gsd-pi 2.77.0-dev.538325aea → 2.77.0-dev.eaa4973bc

package/src/resources/extensions/gsd/tests/turn-epoch.test.ts

@@ -0,0 +1,162 @@
+// Project: gsd-pi — Tests for the auto/turn-epoch stale-write guard.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  _resetTurnEpoch,
+  bumpTurnGeneration,
+  describeTurnEpoch,
+  getCurrentTurnGeneration,
+  isStaleWrite,
+  runWithTurnGeneration,
+} from "../auto/turn-epoch.ts";
+
+test("turn-epoch: generation starts at 0 and bumps monotonically", () => {
+  _resetTurnEpoch();
+  assert.equal(getCurrentTurnGeneration(), 0);
+  assert.equal(bumpTurnGeneration("test-a"), 1);
+  assert.equal(bumpTurnGeneration("test-b"), 2);
+  assert.equal(getCurrentTurnGeneration(), 2);
+});
+
+test("turn-epoch: isStaleWrite returns false when no turn context captured", () => {
+  _resetTurnEpoch();
+  bumpTurnGeneration("no-context");
+  // Called outside runWithTurnGeneration — safe default is false.
+  assert.equal(isStaleWrite("out-of-band"), false);
+});
+
+test("turn-epoch: isStaleWrite returns false inside a fresh turn", () => {
+  _resetTurnEpoch();
+  const captured = getCurrentTurnGeneration();
+  runWithTurnGeneration(captured, () => {
+    assert.equal(isStaleWrite("fresh"), false);
+  });
+});
+
+test("turn-epoch: isStaleWrite returns true after the epoch bumps mid-turn", () => {
+  _resetTurnEpoch();
+  const captured = getCurrentTurnGeneration();
+  runWithTurnGeneration(captured, () => {
+    bumpTurnGeneration("recovery-fires");
+    assert.equal(isStaleWrite("stale"), true);
+  });
+});
+
+test("turn-epoch: nested turns each see their own captured generation", () => {
+  _resetTurnEpoch();
+  const outerGen = getCurrentTurnGeneration();
+  runWithTurnGeneration(outerGen, () => {
+    assert.equal(isStaleWrite("outer-fresh"), false);
+    bumpTurnGeneration("bump-between");
+    const innerGen = getCurrentTurnGeneration();
+    runWithTurnGeneration(innerGen, () => {
+      // Inner context saw the bumped generation at capture time — fresh.
+      assert.equal(isStaleWrite("inner-fresh"), false);
+    });
+    // Back to outer context — still stale because outerGen < current.
+    assert.equal(isStaleWrite("outer-after-bump"), true);
+  });
+});
+
+test("turn-epoch: describeTurnEpoch surfaces captured vs current", () => {
+  _resetTurnEpoch();
+  bumpTurnGeneration("seed");
+  const captured = getCurrentTurnGeneration();
+  runWithTurnGeneration(captured, () => {
+    let snapshot = describeTurnEpoch();
+    assert.equal(snapshot.captured, captured);
+    assert.equal(snapshot.current, captured);
+    assert.equal(snapshot.stale, false);
+
+    bumpTurnGeneration("supersede");
+    snapshot = describeTurnEpoch();
+    assert.equal(snapshot.captured, captured);
+    assert.equal(snapshot.current, captured + 1);
+    assert.equal(snapshot.stale, true);
+  });
+
+  // Outside the turn — captured is null, stale is false.
+  const outside = describeTurnEpoch();
+  assert.equal(outside.captured, null);
+  assert.equal(outside.stale, false);
+});
+
+test("turn-epoch: AsyncLocalStorage propagates across awaits", async () => {
+  _resetTurnEpoch();
+  const captured = getCurrentTurnGeneration();
+  await runWithTurnGeneration(captured, async () => {
+    await Promise.resolve();
+    await new Promise((r) => setTimeout(r, 1));
+    bumpTurnGeneration("async-bump");
+    await Promise.resolve();
+    assert.equal(isStaleWrite("post-await"), true);
+  });
+});
+
+// ─── Source-level invariant checks for recoverTimedOutUnit ──────────────────
+//
+// The recoverTimedOutUnit function has two branch families:
+// - ADVANCE branches: the unit is done, loop moves on — these MUST bump.
+// - STEERING branches: the same LLM turn is kept alive with a steering
+//   message — these MUST NOT bump (otherwise the retry's legitimate writes
+//   get marked stale).
+//
+// The whole function must contain zero raw `resolveAgentEnd` calls with the
+// "timeout-recovery" _synthetic marker — all advance paths go through
+// bumpAndResolveSynthetic. And there must be no top-level bump call.
+
+test("recoverTimedOutUnit: no raw `resolveAgentEnd({ _synthetic: \"timeout-recovery\" })` calls remain", async () => {
+  const fs = await import("node:fs");
+  const path = await import("node:path");
+  const url = await import("node:url");
+  const here = path.dirname(url.fileURLToPath(import.meta.url));
+  const src = fs.readFileSync(
+    path.join(here, "..", "auto-timeout-recovery.ts"),
+    "utf-8",
+  );
+  const rawSyntheticResolve =
+    /resolveAgentEnd\s*\(\s*\{\s*messages:\s*\[\s*\]\s*,\s*_synthetic:\s*["']timeout-recovery/;
+  assert.equal(
+    rawSyntheticResolve.test(src),
+    false,
+    "auto-timeout-recovery.ts must funnel advance paths through bumpAndResolveSynthetic — a raw resolveAgentEnd with _synthetic:\"timeout-recovery\" would leak orphan writes",
+  );
+});
+
+test("recoverTimedOutUnit: no top-level bumpTurnGeneration — steering branches must not supersede", async () => {
+  const fs = await import("node:fs");
+  const path = await import("node:path");
+  const url = await import("node:url");
+  const here = path.dirname(url.fileURLToPath(import.meta.url));
+  const src = fs.readFileSync(
+    path.join(here, "..", "auto-timeout-recovery.ts"),
+    "utf-8",
+  );
+  // The only bump surface allowed is via bumpAndResolveSynthetic (advance
+  // paths) — a direct bumpTurnGeneration call in this file would bump even
+  // when the function later decides to take a steering retry branch.
+  assert.equal(
+    /\bbumpTurnGeneration\s*\(/.test(src),
+    false,
+    "auto-timeout-recovery.ts must not call bumpTurnGeneration directly — use bumpAndResolveSynthetic so bump and supersede are atomic and tied to advance-only branches",
+  );
+});
+
+test("recoverTimedOutUnit: bumpAndResolveSynthetic appears exactly four times (one per advance branch)", async () => {
+  const fs = await import("node:fs");
+  const path = await import("node:path");
+  const url = await import("node:url");
+  const here = path.dirname(url.fileURLToPath(import.meta.url));
+  const src = fs.readFileSync(
+    path.join(here, "..", "auto-timeout-recovery.ts"),
+    "utf-8",
+  );
+  const matches = src.match(/bumpAndResolveSynthetic\s*\(/g) ?? [];
+  assert.equal(
+    matches.length,
+    4,
+    `expected 4 advance-branch supersede sites (durableComplete, execute-task-exhausted, artifact-already-exists, non-execute-exhausted); found ${matches.length}`,
+  );
+});

package/src/resources/extensions/gsd/tests/validate-extension-package.test.ts

@@ -0,0 +1,168 @@
+// GSD-2 — Tests for validateExtensionPackage (EXTR-02, PKG-05)
+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 { validateExtensionPackage } from "../commands-extensions.ts";
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function makeTempDir(): string {
+  const dir = join(tmpdir(), `validate-ext-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function writePackageJson(dir: string, content: Record<string, unknown>): void {
+  writeFileSync(join(dir, "package.json"), JSON.stringify(content, null, 2));
+}
+
+function writeIndexTs(dir: string, content = "export default function() {}"): void {
+  writeFileSync(join(dir, "index.ts"), content);
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+test("validateExtensionPackage: valid package returns { valid: true }", (t) => {
+  // EXTR-02: gsd.extension: true, peerDependencies, pi.extensions
+  const dir = makeTempDir();
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+
+  writeIndexTs(dir);
+  writePackageJson(dir, {
+    name: "@gsd-extensions/test",
+    version: "1.0.0",
+    gsd: { extension: true },
+    pi: { extensions: ["./index.ts"] },
+    peerDependencies: { "@gsd/pi-coding-agent": "*" },
+    dependencies: { "some-lib": "^1.0.0" },
+  });
+
+  const result = validateExtensionPackage(dir);
+  assert.equal(result.valid, true);
+  assert.deepEqual(result.errors, []);
+});
+
+test("validateExtensionPackage: missing gsd.extension marker returns error", (t) => {
+  const dir = makeTempDir();
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+
+  writeIndexTs(dir);
+  writePackageJson(dir, {
+    name: "@gsd-extensions/test",
+    version: "1.0.0",
+    pi: { extensions: ["./index.ts"] },
+    peerDependencies: { "@gsd/pi-coding-agent": "*" },
+  });
+
+  const result = validateExtensionPackage(dir);
+  assert.equal(result.valid, false);
+  assert.ok(result.errors.some(e => e.includes("gsd")), `Expected error about gsd, got: ${JSON.stringify(result.errors)}`);
+});
+
+test("validateExtensionPackage: missing pi.extensions returns error", (t) => {
+  const dir = makeTempDir();
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+
+  writeIndexTs(dir);
+  writePackageJson(dir, {
+    name: "@gsd-extensions/test",
+    version: "1.0.0",
+    gsd: { extension: true },
+    peerDependencies: { "@gsd/pi-coding-agent": "*" },
+  });
+
+  const result = validateExtensionPackage(dir);
+  assert.equal(result.valid, false);
+  assert.ok(result.errors.some(e => e.includes("pi")), `Expected error about pi.extensions, got: ${JSON.stringify(result.errors)}`);
+});
+
+test("validateExtensionPackage: pi.extensions entry path not found returns error", (t) => {
+  const dir = makeTempDir();
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+
+  // Do NOT create index.ts
+  writePackageJson(dir, {
+    name: "@gsd-extensions/test",
+    version: "1.0.0",
+    gsd: { extension: true },
+    pi: { extensions: ["./index.ts"] },
+    peerDependencies: { "@gsd/pi-coding-agent": "*" },
+  });
+
+  const result = validateExtensionPackage(dir);
+  assert.equal(result.valid, false);
+  assert.ok(result.errors.some(e => e.includes("index.ts")), `Expected error about index.ts, got: ${JSON.stringify(result.errors)}`);
+});
+
+test("validateExtensionPackage: @gsd/* in dependencies (not peerDependencies) returns error", (t) => {
+  const dir = makeTempDir();
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+
+  writeIndexTs(dir);
+  writePackageJson(dir, {
+    name: "@gsd-extensions/test",
+    version: "1.0.0",
+    gsd: { extension: true },
+    pi: { extensions: ["./index.ts"] },
+    dependencies: { "@gsd/pi-coding-agent": "^2.0.0" },
+  });
+
+  const result = validateExtensionPackage(dir);
+  assert.equal(result.valid, false);
+  assert.ok(result.errors.some(e => e.includes("@gsd/pi-coding-agent")), `Expected error about @gsd/ dep, got: ${JSON.stringify(result.errors)}`);
+});
+
+test("validateExtensionPackage: @gsd/* in devDependencies returns error", (t) => {
+  const dir = makeTempDir();
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+
+  writeIndexTs(dir);
+  writePackageJson(dir, {
+    name: "@gsd-extensions/test",
+    version: "1.0.0",
+    gsd: { extension: true },
+    pi: { extensions: ["./index.ts"] },
+    peerDependencies: { "@gsd/pi-coding-agent": "*" },
+    devDependencies: { "@gsd/pi-tui": "^2.0.0" },
+  });
+
+  const result = validateExtensionPackage(dir);
+  assert.equal(result.valid, false);
+  assert.ok(
+    result.errors.some(e => e.includes("@gsd/pi-tui") && e.includes("devDependencies")),
+    `Expected error about @gsd/ in devDependencies, got: ${JSON.stringify(result.errors)}`,
+  );
+});
+
+test("validateExtensionPackage: missing package.json returns error", (t) => {
+  const dir = makeTempDir();
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+
+  // No package.json written
+  const result = validateExtensionPackage(dir);
+  assert.equal(result.valid, false);
+  assert.ok(result.errors.some(e => e.includes("package.json")), `Expected error about package.json, got: ${JSON.stringify(result.errors)}`);
+});
+
+test("validateExtensionPackage: invalid JSON in package.json returns error", (t) => {
+  const dir = makeTempDir();
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+
+  writeFileSync(join(dir, "package.json"), "{ invalid json :::}");
+
+  const result = validateExtensionPackage(dir);
+  assert.equal(result.valid, false);
+  assert.ok(result.errors.some(e => e.toLowerCase().includes("json")), `Expected JSON error, got: ${JSON.stringify(result.errors)}`);
+});
+
+test("validateExtensionPackage: extracted google-search package passes validation (PKG-05)", (_t) => {
+  // This test runs against the actual extensions/google-search/ directory.
+  // Use process.cwd() (project root) since relative path from import.meta.url
+  // breaks when tests run from dist-test/.
+  const googleSearchDir = join(process.cwd(), "extensions", "google-search");
+
+  const result = validateExtensionPackage(googleSearchDir);
+  assert.equal(result.valid, true, `extensions/google-search/ should be valid, errors: ${JSON.stringify(result.errors)}`);
+});

package/src/resources/extensions/gsd/tests/workflow-mcp.test.ts

@@ -180,6 +180,11 @@ test("detectWorkflowMcpLaunchConfig resolves the bundled server relative to the
 test("workflow MCP launch config reaches mutation tools over stdio", async () => {
   const projectRoot = mkdtempSync(join(tmpdir(), "gsd-workflow-transport-"));
   mkdirSync(join(projectRoot, ".gsd"), { recursive: true });
+  // Isolate the spawned MCP server from the developer's real ~/.gsd so it
+  // can't pick up a configured Discord/Slack/Telegram channel from global
+  // PREFERENCES.md and route ask_user_questions through a remote adapter
+  // instead of MCP elicitation.
+  const isolatedGsdHome = mkdtempSync(join(tmpdir(), "gsd-workflow-home-"));
 
   const launch = detectWorkflowMcpLaunchConfig(projectRoot, {});
   assert.ok(launch, "expected a workflow MCP launch config");
@@ -219,7 +224,14 @@ test("workflow MCP launch config reaches mutation tools over stdio", async () =>
   const transport = new StdioClientTransport({
     command: launch.command,
     args: launch.args,
-    env: { ...process.env, ...launch.env } as Record<string, string>,
+    env: {
+      ...process.env,
+      ...launch.env,
+      GSD_HOME: isolatedGsdHome,
+      DISCORD_BOT_TOKEN: "",
+      SLACK_BOT_TOKEN: "",
+      TELEGRAM_BOT_TOKEN: "",
+    } as Record<string, string>,
     cwd: launch.cwd,
     stderr: "pipe",
   });
@@ -345,12 +357,14 @@ test("workflow MCP launch config reaches mutation tools over stdio", async () =>
   } finally {
     await client.close().catch(() => {});
     rmSync(projectRoot, { recursive: true, force: true });
+    rmSync(isolatedGsdHome, { recursive: true, force: true });
   }
 });
 
 test("workflow MCP ask_user_questions uses stdio elicitation round-trip", async () => {
   const projectRoot = mkdtempSync(join(tmpdir(), "gsd-workflow-elicit-"));
   mkdirSync(join(projectRoot, ".gsd"), { recursive: true });
+  const isolatedGsdHome = mkdtempSync(join(tmpdir(), "gsd-workflow-home-"));
 
   const launch = detectWorkflowMcpLaunchConfig(projectRoot, {});
   assert.ok(launch, "expected a workflow MCP launch config");
@@ -381,7 +395,14 @@ test("workflow MCP ask_user_questions uses stdio elicitation round-trip", async
   const transport = new StdioClientTransport({
     command: launch.command,
     args: launch.args,
-    env: { ...process.env, ...launch.env } as Record<string, string>,
+    env: {
+      ...process.env,
+      ...launch.env,
+      GSD_HOME: isolatedGsdHome,
+      DISCORD_BOT_TOKEN: "",
+      SLACK_BOT_TOKEN: "",
+      TELEGRAM_BOT_TOKEN: "",
+    } as Record<string, string>,
     cwd: launch.cwd,
     stderr: "pipe",
   });
@@ -432,6 +453,8 @@ test("workflow MCP ask_user_questions uses stdio elicitation round-trip", async
     );
   } finally {
     await client.close();
+    rmSync(projectRoot, { recursive: true, force: true });
+    rmSync(isolatedGsdHome, { recursive: true, force: true });
   }
 });
 

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/workflow-logger.ts

@@ -16,9 +16,17 @@
 // the start of each unit to prevent log bleed between units running in the same
 // Node process.
 
-import { appendFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
+import {
+  appendFileSync,
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+} from "node:fs";
 import { join } from "node:path";
 
+import { withFileLockSync } from "./file-lock.js";
 import { appendNotification } from "./notification-store.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./uok/audit.js";
 import { isUnifiedAuditEnabled } from "./uok/audit-toggle.js";
@@ -59,7 +67,8 @@ export type LogComponent =
   | "memory-ingest"     // Memory layer ingestion pipeline
   | "memory-backfill"   // ADR-013: decisions->memories backfill
   | "context-mode"     // Context-mode exec sandbox and compaction snapshot
-  | "preflight";       // Clean-root preflight gate at milestone completion
+  | "preflight"        // Clean-root preflight gate at milestone completion
+  | "postUnit";     // Post-unit processing (abandon detection, overrides)
 
 export interface LogEntry {
   ts: string;
@@ -313,8 +322,18 @@ function _push(
     try {
       const auditDir = join(_auditBasePath, ".gsd");
       mkdirSync(auditDir, { recursive: true });
+      const auditPath = join(auditDir, "audit-log.jsonl");
       const sanitized = _sanitizeForAudit(entry);
-      appendFileSync(join(auditDir, "audit-log.jsonl"), JSON.stringify(sanitized) + "\n", "utf-8");
+      // Ensure file exists so proper-lockfile can acquire a lock against it.
+      if (!existsSync(auditPath)) closeSync(openSync(auditPath, "a"));
+      // onLocked: "skip" — never block error logging on lock contention.
+      withFileLockSync(
+        auditPath,
+        () => {
+          appendFileSync(auditPath, JSON.stringify(sanitized) + "\n", "utf-8");
+        },
+        { onLocked: "skip" },
+      );
     } catch (auditErr) {
       // Best-effort — never let audit write failures bubble up
       _writeStderr(`[gsd:audit] failed to persist log entry: ${(auditErr as Error).message}\n`);

package/src/resources/extensions/gsd/worktree-manager.ts

@@ -559,6 +559,7 @@ const SKIP_PATHS = [
   ".gsd/worktrees/",
   ".gsd/runtime/",
   ".gsd/activity/",
+  ".gsd/audit/",
   ".gsd/forensics/",
   ".gsd/parallel/",
   ".gsd/journal/",

package/src/resources/extensions/mcp-client/auth.ts

@@ -37,7 +37,18 @@ export type McpHttpAuthConfig = McpHttpAuthHeaders & McpHttpOAuthConfig;
 function resolveEnvValue(value: string): string {
 	return value.replace(
 		/\$\{([^}]+)\}/g,
-		(_match, varName) => process.env[varName] ?? "",
+		(_match, varName) => {
+			const resolved = process.env[varName];
+			if (resolved === undefined || resolved === "") {
+				// eslint-disable-next-line no-console
+				console.warn(
+					`[mcp-client auth] Environment variable "${varName}" referenced in MCP server config is unset. ` +
+					`Requests will go out with a malformed header and the remote server will likely reject them with 401.`,
+				);
+				return "";
+			}
+			return resolved;
+		},
 	);
 }