harness-everything 0.11.5 → 0.11.7

package/docs/workflows/zoom-out.md

@@ -1,74 +1,62 @@
 # Workflow: Zoom Out
 
-> High-level reflection report generation to break out of error loops, analyze failure patterns, and backtrack to alternative paths.
+> Reflect-first breaker after three failures: stop edits, rebuild the full picture with read-only tools, write a fact-check report, then resume or escalate.
 
----
+Source of truth: `zoom-out/SKILL.md`.
 
-## 1. Skill Behavior Workflow
+Contract summary from SKILL.md — Trigger: three same-signature failures or an explicit loop/rethink request. Output: fact-checked report ending in `RESUME` or `ESCALATE`. State: writes the session `zoom-out-report.md`; reset may clear breaker state. Gate: `hooks/scripts/rule-of-3.js` plus a valid report; reset only after the second cycle. USE FOR: "you are stuck in a loop", "the same error keeps failing", "rethink your assumptions". DO NOT USE FOR: routine single-failure debugging, greenfield planning without failures.
 
-This section visualizes how the `zoom-out` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+## 1. Skill Behavior Workflow
 
 ```mermaid
 graph TD
-  Start([3 Consecutive Failures / Goal Drift Triggered]) --> CeaseFire["1. Phase 1: Cease Fire - Stop Code Edits Immediately"]
-  CeaseFire --> Rebuild["2. Phase 2: Rebuild Full Picture using Read-Only Tools"]
-  Rebuild --> CheckPath{3. Resolve Reflection Report Path}
-  
-  CheckPath -->|Session Path Provided| WriteSession["Copy template to Session zoom-out-report.md"]
-  CheckPath -->|Template / Path Unavailable| WritePlatform["Write to .github/harness-everything/zoom-out-report.md or Inline"]
-  
-  WriteSession --> DecisionGate{4. Phase 4: Decision Gate}
-  WritePlatform --> DecisionGate
-  
-  DecisionGate -->|Untried Path Identified| Resume["RESUME: Execute Fresh Diagnosis in TDD / Fable"]
-  DecisionGate -->|Requirement Conflict / Access Gap| Escalate["ESCALATE: Present 2-3 Options + Recommendation to Human"]
-  
-  Resume --> Resolved{5. Problem Cracking Succeeds?}
-  Resolved -->|Yes| SelfEvolve["Call self-evolve to Persist Insight"]
-  Resolved -->|No: 3 More Failures| Escalate
-  SelfEvolve --> End([Reflection Completed & Lessons Persisted])
-  Escalate --> End
+  Third[Third Same Signature Failure] --> Stop[Stop Edits No User Ask Yet]
+  Stop --> ReadOnly[ReadOnly Restate Goal Check Files Config Logs]
+  ReadOnly --> Fill[Fill zoom-out-report template]
+  Fill --> Decide{RESUME or ESCALATE?}
+  Decide -->|untried path| Resume[RESUME On Untried Path]
+  Decide -->|genuine user decision| Escalate[ESCALATE With Options]
+  Resume --> Again{Repeated Breaker Cycle?}
+  Again -->|second cycle| Reset[npm run harness reset]
+  Reset --> Evolve[Record Insight With self-evolve]
+  Again -->|no| Done([Report Complete])
+  Escalate --> Done
 ```
 
----
-
 ## 2. Triggering and Routing Path
 
-This diagram illustrates how the `zoom-out` skill is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
-
 ```mermaid
-graph LR
-  RuleOf3["Rule of 3 Circuit Breaker"] -->|Tripped!| ZoomOut["zoom-out / SKILL.md"]
-  ZoomOut -->|Halts execution for| ActiveWork["Active workspace edits"]
-  ZoomOut -->|Asks for human direction via| AskQuestions["host user-input mechanism"]
-  ZoomOut -->|Unlocks workspace state after| HumanReset["Human Partner Response"]
+graph TD
+  LoopReq[Stuck In Loop Request] --> Skill[zoom-out SKILL]
+  SameErr[Same Error Keeps Failing] --> Skill
+  Rethink[Rethink Assumptions Request] --> Skill
+  ThreeFail[Three Same Signature Failures] --> Breaker[hooks scripts rule-of-3 js]
+  Breaker --> Skill
+  SingleFail[Routine Single Failure] --> DirectFix[Fix Directly]
+  Greenfield[Greenfield Planning No Failures] --> Fable[fable-mode SKILL]
+  Skill --> ReportGate[Valid Report RESUME or ESCALATE]
 ```
 
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `zoom-out` skill, illustrating standard success paths, error handling, or recovery loops.
+## 3. Real-World Use Case
 
 ```mermaid
 graph TD
-  Start["Attempting to fix Python import error; fails 3 times consecutively with same trace"] --> Trigger["Rule of 3 circuit breaker trips"]
-  Trigger --> Lock["Workspace writes locked"]
-  Trigger --> Awaken["Awaken: Stop error-fixing; review imports design & requirements (Law 2)"]
-  Awaken --> Collect["Collect error traces and diff history"]
-  Collect --> WriteReport["Create the session zoom-out-report.md detailing the import cyclic dependency"]
-  WriteReport --> Present["Present options to human: Option A - Merge imports, Option B - Extract shared modules"]
-  Present --> UserChoice["User select: 'Option B'"]
-  UserChoice --> Unlock["Unlock workspace and execute Option B"]
-  Unlock --> Done([Error loop successfully broken and resolved])
+  Fail[Same Test Fails Three Times Same Signature] --> Halt[Stop Edits Rebuild Picture ReadOnly]
+  Halt --> Inspect[Restate Goal Check Files Config Logs]
+  Inspect --> Write[Fill templates zoom-out-report template md]
+  Write --> Choice{Untried Path Exists?}
+  Choice -->|yes| Resume2[RESUME On Untried Path]
+  Choice -->|no| Esc2[ESCALATE With Options]
+  Resume2 -->|repeated cycle| Reset2[npm run harness reset Then self-evolve]
 ```
 
----
+Template: `zoom-out/templates/zoom-out-report.template.md`. Enforcement: `hooks/scripts/rule-of-3.js`. Deep dive: `zoom-out/references/circuit-breaker.md`.
 
 ## 4. Verification Check
 
-To ensure that the `zoom-out` skill is operating in strict compliance with Harness OS design laws, verify the following:
-
-- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
-- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
-- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.
+- [ ] After three same-signature failures, edits stopped and the same approach was not retried
+- [ ] Goal, files, configuration, and logs were rechecked with read-only tools before any resume
+- [ ] `templates/zoom-out-report.template.md` was filled and the session `zoom-out-report.md` ends in `RESUME` or `ESCALATE`
+- [ ] Resume targeted only an untried path; genuine user decisions were escalated with options
+- [ ] Reset via `npm run harness:reset` happened only after the second cycle, with the insight recorded via `self-evolve`
+- [ ] Routine single-failure debugging and greenfield planning without failures were not routed here

package/harness-everything/SKILL.md

@@ -4,7 +4,7 @@ description: "Route software/project work through the Harness kernel: classify T
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.11.2
+  version: 0.11.7
 ---
 
 # Harness Everything

package/harness-everything/scripts/kernel-router.js

@@ -33,12 +33,26 @@ function issueMemoryCapability(workflow) {
   return token;
 }
 
+// Host-generated background-task notifications arrive as UserPromptSubmit
+// hook payloads but are not user input (#168). Routing them like prompts
+// replaces the workflow contract mid-turn (e.g. deferred -> a new Tier-2).
+// A prompt that is entirely a notification envelope must never create or
+// replace a workflow; the current contract is kept unchanged.
+function isHostNotificationPrompt(prompt) {
+  const text = String(prompt || '').trim();
+  if (!text) return false;
+  return /^<task-notification[\s>][\s\S]*<\/task-notification>\s*$/i.test(text);
+}
+
 function persistWorkflow(plan, payload, prompt) {
   if (!payload || !(payload.session_id || payload.sessionId)) return null;
   const { runtime, hooksRoot } = loadRuntime();
   const context = runtime.loadWorkflow(payload);
   const { writeCurrentSession } = require(path.join(hooksRoot, 'lib/harness-state'));
   writeCurrentSession(context.root, context.sessionId);
+  if (isHostNotificationPrompt(prompt)) {
+    return { ...context, hooksRoot, retained: true, hostNotification: true };
+  }
   if (context.workflow && runtime.OPEN_STATES.has(context.workflow.state)) {
     if (!context.workflow.workflowPlan) throw new Error('legacy unresolved workflow needs explicit migration; refusing to replace its obligations');
     // Steering/status prompts cannot drop an unresolved execution contract.
@@ -92,17 +106,30 @@ function run(raw) {
     try { payload = JSON.parse(raw); } catch (_) { console.error('[Workflow Router] Invalid hook payload; lifecycle persistence unavailable.'); }
   }
   const prompt = promptArg || (typeof payload?.prompt === 'string' ? payload.prompt : '');
-  const result = core.route(promptArg, raw || null);
-  let plan = result.contract.workflowPlan;
+  const hostNotification = isHostNotificationPrompt(prompt);
+  // Host-generated notifications are lifecycle events, not user-authored task
+  // input. Never feed their text into the router: when there is an active
+  // contract we retain it below; when there is none, the event is a no-op.
+  const result = hostNotification ? null : core.route(promptArg, raw || null);
+  let plan = result?.contract?.workflowPlan || null;
   let persisted = null;
   let failure = null;
   try {
     persisted = persistWorkflow(plan, payload, prompt);
-    if (persisted?.retained) plan = persisted.workflow.workflowPlan;
+    if (persisted?.retained && persisted.workflow) plan = persisted.workflow.workflowPlan;
   } catch (error) { failure = error; }
-  if (result.sanitized) console.log(result.sanitized);
-  if (result.stderr) process.stderr.write(result.stderr);
-  if (persisted?.retained) console.log('\n=> Retaining unresolved workflow from earlier prompts; the checkpoint below is the active execution contract.');
+  if (hostNotification && !persisted?.workflow) {
+    console.log('\n=> Host notification — no active execution contract; ignored for routing.');
+    if (failure) {
+      console.error('[Workflow Router] ' + failure.message);
+      process.exitCode = 2;
+    }
+    return;
+  }
+  if (result?.sanitized) console.log(result.sanitized);
+  if (result?.stderr) process.stderr.write(result.stderr);
+  if (persisted?.hostNotification) console.log('\n=> Host notification — routing unchanged; keeping the active execution contract.');
+  else if (persisted?.retained) console.log('\n=> Retaining unresolved workflow from earlier prompts; the checkpoint below is the active execution contract.');
   core.printWorkflowPlan(plan);
   core.printRoutingCheckpoint(plan);
   core.printKernelContract(plan);
@@ -116,7 +143,7 @@ function run(raw) {
     console.log('   - Tier 3 / Fable source and artifact mutations require Git worktree isolation; unavailable isolation means BLOCKED.');
     console.log('   - Escape is limited to workflow-uncovered-scope or host-capability-unavailable, with stage, scope and evidence; other obligations remain mandatory.');
   }
-  if (persisted) {
+  if (persisted?.workflow) {
     const controller = path.join(persisted.hooksRoot, 'workflow-disposition.js');
     console.log('   - Workflow id: ' + persisted.workflow.workflowId);
     console.log('   - Memory write disposition: ' + (persisted.workflow.workflowPlan.memory?.write || 'none'));
@@ -130,12 +157,13 @@ function run(raw) {
   if (failure) {
     console.error('[Workflow Router] ' + failure.message);
     process.exitCode = 2;
-  } else if (result.status !== 0) process.exitCode = result.status || 1;
+  } else if (result && result.status !== 0) process.exitCode = result.status || 1;
 }
 
+if (typeof module !== 'undefined') module.exports = { isHostNotificationPrompt };
+
 if (process.argv.length > 2 || process.stdin.isTTY) run('');
-else {
-  let input = '';
+else {  let input = '';
   let finished = false;
   const finish = () => { if (finished) return; finished = true; clearTimeout(timeout); run(input); };
   const timeout = setTimeout(finish, 500);

package/hooks/hooks.json

@@ -157,6 +157,19 @@
         "id": "harness:stop:skill-telemetry"
       }
     ],
+    "PermissionDenied": [
+      {
+        "matcher": "Bash|PowerShell",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/workflow-mutation-denied.js\""
+          }
+        ],
+        "description": "Release reserved mutation capacity when Claude auto mode denies a shell tool call",
+        "id": "harness:permission-denied:mutation-probe"
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "Bash|PowerShell|mcp__.*",
@@ -188,7 +201,7 @@
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/state-persist.js\""
           }
         ],
-        "description": "Save skill transition state",
+        "description": "Persist tool outcome, observed workspace mutation, and verification milestones",
         "id": "harness:post:state-persist"
       },
       {
@@ -259,6 +272,17 @@
         "description": "Track failed tool error signatures for Rule of 3",
         "id": "harness:post-failure:rule-of-3-tracker"
       },
+      {
+        "matcher": "Bash|PowerShell",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scripts/state-persist.js\""
+          }
+        ],
+        "description": "Persist failed shell outcome and any workspace mutation that occurred before failure",
+        "id": "harness:post-failure:state-persist"
+      },
       {
         "matcher": "Skill",
         "hooks": [

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

@@ -1,13 +1,89 @@
 'use strict';
 
 const fs = require('fs');
+const crypto = require('crypto');
 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 });
+function gitRaw(cwd, args) {
+  const result = spawnSync('git', args, { cwd, encoding: 'utf8', windowsHide: true, timeout: 5000, maxBuffer: 16 * 1024 * 1024 });
   if (result.status !== 0) throw new Error('cannot verify Git worktree isolation');
-  return result.stdout.trim();
+  return result.stdout;
+}
+
+function git(cwd, args) {
+  return gitRaw(cwd, args).trim();
+}
+
+function hashWorktreePath(root, relative) {
+  const target = path.join(root, relative);
+  let stat;
+  try { stat = fs.lstatSync(target); }
+  catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+  if (stat.isDirectory()) {
+    const result = spawnSync('git', ['-C', target, 'rev-parse', 'HEAD'], { encoding: 'utf8', windowsHide: true, timeout: 5000 });
+    return { mode: '160000', oid: result.status === 0 ? result.stdout.trim() : 'directory' };
+  }
+  const mode = stat.isSymbolicLink() ? '120000' : ((stat.mode & 0o111) ? '100755' : '100644');
+  const result = spawnSync('git', ['hash-object', '--path=' + relative, '--', relative], {
+    cwd: root, encoding: 'utf8', windowsHide: true, timeout: 5000,
+  });
+  if (result.status !== 0) throw new Error('cannot fingerprint workspace content');
+  return { mode, oid: result.stdout.trim() };
+}
+
+function workspaceFingerprint(cwd) {
+  const root = canonical(git(cwd, ['rev-parse', '--show-toplevel']));
+  const entries = new Map();
+  for (const record of gitRaw(root, ['ls-files', '-s', '-z']).split('\0')) {
+    if (!record) continue;
+    const tab = record.indexOf('\t');
+    if (tab < 0) throw new Error('cannot fingerprint workspace index');
+    const meta = record.slice(0, tab).trim().split(/\s+/);
+    const relative = record.slice(tab + 1);
+    const mode = meta[0];
+    const oid = meta[1];
+    entries.set(relative, { relative, mode, oid });
+  }
+
+  // Substitute current worktree content for tracked paths that differ from the
+  // index. This keeps the fingerprint stable across git add / git commit when
+  // visible workspace content did not change.
+  for (const relative of gitRaw(root, ['diff-files', '--name-only', '-z']).split('\0').filter(Boolean)) {
+    const value = hashWorktreePath(root, relative);
+    if (value) entries.set(relative, { relative, mode: value.mode, oid: value.oid });
+    else entries.delete(relative);
+  }
+
+  for (const relative of gitRaw(root, ['ls-files', '--others', '--exclude-standard', '-z']).split('\0').filter(Boolean)) {
+    const value = hashWorktreePath(root, relative);
+    entries.set(relative, { relative, mode: value.mode, oid: value.oid });
+  }
+
+  const digest = crypto.createHash('sha256');
+  digest.update('harness-workspace-fingerprint-v1\0');
+  for (const entry of [...entries.values()].sort((a, b) => a.relative.localeCompare(b.relative))) {
+    digest.update(entry.relative); digest.update('\0');
+    digest.update(entry.mode); digest.update('\0');
+    digest.update(entry.oid); digest.update('\0');
+  }
+  return digest.digest('hex');
+}
+
+function shellProbeKey(payload, cwd) {
+  const toolUseId = String(payload?.tool_use_id || payload?.toolUseId || '').trim();
+  const tool = String(payload?.tool_name || payload?.tool || '');
+  const command = commandOf(payload);
+  return crypto.createHash('sha256')
+    .update('harness-shell-probe-v2\0')
+    .update(toolUseId || 'no-tool-use-id').update('\0')
+    .update(tool).update('\0')
+    .update(key(cwd)).update('\0')
+    .update(command)
+    .digest('hex');
 }
 
 function canonical(value) {
@@ -144,9 +220,9 @@ function splitShellSegments(text) {
 
 function classifyShell(command) {
   const text = String(command || '').trim();
-  if (!text) return 'mutation-or-unknown';
+  if (!text) return 'untrusted';
   const segments = splitShellSegments(text);
-  if (!segments) return 'mutation-or-unknown';
+  if (!segments) return 'untrusted';
   if (segments.length === 1) {
     if (/^git\s+worktree\s+add\s+/i.test(segments[0]) && !/\s--(?:force|checkout|detach)(?:\s|=|$)/i.test(segments[0])) return 'worktree-setup';
     return isReadOnlySegment(segments[0]) ? 'read-only' : 'mutation-or-unknown';
@@ -172,6 +248,35 @@ function mutationPaths(payload) {
   }
   return [input.file_path || input.filePath || input.path].filter(value => typeof value === 'string' && value.trim());
 }
+
+// Bound workspace root plus its linked worktrees. Git failures (e.g. a
+// non-git workspace) degrade to the root alone instead of throwing, so
+// Tier-2 accounting never blocks on this enumeration (#165; cf. #162).
+function worktreeRoots(root) {
+  const roots = [root];
+  try {
+    for (const field of git(root, ['worktree', 'list', '--porcelain', '-z']).split('\0')) {
+      if (field.startsWith('worktree ')) {
+        const candidate = field.slice('worktree '.length).trim();
+        if (candidate) roots.push(candidate);
+      }
+    }
+  } catch (_) { /* root alone */ }
+  return roots;
+}
+
+// Direct-tool (Edit/Write/apply_patch) targets count against the Tier-2
+// budget only when at least one target lies inside the workspace (#165).
+// Unknown targets (no parseable path) stay conservative and count.
+function directMutationInWorkspace(payload, cwd, root) {
+  const targets = mutationPaths(payload);
+  if (!targets.length) return true;
+  const roots = worktreeRoots(root);
+  return targets.some(target => {
+    const resolved = path.resolve(cwd, target);
+    return roots.some(candidate => within(candidate, resolved));
+  });
+}
 function assertTargets(payload, cwd, isolatedRoot) {
   const targets = mutationPaths(payload);
   if (!targets.length) throw new Error('mutation target is unknown; cannot verify worktree isolation');
@@ -198,4 +303,4 @@ function assertShellScope(command, cwd, isolatedRoot) {
   }
 }
 
-module.exports = { canonical, key, within, linkedWorktree, classifyShell, inputOf, cwdOf, commandOf, mutationPaths, assertTargets, assertShellScope };
+module.exports = { canonical, key, within, linkedWorktree, classifyShell, workspaceFingerprint, shellProbeKey, inputOf, cwdOf, commandOf, mutationPaths, worktreeRoots, directMutationInWorkspace, assertTargets, assertShellScope };

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

@@ -43,6 +43,140 @@ function loadWorkflow(payload) {
 
 function saveWorkflow(context) { atomicWriteJson(context.file, context.workflow); }
 
+const MUTATION_PROBE_KEY = /^[a-f0-9]{64}$/;
+const MUTATION_PROBE_WAIT = new Int32Array(new SharedArrayBuffer(4));
+
+function mutationProbeDir(context) {
+  return path.join(context.sessionDir, 'mutation-probes');
+}
+
+function mutationProbeFile(context, key) {
+  if (!MUTATION_PROBE_KEY.test(String(key || ''))) throw new Error('invalid mutation probe identity');
+  return path.join(mutationProbeDir(context), key + '.json');
+}
+
+function withMutationProbeLock(context, callback) {
+  fs.mkdirSync(context.sessionDir, { recursive: true });
+  const lockDir = path.join(context.sessionDir, '.mutation-probes.lock');
+  let acquired = false;
+  for (let attempt = 0; attempt < 200; attempt++) {
+    try {
+      fs.mkdirSync(lockDir);
+      acquired = true;
+      break;
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      try {
+        const stat = fs.statSync(lockDir);
+        if (Date.now() - stat.mtimeMs > 30000) {
+          fs.rmSync(lockDir, { recursive: true, force: true });
+          continue;
+        }
+      } catch (_) { /* retry below */ }
+      Atomics.wait(MUTATION_PROBE_WAIT, 0, 0, 10);
+    }
+  }
+  if (!acquired) throw new Error('cannot acquire mutation probe lock');
+  try { return callback(); }
+  finally { fs.rmSync(lockDir, { recursive: true, force: true }); }
+}
+
+function mutationProbeReservations(context) {
+  const dir = mutationProbeDir(context);
+  let files = [];
+  try { files = fs.readdirSync(dir).filter(file => /^[a-f0-9]{64}\.json$/.test(file)); }
+  catch (_) { return 0; }
+  let count = 0;
+  for (const file of files) {
+    const probe = readJson(path.join(dir, file));
+    if (probe?.schemaVersion === 1 && probe.reserveIteration === true) count++;
+  }
+  return count;
+}
+
+function refreshWorkflowForProbe(context) {
+  const latest = readJson(context.file);
+  if (!latest || latest.sessionId !== context.sessionId) throw new Error('cannot refresh workflow for mutation probe');
+  context.workflow = latest;
+  return latest;
+}
+
+function assertIterationCapacity(context, evidence) {
+  const { workflow } = context;
+  if (!workflow) throw budgetError('no workflow available for iteration capacity');
+  const budget = ensureWorkflowBudget(workflow);
+  if (budget.state !== 'active') throw budgetError(`workflow budget is ${budget.state}: ${budget.reasonCode || 'unavailable'}`);
+  const limit = budget.limits.maxIterations;
+  if (limit === null) return { applicable: false, value: budget.counters.iterations, reserved: 0 };
+  const reserved = mutationProbeReservations(context);
+  if (budget.counters.iterations + reserved >= limit) {
+    return exhaustBudget(context, 'iteration-budget-exhausted', evidence || 'untrusted-shell-capacity');
+  }
+  return { applicable: true, value: budget.counters.iterations, reserved, limit };
+}
+
+function registerMutationProbe(context, key, fingerprint, reserveIteration) {
+  if (!MUTATION_PROBE_KEY.test(String(key || '')) || !MUTATION_PROBE_KEY.test(String(fingerprint || ''))) {
+    throw new Error('invalid mutation probe identity');
+  }
+  return withMutationProbeLock(context, () => {
+    refreshWorkflowForProbe(context);
+    if (reserveIteration) assertIterationCapacity(context, 'shell:untrusted');
+    const dir = mutationProbeDir(context);
+    fs.mkdirSync(dir, { recursive: true });
+    const file = mutationProbeFile(context, key);
+    if (fs.existsSync(file)) throw new Error('mutation probe is already pending for this tool call');
+    const probe = {
+      schemaVersion: 1,
+      fingerprint,
+      reserveIteration: Boolean(reserveIteration),
+      observedAt: Date.now(),
+    };
+    atomicWriteJson(file, probe);
+    return probe;
+  });
+}
+
+function peekMutationProbe(context, key) {
+  return readJson(mutationProbeFile(context, key));
+}
+
+function settleMutationProbe(context, key, afterFingerprint, tool) {
+  if (!MUTATION_PROBE_KEY.test(String(afterFingerprint || ''))) throw new Error('invalid mutation probe fingerprint');
+  return withMutationProbeLock(context, () => {
+    const file = mutationProbeFile(context, key);
+    const probe = readJson(file);
+    if (!probe || probe.schemaVersion !== 1) return null;
+    refreshWorkflowForProbe(context);
+    fs.unlinkSync(file);
+    const changed = afterFingerprint !== probe.fingerprint;
+    if (changed) {
+      context.workflow.lastMutationAt = Date.now();
+      if (probe.reserveIteration && context.workflow.strategy === 'iterative-single') {
+        recordBudgetEvent(context, 'iteration', { evidence: String(tool || 'shell') + ':observed-workspace-mutation' });
+      } else {
+        saveWorkflow(context);
+      }
+    }
+    return { changed, probe };
+  });
+}
+
+function discardMutationProbe(context, key) {
+  return withMutationProbeLock(context, () => {
+    const file = mutationProbeFile(context, key);
+    if (!fs.existsSync(file)) return false;
+    fs.unlinkSync(file);
+    return true;
+  });
+}
+
+function clearMutationProbes(context) {
+  return withMutationProbeLock(context, () => {
+    fs.rmSync(mutationProbeDir(context), { recursive: true, force: true });
+  });
+}
+
 function budgetLimits(workflow) {
   const limits = workflow?.workflowPlan?.limits || {};
   return {
@@ -123,7 +257,8 @@ function recordBudgetEvent(context, type, options = {}) {
   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);
+    const reserved = type === 'iteration' ? mutationProbeReservations(context) : 0;
+    if (budget.counters[counter] + reserved >= limit) return exhaustBudget(context, reasonCode, evidence);
     budget.counters[counter]++;
     appendBudgetEvent(budget, { type, counter, value: budget.counters[counter], limit, evidence, observedAt: now });
     persistBudget(context);
@@ -175,6 +310,7 @@ function resetWorkflowBudget(context, evidence) {
     evidence: String(evidence).trim(),
     resetAt: now,
   }].slice(-16);
+  clearMutationProbes(context);
   workflow.budget = {
     schemaVersion: 1,
     epoch: previous.epoch + 1,
@@ -260,4 +396,4 @@ function readHookInput(decide) {
   process.stdin.on('error', finish);
 }
 
-module.exports = { OPEN_STATES, SAFE_ID, WORKFLOW_CONTROLLER_COMMANDS, isMajorWorkflow, loadWorkflow, saveWorkflow, budgetLimits, ensureWorkflowBudget, recordBudgetEvent, resetWorkflowBudget, syncBudgetToRun, matchingRun, unresolvedStages, readHookInput };
+module.exports = { OPEN_STATES, SAFE_ID, WORKFLOW_CONTROLLER_COMMANDS, isMajorWorkflow, loadWorkflow, saveWorkflow, budgetLimits, ensureWorkflowBudget, mutationProbeReservations, assertIterationCapacity, registerMutationProbe, peekMutationProbe, settleMutationProbe, discardMutationProbe, clearMutationProbes, recordBudgetEvent, resetWorkflowBudget, syncBudgetToRun, matchingRun, unresolvedStages, readHookInput };

package/hooks/scripts/rule-of-3-tracker.js

@@ -17,6 +17,7 @@ process.stdin.on('end', () => {
     const payload = JSON.parse(inputData);
     const hookEventName = payload.hook_event_name || payload.hookEventName || '';
     const isFailureEvent = hookEventName === 'PostToolUseFailure';
+    const isSuccessEvent = hookEventName === 'PostToolUse';
     const toolResponse = payload.tool_response || {};
     const stdout = toolResponse.stdout ?? payload.stdout ?? '';
     const stderr = toolResponse.stderr ?? payload.stderr ?? '';
@@ -25,10 +26,10 @@ process.stdin.on('end', () => {
     const exitCode = typeof rawExitCode === 'number' ? rawExitCode : undefined;
 
     const explicitFailure = exitCode !== undefined && exitCode !== 0;
-    const explicitSuccess = exitCode === 0;
     const stderrSignal = typeof stderr === 'string' && stderr.trim().length > 0;
     const looksLikeError = /\b(error|fail|failed|failure|exception|fatal|panic|traceback|denied|refused|cannot|unable)\b/i.test(stderr);
-    const isFailure = isFailureEvent || explicitFailure || (exitCode === undefined && stderrSignal && looksLikeError);
+    const isFailure = isFailureEvent || explicitFailure ||
+      (!isSuccessEvent && exitCode === undefined && stderrSignal && looksLikeError);
     const errorText = isFailureEvent
       ? (failureText || (stderrSignal ? stderr : stdout) || '')
       : ((stderrSignal ? stderr : stdout) || failureText || '');
@@ -47,19 +48,22 @@ process.stdin.on('end', () => {
       const filePath = payload.tool_input?.file_path || payload.tool_input?.filePath || '';
       const command = payload.tool_input?.command || '';
 
-      // Categorize failure type for context-aware thresholds
+      // Categorize failure type for context-aware thresholds.
+      // NOTE (#167): match anchored diagnostic phrases, not bare substrings.
+      // A bare `denied`/`timeout` substring matches file names such as
+      // `workflow-mutation-denied.js` and misclassifies the failure.
       let category = 'unknown';
-      if (/SyntaxError|Unexpected token|Syntax Error/i.test(errorText)) {
+      if (/\bSyntaxError\b|Unexpected token|Syntax Error/i.test(errorText)) {
         category = 'syntax';
-      } else if (/ENOENT|not found|No such file|找不到|不存在/i.test(errorText)) {
+      } else if (/\bENOENT\b|\bnot found\b|No such file|找不到|不存在/i.test(errorText)) {
         category = 'environment';
-      } else if (/timeout|timed out|超時|逾時/i.test(errorText)) {
+      } else if (/\bETIMEDOUT\b|TimeoutError|\btimeout\b|\btimed out\b|\btiming out\b|超時|逾時/i.test(errorText)) {
         category = 'timeout';
       } else if (/test.*fail|assertion|AssertionError|測試.*失敗|斷言.*錯誤/i.test(errorText)) {
         category = 'test';
-      } else if (/permission|denied|EACCES|權限/i.test(errorText)) {
+      } else if (/\bpermission denied\b|\bEACCES\b|\bEPERM\b|權限.*(拒絕|不足|被拒)|拒絕.*權限/i.test(errorText)) {
         category = 'permission';
-      } else if (/dependency|module not found|Cannot find module|模組.*找不到/i.test(errorText)) {
+      } else if (/\bdependency\b|\bmodule not found\b|Cannot find module|模組.*找不到/i.test(errorText)) {
         category = 'dependency';
       }
 
@@ -114,7 +118,11 @@ process.stdin.on('end', () => {
       state.lastFailureAt = Date.now();
 
       fs.writeFileSync(stateFile, JSON.stringify(state, null, 2), 'utf8');
-    } else if (!isFailureEvent && explicitSuccess) {
+    } else if (!isFailure) {
+      // NOTE (#166, follows #153): Claude Code PostToolUse success payloads
+      // carry no numeric exit code. The lifecycle event is authoritative:
+      // PostToolUse is success unless a numeric non-zero status contradicts it;
+      // hosts without lifecycle event names keep the conservative stderr fallback.
       // A successful action after an accepted zoom-out is an objective recovery
       // boundary. Emit only IDs/hashes/category; never copy command/output text.
       if ((state.zoomOutCycles || 0) > 0 && state.lastHash) {