@threadcrumbs/common 0.0.0-stage → 0.1.1

package/LICENSE.md

@@ -0,0 +1,34 @@
+# License
+
+Copyright (c) 2026 Threadcrumbs LLC. All rights reserved.
+
+This software is proprietary. Threadcrumbs LLC grants you a free, non-exclusive,
+non-transferable license to install and run it, as published by Threadcrumbs LLC, on computers
+you own or control, for your personal or internal business use.
+
+Paid features, such as Threadnauts Pro, are licensed to you only as your license key and
+subscription allow, under the terms you agreed to when you bought them.
+
+You may not:
+
+- copy, modify, merge, publish, distribute, sublicense, rent, or sell this software, in whole
+  or in part;
+- reverse engineer, decompile, or disassemble it, except where the law allows this despite
+  this restriction;
+- get around its license checks, or share a license key or paid content beyond what your
+  subscription allows.
+
+This license ends automatically if you break these terms. When it ends, you must stop using
+the software and delete your copies of it.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
+BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
+NONINFRINGEMENT. TO THE FULLEST EXTENT THE LAW ALLOWS, IN NO EVENT SHALL THREADCRUMBS LLC BE
+LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR
+OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.
+
+Any other use needs a separate written agreement with Threadcrumbs LLC
+(hello@threadcrumbs.io).
+
+Portions of this software are third-party code used under their own licenses, which are
+reproduced in [NOTICES.md](NOTICES.md). Those licenses govern those portions.

package/NOTICES.md

@@ -0,0 +1,33 @@
+# Notices
+
+## Third-party
+
+@threadcrumbs/common includes the following third-party software, used under its own license.
+
+### Original source code
+
+Portions of @threadcrumbs/common are derived from source code released under the MIT License.
+
+```text
+MIT License
+
+Copyright (c) 2026 Jarren Rocks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Threadcrumbs common
+
+Code the Threadcrumbs apps share, so a fix lands once instead of once per app. Today that's the
+harness readers that Threadnauts and Threadgauge both depend on. More will move in as the apps
+need it.
+
+## What's in it
+
+| Import | What it is |
+| --- | --- |
+| `@threadcrumbs/common/harnesses` | `HARNESSES`, `harnessById`, `detectedHarnesses`: one session reader per coding-agent harness, which finds every thread and says how to open it. Threadnauts uses these. The contract is [`harnesses/README.md`](harnesses/README.md) |
+| `@threadcrumbs/common/harnesses/<id>` | One session reader on its own, such as `claude-code` |
+| `@threadcrumbs/common/telemetry` | `TELEMETRY`: one telemetry reader per harness, reporting each session's live status, tool, context, tokens, spend, and plan. Threadgauge uses these. The contract, and what each harness records, is in [`telemetry/README.md`](telemetry/README.md) |
+| `@threadcrumbs/common/telemetry/<id>` | One telemetry reader on its own |
+| `@threadcrumbs/common/lib/fsutil` | The file helpers the readers use, including `findExecutable`, which Threadnauts also uses to find terminals |
+| `@threadcrumbs/common/lib/claude-transcript` | The one Claude Code transcript parser both Claude readers use. It reads each transcript incrementally, and in skim mode it reads a new transcript's head and tail instead of all of it |
+| `@threadcrumbs/common/lib/*` | The other helpers the readers share: `jsonl-follower` (incremental JSONL reading), `sqlite` (read-only opens and column checks), `telemetry-fields` (titles and plans), `opencode-store` (the store OpenCode and Kilo Code share), `claude-desktop` (the Claude app's session stores and records, for both Claude readers), `anthropic-prices` (Anthropic's list prices), plus the Cursor folder decoding and Hermes home lookup both readers of those harnesses use |
+| `@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 |
+
+`launch/` is the only part of this package that starts processes, and `license/store.mjs` is the
+only part that writes a file. The readers and `orgs/` import neither.
+
+These are likely to follow, each when an app first needs it from here:
+- **Suite discovery:** the `/api/about` identity format and the port search.
+- **Local-server safety:** the Host and Origin checks and the security policy.
+- **Design tokens:** the palette and status colors.
+
+## Using it from an app
+
+The apps live beside this repo, in the same folder:
+
+```
+repos/@threadcrumbs/
+  common/
+  threadgauge/
+  threadnauts/
+```
+
+Each app depends on it with `"@threadcrumbs/common": "link:../common"`, so an edit here shows up
+in both apps without a release. Clone this repo next to an app before running `pnpm install`
+there.
+
+An app that publishes to npm depends on a published version instead. This package is on npm as
+[`@threadcrumbs/common`](https://www.npmjs.com/package/@threadcrumbs/common).
+
+## Publishing a version
+
+1. Raise `version` in `package.json`, and commit it.
+2. Run `npm pack --dry-run` and check the list: only `package.json`, `README.md`, `LICENSE.md`,
+   `NOTICES.md`, and the folders in `files`.
+3. Tag the commit `v<version>`, and push the commit and the tag.
+4. Run `npm publish`. `publishConfig` makes it public, and npm asks for your second factor.
+5. Check it with `npm view @threadcrumbs/common version`.
+
+## Settings it reads
+
+Besides each harness's own variables (`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `OPENCODE_DB`,
+`KILO_DB`, `ANTIGRAVITY_HOME`, `HERMES_HOME`), the readers take five overrides, and `launch/`
+takes one. Tests use the readers' five to fake an install:
+
+| Variable | What it does |
+| --- | --- |
+| `THREADCRUMBS_CLI_DIRS` | Replaces the install folders searched for a harness's CLI; empty means `PATH` alone |
+| `THREADCRUMBS_CLAUDE_DESKTOP_DIR` | The Claude desktop app's session store |
+| `THREADCRUMBS_VSCODE_EXTENSIONS_DIR` | VS Code's extensions folder, where Claude Code looks for its VS Code extension to open threads in when the Claude app is missing |
+| `THREADCRUMBS_CURSOR_PROJECTS_DIR` | Cursor's projects folder |
+| `THREADCRUMBS_ANTIGRAVITY_HOME` | Antigravity's home, ahead of `ANTIGRAVITY_HOME` |
+| `THREADCRUMBS_TERMINAL` | The terminal `launch/` opens a CLI in, ahead of `$TERMINAL` (Linux and macOS). `THREADNAUTS_TERMINAL` still works |
+
+The license store takes three more:
+
+| Variable | What it does |
+| --- | --- |
+| `THREADCRUMBS_DATA_DIR` | The suite's data folder, where `license.json` lives, instead of the platform's own place for it |
+| `THREADCRUMBS_LICENSE_KEYS` | `{ "<kid>": "<public key>" }`, added to the trusted keys only in a development build, so a dev build can check the key service's sandbox licenses |
+| `THREADCRUMBS_CLOUD_URL` | The key service's address, ahead of `cloudUrl()`'s default, in any build |
+
+## Tests
+
+```bash
+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/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,
+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.
+
+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
+link checks in `test/launch.test.mjs`, get their run there.
+
+Node 22.13 or newer, for `node:sqlite`.
+
+## License
+
+Proprietary. See [LICENSE.md](LICENSE.md). Portions are derived from source code released under
+the MIT License, whose notice is in [NOTICES.md](NOTICES.md) and ships in every copy.

package/harnesses/README.md

@@ -0,0 +1,213 @@
+# 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.

package/harnesses/antigravity.mjs

@@ -0,0 +1,269 @@
+/**
+ * Harness adapter: Antigravity CLI (Google).
+ *
+ * Antigravity CLI stores sessions under `~/.gemini/antigravity-cli/brain/<sessionId>/`.
+ * Transcripts are JSONL files located at `.system_generated/logs/transcript.jsonl`
+ * or `transcript.jsonl` inside the session directory.
+ *
+ * Read-only, no subprocess, and no modifications to harness files.
+ */
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+import os from 'node:os'
+import { exists, jsonLines, listDirs, readHead, readTail, findExecutable } from '../lib/fsutil.mjs'
+
+const HOME = os.homedir()
+const ANTIGRAVITY_HOME =
+  process.env.THREADCRUMBS_ANTIGRAVITY_HOME ||
+  process.env.ANTIGRAVITY_HOME ||
+  path.join(HOME, '.gemini', 'antigravity-cli')
+const BRAIN_DIR = path.join(ANTIGRAVITY_HOME, 'brain')
+
+const HEAD_BYTES = 96 * 1024
+const TAIL_BYTES = 32 * 1024
+const ACTIVE_WINDOW_MS = 30 * 60 * 1000
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+const APP = Object.freeze({ name: 'Antigravity', download: 'https://antigravity.google/download' })
+const ENDED = new Set(['DONE', 'ERROR', 'CANCELED', 'INTERRUPTED', 'CLEARED', 'INVALID'])
+
+/** Prefixed, per the contract in `harnesses/README.md`. */
+const ID = (raw) => `antigravity:${raw}`
+
+const clean = (v) => String(v || '').replace(/\s+/g, ' ').trim()
+
+function contentText(content) {
+  if (typeof content === 'string') return content
+  if (!Array.isArray(content)) return ''
+  return content
+    .map((p) => (typeof p === 'string' ? p : p?.text || p?.input_text || ''))
+    .filter(Boolean)
+    .join('\n')
+}
+
+/** Extract user query text from prompt/input record. */
+function userText(record) {
+  const raw = contentText(record?.content || record?.message?.content || '')
+  // Strip XML-like wrapper tags if present
+  const query = /<USER_REQUEST>\s*([\s\S]*?)\s*<\/USER_REQUEST>/i.exec(raw)
+  const text = query ? query[1] : raw.replace(/<[a-z_]+>[\s\S]*?<\/[a-z_]+>/gi, ' ')
+  return clean(text)
+}
+
+/** Try to extract workspace/cwd from prompt user_information tags if present. */
+function extractCwd(text) {
+  const m = /active workspaces, each defined by a URI[\s\S]*?\[(.*?)\]\s*->/i.exec(text)
+  if (m && path.isAbsolute(m[1])) return m[1]
+  return ''
+}
+
+/**
+ * Where each conversation ran. A transcript usually does not say, so most sessions arrived with
+ * no folder at all and shared one zone called "unknown". The CLI's prompt history beside `brain/`
+ * does: every prompt typed is a line of `{ display, timestamp, workspace, conversationId }`. Older
+ * lines carry no conversation id, so not every session is covered — those stay unknown rather
+ * than being guessed from whichever files the session happened to read.
+ *
+ * The folder a conversation started in wins. Re-read only when the file changes.
+ *
+ * The same lines are the only sign of a turn in progress. The transcript is written when a turn
+ * ends, so a prompt newer than the transcript has not been answered yet, and a conversation with
+ * a prompt and no transcript is on its first turn.
+ */
+const HISTORY = path.join(ANTIGRAVITY_HOME, 'history.jsonl')
+let history = { mtime: -1, conversations: new Map() }
+
+function epochMs(value) {
+  if (typeof value === 'number') return value < 1e11 ? value * 1000 : value
+  const t = Date.parse(String(value || ''))
+  return Number.isNaN(t) ? 0 : t
+}
+
+async function conversations() {
+  const st = await fsp.stat(HISTORY).catch(() => null)
+  if (!st) return new Map()
+  if (st.mtimeMs === history.mtime) return history.conversations
+  const out = new Map()
+  try {
+    for (const r of jsonLines(await fsp.readFile(HISTORY, 'utf8'))) {
+      const id = r?.conversationId
+      if (typeof id !== 'string') continue
+      const entry = out.get(id) || { workspace: '', prompt: '', firstPromptAt: 0, lastPromptAt: 0 }
+      const dir = r?.workspace
+      const at = epochMs(r?.timestamp)
+      if (!entry.workspace && typeof dir === 'string' && path.isAbsolute(dir)) entry.workspace = dir
+      if (!entry.prompt && typeof r?.display === 'string') entry.prompt = clean(r.display)
+      entry.firstPromptAt ||= at
+      entry.lastPromptAt = Math.max(entry.lastPromptAt, at)
+      out.set(id, entry)
+    }
+  } catch {
+    /* mid-write, or gone */
+  }
+  history = { mtime: st.mtimeMs, conversations: out }
+  return out
+}
+
+async function findTranscriptFile(sessionDir) {
+  const candidates = [
+    path.join(sessionDir, '.system_generated', 'logs', 'transcript_full.jsonl'),
+    path.join(sessionDir, '.system_generated', 'logs', 'transcript.jsonl'),
+    path.join(sessionDir, 'transcript.jsonl'),
+  ]
+  for (const c of candidates) {
+    if (await exists(c)) return c
+  }
+  return null
+}
+
+async function scanTranscripts() {
+  const out = []
+  for (const sessionDir of await listDirs(BRAIN_DIR)) {
+    const id = path.basename(sessionDir)
+    if (!UUID.test(id)) continue
+    const file = await findTranscriptFile(sessionDir)
+    if (!file) continue
+    try {
+      const st = await fsp.stat(file)
+      if (!st.size) continue
+      out.push({
+        id,
+        file,
+        sessionDir,
+        size: st.size,
+        mtime: st.mtimeMs,
+        born: st.birthtimeMs,
+      })
+    } catch {
+      /* vanished */
+    }
+  }
+  return out
+}
+
+const parseCache = new Map()
+async function facts(entry) {
+  const hit = parseCache.get(entry.id)
+  if (hit && hit.mtime === entry.mtime && hit.size === entry.size) return hit.value
+
+  const value = { prompt: '', cwd: '', startedAt: 0, closed: true, errored: false, modelsTurn: false }
+  try {
+    for (const r of jsonLines(await readHead(entry.file, HEAD_BYTES))) {
+      if (r?.type === 'USER_INPUT' || r?.role === 'user' || r?.source === 'USER_EXPLICIT') {
+        const text = userText(r)
+        if (!value.prompt && text) value.prompt = text
+        const rawContent = String(r?.content || '')
+        if (!value.cwd) value.cwd = r?.cwd || extractCwd(rawContent) || ''
+        if (!value.startedAt && r?.created_at) {
+          const t = Date.parse(r.created_at)
+          if (!Number.isNaN(t)) value.startedAt = t
+        }
+        if (value.prompt && value.cwd && value.startedAt) break
+      }
+    }
+
+    const tail = jsonLines(await readTail(entry.file, TAIL_BYTES))
+    if (tail.length > 0) {
+      const last = tail[tail.length - 1]
+      value.errored = last?.status === 'ERROR' || Boolean(last?.error)
+      value.closed = ENDED.has(last?.status)
+      value.modelsTurn = !value.closed && (last?.type === 'USER_INPUT' || last?.role === 'user')
+    }
+  } catch {
+    /* mid-write, or vanished */
+  }
+
+  parseCache.set(entry.id, { mtime: entry.mtime, size: entry.size, value })
+  return value
+}
+
+async function scanThreads() {
+  const [entries, history] = await Promise.all([scanTranscripts(), conversations()])
+  const now = Date.now()
+  const threads = []
+  const thread = ({ id, f, typed, mtime, born, size }) => {
+    const cwd = f.cwd || typed?.workspace || ''
+    const prompt = f.prompt || typed?.prompt || ''
+    const lastActivityAt = Math.max(mtime, typed?.lastPromptAt || 0)
+    const fresh = now - lastActivityAt < ACTIVE_WINDOW_MS
+    const prompted = Boolean(typed) && typed.lastPromptAt > mtime && now - typed.lastPromptAt < ACTIVE_WINDOW_MS
+    const running = prompted || (fresh && f.modelsTurn)
+    return {
+      id: ID(id),
+      title: (prompt || 'Untitled thread').slice(0, 120),
+      preview: prompt.slice(0, 240),
+      project: cwd ? path.basename(cwd) : 'unknown',
+      projectPath: cwd,
+      worktree: '',
+      cwd,
+      gitBranch: '',
+      model: 'antigravity',
+      effort: '',
+      createdAt: f.startedAt || typed?.firstPromptAt || born || mtime,
+      lastActivityAt,
+      lastFocusedAt: 0,
+      unread: fresh && !running && !f.errored,
+      running,
+      hasError: !running && f.errored,
+      starred: false,
+      routine: '',
+      prState: '',
+      archived: false,
+      sizeBytes: size,
+      source: 'cli',
+      canOpen: true,
+      ref: { sessionId: id, cwd },
+    }
+  }
+
+  for (const entry of entries) {
+    threads.push(thread({ id: entry.id, f: await facts(entry), typed: history.get(entry.id), mtime: entry.mtime, born: entry.born, size: entry.size }))
+  }
+  const seen = new Set(entries.map((e) => e.id))
+  for (const [id, typed] of history) {
+    if (seen.has(id) || !UUID.test(id) || now - typed.lastPromptAt >= ACTIVE_WINDOW_MS) continue
+    const f = { prompt: '', cwd: '', startedAt: 0, closed: false, errored: false, modelsTurn: false }
+    threads.push(thread({ id, f, typed, mtime: 0, born: 0, size: 0 }))
+  }
+  return threads
+}
+
+async function openThread(ref) {
+  const id = ref?.sessionId
+  if (typeof id !== 'string' || !UUID.test(id)) {
+    return { ok: false, error: 'No openable Antigravity session id on that thread' }
+  }
+  const cwd = typeof ref?.cwd === 'string' ? ref.cwd : ''
+  const url = `antigravity://resume?session=${id}`
+  const agy = await findExecutable('agy')
+  const legacy = agy ? null : (await findExecutable('antigravity')) || (await findExecutable('antigravity-cli'))
+  let command
+  if (agy) command = { argv: [agy, '--conversation', id], cwd }
+  else if (legacy) command = { argv: [legacy, '--resume', id], cwd }
+  return { ok: true, url, command, app: APP }
+}
+
+async function newSession(dir) {
+  const abs = String(dir || '').replace(/\\/g, '/')
+  if (!abs.startsWith('/')) return { ok: false, error: 'That folder is not somewhere Antigravity can open' }
+  const bin = (await findExecutable('agy')) || (await findExecutable('antigravity')) || (await findExecutable('antigravity-cli'))
+  const url = `antigravity://new?${new URLSearchParams({ path: abs })}`
+  let command
+  if (bin) {
+    command = { argv: [bin], cwd: abs }
+  }
+  return { ok: true, url, command, app: APP }
+}
+
+const detect = () => exists(BRAIN_DIR)
+
+export default {
+  id: 'antigravity',
+  name: 'Antigravity CLI',
+  app: APP,
+  detect,
+  scanThreads,
+  openThread,
+  newSession,
+  paths: { ANTIGRAVITY_HOME, BRAIN_DIR },
+}