@vibe-commit/capture 0.6.0 → 0.7.0

package/dist/agents/codex_cli.js

@@ -11,7 +11,11 @@
  * measured by this task.** They are recorded as the brief stated them so a later
  * reader can check them against the product rather than against this file.
  */
-import { codexHooksPath, codexTranscriptRoot, isTranscriptFile } from "../paths.js";
+import { readdirSync, realpathSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { CODEX_INDEX_FILE, codexHooksPath, codexIndexDir, codexTranscriptRoot, isInside, isTranscriptFile, } from "../paths.js";
+import { readEntries, sessionFile } from "./session_listing.js";
 /**
  * `SessionEnd` is the tight one — 3 s registered, 2.2 s client.
  *
@@ -24,6 +28,226 @@ const CODEX_SESSION_END_CLIENT_MS = 2_200;
 /** `Stop` and `PreCompact` are registered far wider — 30 s, client 8 s. */
 const CODEX_TURN_REGISTERED_MS = 30_000;
 const CODEX_TURN_CLIENT_MS = 8_000;
+/**
+ * `SessionStart` takes the turn clocks, with no fast path of its own.
+ *
+ * ⛔ **A logged shortcut** — gstack-shortcut(dec-e650afbf), eng review D7 · B.
+ * The ceiling: a hung `SessionStart` can hold a session's start up by as long as
+ * the REGISTERED timeout (30 s here). Upgrade when a measurement or a user report
+ * shows session-start delay, or before slice 2's grants fetch lands in this handler.
+ */
+const CODEX_SESSION_START_REGISTERED_MS = CODEX_TURN_REGISTERED_MS; // gstack-shortcut(dec-e650afbf)
+const CODEX_SESSION_START_CLIENT_MS = CODEX_TURN_CLIENT_MS; // gstack-shortcut(dec-e650afbf)
+/**
+ * ⛔ **THE FOUR COLUMNS, AND NO OTHER — `D11 · A`, Alexander's approved read.**
+ *
+ * The thread index also holds `first_user_message`, `title`, `preview` and more,
+ * which are CONTENT. Selecting one would turn a metadata read into a transcript
+ * read, so the statement names exactly these four and `test/scan-codex-index.test.ts`
+ * asserts the SQL carries nothing else. ⚠ **`archived` is not here either, on
+ * purpose** (VQ, 2026-10-24): an archived thread's `rollout_path` is decided by
+ * the admission below, and a fifth column would change the approved read surface.
+ */
+export const CODEX_INDEX_COLUMNS = ["cwd", "git_origin_url", "rollout_path", "created_at"];
+/** The one statement the adapter runs against a thread row. */
+export const CODEX_INDEX_SQL = `SELECT ${CODEX_INDEX_COLUMNS.join(", ")} FROM threads`;
+/** How long a locked index is waited for before the adapter gives up (eng review D2). */
+const CODEX_BUSY_TIMEOUT_MS = 1_000;
+/**
+ * `node:sqlite`, loaded here and nowhere else, with ITS warning and only its
+ * warning dropped — eng review D2 · A.
+ *
+ * Node 22 prints `ExperimentalWarning: SQLite is an experimental feature…` to
+ * stderr the first time the module loads, which would land mid-screen in the
+ * picker and breaks DESIGN.md §13's output rules. `process.emitWarning` is
+ * wrapped for the duration of the one `require` and restored in a `finally`;
+ * any OTHER warning, in that window or after it, still prints. Measured on
+ * node 22.17.0.
+ *
+ * ⚠ **A `require` and not a dynamic `import()`**, so the whole adapter stays
+ * synchronous like every other lister (`scan` is a chain of `execFileSync`
+ * anyway) and the wrapped window is exactly the load, not a promise turn that
+ * something else could emit a warning inside. Lazy: a machine with no Codex
+ * never loads the module at all.
+ */
+function loadSqlite() {
+    const original = process.emitWarning;
+    process.emitWarning = ((warning, ...rest) => {
+        const type = typeof warning === "string" ? rest[0] : warning.name;
+        const message = typeof warning === "string" ? warning : warning.message;
+        if (type === "ExperimentalWarning" && message.startsWith("SQLite"))
+            return;
+        return original.call(process, warning, ...rest);
+    });
+    try {
+        return createRequire(import.meta.url)("node:sqlite");
+    }
+    finally {
+        process.emitWarning = original;
+    }
+}
+/** Does the `threads` table carry all four columns? A bare name test, nothing deeper. */
+function hasIndexColumns(db) {
+    const present = new Set(db.prepare("PRAGMA table_info(threads)").all().map((c) => String(c.name)));
+    return CODEX_INDEX_COLUMNS.every((column) => present.has(column));
+}
+/** A locked database is a different line from an unrecognised one. */
+function readFailure(err) {
+    return /locked|busy/i.test(err instanceof Error ? err.message : "")
+        ? "index locked"
+        : "unreadable";
+}
+/**
+ * Rollout files under `sessions/` that NO index row names — counted, never opened.
+ *
+ * Open Question 6's text, as VQ ruled (PR 1 ruling 5c): an index which cannot see a
+ * session is a thing to REPORT, not to guess about. The walk lists directory entries — names
+ * and file types, nothing else — and counts each regular `.jsonl`; a symlink is
+ * not a file here (`Dirent.isFile` is false for it).
+ *
+ * Compared as REALPATHS on both sides, because the index stores the path Codex
+ * wrote and the walk builds its own from `home`; a symlinked home would otherwise
+ * make every rollout look unindexed. A row whose rollout has gone cannot be
+ * resolved and names nothing, which is correct: it is not on disk to be matched.
+ */
+function countUnindexed(root, rolloutPaths) {
+    const named = new Set();
+    for (const path of rolloutPaths) {
+        try {
+            named.add(realpathSync(path));
+        }
+        catch {
+            // Gone from disk: it names no file that the walk could find.
+        }
+    }
+    let base;
+    try {
+        base = realpathSync(root);
+    }
+    catch {
+        return 0;
+    }
+    let count = 0;
+    const visit = (dir) => {
+        let entries;
+        try {
+            entries = readEntries(dir);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries ?? []) {
+            const path = join(dir, entry.name);
+            if (entry.isDirectory())
+                visit(path);
+            else if (entry.isFile() && entry.name.endsWith(".jsonl") && !named.has(path))
+                count += 1;
+        }
+    };
+    visit(base);
+    return count;
+}
+/**
+ * Codex's sessions, from its thread index — `D11 · A`, eng review D2, `scan`.
+ *
+ * Codex keeps rollouts DATE-keyed (`sessions/YYYY/MM/DD/`), so a folder walk
+ * cannot say which repo one belongs to; its `threads` table can, because it
+ * records the real `cwd`. That row is the whole reason this adapter exists and
+ * the reason a Codex row is never ambiguous.
+ *
+ * ## ⛔ What is read, and how
+ *
+ *   - **exactly `state_5.sqlite`**, and any other `state_N` is `unrecognised
+ *     index` (Open Question 6; see `codexIndexDir`).
+ *   - **`readOnly`, never `immutable`.** Codex keeps everything since its last
+ *     checkpoint in the `-wal` file (on the author's machine, every thread since
+ *     Sep 30), and an `immutable` open ignores it.
+ *   - **the four columns only** (`CODEX_INDEX_SQL`), after a `PRAGMA table_info`
+ *     check, and a 1000 ms busy timeout. Any failure is this agent's
+ *     `unreadable` answer, so the other two agents' rows are untouched.
+ *
+ * ## ⛔ The rollout file is `lstat`ed, never opened
+ *
+ * A row is admitted only if its `rollout_path` lies under the sessions root and
+ * is a regular file there. That is also what decides an ARCHIVED thread, whose
+ * rollout is not under `sessions/`. The row's `git_origin_url` is carried but is
+ * not the slug source: the scan names a repo from the CLONE (`resolveRepoSlug`),
+ * so there is one normalisation and not two.
+ */
+function codexSessionSource(home, env) {
+    const dir = codexIndexDir(home, env);
+    const file = join(dir, CODEX_INDEX_FILE);
+    let present;
+    try {
+        present = readdirSync(dir);
+    }
+    catch (err) {
+        const code = err.code;
+        return code === "ENOENT" || code === "ENOTDIR"
+            ? { kind: "rows", rows: [], unindexed: 0 }
+            : { kind: "unreadable", reason: "unreadable" };
+    }
+    if (!present.includes(CODEX_INDEX_FILE)) {
+        // A Codex that keeps its index under another generation's name is a store
+        // this client was not checked against. One with no index at all has simply
+        // never recorded a thread — and its rollouts, if any, are all unindexed.
+        return present.some((name) => /^state_\d+\.sqlite$/.test(name))
+            ? { kind: "unreadable", reason: "unrecognised index" }
+            : { kind: "rows", rows: [], unindexed: countUnindexed(codexTranscriptRoot(home, env), []) };
+    }
+    let sqlite;
+    try {
+        sqlite = loadSqlite();
+    }
+    catch {
+        return { kind: "unreadable", reason: "unreadable" };
+    }
+    let db = null;
+    try {
+        // ⚠ `readOnly` stops THIS CODE writing the index and does not stop SQLite creating its own
+        // `-wal`/`-shm` files beside it, which any reader of a WAL database whose writer has closed does
+        // (measured by VQ on node 22.17, PR 1 F1). Nothing is written to `state_5.sqlite` itself.
+        db = new sqlite.DatabaseSync(file, { readOnly: true });
+        db.exec(`PRAGMA busy_timeout = ${CODEX_BUSY_TIMEOUT_MS}`);
+        if (!hasIndexColumns(db))
+            return { kind: "unreadable", reason: "unrecognised index" };
+        const root = codexTranscriptRoot(home, env);
+        const rows = [];
+        const named = [];
+        for (const row of db.prepare(CODEX_INDEX_SQL).all()) {
+            const { cwd, git_origin_url: origin, rollout_path: rollout, created_at: created } = row;
+            if (typeof cwd !== "string" || typeof rollout !== "string")
+                continue;
+            // Every path an index row names counts as INDEXED, admitted or not: an archived thread's rollout
+            // is not "missing from the index", it is simply not capturable (`D11 · A`).
+            named.push(rollout);
+            if (!isInside(root, rollout) || !isTranscriptFile(root, rollout))
+                continue;
+            const session = sessionFile(rollout);
+            if (session === null)
+                continue;
+            rows.push({
+                cwd,
+                origin: typeof origin === "string" ? origin : null,
+                // `created_at` is whole SECONDS (measured), the rest of this client's
+                // times are milliseconds.
+                session: typeof created === "number" ? { ...session, startedMs: created * 1000 } : session,
+            });
+        }
+        return { kind: "rows", rows, unindexed: countUnindexed(root, named) };
+    }
+    catch (err) {
+        return { kind: "unreadable", reason: readFailure(err) };
+    }
+    finally {
+        try {
+            db?.close();
+        }
+        catch {
+            // Closing a read-only handle that failed to open is not a second finding.
+        }
+    }
+}
 export const CODEX_CLI = {
     id: "codex-cli",
     transport: "ndjson",
@@ -46,7 +270,17 @@ export const CODEX_CLI = {
     // against three throwaway `CODEX_HOME`s settled it: `SessionEnd` is recognised
     // and says so by clamping, while `session_end` and a bogus key produce NO
     // diagnostic — a file that parses, registers nothing, and reports success.
-    eventNames: { Stop: "Stop", PreCompact: "PreCompact", SessionEnd: "SessionEnd" },
+    // `SessionStart` is in that schema list too, spelled the same way, and MEASURED
+    // live (Open Question 1, Codex 0.148.0): it fires before the first prompt — in
+    // the TUI lazily, when the first prompt is submitted — and accepts a
+    // `systemMessage`. ⚠ Those runs were under cmux's `--dangerously-bypass-hook-trust`;
+    // stock Codex >= 0.131.0 runs a user-level hook only after the user trusts it.
+    eventNames: {
+        Stop: "Stop",
+        PreCompact: "PreCompact",
+        SessionEnd: "SessionEnd",
+        SessionStart: "SessionStart",
+    },
     // ⛔ `~/.codex/hooks.json`, honouring `CODEX_HOME` — MEASURED, since every
     // probe in this unit drove a real `codex` through a throwaway `CODEX_HOME`
     // and it read the `hooks.json` there. The NESTED shape, also measured: a
@@ -66,6 +300,10 @@ export const CODEX_CLI = {
             registeredTimeoutMs: CODEX_SESSION_END_REGISTERED_MS,
             clientBudgetMs: CODEX_SESSION_END_CLIENT_MS,
         },
+        SessionStart: {
+            registeredTimeoutMs: CODEX_SESSION_START_REGISTERED_MS,
+            clientBudgetMs: CODEX_SESSION_START_CLIENT_MS,
+        },
     },
     // The delegated path ARRIVES on stdin as `agent_transcript_path` — there is no
     // directory to glob. Nothing parses it yet; the discriminator is here so the
@@ -79,6 +317,7 @@ export const CODEX_CLI = {
     // of a measurement, not as a fact about the agent. Measuring it is a change to
     // this line and nothing else.
     sessionIdFromEnv: () => null,
+    sessionSource: codexSessionSource,
     // ⛔ NO `locateCurrentTranscript`, and the omission is the decision. Finding
     // the repository would mean reading a `cwd` out of the transcript's own
     // records — ANALYSIS, which D60 §D6 forbids this client. `connect` therefore

package/dist/agents/codex_cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"codex_cli.js","sourceRoot":"","sources":["../../src/agents/codex_cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGpF;;;;;;GAMG;AACH,MAAM,+BAA+B,GAAG,KAAK,CAAC;AAC9C,MAAM,2BAA2B,GAAG,KAAK,CAAC;AAE1C,2EAA2E;AAC3E,MAAM,wBAAwB,GAAG,MAAM,CAAC;AACxC,MAAM,oBAAoB,GAAG,KAAK,CAAC;AAEnC,MAAM,CAAC,MAAM,SAAS,GAAsB;IAC1C,EAAE,EAAE,WAAW;IACf,SAAS,EAAE,QAAQ;IACnB,cAAc,EAAE,mBAAmB;IACnC,yEAAyE;IACzE,4EAA4E;IAC5E,0EAA0E;IAC1E,+DAA+D;IAC/D,UAAU,EAAE,gBAAgB;IAC5B,4EAA4E;IAC5E,8EAA8E;IAC9E,6EAA6E;IAC7E,8EAA8E;IAC9E,+EAA+E;IAC/E,mEAAmE;IACnE,EAAE;IACF,kEAAkE;IAClE,4EAA4E;IAC5E,+EAA+E;IAC/E,+EAA+E;IAC/E,0EAA0E;IAC1E,2EAA2E;IAC3E,UAAU,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE;IAChF,0EAA0E;IAC1E,2EAA2E;IAC3E,yEAAyE;IACzE,yEAAyE;IACzE,gEAAgE;IAChE,UAAU,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,QAAQ,EAAE;IACrD,MAAM,EAAE;QACN,IAAI,EAAE;YACJ,mBAAmB,EAAE,wBAAwB;YAC7C,cAAc,EAAE,oBAAoB;SACrC;QACD,UAAU,EAAE;YACV,mBAAmB,EAAE,wBAAwB;YAC7C,cAAc,EAAE,oBAAoB;SACrC;QACD,UAAU,EAAE;YACV,mBAAmB,EAAE,+BAA+B;YACpD,cAAc,EAAE,2BAA2B;SAC5C;KACF;IACD,+EAA+E;IAC/E,6EAA6E;IAC7E,oEAAoE;IACpE,oBAAoB,EAAE,UAAU;IAChC,SAAS,EAAE,WAAW;IACtB,8EAA8E;IAC9E,0EAA0E;IAC1E,8EAA8E;IAC9E,6EAA6E;IAC7E,+EAA+E;IAC/E,8BAA8B;IAC9B,gBAAgB,EAAE,GAAG,EAAE,CAAC,IAAI;IAC5B,4EAA4E;IAC5E,wEAAwE;IACxE,6EAA6E;IAC7E,oDAAoD;CACrD,CAAC"}
+{"version":3,"file":"codex_cli.js","sourceRoot":"","sources":["../../src/agents/codex_cli.ts"],"names":[],"mappings":"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"}

package/dist/agents/cursor.d.ts

@@ -18,4 +18,38 @@
  * difference is marked on each member below rather than left to a reader.
  */
 import type { TranscriptDialect } from "./types.js";
+/**
+ * The longest folder name Cursor writes verbatim.
+ *
+ * ⛔ **MEASURED (Open Question 3, VS, 2026-10-24), with `cursor-agent`, which
+ * creates the project folder even when it is not logged in.** A name up to 61
+ * characters is kept; a longer one becomes its first 53 characters, `-`, and 7
+ * hex characters (the hash varied with the input, so it is not a constant).
+ */
+export declare const CURSOR_NAME_LIMIT = 61;
+/**
+ * The folder name Cursor gives a workspace path — Open Question 3.
+ *
+ * ⛔ **THIS IS NOT CLAUDE CODE'S RULE, and the difference is the measurement.**
+ * Every RUN of non-alphanumerics, a literal `--` included, collapses to ONE `-`;
+ * leading and trailing separators are dropped (so `/tmp/q/trail.` is `…-trail`
+ * and there is no leading `-`); case is kept. An emoji and `é'` each gave a single
+ * dash where Claude Code gives two.
+ *
+ * ⚠ **Which makes Cursor's names collide far more:** `a-b`, `a.b`, `a--b` and
+ * `a.b.` are all one folder. The scan's walk encodes every directory entry with
+ * THIS function and matches on the result, so the collapsing applies to every
+ * candidate rather than being assumed away.
+ */
+export declare function encodeProjectPath(path: string): string;
+/**
+ * Is this folder name one Cursor cut and hashed? See `CURSOR_NAME_LIMIT`.
+ *
+ * ⚠ **A hashed name is always exactly 61 long, and so is a verbatim name that
+ * happens to be 61 long** — length alone cannot tell them apart. The test is the
+ * hash's shape too (`-` and 7 hex). A verbatim 61-character name that ends the
+ * same way is read as hashed, which is the safe error: it is skipped and
+ * counted, never matched to a path it might not be.
+ */
+export declare function isHashedProjectName(name: string): boolean;
 export declare const CURSOR: TranscriptDialect;

package/dist/agents/cursor.js

@@ -17,7 +17,9 @@
  * ⚠ **What is DATA here and what is MEASURED is not the same set**, and the
  * difference is marked on each member below rather than left to a reader.
  */
+import { join } from "node:path";
 import { cursorHooksPath, cursorTranscriptRoot, isCursorTranscript } from "../paths.js";
+import { readEntries, sessionFile, subdirectories } from "./session_listing.js";
 /**
  * ⭐ **MEASURED. `D5`'s SECOND HALF IS ANSWERED (`TODOS[130]`), AND THE ANSWER IS
  * THAT CURSOR IMPOSES NO NUMBER OF ITS OWN.**
@@ -79,6 +81,97 @@ import { cursorHooksPath, cursorTranscriptRoot, isCursorTranscript } from "../pa
  */
 const CURSOR_REGISTERED_MS = 3_000;
 const CURSOR_CLIENT_MS = 2_200;
+/**
+ * The longest folder name Cursor writes verbatim.
+ *
+ * ⛔ **MEASURED (Open Question 3, VS, 2026-10-24), with `cursor-agent`, which
+ * creates the project folder even when it is not logged in.** A name up to 61
+ * characters is kept; a longer one becomes its first 53 characters, `-`, and 7
+ * hex characters (the hash varied with the input, so it is not a constant).
+ */
+export const CURSOR_NAME_LIMIT = 61;
+/**
+ * The folder name Cursor gives a workspace path — Open Question 3.
+ *
+ * ⛔ **THIS IS NOT CLAUDE CODE'S RULE, and the difference is the measurement.**
+ * Every RUN of non-alphanumerics, a literal `--` included, collapses to ONE `-`;
+ * leading and trailing separators are dropped (so `/tmp/q/trail.` is `…-trail`
+ * and there is no leading `-`); case is kept. An emoji and `é'` each gave a single
+ * dash where Claude Code gives two.
+ *
+ * ⚠ **Which makes Cursor's names collide far more:** `a-b`, `a.b`, `a--b` and
+ * `a.b.` are all one folder. The scan's walk encodes every directory entry with
+ * THIS function and matches on the result, so the collapsing applies to every
+ * candidate rather than being assumed away.
+ */
+export function encodeProjectPath(path) {
+    return path.replace(/[^A-Za-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+/**
+ * Is this folder name one Cursor cut and hashed? See `CURSOR_NAME_LIMIT`.
+ *
+ * ⚠ **A hashed name is always exactly 61 long, and so is a verbatim name that
+ * happens to be 61 long** — length alone cannot tell them apart. The test is the
+ * hash's shape too (`-` and 7 hex). A verbatim 61-character name that ends the
+ * same way is read as hashed, which is the safe error: it is skipped and
+ * counted, never matched to a path it might not be.
+ */
+export function isHashedProjectName(name) {
+    return name.length === CURSOR_NAME_LIMIT && /-[0-9a-f]{7}$/.test(name);
+}
+/**
+ * The folder Cursor uses for a window with no workspace open. It is not a path,
+ * so it can never resolve to one and is not worth a "folder no longer exists"
+ * count. Seen by NAME on the author's machine; nothing in it was read.
+ */
+const CURSOR_NO_WORKSPACE = "empty-window";
+/**
+ * Cursor's sessions, by folder — `D11 · A`, `scan`.
+ *
+ * `<root>/<encoded workspace>/agent-transcripts/<cid>/<cid>.jsonl`. Only the
+ * conversation's own file counts: `<cid>/subagents/…` is delegated work that
+ * belongs to the parent (`delegatedTranscripts: "announce"`). A flat
+ * `agent-transcripts/<cid>.jsonl` is accepted too, because `isCursorTranscript`
+ * admits any `.jsonl` at that depth and a count that disagreed with the gate
+ * would be a count of nothing.
+ *
+ * ⛔ Names and times only; see `claudeSessionSource` for the rule and its reason.
+ */
+function cursorSessionSource(home) {
+    const root = cursorTranscriptRoot(home);
+    const folders = [];
+    try {
+        for (const folder of subdirectories(root)) {
+            if (folder.name === CURSOR_NO_WORKSPACE)
+                continue;
+            const transcripts = join(folder.path, "agent-transcripts");
+            const sessions = [];
+            for (const entry of readEntries(transcripts) ?? []) {
+                const file = entry.isDirectory()
+                    ? join(transcripts, entry.name, `${entry.name}.jsonl`)
+                    : entry.name.endsWith(".jsonl")
+                        ? join(transcripts, entry.name)
+                        : null;
+                const session = file === null ? null : sessionFile(file);
+                if (session !== null)
+                    sessions.push(session);
+            }
+            if (sessions.length > 0)
+                folders.push({ name: folder.name, sessions });
+        }
+    }
+    catch {
+        return { kind: "unreadable", reason: "unreadable" };
+    }
+    // Cursor keeps no record of the folders it has run in, so there is no second signal.
+    return {
+        kind: "folders",
+        folders,
+        encode: encodeProjectPath,
+        isHashed: isHashedProjectName,
+        recorded: [],
+    };
+}
 export const CURSOR = {
     id: "cursor",
     transport: "ndjson",
@@ -103,7 +196,22 @@ export const CURSOR = {
     // ⛔ Against the client's `SessionEnd`, `sessionEnd` matched NOTHING — not an
     // error, a `false` — so a Cursor session took no settle on its final turn and
     // lost it permanently. That is the whole of the bug.
-    eventNames: { Stop: "stop", PreCompact: "preCompact", SessionEnd: "sessionEnd" },
+    //
+    // ⛔ **`sessionStart` is STATIC, NOT OBSERVED** (Open Question 1, 2026-10-24).
+    // `cursor-agent` was not logged in, so no session ran; the spelling and the
+    // payload (`conversation_id`, `generation_id`, `model`, `is_background_agent`,
+    // `composer_mode`) come from the CLI bundle 2026.08.11-e8db854, which runs it
+    // for a NEW chat before the first turn. It reads `env` and `additional_context`
+    // from the output — and `additional_context` goes into the agent's context and
+    // is NOT shown to the user. There is no user-visible field, so this client
+    // never uses it to carry a notice: Cursor users learn the state from `status`,
+    // and the first-`Stop` install is kept as the fallback for exactly this reason.
+    eventNames: {
+        Stop: "stop",
+        PreCompact: "preCompact",
+        SessionEnd: "sessionEnd",
+        SessionStart: "sessionStart",
+    },
     // ⛔ `~/.cursor/hooks.json`, and the `cursor` SHAPE — the two are a pair.
     // Read out of the shipped bundle's validator: a top-level numeric `version`
     // is REQUIRED, entries are a FLAT array of hook scripts each needing a
@@ -125,6 +233,11 @@ export const CURSOR = {
             registeredTimeoutMs: CURSOR_REGISTERED_MS,
             clientBudgetMs: CURSOR_CLIENT_MS,
         },
+        // gstack-shortcut(dec-e650afbf): `Stop`'s clocks, no fast path (eng review D7 · B).
+        SessionStart: {
+            registeredTimeoutMs: CURSOR_REGISTERED_MS, // gstack-shortcut(dec-e650afbf)
+            clientBudgetMs: CURSOR_CLIENT_MS, // gstack-shortcut(dec-e650afbf)
+        },
     },
     // ⛔ DECLARED EXPLICITLY, and it is load-bearing now in a way it was not
     // before (D177 §2, §9). `subagentsDir()` would compute
@@ -142,6 +255,7 @@ export const CURSOR = {
     // measurement, not as a fact about the agent. Measuring it is a change to this
     // line and nothing else.
     sessionIdFromEnv: () => null,
+    sessionSource: (home) => cursorSessionSource(home),
     // ⛔ NO `locateCurrentTranscript`, and the omission is the decision — the same
     // one Codex made. Finding the conversation for THIS project would mean munging
     // a workspace path this client is never told, or reading a `cwd` out of the

package/dist/agents/cursor.js.map

@@ -1 +1 @@
-{"version":3,"file":"cursor.js","sourceRoot":"","sources":["../../src/agents/cursor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGxF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,MAAM,oBAAoB,GAAG,KAAK,CAAC;AACnC,MAAM,gBAAgB,GAAG,KAAK,CAAC;AAE/B,MAAM,CAAC,MAAM,MAAM,GAAsB;IACvC,EAAE,EAAE,QAAQ;IACZ,SAAS,EAAE,QAAQ;IACnB,8EAA8E;IAC9E,2EAA2E;IAC3E,6EAA6E;IAC7E,uDAAuD;IACvD,cAAc,EAAE,oBAAoB;IACpC,wEAAwE;IACxE,uEAAuE;IACvE,UAAU,EAAE,kBAAkB;IAC9B,8EAA8E;IAC9E,6EAA6E;IAC7E,4EAA4E;IAC5E,iEAAiE;IACjE,+EAA+E;IAC/E,mEAAmE;IACnE,EAAE;IACF,8EAA8E;IAC9E,4EAA4E;IAC5E,EAAE;IACF,6EAA6E;IAC7E,8EAA8E;IAC9E,qDAAqD;IACrD,UAAU,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE;IAChF,yEAAyE;IACzE,4EAA4E;IAC5E,uEAAuE;IACvE,6EAA6E;IAC7E,2EAA2E;IAC3E,uDAAuD;IACvD,yEAAyE;IACzE,UAAU,EAAE,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE;IACtE,MAAM,EAAE;QACN,IAAI,EAAE;YACJ,mBAAmB,EAAE,oBAAoB;YACzC,cAAc,EAAE,gBAAgB;SACjC;QACD,UAAU,EAAE;YACV,mBAAmB,EAAE,oBAAoB;YACzC,cAAc,EAAE,gBAAgB;SACjC;QACD,UAAU,EAAE;YACV,mBAAmB,EAAE,oBAAoB;YACzC,cAAc,EAAE,gBAAgB;SACjC;KACF;IACD,wEAAwE;IACxE,uDAAuD;IACvD,+EAA+E;IAC/E,+EAA+E;IAC/E,8EAA8E;IAC9E,8EAA8E;IAC9E,+DAA+D;IAC/D,oBAAoB,EAAE,UAAU;IAChC,SAAS,EAAE,QAAQ;IACnB,+EAA+E;IAC/E,6EAA6E;IAC7E,6EAA6E;IAC7E,6EAA6E;IAC7E,+EAA+E;IAC/E,yBAAyB;IACzB,gBAAgB,EAAE,GAAG,EAAE,CAAC,IAAI;IAC5B,8EAA8E;IAC9E,+EAA+E;IAC/E,4EAA4E;IAC5E,6EAA6E;IAC7E,0CAA0C;CAC3C,CAAC"}
+{"version":3,"file":"cursor.js","sourceRoot":"","sources":["../../src/agents/cursor.ts"],"names":[],"mappings":"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"}

package/dist/agents/session_listing.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Listing a folder-keyed agent's sessions — `D11 · A`, `scan`.
+ *
+ * The two folder-keyed dialects (Claude Code, Cursor) differ in how a path is
+ * encoded and where a session sits under the folder, and agree on everything
+ * this file does: read directory ENTRIES, `lstat` a candidate for its time, and
+ * never open it.
+ *
+ * ⛔ **`lstat`, REGULAR FILES ONLY.** A symlink named `x.jsonl` is not a session
+ * (Cursor's gate resolves for exactly that reason), and a FIFO or socket under a
+ * root this client does not own is a thing a later `readFileSync` hangs on or
+ * throws on. A listing that only ever `lstat`s cannot be made to block, which is
+ * the property `scan` needs from the one command that walks the whole root.
+ */
+import { type Dirent } from "node:fs";
+import type { SourceSession } from "./types.js";
+/**
+ * The entries of a directory, `null` when it is simply not there, and a THROW
+ * for anything else (permissions, I/O) — the caller turns a throw into the
+ * agent's `unreadable` answer, so an absent store and a broken one stay apart.
+ */
+export declare function readEntries(dir: string): Dirent[] | null;
+/** One regular file's times, or null for anything that is not one. Never opens it. */
+export declare function sessionFile(path: string): SourceSession | null;
+/** `<dir>/<name>` for each entry that is a real directory (a symlink is not one). */
+export declare function subdirectories(dir: string): {
+    name: string;
+    path: string;
+}[];

package/dist/agents/session_listing.js

@@ -0,0 +1,49 @@
+/**
+ * Listing a folder-keyed agent's sessions — `D11 · A`, `scan`.
+ *
+ * The two folder-keyed dialects (Claude Code, Cursor) differ in how a path is
+ * encoded and where a session sits under the folder, and agree on everything
+ * this file does: read directory ENTRIES, `lstat` a candidate for its time, and
+ * never open it.
+ *
+ * ⛔ **`lstat`, REGULAR FILES ONLY.** A symlink named `x.jsonl` is not a session
+ * (Cursor's gate resolves for exactly that reason), and a FIFO or socket under a
+ * root this client does not own is a thing a later `readFileSync` hangs on or
+ * throws on. A listing that only ever `lstat`s cannot be made to block, which is
+ * the property `scan` needs from the one command that walks the whole root.
+ */
+import { lstatSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * The entries of a directory, `null` when it is simply not there, and a THROW
+ * for anything else (permissions, I/O) — the caller turns a throw into the
+ * agent's `unreadable` answer, so an absent store and a broken one stay apart.
+ */
+export function readEntries(dir) {
+    try {
+        return readdirSync(dir, { withFileTypes: true });
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return null;
+        throw err;
+    }
+}
+/** One regular file's times, or null for anything that is not one. Never opens it. */
+export function sessionFile(path) {
+    try {
+        const stat = lstatSync(path);
+        return stat.isFile() ? { path, mtimeMs: stat.mtimeMs } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** `<dir>/<name>` for each entry that is a real directory (a symlink is not one). */
+export function subdirectories(dir) {
+    return (readEntries(dir) ?? [])
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => ({ name: entry.name, path: join(dir, entry.name) }));
+}
+//# sourceMappingURL=session_listing.js.map

package/dist/agents/session_listing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session_listing.js","sourceRoot":"","sources":["../../src/agents/session_listing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,SAAS,EAAE,WAAW,EAAe,MAAM,SAAS,CAAC;AAC9D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAIjC;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,IAAI,CAAC;QACH,OAAO,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IACnD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;QACjD,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QACzD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;QAC7B,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAChE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;SAC5B,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;SACtC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;AACzE,CAAC"}