coleam00/Archon · error · Error

Workflow '${workflow.name}' sets worktree.enabled: true (req

Error message

Workflow '${workflow.name}' sets worktree.enabled: true (requires a worktree).
  --no-worktree conflicts with the workflow policy.
  Drop --no-worktree or change the workflow's worktree.enabled.

What it means

A workflow whose YAML pins `worktree.enabled: true` requires an isolated worktree for every run. Passing `--no-worktree` directly contradicts that policy, so the preflight rejects the invocation rather than letting the flag override the workflow's declared isolation requirement.

Source

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

    }
    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."
      );
    }
    // --no-worktree is redundant but not contradictory — silently accept.
  } else if (pinnedEnabled === true) {
    if (options.noWorktree) {
      throw new Error(
        `Workflow '${workflow.name}' sets worktree.enabled: true (requires a worktree).\n` +
          '  --no-worktree conflicts with the workflow policy.\n' +
          "  Drop --no-worktree or change the workflow's worktree.enabled."
      );
    }
  }

  // Default to worktree isolation unless --no-worktree or --resume. Workflow YAML
  // `worktree.enabled` pins the decision — mismatches with CLI flags are rejected
  // above, so by this point policy (if set) and flags agree. `--resume` reuses an
  // existing worktree and takes precedence over the pinned policy. Computed here
  // (not at the worktree block below) because --detach also needs it to decide
  // whether to pin a generated branch on the child.
  const flagWantsIsolation = !options.resume && !options.noWorktree;
  // Reassigned by adoption resolution (#2747): adopting a branch whose worktree
  // is gone forces isolation ON to cut a fresh worktree FROM that branch.
  let wantsIsolation =
    !options.resume && pinnedEnabled !== undefined ? pinnedEnabled : flagWantsIsolation;

View on GitHub (pinned to 0773b97458)

Solutions

Drop `--no-worktree` and let the run use its isolated worktree.
Change the workflow YAML to `worktree.enabled: false` only if the workflow is genuinely safe to run in the live checkout.

Example fix

// before
archon workflow start pr-review --no-worktree
// after
archon workflow start pr-review

Defensive patterns

Strategy: validation

Validate before calling

if (wf.worktree?.enabled === true && args.includes('--no-worktree')) {
  throw new Error(`${wf.name} requires a worktree; --no-worktree conflicts with its policy.`);
}

Prevention

Don't force --no-worktree on workflows that declare isolation as a requirement.
If live-checkout execution is needed, change the workflow YAML deliberately, not the invocation.

When it happens

Trigger: `archon workflow start <workflow-with-worktree-enabled-true> --no-worktree` — options.noWorktree set while workflow.worktree.enabled === true.

Common situations: Trying to force a worktree-requiring workflow (e.g. one operating on PR branches) to run in the live checkout for speed; sharing one launch command across workflows with different policies.

Related errors

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