toolroll 0.9.91 → 0.9.93

package/dist/phase-routing.js

@@ -50,7 +50,7 @@
  */
 import { ACP_AGENTS, isAcpProvider } from "./acp-agents.js";
 import { createHash } from "node:crypto";
-import { MODEL_ID_SHAPE, postureOf, readRouteOverrides, readSealedRoute, RISKS, ROUTE_PHASES, ROUTE_PROVIDERS, ROUTE_VERSION, TASK_SIZE_WORDS, } from "./contracts/route.js";
+import { MODEL_ID_SHAPE, postureOf, readRouteOverrides, PLAIN_ROUTE_VERSION, readSealedRoute, RISKS, ROUTE_PHASES, ROUTE_PROVIDERS, ROUTE_VERSION, TASK_SIZE_WORDS, } from "./contracts/route.js";
 import { canonicalJson } from "./canonical-json.js";
 export { MODEL_ID_SHAPE };
 // Type-only imports from provider.ts: it sits under evidence.ts and scope.ts
@@ -72,7 +72,7 @@ export function exactModelId(v) {
 /** v2 adds the task's size (small / medium / large, risky or not), the
  * light tier, and plan headroom. A v1 route — sealed before sizing — still
  * reads back exactly and keeps its own digest domain. */
-export { ROUTE_VERSION };
+export { PLAIN_ROUTE_VERSION, ROUTE_VERSION };
 /** The durable route ERA a scope row carries once it was filed under this
  * policy: NULL on a row proven to predate v47 (legacy — the sealed profile
  * alone governs), this value on every row filed since. A row with an era
@@ -270,23 +270,13 @@ export function recommendRoute(input) {
             legs.push({ phase: "plan", provider: rec.spec.provider, model: rec.spec.model, tier: rec.tier, chosen: "recommended", recommended, reasons: rec.reasons, problem: planProblem(rec.spec) });
         }
     }
-    // build — pin > override > recommendation.
+    // build — one precedence order (selectBuildLeg): pin > override > trial > earned rule > configured > headroom.
     let buildMoved = false;
     const build = (() => {
-        const rec = pick("build");
-        buildMoved = rec.moved;
-        const pin = input.pins?.build ?? null;
-        const override = overrideFor("build");
-        const recommended = { provider: rec.spec.provider, model: rec.spec.model, tier: rec.tier };
-        if (pin !== null || override !== null)
-            buildMoved = false;
-        const leg = pin !== null
-            ? { phase: "build", provider: pin.provider, model: pin.model, tier: rec.tier, chosen: "pinned", recommended, reasons: [`pinned to ${specWords(pin)} by the firing that filed this task — nothing overrides a pin`], problem: null }
-            : override !== null
-                ? { phase: "build", provider: override.provider, model: override.model, tier: rec.tier, chosen: "override", recommended, reasons: [`overridden by ${override.by} to ${specWords(override)} (recommended ${specWords(rec.spec)})`], problem: null }
-                : { phase: "build", provider: rec.spec.provider, model: rec.spec.model, tier: rec.tier, chosen: "recommended", recommended, reasons: rec.reasons, problem: null };
-        legs.push(leg);
-        return leg;
+        const chosen = selectBuildLeg(input, pickTier("build"));
+        buildMoved = chosen.moved;
+        legs.push(chosen.leg);
+        return chosen.leg;
     })();
     // repair — ALWAYS the build provider (repair resumes the builder's
     // session; cross-provider repair does not exist). Only the model routes:
@@ -383,7 +373,8 @@ export function recommendRoute(input) {
         }
     }
     return {
-        version: ROUTE_VERSION,
+        // Version 3 only for a build leg that carries a selection: every other route's bytes stay version 2's.
+        version: build.selection !== undefined ? ROUTE_VERSION : PLAIN_ROUTE_VERSION,
         risk: "routine",
         qualityMode: input.qualityMode,
         publication: input.publication,
@@ -398,6 +389,127 @@ export function recommendRoute(input) {
         size: input.size ?? null,
     };
 }
+/**
+ * THE BUILD LEG'S ONE PRECEDENCE ORDER (results routing, docs/plans/results-routing.md slice 2), pure:
+ *
+ *   pin > person override > trial > earned rule > configured row (light / routine / strong by size)
+ *   > headroom move
+ *
+ * Headroom moves only a configured leg, never a rule's or a trial's: their evidence is about one exact model. A rule
+ * or trial whose provider is past the headroom limits is skipped for this filing, and its reason says so. A trial
+ * applies only with a place reserved for this task (slice 3). A rule or trial applies only to an
+ * eligible task — small or medium, not risky, default quality, no screenshot or manual-review evidence, not a
+ * merging mode, not a release or candidate, nothing protected declared — and only over the configured builder it was
+ * earned against. Its leg says how it was selected (`selection`), so the route seals as version 3 and every later
+ * check reads the sealed selection, never the current rules or the reason text.
+ */
+export function selectBuildLeg(input, configured) {
+    const pin = input.pins?.build ?? null;
+    const override = input.overrides.find(one => one.phase === "build") ?? null;
+    if (pin !== null || override !== null) {
+        // What would have run otherwise is said as it always was: the configured leg after headroom.
+        const rec = withHeadroom(input, "build", configured);
+        const recommended = { provider: rec.spec.provider, model: rec.spec.model, tier: rec.tier };
+        const leg = pin !== null
+            ? { phase: "build", provider: pin.provider, model: pin.model, tier: rec.tier, chosen: "pinned", recommended, reasons: [`pinned to ${specWords(pin)} by the firing that filed this task — nothing overrides a pin`], problem: null }
+            : { phase: "build", provider: override.provider, model: override.model, tier: rec.tier, chosen: "override", recommended, reasons: [`overridden by ${override.by} to ${specWords(override)} (recommended ${specWords(rec.spec)})`], problem: null };
+        return { leg, moved: false };
+    }
+    const trial = trialFor(input, configured);
+    if (trial !== null && trial.kind === "trial") {
+        const one = trial.trial;
+        const spec = { provider: one.provider, model: one.model };
+        return {
+            leg: {
+                phase: "build", provider: one.provider, model: one.model, tier: configured.tier, chosen: "recommended",
+                recommended: { ...spec, tier: configured.tier },
+                reasons: [...configured.reasons.slice(0, 1), `trial: ${specWords(spec)} is being tried on this project's next ${one.limit} eligible ${one.cohortSize === "small" ? "small" : "routine"} tasks instead of the configured ${specWords({ provider: one.configured.provider, model: one.configured.model ?? "default" })}; a person approves each one`],
+                problem: null,
+                selection: { kind: "trial", rule: one.id, reservation: one.reservation },
+            },
+            moved: false,
+        };
+    }
+    const earned = earnedRuleFor(input, configured);
+    if (earned !== null && earned.kind === "rule") {
+        const rule = earned.rule;
+        const spec = { provider: rule.provider, model: rule.model };
+        return {
+            leg: {
+                phase: "build", provider: rule.provider, model: rule.model, tier: configured.tier, chosen: "recommended",
+                recommended: { ...spec, tier: configured.tier },
+                reasons: [...configured.reasons.slice(0, 1), `earned rule: ${specWords(spec)} builds this project's eligible ${rule.cohortSize === "small" ? "small" : "routine"} tasks instead of the configured ${specWords({ provider: rule.configured.provider, model: rule.configured.model ?? "default" })}, on its recorded results here`],
+                problem: null,
+                selection: { kind: "rule", rule: rule.id, ruleGeneration: rule.generation },
+            },
+            moved: false,
+        };
+    }
+    const rec = withHeadroom(input, "build", configured);
+    const reasons = [...rec.reasons, ...(trial === null ? [] : [trial.reason]), ...(earned === null ? [] : [earned.reason])];
+    return {
+        leg: { phase: "build", provider: rec.spec.provider, model: rec.spec.model, tier: rec.tier, chosen: "recommended", recommended: { provider: rec.spec.provider, model: rec.spec.model, tier: rec.tier }, reasons, problem: null },
+        moved: rec.moved,
+    };
+}
+/** The earned rule this task's build takes (pure): null when none could apply (no rule for its size, or the task
+ * isn't eligible), or a rule skipped for this filing with the words why. */
+export function earnedRuleFor(input, configured) {
+    const earned = input.earned ?? null;
+    const size = input.size ?? null;
+    if (earned === null || size === null || size.risky || (size.size !== "small" && size.size !== "medium"))
+        return null;
+    const rule = earned.rules.find(one => one.cohortSize === size.size) ?? null;
+    if (rule === null)
+        return null;
+    if (earned.release || earned.protected || input.qualityMode !== "default" || input.publication === "automerge")
+        return null;
+    if (input.evidence.some(kind => kind === "screenshot" || kind === "manual-review"))
+        return null;
+    if (demandedTier(input, "build").tier !== "routine")
+        return null;
+    // Only Claude reports the model it ran, so only a Claude cohort can earn a rule.
+    if (rule.provider !== "claude" || !exactModel(rule.model))
+        return null;
+    if (configured.spec.provider !== rule.configured.provider || configured.spec.model !== rule.configured.model) {
+        return { kind: "skipped", reason: `the earned rule for ${size.size === "small" ? "small" : "routine"} tasks was earned against another configured builder — not applied` };
+    }
+    const room = (input.headroom ?? []).find(one => one.provider === rule.provider) ?? null;
+    const tight = room === null ? null : tightWords(room);
+    if (tight !== null)
+        return { kind: "skipped", reason: `earned rule skipped for this filing: ${tight} — the configured builder runs it` };
+    return { kind: "rule", rule };
+}
+/** The trial this task's build takes (pure, results routing slice 3): null when none could apply (no live trial for
+ * its size, or the task isn't eligible: the same facts an earned rule needs), a trial with this task's place, or a
+ * trial skipped for this filing with the words why (another configured builder, no place left, no headroom). */
+export function trialFor(input, configured) {
+    const trial = input.earned?.trial ?? null;
+    const size = input.size ?? null;
+    if (trial === null || size === null || size.risky || (size.size !== "small" && size.size !== "medium") || trial.cohortSize !== size.size)
+        return null;
+    if (input.earned.release || input.earned.protected || input.qualityMode !== "default" || input.publication === "automerge")
+        return null;
+    if (input.evidence.some(kind => kind === "screenshot" || kind === "manual-review"))
+        return null;
+    if (demandedTier(input, "build").tier !== "routine")
+        return null;
+    // Only Claude reports the model it ran, so only a Claude cohort runs a trial.
+    if (trial.provider !== "claude" || !exactModel(trial.model) || !Number.isSafeInteger(trial.limit) || trial.limit < 1)
+        return null;
+    const words = size.size === "small" ? "small" : "routine";
+    if (configured.spec.provider !== trial.configured.provider || configured.spec.model !== trial.configured.model) {
+        return { kind: "skipped", reason: `the trial for ${words} tasks was started against another configured builder — not applied` };
+    }
+    const room = (input.headroom ?? []).find(one => one.provider === trial.provider) ?? null;
+    const tight = room === null ? null : tightWords(room);
+    if (tight !== null)
+        return { kind: "skipped", reason: `trial skipped for this filing: ${tight} — the configured builder runs it` };
+    if (trial.reservation === null || !Number.isSafeInteger(trial.reservation) || trial.reservation < 1) {
+        return { kind: "skipped", reason: `every place in the trial for ${words} tasks is taken — the configured builder runs it` };
+    }
+    return { kind: "trial", trial: { ...trial, reservation: trial.reservation } };
+}
 /**
  * PLAN HEADROOM (v2), at filing:
  *
@@ -494,6 +606,8 @@ export function canonicalRouteJson(route) {
             recommended: leg.recommended,
             reasons: leg.reasons,
             problem: leg.problem,
+            // v3 (results routing): the build leg's selection is in the bytes, so in the digest; v1 and v2 bytes never change.
+            ...(route.version === 3 && leg.selection !== undefined ? { selection: leg.selection } : {}),
         })),
         overrides: route.overrides.map(one => ({ phase: one.phase, provider: one.provider, model: one.model, by: one.by, at: one.at })),
         // v2 carries the size it was routed for; a v1 snapshot's bytes never change.

package/dist/project-delete.d.ts

@@ -30,6 +30,10 @@ export type ProjectDeleteResult = {
     said: string;
     running?: string[];
 };
+/** The project's Models rows, counted with its settings and deleted by forgetProjectModels only. */
+export declare const MODEL_SETTINGS: readonly [table: string, column: string][];
+/** The project's settings tables, for the deletion test's inventory. */
+export declare const PROJECT_SETTINGS: readonly [table: string, column: string][];
 /** What Toolroll holds for a project, counted. */
 export declare function projectHoldings(store: Store, repo: string): ProjectHoldings;
 /** What's in it, in words: "12 tasks, 3 versions, 30 runs, …". Empty kinds are left out. */

package/dist/project-delete.js

@@ -15,7 +15,7 @@
 import { existsSync, lstatSync, rmSync } from "node:fs";
 import { isAbsolute, relative, resolve } from "node:path";
 import { teardownGit, refusal } from "./teardown-git.js";
-import { BUILT_IN } from "./store.js";
+import { BUILT_IN, forgetProjectModels, V149_REPO_TABLES } from "./store.js";
 import { BRANCH_PREFIXES, isOwnBranch } from "./names.js";
 /** The tables whose history is the audit record itself: never touched. */
 const KEPT = new Set(["action_ledger", "ledger_seal", "ledger_checkpoint"]);
@@ -42,13 +42,19 @@ function doomed(db, repo) {
     const subagents = ids(db, "SELECT id FROM subagent WHERE repo = ?", repo);
     return { refs, tasks, runs, artifacts, threads, turns, flows, cards, subagents };
 }
-/** A project's settings: one row per thing someone set for it. */
+/** A project's settings: one row per thing someone set for it. Its Models rows (phase_config, phase_tier_config,
+ * phase_tier_alternate) are settings too, but go only through store.ts forgetProjectModels, which moves their
+ * generations and takes the project's results-routing rows with them (MODEL_SETTINGS). */
 const SETTINGS = [
     ["approval_policy", "repo"], ["verify_command", "repo"], ["worktree_setup", "repo"], ["backend_grant", "repo"], ["publication_grant", "repo"],
-    ["intake_grant", "repo"], ["capability", "repo"], ["project_tool", "repo"], ["phase_config", "scope"], ["phase_tier_config", "scope"],
+    ["intake_grant", "repo"], ["capability", "repo"], ["project_tool", "repo"],
     ["learning_policy", "repo"], ["operating_mode", "repo"], ["project_knowledge", "repo"], ["live_detail_setting", "repo"],
     ["project_decision", "repo"], ["flow_script", "repo"], ["workflow_recipe", "repo"], ["team_lead_project", "project"],
 ];
+/** The project's Models rows, counted with its settings and deleted by forgetProjectModels only. */
+export const MODEL_SETTINGS = Object.freeze([["phase_config", "scope"], ["phase_tier_config", "scope"], ["phase_tier_alternate", "scope"]]);
+/** The project's settings tables, for the deletion test's inventory. */
+export const PROJECT_SETTINGS = Object.freeze(SETTINGS.map(one => [...one]));
 /** What Toolroll holds for a project, counted. */
 export function projectHoldings(store, repo) {
     const db = store.handle;
@@ -61,7 +67,7 @@ export function projectHoldings(store, repo) {
         checkouts: count("SELECT COUNT(*) AS n FROM worktree WHERE repo = ?", repo),
         chats: d.threads.length, flows: d.flows.length, cards: d.cards.length, subagents: d.subagents.length,
         budgets: count(`SELECT COUNT(*) AS n FROM budget WHERE removed_at IS NULL AND ((scope_kind = 'project' AND scope_key = ?) OR (scope_kind = 'subagent' AND scope_key IN (SELECT CAST(value AS TEXT) FROM json_each(?))))`, repo, json(d.subagents)),
-        settings: SETTINGS.filter(([table]) => tableExists(db, table)).reduce((sum, [table, column]) => sum + count(`SELECT COUNT(*) AS n FROM ${table} WHERE ${column} = ?`, repo), 0),
+        settings: [...SETTINGS, ...MODEL_SETTINGS].filter(([table]) => tableExists(db, table)).reduce((sum, [table, column]) => sum + count(`SELECT COUNT(*) AS n FROM ${table} WHERE ${column} = ?`, repo), 0),
     };
 }
 /** What's in it, in words: "12 tasks, 3 versions, 30 runs, …". Empty kinds are left out. */
@@ -312,9 +318,15 @@ function deleteRows(store, repo, d, now) {
     // Settings, knowledge and the project itself.
     del("operating_mode_event", "mode IN (SELECT id FROM operating_mode WHERE repo = ?)", repo);
     del("decision_change", "decision IN (SELECT id FROM project_decision WHERE repo = ?)", repo);
+    // Its learning-loops rows (v149), by repo; a check's results, a note's tallies and a merge of its decisions go with
+    // the rows they hang off (the deleted runs, notes and decisions), below.
+    for (const table of V149_REPO_TABLES)
+        del(table, "repo = ?", repo);
     del("memory_sighting", "gap IN (SELECT id FROM memory_gap WHERE repo = ?) OR session IN (SELECT id FROM memory_session WHERE repo = ?)", repo, repo);
     for (const [table, column] of SETTINGS)
         del(table, `${column} = ?`, repo);
+    // Its Models rows and results-routing rows: through the Models counter, so whatever depended on them pauses.
+    rows += forgetProjectModels(store, repo, now);
     del("project_mute", "repo = ?", repo);
     for (const table of ["knowledge_change", "project_identity_carry", "project_skill_change", "memory_gap", "memory_proposal", "memory_rejection", "memory_session", "memory_search", "mode_rail", "side_spend", "watch_episode", "worktree", "coordinator_proposal", "lead_commitment"])
         del(table, "repo = ?", repo);

package/dist/project-memory.d.ts

@@ -7,6 +7,14 @@ export declare function listDecisions(store: Store, repo: string, actor: string,
     limit?: number;
 }): Decision[];
 export declare function getDecision(store: Store, repo: string, actor: string, id: number): Decision | null;
+/**
+ * Project memory is changed by a person (like `knowledge apply`, project-knowledge.ts applySavedKnowledge): never in the
+ * lead's chain and never inside a remote run (an API token), whatever credential reached here. The lead proposes (chat
+ * cards decision_record/decision_retire) and a person confirms. Every writer here and in memory-pass.ts calls this first,
+ * and again inside its transaction beside the person's standing (`admission`), so a revocation made since the caller
+ * proved them is seen by the write.
+ */
+export declare function refuseLeadMemoryWrite(): void;
 /** Record one settled choice. A superseding decision retires the older one in the same transaction. */
 export declare function recordDecision(store: Store, args: {
     repo: string;

package/dist/project-memory.js

@@ -8,6 +8,8 @@
  * model; the backward pass that proposes edits lives in memory-pass.ts.
  */
 import { createHash } from 'node:crypto';
+import { currentActor } from './actor.js';
+import { activeRemote } from './remote-run.js';
 import { scanForSecrets } from './evidence.js';
 import { learningIdentity } from './project-learning.js';
 import { TEXT_LIMITS } from './text-limits.js';
@@ -112,8 +114,22 @@ export function getDecision(store, repo, actor, id) {
         throw Error('This decision could not be verified.');
     return d;
 }
+/**
+ * Project memory is changed by a person (like `knowledge apply`, project-knowledge.ts applySavedKnowledge): never in the
+ * lead's chain and never inside a remote run (an API token), whatever credential reached here. The lead proposes (chat
+ * cards decision_record/decision_retire) and a person confirms. Every writer here and in memory-pass.ts calls this first,
+ * and again inside its transaction beside the person's standing (`admission`), so a revocation made since the caller
+ * proved them is seen by the write.
+ */
+export function refuseLeadMemoryWrite() {
+    if (currentActor()?.lead === true)
+        throw Error('Project memory is changed by a person, not the lead.');
+    if (activeRemote() !== null)
+        throw Error('Project memory is changed by a person with their own password, not an API token.');
+}
 /** Record one settled choice. A superseding decision retires the older one in the same transaction. */
 export function recordDecision(store, args, now = new Date()) {
+    refuseLeadMemoryWrite();
     const identity = admission(store, args.repo, args.actor, true);
     const claim = clean(args.draft.claim, TEXT_LIMITS.decisionClaimBytes, 'The decision'), why = clean(args.draft.why, TEXT_LIMITS.decisionWhyBytes, 'The reason');
     const decidedBy = args.draft.decidedBy === undefined ? args.actor : clean(args.draft.decidedBy, TEXT_LIMITS.decisionByBytes, 'Who decided');
@@ -123,6 +139,8 @@ export function recordDecision(store, args, now = new Date()) {
     const sourceKind = args.draft.sourceKind ?? 'manual';
     const sourceRef = args.draft.sourceRef === undefined || args.draft.sourceRef === null ? null : clean(String(args.draft.sourceRef), TEXT_LIMITS.decisionSourceBytes, 'The source');
     return store.transact(() => {
+        refuseLeadMemoryWrite();
+        admission(store, args.repo, args.actor, true);
         let supersedes = null;
         if (args.draft.supersedes !== undefined && args.draft.supersedes !== null) {
             const older = getDecision(store, args.repo, args.actor, Number(args.draft.supersedes));
@@ -155,9 +173,10 @@ function changeStatus(store, repo, actor, id, status, reason, now) {
 }
 /** Retire a decision that no longer holds; history keeps it. */
 export function retireDecision(store, args, now = new Date()) {
+    refuseLeadMemoryWrite();
     admission(store, args.repo, args.actor, true);
     const reason = clean(args.reason, TEXT_LIMITS.decisionRetireBytes, 'The reason');
-    return store.transact(() => { const d = changeStatus(store, args.repo, args.actor, args.id, 'retired', reason, now); reindexProjectMemory(store, args.repo); return d; });
+    return store.transact(() => { refuseLeadMemoryWrite(); admission(store, args.repo, args.actor, true); const d = changeStatus(store, args.repo, args.actor, args.id, 'retired', reason, now); reindexProjectMemory(store, args.repo); return d; });
 }
 export function decisionHistory(store, repo, actor, id) {
     admission(store, repo, actor);

package/dist/pull-request-flow.js

@@ -319,7 +319,7 @@ export async function followPullRequests(store, seen, options) {
             const filed = store.transact(() => {
                 const revised = requestResultChanges(store, options.evidenceRoot, {
                     run: publication.run, batch: "", source: revisionSourceOf(scope?.digest ?? null), actor: CI_ACTOR, repos: null, includeUnplaced: true,
-                    allowMode: false, note, path: "", line: "", request,
+                    allowMode: false, note, path: "", line: "", request, origin: "flow",
                 }, now);
                 if (!revised.ok)
                     return revised;

package/dist/push.d.ts

@@ -61,14 +61,21 @@ export declare function validatePushEndpoint(raw: string): {
     ok: false;
     problem: string;
 };
+/** A push's class: a stored class, or `release`, which is never stored: it is derived at send time from the plane's own
+ * state (release-approval.ts releasePushOf), never from a title, a task id or a link. */
+export type PushClass = NonNullable<Notification["pushClass"]> | "release";
 /** Fixed words, except for one validated machine-only suite/count line. */
-export declare const PUSH_WORDS: Record<NonNullable<Notification["pushClass"]>, {
+export declare const PUSH_WORDS: Record<PushClass, {
     title: string;
     body: string;
 }>;
 /** Static words and machine-minted numbers only — re-proved at send time. */
-export declare function safePushLink(pushClass: NonNullable<Notification["pushClass"]>, link: string | null): string;
-export declare function buildPushPayload(notification: Notification, waiting?: number | null): string;
+export declare function safePushLink(pushClass: PushClass, link: string | null): string;
+/** `release`: the class and link the plane derived for this row at send time (releasePushOf); absent or null, the
+ * row's stored class and link, revalidated. */
+export declare function buildPushPayload(notification: Notification, waiting?: number | null, release?: {
+    link: string;
+} | null): string;
 export type PushFetch = (url: string, init: Record<string, unknown>) => Promise<{
     status: number;
     headers: {

package/dist/push.js

@@ -20,6 +20,7 @@ import { closeSync, constants as fsConstants, fsyncSync, openSync, readFileSync,
 import { join } from "node:path";
 import { createCipheriv, createECDH, createPrivateKey, hkdfSync, randomBytes, createHash, sign as cryptoSign } from "node:crypto";
 import { isCheckProgressLine } from "./check-progress.js";
+import { RELEASE_PUSH_WORDS, releasePushOf, releaseReadyObsolete } from "./release-approval.js";
 export const VAPID_FILE = "vapid-keys.json";
 /** RFC 8291 §4: rs 4096 leaves room for the record's delimiter and tag. */
 const RECORD_SIZE = 4096;
@@ -193,7 +194,6 @@ export function validatePushEndpoint(raw) {
         return { ok: false, problem: "that host is not a known push service — extending the list is a code change, deliberately" };
     return { ok: true, url };
 }
-// ---- the payload ------------------------------------------------------------
 /** Fixed words, except for one validated machine-only suite/count line. */
 export const PUSH_WORDS = {
     decision: { title: "Toolroll", body: "a decision needs you" },
@@ -201,28 +201,37 @@ export const PUSH_WORDS = {
     merge: { title: "Toolroll", body: "a pull request needs a person" },
     attention: { title: "Toolroll", body: "the plane needs attention" },
     progress: { title: "Toolroll", body: "checks in progress" },
+    release: { title: "Toolroll", body: RELEASE_PUSH_WORDS },
 };
-const LINK_SHAPES = [/^\/next$/, /^\/review$/, /^\/system$/, /^\/routines$/, /^\/routines\/[0-9]{1,15}$/, /^\/d\/[0-9]{1,15}$/, /^\/r\/[0-9]{1,15}$/];
+// `/approve/<n>`: a release's opaque locator (a task ref number: no version, commit or branch), resolved by the console.
+const RELEASE_LINK = /^\/approve\/[0-9]{1,15}$/;
+const LINK_SHAPES = [/^\/next$/, /^\/review$/, /^\/system$/, /^\/routines$/, /^\/routines\/[0-9]{1,15}$/, /^\/d\/[0-9]{1,15}$/, /^\/r\/[0-9]{1,15}$/, RELEASE_LINK];
 const CLASS_FALLBACK = {
     decision: "/next",
     pick: "/next",
     merge: "/review",
     attention: "/next",
     progress: "/next",
+    release: "/next",
 };
 /** Static words and machine-minted numbers only — re-proved at send time. */
 export function safePushLink(pushClass, link) {
+    // The release locator rides only the derived `release` class: a stored link of that shape on any other row is not one.
+    if (link !== null && RELEASE_LINK.test(link))
+        return pushClass === "release" ? link : CLASS_FALLBACK[pushClass];
     if (link !== null && LINK_SHAPES.some(shape => shape.test(link)))
         return link;
     return CLASS_FALLBACK[pushClass];
 }
-export function buildPushPayload(notification, waiting = null) {
-    const pushClass = notification.pushClass;
+/** `release`: the class and link the plane derived for this row at send time (releasePushOf); absent or null, the
+ * row's stored class and link, revalidated. */
+export function buildPushPayload(notification, waiting = null, release = null) {
+    const pushClass = release !== null ? "release" : notification.pushClass;
     const words = PUSH_WORDS[pushClass];
     return JSON.stringify({
         title: words.title,
         body: pushClass === "progress" && isCheckProgressLine(notification.body) ? notification.body : words.body,
-        url: safePushLink(pushClass, notification.link),
+        url: safePushLink(pushClass, release !== null ? release.link : notification.link),
         // The opaque tag collapses a crash-duplicate on the lock screen.
         tag: pushClass === "progress" && notification.run !== null ? `so-run-${notification.run}` : `so-${notification.id}`,
         // The app-icon badge (Phase 2E, v2 S4): the server-computed
@@ -268,6 +277,13 @@ export async function pushPass(store, options) {
         if (fenced === null)
             continue; // resolved, retired, rotated, or lost — nothing to send
         const subscription = fenced.subscriptionRow;
+        // A release's "ready for your approval" that no longer stands (approved, superseded, put away) is resolved, never
+        // sent; one that stands is sent as `release`, its class and link derived from the plane's state now.
+        if (releaseReadyObsolete(store, fenced.notificationRow)) {
+            store.handle.prepare("UPDATE notification SET resolved_at = ? WHERE id = ? AND resolved_at IS NULL").run(clock().toISOString(), fenced.notificationRow.id);
+            continue;
+        }
+        const release = releasePushOf(store, fenced.notificationRow);
         const endpoint = validatePushEndpoint(subscription.endpoint);
         if (!endpoint.ok) {
             store.retirePushSubscription(subscription.id, "invalid-endpoint", clock());
@@ -280,7 +296,7 @@ export async function pushPass(store, options) {
             // The badge count rides every push: the same inbox classifier the
             // console's own sidebar badge reads, unscoped (a phone has no
             // project pane), computed at send time.
-            buildPushPayload(fenced.notificationRow, store.countInboxScoped(null, clock(), 100, null).count));
+            buildPushPayload(fenced.notificationRow, store.countInboxScoped(null, clock(), 100, null).count, release));
         }
         catch {
             // Off-curve or malformed subscriber material: the device, not us.

package/dist/release-adapters.js

@@ -31,6 +31,8 @@ import { randomBytes, randomUUID } from "node:crypto";
 import { deploymentGate } from "./deploy-gate.js";
 import { failedBeforeTests } from "./github-jobs.js";
 import { mainHistoryOf, nightlyBoundary } from "./nightly-github.js";
+import { noteReleaseReady, noteReleaseStopped, recordReleaseCi } from "./release-approval.js";
+import { recordVerifiedRelease } from "./release-card.js";
 export { failedBeforeTests } from "./github-jobs.js";
 import { extractCommit } from "./commit-extract.js";
 import { teardownGit, refusal as gitRefusal } from "./teardown-git.js";
@@ -529,7 +531,7 @@ export function releaseAdapters(options) {
             },
             async complete(taskId, receipt) {
                 const answer = await toolroll("task", "complete", taskId, "--digest", receipt);
-                return answer["ok"] === true ? { ok: true } : { ok: false, message: refused(answer) };
+                return answer["ok"] === true ? { ok: true } : { ok: false, message: refused(answer), ...(typeof answer["reason"] === "string" ? { reason: answer["reason"] } : {}) };
             },
             async busy() {
                 const db = new (sqlite().DatabaseSync)(database, { readOnly: true });
@@ -971,6 +973,14 @@ nightlyReads) {
     } };
     return {
         ...(auto === undefined ? {} : { auto: autoReleaseAdapter(withStore, now, auto) }),
+        // One-tap release approval (trusted-release-reports.md, slice A): ids and the coordinator's own readings only; the
+        // plane decides from its own records whether anything is written.
+        ready: {
+            async asked(taskId) { withStore(store => { noteReleaseReady(store, { taskId, now: now() }); }); },
+            async ci(input) { withStore(store => { recordReleaseCi(store, { ...input, now: now() }); }); },
+            async stopped(input) { withStore(store => { noteReleaseStopped(store, { ...input, now: now() }); }); },
+            async verified(input) { withStore(store => { recordVerifiedRelease(store, { ...input, now: now() }); }); },
+        },
         // After a failed release check, and before a pass is taken: the plane's own classification (check-failure.ts).
         ...(auto === undefined ? {} : {
             async recheck(taskId) {