harness-everything 0.14.0 → 0.16.0

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

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

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to this project are documented in this file.
 
+## [0.16.0](https://github.com/dyphn1/Harness-everything/compare/v0.15.0...v0.16.0) (2026-09-20)
+
+### Features
+
+* **codex:** add explicit hooks compatibility installer ([3fb622b](https://github.com/dyphn1/Harness-everything/commit/3fb622b57eef3a9ee5110529bcd2cdc8c81b6a75))
+* **codex:** expose explicit hook fallback CLI ([83e4cf1](https://github.com/dyphn1/Harness-everything/commit/83e4cf1eadd77585d4681bb73acbf360efd63509))
+
+### Bug Fixes
+
+* **codex:** contain compatibility runtime paths ([1ffcc0d](https://github.com/dyphn1/Harness-everything/commit/1ffcc0d984e7dbfd2dd987a03b189fb950e83de8))
+* **codex:** do not recreate removed hooks config ([ee62a1d](https://github.com/dyphn1/Harness-everything/commit/ee62a1d9f466a2e585e4737576a7289ae12087d5))
+* **codex:** fail closed on duplicate compat hooks ([29920d0](https://github.com/dyphn1/Harness-everything/commit/29920d07e76a73c84c35440b60453c3e0b648b29))
+* **codex:** harden compatibility hook ownership ([3ff5c14](https://github.com/dyphn1/Harness-everything/commit/3ff5c1456e6c44398ef661763057c93bcfcbb57c))
+* **codex:** record only inserted hook ownership ([90e0c9b](https://github.com/dyphn1/Harness-everything/commit/90e0c9bbfd4672955473d33f2e33832f760bf294))
+
+## [0.15.0](https://github.com/dyphn1/Harness-everything/compare/v0.14.0...v0.15.0) (2026-09-20)
+
+### Features
+
+* **contract:** add freshness provenance helpers ([865fc0b](https://github.com/dyphn1/Harness-everything/commit/865fc0bdb111feff865c3a85767fc587aecbd11a))
+* **contract:** emit requirement-scoped repair guidance ([cbd33ce](https://github.com/dyphn1/Harness-everything/commit/cbd33ce18fb8575671056bd4b2701bd0138baa96))
+* **contract:** reject stale completion reports ([79ea49e](https://github.com/dyphn1/Harness-everything/commit/79ea49e40f110fe062ac714519597e8a23a6ab5b))
+* **contract:** sync freshness audit runtime ([c5d0381](https://github.com/dyphn1/Harness-everything/commit/c5d038163b7ff2dc14e11bd4733e140e85e39f55))
+
+### Bug Fixes
+
+* **contract:** harden freshness evidence boundaries ([33ebbda](https://github.com/dyphn1/Harness-everything/commit/33ebbdafb2b63c4ece86ee81c14c4fcc6d33907f))
+* **contract:** launch npm probes cross-platform ([9ca5315](https://github.com/dyphn1/Harness-everything/commit/9ca5315cb30e8f03b08fb1f8789a141ea1179af4))
+* **contract:** launch npm probes cross-platform ([2cad76e](https://github.com/dyphn1/Harness-everything/commit/2cad76e217af136d934946f05c740d816e051acd))
+* **contract:** require complete freshness provenance ([5b6d717](https://github.com/dyphn1/Harness-everything/commit/5b6d717487fce37dcd1d1e8cbe8b037597035103))
+* **contract:** require complete freshness provenance ([d94e256](https://github.com/dyphn1/Harness-everything/commit/d94e2562c54d615d223a8572fd4d468e017a5807))
+
 ## [0.14.0](https://github.com/dyphn1/Harness-everything/compare/v0.13.0...v0.14.0) (2026-09-20)
 
 ### Features

package/bin/cli.js

@@ -37,6 +37,9 @@ switch (command) {
   case 'verify-install':
     runInstallVerification(args.slice(1));
     break;
+  case 'codex-hooks':
+    runCodexHooksCompat(args.slice(1));
+    break;
   default:
     console.error(`[Error] Unknown command: "${command}"`);
     showHelp();
@@ -97,6 +100,10 @@ Commands:
                      work; hosts with UserPromptSubmit hooks receive it automatically.
   verify-install     Compare installed Harness manifests and skill trees with
                      this package source; stale versions or missing files fail.
+  codex-hooks        Explicit Codex user-hook compatibility fallback for hosts
+                     that fail to mount enabled plugin-bundled hooks.
+                     Usage: harness codex-hooks <install|status|uninstall>
+                     Does not trust hooks or modify Codex config.toml.
   verify             Run the pre-delivery verification gate (lint/test from the
                      nearest package.json). Exits non-zero if checks fail. This is
                      the explicit stand-in for a hard stop gate on platforms where
@@ -162,3 +169,13 @@ function runInstallVerification(verifyArgs) {
   const result = spawnSync('node', [script, ...verifyArgs], { stdio: 'inherit' });
   process.exit(result.status === null ? 1 : result.status);
 }
+
+function runCodexHooksCompat(compatArgs) {
+  const script = path.resolve(__dirname, '..', 'scripts', 'codex-hooks-compat.js');
+  if (!fs.existsSync(script)) {
+    console.error('[Error] Codex hooks compatibility script not found.');
+    process.exit(1);
+  }
+  const result = spawnSync('node', [script, ...compatArgs], { stdio: 'inherit' });
+  process.exit(result.status === null ? 1 : result.status);
+}

package/ci/contract-integrity.test.js

@@ -265,5 +265,159 @@ for (const relative of [
     'Phase 2 OpenAI package mirror matches canonical: ' + relative);
 }
 
-console.log(`\n${failed === 0 ? 'PASS' : 'FAIL'}: #84 contract integrity phase 1-2 (${failed} failure${failed === 1 ? '' : 's'})`);
+// Phase 4: reports carry actionable requirement-scoped repair guidance and
+// content fingerprints so stale completion evidence cannot be reused.
+check(driftReport.repairGuidance.some(item =>
+  item.requirementId === 'REQ-001' && item.code === 'update-living-spec' &&
+  item.sourceRef === 'docs/specs/api.md#REQ-001'),
+  'stale-spec drift emits requirement-scoped living-spec repair guidance');
+check(paddedReport.repairGuidance.some(item =>
+  item.requirementId === 'REQ-001' && item.code === 'strengthen-weak-oracle' && item.priority === 'BLOCKER'),
+  'surviving required probe emits BLOCKER weak-oracle guidance');
+check(/Repair Guidance/.test(markdown(driftReport)) && /REQ-001/.test(markdown(driftReport)),
+  'Markdown keeps repair guidance concise and tied to requirement identity');
+
+const freshRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-contract-freshness-'));
+try {
+  const workspace = path.join(freshRoot, 'workspace');
+  fs.mkdirSync(workspace, { recursive: true });
+  for (const artifact of baseline.artifacts) {
+    const file = path.join(workspace, artifact.path);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, artifact.id + ': fixture content\n', 'utf8');
+  }
+  const tracePath = path.join(freshRoot, 'trace.json');
+  const tddPath = path.join(freshRoot, 'tdd.json');
+  const reportPath = path.join(freshRoot, 'report.json');
+  fs.writeFileSync(tracePath, JSON.stringify(baseline), 'utf8');
+  fs.writeFileSync(tddPath, JSON.stringify(baselineTdd), 'utf8');
+
+  const unboundReportPath = path.join(freshRoot, 'report-unbound.json');
+  const unboundAudit = spawnSync(process.execPath, [
+    path.join(ROOT, 'contract-integrity/scripts/audit.js'),
+    tracePath,
+    '--tdd-evidence', tddPath,
+    '--output', unboundReportPath,
+  ], { encoding: 'utf8' });
+  check(unboundAudit.status === 0, 'strict audit may emit a PASS report without workspace binding for immediate inspection');
+  const emptyWorkspace = path.join(freshRoot, 'empty-workspace');
+  fs.mkdirSync(emptyWorkspace, { recursive: true });
+  const unboundFreshness = spawnSync(process.execPath, [
+    path.join(ROOT, 'contract-integrity/scripts/audit.js'),
+    tracePath,
+    '--tdd-evidence', tddPath,
+    '--workspace', emptyWorkspace,
+    '--verify-fresh', unboundReportPath,
+  ], { encoding: 'utf8' });
+  check(unboundFreshness.status === 1 &&
+    /report-workspace-unbound/.test(unboundFreshness.stderr) &&
+    /artifact-fingerprint-missing:/.test(unboundFreshness.stderr),
+    'report created without workspace fingerprints cannot later authorize freshness against a supplied workspace');
+
+  const audit = spawnSync(process.execPath, [
+    path.join(ROOT, 'contract-integrity/scripts/audit.js'),
+    tracePath,
+    '--tdd-evidence', tddPath,
+    '--workspace', workspace,
+    '--output', reportPath,
+  ], { encoding: 'utf8' });
+  check(audit.status === 0, 'strict audit with existing workspace artifacts produces fresh PASS report', audit.stderr);
+  const freshReport = JSON.parse(fs.readFileSync(reportPath, 'utf8'));
+  check(freshReport.provenance?.inputs?.trace?.sha256 &&
+    freshReport.provenance?.inputs?.tddEvidence?.sha256 &&
+    freshReport.provenance?.artifacts?.length === baseline.artifacts.length &&
+    freshReport.provenance.artifacts.every(item => item.sha256 && item.missing === false),
+    'report provenance records trace/TDD hashes plus current artifact hashes');
+
+  const verifyFresh = () => spawnSync(process.execPath, [
+    path.join(ROOT, 'contract-integrity/scripts/audit.js'),
+    tracePath,
+    '--tdd-evidence', tddPath,
+    '--workspace', workspace,
+    '--verify-fresh', reportPath,
+  ], { encoding: 'utf8' });
+
+  const current = verifyFresh();
+  check(current.status === 0 && /Freshness: PASS/.test(current.stdout),
+    'unchanged PASS report can authorize completion');
+
+  const failingTracePath = path.join(freshRoot, 'trace-failing.json');
+  const failingReportPath = path.join(freshRoot, 'report-failing.json');
+  const failingTrace = clone(baseline);
+  failingTrace.probes[0].status = 'SURVIVED';
+  failingTrace.probes[0].failureClass = 'none';
+  fs.writeFileSync(failingTracePath, JSON.stringify(failingTrace), 'utf8');
+  const failingAudit = spawnSync(process.execPath, [
+    path.join(ROOT, 'contract-integrity/scripts/audit.js'),
+    failingTracePath,
+    '--tdd-evidence', tddPath,
+    '--workspace', workspace,
+    '--output', failingReportPath,
+  ], { encoding: 'utf8' });
+  check(failingAudit.status === 1, 'surviving required probe produces a reusable FAIL report fixture');
+  const forgedReport = JSON.parse(fs.readFileSync(failingReportPath, 'utf8'));
+  forgedReport.result = 'PASS';
+  forgedReport.completionGate = 'PASS';
+  fs.writeFileSync(failingReportPath, JSON.stringify(forgedReport), 'utf8');
+  const forgedFreshness = spawnSync(process.execPath, [
+    path.join(ROOT, 'contract-integrity/scripts/audit.js'),
+    failingTracePath,
+    '--tdd-evidence', tddPath,
+    '--workspace', workspace,
+    '--verify-fresh', failingReportPath,
+  ], { encoding: 'utf8' });
+  check(forgedFreshness.status === 1 && /current-audit-not-pass/.test(forgedFreshness.stderr),
+    'freshness verification re-derives the current gate instead of trusting forged PASS fields');
+
+  const linkedWorkspace = path.join(freshRoot, 'linked-workspace');
+  fs.mkdirSync(linkedWorkspace, { recursive: true });
+  for (const artifact of baseline.artifacts.filter(item => item.id !== 'IMPL-001')) {
+    const file = path.join(linkedWorkspace, artifact.path);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, artifact.id + ': fixture content\n', 'utf8');
+  }
+  const outsideImpl = path.join(freshRoot, 'outside-implementation');
+  fs.mkdirSync(outsideImpl, { recursive: true });
+  fs.writeFileSync(path.join(outsideImpl, 'api.js'), 'IMPL-001: fixture content\n', 'utf8');
+  fs.symlinkSync(outsideImpl, path.join(linkedWorkspace, 'src'),
+    process.platform === 'win32' ? 'junction' : 'dir');
+  const linkedAudit = spawnSync(process.execPath, [
+    path.join(ROOT, 'contract-integrity/scripts/audit.js'),
+    tracePath,
+    '--tdd-evidence', tddPath,
+    '--workspace', linkedWorkspace,
+  ], { encoding: 'utf8' });
+  check(linkedAudit.status === 2 && /linked-path: IMPL-001/.test(linkedAudit.stderr),
+    'workspace-aware audit rejects artifact paths that resolve through a symlink or junction');
+
+  const testArtifact = path.join(workspace, 'tests/api.test.js');
+  fs.appendFileSync(testArtifact, 'changed after audit\n', 'utf8');
+  const staleTestReport = verifyFresh();
+  check(staleTestReport.status === 1 &&
+    /artifact-changed-since-audit:TEST-001/.test(staleTestReport.stderr),
+    'test artifact change invalidates previously passing report');
+  fs.writeFileSync(testArtifact, 'TEST-001: fixture content\n', 'utf8');
+
+  fs.writeFileSync(tddPath, JSON.stringify({ ...baselineTdd, changedAfterAudit: true }), 'utf8');
+  const staleEvidence = verifyFresh();
+  check(staleEvidence.status === 1 &&
+    /tdd-evidence-changed-since-audit/.test(staleEvidence.stderr),
+    '#58 evidence change invalidates previously passing report');
+
+  fs.writeFileSync(tddPath, JSON.stringify(baselineTdd), 'utf8');
+  fs.rmSync(path.join(workspace, 'src/api.js'));
+  const missingArtifactAudit = spawnSync(process.execPath, [
+    path.join(ROOT, 'contract-integrity/scripts/audit.js'),
+    tracePath,
+    '--tdd-evidence', tddPath,
+    '--workspace', workspace,
+  ], { encoding: 'utf8' });
+  check(missingArtifactAudit.status === 2 &&
+    /provenance artifact missing from workspace: IMPL-001/.test(missingArtifactAudit.stderr),
+    'strict workspace-aware audit fails closed when traced implementation evidence is missing');
+} finally {
+  fs.rmSync(freshRoot, { recursive: true, force: true });
+}
+
+console.log(`\n${failed === 0 ? 'PASS' : 'FAIL'}: #84 contract integrity phase 1-4 mechanism (${failed} failure${failed === 1 ? '' : 's'})`);
 process.exit(failed === 0 ? 0 : 1);

package/ci/mechanism-2al-codex-hooks-compat.test.js

@@ -0,0 +1,286 @@
+#!/usr/bin/env node
+'use strict';
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const compat = require('../scripts/codex-hooks-compat');
+
+let failed = 0;
+function check(condition, message, detail = '') {
+  if (condition) console.log('  PASS ' + message);
+  else {
+    failed++;
+    console.error('  FAIL ' + message + (detail ? ' — ' + detail : ''));
+  }
+}
+
+function read(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function findHarnessEntries(config, runtimeDir) {
+  const out = [];
+  for (const [event, entries] of Object.entries(config.hooks || {})) {
+    for (const entry of entries || []) {
+      if (JSON.stringify(entry).toLowerCase().includes(path.resolve(runtimeDir).replace(/\\/g, '\\\\').toLowerCase()) ||
+          JSON.stringify(entry).replace(/\\\\/g, '/').toLowerCase().includes(path.resolve(runtimeDir).replace(/\\/g, '/').toLowerCase())) {
+        out.push({ event, entry });
+      }
+    }
+  }
+  return out;
+}
+
+console.log('\n[2al] Codex user-hook compatibility fallback (#122)...');
+
+const root = fs.mkdtempSync(path.join(os.tmpdir(), 'harness-codex-hooks-compat-'));
+const codexHome = path.join(root, '.codex');
+fs.mkdirSync(codexHome, { recursive: true });
+const hooksFile = path.join(codexHome, 'hooks.json');
+const configFile = path.join(codexHome, 'config.toml');
+const userHook = {
+  matcher: 'Bash',
+  hooks: [{
+    type: 'command',
+    command: 'node "/user/policy.js"',
+    timeout: 7,
+    statusMessage: 'User policy',
+  }],
+};
+const original = {
+  description: 'user-owned metadata',
+  hooks: {
+    PreToolUse: [userHook],
+    Stop: [{
+      hooks: [{ type: 'command', command: 'node "/user/stop.js"', timeout: 5 }],
+    }],
+  },
+};
+fs.writeFileSync(hooksFile, JSON.stringify(original, null, 4) + '\n', 'utf8');
+fs.writeFileSync(configFile, 'model = "test"\n# user trust/config state\n', 'utf8');
+const configBefore = fs.readFileSync(configFile, 'utf8');
+
+try {
+  const installed = compat.install({ codexHome });
+  check(installed.status === 'installed' && installed.entries > 0,
+    'explicit install materializes compatibility entries');
+  check(installed.trustChanged === false && fs.readFileSync(configFile, 'utf8') === configBefore,
+    'install never changes Codex trust/config.toml state');
+
+  const state = compat.status({ codexHome });
+  check(state.installed && state.healthy && state.exactEntriesPresent === state.expectedEntries,
+    'status verifies exact installed entry hashes and runtime tree');
+
+  const config = read(hooksFile);
+  check(config.description === original.description &&
+    JSON.stringify(config.hooks.PreToolUse[0]) === JSON.stringify(userHook) &&
+    config.hooks.Stop.some(entry => entry.hooks?.[0]?.command === 'node "/user/stop.js"'),
+    'existing unrelated user hooks and top-level metadata are preserved semantically');
+
+  const manifest = read(path.join(codexHome, 'harness-everything', 'compat-hooks', 'manifest.json'));
+  const harnessEntries = findHarnessEntries(config, manifest.runtimeDir);
+  check(harnessEntries.length === manifest.entries.length,
+    'every compatibility hook command resolves to the Harness-owned runtime copy');
+  check(!JSON.stringify(harnessEntries).includes('${PLUGIN_ROOT}') &&
+    !JSON.stringify(harnessEntries).includes('${CLAUDE_PLUGIN_ROOT}') &&
+    !JSON.stringify(harnessEntries).includes('%PLUGIN_ROOT%'),
+    'compatibility entries use literal absolute runtime paths without shell-specific plugin expansion');
+  check(fs.existsSync(path.join(manifest.runtimeDir, 'hooks', 'scripts', 'codex-action-gate-pre.js')) &&
+    fs.existsSync(path.join(manifest.runtimeDir, 'skills', 'harness-everything', 'scripts', 'kernel-router.js')),
+    'compatibility runtime is self-contained for hook and router dependencies');
+
+  const countsBefore = Object.fromEntries(Object.entries(config.hooks).map(([event, entries]) => [event, entries.length]));
+  const updated = compat.install({ codexHome });
+  const configAfterUpdate = read(hooksFile);
+  const countsAfter = Object.fromEntries(Object.entries(configAfterUpdate.hooks).map(([event, entries]) => [event, entries.length]));
+  check(updated.status === 'updated' && JSON.stringify(countsAfter) === JSON.stringify(countsBefore),
+    'reinstall/update is idempotent and does not duplicate hook entries');
+
+  configAfterUpdate.hooks.PostToolUse = configAfterUpdate.hooks.PostToolUse || [];
+  const addedUserHook = { hooks: [{ type: 'command', command: 'node "/user/later.js"', timeout: 3 }] };
+  configAfterUpdate.hooks.PostToolUse.unshift(addedUserHook);
+  fs.writeFileSync(hooksFile, JSON.stringify(configAfterUpdate, null, 2) + '\n', 'utf8');
+  compat.install({ codexHome });
+  check(read(hooksFile).hooks.PostToolUse.some(entry => entry.hooks?.[0]?.command === 'node "/user/later.js"'),
+    'update preserves user hooks added after the initial compatibility install');
+
+  const beforeTamper = fs.readFileSync(hooksFile, 'utf8');
+  const tampered = read(hooksFile);
+  const currentManifest = read(path.join(codexHome, 'harness-everything', 'compat-hooks', 'manifest.json'));
+  let changed = false;
+  for (const [event, entries] of Object.entries(tampered.hooks)) {
+    for (const entry of entries) {
+      if (!changed && JSON.stringify(entry).replace(/\\\\/g, '/').toLowerCase()
+          .includes(path.resolve(currentManifest.runtimeDir).replace(/\\/g, '/').toLowerCase())) {
+        entry.hooks[0].statusMessage = 'user modified this installed Harness hook';
+        changed = true;
+      }
+    }
+  }
+  fs.writeFileSync(hooksFile, JSON.stringify(tampered, null, 2) + '\n', 'utf8');
+  const tamperedBytes = fs.readFileSync(hooksFile, 'utf8');
+  let updateRefused = false;
+  try { compat.install({ codexHome }); } catch (error) { updateRefused = /modified/.test(error.message); }
+  check(updateRefused && fs.readFileSync(hooksFile, 'utf8') === tamperedBytes,
+    'modified Harness compatibility entry makes update fail closed without rewriting user config');
+
+  let uninstallRefused = false;
+  try { compat.uninstall({ codexHome }); } catch (error) { uninstallRefused = /modified/.test(error.message); }
+  check(uninstallRefused && fs.readFileSync(hooksFile, 'utf8') === tamperedBytes,
+    'modified Harness compatibility entry makes uninstall fail closed rather than deleting user edits');
+
+  // Restore the exact generated config by starting from the pre-tamper bytes.
+  fs.writeFileSync(hooksFile, beforeTamper, 'utf8');
+  compat.install({ codexHome });
+  const removed = compat.uninstall({ codexHome });
+  const finalConfig = read(hooksFile);
+  check(removed.status === 'uninstalled' && removed.removed > 0 && removed.trustChanged === false,
+    'explicit uninstall removes exact Harness-owned entries without changing trust state');
+  check(finalConfig.description === original.description &&
+    finalConfig.hooks.PreToolUse.some(entry => entry.hooks?.[0]?.command === 'node "/user/policy.js"') &&
+    finalConfig.hooks.Stop.some(entry => entry.hooks?.[0]?.command === 'node "/user/stop.js"') &&
+    finalConfig.hooks.PostToolUse.some(entry => entry.hooks?.[0]?.command === 'node "/user/later.js"'),
+    'uninstall preserves unrelated pre-existing and later-added user hooks');
+  check(fs.readFileSync(configFile, 'utf8') === configBefore,
+    'uninstall leaves config.toml/trust state byte-identical');
+  check(!fs.existsSync(path.join(codexHome, 'harness-everything', 'compat-hooks', 'manifest.json')),
+    'uninstall removes Harness compatibility ownership manifest');
+
+  const emptyHome = path.join(root, 'empty-codex');
+  fs.mkdirSync(emptyHome, { recursive: true });
+  compat.install({ codexHome: emptyHome });
+  check(fs.existsSync(path.join(emptyHome, 'hooks.json')),
+    'compatibility install can create a new hooks.json when none exists');
+  compat.uninstall({ codexHome: emptyHome });
+  check(!fs.existsSync(path.join(emptyHome, 'hooks.json')),
+    'uninstall removes hooks.json only when Harness created it and no user entries remain');
+
+  const duplicateHome = path.join(root, 'duplicate-codex');
+  fs.mkdirSync(duplicateHome, { recursive: true });
+  compat.install({ codexHome: duplicateHome });
+  const duplicateConfig = read(path.join(duplicateHome, 'hooks.json'));
+  duplicateConfig.hooks.PreToolUse.push(JSON.parse(JSON.stringify(duplicateConfig.hooks.PreToolUse[0])));
+  fs.writeFileSync(path.join(duplicateHome, 'hooks.json'), JSON.stringify(duplicateConfig, null, 2) + '\n', 'utf8');
+  const duplicateBytes = fs.readFileSync(path.join(duplicateHome, 'hooks.json'), 'utf8');
+  let duplicateRefused = false;
+  try { compat.uninstall({ codexHome: duplicateHome }); } catch (error) { duplicateRefused = /modified/.test(error.message); }
+  check(duplicateRefused && fs.readFileSync(path.join(duplicateHome, 'hooks.json'), 'utf8') === duplicateBytes,
+    'extra identical Harness hook is treated as user config drift, not silently deleted');
+
+  const removedConfigHome = path.join(root, 'removed-config-codex');
+  fs.mkdirSync(removedConfigHome, { recursive: true });
+  fs.writeFileSync(path.join(removedConfigHome, 'hooks.json'), JSON.stringify(original, null, 2) + '\n', 'utf8');
+  compat.install({ codexHome: removedConfigHome });
+  fs.rmSync(path.join(removedConfigHome, 'hooks.json'), { force: true });
+  const removedConfigResult = compat.uninstall({ codexHome: removedConfigHome });
+  check(removedConfigResult.status === 'uninstalled' && !fs.existsSync(path.join(removedConfigHome, 'hooks.json')),
+    'uninstall never recreates a user hooks.json that was removed after compatibility install');
+
+  const preexistingHome = path.join(root, 'preexisting-identical-codex');
+  fs.mkdirSync(preexistingHome, { recursive: true });
+  const sourceHash = compat.treeHash(compat.SOURCE_PLUGIN_ROOT);
+  const preexistingPaths = compat.pathsFor(preexistingHome, sourceHash);
+  const preexistingEntries = compat.sourceHookEntries(preexistingPaths.runtimeDir);
+  const preexistingHooks = {};
+  for (const record of preexistingEntries) {
+    preexistingHooks[record.event] = preexistingHooks[record.event] || [];
+    preexistingHooks[record.event].push(JSON.parse(JSON.stringify(record.entry)));
+  }
+  fs.writeFileSync(path.join(preexistingHome, 'hooks.json'),
+    JSON.stringify({ hooks: preexistingHooks }, null, 2) + '\n', 'utf8');
+  const preexistingBefore = fs.readFileSync(path.join(preexistingHome, 'hooks.json'), 'utf8');
+  const preexistingInstall = compat.install({ codexHome: preexistingHome });
+  const preexistingManifest = read(path.join(preexistingHome, 'harness-everything', 'compat-hooks', 'manifest.json'));
+  check(preexistingInstall.status === 'installed' && preexistingManifest.entries.length === 0,
+    'byte-identical pre-existing user hooks are reused but never recorded as Harness-owned');
+  const preexistingRemoved = compat.uninstall({ codexHome: preexistingHome });
+  check(preexistingRemoved.removed === 0 &&
+    fs.readFileSync(path.join(preexistingHome, 'hooks.json'), 'utf8') === preexistingBefore,
+    'uninstall preserves byte-identical hooks that predated compatibility install');
+
+  const forgedManifestHome = path.join(root, 'forged-manifest-codex');
+  fs.mkdirSync(forgedManifestHome, { recursive: true });
+  fs.writeFileSync(path.join(forgedManifestHome, 'hooks.json'),
+    JSON.stringify({ hooks: { PreToolUse: [userHook] } }, null, 2) + '\n', 'utf8');
+  compat.install({ codexHome: forgedManifestHome });
+  const forgedManifestPath = path.join(
+    forgedManifestHome, 'harness-everything', 'compat-hooks', 'manifest.json');
+  const forgedManifest = read(forgedManifestPath);
+  forgedManifest.entries.push({
+    event: 'PreToolUse',
+    hash: compat.entryHash(userHook),
+    entry: userHook,
+  });
+  fs.writeFileSync(forgedManifestPath, JSON.stringify(forgedManifest, null, 2) + '\n', 'utf8');
+  const forgedHooksBefore = fs.readFileSync(path.join(forgedManifestHome, 'hooks.json'), 'utf8');
+  let forgedManifestRefused = false;
+  try { compat.uninstall({ codexHome: forgedManifestHome }); }
+  catch (error) { forgedManifestRefused = /corrupt/.test(error.message); }
+  check(forgedManifestRefused &&
+    fs.readFileSync(path.join(forgedManifestHome, 'hooks.json'), 'utf8') === forgedHooksBefore,
+    'forged manifest ownership fails closed without deleting a user hook');
+
+  const failedInstallHome = path.join(root, 'failed-install-codex');
+  fs.mkdirSync(failedInstallHome, { recursive: true });
+  const failedInstallHooks = path.join(failedInstallHome, 'hooks.json');
+  fs.writeFileSync(failedInstallHooks,
+    JSON.stringify({ description: 'must survive', hooks: { PreToolUse: [userHook] } }, null, 4) + '\n',
+    'utf8');
+  const failedInstallBefore = fs.readFileSync(failedInstallHooks, 'utf8');
+  const failedManifestPath = path.join(
+    failedInstallHome, 'harness-everything', 'compat-hooks', 'manifest.json');
+  const realRenameSync = fs.renameSync;
+  let failedInstallRefused = false;
+  fs.renameSync = function injectedManifestFailure(source, destination) {
+    if (path.resolve(destination) === path.resolve(failedManifestPath)) {
+      throw new Error('injected manifest commit failure');
+    }
+    return realRenameSync(source, destination);
+  };
+  try { compat.install({ codexHome: failedInstallHome }); }
+  catch (error) { failedInstallRefused = /injected manifest commit failure/.test(error.message); }
+  finally { fs.renameSync = realRenameSync; }
+  check(failedInstallRefused &&
+    fs.readFileSync(failedInstallHooks, 'utf8') === failedInstallBefore &&
+    !fs.existsSync(failedManifestPath),
+    'failed manifest commit rolls hooks.json back byte-identically');
+
+  const linkedOwnerHome = path.join(root, 'linked-owner-codex');
+  const linkedOwnerOutside = path.join(root, 'linked-owner-outside');
+  fs.mkdirSync(path.join(linkedOwnerHome, 'harness-everything'), { recursive: true });
+  fs.mkdirSync(linkedOwnerOutside, { recursive: true });
+  fs.symlinkSync(
+    linkedOwnerOutside,
+    path.join(linkedOwnerHome, 'harness-everything', 'compat-hooks'),
+    process.platform === 'win32' ? 'junction' : 'dir'
+  );
+  let linkedOwnerRefused = false;
+  try { compat.install({ codexHome: linkedOwnerHome }); }
+  catch (error) { linkedOwnerRefused = /linked|outside/.test(error.message); }
+  check(linkedOwnerRefused && fs.readdirSync(linkedOwnerOutside).length === 0,
+    'linked compatibility owner path cannot redirect writes outside Codex home');
+
+  const malformedHome = path.join(root, 'malformed-codex');
+  fs.mkdirSync(malformedHome, { recursive: true });
+  const malformed = path.join(malformedHome, 'hooks.json');
+  fs.writeFileSync(malformed, '{ this is not json', 'utf8');
+  const malformedBefore = fs.readFileSync(malformed, 'utf8');
+  let malformedRefused = false;
+  try { compat.install({ codexHome: malformedHome }); } catch (_) { malformedRefused = true; }
+  check(malformedRefused && fs.readFileSync(malformed, 'utf8') === malformedBefore,
+    'malformed user hooks.json fails closed without replacement');
+
+  const source = read(path.join(compat.SOURCE_PLUGIN_ROOT, 'hooks', 'hooks.json'));
+  const sourceCount = Object.values(source.hooks).reduce((sum, entries) => sum + entries.length, 0);
+  check(sourceCount === installed.entries,
+    'fallback derives from the current packaged hook manifest instead of maintaining a second manual hook inventory');
+} finally {
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+console.log('\n' + (failed === 0 ? 'PASS' : 'FAIL') +
+  ': #122 Codex compatibility fallback (' + failed + ' failure' + (failed === 1 ? '' : 's') + ')');
+process.exit(failed === 0 ? 0 : 1);