@agentwhy/cli 0.0.0-dev → 0.2.0

package/LICENSE

@@ -187,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2026 Nessprim Karol Kozer
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.md

@@ -17,12 +17,47 @@
   One command · runs on your computer · sends nothing anywhere · <a href="LICENSE">Apache 2.0</a>
 </p>
 
+<p align="center">
+  <img src="docs/screenshots/landing.png" alt="agentwhy: Your AI opens your files. Now you'll know which ones." width="820">
+</p>
+
 ---
 
 ## What you see
 
 You run one command in your project. A page opens in your browser. Most days it says there is nothing to do.
-When there is, it looks like this:
+When there is, it tells you what to fix. The pictures below are of a demo project.
+
+**Conversations.** Every time your AI worked for you this week, and which of those times it read something private.
+
+![The Conversations page: nine conversations this week, three of them marked as needing attention](docs/screenshots/conversations.png)
+
+**Your to-do list.** One conversation, opened: the private file your AI read, and a **Fix it** button that walks you
+through making it safe.
+
+![The to-do list of one conversation: a private .env file was opened, with a Fix it button](docs/screenshots/to-do-list.png)
+
+**What happened.** The story of one file, step by step: who read it, where it was repeated, and where it ended up.
+
+![What happened to this file, as a story: a helper read the keys, repeated them in a message and passed them back](docs/screenshots/what-happened-story.png)
+
+The same story as a diagram, from your request to the file:
+
+![What happened to this file, as a diagram: you, your AI, a helper, the .env file, and the point where it was exposed](docs/screenshots/what-happened-diagram.png)
+
+And as the full record, one line for every time the file was opened:
+
+![What happened to this file, as the full record: a table of each event with its time, tool and result](docs/screenshots/what-happened-full-record.png)
+
+**Files.** Everything your AI opened, with the private files on top and whether each one is blocked.
+
+![The Files page: four files opened, one of them private](docs/screenshots/files.png)
+
+**How it went.** The helpers your AI brought in, and which of them saw your private files.
+
+![The How it went page: your AI gave work to one helper, which read the .env file](docs/screenshots/helpers.png)
+
+In the terminal, the same kind of finding looks like this:
 
 ```
   the session itself · 4 actions · 1 file reached · wrote the value into files
@@ -103,8 +138,13 @@ In Claude Code, it stops the obvious routes: `init` adds rules for Claude Code's
 refuses shell commands like `cat .env` or `grep -r` over a private file. It is not a sandbox. A path in a variable or a
 script can still get through, and that is why the main job is telling you what actually happened. In Codex the same
 check runs as a Codex hook, with the same list of files. When it blocks a command, a second hook asks Codex to explain
-the block in its reply in the terminal or code editor, without asking you to paste a secret. Codex runs new or changed
-hooks only after you approve them there: until then, it skips them without a word.
+the block in its reply in the terminal or code editor, without asking you to paste a secret. The check is written into
+your own `~/.codex/hooks.json` and approved by agentwhy itself in `~/.codex/config.toml` - its own two entries and
+nothing else, and no folder is marked trusted - because Codex skips an unapproved hook without a word, and in VS Code
+the first conversation starts before anything can be approved (measured on Codex 0.159). Before writing it, `init`
+runs the check once the way Codex will, and writes nothing if that fails. So it blocks from the first message, in the
+terminal and in VS Code, and it acts only in projects whose rules block files. If Codex changes how it checks
+approvals, agentwhy's Settings page says the block may ask again instead of claiming it holds.
 
 **Which agents does it work with?**
 Claude Code, in the terminal and in code editors, and Codex. Not Cursor's own AI, Windsurf or chats on claude.ai. Each
@@ -122,8 +162,8 @@ Codex writes down less than Claude Code does, so a Codex report can answer fewer
 | Which helper was asked to do what, and what it gave back | yes | yes |
 | Which files the AI changed | yes | yes; a change that failed is not counted |
 | What Codex was allowed to do at the time | - | yes, shown apart from your own rules |
-| Blocking a file | yes | yes, the same files, once you approve agentwhy's hook in Codex (measured on 0.159.2) |
-| A message in the chat after agentwhy blocks a command | yes | yes, in the terminal and code editor once both hooks are approved |
+| Blocking a file | yes | yes, the same files, from the first message - agentwhy approves its own check in your `~/.codex` files (measured on 0.159) |
+| A message in the chat after agentwhy blocks a command | yes | yes, in the terminal and code editor |
 | A warning when a value reached the chat, and `check` | yes | no |
 
 Older Codex files keep the commands only inside the code that ran them, so their reports show no commands and say so.
@@ -168,8 +208,20 @@ npx @agentwhy/cli notify           # what you are told when a turn ends, and whe
 
 Every command, flag and hook, and what each word on the page means: [docs/reference.md](docs/reference.md).
 
+## Author
+
+agentwhy is made by **Karol Kozer** ([LinkedIn](https://www.linkedin.com/feed/update/urn:li:activity:7507715323744206849/)).
+Before it, Karol made [Planby](https://planby.app/), which
+[won first place at WaysAwards 2024](https://www.linkedin.com/posts/waysawards2024-digitalinnovation-techawards-ugcPost-7252302039907504129-uszQ/),
+hosted by WaysConf, and has over [1,700 stars on GitHub](https://github.com/karolkozer/planby).
+
+Something else in mind? Write to [karol@agentwhy.dev](mailto:karol@agentwhy.dev). Every message is read, and most get
+an answer within a day or two.
+
 ## License
 
+Copyright 2026 Nessprim Karol Kozer.
+
 Open source, under the [Apache License 2.0](LICENSE). Use it, change it and share it for any purpose, commercial
 use included. When you pass on a copy, keep the license, the copyright and [NOTICE](NOTICE) with it. The license
 does not cover the name agentwhy. The full terms are in [LICENSE](LICENSE); this summary does not replace them.

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

@@ -123,9 +123,15 @@ export const ASSUMPTIONS = [
     },
     {
         id: 'entry-point-per-session',
-        statement: 'The lines that hold a conversation carry entrypoint, which way into Claude Code the session was started by, and one session carries one value: cli, claude-vscode or sdk-cli. Any other value is unknown, never the nearest of these.',
+        statement: 'The lines that hold a conversation carry entrypoint, which way into Claude Code the session was started by, and one session carries one value: cli, claude-vscode, sdk-cli or claude-desktop. Any other value is unknown, never the nearest of these.',
         status: 'verified',
-        evidence: 'which-project VB5 (2026-09-28): the last megabyte of each of 244 transcripts carries it - claude-vscode 180, cli 62, sdk-cli 2 - and no transcript, tail or whole, carries two values. The same values the hooks are given as CLAUDE_CODE_ENTRYPOINT (the-agent-tells-you B9e2). The committed corpus holds a canary marker in its place, which reads as unknown',
+        evidence: 'which-project VB5 (2026-09-28): the last megabyte of each of 244 transcripts carries it - claude-vscode 180, cli 62, sdk-cli 2 - and no transcript, tail or whole, carries two values. The same values the hooks are given as CLAUDE_CODE_ENTRYPOINT (the-agent-tells-you B9e2). claude-desktop on every entrypoint-carrying line of 3 of 3 Claude desktop app conversations, one value each (claude-desktop-conversations CDB1, 2026-10-01). The committed corpus holds a canary marker in its place, which reads as unknown',
+    },
+    {
+        id: 'desktop-session-file',
+        statement: 'The Claude desktop app writes no ai-title line. It keeps one file per conversation on macOS, local_<uuid>.json two directory levels under ~/Library/Application Support/Claude/claude-code-sessions, one JSON object whose cliSessionId is the transcript session id and whose title is the name the app sidebar shows. Only those two fields are read; where the app keeps this on Windows is not measured.',
+        status: 'verified',
+        evidence: 'claude-desktop-conversations CDB1 (2026-10-01, app 2.16120.0 running Claude Code 2.1.284, macOS): 3 of 3 desktop conversations - no ai-title in any transcript read whole, against 1-2 in each of 4 terminal transcripts; 3 files, each one JSON object of 31 keys with a string cliSessionId equal to the transcript file name and the sessionId on its lines, and a non-empty string title; measured by scripts printing key names, counts, lengths and equalities only',
     },
     {
         id: 'sidechain-discriminator',
@@ -135,9 +141,9 @@ export const ASSUMPTIONS = [
     },
     {
         id: 'denial-marker',
-        statement: 'A blocked call is marked by toolDenialKind on its result line; the only observed value is permission-rule.',
+        statement: 'A call that did not run is marked by toolDenialKind on its result line; permission-rule says a rule refused it, automode-blocked that auto mode did. user-rejected has been seen and is not classified.',
         status: 'verified',
-        evidence: '5 of 5 denials',
+        evidence: '5 of 5 denials, permission-rule (2026-09-12); 5 of 5 markers of automode-blocked on a user line with one result (2026-10-01, Claude Code 2.1.236 and 2.1.284); user-rejected, 1 marker, its effect not measured',
     },
     {
         id: 'meta-keys',
@@ -193,6 +199,12 @@ export const ASSUMPTIONS = [
         status: 'verified',
         evidence: '5 of 5 Stop inputs (2026-09-17, the-agent-nobody-watches B8b) and every SubagentStop input of B4 (2026-09-16). Read by `watch` to decide which project a person\'s notification choices were made for, before any of the session has been read',
     },
+    {
+        id: 'hook-subagent-stop-agent-file',
+        statement: "A SubagentStop input names the finished agent's own file in agent_transcript_path, and a delegated agent's file is on disk when the hook runs. A named file that is not there is an agent that kept no record.",
+        status: 'verified',
+        evidence: "On disk on 4 of 4 delegated agents (2026-09-16, when-an-agent-finishes B4c) and on 2 more runs (B4f). Named and not on disk on 2 of 2 SubagentStop runs in the Claude desktop app on Claude Code 2.1.284 (2026-10-01, B4g), each about 3 seconds after the turn's Stop, with an empty agent_type, no file under subagents/ and the agent's id nowhere in the session. Read by `watch` to say such an agent once a session instead of after every turn",
+    },
     {
         id: 'session-title-latest-near-end',
         statement: 'The title a session has now is its last ai-title line, and that line lies within the last megabyte of the transcript.',

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

@@ -1,4 +1,19 @@
-export const KNOWN_DENIAL_KINDS = ['permission-rule'];
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
+export const KNOWN_DENIAL_KINDS = ['permission-rule', 'automode-blocked'];
+/**
+ * Who each known value says refused the call (`specs/2026-10-01-who-stopped-it.md` WS1): a permission rule, or the
+ * reviewer - auto mode's classifier. Measured 2026-10-01 (spec §4.0): `automode-blocked` on 5 result lines of Claude
+ * Code 2.1.236 and 2.1.284, each a `user` line holding one result marked as an error; two were commands that would have
+ * started a server, and none started. A Record over the union: a value added above does not compile until it says who.
+ *
+ * `user-rejected` - a call the person turned down at a prompt - was seen once and is **not** listed: that such a call
+ * does not run has not been measured (WSB1), and a value read as "did not run" without that would be a guess.
+ */
+export const DENIAL_SOURCE = {
+    'permission-rule': 'rule',
+    'automode-blocked': 'reviewer',
+};
 // An unrecognised denial kind must surface as unknown, never be folded into a known one.
 export function isKnownDenialKind(value) {
     return typeof value === 'string' && KNOWN_DENIAL_KINDS.includes(value);

package/dist/adapter/claude-code/contract/desktop-sessions.js

@@ -0,0 +1,28 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Where the Claude desktop app keeps what it knows about a conversation, and the two fields agentwhy reads from it
+ * (`.ai/specs/2026-10-01-claude-desktop-conversations.md` CD1). The app runs Claude Code but writes no `ai-title` into
+ * the transcript: the name its sidebar shows is in a file of the app's own. Measured 2026-10-01 on macOS alone (CDB1,
+ * app 2.16120.0 running Claude Code 2.1.284, 3 of 3 desktop conversations): one JSON object per conversation, two
+ * directory levels under the folder, whose `cliSessionId` is the transcript's session id and whose `title` is the name
+ * the sidebar shows. The file also holds what must never be read - MCP server configuration, permissions, prompt
+ * snapshots - which is why the fields read are named here and nothing else is (CD4). Where the app keeps this on
+ * Windows is not measured (CDB5), so no path is guessed there (CD6).
+ */
+export const DESKTOP_SESSIONS = {
+    /** Under the home directory, on macOS. */
+    folder: ['Library', 'Application Support', 'Claude', 'claude-code-sessions'],
+    /** The file sits exactly this many directory levels under the folder - two ids whose meaning is not measured. */
+    depth: 2,
+    filePrefix: 'local_',
+    fileSuffix: '.json',
+    /** The transcript's session id - the join to `~/.claude/projects/<project>/<session id>.jsonl`. */
+    sessionIdField: 'cliSessionId',
+    /** The name the app's sidebar shows. A model wrote it from what the person typed: content, never structure (L009). */
+    titleField: 'title',
+};
+/** Whether a directory entry's name is a desktop session file. Anything else in those folders is not read. */
+export function isDesktopSessionFileName(name) {
+    return name.startsWith(DESKTOP_SESSIONS.filePrefix) && name.endsWith(DESKTOP_SESSIONS.fileSuffix);
+}

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

@@ -1,10 +1,14 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 /**
  * 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
+ * `claude-vscode` in 180, `cli` in 62, `sdk-cli` in 2, and no transcript carries two values. A fourth value, measured
+ * 2026-10-01 (`claude-desktop-conversations.md` CDB1, CD7): the Claude desktop app writes `claude-desktop`, on every
+ * line that carries the field in 3 of 3 desktop transcripts, one value each. 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".
  */
@@ -12,4 +16,5 @@ export const ENTRY_POINT_VALUES = {
     terminal: 'cli',
     editor: 'claude-vscode',
     script: 'sdk-cli',
+    desktop: 'claude-desktop',
 };

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

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 export const FIELDS = {
     lineType: 'type',
     sidechain: 'isSidechain',

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

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 /**
  * What a Claude Code hook is handed and what it may hand back (`specs/2026-09-16-when-an-agent-finishes.md` §2).
  *
@@ -25,6 +27,12 @@ export const SUBAGENT_STOP = {
         lastMessage: 'last_assistant_message',
         /** The session the agent belongs to: what an alert is remembered under until its turn ends. */
         sessionId: 'session_id',
+        /**
+         * The agent's own file, `subagents/agent-<id>.jsonl` beside the main transcript (D2). On disk when the hook ran for
+         * every delegated agent measured (B4c, B4f); named and **not** on disk on 2 of 2 runs in the Claude desktop app
+         * where nothing was delegated (B4g) - an agent that kept no record at all.
+         */
+        agentTranscriptPath: 'agent_transcript_path',
     },
 };
 /**

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

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 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}$/;

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

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 export const LAYOUT = {
     transcriptSuffix: '.jsonl',
     subagentsDir: 'subagents',

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

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 export const CONVERSATION_LINE_TYPES = ['user', 'assistant'];
 export const SKIPPED_LINE_TYPES = [
     'attachment',

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

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 /**
  * Where a project's sessions live: `~/.claude/projects/<encoded working directory>/`.
  *

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

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 /**
  * 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.

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

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 /**
  * 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.

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

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 /**
  * 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

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

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 // 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.
@@ -43,7 +45,18 @@
 // 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;
+// v14 (2026-10-01): a second value of `toolDenialKind`, `automode-blocked`, and who each value says refused the call
+// (`denials.ts`, `.ai/specs/2026-10-01-who-stopped-it.md`). Measured on the 7 transcripts of one project, Claude Code
+// 2.1.236 and 2.1.284: 5 markers, each on a `user` line holding exactly one result marked as an error, with
+// `toolUseResult` and `sourceToolAssistantUUID` beside it - where `permission-rule` sits. A third value seen there,
+// `user-rejected`, stays unknown until it is measured that its call does not run.
+// v15 (2026-10-04): the Claude desktop app's session file (`desktop-sessions.ts`) - where the app keeps a
+// conversation's title, since it writes no `ai-title` line - and `claude-desktop` as a fourth `entrypoint` value
+// (`entry-points.ts`). Measured 2026-10-01 on macOS (`.ai/specs/2026-10-01-claude-desktop-conversations.md` CDB1,
+// app 2.16120.0 running Claude Code 2.1.284): 3 of 3 desktop conversations, no `ai-title` in any, one
+// `local_<uuid>.json` each whose `cliSessionId` is the transcript's session id and whose `title` is the sidebar's name.
+// Only those two fields are read (CD4); Windows is not measured (CDB5), so no path is read there.
+export const CONTRACT_VERSION = 15;
 export const VERIFIED_AGAINST = {
     claudeCode: '2.1.268',
     session: '951c4f76-9d2a-40d2-9c76-1e57cf47ae4e',

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

@@ -1,4 +1,7 @@
-import { join } from 'node:path';
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
+import { basename, join } from 'node:path';
+import { isDirectory } from '../../../ports/directory-reader.js';
 import { FileAccessError } from '../../../ports/file-access-error.js';
 import { LAYOUT } from '../contract/layout.js';
 import { PROJECTS_DIRECTORY, matchesProject } from '../contract/projects.js';
@@ -68,10 +71,17 @@ export class ClaudeCodeProjectCatalogue {
         }
         if (path === undefined)
             return 'unreadable';
+        // CD2: a conversation the Claude desktop app held has no `ai-title`; its row is titled by the app's own name,
+        // through this list's redactor, as the transcript's title would be.
+        if (recognised.title === undefined && this.#dependencies.desktop !== undefined) {
+            const named = await this.#dependencies.desktop.titleOf(basename(newest.path, LAYOUT.transcriptSuffix));
+            if (named !== undefined)
+                recognised = { ...recognised, title: this.#dependencies.redactor.scan(named) };
+        }
         return {
             id,
             path,
-            exists: await this.#isDirectory(path),
+            folder: this.#dependencies.leaveAlone?.(path) === true ? 'not-looked' : (await isDirectory(this.#dependencies.directories, path)) ? 'there' : 'gone',
             conversations: transcripts.length,
             newest: { modifiedAt: newest.modifiedAt, ...recognised },
         };
@@ -116,14 +126,4 @@ export class ClaudeCodeProjectCatalogue {
             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

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { resolve } from 'node:path';
 import { FileAccessError } from '../../../ports/file-access-error.js';
 import { parseJsonObject } from '../../../shared/json.js';

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

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { join } from 'node:path';
 import { FileAccessError } from '../../../ports/file-access-error.js';
 import { LAYOUT, parseSubagentFileName } from '../contract/layout.js';
@@ -15,9 +17,25 @@ export class ClaudeCodeSessionCatalogue {
         this.#directories = directories;
         this.#home = home;
     }
+    /**
+     * Whether a folder is there and can be read: listed, not only seen, since a sandbox may show a folder it will not let
+     * an app list - and from inside it that is the same as no folder. An error the port names is "no", and nothing else
+     * is swallowed.
+     */
+    async #canList(path) {
+        try {
+            await this.#directories.list(path);
+            return true;
+        }
+        catch (error) {
+            if (!(error instanceof FileAccessError))
+                throw error;
+            return false;
+        }
+    }
     async list(workingDirectory) {
         const root = join(this.#home, ...PROJECTS_DIRECTORY);
-        const directory = await this.#directoryFor(root, workingDirectory);
+        const { directory, storeListed } = await this.#directoryFor(root, workingDirectory);
         let entries;
         try {
             entries = await this.#directories.list(directory);
@@ -25,8 +43,10 @@ export class ClaudeCodeSessionCatalogue {
         catch (error) {
             if (!(error instanceof FileAccessError))
                 throw error;
-            // Not found is an answer, not a failure: this project may simply never have been worked on here.
-            return { directory, found: false, searched: [{ provider: 'claude-code', directory, found: false }], sessions: [] };
+            // Not found is an answer, not a failure: this project may simply never have been worked on here. Whether Claude
+            // Code keeps any conversations here at all is the other half of the answer (R28, amended 2026-10-01).
+            const store = (storeListed ?? (await this.#canList(root))) ? {} : { store: 'missing' };
+            return { directory, found: false, searched: [{ provider: 'claude-code', directory, found: false, ...store }], sessions: [] };
         }
         const sessions = await Promise.all(entries
             .filter((entry) => entry.kind === 'file' && entry.name.endsWith(LAYOUT.transcriptSuffix))
@@ -41,13 +61,14 @@ export class ClaudeCodeSessionCatalogue {
     /**
      * The encoded name first, because it costs nothing when it is right. When it is not - and the rule is
      * inferred from examples, so it will not always be - the stored directories are compared against the working
-     * directory instead of trusting the guess.
+     * directory instead of trusting the guess. Where the store was listed for that, whether it could be is said too, so
+     * it is not asked again.
      */
     async #directoryFor(root, workingDirectory) {
         const derived = join(root, projectDirectoryName(workingDirectory));
         try {
             if ((await this.#directories.kindOf(derived)) === 'directory')
-                return derived;
+                return { directory: derived };
         }
         catch (error) {
             if (!(error instanceof FileAccessError))
@@ -56,12 +77,12 @@ export class ClaudeCodeSessionCatalogue {
         try {
             const stored = await this.#directories.list(root);
             const match = stored.find((entry) => entry.kind === 'directory' && matchesProject(entry.name, workingDirectory));
-            return match === undefined ? derived : join(root, match.name);
+            return { directory: match === undefined ? derived : join(root, match.name), storeListed: true };
         }
         catch (error) {
             if (!(error instanceof FileAccessError))
                 throw error;
-            return derived;
+            return { directory: derived, storeListed: false };
         }
     }
     async #summarise(directory, fileName) {

package/dist/adapter/claude-code/discovery/claude-code-session-discovery.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { basename, join, resolve } from 'node:path';
 import { FileAccessError } from '../../../ports/file-access-error.js';
 import { byString } from '../../../shared/compare.js';

package/dist/adapter/claude-code/discovery/claude-code-session-titles.js

@@ -5,24 +5,48 @@ import { recognitionIn } from './transcript-tail.js';
 /**
  * Reads what a person recognises a session by from the end of its transcript, in one read: the title Claude Code gave
  * it, handed over only once it has passed the redactor, and which way into Claude Code it was held
- * (`.ai/specs/2026-09-27-which-project.md` V4). Nothing else in the transcript is looked at, and nothing is kept.
+ * (`.ai/specs/2026-09-27-which-project.md` V4). Nothing else in the transcript is looked at, and nothing but the tail's
+ * answer is kept. A session the desktop app held has no `ai-title`: its title is the app's own, read the same way a
+ * Codex thread's name is (CD2) - so a row with no title can be asked again at the cost of a look at the app's folder,
+ * never another read of an unchanged transcript (CD5).
  */
 export class ClaudeCodeSessionTitles {
     #dependencies;
+    /** By the session's path: what its tail said when it was last this old. */
+    #known = new Map();
     constructor(dependencies) {
         this.#dependencies = dependencies;
     }
     async recognise(session) {
-        const { transcripts, redactor } = this.#dependencies;
-        let tail;
+        const { redactor, desktop } = this.#dependencies;
+        const kept = this.#known.get(session.path);
+        let fromTail;
+        if (kept !== undefined && kept.modifiedAt === session.modifiedAt) {
+            fromTail = kept.recognition;
+        }
+        else {
+            const tail = await this.#tail(session.path + LAYOUT.transcriptSuffix);
+            // A transcript that is missing or unreadable is recognised by nothing, and nothing is kept: the next ask tries it.
+            if (tail === undefined)
+                return {};
+            fromTail = recognitionIn(tail, redactor);
+            this.#known.set(session.path, { modifiedAt: session.modifiedAt, recognition: fromTail });
+        }
+        if (fromTail.title !== undefined || desktop === undefined)
+            return fromTail;
+        const named = await desktop.titleOf(session.id);
+        if (named === undefined)
+            return fromTail;
+        return { ...fromTail, title: redactor.scan(named) };
+    }
+    async #tail(path) {
         try {
-            tail = await transcripts.readTail(session.path + LAYOUT.transcriptSuffix, SESSION_TITLE.tailBytes);
+            return await this.#dependencies.transcripts.readTail(path, SESSION_TITLE.tailBytes);
         }
         catch (error) {
             if (!(error instanceof FileAccessError))
                 throw error;
-            return {};
+            return undefined;
         }
-        return recognitionIn(tail, redactor);
     }
 }

package/dist/adapter/claude-code/discovery/claude-desktop-titles.js

@@ -0,0 +1,102 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
+import { join } from 'node:path';
+import { FileAccessError } from '../../../ports/file-access-error.js';
+import { parseJsonObject } from '../../../shared/json.js';
+import { oneLine } from '../../../shared/printable.js';
+import { DESKTOP_SESSIONS, isDesktopSessionFileName } from '../contract/desktop-sessions.js';
+/**
+ * The names the Claude desktop app gave its conversations, for the ones whose transcripts hold no `ai-title`
+ * (`.ai/specs/2026-10-01-claude-desktop-conversations.md` CD2). Each file is read for `cliSessionId` and `title` and
+ * nothing else is kept, counted or handed out (CD4); the whole walk answers nothing where the folder is missing or
+ * unreadable, which on a computer without the app is the ordinary case. The app names a conversation at its first turn,
+ * which can be after a list first showed it, so every ask walks the folders again - a look at their listings - while a
+ * file is read again only where it changed (CD5). A title leaves here raw: every caller passes it through its own
+ * redactor before anything shows it (§13.2 pitfall 7), exactly as `ai-title` is handled.
+ */
+export class ClaudeDesktopTitles {
+    #dependencies;
+    /** By file path. A file that could not be read is not kept, so the next ask tries it again. */
+    #read = new Map();
+    /** The walk in flight, shared by the asks of one batch so eight rows cost one walk. */
+    #names;
+    constructor(dependencies) {
+        this.#dependencies = dependencies;
+    }
+    /** The app's name for this session, raw, or nothing - which a caller never tells apart from "no app here". */
+    async titleOf(sessionId) {
+        if (this.#dependencies.folder === undefined)
+            return undefined;
+        if (this.#names === undefined) {
+            this.#names = this.#walk(this.#dependencies.folder).finally(() => {
+                this.#names = undefined;
+            });
+        }
+        return (await this.#names).get(sessionId);
+    }
+    /**
+     * Every session file at exactly `DESKTOP_SESSIONS.depth` levels under the folder - one that sits shallower or deeper
+     * is not the measured shape and is not read. Two files naming one id with different titles name none (CD2): the
+     * contract has no way to pick, and a guess would show a person the wrong conversation's name.
+     */
+    async #walk(folder) {
+        const names = new Map();
+        const conflicted = new Set();
+        for (const first of await this.#list(folder)) {
+            if (first.kind !== 'directory')
+                continue;
+            for (const second of await this.#list(join(folder, first.name))) {
+                if (second.kind !== 'directory')
+                    continue;
+                for (const entry of await this.#list(join(folder, first.name, second.name))) {
+                    if (entry.kind !== 'file' || !isDesktopSessionFileName(entry.name))
+                        continue;
+                    const file = await this.#file(join(folder, first.name, second.name, entry.name));
+                    if (file?.id === undefined || file.title === undefined)
+                        continue;
+                    const known = names.get(file.id);
+                    if (known !== undefined && known !== file.title) {
+                        conflicted.add(file.id);
+                        continue;
+                    }
+                    names.set(file.id, file.title);
+                }
+            }
+        }
+        for (const id of conflicted)
+            names.delete(id);
+        return names;
+    }
+    async #list(path) {
+        try {
+            return await this.#dependencies.directories.list(path);
+        }
+        catch (error) {
+            if (!(error instanceof FileAccessError))
+                throw error;
+            return [];
+        }
+    }
+    /** One file's two fields, from the cache where it has not changed. A shape that is not CDB1's says nothing. */
+    async #file(path) {
+        const { directories, files } = this.#dependencies;
+        try {
+            const modifiedAt = await directories.modifiedAt(path);
+            const kept = this.#read.get(path);
+            if (kept !== undefined && kept.modifiedAt === modifiedAt)
+                return kept;
+            const record = parseJsonObject(await files.readText(path));
+            const id = record?.[DESKTOP_SESSIONS.sessionIdField];
+            const rawTitle = record?.[DESKTOP_SESSIONS.titleField];
+            const title = typeof rawTitle === 'string' ? oneLine(rawTitle) : '';
+            const read = { modifiedAt, ...(typeof id === 'string' && id !== '' && title !== '' ? { id, title } : {}) };
+            this.#read.set(path, read);
+            return read;
+        }
+        catch (error) {
+            if (!(error instanceof FileAccessError))
+                throw error;
+            return undefined;
+        }
+    }
+}

package/dist/adapter/claude-code/discovery/session-entries.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { join } from 'node:path';
 import { byString } from '../../../shared/compare.js';
 import { LAYOUT, isToolResultFileName, parseSubagentFileName, subagentFileName } from '../contract/layout.js';