toolroll 0.9.41 → 0.9.43

package/dist/mate-tools.js

@@ -48,7 +48,9 @@ import { TOOL_CATALOG, discoverTools, projectToolsOf, secretsSetFor, toolCommand
 import { deciderOf, durationWords, FLOW_KIND_WORDS, FLOW_TEMPLATES, flowFromSteps, stepsFor, withKeptSteps } from "./flows.js";
 import { parseContract, toModelSchema } from "./contracts/contract.js";
 import { LEAD_TOOL_INPUTS, LEAD_TOOL_READ_INPUTS, LEAD_TOOL_OPTIONS, LEAD_TOOL_OUTPUTS, reportToolOutput } from "./contracts/lead-tools.js";
-import { flowDefinitionOf } from "./flow-engine.js";
+import { flowCardHref, flowDefinitionOf } from "./flow-engine.js";
+import { planInChat } from "./chat-decide.js";
+import { flowDecisionAt } from "./telegram-flow.js";
 import { flowPersonOf } from "./flow-send.js";
 import { flowInsights } from "./flow-insights.js";
 import { describeTrigger, FLOW_TRIGGER_KINDS, triggerConfigOf } from "./flow-triggers.js";
@@ -491,6 +493,46 @@ const MATE_TOOL_HANDLERS = {
             return id === null ? tooMany() : { ok: true, body: { card: id, label: entry.label, action: "open existing control; nothing changed" } };
         },
     },
+    offer_approval: {
+        description: "When the owner asks to approve one thing (a plan waiting on them, or a flow card waiting at a Person decides step), send that item's own Approve and Send back buttons to their paired chat right away. Their tap there is the approval (two taps, as on any decision card); you never approve. Give task for a plan, or card for a flow card (its number from get_flows). When it can't be approved in chat, the answer says why: say that in one line and open show_control approval (a plan) or the flow, never that you can't approve.",
+        handle: (ctx, args) => {
+            const pairedHere = ctx.channel === "telegram";
+            const paired = ctx.store.handle.prepare("SELECT 1 FROM telegram_binding WHERE approver = ? AND approver_generation = ? AND revoked_at IS NULL LIMIT 1")
+                .get(ctx.who.name, ctx.store.accountOf(ctx.who.name)?.generation ?? -1) !== undefined;
+            const stamp = ctx.now.getTime();
+            if (args["card"] !== undefined) {
+                const cardId = Number(args["card"]);
+                const card = Number.isSafeInteger(cardId) ? ctx.store.getFlowCard(cardId) : null;
+                const flow = card === null ? null : ctx.store.getFlow(card.flow);
+                if (card === null || flow === null || !ctx.who.repos.includes(flow.repo))
+                    return { ok: false, message: "not-found: no such flow card in your projects" };
+                const waiting = flowDecisionAt(ctx.store, card.id, card.entry);
+                const href = flowCardHref(flow.id, card.id);
+                if (waiting === null)
+                    return { ok: true, body: { offered: false, why: card.state === "active" ? "That card isn't waiting for a decision now." : "That card isn't waiting any more.", open: href } };
+                const decider = deciderOf(waiting.stage, waiting.flow);
+                if (decider !== null && decider !== ctx.who.name)
+                    return { ok: true, body: { offered: false, why: `Only ${decider} decides here.`, open: href } };
+                if (!pairedHere || !paired)
+                    return { ok: true, body: { offered: false, why: pairedHere ? "Your chat isn't paired for decisions." : "Buttons go to your paired chat; here, approve it on the card.", open: href } };
+                ctx.store.enqueueNotification({ dedupeKey: `flow-decide:${card.id}:${card.entry}:ask:${stamp}`, kind: "flow-decision", pushClass: "attention", recipient: ctx.who.name,
+                    subject: `${flow.name}: ${card.title} needs your decision`.slice(0, 200), body: `${waiting.stage.title}: approve it, or send it back with a note.`, link: href, source: { project: flow.repo } }, ctx.now);
+                return { ok: true, body: { offered: true, item: `flow card ${card.id}`, shown: "Approve and Send back buttons follow your reply in this chat; the owner's tap decides it" } };
+            }
+            const task = taskIdOf(args);
+            if (task === null || admittedRef(ctx, task) === null)
+                return notFound();
+            const current = ctx.store.taskFamilyOf(task, ctx.who.repos, false)?.current.id ?? task;
+            const plan = planInChat(ctx.store, current, ctx.who.name, ctx.now, ctx.evidenceRoot);
+            if (!plan.ok)
+                return { ok: true, body: { offered: false, task: current, why: plan.why, control: "approval" } };
+            if (!pairedHere || !paired)
+                return { ok: true, body: { offered: false, task: current, why: pairedHere ? "Your chat isn't paired for decisions." : "Buttons go to your paired chat; here, approve it on its card.", control: "approval" } };
+            ctx.store.enqueueNotification({ dedupeKey: `plan-ready:${current}:ask:${stamp}`, kind: "plan-ready", recipient: ctx.who.name, subject: `${current}: plan ready for review`,
+                body: "Approve it here, or open it to edit first.", source: { taskRef: ctx.store.lookupRef(current).id } }, ctx.now);
+            return { ok: true, body: { offered: true, item: `plan for ${current}`, task: current, shown: "Approve & start follows your reply in this chat; the owner's two taps approve it" } };
+        },
+    },
     get_result: {
         description: "Read exact execution/run and feedback. Use get_task currentExecution; page nextFeedbackOffset.",
         handle: (ctx, args) => {

package/dist/mcp-connect.js

@@ -16,6 +16,7 @@ import { homedir } from "node:os";
 import { basename } from "node:path";
 import { LOCAL_APPS, addToolTo, catalogTool, localAppOf, projectToolsOf, readToolSecrets, setToolSecrets, testToolOf } from "./project-tools.js";
 import { envValue } from "./names.js";
+import { SCOPE_TOKEN, readAuthorizationServer, readProtectedResource, readRegistration, readTokenResponse } from "./contracts/integration-metadata.js";
 /**
  * Services that connect this way: their servers speak streamable HTTP and
  * advertise registering clients on the spot. Advertising isn't accepting:
@@ -202,8 +203,7 @@ const GRANTED = "OAUTH_GRANTED_SCOPE";
 export const CONNECT_CALLBACK = "/settings/tools/connected";
 const VISIT_MS = 15 * 60_000, RENEW_RETRY_MS = 5 * 60_000;
 const renewTried = new Map();
-/** RFC 6749 scope tokens; and the most scope text a sign-in address carries (addresses stay well under 8 KB). */
-const SCOPE_TOKEN = /^[\x21\x23-\x5b\x5d-\x7e]{1,128}$/;
+/** The most scope text a sign-in address carries (addresses stay well under 8 KB). */
 const SCOPE_PARAM_LIMIT = 6_000;
 const json = async (fetcher, url) => {
     try {
@@ -238,25 +238,29 @@ export async function discoverSignIn(mcpUrl, fetcher = fetch) {
     catch {
         pointer = null;
     }
-    const resource = (pointer !== null && https(pointer) ? await json(fetcher, pointer) : null)
+    const found = (pointer !== null && https(pointer) ? await json(fetcher, pointer) : null)
         ?? await json(fetcher, `${mcp.origin}/.well-known/oauth-protected-resource${mcp.pathname === "/" ? "" : mcp.pathname}`)
         ?? await json(fetcher, `${mcp.origin}/.well-known/oauth-protected-resource`);
-    const issuers = Array.isArray(resource?.["authorization_servers"]) ? resource["authorization_servers"].filter(https) : [];
+    const resource = found === null ? {} : readProtectedResource(found);
+    const issuers = (resource.authorization_servers ?? []).filter(https);
     const issuer = new URL(issuers[0] ?? mcp.origin);
     const path = issuer.pathname === "/" ? "" : issuer.pathname.replace(/\/$/, "");
-    const meta = await json(fetcher, `${issuer.origin}/.well-known/oauth-authorization-server${path}`)
+    const answered = await json(fetcher, `${issuer.origin}/.well-known/oauth-authorization-server${path}`)
         ?? await json(fetcher, `${issuer.origin}/.well-known/oauth-authorization-server`)
         ?? (path === "" ? null : await json(fetcher, `${issuer.origin}${path}/.well-known/openid-configuration`))
         ?? await json(fetcher, `${issuer.origin}/.well-known/openid-configuration`);
-    if (meta === null || !https(meta["authorization_endpoint"]) || !https(meta["token_endpoint"]) || !https(meta["registration_endpoint"]))
+    if (answered === null)
         return null;
-    const methods = Array.isArray(meta["code_challenge_methods_supported"]) ? meta["code_challenge_methods_supported"] : ["S256"];
-    if (!methods.includes("S256"))
+    const meta = readAuthorizationServer(answered);
+    const { authorization_endpoint: authorize, token_endpoint: token, registration_endpoint: register } = meta;
+    if (!https(authorize) || !https(token) || !https(register))
+        return null;
+    if (!(meta.code_challenge_methods_supported ?? ["S256"]).includes("S256"))
         return null;
     // Ask for every scope the server lists for this resource: a token missing one the server itself requires is
     // refused after a successful sign-in (PostHog lists 155 and needs user:read, the 140th). Only well-formed scope
     // tokens, and at most what fits a sign-in address.
-    const listed = Array.isArray(resource?.["scopes_supported"]) ? resource["scopes_supported"].filter((one) => typeof one === "string" && SCOPE_TOKEN.test(one)) : [];
+    const listed = resource.scopes_supported ?? [];
     const scopes = [];
     for (const one of listed) {
         if (scopes.join(" ").length + one.length + 1 > SCOPE_PARAM_LIMIT)
@@ -264,8 +268,8 @@ export async function discoverSignIn(mcpUrl, fetcher = fetch) {
         scopes.push(one);
     }
     // A token is for the resource the server names (Stripe's has no trailing slash), when it names one.
-    const named = resource?.["resource"];
-    return { authorize: meta["authorization_endpoint"], token: meta["token_endpoint"], register: meta["registration_endpoint"], scopes, resource: https(named) ? named : null };
+    const named = resource.resource;
+    return { authorize, token, register, scopes, resource: https(named) ? named : null };
 }
 /**
  * Start connecting a service: find its sign-in, register this console as a
@@ -287,11 +291,14 @@ export async function startConnect(input, fetcher = fetch, now = Date.now()) {
         // Figma's answer (Oct 2026): it registers only apps it has approved. Said before reading a body that may not be JSON.
         if (registered.status === 401 || registered.status === 403)
             return { ok: false, said: `${service.label} doesn't let other apps sign in this way yet.${INSTEAD[service.id] === undefined ? "" : ` ${INSTEAD[service.id]}`}` };
-        const body = await registered.json();
-        if (!registered.ok || typeof body.client_id !== "string")
+        const body = readRegistration(await registered.json());
+        // A `null` answer that says it registered is no answer, as it always read.
+        if (registered.ok && body === null)
+            return { ok: false, said: `${service.label} couldn't be reached.` };
+        if (!registered.ok || body?.client_id === undefined)
             return { ok: false, said: `${service.label} didn't let Toolroll register (HTTP ${registered.status}).` };
         clientId = body.client_id;
-        clientSecret = typeof body.client_secret === "string" ? body.client_secret : null;
+        clientSecret = body.client_secret ?? null;
     }
     catch {
         return { ok: false, said: `${service.label} couldn't be reached.` };
@@ -327,9 +334,9 @@ export function connectedSpec(serviceId) {
         secrets: [ACCESS, REFRESH, CLIENT, CLIENT_SECRET, TOKEN_URL, EXPIRES, RESOURCE].map(name => ({ name, optional: name !== ACCESS })), about: `${service.label}: ${service.about} Connected by signing in.` };
 }
 const tokensFrom = (body, now) => ({
-    access: typeof body["access_token"] === "string" ? body["access_token"] : null,
-    refresh: typeof body["refresh_token"] === "string" ? body["refresh_token"] : null,
-    expires: typeof body["expires_in"] === "number" && body["expires_in"] > 0 ? new Date(now + body["expires_in"] * 1000).toISOString() : null,
+    access: body.access_token ?? null,
+    refresh: body.refresh_token ?? null,
+    expires: body.expires_in === undefined ? null : new Date(now + body.expires_in * 1000).toISOString(),
 });
 /**
  * Finish connecting: trade the code for tokens, add the tool to the project
@@ -347,9 +354,13 @@ export async function finishConnect(store, visit, code, now, options = {}) {
     try {
         const answer = await fetcher(visit.token, { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" }, signal: AbortSignal.timeout(15_000),
             body: new URLSearchParams({ grant_type: "authorization_code", code, redirect_uri: visit.redirect, client_id: visit.clientId, code_verifier: visit.verifier, resource: visit.resource, ...(visit.clientSecret === null ? {} : { client_secret: visit.clientSecret }) }) });
-        body = await answer.json();
+        const read = readTokenResponse(await answer.json());
+        // An answer of `null` reads as none, like one that isn't JSON.
+        if (read === null)
+            return { ok: false, said: `${service.label} couldn't be reached to finish the sign-in.` };
+        body = read;
         if (!answer.ok)
-            return { ok: false, said: `${service.label} didn't finish the sign-in (${typeof body["error"] === "string" ? body["error"] : `HTTP ${answer.status}`}).` };
+            return { ok: false, said: `${service.label} didn't finish the sign-in (${body.error ?? `HTTP ${answer.status}`}).` };
     }
     catch {
         return { ok: false, said: `${service.label} couldn't be reached to finish the sign-in.` };
@@ -363,7 +374,7 @@ export async function finishConnect(store, visit, code, now, options = {}) {
             return { ok: false, said: added.message };
     }
     // The grant: what the answer says, or what was asked for when it says nothing; never one from an earlier sign-in.
-    const granted = "scope" in body ? scopeList(body["scope"]) : scopeList(visit.scope ?? null);
+    const granted = body.scopeSaid ? scopeList(body.scope) : scopeList(visit.scope ?? null);
     setToolSecrets(visit.repo, spec.name, { [ACCESS]: tokens.access, [CLIENT]: visit.clientId, [TOKEN_URL]: visit.token, [RESOURCE]: visit.resource, [GRANTED]: granted?.join(" ") ?? "",
         ...(tokens.refresh === null ? {} : { [REFRESH]: tokens.refresh }), ...(tokens.expires === null ? {} : { [EXPIRES]: tokens.expires }), ...(visit.clientSecret === null ? {} : { [CLIENT_SECRET]: visit.clientSecret }) }, home);
     // The success line names the project it went to: the page and chat may be looking at another.
@@ -394,7 +405,11 @@ export async function refreshConnections(store, repos, now, options = {}) {
             try {
                 const answer = await fetcher(values[TOKEN_URL], { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" }, signal: AbortSignal.timeout(15_000),
                     body: new URLSearchParams({ grant_type: "refresh_token", refresh_token: values[REFRESH], client_id: values[CLIENT], ...(values[CLIENT_SECRET] === undefined ? {} : { client_secret: values[CLIENT_SECRET] }), ...(values[RESOURCE] === undefined ? {} : { resource: values[RESOURCE] }) }) });
-                const body = await answer.json();
+                const body = readTokenResponse(await answer.json());
+                if (body === null) {
+                    report.problems.push(`${tool.name}: couldn't reach it to renew its sign-in`);
+                    continue;
+                }
                 const tokens = tokensFrom(body, now.getTime());
                 if (!answer.ok || tokens.access === null) {
                     report.problems.push(`${tool.name}: its sign-in ran out; connect it again on the Tools page`);
@@ -402,7 +417,7 @@ export async function refreshConnections(store, repos, now, options = {}) {
                 }
                 // A refresh carries the same grant or a narrower one, and says so when it changes; said badly, it is unknown.
                 setToolSecrets(repo, tool.name, { [ACCESS]: tokens.access, ...(tokens.refresh === null ? {} : { [REFRESH]: tokens.refresh }), ...(tokens.expires === null ? {} : { [EXPIRES]: tokens.expires }),
-                    ...("scope" in body ? { [GRANTED]: scopeList(body["scope"])?.join(" ") ?? "" } : {}) }, home);
+                    ...(body.scopeSaid ? { [GRANTED]: scopeList(body.scope)?.join(" ") ?? "" } : {}) }, home);
                 renewTried.delete(key);
                 report.refreshed++;
             }

package/dist/model-catalog.js

@@ -11,6 +11,7 @@ import { accessSync, constants, lstatSync, readFileSync, realpathSync } from "no
 import { homedir } from "node:os";
 import { delimiter, join } from "node:path";
 import { fetchOpenRouterModels } from "./openrouter-models.js";
+import { codexModelSchema, codexModelsCacheSchema, npmLatestSchema } from "./contracts/model-catalog.js";
 import { readCappedBody } from "./converse.js";
 import { validModelId } from "./provider.js";
 import { activeUpdateWork } from "./desktop-update-gate.js";
@@ -73,10 +74,11 @@ export function codexCatalog(home = homedir()) {
         const path = join(home, ".codex", "models_cache.json");
         if (lstatSync(path).size >= 2_000_000)
             return [];
-        const data = JSON.parse(readFileSync(path, "utf8"));
-        return (Array.isArray(data.models) ? data.models : [])
-            .filter(one => one != null && one.visibility === "list" && typeof one.slug === "string" && validModelId(one.slug))
-            .slice(0, 30).map(one => ({ id: one.slug, name: typeof one.display_name === "string" ? one.display_name.slice(0, 80) : one.slug }));
+        const data = codexModelsCacheSchema.safeParse(JSON.parse(readFileSync(path, "utf8")));
+        return (data.success ? data.data.models : []).flatMap(entry => {
+            const one = codexModelSchema.safeParse(entry);
+            return one.success ? [one.data] : [];
+        }).slice(0, 30).map(one => ({ id: one.slug, name: typeof one.display_name === "string" ? one.display_name.slice(0, 80) : one.slug }));
     }
     catch {
         return [];
@@ -255,8 +257,8 @@ async function latestVersion(pkg, fetcher) {
         const body = await readCappedBody(response, 2_000_000);
         if (body === null)
             return null;
-        const version = JSON.parse(new TextDecoder().decode(body)).version;
-        return typeof version === "string" && /^\d+\.\d+\.\d+/.test(version) ? version : null;
+        const latest = npmLatestSchema.safeParse(JSON.parse(new TextDecoder().decode(body)));
+        return latest.success ? latest.data.version : null;
     }
     catch {
         return null;

package/dist/observations.d.ts

@@ -1,5 +1,6 @@
 import type { Runner } from "./builder.js";
 import type { Store } from "./store.js";
+import { type ObservationCase } from "./contracts/observation-request.js";
 export declare const OBSERVATION_MAILBOX = "STANDING-ORDERS-OBSERVATIONS.json";
 export declare const OBSERVATION_CAPTURE = "machine focused observations v1";
 export declare const OBSERVATION_FILE = "REVIEW-OBSERVATIONS.json";
@@ -18,12 +19,7 @@ export type ObservationBrief = {
     gateDigest: string;
 };
 export declare function focusedTestCommandSupported(command: string): boolean;
-export type ObservationCase = {
-    criterion: string;
-    at: "base" | "head";
-    testPath: string;
-    testName: string;
-};
+export type { ObservationCase };
 export declare function originalTaskBase(store: Store, taskId: string): string | null;
 /** The existing sealed revision brief identifies this narrower kind of work.
  * A title, agent-authored mailbox, or handoff can never elect gate reuse. */

package/dist/observations.js

@@ -6,6 +6,7 @@ import { dirname, join } from "node:path";
 import { stripVTControlCharacters } from "node:util";
 import { canonicalAcceptance } from "./scope.js";
 import { readVerifiedArtifact, scanForSecrets, storeEvidence } from "./evidence.js";
+import { readObservationRequest } from "./contracts/observation-request.js";
 export const OBSERVATION_MAILBOX = "STANDING-ORDERS-OBSERVATIONS.json";
 export const OBSERVATION_CAPTURE = "machine focused observations v1";
 export const OBSERVATION_FILE = "REVIEW-OBSERVATIONS.json";
@@ -62,17 +63,20 @@ export function parseObservationCases(raw, ids) {
     if (Buffer.byteLength(raw) > 16 * 1024)
         throw Error("The observation request is too large.");
     const parsed = JSON.parse(raw);
-    if (parsed?.version !== 1 || !Array.isArray(parsed.observations) || parsed.observations.length < 1 || parsed.observations.length > 4 ||
-        Object.keys(parsed).some(k => k !== "version" && k !== "observations"))
+    const read = readObservationRequest(parsed);
+    // A problem inside one observation is that observation's; anything else is the request's shape.
+    if (!read.ok && read.issues.some(issue => !/^observations\[\d+\]/.test(issue.path)))
         throw Error("Use one to four focused test observations.");
-    const cases = parsed.observations;
-    for (const item of cases) {
-        if (!item || Object.keys(item).some(k => !["criterion", "at", "testPath", "testName"].includes(k)) || !ids.includes(item.criterion) ||
-            !["base", "head"].includes(item.at) || !pathOkay(item.testPath) || !/\.(test|spec)\.[cm]?[jt]sx?$/.test(item.testPath) ||
-            typeof item.testName !== "string" || item.testName.trim() === "" || item.testName.length > 500 || /[\u0000-\u001f\u007f]/.test(item.testName)) {
-            throw Error("An observation must name a requested criterion, base/head, one test file and one test name. Shell commands are not accepted.");
-        }
+    const bad = () => Error("An observation must name a requested criterion, base/head, one test file and one test name. Shell commands are not accepted.");
+    if (!read.ok)
+        throw bad();
+    for (const item of read.value.observations) {
+        if (!ids.includes(item.criterion) || !pathOkay(item.testPath) || !/\.(test|spec)\.[cm]?[jt]sx?$/.test(item.testPath) ||
+            item.testName.trim() === "" || item.testName.length > 500 || /[\u0000-\u001f\u007f]/.test(item.testName))
+            throw bad();
     }
+    // The cases as written: their key order is the receipt's, and two written in different orders are distinct, as before.
+    const cases = parsed.observations;
     if (new Set(cases.map(c => JSON.stringify(c))).size !== cases.length || ids.some(id => !cases.some(c => c.criterion === id)))
         throw Error("Every requested criterion needs a distinct observation.");
     return cases;

package/dist/operate.js

@@ -98,7 +98,8 @@ import { admissionRecorded, admitProject, commandLineActor } from "./project-adm
 import { leadClaim, leadSay, noteLeadWork } from "./lead-voice.js";
 import { createServer as createNetServer } from "node:net";
 import { spawn as spawnChild } from "node:child_process";
-import { envelopeJson } from "./envelope.js";
+// Every envelope is checked against its command's schema (logged, never refused), then serialized unchanged.
+import { checkedEnvelopeJson as envelopeJson } from "./contracts/cli.js";
 import { hasDisguisedText, hasForbiddenControls, validateNote } from "./decision.js";
 import { readVerifiedArtifact, readVerifiedReport, storeEvidence } from "./evidence.js";
 import { contractChangesOf, decodePlanContractRecord, describeContractChanges, encodePlannerSource, plannerSourceOf } from "./planner-source.js";
@@ -203,6 +204,7 @@ import { readPulls } from "./pulls.js";
 import { startMaintenance } from "./maintenance.js";
 import { livePin, modelWatchPass } from "./model-catalog.js";
 import { runModelsCommand } from "./models-cli.js";
+import { ALL_PROJECTS, chatApprovalSettings, chatApprovalWords, setChatApproval } from "./chat-approval.js";
 import { updateAdmissionPaused, UPDATE_PAUSED } from "./desktop-update-gate.js";
 import { beads } from "./beads.js";
 import { githubIssues } from "./issues.js";
@@ -469,6 +471,8 @@ Flows — processes cards move through; the console's rules
   toolroll flows script save --repo <path> --name <name> (--file <path in project> | --body <file>)
       --about "<one line>" [--language shell|python|node] [--timeout-minutes <n>]
   toolroll flows card add <id> --title <t> [--description <d>] [--zone <zone>]
+  toolroll flows card approve <id> <card> [--option <words|number>]
+  toolroll flows card send-back <id> <card> --note <text>
   toolroll flows archive <id>
       writes take --as <you> --token <t> (or the remembered login); create,
       edit, archive and trigger add preview until --yes
@@ -638,7 +642,7 @@ export const OPERATE_VALUE_FLAGS = new Set([
     "max", "cap", "probe", "kind", "expires", "cmd", "since", "repair-model",
     "choose", "note", "max-open-decisions", "max-held-sessions", "name", "days", "publication", "auto-approve", "review-auto", "entries", "port", "host", "allow-host",
     "for", "tick-every", "bridge-every", "reconcile-every", "incarnation",
-    "say", "ceiling-usd",
+    "say", "ceiling-usd", "cap-usd",
     "token-file", "bin", "poll", "github", "remote", "head-prefix", "password",
     // v102: project rules.
     "not-requester", "protect", "protect-paths",
@@ -657,7 +661,7 @@ export const OPERATE_VALUE_FLAGS = new Set([
     // onboard: the starter flows to switch on.
     "starter",
     // flows: templates, steps, scripts and cards.
-    "template", "steps", "about", "language", "timeout-minutes", "body", "description", "zone",
+    "template", "steps", "about", "language", "timeout-minutes", "body", "description", "zone", "option",
     "token-env", "after", "repair-max-attempts", "consumer", "batch", "feedback", "source", "view", "cursor", "why", "supersedes", "decision", "sessions", "timeout",
     // pings follow responsibility: replacements.
     "replaced-by", "replaces",
@@ -670,7 +674,7 @@ export const OPERATE_BOOLEAN_FLAGS = new Set([
     "json", "yes", "all", "brief", "local", "history", "latest-watch", "dry-run", "file", "allow-paid-fallback",
     "clear", "follow", "ready", "all-tasks", "inbound-only", "help", "undo", "anyone", "allow-dispatch", "allow-merge", "merge-delete-branch",
     "no-open", "remove", "no-verify", "no-follow", "end", "report", "off", "tmux",
-    "self-heal", "plan-auto", "chat-approve", "repair-auto", "review-retry-auto", "no-local",
+    "self-heal", "plan-auto", "chat-approve", "full-access", "repair-auto", "review-retry-auto", "no-local",
     "html", "csv", "alerts-only",
     // v105: the full export.
     "zip",
@@ -1087,6 +1091,8 @@ async function dispatch(command, positional, flags, context) {
             return proposalsCommand(positional, flags, context);
         case "mode":
             return modeCommand(positional, flags, context);
+        case "chat-approval":
+            return chatApprovalCommand(positional, flags, context);
         case "people":
             return peopleCommand(positional, flags, context);
         case "keys":
@@ -5754,6 +5760,51 @@ async function peopleCommand(positional, flags, context) {
     ]);
 }
 const MODE_ACTIONS = ["set", "show", "revoke"];
+/** `chat-approval show | on | off [--repo <path>]`: the person's lasting choice to approve plans and merges from their
+ * paired chat (chat-approval.ts), for all their projects or one. On (or wider limits) previews until --yes and takes
+ * the password, like Settings; off is one step. Either way a ledger line. */
+async function chatApprovalCommand(positional, flags, context) {
+    const { store, write, json, clock } = context;
+    const action = positional[0] ?? "show";
+    const command = `chat-approval ${action}`;
+    if (!["show", "on", "off"].includes(action))
+        return fail(write, json, "chat-approval", "usage", "Use chat-approval show | on | off [--repo <path>] [--full-access] [--cap-usd <n>] [--yes].", EXIT.usage);
+    const acting = await askCredentials(flags, context);
+    if (acting === null)
+        return fail(write, json, command, "unauthenticated", "Approving from chat is your own setting: pass --as <you> --token <your password> (or sign in once with toolroll up).", EXIT.refused);
+    const authed = authenticateApprover(store, acting.name, acting.token);
+    if (!authed.ok)
+        return fail(write, json, command, "unauthenticated", "That name and password aren't an approver's. Nothing was changed.", EXIT.refused);
+    const given = text(flags, "repo");
+    const scope = given === undefined ? ALL_PROJECTS : canonicalProject(given) ?? resolve(given);
+    if (scope !== ALL_PROJECTS && !store.accountCanAccess(acting.name, scope))
+        return fail(write, json, command, "unknown-project", "That isn't one of your projects.", EXIT.refused);
+    const where = scope === ALL_PROJECTS ? "all your projects" : projectName(scope);
+    if (action === "show") {
+        const rows = chatApprovalSettings(store, acting.name).map(one => ({ scope: one.scope === ALL_PROJECTS ? "all" : one.scope, enabled: one.enabled, fullAccess: one.fullAccess, capMicrousd: one.capMicrousd, updatedAt: one.updatedAt }));
+        return succeed(write, json, command, { settings: rows }, () => rows.length === 0 ? ["Approving from chat is off everywhere. Turn it on: toolroll chat-approval on [--repo <path>]"]
+            : rows.map(one => `${one.scope === "all" ? "All projects" : projectName(one.scope)}: ${one.enabled ? `on · ${chatApprovalWords(one)}` : "off"}`));
+    }
+    const now = clock();
+    if (action === "off") {
+        const saved = setChatApproval(store, { approver: acting.name, scope, enabled: false, via: "the command line" }, now);
+        return saved.ok ? succeed(write, json, command, { applied: true, scope: scope === ALL_PROJECTS ? "all" : scope }, () => [saved.said]) : fail(write, json, command, "refused", saved.message, EXIT.refused);
+    }
+    const usd = text(flags, "cap-usd");
+    const cap = usd === undefined ? null : Number(usd);
+    if (cap !== null && !(Number.isFinite(cap) && cap >= 0 && cap <= 10_000))
+        return fail(write, json, command, "usage", "Give --cap-usd in dollars, like 5.", EXIT.usage);
+    const limits = { fullAccess: flag(flags, "full-access"), capMicrousd: cap === null ? null : Math.round(cap * 1_000_000) };
+    const terms = [
+        `Your own taps in your paired chat approve plans and merges in ${where}, until you turn it off: it doesn't expire.`,
+        `Limits: ${chatApprovalWords(limits)}.`,
+        "Plans written for you, protected paths, two-person rules and your organisation's policy still open in Toolroll.",
+    ];
+    if (!flag(flags, "yes"))
+        return succeed(write, json, command, { applied: false, scope: scope === ALL_PROJECTS ? "all" : scope, terms }, () => [`Turn on approving from chat for ${where}`, ...terms.map(one => `  ${one}`), "", "Nothing has changed. Add --yes to make this change."]);
+    const saved = setChatApproval(store, { approver: acting.name, scope, enabled: true, limits, via: "the command line" }, now);
+    return saved.ok ? succeed(write, json, command, { applied: true, scope: scope === ALL_PROJECTS ? "all" : scope, terms }, () => [saved.said]) : fail(write, json, command, "refused", saved.message, EXIT.refused);
+}
 async function modeCommand(positional, flags, context) {
     const { store, write, json, clock } = context;
     const [action] = positional;

package/dist/process-recovery-eligibility.d.ts

@@ -50,7 +50,7 @@ export declare function preparedCandidateObserverGapEligibility(store: Store, in
             digest: string;
             approvedAt: string;
             approvedBy: string;
-            approvalBasis: "mode" | "password";
+            approvalBasis: "chat" | "mode" | "password";
             modeDigest: string | null;
         };
         readonly command: {

package/dist/process-recovery-native.d.ts

@@ -1,21 +1,11 @@
+import { type DarwinProcessIdentity } from "./contracts/native-census.js";
 export type PreparedDarwinProcessCensus = {
     sourcePath: string;
     executablePath: string;
     sourceSha256: string;
     executableSha256: string;
 };
-export type DarwinProcessIdentity = {
-    pid: number;
-    ppid: number | null;
-    uid: number | null;
-    birthMs: number | null;
-    uniqueId: string | null;
-    parentUniqueId: string | null;
-    traced: boolean | null;
-    executable: string | null;
-    originalParentVersion: number | null;
-    pidVersion?: number;
-};
+export type { DarwinProcessIdentity } from "./contracts/native-census.js";
 export type DarwinManagedService = {
     domain: string;
     label: string;
@@ -169,4 +159,3 @@ export declare function collectDarwinCoalitionSnapshot(args: {
     maxAttempts?: number;
     anchorPids?: number[];
 }): Promise<DarwinCoalitionRecoverySnapshot>;
-export {};

package/dist/process-recovery-native.js

@@ -3,6 +3,7 @@ import { createHash } from "node:crypto";
 import { chmodSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { hostname, release } from "node:os";
 import { join } from "node:path";
+import { darwinNativeCensusSchema, darwinProcessIdentitySchema, kernelIdInRange } from "./contracts/native-census.js";
 const digest = (data) => createHash("sha256").update(data).digest("hex");
 const cleanEnv = { PATH: "/usr/bin:/bin:/usr/sbin:/sbin", LC_ALL: "C", TZ: "UTC" };
 /** Facts only. Public KERN_PROC_ALL supplies birth/UID/trace metadata without
@@ -189,15 +190,17 @@ const nullable = (value, test) => value === null || test(value);
 const safeText = (value) => typeof value === "string" && value.length <= 4096 && !/[\x00-\x1f\x7f]/.test(value);
 /** Strict parser also strips every field not in the facts contract. */
 export function parseDarwinNativeSnapshot(text) {
-    const v = JSON.parse(text);
-    if (!v || v.schema !== 1 || !nullable(v.bootId, (x) => typeof x === "string" && /^[a-fA-F0-9-]{36}$/.test(x)) || !isInt(v.collectorPid, 2) || typeof v.complete !== "boolean" || !Array.isArray(v.processes) || v.processes.length > 100_000 || !Array.isArray(v.errors) || !v.errors.every(x => ["kernel-process-table-unreadable", "process-membership-unreadable", "process-identity-unreadable", "boot-identity-unreadable", "coalition-counters-unreadable", "coalition-counters-changed", "coalition-count-mismatch", "anchor-identity-unreadable"].includes(x)))
+    const read = darwinNativeCensusSchema.safeParse(JSON.parse(text));
+    if (!read.success)
         throw new Error("malformed-native-census");
+    const v = read.data;
     const pids = new Set(), ids = new Set();
     const processes = v.processes.map((r) => {
-        if (!r || typeof r !== "object")
+        const row = darwinProcessIdentitySchema.safeParse(r);
+        if (!row.success)
             throw new Error("malformed-process-identity");
-        const p = r;
-        if (!isInt(p.pid, 1) || pids.has(p.pid) || !nullable(p.ppid, isInt) || !nullable(p.uid, isInt) || !nullable(p.birthMs, (n) => typeof n === "number" && Number.isFinite(n) && n > 0) || !nullable(p.uniqueId, isId) || p.uniqueId === "0" || (p.uniqueId !== null && ids.has(p.uniqueId)) || !nullable(p.parentUniqueId, isId) || (p.traced !== null && typeof p.traced !== "boolean") || !nullable(p.executable, safeText) || !nullable(p.originalParentVersion, (n) => isInt(n) && n <= 0xffffffff) || (p.pidVersion !== undefined && (!isInt(p.pidVersion) || p.pidVersion > 0xffffffff)))
+        const p = row.data;
+        if (pids.has(p.pid) || (p.uniqueId !== null && !kernelIdInRange(p.uniqueId)) || p.uniqueId === "0" || (p.uniqueId !== null && ids.has(p.uniqueId)) || (p.parentUniqueId !== null && !kernelIdInRange(p.parentUniqueId)))
             throw new Error("malformed-process-identity");
         pids.add(p.pid);
         if (p.uniqueId !== null)

package/dist/project-tools.d.ts

@@ -1,26 +1,6 @@
 import type { Store, ToolActionInfo } from "./store.js";
-/** One secret a tool needs: an env name for a local server, or the value behind an http header. */
-export type ToolSecret = {
-    name: string;
-    optional: boolean;
-};
-export type ToolSpec = {
-    name: string;
-    transport: "stdio" | "http";
-    /** stdio: the program and its arguments (no secrets in either). */
-    command: string | null;
-    args: string[];
-    /** http: the server's address. */
-    url: string | null;
-    /** Every secret the tool needs. stdio: each is an env variable of the server process. */
-    secrets: ToolSecret[];
-    /** http: the secret sent as `Authorization: Bearer <value>`. */
-    bearer: string | null;
-    /** http: header name → the secret sent as its raw value. */
-    headerSecrets: Record<string, string>;
-    /** What it does, in plain words. */
-    about: string;
-};
+import { type ToolSecret, type ToolSpec } from "./contracts/integration-metadata.js";
+export type { ToolSecret, ToolSpec };
 export type ToolTest = {
     at: string;
     ok: boolean;
@@ -68,7 +48,10 @@ export declare function catalogTool(id: string): (ToolSpec & {
 }) | null;
 /** What a build is held to: how the server starts and which secrets it names — never their values or its description. */
 export declare function toolDigest(spec: ToolSpec): string;
-/** A tool definition from any source (catalog, console form, the lead, an import), checked whole. Throws in plain words. */
+/**
+ * A tool definition from any source (catalog, console form, the lead, an import, a saved row), checked whole and made
+ * the spec its schema (src/contracts/integration-metadata.ts) says. Throws in plain words.
+ */
 export declare function validateToolSpec(input: Record<string, unknown>): ToolSpec;
 /** How the tool starts, in one line a person can check. Never a secret value. */
 export declare function toolCommandLine(spec: ToolSpec): string;
@@ -234,4 +217,3 @@ export declare function toolStanding(tool: ProjectTool, secretsSet: readonly str
 export declare function secretsSetFor(repo: string, tool: ToolSpec, home?: string): string[];
 /** A command line split into program and arguments, honouring "double" and 'single' quotes. */
 export declare function splitCommandLine(line: string): string[];
-export {};