toolroll 0.9.96 → 0.9.98

package/dist/contracts/lead-tools.js

@@ -52,7 +52,7 @@ export const CODE_MAP_VIEWS = ["overview", "area", "file", "search"];
 /** Task states a list filters by. */
 export const LISTED_TASK_STATES = ["queued", "running", "done", "failed", "cancelled"];
 /** The shared actions the lead proposes with propose_action; flows and subagents have their own tools. */
-const ACTION_OPERATIONS = Object.keys(CHAT_ACTIONS).filter(one => !one.startsWith("flow_") && !one.startsWith("subagent_"));
+const ACTION_OPERATIONS = Object.keys(CHAT_ACTIONS).filter(one => !one.startsWith("flow_") && !one.startsWith("subagent_") && one !== "task_start");
 /** A card's spec as the lead sees it: one flat props object. Each element's own props are read strictly by card-catalog.ts. */
 const cardProps = z.strictObject({
     source: z.enum(CARD_SOURCES).optional(), chart: z.enum(CARD_CHART_TYPES).optional(), columns: z.array(z.string().max(40)).max(CARD_LIMITS.columns).optional(), facts: z.array(z.string().max(40)).max(CARD_LIMITS.facts).optional(),
@@ -147,6 +147,8 @@ export const LEAD_TOOL_INPUTS = {
         not: scopeText.nullable().optional(), touches: touches.optional(), acceptance,
         planning: z.enum(["auto", "required", "skip"]).optional(), report: z.boolean().optional(), checks: text("checksWords").optional(),
     }),
+    // One-step start from chat (docs/plans/one-step-chat.md C3): one small change the person asked to be done now.
+    propose_start: z.strictObject({ repo: repoId, title: text("taskTitle") }),
     // Lead fan-out (docs/plans/lead-fan-out.md): 2 to 20 independent items under one shared brief and one success test.
     propose_sweep: z.strictObject({
         repo: repoId, title: text("taskTitle"), brief: scopeText,
@@ -286,6 +288,7 @@ export const LEAD_TOOL_OUTPUTS = {
     get_decision: decisionOutput,
     queue: z.looseObject({ repo: str, queueRevision: int, ...queueColumnsOutput }),
     propose_task: proposed("task", { repo: str, deliverable: z.enum(["branch", "report"]), planning: str }),
+    propose_start: z.looseObject({ proposal: int, kind: z.enum(["action", "task"]), startsNow: z.boolean(), awaiting: str }),
     propose_sweep: cardDrafted,
     get_sweep: z.looseObject({ sweep: int, title: str, line: str, table: str, maxParallel: int, items: z.array(z.looseObject({ item: int, label: str, task: str, state: str })) }),
     propose_sweep_cancel: cardDrafted,

package/dist/contracts/store-json.d.ts

@@ -232,6 +232,7 @@ declare const STORE_COLUMN_VALUES: {
             task_reopen: "task_reopen";
             task_restore: "task_restore";
             task_resume: "task_resume";
+            task_start: "task_start";
             tool_add: "tool_add";
             tool_remove: "tool_remove";
             trial_stop: "trial_stop";

package/dist/discord-api.d.ts

@@ -5,7 +5,7 @@ export declare const discordId: (v: unknown) => v is string;
 export type DiscordCredentials = ChatIdentity & {
     botToken: string;
 };
-export type DiscordApi = (method: "GET" | "POST" | "PATCH" | "PUT", path: string, body?: Record<string, unknown>, file?: {
+export type DiscordApi = (method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE", path: string, body?: Record<string, unknown>, file?: {
     bytes: Uint8Array;
     name: string;
 }) => Promise<Record<string, unknown>>;
@@ -13,6 +13,8 @@ export declare class DiscordError extends ChatDeliveryError {
 }
 /** Discord's 403: the bot may not do this here (for a file, no Attach Files permission). */
 export declare const DISCORD_REFUSED = "Discord refused access. Check the app and direct-message permissions.";
+/** Discord's 404: the message (or the conversation) is gone. */
+export declare const DISCORD_GONE = "The Discord message or conversation is unavailable. Open the saved chat.";
 export declare function discordApi(token: string, fetcher?: typeof fetch): DiscordApi;
 export declare const discordCredentialFile: (dir: string) => string;
 export declare function loadDiscordCredentials(dir: string): DiscordCredentials | null;

package/dist/discord-api.js

@@ -10,10 +10,16 @@ export class DiscordError extends ChatDeliveryError {
 }
 /** Discord's 403: the bot may not do this here (for a file, no Attach Files permission). */
 export const DISCORD_REFUSED = "Discord refused access. Check the app and direct-message permissions.";
+/** Discord's 404: the message (or the conversation) is gone. */
+export const DISCORD_GONE = "The Discord message or conversation is unavailable. Open the saved chat.";
 export function discordApi(token, fetcher = fetch) {
     return async (method, path, body, file) => {
-        // Only relative API routes; never send the bot credential to supplied URLs.
-        if (!/^\/(?:users\/@me|users\/[0-9]+|oauth2\/applications\/@me|channels\/[0-9]+(?:\/typing|\/messages\/[0-9]+\/reactions\/%F0%9F%91%8D\/@me|\/messages(?:\/[0-9]+)?(?:\?limit=100)?)?|interactions\/[0-9]+\/[A-Za-z0-9._-]+\/callback)$/.test(path))
+        // Only relative API routes; never send the bot credential to supplied URLs. Beyond messages: typing, and the bot's
+        // own 👀 on a message (put on, taken off).
+        if (!/^\/(?:users\/@me|users\/[0-9]+|oauth2\/applications\/@me|channels\/[0-9]+(?:\/typing|\/messages\/[0-9]+\/reactions\/%F0%9F%91%80\/@me|\/messages(?:\/[0-9]+)?(?:\?limit=100)?)?|interactions\/[0-9]+\/[A-Za-z0-9._-]+\/callback)$/.test(path))
+            throw new DiscordError("Invalid Discord request");
+        // DELETE takes off the bot's own 👀 and nothing else (never a message).
+        if (method === "DELETE" && !/^\/channels\/[0-9]+\/messages\/[0-9]+\/reactions\/%F0%9F%91%80\/@me$/.test(path))
             throw new DiscordError("Invalid Discord request");
         let response;
         const headers = { Authorization: `Bot ${token}` };
@@ -60,7 +66,7 @@ export function discordApi(token, fetcher = fetch) {
                 : response.status === 403
                     ? DISCORD_REFUSED
                     : response.status === 404
-                        ? "The Discord message or conversation is unavailable. Open the saved chat."
+                        ? DISCORD_GONE
                         : response.status === 413
                             ? "Discord refused this file size. Open the saved result to view the evidence."
                             : "Discord could not complete the request";

package/dist/discord-chat.d.ts

@@ -1,9 +1,11 @@
-import { ChatState, type ChatIdentity } from "./chat-delivery-state.js";
+import { ChatState, type ChatIdentity, type ChatEvent } from "./chat-delivery-state.js";
 import { type ChatDeliveryOptions } from "./chat-delivery.js";
 import { discordPlain } from "./reply-shape.js";
+import { type ChatAckHooks, type ChatLiveTransport, type LiveReplies } from "./chat-live.js";
 import { type DiscordApi } from "./discord-api.js";
-export type DiscordChatOptions = Omit<ChatDeliveryOptions, "state" | "label" | "member" | "partSize" | "maxProposal"> & {
-    api: DiscordApi;
+export type DiscordChatOptions = Omit<ChatDeliveryOptions, "state" | "label" | "member" | "partSize" | "maxProposal" | "live"> & {
+    api: DiscordApi; /** The live "Working on it…" message (chat-live.ts): on in the worker. */
+    liveReplies?: LiveReplies;
 };
 export declare const discordDelivery: (options: DiscordChatOptions) => ChatDeliveryOptions;
 export declare const processDiscordEvent: (options: DiscordChatOptions) => Promise<boolean>;
@@ -15,3 +17,11 @@ export declare function receiveDiscord(state: ChatState, identity: ChatIdentity,
 export { discordPlain };
 export declare function discordCard(text: string, buttons?: Record<string, unknown>[], voice?: boolean): Record<string, unknown>;
 export declare function deliverDiscordPart(options: DiscordChatOptions): Promise<boolean>;
+/** The lead's words as Discord carries them, already rendered: one embed description (cut to its 4 096), empty
+ * content, its buttons (none on a live message) and never a ping. Every field is sent on every edit: Discord keeps
+ * what an edit leaves out, and inherits no allowed_mentions. */
+export declare function discordVoicePayload(rendered: string, buttons?: Record<string, unknown>[]): Record<string, unknown>;
+/** The live message for one owner message: a reply to it, created under a nonce so a repeat returns the same one. */
+export declare function discordLive(options: Pick<DiscordChatOptions, "api" | "identity">, event: ChatEvent, spacingMs?: number): ChatLiveTransport;
+/** The 👀 on the owner's message, and taking it off. A missing permission is asked about at most once a minute, quietly. */
+export declare function discordAckHooks(options: Pick<DiscordChatOptions, "api">): ChatAckHooks;

package/dist/discord-chat.js

@@ -14,23 +14,27 @@ import { processChatEvent, planChatNotifications, channelAccess, chatObject as o
 import { chatResultHref } from "./chat-controls.js";
 import { LEAD_MESSAGE_MAX_CHARS } from "./lead.js";
 import { discordPlain, renderReply } from "./reply-shape.js";
-import { WARM_EMOJI } from "./chat-warmth.js";
+import { isLiveMessage, liveSpacingOf, underCooldown } from "./chat-live.js";
 import { proposalPreview, proposalLink, proposalOutcomeText, armedCardText, armedYesLabel, } from "./chat-channel.js";
 import { resultImageFileName, safeResultImageCaption, verifyResultImage, } from "./chat-evidence.js";
-import { discordId, discordMember, DiscordError, DISCORD_REFUSED, } from "./discord-api.js";
-export const discordDelivery = (options) => ({
-    ...options,
-    state: new ChatState(options.store, "discord"),
-    label: "Discord",
-    member: (member, channel) => discordMember(options.api, member, channel),
-    // A 👍 on the owner's message and "typing…" while the lead works; a missing permission is skipped silently.
-    warm: (event) => ({
-        react: () => options.api("PUT", `/channels/${event.channel}/messages/${event.ts}/reactions/${encodeURIComponent(WARM_EMOJI)}/@me`),
-        typing: () => options.api("POST", `/channels/${event.channel}/typing`),
-    }),
-    partSize: 1800,
-    maxProposal: 3400,
-});
+import { discordId, discordMember, DiscordError, DISCORD_REFUSED, DISCORD_GONE, } from "./discord-api.js";
+export const discordDelivery = (options) => {
+    const state = new ChatState(options.store, "discord");
+    return {
+        ...options,
+        state,
+        label: "Discord",
+        member: (member, channel) => discordMember(options.api, member, channel),
+        // "typing…" while the lead works (the 👀 goes at arrival: discordAckHooks), under the shared cooldown; a missing
+        // permission is skipped silently.
+        warm: (event) => ({
+            typing: underCooldown(state, options.identity.installation, error => error instanceof DiscordError && error.code === "ratelimited" ? error.retryMs : null, () => options.clock?.() ?? new Date(), () => options.api("POST", `/channels/${event.channel}/typing`)),
+        }),
+        ...(options.liveReplies ? { live: (event) => discordLive(options, event, liveSpacingOf(options.liveReplies)) } : {}),
+        partSize: 1800,
+        maxProposal: 3400,
+    };
+};
 export const processDiscordEvent = (options) => processChatEvent(discordDelivery(options));
 export const planDiscordRooms = (options) => planRoomMessages(discordDelivery(options));
 export const planDiscordNotifications = (options) => planChatNotifications(discordDelivery(options));
@@ -151,12 +155,7 @@ export { discordPlain };
 export function discordCard(text, buttons = [], voice = false) {
     // The lead's own reply: one description in Discord's Markdown (bold anchors, labelled links), no title line promoted to a header.
     if (voice)
-        return {
-            content: "",
-            embeds: [{ description: renderReply(text, "discord").slice(0, 4096), color: 0x297b70 }],
-            components: Array.from({ length: Math.min(5, Math.ceil(buttons.length / 5)) }, (_, row) => ({ type: 1, components: buttons.slice(row * 5, row * 5 + 5) })),
-            allowed_mentions: { parse: [], replied_user: false },
-        };
+        return discordVoicePayload(renderReply(text, "discord"), buttons);
     const lines = text.split("\n"), first = lines[0] ?? "Toolroll", title = discordPlain(first).length <= 256 &&
         first.length <= 150 &&
         lines.length > 1
@@ -401,6 +400,12 @@ export async function deliverDiscordPart(options) {
         }
         // No permission to attach files here: one plain line instead of the result's screenshots.
         const saved = readChatPart(row.payload), content = saved.ok ? saved.value : null;
+        // The live message the reply was to replace is gone: the reply goes out as a new message.
+        if (content?.edit !== undefined && error instanceof DiscordError && error.code === DISCORD_GONE && isLiveMessage(state, row.event, content.edit)) {
+            const { edit: _edit, ...asNew } = content;
+            state.repaint(row.id, asNew);
+            return true;
+        }
         // Discord refused the card's embed: the part's own plain text goes instead, so the message is never lost.
         if (content?.rich && error instanceof DiscordError && error.code === "Discord could not complete the request" && error.retryMs === 60_000) {
             state.repaint(row.id, withoutCard(content));
@@ -422,3 +427,54 @@ export async function deliverDiscordPart(options) {
         return true;
     }
 }
+/** The lead's words as Discord carries them, already rendered: one embed description (cut to its 4 096), empty
+ * content, its buttons (none on a live message) and never a ping. Every field is sent on every edit: Discord keeps
+ * what an edit leaves out, and inherits no allowed_mentions. */
+export function discordVoicePayload(rendered, buttons = []) {
+    return {
+        content: "",
+        embeds: [{ description: rendered.slice(0, 4096), color: 0x297b70 }],
+        components: Array.from({ length: Math.min(5, Math.ceil(buttons.length / 5)) }, (_, row) => ({ type: 1, components: buttons.slice(row * 5, row * 5 + 5) })),
+        allowed_mentions: { parse: [], replied_user: false },
+    };
+}
+/** The live message for one owner message: a reply to it, created under a nonce so a repeat returns the same one. */
+export function discordLive(options, event, spacingMs) {
+    const nonce = chatHash(`discord:live:${event.id}`).slice(0, 24);
+    const confirmed = (answer, id) => {
+        if (!discordId(answer.id) || answer.channel_id !== event.channel || object(answer.author).id !== options.identity.bot || (id !== undefined && answer.id !== id))
+            throw new DiscordError("Discord did not confirm the message identity", 15_000, true);
+        return answer.id;
+    };
+    return {
+        platform: "discord",
+        ...(spacingMs === undefined ? {} : { spacingMs }),
+        limit: 4_000,
+        create: async (text) => confirmed(await options.api("POST", `/channels/${event.channel}/messages`, {
+            ...discordVoicePayload(text), nonce, enforce_nonce: true,
+            ...(discordId(event.thread) ? { message_reference: { message_id: event.thread, channel_id: event.channel, fail_if_not_exists: false } } : {}),
+        })),
+        // Discord checks an enforced nonce against "the past few minutes": a repeat within one minute is the same message.
+        nonceMs: 60_000,
+        recover: async () => {
+            const recent = await options.api("GET", `/channels/${event.channel}/messages?limit=100`);
+            const found = (Array.isArray(recent.items) ? recent.items : []).map(object)
+                .find(one => one.nonce === nonce && object(one.author).id === options.identity.bot && one.channel_id === event.channel && discordId(one.id));
+            return found === undefined ? null : String(found.id);
+        },
+        edit: async (message, text) => { confirmed(await options.api("PATCH", `/channels/${event.channel}/messages/${message}`, discordVoicePayload(text)), message); },
+        rateLimited: error => error instanceof DiscordError && error.code === "ratelimited" ? error.retryMs : null,
+        uncertain: error => !(error instanceof ChatDeliveryError) || error.uncertain,
+    };
+}
+/** The 👀 on the owner's message, and taking it off. A missing permission is asked about at most once a minute, quietly. */
+export function discordAckHooks(options) {
+    const path = (event) => `/channels/${event.channel}/messages/${event.ts}/reactions/${encodeURIComponent("👀")}/@me`;
+    return {
+        react: (event) => options.api("PUT", path(event)),
+        unreact: (event) => options.api("DELETE", path(event)),
+        refused: error => error instanceof DiscordError && error.code === DISCORD_REFUSED,
+        settled: error => error instanceof DiscordError && error.code === DISCORD_GONE,
+        rateLimited: error => error instanceof DiscordError && error.code === "ratelimited" ? error.retryMs : null,
+    };
+}

package/dist/discord.js

@@ -3,7 +3,8 @@ import { randomBytes } from "node:crypto";
 import { abortablePause, workChatQueue } from "./chat-follow.js";
 import { loadDiscordCredentials, discordApi, object, discordId, } from "./discord-api.js";
 import { ChatState, chatHash } from "./chat-delivery-state.js";
-import { receiveDiscord, processDiscordEvent, deliverDiscordPart, planDiscordNotifications, planDiscordRooms, } from "./discord-chat.js";
+import { runChatAcks } from "./chat-live.js";
+import { receiveDiscord, processDiscordEvent, deliverDiscordPart, planDiscordNotifications, planDiscordRooms, discordAckHooks, } from "./discord-chat.js";
 export function discordReadyMatches(raw, identity) {
     const packet = object(raw);
     return (object(packet.application).id === identity.app &&
@@ -69,6 +70,9 @@ export async function followDiscord(options) {
         });
         client.on("error", () => problem("Discord connection failed. Check the bot token and reconnect."));
         client.on("shardError", () => problem("Discord connection failed. Saved replies will retry."));
+        // The 👀 on each owner message as it arrives, beside the queue (a turn there can take a minute).
+        const acks = runChatAcks({ state, installation: credentials.installation, owner, current: () => same() && connected,
+            hooks: discordAckHooks({ api }), same, signal: options.signal });
         // Never subscribe a logger to raw payloads, SDK debug output or interaction tokens.
         client.on("raw", (packet) => {
             if (!same())
@@ -88,6 +92,8 @@ export async function followDiscord(options) {
             const body = object(packet.d);
             try {
                 const saved = receiveDiscord(state, credentials, packet.t, body, new Date());
+                if (saved && packet.t === "MESSAGE_CREATE")
+                    acks.wake();
                 if (packet.t === "INTERACTION_CREATE" &&
                     body.type === 3 &&
                     body.application_id === credentials.app &&
@@ -119,6 +125,7 @@ export async function followDiscord(options) {
             api,
             current: same,
             canNotify: options.notifications,
+            liveReplies: true,
         };
         try {
             await client.login(credentials.botToken);

package/dist/fast-start.d.ts

@@ -1,4 +1,5 @@
 import { type ApprovalPasswordFacts } from "./approval-password.js";
+import type { ChatApprovalLimits } from "./chat-approval.js";
 import { type TaskSizing } from "./phase-routing.js";
 import { type ApproveResult, type Scope } from "./scope.js";
 import { type Store } from "./store.js";
@@ -9,9 +10,10 @@ export declare const FAST_MAX_FILES = 3;
 export declare const FAST_MAX_LINES = 150;
 /** How long a rendered form may still be pressed. */
 export declare const FAST_PREVIEW_MS: number;
-/** Which person surface is filing. A chat, a flow, a token or an agent has no entry here. */
-export type FastVia = "console" | "terminal-ui" | "cli";
-export type FastRefusal = "setting" | "size" | "classifier" | "plan" | "quality" | "rules" | "protected" | "password" | "release" | "trial" | "chain" | "monthly" | "policy" | "agents" | "machine" | "mode";
+/** Which person surface is filing. `chat` is a Start card a person taps or answers yes to (one-step-chat.md); a flow, a
+ * token or an agent has no entry here. */
+export type FastVia = "console" | "terminal-ui" | "cli" | "chat";
+export type FastRefusal = "setting" | "size" | "classifier" | "plan" | "quality" | "rules" | "protected" | "password" | "release" | "trial" | "chain" | "monthly" | "policy" | "agents" | "machine" | "mode" | "limit";
 export declare const fastRefusalWords: (reason: FastRefusal) => string;
 /** Small tasks start right away: a project's own choice, else on for single-approver installs and off once there's more
  * than one approver. */
@@ -32,10 +34,34 @@ export type FastInput = {
     permissionMode?: "auto" | "bypassPermissions" | undefined;
 };
 export type PasswordFacts = Pick<ApprovalPasswordFacts, "passwordless" | "localOwner" | "freshAt" | "returnTo">;
+/** How the person is proved at the one step that differs by surface: the password rule the form reads, or (a chat
+ * start) the person's own chat approval limits. */
+export type FastProof = {
+    password: PasswordFacts;
+} | {
+    chat: ChatApprovalLimits;
+};
+/** Every person surface's eligibility: the rules, then a machine is refused. */
 export declare function fastStartEligible(store: Store, input: FastInput & {
     taskId: string;
     sizing: TaskSizing;
+} & ({
     password: PasswordFacts;
+} | {
+    proof: FastProof;
+}), now: Date): {
+    ok: true;
+    scope: Scope;
+} | {
+    ok: false;
+    reason: FastRefusal;
+};
+/** The rules alone, the same for every surface: only the person-proof step has two forms (FastProof). A preview reads
+ * these as any caller; Build reads them again behind the machine check (fastStartEligible). */
+export declare function fastStartRules(store: Store, input: FastInput & {
+    taskId: string;
+    sizing: TaskSizing;
+    proof: FastProof;
 }, now: Date): {
     ok: true;
     scope: Scope;
@@ -59,7 +85,7 @@ export type FastPreview = {
  * files exactly this, whatever is posted.
  */
 export declare function prepareFastStart(store: Store, input: FastInput & {
-    via: FastVia;
+    via: Exclude<FastVia, "chat">;
     password: PasswordFacts;
 }, now: Date): Promise<FastPreview>;
 export type FastBuild = {
@@ -84,9 +110,14 @@ export declare function fastStartBuild(store: Store, input: {
     digest: string;
     actor: string;
     via: FastVia;
-    password: PasswordFacts;
     approveNow: FastApprove;
-}, now: Date): FastBuild;
+    /** A chat start: the lead turn its card was drafted in. Its preview must have been prepared in that same turn. */
+    turn?: number;
+} & ({
+    password: PasswordFacts;
+} | {
+    proof: FastProof;
+}), now: Date): FastBuild;
 /**
  * A fast start that didn't start in time: its seal is cleared, in a logged transaction, and the task shows the ordinary
  * Approve plan. A task with a build running or a result to read is left to that.
@@ -134,3 +165,49 @@ export declare function keepGrownChange(store: Store, taskId: string, now: Date)
     ok: false;
     message: string;
 };
+/** What a chat start's preview is for: who asked, where, the lead's one-line title, and the lead turn it is prepared in. */
+export type ChatStartInput = {
+    actor: string;
+    repo: string;
+    title: string;
+    turn: number;
+};
+/**
+ * A chat start's preview, prepared by the lead's turn loop before the Start card is drafted: the classifier asked (at
+ * most its budget), the filing dry-run, and the rules read. It refuses no machine caller, because a preview grants
+ * nothing (the lead's turn runs as the lead): Build refuses a machine (fastStartBuild), and only a person's own tap or
+ * typed yes reaches Build. The row is bound to the person, `via = 'chat'` and the turn; a preview without a turn is
+ * unusable. The person's own chat limits are read again at the tap, for the chat it comes from; here only the loosest
+ * limit that still means something applies (no full access, no cap), so a card is never drafted for terms no chat
+ * approval could allow.
+ */
+export declare function prepareChatStart(store: Store, input: ChatStartInput, now: Date): Promise<FastPreview>;
+/** A chat start's preview, as the Start card reads it again: this person's, `via = 'chat'`, prepared in this turn,
+ * unexpired and unused. Null otherwise. */
+export declare function chatStartPreview(store: Store, preview: string, actor: string, turn: number, now: Date): {
+    taskId: string;
+    repo: string;
+    title: string;
+    sizing: TaskSizing;
+    digest: string;
+} | null;
+/** A dismissed Start card's preview can't be used: consumed, in the dismissal's transaction. */
+export declare function consumeChatStartPreview(store: Store, preview: string, now: Date): void;
+/**
+ * A chat start's filing dry-run, for its card: the scope filing would make, read in a savepoint that is always rolled
+ * back, with the rules read on it (any proof form; the card shows the terms, the tap proves the person). The card is made
+ * from these words; the tap files again and compares.
+ */
+export declare function chatStartDryRun(store: Store, input: {
+    actor: string;
+    repo: string;
+    title: string;
+    taskId: string;
+    sizing: TaskSizing;
+}, now: Date): {
+    ok: true;
+    scope: Scope;
+} | {
+    ok: false;
+    reason: FastRefusal;
+};

package/dist/fast-start.js

@@ -11,11 +11,18 @@
  * - **the Accept backstop**: a machine can't complete it, the project's grant doesn't push it until a person accepted it,
  *   and completion, publication and merge all read one verified measure of the whole change (verifiedChange).
  *
- * Only a person's own surfaces reach here (the browser, the terminal UI as the local owner, interactive `task new`).
- * Every machine is refused in the writer from trusted context. `task add` never comes this way.
+ * Only a person's own surfaces reach here (the browser, the terminal UI as the local owner, interactive `task new`, and
+ * a person's own tap or typed yes on a chat's Start card: docs/plans/one-step-chat.md). Every machine is refused in the
+ * writer from trusted context. `task add` never comes this way.
+ *
+ * A chat start (`via: "chat"`) runs the same rules (fastStartRules). Its words are the lead's, so it is filed as the
+ * lead's text (`proposedVia: "mate"`, quarantined), and only its person-proof step differs: chat has no password, so
+ * instead of the password field it passes only within the person's own chat approval limits (chatLimitProblem), and
+ * quarantined text is approvable in chat only on a card that showed every term whole (store.ts sealScopeApproval).
  */
 import { randomBytes } from "node:crypto";
 import { approvalPasswordField } from "./approval-password.js";
+import { chatLimitProblem } from "./chat-terms.js";
 import { isProtectedWork, protectedChanges } from "./approval-policy.js";
 import { originalTaskBase } from "./observations.js";
 import { legOf, makesNoPlan, routeFromJson } from "./phase-routing.js";
@@ -53,6 +60,7 @@ const FAST_WORDS = {
     agents: "Choose an agent first.",
     machine: "Only a person starts work this way.",
     mode: "This project's mode approves it.",
+    limit: "This is more than your chat approval setting allows.",
 };
 export const fastRefusalWords = (reason) => FAST_WORDS[reason];
 // ---- the project setting ---------------------------------------------------------------------------------------------
@@ -78,10 +86,16 @@ export function setFastStart(store, repo, on, by, now) {
 // ---- eligibility: one function, read by the form and again inside the transaction ------------------------------------
 /** Filed this way, the plan's words are the person's words, and they inspect the result. */
 export const fastAcceptance = (title) => [{ id: "c1", statement: title, how: null, evidence: ["manual-review"] }];
+/** Every person surface's eligibility: the rules, then a machine is refused. */
 export function fastStartEligible(store, input, now) {
-    const no = (reason) => ({ ok: false, reason });
     if (machineActing())
-        return no("machine");
+        return { ok: false, reason: "machine" };
+    return fastStartRules(store, { ...input, proof: "proof" in input ? input.proof : { password: input.password } }, now);
+}
+/** The rules alone, the same for every surface: only the person-proof step has two forms (FastProof). A preview reads
+ * these as any caller; Build reads them again behind the machine check (fastStartEligible). */
+export function fastStartRules(store, input, now) {
+    const no = (reason) => ({ ok: false, reason });
     if (!fastStartOn(store, input.repo))
         return no("setting");
     const account = store.accountOf(input.actor);
@@ -126,9 +140,13 @@ export function fastStartEligible(store, input, now) {
     const profile = scope.profile;
     if (levelOfProfile(scope.profile) === "escalated" || profile["checkAccess"] !== undefined || profile["machLookup"] !== undefined)
         return no("password");
-    const field = approvalPasswordField(store, { name: input.actor, taskId: input.taskId, scope, ...input.password });
-    if (field.field === "required" || field.field === "local-refused")
-        return no("password");
+    if ("password" in input.proof) {
+        const field = approvalPasswordField(store, { name: input.actor, taskId: input.taskId, scope, ...input.proof.password });
+        if (field.field === "required" || field.field === "local-refused")
+            return no("password");
+    }
+    else if (chatLimitProblem(scope, input.proof.chat, "your chat approval setting") !== null)
+        return no("limit");
     const ref = store.lookupRef(input.taskId);
     if (ref === null || store.budgetGate(now)({ ...store.budgetSubject(ref.id), agents: store.agentsFor([scope.profile.provider]) }).over !== null)
         return no("monthly");
@@ -136,12 +154,14 @@ export function fastStartEligible(store, input, now) {
         return no("policy");
     return { ok: true, scope };
 }
-/** File the task, inside the caller's transaction, exactly as Build will. */
+/** File the task, inside the caller's transaction, exactly as Build will. A chat start's words are the lead's: its text
+ * stays quarantined (`proposedVia: "mate"`), as every lead-written scope is. */
 function fileIt(store, id, input, now) {
     const filed = fileTaskProposal(store, {
         id, title: titleWithin(input.title), repo: input.repo, goal: input.title, acceptance: fastAcceptance(input.title), planning: "skip", sizing: input.sizing,
         ...(input.permissionMode === undefined ? {} : { permissionMode: input.permissionMode }),
-        filedVia: input.via === "console" ? "console" : input.via === "terminal-ui" ? "tui" : "cli", filedBy: { name: input.actor, kind: "person" },
+        filedVia: input.via === "console" ? "console" : input.via === "terminal-ui" ? "tui" : input.via === "chat" ? "chat" : "cli", filedBy: { name: input.actor, kind: "person" },
+        ...(input.via === "chat" ? { proposedVia: "mate" } : {}),
     }, now);
     return filed.ok ? { ok: true } : { ok: false, message: filed.message };
 }
@@ -152,10 +172,11 @@ class RolledBack extends Error {
         this.answer = answer;
     }
 }
-/** Run `body` in a transaction that never commits: a preview writes nothing. */
+/** Run `body` in a savepoint that never commits: a preview writes nothing, at any nesting depth (a nested transact runs
+ * in place, so only the savepoint undoes the writes when a caller already holds a transaction). */
 function dryRun(store, body) {
     try {
-        store.transact(() => { throw new RolledBack(body()); });
+        store.transact(() => store.savepoint(() => { throw new RolledBack(body()); }));
     }
     catch (error) {
         if (error instanceof RolledBack)
@@ -172,6 +193,9 @@ function dryRun(store, body) {
 export async function prepareFastStart(store, input, now) {
     if (machineActing())
         return { eligible: false, reason: "machine" };
+    // A chat start is prepared in the lead's turn (prepareChatStart), bound to it.
+    if (input.via === "chat")
+        return { eligible: false, reason: "rules" };
     if (!fastStartOn(store, input.repo))
         return { eligible: false, reason: "setting" };
     if (heuristicSizing({ title: input.title, goal: input.title }).size !== "small")
@@ -203,6 +227,10 @@ export async function prepareFastStart(store, input, now) {
 export function fastStartBuild(store, input, now) {
     if (machineActing())
         return { ok: false, reason: "machine", message: FAST_WORDS.machine };
+    const proof = "proof" in input ? input.proof : { password: input.password };
+    // The chat form of the proof is a chat start's alone; the form's surfaces keep the password rule.
+    if ("chat" in proof && input.via !== "chat")
+        return { ok: false, reason: "rules", message: FAST_WORDS.rules };
     class Refused extends Error {
         answer;
         constructor(answer) {
@@ -212,29 +240,37 @@ export function fastStartBuild(store, input, now) {
     }
     const refuse = (answer) => { throw new Refused(answer); };
     try {
-        return store.transact(() => {
+        // A savepoint inside the transaction: a refusal undoes the filing even when the caller already holds a transaction
+        // (a nested transact runs in place, and this function catches its own refusal).
+        return store.transact(() => store.savepoint(() => {
             const row = store.handle.prepare("SELECT * FROM fast_preview WHERE id = ? AND consumed_at IS NULL AND expires_at > ?").get(input.preview, now.toISOString());
             if (row === undefined || row["actor"] !== input.actor || row["via"] !== input.via)
                 return refuse({ ok: false, reason: "gone", message: "This form has expired. Start again." });
+            // A chat preview without a turn, or from another turn than its card's, is nobody's card.
+            if (input.via === "chat" && (row["turn"] === null || row["turn"] === undefined || input.turn === undefined || Number(row["turn"]) !== input.turn))
+                return refuse({ ok: false, reason: "gone", message: "This card has expired. Ask again." });
             const sizing = JSON.parse(String(row["sizing_json"]));
             const taskId = String(row["task_id"]);
             const filing = { actor: input.actor, repo: String(row["repo"]), title: String(row["title"]), ...(row["permission"] === null ? {} : { permissionMode: row["permission"] }) };
             const filed = fileIt(store, taskId, { ...filing, via: input.via, sizing }, now);
             if (!filed.ok)
                 return refuse({ ok: false, reason: "changed", message: filed.message });
-            const eligible = fastStartEligible(store, { ...filing, taskId, sizing, password: input.password }, now);
+            const eligible = fastStartEligible(store, { ...filing, taskId, sizing, proof }, now);
             if (!eligible.ok)
                 return refuse({ ok: false, reason: eligible.reason, message: FAST_WORDS[eligible.reason] });
             const at = now.toISOString();
             // approve() compares the digest the person saw with the plan just filed: changed terms refuse "changed".
             const approved = input.approveNow(taskId, input.digest, { rule: FAST_START_RULE, at });
+            if (!approved.ok && approved.reason === "changed")
+                return refuse({ ok: false, reason: "changed", message: "This changed since you read it. Read it again." });
+            // Chat has no password: a refusal there says the rule, not "takes your password".
             if (!approved.ok)
-                return refuse({ ok: false, reason: approved.reason === "changed" ? "changed" : "password", message: approved.reason === "changed" ? "This changed since you read it. Read it again." : FAST_WORDS.password });
+                return refuse(input.via === "chat" ? { ok: false, reason: "rules", message: approved.reason === "policy" ? approved.message : FAST_WORDS.rules } : { ok: false, reason: "password", message: FAST_WORDS.password });
             store.handle.prepare("UPDATE fast_preview SET consumed_at = ? WHERE id = ?").run(at, input.preview);
             store.handle.prepare("UPDATE task_ref SET fast_start_at = ?, fast_start_until = ? WHERE backend = ? AND external_id = ?").run(at, new Date(now.getTime() + FAST_WINDOW_MS).toISOString(), BUILT_IN, taskId);
             store.bumpWake();
             return { ok: true, taskId };
-        });
+        }));
     }
     catch (error) {
         if (error instanceof Refused)
@@ -429,3 +465,64 @@ export function keepGrownChange(store, taskId, now) {
         return { ok: true, digest: proposed.digest };
     });
 }
+/**
+ * A chat start's preview, prepared by the lead's turn loop before the Start card is drafted: the classifier asked (at
+ * most its budget), the filing dry-run, and the rules read. It refuses no machine caller, because a preview grants
+ * nothing (the lead's turn runs as the lead): Build refuses a machine (fastStartBuild), and only a person's own tap or
+ * typed yes reaches Build. The row is bound to the person, `via = 'chat'` and the turn; a preview without a turn is
+ * unusable. The person's own chat limits are read again at the tap, for the chat it comes from; here only the loosest
+ * limit that still means something applies (no full access, no cap), so a card is never drafted for terms no chat
+ * approval could allow.
+ */
+export async function prepareChatStart(store, input, now) {
+    if (!Number.isSafeInteger(input.turn) || input.turn < 1)
+        return { eligible: false, reason: "rules" };
+    if (!fastStartOn(store, input.repo))
+        return { eligible: false, reason: "setting" };
+    if (heuristicSizing({ title: input.title, goal: input.title }).size !== "small")
+        return { eligible: false, reason: "size" };
+    const mode = store.activeMode(input.repo, now);
+    if (mode !== null && /"autoApproveFiling":true/.test(mode.termsJson))
+        return { eligible: false, reason: "mode" };
+    const sizer = filingSizer();
+    const sizing = await classifyTask({ title: input.title, goal: input.title }, sizer.sizer, sizer.budget);
+    const taskId = `task-${randomBytes(8).toString("hex")}`;
+    const filing = { actor: input.actor, repo: input.repo, title: input.title };
+    const read = dryRun(store, () => {
+        const filed = fileIt(store, taskId, { ...filing, via: "chat", sizing }, now);
+        if (!filed.ok)
+            return { ok: false, reason: "plan" };
+        return fastStartRules(store, { ...filing, taskId, sizing, proof: { chat: { fullAccess: false, capMicrousd: null } } }, now);
+    });
+    if (!read.ok)
+        return { eligible: false, reason: read.reason };
+    const preview = randomBytes(16).toString("hex");
+    store.handle.prepare(`INSERT INTO fast_preview (id, actor, via, task_id, repo, title, permission, sizing_json, digest, created_at, expires_at, turn) VALUES (?, ?, 'chat', ?, ?, ?, NULL, ?, ?, ?, ?, ?)`)
+        .run(preview, input.actor, taskId, input.repo, input.title, JSON.stringify(sizing), read.scope.digest, now.toISOString(), new Date(now.getTime() + FAST_PREVIEW_MS).toISOString(), input.turn);
+    return { eligible: true, preview, digest: read.scope.digest, scope: read.scope, taskId };
+}
+/** A chat start's preview, as the Start card reads it again: this person's, `via = 'chat'`, prepared in this turn,
+ * unexpired and unused. Null otherwise. */
+export function chatStartPreview(store, preview, actor, turn, now) {
+    const row = store.handle.prepare("SELECT * FROM fast_preview WHERE id = ? AND consumed_at IS NULL AND expires_at > ?").get(preview, now.toISOString());
+    if (row === undefined || row["actor"] !== actor || row["via"] !== "chat" || row["turn"] === null || Number(row["turn"]) !== turn)
+        return null;
+    return { taskId: String(row["task_id"]), repo: String(row["repo"]), title: String(row["title"]), sizing: JSON.parse(String(row["sizing_json"])), digest: String(row["digest"]) };
+}
+/** A dismissed Start card's preview can't be used: consumed, in the dismissal's transaction. */
+export function consumeChatStartPreview(store, preview, now) {
+    store.handle.prepare("UPDATE fast_preview SET consumed_at = ? WHERE id = ? AND via = 'chat' AND consumed_at IS NULL").run(now.toISOString(), preview);
+}
+/**
+ * A chat start's filing dry-run, for its card: the scope filing would make, read in a savepoint that is always rolled
+ * back, with the rules read on it (any proof form; the card shows the terms, the tap proves the person). The card is made
+ * from these words; the tap files again and compares.
+ */
+export function chatStartDryRun(store, input, now) {
+    return dryRun(store, () => {
+        const filed = fileIt(store, input.taskId, { actor: input.actor, repo: input.repo, title: input.title, via: "chat", sizing: input.sizing }, now);
+        if (!filed.ok)
+            return { ok: false, reason: "plan" };
+        return fastStartRules(store, { actor: input.actor, repo: input.repo, title: input.title, taskId: input.taskId, sizing: input.sizing, proof: { chat: { fullAccess: false, capMicrousd: null } } }, now);
+    });
+}