@geraldmaron/construct 1.4.2 → 1.5.0

package/lib/hooks/agent-tracker.mjs

@@ -77,11 +77,17 @@ try {
   const cxDir = doctorRoot();
   mkdirSync(cxDir, { recursive: true });
   
-  // Update last-agent files for coordination (shared + per-agent)
-  const agentEntry = { agent: agentName, coordination: 'tracker-plus-plan', ts: new Date().toISOString(), outcome, description: description.slice(0, 200) };
+  // Update last-agent files for coordination (shared + per-agent). agentId is
+  // best-effort (null on hosts that don't populate it on this event) — it lets
+  // guard-bash's role-fence check prove that a LATER command's own agent_id
+  // is the same subagent this dispatch was for, rather than fencing anyone
+  // riding a fresh timestamp (construct-7164).
+  const agentEntry = { agent: agentName, agentId: input?.agent_id ?? null, coordination: 'tracker-plus-plan', ts: new Date().toISOString(), outcome, description: description.slice(0, 200) };
   writeFileSync(join(cxDir, 'last-agent.json'), JSON.stringify(agentEntry));
-  // Per-agent file prevents one agent dispatch from resetting another's fence window
-  const safeName = agentName.replace(/[^a-z0-9._-]/gi, '_');
+  // Per-agent file prevents one agent dispatch from resetting another's fence
+  // window. Keyed by persona id with the cx- prefix stripped, matching
+  // guard-bash's CONSTRUCT_AGENT_ID lookup (construct-diq1).
+  const safeName = agentName.replace(/^cx-/, '').replace(/[^a-z0-9._-]/gi, '_');
   writeFileSync(join(cxDir, `last-agent-${safeName}.json`), JSON.stringify(agentEntry));
   
   // Per-project agent log (was ~/.cx/agent-log.jsonl which mixed every

package/lib/hooks/edit-guard.mjs

@@ -41,8 +41,8 @@ const cwd = input?.cwd || process.cwd();
 function absOf(p) { return p.startsWith('/') ? p : resolve(cwd, p); }
 
 // Role-fence check: if the most recently dispatched persona is one we manage
-// (cx-sre, cx-qa, cx-security, cx-docs-keeper) and the dispatch is fresh,
-// emit an advisory stderr warning when the edit target is outside the fence.
+// (cx-operations, cx-qa, cx-security) and the dispatch is fresh, emit an
+// advisory stderr warning when the edit target is outside the fence.
 // Hard-block only when the fence returns "outside-fence" (default-deny case);
 // "needs-approval" routes to existing commit-approval flow.
 
@@ -54,7 +54,7 @@ if ((toolName === 'Edit' || toolName === 'Write' || toolName === 'MultiEdit') &&
       const lastTs = last?.ts ? Date.parse(last.ts) : 0;
       const fresh = lastTs && (Date.now() - lastTs) < 10 * 60 * 1000;
       const id = String(last?.agent || '').replace(/^cx-/, '');
-      const ONBOARDED = new Set(['sre', 'qa', 'security', 'docs-keeper']);
+      const ONBOARDED = new Set(['operations', 'qa', 'security']);
       const targetPath = ti.file_path || ti.path || '';
       if (fresh && ONBOARDED.has(id) && targetPath) {
         const { checkAction } = await import('../roles/fence.mjs');

package/lib/hooks/graph-impact-advisory.mjs

@@ -41,13 +41,13 @@ if (!CODE_RE.test(rel)) process.exit(0);
 const stale = checkGraphStaleness(cwd);
 if (stale.stale) {
   process.stderr.write(
-    `[graph-impact] dependency graph stale (${stale.staleReason}). Run \`construct graph build\` before trusting impact output.\n`,
+    `[graph-impact] dependency graph stale (${stale.staleReason}). Run \`construct matrix build\` before trusting impact output.\n`,
   );
 }
 
 const impact = computeImpact({ rootDir: cwd, changedFiles: [rel] });
 if (!impact.graphPresent) {
-  process.stderr.write('[graph-impact] no .cx/graph/ present — run `construct graph build` to enable test-impact advisories.\n');
+  process.stderr.write('[graph-impact] no .cx/graph/ present — run `construct matrix build` to enable test-impact advisories.\n');
   process.exit(0);
 }
 

package/lib/hooks/guard-bash.mjs

@@ -57,9 +57,15 @@ const WARN_PATTERNS = [
   },
 ];
 
-async function getCommand() {
+// agent_id is Claude Code's own subagent marker: present only when this
+// invocation is running inside a subagent's own tool call, absent for
+// main-thread (orchestrator) calls. It is the actor-identity signal the
+// role-fence check below uses to prove WHO is issuing THIS command, instead
+// of trusting how recently some persona was dispatched elsewhere (construct-7164).
+
+async function getInvocation() {
   const fromEnv = process.env.TOOL_INPUT_COMMAND;
-  if (fromEnv) return fromEnv;
+  if (fromEnv) return { command: fromEnv, agentId: null };
 
   return new Promise((resolve) => {
     let data = '';
@@ -68,16 +74,19 @@ async function getCommand() {
     rl.on('close', () => {
       try {
         const parsed = JSON.parse(data);
-        resolve(parsed?.tool_input?.command ?? parsed?.command ?? '');
+        resolve({
+          command: parsed?.tool_input?.command ?? parsed?.command ?? '',
+          agentId: parsed?.agent_id ?? null,
+        });
       } catch (err) {
         logHookFailure({ hook: 'guard-bash', err, phase: 'parse' });
-        resolve('');
+        resolve({ command: '', agentId: null });
       }
     });
   });
 }
 
-const command = await getCommand();
+const { command, agentId: currentAgentId } = await getInvocation();
 
 if (!command) process.exit(0);
 
@@ -94,10 +103,21 @@ for (const { pattern, reason } of WARN_PATTERNS) {
   }
 }
 
-// Role-fence check: if the most recently dispatched persona is one we manage
-// and the dispatch is fresh, evaluate the command against the persona's
-// fence. git commit/push are always commit/push actions; bd ... maps to
-// allowedCommands prefix-match; everything else is the bash action.
+// Role-fence check: evaluate the command against a persona's fence, but only
+// when the CURRENT invocation's actor identity is verifiably that persona —
+// recency of a past dispatch is not proof of who is issuing THIS command
+// (construct-7164: an orchestrator's or a different subagent's own bash
+// calls were getting fenced by a persona dispatched minutes earlier
+// elsewhere). Two identity signals are trusted: CONSTRUCT_AGENT_ID, an
+// explicit self-declaration some hosts set before invoking commands as a
+// given persona; and agent_id, Claude Code's own per-subagent marker, which
+// is guaranteed absent for main-thread calls. The shared last-agent.json
+// (no identity attached) can only corroborate a dispatch already proven by
+// agent_id — it is never sufficient on its own. git commit/push are always
+// commit/push actions; bd ... maps to allowedCommands prefix-match;
+// everything else is the bash action.
+
+const FENCE_WINDOW_MS = 5 * 60 * 1000;
 
 if (process.env.CONSTRUCT_ROLES !== 'off') {
   try {
@@ -105,24 +125,30 @@ if (process.env.CONSTRUCT_ROLES !== 'off') {
     const id = String(process.env.CONSTRUCT_AGENT_ID || '').replace(/^cx-/, '');
     let agentData = null;
 
-    // Prefer per-agent timestamp file (prevents cross-agent fence window reset)
+    // Self-declared identity: the per-agent file is keyed by the same id the
+    // current invocation is claiming, so this match is identity-comparable
+    // by construction.
     if (id) {
       const perAgentPath = join(cxDir, `last-agent-${id.replace(/[^a-z0-9._-]/gi, '_')}.json`);
       if (existsSync(perAgentPath)) {
         agentData = JSON.parse(readFileSync(perAgentPath, 'utf8'));
       }
     }
-    // Fall back to shared last-agent.json
-    if (!agentData) {
+    // No self-declared id: only trust the shared dispatch record when the
+    // CURRENT invocation's own agent_id matches the one recorded at dispatch
+    // time, proving this is the SAME subagent call rather than a different
+    // actor riding a fresh timestamp.
+    if (!agentData && currentAgentId) {
       const sharedPath = join(cxDir, 'last-agent.json');
       if (existsSync(sharedPath)) {
-        agentData = JSON.parse(readFileSync(sharedPath, 'utf8'));
+        const shared = JSON.parse(readFileSync(sharedPath, 'utf8'));
+        if (shared?.agentId && shared.agentId === currentAgentId) agentData = shared;
       }
     }
 
     if (agentData) {
       const lastTs = agentData?.ts ? Date.parse(agentData.ts) : 0;
-      const fresh = lastTs && (Date.now() - lastTs) < 10 * 60 * 1000;
+      const fresh = lastTs && (Date.now() - lastTs) < FENCE_WINDOW_MS;
       const personaId = id || String(agentData?.agent || '').replace(/^cx-/, '');
       if (fresh && personaId) {
         const { isOnboarded } = await import('../roles/manifest.mjs');
@@ -145,7 +171,7 @@ if (process.env.CONSTRUCT_ROLES !== 'off') {
               `[fence] cx-${personaId} cannot run this command — outside declared fence.\n` +
               `Command: ${trimmed.slice(0, 200)}\n` +
               `Allowed commands: ${allowedList}\n` +
-              `To bypass: CONSTRUCT_ROLES=off <command>\n`
+              `To bypass: set CONSTRUCT_ROLES=off as a real environment variable before starting this session (this hook runs as a separate process, so an inline "CONSTRUCT_ROLES=off <command>" prefix on the blocked command never reaches it).\n`
             );
             process.exit(2);
           }

package/lib/hooks/mcp-health-check.mjs

@@ -2,14 +2,14 @@
 /**
  * lib/hooks/mcp-health-check.mjs — MCP health check hook — verifies MCP servers are reachable before tool use.
  *
- * Runs as PreToolUse on MCP tool calls. Checks that the target MCP server is running and reachable. Emits a warning (does not block) if the server is unavailable.
+ * Runs as PreToolUse on MCP tool calls. Checks that the target MCP server is running and reachable. Emits a warning (does not block) if the server is unavailable. A successful tool use resets the failure count for that server.
  *
  * @p95ms 51
  * @maxBlockingScope none (PreToolUse, warn-only)
  *
  * @lifecycle PreToolUse
  * @matcher  mcp__.*
- * @exits 0 = pass | 2 = block tool call
+ * @exits 0 = pass (health check is warn-only; never blocks) | 2 = blocked by role fence (unrelated to health, see below)
  */
 import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { homedir } from 'os';
@@ -46,12 +46,19 @@ if (markFailure) {
   process.exit(0);
 }
 
+// Warn-only per @maxBlockingScope none: a tool-level failure is not proof the
+// server is down, so this notice never blocks. Successful use (below) resets
+// the counter, so the notice only appears while failures are still recent.
+
 const entry = cache[serverSlug];
 if (entry?.status === 'unhealthy' && (Date.now() - entry.since) < CACHE_TTL_MS) {
   process.stderr.write(
-    `[mcp-health] The ${serverSlug} connection is unavailable (failed ${entry.failures} time${entry.failures !== 1 ? 's' : ''} recently). Skipping this step.\n`
+    `[mcp-health] The ${serverSlug} connection failed ${entry.failures} time${entry.failures !== 1 ? 's' : ''} recently.\n`
   );
-  process.exit(2);
+} else if (entry) {
+  entry.status = 'healthy';
+  entry.failures = 0;
+  try { writeFileSync(CACHE_PATH, JSON.stringify(cache, null, 2)); } catch { /* best effort */ }
 }
 
 // Role-fence check for MCP tool calls. Most personas have no MCP fence

package/lib/hooks/model-fallback.mjs

@@ -20,22 +20,41 @@
  * @matcher  *
  * @exits 0 = pass
  */
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import {
   applyToEnv,
   classifyProviderFailure,
+  defaultModelRegistryPath,
   readOpenRouterApiKeyFromOpenCodeConfig,
   selectFallbackModel,
   writeProviderCooldown,
 } from '../model-router.mjs';
+import { extractOpRef, resolveOpRef, resolveSecret } from '../providers/secret-resolver.mjs';
 import { readHookInput } from './_lib/input.mjs';
 import { doctorRoot } from '../config/xdg.mjs';
 
 const cooldownPath = join(doctorRoot(), 'provider-cooldowns.json');
 const envPath = join(process.cwd(), '.env');
+const toolkitDir = process.env.CX_TOOLKIT_DIR || join(homedir(), '.construct');
+
+// The fallback candidate chain must be loaded and bound into scope before
+// selectFallbackModel runs, or its tier definition is always empty and a
+// fallback can never fire — same registry file resolveModelTiers reads
+// (specialists/org/models.json under the toolkit dir).
+
+function readRegistryModels(env) {
+  try {
+    const registryPath = defaultModelRegistryPath(env);
+    if (!existsSync(registryPath)) return {};
+    const registry = JSON.parse(readFileSync(registryPath, 'utf8'));
+    return registry?.models ?? {};
+  } catch {
+    return {};
+  }
+}
 
 const input = readHookInput();
 
@@ -45,7 +64,8 @@ if (!classified || !classified.retryable) process.exit(0);
 process.stderr.write(`[model-fallback] ${classified.kind} detected (provider: ${classified.provider ?? 'unknown'}).\n`);
 
 const now = Date.now();
-const result = selectFallbackModel({ hookInput: input, envPath, cooldownPath, now });
+const registryModels = readRegistryModels(process.env);
+const result = selectFallbackModel({ hookInput: input, envPath, cooldownPath, registryModels, now });
 
 if (result) {
   process.stderr.write(`[model-fallback] Switching ${result.tier} → ${result.targetModel} (reason: ${result.reason}).\n`);
@@ -55,20 +75,44 @@ if (result) {
 }
 
 // No candidate resolved — fall back to full `construct models --apply` if possible.
-const toolkitDir = process.env.CX_TOOLKIT_DIR || join(homedir(), '.construct');
+// No fallback was applied here, so no cooldown is written: writing one on a
+// no-op path would suppress the provider on the NEXT failure even though this
+// hook run changed nothing (construct-uccl.3).
 const constructBin = join(toolkitDir, 'bin', 'construct');
 
 if (!existsSync(constructBin)) {
   process.stderr.write(`[model-fallback] No fallback candidate and construct binary not found at ${constructBin}.\n`);
-  if (classified.provider) writeProviderCooldown(cooldownPath, classified.provider, now);
   process.exit(0);
 }
 
-const openRouterApiKey = process.env.OPENROUTER_API_KEY || readOpenRouterApiKeyFromOpenCodeConfig();
+function materializeConfiguredKey(rawValue) {
+  if (typeof rawValue !== 'string' || rawValue.length === 0) return null;
+  const ref = extractOpRef(rawValue);
+  try {
+    return ref ? resolveOpRef(ref) : rawValue;
+  } catch {
+    return null;
+  }
+}
+
+function resolveOpenRouterApiKey() {
+  try {
+    const envKey = resolveSecret('OPENROUTER_API_KEY', { env: process.env });
+    if (envKey) return envKey;
+  } catch {
+    // Fall through to the OpenCode provider config.
+  }
+  try {
+    return materializeConfiguredKey(readOpenRouterApiKeyFromOpenCodeConfig());
+  } catch {
+    return null;
+  }
+}
+
+const openRouterApiKey = resolveOpenRouterApiKey();
 
 if (!openRouterApiKey) {
   process.stderr.write('[model-fallback] No fallback candidate and no OpenRouter API key — cannot poll models.\n');
-  if (classified.provider) writeProviderCooldown(cooldownPath, classified.provider, now);
   process.exit(0);
 }
 

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

@@ -4,7 +4,7 @@
  *
  * 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
+ * specialist chain (cx-architect, cx-security, cx-reviewer, …) before
  * authoring the deliverable — not write it solo. The persona instructs this, but
  * instruction is not enforcement: this hook is the Claude-only barrier.
  *
@@ -87,10 +87,21 @@ if (event === 'PostToolUse' && isPolicyTool(toolName)) {
   process.exit(0);
 }
 
+// A dispatch tool arms `dispatched:true` unless its own response proves the
+// dispatch produced nothing to synthesize (degraded run, zero tasks, or an
+// error/failed status). Task dispatches carry no envelope — an empty/absent
+// blob matches none of these markers, so they still clear the guard.
+
 if (event === 'PostToolUse' && isDispatchTool(toolName)) {
   if (!hasCx(cwd)) process.exit(0);
   const state = readState(cwd);
-  if (state?.pending) writeState(cwd, { ...state, dispatched: true });
+  if (state?.pending) {
+    const blob = JSON.stringify(input?.tool_response ?? '').replace(/\\/g, '');
+    const failed = /"degraded"\s*:\s*true/.test(blob)
+      || /"tasks"\s*:\s*\[\s*\]/.test(blob)
+      || /"status"\s*:\s*"(error|failed)"/.test(blob);
+    if (!failed) writeState(cwd, { ...state, dispatched: true });
+  }
   process.exit(0);
 }
 
@@ -117,7 +128,7 @@ if (event === 'PreToolUse' && /^(Write|Edit|MultiEdit)$/.test(toolName)) {
     + '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'
+    + 'cx-reviewer 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);