spawnfile 0.1.13 → 0.1.17

package/dist/runtime/usageLedger.js

@@ -0,0 +1,269 @@
+/**
+ * Pure reader/aggregator for Daimon's per-turn usage ledger
+ * (`noopolis.daimon.turn-usage.v1`, see `specs/USAGE_ACCOUNTING_DESIGN.md`). This
+ * module never touches Docker, the filesystem, or a deployment record — it
+ * only knows how to parse ledger text and window/group already-parsed
+ * records. The transport (deciding whether to `docker exec` or fall back to
+ * volume egress, and where the ledger actually lives) is a CLI-layer concern
+ * in `src/cli/usageCommandLive.ts`, which composes this module with
+ * `src/deployment`'s docker probe gateway and volume-egress helpers. Keeping
+ * that composition out of this folder avoids a value-level import cycle:
+ * `src/deployment` already imports real (non-type) exports from this folder
+ * (`dockerManager.ts`'s `resolveNoopolisRunId`), so this folder must not
+ * import real exports back from `src/deployment`.
+ *
+ * The read transport itself (`readUsageLedgerViaExec`, and the rule for when
+ * a failed `cat` means "empty" versus "unknown") lives beside this file in
+ * `usageLedgerRead.ts`, so this module performs no I/O at all.
+ */
+export const USAGE_TURN_RECORD_VERSION = "noopolis.daimon.turn-usage.v1";
+export const USAGE_LIMIT_REASONS = ["tokens", "requests", "timeout", "none"];
+const USAGE_MODELS = ["grok-4.6", "grok-4.5", "grok-build"];
+/**
+ * The additive broker fields of a `turn-usage.v1` row. Each is copied only when
+ * it is a member of Daimon's closed vocabulary; a malformed optional field is
+ * dropped rather than discarding the row's spend.
+ */
+const brokerFields = (record) => ({
+    ...(typeof record.turn === "string" && /^[a-f0-9]{64}$/u.test(record.turn) ? { turn: record.turn } : {}),
+    ...(USAGE_LIMIT_REASONS.includes(record.limit_reason) ? { limit_reason: record.limit_reason } : {}),
+    ...(USAGE_MODELS.includes(record.model) ? { model: record.model } : {}),
+    ...(Number.isSafeInteger(record.estimated_requests) && record.estimated_requests > 0 ? { estimated_requests: record.estimated_requests } : {}),
+    ...(record.outcome === "completed" || record.outcome === "failed" ? { outcome: record.outcome } : {})
+});
+/**
+ * Keeps the first row of every `turn` and every row without one.
+ *
+ * Daimon's broker seals a turn's ledger bytes into the turn record and appends
+ * them again on replay when it cannot see the row, so two replays of one sealed
+ * turn can both append identical bytes. The key exists precisely so such a turn
+ * is never counted twice; every aggregate here must see deduplicated rows.
+ * Readers keep every parsed row so {@link findConflictingUsageTurns} can see
+ * rows that share a key but differ.
+ */
+export const dedupeUsageRecordsByTurn = (records) => {
+    const seen = new Set();
+    return records.filter((record) => {
+        if (record.turn === undefined)
+            return true;
+        if (seen.has(record.turn))
+            return false;
+        seen.add(record.turn);
+        return true;
+    });
+};
+const canonicalRecord = (record) => JSON.stringify(Object.keys(record).sort().map((key) => [key, record[key]]));
+/**
+ * `turn` keys whose rows are not byte-for-byte the same record. A replay
+ * re-appends identical sealed bytes, so differing rows under one key mean the
+ * ledger is not what the broker sealed; the first row is still the one counted,
+ * but the window is reported PARTIAL and the keys are named.
+ */
+export const findConflictingUsageTurns = (records) => {
+    const first = new Map();
+    const conflicts = new Set();
+    for (const record of records) {
+        if (record.turn === undefined)
+            continue;
+        const canonical = canonicalRecord(record);
+        const seen = first.get(record.turn);
+        if (seen === undefined)
+            first.set(record.turn, canonical);
+        else if (seen !== canonical)
+            conflicts.add(record.turn);
+    }
+    return [...conflicts].sort();
+};
+const NUMERIC_FIELDS = [
+    "input",
+    "output",
+    "cache_read",
+    "cache_write",
+    "total",
+    "calls",
+    "notional_usd"
+];
+const isFiniteNonNegative = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0;
+const isNonEmptyString = (value) => typeof value === "string" && value.length > 0;
+/**
+ * Parses one ledger line. Returns `null` (never throws) for: blank lines,
+ * JSON that fails to parse (this is also how a torn trailing line left by a
+ * crash mid-append is skipped — a truncated JSON object fails to parse the
+ * same way a garbled line would), a schema version other than
+ * `noopolis.daimon.turn-usage.v1`, a missing/empty string field, an `at` that
+ * doesn't parse as a date, a non-boolean `complete`, or any numeric field
+ * that isn't a finite, non-negative number.
+ */
+export const parseUsageLedgerLine = (line) => {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return null;
+    }
+    const record = parsed;
+    if (record.v !== USAGE_TURN_RECORD_VERSION) {
+        return null;
+    }
+    if (!isNonEmptyString(record.agent)
+        || !isNonEmptyString(record.wake)
+        || !isNonEmptyString(record.engine)
+        || !isNonEmptyString(record.at)) {
+        return null;
+    }
+    if (Number.isNaN(Date.parse(record.at))) {
+        return null;
+    }
+    if (typeof record.complete !== "boolean") {
+        return null;
+    }
+    for (const field of NUMERIC_FIELDS) {
+        if (!isFiniteNonNegative(record[field])) {
+            return null;
+        }
+    }
+    return {
+        agent: record.agent,
+        at: record.at,
+        cache_read: record.cache_read,
+        cache_write: record.cache_write,
+        calls: record.calls,
+        complete: record.complete,
+        engine: record.engine,
+        input: record.input,
+        notional_usd: record.notional_usd,
+        output: record.output,
+        total: record.total,
+        v: USAGE_TURN_RECORD_VERSION,
+        wake: record.wake,
+        ...brokerFields(record)
+    };
+};
+/**
+ * Parses a newline-delimited ledger file. Never throws: an unparseable line —
+ * including an unterminated trailing line left by a crash mid-append — is
+ * skipped, and the rest of the file still parses.
+ */
+export const parseUsageLedger = (text) => text
+    .split("\n")
+    .map(parseUsageLedgerLine)
+    .filter((record) => record !== null);
+const DURATION_UNIT_MS = {
+    d: 24 * 60 * 60 * 1000,
+    h: 60 * 60 * 1000,
+    m: 60 * 1000
+};
+/** The default window `spawnfile usage` uses when `--since` is omitted. */
+export const DEFAULT_USAGE_SINCE = "24h";
+/** Parses a duration like `"24h"`, `"7d"`, or `"30m"` into milliseconds.
+ * Returns `null` for anything else — the caller is responsible for turning
+ * that into a user-facing input error. */
+export const parseUsageSinceDuration = (input) => {
+    const match = /^(\d+)(h|d|m)$/u.exec(input.trim());
+    if (!match) {
+        return null;
+    }
+    const amount = Number(match[1]);
+    const unit = match[2];
+    return amount * DURATION_UNIT_MS[unit];
+};
+/** Keeps only records at or after `now - sinceMs`. `now` defaults to the real
+ * clock; tests pass a fixed value. */
+export const filterUsageRecordsSince = (records, sinceMs, now = Date.now()) => {
+    const cutoff = now - sinceMs;
+    return records.filter((record) => Date.parse(record.at) >= cutoff);
+};
+const emptyAgentGroup = (agent, engine) => ({
+    agent,
+    engine,
+    estimatedRequests: 0,
+    estimatedTurns: 0,
+    incompleteTurns: 0,
+    notionalUsd: 0,
+    tokens: 0,
+    turns: 0
+});
+/** Groups records by agent. `roster`, when supplied, seeds a zero-usage row
+ * for every known agent (so an uninstrumented engine's agents still show up
+ * with dashes instead of vanishing from the table). */
+export const groupUsageByAgent = (records, roster = []) => {
+    const byAgent = new Map();
+    for (const entry of roster) {
+        byAgent.set(entry.agent, emptyAgentGroup(entry.agent, entry.engine));
+    }
+    for (const record of dedupeUsageRecordsByTurn(records)) {
+        const existing = byAgent.get(record.agent) ?? emptyAgentGroup(record.agent, record.engine);
+        existing.turns += 1;
+        existing.estimatedRequests += record.estimated_requests ?? 0;
+        if (record.estimated_requests !== undefined)
+            existing.estimatedTurns += 1;
+        existing.tokens += record.total;
+        existing.notionalUsd += record.notional_usd;
+        if (!record.complete) {
+            existing.incompleteTurns += 1;
+        }
+        if (existing.engine === null) {
+            existing.engine = record.engine;
+        }
+        byAgent.set(record.agent, existing);
+    }
+    return [...byAgent.values()];
+};
+const emptyEngineGroup = (engine) => ({
+    engine,
+    estimatedRequests: 0,
+    estimatedTurns: 0,
+    incompleteTurns: 0,
+    notionalUsd: 0,
+    tokens: 0,
+    turns: 0
+});
+/** Groups records by engine. `engines`, when supplied, seeds a zero-usage row
+ * for every known engine (so Codex — uninstrumented — shows up as a dashed
+ * row rather than being absent from the rollup). */
+export const groupUsageByEngine = (records, engines = []) => {
+    const byEngine = new Map();
+    for (const engine of engines) {
+        byEngine.set(engine, emptyEngineGroup(engine));
+    }
+    for (const record of dedupeUsageRecordsByTurn(records)) {
+        const existing = byEngine.get(record.engine) ?? emptyEngineGroup(record.engine);
+        existing.turns += 1;
+        existing.estimatedRequests += record.estimated_requests ?? 0;
+        if (record.estimated_requests !== undefined)
+            existing.estimatedTurns += 1;
+        existing.tokens += record.total;
+        existing.notionalUsd += record.notional_usd;
+        if (!record.complete) {
+            existing.incompleteTurns += 1;
+        }
+        byEngine.set(record.engine, existing);
+    }
+    return [...byEngine.values()];
+};
+/** Coverage is computed against `totalAgents` (the full org roster size), not
+ * against however many distinct agents happen to appear in `records` — an
+ * uninstrumented engine's agents must count toward the shortfall, not
+ * disappear from the denominator. */
+export const computeUsageCoverage = (records, totalAgents, unreadableUnitCount = 0) => {
+    const unique = dedupeUsageRecordsByTurn(records);
+    const reporting = new Set(unique.map((record) => record.agent)).size;
+    const conflictingTurnCount = findConflictingUsageTurns(records).length;
+    return {
+        agentsReporting: reporting,
+        agentsTotal: totalAgents,
+        conflictingTurnCount,
+        estimatedTurnCount: unique.filter((record) => record.estimated_requests !== undefined).length,
+        incompleteRecordCount: unique.filter((record) => !record.complete).length,
+        partial: reporting < totalAgents || unreadableUnitCount > 0 || conflictingTurnCount > 0,
+        unreadableUnitCount
+    };
+};

package/dist/runtime/usageLedgerRead.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Transport half of Daimon's per-turn usage ledger reader
+ * (`noopolis.daimon.turn-usage.v1`, see `specs/USAGE_ACCOUNTING_DESIGN.md`). Split
+ * out of `usageLedger.ts` so that file stays a pure parser/aggregator and this
+ * one owns the single I/O-shaped concern: `cat` two ledger generations through
+ * a caller-supplied `exec` and decide, per generation, whether a failed read
+ * means "empty" or "unknown".
+ *
+ * `exec` is duck-typed (structurally the same shape as
+ * `RuntimeProbeGateway.exec` in `./types.ts`) rather than a concrete gateway,
+ * so this module never depends on `src/deployment` — which already imports
+ * real exports from this folder, and so must not be imported back.
+ */
+import { type UsageRecord } from "./usageLedger.js";
+/** The exec shape this module needs to read a ledger — structurally the same
+ * as `RuntimeProbeGateway.exec` (`./types.ts`), duck-typed here rather than
+ * imported so this module never depends on a concrete gateway construction
+ * path. */
+export type UsageLedgerExec = (command: string[]) => Promise<{
+    stderr: string;
+    stdout: string;
+}>;
+export interface UsageLedgerPaths {
+    filePath: string;
+    rotatedFilePath: string;
+}
+/** One ledger generation that exists but could not be read. Never merged into
+ * the record stream and never rendered as zero usage: the caller must surface
+ * it so an unknown window is not mistaken for a cheap one. */
+export interface UsageLedgerReadFailure {
+    filePath: string;
+    reason: string;
+}
+export interface UsageLedgerRead {
+    records: UsageRecord[];
+    unreadable: UsageLedgerReadFailure[];
+}
+/**
+ * Reads both ledger generations (`usage.jsonl` and `usage.jsonl.1`) through
+ * `exec` and parses them. Rotated (older) records are returned before
+ * current ones so a `--since` window spanning a rotation reads in
+ * chronological order.
+ *
+ * Generations that could not be read come back in `unreadable` rather than as
+ * missing records, so the caller can render an UNREADABLE row and mark the
+ * window partial instead of reporting an unknown amount of usage as zero.
+ */
+export declare const readUsageLedgerViaExec: (exec: UsageLedgerExec, paths: UsageLedgerPaths) => Promise<UsageLedgerRead>;

package/dist/runtime/usageLedgerRead.js

@@ -0,0 +1,102 @@
+/**
+ * Transport half of Daimon's per-turn usage ledger reader
+ * (`noopolis.daimon.turn-usage.v1`, see `specs/USAGE_ACCOUNTING_DESIGN.md`). Split
+ * out of `usageLedger.ts` so that file stays a pure parser/aggregator and this
+ * one owns the single I/O-shaped concern: `cat` two ledger generations through
+ * a caller-supplied `exec` and decide, per generation, whether a failed read
+ * means "empty" or "unknown".
+ *
+ * `exec` is duck-typed (structurally the same shape as
+ * `RuntimeProbeGateway.exec` in `./types.ts`) rather than a concrete gateway,
+ * so this module never depends on `src/deployment` — which already imports
+ * real exports from this folder, and so must not be imported back.
+ */
+import { parseUsageLedger } from "./usageLedger.js";
+/** Same redaction discipline as the docker probe gateway's own failure
+ * summaries — written here rather than imported because this module must not
+ * depend on `src/deployment` (see the module doc). */
+const boundedReadFailure = (error) => {
+    const text = (() => {
+        if (error && typeof error === "object") {
+            const candidate = error;
+            if (typeof candidate.stderr === "string" && candidate.stderr.trim().length > 0) {
+                return candidate.stderr;
+            }
+            if (typeof candidate.message === "string")
+                return candidate.message;
+        }
+        return String(error);
+    })();
+    return text
+        .replace(/\s+/gu, " ")
+        .replace(/(bearer|token|password|passwd|secret|authorization)[=: ]+(?:bearer[ ]+)?[^ ]+/giu, "$1=[redacted]")
+        .replace(/https?:\/\/[^ ]+/giu, "[url redacted]")
+        .trim()
+        .slice(0, 240) || "ledger read failed";
+};
+/**
+ * True only for the one failure that legitimately means "there is nothing
+ * here": the file does not exist. That is the normal state of
+ * `usage.jsonl.1` before the first rotation, and of `usage.jsonl` before the
+ * first turn ever completes, so it must stay silent.
+ *
+ * Everything else — a `maxBuffer` overrun on a rotated generation, the read
+ * timing out, the daemon being unreachable, the container having gone away —
+ * is an UNKNOWN number of turns, and reporting it as zero is exactly the
+ * silent data loss `spawnfile usage` exists to prevent. A killed or
+ * string-coded failure is never read as absence no matter what text it
+ * carries, because a truncated or aborted read can still have emitted
+ * unrelated stderr.
+ */
+const isAbsentLedgerFile = (error) => {
+    if (!error || typeof error !== "object")
+        return false;
+    const candidate = error;
+    if (candidate.killed === true || (candidate.signal !== undefined && candidate.signal !== null)) {
+        return false;
+    }
+    // Node reports spawn/stream failures with a string `code`
+    // (`ERR_CHILD_PROCESS_STDIO_MAXBUFFER`, or `ENOENT` for a missing docker
+    // binary); a plain non-zero `cat` exit carries a numeric one.
+    if (typeof candidate.code === "string")
+        return false;
+    const stderr = typeof candidate.stderr === "string" ? candidate.stderr : "";
+    const message = typeof candidate.message === "string" ? candidate.message : "";
+    return /no such file or directory/iu.test(`${stderr}\n${message}`);
+};
+/** `cat`s one generation through `exec`. A genuinely absent file reads as
+ * empty; every other failure is reported, never swallowed. */
+const readLedgerGeneration = async (exec, filePath) => {
+    try {
+        const result = await exec(["cat", filePath]);
+        return { text: result.stdout };
+    }
+    catch (error) {
+        if (isAbsentLedgerFile(error))
+            return { text: "" };
+        return { failure: { filePath, reason: boundedReadFailure(error) }, text: "" };
+    }
+};
+/**
+ * Reads both ledger generations (`usage.jsonl` and `usage.jsonl.1`) through
+ * `exec` and parses them. Rotated (older) records are returned before
+ * current ones so a `--since` window spanning a rotation reads in
+ * chronological order.
+ *
+ * Generations that could not be read come back in `unreadable` rather than as
+ * missing records, so the caller can render an UNREADABLE row and mark the
+ * window partial instead of reporting an unknown amount of usage as zero.
+ */
+export const readUsageLedgerViaExec = async (exec, paths) => {
+    const [rotated, primary] = await Promise.all([
+        readLedgerGeneration(exec, paths.rotatedFilePath),
+        readLedgerGeneration(exec, paths.filePath)
+    ]);
+    return {
+        // Every row is kept, across both generations: aggregates dedupe by `turn`
+        // (a replay can re-append after a rotation) and coverage reports rows that
+        // share a key but differ.
+        records: [...parseUsageLedger(rotated.text), ...parseUsageLedger(primary.text)],
+        unreadable: [rotated.failure, primary.failure].filter((failure) => failure !== undefined)
+    };
+};

package/dist/runtime/usageRequestLedger.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Pure parser for Daimon's per-model-request stream
+ * (`noopolis.daimon.turn-requests.v1`, `requests.jsonl` beside the usage
+ * ledger). Codex rows carry a `thread`; Grok broker rows carry the broker
+ * `turn`, the declared `model`, and `usage_source` (`stream`, `upstream`, or
+ * `estimated` — a conservative charge for a response without valid usage).
+ * Either may carry proxy- or rollout-measured `started_at`/`ended_at`, absent
+ * rather than substituted when not measured. No I/O happens here.
+ */
+export declare const USAGE_REQUEST_RECORD_VERSION: "noopolis.daimon.turn-requests.v1";
+export declare const USAGE_REQUEST_SOURCES: readonly ["stream", "upstream", "estimated"];
+export type UsageRequestSource = typeof USAGE_REQUEST_SOURCES[number];
+export interface UsageRequestRecord {
+    agent: string;
+    at: string;
+    cache_write: number;
+    cached_input: number;
+    ended_at?: string;
+    engine: string;
+    fresh_input: number;
+    input: number;
+    model?: string;
+    output: number;
+    reasoning?: number;
+    request: number;
+    requests: number;
+    started_at?: string;
+    thread?: string;
+    total: number;
+    turn?: string;
+    usage_source?: UsageRequestSource;
+    v: typeof USAGE_REQUEST_RECORD_VERSION;
+    wake: string;
+}
+/** One row, or `null` for a blank, torn, foreign-version, or malformed line. Never throws. */
+export declare const parseUsageRequestLedgerLine: (line: string) => UsageRequestRecord | null;
+/**
+ * Parses a whole stream, keeping the first row of each broker `(turn, request)`
+ * pair: a replayed broker turn re-appends its sealed request rows exactly as it
+ * re-appends its usage row.
+ */
+export declare const parseUsageRequestLedger: (content: string) => UsageRequestRecord[];

package/dist/runtime/usageRequestLedger.js

@@ -0,0 +1,72 @@
+/**
+ * Pure parser for Daimon's per-model-request stream
+ * (`noopolis.daimon.turn-requests.v1`, `requests.jsonl` beside the usage
+ * ledger). Codex rows carry a `thread`; Grok broker rows carry the broker
+ * `turn`, the declared `model`, and `usage_source` (`stream`, `upstream`, or
+ * `estimated` — a conservative charge for a response without valid usage).
+ * Either may carry proxy- or rollout-measured `started_at`/`ended_at`, absent
+ * rather than substituted when not measured. No I/O happens here.
+ */
+export const USAGE_REQUEST_RECORD_VERSION = "noopolis.daimon.turn-requests.v1";
+export const USAGE_REQUEST_SOURCES = ["stream", "upstream", "estimated"];
+const TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?Z$/u;
+const COUNTS = ["input", "cached_input", "fresh_input", "cache_write", "output", "total"];
+const nonNegative = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0;
+const text = (value) => typeof value === "string" && value.length > 0;
+/** One row, or `null` for a blank, torn, foreign-version, or malformed line. Never throws. */
+export const parseUsageRequestLedgerLine = (line) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(line.trim());
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return null;
+    const row = parsed;
+    if (row.v !== USAGE_REQUEST_RECORD_VERSION || !text(row.agent) || !text(row.wake) || !text(row.engine) || !text(row.at) || Number.isNaN(Date.parse(row.at)))
+        return null;
+    if (!Number.isSafeInteger(row.request) || !Number.isSafeInteger(row.requests) || row.request < 0 || row.requests < 1)
+        return null;
+    if (COUNTS.some((field) => !nonNegative(row[field])))
+        return null;
+    if ((row.started_at !== undefined && !(text(row.started_at) && TIMESTAMP.test(row.started_at)))
+        || (row.ended_at !== undefined && !(text(row.ended_at) && TIMESTAMP.test(row.ended_at)))
+        || (row.usage_source !== undefined && !USAGE_REQUEST_SOURCES.includes(row.usage_source))
+        || (row.turn !== undefined && !(typeof row.turn === "string" && /^[a-f0-9]{64}$/u.test(row.turn)))
+        || (row.reasoning !== undefined && !nonNegative(row.reasoning)))
+        return null;
+    return {
+        agent: row.agent, at: row.at, cache_write: row.cache_write, cached_input: row.cached_input,
+        engine: row.engine, fresh_input: row.fresh_input, input: row.input, output: row.output,
+        request: row.request, requests: row.requests, total: row.total,
+        v: USAGE_REQUEST_RECORD_VERSION, wake: row.wake,
+        ...(row.started_at === undefined ? {} : { started_at: row.started_at }),
+        ...(row.ended_at === undefined ? {} : { ended_at: row.ended_at }),
+        ...(text(row.model) ? { model: row.model } : {}),
+        ...(row.reasoning === undefined ? {} : { reasoning: row.reasoning }),
+        ...(text(row.thread) ? { thread: row.thread } : {}),
+        ...(row.turn === undefined ? {} : { turn: row.turn }),
+        ...(row.usage_source === undefined ? {} : { usage_source: row.usage_source })
+    };
+};
+/**
+ * Parses a whole stream, keeping the first row of each broker `(turn, request)`
+ * pair: a replayed broker turn re-appends its sealed request rows exactly as it
+ * re-appends its usage row.
+ */
+export const parseUsageRequestLedger = (content) => {
+    const seen = new Set();
+    return content.split("\n").map(parseUsageRequestLedgerLine).filter((row) => {
+        if (row === null)
+            return false;
+        if (row.turn === undefined)
+            return true;
+        const key = `${row.turn}:${row.request}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+};

package/dist/shared/daimonCodexDocker.d.ts

@@ -0,0 +1,32 @@
+export declare const DAIMON_DOCKER_RUNTIME_SECURITY_ARGS: readonly ["--cap-drop=ALL", "--cap-add=CHOWN", "--cap-add=SETUID", "--cap-add=SETGID", "--cap-add=DAC_READ_SEARCH", "--cap-add=SETPCAP", "--cap-add=KILL", "--security-opt=no-new-privileges:true"];
+export declare const DAIMON_CODEX_NATIVE_SANDBOX_DOCKER_SECURITY_OPTS: readonly ["--security-opt=seccomp=unconfined", "--security-opt=apparmor=unconfined"];
+export interface DaimonEngineDockerInterop {
+    /** A strict Codex agent needs seccomp and AppArmor fully unconfined for its own bubblewrap sandbox. */
+    codex: boolean;
+    /** A brokered Grok worker needs bubblewrap's namespace syscalls: the pinned seccomp profile plus AppArmor unconfined. */
+    grok: boolean;
+}
+export declare const resolveDaimonEngineDockerInterop: (source: string) => DaimonEngineDockerInterop;
+export declare const configRequiresCodexNativeSandboxDockerInterop: (source: string) => boolean;
+export declare const DAIMON_GROK_HOST_USERNS_PREREQUISITE: "kernel.apparmor_restrict_unprivileged_userns=0";
+/**
+ * Writes the pinned Grok seccomp profile into `directory` (content-addressed,
+ * verified after writing) and returns its absolute path. Docker reads a
+ * `seccomp=<file>` option on the client at `docker run` and stores the profile
+ * in the container config, so the file only has to exist for that call.
+ */
+export declare const materializeDaimonGrokSeccompProfile: (directory: string) => Promise<string>;
+/**
+ * Docker security options for a Daimon container, by the engines its configs run.
+ *
+ * Codex's strict native sandbox needs seccomp and AppArmor fully unconfined, and
+ * that superset also lets Grok's bubblewrap run, so it wins whenever a strict
+ * Codex agent is present. Otherwise a Grok agent gets Docker's default seccomp
+ * profile plus bubblewrap's seven namespace syscalls (pinned bytes) and AppArmor
+ * unconfined — the narrowest combination under which Grok 1.0.34 starts. Grok
+ * additionally needs the Docker host to allow unprivileged user namespaces
+ * (`kernel.apparmor_restrict_unprivileged_userns=0`); the container entrypoint
+ * checks that before the broker starts.
+ */
+export declare const daimonEngineDockerSecurityArgsForConfigs: (sources: string[], grokSeccompProfilePath: () => Promise<string>) => Promise<string[]>;
+export declare const codexNativeSandboxDockerSecurityArgsForConfigs: (sources: string[]) => string[];