@opengsd/gsd-pi 1.3.0-dev.65546769 → 1.3.0-dev.72e3af2a

package/src/resources/extensions/gsd/exec-sandbox.ts

@@ -48,6 +48,8 @@ export interface ExecSandboxOptions {
   now?: () => Date;
   /** Optional override for id generation (tests). */
   generateId?: () => string;
+  /** Optional request cancellation signal. Aborting kills the child process tree. */
+  signal?: AbortSignal;
   /**
    * Grace period (ms) between SIGTERM and SIGKILL on timeout.
    * Defaults to SIGKILL_GRACE_MS. Exposed as a test seam.
@@ -67,6 +69,8 @@ export interface ExecSandboxResult {
   exit_code: number | null;
   signal: NodeJS.Signals | null;
   timed_out: boolean;
+  /** True when an external AbortSignal terminated the child process tree. */
+  aborted?: boolean;
   /**
    * True when the result came from the hard-deadline force-resolve (a non-closing
    * D-state child that never emitted 'close') rather than an observed process exit.
@@ -260,11 +264,23 @@ export function runExecSandbox(
     const effectiveForceResolveDelay = opts.force_resolve_delay_ms ?? (effectiveGraceMs + HARD_DEADLINE_MS);
 
     let timedOut = false;
+    let aborted = false;
     let settled = false;
+    let killInitiated = false;
+    let timer: NodeJS.Timeout | undefined;
     let forceResolveTimer: NodeJS.Timeout | undefined;
+    let abortListener: (() => void) | undefined;
 
-    const timer = setTimeout(() => {
-      timedOut = true;
+    const removeAbortListener = () => {
+      if (opts.signal && abortListener) {
+        opts.signal.removeEventListener("abort", abortListener);
+        abortListener = undefined;
+      }
+    };
+
+    const initiateKill = () => {
+      if (killInitiated) return;
+      killInitiated = true;
       // killProcessTree handles both platforms and kills the whole tree: on Unix
       // it signals the process group (SIGTERM -> grace -> SIGKILL); on Windows it
       // force-kills the tree via taskkill /F /T. Using child.kill("SIGTERM") here
@@ -281,14 +297,14 @@ export function runExecSandbox(
         finalize(null, "SIGKILL", true);
       }, effectiveForceResolveDelay);
       forceResolveTimer.unref?.();
-    }, timeoutMs);
-    timer.unref?.();
+    };
 
     const finalize = (exitCode: number | null, signal: NodeJS.Signals | null, forceResolved = false) => {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
       clearTimeout(forceResolveTimer);
+      removeAbortListener();
       const duration = Date.now() - started;
       const stdoutBuf = Buffer.concat(stdoutChunks);
       const stderrBuf = Buffer.concat(stderrChunks);
@@ -301,11 +317,13 @@ export function runExecSandbox(
       const digest =
         digestBody.length > 0
           ? digestBody
-          : timedOut
-            ? "[no stdout — timed out]"
-            : stderrBuf.length > 0
-              ? `[no stdout — tail of stderr]\n${tail(stderrBuf, opts.digest_chars)}`
-              : "[no output]";
+          : aborted
+            ? "[no stdout — aborted]"
+            : timedOut
+              ? "[no stdout — timed out]"
+              : stderrBuf.length > 0
+                ? `[no stdout — tail of stderr]\n${tail(stderrBuf, opts.digest_chars)}`
+                : "[no output]";
 
       const result: ExecSandboxResult = {
         id,
@@ -313,6 +331,7 @@ export function runExecSandbox(
         exit_code: exitCode,
         signal,
         timed_out: timedOut,
+        aborted,
         force_resolved: forceResolved,
         duration_ms: duration,
         stdout_bytes: stdoutBytes,
@@ -328,6 +347,26 @@ export function runExecSandbox(
       resolveP(result);
     };
 
+    timer = setTimeout(() => {
+      timedOut = true;
+      initiateKill();
+    }, timeoutMs);
+    timer.unref?.();
+
+    if (opts.signal) {
+      abortListener = () => {
+        if (settled || timedOut) return;
+        aborted = true;
+        clearTimeout(timer);
+        initiateKill();
+      };
+      if (opts.signal.aborted) {
+        abortListener();
+      } else {
+        opts.signal.addEventListener("abort", abortListener, { once: true });
+      }
+    }
+
     child.on("error", (err) => {
       const message = err instanceof Error ? err.message : String(err);
       const line = `child error: ${message}\n`;
@@ -364,6 +403,7 @@ function writeMeta(
     exit_code: result.exit_code,
     signal: result.signal,
     timed_out: result.timed_out,
+    aborted: result.aborted === true,
     force_resolved: result.force_resolved,
     duration_ms: result.duration_ms,
     stdout_bytes: result.stdout_bytes,

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

@@ -28,8 +28,7 @@ import { deriveState } from "./state.js";
 import { isAutoActive } from "./auto.js";
 import { loadPrompt } from "./prompt-loader.js";
 import { gsdRoot } from "./paths.js";
-import { isDbAvailable, getAllMilestones, getMilestoneSlices, getSliceTasks } from "./gsd-db.js";
-import { isClosedStatus } from "./status-guards.js";
+import { isDbAvailable, getHierarchyCompletionCounts } from "./gsd-db.js";
 import { formatDuration } from "../shared/format-utils.js";
 import { getAutoWorktreePath } from "./auto-worktree.js";
 import { clearGSDPreferencesCache, loadEffectiveGSDPreferences, loadGlobalGSDPreferences, getGlobalGSDPreferencesPath } from "./preferences.js";
@@ -759,37 +758,7 @@ function loadCompletedKeys(basePath: string): string[] {
 function getDbCompletionCounts(): DbCompletionCounts | null {
   if (!isDbAvailable()) return null;
 
-  const milestones = getAllMilestones();
-  let completedMilestones = 0;
-  let totalSlices = 0;
-  let completedSlices = 0;
-  let totalTasks = 0;
-  let completedTasks = 0;
-
-  for (const m of milestones) {
-    if (isClosedStatus(m.status)) completedMilestones++;
-
-    const slices = getMilestoneSlices(m.id);
-    for (const s of slices) {
-      totalSlices++;
-      if (isClosedStatus(s.status)) completedSlices++;
-
-      const tasks = getSliceTasks(m.id, s.id);
-      for (const t of tasks) {
-        totalTasks++;
-        if (isClosedStatus(t.status)) completedTasks++;
-      }
-    }
-  }
-
-  return {
-    milestones: completedMilestones,
-    milestonesTotal: milestones.length,
-    slices: completedSlices,
-    slicesTotal: totalSlices,
-    tasks: completedTasks,
-    tasksTotal: totalTasks,
-  };
+  return getHierarchyCompletionCounts();
 }
 
 // ─── Anomaly Detectors ───────────────────────────────────────────────────────

package/src/resources/extensions/gsd/git-service.ts

@@ -378,6 +378,8 @@ export const RUNTIME_EXCLUSION_PATHS: readonly string[] = [
   ".gsd/DISCUSSION-MANIFEST.json",
 ];
 
+const runtimeFilesCleanedUpRepos = new Set<string>();
+
 // ─── Integration Branch Metadata ───────────────────────────────────────────
 
 /**
@@ -755,7 +757,8 @@ export class GitServiceImpl {
     // and the worktree is torn down. This prevents a mid-execution behavioral
     // discontinuity where the first half of a milestone has .gsd/ artifacts
     // committed but the second half doesn't (#1326).
-    if (!this._runtimeFilesCleanedUp) {
+    const cleanupRepoKey = resolve(this.basePath);
+    if (!runtimeFilesCleanedUpRepos.has(cleanupRepoKey)) {
       let cleaned = false;
       for (const exclusion of RUNTIME_EXCLUSION_PATHS) {
         const removed = nativeRmCached(this.basePath, [exclusion]);
@@ -764,7 +767,7 @@ export class GitServiceImpl {
       if (cleaned) {
         nativeCommit(this.basePath, "chore: untrack .gsd/ runtime files from git index", { allowEmpty: false });
       }
-      this._runtimeFilesCleanedUp = true;
+      runtimeFilesCleanedUpRepos.add(cleanupRepoKey);
     }
 
     // Stage everything using pathspec exclusions so excluded paths are never
@@ -893,9 +896,6 @@ export class GitServiceImpl {
     }
   }
 
-  /** Tracks whether runtime file cleanup has run this session. */
-  private _runtimeFilesCleanedUp = false;
-
   /**
    * Stage files (smart staging) and commit.
    * Returns the commit message string on success, or null if nothing to commit.

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

@@ -20,6 +20,7 @@ import { invalidateAllCaches } from "./cache.js";
 import {
   gsdRoot, resolveMilestoneFile, resolveSliceFile,
   resolveGsdRootFile, relGsdRootFile, relSliceFile,
+  relMilestoneFile,
 } from "./paths.js";
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { atomicWriteSync } from "./atomic-write.js";
@@ -29,6 +30,10 @@ import { loadQueueOrder, sortByQueueOrder, saveQueueOrder } from "./queue-order.
 import { findMilestoneIds, nextMilestoneId } from "./milestone-ids.js";
 import { isFutureMilestoneStatus } from "./status-guards.js";
 
+const QUEUE_ARTIFACT_EXCERPT_MAX_CHARS = 20_000;
+const QUEUE_EXISTING_MILESTONES_CONTEXT_MAX_CHARS = 120_000;
+const QUEUE_CONTEXT_SECTION_SEPARATOR = "\n\n---\n\n";
+
 // ─── Queue Entry Point ──────────────────────────────────────────────────────
 
 /**
@@ -280,7 +285,9 @@ export async function buildExistingMilestonesContext(
     if (contextFile) {
       const content = await loadFile(contextFile);
       if (content) {
-        parts.push(`\n**Context:**\n${content.trim()}`);
+        parts.push(
+          `\n**Context:**\n${summarizeArtifactForQueue(content, relMilestoneFile(basePath, mid, "CONTEXT"))}`,
+        );
       }
     } else {
       // No full CONTEXT.md — check for CONTEXT-DRAFT.md (draft seed from prior discussion)
@@ -288,7 +295,9 @@ export async function buildExistingMilestonesContext(
       if (draftFile) {
         const draftContent = await loadFile(draftFile);
         if (draftContent) {
-          parts.push(`\n**Draft context available:**\n${draftContent.trim()}`);
+          parts.push(
+            `\n**Draft context available:**\n${summarizeArtifactForQueue(draftContent, relMilestoneFile(basePath, mid, "CONTEXT-DRAFT"))}`,
+          );
         }
       }
     }
@@ -300,7 +309,9 @@ export async function buildExistingMilestonesContext(
       if (roadmapFile) {
         const content = await loadFile(roadmapFile);
         if (content) {
-          parts.push(`\n**Roadmap:**\n${content.trim()}`);
+          parts.push(
+            `\n**Roadmap:**\n${summarizeArtifactForQueue(content, relMilestoneFile(basePath, mid, "ROADMAP"))}`,
+          );
         }
       }
     }
@@ -317,7 +328,81 @@ export async function buildExistingMilestonesContext(
     }
   }
 
-  return sections.join("\n\n---\n\n");
+  return capExistingMilestonesContext(sections);
+}
+
+function summarizeArtifactForQueue(
+  content: string,
+  sourcePath: string,
+  cap = QUEUE_ARTIFACT_EXCERPT_MAX_CHARS,
+): string {
+  const trimmed = content.trim();
+  if (trimmed.length <= cap) {
+    return `Source: \`${sourcePath}\`\n\n${trimmed}`;
+  }
+
+  const excerpt = trimmed.slice(0, cap).trimEnd();
+  const omittedChars = trimmed.length - excerpt.length;
+  return [
+    `Source: \`${sourcePath}\``,
+    "",
+    excerpt,
+    "",
+    `[Truncated ${omittedChars} chars. Read \`${sourcePath}\` for full content.]`,
+  ].join("\n");
+}
+
+function capExistingMilestonesContext(
+  sections: string[],
+  cap = QUEUE_EXISTING_MILESTONES_CONTEXT_MAX_CHARS,
+): string {
+  const fullContext = sections.join(QUEUE_CONTEXT_SECTION_SEPARATOR);
+  if (fullContext.length <= cap) return fullContext;
+
+  const notice = `[Existing milestones context truncated to ${cap} chars. Read source paths in this prompt or the corresponding .gsd artifacts for full details.]`;
+  const noticeSuffix = `${QUEUE_CONTEXT_SECTION_SEPARATOR}${notice}`;
+
+  const selected: string[] = [];
+  for (const section of sections) {
+    const candidate = [...selected, section].join(QUEUE_CONTEXT_SECTION_SEPARATOR) + noticeSuffix;
+    if (candidate.length <= cap) {
+      selected.push(section);
+      continue;
+    }
+    break;
+  }
+
+  if (selected.length === sections.length) {
+    return selected.join(QUEUE_CONTEXT_SECTION_SEPARATOR) + noticeSuffix;
+  }
+
+  const compactTail = sections.slice(selected.length).map(compactSectionForQueueBudget);
+  const hybrid = [...selected, ...compactTail].join(QUEUE_CONTEXT_SECTION_SEPARATOR) + noticeSuffix;
+  if (hybrid.length <= cap) return hybrid;
+
+  const compact = sections.map(compactSectionForQueueBudget);
+  const compactContext = compact.join(QUEUE_CONTEXT_SECTION_SEPARATOR) + noticeSuffix;
+  if (compactContext.length <= cap) return compactContext;
+
+  return `${compactContext.slice(0, Math.max(0, cap - notice.length - 2)).trimEnd()}\n\n${notice}`;
+}
+
+function compactSectionForQueueBudget(section: string): string {
+  const lines = section.split("\n");
+  const compact: string[] = [];
+
+  if (lines[0]) compact.push(lines[0]);
+
+  const statusLine = lines.find(line => line.startsWith("**Status:**"));
+  if (statusLine) compact.push(statusLine);
+
+  const sourceLines = lines.filter(line => line.startsWith("Source: `"));
+  if (sourceLines.length > 0) {
+    compact.push("", "**Sources:**", ...sourceLines);
+    compact.push("", "[Artifact excerpts omitted due to total queue/rethink context budget.]");
+  }
+
+  return compact.join("\n");
 }
 
 // ─── Internal Helpers ───────────────────────────────────────────────────────

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

@@ -2,11 +2,12 @@
 // File Purpose: Always-on ambient health signal rendered below the editor.
 
 import type { ExtensionContext } from "@gsd/pi-coding-agent";
+import { execFile } from "node:child_process";
 import type { GSDState } from "./types.js";
-import { runProviderChecks, summariseProviderIssues } from "./doctor-providers.js";
+import { runProviderChecks, runProviderChecksAsync, summariseProviderIssues } from "./doctor-providers.js";
 import { runEnvironmentChecks, runEnvironmentChecksAsync } from "./doctor-environment.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
-import { nativeIsRepo, nativeLastCommitEpoch, nativeGetCurrentBranch, nativeCommitSubject } from "./native-git-bridge.js";
+import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
 import { loadLedgerFromDisk, getProjectTotals } from "./metrics.js";
 import { describeNextUnit, estimateTimeRemaining, updateSliceProgressCache } from "./auto-dashboard.js";
 import { projectRoot } from "./commands/context.js";
@@ -15,32 +16,75 @@ import {
   buildHealthLines,
   detectHealthWidgetProjectState,
   type HealthWidgetData,
+  type HealthWidgetProjectState,
 } from "./health-widget-core.js";
 
 export const HEALTH_WIDGET_ACTIVE_HINTS =
   "  /gsd auto to run  ·  /gsd status to inspect  ·  /gsd report for snapshots  ·  /gsd notifications for history  ·  /gsd help";
 
+const LAST_COMMIT_LOOKUP_TIMEOUT_MS = 3_000;
+const REFRESH_INTERVAL_MS = 60_000;
+const PROJECT_STATE_CACHE_TTL_MS = REFRESH_INTERVAL_MS;
+
 // ── Data loader ────────────────────────────────────────────────────────────────
 
-// Last-commit lookup is subprocess-backed (native-git-bridge → git spawns),
-// so it is treated like the other expensive checks: skipped on first paint,
-// run only by the background refresh.
-function loadLastCommitInfo(basePath: string): { epoch: number | null; message: string | null } {
+const projectStateCache = new Map<string, { state: HealthWidgetProjectState; computedAt: number }>();
+
+export function getCachedProjectState(basePath: string, force?: boolean): HealthWidgetProjectState {
+  const now = Date.now();
+  const cached = projectStateCache.get(basePath);
+  if (!force && cached && now - cached.computedAt <= PROJECT_STATE_CACHE_TTL_MS) {
+    return cached.state;
+  }
+
+  const state = detectHealthWidgetProjectState(basePath);
+  projectStateCache.set(basePath, { state, computedAt: now });
+  return state;
+}
+
+function runHealthWidgetGit(basePath: string, args: string[]): Promise<string | null> {
+  return new Promise((resolve) => {
+    const child = execFile(
+      "git",
+      args,
+      {
+        cwd: basePath,
+        timeout: LAST_COMMIT_LOOKUP_TIMEOUT_MS,
+        encoding: "utf-8",
+        env: GIT_NO_PROMPT_ENV,
+      },
+      (err, stdout) => resolve(err ? null : String(stdout).trimEnd()),
+    );
+    child.on("error", () => resolve(null));
+  });
+}
+
+async function loadLastCommitInfoAsync(basePath: string): Promise<{ epoch: number | null; message: string | null }> {
   try {
-    if (nativeIsRepo(basePath)) {
-      const branch = nativeGetCurrentBranch(basePath);
-      const epoch = nativeLastCommitEpoch(basePath, branch || "HEAD");
-      if (epoch > 0) {
-        return { epoch, message: nativeCommitSubject(basePath, branch || "HEAD") || null };
-      }
+    if ((await runHealthWidgetGit(basePath, ["rev-parse", "--git-dir"])) === null) {
+      return { epoch: null, message: null };
     }
-  } catch { /* non-fatal */ }
-  return { epoch: null, message: null };
+
+    const branch = await runHealthWidgetGit(basePath, ["branch", "--show-current"]);
+    const ref = branch || "HEAD";
+    const raw = await runHealthWidgetGit(basePath, ["log", "-1", "--format=%ct%x00%s", ref]);
+    if (!raw) return { epoch: null, message: null };
+
+    const separator = raw.indexOf("\0");
+    const epochText = separator >= 0 ? raw.slice(0, separator) : raw;
+    const epoch = parseInt(epochText.trim(), 10) || 0;
+    if (epoch <= 0) return { epoch: null, message: null };
+
+    const message = separator >= 0 ? raw.slice(separator + 1).trim() : "";
+    return { epoch, message: message || null };
+  } catch {
+    return { epoch: null, message: null };
+  }
 }
 
 function loadHealthWidgetData(
   basePath: string,
-  options?: { includeChecks?: boolean },
+  options?: { includeChecks?: boolean; forceProjectState?: boolean },
 ): HealthWidgetData {
   // `includeChecks` gates the expensive subprocess-backed checks (provider +
   // environment doctor: `lsof`, `docker`, `node --version`, ...). The initial
@@ -55,7 +99,7 @@ function loadHealthWidgetData(
   let lastCommitEpoch: number | null = null;
   let lastCommitMessage: string | null = null;
 
-  const projectState = detectHealthWidgetProjectState(basePath);
+  const projectState = getCachedProjectState(basePath, options?.forceProjectState);
 
   try {
     const prefs = loadEffectiveGSDPreferences();
@@ -83,13 +127,6 @@ function loadHealthWidgetData(
     } catch { /* non-fatal */ }
   }
 
-  // ── Last commit info ── (git spawns — gated like the other expensive checks)
-  if (includeChecks) {
-    const commit = loadLastCommitInfo(basePath);
-    lastCommitEpoch = commit.epoch;
-    lastCommitMessage = commit.message;
-  }
-
   return {
     projectState,
     budgetCeiling,
@@ -104,10 +141,8 @@ function loadHealthWidgetData(
 }
 
 // Non-blocking variant used by the widget's background refresh: the cheap fields
-// come from the synchronous snapshot, then provider + environment checks are
-// layered in off the event-loop critical path (env checks run concurrently via
-// runEnvironmentChecksAsync). Keeps the always-on widget from stalling the UI on
-// its initial enrichment or its 60s refresh.
+// come from the synchronous snapshot, then provider, environment, and last-commit
+// checks are layered in off the event-loop critical path.
 async function loadHealthWidgetDataAsync(basePath: string): Promise<HealthWidgetData> {
   const data = loadHealthWidgetData(basePath, { includeChecks: false });
   let providerIssue = data.providerIssue;
@@ -115,7 +150,7 @@ async function loadHealthWidgetDataAsync(basePath: string): Promise<HealthWidget
   let environmentWarningCount = 0;
 
   try {
-    providerIssue = summariseProviderIssues(runProviderChecks());
+    providerIssue = summariseProviderIssues(await runProviderChecksAsync());
   } catch { /* non-fatal */ }
 
   try {
@@ -126,7 +161,7 @@ async function loadHealthWidgetDataAsync(basePath: string): Promise<HealthWidget
     }
   } catch { /* non-fatal */ }
 
-  const commit = loadLastCommitInfo(basePath);
+  const commit = await loadLastCommitInfoAsync(basePath);
 
   return {
     ...data,
@@ -141,8 +176,6 @@ async function loadHealthWidgetDataAsync(basePath: string): Promise<HealthWidget
 
 // ── Widget init ────────────────────────────────────────────────────────────────
 
-const REFRESH_INTERVAL_MS = 60_000;
-
 /**
  * Initialize the always-on gsd-health widget (belowEditor).
  * Call once from the extension entry point after context is available.
@@ -152,13 +185,17 @@ export function initHealthWidget(ctx: ExtensionContext): void {
 
   const basePath = projectRoot();
 
+  // Re-init must reflect filesystem changes immediately; the TTL cache is for
+  // interval refreshes, not this one-off synchronous paint.
+  projectStateCache.delete(basePath);
+
   // String-array fallback — used in RPC mode (factory is a no-op there).
   // Skip the expensive provider/environment doctor checks here: this runs
   // synchronously on the interactive-startup path, where running them would
   // block first paint by ~0.9s (lsof/docker probes, otherwise run again
   // immediately by the factory below). The factory's async refresh fills in
   // real health once the screen is up.
-  const initialData = loadHealthWidgetData(basePath, { includeChecks: false });
+  const initialData = loadHealthWidgetData(basePath, { includeChecks: false, forceProjectState: true });
   ctx.ui.setWidget("gsd-health", buildHealthLines(initialData), { placement: "belowEditor" });
 
   // Factory-based widget for TUI mode — replaces the string-array above

package/src/resources/extensions/gsd/layout-policy.ts

@@ -47,8 +47,9 @@ export function dbPath(basePath: string): string {
  * Used by the renderer to derive the phase number from the DB's milestone_id.
  */
 export function milestoneIdToPhaseNum(milestoneId: string): number {
-  // No $ anchor: accepts bare (M012) and team-suffixed (M012-abc123) IDs.
+  // No $ anchor: accepts bare (M012), team-suffixed (M012-abc123), and legacy numeric IDs.
   const m = milestoneId.match(/^M0*(\d+)/i);
+  if (!m && /^\d+$/.test(milestoneId)) return Number.parseInt(milestoneId, 10);
   return m ? Number.parseInt(m[1]!, 10) : 1;
 }
 

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

@@ -25,6 +25,7 @@ import {
   insertArtifact,
   deleteArtifactByPath,
   getGateResults,
+  isDbAvailable,
 } from "./gsd-db.js";
 import type { MilestoneRow, ArtifactRow } from "./db-milestone-artifact-rows.js";
 import type { SliceRow, TaskRow } from "./db-task-slice-rows.js";
@@ -631,16 +632,8 @@ export async function renderRoadmapCheckboxes(
   basePath: string,
   milestoneId: string,
 ): Promise<boolean> {
-  const slices = getMilestoneSlices(milestoneId);
-  if (slices.length === 0) {
-    process.stderr.write(
-      `markdown-renderer: no slices found for milestone ${milestoneId}\n`,
-    );
-    return false;
-  }
-
-  await renderRoadmapFromDb(basePath, milestoneId);
-  return true;
+  const rendered = await renderRoadmapFromDb(basePath, milestoneId);
+  return !("skipped" in rendered);
 }
 
 /**
@@ -737,7 +730,8 @@ function isAutoRecoveryPlaceholderPlan(content: string): boolean {
  * projection (the 4S/0T-vs-5S/13T drift class). The artifacts table is an
  * output sink, never a render input.
  *
- * @returns true if the plan was written, false on skip/error
+ * @returns true if the plan was written, false when the DB slice has no tasks
+ * @throws when the DB connection is unavailable or the render write fails
  */
 export async function renderPlanCheckboxes(
   basePath: string,
@@ -747,6 +741,9 @@ export async function renderPlanCheckboxes(
 ): Promise<boolean> {
   const tasks = getSliceTasks(milestoneId, sliceId);
   if (tasks.length === 0) {
+    if (!isDbAvailable()) {
+      throw new Error(`database unavailable while rendering plan checkboxes for ${milestoneId}/${sliceId}`);
+    }
     process.stderr.write(
       `markdown-renderer: no tasks found for ${milestoneId}/${sliceId}\n`,
     );