@fusengine/harness 0.1.67 → 0.1.69

package/README.md

@@ -125,7 +125,7 @@ also works elsewhere.
 | Harness | PreToolUse coverage | Lifecycle (Session/Subagent/Stop/Compact/…) | Known limit |
 |---|---|---|---|
 | **claude-code** | Full: `evaluate` + APEX gates via `handleHook` (`src/adapters/claude/index.ts`) | 14 event types implemented (`dispatch.ts`) — fires once wired into `.claude/settings.json` beyond the `init` default | None found; richer lifecycle needs manual/marketplace wiring (see Quickstart) |
-| **codex** | Bash gated reliably; **`apply_patch` edits are now gated too** — the patch text is parsed per file (`adapters/codex/apply-patch.ts`), each hunk runs the file gates and ONE violating hunk denies the whole patch (`runtime/apply-patch-gate.ts`, sim scenario 22 incl. the multi-file smuggling case). `ask` prompts are **downgraded to explicit deny** (`respond.ts`, sim scenario 23) because Codex fails open on unsupported shapes. | Not wired by `harness init codex` (PreToolUse `Bash\|apply_patch` + PostToolUse only, `src/init/templates.ts:29-38`) | Upstream caveat: Codex itself does not always enforce a correct `apply_patch` deny (openai/codex#27833) — we emit the right verdict; enforcement is theirs. No interactive `ask`. |
+| **codex** | Bash gated reliably; **`apply_patch` edits are now gated too** — the patch text is parsed per file (`adapters/codex/apply-patch.ts`), each hunk runs the file gates and ONE violating hunk denies the whole patch (`runtime/apply-patch-gate.ts`, sim scenario 22 incl. the multi-file smuggling case). `ask` prompts are **downgraded to explicit deny** (`respond.ts`, sim scenario 23) because Codex fails open on unsupported shapes. On the PostToolUse side, an allowed patch is fanned into one synthetic per-file event so the SOLID/tracking/post-edit handlers see every touched file (`runtime/post-fanout.ts`), and a non-blocking security advisory fires on the first qualifying file (`securityAdvisoryForPatch`). | Not wired by `harness init codex` (PreToolUse `Bash\|apply_patch` + PostToolUse only, `src/init/templates.ts:29-38`) — `Stop` (session cleanup + the SOLID/receipt completion check, since Codex never emits `SessionEnd`/`TaskCompleted`, `runtime/lifecycle/stop-core.ts`) and `SessionStart` (plugin agents/commands cache resync, `runtime/lifecycle/codex-resync/`) ARE implemented but, same caveat as claude-code's extra lifecycle above, only fire once the codex-plugins marketplace's own `hooks.json` wires them. | Upstream caveat: Codex itself does not always enforce a correct `apply_patch` deny (openai/codex#27833) — we emit the right verdict; enforcement is theirs. No interactive `ask`. Codex has no native `PostToolUseFailure`; a failure is inferred from the ordinary `PostToolUse` result shape (non-zero exit or an explicit error field only — never a guess) and journaled into the one-shot failure tally (`src/tracking/codex-post-failure.ts`). |
 | **cursor** | `beforeShellExecution` can deny/ask (shell only, `cursor/index.ts:16-21`) | none | File edits are **advisory only**: `afterFileEdit` always returns `allow` + a `user_message` correction on violation — a `deny` there has no proven effect (hook was "informational only" at launch, and Cursor's deny-enforcement for file ops is confirmed broken upstream, forum.cursor.com/t/154377). Human sees the message; the model is never re-informed. Platform ceiling, documented in `cursor/index.ts`. |
 | **gemini-cli** | `BeforeTool` denies via `{decision:"deny",reason}` (`gemini/index.ts:22-36`) | none | Thin stateless adapter — no session track, no APEX gates wired through it. |
 | **cline** | `PreToolUse` only; block → `{cancel:true}`, non-block → `contextModification` (`cline/index.ts:24-36`) | none | Same as gemini-cli: stateless guard only. |
@@ -198,6 +198,72 @@ Features shipped since 0.1.44, each with its own test:
 - **Hook simulator** — 18 end-to-end scenarios (payload in, expected verdict out)
   replayed against the real CLI in both `src` and built `dist` modes in CI
   (`test/sim/README.md`, `test/sim/scenarios/`).
+- **Codex `multi_agent_v2` custom-agent evidence** — a `spawn_agent` call
+  carrying `tool_input.agent_type` is recorded as `subagent-<agent_type>` in the
+  same SessionTrack as Claude Task evidence, so a Codex explore-codebase/sniper
+  satisfies the APEX freshness gates exactly like a Claude subagent
+  (`src/tracking/session-state.ts`, sim scenario 32b).
+- **File-size gate judges the real Edit outcome, not the on-disk count** — an
+  Edit on a file already over `FUSE_SOLID_MAX_LINES` used to be denied
+  unconditionally (the on-disk count always won); the gate now computes the
+  actual post-edit line count and allows a shrinking Edit while still denying a
+  computable growth past the limit (`src/policy/file-size.ts`, sim scenario 33).
+- **Codex `apply_patch` fan-out to post-handlers** — each file in a patch
+  envelope becomes a synthetic per-file PostToolUse event (`add`→`Write`,
+  `update`→`Edit`, `delete` no-ops on the Write/Edit-only handlers) instead of
+  the whole-patch shape whose own `filePath`/`content` are always undefined
+  (`src/runtime/post-fanout.ts`, `test/apply-patch-post.test.ts`).
+- **Non-blocking multi-file security advisory** — the same PreToolUse "read the
+  security skill" nudge a single Write/Edit gets is now evaluated per file
+  across a Codex `apply_patch` envelope, firing on the first qualifying
+  add/update code file (delete ignored outright) — `additionalContext` only,
+  never a deny (`src/runtime/lifecycle/security/check-skill.ts::securityAdvisoryForPatch`,
+  `test/security-advisory-patch.test.ts`).
+- **Codex SessionStart agent/command resync** — the plugin agents/commands
+  cache under `~/.codex/{agents,prompts}` is re-materialized only when its
+  sha256 fingerprint changed (or a command symlink dangles) since the last
+  apply, otherwise a cheap no-op; agents are copied (Codex won't load
+  symlinked TOMLs), commands are symlinked; a best-effort inter-process lock
+  avoids a torn cache under concurrent session starts (`src/runtime/lifecycle/codex-resync/`,
+  `test/resync-agents.test.ts`).
+- **Codex failure tracking inferred from PostToolUse** — Codex reports every
+  outcome, success or failure, on the same `PostToolUse` event; a failure is
+  classified from an explicit signal only (non-zero exit, an error field —
+  never "can't tell") and journaled into the existing one-shot failure tally
+  (`src/tracking/codex-post-failure.ts`, `test/codex-post-failure.test.ts`).
+- **Shell-credited ref reads** — a `.md` SOLID/skill reference read through a
+  read-only shell command (`cat`/`head`/`tail`/`sed`/`rg`/`less`/`more`/`bat`,
+  including inside a `sh -c` wrapper) now credits the same ref-read evidence a
+  native `Read` would, so a Codex teammate's shell-first consultation still
+  satisfies `solidReadGate`; `sed -i`/`--in-place` and any non-whitelisted
+  command are never credited (`src/policy/shell-read-refs.ts`,
+  `test/shell-read-refs.test.ts`).
+
+### Notification sounds
+
+A native OS sound plays on two lifecycle events: the core-scope `Stop` under
+Codex (`stopCore`, since Claude Code already voices its own turn-end via a
+native `afplay` hook — this harness deliberately does not double it) and
+`TeammateIdle` under Claude Code when there's an actionable notice (a missing
+deliverable or a sniper reminder). **On by default**; opt out entirely with
+`FUSE_HARNESS_SOUND=0`.
+
+Resolution per event kind (`stop`/`permission`/`human`) cascades: (1) a
+per-kind env override path (`FUSE_HARNESS_SOUND_STOP` / `_PERMISSION` /
+`_HUMAN`) if it exists on disk; (2) the package's own bundled
+`assets/song/{finish,permission-need,need-human}.mp3` (located by walking up
+to the running `package.json`, so it survives the flat/hashed `dist/` build);
+(3) `$CLAUDE_PLUGIN_ROOT/song/<file>.mp3` as a last-resort fallback. No file
+resolves → silent no-op. The `permission` kind and its `.mp3`/env var exist in
+the module for symmetry but have no current call site — permission prompts
+stay native-only on every harness today.
+
+Playback is native per platform (`afplay` on darwin, `paplay` on linux,
+PowerShell's `SoundPlayer` on win32) and **absolutely fail-open**: an
+unsupported platform, a missing player binary, an undecodable file, or a
+non-zero exit is swallowed — a broken or absent player can never break a hook
+(`src/runtime/notifications.ts`, `src/runtime/notification-sound.ts`,
+`test/notifications.test.ts`).
 
 ### Environment
 
@@ -214,6 +280,8 @@ Features shipped since 0.1.44, each with its own test:
 | `FUSE_WEBFETCH_TTL_SEC` | WebFetch cache freshness, seconds (default 24h — pages stale faster than docs). |
 | `RALPH_MODE` | **Opt-in (default off).** Exempts safe git commands (`add`/`commit`/`checkout -b`/`status`/`diff`/`log`) from the confirmation ask and auto-approves project installs. Destructive git (force-push, `reset --hard`) and system installs still gate. |
 | `CLAUDE_PROJECT_DIR` | Overrides the project root used to hash the out-of-tree state dir (`src/runtime/paths.ts:20`). |
+| `FUSE_HARNESS_SOUND` | **On by default.** Set to `0` to disable every lifecycle notification sound. |
+| `FUSE_HARNESS_SOUND_STOP` / `_PERMISSION` / `_HUMAN` | Per-kind override: an absolute path to a sound file to play instead of the bundled `assets/song/*.mp3` for that kind (see [Notification sounds](#notification-sounds)). |
 
 ## Library usage
 
@@ -286,9 +354,10 @@ Run `bun run docs:api` for the generated typedoc API reference.
 
 ## Known limitations
 
-- **Codex file edits are not gated.** The SOLID/file-size gate keys off
-  `tool_input.file_path`, which Codex's `apply_patch` call never supplies — only
-  Bash is reliably gated on Codex today (see [Compatibility](#compatibility)).
+- **Codex `apply_patch` enforcement depends on Codex itself.** The harness
+  parses the patch and emits the right verdict per file, but Codex does not
+  always enforce a correct deny on its end (openai/codex#27833, see
+  [Compatibility](#compatibility)) — enforcement beyond the verdict is theirs.
 - **Cursor file edits are advisory-only.** `afterFileEdit` fires after the edit
   already happened — a platform limit, not something this harness can work around.
 - **Hook fan-out is mitigated, not eliminated.** The ~11-sibling-plugin burst is
@@ -306,7 +375,7 @@ Run `bun run docs:api` for the generated typedoc API reference.
 ## Develop
 
 ```sh
-bun test            # 484 tests (94 files)
+bun test            # 662 tests (120 files)
 bunx tsc --noEmit   # typecheck (isolatedDeclarations)
 bun run build       # dist + .d.mts via tsdown (for Node/bundler consumers)
 bun run docs:api    # generate the typedoc API reference

package/dist/adapters/claude/index.mjs

@@ -1,2 +1,2 @@
-import { a as fileSizeGuard, c as readClaudeInput, i as denyResponse, l as systemMessage, n as blockResponse, o as guard, r as contextResponse, s as informResponse, t as attachSystemMessage, u as toClaudeResponse } from "../../claude-Cu6rPxUZ.mjs";
+import { a as fileSizeGuard, c as readClaudeInput, i as denyResponse, l as systemMessage, n as blockResponse, o as guard, r as contextResponse, s as informResponse, t as attachSystemMessage, u as toClaudeResponse } from "../../claude-CHpb1U0A.mjs";
 export { attachSystemMessage, blockResponse, contextResponse, denyResponse, fileSizeGuard, guard, informResponse, readClaudeInput, systemMessage, toClaudeResponse };

package/dist/adapters/cline/index.mjs

@@ -1,4 +1,4 @@
-import { t as evaluate } from "../../evaluate-CxgYAODk.mjs";
+import { t as evaluate } from "../../evaluate-Dx6q1kmQ.mjs";
 import { t as formatPrompt } from "../../types-ernB1Dy3.mjs";
 //#region src/adapters/cline/index.ts
 /**

package/dist/adapters/codex/index.mjs

@@ -1,8 +1,8 @@
 import { f as countLines } from "../../home-state-D0RLWP8J.mjs";
-import { t as evaluate } from "../../evaluate-CxgYAODk.mjs";
+import { t as evaluate } from "../../evaluate-Dx6q1kmQ.mjs";
 import { t as formatPrompt } from "../../types-ernB1Dy3.mjs";
 import { n as parseApplyPatch, t as isBypassPermissions } from "../../permission-mode-BN3MNgbm.mjs";
-import { c as readClaudeInput, i as denyResponse, r as contextResponse, s as informResponse, v as commandToString } from "../../claude-Cu6rPxUZ.mjs";
+import { c as readClaudeInput, i as denyResponse, r as contextResponse, s as informResponse, v as commandToString } from "../../claude-CHpb1U0A.mjs";
 //#region src/adapters/codex/index.ts
 /**
 * OpenAI Codex CLI adapter (hook-mode). Codex's `PreToolUse` hook (since 2026)

package/dist/adapters/cursor/index.mjs

@@ -1,4 +1,4 @@
-import { t as evaluate } from "../../evaluate-CxgYAODk.mjs";
+import { t as evaluate } from "../../evaluate-Dx6q1kmQ.mjs";
 import { t as formatPrompt } from "../../types-ernB1Dy3.mjs";
 //#region src/adapters/cursor/index.ts
 /**

package/dist/adapters/gemini/index.mjs

@@ -1,4 +1,4 @@
-import { t as evaluate } from "../../evaluate-CxgYAODk.mjs";
+import { t as evaluate } from "../../evaluate-Dx6q1kmQ.mjs";
 import { t as formatPrompt } from "../../types-ernB1Dy3.mjs";
 //#region src/adapters/gemini/index.ts
 /**

package/dist/adapters/hermes/index.mjs

@@ -1,2 +1,2 @@
-import { n as readHermesInput, r as toHermesResponse, t as guard } from "../../hermes-BpD0nlyR.mjs";
+import { n as readHermesInput, r as toHermesResponse, t as guard } from "../../hermes-CddsFoPN.mjs";
 export { guard, readHermesInput, toHermesResponse };

package/dist/{claude-Cu6rPxUZ.mjs → claude-CHpb1U0A.mjs}

@@ -1,4 +1,4 @@
-import { t as evaluate } from "./evaluate-CxgYAODk.mjs";
+import { t as evaluate } from "./evaluate-Dx6q1kmQ.mjs";
 import { t as formatPrompt } from "./types-ernB1Dy3.mjs";
 import { dirname, join } from "node:path";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";

package/dist/cli/bin.mjs

@@ -2,10 +2,10 @@
 import { r as loadDotenv, s as resolveTtlSec } from "../dotenv-Jj8aL1FL.mjs";
 import { t as detectHarness } from "../harness-Cb9xR8dC.mjs";
 import { t as claudeHome } from "../home-state-D0RLWP8J.mjs";
-import { n as stagedContent, r as stagedFiles, t as checkStaged } from "../run-BfJytXnW.mjs";
+import { n as stagedContent, r as stagedFiles, t as checkStaged } from "../run-B9Br7SEr.mjs";
 import { n as writeInitFile, t as initFor } from "../run-Do2JltgU.mjs";
-import { J as runningVersion, Lt as todayUtc, Y as versionBanner, q as runDoctor, t as handleHook } from "../handle-CU5UdAei.mjs";
-import { p as readStdin$1 } from "../claude-Cu6rPxUZ.mjs";
+import { $ as versionBanner, Q as runningVersion, Rt as todayUtc, Z as runDoctor, t as handleHook } from "../handle-CVk0NlTg.mjs";
+import { p as readStdin$1 } from "../claude-CHpb1U0A.mjs";
 import { delimiter, join } from "node:path";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";

package/dist/cli/index.mjs

@@ -1,2 +1,2 @@
-import { n as stagedContent, r as stagedFiles, t as checkStaged } from "../run-BfJytXnW.mjs";
+import { n as stagedContent, r as stagedFiles, t as checkStaged } from "../run-B9Br7SEr.mjs";
 export { checkStaged, stagedContent, stagedFiles };

package/dist/{evaluate-CxgYAODk.mjs → evaluate-Dx6q1kmQ.mjs}

@@ -1,3 +1,4 @@
+import { r as resolveMaxLines } from "./limits-CHn8AIL1.mjs";
 import { f as countLines, p as evaluateFileSize, r as fusengineCache, t as claudeHome } from "./home-state-D0RLWP8J.mjs";
 import { dirname, join, normalize } from "node:path";
 import { existsSync } from "node:fs";
@@ -146,6 +147,53 @@ function resolveSolidRefFramework(filePath) {
 	return "generic";
 }
 //#endregion
+//#region src/policy/edit-outcome.ts
+/**
+* Count non-overlapping literal occurrences of `needle` in `haystack`. An
+* empty `needle` returns 0 — treated as "not found" by callers, since Edit's
+* `old_string` is never legitimately empty and an empty needle has no
+* well-defined occurrence count.
+* @param haystack - The on-disk file content to search.
+* @param needle - The literal substring to count.
+*/
+function countOccurrences(haystack, needle) {
+	if (needle === "") return 0;
+	let count = 0;
+	let from = 0;
+	for (;;) {
+		const at = haystack.indexOf(needle, from);
+		if (at === -1) break;
+		count++;
+		from = at + needle.length;
+	}
+	return count;
+}
+/**
+* Compute the line count an Edit would PRODUCE, before it lands on disk —
+* `existingLines − countLines(old_string) + countLines(new_string)`, scaled
+* by how many `old_string` occurrences are actually replaced (1 normally, or
+* every occurrence under `replace_all`). Pure arithmetic on the literal
+* strings — no regex/fuzzy matching, matching the real Edit tool's own
+* exact-substring semantics.
+*
+* Returns `null` (fail-closed — caller must fall back to judging the stale
+* on-disk count alone) when `old_string` is missing/empty, or does not occur
+* in `existingContent` at all: an Edit whose `old_string` doesn't match the
+* real file is stale or adversarial, never a case to special-case an allow for.
+* @param existingContent - Full on-disk content of the file being edited.
+* @param oldString - The Edit's `old_string` (tool_input, unmodified).
+* @param newString - The Edit's `new_string` (tool_input, unmodified).
+* @param replaceAll - The Edit's `replace_all` flag.
+*/
+function computeEditResultLines(existingContent, oldString, newString, replaceAll) {
+	if (!oldString) return null;
+	const occurrences = countOccurrences(existingContent, oldString);
+	if (occurrences === 0) return null;
+	const times = replaceAll ? occurrences : 1;
+	const delta = countLines(newString) - countLines(oldString);
+	return countLines(existingContent) + delta * times;
+}
+//#endregion
 //#region src/policy/guards/security.ts
 /** Critical patterns that must always be blocked — parity `security_rules.py`'s cumulated violation names. */
 const CRITICAL_PATTERNS = [
@@ -822,6 +870,43 @@ function buildNeverApprovalPrompt(cmd) {
 	};
 }
 //#endregion
+//#region src/policy/git-gates.ts
+/**
+* Evaluate the two git confirmation gates — destructive block ({@link
+* GIT_BLOCKED}) and confirmation ask ({@link GIT_ASK}) — against `command`.
+* Skipped entirely when `ralphSafe` is true: Ralph mode already silent-
+* allowed the command upstream (parity with evaluate.ts's pre-existing
+* `!ralphSafe &&` guards). Returns the matching gate's {@link PolicyResult},
+* or `null` when neither gate matches.
+*/
+function evaluateGitGates(command, ralphSafe) {
+	if (ralphSafe || !command) return null;
+	if (matchPatterns(command, GIT_BLOCKED)) {
+		const reason = `Destructive git command: ${command}`;
+		return {
+			decision: "deny",
+			message: reason,
+			prompt: {
+				kind: "block",
+				title: "Destructive git command",
+				reason,
+				actions: ["Use a non-destructive alternative (e.g. --force-with-lease; avoid --hard / -D)"]
+			}
+		};
+	}
+	if (matchPatterns(command, GIT_ASK)) return {
+		decision: "deny",
+		message: `Git operation requires confirmation: ${command}`,
+		prompt: {
+			kind: "ask",
+			title: "Confirm git operation",
+			reason: `Authorize: ${command.trim()}`,
+			actions: ["Approve if this git operation is intended"]
+		}
+	};
+	return null;
+}
+//#endregion
 //#region src/policy/evaluate.ts
 /**
 * Evaluate a single tool-use against the bundled policies, returning a pure
@@ -845,35 +930,21 @@ function evaluate(ctx) {
 			prompt
 		};
 	}
-	if (!ralphSafe && ctx.command && matchPatterns(ctx.command, GIT_BLOCKED)) {
-		const reason = `Destructive git command: ${ctx.command}`;
-		return {
-			decision: "deny",
-			message: reason,
-			prompt: {
-				kind: "block",
-				title: "Destructive git command",
-				reason,
-				actions: ["Use a non-destructive alternative (e.g. --force-with-lease; avoid --hard / -D)"]
-			}
-		};
-	}
-	if (!ralphSafe && ctx.command && matchPatterns(ctx.command, GIT_ASK)) return {
-		decision: "deny",
-		message: `Git operation requires confirmation: ${ctx.command}`,
-		prompt: {
-			kind: "ask",
-			title: "Confirm git operation",
-			reason: `Authorize: ${ctx.command.trim()}`,
-			actions: ["Approve if this git operation is intended"]
-		}
-	};
+	const gitGate = evaluateGitGates(ctx.command, ralphSafe);
+	if (gitGate) return gitGate;
 	if (ctx.filePath && isFileSizeScoped(ctx.filePath) && ctx.agentType !== "Explore" && ctx.agentType !== "Plan") {
 		const incoming = ctx.content !== void 0 ? countLines(ctx.content) : 0;
-		const lines = ctx.tool === "Edit" ? Math.max(incoming, ctx.existingLines ?? 0) : incoming || (ctx.existingLines ?? 0);
+		const existing = ctx.existingLines ?? 0;
+		const max = ctx.maxLines ?? resolveMaxLines();
+		const editResult = ctx.tool === "Edit" && ctx.existingContent !== void 0 && ctx.content !== void 0 ? computeEditResultLines(ctx.existingContent, ctx.oldString, ctx.content, ctx.isReplaceAll === true) : null;
+		if (editResult !== null && (editResult <= max || editResult < existing)) return {
+			decision: "allow",
+			message: null
+		};
+		const lines = ctx.tool === "Edit" ? editResult ?? Math.max(incoming, existing) : incoming || existing;
 		const framework = resolveSolidRefFramework(ctx.filePath);
 		const displayLines = ctx.tool === "Write" ? ctx.existingLines ?? lines : lines;
-		const verdict = evaluateFileSize(lines, ctx.maxLines, ctx.filePath, framework, displayLines);
+		const verdict = evaluateFileSize(lines, max, ctx.filePath, framework, displayLines);
 		if (lines > 0 && !verdict.ok) return {
 			decision: "deny",
 			message: verdict.message,