harness-everything 0.12.0 → 0.12.2

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "harness-everything",
       "source": "./",
       "description": "Harness OS: an orchestrated agent operating system — tier routing, circuit breaker guardrails, verification gates, WAL session memory, and self-evolving workspace rules.",
-      "version": "0.12.0",
+      "version": "0.12.2",
       "author": {
         "name": "Miya Daniel"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "harness-everything",
   "description": "Harness OS: an orchestrated agent operating system — tier routing, circuit breaker guardrails, verification gates, WAL session memory, and self-evolving workspace rules.",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "author": {
     "name": "Miya Daniel"
   },

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 All notable changes to this project are documented in this file.
 
+## [0.12.2](https://github.com/dyphn1/Harness-everything/compare/v0.12.1...v0.12.2) (2026-09-19)
+
+### Bug Fixes
+
+* **workflow:** admit observation-only verification at limit ([08b859e](https://github.com/dyphn1/Harness-everything/commit/08b859ef27c04a07d9a0a6faeeed52f3da986378))
+* **workflow:** admit observation-only verification at limit ([8924a3c](https://github.com/dyphn1/Harness-everything/commit/8924a3cc80455592accbe81e3f2df0f4479a2d8b))
+* **workflow:** allow verification probe at iteration limit ([7ce511e](https://github.com/dyphn1/Harness-everything/commit/7ce511e29ca368371d996f4cbeff02298d97434c))
+* **workflow:** allow verification probe at iteration limit ([07e6ed0](https://github.com/dyphn1/Harness-everything/commit/07e6ed0b369e38f274ac099af590b12373b1ad1c))
+
+## [0.12.1](https://github.com/dyphn1/Harness-everything/compare/v0.12.0...v0.12.1) (2026-09-19)
+
+### Bug Fixes
+
+* **workflow:** bind probe lease to tool timeout ([bb8c598](https://github.com/dyphn1/Harness-everything/commit/bb8c598792530f7a06f8514c51dc9905fc78935c))
+* **workflow:** bind probe lease to tool timeout ([025d6eb](https://github.com/dyphn1/Harness-everything/commit/025d6eb899be92598836ddc0c25c2eced8d4d190))
+* **workflow:** discard unchanged stale probe orphans ([aa8d238](https://github.com/dyphn1/Harness-everything/commit/aa8d238199285b7338edf6b87495cd7454a440ac))
+* **workflow:** discard unchanged stale probe orphans ([49fa840](https://github.com/dyphn1/Harness-everything/commit/49fa8409eb337a8acb5f6149323298b0b82027e8))
+* **workflow:** keep active mutation probes leased ([c62831f](https://github.com/dyphn1/Harness-everything/commit/c62831f64d6b5e3991b4cde34a0bf263c7cab2e7))
+* **workflow:** keep active mutation probes leased ([23f8b3d](https://github.com/dyphn1/Harness-everything/commit/23f8b3d646747f7e538061490a1a9bbf05fb8c39))
+* **workflow:** key shell probes by stable tool-use identity ([4d24ca6](https://github.com/dyphn1/Harness-everything/commit/4d24ca6f538f1c1ca0d3165c1b8adce930a8d9d4))
+* **workflow:** key shell probes by stable tool-use identity ([56c24b4](https://github.com/dyphn1/Harness-everything/commit/56c24b49748d9bd74cc3fe634cce291a691baa15))
+* **workflow:** persist probe observation cwd ([51c5894](https://github.com/dyphn1/Harness-everything/commit/51c58945dbed392424e4690f6be78ad68db8ecbf))
+* **workflow:** persist probe observation cwd ([9e361f1](https://github.com/dyphn1/Harness-everything/commit/9e361f1233f08f2f74c376c38e5d34dab017cbae))
+* **workflow:** reclaim stale mutation-probe reservations ([fe613ec](https://github.com/dyphn1/Harness-everything/commit/fe613ec7cdea09e8b535e60f8a1a6468f649006d))
+* **workflow:** reclaim stale mutation-probe reservations ([62f44d0](https://github.com/dyphn1/Harness-everything/commit/62f44d0f455ea3baf14b864aa33b1c868c6ef945))
+* **workflow:** settle probes from their pre-tool workspace ([e16f7da](https://github.com/dyphn1/Harness-everything/commit/e16f7da4a2290afb1603e9c82b775b4fc6872acb))
+* **workflow:** settle probes from their pre-tool workspace ([a7cce6c](https://github.com/dyphn1/Harness-everything/commit/a7cce6c5d7369bd40565978534c09687c8101408))
+* **workflow:** use conservative default probe timeout ([e4d4e0f](https://github.com/dyphn1/Harness-everything/commit/e4d4e0f0f31d9feed068eb98abcba961c4ee078a))
+* **workflow:** use conservative default probe timeout ([1393450](https://github.com/dyphn1/Harness-everything/commit/13934502a715b1cfa3b8caa76a300b38f0059afd))
+
 ## [0.12.0](https://github.com/dyphn1/Harness-everything/compare/v0.11.7...v0.12.0) (2026-09-19)
 
 ### Features

package/README.md

@@ -255,6 +255,7 @@ For a deep dive into individual modules and the underlying philosophy, explore o
 
 * [Harness Philosophy](docs/philosophy.md): The core behavior-first, intervention-only design.
 * [Harness Architecture](docs/architecture.md): Lifecycle hooks, security model, and data locality.
+* [Enforcement and Lock Diagnostic Flows](docs/enforcement-locks.md): Identify which gate blocked progress, why it fired, and how to recover.
 * [Platform Capability Matrix](docs/platform-capabilities.md): Canonical current enforcement/install/evidence boundary per surface.
 * [Repository Runtime & Workflow Contract](docs/repository-contract.md): Generated Node/action/workflow/gate state used by consistency CI.
 * [OpenAI / ChatGPT Plugin Packaging](docs/openai-plugin.md): Local Codex/OpenAI plugin packaging plus public Skills-only submission boundary.

package/ci/mechanism-2ah-workflow-lifecycle.test.js

@@ -45,9 +45,15 @@ const persistDirect = (tool, input, cwd = repo, response = {}) => node('hooks/sc
   tool_response: response,
 });
 let toolUseSeq = 0;
-function beginShell(command, cwd = repo) {
+function beginShell(command, cwd = repo, extraToolInput = {}) {
   const toolUseId = 'toolu_fixture_' + (++toolUseSeq);
-  const input = { ...payload, cwd, tool_name: 'Bash', tool_use_id: toolUseId, tool_input: { command } };
+  const input = {
+    ...payload,
+    cwd,
+    tool_name: 'Bash',
+    tool_use_id: toolUseId,
+    tool_input: { command, ...extraToolInput },
+  };
   return { command, cwd, toolUseId, result: node('hooks/scripts/workflow-gate.js', input) };
 }
 function persistShell(call, response = {}, hookEvent = 'PostToolUse') {
@@ -84,6 +90,13 @@ const probeFiles = () => {
   try { return fs.readdirSync(probeDir).filter(name => /^[a-f0-9]{64}\.json$/.test(name)); }
   catch (_) { return []; }
 };
+function ageProbeFiles(ms = 60000) {
+  for (const name of probeFiles()) {
+    const target = path.join(probeDir, name);
+    const probe = read(target);
+    write(target, { ...probe, observedAt: Date.now() - ms, reclaimAfterAt: Date.now() - 1 });
+  }
+}
 const stop = extra => node('hooks/scripts/workflow-stop-gate.js', { ...payload, ...extra });
 const control = (...args) => node('hooks/scripts/workflow-disposition.js', null, [args[0], '--session-id', sessionId, ...args.slice(1)]);
 function fixtureSession(fixtureSessionId) {
@@ -190,6 +203,58 @@ try {
   git(['init']); fs.writeFileSync(path.join(repo, 'README.md'), 'fixture\n'); git(['add', '.']);
   git(['-c', 'user.name=Harness Test', '-c', 'user.email=harness@example.invalid', 'commit', '-m', 'fixture']);
   git(['worktree', 'add', linked, '-b', 'isolated']);
+
+  // #164: the mutation budget is an edit budget, not a reason to make the
+  // final edit unverifiable. At the exact limit a verification-shaped shell
+  // gets observation-only admission. No-effect verification may complete the
+  // workflow; a verification command that mutates still exhausts after Post.
+  const finalVerify = fixtureSession('workflow-final-iteration-verify');
+  check(finalVerify.route('Fix this checkout bug with a regression test').status === 0 &&
+    finalVerify.control('start').status === 0,
+    '#164 final-iteration verification fixture starts Tier 2');
+  const finalVerifyLimit = read(finalVerify.file).workflowPlan.limits.maxIterations;
+  for (let i = 0; i < finalVerifyLimit; i++) {
+    check(finalVerify.gate('Write', { file_path: path.join(repo, 'final-verify-' + i + '.txt') }).status === 0,
+      '#164 confirmed mutation fills iteration budget ' + (i + 1) + '/' + finalVerifyLimit);
+  }
+  check(read(finalVerify.file).budget.counters.iterations === finalVerifyLimit,
+    '#164 fixture reaches the exact mutation limit while still running');
+  const finalVerifyId = 'toolu_final_iteration_verify';
+  check(finalVerify.gate('Bash', { command: 'node run-test.js' }, { tool_use_id: finalVerifyId }).status === 0,
+    '#164 no-effect verification shell is admitted at the exact mutation limit');
+  check(finalVerify.persist('Bash', { command: 'node run-test.js' }, { stdout: 'tests passed' },
+    { tool_use_id: finalVerifyId }).status === 0,
+    '#164 no-effect verification settles without exhausting the budget');
+  check(read(finalVerify.file).budget.counters.iterations === finalVerifyLimit &&
+    read(finalVerify.file).state === 'running',
+    '#164 no-effect verification preserves the full mutation count and running state');
+  check(finalVerify.stop().status === 0 && read(finalVerify.file).state === 'satisfied',
+    '#164 verification after the final allowed edit can satisfy Stop');
+
+  const finalMutator = fixtureSession('workflow-final-iteration-mutator');
+  check(finalMutator.route('Fix this checkout bug with a regression test').status === 0 &&
+    finalMutator.control('start').status === 0,
+    '#164 at-limit mutator fixture starts Tier 2');
+  const finalMutatorLimit = read(finalMutator.file).workflowPlan.limits.maxIterations;
+  for (let i = 0; i < finalMutatorLimit; i++) {
+    check(finalMutator.gate('Write', { file_path: path.join(repo, 'final-mutator-' + i + '.txt') }).status === 0,
+      '#164 mutator fixture fills iteration budget ' + (i + 1) + '/' + finalMutatorLimit);
+  }
+  const finalMutatorId = 'toolu_final_iteration_mutator';
+  check(finalMutator.gate('Bash', { command: 'node run-test-and-mutate.js' }, { tool_use_id: finalMutatorId }).status === 0,
+    '#164 verification-shaped command receives observation-only admission at limit');
+  const finalOverflowTarget = path.join(repo, 'final-iteration-overflow.txt');
+  fs.writeFileSync(finalOverflowTarget, 'mutation beyond limit\n');
+  check(finalMutator.persist('Bash', { command: 'node run-test-and-mutate.js' }, { stdout: 'changed' },
+    { tool_use_id: finalMutatorId }).status === 2,
+    '#164 at-limit verification-shaped command that mutates is rejected on observation');
+  const finalMutatorState = read(finalMutator.file);
+  check(finalMutatorState.state === 'blocked' &&
+    finalMutatorState.budget?.state === 'budget-exhausted' &&
+    finalMutatorState.budget?.reasonCode === 'iteration-budget-exhausted',
+    '#164 observed mutation beyond the limit leaves an auditable blocked workflow');
+  fs.unlinkSync(finalOverflowTarget);
+
   const taskNotification = '<task-notification><summary>Background command "Run full test suite" failed with exit code 1</summary></task-notification>';
   const unboundNotification = node('harness-everything/scripts/kernel-router.js', { cwd: repo, prompt: taskNotification });
   check(unboundNotification.status === 0 &&
@@ -524,6 +589,112 @@ try {
       'no-effect untrusted shell command does not advance lastMutationAt');
   }
 
+  // #161: Post payload cwd may differ from Pre payload cwd after a shell
+  // command changes directories. Stable tool_use_id identity plus the stored
+  // Pre-time observation cwd must settle the original probe.
+  const driftCwd = path.join(repo, 'hooks');
+  fs.mkdirSync(driftCwd, { recursive: true });
+  const driftNoEffectBefore = read(file);
+  const driftNoEffect = beginShell('cd hooks && node -e "process.exit(0)"', repo);
+  check(driftNoEffect.result.status === 0 && probeFiles().length === 1,
+    '#161 cwd-drift no-effect call registers one probe');
+  const driftNoEffectPost = node('hooks/scripts/state-persist.js', {
+    ...payload,
+    cwd: driftCwd,
+    hook_event_name: 'PostToolUse',
+    tool_name: 'Bash',
+    tool_use_id: driftNoEffect.toolUseId,
+    tool_input: { command: driftNoEffect.command },
+    tool_response: { stdout: 'ok' },
+  });
+  check(driftNoEffectPost.status === 0 && probeFiles().length === 0,
+    '#161 Post with drifted cwd settles the Pre-time probe');
+  check((read(file).budget?.counters?.iterations || 0) === (driftNoEffectBefore.budget?.counters?.iterations || 0),
+    '#161 cwd-drift no-effect shell consumes zero iterations');
+
+  const driftMutationBefore = read(file);
+  const driftMutation = beginShell('cd hooks && node mutate-from-subdir.js', repo);
+  check(driftMutation.result.status === 0, '#161 cwd-drift mutator is admitted under observation');
+  fs.writeFileSync(path.join(repo, 'drift-mutated.txt'), 'changed under cwd drift\n');
+  const driftMutationPost = node('hooks/scripts/state-persist.js', {
+    ...payload,
+    cwd: driftCwd,
+    hook_event_name: 'PostToolUse',
+    tool_name: 'Bash',
+    tool_use_id: driftMutation.toolUseId,
+    tool_input: { command: driftMutation.command },
+    tool_response: { stdout: 'changed' },
+  });
+  const driftMutationAfter = read(file);
+  check(driftMutationPost.status === 0 && probeFiles().length === 0 &&
+    (driftMutationAfter.budget?.counters?.iterations || 0) === (driftMutationBefore.budget?.counters?.iterations || 0) + 1 &&
+    driftMutationAfter.lastMutationAt >= (driftMutationBefore.lastMutationAt || 0),
+    '#161 cwd-drift real mutation is observed exactly once');
+
+  // A live command may legitimately run longer than the old 1s grace period.
+  // Its probe must remain reserved until the declared tool timeout expires.
+  const longRunningStateBefore = read(file);
+  const longRunningBefore = longRunningStateBefore.budget.counters.iterations;
+  const longRunningA = beginShell('node long-running-mutator.js', repo, { timeout: 60000 });
+  check(longRunningA.result.status === 0 && probeFiles().length === 1,
+    '#161 long-running call registers one timeout-bound probe');
+  {
+    const target = path.join(probeDir, probeFiles()[0]);
+    const probe = read(target);
+    write(target, { ...probe, observedAt: Date.now() - 2000 });
+  }
+  const concurrentB = beginShell('node concurrent-observer.js', repo, { timeout: 60000 });
+  check(concurrentB.result.status === 0 && probeFiles().length === 2,
+    '#161 a second Pre does not reclaim an in-flight probe merely because it is older than 1s');
+  fs.writeFileSync(path.join(repo, 'long-running-mutated.txt'), 'changed by long-running A\n');
+  check(persistShell(longRunningA).status === 0 &&
+    read(file).budget.counters.iterations === longRunningBefore + 1,
+    '#161 long-running A still settles and records its later mutation');
+  check(denyShell(concurrentB).status === 0 && probeFiles().length === 0,
+    '#161 concurrent non-mutating probe can be denied independently after A settles');
+  fs.rmSync(path.join(repo, 'long-running-mutated.txt'), { force: true });
+  write(file, longRunningStateBefore);
+  check(read(file).budget.counters.iterations === longRunningBefore,
+    '#161 long-running regression restores the shared fixture budget before later boundary tests');
+
+  // Simulate default-mode denial / sibling PreToolUse blocking: Pre fires but
+  // neither PostToolUse nor PermissionDenied follows. Force each orphan past
+  // its timeout-bound reclaim deadline so the next real Pre can reclaim it
+  // deterministically without sleeping in CI.
+  const orphanStartIterations = read(file).budget.counters.iterations;
+  for (let i = 0; i < iterationLimit; i++) {
+    const orphan = beginShell('node rejected-before-exec-' + i + '.js', repo);
+    check(orphan.result.status === 0, '#161 Pre-only orphan ' + (i + 1) + ' is initially admitted');
+    ageProbeFiles();
+  }
+  check(workflowRuntime.mutationProbeReservations(workflowRuntime.loadWorkflow(payload)) === 0,
+    '#161 stale Pre-only probes no longer reserve iteration capacity');
+  const harmlessAfterOrphans = beginShell('node harmless-after-orphans.js', repo);
+  check(harmlessAfterOrphans.result.status === 0 && probeFiles().length === 1,
+    '#161 next harmless untrusted shell is admitted after maxIterations Pre-only orphans');
+  check(persistShell(harmlessAfterOrphans).status === 0 && probeFiles().length === 0,
+    '#161 orphan reclamation leaves only the live probe and it settles normally');
+  check(read(file).budget.counters.iterations === orphanStartIterations,
+    '#161 rejected/no-effect orphan sequence consumes zero iterations');
+
+  // If an orphan really did mutate the workspace, reclaim must account for it
+  // once rather than silently dropping evidence.
+  const staleMutation = beginShell('node orphaned-mutator.js', repo);
+  check(staleMutation.result.status === 0, '#161 stale-mutator probe is registered');
+  ageProbeFiles();
+  const staleMutationBefore = read(file);
+  fs.writeFileSync(path.join(repo, 'stale-probe-mutated.txt'), 'changed before missing Post\n');
+  const reclaimTrigger = beginShell('node reclaim-trigger.js', repo);
+  const reclaimed = read(file);
+  check(reclaimTrigger.result.status === 0 &&
+    reclaimed.budget.counters.iterations === staleMutationBefore.budget.counters.iterations + 1 &&
+    reclaimed.lastMutationAt >= (staleMutationBefore.lastMutationAt || 0),
+    '#161 stale probe with workspace change is reclaimed as exactly one mutation');
+  check(persistShell(reclaimTrigger).status === 0 &&
+    read(file).budget.counters.iterations === reclaimed.budget.counters.iterations &&
+    probeFiles().length === 0,
+    '#161 reclaimed stale mutation is not double-counted by the trigger Post');
+
   const deniedCall = beginShell('node denied-by-auto-mode.js');
   check(deniedCall.result.status === 0 && probeFiles().length === 1,
     'auto-mode candidate reserves mutation capacity before permission decision');

package/docs/enforcement-locks.md

@@ -0,0 +1,114 @@
+# Enforcement and Lock Diagnostic Flows
+
+Harness has several mechanisms that can deny a tool call or delay completion. Only one of them is a repeated-failure circuit breaker. Use the emitted mechanism name and the flows below before describing a denial as a lock problem.
+
+This guide describes the repository's current hook wiring. Mechanical enforcement depends on the host and installation surface; see [Platform Capability Matrix](platform-capabilities.md) before generalizing a behavior to every host.
+
+## Lifecycle map
+
+On the Claude hook surface, a request enters the router before tool use. Pre-tool gates decide whether a tool call may start, post-tool hooks record outcomes, and stop gates decide whether the turn may finish.
+
+```mermaid
+flowchart TD
+    A["User prompt"] --> B["Kernel router<br/>select workflow contract"]
+    B --> C["Pre-tool gates"]
+    C --> D{"Tool allowed?"}
+    D -- "No" --> E["Emit gate-specific reason<br/>and recovery"]
+    D -- "Yes" --> F["Execute tool"]
+    F --> G["Post-tool outcome tracking"]
+    G --> H{"Turn stopping?"}
+    H -- "No" --> C
+    H -- "Yes" --> I["Completion gates"]
+    I --> J{"Obligations resolved?"}
+    J -- "Yes" --> K["Evidence-backed completion"]
+    J -- "No" --> E
+```
+
+The important separation is:
+
+- **Pre-tool denial:** the requested operation did not run.
+- **Post-tool tracking:** the operation ran and its outcome updated state.
+- **Stop denial:** the turn cannot claim completion yet; it does not necessarily prevent the next tool call.
+- **Approval request:** the exact destructive or external action waits for authorization; it is not a retry lock.
+
+## Which mechanism stopped progress?
+
+Start with the prefix in the error or hook message. Do not infer the mechanism only from the fact that a command did not run.
+
+```mermaid
+flowchart TD
+    A["Operation or completion blocked"] --> B{"Message prefix or condition"}
+    B -- "RULE OF 3" --> C["Repeated-failure circuit breaker"]
+    B -- "Workflow gate" --> D["Workflow entry, state,<br/>run, or worktree precondition"]
+    B -- "Action gate or permission" --> E["Exact side effect needs approval"]
+    B -- "Workflow Completion Gate" --> F["Selected workflow obligations unresolved"]
+    B -- "Stop Gate" --> G["Edits lack later successful verification"]
+    B -- "Boundary, depth, context,<br/>or scope guard" --> H["Guard-specific policy denial"]
+    C --> I["Follow Rule of 3 recovery flow"]
+    D --> J["Satisfy named workflow precondition"]
+    E --> K["Approve, reject, or change exact payload"]
+    F --> L["Resolve stages or report blocked state"]
+    G --> M["Run a relevant check or state why not applicable"]
+    H --> N["Follow the emitted guard reason"]
+```
+
+If a message has no Harness prefix, check the host permission system and the tool's own error before changing Harness state.
+
+## Mechanism reference
+
+| Mechanism | Trigger | What it blocks | State and persistence | Recovery |
+|---|---|---|---|---|
+| Rule of 3 | The same normalized shell failure signature reaches its category threshold. Defaults to 3; timeout and permission use 2; environment and dependency use 4. | Mutating tools. Read-only investigation remains available, and the required zoom-out report is the only permitted write. | Session-scoped `rule-of-3-state.json`. A second trip of the same signature after one accepted reflection becomes a human-decision hard lock. | First trip: produce a fresh valid `zoom-out-report.md`. Repeat trip: human runs `npm run harness:reset`, starts a new session, or uses `/clear`. |
+| Workflow gate | Active workflow state or entry contract is incompatible with the requested mutation; examples include blocked/failed/satisfied state, missing correlated Fable run, or missing linked worktree for major work. | The requested mutation. Read-only commands and trusted workflow-controller commands have narrow exceptions. | Session workflow state. Major-workflow isolation is a hard precondition, not an automatic fallback. | Use the exact message: enter a linked worktree, start/replan through the controller, resolve blocked state, or submit a new task after satisfaction. |
+| Action gate | A shell rule or structured destructive/external action matches the policy. | Only the exact action payload; its hash is used for audit correlation. | Approval/audit state records pending, executed, failed, or rejected disposition. | Approve or reject through the host flow, or change the action. Approval of one payload does not authorize a different payload. |
+| Workflow completion gate | A selected workflow is stopping with unresolved stage, correlation, or verification obligations. | Completion. On a repeated stop-hook attempt it records a blocked state instead of looping forever. | `workflow-run.json` plus correlated stage/handoff state. | Resolve the named obligation. If genuinely blocked, report the blocker rather than claim completion. |
+| Ordinary stop gate | A dirty tree contains edits with no later successful verification-like command. | Completion once per edit batch. It is intentionally a bounce, not a persistent cage. | `stop-gate-state.json` remembers the edit timestamp already bounced. | Run a targeted test/build/lint check, or explicitly state why verification is not applicable and stop again. |
+| Boundary/depth/context/scope guards | A guard-specific read, write, context-pressure, or subagent-scope condition matches. | The matching tool or workflow step. | Mechanism-specific; these are not Rule of 3 counters. | Follow the emitted reason and the corresponding architecture documentation. |
+
+## Rule of 3 state transitions
+
+The tracker hashes a normalized failure together with category, file path, and command context. A different signature starts a new counter. A confirmed successful action clears recovery state.
+
+```mermaid
+stateDiagram-v2
+    [*] --> Counting
+    Counting --> Counting: same signature below threshold
+    Counting --> Reflecting: threshold reached
+    Reflecting --> Counting: valid fresh report with RESUME
+    Reflecting --> Escalating: valid fresh report with ESCALATE
+    Counting --> HardLocked: same signature trips after reflection
+    HardLocked --> [*]: human reset or new session
+    Counting --> [*]: confirmed success
+    Escalating --> HardLocked: mutation retried and signature trips again
+```
+
+A valid reflection report must be newer than the failure that tripped the breaker, contain `Goal`, `Failed Attempts`, `Verified Facts`, `Diagnosis`, and `Decision`, and end in a `RESUME` or `ESCALATE` decision. A stale report cannot release a later trip.
+
+## Pre-tool ordering and overlapping denials
+
+The configured Claude pre-tool order is workflow gate, action gate, Rule of 3, then the narrower boundary/depth/context/scope guards for their matched tools. This means the first emitted denial identifies the condition reached on that call; it does not prove that every later gate would pass.
+
+For example:
+
+1. A force push may first fail the workflow gate if the selected workflow has not been entered.
+2. After workflow entry is fixed, the action gate may still require approval for the same force push.
+3. Rule of 3 is relevant only when repeated tracked failures reached the signature threshold; it should not be reset to bypass workflow or approval requirements.
+
+Treat each denial independently and re-evaluate after satisfying its stated condition.
+
+## Host and evidence boundary
+
+The hook sequence above is the canonical Claude package wiring. The local OpenAI/Codex plugin packages related lifecycle adapters, while general installer paths and the public Skills-only artifact may be advisory rather than mechanically enforced. OpenCode has a separate plugin implementation and a narrower retained live-host evidence boundary.
+
+Repository mechanism tests show that packaged code follows its tested contract. They do not by themselves prove that a particular live host loaded the package, fired the hook, or improved agent behavior. Record live-host evidence before making that stronger claim.
+
+## Source map
+
+Use these implementation files when this guide and runtime appear to disagree:
+
+- `hooks/hooks.json` — lifecycle wiring and order.
+- `hooks/scripts/rule-of-3.js` and `rule-of-3-tracker.js` — counter, thresholds, reflection, and hard-lock behavior.
+- `hooks/scripts/workflow-gate.js` and `workflow-stop-gate.js` — mutation and completion workflow contracts.
+- `hooks/scripts/action-gate.js` and `action-gate-rules.json` — approval policy and audit behavior.
+- `hooks/scripts/stop-gate.js` — ordinary one-bounce verification behavior.
+- [Harness Architecture](architecture.md) and [Workflow Runtime](workflow-runtime.md) — broader runtime contracts and limitations.

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

@@ -76,10 +76,18 @@ function workspaceFingerprint(cwd) {
 function shellProbeKey(payload, cwd) {
   const toolUseId = String(payload?.tool_use_id || payload?.toolUseId || '').trim();
   const tool = String(payload?.tool_name || payload?.tool || '');
+  if (toolUseId) {
+    // Host tool-use identity is stable across Pre/Post payload cwd drift.
+    return crypto.createHash('sha256')
+      .update('harness-shell-probe-v3\0')
+      .update(toolUseId).update('\0')
+      .update(tool)
+      .digest('hex');
+  }
+  // Compatibility fallback for hosts that do not expose tool_use_id.
   const command = commandOf(payload);
   return crypto.createHash('sha256')
-    .update('harness-shell-probe-v2\0')
-    .update(toolUseId || 'no-tool-use-id').update('\0')
+    .update('harness-shell-probe-v2-fallback\0')
     .update(tool).update('\0')
     .update(key(cwd)).update('\0')
     .update(command)
@@ -127,6 +135,11 @@ function linkedWorktree(cwd, boundRoot) {
 // Unsupported shell syntax still fails closed.
 const DANGEROUS_FLAG_RE = /\s(?:--(?:output|ext-diff|textconv|exec|pre|pre-glob|pager|open|batch|filters)|-[xoO])(?:\b|=)|\s-(?:exec|execdir|delete|fprint|fprintf)\b/i;
 const READ_ONLY_PREFIX_RE = /^(?:git\s+(?:status|rev-parse|diff|log|show|ls-files|check-ignore)(?:\s|$)|git\s+branch\s+--show-current$|git\s+worktree\s+list(?:\s|$)|gh\s+(?:issue|pr)\s+(?:view|list)(?:\s|$)|gh\s+repo\s+view(?:\s|$)|gh\s+auth\s+status(?:\s|$)|(?:pwd|ls|dir|cat|type|head|tail|wc|stat|rg|grep|echo|Get-Location|Get-ChildItem|Get-Content|Select-String|Test-Path)(?:\s|$))/i;
+const VERIFY_COMMAND_RE = /\b(test|spec|jest|vitest|mocha|pytest|rspec|phpunit|tsc|eslint|lint|build|compile|verify|check)\b/i;
+
+function isVerificationShell(command) {
+  return VERIFY_COMMAND_RE.test(String(command || ''));
+}
 
 function isReadOnlySegment(segment) {
   return READ_ONLY_PREFIX_RE.test(segment) && !DANGEROUS_FLAG_RE.test(segment);
@@ -303,4 +316,4 @@ function assertShellScope(command, cwd, isolatedRoot) {
   }
 }
 
-module.exports = { canonical, key, within, linkedWorktree, classifyShell, workspaceFingerprint, shellProbeKey, inputOf, cwdOf, commandOf, mutationPaths, worktreeRoots, directMutationInWorkspace, assertTargets, assertShellScope };
+module.exports = { canonical, key, within, linkedWorktree, classifyShell, isVerificationShell, workspaceFingerprint, shellProbeKey, inputOf, cwdOf, commandOf, mutationPaths, worktreeRoots, directMutationInWorkspace, assertTargets, assertShellScope };

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

@@ -4,6 +4,7 @@ const fs = require('fs');
 const path = require('path');
 const { getWorkspaceRoot, getSessionDir, getSessionId, getStateRoot } = require('./harness-state');
 const { atomicWriteJson, readJson } = require('./fable-contracts');
+const { workspaceFingerprint } = require('./workflow-isolation');
 
 const OPEN_STATES = new Set(['pending', 'active', 'running', 'failed', 'blocked', 'escaped']);
 const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
@@ -45,6 +46,25 @@ 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));
+const MUTATION_PROBE_DEFAULT_TIMEOUT_MS = 120000;
+const MUTATION_PROBE_RECLAIM_GRACE_MS = 5000;
+const MUTATION_PROBE_MAX_TIMEOUT_MS = 30 * 60 * 1000;
+
+function mutationProbeLeaseMs(timeoutMs) {
+  const parsed = Number(timeoutMs);
+  const executionMs = Number.isFinite(parsed) && parsed > 0
+    ? Math.min(parsed, MUTATION_PROBE_MAX_TIMEOUT_MS)
+    : MUTATION_PROBE_DEFAULT_TIMEOUT_MS;
+  return executionMs + MUTATION_PROBE_RECLAIM_GRACE_MS;
+}
+
+function mutationProbeExpired(probe, now = Date.now()) {
+  const reclaimAfterAt = Number(probe?.reclaimAfterAt);
+  if (Number.isFinite(reclaimAfterAt)) return now >= reclaimAfterAt;
+  const observedAt = Number(probe?.observedAt);
+  return Number.isFinite(observedAt) &&
+    now - observedAt >= mutationProbeLeaseMs(null);
+}
 
 function mutationProbeDir(context) {
   return path.join(context.sessionDir, 'mutation-probes');
@@ -81,15 +101,25 @@ function withMutationProbeLock(context, callback) {
   finally { fs.rmSync(lockDir, { recursive: true, force: true }); }
 }
 
+function probeCountsIteration(probe) {
+  return Boolean(probe && (probe.countIteration === true ||
+    (probe.countIteration === undefined && probe.reserveIteration === 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; }
+  const now = Date.now();
   let count = 0;
   for (const file of files) {
     const probe = readJson(path.join(dir, file));
-    if (probe?.schemaVersion === 1 && probe.reserveIteration === true) count++;
+    if (probe?.schemaVersion !== 1 || probe.reserveIteration !== true) continue;
+    // A reservation remains active for the host/tool execution timeout plus
+    // a grace period. This prevents a genuinely in-flight command from being
+    // reclaimed merely because it ran longer than an arbitrary short delay.
+    if (!mutationProbeExpired(probe, now)) count++;
   }
   return count;
 }
@@ -115,22 +145,95 @@ function assertIterationCapacity(context, evidence) {
   return { applicable: true, value: budget.counters.iterations, reserved, limit };
 }
 
-function registerMutationProbe(context, key, fingerprint, reserveIteration) {
+function reclaimStaleMutationProbes(context, keepKey) {
+  const dir = mutationProbeDir(context);
+  let files = [];
+  try { files = fs.readdirSync(dir).filter(file => /^[a-f0-9]{64}\.json$/.test(file)); }
+  catch (_) { return; }
+  const now = Date.now();
+  for (const name of files) {
+    const staleKey = name.slice(0, -'.json'.length);
+    if (staleKey === keepKey) continue;
+    const file = path.join(dir, name);
+    const probe = readJson(file);
+    if (!probe || probe.schemaVersion !== 1) continue;
+    if (!mutationProbeExpired(probe, now)) continue;
+    const countsIteration = probeCountsIteration(probe);
+    if (!probe.observationCwd) {
+      // Legacy probes predate stored observation roots and cannot be safely
+      // re-observed. Once outside the in-flight grace window they must not
+      // reserve capacity forever.
+      fs.unlinkSync(file);
+      continue;
+    }
+    let currentFingerprint;
+    try {
+      currentFingerprint = workspaceFingerprint(probe.observationCwd);
+    } catch (_) {
+      fs.unlinkSync(file);
+      context.workflow.lastMutationAt = now;
+      if (countsIteration && context.workflow.strategy === 'iterative-single') {
+        recordBudgetEvent(context, 'iteration', { evidence: 'shell:reclaimed-unobservable-workspace' });
+      } else {
+        saveWorkflow(context);
+      }
+      continue;
+    }
+    if (currentFingerprint !== probe.fingerprint) {
+      fs.unlinkSync(file);
+      context.workflow.lastMutationAt = now;
+      if (countsIteration && context.workflow.strategy === 'iterative-single') {
+        recordBudgetEvent(context, 'iteration', { evidence: 'shell:reclaimed-stale-workspace-mutation' });
+      } else {
+        saveWorkflow(context);
+      }
+      continue;
+    }
+    // No visible workspace effect after the grace window: this probe was
+    // orphaned by a denial/block/missing Post event. Discard it so it cannot
+    // reserve capacity or later attribute an unrelated mutation (#161).
+    fs.unlinkSync(file);
+  }
+}
+
+function registerMutationProbe(context, key, fingerprint, reserveIteration, observationCwd, options = {}) {
   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');
+    reclaimStaleMutationProbes(context, key);
+    let activeReservation = Boolean(reserveIteration);
+    let atLimitAllowance = false;
+    if (activeReservation) {
+      const budget = ensureWorkflowBudget(context.workflow);
+      const limit = budget.limits.maxIterations;
+      const reserved = mutationProbeReservations(context);
+      if (options.allowAtLimit === true && budget.state === 'active' && limit !== null &&
+          budget.counters.iterations === limit && reserved === 0) {
+        // Verification-shaped commands get observation-only admission at the
+        // exact mutation limit. If they mutate, settlement still records the
+        // mutation and exhausts the budget after execution (#164).
+        activeReservation = false;
+        atLimitAllowance = true;
+      } else {
+        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 observedAt = Date.now();
     const probe = {
       schemaVersion: 1,
       fingerprint,
-      reserveIteration: Boolean(reserveIteration),
-      observedAt: Date.now(),
+      reserveIteration: activeReservation,
+      countIteration: options.countIteration === undefined ? Boolean(reserveIteration) : Boolean(options.countIteration),
+      atLimitAllowance,
+      observationCwd: observationCwd ? path.resolve(observationCwd) : null,
+      observedAt,
+      reclaimAfterAt: observedAt + mutationProbeLeaseMs(options.timeoutMs),
     };
     atomicWriteJson(file, probe);
     return probe;
@@ -152,7 +255,7 @@ function settleMutationProbe(context, key, afterFingerprint, tool) {
     const changed = afterFingerprint !== probe.fingerprint;
     if (changed) {
       context.workflow.lastMutationAt = Date.now();
-      if (probe.reserveIteration && context.workflow.strategy === 'iterative-single') {
+      if (probeCountsIteration(probe) && context.workflow.strategy === 'iterative-single') {
         recordBudgetEvent(context, 'iteration', { evidence: String(tool || 'shell') + ':observed-workspace-mutation' });
       } else {
         saveWorkflow(context);
@@ -170,7 +273,7 @@ function settleMutationProbeConservative(context, key, tool, evidence = 'unobser
     refreshWorkflowForProbe(context);
     fs.unlinkSync(file);
     context.workflow.lastMutationAt = Date.now();
-    if (probe.reserveIteration && context.workflow.strategy === 'iterative-single') {
+    if (probeCountsIteration(probe) && context.workflow.strategy === 'iterative-single') {
       recordBudgetEvent(context, 'iteration', { evidence: String(tool || 'shell') + ':' + evidence });
     } else {
       saveWorkflow(context);

package/hooks/scripts/state-persist.js

@@ -3,14 +3,9 @@ const fs = require('fs');
 const path = require('path');
 const { getWorkspaceRoot, getSessionDir } = require('./lib/harness-state');
 const { loadWorkflow, saveWorkflow, isMajorWorkflow, peekMutationProbe, settleMutationProbe, settleMutationProbeConservative } = require('./lib/workflow-runtime');
-const { cwdOf, shellProbeKey, workspaceFingerprint, directMutationInWorkspace } = require('./lib/workflow-isolation');
+const { cwdOf, shellProbeKey, isVerificationShell, workspaceFingerprint, directMutationInWorkspace } = require('./lib/workflow-isolation');
 const { observeTool } = require('./lib/telemetry');
 
-// Commands that count as "verification ran" for the Stop gate
-// (hooks/scripts/stop-gate.js). Recall over precision: under-blocking the
-// gate is the correct failure direction, so a broad net is fine.
-const VERIFY_COMMAND_RE = /\b(test|spec|jest|vitest|mocha|pytest|rspec|phpunit|tsc|eslint|lint|build|compile|verify|check)\b/i;
-
 let inputData = '';
 const timeout = setTimeout(() => {
   processState(null);
@@ -37,10 +32,12 @@ function observeWorkspaceMutation(payload, root) {
   if (!context.workflow || context.workflow.state === 'deferred') return false;
   const cwd = cwdOf(payload, root);
   const probeKey = shellProbeKey(payload, cwd);
-  if (!peekMutationProbe(context, probeKey)) return false;
+  const probe = peekMutationProbe(context, probeKey);
+  if (!probe) return false;
+  const observationCwd = probe.observationCwd || cwd;
   let after;
   try {
-    after = workspaceFingerprint(cwd);
+    after = workspaceFingerprint(observationCwd);
   } catch (error) {
     if (!isMajorWorkflow(context.workflow)) {
       const conservative = settleMutationProbeConservative(context, probeKey, toolName, 'unobservable-workspace');
@@ -125,7 +122,7 @@ function processState(payload) {
       }
       if ((toolName === 'Bash' || toolName === 'PowerShell') && !isFailed) {
         const command = (payload.tool_input && payload.tool_input.command) || '';
-        if (VERIFY_COMMAND_RE.test(command)) {
+        if (isVerificationShell(command)) {
           state.lastVerifyAt = Date.now();
           state.lastVerifyExitCode = exitCode ?? null;
         }

package/hooks/scripts/workflow-gate.js

@@ -4,11 +4,20 @@
 const path = require('path');
 const fs = require('fs');
 const { loadWorkflow, saveWorkflow, isMajorWorkflow, matchingRun, registerMutationProbe, recordBudgetEvent, readHookInput, WORKFLOW_CONTROLLER_COMMANDS } = require('./lib/workflow-runtime');
-const { key, classifyShell, workspaceFingerprint, shellProbeKey, cwdOf, commandOf, mutationPaths, directMutationInWorkspace, linkedWorktree, assertTargets, assertShellScope } = require('./lib/workflow-isolation');
+const { key, classifyShell, isVerificationShell, workspaceFingerprint, shellProbeKey, cwdOf, commandOf, mutationPaths, directMutationInWorkspace, linkedWorktree, assertTargets, assertShellScope } = require('./lib/workflow-isolation');
 
 const DIRECT = new Set(['Edit', 'Write', 'apply_patch']);
 const SHELL = new Set(['Bash', 'PowerShell', 'exec_command']);
 
+function shellTimeoutMs(payload) {
+  const input = payload?.tool_input || payload?.input || {};
+  for (const value of [input.timeout_ms, input.timeoutMs, input.timeout, payload.timeout_ms, payload.timeoutMs]) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  }
+  return null;
+}
+
 function isController(command, cwd) {
   // One trusted local executable, literal arguments, no shell evaluation.
   if (/[;&|`\r\n<>$(){}]/.test(command)) return false;
@@ -79,7 +88,12 @@ function decide(payload) {
     return;
   }
   const probeKey = shellProbeKey(payload, cwd);
-  registerMutationProbe(context, probeKey, fingerprint, workflow.strategy === 'iterative-single');
+  const iterative = workflow.strategy === 'iterative-single';
+  registerMutationProbe(context, probeKey, fingerprint, iterative, cwd, {
+    countIteration: iterative,
+    allowAtLimit: iterative && isVerificationShell(command),
+    timeoutMs: shellTimeoutMs(payload),
+  });
 }
 
 readHookInput(decide);

package/opencode-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "harness-enforcement",
   "description": "Repository inventory for the opencode enforcement plugin and its standalone helper",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "runtime": "index.mjs",
   "hooks": {
     "verify": "hooks/verify.js"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harness-everything",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "description": "Harness OS: An Orchestrated Agent Operating System for AI-driven Development",
   "main": "harness-everything/scripts/bootstrap.js",
   "bin": {

package/plugins/harness-everything/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "harness-everything",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "description": "Invariant-first engineering harness for routing, verification, and failure recovery while preserving agent autonomy.",
   "author": {
     "name": "Miya Daniel",

package/plugins/harness-everything/hooks/scripts/lib/workflow-isolation.js

@@ -76,10 +76,18 @@ function workspaceFingerprint(cwd) {
 function shellProbeKey(payload, cwd) {
   const toolUseId = String(payload?.tool_use_id || payload?.toolUseId || '').trim();
   const tool = String(payload?.tool_name || payload?.tool || '');
+  if (toolUseId) {
+    // Host tool-use identity is stable across Pre/Post payload cwd drift.
+    return crypto.createHash('sha256')
+      .update('harness-shell-probe-v3\0')
+      .update(toolUseId).update('\0')
+      .update(tool)
+      .digest('hex');
+  }
+  // Compatibility fallback for hosts that do not expose tool_use_id.
   const command = commandOf(payload);
   return crypto.createHash('sha256')
-    .update('harness-shell-probe-v2\0')
-    .update(toolUseId || 'no-tool-use-id').update('\0')
+    .update('harness-shell-probe-v2-fallback\0')
     .update(tool).update('\0')
     .update(key(cwd)).update('\0')
     .update(command)
@@ -127,6 +135,11 @@ function linkedWorktree(cwd, boundRoot) {
 // Unsupported shell syntax still fails closed.
 const DANGEROUS_FLAG_RE = /\s(?:--(?:output|ext-diff|textconv|exec|pre|pre-glob|pager|open|batch|filters)|-[xoO])(?:\b|=)|\s-(?:exec|execdir|delete|fprint|fprintf)\b/i;
 const READ_ONLY_PREFIX_RE = /^(?:git\s+(?:status|rev-parse|diff|log|show|ls-files|check-ignore)(?:\s|$)|git\s+branch\s+--show-current$|git\s+worktree\s+list(?:\s|$)|gh\s+(?:issue|pr)\s+(?:view|list)(?:\s|$)|gh\s+repo\s+view(?:\s|$)|gh\s+auth\s+status(?:\s|$)|(?:pwd|ls|dir|cat|type|head|tail|wc|stat|rg|grep|echo|Get-Location|Get-ChildItem|Get-Content|Select-String|Test-Path)(?:\s|$))/i;
+const VERIFY_COMMAND_RE = /\b(test|spec|jest|vitest|mocha|pytest|rspec|phpunit|tsc|eslint|lint|build|compile|verify|check)\b/i;
+
+function isVerificationShell(command) {
+  return VERIFY_COMMAND_RE.test(String(command || ''));
+}
 
 function isReadOnlySegment(segment) {
   return READ_ONLY_PREFIX_RE.test(segment) && !DANGEROUS_FLAG_RE.test(segment);
@@ -303,4 +316,4 @@ function assertShellScope(command, cwd, isolatedRoot) {
   }
 }
 
-module.exports = { canonical, key, within, linkedWorktree, classifyShell, workspaceFingerprint, shellProbeKey, inputOf, cwdOf, commandOf, mutationPaths, worktreeRoots, directMutationInWorkspace, assertTargets, assertShellScope };
+module.exports = { canonical, key, within, linkedWorktree, classifyShell, isVerificationShell, workspaceFingerprint, shellProbeKey, inputOf, cwdOf, commandOf, mutationPaths, worktreeRoots, directMutationInWorkspace, assertTargets, assertShellScope };

package/plugins/harness-everything/hooks/scripts/lib/workflow-runtime.js

@@ -4,6 +4,7 @@ const fs = require('fs');
 const path = require('path');
 const { getWorkspaceRoot, getSessionDir, getSessionId, getStateRoot } = require('./harness-state');
 const { atomicWriteJson, readJson } = require('./fable-contracts');
+const { workspaceFingerprint } = require('./workflow-isolation');
 
 const OPEN_STATES = new Set(['pending', 'active', 'running', 'failed', 'blocked', 'escaped']);
 const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
@@ -45,6 +46,25 @@ 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));
+const MUTATION_PROBE_DEFAULT_TIMEOUT_MS = 120000;
+const MUTATION_PROBE_RECLAIM_GRACE_MS = 5000;
+const MUTATION_PROBE_MAX_TIMEOUT_MS = 30 * 60 * 1000;
+
+function mutationProbeLeaseMs(timeoutMs) {
+  const parsed = Number(timeoutMs);
+  const executionMs = Number.isFinite(parsed) && parsed > 0
+    ? Math.min(parsed, MUTATION_PROBE_MAX_TIMEOUT_MS)
+    : MUTATION_PROBE_DEFAULT_TIMEOUT_MS;
+  return executionMs + MUTATION_PROBE_RECLAIM_GRACE_MS;
+}
+
+function mutationProbeExpired(probe, now = Date.now()) {
+  const reclaimAfterAt = Number(probe?.reclaimAfterAt);
+  if (Number.isFinite(reclaimAfterAt)) return now >= reclaimAfterAt;
+  const observedAt = Number(probe?.observedAt);
+  return Number.isFinite(observedAt) &&
+    now - observedAt >= mutationProbeLeaseMs(null);
+}
 
 function mutationProbeDir(context) {
   return path.join(context.sessionDir, 'mutation-probes');
@@ -81,15 +101,25 @@ function withMutationProbeLock(context, callback) {
   finally { fs.rmSync(lockDir, { recursive: true, force: true }); }
 }
 
+function probeCountsIteration(probe) {
+  return Boolean(probe && (probe.countIteration === true ||
+    (probe.countIteration === undefined && probe.reserveIteration === 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; }
+  const now = Date.now();
   let count = 0;
   for (const file of files) {
     const probe = readJson(path.join(dir, file));
-    if (probe?.schemaVersion === 1 && probe.reserveIteration === true) count++;
+    if (probe?.schemaVersion !== 1 || probe.reserveIteration !== true) continue;
+    // A reservation remains active for the host/tool execution timeout plus
+    // a grace period. This prevents a genuinely in-flight command from being
+    // reclaimed merely because it ran longer than an arbitrary short delay.
+    if (!mutationProbeExpired(probe, now)) count++;
   }
   return count;
 }
@@ -115,22 +145,95 @@ function assertIterationCapacity(context, evidence) {
   return { applicable: true, value: budget.counters.iterations, reserved, limit };
 }
 
-function registerMutationProbe(context, key, fingerprint, reserveIteration) {
+function reclaimStaleMutationProbes(context, keepKey) {
+  const dir = mutationProbeDir(context);
+  let files = [];
+  try { files = fs.readdirSync(dir).filter(file => /^[a-f0-9]{64}\.json$/.test(file)); }
+  catch (_) { return; }
+  const now = Date.now();
+  for (const name of files) {
+    const staleKey = name.slice(0, -'.json'.length);
+    if (staleKey === keepKey) continue;
+    const file = path.join(dir, name);
+    const probe = readJson(file);
+    if (!probe || probe.schemaVersion !== 1) continue;
+    if (!mutationProbeExpired(probe, now)) continue;
+    const countsIteration = probeCountsIteration(probe);
+    if (!probe.observationCwd) {
+      // Legacy probes predate stored observation roots and cannot be safely
+      // re-observed. Once outside the in-flight grace window they must not
+      // reserve capacity forever.
+      fs.unlinkSync(file);
+      continue;
+    }
+    let currentFingerprint;
+    try {
+      currentFingerprint = workspaceFingerprint(probe.observationCwd);
+    } catch (_) {
+      fs.unlinkSync(file);
+      context.workflow.lastMutationAt = now;
+      if (countsIteration && context.workflow.strategy === 'iterative-single') {
+        recordBudgetEvent(context, 'iteration', { evidence: 'shell:reclaimed-unobservable-workspace' });
+      } else {
+        saveWorkflow(context);
+      }
+      continue;
+    }
+    if (currentFingerprint !== probe.fingerprint) {
+      fs.unlinkSync(file);
+      context.workflow.lastMutationAt = now;
+      if (countsIteration && context.workflow.strategy === 'iterative-single') {
+        recordBudgetEvent(context, 'iteration', { evidence: 'shell:reclaimed-stale-workspace-mutation' });
+      } else {
+        saveWorkflow(context);
+      }
+      continue;
+    }
+    // No visible workspace effect after the grace window: this probe was
+    // orphaned by a denial/block/missing Post event. Discard it so it cannot
+    // reserve capacity or later attribute an unrelated mutation (#161).
+    fs.unlinkSync(file);
+  }
+}
+
+function registerMutationProbe(context, key, fingerprint, reserveIteration, observationCwd, options = {}) {
   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');
+    reclaimStaleMutationProbes(context, key);
+    let activeReservation = Boolean(reserveIteration);
+    let atLimitAllowance = false;
+    if (activeReservation) {
+      const budget = ensureWorkflowBudget(context.workflow);
+      const limit = budget.limits.maxIterations;
+      const reserved = mutationProbeReservations(context);
+      if (options.allowAtLimit === true && budget.state === 'active' && limit !== null &&
+          budget.counters.iterations === limit && reserved === 0) {
+        // Verification-shaped commands get observation-only admission at the
+        // exact mutation limit. If they mutate, settlement still records the
+        // mutation and exhausts the budget after execution (#164).
+        activeReservation = false;
+        atLimitAllowance = true;
+      } else {
+        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 observedAt = Date.now();
     const probe = {
       schemaVersion: 1,
       fingerprint,
-      reserveIteration: Boolean(reserveIteration),
-      observedAt: Date.now(),
+      reserveIteration: activeReservation,
+      countIteration: options.countIteration === undefined ? Boolean(reserveIteration) : Boolean(options.countIteration),
+      atLimitAllowance,
+      observationCwd: observationCwd ? path.resolve(observationCwd) : null,
+      observedAt,
+      reclaimAfterAt: observedAt + mutationProbeLeaseMs(options.timeoutMs),
     };
     atomicWriteJson(file, probe);
     return probe;
@@ -152,7 +255,7 @@ function settleMutationProbe(context, key, afterFingerprint, tool) {
     const changed = afterFingerprint !== probe.fingerprint;
     if (changed) {
       context.workflow.lastMutationAt = Date.now();
-      if (probe.reserveIteration && context.workflow.strategy === 'iterative-single') {
+      if (probeCountsIteration(probe) && context.workflow.strategy === 'iterative-single') {
         recordBudgetEvent(context, 'iteration', { evidence: String(tool || 'shell') + ':observed-workspace-mutation' });
       } else {
         saveWorkflow(context);
@@ -170,7 +273,7 @@ function settleMutationProbeConservative(context, key, tool, evidence = 'unobser
     refreshWorkflowForProbe(context);
     fs.unlinkSync(file);
     context.workflow.lastMutationAt = Date.now();
-    if (probe.reserveIteration && context.workflow.strategy === 'iterative-single') {
+    if (probeCountsIteration(probe) && context.workflow.strategy === 'iterative-single') {
       recordBudgetEvent(context, 'iteration', { evidence: String(tool || 'shell') + ':' + evidence });
     } else {
       saveWorkflow(context);

package/plugins/harness-everything/hooks/scripts/state-persist.js

@@ -3,14 +3,9 @@ const fs = require('fs');
 const path = require('path');
 const { getWorkspaceRoot, getSessionDir } = require('./lib/harness-state');
 const { loadWorkflow, saveWorkflow, isMajorWorkflow, peekMutationProbe, settleMutationProbe, settleMutationProbeConservative } = require('./lib/workflow-runtime');
-const { cwdOf, shellProbeKey, workspaceFingerprint, directMutationInWorkspace } = require('./lib/workflow-isolation');
+const { cwdOf, shellProbeKey, isVerificationShell, workspaceFingerprint, directMutationInWorkspace } = require('./lib/workflow-isolation');
 const { observeTool } = require('./lib/telemetry');
 
-// Commands that count as "verification ran" for the Stop gate
-// (hooks/scripts/stop-gate.js). Recall over precision: under-blocking the
-// gate is the correct failure direction, so a broad net is fine.
-const VERIFY_COMMAND_RE = /\b(test|spec|jest|vitest|mocha|pytest|rspec|phpunit|tsc|eslint|lint|build|compile|verify|check)\b/i;
-
 let inputData = '';
 const timeout = setTimeout(() => {
   processState(null);
@@ -37,10 +32,12 @@ function observeWorkspaceMutation(payload, root) {
   if (!context.workflow || context.workflow.state === 'deferred') return false;
   const cwd = cwdOf(payload, root);
   const probeKey = shellProbeKey(payload, cwd);
-  if (!peekMutationProbe(context, probeKey)) return false;
+  const probe = peekMutationProbe(context, probeKey);
+  if (!probe) return false;
+  const observationCwd = probe.observationCwd || cwd;
   let after;
   try {
-    after = workspaceFingerprint(cwd);
+    after = workspaceFingerprint(observationCwd);
   } catch (error) {
     if (!isMajorWorkflow(context.workflow)) {
       const conservative = settleMutationProbeConservative(context, probeKey, toolName, 'unobservable-workspace');
@@ -125,7 +122,7 @@ function processState(payload) {
       }
       if ((toolName === 'Bash' || toolName === 'PowerShell') && !isFailed) {
         const command = (payload.tool_input && payload.tool_input.command) || '';
-        if (VERIFY_COMMAND_RE.test(command)) {
+        if (isVerificationShell(command)) {
           state.lastVerifyAt = Date.now();
           state.lastVerifyExitCode = exitCode ?? null;
         }

package/plugins/harness-everything/hooks/scripts/workflow-gate.js

@@ -4,11 +4,20 @@
 const path = require('path');
 const fs = require('fs');
 const { loadWorkflow, saveWorkflow, isMajorWorkflow, matchingRun, registerMutationProbe, recordBudgetEvent, readHookInput, WORKFLOW_CONTROLLER_COMMANDS } = require('./lib/workflow-runtime');
-const { key, classifyShell, workspaceFingerprint, shellProbeKey, cwdOf, commandOf, mutationPaths, directMutationInWorkspace, linkedWorktree, assertTargets, assertShellScope } = require('./lib/workflow-isolation');
+const { key, classifyShell, isVerificationShell, workspaceFingerprint, shellProbeKey, cwdOf, commandOf, mutationPaths, directMutationInWorkspace, linkedWorktree, assertTargets, assertShellScope } = require('./lib/workflow-isolation');
 
 const DIRECT = new Set(['Edit', 'Write', 'apply_patch']);
 const SHELL = new Set(['Bash', 'PowerShell', 'exec_command']);
 
+function shellTimeoutMs(payload) {
+  const input = payload?.tool_input || payload?.input || {};
+  for (const value of [input.timeout_ms, input.timeoutMs, input.timeout, payload.timeout_ms, payload.timeoutMs]) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  }
+  return null;
+}
+
 function isController(command, cwd) {
   // One trusted local executable, literal arguments, no shell evaluation.
   if (/[;&|`\r\n<>$(){}]/.test(command)) return false;
@@ -79,7 +88,12 @@ function decide(payload) {
     return;
   }
   const probeKey = shellProbeKey(payload, cwd);
-  registerMutationProbe(context, probeKey, fingerprint, workflow.strategy === 'iterative-single');
+  const iterative = workflow.strategy === 'iterative-single';
+  registerMutationProbe(context, probeKey, fingerprint, iterative, cwd, {
+    countIteration: iterative,
+    allowAtLimit: iterative && isVerificationShell(command),
+    timeoutMs: shellTimeoutMs(payload),
+  });
 }
 
 readHookInput(decide);

package/plugins/harness-everything/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "harness-everything",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "description": "Invariant-first engineering harness for routing, verification, and failure recovery while preserving agent autonomy.",
   "author": {
     "name": "Miya Daniel",