gsd-pi 2.76.0-dev.fe143342a → 2.77.0-dev.1d17f366c

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

@@ -7,7 +7,7 @@
  */
 
 import { join } from "node:path";
-import { mkdirSync } from "node:fs";
+import { mkdirSync, existsSync } from "node:fs";
 
 import {
   transaction,
@@ -202,14 +202,20 @@ export async function handleCompleteMilestone(
     summaryPath = join(manualDir, `${params.milestoneId}-SUMMARY.md`);
   }
 
-  try {
-    await saveFile(summaryPath, summaryMd);
-  } catch (renderErr) {
-    // Disk render failed — roll back DB status so state stays consistent
-    logWarning("tool", `complete_milestone — disk render failed, rolling back DB status: ${(renderErr as Error).message}`);
-    updateMilestoneStatus(params.milestoneId, 'active', null);
-    invalidateStateCache();
-    return { error: `disk render failed: ${(renderErr as Error).message}` };
+  // Guard (#4598): if SUMMARY.md already exists on disk, do not overwrite it.
+  // This handles re-dispatch scenarios (DB/disk state divergence) where a prior
+  // completion already wrote the file. Overwriting would silently destroy the
+  // richer content the agent produced during the original completion run.
+  if (!existsSync(summaryPath)) {
+    try {
+      await saveFile(summaryPath, summaryMd);
+    } catch (renderErr) {
+      // Disk render failed — roll back DB status so state stays consistent
+      logWarning("tool", `complete_milestone — disk render failed, rolling back DB status: ${(renderErr as Error).message}`);
+      updateMilestoneStatus(params.milestoneId, 'active', null);
+      invalidateStateCache();
+      return { error: `disk render failed: ${(renderErr as Error).message}` };
+    }
   }
 
   // Invalidate all caches

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/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,

package/src/resources/extensions/gsd/uok/loop-adapter.ts

@@ -6,6 +6,7 @@ import type {
 } from "./contracts.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./audit.js";
 import { writeTurnCloseoutGitRecord, writeTurnGitTransaction } from "./gitops.js";
+import { acquireWriterToken, nextWriteRecord, releaseWriterToken } from "./writer.js";
 
 export interface CreateTurnObserverOptions {
   basePath: string;
@@ -17,12 +18,38 @@ export interface CreateTurnObserverOptions {
 
 export function createTurnObserver(options: CreateTurnObserverOptions): UokTurnObserver {
   let current: TurnContract | null = null;
+  let writerToken: ReturnType<typeof acquireWriterToken> | null = null;
   const phaseResults: TurnResult["phaseResults"] = [];
 
+  function nextSequenceMetadata(
+    category: "audit" | "gitops",
+    operation: "append" | "insert" | "update",
+    metadata?: Record<string, unknown>,
+  ): Record<string, unknown> {
+    if (!writerToken) return metadata ?? {};
+    const record = nextWriteRecord({
+      basePath: options.basePath,
+      token: writerToken,
+      category,
+      operation,
+      metadata,
+    });
+    return {
+      ...(metadata ?? {}),
+      writeSequence: record.sequence.sequence,
+      writerTokenId: record.writerToken.tokenId,
+    };
+  }
+
   return {
     onTurnStart(contract): void {
       current = contract;
       phaseResults.length = 0;
+      writerToken = acquireWriterToken({
+        basePath: options.basePath,
+        traceId: contract.traceId,
+        turnId: contract.turnId,
+      });
 
       if (options.enableGitops) {
         writeTurnGitTransaction({
@@ -35,10 +62,10 @@ export function createTurnObserver(options: CreateTurnObserverOptions): UokTurnO
           action: options.gitAction,
           push: options.gitPush,
           status: "ok",
-          metadata: {
+          metadata: nextSequenceMetadata("gitops", "insert", {
             iteration: contract.iteration,
             sidecarKind: contract.sidecarKind,
-          },
+          }),
         });
       }
 
@@ -50,12 +77,12 @@ export function createTurnObserver(options: CreateTurnObserverOptions): UokTurnO
             turnId: contract.turnId,
             category: "orchestration",
             type: "turn-start",
-            payload: {
+            payload: nextSequenceMetadata("audit", "append", {
               iteration: contract.iteration,
               unitType: contract.unitType,
               unitId: contract.unitId,
               sidecarKind: contract.sidecarKind,
-            },
+            }),
           }),
         );
       }
@@ -81,7 +108,7 @@ export function createTurnObserver(options: CreateTurnObserverOptions): UokTurnO
           action: options.gitAction,
           push: options.gitPush,
           status: "ok",
-          metadata: { action },
+          metadata: nextSequenceMetadata("gitops", "update", { action }),
         });
       }
       if (phase === "unit") {
@@ -95,7 +122,7 @@ export function createTurnObserver(options: CreateTurnObserverOptions): UokTurnO
           action: options.gitAction,
           push: options.gitPush,
           status: "ok",
-          metadata: { action },
+          metadata: nextSequenceMetadata("gitops", "update", { action }),
         });
       }
       if (phase === "finalize") {
@@ -109,7 +136,7 @@ export function createTurnObserver(options: CreateTurnObserverOptions): UokTurnO
           action: options.gitAction,
           push: options.gitPush,
           status: "ok",
-          metadata: { action },
+          metadata: nextSequenceMetadata("gitops", "update", { action }),
         });
       }
     },
@@ -128,14 +155,14 @@ export function createTurnObserver(options: CreateTurnObserverOptions): UokTurnO
             turnId: merged.turnId,
             category: "orchestration",
             type: "turn-result",
-            payload: {
+            payload: nextSequenceMetadata("audit", "append", {
               unitType: merged.unitType,
               unitId: merged.unitId,
               status: merged.status,
               failureClass: merged.failureClass,
               error: merged.error,
               phaseCount: merged.phaseResults.length,
-            },
+            }),
           }),
         );
       }
@@ -152,9 +179,17 @@ export function createTurnObserver(options: CreateTurnObserverOptions): UokTurnO
           gitPushed: options.gitPush,
           finishedAt: merged.finishedAt,
         };
-        writeTurnCloseoutGitRecord(options.basePath, closeout);
+        writeTurnCloseoutGitRecord(
+          options.basePath,
+          closeout,
+          nextSequenceMetadata("gitops", "update", { action: "record" }),
+        );
       }
 
+      if (writerToken) {
+        releaseWriterToken(options.basePath, writerToken);
+      }
+      writerToken = null;
       current = null;
       phaseResults.length = 0;
     },

package/src/resources/extensions/gsd/uok/parity-report.ts

@@ -0,0 +1,84 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { gsdRoot } from "../paths.js";
+
+export interface UokParityEvent {
+  ts?: string;
+  path?: string;
+  phase?: string;
+  status?: string;
+  error?: string;
+  flags?: Record<string, unknown>;
+}
+
+export interface UokParityReport {
+  generatedAt: string;
+  sourcePath: string;
+  totalEvents: number;
+  paths: Record<string, number>;
+  statuses: Record<string, number>;
+  criticalMismatches: string[];
+  fallbackInvocations: number;
+}
+
+function parityLogPath(basePath: string): string {
+  return join(gsdRoot(basePath), "runtime", "uok-parity.jsonl");
+}
+
+function reportPath(basePath: string): string {
+  return join(gsdRoot(basePath), "runtime", "uok-parity-report.json");
+}
+
+function increment(bucket: Record<string, number>, key: string | undefined): void {
+  const normalized = key && key.trim().length > 0 ? key : "unknown";
+  bucket[normalized] = (bucket[normalized] ?? 0) + 1;
+}
+
+export function parseParityEvents(raw: string): UokParityEvent[] {
+  return raw
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line) as UokParityEvent;
+      } catch {
+        return { status: "error", error: "invalid parity json line" };
+      }
+    });
+}
+
+export function buildParityReport(events: readonly UokParityEvent[], sourcePath: string): UokParityReport {
+  const paths: Record<string, number> = {};
+  const statuses: Record<string, number> = {};
+  const criticalMismatches: string[] = [];
+  let fallbackInvocations = 0;
+
+  for (const event of events) {
+    increment(paths, event.path);
+    increment(statuses, event.status);
+    if (event.path === "legacy-fallback") fallbackInvocations += 1;
+    if (event.status === "error") {
+      criticalMismatches.push(event.error ?? "parity event reported error");
+    }
+  }
+
+  return {
+    generatedAt: new Date().toISOString(),
+    sourcePath,
+    totalEvents: events.length,
+    paths,
+    statuses,
+    criticalMismatches,
+    fallbackInvocations,
+  };
+}
+
+export function writeParityReport(basePath: string): UokParityReport {
+  const sourcePath = parityLogPath(basePath);
+  const raw = existsSync(sourcePath) ? readFileSync(sourcePath, "utf-8") : "";
+  const report = buildParityReport(parseParityEvents(raw), sourcePath);
+  mkdirSync(join(gsdRoot(basePath), "runtime"), { recursive: true });
+  writeFileSync(reportPath(basePath), JSON.stringify(report, null, 2) + "\n", "utf-8");
+  return report;
+}