@manyoars/oars 0.4.1 → 0.5.2

package/dist/sessions/machine-stop.d.ts

@@ -0,0 +1,22 @@
+import type { SenderSpawn } from './pool-due.js';
+export type MachineStopResult = 'not-machine' | 'no-input' | 'started' | 'failed';
+export interface MachineStopDeps {
+    env: {
+        [name: string]: string | undefined;
+    };
+    /** The hook's stdin text. */
+    stdin: string;
+    /** The `hook-bin.js` that is running: the child is the same file with `machine-child`. */
+    hookBin: string;
+    /** The child's working folder, the home folder, so it never holds the session's repository open. */
+    home: string;
+    /** The session store, where the notice file is. */
+    storeDir: string;
+    /** The hook's stdout. */
+    write: (text: string) => void;
+    spawn: SenderSpawn;
+}
+/** What the child needs of the hook's input: the session, its transcript, and the folder it ran in. The rest of the input (a long last message, say) never goes onto a command line. `undefined` when it has no session or no transcript. */
+export declare const forwardedInput: (stdin: string) => string | undefined;
+/** Never throws: a hook that cannot start its child must not fail the session. A child that cannot start later (its `error` event) is dropped; the next Stop builds the same batch. */
+export declare const machineStop: (deps: MachineStopDeps) => MachineStopResult;

package/dist/sessions/machine-stop.js

@@ -0,0 +1,53 @@
+// The Stop of a machine (a cloud VM, a VPS, a self-hosted runner): `oars-hook stop --machine`. The hook's own body does one thing, it starts a detached child with its output redirected and returns, so the
+// harness is never held by a capture, a settle wait, or a build; every one of those runs in the child (`machine-child.ts`). The gate is `OARS_HOST_CLASS` (`machineOf`): on a laptop, or anywhere the variable is not set to a
+// machine class, this does nothing and starts nothing. Before it starts the child it reads the notice file (`machine-notice.ts`) the last child may have left and prints it once as the hook's `systemMessage`.
+// It imports no store module, so the hook's cost is the node start plus this.
+import { machineOf } from './machine.js';
+import { takeNotice } from './machine-notice.js';
+const text = (value) => (typeof value === 'string' && value !== '' ? value : undefined);
+/** What the child needs of the hook's input: the session, its transcript, and the folder it ran in. The rest of the input (a long last message, say) never goes onto a command line. `undefined` when it has no session or no transcript. */
+export const forwardedInput = (stdin) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdin);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    const session = text(Reflect.get(parsed, 'session_id'));
+    const transcript = text(Reflect.get(parsed, 'transcript_path'));
+    if (session === undefined || transcript === undefined)
+        return undefined;
+    return JSON.stringify({ session_id: session, transcript_path: transcript, cwd: text(Reflect.get(parsed, 'cwd')) });
+};
+/** The notice the last child left, printed once as one `systemMessage` and cleared, so it is shown by the next Stop and not again. A notice that cannot be read or printed is dropped: the condition, still true, is written again by the next child. */
+const announce = (deps) => {
+    try {
+        const notice = takeNotice(deps.storeDir);
+        if (notice !== undefined)
+            deps.write(JSON.stringify({ systemMessage: notice }));
+    }
+    catch {
+        // A hook never fails the session over a message.
+    }
+};
+/** Never throws: a hook that cannot start its child must not fail the session. A child that cannot start later (its `error` event) is dropped; the next Stop builds the same batch. */
+export const machineStop = (deps) => {
+    if (machineOf(deps.env) === undefined)
+        return 'not-machine';
+    announce(deps);
+    const input = forwardedInput(deps.stdin);
+    if (input === undefined)
+        return 'no-input';
+    try {
+        const child = deps.spawn(process.execPath, [deps.hookBin, 'machine-child', input], { detached: true, stdio: 'ignore', windowsHide: true, cwd: deps.home });
+        child.on('error', () => undefined);
+        child.unref();
+        return 'started';
+    }
+    catch {
+        return 'failed';
+    }
+};

package/dist/sessions/machine.d.ts

@@ -0,0 +1,41 @@
+/** Where a session runs: `local` is every ordinary machine and the only class that is not a machine here. */
+export declare const HOST_CLASSES: readonly ["local", "vps", "cloud", "ci", "hosted"];
+export type HostClass = (typeof HOST_CLASSES)[number];
+export type MachineClass = Exclude<HostClass, 'local'>;
+/** Every variable of the enrollment block; an install writes these and refuses any other name, so a typo is never silently dropped. */
+export declare const ENROLLMENT_NAMES: readonly ["OARS_HOST_CLASS", "OARS_LAUNCHER", "OARS_MACHINE", "OARS_ALLOW_REPOS", "OARS_REPO_SALT", "OARS_SESSION_SALT", "OARS_EXCLUSION_TERMS", "OARS_EXCLUSION_TERMS_INLINE"];
+export interface MachineConfig {
+    hostClass: MachineClass;
+    /** `OARS_LAUNCHER`, as the enrollment printed it; absent when unset. */
+    launcher: string | undefined;
+    /** `OARS_MACHINE`, the opaque id minted at enrollment; absent when unset. */
+    machine: string | undefined;
+    /** `OARS_SESSION_SALT`: the key of a session's skeleton `id` and of the terms digest; absent when unset. */
+    sessionSalt: string | undefined;
+    /** `CLAUDE_CODE_REMOTE_SESSION_ID`: the cloud's own name for the session; absent when unset. */
+    remoteSession: string | undefined;
+    /** `OARS_ALLOW_REPOS` split on commas and whitespace, lowercased; empty means no repository is allowed. */
+    allowRepos: string[];
+}
+/** The machine configuration in `env`, or `undefined` for a local runtime (no `OARS_HOST_CLASS`, `local`, or a value that is not a class). A value that is not a class is not a machine: nothing is built. */
+export declare const machineOf: (env: {
+    [name: string]: string | undefined;
+}) => MachineConfig | undefined;
+/**
+ * The `env` entries a user-scope machine install writes, from the `NAME=value` pairs of `--env`. `OARS_HOST_CLASS` is required and is the gate, so it must be a class other than `local`. With
+ * `--terms-file`, the inline terms go to that file (owner-only) and `OARS_EXCLUSION_TERMS` names it, so the settings file holds no term. Nothing is written until every pair is valid.
+ */
+export declare const enrollmentOf: (pairs: readonly string[], termsFile: string | undefined, cwd: string) => Promise<{
+    env: {
+        [name: string]: string;
+    };
+    termsPath: string | undefined;
+}>;
+/** Where a machine's child keeps the terms it was given in `OARS_EXCLUSION_TERMS_INLINE`: in the store, owner-only. */
+export declare const inlineTermsFile: (storeDir: string) => string;
+/**
+ * A machine whose enrollment put the exclusion terms in one variable (a cloud environment has no file to point at) gets them written, owner-only, into its store at every Stop, with `OARS_EXCLUSION_TERMS` pointed at that file, so the
+ * file is always the variable's current value. The inline terms win over a file named by `OARS_EXCLUSION_TERMS`, because the enrollment is where the operator stated them. With no inline terms (unset or blank) `env` is returned as it is,
+ * and a machine with no term file at all fails closed, as everywhere. The given `env` is not changed.
+ */
+export declare const withInlineTerms: (env: NodeJS.ProcessEnv, storeDir: string) => Promise<NodeJS.ProcessEnv>;

package/dist/sessions/machine.js

@@ -0,0 +1,89 @@
+// What makes a runtime a machine: a cloud VM, a VPS, or a self-hosted runner that builds its session's deposit batch at every Stop. The gate is one variable, `OARS_HOST_CLASS`, set to a class
+// other than `local`; a laptop never sets it, so it keeps its own hooks and its end-of-session gate untouched. The rest of the enrollment block (launcher, machine id, allowed repositories,
+// salts, exclusion terms) is read where it is used; this file holds the names, the gate, and the install-time parsing of the block.
+import { rename } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { CliError, ExitCode } from '../errors.js';
+import { mkdirOwnerOnly, writeOwnerOnly } from './owner-only.js';
+/** Where a session runs: `local` is every ordinary machine and the only class that is not a machine here. */
+export const HOST_CLASSES = ['local', 'vps', 'cloud', 'ci', 'hosted'];
+/** Every variable of the enrollment block; an install writes these and refuses any other name, so a typo is never silently dropped. */
+export const ENROLLMENT_NAMES = [
+    'OARS_HOST_CLASS',
+    'OARS_LAUNCHER',
+    'OARS_MACHINE',
+    'OARS_ALLOW_REPOS',
+    'OARS_REPO_SALT',
+    'OARS_SESSION_SALT',
+    'OARS_EXCLUSION_TERMS',
+    'OARS_EXCLUSION_TERMS_INLINE',
+];
+const isMachineClass = (value) => HOST_CLASSES.some((name) => name === value && name !== 'local');
+const present = (value) => (value === undefined || value.trim() === '' ? undefined : value.trim());
+/** The machine configuration in `env`, or `undefined` for a local runtime (no `OARS_HOST_CLASS`, `local`, or a value that is not a class). A value that is not a class is not a machine: nothing is built. */
+export const machineOf = (env) => {
+    const hostClass = present(env.OARS_HOST_CLASS);
+    if (!isMachineClass(hostClass))
+        return undefined;
+    return {
+        hostClass,
+        launcher: present(env.OARS_LAUNCHER),
+        machine: present(env.OARS_MACHINE),
+        sessionSalt: present(env.OARS_SESSION_SALT),
+        remoteSession: present(env.CLAUDE_CODE_REMOTE_SESSION_ID),
+        allowRepos: (env.OARS_ALLOW_REPOS ?? '')
+            .split(/[\s,]+/u)
+            .map((entry) => entry.trim().toLowerCase())
+            .filter((entry) => entry !== ''),
+    };
+};
+const usage = (message) => new CliError(message, ExitCode.USAGE, 'usage');
+const isEnrollmentName = (name) => ENROLLMENT_NAMES.some((known) => known === name);
+/**
+ * The `env` entries a user-scope machine install writes, from the `NAME=value` pairs of `--env`. `OARS_HOST_CLASS` is required and is the gate, so it must be a class other than `local`. With
+ * `--terms-file`, the inline terms go to that file (owner-only) and `OARS_EXCLUSION_TERMS` names it, so the settings file holds no term. Nothing is written until every pair is valid.
+ */
+export const enrollmentOf = async (pairs, termsFile, cwd) => {
+    const env = {};
+    for (const pair of pairs) {
+        const at = pair.indexOf('=');
+        const name = at < 0 ? pair : pair.slice(0, at);
+        if (at < 0 || !isEnrollmentName(name))
+            throw usage(`--env takes NAME=value with a name from the enrollment block (${ENROLLMENT_NAMES.join(', ')}); got ${at < 0 ? 'no "="' : name}. Nothing was written.`);
+        env[name] = pair.slice(at + 1);
+    }
+    if (!isMachineClass(present(env.OARS_HOST_CLASS)))
+        throw usage('--scope user --machine needs --env OARS_HOST_CLASS=<vps|cloud|ci|hosted>: that variable is the gate, and local is not a machine. Nothing was written.');
+    const inline = env.OARS_EXCLUSION_TERMS_INLINE;
+    if (inline !== undefined && env.OARS_EXCLUSION_TERMS !== undefined)
+        throw usage('Give the exclusion terms once: OARS_EXCLUSION_TERMS_INLINE or OARS_EXCLUSION_TERMS, not both. Nothing was written.');
+    if (termsFile === undefined)
+        return { env, termsPath: undefined };
+    if (inline === undefined)
+        throw usage('--terms-file moves the terms of --env OARS_EXCLUSION_TERMS_INLINE into an owner-only file, and none was given. Nothing was written.');
+    const termsPath = resolve(cwd, termsFile);
+    await mkdirOwnerOnly(dirname(termsPath));
+    await writeOwnerOnly(termsPath, inline.endsWith('\n') ? inline : `${inline}\n`);
+    Reflect.deleteProperty(env, 'OARS_EXCLUSION_TERMS_INLINE');
+    env.OARS_EXCLUSION_TERMS = termsPath;
+    return { env, termsPath };
+};
+/** Where a machine's child keeps the terms it was given in `OARS_EXCLUSION_TERMS_INLINE`: in the store, owner-only. */
+export const inlineTermsFile = (storeDir) => join(storeDir, 'exclusion-terms-inline.txt');
+/**
+ * A machine whose enrollment put the exclusion terms in one variable (a cloud environment has no file to point at) gets them written, owner-only, into its store at every Stop, with `OARS_EXCLUSION_TERMS` pointed at that file, so the
+ * file is always the variable's current value. The inline terms win over a file named by `OARS_EXCLUSION_TERMS`, because the enrollment is where the operator stated them. With no inline terms (unset or blank) `env` is returned as it is,
+ * and a machine with no term file at all fails closed, as everywhere. The given `env` is not changed.
+ */
+export const withInlineTerms = async (env, storeDir) => {
+    const inline = env.OARS_EXCLUSION_TERMS_INLINE;
+    if (inline === undefined || inline.trim() === '')
+        return env;
+    const file = inlineTermsFile(storeDir);
+    await mkdirOwnerOnly(storeDir);
+    // Written beside the file and renamed onto it: a Stop still in its gates reads the old list or the new one, never a half-written one that would fail closed and withdraw its batch.
+    const staged = `${file}.${String(process.pid)}`;
+    await writeOwnerOnly(staged, inline.endsWith('\n') ? inline : `${inline}\n`);
+    await rename(staged, file);
+    return { ...env, OARS_EXCLUSION_TERMS: file };
+};

package/dist/sessions/opencode.d.ts

@@ -25,6 +25,8 @@ export interface OpencodeStore {
     sessions: OpencodeSession[];
     /** The session as transcript text for `captureSession`; throws when it holds no parseable message. */
     transcript: (session: OpencodeSession) => string;
+    /** True when every row of the session is a type the format defines that carries no turn (`NO_TURN_ROWS`); `sessions verify` counts such a session as empty, not unreadable. */
+    headOnly: (session: OpencodeSession) => boolean;
     /** Sessions skipped because their id is not a safe file name (it names a skeleton), counted so the skip is never silent. */
     rejected: number;
     close: () => void;

package/dist/sessions/opencode.js

@@ -247,6 +247,8 @@ const linesOf = (session, rows, parts) => {
     }
     return { lines, bad };
 };
+/** The `session_message` types the format defines that are not a prompt and not read (the header comment): a session of these alone was opened and left. */
+const NO_TURN_ROWS = new Set(['location-switched', 'synthetic', 'system', 'skill', 'compaction', 'idle', 'agent-switched', 'model-switched']);
 /** Opens the OpenCode store under `root`; undefined when it holds no database, so a machine without OpenCode is skipped silently. A database that cannot be read throws. */
 export const openOpencodeStore = async (root) => {
     const file = join(root, DATABASE);
@@ -300,6 +302,10 @@ export const openOpencodeStore = async (root) => {
         close: () => {
             db.close();
         },
+        headOnly: (session) => {
+            const types = db.prepare('select distinct type from session_message where session_id = ?').all(session.id);
+            return types.length > 0 && types.every((row) => typeof row.type === 'string' && NO_TURN_ROWS.has(row.type));
+        },
         transcript: (session) => {
             const rows = db.prepare('select id, type, time_created, data from session_message where session_id = ? order by seq').all(session.id);
             const parts = new Map();

package/dist/sessions/otel.d.ts

@@ -34,7 +34,18 @@ export interface OtelSession {
         spawnedBy: string | null;
     } | undefined;
     file: string;
+    /** True when a span of the session holds a `gen_ai.*` attribute or a name leading with an operation. A session with none (ordinary HTTP spans) is a known form with no turn. */
+    genai: boolean;
 }
+/**
+ * The single-trace sessions a conversation id folds into a merged one: a trace that names a conversation is no session of its own, but an earlier deposit that read
+ * it before the id arrived (the id sits on the root agent span, which a batch exporter writes last) holds one under the trace's own id. The deposit supersedes that
+ * session with a later rev, only if it holds one.
+ */
+export declare const supersededSessions: (spans: readonly Span[]) => {
+    id: string;
+    by: string;
+}[];
 /** The sessions of a set of spans (every trace of every file). */
 export declare const otelSessions: (spans: readonly Span[]) => OtelSession[];
 /** A trace session found in the folder, before its lines are read. */
@@ -46,11 +57,21 @@ export interface OtelFound {
     mtimeMs: number;
     subagent: OtelSession['subagent'];
     file: string;
+    genai: boolean;
 }
 export interface OtelStore {
     sessions: OtelFound[];
+    /** The single-trace sessions a conversation id has folded into a merged one (`supersededSessions`). */
+    superseded: {
+        id: string;
+        by: string;
+    }[];
     transcript: (session: OtelFound) => string;
+    /** True when a session with no turn holds no GenAI span (ordinary HTTP spans): a known form, so `sessions verify` counts it as empty, not unreadable. */
+    headOnly: (session: OtelFound) => boolean;
     rejected: number;
+    /** Files that held a request but gave no span because the request's shape is not one the reader knows. Read only by `sessions verify`; selection is unchanged. */
+    shapeMoved: number;
     unreadable: {
         file: string;
         reason: string;

package/dist/sessions/otel.js

@@ -4,8 +4,8 @@
 // conventions moved there from open-telemetry/semantic-conventions, which has a release but only "Moved" stubs for GenAI, and the new repository has no release)
 // and the OTLP JSON encoding (opentelemetry-proto v1.11.1, docs/specification.md:453-484, trace.proto:96-327; the file exporter,
 // opentelemetry-specification specification/protocol/file-exporter.md:64-75, writes one `ExportTraceServiceRequest` a line with no order guarantee). Nothing was
-// copied and no real trace was read: `docs/sessions-store.md` names the one hand run that would prove the reader. Every GenAI attribute below is marked Development
-// in the registry, so each one is optional here: a missing or renamed attribute means less is read, never a throw.
+// copied; a real Pydantic AI trace is pinned in `otel-real-trace.test.ts`. Every GenAI attribute below is marked Development in the registry, so each one is
+// optional here: a missing or renamed attribute means less is read, never a throw.
 //
 // Where it reads from (`otelRoot`): `$OARS_OTEL_TRACES`, else `<config>/oars/otel-traces` (a configured folder, so the nightly run is deterministic). Every `*.jsonl` and
 // `*.json` file in it is read; the traces of all files are joined by `traceId` first, because a collector may split one trace across files.
@@ -13,11 +13,15 @@
 // How a trace becomes a session:
 //   session      one `traceId`; traces that share `gen_ai.conversation.id` are one session, each trace a turn in start-time order. An agent span nested inside another
 //                agent's (directly or through an agent-as-tool `execute_tool` span) is its own session `<traceId>-<spanId>`, a subagent of the span's session.
-//   prompt       one per root agent span (`invoke_agent`, `invoke_workflow`, any `invoke_*` operation), else per trace root; its text is the last user message of
-//                `gen_ai.input.messages` (Opt-In: absent by default, and then the turn is written content-less, as an image-only prompt is).
+//   prompt       one per root agent span (`invoke_agent`, `invoke_workflow`, any `invoke_*` operation), else one per trace, from its earliest root (by start time, then input
+//                order; a root whose parent never reached the data joins it); its text is the last user message of `gen_ai.input.messages`, else of the earliest chat child span
+//                that has them (Opt-In: absent by default, and then the turn is written content-less, as an image-only prompt is).
 //   model call   a span whose `gen_ai.operation.name` is `chat`, `generate_content`, or `text_completion`: one assistant line, its `requestId` the span id.
-//   tool call    an `execute_tool` span: a block in the model call that ended before it began (or whose output messages name its `gen_ai.tool.call.id`). It failed iff the
-//                span's status code is ERROR (2) or `error.type` is set (stable, recording-errors.md): the error line is `error.type: status.message`, never the result.
+//   tool call    an `execute_tool` span, put under the model call that ended before it began (or whose output messages name its `gen_ai.tool.call.id`): a block in
+//                that call's line, or, with both times and end not before start (a directly nested agent span too), its own assistant line at the span's start under
+//                the call's `requestId`, so its duration is the span's length. It failed iff the span's status code is ERROR (2) or `error.type` is set (stable,
+//                recording-errors.md): the error line is `error.type: status.message`, never the result; a call that did not fail keeps `gen_ai.tool.call.result` as
+//                its result content.
 //   usage        `gen_ai.usage.*`; `input_tokens` includes the cache reads and writes (the registry says it SHOULD), and capture's fields are disjoint, so the uncached
 //                part is input - read - write. A figure the span did not report is not written as zero.
 //   harness      `otel`; the version slot holds the emitting framework from the instrumentation scope name (a closed list plus `other`). Nothing names a working folder.
@@ -138,6 +142,18 @@ const spansOf = (request, order, file) => {
     }
     return spans;
 };
+/**
+ * True when a request holds something the reader found no span in: no `resourceSpans` list, or a span that is not an object or lacks `traceId` or `spanId`. An export with an
+ * empty list is routine (nothing was traced) and is not this.
+ */
+const holdsUnreadSpans = (request) => {
+    // A metrics or logs export in the same folder is another signal, not a moved trace.
+    if (isObj(request) && ('resourceMetrics' in request || 'resourceLogs' in request))
+        return false;
+    if (!isObj(request) || !Array.isArray(request.resourceSpans))
+        return true;
+    return request.resourceSpans.some((resource) => (isObj(resource) && Array.isArray(resource.scopeSpans) ? resource.scopeSpans : []).some((scoped) => (isObj(scoped) && Array.isArray(scoped.spans) ? scoped.spans : []).some((raw) => !isObj(raw) || str(raw.traceId) === undefined || str(raw.spanId) === undefined)));
+};
 /** The requests of one file: the whole text as one JSON value (a `.json` file), else one request a line (the file exporter's JSON Lines). Throws when nothing parses. */
 const requestsOf = (text) => {
     const whole = parse(text);
@@ -169,21 +185,58 @@ const messagesOf = (value) => {
     const list = structured(value);
     return Array.isArray(list) ? list.filter(isObj) : [];
 };
-const promptText = (span) => {
-    const users = messagesOf(span.attrs['gen_ai.input.messages']).filter((message) => message.role === 'user');
+const promptText = (span, models) => {
+    // Pydantic AI's agent span has no `gen_ai.input.messages` (they sit on its chat spans), so the earliest chat span that carries them stands in; a span that has them keeps its own.
+    const source = span.attrs['gen_ai.input.messages'] === undefined ? (models.find((model) => model.attrs['gen_ai.input.messages'] !== undefined) ?? span) : span;
+    const users = messagesOf(source.attrs['gen_ai.input.messages']).filter((message) => message.role === 'user');
     return textParts(users[users.length - 1]);
 };
+/** A tool span's result as the content of its result line: a string as written, anything else as JSON; `""` when the span names none. */
+const resultContent = (span) => {
+    const value = span.attrs['gen_ai.tool.call.result'];
+    if (value === undefined)
+        return '';
+    return typeof value === 'string' ? value : JSON.stringify(value);
+};
 /** The tool call ids a model call's output messages name. */
 const namedCalls = (span) => messagesOf(span.attrs['gen_ai.output.messages']).flatMap((message) => (Array.isArray(message.parts) ? message.parts : []).flatMap((part) => (isObj(part) && part.type === 'tool_call' && str(part.id) !== undefined ? [String(part.id)] : [])));
 const count = (value) => (typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined);
 /** A tool span's error line: `error.type: status.message`, either alone when the other is missing, else the exception event's message. */
 const failureText = (span) => {
-    const type = str(span.attrs['error.type']);
+    // `error.type` is the stable name; a framework that records the failure only as an exception event (Pydantic AI) still names the class there.
+    const type = str(span.attrs['error.type']) ?? str(span.events.find((event) => event.name === 'exception')?.['exception.type']);
     const message = span.statusMessage ?? str(span.events.find((event) => event.name === 'exception')?.['exception.message']);
     if (type !== undefined && message !== undefined)
         return `${type}: ${message}`;
     return type ?? message ?? 'tool failed';
 };
+const isGenAi = (span) => Object.keys(span.attrs).some((key) => key.startsWith('gen_ai.')) || ops(span) !== '';
+/** The id a trace's own session takes, and the one nested agents build on: the trace id when it is a plain id, else a digest of it. */
+const tracePart = (trace) => (/^[A-Za-z0-9]{1,64}$/.test(trace) ? trace : digest(trace));
+/** The conversation each trace names, from the earliest span that names one. */
+const conversationsOf = (spans) => {
+    const conversationOf = new Map();
+    for (const span of [...spans].sort((a, b) => (a.start ?? a.end ?? 0) - (b.start ?? b.end ?? 0))) {
+        const conversation = str(span.attrs['gen_ai.conversation.id']);
+        if (conversation !== undefined && !conversationOf.has(span.trace))
+            conversationOf.set(span.trace, conversation);
+    }
+    return conversationOf;
+};
+/** The session a trace's turns belong to: its conversation's, else its own. */
+const sessionIdOf = (trace, conversationOf) => {
+    const conversation = conversationOf.get(trace);
+    return conversation === undefined ? tracePart(trace) : `conv-${digest(conversation)}`;
+};
+/**
+ * The single-trace sessions a conversation id folds into a merged one: a trace that names a conversation is no session of its own, but an earlier deposit that read
+ * it before the id arrived (the id sits on the root agent span, which a batch exporter writes last) holds one under the trace's own id. The deposit supersedes that
+ * session with a later rev, only if it holds one.
+ */
+export const supersededSessions = (spans) => {
+    const conversationOf = conversationsOf(spans);
+    return [...conversationOf.keys()].map((trace) => ({ id: tracePart(trace), by: sessionIdOf(trace, conversationOf) }));
+};
 /** The sessions of a set of spans (every trace of every file). */
 export const otelSessions = (spans) => {
     const byId = new Map(spans.map((span) => [`${span.trace}/${span.id}`, span]));
@@ -216,17 +269,9 @@ export const otelSessions = (spans) => {
     }
     const roots = spans.filter((span) => parentOf(span) === undefined);
     const startOf = (span) => span.start ?? span.end ?? 0;
-    const conversationOf = new Map();
-    for (const span of [...spans].sort((a, b) => startOf(a) - startOf(b))) {
-        const conversation = str(span.attrs['gen_ai.conversation.id']);
-        if (conversation !== undefined && !conversationOf.has(span.trace))
-            conversationOf.set(span.trace, conversation);
-    }
-    const tracePart = (trace) => (/^[A-Za-z0-9]{1,64}$/.test(trace) ? trace : digest(trace));
-    const sessionOfTrace = (trace) => {
-        const conversation = conversationOf.get(trace);
-        return conversation === undefined ? tracePart(trace) : `conv-${digest(conversation)}`;
-    };
+    const timed = (span) => span.start !== undefined && span.end !== undefined && span.end >= span.start;
+    const conversationOf = conversationsOf(spans);
+    const sessionOfTrace = (trace) => sessionIdOf(trace, conversationOf);
     // A unit is an agent span, or a trace root that is not one: whatever owns the model calls and tools beneath it.
     const unitOf = new Map();
     const agentsAbove = (span) => ancestors(span).find(isAgent);
@@ -285,6 +330,15 @@ export const otelSessions = (spans) => {
         else
             held.push(span);
     }
+    // A GenAI attribute (or an operation-leading name) on any span of a unit's trace marks its session, even an ordinary child span that is no model or tool span: a renamed attribute there is a moved form, not an empty session.
+    const genaiUnits = new Set();
+    for (const span of spans) {
+        if (!isGenAi(span))
+            continue;
+        const owner = ownerOf(span);
+        if (owner !== undefined)
+            genaiUnits.add(owner);
+    }
     const out = new Map();
     const framework = (unit) => unit.span.framework;
     const orderedUnits = [...unitOf.values()].sort((a, b) => startOf(a.span) - startOf(b.span) || a.span.order - b.span.order);
@@ -303,7 +357,7 @@ export const otelSessions = (spans) => {
             held.push(child.span);
     }
     for (const unit of orderedUnits) {
-        const entry = out.get(unit.session) ?? { lines: [], mtime: 0, spans: 0, subagent: undefined, file: unit.span.file };
+        const entry = out.get(unit.session) ?? { lines: [], mtime: 0, spans: 0, subagent: undefined, file: unit.span.file, genai: false };
         out.set(unit.session, entry);
         if (unit.spawn !== undefined) {
             const agentName = str(unit.span.attrs['gen_ai.agent.name']);
@@ -327,7 +381,7 @@ export const otelSessions = (spans) => {
             return at !== undefined && (least === undefined || at < least) ? at : least;
         }, undefined);
         const begin = stamp(unit.span.start ?? unit.span.end ?? (entry.mtime === 0 ? earliest : undefined));
-        const text = promptText(unit.span);
+        const text = promptText(unit.span, mine.filter(isModel));
         const pieces = [];
         pieces.push({ t: begin, rank: -1, line: { ...base, type: 'user', uuid: `${unit.session}-${unit.span.id}-u`, timestamp: iso(begin), message: { role: 'user', content: [text === '' ? { type: 'image' } : { type: 'text', text }] } } });
         const calls = [];
@@ -340,25 +394,31 @@ export const otelSessions = (spans) => {
             pieces.push({ t, rank: 0, line });
             return { content, line, message };
         };
-        const attach = (callId, tool) => {
-            const named = calls.find((call) => call.names.includes(callId));
-            const before = calls.findLast((call) => call.end <= startOf(tool));
-            const chosen = named ?? before;
-            if (chosen !== undefined)
-                return chosen;
-            return assistant(tool, `${tool.id}-call`);
+        const chooseCall = (callId, tool) => calls.find((call) => call.names.includes(callId)) ?? calls.findLast((call) => call.end <= startOf(tool));
+        const attach = (callId, tool) => chooseCall(callId, tool) ?? assistant(tool, `${tool.id}-call`);
+        // A timed tool is its own assistant line at the span's start under the chat's `requestId` (the one-block-per-line shape Claude Code transcripts have), so extract reads the span's own length as the call's duration.
+        const place = (callId, tool, block) => {
+            const chosen = timed(tool) ? chooseCall(callId, tool) : undefined;
+            if (chosen === undefined) {
+                attach(callId, tool).content.push(block);
+                return;
+            }
+            const { content, line } = assistant(tool, String(chosen.line.requestId));
+            if (chosen.line.requestedModel !== undefined)
+                line.requestedModel = chosen.line.requestedModel;
+            content.push(block);
         };
-        const result = (id, tool, failure) => {
+        const result = (id, tool, failure, output = '') => {
             const t = Math.max(stamp(tool.end ?? tool.start), begin);
             pieces.push({
                 t,
                 rank: 1,
-                line: { ...base, type: 'user', uuid: `${unit.session}-${tool.id}-r-${id}`, timestamp: iso(t), noDuration: true, message: { role: 'user', content: [{ type: 'tool_result', tool_use_id: id, is_error: failure !== undefined, content: failure ?? '' }] } },
+                line: { ...base, type: 'user', uuid: `${unit.session}-${tool.id}-r-${id}`, timestamp: iso(t), ...(timed(tool) ? {} : { noDuration: true }), message: { role: 'user', content: [{ type: 'tool_result', tool_use_id: id, is_error: failure !== undefined, content: failure ?? output }] } },
             });
         };
         for (const span of mine) {
             if (direct.has(span)) {
-                attach(span.id, span).content.push({ type: 'tool_use', id: span.id, name: 'invoke_agent', native: 'invoke_agent', input: {} });
+                place(span.id, span, { type: 'tool_use', id: span.id, name: 'invoke_agent', native: 'invoke_agent', input: {} });
                 result(span.id, span, span.failed ? failureText(span) : undefined);
             }
             else if (isModel(span)) {
@@ -418,15 +478,18 @@ export const otelSessions = (spans) => {
                     block.name = `mcp__unnamed__${toolName}`;
                     block.native = block.name;
                 }
-                attach(id, span).content.push(block);
-                result(id, span, failed ? (exit !== undefined && exit !== 0 && !span.failed ? `Exit code ${String(exit)}` : failureText(span)) : undefined);
+                place(id, span, block);
+                result(id, span, failed ? (exit !== undefined && exit !== 0 && !span.failed ? `Exit code ${String(exit)}` : failureText(span)) : undefined, resultContent(span));
             }
         }
         pieces.sort((a, b) => a.t - b.t || a.rank - b.rank);
         entry.lines.push(...pieces.map((piece) => piece.line));
-        entry.spans += 1 + mine.length;
+        // The unit's own span counts once, though it is also a model or tool span when the earliest root of an agentless trace is one.
+        entry.spans += 1 + mine.filter((span) => span !== unit.span).length;
+        if (mine.some(isGenAi) || genaiUnits.has(unit))
+            entry.genai = true;
     }
-    return [...out.entries()].map(([id, held]) => ({ id, size: held.spans, mtimeMs: held.mtime, lines: held.lines, subagent: held.subagent, file: held.file }));
+    return [...out.entries()].map(([id, held]) => ({ id, size: held.spans, mtimeMs: held.mtime, lines: held.lines, subagent: held.subagent, file: held.file, genai: held.genai }));
 };
 const SAFE = /^(?!\.+$)[A-Za-z0-9._-]+$/;
 export const openOtelStore = async (root) => {
@@ -437,11 +500,12 @@ export const openOtelStore = async (root) => {
     catch (error) {
         if (missing(error))
             return undefined;
-        return { sessions: [], transcript: () => '', rejected: 0, unreadable: [{ file: root, reason: reasonOf(error, root) }] };
+        return { sessions: [], superseded: [], transcript: () => '', headOnly: () => false, rejected: 0, shapeMoved: 0, unreadable: [{ file: root, reason: reasonOf(error, root) }] };
     }
     const unreadable = [];
     const spans = [];
     const order = { next: 0 };
+    let shapeMoved = 0;
     // The torn lines of each file stay with that file: a session that came from it counts them, else the file is named.
     const torn = new Map();
     for (const name of names) {
@@ -452,15 +516,19 @@ export const openOtelStore = async (root) => {
             const { requests, bad } = requestsOf(await readFile(file, 'utf8'));
             if (bad.length > 0)
                 torn.set(file, bad);
+            const before = spans.length;
             for (const request of requests) {
                 spans.push(...spansOf(request, order, file));
             }
+            if (spans.length === before && requests.some(holdsUnreadSpans))
+                shapeMoved += 1;
         }
         catch (error) {
             unreadable.push({ file, reason: reasonOf(error, file) });
         }
     }
     const built = otelSessions(spans);
+    const superseded = supersededSessions(spans).filter((entry) => SAFE.test(entry.id) && SAFE.test(entry.by));
     let rejected = 0;
     const sessions = [];
     const lines = new Map();
@@ -470,7 +538,7 @@ export const openOtelStore = async (root) => {
             continue;
         }
         lines.set(session.id, session.lines);
-        sessions.push({ id: session.id, folder: null, size: session.size, mtimeMs: session.mtimeMs, subagent: session.subagent, file: session.file });
+        sessions.push({ id: session.id, folder: null, size: session.size, mtimeMs: session.mtimeMs, subagent: session.subagent, file: session.file, genai: session.genai });
     }
     sessions.sort((a, b) => a.mtimeMs - b.mtimeMs || a.id.localeCompare(b.id));
     const tornOf = new Map();
@@ -483,7 +551,10 @@ export const openOtelStore = async (root) => {
     }
     return {
         sessions,
+        superseded,
+        headOnly: (session) => !session.genai,
         rejected,
+        shapeMoved,
         unreadable,
         transcript: (session) => {
             const held = lines.get(session.id) ?? [];

package/dist/sessions/owner-only.d.ts

@@ -0,0 +1,7 @@
+export declare const isMissing: (error: unknown) => boolean;
+/** Appends `text` to `file`, which stays readable and writable by the owner only whether or not it existed. */
+export declare const appendOwnerOnly: (file: string, text: string) => Promise<void>;
+/** Writes `text` (or bytes, kept exactly as they are) to `file`, readable and writable by the owner only, whether or not the file existed. */
+export declare const writeOwnerOnly: (file: string, text: string | Uint8Array) => Promise<void>;
+/** Makes `folder` (and any parent it has to create) 0700; a `folder` that exists is narrowed to 0700 as well. */
+export declare const mkdirOwnerOnly: (folder: string) => Promise<void>;

package/dist/sessions/owner-only.js

@@ -0,0 +1,34 @@
+// What the pool commands keep on this machine is the operator's alone: the pool account file holds a credential, and the outbox holds redacted transcripts and batches (census S9, S10). Files are written 0600 and folders 0700.
+// `writeFile` and `mkdir` apply a mode only to what they create, so a file or folder an older client made wider is narrowed here too, and a file is narrowed before new bytes go into it.
+// Windows has no POSIX mode bits (its own file ACLs apply), so there the calls are skipped.
+import { appendFile, chmod, mkdir, writeFile } from 'node:fs/promises';
+const POSIX = process.platform !== 'win32';
+export const isMissing = (error) => error instanceof Error && 'code' in error && error.code === 'ENOENT';
+/** Narrows a file that exists to 0600 before bytes go into it; a file not made yet is created 0600 by the write itself. */
+const narrow = async (file) => {
+    if (!POSIX)
+        return;
+    try {
+        await chmod(file, 0o600);
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+    }
+};
+/** Appends `text` to `file`, which stays readable and writable by the owner only whether or not it existed. */
+export const appendOwnerOnly = async (file, text) => {
+    await narrow(file);
+    await appendFile(file, text, { encoding: 'utf8', mode: 0o600 });
+};
+/** Writes `text` (or bytes, kept exactly as they are) to `file`, readable and writable by the owner only, whether or not the file existed. */
+export const writeOwnerOnly = async (file, text) => {
+    await narrow(file);
+    await writeFile(file, text, { encoding: 'utf8', mode: 0o600 });
+};
+/** Makes `folder` (and any parent it has to create) 0700; a `folder` that exists is narrowed to 0700 as well. */
+export const mkdirOwnerOnly = async (folder) => {
+    await mkdir(folder, { recursive: true, mode: 0o700 });
+    if (POSIX)
+        await chmod(folder, 0o700);
+};