@hegemonart/get-design-done 1.59.6 → 1.59.8

package/hooks/_hook-emit.js

@@ -24,58 +24,142 @@
 
 'use strict';
 
+const fs = require('node:fs');
+const path = require('node:path');
+
 let cachedAppendEvent = null;
 let resolutionAttempted = false;
 
 /**
- * Lazy-resolve `appendEvent` — only loads the event-stream module the
- * first time a hook fires. Falls back to a no-op if the module is not
- * loadable in the current runtime (e.g. plain `node` without
- * --experimental-strip-types).
+ * Best-effort resolve of the SDK `appendEvent`. On modern Node (≥22.18,
+ * which supports `require()` of ESM/`.ts` via type-stripping) this loads
+ * the full event-stream writer — giving us bus broadcast + the SDK's
+ * truncation/redaction logic for free. On older Node (22.0–22.17), the
+ * `.ts` require throws and we fall back to `null`; the inline appender
+ * below takes over so `hook.fired` STILL lands on disk.
+ *
+ * Returns `null` (not a no-op) when unavailable so the caller knows to
+ * use the inline path instead of silently dropping the event.
  *
- * @returns {(ev: unknown) => void}
+ * @returns {((ev: unknown) => void) | null}
  */
 function getAppendEvent() {
-  if (cachedAppendEvent !== null || resolutionAttempted) {
-    return cachedAppendEvent || (() => {});
-  }
+  if (resolutionAttempted) return cachedAppendEvent;
   resolutionAttempted = true;
   try {
-    // event-stream/index.ts requires --experimental-strip-types. Try
-    // require()'ing — if Node refuses to parse `.ts`, we silently fall
-    // back to no-op.
     // eslint-disable-next-line node/no-missing-require, global-require
-    cachedAppendEvent = require('../sdk/event-stream/index.ts').appendEvent;
-    return cachedAppendEvent;
+    const m = require('../sdk/event-stream/index.ts');
+    if (m && typeof m.appendEvent === 'function') {
+      cachedAppendEvent = m.appendEvent;
+    }
   } catch {
     cachedAppendEvent = null;
-    return () => {};
   }
+  return cachedAppendEvent;
+}
+
+// ---------------------------------------------------------------------------
+// Inline redaction (best-effort). The SDK writer scrubs secrets at the
+// serialize boundary via scripts/lib/redact.cjs. When we take the inline
+// append path (older Node), replicate that scrubbing so the fallback never
+// leaks secrets that the SDK path would have caught. redact.cjs is plain
+// CommonJS, so it loads under any Node version. If unreachable, identity.
+// ---------------------------------------------------------------------------
+
+let cachedRedact = null;
+let redactResolved = false;
+
+function getRedact() {
+  if (redactResolved) return cachedRedact;
+  redactResolved = true;
+  try {
+    // eslint-disable-next-line global-require
+    const m = require('../scripts/lib/redact.cjs');
+    if (m && typeof m.redact === 'function') cachedRedact = m.redact;
+  } catch {
+    cachedRedact = null;
+  }
+  return cachedRedact;
 }
 
 /**
- * Emit a `hook.fired` event. Silent on every failure mode.
+ * Resolve the on-disk events.jsonl path the same way the SDK writer does:
+ * honor GDD_EVENTS_PATH (absolute path used by tests/E2E to steer the
+ * stream), else default to `<cwd>/.design/telemetry/events.jsonl`.
  *
- * @param {string} hookName
- * @param {string} decision
- * @param {Record<string, unknown>} [extras] — opaque additional payload fields
+ * @returns {string}
  */
-function emitHookFired(hookName, decision, extras) {
+function resolveEventsPath() {
+  const envPath = process.env.GDD_EVENTS_PATH;
+  if (typeof envPath === 'string' && envPath.length > 0) {
+    return path.isAbsolute(envPath) ? envPath : path.resolve(process.cwd(), envPath);
+  }
+  return path.resolve(process.cwd(), '.design', 'telemetry', 'events.jsonl');
+}
+
+/**
+ * Inline append of one event as a JSONL line. Mirrors the SDK
+ * EventWriter.append minimal envelope contract: redact → JSON.stringify →
+ * appendFileSync with O_APPEND. NEVER throws.
+ *
+ * @param {Record<string, unknown>} ev
+ */
+function inlineAppend(ev) {
   try {
+    const redact = getRedact();
+    const scrubbed = redact ? redact(ev) : ev;
+    const dest = resolveEventsPath();
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.appendFileSync(dest, JSON.stringify(scrubbed) + '\n', { flag: 'a' });
+  } catch {
+    /* hooks must never throw on telemetry */
+  }
+}
+
+/**
+ * Persist an arbitrary event envelope. Silent on every failure mode.
+ * Uses the SDK writer when loadable (modern Node), else the inline
+ * appender (older Node) — so the event ACTUALLY lands on disk on every
+ * supported Node version instead of no-op'ing.
+ *
+ * @param {Record<string, unknown>} ev — must carry at least `type`
+ */
+function emitEvent(ev) {
+  try {
+    if (!ev || typeof ev !== 'object') return;
     const appendEvent = getAppendEvent();
-    const payload = { hook: hookName, decision };
-    if (extras && typeof extras === 'object') {
-      Object.assign(payload, extras);
+    if (appendEvent) {
+      appendEvent(ev);
+    } else {
+      inlineAppend(ev);
     }
-    appendEvent({
-      type: 'hook.fired',
-      timestamp: new Date().toISOString(),
-      sessionId: process.env.GDD_SESSION_ID || 'hook',
-      payload,
-    });
   } catch {
     /* hooks must never throw on telemetry */
   }
 }
 
-module.exports = { emitHookFired };
+/**
+ * Emit a `hook.fired` event. Silent on every failure mode.
+ *
+ * Happy path actually lands a line in `.design/telemetry/events.jsonl`
+ * (or GDD_EVENTS_PATH) on EVERY supported Node version — via the SDK
+ * writer when loadable, else via the inline appender.
+ *
+ * @param {string} hookName
+ * @param {string} decision
+ * @param {Record<string, unknown>} [extras] — opaque additional payload fields
+ */
+function emitHookFired(hookName, decision, extras) {
+  const payload = { hook: hookName, decision };
+  if (extras && typeof extras === 'object') {
+    Object.assign(payload, extras);
+  }
+  emitEvent({
+    type: 'hook.fired',
+    timestamp: new Date().toISOString(),
+    sessionId: process.env.GDD_SESSION_ID || 'hook',
+    payload,
+  });
+}
+
+module.exports = { emitHookFired, emitEvent };

package/hooks/budget-enforcer.ts

@@ -350,6 +350,19 @@ interface ToolOutput {
   stopReason?: string;
   modified_tool_input?: ToolInput;
   cached_result?: unknown;
+  /**
+   * Claude Code PreToolUse hook-specific envelope. This is the ONLY
+   * supported mechanism on current Claude Code for mutating a tool's
+   * input (`updatedInput`) or blocking a call (`permissionDecision`).
+   * The top-level `modified_tool_input` / `cached_result` fields are
+   * retained for backward-compat but are silently ignored by the harness.
+   */
+  hookSpecificOutput?: {
+    hookEventName: 'PreToolUse';
+    permissionDecision?: 'allow' | 'deny' | 'ask';
+    permissionDecisionReason?: string;
+    updatedInput?: ToolInput;
+  };
 }
 
 /** Shape of .design/cache-manifest.json — D-05 cache short-circuit. */
@@ -733,8 +746,28 @@ export function resolveTier(
  */
 function spawnAggregator(): void {
   try {
-    const aggregatorPath = join(
-      process.cwd(),
+    // Opt-out: when GDD_NO_AGGREGATOR is set (truthy), skip the detached
+    // child entirely. Production leaves this unset so the rollups stay
+    // current; tests that scaffold a throwaway temp cwd set it so the
+    // fire-and-forget child doesn't hold a handle on the dir they delete
+    // immediately after (a Windows rmSync EPERM race surfaced once the C3
+    // fix made this spawn actually resolve the script). No effect on the
+    // production code path.
+    const optOut = process.env['GDD_NO_AGGREGATOR'];
+    if (typeof optOut === 'string' && optOut !== '' && optOut !== '0' && optOut !== 'false') {
+      return;
+    }
+    // C3 fix: resolve the aggregator script relative to THIS hook file's
+    // location (the plugin's own tree), not process.cwd(). When an installed
+    // user runs from their project root, cwd is NOT the plugin repo, so
+    // `join(process.cwd(), 'scripts', ...)` never exists and the aggregator
+    // silently never runs — leaving phase-totals.json unbuilt and forcing a
+    // full costs.jsonl re-parse on every spawn. Anchor on the hook file via
+    // the same resolveHookPath() idiom used for createRequire above
+    // (hooks/budget-enforcer.ts → ../scripts/aggregate-agent-metrics.ts).
+    const aggregatorPath = resolve(
+      dirname(resolveHookPath()),
+      '..',
       'scripts',
       'aggregate-agent-metrics.ts',
     );
@@ -976,7 +1009,7 @@ export async function main(): Promise<void> {
     process.exit(0);
   }
 
-  if (parsed.tool_name !== 'Agent') process.exit(0);
+  if (parsed.tool_name !== 'Agent' && parsed.tool_name !== 'Task') process.exit(0);
 
   const toolInput: ToolInput = parsed.tool_input ?? {};
   const agent =
@@ -1059,6 +1092,7 @@ export async function main(): Promise<void> {
       continue: true,
       suppressOutput: true,
       modified_tool_input: toolInput,
+      hookSpecificOutput: { hookEventName: 'PreToolUse', updatedInput: toolInput },
     };
     process.stdout.write(JSON.stringify(response));
     return;
@@ -1090,10 +1124,14 @@ export async function main(): Promise<void> {
       });
       emitHookFired('cache', cycle);
       const response: ToolOutput = {
-        continue: false,
+        continue: true,
         suppressOutput: false,
         message: `gdd-budget-enforcer: SkippedCached — returning cached result for ${agent}:${inputHash}`,
-        cached_result: cached,
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: 'deny',
+          permissionDecisionReason: `SkippedCached — a prior identical spawn already produced a result. Reuse it instead of re-spawning. Cached: ${JSON.stringify(cached).slice(0, 2000)}`,
+        },
       };
       process.stdout.write(JSON.stringify(response));
       return;
@@ -1581,6 +1619,7 @@ export async function main(): Promise<void> {
     continue: true,
     suppressOutput: true,
     modified_tool_input: toolInput,
+    hookSpecificOutput: { hookEventName: 'PreToolUse', updatedInput: toolInput },
   };
   process.stdout.write(JSON.stringify(response));
 }

package/hooks/gdd-mcp-circuit-breaker.js

@@ -25,6 +25,32 @@ const DEFAULT_FILE = path.join(REPO_ROOT, 'reference', 'mcp-budget.default.json'
 
 const TRACKED_TOOL_RE = /^mcp__.*use_(figma|paper|pencil)$/;
 
+// Bounded fallback window (ms) for counting volume when no session id is
+// available on the payload. Without this, `total_calls` would count every row
+// ever appended to the ledger — so after `max_calls_per_task` cumulative calls
+// across ALL sessions for the lifetime of the file, every mutation is blocked
+// forever (and a BLOCKER is appended to STATE.md each time). The volume gate is
+// meant to be PER-TASK; this window keeps the fallback path per-task-ish so a
+// long-lived user is never permanently locked out.
+const SESSIONLESS_WINDOW_MS = 6 * 60 * 60 * 1000; // 6 hours
+
+/**
+ * Resolve the current session id from the hook payload (Claude Code passes
+ * `session_id`; tolerate `sessionId`), falling back to GDD_SESSION_ID, else
+ * null. A non-null id makes the volume window exact (count only this session's
+ * rows); null falls back to the bounded time window.
+ *
+ * @param {any} payload
+ * @returns {string|null}
+ */
+function resolveSessionId(payload) {
+  const fromPayload = payload && (payload.session_id || payload.sessionId);
+  if (typeof fromPayload === 'string' && fromPayload.length > 0) return fromPayload;
+  const fromEnv = process.env.GDD_SESSION_ID;
+  if (typeof fromEnv === 'string' && fromEnv.length > 0) return fromEnv;
+  return null;
+}
+
 function loadBudget(cwd) {
   let defaults = { max_calls_per_task: 30, max_consecutive_timeouts: 3, reset_on_success: true };
   try {
@@ -106,7 +132,25 @@ function classifyOutcome(toolResponse) {
   return 'error';
 }
 
-function readJsonlTail(filePath) {
+/**
+ * Read the ledger and compute the prior volume + consecutive-timeout state
+ * for the CURRENT task window only — not the whole-file lifetime.
+ *
+ * Window membership for a row:
+ *   - If a current session id is known AND the row carries a `session` field:
+ *     the row counts iff `row.session === sessionId`.
+ *   - Otherwise (sessionless harness/tests, or legacy rows without `session`):
+ *     the row counts iff its timestamp is within SESSIONLESS_WINDOW_MS of now.
+ *
+ * This bounds the volume count so a long-lived ledger can never permanently
+ * trip `volumeBreak`, while keeping rapid same-task calls (the common case and
+ * the existing test scenario) counted together.
+ *
+ * @param {string} filePath
+ * @param {string|null} sessionId
+ * @param {number} nowMs
+ */
+function readJsonlTail(filePath, sessionId, nowMs) {
   if (!fs.existsSync(filePath)) return { lastRow: null, total_calls: 0, consecutive_timeouts: 0 };
   let total = 0;
   let lastTimeoutsChain = 0;
@@ -118,6 +162,25 @@ function readJsonlTail(filePath) {
       if (!t) continue;
       let row;
       try { row = JSON.parse(t); } catch { continue; }
+
+      // Decide whether this row belongs to the current task window.
+      let inWindow;
+      if (sessionId !== null && typeof row.session === 'string' && row.session.length > 0) {
+        inWindow = row.session === sessionId;
+      } else {
+        const rowMs = typeof row.ts === 'string' ? Date.parse(row.ts) : NaN;
+        // Unparseable timestamps fall back to "in window" so we never
+        // under-count; a malformed-ts row is treated as recent.
+        inWindow = Number.isNaN(rowMs) ? true : (nowMs - rowMs) <= SESSIONLESS_WINDOW_MS;
+      }
+
+      if (!inWindow) {
+        // Out-of-window rows reset the streak — a new task/session must not
+        // inherit a stale consecutive-timeout chain.
+        lastTimeoutsChain = 0;
+        continue;
+      }
+
       total++;
       if (row.outcome === 'timeout') lastTimeoutsChain++;
       else lastTimeoutsChain = 0;
@@ -158,7 +221,9 @@ async function main() {
   const budget = loadBudget(cwd);
   const ledgerPath = path.join(cwd, '.design', 'telemetry', 'mcp-budget.jsonl');
 
-  const prior = readJsonlTail(ledgerPath);
+  const sessionId = resolveSessionId(payload);
+  const nowMs = Date.now();
+  const prior = readJsonlTail(ledgerPath, sessionId, nowMs);
   const outcome = classifyOutcome(payload?.tool_response);
   const total_calls = prior.total_calls + 1;
   const consecutive_timeouts = outcome === 'timeout'
@@ -166,12 +231,16 @@ async function main() {
     : (budget.reset_on_success && outcome === 'success' ? 0 : prior.consecutive_timeouts);
 
   const row = {
-    ts: new Date().toISOString(),
+    ts: new Date(nowMs).toISOString(),
     tool,
     outcome,
     consecutive_timeouts,
     total_calls,
   };
+  // Stamp the session id so future calls can scope the volume window exactly.
+  // Omitted when unknown (keeps the row schema stable for the sessionless path,
+  // which relies on the time window instead).
+  if (sessionId !== null) row.session = sessionId;
   appendJsonl(ledgerPath, row);
 
   const timeoutBreak = consecutive_timeouts >= budget.max_consecutive_timeouts;

package/hooks/gdd-sessionstart-recap.js

@@ -57,17 +57,21 @@ function detectHarness() {
 }
 
 // ---------------------------------------------------------------------------
-// Lazy event-stream emit (best-effort)
+// Event emit (best-effort) — delegate to the shared _hook-emit helper, which
+// uses the SDK writer when loadable (modern Node) and an inline JSONL appender
+// otherwise. The previous direct `require('../sdk/event-stream')` resolved to
+// the `.ts` ESM index and threw under plain `node` on Node 22.0–22.17, leaving
+// recap.emitted permanently no-op'd. emitEvent lands the line on every Node.
 // ---------------------------------------------------------------------------
 
-function getAppendEvent() {
+function getEmitEvent() {
   try {
-    const m = require('../sdk/event-stream');
-    if (m && typeof m.appendEvent === 'function') return m.appendEvent;
+    const m = require('./_hook-emit.js');
+    if (m && typeof m.emitEvent === 'function') return m.emitEvent;
   } catch {
-    /* swallow — event-stream is optional infrastructure */
+    /* swallow — telemetry is optional infrastructure */
   }
-  return function noopAppend(_ev) {
+  return function noopEmit(_ev) {
     /* no-op */
   };
 }
@@ -87,9 +91,12 @@ function readStateMd(paths) {
   }
 
   const frontmatter = {};
-  const fmMatch = body.match(/^---\n([\s\S]*?)\n---\n/);
+  // Tolerate CRLF line endings — the STATE.md mutator preserves CRLF, so a
+  // strict `\n`-only anchor fails to match the frontmatter block on Windows
+  // checkouts and the recap silently reports an empty cycle/decisions diff.
+  const fmMatch = body.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
   if (fmMatch) {
-    for (const line of fmMatch[1].split('\n')) {
+    for (const line of fmMatch[1].split(/\r?\n/)) {
       const m = line.match(/^(\w+):\s*(.+)$/);
       if (m) frontmatter[m[1]] = m[2].trim();
     }
@@ -273,9 +280,9 @@ async function main() {
   }
 
   // Best-effort event emit.
-  const appendEvent = getAppendEvent();
+  const emitEvent = getEmitEvent();
   try {
-    appendEvent({
+    emitEvent({
       type: 'recap.emitted',
       timestamp: new Date().toISOString(),
       sessionId: process.env.GDD_SESSION_ID || 'sessionstart-hook',
@@ -300,9 +307,11 @@ async function main() {
   process.exit(0);
 }
 
-try {
-  main();
-} catch (err) {
+// `main` is async: a sync try/catch cannot observe a rejected promise, so a
+// throw inside an `await` boundary would escape as an unhandled rejection and
+// exit non-zero — violating the silent-exit-0 contract for SessionStart hooks.
+// Attach `.catch` so every failure mode is swallowed and we exit 0.
+main().catch((err) => {
   try {
     process.stderr.write(
       '[gdd-sessionstart-recap] uncaught: ' +
@@ -313,4 +322,4 @@ try {
     /* swallow */
   }
   process.exit(0);
-}
+});

package/hooks/hooks.json

@@ -45,7 +45,7 @@
     ],
     "PreToolUse": [
       {
-        "matcher": "Agent",
+        "matcher": "Task|Agent",
         "hooks": [
           {
             "type": "command",
@@ -119,7 +119,7 @@
         ]
       },
       {
-        "matcher": "Agent",
+        "matcher": "Task|Agent",
         "hooks": [
           {
             "type": "command",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.59.6",
+  "version": "1.59.8",
   "description": "A design-quality pipeline for AI coding agents: brief, explore, plan, design, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",
@@ -10,7 +10,7 @@
   },
   "license": "MIT",
   "engines": {
-    "node": ">=22"
+    "node": ">=22.6.0"
   },
   "files": [
     ".claude-plugin/",

package/reference/bandit-integration.md

@@ -10,7 +10,7 @@ description: Bandit posterior + production-integration shim cheat sheet - signat
 
 **Phase 27.5 (v1.27.5).** Reference for the bandit production-integration surface. Authoring or modifying a caller of the bandit posterior? Debugging a routing decision at the code level? Start here.
 
-For ops-level guidance (when bandit fires, how to disable, posterior inspection), see `docs/BANDIT-INTEGRATION.md`.
+For ops-level guidance (when bandit fires, how to disable, posterior inspection), use the read-only diagnostic surfaces: `/gdd:bandit-status` (per-arm posterior snapshots) and `/gdd:bandit-reset` (confirm-then-reset). The `adaptive_mode` gate below covers enable/disable.
 
 In-scope modules:
 
@@ -104,6 +104,17 @@ Phase 27.5 passes `wallTimeMs: 0` always (D-08 unchanged from Phase 23.5).
 
 ---
 
+## Where adaptive routing actually learns
+
+This is a deliberate design boundary, not a bug - read it before assuming the bandit "learns" in every runtime.
+
+- **The posterior is updated only on the SDK / headless path.** `recordOutcome` (the learning update that moves `alpha`/`beta`) is called from `scripts/lib/session-runner/index.ts` after a session terminates. That path runs in the SDK / headless `session-runner` execution model. It is the only place a reward is folded back into the posterior.
+- **In interactive Claude Code with `adaptive_mode: full`, the bandit samples but does not currently learn from in-session outcomes.** When a plugin/interactive run consults the bandit, `consultBandit` performs a Thompson sample from the *configured priors* (and whatever the SDK path has already written), and `pull()` bumps `last_used` + `count` - but no `recordOutcome` fires from an interactive Claude Code hook, so the success/fail posterior does not move within the interactive session. With an un-seeded posterior, sampling therefore reflects the informed `TIER_PRIOR` (which leans toward the higher tiers, e.g. opus). Wiring `recordOutcome` into an interactive hook is intentionally out of scope for this phase.
+- **`adaptive_mode` defaults to `static` - the feature is opt-in.** Per `scripts/lib/adaptive-mode.cjs`, the default mode is `static`, in which the bandit is fully silent (no reads, no writes) and `default-tier:` is authoritative. Adaptive routing only engages when an operator explicitly sets `adaptive_mode: full` in `.design/budget.json`.
+- **Contextual dimensions are supplied by the caller, not inferred here.** The `bin` (glob-count bucket via `binForGlobCount`) and `delegate` dimensions are passed in at the call site; the router does not derive them from ambient session state.
+
+Net: enable `adaptive_mode: full` and run the SDK/headless `session-runner` path to accumulate a posterior that genuinely reflects observed outcomes. In interactive Claude Code, `full` mode gives you prior-driven Thompson sampling, not in-session reinforcement.
+
 ## `adaptive_mode` gate semantics
 
 Phase 23.5 ladder (D-07):
@@ -154,7 +165,7 @@ Phase 27.5 wires these consumers:
 
 ## Cross-references
 
-- `docs/BANDIT-INTEGRATION.md` - operator guide (when bandit fires, how to disable, troubleshooting).
+- `/gdd:bandit-status` + `/gdd:bandit-reset` - read-only operator surfaces (when bandit fires, posterior inspection, reset). Disable/enable is the `adaptive_mode` gate in `.design/budget.json` (see above).
 - `reference/peer-protocols.md` - Phase 27 ACP/ASP cheat sheet (peer-CLI delegation transport).
 - `scripts/lib/bandit-router.cjs` - Phase 23.5 primitives surface.
 - `scripts/lib/bandit-router/integration.cjs` - Phase 27.5 production shim.

package/scripts/bootstrap.cjs

@@ -148,6 +148,14 @@ function filesEqual(a, b) {
   }
 }
 
+/**
+ * Network timeout (ms) for the git clone/pull. SessionStart hooks must never
+ * block the harness: without a timeout, a hung network connection would stall
+ * the whole session-start sequence indefinitely. spawnSync kills the child
+ * with `killSignal` once this elapses and reports it as a failure.
+ */
+const GIT_TIMEOUT_MS = 15000;
+
 /**
  * Match the .sh `clone_or_update`:
  *   - target/.git exists  → `git -C target pull --quiet --ff-only`, log on fail
@@ -157,8 +165,14 @@ function filesEqual(a, b) {
  * We invoke the `git` CLI directly via spawnSync. spawnSync('git', …) is fine —
  * the prohibition is on spawnSync('bash', …).
  *
+ * Returns true ONLY when the repo is in a good post-condition (pull/clone
+ * succeeded, or a pre-existing non-git dir we intentionally skip). Returns
+ * false when a network op failed or timed out — so the caller can withhold the
+ * success marker and retry next session instead of recording failure as done.
+ *
  * @param {string} repoUrl
  * @param {string} target
+ * @returns {boolean} success
  */
 function cloneOrUpdate(repoUrl, target) {
   let isGitCheckout = false;
@@ -177,16 +191,22 @@ function cloneOrUpdate(repoUrl, target) {
     const r = spawnSync('git', ['-C', target, 'pull', '--quiet', '--ff-only'], {
       stdio: ['ignore', 'ignore', 'ignore'],
       windowsHide: true,
+      timeout: GIT_TIMEOUT_MS,
+      killSignal: 'SIGKILL',
     });
     if (r.error || r.status !== 0) {
-      log(`pull failed for ${target} (continuing)`);
+      const why = r.error && r.error.code === 'ETIMEDOUT' ? 'timed out' : 'failed';
+      log(`pull ${why} for ${target} (continuing)`);
+      return false;
     }
-    return;
+    return true;
   }
 
   if (targetExists) {
     log(`${target} exists and is not a git checkout — skipping`);
-    return;
+    // A pre-existing non-git dir is a stable post-condition, not a failure:
+    // re-running won't change it, so don't force a retry every session.
+    return true;
   }
 
   // Defense in depth: refuse repoUrl / target arguments that look like git
@@ -196,7 +216,7 @@ function cloneOrUpdate(repoUrl, target) {
   if (typeof repoUrl !== 'string' || repoUrl.startsWith('-') ||
       typeof target !== 'string' || target.startsWith('-')) {
     log(`refusing suspicious clone args for ${repoUrl} -> ${target}`);
-    return;
+    return false;
   }
 
   log(`cloning ${repoUrl} -> ${target}`);
@@ -205,10 +225,15 @@ function cloneOrUpdate(repoUrl, target) {
   const r = spawnSync('git', ['clone', '--quiet', '--depth', '1', '--', repoUrl, target], {
     stdio: ['ignore', 'ignore', 'ignore'],
     windowsHide: true,
+    timeout: GIT_TIMEOUT_MS,
+    killSignal: 'SIGKILL',
   });
   if (r.error || r.status !== 0) {
-    log(`clone failed for ${repoUrl}`);
+    const why = r.error && r.error.code === 'ETIMEDOUT' ? 'timed out' : 'failed';
+    log(`clone ${why} for ${repoUrl}`);
+    return false;
   }
+  return true;
 }
 
 /**
@@ -315,7 +340,7 @@ function run(opts = {}) {
   }
 
   // Required library: VoltAgent/awesome-design-md.
-  cloneOrUpdate(
+  const repoOk = cloneOrUpdate(
     'https://github.com/VoltAgent/awesome-design-md.git',
     ctx.awesomeRepoTarget
   );
@@ -332,8 +357,15 @@ function run(opts = {}) {
   // Phase 10.1: .design/budget.json + .design/telemetry/ (D-12).
   ensureDesignDir(cwd);
 
-  // Record success so we don't re-run until the bundled manifest changes.
-  copyManifestToMarker(ctx.manifest, ctx.marker);
+  // Record success ONLY when the network provisioning actually succeeded.
+  // Writing the marker unconditionally records a failed clone as "done" and
+  // never retries — leaving the required library permanently absent. Gating on
+  // repoOk means a transient network failure/timeout is retried next session.
+  if (repoOk) {
+    copyManifestToMarker(ctx.manifest, ctx.marker);
+  } else {
+    log('skipping success marker — provisioning incomplete, will retry next session');
+  }
 
   return 0;
 }

package/scripts/install.cjs

@@ -211,6 +211,28 @@ async function main() {
       }
       runtimes = picked.runtimes;
       if (picked.location) location = picked.location;
+    } else if (uninstall) {
+      // B4 fix (Phase 59.8): bare `--uninstall` in a non-TTY context must NOT
+      // silently default to removing claude. The interactive path is the only
+      // safe way to pick what to remove without an explicit flag; in non-TTY
+      // we refuse and require an explicit runtime flag so a scripted/CI
+      // invocation can never destroy an install the operator didn't name.
+      // (See the comment at shouldUseInteractive: bare --uninstall is meant to
+      // trigger the interactive select-which-to-remove flow.)
+      process.stderr.write(
+        [
+          'Refusing to uninstall: no runtime specified and not running in an',
+          'interactive terminal.',
+          '',
+          'Re-run with an explicit runtime flag, e.g.:',
+          '  npx @hegemonart/get-design-done --uninstall --claude',
+          '  npx @hegemonart/get-design-done --uninstall --all',
+          '',
+          'Run with --help to list available runtime flags.',
+          '',
+        ].join('\n'),
+      );
+      process.exit(2);
     } else {
       // Non-TTY zero-flag fallback: back-compat with v1.23.5 behaviour.
       runtimes = ['claude'];
@@ -359,7 +381,7 @@ async function maybeNudgePeerCli({ flags }) {
       '✓ Detected peer CLIs: ' + detectedDisplay,
       '',
       'gdd v1.27.0 introduced optional peer-CLI delegation. With your',
-      'agents\\u2019 frontmatter `delegate_to:` set, gdd can route specific',
+      "agents' frontmatter `delegate_to:` set, gdd can route specific",
       'roles through these peer CLIs (cost or quality wins per Phase 23.5',
       'bandit). You can change this anytime via .design/config.json.',
       '',