npm - @threadcrumbs/common - Versions diffs - 0.1.9 → 0.1.11 - Mend

@threadcrumbs/common 0.1.9 → 0.1.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md +8 -5
package/harnesses/README.md +214 -213
package/harnesses/claude-code.mjs +579 -578
package/lib/claude-transcript.mjs +17 -3
package/lib/proc-start.mjs +157 -0
package/license/store.mjs +192 -155
package/package.json +1 -1
package/telemetry/claude-code.mjs +3 -2

package/README.md CHANGED Viewed

@@ -18,7 +18,7 @@ need it.
 | `@threadcrumbs/common/orgs` | Which organization each repo belongs to, so the apps can group repos the same way. `organizationReader()` returns `withOrganizations(threads)`, which tags each thread with `org` by its `projectPath` and reads each folder at most once a minute. `signalsOf(dir)` reads one folder's package name and git origin owner, and `organizationsFor(signals)` combines them. The rules are in [DECISIONS.md](DECISIONS.md#a-repos-organization-comes-from-its-package-name). Node only, and it only reads |
 | `@threadcrumbs/common/launch` | `present(result, via)`: carries out a harness adapter's answer to "open this thread" by fronting the window of a session already running, handing a deep link to the OS, or running the harness's CLI in a new terminal. When nothing on the machine answers the link, it tries the adapter's `fallback` links, such as Claude Code's thread in VS Code, and failing those returns `{ ok: false, error, missing: { name, download, scheme, also }, terminal }`: the app to install, where to get it, other apps that would do, and whether `via: 'terminal'` would work instead. Also `launch(target)` and `resolveFolder(dir)`. Threadgauge uses it, and Threadnauts still has its own copy |
 | `@threadcrumbs/common/license` | The Threadcrumbs license both apps check offline and the key service signs: `createLicenseKeys`, `publicKeyOf`, `licenseClaims`, `signLicense`, `verifyLicense`, and the unlock rule, `paidThrough` and `unlocks`, plus `renewalDue`. Web APIs only, so the same file runs in a Cloudflare Worker. The format and rules are in [DECISIONS.md](DECISIONS.md#licenses-are-signed-by-threadcrumbs-and-checked-offline). `LICENSE_PUBLIC_KEYS` holds the production keys every app trusts, and never a sandbox key |
-| `@threadcrumbs/common/license/store` | Where the license lives on this machine, shared by every app: `licenseStore()` returns `device()`, `current()`, `save(token)`, and `clear()`, over `license.json` in `threadcrumbsDataDir()`. `current().at` is the time to test unlocks at, and `current()` writes nothing on a machine where no one has entered a key. `trustedKeys({ development })` adds a sandbox key in a development build, and `cloudUrl({ development })` is the key service's address: `https://threadcrumbs.io/api`, or the local Worker at `http://localhost:8787/api` in a development build. Node only, so the Worker never loads it |
+| `@threadcrumbs/common/license/store` | Where the license lives on this machine, shared by every app: `licenseStore()` returns `device()`, `current()`, `save(token)`, and `clear()`, over `license.json` in `threadcrumbsDataDir()`. `current().at` is the time to test unlocks at, and `current()` writes nothing on a machine where no one has entered a key. `trustedKeys({ development })` adds a sandbox key in a development build, and `cloudUrl({ development })` is the key service's address: `https://threadcrumbs.io/api`, or the local Worker at `http://localhost:8787/api` in a development build. `portalUrl({ license, device, fetch, cloud })` asks the key service for Polar's customer portal, signed in, where a subscriber changes plan; it resolves to `{ url }` or `{ error, why }`, with `why` ready to show ([DECISIONS.md](DECISIONS.md#changing-plan-happens-in-polars-portal-opened-with-the-license)). Node only, so the Worker never loads it |
 | `@threadcrumbs/common/ui/theme.css` | The Threadcrumbs look as CSS variables: the Quieter backgrounds, lines, and text levels, Threadcrumbs orange, the six status colors and their plates, `--warn`, added and removed, the chart and gauge colors, focus, type sizes, spacing, radii, and the default `--sans`, `--cond`, and `--mono` stacks. Every element keeps one x-height (`font-size-adjust: 0.51`) |
 | `@threadcrumbs/common/ui/fonts.css` | `@font-face` rules for Inter, Inter Tight, and JetBrains Mono, Latin and Latin Extended, upright, with their `.woff2` files in `ui/fonts/`. A bundler copies the files into the app, so they load from its own origin. `tools/ui-fonts.mjs` writes both from the `@fontsource` packages |
 | `@threadcrumbs/common/ui/status` | `STATUSES` (each status's key, name, color, and plate, in the order both apps pin), `STATUS_KEYS`, `URGENCY_ORDER` (for the status row and the waffle), `LIVE_STATUSES`, `statusOf`, the status icons as SVG in `LAMP_ICONS`, and `lampHTML(status)`. `ui/status.css` colors each `[data-st]` and animates the lamps, and reduced motion stops them |
@@ -31,7 +31,8 @@ need it.
 | `@threadcrumbs/common/ui/totals` | The status lamps and the footer: `statusCounts`, `lampsHTML(counts, total, pressed)`, `footerTotals(threads)`, `footerHTML(totals, { short, bars })`, and the output-over-time log, `emptyOutputLog`, `recordOutput`, and `outputBars`. `ui/totals.css` styles them and builds on `ui/rows.css` |
 | `@threadcrumbs/common/ui/pictures` | The footer's pictures, `FOOT_DRAW` (`drawPie`, `drawWaffle`, `drawCols`) at `FOOT_SIZE`, with `footerNote`; plan ticks, `planTicks` and `planSpec`; `waffleStates` and `binTimes`; and the SVG helpers Threadgauge's other pictures use (`fx`, `clamp`, `polar`, `wideBox`, `wideSVG`, and an `esc` for SVG text). `ui/pictures.css` colors them |
-`launch/` is the only part of this package that starts processes, and `license/store.mjs` is the
+`launch/` is the only part of this package that starts processes, apart from `lib/proc-start.mjs`
+asking `ps` or `Get-Process` when a pid started, and `license/store.mjs` is the
 only part that writes a file. The readers and `orgs/` import neither. `ui/` is plain functions
 that return markup, plus CSS and fonts, for a page to draw; it touches no DOM and does no I/O.
@@ -132,15 +133,17 @@ pnpm test
 `test/harness.test.mjs` fakes an install of each harness in a temp folder for the session readers,
 and each `test/<harness>-telemetry.test.mjs` does the same for that harness's telemetry reader.
 `test/claude-transcript.test.mjs` covers the shared Claude parser on its own.
+`test/proc-start.test.mjs` covers telling a live Claude Code session from a recycled pid, against
+fake lookups: a match, a recycled pid, a failed or slow lookup, the cache, and the batching.
 `test/shared-ids.test.mjs` has both readers of each harness scan one fake install and checks they
 give its sessions the same ids, which Threadgauge's Open depends on.
 `test/orgs.test.mjs` covers each package manager's name, the git origin, and the combining rule.
 `test/read-only.test.mjs` reads the package's own source and fails if anything under `harnesses/`,
-`telemetry/`, `lib/`, or `orgs/` writes a file, opens a database for writing, starts or signals a process,
-or imports `launch/` or the license store. `test/launch.test.mjs` covers how `present()` refuses and names a missing app,
+`telemetry/`, `lib/`, or `orgs/` writes a file, opens a database for writing, starts or signals a process
+(apart from `lib/proc-start.mjs`'s start-time query), or imports `launch/` or the license store. `test/launch.test.mjs` covers how `present()` refuses and names a missing app,
 starting nothing but a registry query on Windows. `test/license.test.mjs` covers signing and the unlock rule, and
 `test/license-store.test.mjs` covers the shared file, including two apps starting at once on a
-fresh machine and a clock set back.
+fresh machine and a clock set back, and `portalUrl()` against a fake key service.
 GitHub Actions runs the suite on Windows, macOS, and Linux for every push to `master` and every
 pull request (`.github/workflows/test.yml`). The tests that only run on one OS, like the real

package/harnesses/README.md CHANGED Viewed

@@ -1,213 +1,214 @@
-# Harness adapters
-A **harness** is whatever runs the agent threads — Claude Code, Codex CLI, OpenCode, and so on.
-The Threadcrumbs apps do not care which one you use: each asks every harness present on the
-machine for its threads, through these adapters, and shows whatever comes back. Threadnauts
-draws them as bots in its colony, which is where most of the wording below comes from.
-Adding one is meant to be **one new file in this directory**, plus one line in `index.mjs`.
-Nothing in an app's scanner, its API, or its page should need to change.
-If you find yourself editing those to land a harness, that is a bug in this seam — please say so
-in the PR, because the next person will hit it too.
-## The shape of it
-```js
-// harnesses/my-harness.mjs
-export default {
-  id: 'my-harness',              // stable, kebab-case, used as a key — never change it later
-  name: 'My Harness',            // what a human sees in the UI
-  detect,                        // () => Promise<boolean>
-  scanThreads,                   // () => Promise<Thread[]>
-  app,                           // { name, download }: the app that answers the deep link
-  openThread,                    // (ref) => { ok, url, command?, app } | { ok: false, error }
-  newSession,                    // (dir) => { ok, url, command?, app } | { ok: false, error }
-}
-```
-Then, in `index.mjs`:
-```js
-import myHarness from './my-harness.mjs'
-export const HARNESSES = [claudeCode, myHarness]
-```
-### `detect()`
-Is this harness on this machine at all? Usually just "does its data directory exist". Cheap —
-it runs on every scan, so that installing a harness while the colony is open is noticed on the
-next poll. Returning `false` means the harness is skipped entirely, and no bot for it
-ever appears.
-### `scanThreads()`
-The real work: return one `Thread` per session the harness knows about.
-Throwing is survivable — the scanner logs it and carries on with the other harnesses, so one
-broken adapter costs you its own threads and nothing else. Prefer that over returning junk.
-### `openThread(ref)` / `newSession(dir)`
-Return `{ ok: true, url }` and the server hands that URL to the OS opener. `openThread` gets
-the `ref` from the thread it belongs to; `newSession` gets an absolute directory that the
-server has already checked still exists.
-Add `command: { argv, cwd }` — the harness's own CLI resuming the same thread, with an absolute `argv[0]` —
-when the CLI is installed, and the server runs it in a terminal for a machine with no desktop app or a person who asked for one.
-Never spawn it yourself.
-Add `app: { name, download }` too, the same object as the adapter's own `app`: the app that answers
-the deep link, as a person would call it, and the page to download it from. When nothing on the
-machine answers the link, `present()` names that app, so the UI can say what to install instead
-of a click that does nothing. `app.also` can list other apps that would do, such as the Claude Code
-extension for VS Code.
-When another app can open the thread through links of its own, add `fallback: { app, urls, note }`.
-`present()` tries it when nothing answers `url`: it opens each URL in turn, two seconds apart,
-and returns `note`. Claude Code uses it to open the thread's folder in VS Code and then the
-extension's session link.
-If your harness has no deep link, return `{ ok: false, error: '…' }` and say why — the UI
-shows the message rather than pretending the click worked.
-### There is no `setArchived`, and that is deliberate
-No adapter writes to a harness. Not the transcripts, not the session records, not one
-flag. Threadnauts records archiving in its own `colony.json` and nowhere else: the thread leaves
-the map and the bot walks back to the ship.
-It used to write one flag — `isArchived` on Claude Code's own session record — and that write
-genuinely landed on disk. It just did not *mean* anything: the desktop app serves from the copy it
-loaded at launch, so the thread stayed in its list until the app restarted, and the app rewrote the
-record from memory the next time it touched the thread. Holding that together took a re-assert on
-every scan, a `ps` sweep to guess whether the app had re-read the file, and a *pending* state for
-the gap between them. All of that is gone, and the scan no longer starts a subprocess at all.
-Archiving in the harness's own UI still works and is still the right way to do it — your adapter
-reports it through the `archived` field and the bot goes home on the next poll.
-## The `Thread` your adapter returns
-Only `id` is truly required, but the colony gets duller the more you leave out — `project` is
-what earns a repo its own zone, and `lastActivityAt` is what sorts the whole map.
-| Field | Type | What it means |
-| --- | --- | --- |
-| `id` | string | **Unique across every harness.** A UUID is fine; otherwise prefix it, e.g. `my-harness:1234` |
-| `title` | string | Thread title. `'Untitled thread'` if the harness has none |
-| `preview` | string | First prompt, trimmed — shown on the thread card |
-| `project` | string | Repo/folder **name**. This is what claims a hex zone |
-| `projectPath` | string | Absolute path to the repo root |
-| `worktree` | string | Worktree name, or `''` |
-| `cwd` | string | Where the thread is actually working |
-| `gitBranch` | string | Branch name, or `''` |
-| `model` / `effort` | string | Shown on the thread card |
-| `createdAt` | number | Epoch ms |
-| `lastActivityAt` | number | Epoch ms. Sorts the colony and drives the "asleep for 3 days" behaviour |
-| `lastFocusedAt` | number | Epoch ms, `0` if unknowable |
-| `running` | boolean | Working **right now** — the bot hammers away |
-| `unread` | boolean | Done: the turn ended and moved on since you last looked — the bot stops and raises a hand |
-| `needsInput` | boolean | Needs you: stopped mid-turn on a permission prompt, a question, or an approval only you can answer — the bot holds a `?` and waves until you do. Outranks every other state |
-| `awaitingSubagents` | boolean | Waiting on bots: its own turn is over, or its only open calls are subagents, and subagents it sent out are still working, or another thread it asked to hear from is still busy — the bot stands at its site under a `…` until they report back. Outranks `running` and `unread` |
-| `hasError` | boolean | Errored — the bot slumps, red eyes |
-| `starred` / `routine` / `prState` | | Optional extras; `prState: 'merged'` triggers the confetti |
-| `archived` | boolean | Archived in the harness's own records. Read-only — reporting it is all an adapter does |
-| `sizeBytes` | number | Transcript size. **This is how finished a building looks**, on a log scale |
-| `source` | string | Free-form, for your own bookkeeping (the Claude adapter uses `desktop` / `cli`) |
-| `canOpen` | boolean | Whether this thread can be opened. The UI greys the button out |
-| `subagents` | array | Optional. Errands this thread has out *right now*: `{ id, task, lastActivityAt }`. Drawn as small companions at the parent's building — no zone, no badge, not counted. Omit it and nothing changes |
-| `awaiting` | array | Optional. Other threads it asked to hear from that are still busy: `{ id, title }`, where `id` is that thread's own id. They are bots of their own, so this names them rather than adding companions. Omit it and nothing changes |
-| `ref` | object | **Opaque.** Whatever *you* need to find this thread again |
-### About `ref`
-`ref` is the whole reason the browser does not know what a session id looks like. Your adapter
-puts whatever it needs in there, the page hands it straight back on open and archive, and
-nothing between the two ever inspects it.
-Keep it small and keep it serialisable — it makes a round trip through JSON on every action.
-Do not put a file handle, a class instance, or a secret in it.
-## Ground rules
-- **Read-only. No exceptions.** An adapter never writes a file and never starts a process;
-  `test/read-only.test.mjs` fails if one tries. A harness's transcripts and records are
-  somebody's actual work, and the apps are viewers, not editors. If an adapter seems to need a
-  write, it does not — say so in an issue. Anything that has to write to a harness belongs to the
-  app that asks for it, outside this package.
-- **Never run anything out of another application's bundle.** Not to read from it, not to
-  execute it. Only files under the user's own home directory. Opening a thread goes through a
-  URL the OS resolves, or a command the user already has on `PATH`.
-- **Never block the scan.** It runs on a poll. Cache anything expensive against file size and
-  mtime. Claude Code's transcripts go through `transcriptReader` in
-  `../lib/claude-transcript.mjs`, which reads a new transcript's head and tail once and after
-  that only the lines appended since the last scan, so a 12MB transcript is never reparsed.
-- **Read heads, not whole files.** `readHead` in `../lib/fsutil.mjs` pulls the first chunk and
-  drops a trailing partial line, so `JSON.parse` never sees half a record.
-- **Expect malformed data.** A session being written *right now* is a normal thing to trip
-  over. Skip that record and move on; do not throw the pass away.
-- **Never widen `id` collisions.** The colony keys its archive list and saved layout on `id`.
-  Two harnesses handing back the same id would merge two unrelated threads into one bot.
-## Starting points
-Verified on a real machine:
-- **Claude Code** — desktop records in
-  `~/Library/Application Support/Claude/claude-code-sessions/<account>/<org>/local_*.json`
-  (`%APPDATA%\Claude\claude-code-sessions\…` on older Windows installs, and
-  `%LOCALAPPDATA%\Claude-Data\<install>\claude-code-sessions\…` on current ones, which leave a
-  `.user-data-left.<install>` marker in the old folder). The app folder is not always called
-  `Claude`: it is `Claude-3p` on some macOS installs, and each extra desktop profile gets its own
-  `Claude-<profile>` beside the first, so every `Claude*` folder holding a store is read. In the
-  same folder sits a
-  `deleted_<cliSessionId>` marker for every thread deleted in the app, holding the deletion time
-  in epoch ms — the record goes, the CLI transcript stays, and the marker is all that tells a
-  deleted thread from one started in a terminal, so the adapter reports it as `archived`; CLI
-  transcripts in `~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl`; live processes in
-  `~/.claude/sessions/*.json`, whose `status` is `busy`, `waiting` (a prompt is open, named in
-  `waitingFor`) or `idle`, and whose `messagingSocketPath` is the address other sessions message
-  it at. A session that sends `SendMessage` with `notify_when_idle: true` is waiting on the
-  session at that address until a user record reading `[Cross-session idle notice] "<address>"`
-  arrives. `CLAUDE_CONFIG_DIR` (the CLI's own override for `~/.claude`) and
-  `THREADCRUMBS_CLAUDE_DESKTOP_DIR` (the session store) point both roots elsewhere, which is how
-  `test/harness.test.mjs` fakes an install. Implemented in `claude-code.mjs`.
-- **Codex** — the desktop app, the VS Code extension and the CLI share one store. One row per
-  thread (title, cwd, branch, model, effort, archived) in `~/.codex/state_<n>.sqlite`, and
-  transcripts in `~/.codex/sessions/YYYY/MM/DD/rollout-<iso>-<uuid>.jsonl`, with records shaped
-  `{ timestamp, type, payload }`. They join on the session id, and the transcripts are the only
-  source for a session the database has not indexed yet. Renames are also in
-  `~/.codex/session_index.jsonl`. `CODEX_HOME` points it elsewhere. Implemented in `codex.mjs`.
-For anything else, the fastest way in is usually to start a throwaway session in that harness
-and watch which files change:
-```bash
-find ~ -maxdepth 4 -newermt '-2 minutes' -type f 2>/dev/null | grep -iv Library/Caches
-```
-## Checking your work
-`pnpm test` in this repo runs `test/harness.test.mjs`, which fakes an install of each harness in a
-temp folder. Add yours there. Then, against a real install:
-1. `node --check harnesses/my-harness.mjs`
-2. With Threadnauts running, `GET /api/harnesses` lists every registered harness and whether
-   `detect()` found it. If yours is missing or `detected: false`, stop here — nothing else
-   will work until it shows up:
-   ```bash
-   curl -s localhost:5274/api/harnesses
-   ```
-3. Scan straight from node and look at the result — the number should match what the harness
-   itself reports, and no field should be `undefined`:
-   ```bash
-   node -e 'import("./harnesses/my-harness.mjs").then(async m => {
-     const t = await m.default.scanThreads()
-     console.log(t.length, "threads"); console.dir(t[0], { depth: 4 })
-   })'
-   ```
-4. `pnpm dev` in Threadnauts, then confirm the bots appear on the right plots, the thread card
-   fills in, and Open does what you expect.
-5. Archive one thread and check it shows as archived **in the harness's own UI**, not just here.
+# Harness adapters
+A **harness** is whatever runs the agent threads — Claude Code, Codex CLI, OpenCode, and so on.
+The Threadcrumbs apps do not care which one you use: each asks every harness present on the
+machine for its threads, through these adapters, and shows whatever comes back. Threadnauts
+draws them as bots in its colony, which is where most of the wording below comes from.
+Adding one is meant to be **one new file in this directory**, plus one line in `index.mjs`.
+Nothing in an app's scanner, its API, or its page should need to change.
+If you find yourself editing those to land a harness, that is a bug in this seam — please say so
+in the PR, because the next person will hit it too.
+## The shape of it
+```js
+// harnesses/my-harness.mjs
+export default {
+  id: 'my-harness',              // stable, kebab-case, used as a key — never change it later
+  name: 'My Harness',            // what a human sees in the UI
+  detect,                        // () => Promise<boolean>
+  scanThreads,                   // () => Promise<Thread[]>
+  app,                           // { name, download }: the app that answers the deep link
+  openThread,                    // (ref) => { ok, url, command?, app } | { ok: false, error }
+  newSession,                    // (dir) => { ok, url, command?, app } | { ok: false, error }
+}
+```
+Then, in `index.mjs`:
+```js
+import myHarness from './my-harness.mjs'
+export const HARNESSES = [claudeCode, myHarness]
+```
+### `detect()`
+Is this harness on this machine at all? Usually just "does its data directory exist". Cheap —
+it runs on every scan, so that installing a harness while the colony is open is noticed on the
+next poll. Returning `false` means the harness is skipped entirely, and no bot for it
+ever appears.
+### `scanThreads()`
+The real work: return one `Thread` per session the harness knows about.
+Throwing is survivable — the scanner logs it and carries on with the other harnesses, so one
+broken adapter costs you its own threads and nothing else. Prefer that over returning junk.
+### `openThread(ref)` / `newSession(dir)`
+Return `{ ok: true, url }` and the server hands that URL to the OS opener. `openThread` gets
+the `ref` from the thread it belongs to; `newSession` gets an absolute directory that the
+server has already checked still exists.
+Add `command: { argv, cwd }` — the harness's own CLI resuming the same thread, with an absolute `argv[0]` —
+when the CLI is installed, and the server runs it in a terminal for a machine with no desktop app or a person who asked for one.
+Never spawn it yourself.
+Add `app: { name, download }` too, the same object as the adapter's own `app`: the app that answers
+the deep link, as a person would call it, and the page to download it from. When nothing on the
+machine answers the link, `present()` names that app, so the UI can say what to install instead
+of a click that does nothing. `app.also` can list other apps that would do, such as the Claude Code
+extension for VS Code.
+When another app can open the thread through links of its own, add `fallback: { app, urls, note }`.
+`present()` tries it when nothing answers `url`: it opens each URL in turn, two seconds apart,
+and returns `note`. Claude Code uses it to open the thread's folder in VS Code and then the
+extension's session link.
+If your harness has no deep link, return `{ ok: false, error: '…' }` and say why — the UI
+shows the message rather than pretending the click worked.
+### There is no `setArchived`, and that is deliberate
+No adapter writes to a harness. Not the transcripts, not the session records, not one
+flag. Threadnauts records archiving in its own `colony.json` and nowhere else: the thread leaves
+the map and the bot walks back to the ship.
+It used to write one flag — `isArchived` on Claude Code's own session record — and that write
+genuinely landed on disk. It just did not *mean* anything: the desktop app serves from the copy it
+loaded at launch, so the thread stayed in its list until the app restarted, and the app rewrote the
+record from memory the next time it touched the thread. Holding that together took a re-assert on
+every scan, a `ps` sweep to guess whether the app had re-read the file, and a *pending* state for
+the gap between them. All of that is gone, and the scan no longer starts a subprocess at all.
+Archiving in the harness's own UI still works and is still the right way to do it — your adapter
+reports it through the `archived` field and the bot goes home on the next poll.
+## The `Thread` your adapter returns
+Only `id` is truly required, but the colony gets duller the more you leave out — `project` is
+what earns a repo its own zone, and `lastActivityAt` is what sorts the whole map.
+| Field | Type | What it means |
+| --- | --- | --- |
+| `id` | string | **Unique across every harness.** A UUID is fine; otherwise prefix it, e.g. `my-harness:1234` |
+| `title` | string | Thread title. `'Untitled thread'` if the harness has none |
+| `preview` | string | First prompt, trimmed — shown on the thread card |
+| `project` | string | Repo/folder **name**. This is what claims a hex zone |
+| `projectPath` | string | Absolute path to the repo root |
+| `worktree` | string | Worktree name, or `''` |
+| `cwd` | string | Where the thread is actually working |
+| `gitBranch` | string | Branch name, or `''` |
+| `model` / `effort` | string | Shown on the thread card |
+| `createdAt` | number | Epoch ms |
+| `lastActivityAt` | number | Epoch ms. Sorts the colony and drives the "asleep for 3 days" behaviour |
+| `lastFocusedAt` | number | Epoch ms, `0` if unknowable |
+| `running` | boolean | Working **right now** — the bot hammers away |
+| `unread` | boolean | Done: the turn ended and moved on since you last looked — the bot stops and raises a hand |
+| `needsInput` | boolean | Needs you: stopped mid-turn on a permission prompt, a question, or an approval only you can answer — the bot holds a `?` and waves until you do. Outranks every other state |
+| `awaitingSubagents` | boolean | Waiting on bots: its own turn is over, or its only open calls are subagents, and subagents it sent out are still working, or another thread it asked to hear from is still busy — the bot stands at its site under a `…` until they report back. Outranks `running` and `unread` |
+| `hasError` | boolean | Errored — the bot slumps, red eyes |
+| `starred` / `routine` / `prState` | | Optional extras; `prState: 'merged'` triggers the confetti |
+| `archived` | boolean | Archived in the harness's own records. Read-only — reporting it is all an adapter does |
+| `sizeBytes` | number | Transcript size. **This is how finished a building looks**, on a log scale |
+| `source` | string | Free-form, for your own bookkeeping (the Claude adapter uses `desktop` / `cli`) |
+| `canOpen` | boolean | Whether this thread can be opened. The UI greys the button out |
+| `subagents` | array | Optional. Errands this thread has out *right now*: `{ id, task, lastActivityAt }`. Drawn as small companions at the parent's building — no zone, no badge, not counted. Omit it and nothing changes |
+| `awaiting` | array | Optional. Other threads it asked to hear from that are still busy: `{ id, title }`, where `id` is that thread's own id. They are bots of their own, so this names them rather than adding companions. Omit it and nothing changes |
+| `ref` | object | **Opaque.** Whatever *you* need to find this thread again |
+### About `ref`
+`ref` is the whole reason the browser does not know what a session id looks like. Your adapter
+puts whatever it needs in there, the page hands it straight back on open and archive, and
+nothing between the two ever inspects it.
+Keep it small and keep it serialisable — it makes a round trip through JSON on every action.
+Do not put a file handle, a class instance, or a secret in it.
+## Ground rules
+- **Read-only. No exceptions.** An adapter never writes a file and never starts a process;
+  `test/read-only.test.mjs` fails if one tries. The one process the readers share is
+  `lib/proc-start.mjs` asking the OS when a pid started, and DECISIONS.md says why. A harness's transcripts and records are
+  somebody's actual work, and the apps are viewers, not editors. If an adapter seems to need a
+  write, it does not — say so in an issue. Anything that has to write to a harness belongs to the
+  app that asks for it, outside this package.
+- **Never run anything out of another application's bundle.** Not to read from it, not to
+  execute it. Only files under the user's own home directory. Opening a thread goes through a
+  URL the OS resolves, or a command the user already has on `PATH`.
+- **Never block the scan.** It runs on a poll. Cache anything expensive against file size and
+  mtime. Claude Code's transcripts go through `transcriptReader` in
+  `../lib/claude-transcript.mjs`, which reads a new transcript's head and tail once and after
+  that only the lines appended since the last scan, so a 12MB transcript is never reparsed.
+- **Read heads, not whole files.** `readHead` in `../lib/fsutil.mjs` pulls the first chunk and
+  drops a trailing partial line, so `JSON.parse` never sees half a record.
+- **Expect malformed data.** A session being written *right now* is a normal thing to trip
+  over. Skip that record and move on; do not throw the pass away.
+- **Never widen `id` collisions.** The colony keys its archive list and saved layout on `id`.
+  Two harnesses handing back the same id would merge two unrelated threads into one bot.
+## Starting points
+Verified on a real machine:
+- **Claude Code** — desktop records in
+  `~/Library/Application Support/Claude/claude-code-sessions/<account>/<org>/local_*.json`
+  (`%APPDATA%\Claude\claude-code-sessions\…` on older Windows installs, and
+  `%LOCALAPPDATA%\Claude-Data\<install>\claude-code-sessions\…` on current ones, which leave a
+  `.user-data-left.<install>` marker in the old folder). The app folder is not always called
+  `Claude`: it is `Claude-3p` on some macOS installs, and each extra desktop profile gets its own
+  `Claude-<profile>` beside the first, so every `Claude*` folder holding a store is read. In the
+  same folder sits a
+  `deleted_<cliSessionId>` marker for every thread deleted in the app, holding the deletion time
+  in epoch ms — the record goes, the CLI transcript stays, and the marker is all that tells a
+  deleted thread from one started in a terminal, so the adapter reports it as `archived`; CLI
+  transcripts in `~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl`; live processes in
+  `~/.claude/sessions/*.json`, whose `status` is `busy`, `waiting` (a prompt is open, named in
+  `waitingFor`) or `idle`, and whose `messagingSocketPath` is the address other sessions message
+  it at. A session that sends `SendMessage` with `notify_when_idle: true` is waiting on the
+  session at that address until a user record reading `[Cross-session idle notice] "<address>"`
+  arrives. `CLAUDE_CONFIG_DIR` (the CLI's own override for `~/.claude`) and
+  `THREADCRUMBS_CLAUDE_DESKTOP_DIR` (the session store) point both roots elsewhere, which is how
+  `test/harness.test.mjs` fakes an install. Implemented in `claude-code.mjs`.
+- **Codex** — the desktop app, the VS Code extension and the CLI share one store. One row per
+  thread (title, cwd, branch, model, effort, archived) in `~/.codex/state_<n>.sqlite`, and
+  transcripts in `~/.codex/sessions/YYYY/MM/DD/rollout-<iso>-<uuid>.jsonl`, with records shaped
+  `{ timestamp, type, payload }`. They join on the session id, and the transcripts are the only
+  source for a session the database has not indexed yet. Renames are also in
+  `~/.codex/session_index.jsonl`. `CODEX_HOME` points it elsewhere. Implemented in `codex.mjs`.
+For anything else, the fastest way in is usually to start a throwaway session in that harness
+and watch which files change:
+```bash
+find ~ -maxdepth 4 -newermt '-2 minutes' -type f 2>/dev/null | grep -iv Library/Caches
+```
+## Checking your work
+`pnpm test` in this repo runs `test/harness.test.mjs`, which fakes an install of each harness in a
+temp folder. Add yours there. Then, against a real install:
+1. `node --check harnesses/my-harness.mjs`
+2. With Threadnauts running, `GET /api/harnesses` lists every registered harness and whether
+   `detect()` found it. If yours is missing or `detected: false`, stop here — nothing else
+   will work until it shows up:
+   ```bash
+   curl -s localhost:5274/api/harnesses
+   ```
+3. Scan straight from node and look at the result — the number should match what the harness
+   itself reports, and no field should be `undefined`:
+   ```bash
+   node -e 'import("./harnesses/my-harness.mjs").then(async m => {
+     const t = await m.default.scanThreads()
+     console.log(t.length, "threads"); console.dir(t[0], { depth: 4 })
+   })'
+   ```
+4. `pnpm dev` in Threadnauts, then confirm the bots appear on the right plots, the thread card
+   fills in, and Open does what you expect.
+5. Archive one thread and check it shows as archived **in the harness's own UI**, not just here.