coleam00/Archon · error · Error

--adopt/--supersedes requires a run id.

Error message

--adopt/--supersedes requires a run id.

What it means

Defensive guard on the --adopt/--supersedes continuation flags: continuation requires exactly one run id, and if neither option is set after the earlier resolution steps, the CLI throws this error. In practice the outer `if` makes it nearly unreachable — it exists so the type system can narrow options.adoptRunId/options.supersedesRunId to defined values.

Source

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

  // Set when the adopt lane executes inside a checkout whose `.archon` may differ from
  // this process's cwd — the trigger for recaptureForLane once the path is final.
  let adoptLaneRunsIsolatedCheckout = false;
  if (options.adoptRunId !== undefined || options.supersedesRunId !== undefined) {
    if (!codebase) {
      throw new Error(
        'Cannot resolve the project for --adopt/--supersedes. Run from the project checkout and try again.'
      );
    }
    // Narrowed by construction: the flag-conflict gate above guarantees exactly
    // one of the two ids is present.
    if (options.adoptRunId !== undefined) {
      continuationMode = 'adopt';
      adoptedFromRunId = await resolveRunIdArg(options.adoptRunId, cwd, false, codebase.id);
    } else if (options.supersedesRunId !== undefined) {
      continuationMode = 'supersede';
      adoptedFromRunId = await resolveRunIdArg(options.supersedesRunId, cwd, false, codebase.id);
    } else {
      throw new Error('--adopt/--supersedes requires a run id.');
    }

    if (continuationMode === 'adopt') {
      const { adoptedRun, lane } = await resolveWorkflowAdoption({
        adoptedRunId: adoptedFromRunId,
        codebaseId: codebase.id,
        codebasePath: codebase.default_cwd,
        codebaseKind: codebase.kind,
        containerRequested: options.container === true,
      });
      if (lane.kind === 'reuse-worktree') {
        workingCwd = lane.workingPath;
        isolationEnvId = lane.envId;
        adoptLaneRunsIsolatedCheckout = true;
        // The reuse lane IS the isolation: run in the inherited worktree as-is.
        // Leaving wantsIsolation set would fall through to worktree creation below
        // and silently cut a fresh worktree from base over the inherited one.
        wantsIsolation = false;

View on GitHub (pinned to 0773b97458)

Solutions

1. Pass a run id: `archon workflow run <flow> --adopt <runId>` or `--supersedes <runId>`.
2. Check the wrapper/script constructing the command for a dropped or empty argument.
3. Use `archon workflow get <id>` to confirm the run id you intend to continue exists.

Example fix

// before
archon workflow run my-flow --adopt   # flag present but no id
// after
archon workflow run my-flow --adopt 7f3c9e2a-...

const adoptId = flags['adopt'] ?? flags['supersedes'];
if (!adoptId) {
  throw new Error('--adopt/--supersedes requires a run id, e.g. --adopt <runId>.');
}

try {
  await spawn('archon', ['workflow', 'run', flow, '--adopt', runId]);
} catch (e) {
  if (String(e).includes('requires a run id')) {
    console.error('Wrapper dropped the run id argument; check your script argv construction.');
  } else throw e;
}

When it happens

Trigger: Programmatic invocation where the adopt/supersedes options object is constructed without either run id (both undefined) but some related flag skips the outer gate; effectively unreachable through normal CLI parsing of --adopt/--supersedes.

Common situations: Scripts or wrappers that build the options object dynamically and forget to pass the run id value, or pass an empty value that parseArgs dropped.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• --resume and --config are mutually exclusive. A resumed run
• Failed to download web UI: ${tarballRes.status} ${tarballRes
• Failed to read version: package.json is malformed
• Failed to start detached workflow child (executable: ${cmd[0
• Cannot create worktree: database lookup failed. Error: ${res

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