toolroll 0.5.0

package/dist/gate-failure.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Why a machine gate failed, read from its sealed receipt, log and candidate
+ * inventory — so the bounded repair loop does not spend a code-writing
+ * attempt on a failure the change cannot have caused.
+ *
+ * Two classes are conservative enough to skip a repair draft:
+ *  - the whole command timed out before any test failed, and
+ *  - every failing test is a per-test timeout inside a file the candidate
+ *    did not touch.
+ * An ordinary assertion failure anywhere — including in an untouched file,
+ * whose imports the change may have broken — stays repairable. When the
+ * failing files cannot be read from the log with certainty, the failure
+ * stays repairable too: never silence a real failure by parsing badly.
+ */
+import type { VerifyCommandFacts } from "./proof.js";
+export type GateFailureClass = {
+    kind: "repairable";
+} | {
+    kind: "gate-timed-out";
+    timeoutMs: number | null;
+} | {
+    kind: "untouched-test-timeout";
+    files: string[];
+};
+export type FailingTest = {
+    file: string;
+    timedOut: boolean;
+};
+/** The failing tests a Vitest log names, or null when the log's own failed
+ * count and its FAIL blocks disagree (or no count was printed at all). */
+export declare function failingTestsOf(log: string): FailingTest[] | null;
+export declare function classifyGateFailure(result: VerifyCommandFacts, log: string, changedPaths: readonly string[] | null, timeoutMs?: number | null): GateFailureClass;
+/** What happened, in one sentence, for every notice about this failure. */
+export declare function gateFailureSummary(failure: Exclude<GateFailureClass, {
+    kind: "repairable";
+}>): string;
+/** Plain words for the person who has to act. */
+export declare function describeGateFailure(failure: Exclude<GateFailureClass, {
+    kind: "repairable";
+}>, taskId: string): string;

package/dist/gate-failure.js

@@ -0,0 +1,66 @@
+const ANSI = /\x1b\[[0-9;]*[A-Za-z]/g;
+const FAIL_LINE = /^\s*FAIL\s+(\S+?)(?:\s+>\s.*)?\s*$/;
+const TESTS_SUMMARY = /^\s*Tests\s+(\d+)\s+failed\b/;
+const TIMED_OUT = /\b(?:Test|Hook) timed out in \d+ms\b/;
+/** The failing tests a Vitest log names, or null when the log's own failed
+ * count and its FAIL blocks disagree (or no count was printed at all). */
+export function failingTestsOf(log) {
+    const lines = log.replace(ANSI, "").split(/\r?\n/);
+    const failures = [];
+    let reported = null;
+    let open = null;
+    for (const line of lines) {
+        const summary = TESTS_SUMMARY.exec(line);
+        if (summary) {
+            reported = Number(summary[1]);
+            open = null;
+            continue;
+        }
+        const fail = FAIL_LINE.exec(line);
+        if (fail) {
+            open = { file: fail[1], timedOut: false };
+            failures.push(open);
+            continue;
+        }
+        if (open !== null && TIMED_OUT.test(line))
+            open.timedOut = true;
+    }
+    if (reported === null || reported !== failures.length)
+        return null;
+    return failures;
+}
+/** Vitest prints paths relative to its root; the candidate inventory lists
+ * repository paths. Treat a failing file as touched when any changed path is
+ * the same path or ends with it. */
+const touched = (file, changed) => changed.some(path => path === file || path.endsWith(`/${file}`) || file.endsWith(`/${path}`));
+export function classifyGateFailure(result, log, changedPaths, timeoutMs = null) {
+    if (!result.configured)
+        return { kind: "repairable" };
+    if (!result.ran) {
+        return result.failure === "timed-out" || result.failure === "retry-timed-out" ? { kind: "gate-timed-out", timeoutMs } : { kind: "repairable" };
+    }
+    if (result.exitCode === 0 || changedPaths === null)
+        return { kind: "repairable" };
+    const failures = failingTestsOf(log);
+    if (failures === null || failures.length === 0)
+        return { kind: "repairable" };
+    if (failures.every(one => one.timedOut && !touched(one.file, changedPaths))) {
+        return { kind: "untouched-test-timeout", files: [...new Set(failures.map(one => one.file))].sort() };
+    }
+    return { kind: "repairable" };
+}
+/** What happened, in one sentence, for every notice about this failure. */
+export function gateFailureSummary(failure) {
+    if (failure.kind === "gate-timed-out") {
+        const limit = failure.timeoutMs === null ? "its time limit" : `${Math.round(failure.timeoutMs / 1000)} s`;
+        return `The project check ran out of time (${limit}) before any test failed, so the code was not shown to be wrong.`;
+    }
+    return `The project check failed only because ${failure.files.join(", ")} timed out, and this change did not touch ${failure.files.length === 1 ? "that file" : "those files"}.`;
+}
+/** Plain words for the person who has to act. */
+export function describeGateFailure(failure, taskId) {
+    const next = failure.kind === "gate-timed-out"
+        ? `Raise the check's time limit or shorten the suite, then run \`toolroll task regate ${taskId}\` to check the same commit again.`
+        : `Run \`toolroll task regate ${taskId}\` to check the same commit again, or fix the slow test outside this task first.`;
+    return `${gateFailureSummary(failure)} No repair task was filed. ${next}`;
+}

package/dist/git.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Parsers for git plumbing output.
+ *
+ * Pure functions over strings — no child_process, no fs. Shelling out lives in
+ * the caller, so the part most worth testing needs no fixture repo. This is also
+ * why discovery can claim to be read-only: nothing here can reach a repository.
+ */
+export type Worktree = {
+    path: string;
+    head: string;
+    /** null when in detached HEAD — which is how treehouse leases worktrees. */
+    branch: string | null;
+    detached: boolean;
+    bare: boolean;
+    locked: boolean;
+    prunable: boolean;
+};
+export type TrackingState = {
+    ahead: number;
+    behind: number;
+    /** Upstream existed and was deleted — the merged-and-cleaned-up case. */
+    gone: boolean;
+};
+export type Branch = {
+    name: string;
+    track: TrackingState;
+    /** Opaque ISO-8601 from git, passed through untouched. Never reformatted here. */
+    committedAt: string;
+};
+/**
+ * Parse `git worktree list --porcelain`.
+ *
+ * Records are separated by blank lines; each is a sequence of `key value` lines
+ * where `detached`, `bare`, `locked` and `prunable` are bare flags that may carry
+ * a trailing reason we deliberately discard.
+ */
+export declare function parseWorktrees(porcelain: string): Worktree[];
+/**
+ * Parse the `%(upstream:track)` field: `""`, `"[gone]"`, `"[ahead 2]"`,
+ * `"[behind 5]"`, or `"[ahead 2, behind 5]"`.
+ *
+ * Unrecognized input yields a zeroed state rather than throwing — a tracking
+ * field we cannot read must never take down discovery of the repo around it.
+ */
+export declare function parseTrack(field: string): TrackingState;
+/**
+ * Parse tab-separated `git for-each-ref` output:
+ *
+ *   %(refname:short)\t%(upstream:track)\t%(committerdate:iso8601-strict)
+ *
+ * Tabs rather than spaces because a ref name may not contain a tab, but the
+ * tracking field always does.
+ */
+export declare function parseBranches(output: string): Branch[];

package/dist/git.js

@@ -0,0 +1,94 @@
+/**
+ * Parsers for git plumbing output.
+ *
+ * Pure functions over strings — no child_process, no fs. Shelling out lives in
+ * the caller, so the part most worth testing needs no fixture repo. This is also
+ * why discovery can claim to be read-only: nothing here can reach a repository.
+ */
+const HEADS_PREFIX = "refs/heads/";
+const emptyTrack = () => ({ ahead: 0, behind: 0, gone: false });
+/**
+ * Parse `git worktree list --porcelain`.
+ *
+ * Records are separated by blank lines; each is a sequence of `key value` lines
+ * where `detached`, `bare`, `locked` and `prunable` are bare flags that may carry
+ * a trailing reason we deliberately discard.
+ */
+export function parseWorktrees(porcelain) {
+    return porcelain
+        .split(/\n\s*\n/)
+        .map(block => block.trim())
+        .filter(Boolean)
+        .map(parseWorktreeBlock)
+        .filter((wt) => wt !== null);
+}
+function parseWorktreeBlock(block) {
+    const lines = block.split("\n");
+    const path = readValue(lines, "worktree");
+    if (path === null)
+        return null;
+    const branchRef = readValue(lines, "branch");
+    return {
+        path,
+        head: readValue(lines, "HEAD") ?? "",
+        branch: branchRef === null ? null : stripHeadsPrefix(branchRef),
+        detached: hasFlag(lines, "detached"),
+        bare: hasFlag(lines, "bare"),
+        locked: hasFlag(lines, "locked"),
+        prunable: hasFlag(lines, "prunable"),
+    };
+}
+/** First value for `key`, or null when absent. Values may contain spaces. */
+function readValue(lines, key) {
+    const prefix = `${key} `;
+    const line = lines.find(l => l.startsWith(prefix));
+    return line === undefined ? null : line.slice(prefix.length).trim();
+}
+/** Flags appear bare (`detached`) or with a trailing reason (`locked why`). */
+function hasFlag(lines, flag) {
+    return lines.some(l => l === flag || l.startsWith(`${flag} `));
+}
+function stripHeadsPrefix(ref) {
+    return ref.startsWith(HEADS_PREFIX) ? ref.slice(HEADS_PREFIX.length) : ref;
+}
+/**
+ * Parse the `%(upstream:track)` field: `""`, `"[gone]"`, `"[ahead 2]"`,
+ * `"[behind 5]"`, or `"[ahead 2, behind 5]"`.
+ *
+ * Unrecognized input yields a zeroed state rather than throwing — a tracking
+ * field we cannot read must never take down discovery of the repo around it.
+ */
+export function parseTrack(field) {
+    const trimmed = field.trim();
+    if (trimmed === "")
+        return emptyTrack();
+    if (trimmed === "[gone]")
+        return { ahead: 0, behind: 0, gone: true };
+    return {
+        ahead: readCount(trimmed, "ahead"),
+        behind: readCount(trimmed, "behind"),
+        gone: false,
+    };
+}
+function readCount(field, key) {
+    const match = field.match(new RegExp(`${key} (\\d+)`));
+    return match === null ? 0 : Number(match[1]);
+}
+/**
+ * Parse tab-separated `git for-each-ref` output:
+ *
+ *   %(refname:short)\t%(upstream:track)\t%(committerdate:iso8601-strict)
+ *
+ * Tabs rather than spaces because a ref name may not contain a tab, but the
+ * tracking field always does.
+ */
+export function parseBranches(output) {
+    return output
+        .split("\n")
+        .filter(line => line.trim() !== "")
+        .map(parseBranchLine);
+}
+function parseBranchLine(line) {
+    const [name = "", track = "", committedAt = ""] = line.split("\t");
+    return { name: name.trim(), track: parseTrack(track), committedAt: committedAt.trim() };
+}

package/dist/google-mail.d.ts

@@ -0,0 +1,58 @@
+export declare const GOOGLE_AUTH = "https://accounts.google.com/o/oauth2/v2/auth";
+export declare const GOOGLE_TOKEN = "https://oauth2.googleapis.com/token";
+/** Full mail access is what IMAP and SMTP sign-in needs; "email" says which address it is. */
+export declare const GOOGLE_SCOPE = "https://mail.google.com/ openid email";
+export declare const GOOGLE_CALLBACK = "/settings/google/callback";
+export type GoogleMail = {
+    clientId: string;
+    clientSecret: string;
+    refreshToken: string | null;
+    address: string | null;
+};
+export declare function readGoogleMail(dir: string | null): GoogleMail | null;
+/** Connected: a refresh token and the address it belongs to. */
+export declare function googleConnected(dir: string | null): {
+    address: string;
+} | null;
+/** Save the OAuth client from Settings; an empty secret keeps the saved one. A new client forgets the old connection. */
+export declare function saveGoogleClient(dir: string, input: {
+    clientId: unknown;
+    clientSecret: unknown;
+}): {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+export type GoogleVisit = {
+    state: string;
+    verifier: string;
+    redirectUri: string;
+    by: string;
+    expires: number;
+};
+/** Where to send the person to consent, and what to remember to check their return against. */
+export declare function googleConsent(client: GoogleMail, redirectUri: string, by: string, now?: number): {
+    url: string;
+    visit: GoogleVisit;
+};
+/** The one-time code from Google's redirect, exchanged for a refresh token and saved. */
+export declare function finishGoogleConsent(dir: string, visit: GoogleVisit, code: string, fetcher: typeof fetch): Promise<{
+    ok: true;
+    address: string;
+} | {
+    ok: false;
+    message: string;
+}>;
+/** A fresh access token for IMAP and SMTP (kept in memory until a minute before it ends). */
+export declare function googleAccessToken(dir: string | null, fetcher: typeof fetch, now?: number): Promise<{
+    ok: true;
+    token: string;
+    address: string;
+} | {
+    ok: false;
+    said: string;
+    permanent: boolean;
+}>;
+/** Disconnect: Google forgets the grant (best effort), and the file goes. */
+export declare function disconnectGoogle(dir: string, fetcher: typeof fetch): Promise<void>;

package/dist/google-mail.js

@@ -0,0 +1,151 @@
+/**
+ * A Google account for email (v89): sign in with Google instead of an app
+ * password, for Send email steps and Inbox triggers alike.
+ *
+ * The person makes an OAuth client in their own Google Cloud project (a
+ * "Web application", with this console's callback as its redirect address)
+ * and pastes its ID and secret into Settings → Email. Connecting sends them
+ * to Google's consent screen; Google sends them back here with a one-time
+ * code (checked against a state and a PKCE verifier made for that visit),
+ * which becomes a refresh token. The client secret and refresh token live
+ * in a 0600 file beside the database, never in a column, a log or a page.
+ * Mail itself goes over IMAP and SMTP with XOAUTH2, so reading and sending
+ * are the same code as for any other mail server.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { chmodSync, existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const FILE = "google-mail.json";
+export const GOOGLE_AUTH = "https://accounts.google.com/o/oauth2/v2/auth";
+export const GOOGLE_TOKEN = "https://oauth2.googleapis.com/token";
+const GOOGLE_REVOKE = "https://oauth2.googleapis.com/revoke";
+/** Full mail access is what IMAP and SMTP sign-in needs; "email" says which address it is. */
+export const GOOGLE_SCOPE = "https://mail.google.com/ openid email";
+export const GOOGLE_CALLBACK = "/settings/google/callback";
+export function readGoogleMail(dir) {
+    if (dir === null || !existsSync(join(dir, FILE)))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(join(dir, FILE), "utf8"));
+        if (typeof raw["clientId"] !== "string" || typeof raw["clientSecret"] !== "string")
+            return null;
+        return { clientId: raw["clientId"], clientSecret: raw["clientSecret"], refreshToken: typeof raw["refreshToken"] === "string" ? raw["refreshToken"] : null, address: typeof raw["address"] === "string" ? raw["address"] : null };
+    }
+    catch {
+        return null;
+    }
+}
+/** Connected: a refresh token and the address it belongs to. */
+export function googleConnected(dir) {
+    const saved = readGoogleMail(dir);
+    return saved?.refreshToken && saved.address ? { address: saved.address } : null;
+}
+function write(dir, value) {
+    writeFileSync(join(dir, FILE), JSON.stringify(value), { mode: 0o600 });
+    chmodSync(join(dir, FILE), 0o600);
+}
+/** Save the OAuth client from Settings; an empty secret keeps the saved one. A new client forgets the old connection. */
+export function saveGoogleClient(dir, input) {
+    const clientId = typeof input.clientId === "string" ? input.clientId.trim() : "";
+    if (!/^[0-9]{6,20}-[a-z0-9]{8,64}\.apps\.googleusercontent\.com$/.test(clientId))
+        return { ok: false, message: "That doesn't look like a Google OAuth client ID. It ends in .apps.googleusercontent.com." };
+    const before = readGoogleMail(dir);
+    const clientSecret = typeof input.clientSecret === "string" && input.clientSecret.trim() !== "" ? input.clientSecret.trim() : before?.clientId === clientId ? before.clientSecret : "";
+    if (!/^[A-Za-z0-9_-]{16,80}$/.test(clientSecret))
+        return { ok: false, message: "Paste the client secret from the same OAuth client." };
+    write(dir, { clientId, clientSecret, refreshToken: before?.clientId === clientId ? before.refreshToken : null, address: before?.clientId === clientId ? before.address : null });
+    return { ok: true };
+}
+/** Where to send the person to consent, and what to remember to check their return against. */
+export function googleConsent(client, redirectUri, by, now = Date.now()) {
+    const state = randomBytes(24).toString("base64url"), verifier = randomBytes(48).toString("base64url");
+    const challenge = createHash("sha256").update(verifier).digest("base64url");
+    const url = `${GOOGLE_AUTH}?${new URLSearchParams({
+        client_id: client.clientId, redirect_uri: redirectUri, response_type: "code", scope: GOOGLE_SCOPE,
+        access_type: "offline", prompt: "consent", include_granted_scopes: "true", state, code_challenge: challenge, code_challenge_method: "S256",
+    })}`;
+    return { url, visit: { state, verifier, redirectUri, by, expires: now + 10 * 60_000 } };
+}
+const post = async (fetcher, url, form) => {
+    const response = await fetcher(url, { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" }, body: new URLSearchParams(form), signal: AbortSignal.timeout(20_000) });
+    let body = {};
+    try {
+        body = await response.json();
+    }
+    catch { /* an empty or broken answer */ }
+    return { status: response.status, body };
+};
+/** The address an ID token names; it came straight from Google's token endpoint over TLS. */
+function addressOf(idToken) {
+    if (typeof idToken !== "string")
+        return null;
+    try {
+        const claims = JSON.parse(Buffer.from(idToken.split(".")[1] ?? "", "base64url").toString("utf8"));
+        return typeof claims["email"] === "string" && claims["email_verified"] !== false ? claims["email"] : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The one-time code from Google's redirect, exchanged for a refresh token and saved. */
+export async function finishGoogleConsent(dir, visit, code, fetcher) {
+    const client = readGoogleMail(dir);
+    if (client === null)
+        return { ok: false, message: "Save the Google OAuth client first." };
+    let answer;
+    try {
+        answer = await post(fetcher, GOOGLE_TOKEN, { code, client_id: client.clientId, client_secret: client.clientSecret, redirect_uri: visit.redirectUri, grant_type: "authorization_code", code_verifier: visit.verifier });
+    }
+    catch {
+        return { ok: false, message: "Couldn't reach Google. Try connecting again." };
+    }
+    const refresh = answer.body["refresh_token"], scope = String(answer.body["scope"] ?? "");
+    if (answer.status !== 200 || typeof refresh !== "string")
+        return { ok: false, message: `Google didn't connect it${typeof answer.body["error_description"] === "string" ? `: ${String(answer.body["error_description"]).slice(0, 160)}` : "."}` };
+    if (!scope.split(" ").includes("https://mail.google.com/"))
+        return { ok: false, message: "Google didn't allow mail access. Connect again and tick the box to read, compose, send and delete mail." };
+    const address = addressOf(answer.body["id_token"]);
+    if (address === null)
+        return { ok: false, message: "Google didn't say which address this is. Connect again." };
+    write(dir, { ...client, refreshToken: refresh, address });
+    cached.delete(client.clientId);
+    return { ok: true, address };
+}
+const cached = new Map();
+/** A fresh access token for IMAP and SMTP (kept in memory until a minute before it ends). */
+export async function googleAccessToken(dir, fetcher, now = Date.now()) {
+    const saved = readGoogleMail(dir);
+    if (saved?.refreshToken == null || saved.address === null)
+        return { ok: false, said: "The Google account isn't connected. Connect it in Settings → Email.", permanent: true };
+    const hit = cached.get(saved.clientId);
+    if (hit !== undefined && hit.refresh === saved.refreshToken && hit.until > now)
+        return { ok: true, token: hit.token, address: saved.address };
+    let answer;
+    try {
+        answer = await post(fetcher, GOOGLE_TOKEN, { client_id: saved.clientId, client_secret: saved.clientSecret, refresh_token: saved.refreshToken, grant_type: "refresh_token" });
+    }
+    catch {
+        return { ok: false, said: "Couldn't reach Google to sign in.", permanent: false };
+    }
+    const token = answer.body["access_token"];
+    if (answer.status !== 200 || typeof token !== "string") {
+        // invalid_grant: the person removed access, or the client changed. It won't fix itself.
+        const lost = answer.body["error"] === "invalid_grant";
+        return { ok: false, said: lost ? "Google no longer accepts this connection. Connect the account again in Settings → Email." : "Google didn't sign in just now.", permanent: lost };
+    }
+    cached.set(saved.clientId, { token, refresh: saved.refreshToken, until: now + Math.max(60, Number(answer.body["expires_in"]) || 3600) * 1000 - 60_000 });
+    return { ok: true, token, address: saved.address };
+}
+/** Disconnect: Google forgets the grant (best effort), and the file goes. */
+export async function disconnectGoogle(dir, fetcher) {
+    const saved = readGoogleMail(dir);
+    if (saved?.refreshToken) {
+        try {
+            await fetcher(`${GOOGLE_REVOKE}?${new URLSearchParams({ token: saved.refreshToken })}`, { method: "POST", signal: AbortSignal.timeout(10_000) });
+        }
+        catch { /* the file goes either way */ }
+    }
+    if (saved !== null)
+        cached.delete(saved.clientId);
+    rmSync(join(dir, FILE), { force: true });
+}

package/dist/grant.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Permission to write to somebody else's tracker.
+ *
+ * Everything up to here reads. This is the line, and it is drawn deliberately
+ * wide of where it needs to be: discovery indexes everything it can see, and
+ * Toolroll drives only what has been handed over, one repository and one
+ * backend at a time, by a person, in an act that shows its own consequences
+ * first.
+ *
+ * The grant is not a boolean. A yes/no flag would answer "may I write here"
+ * and leave every interesting question — write *what*, to *which* tasks, with
+ * *whose* credentials, visible to *whom* — to whatever the agent decided at
+ * 3am. So the record carries all of them, and the check is against the whole
+ * thing.
+ *
+ * Two defaults are load-bearing.
+ *
+ * **Only tasks we created or were given.** An operator enrolling a repository
+ * with four hundred open issues is not volunteering all four hundred to an
+ * unattended agent, and reading enrollment that way is how a tool ends up
+ * closing somebody's backlog overnight.
+ *
+ * **Closing is not included.** Creating a task is additive and reversible;
+ * transitioning one we own is ours to do; closing work somebody else filed is
+ * neither, so it is off unless explicitly granted. Widening takes another
+ * human action, which is the design's rule and not a nicety.
+ *
+ * Absence of a grant is denial. There is no implicit, inherited, or default
+ * permission anywhere in this module — an unknown repository is refused for
+ * the same reason an unknown lease is: silence is not consent.
+ */
+import { type ExecResult, type RunOptions } from "./exec.js";
+/**
+ * What a write actually does, split by how much it can hurt.
+ *
+ * `close` is separate from `transition` because "mark the task I am working on
+ * as done" and "close the issue somebody filed in March" are the same verb to
+ * a database and completely different acts to a person.
+ */
+export type MutationClass = "create" | "transition" | "edge" | "hold" | "close" | "comment";
+export declare const MUTATION_CLASSES: readonly MutationClass[];
+/** Granted unless asked otherwise; `close` is the deliberate omission. */
+export declare const DEFAULT_MUTATIONS: readonly MutationClass[];
+/**
+ * Which tasks the grant covers. `ours` means the ones Toolroll created or
+ * was explicitly given — the design's default, and the one that keeps an
+ * enrolment from becoming an amnesty over an entire backlog.
+ */
+export type TaskSelector = "ours" | "all";
+export type BackendGrant = {
+    repo: string;
+    backend: string;
+    /** Exact paths, or `owner/name` for a GitHub tracker. Never a wildcard. */
+    paths: string[];
+    mutations: MutationClass[];
+    selector: TaskSelector;
+    /** Named, never held: the value lives on the runner. */
+    credentialScope: string | null;
+    /** Whether these writes will show up in `git status` and in history. */
+    observedByGit: boolean;
+    grantedAt: string;
+    grantedBy: string;
+    /** External dispatch (v20): a SEPARATE authority from tracker writes —
+     * "this plane will BUILD what this tracker nominates, under scopes
+     * approved here". Never in any default; its own explicit yes. */
+    dispatch?: boolean;
+    /** The one exact owner/name this dispatch grant binds. Required when
+     * dispatch is true (enforced in saveGrant). */
+    remoteRepo?: string | null;
+    /** This plane's identity for the tracker-side marker — detection of a
+     * second plane, never a distributed lease. Minted at grant creation. */
+    planeId?: string | null;
+    /** Fail-closed dispatch block: set by marker verification and sync
+     * failures; null = clear. Admission refuses while set. */
+    dispatchBlocked?: "pending-marker" | "unreachable" | "foreign" | "missing" | "multiple-or-malformed" | null;
+    dispatchBlockedAt?: string | null;
+    dispatchBlockedDetail?: string | null;
+};
+/** Where a task came from, which is what `selector` discriminates on. */
+export type TaskOrigin = "ours" | "theirs";
+export type WriteRequest = {
+    repo: string;
+    backend: string;
+    mutation: MutationClass;
+    origin: TaskOrigin;
+    /** The file or repository being written, when the backend has one. */
+    path?: string;
+};
+export type Verdict = {
+    ok: true;
+} | {
+    ok: false;
+    reason: DenialReason;
+    message: string;
+};
+/** Stable tokens: an agent branches on these, a person reads the message. */
+export type DenialReason = "no-grant" | "mutation" | "selector" | "path";
+/**
+ * Whether this write is inside the grant.
+ *
+ * Written as a pure function over the whole grant so the policy can be read in
+ * one place and tested without a database, a repository, or a network — the
+ * three things that make a permission check hard to trust.
+ */
+export declare function permits(grant: BackendGrant | null, request: WriteRequest): Verdict;
+export type Runner = (file: string, args: readonly string[], options?: RunOptions) => Promise<ExecResult>;
+export type ProposeOptions = {
+    repo: string;
+    backend: string;
+    paths: string[];
+    mutations?: readonly MutationClass[];
+    selector?: TaskSelector;
+    credentialScope?: string | null;
+    grantedBy?: string;
+    now: Date;
+    runner?: Runner;
+};
+/**
+ * Build the grant that would be created, including the one fact an operator
+ * cannot easily check for themselves: whether these writes will be visible.
+ *
+ * A backend that stores its data in a tracked directory means every task
+ * transition shows up in `git status` and eventually in history — which is
+ * either exactly what somebody wants, or a nasty surprise on their next
+ * commit. It is asked of git rather than assumed, because the answer differs
+ * per repository and the guess would be wrong half the time.
+ */
+export declare function proposeGrant(options: ProposeOptions): Promise<BackendGrant>;
+/**
+ * The grant, in the words an operator needs before agreeing to it — what may
+ * be touched, what may be done, to which tasks, and whether anyone else will
+ * see it happen.
+ */
+export declare function describeGrant(grant: BackendGrant): string[];
+/** What is not granted, which is the half people forget to read. */
+export declare function describeWithheld(grant: BackendGrant): string[];