toolroll 0.9.96 → 0.9.98

package/dist/lead-latency-schema.d.ts

@@ -0,0 +1,24 @@
+/**
+ * v158: the lead's latency records and its quick-answer switch (docs/plans/responsive-chat.md, slice 5). Adds only:
+ * a saved row reads as it did. Kept beside nothing else so the update road can read the lists without the store.
+ *
+ * - `chat_turn.tools`: the tool names one lead step asked for, as a JSON array of names (never arguments); saved rows
+ *   read NULL (not recorded). So the next latency decision (a prefetched brief, §7.2) is made from data.
+ * - `chat_turn.failure_detail` and `mate_turn.failure_detail`: why a step or reply failed, more exactly than
+ *   failure_reason (LEAD_FAILURE_DETAILS); saved rows read NULL (unknown), and read the plain reason's words as before.
+ * - `mate_turn.route`: which model answered (§8): `default`, `fast` (the quick model answered) or `escalated` (a quick
+ *   step asked for more than reading, so the main model took the reply over); saved rows read NULL (before routing).
+ * - `lead_quick_setting`: Settings → Lead's "Quick answers use a faster model", one row; absent reads off.
+ */
+export declare const LEAD_FAILURE_DETAILS: readonly ["not-installed", "sign-in", "refused", "lost", "timeout-silent", "timeout-output"];
+export type LeadFailureDetail = typeof LEAD_FAILURE_DETAILS[number];
+export declare const LEAD_ROUTES: readonly ["default", "fast", "escalated"];
+export type LeadRoute = typeof LEAD_ROUTES[number];
+export declare const V158_SCHEMA = "\nCREATE TABLE IF NOT EXISTS lead_quick_setting (\n  id         INTEGER PRIMARY KEY CHECK (id = 1),\n  enabled    INTEGER NOT NULL CHECK (enabled IN (0, 1)),\n  updated_by TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n";
+export declare const V158_ADDED_COLUMNS: Readonly<Record<string, Readonly<Record<string, {
+    definition: string;
+    saved: string;
+}>>>>;
+export declare const V158_TABLES: readonly ["lead_quick_setting"];
+/** The v158 migration's steps, in order (a test seam may stop after each). */
+export declare const V158_STEPS: readonly ["lead-quick-setting", "lead-latency-columns"];

package/dist/lead-latency-schema.js

@@ -0,0 +1,36 @@
+/**
+ * v158: the lead's latency records and its quick-answer switch (docs/plans/responsive-chat.md, slice 5). Adds only:
+ * a saved row reads as it did. Kept beside nothing else so the update road can read the lists without the store.
+ *
+ * - `chat_turn.tools`: the tool names one lead step asked for, as a JSON array of names (never arguments); saved rows
+ *   read NULL (not recorded). So the next latency decision (a prefetched brief, §7.2) is made from data.
+ * - `chat_turn.failure_detail` and `mate_turn.failure_detail`: why a step or reply failed, more exactly than
+ *   failure_reason (LEAD_FAILURE_DETAILS); saved rows read NULL (unknown), and read the plain reason's words as before.
+ * - `mate_turn.route`: which model answered (§8): `default`, `fast` (the quick model answered) or `escalated` (a quick
+ *   step asked for more than reading, so the main model took the reply over); saved rows read NULL (before routing).
+ * - `lead_quick_setting`: Settings → Lead's "Quick answers use a faster model", one row; absent reads off.
+ */
+export const LEAD_FAILURE_DETAILS = ["not-installed", "sign-in", "refused", "lost", "timeout-silent", "timeout-output"];
+export const LEAD_ROUTES = ["default", "fast", "escalated"];
+const detailCheck = (column) => `TEXT CHECK (${column} IS NULL OR ${column} IN (${LEAD_FAILURE_DETAILS.map(one => `'${one}'`).join(",")}))`;
+export const V158_SCHEMA = `
+CREATE TABLE IF NOT EXISTS lead_quick_setting (
+  id         INTEGER PRIMARY KEY CHECK (id = 1),
+  enabled    INTEGER NOT NULL CHECK (enabled IN (0, 1)),
+  updated_by TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+`;
+export const V158_ADDED_COLUMNS = Object.freeze({
+    chat_turn: {
+        tools: { definition: "TEXT", saved: "NULL" },
+        failure_detail: { definition: detailCheck("failure_detail"), saved: "NULL" },
+    },
+    mate_turn: {
+        route: { definition: `TEXT CHECK (route IS NULL OR route IN (${LEAD_ROUTES.map(one => `'${one}'`).join(",")}))`, saved: "NULL" },
+        failure_detail: { definition: detailCheck("failure_detail"), saved: "NULL" },
+    },
+});
+export const V158_TABLES = Object.freeze(["lead_quick_setting"]);
+/** The v158 migration's steps, in order (a test seam may stop after each). */
+export const V158_STEPS = Object.freeze(["lead-quick-setting", "lead-latency-columns"]);

package/dist/lead-progress.d.ts

@@ -4,10 +4,13 @@
 export type LeadProgress = {
     kind: "started";
     turn: number;
-} | {
+}
+/** `reason`: the step re-asks the model about its own reply (a repair of a claim it can't back, or a shorten). */
+ | {
     kind: "step";
     turn: number;
     step: number;
+    reason?: "repair" | "shorten";
 } | {
     kind: "tool";
     turn: number;
@@ -28,6 +31,12 @@ export type LeadProgress = {
     step: number;
     text: string;
     final?: true;
+}
+/** Text was held back because it looked like a password or key (mid-stream, or the finished reply refused): every
+ * live preview of this turn closes and clears at once (docs/plans/responsive-chat.md §2.1). */
+ | {
+    kind: "blocked";
+    turn: number;
 };
 export type LeadToolOutcome = {
     state: "succeeded";

package/dist/lead-progress.js

@@ -48,7 +48,7 @@ const TOOL_LABELS = {
 export function leadToolLabel(name) {
     if (name in TOOL_LABELS)
         return TOOL_LABELS[name];
-    return name.startsWith("propose_") ? "Preparing a card for you to confirm" : "Working";
+    return name.startsWith("propose_") ? "Preparing a card for you to confirm" : "Working on it";
 }
 /** Tool errors instruct the model how to retry. Only known, fixed copy belongs
  * in the live UI; never echo arguments, redaction placeholders or exceptions. */

package/dist/lead-queue-runtime.d.ts

@@ -28,7 +28,7 @@ export type PersonalQueueRuntimeOptions = {
     };
     /** The console's live reply display: started per turn, ended with the progress handle it returned. */
     live?: {
-        begin: (thread: number) => (event: LeadProgress) => void;
+        begin: (thread: number, asked: string) => (event: LeadProgress) => void;
         end: (thread: number, ok: boolean, progress: (event: LeadProgress) => void) => void;
     };
     subscriptionRunner?: LeadTurnInput["subscriptionRunner"];

package/dist/lead-queue-runtime.js

@@ -105,7 +105,7 @@ export function createPersonalQueueRuntime(options) {
                 onAdmitted: turn => {
                     if (!queue.bindTurn(claim, turn))
                         throw new Error("The queued message changed before admission.");
-                    progress = options.live?.begin(claim.thread);
+                    progress = options.live?.begin(claim.thread, claim.text);
                 },
                 ...(context === undefined ? {} : { context }), channel: "console", clock, evidenceRoot: options.evidenceRoot,
                 ...(options.live === undefined ? {} : { onProgress: (event) => progress?.(event) }),

package/dist/lead-route.d.ts

@@ -0,0 +1,56 @@
+import type { LeadRoute } from "./lead-latency-schema.js";
+import type { Store } from "./store.js";
+/** Words that ask for something to be done (§8's fixed list, plus a few plain synonyms). Any of them keeps a message on
+ * the main model. Matched as whole words in their plain form, the form a request takes ("fix it", "can you merge",
+ * "file a task"): "what's running?" or "is it merged?" ask about a state and stay quick. A quick step that asks to act
+ * anyway is escalated (quickStepEscalates), so this list is the first line, not the only one. */
+export declare const QUICK_ACT_WORDS: readonly string[];
+/** The longest message the quick model takes: longer ones are rarely a plain status question. */
+export declare const QUICK_MESSAGE_MAX_CHARS = 240;
+/** Whether a message reads as a status or read question with no act word (§8's message rule). */
+export declare function quickQuestion(message: string): boolean;
+/**
+ * The tools a quick reply's requests advertise: reads only. Every one is a read of saved state as this person sees it;
+ * none drafts, records a question, a promise, a memory or a card, or opens a page. `find_tools` is advertised beside them
+ * but is not one of them: it is how a quick step says it needs something else ("search before saying something can't
+ * be done"), so calling it hands the reply to the main model, unrun (more conservative than §8's "find_tools for
+ * something to change": any search escalates).
+ */
+export declare const QUICK_READ_TOOLS: ReadonlySet<string>;
+/** Whether a quick step's request advertises this tool: the reads, and find_tools as the way to ask for more. */
+export declare function quickAdvertises(name: string): boolean;
+/** The faster model, as the model catalog names it: the newest Sonnet this computer's Claude has been seen to run, else
+ * the compiled current one. Always an exact id, never an alias that could move under a recorded route. */
+export declare function quickLeadModel(store: Store): string;
+export type QuickRouteInput = {
+    /** Settings → Lead's switch. */
+    enabled: boolean;
+    provider: string;
+    /** The configured model, which a quick reply would otherwise run on. */
+    mainModel: string;
+    message: string;
+    /** Server-authored context for this turn (a task page, a crew update): present keeps the main model. */
+    hasContext: boolean;
+    /** The message replies to an image (a result's screenshot). */
+    hasReplyImage: boolean;
+    /** The thread's newest reply asked the owner a question. */
+    askOpen: boolean;
+    /** The faster model, and whether the organisation policy allows it. */
+    quickModel: string;
+    quickAllowed: boolean;
+};
+/** Which model answers: the faster one only when every condition holds. */
+export declare function quickRoute(input: QuickRouteInput): {
+    route: Extract<LeadRoute, "fast">;
+    model: string;
+} | {
+    route: Extract<LeadRoute, "default">;
+};
+/** Whether a quick step asked for anything beyond the quick reads: its calls are then discarded unrun (§8). */
+export declare function quickStepEscalates(calls: readonly {
+    name: string;
+}[]): boolean;
+/** "Sonnet 5.5" for claude-sonnet-5-5; the id itself for anything else. */
+export declare function modelName(model: string): string;
+/** The activity line's words for a routed reply: "answered by Sonnet 5.5", "moved to Opus"; nothing for the default. */
+export declare function routeWords(route: LeadRoute, quickModel: string, mainModel: string): string | null;

package/dist/lead-route.js

@@ -0,0 +1,104 @@
+/**
+ * The quick-answer router (docs/plans/responsive-chat.md §8, owner decision 7): which model answers a reply, decided
+ * before the turn, deterministically and conservatively. A reply goes to the faster model only when quick answers are
+ * on, the lead runs on the Claude membership, the organisation policy allows that model, the message carries no task
+ * or reply context, it doesn't answer the lead's own open question, and it reads as a status or read question with no
+ * act word. Everything else stays on the main model, unchanged.
+ *
+ * A quick reply is read-only by construction: its requests advertise only QUICK_READ_TOOLS (and find_tools, the way to
+ * ask for more). A quick step that asks for anything else has its calls discarded unrun, and the main model takes the reply over from that step (lead.ts).
+ */
+import { aliasTarget } from "./model-catalog.js";
+import { exactModelId } from "./phase-routing.js";
+import { SONNET } from "./model-choices.js";
+/** Words that ask for something to be done (§8's fixed list, plus a few plain synonyms). Any of them keeps a message on
+ * the main model. Matched as whole words in their plain form, the form a request takes ("fix it", "can you merge",
+ * "file a task"): "what's running?" or "is it merged?" ask about a state and stay quick. A quick step that asks to act
+ * anyway is escalated (quickStepEscalates), so this list is the first line, not the only one. */
+export const QUICK_ACT_WORDS = Object.freeze([
+    "file", "make", "create", "add", "fix", "change", "build", "plan", "approve", "confirm", "merge", "release", "ship",
+    "deploy", "cancel", "pause", "hold", "resume", "retry", "steer", "remember", "delete", "archive", "send", "run",
+    "start", "stop",
+    // Plain synonyms of the same acts.
+    "rerun", "redo", "undo", "revert", "push", "publish", "kill", "edit", "remove", "rename", "reset", "restart",
+    "install", "upgrade", "enable", "disable", "accept", "reject", "schedule", "assign", "write", "draft", "set", "move",
+    "close", "reopen", "unhold", "dismiss", "prioritize", "prioritise", "split", "revise",
+]);
+/** Openings that ask about the state of things. */
+const ASKING_OPENINGS = new Set([
+    "what", "what's", "whats", "which", "who", "who's", "whose", "why", "when", "where", "how", "how's", "is", "are", "was",
+    "were", "did", "does", "do", "has", "have", "had", "any", "anything", "show", "list", "status", "tell", "give",
+]);
+/** The longest message the quick model takes: longer ones are rarely a plain status question. */
+export const QUICK_MESSAGE_MAX_CHARS = 240;
+const words = (text) => text.toLowerCase().replace(/[’]/g, "'").split(/[^a-z0-9']+/).filter(one => one !== "");
+/** Whether a message reads as a status or read question with no act word (§8's message rule). */
+export function quickQuestion(message) {
+    const text = message.trim();
+    if (text === "" || text.length > QUICK_MESSAGE_MAX_CHARS || /[\r\n]/.test(text))
+        return false;
+    const all = words(text);
+    if (all.length === 0)
+        return false;
+    if (all.some(word => QUICK_ACT_WORDS.includes(word.replace(/'s$/, ""))))
+        return false;
+    // A negated or conditional request ("don't…", "if…, then…") is a judgement call: the main model takes it.
+    if (all.some(word => word === "don't" || word === "dont" || word === "if" || word === "please"))
+        return false;
+    return text.endsWith("?") || ASKING_OPENINGS.has(all[0]);
+}
+/**
+ * The tools a quick reply's requests advertise: reads only. Every one is a read of saved state as this person sees it;
+ * none drafts, records a question, a promise, a memory or a card, or opens a page. `find_tools` is advertised beside them
+ * but is not one of them: it is how a quick step says it needs something else ("search before saying something can't
+ * be done"), so calling it hands the reply to the main model, unrun (more conservative than §8's "find_tools for
+ * something to change": any search escalates).
+ */
+export const QUICK_READ_TOOLS = new Set([
+    "get_brief", "get_project_context", "get_code_map", "get_project_activity", "get_actions", "get_action_status", "get_skills",
+    "get_acceptance_evidence", "recap", "list_repos", "list_tasks", "get_task", "get_result", "get_result_images", "get_controls",
+    "get_agents", "get_project_knowledge", "get_flaky_tests", "get_task_conversation", "get_diff", "get_check_log",
+    "get_project_tools", "get_flows", "get_flow_insights", "list_decisions", "get_decision", "queue",
+    "get_findings", "get_subagents", "get_person", "get_integrations", "get_capabilities", "search_project_memory", "get_models", "get_sweep",
+]);
+/** Whether a quick step's request advertises this tool: the reads, and find_tools as the way to ask for more. */
+export function quickAdvertises(name) {
+    return QUICK_READ_TOOLS.has(name) || name === "find_tools";
+}
+/** The faster model, as the model catalog names it: the newest Sonnet this computer's Claude has been seen to run, else
+ * the compiled current one. Always an exact id, never an alias that could move under a recorded route. */
+export function quickLeadModel(store) {
+    const seen = aliasTarget(store, "sonnet")?.id ?? null;
+    return seen !== null && exactModelId(seen) ? seen : SONNET;
+}
+/** Which model answers: the faster one only when every condition holds. */
+export function quickRoute(input) {
+    if (!input.enabled || input.provider !== "claude-subscription" || !input.quickAllowed)
+        return { route: "default" };
+    if (input.quickModel === input.mainModel || input.hasContext || input.hasReplyImage || input.askOpen)
+        return { route: "default" };
+    return quickQuestion(input.message) ? { route: "fast", model: input.quickModel } : { route: "default" };
+}
+/** Whether a quick step asked for anything beyond the quick reads: its calls are then discarded unrun (§8). */
+export function quickStepEscalates(calls) {
+    return calls.some(call => !QUICK_READ_TOOLS.has(call.name));
+}
+/** "Sonnet 5.5" for claude-sonnet-5-5; the id itself for anything else. */
+export function modelName(model) {
+    if (model === "default")
+        return "the main model";
+    const family = /^claude-(opus|sonnet|haiku|fable)-(\d+)(?:-(\d+))?/.exec(model);
+    if (family !== null)
+        return `${family[1].charAt(0).toUpperCase()}${family[1].slice(1)} ${family[2]}${family[3] === undefined ? "" : `.${family[3]}`}`;
+    if (/^(opus|sonnet|haiku|fable)$/.test(model))
+        return `${model.charAt(0).toUpperCase()}${model.slice(1)}`;
+    return model;
+}
+/** The activity line's words for a routed reply: "answered by Sonnet 5.5", "moved to Opus"; nothing for the default. */
+export function routeWords(route, quickModel, mainModel) {
+    if (route === "fast")
+        return `answered by ${modelName(quickModel)}`;
+    if (route === "escalated")
+        return `moved to ${modelName(mainModel)}`;
+    return null;
+}

package/dist/lead-status.d.ts

@@ -1,5 +1,6 @@
 import { type LimitWindow } from "./provider-limits.js";
 import { type RunCheckSuite, type Store } from "./store.js";
+import { type HomeFigures } from "./home-groups.js";
 export type CheckSummary = {
     status: "passed" | "failed" | "not-run" | "unknown";
     exitCode: number | null;
@@ -84,6 +85,8 @@ export type InstallationStatus = {
         task: string | null;
         line: string;
     } | null;
+    /** Home's figures from the same work index totals (home-groups.ts): each the count of the Tasks list it names. */
+    figures: HomeFigures;
 };
 /** One indexed observation for `task wait`. `watchedRun` is the attempt the
  * caller first saw. Each poll follows the task's newest attempt from there, so

package/dist/lead-status.js

@@ -5,6 +5,7 @@ import { windowLabel } from "./provider-limits.js";
 import { openAuthPauses, signInCommand, signInReason } from "./provider-auth.js";
 import { BUILT_IN, checkSuitesOf } from "./store.js";
 import { workIndexPage, workReadyForReview } from "./work-index.js";
+import { homeFiguresLine, homeFiguresOf } from "./home-groups.js";
 import { currentActor } from "./actor.js";
 import { leadActivity, leadActivityLine } from "./lead-voice.js";
 const maybeNumber = (value) => value === null || value === undefined || !Number.isInteger(Number(value)) ? null : Number(value);
@@ -234,6 +235,8 @@ export function installationStatus(store, now, viewer = currentActor()?.account
     // One per family, from the same projection as the Tasks list: a completed
     // family (root or any revision) and a superseded version never count.
     const ready = workReadyForReview(store, now, access, 5);
+    // The most urgent tasks and Home's figures, from one read of the work index.
+    const index = workIndexPage(store, now, { ...access, viewer }, { limit: 8, ...(root === undefined ? {} : { root }) });
     const checkRow = (run) => store.handle.prepare(`SELECT ${CHECK_COLUMNS} FROM run_check AS rc WHERE rc.run = ?`).get(run);
     // Run ids grow with time, so the newest finished release check is the
     // first finished row down the partial index.
@@ -265,8 +268,8 @@ export function installationStatus(store, now, viewer = currentActor()?.account
             observedAt: String(row["observed_at"]),
         })),
         signIn: pauses.map(one => ({ provider: one.provider, reason: signInReason(one), command: signInCommand(one), since: one.openedAt })),
-        tasks: workIndexPage(store, now, { ...access, viewer }, { limit: 8, ...(root === undefined ? {} : { root }) }).items
-            .map(one => ({ task: one.rootId, title: one.title, headline: one.status.label, sentence: one.status.detail })),
+        tasks: index.items.map(one => ({ task: one.rootId, title: one.title, headline: one.status.label, sentence: one.status.detail })),
+        figures: homeFiguresOf(index.totals),
         lead: repos !== null ? null : (() => {
             // Only the asker's own lead: another person's lead is never "Your lead".
             const activity = leadActivity(store, viewer);
@@ -280,6 +283,8 @@ export function renderInstallationStatus(status, limited = false) {
     // A paused provider comes first: it is the one thing a person must do.
     for (const one of status.signIn)
         lines.push(`${one.reason} — run \`${one.command}\`. Its tasks wait until then.`);
+    // Then Home's figures, the same words and counts as Home.
+    lines.push(homeFiguresLine(status.figures));
     if (status.lead != null)
         lines.push(status.lead.line);
     // Each task's one headline, the same words as the console and chat cards.
@@ -320,7 +325,7 @@ export function renderInstallationStatus(status, limited = false) {
             lines.push(`Plan windows: ${provider} — ${detail}`);
         }
     }
-    return lines.slice(0, 12 + status.signIn.length + (status.lead == null ? 0 : 1) + (status.tasks.length === 0 ? 0 : status.tasks.length + 1));
+    return lines.slice(0, 13 + status.signIn.length + (status.lead == null ? 0 : 1) + (status.tasks.length === 0 ? 0 : status.tasks.length + 1));
 }
 export function renderTaskWait(snapshot, outcome = snapshot.outcome) {
     const check = snapshot.check.status === "unknown" ? "checks unknown" : snapshot.check.status === "not-run" ? "checks not run" : `checks ${snapshot.check.status}${snapshot.check.exitCode === null ? "" : ` (exit ${snapshot.check.exitCode})`}`;

package/dist/lead-tools.d.ts

@@ -1,4 +1,5 @@
 import { type FeedbackImage } from "./result-review.js";
+import { type FastPreview } from "./fast-start.js";
 import { type CommitmentChannel } from "./lead-commitments.js";
 import { type Integration } from "./integrations.js";
 import type { AuthMode } from "./keys.js";
@@ -56,6 +57,10 @@ export type LeadToolContext = {
         searches: number;
         found: Set<string>;
     };
+    /** propose_start only (docs/plans/one-step-chat.md C3): the preview the conversation loop prepared for THIS call, in
+     * this turn, after the call's input was validated (startInputOf). Never read from the model's arguments; absent (a
+     * direct call outside a turn), nothing was prepared and the person gets an ordinary task card. */
+    startPrepared?: FastPreview;
 };
 export type LeadToolResult = {
     ok: true;
@@ -145,3 +150,18 @@ export declare function isLeadTool(name: string): boolean;
 export declare function executeLeadTool(ctx: LeadToolContext, name: string, args: Record<string, unknown>, view?: LeadViewContext): LeadToolResult;
 /** Bytes of a serialized tool result as it will sit inside the request body. */
 export declare function toolResultBytes(text: string): number;
+/** What propose_start may start with, checked before Toolroll asks the classifier (docs/plans/one-step-chat.md C3): the
+ * call's contract, the same memory and capability checks every proposal makes, never a team chat, a project the person
+ * can reach now, and the same text and secret checks as propose_task. The conversation loop runs this, and only then
+ * prepares a preview; the handler runs it again. Invalid input never reaches the classifier. */
+export declare function startInputOf(ctx: LeadToolContext, args: Record<string, unknown>): {
+    ok: true;
+    input: {
+        repo: string;
+        repoId: string;
+        title: string;
+    };
+} | {
+    ok: false;
+    message: string;
+};

package/dist/lead-tools.js

@@ -17,6 +17,7 @@ import { taskControlOf } from "./task-control.js";
 import { taskWorkSummaryOf } from "./work-summary.js";
 import { assignmentOf, assignmentBrief } from "./assignment.js";
 import { validateScopeText, validateTaskText } from "./task-text.js";
+import { fastRefusalWords } from "./fast-start.js";
 import { conversationKnowledge, knowledgeView } from "./project-knowledge.js";
 import { fixTaskOf, flakyList, flakyShow } from "./flaky.js";
 import { cancelCommitment, CHECK_RESULTS, conditionWords, latestResultRun, recordCommitment, RUN_OUTCOMES, TASK_STATES } from "./lead-commitments.js";
@@ -393,7 +394,7 @@ export function agentsOver(store, taskId, now) {
 export const LEAD_CORE_TOOLS = new Set([
     "find_tools", "get_brief", "recap", "list_repos", "get_project_context", "get_project_activity", "search_project_memory", "get_capabilities",
     "list_tasks", "get_task", "get_result", "get_diff", "get_check_log", "list_decisions", "get_decision",
-    "get_actions", "get_action_status", "propose_action", "propose_task", "propose_scope", "propose_steer",
+    "get_actions", "get_action_status", "propose_action", "propose_task", "propose_start", "propose_scope", "propose_steer",
     "propose_answer", "propose_review", "remember", "ask_owner", "commit_to",
     // The lead's queue verbs: basic, and small enough that deferring them saves almost nothing.
     "queue", "propose_next", "propose_reserve", "propose_hold", "propose_unhold", "propose_cancel",
@@ -596,7 +597,7 @@ const LEAD_TOOL_HANDLERS = {
     },
     get_actions: {
         description: "List shared actions and required inputs. All channels use the same approvals.",
-        handle: () => ({ ok: true, body: { actions: Object.entries(CHAT_ACTIONS).filter(([operation]) => !operation.startsWith('flow_') && !operation.startsWith('subagent_')).map(([operation, value]) => ({ operation, label: value.label, secureReview: value.protected, inputs: CHAT_ACTION_FIELDS[operation].filter(field => field !== 'nonce' && field !== 'files') })), notice: 'Passwords and credentials never belong in a tool call or conversation. Secure review links complete protected actions.' } }),
+        handle: () => ({ ok: true, body: { actions: Object.entries(CHAT_ACTIONS).filter(([operation]) => !operation.startsWith('flow_') && !operation.startsWith('subagent_') && operation !== 'task_start').map(([operation, value]) => ({ operation, label: value.label, secureReview: value.protected, inputs: CHAT_ACTION_FIELDS[operation].filter(field => field !== 'nonce' && field !== 'files') })), notice: 'Passwords and credentials never belong in a tool call or conversation. Secure review links complete protected actions.' } }),
     },
     propose_action: {
         description: "Read get_actions and relevant skills/evidence first. Save an exact-state proposal only; protected or long terms require full secure review.",
@@ -608,6 +609,9 @@ const LEAD_TOOL_HANDLERS = {
                 return { ok: false, message: 'Use propose_flow for flows.' };
             if (operation.startsWith('subagent_'))
                 return { ok: false, message: 'Use propose_subagent for subagents.' };
+            // A Start card is drafted only by propose_start, whose preview comes from the turn loop, never from arguments.
+            if (operation === 'task_start')
+                return { ok: false, message: 'Use propose_start for a small change to start now.' };
             const input = { ...args };
             delete input['operation'];
             if (operation.startsWith('skill_') || operation.startsWith('knowledge_') || operation.startsWith('tool_') || operation === 'mode_revoke' || operation === 'memory_decide') {
@@ -1709,7 +1713,7 @@ const LEAD_TOOL_HANDLERS = {
         },
     },
     search_project_memory: {
-        description: "Search decisions, instructions, references, lessons and the conversations you may read, across your projects. Read-only; cite the kind and id of what you rely on.",
+        description: "Search decisions, instructions, references, lessons and the conversations you may read, across your projects. Read-only; name what you rely on by what it settled ('you chose Postgres in March'); give its kind and id when asked.",
         handle: (ctx, args) => {
             const repo = args['repo'] === undefined ? null : repoPathOf(ctx.who, args['repo']);
             if (args['repo'] !== undefined && repo === null)
@@ -1925,6 +1929,35 @@ const LEAD_TOOL_HANDLERS = {
             return { ok: true, body: { proposal: id, kind: "task", repo: args["repo"], deliverable: report ? "report" : "branch", planning: report ? "not needed for a scout" : planning, awaiting: "the operator's confirmation" } };
         },
     },
+    propose_start: {
+        description: "The person asked for one small, clear change to be done now. Toolroll decides whether it can start right away; if not, you get an ordinary task card. title is the change in their words, one line.",
+        handle: (ctx, args) => {
+            const checked = startInputOf(ctx, args);
+            if (!checked.ok)
+                return { ok: false, message: checked.message };
+            const { repo, repoId, title } = checked.input;
+            // Eligible: a Start card from the loop's own preview (the request names it back; the card checks it is this
+            // person's, this turn's, on chat). Anything else: today's task card, built directly, and why in the body.
+            const prepared = ctx.startPrepared;
+            let why = fastRefusalWords(prepared === undefined ? "classifier" : prepared.eligible ? "classifier" : prepared.reason);
+            if (prepared !== undefined && prepared.eligible) {
+                try {
+                    const action = prepareSharedAction(ctx.store, ctx.who, "task_start", { repo, preview: prepared.preview }, ctx.evidenceRoot, ctx.now, ctx.turn);
+                    const id = ctx.draft("action", { ...action });
+                    if (id === null)
+                        return tooMany();
+                    return { ok: true, body: { proposal: id, kind: "action", label: action.title, startsNow: true, awaiting: "the person's own yes on Start work", executed: false } };
+                }
+                catch (error) {
+                    why = error instanceof Error ? error.message : why;
+                }
+            }
+            const id = ctx.draft("task", { repo, repoId, title, goal: title, not: null, touches: [], acceptance: [{ id: "c1", statement: title, evidence: ["manual-review"] }], planning: "skip", report: false });
+            if (id === null)
+                return tooMany();
+            return { ok: true, body: { proposal: id, kind: "task", repo: repoId, startsNow: false, why, awaiting: "the operator's confirmation" } };
+        },
+    },
     propose_sweep: {
         description: "Several independent items under ONE shared rule set (a bug sweep, a batch of small fixes): 2-20 items, each becomes its own task in its own worktree, started with one approval, at most max_parallel (default 3) at once, each reporting a verdict into one table. brief holds the shared rules every item gets (e.g. reproduce first; 'not reproducible' is a valid result; prove the fix); each item is only its own report. Not for one task, and not for steps that depend on each other.",
         handle: (ctx, args) => {
@@ -2515,3 +2548,33 @@ export function executeLeadTool(ctx, name, args, view) {
 export function toolResultBytes(text) {
     return Buffer.byteLength(JSON.stringify(text), "utf8");
 }
+/** What propose_start may start with, checked before Toolroll asks the classifier (docs/plans/one-step-chat.md C3): the
+ * call's contract, the same memory and capability checks every proposal makes, never a team chat, a project the person
+ * can reach now, and the same text and secret checks as propose_task. The conversation loop runs this, and only then
+ * prepares a preview; the handler runs it again. Invalid input never reaches the classifier. */
+export function startInputOf(ctx, args) {
+    const tool = LEAD_TOOLS.find(one => one.name === "propose_start");
+    if (tool === undefined)
+        return { ok: false, message: "propose_start isn't available." };
+    const read = tool.read(ctx, args);
+    if (!read.ok)
+        return { ok: false, message: read.issues.map(one => one.line).join("\n") };
+    const unchecked = memoryUnsearched(ctx, "propose_start", read.value) ?? capabilitiesUnread(ctx, "propose_start", read.value);
+    if (unchecked !== null && !unchecked.ok)
+        return { ok: false, message: unchecked.message };
+    // A start is the person's own yes in their own chat with you: a shared team chat proposes an ordinary task.
+    if (teamRoomOf(ctx.store, ctx.thread) !== null)
+        return { ok: false, message: "Starting work in one step is for the person's own chat. Use propose_task here." };
+    const repo = repoPathOf(ctx.who, read.value["repo"]);
+    if (repo === null || !ctx.store.accountCanAccess(ctx.who.name, repo))
+        return { ok: false, message: "repo must be one of the ids from list_repos" };
+    const title = read.value["title"];
+    if (typeof title !== "string")
+        return { ok: false, message: "title is the change, one line" };
+    const badText = validateTaskText({ title, goal: title, outOfScope: null });
+    if (badText !== null)
+        return { ok: false, message: badText.message };
+    if (scanForSecrets(title).length > 0)
+        return { ok: false, message: "Task text cannot contain credentials." };
+    return { ok: true, input: { repo, repoId: String(read.value["repo"]), title } };
+}

package/dist/lead-voice.js

@@ -11,7 +11,7 @@ import { BATCH_MS, chatText, chatTitle } from "./chat-voice.js";
 import { BUILT_IN, refArchived } from "./store.js";
 import { leadNameOf } from "./lead-identity.js";
 import { leadLapsed } from "./task-status.js";
-import { phoneText as plain } from "./telegram-status.js";
+import { publicChatText as plain } from "./chat-display.js";
 export const LEAD_SAY_KIND = "lead-say";
 /** Repaints the owner's task card when the lead takes a task on: it never makes a new message in quiet chat. */
 export const LEAD_ON_IT_KIND = "lead-on-it";

package/dist/lead.d.ts

@@ -1,5 +1,6 @@
 import { type LeadProgress } from "./lead-progress.js";
 import type { ChatConfig, LeadSession, LeadThread, Store } from "./store.js";
+import type { LeadFailureDetail } from "./lead-latency-schema.js";
 import type { Integration } from "./integrations.js";
 import type { VerifiedApprover } from "./principal.js";
 import { type LeadHistoryMessage } from "./converse.js";
@@ -128,8 +129,9 @@ export declare const LEAD_FAILURE_COPY: {
     readonly empty: "The lead sent back an empty answer. Nothing was kept. Send your message again.";
     readonly unusable: "The lead's answer couldn't be used, so it was thrown away. Nothing was kept. Send your message again.";
 };
-/** A failed turn's saved reason as plain words, for a surface that reads the turn back later (a restart, a delivery retry). */
-export declare function leadFailureText(reason: string | null, unknownSpend?: boolean): string;
+/** A failed turn's saved reason as plain words, for a surface that reads the turn back later (a restart, a delivery retry).
+ * Its saved detail (v158), when known, names the exact cause the person saw live ("not installed", "sign-in expired"). */
+export declare function leadFailureText(reason: string | null, unknownSpend?: boolean, detail?: LeadFailureDetail | null): string;
 /** How long a provider that ignored its abort at the turn's deadline is waited for before the turn ends without it.
  * Its process group was already killed at the deadline; this only bounds the wait for the transport to say so. */
 export declare const LEAD_ABORT_GRACE_MS = 5000;