harness-everything 0.11.4 → 0.11.6

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/state-persist.js

@@ -2,6 +2,8 @@
 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 { cwdOf, shellProbeKey, workspaceFingerprint } = require('./lib/workflow-isolation');
 const { observeTool } = require('./lib/telemetry');
 
 // Commands that count as "verification ran" for the Stop gate
@@ -28,7 +30,31 @@ process.stdin.on('end', () => {
   }
 });
 
+function observeWorkspaceMutation(payload, root) {
+  const toolName = payload && (payload.tool_name || payload.tool);
+  if (toolName !== 'Bash' && toolName !== 'PowerShell' && toolName !== 'exec_command') return false;
+  const context = loadWorkflow(payload);
+  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;
+  let after;
+  try {
+    after = workspaceFingerprint(cwd);
+  } catch (error) {
+    context.workflow.state = 'blocked';
+    context.workflow.blockReason = 'mutation-observation-failed';
+    saveWorkflow(context);
+    const critical = new Error('cannot verify whether shell execution changed workspace content');
+    critical.code = 'HARNESS_MUTATION_OBSERVATION';
+    throw critical;
+  }
+  const result = settleMutationProbe(context, probeKey, after, toolName);
+  return Boolean(result && result.changed);
+}
+
 function processState(payload) {
+  let exitCodeForHook = 0;
   try {
     const sessionId = payload && (payload.session_id || payload.sessionId);
     const root = getWorkspaceRoot(payload);
@@ -48,12 +74,16 @@ function processState(payload) {
       // it's actually a number; fall back to a stderr signal otherwise.
       const toolResponse = payload.tool_response || {};
       const stdout = toolResponse.stdout ?? payload.stdout ?? '';
-      const stderr = toolResponse.stderr ?? payload.stderr ?? '';
+      const stderr = toolResponse.stderr ?? payload.stderr ?? payload.error ?? '';
       const rawExitCode = toolResponse.exitCode ?? toolResponse.exit_code ?? payload.exitCode;
       const exitCode = typeof rawExitCode === 'number' ? rawExitCode : undefined;
       const stderrSignal = typeof stderr === 'string' && stderr.trim().length > 0;
-      const isFailed = (exitCode !== undefined && exitCode !== 0) || (exitCode === undefined && stderrSignal);
+      const hookEvent = payload.hook_event_name || payload.hookEventName || '';
+      const isFailed = hookEvent === 'PostToolUseFailure' ||
+        (exitCode !== undefined && exitCode !== 0) ||
+        (exitCode === undefined && stderrSignal);
       const toolName = payload.tool_name || payload.tool || 'command';
+      const observedMutation = observeWorkspaceMutation(payload, root);
 
       if (isFailed) {
         // Truncate output to avoid state bloat
@@ -78,9 +108,10 @@ function processState(payload) {
 
       // Milestones for the Stop gate: when did the last mutation happen, and
       // has any verification-ish command succeeded since.
-      if (toolName === 'Edit' || toolName === 'Write' || toolName === 'apply_patch') {
+      if (toolName === 'Edit' || toolName === 'Write' || toolName === 'apply_patch' || observedMutation) {
         state.lastEditAt = Date.now();
-      } else if ((toolName === 'Bash' || toolName === 'PowerShell') && !isFailed) {
+      }
+      if ((toolName === 'Bash' || toolName === 'PowerShell') && !isFailed) {
         const command = (payload.tool_input && payload.tool_input.command) || '';
         if (VERIFY_COMMAND_RE.test(command)) {
           state.lastVerifyAt = Date.now();
@@ -100,7 +131,11 @@ function processState(payload) {
       }
     }
   } catch (err) {
-    // Fail silently in hooks
+    if (err && (err.code === 'HARNESS_MUTATION_OBSERVATION' || err.code === 'HARNESS_WORKFLOW_BUDGET')) {
+      console.error('[State Persist] ' + err.message);
+      exitCodeForHook = 2;
+    }
+    // Non-critical persistence/telemetry failures remain fail-open.
   }
-  process.exit(0);
+  process.exit(exitCodeForHook);
 }

package/hooks/scripts/workflow-gate.js

@@ -3,8 +3,8 @@
 
 const path = require('path');
 const fs = require('fs');
-const { loadWorkflow, saveWorkflow, isMajorWorkflow, matchingRun, recordBudgetEvent, readHookInput, WORKFLOW_CONTROLLER_COMMANDS } = require('./lib/workflow-runtime');
-const { key, classifyShell, cwdOf, commandOf, mutationPaths, linkedWorktree, assertTargets, assertShellScope } = require('./lib/workflow-isolation');
+const { loadWorkflow, saveWorkflow, isMajorWorkflow, matchingRun, registerMutationProbe, recordBudgetEvent, readHookInput, WORKFLOW_CONTROLLER_COMMANDS } = require('./lib/workflow-runtime');
+const { key, classifyShell, workspaceFingerprint, shellProbeKey, cwdOf, commandOf, mutationPaths, linkedWorktree, assertTargets, assertShellScope } = require('./lib/workflow-isolation');
 
 const DIRECT = new Set(['Edit', 'Write', 'apply_patch']);
 const SHELL = new Set(['Bash', 'PowerShell', 'exec_command']);
@@ -27,8 +27,8 @@ function decide(payload) {
   const cwd = cwdOf(payload, root);
   const command = commandOf(payload);
   const commandClass = SHELL.has(tool) ? classifyShell(command) : 'direct-mutation';
-  if (commandClass === 'read-only' || commandClass === 'worktree-setup') return;
   if (SHELL.has(tool) && isController(command, cwd)) return;
+  if (commandClass === 'read-only' || commandClass === 'worktree-setup') return;
   // Only the stage specification is allowed before run entry. Other runtime
   // state, including workflow-run.json, cannot use this bootstrap exception.
   const targets = DIRECT.has(tool) ? mutationPaths(payload) : [];
@@ -47,11 +47,22 @@ function decide(payload) {
   if (String(workflow.strategy || '').startsWith('fable-') && !matchingRun(context)) {
     throw new Error('selected Fable workflow has no correlated run. Write workflow-stages.json at the displayed session path, then use workflow-disposition.js start.');
   }
-  if (workflow.strategy === 'iterative-single') {
-    recordBudgetEvent(context, 'iteration', { evidence: `${tool}:${commandClass}` });
+  if (DIRECT.has(tool)) {
+    if (workflow.strategy === 'iterative-single') {
+      recordBudgetEvent(context, 'iteration', { evidence: `${tool}:direct-mutation` });
+    }
+    workflow.lastMutationAt = Date.now();
+    saveWorkflow(context);
+    return;
   }
-  workflow.lastMutationAt = Date.now();
-  saveWorkflow(context);
+
+  // 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);
+  const probeKey = shellProbeKey(payload, cwd);
+  registerMutationProbe(context, probeKey, fingerprint, workflow.strategy === 'iterative-single');
 }
 
 readHookInput(decide);

package/hooks/scripts/workflow-mutation-denied.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+'use strict';
+
+const { loadWorkflow, discardMutationProbe, readHookInput } = require('./lib/workflow-runtime');
+const { cwdOf, shellProbeKey } = require('./lib/workflow-isolation');
+
+function discardDenied(payload) {
+  if (!payload) return;
+  const tool = payload.tool_name || payload.tool;
+  if (tool !== 'Bash' && tool !== 'PowerShell' && tool !== 'exec_command') return;
+  const context = loadWorkflow(payload);
+  if (!context.workflow || context.workflow.state === 'deferred') return;
+  const cwd = cwdOf(payload, context.root);
+  discardMutationProbe(context, shellProbeKey(payload, cwd));
+}
+
+readHookInput(discardDenied);

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.11.4",
+  "version": "0.11.6",
   "runtime": "index.mjs",
   "hooks": {
     "verify": "hooks/verify.js"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harness-everything",
-  "version": "0.11.4",
+  "version": "0.11.6",
   "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.11.4",
+  "version": "0.11.6",
   "description": "Invariant-first engineering harness for routing, verification, and failure recovery while preserving agent autonomy.",
   "author": {
     "name": "Miya Daniel",

package/plugins/harness-everything/hooks/hooks.json

@@ -142,7 +142,7 @@
             "command": "node \"${PLUGIN_ROOT}/hooks/scripts/state-persist.js\"",
             "commandWindows": "node \"${PLUGIN_ROOT}\\hooks\\scripts\\state-persist.js\"",
             "timeout": 15,
-            "statusMessage": "Saving Harness session state"
+            "statusMessage": "Saving Harness state and observed mutation"
           }
         ]
       },

package/plugins/harness-everything/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) {
@@ -43,13 +119,12 @@ function linkedWorktree(cwd, boundRoot) {
   return worktrees.some(field => field.startsWith('worktree ') && key(field.slice(9)) === key(top)) ? top : null;
 }
 
-// A conservative read subset, not a general shell sandbox. Chaining (`;`, `&&`,
-// `||`, `|`) and the `2>&1`/`1>&2` fd-duplication redirect are permitted only
-// when every resulting segment independently matches the trusted read-only set
-// below; any other metacharacter (substitution, grouping, a lone `&`, a file
-// redirect, `<`) still forces mutation-or-unknown for the whole command.
-const SHELL_SEPARATOR_RE = /\s*(?:&&|\|\||;|\|)\s*/;
-const SAFE_FD_REDIRECT_RE = /[12]>&[12]/g;
+// A conservative read subset, not a general shell sandbox. Top-level chaining
+// (`;`, `&&`, `||`, `|`) and the `2>&1`/`1>&2` fd-duplication redirect
+// are permitted only when every resulting segment independently matches the
+// trusted read-only set below. The scanner is deliberately lexical rather than
+// a raw regex split so quoted/escaped separator characters remain arguments.
+// 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;
 
@@ -57,20 +132,102 @@ function isReadOnlySegment(segment) {
   return READ_ONLY_PREFIX_RE.test(segment) && !DANGEROUS_FLAG_RE.test(segment);
 }
 
+function splitShellSegments(text) {
+  const segments = [];
+  let current = '';
+  let quote = null;
+
+  const push = () => {
+    const segment = current.trim();
+    if (!segment) return false;
+    segments.push(segment);
+    current = '';
+    return true;
+  };
+
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+
+    if (quote === "'") {
+      current += ch;
+      if (ch === "'") quote = null;
+      continue;
+    }
+
+    if (quote === '"') {
+      if (ch === '$' || ch === '`') return null;
+      current += ch;
+      if (ch === '"') {
+        quote = null;
+      } else if (ch === '\\') {
+        if (i + 1 >= text.length) return null;
+        current += text[++i];
+      }
+      continue;
+    }
+
+    if (ch === "'" || ch === '"') {
+      quote = ch;
+      current += ch;
+      continue;
+    }
+
+    if (ch === '\\') {
+      if (i + 1 >= text.length) return null;
+      current += ch + text[++i];
+      continue;
+    }
+
+    if (ch === '$' || ch === '`' || ch === '(' || ch === ')' || ch === '{' || ch === '}' ||
+        ch === '\r' || ch === '\n' || ch === '\x00') return null;
+
+    // Only treat fd duplication as syntax at a token boundary. Quoted text such
+    // as "2>&1" was handled above and remains literal argument content.
+    if ((ch === '1' || ch === '2') && text[i + 1] === '>' && text[i + 2] === '&' &&
+        (text[i + 3] === '1' || text[i + 3] === '2') &&
+        (i === 0 || /\s/.test(text[i - 1])) &&
+        (i + 4 === text.length || /[\s;|&]/.test(text[i + 4]))) {
+      current += ' ';
+      i += 3;
+      continue;
+    }
+
+    if (ch === '>' || ch === '<') return null;
+
+    if (ch === ';') {
+      if (!push()) return null;
+      continue;
+    }
+
+    if (ch === '|') {
+      if (!push()) return null;
+      if (text[i + 1] === '|') i++;
+      continue;
+    }
+
+    if (ch === '&') {
+      if (text[i + 1] !== '&' || !push()) return null;
+      i++;
+      continue;
+    }
+
+    current += ch;
+  }
+
+  if (quote || !push()) return null;
+  return segments;
+}
+
 function classifyShell(command) {
   const text = String(command || '').trim();
-  if (!text || /[`$(){}\r\n\x00]/.test(text)) return 'mutation-or-unknown';
-  // Strip the safe `2>&1`/`1>&2` fd-duplication redirect first: it contains a
-  // literal `&` that must not be mistaken for a lone backgrounding `&`.
-  const withoutSafeRedirects = text.replace(SAFE_FD_REDIRECT_RE, ' ');
-  if (/&/.test(withoutSafeRedirects.replace(/&&/g, ''))) return 'mutation-or-unknown';
-  if (/[<>]/.test(withoutSafeRedirects)) return 'mutation-or-unknown';
-  const segments = text.split(SHELL_SEPARATOR_RE).map(segment => segment.replace(SAFE_FD_REDIRECT_RE, '').trim());
+  if (!text) return 'untrusted';
+  const segments = splitShellSegments(text);
+  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';
   }
-  return segments.every(segment => segment && isReadOnlySegment(segment)) ? 'read-only' : 'mutation-or-unknown';
+  return segments.every(isReadOnlySegment) ? 'read-only' : 'mutation-or-unknown';
 }
 
 function inputOf(payload) { return payload?.tool_input ?? payload?.toolInput ?? payload?.input ?? {}; }
@@ -117,4 +274,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, assertTargets, assertShellScope };