toolroll 0.9.101 → 0.9.103

package/dist/browser-workspace.d.ts

@@ -9,6 +9,7 @@ export { browserCrewFromIndex, browserWorkActionHref } from './browser-crew.js';
 import type { Store } from './store.js';
 import type { WorkSummaryAccess } from './work-summary.js';
 import type { StatusTone, StepRow } from './workspace-ui.js';
+import type { PageWork } from './page-work-contract.js';
 import type { Ask, AskChip } from './needs-you.js';
 import type { WorkIndexGroup } from './work-index.js';
 import type { AssignmentCard } from './assignment-ui.js';
@@ -486,9 +487,12 @@ export type BrowserTaskView = {
         }[];
     } | null;
     /** Server cards that may need a person now (stop/resume, scope prompt, plan, live attempt). */
+    /** `instance`: what the block is about now (the attempt card: its build). The page installs a block's HTML once;
+     * another instance replaces it. */
     lead: {
         key: string;
         html: string;
+        instance?: string;
     }[];
     questions: string;
     facts: BrowserTaskFact[];
@@ -549,6 +553,8 @@ export type BrowserTaskView = {
         /** When a remembered password stops counting (ISO); the page words it in the viewer's zone. */
         rememberedUntil: string | null;
         planHtml: string;
+        /** The plan sheet alone (no editor, no form): what Home shows beside its Approve (live-pages-and-home.md B2.1). */
+        sheetHtml?: string;
         /** The terms line in words, when the rule isn't one of the kit's (easy-start C5: a laptop's own owner). */
         termsWords?: string;
     } | null;
@@ -1613,6 +1619,15 @@ export type BrowserWorkspace = {
     user: string;
     csrf: string;
     sensitive: boolean;
+    /** True when this page may replace another without a document load (docs/plans/live-pages-and-home.md A1.1): the server
+     * sets it on every workspace it sends; absent (an older server, a fixture) is false. */
+    inPlace?: boolean;
+    /** What the app runs for this page in place of a page script (docs/plans/task-page-in-app.md): data, a closed list.
+     * Present only when the app covers the page's whole script; the document then ships no page script string. */
+    work?: readonly PageWork[];
+    /** This document ships a page script string (set on a document load only). Its listeners live as long as the
+     * document, so the app never changes pages in place from it, and never runs `work` in it. */
+    scripted?: boolean;
     /** Passwordless is on for this signed-in browser: ceremony password fields are left out (docs/plans/passwordless.md). */
     passwordless?: boolean;
     /** The session's open project (its path), or null: the sidebar's project picker names it. */
@@ -1688,13 +1703,14 @@ export type BrowserWorkspace = {
         command: string;
     };
 };
-/** Home ("/"): one sentence that answers "what needs me?", four counts that agree with the Tasks filters they open,
- * the work grouped as Waiting on you, Working and Done, and the selected item answered in place. */
+/** Home ("/", docs/plans/live-pages-and-home.md B1): the heading said once, one quiet line for what runs and waits, what
+ * needs this person grouped by what is asked (each group with its exact count), the selected one open beside the list,
+ * and the lead's last message above the message box. With nothing waiting: what runs and what finished today. */
 export type BrowserHomeView = {
     kind: 'home';
-    /** "7 need you across 2 projects.", derived from the same counts as the figures. */
+    /** "19 tasks need you", "Nothing needs you", read from the same total as the rail's count. */
     say: string;
-    /** The project in view (a path) or every project (null), and the scope links (null with one project). */
+    /** The project in view (a path) or every project (null), and the project filter's choices (null with one project). */
     project: string | null;
     scopes: {
         key: string;
@@ -1702,29 +1718,43 @@ export type BrowserHomeView = {
         href: string;
         active: boolean;
     }[] | null;
+    /** The work index totals, each with the Tasks list it opens. */
     counts: {
         key: 'needs' | 'running' | 'queued' | 'finished';
         label: string;
         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). */
+    /** What needs you, by what is asked, in this order: release, approve, answer, flow, wrong, review, setup, other
+     * (anything none of the others fits; docs/plans/home-other-asks.md). `count` is the exact total for that ask, past the
+     * rows listed. */
     groups: {
-        key: 'you' | 'working' | 'done';
+        key: BrowserHomeAsk;
         label: string;
+        count: number;
         rows: BrowserHomeRow[];
     }[];
-    /** More waits on you than the list shows: open them all in Tasks. */
-    more: {
+    /** What runs, then what waits its turn. */
+    working: BrowserHomeRow[];
+    /** What was completed today: the exact figure, the newest rows, and the list that has them all. */
+    finishedToday: {
         count: number;
+        rows: BrowserHomeRow[];
         href: string;
-    } | null;
+    };
     newTask: string;
     /** The lead's message box, where chat is allowed for this person: a POST to /chat in this scope. */
     ask: {
         project: string | null;
         placeholder: string;
     } | null;
+    /** The lead's last message in this person's main thread, as one plain line that opens the chat; null when there is
+     * none or this person may not read that thread. */
+    lastLead: {
+        text: string;
+        age: string;
+        href: string;
+    } | null;
     empty: {
         title: string;
         text: string;
@@ -1732,19 +1762,25 @@ export type BrowserHomeView = {
     /** While the first run is open (no first result yet): the welcome's address, linked as Finish setup. */
     setup?: string | null;
 };
+/** What a waiting row asks (work-index.ts WorkAskGroup), plus a flow card waiting on you and a first-run step. */
+export type BrowserHomeAsk = 'release' | 'approve' | 'answer' | 'flow' | 'wrong' | 'review' | 'setup' | 'other';
 export type BrowserHomeRow = {
+    /** A task row's family id; a row that isn't a task is namespaced (`release:<task>`, `flow:<card>`, `setup:<step>`). */
     id: string;
     title: string;
     href: string;
     project: string | null;
     age: string;
-    chip: {
-        word: string;
-        tone: '' | 'needs' | 'ask' | 'live' | 'done' | 'failed';
-    };
+    /** Which list it is in: it needs you, it runs, it waits its turn, or it finished. */
+    state: 'needs' | 'running' | 'queued' | 'done';
+    /** What it asks of you (its group), or null when it doesn't wait on you. */
+    ask: BrowserHomeAsk | null;
+    /** Why, in one short line: only a row where something went wrong. */
+    reason: string | null;
     /** One line: what it asks, or what the agent is doing now. */
     line: string | null;
-    /** The one act that resolves it (a link), or null. */
+    /** The one act that resolves it (a link), or null. A release, a flow card or a setup step is never acted on at
+     * Home: its one link opens its own page. */
     action: {
         label: string;
         href: string;
@@ -1933,3 +1969,4 @@ export type MergeReadyView = {
         act: MergeReadyAct | null;
     }[];
 };
+export type { PageWork } from './page-work-contract.js';

package/dist/browser-workspace.js

@@ -97,11 +97,13 @@ export function browserProjectsOf(projects) {
 export function browserNavigationOf(path, project = null, needsYou = 0, tasksProject = project, needsYouLabel) {
     const pathname = path.split('?')[0].split('#')[0];
     const under = (...roots) => roots.some(root => pathname === root || pathname.startsWith(`${root}/`));
-    // The rail (UI revamp, wave B): Home carries the one Needs-you count; the lead chat and an agent's question live
-    // under Home, a task's pages under Tasks, every computer and terminal under Agents, every setting under Settings.
+    // The rail (UI revamp, wave B; Chat under Home, live-pages-and-home.md B1): Home carries the one Needs-you count and
+    // an agent's question lives under it; the lead chat is its own item; a task's pages under Tasks, every computer and
+    // terminal under Agents, every setting under Settings.
     return [
-        { label: 'Home', href: '/', active: pathname === '/' || pathname === '/chat' || under('/d', '/activity', '/morning'),
+        { label: 'Home', href: '/', active: pathname === '/' || under('/d', '/activity', '/morning'),
             ...(needsYou > 0 ? { count: needsYou, ...(needsYouLabel === undefined ? {} : { countLabel: needsYouLabel }) } : {}) },
+        { label: 'Chat', href: '/chat', active: under('/chat') },
         { label: 'Tasks', href: `/tasks${tasksProject === null ? '' : `?project=${encodeURIComponent(tasksProject)}`}`,
             active: under('/tasks', '/t', '/r', '/review') },
         { label: 'Flows', href: '/flows', active: under('/flows', '/recipes', '/kits', '/routines') },

package/dist/flow-engine.d.ts

@@ -9,6 +9,9 @@ export type FlowAdvance = {
 export declare function flowDefinitionOf(flow: FlowRow): FlowDefinition | null;
 /** Where a card's link opens: the flow's canvas with the card selected. */
 export declare const flowCardHref: (flow: number, card: number) => string;
+/** A reply wait that timed out with nowhere to send the card asks its owner (or the flow's owner) to move it on: the
+ * card's waiting words end with this (flows-ui.ts flowCardWaitsOn reads it). */
+export declare const NO_REPLY_MOVE_ON = "Move the card on when you're ready.";
 /** Where a confirmed flow action may point: a flow's canvas, maybe with one card open. */
 export declare const FLOW_HREF: RegExp;
 /** Advance every active card in one project's flows. */

package/dist/flow-engine.js

@@ -36,6 +36,9 @@ export function flowDefinitionOf(flow) {
 }
 /** Where a card's link opens: the flow's canvas with the card selected. */
 export const flowCardHref = (flow, card) => `/flows/${flow}?card=${card}`;
+/** A reply wait that timed out with nowhere to send the card asks its owner (or the flow's owner) to move it on: the
+ * card's waiting words end with this (flows-ui.ts flowCardWaitsOn reads it). */
+export const NO_REPLY_MOVE_ON = "Move the card on when you're ready.";
 /** Where a confirmed flow action may point: a flow's canvas, maybe with one card open. */
 export const FLOW_HREF = /^\/flows\/[1-9][0-9]{0,9}(\?card=[1-9][0-9]{0,9})?$/;
 const ACCEPTANCE = FLOW_ACCEPTANCE;
@@ -173,7 +176,7 @@ function advanceCard(store, flow, definition, card, now, options, outcome) {
                     outcome.moved++;
                 return;
             }
-            const waiting = `No reply after ${words}. Move the card on when you're ready.`;
+            const waiting = `No reply after ${words}. ${NO_REPLY_MOVE_ON}`;
             if (card.waiting !== waiting) {
                 store.updateFlowCard(card.id, { waiting }, now);
                 notifyPeople(store, card, [card.owner ?? flow.owner], null, { key: `no-reply:${card.entry}`, subject: `No reply to “${card.title}” after ${words}`, body: `It's waiting in ${stage.title}.`, attention: true }, now);

package/dist/flows-ui.d.ts

@@ -1,5 +1,6 @@
 import type { BrowserFlowView } from "./browser-workspace.js";
-import type { FlowRow, Store } from "./store.js";
+import { type FlowStage } from "./flows.js";
+import type { FlowCardRow, FlowRow, Store, SubagentQuestionRow } from "./store.js";
 import { type FlowFile, type FlowImportPlan } from "./flow-share.js";
 import { type Html } from "./html.js";
 /** The flow page's fallback rules, plus the Flows list and the import preview (kit pieces; only layout here). */
@@ -24,6 +25,35 @@ export declare function flowImportHtml(input: {
     previewed: string;
     problem: string | null;
 }): Html;
+/** Why a card waits on this person now (docs/plans/home-other-asks.md part 4, v2.3): the one rule the flow page's
+ * Decide and Home's Flow decisions both read, so they never disagree. Each needs approver standing:
+ * - `decide`: an approval zone it is theirs to decide (the zone's decider, the flow's owner for "to owner", any approver
+ *   when none is named), and no subagent of the zone deciding it first;
+ * - `choose`: a "Person chooses" zone waiting on them (flow-send.ts flowChoiceAt);
+ * - `answer`: its subagent's open question or tool-call request asked of them;
+ * - `browser`: a check zone waiting for browser use, which only an approver with every project may allow;
+ * - `reply`: a reply wait that ran out with nowhere to go, asking the card's owner (else the flow's) to move it on.
+ * `reads` passes what the caller already read (a missing key is read here). */
+export type FlowCardWait = {
+    decide: boolean;
+    choose: boolean;
+    answer: boolean;
+    browser: boolean;
+    reply: boolean;
+};
+export declare function flowCardWaitsOn(store: Store, flow: FlowRow, card: FlowCardRow, viewer: {
+    name: string;
+    approver: boolean;
+}, reads?: {
+    stage?: FlowStage | undefined;
+    asked?: SubagentQuestionRow | null;
+    choosing?: {
+        person: string;
+    } | null;
+    browser?: {
+        status: string;
+    } | null;
+}): FlowCardWait;
 /** One flow's canvas for one person. */
 export declare function flowView(store: Store, flow: FlowRow, viewer: {
     name: string;

package/dist/flows-ui.js

@@ -1,7 +1,7 @@
 /** Flows in the console: the list of a person's flows, and one flow's canvas
  * (the React view's data, plus a plain fallback page the view replaces). */
 import { liveAttemptOf, steerControlsFor } from "./steer-controls.js";
-import { draftFor, flowDefinitionOf } from "./flow-engine.js";
+import { draftFor, flowDefinitionOf, NO_REPLY_MOVE_ON } from "./flow-engine.js";
 import { describeStandingOrder } from "./flow-schedule.js";
 import { describeTrigger, triggerHeadline, FLOW_TRIGGER_KINDS, FLOW_TRIGGER_WORDS, githubRepoOf, HOOK_PATH, hookReady, planeStatusLink, readHooksBase, readLinearKey, senderOf, takesDeliveries, triggerConfigOf } from "./flow-triggers.js";
 import { SENDER_WORDS } from "./webhook-signing.js";
@@ -14,7 +14,7 @@ import { parseSortDecision, sortChip } from "./flow-sort.js";
 import { flowSecretNames, readEmailSettings, sendingReady } from "./flow-actions.js";
 import { projectToolsOf, secretsSetFor, toolStanding } from "./project-tools.js";
 import { flowFingerprint } from "./flow-live.js";
-import { flowChoiceAt, readFlowSend } from "./flow-send.js";
+import { flowChoiceAt, flowPersonOf, readFlowSend } from "./flow-send.js";
 import { itemCaption, whyLines } from "./flow-items.js";
 import { FLOW_FILE_MAX_BYTES } from "./flow-share.js";
 import { googleConnected } from "./google-mail.js";
@@ -224,6 +224,37 @@ const historyText = (event, title, sorts = new Set()) => {
         default: return `Moved to ${title(event.toStage)}${who}${note}`;
     }
 };
+export function flowCardWaitsOn(store, flow, card, viewer, reads = {}) {
+    const none = { decide: false, choose: false, answer: false, browser: false, reply: false };
+    if (!viewer.approver || card.state !== "active")
+        return none;
+    const stage = "stage" in reads ? reads.stage : flowDefinitionOf(flow)?.stages.find(one => one.id === card.stage);
+    // Its subagent's open question is the person's to answer whatever zone it is in, even one since removed from the flow
+    // (the flow page shows it and takes the answer).
+    const asked = "asked" in reads ? reads.asked ?? null : store.openSubagentQuestionOn(card.id, card.entry);
+    const answer = asked !== null && asked.state === "open" && asked.askedOf === viewer.name && store.getSubagent(asked.subagent) !== null;
+    if (stage === undefined)
+        return { ...none, answer };
+    const decider = stage.kind === "approval" ? deciderOf(stage, flow) : null;
+    // While its subagent is deciding (v92), the card isn't anyone else's to decide yet.
+    const subagentDeciding = stage.subagent !== undefined && card.waiting !== null && card.waiting.endsWith(" is deciding");
+    const choosing = stage.kind !== "choose" ? null : "choosing" in reads ? reads.choosing ?? null : flowChoiceAt(store, card.id, card.entry);
+    const browser = stage.kind !== "check" || stage.browser !== true ? null : "browser" in reads ? reads.browser ?? null : browserViewOf(store, flow);
+    const wait = stage.wait ?? { for: "reply" };
+    return {
+        decide: stage.kind === "approval" && (decider === null || decider === viewer.name) && !subagentDeciding,
+        choose: choosing !== null && choosing.person === viewer.name,
+        answer,
+        browser: browserWaitOn(card, stage, browser) && store.accountOf(viewer.name)?.projects === null,
+        reply: stage.kind === "wait" && wait.for === "reply" && card.waiting !== null && card.waiting.startsWith("No reply after ") && card.waiting.endsWith(NO_REPLY_MOVE_ON)
+            && flowPersonOf(card, flow) === viewer.name,
+    };
+}
+/** A check zone's card waiting for browser use (flow-browser.ts): the flow's browser isn't allowed and the card says so. */
+function browserWaitOn(card, stage, browser) {
+    return card.state === "active" && stage?.kind === "check" && stage.browser === true && browser !== null && browser.status !== "allowed"
+        && card.waiting !== null && card.waiting.startsWith(`${stage.title} starts a browser`);
+}
 /** One flow's canvas for one person. */
 export function flowView(store, flow, viewer, selectedCard, setup = { dir: null, repos: [] }) {
     const definition = flowDefinitionOf(flow);
@@ -249,10 +280,12 @@ export function flowView(store, flow, viewer, selectedCard, setup = { dir: null,
         const canReadTask = taskRepo !== null && (taskRepo === flow.repo || (setup.repos.includes(taskRepo) && store.accountCanAccess(viewer.name, taskRepo)));
         const discussion = store.flowComments(card.id);
         const watchers = store.flowCardWatchers(card.id);
-        const decider = stage?.kind === "approval" ? deciderOf(stage, flow) : null;
-        // While its subagent is deciding (v92), the card isn't anyone else's to decide yet.
-        const subagentDeciding = stage?.subagent !== undefined && card.waiting !== null && card.waiting.endsWith(" is deciding");
-        const canDecide = viewer.approver && card.state === "active" && stage?.kind === "approval" && (decider === null || decider === viewer.name) && !subagentDeciding;
+        // Its open question: one of its own, or (v94) a tool call waiting for approval.
+        const asked = card.state === "active" ? store.openSubagentQuestionOn(card.id, card.entry) : null;
+        // "Person chooses" (flow-send.ts): what was sent, and the options, for the person it waits on; the latest send otherwise.
+        const choosing = card.state === "active" && stage?.kind === "choose" ? flowChoiceAt(store, card.id, card.entry) : null;
+        // Who may decide it here: the one rule Home reads too (flowCardWaitsOn).
+        const canDecide = flowCardWaitsOn(store, flow, card, viewer, { stage, asked, choosing, browser: browserNow }).decide;
         // History reads moves and ownership together, newest first.
         const owned = discussion.filter(one => one.kind === "owner").map(one => ({ text: one.body === "" ? `${one.author} left it without an owner` : one.body === one.author ? `${one.author} took it on` : `${one.author} made ${one.body} the owner`, at: one.at }));
         const moves = store.flowEvents(card.id).map(event => ({ text: historyText(event, title, sortZones), at: event.at }));
@@ -266,8 +299,6 @@ export function flowView(store, flow, viewer, selectedCard, setup = { dir: null,
             at: until.toISOString(),
             label: stage.wait !== undefined && stage.wait.for !== "hours" ? (stage.wait.for === "reply" ? "No reply by" : "Moves on at") : stage.limit.to !== null ? `Moves to ${title(stage.limit.to)} at` : "Reminder at",
         };
-        // Its open question: one of its own, or (v94) a tool call waiting for approval.
-        const asked = card.state === "active" ? store.openSubagentQuestionOn(card.id, card.entry) : null;
         const pending = asked?.toolCall == null ? null : store.subagentCall(asked.toolCall);
         // A decision its subagent handed over carries what the subagent said (v92).
         const turn = card.state === "active" && stage?.kind === "approval" && stage.subagent !== undefined ? store.flowStepRun(card.id, card.entry) : null;
@@ -284,8 +315,6 @@ export function flowView(store, flow, viewer, selectedCard, setup = { dir: null,
             }
         }
         const asker = asked === null || asked.state !== "open" ? null : store.getSubagent(asked.subagent);
-        // "Person chooses" (flow-send.ts): what was sent, and the options, for the person it waits on; the latest send otherwise.
-        const choosing = card.state === "active" && stage?.kind === "choose" ? flowChoiceAt(store, card.id, card.entry) : null;
         const latest = store.flowSends(card.id)[0] ?? null;
         const sentContent = latest === null ? null : readFlowSend(latest.contentJson);
         // On the card itself: where it came from (the card's title is right above), and only the links the panel doesn't already have.
@@ -295,8 +324,7 @@ export function flowView(store, flow, viewer, selectedCard, setup = { dir: null,
             // After research: the same numbered items the message carried, each beside its screenshot.
             ...(content.items === undefined ? {} : { items: content.items.map((item, index) => ({ number: index + 1, title: item.title, lines: whyLines(item.why), source: item.source, url: item.url,
                     image: item.shot === null || content.shots === null ? null : { src: `/r/${content.shots.run}/evidence/${item.shot}`, caption: itemCaption(index + 1, item) } })) }) });
-        const browserWait = card.state === "active" && stage?.kind === "check" && stage.browser === true && browser !== null && browser.status !== "allowed"
-            && card.waiting !== null && card.waiting.startsWith(`${stage.title} starts a browser`);
+        const browserWait = browserWaitOn(card, stage, browser);
         return {
             id: card.id, title: card.title, description: card.description, stage: card.stage, state: card.state,
             waiting: card.state === "active" && card.task !== null && (stage?.kind === "task" || stage?.kind === "report")

package/dist/page-work-contract.d.ts

@@ -0,0 +1,21 @@
+/**
+ * One behaviour the app runs for the page on screen instead of a page script string (docs/plans/task-page-in-app.md).
+ * `answer`: a question's inline answer (render-tasks.ts decisionAnswerScript). `region`: a server-drawn region kept
+ * current from a build's own fragment (chrome.ts regionScript), `/r/<run>?fragment=check|peek`. `result`: reviewing the
+ * result the page shows (result-review.ts RESULT_REVIEW_SCRIPT with render-results.ts reviewEvidenceScript). No code,
+ * selector or address travels here: the app runs only the kinds it knows.
+ */
+export type PageWork = {
+    kind: "answer";
+} | {
+    kind: "result";
+} | {
+    kind: "region";
+    region: "check-progress" | "run-peek";
+    run: number;
+};
+/** The work the app and the server agree on. A workspace read says it with `x-toolroll-work`; a reader that does not
+ * say exactly this version (an older tab) gets the page as a document with its script string, as before. A hint, never
+ * authority. It moves whenever a kind is added: 2 added `result`. */
+export declare const PAGE_WORK_VERSION = 2;
+export declare const PAGE_WORK_HEADER = "x-toolroll-work";

package/dist/page-work-contract.js

@@ -0,0 +1,5 @@
+/** The work the app and the server agree on. A workspace read says it with `x-toolroll-work`; a reader that does not
+ * say exactly this version (an older tab) gets the page as a document with its script string, as before. A hint, never
+ * authority. It moves whenever a kind is added: 2 added `result`. */
+export const PAGE_WORK_VERSION = 2;
+export const PAGE_WORK_HEADER = "x-toolroll-work";

package/dist/project-knowledge.d.ts

@@ -22,19 +22,19 @@ export type KnowledgeView = ReturnType<typeof knowledgeView>;
 export declare function knowledgeVersion(store: Store, repo: string, actor: string, revision: number): Knowledge;
 /** Chat reads only an admitted project. Keep the full source in the project UI. */
 export declare function conversationKnowledge(store: Store, repo: string, actor: string, reference?: string, decision?: number): {
-    history?: never;
+    title?: never;
+    content?: never;
     revision: number;
     stale: boolean;
     notice: string;
-    title?: never;
-    content?: never;
+    history?: never;
     instructions?: never;
     references?: never;
     decisions?: never;
     waiting?: never;
 } | {
-    revision?: never;
-    history?: never;
+    title?: never;
+    content?: never;
     stale?: never;
     decision: {
         repo: string;
@@ -52,27 +52,27 @@ export declare function conversationKnowledge(store: Store, repo: string, actor:
     };
     afterwards?: string;
     notice: string;
-    title?: never;
-    content?: never;
+    revision?: never;
+    history?: never;
     instructions?: never;
     references?: never;
     decisions?: never;
     waiting?: never;
 } | {
-    history?: never;
     stale?: never;
     revision: number;
     title: string;
     content: string;
     notice: string;
+    history?: never;
     instructions?: never;
     references?: never;
     decisions?: never;
     waiting?: never;
 } | {
-    stale?: never;
     title?: never;
     content?: never;
+    stale?: never;
     revision: number;
     history: {
         revision: number;

package/dist/release-approval.d.ts

@@ -1,22 +1,8 @@
 import { type PullRequestReader, type ReleaseCard, type ReleaseSeal, type TermLine } from "./release-card.js";
 import { type ApproveResult, type Scope } from "./scope.js";
 import { type Notification, type Store } from "./store.js";
-/** The ledger act holding the coordinator's latest reading of the pull request's CI on the exact candidate. */
-export declare const RELEASE_CI_SEEN_ACTION = "release CI observed";
-/** One check's newest attempt, as the coordinator's own gh read it. A re-run is a new check run id. */
-export type ReleaseCiRun = {
-    id: number | null;
-    name: string;
-    status: string;
-    conclusion: string | null;
-};
-export type ReleaseCiSnapshot = {
-    candidate: string;
-    at: string;
-    state: "passed" | "running" | "failed";
-    failed: string[];
-    runs: ReleaseCiRun[];
-};
+import { type ReleaseCiSnapshot } from "./release-refusal.js";
+export { ciWords, releaseApprovalRefusal, releaseCiOf, RELEASE_CI_SEEN_ACTION, type ReleaseCiRun, type ReleaseCiSnapshot } from "./release-refusal.js";
 /**
  * Record what the coordinator just read of the pull request's CI on `candidate` (its verdict and every check's newest
  * attempt), when it differs from the last reading recorded: the sheet and the CLI show it, and the card digest binds
@@ -35,13 +21,9 @@ export declare function recordReleaseCi(store: Store, input: {
     }[];
     now: Date;
 }): boolean;
-/** The coordinator's latest CI reading for this task on exactly `candidate`, or null (not read yet, or another commit). */
-export declare function releaseCiOf(store: Store, taskId: string, candidate: string): ReleaseCiSnapshot | null;
 /** What of a CI reading the card binds: its state and each check's attempt, whether it finished, and how. Queued and
  * in progress read alike (neither is finished); the time it was read is not bound. */
 export declare function ciBinding(ci: ReleaseCiSnapshot | null): unknown;
-/** GitHub CI in one line, as the sheet and the CLI say it. */
-export declare function ciWords(ci: ReleaseCiSnapshot | null, candidate: string): string;
 export type ReleaseApprovalCard = {
     taskId: string;
     taskRef: number;
@@ -189,3 +171,10 @@ export declare function waitingJournals(stateDir: string, expectedFile: (branch:
     journals: WaitingJournal[];
     unreadable: string[];
 };
+/** A release as Home names it (docs/plans/home-other-asks.md, part 1): its version, and why it can't take a yes now
+ * in the sheet's own words (`refusalOf`, the one source), or null when this isn't a release. Reads only; Home never
+ * approves one, it links to the sheet. */
+export declare function releaseAskOf(store: Store, taskId: string): {
+    version: string;
+    refusal: string | null;
+} | null;

package/dist/release-approval.js

@@ -19,20 +19,19 @@ import { lstatSync, readdirSync, readFileSync, realpathSync } from "node:fs";
 import { join } from "node:path";
 import { permissionPlainWords } from "./chat-terms.js";
 import { approvalTermsOf, releaseAccessWords, releaseCardOf, releaseSealOf } from "./release-card.js";
-import { releaseCiHoldOf, releaseCiHoldWords } from "./release-ci-hold.js";
 import { approvalOf } from "./scope.js";
 import { releaseProgressFor } from "./store.js";
 import { taskArchived } from "./task-archive.js";
 import { cleanTerminalLine } from "./terminal-text.js";
+import { ciName, ciWords, refusalOf, releaseCiOf, RELEASE_CI_SEEN_ACTION } from "./release-refusal.js";
+// The CI reading and the refusals live in release-refusal.ts, so scope.ts approve() can read them without a cycle.
+export { ciWords, releaseApprovalRefusal, releaseCiOf, RELEASE_CI_SEEN_ACTION } from "./release-refusal.js";
 const SHA = /^[0-9a-f]{40}$/;
 const DIGEST = /^[0-9a-f]{64}$/;
 /** A scope digest as scope.ts writes it. */
 const SCOPE_DIGEST = /^[0-9a-f]{32,64}$/;
 const sha256 = (text) => createHash("sha256").update(text).digest("hex");
 // ---- GitHub CI as the coordinator read it -------------------------------------------------------------------------
-/** The ledger act holding the coordinator's latest reading of the pull request's CI on the exact candidate. */
-export const RELEASE_CI_SEEN_ACTION = "release CI observed";
-const ciName = (value) => cleanTerminalLine(String(value ?? "")).trim().slice(0, 120);
 /**
  * Record what the coordinator just read of the pull request's CI on `candidate` (its verdict and every check's newest
  * attempt), when it differs from the last reading recorded: the sheet and the CLI show it, and the card digest binds
@@ -58,60 +57,11 @@ export function recordReleaseCi(store, input) {
         action: RELEASE_CI_SEEN_ACTION, outcome: input.state, source: "work", detail });
     return true;
 }
-/** The coordinator's latest CI reading for this task on exactly `candidate`, or null (not read yet, or another commit). */
-export function releaseCiOf(store, taskId, candidate) {
-    const row = store.handle.prepare("SELECT detail, at FROM action_ledger WHERE task_id = ? AND action = ? ORDER BY id DESC LIMIT 1").get(taskId, RELEASE_CI_SEEN_ACTION);
-    if (row === undefined)
-        return null;
-    let parsed;
-    try {
-        parsed = JSON.parse(String(row["detail"]));
-    }
-    catch {
-        return null;
-    }
-    const one = parsed;
-    if (one.v !== 1 || one.candidate !== candidate || !["passed", "running", "failed"].includes(String(one.state)) || !Array.isArray(one.failed) || !Array.isArray(one.runs))
-        return null;
-    return { candidate, at: String(row["at"]), state: one.state, failed: one.failed.map(ciName),
-        runs: one.runs.map(run => { const r = run; return { id: typeof r["id"] === "number" ? r["id"] : null, name: ciName(r["name"]), status: ciName(r["status"]), conclusion: r["conclusion"] == null ? null : ciName(r["conclusion"]) }; }) };
-}
 /** What of a CI reading the card binds: its state and each check's attempt, whether it finished, and how. Queued and
  * in progress read alike (neither is finished); the time it was read is not bound. */
 export function ciBinding(ci) {
     return ci === null ? null : { candidate: ci.candidate, state: ci.state, failed: ci.failed, runs: ci.runs.map(run => [run.id, run.name, run.status === "completed", run.conclusion]) };
 }
-/** GitHub CI in one line, as the sheet and the CLI say it. */
-export function ciWords(ci, candidate) {
-    const short = candidate.slice(0, 7);
-    if (ci === null)
-        return `GitHub CI on ${short} hasn't been read yet.`;
-    if (ci.state === "passed")
-        return `GitHub CI passed on ${short}.`;
-    if (ci.state === "failed")
-        return `GitHub CI failed on ${short}: ${ci.failed.join(", ") || "a check"}.`;
-    const finished = ci.runs.filter(run => run.status === "completed").length;
-    return `GitHub CI is running on ${short}: ${finished} of ${ci.runs.length} checks finished.`;
-}
-/** The release check failed on this task already (the coordinator's record): nobody approves it again here. */
-function checkFailed(store, taskId) {
-    return store.handle.prepare("SELECT 1 FROM release_step WHERE task_id = ? AND step = 'check' AND state = 'failed' LIMIT 1").get(taskId) !== undefined;
-}
-/** Why a release can't be approved now, from the plane's own state, or null. */
-function refusalOf(store, taskId, scope, ci) {
-    if (taskArchived(store, taskId))
-        return "This release is put away. Restore it before approving.";
-    const hold = releaseCiHoldOf(store, taskId);
-    if (hold !== null)
-        return releaseCiHoldWords(hold);
-    if (ci?.state === "failed")
-        return `${ciWords(ci, scope.candidate)} Fix the branch or rerun the failed job on GitHub, then release again.`;
-    if (checkFailed(store, taskId))
-        return "The release check already failed on this commit. Fix the branch and release the new commit.";
-    if (scope.approvedAt !== null && scope.approvedDigest !== scope.digest)
-        return "The release's terms changed after an earlier approval. Read them again.";
-    return null;
-}
 /** A release task from the plane's own state: a sealed form (terms or a release check's purpose) whose repository is the
  * task's project and whose approved commit is the scope's candidate. Never from a title or a task id. */
 export function releaseTaskOf(store, taskId) {
@@ -380,3 +330,14 @@ export function waitingJournals(stateDir, expectedFile) {
     }
     return { journals, unreadable };
 }
+/** A release as Home names it (docs/plans/home-other-asks.md, part 1): its version, and why it can't take a yes now
+ * in the sheet's own words (`refusalOf`, the one source), or null when this isn't a release. Reads only; Home never
+ * approves one, it links to the sheet. */
+export function releaseAskOf(store, taskId) {
+    const found = releaseTaskOf(store, taskId);
+    if (found === null)
+        return null;
+    const { scope, seal } = found;
+    const refusal = approvalOf(scope).approved ? null : refusalOf(store, taskId, scope, releaseCiOf(store, taskId, scope.candidate));
+    return { version: seal.identity.packageVersion, refusal };
+}

package/dist/release-refusal.d.ts

@@ -0,0 +1,32 @@
+import type { Scope } from "./scope.js";
+import type { Store } from "./store.js";
+/** The ledger act holding the coordinator's latest reading of the pull request's CI on the exact candidate. */
+export declare const RELEASE_CI_SEEN_ACTION = "release CI observed";
+/** One check's newest attempt, as the coordinator's own gh read it. A re-run is a new check run id. */
+export type ReleaseCiRun = {
+    id: number | null;
+    name: string;
+    status: string;
+    conclusion: string | null;
+};
+export type ReleaseCiSnapshot = {
+    candidate: string;
+    at: string;
+    state: "passed" | "running" | "failed";
+    failed: string[];
+    runs: ReleaseCiRun[];
+};
+export declare const ciName: (value: unknown) => string;
+/** The coordinator's latest CI reading for this task on exactly `candidate`, or null (not read yet, or another commit). */
+export declare function releaseCiOf(store: Store, taskId: string, candidate: string): ReleaseCiSnapshot | null;
+/** GitHub CI in one line, as the sheet and the CLI say it. */
+export declare function ciWords(ci: ReleaseCiSnapshot | null, candidate: string): string;
+/** Why a release can't be approved now, from the plane's own state, or null. */
+export declare function refusalOf(store: Store, taskId: string, scope: Scope, ci: ReleaseCiSnapshot | null): string | null;
+/**
+ * The release refusals every approval road shares (scope.ts approve(), read inside its transaction): for a scope
+ * sealing release terms or a release check's purpose, the sheet's own reasons in the sheet's own words, so the task
+ * page, Home's in-place yes, chat and `toolroll task approve` refuse exactly what `/t/<id>/release` refuses. Null for
+ * every other scope, and for a release nothing stops. The sheet's card digest binding stays the sheet's.
+ */
+export declare function releaseApprovalRefusal(store: Store, taskId: string, scope: Scope): string | null;