@vibe-commit/capture 0.6.1 → 0.8.0

package/dist/consent.d.ts

@@ -30,11 +30,21 @@
  * `.consent`, and the parameter is named for it so a toplevel passed by habit
  * reads wrong at the call site.
  *
+ * ## ⛔ A SECOND KEY, AND ONE DOOR: `isCaptureAllowed` (0.7.0, D1 · B)
+ *
+ * A repo can now also be admitted by its SLUG (`owner/repo`) through
+ * `grants.json`, so any clone of it matches, not only the one that ran
+ * `connect`. Every gate asks `isCaptureAllowed`; `isProjectAllowed` is the
+ * common-dir half of it and nothing outside this file calls it
+ * (`test/consent-gates.test.ts` scans for exactly that). Two keys behind two
+ * doors is how `post_rewrite.ts` was missed once.
+ *
  * ⚠ **No migration for allow lists written under the old key**, and that is a
  * decision rather than an omission: pre-launch there are zero users and zero
  * rows (`project_pre_launch_no_data`), so there is nothing to migrate. See
  * `resolveProjectKeys`.
  */
+import type { ProjectKeys } from "./project.js";
 /** One consented project. `at` is informational; presence is the grant. */
 export interface ProjectGrant {
     readonly at: string;
@@ -52,6 +62,213 @@ export declare function isProjectAllowed(home: string, consentKey: string | null
 export declare function grantProject(home: string, consentKey: string, now: Date): void;
 /** Revoke consent for one project (`vibecommit off`). */
 export declare function revokeProject(home: string, consentKey: string): boolean;
+/**
+ * `grants.json`. ⛔ **Slugs, not paths**: `owner/repo` for GitHub, `host/owner/repo`
+ * for any other host (`git.ts`'s `parseRemoteSlug`), so every clone matches.
+ *
+ *  - `owners`   — "all repos under this owner, including ones cloned later". An owner is the
+ *                 slug minus its last segment: `alexvibecommit`, or `gitlab.example.com/team`.
+ *  - `repos`    — single repos granted one by one.
+ *  - `excluded` — `vibecommit off`. **Wins over every other basis**, a surviving common-dir entry included.
+ *  - `refused`  — 0.7.0's field for server refusals, kept so a 0.7.0 client can still read a 0.8.0 file. ⛔ Nothing writes it:
+ *                 slice 2's refusals are written by hooks, and hooks never write this file (see `grants-account.json` below).
+ *                 It is still honoured as a denial if something is in it.
+ *  - `pending`  — slice 2: grant writes this machine has not yet delivered to the account `{ op, kind, value, at }`. The next
+ *                 CLI verb that syncs sends and clears them (`grants_sync.ts`). Absent in a 0.7.0 file, which reads as none.
+ *
+ * ⛔ **THIS FILE IS CLI-ONLY.** `updateGrants` is an unlocked read-modify-write, so a hook that wrote here could race
+ * `vibecommit off` and restore the repo `off` had just turned off. What a hook has to remember lives in `grants-account.json`.
+ *
+ * `disclosed_at` is when the D65 disclosure was last answered yes for a grant; `null` until then.
+ */
+export interface Grants {
+    readonly disclosed_at: string | null;
+    readonly owners: readonly string[];
+    readonly repos: readonly string[];
+    readonly excluded: readonly string[];
+    readonly refused: readonly string[];
+    readonly pending: readonly PendingOp[];
+    /**
+     * ISO 8601, set ONCE, when this machine's first sync got a 200; `null` before. ⛔ **This is what makes a sync a "first sync"** (it
+     * uploads everything this machine already named), and it lives here and not in `grants-account.json` on purpose: that file is
+     * ignored when unreadable, and a deleted one must not make the next sync re-grant what was revoked elsewhere. CLI-only.
+     * Absent in a 0.7.0 file, which reads as `null`.
+     */
+    readonly synced_at: string | null;
+}
+/** One queued write to the account's grants — the shape the server's sync endpoint takes, plus when it was queued. */
+export interface PendingOp {
+    readonly op: "grant" | "revoke" | "exclude" | "include";
+    /** `exclude` and `include` are repo-only. The kind cannot be read off the value (`acme/api` and `gitlab.example.com/team` are both one slash). */
+    readonly kind: "owner" | "repo";
+    readonly value: string;
+    /** ISO 8601, when it was queued. */
+    readonly at: string;
+}
+export declare const EMPTY_GRANTS: Grants;
+/**
+ * ⛔ **THE ONE NORMALIZATION.** The whole host-qualified slug, lowercased, for every host — the identity the
+ * server already stores (`resolve_repository` sets `v_slug := lower(trim(...))`). Owners, repos, exclusions,
+ * every `grants.json` write and slice 2's server comparison all go through this, so two clones whose remotes
+ * differ only in case are one repo on both sides.
+ */
+export declare function normalizeSlug(slug: string): string;
+/** An owner as stored: normalized, and without the trailing `/` the picker displays (`alexvibecommit/`). */
+export declare function normalizeOwner(owner: string): string;
+/** `local:` slugs name a path, not a repo: no grant can match one, and their consent stays per clone. */
+export declare function isLocalSlug(slug: string): boolean;
+/** The owner part of a slug: everything before the last `/`. `""` when there is none. */
+export declare function ownerOfSlug(slug: string): string;
+/**
+ * What reading `grants.json` found. ⛔ **Three states, because two of them mean opposite things.**
+ *
+ *  - `missing`    — no file. Every machine upgrading from 0.6.x is here, and their common-dir consents
+ *                   must keep capturing.
+ *  - `unreadable` — a file is there and cannot be read or does not parse. It may hold exclusions we cannot
+ *                   see, so it DENIES every clone that has a slug (`isCaptureAllowed`). `status` says so
+ *                   loudly, since a hook cannot.
+ *  - `ok`         — parsed and normalized.
+ */
+export type GrantsRead = {
+    readonly kind: "missing";
+} | {
+    readonly kind: "unreadable";
+} | {
+    readonly kind: "ok";
+    readonly grants: Grants;
+};
+export declare function readGrants(home: string): GrantsRead;
+/** True when a `grants.json` is present and unusable — the state `status` reports and a SessionStart notice names. */
+export declare function grantsUnreadable(home: string): boolean;
+/**
+ * The account's grants as the last sync or GET returned them. ⛔ **It never admits anything** (R3-22): a repo the account
+ * grants is captured on this machine only once THIS machine names it, in `grants.json`. `excluded` here does DENY — a repo
+ * turned off from another machine or the dashboard stops here too.
+ */
+export interface AccountGrants {
+    readonly owners: readonly string[];
+    readonly repos: readonly string[];
+    readonly excluded: readonly string[];
+    /** The server's `epoch` for the user's grants when this was read. */
+    readonly epoch: number;
+    /** ISO 8601, when this machine got it. */
+    readonly synced_at: string;
+}
+/**
+ * `grants-account.json`.
+ *
+ *  - `account`      — the last synced account state, or `null` before the first sync.
+ *  - `refused`      — slugs the server refused with `repository_excluded` since the last sync. Denied here; a sync clears it.
+ *  - `stale`        — an `X-Grant-Epoch` differed from `account.epoch` (`noteGrantEpoch`); SessionStart's one GET reads it and clears it.
+ *  - `last_get_at`  — when SessionStart last did that GET, for its hourly limit.
+ *
+ * ⛔ **HOOKS WRITE THIS FILE AND NEVER `grants.json`.** It is written WHOLE and atomically (temp file + rename, 0600) and never
+ * through `updateGrants`. Two writers can still lose each other's update (the same unlocked read-modify-write), and that is
+ * safe by design: a lost `refused` slug means the server refuses it once more, and a lost `account` is read back by the next
+ * sync. Nothing in here can admit a repo, so nothing a race loses can capture one.
+ *
+ * ⛔ **An unreadable or corrupt file is IGNORED — it reads as empty, never as deny-all.** The opposite of `grants.json`, for the
+ * opposite reason: `grants.json` holds the user's own exclusions, which a deny-all protects; this file holds a cache and a
+ * server's refusals, and a machine that can't read it just asks the server again.
+ */
+export interface AccountState {
+    readonly account: AccountGrants | null;
+    readonly refused: readonly string[];
+    readonly stale: boolean;
+    readonly last_get_at: string | null;
+}
+export declare const EMPTY_ACCOUNT_STATE: AccountState;
+/** Read it. **NEVER THROWS, and any failure — missing, unreadable, not JSON, any field off-shape — is the empty state.** */
+export declare function readAccountState(home: string): AccountState;
+/** Write it whole: normalized, atomic, 0600. Throws on an I/O failure (the destination is then untouched). */
+export declare function writeAccountState(home: string, state: AccountState): void;
+/**
+ * A hook saw `repository_excluded` for this slug: remember it, so this machine stops reading that repo's transcripts until
+ * the next sync says otherwise. **NEVER THROWS** — it runs on the hook's path, where a failed write only means the server
+ * refuses the next upload too. `local:` slugs are never recorded (there is no repo identity to refuse).
+ */
+export declare function recordRefused(home: string, slug: string): void;
+/**
+ * A hook saw `X-Grant-Epoch` on a server answer (an ingest 2xx, or a grants refusal): if it is not the epoch this machine last
+ * recorded, mark the account state `stale`, which is what SessionStart's one bounded `GET` looks for (`session_grants.ts`).
+ * A machine with no recorded account state counts as epoch 0, as the server does when a user has no grants row.
+ *
+ * Writes `grants-account.json` and never `grants.json` (see `AccountState`), only when something changed — so a Stop hook that sees
+ * the same epoch every turn does no file write at all — and only ever sets `stale`; the GET (or a sync) clears it. **NEVER THROWS**:
+ * it runs on the hook's path, and a lost mark only means the next answer marks it again.
+ */
+export declare function noteGrantEpoch(home: string, epoch: number | null | undefined): void;
+/** A slug now, or a way to get it. The thunk is for the hooks: see `isCaptureAllowed`. */
+export type SlugSource = string | (() => string);
+/**
+ * Does the hold of `isCaptureAllowed` (step 3) apply to ANYTHING on this machine right now? True when the machine has synced
+ * (`synced_at` is set) and a queued `grant` op names an owner or a repo the last synced account state does not already grant
+ * (the same two conditions the per-slug hold uses: a synced machine, and the account not already admitting it). "0.8.0 truth
+ * fixes" R2-2: `connect`'s untold line says sessions wait only when something actually waits. Reads `grants.json` and
+ * `grants-account.json`; an unreadable `grants.json` holds nothing here (the gate denies for its own reason).
+ */
+export declare function holdsAny(home: string): boolean;
+/**
+ * ⛔ **THE ONE ADMISSION DECISION.** Every gate calls this; `entry.ts`, `post_commit.ts`, `post_rewrite.ts` (twice),
+ * `finalize.ts`, `status.ts` and `connect.ts` are the seven call sites. Absence is a NO and every error path denies.
+ *
+ * Precedence:
+ *  1. A MISSING `grants.json` is empty (0.6.x machines keep capturing on their common-dir consent). A PRESENT file
+ *     that cannot be read denies every clone that has a slug, whatever `projects.json` says.
+ *  2. A denied slug is denied, whatever the basis: `grants.json`'s `excluded` (and its legacy `refused`), the account file's
+ *     `refused`, or the account's own `excluded`.
+ *  3. On a machine that HAS SYNCED (`grants.synced_at` is set), a slug with a `grant` still PENDING (queued, not yet delivered to
+ *     the account) is held back when that grant is the slug's ONLY local basis, i.e. the clone has no common-dir consent: its
+ *     spans stay unsent with their offset unchanged, and go once a sync delivers the grant. It is not held either when the last
+ *     synced account state already grants the repo or its owner (the server admits it, so a queued grant that was refused must
+ *     not hold it for ever).
+ *     ⭐ **A MACHINE THAT HAS NEVER SYNCED HOLDS NOTHING** (VQ, "0.8.0 truth fixes" F1): the server refuses only a credential that
+ *     has synced (`grants_synced_at`), so before the first sync the hold protects nothing and would only defer uploads, for ever
+ *     against a server without the routes. Such a machine decides capture by its own choices, as under 0.7.0.
+ *     ⭐ **WHY A COMMON-DIR CONSENT LIFTS THE HOLD** (VQ's ruling): a remote repo gets a common-dir consent only from pre-0.8.0
+ *     flows (0.8.0's in-repo `connect` pre-ticks the picker, which writes GRANTS). The first sync uploads those consented slugs, so
+ *     either this credential has not synced, and the server never refuses anything for it, or the first sync already granted the
+ *     slug, and holding it would only delay bytes the server accepts.
+ *  4. Otherwise: admitted on the common-dir consent, or on a slug matched by `owners` or `repos`. ⛔ The account's own
+ *     `owners`/`repos` are NOT consulted — a repo only the account grants is not captured on this machine (per-machine naming).
+ *
+ * `local:` slugs never match a grant and keep common-dir consent alone. They are also not subject to
+ * exclusion or to an unreadable file: there is no repo identity to exclude.
+ *
+ * `grants-account.json` is read on every call and an unreadable one is the empty state, never a denial (`AccountState`).
+ *
+ * ⚠ **`slug` MAY BE A THUNK, and the hooks pass one.** Computing a slug can spawn `git remote get-url` and `ssh -G`,
+ * which is real time on a hook's budget; a machine with no `grants.json` (every 0.6.x machine) needs none of it, and
+ * neither does a clone with no consent and no grants to match. The slug is asked for only when the answer depends on it.
+ * Pass a memoized thunk (`git.ts`'s `onceRepoSlug`) so the caller's own later use shares the one spawn.
+ *
+ * `keys` is the `resolveProjectKeys` result the caller already holds, so the confinement roots it derives afterwards
+ * come from the very resolution this gate used (`D184 §3`).
+ */
+export declare function isCaptureAllowed(home: string, keys: ProjectKeys | null, slug: SlugSource): boolean;
+/** `updateGrants` refuses to rewrite a file it cannot read: overwriting would silently drop exclusions it never saw. */
+export declare class GrantsUnreadableError extends Error {
+    constructor();
+}
+/**
+ * Read-modify-write `grants.json`. 0700 on the directory, 0600 on the file, atomic (a hook reading while a verb saves
+ * sees the old file or the new, never half). Entries are normalized and de-duplicated on the way out.
+ *
+ * ⛔ **Throws `GrantsUnreadableError` rather than start from empty** when the file is present and unusable: a rewrite
+ * would turn "denies everything" into "admits on common-dir consent" without the user having decided anything.
+ *
+ * ⛔ **Keeps the top-level keys it does not know**, verbatim and uninterpreted, after the five it rebuilds (which always
+ * win). A newer version's file read by this one is written back whole: dropping a key it added would silently undo its
+ * state. No lock: same read-modify-write as `projects.json`, so two simultaneous verbs can lose one write.
+ */
+export declare function updateGrants(home: string, change: (current: Grants) => Grants): Grants;
+/** `vibecommit off`: the slug joins `excluded`. Returns true when that changed the file. */
+export declare function excludeSlug(home: string, slug: string): boolean;
+/**
+ * A yes at the disclosure re-includes a turned-off repo; nothing else does. `"none"` when the slug was not excluded
+ * (no file is written then), `"unreadable"` when `grants.json` cannot be read.
+ */
+export declare function clearExclusion(home: string, slug: string): "cleared" | "none" | "unreadable";
 /**
  * Interpret an answer to the consent prompt. **Only an explicit yes is a yes.**
  * Empty (the user pressed return) is NO, which is what makes `[y/N]` honest.

package/dist/consent.js

@@ -30,6 +30,15 @@
  * `.consent`, and the parameter is named for it so a toplevel passed by habit
  * reads wrong at the call site.
  *
+ * ## ⛔ A SECOND KEY, AND ONE DOOR: `isCaptureAllowed` (0.7.0, D1 · B)
+ *
+ * A repo can now also be admitted by its SLUG (`owner/repo`) through
+ * `grants.json`, so any clone of it matches, not only the one that ran
+ * `connect`. Every gate asks `isCaptureAllowed`; `isProjectAllowed` is the
+ * common-dir half of it and nothing outside this file calls it
+ * (`test/consent-gates.test.ts` scans for exactly that). Two keys behind two
+ * doors is how `post_rewrite.ts` was missed once.
+ *
  * ⚠ **No migration for allow lists written under the old key**, and that is a
  * decision rather than an omission: pre-launch there are zero users and zero
  * rows (`project_pre_launch_no_data`), so there is nothing to migrate. See
@@ -37,7 +46,8 @@
  */
 import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
-import { projectsPath, rootDir } from "./paths.js";
+import { writeFileAtomic } from "./atomic_write.js";
+import { grantsAccountPath, grantsPath, projectsPath, rootDir } from "./paths.js";
 /**
  * Read the allow list. **Every failure returns an empty list**, which means "no
  * project is consented" — a corrupt or unreadable file must not be able to grant
@@ -100,6 +110,395 @@ export function revokeProject(home, consentKey) {
     chmodSync(path, 0o600);
     return true;
 }
+export const EMPTY_GRANTS = {
+    disclosed_at: null,
+    owners: [],
+    repos: [],
+    excluded: [],
+    refused: [],
+    pending: [],
+    synced_at: null,
+};
+/**
+ * ⛔ **THE ONE NORMALIZATION.** The whole host-qualified slug, lowercased, for every host — the identity the
+ * server already stores (`resolve_repository` sets `v_slug := lower(trim(...))`). Owners, repos, exclusions,
+ * every `grants.json` write and slice 2's server comparison all go through this, so two clones whose remotes
+ * differ only in case are one repo on both sides.
+ */
+export function normalizeSlug(slug) {
+    return slug.trim().toLowerCase();
+}
+/** An owner as stored: normalized, and without the trailing `/` the picker displays (`alexvibecommit/`). */
+export function normalizeOwner(owner) {
+    return normalizeSlug(owner).replace(/\/+$/, "");
+}
+/** `local:` slugs name a path, not a repo: no grant can match one, and their consent stays per clone. */
+export function isLocalSlug(slug) {
+    return slug.startsWith("local:");
+}
+/** The owner part of a slug: everything before the last `/`. `""` when there is none. */
+export function ownerOfSlug(slug) {
+    const cut = slug.lastIndexOf("/");
+    return cut <= 0 ? "" : slug.slice(0, cut);
+}
+function stringList(value, normalize) {
+    if (!Array.isArray(value))
+        return null;
+    const out = [];
+    for (const item of value) {
+        if (typeof item !== "string")
+            return null;
+        const n = normalize(item);
+        if (n !== "" && !out.includes(n))
+            out.push(n);
+    }
+    return out;
+}
+const PENDING_OPS = new Set(["grant", "revoke", "exclude", "include"]);
+/**
+ * `pending`: ABSENT is none (every 0.7.0 file), but a field that is there and malformed is `null` — the caller reads the
+ * whole file as unreadable, the same rule as the other lists, since a queue we cannot read may hold a grant we are holding.
+ */
+function parsePending(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        return null;
+    const out = [];
+    for (const item of value) {
+        if (item === null || typeof item !== "object" || Array.isArray(item))
+            return null;
+        const { op, kind, value: v, at } = item;
+        if (typeof op !== "string" || !PENDING_OPS.has(op))
+            return null;
+        if (kind !== "owner" && kind !== "repo")
+            return null;
+        if (typeof v !== "string" || typeof at !== "string")
+            return null;
+        if ((op === "exclude" || op === "include") && kind !== "repo")
+            return null;
+        const clean = kind === "owner" ? normalizeOwner(v) : normalizeSlug(v);
+        if (clean === "")
+            return null;
+        out.push({ op: op, kind, value: clean, at });
+    }
+    return out;
+}
+/**
+ * The seven fields this version knows and REBUILDS on every write (`pending` and `synced_at` are slice 2's); every other top-level key
+ * of `grants.json` is carried through untouched.
+ */
+const KNOWN_GRANTS_KEYS = new Set(["disclosed_at", "owners", "repos", "excluded", "refused", "pending", "synced_at"]);
+/**
+ * `readGrants` plus the top-level keys it does not know, in file order. One read and one parse, so `updateGrants`
+ * rewrites exactly the file it read. `extras` is empty unless `read` is `ok`.
+ */
+function readGrantsWithExtras(home) {
+    const none = [];
+    let raw;
+    try {
+        raw = readFileSync(grantsPath(home), "utf8");
+    }
+    catch (error) {
+        return { read: error.code === "ENOENT" ? { kind: "missing" } : { kind: "unreadable" }, extras: none };
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+            return { read: { kind: "unreadable" }, extras: none };
+        const o = parsed;
+        // A missing list is NOT read as empty: a typo'd `exclude` key would otherwise silently drop every
+        // exclusion. All four are required, extra keys are ignored.
+        const owners = stringList(o.owners, normalizeOwner);
+        const repos = stringList(o.repos, normalizeSlug);
+        const excluded = stringList(o.excluded, normalizeSlug);
+        const refused = stringList(o.refused, normalizeSlug);
+        const pending = parsePending(o.pending);
+        const syncedAt = o.synced_at === undefined ? null : o.synced_at;
+        const at = o.disclosed_at;
+        if (owners === null || repos === null || excluded === null || refused === null || pending === null) {
+            return { read: { kind: "unreadable" }, extras: none };
+        }
+        if (at !== null && typeof at !== "string")
+            return { read: { kind: "unreadable" }, extras: none };
+        if (syncedAt !== null && typeof syncedAt !== "string")
+            return { read: { kind: "unreadable" }, extras: none };
+        return {
+            read: { kind: "ok", grants: { disclosed_at: at, owners, repos, excluded, refused, pending, synced_at: syncedAt } },
+            extras: Object.entries(o).filter(([key]) => !KNOWN_GRANTS_KEYS.has(key)),
+        };
+    }
+    catch {
+        return { read: { kind: "unreadable" }, extras: none };
+    }
+}
+export function readGrants(home) {
+    return readGrantsWithExtras(home).read;
+}
+/** True when a `grants.json` is present and unusable — the state `status` reports and a SessionStart notice names. */
+export function grantsUnreadable(home) {
+    return readGrants(home).kind === "unreadable";
+}
+export const EMPTY_ACCOUNT_STATE = { account: null, refused: [], stale: false, last_get_at: null };
+function parseAccountGrants(value) {
+    if (value === null)
+        return null;
+    if (typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const o = value;
+    const owners = stringList(o.owners, normalizeOwner);
+    const repos = stringList(o.repos, normalizeSlug);
+    const excluded = stringList(o.excluded, normalizeSlug);
+    if (owners === null || repos === null || excluded === null)
+        return undefined;
+    if (typeof o.epoch !== "number" || !Number.isSafeInteger(o.epoch) || o.epoch < 0)
+        return undefined;
+    if (typeof o.synced_at !== "string")
+        return undefined;
+    return { owners, repos, excluded, epoch: o.epoch, synced_at: o.synced_at };
+}
+/** Read it. **NEVER THROWS, and any failure — missing, unreadable, not JSON, any field off-shape — is the empty state.** */
+export function readAccountState(home) {
+    try {
+        const parsed = JSON.parse(readFileSync(grantsAccountPath(home), "utf8"));
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+            return EMPTY_ACCOUNT_STATE;
+        const o = parsed;
+        const account = o.account === undefined ? null : parseAccountGrants(o.account);
+        const refused = o.refused === undefined ? [] : stringList(o.refused, normalizeSlug);
+        const last = o.last_get_at === undefined ? null : o.last_get_at;
+        if (account === undefined || refused === null)
+            return EMPTY_ACCOUNT_STATE;
+        if (o.stale !== undefined && typeof o.stale !== "boolean")
+            return EMPTY_ACCOUNT_STATE;
+        if (last !== null && typeof last !== "string")
+            return EMPTY_ACCOUNT_STATE;
+        return { account, refused, stale: o.stale === true, last_get_at: last };
+    }
+    catch {
+        return EMPTY_ACCOUNT_STATE;
+    }
+}
+/** Write it whole: normalized, atomic, 0600. Throws on an I/O failure (the destination is then untouched). */
+export function writeAccountState(home, state) {
+    const clean = {
+        account: state.account === null
+            ? null
+            : {
+                owners: [...new Set(state.account.owners.map(normalizeOwner).filter((o) => o !== ""))],
+                repos: [...new Set(state.account.repos.map(normalizeSlug).filter((r) => r !== ""))],
+                excluded: [...new Set(state.account.excluded.map(normalizeSlug).filter((x) => x !== ""))],
+                epoch: state.account.epoch,
+                synced_at: state.account.synced_at,
+            },
+        refused: [...new Set(state.refused.map(normalizeSlug).filter((x) => x !== "" && !isLocalSlug(x)))],
+        stale: state.stale,
+        last_get_at: state.last_get_at,
+    };
+    const path = grantsAccountPath(home);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileAtomic(path, `${JSON.stringify(clean, null, 2)}\n`, 0o600);
+}
+/**
+ * A hook saw `repository_excluded` for this slug: remember it, so this machine stops reading that repo's transcripts until
+ * the next sync says otherwise. **NEVER THROWS** — it runs on the hook's path, where a failed write only means the server
+ * refuses the next upload too. `local:` slugs are never recorded (there is no repo identity to refuse).
+ */
+export function recordRefused(home, slug) {
+    const name = normalizeSlug(slug);
+    if (name === "" || isLocalSlug(name))
+        return;
+    try {
+        const current = readAccountState(home);
+        if (current.refused.includes(name))
+            return;
+        writeAccountState(home, { ...current, refused: [...current.refused, name] });
+    }
+    catch {
+        // The hook goes on: nothing was written, and the next refusal tries again.
+    }
+}
+/**
+ * A hook saw `X-Grant-Epoch` on a server answer (an ingest 2xx, or a grants refusal): if it is not the epoch this machine last
+ * recorded, mark the account state `stale`, which is what SessionStart's one bounded `GET` looks for (`session_grants.ts`).
+ * A machine with no recorded account state counts as epoch 0, as the server does when a user has no grants row.
+ *
+ * Writes `grants-account.json` and never `grants.json` (see `AccountState`), only when something changed — so a Stop hook that sees
+ * the same epoch every turn does no file write at all — and only ever sets `stale`; the GET (or a sync) clears it. **NEVER THROWS**:
+ * it runs on the hook's path, and a lost mark only means the next answer marks it again.
+ */
+export function noteGrantEpoch(home, epoch) {
+    if (epoch === null || epoch === undefined || !Number.isSafeInteger(epoch) || epoch < 0)
+        return;
+    try {
+        const current = readAccountState(home);
+        if (current.stale)
+            return;
+        if (epoch === (current.account?.epoch ?? 0))
+            return;
+        writeAccountState(home, { ...current, stale: true });
+    }
+    catch {
+        // The hook goes on: nothing was written, and the next answer marks it again.
+    }
+}
+/**
+ * True when the last synced account state (the last 200) already grants this repo, or its owner. ⚠ Read only to avoid a NEEDLESS
+ * hold — say an owner grant was queued and refused with a 400 while the server already admits this repo — and never to admit: the
+ * account's grants do not admit anything on this machine.
+ */
+function accountGrants(state, name) {
+    const a = state.account;
+    return a !== null && (a.repos.includes(name) || a.owners.includes(ownerOfSlug(name)));
+}
+/** True when a queued `grant` op names this slug, or its owner. */
+function grantPendingFor(pending, name) {
+    const owner = ownerOfSlug(name);
+    return pending.some((p) => p.op === "grant" && (p.kind === "repo" ? p.value === name : p.value === owner));
+}
+/**
+ * Does the hold of `isCaptureAllowed` (step 3) apply to ANYTHING on this machine right now? True when the machine has synced
+ * (`synced_at` is set) and a queued `grant` op names an owner or a repo the last synced account state does not already grant
+ * (the same two conditions the per-slug hold uses: a synced machine, and the account not already admitting it). "0.8.0 truth
+ * fixes" R2-2: `connect`'s untold line says sessions wait only when something actually waits. Reads `grants.json` and
+ * `grants-account.json`; an unreadable `grants.json` holds nothing here (the gate denies for its own reason).
+ */
+export function holdsAny(home) {
+    const read = readGrants(home);
+    if (read.kind !== "ok" || read.grants.synced_at === null)
+        return false;
+    const state = readAccountState(home);
+    // `accountGrants` is the gate's own predicate: an owner op is asked as `owner/` (its owner is `owner`, and no account repo is spelled that way).
+    return read.grants.pending.some((p) => p.op === "grant" && !accountGrants(state, p.kind === "repo" ? p.value : `${p.value}/`));
+}
+/**
+ * ⛔ **THE ONE ADMISSION DECISION.** Every gate calls this; `entry.ts`, `post_commit.ts`, `post_rewrite.ts` (twice),
+ * `finalize.ts`, `status.ts` and `connect.ts` are the seven call sites. Absence is a NO and every error path denies.
+ *
+ * Precedence:
+ *  1. A MISSING `grants.json` is empty (0.6.x machines keep capturing on their common-dir consent). A PRESENT file
+ *     that cannot be read denies every clone that has a slug, whatever `projects.json` says.
+ *  2. A denied slug is denied, whatever the basis: `grants.json`'s `excluded` (and its legacy `refused`), the account file's
+ *     `refused`, or the account's own `excluded`.
+ *  3. On a machine that HAS SYNCED (`grants.synced_at` is set), a slug with a `grant` still PENDING (queued, not yet delivered to
+ *     the account) is held back when that grant is the slug's ONLY local basis, i.e. the clone has no common-dir consent: its
+ *     spans stay unsent with their offset unchanged, and go once a sync delivers the grant. It is not held either when the last
+ *     synced account state already grants the repo or its owner (the server admits it, so a queued grant that was refused must
+ *     not hold it for ever).
+ *     ⭐ **A MACHINE THAT HAS NEVER SYNCED HOLDS NOTHING** (VQ, "0.8.0 truth fixes" F1): the server refuses only a credential that
+ *     has synced (`grants_synced_at`), so before the first sync the hold protects nothing and would only defer uploads, for ever
+ *     against a server without the routes. Such a machine decides capture by its own choices, as under 0.7.0.
+ *     ⭐ **WHY A COMMON-DIR CONSENT LIFTS THE HOLD** (VQ's ruling): a remote repo gets a common-dir consent only from pre-0.8.0
+ *     flows (0.8.0's in-repo `connect` pre-ticks the picker, which writes GRANTS). The first sync uploads those consented slugs, so
+ *     either this credential has not synced, and the server never refuses anything for it, or the first sync already granted the
+ *     slug, and holding it would only delay bytes the server accepts.
+ *  4. Otherwise: admitted on the common-dir consent, or on a slug matched by `owners` or `repos`. ⛔ The account's own
+ *     `owners`/`repos` are NOT consulted — a repo only the account grants is not captured on this machine (per-machine naming).
+ *
+ * `local:` slugs never match a grant and keep common-dir consent alone. They are also not subject to
+ * exclusion or to an unreadable file: there is no repo identity to exclude.
+ *
+ * `grants-account.json` is read on every call and an unreadable one is the empty state, never a denial (`AccountState`).
+ *
+ * ⚠ **`slug` MAY BE A THUNK, and the hooks pass one.** Computing a slug can spawn `git remote get-url` and `ssh -G`,
+ * which is real time on a hook's budget; a machine with no `grants.json` (every 0.6.x machine) needs none of it, and
+ * neither does a clone with no consent and no grants to match. The slug is asked for only when the answer depends on it.
+ * Pass a memoized thunk (`git.ts`'s `onceRepoSlug`) so the caller's own later use shares the one spawn.
+ *
+ * `keys` is the `resolveProjectKeys` result the caller already holds, so the confinement roots it derives afterwards
+ * come from the very resolution this gate used (`D184 §3`).
+ */
+export function isCaptureAllowed(home, keys, slug) {
+    if (keys === null)
+        return false;
+    const byClone = isProjectAllowed(home, keys.consent);
+    const read = readGrants(home);
+    const resolve = () => normalizeSlug(typeof slug === "function" ? slug() : slug);
+    if (read.kind === "unreadable")
+        return isLocalSlug(resolve()) ? byClone : false;
+    const grants = read.kind === "ok" ? read.grants : EMPTY_GRANTS;
+    const account = readAccountState(home);
+    const denyLists = [grants.excluded, grants.refused, account.refused, account.account?.excluded ?? []];
+    const mayDeny = denyLists.some((list) => list.length > 0);
+    const mayHold = !byClone && grants.synced_at !== null && grants.pending.some((p) => p.op === "grant");
+    if (!mayDeny && !mayHold && (byClone || (grants.owners.length === 0 && grants.repos.length === 0)))
+        return byClone;
+    const name = resolve();
+    if (isLocalSlug(name))
+        return byClone;
+    if (denyLists.some((list) => list.includes(name)))
+        return false;
+    if (!byClone && grants.synced_at !== null && grantPendingFor(grants.pending, name) && !accountGrants(account, name))
+        return false;
+    return byClone || grants.repos.includes(name) || grants.owners.includes(ownerOfSlug(name));
+}
+/** `updateGrants` refuses to rewrite a file it cannot read: overwriting would silently drop exclusions it never saw. */
+export class GrantsUnreadableError extends Error {
+    constructor() {
+        super("grants.json is present and cannot be read");
+        this.name = "GrantsUnreadableError";
+    }
+}
+/**
+ * Read-modify-write `grants.json`. 0700 on the directory, 0600 on the file, atomic (a hook reading while a verb saves
+ * sees the old file or the new, never half). Entries are normalized and de-duplicated on the way out.
+ *
+ * ⛔ **Throws `GrantsUnreadableError` rather than start from empty** when the file is present and unusable: a rewrite
+ * would turn "denies everything" into "admits on common-dir consent" without the user having decided anything.
+ *
+ * ⛔ **Keeps the top-level keys it does not know**, verbatim and uninterpreted, after the five it rebuilds (which always
+ * win). A newer version's file read by this one is written back whole: dropping a key it added would silently undo its
+ * state. No lock: same read-modify-write as `projects.json`, so two simultaneous verbs can lose one write.
+ */
+export function updateGrants(home, change) {
+    const { read, extras } = readGrantsWithExtras(home);
+    if (read.kind === "unreadable")
+        throw new GrantsUnreadableError();
+    const next = change(read.kind === "ok" ? read.grants : EMPTY_GRANTS);
+    const clean = {
+        disclosed_at: next.disclosed_at,
+        owners: [...new Set(next.owners.map(normalizeOwner).filter((o) => o !== ""))],
+        repos: [...new Set(next.repos.map(normalizeSlug).filter((r) => r !== ""))],
+        excluded: [...new Set(next.excluded.map(normalizeSlug).filter((x) => x !== ""))],
+        refused: [...new Set(next.refused.map(normalizeSlug).filter((x) => x !== ""))],
+        pending: next.pending.flatMap((p) => {
+            const value = p.kind === "owner" ? normalizeOwner(p.value) : normalizeSlug(p.value);
+            return value === "" ? [] : [{ ...p, value }];
+        }),
+        synced_at: next.synced_at,
+    };
+    const path = grantsPath(home);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    chmodSync(rootDir(home), 0o700);
+    // `Object.fromEntries` defines own properties, so even a key named `__proto__` is written back as data.
+    const out = Object.fromEntries([...Object.entries(clean), ...extras]);
+    writeFileAtomic(path, `${JSON.stringify(out, null, 2)}\n`, 0o600);
+    return clean;
+}
+/** `vibecommit off`: the slug joins `excluded`. Returns true when that changed the file. */
+export function excludeSlug(home, slug) {
+    const name = normalizeSlug(slug);
+    let changed = false;
+    updateGrants(home, (g) => {
+        changed = !g.excluded.includes(name);
+        return changed ? { ...g, excluded: [...g.excluded, name] } : g;
+    });
+    return changed;
+}
+/**
+ * A yes at the disclosure re-includes a turned-off repo; nothing else does. `"none"` when the slug was not excluded
+ * (no file is written then), `"unreadable"` when `grants.json` cannot be read.
+ */
+export function clearExclusion(home, slug) {
+    const name = normalizeSlug(slug);
+    const read = readGrants(home);
+    if (read.kind === "unreadable")
+        return "unreadable";
+    if (read.kind === "missing" || !read.grants.excluded.includes(name))
+        return "none";
+    updateGrants(home, (g) => ({ ...g, excluded: g.excluded.filter((x) => x !== name) }));
+    return "cleared";
+}
 /**
  * Interpret an answer to the consent prompt. **Only an explicit yes is a yes.**
  * Empty (the user pressed return) is NO, which is what makes `[y/N]` honest.