harness-everything 0.3.6 → 0.4.1

package/plugins/harness-everything/hooks/scripts/openai-session-start.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const {
+  getWorkspaceRoot,
+  getSessionId,
+  getSessionDir,
+  writeCurrentSession,
+  pruneStaleSessions
+} = require('./lib/harness-state');
+
+const POLICY = [
+  'Harness Cognitive OS policy is active.',
+  'Use Discover -> Think -> Try -> Summarize -> Record as a lightweight reasoning loop.',
+  'Cross-cutting invariants:',
+  '- Route before execution: establish task scope before mutating work.',
+  '- Verify before claim: require objective evidence appropriate to the change.',
+  '- Re-plan on repetition: after 3 same-signature failures, zoom out instead of repeating the same attempt.',
+  'Domain skills are advisory. Do not enforce a universal workflow order; choose the smallest useful skill/tool set.'
+].join('\n');
+
+function readPayload() {
+  if (process.stdin.isTTY) return null;
+  try {
+    const raw = fs.readFileSync(0, 'utf8').trim();
+    return raw ? JSON.parse(raw) : null;
+  } catch (err) {
+    return null;
+  }
+}
+
+function removeIfPresent(file) {
+  try {
+    if (fs.existsSync(file)) fs.unlinkSync(file);
+  } catch (err) {
+    // Session reset is best effort; a stale breaker must never block startup.
+  }
+}
+
+function handoffContext(sessionDir) {
+  try {
+    const handoff = JSON.parse(fs.readFileSync(path.join(sessionDir, 'handoff-state.json'), 'utf8'));
+    if (handoff.status !== 'failed') return '';
+    const detail = String(handoff.errorSummary || 'No error snippet available').trim().slice(-300);
+    return `\nPrevious session checkpoint: ${handoff.tool || 'unknown'} failed${handoff.exitCode ? ` (exit ${handoff.exitCode})` : ''}.\nReview the failure evidence before continuing.\n${detail}`;
+  } catch (err) {
+    return '';
+  }
+}
+
+function main() {
+  const payload = readPayload();
+  const root = getWorkspaceRoot(payload);
+  const sessionId = getSessionId(payload);
+  let additionalContext = POLICY;
+
+  if (root) {
+    try {
+      pruneStaleSessions(root);
+      writeCurrentSession(root, sessionId);
+      const sessionDir = getSessionDir(root, sessionId);
+      removeIfPresent(path.join(sessionDir, 'rule-of-3-state.json'));
+      removeIfPresent(path.join(sessionDir, 'zoom-out-report.md'));
+      removeIfPresent(path.join(sessionDir, 'subagent-scope-state.json'));
+      additionalContext += handoffContext(sessionDir);
+    } catch (err) {
+      // Policy injection remains useful even if runtime state is unavailable.
+    }
+  }
+
+  console.log(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart',
+      additionalContext
+    }
+  }));
+}
+
+main();

package/plugins/harness-everything/hooks/scripts/reset-circuit-breaker.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+// Manual escape hatch for the Rule of 3 circuit breaker. Run this directly
+// in your own terminal (not through the agent — Bash is blocked while the
+// breaker is tripped) to clear it without waiting for a new session.
+const fs = require('fs');
+const path = require('path');
+const { getWorkspaceRoot, getSessionDir, readCurrentSession } = require('./lib/harness-state');
+
+// This is run directly by the human, not through the agent, so there's no
+// hook payload to read a session_id from - resolve "the session that's
+// currently blocked" via the pointer bootstrap.js wrote at its last
+// SessionStart.
+const root = getWorkspaceRoot();
+const harnessDir = getSessionDir(root, readCurrentSession(root));
+const stateFile = path.join(harnessDir, 'rule-of-3-state.json');
+const reportFile = path.join(harnessDir, 'zoom-out-report.md');
+
+if (fs.existsSync(stateFile)) {
+  fs.unlinkSync(stateFile);
+  console.log('Rule of 3 circuit breaker cleared.');
+} else {
+  console.log('Rule of 3 circuit breaker is not currently tripped.');
+}
+
+// A human reset is a full clear: the stale reflection report belongs to the
+// loop that was just abandoned.
+if (fs.existsSync(reportFile)) {
+  fs.unlinkSync(reportFile);
+  console.log('Stale zoom-out report removed.');
+}

package/plugins/harness-everything/hooks/scripts/rule-of-3-tracker.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { getWorkspaceRoot, getSessionDir } = require('./lib/harness-state');
+
+// PostToolUse hooks in Claude Code typically receive the tool output via stdin
+let inputData = '';
+
+process.stdin.on('data', chunk => {
+  inputData += chunk;
+});
+
+process.stdin.on('end', () => {
+  try {
+    const payload = JSON.parse(inputData);
+    const toolResponse = payload.tool_response || {};
+    const stdout = toolResponse.stdout ?? payload.stdout ?? '';
+    const stderr = toolResponse.stderr ?? payload.stderr ?? '';
+    const rawExitCode = toolResponse.exitCode ?? toolResponse.exit_code ?? payload.exitCode;
+    const exitCode = typeof rawExitCode === 'number' ? rawExitCode : undefined;
+
+    const explicitFailure = exitCode !== undefined && exitCode !== 0;
+    const explicitSuccess = exitCode === 0;
+    const stderrSignal = typeof stderr === 'string' && stderr.trim().length > 0;
+    const looksLikeError = /\b(error|fail|failed|failure|exception|fatal|panic|traceback|denied|refused|cannot|unable)\b/i.test(stderr);
+    const isFailure = explicitFailure || (exitCode === undefined && stderrSignal && looksLikeError);
+    const errorText = (stderrSignal ? stderr : stdout) || '';
+
+    const root = getWorkspaceRoot(payload);
+    const stateFile = path.join(getSessionDir(root, payload.session_id || payload.sessionId), 'rule-of-3-state.json');
+
+    let state = { count: 0, lastHash: null, zoomOutResolved: false, zoomOutCycles: 0, lastFailureAt: 0 };
+    if (fs.existsSync(stateFile)) {
+      state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+    }
+
+    if (isFailure && errorText) {
+      // Enhanced failure signature detection with context-aware categorization
+      // Hash includes: error message, file path, command attempted, and failure category
+      const filePath = payload.tool_input?.file_path || payload.tool_input?.filePath || '';
+      const command = payload.tool_input?.command || '';
+
+      // Categorize failure type for context-aware thresholds
+      let category = 'unknown';
+      if (/SyntaxError|Unexpected token|Syntax Error/i.test(errorText)) {
+        category = 'syntax';
+      } else if (/ENOENT|not found|No such file|找不到|不存在/i.test(errorText)) {
+        category = 'environment';
+      } else if (/timeout|timed out|超時|逾時/i.test(errorText)) {
+        category = 'timeout';
+      } else if (/test.*fail|assertion|AssertionError|測試.*失敗|斷言.*錯誤/i.test(errorText)) {
+        category = 'test';
+      } else if (/permission|denied|EACCES|權限/i.test(errorText)) {
+        category = 'permission';
+      } else if (/dependency|module not found|Cannot find module|模組.*找不到/i.test(errorText)) {
+        category = 'dependency';
+      }
+
+      // Normalize error text with context for better loop detection
+      const normalized = errorText.slice(-400)
+        .toLowerCase()
+        .replace(/0x[0-9a-f]+/g, '#')
+        .replace(/\d+/g, '#')
+        .replace(/\s+/g, ' ')
+        .trim();
+
+      // Include file path and command in hash for better context
+      const contextString = `${category}:${filePath}:${command}:${normalized.slice(-200)}`;
+      const hash = crypto.createHash('md5').update(contextString).digest('hex');
+
+      // Context-aware thresholds: different failure types have different breaking points
+      let threshold = 3; // Default: 3 strikes
+      if (category === 'syntax') {
+        threshold = 3; // Same syntax error 3 times = stop
+      } else if (category === 'environment') {
+        threshold = 4; // Environment issues may need more exploration
+      } else if (category === 'test') {
+        threshold = 3; // Same test failure 3 times = stop
+      } else if (category === 'timeout') {
+        threshold = 2; // Timeouts are expensive, fail faster
+      } else if (category === 'permission') {
+        threshold = 2; // Permission issues rarely resolve by retrying
+      } else if (category === 'dependency') {
+        threshold = 4; // Dependency issues may need different approaches
+      }
+
+      if (state.lastHash === hash) {
+        state.count += 1;
+        state.category = category; // Track failure category for smarter decisions
+      } else {
+        state.count = 1;
+        state.lastHash = hash;
+        state.category = category;
+        // New signature = new problem: the zoom-out cycle budget starts over.
+        state.zoomOutCycles = 0;
+      }
+
+      // Store threshold for this failure type
+      state.threshold = threshold;
+
+      // Any fresh failure re-arms the breaker. Without this, a signature that
+      // failed again after a success (or after a zoom-out release) would keep
+      // zoomOutResolved=true and the breaker could never trip on it again.
+      state.zoomOutResolved = false;
+      // rule-of-3.js only honors a zoom-out report written AFTER this moment,
+      // so a stale report can't unlock a later trip.
+      state.lastFailureAt = Date.now();
+
+      fs.writeFileSync(stateFile, JSON.stringify(state, null, 2), 'utf8');
+    } else if (explicitSuccess) {
+      // Only reset on a *confirmed* zero exit code, not merely "not a failure".
+      if (state.count > 0 || state.zoomOutCycles > 0) {
+        state.count = 0;
+        state.zoomOutResolved = true;
+        state.zoomOutCycles = 0;
+        fs.writeFileSync(stateFile, JSON.stringify(state, null, 2), 'utf8');
+      }
+    }
+
+  } catch (err) {
+    // silently fail
+  }
+  process.exit(0);
+});

package/plugins/harness-everything/hooks/scripts/rule-of-3.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+// Rule of 3 circuit breaker (PreToolUse: Bash|PowerShell|Edit|Write|apply_patch).
+//
+// Tripping the breaker forces REFLECTION, not surrender. The most common
+// agent failure mode is drilling deeper on one unverified assumption, so the
+// breaker locks mutating tools and demands a zoom-out fact-check first
+// (read-only tools stay available). A valid reflection report - written to
+// the session's zoom-out-report.md (path given in the block message below) -
+// releases the breaker again. Only a SECOND trip on the same failure
+// signature - proof that reflection alone couldn't crack it - hard-locks the
+// session until the Human Partner decides.
+//
+// State is scoped per Claude Code session_id (see lib/harness-state.js) so
+// two sessions open on the same repo never share a trip count. The common
+// case - nobody's breaker tripped anywhere - never has to read stdin to find
+// that out; only once some session IS tripped do we pay to read the payload
+// and check whether it's this one.
+const fs = require('fs');
+const path = require('path');
+const { getWorkspaceRoot, getSessionDir, listSessionDirs } = require('./lib/harness-state');
+
+const REQUIRED_SECTIONS = [
+  '## Goal',
+  '## Failed Attempts',
+  '## Verified Facts',
+  '## Diagnosis',
+  '## Decision'
+];
+
+function readState(stateFile) {
+  if (!fs.existsSync(stateFile)) return null;
+  try { return JSON.parse(fs.readFileSync(stateFile, 'utf8')); } catch (err) { return null; }
+}
+
+function isTripped(state) {
+  if (!state || state.zoomOutResolved) return false;
+
+  // Use context-aware thresholds if available, otherwise default to 3
+  const threshold = state.threshold || 3;
+  return state.count >= threshold;
+}
+
+function anySessionTripped(root) {
+  return listSessionDirs(root).some(dir => isTripped(readState(path.join(dir, 'rule-of-3-state.json'))));
+}
+
+// The one mutation allowed while tripped: writing the reflection report.
+const ALLOWED_WRITE_TOOLS = new Set([
+  'Write', 'Edit', 'create_file', 'replace_string_in_file',
+  'insert_edit_into_file', 'write_file', 'edit_file', 'apply_patch'
+]);
+
+function isReportWrite(payload, reportFile) {
+  if (!payload) return false;
+  const toolName = payload.tool_name || payload.toolName;
+  if (!ALLOWED_WRITE_TOOLS.has(toolName)) return false;
+  const input = payload.tool_input || payload.toolInput || payload.input || {};
+  const target = input.file_path || input.filePath || input.path || input.file;
+  if (target && path.resolve(target).toLowerCase() === path.resolve(reportFile).toLowerCase()) return true;
+  if (toolName !== 'apply_patch') return false;
+
+  const patch = input.patch || input.command || input.content || '';
+  const base = payload.cwd || process.cwd();
+  const files = [...String(patch).matchAll(/^\*\*\* (?:Update|Add|Delete) File:\s*(.+?)\s*$/gm)]
+    .map(match => match[1]);
+  const reportPath = path.resolve(reportFile).toLowerCase();
+  return files.length > 0 && files.every(file => path.resolve(base, file).toLowerCase() === reportPath);
+}
+
+// A report only counts if it was written AFTER the failure that tripped the
+// breaker (a stale report from an earlier loop can't unlock a new one), has
+// every required section, and actually committed to a RESUME/ESCALATE call.
+function reportIsValid(state, reportFile) {
+  if (!fs.existsSync(reportFile)) return false;
+  if (fs.statSync(reportFile).mtimeMs < (state.lastFailureAt || 0)) return false;
+  const text = fs.readFileSync(reportFile, 'utf8');
+  if (!REQUIRED_SECTIONS.every(h => text.includes(h))) return false;
+  return /\b(RESUME|ESCALATE)\b/.test(text);
+}
+
+function blockForReflection(state, reportFile) {
+  console.error(`[CRITICAL] RULE OF 3 CIRCUIT BREAKER TRIGGERED!`);
+  console.error(`The same failure signature has now occurred 3 times.`);
+  console.error(`Error Signature: ${state.lastHash}`);
+  console.error(`\nMutating tools (Bash/PowerShell/Edit/Write/apply_patch) are locked - not because you`);
+  console.error(`must wait for a human, but because you must stop drilling and rebuild the`);
+  console.error(`full picture first. Do NOT ask the Human Partner yet.`);
+  console.error(`\nACTION REQUIRED (reflect first):`);
+  console.error(`1. CEASE FIRE. No new fix attempts, no variations of the last one.`);
+  console.error(`2. Load the 'zoom-out' skill and follow its Reflect & Fact-Check protocol.`);
+  console.error(`3. Using READ-ONLY tools (Read/Grep/Glob - still available), re-verify the`);
+  console.error(`   assumption behind each failed attempt against the actual code/logs/docs.`);
+  console.error(`4. Write your findings to '${reportFile}' (the ONLY write`);
+  console.error(`   allowed right now) with sections: ## Goal, ## Failed Attempts,`);
+  console.error(`   ## Verified Facts, ## Diagnosis, ## Decision (ending RESUME: or ESCALATE:).`);
+  console.error(`\nA valid report releases this breaker automatically. Escalate to the Human`);
+  console.error(`Partner ONLY if your Decision concludes a genuinely human call is needed`);
+  console.error(`(requirement conflict, architecture trade-off, destructive action, missing`);
+  console.error(`access) - and then present options with a recommendation, not apologies.`);
+  // For PreToolUse, only exit code 2 actually blocks the tool call.
+  // Exit 1 is a non-blocking error and Claude Code proceeds anyway.
+  process.exit(2);
+}
+
+function blockForHumanDecision(state) {
+  console.error(`[CRITICAL] RULE OF 3 CIRCUIT BREAKER TRIGGERED! (repeat trip - hard lock)`);
+  console.error(`Error Signature: ${state.lastHash}`);
+  console.error(`\nYou already completed a zoom-out reflection for this same failure signature`);
+  console.error(`and the fresh diagnosis failed too. This is now past reflect-and-retry:`);
+  console.error(`STOP and hand the decision to your Human Partner.`);
+  console.error(`\nPresent a DECISION REQUEST, not a plea: the goal, the verified facts, every`);
+  console.error(`path already falsified (including the post-reflection diagnosis), 2-3`);
+  console.error(`concrete options with trade-offs, and your recommendation.`);
+  console.error(`\nThis lock persists until the Human Partner clears it by running`);
+  console.error(`"npm run harness:reset" in their own terminal, or by starting a new`);
+  console.error(`session / running /clear (which resets it automatically on SessionStart).`);
+  process.exit(2);
+}
+
+function main(payload) {
+  try {
+    const root = getWorkspaceRoot(payload);
+    const sessionDir = getSessionDir(root, payload && (payload.session_id || payload.sessionId));
+    const stateFile = path.join(sessionDir, 'rule-of-3-state.json');
+    const reportFile = path.join(sessionDir, 'zoom-out-report.md');
+
+    const state = readState(stateFile);
+    if (!isTripped(state)) {
+      process.exit(0);
+    }
+
+    if (isReportWrite(payload, reportFile)) {
+      process.exit(0);
+    }
+
+    if (reportIsValid(state, reportFile)) {
+      state.count = 0;
+      state.zoomOutResolved = true;
+      state.zoomOutCycles = (state.zoomOutCycles || 0) + 1;
+      fs.writeFileSync(stateFile, JSON.stringify(state, null, 2), 'utf8');
+      console.log(
+        `[Rule of 3] Zoom-out report accepted - breaker released. Follow your ` +
+        `report's Decision: RESUME means one fresh run at the NEW diagnosis; ` +
+        `ESCALATE means present the decision request and WAIT for the Human ` +
+        `Partner before mutating anything. If this same signature trips the ` +
+        `breaker again, it hard-locks for a human decision.`
+      );
+      process.exit(0);
+    }
+
+    if ((state.zoomOutCycles || 0) >= 1) {
+      blockForHumanDecision(state);
+    }
+    blockForReflection(state, reportFile);
+  } catch (err) {
+    // Fail open if state tracking breaks
+    process.exit(0);
+  }
+}
+
+// Read the payload before the fast path. The session registry may point at a
+// different workspace than process.cwd() after an agent changes directory;
+// checking the cwd first would skip an active breaker in the bound session.
+function runForPayload(payload) {
+  let tripped = false;
+  try {
+    tripped = anySessionTripped(getWorkspaceRoot(payload));
+  } catch (err) {
+    tripped = false; // fail open
+  }
+  if (!tripped) process.exit(0);
+  main(payload);
+}
+
+if (process.stdin.isTTY) {
+  // Manual run in a terminal - no payload is coming.
+  runForPayload(null);
+} else {
+  let raw = '';
+  let finished = false;
+  const finish = () => {
+    if (finished) return;
+    finished = true;
+    let payload = null;
+    try { payload = JSON.parse(raw); } catch (err) { /* no payload */ }
+    runForPayload(payload);
+  };
+  // Claude Code closes stdin right after writing the payload; the timer is a
+  // safety net so an odd caller that never closes stdin can't hang the hook.
+  const timer = setTimeout(finish, 300);
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => { raw += chunk; });
+  process.stdin.on('end', () => { clearTimeout(timer); finish(); });
+  process.stdin.on('error', () => { clearTimeout(timer); finish(); });
+}

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

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const { getWorkspaceRoot, getSessionDir } = require('./lib/harness-state');
+
+// 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);
+}, 200);
+
+process.stdin.on('data', chunk => {
+  inputData += chunk;
+});
+
+process.stdin.on('end', () => {
+  clearTimeout(timeout);
+  try {
+    const payload = JSON.parse(inputData.trim());
+    processState(payload);
+  } catch (err) {
+    processState(null);
+  }
+});
+
+function processState(payload) {
+  try {
+    const sessionId = payload && (payload.session_id || payload.sessionId);
+    const root = getWorkspaceRoot(payload);
+    const stateFile = path.join(getSessionDir(root, sessionId), 'handoff-state.json');
+
+    // Merge into the existing state rather than replacing it, so the
+    // failure/idle status and the Stop-gate milestones can coexist.
+    let state = { status: 'idle', timestamp: new Date().toISOString() };
+    if (fs.existsSync(stateFile)) {
+      try { state = JSON.parse(fs.readFileSync(stateFile, 'utf8')); } catch (e) { /* keep default */ }
+    }
+
+    if (payload) {
+      // Hook hosts nest tool output under tool_response, not at the top
+      // level, and uses tool_name rather than tool. A numeric exit code
+      // also isn't guaranteed to be present at all - only trust it when
+      // 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 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 toolName = payload.tool_name || payload.tool || 'command';
+
+      if (isFailed) {
+        // Truncate output to avoid state bloat
+        let output = (stderrSignal ? stderr : stdout) || payload.output || '';
+        if (output.length > 500) {
+          output = '...' + output.slice(-500);
+        }
+
+        state.status = 'failed';
+        state.timestamp = new Date().toISOString();
+        state.tool = toolName;
+        state.exitCode = exitCode;
+        state.errorSummary = output.trim();
+      } else if (exitCode === 0 && state.status === 'failed') {
+        // Clear failed state or mark as idle/resolved
+        state.lastResolved = { tool: state.tool, timestamp: state.timestamp };
+        state.status = 'idle';
+        state.timestamp = new Date().toISOString();
+        delete state.exitCode;
+        delete state.errorSummary;
+      }
+
+      // 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') {
+        state.lastEditAt = Date.now();
+      } else 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();
+        }
+      }
+
+      fs.writeFileSync(stateFile, JSON.stringify(state, null, 2), 'utf8');
+    } else {
+      // No standard input payload, or invalid JSON. Just maintain a heartbeat timestamp
+      if (!fs.existsSync(stateFile)) {
+        fs.writeFileSync(stateFile, JSON.stringify(state, null, 2), 'utf8');
+      }
+    }
+  } catch (err) {
+    // Fail silently in hooks
+  }
+  process.exit(0);
+}

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

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * Stop Gate (Stop hook - Claude Code only)
+ * The pre-delivery gate (verification-loop) was prose-only, and prose decays
+ * as context grows. This makes the one check that matters mechanical: ending
+ * the turn with edits that were never followed by a successful
+ * verification-ish command (test/build/lint - tracked by state-persist.js)
+ * while uncommitted changes sit in the tree gets bounced back ONCE per edit
+ * batch. Objective facts only; fails open on any error.
+ */
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { getWorkspaceRoot, getSessionDir } = require('./lib/harness-state');
+
+function decide(payload) {
+  try {
+    // Loop guard: if this stop already resulted from a Stop-hook block,
+    // always let it through - one bounce is the contract, never a cage.
+    if (payload && payload.stop_hook_active) {
+      process.exit(0);
+    }
+
+    const root = getWorkspaceRoot(payload);
+    const sessionDir = getSessionDir(root, payload && (payload.session_id || payload.sessionId));
+    const handoffFile = path.join(sessionDir, 'handoff-state.json');
+    const gateFile = path.join(sessionDir, 'stop-gate-state.json');
+
+    if (!fs.existsSync(handoffFile)) process.exit(0);
+    const handoff = JSON.parse(fs.readFileSync(handoffFile, 'utf8'));
+    const lastEditAt = handoff.lastEditAt || 0;
+    const lastVerifyAt = handoff.lastVerifyAt || 0;
+
+    // No edits this session, or verification already ran after the last edit.
+    if (!lastEditAt || lastVerifyAt >= lastEditAt) process.exit(0);
+
+    // One bounce per edit batch: if we already blocked for this exact edit
+    // timestamp, the model either verified (which moves lastVerifyAt) or
+    // explicitly chose not to - don't nag twice for the same batch.
+    let gate = {};
+    if (fs.existsSync(gateFile)) {
+      try { gate = JSON.parse(fs.readFileSync(gateFile, 'utf8')); } catch (e) { /* ignore */ }
+    }
+    if (gate.blockedForEditAt === lastEditAt) process.exit(0);
+
+    // Only relevant when unverified work is actually sitting in the tree.
+    const dirty = execSync('git status --porcelain', {
+      cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore']
+    }).trim();
+    if (!dirty) process.exit(0);
+
+    fs.writeFileSync(gateFile, JSON.stringify({ blockedForEditAt: lastEditAt }, null, 2), 'utf8');
+
+    console.error(`[Stop Gate] Turn is ending with uncommitted edits and no successful verification command (test/build/lint) since the last edit.`);
+    console.error(`Before delivering: run the relevant check from 'verification-loop' - even a single targeted test beats none.`);
+    console.error(`If verification is genuinely not applicable (docs-only change, analysis-only turn, the Human Partner told you to stop), state that explicitly in your reply and stop again.`);
+    console.error(`This gate bounces at most once per edit batch.`);
+    process.exit(2);
+  } catch (err) {
+    // Fail open - a broken gate must never trap the session.
+    process.exit(0);
+  }
+}
+
+let inputData = '';
+const timeout = setTimeout(() => {
+  decide(null);
+}, 200);
+
+process.stdin.on('data', chunk => { inputData += chunk; });
+process.stdin.on('end', () => {
+  clearTimeout(timeout);
+  let payload = null;
+  try { payload = JSON.parse(inputData.trim()); } catch (err) { /* no payload */ }
+  decide(payload);
+});
+process.stdin.on('error', () => {
+  clearTimeout(timeout);
+  decide(null);
+});