@opengsd/gsd-pi 1.5.0-dev.4fb2d460 → 1.5.0-dev.c4c8885f

package/src/resources/extensions/gsd/markdown-renderer.ts

@@ -38,9 +38,10 @@ import {
   resolveSlicePath,
   resolveTaskFile,
   resolveTasksDir,
+  targetMilestoneFile,
+  targetSliceFile,
   gsdProjectionRoot,
   gsdRoot,
-  buildMilestoneFileName,
   buildTaskFileName,
   buildSliceFileName,
 } from "./paths.js";
@@ -52,9 +53,6 @@ import { readCompatMarker, writeCompatMarker, computeProjectionSha } from "./com
 import type { RiskLevel } from "./types.js";
 import {
   phaseDirName,
-  planFileName,
-  milestoneIdToPhaseNum,
-  sliceIdToPlanNum,
   derivePhaseSlug,
 } from "./layout-policy.js";
 
@@ -176,23 +174,6 @@ function sanitizeInlineRoadmapText(value: string | null | undefined): string {
     .trim();
 }
 
-function resolveRoadmapProjectionPath(basePath: string, milestoneId: string): string {
-  const phaseNum = milestoneIdToPhaseNum(milestoneId);
-  const existing = resolveMilestonePath(basePath, milestoneId);
-  const legacyBase = legacyMilestonesDir(basePath);
-  const isLegacyLayout = existing
-    ? existing.startsWith(legacyBase + "/") || existing.startsWith(legacyBase + "\\")
-    : isLegacyMilestonesLayout(basePath);
-  const phaseDir = existing ?? join(
-    isLegacyLayout ? legacyBase : milestonesDir(basePath),
-    isLegacyLayout ? milestoneId : canonicalPhaseDirName(milestoneId, getMilestone(milestoneId)?.title),
-  );
-  const roadmapFileName = isLegacyLayout
-    ? `${milestoneId}-ROADMAP.md`
-    : `${String(phaseNum).padStart(2, "0")}-ROADMAP.md`;
-  return join(phaseDir, roadmapFileName);
-}
-
 function isMilestoneFlatPhaseLayout(basePath: string, milestoneId: string): boolean {
   const existing = resolveMilestonePath(basePath, milestoneId);
   const legacyBase = legacyMilestonesDir(basePath);
@@ -600,7 +581,7 @@ export async function renderRoadmapFromDb(
       "projection",
       `renderRoadmapFromDb skipped unplanned milestone ${milestoneId} (zero slices, empty vision) — refusing to write a stub ROADMAP`,
     );
-    const absPath = resolveRoadmapProjectionPath(basePath, milestoneId);
+    const absPath = targetMilestoneFile(basePath, milestoneId, "ROADMAP", milestone.title);
     if (existsSync(absPath)) {
       const artifactPath = toArtifactPath(absPath, basePath);
       unlinkSync(absPath);
@@ -614,7 +595,7 @@ export async function renderRoadmapFromDb(
     return { skipped: "unplanned-milestone" };
   }
 
-  const absPath = resolveRoadmapProjectionPath(basePath, milestoneId);
+  const absPath = targetMilestoneFile(basePath, milestoneId, "ROADMAP", milestone.title);
   const artifactPath = toArtifactPath(absPath, basePath);
   const content = renderRoadmapMarkdown(milestone, slices);
 
@@ -655,25 +636,20 @@ export async function renderMilestoneArtifactsFromDb(
   const artifacts = getMilestoneScopedArtifacts(milestoneId);
   if (artifacts.length === 0) return false;
 
-  const phaseDir = resolveMilestonePath(basePath, milestoneId) ??
-    join(
-      milestonesDir(basePath),
-      canonicalPhaseDirName(milestoneId, getMilestone(milestoneId)?.title),
-    );
-  mkdirSync(phaseDir, { recursive: true });
-
-  const legacyBase = legacyMilestonesDir(basePath);
-  const isLegacy = phaseDir.startsWith(legacyBase + "/") || phaseDir.startsWith(legacyBase + "\\");
+  const milestone = getMilestone(milestoneId);
 
   let wrote = false;
   for (const artifact of artifacts) {
     if (artifact.artifact_type === "ROADMAP") continue;
     if (!artifact.full_content.trim()) continue;
 
-    const fileName = isLegacy
-      ? `${milestoneId}-${artifact.artifact_type}.md`
-      : buildMilestoneFileName(milestoneId, artifact.artifact_type);
-    const absPath = join(phaseDir, fileName);
+    const absPath = targetMilestoneFile(
+      basePath,
+      milestoneId,
+      artifact.artifact_type,
+      milestone?.title,
+    );
+    mkdirSync(dirname(absPath), { recursive: true });
     const artifactPath = toArtifactPath(absPath, basePath);
     await writeAndStore(absPath, artifactPath, artifact.full_content, {
       artifact_type: artifact.artifact_type,
@@ -824,22 +800,12 @@ export async function renderSliceSummary(
     return false; // No slice data — skip silently
   }
 
-  // Flat-phase: resolve or create the phase dir, since resolveSlicePath only
-  // finds existing dirs. In flat-phase the slice "path" is the phase dir.
-  let slicePath = resolveSlicePath(basePath, milestoneId, sliceId);
-  if (!slicePath) {
-    const mDir = milestonesDir(basePath);
-    const dirName = canonicalPhaseDirName(milestoneId, getMilestone(milestoneId)?.title);
-    slicePath = join(mDir, dirName);
-    mkdirSync(slicePath, { recursive: true });
-  }
-
+  const milestoneTitle = getMilestone(milestoneId)?.title;
   let wrote = false;
 
-  // Write SUMMARY — flat-phase: NN-MM-SUMMARY.md inside phase dir
   if (slice.full_summary_md) {
-    const summaryName = planFileName(milestoneIdToPhaseNum(milestoneId), sliceIdToPlanNum(sliceId), "SUMMARY");
-    const summaryAbs = join(slicePath, summaryName);
+    const summaryAbs = targetSliceFile(basePath, milestoneId, sliceId, "SUMMARY", milestoneTitle);
+    mkdirSync(dirname(summaryAbs), { recursive: true });
     const summaryArtifact = toArtifactPath(summaryAbs, basePath);
 
     await writeAndStore(summaryAbs, summaryArtifact, slice.full_summary_md, {
@@ -850,10 +816,9 @@ export async function renderSliceSummary(
     wrote = true;
   }
 
-  // Write UAT — flat-phase: NN-MM-UAT.md inside phase dir
   if (slice.full_uat_md) {
-    const uatName = planFileName(milestoneIdToPhaseNum(milestoneId), sliceIdToPlanNum(sliceId), "UAT");
-    const uatAbs = join(slicePath, uatName);
+    const uatAbs = targetSliceFile(basePath, milestoneId, sliceId, "UAT", milestoneTitle);
+    mkdirSync(dirname(uatAbs), { recursive: true });
     const uatArtifact = toArtifactPath(uatAbs, basePath);
 
     await writeAndStore(uatAbs, uatArtifact, slice.full_uat_md, {
@@ -1080,7 +1045,7 @@ function detectStaleRendersImpl(basePath: string): StaleEntry[] {
     // TODO(flat-phase): roadmap checkbox parsing may not match flat-phase
     // roadmap format, causing false-positive drift loops. Skip during transition.
     /*
-    const roadmapPath = resolveRoadmapProjectionPath(basePath, milestone.id);
+    const roadmapPath = targetMilestoneFile(basePath, milestone.id, "ROADMAP", milestone.title);
     if (existsSync(roadmapPath)) {
       try {
         const parsed = parseProjectionByIdentity(roadmapPath, parseRoadmap) as ReturnType<typeof parseRoadmap>;
@@ -1172,36 +1137,28 @@ function detectStaleRendersImpl(basePath: string): StaleEntry[] {
         }
       }
 
-      // Check missing slice summary/UAT files
+      // Check missing slice summary/UAT files. Use the same target helper as
+      // renderSliceSummary so detection and repair agree on flat-phase vs legacy
+      // output locations.
       const sliceRow = getSlice(milestone.id, slice.id);
       if (sliceRow && sliceRow.status === "complete") {
-        // Use the SAME path construction as renderSliceSummary (planFileName format)
-        // so the detector and repair always agree on the file location.
-        const slicePath = resolveSlicePath(basePath, milestone.id, slice.id);
-        if (slicePath) {
-          const phaseNum = milestoneIdToPhaseNum(milestone.id);
-          const planNum = sliceIdToPlanNum(slice.id);
-
-          if (sliceRow.full_summary_md) {
-            const summaryName = planFileName(phaseNum, planNum, "SUMMARY");
-            const summaryAbsPath = join(slicePath, summaryName);
-            if (!existsSync(summaryAbsPath)) {
-              stale.push({
-                path: summaryAbsPath,
-                reason: `${slice.id} is complete with summary in DB but SUMMARY.md missing on disk`,
-              });
-            }
+        if (sliceRow.full_summary_md) {
+          const summaryAbsPath = targetSliceFile(basePath, milestone.id, slice.id, "SUMMARY", milestone.title);
+          if (!existsSync(summaryAbsPath)) {
+            stale.push({
+              path: summaryAbsPath,
+              reason: `${slice.id} is complete with summary in DB but SUMMARY.md missing on disk`,
+            });
           }
+        }
 
-          if (sliceRow.full_uat_md) {
-            const uatName = planFileName(phaseNum, planNum, "UAT");
-            const uatAbsPath = join(slicePath, uatName);
-            if (!existsSync(uatAbsPath)) {
-              stale.push({
-                path: uatAbsPath,
-                reason: `${slice.id} is complete with UAT in DB but UAT.md missing on disk`,
-              });
-            }
+        if (sliceRow.full_uat_md) {
+          const uatAbsPath = targetSliceFile(basePath, milestone.id, slice.id, "UAT", milestone.title);
+          if (!existsSync(uatAbsPath)) {
+            stale.push({
+              path: uatAbsPath,
+              reason: `${slice.id} is complete with UAT in DB but UAT.md missing on disk`,
+            });
           }
         }
       }
@@ -1257,12 +1214,14 @@ export async function renderReplanFromDb(
   sliceId: string,
   replanData: ReplanData,
 ): Promise<{ replanPath: string; content: string }> {
-  // Flat-phase: replan file lives in the phase dir
-  const slicePath = resolveSlicePath(basePath, milestoneId, sliceId)
-    ?? join(milestonesDir(basePath), canonicalPhaseDirName(milestoneId, getMilestone(milestoneId)?.title));
-  const phaseNum = milestoneIdToPhaseNum(milestoneId);
-  const planNum = sliceIdToPlanNum(sliceId);
-  const absPath = join(slicePath, planFileName(phaseNum, planNum, "REPLAN"));
+  const absPath = targetSliceFile(
+    basePath,
+    milestoneId,
+    sliceId,
+    "REPLAN",
+    getMilestone(milestoneId)?.title,
+  );
+  mkdirSync(dirname(absPath), { recursive: true });
   const artifactPath = toArtifactPath(absPath, basePath);
 
   const lines: string[] = [];
@@ -1299,24 +1258,14 @@ export async function renderAssessmentFromDb(
   sliceId: string,
   assessmentData: AssessmentData,
 ): Promise<{ assessmentPath: string; content: string }> {
-  // Flat-phase: the assessment file lives in the phase dir, NOT in a slices/SID/
-  // subdir. resolveSlicePath() detects a slices/SID/ dir unconditionally, so a
-  // stray slices/SID/ created by an earlier planning step would send this write
-  // to a hybrid path (wrong dir, flat filename) that verification cannot find.
-  // Guard with the same legacy-base check relSlicePath() uses so flat-phase
-  // milestones always target the phase dir.
-  const mDir = resolveMilestonePath(basePath, milestoneId);
-  const legacyBase = legacyMilestonesDir(basePath);
-  const isLegacyLayout = mDir
-    ? mDir.startsWith(legacyBase + "/") || mDir.startsWith(legacyBase + "\\")
-    : false;
-  const fallbackDir = join(milestonesDir(basePath), canonicalPhaseDirName(milestoneId, getMilestone(milestoneId)?.title));
-  const slicePath = isLegacyLayout
-    ? (resolveSlicePath(basePath, milestoneId, sliceId) ?? fallbackDir)
-    : (mDir ?? fallbackDir);
-  const phaseNum = milestoneIdToPhaseNum(milestoneId);
-  const planNum = sliceIdToPlanNum(sliceId);
-  const absPath = join(slicePath, planFileName(phaseNum, planNum, "ASSESSMENT"));
+  const absPath = targetSliceFile(
+    basePath,
+    milestoneId,
+    sliceId,
+    "ASSESSMENT",
+    getMilestone(milestoneId)?.title,
+  );
+  mkdirSync(dirname(absPath), { recursive: true });
   const artifactPath = toArtifactPath(absPath, basePath);
 
   const lines: string[] = [];

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

@@ -265,7 +265,7 @@ export function snapshotUnitMetrics(
   }
   saveLedger(basePath, ledger);
 
-  if (isUnifiedAuditEnabled()) {
+  if (isUnifiedAuditEnabled(basePath)) {
     emitUokAuditEvent(
       basePath,
       buildAuditEnvelope({
@@ -458,7 +458,7 @@ export function snapshotUnitMetricsByScope(
   }
   saveLedger(base, scopedLedger);
 
-  if (isUnifiedAuditEnabled()) {
+  if (isUnifiedAuditEnabled(base)) {
     emitUokAuditEvent(
       base,
       buildAuditEnvelope({

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

@@ -11,7 +11,7 @@
  */
 
 import { readdirSync, existsSync, realpathSync, statSync, Dirent } from "node:fs";
-import { join, dirname, normalize, resolve } from "node:path";
+import { join, dirname, normalize, relative, resolve } from "node:path";
 import { homedir } from "node:os";
 import { spawnSync } from "node:child_process";
 import { nativeScanGsdTree, type GsdTreeEntry } from "./native-parser-bridge.js";
@@ -379,21 +379,26 @@ export function resolveGsdPathContract(
   const resolvedWorkRoot = resolve(workRoot || process.cwd());
   const isWorktree = isGsdWorktreePath(resolvedWorkRoot);
   if (isWorktree && !originalProjectRoot?.trim()) {
-    const projectGsd = resolveExternalStateProjectGsdFromWorktreePath(resolvedWorkRoot);
-    if (projectGsd) {
+    const rawProjectGsd = resolveExternalStateProjectGsdFromWorktreePath(resolvedWorkRoot);
+    if (rawProjectGsd) {
+      // Canonicalize the `.gsd` root so the DB path matches what every other
+      // accessor (gsdRoot/gsdProjectionRoot) returns — otherwise an unresolved
+      // symlink (e.g. `/mnt/c/.../.gsd` → native ext4 on WSL) selects the wrong
+      // journal mode and yields a fragile, move-prone handle. See issue #1239.
+      const projectGsd = normalizeRealPath(rawProjectGsd);
       return {
         projectRoot: dirname(dirname(projectGsd)),
         workRoot: resolvedWorkRoot,
         projectGsd,
-        worktreeGsd: join(resolvedWorkRoot, ".gsd"),
+        worktreeGsd: normalizeRealPath(join(resolvedWorkRoot, ".gsd")),
         projectDb: join(projectGsd, "gsd.db"),
         isWorktree,
       };
     }
   }
   const projectRoot = resolve(resolveWorktreeProjectRoot(resolvedWorkRoot, originalProjectRoot));
-  const projectGsd = join(projectRoot, ".gsd");
-  const worktreeGsd = isWorktree ? join(resolvedWorkRoot, ".gsd") : null;
+  const projectGsd = normalizeRealPath(join(projectRoot, ".gsd"));
+  const worktreeGsd = isWorktree ? normalizeRealPath(join(resolvedWorkRoot, ".gsd")) : null;
 
   return {
     projectRoot,
@@ -916,10 +921,24 @@ export function resolveTaskFile(
   basePath: string, milestoneId: string, sliceId: string,
   taskId: string, suffix: string
 ): string | null {
+  const phaseDir = resolveMilestonePath(basePath, milestoneId);
+  if (!phaseDir) return null;
+
+  const legacyBase = legacyMilestonesDir(basePath);
+  const isLegacy = phaseDir.startsWith(legacyBase + "/") || phaseDir.startsWith(legacyBase + "\\");
+
+  if (suffix !== "PLAN" && !isLegacy) {
+    const flatPath = join(phaseDir, buildTaskFileName(taskId, suffix));
+    return existsSync(flatPath) ? flatPath : null;
+  }
+
   const tDir = resolveTasksDir(basePath, milestoneId, sliceId);
-  if (!tDir) return null;
-  const file = resolveFile(tDir, taskId, suffix);
-  return file ? join(tDir, file) : null;
+  if (tDir) {
+    const file = resolveFile(tDir, taskId, suffix);
+    if (file) return join(tDir, file);
+  }
+
+  return null;
 }
 
 // ─── Relative Path Builders (for prompts — .gsd/milestones/...) ────────────
@@ -954,31 +973,41 @@ export function relMilestonePath(basePath: string, milestoneId: string, title?:
 }
 
 /**
- * Build relative .gsd/ path to a milestone file.
- * Layout-aware: uses resolveMilestoneFile to find NN-SUFFIX.md (flat-phase)
- * or M001-SUFFIX.md (legacy). Falls back to a layout-appropriate canonical
- * name when the file doesn't exist yet.
+ * Build the canonical absolute write target for a milestone file.
+ * Existing compatibility filenames are intentionally ignored; readers that need
+ * to preserve an existing file should call resolveMilestoneFile first.
  */
-export function relMilestoneFile(
-  basePath: string, milestoneId: string, suffix: string
+export function targetMilestoneFile(
+  basePath: string, milestoneId: string, suffix: string, title?: string
 ): string {
-  const mRel = relMilestonePath(basePath, milestoneId);
-  // resolveMilestoneFile checks NN-SUFFIX.md (flat-phase) and MID-SUFFIX.md (legacy).
-  const absFile = resolveMilestoneFile(basePath, milestoneId, suffix);
-  if (absFile) {
-    const fileName = absFile.split(/[/\\]/).pop()!;
-    return `${mRel}/${fileName}`;
-  }
-  // File doesn't exist yet — use layout-aware fallback filename.
   const mDir = resolveMilestonePath(basePath, milestoneId);
   const legacyBase = legacyMilestonesDir(basePath);
   const isLegacy = mDir
     ? mDir.startsWith(legacyBase + "/") || mDir.startsWith(legacyBase + "\\")
-    : false;
+    : isLegacyMilestonesLayout(basePath);
+  const dir = mDir ?? join(
+    isLegacy ? legacyBase : milestonesDir(basePath),
+    isLegacy ? milestoneId : canonicalPhaseDirName(milestoneId, title),
+  );
   const fileName = isLegacy
     ? `${milestoneId}-${suffix}.md`
     : `${String(milestoneIdToPhaseNum(milestoneId)).padStart(2, "0")}-${suffix}.md`;
-  return `${mRel}/${fileName}`;
+  return join(dir, fileName);
+}
+
+/**
+ * Build relative .gsd/ path to a milestone file.
+ * Preserves an existing compatibility filename when present; otherwise falls
+ * back to the canonical write target.
+ */
+export function relMilestoneFile(
+  basePath: string, milestoneId: string, suffix: string, title?: string
+): string {
+  const rel = relative(
+    gsdProjectionRoot(basePath),
+    resolveMilestoneFile(basePath, milestoneId, suffix) ?? targetMilestoneFile(basePath, milestoneId, suffix, title),
+  ).replace(/\\/g, "/");
+  return `.gsd/${rel}`;
 }
 
 /**
@@ -1010,34 +1039,44 @@ export function relSlicePath(
 }
 
 /**
- * Build relative .gsd/ path to a slice file.
- * Layout-aware: legacy uses S01-SUFFIX.md; flat-phase uses NN-MM-SUFFIX.md.
- *
- * @param milestoneTitle - Optional milestone title forwarded to relSlicePath /
- *   relMilestonePath for title-aware flat-phase fallback dir naming. Only used
- *   when the phase directory does not yet exist on disk.
+ * Build the canonical absolute write target for a slice file.
+ * Existing compatibility filenames are intentionally ignored; readers that need
+ * to preserve an existing file should call resolveSliceFile first.
  */
-export function relSliceFile(
+export function targetSliceFile(
   basePath: string, milestoneId: string, sliceId: string, suffix: string, milestoneTitle?: string
 ): string {
-  const sRel = relSlicePath(basePath, milestoneId, sliceId, milestoneTitle);
-  const absPath = resolveSliceFile(basePath, milestoneId, sliceId, suffix);
-  if (absPath) {
-    const fileName = absPath.split(/[/\\]/).pop()!;
-    return `${sRel}/${fileName}`;
-  }
-  // Fallback when file doesn't exist yet — use layout-aware filename.
   const mDir = resolveMilestonePath(basePath, milestoneId);
   const legacyBase = legacyMilestonesDir(basePath);
   const isLegacy = mDir
     ? mDir.startsWith(legacyBase + "/") || mDir.startsWith(legacyBase + "\\")
-    : false;
-  if (isLegacy) {
-    return `${sRel}/${sliceId}-${suffix}.md`;
-  }
-  const phaseNum = milestoneIdToPhaseNum(milestoneId);
-  const planNum = sliceIdToPlanNum(sliceId);
-  return `${sRel}/${planFileName(phaseNum, planNum, suffix)}`;
+    : isLegacyMilestonesLayout(basePath);
+  const milestoneDir = mDir
+    ?? dirname(targetMilestoneFile(basePath, milestoneId, "ROADMAP", milestoneTitle));
+  const slicesDir = join(milestoneDir, "slices");
+  const dir = isLegacy
+    ? join(slicesDir, resolveDir(slicesDir, sliceId) ?? sliceId)
+    : milestoneDir;
+  const fileName = isLegacy
+    ? `${sliceId}-${suffix}.md`
+    : planFileName(milestoneIdToPhaseNum(milestoneId), sliceIdToPlanNum(sliceId), suffix);
+  return join(dir, fileName);
+}
+
+/**
+ * Build relative .gsd/ path to a slice file.
+ * Preserves an existing compatibility filename when present; otherwise falls
+ * back to the canonical write target.
+ */
+export function relSliceFile(
+  basePath: string, milestoneId: string, sliceId: string, suffix: string, milestoneTitle?: string
+): string {
+  const rel = relative(
+    gsdProjectionRoot(basePath),
+    resolveSliceFile(basePath, milestoneId, sliceId, suffix)
+      ?? targetSliceFile(basePath, milestoneId, sliceId, suffix, milestoneTitle),
+  ).replace(/\\/g, "/");
+  return `.gsd/${rel}`;
 }
 
 /**
@@ -1049,7 +1088,7 @@ export function relSliceFile(
  */
 export function relTaskFile(
   basePath: string, milestoneId: string, sliceId: string,
-  taskId: string, suffix: string
+  taskId: string, suffix: string, milestoneTitle?: string
 ): string {
   const sDir = resolveSlicePath(basePath, milestoneId, sliceId);
   const phaseDir = resolveMilestonePath(basePath, milestoneId);
@@ -1062,6 +1101,6 @@ export function relTaskFile(
   if (suffix === "PLAN") {
     return relSliceFile(basePath, milestoneId, sliceId, "PLAN");
   }
-  const relS = relSlicePath(basePath, milestoneId, sliceId);
+  const relS = relSlicePath(basePath, milestoneId, sliceId, milestoneTitle);
   return `${relS}/${buildTaskFileName(taskId, suffix)}`;
 }

package/src/resources/extensions/gsd/post-unit-hooks.ts

@@ -11,6 +11,7 @@ import type {
   HookStatusEntry,
   PostUnitGateBlock,
 } from "./types.js";
+import type { SidecarItem } from "./auto/session.js";
 import { getOrCreateRegistry, resolveHookArtifactPath } from "./rule-registry.js";
 
 // Re-export resolveHookArtifactPath so existing importers still work.
@@ -75,6 +76,37 @@ export function restoreHookState(basePath: string): void {
   getOrCreateRegistry().restoreState(basePath);
 }
 
+/**
+ * Reconcile a restored `activeHook` against the session's sidecar queue.
+ *
+ * The registry persists `activeHook` to disk but the pending hook *dispatch*
+ * lives only on the non-persisted `s.sidecarQueue`. After a pause/resume or
+ * crash-recovery, `restoreHookState` re-hydrates `activeHook` while the dispatch
+ * is gone, so the registry believes a hook is in-flight but nothing will ever
+ * complete it — and the next unrelated unit's close-out is falsely charged
+ * against the stale hook and blocked. Re-enqueue the missing dispatch so the
+ * hook actually runs, restoring the invariant that a persisted `activeHook`
+ * always has a live dispatch (#1246).
+ */
+export function reconcileRestoredHookDispatch(
+  basePath: string,
+  sidecarQueue: SidecarItem[],
+): void {
+  const dispatch = getOrCreateRegistry().getPendingHookDispatch(basePath);
+  if (!dispatch) return;
+  const alreadyQueued = sidecarQueue.some(
+    item => item.kind === "hook" && item.unitType === dispatch.unitType,
+  );
+  if (alreadyQueued) return;
+  sidecarQueue.push({
+    kind: "hook",
+    unitType: dispatch.unitType,
+    unitId: dispatch.unitId,
+    prompt: dispatch.prompt,
+    model: dispatch.model,
+  });
+}
+
 export function clearPersistedHookState(basePath: string): void {
   getOrCreateRegistry().clearPersistedState(basePath);
 }