gsd-pi 2.76.0 → 2.77.0-dev.1594b263e

package/dist/resources/extensions/gsd/bootstrap/register-extension.js

@@ -4,6 +4,7 @@ import { registerWorktreeCommand } from "../worktree-command.js";
 import { loadEcosystemExtensions } from "../ecosystem/loader.js";
 import { registerDbTools } from "./db-tools.js";
 import { registerDynamicTools } from "./dynamic-tools.js";
+import { registerExecTools } from "./exec-tools.js";
 import { registerJournalTools } from "./journal-tools.js";
 import { registerMemoryTools } from "./memory-tools.js";
 import { registerQueryTools } from "./query-tools.js";
@@ -11,6 +12,13 @@ import { registerHooks } from "./register-hooks.js";
 import { registerShortcuts } from "./register-shortcuts.js";
 import { writeCrashLog } from "./crash-log.js";
 import { logWarning } from "../workflow-logger.js";
+// Static import so cmux event listeners are registered synchronously during
+// extension bootstrap. Prior implementation used `void import().then()` which
+// queued listener registration as a microtask — any CMUX_CHANNELS emit fired
+// in the same event loop turn as registration (e.g. from a provider-error
+// session hook calling startAuto) would be silently dropped because Node's
+// EventEmitter does not buffer events for late subscribers.
+import { initCmuxEventListeners } from "../../cmux/index.js";
 export { writeCrashLog } from "./crash-log.js";
 export function handleRecoverableExtensionProcessError(err) {
     if (err.code === "EPIPE") {
@@ -58,6 +66,16 @@ export function registerGsdExtension(pi) {
     // so we intentionally skip it here to avoid double-registration.
     registerWorktreeCommand(pi);
     registerExitCommand(pi);
+    // Wire the Layer 2 event emitter bridge so deeply-nested GSD code can emit
+    // extension events (git lifecycle, verify, budget, milestone, unit) without
+    // threading `pi` through every call site.
+    import("../hook-emitter.js")
+        .then(({ setHookEmitter }) => setHookEmitter(pi))
+        .catch((err) => {
+        // Non-fatal — emitters simply become no-ops if this import fails, but
+        // surface the failure so silent bootstrap breakage is debuggable.
+        process.stderr.write(`[gsd] Failed to bootstrap hook-emitter bridge: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+    });
     installEpipeGuard();
     // Ecosystem handlers captured by the GSDExtensionAPI wrapper for the
     // GSD-owned `before_agent_start` dispatch step (#3338).
@@ -76,7 +94,12 @@ export function registerGsdExtension(pi) {
         ["journal-tools", () => registerJournalTools(pi)],
         ["query-tools", () => registerQueryTools(pi)],
         ["memory-tools", () => registerMemoryTools(pi)],
+        ["exec-tools", () => registerExecTools(pi)],
         ["shortcuts", () => registerShortcuts(pi)],
+        // cmux is a library (no pi), so gsd sets up the event listeners on its
+        // behalf using the shared event channel contract. Registration is
+        // synchronous — see the import comment above for the rationale.
+        ["cmux-events", () => initCmuxEventListeners(pi.events)],
         ["hooks", () => registerHooks(pi, ecosystemHandlers)],
         ["ecosystem", () => {
                 void loadEcosystemExtensions(pi, ecosystemHandlers).catch((err) => {

package/dist/resources/extensions/gsd/bootstrap/register-hooks.js

@@ -13,12 +13,12 @@ import { loadToolApiKeys } from "../commands-config.js";
 import { loadFile, saveFile, formatContinue } from "../files.js";
 import { deriveState } from "../state.js";
 import { getAutoDashboardData, isAutoActive, isAutoPaused, markToolEnd, markToolStart, recordToolInvocationError } from "../auto.js";
-import { hideFooter } from "../auto-dashboard.js";
 import { isParallelActive, shutdownParallel } from "../parallel-orchestrator.js";
 import { checkToolCallLoop, resetToolCallLoopGuard } from "./tool-call-loop-guard.js";
 import { saveActivityLog } from "../activity-log.js";
 import { resetAskUserQuestionsCache } from "../../ask-user-questions.js";
-import { recordToolCall as safetyRecordToolCall, recordToolResult as safetyRecordToolResult } from "../safety/evidence-collector.js";
+import { recordToolCall as safetyRecordToolCall, recordToolResult as safetyRecordToolResult, saveEvidenceToDisk } from "../safety/evidence-collector.js";
+import { parseUnitId } from "../unit-id.js";
 import { classifyCommand } from "../safety/destructive-guard.js";
 import { logWarning as safetyLogWarning } from "../workflow-logger.js";
 import { installNotifyInterceptor } from "./notify-interceptor.js";
@@ -37,7 +37,9 @@ export function registerHooks(pi, ecosystemHandlers) {
         initNotificationStore(process.cwd());
         installNotifyInterceptor(ctx);
         initNotificationWidget(ctx);
-        initHealthWidget(ctx);
+        if (!isAutoActive()) {
+            initHealthWidget(ctx);
+        }
         resetWriteGateState();
         resetToolCallLoopGuard();
         resetAskUserQuestionsCache();
@@ -79,7 +81,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         }
         loadToolApiKeys();
         if (isAutoActive()) {
-            ctx.ui.setFooter(hideFooter);
+            ctx.ui.setWidget("gsd-health", undefined);
         }
     });
     pi.on("session_switch", async (_event, ctx) => {
@@ -101,7 +103,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         }
         loadToolApiKeys();
         if (isAutoActive()) {
-            ctx.ui.setFooter(hideFooter);
+            ctx.ui.setWidget("gsd-health", undefined);
         }
     });
     pi.on("before_agent_start", async (event, ctx) => {
@@ -204,6 +206,41 @@ export function registerHooks(pi, ecosystemHandlers) {
             nextAction: `Resume task ${state.activeTask.id}: ${state.activeTask.title}.`,
         }));
     });
+    // Context-mode snapshot: write .gsd/last-snapshot.md before compaction so
+    // agents can call gsd_resume (or Read the file) to re-orient. Opt-in via
+    // preferences.context_mode.enabled. Runs after the auto-cancel handler
+    // above — if that one returned cancel:true, pi still fires us but the
+    // compaction won't actually happen; the snapshot is still useful then,
+    // since auto may pause and resume later.
+    pi.on("session_before_compact", async () => {
+        try {
+            const { loadEffectiveGSDPreferences } = await import("../preferences.js");
+            const { isContextModeEnabled } = await import("../preferences-types.js");
+            const prefs = loadEffectiveGSDPreferences();
+            if (!isContextModeEnabled(prefs?.preferences))
+                return;
+            const { writeCompactionSnapshot } = await import("../compaction-snapshot.js");
+            const { ensureDbOpen } = await import("./dynamic-tools.js");
+            await ensureDbOpen();
+            const basePath = process.cwd();
+            let activeContext = null;
+            try {
+                const state = await deriveState(basePath);
+                if (state.activeMilestone && state.activeSlice && state.activeTask) {
+                    activeContext =
+                        `Active: ${state.activeMilestone.id} / ${state.activeSlice.id} / ${state.activeTask.id}` +
+                            (state.activeTask.title ? ` — ${state.activeTask.title}` : "");
+                }
+            }
+            catch {
+                /* non-fatal */
+            }
+            writeCompactionSnapshot(basePath, { activeContext });
+        }
+        catch (err) {
+            safetyLogWarning("context-mode", `failed to write compaction snapshot: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
     pi.on("session_shutdown", async (_event, ctx) => {
         if (isParallelActive()) {
             try {
@@ -316,7 +353,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         if (isAutoActive() && typeof event.toolCallId === "string") {
             markToolEnd(event.toolCallId);
         }
-        if (isAutoActive() && event.isError && event.toolName.startsWith("gsd_")) {
+        if (isAutoActive() && event.isError) {
             const resultPayload = ("result" in event ? event.result : undefined);
             const errorText = typeof resultPayload === "string"
                 ? resultPayload
@@ -325,6 +362,8 @@ export function registerHooks(pi, ecosystemHandlers) {
                     : (typeof event.content === "string"
                         ? event.content
                         : String(resultPayload ?? "")));
+            // Let recordToolInvocationError classify the failure so non-gsd_ harness
+            // errors and deterministic policy rejections are handled consistently.
             recordToolInvocationError(event.toolName, errorText);
         }
         if (event.toolName !== "ask_user_questions")
@@ -406,21 +445,32 @@ export function registerHooks(pi, ecosystemHandlers) {
     pi.on("tool_execution_start", async (event) => {
         if (!isAutoActive())
             return;
-        markToolStart(event.toolCallId);
+        markToolStart(event.toolCallId, event.toolName);
     });
     pi.on("tool_execution_end", async (event) => {
         markToolEnd(event.toolCallId);
-        // #2883: Capture tool invocation errors (malformed/truncated JSON arguments)
+        // #2883/#4974: Capture deterministic invocation/policy errors
         // so postUnitPreVerification can break the retry loop instead of re-dispatching.
-        if (event.isError && event.toolName.startsWith("gsd_")) {
+        if (event.isError) {
             const errorText = typeof event.result === "string"
                 ? event.result
                 : (typeof event.result?.content?.[0]?.text === "string" ? event.result.content[0].text : String(event.result));
+            // Let recordToolInvocationError classify the failure so non-gsd_ harness
+            // errors and deterministic policy rejections are handled consistently.
             recordToolInvocationError(event.toolName, errorText);
         }
         // Safety harness: record tool execution results for evidence cross-referencing
         if (isAutoActive()) {
             safetyRecordToolResult(event.toolCallId, event.toolName, event.result, event.isError);
+            // Persist evidence to disk after each tool result so it survives a session
+            // restart mid-unit (Bug #4385 — non-persisted evidence false positives).
+            const dash = getAutoDashboardData();
+            if (dash.basePath && dash.currentUnit?.type === "execute-task") {
+                const { milestone: pMid, slice: pSid, task: pTid } = parseUnitId(dash.currentUnit.id);
+                if (pMid && pSid && pTid) {
+                    saveEvidenceToDisk(dash.basePath, pMid, pSid, pTid);
+                }
+            }
         }
     });
     pi.on("model_select", async (_event, ctx) => {

package/dist/resources/extensions/gsd/bootstrap/system-context.js

@@ -16,7 +16,6 @@ import { getActiveWorktreeName, getWorktreeOriginalCwd } from "../worktree-comma
 import { deriveState } from "../state.js";
 import { formatOverridesSection, formatShortcut, loadActiveOverrides, loadFile, parseContinue, parseSummary } from "../files.js";
 import { toPosixPath } from "../../shared/mod.js";
-import { markCmuxPromptShown, shouldPromptToEnableCmux } from "../../cmux/index.js";
 import { autoEnableCmuxPreferences } from "../commands-cmux.js";
 const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
 /**
@@ -24,10 +23,30 @@ const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
  * hardcoding absolute paths in the system prompt template. Only skills
  * that actually exist on disk are included in the table. (#3575)
  */
-const BUNDLED_SKILL_TRIGGERS = [
+export const BUNDLED_SKILL_TRIGGERS = [
     { trigger: "Frontend UI - web components, pages, landing pages, dashboards, React/HTML/CSS, styling", skill: "frontend-design" },
     { trigger: "macOS or iOS apps - SwiftUI, Xcode, App Store", skill: "swiftui" },
     { trigger: "Debugging - complex bugs, failing tests, root-cause investigation after standard approaches fail", skill: "debug-like-expert" },
+    { trigger: "Code review - security, performance, bugs, quality review of staged/unstaged diffs or PRs", skill: "review" },
+    { trigger: "Test generation or execution - auto-detect framework, generate tests, run suite, analyze failures", skill: "test" },
+    { trigger: "Linting/formatting - run the detected linter/formatter with auto-fix, report remaining issues", skill: "lint" },
+    { trigger: "Polishing UI details - animations, hover states, typography, borders, micro-interactions, optical alignment", skill: "make-interfaces-feel-better" },
+    { trigger: "Accessibility audit - WCAG, screen reader, keyboard navigation, a11y review", skill: "accessibility" },
+    { trigger: "Planning interviews - stress-test a plan, grill the user, resolve decision trees one branch at a time", skill: "grill-me" },
+    { trigger: "Interface design - produce 3+ radically different designs for a module/API, compare in prose, synthesize", skill: "design-an-interface" },
+    { trigger: "TDD - red-green-refactor vertical slices, never refactor while red, tests survive refactors", skill: "tdd" },
+    { trigger: "Draft a milestone brief (M###-CONTEXT.md) or PRD from current conversation context", skill: "write-milestone-brief" },
+    { trigger: "Break a plan into vertical-slice roadmap slices (M###-ROADMAP.md) or GitHub issues with dependency ordering", skill: "decompose-into-slices" },
+    { trigger: "Package spike findings into a reusable project-local skill at .claude/skills/", skill: "spike-wrap-up" },
+    { trigger: "Block completion claims until verification evidence has been produced in this message", skill: "verify-before-complete" },
+    { trigger: "Create a Model Context Protocol (MCP) server — tool design, error handling, Inspector testing, evals", skill: "create-mcp-server" },
+    { trigger: "Write documentation, proposals, specs, RFCs, or READMEs for a fresh reader", skill: "write-docs" },
+    { trigger: "Post-mortem a failed GSD auto-mode run using .gsd/activity, .gsd/journal, and .gsd/metrics.json", skill: "forensics" },
+    { trigger: "Prepare a clean cross-session handoff — continue.md + summary updates (pause/resume work)", skill: "handoff" },
+    { trigger: "Security review with STRIDE threat modeling and exploit-scenario reporting", skill: "security-review" },
+    { trigger: "HTTP/REST/GraphQL API design — verbs, status codes, pagination, errors, idempotency, versioning", skill: "api-design" },
+    { trigger: "Dependency upgrades — risk-batched, verified between batches, one major per commit", skill: "dependency-upgrade" },
+    { trigger: "Agent-first observability — structured logs, persisted failure state, health surfaces, explicit failure modes", skill: "observability" },
 ];
 function buildBundledSkillsTable() {
     const cwd = process.cwd();
@@ -67,13 +86,19 @@ export async function buildBeforeAgentStartResult(event, ctx) {
         shortcutShell: formatShortcut("Ctrl+Alt+B"),
     });
     let loadedPreferences = loadEffectiveGSDPreferences();
-    if (shouldPromptToEnableCmux(loadedPreferences?.preferences)) {
-        markCmuxPromptShown();
-        if (autoEnableCmuxPreferences()) {
-            loadedPreferences = loadEffectiveGSDPreferences();
-            ctx.ui.notify("cmux detected — auto-enabled. Run /gsd cmux off to disable.", "info");
+    try {
+        const { markCmuxPromptShown, shouldPromptToEnableCmux } = await import("../../cmux/index.js");
+        if (shouldPromptToEnableCmux(loadedPreferences?.preferences)) {
+            markCmuxPromptShown();
+            if (autoEnableCmuxPreferences()) {
+                loadedPreferences = loadEffectiveGSDPreferences();
+                ctx.ui.notify("cmux detected — auto-enabled. Run /gsd cmux off to disable.", "info");
+            }
         }
     }
+    catch (e) {
+        logWarning("bootstrap", `cmux prompt setup skipped: ${e.message}`);
+    }
     let preferenceBlock = "";
     if (loadedPreferences) {
         const cwd = process.cwd();
@@ -87,33 +112,20 @@ export async function buildBeforeAgentStartResult(event, ctx) {
     if (globalSizeKb > 4) {
         ctx.ui.notify(`GSD: ~/.gsd/agent/KNOWLEDGE.md is ${globalSizeKb.toFixed(1)}KB — consider trimming to keep system prompt lean.`, "warning");
     }
-    let memoryBlock = "";
+    // ADR-013 step 5: opportunistic decisions->memories backfill. Idempotent
+    // and best-effort — first run absorbs the existing decisions table into
+    // the memory store; subsequent runs are a single sentinel SELECT.
     try {
-        const { formatMemoriesForPrompt, getActiveMemoriesRanked, queryMemoriesRanked } = await import("../memory-store.js");
-        // Always-on "critical" set — small, stable memories that belong in every
-        // turn (gotchas, environment, conventions). Ranked by the existing score.
-        const CRITICAL_CATEGORIES = new Set(["gotcha", "environment", "convention"]);
-        const allRanked = getActiveMemoriesRanked(60);
-        const critical = allRanked.filter((m) => CRITICAL_CATEGORIES.has(m.category)).slice(0, 5);
-        const criticalIds = new Set(critical.map((m) => m.id));
-        // Prompt-relevance set — hybrid FTS5 + (future) semantic retrieval.
-        let relevant = [];
-        const userPrompt = (event.prompt ?? "").trim();
-        if (userPrompt) {
-            const hits = queryMemoriesRanked({ query: userPrompt, k: 10 });
-            relevant = hits.map((h) => h.memory).filter((m) => !criticalIds.has(m.id));
-        }
-        const merged = [...critical, ...relevant];
-        if (merged.length > 0) {
-            const formatted = formatMemoriesForPrompt(merged, 2000);
-            if (formatted) {
-                memoryBlock = `\n\n${formatted}`;
-            }
+        const { backfillDecisionsToMemories } = await import("../memory-backfill.js");
+        const written = backfillDecisionsToMemories();
+        if (written > 0) {
+            ctx.ui.notify(`GSD: backfilled ${written} decision${written === 1 ? "" : "s"} into the memory store (ADR-013).`, "info");
         }
     }
     catch (e) {
-        logWarning("bootstrap", `memory block fetch failed: ${e.message}`);
+        logWarning("bootstrap", `decisions backfill failed: ${e.message}`);
     }
+    const memoryBlock = await loadMemoryBlock(event.prompt ?? "");
     let newSkillsBlock = "";
     if (hasSkillSnapshot()) {
         const newSkills = detectNewSkills();
@@ -183,6 +195,60 @@ export async function buildBeforeAgentStartResult(event, ctx) {
         ...(contextMessage ? { message: contextMessage } : {}),
     };
 }
+/**
+ * ADR-013 step 4 — auto-injection parity for the memories table.
+ *
+ * Mirrors loadKnowledgeBlock by producing a labeled, deterministic block
+ * combining two memory sets:
+ *
+ * 1. Always-on "critical" set — top-ranked active memories in categories
+ *    that future GSD turns generally want without asking. After ADR-013
+ *    expands this to include "architecture", these memories serve as the
+ *    auto-injected replacement for inlineDecisionsFromDb when the cutover
+ *    in step 6 lands.
+ * 2. Prompt-relevance set — FTS5/semantic hits against the current user
+ *    prompt, deduplicated against the critical set.
+ *
+ * Both sets are ranked, merged, and rendered via formatMemoriesForPrompt
+ * with a token-budget cap. Failures degrade gracefully — the function never
+ * throws and returns "" so the system prompt construction continues.
+ */
+export async function loadMemoryBlock(userPrompt) {
+    try {
+        const { formatMemoriesForPrompt, getActiveMemoriesRanked, queryMemoriesRanked } = await import("../memory-store.js");
+        // Categories that belong in every turn. Pre-ADR-013 this was just
+        // {gotcha, environment, convention}. ADR-013 adds "architecture" so
+        // decision-equivalent memories survive the inlineDecisionsFromDb cutover
+        // in step 6.
+        const CRITICAL_CATEGORIES = new Set(["gotcha", "environment", "convention", "architecture"]);
+        const CRITICAL_CAP = 8;
+        const QUERY_K = 10;
+        // ~1 token ≈ 4 chars. 4000 chars ≈ 1000 tokens — comfortably under the
+        // KNOWLEDGE.md 4KB warning threshold and roughly twice the pre-ADR-013
+        // budget so the absorbed DECISIONS surface fits.
+        const CHAR_BUDGET = 4000;
+        const allRanked = getActiveMemoriesRanked(80);
+        const critical = allRanked.filter((m) => CRITICAL_CATEGORIES.has(m.category)).slice(0, CRITICAL_CAP);
+        const criticalIds = new Set(critical.map((m) => m.id));
+        let relevant = [];
+        const trimmed = userPrompt.trim();
+        if (trimmed) {
+            const hits = queryMemoriesRanked({ query: trimmed, k: QUERY_K });
+            relevant = hits.map((h) => h.memory).filter((m) => !criticalIds.has(m.id));
+        }
+        const merged = [...critical, ...relevant];
+        if (merged.length === 0)
+            return "";
+        const formatted = formatMemoriesForPrompt(merged, CHAR_BUDGET);
+        if (!formatted)
+            return "";
+        return `\n\n[MEMORY — Critical and prompt-relevant memories from the GSD memory store]\n\n${formatted}`;
+    }
+    catch (e) {
+        logWarning("bootstrap", `memory block fetch failed: ${e.message}`);
+        return "";
+    }
+}
 export function loadKnowledgeBlock(gsdHomeDir, cwd) {
     // 1. Global knowledge (~/.gsd/agent/KNOWLEDGE.md) — cross-project, user-maintained
     let globalKnowledge = "";

package/dist/resources/extensions/gsd/bootstrap/write-gate.js

@@ -1,6 +1,13 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-const MILESTONE_CONTEXT_RE = /M\d+(?:-[a-z0-9]{6})?-CONTEXT\.md$/;
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { minimatch } from "minimatch";
+/**
+ * Regex matching milestone CONTEXT.md file names in both legacy M001
+ * and unique M001-abc123 formats. Exported so regex-hardening tests
+ * can exercise the real pattern rather than a drift-prone inline
+ * re-implementation (see #4835).
+ */
+export const MILESTONE_CONTEXT_RE = /M\d+(?:-[a-z0-9]{6})?-CONTEXT\.md$/;
 const CONTEXT_MILESTONE_RE = /(?:^|[/\\])(M\d+(?:-[a-z0-9]{6})?)-CONTEXT\.md$/i;
 const DEPTH_VERIFICATION_MILESTONE_RE = /depth_verification[_-](M\d+(?:-[a-z0-9]{6})?)/i;
 /**
@@ -24,8 +31,29 @@ const QUEUE_SAFE_TOOLS = new Set([
 /**
  * Bash commands that are read-only / investigative — safe during queue mode.
  * Matches the leading command in a bash invocation.
+ *
+ * Extension policy: add commands here when they are read-only / diagnostic.
+ * Never add commands that mutate project state (write files, run builds that
+ * emit artifacts, install packages, etc.).
+ *
+ * Current read-only additions (Bug #4385):
+ *   npm run <diagnostic> — read-only diagnostic scripts: test, lint, typecheck, etc.
+ *                         NOT: build, install, compile, generate, deploy (artifact-producing)
+ *   npm ls/list/info    — inspect installed packages (read-only)
+ *   npm outdated/audit  — security/update checks (read-only)
+ *   npx <pkg>           — run a package binary without installing globally
+ *   tsx                 — TypeScript runner used for dry-run / inspection scripts
+ *   node --print        — evaluate and print an expression, no side effects
+ *   python / python3    — script inspection, version checks
+ *   pip / pip3 show     — show installed package info (read-only)
+ *   jq                  — read-only JSON query
+ *   yq                  — read-only YAML query
+ *   curl -s / curl --silent — fetch for inspection (no -o / no output redirect)
+ *   openssl version     — version / certificate inspection
+ *   env / printenv      — print environment variables
+ *   true / false        — shell no-ops / test exit codes
  */
-const BASH_READ_ONLY_RE = /^\s*(cat|head|tail|less|more|wc|file|stat|du|df|which|type|echo|printf|ls|find|grep|rg|awk|sed\b(?!.*-i)|sort|uniq|diff|comm|tr|cut|tee\s+-a\s+\/dev\/null|git\s+(log|show|diff|status|branch|tag|remote|rev-parse|ls-files|blame|shortlog|describe|stash\s+list|config\s+--get|cat-file)|gh\s+(issue|pr|api|repo|release)\s+(view|list|diff|status|checks)|mkdir\s+-p\s+\.gsd|rtk\s)/;
+const BASH_READ_ONLY_RE = /^\s*(cat|head|tail|less|more|wc|file|stat|du|df|which|type|echo|printf|ls|find|grep|rg|awk|sed\b(?!.*-i)|sort|uniq|diff|comm|tr|cut|tee\s+-a\s+\/dev\/null|git\s+(log|show|diff|status|branch|tag|remote|rev-parse|ls-files|blame|shortlog|describe|stash\s+list|config\s+--get|cat-file)|gh\s+(issue|pr|api|repo|release)\s+(view|list|diff|status|checks)|mkdir\s+-p\s+\.gsd|rtk\s|npm\s+run\s+(test|test:\w+|lint|lint:\w+|typecheck|type-check|type-check:\w+|check|verify|audit|outdated|format:check|ci|validate)\b|npm\s+(ls|list|info|view|show|outdated|audit|explain|doctor|ping|--version|-v)\b|npx\s|tsx\s|node\s+(--print|--version|-v\b)|python[23]?\s+(-c\s+'[^']*'|--version|-V\b|-m\s+(pip\s+show|pip\s+list|site))|pip[23]?\s+(show|list|freeze|check|index\s+versions)\b|jq\s|yq\s|curl\s+(-s\b|--silent\b)(?!\s+[^|>]*\s-[oO]\b)(?!\s+[^|>]*\s--output\b)[^|>]*$|openssl\s+(version|x509|s_client)|env\b|printenv\b|true\b|false\b)/;
 const verifiedDepthMilestones = new Set();
 let activeQueuePhase = false;
 /**
@@ -55,8 +83,15 @@ const GATE_SAFE_TOOLS = new Set([
     "search-the-web", "resolve_library", "get_library_docs", "fetch_page",
     "search_and_read",
 ]);
+/**
+ * Persistence is ON by default (opt-out).
+ * Set GSD_PERSIST_WRITE_GATE_STATE="0" or GSD_PERSIST_WRITE_GATE_STATE="false"
+ * to disable. All other values — including unset — persist the snapshot.
+ * (Inverted from the original opt-in guard; see #4950.)
+ */
 function shouldPersistWriteGateSnapshot(env = process.env) {
-    return env.GSD_PERSIST_WRITE_GATE_STATE === "1";
+    const v = env.GSD_PERSIST_WRITE_GATE_STATE;
+    return v !== "0" && v !== "false";
 }
 function writeGateSnapshotPath(basePath = process.cwd()) {
     return join(basePath, ".gsd", "runtime", "write-gate-state.json");
@@ -73,9 +108,22 @@ function persistWriteGateSnapshot(basePath = process.cwd()) {
         return;
     const path = writeGateSnapshotPath(basePath);
     mkdirSync(join(basePath, ".gsd", "runtime"), { recursive: true });
-    const tempPath = `${path}.tmp`;
+    const tempPath = `${path}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`;
     writeFileSync(tempPath, JSON.stringify(currentWriteGateSnapshot(), null, 2), "utf-8");
-    renameSync(tempPath, path);
+    try {
+        renameSync(tempPath, path);
+    }
+    catch (err) {
+        // EXDEV: cross-device rename (temp and dest on different mounts). Fall back
+        // to copy-then-delete so the snapshot is still written atomically enough.
+        if (err instanceof Error && err.code === "EXDEV") {
+            copyFileSync(tempPath, path);
+            unlinkSync(tempPath);
+        }
+        else {
+            throw err;
+        }
+    }
 }
 function clearPersistedWriteGateSnapshot(basePath = process.cwd()) {
     if (!shouldPersistWriteGateSnapshot())
@@ -99,10 +147,21 @@ function normalizeWriteGateSnapshot(value) {
         pendingGateId: typeof record.pendingGateId === "string" ? record.pendingGateId : null,
     };
 }
+const EMPTY_SNAPSHOT = {
+    verifiedDepthMilestones: [],
+    activeQueuePhase: false,
+    pendingGateId: null,
+};
 export function loadWriteGateSnapshot(basePath = process.cwd()) {
     const path = writeGateSnapshotPath(basePath);
-    if (!existsSync(path))
+    if (!existsSync(path)) {
+        // When persist mode is active and the file has been deleted, treat it as a
+        // full state reset so deleting the file clears the HARD BLOCK gate.
+        // In non-persist mode the file is never written, so fall back to in-memory.
+        if (shouldPersistWriteGateSnapshot())
+            return EMPTY_SNAPSHOT;
         return currentWriteGateSnapshot();
+    }
     try {
         return normalizeWriteGateSnapshot(JSON.parse(readFileSync(path, "utf-8")));
     }
@@ -263,9 +322,9 @@ export function isDepthConfirmationAnswer(selected, options) {
         const confirmLabel = options[0]?.label;
         return typeof confirmLabel === "string" && value === confirmLabel;
     }
-    // Fallback when options aren't available (e.g., older call sites):
-    // accept only if it contains "(Recommended)" — the prompt convention suffix.
-    return value.includes("(Recommended)");
+    // Fail-closed: no options means we cannot structurally validate the answer.
+    // Returning false prevents any free-form string from unlocking the gate.
+    return false;
 }
 export function shouldBlockContextWrite(toolName, inputPath, milestoneId, _queuePhaseActive) {
     if (toolName !== "write")
@@ -381,3 +440,94 @@ export function shouldBlockQueueExecutionInSnapshot(snapshot, toolName, input, q
         reason: `Blocked: /gsd queue is a planning tool — it creates milestones, not executes work. Unknown tools are not permitted during queue mode.`,
     };
 }
+// ─── Planning-unit tools-policy enforcement (#4934) ───────────────────────
+const PLANNING_WRITE_TOOLS = new Set(["write", "edit", "multi_edit", "notebook_edit"]);
+const PLANNING_SUBAGENT_TOOLS = new Set(["subagent", "task"]);
+const PLANNING_SAFE_TOOLS = new Set([
+    "read", "grep", "find", "ls", "glob",
+    "ask_user_questions",
+    "search-the-web", "resolve_library", "get_library_docs", "fetch_page",
+    "search_and_read",
+]);
+function isPathUnderGsd(absPath, basePath) {
+    const gsdRoot = resolve(basePath, ".gsd");
+    const rel = relative(gsdRoot, absPath);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+function matchesAllowedGlob(absPath, basePath, globs) {
+    const rel = relative(basePath, absPath);
+    if (rel.startsWith("..") || isAbsolute(rel))
+        return false;
+    const posix = rel.split(sep).join("/");
+    return globs.some(g => minimatch(posix, g, { dot: false, nocase: false }));
+}
+function blockReason(unitType, mode, what) {
+    return [
+        `HARD BLOCK: unit "${unitType}" runs under tools-policy "${mode}" — ${what}.`,
+        `This is a mechanical gate enforced by manifest.tools (#4934). You MUST NOT proceed,`,
+        `retry the same call, or rationalize past this block. If you need to write user source,`,
+        `the work belongs in execute-task, not in a planning unit.`,
+    ].join(" ");
+}
+/**
+ * Planning-unit tool-policy enforcement. Returns { block } per the policy
+ * resolved from the active unit's manifest:
+ *
+ *   - "all"        → never blocks.
+ *   - "read-only"  → blocks all writes, bash, and subagent dispatch.
+ *   - "planning"   → blocks writes to paths outside <basePath>/.gsd/,
+ *                    bash that isn't read-only, and subagent dispatch.
+ *   - "docs"       → like "planning" but also allows writes to paths
+ *                    matching `allowedPathGlobs` relative to basePath.
+ *
+ * `policy` of null means "no manifest resolved" — pass-through.
+ */
+export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitType, policy) {
+    if (!policy)
+        return { block: false };
+    if (policy.mode === "all")
+        return { block: false };
+    const tool = toolName;
+    if (policy.mode === "read-only") {
+        if (PLANNING_SAFE_TOOLS.has(tool))
+            return { block: false };
+        if (tool.startsWith("gsd_"))
+            return { block: false };
+        if (PLANNING_WRITE_TOOLS.has(tool) || tool === "bash" || PLANNING_SUBAGENT_TOOLS.has(tool)) {
+            return { block: true, reason: blockReason(unitType, policy.mode, `${tool} is not permitted (read-only)`) };
+        }
+        return { block: true, reason: blockReason(unitType, policy.mode, `tool "${tool}" is not on the read-only allowlist`) };
+    }
+    // planning / docs modes
+    if (PLANNING_SAFE_TOOLS.has(tool))
+        return { block: false };
+    if (tool.startsWith("gsd_"))
+        return { block: false };
+    if (PLANNING_SUBAGENT_TOOLS.has(tool)) {
+        return { block: true, reason: blockReason(unitType, policy.mode, `subagent dispatch is not permitted in planning units`) };
+    }
+    if (tool === "bash") {
+        if (BASH_READ_ONLY_RE.test(pathOrCommand))
+            return { block: false };
+        return {
+            block: true,
+            reason: blockReason(unitType, policy.mode, `bash is restricted to read-only commands (cat/grep/git log/etc); cannot run "${pathOrCommand.slice(0, 80)}${pathOrCommand.length > 80 ? "…" : ""}"`),
+        };
+    }
+    if (PLANNING_WRITE_TOOLS.has(tool)) {
+        if (!pathOrCommand) {
+            return { block: true, reason: blockReason(unitType, policy.mode, `${tool} called with empty path`) };
+        }
+        const absPath = isAbsolute(pathOrCommand) ? pathOrCommand : resolve(basePath, pathOrCommand);
+        if (isPathUnderGsd(absPath, basePath))
+            return { block: false };
+        if (policy.mode === "docs" && matchesAllowedGlob(absPath, basePath, policy.allowedPathGlobs)) {
+            return { block: false };
+        }
+        return {
+            block: true,
+            reason: blockReason(unitType, policy.mode, `cannot ${tool} "${pathOrCommand}" — writes are restricted to .gsd/${policy.mode === "docs" ? " and " + policy.allowedPathGlobs.join(", ") : ""}`),
+        };
+    }
+    return { block: false };
+}