gsd-pi 2.80.0 → 2.81.0

package/src/resources/extensions/gsd/commands-handlers.ts

@@ -26,6 +26,15 @@ import { isAutoActive, checkRemoteAutoSession } from "./auto.js";
 import { getAutoWorktreePath } from "./auto-worktree.js";
 import { currentDirectoryRoot, projectRoot } from "./commands/context.js";
 import { loadPrompt } from "./prompt-loader.js";
+import {
+  buildDoctorHealIssuePayload,
+  buildDoctorHealSummary,
+  buildWorkflowDispatchContent,
+} from "./workflow-protocol.js";
+import {
+  restoreGsdWorkflowTools,
+  scopeGsdWorkflowToolsForDispatch,
+} from "./bootstrap/register-hooks.js";
 
 const UPDATE_REGISTRY_URL = "https://registry.npmjs.org/gsd-pi/latest";
 const UPDATE_FETCH_TIMEOUT_MS = 5000;
@@ -72,18 +81,23 @@ export function dispatchDoctorHeal(pi: ExtensionAPI, scope: string | undefined,
   const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(gsdHome(), "agent", "GSD-WORKFLOW.md");
   const workflow = readFileSync(workflowPath, "utf-8");
   const prompt = loadPrompt("doctor-heal", {
-    doctorSummary: reportText,
-    structuredIssues,
+    doctorSummary: buildDoctorHealSummary(reportText),
+    structuredIssues: buildDoctorHealIssuePayload(structuredIssues),
     scopeLabel: scope ?? "active milestone / blocking scope",
     doctorCommandSuffix: scope ? ` ${scope}` : "",
   });
 
-  const content = `Read the following GSD workflow protocol and execute exactly.\n\n${workflow}\n\n## Your Task\n\n${prompt}`;
+  const content = buildWorkflowDispatchContent({ workflow, workflowPath, task: prompt });
+  const savedTools = scopeGsdWorkflowToolsForDispatch(pi);
 
-  pi.sendMessage(
-    { customType: "gsd-doctor-heal", content, display: false },
-    { triggerTurn: true },
-  );
+  try {
+    pi.sendMessage(
+      { customType: "gsd-doctor-heal", content, display: false },
+      { triggerTurn: true },
+    );
+  } finally {
+    restoreGsdWorkflowTools(pi, savedTools);
+  }
 }
 
 /** Parse doctor command args into structured flags and positionals (pure, no I/O). */
@@ -258,15 +272,20 @@ export async function handleTriage(ctx: ExtensionCommandContext, pi: ExtensionAP
 
   const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(gsdHome(), "agent", "GSD-WORKFLOW.md");
   const workflow = readFileSync(workflowPath, "utf-8");
+  const savedTools = scopeGsdWorkflowToolsForDispatch(pi);
 
-  pi.sendMessage(
-    {
-      customType: "gsd-triage",
-      content: `Read the following GSD workflow protocol and execute exactly.\n\n${workflow}\n\n## Your Task\n\n${prompt}`,
-      display: false,
-    },
-    { triggerTurn: true },
-  );
+  try {
+    pi.sendMessage(
+      {
+        customType: "gsd-triage",
+        content: buildWorkflowDispatchContent({ workflow, workflowPath, task: prompt }),
+        display: false,
+      },
+      { triggerTurn: true },
+    );
+  } finally {
+    restoreGsdWorkflowTools(pi, savedTools);
+  }
 }
 
 export async function handleSteer(change: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<void> {

package/src/resources/extensions/gsd/commands-ship.ts

@@ -1,3 +1,6 @@
+// Project/App: GSD-2
+// File Purpose: Ship command for creating pull requests from GSD milestone evidence.
+
 /**
  * GSD Command — /gsd ship
  *
@@ -18,6 +21,7 @@ import { nativeGetCurrentBranch, nativeDetectMainBranch } from "./native-git-bri
 import { formatDuration } from "../shared/format-utils.js";
 import { parseEvalReviewFrontmatter, type Verdict } from "./eval-review-schema.js";
 import { currentDirectoryRoot } from "./commands/context.js";
+import { buildPrEvidence } from "./pr-evidence.js";
 
 function git(basePath: string, args: readonly string[]): string {
   return execFileSync("git", args, { cwd: basePath, encoding: "utf-8" }).trim();
@@ -32,11 +36,6 @@ function isValidRefName(name: string): boolean {
   }
 }
 
-interface PRContent {
-  title: string;
-  body: string;
-}
-
 function listSliceIds(basePath: string, milestoneId: string): string[] {
   // Slices live at <milestoneDir>/slices/<sliceId>/ with canonical S\d+ IDs.
   // Use resolveSlicePath with a probe to find the real slices directory root.
@@ -148,74 +147,48 @@ export async function checkSliceEvalReview(
   };
 }
 
-function generatePRContent(basePath: string, milestoneId: string, milestoneTitle: string): PRContent {
-  const title = `feat: ${milestoneTitle || milestoneId}`;
-
-  const sections: string[] = [];
-
-  // TL;DR
-  sections.push("## TL;DR\n");
-  sections.push(`**What:** Ship milestone ${milestoneId} — ${milestoneTitle || "(untitled)"}`);
-  sections.push(`**Why:** Milestone work complete, ready for review.`);
-  sections.push(`**How:** See slice summaries below.\n`);
-
-  // What — slice summaries
+function generatePRContent(basePath: string, milestoneId: string, milestoneTitle: string) {
   const summaries = collectSliceSummaries(basePath, milestoneId);
-  if (summaries.length > 0) {
-    sections.push("## What\n");
-    sections.push(summaries.join("\n\n"));
-    sections.push("");
-  }
-
-  // Roadmap status
+  const roadmapItems: string[] = [];
   const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
   if (roadmapPath && existsSync(roadmapPath)) {
     try {
       const roadmap = readFileSync(roadmapPath, "utf-8");
       const checkboxLines = roadmap.split("\n").filter((l) => /^\s*-\s*\[[ x]\]/.test(l));
-      if (checkboxLines.length > 0) {
-        sections.push("## Roadmap\n");
-        sections.push(checkboxLines.join("\n"));
-        sections.push("");
-      }
+      roadmapItems.push(...checkboxLines);
     } catch {
       // non-fatal
     }
   }
 
-  // Metrics
+  const metrics: string[] = [];
   const ledger = getLedger();
   const units = ledger?.units ?? loadLedgerFromDisk(basePath)?.units ?? [];
   if (units.length > 0) {
     const totals = getProjectTotals(units);
     const byModel = aggregateByModel(units);
-    sections.push("## Metrics\n");
-    sections.push(`- **Units executed:** ${units.length}`);
-    sections.push(`- **Total cost:** ${formatCost(totals.cost)}`);
-    sections.push(`- **Tokens:** ${formatTokenCount(totals.tokens.input)} input / ${formatTokenCount(totals.tokens.output)} output`);
+    metrics.push(`**Units executed:** ${units.length}`);
+    metrics.push(`**Total cost:** ${formatCost(totals.cost)}`);
+    metrics.push(`**Tokens:** ${formatTokenCount(totals.tokens.input)} input / ${formatTokenCount(totals.tokens.output)} output`);
     if (totals.duration > 0) {
-      sections.push(`- **Duration:** ${formatDuration(totals.duration)}`);
+      metrics.push(`**Duration:** ${formatDuration(totals.duration)}`);
     }
     if (byModel.length > 0) {
-      sections.push(`- **Models:** ${byModel.map((m) => `${m.model} (${m.units} units)`).join(", ")}`);
+      metrics.push(`**Models:** ${byModel.map((m) => `${m.model} (${m.units} units)`).join(", ")}`);
     }
-    sections.push("");
   }
 
-  // Change type checklist
-  sections.push("## Change type\n");
-  sections.push("- [x] `feat` — New feature or capability");
-  sections.push("- [ ] `fix` — Bug fix");
-  sections.push("- [ ] `refactor` — Code restructuring");
-  sections.push("- [ ] `test` — Adding or updating tests");
-  sections.push("- [ ] `docs` — Documentation only");
-  sections.push("- [ ] `chore` — Build, CI, or tooling changes\n");
-
-  // AI disclosure
-  sections.push("---\n");
-  sections.push("*This PR was prepared with AI assistance (GSD auto-mode).*");
-
-  return { title, body: sections.join("\n") };
+  return buildPrEvidence({
+    milestoneId,
+    milestoneTitle,
+    changeType: "feat",
+    summaries,
+    roadmapItems,
+    metrics,
+    testsRun: ["Run `npm run verify:pr` before marking this PR ready."],
+    rollbackNotes: ["Revert the merge commit or close the PR before merge if review finds a regression."],
+    how: "Generated from GSD milestone slice summaries, roadmap status, and local metrics.",
+  });
 }
 
 export async function handleShip(

package/src/resources/extensions/gsd/commands-workflow-templates.ts

@@ -1,3 +1,6 @@
+// Project/App: GSD-2
+// File Purpose: Workflow template commands for starting, listing, and dispatching workflows.
+
 /**
  * GSD Workflow Template Commands — /gsd start, /gsd templates
  *
@@ -15,6 +18,7 @@ import {
   getTemplateInfo,
   loadWorkflowTemplate,
   loadRegistry,
+  isLegacyWorkflowMode,
   type TemplateMatch,
 } from "./workflow-templates.js";
 import { loadPrompt } from "./prompt-loader.js";
@@ -24,6 +28,8 @@ import { isAutoActive, isAutoPaused } from "./auto.js";
 import { getErrorMessage } from "./error-utils.js";
 import { resolvePlugin, type WorkflowPlugin } from "./workflow-plugins.js";
 import { currentDirectoryRoot } from "./commands/context.js";
+import { formatRecommendedProcessPaths } from "./process-task-path.js";
+import { incrementLegacyTelemetry } from "./legacy-telemetry.js";
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
@@ -328,6 +334,9 @@ export async function handleStart(
         "  /gsd start bugfix fix login button not responding\n" +
         "  /gsd start spike evaluate auth libraries\n" +
         "  /gsd start hotfix critical: API returns 500\n\n" +
+        "Recommended task paths:\n" +
+        formatRecommendedProcessPaths() +
+        "\n\n" +
         "Flags:\n" +
         "  --dry-run       Preview what would happen without executing\n" +
         "  --issue <ref>   Link to a GitHub issue\n\n" +
@@ -484,6 +493,9 @@ export async function handleStart(
   if (artifactDir) infoLines.push(`Artifacts: ${artifactDir}`);
   infoLines.push(`Branch: ${actualBranch}`);
   ctx.ui.notify(infoLines.join("\n"), "info");
+  if (isLegacyWorkflowMode(template.mode)) {
+    incrementLegacyTelemetry("legacy.workflowEngineUsed");
+  }
 
   const prompt = loadPrompt("workflow-start", {
     templateId,
@@ -649,6 +661,7 @@ export function dispatchMarkdownPhasePlugin(
   if (artifactDir) infoLines.push(`Artifacts: ${artifactDir}`);
   infoLines.push(`Branch: ${actualBranch}`);
   ctx.ui.notify(infoLines.join("\n"), "info");
+  incrementLegacyTelemetry("legacy.workflowEngineUsed");
 
   const prompt = loadPrompt("workflow-start", {
     templateId,

package/src/resources/extensions/gsd/component-loader.ts

@@ -1,19 +1,11 @@
-/**
- * Component Loader
- *
- * Multi-format loader that handles:
- * 1. New format: component.yaml + SKILL.md/AGENT.md
- * 2. Legacy skill format: SKILL.md with YAML frontmatter
- * 3. Legacy agent format: .md with YAML frontmatter (name, description, tools, model)
- *
- * Auto-detects format by checking for component.yaml first, then falling back
- * to legacy formats based on file naming conventions.
- */
+// Project/App: GSD-2
+// File Purpose: Loads modern component.yaml definitions and legacy skill/agent formats.
 
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
 import { parse as parseYaml } from 'yaml';
 import { parseFrontmatter } from '@gsd/pi-coding-agent';
+import { incrementLegacyTelemetry } from './legacy-telemetry.js';
 import type {
 	Component,
 	ComponentApiVersion,
@@ -270,6 +262,7 @@ function loadFromLegacySkill(
 		enabled: true,
 	};
 
+	incrementLegacyTelemetry('legacy.componentFormatUsed');
 	return { component, diagnostics };
 }
 
@@ -345,6 +338,7 @@ function loadFromLegacyAgent(
 		enabled: true,
 	};
 
+	incrementLegacyTelemetry('legacy.componentFormatUsed');
 	return { component, diagnostics };
 }
 

package/src/resources/extensions/gsd/context-budget.ts

@@ -8,7 +8,12 @@
  * @see D001 (module location), D002 (200K fallback), D003 (section-boundary truncation)
  */
 
-import { type TokenProvider, getCharsPerToken } from "./token-counter.js";
+import {
+  type TokenProvider,
+  getCharsPerToken,
+  isAccurateCountingAvailable,
+  countTokensSync,
+} from "./token-counter.js";
 
 // ─── Budget ratio constants ──────────────────────────────────────────────────
 // Percentages of total context window allocated to each budget category.
@@ -32,6 +37,24 @@ const DEFAULT_CONTEXT_WINDOW = 200_000;
 /** Conservative effective context for Claude Code subscription routing (#4676) */
 const CLAUDE_CODE_EFFECTIVE_CONTEXT_WINDOW = 200_000;
 
+/**
+ * Cached empirical chars-per-token from a tiktoken probe, keyed by provider.
+ * countTokensSync's fallback path is provider-aware, so we cache per-provider
+ * to preserve that distinction once the encoder warms. The cl100k_base encoder
+ * itself gives a stable ratio for ASCII English so a single probe per provider
+ * key is sufficient. Empty map means "not yet probed" or "encoder unavailable".
+ */
+const _empiricalCharsPerTokenByProvider = new Map<string, number>();
+
+/**
+ * Test hook — clears the empirical chars-per-token cache so test cases that
+ * assert against the static char-ratio fallback aren't polluted by a prior
+ * tiktoken-warmed run in the same process. Production code must not call this.
+ */
+export function _resetEmpiricalCacheForTest(): void {
+  _empiricalCharsPerTokenByProvider.clear();
+}
+
 /** Percentage of context consumed before suggesting a continue-here checkpoint */
 const CONTINUE_THRESHOLD_PERCENT = 70;
 
@@ -101,7 +124,26 @@ export interface MinimalPreferences {
 export function computeBudgets(contextWindow: number, provider?: TokenProvider): BudgetAllocation {
   const effectiveWindow = contextWindow > 0 ? contextWindow : DEFAULT_CONTEXT_WINDOW;
   const charsPerToken = provider ? getCharsPerToken(provider) : CHARS_PER_TOKEN;
-  const totalChars = effectiveWindow * charsPerToken;
+
+  // Prefer the tiktoken encoder for total-char estimation when it has been
+  // warmed (initTokenCounter resolved). The cl100k_base ratio is stable for
+  // ASCII English, so probe once per provider and cache — computeBudgets is
+  // called multiple times per prompt build and the probe encode is otherwise
+  // wasted work.
+  let totalChars: number;
+  if (isAccurateCountingAvailable()) {
+    const providerKey = provider ?? "__default__";
+    let empirical = _empiricalCharsPerTokenByProvider.get(providerKey);
+    if (empirical === undefined) {
+      const probe = "the quick brown fox jumps over the lazy dog ".repeat(64);
+      const probeTokens = countTokensSync(probe, provider);
+      empirical = probeTokens > 0 ? probe.length / probeTokens : charsPerToken;
+      _empiricalCharsPerTokenByProvider.set(providerKey, empirical);
+    }
+    totalChars = effectiveWindow * empirical;
+  } else {
+    totalChars = effectiveWindow * charsPerToken;
+  }
 
   return {
     summaryBudgetChars: Math.floor(totalChars * SUMMARY_RATIO),

package/src/resources/extensions/gsd/crash-recovery.ts

@@ -38,6 +38,7 @@ import { _getAdapter, isDbAvailable } from "./gsd-db.js";
 import { gsdRoot, normalizeRealPath } from "./paths.js";
 import { atomicWriteSync } from "./atomic-write.js";
 import { effectiveLockFile } from "./session-lock.js";
+import { isInFlightRuntimePhase, listUnitRuntimeRecords, type AutoUnitRuntimeRecord } from "./unit-runtime.js";
 
 export interface LockData {
   pid: number;
@@ -103,10 +104,40 @@ function getLatestDispatchForWorker(workerId: string):
   return row ?? null;
 }
 
-function workerToLockData(worker: AutoWorkerRow): LockData {
+function latestInFlightRuntimeRecord(basePath: string): AutoUnitRuntimeRecord | null {
+  const records = listUnitRuntimeRecords(basePath).filter((record) =>
+    isInFlightRuntimePhase(record.phase),
+  );
+  if (records.length === 0) return null;
+  return records.sort((a, b) => {
+    const bTime = b.updatedAt || b.startedAt || 0;
+    const aTime = a.updatedAt || a.startedAt || 0;
+    return bTime - aTime;
+  })[0] ?? null;
+}
+
+function runtimeRecordToLockData(worker: AutoWorkerRow, record: AutoUnitRuntimeRecord, sessionFile?: string): LockData {
+  const startedAt = Number.isFinite(record.startedAt)
+    ? new Date(record.startedAt).toISOString()
+    : worker.started_at;
+  return {
+    pid: worker.pid,
+    startedAt: worker.started_at,
+    unitType: record.unitType,
+    unitId: record.unitId,
+    unitStartedAt: startedAt,
+    sessionFile,
+  };
+}
+
+function workerToLockData(basePath: string, worker: AutoWorkerRow): LockData {
   const dispatch = getLatestDispatchForWorker(worker.worker_id);
   const sessionFile =
     getRuntimeKv<string>("worker", worker.worker_id, SESSION_FILE_KV_KEY) ?? undefined;
+  if (!dispatch) {
+    const runtimeRecord = latestInFlightRuntimeRecord(basePath);
+    if (runtimeRecord) return runtimeRecordToLockData(worker, runtimeRecord, sessionFile);
+  }
   return {
     pid: worker.pid,
     startedAt: worker.started_at,
@@ -204,7 +235,7 @@ export function readCrashLock(basePath: string): LockData | null {
     try {
       const projectRoot = normalizeRealPath(basePath);
       const stale = findStaleWorkerForProject(projectRoot);
-      if (stale) return workerToLockData(stale);
+      if (stale) return workerToLockData(basePath, stale);
     } catch {
       // Fall through to the legacy lock-file compatibility path.
     }
@@ -260,25 +291,48 @@ export function formatCrashInfo(lock: LockData): string {
  */
 export function emitCrashRecoveredUnitEnd(basePath: string, lock: LockData): void {
   if (!lock.unitType || !lock.unitId || lock.unitType === "starting") return;
+  emitOpenUnitEndForUnit(basePath, lock.unitType, lock.unitId, "crash-recovered");
+}
 
+export function emitOpenUnitEndForUnit(
+  basePath: string,
+  unitType: string,
+  unitId: string,
+  status: string,
+  errorContext?: { message: string; category: string; stopReason?: string; isTransient?: boolean; retryAfterMs?: number },
+): boolean {
   try {
     const all = queryJournal(basePath);
 
     const starts = all.filter(
-      (e) => e.eventType === "unit-start" && e.data?.unitId === lock.unitId,
+      (e) =>
+        e.eventType === "unit-start" &&
+        e.data?.unitType === unitType &&
+        e.data?.unitId === unitId,
     );
-    if (starts.length === 0) return;
+    if (starts.length === 0) return false;
 
-    const lastStart = starts[starts.length - 1];
+    const lastStart = [...starts].reverse().find((start) => {
+      return !all.some(
+        (e) =>
+          e.eventType === "unit-end" &&
+          e.data?.unitType === unitType &&
+          e.data?.unitId === unitId &&
+          e.causedBy?.flowId === start.flowId &&
+          e.causedBy?.seq === start.seq,
+      );
+    });
+    if (!lastStart) return false;
 
     const alreadyClosed = all.some(
       (e) =>
         e.eventType === "unit-end" &&
-        e.data?.unitId === lock.unitId &&
+        e.data?.unitType === unitType &&
+        e.data?.unitId === unitId &&
         e.causedBy?.flowId === lastStart.flowId &&
         e.causedBy?.seq === lastStart.seq,
     );
-    if (alreadyClosed) return;
+    if (alreadyClosed) return false;
 
     const maxSeq = all
       .filter((e) => e.flowId === lastStart.flowId)
@@ -290,15 +344,18 @@ export function emitCrashRecoveredUnitEnd(basePath: string, lock: LockData): voi
       seq: maxSeq + 1,
       eventType: "unit-end",
       data: {
-        unitType: lock.unitType,
-        unitId: lock.unitId,
-        status: "crash-recovered",
+        unitType,
+        unitId,
+        status,
         artifactVerified: false,
+        ...(errorContext ? { errorContext } : {}),
       },
       causedBy: { flowId: lastStart.flowId, seq: lastStart.seq },
     });
+    return true;
   } catch {
     // Never throw from crash recovery path.
+    return false;
   }
 }
 

package/src/resources/extensions/gsd/custom-workflow-engine.ts

@@ -29,6 +29,7 @@ import {
   markStepActive,
   markStepComplete,
   expandIteration,
+  isTerminalStepStatus,
   type WorkflowGraph,
 } from "./graph.js";
 import { injectContext } from "./context-injector.js";
@@ -40,6 +41,24 @@ import { withFileLock } from "./file-lock.js";
 // Re-export for downstream consumers
 export { readFrozenDefinition } from "./definition-io.js";
 
+function formatBlockedWorkflowReason(graph: WorkflowGraph): string {
+  const statusById = new Map(graph.steps.map((step) => [step.id, step.status]));
+  const blockedSteps = graph.steps
+    .filter((step) => step.status === "pending")
+    .map((step) => {
+      const blockers = step.dependsOn
+        .filter((depId) => !isTerminalStepStatus(statusById.get(depId)))
+        .map((depId) => `${depId} (${statusById.get(depId) ?? "missing"})`);
+      return blockers.length > 0
+        ? `${step.id} waiting on ${blockers.join(", ")}`
+        : `${step.id} has no runnable dependency path`;
+    });
+
+  return blockedSteps.length > 0
+    ? `Workflow blocked: no pending steps are ready. Blocked steps: ${blockedSteps.join("; ")}`
+    : "Workflow blocked: no pending steps are ready.";
+}
+
 export class CustomWorkflowEngine implements WorkflowEngine {
   readonly engineId = "custom";
   private readonly runDir: string;
@@ -110,6 +129,16 @@ export class CustomWorkflowEngine implements WorkflowEngine {
       let next = getNextPendingStep(graph);
 
       if (!next) {
+        const allDone = graph.steps.every(
+          (step) => step.status === "complete" || step.status === "expanded",
+        );
+        if (!allDone) {
+          return {
+            action: "stop",
+            reason: formatBlockedWorkflowReason(graph),
+            level: "error",
+          };
+        }
         return {
           action: "stop",
           reason: "All steps complete",

package/src/resources/extensions/gsd/dashboard-overlay.ts

@@ -29,7 +29,7 @@ import { computeProgressScore, formatProgressLine } from "./progress-score.js";
 import { runEnvironmentChecks, type EnvironmentCheckResult } from "./doctor-environment.js";
 import { formattedShortcutPair } from "./shortcut-defs.js";
 
-function unitLabel(type: string): string {
+export function unitLabel(type: string): string {
   switch (type) {
     case "discuss-milestone":
     case "discuss-slice": return "Discuss";

package/src/resources/extensions/gsd/db/unit-dispatches.ts

@@ -98,6 +98,70 @@ function isAlreadyActiveConstraintError(err: unknown): boolean {
   return /\bUNIQUE\b|\bconstraint failed\b/i.test(msg);
 }
 
+function settleStaleActiveDispatchForUnit(input: RecordClaimInput, now: string): void {
+  const db = _getAdapter()!;
+  const active = db.prepare(
+    `SELECT id, status, worker_id, milestone_lease_token
+     FROM unit_dispatches
+     WHERE unit_id = :unit_id
+       AND status IN ('claimed','running')
+     ORDER BY id DESC
+     LIMIT 1`,
+  ).get({ ":unit_id": input.unitId }) as
+    | { id: number; status: DispatchStatus; worker_id: string; milestone_lease_token: number }
+    | undefined;
+
+  if (!active) return;
+  if (
+    active.worker_id === input.workerId &&
+    active.milestone_lease_token === input.milestoneLeaseToken
+  ) {
+    return;
+  }
+
+  const reason = "stale-dispatch-lease-takeover";
+  const result = db.prepare(
+    `UPDATE unit_dispatches
+     SET status = 'canceled',
+         ended_at = :ended_at,
+         exit_reason = :reason
+     WHERE id = :id
+       AND status IN ('claimed','running')
+       AND (worker_id != :worker_id OR milestone_lease_token != :token)`,
+  ).run({
+    ":id": active.id,
+    ":ended_at": now,
+    ":reason": reason,
+    ":worker_id": input.workerId,
+    ":token": input.milestoneLeaseToken,
+  });
+
+  const changes =
+    typeof (result as { changes?: unknown }).changes === "number"
+      ? (result as { changes: number }).changes
+      : 0;
+  if (changes < 1) return;
+
+  insertAuditEvent({
+    eventId: randomUUID(),
+    traceId: input.traceId,
+    turnId: input.turnId ?? undefined,
+    category: "orchestration",
+    type: "dispatch-stale-canceled",
+    ts: now,
+    payload: {
+      dispatchId: active.id,
+      unitId: input.unitId,
+      priorStatus: active.status,
+      priorWorkerId: active.worker_id,
+      priorMilestoneLeaseToken: active.milestone_lease_token,
+      takeoverWorkerId: input.workerId,
+      takeoverMilestoneLeaseToken: input.milestoneLeaseToken,
+      reason,
+    },
+  });
+}
+
 /**
  * Insert a new dispatch row in `claimed` state. Atomic guard against
  * double-claim (B2): the partial unique index
@@ -135,6 +199,8 @@ export function recordDispatchClaim(input: RecordClaimInput): RecordClaimResult
       };
     }
 
+    settleStaleActiveDispatchForUnit(input, now);
+
     try {
       const result = db.prepare(
         `INSERT INTO unit_dispatches (
@@ -359,6 +425,47 @@ export function markCanceled(dispatchId: number, reason: string): void {
   ).run({ ":id": dispatchId, ":ended_at": now, ":reason": reason });
 }
 
+/**
+ * Best-effort signal/crash cleanup: cancel the latest active dispatch owned by
+ * a worker when the process is exiting before the normal loop can settle it.
+ */
+export function markLatestActiveForWorkerCanceled(workerId: string, reason: string): boolean {
+  if (!isDbAvailable()) return false;
+  const now = new Date().toISOString();
+  const db = _getAdapter()!;
+  const result = transaction(() => {
+    return db.prepare(
+      `UPDATE unit_dispatches
+       SET status = 'canceled', ended_at = :ended_at, exit_reason = :reason
+       WHERE id = (
+         SELECT id FROM unit_dispatches
+         WHERE worker_id = :worker_id
+           AND status IN ('pending','claimed','running')
+         ORDER BY id DESC
+         LIMIT 1
+       )`,
+    ).run({
+      ":ended_at": now,
+      ":reason": reason,
+      ":worker_id": workerId,
+    });
+  });
+  const changes =
+    typeof (result as { changes?: unknown }).changes === "number"
+      ? (result as { changes: number }).changes
+      : 0;
+  if (changes <= 0) return false;
+  insertAuditEvent({
+    eventId: randomUUID(),
+    traceId: workerId,
+    category: "orchestration",
+    type: "dispatch-canceled",
+    ts: now,
+    payload: { workerId, reason },
+  });
+  return true;
+}
+
 /**
  * Fetch the most recent N dispatches for a unit. Used by recordDispatchClaim
  * callers to compute attempt_n and by detect-stuck.ts (B3) to consult