toolroll 0.9.97 → 0.9.98

package/dist/browser-workspace.d.ts

@@ -1660,7 +1660,7 @@ export type BrowserWorkspace = {
     };
 };
 /** Home ("/"): one sentence that answers "what needs me?", four counts that agree with the Tasks filters they open,
- * what waits on this person grouped by what it asks, what is running, and the selected item answered in place. */
+ * the work grouped as Waiting on you, Working and Done, and the selected item answered in place. */
 export type BrowserHomeView = {
     kind: 'home';
     /** "7 need you across 2 projects.", derived from the same counts as the figures. */
@@ -1679,12 +1679,13 @@ export type BrowserHomeView = {
         value: number;
         href: string;
     }[];
+    /** The work in three groups, in this order (home-groups.ts): Waiting on you, Working, Done (finished in the last 7 days). */
     groups: {
-        key: 'decide' | 'review' | 'unblock' | 'running' | 'waiting';
+        key: 'you' | 'working' | 'done';
         label: string;
         rows: BrowserHomeRow[];
     }[];
-    /** More waits than the list shows: open them all in Tasks. */
+    /** More waits on you than the list shows: open them all in Tasks. */
     more: {
         count: number;
         href: string;

package/dist/chat-actions.d.ts

@@ -1,4 +1,5 @@
 import { type Authority } from "./local-owner.js";
+import { type CardChannel } from "./chat-terms.js";
 import { type Store } from "./store.js";
 import { type VerifiedApprover } from "./principal.js";
 import { CHAT_ACTION_FIELDS, type SharedAction } from "./contracts/chat-actions.js";
@@ -354,6 +355,11 @@ export declare const CHAT_ACTIONS: {
         readonly protected: true;
         readonly password: false;
     };
+    readonly task_start: {
+        readonly label: "Start work";
+        readonly protected: true;
+        readonly password: false;
+    };
 };
 export type ChatAction = keyof typeof CHAT_ACTIONS;
 /** Approvals (owner's decision, docs/plans/toolroll-cards.md): a person's own yes from their chat stands without a password.
@@ -368,19 +374,28 @@ export declare const OWNER_ACTIONS: ReadonlySet<ChatAction>;
 export declare function isChatAction(value: unknown): value is ChatAction;
 /** No writes, including at preview. Store-derived snapshots are never accepted
  * from a model. Rebuilding the same request before execution catches changes. */
-export declare function prepareSharedAction(store: Store, who: VerifiedApprover, operation: ChatAction, input: Record<string, unknown>, root?: string, now?: Date): SharedAction;
+export declare function prepareSharedAction(store: Store, who: VerifiedApprover, operation: ChatAction, input: Record<string, unknown>, root?: string, now?: Date, 
+/** The lead turn the card is (or is being) drafted in: a Start card's preview must have been prepared in it. Read
+ * from the proposal row (or the running turn), never from the request. */
+turn?: number): SharedAction;
 /** A saved proposal's action, read by its schema (contracts/chat-actions.ts); null when it can't be read. */
 export declare function sharedActionPayload(value: unknown): SharedAction | null;
 export declare function sharedActionNeedsReview(action: SharedAction): boolean;
-/** Whether a paired phone may confirm this protected action behind its own
+/** Whether a linked chat may confirm this protected action behind its own
  * explicit challenge: the action is on the challenge list, needs no
- * password, and every term fits the card unshortened. */
-export declare function sharedActionAllowsChallenge(action: SharedAction): boolean;
+ * password, and every term fits the card unshortened. An approval's yes is
+ * a yes to the words the card showed (they are sealed as shown), so it also
+ * needs a chat app that shows them exactly as stored (shownAsWritten: never
+ * Teams, whose card reads Markdown; not Slack when a word would become an
+ * emoji). There the card links to the review page and no tap approves. The
+ * chat app is the one the card is drawn for or the tap came through, never
+ * something the action or a caller's input names. */
+export declare function sharedActionAllowsChallenge(action: SharedAction, channel: CardChannel): boolean;
 export declare function sharedActionReviewPath(id: number): string;
 export declare function mintSharedActionReview(store: Store, who: VerifiedApprover, id: number, root: string, now: Date): {
     payload: {
         version: 1;
-        operation: "code_map_holdout_end" | "code_map_switch" | "decision_record" | "decision_retire" | "finding_resend" | "finding_send" | "flow_archive" | "flow_browser" | "flow_browser_off" | "flow_card_add" | "flow_card_approve" | "flow_card_assign" | "flow_card_cancel" | "flow_card_choose" | "flow_card_comment" | "flow_card_move" | "flow_card_send_back" | "flow_card_watch" | "flow_create" | "flow_edit" | "flow_script_save" | "flow_starter" | "flow_trigger_add" | "flow_trigger_pause" | "flow_trigger_remove" | "flow_trigger_resume" | "flow_unattended" | "flow_unattended_off" | "incident_resolve" | "kit_setup" | "knowledge_instructions" | "knowledge_remove" | "knowledge_restore" | "knowledge_save" | "lead_about_you" | "lead_identity" | "memory_decide" | "mode_revoke" | "provider_resume" | "result_accept" | "revision_accept" | "revision_reject" | "scope_approve" | "skill_disable" | "skill_enable" | "skill_import" | "skill_restore" | "skill_test" | "subagent_answer" | "subagent_ask" | "subagent_create" | "subagent_memory" | "subagent_note" | "subagent_routine" | "subagent_soul" | "subagent_state" | "subagent_tools" | "subagent_undo" | "suggestion_not_now" | "sweep_cancel_rest" | "sweep_file" | "task_archive" | "task_cancel" | "task_reopen" | "task_restore" | "task_resume" | "tool_add" | "tool_remove" | "trial_stop" | "worker_note";
+        operation: "code_map_holdout_end" | "code_map_switch" | "decision_record" | "decision_retire" | "finding_resend" | "finding_send" | "flow_archive" | "flow_browser" | "flow_browser_off" | "flow_card_add" | "flow_card_approve" | "flow_card_assign" | "flow_card_cancel" | "flow_card_choose" | "flow_card_comment" | "flow_card_move" | "flow_card_send_back" | "flow_card_watch" | "flow_create" | "flow_edit" | "flow_script_save" | "flow_starter" | "flow_trigger_add" | "flow_trigger_pause" | "flow_trigger_remove" | "flow_trigger_resume" | "flow_unattended" | "flow_unattended_off" | "incident_resolve" | "kit_setup" | "knowledge_instructions" | "knowledge_remove" | "knowledge_restore" | "knowledge_save" | "lead_about_you" | "lead_identity" | "memory_decide" | "mode_revoke" | "provider_resume" | "result_accept" | "revision_accept" | "revision_reject" | "scope_approve" | "skill_disable" | "skill_enable" | "skill_import" | "skill_restore" | "skill_test" | "subagent_answer" | "subagent_ask" | "subagent_create" | "subagent_memory" | "subagent_note" | "subagent_routine" | "subagent_soul" | "subagent_state" | "subagent_tools" | "subagent_undo" | "suggestion_not_now" | "sweep_cancel_rest" | "sweep_file" | "task_archive" | "task_cancel" | "task_reopen" | "task_restore" | "task_resume" | "task_start" | "tool_add" | "tool_remove" | "trial_stop" | "worker_note";
         request: {
             [x: string]: unknown;
         };
@@ -408,7 +423,17 @@ export type SharedActionOptions = {
     person?: boolean;
     /** A linked chat's own binding: which chat the yes came from, for the ledger. */
     binding?: number;
+    /** A typed yes to a Start card on Telegram (one-step-chat.md C5): the inbound message that was the yes. The only other
+     * way past the "confirm this" gate, for `task_start` alone, on Telegram alone, and only while that message's unsettled
+     * typed-yes record names this proposal (typedStartOpens). It is never `confirm`, mints no review and changes no `via`. */
+    typedStart?: {
+        provider: string;
+        event: string;
+    };
 };
+/** Whether a typed yes may stand in for the challenge's tap on this action: a Start card, on Telegram, a person (never a
+ * machine), terms whole on the card, and an unsettled typed-yes record naming exactly this proposal. */
+export declare function typedStartOpens(store: Store, proposal: number, action: SharedAction, options: Pick<SharedActionOptions, "via" | "typedStart" | "authority">): boolean;
 /** Called inside the proposal door's transaction, after ownership and session
  * checks. No password or review receipt is ever part of a saved proposal. */
 export declare function executeSharedAction(store: Store, who: VerifiedApprover, id: number, payload: SharedAction, now: Date, options: SharedActionOptions): {
@@ -423,3 +448,13 @@ export declare function executeSharedAction(store: Store, who: VerifiedApprover,
     reason: "needs-confirm" | "stale" | "refused";
     said: string;
 };
+/**
+ * A value safe to paste into a shell as ONE word, single-quoted, or null. The value is model- or person-written (the
+ * lead's title, a project path), so only a strict allowlist passes: letters, digits, spaces and `. , : _ / - ( ) + # @`,
+ * 1 to 120 characters, no leading `-`. Anything else (quotes, backticks, `$`, `\`, newlines, globs, redirections…) is
+ * null, and the caller shows a placeholder instead.
+ */
+export declare function shellWordOrNull(text: string): string | null;
+/** Where `toolroll chat` sends a Start card: the terminal's own fast start, with the words the lead drafted when they are
+ * safe to paste as one shell word, else the placeholders. Never a value unquoted or in double quotes. */
+export declare function startFromTerminalWords(store: Store, action: Pick<SharedAction, "repo" | "state">): string;

package/dist/chat-actions.js

@@ -23,7 +23,10 @@ import { authPauseOf, liftAuthPause } from "./provider-auth.js";
 import { isProviderId } from "./provider.js";
 import { approverStandsNow, familyRepoOf } from "./tidy.js";
 import { chatApproveMode, effectiveChatApproval } from "./chat-approval.js";
-import { cardTermsDigest, chatLimitProblem, scopeTermsText } from "./chat-terms.js";
+import { cardTermsDigest, chatLimitProblem, scopeTermsText, shownAsWritten } from "./chat-terms.js";
+import { chatStartDryRun, chatStartPreview, fastRefusalWords, fastStartBuild, FAST_MAX_FILES, FAST_MAX_LINES } from "./fast-start.js";
+import { fastTermsLines } from "./fast-terms.js";
+import { TYPED_START_REFUSED, typedStartNames } from "./typed-start.js";
 import { createHash, randomBytes } from "node:crypto";
 import { archiveTaskFamily, leadTurnKeepsProposals, restoreTaskFamily, verifiedAuthor } from "./store.js";
 import { isVerifiedApprover, reproveApprover, } from "./principal.js";
@@ -176,13 +179,16 @@ export const CHAT_ACTIONS = {
     result_accept: { label: "Accept", protected: true, password: false },
     task_cancel: { label: "Cancel task", protected: true, password: false },
     task_resume: { label: "Resume task", protected: true, password: false },
+    // One-step start from chat (docs/plans/one-step-chat.md C2): files and approves one small task the lead drafted, under
+    // exactly the fast start rules. Only the lead's turn loop drafts one (propose_start); a person's own yes starts it.
+    task_start: { label: "Start work", protected: true, password: false },
 };
 // Every action has a schema (contracts/chat-actions.ts) and every schema an action: a mismatch fails to compile.
 const SAME_ACTIONS = true;
 void SAME_ACTIONS;
 /** Approvals (owner's decision, docs/plans/toolroll-cards.md): a person's own yes from their chat stands without a password.
  * Only a person's tap in a linked chat, or their click in a signed-in browser, ever runs one. */
-export const APPROVAL_ACTIONS = new Set(["scope_approve", "task_resume", "sweep_file", "flow_browser", "task_reopen", "revision_accept", "revision_reject", "flow_unattended"]);
+export const APPROVAL_ACTIONS = new Set(["scope_approve", "task_resume", "sweep_file", "flow_browser", "task_reopen", "revision_accept", "revision_reject", "flow_unattended", "task_start"]);
 /** Protected actions a linked chat may confirm behind its own explicit yes/cancel challenge instead of the review screen.
  * Password actions and long or redacted terms never qualify: the card must show the exact terms. */
 export const APPROVAL_TERM_CHARS = 3000;
@@ -296,7 +302,10 @@ function flowDrawingOf(store, input, repo) {
 const quoted = (value) => `“${value}”`;
 /** No writes, including at preview. Store-derived snapshots are never accepted
  * from a model. Rebuilding the same request before execution catches changes. */
-export function prepareSharedAction(store, who, operation, input, root, now = new Date()) {
+export function prepareSharedAction(store, who, operation, input, root, now = new Date(), 
+/** The lead turn the card is (or is being) drafted in: a Start card's preview must have been prepared in it. Read
+ * from the proposal row (or the running turn), never from the request. */
+turn) {
     if (!isChatAction(operation))
         throw Error("Choose an available action.");
     // The action's own schema: its fields and their kinds, refused by path. The request itself is used as given, so a
@@ -334,7 +343,7 @@ export function prepareSharedAction(store, who, operation, input, root, now = ne
         const stamp = hash({ operation, request, repo: "", state, terms, actor: who.name, generation: who.generation, ceiling: who.ceilingDigest });
         return { version: SHARED_ACTION_VERSION, operation, request, repo: "", title, terms, stamp, state };
     }
-    const task = operation === "mode_revoke" || operation === "memory_decide" || operation === "incident_resolve" || operation === "finding_resend" || operation.startsWith("code_map_") || operation.startsWith("skill_") || operation.startsWith("knowledge_") || operation.startsWith("decision_") || operation.startsWith("tool_") || operation.startsWith("flow_") || operation.startsWith("subagent_") || operation.startsWith("kit_") || operation.startsWith("sweep_") || operation.startsWith("suggestion_") || operation.startsWith("trial_")
+    const task = operation === "mode_revoke" || operation === "memory_decide" || operation === "incident_resolve" || operation === "finding_resend" || operation.startsWith("code_map_") || operation.startsWith("skill_") || operation.startsWith("knowledge_") || operation.startsWith("decision_") || operation.startsWith("tool_") || operation.startsWith("flow_") || operation.startsWith("subagent_") || operation.startsWith("kit_") || operation.startsWith("sweep_") || operation.startsWith("suggestion_") || operation.startsWith("trial_") || operation === "task_start"
         ? null
         : text(input, "task", 64);
     const flowTarget = operation.startsWith("flow_") && operation !== "flow_create" && operation !== "flow_script_save" && operation !== "flow_starter" ? flowTargetOf(store, input) : null;
@@ -636,6 +645,31 @@ export function prepareSharedAction(store, who, operation, input, root, now = ne
             terms.push(question.question, `Your answer: ${[choice?.label, said].filter(Boolean).join(" — ")}`);
         }
     }
+    else if (operation === "task_start") {
+        // A Start card (docs/plans/one-step-chat.md C2). The preview is the one the lead's turn loop prepared in this card's
+        // own turn, for this person, on chat (never an id the model chose: the request only names it back), unexpired and
+        // unused. Every word below is Toolroll's, from a filing dry-run in a savepoint that is always rolled back, with the
+        // fast start rules read on it: the tap files again, and the stamp, approve()'s digest and its whole-terms check refuse
+        // anything that differs.
+        const preview = text(input, "preview", 64);
+        const saved = turn === undefined ? null : chatStartPreview(store, preview, who.name, turn, now);
+        if (saved === null || saved.repo !== repo)
+            throw Error("This expired. Ask again.");
+        const read = chatStartDryRun(store, { actor: who.name, repo, title: saved.title, taskId: saved.taskId, sizing: saved.sizing }, now);
+        if (!read.ok)
+            throw Error(`${fastRefusalWords(read.reason)} Ask for an ordinary task instead.`);
+        if (read.scope.digest !== saved.digest)
+            throw Error("This changed since it was drafted. Ask again.");
+        const authority = scopeAuthorityOf(read.scope, { authMode: readAuthModeStrict });
+        if (!authority.ok)
+            throw Error(authority.problem);
+        state = { preview, taskId: saved.taskId, digest: read.scope.digest };
+        const project = repo.split(/[\\/]/).filter(Boolean).at(-1) ?? repo;
+        title = `Start work in ${project}: ${saved.title}`;
+        terms.push(`Starts now as a small change. If it grows past ${FAST_MAX_FILES} files or ${FAST_MAX_LINES} changed lines, it waits for you to approve it again.`, 
+        // The goal and its one success test are the lead's words, shown exactly and labelled as the lead's.
+        `Written by the lead from your request: ${quoted(saved.title)}`, scopeTermsText(read.scope), ...fastTermsLines(store, read.scope, repo).map(line => `${line.label}: ${line.words}`), `Agent permissions and limits\n${runtimeTerms(authority.profile)}\n${authority.authMode === "api-key" ? "Uses your API key; spend is charged to that account." : authority.authMode === "subscription" ? "Uses your subscription login." : ""}`);
+    }
     else if (operation === "sweep_cancel_rest") {
         // Exactly the items open now: if any settles or starts in between, the card is stale and a fresh one is needed.
         const table = sweepTable(store, integer(input, "sweep"), now, who.repos);
@@ -1144,15 +1178,22 @@ export function sharedActionNeedsReview(action) {
     return (CHAT_ACTIONS[action.operation].protected ||
         sharedActionContentNeedsReview(action));
 }
-/** Whether a paired phone may confirm this protected action behind its own
+/** Whether a linked chat may confirm this protected action behind its own
  * explicit challenge: the action is on the challenge list, needs no
- * password, and every term fits the card unshortened. */
-export function sharedActionAllowsChallenge(action) {
+ * password, and every term fits the card unshortened. An approval's yes is
+ * a yes to the words the card showed (they are sealed as shown), so it also
+ * needs a chat app that shows them exactly as stored (shownAsWritten: never
+ * Teams, whose card reads Markdown; not Slack when a word would become an
+ * emoji). There the card links to the review page and no tap approves. The
+ * chat app is the one the card is drawn for or the tap came through, never
+ * something the action or a caller's input names. */
+export function sharedActionAllowsChallenge(action, channel) {
     const config = CHAT_ACTIONS[action.operation];
     return (CHALLENGE_ACTIONS.has(action.operation) &&
         config.protected &&
         !config.password &&
-        !sharedActionContentNeedsReview(action));
+        !sharedActionContentNeedsReview(action) &&
+        (!APPROVAL_ACTIONS.has(action.operation) || shownAsWritten([action.title, ...action.terms].join("\n"), channel)));
 }
 export function sharedActionReviewPath(id) {
     return `/chat/action/${id}`;
@@ -1200,7 +1241,7 @@ function sameSharedAction(store, who, live, saved) {
 }
 export function mintSharedActionReview(store, who, id, root, now) {
     const payload = savedActionContext(store, who, id, "pending");
-    const live = prepareSharedAction(store, who, payload.operation, payload.request, root, now);
+    const live = prepareSharedAction(store, who, payload.operation, payload.request, root, now, store.getLeadProposal(id)?.turn);
     if (!sameSharedAction(store, who, live, payload))
         throw Error("This action changed. Ask for a fresh proposal.");
     const nonce = randomBytes(24).toString("hex");
@@ -1215,6 +1256,13 @@ export function mintSharedActionReview(store, who, id, root, now) {
         throw Error("Too many reviews are open. Close older reviews and try again.");
     return { payload: live, nonce };
 }
+/** Whether a typed yes may stand in for the challenge's tap on this action: a Start card, on Telegram, a person (never a
+ * machine), terms whole on the card, and an unsettled typed-yes record naming exactly this proposal. */
+export function typedStartOpens(store, proposal, action, options) {
+    const typed = options.typedStart;
+    return typed !== undefined && action.operation === "task_start" && options.via === "telegram" && typed.provider === "telegram"
+        && options.authority !== "local-owner" && !machineActing() && sharedActionAllowsChallenge(action, "telegram") && typedStartNames(store, typed, proposal);
+}
 /** Called inside the proposal door's transaction, after ownership and session
  * checks. No password or review receipt is ever part of a saved proposal. */
 export function executeSharedAction(store, who, id, payload, now, options) {
@@ -1231,7 +1279,7 @@ export function executeSharedAction(store, who, id, payload, now, options) {
         drafted = saved;
         if (hash(saved) !== hash(payload))
             return refuse("refused", "This action does not match the saved proposal.");
-        live = prepareSharedAction(store, who, saved.operation, saved.request, options.root, now);
+        live = prepareSharedAction(store, who, saved.operation, saved.request, options.root, now, store.getLeadProposal(id)?.turn);
         if (!sameSharedAction(store, who, live, saved))
             return refuse("stale", "This action changed. Ask for a fresh proposal.");
     }
@@ -1244,10 +1292,13 @@ export function executeSharedAction(store, who, id, payload, now, options) {
     const savedStamp = payload.stamp;
     payload = live;
     const config = CHAT_ACTIONS[live.operation], req = live.request;
+    // A typed yes (C5) is checked on the live action and the live record; any use it doesn't open refuses.
+    const typed = typedStartOpens(store, id, payload, options);
+    if (options.typedStart !== undefined && !typed)
+        return refuse("refused", TYPED_START_REFUSED);
     const challenged = options.via !== "web" &&
         options.via !== "cli" &&
-        options.confirm === true &&
-        sharedActionAllowsChallenge(payload);
+        ((options.confirm === true && sharedActionAllowsChallenge(payload, options.via)) || typed);
     if (APPROVAL_ACTIONS.has(live.operation) && machineActing())
         return refuse("needs-confirm", "Only a person approves this.");
     // A lead's or remote token reaches the same web door: an approval needs a person's own session (or tap, above).
@@ -1330,6 +1381,10 @@ export function executeSharedAction(store, who, id, payload, now, options) {
                 const said = cancelSweepRest(store, who.name, payload.state["open"], now, "web");
                 return { ok: true, taskId: null, said, href: `/sweeps/${Number(req["sweep"])}` };
             }
+            else if (payload.operation === "task_start") {
+                const started = startFromCard(store, who, id, drafted, options, now);
+                return { ok: true, taskId: started, said: "Started. It's building now.", href: `/t/${encodeURIComponent(started)}` };
+            }
             else if (payload.operation === "sweep_file") {
                 const done = fileSweep(store, who, id, payload, approvalBy(store, who, payload.repo, now, options, drafted), now);
                 return { ok: true, taskId: null, said: done.said, href: done.href };
@@ -1452,7 +1507,7 @@ export function executeSharedAction(store, who, id, payload, now, options) {
                 return {
                     ok: true,
                     taskId,
-                    said: `Stop released. ${result.gate ? "Other requirements still prevent the next attempt." : "The next attempt may start."}`,
+                    said: `Stop lifted. ${result.gate ? "Something else still holds the next attempt." : "The next attempt may start."}`,
                 };
             }
             const said = payload.operation === "skill_test"
@@ -1550,6 +1605,62 @@ function sweepChildScopes(store, who, repo, brief, items, acceptance, now) {
     });
     return found;
 }
+/**
+ * A Start card's yes (docs/plans/one-step-chat.md C2): file and approve in one step through fastStartBuild, in this
+ * action's savepoint. Two proofs of the person and no third: their own yes from chat (approvalBy gives `chat`, with the
+ * card's whole words and their digest), under their own chat limits; or this computer's local owner on web chat, whose
+ * approve() proves the owner itself and allows `build-now` only with a fast marker. Anything else refuses, and a refusal
+ * throws, taking the filing back.
+ */
+function startFromCard(store, who, proposal, drafted, options, now) {
+    // `toolroll chat` keeps refusing approvals; a Start card names the terminal's own fast start instead.
+    if (options.via === "cli")
+        throw Error(startFromTerminalWords(store, drafted));
+    const by = approvalBy(store, who, drafted.repo, now, options, drafted);
+    if (by.ok === false)
+        throw Error(by.why);
+    let proof, approveNow;
+    if (by.chat !== undefined) {
+        const chat = by.chat;
+        proof = { chat: by.limits };
+        // A typed yes (C5) is recorded beside the fast marker: which message was the yes. The executor's gate has proved it.
+        const typed = options.typedStart;
+        approveNow = (taskId, saw, fast) => approve(store, taskId, who.name, now, saw, "", {}, typed === undefined ? fast : { ...fast, typed: { provider: typed.provider, event: typed.event } }, chat);
+    }
+    else if (options.authority === "local-owner" && currentLocalOwner() !== null) {
+        proof = { password: { localOwner: true, passwordless: false, freshAt: null, returnTo: "/chat" } };
+        approveNow = (taskId, saw, fast) => approve(store, taskId, who.name, now, saw, "", {}, fast);
+    }
+    else
+        throw Error("Only a person starts work this way.");
+    const turn = store.getLeadProposal(proposal)?.turn;
+    const built = fastStartBuild(store, { preview: String(drafted.state["preview"] ?? ""), digest: String(drafted.state["digest"] ?? ""), actor: who.name, via: "chat",
+        ...(turn === undefined ? {} : { turn }), proof, approveNow }, now);
+    if (!built.ok)
+        throw Error(built.message);
+    return built.taskId;
+}
+/**
+ * A value safe to paste into a shell as ONE word, single-quoted, or null. The value is model- or person-written (the
+ * lead's title, a project path), so only a strict allowlist passes: letters, digits, spaces and `. , : _ / - ( ) + # @`,
+ * 1 to 120 characters, no leading `-`. Anything else (quotes, backticks, `$`, `\`, newlines, globs, redirections…) is
+ * null, and the caller shows a placeholder instead.
+ */
+export function shellWordOrNull(text) {
+    if (text.length < 1 || text.length > 120 || text.startsWith("-"))
+        return null;
+    if (!/^[\p{L}\p{N} .,:_/()+#@-]+$/u.test(text))
+        return null;
+    return `'${text}'`;
+}
+/** Where `toolroll chat` sends a Start card: the terminal's own fast start, with the words the lead drafted when they are
+ * safe to paste as one shell word, else the placeholders. Never a value unquoted or in double quotes. */
+export function startFromTerminalWords(store, action) {
+    const row = store.handle.prepare("SELECT title FROM fast_preview WHERE id = ?").get(String(action.state["preview"] ?? ""));
+    const title = row === undefined ? null : shellWordOrNull(String(row["title"]));
+    const project = shellWordOrNull(action.repo);
+    return `Start it from the terminal with \`toolroll task new ${title ?? "\"<title>\""} --repo ${project ?? "<project>"}\`.`;
+}
 /** How this yes stands, and under whose limits: a person's own from chat, by their own chat setting, with the words and
  * digest the card was made with. A local owner's road has none: approve() proves it itself. */
 function approvalBy(store, who, repo, now, options, drafted) {

package/dist/chat-card.js

@@ -93,7 +93,10 @@ export function isCardProposal(proposal) {
 export const cardPlainOf = (proposal) => typeof proposal.payload["plain"] === "string" ? proposal.payload["plain"] : "This card can't be shown.";
 /** Cards before the proposals they lead to, so each Confirm sits under its card. */
 export function cardsFirst(proposals) {
-    return [...proposals.filter(isCardProposal), ...proposals.filter(one => !isCardProposal(one))];
+    // A Start card goes last (docs/plans/one-step-chat.md C5): nothing Toolroll sends for the turn comes after it.
+    const start = (one) => one.kind === "action" && one.payload["operation"] === "task_start";
+    const rest = proposals.filter(one => !start(one));
+    return [...rest.filter(isCardProposal), ...rest.filter(one => !isCardProposal(one)), ...proposals.filter(start)];
 }
 /** A card goes only where every project behind it is still reachable. */
 export const cardWithin = (card, repos) => card.repos.every(one => repos.includes(one));

package/dist/chat-channel.d.ts

@@ -121,3 +121,6 @@ export declare function handoffCardText(text: string, note: string | null): stri
  * a signed mode asks for nothing more. A staged resume says what remains.
  */
 export declare function confirmedCardText(store: Store, outcome: DoorOutcome, proposal: LeadProposal, note: string | null): string;
+/** The link to a task a Start card just started (a tapped card, and Toolroll's reply to a typed yes): the task's own
+ * page, only while the task is one of the person's projects. Navigation only. */
+export declare function startedTaskLink(store: Store, taskId: string, repos: readonly string[]): PhoneLink | null;

package/dist/chat-channel.js

@@ -1,5 +1,6 @@
 import { parseFeedbackImage } from "./result-review.js";
 /** Shared membership-chat identity, proposal previews and result links. Transport adapters never grant authority. */
+import { TYPED_START_LINE } from "./typed-start.js";
 import { FLOW_HREF } from "./flow-engine.js";
 import { closedQuestionWords, LIMITS } from "./decision.js";
 import { createHash } from "node:crypto";
@@ -225,8 +226,8 @@ export function proposalLink(store, proposal, repos, channel = null) {
         return action &&
             repos.includes(action.repo) &&
             sharedActionNeedsReview(action) &&
-            !(channel !== null && sharedActionAllowsChallenge(action))
-            ? { label: "Review action", path: sharedActionReviewPath(proposal.id) }
+            !(channel !== null && sharedActionAllowsChallenge(action, channel))
+            ? { label: action.operation === "task_start" ? "Review and start" : "Review action", path: sharedActionReviewPath(proposal.id) }
             : null;
     }
     const task = typeof payload["task"] === "string" ? payload["task"] : "";
@@ -281,8 +282,9 @@ export function confirmedLink(store, outcome, proposal, repos) {
         return { label: "Open the flow", path: outcome.href };
     if (!outcome.ok || outcome.taskId === null)
         return null;
+    // A skill test's task, and the task a Start card started: the card opens it.
     if (proposal.kind === "action" &&
-        proposal.payload["operation"] === "skill_test")
+        (proposal.payload["operation"] === "skill_test" || proposal.payload["operation"] === "task_start"))
         return taskLink(store, outcome.taskId, repos);
     const staged = proposal.kind === "task" ||
         proposal.kind === "scope" ||
@@ -315,7 +317,9 @@ export function proposalPreview(store, proposal, repos, channel = null) {
     })();
     // Telegram's card leads with the action and what confirming does, then the exact terms; its buttons say the rest.
     const phone = channel === "telegram";
-    const card = (headline, body = [], consequence = null) => ({
+    const card = (headline, body = [], consequence = null, 
+    /** Telegram only: a fixed last line outside the terms (a Start card's "reply yes", one-step-chat.md C5). */
+    last = null) => ({
         text: (phone
             ? [
                 headline,
@@ -323,6 +327,7 @@ export function proposalPreview(store, proposal, repos, channel = null) {
                 ...(body.length === 0 ? [] : ["", ...body]),
                 "",
                 "Nothing changes until you confirm.",
+                ...(last === null ? [] : [last]),
             ]
             : [
                 headline,
@@ -345,8 +350,10 @@ export function proposalPreview(store, proposal, repos, channel = null) {
             const action = sharedActionPayload(payload);
             if (!action)
                 return handoff("This action is unavailable.");
-            if (channel !== null && sharedActionAllowsChallenge(action))
-                return card(phoneText(action.title, 200), action.terms.map((term) => phoneText(term, APPROVAL_TERM_CHARS)), "Confirm asks once more before anything is recorded.");
+            if (channel !== null && sharedActionAllowsChallenge(action, channel))
+                return card(phoneText(action.title, 200), action.terms.map((term) => phoneText(term, APPROVAL_TERM_CHARS)), "Confirm asks once more before anything is recorded.", 
+                // A Start card on Telegram says what a typed yes does; no part of the lead's reply is ever inspected for it.
+                action.operation === "task_start" && channel === "telegram" ? TYPED_START_LINE : null);
             return sharedActionNeedsReview(action)
                 ? handoff(phoneText(action.title, 200), [
                     "Review the full details and confirm this exact action.",
@@ -652,6 +659,11 @@ export const CHAT_ACTION_PARITY = {
         how: "Card with Confirm/Dismiss through confirmLeadProposal (filed as a lead proposal, via telegram). The confirmed card links Review & start for the filed task while its scope waits; under a signed automatic mode it says the scope is approved and links the task.",
         gap: "Under manual approval the plan then needs the person's own yes, on its card.",
     },
+    propose_start: {
+        support: "direct",
+        how: "A protected shared action (task_start): Start work arms Yes and Cancel, and the person's own Yes files and approves one small task under the fast start rules (fastStartBuild), or a typed yes as a reply to the card or as the very next message. When Toolroll can't start it right away it is an ordinary task card.",
+        gap: "Terms too long for one message open the review page, in the signed-in console.",
+    },
     propose_sweep: {
         support: "direct",
         how: "A protected shared action (sweep_file): the card lists every item, the shared rules and the success test; confirming files them all and approves each scope.",
@@ -763,7 +775,7 @@ export function confirmedCardText(store, outcome, proposal, note) {
     // a revision; under a signed automatic mode the recorded scope is already
     // approved, and the card says that instead of asking again.
     const words = proposal.kind === "task" && state === "approved"
-        ? `${said.split(" — ")[0]} — approved under your automatic approval settings; nothing more is needed from you.`
+        ? `${said.split(/ — |\. /)[0]} — approved under your automatic approval settings; nothing more is needed from you.`
         : revise && state === "approved"
             ? "Revision created under your automatic approval settings."
             : said;
@@ -775,3 +787,8 @@ export function confirmedCardText(store, outcome, proposal, note) {
     const setup = (approval || resume) && note !== null ? note : "";
     return [`✓ ${words}`, ...[next, setup].filter((one) => one !== "")].join("\n\n");
 }
+/** The link to a task a Start card just started (a tapped card, and Toolroll's reply to a typed yes): the task's own
+ * page, only while the task is one of the person's projects. Navigation only. */
+export function startedTaskLink(store, taskId, repos) {
+    return taskLink(store, taskId, repos);
+}

package/dist/chat-decide.js

@@ -33,7 +33,7 @@ import { gateWords } from "./approval-policy.js";
 import { releaseCardOf } from "./release-card.js";
 import { releaseCiHoldOf, releaseCiHoldWords } from "./release-ci-hold.js";
 import { phoneText, projectLabel } from "./telegram-status.js";
-import { cardTermsDigest, chatLimitProblem, permissionPlainWords, scopeTermsText, shownTermsDigest } from "./chat-terms.js";
+import { cardTermsDigest, chatLimitProblem, permissionPlainWords, scopeTermsText, shownAsWritten, shownTermsDigest } from "./chat-terms.js";
 import { chainTermsLines } from "./scope.js";
 import { YOUIYOUX_CARD_KIND, YOUIYOUX_FILED_VIA, YOUIYOUX_HOME_PATH } from "./contracts/youiyoux-request.js";
 import { FILED_PER_PASS, requestKindWord, requestPassOf } from "./youiyoux-intake.js";
@@ -191,9 +191,11 @@ function listedOf(digest) {
  * (after its escapes) Discord's limits, with room for the question a tap adds. Teams draws card text as Markdown, where
  * a link's label hides its address, and Slack turns `:name:` into an emoji: there such words never approve. */
 export function shownWhole(text, channel) {
+    if (!shownAsWritten(text, channel))
+        return false;
     switch (channel) {
         case "telegram": return text.length + ROOM <= 3_900;
-        case "slack": return text.length + ROOM <= PLATFORM_LIMITS.slack && !/:[a-z0-9_+'-]+:/i.test(text);
+        case "slack": return text.length + ROOM <= PLATFORM_LIMITS.slack;
         case "discord": return discordPlain(text).length + ROOM <= PLATFORM_LIMITS.discord;
         case "teams": return false;
     }

package/dist/chat-task-actions.js

@@ -67,7 +67,7 @@ export function applyChatTaskAction(store, who, payload, now, web, controls = {}
             if (!allowed.ok && controls.via === "web")
                 return { ok: false, message: allowed.why };
             const resumed = resumeTaskStop(store, { taskId: task, runId: run, by: verifiedAuthor(who.name), via: controls.via ?? "web" }, now);
-            return resumed.ok ? { ok: true, taskId: task, said: `Stop released. ${resumed.gate ? "Other requirements still prevent the next attempt." : "The next attempt may start."}` } : { ok: false, message: resumed.detail };
+            return resumed.ok ? { ok: true, taskId: task, said: `Stop lifted. ${resumed.gate ? "Something else still holds the next attempt." : "The next attempt may start."}` } : { ok: false, message: resumed.detail };
         }
         const { via, evidenceRoot: _root, ...rest } = controls;
         const result = requestTaskStop(store, { taskId: task, runId: run, by: verifiedAuthor(who.name), via: via ?? (web ? "web" : "cli"), ...rest }, now);

package/dist/chat-terms.d.ts

@@ -19,3 +19,11 @@ export declare function chatLimitProblem(scope: Pick<Scope, "profile" | "budgetM
     fullAccess: boolean;
     capMicrousd: number | null;
 }, yours: string): string | null;
+/** The chat apps a card goes to. */
+export type CardChannel = "telegram" | "slack" | "discord" | "teams";
+/** Whether a chat app shows a card's words exactly as they are stored, so a tap there is a yes to those words. Teams
+ * draws card text as Markdown, where a link's label hides its address, and Slack turns `:name:` into an emoji: there
+ * the words go to the review page and no tap approves them. Telegram's card is plain text and Discord's escapes its
+ * presentation syntax. Both approval roads read this one rule (chat-decide.ts shownWhole, chat-actions.ts
+ * sharedActionAllowsChallenge), so neither can seal words the other would refuse. */
+export declare function shownAsWritten(text: string, channel: CardChannel): boolean;

package/dist/chat-terms.js

@@ -79,3 +79,17 @@ export function chatLimitProblem(scope, limits, yours) {
         return `This plan has ${scope.budgetMicrousd === null ? "no attempt limit" : `a ${money(scope.budgetMicrousd)} attempt limit`}, more than ${yours === "your mode" ? "your mode's" : "your chat approval limit of"} ${money(cap)}.`;
     return null;
 }
+/** Whether a chat app shows a card's words exactly as they are stored, so a tap there is a yes to those words. Teams
+ * draws card text as Markdown, where a link's label hides its address, and Slack turns `:name:` into an emoji: there
+ * the words go to the review page and no tap approves them. Telegram's card is plain text and Discord's escapes its
+ * presentation syntax. Both approval roads read this one rule (chat-decide.ts shownWhole, chat-actions.ts
+ * sharedActionAllowsChallenge), so neither can seal words the other would refuse. */
+export function shownAsWritten(text, channel) {
+    switch (channel) {
+        case "telegram":
+        case "discord": return true;
+        // Emoji names: letters and digits of any script (workspaces add their own), `_`, `+`, `'`, `-`.
+        case "slack": return !/:[\p{L}\p{N}_+'-]+:/u.test(text);
+        case "teams": return false;
+    }
+}

package/dist/chat-voice.js

@@ -4,7 +4,7 @@
  * task id, a "— revision" suffix or a person's own act never reaches a chat.
  * The console keeps every exact name and fact. */
 import { leadOnIt } from "./task-status.js";
-import { phoneText } from "./telegram-status.js";
+import { publicChatText as phoneText } from "./chat-display.js";
 /** The bot's display name in every chat app. */
 export const BOT_NAME = "Toolroll";
 /** Updates for one person landing within this window become one message, edited in place as it grows. */

package/dist/contracts/chat-actions.d.ts

@@ -353,6 +353,11 @@ export declare const chatActionRequestSchemas: {
         task: z.ZodString;
         run: z.ZodInt;
     }, z.core.$strict>;
+    /** One-step start from chat: the project and the preview the lead's turn loop prepared (never the model's id). */
+    readonly task_start: z.ZodObject<{
+        repo: z.ZodString;
+        preview: z.ZodString;
+    }, z.core.$strict>;
 };
 export type ChatActionOperation = keyof typeof chatActionRequestSchemas;
 export declare const CHAT_ACTION_OPERATIONS: [ChatActionOperation, ...ChatActionOperation[]];
@@ -435,6 +440,7 @@ export declare const sharedActionSchema: z.ZodObject<{
         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/contracts/chat-actions.js

@@ -111,6 +111,8 @@ export const chatActionRequestSchemas = {
     result_accept: z.strictObject({ task: words, run: id }),
     task_cancel: z.strictObject({ task: words }),
     task_resume: z.strictObject({ task: words, run: id }),
+    /** One-step start from chat: the project and the preview the lead's turn loop prepared (never the model's id). */
+    task_start: z.strictObject({ repo: words, preview: words }),
 };
 export const CHAT_ACTION_OPERATIONS = Object.keys(chatActionRequestSchemas);
 /** The fields each action takes, from its schema. */

package/dist/contracts/cli.d.ts

@@ -209,6 +209,12 @@ export declare const COMMAND_OUTPUTS: {
             task: z.ZodNullable<z.ZodString>;
             line: z.ZodString;
         }, z.core.$loose>>;
+        figures: z.ZodOptional<z.ZodObject<{
+            waitingOnYou: z.ZodNumber;
+            running: z.ZodNumber;
+            queued: z.ZodNumber;
+            done: z.ZodNumber;
+        }, z.core.$loose>>;
         projects: z.ZodArray<z.ZodObject<{
             repo: z.ZodString;
             name: z.ZodString;

package/dist/contracts/cli.js

@@ -85,6 +85,9 @@ const statusOutput = answers("status", {
     signIn: rows({ provider: str, reason: str, command: str, since: str }),
     tasks: rows({ task: str, title: str, headline: str, sentence: str }),
     lead: nullable(z.looseObject({ owner: str, doing: str, at: str, task: nullable(str), line: str })),
+    // Home's figures (home-groups.ts), the opening line's counts: each is the count of the Tasks list it names. An
+    // older Toolroll's answer has none.
+    figures: z.looseObject({ waitingOnYou: int, running: int, queued: int, done: int }).optional(),
     projects: rows({ repo: str, name: str, running: int, limit: int }),
     update: z.looseObject({ current: str, latest: str, security: z.boolean(), updateCommand: str, url: str }).optional(),
     integrations: z.looseObject({ broken: rows({ key: str, name: str, fix: nullable(str) }) }).optional(),