toolroll 0.9.97 → 0.9.99

package/dist/contracts/lead-tools.d.ts

@@ -756,6 +756,10 @@ export declare const LEAD_TOOL_INPUTS: {
         report: z.ZodOptional<z.ZodBoolean>;
         checks: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
+    readonly propose_start: z.ZodObject<{
+        repo: z.ZodString;
+        title: z.ZodString;
+    }, z.core.$strict>;
     readonly propose_sweep: z.ZodObject<{
         repo: z.ZodString;
         title: z.ZodString;
@@ -1567,6 +1571,10 @@ export declare const LEAD_TOOL_READ_INPUTS: {
         report: z.ZodOptional<z.ZodBoolean>;
         checks: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
+    readonly propose_start: z.ZodObject<{
+        repo: z.ZodString;
+        title: z.ZodString;
+    }, z.core.$strict>;
     readonly propose_sweep: z.ZodObject<{
         repo: z.ZodString;
         title: z.ZodString;
@@ -2212,6 +2220,15 @@ export declare const LEAD_TOOL_OUTPUTS: {
         kind: z.ZodLiteral<"task">;
         awaiting: z.ZodString;
     }, z.core.$loose>;
+    readonly propose_start: z.ZodObject<{
+        proposal: z.ZodNumber;
+        kind: z.ZodEnum<{
+            action: "action";
+            task: "task";
+        }>;
+        startsNow: z.ZodBoolean;
+        awaiting: z.ZodString;
+    }, z.core.$loose>;
     readonly propose_sweep: z.ZodObject<{
         proposal: z.ZodNumber;
         label: z.ZodString;

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/deploy-phase-data.json

@@ -0,0 +1,21 @@
+{
+  "phases": [
+    { "phase": "preparing", "action": "lift-pause", "flags": ["beforeSwap", "beforePause"] },
+    { "phase": "admission-paused", "action": "lift-pause", "flags": ["beforeSwap"] },
+    { "phase": "frozen", "action": "lift-pause", "flags": ["beforeSwap"] },
+    { "phase": "backup-verified", "action": "lift-pause", "flags": ["beforeSwap"] },
+    { "phase": "rehearsed", "action": "lift-pause", "flags": ["beforeSwap"] },
+    { "phase": "stopping", "action": "roll-back", "flags": [] },
+    { "phase": "stopped", "action": "roll-back", "flags": ["restartable"] },
+    { "phase": "migrating", "action": "roll-back", "flags": ["migrationStarted", "restartable"] },
+    { "phase": "migrated", "action": "roll-back", "flags": ["migrationStarted", "restartable"] },
+    { "phase": "starting", "action": "forward", "flags": [] },
+    { "phase": "started", "action": "forward", "flags": [] },
+    { "phase": "healthy", "action": "forward", "flags": [] },
+    { "phase": "start-failed", "action": "roll-back", "flags": ["migrationStarted", "restartable"] },
+    { "phase": "backup-restored", "action": "roll-back", "flags": ["restartable"] },
+    { "phase": "restored", "action": "roll-back", "flags": [] },
+    { "phase": "released", "action": "none", "flags": [] },
+    { "phase": "deployed", "action": "none", "flags": ["deployed"] }
+  ]
+}

package/dist/deploy-phase.d.ts

@@ -0,0 +1,37 @@
+/** What `toolroll release` does with a deployment that stopped at a phase; "refuse" for a word that is no phase. */
+export type DeployAction = "none" | "lift-pause" | "forward" | "roll-back" | "refuse";
+type RowAction = Exclude<DeployAction, "refuse">;
+type Flag = "beforeSwap" | "beforePause" | "migrationStarted" | "restartable" | "deployed";
+type Row = {
+    readonly phase: string;
+    readonly action: RowAction;
+    readonly flags: readonly Flag[];
+};
+/** The rows of a parsed data file, or an Error naming what is wrong with it. Never a partial table. */
+export declare function deployPhaseRows(data: unknown): readonly Row[];
+/** Every phase, in journal order. */
+export declare const DEPLOY_PHASES: readonly string[];
+export declare const isDeployPhase: (phase: unknown) => phase is string;
+/** The one action a journal's phase calls for; "refuse" for anything that is not a phase. */
+export declare const deployActionOf: (phase: unknown) => DeployAction;
+/** The word itself, or an Error: a journal is never written with a word the table does not hold. */
+export declare function assertDeployPhase(phase: string): string;
+/** The service was never stopped. */
+export declare const BEFORE_SWAP: readonly string[];
+/** Before the swap, with the pause in place. */
+export declare const PAUSED_BEFORE_SWAP: readonly string[];
+/** The candidate's store opened the live database, or the new service ran on it. */
+export declare const MIGRATION_STARTED: readonly string[];
+/** The old service is proved stopped: the previous definition may be started again. */
+export declare const RESTARTABLE: readonly string[];
+/** The new service may be running: never rolled back by a journal alone. */
+export declare const FORWARD_ONLY: readonly string[];
+/** Nothing is left to recover. Not the same as deployed: a released deployment never installed its runtime. */
+export declare const NEEDS_NO_RECOVERY: readonly string[];
+/** The deployment finished and its runtime is the installed one. */
+export declare const isDeployed: (phase: unknown) => boolean;
+/** Stopped where nothing was changed (before its pause), or with nothing left to do. */
+export declare const stoppedWhereNothingChanged: (phase: unknown) => boolean;
+/** The phase a lifted pause leaves behind (release-gate.ts). */
+export declare const RELEASED: string;
+export {};

package/dist/deploy-phase.js

@@ -0,0 +1,64 @@
+/**
+ * The phases of a browser deployment's journal, and what a stopped deployment at each one calls for.
+ *
+ * The rows are data: deploy-phase-data.json beside this file, the one authored list (the build copies it into dist,
+ * scripts/postbuild.mjs). The deploy scripts read the same file through scripts/deploy-phase-table.mjs, where each
+ * column is described. Both sides check its shape the same way; deploy-phase.test.ts holds them to each other and to
+ * its own hand-written expectations.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+const ACTIONS = ["none", "lift-pause", "forward", "roll-back"];
+const FLAGS = ["beforeSwap", "beforePause", "migrationStarted", "restartable", "deployed"];
+/** The rows of a parsed data file, or an Error naming what is wrong with it. Never a partial table. */
+export function deployPhaseRows(data) {
+    const rows = data?.phases;
+    if (!Array.isArray(rows) || rows.length === 0)
+        throw new Error("The deployment phase table has no rows.");
+    const seen = new Set();
+    return Object.freeze(rows.map((row) => {
+        const { phase, action, flags } = (row ?? {});
+        if (typeof phase !== "string" || !/^[a-z]+(-[a-z]+)*$/.test(phase) || seen.has(phase))
+            throw new Error(`The deployment phase table has a bad or repeated phase: ${String(phase)}.`);
+        if (typeof action !== "string" || !ACTIONS.includes(action))
+            throw new Error(`The deployment phase ${phase} has no known action.`);
+        if (!Array.isArray(flags) || flags.some(flag => typeof flag !== "string" || !FLAGS.includes(flag)) || new Set(flags).size !== flags.length)
+            throw new Error(`The deployment phase ${phase} has an unknown or repeated flag.`);
+        seen.add(phase);
+        return Object.freeze({ phase, action: action, flags: Object.freeze([...flags]) });
+    }));
+}
+// By path, not by URL: a test environment that stands in for a browser replaces the global URL.
+const ROWS = deployPhaseRows(JSON.parse(readFileSync(join(import.meta.dirname, "deploy-phase-data.json"), "utf8")));
+const rowOf = (phase) => typeof phase === "string" ? ROWS.find(row => row.phase === phase) : undefined;
+const withFlag = (flag) => Object.freeze(ROWS.filter(row => row.flags.includes(flag)).map(row => row.phase));
+const withAction = (action) => Object.freeze(ROWS.filter(row => row.action === action).map(row => row.phase));
+/** Every phase, in journal order. */
+export const DEPLOY_PHASES = Object.freeze(ROWS.map(row => row.phase));
+export const isDeployPhase = (phase) => rowOf(phase) !== undefined;
+/** The one action a journal's phase calls for; "refuse" for anything that is not a phase. */
+export const deployActionOf = (phase) => rowOf(phase)?.action ?? "refuse";
+/** The word itself, or an Error: a journal is never written with a word the table does not hold. */
+export function assertDeployPhase(phase) {
+    if (!isDeployPhase(phase))
+        throw new Error(`"${String(phase)}" is not a deployment phase; the journal was not written.`);
+    return phase;
+}
+/** The service was never stopped. */
+export const BEFORE_SWAP = withFlag("beforeSwap");
+/** Before the swap, with the pause in place. */
+export const PAUSED_BEFORE_SWAP = Object.freeze(ROWS.filter(row => row.flags.includes("beforeSwap") && !row.flags.includes("beforePause")).map(row => row.phase));
+/** The candidate's store opened the live database, or the new service ran on it. */
+export const MIGRATION_STARTED = withFlag("migrationStarted");
+/** The old service is proved stopped: the previous definition may be started again. */
+export const RESTARTABLE = withFlag("restartable");
+/** The new service may be running: never rolled back by a journal alone. */
+export const FORWARD_ONLY = withAction("forward");
+/** Nothing is left to recover. Not the same as deployed: a released deployment never installed its runtime. */
+export const NEEDS_NO_RECOVERY = withAction("none");
+/** The deployment finished and its runtime is the installed one. */
+export const isDeployed = (phase) => rowOf(phase)?.flags.includes("deployed") === true;
+/** Stopped where nothing was changed (before its pause), or with nothing left to do. */
+export const stoppedWhereNothingChanged = (phase) => { const row = rowOf(phase); return row !== undefined && (row.flags.includes("beforePause") || row.action === "none"); };
+/** The phase a lifted pause leaves behind (release-gate.ts). */
+export const RELEASED = assertDeployPhase("released");

package/dist/deploy-rescue.d.ts

@@ -1,5 +1,6 @@
+import { FORWARD_ONLY } from "./deploy-phase.js";
 /** Phases where the new service may be running: recovery leaves them to the release, which resumes forward. */
-export declare const FORWARD_ONLY: readonly string[];
+export { FORWARD_ONLY };
 export type RescueWorld = {
     /** The live database. */
     database: string;

package/dist/deploy-rescue.js

@@ -18,10 +18,9 @@
  */
 import { realpathSync } from "node:fs";
 import { join } from "node:path";
-import { BEFORE_SWAP } from "./release-gate.js";
+import { BEFORE_SWAP, FORWARD_ONLY, MIGRATION_STARTED, NEEDS_NO_RECOVERY, RESTARTABLE } from "./deploy-phase.js";
 /** Phases where the new service may be running: recovery leaves them to the release, which resumes forward. */
-export const FORWARD_ONLY = Object.freeze(["starting", "started", "healthy"]);
-const FINISHED = Object.freeze(["released", "deployed"]);
+export { FORWARD_ONLY };
 const real = (path) => { try {
     return realpathSync(path);
 }
@@ -39,8 +38,8 @@ export function rescuePlan(phase, journal) {
     if (phase === "stopping") {
         words.push("The old service must already be stopped. Recovery checks for remaining processes and refuses while any may still be running. Stop them through the service owner, then rerun recovery.");
     }
-    if (["stopping", "stopped", "migrating", "migrated", "start-failed", "backup-restored"].includes(phase)) {
-        if (["migrating", "migrated", "start-failed"].includes(phase))
+    if (phase === "stopping" || RESTARTABLE.includes(phase)) {
+        if (MIGRATION_STARTED.includes(phase))
             words.push("Puts the verified backup back first when the previous runtime can't read the migrated database.");
         words.push(`Starts the previous service (${prior}) again and waits for it to answer, past a stopped worker's heartbeat window; then lifts update pause ${id}.`);
     }
@@ -56,7 +55,7 @@ export async function rescueDeployment(stageArg, yes, world) {
             return { ok: false, reason: "usage", message: `${stageArg} is not a deployment stage of this installation (under ${join(world.stateDir, "staged-upgrades")}).` };
     }
     else {
-        const open = all.filter(one => one.journal === null || !FINISHED.includes(String(one.journal["phase"])));
+        const open = all.filter(one => one.journal === null || !NEEDS_NO_RECOVERY.includes(String(one.journal["phase"])));
         if (open.length === 0)
             return { ok: true, acted: false, stage: null, phase: null, words: ["Nothing to recover: every deployment finished or was already put back."] };
         if (open.length > 1)
@@ -74,7 +73,7 @@ export async function rescueDeployment(stageArg, yes, world) {
         return { ok: false, reason: "conflict", message: `That deployment ran on ${String(journal["database"])}, not ${world.database}; nothing was changed.` };
     if (!Number.isSafeInteger(run) || run < 1)
         return { ok: false, reason: "damaged", message: `${join(stage, "deployment.json")} names no builder run, so its commit's recovery can't be found; nothing was changed.` };
-    if (FINISHED.includes(phase))
+    if (NEEDS_NO_RECOVERY.includes(phase))
         return { ok: true, acted: false, stage, phase, words: [`Nothing to recover: that deployment is ${phase}.`] };
     if (FORWARD_ONLY.includes(phase)) {
         return { ok: false, reason: "forward", message: `That deployment is at ${phase}: the new service may be running, so nothing was stopped. Continue it forward with \`toolroll release <branch>\` (it resumes the deployment's finish).` };

package/dist/desktop-update.d.ts

@@ -97,20 +97,20 @@ export declare function sqliteLock(file: string, busyTimeoutMs?: number): Databa
 export declare function lockHeld(file: string): boolean;
 export declare const installationLock: (j: UpdateJournal) => DatabaseSync | null;
 export declare function desktopUpdateStatus(stateDir: string): {
-    version?: never;
+    error?: never;
     active: boolean;
     phase: string;
     detail: string;
     running: boolean;
     canResume: boolean;
     canCancel: boolean;
-    error?: never;
     automaticRecovery?: never;
     recoveryAttempts?: never;
     recoveryRepairs?: never;
     wasRunning?: never;
     backupPath?: never;
     updateId?: never;
+    version?: never;
     buildId?: never;
     workDir?: never;
 } | {

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);
+    });
+}