harness-everything 0.8.0 → 0.9.0

package/hooks/hooks.json

@@ -21,13 +21,24 @@
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/harness-everything/scripts/kernel-router.js\""
           }
         ],
-        "description": "Establish Harness routing invariants before host/domain skill selection",
+        "description": "Establish Harness routing invariants and an active workflow execution contract before host/domain skill selection",
         "id": "harness:pre:kernel-router"
       }
     ],
     "PreToolUse": [
       {
-        "matcher": "Bash|PowerShell",
+        "matcher": "Bash|PowerShell|Edit|Write|apply_patch",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/workflow-gate.js\""
+          }
+        ],
+        "description": "Enforce mandatory workflow entry and Tier 3 Git-worktree mutation isolation",
+        "id": "harness:pre:workflow-gate"
+      },
+      {
+        "matcher": "Bash|PowerShell|mcp__.*",
         "hooks": [
           {
             "type": "command",
@@ -104,6 +115,16 @@
         "description": "Close any unexecuted action-gate approvals as rejected for this turn",
         "id": "harness:stop:action-gate-audit"
       },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/workflow-stop-gate.js\""
+          }
+        ],
+        "description": "Prevent completion while a selected Fable workflow has not reached verified stage resolution",
+        "id": "harness:stop:workflow-completion-gate"
+      },
       {
         "hooks": [
           {
@@ -117,7 +138,7 @@
     ],
     "PostToolUse": [
       {
-        "matcher": "Bash|PowerShell",
+        "matcher": "Bash|PowerShell|mcp__.*",
         "hooks": [
           {
             "type": "command",
@@ -185,7 +206,7 @@
     ],
     "PostToolUseFailure": [
       {
-        "matcher": "Bash|PowerShell",
+        "matcher": "Bash|PowerShell|mcp__.*",
         "hooks": [
           {
             "type": "command",

package/hooks/scripts/action-gate.js

@@ -16,6 +16,8 @@ const VALID_SCOPES = new Set(['always', 'outside-scratch']);
 const POLICY_ENV = 'HARNESS_ACTION_GATE_POLICY';
 const DEFER_POLICY = 'defer-to-host';
 const ALWAYS_ASK_POLICY = 'always-ask';
+const STRUCTURED_GATED_ACTIONS = new Set(['delete', 'publish', 'deploy', 'send', 'mutate']);
+const STRUCTURED_SAFE_ACTIONS = new Set(['read']);
 
 // Fail-safe defaults are used only when the configured table is missing or
 // invalid. A valid-but-empty table stays empty so CI can catch policy erasure.
@@ -47,12 +49,113 @@ function toolInputOf(payload) {
   return (payload && (payload.tool_input || payload.toolInput || payload.input)) || {};
 }
 
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (!value || typeof value !== 'object') return value;
+  return Object.keys(value).sort().reduce((acc, key) => {
+    acc[key] = stableValue(value[key]);
+    return acc;
+  }, {});
+}
+
 function exactPayloadText(payload) {
   const input = toolInputOf(payload);
   const tool = toolNameOf(payload);
   if (tool === 'Bash' || tool === 'PowerShell') return String(input.command || '');
   if (tool === 'apply_patch') return String(input.patch || input.command || input.content || '');
-  return JSON.stringify(input);
+  return JSON.stringify(stableValue(input));
+}
+
+function explicitActionDescriptor(payload) {
+  const input = toolInputOf(payload);
+  const candidates = [
+    payload && (payload.action_descriptor || payload.actionDescriptor),
+    input && (input.action_descriptor || input.actionDescriptor),
+    payload && payload.harness && (payload.harness.action_descriptor || payload.harness.actionDescriptor),
+  ];
+  return candidates.find(value => value && typeof value === 'object' && !Array.isArray(value)) || null;
+}
+
+function inferToolFamily(tool, explicit) {
+  if (explicit && ['shell', 'mcp', 'local-function'].includes(explicit.toolFamily)) return explicit.toolFamily;
+  if (tool === 'Bash' || tool === 'PowerShell') return 'shell';
+  if (/^mcp(?:__|_)/i.test(tool)) return 'mcp';
+  return 'local-function';
+}
+
+function inferStructuredAction(tool, explicit) {
+  const requested = explicit && String(explicit.action || '').toLowerCase();
+  if (['read', 'delete', 'publish', 'deploy', 'send', 'mutate', 'unknown'].includes(requested)) return requested;
+  const name = String(tool || '').toLowerCase();
+  if (/(?:^|[_-])(get|list|read|search|find|fetch|show|inspect)(?:$|[_-])/.test(name)) return 'read';
+  if (/(?:delete|remove|destroy|drop|purge)/.test(name)) return 'delete';
+  if (/(?:publish|release_create|create_release|release-publish)/.test(name)) return 'publish';
+  if (/(?:deploy|apply_production|promote)/.test(name)) return 'deploy';
+  if (/(?:send|email|message|notify|post_message)/.test(name)) return 'send';
+  if (/(?:create|update|write|edit|mutate|set_|add_|merge|close_)/.test(name)) return 'mutate';
+  return 'unknown';
+}
+
+function safeResource(input, explicit) {
+  const direct = explicit && explicit.resource;
+  if (typeof direct === 'string' && direct.trim()) return direct.trim().slice(0, 200);
+  for (const [key, value] of Object.entries(input || {})) {
+    if (/token|secret|password|credential|authorization|api[_-]?key/i.test(key)) continue;
+    if (!/resource|path|target|repo|repository|channel|issue|file|name|id$/i.test(key)) continue;
+    if (typeof value === 'string' || typeof value === 'number') return String(value).slice(0, 200);
+  }
+  return null;
+}
+
+function normalizeActionDescriptor(payload) {
+  const tool = toolNameOf(payload);
+  const input = toolInputOf(payload);
+  const explicit = explicitActionDescriptor(payload);
+  const toolFamily = inferToolFamily(tool, explicit);
+  const action = inferStructuredAction(tool, explicit);
+  const classification = STRUCTURED_GATED_ACTIONS.has(action)
+    ? 'gated'
+    : (STRUCTURED_SAFE_ACTIONS.has(action) ? 'safe' : 'unknown');
+  const reasonCodes = [];
+  if (explicit) reasonCodes.push('explicit-structured-action');
+  else if (action !== 'unknown') reasonCodes.push('tool-identity-inference');
+  else reasonCodes.push('structured-action-unknown');
+  return {
+    schemaVersion: 1,
+    toolFamily,
+    toolName: tool,
+    action,
+    resource: safeResource(input, explicit),
+    payloadHash: hashExact(exactPayloadText(payload)),
+    classification,
+    reasonCodes,
+  };
+}
+
+function structuredRule(payload) {
+  const descriptor = normalizeActionDescriptor(payload);
+  if (descriptor.toolFamily === 'shell') return { descriptor, rule: null };
+  if (descriptor.classification === 'safe') return { descriptor, rule: null };
+  if (descriptor.classification === 'gated') {
+    return {
+      descriptor,
+      rule: {
+        id: `structured-${descriptor.action}`,
+        reason: `Structured ${descriptor.action} action requires pre-action authorization.`,
+      },
+    };
+  }
+  const hint = routerActionGateHint(payload);
+  if (hint && hint.required) {
+    return {
+      descriptor,
+      rule: {
+        id: 'structured-unknown-required',
+        reason: 'The workflow requires an action gate, but this structured tool action is unknown.',
+      },
+    };
+  }
+  return { descriptor, rule: null };
 }
 
 function validateRule(rule) {
@@ -306,11 +409,13 @@ function recordDecision(payload, rule, table, host, disposition, options = {}, e
   const exact = exactPayloadText(payload);
   const commandHash = hashExact(exact);
   const now = new Date().toISOString();
+  const descriptor = normalizeActionDescriptor(payload);
   const record = {
     schemaVersion: 1,
     toolName: toolNameOf(payload),
     toolUseId: (payload && (payload.tool_use_id || payload.toolUseId)) || null,
     commandHash,
+    actionDescriptor: descriptor,
     matchedRule: rule.id,
     ruleReason: rule.reason,
     disposition,
@@ -332,7 +437,8 @@ function recordDecision(payload, rule, table, host, disposition, options = {}, e
 function evaluatePreToolUse(payload, options = {}) {
   const context = sessionContext(payload, options.sessionDir);
   const table = options.ruleTable || loadRuleTable(options.rulePath || RULES_PATH);
-  const rule = classify(payload, table.rules, context.sessionDir);
+  const structured = structuredRule(payload);
+  const rule = structured.rule || classify(payload, table.rules, context.sessionDir);
   if (!rule) {
     return {
       kind: 'allow',
@@ -341,6 +447,7 @@ function evaluatePreToolUse(payload, options = {}) {
       stderr: table.degraded ? `[Harness actionGate] ${table.degradationReason}; built-in defaults active.` : null,
       rule: null,
       table,
+      descriptor: structured.descriptor,
     };
   }
 
@@ -535,4 +642,6 @@ module.exports = {
   routerActionGateHint,
   scratchRoots,
   validateRuleTable,
+  normalizeActionDescriptor,
+  structuredRule,
 };

package/hooks/scripts/contract-test.js

@@ -20,7 +20,9 @@ const {
   chooseCorrelatedContract,
   commandMatches,
   listRunContracts,
+  getWorkerId,
 } = require('./lib/fable-contracts');
+const { loadWorkflow, matchingRun, recordBudgetEvent } = require('./lib/workflow-runtime');
 
 function resultState(payload) {
   const toolResponse = payload.tool_response || payload.tool_result || {};
@@ -41,6 +43,7 @@ function updateRunContract(entry, payload, command, sessionId) {
   const observedAt = new Date().toISOString();
   const contract = {
     ...entry.contract,
+    workerId: entry.contract.workerId || getWorkerId(payload),
     status: failed ? 'fail' : 'pass',
     lastObservedCommand: command,
     lastObservedExitCode: exitCode ?? null,
@@ -103,8 +106,11 @@ process.stdin.on('end', () => {
     const root = getWorkspaceRoot(payload);
     const stateRoot = getStateRoot(root, payload);
     const sessionId = getSessionId(payload);
+    const workflowContext = loadWorkflow(payload);
+    const activeRun = workflowContext.workflow?.workflowId ? matchingRun(workflowContext) : null;
     const runMatches = listRunContracts(stateRoot).filter(({ contract }) =>
-      ['pending', 'planned', 'running'].includes(contract.status) && commandMatches(contract, command)
+      (contract.workflowId ? ['pending', 'planned', 'running', 'fail', 'pass'] : ['pending', 'planned', 'running']).includes(contract.status) && commandMatches(contract, command) &&
+      (!workflowContext.workflow?.workflowId || (activeRun && contract.runId === activeRun.run.runId && contract.sessionId === sessionId))
     );
 
     if (runMatches.length > 0) {
@@ -115,9 +121,28 @@ process.stdin.on('end', () => {
         process.exit(2);
       }
 
-      const contract = updateRunContract(resolution.match, payload, command, sessionId);
+      const entry = resolution.match;
+      if (entry.contract.workflowId) {
+        const worker = getWorkerId(payload);
+        if (!worker || (entry.contract.workerId && worker !== entry.contract.workerId)) {
+          console.error('[Contract Test] Active workflow check lacks a matching observed worker identity.');
+          process.exit(2);
+        }
+        for (const id of entry.contract.dependsOn || []) {
+          const dependency = JSON.parse(fs.readFileSync(path.join(entry.runRoot, 'contracts', `${id}.json`), 'utf8'));
+          const escaped = workflowContext.workflow.escapes?.some(item => item.stageId === id && item.runId === entry.contract.runId);
+          if (dependency.status !== 'pass' && !escaped) {
+            console.error('[Contract Test] Dependency has not passed: ' + id);
+            process.exit(2);
+          }
+        }
+      }
+      const contract = updateRunContract(entry, payload, command, sessionId);
       console.log(`[Contract Test] ${contract.planId}/${contract.runId}/${contract.stageId}: ${contract.status.toUpperCase()} ${contract.checkCommand}`);
       if (contract.status === 'fail') {
+        if (workflowContext.workflow?.workflowId) {
+          recordBudgetEvent(workflowContext, 'revision', { evidence: `${contract.stageId}:${contract.evidence || 'verification-failed'}` });
+        }
         console.error(`Evidence: ${contract.evidence || '(no output captured)'}`);
         console.error(`Do not build on this stage's output until it passes. Artifact: ${contract.outputPath || '(no path recorded)'}`);
         process.exit(2);

package/hooks/scripts/lib/workflow-isolation.js

@@ -0,0 +1,102 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+function git(cwd, args) {
+  const result = spawnSync('git', args, { cwd, encoding: 'utf8', windowsHide: true, timeout: 5000 });
+  if (result.status !== 0) throw new Error('cannot verify Git worktree isolation');
+  return result.stdout.trim();
+}
+
+function canonical(value) {
+  const resolved = path.resolve(value);
+  // The JS resolver preserves Windows 8.3 spellings (RUNNER~1), while Git
+  // reports the long directory name. Native resolution gives one identity.
+  try { return fs.realpathSync.native(resolved); }
+  catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    const parent = path.dirname(resolved);
+    if (parent === resolved) return resolved;
+    return path.join(canonical(parent), path.basename(resolved));
+  }
+}
+
+function key(value) {
+  const result = canonical(value);
+  return process.platform === 'win32' ? result.toLowerCase() : result;
+}
+
+function within(root, target) {
+  const relative = path.relative(key(root), key(target));
+  return !path.isAbsolute(relative) && relative !== '..' && !relative.startsWith(`..${path.sep}`);
+}
+
+function linkedWorktree(cwd, boundRoot) {
+  const common = canonical(git(cwd, ['rev-parse', '--path-format=absolute', '--git-common-dir']));
+  const gitDir = canonical(git(cwd, ['rev-parse', '--absolute-git-dir']));
+  const boundCommon = canonical(git(boundRoot, ['rev-parse', '--path-format=absolute', '--git-common-dir']));
+  const top = canonical(git(cwd, ['rev-parse', '--show-toplevel']));
+  if (key(common) === key(gitDir) || key(common) !== key(boundCommon)) return null;
+  const worktrees = git(boundRoot, ['worktree', 'list', '--porcelain', '-z']).split('\0');
+  return worktrees.some(field => field.startsWith('worktree ') && key(field.slice(9)) === key(top)) ? top : null;
+}
+
+// A conservative read subset, not a general shell sandbox.
+function classifyShell(command) {
+  const text = String(command || '').trim();
+  if (!text || /[;&|`\r\n<>$(){}\x00]/.test(text)) return 'mutation-or-unknown';
+  if (/^git\s+worktree\s+add\s+/i.test(text) && !/\s--(?:force|checkout|detach)(?:\s|=|$)/i.test(text)) return 'worktree-setup';
+  if (/\s(?:--(?:output|ext-diff|textconv|exec|pre|pre-glob|pager|open|batch|filters)|-[xoO])(?:\b|=)|\s-(?:exec|execdir|delete|fprint|fprintf)\b/i.test(text)) return 'mutation-or-unknown';
+  if (/^git\s+(?:status|rev-parse|diff|log|show|ls-files|check-ignore)(?:\s|$)/i.test(text) ||
+      /^git\s+branch\s+--show-current$/i.test(text) || /^git\s+worktree\s+list(?:\s|$)/i.test(text) ||
+      /^(?:pwd|ls|dir|cat|type|head|tail|wc|stat|rg|Get-Location|Get-ChildItem|Get-Content|Select-String|Test-Path)(?:\s|$)/i.test(text)) return 'read-only';
+  return 'mutation-or-unknown';
+}
+
+function inputOf(payload) { return payload?.tool_input ?? payload?.toolInput ?? payload?.input ?? {}; }
+function cwdOf(payload, root) {
+  const input = inputOf(payload);
+  return input.workdir || input.cwd || input.working_directory || input.workingDirectory ||
+    payload.cwd || payload.working_directory || payload.workingDirectory || root;
+}
+function commandOf(payload) {
+  const input = inputOf(payload);
+  return String(input.command || input.script || input.cmd || '');
+}
+function mutationPaths(payload) {
+  const input = inputOf(payload);
+  if ((payload.tool_name || payload.tool) === 'apply_patch') {
+    const patch = typeof input === 'string' ? input : input.patch || input.input || '';
+    return [...String(patch).matchAll(/^\*\*\* (?:Add File|Update File|Delete File|Move to): (.+)\r?$/gm)].map(match => match[1].trim());
+  }
+  return [input.file_path || input.filePath || input.path].filter(value => typeof value === 'string' && value.trim());
+}
+function assertTargets(payload, cwd, isolatedRoot) {
+  const targets = mutationPaths(payload);
+  if (!targets.length) throw new Error('mutation target is unknown; cannot verify worktree isolation');
+  for (const target of targets) {
+    const resolved = path.resolve(cwd, target);
+    if (!within(isolatedRoot, resolved) || within(path.join(isolatedRoot, '.git'), resolved)) {
+      throw new Error('mutation target escapes Git worktree isolation or modifies Git metadata');
+    }
+    let parent = path.dirname(resolved);
+    while (!fs.existsSync(parent)) parent = path.dirname(parent);
+    if (key(git(parent, ['rev-parse', '--show-toplevel'])) !== key(isolatedRoot)) throw new Error('mutation target belongs to a different repository');
+  }
+}
+function assertShellScope(command, cwd, isolatedRoot) {
+  if (/(?:^|[;&|\r\n])\s*(?:cd|chdir|pushd|Set-Location|Push-Location)\b/i.test(command)) {
+    throw new Error('use the shell tool working-directory field so isolation can be verified');
+  }
+  const tokens = command.match(/"[^"]*"|'[^']*'|[^\s;&|<>]+/g) || [];
+  for (const token of tokens.slice(1)) {
+    const value = token.replace(/^["']|["']$/g, '').replace(/^[A-Za-z-]+=/, '');
+    if ((path.isAbsolute(value) || /^\.\.[\\/]/.test(value)) && !within(isolatedRoot, path.resolve(cwd, value))) {
+      throw new Error('explicit shell path escapes Git worktree isolation');
+    }
+  }
+}
+
+module.exports = { canonical, key, within, linkedWorktree, classifyShell, inputOf, cwdOf, commandOf, mutationPaths, assertTargets, assertShellScope };

package/hooks/scripts/lib/workflow-runtime.js

@@ -0,0 +1,254 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { getWorkspaceRoot, getSessionDir, getSessionId, getStateRoot } = require('./harness-state');
+const { atomicWriteJson, readJson } = require('./fable-contracts');
+
+const OPEN_STATES = new Set(['pending', 'active', 'running', 'failed', 'blocked', 'escaped']);
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+function isMajorWorkflow(workflow) {
+  return Boolean(workflow && (workflow.mutationIsolation?.required || workflow.tier === 'tier3' || String(workflow.strategy || '').startsWith('fable-')));
+}
+
+function loadWorkflow(payload) {
+  const root = getWorkspaceRoot(payload);
+  const sessionId = getSessionId(payload);
+  const sessionDir = getSessionDir(root, sessionId, payload);
+  const file = path.join(sessionDir, 'workflow-run.json');
+  if (!fs.existsSync(file)) return { root, sessionId, sessionDir, file, workflow: null };
+  const workflow = readJson(file);
+  if (!workflow || !['deferred', 'satisfied', ...OPEN_STATES].includes(workflow.state)) {
+    throw new Error('recorded workflow is unreadable or invalid; repair its state before mutation/completion');
+  }
+  const strategies = ['direct-single', 'iterative-single', 'fable-staged', 'fable-parallel', 'fable-multi-agent-workspace'];
+  if (![1, 2].includes(workflow.schemaVersion) || workflow.sessionId !== sessionId ||
+      (workflow.state !== 'deferred' && !strategies.includes(workflow.strategy)) ||
+      (workflow.schemaVersion === 2 && (!workflow.workflowId || !workflow.workflowPlan ||
+        workflow.workflowPlan.strategy !== workflow.strategy || !Number.isInteger(workflow.revision) || workflow.revision < 0))) {
+    throw new Error('recorded workflow schema or session correlation is invalid');
+  }
+  return { root, sessionId, sessionDir, file, workflow };
+}
+
+function saveWorkflow(context) { atomicWriteJson(context.file, context.workflow); }
+
+function budgetLimits(workflow) {
+  const limits = workflow?.workflowPlan?.limits || {};
+  return {
+    maxIterations: Number.isInteger(limits.maxIterations) && limits.maxIterations > 0 ? limits.maxIterations : null,
+    maxRevisionRounds: Number.isInteger(limits.maxRevisionRounds) && limits.maxRevisionRounds >= 0 ? limits.maxRevisionRounds : 0,
+    maxReplans: Number.isInteger(limits.maxReplans) && limits.maxReplans >= 0 ? limits.maxReplans : 0,
+    maxWorkers: Number.isInteger(limits.maxWorkers) && limits.maxWorkers > 0 ? limits.maxWorkers : 1,
+  };
+}
+
+function ensureWorkflowBudget(workflow) {
+  if (workflow.budget && workflow.budget.schemaVersion === 1) return workflow.budget;
+  const now = new Date().toISOString();
+  workflow.budget = {
+    schemaVersion: 1,
+    epoch: 0,
+    state: 'active',
+    limits: budgetLimits(workflow),
+    counters: { iterations: 0, revisionRounds: 0, replans: 0 },
+    activeWorkers: {},
+    reasonCode: null,
+    exhaustedAt: null,
+    resets: [],
+    events: [],
+    createdAt: now,
+    updatedAt: now,
+  };
+  return workflow.budget;
+}
+
+function syncBudgetToRun(context) {
+  const match = matchingRun(context);
+  if (!match || !context.workflow?.budget) return;
+  const updated = {
+    ...match.run,
+    budget: JSON.parse(JSON.stringify(context.workflow.budget)),
+  };
+  atomicWriteJson(path.join(match.runRoot, 'run.json'), updated);
+}
+
+function persistBudget(context) {
+  saveWorkflow(context);
+  syncBudgetToRun(context);
+}
+
+function budgetError(message) {
+  const error = new Error(message);
+  error.code = 'HARNESS_WORKFLOW_BUDGET';
+  return error;
+}
+
+function appendBudgetEvent(budget, event) {
+  budget.events = [...(budget.events || []), event].slice(-64);
+  budget.updatedAt = event.observedAt;
+}
+
+function exhaustBudget(context, reasonCode, evidence) {
+  const budget = ensureWorkflowBudget(context.workflow);
+  const now = new Date().toISOString();
+  budget.state = 'budget-exhausted';
+  budget.reasonCode = reasonCode;
+  budget.exhaustedAt = now;
+  appendBudgetEvent(budget, { type: 'budget-exhausted', reasonCode, evidence: evidence || null, observedAt: now });
+  context.workflow.state = 'blocked';
+  context.workflow.blockReason = reasonCode;
+  persistBudget(context);
+  throw budgetError(`budget-exhausted: ${reasonCode}`);
+}
+
+function recordBudgetEvent(context, type, options = {}) {
+  const { workflow } = context;
+  if (!workflow) throw budgetError('no workflow available for budget accounting');
+  const budget = ensureWorkflowBudget(workflow);
+  if (budget.state !== 'active') throw budgetError(`workflow budget is ${budget.state}: ${budget.reasonCode || 'unavailable'}`);
+  const now = new Date().toISOString();
+  const evidence = options.evidence || null;
+
+  const consume = (counter, limitName, reasonCode) => {
+    const limit = budget.limits[limitName];
+    if (limit === null) return { applicable: false, value: budget.counters[counter] };
+    if (budget.counters[counter] >= limit) return exhaustBudget(context, reasonCode, evidence);
+    budget.counters[counter]++;
+    appendBudgetEvent(budget, { type, counter, value: budget.counters[counter], limit, evidence, observedAt: now });
+    persistBudget(context);
+    return { applicable: true, value: budget.counters[counter], limit };
+  };
+
+  if (type === 'iteration') return consume('iterations', 'maxIterations', 'iteration-budget-exhausted');
+  if (type === 'revision') return consume('revisionRounds', 'maxRevisionRounds', 'revision-budget-exhausted');
+  if (type === 'replan') return consume('replans', 'maxReplans', 'replan-budget-exhausted');
+
+  if (type === 'worker-acquire') {
+    const workerId = String(options.workerId || '').trim();
+    if (!SAFE_ID.test(workerId)) throw budgetError('worker-acquire requires a stable safe worker id');
+    if (budget.activeWorkers[workerId]) return { active: Object.keys(budget.activeWorkers).length, idempotent: true };
+    const active = Object.keys(budget.activeWorkers).length;
+    if (active >= budget.limits.maxWorkers) return exhaustBudget(context, 'worker-budget-exhausted', evidence || workerId);
+    budget.activeWorkers[workerId] = { acquiredAt: now, evidence };
+    appendBudgetEvent(budget, { type, workerId, active: active + 1, limit: budget.limits.maxWorkers, evidence, observedAt: now });
+    persistBudget(context);
+    return { active: active + 1, limit: budget.limits.maxWorkers };
+  }
+
+  if (type === 'worker-release') {
+    const workerId = String(options.workerId || '').trim();
+    if (!SAFE_ID.test(workerId)) throw budgetError('worker-release requires a stable safe worker id');
+    const existed = Boolean(budget.activeWorkers[workerId]);
+    delete budget.activeWorkers[workerId];
+    appendBudgetEvent(budget, { type, workerId, existed, active: Object.keys(budget.activeWorkers).length, evidence, observedAt: now });
+    persistBudget(context);
+    return { active: Object.keys(budget.activeWorkers).length, existed };
+  }
+
+  throw budgetError(`unknown workflow budget event: ${type}`);
+}
+
+function resetWorkflowBudget(context, evidence) {
+  const { workflow } = context;
+  if (!workflow) throw budgetError('no workflow available for budget reset');
+  const previous = ensureWorkflowBudget(workflow);
+  if (previous.state !== 'budget-exhausted' || workflow.state !== 'blocked') {
+    throw budgetError('budget reset is allowed only after explicit budget exhaustion');
+  }
+  if (!String(evidence || '').trim()) throw budgetError('budget reset requires audit evidence');
+  const now = new Date().toISOString();
+  const resets = [...(previous.resets || []), {
+    epoch: previous.epoch,
+    reasonCode: previous.reasonCode,
+    counters: previous.counters,
+    evidence: String(evidence).trim(),
+    resetAt: now,
+  }].slice(-16);
+  workflow.budget = {
+    schemaVersion: 1,
+    epoch: previous.epoch + 1,
+    state: 'active',
+    limits: budgetLimits(workflow),
+    counters: { iterations: 0, revisionRounds: 0, replans: 0 },
+    activeWorkers: {},
+    reasonCode: null,
+    exhaustedAt: null,
+    resets,
+    events: [{ type: 'budget-reset', evidence: String(evidence).trim(), observedAt: now }],
+    createdAt: previous.createdAt || now,
+    updatedAt: now,
+  };
+  workflow.state = 'pending';
+  delete workflow.blockReason;
+  persistBudget(context);
+  return workflow.budget;
+}
+
+function matchingRun(context) {
+  const { workflow, root, sessionId } = context;
+  if (!workflow || !SAFE_ID.test(workflow.runId || '') || !workflow.workflowId || !sessionId) return null;
+  const runRoot = path.join(getStateRoot(root), 'fable-runs', workflow.runId);
+  const run = readJson(path.join(runRoot, 'run.json'));
+  if (!run || run.runId !== workflow.runId || run.workflowId !== workflow.workflowId ||
+      run.sessionId !== sessionId || run.strategy !== workflow.strategy ||
+      !Number.isFinite(Date.parse(run.createdAt)) || !Array.isArray(run.stageIds) || !run.stageIds.length ||
+      new Set(run.stageIds).size !== run.stageIds.length || run.stageIds.some(id => !SAFE_ID.test(id))) return null;
+  return { runRoot, run };
+}
+
+function unresolvedStages(match, workflow) {
+  const unresolved = [];
+  const stages = [];
+  for (const stageId of match.run.stageIds) {
+    const contract = readJson(path.join(match.runRoot, 'contracts', `${stageId}.json`));
+    if (!contract || contract.stageId !== stageId || contract.runId !== match.run.runId ||
+        contract.planId !== match.run.planId || contract.sessionId !== match.run.sessionId) {
+      unresolved.push(`${stageId}:missing-or-uncorrelated`);
+      continue;
+    }
+    stages.push(contract);
+    const escape = (workflow.escapes || []).find(item => item.stageId === stageId && item.runId === match.run.runId);
+    if (escape && escape.evidence && escape.uncoveredScope &&
+        ['workflow-uncovered-scope', 'host-capability-unavailable'].includes(escape.reasonCode)) continue;
+    const evidence = readJson(path.join(match.runRoot, 'evidence', `${stageId}.json`));
+    if (contract.status !== 'pass' || !contract.checkCommand || !evidence || evidence.status !== 'pass' ||
+        evidence.exitCode !== 0 || evidence.planId !== contract.planId || evidence.runId !== contract.runId ||
+        evidence.stageId !== stageId || evidence.sessionId !== contract.sessionId ||
+        evidence.checkCommand !== contract.checkCommand || !Number.isFinite(Date.parse(evidence.observedAt)) ||
+        evidence.workerId !== contract.workerId || !evidence.workerId || evidence.observedAt !== contract.verifiedAt) {
+      unresolved.push(`${stageId}:verification-unresolved`);
+    }
+  }
+  if (workflow.verification?.independent) {
+    const verifiers = stages.filter(stage => stage.agent === 'fable-verifier' && stage.writeSet?.length === 0);
+    const workers = stages.filter(stage => stage.agent !== 'fable-verifier').map(stage => stage.workerId).filter(Boolean);
+    const latestCheck = Math.max(0, ...stages.filter(stage => stage.agent !== 'fable-verifier').map(stage => Date.parse(stage.verifiedAt) || 0));
+    if (!verifiers.some(stage => stage.workerId && !workers.includes(stage.workerId) && stage.status === 'pass' &&
+        Date.parse(stage.verifiedAt) >= Math.max(workflow.lastMutationAt || 0, latestCheck) &&
+        match.run.stageIds.filter(id => id !== stage.stageId).every(id => stage.dependsOn?.includes(id)))) {
+      unresolved.push('independent-verifier-missing');
+    }
+  }
+  return unresolved;
+}
+
+function readHookInput(decide) {
+  let input = '';
+  let finished = false;
+  const finish = () => {
+    if (finished) return;
+    finished = true;
+    clearTimeout(timeout);
+    try { decide(input.trim() ? JSON.parse(input) : null); }
+    catch (error) { console.error(`[Workflow Gate] ${error.message}`); process.exitCode = 2; }
+  };
+  const timeout = setTimeout(finish, 500);
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => { input += chunk; });
+  process.stdin.on('end', finish);
+  process.stdin.on('error', finish);
+}
+
+module.exports = { OPEN_STATES, SAFE_ID, isMajorWorkflow, loadWorkflow, saveWorkflow, budgetLimits, ensureWorkflowBudget, recordBudgetEvent, resetWorkflowBudget, syncBudgetToRun, matchingRun, unresolvedStages, readHookInput };

package/hooks/scripts/state-persist.js

@@ -83,6 +83,7 @@ function processState(payload) {
         const command = (payload.tool_input && payload.tool_input.command) || '';
         if (VERIFY_COMMAND_RE.test(command)) {
           state.lastVerifyAt = Date.now();
+          state.lastVerifyExitCode = exitCode ?? null;
         }
       }