ai-whisper 0.2.1 → 0.3.0

package/dist/bin/companion-agent.js

@@ -582,6 +582,100 @@ function getCollab(db, collabId) {
   });
 }
 
+// ../broker/dist/storage/repositories/workflow-repository.js
+function rowToRecord(row) {
+  return {
+    workflowId: row.workflow_id,
+    collabId: row.collab_id,
+    workflowType: row.workflow_type,
+    name: row.name,
+    specPath: row.spec_path,
+    roleBindings: JSON.parse(row.role_bindings),
+    status: row.status,
+    currentPhaseIndex: row.current_phase_index,
+    haltReason: row.halt_reason,
+    workflowContext: JSON.parse(row.workflow_context),
+    createdAt: row.created_at,
+    updatedAt: row.updated_at
+  };
+}
+function insertWorkflow(db, input) {
+  db.prepare(`INSERT INTO workflows
+		 (workflow_id, collab_id, workflow_type, name, spec_path, role_bindings, status,
+		  current_phase_index, halt_reason, workflow_context, created_at, updated_at)
+		 VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL, ?, ?, ?)`).run(input.workflowId, input.collabId, input.workflowType, input.name, input.specPath, JSON.stringify(input.roleBindings), input.status, input.currentPhaseIndex, JSON.stringify(input.workflowContext), input.now, input.now);
+}
+function getWorkflowById(db, workflowId) {
+  const row = db.prepare("SELECT * FROM workflows WHERE workflow_id = ?").get(workflowId);
+  return row ? rowToRecord(row) : null;
+}
+function listWorkflows(db, filter = {}) {
+  const clauses = [];
+  const args = [];
+  if (filter.collabId) {
+    clauses.push("collab_id = ?");
+    args.push(filter.collabId);
+  }
+  if (filter.status) {
+    clauses.push("status = ?");
+    args.push(filter.status);
+  }
+  const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+  const rows = db.prepare(`SELECT * FROM workflows ${where} ORDER BY created_at DESC`).all(...args);
+  return rows.map(rowToRecord);
+}
+function setWorkflowStatus(db, input) {
+  db.prepare(`UPDATE workflows
+		   SET status = ?, halt_reason = ?, updated_at = ?
+		 WHERE workflow_id = ?`).run(input.status, input.haltReason, input.now, input.workflowId);
+}
+function updateWorkflowContext(db, input) {
+  const existing = getWorkflowById(db, input.workflowId);
+  if (!existing) {
+    throw new Error(`updateWorkflowContext: unknown workflowId ${input.workflowId}`);
+  }
+  const merged = { ...existing.workflowContext, ...input.patch };
+  db.prepare("UPDATE workflows SET workflow_context = ?, updated_at = ? WHERE workflow_id = ?").run(JSON.stringify(merged), input.now, input.workflowId);
+}
+function incrementCurrentPhaseIndex(db, input) {
+  db.prepare(`UPDATE workflows
+		   SET current_phase_index = current_phase_index + 1, updated_at = ?
+		 WHERE workflow_id = ?`).run(input.now, input.workflowId);
+}
+function countActiveWorkflowsForCollab(db, collabId) {
+  const row = db.prepare("SELECT COUNT(*) AS n FROM workflows WHERE collab_id = ? AND status IN ('running', 'paused')").get(collabId);
+  return row.n;
+}
+
+// ../broker/dist/runtime/workspace-snapshot.js
+import { execFileSync } from "node:child_process";
+function captureWorkspaceSnapshotSync(workspaceRoot) {
+  try {
+    const ref = execFileSync("git", ["-C", workspaceRoot, "stash", "create"], {
+      encoding: "utf8",
+      timeout: 1e4
+    }).trim();
+    if (ref)
+      return ref;
+    const head = execFileSync("git", ["-C", workspaceRoot, "rev-parse", "HEAD"], {
+      encoding: "utf8",
+      timeout: 1e4
+    }).trim();
+    return head || null;
+  } catch {
+    return null;
+  }
+}
+function diffChangedFilesSince(workspaceRoot, sinceRef) {
+  try {
+    const stdout = execFileSync("git", ["-C", workspaceRoot, "diff", "--name-only", sinceRef], { encoding: "utf8", timeout: 1e4 });
+    const files = stdout.split("\n").map((l) => l.trim()).filter((l) => l.length > 0 && !l.startsWith(".ai-whisper/"));
+    return [...new Set(files)].sort();
+  } catch {
+    return [];
+  }
+}
+
 // ../broker/dist/storage/repositories/reply-repository.js
 function insertReply(db, reply) {
   db.prepare(`INSERT INTO reply (
@@ -1047,7 +1141,7 @@ function upsertRelayTurnState(db, input) {
 }
 
 // ../broker/dist/storage/repositories/relay-capture-diagnostics-repository.js
-function rowToRecord(row) {
+function rowToRecord2(row) {
   return {
     captureId: row.capture_id,
     handoffId: row.handoff_id,
@@ -1084,32 +1178,32 @@ function listCaptureDiagnosticsByCollab(db, collabId, limit, opts) {
     const rows2 = db.prepare(`SELECT * FROM relay_capture_diagnostics
 				 WHERE collab_id = ?${filterClause}
 				 ORDER BY created_at DESC`).all(collabId, ...filterArgs);
-    return rows2.map(rowToRecord);
+    return rows2.map(rowToRecord2);
   }
   const rows = db.prepare(`SELECT * FROM relay_capture_diagnostics
 			 WHERE collab_id = ?${filterClause}
 			 ORDER BY created_at DESC
 			 LIMIT ?`).all(collabId, ...filterArgs, limit);
-  return rows.map(rowToRecord);
+  return rows.map(rowToRecord2);
 }
 function listCaptureDiagnosticsByCollabAndChain(db, collabId, chainId, limit) {
   if (limit === null) {
     const rows2 = db.prepare(`SELECT * FROM relay_capture_diagnostics
 				 WHERE collab_id = ? AND chain_id = ?
 				 ORDER BY created_at DESC`).all(collabId, chainId);
-    return rows2.map(rowToRecord);
+    return rows2.map(rowToRecord2);
   }
   const rows = db.prepare(`SELECT * FROM relay_capture_diagnostics
 			 WHERE collab_id = ? AND chain_id = ?
 			 ORDER BY created_at DESC
 			 LIMIT ?`).all(collabId, chainId, limit);
-  return rows.map(rowToRecord);
+  return rows.map(rowToRecord2);
 }
 function listCaptureDiagnosticsByHandoff(db, handoffId) {
   const rows = db.prepare(`SELECT * FROM relay_capture_diagnostics
 			 WHERE handoff_id = ?
 			 ORDER BY created_at ASC`).all(handoffId);
-  return rows.map(rowToRecord);
+  return rows.map(rowToRecord2);
 }
 function deleteCaptureDiagnosticsOlderThan(db, cutoffIso) {
   const result = db.prepare("DELETE FROM relay_capture_diagnostics WHERE created_at < ?").run(cutoffIso);
@@ -1117,7 +1211,7 @@ function deleteCaptureDiagnosticsOlderThan(db, cutoffIso) {
 }
 
 // ../broker/dist/storage/repositories/relay-evaluator-diagnostics-repository.js
-function rowToRecord2(row) {
+function rowToRecord3(row) {
   return {
     evaluatorId: row.evaluator_id,
     handoffId: row.handoff_id,
@@ -1162,32 +1256,32 @@ function listEvaluatorDiagnosticsByCollab(db, collabId, limit, opts) {
     const rows2 = db.prepare(`SELECT * FROM relay_evaluator_diagnostics
 				 WHERE collab_id = ?${filterClause}
 				 ORDER BY created_at DESC`).all(collabId, ...filterArgs);
-    return rows2.map(rowToRecord2);
+    return rows2.map(rowToRecord3);
   }
   const rows = db.prepare(`SELECT * FROM relay_evaluator_diagnostics
 			 WHERE collab_id = ?${filterClause}
 			 ORDER BY created_at DESC
 			 LIMIT ?`).all(collabId, ...filterArgs, limit);
-  return rows.map(rowToRecord2);
+  return rows.map(rowToRecord3);
 }
 function listEvaluatorDiagnosticsByCollabAndChain(db, collabId, chainId, limit) {
   if (limit === null) {
     const rows2 = db.prepare(`SELECT * FROM relay_evaluator_diagnostics
 				 WHERE collab_id = ? AND chain_id = ?
 				 ORDER BY created_at DESC`).all(collabId, chainId);
-    return rows2.map(rowToRecord2);
+    return rows2.map(rowToRecord3);
   }
   const rows = db.prepare(`SELECT * FROM relay_evaluator_diagnostics
 			 WHERE collab_id = ? AND chain_id = ?
 			 ORDER BY created_at DESC
 			 LIMIT ?`).all(collabId, chainId, limit);
-  return rows.map(rowToRecord2);
+  return rows.map(rowToRecord3);
 }
 function listEvaluatorDiagnosticsByHandoff(db, handoffId) {
   const rows = db.prepare(`SELECT * FROM relay_evaluator_diagnostics
 			 WHERE handoff_id = ?
 			 ORDER BY created_at ASC`).all(handoffId);
-  return rows.map(rowToRecord2);
+  return rows.map(rowToRecord3);
 }
 function deleteEvaluatorDiagnosticsOlderThan(db, cutoffIso) {
   const result = db.prepare("DELETE FROM relay_evaluator_diagnostics WHERE created_at < ?").run(cutoffIso);
@@ -1195,7 +1289,7 @@ function deleteEvaluatorDiagnosticsOlderThan(db, cutoffIso) {
 }
 
 // ../broker/dist/storage/repositories/relay-handoff-repository.js
-function rowToRecord3(row) {
+function rowToRecord4(row) {
   return {
     handoffId: row.handoff_id,
     collabId: row.collab_id,
@@ -1232,7 +1326,7 @@ function queryRelayHandoff(db, handoffId) {
 			 FROM relay_handoff h
 			 JOIN collab c ON c.collab_id = h.collab_id
 			 WHERE h.handoff_id = ?`).get(handoffId);
-  return row ? rowToRecord3(row) : null;
+  return row ? rowToRecord4(row) : null;
 }
 function createRelayHandoffTxn(db, input) {
   return db.transaction(() => {
@@ -1384,7 +1478,7 @@ function queryLatestHandedBackHandoff(db, collabId) {
 			 WHERE h.collab_id = ? AND h.status = 'handed_back'
 			 ORDER BY h.resolved_at DESC
 			 LIMIT 1`).get(collabId);
-  return row ? rowToRecord3(row) : null;
+  return row ? rowToRecord4(row) : null;
 }
 function failRelayHandoffOnDisconnectTxn(db, input) {
   db.transaction(() => {
@@ -1408,6 +1502,30 @@ function failRelayHandoffOnDisconnectTxn(db, input) {
     }
   })();
 }
+function hasInFlightAcceptedHandoffForWorkflow(db, workflowId) {
+  const row = db.prepare("SELECT COUNT(*) AS n FROM relay_handoff WHERE workflow_id = ? AND status = 'accepted'").get(workflowId);
+  return row.n > 0;
+}
+function resetStrandedOrchestrationForWorkflow(db, workflowId) {
+  const result = db.prepare(`UPDATE relay_handoff
+			    SET orchestrator_status = 'idle', orchestrator_claimed_at = NULL
+			  WHERE workflow_id = ?
+			    AND status = 'handed_back'
+			    AND orchestrator_status = 'pending'
+			    AND evaluator_verdict IS NULL`).run(workflowId);
+  return result.changes;
+}
+function prependToPendingHandoffRequestText(db, input) {
+  const row = db.prepare(`SELECT handoff_id, request_text FROM relay_handoff
+			  WHERE workflow_id = ? AND status = 'pending'
+			  ORDER BY created_at DESC LIMIT 1`).get(input.workflowId);
+  if (!row)
+    return false;
+  db.prepare("UPDATE relay_handoff SET request_text = ?, last_activity_at = ? WHERE handoff_id = ?").run(`${input.prefix}
+
+${row.request_text}`, input.now, row.handoff_id);
+  return true;
+}
 function claimRelayHandoffForOrchestrationTxn(db, input) {
   const result = db.prepare(`UPDATE relay_handoff
 			    SET orchestrator_status = 'pending',
@@ -1426,10 +1544,12 @@ function listRelayHandoffsPendingOrchestration(db, collabId) {
 			        c.orchestrator_max_rounds AS max_rounds
 			 FROM relay_handoff h
 			 JOIN collab c ON c.collab_id = h.collab_id
+			 LEFT JOIN workflows w ON w.workflow_id = h.workflow_id
 			 WHERE h.collab_id = ?
 			   AND h.status = 'handed_back'
-			   AND h.orchestrator_status = 'idle'`).all(collabId);
-  return rows.map(rowToRecord3);
+			   AND h.orchestrator_status = 'idle'
+			   AND (w.status IS NULL OR w.status <> 'paused')`).all(collabId);
+  return rows.map(rowToRecord4);
 }
 function createLoopRelayHandoffTxn(db, input) {
   return db.transaction(() => {
@@ -1625,7 +1745,7 @@ function getHandoffWithWorkflowMetaById(db, handoffId) {
 			 WHERE h.handoff_id = ?`).get(handoffId);
   if (!row)
     return null;
-  const base = rowToRecord3(row);
+  const base = rowToRecord4(row);
   return {
     ...base,
     handoffStep: row.handoff_step,
@@ -1875,71 +1995,6 @@ function listRunCostRows(db, input) {
 // ../broker/dist/control/workflow-control.js
 import { randomUUID } from "node:crypto";
 
-// ../broker/dist/storage/repositories/workflow-repository.js
-function rowToRecord4(row) {
-  return {
-    workflowId: row.workflow_id,
-    collabId: row.collab_id,
-    workflowType: row.workflow_type,
-    name: row.name,
-    specPath: row.spec_path,
-    roleBindings: JSON.parse(row.role_bindings),
-    status: row.status,
-    currentPhaseIndex: row.current_phase_index,
-    haltReason: row.halt_reason,
-    workflowContext: JSON.parse(row.workflow_context),
-    createdAt: row.created_at,
-    updatedAt: row.updated_at
-  };
-}
-function insertWorkflow(db, input) {
-  db.prepare(`INSERT INTO workflows
-		 (workflow_id, collab_id, workflow_type, name, spec_path, role_bindings, status,
-		  current_phase_index, halt_reason, workflow_context, created_at, updated_at)
-		 VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL, ?, ?, ?)`).run(input.workflowId, input.collabId, input.workflowType, input.name, input.specPath, JSON.stringify(input.roleBindings), input.status, input.currentPhaseIndex, JSON.stringify(input.workflowContext), input.now, input.now);
-}
-function getWorkflowById(db, workflowId) {
-  const row = db.prepare("SELECT * FROM workflows WHERE workflow_id = ?").get(workflowId);
-  return row ? rowToRecord4(row) : null;
-}
-function listWorkflows(db, filter = {}) {
-  const clauses = [];
-  const args = [];
-  if (filter.collabId) {
-    clauses.push("collab_id = ?");
-    args.push(filter.collabId);
-  }
-  if (filter.status) {
-    clauses.push("status = ?");
-    args.push(filter.status);
-  }
-  const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
-  const rows = db.prepare(`SELECT * FROM workflows ${where} ORDER BY created_at DESC`).all(...args);
-  return rows.map(rowToRecord4);
-}
-function setWorkflowStatus(db, input) {
-  db.prepare(`UPDATE workflows
-		   SET status = ?, halt_reason = ?, updated_at = ?
-		 WHERE workflow_id = ?`).run(input.status, input.haltReason, input.now, input.workflowId);
-}
-function updateWorkflowContext(db, input) {
-  const existing = getWorkflowById(db, input.workflowId);
-  if (!existing) {
-    throw new Error(`updateWorkflowContext: unknown workflowId ${input.workflowId}`);
-  }
-  const merged = { ...existing.workflowContext, ...input.patch };
-  db.prepare("UPDATE workflows SET workflow_context = ?, updated_at = ? WHERE workflow_id = ?").run(JSON.stringify(merged), input.now, input.workflowId);
-}
-function incrementCurrentPhaseIndex(db, input) {
-  db.prepare(`UPDATE workflows
-		   SET current_phase_index = current_phase_index + 1, updated_at = ?
-		 WHERE workflow_id = ?`).run(input.now, input.workflowId);
-}
-function countRunningWorkflowsForCollab(db, collabId) {
-  const row = db.prepare("SELECT COUNT(*) AS n FROM workflows WHERE collab_id = ? AND status = 'running'").get(collabId);
-  return row.n;
-}
-
 // ../broker/dist/storage/repositories/workflow-phase-repository.js
 function rowToRecord5(row) {
   return {
@@ -2060,6 +2115,14 @@ Findings:           (omit this block entirely if none)
 Non-blocking risks:
 - <quality risk that does NOT block this gate, or "None.">
 --- end protocol ---`;
+var WORKFLOW_OPERATOR_CONTROL = `--- ai-whisper operator control ---
+If the operator interrupts you and asks to pause the workflow (e.g. "pause the workflow, I need to fix X"):
+1. Find the active workflow id: run \`whisper workflow list\`.
+2. Run \`whisper workflow pause <id>\`.
+3. Acknowledge and STOP working \u2014 do not start the next change.
+The operator will edit artifacts and later run \`whisper workflow resume <id> [--message "..."]\`; you will then receive a notice of what changed and must re-read those files before continuing.
+Provider note: the Codex CLI EXITS its session on Ctrl+C at an idle prompt (a mid-task Ctrl+C only interrupts the running task). The operator typically interrupts you while you are BUSY before issuing this instruction; do not assume Ctrl+C is a safe no-op.
+--- end operator control ---`;
 var WORKFLOW_DIAGNOSIS_PROTOCOL = `--- ai-whisper diagnosis review protocol ---
 You are the gatekeeper for an ai-whisper complex-bug-fixing DIAGNOSIS gate. No human is in the loop. Do NOT trust the implementer's diagnosis \u2014 verify it yourself. The gate stays shut until YOU independently agree on the root cause and that the fix is net-safe.
 
@@ -2298,10 +2361,21 @@ var COMPLEX_BUG_FIXING = {
     }
   ]
 };
+function withOperatorControl(def) {
+  return {
+    ...def,
+    phases: def.phases.map((p) => ({
+      ...p,
+      kickoffTemplate: `${p.kickoffTemplate}
+
+${WORKFLOW_OPERATOR_CONTROL}`
+    }))
+  };
+}
 var REGISTRY = {
-  [SPEC_DRIVEN_DEVELOPMENT.type]: SPEC_DRIVEN_DEVELOPMENT,
-  [RALPH_LOOP.type]: RALPH_LOOP,
-  [COMPLEX_BUG_FIXING.type]: COMPLEX_BUG_FIXING
+  [SPEC_DRIVEN_DEVELOPMENT.type]: withOperatorControl(SPEC_DRIVEN_DEVELOPMENT),
+  [RALPH_LOOP.type]: withOperatorControl(RALPH_LOOP),
+  [COMPLEX_BUG_FIXING.type]: withOperatorControl(COMPLEX_BUG_FIXING)
 };
 function ralphRunDir(workspaceRoot, workflowId) {
   return join(workspaceRoot, ".ai-whisper", "ralph", workflowId);
@@ -2357,6 +2431,23 @@ function safeDerivePlanPath(specPath, createdAt) {
     return `${dir}${stem}.plan.md`;
   }
 }
+function composeResumeNotice(input) {
+  const hasFiles = input.changedFiles.length > 0;
+  const hasMessage = !!input.message && input.message.trim().length > 0;
+  if (!hasFiles && !hasMessage)
+    return null;
+  const lines = [];
+  if (hasFiles) {
+    lines.push("While paused, the operator modified these files:");
+    for (const f of input.changedFiles)
+      lines.push(`  - ${f}`);
+    lines.push("Re-read them before continuing.");
+  }
+  if (hasMessage)
+    lines.push(`Operator note: ${input.message.trim()}`);
+  lines.push("Re-evaluate whether your current direction still holds; correct course before proceeding.");
+  return lines.join("\n");
+}
 function createWorkflowControl(deps) {
   const { db, events } = deps;
   function createWorkflow(input) {
@@ -2379,8 +2470,9 @@ function createWorkflowControl(deps) {
     }
     const workflowId = `wf_${randomUUID().replace(/-/g, "").slice(0, 16)}`;
     const tx = db.transaction(() => {
-      if (countRunningWorkflowsForCollab(db, input.collabId) > 0) {
-        throw new Error(`another workflow is already running on this collab (${input.collabId})`);
+      if (countActiveWorkflowsForCollab(db, input.collabId) > 0) {
+        const active = listWorkflows(db, { collabId: input.collabId }).find((w) => w.status === "running" || w.status === "paused");
+        throw new Error(`another workflow is already active on this collab (${input.collabId})` + (active ? `: ${active.workflowId} (${active.status})` : ""));
       }
       insertWorkflow(db, {
         workflowId,
@@ -2548,6 +2640,24 @@ function createWorkflowControl(deps) {
       postmortemPath: bf.postmortemPath
     });
   }
+  function consumeResumeNotice(input) {
+    const wf = getWorkflowById(db, input.workflowId);
+    const notice = wf?.workflowContext?.resumeNotice ?? null;
+    if (notice) {
+      updateWorkflowContext(db, {
+        workflowId: input.workflowId,
+        patch: { resumeNotice: null },
+        now: input.now
+      });
+    }
+    return notice;
+  }
+  function withResumeNotice(workflowId, requestText, now) {
+    const notice = consumeResumeNotice({ workflowId, now });
+    return notice ? `${notice}
+
+${requestText}` : requestText;
+  }
   function createContinuationHandoff(input) {
     const handoffId = `ho_${randomUUID().replace(/-/g, "").slice(0, 16)}`;
     insertWorkflowOwnedRelayHandoff(db, {
@@ -2555,7 +2665,9 @@ function createWorkflowControl(deps) {
       collabId: input.workflow.collabId,
       senderAgent: input.sender,
       targetAgent: input.target,
-      requestText: input.requestText,
+      // Prepend the one-time resume notice (if any) to the FIRST outgoing request
+      // after a resume, then it is cleared — so the agent re-reads changed files.
+      requestText: withResumeNotice(input.workflow.workflowId, input.requestText, input.now),
       chainId: input.chain.chainId,
       roundNumber: input.incrementRound ? input.chain.currentRound + 1 : input.chain.currentRound,
       maxRounds: input.chain.maxRounds,
@@ -2615,7 +2727,9 @@ function createWorkflowControl(deps) {
       collabId: input.workflow.collabId,
       senderAgent: sender,
       targetAgent: target,
-      requestText: kickoffText,
+      // Prepend a pending resume notice (consumed once) so a phase-advance kickoff
+      // after a resume also carries the operator's change notice.
+      requestText: withResumeNotice(input.workflow.workflowId, kickoffText, input.now),
       chainId,
       roundNumber: 1,
       maxRounds: phase.maxRounds,
@@ -3076,20 +3190,100 @@ ${findingsText}`;
       reason: input.reason
     });
   }
+  function maybeCaptureQuiesceSnapshot(input) {
+    const wf = getWorkflowById(db, input.workflowId);
+    if (!wf || wf.status !== "paused")
+      return;
+    if (wf.workflowContext.pauseSnapshotRef !== void 0) {
+      return;
+    }
+    if (hasInFlightAcceptedHandoffForWorkflow(db, input.workflowId))
+      return;
+    const ref = deps.captureSnapshotRef ? deps.captureSnapshotRef(input.workflowId) : null;
+    updateWorkflowContext(db, {
+      workflowId: input.workflowId,
+      patch: { pauseSnapshotRef: ref },
+      now: input.now
+    });
+  }
+  function pauseWorkflow(input) {
+    const workflow = getWorkflowById(db, input.workflowId);
+    if (!workflow) {
+      throw new Error(`pauseWorkflow: unknown workflowId ${input.workflowId}`);
+    }
+    if (workflow.status !== "running") {
+      throw new Error(`pauseWorkflow: workflow ${input.workflowId} is ${workflow.status}, only running workflows can be paused`);
+    }
+    const tx = db.transaction(() => {
+      const current = getWorkflowById(db, input.workflowId);
+      if (!current || current.status !== "running")
+        return;
+      setWorkflowStatus(db, {
+        workflowId: input.workflowId,
+        status: "paused",
+        haltReason: null,
+        now: input.now
+      });
+      updateWorkflowContext(db, {
+        workflowId: input.workflowId,
+        patch: { pausedAt: input.now },
+        now: input.now
+      });
+    });
+    tx.immediate();
+    events.emit("workflow.paused", { workflowId: input.workflowId });
+    maybeCaptureQuiesceSnapshot({ workflowId: input.workflowId, now: input.now });
+  }
+  function resumeHaltedWorkflow(workflow, now) {
+    const tx = db.transaction(() => {
+      const others = listWorkflows(db, { collabId: workflow.collabId }).filter((w) => w.workflowId !== workflow.workflowId && (w.status === "running" || w.status === "paused"));
+      if (others.length > 0) {
+        throw new Error(`resumeWorkflow: another workflow is already active on collab ${workflow.collabId}`);
+      }
+      setWorkflowStatus(db, {
+        workflowId: workflow.workflowId,
+        status: "running",
+        haltReason: null,
+        now
+      });
+    });
+    tx.immediate();
+    events.emit("workflow.resumed", {
+      workflowId: workflow.workflowId,
+      phaseIndex: workflow.currentPhaseIndex
+    });
+  }
   function resumeWorkflow(input) {
     const workflow = getWorkflowById(db, input.workflowId);
     if (!workflow) {
       throw new Error(`resumeWorkflow: unknown workflowId ${input.workflowId}`);
     }
-    if (workflow.status === "canceled") {
-      throw new Error(`resumeWorkflow: workflow ${input.workflowId} is canceled and cannot be resumed`);
+    if (workflow.status === "halted") {
+      resumeHaltedWorkflow(workflow, input.now);
+      return;
     }
-    if (workflow.status !== "halted") {
-      throw new Error(`resumeWorkflow: workflow ${input.workflowId} is not halted (status=${workflow.status})`);
+    if (workflow.status !== "paused") {
+      throw new Error(`resumeWorkflow: workflow ${input.workflowId} is ${workflow.status}, only paused or halted workflows can be resumed`);
     }
+    const ref = workflow.workflowContext.pauseSnapshotRef ?? null;
+    const changedFiles = ref && deps.diffChangedFilesSinceSnapshot ? deps.diffChangedFilesSinceSnapshot(input.workflowId, ref) : [];
+    const notice = composeResumeNotice({
+      changedFiles,
+      message: input.message ?? null
+    });
     const tx = db.transaction(() => {
-      if (countRunningWorkflowsForCollab(db, workflow.collabId) > 0) {
-        throw new Error(`resumeWorkflow: another workflow is already running on collab ${workflow.collabId}`);
+      const others = listWorkflows(db, { collabId: workflow.collabId }).filter((w) => w.workflowId !== input.workflowId && (w.status === "running" || w.status === "paused"));
+      if (others.length > 0) {
+        throw new Error(`resumeWorkflow: another workflow is already active on collab ${workflow.collabId}`);
+      }
+      resetStrandedOrchestrationForWorkflow(db, input.workflowId);
+      let bakedIntoPending = false;
+      if (notice) {
+        bakedIntoPending = prependToPendingHandoffRequestText(db, {
+          workflowId: input.workflowId,
+          prefix: notice,
+          now: input.now
+        });
       }
       setWorkflowStatus(db, {
         workflowId: input.workflowId,
@@ -3097,6 +3291,15 @@ ${findingsText}`;
         haltReason: null,
         now: input.now
       });
+      updateWorkflowContext(db, {
+        workflowId: input.workflowId,
+        patch: {
+          resumeNotice: bakedIntoPending ? null : notice,
+          pausedAt: null,
+          pauseSnapshotRef: null
+        },
+        now: input.now
+      });
     });
     tx.immediate();
     events.emit("workflow.resumed", {
@@ -3197,6 +3400,9 @@ ${findingsText}`;
     beginPhaseRun,
     applyOrchestratorVerdict,
     haltWorkflow,
+    pauseWorkflow,
+    maybeCaptureQuiesceSnapshot,
+    consumeResumeNotice,
     resumeWorkflow,
     cancelWorkflow,
     getHandoffWithWorkflowMeta,
@@ -3212,8 +3418,32 @@ function buildEventId(kind, subjectId, timestamp) {
   return `evt_${kind}_${subjectId}_${normalizeTimestampForEventId(timestamp)}`;
 }
 function createControlService(db, events) {
-  const workflowControl = createWorkflowControl({ db, events });
+  const resolveWorkspaceRoot = (workflowId) => {
+    const wf = getWorkflowById(db, workflowId);
+    if (!wf)
+      return null;
+    return getCollab(db, wf.collabId)?.workspaceRoot ?? null;
+  };
+  const workflowControl = createWorkflowControl({
+    db,
+    events,
+    captureSnapshotRef: (workflowId) => {
+      const root = resolveWorkspaceRoot(workflowId);
+      return root ? captureWorkspaceSnapshotSync(root) : null;
+    },
+    diffChangedFilesSinceSnapshot: (workflowId, sinceRef) => {
+      const root = resolveWorkspaceRoot(workflowId);
+      return root ? diffChangedFilesSince(root, sinceRef) : [];
+    }
+  });
+  const isWorkflowDeliverySuspended = (handoffId) => {
+    const meta = workflowControl.getHandoffWithWorkflowMeta(handoffId);
+    if (!meta?.workflowId)
+      return false;
+    return workflowControl.getWorkflow(meta.workflowId)?.status === "paused";
+  };
   return Object.assign({
+    isWorkflowDeliverySuspended,
     startCollab(input) {
       const collab = collabSchema.parse({
         version: 1,
@@ -3841,6 +4071,8 @@ function createControlService(db, events) {
       return createRelayHandoffTxn(db, input);
     },
     acceptRelayHandoff(input) {
+      if (isWorkflowDeliverySuspended(input.handoffId))
+        return;
       return acceptRelayHandoffTxn(db, input);
     },
     deferRelayHandoff(input) {
@@ -3853,7 +4085,12 @@ function createControlService(db, events) {
       return markRelayHandoffStaleTxn(db, input);
     },
     handoffBackRelay(input) {
-      return handoffBackRelayTxn(db, input);
+      const result = handoffBackRelayTxn(db, input);
+      const meta = workflowControl.getHandoffWithWorkflowMeta(input.handoffId);
+      if (meta?.workflowId && workflowControl.getWorkflow(meta.workflowId)?.status === "paused") {
+        workflowControl.maybeCaptureQuiesceSnapshot({ workflowId: meta.workflowId, now: input.now });
+      }
+      return result;
     },
     failRelayHandoffOnDisconnect(input) {
       return failRelayHandoffOnDisconnectTxn(db, input);
@@ -3865,6 +4102,8 @@ function createControlService(db, events) {
       return queryLatestHandedBackHandoff(db, collabId);
     },
     claimRelayHandoffForOrchestration(input) {
+      if (isWorkflowDeliverySuspended(input.handoffId))
+        return null;
       return claimRelayHandoffForOrchestrationTxn(db, input);
     },
     listRelayHandoffsPendingOrchestration(collabId) {
@@ -4318,8 +4557,9 @@ CREATE TABLE IF NOT EXISTS workflows (
   updated_at TEXT NOT NULL
 );
 
+DROP INDEX IF EXISTS workflows_one_running_per_collab;
 CREATE UNIQUE INDEX IF NOT EXISTS workflows_one_running_per_collab
-  ON workflows(collab_id) WHERE status = 'running';
+  ON workflows(collab_id) WHERE status IN ('running', 'paused');
 
 CREATE TABLE IF NOT EXISTS workflow_phases (
   phase_run_id TEXT PRIMARY KEY,