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).
  --from/--from-branch only applies when a worktree is created.
  Drop --from or change the workflow's worktree.enabled.

What it means

A workflow pinned to `worktree.enabled: false` runs in the live checkout, so `--from`/`--from-branch` — which only matters when a worktree is created — would have no effect. The CLI rejects the flag rather than silently ignoring it, mirroring the other policy-vs-flag checks.

Source

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

  // 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."
      );
    }
    // --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' +

View on GitHub (pinned to 0773b97458)

Solutions

Drop the `--from`/`--from-branch` flag; it only applies when a worktree is created.
Set `worktree.enabled: true` in the workflow YAML if `--from` should be meaningful.

Example fix

// before
archon workflow start live-sync --from main
// after
archon workflow start live-sync

Defensive patterns

Strategy: validation

Validate before calling

if (wf.worktree?.enabled === false && (args.includes('--from') || args.includes('--from-branch'))) {
  throw new Error(`${wf.name} never creates a worktree; --from is not applicable.`);
}

Prevention

Treat --from/--from-branch as worktree-creation-only flags.
Strip worktree flags from launchers when the target workflow disables worktrees.

When it happens

Trigger: `archon workflow start <workflow-with-worktree-enabled-false> --from <branch>` (or `--from-branch`) — options.fromBranch set while workflow.worktree.enabled === false.

Common situations: Copy-pasting a full worktree flag set (`--from`, `--base`, `--branch`) onto a workflow whose YAML disables worktrees.

Related errors

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