{"record":{"id":"4fec25db90fe8846","repo":"ruvnet/ruflo","slug":"unknown-worktree-run-runid","errorCode":null,"errorMessage":"unknown worktree run: ${runId}","messagePattern":"unknown worktree run: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/codex/src/worktrees/coordinator.ts","lineNumber":101,"sourceCode":"        runId,\n        repoRoot: this.repoRoot,\n        createdAt: Date.now(),\n        assignments,\n      };\n      this.writeRecord(registryPath, record);\n      return record;\n    } catch (error) {\n      for (const assignment of assignments.reverse()) {\n        try { git(this.repoRoot, ['worktree', 'remove', assignment.path]); } catch { /* retain work for recovery */ }\n      }\n      throw error;\n    }\n  }\n\n  status(runId: string): WorktreeRunRecord {\n    assertId(runId, 'run id');\n    const file = this.registryPath(runId);\n    if (!existsSync(file)) throw new Error(`unknown worktree run: ${runId}`);\n    const record = JSON.parse(readFileSync(file, 'utf8')) as WorktreeRunRecord;\n    if (record.version !== 1 || record.runId !== runId || resolve(record.repoRoot) !== this.repoRoot) {\n      throw new Error('invalid worktree registry record');\n    }\n    const expectedPrefix = resolve(join(this.worktreeBase, runId));\n    for (const assignment of record.assignments) {\n      const actual = resolve(assignment.path);\n      if (actual !== expectedPrefix && !actual.startsWith(`${expectedPrefix}/`)) {\n        throw new Error(`registry path escapes owned worktree root: ${actual}`);\n      }\n    }\n    return record;\n  }\n\n  integrate(runId: string, agentIds?: string[]): { merged: string[] } {\n    const record = this.status(runId);\n    const wanted = agentIds ? new Set(agentIds) : null;\n    const merged: string[] = [];","sourceCodeStart":83,"sourceCodeEnd":119,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/codex/src/worktrees/coordinator.ts#L83-L119","documentation":"status(runId) — also used internally by integrate() — loads a per-run registry JSON at <repoRoot>/.claude-flow/swarm/worktrees/<runId>.json. If that file does not exist, the run was never prepared in this repository (or the registry was deleted), so the run id is unknown and every run-scoped operation is refused.","triggerScenarios":"Calling status(runId) or integrate(runId) before prepare() completed; using a runId that was never prepared; after .claude/swarm/worktrees was removed by a fresh clone or `git clean`.","commonSituations":"Restarting an orchestrator and reusing a run id recorded on a previous machine or clone; constructing the coordinator with a different repoRoot than the process that created the run; typos or case differences in the run id.","solutions":["Call prepare(runId, agents) first — it is idempotent and returns the existing record if the registry file already exists","Persist the run id immediately after prepare() and reuse that exact string for status()/integrate()","Verify <repoRoot>/.claude-flow/swarm/worktrees/<runId>.json exists; if the registry is gone, start a fresh run id instead of resurrecting the old one"],"exampleFix":"// before\ncoordinator.integrate('run-42'); // throws: unknown worktree run\n\n// after\nconst record = coordinator.prepare('run-42', agents); // creates or reloads registry\ncoordinator.integrate('run-42');","handlingStrategy":"validation","validationCode":"import { existsSync } from 'node:fs';\nimport { join, resolve } from 'node:path';\nfunction isPreparedRun(coord: { repoRoot: string }, runId: string): boolean {\n  return existsSync(join(resolve(coord.repoRoot), '.claude-flow', 'swarm', 'worktrees', `${runId}.json`));\n}\nif (!isPreparedRun(coordinator, runId)) coordinator.prepare(runId, agents);\nelse coordinator.status(runId);","typeGuard":null,"tryCatchPattern":"try {\n  record = coordinator.status(runId);\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('unknown worktree run')) {\n    record = coordinator.prepare(runId, agents); // create-or-reuse is idempotent\n  } else throw e;\n}","preventionTips":["Persist the run id returned/used at prepare() time and reuse that exact string","Treat the registry directory (.claude-flow/swarm/worktrees) as required state — do not git-clean it mid-run"],"tags":["worktrees","registry","not-found","git"],"backgroundTag":"entity-not-found","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-08-22T14:17:55.899Z"}