@agentwhy/cli 0.0.0-dev

package/dist/adapter/claude-code/contract/entry-points.js

@@ -0,0 +1,15 @@
+/**
+ * Which way into Claude Code a session was started by, as its transcript records it in `entrypoint` - by the words a
+ * person knows it by (`.ai/specs/2026-09-27-which-project.md` V4). These are the values Claude Code also gives its hooks
+ * as `CLAUDE_CODE_ENTRYPOINT` (`the-agent-tells-you.md` B9e2: terminal `claude`, the editor extension, `claude -p`).
+ *
+ * Measured, not guessed (which-project VB5, 2026-09-28): the last megabyte of each of 244 transcripts carries the field,
+ * `claude-vscode` in 180, `cli` in 62, `sdk-cli` in 2, and no transcript carries two values. No other value has been
+ * seen: one that is not listed here is said to be unknown, never read as the nearest of these. What the extension writes
+ * inside Cursor, and the plugin inside JetBrains, is not measured (VB4), so `editor` is a code editor and not "VS Code".
+ */
+export const ENTRY_POINT_VALUES = {
+    terminal: 'cli',
+    editor: 'claude-vscode',
+    script: 'sdk-cli',
+};

package/dist/adapter/claude-code/contract/fields.js

@@ -0,0 +1,73 @@
+export const FIELDS = {
+    lineType: 'type',
+    sidechain: 'isSidechain',
+    denialKind: 'toolDenialKind',
+    toolUseResult: 'toolUseResult',
+    resultSourceAssistant: 'sourceToolAssistantUUID',
+    toolVersion: 'version',
+    /** The session's working directory: the project root a report makes paths relative to. On conversation lines only. */
+    workingDirectory: 'cwd',
+    /** Which way into Claude Code the session was started by: the values of `entry-points.ts`. On conversation lines. */
+    entryPoint: 'entrypoint',
+    /**
+     * When the line was written: ISO 8601 in UTC with milliseconds. For display only (the report page spec M4) - a line
+     * can be earlier than the one before it, so it never orders or joins anything (architecture invariant 3).
+     */
+    recordedAt: 'timestamp',
+    systemSubtype: 'subtype',
+    message: 'message',
+    messageContent: 'content',
+    blockType: 'type',
+    toolName: 'name',
+    toolInput: 'input',
+    blockContent: 'content',
+    messageRole: 'role',
+    agentId: 'agentId',
+    /** The id of a tool_use block: what a result names to say which call it answers. */
+    blockId: 'id',
+    /** On a tool_result block, the id of the call it answers - the join of §4.3 rule 1. */
+    resultCallId: 'tool_use_id',
+    /** On a tool_result block, `true` when the tool answered with an error rather than a result. */
+    resultIsError: 'is_error',
+    /** On a text block, the words themselves. */
+    blockText: 'text',
+    /** On a reasoning block, the words themselves. The field carries the block's own name. */
+    blockThinking: 'thinking',
+};
+/**
+ * How a subagent hands its report back when it does not write it as a message: a call of its own, whose input
+ * carries the words (`.ai/specs/2026-09-16-when-an-agent-finishes.md` D9).
+ *
+ * Measured, not guessed (`.ai/skills/update-format-contract/SKILL.md` step 1), on a session
+ * of 2026-09-19 (Claude Code 2.x auto mode): 2 calls, both on sidechain lines, one input key
+ * - `message` - holding a string. The call names no delegation, so the join is the one the subagent's own index
+ * entry already makes: the report belongs to the delegation that started the agent whose transcript it is on.
+ */
+export const HANDBACK_TOOL = {
+    name: 'SubagentHandback',
+    reportInputKey: 'message',
+};
+export const TOOL_USE_BLOCK_TYPE = 'tool_use';
+export const TOOL_RESULT_BLOCK_TYPE = 'tool_result';
+/** What an agent writes, as opposed to what it calls: a block of its own on an assistant line. */
+export const TEXT_BLOCK_TYPE = 'text';
+/** What an agent works out before it calls, in its own words (`specs/2026-09-15-why-this-call.md` R1). */
+export const THINKING_BLOCK_TYPE = 'thinking';
+export const AGENT_TOOL = {
+    name: 'Agent',
+    inputKeys: ['description', 'prompt', 'subagent_type'],
+    optionalInputKeys: ['run_in_background'],
+    /** The one input key whose value is an enumeration - the agent type - rather than free text. */
+    typeInputKey: 'subagent_type',
+    promptInputKey: 'prompt',
+    descriptionInputKey: 'description',
+};
+export const META_FIELD = {
+    agentType: 'agentType',
+    description: 'description',
+    toolUseId: 'toolUseId',
+    spawnDepth: 'spawnDepth',
+    requestShape: 'requestShape',
+    requestNonInteractive: 'requestNonInteractive',
+};
+export const META_KEYS = Object.values(META_FIELD);

package/dist/adapter/claude-code/contract/hooks.js

@@ -0,0 +1,96 @@
+/**
+ * What a Claude Code hook is handed and what it may hand back (`specs/2026-09-16-when-an-agent-finishes.md` §2).
+ *
+ * Read from the hooks reference on 2026-09-16, and **measured the same day** (B4, spec §3.1): on 4 of 4 real
+ * `SubagentStop` inputs every field below was present and `agent_id` was the id in the agent's file name. A change
+ * goes through `update-format-contract`.
+ */
+/**
+ * The field every hook input carries, whichever event it was: where the session is running. Measured on 5 of 5 real
+ * `Stop` inputs (`the-agent-nobody-watches.md` B8b) and present on the `SubagentStop` inputs of B4. It is what says
+ * which project a session belongs to before anything of that session has been read.
+ */
+export const HOOK_INPUT = {
+    fields: { workingDirectory: 'cwd' },
+};
+export const SUBAGENT_STOP = {
+    event: 'SubagentStop',
+    fields: {
+        event: 'hook_event_name',
+        /** The main session's transcript: D2. */
+        transcriptPath: 'transcript_path',
+        /** The id in the agent's own file name, `agent-<id>.jsonl`: B4b, 4 of 4. */
+        agentId: 'agent_id',
+        /** The agent's final text. B4c: not yet on disk when the hook ran, on 4 of 4 agents. */
+        lastMessage: 'last_assistant_message',
+        /** The session the agent belongs to: what an alert is remembered under until its turn ends. */
+        sessionId: 'session_id',
+    },
+};
+/**
+ * What a `Stop` hook is handed, and the event that shows a `systemMessage`
+ * (`specs/2026-09-16-a-notice-in-the-conversation.md` §3a, B6a). Measured on v2.1.236: the field is rendered under
+ * the assistant's reply as `Stop says: …`, and B6b found it absent from the model's context.
+ */
+export const STOP = {
+    event: 'Stop',
+    fields: {
+        event: 'hook_event_name',
+        sessionId: 'session_id',
+        /**
+         * That this hook run is already inside a continuation it caused before (D15). Measured `true` on the `Stop`
+         * that ended such a continuation and `false` on the next turn's (B9c), so it is what keeps one notice from
+         * becoming a loop.
+         */
+        active: 'stop_hook_active',
+    },
+};
+/**
+ * What a `PreToolUse` hook on the shell is handed (`specs/2026-09-16-worth-running-every-day.md` R18, R19). **Documented,
+ * not measured**: B7 of that specification records what a real input carries and what exit 2 does.
+ */
+export const PRE_TOOL_USE = {
+    event: 'PreToolUse',
+    fields: {
+        event: 'hook_event_name',
+        toolName: 'tool_name',
+        toolInput: 'tool_input',
+        /** Inside `tool_input` for the shell tool. */
+        command: 'command',
+        /** Where the shell is when the command runs: what `.` and a glob in it are read against. */
+        cwd: 'cwd',
+    },
+    /** The one tool `refuse` reads a command line from. */
+    shellTool: 'Bash',
+};
+/**
+ * The universal output fields a hook's JSON on stdout may carry to reach a person. `systemMessage` is documented as a
+ * warning shown to the user (D5): from `SubagentStop` it reached neither the user nor the model (B4d, B4f), and from
+ * `Stop` it reached the user and not the model (B6a, B6b). `terminalSequence` showed in the terminal interface (B4f).
+ */
+export const HOOK_OUTPUT = {
+    systemMessage: 'systemMessage',
+    terminalSequence: 'terminalSequence',
+    /**
+     * What keeps a turn from ending and hands `reason` to the session's own agent, returned with exit 0
+     * (`the-agent-tells-you.md` D16). Measured on v2.1.236: the agent answers it in a message of its own, and the
+     * person sees the reason too, framed by Claude Code as `Stop hook error:` (B9a).
+     */
+    decision: 'decision',
+    block: 'block',
+    reason: 'reason',
+};
+/**
+ * The escape sequences the reference allows in `terminalSequence`. Anything outside the allowlist makes Claude Code
+ * ignore the whole field, so a control character inside the words would silence the notice.
+ */
+export const TERMINAL = {
+    osc: '\u001b]',
+    bel: '\u0007',
+    /** iTerm2, Windows Terminal, WezTerm, ConEmu: `9;<text>`. */
+    notify: '9',
+    /** urxvt, Ghostty, Warp: `777;notify;<title>;<body>`. */
+    notifyWithTitle: '777;notify',
+};
+/** A path the reference writes with a leading `~/` in its examples. Expanded rather than read as relative. */
+export const HOME_PREFIX = '~/';

package/dist/adapter/claude-code/contract/identifiers.js

@@ -0,0 +1,15 @@
+const TOOL_USE_ID = /toolu_[A-Za-z0-9]{20,}/g;
+const UUID = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/g;
+const AGENT_ID = /^(agent-)?a[0-9a-f]{16}$/;
+/**
+ * The id of a subagent, as it appears in a file name and in the `agentId` field of its lines. An identifier, not
+ * content: spec §5.4 already excludes this shape from the entropy class. Whole-value match only, so a longer
+ * string that merely contains one is not mistaken for an identifier.
+ */
+export function isAgentId(value) {
+    return AGENT_ID.test(value);
+}
+/** Identifier shapes that the secret scanner must never mistake for secrets (lesson L001). */
+export function identifierMatches(text) {
+    return { toolUseIds: text.match(TOOL_USE_ID) ?? [], uuids: text.match(UUID) ?? [] };
+}

package/dist/adapter/claude-code/contract/layout.js

@@ -0,0 +1,29 @@
+export const LAYOUT = {
+    transcriptSuffix: '.jsonl',
+    subagentsDir: 'subagents',
+    toolResultsDir: 'tool-results',
+    toolResultSuffix: '.txt',
+};
+const SUBAGENT_FILE_SUFFIX = {
+    transcript: '.jsonl',
+    meta: '.meta.json',
+};
+const SUBAGENT_FILE = /^agent-([A-Za-z0-9]+)(\.jsonl|\.meta\.json)$/;
+const TOOL_RESULT_REFERENCE = /tool-results\/([A-Za-z0-9_-]+\.txt)/g;
+export function parseSubagentFileName(name) {
+    const match = SUBAGENT_FILE.exec(name);
+    const fileId = match?.[1];
+    if (fileId === undefined)
+        return undefined;
+    return { fileId, kind: match?.[2] === SUBAGENT_FILE_SUFFIX.meta ? 'meta' : 'transcript' };
+}
+export function subagentFileName(fileId, kind) {
+    return `agent-${fileId}${SUBAGENT_FILE_SUFFIX[kind]}`;
+}
+export function isToolResultFileName(name) {
+    return name.endsWith(LAYOUT.toolResultSuffix);
+}
+/** File names of spilled results that a piece of transcript text points at. */
+export function toolResultReferences(text) {
+    return Array.from(text.matchAll(TOOL_RESULT_REFERENCE), (match) => match[1] ?? '').filter((name) => name !== '');
+}

package/dist/adapter/claude-code/contract/line-types.js

@@ -0,0 +1,26 @@
+export const CONVERSATION_LINE_TYPES = ['user', 'assistant'];
+export const SKIPPED_LINE_TYPES = [
+    'attachment',
+    'queue-operation',
+    'atis-latch',
+    'last-prompt',
+    'ai-title',
+    'system',
+    'file-history-snapshot',
+    'file-history-delta',
+    'bridge-session',
+];
+export const SYSTEM_LINE_TYPE = 'system';
+/** The line an agent writes on. A user line carries text blocks too, and they are not the agent's words. */
+export const ASSISTANT_LINE_TYPE = 'assistant';
+/** The line a result arrives on, and a report delivered late. Its words are not the words of the agent it reaches. */
+export const USER_LINE_TYPE = 'user';
+export function classifyLineType(type) {
+    if (typeof type !== 'string')
+        return 'unknown';
+    if (CONVERSATION_LINE_TYPES.includes(type))
+        return 'conversation';
+    if (SKIPPED_LINE_TYPES.includes(type))
+        return 'skipped';
+    return 'unknown';
+}

package/dist/adapter/claude-code/contract/projects.js

@@ -0,0 +1,23 @@
+/**
+ * Where a project's sessions live: `~/.claude/projects/<encoded working directory>/`.
+ *
+ * The encoding replaces **every run of non-alphanumeric characters** with a single hyphen, not only the path
+ * separators. Corrected on 2026-09-14 by the first real use outside this repository: a project under
+ * `…/Web Portal/…` is stored as `…-Web-Portal-…`, and a rule that only replaced separators looked in a
+ * directory that does not exist and reported "no sessions" for a project with plenty.
+ *
+ * The rule is still inferred from examples, so it is not trusted on its own: `matches` lets a caller compare an
+ * existing directory name against a working directory, and the catalogue falls back to scanning. An encoding
+ * we have not seen costs a slower lookup, not a wrong answer.
+ */
+export const PROJECTS_DIRECTORY = ['.claude', 'projects'];
+export function projectDirectoryName(workingDirectory) {
+    return normalise(workingDirectory);
+}
+/** Whether this stored directory is the one for that working directory, whatever else the encoder did to it. */
+export function matchesProject(directoryName, workingDirectory) {
+    return normalise(directoryName) === normalise(workingDirectory);
+}
+function normalise(text) {
+    return text.replace(/[^A-Za-z0-9]+/g, '-');
+}

package/dist/adapter/claude-code/contract/recognition.js

@@ -0,0 +1,14 @@
+/**
+ * What makes a file a Claude Code transcript by its content (`2026-09-27-what-codex-wrote.md` X2): its first non-blank
+ * line is a JSON object with a string `type`, and either a string `sessionId` or a `type` the contract lists.
+ *
+ * Measured 2026-09-29 over the first lines of 257 main transcripts, printing only fixed labels and counts: a string
+ * `type` in 257, a string `sessionId` equal to the file's own name in 257, a `payload` in none; the `type` was one the
+ * contract lists in 193 and another in 64 - which is why the id, not the type, carries the rule. The hand-built
+ * fixtures carry a listed type and no `sessionId`, and are recognised by the second half. A Codex rollout's first line
+ * is `session_meta` with a `payload` and no `sessionId`, so the two rules never both hold.
+ */
+export const RECOGNITION = {
+    lineType: 'type',
+    sessionId: 'sessionId',
+};

package/dist/adapter/claude-code/contract/session-title.js

@@ -0,0 +1,20 @@
+/**
+ * The title Claude Code gives a session - the one its own session list shows. Measured for contract v7: every
+ * `ai-title` line of the measured session is `{type, aiTitle, sessionId}` with a string `aiTitle`, and the title
+ * is written again as the session goes on, so the last such line is the latest.
+ *
+ * A model writes it from what the user typed. That makes it **content**, not structure (lesson L009): it crosses
+ * the redaction boundary before anything shows it (spec §13.2, pitfall 7).
+ */
+export const SESSION_TITLE = {
+    lineType: 'ai-title',
+    field: 'aiTitle',
+    /**
+     * How much of the end of a transcript is read to find it. In the corpus, the redacted measured session, the last
+     * title ended 17 KB before the end of the file and no two titles were more than 30 KB apart. Redaction changes the
+     * length of content, so those distances are indicative, and the window is a megabyte - a session smaller than that
+     * is read whole. A session whose last title lies further back shows no title, which a person can see, rather than
+     * an older one.
+     */
+    tailBytes: 1024 * 1024,
+};

package/dist/adapter/claude-code/contract/settings.js

@@ -0,0 +1,27 @@
+/**
+ * Where a project keeps Claude Code settings, and how hooks are written in them (`specs/2026-09-16-worth-running-every-day.md`
+ * R4-R8). **Documented, not measured** against this project's oracle: read from the settings and hooks references.
+ */
+export const SETTINGS_FILES = {
+    directory: '.claude',
+    /** Shared with everyone who clones the project. `init` reads deny rules here and never writes. */
+    shared: 'settings.json',
+    /** One person's, kept out of the repository by Claude Code. The only file `init` writes. */
+    local: 'settings.local.json',
+};
+export const HOOK_SETTINGS = {
+    hooks: 'hooks',
+    /** One entry of an event's list: an optional matcher, and the commands it runs. */
+    matcher: 'matcher',
+    commands: 'hooks',
+    type: 'type',
+    commandType: 'command',
+    command: 'command',
+    /** The variable a hook command is expanded with, naming the project it runs for. */
+    projectDirectory: '$CLAUDE_PROJECT_DIR',
+};
+/** Where a settings file keeps the rules that refuse a tool call (`specs/2026-09-13-agentwhy-spec.md` §6.1). */
+export const PERMISSIONS = {
+    permissions: 'permissions',
+    deny: 'deny',
+};

package/dist/adapter/claude-code/contract/task-notifications.js

@@ -0,0 +1,33 @@
+/**
+ * A report delivered late (`specs/2026-09-15-where-the-value-went.md` R1, R5). An agent started in the background
+ * answers its delegating call with a launch notice, and its report reaches the calling agent afterwards, in a
+ * notification on a user line of its own. A `queue-operation` line queues the same words first; it is not a delivery,
+ * since a queued line can be removed, and it stays skipped.
+ */
+export const TASK_NOTIFICATION = {
+    opening: '<task-notification>',
+    closing: '</task-notification>',
+    /** The tag holding the id of the call a notification answers: a delegating call's, 6 of 6 measured. */
+    callIdTag: 'tool-use-id',
+};
+/** On a delegating result's payload: the field, and the value that makes the result a launch notice. */
+export const LAUNCH_NOTICE = {
+    statusField: 'status',
+    launchedStatus: 'async_launched',
+};
+const CALL_ID = new RegExp(`<${TASK_NOTIFICATION.callIdTag}>\\s*([^<\\s]+)\\s*</${TASK_NOTIFICATION.callIdTag}>`);
+/** Every notification in a line's words, in the order written. */
+export function notificationsIn(words) {
+    const { opening, closing } = TASK_NOTIFICATION;
+    const notifications = [];
+    for (let from = words.indexOf(opening); from !== -1;) {
+        const next = words.indexOf(opening, from + opening.length);
+        const close = words.indexOf(closing, from);
+        const end = close !== -1 && (next === -1 || close < next) ? close + closing.length : next === -1 ? words.length : next;
+        const text = words.slice(from, end);
+        const callId = CALL_ID.exec(text)?.[1];
+        notifications.push(callId === undefined ? { text } : { callId, text });
+        from = next;
+    }
+    return notifications;
+}

package/dist/adapter/claude-code/contract/tools.js

@@ -0,0 +1,37 @@
+function profile(pathKeys, commandKeys, result, writes) {
+    return { pathKeys, commandKeys, searchWholeInput: false, result, ...(writes === undefined ? {} : { writes }) };
+}
+export const TOOL_PROFILES = {
+    Read: profile(['file_path'], [], 'content'),
+    Edit: profile(['file_path'], [], 'none', { removedTextKeys: ['old_string'] }),
+    Write: profile(['file_path'], [], 'none', { removedTextKeys: [] }),
+    NotebookEdit: profile(['notebook_path'], [], 'none'),
+    Bash: profile([], ['command'], 'listing'),
+    Grep: profile(['path'], [], 'listing'),
+    Glob: profile(['path'], [], 'listing'),
+    Agent: profile([], [], 'none'),
+    Skill: profile([], [], 'none'),
+    ToolSearch: profile([], [], 'none'),
+    WebFetch: profile([], [], 'none'),
+    WebSearch: profile([], [], 'none'),
+};
+/**
+ * An unknown tool is treated as the noisiest possibility rather than passed over: everything it was given may
+ * name a target, and its result may enumerate what it reached. Callers are told the tool was not recognised, so
+ * a report can say so instead of presenting the guess as knowledge.
+ */
+export const UNKNOWN_TOOL = { pathKeys: [], commandKeys: [], searchWholeInput: true, result: 'listing' };
+export function profileOf(toolName) {
+    // `Object.hasOwn`, because a tool named `toString` or `constructor` would otherwise find something on the
+    // prototype, report itself as known, and hand back a profile with no keys at all.
+    if (!Object.hasOwn(TOOL_PROFILES, toolName))
+        return { profile: UNKNOWN_TOOL, known: false };
+    const profile = TOOL_PROFILES[toolName];
+    return profile === undefined ? { profile: UNKNOWN_TOOL, known: false } : { profile, known: true };
+}
+/**
+ * The Grep tool prints the lines it matched only when its input asks for them; by default it prints file names
+ * (`search-hits-are-reads` H1). Measured on the maintainer's transcripts of 2026-09-24: no call of it at all - every
+ * search there went through the shell - so this is written from the tool's documented input, not from a record.
+ */
+export const GREP_TOOL = { name: 'Grep', outputModeKey: 'output_mode', contentMode: 'content' };

package/dist/adapter/claude-code/contract/version.js

@@ -0,0 +1,51 @@
+// The format contract: the only code that knows the Claude Code transcript format, one subject per file in this
+// directory. Everything here was measured against a real session (spec §4.0, tests/fixtures/oracle.json). When
+// `agentwhy doctor` reports drift, follow .ai/skills/update-format-contract/SKILL.md instead of patching callers.
+// v1 (2026-09-12): measured on a live Claude Code 2.1.268 session. v2 (2026-09-13): re-measured on a copy of it;
+// `bridge-session` classified as skipped, `run_in_background` recorded as an optional Agent input key.
+// v3 (2026-09-13): `role`, `subagent_type` and the subagent id recorded as structure rather than content, so the
+// corpus keeps them and M1 can assert the file-id-to-agentId relation on it.
+// v4 (2026-09-13): the two identifier fields the M1 join needs - a tool_use block's `id` and a tool_result
+// block's `tool_use_id`, measured as present on 373 of 373 result lines.
+// v5 (2026-09-14): `cwd`, the session working directory, recorded as a per-line field. It is the project root
+// that the display paths of `specs/2026-09-14-path-display-and-share.md` are relative to, so where it comes from is
+// contract knowledge rather than something a renderer works out.
+// v6 (2026-09-15): the text block of an assistant line - what an agent writes - measured as 149 of 149 carrying a
+// string `text`, never beside a tool_use; and a delegating call's result as a list of text blocks, 15 of 15 on the
+// measured session. `specs/2026-09-15-what-came-back.md` R1 and R1b need both: a delegated agent's report is one of each.
+// v7 (2026-09-15): the session title - `aiTitle` on the `ai-title` line - measured as a string on 82 of 82 such
+// lines. `sessions` shows it, redacted, so that a person choosing a session can tell one from another.
+// v8 (2026-09-15): the reasoning block of an assistant line - what an agent works out before it calls - measured
+// as 249 of 249 carrying a string `thinking`, with the keys type, thinking and signature.
+// `specs/2026-09-15-why-this-call.md` R1 needs it: the answer to "why this call" is written there, by the agent itself.
+// v9 (2026-09-15): a report delivered late - a <task-notification> on a user line naming the delegating call by its
+// tool-use-id, 6 of 6 on the measured session - and the payload status async_launched that makes a delegating result a
+// launch notice, 6 of 15. `specs/2026-09-15-where-the-value-went.md` R1 and R5 need both: the motivating case's value
+// came back on such a report, and was read from the notice. And which tools write a file, with the key of the text an edit takes
+// out - Edit 45 of 45, Write 7 of 7 - so a value only in that text is not said to have been written (R7).
+// v10 (2026-09-19): `SubagentHandback` - how a subagent hands its report back in auto mode from v2.1.271, as one
+// call of its own whose input key `message` holds the words. Measured on a session of
+// 2026-09-19: 2 calls, both on sidechain lines, one input key, a string of 200-999 characters. This closes the gap
+// `.ai/specs/2026-09-16-when-an-agent-finishes.md` states as D9 and §6.1: until now a report delivered that way was
+// read by nothing, so `what came back` measured the wrong text and a value that did reach the delegating agent was
+// reported as never having left the one that read it.
+// v11 (2026-09-23): `timestamp`, when a line was written, recorded as a per-line field for display only (the report page
+// spec M4, Q1). Measured on three sessions of Claude Code 2.1.280: on every
+// assistant, user, attachment, queue-operation, file-history-delta and system line of the main transcripts and every
+// line of 2 subagent transcripts, always a string of ISO 8601 in UTC with milliseconds, all of which parse; absent on
+// ai-title, atis-latch, last-prompt, cost-state and file-history-snapshot lines. 54 of 4020 consecutive pairs within
+// one file run backwards in time - which is why it is shown and never used to order or join.
+// v12 (2026-09-28): `entrypoint`, which way into Claude Code a session was started by, recorded with its three measured
+// values (`entry-points.ts`); and `cwd` corrected - one session can carry more than one. Measured over the last megabyte
+// of 244 transcripts (`.ai/specs/2026-09-27-which-project.md` VB5): `entrypoint` in all 244, one value each; `cwd` in all
+// 244, a value matching the project directory's name in all 244, and more than one value in 14. The list of a person's
+// projects reads both (V4, V9): the value that names the project is the matching one, never the last.
+// v13 (2026-09-29): recognition by content (`recognition.ts`), so a Codex rollout is never read as a transcript
+// (`.ai/specs/2026-09-27-what-codex-wrote.md` X2, XD7). Measured over the first lines of 257 main transcripts: a string
+// `type` and a string `sessionId` equal to the file's name in all 257; a listed `type` in 193.
+export const CONTRACT_VERSION = 13;
+export const VERIFIED_AGAINST = {
+    claudeCode: '2.1.268',
+    session: '951c4f76-9d2a-40d2-9c76-1e57cf47ae4e',
+    date: '2026-09-13',
+};

package/dist/adapter/claude-code/discovery/claude-code-project-catalogue.js

@@ -0,0 +1,129 @@
+import { join } from 'node:path';
+import { FileAccessError } from '../../../ports/file-access-error.js';
+import { LAYOUT } from '../contract/layout.js';
+import { PROJECTS_DIRECTORY, matchesProject } from '../contract/projects.js';
+import { SESSION_TITLE } from '../contract/session-title.js';
+import { recognitionIn, workingDirectoryIn } from './transcript-tail.js';
+/**
+ * How many transcripts of one project are read, newest first, to find its folder. The newest said it for 14 of 14
+ * projects measured (`which-project.md` VB5); a session begun a moment ago may not have a conversation line yet.
+ */
+const READS_PER_PROJECT = 3;
+/**
+ * How many projects are read at once. Each holds up to a megabyte of a transcript's end, and a descriptor for it, until
+ * it answers; every project at once would hold all of that at the same moment, as `start`'s titles would.
+ */
+const PROJECTS_AT_ONCE = 8;
+/**
+ * The projects Claude Code keeps conversations for, under `~/.claude/projects/` (`.ai/specs/2026-09-27-which-project.md`
+ * V9). A directory's name is a lossy encoding of the project's path (§13.2 pitfall 6), so the path is the `cwd` a
+ * conversation carries that matches the name - one conversation can carry several (contract v12) - and a directory whose
+ * conversations carry none is counted, never decoded. One transcript's end is read per project, the newest, and one or
+ * two more only where it does not say the folder.
+ */
+export class ClaudeCodeProjectCatalogue {
+    #dependencies;
+    constructor(dependencies) {
+        this.#dependencies = dependencies;
+    }
+    async list() {
+        const root = join(this.#dependencies.home, ...PROJECTS_DIRECTORY);
+        let entries;
+        try {
+            entries = await this.#dependencies.directories.list(root);
+        }
+        catch (error) {
+            if (!(error instanceof FileAccessError))
+                throw error;
+            // No conversations kept on this computer at all is an answer, not a failure.
+            return { projects: [], unreadable: 0 };
+        }
+        const directories = entries.filter((entry) => entry.kind === 'directory');
+        const found = [];
+        for (let from = 0; from < directories.length; from += PROJECTS_AT_ONCE) {
+            const batch = directories.slice(from, from + PROJECTS_AT_ONCE);
+            found.push(...(await Promise.all(batch.map((entry) => this.#project(join(root, entry.name), entry.name)))));
+        }
+        const projects = found.filter((project) => project !== undefined && project !== 'unreadable');
+        const unreadable = found.filter((project) => project === 'unreadable').length;
+        return { projects: projects.sort((a, b) => b.newest.modifiedAt - a.newest.modifiedAt), unreadable };
+    }
+    /** One directory as a project; `undefined` where it keeps no conversation, `unreadable` where none says the folder. */
+    async #project(directory, id) {
+        const transcripts = await this.#transcripts(directory);
+        const newest = transcripts[0];
+        if (newest === undefined)
+            return undefined;
+        let path;
+        let recognised = {};
+        for (const [at, transcript] of transcripts.slice(0, READS_PER_PROJECT).entries()) {
+            const tail = await this.#tail(transcript.path);
+            if (tail === undefined)
+                continue;
+            if (at === 0)
+                recognised = recognitionIn(tail, this.#dependencies.redactor);
+            path = workingDirectoryIn(tail, (cwd) => matchesProject(id, cwd));
+            if (path !== undefined)
+                break;
+        }
+        if (path === undefined)
+            return 'unreadable';
+        return {
+            id,
+            path,
+            exists: await this.#isDirectory(path),
+            conversations: transcripts.length,
+            newest: { modifiedAt: newest.modifiedAt, ...recognised },
+        };
+    }
+    /** The directory's transcripts, newest first. The files inside a session's own directory are not conversations. */
+    async #transcripts(directory) {
+        const { directories } = this.#dependencies;
+        let entries;
+        try {
+            entries = await directories.list(directory);
+        }
+        catch (error) {
+            if (!(error instanceof FileAccessError))
+                throw error;
+            return [];
+        }
+        const found = await Promise.all(entries
+            .filter((entry) => entry.kind === 'file' && entry.name.endsWith(LAYOUT.transcriptSuffix))
+            .map(async (entry) => {
+            const path = join(directory, entry.name);
+            return { path, modifiedAt: await this.#modifiedAt(path) };
+        }));
+        return found.sort((a, b) => b.modifiedAt - a.modifiedAt);
+    }
+    async #tail(path) {
+        try {
+            return await this.#dependencies.transcripts.readTail(path, SESSION_TITLE.tailBytes);
+        }
+        catch (error) {
+            if (!(error instanceof FileAccessError))
+                throw error;
+            return undefined;
+        }
+    }
+    async #modifiedAt(path) {
+        try {
+            return await this.#dependencies.directories.modifiedAt(path);
+        }
+        catch (error) {
+            if (!(error instanceof FileAccessError))
+                throw error;
+            return 0;
+        }
+    }
+    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/claude-code/discovery/claude-code-recognition.js

@@ -0,0 +1,46 @@
+import { resolve } from 'node:path';
+import { FileAccessError } from '../../../ports/file-access-error.js';
+import { parseJsonObject } from '../../../shared/json.js';
+import { LAYOUT } from '../contract/layout.js';
+import { classifyLineType } from '../contract/line-types.js';
+import { RECOGNITION } from '../contract/recognition.js';
+/** How many damaged lines before the first that parses recognition passes over, so a file of noise is not read whole. */
+const DAMAGED_LINES_SKIPPED = 8;
+/**
+ * Whether an input is a Claude Code session, by its main transcript's first non-blank line that parses (`recognition.ts`).
+ * The input is named as `ClaudeCodeSessionDiscovery` names it - a session directory or its `.jsonl` - and nothing past
+ * that line is read. A line that does not parse says how a write failed, not which format wrote it, and diagnosing it is
+ * `doctor`'s job, so up to `DAMAGED_LINES_SKIPPED` of them are passed over; a file of nothing else stays unknown. A
+ * transcript that is not there is `unavailable`, which `doctor` still reports on as Claude Code's.
+ */
+export async function recogniseClaudeCode(files, input) {
+    const target = resolve(input);
+    const transcript = target.endsWith(LAYOUT.transcriptSuffix) ? target : target + LAYOUT.transcriptSuffix;
+    let damaged = 0;
+    try {
+        for await (const text of files.readLines(transcript)) {
+            if (text.trim() === '')
+                continue;
+            const line = parseJsonObject(text);
+            if (line === undefined) {
+                damaged += 1;
+                if (damaged > DAMAGED_LINES_SKIPPED)
+                    return 'unknown';
+                continue;
+            }
+            return isClaudeLine(line) ? 'recognised' : 'unknown';
+        }
+        return 'unknown';
+    }
+    catch (error) {
+        if (error instanceof FileAccessError)
+            return 'unavailable';
+        throw error;
+    }
+}
+function isClaudeLine(line) {
+    const type = line[RECOGNITION.lineType];
+    if (typeof type !== 'string')
+        return false;
+    return typeof line[RECOGNITION.sessionId] === 'string' || classifyLineType(type) !== 'unknown';
+}