@noopolis/daimon 0.1.2 → 0.2.1

package/dist/pi/cliTurnMetering.js

@@ -0,0 +1,60 @@
+import { cliChildFailureReason, tagCliChildFailure } from "./cliChildOutput.js";
+import { decodeCodexHeadlessTurn } from "./codexHeadlessResult.js";
+export const createCliTurnMeter = () => {
+    let usage;
+    let completions = 0;
+    return {
+        observeCodexTurnCompleted: (reported) => {
+            completions += 1;
+            if (reported !== undefined)
+                usage = reported;
+        },
+        reported: () => (completions === 1 ? usage : undefined)
+    };
+};
+/**
+ * A turn Codex reported usage for but that the decoder refuses to publish is
+ * still a turn that spent tokens. Tagging the rejection is what lets the
+ * ledger row name why the wake failed instead of matching on message prose.
+ */
+export const decodeCodexTurn = (output) => {
+    try {
+        return decodeCodexHeadlessTurn(output);
+    }
+    catch (error) {
+        throw tagCliChildFailure(error, "turn_rejected");
+    }
+};
+/** The failed row's marker, named by the bound that actually fired. */
+export const failedTurnOutcome = (failure) => ({ status: "failed", reason: cliChildFailureReason(failure) ?? "unknown" });
+/**
+ * Advisory: metering never fails, delays, or rewrites the wake it describes —
+ * the same ordering rule the Grok engine broker states in
+ * `finishBrokerTurnWithUsage`.
+ */
+export const publishTurnUsage = async (sink, usage, outcome) => {
+    if (usage === undefined)
+        return;
+    try {
+        await sink?.(usage, outcome).catch(() => undefined);
+    }
+    catch { /* advisory */ }
+};
+/**
+ * Advisory per-request instrumentation, under the same ordering rule as
+ * {@link publishTurnUsage}: it never fails, delays, or rewrites the wake it
+ * describes.
+ *
+ * No thread id means Codex never announced one — an engine that is not Codex,
+ * a child killed before its first frame, or a future stream that renamed the
+ * event. Nothing is written in that case, because the alternative is guessing
+ * which rollout on disk belongs to this wake.
+ */
+export const publishTurnRequests = async (sink, threadId) => {
+    if (threadId === undefined)
+        return;
+    try {
+        await sink?.(threadId).catch(() => undefined);
+    }
+    catch { /* advisory */ }
+};

package/dist/pi/codexFilesystemRules.d.ts

@@ -0,0 +1,3 @@
+/** Codex mounts deny roots read-only; a second deny below one cannot create parents. */
+export declare function codexFilesystemRules(protectedPaths: readonly string[], readablePaths: readonly string[], workspacePath?: string): Record<string, "read" | "deny">;
+//# sourceMappingURL=codexFilesystemRules.d.ts.map

package/dist/pi/codexFilesystemRules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codexFilesystemRules.d.ts","sourceRoot":"","sources":["../../src/pi/codexFilesystemRules.ts"],"names":[],"mappings":"AAIA,wFAAwF;AACxF,wBAAgB,oBAAoB,CAClC,cAAc,EAAE,SAAS,MAAM,EAAE,EAAE,aAAa,EAAE,SAAS,MAAM,EAAE,EAAE,aAAa,CAAC,EAAE,MAAM,GAC1F,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAqBjC"}

package/dist/pi/codexFilesystemRules.js

@@ -0,0 +1,28 @@
+import path from "node:path";
+/** Codex mounts deny roots read-only; a second deny below one cannot create parents. */
+export function codexFilesystemRules(protectedPaths, readablePaths, workspacePath) {
+    const explicit = new Map();
+    // Agent roots are canonical, but shared acceptance paths may contain `..`
+    // or trailing separators. Compare the same absolute locations Codex uses.
+    for (const readablePath of readablePaths)
+        explicit.set(path.resolve(readablePath), "read");
+    for (const protectedPath of protectedPaths)
+        explicit.set(path.resolve(protectedPath), "deny");
+    const effective = new Map([
+        ...(workspacePath === undefined ? [] : [[path.resolve(workspacePath), "write"]]),
+        ...explicit
+    ]);
+    return Object.fromEntries([...explicit].filter(([target, permission]) => {
+        if (permission !== "deny")
+            return true;
+        let ancestor = path.dirname(target);
+        while (ancestor !== target) {
+            const inherited = effective.get(ancestor);
+            if (inherited !== undefined)
+                return inherited !== "deny";
+            target = ancestor;
+            ancestor = path.dirname(target);
+        }
+        return true;
+    }));
+}

package/dist/pi/codexHeadlessResult.d.ts

@@ -0,0 +1,68 @@
+type JsonRecord = Readonly<Record<string, unknown>>;
+/**
+ * Token accounting for one Codex turn, from the terminal frame emitted by
+ * `codex exec --json`:
+ *
+ *     {"type":"turn.completed","usage":{"input_tokens":…,
+ *       "cached_input_tokens":…,"cache_write_input_tokens":…,
+ *       "output_tokens":…,"reasoning_output_tokens":…}}
+ *
+ * Codex's reconciled session total proves `cached_input_tokens` is a subset of
+ * `input_tokens`: total is `input + output`, unlike AGY's disjoint cache-read
+ * bucket. Adding cacheRead would over-count every cached turn. Likewise,
+ * `reasoning_output_tokens` is a subset of `output_tokens`; it is read only to
+ * validate that relationship, never added. Codex reports cache writes, but no
+ * cost, so `cacheWrite` is measured while `notionalUsd: 0` means absent, not
+ * free. `calls` counts completed command/MCP tools; Codex exposes no AGY-like
+ * model-step count, so this is explicitly a tool-call count.
+ */
+export type CodexTurnUsage = Readonly<{
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    total: number;
+    calls: number;
+    notionalUsd: number;
+    complete: boolean;
+}>;
+export type CodexHeadlessTurn = Readonly<{
+    text: string;
+    usage?: CodexTurnUsage;
+}>;
+/**
+ * Advisory usage decoding: an absent or malformed block is `undefined`, never
+ * a failed published turn and never a zero-filled record. Every field must be
+ * a non-negative safe integer because a substituted zero is byte-identical to
+ * a real zero. `complete` requires a non-zero derived total and valid subset
+ * relationships. As with AGY, every emitted count remains a lower bound.
+ */
+export declare const decodeCodexTurnUsage: (frame: JsonRecord, calls: number) => CodexTurnUsage | undefined;
+/**
+ * Decode Codex's NDJSON stream without mistaking tool/progress items for the
+ * reply. Unknown envelopes and item types are skipped because Codex owns the
+ * vocabulary and a future frame must not fail a turn that published.
+ * A Codex turn that spent subscription money and produced a reply must reach
+ * the organization: uncertainty about accounting degrades to `usage:
+ * undefined` and never discards publishable text. Unlike AGY's stricter
+ * envelope, Codex may omit, repeat, or follow `turn.completed` with another
+ * frame, so only exactly one completion frame supplies trustworthy usage.
+ *
+ * Success is decided from the terminal frame, not from whether a reply was
+ * published: `engineDispatcher.ts`'s runtime envelope tells every agent its
+ * terminal response is a private note to the runtime, not an outward
+ * message, and that it may "leave it empty". A `turn.completed` with no
+ * `agent_message` is therefore a sanctioned silent success — `text: ""`,
+ * never a thrown failure — and its usage still reaches the ledger exactly as
+ * a spoken turn's would; do not reinstate throwing on empty text, it would
+ * both misreport a clean turn as failed and drop its usage from the ledger
+ * silently. Only `turn.failed` with no reply already published, or a stream
+ * with neither terminal frame at all (a truncated or killed child), reject
+ * the turn; the latter gets its own detail string so a genuinely truncated
+ * stream is never confused with a legitimately silent one.
+ */
+export declare const decodeCodexHeadlessTurn: (output: string) => CodexHeadlessTurn;
+/** Text-only view of {@link decodeCodexHeadlessTurn}, for callers that do not meter. */
+export declare const decodeCodexHeadlessResult: (output: string) => string;
+export {};
+//# sourceMappingURL=codexHeadlessResult.d.ts.map

package/dist/pi/codexHeadlessResult.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codexHeadlessResult.d.ts","sourceRoot":"","sources":["../../src/pi/codexHeadlessResult.ts"],"names":[],"mappings":"AAAA,KAAK,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAQpD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,cAAc,CAAA;CAAE,CAAC,CAAC;AA0BnF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAAI,OAAO,UAAU,EAAE,OAAO,MAAM,KAAG,cAAc,GAAG,SAmBxF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,uBAAuB,GAAI,QAAQ,MAAM,KAAG,iBAiCxD,CAAC;AAEF,wFAAwF;AACxF,eAAO,MAAM,yBAAyB,GAAI,QAAQ,MAAM,KAAG,MAA8C,CAAC"}

package/dist/pi/codexHeadlessResult.js

@@ -0,0 +1,122 @@
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const invalidResult = (detail) => new Error(`Codex CLI returned no publishable terminal response: ${detail}`);
+/**
+ * Every field Codex actually emits on `turn.completed.usage`.
+ *
+ * `cache_write_input_tokens` is NOT in this list: Codex 0.142.3 and 0.151.0
+ * both emit exactly `{input_tokens, cached_input_tokens, output_tokens,
+ * reasoning_output_tokens}`, verified against a live turn inside the runtime
+ * image and against `token_count` in a session rollout. Requiring the cache
+ * write field made `decodeCodexTurnUsage` return `undefined` for *every* real
+ * turn, so the codex half of the usage ledger recorded nothing at all while
+ * every test passed against a fixture that invented the field.
+ */
+const USAGE_TOKEN_FIELDS = [
+    "input_tokens",
+    "cached_input_tokens",
+    "output_tokens",
+    "reasoning_output_tokens"
+];
+/** Absent means zero; present-but-malformed still degrades the whole block. */
+const CACHE_WRITE_FIELD = "cache_write_input_tokens";
+const tokenCount = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+/**
+ * Advisory usage decoding: an absent or malformed block is `undefined`, never
+ * a failed published turn and never a zero-filled record. Every field must be
+ * a non-negative safe integer because a substituted zero is byte-identical to
+ * a real zero. `complete` requires a non-zero derived total and valid subset
+ * relationships. As with AGY, every emitted count remains a lower bound.
+ */
+export const decodeCodexTurnUsage = (frame, calls) => {
+    if (!isRecord(frame.usage))
+        return undefined;
+    const usage = frame.usage;
+    const counts = USAGE_TOKEN_FIELDS.map((field) => tokenCount(usage[field]));
+    if (counts.some((count) => count === undefined))
+        return undefined;
+    const cacheWrite = usage[CACHE_WRITE_FIELD] === undefined ? 0 : tokenCount(usage[CACHE_WRITE_FIELD]);
+    if (cacheWrite === undefined)
+        return undefined;
+    const [input, cacheRead, output, reasoningOutput] = counts;
+    const total = input + output;
+    return {
+        input,
+        output,
+        cacheRead,
+        cacheWrite,
+        total,
+        calls,
+        notionalUsd: 0,
+        complete: total > 0 && cacheRead <= input && reasoningOutput <= output
+    };
+};
+/**
+ * Decode Codex's NDJSON stream without mistaking tool/progress items for the
+ * reply. Unknown envelopes and item types are skipped because Codex owns the
+ * vocabulary and a future frame must not fail a turn that published.
+ * A Codex turn that spent subscription money and produced a reply must reach
+ * the organization: uncertainty about accounting degrades to `usage:
+ * undefined` and never discards publishable text. Unlike AGY's stricter
+ * envelope, Codex may omit, repeat, or follow `turn.completed` with another
+ * frame, so only exactly one completion frame supplies trustworthy usage.
+ *
+ * Success is decided from the terminal frame, not from whether a reply was
+ * published: `engineDispatcher.ts`'s runtime envelope tells every agent its
+ * terminal response is a private note to the runtime, not an outward
+ * message, and that it may "leave it empty". A `turn.completed` with no
+ * `agent_message` is therefore a sanctioned silent success — `text: ""`,
+ * never a thrown failure — and its usage still reaches the ledger exactly as
+ * a spoken turn's would; do not reinstate throwing on empty text, it would
+ * both misreport a clean turn as failed and drop its usage from the ledger
+ * silently. Only `turn.failed` with no reply already published, or a stream
+ * with neither terminal frame at all (a truncated or killed child), reject
+ * the turn; the latter gets its own detail string so a genuinely truncated
+ * stream is never confused with a legitimately silent one.
+ */
+export const decodeCodexHeadlessTurn = (output) => {
+    const lines = output.split(/\r?\n/).filter((line) => line.trim().length > 0);
+    if (lines.length === 0)
+        throw invalidResult("empty stream");
+    let text;
+    const completed = [];
+    let failed = false;
+    let calls = 0;
+    for (const line of lines) {
+        let frame;
+        try {
+            frame = JSON.parse(line);
+        }
+        catch {
+            throw invalidResult("invalid JSON");
+        }
+        if (!isRecord(frame) || typeof frame.type !== "string")
+            throw invalidResult("invalid event");
+        if (frame.type === "turn.failed") {
+            failed = true;
+            continue;
+        }
+        if (frame.type === "turn.completed") {
+            completed.push(frame);
+            continue;
+        }
+        if (frame.type !== "item.completed" || !isRecord(frame.item) || typeof frame.item.type !== "string")
+            continue;
+        if (frame.item.type === "command_execution" || frame.item.type === "mcp_tool_call")
+            calls += 1;
+        if (frame.item.type === "agent_message" && typeof frame.item.text === "string" && frame.item.text.trim().length > 0) {
+            text = frame.item.text;
+        }
+    }
+    if (typeof text !== "string") {
+        if (failed)
+            throw invalidResult("failed turn");
+        // No reply, but a completion frame arrived: a sanctioned silent success.
+        if (completed.length === 0)
+            throw invalidResult("no terminal frame");
+        text = "";
+    }
+    const usage = !failed && completed.length === 1 ? decodeCodexTurnUsage(completed[0], calls) : undefined;
+    return usage === undefined ? { text: text.trim() } : { text: text.trim(), usage };
+};
+/** Text-only view of {@link decodeCodexHeadlessTurn}, for callers that do not meter. */
+export const decodeCodexHeadlessResult = (output) => decodeCodexHeadlessTurn(output).text;

package/dist/pi/codexRolloutUsage.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Per-model-request token accounting, recovered from the rollout file Codex
+ * already writes for every non-`--ephemeral` thread.
+ *
+ * Daimon's usage ledger records exactly one row per wake, decoded from the
+ * single `turn.completed` frame on the `--json` stream. That row is a sum: it
+ * cannot say whether a wake's fresh input is one cold miss on a shared prefix
+ * that is then replayed cheaply, or a context that grows with every tool call.
+ * Those two shapes call for opposite optimisations, and the aggregate row is
+ * blind to the difference. It also drops `reasoning_output_tokens` entirely.
+ *
+ * Codex writes the missing detail to
+ * `$CODEX_HOME/sessions/<yyyy>/<mm>/<dd>/rollout-<ts>-<thread-id>.jsonl`, one
+ * usage frame per model request. Two frame shapes carry it, and both were read
+ * off real rollouts written by codex-cli 0.153.4:
+ *
+ *     {"type":"token_usage_record","payload":{"thread_id":…,"turn_id":…,
+ *       "usage":{"input_tokens":22119,"cached_input_tokens":21888,
+ *       "cache_write_input_tokens":0,"output_tokens":358,
+ *       "reasoning_output_tokens":169,"total_tokens":22477}, …}}
+ *
+ *     {"type":"event_msg","payload":{"type":"token_count","info":{
+ *       "last_token_usage":{…same fields…},"total_token_usage":{…}}}}
+ *
+ * `token_usage_record` is preferred because it names its thread and turn. The
+ * `token_count` shape is the fallback for a Codex version that predates it —
+ * the pinned runtime image's version was not available to check. The two are
+ * emitted in pairs, so they are never both counted.
+ *
+ * Reading is strictly advisory and strictly read-only: Codex owns these files,
+ * Daimon never writes, moves, or prunes them.
+ */
+/** One model request's own token usage, exactly as Codex reported it. */
+export type CodexRequestUsage = Readonly<{
+    /** 0-based position of this request within the rollout. */
+    index: number;
+    input: number;
+    cachedInput: number;
+    cacheWrite: number;
+    output: number;
+    reasoning: number;
+    total: number;
+    /**
+     * When the request began and ended, from the rollout's own frame
+     * `timestamp`s. `endedAt` is the usage frame's timestamp (Codex appends it at
+     * `response.completed`); `startedAt` is the first non-usage frame after the
+     * previous request's usage frame — the tool output or turn context that
+     * triggers the next request — falling back to the previous request's end.
+     * Either is absent when the frames carry no valid timestamp: a wake-end stamp
+     * substituted here would be indistinguishable from a measured one.
+     */
+    startedAt?: string;
+    endedAt?: string;
+}>;
+export declare const isCodexThreadId: (value: unknown) => value is string;
+/** Rollouts are model transcripts; refuse to buffer an implausible one. */
+export declare const CODEX_ROLLOUT_MAX_BYTES: number;
+/**
+ * Locate the rollout belonging to *this* turn, by thread id.
+ *
+ * The thread id comes from the `thread.started` frame Codex emits as the very
+ * first line of its own `--json` stream (verified live against codex-cli
+ * 0.153.4: `{"type":"thread.started","thread_id":"01a076d3-…"}`), and the
+ * rollout filename ends with `-<thread-id>.jsonl`. Nothing here globs for "the
+ * newest file": with concurrent agents in one container, newest-file matching
+ * would attribute one agent's requests to another's wake.
+ */
+export declare const findCodexRolloutPath: (codexHome: string, threadId: string) => Promise<string | undefined>;
+/**
+ * Every model request in one rollout, in stream order — or an empty list.
+ *
+ * "Or an empty list" is the whole contract. A rollout that yields no usage
+ * frame, or that contains a usage frame Daimon cannot decode, produces nothing:
+ * a partial or invented row here would be indistinguishable from a real
+ * measurement, and the entire point of this file is to be trusted about which
+ * of two cost shapes production actually has.
+ *
+ * Individual unparseable *lines* are skipped rather than fatal. Codex appends
+ * to this file while the turn runs, so a torn final line is an ordinary
+ * artefact of reading it, not evidence that the accounting is wrong. A usage
+ * frame that parses but whose usage block does not decode is fatal, because
+ * that is a genuine disagreement about the shape of the number.
+ *
+ * Daimon spawns one `codex exec` per wake and never resumes a thread, so one
+ * rollout is one wake. If that ever changes, this needs a turn-id filter.
+ */
+export declare const parseCodexRolloutRequests: (text: string, threadId: string) => readonly CodexRequestUsage[];
+/**
+ * Read one turn's per-request usage. Never throws.
+ *
+ * Absent, unreadable, oversized, or undecodable all answer the same way: an
+ * empty list, which the caller writes nothing for.
+ */
+export declare const readCodexRolloutRequests: (codexHome: string, threadId: string) => Promise<readonly CodexRequestUsage[]>;
+//# sourceMappingURL=codexRolloutUsage.d.ts.map

package/dist/pi/codexRolloutUsage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codexRolloutUsage.d.ts","sourceRoot":"","sources":["../../src/pi/codexRolloutUsage.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,yEAAyE;AACzE,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC,CAAC;AAUH,eAAO,MAAM,eAAe,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MACD,CAAC;AAc1D,2EAA2E;AAC3E,eAAO,MAAM,uBAAuB,QAAmB,CAAC;AAExD;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,GAAU,WAAW,MAAM,EAAE,UAAU,MAAM,KAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAoB1G,CAAC;AAqDF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,yBAAyB,GAAI,MAAM,MAAM,EAAE,UAAU,MAAM,KAAG,SAAS,iBAAiB,EAqCpG,CAAC;AAkBF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,GACnC,WAAW,MAAM,EACjB,UAAU,MAAM,KACf,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAUtC,CAAC"}

package/dist/pi/codexRolloutUsage.js

@@ -0,0 +1,221 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+/**
+ * A thread id is interpolated into a filename suffix, so it is constrained to
+ * the shape Codex actually emits (a UUID) before it can reach the filesystem.
+ * A value carrying `/` or `..` would otherwise steer the search out of
+ * `$CODEX_HOME`.
+ */
+const SAFE_THREAD_ID = /^[A-Za-z0-9][A-Za-z0-9-]{0,63}$/u;
+export const isCodexThreadId = (value) => typeof value === "string" && SAFE_THREAD_ID.test(value);
+/**
+ * Codex lays rollouts out as `sessions/<yyyy>/<mm>/<dd>/rollout-*.jsonl`, so
+ * three directory levels below `sessions` is the whole tree. Directory entries
+ * are walked newest-name-first, which for zero-padded date components is
+ * newest-day-first — the wake that just finished is in the first day directory
+ * examined, so the search normally reads one directory per level.
+ */
+const ROLLOUT_MAX_DEPTH = 3;
+/** A budget so a pathological sessions tree cannot turn instrumentation into a stall. */
+const ROLLOUT_MAX_ENTRIES = 20_000;
+/** Rollouts are model transcripts; refuse to buffer an implausible one. */
+export const CODEX_ROLLOUT_MAX_BYTES = 64 * 1024 * 1024;
+/**
+ * Locate the rollout belonging to *this* turn, by thread id.
+ *
+ * The thread id comes from the `thread.started` frame Codex emits as the very
+ * first line of its own `--json` stream (verified live against codex-cli
+ * 0.153.4: `{"type":"thread.started","thread_id":"01a076d3-…"}`), and the
+ * rollout filename ends with `-<thread-id>.jsonl`. Nothing here globs for "the
+ * newest file": with concurrent agents in one container, newest-file matching
+ * would attribute one agent's requests to another's wake.
+ */
+export const findCodexRolloutPath = async (codexHome, threadId) => {
+    if (!isCodexThreadId(threadId))
+        return undefined;
+    const suffix = `-${threadId}.jsonl`;
+    let budget = ROLLOUT_MAX_ENTRIES;
+    const walk = async (directory, depth) => {
+        let entries;
+        try {
+            entries = await readdir(directory, { withFileTypes: true });
+        }
+        catch {
+            return undefined;
+        }
+        budget -= entries.length;
+        if (budget < 0)
+            return undefined;
+        const match = entries.find((entry) => entry.isFile() && entry.name.startsWith("rollout-") && entry.name.endsWith(suffix));
+        if (match !== undefined)
+            return path.join(directory, match.name);
+        if (depth >= ROLLOUT_MAX_DEPTH)
+            return undefined;
+        const directories = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort().reverse();
+        for (const name of directories) {
+            const found = await walk(path.join(directory, name), depth + 1);
+            if (found !== undefined)
+                return found;
+        }
+        return undefined;
+    };
+    return walk(path.join(codexHome, "sessions"), 0);
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const tokenCount = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+/**
+ * Decode one usage block, or `undefined` when any part of it is not a
+ * non-negative safe integer.
+ *
+ * The rule `turnUsageLedger.ts` and `codexHeadlessResult.ts` already hold to
+ * applies here unchanged: a substituted zero is byte-identical to a real zero,
+ * so a number is never invented. `cache_write_input_tokens` and `total_tokens`
+ * may be absent (older Codex versions omit them); absent means zero and a
+ * derived total respectively, but present-and-malformed still rejects the
+ * block. The subset relationships Codex's own totals imply — cached input
+ * inside input, reasoning output inside output — are checked rather than
+ * assumed, because a block that violates them is not describing the request
+ * this row claims to describe.
+ */
+const decodeRequestUsage = (usage, index) => {
+    if (!isRecord(usage))
+        return undefined;
+    const input = tokenCount(usage.input_tokens);
+    const cachedInput = tokenCount(usage.cached_input_tokens);
+    const output = tokenCount(usage.output_tokens);
+    const reasoning = tokenCount(usage.reasoning_output_tokens);
+    if (input === undefined || cachedInput === undefined || output === undefined || reasoning === undefined)
+        return undefined;
+    const cacheWrite = usage.cache_write_input_tokens === undefined ? 0 : tokenCount(usage.cache_write_input_tokens);
+    const total = usage.total_tokens === undefined ? input + output : tokenCount(usage.total_tokens);
+    if (cacheWrite === undefined || total === undefined)
+        return undefined;
+    if (cachedInput > input || reasoning > output)
+        return undefined;
+    return { index, input, cachedInput, cacheWrite, output, reasoning, total };
+};
+const usageBlock = (frame, threadId) => {
+    const payload = isRecord(frame.payload) ? frame.payload : undefined;
+    if (payload === undefined)
+        return undefined;
+    if (frame.type === "token_usage_record") {
+        // The file is already thread-scoped by its name; the field is checked anyway
+        // so a forked or sub-thread record can never be billed to this wake.
+        if (typeof payload.thread_id === "string" && payload.thread_id !== threadId)
+            return undefined;
+        return { usage: payload.usage };
+    }
+    if (frame.type === "event_msg" && payload.type === "token_count" && isRecord(payload.info)) {
+        return { usage: payload.info.last_token_usage };
+    }
+    return undefined;
+};
+/**
+ * Every model request in one rollout, in stream order — or an empty list.
+ *
+ * "Or an empty list" is the whole contract. A rollout that yields no usage
+ * frame, or that contains a usage frame Daimon cannot decode, produces nothing:
+ * a partial or invented row here would be indistinguishable from a real
+ * measurement, and the entire point of this file is to be trusted about which
+ * of two cost shapes production actually has.
+ *
+ * Individual unparseable *lines* are skipped rather than fatal. Codex appends
+ * to this file while the turn runs, so a torn final line is an ordinary
+ * artefact of reading it, not evidence that the accounting is wrong. A usage
+ * frame that parses but whose usage block does not decode is fatal, because
+ * that is a genuine disagreement about the shape of the number.
+ *
+ * Daimon spawns one `codex exec` per wake and never resumes a thread, so one
+ * rollout is one wake. If that ever changes, this needs a turn-id filter.
+ */
+export const parseCodexRolloutRequests = (text, threadId) => {
+    const requests = [];
+    const fallback = [];
+    let previousFallback = "";
+    const clocks = { record: requestClock(), fallback: requestClock() };
+    for (const line of text.split("\n")) {
+        if (line.trim().length === 0)
+            continue;
+        let frame;
+        try {
+            frame = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!isRecord(frame))
+            continue;
+        const block = usageBlock(frame, threadId);
+        const usageFrame = frame.type === "token_usage_record" || (frame.type === "event_msg" && isRecord(frame.payload) && frame.payload.type === "token_count");
+        if (!usageFrame) {
+            if (frame.type !== "session_meta") {
+                clocks.record.observe(frame.timestamp);
+                clocks.fallback.observe(frame.timestamp);
+            }
+            continue;
+        }
+        if (block === undefined)
+            continue;
+        if (frame.type === "token_usage_record") {
+            const decoded = decodeRequestUsage(block.usage, requests.length);
+            if (decoded === undefined)
+                return [];
+            requests.push({ ...decoded, ...clocks.record.close(frame.timestamp) });
+            continue;
+        }
+        // `token_count` is NOT one frame per request: the captured fixture carries
+        // six of them for four requests, three of which repeat one earlier
+        // `last_token_usage` verbatim because the event is re-emitted whenever the
+        // rate-limit block refreshes. Counting them would inflate the request count
+        // — the single number this whole stream exists to establish. Only a block
+        // that differs from the one before it is a new request.
+        const serialized = JSON.stringify(block.usage);
+        if (serialized === previousFallback)
+            continue;
+        previousFallback = serialized;
+        const decoded = decodeRequestUsage(block.usage, fallback.length);
+        if (decoded === undefined)
+            return [];
+        fallback.push({ ...decoded, ...clocks.fallback.close(frame.timestamp) });
+    }
+    // A Codex version that emits both shapes emits `token_usage_record` once per
+    // request, so the richer one wins outright rather than being merged into a
+    // double count. The fallback exists only for a version that has neither.
+    return requests.length > 0 ? requests : fallback;
+};
+const timestampOf = (value) => typeof value === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?Z$/u.test(value) && !Number.isNaN(Date.parse(value)) ? value : undefined;
+/** Tracks one request stream's start/end stamps; see {@link CodexRequestUsage.startedAt}. */
+const requestClock = () => {
+    let start, previousEnd;
+    return {
+        observe(value) { start ??= timestampOf(value); },
+        close(value) {
+            const endedAt = timestampOf(value), startedAt = start ?? previousEnd;
+            start = undefined;
+            previousEnd = endedAt;
+            return { ...(startedAt === undefined ? {} : { startedAt }), ...(endedAt === undefined ? {} : { endedAt }) };
+        }
+    };
+};
+/**
+ * Read one turn's per-request usage. Never throws.
+ *
+ * Absent, unreadable, oversized, or undecodable all answer the same way: an
+ * empty list, which the caller writes nothing for.
+ */
+export const readCodexRolloutRequests = async (codexHome, threadId) => {
+    const file = await findCodexRolloutPath(codexHome, threadId);
+    if (file === undefined)
+        return [];
+    let text;
+    try {
+        const bytes = await readFile(file);
+        if (bytes.byteLength > CODEX_ROLLOUT_MAX_BYTES)
+            return [];
+        text = bytes.toString("utf8");
+    }
+    catch {
+        return [];
+    }
+    return parseCodexRolloutRequests(text, threadId);
+};

package/dist/pi/engineTaskClock.d.ts

@@ -0,0 +1,9 @@
+/** Explicit set is scoped by the engines to shell/tool children, never provider traffic.
+ * Pin an empty allowlist so ambient include filters cannot discard the clock values.
+ * Sources/versions and the broker contract and AGY gap are recorded in docs/runtime.md.
+ */
+export declare function codexTaskClockArgs(): string[];
+export declare function grokTaskClockConfig(): string;
+/** Operational diagnostic only. Brokered Grok reports from its attested per-turn boundary. */
+export declare function reportEngineTaskClockGap(engine: "codex" | "grok" | "agy"): void;
+//# sourceMappingURL=engineTaskClock.d.ts.map

package/dist/pi/engineTaskClock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engineTaskClock.d.ts","sourceRoot":"","sources":["../../src/pi/engineTaskClock.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,EAAE,CAI7C;AAED,wBAAgB,mBAAmB,IAAI,MAAM,CAG5C;AAMD,8FAA8F;AAC9F,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,IAAI,CAK/E"}

package/dist/pi/engineTaskClock.js

@@ -0,0 +1,28 @@
+import { readTaskClock, taskClockChildEnvironment } from "../runtime/taskClock.js";
+import { shellEnvironmentPolicyEntries } from "../contracts/shellEnvironmentPolicy.js";
+/** Explicit set is scoped by the engines to shell/tool children, never provider traffic.
+ * Pin an empty allowlist so ambient include filters cannot discard the clock values.
+ * Sources/versions and the broker contract and AGY gap are recorded in docs/runtime.md.
+ */
+export function codexTaskClockArgs() {
+    const env = taskClockChildEnvironment();
+    if (Object.keys(env).length === 0)
+        return [];
+    return ["-c", `shell_environment_policy=${shellPolicy(env)}`];
+}
+export function grokTaskClockConfig() {
+    const env = taskClockChildEnvironment();
+    return Object.keys(env).length === 0 ? "" : `shell_environment_policy = ${shellPolicy(env)}\n`;
+}
+function shellPolicy(env) {
+    return `{${shellEnvironmentPolicyEntries(env).join(",")}}`;
+}
+/** Operational diagnostic only. Brokered Grok reports from its attested per-turn boundary. */
+export function reportEngineTaskClockGap(engine) {
+    if (readTaskClock() === undefined)
+        return;
+    const gap = engine === "agy" ? "no supported tool-only environment setting"
+        : undefined; // Brokered Grok reports after config attestation, from its per-turn processClock field.
+    if (gap)
+        console.warn(`daimon: task clock coverage gap engine=${engine}: ${gap}; native tools remain on real time; wake allowed`);
+}