aicodeman 1.45.0 → 1.47.0

package/README.md

@@ -460,7 +460,7 @@ PTY Output → 16ms Server Batch → DEC 2026 Wrap → SSE → Client rAF → xt
 - **Background daemon & service install** — `codeman web -d` runs the server detached with a pidfile, `~/.codeman/web.log`, and verified startup (it polls the server until it answers, so a port clash never reads as success); `codeman service install` writes a systemd user unit (Linux) or LaunchAgent (macOS) with your shell's PATH baked in, so an nvm or Homebrew `node`, `tmux` and `claude` are actually found. Secrets are never written into unit files
 - **Diagnostics in Settings** — **App Settings → System → Diagnostics → Run checks** runs `codeman doctor` on the server and lists Node, tmux, every agent CLI and the optional office tools with versions, paths and install hints. Besides the `PATH`, it also looks in each CLI's usual install directories (`~/.local/bin`, `~/.npm-global/bin` and the like), so most installs are found under a service with a minimal `PATH`. Admin only in multi-user mode.
 - **Self-update** — git-clone installs under systemd/launchd update in place from **App Settings → System → Updates**: it detects the latest release, auto-stashes a dirty tree, and streams build progress across the service restart (npm installs report as non-updatable)
-- **Git status in the bottom bar** — off by default (**App Settings → Header & Panels → Bottom bar → Git status**, per device). A small indicator at the right of the bottom bar shows the active session's repository at a glance: `● 3` uncommitted files, `↑ 2` commits not pushed, `⚠` merge conflicts, `✓` all committed and pushed. Click it for a draggable window listing the staged, not-staged, untracked and conflicted files (grouped under collapsed folders, or as a flat list if you turn that setting off) and the unpushed commits; **click a file to see its diff** (new files as all additions, deleted files as all removals), with **Open file** to jump to the viewer. A folder that holds several projects gets one collapsible section per repository found up to two levels down, all collapsed until you open them. Read-only and offline (Codeman never fetches or changes the repo); not shown for Docker or remote sessions.
+- **Git status in the bottom bar** — off by default (**App Settings → Header & Panels → Bottom bar → Git status**, per device). A small indicator at the right of the bottom bar shows the active session's repository at a glance: `● 3` uncommitted files, `↑ 2` commits not pushed, `⚠` merge conflicts, `✓` all committed and pushed. Click it for a draggable window listing the staged, not-staged, untracked and conflicted files (grouped under collapsed folders, or as a flat list if you turn that setting off) and the unpushed commits; **click a file to see its diff** (new files as all additions, deleted files as all removals), with **Open file** to jump to the viewer. A folder that holds several projects gets one collapsible section per repository found up to two levels down, all collapsed until you open them. **Fetch** in that window's header runs `git fetch` for the repositories it lists, on your click or on an interval you turn on (**App Settings → Bottom bar**, off by default; **Session Options → Git** overrides both the switch and the interval per session). Sessions open on the same folder share one run and each sees its result. Apart from that fetch Codeman never fetches or changes the repo, so "behind" is as of the last fetch; not shown for Docker or remote sessions.
 - **Clone a GitHub repo as a case** — paste a repository URL into **Add Case → Clone Repo** and Codeman clones it into `~/codeman-cases/<name>` and registers it as a normal case, ready to run an agent in. It preflights the URL while you type (tells you whether it can be cloned anonymously and offers the repo's real branches and tags for the optional branch/tag field), fills the case name in from the URL, and lets you pick which CLI the Run button should use. Public repositories over `https://`; Codeman never collects or stores credentials
 - **Create a case in a custom folder** — tick **Create in a custom folder** in **Add Case → Create New**, pick a parent folder (Browse included) and a name, and Codeman scaffolds the new case there instead of `~/codeman-cases`. The target must be a new or empty folder; system directories, your home folder itself, credential trees such as `~/.ssh`, and Codeman's own data folder are refused. Admin only in multi-user mode.
 - **Multi-CLI** — run **Claude Code**, **OpenCode**, **Codex**, **Antigravity**, **Gemini**, **Pi**, **Grok**, **DeepSeek Harness**, **OMP**, or **GitHub Copilot CLI** per session; env-var prefixes auto-gate (`CLAUDE_CODE_*` vs `OPENCODE_*` vs `CODEX_*` vs `ANTIGRAVITY_*` vs `GEMINI_*`/`GOOGLE_*` vs `PI_*` vs `GROK_*`/`XAI_*` vs `DSH_*`/`DEEPSEEK_*` vs `OMP_*` vs `COPILOT_*`). See [`docs/opencode-integration.md`](docs/opencode-integration.md), [`docs/pi-integration.md`](docs/pi-integration.md), [`docs/grok-integration.md`](docs/grok-integration.md), [`docs/deepseek-integration.md`](docs/deepseek-integration.md) [`docs/omp-integration.md`](docs/omp-integration.md) and [`docs/copilot-integration.md`](docs/copilot-integration.md)
@@ -584,6 +584,8 @@ loginctl enable-linger $USER
 
 **Always set `CODEMAN_PASSWORD`** before exposing via tunnel — without it, anyone with the URL has full access to your sessions.
 
+The tunnel Codeman manages (App Settings → System → Remote access) refuses to start without a login (`CODEMAN_PASSWORD` or multi-user mode) unless `CODEMAN_ALLOW_UNAUTHENTICATED_TUNNEL=1` or `codeman web --allow-unauthenticated-tunnel` acknowledges the exposure, or you accept the browser's confirm, which it asks before every enable while no login is set. `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK` covers only the network bind: it does not let the tunnel start.
+
 </details>
 
 ### QR Code Authentication
@@ -825,12 +827,14 @@ Those `DONE_<task>_<random>` strings are the skill's **split marker** trick, and
 | [`reference/recipes.md`](skills/codeman/reference/recipes.md)       | 8 worked flows: claude, DeepSeek Harness and shell workers, fan-out, blocked-worker watch, messaging fan-out. On demand. |
 | [`reference/endpoints.md`](skills/codeman/reference/endpoints.md)   | Full endpoint tables, error codes, per-mode signal table, capacity limits. On demand.        |
 | [`reference/messaging.md`](skills/codeman/reference/messaging.md)   | Talking to claude workers directly via Claude Code cross-session messaging. On demand.       |
+| [`reference/history.md`](skills/codeman/reference/history.md)       | Reading saved Codex conversations offline with `codeman history read`: selectors, filters, forks, budgets. On demand. |
+| [`reference/inspection-and-staging.md`](skills/codeman/reference/inspection-and-staging.md) | Experimental and opt-in: bounded pane inspection and guarded submission with `codeman agent inspect`, `stage` and `submit`. On demand. |
 
 Every recipe in there was verified against a live server, and the comments record the failure modes that were measured rather than guessed.
 
 #### Two things worth knowing
 
-- **It self-gates.** Outside a Codeman session (`CODEMAN_MUX` unset) the skill refuses to act and does not guess an API URL, so a global install costs an unrelated Claude Code session nothing.
+- **It self-gates.** It acts inside a Codeman-managed session. Outside one (`CODEMAN_MUX` unset) it only reads saved Codex conversations offline (`codeman history read`) and refuses everything else, and it never guesses an API URL, so a global install costs an unrelated Claude Code session nothing.
 - **It is deliberately conservative.** Unprompted, it may only spawn sessions, prompt them, and delete ones **it created in that same conversation, by exact id**, through a fail-closed guard that refuses to delete the agent's own session. Deleting a case (which erases a real directory of your code), bulk kills, respawn/ralph/cron/orchestrator changes and settings writes all require you to ask, naming the target.
 
 ⚠️ Turning `agentSkillEnabled` back off **does not remove already-injected copies** (a create-time sweep would yank the skill out from under other live sessions sharing that workspace). Remove them per case with `codeman skill uninstall --case <name>`.
@@ -977,14 +981,18 @@ codeman tui 3                            #      attach to session 3 of that list
 
 ### `codeman agent` — session-to-session verbs in every CLI mode
 
-The skill above drives the API with `curl` and `jq` from a preamble Codeman seeds per session. Where it does not reach (a `pi` or `shell` session, a machine without `jq`), the same environment is still there (`CODEMAN_MUX=1`, `CODEMAN_SESSION_ID`, `CODEMAN_API_URL` are exported into every pane), so `codeman agent` packages the same verbs as commands. It is a thin client over the endpoints listed under [API](#api): no new route, no new transport, auth and ownership unchanged. One line in a case's `AGENTS.md` is enough: *"other sessions: `codeman agent --help`"*.
+The skill above drives the API with `curl` and `jq` from a preamble Codeman seeds per session. Where it does not reach (a `pi` or `shell` session, a machine without `jq`), the same environment is still there (`CODEMAN_MUX=1`, `CODEMAN_SESSION_ID`, `CODEMAN_API_URL` are exported into every pane), so `codeman agent` packages the same verbs as commands. It is a thin client over the endpoints listed under [API](#api): auth and ownership apply to every endpoint, including bounded inspection and guarded input. The `inspect`, `stage` and `submit` commands and their HTTP routes are **experimental** and **opt-in**: turn on **Experimental agent coordination** in App Settings (`agentCoordinationEnabled`, synced, off by default; until then the routes answer `403 FORBIDDEN` naming it). Their commands, flags, paths, payloads and behavior may change or be removed in minor or patch releases, so pin a compatible version when automating them; see [Experimental agent coordination](docs/versioning-policy.md#experimental-agent-coordination). One line in a case's `AGENTS.md` is enough: *"other sessions: `codeman agent --help`"*.
 
 ```bash
 codeman agent ls                                          # sessions; * marks this one
 SID=$(codeman agent spawn scratch-1 --mode claude)        # quick-start + wait for the composer where the mode has a ready mark
+SID=$(codeman agent spawn --working-dir ~/src/app --mode codex)   # no case: an existing directory (cwd by default)
 codeman agent send "$SID" 'review src/, then say DONE' --until stop,exit --timeout 300000   # --wait = default signal set
 codeman agent read "$SID"                                 # last answer (as the server reads it for that mode)
 codeman agent read "$SID" --tail 3000                     # terminal tail, ANSI stripped (every mode)
+codeman agent inspect "$SID" --max-bytes 8192 --json     # recent evidence + opaque cursor (pane snapshots are labeled)
+codeman agent stage "$SID" --message-file /tmp/prompt.txt --json  # no Enter; known local Codex composer only
+codeman agent submit "$SID" --stage-id "$STAGE_ID" --confirm-sha "$SHA256" --json  # one conditional Enter
 codeman agent send "$SID" 'run the tests, then print WORKDONE followed by _4711'   # hook-less modes (opencode, pi, …): ask for the marker in halves …
 codeman agent wait "$SID" --match WORKDONE_4711           # … and wait on the joined form, which the prompt's echo never contains
 codeman agent interrupt "$SID"                            # a bare ESC, conversation intact
@@ -994,11 +1002,23 @@ codeman agent ack <msg-id>                                # remove what you hand
 codeman agent rm "$SID"                                   # any session except this one
 ```
 
-Rules the commands enforce rather than document: they refuse outside a Codeman session and never guess a URL; `send` transmits printable text plus Enter only (a control byte such as `Ctrl+C` is `app_exit` in opencode — ESC exists solely as `interrupt`, which never appends Enter); `rm` refuses an empty id, an unprovable self id and a prefix match in either direction. Ids may be the 8-character prefixes `ls` prints (resolved through the list; an ambiguous prefix refuses, anything shorter than 8 characters refuses on every verb). A prompt that starts with `-` goes after `--` (`send "$SID" -- "- fix the bug"`). The echo of the prompt you sent is output too: a `--match` marker that appears verbatim in the prompt matches at once, before the worker has done anything, so the prompt asks for it in halves. A remote session whose host is asleep answers a fire-and-forget `send` with `buffered` (Codeman wakes the host and types the prompt once the pane is back) or `dropped` (over the wake buffer's cap, nothing will be typed: exit `1`). Exit codes: `0` delivered/matched/signal, `1` error, `2` timeout, `3` the worker exited or the wait ended without an answer (`delivered:false`, `ended:true`), `4` refused. `spawn` prints the id alone on stdout (prose goes to stderr), so `SID=$(…)` captures exactly the id. `--json` prints the envelope's `data` for every verb. `--until stop` on a mode without hook signals is the server's 400, passed through — the marker path (`--match`) is the answer there, exactly as for the skill.
+Rules the commands enforce rather than document: they refuse outside a Codeman session and never guess a URL; `send` transmits printable text plus Enter only (a control byte such as `Ctrl+C` is `app_exit` in opencode — ESC exists solely as `interrupt`, which never appends Enter); `rm` refuses an empty id, an unprovable self id and a prefix match in either direction. Ids may be the 8-character prefixes `ls` prints (resolved through the list; an ambiguous prefix refuses, anything shorter than 8 characters refuses on every verb). A prompt that starts with `-` goes after `--` (`send "$SID" -- "- fix the bug"`). The echo of the prompt you sent is output too: a `--match` marker that appears verbatim in the prompt matches at once, before the worker has done anything, so the prompt asks for it in halves. A remote session whose host is asleep answers a fire-and-forget `send` with `buffered` (Codeman wakes the host and types the prompt once the pane is back) or `dropped` (over the wake buffer's cap, nothing will be typed: exit `1`). Exit codes: `0` delivered/matched/signal, `1` error, `2` timeout, `3` the worker exited or the wait ended without an answer (`delivered:false`, `ended:true`), `4` refused. `spawn` prints the id alone on stdout (prose goes to stderr), so `SID=$(…)` captures exactly the id. `spawn` with no case, or with `--working-dir`, starts the worker in that existing directory through `POST /api/v1/sessions` plus `POST /api/v1/sessions/:id/interactive` (or `/shell`) instead of quick-start, so no case is created and the directory is never labelled agent scratch; an empty `--working-dir` refuses (exit `4`) rather than falling back to cwd, and so does a cwd that is your home directory (Codeman's hooks would land in `~/.claude`), which needs an explicit `--working-dir ~`; if the start fails it still prints the created id and exits `1`. `--json` prints the envelope's `data` for every verb, except a directory `spawn`, which prints `{ sessionId, workingDir, created: true }`, plus `ready` when a readiness wait ran, `readinessError` when that call failed, and `startupError` when the start failed. `--until stop` on a mode without hook signals is the server's 400, passed through — the marker path (`--match`) is the answer there, exactly as for the skill.
+
+### `codeman history read`: saved Codex conversations, offline
+
+`codeman history read` reads Codex's own saved rollouts (`$CODEX_HOME/sessions`, else `~/.codex/sessions`) straight from disk: no server, no managed session, nothing written. Unlike `codeman agent` it works anywhere, including on a machine where Codeman is not running.
+
+```bash
+codeman history read --session-id 019fc604                         # one conversation, by native id or 8+ character prefix
+codeman history read --root-session-id <uuid> --topic auth          # a conversation and every sub-agent or fork under it
+codeman history read --file /path/to/rollout.jsonl --format text
+```
+
+Filters keep whole user/assistant turns (`--topic` is a literal, case-insensitive match; `--after`/`--before` are inclusive UTC dates). A forked or spawned thread's copy of its parent's history is dropped, so every record belongs to the thread that wrote it. Output is JSON by default and carries `complete: false` whenever the evidence is partial (a file that could not be attributed, a compressed `.jsonl.zst` rollout, a record a running Codex is still writing, an unknown ancestor). Every bound fails closed and is raisable: `--metadata-bytes` (attributing the store, default 1 GiB), `--max-entries` (default 65536), `--scan-bytes` (the selected transcripts, default 16 MiB) and `--max-bytes` (output, default 8192). The full reference is [`skills/codeman/reference/history.md`](skills/codeman/reference/history.md).
 
 ### MCP server (`codeman mcp`): drive Codeman from any MCP client
 
-`codeman mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server on stdio, so any MCP client (Claude Code, Claude Desktop, Codex, Gemini CLI, Cursor, ...) can start Codeman sessions in any installed agent CLI, prompt them, wait for them, read their answers and clean up, from inside Codeman or from outside it. Like `codeman agent`, it is a client of the HTTP API: no new route, auth and ownership unchanged.
+`codeman mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server on stdio, so any MCP client (Claude Code, Claude Desktop, Codex, Gemini CLI, Cursor, ...) can start Codeman sessions in any installed agent CLI, prompt them, wait for them, read their answers and clean up, from inside Codeman or from outside it. Like `codeman agent`, it is a client of the HTTP API. The MCP server adds no routes of its own, and auth and ownership are unchanged.
 
 ```bash
 # Claude Code
@@ -1227,7 +1247,7 @@ Full details: [`docs/archive/code-structure-findings.md`](docs/archive/code-stru
 
 [![npm](https://img.shields.io/npm/v/xterm-zerolag-input?style=flat-square&color=22c55e)](https://www.npmjs.com/package/xterm-zerolag-input)
 
-Instant keystroke feedback overlay for xterm.js. Eliminates perceived input latency over high-RTT connections by rendering typed characters immediately as a pixel-perfect DOM overlay. Zero dependencies, 6.1 kB gzipped, configurable prompt detection, CJK/emoji wide-character support, full state machine with 238 tests.
+Instant keystroke feedback overlay for xterm.js. Eliminates perceived input latency over high-RTT connections by rendering typed characters immediately as a pixel-perfect DOM overlay. Zero dependencies, 5.7 kB minified and gzipped, configurable prompt detection, CJK/emoji wide-character support, full state machine with 276 tests. Typing cost does not grow with prompt length.
 
 ```bash
 npm install xterm-zerolag-input

package/dist/agent-codex-identity.d.ts

@@ -0,0 +1,26 @@
+export interface CodexAttributionOptions {
+    codexHome: string;
+    sessionId: string;
+    workingDir: string;
+    resumeSessionId?: string;
+}
+export interface CodexAttributionBudget {
+    maxEntries: number;
+    maxBytes: number;
+    /** Separate bound for cheap negative prefixes; full candidate metadata has its own budget. */
+    maxPrefixBytes?: number;
+}
+/** Match the CLI's relative CODEX_HOME interpretation without exposing env credentials. */
+export declare function resolveEffectiveCodexHome(sessionHome: string | undefined, workingDir: string, env?: Readonly<Record<string, string | undefined>>): string;
+/** Test-only: forget every remembered attribution. */
+export declare function __clearCodexAttributionMemo(): void;
+/**
+ * A configured resume and a newly owned rollout conflict rather than pinning an
+ * old launch forever after /new. TUI resumes of foreign-originator threads cannot
+ * be authoritatively tracked from this metadata; this returns attributed evidence.
+ */
+export declare function findExactCodexConversation(options: CodexAttributionOptions, budget?: CodexAttributionBudget): Promise<{
+    id: string;
+    path: string;
+} | undefined>;
+//# sourceMappingURL=agent-codex-identity.d.ts.map

package/dist/agent-codex-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-codex-identity.d.ts","sourceRoot":"","sources":["../src/agent-codex-identity.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AACD,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,8FAA8F;IAC9F,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAcD,2FAA2F;AAC3F,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,UAAU,EAAE,MAAM,EAClB,GAAG,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAe,GAC9D,MAAM,CAGR;AA4CD,sDAAsD;AACtD,wBAAgB,2BAA2B,IAAI,IAAI,CAElD;AAeD;;;;GAIG;AACH,wBAAsB,0BAA0B,CAC9C,OAAO,EAAE,uBAAuB,EAChC,MAAM,GAAE,sBAAgE,GACvE,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAC,CAsDnD"}

package/dist/agent-codex-identity.js

@@ -0,0 +1,253 @@
+/**
+ * @fileoverview Bounded Codex rollout attribution for agent evidence. Never uses
+ * newest-mtime, prompt timestamps or cwd alone as proof of session ownership.
+ * The first call walks the store under explicit budgets; the attributed file is
+ * then remembered per session and only re-verified (plus a scan of the date
+ * directories not older than it) on later calls, since codex never prunes
+ * `~/.codex/sessions`.
+ */
+import { open, opendir, realpath } from 'node:fs/promises';
+import { probePathKind } from './utils/bounded-path-probe.js';
+import { tmpdir } from 'node:os';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { LRUMap } from './utils/lru-map.js';
+const UUID_AT_END = /-([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i;
+const HEAD_BYTES = 131072;
+const PREFIX_SCAN_BYTES = 8 * 1024 * 1024;
+async function canonical(path) {
+    if ((await probePathKind(path, { pastCap: true })) !== 'directory')
+        return undefined;
+    try {
+        return await realpath(path);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Match the CLI's relative CODEX_HOME interpretation without exposing env credentials. */
+export function resolveEffectiveCodexHome(sessionHome, workingDir, env = process.env) {
+    const path = resolve(workingDir, sessionHome || env.CODEX_HOME || join(env.HOME || tmpdir(), '.codex'));
+    return path;
+}
+/** Complete metadata only: a prefix or a partially flushed JSONL row proves nothing. */
+function strictMetadata(bytes) {
+    const rows = bytes.toString('utf8').split('\n');
+    rows.pop();
+    let found;
+    for (const line of rows) {
+        try {
+            const row = JSON.parse(line);
+            if (row.type !== 'session_meta')
+                continue;
+            if (found ||
+                typeof row.payload?.id !== 'string' ||
+                typeof row.payload.cwd !== 'string' ||
+                (row.payload.originator !== undefined && typeof row.payload.originator !== 'string'))
+                return undefined;
+            found = row.payload;
+        }
+        catch {
+            /* Incomplete or malformed rows are not identity evidence. */
+        }
+    }
+    return found;
+}
+const attributionMemo = new LRUMap({ maxSize: 1024 });
+/** Test-only: forget every remembered attribution. */
+export function __clearCodexAttributionMemo() {
+    attributionMemo.clear();
+}
+/** Short first read: `originator` sits right after `id`, `timestamp` and `cwd`. */
+const PREFIX_FIRST_BYTES = 1024;
+/** Fallback read when the first window holds no complete `originator` field. */
+const PREFIX_MAX_BYTES = 4096;
+const ORIGINATOR_FIELD = /"originator"\s*:\s*"(?:[^"\\]|\\.)*"/;
+/**
+ * Is a date-shaped directory name older than the remembered one at the same depth?
+ * Only all-digit names compare (codex writes `sessions/YYYY/MM/DD/`); anything else
+ * is never pruned, so an unexpected layout costs a wider scan, not a missed rollout.
+ */
+function olderDatePart(name, memo) {
+    if (memo === undefined || !/^\d+$/.test(name) || !/^\d+$/.test(memo))
+        return false;
+    return Number(name) < Number(memo);
+}
+/**
+ * A configured resume and a newly owned rollout conflict rather than pinning an
+ * old launch forever after /new. TUI resumes of foreign-originator threads cannot
+ * be authoritatively tracked from this metadata; this returns attributed evidence.
+ */
+export async function findExactCodexConversation(options, budget = { maxEntries: 8192, maxBytes: 1048576 }) {
+    const workspace = await canonical(options.workingDir);
+    const home = await canonical(options.codexHome);
+    if (!workspace || !home)
+        return undefined;
+    const sessions = join(home, 'sessions');
+    if ((await probePathKind(sessions, { pastCap: true })) !== 'directory')
+        return undefined;
+    const key = [home, options.sessionId, options.resumeSessionId ?? '', workspace].join('\0');
+    const remembered = attributionMemo.get(key);
+    if (remembered) {
+        const verified = await verifyRemembered(remembered, workspace, budget);
+        if (verified) {
+            const others = await scanCandidates(sessions, options, budget, remembered.dirParts);
+            if (others && others.length === 1 && others[0].path === remembered.path) {
+                return { id: remembered.id, path: remembered.path };
+            }
+        }
+        attributionMemo.delete(key);
+        // A file that no longer verifies (replaced, rewritten, gone) gets one full walk
+        // now. A verified file whose incremental scan failed does not: that scan reads a
+        // subset of what a full walk reads under the same budget, so a second candidate,
+        // an exhausted budget or an unreadable entry it hit is one the full walk would hit
+        // too, and walking the whole never-pruned store could only end the same way.
+        if (verified)
+            return undefined;
+    }
+    const candidates = await scanCandidates(sessions, options, budget);
+    if (!candidates || candidates.length !== 1)
+        return undefined;
+    const candidate = candidates[0];
+    if (!candidate.meta.cwd || (await canonical(candidate.meta.cwd)) !== workspace)
+        return undefined;
+    const handle = await open(candidate.path, 'r').catch(() => undefined);
+    if (!handle)
+        return undefined;
+    try {
+        const info = await handle.stat();
+        const bytes = Buffer.alloc(HEAD_BYTES);
+        const read = await handle.read(bytes, 0, bytes.length, 0);
+        const meta = strictMetadata(bytes.subarray(0, read.bytesRead));
+        if (!meta ||
+            meta.id !== candidate.id ||
+            meta.cwd !== candidate.meta.cwd ||
+            meta.originator !== candidate.meta.originator)
+            return undefined;
+        attributionMemo.set(key, {
+            id: candidate.id,
+            path: candidate.path,
+            dev: info.dev,
+            ino: info.ino,
+            meta,
+            dirParts: relative(sessions, dirname(candidate.path)).split(sep).filter(Boolean),
+        });
+        return { id: candidate.id, path: candidate.path };
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Same file (`dev:ino`), same strict metadata, same canonical workspace: nothing else. */
+async function verifyRemembered(memo, workspace, budget) {
+    if (HEAD_BYTES > budget.maxBytes)
+        return false;
+    if (!memo.meta.cwd || (await canonical(memo.meta.cwd)) !== workspace)
+        return false;
+    const handle = await open(memo.path, 'r').catch(() => undefined);
+    if (!handle)
+        return false;
+    try {
+        const info = await handle.stat();
+        if (!info.isFile() || info.dev !== memo.dev || info.ino !== memo.ino)
+            return false;
+        const bytes = Buffer.alloc(HEAD_BYTES);
+        const read = await handle.read(bytes, 0, bytes.length, 0);
+        const meta = strictMetadata(bytes.subarray(0, read.bytesRead));
+        return !!meta && meta.id === memo.id && meta.cwd === memo.meta.cwd && meta.originator === memo.meta.originator;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Every rollout under `sessions` whose strict metadata names this session (or the
+ * configured resume id), or undefined when the walk hit a bound or an unreadable
+ * entry (an incomplete inventory proves nothing). With `notOlderThan`, date-shaped
+ * directories older than those components are skipped.
+ */
+async function scanCandidates(sessions, options, budget, notOlderThan) {
+    // `onBoundary`: every ancestor so far equals the remembered path, so pruning applies.
+    const directories = [{ path: sessions, depth: 0, onBoundary: notOlderThan !== undefined }];
+    const candidates = [];
+    const originator = `codeman_${options.sessionId}`;
+    const originatorJson = JSON.stringify(originator);
+    const explicit = options.resumeSessionId;
+    let entries = 0;
+    let prefixes = 0;
+    const prefixLimit = Math.min(budget.maxPrefixBytes ?? PREFIX_SCAN_BYTES, PREFIX_SCAN_BYTES);
+    let scanned = HEAD_BYTES; // Reserve an independent final verification.
+    while (directories.length) {
+        const dir = directories.pop();
+        const handle = await opendir(dir.path).catch(() => undefined);
+        if (!handle)
+            return undefined;
+        for await (const entry of handle) {
+            if (++entries > budget.maxEntries)
+                return undefined;
+            const path = join(dir.path, entry.name);
+            if (entry.isDirectory()) {
+                if (dir.depth >= 8)
+                    return undefined;
+                const part = notOlderThan?.[dir.depth];
+                if (dir.onBoundary && olderDatePart(entry.name, part))
+                    continue;
+                directories.push({ path, depth: dir.depth + 1, onBoundary: dir.onBoundary && entry.name === part });
+            }
+            else if (entry.isFile() && entry.name.endsWith('.jsonl')) {
+                const id = entry.name.match(UUID_AT_END)?.[1];
+                if (!id)
+                    continue; // no rollout id in the name: never a candidate, read nothing
+                const file = await open(path, 'r').catch(() => undefined);
+                if (!file)
+                    return undefined;
+                try {
+                    const info = await file.stat();
+                    if (!info.isFile())
+                        return undefined;
+                    if (id !== explicit) {
+                        // Cheap negative filter only; a match still needs full parsed metadata.
+                        // A short first window decides when it already holds the whole
+                        // `originator` field; only otherwise is the wider window read.
+                        let window = Math.min(info.size, PREFIX_FIRST_BYTES);
+                        let prefix = '';
+                        for (;;) {
+                            if (prefixes + window > prefixLimit)
+                                return undefined;
+                            prefixes += window;
+                            const buffer = Buffer.alloc(window);
+                            const first = await file.read(buffer, 0, window, 0);
+                            prefix = buffer.subarray(0, first.bytesRead).toString('utf8');
+                            if (prefix.includes(originatorJson) || ORIGINATOR_FIELD.test(prefix))
+                                break;
+                            const wider = Math.min(info.size, PREFIX_MAX_BYTES);
+                            if (wider <= window)
+                                break;
+                            window = wider;
+                        }
+                        if (!prefix.includes(originatorJson))
+                            continue;
+                    }
+                    const size = Math.min(info.size, HEAD_BYTES);
+                    if (scanned + size > budget.maxBytes)
+                        return undefined;
+                    scanned += size;
+                    const bytes = Buffer.alloc(size);
+                    const read = await file.read(bytes, 0, size, 0);
+                    const meta = strictMetadata(bytes.subarray(0, read.bytesRead));
+                    if (!meta || meta.id !== id)
+                        continue;
+                    if (id === explicit || meta.originator === originator)
+                        candidates.push({ id, path, meta });
+                }
+                finally {
+                    await file.close();
+                }
+            }
+        }
+    }
+    return candidates;
+}
+//# sourceMappingURL=agent-codex-identity.js.map

package/dist/agent-codex-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-codex-identity.js","sourceRoot":"","sources":["../src/agent-codex-identity.ts"],"names":[],"mappings":"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"}

package/dist/agent-inspection.d.ts

@@ -0,0 +1,32 @@
+export declare const INSPECT_MAX_BYTES = 65536;
+export declare const INSPECT_SCAN_BYTES = 262144;
+export interface InspectionScope {
+    owner: string;
+    sessionId: string;
+    generation: string;
+    conversationId: string;
+}
+export declare class InspectionConflict extends Error {
+}
+/** UTF8-safe suffix, also used for explicitly non-incremental pane evidence. */
+export declare function boundedUtf8Tail(text: string, maxBytes: number): string;
+/** Cursors kept per owner and session; older ones are retired first. */
+export declare const INSPECT_CURSORS_PER_SCOPE = 8;
+export declare class InspectionReader {
+    private readonly now;
+    private readonly capacity;
+    private readonly ttlMs;
+    private readonly perScope;
+    private readonly cursors;
+    constructor(now?: () => number, capacity?: number, ttlMs?: number, perScope?: number);
+    read(path: string, scope: InspectionScope, maxBytes: number, since?: string): Promise<{
+        evidence: string;
+        cursor: `${string}-${string}-${string}-${string}-${string}`;
+        omittedBeforeBytes: number;
+        truncated: boolean;
+        blockedReason: string | undefined;
+        scannedBytes: number;
+    }>;
+    clear(): void;
+}
+//# sourceMappingURL=agent-inspection.d.ts.map

package/dist/agent-inspection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-inspection.d.ts","sourceRoot":"","sources":["../src/agent-inspection.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,iBAAiB,QAAQ,CAAC;AACvC,eAAO,MAAM,kBAAkB,SAAS,CAAC;AACzC,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;CACxB;AAcD,qBAAa,kBAAmB,SAAQ,KAAK;CAAG;AAEhD,gFAAgF;AAChF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAOtE;AAUD,wEAAwE;AACxE,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAE3C,qBAAa,gBAAgB;IAGzB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAL3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;gBAEvC,GAAG,eAAW,EACd,QAAQ,SAAO,EACf,KAAK,SAAS,EACd,QAAQ,SAA4B;IAGjD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;;;;;;;;IA6IjF,KAAK,IAAI,IAAI;CAGd"}

package/dist/agent-inspection.js

@@ -0,0 +1,196 @@
+/**
+ * @fileoverview Bounded append-only JSONL evidence reads for agent inspection.
+ * Opaque, expiring server-side cursors contain no public filesystem paths. A cursor
+ * binds the caller, pane generation, attributed conversation and opened file identity.
+ * Complete records only; an oversized row stalls explicitly rather than losing evidence.
+ */
+import { open } from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import { isUtf8 } from 'node:buffer';
+export const INSPECT_MAX_BYTES = 65536;
+export const INSPECT_SCAN_BYTES = 262144;
+export class InspectionConflict extends Error {
+}
+/** UTF8-safe suffix, also used for explicitly non-incremental pane evidence. */
+export function boundedUtf8Tail(text, maxBytes) {
+    // A UTF8 suffix fits within this many UTF16 units. Include a pair of extra
+    // units so slicing cannot introduce a surrogate replacement inside the result.
+    const bytes = Buffer.from(text.slice(-maxBytes - 2));
+    let start = Math.max(0, bytes.length - maxBytes);
+    while (start < bytes.length && (bytes[start] & 0xc0) === 0x80)
+        start++;
+    return bytes.subarray(start).toString('utf8');
+}
+async function anchor(handle, offset) {
+    const count = Math.min(offset, 4096);
+    const head = Buffer.alloc(count);
+    const tail = Buffer.alloc(count);
+    await handle.read(head, 0, count, 0);
+    await handle.read(tail, 0, count, Math.max(0, offset - count));
+    return createHash('sha256').update(head).update(tail).digest('hex');
+}
+/** Cursors kept per owner and session; older ones are retired first. */
+export const INSPECT_CURSORS_PER_SCOPE = 8;
+export class InspectionReader {
+    now;
+    capacity;
+    ttlMs;
+    perScope;
+    cursors = new Map();
+    constructor(now = Date.now, capacity = 1024, ttlMs = 900000, perScope = INSPECT_CURSORS_PER_SCOPE) {
+        this.now = now;
+        this.capacity = capacity;
+        this.ttlMs = ttlMs;
+        this.perScope = perScope;
+    }
+    async read(path, scope, maxBytes, since) {
+        if (!Number.isInteger(maxBytes) || maxBytes < 1 || maxBytes > INSPECT_MAX_BYTES)
+            throw new Error('Invalid byte budget');
+        const scopeKey = JSON.stringify(scope);
+        const previous = since ? this.cursors.get(since) : undefined;
+        if (since &&
+            (!previous || previous.expiresAt <= this.now() || previous.scope !== scopeKey || previous.path !== path)) {
+            throw new InspectionConflict('Invalid or expired inspection cursor; inspect without since to start again');
+        }
+        const handle = await open(path, 'r');
+        try {
+            const before = await handle.stat();
+            if (!before.isFile())
+                throw new InspectionConflict('Inspection source is not a regular file');
+            const identity = `${before.dev}:${before.ino}:${before.birthtimeMs}`;
+            let offset = previous?.offset ?? Math.max(0, before.size - INSPECT_SCAN_BYTES + 1);
+            if (previous &&
+                (identity !== previous.identity ||
+                    before.size < previous.observedSize ||
+                    (before.size === previous.observedSize &&
+                        (before.mtimeMs !== previous.modifiedAt || before.ctimeMs !== previous.changedAt)) ||
+                    (await anchor(handle, offset)) !== previous.anchor)) {
+                throw new InspectionConflict('Inspection cursor source changed; inspect without since to start again');
+            }
+            let startsAtBoundary = offset === 0;
+            if (!previous && offset > 0) {
+                const preceding = Buffer.alloc(1);
+                await handle.read(preceding, 0, 1, offset - 1);
+                startsAtBoundary = preceding[0] === 10;
+            }
+            const scan = Buffer.alloc(Math.min(INSPECT_SCAN_BYTES - (!previous && offset > 0 ? 1 : 0), Math.max(0, before.size - offset)));
+            const { bytesRead } = await handle.read(scan, 0, scan.length, offset);
+            let selectedStart = 0;
+            let consumed = 0;
+            let blockedReason;
+            let omittedBeforeBytes = 0;
+            if (!previous) {
+                const leading = startsAtBoundary ? 0 : scan.indexOf(10) + 1;
+                const completeEnd = scan.lastIndexOf(10, bytesRead - 1) + 1;
+                if (!startsAtBoundary && leading === 0) {
+                    // The tail lies wholly inside one unfinished oversized record. Its
+                    // beginning is not known: retain the known file boundary rather than
+                    // manufacture a cursor pointing into a JSON/UTF8 fragment.
+                    offset = 0;
+                    blockedReason = 'record-exceeds-scan-limit';
+                }
+                else {
+                    selectedStart = completeEnd;
+                    consumed = completeEnd;
+                    while (selectedStart > leading) {
+                        const recordStart = Math.max(leading, scan.lastIndexOf(10, selectedStart - 2) + 1);
+                        if (completeEnd - recordStart > maxBytes) {
+                            if (selectedStart === completeEnd) {
+                                selectedStart = recordStart;
+                                consumed = recordStart;
+                                blockedReason = 'record-exceeds-output-budget';
+                            }
+                            break;
+                        }
+                        selectedStart = recordStart;
+                    }
+                    if (completeEnd < bytesRead && !blockedReason)
+                        blockedReason = 'partial-record';
+                    // If the only known boundary is the end of a skipped leading row,
+                    // the remainder is a partial record and stays pending there.
+                    if (completeEnd < leading)
+                        selectedStart = consumed = leading;
+                    omittedBeforeBytes = offset + selectedStart;
+                }
+            }
+            else {
+                while (consumed < bytesRead) {
+                    const end = scan.indexOf(10, consumed);
+                    if (end < 0) {
+                        blockedReason = bytesRead === INSPECT_SCAN_BYTES ? 'record-exceeds-scan-limit' : 'partial-record';
+                        break;
+                    }
+                    if (end + 1 > maxBytes) {
+                        if (consumed === 0)
+                            blockedReason = 'record-exceeds-output-budget';
+                        break;
+                    }
+                    consumed = end + 1;
+                }
+            }
+            const evidenceBytes = scan.subarray(selectedStart, consumed);
+            if (!isUtf8(evidenceBytes))
+                throw new InspectionConflict('Inspection source contains invalid UTF8');
+            for (const row of evidenceBytes.toString('utf8').split('\n').slice(0, -1)) {
+                try {
+                    JSON.parse(row);
+                }
+                catch {
+                    throw new InspectionConflict('Inspection source contains invalid JSONL');
+                }
+            }
+            const after = await handle.stat();
+            if (after.size < before.size ||
+                after.ino !== before.ino ||
+                (after.size === before.size && (after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs)))
+                throw new InspectionConflict('Inspection source changed during read');
+            const nextAnchor = await anchor(handle, offset + consumed);
+            const cursor = randomUUID();
+            // No await between capacity enforcement and insertion: concurrent reads
+            // must not all reserve the same remaining slot while hashing anchors.
+            // Each owner and session keeps only its newest cursors, so one agent polling in
+            // a loop retires its own oldest ones instead of pushing every other caller's out
+            // of the shared map. The cursor just used stays among the newest, so a retry of
+            // the last call still works. The global capacity is only a backstop.
+            const holder = JSON.stringify([scope.owner, scope.sessionId]);
+            const mine = [];
+            for (const [key, value] of this.cursors) {
+                if (value.expiresAt <= this.now())
+                    this.cursors.delete(key);
+                else if (value.holder === holder)
+                    mine.push(key);
+            }
+            while (mine.length >= this.perScope)
+                this.cursors.delete(mine.shift());
+            while (this.cursors.size >= this.capacity)
+                this.cursors.delete(this.cursors.keys().next().value);
+            this.cursors.set(cursor, {
+                scope: scopeKey,
+                holder,
+                path,
+                identity,
+                offset: offset + consumed,
+                observedSize: before.size,
+                modifiedAt: before.mtimeMs,
+                changedAt: before.ctimeMs,
+                anchor: nextAnchor,
+                expiresAt: this.now() + this.ttlMs,
+            });
+            return {
+                evidence: evidenceBytes.toString('utf8'),
+                cursor,
+                omittedBeforeBytes,
+                truncated: omittedBeforeBytes > 0 || offset + consumed < before.size,
+                blockedReason,
+                scannedBytes: bytesRead,
+            };
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    clear() {
+        this.cursors.clear();
+    }
+}
+//# sourceMappingURL=agent-inspection.js.map