@geraldmaron/construct 1.0.20 → 1.0.23

package/lib/document-ingest.mjs

@@ -14,7 +14,7 @@ import { syncFileStateToSql } from './storage/sync.mjs';
 import { stampFrontmatter } from './doc-stamp.mjs';
 import { KNOWLEDGE_ROOT, KNOWLEDGE_SUBDIRS } from './knowledge/layout.mjs';
 import { loadProjectConfig } from './config/project-config.mjs';
-import { resolveIngestStrategy, INGEST_STRATEGIES } from './ingest/strategy.mjs';
+import { resolveIngestStrategy, INGEST_STRATEGIES, INGEST_ORCHESTRATION_STRATEGIES } from './ingest/strategy.mjs';
 import { extractViaProvider } from './ingest/provider-extract.mjs';
 
 const DEFAULT_TARGET_DIR = '.cx/knowledge/internal';
@@ -167,6 +167,7 @@ export async function ingestDocuments(inputPaths, {
   strict = false,
   highFidelity = true,
   strategy = null,
+  orchestration = null,
   env = process.env,
 } = {}) {
   if (!Array.isArray(inputPaths) || inputPaths.length === 0) {
@@ -182,7 +183,7 @@ export async function ingestDocuments(inputPaths, {
   }
 
   const { config } = loadProjectConfig(cwd, env);
-  const resolvedStrategy = resolveIngestStrategy({ config, env, override: strategy });
+  const resolvedStrategy = resolveIngestStrategy({ config, env, override: strategy, orchestrationOverride: orchestration, cwd });
 
   const results = [];
   let totalDrops = 0;
@@ -266,9 +267,11 @@ export async function ingestDocuments(inputPaths, {
     ingestion: {
       strategy: resolvedStrategy.strategy,
       fallback: resolvedStrategy.fallback,
+      orchestration: resolvedStrategy.orchestration,
       model: resolvedStrategy.model,
       provider: resolvedStrategy.provider,
       fallbackApplied,
+      execution: resolvedStrategy.execution,
     },
   };
 }
@@ -282,6 +285,7 @@ export async function runIngestCli(argv = process.argv.slice(2), { cwd = process
   let strict = false;
   let highFidelity = true;
   let strategy = null;
+  let orchestration = null;
 
   for (const arg of argv) {
     if (arg.startsWith('--out=')) outputPath = arg.split('=').slice(1).join('=');
@@ -289,6 +293,7 @@ export async function runIngestCli(argv = process.argv.slice(2), { cwd = process
     else if (arg.startsWith('--target=')) target = arg.split('=').slice(1).join('=');
     else if (arg.startsWith('--strategy=')) strategy = arg.split('=').slice(1).join('=');
     else if (arg === '--strategy') strategy = '';
+    else if (arg.startsWith('--orchestration=')) orchestration = arg.split('=').slice(1).join('=');
     else if (arg === '--sync') sync = true;
     else if (arg === '--strict') strict = true;
     else if (arg === '--legacy-extractor') highFidelity = false;
@@ -299,8 +304,9 @@ export async function runIngestCli(argv = process.argv.slice(2), { cwd = process
   if (inputs.length === 0) {
     throw new Error(
       `Usage: construct ingest <file-or-dir> [more paths] [--out=FILE] [--out-dir=DIR] ` +
-      `[--target=sibling|knowledge/<subdir>] [--strategy=adapter|provider] [--sync] [--strict] [--legacy-extractor]\n` +
+      `[--target=sibling|knowledge/<subdir>] [--strategy=adapter|provider] [--orchestration=prompt-only|orchestrated] [--sync] [--strict] [--legacy-extractor]\n` +
       `  --strategy: extraction strategy override (adapter = local extractors; provider = configured provider/model)\n` +
+      `  --orchestration: prompt-only (deterministic extraction) or orchestrated (engage the specialist chain)\n` +
       `  --strict: exit non-zero if any extraction drops occur\n` +
       `  --legacy-extractor: use the pre-docling regex extractor (lower fidelity)\n` +
       `  knowledge subdirs: ${KNOWLEDGE_SUBDIRS.join(', ')}`,
@@ -309,6 +315,9 @@ export async function runIngestCli(argv = process.argv.slice(2), { cwd = process
   if (strategy !== null && strategy !== '' && !INGEST_STRATEGIES.includes(strategy)) {
     throw new Error(`Unsupported strategy: ${strategy}. Valid strategies: ${INGEST_STRATEGIES.join(', ')}`);
   }
+  if (orchestration !== null && !INGEST_ORCHESTRATION_STRATEGIES.includes(orchestration)) {
+    throw new Error(`Unsupported orchestration: ${orchestration}. Valid values: ${INGEST_ORCHESTRATION_STRATEGIES.join(', ')}`);
+  }
   const knowledgeTargets = KNOWLEDGE_SUBDIRS.map((s) => `knowledge/${s}`);
   if (!['sibling', ...knowledgeTargets].includes(target)) {
     throw new Error(
@@ -316,5 +325,5 @@ export async function runIngestCli(argv = process.argv.slice(2), { cwd = process
     );
   }
 
-  return ingestDocuments(inputs, { cwd, outputPath, outputDir, target, sync, strict, highFidelity, strategy: strategy || null, env });
+  return ingestDocuments(inputs, { cwd, outputPath, outputDir, target, sync, strict, highFidelity, strategy: strategy || null, orchestration: orchestration || null, env });
 }

package/lib/embed/daemon.mjs

@@ -1077,7 +1077,7 @@ this.#scheduler.register(
                 method: 'POST',
                 headers: {
                   Authorization: `Bearer ${orKey}`, 'content-type': 'application/json',
-                  'HTTP-Referer': 'https://github.com/construct',
+                  'HTTP-Referer': 'https://github.com/geraldmaron/construct',
                 },
                 body: JSON.stringify({
                   model: modelId.replace(/^openrouter\//, ''),

package/lib/embed/inbox.mjs

@@ -296,17 +296,22 @@ export class InboxWatcher {
   #rootDir;
   #env;
   #cwd;
+  #prepareIntakeFn;
 
   /**
    * @param {object} opts
    * @param {string} opts.rootDir - Root dir for observation store + state file
    * @param {object} [opts.env]   - Env override (default: process.env)
    * @param {string} [opts.cwd]   - Working dir for ingest output (default: rootDir)
+   * @param {Function} [opts.prepareIntakeFn] - Override for prepareIntakeForIngestedFile
+   *   (test seam): receives the same args; returns null/throws to simulate a failed
+   *   packet creation so tests can assert the manifest-gate behavior (construct-k4bg).
    */
-  constructor({ rootDir, env = process.env, cwd } = {}) {
+  constructor({ rootDir, env = process.env, cwd, prepareIntakeFn } = {}) {
     this.#rootDir = rootDir;
     this.#env = env;
     this.#cwd = cwd ?? rootDir;
+    this.#prepareIntakeFn = prepareIntakeFn ?? prepareIntakeForIngestedFile;
   }
 
   /**
@@ -423,13 +428,15 @@ export class InboxWatcher {
               extractedText,
             });
 
-            // Queue an intake packet so the agent can triage the new
-            // signal against the existing corpus. Failure here is
-            // non-fatal — ingest already succeeded; the queue is a
-            // best-effort handoff, not the ingestion's source of truth.
+            // Queue an intake packet so the agent can triage the new signal
+            // against the existing corpus. Failure here is non-fatal — ingest
+            // already succeeded; the queue is a best-effort handoff, not the
+            // ingestion's source of truth.
+
             let intakeId = null;
+            let intakeFailed = false;
             try {
-              const intakeResult = await prepareIntakeForIngestedFile({
+              const intakeResult = await this.#prepareIntakeFn({
                 rootDir: this.#rootDir,
                 ingestedFile: {
                   sourcePath: candidate.path,
@@ -441,7 +448,9 @@ export class InboxWatcher {
                 env: this.#env,
               });
               intakeId = intakeResult?.id || null;
+              if (!intakeId) intakeFailed = true;
             } catch (err) {
+              intakeFailed = true;
               if (this.#env.CONSTRUCT_DEBUG_INTAKE === '1') {
                 process.stderr.write(`[inbox] intake queue write failed for ${candidate.path}: ${err.message}\n`);
               }
@@ -449,7 +458,14 @@ export class InboxWatcher {
 
             state[key] = { mtimeMs: candidate.mtimeMs, processedAt: new Date().toISOString(), outputPath: fileResult.outputPath };
 
-            if (manifestEnabled && candidateSha) {
+            // The dedup manifest entry is the signal that `construct intake
+            // process` uses to skip already-handled files. Recording it when
+            // packet creation failed strands the file: explicit `intake process`
+            // reports "skipped (unchanged)" while `intake list` is empty, with
+            // no path back. Record only on a successful intake id so a failed
+            // auto-ingest stays retriable via the explicit path (construct-k4bg).
+
+            if (manifestEnabled && candidateSha && intakeId && !intakeFailed) {
               try {
                 recordFile(this.#rootDir, candidateSha, {
                   sourcePath: candidate.path,
@@ -462,6 +478,8 @@ export class InboxWatcher {
                   process.stderr.write(`[inbox] manifest record failed for ${candidate.path}: ${err.message}\n`);
                 }
               }
+            } else if (manifestEnabled && intakeFailed) {
+              process.stderr.write(`[inbox] ${candidate.path}: ingest succeeded but intake-packet creation failed; rerun \`construct intake process\` to retry.\n`);
             }
 
             processed.push({ path: candidate.path, outputPath: fileResult.outputPath, docsPath, characters: fileResult.characters, knowledgeSubdir, intakeId, dedupHash: candidateSha });

package/lib/embedded-contract/triage.mjs

@@ -16,6 +16,7 @@ import { classifyRdIntake } from '../intake/classify.mjs';
 import { getDeploymentMode } from '../deployment-mode.mjs';
 import { roleMap, roleRationale, skillsForChain, contractFacts } from './role-facts.mjs';
 import { workflowTypeForIntake } from './workflow-defs.mjs';
+import { resolveExecution } from './execution.mjs';
 
 const CONFIDENCE_FLOOR = 0.6;
 
@@ -46,7 +47,7 @@ function buildRiskFactors(triage) {
  * @returns {object}
  */
 export function recommendPlan(request = {}, { env = process.env, cwd = process.cwd() } = {}) {
-  const { input = '', sourcePath = '', artifactType, availableRoles, profile = null, ingestion = null } = request;
+  const { input = '', sourcePath = '', artifactType, availableRoles, profile = null, ingestion = null, host, hostModel, hostProvider, constructStrategy = 'auto' } = request;
   const warnings = [];
 
   // Surface extraction provenance and flag low-yield/truncated inputs so a
@@ -109,6 +110,26 @@ export function recommendPlan(request = {}, { env = process.env, cwd = process.c
   if (canExecute) nextStepOptions.push({ action: 'invoke-workflow', description: 'Invoke the recommended role chain as an embedded workflow.' });
   if (!canExecute) nextStepOptions.push({ action: 'clarify', description: 'Request more detail; classification confidence is low or unknown.' });
 
+  const suggestedWorkflowType = workflowTypeForIntake(triage.intakeType);
+
+  // Execution preview: forecast the executionMode an invocation of the suggested
+  // workflow would resolve to, but only when the host supplies context — absent
+  // it, forcing a model resolution on every triage call would be wasteful and
+  // the preview would be uninformative. null keeps the field parity-stable.
+  let execution = null;
+  if (suggestedWorkflowType && (hostModel || hostProvider || (constructStrategy && constructStrategy !== 'auto'))) {
+    const e = resolveExecution({ workflowType: suggestedWorkflowType, requestedStrategy: constructStrategy, host, hostModel, hostProvider }, { env, cwd });
+    execution = {
+      executionMode: e.executionMode,
+      effectiveStrategy: e.effectiveStrategy,
+      requestedStrategy: e.requestedStrategy,
+      constructCapabilitiesActive: e.constructCapabilitiesActive,
+      degraded: e.degraded,
+      degradationReason: e.degradationReason,
+      semantics: e.semantics,
+    };
+  }
+
   return {
     classification: { intakeType: triage.intakeType, rdStage: triage.rdStage },
     ingestion,
@@ -117,7 +138,8 @@ export function recommendPlan(request = {}, { env = process.env, cwd = process.c
     primaryOwner,
     recommendedAction: triage.recommendedAction,
     recommendedChain: chain,
-    suggestedWorkflowType: workflowTypeForIntake(triage.intakeType),
+    suggestedWorkflowType,
+    execution,
     roleRationale: rationale,
     suggestedSkills,
     evidenceRequirements,

package/lib/embedded-contract/workflow-invoke.mjs

@@ -26,6 +26,7 @@ import { recordApprovalRequest } from '../roles/approval-surface.mjs';
 import { getWorkflowDef, WORKFLOW_TYPES } from './workflow-defs.mjs';
 import { roleMap, roleRationale, skillsForChain, contractFacts } from './role-facts.mjs';
 import { resolveEmbeddedModel } from './model-resolve.mjs';
+import { resolveExecution } from './execution.mjs';
 import { resolveWriteGate, newTraceId, DEFAULT_APPROVAL_MODE } from './audit.mjs';
 
 const VALID_STRATEGIES = ['auto', 'explicit', 'constrained'];
@@ -91,6 +92,7 @@ function errorResult({ workflowId, traceId, approvalMode, code, message, warning
  * @param {string} [request.host]
  * @param {string} [request.hostModel]
  * @param {string} [request.hostProvider]
+ * @param {string} [request.constructStrategy]  orchestrated | prompt-only | auto (execution mode)
  * @param {object} [opts]   { env, cwd }
  * @returns {Promise<object>}
  */
@@ -98,6 +100,7 @@ export async function invokeWorkflow(request = {}, { env = process.env, cwd = pr
   const {
     workflowType, context = {}, roleStrategy = 'auto', requestedRoles,
     approvalMode, trace = true, host, hostModel, hostProvider, ingestion = null,
+    constructStrategy = 'auto',
   } = request;
   const warnings = [];
   if (ingestion) {
@@ -129,6 +132,23 @@ export async function invokeWorkflow(request = {}, { env = process.env, cwd = pr
   );
   for (const w of modelWarnings) warnings.push(`model-resolution: ${w}`);
 
+  // The execution-capability contract reports the PLANNED executionMode for this
+  // run (descriptive, not enforced — ADR-0019). Construct returns a plan; the
+  // host runtime executes it, so this never claims observed specialist execution.
+  const executionData = resolveExecution(
+    { workflowType, requestedStrategy: constructStrategy, host, hostModel, hostProvider, requestedTier: def.tier },
+    { env, cwd },
+  );
+  const execution = {
+    executionMode: executionData.executionMode,
+    effectiveStrategy: executionData.effectiveStrategy,
+    requestedStrategy: executionData.requestedStrategy,
+    constructCapabilitiesActive: executionData.constructCapabilitiesActive,
+    degraded: executionData.degraded,
+    degradationReason: executionData.degradationReason,
+    semantics: executionData.semantics,
+  };
+
   const primaryOwner = selectedRoles[0];
   const facts = contractFacts(primaryOwner);
   const skillsApplied = skillsForChain(selectedRoles, map);
@@ -204,6 +224,7 @@ export async function invokeWorkflow(request = {}, { env = process.env, cwd = pr
     roleRationale: rationale,
     skillsApplied,
     modelResolution,
+    execution,
     outputs,
     recommendations,
     evidence: { requirements: facts.evidenceRequirements, satisfied, missing: missingEvidence, traceId },

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);