toolroll 0.9.42 → 0.9.44

package/dist/store.js

@@ -64,7 +64,7 @@ import { authenticate as runnerAuthenticate } from "./runner.js";
 import { stampNewProjectLevel } from "./check-levels.js";
 import { parseCheckProgressSnapshot } from "./check-progress.js";
 import { normalizeProjectAccess, projectAccessAllows, readProjectAccess } from "./project-access.js";
-import { LEDGER_SCHEMA, LEDGER_TABLE, LEDGER_V54_COLUMNS, LEDGER_V54_TABLE, installLedgerTriggers } from "./action-ledger.js";
+import { LEDGER_SCHEMA, LEDGER_TABLE, LEDGER_V54_COLUMNS, LEDGER_V54_TABLE, LEDGER_V99_TABLE, installLedgerTriggers } from "./action-ledger.js";
 import { PLAN_AUTO_SCHEMA } from "./plan-auto.js";
 import { RECIPE_SCHEMA } from "./recipes.js";
 import { POLICY_SCHEMA, agentRefusal, approvalRefusal, attendedRefusal, policyParts, readPolicy, underCeiling, sessionCeilingRefusal } from "./policy.js";
@@ -354,6 +354,40 @@ CREATE TABLE IF NOT EXISTS telegram_flow_choice (
 );
 CREATE INDEX IF NOT EXISTS telegram_flow_choice_visit ON telegram_flow_choice (card, entry);
 `;
+/** An owner's lasting choice to approve plans and merges from their paired chat (chat-approval.ts), for all their
+ * projects (scope '*') or one (its path), with the limits they agreed to. Off unless a row says on; a project's own row
+ * outranks the all-projects one. `generation` is the account's at the change: a reset password ends it. */
+export const CHAT_APPROVAL_SCHEMA = `
+CREATE TABLE IF NOT EXISTS chat_approval_setting (
+  approver             TEXT NOT NULL,
+  scope                TEXT NOT NULL,
+  enabled              INTEGER NOT NULL CHECK (enabled IN (0,1)),
+  full_access          INTEGER NOT NULL DEFAULT 0 CHECK (full_access IN (0,1)),
+  attempt_cap_microusd INTEGER CHECK (attempt_cap_microusd IS NULL OR attempt_cap_microusd >= 0),
+  generation           INTEGER NOT NULL,
+  digest               TEXT NOT NULL,
+  updated_by           TEXT NOT NULL,
+  updated_at           TEXT NOT NULL,
+  PRIMARY KEY (approver, scope)
+);
+`;
+/** The second tap on a flow decision in Telegram (telegram-flow.ts): Approve arms Yes and Cancel, bound to the binding,
+ * chat, message and exact visit of the card; Yes decides it once. */
+export const TELEGRAM_FLOW_CONFIRM_SCHEMA = `
+CREATE TABLE IF NOT EXISTS telegram_flow_confirm (
+  token       TEXT PRIMARY KEY,
+  binding     INTEGER NOT NULL,
+  chat_id     TEXT NOT NULL,
+  message_id  TEXT NOT NULL,
+  card        INTEGER NOT NULL,
+  entry       INTEGER NOT NULL,
+  phase       TEXT NOT NULL CHECK (phase IN ('yes','cancel')),
+  created_at  TEXT NOT NULL,
+  expires_at  TEXT NOT NULL,
+  consumed_at TEXT
+);
+CREATE INDEX IF NOT EXISTS telegram_flow_confirm_visit ON telegram_flow_confirm (card, entry);
+`;
 export const CHAT_DECIDE_SCHEMA = `
 CREATE TABLE IF NOT EXISTS chat_decide_action (
   token       TEXT PRIMARY KEY,
@@ -529,7 +563,29 @@ const REGISTERED_AT_FILING = "again, as it was filed";
 // v107 keeps a check's progress and result in one record (run_check absorbs check_progress).
 // v108 keeps sign-in pauses: one incident per provider whose sign-in stopped working (provider_auth_pause).
 // v109 remembers which sign-in pause parked a task (task_ref.auth_wait_pause), so reviews and other runs outside the tick wait for it too.
-export const SCHEMA_VERSION = 109;
+// v110 lets the action ledger record commands a person ran on this server with their API token (source 'api', or 'mcp' from their agent).
+export const SCHEMA_VERSION = 110;
+/**
+ * The migrations `toolroll update` may carry a database through in place: each
+ * one only adds (a table, a column, an accepted value) and leaves every saved row
+ * as it was, so the updater's rehearsal on a copy (same history, integrity ok)
+ * proves it and the verified backup undoes it. Any migration not listed here
+ * needs the separate verified migration procedure. The desktop update never
+ * migrates and does not read this list.
+ *
+ * v110 rebuilds action_ledger only to widen its source check ('api', 'mcp'):
+ * every row, id and hash-chain link is copied unchanged.
+ */
+export const UPDATE_SAFE_MIGRATIONS = Object.freeze([110]);
+/** Whether a database settled at `version` reaches this build's schema through update-safe migrations alone. */
+export function updateSafeSchema(version) {
+    if (version === null || !Number.isSafeInteger(version) || version <= 0 || version > SCHEMA_VERSION)
+        return false;
+    for (let next = version + 1; next <= SCHEMA_VERSION; next++)
+        if (!UPDATE_SAFE_MIGRATIONS.includes(next))
+            return false;
+    return true;
+}
 /** v102: a project's approval rules, and each person's approval of an exact scope (two are needed for protected work). */
 const APPROVAL_SCHEMA = `
 CREATE TABLE IF NOT EXISTS approval_policy (
@@ -3964,6 +4020,9 @@ function initializeStore(db, file) {
     db.exec(MATE_ASK_SCHEMA);
     // Decisions in the chat app (no version bump: additive only): result, plan and merge buttons, and Request changes.
     db.exec(CHAT_DECIDE_SCHEMA);
+    // An owner's lasting chat-approval setting (no version bump: additive only; absent means off).
+    db.exec(CHAT_APPROVAL_SCHEMA);
+    db.exec(TELEGRAM_FLOW_CONFIRM_SCHEMA);
     // A flow's "Send to me" and "Person chooses" zones (no version bump: additive only).
     db.exec(FLOW_SEND_SCHEMA);
     db.exec(SPEND_SCHEMA);
@@ -5175,8 +5234,8 @@ function migrate(db, origin) {
        tool_call     INTEGER REFERENCES teammate_call(id),
        suggestion    INTEGER REFERENCES teammate_suggestion(id)
      )`, ["id", "teammate", "card", "entry", "question", "options_json", "asked_of", "state", "choice", "answer", "answered_by", "answered_via", "answered_at", "created_at", "tool_call", "suggestion"]);
-    // v99: the action ledger admits sign-in and policy events, each with a short detail.
-    rebuildLedgerForV99(db);
+    // v99: the action ledger admits sign-in and policy events, each with a short detail; v110: and remote commands ('api', 'mcp').
+    rebuildLedger(db);
     // v101: a coordinator credential's expiry (null: made before expiry existed, until renewed).
     addColumn(db, "coordinator_credential", "expires_at", "TEXT");
     // v102: who filed a task (a person, or the person a coordinator acts for; null when no person is known) and what kind of filer.
@@ -5497,19 +5556,24 @@ function readWebSession(row) {
 }
 /**
  * v99: the ledger's source admits 'sign-in' and 'policy', and each row may
- * carry a short detail. The work triggers on other tables write into the
+ * carry a short detail. v110: it admits 'api' and 'mcp' too, from either
+ * earlier shape; rows, ids and the counter are carried whole, so the v103
+ * seals over them still hold. The work triggers on other tables write into the
  * ledger, and a rename refuses while a trigger points at a table that's gone,
  * so every trigger naming it is dropped first; openStore puts them back
  * (LEDGER_SCHEMA and installLedgerTriggers run after migration).
  */
-function rebuildLedgerForV99(db) {
+function rebuildLedger(db) {
     const row = db.prepare("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'action_ledger'").get();
     if (row === undefined || canonicalDdl(String(row["sql"])) === canonicalDdl(LEDGER_TABLE("action_ledger")))
         return;
     for (const trigger of db.prepare("SELECT name FROM sqlite_master WHERE type = 'trigger' AND sql LIKE '%action_ledger%'").all()) {
         db.exec(`DROP TRIGGER IF EXISTS "${String(trigger["name"]).replace(/"/g, '""')}"`);
     }
-    rebuildExact(db, "action_ledger", LEDGER_V54_TABLE, LEDGER_TABLE, LEDGER_V54_COLUMNS);
+    if (canonicalDdl(String(row["sql"])) === canonicalDdl(LEDGER_V54_TABLE("action_ledger")))
+        rebuildExact(db, "action_ledger", LEDGER_V54_TABLE, LEDGER_TABLE, LEDGER_V54_COLUMNS);
+    else
+        rebuildExact(db, "action_ledger", LEDGER_V99_TABLE, LEDGER_TABLE, [...LEDGER_V54_COLUMNS, "detail"]);
 }
 /** v34: artifact.kind admits 'report'. A table already rebuilt to the v38
  * shape (migrate() runs unconditionally on every open, including a fresh
@@ -8797,7 +8861,7 @@ export class Store {
                 // (setup review): the approval is what was stale, and it is new.
                 const ref = this.db.prepare("SELECT id FROM task_ref WHERE backend = ? AND external_id = ?").get(BUILT_IN, taskId);
                 if (ref !== undefined) {
-                    if (basis === undefined)
+                    if (basis === undefined || basis.kind === "chat")
                         this.noteTaskAct(Number(ref["id"]), "approved", now);
                     this.db.prepare("DELETE FROM hold WHERE owner_kind = 'backoff' AND owner_id = ?").run(`stale:${Number(ref["id"])}`);
                     this.db
@@ -8813,7 +8877,9 @@ export class Store {
                             subject: "Scope approved",
                             body: basis === undefined
                                 ? `Approved by ${currentActor()?.lead === true ? "the lead" : lifecycleWords(by, 40)}. A connected worker can take it next.`
-                                : "Approved automatically under the operating mode. A connected worker can take it next.",
+                                : basis.kind === "chat"
+                                    ? `Approved by ${lifecycleWords(by, 40)} in chat. A connected worker can take it next.`
+                                    : "Approved automatically under the operating mode. A connected worker can take it next.",
                             link: chatControlHref("task", taskId),
                         }, now);
                     }
@@ -18513,6 +18579,7 @@ export class Store {
         const stamp = now.toISOString();
         this.db.prepare("UPDATE telegram_flow_action SET consumed_at = ? WHERE card = ? AND entry = ? AND consumed_at IS NULL").run(stamp, card, entry);
         this.db.prepare("UPDATE telegram_flow_prompt SET consumed_at = ? WHERE card = ? AND entry = ? AND consumed_at IS NULL").run(stamp, card, entry);
+        this.db.prepare("UPDATE telegram_flow_confirm SET consumed_at = ? WHERE card = ? AND entry = ? AND consumed_at IS NULL").run(stamp, card, entry);
     }
     recordTelegramFlowPrompt(prompt, now, hours = 24) {
         this.db.prepare("INSERT OR REPLACE INTO telegram_flow_prompt (chat_id, message_id, binding, card, entry, mode, created_at, expires_at, consumed_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL)")

package/dist/surface.d.ts

@@ -1,6 +1,6 @@
-import { type CommandFlag, type CommandRow } from './contracts/cli.js';
+import { type CommandFlag, type CommandRow, type RemotePolicy } from './contracts/cli.js';
 /** A guide row and its flags are derived from their schemas in src/contracts/cli.ts. */
-export type { CommandFlag, CommandRow };
+export type { CommandFlag, CommandRow, RemotePolicy };
 /** The guide's limits, stated machine-readably in every dump. */
 export declare const SURFACE_NOTES: {
     readonly authority: "documentation is not permission; session descriptors also drive parser and request validation; legacy entries remain advisory";
@@ -9,7 +9,14 @@ export declare const SURFACE_NOTES: {
     readonly database: "local database commands wait up to 15 seconds for another writer; an exhausted wait returns database-busy and names the selected file";
 };
 export declare const SURFACE_SCHEMA_VERSION = 1;
-/** Every declared command, in guide order, paired with the schema of its `--json` answer (src/contracts/cli.ts). */
+/** Every row's remote policy, by invocation. Exported for the contract test, which holds it to the guide exactly. */
+export declare const REMOTE_POLICY: ReadonlyMap<string, RemotePolicy>;
+/** How many times each invocation was classified — the contract test refuses a row stated twice. */
+export declare const REMOTE_POLICY_COUNT: number;
+/** Every declared command, in guide order, paired with the schema of its `--json` answer (src/contracts/cli.ts).
+ * An unclassified row is "no": nothing runs remotely by omission. */
 export declare const COMMAND_ENTRIES: readonly import("./contracts/cli.js").CommandEntry[];
+/** The invocations the guide states, for the contract test (a classification naming none of them is stale). */
+export declare const GUIDE_INVOCATIONS: readonly string[];
 /** The guide `contract --commands` dumps: each declared command's row, projected from COMMAND_ENTRIES. */
 export declare const COMMAND_GUIDE: readonly CommandRow[];

package/dist/surface.js

@@ -125,7 +125,7 @@ const GUIDE_ROWS = [
     ...MEMORY_DESCRIPTORS.map(spec => ({ invocation: `memory ${spec.action}`, synopsis: spec.synopsis, audience: "agent", agentMayInvoke: true, mutation: spec.mutation, flags: spec.flags, ...(spec.takesQuery ? { positionals: [{ name: "query", required: true, meaning: "search text, a decision id, or the decision sentence" }] } : {}) })),
     // Flow writes carry an approver's credential: an agent runs them only as the person asked, after showing the preview.
     ...FLOWS_DESCRIPTORS.map(spec => ({ invocation: `flows ${spec.action}`, synopsis: spec.synopsis, audience: "agent", agentMayInvoke: true, mutation: spec.mutation, flags: spec.flags,
-        ...("positionals" in spec ? { positionals: spec.positionals.map(name => ({ name, required: true, meaning: name === "flow" ? "a flow id from flows list" : "a trigger id from flows show, or for trigger add its settings as JSON, a JSON file, or -" })) } : {}) })),
+        ...("positionals" in spec ? { positionals: spec.positionals.map(name => ({ name, required: true, meaning: name === "flow" ? "a flow id from flows list" : name === "card" ? "a card id from flows show" : "a trigger id from flows show, or for trigger add its settings as JSON, a JSON file, or -" })) } : {}) })),
     ...MODELS_DESCRIPTORS.map(spec => ({ invocation: `models ${spec.action}`, synopsis: spec.synopsis, audience: "agent", agentMayInvoke: true, mutation: spec.mutation, flags: spec.flags, ...(spec.takesQuery ? { positionals: [{ name: "target", required: true, meaning: "the CLI to update, or on/off" }] } : {}) })),
     // ---- the queue (agent surface) ----
     { invocation: "status", synopsis: "running work, queued reasons, results to review, the latest release check and plan windows", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
@@ -384,6 +384,9 @@ const GUIDE_ROWS = [
     operatorRead("review show", "whether a project's finished builds get one automatic review"),
     operator("review on", "one automatic review of each finished build whose check passes; only HIGH findings send it back, once"),
     operator("review off", "finished builds go straight to the person, unreviewed"),
+    operatorRead("chat-approval show", "whether your own taps in your paired chat approve plans and merges: all projects and each project's own setting"),
+    operator("chat-approval on", "let your paired chat approve plans and merges in all your projects or one (--repo); lasting, with limits; previews until --yes"),
+    operator("chat-approval off", "stop approving from chat for all your projects or one (--repo); one step"),
     operator("mode revoke", "revoke a repository's mode — one click, every act it covered falls back to its own ceremony"),
     operator("config set", "set phase or spend configuration"),
     operator("config clear", "clear phase or spend configuration"),
@@ -413,7 +416,72 @@ const GUIDE_ROWS = [
     operator("onboard", "add this repository, report signed-in agents, install or --remove the operator skill (--yes), offer the starter flows (--starter <ids>), and print the handoff"),
     operator("daemon", "install the loop under the OS service manager"),
 ];
-/** Every declared command, in guide order, paired with the schema of its `--json` answer (src/contracts/cli.ts). */
-export const COMMAND_ENTRIES = commandEntries(GUIDE_ROWS);
+/**
+ * Whether each row may run on a central server for a person signed in with their own API token (`runOperateAs` in
+ * operate.ts), stated for every row by name. "no" is this machine's own infrastructure, credentials, files and the
+ * commands that only make sense beside a checkout (or that the local CLI answers itself); "step-up" is approvals,
+ * people and policy, which stay in the console and chat; "yes" runs as the person, within their token's scope and
+ * project access. A row missing here fails the contract test, and runs nowhere remotely meanwhile.
+ */
+const REMOTE_NO = [
+    // Answered by the local CLI, or a client of a central server itself.
+    "", "pulls", "graph", "repos", "repos add", "repos remove", "repos add-from-github", "contract", "skills list", "skills get", "skills install",
+    "link", "unlink", "update", "demo", "chat", "connect", "lead list", "lead create", "lead update", "lead member", "lead transfer",
+    "conversation list", "conversation create", "conversation show", "conversation member", "conversation edit", "conversation withdraw",
+    "conversation read", "conversation follow", "conversation stop",
+    "session capabilities", "session list", "session show", "session changes", "session start", "session send", "session stop", "session resume", "session recover",
+    // This machine's checkout, saved profile, credentials and catch-up.
+    "project show", "project use", "brief", "lead token", "lead say",
+    "assignment show", "assignment updates", "assignment claim", "assignment check", "assignment brief", "assignment inbox", "assignment ack",
+    // Workers, the loop and the services that run here.
+    "claim", "heartbeat", "release", "reap", "tick", "build", "reconcile",
+    "runner register", "runner retire", "runner bind", "runner capacity", "coordinator mint", "coordinator revoke", "mcp", "outbox deliver", "peek",
+    "serve", "watch", "up", "onboard", "daemon", "bridge", "setup show", "setup clear",
+    // Provider keys and model tools on this machine.
+    "providers", "keys status", "keys set", "keys clear", "keys verify", "keys auth", "models check", "models update", "models watch",
+    // Publication and release.
+    "publish", "publish status", "publish merge", "publish refire", "publish unblock", "publish rearm", "publish grant", "publish revoke",
+    // A repository's authority grants on this machine.
+    "enroll", "revoke",
+    // Flow steps that fetch addresses or run checks and scripts here.
+    "flows import", "flows trigger check", "flows script save",
+    // Reads this machine owner's own Claude and Codex session files (~/.claude, ~/.codex).
+    "memory propose",
+];
+const REMOTE_STEP_UP = [
+    "proposals", "decide", "task regate", "task approve", "task accept", "task merge", "run settle", "routine approve", "knowledge apply", "memory apply",
+    "flows card approve", "flows card send-back", "flows script approve",
+    "approver list", "approver add", "people list", "people invite", "people projects", "people revoke",
+    "mode show", "mode set", "mode revoke", "chat-approval on", "review on", "review off", "config set", "config clear",
+    "verify set", "verify clear", "verify level", "project checks", "project concurrency", "intake grant", "intake clear", "webhook primary",
+];
+const REMOTE_YES = [
+    "status", "integrations", "ready", "gaps", "grants", "sync",
+    "task add", "task ask", "task checks", "task add-tests", "task list", "task show", "check-progress", "task wait", "task complete", "task revise",
+    "task state", "task block", "task unblock", "task next", "task steer", "task assign", "task scope", "task plan", "task hold", "task unhold", "task require",
+    "task requeue", "task review", "task repair", "task route", "task reopen", "task stop", "task resume",
+    "runner list", "coordinator list", "cap list", "cap add", "outbox list", "incident list", "incident resolve",
+    "routine list", "routine show", "routine add", "routine refresh", "routine pause", "routine resume", "routine run-now",
+    "config show", "verify show", "intake show", "intake run", "intake preview", "intake pr-comments", "template list", "template show",
+    "contest show", "contest exclude", "webhook status", "webhook test", "review show", "chat-approval show", "chat-approval off",
+    "knowledge search", "knowledge impact", "knowledge refresh",
+    "memory search", "memory decisions", "memory show", "memory decide", "memory retire", "memory review", "memory status",
+    "flows list", "flows show", "flows export", "flows create", "flows edit", "flows trigger add", "flows trigger pause", "flows trigger resume",
+    "flows trigger remove", "flows card add", "flows archive",
+    "models status", "models list",
+];
+/** Every row's remote policy, by invocation. Exported for the contract test, which holds it to the guide exactly. */
+export const REMOTE_POLICY = new Map([
+    ...REMOTE_NO.map(invocation => [invocation, "no"]),
+    ...REMOTE_STEP_UP.map(invocation => [invocation, "step-up"]),
+    ...REMOTE_YES.map(invocation => [invocation, "yes"]),
+]);
+/** How many times each invocation was classified — the contract test refuses a row stated twice. */
+export const REMOTE_POLICY_COUNT = REMOTE_NO.length + REMOTE_STEP_UP.length + REMOTE_YES.length;
+/** Every declared command, in guide order, paired with the schema of its `--json` answer (src/contracts/cli.ts).
+ * An unclassified row is "no": nothing runs remotely by omission. */
+export const COMMAND_ENTRIES = commandEntries(GUIDE_ROWS.map(row => ({ ...row, remote: REMOTE_POLICY.get(row.invocation) ?? "no" })));
+/** The invocations the guide states, for the contract test (a classification naming none of them is stale). */
+export const GUIDE_INVOCATIONS = GUIDE_ROWS.map(row => row.invocation);
 /** The guide `contract --commands` dumps: each declared command's row, projected from COMMAND_ENTRIES. */
 export const COMMAND_GUIDE = COMMAND_ENTRIES.map(entry => entry.guide);

package/dist/team-cli.d.ts

@@ -11,5 +11,24 @@ export type TeamCliOptions = {
     sleep?: (milliseconds: number, signal: AbortSignal) => Promise<void>;
 };
 export declare const TEAM_CLI_ACTIONS: readonly ['connect', 'lead list', 'lead create', 'lead update', 'lead member', 'lead transfer', 'conversation list', 'conversation create', 'conversation show', 'conversation member', 'conversation edit', 'conversation withdraw', 'conversation read', 'conversation follow', 'conversation stop'];
+export declare class UsageError extends Error {
+}
+type Profile = {
+    origin: string;
+    account: string;
+    token: string;
+};
+/** An API token (so_…) is sent bare; an older saved sign-in keeps its account:secret form. */
+export declare const bearerOf: (profile: Profile) => string;
+/** The saved central profile remote commands use: the named one (or the active one), and whether it holds an API token.
+ * null when nothing is saved. Reads only the private profile file — never a local login or the database. */
+export declare function centralProfile(options: TeamCliOptions, name?: string): {
+    name: string;
+    origin: string;
+    account: string;
+    token: string;
+    apiToken: boolean;
+} | null;
 /** null means preserve the existing local command path. Nothing here opens a database. */
 export declare function maybeRunTeamCommand(argv: readonly string[], write: (line: string) => void, options?: TeamCliOptions): Promise<number | null>;
+export {};

package/dist/team-cli.js

@@ -8,9 +8,12 @@ import { envelopeJson } from './envelope.js';
 import { sessionServiceOrigin } from './session-cli.js';
 import { databasePath } from './store.js';
 import { configBase, namedPath } from './names.js';
+import { parseApiToken } from './api-tokens.js';
 export const TEAM_CLI_ACTIONS = ['connect', 'lead list', 'lead create', 'lead update', 'lead member', 'lead transfer', 'conversation list', 'conversation create', 'conversation show', 'conversation member', 'conversation edit', 'conversation withdraw', 'conversation read', 'conversation follow', 'conversation stop'];
 const HELP = `toolroll connect <HTTPS-origin> --as <account> --token-stdin
-  Use --token-file <private-file> or --local-login for your existing local sign-in.
+  Pipe your API token (so_…, from Settings → API tokens) or use --token-file <private-file>;
+  --local-login uses your existing local sign-in for chat only.
+  With an API token saved, other commands run on that server as you (--local runs here).
   Optional: --profile <name> (saved as the active profile).
 toolroll lead list|create|update|member|transfer [--profile <name>] [--json]
   create: --name <name> --instructions <text> --project <server-path> (repeatable)
@@ -36,7 +39,7 @@ toolroll brief --lead <id> --conversation <id> [--json]
 Saved profiles select the central service for chat and brief. Use --local for the
 existing local commands. Credentials stay in a private file, never in URLs or arguments.
 Reads and attachment do not start model work. Server permissions remain authoritative.`;
-class UsageError extends Error {
+export class UsageError extends Error {
 }
 const value = (flags, name) => typeof flags[name] === 'string' ? flags[name] : '';
 const required = (flags, name) => { const result = value(flags, name); if (!result)
@@ -128,6 +131,20 @@ function saveProfile(options, name, profile) {
             unlinkSync(temporary);
     }
 }
+/** An API token (so_…) is sent bare; an older saved sign-in keeps its account:secret form. */
+export const bearerOf = (profile) => parseApiToken(profile.token) !== null ? `Bearer ${profile.token}` : `Bearer ${profile.account}:${profile.token}`;
+/** The saved central profile remote commands use: the named one (or the active one), and whether it holds an API token.
+ * null when nothing is saved. Reads only the private profile file — never a local login or the database. */
+export function centralProfile(options, name) {
+    const saved = profiles(options);
+    if (saved === null)
+        return null;
+    const chosen = name ?? saved.active;
+    if (!/^[A-Za-z0-9_-]{1,64}$/.test(chosen) || !Object.hasOwn(saved.profiles, chosen))
+        throw new UsageError(`No saved connection named ${chosen}. Use connect with your API token first.`);
+    const profile = saved.profiles[chosen];
+    return { name: chosen, ...profile, apiToken: parseApiToken(profile.token) !== null };
+}
 async function stdinSecret() {
     if (process.stdin.isTTY)
         throw new UsageError('Pipe your sign-in secret into --token-stdin, or use --token-file.');
@@ -229,7 +246,7 @@ async function perform(profile, request, options) {
     const reading = ['list', 'show'].includes(request.operation);
     const unconfirmed = () => failure(reading ? 'service-unavailable' : 'delivery-unconfirmed', reading ? 'The service response could not be read.' : 'The response could not be confirmed. Inspect saved messages before continuing; this request was not retried.', { operation: request.operation, ...(request.args.conversationId ? { conversationId: request.args.conversationId } : {}), ...(request.args.requestId ? { requestId: request.args.requestId } : {}) });
     try {
-        const response = await (options.fetch ?? fetch)(`${profile.origin}/api/team`, { method: 'POST', redirect: 'manual', credentials: 'omit', signal: options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000), headers: { authorization: `Bearer ${profile.account}:${profile.token}`, 'content-type': 'application/json', accept: 'application/json' }, body: JSON.stringify(request) });
+        const response = await (options.fetch ?? fetch)(`${profile.origin}/api/team`, { method: 'POST', redirect: 'manual', credentials: 'omit', signal: options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000), headers: { authorization: bearerOf(profile), 'content-type': 'application/json', accept: 'application/json' }, body: JSON.stringify(request) });
         if (response.status >= 300 && response.status < 400) {
             await response.body?.cancel();
             return unconfirmed();

package/dist/teammate-work.js

@@ -206,7 +206,7 @@ function carryOut(store, flow, definition, stage, card, mate, context, answer, n
     if (answer.action === "approve" || answer.action === "send_back") {
         const draft = draftFor(definition, stage);
         const decided = decideFlowCard(store, {
-            card: card.id, decision: answer.action === "approve" ? "approve" : "send-back", note: answer.action === "approve" ? answer.reason || null : note(answer.note), actor, repos, teammate: mate.handle, entry: card.entry,
+            card: card.id, decision: answer.action === "approve" ? "approve" : "send-back", note: answer.action === "approve" ? answer.reason || null : note(answer.note), actor, repos, teammate: mate.handle, entry: card.entry, where: "a teammate",
             ...(answer.action === "approve" && draft !== null && answer.text !== "" ? { draft: wholeDraft(answer.text) } : {}),
             ...(io.evidenceRoot === undefined ? {} : { evidenceRoot: io.evidenceRoot }),
         }, now);

package/dist/telegram-flow.d.ts

@@ -2,6 +2,7 @@ import { type FlowChoiceVisit, type FlowSendContent } from "./flow-send.js";
 import { type FlowStage } from "./flows.js";
 import { type InlineButton } from "./telegram-mate.js";
 import type { FlowCardRow, FlowRow, Store, TelegramBinding, TelegramFlowAction, TelegramFlowChoice, TelegramFlowPrompt } from "./store.js";
+/** A flow decision's notice: one per visit, and again (`:ask:<ms>`) when the owner asks the lead to approve it. */
 export declare const FLOW_DECIDE_KEY: RegExp;
 type Waiting = {
     card: FlowCardRow;
@@ -41,21 +42,60 @@ export declare function applyFlowChoiceTap(store: Store, binding: TelegramBindin
 export type FlowTapEffect = {
     kind: "ack";
     text: string;
-} | {
+}
+/** The message repainted; `keyboard` (absent: none) replaces its buttons, and links are paths under the console. */
+ | {
     kind: "edit";
     text: string;
+    keyboard?: FlowKeyboard;
+    place?: string[];
 } | {
     kind: "prompt";
     text: string;
     placeholder: string;
     prompt: Omit<TelegramFlowPrompt, "messageId">;
 };
+/** A repainted message's buttons: a token, or a link to a console path. `place` names fresh flow buttons to stamp on the message. */
+export type FlowKeyboard = Array<Array<{
+    label: string;
+    token: string;
+} | {
+    label: string;
+    link: {
+        label: string;
+        path: string;
+    };
+}>>;
+/** Where a card is now, for a message whose buttons no longer act: named and linked only when it is in one of the
+ * viewer's projects, and linked only while it still waits on someone. Never a live button. */
+export declare function flowWhereNow(store: Store, cardId: number, repos: readonly string[] | null): {
+    said: string;
+    keyboard: FlowKeyboard;
+};
 /** A tapped flow button, applied inside the update's transaction. */
 export declare function applyFlowTap(store: Store, binding: TelegramBinding, action: TelegramFlowAction, message: {
     chatId: string;
     messageId: string;
     text: string;
 }, repos: readonly string[] | null, now: Date): FlowTapEffect[];
+export type FlowConfirm = {
+    token: string;
+    binding: number;
+    chatId: string;
+    messageId: string;
+    card: number;
+    entry: number;
+    phase: "yes" | "cancel";
+    expiresAt: string;
+    consumedAt: string | null;
+};
+/** A Yes or Cancel this module armed, or null when the token isn't one. */
+export declare function flowConfirmOf(store: Store, token: string): FlowConfirm | null;
+/** The second tap, inside the update's transaction: Yes decides the card through the console's door, once; Cancel puts
+ * the card's own buttons back. The caller has proved the binding, chat and message are the ones it was armed on. */
+export declare function applyFlowConfirm(store: Store, binding: TelegramBinding, confirm: FlowConfirm, message: {
+    text: string;
+}, repos: readonly string[] | null, now: Date): FlowTapEffect[];
 export type FlowReplyEffect = {
     kind: "say";
     text: string;

package/dist/telegram-flow.js

@@ -22,12 +22,13 @@
 import { randomBytes } from "node:crypto";
 import { LIMITS } from "./decision.js";
 import { keptDraft } from "./flow-draft.js";
-import { decideFlowCard, draftFor, flowDefinitionOf } from "./flow-engine.js";
-import { chooseFlowCard, flowChoiceAt, flowSendPaths, readFlowSend } from "./flow-send.js";
+import { decideFlowCard, draftFor, flowCardHref, flowDefinitionOf } from "./flow-engine.js";
+import { chooseFlowCard, flowChoiceAt, flowPersonOf, flowSendPaths, readFlowSend } from "./flow-send.js";
 import { deciderOf, FLOW_END, replyTarget } from "./flows.js";
 import { phoneLinkButton } from "./telegram-mate.js";
 import { telegramButton } from "./contracts/telegram-callback.js";
-export const FLOW_DECIDE_KEY = /^flow-decide:([1-9][0-9]{0,14}):([1-9][0-9]{0,9})$/;
+/** A flow decision's notice: one per visit, and again (`:ask:<ms>`) when the owner asks the lead to approve it. */
+export const FLOW_DECIDE_KEY = /^flow-decide:([1-9][0-9]{0,14}):([1-9][0-9]{0,9})(?::ask:[0-9]{1,15})?$/;
 const DRAFT_LIMIT = 4000;
 /** The card, if it is still at that visit, waiting at a decision. */
 export function flowDecisionAt(store, cardId, entry) {
@@ -126,24 +127,66 @@ export function applyFlowChoiceTap(store, binding, choice, message, repos, now)
     const said = chosen.said.startsWith(`${choice.label}.`) ? chosen.said : `You chose “${choice.label}”. ${chosen.said}`;
     return [{ kind: "ack", text: choice.label.slice(0, 190) }, { kind: "edit", text: `${message.text}\n\n✅ ${said}`.slice(0, 4000) }];
 }
+/** A card's own fresh buttons, as a repaint carries them. */
+function freshButtons(store, binding, waiting, now) {
+    const minted = flowButtons(store, binding, waiting, now);
+    return { keyboard: minted.keyboard.map(row => row.flatMap(one => "callback_data" in one && typeof one.callback_data === "string" ? [{ label: one.text, token: one.callback_data }] : [])), place: minted.tokens };
+}
+const CONFIRM_TTL_MS = 10 * 60_000;
+const FLOW_QUESTION = /\n\nApprove “[^\n]*”\? [^\n]*$/;
+/** Where a card is now, for a message whose buttons no longer act: named and linked only when it is in one of the
+ * viewer's projects, and linked only while it still waits on someone. Never a live button. */
+export function flowWhereNow(store, cardId, repos) {
+    const card = store.getFlowCard(cardId);
+    const flow = card === null ? null : store.getFlow(card.flow);
+    if (card === null || flow === null || repos === null || !repos.includes(flow.repo))
+        return { said: "This card has moved on since.", keyboard: [] };
+    if (card.state !== "active")
+        return { said: card.state === "done" ? "This card is done." : "This card was closed.", keyboard: [] };
+    const definition = flowDefinitionOf(flow);
+    const stage = definition?.stages.find(one => one.id === card.stage);
+    const where = stage?.title ?? card.stage;
+    const open = { label: "Open it in Flows", path: flowCardHref(flow.id, card.id) };
+    if (stage?.kind === "approval" || stage?.kind === "choose") {
+        const person = stage.kind === "approval" ? deciderOf(stage, flow) ?? "an approver" : flowPersonOf(card, flow);
+        return { said: `It's waiting for ${person} in ${where} (${flow.name}).`, keyboard: [[{ label: open.label, link: open }]] };
+    }
+    if (card.waiting !== null)
+        return { said: `It's in ${where} now (${flow.name}): ${card.waiting.replace(/\.$/, "")}.`, keyboard: [[{ label: open.label, link: open }]] };
+    return { said: `It moved on to ${where} (${flow.name}).`, keyboard: [] };
+}
 /** A tapped flow button, applied inside the update's transaction. */
 export function applyFlowTap(store, binding, action, message, repos, now) {
-    if (action.consumedAt !== null || action.expiresAt <= now.toISOString())
-        return [{ kind: "ack", text: "That was already decided, or these buttons are too old." }];
+    if (action.consumedAt !== null || action.expiresAt <= now.toISOString()) {
+        // Spent or too old: say where the card is now, with a way to it while it still waits. The old button never acts again.
+        const now_ = flowWhereNow(store, action.card, repos);
+        return [{ kind: "ack", text: "These buttons were already used, or are too old." }, { kind: "edit", text: `${message.text.replace(FLOW_QUESTION, "")}\n\nThese buttons were already used, or are too old. ${now_.said}`.slice(0, 4000), keyboard: now_.keyboard }];
+    }
     const waiting = flowDecisionAt(store, action.card, action.entry);
-    if (waiting === null)
-        return [{ kind: "ack", text: "That card has moved on since; nothing was changed." }];
+    if (waiting === null) {
+        const now_ = flowWhereNow(store, action.card, repos);
+        store.retireTelegramFlowVisit(action.card, action.entry, now);
+        return [{ kind: "ack", text: "That card has moved on since; nothing was changed." }, { kind: "edit", text: `${message.text}\n\nNothing was changed. ${now_.said}`.slice(0, 4000), keyboard: now_.keyboard }];
+    }
     const decider = deciderOf(waiting.stage, waiting.flow);
     if (decider !== null && decider !== binding.approver)
         return [{ kind: "ack", text: `Only ${decider} decides here.` }];
     if (action.action === "approve") {
+        // The first tap asks; only the Yes decides, bound to exactly this visit of this card, on this message.
         if (repos === null)
             return [{ kind: "ack", text: "Couldn't check your projects just now. Try again in a moment." }];
-        const decided = decideFlowCard(store, { card: waiting.card.id, decision: "approve", note: null, actor: binding.approver, repos, entry: action.entry }, now);
-        if (!decided.ok)
-            return [{ kind: "ack", text: decided.message.slice(0, 190) }];
+        if (!repos.includes(waiting.flow.repo))
+            return [{ kind: "ack", text: "That card isn't in one of your projects now." }];
         store.retireTelegramFlowVisit(action.card, action.entry, now);
-        return [{ kind: "ack", text: "Approved" }, { kind: "edit", text: `${message.text}\n\n✅ ${decided.said}`.slice(0, 4000) }];
+        const mint = (phase) => {
+            const token = randomBytes(16).toString("hex");
+            store.handle.prepare("INSERT INTO telegram_flow_confirm (token, binding, chat_id, message_id, card, entry, phase, created_at, expires_at) VALUES (?,?,?,?,?,?,?,?,?)")
+                .run(token, binding.id, binding.chatId, message.messageId, action.card, action.entry, phase, now.toISOString(), new Date(now.getTime() + CONFIRM_TTL_MS).toISOString());
+            return token;
+        };
+        const where = waiting.stage.next === null ? "The card is then done." : `It moves to ${titleOf(waiting, waiting.stage.next)}.`;
+        return [{ kind: "ack", text: "Confirm below." }, { kind: "edit", text: `${message.text}\n\nApprove “${waiting.card.title}”? ${where}`.slice(0, 4000),
+                keyboard: [[{ label: "Yes", token: mint("yes") }, { label: "Cancel", token: mint("cancel") }]] }];
     }
     const prompt = { chatId: binding.chatId, binding: binding.id, card: action.card, entry: action.entry, mode: action.action };
     if (action.action === "edit") {
@@ -154,6 +197,47 @@ export function applyFlowTap(store, binding, action, message, repos, now) {
     return [{ kind: "ack", text: "What should change?" }, { kind: "prompt", prompt, placeholder: "What should change",
             text: `What should change on “${waiting.card.title}”? Reply to this message and it goes back to ${back} with your note.` }];
 }
+/** A Yes or Cancel this module armed, or null when the token isn't one. */
+export function flowConfirmOf(store, token) {
+    if (!/^[0-9a-f]{32}$/.test(token))
+        return null;
+    const row = store.handle.prepare("SELECT * FROM telegram_flow_confirm WHERE token = ?").get(token);
+    if (row === undefined)
+        return null;
+    return { token: String(row["token"]), binding: Number(row["binding"]), chatId: String(row["chat_id"]), messageId: String(row["message_id"]), card: Number(row["card"]), entry: Number(row["entry"]),
+        phase: String(row["phase"]) === "cancel" ? "cancel" : "yes", expiresAt: String(row["expires_at"]), consumedAt: row["consumed_at"] == null ? null : String(row["consumed_at"]) };
+}
+/** The second tap, inside the update's transaction: Yes decides the card through the console's door, once; Cancel puts
+ * the card's own buttons back. The caller has proved the binding, chat and message are the ones it was armed on. */
+export function applyFlowConfirm(store, binding, confirm, message, repos, now) {
+    const body = message.text.replace(FLOW_QUESTION, "");
+    const spend = () => store.handle.prepare("UPDATE telegram_flow_confirm SET consumed_at = ? WHERE card = ? AND entry = ? AND message_id = ? AND consumed_at IS NULL").run(now.toISOString(), confirm.card, confirm.entry, confirm.messageId);
+    if (confirm.consumedAt !== null || confirm.expiresAt <= now.toISOString()) {
+        spend();
+        const now_ = flowWhereNow(store, confirm.card, repos);
+        const waiting = flowDecisionAt(store, confirm.card, confirm.entry);
+        // Too old, but the same visit still waits: fresh buttons, never the old Yes.
+        if (waiting !== null && repos !== null && repos.includes(waiting.flow.repo)) {
+            return [{ kind: "ack", text: "That Yes expired. Nothing was done." }, { kind: "edit", text: body, ...freshButtons(store, binding, waiting, now) }];
+        }
+        return [{ kind: "ack", text: "That Yes expired. Nothing was done." }, { kind: "edit", text: `${body}\n\nNothing was done. ${now_.said}`.slice(0, 4000), keyboard: now_.keyboard }];
+    }
+    spend();
+    const waiting = flowDecisionAt(store, confirm.card, confirm.entry);
+    if (waiting === null || repos === null) {
+        const now_ = flowWhereNow(store, confirm.card, repos);
+        return [{ kind: "ack", text: repos === null ? "Couldn't check your projects just now. Try again in a moment." : "That card has moved on since; nothing was changed." },
+            { kind: "edit", text: `${body}\n\nNothing was changed. ${now_.said}`.slice(0, 4000), keyboard: now_.keyboard }];
+    }
+    if (confirm.phase === "cancel") {
+        return [{ kind: "ack", text: "Cancelled." }, { kind: "edit", text: body, ...freshButtons(store, binding, waiting, now) }];
+    }
+    const decided = decideFlowCard(store, { card: waiting.card.id, decision: "approve", note: null, actor: binding.approver, repos, entry: confirm.entry, where: "Telegram" }, now);
+    if (!decided.ok)
+        return [{ kind: "ack", text: "Not done." }, { kind: "edit", text: `${body}\n\n✗ Not done: ${decided.message}`.slice(0, 4000), keyboard: flowWhereNow(store, confirm.card, repos).keyboard }];
+    store.retireTelegramFlowVisit(confirm.card, confirm.entry, now);
+    return [{ kind: "ack", text: "Approved" }, { kind: "edit", text: `${body}\n\n✅ ${decided.said}`.slice(0, 4000) }];
+}
 const titleOf = (waiting, id) => flowDefinitionOf(waiting.flow)?.stages.find(one => one.id === id)?.title ?? id;
 /** A reply to an Edit or Send back prompt, applied inside the update's transaction. */
 export function applyFlowReply(store, binding, prompt, text, repos, now) {
@@ -200,7 +284,7 @@ export function applyFlowReply(store, binding, prompt, text, repos, now) {
         return [{ kind: "say", text: `That's ${said.length.toLocaleString("en-US")} characters. Keep the note to ${LIMITS.note.toLocaleString("en-US")}, or send it back in Toolroll.` }];
     if (repos === null)
         return [{ kind: "say", text: "Couldn't check your projects just now. Reply again in a moment." }];
-    const decided = decideFlowCard(store, { card: waiting.card.id, decision: "send-back", note: said, actor: binding.approver, repos, entry: prompt.entry }, now);
+    const decided = decideFlowCard(store, { card: waiting.card.id, decision: "send-back", note: said, actor: binding.approver, repos, entry: prompt.entry, where: "Telegram" }, now);
     if (!decided.ok)
         return [{ kind: "say", text: decided.message }];
     store.retireTelegramFlowVisit(prompt.card, prompt.entry, now);