@capybara-hq/kernel 0.1.0-rc.27 → 0.1.0-rc.28

package/dist/tools/connectors.service.js

@@ -96,7 +96,10 @@ let ConnectorsService = class ConnectorsService {
     txHost;
     guides;
     constructor(kdb, registry, 
-    /** Extension manifests (a slug may not take an extension's name). */
+    /**
+     * Extension manifests: a derived default slug avoids an extension's name (an explicit slug may
+     * take one; connector and extension tool keys live in separate namespaces).
+     */
     extensions, credentials, config, drift, 
     /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
     orgLock, txHost, 
@@ -437,6 +440,7 @@ let ConnectorsService = class ConnectorsService {
             connector: input.connector,
             endpoint: JSON.stringify(endpoint),
             auth: JSON.stringify(auth),
+            git_hosts: input.git !== undefined ? JSON.stringify(input.git.hosts) : null,
             created_by: actorAccountId,
             catalog_item_id: input.template?.itemId ?? null,
             catalog_version: input.template?.version ?? null,
@@ -523,14 +527,21 @@ let ConnectorsService = class ConnectorsService {
      */
     async applyTemplateIn(orgId, connectorId, actorAccountId, p, actorTokenId) {
         const t = this.db;
-        await this.row(t, orgId, connectorId, true);
+        const before = await this.row(t, orgId, connectorId, true);
         const { input } = p;
         const policies = input.template.defaultToolPolicies;
+        const botCapable = input.git !== undefined &&
+            input.git.hosts.length > 0 &&
+            input.auth.type !== "none" &&
+            input.auth.ownership === "org";
         await t
             .updateTable("connectors")
             .set({
             endpoint: JSON.stringify(p.endpoint),
             auth: JSON.stringify(input.auth),
+            git_hosts: input.git !== undefined ? JSON.stringify(input.git.hosts) : null,
+            // "use for git" needs org ownership and git hosts: a template that drops either clears it
+            ...(!botCapable && { use_for_git: false }),
             catalog_item_id: input.template.itemId,
             catalog_version: input.template.version,
             template_tool_policies: policies ? JSON.stringify(policies) : null,
@@ -599,6 +610,7 @@ let ConnectorsService = class ConnectorsService {
                 credentialsReset: input.resetCredentials,
                 credentialProvided: p.secret !== undefined || p.oauth !== undefined,
                 policies: policyChanges,
+                ...(before.use_for_git && !botCapable && { useForGit: { from: true, to: false } }),
             },
         });
     }
@@ -770,6 +782,8 @@ let ConnectorsService = class ConnectorsService {
             status: r.status,
             platformTemplateId: r.platform_template_id ?? null,
             catalogItemId: r.catalog_item_id ?? null,
+            git: r.git_hosts !== null && r.git_hosts.length > 0 ? { hosts: r.git_hosts } : null,
+            useForGit: r.use_for_git,
             createdBy: r.created_by,
             createdAt: r.created_at,
             updatedAt: r.updated_at,
@@ -983,15 +997,34 @@ let ConnectorsService = class ConnectorsService {
                     problems.push({ path, message: issue });
             }
         }
+        const appAuth = app.auth;
+        if (patch.useForGit === true) {
+            if (appAuth.type === "none" || appAuth.ownership !== "org") {
+                problems.push({
+                    path: "useForGit",
+                    message: "Only an org-credential connector can be used for git; members' own connections always are",
+                });
+            }
+            else if (app.git_hosts === null || app.git_hosts.length === 0) {
+                problems.push({ path: "useForGit", message: "This connector declares no git hosts" });
+            }
+        }
         if (problems.length > 0) {
             throw new ApiError("validation_failed", "Request validation failed", problems);
         }
-        if (patch.name !== undefined || patch.status !== undefined) {
+        const gitChanged = patch.useForGit !== undefined && patch.useForGit !== app.use_for_git;
+        if (patch.name !== undefined || patch.status !== undefined || gitChanged) {
             await t
                 .updateTable("connectors")
                 .set({
                 ...(patch.name !== undefined && { name: patch.name }),
-                ...(patch.status !== undefined && { status: patch.status }),
+                // An explicit status change is the org's own decision: a plugin switch-off no longer
+                // owns this connector, so a later switch-on must not turn it back on
+                ...(patch.status !== undefined && {
+                    status: patch.status,
+                    disabled_by_plugin_id: null,
+                }),
+                ...(gitChanged && { use_for_git: patch.useForGit === true }),
                 updated_at: sql `now()`,
             })
                 .where("id", "=", connectorId)
@@ -1041,6 +1074,7 @@ let ConnectorsService = class ConnectorsService {
             detail: {
                 ...(patch.name !== undefined && { name: { from: app.name, to: patch.name } }),
                 ...(patch.status !== undefined && { status: { from: app.status, to: patch.status } }),
+                ...(gitChanged && { useForGit: { from: app.use_for_git, to: patch.useForGit } }),
                 ...(toolChanges.length > 0 && { tools: Object.fromEntries(toolChanges) }),
                 ...(allowed.length > 0 && { allowedUnannotated: allowed }),
             },
@@ -1064,6 +1098,57 @@ let ConnectorsService = class ConnectorsService {
             throw notFound();
         return r.org_id;
     }
+    /**
+     * Disables a connector because its plugin was switched off in the org (spec §5 rule 8): its
+     * endpoint and credentials stay. Only a connector that was active is marked with the plugin
+     * (`connectors.disabled_by_plugin_id`), so switching the plugin back on re-enables exactly what
+     * this call disabled; one an org admin disabled by hand keeps no marker and stays disabled. The
+     * caller holds the org row lock and runs in its transaction.
+     */
+    async disableWithPluginIn(orgId, connectorId, itemId) {
+        const t = this.db;
+        const row = await t
+            .selectFrom("connectors")
+            .select(["status"])
+            .where("id", "=", connectorId)
+            .where("org_id", "=", orgId)
+            .where("deleted_at", "is", null)
+            .forUpdate()
+            .executeTakeFirst();
+        if (!row)
+            return;
+        await t
+            .updateTable("connectors")
+            .set({
+            status: "disabled",
+            // An admin's disable is not the plugin's: it is not marked and so stays off on switch-on
+            ...(row.status === "active" && { disabled_by_plugin_id: itemId }),
+            updated_at: sql `now()`,
+        })
+            .where("id", "=", connectorId)
+            .where("org_id", "=", orgId)
+            .where("deleted_at", "is", null)
+            .execute();
+    }
+    /**
+     * Re-enables a connector the given plugin's switch-off disabled
+     * ({@link disableWithPluginIn}) when the plugin is switched back on and its install takes the
+     * connector back through the reuse path. A connector an org admin disabled by hand (no marker)
+     * or one another state left disabled stays disabled. Returns whether it switched it on.
+     */
+    async enableIfPluginDisabledIn(orgId, connectorId, itemId) {
+        const r = await this.db
+            .updateTable("connectors")
+            .set({ status: "active", disabled_by_plugin_id: null, updated_at: sql `now()` })
+            .where("id", "=", connectorId)
+            .where("org_id", "=", orgId)
+            .where("deleted_at", "is", null)
+            .where("status", "=", "disabled")
+            .where("disabled_by_plugin_id", "=", itemId)
+            .returning("id")
+            .executeTakeFirst();
+        return r !== undefined;
+    }
     /**
      * Disables or enables a connector on the platform's behalf (a super admin who need not be a
      * member of the org; the caller checks the super admin): org row lock, the status update, audit
@@ -1077,7 +1162,9 @@ let ConnectorsService = class ConnectorsService {
         const app = await this.row(t, orgId, connectorId, true);
         await t
             .updateTable("connectors")
-            .set({ status, updated_at: sql `now()` })
+            // The platform's explicit choice replaces a plugin switch-off's: a later plugin switch-on
+            // leaves the connector as the platform set it
+            .set({ status, disabled_by_plugin_id: null, updated_at: sql `now()` })
             .where("id", "=", connectorId)
             .execute();
         await audit(t, {
@@ -1384,6 +1471,12 @@ __decorate([
 __decorate([
     Transactional()
 ], ConnectorsService.prototype, "update", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], ConnectorsService.prototype, "disableWithPluginIn", null);
+__decorate([
+    Transactional()
+], ConnectorsService.prototype, "enableIfPluginDisabledIn", null);
 __decorate([
     Transactional()
 ], ConnectorsService.prototype, "setStatusAsPlatform", null);

package/dist/tools/credentials.d.ts

@@ -148,6 +148,24 @@ export declare class Credentials {
      * 返回新 token；refresh 被拒 → 凭据删除并抛 CredentialMissing。静态凭据无事可做。
      */
     onUnauthorized(orgId: string, connectorId: string, auth: ConnectorAuth, accountId: string, stale?: AuthInjection): Promise<void>;
+    /**
+     * The `Authorization` value one git gateway request presents upstream (sandbox git credentials
+     * spec §5, §6.1): `Basic base64(<username>:<token>)` with the connector's token for the actor,
+     * built here so the raw token never reaches a caller. `username` is the git host's basic user
+     * from the connector's `git_hosts` (GitHub: `x-access-token`). An OAuth token is refreshed as
+     * {@link injection} does (cross-replica lock); a `basic` connector presents its stored pair as
+     * it is. The header, its base64 and decoded forms are registered for log redaction. Missing (or
+     * a refresh refused) -> {@link CredentialMissing}; `none` / `headers` auth cannot authenticate
+     * git (git sources exclude them) and throw.
+     */
+    gitAuthorization(orgId: string, connectorId: string, auth: ConnectorAuth, accountId: string, username: string): Promise<string>;
+    /**
+     * The git host answered 401 to `stale` (a value {@link gitAuthorization} returned): an OAuth
+     * connector force-refreshes in the refresh lock, unless another request already replaced that
+     * token, so the next {@link gitAuthorization} presents a new one; a refused refresh deletes the
+     * credential and throws {@link CredentialMissing}. Static credentials: nothing to do.
+     */
+    gitUnauthorized(orgId: string, connectorId: string, auth: ConnectorAuth, accountId: string, stale: string): Promise<void>;
     /** 「需要重新连接」→ CredentialMissing（个人凭据由管线转成 connection_required）。 */
     private oauthCall;
     /**

package/dist/tools/credentials.js

@@ -382,6 +382,66 @@ let Credentials = class Credentials {
         const token = header?.startsWith("Bearer ") ? header.slice("Bearer ".length) : undefined;
         await this.oauthCall(connectorId, auth, () => this.oauth().forceRefresh(orgId, connectorId, auth, ownerOf(auth, accountId), token));
     }
+    /**
+     * The `Authorization` value one git gateway request presents upstream (sandbox git credentials
+     * spec §5, §6.1): `Basic base64(<username>:<token>)` with the connector's token for the actor,
+     * built here so the raw token never reaches a caller. `username` is the git host's basic user
+     * from the connector's `git_hosts` (GitHub: `x-access-token`). An OAuth token is refreshed as
+     * {@link injection} does (cross-replica lock); a `basic` connector presents its stored pair as
+     * it is. The header, its base64 and decoded forms are registered for log redaction. Missing (or
+     * a refresh refused) -> {@link CredentialMissing}; `none` / `headers` auth cannot authenticate
+     * git (git sources exclude them) and throw.
+     */
+    async gitAuthorization(orgId, connectorId, auth, accountId, username) {
+        if (auth.type === "none" || auth.type === "headers") {
+            throw new Error(`credentials: auth type ${auth.type} cannot authenticate git`);
+        }
+        const owner = ownerOf(auth, accountId);
+        let user = username;
+        let password;
+        if (isOAuth(auth)) {
+            password = await this.oauthCall(connectorId, auth, () => this.oauth().accessToken(orgId, connectorId, auth, owner));
+        }
+        else {
+            const missing = () => new CredentialMissing(connectorId, auth.ownership);
+            const value = (await this.readJson(orgId, keyOf(connectorId, owner), connectorId));
+            if (value === null || typeof value !== "object")
+                throw missing();
+            if (auth.type === "basic") {
+                if (typeof value.username !== "string" || typeof value.password !== "string") {
+                    throw missing();
+                }
+                user = value.username;
+                password = value.password;
+            }
+            else {
+                if (typeof value.token !== "string" || value.token === "")
+                    throw missing();
+                password = value.token;
+            }
+        }
+        const header = `Basic ${Buffer.from(`${user}:${password}`).toString("base64")}`;
+        this.log.addOrgSecrets(injectionSecrets({ headers: { Authorization: header } }));
+        return header;
+    }
+    /**
+     * The git host answered 401 to `stale` (a value {@link gitAuthorization} returned): an OAuth
+     * connector force-refreshes in the refresh lock, unless another request already replaced that
+     * token, so the next {@link gitAuthorization} presents a new one; a refused refresh deletes the
+     * credential and throws {@link CredentialMissing}. Static credentials: nothing to do.
+     */
+    async gitUnauthorized(orgId, connectorId, auth, accountId, stale) {
+        if (!isOAuth(auth))
+            return;
+        let token;
+        if (stale.startsWith("Basic ")) {
+            const decoded = Buffer.from(stale.slice("Basic ".length), "base64").toString("utf8");
+            const colon = decoded.indexOf(":");
+            if (colon >= 0)
+                token = decoded.slice(colon + 1);
+        }
+        await this.oauthCall(connectorId, auth, () => this.oauth().forceRefresh(orgId, connectorId, auth, ownerOf(auth, accountId), token));
+    }
     /** 「需要重新连接」→ CredentialMissing（个人凭据由管线转成 connection_required）。 */
     async oauthCall(connectorId, auth, work) {
         try {

package/dist/tools/credentials.module.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Connector credentials ({@link Credentials}) on their own: they need only the global infra
+ * (database, keyring, logger, config, locks, Redis), so the git gateway (`GitModule`) can use them
+ * without importing `ToolsModule` (whose tool code imports `GitModule`). `ToolsModule` re-exports it.
+ */
+export declare class CredentialsModule {
+}

package/dist/tools/credentials.module.js

@@ -0,0 +1,22 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Module } from "@nestjs/common";
+import { Credentials } from "./credentials.js";
+/**
+ * Connector credentials ({@link Credentials}) on their own: they need only the global infra
+ * (database, keyring, logger, config, locks, Redis), so the git gateway (`GitModule`) can use them
+ * without importing `ToolsModule` (whose tool code imports `GitModule`). `ToolsModule` re-exports it.
+ */
+let CredentialsModule = class CredentialsModule {
+};
+CredentialsModule = __decorate([
+    Module({
+        providers: [Credentials],
+        exports: [Credentials],
+    })
+], CredentialsModule);
+export { CredentialsModule };

package/dist/tools/git-asks.d.ts

@@ -0,0 +1,113 @@
+import type { Redis } from "ioredis";
+import { type ApprovalRecord } from "./approvals.service.js";
+/**
+ * Git push asks in the tool pipeline (sandbox git credentials spec §5.6, §7; the flow of network
+ * ask-to-allow spec §6.2–§6.8): the record the gateway leaves when it holds a push, what that
+ * record turns into after the command (an ask to the actor, or notes written at once) and the
+ * model-visible notes. Pure apart from the Redis record helpers, which the gateway (writes) and
+ * the `Bash` pipeline (reads) share.
+ */
+/** How long the gateway's record of a held push waits for the command's result (seconds). */
+export declare const GIT_ASK_RECORD_TTL_SECONDS: number;
+/** The Redis key of the push the gateway held during one exec (`execId`: the tool call id). */
+export declare const gitAskKey: (execId: string) => string;
+/** The most git asks one run makes; later held pushes get {@link gitTooManyNote}. */
+export declare const MAX_GIT_ASKS_PER_RUN = 5;
+/** The line a kept result ends with when it had to be clipped to 16 KB. */
+export declare const GIT_ASK_CLIPPED_NOTE = "[Output clipped to its first 16 KB while waiting for approval of the push.]";
+/**
+ * What the gateway refused during an exec (Redis `git-ask:<execId>`, TTL
+ * {@link GIT_ASK_RECORD_TTL_SECONDS}): the host, the repository (`<owner>/<repo>`, normalized),
+ * the refs the push would have updated and why it refused: `ask` (the policy asks the actor;
+ * absent means `ask`), `unattended` (a scheduled run without a task grant, `fail` mode) or
+ * `denied` (the org's or the member's policy denies it). `connectorId`: the git source whose
+ * credential the push used (the ask's connector).
+ */
+export interface GitAskRecord {
+    host: string;
+    repo: string;
+    refs: string[];
+    connectorId?: string;
+    outcome?: "ask" | "unattended" | "denied";
+}
+/** The Redis commands the record helpers use. */
+export type GitAskRedis = Pick<Redis, "set" | "getdel">;
+/**
+ * Records the push the gateway held during `execId` (one per exec: a later one replaces it), with
+ * TTL {@link GIT_ASK_RECORD_TTL_SECONDS}. An unusable record (no `<owner>/<repo>`) is not written.
+ */
+export declare function recordGitAsk(redis: GitAskRedis, execId: string, ask: GitAskRecord): Promise<void>;
+/** Reads and deletes the push held during `execId` (null: none, expired or unreadable). */
+export declare function takeGitAsk(redis: GitAskRedis, execId: string): Promise<GitAskRecord | null>;
+/**
+ * Asked: the line the gateway's refusal carries (git prints it in the command's output, so the
+ * model reads it in the kept result while the ask waits).
+ */
+export declare const gitAskedNote: (repo: string) => string;
+/** Asked, allowed for the rest of the run (a run grant). */
+export declare const gitAllowedOnceNote: (repo: string, refs: readonly string[]) => string;
+/** Asked, allowed from now on (the member's standing allow for the repository). */
+export declare const gitAllowedAlwaysNote: (repo: string, refs: readonly string[]) => string;
+/** Asked and declined (also a repository refused earlier in the run). */
+export declare const gitDeniedNote: (repo: string, refs: readonly string[], reason?: string | null) => string;
+/** Asked, no answer within the approval timeout. */
+export declare const gitExpiredNote: (repo: string, refs: readonly string[], hours: number) => string;
+/** Asked, the person sent a message instead. */
+export declare const gitSkippedNote: (repo: string, refs: readonly string[]) => string;
+/** Asked, the run was stopped before the answer (the note abort writes too). */
+export declare const gitCancelledNote: () => string;
+/** Not asked: another git push ask of the run tree is waiting (at most one at a time). */
+export declare const gitOtherAskPendingNote: (repo: string, refs: readonly string[]) => string;
+/** Not asked: the run made {@link MAX_GIT_ASKS_PER_RUN} asks already. */
+export declare const gitTooManyNote: (repo: string, refs: readonly string[]) => string;
+/** An unattended run in `fail` mode: no ask, the creator can add a task grant. */
+export declare const gitUnattendedNote: (repo: string, refs: readonly string[]) => string;
+/** The org's or the member's policy denies pushes to the repository. */
+export declare const gitPolicyDeniedNote: (repo: string, refs: readonly string[]) => string;
+/** The push had no credential: the actor has no connection for the host (spec §6.2). */
+export declare const gitNotConnectedNote: (host: string) => string;
+/** How the run state keys a repository on a host: `<host>/<owner>/<repo>` (lower-case). */
+export declare const gitRepoKey: (host: string, repo: string) => string;
+/**
+ * What the run tree's git asks add up to (the network asks' rules, §6.8 there); repositories are
+ * keyed by {@link gitRepoKey}, so a decision about one host says nothing about another.
+ */
+export interface GitRunState {
+    /** Repositories allowed for the rest of the run tree (「这次允许」). */
+    granted: Set<string>;
+    /** Repositories refused in the run tree (denied, expired, skipped, cancelled): never asked again. */
+    refused: Set<string>;
+    /** Git asks of this run (the per-run cap counts them). */
+    asks: number;
+    /** A git ask of the run tree is still pending (at most one at a time). */
+    pending: boolean;
+}
+/** What to do with a push the gateway held. */
+export interface GitPlan {
+    /** Ask the actor about the push (the record's facts become the ask's detail). */
+    ask: boolean;
+    /** Notes written now, after the command output. */
+    notes: string[];
+    /** `missing_grants` keys of an unattended run (`git:push:<owner>/<repo>`). */
+    missingGrants: string[];
+}
+/**
+ * Decides what a held push becomes after its command (the caller asks only for a foreground
+ * `Bash` call): the gateway's own refusals (`unattended`: its note and a missing grant;
+ * `denied`: the policy note) are written at once; an ask (`ask`) about a repository refused
+ * earlier in the run tree gets the denied note, one while another git ask of the tree is pending
+ * or after {@link MAX_GIT_ASKS_PER_RUN} asks of the run gets its note; the rest is asked.
+ */
+export declare function planGitAsk(record: GitAskRecord, run: GitRunState | null): GitPlan;
+/**
+ * The note of a settled git ask: one line per outcome; `hours` is the ask's own wait (created to
+ * expiry). Null while it is pending or for an approval of another kind.
+ */
+export declare function settledGitNotes(a: ApprovalRecord, hours: number): string[] | null;
+/** `text` followed by `notes` after a blank line (unchanged without notes). */
+export declare const withGitNotes: (text: string, notes: readonly string[]) => string;
+/**
+ * A kept result's content within 16 KB (UTF-8): the head, then {@link GIT_ASK_CLIPPED_NOTE}. The
+ * caller archives large output first, so this rarely cuts.
+ */
+export declare const clipGitKept: (content: string) => string;

package/dist/tools/git-asks.js

@@ -0,0 +1,174 @@
+import { GIT_ASK_MAX_REFS, GIT_REF_MAX_CHARS } from "../conversations/events.js";
+import { gitPushGrantKey, normalizeGitRepo } from "../schedules/grant-rules.js";
+import { GIT_ASK_CANCELLED_NOTE } from "./approvals.service.js";
+import { clipKeptWith } from "./network-asks.js";
+/**
+ * Git push asks in the tool pipeline (sandbox git credentials spec §5.6, §7; the flow of network
+ * ask-to-allow spec §6.2–§6.8): the record the gateway leaves when it holds a push, what that
+ * record turns into after the command (an ask to the actor, or notes written at once) and the
+ * model-visible notes. Pure apart from the Redis record helpers, which the gateway (writes) and
+ * the `Bash` pipeline (reads) share.
+ */
+/** How long the gateway's record of a held push waits for the command's result (seconds). */
+export const GIT_ASK_RECORD_TTL_SECONDS = 60 * 60;
+/** The Redis key of the push the gateway held during one exec (`execId`: the tool call id). */
+export const gitAskKey = (execId) => `git-ask:${execId}`;
+/** The most git asks one run makes; later held pushes get {@link gitTooManyNote}. */
+export const MAX_GIT_ASKS_PER_RUN = 5;
+/** The line a kept result ends with when it had to be clipped to 16 KB. */
+export const GIT_ASK_CLIPPED_NOTE = "[Output clipped to its first 16 KB while waiting for approval of the push.]";
+/** A record as stored and read back: valid fields only, refs capped; null when unusable. */
+function cleanRecord(raw) {
+    const r = raw;
+    if (r === null || typeof r !== "object")
+        return null;
+    if (typeof r.host !== "string" || r.host === "" || r.host.length > 255)
+        return null;
+    if (typeof r.repo !== "string")
+        return null;
+    const repo = normalizeGitRepo(r.repo);
+    if (repo === null)
+        return null;
+    const refs = Array.isArray(r.refs)
+        ? [
+            ...new Set(r.refs.filter((x) => typeof x === "string" && x !== "" && x.length <= GIT_REF_MAX_CHARS)),
+        ].slice(0, GIT_ASK_MAX_REFS)
+        : [];
+    const outcome = r.outcome === "unattended" || r.outcome === "denied" || r.outcome === "ask"
+        ? r.outcome
+        : undefined;
+    return {
+        host: r.host.toLowerCase(),
+        repo,
+        refs,
+        ...(typeof r.connectorId === "string" && { connectorId: r.connectorId }),
+        ...(outcome !== undefined && { outcome }),
+    };
+}
+/**
+ * Records the push the gateway held during `execId` (one per exec: a later one replaces it), with
+ * TTL {@link GIT_ASK_RECORD_TTL_SECONDS}. An unusable record (no `<owner>/<repo>`) is not written.
+ */
+export async function recordGitAsk(redis, execId, ask) {
+    const clean = cleanRecord(ask);
+    if (clean === null)
+        return;
+    await redis.set(gitAskKey(execId), JSON.stringify(clean), "EX", GIT_ASK_RECORD_TTL_SECONDS);
+}
+/** Reads and deletes the push held during `execId` (null: none, expired or unreadable). */
+export async function takeGitAsk(redis, execId) {
+    const raw = await redis.getdel(gitAskKey(execId));
+    if (raw === null)
+        return null;
+    try {
+        return cleanRecord(JSON.parse(raw));
+    }
+    catch {
+        return null;
+    }
+}
+/** A ref as notes and cards show it (`refs/heads/` dropped). */
+const shortRef = (ref) => ref.replace(/^refs\/heads\//, "");
+/** "acme/app (main, feat/x)": the repository and up to three refs. */
+function target(repo, refs) {
+    if (refs.length === 0)
+        return repo;
+    const shown = refs.slice(0, 3).map(shortRef).join(", ");
+    return `${repo} (${refs.length > 3 ? `${shown} and ${refs.length - 3} more` : shown})`;
+}
+/** "[git] The push to acme/app (main) was held for the user's approval." (the lead of ask notes). */
+const heldLead = (repo, refs) => `[git] The push to ${target(repo, refs)} was held for the user's approval.`;
+/**
+ * Asked: the line the gateway's refusal carries (git prints it in the command's output, so the
+ * model reads it in the kept result while the ask waits).
+ */
+export const gitAskedNote = (repo) => `[git] Push to ${repo} needs approval; the user is asked after this command.`;
+/** Asked, allowed for the rest of the run (a run grant). */
+export const gitAllowedOnceNote = (repo, refs) => `${heldLead(repo, refs)} The user allowed pushes to ${repo} for the rest of this task. Run the push again.`;
+/** Asked, allowed from now on (the member's standing allow for the repository). */
+export const gitAllowedAlwaysNote = (repo, refs) => `${heldLead(repo, refs)} The user allowed pushes to ${repo} from now on. Run the push again.`;
+/** Asked and declined (also a repository refused earlier in the run). */
+export const gitDeniedNote = (repo, refs, reason) => `${heldLead(repo, refs)} The user declined the push to ${repo}. Do not push it another way; continue without pushing or ask the user.` +
+    (reason != null && reason !== "" ? ` Reason: ${reason}` : "");
+/** Asked, no answer within the approval timeout. */
+export const gitExpiredNote = (repo, refs, hours) => `${heldLead(repo, refs)} The user did not answer within ${hours}h; the push was not made.`;
+/** Asked, the person sent a message instead. */
+export const gitSkippedNote = (repo, refs) => `${heldLead(repo, refs)} The user sent a message instead of answering; the push was not made.`;
+/** Asked, the run was stopped before the answer (the note abort writes too). */
+export const gitCancelledNote = () => GIT_ASK_CANCELLED_NOTE;
+/** Not asked: another git push ask of the run tree is waiting (at most one at a time). */
+export const gitOtherAskPendingNote = (repo, refs) => `[git] The push to ${target(repo, refs)} was not made: another push request is waiting for the user. Run it again after that one is answered.`;
+/** Not asked: the run made {@link MAX_GIT_ASKS_PER_RUN} asks already. */
+export const gitTooManyNote = (repo, refs) => `[git] The push to ${target(repo, refs)} was not made: too many push requests in this task. Ask the user to push or to allow ${repo}.`;
+/** An unattended run in `fail` mode: no ask, the creator can add a task grant. */
+export const gitUnattendedNote = (repo, refs) => `[git] The push to ${target(repo, refs)} was not made: this scheduled run cannot ask for approval. The task's owner can allow pushes to ${repo} for the task. Continue without pushing.`;
+/** The org's or the member's policy denies pushes to the repository. */
+export const gitPolicyDeniedNote = (repo, refs) => `[git] The push to ${target(repo, refs)} was not made: pushes to ${repo} are not allowed by this organization's policy. Do not push it another way; continue without pushing or tell the user.`;
+/** The push had no credential: the actor has no connection for the host (spec §6.2). */
+export const gitNotConnectedNote = (host) => `[git] The push to ${host} was not made: the user has no connection that can push there. The user can connect one under Settings → Connectors; continue without pushing or ask the user.`;
+/** How the run state keys a repository on a host: `<host>/<owner>/<repo>` (lower-case). */
+export const gitRepoKey = (host, repo) => `${host.toLowerCase()}/${repo}`;
+/**
+ * Decides what a held push becomes after its command (the caller asks only for a foreground
+ * `Bash` call): the gateway's own refusals (`unattended`: its note and a missing grant;
+ * `denied`: the policy note) are written at once; an ask (`ask`) about a repository refused
+ * earlier in the run tree gets the denied note, one while another git ask of the tree is pending
+ * or after {@link MAX_GIT_ASKS_PER_RUN} asks of the run gets its note; the rest is asked.
+ */
+export function planGitAsk(record, run) {
+    const { repo, refs } = record;
+    switch (record.outcome) {
+        case "unattended":
+            return {
+                ask: false,
+                notes: [gitUnattendedNote(repo, refs)],
+                missingGrants: [gitPushGrantKey(repo)],
+            };
+        case "denied":
+            return { ask: false, notes: [gitPolicyDeniedNote(repo, refs)], missingGrants: [] };
+        default:
+            break;
+    }
+    if (run?.refused.has(gitRepoKey(record.host, repo))) {
+        return { ask: false, notes: [gitDeniedNote(repo, refs)], missingGrants: [] };
+    }
+    if (run?.pending === true) {
+        return { ask: false, notes: [gitOtherAskPendingNote(repo, refs)], missingGrants: [] };
+    }
+    if ((run?.asks ?? 0) >= MAX_GIT_ASKS_PER_RUN) {
+        return { ask: false, notes: [gitTooManyNote(repo, refs)], missingGrants: [] };
+    }
+    return { ask: true, notes: [], missingGrants: [] };
+}
+/**
+ * The note of a settled git ask: one line per outcome; `hours` is the ask's own wait (created to
+ * expiry). Null while it is pending or for an approval of another kind.
+ */
+export function settledGitNotes(a, hours) {
+    if (a.git === null)
+        return null;
+    const { repo, refs } = a.git;
+    switch (a.status) {
+        case "approved":
+            return [
+                a.scope === "always" ? gitAllowedAlwaysNote(repo, refs) : gitAllowedOnceNote(repo, refs),
+            ];
+        case "denied":
+            return [gitDeniedNote(repo, refs, a.denyReason)];
+        case "expired":
+            return [gitExpiredNote(repo, refs, hours)];
+        case "skipped":
+            return [gitSkippedNote(repo, refs)];
+        case "cancelled":
+            return [gitCancelledNote()];
+        default:
+            return null;
+    }
+}
+/** `text` followed by `notes` after a blank line (unchanged without notes). */
+export const withGitNotes = (text, notes) => notes.length === 0 ? text : `${text}\n\n${notes.join("\n")}`;
+/**
+ * A kept result's content within 16 KB (UTF-8): the head, then {@link GIT_ASK_CLIPPED_NOTE}. The
+ * caller archives large output first, so this rarely cuts.
+ */
+export const clipGitKept = (content) => clipKeptWith(content, GIT_ASK_CLIPPED_NOTE);