coleam00/Archon · error · Error

Workflow '${workflow.name}' sets worktree.enabled: false (ru

Error message

Workflow '${workflow.name}' sets worktree.enabled: false (runs in live checkout).
  --branch requires an isolated worktree.
  Drop --branch or change the workflow's worktree.enabled.

What it means

A workflow whose YAML pins `worktree.enabled: false` always runs in the live checkout. Passing `--branch` — which names the branch of an isolated worktree — would be silently ignored, so the CLI rejects the mismatch between the workflow's isolation policy and the caller's flag rather than applying one side.

Source

Thrown at packages/cli/src/commands/workflow.ts:1891

  }

  // Per-dispatch --base override, normalized once. Wins over repo config + the
  // codebase default for both the worktree cut-from (the provider request's
  // `baseOverride` below) and the PR target / $BASE_BRANCH (executeWorkflow's
  // `baseOverride` opt). Both halves need their own channel: the `baseBranch`
  // field on either side is the codebase-default FALLBACK and ranks below repo
  // config, so routing the flag through it would silently lose to a repo that
  // sets `worktree.baseBranch`.
  const flagBase = options.baseBranch?.trim() || undefined;

  // Reconcile workflow-level worktree policy with invocation flags.
  // The workflow YAML's `worktree.enabled` pins isolation regardless of caller —
  // a mismatch between policy and flags is a user error we surface loudly
  // rather than silently applying one side and ignoring the other.
  const pinnedEnabled = workflow.worktree?.enabled;
  if (pinnedEnabled === false) {
    if (options.branchName !== undefined) {
      throw new Error(
        `Workflow '${workflow.name}' sets worktree.enabled: false (runs in live checkout).\n` +
          '  --branch requires an isolated worktree.\n' +
          "  Drop --branch or change the workflow's worktree.enabled."
      );
    }
    if (options.fromBranch !== undefined) {
      throw new Error(
        `Workflow '${workflow.name}' sets worktree.enabled: false (runs in live checkout).\n` +
          '  --from/--from-branch only applies when a worktree is created.\n' +
          "  Drop --from or change the workflow's worktree.enabled."
      );
    }
    if (options.baseBranch !== undefined) {
      throw new Error(
        `Workflow '${workflow.name}' sets worktree.enabled: false (runs in live checkout).\n` +
          '  --base only applies when a worktree is created.\n' +
          "  Drop --base or change the workflow's worktree.enabled."
      );

View on GitHub (pinned to 0773b97458)

Solutions

Drop the `--branch` flag when starting this workflow.
Change the workflow YAML to `worktree.enabled: true` if runs should be isolated and branch-controlled.

Example fix

// before
archon workflow start live-sync --branch fix/thing
// after
archon workflow start live-sync

Defensive patterns

Strategy: validation

Validate before calling

// check the workflow's pinned policy before passing lane flags
const wf = JSON.parse(await Bun.file(`.archon/workflows/${name}.yaml`).text()); // or via `archon workflow show`
if (wf.worktree?.enabled === false && args.includes('--branch')) {
  throw new Error(`${name} runs in the live checkout; --branch is not applicable.`);
}

Prevention

Inspect `worktree.enabled` in the workflow YAML before adding isolation flags.
Keep per-workflow launch scripts instead of one shared flag set.

When it happens

Trigger: `archon workflow start <workflow-with-worktree-enabled-false> --branch <name>` — options.branchName set while workflow.worktree.enabled === false.

Common situations: Reusing a shared `--branch` wrapper script across workflows; not realizing the target workflow's YAML disables worktree isolation.

Related errors

AI-assisted analysis of coleam00/Archon@0773b97458 (2026-09-01). Data as JSON: /api/errors/7e3cc751ebb0a236. Report an issue: GitHub.