toolroll 0.9.41 → 0.9.43

package/dist/surface.d.ts

@@ -1,57 +1,6 @@
-/**
- * The declared command guide (arc 5): the agent-facing surface as data,
- * dumped by `contract --commands`. This is DOCUMENTATION with a stable
- * shape, not authority — legacy verbs do not execute from it,
- * and the runtime envelope remains the truth. Its honest limits ride the
- * envelope itself as SURFACE_NOTES, because a source comment is invisible
- * to consumers (arc-5 review, finding 1).
- *
- * What the tests DO hold to the code: every root here is a routed verb
- * and every routed verb appears here; every declared flag lives in the
- * parser's global vocabulary with the declared arity; the subcommand
- * inventories for task/publish/config/approver/routine/contest match the
- * exported action lists their dispatchers consult; keyed mutations
- * declare --key; notableReasons come from DOCUMENTED_REASONS. What they
- * CANNOT prove — that a given flag is read by a given handler — is why
- * SURFACE_NOTES.flags says "intended".
- */
-import { type SessionDescriptor } from './session-contract.js';
-export type CommandFlag = {
-    readonly name: string;
-    readonly takesValue: boolean;
-    readonly meaning: string;
-};
-export type CommandRow = {
-    /** What you type after `toolroll` (subcommands included). */
-    readonly invocation: string;
-    /** The `command` field the envelope answers with, where it differs
-     * from the invocation (the no-verb report answers as "scan"). */
-    readonly envelopeCommand?: string;
-    readonly synopsis: string;
-    /** Who this act belongs to. "operator" rows are ceremonies or
-     * infrastructure: an agent must not invoke them even when credentials
-     * are within reach — the credential IS the person. The operator() helper
-     * omits flag detail on purpose; an explicit row may document flags when
-     * its command contract requires them. A schema is never permission. */
-    readonly audience: "agent" | "operator";
-    readonly agentMayInvoke: boolean;
-    /** Truthful retry semantics, not a boolean:
-     *  keyed — takes --key; same key returns the first answer.
-     *  identity-idempotent — repeating it converges (same lease, same
-     *    path, same managed file); no key needed.
-     *  unkeyed — a mutation without replay protection: do not blind-retry.
-     *  none — a read. */
-    readonly mutation: "keyed" | "identity-idempotent" | "unkeyed" | "none";
-    readonly positionals?: readonly {
-        name: string;
-        required: boolean;
-        meaning: string;
-    }[];
-    readonly flags?: readonly CommandFlag[];
-    readonly notableReasons?: readonly string[];
-    /** Session schemas are executable input contracts, not a grant of authority. */
-    readonly inputSchema?: SessionDescriptor['inputSchema'];
-};
+import { type CommandFlag, type CommandRow } from './contracts/cli.js';
+/** A guide row and its flags are derived from their schemas in src/contracts/cli.ts. */
+export type { CommandFlag, CommandRow };
 /** 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";
@@ -60,4 +9,7 @@ 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). */
+export declare const COMMAND_ENTRIES: readonly import("./contracts/cli.js").CommandEntry[];
+/** 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

@@ -21,6 +21,7 @@ import { FLOWS_DESCRIPTORS } from "./flows-cli.js";
  */
 import { SESSION_DESCRIPTORS } from './session-contract.js';
 import { sessionCliFlags } from './session-cli.js';
+import { commandEntries } from './contracts/cli.js';
 /** The guide's limits, stated machine-readably in every dump. */
 export const SURFACE_NOTES = {
     authority: "documentation is not permission; session descriptors also drive parser and request validation; legacy entries remain advisory",
@@ -47,7 +48,7 @@ const operatorRead = (invocation, synopsis) => ({
     agentMayInvoke: false,
     mutation: "none",
 });
-export const COMMAND_GUIDE = [
+const GUIDE_ROWS = [
     // ---- reports (reads) ----
     {
         invocation: "",
@@ -124,7 +125,7 @@ export const COMMAND_GUIDE = [
     ...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] },
@@ -383,6 +384,9 @@ export const COMMAND_GUIDE = [
     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"),
@@ -412,3 +416,7 @@ export const COMMAND_GUIDE = [
     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);
+/** 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/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);

package/dist/telegram.js

@@ -34,7 +34,7 @@ import { enqueueEveningDigests, finishedView, isTaskFact, joinsBatch, needsPerso
 import { BATCH_MS, chatText, chatTitle, factLinkLabel, mentions, nameTelegramBot } from "./chat-voice.js";
 import { LEAD_SAY_KIND, enqueueLeadLapses, leadSayEarlier, leadSayText, leadSubjectOf } from "./lead-voice.js";
 import { applyTeamInbound, deliverTeamChats, teamCommand } from "./telegram-team.js";
-import { applyFlowChoiceTap, applyFlowReply, applyFlowTap, FLOW_DECIDE_KEY, flowButtons, flowChoiceButtons, flowChoiceHead, flowDecisionAt, flowDecisionText, flowSendKeyboardRow, flowSentContent } from "./telegram-flow.js";
+import { applyFlowChoiceTap, applyFlowConfirm, applyFlowReply, applyFlowTap, flowConfirmOf, FLOW_DECIDE_KEY, flowButtons, flowChoiceButtons, flowChoiceHead, flowDecisionAt, flowDecisionText, flowSendKeyboardRow, flowSentContent } from "./telegram-flow.js";
 import { flowChoiceAt, flowSendTail, FLOW_CHOOSE_KEY, FLOW_SEND_KEY } from "./flow-send.js";
 import { cleanFlowMessage, fitFlowMessage } from "./flow-items.js";
 import { telegramReply } from "./reply-shape.js";
@@ -1523,7 +1523,8 @@ async function enrolledForMessage(context, update) {
 async function projectsForTap(context, update) {
     const callback = update.callback_query;
     // Flow decision buttons (v86) work with or without the lead's conversation on this phone.
-    const flowTap = callback !== undefined && (context.store.getTelegramFlowAction(callback.data ?? "") !== null || context.store.getTelegramFlowChoice(callback.data ?? "") !== null);
+    const flowTap = callback !== undefined && (context.store.getTelegramFlowAction(callback.data ?? "") !== null || context.store.getTelegramFlowChoice(callback.data ?? "") !== null
+        || flowConfirmOf(context.store, callback.data ?? "") !== null);
     // So do a result's, plan's or pull request's own buttons (chat-decide.ts).
     const decideTap = callback !== undefined && isDecideToken(context.store, callback.data ?? "");
     if (callback === undefined || context.readProjects === undefined || (context.conversation === undefined && !flowTap && !decideTap))
@@ -2172,6 +2173,29 @@ function applyCallback(context, update, effects) {
         }
         return;
     }
+    // A flow decision's repaint: its buttons (fresh ones stamped on this message) or links under the console.
+    const flowEdit = (effect) => {
+        if (effect.place !== undefined && effect.place.length > 0)
+            store.placeTelegramFlowActions(effect.place, String(message.message_id));
+        editText(effect.text, decideKeyboard(context.conversation?.phoneOrigin, effect.keyboard ?? []));
+    };
+    // The Yes or Cancel a flow Approve armed (telegram-flow.ts): on the message it was armed on, by the person it was armed for.
+    const flowConfirm = flowConfirmOf(store, token);
+    if (flowConfirm !== null) {
+        if (flowConfirm.binding !== binding.id || flowConfirm.chatId !== tapChat || flowConfirm.messageId !== String(message.message_id)) {
+            report.ignored++;
+            ack("That button isn't for this chat. Nothing was done.");
+            return;
+        }
+        const repos = context.projects === null ? null : telegramConversationRepos(store, binding.approver, context.projects);
+        for (const effect of applyFlowConfirm(store, binding, flowConfirm, { text: message.text ?? "" }, repos, clock())) {
+            if (effect.kind === "ack")
+                ack(effect.text);
+            else if (effect.kind === "edit")
+                flowEdit(effect);
+        }
+        return;
+    }
     const flowAction = store.getTelegramFlowAction(token);
     if (flowAction !== null) {
         if (flowAction.binding !== binding.id || flowAction.chatId !== tapChat || (flowAction.messageId !== null && flowAction.messageId !== String(message.message_id))) {
@@ -2184,7 +2208,7 @@ function applyCallback(context, update, effects) {
             if (effect.kind === "ack")
                 ack(effect.text);
             else if (effect.kind === "edit")
-                editText(effect.text);
+                flowEdit(effect);
             else
                 effects.push(async () => {
                     // A reply box: whatever they send back as a reply to this prompt is the new draft, or the note.

package/dist/toolroll-update.d.ts

@@ -1,14 +1,14 @@
 import type { DatabaseSync } from "node:sqlite";
-import { type LingeringRun, type UpdateWaiting } from "./desktop-update.js";
-import { type ReleasedCodingOwner } from "./coding-update.js";
+import { type UpdateWaiting } from "./desktop-update.js";
 import { type SupervisorRunner } from "./daemon.js";
+import { RUNTIME_PHASES, type RuntimeUpdateJournalRecord } from "./contracts/update-journal.js";
 export declare const PROVENANCE_REPOSITORY = "https://github.com/ap9000/toolroll";
 export declare const PROVENANCE_WORKFLOW = ".github/workflows/publish.yml";
 export declare const PROVENANCE_ISSUER = "https://token.actions.githubusercontent.com";
 /** The steps a person sees, in order. */
 export declare const UPDATE_STEPS: readonly ["verifying", "draining", "backing-up", "rehearsing", "switching", "restarting", "health"];
 export type UpdateStep = typeof UPDATE_STEPS[number];
-export type RuntimePhase = "scheduled" | UpdateStep | "complete" | "rolling-back" | "restored" | "refused" | "cancelled" | "needs-attention";
+export type RuntimePhase = typeof RUNTIME_PHASES[number];
 export declare const STEP_WORDS: Record<UpdateStep, string>;
 export type When = "now" | "when-idle" | "at";
 export type RuntimeRef = {
@@ -19,100 +19,9 @@ export type RuntimeRef = {
 export declare const KEEP_RUNTIMES = 2;
 /** The one-off launchd job the console starts the updater as. */
 export declare const UPDATE_JOB_LABEL = "com.toolroll.update";
-export type RuntimeUpdateJournal = {
-    version: 1;
-    id: string;
-    kind: "update" | "rollback";
-    stateDir: string;
-    databaseFile: string;
-    stageDir: string;
-    from: RuntimeRef;
-    to: RuntimeRef;
-    when: When;
-    at: string | null;
-    actor: string;
-    phase: RuntimePhase;
-    detail: string;
-    error?: string;
-    steps: {
-        phase: RuntimePhase;
-        at: string;
-    }[];
-    startedAt: string;
-    updatedAt: string;
-    finishedAt?: string;
-    package?: {
-        sha512: string;
-        repository: string;
-        workflow: string;
-    };
-    notes?: string[];
-    /** This run's own verified copies of the live database and coding catalog: what a failure restores. */
-    backupPath?: string;
-    backupHash?: string;
-    codingBackupPath?: string;
-    codingBackupHash?: string;
-    /** A rollback installs the update's earlier backups (checked against their recorded hashes). */
-    restoreFrom?: {
-        path: string;
-        hash: string;
-        updateId: string;
-        codingPath?: string;
-        codingHash?: string;
-    };
-    rehearsal?: {
-        tables: number;
-        rows: number;
-    };
-    /** The background service, recorded before it is stopped: its definition and the processes that must be gone. */
-    service?: {
-        unit: string;
-        pids: number[];
-    };
-    /** Each repo's watch daemon that runs this version, recorded the same way: switched with the service, and stopped and
-     * restarted with it only when launchd had it loaded before the update (`loaded` absent: 0.8.1 stopped every one). */
-    watches?: {
-        unit: string;
-        pids: number[];
-        loaded?: boolean;
-    }[];
-    /** Recorded before each change so a resumed or failed run knows what to put back. */
-    switched?: {
-        links: {
-            path: string;
-            previous: string;
-        }[];
-        unit: {
-            path: string;
-            saved: string;
-        } | null;
-        watches?: {
-            path: string;
-            saved: string;
-        }[];
-        databaseRestored?: boolean;
-    };
-    /** What the live database held when a failed run restored its backup: nothing written is lost. The newest of `kept`. */
-    keptAside?: string;
-    /** The live database could not be read, so it was moved aside whole rather than copied. */
-    keptAsideUnreadable?: boolean;
-    /** Every copy kept aside, oldest first: a retried restore adds one and never drops the pointer to an earlier one. */
-    kept?: {
-        path: string;
-        unreadable: boolean;
-    }[];
-    /** The restore put the backup back: a retried restore never puts it back again (what was written since belongs to
-     * the restored version and would be lost), and it keeps a fresh copy aside before every attempt until then. */
-    restoredDatabase?: boolean;
-    /** A stale coding owner record this run released after proving its processes gone. */
-    codingOwnerReleased?: ReleasedCodingOwner;
-    seen?: boolean;
-    /** The finished run the update is waiting on (or stopped waiting on): what is in the way and the command that
-     * clears it. Absent while it waits on ordinary running work. */
-    waiting?: LingeringRun & {
-        since: string;
-    };
-};
+/** The update's journal (`toolroll-update.json`, `.last.json` and the stage's `update.json`):
+ * src/contracts/update-journal.ts. */
+export type RuntimeUpdateJournal = RuntimeUpdateJournalRecord;
 export type PackageRelease = {
     version: string;
     tarball: string;
@@ -164,11 +73,11 @@ export type UpdateSystem = {
 };
 export type UpdateOutcome = {
     ok: boolean;
-    phase: RuntimePhase;
+    phase: RuntimeUpdateJournal["phase"];
     message: string;
     journal: RuntimeUpdateJournal | null;
 };
-export declare const runtimeUpdateTerminal: (phase: RuntimePhase) => boolean;
+export declare const runtimeUpdateTerminal: (phase: string) => boolean;
 /** How long a launched or resuming updater is expected to take to start and hold the lock. */
 export declare const UPDATER_START_MS: number;
 export declare function readRuntimeUpdate(stateDir: string, file?: string): RuntimeUpdateJournal | null;