@geraldmaron/construct 1.0.21 → 1.0.24

package/lib/embed/reconcile.mjs

@@ -26,8 +26,8 @@ export async function reconcileObservationEmbeddings(rootDir, { env = process.en
   const result = { checked: 0, reembedded: 0, model: null, skipped: null };
 
   try {
-    if (!(await client.isHealthy()) || !(await client.isPgvectorEnabled())) {
-      result.skipped = 'no-pg';
+    if (!(await client.isHealthy())) {
+      result.skipped = 'unhealthy';
       return result;
     }
 

package/lib/features.mjs

@@ -63,27 +63,27 @@ function readOpenCodeConfig(overrides = {}) {
   return null;
 }
 
-function getVSCodeSettingsPaths(overrides = {}) {
-  if (overrides.vscodeSettingsPaths) return overrides.vscodeSettingsPaths.filter(existsSync);
+function getVSCodeUserMcpPaths(overrides = {}) {
+  if (overrides.vscodeMcpPaths) return overrides.vscodeMcpPaths.filter(existsSync);
   const home = getHomeDir(overrides);
   const { platform } = process;
   if (platform === 'darwin') {
     return [
-      join(home, 'Library', 'Application Support', 'Code', 'User', 'settings.json'),
-      join(home, 'Library', 'Application Support', 'Code - Insiders', 'User', 'settings.json'),
+      join(home, 'Library', 'Application Support', 'Code', 'User', 'mcp.json'),
+      join(home, 'Library', 'Application Support', 'Code - Insiders', 'User', 'mcp.json'),
     ].filter(existsSync);
   }
   if (platform === 'linux') {
     return [
-      join(home, '.config', 'Code', 'User', 'settings.json'),
-      join(home, '.config', 'Code - Insiders', 'User', 'settings.json'),
+      join(home, '.config', 'Code', 'User', 'mcp.json'),
+      join(home, '.config', 'Code - Insiders', 'User', 'mcp.json'),
     ].filter(existsSync);
   }
   if (platform === 'win32') {
     const appData = process.env.APPDATA ?? join(home, 'AppData', 'Roaming');
     return [
-      join(appData, 'Code', 'User', 'settings.json'),
-      join(appData, 'Code - Insiders', 'User', 'settings.json'),
+      join(appData, 'Code', 'User', 'mcp.json'),
+      join(appData, 'Code - Insiders', 'User', 'mcp.json'),
     ].filter(existsSync);
   }
   return [];
@@ -230,9 +230,9 @@ function getMcpPlatforms(mcp, overrides = {}) {
   }
 
   // --- VS Code / Copilot ---
-  for (const p of getVSCodeSettingsPaths(overrides)) {
-    const settings = readJSON(p);
-    if (configHasAny(settings?.['github.copilot.mcpServers'], matchIds)) {
+  for (const p of getVSCodeUserMcpPaths(overrides)) {
+    const config = readJSON(p);
+    if (configHasAny(config?.servers, matchIds)) {
       const label = p.includes('Insiders') ? 'VS Code Insiders' : 'VS Code';
       if (!platforms.includes(label)) platforms.push(label);
     }

package/lib/git-hooks-path.mjs

@@ -0,0 +1,61 @@
+/**
+ * lib/git-hooks-path.mjs — wire a git repo's `core.hooksPath` to `.beads/hooks`
+ * so Construct's pre-commit secret-scan, policy gates, and the beads dispatcher
+ * activate.
+ *
+ * Project-scoped: it mutates the git config of the directory passed in, so it
+ * is owned by `construct init` (project scaffolding), never `construct install`
+ * (machine setup must not touch the cwd repo — ADR-0027 §3). The git default
+ * (`.git/hooks`, set or unset) is treated as "no active choice" and overwritten;
+ * a non-default custom hooksPath is left alone with a warning.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+export function ensureGitHooksPath({ cwd = process.cwd() } = {}) {
+  const hooksDir = path.join(cwd, '.beads', 'hooks');
+  if (!fs.existsSync(path.join(hooksDir, 'pre-commit'))) {
+    return { status: 'skipped', reason: 'no .beads/hooks/pre-commit in this directory' };
+  }
+  const inGit = spawnSync('git', ['rev-parse', '--is-inside-work-tree'], { cwd, stdio: 'pipe', encoding: 'utf8' });
+  if (inGit.status !== 0) {
+    return { status: 'skipped', reason: 'not a git working tree' };
+  }
+  const current = spawnSync('git', ['config', '--get', 'core.hooksPath'], { cwd, stdio: 'pipe', encoding: 'utf8' });
+  const currentValue = current.status === 0 ? (current.stdout || '').trim() : '';
+  const desired = '.beads/hooks';
+  if (currentValue === desired) {
+    return { status: 'ok', message: 'core.hooksPath already wired to .beads/hooks' };
+  }
+
+  // Treat the git default (`.git/hooks` or an absolute path to it) as
+  // equivalent to unset. A user who has accepted the default has not made an
+  // active choice that justifies "leave alone" semantics; without this branch
+  // an install that happens to land while `.git/hooks` is already in play
+  // leaves policy gates inactive permanently.
+
+  const isGitDefault =
+    !currentValue ||
+    currentValue === '.git/hooks' ||
+    currentValue === path.join(cwd, '.git', 'hooks') ||
+    currentValue.replace(/\/+$/, '').endsWith(`${path.sep}.git${path.sep}hooks`);
+  if (!isGitDefault) {
+    return {
+      status: 'warning',
+      message: `core.hooksPath is set to '${currentValue}'. Leaving alone. Set to '.beads/hooks' to activate Construct policy gates.`,
+    };
+  }
+  const result = spawnSync('git', ['config', 'core.hooksPath', desired], { cwd, stdio: 'pipe', encoding: 'utf8' });
+  if (result.status !== 0) {
+    return {
+      status: 'error',
+      message: `failed to set core.hooksPath: ${(result.stderr || '').trim() || 'unknown error'}`,
+    };
+  }
+  return {
+    status: 'set',
+    message: 'core.hooksPath set to .beads/hooks (activates pre-commit secret-scan + Construct policy gates + beads dispatcher)',
+  };
+}

package/lib/home-namespace.mjs

@@ -0,0 +1,60 @@
+/**
+ * lib/home-namespace.mjs — per-home derivation of local-service identifiers so
+ * isolated HOMEs (test sandboxes, multiple users on one machine, parallel CI)
+ * never collide on the same Postgres container/port or memory port (construct-lb7b).
+ *
+ * The canonical `construct-postgres`:54329 container and the memory :8765 port are
+ * singular per machine; two HOMEs sharing them clobber each other's data and
+ * fight over the port. Each identifier here is derived from a stable hash of the
+ * resolved home directory, so every HOME gets its own deterministic namespace.
+ *
+ * Explicit env overrides win (CONSTRUCT_PG_PORT, MEMORY_PORT, CONSTRUCT_PG_CONTAINER),
+ * so a pinned setup keeps its values. The LaunchAgent label stays singular — it is
+ * a machine-level guard, not a per-home resource.
+ */
+
+import { createHash } from 'node:crypto';
+import { homeDir } from './paths.mjs';
+
+const PG_PORT_BASE = 54329;
+const MEMORY_PORT_BASE = 8765;
+const PORT_SPAN = 2000;
+
+function digest(home) {
+  return createHash('sha256').update(home).digest('hex');
+}
+
+export function homeNamespaceSuffix(home = homeDir()) {
+  return digest(home).slice(0, 8);
+}
+
+// Distinct hash slices for the two ports so they do not move in lockstep across
+// homes (which would re-create collisions one base apart).
+
+function offsetFromSlice(home, start) {
+  return parseInt(digest(home).slice(start, start + 8), 16) % PORT_SPAN;
+}
+
+export function postgresPort(env = process.env, home = homeDir()) {
+  const override = env.CONSTRUCT_PG_PORT;
+  if (override && /^\d+$/.test(override)) return Number(override);
+  return PG_PORT_BASE + offsetFromSlice(home, 0);
+}
+
+export function memoryPort(env = process.env, home = homeDir()) {
+  const override = env.MEMORY_PORT;
+  if (override && /^\d+$/.test(override)) return Number(override);
+  return MEMORY_PORT_BASE + offsetFromSlice(home, 8);
+}
+
+export function postgresContainerName(env = process.env, home = homeDir()) {
+  return env.CONSTRUCT_PG_CONTAINER || `construct-postgres-${homeNamespaceSuffix(home)}`;
+}
+
+// The legacy singular identifiers prior versions wrote. The postgres-namespace
+// reconciliation (lib/reconcile/) uses these to detect state that predates the
+// per-home derivation.
+
+export const LEGACY_PG_CONTAINER = 'construct-postgres';
+export const LEGACY_PG_PORT = 54329;
+export const LEGACY_MEMORY_PORT = 8765;

package/lib/hooks/ci-status-check.mjs

@@ -2,17 +2,22 @@
 /**
  * lib/hooks/ci-status-check.mjs — UserPromptSubmit hook: inject remote CI status into agent context.
  *
- * Queries `gh run list --branch=<current> --limit=1` once per user prompt and,
- * if the last run on the current branch failed, prints a stderr line that the
- * agent will see in its next observation. Without this, an agent has no way
- * to know remote CI is red without explicitly running gh — which means failed
- * jobs go unnoticed until the user catches them. Non-blocking.
+ * Reads a 60s on-disk cache of the last `gh run list` result for the current
+ * branch and, when the cached conclusion is `failure`, emits a stderr line the
+ * agent sees in its next observation. The synchronous fast path does no
+ * subprocess spawning beyond a 50ms `git branch` probe — every cache miss is
+ * served by detaching a background refresher (stale-while-revalidate), so the
+ * UserPromptSubmit critical path stays under its 200ms budget regardless of
+ * `gh` / network latency. Without this hook, an agent has no way to know
+ * remote CI is red without explicitly running gh.
  *
- * Cached on disk for 60s so frequent prompts don't spam the gh API.
+ * The background refresher is `scripts/refresh-ci-status.mjs` invoked with
+ * `--branch=<name> --cwd=<dir> --cache=<path>`; it inherits no stdio and
+ * detaches so a slow `gh` invocation can't keep the hook process alive.
  * Skipped silently if gh is not installed, not authenticated, or the dir is
  * not a git repo.
  *
- * @p95ms 4000
+ * @p95ms 200
  * @maxBlockingScope none (UserPromptSubmit, non-blocking)
  *
  * @lifecycle UserPromptSubmit
@@ -20,13 +25,16 @@
  * @exits 0 = pass
  */
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync } from 'node:fs';
-import { execSync } from 'node:child_process';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { execSync, spawn } from 'node:child_process';
 import { homedir } from 'node:os';
-import { join, dirname } from 'node:path';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 const CACHE_PATH = join(homedir(), '.cx', 'ci-status-cache.json');
 const CACHE_TTL_MS = 60_000;
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REFRESHER = resolve(HERE, '..', '..', 'scripts', 'refresh-ci-status.mjs');
 
 let cwd = process.cwd();
 try {
@@ -34,12 +42,20 @@ try {
   if (input?.cwd) cwd = input.cwd;
 } catch {}
 
-function safeExec(cmd, opts = {}) {
-  try { return execSync(cmd, { cwd, stdio: ['ignore', 'pipe', 'ignore'], timeout: 3000, ...opts }).toString().trim(); }
-  catch { return null; }
+// 50ms hard timeout on `git branch --show-current`: bounded enough that even
+// a hung git invocation cannot blow the 200ms hook budget.
+
+function safeGitBranch() {
+  try {
+    return execSync('git branch --show-current', {
+      cwd,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 50,
+    }).toString().trim();
+  } catch { return null; }
 }
 
-const branch = safeExec('git branch --show-current');
+const branch = safeGitBranch();
 if (!branch) process.exit(0);
 
 const cacheKey = `${cwd}::${branch}`;
@@ -48,39 +64,45 @@ try { cache = JSON.parse(readFileSync(CACHE_PATH, 'utf8')); } catch {}
 const cached = cache[cacheKey];
 const now = Date.now();
 
-let conclusion = null;
-let runId = null;
-let runUrl = null;
+// Stale-while-revalidate: serve any cached value (even stale) on the
+// critical path, and detach a background refresher when the cache is stale
+// or absent. The first prompt against a never-cached branch sees nothing;
+// the second prompt (after the detached refresher has written) sees the
+// real status. That tradeoff buys a flat ~50ms p95.
 
-if (cached && (now - cached.fetchedAt) < CACHE_TTL_MS) {
-  conclusion = cached.conclusion;
-  runId = cached.runId;
-  runUrl = cached.runUrl;
-} else {
-  const json = safeExec(
-    `gh run list --branch=${JSON.stringify(branch)} --limit=1 --json conclusion,databaseId,url`,
-    { timeout: 4000 },
-  );
-  if (!json) process.exit(0);
+const isStale = !cached || (now - cached.fetchedAt) >= CACHE_TTL_MS;
+
+if (isStale && existsSync(REFRESHER)) {
   try {
-    const [run] = JSON.parse(json);
-    if (run) {
-      conclusion = run.conclusion;
-      runId = run.databaseId;
-      runUrl = run.url;
-      cache[cacheKey] = { conclusion, runId, runUrl, fetchedAt: now };
-      try {
-        mkdirSync(dirname(CACHE_PATH), { recursive: true });
-        writeFileSync(CACHE_PATH, JSON.stringify(cache));
-      } catch {}
-    }
+    const child = spawn(process.execPath, [
+      REFRESHER,
+      `--branch=${branch}`,
+      `--cwd=${cwd}`,
+      `--cache=${CACHE_PATH}`,
+    ], {
+      cwd,
+      detached: true,
+      stdio: 'ignore',
+    });
+    child.unref();
   } catch {}
 }
 
-if (conclusion === 'failure') {
+if (cached?.conclusion === 'failure') {
   process.stderr.write(
-    `[ci] Last CI run on branch '${branch}' FAILED (run ${runId}).\n  ${runUrl || ''}\n  Investigate with: gh run view ${runId} --log-failed\n  Do not stop the session until the failure is fixed or explicitly acknowledged (CONSTRUCT_STOP_OK_RED_CI=1).\n`,
+    `[ci] Last CI run on branch '${branch}' FAILED (run ${cached.runId}).\n  ${cached.runUrl || ''}\n  Investigate with: gh run view ${cached.runId} --log-failed\n  Do not stop the session until the failure is fixed or explicitly acknowledged (CONSTRUCT_STOP_OK_RED_CI=1).\n`,
   );
 }
 
+// First-prompt edge case: no cache exists yet AND we just kicked off the
+// refresher. We still exit 0 (silent). On the next prompt, the cache will
+// be populated and any failure surfaces.
+
+if (!cached) {
+  try {
+    mkdirSync(dirname(CACHE_PATH), { recursive: true });
+    if (!existsSync(CACHE_PATH)) writeFileSync(CACHE_PATH, '{}');
+  } catch {}
+}
+
 process.exit(0);

package/lib/hooks/config-protection.mjs

@@ -21,7 +21,7 @@
  *
  * @lifecycle PreToolUse
  * @matcher  Write|Edit|MultiEdit
- * @exits 0 = pass | 2 = block tool call
+ * @exits 0 = always, emits audit event on violation
  */
 import { readFileSync } from 'fs';
 import { execFileSync } from 'child_process';
@@ -90,10 +90,10 @@ async function emitEvent(type, category, summary) {
 const base = filePath.split('/').pop();
 if (PROTECTED.some(r => r.test(base)) && isTrackedInGit(filePath)) {
   process.stderr.write(
-    `[config-protection] The code quality rules are protected. Fix the code to meet the existing standards — don't weaken the rules.\nFile: ${filePath}\n`
+    `[config-protection] The code quality rules are protected. You are editing a tracked config file. Ensure you are not weakening rules just to bypass errors.\nFile: ${filePath}\n`
   );
-  await emitEvent('config.protection.violation', 'code-quality-config', `Blocked edit to code-quality-config: ${filePath}`);
-  process.exit(2);
+  await emitEvent('config.protection.violation', 'code-quality-config', `Edited code-quality-config: ${filePath}`);
+  process.exit(0);
 }
 
 if (META_FILES.some(r => r.test(filePath))) {

package/lib/hooks/orchestration-dispatch-guard.mjs

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/orchestration-dispatch-guard.mjs — backstop against solo-authoring an orchestrated deliverable.
+ *
+ * The orchestration_policy tool classifies a request into immediate / focused /
+ * orchestrated. An orchestrated verdict means the orchestrator must dispatch the
+ * specialist chain (cx-architect, cx-security, cx-devil-advocate, …) before
+ * authoring the deliverable — not write it solo. The persona instructs this, but
+ * instruction is not enforcement: this hook is the Claude-only barrier.
+ *
+ * Three roles, one file, branched on event + tool:
+ *  - PostToolUse on *orchestration_policy: record the verdict. orchestrated →
+ *    {pending:true,dispatched:false}; immediate/focused → cleared. Each new
+ *    classification resets state for the new request.
+ *  - PostToolUse on a dispatch tool (*orchestration_run, *worker_run, Task) →
+ *    {dispatched:true}: the chain is running, authoring is now legitimate.
+ *  - PreToolUse on Write|Edit|MultiEdit → block (exit 2) when a substantial
+ *    documentation/strategy deliverable is authored while pending && !dispatched.
+ *
+ * Scoped to documentation/strategy artifacts (.md outside the routine planning
+ * and tracking files), not code — solo code authoring is harder to separate
+ * from legitimate pre-dispatch scaffolding, so it is left to the persona
+ * contract rather than over-blocked here. Only the deterministic
+ * orchestrated-but-not-dispatched case blocks. Fails open on any internal error.
+ *
+ * @p95ms 8
+ * @maxBlockingScope orchestrated deliverable authoring without prior dispatch
+ *
+ * @lifecycle PreToolUse, PostToolUse
+ * @matcher Write|Edit|MultiEdit, mcp__.*__orchestration_policy, mcp__.*__orchestration_run, mcp__.*__worker_run, Task
+ * @exits 0 = pass · 2 = block (author after dispatch instead)
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join, basename, relative, isAbsolute } from 'path';
+
+const STALE_MS = 2 * 60 * 60 * 1000;
+const SUBSTANTIAL_CHARS = 1500;
+const SUBSTANTIAL_LINES = 40;
+
+let input = {};
+try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
+
+const event = input?.hook_event_name || '';
+const toolName = input?.tool_name || '';
+const cwd = input?.cwd || process.cwd();
+
+function statePath(root) {
+  return join(root, '.cx', 'runtime', 'orchestration-guard.json');
+}
+
+function readState(root) {
+  try { return JSON.parse(readFileSync(statePath(root), 'utf8')); } catch { return null; }
+}
+
+function writeState(root, state) {
+  try {
+    mkdirSync(join(root, '.cx', 'runtime'), { recursive: true });
+    writeFileSync(statePath(root), JSON.stringify(state));
+  } catch { /* fail open */ }
+}
+
+// The marker only lives inside an already-initialized construct project; never
+// seed .cx into a project that does not have it.
+
+function hasCx(root) {
+  return existsSync(join(root, '.cx'));
+}
+
+function isPolicyTool(name) {
+  return /orchestration_policy$/.test(name);
+}
+
+function isDispatchTool(name) {
+  return name === 'Task' || /orchestration_run$/.test(name) || /worker_run$/.test(name);
+}
+
+// PostToolUse: a classification verdict updates the marker. orchestrated arms
+// the guard; immediate/focused disarms it. The verdict text can be nested in an
+// MCP content envelope, so match against the stringified response.
+
+if (event === 'PostToolUse' && isPolicyTool(toolName)) {
+  if (!hasCx(cwd)) process.exit(0);
+  const blob = JSON.stringify(input?.tool_response ?? '').replace(/\\/g, '');
+  const orchestrated = /"track"\s*:\s*"orchestrated"/.test(blob);
+  if (orchestrated) writeState(cwd, { pending: true, dispatched: false, ts: Date.now() });
+  else writeState(cwd, { pending: false, ts: Date.now() });
+  process.exit(0);
+}
+
+if (event === 'PostToolUse' && isDispatchTool(toolName)) {
+  if (!hasCx(cwd)) process.exit(0);
+  const state = readState(cwd);
+  if (state?.pending) writeState(cwd, { ...state, dispatched: true });
+  process.exit(0);
+}
+
+// PreToolUse on an authoring tool: block only the deterministic failure — a
+// substantial documentation/strategy deliverable authored while a fresh
+// orchestrated verdict is pending and no dispatch has run.
+
+if (event === 'PreToolUse' && /^(Write|Edit|MultiEdit)$/.test(toolName)) {
+  if (!hasCx(cwd)) process.exit(0);
+  const state = readState(cwd);
+  if (!state?.pending || state?.dispatched) process.exit(0);
+  if (typeof state.ts === 'number' && Date.now() - state.ts > STALE_MS) process.exit(0);
+
+  const ti = input?.tool_input || {};
+  const filePath = ti.file_path || ti.filePath || '';
+  if (!isDeliverableArtifact(filePath, cwd)) process.exit(0);
+
+  const authored = authoredContent(toolName, ti);
+  const lineCount = authored ? authored.split('\n').length : 0;
+  if (authored.length < SUBSTANTIAL_CHARS && lineCount < SUBSTANTIAL_LINES) process.exit(0);
+
+  process.stderr.write(
+    '⛔ orchestration-dispatch-guard: orchestration_policy classified this request as ORCHESTRATED, '
+    + 'but no specialist dispatch (orchestration_run / Task) has run yet.\n'
+    + 'You may not author the deliverable solo. Emit the task-packet and dispatch the chain '
+    + '(e.g. cx-architect owns structure, cx-security challenges the credential/state model, '
+    + 'cx-devil-advocate pressure-tests the approach), then synthesize their verdicts in Construct\'s voice.\n'
+    + 'If this write IS post-dispatch synthesis, run the dispatch tool first so the guard clears.\n',
+  );
+  process.exit(2);
+}
+
+process.exit(0);
+
+// A deliverable is a markdown doc/strategy artifact outside the routine
+// planning and tracking files. Code paths are intentionally excluded — see
+// the file header.
+
+function isDeliverableArtifact(filePath, root) {
+  if (!filePath || !/\.mdx?$/.test(filePath)) return false;
+  let rel = filePath;
+  try { rel = isAbsolute(filePath) ? relative(root, filePath) : filePath; } catch { rel = filePath; }
+  rel = rel.replace(/\\/g, '/');
+  if (rel.startsWith('..')) return false;
+  if (rel.startsWith('.cx/')) return false;
+  const base = basename(rel).toLowerCase();
+  const routine = new Set(['plan.md', 'changelog.md', 'readme.md', 'agents.md', 'contributing.md']);
+  if (routine.has(base)) return false;
+  if (rel.startsWith('.cx/handoffs/') || rel.includes('/handoffs/')) return false;
+  return true;
+}
+
+function authoredContent(name, ti) {
+  if (name === 'Write') return String(ti.content ?? '');
+  if (name === 'Edit') return String(ti.new_string ?? '');
+  if (name === 'MultiEdit' && Array.isArray(ti.edits)) {
+    return ti.edits.map((e) => String(e?.new_string ?? '')).join('\n');
+  }
+  return '';
+}

package/lib/hooks/pre-push-gate.mjs

@@ -116,18 +116,27 @@ if (isGhPrCreate || isGhPrEdit) {
   echo();
 }
 
-// git push: refuse claude/* unconditionally.
-
-if (/\bclaude\//.test(command)) {
+// git push: refuse agent-prefixed branches. Match the branch name(s) actually
+// being pushed — the current branch plus any explicit refspec — anchored at the
+// start, so a `.claude/agents` path argument anywhere in the command does not
+// trip the gate.
+
+const AGENT_BRANCH_PREFIX = /^(claude|cursor|copilot|codex|aider|devin)\//;
+const pushTargets = [currentBranch()];
+const pushArgs = (command.match(/\bgit\s+push\b([^|;&\n]*)/)?.[1] || '')
+  .trim().split(/\s+/).filter((a) => a && !a.startsWith('-'));
+for (const arg of pushArgs.slice(1)) pushTargets.push(arg.split(':').pop());
+
+if (pushTargets.some((b) => b && AGENT_BRANCH_PREFIX.test(b))) {
   process.stderr.write(
-    `[pre-push-gate] Refusing to push a claude/* branch to remote (user policy).\n` +
+    `[pre-push-gate] Refusing to push an agent-prefixed branch to remote (user policy).\n` +
     `  Use a non-agent branch name.\n`,
   );
   emitRoleEvent({
     type: 'push_gate.fail',
-    summary: 'claude/* branch push refused',
+    summary: 'agent-prefixed branch push refused',
     hookInput: input,
-    context: { command },
+    context: { command, pushTargets },
   });
   process.exit(2);
 }

package/lib/hooks/session-reflect.mjs

@@ -22,7 +22,11 @@
 import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 
-const HARD_BUDGET_MS = 500;
+// 500ms keeps the per-turn Stop-hook tax small (ADR-0029): reflection is
+// best-effort and a LanceDB write that overruns the budget is left to the
+// embed daemon's reconcile to backfill. CONSTRUCT_REFLECT_BUDGET_MS raises the
+// ceiling where the write must complete deterministically (slow disks, tests).
+const HARD_BUDGET_MS = Number(process.env.CONSTRUCT_REFLECT_BUDGET_MS) || 500;
 const startedAt = Date.now();
 
 // Opt-out before any heavy work — the env check is cheaper than parsing input.

package/lib/hooks/stop-notify.mjs

@@ -155,8 +155,16 @@ const costLogPath = join(home, '.cx', 'session-cost.jsonl');
 const lastAgentPath = join(home, '.cx', 'last-agent.json');
 const checkpointPath = join(home, '.cx', 'transcript-checkpoints.json');
 
+// Consume-clear like warn-flags/files-changed below: a TS result is reported
+// once, not re-fired on every subsequent no-op Stop. stop-typecheck rewrites
+// the file each turn it actually runs.
 let tsResult = 'unchecked';
-try { tsResult = existsSync(tsResultPath) ? readFileSync(tsResultPath, 'utf8').trim() : 'unchecked'; } catch { /* non-critical */ }
+try {
+  if (existsSync(tsResultPath)) {
+    tsResult = readFileSync(tsResultPath, 'utf8').trim() || 'unchecked';
+    writeFileSync(tsResultPath, 'unchecked');
+  }
+} catch { /* non-critical */ }
 
 let warnings = [];
 try {
@@ -326,25 +334,32 @@ try {
   }
 } catch { /* review is best-effort */ }
 
+// Stop fires per-turn, so a desktop banner only earns the interruption when the
+// turn produced something actionable: files changed or a warning to review.
+// A bare "TS OK" (the sticky-pass default on a no-op turn) is noise — the ledger
+// and session bookkeeping above still run; only the banner is suppressed.
 const platform = process.platform;
-try {
-  if (platform === 'darwin') {
-    const escaped = body.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
-    const titleEsc = title.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-    execSync(`osascript -e 'display notification "${escaped}" with title "${titleEsc}"'`, {
-      timeout: 5000,
-      stdio: 'pipe',
-    });
-  } else if (platform === 'linux') {
-    execSync(`notify-send "${title}" "${body.replace(/"/g, '\\"')}"`, {
-      timeout: 5000,
-      stdio: 'pipe',
-    });
-  } else {
+const shouldNotify = (hasWarnings || fileCount > 0) && Boolean(body);
+if (shouldNotify) {
+  try {
+    if (platform === 'darwin') {
+      const escaped = body.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
+      const titleEsc = title.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+      execSync(`osascript -e 'display notification "${escaped}" with title "${titleEsc}"'`, {
+        timeout: 5000,
+        stdio: 'pipe',
+      });
+    } else if (platform === 'linux') {
+      execSync(`notify-send "${title}" "${body.replace(/"/g, '\\"')}"`, {
+        timeout: 5000,
+        stdio: 'pipe',
+      });
+    } else {
+      process.stderr.write(`[stop-notify] ${title}: ${body}\n`);
+    }
+  } catch {
     process.stderr.write(`[stop-notify] ${title}: ${body}\n`);
   }
-} catch {
-  process.stderr.write(`[stop-notify] ${title}: ${body}\n`);
 }
 
 process.exit(0);

package/lib/hooks/stop-typecheck.mjs

@@ -31,8 +31,11 @@ const pending = existsSync(tcPath)
   ? readFileSync(tcPath, 'utf8').split('\n').filter(Boolean)
   : [];
 
+// No files queued means no typecheck ran this turn — record 'unchecked', not a
+// misleading 'pass'. A stale 'pass' here is what made stop-notify fire a bare
+// "TS OK" banner on every no-op turn.
 if (pending.length === 0) {
-  try { writeFileSync(tsResultPath, 'pass'); } catch { /* best effort */ }
+  try { writeFileSync(tsResultPath, 'unchecked'); } catch { /* best effort */ }
   process.exit(0);
 }
 
@@ -55,8 +58,10 @@ function findTsConfig(startDir) {
 const startDir = dirname(pending[0]);
 const tsconfig = findTsConfig(startDir);
 
+// Files were edited but no tsconfig governs them — the typecheck couldn't run,
+// so the honest state is 'unchecked', not 'pass'.
 if (!tsconfig) {
-  try { writeFileSync(tsResultPath, 'pass'); } catch { /* best effort */ }
+  try { writeFileSync(tsResultPath, 'unchecked'); } catch { /* best effort */ }
   process.exit(0);
 }