coleam00/Archon · error · Error

Cannot resolve run id prefix '${runId}' without a project di

Error message

Cannot resolve run id prefix '${runId}' without a project directory.

What it means

Run-id prefix resolution needs a project scope to disambiguate short ids. When the caller passed neither a cwd nor a codebaseId, and requirePrefixMatch is set, a non-full run id cannot be resolved and this error is thrown; a full UUID-shaped id is accepted as-is.

Source

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

 *
 * Full UUIDs skip resolution entirely — exact lookup is global, so full ids
 * keep working from any directory. A caller that already resolved a project can
 * provide its id; otherwise project lookup preserves an exact checkout
 * registration, then falls back to a linked worktree's canonical checkout. By
 * default, an omitted or unregistered cwd and an unmatched prefix pass through
 * unchanged so the downstream exact lookup keeps its existing error surface.
 * Callers without a downstream lookup can require a match instead.
 */
async function resolveRunIdArg(
  runId: string,
  cwd?: string,
  requirePrefixMatch = false,
  codebaseId?: string
): Promise<string> {
  if (FULL_RUN_ID_RE.test(runId)) return runId;
  if (cwd === undefined && codebaseId === undefined) {
    if (requirePrefixMatch) {
      throw new Error(`Cannot resolve run id prefix '${runId}' without a project directory.`);
    }
    return runId;
  }
  const resolvedCodebaseId =
    codebaseId ?? (cwd === undefined ? undefined : (await findCodebaseForCheckoutPath(cwd))?.id);
  if (!resolvedCodebaseId) {
    if (requirePrefixMatch) {
      throw new Error(`Cannot resolve run id prefix '${runId}' outside a registered project.`);
    }
    return runId;
  }
  const matches = await workflowDb.findWorkflowRunsByIdPrefix(runId, resolvedCodebaseId);
  if (matches.length > 1) {
    const candidates = matches.map(match => `  ${match.id}`).join('\n');
    throw new Error(
      `Run id '${runId}' matches more than one run in this project:\n${candidates}\nUse more characters or the full id.`
    );
  }

View on GitHub (pinned to 0773b97458)

Solutions

cd into the registered project checkout before running the command.
Use the full run id (matching FULL_RUN_ID_RE) so no project scope is needed.
Register the current directory with `archon project register` so cwd resolves to a codebase.

Example fix

// before
archon workflow get ab12   # run from ~/
// after
cd ~/projects/my-app && archon workflow get ab12

Defensive patterns

Strategy: validation

Validate before calling

const isFullId = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id); if (!isFullId && !process.cwd().startsWith(registeredRoot)) throw new Error('cd into the project or pass the full run id');

Type guard

function isFullRunId(s: string): boolean { return /^[0-9a-f-]{36}$/i.test(s); }

Try / catch

try { await getRun(prefix); } catch (e) { if (String(e.message).includes('without a project directory')) await getRun(await expandToFullId(prefix)); }

Prevention

Always run Archon commands from the registered project checkout.
Prefer full run ids in scripts and CI; reserve prefixes for interactive use.
Resolve the codebase explicitly (codebaseId) when invoking helpers programmatically.

When it happens

Trigger: Calling a command (e.g. `workflow get <prefix>`, resume/approve) with a short run-id prefix while running outside any project directory and without an explicit codebase context.

Common situations: Running the CLI from $HOME or a non-registered checkout; CI jobs that lost the working directory; piping ids from another machine's workspace.

Related errors

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