@drisp/cli 0.5.26 → 0.5.28

package/dist/{chunk-73V7GXV6.js → chunk-2QV7YSX6.js}

@@ -1033,6 +1033,10 @@ function hasProjectWorkflow(projectDir) {
 }
 
 // src/core/workflows/types.ts
+var DEFAULT_MAX_TURN_TOKEN_COUNT = 13e4;
+var DEFAULT_NUDGE_CAP = 3;
+var DEFAULT_RETRY_CAP = 3;
+var DEFAULT_RETRY_BACKOFF_MS = 1e4;
 function pluginSpecRef(spec) {
   return typeof spec === "string" ? spec : spec.ref;
 }
@@ -1127,15 +1131,16 @@ function refreshPinnedWorkflowPlugins(workflow) {
 // src/core/workflows/registry.ts
 import fs9 from "fs";
 import os5 from "os";
-import path7 from "path";
+import path8 from "path";
 
 // src/core/workflows/builtins/index.ts
 import fs7 from "fs";
 import os4 from "os";
-import path5 from "path";
+import path6 from "path";
 
 // src/core/workflows/trackerReader.ts
 import fs6 from "fs";
+import path5 from "path";
 
 // src/core/workflows/templateVars.ts
 function substituteVariables(text, ctx) {
@@ -1158,6 +1163,7 @@ var DEFAULT_COMPLETION_MARKER = "<!-- WORKFLOW_COMPLETE -->";
 var DEFAULT_BLOCKED_MARKER = "<!-- WORKFLOW_BLOCKED";
 var DEFAULT_TRACKER_PATH = ".athena/{sessionId}/tracker.md";
 var TRACKER_SKELETON_MARKER = "<!-- TRACKER_SKELETON -->";
+var DEFAULT_TRACKER_TOKEN_BOUND = 8e3;
 var DEFAULT_CONTINUE_PROMPT = "Continue the task. Read the tracker at {trackerPath} for current progress. If the work is complete or blocked, the terminal marker must be the final non-empty line of the tracker; do not write any prose after it.";
 function readTracker(trackerPath) {
   try {
@@ -1209,12 +1215,114 @@ function parseTrackerState(content, markers = {}) {
     skeletonNotReplaced: content.includes(TRACKER_SKELETON_MARKER)
   };
 }
+function demoteTerminalMarkers(content, markers = {}) {
+  const completionMarker = markers.completionMarker ?? DEFAULT_COMPLETION_MARKER;
+  const blockedMarker = markers.blockedMarker ?? DEFAULT_BLOCKED_MARKER;
+  return content.split("\n").map((line) => {
+    const trimmed = line.trim();
+    if (trimmed === completionMarker) return "> _Prior Run ended: complete._";
+    if (isBlockedLine(trimmed, blockedMarker)) {
+      const reason = extractBlockedReason(trimmed, blockedMarker);
+      return reason ? `> _Prior Run ended: needed attention \u2014 ${reason}._` : "> _Prior Run ended: needed attention._";
+    }
+    return line;
+  }).join("\n");
+}
 function buildContinuePrompt(loop) {
   const template = loop.continuePrompt ?? DEFAULT_CONTINUE_PROMPT;
   return substituteVariables(template, {
     trackerPath: loop.trackerPath ?? DEFAULT_TRACKER_PATH
   });
 }
+function buildNudgePrompt(loop, opts) {
+  const completionMarker = loop.completionMarker ?? DEFAULT_COMPLETION_MARKER;
+  const blockedMarker = loop.blockedMarker ?? DEFAULT_BLOCKED_MARKER;
+  const trackerPath = loop.trackerPath ?? DEFAULT_TRACKER_PATH;
+  const bootstrapPreamble = opts?.skeletonNotReplaced ? `You stopped without writing the tracker at ${trackerPath} \u2014 it still contains the runner's skeleton. If you were asking the human a question, do not ask it in chat: write it to the tracker and declare ${blockedMarker}: <your question> --> as the final non-empty line. Otherwise replace the skeleton with the real plan and continue. ` : `You stopped without declaring how this workflow ended. If work remains, continue it now. `;
+  return bootstrapPreamble + `If everything is done and verified, write ${completionMarker} as the final non-empty line of the tracker at ${trackerPath}. If you cannot proceed without a human, write ${blockedMarker}: <reason> --> there instead. Do not stop again without either finishing the work or declaring one of these markers.`;
+}
+function estimateTokenCount(content) {
+  return Math.ceil(content.length / 4);
+}
+function buildTrackerSizeNudgeSuffix(trackerPath) {
+  const where = trackerPath ?? "the tracker";
+  return ` Separately: ${where} has crossed the ~8,000-token shedding backstop (ADR 0015 \xA73). Before continuing, cut the completed phases of the still-open unit out of the tracker and paste them verbatim into that unit's record under units/<slug>.md, leaving a pointer row behind \u2014 this is a nudge, not a requirement, so continue the work either way.`;
+}
+var UNITS_HEADING_RE = /^##\s+Units\s*$/;
+function splitTableRow(line) {
+  const trimmed = line.trim();
+  const withoutEdgePipes = trimmed.replace(/^\|/, "").replace(/\|$/, "");
+  return withoutEdgePipes.split("|").map((cell) => cell.trim());
+}
+function isSeparatorRow(cells) {
+  return cells.length > 0 && cells.every((cell) => /^:?-+:?$/.test(cell));
+}
+function parseUnitTable(content) {
+  const lines = content.split("\n");
+  const headingIndex = lines.findIndex(
+    (line) => UNITS_HEADING_RE.test(line.trim())
+  );
+  if (headingIndex === -1) return null;
+  let i = headingIndex + 1;
+  while (i < lines.length && lines[i].trim() === "") i++;
+  const tableLines = [];
+  while (i < lines.length) {
+    const trimmed = lines[i].trim();
+    if (!trimmed.startsWith("|")) break;
+    tableLines.push(trimmed);
+    i++;
+  }
+  if (tableLines.length < 2) return null;
+  const rows = [];
+  for (const line of tableLines.slice(1)) {
+    const cells = splitTableRow(line);
+    if (isSeparatorRow(cells)) continue;
+    if (cells.length !== 2) continue;
+    const [label, recordPath] = cells;
+    if (!label || !recordPath) continue;
+    rows.push({ label, recordPath });
+  }
+  return rows;
+}
+var FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/;
+function parseUnitRecordFrontmatter(content) {
+  const match = FRONTMATTER_RE.exec(content);
+  if (!match) return null;
+  const block = match[1];
+  const statusMatch = /^status:\s*(\S+)\s*$/m.exec(block);
+  const raw = statusMatch?.[1]?.trim().toLowerCase();
+  if (raw !== "open" && raw !== "closed") return null;
+  return { status: raw };
+}
+function projectTrackerTasks(trackerAbsPath) {
+  const content = readTracker(trackerAbsPath);
+  if (!content) return null;
+  const rows = parseUnitTable(content);
+  if (!rows) return null;
+  const baseDir = path5.dirname(trackerAbsPath);
+  const tasks = [];
+  for (const row of rows) {
+    const recordAbsPath = path5.resolve(baseDir, row.recordPath);
+    const relToBase = path5.relative(baseDir, recordAbsPath);
+    if (relToBase.startsWith("..") || path5.isAbsolute(relToBase)) continue;
+    let recordContent;
+    try {
+      recordContent = fs6.readFileSync(recordAbsPath, "utf-8");
+    } catch {
+      continue;
+    }
+    const frontmatter = parseUnitRecordFrontmatter(recordContent);
+    if (!frontmatter) continue;
+    const taskId = path5.basename(row.recordPath, path5.extname(row.recordPath));
+    if (!taskId) continue;
+    tasks.push({
+      taskId,
+      content: row.label,
+      status: frontmatter.status === "closed" ? "completed" : "pending"
+    });
+  }
+  return tasks;
+}
 
 // src/core/workflows/builtins/index.ts
 var DEFAULT_BLOCKED_CLOSED_MARKER = `${DEFAULT_BLOCKED_MARKER} -->`;
@@ -1274,14 +1382,14 @@ If you are blocked and cannot make further progress:
 4. Do not write any tracker content after the terminal marker
 `;
 function ensureSystemPromptFile() {
-  const dir = path5.join(
+  const dir = path6.join(
     os4.homedir(),
     ".config",
     "athena",
     "builtins",
     "default"
   );
-  const filePath = path5.join(dir, "system_prompt.md");
+  const filePath = path6.join(dir, "system_prompt.md");
   if (!fs7.existsSync(filePath) || fs7.readFileSync(filePath, "utf-8") !== SYSTEM_PROMPT) {
     fs7.mkdirSync(dir, { recursive: true });
     fs7.writeFileSync(filePath, SYSTEM_PROMPT, "utf-8");
@@ -1312,7 +1420,7 @@ function listBuiltinWorkflows() {
 
 // src/core/workflows/sourceMetadata.ts
 import fs8 from "fs";
-import path6 from "path";
+import path7 from "path";
 function legacyLocalToNew(legacyPath, legacyRepoDir) {
   const repoDir = legacyRepoDir ?? findMarketplaceRepoDir(legacyPath);
   if (!repoDir) {
@@ -1338,7 +1446,7 @@ function legacyLocalToNew(legacyPath, legacyRepoDir) {
   return { kind: "filesystem", path: legacyPath };
 }
 function readWorkflowSourceMetadata(workflowDir) {
-  const sourceFile = path6.join(workflowDir, "source.json");
+  const sourceFile = path7.join(workflowDir, "source.json");
   if (!fs8.existsSync(sourceFile)) return void 0;
   let raw;
   try {
@@ -1386,7 +1494,7 @@ function readWorkflowSourceMetadata(workflowDir) {
 function writeWorkflowSourceMetadata(workflowDir, metadata) {
   fs8.mkdirSync(workflowDir, { recursive: true });
   fs8.writeFileSync(
-    path6.join(workflowDir, "source.json"),
+    path7.join(workflowDir, "source.json"),
     JSON.stringify({ v: 2, ...metadata }),
     "utf-8"
   );
@@ -1394,18 +1502,18 @@ function writeWorkflowSourceMetadata(workflowDir, metadata) {
 
 // src/core/workflows/registry.ts
 function registryDir() {
-  return path7.join(os5.homedir(), ".config", "athena", "workflows");
+  return path8.join(os5.homedir(), ".config", "athena", "workflows");
 }
 function ensurePathWithinRoot(rootDir, targetPath, label) {
-  const relative = path7.relative(rootDir, targetPath);
-  if (relative === "" || !relative.startsWith("..") && !path7.isAbsolute(relative)) {
+  const relative = path8.relative(rootDir, targetPath);
+  if (relative === "" || !relative.startsWith("..") && !path8.isAbsolute(relative)) {
     return;
   }
   throw new Error(`${label} resolves outside the workflow root: ${targetPath}`);
 }
 function resolveWorkflow(name) {
-  const workflowDir = path7.join(registryDir(), name);
-  const workflowPath = path7.join(workflowDir, "workflow.json");
+  const workflowDir = path8.join(registryDir(), name);
+  const workflowPath = path8.join(workflowDir, "workflow.json");
   if (!fs9.existsSync(workflowPath)) {
     const builtin = resolveBuiltinWorkflow(name);
     if (builtin) {
@@ -1456,8 +1564,8 @@ function resolveWorkflow(name) {
     );
   }
   const workflowFile = raw["workflowFile"];
-  if (typeof workflowFile === "string" && !path7.isAbsolute(workflowFile)) {
-    const workflowFilePath = path7.resolve(workflowDir, workflowFile);
+  if (typeof workflowFile === "string" && !path8.isAbsolute(workflowFile)) {
+    const workflowFilePath = path8.resolve(workflowDir, workflowFile);
     if (!fs9.existsSync(workflowFilePath)) {
       throw new Error(
         `Invalid workflow.json: workflowFile "${workflowFile}" not found at ${workflowFilePath}`
@@ -1480,23 +1588,23 @@ function readWorkflowSource(sourcePath) {
 }
 function copyWorkflowFiles(sourcePath, destDir) {
   const { content, workflow } = readWorkflowSource(sourcePath);
-  const absoluteSourcePath = path7.resolve(sourcePath);
-  const sourceDir = path7.dirname(absoluteSourcePath);
-  const absoluteDestDir = path7.resolve(destDir);
+  const absoluteSourcePath = path8.resolve(sourcePath);
+  const sourceDir = path8.dirname(absoluteSourcePath);
+  const absoluteDestDir = path8.resolve(destDir);
   fs9.mkdirSync(absoluteDestDir, { recursive: true });
   fs9.writeFileSync(
-    path7.join(absoluteDestDir, "workflow.json"),
+    path8.join(absoluteDestDir, "workflow.json"),
     content,
     "utf-8"
   );
   const copyRelativeAsset = (assetPath) => {
-    if (!assetPath || path7.isAbsolute(assetPath)) return;
-    const sourceAssetPath = path7.resolve(sourceDir, assetPath);
+    if (!assetPath || path8.isAbsolute(assetPath)) return;
+    const sourceAssetPath = path8.resolve(sourceDir, assetPath);
     ensurePathWithinRoot(sourceDir, sourceAssetPath, "Workflow asset");
     if (!fs9.existsSync(sourceAssetPath)) return;
-    const destAssetPath = path7.resolve(absoluteDestDir, assetPath);
+    const destAssetPath = path8.resolve(absoluteDestDir, assetPath);
     ensurePathWithinRoot(absoluteDestDir, destAssetPath, "Workflow asset");
-    fs9.mkdirSync(path7.dirname(destAssetPath), { recursive: true });
+    fs9.mkdirSync(path8.dirname(destAssetPath), { recursive: true });
     fs9.copyFileSync(sourceAssetPath, destAssetPath);
   };
   const rawWorkflow = workflow;
@@ -1534,7 +1642,7 @@ function installWorkflowFromSource(source, name) {
       'Workflow has no "name" field. Provide --name to specify one.'
     );
   }
-  const destDir = path7.join(registryDir(), workflowName);
+  const destDir = path8.join(registryDir(), workflowName);
   copyWorkflowFiles(source.workflowPath, destDir);
   const metadata = toStoredMetadata(source);
   writeWorkflowSourceMetadata(destDir, metadata);
@@ -1579,7 +1687,7 @@ function reResolveFromMetadata(metadata, refresh = refreshMarketplaceRepo, onSel
   return { kind: "filesystem", workflowPath: metadata.path };
 }
 function updateWorkflow(name, refresh = refreshMarketplaceRepo, onSelfHeal) {
-  const workflowDir = path7.join(registryDir(), name);
+  const workflowDir = path8.join(registryDir(), name);
   const metadata = readWorkflowSourceMetadata(workflowDir);
   if (!metadata) {
     throw new Error(
@@ -1635,7 +1743,7 @@ function updateWorkflows(names) {
 function listWorkflows() {
   const dir = registryDir();
   const installed = fs9.existsSync(dir) ? fs9.readdirSync(dir, { withFileTypes: true }).filter(
-    (entry) => entry.isDirectory() && fs9.existsSync(path7.join(dir, entry.name, "workflow.json"))
+    (entry) => entry.isDirectory() && fs9.existsSync(path8.join(dir, entry.name, "workflow.json"))
   ).map((entry) => entry.name) : [];
   const builtins = listBuiltinWorkflows().filter(
     (name) => !installed.includes(name)
@@ -1643,7 +1751,7 @@ function listWorkflows() {
   return [...builtins, ...installed];
 }
 function removeWorkflow(name) {
-  const dir = path7.join(registryDir(), name);
+  const dir = path8.join(registryDir(), name);
   if (!fs9.existsSync(dir)) {
     throw new Error(`Workflow "${name}" not found.`);
   }
@@ -1682,10 +1790,10 @@ function compileWorkflowPlan(input) {
 
 // src/core/workflows/sessionPlan.ts
 import fs10 from "fs";
-import path8 from "path";
+import path9 from "path";
 
 // src/core/workflows/stateMachine.md
-var stateMachine_default = "# Stateless Turn Protocol\n\nYou run in a stateless loop. Each Turn is a fresh process with no memory of prior Turns. **The tracker file is your only continuity** \u2014 read it, work, write it. Assume interruption: the runner may kill a long Turn, your context may collapse under tool output, you may hit token limits mid-task. Anything not in the tracker is gone.\n\n## First action, every Turn\n\n1. Read the tracker at the configured path (default: `.athena/<session_id>/tracker.md`). The runner provides the session ID \u2014 do not invent one.\n2. If the tracker contains `<!-- TRACKER_SKELETON -->` \u2192 this is Turn 1, run [**Orient**](#orient-turn-1).\n3. Otherwise \u2192 this is a continuation, run [**Execute**](#execute-turn-2) from where the tracker says, not from the start of the flow.\n\nReading first prevents two failure modes that waste whole Turns: redoing work already done, or contradicting decisions a prior Turn made.\n\n## Tracker contract\n\nThe tracker must always answer four questions:\n\n1. What are we trying to accomplish?\n2. What has been done?\n3. What's left?\n4. What should the next Turn do first?\n\nA future Turn has no other context. If something isn't here, it doesn't exist. Section headings may vary by workflow, but these four answers must be explicit and easy to find.\n\n### Terminal markers\n\nDefault markers (workflows may override \u2014 use the markers configured for the active workflow):\n\n- `<!-- WORKFLOW_COMPLETE -->` \u2014 all work done and verified\n- `<!-- WORKFLOW_BLOCKED -->` or `<!-- WORKFLOW_BLOCKED: reason -->` \u2014 cannot proceed without external intervention\n\nRules:\n\n- Only the last non-empty line of the tracker is authoritative. Marker-like text in notes, examples, or quoted instructions earlier in the file is ignored.\n- When you write a terminal marker, it must be the final non-empty line of the tracker. Put every summary, status note, and next-step sentence before the marker. Never append prose after it.\n- The runner trusts markers unconditionally. A premature marker ends the loop with no automatic recovery \u2014 write one only when its criteria are fully met.\n- Include a concrete reason after `WORKFLOW_BLOCKED:` whenever possible; the bare form is still valid.\n\n## Phases\n\n### Orient (Turn 1)\n\n1. **Replace the skeleton immediately**, before any domain work. Even a three-line tracker (goal + \"orienting\") protects you if the Turn dies during setup.\n2. Identify and load the applicable workflow skills before doing domain work. If a workflow, plugin, or local skill table names a relevant skill, read it fully and follow it. Do not assume you already know the workflow's conventions, tool sequence, quality gates, or implementation details.\n3. Use a dedicated git worktree for repository-changing work. If you are not already inside a task-specific worktree, create or enter one before editing files, record its branch/path in the tracker, and continue there. Skip this only when the workflow explicitly forbids it or the task is read-only.\n4. Run the workflow's orientation steps exactly as written. These vary by domain \u2014 a test-writing workflow explores the product in a browser; a migration workflow audits the schema. The workflow defines what orientation means. Do not skip, reorder, reinterpret, or replace workflow steps with a generic approach unless the workflow explicitly allows it or the tracker records a concrete blocker that makes the written step impossible.\n5. Refine the tracker into a granular plan. Each task a concrete, verifiable unit of work, including verification steps (running checks, reviewing output) \u2014 not just implementation. Vague tasks (\"write tests\") cannot be meaningfully resumed by a future Turn that has no idea what they mean here.\n6. Record concrete observations \u2014 what you actually saw, not what you assumed. Wrong assumptions burn entire future Turns on rework.\n7. **Single-Turn requests still go through this phase.** If the entire request is satisfied in one Turn, write a minimal tracker (what was asked, what was done, the outcome) and append `<!-- WORKFLOW_COMPLETE -->`. Leaving the skeleton in place causes the runner to classify the Turn as a failure.\n\n### Execute (Turn 2+)\n\n- Work from where the tracker says, in the workflow's prescribed sequence. Not every Turn covers every step.\n- Be strict with workflow steps. Before starting each unit, identify the next required workflow step from the workflow document and tracker, follow it as written, and record completion or blockers against that step. Do not substitute your own process, collapse separate gates into one, or advance past an unchecked step.\n- Be strict with skills. Before each new activity, check the workflow, plugin metadata, local skill table, and tracker for relevant skills. Load the appropriate skill first, read it completely, and follow its instructions. If no skill applies, record that explicitly in the tracker before proceeding. Skills carry the implementation detail (scaffolding steps, locator rules, anti-patterns, code templates) that this protocol intentionally doesn't repeat.\n- Keep repository work inside the recorded git worktree. If a continuation Turn starts outside the recorded worktree, enter it before editing. If no worktree is recorded and edits are still required, create or enter one before proceeding.\n- Delegate heavy exploration or generation to subagents via the Task tool. Pass file paths, conventions, and concrete output expectations; tell them which skill to load. Respect the workflow's **delegation constraints** \u2014 some operations must run in the main agent because their output is proof, or because the main agent needs to interpret results in context.\n- Run quality gates in order. Do not skip \u2014 they exist because skipping cascades into rework. On a failing verdict, address the issues and re-run before proceeding. Respect the workflow's **retry limits**: repeated failure usually signals a deeper issue another retry won't fix.\n\n### End\n\n1. Tracker reflects all progress, discoveries, and blockers.\n2. Tracker says clearly what the next Turn should do first.\n3. If all work is verified: append the completion marker as the final non-empty line.\n4. If an unrecoverable blocker prevents progress: append the blocked marker as the final non-empty line, with a reason if you have one.\n\n## When to write the tracker\n\nWrite on **concrete triggers**, not on a vague sense of \"meaningful progress.\" The right cadence sits between every-tool-call (noisy log, wastes tokens) and end-of-Turn (everything lost if you die mid-task).\n\n- **Discrete unit done** \u2014 file written, fix applied, test run, gate passed. Reflect the new reality before starting the next unit.\n- **Insight learned** \u2014 API quirk, config field that turned out to matter, dead end ruled out, decision between two approaches. Insights are tracker-worthy even when no code changed; rediscovering them costs the next Turn a full re-exploration. The tracker is a knowledge ledger, not just a task log.\n- **About to do something risky or long-running** \u2014 subagent dispatch, long build, flaky external call, large refactor. Write _first_, then act. If the operation kills your Turn, only what's on disk survives.\n- **Plan changed** \u2014 task resequenced, new task surfaced, planned task no longer needed. Stale plans poison continuation Turns.\n- **You haven't written in a while** \u2014 if you can't remember the last update, you've gone too long. A short defensive update (\"doing X, last completed Y, next is Z\") beats nothing.\n\nEach update covers: what changed (work or knowledge), what's now next, and any caveat the next Turn needs. Don't transcribe tool calls \u2014 the tracker is a contract with your future self, not a replay log.\n\nThe cost of one extra tracker update is a few tokens. The cost of dying without one is a whole wasted Turn. Bias toward writing.\n\n## Task UI projection\n\nThe tracker is the durable source of truth. Your harness's task tools are a Turn-scoped UI projection of the same plan, shown to the user in their CLI widget. They do not survive process exit.\n\n{{TASK_TOOL_INSTRUCTIONS}}\n\n- **Turn 1, after orientation:** project the tracker's task plan into the task tools.\n- **Turn 2+, after reading the tracker:** recreate the projection from the tracker; do not assume task IDs from prior Turns still exist.\n- **During work:** update both \u2014 the task tools for immediate UI feedback, the tracker for persistence \u2014 in the same working phase.\n\n## Turn bounding\n\nEach fresh Turn starts with a clean context window and a compact tracker \u2014 effectively self-compaction. As you work, context fills with tool outputs and intermediate state. The longer you run, the more attention is spread across tokens that are no longer relevant, degrading precision on the work that matters now.\n\nWork a bounded chunk per Turn. Ending early and letting the next Turn pick up from a clean tracker is almost always better than pushing through with a heavy context. Natural checkpoints:\n\n- After a quality gate\n- After crossing multiple phases (explored \u2192 planned \u2192 wrote specs) \u2014 stop before pushing into the next\n- When your context is visibly heavy with tool output from earlier work\n\n## Quick reference\n\n- [ ] Read the tracker before doing anything else\n- [ ] Replace the skeleton immediately, even for single-Turn requests\n- [ ] Update on concrete triggers \u2014 unit done, insight learned, risky op pending, plan changed\n- [ ] Project the tracker plan into task tools at Turn start; keep both in sync as work lands\n- [ ] Follow the workflow steps as written; do not skip, reorder, or substitute your own process\n- [ ] Load the appropriate skill before each activity; do not rely on assumed knowledge\n- [ ] Use and record a dedicated git worktree for repository-changing work\n- [ ] Run quality gates in order; respect delegation constraints and retry limits\n- [ ] Write the completion marker only when all work is verified, and make it the final non-empty line\n- [ ] Checkpoint and end before context goes stale\n";
+var stateMachine_default = "# Turn Protocol\n\nYou run inside a managed workflow loop. **Run until the work is done.** The Dossier \u2014 `.athena/<session_id>/` \u2014 is your durable memory; `tracker.md` is your index into it: read it, work, write it as you go. Your conversation context usually survives between stops \u2014 the runner resumes your session rather than restarting it \u2014 but never rely on that: the runner may kill a long Turn, your session may be replaced at a context bound, the process may die mid-task. Anything not in the Dossier can be lost.\n\nTwo kinds of Turn exist, and you should know which you are in:\n\n- **A fresh Turn** \u2014 the first Turn of the run, or the Turn right after a Handover (the runner's context reset). You start with no memory of prior work; the tracker (and, after a Handover, the Handoff file) is all you have.\n- **A resumed Turn** \u2014 the runner continued your existing session with a new instruction (a corrective nudge, a retry after a transient failure, or a human's reply). Your context is intact; act on the new instruction and keep going.\n\n## First action, in a fresh Turn\n\n1. Read the tracker at the configured path (default: `.athena/<session_id>/tracker.md`). The runner provides the session ID \u2014 do not invent one.\n2. If the tracker contains `<!-- TRACKER_SKELETON -->` \u2192 this is Turn 1, run [**Orient**](#orient-turn-1).\n3. Otherwise \u2192 this is a continuation, run [**Execute**](#execute-continuation) from where the tracker says, not from the start of the flow.\n4. If the runner's prompt names a Handoff file, read it too \u2014 it's mandatory alongside the tracker: it carries the in-flight context the tracker never checkpointed. Before any domain work, fold whatever in it is still durable into the tracker (or the open unit's record, if it's been shed) \u2014 the Handoff is a one-time relay, not a permanent Dossier file, so anything worth keeping has to land in `tracker.md`/`units/<slug>.md` now or it is lost once the Handoff falls off the chain. Then read whatever the tracker's fifth question names (see [Tracker contract](#tracker-contract)) \u2014 that, the tracker, and any named Handoff file are your complete required reading. Do not redo completed work or re-litigate decisions any of them record.\n\nReading first prevents two failure modes that waste whole Turns: redoing work already done, or contradicting decisions a prior Turn made.\n\nIn a resumed Turn, your context is already loaded \u2014 skim the tracker only if you have any doubt it still matches reality, then continue.\n\n## Tracker contract\n\nThe tracker must always answer five questions:\n\n1. What are we trying to accomplish?\n2. What has been done?\n3. What's left?\n4. What should the next Turn do first?\n5. What else, beyond this file, must the next Turn read to have full context?\n\nA fresh Turn has no other context. If something isn't here or in a file question 5 names, it doesn't exist. Section headings may vary by workflow, but these five answers must be explicit and easy to find. Question 5 is the tracker's pointer into the rest of the Dossier (see [The Dossier](#the-dossier)): on a single-file Run its honest answer is \"nothing else\"; once anything has been shed, it names exactly which files, so a fresh Turn's opening read stays small even when the Dossier has grown.\n\n### Terminal markers\n\nDefault markers (workflows may override \u2014 use the markers configured for the active workflow):\n\n- `<!-- WORKFLOW_COMPLETE -->` \u2014 all work done and verified\n- `<!-- WORKFLOW_BLOCKED -->` or `<!-- WORKFLOW_BLOCKED: reason -->` \u2014 you need a human: a question only they can answer, or an external blocker only they can clear\n\nRules:\n\n- Only the last non-empty line of the tracker is authoritative. Marker-like text in notes, examples, or quoted instructions earlier in the file is ignored.\n- When you write a terminal marker, it must be the final non-empty line of the tracker. Put every summary, status note, and next-step sentence before the marker. Never append prose after it.\n- The runner trusts markers unconditionally. A premature `WORKFLOW_COMPLETE` ends the run with no automatic recovery \u2014 write it only when its criteria are fully met.\n- Include a concrete reason after `WORKFLOW_BLOCKED:` whenever possible \u2014 it is what the human sees when deciding how to answer you. Put the full question there.\n\n## The Dossier\n\n`.athena/<session_id>/` is the Dossier: the tracker plus everywhere it can shed cold detail once shedding earns its keep.\n\n```\ntracker.md       state: index, open loops, next action, terminal marker\nunits/<slug>.md   journal: contract, problem, design + rationale, build state, gate evidence\norientation.md    cross-unit knowledge, revised in place\nhandoff/NNN.md    episodic distillation, written at a Handover (chain, newest is mandatory reading)\n```\n\n**On most Runs the Dossier never grows past `tracker.md` itself** \u2014 one file, no ceremony, no extra directories, nothing below this line to act on. Nothing here changes how a short, single-unit Run works.\n\nA **unit** is a bounded piece of the plan that reaches its own closed state while the Run keeps going \u2014 one issue in a multi-issue epic, one phase of a larger goal. A Run with only one unit never closes a unit while another stays open, so it can never trip the first shed trigger below.\n\n### When to shed\n\nTwo triggers, both structural. A single-unit Run can only ever reach the second, and only once that unit has outgrown the bound:\n\n- **A unit closes while another is still open.** Cut that unit's whole detail out of the tracker now, before starting the next one.\n- **The tracker crosses ~8,000 tokens** (roughly 32,000 characters \u2014 a token is about 4 characters at this codebase's measured rate). This is a backstop for one long single unit, not a target to design toward \u2014 shed the completed phases of the still-open unit.\n\n### How to shed\n\nShedding is three positive acts on one whole named `##` section \u2014 never a summary, never a partial move:\n\n1. **Cut** the section, verbatim, out of `tracker.md`.\n2. **Paste** it, verbatim, into `units/<slug>.md` (create the file on that unit's first shed).\n3. **Pointer** \u2014 leave one index row in the tracker's unit table with a relative path to where the detail went.\n\nContent is demoted, never deleted. If you find yourself rewording or condensing while moving text, stop \u2014 that is not shedding, that is exactly where fidelity leaks.\n\n### The unit table\n\nThe tracker's unit table is the index the runner reads to keep the CLI's own task list in sync with your plan \u2014 it is parsed by tooling, so its shape is fixed, not free-form prose. Keep it under a `## Units` heading, as a GFM table with exactly two columns:\n\n```\n## Units\n\n| Unit                  | Record                     |\n| ---------------------- | --------------------------- |\n| Add the size nudge     | units/size-nudge.md         |\n| Wire up task projection | units/task-projection.md   |\n```\n\n- **Unit** \u2014 a short human-readable label for the unit (what step 3 of [How to shed](#how-to-shed) points at).\n- **Record** \u2014 the path to that unit's `units/<slug>.md`, relative to the tracker's own directory.\n\nOne row per unit that has been shed; units still fully inline in the tracker (never shed) don't need a row. A row whose Record file is missing, unreadable, or malformed is simply skipped by the runner \u2014 never guessed at, never a failure (see the next section). Malformed rows in an otherwise-fine table don't invalidate the rest of the table.\n\nEach `units/<slug>.md` record opens with a small YAML frontmatter block the runner reads to know the unit's state:\n\n```\n---\nstatus: open\ngates: []\n---\n\n<the shed section content, verbatim>\n```\n\n- `status` \u2014 `open` or `closed`, exactly (case-insensitive). Any other value, or a missing `status` key, means the runner treats the whole record as unparseable for projection purposes \u2014 it still exists as your durable journal, it just doesn't surface in the task list.\n- `gates` \u2014 reserved for future gate-evidence tracking; not read by anything yet. Leave it present but empty, or omit it \u2014 either is fine today.\n\nThis frontmatter is the only structured part of a unit record; everything after the closing `---` is free-form prose exactly like the rest of the Dossier.\n\n### Parsing is best-effort, never a gate\n\nThe unit table and unit-record frontmatter exist so the runner can mirror your plan into the harness's own task list (see [Task UI projection](#task-ui-projection)) and, separately, so it can nudge you when the tracker grows past its size backstop. Both are conveniences layered on top of the Dossier, not requirements on it:\n\n- A missing table, an extra column, a typo'd status, a unit record that fails to parse \u2014 none of it fails your Turn, and none of it is worth stopping to fix for the runner's sake. The runner silently skips whatever it can't parse and, at most, folds a size nudge into your next prompt.\n- Never restructure the tracker or a unit record just to make automated parsing happy at the expense of the content itself. If the table and the prose disagree, the prose (what you actually did) is the truth.\n\n### orientation.md\n\nKnowledge that spans more than one unit lives here, revised in place instead of appended to \u2014 the one Dossier surface you edit rather than move things into. Two sections with different rules:\n\n- **Established** \u2014 decisions. Never decay; only explicitly superseded (\"we chose X over Y because Z \u2014 superseded 2026-09-03: \u2026\").\n- **Observed** \u2014 facts carrying a `file.ts:123`-style anchor. Revalidate the anchor before relying on it; code moves.\n\nA correction is an edit to the existing entry, not a new capitalized warning stacked on top of stale text.\n\n## Run until done; declare when blocked\n\nThe loop's contract with you:\n\n- **Do not stop early.** There is no checkpoint budget and no reason to end a Turn \"to be safe\" \u2014 context refresh is the runner's job, not yours. When your context approaches its bound the runner performs a **Handover**: your conversation is distilled into a Handoff file and a fresh session picks up seamlessly from it plus the tracker. You will not see this happen; just keep the tracker current so nothing is lost.\n- **Stopping without a marker is a mistake**, not a signal. The runner reads it as a premature stop and resumes you with a corrective prompt; repeated markerless stops without tracker progress escalate to a human. Never stop as a way of asking \"should I continue?\" \u2014 the answer is always to continue or to declare.\n- **Need a human? Declare it.** Write `WORKFLOW_BLOCKED: <your question or blocker>` as the tracker's final non-empty line and end. The run suspends until a human replies; their reply resumes your session with the answer. This is the only correct way to wait for a person \u2014 an interactive question asked into an unattended run cannot be answered.\n- Transient infrastructure failures are not yours to manage: the runner retries them by resuming your session. Just make sure the tracker reflects reality before risky operations.\n\n## Phases\n\n### Orient (Turn 1)\n\n1. **Replace the skeleton immediately**, before any domain work. Even a three-line tracker (goal + \"orienting\") protects you if the Turn dies during setup.\n2. Identify and load the applicable workflow skills before doing domain work. If a workflow, plugin, or local skill table names a relevant skill, read it fully and follow it. Do not assume you already know the workflow's conventions, tool sequence, quality gates, or implementation details.\n3. Use a dedicated git worktree for repository-changing work. If you are not already inside a task-specific worktree, create or enter one before editing files, record its branch/path in the tracker, and continue there. Skip this only when the workflow explicitly forbids it or the task is read-only.\n4. Run the workflow's orientation steps exactly as written. These vary by domain \u2014 a test-writing workflow explores the product in a browser; a migration workflow audits the schema. The workflow defines what orientation means. Do not skip, reorder, reinterpret, or replace workflow steps with a generic approach unless the workflow explicitly allows it or the tracker records a concrete blocker that makes the written step impossible.\n5. Refine the tracker into a granular plan. Each task a concrete, verifiable unit of work, including verification steps (running checks, reviewing output) \u2014 not just implementation. Vague tasks (\"write tests\") cannot be meaningfully resumed by a future Turn that has no idea what they mean here.\n6. Record concrete observations \u2014 what you actually saw, not what you assumed. Wrong assumptions burn entire future Turns on rework.\n7. **Single-Turn requests still go through this phase.** If the entire request is satisfied quickly, write a minimal tracker (what was asked, what was done, the outcome) and append `<!-- WORKFLOW_COMPLETE -->`. Leaving the skeleton in place gets you nudged \u2014 the runner cannot trust work it can't read from the tracker \u2014 and repeated stops with an untouched skeleton escalate to a human.\n\n### Execute (continuation)\n\n- Work from where the tracker says, in the workflow's prescribed sequence, and keep going until the work is done or a declared blocker stops you.\n- Be strict with workflow steps. Before starting each unit, identify the next required workflow step from the workflow document and tracker, follow it as written, and record completion or blockers against that step. Do not substitute your own process, collapse separate gates into one, or advance past an unchecked step.\n- Be strict with skills. Before each new activity, check the workflow, plugin metadata, local skill table, and tracker for relevant skills. Load the appropriate skill first, read it completely, and follow its instructions. If no skill applies, record that explicitly in the tracker before proceeding. Skills carry the implementation detail (scaffolding steps, locator rules, anti-patterns, code templates) that this protocol intentionally doesn't repeat.\n- Keep repository work inside the recorded git worktree. If a continuation starts outside the recorded worktree, enter it before editing. If no worktree is recorded and edits are still required, create or enter one before proceeding.\n- Delegate heavy exploration or generation to subagents via the Task tool. Pass file paths, conventions, and concrete output expectations; tell them which skill to load. Respect the workflow's **delegation constraints** \u2014 some operations must run in the main agent because their output is proof, or because the main agent needs to interpret results in context.\n- Run quality gates in order. Do not skip \u2014 they exist because skipping cascades into rework. On a failing verdict, address the issues and re-run before proceeding. Respect the workflow's **retry limits**: repeated failure usually signals a deeper issue another retry won't fix.\n\n### End\n\nYou end the run only by declaring:\n\n1. Tracker reflects all progress, discoveries, and blockers.\n2. Tracker says clearly what a fresh Turn would need to do first (a Handover can happen at any time).\n3. If all work is verified: append the completion marker as the final non-empty line.\n4. If a human is needed to proceed: append the blocked marker as the final non-empty line, with the question or blocker spelled out as the reason.\n\n## When to write the tracker\n\nWrite on **concrete triggers**, not on a vague sense of \"meaningful progress.\" The right cadence sits between every-tool-call (noisy log, wastes tokens) and end-of-run (everything lost if you die mid-task). This matters more, not less, now that Turns run long: the tracker (plus the Handoff file at a Handover) is what carries a killed or reset session.\n\n- **Discrete unit done** \u2014 file written, fix applied, test run, gate passed. Reflect the new reality before starting the next unit. If another unit is still open, this is also a shed trigger (see [The Dossier](#the-dossier)): cut this unit's detail into `units/<slug>.md` before you start the next one.\n- **Insight learned** \u2014 API quirk, config field that turned out to matter, dead end ruled out, decision between two approaches. Insights are tracker-worthy even when no code changed; rediscovering them costs a future Turn a full re-exploration. The tracker is a knowledge ledger, not just a task log. Insight that spans more than one unit belongs in `orientation.md`, not the tracker.\n- **About to do something risky or long-running** \u2014 subagent dispatch, long build, flaky external call, large refactor. Write _first_, then act. If the operation kills your Turn, only what's on disk survives.\n- **Plan changed** \u2014 task resequenced, new task surfaced, planned task no longer needed. Stale plans poison continuation Turns.\n- **The tracker crosses the ~8,000-token backstop** \u2014 shed the completed phases of the still-open unit into its `units/<slug>.md` record now, mid-unit; don't wait for it to close.\n- **You haven't written in a while** \u2014 if you can't remember the last update, you've gone too long. A short defensive update (\"doing X, last completed Y, next is Z\") beats nothing.\n\nEach update covers: what changed (work or knowledge), what's now next, and any caveat a future Turn needs. Don't transcribe tool calls \u2014 the tracker is a contract with your future self, not a replay log.\n\nThe cost of one extra tracker update is a few tokens. The cost of dying without one is rework. Bias toward writing.\n\n## Task UI projection\n\nThe tracker is the durable source of truth. Your harness's task tools are a session-scoped UI projection of the same plan, shown to the user in their CLI widget. They do not survive process exit.\n\n{{TASK_TOOL_INSTRUCTIONS}}\n\n- **Turn 1, after orientation:** project the tracker's task plan into the task tools.\n- **In a fresh continuation (e.g. after a Handover):** recreate the projection from the tracker; do not assume task IDs from prior sessions still exist.\n- **During work:** update both \u2014 the task tools for immediate UI feedback, the tracker for persistence \u2014 in the same working phase.\n\nSeparately, the runner independently re-derives a task list from the tracker's [unit table](#the-unit-table) and each unit record's frontmatter after every Turn, and mirrors it into the CLI's own task display. This is a backstop, not a substitute for the above \u2014 it only ever reaches `open`/`closed`, so keep calling the task tools yourself for anything finer-grained. It never blocks or fails a Turn: an unparseable table or record just means that Turn's mirror is skipped, exactly as described in [Parsing is best-effort, never a gate](#parsing-is-best-effort-never-a-gate).\n\n## Quick reference\n\n- [ ] Fresh Turn: read the tracker (and any named Handoff file) before doing anything else\n- [ ] Replace the skeleton immediately, even for single-Turn requests\n- [ ] Run until the work is done \u2014 do not stop at checkpoints, and never stop as a way of asking permission to continue\n- [ ] Need a human? Declare it: `WORKFLOW_BLOCKED: <question>` as the final non-empty line, then end\n- [ ] Update the tracker on concrete triggers \u2014 unit done, insight learned, risky op pending, plan changed\n- [ ] Shed a unit's detail into `units/<slug>.md` the moment it closes while another stays open, or the tracker crosses ~8,000 tokens \u2014 cut, paste, pointer, never summarize\n- [ ] Keep the unit table and each shed record's `status: open|closed` frontmatter current \u2014 the runner mirrors them into the task list and skips silently on any parse miss\n- [ ] After a Handover: fold the Handoff's durable content into the tracker or open unit record before any domain work\n- [ ] Project the tracker plan into task tools at session start; keep both in sync as work lands\n- [ ] Follow the workflow steps as written; do not skip, reorder, or substitute your own process\n- [ ] Load the appropriate skill before each activity; do not rely on assumed knowledge\n- [ ] Use and record a dedicated git worktree for repository-changing work\n- [ ] Run quality gates in order; respect delegation constraints and retry limits\n- [ ] Write the completion marker only when all work is verified, and make it the final non-empty line\n";
 
 // src/core/workflows/stateMachine.ts
 function buildTaskToolInstructions(harness) {
@@ -1725,7 +1833,7 @@ function readWorkflowOverride(projectDir, workflow, sessionId, trackerPath, harn
   if (!workflow?.workflowFile) {
     return { workflowOverride: void 0, warnings: [] };
   }
-  const resolvedPath = path8.isAbsolute(workflow.workflowFile) ? workflow.workflowFile : path8.resolve(projectDir, workflow.workflowFile);
+  const resolvedPath = path9.isAbsolute(workflow.workflowFile) ? workflow.workflowFile : path9.resolve(projectDir, workflow.workflowFile);
   let workflowContent;
   try {
     workflowContent = fs10.readFileSync(resolvedPath, "utf-8");
@@ -1742,8 +1850,8 @@ function readWorkflowOverride(projectDir, workflow, sessionId, trackerPath, harn
     sessionId,
     trackerPath: trackerPath ?? void 0
   });
-  const workflowDir = path8.dirname(resolvedPath);
-  const composedPath = path8.join(workflowDir, ".composed-system-prompt.md");
+  const workflowDir = path9.dirname(resolvedPath);
+  const composedPath = path9.join(workflowDir, ".composed-system-prompt.md");
   fs10.writeFileSync(composedPath, composed, "utf-8");
   return {
     workflowOverride: {
@@ -1771,7 +1879,7 @@ function resolveTrackerPath(input) {
     return null;
   }
   const promptPath = input.sessionId ? rawPath.replaceAll("{sessionId}", input.sessionId) : rawPath;
-  const absolutePath = path8.isAbsolute(promptPath) ? promptPath : path8.resolve(input.projectDir, promptPath);
+  const absolutePath = path9.isAbsolute(promptPath) ? promptPath : path9.resolve(input.projectDir, promptPath);
   return {
     absolutePath,
     promptPath
@@ -1816,14 +1924,13 @@ function prepareWorkflowTurn(state, input) {
 import { useCallback, useEffect, useRef, useState } from "react";
 
 // src/core/workflows/workflowRunner.ts
-import crypto from "crypto";
+import crypto2 from "crypto";
 import fs12 from "fs";
-import path9 from "path";
+import path10 from "path";
 
 // src/core/workflows/terminalOutcome.ts
 import fs11 from "fs";
 var MISSING_TRACKER_MESSAGE = "the tracker file went missing during the run \u2014 the workflow can no longer verify progress";
-var SKELETON_NOT_REPLACED_MESSAGE = "tracker skeleton was never replaced \u2014 Claude did not bootstrap the tracker";
 var MISPLACED_TERMINAL_MARKER_MESSAGE = "terminal workflow marker is not the final non-empty line of the tracker; move all summary text above the marker";
 function resolveTurnOutcome(input) {
   const { trackerPath, loop, iteration } = input;
@@ -1835,13 +1942,6 @@ function resolveTurnOutcome(input) {
     };
   }
   const tracker = parseTrackerState(readTracker(trackerPath), loop);
-  if (tracker.skeletonNotReplaced) {
-    return {
-      kind: "stop",
-      status: "failed",
-      stopReason: SKELETON_NOT_REPLACED_MESSAGE
-    };
-  }
   if (tracker.misplacedTerminalMarker) {
     return {
       kind: "stop",
@@ -1853,14 +1953,640 @@ function resolveTurnOutcome(input) {
     return { kind: "stop", status: "completed" };
   }
   if (tracker.blocked) {
-    return { kind: "stop", status: "blocked", stopReason: tracker.blockedReason };
+    return {
+      kind: "suspend",
+      status: "awaiting_attention",
+      stopReason: tracker.blockedReason ? `agent declared WORKFLOW_BLOCKED: ${tracker.blockedReason}` : "agent declared WORKFLOW_BLOCKED"
+    };
   }
   if (iteration >= loop.maxIterations) {
-    return { kind: "stop", status: "exhausted" };
+    return {
+      kind: "suspend",
+      status: "awaiting_attention",
+      stopReason: `iteration ceiling reached: ${loop.maxIterations} iteration${loop.maxIterations === 1 ? "" : "s"} (maxIterations) used without a terminal marker`
+    };
   }
   return { kind: "continue" };
 }
 
+// src/core/runtime/failureTaxonomy.ts
+var RULES = [
+  // ── hard, specific ──
+  {
+    pattern: /\b401\b|authentication_error|unauthorized|invalid.?api.?key|api key.*(invalid|revoked|expired)|oauth token.*(expired|revoked)|not.?logged.?in|please.*log ?in/i,
+    classification: { kind: "hard", code: "auth" }
+  },
+  {
+    pattern: /\b402\b|billing|credit balance|insufficient.?(funds|credits?|quota)|payment required|plan limit/i,
+    classification: { kind: "hard", code: "billing" }
+  },
+  {
+    pattern: /model.{0,20}not.?(found|supported|available)|no such model/i,
+    classification: { kind: "hard", code: "model_not_found" }
+  },
+  // ── transient ──
+  {
+    pattern: /\b429\b|rate.?limit/i,
+    classification: { kind: "transient", code: "rate_limit" }
+  },
+  {
+    pattern: /\b529\b|overloaded/i,
+    classification: { kind: "transient", code: "overloaded" }
+  },
+  {
+    pattern: /\b(500|502|503|504)\b|internal server error|bad gateway|service unavailable|gateway timeout|server_error|api_error/i,
+    classification: { kind: "transient", code: "server_error" }
+  },
+  {
+    pattern: /econnrefused|econnreset|etimedout|enotfound|eai_again|epipe|socket hang up|fetch failed|network error|connection (error|closed|refused|reset)/i,
+    classification: { kind: "transient", code: "network" }
+  },
+  // ── hard, generic (after the specific hard + transient rules) ──
+  {
+    pattern: /\b400\b|invalid_request_error|invalid request|malformed request/i,
+    classification: { kind: "hard", code: "invalid_request" }
+  }
+];
+function classifyTurnFailure(input) {
+  const haystack = [input.errorMessage, input.lastStderr, input.lastMessage].filter((part) => typeof part === "string").join("\n");
+  for (const rule of RULES) {
+    if (rule.pattern.test(haystack)) {
+      return rule.classification;
+    }
+  }
+  return { kind: "hard", code: "unclassified" };
+}
+
+// src/core/workflows/runMachine.ts
+import crypto from "crypto";
+function hashTrackerContent(content) {
+  return crypto.createHash("sha256").update(content).digest("hex");
+}
+function buildHandoverSeedPrompt(handoffPath, trackerPath) {
+  return `A Handover occurred: the previous agent session reached its context bound and was distilled into a Handoff file. Read the Handoff file at ${handoffPath}` + (trackerPath ? ` and the tracker at ${trackerPath}` : "") + `. Before any domain work: fold whatever durable content the Handoff file records into the tracker` + (trackerPath ? ` at ${trackerPath}` : "") + ` and the open unit's record (ADR 0015 \xA78) \u2014 that fold-in is itself the tracker's next edit. Only once it is written should you continue the work from exactly where it stands. Do not redo completed work, and do not re-litigate decisions the Handoff file records.`;
+}
+function buildWakePrompt(reply, trackerPath) {
+  return `This workflow run was suspended awaiting a human; it is now resumed. The human replied:
+
+${reply}
+
+` + (trackerPath ? `Read the tracker at ${trackerPath} for the task and its current state, apply the reply, and continue the workflow. ` : `Apply the reply and continue the workflow. `) + `Keep the tracker current as you work \u2014 if it still contains the runner's skeleton, replace it while orienting \u2014 and end by declaring a terminal marker as usual.`;
+}
+function buildFailureDetail(event) {
+  const parts = [];
+  if (event.errorMessage) {
+    parts.push(event.errorMessage);
+  } else if (event.exitCode !== null) {
+    parts.push(`Process exited with code ${event.exitCode}`);
+  }
+  if (event.lastStderr) {
+    parts.push(event.lastStderr);
+  } else if (event.streamMessage) {
+    parts.push(event.streamMessage.slice(0, 300));
+  }
+  return parts.join(": ") || "Turn failed";
+}
+function createInitialRun(cfg, opts) {
+  if (opts.waking && opts.resumedMemory) {
+    return {
+      phase: {
+        kind: "awaiting_attention",
+        stopReason: opts.awaitingAttentionStopReason ?? ""
+      },
+      memory: opts.resumedMemory
+    };
+  }
+  if (opts.resumedMemory) {
+    return {
+      phase: {
+        kind: "backing_off",
+        ms: 0,
+        resume: {
+          kind: "turn",
+          prompt: opts.resumedMemory.lastStopPrompt,
+          continuation: opts.resumedMemory.lastStopContinuation
+        }
+      },
+      memory: opts.resumedMemory
+    };
+  }
+  const continuation = opts.initialContinuation ?? { mode: "fresh" };
+  const iteration = 1;
+  const prepared = prepareWorkflowTurn(cfg.workflowState, {
+    prompt: cfg.initialPrompt,
+    iteration,
+    configOverride: void 0
+  });
+  const prompt = opts.waking ? buildWakePrompt(cfg.initialPrompt, cfg.trackerPromptPath) : prepared.prompt;
+  return {
+    phase: {
+      kind: "turn_in_flight",
+      prompt,
+      continuation,
+      configOverride: prepared.configOverride
+    },
+    memory: {
+      iteration,
+      nudgeStreak: 0,
+      retryStreak: 0,
+      lastTrackerHash: null,
+      lastStopPrompt: prompt,
+      lastStopContinuation: continuation,
+      lastHandoffSizeBytes: null
+    }
+  };
+}
+function handleTurnInFlight(phase, memory, event, cfg) {
+  if (event.cancelled) {
+    return { phase: { kind: "cancelled" }, memory, actions: [{ type: "persist" }] };
+  }
+  if (event.handoverRequestHandle !== null) {
+    return {
+      phase: {
+        kind: "handing_over",
+        handle: event.handoverRequestHandle,
+        // Reuse this Turn's own prepared configOverride (the same object
+        // the primary `start_turn` action used) rather than recomputing —
+        // matches workflowRunner.ts's original `prepared.configOverride`
+        // reuse at the fork call site exactly. Stored on the phase too
+        // (not just the action) so a transient-retry (§8) can re-issue the
+        // fork with the same override.
+        configOverride: phase.configOverride
+      },
+      memory,
+      actions: [
+        {
+          type: "start_fork_turn",
+          handle: event.handoverRequestHandle,
+          configOverride: phase.configOverride
+        }
+      ]
+    };
+  }
+  if (event.suspension) {
+    return {
+      phase: { kind: "awaiting_attention", stopReason: event.suspension.reason },
+      memory,
+      actions: [{ type: "persist" }]
+    };
+  }
+  const failed = event.hasError || event.exitCode !== null && event.exitCode !== 0;
+  if (failed) {
+    const failureDetail = buildFailureDetail(event);
+    if (cfg.loop?.enabled) {
+      const classification = classifyTurnFailure({
+        errorMessage: event.errorMessage,
+        lastStderr: event.stderrTail ?? event.lastStderr,
+        lastMessage: event.streamMessage
+      });
+      if (classification.kind === "transient") {
+        const retryStreak = memory.retryStreak + 1;
+        const retryCap = cfg.loop.retryCap ?? DEFAULT_RETRY_CAP;
+        if (retryStreak > retryCap) {
+          return {
+            phase: {
+              kind: "awaiting_attention",
+              stopReason: `retry cap reached: ${retryCap} transient failure${retryCap === 1 ? "" : "s"} (retryCap); last (${classification.code}): ${failureDetail}`
+            },
+            memory: { ...memory, retryStreak },
+            actions: [{ type: "persist" }]
+          };
+        }
+        const backoffBase = cfg.loop.retryBackoffMs ?? DEFAULT_RETRY_BACKOFF_MS;
+        const ms = backoffBase * 2 ** (retryStreak - 1);
+        return {
+          phase: {
+            kind: "backing_off",
+            ms,
+            resume: {
+              kind: "turn",
+              prompt: phase.prompt,
+              continuation: phase.continuation
+            }
+          },
+          memory: { ...memory, retryStreak },
+          actions: [{ type: "wait", ms }]
+        };
+      }
+      if (phase.continuation.mode === "resume") {
+        const continuation2 = { mode: "fresh" };
+        const prepared2 = prepareWorkflowTurn(cfg.workflowState, {
+          prompt: cfg.initialPrompt,
+          iteration: memory.iteration,
+          configOverride: void 0
+        });
+        return {
+          phase: {
+            kind: "turn_in_flight",
+            prompt: prepared2.prompt,
+            continuation: continuation2,
+            configOverride: prepared2.configOverride
+          },
+          memory: {
+            ...memory,
+            lastStopPrompt: prepared2.prompt,
+            lastStopContinuation: continuation2
+          },
+          actions: [
+            { type: "persist" },
+            {
+              type: "start_turn",
+              prompt: prepared2.prompt,
+              continuation: continuation2,
+              configOverride: prepared2.configOverride
+            }
+          ]
+        };
+      }
+      return {
+        phase: {
+          kind: "awaiting_attention",
+          stopReason: `hard failure (${classification.code}): ${failureDetail} \u2014 not retried; needs a human`
+        },
+        memory,
+        actions: [{ type: "persist" }]
+      };
+    }
+    return {
+      phase: { kind: "failed", stopReason: failureDetail },
+      memory,
+      actions: [{ type: "persist" }]
+    };
+  }
+  const memoryAfterSuccess = { ...memory, retryStreak: 0 };
+  if (event.transportBroken) {
+    return {
+      phase: {
+        kind: "failed",
+        stopReason: `Hook transport broken: observed a tool use in the Claude stream but received no PreToolUse events.`
+      },
+      memory: memoryAfterSuccess,
+      actions: [{ type: "persist" }]
+    };
+  }
+  if (!cfg.loop?.enabled) {
+    return {
+      phase: { kind: "completed" },
+      memory: memoryAfterSuccess,
+      actions: [{ type: "persist" }]
+    };
+  }
+  const loop = cfg.loop;
+  if (event.outcome && (event.outcome.kind === "stop" || event.outcome.kind === "suspend")) {
+    const outcome = event.outcome;
+    const nextPhase = outcome.status === "completed" ? { kind: "completed" } : outcome.status === "failed" ? { kind: "failed", stopReason: outcome.stopReason } : {
+      kind: "awaiting_attention",
+      stopReason: outcome.stopReason ?? "stopped"
+    };
+    return {
+      phase: nextPhase,
+      memory: memoryAfterSuccess,
+      actions: [{ type: "persist" }]
+    };
+  }
+  const trackerHash = hashTrackerContent(event.trackerContent);
+  let nudgeStreak = memoryAfterSuccess.nudgeStreak;
+  if (trackerHash !== memoryAfterSuccess.lastTrackerHash) {
+    nudgeStreak = 0;
+  }
+  const memoryWithHash = {
+    ...memoryAfterSuccess,
+    lastTrackerHash: trackerHash,
+    nudgeStreak
+  };
+  const sizeNudgeSuffix = estimateTokenCount(event.trackerContent) > DEFAULT_TRACKER_TOKEN_BOUND ? buildTrackerSizeNudgeSuffix(cfg.trackerPromptPath) : "";
+  if (event.adapterSessionId) {
+    const nextNudgeStreak = nudgeStreak + 1;
+    const nudgeCap = loop.nudgeCap ?? DEFAULT_NUDGE_CAP;
+    if (nextNudgeStreak > nudgeCap) {
+      return {
+        phase: {
+          kind: "awaiting_attention",
+          stopReason: `nudge cap reached: ${nudgeCap} nudge${nudgeCap === 1 ? "" : "s"} (nudgeCap) without tracker progress or a terminal marker`
+        },
+        memory: { ...memoryWithHash, nudgeStreak: nextNudgeStreak },
+        actions: [{ type: "persist" }]
+      };
+    }
+    const promptOverride = buildNudgePrompt(
+      { ...loop, trackerPath: cfg.trackerPromptPath ?? loop.trackerPath },
+      {
+        skeletonNotReplaced: event.trackerContent.includes(
+          TRACKER_SKELETON_MARKER
+        )
+      }
+    ) + sizeNudgeSuffix;
+    const nextIteration2 = memoryWithHash.iteration + 1;
+    const continuation2 = {
+      mode: "resume",
+      handle: event.adapterSessionId
+    };
+    const prepared2 = prepareWorkflowTurn(cfg.workflowState, {
+      prompt: cfg.initialPrompt,
+      iteration: nextIteration2,
+      configOverride: void 0
+    });
+    return {
+      phase: {
+        kind: "turn_in_flight",
+        prompt: promptOverride,
+        continuation: continuation2,
+        configOverride: prepared2.configOverride
+      },
+      memory: {
+        ...memoryWithHash,
+        nudgeStreak: nextNudgeStreak,
+        iteration: nextIteration2,
+        lastStopPrompt: promptOverride,
+        lastStopContinuation: continuation2
+      },
+      actions: [
+        { type: "persist" },
+        { type: "notify_iteration_complete" },
+        {
+          type: "start_turn",
+          prompt: promptOverride,
+          continuation: continuation2,
+          configOverride: prepared2.configOverride
+        }
+      ]
+    };
+  }
+  const nextIteration = memoryWithHash.iteration + 1;
+  const continuation = { mode: "fresh" };
+  const prepared = prepareWorkflowTurn(cfg.workflowState, {
+    prompt: cfg.initialPrompt,
+    iteration: nextIteration,
+    configOverride: void 0
+  });
+  const promptWithSizeNudge = prepared.prompt + sizeNudgeSuffix;
+  return {
+    phase: {
+      kind: "turn_in_flight",
+      prompt: promptWithSizeNudge,
+      continuation,
+      configOverride: prepared.configOverride
+    },
+    memory: {
+      ...memoryWithHash,
+      iteration: nextIteration,
+      lastStopPrompt: promptWithSizeNudge,
+      lastStopContinuation: continuation
+    },
+    actions: [
+      { type: "persist" },
+      { type: "notify_iteration_complete" },
+      {
+        type: "start_turn",
+        prompt: promptWithSizeNudge,
+        continuation,
+        configOverride: prepared.configOverride
+      }
+    ]
+  };
+}
+function handleBackingOff(phase, memory, event, cfg) {
+  if (event.cancelled) {
+    return { phase: { kind: "cancelled" }, memory, actions: [{ type: "persist" }] };
+  }
+  if (phase.resume.kind === "fork") {
+    return {
+      phase: {
+        kind: "handing_over",
+        handle: phase.resume.handle,
+        configOverride: phase.resume.configOverride,
+        retried: true
+      },
+      memory,
+      actions: [
+        {
+          type: "start_fork_turn",
+          handle: phase.resume.handle,
+          configOverride: phase.resume.configOverride
+        }
+      ]
+    };
+  }
+  const continuation = event.adapterSessionId ? { mode: "resume", handle: event.adapterSessionId } : phase.resume.continuation;
+  const prompt = continuation.mode === "fresh" ? phase.resume.prompt : cfg.loop ? buildContinuePrompt(cfg.loop) : "Continue.";
+  const prepared = prepareWorkflowTurn(cfg.workflowState, {
+    prompt: cfg.initialPrompt,
+    iteration: memory.iteration,
+    configOverride: void 0
+  });
+  return {
+    phase: {
+      kind: "turn_in_flight",
+      prompt,
+      continuation,
+      configOverride: prepared.configOverride
+    },
+    memory: {
+      ...memory,
+      lastStopPrompt: prompt,
+      lastStopContinuation: continuation
+    },
+    actions: [
+      { type: "persist" },
+      {
+        type: "start_turn",
+        prompt,
+        continuation,
+        configOverride: prepared.configOverride
+      }
+    ]
+  };
+}
+function handleHandingOver(phase, memory, event, cfg) {
+  if (event.cancelled) {
+    return { phase: { kind: "cancelled" }, memory, actions: [{ type: "persist" }] };
+  }
+  const nextIteration = memory.iteration + 1;
+  if (event.ok) {
+    const continuation2 = { mode: "fresh" };
+    const seedPrompt = buildHandoverSeedPrompt(
+      event.handoffPath,
+      cfg.trackerAbsPath ?? void 0
+    );
+    const prepared2 = prepareWorkflowTurn(cfg.workflowState, {
+      prompt: cfg.initialPrompt,
+      iteration: nextIteration,
+      configOverride: void 0
+    });
+    return {
+      phase: {
+        kind: "turn_in_flight",
+        prompt: seedPrompt,
+        continuation: continuation2,
+        configOverride: prepared2.configOverride
+      },
+      memory: {
+        ...memory,
+        iteration: nextIteration,
+        lastStopPrompt: seedPrompt,
+        lastStopContinuation: continuation2,
+        lastHandoffSizeBytes: event.handoffSizeBytes
+      },
+      actions: [
+        { type: "purge_handoffs" },
+        { type: "persist" },
+        {
+          type: "start_turn",
+          prompt: seedPrompt,
+          continuation: continuation2,
+          configOverride: prepared2.configOverride
+        }
+      ]
+    };
+  }
+  if (event.transient && !phase.retried) {
+    const ms = cfg.loop?.retryBackoffMs ?? DEFAULT_RETRY_BACKOFF_MS;
+    return {
+      phase: {
+        kind: "backing_off",
+        ms,
+        resume: {
+          kind: "fork",
+          handle: phase.handle,
+          configOverride: phase.configOverride
+        }
+      },
+      memory,
+      actions: [{ type: "wait", ms }]
+    };
+  }
+  const continuation = { mode: "resume", handle: phase.handle };
+  const prepared = prepareWorkflowTurn(cfg.workflowState, {
+    prompt: cfg.initialPrompt,
+    iteration: nextIteration,
+    configOverride: void 0
+  });
+  return {
+    phase: {
+      kind: "turn_in_flight",
+      prompt: prepared.prompt,
+      continuation,
+      configOverride: prepared.configOverride
+    },
+    memory: {
+      ...memory,
+      iteration: nextIteration,
+      lastStopPrompt: prepared.prompt,
+      lastStopContinuation: continuation
+    },
+    actions: [
+      { type: "degrade_handover", handle: phase.handle },
+      { type: "persist" },
+      {
+        type: "start_turn",
+        prompt: prepared.prompt,
+        continuation,
+        configOverride: prepared.configOverride
+      }
+    ]
+  };
+}
+function handleAwaitingAttention(memory, event, cfg) {
+  const nextIteration = memory.iteration + 1;
+  const prompt = buildWakePrompt(cfg.initialPrompt, cfg.trackerPromptPath);
+  const prepared = prepareWorkflowTurn(cfg.workflowState, {
+    prompt: cfg.initialPrompt,
+    iteration: nextIteration,
+    configOverride: void 0
+  });
+  return {
+    phase: {
+      kind: "turn_in_flight",
+      prompt,
+      continuation: event.continuation,
+      configOverride: prepared.configOverride
+    },
+    memory: {
+      ...memory,
+      iteration: nextIteration,
+      lastStopPrompt: prompt,
+      lastStopContinuation: event.continuation
+    },
+    actions: [
+      { type: "persist" },
+      {
+        type: "start_turn",
+        prompt,
+        continuation: event.continuation,
+        configOverride: prepared.configOverride
+      }
+    ]
+  };
+}
+function step(phase, memory, event, cfg) {
+  switch (phase.kind) {
+    case "turn_in_flight": {
+      if (event.type !== "turn_finished") {
+        throw new Error(
+          `runMachine: phase 'turn_in_flight' received unexpected event '${event.type}'`
+        );
+      }
+      return handleTurnInFlight(phase, memory, event, cfg);
+    }
+    case "backing_off": {
+      if (event.type !== "backoff_elapsed") {
+        throw new Error(
+          `runMachine: phase 'backing_off' received unexpected event '${event.type}'`
+        );
+      }
+      return handleBackingOff(phase, memory, event, cfg);
+    }
+    case "handing_over": {
+      if (event.type !== "fork_finished") {
+        throw new Error(
+          `runMachine: phase 'handing_over' received unexpected event '${event.type}'`
+        );
+      }
+      return handleHandingOver(phase, memory, event, cfg);
+    }
+    case "awaiting_attention": {
+      if (event.type !== "woken") {
+        throw new Error(
+          `runMachine: phase 'awaiting_attention' received unexpected event '${event.type}'`
+        );
+      }
+      return handleAwaitingAttention(memory, event, cfg);
+    }
+    case "completed":
+    case "failed":
+    case "cancelled": {
+      throw new Error(
+        `runMachine: step() called on terminal phase '${phase.kind}'`
+      );
+    }
+    default: {
+      const _exhaustive = phase;
+      throw new Error(
+        `runMachine: step() called on unrecognized phase kind '${_exhaustive.kind}'`
+      );
+    }
+  }
+}
+function serializeRunMemory(memory) {
+  return JSON.stringify(memory);
+}
+function deserializeRunMemory(json) {
+  if (!json) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const candidate = parsed;
+  const continuation = candidate.lastStopContinuation;
+  if (typeof candidate.iteration !== "number" || typeof candidate.nudgeStreak !== "number" || typeof candidate.retryStreak !== "number" || candidate.lastTrackerHash !== null && typeof candidate.lastTrackerHash !== "string" || typeof candidate.lastStopPrompt !== "string" || !continuation || typeof continuation.mode !== "string") {
+    return null;
+  }
+  return candidate;
+}
+
 // src/core/workflows/workflowRunner.ts
 var NULL_TOKENS = {
   input: null,
@@ -1881,7 +2607,7 @@ var TRACKER_SKELETON_TEMPLATE = `${TRACKER_SKELETON_MARKER}
 ---
 
 > This tracker was created by the runner. Update it as you work.
-> See the Stateless Turn Protocol for tracker conventions.
+> See the Turn Protocol for tracker conventions.
 
 ## Status
 
@@ -1895,6 +2621,33 @@ _To be created during orientation._
 
 _No progress yet._
 `;
+function openRunSection(trackerPath, opts) {
+  let existing;
+  try {
+    existing = fs12.readFileSync(trackerPath, "utf-8");
+  } catch {
+    return;
+  }
+  const banner = `
+
+---
+
+## New Workflow Run
+
+**Run**: ${opts.runId}
+**Goal**: ${opts.goal}
+
+_Sections above belong to earlier Workflow Runs in this Athena Session._
+`;
+  try {
+    fs12.writeFileSync(
+      trackerPath,
+      demoteTerminalMarkers(existing.trimEnd(), opts.markers) + banner,
+      "utf-8"
+    );
+  } catch {
+  }
+}
 function mergeTokens(base, next) {
   const input = (base.input ?? 0) + (next.input ?? 0);
   const output = (base.output ?? 0) + (next.output ?? 0);
@@ -1917,21 +2670,73 @@ function mergeTokens(base, next) {
     contextWindowSize: next.contextWindowSize ?? base.contextWindowSize
   };
 }
+function buildHandoffInvocationPrompt(handoffPath) {
+  return `Invoke the handoff skill to write a Handoff file to ${handoffPath}. Do nothing else: no code changes, no tracker updates \u2014 only the Handoff file.`;
+}
+async function delayWithCancel(ms, isCancelled) {
+  const slice = 250;
+  for (let waited = 0; waited < ms && !isCancelled(); waited += slice) {
+    await new Promise(
+      (resolve) => setTimeout(resolve, Math.min(slice, ms - waited))
+    );
+  }
+}
+var HANDOFF_DIR_NAME = "handoff";
+var HANDOFF_RETAIN = 2;
+function listHandoffSeqs(dir) {
+  try {
+    return fs12.readdirSync(dir).map((name) => /^(\d{3})\.md$/.exec(name)?.[1]).filter((seq) => seq !== void 0).map(Number).sort((a, b) => a - b);
+  } catch {
+    return [];
+  }
+}
+function handoffPathFor(dir, seq) {
+  return path10.join(dir, `${String(seq).padStart(3, "0")}.md`);
+}
+function nextHandoffPath(dir) {
+  const next = (listHandoffSeqs(dir).at(-1) ?? 0) + 1;
+  fs12.mkdirSync(dir, { recursive: true });
+  return handoffPathFor(dir, next);
+}
+function purgeHandoffs(dir, keep) {
+  const seqs = listHandoffSeqs(dir);
+  for (const seq of seqs.slice(0, Math.max(0, seqs.length - keep))) {
+    try {
+      fs12.rmSync(handoffPathFor(dir, seq), { force: true });
+    } catch {
+    }
+  }
+}
 function defaultCreateTracker(trackerPath, content) {
-  fs12.mkdirSync(path9.dirname(trackerPath), { recursive: true });
+  fs12.mkdirSync(path10.dirname(trackerPath), { recursive: true });
   try {
     fs12.writeFileSync(trackerPath, content, { encoding: "utf-8", flag: "wx" });
   } catch (e) {
     if (e.code !== "EEXIST") throw e;
   }
 }
+function isTerminalPhase(phase) {
+  return phase.kind === "awaiting_attention" || phase.kind === "completed" || phase.kind === "failed" || phase.kind === "cancelled";
+}
+function terminalPhaseToStatus(phase) {
+  switch (phase.kind) {
+    case "awaiting_attention":
+      return { status: "awaiting_attention", stopReason: phase.stopReason };
+    case "completed":
+      return { status: "completed" };
+    case "failed":
+      return { status: "failed", stopReason: phase.stopReason };
+    case "cancelled":
+      return { status: "cancelled" };
+  }
+}
 function createWorkflowRunner(input) {
-  const runId = crypto.randomUUID();
+  const runId = input.resumeRunId ?? crypto2.randomUUID();
   let cancelled = false;
   let status = "running";
-  let iterations = 0;
   let cumulativeTokens = { ...NULL_TOKENS };
   let stopReason;
+  let memory;
   const trackerResolved = resolveTrackerPath({
     projectDir: input.projectDir,
     sessionId: input.sessionId,
@@ -1940,15 +2745,18 @@ function createWorkflowRunner(input) {
   const trackerAbsPath = trackerResolved?.absolutePath ?? null;
   const trackerPromptPath = trackerResolved?.promptPath;
   function snapshot() {
+    const adapterSessionId = input.currentAdapterSessionId?.() ?? void 0;
     return {
       runId,
       sessionId: input.sessionId,
       workflowName: input.workflow?.name,
-      iteration: iterations,
+      iteration: memory?.iteration ?? 0,
       maxIterations: input.workflow?.loop?.maxIterations ?? 1,
       status,
       stopReason,
-      trackerPath: trackerPromptPath
+      trackerPath: trackerPromptPath,
+      ...adapterSessionId ? { adapterSessionId } : {},
+      ...memory ? { runMemoryJson: serializeRunMemory(memory) } : {}
     };
   }
   function persist() {
@@ -1957,6 +2765,16 @@ function createWorkflowRunner(input) {
     } catch {
     }
   }
+  function handoffDirFor() {
+    return path10.join(
+      trackerAbsPath ? path10.dirname(trackerAbsPath) : path10.resolve(
+        input.projectDir,
+        ".athena",
+        input.sessionId || "session"
+      ),
+      HANDOFF_DIR_NAME
+    );
+  }
   const result = (async () => {
     await Promise.resolve();
     if (trackerAbsPath && input.workflow?.loop?.enabled) {
@@ -1966,7 +2784,18 @@ function createWorkflowRunner(input) {
         input: input.prompt
       });
       const write = input.createTracker ?? defaultCreateTracker;
+      const trackerExisted = fs12.existsSync(trackerAbsPath);
       write(trackerAbsPath, content);
+      if (trackerExisted && !input.resumeRunId) {
+        openRunSection(trackerAbsPath, {
+          runId,
+          goal: input.prompt,
+          markers: {
+            completionMarker: input.workflow.loop.completionMarker,
+            blockedMarker: input.workflow.loop.blockedMarker
+          }
+        });
+      }
     }
     persist();
     const workflowState = createWorkflowRunState({
@@ -1975,80 +2804,271 @@ function createWorkflowRunner(input) {
       workflow: input.workflow,
       harness: input.harness
     });
-    let nextContinuation = input.initialContinuation ?? {
-      mode: "fresh"
-    };
     const loop = input.workflow?.loop;
-    while (!cancelled) {
-      iterations++;
-      const prepared = prepareWorkflowTurn(workflowState, {
-        prompt: input.prompt,
-        iteration: iterations,
-        configOverride: void 0
-      });
+    const cfg = {
+      workflowState,
+      initialPrompt: input.prompt,
+      loop,
+      trackerAbsPath,
+      trackerPromptPath
+    };
+    const initial = createInitialRun(cfg, {
+      initialContinuation: input.initialContinuation,
+      waking: !!(input.resumeRunId && loop?.enabled),
+      resumedMemory: input.resumedRunMemory,
+      awaitingAttentionStopReason: input.resumedStopReason
+    });
+    let phase = initial.phase;
+    memory = initial.memory;
+    async function performStartTurn(prompt, continuation, configOverride) {
       const turnResult = await input.startTurn({
-        prompt: prepared.prompt,
-        continuation: nextContinuation,
-        configOverride: prepared.configOverride
+        prompt,
+        continuation,
+        configOverride
       });
       if (cancelled) {
-        status = "cancelled";
-        persist();
-        break;
+        return {
+          type: "turn_finished",
+          cancelled: true,
+          hasError: false,
+          exitCode: null,
+          streamMessage: null,
+          transportBroken: false,
+          handoverRequestHandle: null,
+          suspension: null,
+          adapterSessionId: null,
+          outcome: null,
+          trackerContent: ""
+        };
       }
       cumulativeTokens = mergeTokens(cumulativeTokens, turnResult.tokens);
-      if (turnResult.error || turnResult.exitCode !== null && turnResult.exitCode !== 0) {
-        status = "failed";
-        const parts = [];
-        if (turnResult.error?.message) {
-          parts.push(turnResult.error.message);
-        } else if (turnResult.exitCode !== null) {
-          parts.push(`Process exited with code ${turnResult.exitCode}`);
-        }
-        if (turnResult.lastStderr) {
-          parts.push(turnResult.lastStderr);
-        }
-        stopReason = parts.join(": ") || "Turn failed";
-        persist();
-        break;
+      const handoverRequest = input.handover?.takeRequest() ?? null;
+      if (handoverRequest) {
+        return {
+          type: "turn_finished",
+          cancelled: false,
+          hasError: false,
+          exitCode: null,
+          streamMessage: null,
+          transportBroken: false,
+          handoverRequestHandle: handoverRequest.handle,
+          suspension: null,
+          adapterSessionId: null,
+          outcome: null,
+          trackerContent: ""
+        };
       }
-      const transport = turnResult.diagnostics?.transport;
-      if (transport && transport.streamToolUses > 0 && transport.preToolUseEvents === 0) {
-        status = "failed";
-        stopReason = `Hook transport broken: observed ${transport.streamToolUses} tool use(s) in Claude stream but received no PreToolUse events.`;
-        persist();
-        break;
+      const suspension = input.checkSuspension?.() ?? null;
+      if (suspension) {
+        return {
+          type: "turn_finished",
+          cancelled: false,
+          hasError: false,
+          exitCode: null,
+          streamMessage: null,
+          transportBroken: false,
+          handoverRequestHandle: null,
+          suspension,
+          adapterSessionId: null,
+          outcome: null,
+          trackerContent: ""
+        };
       }
-      if (!loop?.enabled) {
-        status = "completed";
-        persist();
-        break;
+      const adapterSessionId = input.currentAdapterSessionId?.() ?? null;
+      const hasError = !!turnResult.error;
+      const failed = hasError || turnResult.exitCode !== null && turnResult.exitCode !== 0;
+      if (failed) {
+        return {
+          type: "turn_finished",
+          cancelled: false,
+          hasError,
+          errorMessage: turnResult.error?.message,
+          exitCode: turnResult.exitCode,
+          lastStderr: turnResult.lastStderr,
+          stderrTail: turnResult.stderrTail,
+          streamMessage: turnResult.streamMessage,
+          transportBroken: false,
+          handoverRequestHandle: null,
+          suspension: null,
+          adapterSessionId,
+          outcome: null,
+          trackerContent: ""
+        };
       }
-      if (trackerAbsPath) {
-        const outcome = resolveTurnOutcome({
+      const transport = turnResult.diagnostics?.transport;
+      const transportBroken = !!(transport && transport.streamToolUses > 0 && transport.preToolUseEvents === 0);
+      let trackerContent = "";
+      let outcome = null;
+      if (!transportBroken && loop?.enabled && trackerAbsPath) {
+        trackerContent = readTracker(trackerAbsPath);
+        outcome = resolveTurnOutcome({
           trackerPath: trackerAbsPath,
           loop,
-          iteration: iterations
+          iteration: memory.iteration
+        });
+      }
+      return {
+        type: "turn_finished",
+        cancelled: false,
+        hasError: false,
+        exitCode: turnResult.exitCode,
+        streamMessage: turnResult.streamMessage,
+        transportBroken,
+        handoverRequestHandle: null,
+        suspension: null,
+        adapterSessionId,
+        outcome,
+        trackerContent
+      };
+    }
+    async function performForkTurn(handle, configOverride) {
+      const handoffDir = handoffDirFor();
+      const handoffAbsPath = nextHandoffPath(handoffDir);
+      input.handover?.onForkStateChange?.(true);
+      let forkOk = false;
+      let transient = false;
+      try {
+        const forkResult = await input.startTurn({
+          prompt: buildHandoffInvocationPrompt(handoffAbsPath),
+          continuation: { mode: "resume", handle },
+          configOverride: { ...configOverride, forkSession: true }
         });
-        if (outcome.kind === "stop") {
-          status = outcome.status;
-          stopReason = outcome.stopReason;
-          persist();
-          break;
+        cumulativeTokens = mergeTokens(cumulativeTokens, forkResult.tokens);
+        forkOk = !forkResult.error && (forkResult.exitCode === null || forkResult.exitCode === 0) && fs12.existsSync(handoffAbsPath);
+        if (!forkOk) {
+          transient = classifyTurnFailure({
+            errorMessage: forkResult.error?.message,
+            lastStderr: forkResult.stderrTail ?? forkResult.lastStderr,
+            lastMessage: forkResult.streamMessage
+          }).kind === "transient";
         }
+      } catch (e) {
+        forkOk = false;
+        transient = classifyTurnFailure({
+          errorMessage: e instanceof Error ? e.message : String(e)
+        }).kind === "transient";
+      } finally {
+        input.handover?.onForkStateChange?.(false);
       }
-      persist();
-      input.onIterationComplete?.(snapshot());
-      nextContinuation = { mode: "fresh" };
+      let handoffSizeBytes = null;
+      if (forkOk) {
+        try {
+          handoffSizeBytes = fs12.statSync(handoffAbsPath).size;
+        } catch {
+          handoffSizeBytes = null;
+        }
+      }
+      return {
+        type: "fork_finished",
+        ok: forkOk,
+        cancelled,
+        handoffPath: handoffAbsPath,
+        handoffSizeBytes,
+        transient
+      };
     }
-    if (cancelled && status === "running") {
-      status = "cancelled";
-      persist();
+    async function performWait(ms) {
+      await delayWithCancel(ms, () => cancelled);
+      if (cancelled) {
+        return {
+          type: "backoff_elapsed",
+          cancelled: true,
+          adapterSessionId: null
+        };
+      }
+      const adapterSessionId = input.currentAdapterSessionId?.() ?? null;
+      return { type: "backoff_elapsed", cancelled: false, adapterSessionId };
+    }
+    function isKickoffAction(action) {
+      return action.type === "start_turn" || action.type === "start_fork_turn" || action.type === "wait";
+    }
+    async function runActions(actions) {
+      let kickoff = null;
+      for (const action of actions) {
+        if (isKickoffAction(action)) {
+          kickoff = action;
+          continue;
+        }
+        switch (action.type) {
+          case "persist":
+            persist();
+            if (trackerAbsPath && input.projectTasks) {
+              try {
+                const tasks = projectTrackerTasks(trackerAbsPath);
+                if (tasks) input.projectTasks(tasks);
+              } catch {
+              }
+            }
+            break;
+          case "notify_iteration_complete":
+            input.onIterationComplete?.(snapshot());
+            break;
+          case "purge_handoffs":
+            purgeHandoffs(handoffDirFor(), HANDOFF_RETAIN);
+            break;
+          case "degrade_handover":
+            input.handover?.onDegraded?.(action.handle);
+            break;
+        }
+      }
+      if (!kickoff) return null;
+      switch (kickoff.type) {
+        case "start_turn":
+          return performStartTurn(
+            kickoff.prompt,
+            kickoff.continuation,
+            kickoff.configOverride
+          );
+        case "start_fork_turn":
+          return performForkTurn(kickoff.handle, kickoff.configOverride);
+        case "wait":
+          return performWait(kickoff.ms);
+        default:
+          return null;
+      }
+    }
+    let bootstrapActions;
+    if (phase.kind === "awaiting_attention") {
+      const wokenEvent = {
+        type: "woken",
+        continuation: input.initialContinuation ?? { mode: "fresh" }
+      };
+      const stepResult = step(phase, memory, wokenEvent, cfg);
+      phase = stepResult.phase;
+      memory = stepResult.memory;
+      bootstrapActions = stepResult.actions;
+    } else if (phase.kind === "turn_in_flight") {
+      bootstrapActions = [
+        {
+          type: "start_turn",
+          prompt: phase.prompt,
+          continuation: phase.continuation,
+          configOverride: phase.configOverride
+        }
+      ];
+    } else if (phase.kind === "backing_off") {
+      bootstrapActions = [{ type: "wait", ms: phase.ms }];
+    } else {
+      bootstrapActions = [];
+    }
+    let pendingEvent = await runActions(bootstrapActions);
+    while (pendingEvent) {
+      const stepResult = step(phase, memory, pendingEvent, cfg);
+      phase = stepResult.phase;
+      memory = stepResult.memory;
+      if (isTerminalPhase(phase)) {
+        const terminal = terminalPhaseToStatus(phase);
+        status = terminal.status;
+        stopReason = terminal.stopReason;
+        await runActions(stepResult.actions);
+        break;
+      }
+      pendingEvent = await runActions(stepResult.actions);
     }
     return {
       runId,
       status,
-      iterations,
+      iterations: memory.iteration,
       stopReason,
       tokens: cumulativeTokens
     };
@@ -2171,12 +3191,12 @@ function useWorkflowSessionController(base, input) {
 
 // src/infra/plugins/mcpOptions.ts
 import fs13 from "fs";
-import path10 from "path";
+import path11 from "path";
 function collectMcpServersWithOptions(pluginDirs) {
   const result = [];
   const seen = /* @__PURE__ */ new Set();
   for (const dir of pluginDirs) {
-    const mcpPath = path10.join(dir, ".mcp.json");
+    const mcpPath = path11.join(dir, ".mcp.json");
     if (!fs13.existsSync(mcpPath)) {
       continue;
     }
@@ -2195,6 +3215,8 @@ function collectMcpServersWithOptions(pluginDirs) {
 }
 
 export {
+  DEFAULT_MAX_TURN_TOKEN_COUNT,
+  deserializeRunMemory,
   createWorkflowRunner,
   useWorkflowSessionController,
   isMarketplaceRef,
@@ -2226,4 +3248,4 @@ export {
   compileWorkflowPlan,
   collectMcpServersWithOptions
 };
-//# sourceMappingURL=chunk-73V7GXV6.js.map
+//# sourceMappingURL=chunk-2QV7YSX6.js.map