gsd-pi 2.76.0 → 2.77.0-dev.1d17f366c

package/src/resources/extensions/gsd/guided-flow.ts

@@ -13,7 +13,7 @@ import { loadFile, saveFile } from "./files.js";
 import { isDbAvailable, getMilestoneSlices } from "./gsd-db.js";
 import { parseRoadmapSlices } from "./roadmap-slices.js";
 import { loadPrompt, inlineTemplate } from "./prompt-loader.js";
-import { buildSkillActivationBlock } from "./auto-prompts.js";
+import { buildDiscussMilestonePrompt, buildSkillActivationBlock } from "./auto-prompts.js";
 import { deriveState } from "./state.js";
 import { invalidateAllCaches } from "./cache.js";
 import { startAutoDetached } from "./auto.js";
@@ -38,7 +38,7 @@ import { isInheritedRepo } from "./repo-identity.js";
 import { ensureGitignore, ensurePreferences, untrackRuntimeFiles } from "./gitignore.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { resolveUokFlags } from "./uok/flags.js";
-import { ensurePlanV2Graph } from "./uok/plan-v2.js";
+import { ensurePlanV2Graph, isMissingFinalizedContextResult } from "./uok/plan-v2.js";
 import { detectProjectState } from "./detection.js";
 import { showProjectInit, offerMigration } from "./init-wizard.js";
 import { validateDirectory } from "./validate-directory.js";
@@ -93,24 +93,29 @@ function needsPlanV2Gate(state: GSDState): boolean {
     || state.phase === "completing-milestone";
 }
 
+type PlanV2GateDecision = "pass" | "recover-missing-context" | "block";
+
 function runPlanV2Gate(
   ctx: ExtensionContext,
   basePath: string,
   state: GSDState,
-): boolean {
+): PlanV2GateDecision {
   const prefs = loadEffectiveGSDPreferences()?.preferences;
   const uokFlags = resolveUokFlags(prefs);
-  if (!uokFlags.planV2 || !needsPlanV2Gate(state)) return true;
+  if (!uokFlags.planV2 || !needsPlanV2Gate(state)) return "pass";
   const compiled = ensurePlanV2Graph(basePath, state);
   if (!compiled.ok) {
+    if (isMissingFinalizedContextResult(compiled)) {
+      return "recover-missing-context";
+    }
     const reason = compiled.reason ?? "plan-v2 compilation failed";
     ctx.ui.notify(
-      `Plan gate failed-closed: ${reason}. Complete plan/discuss artifacts before execution.`,
+      `Plan gate failed-closed: ${reason}. Complete plan/discuss artifacts before execution.\n\nIf this keeps happening, try: /gsd doctor heal`,
       "error",
     );
-    return false;
+    return "block";
   }
-  return true;
+  return "pass";
 }
 
 // ─── Commit Instruction Helpers ──────────────────────────────────────────────
@@ -130,8 +135,20 @@ interface PendingAutoStartEntry {
   milestoneId: string; // the milestone being discussed
   step?: boolean; // preserve step mode through discuss → auto transition
   createdAt: number; // timestamp for staleness detection (#3274)
+  // #4573: counter for how many times the LLM emitted the ready phrase
+  // without writing the required artifacts. Cleared on entry delete/recreate.
+  readyRejectCount?: number;
 }
 
+// #4573: cap for how many times we nudge the LLM after a premature ready
+// phrase before giving up and asking the user to re-run /gsd.
+const MAX_READY_REJECTS = 2;
+
+// #4573: matches the canonical ready phrase the discuss prompt asks the LLM
+// to emit. Accepts any M-prefixed milestone ID (three digits + optional
+// suffix) with optional trailing punctuation.
+const READY_PHRASE_RE = /\bMilestone\s+M\d{3}[A-Z0-9-]*\s+ready\.?/i;
+
 const pendingAutoStartMap = new Map<string, PendingAutoStartEntry>();
 
 /**
@@ -279,6 +296,215 @@ export function checkAutoStartAfterDiscuss(): boolean {
   return true;
 }
 
+/**
+ * Extract the concatenated text content from an assistant message, whether it
+ * stores content as a string or as an array of text blocks.
+ */
+function extractAssistantText(msg: any): string {
+  if (!msg) return "";
+  const content = msg.content;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  const parts: string[] = [];
+  for (const block of content) {
+    if (!block || typeof block !== "object") continue;
+    if (block.type === "text" && typeof block.text === "string") parts.push(block.text);
+  }
+  return parts.join("\n");
+}
+
+/**
+ * Return true if the assistant message contains any tool-use block.
+ */
+function hasToolUse(msg: any): boolean {
+  if (!msg) return false;
+  const content = msg.content;
+  if (!Array.isArray(content)) return false;
+  return content.some((b: any) => b && typeof b === "object" && (b.type === "tool_use" || b.type === "tool-use"));
+}
+
+/**
+ * #4573 — Detect and recover from the "ready phrase without files" failure mode.
+ *
+ * When the LLM emits "Milestone {{id}} ready." but has not written CONTEXT.md
+ * or ROADMAP.md, `checkAutoStartAfterDiscuss()` silently returns false and the
+ * next /gsd invocation loops into the "All milestones complete" warning.
+ *
+ * This function, called from `handleAgentEnd` after `checkAutoStartAfterDiscuss`
+ * returns false, pattern-matches the ready phrase on the last assistant message.
+ * If it fired AND neither CONTEXT.md nor ROADMAP.md exists, it:
+ *   1. Notifies the user that the signal was rejected.
+ *   2. Injects a system message via `pi.sendMessage(..., {triggerTurn:true})`
+ *      telling the LLM the signal was premature and to emit the writes now.
+ *   3. Caps at `MAX_READY_REJECTS` per-entry; beyond that, gives up and asks
+ *      the user to re-run /gsd.
+ *
+ * Returns true when a nudge (or give-up) was emitted, signaling the caller to
+ * skip `resolveAgentEnd`.
+ */
+export function maybeHandleReadyPhraseWithoutFiles(event: { messages: any[] }): boolean {
+  const entry = _getPendingAutoStart();
+  if (!entry) return false;
+  const { ctx, pi, basePath, milestoneId } = entry;
+
+  // Gate: last assistant message must contain the ready phrase
+  const lastMsg = event.messages[event.messages.length - 1];
+  const text = extractAssistantText(lastMsg);
+  if (!READY_PHRASE_RE.test(text)) return false;
+
+  // Gate: artifacts must still be missing — if they exist, the happy path
+  // already fired and we have nothing to do.
+  const contextFile = resolveMilestoneFile(basePath, milestoneId, "CONTEXT");
+  const roadmapFile = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+  if (contextFile || roadmapFile) return false;
+
+  entry.readyRejectCount = (entry.readyRejectCount ?? 0) + 1;
+
+  if (entry.readyRejectCount > MAX_READY_REJECTS) {
+    // Give up: clear state and tell the user to re-run /gsd. Avoids an
+    // infinite nudge loop when the LLM never produces the writes.
+    pendingAutoStartMap.delete(basePath);
+    ctx.ui.notify(
+      `Milestone ${milestoneId}: LLM signaled "ready" ${entry.readyRejectCount} times without writing files. ` +
+      `Stopping auto-nudge. Run /gsd to try again.`,
+      "error",
+    );
+    return true;
+  }
+
+  ctx.ui.notify(
+    `Milestone ${milestoneId}: "ready" signal rejected — CONTEXT.md and ROADMAP.md are missing. Asking the LLM to complete the writes.`,
+    "warning",
+  );
+
+  const nudge =
+    `You emitted "Milestone ${milestoneId} ready." but neither ` +
+    `.gsd/milestones/${milestoneId}/${milestoneId}-CONTEXT.md nor ` +
+    `.gsd/milestones/${milestoneId}/${milestoneId}-ROADMAP.md exists on disk. ` +
+    `The ready phrase is a POST-WRITE signal and has been rejected. ` +
+    `In this turn: (1) write PROJECT.md, REQUIREMENTS.md, and the milestone ` +
+    `CONTEXT.md, (2) call gsd_plan_milestone, then (3) emit the ready phrase. ` +
+    `Do not describe these steps — execute them as tool calls. ` +
+    `This is retry ${entry.readyRejectCount}/${MAX_READY_REJECTS}; further ` +
+    `premature signals will clear the session.`;
+
+  try {
+    pi.sendMessage(
+      { customType: "gsd-ready-no-files", content: nudge, display: false },
+      { triggerTurn: true },
+    );
+  } catch (e) {
+    logWarning("guided", `ready-phrase nudge sendMessage failed: ${(e as Error).message}`);
+    return false;
+  }
+  return true;
+}
+
+/**
+ * #4573 — Detect and recover from the "announces tool, never calls it" stall.
+ *
+ * The LLM emits text like "I'll now write the CONTEXT.md file" but the turn
+ * ends with zero tool-use blocks. The harness has no post-turn tool-call
+ * validation, so the unit promise resolves and the user sees a stalled state.
+ *
+ * This function, called from `handleAgentEnd`, inspects the last assistant
+ * message. If ALL of the following are true, it injects a recovery message:
+ *   - Text-only (no tool-use blocks)
+ *   - Contains a commit-intent phrase ("I'll write", "I'll call", etc.)
+ *   - Auto-mode is active OR a discussion autostart is pending
+ *   - `emptyTurnRetryCount` is under the cap
+ *
+ * Per-handler state is held on the `PendingAutoStartEntry` when present, and
+ * on a module-level map otherwise. The counter resets on any successful
+ * tool-use turn via `resetEmptyTurnCounter`.
+ */
+const emptyTurnCounterByBase = new Map<string, number>();
+const MAX_EMPTY_TURN_RETRIES = 2;
+
+// Phrases that indicate the LLM is about to do something but has not yet.
+// Kept tight to avoid flagging legitimate narration like "I'll wait for your answer."
+const COMMIT_INTENT_RE =
+  /\b(?:I['’]ll|I will|Next,? I['’]ll|Now I['’]ll|Let me|I['’]m going to|I am going to)\s+(?:now\s+)?(?:write|create|call|invoke|update|add|make|run|execute|generate|produce|emit|compose|implement|save|apply|commit)\b/i;
+
+/**
+ * Reset the empty-turn counter for a basePath after a successful tool-use turn.
+ * Called from handleAgentEnd when the last message contains tool_use blocks.
+ */
+export function resetEmptyTurnCounter(basePath?: string): void {
+  if (basePath) emptyTurnCounterByBase.delete(basePath);
+  else emptyTurnCounterByBase.clear();
+}
+
+export function maybeHandleEmptyIntentTurn(
+  event: { messages: any[] },
+  isAuto: boolean,
+): boolean {
+  // Gate: only fire when there is system-driven work in flight. Interactive
+  // /gsd discuss (user-driven) produces legitimate text-only turns.
+  if (!isAuto && pendingAutoStartMap.size === 0) return false;
+
+  const lastMsg = event.messages[event.messages.length - 1];
+  if (!lastMsg) return false;
+  if (hasToolUse(lastMsg)) return false;
+
+  const text = extractAssistantText(lastMsg).trim();
+  if (!text) return false;
+
+  // Skip if the LLM is emitting the ready phrase — that is the ready-no-files
+  // path, handled by maybeHandleReadyPhraseWithoutFiles.
+  if (READY_PHRASE_RE.test(text)) return false;
+
+  // Skip if the LLM is clearly handing back to the user. Keep the heuristic
+  // tight: a trailing question mark on the last non-empty line is the common
+  // signal for "I asked the user a question and stopped."
+  const lines = text.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+  const lastLine = lines[lines.length - 1] ?? "";
+  if (lastLine.endsWith("?")) return false;
+
+  // Must contain a commit-intent phrase — this is the stall we care about.
+  if (!COMMIT_INTENT_RE.test(text)) return false;
+
+  // Resolve the target basePath + pi for injection. Prefer the pending
+  // autostart entry (discuss flow); otherwise we cannot inject.
+  const entry = _getPendingAutoStart();
+  if (!entry) return false;
+  const { ctx, pi, basePath } = entry;
+
+  const count = (emptyTurnCounterByBase.get(basePath) ?? 0) + 1;
+  emptyTurnCounterByBase.set(basePath, count);
+
+  if (count > MAX_EMPTY_TURN_RETRIES) {
+    ctx.ui.notify(
+      `Empty-turn recovery: LLM announced intent ${count} times without calling any tool. ` +
+      `Stopping auto-nudge.`,
+      "error",
+    );
+    return false; // let the normal flow resolve/pause the unit
+  }
+
+  ctx.ui.notify(
+    `Empty-turn detected: LLM announced intent but called no tool. Prompting it to execute.`,
+    "info",
+  );
+
+  const nudge =
+    `Your last turn announced an action (e.g. "I'll write…" or "Let me call…") ` +
+    `but contained no tool call. The system records zero tool-use blocks for ` +
+    `that turn. Execute the announced action NOW as a tool call in this turn. ` +
+    `Do not describe it again. Retry ${count}/${MAX_EMPTY_TURN_RETRIES}.`;
+
+  try {
+    pi.sendMessage(
+      { customType: "gsd-empty-turn-recovery", content: nudge, display: false },
+      { triggerTurn: true },
+    );
+  } catch (e) {
+    logWarning("guided", `empty-turn nudge sendMessage failed: ${(e as Error).message}`);
+    return false;
+  }
+  return true;
+}
+
 /**
  * Extract milestone IDs from PROJECT.md milestone sequence table.
  * Looks for rows like "| M001 | Name | Status |" and extracts the ID column.
@@ -604,8 +830,13 @@ export async function showHeadlessMilestoneCreation(
   // Set pending auto start (auto-mode triggers on "Milestone X ready." via checkAutoStartAfterDiscuss)
   pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, createdAt: Date.now() });
 
-  // Dispatch — headless milestone creation is a planning activity
-  await dispatchWorkflow(pi, prompt, "gsd-run", ctx, "plan-milestone");
+  // Dispatch as discuss-milestone. The LLM writes PROJECT.md, REQUIREMENTS.md,
+  // and CONTEXT.md, then calls gsd_plan_milestone — this is semantically the
+  // discuss path, just non-interactive. Using "plan-milestone" here caused
+  // model/tool routing to skip discuss-flow tool scoping and
+  // `checkAutoStartAfterDiscuss` guardrails that rely on the
+  // "discuss-"-prefixed unitType.
+  await dispatchWorkflow(pi, prompt, "gsd-run", ctx, "discuss-milestone");
 }
 
 
@@ -1352,7 +1583,8 @@ export async function showSmartEntry(
     logWarning("guided", `STATE.md rebuild failed: ${(err as Error).message}`);
   }
 
-  if (!runPlanV2Gate(ctx, basePath, state)) return;
+  const planV2GateDecision = runPlanV2Gate(ctx, basePath, state);
+  if (planV2GateDecision === "block") return;
 
   if (!state.activeMilestone?.id) {
     // Guard: if a discuss session is already in flight, don't re-inject the prompt.
@@ -1440,6 +1672,23 @@ export async function showSmartEntry(
   const milestoneId = state.activeMilestone.id;
   const milestoneTitle = state.activeMilestone.title;
 
+  if (planV2GateDecision === "recover-missing-context") {
+    pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId, step: stepMode, createdAt: Date.now() });
+    await dispatchWorkflow(
+      pi,
+      await buildDiscussMilestonePrompt(
+        milestoneId,
+        milestoneTitle,
+        basePath,
+        getStructuredQuestionsAvailability(pi, ctx),
+      ),
+      "gsd-discuss",
+      ctx,
+      "discuss-milestone",
+    );
+    return;
+  }
+
   // ── All milestones complete → New milestone ──────────────────────────
   if (state.phase === "complete") {
     const choice = await showNextAction(ctx, {

package/src/resources/extensions/gsd/health-widget.ts

@@ -108,6 +108,7 @@ export function initHealthWidget(ctx: ExtensionContext): void {
     let data = initialData;
     let cachedLines: string[] | undefined;
     let refreshInFlight = false;
+    let isDisposed = false;
 
     const refresh = async () => {
       if (refreshInFlight) return;
@@ -115,7 +116,7 @@ export function initHealthWidget(ctx: ExtensionContext): void {
       try {
         data = loadHealthWidgetData(basePath);
         cachedLines = undefined;
-        _tui.requestRender();
+        if (!isDisposed) _tui.requestRender();
       } catch { /* non-fatal */ } finally {
         refreshInFlight = false;
       }
@@ -140,6 +141,7 @@ export function initHealthWidget(ctx: ExtensionContext): void {
       },
       invalidate(): void { cachedLines = undefined; cachedWidth = undefined; },
       dispose(): void {
+        isDisposed = true;
         clearInterval(refreshTimer);
       },
     };

package/src/resources/extensions/gsd/hook-emitter.ts

@@ -0,0 +1,188 @@
+// GSD Extension — Layer 2 Event Emitter Bridge
+//
+// Holds a module-scoped reference to the ExtensionAPI so deeply-nested code
+// (auto-loop, git-service callers, verification, budget) can emit Layer 2
+// events without having to thread `pi` through every function signature.
+//
+// Set once from `registerGsdExtension`. All emitters are best-effort — a
+// missing `pi` (e.g. in standalone unit tests) silently becomes a no-op.
+
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+import type {
+  BeforeCommitEventResult,
+  BeforePrEventResult,
+  BeforePushEventResult,
+  BeforeVerifyEventResult,
+  BudgetThresholdEventResult,
+  VerifyFailure,
+} from "@gsd/pi-coding-agent";
+
+let _pi: ExtensionAPI | undefined;
+
+export function setHookEmitter(pi: ExtensionAPI): void {
+  _pi = pi;
+}
+
+export function clearHookEmitter(): void {
+  _pi = undefined;
+}
+
+// ─── Notification ──────────────────────────────────────────────────────────
+
+export async function emitNotification(
+  kind: "blocked" | "input_needed" | "milestone_ready" | "idle" | "error",
+  message: string,
+  details?: Record<string, unknown>,
+): Promise<void> {
+  if (!_pi) return;
+  await _pi.emitExtensionEvent({ type: "notification", kind, message, details });
+}
+
+// ─── Git Lifecycle ─────────────────────────────────────────────────────────
+
+export async function emitBeforeCommit(args: {
+  message: string;
+  files: string[];
+  cwd: string;
+  author?: string;
+}): Promise<BeforeCommitEventResult | undefined> {
+  if (!_pi) return undefined;
+  return (await _pi.emitExtensionEvent({
+    type: "before_commit",
+    ...args,
+  })) as BeforeCommitEventResult | undefined;
+}
+
+export async function emitCommit(args: {
+  sha: string;
+  message: string;
+  files: string[];
+  cwd: string;
+}): Promise<void> {
+  if (!_pi) return;
+  await _pi.emitExtensionEvent({ type: "commit", ...args });
+}
+
+export async function emitBeforePush(args: {
+  remote: string;
+  branch: string;
+  cwd: string;
+}): Promise<BeforePushEventResult | undefined> {
+  if (!_pi) return undefined;
+  return (await _pi.emitExtensionEvent({
+    type: "before_push",
+    ...args,
+  })) as BeforePushEventResult | undefined;
+}
+
+export async function emitPush(args: { remote: string; branch: string; cwd: string }): Promise<void> {
+  if (!_pi) return;
+  await _pi.emitExtensionEvent({ type: "push", ...args });
+}
+
+export async function emitBeforePr(args: {
+  branch: string;
+  targetBranch: string;
+  title: string;
+  body: string;
+  cwd: string;
+}): Promise<BeforePrEventResult | undefined> {
+  if (!_pi) return undefined;
+  return (await _pi.emitExtensionEvent({
+    type: "before_pr",
+    ...args,
+  })) as BeforePrEventResult | undefined;
+}
+
+export async function emitPrOpened(args: {
+  url: string;
+  branch: string;
+  targetBranch: string;
+  cwd: string;
+}): Promise<void> {
+  if (!_pi) return;
+  await _pi.emitExtensionEvent({ type: "pr_opened", ...args });
+}
+
+// ─── Verification ──────────────────────────────────────────────────────────
+
+export async function emitBeforeVerify(args: {
+  unitType?: string;
+  unitId?: string;
+  cwd: string;
+}): Promise<BeforeVerifyEventResult | undefined> {
+  if (!_pi) return undefined;
+  return (await _pi.emitExtensionEvent({
+    type: "before_verify",
+    ...args,
+  })) as BeforeVerifyEventResult | undefined;
+}
+
+export async function emitVerifyResult(args: {
+  passed: boolean;
+  failures: VerifyFailure[];
+  unitType?: string;
+  unitId?: string;
+  cwd: string;
+}): Promise<void> {
+  if (!_pi) return;
+  await _pi.emitExtensionEvent({ type: "verify_result", ...args });
+}
+
+// ─── Budget ────────────────────────────────────────────────────────────────
+
+export async function emitBudgetThreshold(args: {
+  fraction: number;
+  spent: number;
+  limit: number;
+}): Promise<BudgetThresholdEventResult | undefined> {
+  if (!_pi) return undefined;
+  return (await _pi.emitExtensionEvent({
+    type: "budget_threshold",
+    fraction: args.fraction,
+    spent: args.spent,
+    limit: args.limit,
+    currency: "USD",
+  })) as BudgetThresholdEventResult | undefined;
+}
+
+// ─── Orchestrator Boundaries ───────────────────────────────────────────────
+
+export async function emitMilestoneStart(args: {
+  milestoneId: string;
+  title?: string;
+  cwd: string;
+}): Promise<void> {
+  if (!_pi) return;
+  await _pi.emitExtensionEvent({ type: "milestone_start", ...args });
+}
+
+export async function emitMilestoneEnd(args: {
+  milestoneId: string;
+  status: "completed" | "failed" | "cancelled";
+  cwd: string;
+}): Promise<void> {
+  if (!_pi) return;
+  await _pi.emitExtensionEvent({ type: "milestone_end", ...args });
+}
+
+export async function emitUnitStart(args: {
+  unitType: string;
+  unitId: string;
+  milestoneId?: string;
+  cwd: string;
+}): Promise<void> {
+  if (!_pi) return;
+  await _pi.emitExtensionEvent({ type: "unit_start", ...args });
+}
+
+export async function emitUnitEnd(args: {
+  unitType: string;
+  unitId: string;
+  milestoneId?: string;
+  status: "completed" | "failed" | "cancelled" | "blocked";
+  cwd: string;
+}): Promise<void> {
+  if (!_pi) return;
+  await _pi.emitExtensionEvent({ type: "unit_end", ...args });
+}

package/src/resources/extensions/gsd/init-wizard.ts

@@ -10,7 +10,7 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent
 import { existsSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { showNextAction } from "../shared/tui.js";
-import { nativeIsRepo, nativeInit } from "./native-git-bridge.js";
+import { nativeIsRepo, nativeInit, nativeAddAll, nativeCommit } from "./native-git-bridge.js";
 import { ensureGitignore, untrackRuntimeFiles } from "./gitignore.js";
 import { gsdRoot } from "./paths.js";
 import { assertSafeDirectory } from "./validate-directory.js";
@@ -74,6 +74,7 @@ export async function showProjectInit(
   }
 
   // ── Step 2: Git setup ──────────────────────────────────────────────────────
+  let didInitGit = false;
   if (!signals.isGitRepo) {
     const gitChoice = await showNextAction(ctx, {
       title: "GSD — Project Setup",
@@ -89,6 +90,7 @@ export async function showProjectInit(
 
     if (gitChoice === "init_git") {
       nativeInit(basePath, prefs.mainBranch);
+      didInitGit = true;
     }
   } else {
     // Auto-detect main branch from existing repo
@@ -295,6 +297,18 @@ export async function showProjectInit(
   ensureGitignore(basePath);
   untrackRuntimeFiles(basePath);
 
+  // Create initial commit so git log and git worktree work immediately (#4530).
+  // Without this, the branch is "unborn" (zero commits) and downstream operations
+  // like `git log` and `git worktree add` fail.
+  if (didInitGit) {
+    try {
+      nativeAddAll(basePath);
+      nativeCommit(basePath, "chore: init project");
+    } catch {
+      // Non-fatal — user can commit manually; don't block project init
+    }
+  }
+
   // Auto-generate codebase map for instant agent orientation
   try {
     const result = generateCodebaseMap(basePath);

package/src/resources/extensions/gsd/journal.ts

@@ -12,8 +12,18 @@
  * - Silent failure: journal writes never throw — absence of events is the failure signal
  */
 
-import { appendFileSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import {
+  appendFileSync,
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+} from "node:fs";
 import { join } from "node:path";
+import { isStaleWrite } from "./auto/turn-epoch.js";
+import { withFileLockSync } from "./file-lock.js";
 import { gsdRoot } from "./paths.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./uok/audit.js";
 import { isUnifiedAuditEnabled } from "./uok/audit-toggle.js";
@@ -39,7 +49,8 @@ export type JournalEventType =
   | "worktree-create-failed"
   | "worktree-skip"
   | "worktree-merge-start"
-  | "worktree-merge-failed";
+  | "worktree-merge-failed"
+  | "artifact-verification-retry";
 
 /** A single structured event in the journal. */
 export interface JournalEntry {
@@ -83,12 +94,27 @@ export interface JournalQueryFilters {
  * Never throws — all errors are silently caught.
  */
 export function emitJournalEvent(basePath: string, entry: JournalEntry): void {
+  // Drop writes from a turn superseded by timeout recovery / cancellation.
+  // See auto/turn-epoch.ts for the full rationale.
+  if (isStaleWrite("journal")) return;
   try {
     const journalDir = join(gsdRoot(basePath), "journal");
     mkdirSync(journalDir, { recursive: true });
     const dateStr = entry.ts.slice(0, 10);
     const filePath = join(journalDir, `${dateStr}.jsonl`);
-    appendFileSync(filePath, JSON.stringify(entry) + "\n");
+    // Ensure file exists so proper-lockfile can acquire a lock against it.
+    if (!existsSync(filePath)) closeSync(openSync(filePath, "a"));
+    // onLocked: "skip" — journal writes are best-effort. POSIX O_APPEND
+    // atomicity still protects small entries; the lock mainly serializes
+    // larger writes and gives cross-process exclusivity on platforms where
+    // O_APPEND semantics are weaker (Windows).
+    withFileLockSync(
+      filePath,
+      () => {
+        appendFileSync(filePath, JSON.stringify(entry) + "\n");
+      },
+      { onLocked: "skip" },
+    );
   } catch {
     // Silent failure — journal must never break auto-mode
   }