harness-everything 0.11.7 → 0.12.1

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/grill-with-docs/ADR-FORMAT.md

@@ -22,6 +22,28 @@ Only include these when they add genuine value. Most ADRs won't need them.
 - **Considered Options** — only when the rejected alternatives are worth remembering
 - **Consequences** — only when non-obvious downstream effects need to be called out
 
+## Decision lifecycle and contract lineage
+
+Once an ADR is **accepted**, keep its decision and rationale historically stable. Do not rewrite an accepted ADR to make a later design look as though it was always the decision.
+
+Use compact metadata when the ADR participates in a behavior contract:
+
+```md
+ADR-ID: ADR-0001
+Status: proposed | accepted | deprecated | superseded by ADR-0002
+Affected requirements: REQ-001, REQ-004
+```
+
+When a later change materially changes the decision or its rationale:
+
+1. create a new sequential ADR;
+2. state the new decision and why the prior trade-off changed;
+3. mark the earlier ADR `superseded by ADR-NNNN`;
+4. update the living spec requirements affected by that decision;
+5. let the structured contract trace carry detailed ticket/test/implementation lineage.
+
+A ticket or implementation note never silently becomes the new architectural source of truth. If only implementation changes and the approved behavior/decision does not, keep the accepted ADR unchanged.
+
 ## Numbering
 
 Scan `docs/adr/` for the highest existing number and increment by one.

package/grill-with-docs/SKILL.md

@@ -4,7 +4,7 @@ description: Challenge the plan against the existing domain model, sharpen termi
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.4.0
+  version: 0.12.0
 ---
 
 # Grill With Docs (Domain Modeling & Architectural Alignment)

package/hooks/scripts/lib/learning-opportunity.js

@@ -8,6 +8,7 @@ const {
   getSessionId,
   getSessionDir,
 } = require('./harness-state');
+const { emitLessonTelemetry } = require('./telemetry');
 
 const SCHEMA_VERSION = 1;
 const TRIGGERS = new Set(['rule-of-3-recovery', 'verifier-fail-pass']);
@@ -134,6 +135,27 @@ function createLearningOpportunity(payload, input = {}) {
     updatedAt: observedAt,
   };
   atomicWriteJson(file, candidate);
+  const lifecycleReasonCodes = [...candidate.trigger.reasonCodes, `trigger:${triggerType}`];
+  emitLessonTelemetry({
+    event: 'learning_opportunity',
+    root,
+    payload,
+    sessionId,
+    candidateId,
+    observedAt,
+    status: 'success',
+    reasonCodes: lifecycleReasonCodes,
+  });
+  emitLessonTelemetry({
+    event: 'lesson_proposed',
+    root,
+    payload,
+    sessionId,
+    candidateId,
+    observedAt,
+    status: 'success',
+    reasonCodes: lifecycleReasonCodes,
+  });
   return { created: true, file, candidate };
 }
 

package/hooks/scripts/lib/telemetry.js

@@ -6,11 +6,26 @@ const path = require('path');
 const { getWorkspaceRoot, getStateRoot, getSessionDir } = require('./harness-state');
 
 const TELEMETRY_SCHEMA_VERSION = 1;
+const LESSON_EVENT_TYPES = new Set([
+  'learning_opportunity',
+  'lesson_proposed',
+  'lesson_screened',
+  'lesson_evaluated',
+  'lesson_accepted',
+  'lesson_rejected',
+  'lesson_inconclusive',
+  'lesson_persisted',
+  'lesson_retrieved',
+  'lesson_validated',
+  'lesson_regressed',
+  'lesson_superseded',
+]);
 const EVENT_TYPES = new Set([
   'skill.invoke',
   'skill.loaded',
   'skill.complete',
   'tool.observed',
+  ...LESSON_EVENT_TYPES,
 ]);
 const STATUSES = new Set(['unknown', 'success', 'failure', 'aborted']);
 const FORBIDDEN_KEYS = new Set([
@@ -102,6 +117,29 @@ function telemetryFile(root, payload) {
   return path.join(getStateRoot(root || getWorkspaceRoot(payload), payload), 'telemetry', 'events.jsonl');
 }
 
+function emitLessonTelemetry(input = {}) {
+  const event = String(input.event || '');
+  if (!LESSON_EVENT_TYPES.has(event)) {
+    return { ok: false, error: `unsupported lesson telemetry event: ${event}`, overheadMs: 0 };
+  }
+  const invocationId = localId('lesson', input.candidateId);
+  if (!invocationId) {
+    return { ok: false, error: 'lesson telemetry requires candidateId', overheadMs: 0 };
+  }
+  return emitTelemetry({
+    event,
+    host: ['claude', 'codex', 'opencode', 'unknown'].includes(input.host)
+      ? input.host
+      : detectHost(input.payload || {}),
+    observedAt: input.observedAt || nowIso(),
+    sessionId: localId('session', input.sessionId),
+    invocationId,
+    skillName: 'self-evolve',
+    status: STATUSES.has(input.status) ? input.status : 'unknown',
+    reasonCodes: input.reasonCodes || [],
+  }, { root: input.root, payload: input.payload });
+}
+
 function emitTelemetry(input, options = {}) {
   const started = process.hrtime.bigint();
   try {
@@ -361,9 +399,11 @@ function readEvents(file) {
 module.exports = {
   EVENT_TYPES,
   FORBIDDEN_KEYS,
+  LESSON_EVENT_TYPES,
   STATUSES,
   TELEMETRY_SCHEMA_VERSION,
   detectHost,
+  emitLessonTelemetry,
   emitTelemetry,
   hostDuration,
   localId,

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)

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,78 @@ 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, timeoutMs) {
   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);
+    reclaimStaleMutationProbes(context, key);
     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 observedAt = Date.now();
     const probe = {
       schemaVersion: 1,
       fingerprint,
       reserveIteration: Boolean(reserveIteration),
-      observedAt: Date.now(),
+      countIteration: Boolean(reserveIteration),
+      observationCwd: observationCwd ? path.resolve(observationCwd) : null,
+      observedAt,
+      reclaimAfterAt: observedAt + mutationProbeLeaseMs(timeoutMs),
     };
     atomicWriteJson(file, probe);
     return probe;
@@ -152,7 +238,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);
@@ -162,6 +248,23 @@ function settleMutationProbe(context, key, afterFingerprint, tool) {
   });
 }
 
+function settleMutationProbeConservative(context, key, tool, evidence = 'unobservable-workspace') {
+  return withMutationProbeLock(context, () => {
+    const file = mutationProbeFile(context, key);
+    const probe = readJson(file);
+    if (!probe || probe.schemaVersion !== 1) return null;
+    refreshWorkflowForProbe(context);
+    fs.unlinkSync(file);
+    context.workflow.lastMutationAt = Date.now();
+    if (probeCountsIteration(probe) && context.workflow.strategy === 'iterative-single') {
+      recordBudgetEvent(context, 'iteration', { evidence: String(tool || 'shell') + ':' + evidence });
+    } else {
+      saveWorkflow(context);
+    }
+    return { changed: true, probe, conservative: true };
+  });
+}
+
 function discardMutationProbe(context, key) {
   return withMutationProbeLock(context, () => {
     const file = mutationProbeFile(context, key);
@@ -396,4 +499,4 @@ function readHookInput(decide) {
   process.stdin.on('error', finish);
 }
 
-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 };
+module.exports = { OPEN_STATES, SAFE_ID, WORKFLOW_CONTROLLER_COMMANDS, isMajorWorkflow, loadWorkflow, saveWorkflow, budgetLimits, ensureWorkflowBudget, mutationProbeReservations, assertIterationCapacity, registerMutationProbe, peekMutationProbe, settleMutationProbe, settleMutationProbeConservative, discardMutationProbe, clearMutationProbes, recordBudgetEvent, resetWorkflowBudget, syncBudgetToRun, matchingRun, unresolvedStages, readHookInput };

package/hooks/scripts/state-persist.js

@@ -2,7 +2,7 @@
 const fs = require('fs');
 const path = require('path');
 const { getWorkspaceRoot, getSessionDir } = require('./lib/harness-state');
-const { loadWorkflow, saveWorkflow, peekMutationProbe, settleMutationProbe } = require('./lib/workflow-runtime');
+const { loadWorkflow, saveWorkflow, isMajorWorkflow, peekMutationProbe, settleMutationProbe, settleMutationProbeConservative } = require('./lib/workflow-runtime');
 const { cwdOf, shellProbeKey, workspaceFingerprint, directMutationInWorkspace } = require('./lib/workflow-isolation');
 const { observeTool } = require('./lib/telemetry');
 
@@ -37,11 +37,17 @@ 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');
+      return Boolean(conservative && conservative.changed);
+    }
     context.workflow.state = 'blocked';
     context.workflow.blockReason = 'mutation-observation-failed';
     saveWorkflow(context);

package/hooks/scripts/workflow-disposition.js

@@ -3,7 +3,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { loadWorkflow, saveWorkflow, matchingRun, OPEN_STATES, ensureWorkflowBudget, recordBudgetEvent, resetWorkflowBudget, syncBudgetToRun, WORKFLOW_CONTROLLER_COMMANDS } = require('./lib/workflow-runtime');
+const { loadWorkflow, saveWorkflow, matchingRun, OPEN_STATES, budgetLimits, ensureWorkflowBudget, recordBudgetEvent, resetWorkflowBudget, syncBudgetToRun, WORKFLOW_CONTROLLER_COMMANDS } = require('./lib/workflow-runtime');
 const { getWorkspaceRoot, readCurrentSession } = require('./lib/harness-state');
 const { atomicWriteJson, readJson } = require('./lib/fable-contracts');
 
@@ -32,6 +32,20 @@ function consumer() {
   throw new Error('Fable consumer unavailable');
 }
 
+function activatePlan(workflow, plan) {
+  workflow.workflowPlan = plan;
+  workflow.strategy = plan.strategy;
+  workflow.strategySelection = plan.strategySelection;
+  workflow.tier = plan.tier;
+  workflow.requiredInvariants = plan.requiredInvariants || [];
+  workflow.suggestedSkills = plan.suggestedSkills || [];
+  workflow.verification = plan.verification;
+  workflow.mutationIsolation = plan.mutationIsolation || { required: false };
+  const budget = ensureWorkflowBudget(workflow);
+  budget.limits = budgetLimits(workflow);
+  budget.updatedAt = new Date().toISOString();
+}
+
 function main() {
   const args = parseArgs(process.argv.slice(2));
   if (!WORKFLOW_CONTROLLER_COMMANDS.has(args.command)) throw new Error(usage());
@@ -47,10 +61,12 @@ function main() {
     if (isReplan) recordBudgetEvent(context, 'replan', { evidence: 'workflow-disposition:start' });
     const plan = workflow.pendingPlan || workflow.workflowPlan;
     if (!String(plan.strategy || '').startsWith('fable-')) {
+      activatePlan(workflow, plan);
       workflow.revision++;
       workflow.state = 'running';
+      workflow.escapes = [];
+      delete workflow.pendingPlan;
       delete workflow.blockReason;
-      ensureWorkflowBudget(workflow);
       saveWorkflow(context);
       process.stdout.write(JSON.stringify({ state: workflow.state, workflowId: workflow.workflowId, revision: workflow.revision }) + '\n');
       return;
@@ -66,18 +82,13 @@ function main() {
       routerContract: { workflowPlan: plan }, stages, workspaceRoot: context.root,
       sessionId, workflowId: workflow.workflowId,
     });
-    workflow.workflowPlan = plan;
-    workflow.strategy = plan.strategy;
-    workflow.tier = plan.tier;
-    workflow.verification = plan.verification;
-    workflow.mutationIsolation = plan.mutationIsolation || workflow.mutationIsolation;
+    activatePlan(workflow, plan);
     workflow.runId = run.runId;
     workflow.revision++;
     workflow.state = 'running';
     workflow.escapes = [];
     delete workflow.pendingPlan;
     delete workflow.blockReason;
-    ensureWorkflowBudget(workflow);
   } else if (args.command === 'revision') {
     recordBudgetEvent(context, 'revision', { evidence: args.evidence || 'workflow-disposition:revision' });
   } else if (args.command === 'reset-budget') {

package/hooks/scripts/workflow-gate.js

@@ -9,6 +9,15 @@ const { key, classifyShell, workspaceFingerprint, shellProbeKey, cwdOf, commandO
 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;
@@ -62,11 +71,31 @@ function decide(payload) {
 
   // Shell safety and shell mutation accounting are intentionally separate.
   // `untrusted` means "not proven read-only", not "a mutation occurred".
-  // Capture an opaque pre-execution workspace fingerprint; the post-tool
-  // observer consumes an iteration only when workspace content actually changed.
-  const fingerprint = workspaceFingerprint(cwd);
+  // Capture an opaque pre-execution workspace fingerprint when possible. A
+  // non-major workflow may run outside Git, where mutation observation is an
+  // accounting aid rather than an isolation boundary; degrade conservatively
+  // instead of blocking the user's command (#162).
+  let fingerprint;
+  try {
+    fingerprint = workspaceFingerprint(cwd);
+  } catch (error) {
+    if (isMajorWorkflow(workflow)) throw error;
+    if (workflow.strategy === 'iterative-single') {
+      recordBudgetEvent(context, 'iteration', { evidence: 'shell:unobservable-workspace' });
+    }
+    workflow.lastMutationAt = Date.now();
+    saveWorkflow(context);
+    return;
+  }
   const probeKey = shellProbeKey(payload, cwd);
-  registerMutationProbe(context, probeKey, fingerprint, workflow.strategy === 'iterative-single');
+  registerMutationProbe(
+    context,
+    probeKey,
+    fingerprint,
+    workflow.strategy === 'iterative-single',
+    cwd,
+    shellTimeoutMs(payload)
+  );
 }
 
 readHookInput(decide);

package/multi-agent-workspace/SKILL.md

@@ -4,7 +4,7 @@ description: "Scaffold a verified multi-agent workspace and select bounded speci
 license: Apache-2.0
 metadata:
   author: Miya Daniel
-  version: 0.10.0
+  version: 0.12.0
 ---
 
 # Multi-Agent Workspace

package/multi-agent-workspace/scripts/index_memory.js

@@ -5,6 +5,18 @@ const fs = require('fs');
 const path = require('path');
 const { getWorkspaceRoot, getRuntimeRoot, resolveProjectDocs } = require('./project-docs-resolver');
 
+let emitLessonTelemetry = () => ({ ok: false, unavailable: true });
+for (const relative of [
+  '../../hooks/scripts/lib/telemetry.js',
+  '../../../hooks/scripts/lib/telemetry.js',
+]) {
+  const candidate = path.resolve(__dirname, relative);
+  if (fs.existsSync(candidate)) {
+    ({ emitLessonTelemetry } = require(candidate));
+    break;
+  }
+}
+
 function option(args, ...names) {
   for (const name of names) {
     const index = args.indexOf(name);
@@ -166,6 +178,22 @@ function retrieveMemoryRecords({ workspace, task = '', requirement = '', role =
     });
   }
 
+  for (const record of included) {
+    if (!record.origin?.lessonCandidateId) continue;
+    emitLessonTelemetry({
+      event: 'lesson_retrieved',
+      root,
+      sessionId: record.writer?.sessionId || null,
+      candidateId: record.origin.lessonCandidateId,
+      observedAt: new Date(nowMs).toISOString(),
+      status: 'success',
+      reasonCodes: [
+        'scoped-memory-retrieval',
+        ...(record.retrieval?.reasonCodes || []),
+      ],
+    });
+  }
+
   return {
     schemaVersion: 1,
     workspace: root,