toolroll 0.9.84 → 0.9.86

package/dist/surface.js

@@ -171,7 +171,7 @@ const GUIDE_ROWS = [
         notableReasons: ["no-result"] },
     { invocation: "task list", synopsis: "a page of saved task status", audience: "agent", agentMayInvoke: true, mutation: "none",
         flags: [jsonFlag, dbFlag, { name: "state", takesValue: true, meaning: "queued|running|done|failed|cancelled" },
-            { name: "view", takesValue: true, meaning: "all|needs-you|running|completed" },
+            { name: "view", takesValue: true, meaning: "all|needs-you|running|completed|archived" },
             { name: "limit", takesValue: true, meaning: "page size, 1–100; default 40" },
             { name: "cursor", takesValue: true, meaning: "nextCursor from the previous response" },
             { name: "repo", takesValue: true, meaning: "filter to one project" }] },
@@ -299,6 +299,18 @@ const GUIDE_ROWS = [
     operator("task route", "which configured agents plan, build and repair this task; phase and size changes require renewed approval"),
     operator("task reopen", "resume external work its tracker closed and has been SEEN open again"),
     operator("task stop", "stop ONE exact live attempt (--run <id>): durable before any process is signalled, answers 'stopping' until its own processes are established gone; work, branch, and evidence preserved; no strike, no retry"),
+    { ...operator("task archive", "put tasks away (a person's act): out of every list, count and nudge, history and approvals kept; nothing claims, approves or dispatches them until restored"),
+        positionals: [{ name: "id", required: true, meaning: "one or more tasks (any version: the whole family goes)" }],
+        flags: [jsonFlag, dbFlag, { name: "reason", takesValue: true, meaning: "why, shown on the task page" }], notableReasons: ["unknown-task", "not-an-approver"] },
+    { ...operator("task restore", "bring put-away tasks back exactly as they were (a person's act)"),
+        positionals: [{ name: "id", required: true, meaning: "one or more put-away tasks" }], flags: [jsonFlag, dbFlag], notableReasons: ["unknown-task", "not-an-approver"] },
+    { ...operator("task tidy", "Put away old tasks: --preview lists what would go and why (read-only), --apply --digest <d> puts away exactly that list (a person's act)"),
+        flags: [jsonFlag, dbFlag, { name: "preview", takesValue: false, meaning: "show the list and the digest; changes nothing" },
+            { name: "apply", takesValue: false, meaning: "put away exactly the previewed list (needs --digest)" },
+            { name: "digest", takesValue: true, meaning: "the digest --preview printed" },
+            { name: "days", takesValue: true, meaning: "also finished tasks untouched this many days (1–365, default 14)" },
+            { name: "except", takesValue: true, meaning: "comma-separated tasks from the list to leave out" }],
+        notableReasons: ["usage", "not-an-approver", "empty"] },
     operator("run settle", "last resort for a finished run whose process witness can't be proven either way: records your --why in the ledger; refuses while any of the run's processes is alive"),
     operator("task resume", "resume the exact stopped attempt (--run <id>): refuses until it is quiescent, lifts only that stop's hold, approves nothing — the next pass re-proves the scope and inherits the draft with fresh proof"),
     // ---- leases (runner surface) ----
@@ -443,11 +455,15 @@ const REMOTE_NO = [
     "enroll", "revoke",
     // Flow steps that fetch addresses or run checks and scripts here.
     "flows import", "flows trigger check", "flows script save",
+    // Lets a flow script on this machine start Chromium in its sandbox: a person here, with their own password.
+    "flows browser",
     // Reads this machine owner's own Claude and Codex session files (~/.claude, ~/.codex).
     "memory propose",
 ];
 const REMOTE_STEP_UP = [
-    "proposals", "decide", "task regate", "task approve", "task accept", "task merge", "run settle", "knowledge apply", "memory apply",
+    "proposals", "decide", "task regate", "task approve", "task accept", "task merge", "run settle",
+    // Putting tasks away and restoring them: a person's act, in the console or on the server's machine.
+    "task archive", "task restore", "task tidy", "knowledge apply", "memory apply",
     "flows card approve", "flows card send-back", "flows script approve", "flows unattended",
     "approver list", "approver add", "people list", "people invite", "people projects", "people revoke",
     // A person's own API tokens: a password step-up on the server's machine, or the console. Never with a token.

package/dist/task-archive.d.ts

@@ -0,0 +1,10 @@
+/** Put-away checks (v145, docs/plans/task-tidy.md), in a leaf module so every door can ask without loading the store. */
+import type { Store } from "./store.js";
+/** Whether this task version is put away. Every door that dispatches, claims or approves asks this (fail closed: a
+ * row means no). */
+export declare function refArchived(store: Store, taskRef: number): boolean;
+/** Whether the built-in task with this id is put away. */
+export declare function taskArchived(store: Store, taskId: string): boolean;
+/** Whether a flow card's work is put away: its current task or its first build task (a later stage keeps the first
+ * and may clear the current one). Read from the card's own row now, so a put away that committed first holds it. */
+export declare function cardTaskArchived(store: Store, cardId: number): boolean;

package/dist/task-archive.js

@@ -0,0 +1,16 @@
+/** Whether this task version is put away. Every door that dispatches, claims or approves asks this (fail closed: a
+ * row means no). */
+export function refArchived(store, taskRef) {
+    return store.handle.prepare("SELECT 1 FROM task_archive WHERE task_ref = ?").get(taskRef) !== undefined;
+}
+/** Whether the built-in task with this id is put away. */
+export function taskArchived(store, taskId) {
+    return store.handle.prepare(`SELECT 1 FROM task_archive a JOIN task_ref r ON r.id = a.task_ref
+    WHERE r.backend = 'built-in' AND r.external_id = ?`).get(taskId) !== undefined;
+}
+/** Whether a flow card's work is put away: its current task or its first build task (a later stage keeps the first
+ * and may clear the current one). Read from the card's own row now, so a put away that committed first holds it. */
+export function cardTaskArchived(store, cardId) {
+    return store.handle.prepare(`SELECT 1 FROM flow_card c JOIN task_ref r ON r.backend = 'built-in' AND r.external_id IN (c.task, c.primary_task)
+    JOIN task_archive a ON a.task_ref = r.id WHERE c.id = ?`).get(cardId) !== undefined;
+}

package/dist/task-control.d.ts

@@ -102,7 +102,7 @@ export type ResumeOutcome = {
     gate: DispatchDiagnosis | null;
 } | {
     ok: false;
-    reason: "no-task" | "no-stop" | "wrong-task" | "stopping" | "already-resumed" | "superseded" | "busy" | "review" | "occupied";
+    reason: "no-task" | "no-stop" | "wrong-task" | "stopping" | "already-resumed" | "superseded" | "busy" | "review" | "occupied" | "archived";
     detail: string;
 };
 /**

package/dist/task-source.d.ts

@@ -51,8 +51,20 @@ export type TaskOrigin = {
         url: string | null;
         host: string | null;
     } | null;
+    /** A youiyoux change or options request (youiyoux-intake.ts): its id, its kind, and where the person pointed. */
+    request?: {
+        id: string;
+        kind: "change" | "options";
+        route: string | null;
+        component: string | null;
+        at: string | null;
+    } | null;
 };
-/** A task's origin, or null when it came from neither a flow nor an outside event. */
+/** A task's origin, or null when it came from neither a flow, an outside event nor a youiyoux request. */
 export declare function originOf(store: Store, taskId: string, canSee: (repo: string) => boolean): TaskOrigin | null;
+/** A youiyoux request by its kind: "youiyoux change request r-…" or "youiyoux options request r-…". */
+export declare function requestName(request: NonNullable<TaskOrigin["request"]>): string;
+/** Where a youiyoux request pointed, in words: "Button on /flows (src/button.tsx:12)". */
+export declare function requestWords(request: NonNullable<TaskOrigin["request"]>): string;
 /** The one line an approval shows about an outside event that started its work: context, never a term agreed to. */
 export declare function originNote(origin: TaskOrigin | null | undefined): string | null;

package/dist/task-source.js

@@ -71,8 +71,11 @@ export function cardReference(source) {
     const snapshot = snapshotOf(source ?? null);
     return snapshot === null ? "" : referenceWords(snapshot);
 }
-/** A task's origin, or null when it came from neither a flow nor an outside event. */
+/** A task's origin, or null when it came from neither a flow, an outside event nor a youiyoux request. */
 export function originOf(store, taskId, canSee) {
+    const request = store.youiyouxOriginOf(taskId);
+    if (request !== null)
+        return { flow: null, source: null, request: { id: request.request, kind: request.kind, route: request.route, component: request.component, at: request.at } };
     const kept = store.taskSourceOf(taskId);
     const flowId = kept?.flow ?? Number(/^flow:(\d+)$/.exec(store.filedViaOf(taskId) ?? "")?.[1] ?? NaN);
     const snapshot = kept === null ? null : readSnapshot(kept.sourceJson);
@@ -84,8 +87,21 @@ export function originOf(store, taskId, canSee) {
         source: snapshot === null ? null : { label: snapshot.label, proved: provedWords(snapshot), url: snapshot.external.url, host: hostOf(snapshot.external.url) },
     };
 }
+/** A youiyoux request by its kind: "youiyoux change request r-…" or "youiyoux options request r-…". */
+export function requestName(request) {
+    return `youiyoux ${request.kind === "options" ? "options" : "change"} request ${request.id}`;
+}
+/** Where a youiyoux request pointed, in words: "Button on /flows (src/button.tsx:12)". */
+export function requestWords(request) {
+    const what = [request.component, request.route === null ? null : `on ${request.route}`].filter(one => one !== null).join(" ");
+    return `${what === "" ? "" : what}${request.at === null ? "" : `${what === "" ? "" : " "}(${request.at})`}`;
+}
 /** The one line an approval shows about an outside event that started its work: context, never a term agreed to. */
 export function originNote(origin) {
+    if (origin?.request != null) {
+        const where = requestWords(origin.request);
+        return `From ${requestName(origin.request)}${where === "" ? "" : `: ${where}`}. Whoever can write the project's folder wrote these words; read them all before you approve.`;
+    }
     if (origin?.source == null)
         return null;
     const where = origin.source.host === null ? "" : ` · ${origin.source.host}`;

package/dist/telegram-lead.js

@@ -1,5 +1,5 @@
 import { CHAT_ACTIONS, sharedActionAllowsChallenge, sharedActionPayload } from "./chat-actions.js";
-import { taskInCeiling, mirrorToTaskChat, couldNotAnswerText, channelRepos as telegramConversationRepos, resolveChannelLead as resolveTelegramLead, NO_PHONE_LINK, NO_TASK_LINK, proposalLink, confirmedLink, proposalPreview, proposalOutcomeText, handoffCardText, confirmedCardText } from "./chat-channel.js";
+import { taskInCeiling, mirrorToTaskChat, couldNotAnswerText, channelRepos as telegramConversationRepos, resolveChannelLead as resolveTelegramLead, NO_PHONE_LINK, NO_TASK_LINK, phoneProposalLink, confirmedLink, phoneProposalPreview, proposalOutcomeText, handoffCardText, confirmedCardText } from "./chat-channel.js";
 export { channelRepos as telegramConversationRepos, resolveChannelLead as resolveTelegramLead, tooLongText, whichTaskText, replyContextFor, NO_PHONE_LINK, NO_TASK_LINK, proposalLink, confirmedLink, proposalPreview, proposalOutcomeText, handoffCardText, confirmedCardText, CHAT_ACTION_PARITY as TELEGRAM_ACTION_PARITY, parityGaps } from "./chat-channel.js";
 /**
  * The paired phone as one more way to use the same assistant.
@@ -207,7 +207,7 @@ export function applyProposalTap(store, binding, token, message, repos, options,
         return { effects, confirmed: false, ignored: true };
     }
     const who = verified.who;
-    const preview = proposalPreview(store, proposal, actionRepos, "telegram");
+    const preview = phoneProposalPreview(store, proposal, actionRepos);
     const origin = options.phoneOrigin?.() ?? null;
     if (preview.closed) {
         store.consumeTelegramProposalActions(proposal.id, now);
@@ -239,7 +239,7 @@ export function applyProposalTap(store, binding, token, message, repos, options,
         // A forged keyboard on a handoff card: nothing acts; the card is
         // repainted with its current link (or the honest absence of one).
         store.consumeTelegramProposalActions(proposal.id, now);
-        const wanted = proposalLink(store, proposal, actionRepos, "telegram");
+        const wanted = phoneProposalLink(store, proposal, actionRepos, "telegram");
         const link = phoneLinkButton(origin, wanted);
         ack(link === null ? "this step finishes on the computer" : "open the button below to finish this step");
         edit(handoffCardText(preview.text, linkNote(origin, wanted)), keyboardWith(null, link));
@@ -545,7 +545,7 @@ async function runTelegramConversation(row, args) {
                 // or went away carries the current truth, never a stored URL.
                 const proposal = part.kind === "card" && part.proposal !== null ? store.getLeadProposal(part.proposal) : null;
                 const origin = proposal === null ? null : options.phoneOrigin?.() ?? null;
-                const wanted = proposal === null ? null : proposalLink(store, proposal, repos);
+                const wanted = proposal === null ? null : phoneProposalLink(store, proposal, repos);
                 const keyboard = keyboardWith(part.keyboard, phoneLinkButton(origin, wanted));
                 // The lead's own words carry their bold anchors and labelled links as entities, never as Markdown characters.
                 const voiced = part.kind === "reply" ? telegramReply(part.text) : null;
@@ -625,7 +625,7 @@ async function runTelegramConversation(row, args) {
                 for (const image of selected)
                     parts.push({ kind: "image", text: image.caption, taskId: image.taskId, run: image.run, artifact: image.artifact, sha256: image.sha256 });
                 for (const proposal of proposals) {
-                    const preview = proposalPreview(store, proposal, repos, "telegram");
+                    const preview = phoneProposalPreview(store, proposal, repos);
                     const keyboard = preview.buttons ? mintCardTokens(store, binding, proposal.id, now).keyboard : null;
                     parts.push({ kind: "card", text: preview.text, proposal: proposal.id, keyboard });
                 }
@@ -763,11 +763,13 @@ async function runTelegramConversation(row, args) {
         react: () => transport("setMessageReaction", { chat_id: chatId, message_id: Number(row.messageId), reaction: [{ type: "emoji", emoji: WARM_EMOJI }] }),
         typing: () => transport("sendChatAction", { chat_id: chatId, action: "typing" }),
     });
+    const replyImage = row.replyTo === null ? undefined : store.telegramMessageBindings(binding, row.replyTo).find(one => one.taskId === row.taskId && one.run === row.sourceRun && one.image !== undefined)?.image;
     let outcome;
     try {
         outcome = await runLeadTurn({
             store, who, session, thread, config, key: null, message: row.text, requestId: row.request,
             ...(row.context === null ? {} : { context: row.context }),
+            ...(replyImage === undefined ? {} : { replyImage }),
             ...(options.subscriptionRunner === undefined ? {} : { subscriptionRunner: options.subscriptionRunner }),
             clock, evidenceRoot: options.evidenceRoot, revalidate, mediaDelivery: "documents", channel: "telegram", onProgress: warm.onProgress,
         });

package/dist/telegram.js

@@ -1852,7 +1852,7 @@ function applyConversation(context, update, effects) {
         if (tasks.length === 1) {
             taskId = tasks[0];
             sourceRun = bindings.find(one => one.run !== null)?.run ?? null;
-            context_ = replyContextFor(taskId, sourceRun);
+            context_ = replyContextFor(taskId, sourceRun, bindings.find(one => one.image !== undefined)?.image);
         }
     }
     // No reply target: the task this chat chose to talk about, if any. The

package/dist/tidy.d.ts

@@ -0,0 +1,130 @@
+import { type Store } from "./store.js";
+import type { WorkSummaryAccess } from "./work-summary.js";
+export type TidyRule = "release" | "routine" | "ci" | "finished";
+/** The preview's groups, in order. "finished" is a person's own choice only; tidy never applies it on its own. */
+export declare const TIDY_GROUPS: readonly {
+    rule: TidyRule;
+    label: string;
+}[];
+export declare const TIDY_DEFAULT_DAYS = 14;
+/** At most this many tasks are put away automatically per pass. */
+export declare const TIDY_PASS_LIMIT = 25;
+/** One task tidy would put away: its family's current task, every version that goes with it (`members`, task_ref ids),
+ * why, and under which rule. */
+export type TidyItem = {
+    rule: TidyRule;
+    taskId: string;
+    title: string;
+    repo: string | null;
+    reason: string;
+    updatedAt: string;
+    members: number[];
+};
+/** What the release journals say about one release task (release.ts writes them; read only). */
+export type ReleaseFact = {
+    taskId: string;
+    version: string;
+    product: string;
+    candidate: string;
+    superseded: boolean;
+    done: boolean;
+    published: boolean;
+    stopped: boolean;
+};
+/** Every release journal's facts, or why they can't be trusted: one unreadable journal leaves the release rule out. */
+export type ReleaseFacts = {
+    facts: ReleaseFact[];
+    problem: string | null;
+};
+/** Reads `releases/*.json` under the plane's state folder (the database's folder), written only by `toolroll release`.
+ * A symlink, a non-file, an oversized or unreadable journal makes the whole answer untrusted (`problem`), so the
+ * release rule then puts nothing away: a journal it can't read might be the one that says a release is in flight. */
+export declare function readReleaseFacts(stateDir: string): ReleaseFacts;
+/** The release journals beside this database (its folder is the plane's state folder). An in-memory or relative
+ * database has no state folder, so the release rule stays off rather than reading whatever folder it runs in. */
+export declare function releaseFactsFor(databaseFile: string): ReleaseFacts;
+/** -1, 0 or 1: numeric parts first, then a release above any of its pre-releases. */
+export declare function compareVersions(a: string, b: string): number;
+/** The failing runs older "Checks failed" cards of this trigger name (their own GitHub run links) that aren't on record
+ * yet, newest first, at most `limit`: the checks trigger reads each from GitHub so tidy can tell where it ran. */
+export declare function unprovenNoticeRuns(store: Store, trigger: number, repo: string, limit?: number): number[];
+/** A completed workflow run on the watched branch, as the checks trigger read it from GitHub (its poll through the
+ * person's own gh login, or its signed webhook): kept once per run. Only a push to the watched branch of the watched
+ * repository counts (a pull request from a fork whose branch is also called main does not). */
+export declare function recordBranchCheckRun(store: Store, watched: {
+    repo: string;
+    branch: string;
+}, run: {
+    id?: number | undefined;
+    name?: string | undefined;
+    head_sha?: string | undefined;
+    head_branch?: string | undefined;
+    conclusion?: string | undefined;
+    created_at?: string | undefined;
+    event?: string | undefined;
+    head_repository?: {
+        full_name?: string | undefined;
+    } | undefined;
+}, now: Date): boolean;
+/** What tidy would put away now, in group order, oldest first within a group. `days`: also offer finished tasks
+ * untouched that long (a person's preview only); null is tidy's own automatic rules. `access`: whose lists. */
+export declare function tidyPreview(store: Store, now: Date, input: {
+    releases: ReleaseFacts;
+    days: number | null;
+    access?: WorkSummaryAccess;
+}): TidyItem[];
+/** The preview's identity: exactly which tasks under which rules, for how many days. A person's confirmation names it. */
+export declare function tidyDigest(items: readonly TidyItem[], days: number | null): string;
+/** The preview in its groups (empty ones left out), with each group's label. */
+export declare function tidyGroups(items: readonly TidyItem[], days: number): {
+    rule: TidyRule;
+    label: string;
+    items: TidyItem[];
+}[];
+/** A day count from a person (1–365), or the default. */
+export declare function tidyDays(raw: string | null | undefined): number | null;
+export type TidyApply = {
+    ok: true;
+    archived: TidyItem[];
+    skipped: {
+        taskId: string;
+        message: string;
+    }[];
+} | {
+    ok: false;
+    reason: "changed" | "outside" | "empty";
+    message: string;
+    items: TidyItem[];
+    digest: string;
+};
+/** A person puts away exactly what they previewed (or the ticked part of it), in one write transaction that recomputes
+ * the preview and refuses when its digest moved or a ticked task isn't in it. */
+export declare function applyTidy(store: Store, now: Date, input: {
+    by: string;
+    days: number;
+    digest: string;
+    only: readonly string[] | null;
+    releases: ReleaseFacts;
+    access?: WorkSummaryAccess;
+}): TidyApply;
+/** Tidy on its own (the worker's reconcile pass): its automatic rules only, at most `limit` tasks, in one write
+ * transaction. Idempotent: what is put away is skipped next time, and a restored task is never put away again. */
+export declare function runTidy(store: Store, now: Date, releases: ReleaseFacts, limit?: number, access?: WorkSummaryAccess): TidyItem[];
+/** Whether this person may still put away or restore work in this project, read under the write lock (check and write
+ * together): an active approver who can see it. Null when they may; otherwise why not. */
+export declare function approverStandsNow(store: Store, name: string, repo: string | null): string | null;
+/** The repository of a task's family, from its first version (all versions share it). */
+export declare function familyRepoOf(store: Store, refs: readonly number[]): string | null;
+/** "Archived by tidy: <reason>" or "Archived by <person>: <reason>": the one sentence every surface shows. */
+export declare function archivedWords(archived: {
+    by: string;
+    byKind: "person" | "tidy";
+    reason: string;
+}): string;
+/** The release journals beside the store's own database file (none for an in-memory one). */
+export declare function releaseFactsOf(store: Store): ReleaseFacts;
+/** The lists one person sees, for tidy: every project for an unrestricted account, otherwise exactly theirs. The CLI's
+ * preview (`--as <name>`) and its apply read the same scope, so the same records give the same digest. */
+export declare function accessOf(store: Store, name: string): WorkSummaryAccess;
+/** Narrows `access` to the caller's own lens (a remote person's project limit): never wider. No lens: unchanged. */
+export declare function withinLens(access: WorkSummaryAccess, lens: readonly string[] | null): WorkSummaryAccess;