@agentwhy/cli 0.0.0-dev

package/dist/adapter/codex/contract/permissions.js

@@ -0,0 +1,27 @@
+/**
+ * The runtime permissions a `turn_context` records for its turn (§2.5; §2.8): recorded settings, never agentwhy's policy
+ * and never a verdict on a path (X21, X22). Values outside these lists are kept out of the model and said as unknown.
+ */
+export const PERMISSIONS = {
+    approval: 'approval_policy',
+    approver: 'approvals_reviewer',
+    sandbox: 'sandbox_policy',
+    sandboxType: 'type',
+    network: 'network_access',
+    fileSystem: 'file_system_sandbox_policy',
+    entries: 'entries',
+    access: 'access',
+    target: 'path',
+    targetType: 'type',
+    targetPath: 'path',
+};
+/** `approvals_reviewer`: `user` 128 and `auto_review` 341 turns (§2.5); `user` in 7 of 7 (§2.8). */
+export const APPROVERS = { user: 'person', auto_review: 'reviewer' };
+/** `approval_policy` string values: `on-request` 304 and `never` 145 turns (§2.5). A `granular` object (20) is not read. */
+export const APPROVAL_POLICIES = ['on-request', 'never'];
+/** `sandbox_policy.type`: `workspace-write` and `read-only` (§2.8). */
+export const SANDBOX_TYPES = ['workspace-write', 'read-only'];
+/** `entries[].access`: `read` 2,731 and `write` 1,112 (§2.5). The entries only allow; not one denies. */
+export const SCOPE_ACCESS = ['read', 'write'];
+/** `entries[].path.type`: `path` 2,436 and `special` 1,407 (§2.5). A special target names no path this reads. */
+export const SCOPE_TARGETS = { path: 'path', special: 'special' };

package/dist/adapter/codex/contract/reviews.js

@@ -0,0 +1,13 @@
+/**
+ * Codex's own reviewer (X19, X20; §2.4): a child thread whose `source.subagent.other` is `guardian`, started by Codex and
+ * never by the agent. Its turns name the reviewed turn by `root_turn_id` (§2.7: 52 references, all present); its
+ * `task_complete.last_agent_message` is a JSON verdict (141 of 141) whose `outcome` was `allow` every time.
+ */
+export const REVIEWER = { other: 'other', guardian: 'guardian' };
+export const VERDICT = {
+    outcome: 'outcome',
+    risk: 'risk_level',
+    rationale: 'rationale',
+    /** The one outcome measured. Any other is unrecognised, never a refusal (X20, XB1). */
+    allowed: 'allow',
+};

package/dist/adapter/codex/contract/session.js

@@ -0,0 +1,31 @@
+/** First-line discovery (§2.1, §2.7). Measured 2026-09-29; action and message semantics have separate gates. */
+export const SESSION = {
+    lineType: 'type',
+    metadataType: 'session_meta',
+    payload: 'payload',
+    id: 'id',
+    parentId: 'parent_thread_id',
+    workingDirectory: 'cwd',
+    historyMode: 'history_mode',
+    /** The build that wrote the file: `0.154.0-alpha.6.2`, `0.155.0-alpha.16.3`, `0.155.0-alpha.9` (§2.7), `0.157.0` (§2.8). */
+    version: 'cli_version',
+    /** A string for a person's session (`exec` in §2.8); an object `{subagent: …}` for a thread another started (§2.4). */
+    source: 'source',
+    filePrefix: 'rollout-',
+    fileSuffix: '.jsonl',
+};
+/** Where Codex keeps its rollouts, under the home directory (X1, §2.1). `$CODEX_HOME` is not measured (XB6). */
+export const SESSIONS_ROOT = ['.codex', 'sessions'];
+export const HISTORY_MODES = ['paginated', 'legacy'];
+/**
+ * Codex's own list of thread names, under the home directory: one JSON object a line, `{"id", "thread_name",
+ * "updated_at"}`, appended as a name is given (a later line names the same id again). Measured 2026-09-30 on 55 lines:
+ * every root thread started from the VS Code extension, the desktop app and the terminal app (0.154.0-alpha.6.2 to
+ * 0.159.2) had a line, and no thread whose `source` is `exec` did (20); the name was never the person's first message nor its start, so it
+ * is a title Codex wrote, as Claude Code's `ai-title` is. The `id` is the rollout's thread id.
+ */
+export const THREAD_NAMES = {
+    file: ['.codex', 'session_index.jsonl'],
+    id: 'id',
+    name: 'thread_name',
+};

package/dist/adapter/codex/contract/turns.js

@@ -0,0 +1,23 @@
+/**
+ * A turn and its boundaries (§2.2): `turn_context` opens one per turn with its `turn_id`; `task_started`,
+ * `task_complete` and `turn_aborted` name it by the same id. Every item and response record carries it (§2.2, §2.8).
+ */
+export const TURN_CONTEXT = {
+    turnId: 'turn_id',
+    workingDirectory: 'cwd',
+};
+export const TURN_EVENTS = {
+    started: 'task_started',
+    complete: 'task_complete',
+    aborted: 'turn_aborted',
+    turnId: 'turn_id',
+    /** On a reviewer's turns: the turn of the agent it reviewed (§2.4, §2.7). */
+    rootTurnId: 'root_turn_id',
+    /** On `task_complete`: a copy of the turn's final answer, or a reviewer's verdict (§2.4, §2.8). */
+    lastMessage: 'last_agent_message',
+};
+/** Where a response record carries its turn (§2.2): 1 record of all measured lacked it. */
+export const RESPONSE_TURN = {
+    metadata: 'internal_chat_message_metadata_passthrough',
+    turnId: 'turn_id',
+};

package/dist/adapter/codex/contract/version.js

@@ -0,0 +1,15 @@
+/**
+ * v1 (2026-09-29): first-line recognition and identity only, X1-X5, measured on 70 frozen files (spec §2.7).
+ * v2 (2026-09-29): the records a report reads - turns and their permissions, action items, messages, the cell's output
+ * handed to the model, delegations and reviewers - from §2.2-§2.6 and the controlled terminal sessions of §2.8, and the
+ * capability matrix they permit (`capabilities.ts`). Joins that depend on the probe's corrected session index (§2.4)
+ * stay provisional: they are made by id and leave a relation unresolved where they break; XB4 is open. Every other
+ * build and mode is read with its capabilities unmeasured.
+ */
+export const CONTRACT_VERSION = 2;
+export const VERIFIED_AGAINST = {
+    date: '2026-09-29',
+    codex: ['0.154.0-alpha.6.2', '0.155.0-alpha.16.3', '0.155.0-alpha.9', '0.157.0'],
+    files: 77,
+    scope: 'session-records',
+};

package/dist/adapter/codex/discovery/codex-conversations.js

@@ -0,0 +1,44 @@
+import { FileAccessError } from '../../../ports/file-access-error.js';
+/**
+ * The conversations of one listing (X5): every root, with the files whose parents lead to it, and every file whose
+ * relation did not resolve, which is listed on its own rather than hidden as a thread of nothing. A resolved descendant
+ * is never a row: lists show the root only. `keep` chooses the rows by their first file, before any file is looked at:
+ * only the files of the rows kept are.
+ */
+export async function conversationsIn(listing, directories, keep = () => true) {
+    // The files resolved to each root, gathered in one pass: thousands of rollouts are walked once, not once per row.
+    const resolvedTo = new Map();
+    listing.sources.forEach((source, at) => {
+        if (source.relation.kind !== 'resolved')
+            return;
+        const members = resolvedTo.get(source.relation.root);
+        if (members === undefined)
+            resolvedTo.set(source.relation.root, [at]);
+        else
+            members.push(at);
+    });
+    const rows = listing.sources.flatMap((source, index) => {
+        const relation = source.relation;
+        if ((relation.kind === 'resolved' && relation.root !== index) || !keep(source))
+            return [];
+        return [{ source, index, members: relation.kind === 'resolved' ? (resolvedTo.get(index) ?? []) : [index] }];
+    });
+    return Promise.all(rows.map(async ({ source, index, members }) => {
+        const modified = await Promise.all(members.map((at) => modifiedAt(directories, listing.sources[at]?.path ?? '')));
+        return {
+            source,
+            modifiedAt: Math.max(...modified),
+            delegations: members.filter((at) => at !== index && listing.sources[at]?.header.origin.kind === 'spawned').length,
+        };
+    }));
+}
+async function modifiedAt(directories, path) {
+    try {
+        return await directories.modifiedAt(path);
+    }
+    catch (error) {
+        if (!(error instanceof FileAccessError))
+            throw error;
+        return 0;
+    }
+}

package/dist/adapter/codex/discovery/codex-project-catalogue.js

@@ -0,0 +1,49 @@
+import { FileAccessError } from '../../../ports/file-access-error.js';
+import { conversationsIn } from './codex-conversations.js';
+/**
+ * The projects Codex keeps conversations for (`which-project.md` V9; X4): one per recorded `cwd` of a conversation's
+ * first line, named by `projectId` and never decoded from it. A conversation that records no folder is counted, never
+ * guessed. Titles and ways in are not read: their sources are not measured for Codex.
+ */
+export class CodexProjectCatalogue {
+    #dependencies;
+    constructor(dependencies) {
+        this.#dependencies = dependencies;
+    }
+    async list() {
+        const { index, directories, sessionsRoot, projectId } = this.#dependencies;
+        const conversations = await conversationsIn(await index.list(sessionsRoot), directories);
+        const byFolder = new Map();
+        let unreadable = 0;
+        for (const conversation of conversations) {
+            const folder = conversation.source.header.project;
+            if (folder === undefined) {
+                unreadable += 1;
+                continue;
+            }
+            const known = byFolder.get(folder);
+            byFolder.set(folder, {
+                conversations: (known?.conversations ?? 0) + 1,
+                newest: Math.max(known?.newest ?? 0, conversation.modifiedAt),
+            });
+        }
+        const projects = await Promise.all([...byFolder].map(async ([path, folder]) => ({
+            id: projectId(path),
+            path,
+            exists: await this.#isDirectory(path),
+            conversations: folder.conversations,
+            newest: { modifiedAt: folder.newest },
+        })));
+        return { projects: projects.sort((a, b) => b.newest.modifiedAt - a.newest.modifiedAt), unreadable };
+    }
+    async #isDirectory(path) {
+        try {
+            return (await this.#dependencies.directories.kindOf(path)) === 'directory';
+        }
+        catch (error) {
+            if (!(error instanceof FileAccessError))
+                throw error;
+            return false;
+        }
+    }
+}

package/dist/adapter/codex/discovery/codex-recognition.js

@@ -0,0 +1,20 @@
+import { FileAccessError } from '../../../ports/file-access-error.js';
+/**
+ * Whether an input is Codex's (X2): a file whose first line is a Codex `session_meta`, or a folder holding at least one
+ * such rollout. Only first lines are read, and a folder's only until the first rollout recognised.
+ */
+export async function recogniseCodex(discovery, directories, input) {
+    let kind;
+    try {
+        kind = await directories.kindOf(input);
+    }
+    catch (error) {
+        if (error instanceof FileAccessError)
+            return 'unavailable';
+        throw error;
+    }
+    if (kind === 'directory')
+        return (await discovery.holdsSession(input)) ? 'recognised' : 'unknown';
+    const read = await discovery.readHeader(input);
+    return read.kind === 'recognised' ? 'recognised' : read.kind === 'unknown' ? 'unknown' : 'unavailable';
+}

package/dist/adapter/codex/discovery/codex-session-catalogue.js

@@ -0,0 +1,28 @@
+import { conversationsIn } from './codex-conversations.js';
+/**
+ * A project's Codex conversations (X1, X4, X5): each conversation whose first line records the project's folder as its
+ * `cwd`, exactly - Codex records the folder itself, where Claude Code's store encodes it. First lines only are read.
+ */
+export class CodexSessionCatalogue {
+    #dependencies;
+    constructor(dependencies) {
+        this.#dependencies = dependencies;
+    }
+    async list(workingDirectory) {
+        const { index, directories, sessionsRoot } = this.#dependencies;
+        const listing = await index.list(sessionsRoot);
+        // The root itself missing or unreadable is "not looked at", never "no conversations".
+        const found = !listing.gaps.some((gap) => gap.path === sessionsRoot);
+        // Chosen by the first line before any file is looked at: only this project's conversations cost a look.
+        const sessions = (await conversationsIn(listing, directories, (root) => root.header.project === workingDirectory))
+            .map((conversation) => ({
+            id: conversation.source.header.id,
+            path: conversation.source.path,
+            modifiedAt: conversation.modifiedAt,
+            delegations: conversation.delegations,
+            provider: 'codex',
+        }))
+            .sort((a, b) => b.modifiedAt - a.modifiedAt);
+        return { directory: sessionsRoot, found, searched: [{ provider: 'codex', directory: sessionsRoot, found }], sessions };
+    }
+}

package/dist/adapter/codex/discovery/codex-session-discovery.js

@@ -0,0 +1,115 @@
+import { dirname, join, relative, resolve } from 'node:path';
+import { FileAccessError } from '../../../ports/file-access-error.js';
+import { SESSION } from '../contract/session.js';
+import { readSessionHeader } from './session-header.js';
+import { AMBIGUOUS, sessionOwners } from './session-owners.js';
+import { sessionRoots } from './session-roots.js';
+/** Header-only discovery. The caller supplies the supported sessions root; no environment or SQLite access. */
+export class CodexSessionDiscovery {
+    #directories;
+    #files;
+    constructor(dependencies) {
+        this.#directories = dependencies.directories;
+        this.#files = dependencies.files;
+    }
+    /** Explicit file recognition ignores its name and never reads beyond its first line. */
+    readHeader(path) {
+        return readSessionHeader(this.#files, path);
+    }
+    /**
+     * The tree of the conversation `input` names (X5). It is searched for in the supported sessions root when `input` is
+     * inside it, and otherwise in `input`'s own folder only: a copy of a session and the original it was copied from hold
+     * one id, and neither would join anything (X3). A listing of that same folder already taken - by the catalogue that
+     * listed this conversation - is used instead of walking it again.
+     */
+    async tree(input, sessionsRoot, known) {
+        const path = resolve(input);
+        const head = await this.readHeader(path);
+        if (head.kind !== 'recognised')
+            return head;
+        const inside = !relative(resolve(sessionsRoot), path).startsWith('..');
+        const directory = inside ? resolve(sessionsRoot) : dirname(path);
+        const listing = known !== undefined && resolve(known.directory) === directory ? known.listing : await this.list(directory);
+        const byPath = new Map([[path, head.header]]);
+        for (const source of listing.sources)
+            if (!byPath.has(resolve(source.path)))
+                byPath.set(resolve(source.path), source.header);
+        const paths = [...byPath.keys()].sort((a, b) => a.localeCompare(b));
+        const headers = paths.map((each) => byPath.get(each));
+        const owners = sessionOwners(headers.map((header) => (header.id === '' ? undefined : header.id)));
+        const parentOf = (index) => {
+            const parent = headers[index]?.parent;
+            const owner = parent?.kind === 'parent' ? owners.get(parent.id) : undefined;
+            return typeof owner === 'number' ? owner : undefined;
+        };
+        const root = paths.indexOf(path);
+        // A member is a file whose chain of unique parents reaches the root; a cycle or a break ends the walk.
+        const reaches = (start) => {
+            const seen = new Set();
+            for (let at = parentOf(start); at !== undefined && !seen.has(at); at = parentOf(at)) {
+                if (at === root)
+                    return true;
+                seen.add(at);
+            }
+            return false;
+        };
+        const order = [root, ...paths.map((_, index) => index).filter((index) => index !== root && reaches(index))];
+        const position = new Map(order.map((index, at) => [index, at]));
+        const members = order.map((index) => {
+            const parent = index === root ? undefined : position.get(parentOf(index) ?? -1);
+            return { path: paths[index], header: headers[index], ...(parent === undefined ? {} : { parent }) };
+        });
+        return { kind: 'tree', members, rootShared: owners.get(head.header.id) === AMBIGUOUS, gaps: listing.gaps };
+    }
+    async list(directory) {
+        const sources = [];
+        const gaps = [];
+        for await (const { path, read } of this.#rollouts(directory, gaps)) {
+            if (read.kind === 'recognised')
+                sources.push({ path, header: read.header });
+            else
+                gaps.push({ path, reason: read.kind === 'unavailable' ? read.reason : 'unknown-format' });
+        }
+        // Path order is presentation only. Ownership and root resolution are independent of traversal order.
+        sources.sort((a, b) => a.path.localeCompare(b.path));
+        const relations = sessionRoots(sources.map((source) => source.header));
+        return {
+            sources: sources.map((source, index) => ({ ...source, relation: relations[index] })),
+            gaps,
+        };
+    }
+    /** Whether a folder holds at least one Codex session: the walk `list` makes, ended at the first header recognised (X2). */
+    async holdsSession(directory) {
+        for await (const { read } of this.#rollouts(directory, []))
+            if (read.kind === 'recognised')
+                return true;
+        return false;
+    }
+    /** Every rollout under a folder with its first line read, in walk order; a folder that cannot be listed is a gap. */
+    async *#rollouts(directory, gaps) {
+        const pending = [directory];
+        while (pending.length > 0) {
+            const current = pending.pop();
+            if (current === undefined)
+                break;
+            let entries;
+            try {
+                entries = await this.#directories.list(current);
+            }
+            catch (error) {
+                if (!(error instanceof FileAccessError))
+                    throw error;
+                gaps.push({ path: current, reason: error.failure });
+                continue;
+            }
+            for (const entry of entries) {
+                const path = join(current, entry.name);
+                if (entry.kind === 'directory')
+                    pending.push(path);
+                else if (entry.kind === 'file' && entry.name.startsWith(SESSION.filePrefix) && entry.name.endsWith(SESSION.fileSuffix)) {
+                    yield { path, read: await this.readHeader(path) };
+                }
+            }
+        }
+    }
+}

package/dist/adapter/codex/discovery/codex-session-index.js

@@ -0,0 +1,21 @@
+/**
+ * The last listing of the sessions root, taken by a catalogue and reused by the reader for the conversations it listed
+ * (the review of 2026-09-29, `.ai/plans/2026-09-29-what-codex-wrote.md`): the root's headers are read once per listing,
+ * not once per conversation. It is only ever the latest - every listing replaces it - so a thread started since is in
+ * the next one, and nothing is kept past it.
+ */
+export class CodexSessionIndex {
+    #discovery;
+    #latest;
+    constructor(discovery) {
+        this.#discovery = discovery;
+    }
+    async list(directory) {
+        const listing = await this.#discovery.list(directory);
+        this.#latest = { directory, listing };
+        return listing;
+    }
+    latest() {
+        return this.#latest;
+    }
+}

package/dist/adapter/codex/discovery/codex-session-titles.js

@@ -0,0 +1,135 @@
+import { FileAccessError } from '../../../ports/file-access-error.js';
+import { isJsonObject, parseJsonObject } from '../../../shared/json.js';
+import { oneLine } from '../../../shared/printable.js';
+import { ENVELOPE, LINE_TYPES } from '../contract/envelope.js';
+import { MESSAGE, RESPONSE_ITEMS, ROLES, TEXT_BLOCKS } from '../contract/messages.js';
+import { SESSION, THREAD_NAMES } from '../contract/session.js';
+import { RESPONSE_TURN } from '../contract/turns.js';
+/**
+ * What a person recognises a Codex conversation by: the name Codex gave its thread and shows in its own list, from
+ * `session_index.jsonl`, past the redactor. The file is read once, for the whole list; its last line for an id is the
+ * name the thread has now, since a name given again is appended. Where `codex exec` wrote no name, its first prompt
+ * follows a separate environment-context message in measured builds. That prompt can identify the conversation too.
+ */
+export class CodexSessionTitles {
+    #dependencies;
+    #names;
+    #readAt;
+    constructor(dependencies) {
+        this.#dependencies = dependencies;
+    }
+    async recognise(session) {
+        const indexed = (await this.#current()).get(session.id);
+        if (indexed !== undefined)
+            return { title: this.#dependencies.redactor.scan(indexed) };
+        const prompt = await this.#execPrompt(session);
+        if (prompt === undefined)
+            return {};
+        // Scan the entire prompt before shortening it: a cut secret might no longer match the redactor's pattern.
+        const safe = this.#dependencies.redactor.scan(prompt);
+        return { title: this.#dependencies.redactor.scan(Array.from(oneLine(safe)).slice(0, 160).join('')) };
+    }
+    /**
+     * Measured on 21 local `exec` roots (0.155.0-alpha.16.3, 0.157.0, 0.159.2): the first user message is injected
+     * context containing `<environment_context>`; the second, in the same turn, is one `input_text` prompt at line 9.
+     * Stop near the start. An unfamiliar shape has no fallback title instead of guessing from a later message.
+     */
+    async #execPrompt(session) {
+        let lineNumber = 0;
+        let contextTurn;
+        try {
+            for await (const raw of this.#dependencies.files.readLines(session.path)) {
+                if (++lineNumber > 32)
+                    break;
+                const line = parseJsonObject(raw);
+                if (!isJsonObject(line))
+                    return undefined;
+                const payload = line[ENVELOPE.payload];
+                if (!isJsonObject(payload))
+                    return undefined;
+                if (lineNumber === 1) {
+                    if (line[ENVELOPE.type] !== LINE_TYPES.sessionMeta || payload[SESSION.id] !== session.id ||
+                        payload[SESSION.source] !== 'exec' ||
+                        !['0.155.0-alpha.16.3', '0.157.0', '0.159.2'].includes(String(payload[SESSION.version])))
+                        return undefined;
+                    continue;
+                }
+                if (line[ENVELOPE.type] !== LINE_TYPES.responseItem || payload[ENVELOPE.payloadType] !== RESPONSE_ITEMS.message ||
+                    payload[MESSAGE.role] !== ROLES.user)
+                    continue;
+                const metadata = payload[RESPONSE_TURN.metadata];
+                const turn = isJsonObject(metadata) ? metadata[RESPONSE_TURN.turnId] : undefined;
+                const blocks = payload[MESSAGE.content];
+                if (typeof turn !== 'string' || !Array.isArray(blocks))
+                    return undefined;
+                if (contextTurn === undefined) {
+                    if (!blocks.some((block) => {
+                        if (!isJsonObject(block) || block[MESSAGE.blockType] !== TEXT_BLOCKS.given)
+                            return false;
+                        const text = block[MESSAGE.blockText];
+                        return typeof text === 'string' && text.includes('<environment_context>');
+                    }))
+                        return undefined;
+                    contextTurn = turn;
+                    continue;
+                }
+                if (turn !== contextTurn || blocks.length !== 1 || !isJsonObject(blocks[0]) ||
+                    blocks[0][MESSAGE.blockType] !== TEXT_BLOCKS.given)
+                    return undefined;
+                const prompt = blocks[0][MESSAGE.blockText];
+                if (typeof prompt !== 'string')
+                    return undefined;
+                const title = oneLine(prompt);
+                return title === '' ? undefined : title;
+            }
+        }
+        catch (error) {
+            if (!(error instanceof FileAccessError))
+                throw error;
+        }
+        return undefined;
+    }
+    /**
+     * The names as the file holds them now. Codex names a thread a few seconds after it starts (§2.9: 14 s in the
+     * maintainer's run), and a served page lists a conversation started since as it is drawn again - so the file is read
+     * again whenever it changed, and once for every list where it did not. Found by the maintainer: read once per process,
+     * a conversation started a moment before `start` kept "A conversation with no title" on every later drawing.
+     */
+    async #current() {
+        let at;
+        try {
+            at = await this.#dependencies.directories.modifiedAt(this.#dependencies.path);
+        }
+        catch (error) {
+            if (!(error instanceof FileAccessError))
+                throw error;
+        }
+        if (this.#names === undefined || at !== this.#readAt) {
+            this.#readAt = at;
+            this.#names = this.#read();
+        }
+        return this.#names;
+    }
+    async #read() {
+        const names = new Map();
+        try {
+            for await (const line of this.#dependencies.files.readLines(this.#dependencies.path)) {
+                const record = parseJsonObject(line);
+                if (!isJsonObject(record))
+                    continue;
+                const id = record[THREAD_NAMES.id];
+                const name = record[THREAD_NAMES.name];
+                if (typeof id !== 'string' || typeof name !== 'string')
+                    continue;
+                const shown = oneLine(name);
+                if (shown !== '')
+                    names.set(id, shown);
+            }
+        }
+        catch (error) {
+            if (!(error instanceof FileAccessError))
+                throw error;
+        }
+        return names;
+    }
+}

package/dist/adapter/codex/discovery/session-header.js

@@ -0,0 +1,86 @@
+import { FileAccessError } from '../../../ports/file-access-error.js';
+import { isJsonObject, parseJsonObject } from '../../../shared/json.js';
+import { THREAD_SPAWN } from '../contract/delegations.js';
+import { REVIEWER } from '../contract/reviews.js';
+import { HISTORY_MODES, SESSION } from '../contract/session.js';
+/** X2: the first physical line decides recognition. A later metadata line cannot rescue an unknown file. */
+export async function readSessionHeader(files, path) {
+    try {
+        for await (const text of files.readLines(path)) {
+            const header = headerIn(text);
+            return header === undefined ? { kind: 'unknown' } : { kind: 'recognised', header };
+        }
+        return { kind: 'unknown' };
+    }
+    catch (error) {
+        if (error instanceof FileAccessError)
+            return { kind: 'unavailable', reason: error.failure };
+        throw error;
+    }
+}
+function headerIn(text) {
+    const line = parseJsonObject(text);
+    if (line?.[SESSION.lineType] !== SESSION.metadataType)
+        return undefined;
+    const payload = line[SESSION.payload];
+    if (!isJsonObject(payload))
+        return undefined;
+    const id = payload[SESSION.id];
+    if (typeof id !== 'string')
+        return undefined;
+    const issues = [];
+    if (id === '')
+        issues.push('empty-session-id');
+    const directory = payload[SESSION.workingDirectory];
+    const project = typeof directory === 'string' && directory !== '' ? directory : undefined;
+    if (project === undefined)
+        issues.push('project-missing');
+    const parentId = payload[SESSION.parentId];
+    const parent = !(SESSION.parentId in payload)
+        ? { kind: 'root' }
+        : typeof parentId === 'string' && parentId !== ''
+            ? { kind: 'parent', id: parentId }
+            : { kind: 'unknown' };
+    if (parent.kind === 'unknown')
+        issues.push('parent-invalid');
+    const historyMode = HISTORY_MODES.find((mode) => payload[SESSION.historyMode] === mode) ?? 'unknown';
+    if (historyMode === 'unknown')
+        issues.push('history-unrecognised');
+    const version = payload[SESSION.version];
+    return {
+        id,
+        parent,
+        ...(project === undefined ? {} : { project }),
+        historyMode,
+        ...(typeof version === 'string' ? { version } : {}),
+        origin: originOf(payload[SESSION.source]),
+        issues,
+    };
+}
+function originOf(source) {
+    if (typeof source === 'string')
+        return { kind: 'person' };
+    const subagent = isJsonObject(source) ? source[THREAD_SPAWN.subagent] : undefined;
+    if (!isJsonObject(subagent))
+        return { kind: 'unknown' };
+    if (subagent[REVIEWER.other] === REVIEWER.guardian)
+        return { kind: 'reviewer' };
+    const spawn = subagent[THREAD_SPAWN.threadSpawn];
+    return isJsonObject(spawn) ? { kind: 'spawned', ...spawnFacts(spawn) } : { kind: 'unknown' };
+}
+function spawnFacts(spawn) {
+    const text = (key) => {
+        const value = spawn[key];
+        return typeof value === 'string' && value !== '' ? value : undefined;
+    };
+    const depth = spawn[THREAD_SPAWN.depth];
+    const spawnedBy = text(THREAD_SPAWN.parentId);
+    const agentPath = text(THREAD_SPAWN.agentPath);
+    const role = text(THREAD_SPAWN.role);
+    return {
+        ...(spawnedBy === undefined ? {} : { spawnedBy }),
+        ...(typeof depth === 'number' && Number.isInteger(depth) && depth >= 0 ? { depth } : {}),
+        ...(agentPath === undefined ? {} : { agentPath }),
+        ...(role === undefined ? {} : { role }),
+    };
+}

package/dist/adapter/codex/discovery/session-owners.js

@@ -0,0 +1,11 @@
+/** An id owned by multiple files must resolve to none, regardless of traversal order (X3). */
+export const AMBIGUOUS = Symbol('held by more than one file');
+/** Used by runtime discovery and the reconnaissance probe, so they cannot choose different owners. */
+export function sessionOwners(ids) {
+    const owners = new Map();
+    ids.forEach((id, index) => {
+        if (id !== undefined)
+            owners.set(id, owners.has(id) ? AMBIGUOUS : index);
+    });
+    return owners;
+}