holo-codex 0.1.0

package/plugins/autonomous-pr-loop/core/delivery-work-item.ts

@@ -0,0 +1,217 @@
+import { AgentLoopError } from "./errors.js";
+import { redactSecrets } from "./redaction.js";
+import type { AgentLoopEvent, AgentLoopRun, AgentLoopStorage } from "./types.js";
+
+export const DELIVERY_WORK_ITEM_BOUND_KIND = "delivery_work_item_bound";
+export const WORKFLOW_STAGE_EVIDENCE_KIND = "workflow_stage_evidence";
+
+export interface DeliveryWorkItem {
+  issue: number;
+  title: string;
+  url: string;
+  branch?: string;
+  source: "cli" | "dashboard" | "state_machine";
+}
+
+export interface BindDeliveryWorkItemInput {
+  issue?: string;
+  title?: string;
+  url?: string;
+  branch?: string;
+  runId?: string;
+  source?: "cli" | "dashboard" | "state_machine";
+}
+
+export interface BindDeliveryWorkItemResult {
+  run: AgentLoopRun;
+  workItem: DeliveryWorkItem;
+  reused: boolean;
+  bound: boolean;
+  event?: AgentLoopEvent;
+}
+
+export function bindDeliveryWorkItem(
+  storage: AgentLoopStorage,
+  input: BindDeliveryWorkItemInput
+): BindDeliveryWorkItemResult {
+  const workItem = normalizeWorkItemInput(input);
+  const run = selectBindableRun(storage, workItem, input.runId);
+  const existing = getDeliveryWorkItem(storage, run.id);
+  if (existing && sameIssue(existing, workItem)) {
+    return { run, workItem: existing, reused: true, bound: false };
+  }
+
+  const event = storage.appendEvent({
+    runId: run.id,
+    kind: DELIVERY_WORK_ITEM_BOUND_KIND,
+    message: `Bound delivery work item #${workItem.issue}: ${redactSecrets(workItem.title)}`,
+    payload: workItem
+  });
+  storage.appendDecision({
+    runId: run.id,
+    kind: DELIVERY_WORK_ITEM_BOUND_KIND,
+    message: `Bound delivery work item #${workItem.issue}.`,
+    details: workItem
+  });
+  appendWorkItemStageEvidence(storage, run.id, workItem);
+  return { run, workItem, reused: false, bound: true, event };
+}
+
+export function getDeliveryWorkItem(storage: AgentLoopStorage, runId: string | undefined): DeliveryWorkItem | undefined {
+  if (!runId) return undefined;
+  const event = latestEventLookup(storage)?.findLatestEvent(runId, DELIVERY_WORK_ITEM_BOUND_KIND)
+    ?? storage
+      .listEvents(100_000)
+      .find((item) => item.runId === runId && item.kind === DELIVERY_WORK_ITEM_BOUND_KIND);
+  return parseDeliveryWorkItem(event?.payload);
+}
+
+export function selectDefaultDeliveryRun(storage: AgentLoopStorage): AgentLoopRun | undefined {
+  return storage
+    .listRuns(200)
+    .find((run) => isLiveRun(run) && getDeliveryWorkItem(storage, run.id) !== undefined);
+}
+
+export function defaultIssueBranch(issue: number, title: string, prefix: string): string {
+  const slug = `${title}`
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48);
+  return `${prefix}issue-${issue}${slug ? `-${slug}` : ""}`;
+}
+
+function selectBindableRun(
+  storage: AgentLoopStorage,
+  workItem: DeliveryWorkItem,
+  runId: string | undefined
+): AgentLoopRun {
+  if (runId) {
+    const run = storage.listRuns(200).find((item) => item.id === runId);
+    if (!run) {
+      throw new AgentLoopError("storage_error", `Run not found: ${runId}`);
+    }
+    assertCanBindRun(storage, run, workItem);
+    return run;
+  }
+
+  const liveRuns = storage.listRuns(200).filter(isLiveRun);
+  const sameIssueRun = liveRuns.find((run) => {
+    const existing = getDeliveryWorkItem(storage, run.id);
+    return existing && sameIssue(existing, workItem);
+  });
+  if (sameIssueRun) return sameIssueRun;
+
+  const unboundLiveRun = liveRuns.find((run) => run.status === "RUNNING" && getDeliveryWorkItem(storage, run.id) === undefined);
+  if (unboundLiveRun) return unboundLiveRun;
+
+  const different = liveRuns.find((run) => {
+    const existing = getDeliveryWorkItem(storage, run.id);
+    return existing !== undefined && !sameIssue(existing, workItem);
+  });
+  if (different) {
+    const existing = getDeliveryWorkItem(storage, different.id);
+    throw new AgentLoopError("policy_violation", "Another delivery work item is already bound to an active run.", {
+      details: { runId: different.id, existingIssue: existing?.issue, requestedIssue: workItem.issue },
+      exitCode: 2
+    });
+  }
+
+  return storage.createRun("RUNNING", {
+    currentState: "SELECT_NEXT_PR"
+  });
+}
+
+function assertCanBindRun(storage: AgentLoopStorage, run: AgentLoopRun, workItem: DeliveryWorkItem): void {
+  if (!isLiveRun(run)) {
+    throw new AgentLoopError("policy_violation", "Delivery work item can only be bound to a running or blocked run.", {
+      details: { runId: run.id, status: run.status },
+      exitCode: 2
+    });
+  }
+  const existing = getDeliveryWorkItem(storage, run.id);
+  if (existing && !sameIssue(existing, workItem)) {
+    throw new AgentLoopError("policy_violation", "The requested run is already bound to a different delivery work item.", {
+      details: { runId: run.id, existingIssue: existing.issue, requestedIssue: workItem.issue },
+      exitCode: 2
+    });
+  }
+}
+
+function normalizeWorkItemInput(input: BindDeliveryWorkItemInput): DeliveryWorkItem {
+  const issue = Number(input.issue);
+  if (!Number.isInteger(issue) || issue < 1) {
+    throw new AgentLoopError("invalid_config", "delivery bind requires --issue with a positive integer.");
+  }
+  const title = typeof input.title === "string" ? input.title.trim() : "";
+  if (!title) {
+    throw new AgentLoopError("invalid_config", "delivery bind requires --title.");
+  }
+  const url = typeof input.url === "string" ? input.url.trim() : "";
+  if (!/^https:\/\/github\.com\/[^/]+\/[^/]+\/issues\/\d+$/i.test(url)) {
+    throw new AgentLoopError("invalid_config", "delivery bind requires --url pointing to a GitHub issue.");
+  }
+  const branch = typeof input.branch === "string" && input.branch.trim().length > 0 ? input.branch.trim() : undefined;
+  return {
+    issue,
+    title: redactSecrets(title),
+    url,
+    ...(branch ? { branch } : {}),
+    source: input.source ?? "cli"
+  };
+}
+
+function appendWorkItemStageEvidence(storage: AgentLoopStorage, runId: string, workItem: DeliveryWorkItem): void {
+  storage.appendEvent({
+    runId,
+    kind: WORKFLOW_STAGE_EVIDENCE_KIND,
+    message: `Selected issue #${workItem.issue}: ${workItem.title}`,
+    payload: {
+      stageId: "work_item",
+      substageId: "issue_selected",
+      evidenceRefIds: [workItem.url],
+      artifactIds: [],
+      actor: "codex",
+      status: "done",
+      source: "delivery"
+    }
+  });
+}
+
+function sameIssue(left: DeliveryWorkItem, right: DeliveryWorkItem): boolean {
+  return left.issue === right.issue;
+}
+
+function isLiveRun(run: AgentLoopRun): boolean {
+  return run.status === "RUNNING" || run.status === "BLOCKED";
+}
+
+function latestEventLookup(storage: AgentLoopStorage): { findLatestEvent(runId: string, kind: string): AgentLoopEvent | undefined } | undefined {
+  const candidate = storage as AgentLoopStorage & { findLatestEvent?: unknown };
+  return typeof candidate.findLatestEvent === "function"
+    ? { findLatestEvent: candidate.findLatestEvent.bind(storage) as (runId: string, kind: string) => AgentLoopEvent | undefined }
+    : undefined;
+}
+
+function parseDeliveryWorkItem(payload: unknown): DeliveryWorkItem | undefined {
+  if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+    return undefined;
+  }
+  const record = payload as Record<string, unknown>;
+  if (
+    typeof record.issue !== "number" ||
+    !Number.isInteger(record.issue) ||
+    typeof record.title !== "string" ||
+    typeof record.url !== "string"
+  ) {
+    return undefined;
+  }
+  const source = record.source === "dashboard" || record.source === "state_machine" ? record.source : "cli";
+  return {
+    issue: record.issue,
+    title: record.title,
+    url: record.url,
+    ...(typeof record.branch === "string" ? { branch: record.branch } : {}),
+    source
+  };
+}

package/plugins/autonomous-pr-loop/core/doctor.ts

@@ -0,0 +1,335 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { redactRemote, runCommand } from "./command.js";
+import { loadConfig, statePath } from "./config.js";
+import { AgentLoopError } from "./errors.js";
+import { inspectHookCapture } from "./hook-capture.js";
+import { agentLoopRouterHookCommand, collectHookCommands, isLegacyAgentLoopHookCommand } from "./hook-installation.js";
+import { CODEX_HOOK_EVENTS, hookScriptName } from "./hook-events.js";
+import { hookRegistryPath, inspectHookRegistryLock, listHookBindings } from "./hook-router.js";
+import { defaultPackageRoot, hookDistRoot, hookSourceRoot } from "./plugin-paths.js";
+import { SqliteAgentLoopStorage } from "./storage.js";
+import type { AgentTimelineIntegrityReport, DoctorCheck, DoctorReport } from "./types.js";
+
+/** Run PR A environment diagnostics for the current repository. */
+export function runDoctor(repoRoot: string): DoctorReport {
+  const checks: DoctorCheck[] = [];
+  const gitRoot = runCommand("git", ["rev-parse", "--show-toplevel"], repoRoot);
+  pushCheck(checks, "git repo", gitRoot.ok, "Current directory is inside a git repository.");
+
+  const remote = runCommand("git", ["remote", "get-url", "origin"], repoRoot);
+  const githubRemote = remote.ok && remote.stdout.includes("github.com");
+  pushCheck(checks, "github remote", githubRemote, "origin remote points to GitHub.", {
+    remote: remote.ok ? redactRemote(remote.stdout) : redactRemote(remote.stderr)
+  });
+
+  const ghAuth = runCommand("gh", ["auth", "status", "-h", "github.com"], repoRoot);
+  const ghAuthed = ghAuth.ok;
+  pushCheck(checks, "gh auth", ghAuthed, "GitHub CLI is authenticated.");
+  if (ghAuth.ok) {
+    const hasRepo = ghAuth.combined.includes("'repo'") || ghAuth.combined.includes(" repo");
+    const hasWorkflow =
+      ghAuth.combined.includes("'workflow'") || ghAuth.combined.includes(" workflow");
+    checks.push({
+      name: "gh token scopes",
+      status: hasRepo ? (hasWorkflow ? "pass" : "warn") : "fail",
+      message: hasRepo
+        ? hasWorkflow
+          ? "gh token has repo and workflow scopes."
+          : "gh token has repo scope; workflow scope is recommended."
+        : "gh token must include repo scope."
+    });
+  }
+
+  const codex = runCommand("codex", ["--version"], repoRoot);
+  pushCheck(checks, "codex cli", codex.ok, "codex CLI is available.", {
+    version: codex.ok ? codex.stdout : codex.stderr
+  });
+
+  const packageRoot = defaultPackageRoot();
+  checks.push(checkHooksBuilt(packageRoot, repoRoot));
+  checks.push(checkHooksInstalled(repoRoot, packageRoot));
+
+  const nodeMajorMinor = process.versions.node.split(".").slice(0, 2).map(Number);
+  const nodeOk =
+    (nodeMajorMinor[0] ?? 0) > 22 ||
+    ((nodeMajorMinor[0] ?? 0) === 22 && (nodeMajorMinor[1] ?? 0) >= 5);
+  pushCheck(checks, "node version", nodeOk, "Node version supports node:sqlite.", {
+    version: process.version
+  });
+
+  let missingConfig = false;
+  try {
+    const { config } = loadConfig(repoRoot);
+    checks.push({
+      name: "config schema",
+      status: "pass",
+      message: ".agent-loop/config.json is valid."
+    });
+    checks.push({
+      name: "plansDir",
+      status: existsSync(join(repoRoot, config.plansDir)) ? "pass" : "fail",
+      message: `plansDir exists: ${config.plansDir}`
+    });
+
+    const storage = new SqliteAgentLoopStorage(statePath(repoRoot));
+    let timelineIntegrity: AgentTimelineIntegrityReport;
+    try {
+      storage.writeRepoConfig(config);
+      try {
+        timelineIntegrity = storage.checkTimelineIntegrity();
+      } catch (error) {
+        timelineIntegrity = failedTimelineIntegrity(error);
+      }
+    } finally {
+      storage.close();
+    }
+    checks.push({
+      name: "storage",
+      status: "pass",
+      message: "Storage can be opened and written."
+    });
+    checks.push({
+      name: "timeline integrity",
+      status: timelineIntegrity.ok ? "pass" : "fail",
+      message: timelineIntegrity.ok
+        ? "Timeline index and triggers are installed."
+        : "Timeline index or triggers are missing.",
+      details: timelineIntegrity
+    });
+
+    const gitnexus = runCommand("npx", ["gitnexus", "--version"], repoRoot);
+    checks.push({
+      name: "gitnexus",
+      status: gitnexus.ok ? "pass" : config.gitnexusRequired ? "fail" : "warn",
+      message: gitnexus.ok
+        ? "GitNexus is available."
+        : "GitNexus is not available from npx gitnexus --version."
+    });
+  } catch (error) {
+    if (error instanceof AgentLoopError && error.code === "needs_repo_init") {
+      missingConfig = true;
+      checks.push({
+        name: "config schema",
+        status: "fail",
+        message: "Missing .agent-loop/config.json.",
+        details: { gate: "needs_repo_init" }
+      });
+    } else {
+      checks.push({
+        name: "config schema",
+        status: "fail",
+        message: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+
+  const status = checks.some((check) => check.status === "fail")
+    ? "fail"
+    : checks.some((check) => check.status === "warn")
+      ? "warn"
+      : "pass";
+  return {
+    status,
+    checks,
+    ...(missingConfig ? { gate: "needs_repo_init" } : {})
+  };
+}
+
+function checkHooksBuilt(packageRoot: string, targetRepoRoot: string): DoctorCheck {
+  const sourceDir = hookSourceRoot(packageRoot);
+  const distDir = hookDistRoot(packageRoot);
+  const installCommand = installHooksCommand(targetRepoRoot);
+  const missing = CODEX_HOOK_EVENTS
+    .map((event) => hookScriptName(event))
+    .filter((script) => !existsSync(join(distDir, script)));
+  if (missing.length > 0) {
+    return {
+      name: "codex hooks build",
+      status: "warn",
+      message: `Compiled hook runners are missing. Run \`pnpm build:hooks\` from ${packageRoot}, then \`${installCommand}\`.`,
+      details: { packageRoot, distDir, missing, installCommand }
+    };
+  }
+  if (!existsSync(join(packageRoot, "pnpm-lock.yaml"))) {
+    return {
+      name: "codex hooks build",
+      status: "pass",
+      message: "Packaged hook runners are available.",
+      details: { packageRoot, distDir }
+    };
+  }
+  const stale = CODEX_HOOK_EVENTS
+    .map((event) => ({
+      source: join(sourceDir, hookScriptName(event).replace(/\.js$/, ".ts")),
+      dist: join(distDir, hookScriptName(event))
+    }))
+    .filter((entry) => existsSync(entry.source) && statSync(entry.dist).mtimeMs < statSync(entry.source).mtimeMs);
+  return {
+    name: "codex hooks build",
+    status: stale.length === 0 ? "pass" : "warn",
+    message: stale.length === 0
+      ? "Compiled hook runners are available."
+      : `Compiled hook runners are older than sources. Run \`pnpm build:hooks\` from ${packageRoot}, then \`${installCommand}\`.`,
+    ...(stale.length > 0 ? { details: { packageRoot, stale, installCommand } } : {})
+  };
+}
+
+function checkHooksInstalled(repoRoot: string, pluginRoot: string): DoctorCheck {
+  const codexHome = process.env.CODEX_HOME ?? join(homedir(), ".codex");
+  const hooksPath = join(codexHome, "hooks.json");
+  const installCommand = installHooksCommand(repoRoot);
+  if (!existsSync(hooksPath)) {
+    return {
+      name: "codex hooks",
+      status: "warn",
+      message: `Codex hooks are not installed. Run \`${installCommand}\`.`,
+      details: { hooksPath, targetRepoRoot: repoRoot, pluginRoot, installCommand }
+    };
+  }
+  const text = readFileSync(hooksPath, "utf8");
+  let parsedHooks: unknown;
+  try {
+    parsedHooks = JSON.parse(text) as unknown;
+  } catch (error) {
+    return {
+      name: "codex hooks",
+      status: "warn",
+      message: `Codex hooks config is not valid JSON. Fix ${hooksPath}, then run \`${installCommand}\`.`,
+      details: { hooksPath, error: error instanceof Error ? error.message : String(error), installCommand }
+    };
+  }
+  const commands = collectHookCommands(parsedHooks);
+  const missing = CODEX_HOOK_EVENTS.filter((event) => !commands.includes(agentLoopRouterHookCommand(event, pluginRoot)));
+  const legacyCommands = commands.filter(isLegacyAgentLoopHookCommand);
+  const expectedDist = hookDistRoot(pluginRoot);
+  const routerCommands = commands.filter((command) => command.includes("autonomous-pr-loop/hooks/dist/"));
+  const unexpectedRouterCommands = routerCommands.filter((command) => !command.includes(expectedDist));
+  let bindings: ReturnType<typeof listHookBindings>;
+  let registryError: string | undefined;
+  try {
+    bindings = listHookBindings(codexHome);
+  } catch (error) {
+    bindings = [];
+    registryError = error instanceof Error ? error.message : String(error);
+  }
+  const activeBindings = bindings.filter((binding) => binding.status === "active");
+  const currentRepoBindings = activeBindings.filter((binding) => binding.repoRoot === repoRoot);
+  const lock = inspectHookRegistryLock(codexHome);
+  const capture = inspectHookCapture(repoRoot, codexHome);
+  const installed = missing.length === 0;
+  const routerDistDrift = unexpectedRouterCommands.length > 0;
+  const captureWarn = capture.status === "ambiguous" || capture.status === "unavailable";
+  const status = !installed ? "warn" : routerDistDrift || registryError || lock.stale || legacyCommands.length > 0 || currentRepoBindings.length === 0 || captureWarn ? "warn" : "pass";
+  const message = hookInstallMessage({
+    installed,
+    routerDistDrift,
+    registryError,
+    lockStale: lock.stale,
+    lockPath: lock.path,
+    legacyCommands,
+    currentRepoBindings,
+    installCommand,
+    codexHome
+  });
+  return {
+    name: "codex hooks",
+    status,
+    message,
+    details: {
+      hooksPath,
+      registryPath: hookRegistryPath(codexHome),
+      targetRepoRoot: repoRoot,
+      pluginRoot,
+      expectedDist,
+      missing,
+      legacyCommands,
+      routerCommandsPointToExpectedDist: routerCommands.length > 0 && unexpectedRouterCommands.length === 0,
+      unexpectedRouterCommands,
+      activeBindings: activeBindings.length,
+      currentRepoBindings: currentRepoBindings.length,
+      lock,
+      hookCapture: capture,
+      ...(registryError ? { registryError } : {}),
+      installCommand
+    }
+  };
+}
+
+function hookInstallMessage(input: {
+  installed: boolean;
+  routerDistDrift: boolean;
+  registryError: string | undefined;
+  lockStale: boolean;
+  lockPath: string;
+  legacyCommands: string[];
+  currentRepoBindings: unknown[];
+  installCommand: string;
+  codexHome: string;
+}): string {
+  if (!input.installed && input.routerDistDrift) {
+    return `Codex hook router is not installed at the expected hook dist; existing router commands point outside the expected hook dist. Run \`${input.installCommand}\` to refresh router hooks and bind this repo.`;
+  }
+  if (!input.installed) {
+    return `Codex hook router is not installed. Run \`${input.installCommand}\` to install router hooks and bind this repo.`;
+  }
+  if (input.routerDistDrift) {
+    return `Codex hook router includes commands outside the expected hook dist. Run \`${input.installCommand}\` to refresh router hooks.`;
+  }
+  if (input.registryError) {
+    return `Codex hook binding registry is not valid. Fix ${hookRegistryPath(input.codexHome)}, then run \`${input.installCommand}\`.`;
+  }
+  if (input.lockStale) {
+    return `Codex hook binding registry lock appears stale. Remove ${input.lockPath} or rerun after the stale writer exits.`;
+  }
+  if (input.legacyCommands.length > 0) {
+    return `Codex hook router is installed, but legacy per-repo agent-loop hooks remain. Run \`${input.installCommand}\` to migrate them.`;
+  }
+  if (input.currentRepoBindings.length === 0) {
+    return `Codex hook router is installed, but this repo is not bound. Run \`${input.installCommand}\`.`;
+  }
+  return "HOLO-Codex hook router is installed and this repo has an active binding.";
+}
+
+function installHooksCommand(repoRoot: string): string {
+  return `agent-loop install-hooks --repo ${shellQuote(repoRoot)}`;
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function pushCheck(
+  checks: DoctorCheck[],
+  name: string,
+  pass: boolean,
+  message: string,
+  details?: unknown
+): void {
+  checks.push({
+    name,
+    status: pass ? "pass" : "fail",
+    message: pass ? message : `${message} Check failed.`,
+    ...(details ? { details } : {})
+  });
+}
+
+function failedTimelineIntegrity(error: unknown): AgentTimelineIntegrityReport {
+  return {
+    ok: false,
+    missingTable: false,
+    missingTriggers: [],
+    missingSourceRows: [],
+    sourceCounts: {
+      event: 0,
+      worker_event: 0,
+      worker: 0,
+      state: 0,
+      gate: 0,
+      artifact: 0,
+      decision: 0
+    },
+    repair: `Timeline integrity check failed: ${error instanceof Error ? error.message : String(error)}`
+  };
+}

package/plugins/autonomous-pr-loop/core/errors.ts

@@ -0,0 +1,82 @@
+import type { AgentLoopGateKind } from "./types.js";
+
+export type AgentLoopErrorCode =
+  | AgentLoopGateKind
+  | "invalid_config"
+  | "not_git_repo"
+  | "config_exists"
+  | "storage_schema_mismatch"
+  | "version_conflict"
+  | "storage_error"
+  | "artifact_integrity_error"
+  | "command_rejected"
+  | "command_timeout"
+  | "unknown_command";
+
+/** Structured error used by CLI and core APIs to preserve stable machine-readable codes. */
+export class AgentLoopError extends Error {
+  readonly code: AgentLoopErrorCode;
+  readonly details?: unknown;
+  readonly exitCode: 0 | 1 | 2;
+
+  constructor(
+    code: AgentLoopErrorCode,
+    message: string,
+    options: { details?: unknown; exitCode?: 0 | 1 | 2 } = {}
+  ) {
+    super(message);
+    this.name = "AgentLoopError";
+    this.code = code;
+    this.details = options.details;
+    this.exitCode = options.exitCode ?? (isGateCode(code) ? 2 : 1);
+  }
+}
+
+/** Return true when an error code represents a gate rather than an unexpected failure. */
+export function isGateCode(code: AgentLoopErrorCode): code is AgentLoopGateKind {
+  return (
+    code === "needs_repo_init" ||
+    code === "unsupported_remote" ||
+    code === "needs_secret_or_login" ||
+    code === "policy_violation" ||
+    code === "ambiguous_next_pr" ||
+    code === "dirty_unowned_worktree" ||
+    code === "required_tool_unavailable" ||
+    code === "ci_required_checks_missing" ||
+    code === "ci_pending_timeout" ||
+    code === "merge_requires_confirmation" ||
+    code === "github_transient_failure" ||
+    code === "gitnexus_check_failed" ||
+    code === "github_resource_not_found" ||
+    code === "worker_failed" ||
+    code === "worker_output_invalid" ||
+    code === "review_out_of_scope" ||
+    code === "worker_timeout" ||
+    code === "worker_already_running" ||
+    code === "generic_goal_needs_confirmation" ||
+    code === "generic_human_gate" ||
+    code === "generic_scope_change_requested"
+  );
+}
+
+/** Convert unknown thrown values into stable JSON-safe CLI error payloads. */
+export function toErrorPayload(error: unknown): {
+  code: string;
+  message: string;
+  details?: unknown;
+} {
+  if (error instanceof AgentLoopError) {
+    const payload: { code: string; message: string; details?: unknown } = {
+      code: error.code,
+      message: error.message
+    };
+    if (error.details !== undefined) {
+      payload.details = error.details;
+    }
+    return payload;
+  }
+  if (error instanceof Error) {
+    return { code: "error", message: error.message };
+  }
+  return { code: "error", message: String(error) };
+}