gsd-pi 2.77.0-dev.538325aea → 2.77.0-dev.58d3d4d6c

package/src/resources/extensions/gsd/tests/worktree-telemetry.test.ts

@@ -0,0 +1,210 @@
+/**
+ * Tests for worktree telemetry — #4764.
+ *
+ * Covers emit helpers (writing to the journal) and the aggregator
+ * (summarizeWorktreeTelemetry).
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+
+import {
+  emitWorktreeCreated,
+  emitWorktreeMerged,
+  emitWorktreeOrphaned,
+  emitAutoExit,
+  emitCanonicalRootRedirect,
+  summarizeWorktreeTelemetry,
+  percentile,
+} from "../worktree-telemetry.ts";
+import { resolveCanonicalMilestoneRoot } from "../worktree-manager.ts";
+import { queryJournal } from "../journal.ts";
+
+function makeTmpBase(): string {
+  const base = join(tmpdir(), `gsd-tel-test-${randomUUID()}`);
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  return base;
+}
+
+function cleanup(base: string): void {
+  try { rmSync(base, { recursive: true, force: true }); } catch { /* */ }
+}
+
+test("emitWorktreeCreated writes a worktree-created journal event", () => {
+  const base = makeTmpBase();
+  try {
+    emitWorktreeCreated(base, "M001", { reason: "create-milestone" });
+    const entries = queryJournal(base, { eventType: "worktree-created" });
+    assert.equal(entries.length, 1);
+    assert.equal(entries[0].data?.milestoneId, "M001");
+    assert.equal(entries[0].data?.reason, "create-milestone");
+    assert.ok(typeof entries[0].data?.startedAt === "string");
+  } finally { cleanup(base); }
+});
+
+test("emitWorktreeMerged records duration and conflict fields", () => {
+  const base = makeTmpBase();
+  try {
+    emitWorktreeMerged(base, "M001", {
+      reason: "milestone-complete",
+      durationMs: 1234,
+      sliceCount: 3,
+      taskCount: 9,
+      conflict: false,
+    });
+    const entries = queryJournal(base, { eventType: "worktree-merged" });
+    assert.equal(entries.length, 1);
+    assert.equal(entries[0].data?.milestoneId, "M001");
+    assert.equal(entries[0].data?.durationMs, 1234);
+    assert.equal(entries[0].data?.sliceCount, 3);
+    assert.equal(entries[0].data?.conflict, false);
+  } finally { cleanup(base); }
+});
+
+test("emitWorktreeOrphaned captures reason and commits-ahead", () => {
+  const base = makeTmpBase();
+  try {
+    emitWorktreeOrphaned(base, "M002", {
+      reason: "in-progress-unmerged",
+      commitsAhead: 4,
+      worktreeDirExists: true,
+    });
+    const entries = queryJournal(base, { eventType: "worktree-orphaned" });
+    assert.equal(entries.length, 1);
+    assert.equal(entries[0].data?.milestoneId, "M002");
+    assert.equal(entries[0].data?.reason, "in-progress-unmerged");
+    assert.equal(entries[0].data?.commitsAhead, 4);
+    assert.equal(entries[0].data?.worktreeDirExists, true);
+  } finally { cleanup(base); }
+});
+
+test("emitAutoExit records reason and unmerged-work signal", () => {
+  const base = makeTmpBase();
+  try {
+    emitAutoExit(base, {
+      reason: "pause",
+      milestoneId: "M003",
+      milestoneMerged: false,
+    });
+    const entries = queryJournal(base, { eventType: "auto-exit" });
+    assert.equal(entries.length, 1);
+    assert.equal(entries[0].data?.reason, "pause");
+    assert.equal(entries[0].data?.milestoneMerged, false);
+  } finally { cleanup(base); }
+});
+
+test("summarizeWorktreeTelemetry aggregates events correctly", () => {
+  const base = makeTmpBase();
+  try {
+    // Two created, one merged, two orphans (different reasons), three exits,
+    // two of which left work unmerged.
+    emitWorktreeCreated(base, "M001");
+    emitWorktreeCreated(base, "M002");
+
+    emitWorktreeMerged(base, "M001", { reason: "milestone-complete", durationMs: 500, conflict: false });
+
+    emitWorktreeOrphaned(base, "M002", { reason: "in-progress-unmerged", commitsAhead: 2 });
+    emitWorktreeOrphaned(base, "M003", { reason: "complete-unmerged" });
+
+    emitAutoExit(base, { reason: "pause", milestoneId: "M002", milestoneMerged: false });
+    emitAutoExit(base, { reason: "stop", milestoneId: "M002", milestoneMerged: false });
+    emitAutoExit(base, { reason: "all-complete", milestoneId: "M001", milestoneMerged: true });
+
+    const summary = summarizeWorktreeTelemetry(base);
+    assert.equal(summary.worktreesCreated, 2);
+    assert.equal(summary.worktreesMerged, 1);
+    assert.equal(summary.orphansDetected, 2);
+    assert.deepStrictEqual(summary.orphansByReason, {
+      "in-progress-unmerged": 1,
+      "complete-unmerged": 1,
+    });
+    assert.deepStrictEqual(summary.mergeDurationsMs, [500]);
+    assert.equal(summary.mergeConflicts, 0);
+    assert.deepStrictEqual(summary.exitsByReason, {
+      "pause": 1,
+      "stop": 1,
+      "all-complete": 1,
+    });
+    assert.equal(summary.exitsWithUnmergedWork, 2, "pause and stop each left work unmerged");
+  } finally { cleanup(base); }
+});
+
+test("summarizeWorktreeTelemetry counts merge conflicts", () => {
+  const base = makeTmpBase();
+  try {
+    emitWorktreeMerged(base, "M001", { reason: "milestone-complete", durationMs: 100, conflict: false });
+    emitWorktreeMerged(base, "M002", { reason: "milestone-complete", durationMs: 200, conflict: true, conflictedFiles: 3 });
+    emitWorktreeMerged(base, "M003", { reason: "milestone-complete", durationMs: 150, conflict: false });
+
+    const summary = summarizeWorktreeTelemetry(base);
+    assert.equal(summary.worktreesMerged, 3);
+    assert.equal(summary.mergeConflicts, 1);
+    // Durations are sorted
+    assert.deepStrictEqual(summary.mergeDurationsMs, [100, 150, 200]);
+  } finally { cleanup(base); }
+});
+
+test("resolveCanonicalMilestoneRoot emits canonical-root-redirect on redirect", () => {
+  const base = makeTmpBase();
+  try {
+    // Create the live-worktree shape the resolver looks for
+    const wtDir = join(base, ".gsd", "worktrees", "M001");
+    mkdirSync(wtDir, { recursive: true });
+    writeFileSync(join(wtDir, ".git"), `gitdir: ${join(base, ".git", "worktrees", "M001")}\n`);
+
+    const result = resolveCanonicalMilestoneRoot(base, "M001");
+    assert.equal(result, wtDir);
+
+    const summary = summarizeWorktreeTelemetry(base);
+    assert.equal(summary.canonicalRedirects, 1, "redirect should emit exactly one event");
+  } finally { cleanup(base); }
+});
+
+test("resolveCanonicalMilestoneRoot emits nothing when it doesn't redirect", () => {
+  const base = makeTmpBase();
+  try {
+    const result = resolveCanonicalMilestoneRoot(base, "M999");
+    assert.equal(result, base);
+
+    const summary = summarizeWorktreeTelemetry(base);
+    assert.equal(summary.canonicalRedirects, 0, "no worktree → no redirect event");
+  } finally { cleanup(base); }
+});
+
+test("percentile helper returns quantiles of a sorted array (nearest-rank)", () => {
+  assert.equal(percentile([], 0.5), null);
+  assert.equal(percentile([10], 0.5), 10);
+  // Boundary behavior
+  assert.equal(percentile([10, 20, 30, 40], 0), 10);
+  assert.equal(percentile([10, 20, 30, 40], 1), 40);
+  // Nearest-rank: idx = ceil(q*n) - 1
+  // q=0.5, n=4 → idx = 2-1 = 1 → 20
+  assert.equal(percentile([10, 20, 30, 40], 0.5), 20);
+  // p95 on 20 values = idx ceil(0.95*20)-1 = 19-1 = 18 → value at index 18 (19th sample)
+  const twenty = Array.from({ length: 20 }, (_, i) => (i + 1) * 10); // [10..200]
+  assert.equal(percentile(twenty, 0.95), 190, "p95 should be the 19th of 20 sorted values, not the max");
+});
+
+test("summarizeWorktreeTelemetry supports time-window filtering", () => {
+  const base = makeTmpBase();
+  try {
+    emitWorktreeCreated(base, "M001");
+    const midpoint = new Date().toISOString();
+    // Brief delay to ensure the next event has a later ts
+    const start = Date.now();
+    while (Date.now() - start < 10) { /* spin */ }
+    emitWorktreeCreated(base, "M002");
+
+    const beforeOnly = summarizeWorktreeTelemetry(base, { before: midpoint });
+    const afterOnly = summarizeWorktreeTelemetry(base, { after: midpoint });
+    // The sum of the two partitions covers all events (may overlap by 1 at
+    // exact-ts boundary — assert each partition is a proper subset).
+    assert.ok(beforeOnly.worktreesCreated >= 1);
+    assert.ok(afterOnly.worktreesCreated >= 1);
+    assert.ok(beforeOnly.worktreesCreated + afterOnly.worktreesCreated >= 2);
+  } finally { cleanup(base); }
+});

package/src/resources/extensions/gsd/tests/zombie-gsd-state.test.ts

@@ -1,7 +1,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
-import { createTestContext } from "./test-helpers.ts";
+import {createTestContext, extractSourceRegion } from "./test-helpers.ts";
 
 const { assertTrue, assertMatch, assertNoMatch, report } = createTestContext();
 
@@ -26,7 +26,7 @@ assertTrue(smartEntryIdx >= 0, "guided-flow.ts defines showSmartEntry");
 
 // Extract the region between showSmartEntry and the first showProjectInit call
 // This is where the init wizard gate lives.
-const afterSmartEntry = smartEntryIdx >= 0 ? guidedFlowSrc.slice(smartEntryIdx, smartEntryIdx + 3000) : "";
+const afterSmartEntry = smartEntryIdx >= 0 ? extractSourceRegion(guidedFlowSrc, "export async function showSmartEntry(") : "";
 
 // The gate must NOT be a bare `!existsSync(gsdRoot(basePath))` check.
 // It must also verify that bootstrap artifacts (PREFERENCES.md or milestones/) exist.
@@ -48,7 +48,7 @@ assertTrue(
 // Find the specific init wizard gate pattern — the detection preamble block.
 const detectionPreambleIdx = afterSmartEntry.indexOf("Detection preamble");
 const detectionRegion = detectionPreambleIdx >= 0
-  ? afterSmartEntry.slice(detectionPreambleIdx, detectionPreambleIdx + 600)
+  ? extractSourceRegion(afterSmartEntry, "Detection preamble")
   : afterSmartEntry.slice(0, 1500);
 
 // The gate condition must reference PREFERENCES.md or milestones (bootstrap artifacts)

package/src/resources/extensions/gsd/tools/complete-slice.ts

@@ -30,6 +30,7 @@ import { checkOwnership, sliceUnitKey } from "../unit-ownership.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
 import { renderRoadmapCheckboxes } from "../markdown-renderer.js";
+import { isStaleWrite } from "../auto/turn-epoch.js";
 import { renderAllProjections } from "../workflow-projections.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
@@ -40,6 +41,14 @@ export interface CompleteSliceResult {
   milestoneId: string;
   summaryPath: string;
   uatPath: string;
+  /**
+   * True when this call re-completed an already-closed slice from a turn
+   * superseded by timeout recovery or cancellation. Response is shaped like
+   * success so the orphaned LLM tool call unwinds cleanly without mutating
+   * state.
+   */
+  duplicate?: boolean;
+  stale?: boolean;
 }
 
 /**
@@ -283,6 +292,10 @@ export async function handleCompleteSlice(
 
     const slice = getSlice(params.milestoneId, params.sliceId);
     if (slice && isClosedStatus(slice.status)) {
+      if (isStaleWrite("complete-slice")) {
+        guardError = "__stale_duplicate__";
+        return;
+      }
       guardError = `slice ${params.sliceId} is already complete — use gsd_slice_reopen first if you need to redo it`;
       return;
     }
@@ -307,6 +320,31 @@ export async function handleCompleteSlice(
     updateSliceStatus(params.milestoneId, params.sliceId, "complete", completedAt);
   });
 
+  if (guardError === "__stale_duplicate__") {
+    // Stale duplicate from a turn superseded by timeout recovery. Return a
+    // non-mutating success so the orphaned LLM tool call unwinds quietly.
+    const sliceDir = resolveSlicePath(basePath, params.milestoneId, params.sliceId);
+    const staleSummaryPath = sliceDir
+      ? join(sliceDir, `${params.sliceId}-SUMMARY.md`)
+      : join(
+          basePath,
+          ".gsd",
+          "milestones",
+          params.milestoneId,
+          "slices",
+          params.sliceId,
+          `${params.sliceId}-SUMMARY.md`,
+        );
+    return {
+      sliceId: params.sliceId,
+      milestoneId: params.milestoneId,
+      summaryPath: staleSummaryPath,
+      uatPath: staleSummaryPath.replace(/-SUMMARY\.md$/, "-UAT.md"),
+      duplicate: true,
+      stale: true,
+    };
+  }
+
   if (guardError) {
     return { error: guardError };
   }

package/src/resources/extensions/gsd/tools/complete-task.ts

@@ -38,6 +38,7 @@ import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning, logError } from "../workflow-logger.js";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
+import { isStaleWrite } from "../auto/turn-epoch.js";
 import { buildEscalationArtifact, writeEscalationArtifact } from "../escalation.js";
 
 export interface CompleteTaskResult {
@@ -45,6 +46,14 @@ export interface CompleteTaskResult {
   sliceId: string;
   milestoneId: string;
   summaryPath: string;
+  /**
+   * True when this call re-completed an already-closed task from a turn that
+   * had been superseded by timeout recovery or cancellation. The underlying
+   * state was not mutated; the response is a no-op shaped like a success so
+   * the orphaned LLM tool call resolves cleanly.
+   */
+  duplicate?: boolean;
+  stale?: boolean;
 }
 
 import type { TaskRow } from "../gsd-db.js";
@@ -211,6 +220,18 @@ export async function handleCompleteTask(
 
     const existingTask = getTask(params.milestoneId, params.sliceId, params.taskId);
     if (existingTask && isClosedStatus(existingTask.status)) {
+      // Stale-turn path: a timed-out turn that was superseded by recovery
+      // can still reach this code when its LLM call eventually returns and
+      // invokes gsd_complete_task. Returning an error would produce noisy
+      // "already complete — use reopen first" logs in the orphaned turn.
+      // Instead, signal the duplicate via a non-mutating success shape that
+      // callers can detect via `duplicate: true` / `stale: true`.
+      if (isStaleWrite("complete-task")) {
+        // Sentinel handled below — outside the transaction — so we don't
+        // render SUMMARY.md or flip plan checkboxes for a stale duplicate.
+        guardError = "__stale_duplicate__";
+        return;
+      }
       guardError = `task ${params.taskId} is already complete — use gsd_task_reopen first if you need to redo it`;
       return;
     }
@@ -248,6 +269,34 @@ export async function handleCompleteTask(
     }
   });
 
+  if (guardError === "__stale_duplicate__") {
+    // Orphaned-turn duplicate: the task is already complete from the
+    // superseded turn's earlier (real) call. Return a non-mutating success
+    // so the stale LLM tool call unwinds cleanly. summaryPath is synthesized
+    // from the existing on-disk layout; no file is written.
+    const tasksDir = resolveTasksDir(basePath, params.milestoneId, params.sliceId);
+    const staleSummaryPath = tasksDir
+      ? join(tasksDir, `${params.taskId}-SUMMARY.md`)
+      : join(
+          basePath,
+          ".gsd",
+          "milestones",
+          params.milestoneId,
+          "slices",
+          params.sliceId,
+          "tasks",
+          `${params.taskId}-SUMMARY.md`,
+        );
+    return {
+      taskId: params.taskId,
+      sliceId: params.sliceId,
+      milestoneId: params.milestoneId,
+      summaryPath: staleSummaryPath,
+      duplicate: true,
+      stale: true,
+    };
+  }
+
   if (guardError) {
     return { error: guardError };
   }

package/src/resources/extensions/gsd/tools/validate-milestone.ts

@@ -18,6 +18,7 @@ import {
   getMilestoneSlices,
 } from "../gsd-db.js";
 import { resolveMilestonePath, clearPathCache } from "../paths.js";
+import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
 import { VALIDATION_VERDICTS, isValidMilestoneVerdict } from "../verdict-parser.js";
@@ -100,14 +101,19 @@ export async function handleValidateMilestone(
   }
 
   // ── Resolve paths and render markdown ────────────────────────────────
+  // #4761: route through the canonical-root resolver so that when a live
+  // worktree exists for this milestone, validation reads/writes the
+  // worktree's artifacts instead of stale project-root state.
   const validationMd = renderValidationMarkdown(params);
 
+  const canonicalBase = resolveCanonicalMilestoneRoot(basePath, params.milestoneId);
+
   let validationPath: string;
-  const milestoneDir = resolveMilestonePath(basePath, params.milestoneId);
+  const milestoneDir = resolveMilestonePath(canonicalBase, params.milestoneId);
   if (milestoneDir) {
     validationPath = join(milestoneDir, `${params.milestoneId}-VALIDATION.md`);
   } else {
-    const gsdDir = join(basePath, ".gsd");
+    const gsdDir = join(canonicalBase, ".gsd");
     const manualDir = join(gsdDir, "milestones", params.milestoneId);
     validationPath = join(manualDir, `${params.milestoneId}-VALIDATION.md`);
   }

package/src/resources/extensions/gsd/uok/audit.ts

@@ -1,7 +1,9 @@
-import { appendFileSync, mkdirSync } from "node:fs";
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync } from "node:fs";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
 
+import { isStaleWrite } from "../auto/turn-epoch.js";
+import { withFileLockSync } from "../file-lock.js";
 import { gsdRoot } from "../paths.js";
 import { isDbAvailable, insertAuditEvent } from "../gsd-db.js";
 import type { AuditEventEnvelope } from "./contracts.js";
@@ -35,9 +37,25 @@ export function buildAuditEnvelope(args: {
 }
 
 export function emitUokAuditEvent(basePath: string, event: AuditEventEnvelope): void {
+  // Drop writes from a turn superseded by timeout recovery / cancellation.
+  if (isStaleWrite("uok-audit")) return;
   try {
     ensureAuditDir(basePath);
-    appendFileSync(auditLogPath(basePath), `${JSON.stringify(event)}\n`, "utf-8");
+    const path = auditLogPath(basePath);
+    // proper-lockfile requires the target file to exist before locking.
+    // Touch it via open(O_APPEND|O_CREAT) so the first writer wins the race
+    // atomically at the kernel level.
+    if (!existsSync(path)) closeSync(openSync(path, "a"));
+    // onLocked: "skip" — audit writes are best-effort; under heavy contention
+    // POSIX O_APPEND atomicity still protects small line writes, so skipping
+    // the lock rather than stalling orchestration is the correct tradeoff.
+    withFileLockSync(
+      path,
+      () => {
+        appendFileSync(path, `${JSON.stringify(event)}\n`, "utf-8");
+      },
+      { onLocked: "skip" },
+    );
   } catch {
     // Best-effort: audit writes must never break orchestration.
   }

package/src/resources/extensions/gsd/uok/contracts.ts

@@ -13,6 +13,15 @@ export type FailureClass =
 
 export type GateOutcome = "pass" | "fail" | "retry" | "manual-attention";
 
+export type DispatchReasonCode =
+  | "policy"
+  | "state"
+  | "recovery"
+  | "manual"
+  | "dependency"
+  | "conflict"
+  | "retry";
+
 export interface GateResult {
   gateId: string;
   gateType: string;
@@ -88,6 +97,38 @@ export interface TurnResult {
   finishedAt: string;
 }
 
+export interface DispatchExplanation {
+  reasonCode: DispatchReasonCode;
+  summary: string;
+  evidence?: Record<string, unknown>;
+  blockedBy?: Array<{
+    kind: "gate" | "state" | "dependency" | "conflict" | "policy" | "manual";
+    id: string;
+    detail?: string;
+  }>;
+}
+
+export interface UokDispatchEnvelope {
+  action: "dispatch" | "stop" | "skip";
+  nodeKind?: UokNodeKind;
+  unitType?: string;
+  unitId?: string;
+  prompt?: string;
+  reason: DispatchExplanation;
+  gateVerdict?: GateResult;
+  constraints?: {
+    reads?: string[];
+    writes?: string[];
+    dependsOn?: string[];
+    maxWorkers?: number;
+  };
+  trace?: {
+    traceId?: string;
+    turnId?: string;
+    causedBy?: string;
+  };
+}
+
 export interface AuditEventEnvelope {
   eventId: string;
   traceId: string;
@@ -125,6 +166,30 @@ export interface UokGraphNode {
   metadata?: Record<string, unknown>;
 }
 
+export interface WriterToken {
+  tokenId: string;
+  traceId: string;
+  turnId: string;
+  acquiredAt: string;
+  owner: "uok" | "legacy-compat" | "manual";
+}
+
+export interface WriteSequence {
+  traceId: string;
+  turnId: string;
+  sequence: number;
+}
+
+export interface WriteRecord {
+  writerToken: WriterToken;
+  sequence: WriteSequence;
+  category: "state" | "audit" | "gitops" | "gate" | "artifact" | "other";
+  path?: string;
+  operation: "append" | "replace" | "insert" | "update" | "delete" | "noop";
+  ts: string;
+  metadata?: Record<string, unknown>;
+}
+
 export interface UokTurnObserver {
   onTurnStart(contract: TurnContract): void;
   onPhaseResult(

package/src/resources/extensions/gsd/uok/dispatch-envelope.ts

@@ -0,0 +1,56 @@
+import type {
+  DispatchExplanation,
+  DispatchReasonCode,
+  GateResult,
+  UokDispatchEnvelope,
+  UokGraphNode,
+} from "./contracts.js";
+
+export interface BuildDispatchEnvelopeInput {
+  action: UokDispatchEnvelope["action"];
+  node?: Pick<UokGraphNode, "kind" | "reads" | "writes" | "dependsOn">;
+  unitType?: string;
+  unitId?: string;
+  prompt?: string;
+  reasonCode: DispatchReasonCode;
+  summary: string;
+  evidence?: Record<string, unknown>;
+  blockedBy?: DispatchExplanation["blockedBy"];
+  gateVerdict?: GateResult;
+  trace?: UokDispatchEnvelope["trace"];
+}
+
+export function buildDispatchEnvelope(input: BuildDispatchEnvelopeInput): UokDispatchEnvelope {
+  return {
+    action: input.action,
+    nodeKind: input.node?.kind,
+    unitType: input.unitType,
+    unitId: input.unitId,
+    prompt: input.prompt,
+    reason: {
+      reasonCode: input.reasonCode,
+      summary: input.summary,
+      evidence: input.evidence,
+      blockedBy: input.blockedBy,
+    },
+    gateVerdict: input.gateVerdict,
+    constraints: input.node
+      ? {
+          reads: input.node.reads,
+          writes: input.node.writes,
+          dependsOn: input.node.dependsOn,
+        }
+      : undefined,
+    trace: input.trace,
+  };
+}
+
+export function explainDispatch(envelope: UokDispatchEnvelope): string {
+  const subject = envelope.unitType && envelope.unitId
+    ? `${envelope.unitType} ${envelope.unitId}`
+    : envelope.nodeKind ?? envelope.action;
+  const blocked = envelope.reason.blockedBy && envelope.reason.blockedBy.length > 0
+    ? ` Blocked by: ${envelope.reason.blockedBy.map((b) => `${b.kind}:${b.id}`).join(", ")}.`
+    : "";
+  return `[${envelope.reason.reasonCode}] ${subject}: ${envelope.reason.summary}.${blocked}`;
+}

package/src/resources/extensions/gsd/uok/execution-graph.ts

@@ -12,6 +12,14 @@ export interface ExecutionGraphResult {
   conflicts: Array<{ nodeA: string; nodeB: string; file: string }>;
 }
 
+export interface ExecutionGraphSnapshot {
+  capturedAt: string;
+  phase: "before-unit" | "after-unit";
+  nodes: UokGraphNode[];
+  order: string[];
+  conflicts: Array<{ nodeA: string; nodeB: string; file: string }>;
+}
+
 export type ExecutionNodeHandler = (node: UokGraphNode) => Promise<void>;
 
 export interface ConflictFreeBatchInput {
@@ -113,6 +121,20 @@ export function buildSidecarQueueNodes(queue: SidecarItem[]): UokGraphNode[] {
   }));
 }
 
+export function buildExecutionGraphSnapshot(
+  nodes: UokGraphNode[],
+  phase: ExecutionGraphSnapshot["phase"],
+): ExecutionGraphSnapshot {
+  const sorted = topologicalSort(nodes);
+  return {
+    capturedAt: new Date().toISOString(),
+    phase,
+    nodes: sorted,
+    order: sorted.map((node) => node.id),
+    conflicts: detectFileConflicts(nodes),
+  };
+}
+
 export async function scheduleSidecarQueue(queue: SidecarItem[]): Promise<SidecarItem[]> {
   if (queue.length <= 1) return [...queue];
   const nodes = buildSidecarQueueNodes(queue);

package/src/resources/extensions/gsd/uok/gitops.ts

@@ -54,7 +54,11 @@ export function writeTurnGitTransaction(args: GitTxArgs): void {
   );
 }
 
-export function writeTurnCloseoutGitRecord(basePath: string, record: TurnCloseoutRecord): void {
+export function writeTurnCloseoutGitRecord(
+  basePath: string,
+  record: TurnCloseoutRecord,
+  metadata?: Record<string, unknown>,
+): void {
   writeTurnGitTransaction({
     basePath,
     traceId: record.traceId,
@@ -67,6 +71,7 @@ export function writeTurnCloseoutGitRecord(basePath: string, record: TurnCloseou
     status: record.failureClass === "git" ? "failed" : "ok",
     error: record.failureClass === "git" ? "git closeout failure" : undefined,
     metadata: {
+      ...(metadata ?? {}),
       turnStatus: record.status,
       finishedAt: record.finishedAt,
       activityFile: record.activityFile,