@awak-app/simy-cli 0.1.0 → 0.1.2

package/src/runner.js

@@ -1,5 +1,5 @@
 import { execFile, spawn } from "node:child_process";
-import { EventEmitter } from "node:events";
+import { EventEmitter, once } from "node:events";
 import { access } from "node:fs/promises";
 import path from "node:path";
 import { promisify } from "node:util";
@@ -18,32 +18,52 @@ import {
   redactExecutionLogs,
   redactExecutionText,
 } from "./orchestrator/execution-io.js";
+import { summarizeCodingLoopEvent } from "./orchestrator/presentation.js";
+import { createProviderStreamDecoder } from "./provider-stream.js";
+import { resolveBackendExecutable } from "./backend-executable.js";
+import {
+  attachmentDescriptorForLedger,
+  cleanupRunAttachments,
+  markAttachmentsCleaned,
+  markAttachmentsCleanupFailed,
+  markAttachmentsDelivered,
+} from "./local-attachments.js";
+import { LocalRunRegistry } from "./run-registry.js";
+import { webApiHeaders, webApiUrl } from "./web-api.js";
+import { normalizeGitHubRemote } from "./workspace-context.js";
 
 const execFileAsync = promisify(execFile);
+const MAX_LOCAL_LOG_LINES = 1_000;
 const TERMINAL_STATES = new Set([
   "merge_ready",
   "pr_ready_for_review",
   "failed",
   "blocked",
   "waiting_human",
+  "stopped",
 ]);
+const RESUMABLE_STATES = new Set([
+  "waiting_human",
+  "pr_ready_for_review",
+  "blocked",
+  "failed",
+  "stopped",
+]);
+const INTERRUPTED_STATES = new Set([
+  "queued",
+  "risk_classifying",
+  "chartering",
+  "dispatching",
+  "coding",
+  "collecting_evidence",
+  "auditing",
+  "independent_auditing",
+  "checking_pr",
+  "re_instructing",
+]);
+const RESTORABLE_STATES = new Set([...RESUMABLE_STATES, ...INTERRUPTED_STATES]);
 
-export class LocalRunRegistry {
-  #runs = new Map();
-
-  create(run) {
-    if (this.#runs.has(run.id)) throw new Error(`Run ${run.id} already exists.`);
-    this.#runs.set(run.id, run);
-  }
-
-  get(runId) {
-    return this.#runs.get(runId) ?? null;
-  }
-
-  has(runId) {
-    return this.#runs.has(runId);
-  }
-}
+export { LocalRunRegistry };
 
 export function createRun({ runId, request, session, apiOrigin }) {
   const emitter = new EventEmitter();
@@ -57,6 +77,12 @@ export function createRun({ runId, request, session, apiOrigin }) {
     startedAt: null,
     completedAt: null,
     child: null,
+    operation: null,
+    controlState: "queued",
+    stopRequested: false,
+    logs: [],
+    pendingGuidance: [],
+    resumeCount: 0,
     emitter,
     pendingLedgerUpdate: null,
     ledgerUpdateRunning: false,
@@ -71,13 +97,312 @@ export function createRun({ runId, request, session, apiOrigin }) {
   };
 }
 
+export function restoreRun({ snapshot, session, apiOrigin, localPath = null }) {
+  if (!snapshot || typeof snapshot !== "object" || !snapshot.charter) {
+    throw new Error("Cannot restore an invalid coding loop snapshot.");
+  }
+  const charter = snapshot.charter;
+  const run = createRun({
+    runId: String(snapshot.id || ""),
+    session,
+    apiOrigin,
+    request: {
+      backend: charter.backend === "claude" ? "claude" : "codex",
+      audit_backend:
+        charter.audit_backend === "claude" || charter.audit_backend === "codex"
+          ? charter.audit_backend
+          : null,
+      requirement: String(charter.requirement || ""),
+      repository: String(charter.repository || ""),
+      local_path: localPath,
+      base_branch: String(charter.base_branch || "dev"),
+      max_attempts: charter.max_attempts,
+      ui_evidence_root: String(charter.ui_evidence_root || ""),
+      acceptance_criteria: Array.isArray(charter.acceptance_criteria)
+        ? charter.acceptance_criteria
+        : [],
+      expected_tests: Array.isArray(charter.expected_tests) ? charter.expected_tests : [],
+      expected_evidence: Array.isArray(charter.expected_evidence)
+        ? charter.expected_evidence
+        : [],
+      required_checks: Array.isArray(charter.required_checks) ? charter.required_checks : [],
+      require_human_approval: charter.require_human_approval !== false,
+      must_not: Array.isArray(charter.must_not) ? charter.must_not : [],
+      proposal_id: typeof charter.proposal_id === "string" ? charter.proposal_id : null,
+      attachments: [],
+    },
+  });
+  const restoredSnapshot = structuredClone(snapshot);
+  const lifecycleState = restoredSnapshot.metadata?.pr_lifecycle_state;
+  const persistedState =
+    typeof lifecycleState === "string" && RESTORABLE_STATES.has(lifecycleState)
+      ? lifecycleState
+      : restoredSnapshot.state;
+  if (!RESTORABLE_STATES.has(persistedState)) {
+    throw new Error(`Coding loop ${run.id} is not in a restorable state.`);
+  }
+  const restoredFromState = INTERRUPTED_STATES.has(persistedState) ? persistedState : null;
+  const restoredState = restoredFromState ? "waiting_human" : persistedState;
+  if (restoredFromState) {
+    restoredSnapshot.events = Array.isArray(restoredSnapshot.events)
+      ? restoredSnapshot.events
+      : [];
+    restoredSnapshot.events.push({
+      state: "waiting_human",
+      message: "Local execution was interrupted and is ready to continue.",
+      detail: {
+        code: "local_execution_interrupted",
+        interrupted_state: restoredFromState,
+      },
+      occurred_at: new Date().toISOString(),
+    });
+  }
+
+  run.snapshot = restoredSnapshot;
+  run.snapshot.state = restoredState;
+  run.status = restoredState;
+  run.lastOutput = restoredFromState
+    ? `Local CLI restarted during ${restoredFromState}; provide guidance to continue this run.`
+    : String(restoredSnapshot.metadata?.last_agent_output || "");
+  run.startedAt = restoredSnapshot.created_at || null;
+  run.completedAt = restoredSnapshot.updated_at || null;
+  run.controlState = restoredState === "stopped" ? "stopped" : "waiting_human";
+  run.restoredFromState = restoredFromState;
+  return run;
+}
+
+export async function publishRestoredLocalCodingRun(run) {
+  if (!run?.restoredFromState) return run?.snapshot || null;
+  await updateRun(run, "waiting_human");
+  return run.snapshot;
+}
+
 export async function startLocalCodingRun(
   run,
-  { executeAttempt, executeIndependentAudit, collectEvidence } = {},
+  dependencies = {},
 ) {
-  if (run.child || TERMINAL_STATES.has(run.status) || run.startedAt) return;
+  if (run.operation || run.child || TERMINAL_STATES.has(run.status) || run.startedAt) return;
   run.startedAt = new Date().toISOString();
+  run.controlState = "running";
+  return executeLocalCodingRun(run, dependencies);
+}
+
+export async function continueLocalCodingRun(run, guidance, dependencies = {}) {
+  const message = String(guidance || "").trim();
+  if (!message) throw new Error("Human guidance is required.");
+  if (run.operation || run.child) throw new Error("The selected coding run is still active.");
+  if (!RESUMABLE_STATES.has(run.status)) {
+    throw new Error("Human guidance is available only when the selected run is waiting.");
+  }
+
+  const nextAttempt = run.snapshot.attempts.length + 1;
+  if (nextAttempt > 5) throw new Error("The coding run reached the five-attempt safety limit.");
+  run.snapshot.charter.max_attempts = Math.max(run.snapshot.charter.max_attempts, nextAttempt);
+  run.completedAt = null;
+  run.stopRequested = false;
+  run.controlState = "running";
+  run.resumeCount += 1;
+  emitControl(run, "human_input", `Human guidance accepted: ${message}`);
+  return executeLocalCodingRun(run, dependencies, { humanGuidance: message, resume: true });
+}
+
+export async function continueLocalCodingRunAfterRepositoryApproval(
+  run,
+  { repository, localPath } = {},
+  dependencies = {},
+) {
+  const approvedRepository = String(repository || run.request.repository || "").trim();
+  const approvedPath = String(localPath || "").trim();
+  if (!approvedRepository || !approvedPath) {
+    throw new Error("An approved local repository and path are required.");
+  }
+  if (run.operation || run.child) throw new Error("The selected coding run is still active.");
+  if (run.status !== "waiting_human") {
+    throw new Error("Repository approval is available only while the run is waiting.");
+  }
+  if (run.snapshot.attempts.length > 0) {
+    throw new Error("Repository approval cannot restart a run after a coding attempt.");
+  }
+
+  run.request.local_path = approvedPath;
+  run.snapshot.final_audit = null;
+  run.snapshot.events.push({
+    state: "queued",
+    message: "Local repository authorization accepted.",
+    detail: {
+      code: "local_repository_authorized",
+      repository: approvedRepository,
+    },
+    occurred_at: new Date().toISOString(),
+  });
+  run.snapshot.state = "queued";
+  run.status = "queued";
+  run.lastOutput = `Authorized local repository: ${approvedRepository}.`;
+  run.completedAt = null;
+  run.stopRequested = false;
+  run.controlState = "running";
+  emitControl(
+    run,
+    "repository_authorized",
+    `Authorized local repository selected: ${approvedRepository}.`,
+  );
+  return executeLocalCodingRun(run, dependencies, {
+    humanGuidance: `Repository scan approved: ${approvedRepository}.`,
+    resume: false,
+  });
+}
+
+export function isLocalRepositoryApprovalPending(run) {
+  if (run?.status !== "waiting_human" || run.snapshot?.attempts?.length > 0) return false;
+  const events = Array.isArray(run.snapshot?.events) ? run.snapshot.events : [];
+  const markerIndex = events.findLastIndex(
+    (event) => event?.detail?.code === "local_repository_not_found",
+  );
+  if (markerIndex < 0) return false;
+  return events
+    .slice(markerIndex + 1)
+    .every((event) => event?.state === "waiting_human" || event?.state === "pr_ready_for_review");
+}
+
+export function queueLocalCodingGuidance(run, guidance) {
+  const message = String(guidance || "").trim();
+  if (!message) throw new Error("Human guidance is required.");
+  run.pendingGuidance.push(message);
+  emitControl(
+    run,
+    "guidance_queued",
+    "Human guidance queued for the next executor handoff.",
+  );
+}
+
+export async function applyLocalHumanDecision(
+  run,
+  { message, designApproval = false, requiredChecks = [], acceptanceCriteria = [] } = {},
+  dependencies = {},
+) {
+  const guidance = String(message || "").trim();
+  if (!guidance) throw new Error("A human decision note is required.");
+  const charter = run.snapshot.charter;
+  if (acceptanceCriteria.length > 0) {
+    charter.acceptance_criteria = acceptanceCriteria.map(String).map((item) => item.trim()).filter(Boolean);
+    charter.acceptance_criteria_source = "explicit";
+  }
+  if (requiredChecks.length > 0) {
+    charter.required_checks = requiredChecks.map(String).map((item) => item.trim()).filter(Boolean);
+  }
+  if (designApproval) {
+    charter.design_review.summary = guidance;
+    charter.design_review.approved_by = run.session?.device_id || "local-cli-human";
+    charter.design_review.evidence_url = `local-cli://approval/${encodeURIComponent(run.id)}/${Date.now()}`;
+    charter.design_review.status = "approved";
+  }
+  return continueLocalCodingRun(run, guidance, dependencies);
+}
+
+export function pauseLocalCodingRun(run) {
+  if (!run.child) throw new Error("The selected run has no active executor process.");
+  if (run.controlState === "paused") throw new Error("The executor process is already paused.");
+  if (process.platform === "win32") {
+    throw new Error("Process pause is not supported on Windows; stop the run instead.");
+  }
+  if (!run.child.kill("SIGSTOP")) throw new Error("The executor process could not be paused.");
+  run.controlState = "paused";
+  emitControl(run, "paused", "Executor paused by the local human operator.");
+}
+
+export function resumeLocalCodingRun(run) {
+  if (!run.child) throw new Error("The selected run has no paused executor process.");
+  if (run.controlState !== "paused") throw new Error("The executor process is not paused.");
+  if (process.platform === "win32") {
+    throw new Error("Process resume is not supported on Windows.");
+  }
+  if (!run.child.kill("SIGCONT")) throw new Error("The executor process could not be resumed.");
+  run.controlState = "running";
+  emitControl(run, "resumed", "Executor resumed by the local human operator.");
+}
+
+export async function stopLocalCodingRun(run) {
+  if (run.status === "stopped") return run.snapshot;
+  if (run.stopRequested) {
+    await waitForLocalStop(run);
+    return run.snapshot;
+  }
+  run.stopRequested = true;
+  run.controlState = "stopping";
+  emitControl(run, "stopping", "Stop requested by the local human operator.");
+
+  const child = run.child;
+  if (!child) {
+    await finalizeLocalStop(run);
+    return run.snapshot;
+  }
+
+  let outcome = await signalAndWaitForClose(child, "SIGINT", 1_500);
+  if (outcome === "timeout" && run.child === child) {
+    outcome = await signalAndWaitForClose(child, "SIGTERM", 1_500);
+  }
+  if (outcome === "timeout" && run.child === child) {
+    await signalAndWaitForClose(child, "SIGKILL", 750);
+  }
+  await waitForLocalStop(run);
+  await finalizeLocalStop(run);
+  return run.snapshot;
+}
+
+async function signalAndWaitForClose(child, signal, timeoutMs) {
+  const close = once(child, "close").then(() => "closed");
+  child.kill(signal);
+  return Promise.race([
+    close,
+    new Promise((resolve) => setTimeout(() => resolve("timeout"), timeoutMs)),
+  ]);
+}
+
+async function waitForLocalStop(run) {
+  if (!run.operation) return;
+  await Promise.race([
+    run.operation.catch(() => null),
+    new Promise((resolve) => setTimeout(resolve, 1_500)),
+  ]);
+}
+
+async function finalizeLocalStop(run) {
+  if (run.status === "stopped") return;
+  if (run.snapshot.events.at(-1)?.state !== "stopped") {
+    run.snapshot.events.push({
+      state: "stopped",
+      message: "Coding loop stopped by the local human operator.",
+      detail: { source: "local_cli" },
+      occurred_at: new Date().toISOString(),
+    });
+  }
+  await updateRun(run, "stopped");
+}
 
+async function executeLocalCodingRun(
+  run,
+  { executeAttempt, executeIndependentAudit, collectEvidence } = {},
+  { humanGuidance = "", resume = false } = {},
+) {
+  const operation = runLocalCodingRun(run, {
+    executeAttempt,
+    executeIndependentAudit,
+    collectEvidence,
+    humanGuidance,
+    resume,
+  });
+  run.operation = operation;
+  try {
+    return await operation;
+  } finally {
+    if (run.operation === operation) run.operation = null;
+  }
+}
+
+async function runLocalCodingRun(
+  run,
+  { executeAttempt, executeIndependentAudit, collectEvidence, humanGuidance, resume },
+) {
   let repositoryPath;
   try {
     repositoryPath = await resolveRepositoryPath(run.request);
@@ -91,10 +416,13 @@ export async function startLocalCodingRun(
       detail: { code: "local_repository_not_found" },
       occurred_at: new Date().toISOString(),
     });
+    await cleanupLocalAttachments(run);
     await updateRun(run, "waiting_human");
     return;
   }
 
+  markAttachmentsDelivered(run.request.attachments);
+
   const executor =
     executeAttempt ||
     ((context) =>
@@ -127,6 +455,10 @@ export async function startLocalCodingRun(
       executeAttempt: executor,
       executeIndependentAudit: independentAuditor,
       collectEvidence: evidenceCollector,
+      humanGuidance,
+      resume,
+      shouldStop: () => run.stopRequested,
+      consumeHumanGuidance: () => run.pendingGuidance.splice(0).join("\n\n"),
       onUpdate: async (snapshot) => {
         run.snapshot = snapshot;
         await updateRun(run, snapshot.state);
@@ -142,6 +474,31 @@ export async function startLocalCodingRun(
       occurred_at: new Date().toISOString(),
     });
     await updateRun(run, "failed");
+  } finally {
+    const cleanupError = await cleanupLocalAttachments(run);
+    if (cleanupError) {
+      const message = `Local attachment cleanup failed: ${cleanupError}`;
+      emitOutput(run, message);
+      run.snapshot.events.push({
+        state: "failed",
+        message: "Local attachment cleanup failed.",
+        detail: { error: cleanupError },
+        occurred_at: new Date().toISOString(),
+      });
+      run.snapshot.state = "failed";
+    }
+    await updateRun(run, run.snapshot.state);
+  }
+}
+
+async function cleanupLocalAttachments(run) {
+  try {
+    await cleanupRunAttachments(run.request.attachments);
+    markAttachmentsCleaned(run.request.attachments);
+    return null;
+  } catch (error) {
+    markAttachmentsCleanupFailed(run.request.attachments, error);
+    return error instanceof Error ? error.message : "attachment cleanup failed";
   }
 }
 
@@ -174,11 +531,14 @@ async function executeProcessAttempt({
   repositoryPath,
   run,
   marker = "SIMY_RESULT_JSON:",
+  attemptNumber = null,
 }) {
-  const command = resolveBackendCommand({ backend, instruction, repositoryPath });
+  const command = await resolveBackendCommand({ backend, instruction, repositoryPath });
   const startedAt = new Date().toISOString();
   const stdout = [];
   const stderr = [];
+  const tokenUsageRecords = [];
+  const phase = marker === "SIMY_AUDIT_JSON:" ? "reviewer" : "executor";
 
   return new Promise((resolve) => {
     let settled = false;
@@ -189,17 +549,36 @@ async function executeProcessAttempt({
     });
     run.child = child;
 
-    const collect = (target, chunk) => {
+    const stdoutDecoder = createProviderStreamDecoder({
+      backend,
+      stream: "stdout",
+      onLine: (line) => emitOutput(run, line, { backend }),
+      onUsage: (usage) =>
+        tokenUsageRecords.push({
+          ...usage,
+          phase,
+          ...(Number.isInteger(attemptNumber) ? { attempt_number: attemptNumber } : {}),
+          backend,
+        }),
+    });
+    const stderrDecoder = createProviderStreamDecoder({
+      backend,
+      stream: "stderr",
+      onLine: (line) => emitOutput(run, line, { backend }),
+    });
+    const collect = (target, decoder, chunk) => {
       const text = chunk.toString("utf8");
       target.push(text);
-      emitOutput(run, text);
+      decoder.push(text);
     };
-    child.stdout?.on("data", (chunk) => collect(stdout, chunk));
-    child.stderr?.on("data", (chunk) => collect(stderr, chunk));
+    child.stdout?.on("data", (chunk) => collect(stdout, stdoutDecoder, chunk));
+    child.stderr?.on("data", (chunk) => collect(stderr, stderrDecoder, chunk));
 
     const finish = ({ exitCode = null, error = null } = {}) => {
       if (settled) return;
       settled = true;
+      stdoutDecoder.flush();
+      stderrDecoder.flush();
       run.child = null;
       const rawStdout = stdout.join("");
       const assistantText = extractAssistantText(rawStdout);
@@ -212,6 +591,8 @@ async function executeProcessAttempt({
         exitCode,
         error,
         result: Object.keys(result).length > 0 ? result : parse(rawStdout),
+        tokenUsage:
+          tokenUsageRecords.length > 0 ? { records: tokenUsageRecords } : {},
         logs: [...stdout, ...stderr]
           .join("")
           .split(/\r?\n/)
@@ -227,13 +608,14 @@ async function executeProcessAttempt({
   });
 }
 
-function resolveBackendCommand({ backend, instruction, repositoryPath }) {
+async function resolveBackendCommand({ backend, instruction, repositoryPath }) {
   if (backend === "claude") {
     const override = process.env.SIMY_CLAUDE_COMMAND;
     if (override) return shellCommand(override, repositoryPath, instruction);
+    const binary = (await resolveBackendExecutable("claude")) || "claude";
     return {
-      bin: "claude",
-      args: ["-p", instruction, "--output-format", "stream-json", "--verbose"],
+      bin: binary,
+      args: claudeBackendArgs(instruction),
       env: {},
       spawn,
     };
@@ -241,14 +623,29 @@ function resolveBackendCommand({ backend, instruction, repositoryPath }) {
 
   const override = process.env.SIMY_CODEX_COMMAND;
   if (override) return shellCommand(override, repositoryPath, instruction);
+  const binary = (await resolveBackendExecutable("codex")) || "codex";
   return {
-    bin: "codex",
+    bin: binary,
     args: ["exec", "--json", instruction],
     env: {},
     spawn,
   };
 }
 
+export function claudeBackendArgs(instruction) {
+  return [
+    "-p",
+    instruction,
+    "--output-format",
+    "stream-json",
+    "--verbose",
+    // The Coding Loop is already scoped to a verified checkout and explicitly
+    // approved by the user. Print mode cannot display permission prompts, so
+    // edits would otherwise be silently unavailable to the executor.
+    "--dangerously-skip-permissions",
+  ];
+}
+
 function shellCommand(command, cwd, instruction) {
   return {
     bin: process.platform === "win32" ? "cmd.exe" : "sh",
@@ -259,12 +656,15 @@ function shellCommand(command, cwd, instruction) {
   };
 }
 
-async function resolveRepositoryPath(request) {
+export async function resolveRepositoryPath(request) {
   const repository = String(request.repository || "").replace(/^https?:\/\/github\.com\//, "").replace(/\.git$/, "");
   const repoName = repository.split("/").filter(Boolean).at(-1);
   if (!repoName) throw new Error("The coding loop did not specify a valid GitHub repository.");
 
-  const roots = [request.local_path, process.env.SIMY_REPO_ROOT, process.cwd()].filter(Boolean);
+  // An operator-provided root scopes this CLI process to the intended workspace.
+  // Persisted inventory paths can outlive a checkout, so only prefer them when no
+  // explicit process scope is configured.
+  const roots = [process.env.SIMY_REPO_ROOT, request.local_path, process.cwd()].filter(Boolean);
   const candidates = new Set();
   for (const root of roots) {
     const resolved = path.resolve(String(root));
@@ -280,29 +680,19 @@ async function resolveRepositoryPath(request) {
 
   throw new Error(
     `Repository ${repository} was not found below ${process.env.SIMY_REPO_ROOT || process.cwd()}. ` +
-      "Start simy from the repository or its workspace root, or set SIMY_REPO_ROOT.",
+      "Open SIMY CLI and press s to authorize a local repository scan, or set SIMY_REPO_ROOT.",
   );
 }
 
 async function gitRemote(cwd) {
   try {
     const { stdout } = await execFileAsync("git", ["remote", "get-url", "origin"], { cwd });
-    return normalizeGitHubRemote(stdout);
+    return normalizeGitHubRemote(stdout)?.toLowerCase() ?? null;
   } catch {
     return null;
   }
 }
 
-function normalizeGitHubRemote(value) {
-  return String(value || "")
-    .trim()
-    .replace(/^git@github\.com:/, "")
-    .replace(/^ssh:\/\/git@github\.com\//, "")
-    .replace(/^https?:\/\/github\.com\//, "")
-    .replace(/\.git$/, "")
-    .toLowerCase();
-}
-
 async function pathExists(value) {
   try {
     await access(value);
@@ -332,25 +722,55 @@ function extractAssistantText(raw) {
   return messages.join("\n");
 }
 
-function emitOutput(run, text) {
+function emitOutput(run, text, { backend = run.request.backend } = {}) {
   for (const line of String(text).split(/\r?\n/)) {
     if (!line.trim()) continue;
+    const occurredAt = new Date().toISOString();
     run.lastOutput = line;
+    run.logs.push({
+      text: line,
+      backend,
+      occurred_at: occurredAt,
+    });
+    if (run.logs.length > MAX_LOCAL_LOG_LINES) {
+      run.logs.splice(0, run.logs.length - MAX_LOCAL_LOG_LINES);
+    }
     run.emitter.emit("event", {
       type: "output",
       run_id: run.id,
-      backend: run.request.backend,
+      backend,
       text: line,
-      occurred_at: new Date().toISOString(),
+      occurred_at: occurredAt,
     });
   }
 }
 
+function emitControl(run, state, message) {
+  run.emitter.emit("event", {
+    type: "control",
+    run_id: run.id,
+    state,
+    message,
+    occurred_at: new Date().toISOString(),
+  });
+}
+
 async function updateRun(run, state) {
   run.status = state;
   run.snapshot.state = state;
   run.snapshot.updated_at = new Date().toISOString();
   run.completedAt = TERMINAL_STATES.has(state) ? run.snapshot.updated_at : null;
+  if (state === "waiting_human" || state === "pr_ready_for_review") {
+    run.controlState = "waiting_human";
+  } else if (state === "stopped") {
+    run.controlState = "stopped";
+  } else if (state === "merge_ready") {
+    run.controlState = "complete";
+  } else if (TERMINAL_STATES.has(state)) {
+    run.controlState = "complete";
+  } else if (run.controlState !== "paused" && run.controlState !== "stopping") {
+    run.controlState = "running";
+  }
 
   run.emitter.emit("event", { type: "run", run: toLedgerSnapshot(run.snapshot) });
   const latestEvent = run.snapshot.events.at(-1);
@@ -395,15 +815,18 @@ async function drainLedgerUpdates(run) {
 }
 
 async function persistRunStatus(run, update) {
-  const url = new URL(`/api/local-cli/runs/${encodeURIComponent(run.id)}/status`, run.apiOrigin);
+  const url = webApiUrl(`runs/${encodeURIComponent(run.id)}/status`, {
+    webOrigin: run.apiOrigin,
+    apiBaseUrl: run.session.api_base_url,
+  });
   try {
     const response = await fetch(url, {
       method: "POST",
       signal: AbortSignal.timeout(5000),
-      headers: {
-        Authorization: `Bearer ${run.session.token}`,
-        "Content-Type": "application/json",
-      },
+      headers: webApiHeaders(
+        { token: run.session.token },
+        { "Content-Type": "application/json" },
+      ),
       body: JSON.stringify({
         state: update.state,
         last_agent_output: redactExecutionText(run.lastOutput, { maxChars: 2_000 }).text || null,
@@ -420,15 +843,32 @@ async function persistRunStatus(run, update) {
 }
 
 export function toLedgerSnapshot(snapshot) {
+  const attachments = snapshot.charter.attachments || [];
   return {
     ...snapshot,
+    charter: {
+      ...snapshot.charter,
+      attachments: (snapshot.charter.attachments || []).map(attachmentDescriptorForLedger),
+    },
     state: toCompatibleCodingLoopState(snapshot.state),
-    attempts: snapshot.attempts.map(redactedAttemptForLedger),
-    events: snapshot.events.map((item) => ({
-      ...item,
-      state: toCompatibleCodingLoopState(item.state),
-      detail: redactedEventDetail(item.detail, item.state),
-    })),
+    attempts: snapshot.attempts.map((attempt) => redactedAttemptForLedger(attempt, attachments)),
+    events: snapshot.events.map((item) => {
+      const presentation = summarizeCodingLoopEvent(snapshot, item);
+      return {
+        ...item,
+        state: toCompatibleCodingLoopState(item.state),
+        detail: redactedEventDetail(
+          {
+            ...item.detail,
+            step_summary: presentation.summary,
+            step_result: presentation.result,
+            next_action: presentation.next,
+          },
+          item.state,
+          attachments,
+        ),
+      };
+    }),
     metadata: {
       ...(snapshot.metadata || {}),
       pr_lifecycle_state: snapshot.state,
@@ -440,15 +880,19 @@ export function toLedgerSnapshot(snapshot) {
   };
 }
 
-function redactedAttemptForLedger(attempt) {
+function redactedAttemptForLedger(attempt, attachments) {
   const instruction = redactExecutionText(attempt.instruction);
   const executorLogs = redactExecutionLogs(attempt.executor_logs);
-  const logText = executorLogs.lines.join("\n");
+  const redactedInstruction = redactAttachmentPaths(instruction.text, attachments);
+  const redactedExecutorLogs = executorLogs.lines.map((line) =>
+    redactAttachmentPaths(line, attachments),
+  );
+  const logText = redactedExecutorLogs.join("\n");
   return {
     ...attempt,
-    instruction: instruction.text,
-    instruction_sha256: executionTextSha256(instruction.text),
-    executor_logs: executorLogs.lines,
+    instruction: redactedInstruction,
+    instruction_sha256: executionTextSha256(redactedInstruction),
+    executor_logs: redactedExecutorLogs,
     executor_logs_sha256: executionTextSha256(logText),
     io_redaction: {
       policy_version: EXECUTION_IO_POLICY_VERSION,
@@ -462,15 +906,20 @@ function redactedAttemptForLedger(attempt) {
   };
 }
 
-function redactedEventDetail(value, lifecycleState) {
+function redactedEventDetail(value, lifecycleState, attachments) {
   const detail = value && typeof value === "object" ? value : {};
   const result = {};
   for (const [key, item] of Object.entries(detail)) {
     if (["instruction", "reinstruction", "prompt", "last_agent_output"].includes(key)) {
-      result[key] = redactExecutionText(item, { maxChars: 24_000 }).text;
+      result[key] = redactAttachmentPaths(
+        redactExecutionText(item, { maxChars: 24_000 }).text,
+        attachments,
+      );
     } else if (["executor_logs", "stdout", "stderr"].includes(key)) {
       const logs = Array.isArray(item) ? item : [item];
-      result[key] = redactExecutionLogs(logs).lines;
+      result[key] = redactExecutionLogs(logs).lines.map((line) =>
+        redactAttachmentPaths(line, attachments),
+      );
     } else {
       result[key] = item;
     }
@@ -479,6 +928,16 @@ function redactedEventDetail(value, lifecycleState) {
   return result;
 }
 
+function redactAttachmentPaths(value, attachments) {
+  let text = String(value || "");
+  for (const attachment of attachments) {
+    if (typeof attachment?.local_path === "string" && attachment.local_path) {
+      text = text.replaceAll(attachment.local_path, `[LOCAL_ATTACHMENT:${attachment.name}]`);
+    }
+  }
+  return text;
+}
+
 function observedEvidenceForLedger(value) {
   if (!value || typeof value !== "object") return null;
   const local = value.local && typeof value.local === "object" ? value.local : {};
@@ -530,6 +989,8 @@ export function toCompatibleCodingLoopState(state) {
       return "waiting_human";
     case "merge_ready":
       return "done";
+    case "stopped":
+      return "failed";
     default:
       return state;
   }