@quickchatai/pi-quickreview 0.0.0-stage → 1.2.0

package/dist/src/gate.d.ts

@@ -0,0 +1,199 @@
+export type MutationKind = "add_label" | "remove_label" | "delete_team_review_request" | "request_reviewer" | "create_review" | "create_review_comment_reply" | "create_issue_comment" | "resolve_own_review_thread" | "create_issue" | "create_pull" | "push_branch" | "supersede_own_review" | "update_own_webhook_url";
+/**
+ * The same set at RUNTIME. The union above is erased at compile time, so on
+ * its own it stops honest call sites and nothing else — a hand-rolled intent
+ * (or one that crosses a JSON boundary) would pass. Every intent is checked
+ * against this list, which makes a kind that is not on it — a review
+ * dismissal, say — unreachable in fact and not merely in the type system.
+ */
+export declare const MUTATION_KINDS: readonly MutationKind[];
+/**
+ * The app-self-config gate class (AGENTS.md invariant 6): mutations that touch
+ * ONLY the GitHub App's own configuration and can never reach the reviewed
+ * repo. The gate EXECUTES this class even when `dry_run = true`, loudly
+ * logged every time, because new users run dry-run during exactly the window
+ * the webhook self-heal matters.
+ *
+ * The class is a CLOSED SET, pinned exactly like the forceLive bypass: it
+ * contains exactly `update_own_webhook_url`, and tests/gate.test.ts asserts
+ * deep equality against that one-element list, so adding a second kind fails
+ * a test. Widening it is the owner's call, never an in-flight improvement.
+ * `forceLive` semantics are untouched — the gate still throws on forceLive
+ * for anything but `supersede_own_review`, this kind included.
+ */
+export declare const APP_SELF_CONFIG_KINDS: readonly ["update_own_webhook_url"];
+/** The class as a TYPE, so a `Record<MutationKind, …>` elsewhere can exclude
+ * it deliberately (the App-manifest permission map: these are JWT-authed and
+ * need no installation permission at all) instead of forgetting it. */
+export type AppSelfConfigKind = (typeof APP_SELF_CONFIG_KINDS)[number];
+/**
+ * Provenance of a MECHANICALLY-authored review — one the daemon composed
+ * itself, as opposed to the round's substantive review, which the session
+ * writes. Absent means substantive.
+ *
+ * Both members are COMMENT-event reviews that state a fact and ask for
+ * nothing: the migration-number collision remedy, and the escalation note
+ * pointing one named person at one named thing. Neither carries a verdict, so
+ * neither may claim the head (guards.ts `after`).
+ *
+ * That is enforced, not described. A `reviewPurpose` buys two
+ * exemptions — it never claims the head, and the escalation purpose is exempt
+ * from guard 2 — so a purpose riding an APPROVE would be an approval that
+ * never marks the head it approved.
+ * `execute()` therefore refuses any purposed intent that is not a
+ * `create_review` with `event: "COMMENT"` — on the detached snapshot of the
+ * caller's intent at entry, and again on the detached copy of what the guard
+ * hands back (see `snapshot`), so the `event` this check reads is the
+ * `event` the executor sends.
+ */
+export type ReviewPurpose = "migration_precheck" | "escalation";
+/**
+ * Every field is `readonly` because every object the gate hands on is frozen
+ * (see `snapshot` and `execute`): the type is honest about the runtime object.
+ * A guard rewrites by RETURNING a new object — a spread with `body` and/or
+ * `note` replaced, which is what the shipped guards do; those two are the
+ * whole of a guard's authority (GUARD_REWRITABLE_FIELDS). A first-party guard
+ * that assigns to `intent.kind` — or to `intent.note`, the field it is most
+ * invited to touch — fails to compile instead of failing inside the guard
+ * with a bare TypeError that names no kind. (The freeze is shallow: an
+ * assignment INSIDE `body` lands on the guard's own copy — see `snapshot`.)
+ */
+export interface MutationIntent {
+    readonly kind: MutationKind;
+    /** REST method+path for API intents; "git" for pushes. */
+    readonly method: "POST" | "PATCH" | "PUT" | "DELETE" | "git";
+    readonly path: string;
+    readonly body?: unknown;
+    /** Human-readable one-liner for the dry-run record / event log. */
+    readonly note: string;
+    readonly pr?: number;
+    /** Internal provenance for a mechanically-authored review. Absent means a
+     * substantive review. It never enters the GitHub body; posting guards use
+     * it only to keep mechanical pre-check output from claiming the head. */
+    readonly reviewPurpose?: ReviewPurpose;
+    /** The posting key of a
+     * deferred SESSION review the daemon is delivering after GitHub failed to
+     * answer the session's own POST. It buys exactly one exemption — guard 5
+     * (head drift): the review is posted at its ORIGINAL `commit_id` even if
+     * the PR has moved on since. Every other guard binds (merged/closed, CI,
+     * human approval, no-new-evidence) and dry-run suppresses it like anything
+     * else. Admission confines it to a substantive `create_review` whose body
+     * carries this key's marker and whose `commit_id` is this key's head
+     * (`postingRetryCheck`). It never enters the GitHub body. */
+    readonly postingRetry?: string;
+    /** Execute even in dry-run. Only `supersede_own_review` may set this: the
+     * session-side posting leakage is accepted, so the cleanup of that leakage
+     * must be real too. Noise-reducing only. */
+    readonly forceLive?: boolean;
+}
+export interface GateResult {
+    executed: boolean;
+    dryRunFile?: string;
+    response?: unknown;
+    /** Set when a guard refused the mutation. Nothing was executed and
+     * nothing was recorded — the reason is a short tag ("pr-merged", …). */
+    blocked?: string;
+}
+export type MutationExecutor = (intent: MutationIntent) => Promise<unknown>;
+/**
+ * How a `method: "git"` intent is actually performed.
+ *
+ * A git push cannot go through the REST executor — `GitHubAdapter.executeMutation`
+ * throws on `method === "git"` — yet it must still be gated in live mode
+ * (AGENTS.md invariant 1). So the gate mediates the push: the caller — which is
+ * the only thing that knows which clone the push must run in — hands the gate
+ * a performer, and the
+ * GATE, never the call site, decides whether it runs: the kind check, the
+ * `forceLive` check, the guards and the dry-run branch all run first, exactly
+ * as they do for a REST mutation.
+ *
+ * The seam cannot widen. `execute` throws if a performer accompanies any method
+ * other than `"git"` OR any kind other than `push_branch` — `method` is a free
+ * field with no relation to `kind`, so the method check alone would let any
+ * kind ride the performer. Both are checked again on the intent that comes out
+ * of the guard step (`admit` runs twice), and that intent is compared field by
+ * field against the frozen snapshot the guard was handed
+ * (`GUARD_REWRITABLE_FIELDS`), so a guard has no way to change either.
+ */
+export type GitPerformer = () => Promise<unknown>;
+/** A guard's answer: refuse (`block`), or let it through — optionally with a
+ * rewritten intent (the human-approval downgrade posts a COMMENT instead of a
+ * REQUEST_CHANGES). Returning `{}` means "no opinion". The intent a guard
+ * receives is a FROZEN snapshot: an in-place edit to a top-level field throws,
+ * and an edit inside `body` lands on the guard's copy, never the caller's. The
+ * intent that goes on is a fresh copy (`snapshot`) of whatever the guard
+ * returned — or of the snapshot it was handed, body included, when it returned
+ * none — and it may differ from that snapshot in `body` and `note` ONLY
+ * (GUARD_REWRITABLE_FIELDS); the gate refuses any other difference. */
+export interface GuardDecision {
+    block?: string;
+    intent?: MutationIntent;
+}
+/**
+ * The ONLY fields a guard may rewrite. Everything else on a
+ * MutationIntent is the mutation's IDENTITY — `kind` selects the gate's policy
+ * (the kind list, the forceLive exception, the app-self-config class),
+ * `method` + `path` are what the executor actually sends, `pr` is what the
+ * `after` hooks stamp, and `reviewPurpose` and `forceLive` each buy an
+ * exemption — and a guard has no business with any of it.
+ *
+ * Why a closed list of what MAY change, rather than checks on what must not:
+ * the gate admits an intent, lets the guards rewrite it, then executes what
+ * came back. A re-check that enumerates only the fields it thought of would
+ * let a guard return `kind: "dismiss_review"`, or turn a review into
+ * `update_own_webhook_url` (which executes for real in dry-run), or add
+ * `forceLive`. Guards 1 and 4 rewrite `body` and `note` and nothing else,
+ * which is the whole of what a guard is for: it may change the PAYLOAD
+ * (`body` — and for a review, a label, a reviewer request or a pull that IS
+ * the verdict, the labels, the logins, the branches; softening is the shipped
+ * use, not the limit) and the RECORD (`note`), never the ROUTE — `kind`,
+ * `method`, `path`, `pr` — nor the two exemptions. Rule 2 is meant to be
+ * structural, so a guard's authority is stated positively and exhaustively.
+ * A field added to MutationIntent later is identity by default and stays
+ * un-rewritable until someone puts it here on purpose.
+ *
+ * How the comparison is made to mean something: a check on what a guard
+ * RETURNS is only a check if the guard cannot change the
+ * object it was HANDED — `MutationIntent` is a plain object, and a guard that
+ * assigned `intent.kind = …` and returned `{}` (or returned that same object)
+ * would execute the assigned kind. So `execute` hands the
+ * guard a `snapshot` of the admitted intent — frozen, with its own copy of
+ * `body` (strict-mode ESM: an assignment to an identity field throws inside
+ * the guard, and an edit to the body reaches the guard's copy, never the
+ * caller's) — takes a second `snapshot` of what came back (so a getter on any
+ * field, `body`'s contents included, is read exactly once and cannot answer
+ * one thing to this check and another to the executor), compares the two, and
+ * re-admits the copy that will execute — unconditionally, whether or not the
+ * guard returned an intent.
+ */
+export declare const GUARD_REWRITABLE_FIELDS: readonly ["body", "note"];
+/**
+ * Posting-time guards, attached to the ONE gate so that no posting
+ * route can reach GitHub around them. `before` runs ahead of the dry-run
+ * branch and of the executor; `after` sees what actually happened.
+ */
+export interface MutationGuard {
+    before(intent: MutationIntent): Promise<GuardDecision>;
+    after?(intent: MutationIntent, result: GateResult): void | Promise<void>;
+}
+export declare class MutationGate {
+    private readonly dryRun;
+    private readonly dryrunDir;
+    private readonly executor;
+    private readonly now;
+    private guard?;
+    private logFn;
+    constructor(dryRun: boolean, dryrunDir: string, executor: MutationExecutor, now?: () => Date, guard?: MutationGuard | undefined, logFn?: (msg: string, extra?: unknown) => void);
+    get isDryRun(): boolean;
+    /** Attach the posting guards. Production wiring needs the store and the
+     * adapter, which only exist after the gate itself does — hence a setter
+     * rather than a constructor-only dependency. */
+    setGuard(guard: MutationGuard): void;
+    /** Attach the production logger (same late-binding shape as setGuard). The
+     * core has no console of its own, so the app-self-config loud line goes
+     * where the host says: every production gate is wired (src/wire.ts to the
+     * daemon log; src/daemon.ts, src/cli.ts and packages/pi-plugin/src/reviewpost.ts to stdout). */
+    setLog(logFn: (msg: string, extra?: unknown) => void): void;
+    execute(intentIn: MutationIntent, perform?: GitPerformer): Promise<GateResult>;
+}
+//# sourceMappingURL=gate.d.ts.map

package/dist/src/gate.d.ts.map

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

package/dist/src/gate.js

@@ -0,0 +1,315 @@
+// The single GitHub mutation gate. Every write to GitHub — REST, GraphQL or
+// git push — is described as a MutationIntent and passed through execute().
+// In dry-run (config.dry_run) the intent is written to state/dryrun/ instead
+// of being executed. There is deliberately no review-dismissal intent kind:
+// the never-dismiss invariant is structural (AGENTS.md invariant 2).
+//
+// A git push is gated too: a git intent carries a `GitPerformer` (see below)
+// and the gate, not the call site, decides whether it runs.
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { postingMarker } from "./postingkey.js";
+/**
+ * The same set at RUNTIME. The union above is erased at compile time, so on
+ * its own it stops honest call sites and nothing else — a hand-rolled intent
+ * (or one that crosses a JSON boundary) would pass. Every intent is checked
+ * against this list, which makes a kind that is not on it — a review
+ * dismissal, say — unreachable in fact and not merely in the type system.
+ */
+export const MUTATION_KINDS = [
+    "add_label",
+    "remove_label",
+    "delete_team_review_request",
+    "request_reviewer",
+    "create_review",
+    "create_review_comment_reply",
+    "create_issue_comment",
+    "resolve_own_review_thread",
+    "create_issue",
+    "create_pull",
+    "push_branch",
+    "supersede_own_review",
+    "update_own_webhook_url",
+];
+/**
+ * The app-self-config gate class (AGENTS.md invariant 6): mutations that touch
+ * ONLY the GitHub App's own configuration and can never reach the reviewed
+ * repo. The gate EXECUTES this class even when `dry_run = true`, loudly
+ * logged every time, because new users run dry-run during exactly the window
+ * the webhook self-heal matters.
+ *
+ * The class is a CLOSED SET, pinned exactly like the forceLive bypass: it
+ * contains exactly `update_own_webhook_url`, and tests/gate.test.ts asserts
+ * deep equality against that one-element list, so adding a second kind fails
+ * a test. Widening it is the owner's call, never an in-flight improvement.
+ * `forceLive` semantics are untouched — the gate still throws on forceLive
+ * for anything but `supersede_own_review`, this kind included.
+ */
+export const APP_SELF_CONFIG_KINDS = [
+    "update_own_webhook_url",
+];
+/**
+ * The ONLY fields a guard may rewrite. Everything else on a
+ * MutationIntent is the mutation's IDENTITY — `kind` selects the gate's policy
+ * (the kind list, the forceLive exception, the app-self-config class),
+ * `method` + `path` are what the executor actually sends, `pr` is what the
+ * `after` hooks stamp, and `reviewPurpose` and `forceLive` each buy an
+ * exemption — and a guard has no business with any of it.
+ *
+ * Why a closed list of what MAY change, rather than checks on what must not:
+ * the gate admits an intent, lets the guards rewrite it, then executes what
+ * came back. A re-check that enumerates only the fields it thought of would
+ * let a guard return `kind: "dismiss_review"`, or turn a review into
+ * `update_own_webhook_url` (which executes for real in dry-run), or add
+ * `forceLive`. Guards 1 and 4 rewrite `body` and `note` and nothing else,
+ * which is the whole of what a guard is for: it may change the PAYLOAD
+ * (`body` — and for a review, a label, a reviewer request or a pull that IS
+ * the verdict, the labels, the logins, the branches; softening is the shipped
+ * use, not the limit) and the RECORD (`note`), never the ROUTE — `kind`,
+ * `method`, `path`, `pr` — nor the two exemptions. Rule 2 is meant to be
+ * structural, so a guard's authority is stated positively and exhaustively.
+ * A field added to MutationIntent later is identity by default and stays
+ * un-rewritable until someone puts it here on purpose.
+ *
+ * How the comparison is made to mean something: a check on what a guard
+ * RETURNS is only a check if the guard cannot change the
+ * object it was HANDED — `MutationIntent` is a plain object, and a guard that
+ * assigned `intent.kind = …` and returned `{}` (or returned that same object)
+ * would execute the assigned kind. So `execute` hands the
+ * guard a `snapshot` of the admitted intent — frozen, with its own copy of
+ * `body` (strict-mode ESM: an assignment to an identity field throws inside
+ * the guard, and an edit to the body reaches the guard's copy, never the
+ * caller's) — takes a second `snapshot` of what came back (so a getter on any
+ * field, `body`'s contents included, is read exactly once and cannot answer
+ * one thing to this check and another to the executor), compares the two, and
+ * re-admits the copy that will execute — unconditionally, whether or not the
+ * guard returned an intent.
+ */
+export const GUARD_REWRITABLE_FIELDS = [
+    "body",
+    "note",
+];
+/** See GUARD_REWRITABLE_FIELDS: every field outside that list must be the
+ * same value (`Object.is`, so a `NaN` the guard never touched is not blamed on
+ * it) before and after the guard, presence included — a guard that ADDS
+ * `forceLive: true` differs from one that left it absent. The walk is over
+ * every OWN key of both objects — string and symbol, whatever the type
+ * declares — because that is exactly the set `snapshot`'s spread copies onto
+ * the object that executes: a field the type does not declare, or a
+ * symbol-keyed one, is exactly what this check must not assume away. */
+function guardRewriteCheck(before, after) {
+    // Viewed as bags of fields, deliberately: `keyof MutationIntent` is the one
+    // thing an unknown added key is not.
+    const b = before;
+    const a = after;
+    for (const field of new Set([...Reflect.ownKeys(b), ...Reflect.ownKeys(a)])) {
+        if (typeof field === "string" && GUARD_REWRITABLE_FIELDS.includes(field))
+            continue;
+        if (!Object.is(b[field], a[field])) {
+            throw new Error(`gate: a guard may rewrite only ${GUARD_REWRITABLE_FIELDS.join(" and ")}; it changed "${String(field)}" on ${before.kind} ` +
+                `(${JSON.stringify(b[field])} → ${JSON.stringify(a[field])}) — refusing to execute or record it`);
+        }
+    }
+}
+/**
+ * A frozen copy of an intent with its OWN `body` — the object `execute`
+ * admits, hands a guard, and then compares, re-admits and executes. Every
+ * field is read exactly once, here, by the spread; nothing downstream ever
+ * reads the object it was given. Shallow everywhere but `body`, because
+ * `body` is the one nested field: a body is plain data (the REST executor
+ * JSON-encodes it; the push body is three strings), so `structuredClone`
+ * detaches it and reads any getter in it once. A body that is not plain data
+ * (a function, a URL, …) is one the executor could not have sent faithfully
+ * either; it is refused — with the gate's name and the kind on the refusal,
+ * so the log line says which mutation went nowhere and why, rather than a
+ * bare DataCloneError.
+ */
+function snapshot(intent) {
+    const copy = { ...intent };
+    if (copy.body !== undefined) {
+        try {
+            copy.body = structuredClone(copy.body);
+        }
+        catch (err) {
+            throw new Error(`gate: intent body for ${copy.kind} is not plain data (${err instanceof Error ? err.message : String(err)}) — refusing to execute or record it`, { cause: err });
+        }
+    }
+    return Object.freeze(copy);
+}
+/** See ReviewPurpose: a purposed intent is a `create_review` COMMENT or it is
+ * refused. Free function called from `admit`, which `execute` runs twice —
+ * on the entry snapshot, and again on the post-guard copy. */
+function reviewPurposeCheck(intent) {
+    if (!intent.reviewPurpose)
+        return;
+    const event = String(intent.body?.event ?? "").toUpperCase();
+    if (intent.kind !== "create_review" || event !== "COMMENT") {
+        throw new Error(`gate: reviewPurpose "${intent.reviewPurpose}" is only allowed on a create_review with event COMMENT, not ${intent.kind}/${event || "(no event)"}`);
+    }
+}
+/** See MutationIntent.postingRetry: a substantive create_review carrying
+ * the key's own marker at the key's own head, or it is refused. */
+function postingRetryCheck(intent) {
+    if (intent.postingRetry === undefined)
+        return;
+    const key = intent.postingRetry;
+    const body = (intent.body ?? {});
+    const m = typeof key === "string" ? /^v1:\d+:\d+:([0-9a-f]+)$/.exec(key) : null;
+    if (intent.kind !== "create_review" ||
+        intent.reviewPurpose !== undefined ||
+        !m ||
+        typeof body.commit_id !== "string" ||
+        body.commit_id.toLowerCase() !== m[1] ||
+        typeof body.body !== "string" ||
+        !body.body.includes(postingMarker(key))) {
+        throw new Error(`gate: postingRetry is only allowed on a substantive create_review at its key's head carrying its key's marker (${intent.kind})`);
+    }
+}
+/**
+ * Admission: what the gate demands of ANY intent before it may execute or be
+ * recorded. It runs on the entry `snapshot` of the caller's intent — never on
+ * the caller's object itself, whose fields (a getter on `kind`, say) could
+ * answer this check one way and the snapshot's spread another — and again on
+ * the snapshot of whatever a guard hands back. Each
+ * run is the invariant "only an admitted intent executes", checked on the
+ * very object that goes on rather than inferred from GUARD_REWRITABLE_FIELDS.
+ * The field list and admission are deliberately independent belts: the list
+ * says what a guard MAY change, admission says what may run at all — so
+ * widening the list (should a guard ever need to) does not loosen what runs.
+ */
+function admit(intent, perform) {
+    // Checked before anything else — an unknown kind is never recorded to
+    // state/dryrun/ either, so it cannot leave evidence suggesting the daemon
+    // performs it.
+    if (!MUTATION_KINDS.includes(intent.kind)) {
+        throw new Error(`gate: unknown mutation kind "${intent.kind}" — refusing to execute or record it`);
+    }
+    // The git performer exists for `method: "git"` and nothing else:
+    // otherwise it would be a second executor, i.e. a way to run an arbitrary
+    // mutation the REST executor never saw. Refused regardless of what any guard
+    // says — admission is not a guard's to soften.
+    if (perform && intent.method !== "git") {
+        throw new Error(`gate: a git performer is only allowed for method "git", not ${intent.method} (${intent.kind})`);
+    }
+    // `method` is a free field with no relation to `kind`, so the method check
+    // alone would let any kind ride the performer. `push_branch` is the only
+    // kind this system ever performs with git — and rule 4 already says the
+    // only branches it pushes are `bot/improve-*`.
+    if (perform && intent.kind !== "push_branch") {
+        throw new Error(`gate: a git performer is only allowed for kind "push_branch", not ${intent.kind}`);
+    }
+    if (intent.forceLive && intent.kind !== "supersede_own_review") {
+        throw new Error(`forceLive is not allowed for kind ${intent.kind}`);
+    }
+    // A reviewPurpose marks a MECHANICALLY-authored COMMENT (see ReviewPurpose):
+    // it buys two exemptions, so it is confined to the one shape those
+    // exemptions are safe for.
+    reviewPurposeCheck(intent);
+    postingRetryCheck(intent);
+}
+let seq = 0;
+export class MutationGate {
+    dryRun;
+    dryrunDir;
+    executor;
+    now;
+    guard;
+    logFn;
+    constructor(dryRun, dryrunDir, executor, now = () => new Date(), guard, logFn = () => { }) {
+        this.dryRun = dryRun;
+        this.dryrunDir = dryrunDir;
+        this.executor = executor;
+        this.now = now;
+        this.guard = guard;
+        this.logFn = logFn;
+    }
+    get isDryRun() {
+        return this.dryRun;
+    }
+    /** Attach the posting guards. Production wiring needs the store and the
+     * adapter, which only exist after the gate itself does — hence a setter
+     * rather than a constructor-only dependency. */
+    setGuard(guard) {
+        this.guard = guard;
+    }
+    /** Attach the production logger (same late-binding shape as setGuard). The
+     * core has no console of its own, so the app-self-config loud line goes
+     * where the host says: every production gate is wired (src/wire.ts to the
+     * daemon log; src/daemon.ts, src/cli.ts and packages/pi-plugin/src/reviewpost.ts to stdout). */
+    setLog(logFn) {
+        this.logFn = logFn;
+    }
+    async execute(intentIn, perform) {
+        // The caller's object is read ONCE, by this spread, and never again: what
+        // is admitted, handed to the guards and (with no guard installed) executed
+        // is this frozen snapshot with its own body — so the object that executes
+        // is the object that was checked. An assignment to one of its top-level
+        // fields throws inside a guard (strict-mode ESM); an edit inside its body
+        // lands on the snapshot's copy, never the caller's.
+        let intent = snapshot(intentIn);
+        admit(intent, perform);
+        // Posting-time guards run BEFORE the dry-run branch: a mutation a guard
+        // refuses is neither executed nor recorded, so the dry-run evidence shows
+        // the same behaviour the live path would have had.
+        if (this.guard) {
+            const decision = await this.guard.before(intent);
+            if (decision.block) {
+                const blocked = { executed: false, blocked: decision.block };
+                await this.guard.after?.(intent, blocked);
+                return blocked;
+            }
+            // Whatever came back — a rewrite, or the snapshot itself when the guard
+            // had no opinion — is snapshotted ONCE, body included, and that copy is
+            // what is compared, admitted and executed. Copying is what makes both
+            // checks final: a getter on a returned field, or inside its body, is
+            // read here and never again, so it cannot answer this check with one
+            // value (`event: COMMENT` to the reviewPurpose leg) and the executor
+            // with another. Both checks run unconditionally; `return {}` is not a
+            // way around them.
+            const post = snapshot(decision.intent ?? intent);
+            // A guard may soften the mutation (guards 1 and 4 rewrite the review
+            // body and the note), never change which mutation it is: every field
+            // outside GUARD_REWRITABLE_FIELDS must be identical to the snapshot.
+            guardRewriteCheck(intent, post);
+            // And what executes is re-admitted IN FULL — kind against
+            // MUTATION_KINDS, forceLive against its single permitted kind, the
+            // performer's method/kind, reviewPurpose against the rewritten body —
+            // on the object that will execute, not inferred from the check above.
+            // Only the reviewPurpose leg can still fail here today (guard 1 really
+            // does rewrite the event); the rest is what keeps that true if the
+            // field list is ever widened.
+            admit(post, perform);
+            intent = post;
+        }
+        // The app-self-config class (see APP_SELF_CONFIG_KINDS): executes for real
+        // even in dry-run (AGENTS.md invariant 6), and every execution is loud. The
+        // intent's `note` names old and new URL, so the line does too.
+        if (APP_SELF_CONFIG_KINDS.includes(intent.kind)) {
+            this.logFn(`gate: APP-SELF-CONFIG "${intent.kind}" executing FOR REAL${this.dryRun ? " despite dry_run (the app-self-config exception)" : ""} — ${intent.note}`);
+            const response = await this.executor(intent);
+            const executed = { executed: true, response };
+            await this.guard?.after?.(intent, executed);
+            return executed;
+        }
+        if (this.dryRun && !intent.forceLive) {
+            mkdirSync(this.dryrunDir, { recursive: true });
+            const ts = this.now().toISOString().replace(/[:.]/g, "-");
+            const file = join(this.dryrunDir, `${ts}-${String(seq++).padStart(4, "0")}-${intent.kind}.json`);
+            writeFileSync(file, JSON.stringify({ recorded_at: this.now().toISOString(), ...intent }, null, 2));
+            const recorded = { executed: false, dryRunFile: file };
+            await this.guard?.after?.(intent, recorded);
+            return recorded;
+        }
+        // A `method: "git"` intent runs its performer; everything else runs the
+        // REST executor (which still throws on "git", so a git intent that arrives
+        // without a performer cannot execute). By this line `intent` is a frozen
+        // copy that has passed admission — twice, if a guard was installed — and
+        // that matched the admitted snapshot on `method` and `kind`, so the
+        // performer only ever runs against the push_branch it was handed in for.
+        const response = perform ? await perform() : await this.executor(intent);
+        const executed = { executed: true, response };
+        await this.guard?.after?.(intent, executed);
+        return executed;
+    }
+}
+//# sourceMappingURL=gate.js.map

package/dist/src/gate.js.map

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

package/dist/src/ghcred.d.ts

@@ -0,0 +1,58 @@
+export declare const CREDENTIAL_SOURCES: readonly ["app", "handoff", "gh", "env:GITHUB_TOKEN", "env:GH_TOKEN"];
+export type CredentialSource = (typeof CREDENTIAL_SOURCES)[number];
+/** The variable that names the handed-over token file. */
+export declare const HANDOFF_FILE_ENV = "QCR_GH_TOKEN_FILE";
+/** Where the container sees the handoff dir. */
+export declare const HANDOFF_MOUNT = "/run/qcr-in";
+/**
+ * Read the handed-over token file once and unlink it. Returns the token (also
+ * kept for `handedToken()`), or null when no file was named. Throws, leaving
+ * nothing in memory, when the file is named but unreadable, empty, or cannot
+ * be removed: a token that stays on disk beside a model's tools is refused,
+ * never used. The variable is deleted from `env` either way, so no child
+ * inherits the path.
+ */
+export declare function takeHandoffToken(env?: Record<string, string | undefined>): string | null;
+/** The token `takeHandoffToken` read, or null. */
+export declare const handedToken: () => string | null;
+/** Forget the handed-over token (tests; a long-lived host after its last use). */
+export declare function dropHandedToken(): void;
+export interface StagedHandoff {
+    /** The host dir to bind-mount at HANDOFF_MOUNT (mode 0700). */
+    dir: string;
+    /** The value for QCR_GH_TOKEN_FILE inside the container. */
+    containerFile: string;
+    /** Remove the host dir; call on exit, whatever happened. */
+    remove: () => void;
+}
+/**
+ * The caller's half: write `token` to a 0600 file in a fresh 0700 dir. On
+ * Linux the dir is under an absolute $XDG_RUNTIME_DIR (normally a tmpfs);
+ * without one, and elsewhere (macOS), it comes from mkdtemp under the OS
+ * temp dir ($TMPDIR), which may be disk-backed. The token is never put in env or argv.
+ */
+export declare function stageHandoffToken(token: string, env?: Record<string, string | undefined>, platform?: NodeJS.Platform): StagedHandoff;
+export type CredentialResolution = {
+    ok: true;
+    source: CredentialSource;
+    token: string;
+} | {
+    ok: false;
+    error: string;
+};
+export declare const MISSING_CREDENTIAL_HELP: string;
+export interface CredentialDeps {
+    /** `[github].secrets_dir`: where the App's app_id and app.pem live. */
+    secretsDir: string;
+    env: Record<string, string | undefined>;
+    /** Mint an installation token from the App in `secretsDir`. */
+    mintApp: (secretsDir: string) => Promise<string>;
+    /** The token `gh auth token` prints, or null when gh is absent or logged out. */
+    ghAuthToken: () => string | null;
+    /** The token handed to this container as a file, if one was (`handedToken()`). */
+    handoff?: string | null;
+}
+/** The real `gh auth token`. */
+export declare function ghAuthTokenFromCli(): string | null;
+export declare function resolveGithubCredential(d: CredentialDeps): Promise<CredentialResolution>;
+//# sourceMappingURL=ghcred.d.ts.map

package/dist/src/ghcred.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ghcred.d.ts","sourceRoot":"","sources":["../../src/ghcred.ts"],"names":[],"mappings":"AAgCA,eAAO,MAAM,kBAAkB,uEAMrB,CAAC;AACX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnE,0DAA0D;AAC1D,eAAO,MAAM,gBAAgB,sBAAsB,CAAC;AACpD,gDAAgD;AAChD,eAAO,MAAM,aAAa,gBAAgB,CAAC;AAI3C;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACpD,MAAM,GAAG,IAAI,CAgBf;AAED,kDAAkD;AAClD,eAAO,MAAM,WAAW,QAAO,MAAM,GAAG,IAAc,CAAC;AAEvD,kFAAkF;AAClF,wBAAgB,eAAe,IAAI,IAAI,CAEtC;AAED,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,aAAa,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,EACb,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,EACrD,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,aAAa,CAgBf;AAED,MAAM,MAAM,oBAAoB,GAC9B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvF,eAAO,MAAM,uBAAuB,QAEqC,CAAC;AAE1E,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACxC,+DAA+D;IAC/D,OAAO,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACjD,iFAAiF;IACjF,WAAW,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IACjC,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,gCAAgC;AAChC,wBAAgB,kBAAkB,IAAI,MAAM,GAAG,IAAI,CAWlD;AAED,wBAAsB,uBAAuB,CAAC,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,oBAAoB,CAAC,CA4B9F"}