@opengsd/gsd-pi 1.3.0-dev.65546769 → 1.3.0-dev.738160b9

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

@@ -1,15 +1,18 @@
 import { clearParseCache } from "../files.js";
 import { isClosedStatus } from "../status-guards.js";
 import { isNonEmptyString, validateStringArray } from "../validation.js";
-import { transaction, getSlice, getTask, insertTask, upsertTaskPlanning } from "../gsd-db.js";
+import { getGateIdsForTurn } from "../gate-registry.js";
+import { transaction, getSlice, getTask, insertTask, upsertTaskPlanning, insertGateRow, setSliceSketchFlag } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
 import { renderTaskPlanFromDb, renderPlanFromDb } from "../markdown-renderer.js";
-import { resolveSliceFile, resolveTasksDir } from "../paths.js";
+import { resolveTasksDir } from "../paths.js";
 import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
+import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { validatePathOnlyPlanningFields, validatePlanningPathScope } from "../planning-path-scope.js";
+import type { GateId } from "../types.js";
 
 export interface PlanTaskParams {
   milestoneId: string;
@@ -57,6 +60,12 @@ function validateParams(params: PlanTaskParams): PlanTaskParams {
   };
 }
 
+function resolveTaskGates(basePath: string): GateId[] {
+  const loaded = loadEffectiveGSDPreferences(basePath);
+  if (loaded?.preferences?.gate_evaluation?.task_gates === false) return [];
+  return [...getGateIdsForTurn("execute-task")];
+}
+
 export async function handlePlanTask(
   rawParams: PlanTaskParams,
   basePath: string,
@@ -84,6 +93,14 @@ export async function handlePlanTask(
     return { error: `validation failed: ${pathScopeError}` };
   }
 
+  let taskGates: GateId[];
+  try {
+    taskGates = resolveTaskGates(basePath);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { error: `validation failed: ${message}` };
+  }
+
   // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
   // Guards must be inside the transaction so the state they check cannot
   // change between the read and the write (#2723).
@@ -127,6 +144,9 @@ export async function handlePlanTask(
         observabilityImpact: params.observabilityImpact ?? "",
         fullPlanMd: params.fullPlanMd,
       });
+      for (const gid of taskGates) {
+        insertGateRow({ milestoneId: params.milestoneId, sliceId: params.sliceId, gateId: gid, scope: "task", taskId: params.taskId });
+      }
     });
   } catch (err) {
     return { error: `db write failed: ${(err as Error).message}` };
@@ -142,17 +162,22 @@ export async function handlePlanTask(
     // Flat-phase: tasks live as checkboxes in the slice plan's <tasks> block,
     // not as standalone TID-PLAN.md files. Re-render the slice plan so the
     // new/updated task appears in the plan file that gsd-core reads.
-    // Guard: resolveTasksDir is null in flat-phase (no tasks/ subdir exists);
-    //        only sync if a slice plan already exists (guards pre-plan-slice calls).
+    // Guard: resolveTasksDir is null in flat-phase (no tasks/ subdir exists).
+    let slicePlanSynced = false;
     try {
       const tDir = resolveTasksDir(basePath, params.milestoneId, params.sliceId);
-      if (!tDir && resolveSliceFile(basePath, params.milestoneId, params.sliceId, "PLAN")) {
+      if (!tDir) {
         await renderPlanFromDb(basePath, params.milestoneId, params.sliceId);
+        slicePlanSynced = true;
       }
     } catch (syncErr) {
       logWarning("tool", `plan-task: slice-plan sync failed: ${(syncErr as Error).message}`);
     }
 
+    if (slicePlanSynced) {
+      setSliceSketchFlag(params.milestoneId, params.sliceId, false);
+    }
+
     invalidateStateCache();
     clearParseCache();
 

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

@@ -15,6 +15,7 @@ import { gsdRoot, resolveTasksDir, resolveSlicePath, resolveSliceFile, resolveTa
 import { sendDesktopNotification } from "./notifications.js";
 import { getTask, getSlice, getSliceTasks, updateTaskStatus, resetSliceCascade } from "./gsd-db.js";
 import { renderPlanCheckboxes, renderRoadmapCheckboxes } from "./markdown-renderer.js";
+import { UNIT_REGISTRY } from "./unit-registry.js";
 
 /**
  * Undo the last completed unit: revert git commits,
@@ -42,16 +43,20 @@ export async function handleUndo(args: string, ctx: ExtensionCommandContext, _pi
     return;
   }
 
-  // Extract unit type and ID from the most recent activity log filename
-  // Format: <seq>-<unitType>-<unitId>.jsonl
-  const match = files[0].match(/^\d+-(.+?)-(.+)\.jsonl$/);
-  if (!match) {
+  // Extract unit type and ID from the most recent activity log filename.
+  // Both the unit type and the unit ID may contain hyphens, so anchor on the
+  // known unit-type vocabulary instead of guessing the unit-ID shape: a regex
+  // tuned to milestone-shaped IDs rejects project-level units whose IDs are
+  // symbolic (e.g. discuss-project uses PROJECT, workflow-preferences uses
+  // WORKFLOW-PREFS).
+  const parsed = parseActivityLogFilename(files[0]);
+  if (!parsed) {
     ctx.ui.notify("Nothing to undo — could not parse latest activity log.", "warning");
     return;
   }
 
-  const unitType = match[1];
-  const unitId = match[2].replace(/-/g, "/");
+  const unitType = parsed.unitType;
+  const unitId = parsed.unitId.replace(/-/g, "/");
 
   if (!force) {
     ctx.ui.notify(
@@ -100,6 +105,11 @@ export async function handleUndo(args: string, ctx: ExtensionCommandContext, _pi
   if (unitType === "execute-task" && task !== undefined && slice !== undefined) {
     const [mid, sid, tid] = [milestone, slice, task];
     planUpdated = uncheckTaskInPlan(basePath, mid, sid, tid);
+    if (getTask(mid, sid, tid)) {
+      updateTaskStatus(mid, sid, tid, "pending");
+      await renderPlanCheckboxes(basePath, mid, sid);
+      planUpdated = true;
+    }
   }
 
   // 3. Try to revert git commits from activity log
@@ -379,6 +389,37 @@ export async function handleResetSlice(
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
+// Known unit types sorted longest-first so a more specific type (e.g.
+// "execute-task-simple") matches before a prefix of it ("execute-task") when
+// splitting "<seq>-<unitType>-<unitId>.jsonl".
+const UNIT_TYPES_BY_LENGTH_DESC: readonly string[] = Object.keys(UNIT_REGISTRY).sort(
+  (a, b) => b.length - a.length,
+);
+
+/**
+ * Parse an activity-log filename of the form `<seq>-<unitType>-<unitId>.jsonl`
+ * (the format written by activity-log.ts). Both the unit type and the unit ID
+ * may contain hyphens, so we anchor on the known unit-type vocabulary rather
+ * than guessing the ID shape. This keeps non-milestone IDs (e.g. PROJECT,
+ * WORKFLOW-PREFS) parseable. Returns null when the name has no sequence prefix
+ * or does not start with a recognised unit type.
+ */
+export function parseActivityLogFilename(
+  filename: string,
+): { unitType: string; unitId: string } | null {
+  const seqMatch = filename.match(/^\d+-(.+)\.jsonl$/);
+  if (!seqMatch) return null;
+  const rest = seqMatch[1];
+  for (const unitType of UNIT_TYPES_BY_LENGTH_DESC) {
+    const prefix = `${unitType}-`;
+    if (rest.startsWith(prefix)) {
+      const unitId = rest.slice(prefix.length);
+      if (unitId.length > 0) return { unitType, unitId };
+    }
+  }
+  return null;
+}
+
 export function uncheckTaskInPlan(basePath: string, mid: string, sid: string, tid: string): boolean {
   const slicePath = resolveSlicePath(basePath, mid, sid);
   if (!slicePath) return false;

package/src/resources/extensions/gsd/unit-context-composer.ts

@@ -135,14 +135,38 @@ const CONTEXT_MODE_GUIDANCE_BY_LANE: Record<Exclude<ContextModePolicy, "none">,
     "Use `gsd_resume` for prior context, `gsd_exec_search` for saved evidence, and `gsd_exec` for noisy doc validation commands.",
 };
 
-// Per-unit overrides win over the lane default. run-uat's tool contract
-// forbids `gsd_exec`/`gsd_exec_search` (acceptance evidence must flow through
-// `gsd_uat_exec`) and Claude Code dispatch strips the tools entirely, so the
-// shared verification-lane guidance would steer the agent into calling an
-// unavailable tool.
-const CONTEXT_MODE_GUIDANCE_BY_UNIT: Record<string, string> = {
+// Per-unit overrides win over the lane default. Some units intentionally run
+// with narrower tool contracts than their shared Context Mode lane, so their
+// guidance must name only tools the unit can actually call.
+export const CONTEXT_MODE_GUIDANCE_BY_UNIT: Readonly<Record<string, string>> = {
+  "discuss-milestone":
+    "Use `ask_user_questions` to continue the milestone interview, then persist outcomes with `gsd_summary_save`, `gsd_decision_save`, `gsd_requirement_save`, `gsd_requirement_update`, `gsd_plan_milestone`, or `gsd_milestone_generate_id` as appropriate.",
+  "discuss-slice":
+    "Use `ask_user_questions` to continue the slice interview, then persist outcomes with `gsd_summary_save` or `gsd_decision_save` as appropriate.",
+  "discuss-project":
+    "Use `ask_user_questions` to continue the project interview, then persist outcomes with `gsd_summary_save`, `gsd_decision_save`, or `gsd_requirement_save` as appropriate.",
+  "discuss-requirements":
+    "Use `ask_user_questions` to continue the requirements interview, then persist outcomes with `gsd_requirement_save` or `gsd_summary_save` as appropriate.",
+  "replan-slice":
+    "Use `gsd_replan_slice` to persist the revised slice plan, and `gsd_decision_save` for planning decisions that need durable rationale.",
+  "reassess-roadmap":
+    "Use `gsd_milestone_status` to inspect current milestone state, then `gsd_reassess_roadmap` to persist the roadmap reassessment.",
   "run-uat":
     "Use `gsd_uat_exec` for acceptance checks so evidence is typed as UAT-owned, and `gsd_resume` after compaction or resume.",
+  "research-project":
+    "Dispatch parallel scout subagents for stack, features, architecture, and pitfalls research; each writes one file under `.gsd/research/` (`STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, `PITFALLS.md`).",
+  "gate-evaluate":
+    "Use `subagent` to dispatch tester agents, then persist each gate with `gsd_save_gate_result`; rely on testers for verification evidence.",
+};
+
+// Per-unit guidance for the nested render mode (renderMode: "nested"), used when this
+// unit's Context Mode line is embedded into a subagent prompt — e.g. the tester prompts
+// dispatched by gate-evaluate. Must instruct the subagent on what IT should do, not
+// re-state the parent coordinator's dispatch instructions. Falls back to
+// CONTEXT_MODE_GUIDANCE_BY_UNIT then the lane default when no nested entry exists.
+export const CONTEXT_MODE_NESTED_GUIDANCE_BY_UNIT: Readonly<Record<string, string>> = {
+  "gate-evaluate":
+    "Run verification checks to answer the gate question, then persist the verdict with `gsd_save_gate_result`.",
 };
 
 /**
@@ -160,7 +184,9 @@ export function composeContextModeInstructions(
 
   const lane = CONTEXT_MODE_LANE_LABELS[manifest.contextMode];
   const guidance =
-    CONTEXT_MODE_GUIDANCE_BY_UNIT[unitType] ?? CONTEXT_MODE_GUIDANCE_BY_LANE[manifest.contextMode];
+    (opts.renderMode === "nested" ? CONTEXT_MODE_NESTED_GUIDANCE_BY_UNIT[unitType] : undefined)
+    ?? CONTEXT_MODE_GUIDANCE_BY_UNIT[unitType]
+    ?? CONTEXT_MODE_GUIDANCE_BY_LANE[manifest.contextMode];
   if (opts.renderMode === "nested") {
     return `Context Mode (${lane} lane): ${guidance}`;
   }

package/src/resources/extensions/gsd/unit-registry.ts

@@ -98,7 +98,13 @@ export const UNIT_REGISTRY = {
     scopeClass: "standard",
     phaseChain: ["research"],
     toolContract: {
-      allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+      allowedGsdTools: [
+        "gsd_summary_save",
+        "gsd_decision_save",
+        "gsd_exec",
+        "gsd_exec_search",
+        "gsd_resume",
+      ],
       requiredWorkflowTools: ["gsd_summary_save"],
     },
   },
@@ -111,10 +117,11 @@ export const UNIT_REGISTRY = {
         "gsd_milestone_status",
         "gsd_plan_milestone",
         "gsd_plan_slice",
+        "gsd_plan_task",
         "gsd_decision_save",
         "gsd_requirement_update",
       ],
-      requiredWorkflowTools: ["gsd_milestone_status", "gsd_plan_milestone", "gsd_plan_slice"],
+      requiredWorkflowTools: ["gsd_milestone_status", "gsd_plan_milestone", "gsd_plan_slice", "gsd_plan_task"],
     },
   },
   "discuss-milestone": {
@@ -154,7 +161,15 @@ export const UNIT_REGISTRY = {
     scopeClass: "section-close",
     phaseChain: ["validation", "planning"],
     toolContract: {
-      allowedGsdTools: ["gsd_milestone_status", "gsd_validate_milestone", "gsd_reassess_roadmap", "subagent"],
+      allowedGsdTools: [
+        "gsd_milestone_status",
+        "gsd_exec",
+        "gsd_exec_search",
+        "gsd_resume",
+        "gsd_validate_milestone",
+        "gsd_reassess_roadmap",
+        "subagent",
+      ],
       requiredWorkflowTools: ["gsd_milestone_status", "gsd_validate_milestone", "gsd_reassess_roadmap"],
     },
   },
@@ -165,6 +180,9 @@ export const UNIT_REGISTRY = {
     toolContract: {
       allowedGsdTools: [
         "gsd_milestone_status",
+        "gsd_exec",
+        "gsd_exec_search",
+        "gsd_resume",
         "gsd_requirement_update",
         "gsd_summary_save",
         "gsd_complete_milestone",
@@ -202,13 +220,14 @@ export const UNIT_REGISTRY = {
       allowedGsdTools: [
         "gsd_milestone_status",
         "gsd_plan_slice",
+        "gsd_plan_task",
         "gsd_reassess_roadmap",
         "gsd_decision_save",
         "gsd_exec",
         "gsd_exec_search",
         "gsd_resume",
       ],
-      requiredWorkflowTools: ["gsd_plan_slice", "gsd_reassess_roadmap"],
+      requiredWorkflowTools: ["gsd_plan_slice", "gsd_plan_task", "gsd_reassess_roadmap"],
     },
   },
   "refine-slice": {
@@ -244,6 +263,8 @@ export const UNIT_REGISTRY = {
       allowedGsdTools: [
         "gsd_milestone_status",
         "gsd_exec",
+        "gsd_exec_search",
+        "gsd_resume",
         "gsd_slice_complete",
         "gsd_task_reopen",
         "gsd_replan_slice",
@@ -326,7 +347,13 @@ export const UNIT_REGISTRY = {
     scopeClass: "execute-task",
     phaseChain: ["execution"],
     toolContract: {
-      allowedGsdTools: ["gsd_task_complete", "gsd_summary_save", "gsd_decision_save"],
+      allowedGsdTools: [
+        "gsd_milestone_status",
+        "gsd_task_complete",
+        "gsd_exec",
+        "gsd_summary_save",
+        "gsd_decision_save",
+      ],
       requiredWorkflowTools: ["gsd_task_complete", "gsd_summary_save"],
     },
   },
@@ -413,12 +440,15 @@ export const UNIT_REGISTRY = {
       requiredWorkflowTools: ["ask_user_questions"],
     },
   },
+  // research-project dispatches 4 parallel scout subagents (Task calls); each scout
+  // writes one file under .gsd/research/ directly. The parent coordinator does not
+  // call gsd_summary_save or gsd_decision_save — the scouts own their own output.
   "research-project": {
     kind: "primary",
     scopeClass: "standard",
     phaseChain: ["research"],
     toolContract: {
-      allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+      allowedGsdTools: [],
       requiredWorkflowTools: [],
     },
   },

package/src/resources/extensions/gsd/unmerged-milestone-guard.ts

@@ -1,6 +1,8 @@
 // Project/App: gsd-pi
 // File Purpose: Block new workflow entry when completed milestone branches are still unmerged.
 
+import { execFileSync } from "node:child_process";
+
 import {
   nativeBranchExists,
   nativeDetectMainBranch,
@@ -12,17 +14,23 @@ import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
 import { getAllMilestones } from "./gsd-db.js";
 import { resolveMilestoneIntegrationBranch } from "./git-service.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
-import { captureRootDirtySnapshot, type RootDirtyEntry } from "./root-write-leak-guard.js";
 import { isClosedStatus } from "./status-guards.js";
 
+export interface UnmergedMilestoneDirtyEntry {
+  path: string;
+  status: string;
+}
+
 export interface UnmergedMilestoneBlocker {
   milestoneId: string;
   branch: string;
   integrationBranch: string;
   files: string[];
-  dirtyOverlap: RootDirtyEntry[];
+  dirtyOverlap: UnmergedMilestoneDirtyEntry[];
 }
 
+type UnmergedMilestoneDirtySnapshot = Map<string, UnmergedMilestoneDirtyEntry>;
+
 const BLOCKED_COMMANDS = new Set([
   "auto",
   "next",
@@ -67,6 +75,32 @@ function isRuntimePath(path: string): boolean {
   return path === ".gsd" || path.startsWith(".gsd/");
 }
 
+function captureDirtyPathStatusSnapshot(rootPath: string): UnmergedMilestoneDirtySnapshot {
+  const snapshot: UnmergedMilestoneDirtySnapshot = new Map();
+  let status = "";
+  try {
+    status = execFileSync("git", ["status", "--porcelain", "--untracked-files=all"], {
+      cwd: rootPath,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+    });
+  } catch {
+    return snapshot;
+  }
+
+  for (const line of status.split("\n")) {
+    if (!line.trim()) continue;
+    const code = line.slice(0, 2);
+    const path = line.slice(3).replace(/^"|"$/g, "");
+    if (!path || isRuntimePath(path)) continue;
+    snapshot.set(path, {
+      path,
+      status: code.trim() || code,
+    });
+  }
+  return snapshot;
+}
+
 function formatCommandLabel(attemptedCommand: string): string {
   const trimmed = attemptedCommand.trim();
   return trimmed ? `/gsd ${trimmed}` : "/gsd";
@@ -132,7 +166,7 @@ export async function findUnmergedCompletedMilestones(base: string): Promise<Unm
   await ensureDbOpen(base);
 
   const blockers: UnmergedMilestoneBlocker[] = [];
-  const dirtyByPath = captureRootDirtySnapshot(base);
+  let dirtyByPath: UnmergedMilestoneDirtySnapshot | null = null;
 
   for (const milestone of getAllMilestones()) {
     if (!isClosedStatus(milestone.status)) continue;
@@ -158,14 +192,16 @@ export async function findUnmergedCompletedMilestones(base: string): Promise<Unm
     const uniqueFiles = [...new Set(files)].sort();
     if (uniqueFiles.length === 0) continue;
 
+    if (!dirtyByPath) dirtyByPath = captureDirtyPathStatusSnapshot(base);
+    const dirtySnapshot = dirtyByPath;
     blockers.push({
       milestoneId: milestone.id,
       branch,
       integrationBranch,
       files: uniqueFiles,
       dirtyOverlap: uniqueFiles
-        .map((path) => dirtyByPath.get(path))
-        .filter((entry): entry is RootDirtyEntry => Boolean(entry)),
+        .map((path) => dirtySnapshot.get(path))
+        .filter((entry): entry is UnmergedMilestoneDirtyEntry => Boolean(entry)),
     });
   }
 

package/src/resources/extensions/gsd/validation-block-guard.ts

@@ -7,7 +7,7 @@ import { getAutoWorktreePath, isInAutoWorktree } from "./auto-worktree.js";
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
 import { refreshWorkflowDatabaseFromDisk } from "./db-workspace.js";
 import { getIsolationMode } from "./preferences.js";
-import { deriveState } from "./state.js";
+import { deriveState, invalidateStateCache } from "./state.js";
 import type { GSDState } from "./types.js";
 import { detectWorktreeName } from "./worktree.js";
 
@@ -133,12 +133,7 @@ export function formatValidationBlockedMessage(
   ].join("\n\n");
 }
 
-export async function getValidationBlockMessageForBase(
-  base: string,
-  attemptedCommand = "",
-): Promise<string | null> {
-  await ensureDbOpen(base);
-  refreshWorkflowDatabaseFromDisk();
+async function deriveValidationBlockState(base: string): Promise<GSDState> {
   let state = await deriveState(base);
 
   if (
@@ -153,5 +148,16 @@ export async function getValidationBlockMessageForBase(
     }
   }
 
+  return state;
+}
+
+export async function getValidationBlockMessageForBase(
+  base: string,
+  attemptedCommand = "",
+): Promise<string | null> {
+  await ensureDbOpen(base);
+  refreshWorkflowDatabaseFromDisk();
+  invalidateStateCache();
+  const state = await deriveValidationBlockState(base);
   return formatValidationBlockedMessage(state, attemptedCommand);
 }

package/src/resources/extensions/gsd/verification-gate.ts

@@ -244,6 +244,14 @@ export function formatFailureContext(result: VerificationResult): string {
   return header + body;
 }
 
+export function formatFailureSignature(result: VerificationResult): string {
+  return result.checks
+    .filter((check) => check.exitCode !== 0)
+    .map((check) => `${check.command.trim()}#${check.exitCode}`)
+    .sort()
+    .join("\n");
+}
+
 // ─── Gate Execution ─────────────────────────────────────────────────────────
 
 /** Characters that indicate shell control syntax when unquoted in a command string. */

package/src/resources/extensions/gsd/workflow-manifest.ts

@@ -10,11 +10,12 @@ import type { ArtifactRow, MilestoneRow } from "./db-milestone-artifact-rows.js"
 import type { SliceRow, TaskRow } from "./db-task-slice-rows.js";
 import type { VerificationEvidenceRow } from "./db-verification-evidence-rows.js";
 import type { Decision, GateRow, Requirement } from "./types.js";
-import { atomicWriteSync } from "./atomic-write.js";
+import { atomicWriteAsync, atomicWriteSync } from "./atomic-write.js";
 import { getAllDecisionsFromMemories } from "./context-store.js";
 import { backfillDecisionsToMemories } from "./memory-backfill.js";
 import { invalidateAllCaches } from "./cache.js";
-import { readFileSync, existsSync, mkdirSync } from "node:fs";
+import { logWarning } from "./workflow-logger.js";
+import { readFileSync, existsSync } from "node:fs";
 import { isAbsolute, join, relative, resolve } from "node:path";
 
 // ─── Manifest Types ──────────────────────────────────────────────────────
@@ -349,16 +350,146 @@ export function snapshotState(): StateManifest {
 
 // ─── writeManifest ───────────────────────────────────────────────────────
 
+interface ManifestWriteState {
+  filePath: string;
+  latestJson: string | null;
+  inFlightJson: string | null;
+  /** Set by sync exit flush so an in-flight async write cannot leave stale data on disk. */
+  syncFlushJson: string | null;
+  active: Promise<void> | null;
+}
+
+const manifestWrites = new Map<string, ManifestWriteState>();
+let processTeardownFlushInstalled = false;
+let beforeExitFlushStarted = false;
+
+function manifestWriteKey(basePath: string): string {
+  return resolve(basePath);
+}
+
+function manifestFilePath(basePath: string): string {
+  return join(resolve(basePath), ".gsd", "state-manifest.json");
+}
+
+function describeError(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+function logManifestWriteFailure(filePath: string, err: unknown): void {
+  logWarning("manifest", `state manifest write failed: ${describeError(err)}`, { file: filePath });
+}
+
+async function drainManifestWrites(key: string, state: ManifestWriteState): Promise<void> {
+  let lastWriteError: unknown = null;
+  try {
+    while (state.latestJson !== null && state.syncFlushJson === null) {
+      const json = state.latestJson;
+      state.latestJson = null;
+      state.inFlightJson = json;
+      try {
+        await atomicWriteAsync(state.filePath, json);
+        if (state.syncFlushJson !== null) {
+          atomicWriteSync(state.filePath, state.syncFlushJson);
+          break;
+        }
+        lastWriteError = null;
+      } catch (err) {
+        lastWriteError = err;
+        logManifestWriteFailure(state.filePath, err);
+      } finally {
+        state.inFlightJson = null;
+      }
+    }
+  } finally {
+    state.active = null;
+    if (state.latestJson === null && state.inFlightJson === null) {
+      manifestWrites.delete(key);
+    }
+  }
+  if (lastWriteError !== null && state.syncFlushJson === null) {
+    throw lastWriteError;
+  }
+}
+
+function enqueueManifestWrite(basePath: string, json: string): void {
+  const key = manifestWriteKey(basePath);
+  let state = manifestWrites.get(key);
+  if (!state) {
+    state = {
+      filePath: manifestFilePath(basePath),
+      latestJson: null,
+      inFlightJson: null,
+      syncFlushJson: null,
+      active: null,
+    };
+    manifestWrites.set(key, state);
+  }
+
+  state.latestJson = json;
+  if (!state.active) {
+    const active = drainManifestWrites(key, state);
+    void active.catch(() => {});
+    state.active = active;
+  }
+}
+
 /**
- * Write current DB state to .gsd/state-manifest.json via atomicWriteSync.
+ * Queue current DB state for an async atomic write to .gsd/state-manifest.json.
  * Uses JSON.stringify with 2-space indent for git three-way merge friendliness.
  */
 export function writeManifest(basePath: string): void {
   const manifest = snapshotState();
   const json = JSON.stringify(manifest, null, 2);
-  const dir = join(basePath, ".gsd");
-  mkdirSync(dir, { recursive: true });
-  atomicWriteSync(join(dir, "state-manifest.json"), json);
+  enqueueManifestWrite(basePath, json);
+}
+
+async function flushManifestByKey(key: string): Promise<void> {
+  for (;;) {
+    const active = manifestWrites.get(key)?.active;
+    if (!active) return;
+    await active;
+  }
+}
+
+/**
+ * Wait for any queued manifest write for this base path to become durable.
+ */
+export async function flushManifest(basePath: string): Promise<void> {
+  await flushManifestByKey(manifestWriteKey(basePath));
+}
+
+export async function flushAllManifests(): Promise<void> {
+  await Promise.all(Array.from(manifestWrites.keys(), key => flushManifestByKey(key)));
+}
+
+function flushAllManifestsSync(): void {
+  for (const [key, state] of manifestWrites) {
+    const json = state.latestJson ?? state.inFlightJson;
+    if (json === null) continue;
+    try {
+      atomicWriteSync(state.filePath, json);
+      state.latestJson = null;
+      state.inFlightJson = null;
+      state.syncFlushJson = json;
+      manifestWrites.delete(key);
+    } catch (err) {
+      logManifestWriteFailure(state.filePath, err);
+    }
+  }
+}
+
+export function installManifestFlushOnProcessTeardown(): void {
+  if (processTeardownFlushInstalled) return;
+  processTeardownFlushInstalled = true;
+
+  process.once("beforeExit", () => {
+    if (beforeExitFlushStarted) return;
+    beforeExitFlushStarted = true;
+    void flushAllManifests();
+  });
+  process.once("exit", () => {
+    flushAllManifestsSync();
+  });
 }
 
 // ─── readManifest ────────────────────────────────────────────────────────
@@ -414,9 +545,12 @@ function restoreArtifactProjections(basePath: string, manifest: StateManifest):
   if (manifest.artifacts === undefined) return;
 
   for (const artifact of manifest.artifacts) {
+    const content = artifact.full_content ?? "";
+    if (content === "") continue;
+
     atomicWriteSync(
       artifactProjectionPath(basePath, artifact.path),
-      artifact.full_content ?? "",
+      content,
     );
   }
 }