harness-everything 0.2.2 → 0.4.0

package/harness-everything/schemas/router-task-shape.schema.json

@@ -0,0 +1,126 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dyphn1/Harness-everything/harness-everything/schemas/router-task-shape.schema.json",
+  "title": "Harness Router Task Shape",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "scopeSize",
+    "estimatedStages",
+    "dependencyGraph",
+    "writeSetOverlap",
+    "domainDiversity",
+    "expectedDuration",
+    "reversibility",
+    "uncertainty",
+    "verificationRequirement",
+    "hostCapabilities",
+    "constraints",
+    "explicitRequest",
+    "observedSignals",
+    "reasonCodes"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "scopeSize": { "enum": ["single-file", "multi-file", "repository-wide", "unknown"] },
+    "estimatedStages": { "type": ["integer", "null"], "minimum": 1 },
+    "dependencyGraph": { "enum": ["independent", "sequential", "cyclic", "unknown"] },
+    "writeSetOverlap": { "enum": ["disjoint", "overlap", "read-only", "unknown"] },
+    "domainDiversity": { "enum": ["single-domain", "multi-domain", "unknown"] },
+    "expectedDuration": { "enum": ["one-turn", "multi-turn", "multi-session", "unknown"] },
+    "reversibility": { "enum": ["reversible", "irreversible", "external-side-effect", "unknown"] },
+    "uncertainty": { "enum": ["low", "medium", "high", "unknown"] },
+    "verificationRequirement": { "enum": ["basic", "objective", "independent", "unknown"] },
+    "hostCapabilities": {
+      "type": "object",
+      "required": ["subagents", "parallelCalls", "hooks", "state", "modelAvailability"],
+      "additionalProperties": false,
+      "properties": {
+        "subagents": { "enum": ["available", "unavailable", "unknown"] },
+        "parallelCalls": { "enum": ["available", "unavailable", "unknown"] },
+        "hooks": { "enum": ["available", "unavailable", "unknown"] },
+        "state": { "enum": ["available", "unavailable", "unknown"] },
+        "modelAvailability": { "enum": ["available", "partial", "unavailable", "unknown"] }
+      }
+    },
+    "constraints": {
+      "type": "object",
+      "required": ["cost", "latency", "tokens", "concurrency"],
+      "additionalProperties": false,
+      "properties": {
+        "cost": { "type": ["string", "number", "null"] },
+        "latency": { "type": ["string", "number", "null"] },
+        "tokens": { "type": ["string", "number", "null"] },
+        "concurrency": { "type": ["string", "number", "null"] }
+      }
+    },
+    "explicitRequest": {
+      "type": "object",
+      "required": ["fableModel", "strategy", "prohibitions"],
+      "additionalProperties": false,
+      "properties": {
+        "fableModel": { "enum": ["haiku", "sonnet", "opus", null] },
+        "strategy": {
+          "enum": ["direct-single", "iterative-single", "fable-staged", "fable-parallel", "fable-multi-agent-workspace", null]
+        },
+        "prohibitions": {
+          "type": "array",
+          "items": { "enum": ["fable", "subagents", "parallel", "workspace", "memory", "ensemble"] },
+          "uniqueItems": true
+        }
+      }
+    },
+    "observedSignals": {
+      "type": "object",
+      "required": [
+        "macroScope",
+        "trivialDocsEdit",
+        "tier3Keyword",
+        "tier2Keyword",
+        "multipleTasks",
+        "multipleSentences",
+        "specificFile",
+        "question",
+        "independentWorkstreams",
+        "readOnly",
+        "disjointWrites",
+        "sharedWrite",
+        "dependentStages",
+        "multiSession",
+        "reusableSpecialists",
+        "crossDomain",
+        "highUncertainty",
+        "irreversibleAction",
+        "externalSideEffect"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "macroScope": { "type": "boolean" },
+        "trivialDocsEdit": { "type": "boolean" },
+        "tier3Keyword": { "type": "boolean" },
+        "tier2Keyword": { "type": "boolean" },
+        "multipleTasks": { "type": "boolean" },
+        "multipleSentences": { "type": "boolean" },
+        "specificFile": { "type": "boolean" },
+        "question": { "type": "boolean" },
+        "independentWorkstreams": { "type": "boolean" },
+        "readOnly": { "type": "boolean" },
+        "disjointWrites": { "type": "boolean" },
+        "sharedWrite": { "type": "boolean" },
+        "dependentStages": { "type": "boolean" },
+        "multiSession": { "type": "boolean" },
+        "reusableSpecialists": { "type": "boolean" },
+        "crossDomain": { "type": "boolean" },
+        "highUncertainty": { "type": "boolean" },
+        "irreversibleAction": { "type": "boolean" },
+        "externalSideEffect": { "type": "boolean" }
+      }
+    },
+    "reasonCodes": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    }
+  },
+  "additionalProperties": false
+}

package/harness-everything/schemas/router-workflow-plan.schema.json

@@ -0,0 +1,149 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dyphn1/Harness-everything/harness-everything/schemas/router-workflow-plan.schema.json",
+  "title": "Harness Router Workflow Plan",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "routingStatus",
+    "tier",
+    "strategy",
+    "strategySelection",
+    "patterns",
+    "requiredInvariants",
+    "suggestedSkills",
+    "actionGate",
+    "limits",
+    "parallelism",
+    "workspace",
+    "memory",
+    "verification",
+    "ensemble",
+    "modelSelection",
+    "fallback",
+    "reasonCodes"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "routingStatus": { "enum": ["ok", "degraded"] },
+    "tier": { "enum": ["tier1", "tier2", "tier3", "unclassified"] },
+    "strategy": {
+      "enum": ["direct-single", "iterative-single", "fable-staged", "fable-parallel", "fable-multi-agent-workspace", null]
+    },
+    "strategySelection": { "enum": ["shadow", "selected", "deferred"] },
+    "patterns": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+    "requiredInvariants": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+    "suggestedSkills": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+    "actionGate": {
+      "type": "object",
+      "required": ["required", "reasonCodes", "approver", "disposition"],
+      "additionalProperties": false,
+      "properties": {
+        "required": { "type": "boolean" },
+        "reasonCodes": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+        "approver": { "enum": ["rule-or-human", null] },
+        "disposition": { "enum": ["executed", "rejected", "pending-approval", null] }
+      }
+    },
+    "limits": {
+      "type": "object",
+      "required": ["maxIterations", "maxRevisionRounds", "maxWorkers"],
+      "additionalProperties": false,
+      "properties": {
+        "maxIterations": { "type": ["integer", "null"], "minimum": 1 },
+        "maxRevisionRounds": { "type": "integer", "minimum": 0, "maximum": 2 },
+        "maxWorkers": { "enum": ["fable-orchestrator-cap"] }
+      }
+    },
+    "parallelism": {
+      "type": "object",
+      "required": ["allowed", "requires", "reasonCodes"],
+      "additionalProperties": false,
+      "properties": {
+        "allowed": { "type": ["boolean", "null"] },
+        "requires": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+        "reasonCodes": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }
+      }
+    },
+    "workspace": {
+      "type": "object",
+      "required": ["required", "reasonCodes"],
+      "additionalProperties": false,
+      "properties": {
+        "required": { "type": ["boolean", "null"] },
+        "reasonCodes": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }
+      }
+    },
+    "memory": {
+      "type": "object",
+      "required": ["read", "scope", "write"],
+      "additionalProperties": false,
+      "properties": {
+        "read": { "enum": ["workspace-index", "none", null] },
+        "scope": { "enum": ["task-relevant-only"] },
+        "write": { "enum": ["none", "propose", "persist-via-self-evolve"] }
+      }
+    },
+    "verification": {
+      "type": "object",
+      "required": ["mode", "independent"],
+      "additionalProperties": false,
+      "properties": {
+        "mode": { "enum": ["verify-before-claim", "objective", "cold-verifier"] },
+        "independent": { "type": ["boolean", "null"] }
+      }
+    },
+    "ensemble": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "required": ["maxCandidates", "diversity", "synthesis", "verifier", "reasonCodes"],
+          "additionalProperties": false,
+          "properties": {
+            "maxCandidates": { "type": "integer", "minimum": 2, "maximum": 4 },
+            "diversity": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": { "enum": ["model", "prompt", "evidence"] }
+            },
+            "synthesis": { "const": "preserve-disagreement" },
+            "verifier": { "const": "independent" },
+            "reasonCodes": {
+              "type": "array",
+              "items": { "type": "string", "minLength": 1 },
+              "uniqueItems": true
+            }
+          }
+        }
+      ]
+    },
+    "modelSelection": {
+      "type": "object",
+      "required": ["requested", "policy"],
+      "additionalProperties": false,
+      "properties": {
+        "requested": { "enum": ["haiku", "sonnet", "opus", null] },
+        "policy": { "enum": ["defer-to-fable-selector"] }
+      }
+    },
+    "fallback": {
+      "type": "object",
+      "required": ["onMissingSubagents", "disposition", "mode", "reasonCodes"],
+      "additionalProperties": false,
+      "properties": {
+        "onMissingSubagents": { "enum": ["visible-inline-or-stop"] },
+        "disposition": { "enum": ["none", "reduced", "blocked"] },
+        "mode": { "enum": ["none", "inline", "serialized", "blocked"] },
+        "reasonCodes": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }
+      }
+    },
+    "reasonCodes": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    }
+  },
+  "additionalProperties": false
+}

package/harness-everything/scripts/bootstrap.js

@@ -1,140 +1,212 @@
-#!/usr/bin/env node
-const fs = require('fs');
-const path = require('path');
-const {
-  getWorkspaceRoot,
-  getSessionDir,
-  writeCurrentSession,
-  pruneStaleSessions,
-} = require('../../hooks/scripts/lib/harness-state');
-
-console.log("Bootstrapping Harness Skills OS...");
-
-// SessionStart hooks receive a payload with session_id via stdin, same as
-// every other hook. Read it synchronously up front - bootstrap has no
-// tool-call latency to protect, so there's no fast-path tradeoff here - but
-// skip entirely on an interactive TTY (manual run) where reading fd 0 would
-// just hang waiting for input that's never coming.
-let payload = null;
-if (!process.stdin.isTTY) {
-  try {
-    const raw = fs.readFileSync(0, 'utf8');
-    payload = JSON.parse(raw);
-  } catch (err) {
-    // No payload piped in, or invalid JSON - fall back to 'default'.
-  }
-}
-const sessionId = payload && payload.session_id;
-
-const root = getWorkspaceRoot();
-
-// Nothing purges old session directories the way an OS temp dir would -
-// drop ones untouched for a while so .claude/harness-state/sessions/ doesn't
-// grow forever.
-pruneStaleSessions(root);
-
-// The manual escape hatch (reset-circuit-breaker.js) and any CLI tool that
-// can't see a session_id (todo-cli.js) resolve "current session" through
-// this pointer.
-writeCurrentSession(root, sessionId);
-
-const harnessDir = getSessionDir(root, sessionId);
-
-// The Rule of 3 circuit breaker (hooks/scripts/rule-of-3.js) locks all
-// Bash/Edit/Write calls once tripped; the only in-session exits are a valid
-// zoom-out reflection report or a human reset. A new SessionStart means the
-// human has taken over (new session, /clear, /compact) and reviewed the
-// situation, so it's safe to clear here. The stale reflection report goes
-// with it - it belongs to the previous loop, not this session.
-const circuitBreakerFile = path.join(harnessDir, 'rule-of-3-state.json');
-if (fs.existsSync(circuitBreakerFile)) {
-  try {
-    fs.unlinkSync(circuitBreakerFile);
-    console.log("Rule of 3 circuit breaker state cleared for new session.");
-  } catch (err) {
-    // Ignore; worst case the breaker stays tripped until manually reset.
-  }
-}
-const zoomOutReportFile = path.join(harnessDir, 'zoom-out-report.md');
-if (fs.existsSync(zoomOutReportFile)) {
-  try {
-    fs.unlinkSync(zoomOutReportFile);
-  } catch (err) {
-    // Ignore; rule-of-3.js already rejects reports older than the last failure.
-  }
-}
-
-// Same reasoning: a stale subagent-scope baseline from a previous session
-// would make the first Task burst of this session diff against the wrong
-// starting point.
-const subagentScopeFile = path.join(harnessDir, 'subagent-scope-state.json');
-if (fs.existsSync(subagentScopeFile)) {
-  try {
-    fs.unlinkSync(subagentScopeFile);
-  } catch (err) {
-    // Ignore.
-  }
-}
-
-// Self-heal audit: report missing platform integration touchpoints so the
-// model (per harness-everything SKILL.md) repairs them via self-heal.js.
-// Audit-and-report only - bootstrap never writes these files itself, so a
-// user who intentionally removed one isn't fought every session start.
-try {
-  const MARKER = 'Harness OS Guidance (Advisory)';
-  const HOOK_ID = 'harness:pre:bootstrap';
-  const workspaceRoot = getWorkspaceRoot();
-  const contains = (p, needle) => {
-    try { return fs.readFileSync(p, 'utf8').includes(needle); } catch (e) { return false; }
-  };
-  const missing = [
-    ['.claude/settings.json (Claude Code hooks)', contains(path.join(workspaceRoot, '.claude', 'settings.json'), HOOK_ID)],
-    ['.cursorrules (Cursor)', contains(path.join(workspaceRoot, '.cursorrules'), MARKER)],
-    ['.github/copilot-instructions.md (Copilot)', contains(path.join(workspaceRoot, '.github', 'copilot-instructions.md'), MARKER)],
-    ['AGENTS.md (Codex)', contains(path.join(workspaceRoot, 'AGENTS.md'), MARKER)]
-  ].filter(([, ok]) => !ok).map(([label]) => label);
-  if (missing.length > 0 && path.resolve(workspaceRoot) !== path.resolve(__dirname, '..', '..')) {
-    console.log(`\n[Self-Heal] Missing integration touchpoints: ${missing.join(', ')}`);
-    console.log(`[Self-Heal] Repair (idempotent): node "${path.join(__dirname, 'self-heal.js')}"`);
-  }
-} catch (err) {
-  // Audit is best-effort; never block session start.
-}
-
-// Check for handoff/state checkpoint from previous session
-const handoffFile = path.join(harnessDir, 'handoff-state.json');
-if (fs.existsSync(handoffFile)) {
-  try {
-    const handoff = JSON.parse(fs.readFileSync(handoffFile, 'utf8'));
-    if (handoff.status === 'failed') {
-      const exitStr = handoff.exitCode ? ` (exit code ${handoff.exitCode})` : '';
-      const border = "─".repeat(60);
-      console.log(`\n┌${border}┐`);
-      console.log(`│             Harness OS - Handoff Checkpoint              │`);
-      console.log(`├${border}┤`);
-      console.log(`│ - Last active action failed${exitStr.padEnd(30)} │`);
-      console.log(`│ - Action: ${String(handoff.tool || 'unknown').padEnd(46)} │`);
-      console.log(`│ - Last error output snippet:                             │`);
-      
-      const snippet = handoff.errorSummary || 'No snippet available';
-      const lines = snippet.split('\n').map(l => l.trim()).filter(Boolean).slice(-3);
-      if (lines.length > 0) {
-        lines.forEach(line => {
-          const paddedLine = line.slice(0, 54).padEnd(54);
-          console.log(`│     > ${paddedLine} │`);
-        });
-      } else {
-        console.log(`│     > None                                               │`);
-      }
-      console.log(`├${border}┤`);
-      console.log(`│ Hint: Use this context to continue resolving the issue   │`);
-      console.log(`│       efficiently or start on a new path.                │`);
-      console.log(`└${border}┘\n`);
-    }
-  } catch (err) {
-    // Ignore malformed files
-  }
-}
-
-console.log("Harness OS initialized. Ready for user prompt.");
-
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const {
+  getWorkspaceRoot,
+  getSessionId,
+  getSessionDir,
+  writeCurrentSession,
+  pruneStaleSessions,
+} = require('../../hooks/scripts/lib/harness-state');
+
+console.log("Bootstrapping Harness Skills OS...");
+
+// SessionStart hooks receive a payload with session_id via stdin, same as
+// every other hook. Read it synchronously up front - bootstrap has no
+// tool-call latency to protect, so there's no fast-path tradeoff here - but
+// skip entirely on an interactive TTY (manual run) where reading fd 0 would
+// just hang waiting for input that's never coming.
+let payload = null;
+if (!process.stdin.isTTY) {
+  try {
+    const raw = fs.readFileSync(0, 'utf8');
+    payload = JSON.parse(raw);
+  } catch (err) {
+    // No payload piped in, or invalid JSON - fall back to 'default'.
+  }
+}
+const sessionId = getSessionId(payload);
+
+const root = getWorkspaceRoot(payload);
+
+// Guard: only materialize state in a workspace that actually has Harness
+// installed. Without this, running a Claude session in any random folder
+// (or using the agent for non-engineering chat) would still create
+// state directories and session files there. A workspace counts as
+// managed when it is a git repo AND carries at least one Harness install
+// marker - or IS the harness-everything source repo itself (so manual
+// VERIFICATION.md runs keep working after a fresh clone).
+function isManagedWorkspace(wsRoot) {
+  if (!fs.existsSync(path.join(wsRoot, '.git'))) return false;
+  if (fs.existsSync(path.join(wsRoot, 'harness-everything', 'scripts', 'bootstrap.js'))) return true;
+  const markers = [
+    path.join(wsRoot, '.claude', 'settings.json'),
+    path.join(wsRoot, '.cursorrules'),
+    path.join(wsRoot, '.github', 'copilot-instructions.md'),
+    path.join(wsRoot, 'AGENTS.md'),
+    path.join(wsRoot, '.continue', 'rules', 'harness.md'),
+    path.join(wsRoot, '.hermes.md'),
+  ];
+  return markers.some(m => fs.existsSync(m));
+}
+
+if (!isManagedWorkspace(root)) {
+  // Stay completely silent: hooks must never surprise the user with files
+  // or output in workspaces Harness was never installed into.
+  process.exit(0);
+}
+
+// Nothing purges old session directories the way an OS temp dir would -
+// drop ones untouched for a while so .claude/harness-everything/state/sessions/ doesn't
+// grow forever.
+pruneStaleSessions(root);
+
+// The manual escape hatch (reset-circuit-breaker.js) and any CLI tool that
+// can't see a session_id, resolve "current session" through
+// this pointer.
+writeCurrentSession(root, sessionId);
+
+const harnessDir = getSessionDir(root, sessionId);
+
+// The Rule of 3 circuit breaker (hooks/scripts/rule-of-3.js) locks all
+// Bash/Edit/Write calls once tripped; the only in-session exits are a valid
+// zoom-out reflection report or a human reset. A new SessionStart means the
+// human has taken over (new session, /clear, /compact) and reviewed the
+// situation, so it's safe to clear here. The stale reflection report goes
+// with it - it belongs to the previous loop, not this session.
+const circuitBreakerFile = path.join(harnessDir, 'rule-of-3-state.json');
+if (fs.existsSync(circuitBreakerFile)) {
+  try {
+    fs.unlinkSync(circuitBreakerFile);
+    console.log("Rule of 3 circuit breaker state cleared for new session.");
+  } catch (err) {
+    // Ignore; worst case the breaker stays tripped until manually reset.
+  }
+}
+const zoomOutReportFile = path.join(harnessDir, 'zoom-out-report.md');
+if (fs.existsSync(zoomOutReportFile)) {
+  try {
+    fs.unlinkSync(zoomOutReportFile);
+  } catch (err) {
+    // Ignore; rule-of-3.js already rejects reports older than the last failure.
+  }
+}
+
+// Same reasoning: a stale subagent-scope baseline from a previous session
+// would make the first Task burst of this session diff against the wrong
+// starting point.
+const subagentScopeFile = path.join(harnessDir, 'subagent-scope-state.json');
+if (fs.existsSync(subagentScopeFile)) {
+  try {
+    fs.unlinkSync(subagentScopeFile);
+  } catch (err) {
+    // Ignore.
+  }
+}
+
+// Self-heal audit: report missing platform integration touchpoints so the
+// model (per harness-everything SKILL.md) repairs them via self-heal.js.
+// Audit-and-report only - bootstrap never writes these files itself, so a
+// user who intentionally removed one isn't fought every session start.
+try {
+  const MARKER = 'Harness OS Guidance (Advisory)';
+  const HOOK_ID = 'harness:pre:bootstrap';
+  const workspaceRoot = getWorkspaceRoot(payload);
+  const contains = (p, needle) => {
+    try { return fs.readFileSync(p, 'utf8').includes(needle); } catch (e) { return false; }
+  };
+
+  const isClaudeEnv = process.env.CLAUDE_CODE === 'true' || process.env.SHELL?.includes('claude-code') || false;
+  const isCursorEnv = process.env.TERM_PROGRAM === 'cursor' || process.env.CURSOR_SANDBOX !== undefined || false;
+  const isCopilotEnv = process.env.GITHUB_COPILOT_CHAT === 'true' || process.env.COPILOT_AGENT === '1' || process.env.AI_AGENT?.includes('copilot') || process.env.TERM_PROGRAM === 'vscode' || process.env.VSCODE_PID !== undefined || false;
+
+  const hasClaude = fs.existsSync(path.join(workspaceRoot, '.claude'));
+  const hasCursor = fs.existsSync(path.join(workspaceRoot, '.cursorrules')) || fs.existsSync(path.join(workspaceRoot, '.cursor'));
+  const hasCopilot = fs.existsSync(path.join(workspaceRoot, '.github', 'copilot-instructions.md'));
+  const hasCodex = fs.existsSync(path.join(workspaceRoot, 'AGENTS.md'));
+
+  const activePlatforms = {
+    claude: isClaudeEnv || hasClaude,
+    cursor: isCursorEnv || hasCursor,
+    copilot: (!isClaudeEnv && !isCursorEnv && isCopilotEnv) || hasCopilot,
+    codex: hasCodex
+  };
+
+  // If no platforms are active, fallback to current environment
+  const hasAnyActive = Object.values(activePlatforms).some(v => v);
+  if (!hasAnyActive) {
+    if (isClaudeEnv) {
+      activePlatforms.claude = true;
+    } else if (isCursorEnv) {
+      activePlatforms.cursor = true;
+    } else {
+      activePlatforms.copilot = true;
+    }
+  }
+
+  const missing = [];
+  if (activePlatforms.claude && !contains(path.join(workspaceRoot, '.claude', 'settings.json'), HOOK_ID)) {
+    missing.push('.claude/settings.json (Claude Code hooks)');
+  }
+  if (activePlatforms.cursor && !contains(path.join(workspaceRoot, '.cursorrules'), MARKER)) {
+    missing.push('.cursorrules (Cursor)');
+  }
+  if (activePlatforms.copilot && !contains(path.join(workspaceRoot, '.github', 'copilot-instructions.md'), MARKER)) {
+    missing.push('.github/copilot-instructions.md (Copilot)');
+  }
+  if (activePlatforms.codex && !contains(path.join(workspaceRoot, 'AGENTS.md'), MARKER)) {
+    missing.push('AGENTS.md (Codex)');
+  }
+
+  // Identity, not path: __dirname/../.. is the INSTALLED copy's root, so an
+  // npx/global install auditing the harness checkout itself compares two
+  // different paths and wrongly advises a repair that self-heal then skips
+  // (issue #40). Required lazily so a missing lib can never break session start.
+  const { isHarnessRepo } = require('../../scripts/lib/workspace');
+  const auditingSelf = isHarnessRepo(workspaceRoot)
+    || path.resolve(workspaceRoot) === path.resolve(__dirname, '..', '..');
+
+  if (missing.length > 0 && !auditingSelf) {
+    console.log(`\n[Self-Heal] Missing integration touchpoints: ${missing.join(', ')}`);
+    console.log(`[Self-Heal] Repair (idempotent): node "${path.join(__dirname, 'self-heal.js')}"`);
+  }
+} catch (err) {
+  // Audit is best-effort; never block session start.
+}
+
+// Check for handoff/state checkpoint from previous session
+const handoffFile = path.join(harnessDir, 'handoff-state.json');
+if (fs.existsSync(handoffFile)) {
+  try {
+    const handoff = JSON.parse(fs.readFileSync(handoffFile, 'utf8'));
+    if (handoff.status === 'failed') {
+      const exitStr = handoff.exitCode ? ` (exit code ${handoff.exitCode})` : '';
+      const border = "─".repeat(60);
+      console.log(`\n┌${border}┐`);
+      console.log(`│             Harness OS - Handoff Checkpoint              │`);
+      console.log(`├${border}┤`);
+      console.log(`│ - Last active action failed${exitStr.padEnd(30)} │`);
+      console.log(`│ - Action: ${String(handoff.tool || 'unknown').padEnd(46)} │`);
+      console.log(`│ - Last error output snippet:                             │`);
+      
+      const snippet = handoff.errorSummary || 'No snippet available';
+      const lines = snippet.split('\n').map(l => l.trim()).filter(Boolean).slice(-3);
+      if (lines.length > 0) {
+        lines.forEach(line => {
+          const paddedLine = line.slice(0, 54).padEnd(54);
+          console.log(`│     > ${paddedLine} │`);
+        });
+      } else {
+        console.log(`│     > None                                               │`);
+      }
+      console.log(`├${border}┤`);
+      console.log(`│ Hint: Use this context to continue resolving the issue   │`);
+      console.log(`│       efficiently or start on a new path.                │`);
+      console.log(`└${border}┘\n`);
+    }
+  } catch (err) {
+    // Ignore malformed files
+  }
+}
+
+console.log("Harness OS initialized. Ready for user prompt.");