gsd-pi 2.31.2 → 2.32.0-dev.3d7932c

package/README.md

@@ -24,21 +24,24 @@ One command. Walk away. Come back to a built project with clean git history.
 
 ---
 
-## What's New in v2.29
-
-- **Node.js 24 LTS** — CI, Docker, and package config all upgraded to Node 24 (Krypton)
-- **`searchExcludeDirs` setting** — blacklist directories from `@` file autocomplete (e.g., `node_modules`, `dist`)
-- **Automated releases** — prod-release now auto-generates changelogs, bumps versions, and publishes to npm
-- **`/gsd logs`** — browse activity, debug, and metrics logs from within a session
-- **Configurable screenshots** — browser-tools now support custom resolution, format, and quality
-- **Pre-commit secret scanning** — automatic detection of hardcoded secrets in CI and locally
-- **Per-project MCP config** — `.gsd/mcp.json` for project-scoped MCP server definitions
-- **API request metrics** — track request counts for Copilot/subscription users
-- **`/gsd keys`** — full API key lifecycle management (list, add, remove, test, rotate, doctor)
-- **Advisory verification gate** — auto-discovered checks (lint/test from package.json) no longer doom-loop on pre-existing errors
-- **Worktree living doc sync** — DECISIONS, REQUIREMENTS, PROJECT, and KNOWLEDGE now sync between worktree and project root
-- **Windows non-ASCII path support** — `cpSync` fallback for usernames with special characters
-- **`needs-discussion` routing** — milestones with draft context now route to the interactive discussion flow instead of stopping
+## What's New in v2.32
+
+- **Simplified pipeline** — research merged into planning, mechanical completion (ADR-003)
+- **Always-on health widget** — 🟢🟡🔴 traffic-light indicator in the progress widget and visualizer health tab
+- **Environment health checks** — progress scoring and status integration for auto-mode
+- **Extension registry** — user-managed enable/disable for bundled and custom extensions
+- **Built-in skill authoring** — create and distribute custom skills from within GSD
+- **Workflow templates** — right-sized workflows for every task type (research, plan, execute, complete)
+- **AWS Bedrock auth** — automatic credential refresh via the new `aws-auth` extension
+- **`-w` / `--worktree` CLI flag** — launch isolated worktree sessions from the command line
+- **Native MCP client** — replaced MCPorter with a built-in MCP client for better reliability
+- **External state directory** — `.gsd/` now lives in `~/.gsd/projects/` with a symlink (ADR-002)
+- **Model health indicator** — live health status based on error trends and consecutive failures
+- **Quick-task branch cleanup** — `/gsd quick` branches auto-merge back after completion
+- **Windows EPERM fallback** — migration rename uses copy+delete when NTFS blocks rename
+- **Worktree identity fix** — stable project hash across worktrees and main repo
+- **Crash recovery guidance** — actionable next-step messages based on what was interrupted
+- **UAT verdict gating** — non-PASS verdicts now block slice progression instead of being ignored
 
 See the full [Changelog](./CHANGELOG.md) for details.
 
@@ -65,6 +68,7 @@ Full documentation is available in the [`docs/`](./docs/) directory:
 - **[Visualizer](./docs/visualizer.md)** — workflow visualizer with stats and discussion status
 - **[Remote Questions](./docs/remote-questions.md)** — route decisions to Slack or Discord when human input is needed
 - **[Dynamic Model Routing](./docs/dynamic-model-routing.md)** — complexity-based model selection and budget pressure
+- **[Pipeline Simplification (ADR-003)](./docs/ADR-003-pipeline-simplification.md)** — merged research into planning, mechanical completion
 - **[Migration from v1](./docs/migration.md)** — `.planning` → `.gsd` migration
 
 ---
@@ -141,12 +145,12 @@ The iron rule: **a task must fit in one context window.** If it can't, it's two
 Each slice flows through phases automatically:
 
 ```
-Research → Plan → Execute (per task) → Complete → Reassess Roadmap → Next Slice
-                                                                      ↓ (all slices done)
-                                                              Validate Milestone → Complete Milestone
+Plan (with integrated research) → Execute (per task) → Complete → Reassess Roadmap → Next Slice
+                                                                                      ↓ (all slices done)
+                                                                              Validate Milestone → Complete Milestone
 ```
 
-**Research** scouts the codebase and relevant docs. **Plan** decomposes the slice into tasks with must-haves (mechanically verifiable outcomes). **Execute** runs each task in a fresh context window with only the relevant files pre-loaded — then runs configured verification commands (lint, test, etc.) with auto-fix retries. **Complete** writes the summary, UAT script, marks the roadmap, and commits with meaningful messages derived from task summaries. **Reassess** checks if the roadmap still makes sense given what was learned. **Validate Milestone** runs a reconciliation gate after all slices complete — comparing roadmap success criteria against actual results before sealing the milestone.
+**Plan** scouts the codebase, researches relevant docs, and decomposes the slice into tasks with must-haves (mechanically verifiable outcomes). **Execute** runs each task in a fresh context window with only the relevant files pre-loaded — then runs configured verification commands (lint, test, etc.) with auto-fix retries. **Complete** writes the summary, UAT script, marks the roadmap, and commits with meaningful messages derived from task summaries. **Reassess** checks if the roadmap still makes sense given what was learned. **Validate Milestone** runs a reconciliation gate after all slices complete — comparing roadmap success criteria against actual results before sealing the milestone.
 
 ### `/gsd auto` — The Main Event
 
@@ -326,6 +330,7 @@ On first run, GSD launches a branded setup wizard that walks you through LLM pro
 | `gsd headless [cmd]`    | Run `/gsd` commands without TUI (CI, cron, scripts)             |
 | `gsd headless query`    | Instant JSON snapshot — state, next dispatch, costs (no LLM)    |
 | `gsd --continue` (`-c`) | Resume the most recent session for the current directory        |
+| `gsd --worktree` (`-w`) | Launch an isolated worktree session for the active milestone    |
 | `gsd sessions`          | Interactive session picker — browse and resume any saved session |
 
 ---
@@ -483,7 +488,7 @@ See the full [Token Optimization Guide](./docs/token-optimization.md) for detail
 
 ### Bundled Tools
 
-GSD ships with 16 extensions, all loaded automatically:
+GSD ships with 18 extensions, all loaded automatically:
 
 | Extension              | What it provides                                                                                                       |
 | ---------------------- | ---------------------------------------------------------------------------------------------------------------------- |
@@ -503,6 +508,8 @@ GSD ships with 16 extensions, all loaded automatically:
 | **Secure Env Collect** | Masked secret collection without manual .env editing                                                                   |
 | **Remote Questions**   | Route decisions to Slack/Discord when human input is needed in headless/CI mode                                         |
 | **Universal Config**   | Discover and import MCP servers and rules from other AI coding tools                                                    |
+| **AWS Auth**           | Automatic Bedrock credential refresh for AWS-hosted models                                                              |
+| **TTSR**               | Tool-use type-safe runtime validation                                                                                   |
 
 ### Bundled Agents
 

package/dist/cli.js

@@ -359,16 +359,16 @@ if (cliFlags.messages[0] === 'worktree' || cliFlags.messages[0] === 'wt') {
     const sub = cliFlags.messages[1];
     const subArgs = cliFlags.messages.slice(2);
     if (!sub || sub === 'list') {
-        handleList(process.cwd());
+        await handleList(process.cwd());
     }
     else if (sub === 'merge') {
         await handleMerge(process.cwd(), subArgs);
     }
     else if (sub === 'clean') {
-        handleClean(process.cwd());
+        await handleClean(process.cwd());
     }
     else if (sub === 'remove' || sub === 'rm') {
-        handleRemove(process.cwd(), subArgs);
+        await handleRemove(process.cwd(), subArgs);
     }
     else {
         process.stderr.write(`Unknown worktree command: ${sub}\n`);
@@ -381,7 +381,7 @@ if (cliFlags.messages[0] === 'worktree' || cliFlags.messages[0] === 'wt') {
 // ---------------------------------------------------------------------------
 if (cliFlags.worktree) {
     const { handleWorktreeFlag } = await import('./worktree-cli.js');
-    handleWorktreeFlag(cliFlags.worktree);
+    await handleWorktreeFlag(cliFlags.worktree);
 }
 // ---------------------------------------------------------------------------
 // Active worktree banner — remind user of unmerged worktrees on normal launch
@@ -389,7 +389,7 @@ if (cliFlags.worktree) {
 if (!cliFlags.worktree && !isPrintMode) {
     try {
         const { handleStatusBanner } = await import('./worktree-cli.js');
-        handleStatusBanner(process.cwd());
+        await handleStatusBanner(process.cwd());
     }
     catch { /* non-fatal */ }
 }

package/dist/resource-loader.js

@@ -1,7 +1,7 @@
 import { DefaultResourceLoader } from '@gsd/pi-coding-agent';
 import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
-import { chmodSync, copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { chmodSync, copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { compareSemver } from './update-check.js';
@@ -118,7 +118,12 @@ export function getNewerManagedResourceVersion(agentDir, currentVersion) {
 function makeTreeWritable(dirPath) {
     if (!existsSync(dirPath))
         return;
-    const stats = statSync(dirPath);
+    // Use lstatSync to avoid following symlinks into immutable filesystems
+    // (e.g., Nix store on NixOS/nix-darwin). Symlinks don't carry their own
+    // permissions and their targets may be read-only by design (#1298).
+    const stats = lstatSync(dirPath);
+    if (stats.isSymbolicLink())
+        return;
     const isDir = stats.isDirectory();
     const currentMode = stats.mode & 0o777;
     // Ensure owner-write; for directories also ensure owner-exec so they remain traversable.
@@ -127,7 +132,12 @@ function makeTreeWritable(dirPath) {
         newMode |= 0o100;
     }
     if (newMode !== currentMode) {
-        chmodSync(dirPath, newMode);
+        try {
+            chmodSync(dirPath, newMode);
+        }
+        catch {
+            // Non-fatal — may fail on read-only filesystems or insufficient permissions
+        }
     }
     if (isDir) {
         for (const entry of readdirSync(dirPath, { withFileTypes: true })) {

package/dist/resources/extensions/gsd/auto-constants.ts

@@ -0,0 +1,6 @@
+/**
+ * Shared constants for auto-mode modules (auto.ts, auto-post-unit.ts, etc.).
+ */
+
+/** Throttle STATE.md rebuilds — at most once per 30 seconds. */
+export const STATE_REBUILD_MIN_INTERVAL_MS = 30_000;

package/dist/resources/extensions/gsd/auto-dashboard.ts

@@ -20,6 +20,7 @@ import { parseRoadmap, parsePlan } from "./files.js";
 import { readFileSync, existsSync } from "node:fs";
 import { truncateToWidth, visibleWidth } from "@gsd/pi-tui";
 import { makeUI, GLYPH, INDENT } from "../shared/mod.js";
+import { parseUnitId } from "./unit-id.js";
 
 // ─── Dashboard Data ───────────────────────────────────────────────────────────
 
@@ -48,40 +49,34 @@ export interface AutoDashboardData {
 
 // ─── Unit Description Helpers ─────────────────────────────────────────────────
 
+/** Canonical verb and phase label for each known unit type. */
+const UNIT_TYPE_INFO: Record<string, { verb: string; phaseLabel: string }> = {
+  "research-milestone": { verb: "researching",  phaseLabel: "RESEARCH" },
+  "research-slice":     { verb: "researching",  phaseLabel: "RESEARCH" },
+  "plan-milestone":     { verb: "planning",     phaseLabel: "PLAN" },
+  "plan-slice":         { verb: "planning",     phaseLabel: "PLAN" },
+  "execute-task":       { verb: "executing",    phaseLabel: "EXECUTE" },
+  "complete-slice":     { verb: "completing",   phaseLabel: "COMPLETE" },
+  "replan-slice":       { verb: "replanning",   phaseLabel: "REPLAN" },
+  "rewrite-docs":       { verb: "rewriting",    phaseLabel: "REWRITE" },
+  "reassess-roadmap":   { verb: "reassessing",  phaseLabel: "REASSESS" },
+  "run-uat":            { verb: "running UAT",  phaseLabel: "UAT" },
+};
+
 export function unitVerb(unitType: string): string {
   if (unitType.startsWith("hook/")) return `hook: ${unitType.slice(5)}`;
-  switch (unitType) {
-    case "research-milestone":
-    case "research-slice": return "researching";
-    case "plan-milestone":
-    case "plan-slice": return "planning";
-    case "execute-task": return "executing";
-    case "complete-slice": return "completing";
-    case "replan-slice": return "replanning";
-    case "rewrite-docs": return "rewriting";
-    case "reassess-roadmap": return "reassessing";
-    case "run-uat": return "running UAT";
-    default: return unitType;
-  }
+  return UNIT_TYPE_INFO[unitType]?.verb ?? unitType;
 }
 
 export function unitPhaseLabel(unitType: string): string {
   if (unitType.startsWith("hook/")) return "HOOK";
-  switch (unitType) {
-    case "research-milestone": return "RESEARCH";
-    case "research-slice": return "RESEARCH";
-    case "plan-milestone": return "PLAN";
-    case "plan-slice": return "PLAN";
-    case "execute-task": return "EXECUTE";
-    case "complete-slice": return "COMPLETE";
-    case "replan-slice": return "REPLAN";
-    case "rewrite-docs": return "REWRITE";
-    case "reassess-roadmap": return "REASSESS";
-    case "run-uat": return "UAT";
-    default: return unitType.toUpperCase();
-  }
+  return UNIT_TYPE_INFO[unitType]?.phaseLabel ?? unitType.toUpperCase();
 }
 
+/**
+ * Describe the expected next step after the current unit completes.
+ * Unit types here mirror the keys in UNIT_TYPE_INFO above.
+ */
 function peekNext(unitType: string, state: GSDState): string {
   // Show active hook info in progress display
   const activeHookState = getActiveHook();
@@ -378,8 +373,9 @@ export function updateProgressWidget(
         lines.push("");
 
         const isHook = unitType.startsWith("hook/");
+        const hookParsed = isHook ? parseUnitId(unitId) : undefined;
         const target = isHook
-          ? (unitId.split("/").pop() ?? unitId)
+          ? (hookParsed!.task ?? hookParsed!.slice ?? unitId)
           : (task ? `${task.id}: ${task.title}` : unitId);
         const actionLeft = `${pad}${theme.fg("accent", "▸")} ${theme.fg("accent", verb)}  ${theme.fg("text", target)}`;
         const tierTag = tierBadge ? theme.fg("dim", `[${tierBadge}] `) : "";

package/dist/resources/extensions/gsd/auto-direct-dispatch.ts

@@ -182,15 +182,10 @@ export async function dispatchDirectPhase(
         ctx.ui.notify("Cannot dispatch run-uat: no UAT file found.", "warning");
         return;
       }
-      const uatContent = await loadFile(uatFile);
-      if (!uatContent) {
-        ctx.ui.notify("Cannot dispatch run-uat: UAT file is empty.", "warning");
-        return;
-      }
       const uatPath = relSliceFile(base, mid, sid, "UAT");
       unitType = "run-uat";
       unitId = `${mid}/${sid}`;
-      prompt = await buildRunUatPrompt(mid, sid, uatPath, uatContent, base);
+      prompt = await buildRunUatPrompt(mid, sid, uatPath, base);
       break;
     }
 

package/dist/resources/extensions/gsd/auto-dispatch.ts

@@ -11,8 +11,7 @@
 
 import type { GSDState } from "./types.js";
 import type { GSDPreferences } from "./preferences.js";
-import type { UatType } from "./files.js";
-import { loadFile, extractUatType, loadActiveOverrides, parseRoadmap } from "./files.js";
+import { loadFile, loadActiveOverrides, parseRoadmap } from "./files.js";
 import {
   resolveMilestoneFile, resolveMilestonePath, resolveSliceFile, resolveTaskFile,
   relSliceFile, buildMilestoneFileName,
@@ -39,7 +38,7 @@ import {
 // ─── Types ────────────────────────────────────────────────────────────────
 
 export type DispatchAction =
-  | { action: "dispatch"; unitType: string; unitId: string; prompt: string; pauseAfterDispatch?: boolean }
+  | { action: "dispatch"; unitType: string; unitId: string; prompt: string }
   | { action: "stop"; reason: string; level: "info" | "warning" | "error" }
   | { action: "skip" };
 
@@ -138,17 +137,14 @@ const DISPATCH_RULES: DispatchRule[] = [
     match: async ({ state, mid, basePath, prefs }) => {
       const needsRunUat = await checkNeedsRunUat(basePath, mid, state, prefs);
       if (!needsRunUat) return null;
-      const { sliceId, uatType } = needsRunUat;
-      const uatFile = resolveSliceFile(basePath, mid, sliceId, "UAT")!;
-      const uatContent = await loadFile(uatFile);
+      const { sliceId } = needsRunUat;
       return {
         action: "dispatch",
         unitType: "run-uat",
         unitId: `${mid}/${sliceId}`,
         prompt: await buildRunUatPrompt(
-          mid, sliceId, relSliceFile(basePath, mid, sliceId, "UAT"), uatContent ?? "", basePath,
+          mid, sliceId, relSliceFile(basePath, mid, sliceId, "UAT"), basePath,
         ),
-        pauseAfterDispatch: uatType !== "artifact-driven",
       };
     },
   },

package/dist/resources/extensions/gsd/auto-idempotency.ts

@@ -18,6 +18,7 @@ import {
 import { resolveMilestoneFile } from "./paths.js";
 import { MAX_CONSECUTIVE_SKIPS, MAX_LIFETIME_DISPATCHES } from "./auto/session.js";
 import type { AutoSession } from "./auto/session.js";
+import { parseUnitId } from "./unit-id.js";
 
 export interface IdempotencyContext {
   s: AutoSession;
@@ -54,7 +55,7 @@ export function checkIdempotency(ictx: IdempotencyContext): IdempotencyResult {
       s.unitConsecutiveSkips.set(idempotencyKey, skipCount);
       if (skipCount > MAX_CONSECUTIVE_SKIPS) {
         // Cross-check: verify the unit's milestone is still active (#790)
-        const skippedMid = unitId.split("/")[0];
+        const skippedMid = parseUnitId(unitId).milestone;
         const skippedMilestoneComplete = skippedMid
           ? !!resolveMilestoneFile(basePath, skippedMid, "SUMMARY")
           : false;
@@ -110,7 +111,7 @@ export function checkIdempotency(ictx: IdempotencyContext): IdempotencyResult {
     const skipCount2 = (s.unitConsecutiveSkips.get(idempotencyKey) ?? 0) + 1;
     s.unitConsecutiveSkips.set(idempotencyKey, skipCount2);
     if (skipCount2 > MAX_CONSECUTIVE_SKIPS) {
-      const skippedMid2 = unitId.split("/")[0];
+      const skippedMid2 = parseUnitId(unitId).milestone;
       const skippedMilestoneComplete2 = skippedMid2
         ? !!resolveMilestoneFile(basePath, skippedMid2, "SUMMARY")
         : false;

package/dist/resources/extensions/gsd/auto-observability.ts

@@ -12,6 +12,7 @@ import {
   formatValidationIssues,
 } from "./observability-validator.js";
 import type { ValidationIssue } from "./observability-validator.js";
+import { parseUnitId } from "./unit-id.js";
 
 export async function collectObservabilityWarnings(
   ctx: ExtensionContext,
@@ -22,10 +23,7 @@ export async function collectObservabilityWarnings(
   // Hook units have custom artifacts — skip standard observability checks
   if (unitType.startsWith("hook/")) return [];
 
-  const parts = unitId.split("/");
-  const mid = parts[0];
-  const sid = parts[1];
-  const tid = parts[2];
+  const { milestone: mid, slice: sid, task: tid } = parseUnitId(unitId);
 
   if (!mid || !sid) return [];
 

package/dist/resources/extensions/gsd/auto-post-unit.ts

@@ -60,9 +60,32 @@ import {
   hideFooter,
 } from "./auto-dashboard.js";
 import { join } from "node:path";
+import { STATE_REBUILD_MIN_INTERVAL_MS } from "./auto-constants.js";
+import { parseUnitId } from "./unit-id.js";
 
-/** Throttle STATE.md rebuilds — at most once per 30 seconds */
-const STATE_REBUILD_MIN_INTERVAL_MS = 30_000;
+/**
+ * Initialize a unit dispatch: stamp the current time, set `s.currentUnit`,
+ * and persist the initial runtime record. Returns `startedAt` for callers
+ * that need the timestamp.
+ */
+function dispatchUnit(
+  s: AutoSession,
+  basePath: string,
+  unitType: string,
+  unitId: string,
+): number {
+  const startedAt = Date.now();
+  s.currentUnit = { type: unitType, id: unitId, startedAt };
+  writeUnitRuntimeRecord(basePath, unitType, unitId, startedAt, {
+    phase: "dispatched",
+    wrapupWarningSent: false,
+    timeoutAt: null,
+    lastProgressAt: startedAt,
+    progressCount: 0,
+    lastProgressKind: "dispatch",
+  });
+  return startedAt;
+}
 
 export interface PostUnitContext {
   s: AutoSession;
@@ -112,8 +135,7 @@ export async function postUnitPreVerification(pctx: PostUnitContext): Promise<"d
       let taskContext: TaskCommitContext | undefined;
 
       if (s.currentUnit.type === "execute-task") {
-        const parts = s.currentUnit.id.split("/");
-        const [mid, sid, tid] = parts;
+        const { milestone: mid, slice: sid, task: tid } = parseUnitId(s.currentUnit.id);
         if (mid && sid && tid) {
           const summaryPath = resolveTaskFile(s.basePath, mid, sid, tid, "SUMMARY");
           if (summaryPath) {
@@ -145,8 +167,8 @@ export async function postUnitPreVerification(pctx: PostUnitContext): Promise<"d
 
     // Doctor: fix mechanical bookkeeping
     try {
-      const scopeParts = s.currentUnit.id.split("/").slice(0, 2);
-      const doctorScope = scopeParts.join("/");
+      const { milestone, slice } = parseUnitId(s.currentUnit.id);
+      const doctorScope = slice ? `${milestone}/${slice}` : milestone;
       const sliceTerminalUnits = new Set(["complete-slice", "run-uat"]);
       const effectiveFixLevel = sliceTerminalUnits.has(s.currentUnit.type) ? "all" as const : "task" as const;
       const report = await runGSDDoctor(s.basePath, { fix: true, scope: doctorScope, fixLevel: effectiveFixLevel });
@@ -326,7 +348,7 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
   // instead of dispatching LLM sessions for complete-slice / validate-milestone.
   if (s.currentUnit?.type === "execute-task" && !s.stepMode) {
     try {
-      const [mid, sid] = s.currentUnit.id.split("/");
+      const { milestone: mid, slice: sid } = parseUnitId(s.currentUnit.id);
       if (mid && sid) {
         const state = await deriveState(s.basePath);
         if (state.phase === "summarizing" && state.activeSlice?.id === sid) {
@@ -364,19 +386,10 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
   if (s.currentUnit && !s.stepMode) {
     const hookUnit = checkPostUnitHooks(s.currentUnit.type, s.currentUnit.id, s.basePath);
     if (hookUnit) {
-      const hookStartedAt = Date.now();
       if (s.currentUnit) {
         await closeoutUnit(ctx, s.basePath, s.currentUnit.type, s.currentUnit.id, s.currentUnit.startedAt, buildSnapshotOpts(s.currentUnit.type, s.currentUnit.id));
       }
-      s.currentUnit = { type: hookUnit.unitType, id: hookUnit.unitId, startedAt: hookStartedAt };
-      writeUnitRuntimeRecord(s.basePath, hookUnit.unitType, hookUnit.unitId, hookStartedAt, {
-        phase: "dispatched",
-        wrapupWarningSent: false,
-        timeoutAt: null,
-        lastProgressAt: hookStartedAt,
-        progressCount: 0,
-        lastProgressKind: "dispatch",
-      });
+      dispatchUnit(s, s.basePath, hookUnit.unitType, hookUnit.unitId);
 
       const state = await deriveState(s.basePath);
       updateProgressWidget(ctx, hookUnit.unitType, hookUnit.unitId, state);
@@ -498,16 +511,7 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
 
             const triageUnitType = "triage-captures";
             const triageUnitId = `${mid}/${sid}/triage`;
-            const triageStartedAt = Date.now();
-            s.currentUnit = { type: triageUnitType, id: triageUnitId, startedAt: triageStartedAt };
-            writeUnitRuntimeRecord(s.basePath, triageUnitType, triageUnitId, triageStartedAt, {
-              phase: "dispatched",
-              wrapupWarningSent: false,
-              timeoutAt: null,
-              lastProgressAt: triageStartedAt,
-              progressCount: 0,
-              lastProgressKind: "dispatch",
-            });
+            dispatchUnit(s, s.basePath, triageUnitType, triageUnitId);
             updateProgressWidget(ctx, triageUnitType, triageUnitId, state);
 
             const result = await s.cmdCtx!.newSession();
@@ -568,16 +572,7 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
 
       const qtUnitType = "quick-task";
       const qtUnitId = `${s.currentMilestoneId}/${capture.id}`;
-      const qtStartedAt = Date.now();
-      s.currentUnit = { type: qtUnitType, id: qtUnitId, startedAt: qtStartedAt };
-      writeUnitRuntimeRecord(s.basePath, qtUnitType, qtUnitId, qtStartedAt, {
-        phase: "dispatched",
-        wrapupWarningSent: false,
-        timeoutAt: null,
-        lastProgressAt: qtStartedAt,
-        progressCount: 0,
-        lastProgressKind: "dispatch",
-      });
+      dispatchUnit(s, s.basePath, qtUnitType, qtUnitId);
       const state = await deriveState(s.basePath);
       updateProgressWidget(ctx, qtUnitType, qtUnitId, state);