@vibe-commit/capture 0.6.1 → 0.8.0

package/dist/hooks/post_rewrite.js.map

@@ -1 +1 @@
-{"version":3,"file":"post_rewrite.js","sourceRoot":"","sources":["../../src/hooks/post_rewrite.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"post_rewrite.js","sourceRoot":"","sources":["../../src/hooks/post_rewrite.ts"],"names":[],"mappings":"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"}

package/dist/hooks/session_grants.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `SessionStart`'s one bounded read of the account's grants (slice 2, `CR-259`, S4; exception 2, VT's conditions).
+ *
+ * ```
+ *   GET <ingest origin>/ingest/v1/grants      200 { "schema": 1, "epoch", "owners", "repos", "excluded" }
+ * ```
+ *
+ * This is the ONLY place a hook reads a successful response body. It is a separate request from any upload and it never goes through
+ * `send`, so an ingest reply's 2xx body is still not read on the hook path (`post.ts`).
+ *
+ * ## When it runs — all four, or not at all
+ *
+ *   1. the machine's account state is **stale**: a credential-lane answer carried an `X-Grant-Epoch` that is not the epoch last
+ *      recorded (`noteGrantEpoch`, called from `deliver`). A machine that has seen the same epoch every turn never asks;
+ *   2. the last GET was **more than an hour ago** (`last_get_at`). It is written BEFORE the request, so a server that hangs or a
+ *      hook that is killed mid-request costs the next hour of sessions nothing;
+ *   3. there is a **usable credential and ingest address**;
+ *   4. the hook has **budget to spare**: the GET is bounded at 1,000 ms and by what is left of the hook's own wall clock.
+ *
+ * ## What it can and cannot do
+ *
+ *   - It reads through `readCappedJson` at the **hook path's 64 KiB** (a CLI verb reads 1 MiB; a hook does not). A stalled, cut-off,
+ *     oversize or off-contract body is "unavailable": **the state stays stale**, nothing throws, and nothing waits past the bound.
+ *   - It writes `grants-account.json` — `account`, `stale: false`, `last_get_at` — whole and atomically, and NEVER `grants.json`.
+ *     `refused` is left as it was: a GET is not a sync, only a sync (or this machine's own next 200) says a refusal is over.
+ *   - It never syncs: no POST, no queue, no `pending`. Whatever the machine has not delivered stays for the next verb.
+ *   - What it learned admits nothing. `isCaptureAllowed` never reads `account` as a grant.
+ *
+ * It returns how many of the account's owner grants and repository grants this machine has not named, so the caller can say state 10.
+ * `null` means nothing to say.
+ */
+import type { IngestCredential } from "../credential.js";
+/** The most one SessionStart GET waits: exception 2's bound, inside the hook's existing budget. */
+export declare const SESSION_GRANTS_GET_MS = 1000;
+/** At most one GET an hour per machine. */
+export declare const SESSION_GRANTS_MIN_INTERVAL_MS: number;
+export interface SessionGrantsDeps {
+    readonly env: NodeJS.ProcessEnv;
+    readonly home: string;
+    readonly credential: IngestCredential;
+    /** Injected so a cell can stub the one request. */
+    readonly fetch?: typeof fetch;
+    readonly now?: () => Date;
+    /** What is left of the hook's own budget, in ms. Absent means the GET's own bound is all there is. */
+    readonly budgetLeftMs?: () => number;
+}
+export interface GrantsNoticeFacts {
+    /** The account's epoch as the GET read it: the key of the once-per-epoch notice. */
+    readonly epoch: number;
+    /** How many of the account's OWNER grants this machine has not named. */
+    readonly owners: number;
+    /** How many of the account's REPOSITORY grants this machine has not named (not under a named owner, not turned off). Owners plus repos is at least 1. */
+    readonly repos: number;
+}
+/**
+ * Do the one bounded GET if it is due, record what it said, and report the unnamed count if there is one to report.
+ * **NEVER THROWS.**
+ */
+export declare function refreshAccountGrants(deps: SessionGrantsDeps): Promise<GrantsNoticeFacts | null>;

package/dist/hooks/session_grants.js

@@ -0,0 +1,91 @@
+/**
+ * `SessionStart`'s one bounded read of the account's grants (slice 2, `CR-259`, S4; exception 2, VT's conditions).
+ *
+ * ```
+ *   GET <ingest origin>/ingest/v1/grants      200 { "schema": 1, "epoch", "owners", "repos", "excluded" }
+ * ```
+ *
+ * This is the ONLY place a hook reads a successful response body. It is a separate request from any upload and it never goes through
+ * `send`, so an ingest reply's 2xx body is still not read on the hook path (`post.ts`).
+ *
+ * ## When it runs — all four, or not at all
+ *
+ *   1. the machine's account state is **stale**: a credential-lane answer carried an `X-Grant-Epoch` that is not the epoch last
+ *      recorded (`noteGrantEpoch`, called from `deliver`). A machine that has seen the same epoch every turn never asks;
+ *   2. the last GET was **more than an hour ago** (`last_get_at`). It is written BEFORE the request, so a server that hangs or a
+ *      hook that is killed mid-request costs the next hour of sessions nothing;
+ *   3. there is a **usable credential and ingest address**;
+ *   4. the hook has **budget to spare**: the GET is bounded at 1,000 ms and by what is left of the hook's own wall clock.
+ *
+ * ## What it can and cannot do
+ *
+ *   - It reads through `readCappedJson` at the **hook path's 64 KiB** (a CLI verb reads 1 MiB; a hook does not). A stalled, cut-off,
+ *     oversize or off-contract body is "unavailable": **the state stays stale**, nothing throws, and nothing waits past the bound.
+ *   - It writes `grants-account.json` — `account`, `stale: false`, `last_get_at` — whole and atomically, and NEVER `grants.json`.
+ *     `refused` is left as it was: a GET is not a sync, only a sync (or this machine's own next 200) says a refusal is over.
+ *   - It never syncs: no POST, no queue, no `pending`. Whatever the machine has not delivered stays for the next verb.
+ *   - What it learned admits nothing. `isCaptureAllowed` never reads `account` as a grant.
+ *
+ * It returns how many of the account's owner grants and repository grants this machine has not named, so the caller can say state 10.
+ * `null` means nothing to say.
+ */
+import { accountNotHere } from "../account_not_here.js";
+import { readGrants, readAccountState, writeAccountState, EMPTY_GRANTS } from "../consent.js";
+import { fetchAccountGrants } from "../grants_sync.js";
+import { readPerClone } from "../machine_state.js";
+import { ingestUrl } from "../post.js";
+/** The most one SessionStart GET waits: exception 2's bound, inside the hook's existing budget. */
+export const SESSION_GRANTS_GET_MS = 1_000;
+/** At most one GET an hour per machine. */
+export const SESSION_GRANTS_MIN_INTERVAL_MS = 60 * 60 * 1000;
+/** Kept back from the hook's wall clock for everything after the request (the notice, the write, the exit). */
+const RESERVE_MS = 300;
+/** Under this the request is not worth starting: the hook just leaves the state stale. */
+const MIN_TIMEOUT_MS = 100;
+/**
+ * Do the one bounded GET if it is due, record what it said, and report the unnamed count if there is one to report.
+ * **NEVER THROWS.**
+ */
+export async function refreshAccountGrants(deps) {
+    try {
+        const now = (deps.now ?? (() => new Date()))();
+        const state = readAccountState(deps.home);
+        if (!state.stale)
+            return null;
+        if (state.last_get_at !== null) {
+            const last = Date.parse(state.last_get_at);
+            if (Number.isFinite(last) && now.getTime() - last < SESSION_GRANTS_MIN_INTERVAL_MS && now.getTime() >= last)
+                return null;
+        }
+        const url = ingestUrl(deps.env);
+        if (url === null)
+            return null;
+        const left = deps.budgetLeftMs?.() ?? Number.POSITIVE_INFINITY;
+        const timeoutMs = Math.min(SESSION_GRANTS_GET_MS, left - RESERVE_MS);
+        if (!(timeoutMs >= MIN_TIMEOUT_MS))
+            return null;
+        // Before the request, not after it: a hang must not be paid for again by every session of the next hour.
+        writeAccountState(deps.home, { ...state, last_get_at: now.toISOString() });
+        const read = await fetchAccountGrants(url, deps.credential, { fetch: deps.fetch ?? fetch, timeoutMs });
+        if (read.kind !== "ok")
+            return null;
+        const stamp = now.toISOString();
+        const account = { owners: read.owners, repos: read.repos, excluded: read.excluded, epoch: read.epoch, synced_at: stamp };
+        // Re-read: another hook or a verb may have written the file during the request, and only this hook's own fields are ours to set.
+        writeAccountState(deps.home, { ...readAccountState(deps.home), account, stale: false, last_get_at: stamp });
+        const grants = readGrants(deps.home);
+        if (grants.kind === "unreadable")
+            return null;
+        // A repo this machine holds only a per-clone consent for is on here: count it as named (the same resolution `status` uses).
+        const perClone = readPerClone(deps.home).flatMap((c) => (c.slug === null ? [] : [c.slug]));
+        const notHere = accountNotHere(grants.kind === "ok" ? grants.grants : EMPTY_GRANTS, account, perClone);
+        // `notHere` names an owner as `owner/` and a repo as its slug (`account_not_here.ts`): the trailing slash is the split.
+        const owners = notHere.filter((name) => name.endsWith("/")).length;
+        const repos = notHere.length - owners;
+        return owners + repos === 0 ? null : { epoch: read.epoch, owners, repos };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=session_grants.js.map

package/dist/hooks/session_grants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session_grants.js","sourceRoot":"","sources":["../../src/hooks/session_grants.ts"],"names":[],"mappings":"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"}

package/dist/hooks/session_start.d.ts

@@ -0,0 +1,114 @@
+/**
+ * `SessionStart` — the event that never uploads (0.7.0, eng review D3 · A, D4 · A, A4).
+ *
+ * It does three things in a clone that is already captured, and one more that asks nothing of the clone:
+ *
+ *   1. installs the clone's two git hooks, once, and ONLY when that is a plain write;
+ *   2. says so, once, as the hook's one `systemMessage` (style guide §10.1 states 6-8);
+ *   3. says the other things a session start can know without sending anything: the machine has no
+ *      credential (state 1), the credential ends soon (state 5), `grants.json` is unreadable (state 9).
+ *   4. (slice 2) when the account state is stale and an hour has passed, makes ONE bounded `GET` of the account's grants
+ *      (`session_grants.ts`) and, if the account grants repositories this machine has not named, says so once per account
+ *      epoch (state 10). It names no repo and sends nothing about the clone: the request is the machine's credential and a path.
+ *
+ * ⛔ **IT NEVER READS `transcript_path` AND NEVER UPLOADS.** `entry.ts` resolves the canonical event first and
+ * branches here BEFORE the consent gate and before the transcript confinement check, so this module is not a
+ * path a transcript can reach. There is no `fetch` call here, and the one request anything it imports can make is
+ * `session_grants.ts`'s GET, which runs only on a stale account state, at most hourly (a machine that has never been told a
+ * different epoch makes none); the cells in `test/session-start.test.ts` assert 0 requests and an unopened transcript for
+ * each of the three dialects.
+ *
+ * ⚠ **The consent gate is still applied — HERE**, because installing git hooks into a repo is a write into
+ * the user's clone and "absence means no" covers writes as much as reads. An ungranted or excluded clone gets
+ * silence and no file.
+ *
+ * ## The budget
+ *
+ * SessionStart runs on each agent's STOP clocks, with no fast path of its own (eng review D7 · B, Alexander's
+ * choice over a 1.5 s cap). That is a logged shortcut — gstack-shortcut(dec-e650afbf) — and the constants carry
+ * the marker in `src/agents/*.ts`. The ceiling: a hung git call here can hold a session's start up by as long
+ * as the agent's REGISTERED timeout. `startSpawnBudget` (armed in `runHook`) still bounds every spawn.
+ */
+import { credentialFingerprint } from "../post.js";
+import { type ProjectKeys } from "../project.js";
+import type { NoticeState } from "../system_message.js";
+/** The slice of `hookBody` this module needs, injected so it carries no import cycle with `entry.ts`. */
+export interface SessionStartContext {
+    /**
+     * Which agent registered this hook (`--agent=`). Cursor's `sessionStart` has NO field a user sees, so for it the
+     * handler installs and returns null: it renders nothing and claims nothing (see `sessionStartPayload`).
+     */
+    readonly agentId: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly home: string;
+    /** `process.argv[1]` — the path the git hooks will invoke, and the channel test's input. */
+    readonly selfPath: string;
+    readonly cwd: string;
+    /**
+     * Render a state into the hook's stdout payload, or null when it is already claimed, unrenderable or
+     * unclaimable. `cloneKey` is passed only by states 6-8. This is `hookBody`'s own `notice` closure.
+     */
+    readonly notice: (state: NoticeState, repoKey?: string | null, rejected?: Parameters<typeof credentialFingerprint>[0], endsAt?: string, cloneKey?: string, 
+    /** State 10 only: the account epoch the GET read and how many of its owner and repository grants this machine has not named. */
+    account?: {
+        readonly epoch: number;
+        readonly owners: number;
+        readonly repos: number;
+    }) => string | null;
+    /** What is left of the hook's wall clock, in ms: the one GET is bounded by it as well as by its own 1,000 ms. Absent: no outer bound. */
+    readonly budgetLeftMs?: () => number;
+    /** Injected so a cell can stub the one request and the clock. */
+    readonly fetch?: typeof fetch;
+    readonly now?: () => Date;
+}
+/**
+ * This clone's identity for the once-per-clone markers: a random nonce in `<common-dir>/capture-clone-id`,
+ * written once, on the first install in a granted clone (eng review D4 · A, VQ's ruling on PR 4's P1).
+ *
+ * ⛔ **WHY A NONCE AND NOT SOMETHING DERIVED FROM GIT.** The first version keyed on the common dir plus the oldest
+ * HEAD reflog entry, and that key MOVES: a linked worktree has its own HEAD reflog, `git gc` expires old entries
+ * (reachable ones after 90 days, unreachable after 30), and a reflog past about 18k entries overflows the spawn's
+ * 1 MiB buffer. Each gave a new key, so a deleted hook was written back — the one thing D4 forbids. A file in the
+ * common dir has none of those failure modes: worktrees share it, `gc` leaves it alone, and a fresh clone at the
+ * same path has no `.git` of the old one, so it has no id and installs again — D4's three properties, kept.
+ *
+ * Returns null when the id can be neither read nor made (a read-only `.git`): no key means no install, which is the
+ * safe direction. `wx` makes the first writer win; a racing second session reads the winner's value.
+ */
+export declare function cloneId(commonDir: string): string | null;
+/**
+ * Install this clone's git hooks if, and only if, it is the first time and the write is a plain one.
+ *
+ * Returns the notice STATE to speak (6, 7 or 8), or null for "nothing to say" — which includes a clone that
+ * already had an install record (D4: a hook the user deleted stays deleted; `vibecommit connect` puts it back
+ * with the user watching), one whose slots were already ours, and a write that failed.
+ *
+ * ⭐ **STATE 6 IS OWED UNTIL IT HAS BEEN SAID.** The install record says the hooks were written; whether the
+ * notice was SAID is its own once-per-clone claim. So a clone installed in a session where state 1 or 5 outranked
+ * 6, or installed by Cursor's `sessionStart` (which says nothing), still owes state 6, and the next hook that can
+ * speak says it — until `renderNotice` has claimed it, after which it is never owed again.
+ *
+ * What is recorded, and what is not: an install, and a clone whose slots were already ours, write the record. A
+ * `core.hooksPath` redirect and a foreign hook write no hook and no install record — the clone id IS written (it
+ * is a consented repo, and the markers for states 7 and 8 are keyed by it), so those states stay once per clone —
+ * and a later session re-probes, cheaply and silently. A `failed` write is retried next session for the same
+ * reason.
+ */
+export declare function installOnce(ctx: Pick<SessionStartContext, "env" | "home" | "selfPath">, keys: ProjectKeys): {
+    readonly state: NoticeState | null;
+    readonly cloneKey: string;
+};
+/**
+ * The `SessionStart` hook body. Returns the stdout payload or null; never throws past the caller's catch, and
+ * opens no transcript.
+ *
+ * Precedence — one hook speaks at most once: 9, then 10, then 1, then 5, then 7, 8, 6. (States 2 and 4 need a send, and
+ * 3 is `hookBody`'s own check ahead of the branch, so on a runtime below the Node floor 3 outranks 9: nothing
+ * else on such a runtime works either.) A state that is already claimed returns null and the next one speaks.
+ *
+ * State 10 needs a usable credential, so it cannot share a session with state 1; it outranks 5 and the three install states.
+ * It is the one notice that can speak from a clone THIS machine does not capture — the clone an account grant names is exactly
+ * such a clone — so it is gated on the clone having a remote (as state 9 is), not on `isCaptureAllowed`. What it sends is the
+ * machine's credential and no word about the clone.
+ */
+export declare function sessionStartPayload(ctx: SessionStartContext): Promise<string | null>;

package/dist/hooks/session_start.js

@@ -0,0 +1,243 @@
+/**
+ * `SessionStart` — the event that never uploads (0.7.0, eng review D3 · A, D4 · A, A4).
+ *
+ * It does three things in a clone that is already captured, and one more that asks nothing of the clone:
+ *
+ *   1. installs the clone's two git hooks, once, and ONLY when that is a plain write;
+ *   2. says so, once, as the hook's one `systemMessage` (style guide §10.1 states 6-8);
+ *   3. says the other things a session start can know without sending anything: the machine has no
+ *      credential (state 1), the credential ends soon (state 5), `grants.json` is unreadable (state 9).
+ *   4. (slice 2) when the account state is stale and an hour has passed, makes ONE bounded `GET` of the account's grants
+ *      (`session_grants.ts`) and, if the account grants repositories this machine has not named, says so once per account
+ *      epoch (state 10). It names no repo and sends nothing about the clone: the request is the machine's credential and a path.
+ *
+ * ⛔ **IT NEVER READS `transcript_path` AND NEVER UPLOADS.** `entry.ts` resolves the canonical event first and
+ * branches here BEFORE the consent gate and before the transcript confinement check, so this module is not a
+ * path a transcript can reach. There is no `fetch` call here, and the one request anything it imports can make is
+ * `session_grants.ts`'s GET, which runs only on a stale account state, at most hourly (a machine that has never been told a
+ * different epoch makes none); the cells in `test/session-start.test.ts` assert 0 requests and an unopened transcript for
+ * each of the three dialects.
+ *
+ * ⚠ **The consent gate is still applied — HERE**, because installing git hooks into a repo is a write into
+ * the user's clone and "absence means no" covers writes as much as reads. An ungranted or excluded clone gets
+ * silence and no file.
+ *
+ * ## The budget
+ *
+ * SessionStart runs on each agent's STOP clocks, with no fast path of its own (eng review D7 · B, Alexander's
+ * choice over a 1.5 s cap). That is a logged shortcut — gstack-shortcut(dec-e650afbf) — and the constants carry
+ * the marker in `src/agents/*.ts`. The ceiling: a hung git call here can hold a session's start up by as long
+ * as the agent's REGISTERED timeout. `startSpawnBudget` (armed in `runHook`) still bounds every spawn.
+ */
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { grantsUnreadable, isCaptureAllowed, isLocalSlug, readAccountState } from "../consent.js";
+import { endingSoon, metaFor } from "../credential_meta.js";
+import { loadCredential } from "../credential.js";
+import { onceRepoSlug } from "../git.js";
+import { refreshAccountGrants } from "./session_grants.js";
+import { installChannel, installCaptureHooks } from "../install.js";
+import { cloneMarkerPath } from "../paths.js";
+import { credentialFingerprint } from "../post.js";
+import { resolveProjectKeys } from "../project.js";
+/** The file in the git COMMON dir that names this clone. Shared by every linked worktree; `gc` never touches it. */
+// ⚠ Not `vibecommit-…`: `test/provenance.test.ts` reads every `vibecommit-<word>` token in src/ as a sibling repository
+// that must be declared, so a filename of that shape fails it. The name is a plain one for that reason alone.
+const CLONE_ID_FILE = "capture-clone-id";
+/**
+ * This clone's identity for the once-per-clone markers: a random nonce in `<common-dir>/capture-clone-id`,
+ * written once, on the first install in a granted clone (eng review D4 · A, VQ's ruling on PR 4's P1).
+ *
+ * ⛔ **WHY A NONCE AND NOT SOMETHING DERIVED FROM GIT.** The first version keyed on the common dir plus the oldest
+ * HEAD reflog entry, and that key MOVES: a linked worktree has its own HEAD reflog, `git gc` expires old entries
+ * (reachable ones after 90 days, unreachable after 30), and a reflog past about 18k entries overflows the spawn's
+ * 1 MiB buffer. Each gave a new key, so a deleted hook was written back — the one thing D4 forbids. A file in the
+ * common dir has none of those failure modes: worktrees share it, `gc` leaves it alone, and a fresh clone at the
+ * same path has no `.git` of the old one, so it has no id and installs again — D4's three properties, kept.
+ *
+ * Returns null when the id can be neither read nor made (a read-only `.git`): no key means no install, which is the
+ * safe direction. `wx` makes the first writer win; a racing second session reads the winner's value.
+ */
+export function cloneId(commonDir) {
+    const path = join(commonDir, CLONE_ID_FILE);
+    const read = () => {
+        try {
+            const text = readFileSync(path, "utf8").trim();
+            return /^[0-9a-f]{32}$/.test(text) ? text : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const existing = read();
+    if (existing !== null)
+        return existing;
+    try {
+        writeFileSync(path, `${randomBytes(16).toString("hex")}\n`, { flag: "wx", mode: 0o600 });
+    }
+    catch {
+        // Lost the race (EEXIST) or cannot write; either way the file, if there is one, is the answer.
+    }
+    return read();
+}
+/** The install record: `clone/<digest>/installed.json`, beside the notice markers. */
+function installRecordPath(home, key) {
+    return cloneMarkerPath(home, key, "installed");
+}
+/** What the install record says. `wrote` is whether THIS client put a hook there, which is what owes the clone state 6. */
+function readInstallRecord(home, key) {
+    try {
+        const parsed = JSON.parse(readFileSync(installRecordPath(home, key), "utf8"));
+        return { wrote: parsed.wrote === true };
+    }
+    catch {
+        return null;
+    }
+}
+/** Best effort; a record we cannot write means the next session tries again, which is the safe direction. */
+function writeInstallRecord(home, key, wrote) {
+    try {
+        const path = installRecordPath(home, key);
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        writeFileSync(path, `${JSON.stringify({ at: new Date().toISOString(), wrote })}\n`, { flag: "wx", mode: 0o600 });
+    }
+    catch {
+        // An existing record (`wx`) or an unwritable home: both leave the clone as it was.
+    }
+}
+/**
+ * Install this clone's git hooks if, and only if, it is the first time and the write is a plain one.
+ *
+ * Returns the notice STATE to speak (6, 7 or 8), or null for "nothing to say" — which includes a clone that
+ * already had an install record (D4: a hook the user deleted stays deleted; `vibecommit connect` puts it back
+ * with the user watching), one whose slots were already ours, and a write that failed.
+ *
+ * ⭐ **STATE 6 IS OWED UNTIL IT HAS BEEN SAID.** The install record says the hooks were written; whether the
+ * notice was SAID is its own once-per-clone claim. So a clone installed in a session where state 1 or 5 outranked
+ * 6, or installed by Cursor's `sessionStart` (which says nothing), still owes state 6, and the next hook that can
+ * speak says it — until `renderNotice` has claimed it, after which it is never owed again.
+ *
+ * What is recorded, and what is not: an install, and a clone whose slots were already ours, write the record. A
+ * `core.hooksPath` redirect and a foreign hook write no hook and no install record — the clone id IS written (it
+ * is a consented repo, and the markers for states 7 and 8 are keyed by it), so those states stay once per clone —
+ * and a later session re-probes, cheaply and silently. A `failed` write is retried next session for the same
+ * reason.
+ */
+export function installOnce(ctx, keys) {
+    // No binary path to point a git hook at, or the plugin channel — which installs no git hooks, by contract
+    // ("the plugin installs no git hooks" stays true; TODOS [173] (a2) is Alexander's call).
+    if (ctx.selfPath === "" || installChannel(ctx.env, ctx.selfPath).kind === "plugin") {
+        return { state: null, cloneKey: "" };
+    }
+    const key = cloneId(keys.consent);
+    if (key === null)
+        return { state: null, cloneKey: "" };
+    const record = readInstallRecord(ctx.home, key);
+    if (record !== null) {
+        const owed = record.wrote && !existsSync(cloneMarkerPath(ctx.home, key, "hooks_added"));
+        return { state: owed ? "hooks_added" : null, cloneKey: key };
+    }
+    const result = installCaptureHooks(keys.worktree, ctx.selfPath, { plainWriteOnly: true });
+    const kinds = [result.commit.kind, result.rewrite.kind];
+    if (kinds.includes("hooks-path"))
+        return { state: "hooks_path_set", cloneKey: key };
+    if (kinds.includes("foreign"))
+        return { state: "own_commit_hook", cloneKey: key };
+    if (kinds.includes("failed"))
+        return { state: null, cloneKey: key };
+    const wrote = (v) => v.kind === "installed" || v.kind === "chained";
+    const didWrite = wrote(result.commit) || wrote(result.rewrite);
+    writeInstallRecord(ctx.home, key, didWrite);
+    return { state: didWrite ? "hooks_added" : null, cloneKey: key };
+}
+/**
+ * The `SessionStart` hook body. Returns the stdout payload or null; never throws past the caller's catch, and
+ * opens no transcript.
+ *
+ * Precedence — one hook speaks at most once: 9, then 10, then 1, then 5, then 7, 8, 6. (States 2 and 4 need a send, and
+ * 3 is `hookBody`'s own check ahead of the branch, so on a runtime below the Node floor 3 outranks 9: nothing
+ * else on such a runtime works either.) A state that is already claimed returns null and the next one speaks.
+ *
+ * State 10 needs a usable credential, so it cannot share a session with state 1; it outranks 5 and the three install states.
+ * It is the one notice that can speak from a clone THIS machine does not capture — the clone an account grant names is exactly
+ * such a clone — so it is gated on the clone having a remote (as state 9 is), not on `isCaptureAllowed`. What it sends is the
+ * machine's credential and no word about the clone.
+ */
+export async function sessionStartPayload(ctx) {
+    const keys = resolveProjectKeys(ctx.cwd);
+    if (keys === null)
+        return null;
+    const slugOf = onceRepoSlug(keys.worktree);
+    // ⛔ CURSOR'S `sessionStart` HAS NO USER-VISIBLE FIELD (Open Question 1, static read), so it installs and says
+    // NOTHING: it renders no notice and, because `renderNotice` is what claims, it claims none. Rendering here would
+    // print a line nobody sees AND use up the clone's state 6 and the machine's once-a-day 9 and 5, leaving Claude
+    // Code and Codex quiet. State 6 stays owed (`installOnce`) for the next hook that can speak — Cursor's first
+    // `stop`. Ahead of the state-9 branch for the same reason. And it makes no GET: the answer would be a notice nobody sees,
+    // and the stale mark stays for a hook that can speak.
+    if (ctx.agentId === "cursor") {
+        if (isCaptureAllowed(ctx.home, keys, slugOf))
+            installOnce(ctx, keys);
+        return null;
+    }
+    // State 9 first. An unreadable `grants.json` denies every repo with a remote, so the hook can say so once a
+    // day per machine — but only from a clone it WOULD have captured, so a folder with no remote hears nothing.
+    if (grantsUnreadable(ctx.home) && !isLocalSlug(slugOf())) {
+        return ctx.notice("grants_unreadable");
+    }
+    const allowed = isCaptureAllowed(ctx.home, keys, slugOf);
+    // The side effect comes before any notice, so a higher-precedence notice never costs the install — and state 6
+    // stays OWED to a later session rather than lost (`installOnce`).
+    const installed = allowed ? installOnce(ctx, keys) : null;
+    // ⛔ A clone this machine does NOT capture may still be where an account grant is named, so it may make the one GET — under VT's five
+    // conditions (#89): (1) the request is the bare `GET /ingest/v1/grants` with only the credential, client-version and accept headers;
+    // (2) nothing is written into the clone (no clone id, no git config, no hook); (3) no transcript is opened or stat'ed (this module never
+    // names `transcript_path`); (4) the conditions are machine-wide — stale, at most hourly across ALL clones, `timeoutMs` ≤ 1,000, 64 KiB,
+    // a stalled or oversize answer stays stale; (5) THE SLUG RESOLVES LAZILY: the remote is looked up (a git spawn) only when the account
+    // state this machine already holds names at least one owner or repo AND is stale. A machine whose cached account is empty never spawns git
+    // for this, and a clone with no remote asks nothing.
+    if (!allowed) {
+        const cached = readAccountState(ctx.home);
+        if (!cached.stale || cached.account === null || (cached.account.owners.length === 0 && cached.account.repos.length === 0))
+            return null;
+        if (isLocalSlug(slugOf()))
+            return null;
+    }
+    const load = loadCredential({ env: ctx.env, home: ctx.home });
+    if (load.kind === "ok") {
+        // State 10. The GET is due only when the account state is stale and an hour has passed (`session_grants.ts`).
+        const found = await refreshAccountGrants({
+            env: ctx.env,
+            home: ctx.home,
+            credential: load.credential,
+            ...(ctx.fetch === undefined ? {} : { fetch: ctx.fetch }),
+            ...(ctx.now === undefined ? {} : { now: ctx.now }),
+            ...(ctx.budgetLeftMs === undefined ? {} : { budgetLeftMs: ctx.budgetLeftMs }),
+        });
+        if (found !== null) {
+            const unnamed = ctx.notice("account_grants_unnamed", null, undefined, undefined, undefined, found);
+            if (unnamed !== null)
+                return unnamed;
+        }
+    }
+    // Everything below is about a clone this machine captures. A clone it does not capture is silent, as it always was.
+    if (!allowed || installed === null)
+        return null;
+    if (load.kind !== "ok") {
+        const notConnected = ctx.notice("not_connected");
+        if (notConnected !== null)
+            return notConnected;
+    }
+    else {
+        const endsAt = endingSoon(metaFor(ctx.home, credentialFingerprint(load.credential)), Date.now());
+        if (endsAt !== null) {
+            const ending = ctx.notice("credential_ending", null, load.credential, endsAt);
+            if (ending !== null)
+                return ending;
+        }
+    }
+    if (installed.state === null)
+        return null;
+    return ctx.notice(installed.state, null, undefined, undefined, installed.cloneKey);
+}
+//# sourceMappingURL=session_start.js.map

package/dist/hooks/session_start.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session_start.js","sourceRoot":"","sources":["../../src/hooks/session_start.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { type InvocationMode } from "./exit.js";
-declare const VERBS: readonly ["auth", "connect", "status", "off", "why", "report", "finalize"];
+declare const VERBS: readonly ["auth", "connect", "scan", "backfill", "status", "off", "why", "report", "finalize"];
 export type Verb = (typeof VERBS)[number];
 export declare function isVerb(value: string): value is Verb;
 /**