harnery 0.5.0 → 0.7.0

package/src/core/agents/coord-client.ts

@@ -153,6 +153,17 @@ export function resolveOwnerWithSource(): {
 
   const root = monorepoRoot();
   if (!root) return { owner: null, source: "none" };
+
+  // Cursor's Glass/Agents UI can run several chats under one long-lived node
+  // process, so the pid-map row for that shared ancestor is last-writer-wins.
+  // Prefer the per-chat session id when Cursor exposes one in the tool env.
+  if (shouldPreferSessionEnv()) {
+    const bySession = resolveOwnerBySessionEnv(root);
+    if (bySession) {
+      return { owner: bySession, source: "session_env" };
+    }
+  }
+
   const pidmapDir = resolve(root, ".harnery", "pid-map");
   if (!existsSync(pidmapDir)) return { owner: null, source: "none" };
 
@@ -216,16 +227,32 @@ const SESSION_ID_ENV_VARS = [
   "HARNERY_AGENT_COORD_SESSION_ID", // explicit override, wins if set
   "CLAUDE_CODE_SESSION_ID",
   "CURSOR_SESSION_ID",
+  "CURSOR_CONVERSATION_ID",
   "CODEX_SESSION_ID",
 ] as const;
 
-/** Read the first non-empty harness session-id env var, or null. */
-function sessionIdFromEnv(): string | null {
+/** Read normalized candidates from the first non-empty harness session-id env var. */
+function sessionIdsFromEnv(): string[] {
   for (const key of SESSION_ID_ENV_VARS) {
     const v = process.env[key]?.trim();
-    if (v) return v;
+    if (!v) continue;
+    if (key === "CURSOR_CONVERSATION_ID" && v.startsWith("bc-") && v.length > 3) {
+      return [v.slice(3), v];
+    }
+    return [v];
   }
-  return null;
+  return [];
+}
+
+/** Read the first non-empty harness session-id env var, or null. */
+function sessionIdFromEnv(): string | null {
+  return sessionIdsFromEnv()[0] ?? null;
+}
+
+function shouldPreferSessionEnv(): boolean {
+  if (!sessionIdFromEnv()) return false;
+  const platform = process.env.HARNERY_AGENT_COORD_PLATFORM?.trim();
+  return process.env.CURSOR_AGENT === "1" || platform === "cursor";
 }
 
 /**
@@ -239,8 +266,8 @@ function sessionIdFromEnv(): string | null {
  * Exported for unit testing with an injectable root.
  */
 export function resolveOwnerBySessionEnv(root: string): string | null {
-  const sessionId = sessionIdFromEnv();
-  if (!sessionId) return null;
+  const sessionIds = sessionIdsFromEnv();
+  if (sessionIds.length === 0) return null;
 
   const activeDir = resolve(root, ".harnery", "active");
   if (!existsSync(activeDir)) return null;
@@ -256,7 +283,7 @@ export function resolveOwnerBySessionEnv(root: string): string | null {
     if (!file.endsWith(".json")) continue;
     try {
       const parsed = JSON.parse(readFileSync(resolve(activeDir, file), "utf8"));
-      if (!parsed || parsed.session_id !== sessionId) continue;
+      if (!parsed || !sessionIds.includes(parsed.session_id)) continue;
       if (typeof parsed.instance_id !== "string") continue;
       const ts = Date.parse(parsed.last_heartbeat);
       if (Number.isFinite(ts) && ts >= cutoffMs) return parsed.instance_id;

package/src/core/agents/events/consume.ts

@@ -11,8 +11,12 @@
  * with a bounded **tail read** (reading only the last `tailBytes` of the file
  * and locating the cursor there) which turns an O(file-size) read into
  * O(window). If the cursor is older than the window (a long-idle system, or a
- * cursor that's been rotated out) we fall back to a full read. The fallback is
- * always correct, just slower, so undersizing the window can never lose events.
+ * cursor that's been rotated out) we fall back to a wider read that is itself
+ * capped (`fallbackCapBytes`): the stream is an append-only ledger that grows
+ * without bound, so a whole-file `readFileSync` throws V8's max-string-length
+ * error ("Cannot create a string longer than 0x1fffffe8 characters") once it
+ * passes ~512MB, which would abort the projection. Events older than the cap are
+ * stale for coord-state purposes, so a bounded replay is the correct fallback.
  *
  * Idempotency: projectors are idempotent by `event_id`. The
  * cursor file makes this cheap (we never replay an already-projected event by
@@ -36,6 +40,11 @@ import { coordEnv } from "../../../lib/env.ts";
 const STREAM_REL = ".harnery/events.ndjson";
 const CURSOR_REL = ".harnery/.events-cursor";
 const DEFAULT_TAIL_BYTES = 2 * 1024 * 1024; // 2 MiB, thousands of events of headroom
+/** Cap for the fall-through read when the cursor misses the tail window. Well
+ * under V8's ~512MB max string length so it never throws on the unbounded
+ * ledger; comfortably larger than any realistic cursor drift (the global cursor
+ * advances on every agent's turn.stop, so it sits near EOF in practice). */
+const DEFAULT_FALLBACK_CAP_BYTES = 64 * 1024 * 1024; // 64 MiB
 
 export interface CanonicalEvent {
   schema_version: number;
@@ -69,6 +78,13 @@ export interface ConsumeOpts {
    * callers should leave it unset.
    */
   tailBytes?: number;
+  /**
+   * Cap in bytes for the fall-through read (cursor missed the tail window).
+   * Defaults to `HARNERY_AGENT_COORD_FALLBACK_CAP_BYTES` env or 64 MiB. Bounds
+   * the read so the unbounded ledger can never overflow V8's max string length.
+   * Mainly a test seam; production callers should leave it unset.
+   */
+  fallbackCapBytes?: number;
 }
 
 /**
@@ -103,8 +119,19 @@ export function consumeSince(coordRoot: string, opts: ConsumeOpts = {}): Consume
     // Cursor older than the tail window → fall through to a full read.
   }
 
-  // Full read: first run, replayAll, small file, or cursor not found in tail.
-  const all = parseLines(readFileSync(streamPath, "utf8"));
+  // Bounded fall-through: first run, replayAll, small file, or cursor not found
+  // in the tail. This must NEVER read the whole file: the stream grows without
+  // bound and a >512MB readFileSync throws V8's max-string-length error, which
+  // would abort the projection. Read at most `cap` bytes from the tail; when we
+  // start mid-file, drop the (likely partial) first line.
+  const cap = resolveFallbackCap(opts.fallbackCapBytes);
+  const readBytes = Math.min(fileSize, cap);
+  let text = readTailUtf8(streamPath, fileSize, readBytes);
+  if (readBytes < fileSize) {
+    const firstNl = text.indexOf("\n");
+    text = firstNl >= 0 ? text.slice(firstNl + 1) : "";
+  }
+  const all = parseLines(text);
   const parsed = eventsAfterCursor(all, cursor);
   if (parsed.foundCursor) {
     return {
@@ -114,12 +141,19 @@ export function consumeSince(coordRoot: string, opts: ConsumeOpts = {}): Consume
     };
   }
 
-  // The cursor names an event that's been rotated out of the file, so replay
-  // everything (safer than silent state drift; the projector is idempotent by
-  // event_id).
+  // The cursor names an event older than the capped window (or rotated out), so
+  // replay what the window holds (safer than silent state drift; the projector
+  // is idempotent by event_id). lastEventId null keeps the cursor put.
   return { events: all, lastEventId: null, streamBytes: fileSize };
 }
 
+function resolveFallbackCap(override?: number): number {
+  if (override !== undefined && override > 0) return override;
+  const env = coordEnv("AGENT_COORD_FALLBACK_CAP_BYTES");
+  const n = env ? Number(env) : Number.NaN;
+  return Number.isFinite(n) && n > 0 ? n : DEFAULT_FALLBACK_CAP_BYTES;
+}
+
 function resolveTailBytes(override?: number): number {
   if (override !== undefined && override > 0) return override;
   const env = coordEnv("AGENT_COORD_TAIL_BYTES");
@@ -127,6 +161,30 @@ function resolveTailBytes(override?: number): number {
   return Number.isFinite(n) && n > 0 ? n : DEFAULT_TAIL_BYTES;
 }
 
+/**
+ * Read at most `capBytes` from the tail of the event stream as UTF-8, dropping
+ * the (partial) leading line when the file is larger than the cap. Shared
+ * bounded reader for CLI consumers (`agents trace` / `agents health`) that must
+ * never `readFileSync` the whole unbounded ledger — a >512MB read throws V8's
+ * max-string-length error. `truncated` is true when older bytes were skipped, so
+ * callers can surface the cap rather than silently under-reporting.
+ */
+export function readStreamTailBounded(
+  streamPath: string,
+  capBytes: number,
+): { text: string; truncated: boolean } {
+  if (!existsSync(streamPath)) return { text: "", truncated: false };
+  const fileSize = statSync(streamPath).size;
+  const readBytes = Math.min(fileSize, capBytes);
+  let text = readTailUtf8(streamPath, fileSize, readBytes);
+  const truncated = readBytes < fileSize;
+  if (truncated) {
+    const nl = text.indexOf("\n");
+    text = nl >= 0 ? text.slice(nl + 1) : "";
+  }
+  return { text, truncated };
+}
+
 /** Read the trailing `windowBytes` of a file as UTF-8 without loading the rest. */
 function readTailUtf8(streamPath: string, fileSize: number, windowBytes: number): string {
   const start = Math.max(0, fileSize - windowBytes);

package/src/core/agents/events/emit.ts

@@ -5,11 +5,13 @@
  * event/schema types).
  *
  * Phase 4: agent-coord uses this from CLI handlers (state.task_set,
- * state.status_checked, state.scratch_append, council.*, presence.*).
+ * state.status_checked, state.scratch_append, council.*, decision.*,
+ * presence.*).
  */
 
 import { appendFileSync, closeSync, mkdirSync, openSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { maybeRotateEventStream } from "../../hooks/events/rotate.ts";
 import { ulid } from "./ulid.ts";
 
 const SCHEMA_VERSION = 1 as const;
@@ -70,6 +72,10 @@ export function emit(coordRoot: string, input: EmitInput): Envelope {
   const streamPath = join(coordRoot, STREAM_FILE);
   const lockPath = join(coordRoot, LOCK_FILE);
 
+  // Size-triggered rotation (shared with the agent-hooks emitter): roll the
+  // active file to a dated archive when it crosses the cap. Fail-soft.
+  maybeRotateEventStream(coordRoot);
+
   ensureDir(dirname(streamPath));
   ensureFile(lockPath);
 

package/src/core/agents/rules/claim-conflict.ts

@@ -95,11 +95,22 @@ export function evaluateClaim(coordRoot: string, req: ClaimRequest): VerdictResu
 
   // Ordering check: if we hold any claim with path < req.path, fine.
   // Otherwise the new claim would create a backward-edge in the dependency
-  // graph and risk deadlock. Only applies when there are OTHER fresh peers:
-  // single-agent flow can't deadlock with itself, and the rule otherwise
-  // forces release-and-reacquire cycles on every reverse-order edit pair.
-  const hasFreshPeers = otherPeers.some(
-    (p) => isFresh(p.last_heartbeat) && p.files_touched.length > 0,
+  // graph and risk deadlock. Only applies when a fresh peer genuinely CONTENDS
+  // with us — i.e. holds a path that also sits in our own footprint (held
+  // claims ∪ the path we're now requesting). A wait-for cycle is a
+  // strongly-connected set of agents linked by shared files; if no fresh peer
+  // shares any file with our footprint, we're in a disjoint component of the
+  // resource graph and cannot be part of any cycle, so sorted-order acquisition
+  // buys nothing and the block is pure false-positive friction. Sharing a file
+  // is the necessary condition for a cycle through this agent, so this narrowing
+  // leaves the deadlock-prevention invariant intact for genuine contention while
+  // removing the dominant real-world cost — a peer editing unrelated files
+  // walling off every backward-order edit. (Single-agent flow can't deadlock
+  // with itself and never arms, since there are no other peers to contend.)
+  const myFootprint = new Set<string>(myPeer?.files_touched ?? []);
+  myFootprint.add(req.path);
+  const hasContendingPeer = otherPeers.some(
+    (p) => isFresh(p.last_heartbeat) && p.files_touched.some((f) => myFootprint.has(f)),
   );
   // Re-editing a path already in our own files_touched acquires no new lock
   // edge, so it can't create a circular wait — the ordering rule must not block
@@ -109,7 +120,7 @@ export function evaluateClaim(coordRoot: string, req: ClaimRequest): VerdictResu
   // both agent-Gibson holding README.md and agent-Ophelia holding AGENTS.md were
   // blocked re-editing those held files after touching a higher path, 2026-07-03).
   const alreadyHeld = myPeer?.files_touched.includes(req.path) ?? false;
-  if (hasFreshPeers && myPeer && myPeer.files_touched.length > 0 && !alreadyHeld) {
+  if (hasContendingPeer && myPeer && myPeer.files_touched.length > 0 && !alreadyHeld) {
     // Only ACTIVE (uncommitted) edits should constrain lock ordering. A claim on
     // a committed-clean file is a finished edit, not a held lock, so it must not
     // wall off a lower-sorted acquisition. Without this, a long session

package/src/core/agents/state/scratch.ts

@@ -81,7 +81,7 @@ export function appendScratch(
 
 /**
  * Replace the scratchpad with new body, archiving prior contents and
- * appending an "(edited via UI by Ryan)" audit-marker note.
+ * appending an "(edited via UI by the operator)" audit-marker note.
  */
 export function editScratchpad(
   coordRoot: string,
@@ -112,7 +112,7 @@ export function editScratchpad(
 
   const summaryText = summary && summary.length > 0 ? summary : "(no summary)";
   const auditMarker =
-    `## [${ts}] note (edited via UI by Ryan)\n` +
+    `## [${ts}] note (edited via UI by the operator)\n` +
     `${summaryText}\n` +
     `Pre-edit archived at .harnery/scratch/archived/${instanceId}-${archiveSuffix}.md\n\n`;
 

package/src/core/config.ts

@@ -23,7 +23,7 @@ import { findCoordRoot } from "./hooks/resolve/coord-root.ts";
 export const DEFAULT_BIN_NAME = "harn";
 
 interface HarneryConfig {
-  /** Host CLI bin name, stamped by `harn init` for a consumer (e.g. "bp"). */
+  /** Host CLI bin name, stamped by `harn init` for a consumer (e.g. "acme"). */
   binName?: string;
   /**
    * Host-specific command that (re)installs the project's git hooks, surfaced
@@ -118,6 +118,20 @@ export function resolveBinName(coordRoot?: string | null): string {
   return DEFAULT_BIN_NAME;
 }
 
+/**
+ * The binName explicitly pinned in `<projectRoot>/.harnery/config.jsonc`, or
+ * null when absent. Unlike `resolveBinName()` this ignores `HARNERY_BIN` and
+ * never falls back to the default — it answers "did someone deliberately pin
+ * a name for THIS project?". `init` uses it so a re-run from a different host
+ * CLI can't silently re-stamp its own name over a committed pin (the harnery
+ * repo itself pins `"harn"` while living embedded in a host monorepo whose
+ * CLI would otherwise stamp the host's name into public, committed surfaces).
+ */
+export function pinnedBinName(projectRoot: string): string | null {
+  const binName = readConfig(projectRoot).binName;
+  return typeof binName === "string" && binName.trim() ? binName.trim() : null;
+}
+
 /**
  * The host's git-hook (re)install command, for the "commit guard not wired"
  * nudge. Returns the configured `hooksSetupHint` (e.g. "scripts/setup-hooks.sh")

package/src/core/hooks/cli.ts

@@ -33,12 +33,12 @@ import {
   imageJanitor,
   playSound,
   resetSoundCounters,
+  runSessionSyncExtension,
   runTurnSummary,
   scratchArchive,
   scratchJanitor,
   scratchRecoveryCue,
   soundForEvent,
-  syncClaudeSessions,
 } from "./effects/index.ts";
 import { emit } from "./events/emit.ts";
 import type { Harness } from "./events/schema.ts";
@@ -508,7 +508,7 @@ async function main(): Promise<number> {
     // session-telemetry sync (via HARNERY_CLAUDE_SESSIONS_FORCE=1).
     if (harness === "claude-code") {
       scratchArchive(coordRoot, owner.instance_id);
-      syncClaudeSessions(coordRoot, true);
+      runSessionSyncExtension(coordRoot, true);
     }
   }
 
@@ -603,7 +603,7 @@ async function main(): Promise<number> {
     // CC effects: rate-limited session-telemetry sync + turn-summary Haiku
     // auto-summary.
     if (harness === "claude-code") {
-      syncClaudeSessions(coordRoot, false);
+      runSessionSyncExtension(coordRoot, false);
       runTurnSummary(coordRoot, owner.instance_id, sessionId, payload?.transcript_path);
     }
 

package/src/core/hooks/effects/index.ts

@@ -117,24 +117,31 @@ export function scratchArchive(repoRoot: string, owner: string): void {
 }
 
 /**
- * Sync Claude Code session JSONL → BigQuery (`harn claude-sessions sync`). Lives
- * in the host CLI (parses Claude Code's own ~/.claude/projects/**\/*.jsonl), so harnery
- * shells out to the harn binary rather than importing it. Detached + unref'd so a
- * slow BigQuery round-trip never blocks the hook. Stop-path syncs are rate-
- * limited inside `harn claude-sessions sync`; SessionEnd forces via env. Caller
- * gates to the claude-code harness.
+ * Fire the optional host session-sync extension on turn stop / session end.
+ * harnery core has no session-telemetry sink of its own; a host that wants one
+ * drops an executable at
+ * `scripts/hooks/harness/claude_code/extensions/session-sync.sh` under the coord
+ * root, and core runs it detached + unref'd so a slow sink never blocks the
+ * hook. `force` arrives as argv $1 ("1" on session end, "0" on turn stop) so the
+ * host can rate-limit the stop path and force-flush on end. No-op when the
+ * script is absent, so a plain public install spawns nothing. Mirrors
+ * `runTurnSummary`'s extension-script pattern. Caller gates to the claude-code
+ * harness.
  */
-export function syncClaudeSessions(repoRoot: string, force: boolean): void {
+export function runSessionSyncExtension(repoRoot: string, force: boolean): void {
   try {
-    const bin = join(repoRoot, "bin", "bp");
-    if (!existsSync(bin)) return;
-    const env: Record<string, string | undefined> = {
-      ...process.env,
-      HARNERY_OUTPUT_SESSION_TEE: "0",
-    };
-    if (force) env.HARNERY_CLAUDE_SESSIONS_FORCE = "1";
-    const child = spawn("bash", [bin, "claude-sessions", "sync", "--quiet"], {
-      env,
+    const script = join(
+      repoRoot,
+      "scripts",
+      "hooks",
+      "harness",
+      "claude_code",
+      "extensions",
+      "session-sync.sh",
+    );
+    if (!existsSync(script)) return;
+    const child = spawn("bash", [script, force ? "1" : "0"], {
+      env: { ...process.env, HARNERY_OUTPUT_SESSION_TEE: "0" },
       detached: true,
       stdio: "ignore",
     });

package/src/core/hooks/events/emit.ts

@@ -1,5 +1,6 @@
 import { appendFileSync, closeSync, mkdirSync, openSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { maybeRotateEventStream } from "./rotate.ts";
 import {
   type EventEnvelope,
   type EventType,
@@ -69,6 +70,10 @@ export function emit<TType extends EventType, TData>(
   const streamPath = join(coordRoot, STREAM_FILE);
   const lockPath = join(coordRoot, LOCK_FILE);
 
+  // Size-triggered rotation: roll the active file to a dated archive when it
+  // crosses the cap, so this append lands in a bounded fresh file. Fail-soft.
+  maybeRotateEventStream(coordRoot);
+
   ensureDir(dirname(streamPath));
   ensureFile(lockPath);
 

package/src/core/hooks/events/rotate.ts

@@ -0,0 +1,151 @@
+/**
+ * Size-triggered rotation for the canonical event stream
+ * `.harnery/events.ndjson`.
+ *
+ * The stream is a deliberately-immutable, append-only ledger. Left unbounded it
+ * grows past V8's ~512MB max string length, at which point any code that does a
+ * whole-file `readFileSync` throws ("Cannot create a string longer than
+ * 0x1fffffe8 characters"). Rather than police every current + future reader,
+ * we bound the *active* file: once it crosses a byte cap we rename it to a dated
+ * archive (`events-YYYY-MM-DD.ndjson`) and start a fresh active file. Archives
+ * are kept — the audit trail is preserved, just spread across files that readers
+ * glob newest-first.
+ *
+ * Both independent append paths (agent-hooks `hooks/events/emit.ts` and
+ * agent-coord `agents/events/emit.ts`) call `maybeRotateEventStream` before
+ * appending, so a roll is triggered continuously, not only at session
+ * boundaries.
+ *
+ * Concurrency: many short-lived hook processes append at once. The rename itself
+ * is atomic — a concurrent appender opening the path by name lands its line in
+ * whichever inode the name currently resolves to (old archive or new active
+ * file), never nowhere. The only hazard is two processes both renaming (the
+ * second would move the fresh empty file to a second archive name), which an
+ * `O_EXCL` roll-lock prevents.
+ *
+ * Design + rationale: harnery ADR 0009; decision docket
+ * `should-harnery-adopt-a-retention-2026-07-07-ed07`.
+ */
+
+import {
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { coordEnv } from "../../../lib/env.ts";
+
+const STREAM_FILE = ".harnery/events.ndjson";
+const ROLL_LOCK_FILE = ".harnery/events.ndjson.roll.lock";
+
+/** Default active-file cap: 256 MiB — half of V8's ~512MB string cliff, so even
+ * a reader that loads the whole active file whole stays clear of the limit. */
+const DEFAULT_ROLL_BYTES = 256 * 1024 * 1024;
+
+/** A roll-lock older than this is treated as abandoned (a crashed roller) and
+ * stolen. Rolls are sub-millisecond, so 60s is orders of magnitude of slack. */
+const STALE_LOCK_MS = 60_000;
+
+/** Archive glob prefix. Readers enumerate `events-*.ndjson` newest-first.
+ * The pre-existing manual `events-legacy.ndjson` matches and is picked up for
+ * free. Kept in sync with the reader-side pattern in web/lib/coord-reader.ts. */
+export const ARCHIVE_PREFIX = "events-";
+export const ARCHIVE_SUFFIX = ".ndjson";
+
+function resolveRollBytes(): number {
+  const env = coordEnv("EVENTS_ROLL_BYTES");
+  const n = env ? Number(env) : Number.NaN;
+  return Number.isFinite(n) && n > 0 ? n : DEFAULT_ROLL_BYTES;
+}
+
+/** `YYYY-MM-DD` (UTC) from a millisecond timestamp. Uses the file's own mtime
+ * rather than `Date.now()` so it's deterministic and independent of the harness
+ * runtime's clock surface. */
+function utcDateStamp(mtimeMs: number): string {
+  const d = new Date(mtimeMs);
+  const y = d.getUTCFullYear();
+  const mo = String(d.getUTCMonth() + 1).padStart(2, "0");
+  const day = String(d.getUTCDate()).padStart(2, "0");
+  return `${y}-${mo}-${day}`;
+}
+
+/** First non-colliding `events-<stamp>[.N].ndjson` path under `coordDir`. */
+function archivePathFor(coordDir: string, stamp: string): string {
+  const base = join(coordDir, `${ARCHIVE_PREFIX}${stamp}${ARCHIVE_SUFFIX}`);
+  if (!existsSync(base)) return base;
+  for (let n = 1; ; n++) {
+    const cand = join(coordDir, `${ARCHIVE_PREFIX}${stamp}.${n}${ARCHIVE_SUFFIX}`);
+    if (!existsSync(cand)) return cand;
+  }
+}
+
+/**
+ * Roll `events.ndjson` to a dated archive when it exceeds the byte cap. Cheap
+ * no-op (a single `statSync`) below the cap. Fail-soft: any error is swallowed
+ * so a rotation problem can never break the append that triggered it.
+ *
+ * `nowMs` is injectable for the stale-lock check in tests; production leaves it
+ * unset (the roll date always comes from the file's mtime, never `nowMs`).
+ */
+export function maybeRotateEventStream(coordRoot: string, nowMs?: number): boolean {
+  try {
+    const streamPath = join(coordRoot, STREAM_FILE);
+    if (!existsSync(streamPath)) return false;
+    const cap = resolveRollBytes();
+    let st = statSync(streamPath);
+    if (st.size < cap) return false;
+
+    const coordDir = dirname(streamPath);
+    const lockPath = join(coordRoot, ROLL_LOCK_FILE);
+    mkdirSync(coordDir, { recursive: true });
+
+    if (!acquireRollLock(lockPath, nowMs)) return false; // another roller active
+    try {
+      // Re-check under the lock: a concurrent process may have just rolled.
+      if (!existsSync(streamPath)) return false;
+      st = statSync(streamPath);
+      if (st.size < cap) return false;
+
+      const archive = archivePathFor(coordDir, utcDateStamp(st.mtimeMs));
+      renameSync(streamPath, archive);
+      // Recreate an empty active file so the very next append (and any reader's
+      // existsSync) sees a valid, present stream.
+      closeSync(openSync(streamPath, "a"));
+      return true;
+    } finally {
+      try {
+        unlinkSync(lockPath);
+      } catch {
+        /* best-effort */
+      }
+    }
+  } catch {
+    return false; // fail-soft: never break the caller's append
+  }
+}
+
+/** Create the roll-lock with O_EXCL. Returns true on acquisition. On collision,
+ * steals a stale lock (crashed roller) once, else returns false. */
+function acquireRollLock(lockPath: string, nowMs?: number): boolean {
+  try {
+    closeSync(openSync(lockPath, "wx"));
+    return true;
+  } catch {
+    // Exists: steal if abandoned.
+    try {
+      const age = (nowMs ?? Date.now()) - statSync(lockPath).mtimeMs;
+      if (age > STALE_LOCK_MS) {
+        unlinkSync(lockPath);
+        closeSync(openSync(lockPath, "wx"));
+        return true;
+      }
+    } catch {
+      /* lost the steal race — someone else holds it */
+    }
+    return false;
+  }
+}

package/src/core/hooks/harness/events.ts

@@ -34,6 +34,12 @@ export interface HarnessSpec {
   entryShape: HookEntryShape;
   /** When set, ensure this top-level `version` key in the file (Cursor requires `1`). */
   rootVersion?: number;
+  /** Harness-owned entries from older specs that `init` should remove during migration. */
+  legacyEvents?: HookEvent[];
+  /** Strict top-level settings keys accepted by this harness, when its parser is closed. */
+  allowedTopLevelKeys?: string[];
+  /** Strict hook event keys accepted by this harness, including events harnery does not wire. */
+  allowedEventKeys?: string[];
 }
 
 /** Claude Code: `.claude/settings.json`. */
@@ -67,20 +73,38 @@ export const CURSOR_EVENTS: HookEvent[] = [
   { settingsKey: "stop", subcommand: "stop" },
 ];
 
-/** Codex: `.codex/hooks.json`. PascalCase keys + the same entry shape as Claude Code. */
+/** Codex events that harnery uses from the current native lifecycle surface. */
 export const CODEX_EVENTS: HookEvent[] = [
   { settingsKey: "SessionStart", subcommand: "session-start" },
-  { settingsKey: "SessionEnd", subcommand: "session-end" },
   { settingsKey: "PreToolUse", subcommand: "pre-tool-use" },
   { settingsKey: "PostToolUse", subcommand: "post-tool-use" },
-  { settingsKey: "PostToolUseFailure", subcommand: "post-tool-use-failure" },
   { settingsKey: "UserPromptSubmit", subcommand: "user-prompt-submit" },
   { settingsKey: "SubagentStart", subcommand: "sub-agent-start" },
   { settingsKey: "SubagentStop", subcommand: "sub-agent-stop" },
   { settingsKey: "Stop", subcommand: "stop" },
+];
+
+/** Entries written by harnery before Codex adopted a strict native hook schema. */
+export const LEGACY_CODEX_EVENTS: HookEvent[] = [
+  { settingsKey: "SessionEnd", subcommand: "session-end" },
+  { settingsKey: "PostToolUseFailure", subcommand: "post-tool-use-failure" },
   { settingsKey: "StopFailure", subcommand: "stop-failure" },
 ];
 
+/** Every hook key accepted by Codex 0.144, including events harnery does not consume. */
+export const CODEX_ALLOWED_EVENT_KEYS = [
+  "SessionStart",
+  "PreToolUse",
+  "PermissionRequest",
+  "PostToolUse",
+  "PreCompact",
+  "PostCompact",
+  "UserPromptSubmit",
+  "SubagentStart",
+  "SubagentStop",
+  "Stop",
+];
+
 /** Every supported harness, fully wireable by `harn init`. */
 export const HARNESS_SPECS: Record<HarnessId, HarnessSpec> = {
   "claude-code": {
@@ -98,5 +122,8 @@ export const HARNESS_SPECS: Record<HarnessId, HarnessSpec> = {
     settingsFile: ".codex/hooks.json",
     events: CODEX_EVENTS,
     entryShape: "claude",
+    legacyEvents: LEGACY_CODEX_EVENTS,
+    allowedTopLevelKeys: ["description", "hooks"],
+    allowedEventKeys: CODEX_ALLOWED_EVENT_KEYS,
   },
 };