toolroll 0.9.83 → 0.9.85

package/dist/contracts/youiyoux-request.js

@@ -0,0 +1,152 @@
+/**
+ * A youiyoux request as Toolroll reads it (youiyoux-intake.ts): the published `youi.request/v1` schema (youiyoux's
+ * schema/youi.request.schema.json), held to its own limits, and the `youi.proposal/v1` options file an options request's
+ * agent writes (schema/youi.proposal.schema.json). Unknown keys are allowed, as the published schemas allow them;
+ * everything Toolroll reads is checked here, and every string is outside text all the same.
+ */
+import { z } from "zod";
+import { parseContract } from "./contract.js";
+export const REQUEST_ID = /^r-[0-9a-f]{10}$/;
+/** An options file's id: `p-` and the same 10 hex as the options request it answers. */
+export const PROPOSAL_ID = /^p-[0-9a-f]{10}$/;
+/** The provenance every task filed from a request carries (task_ref.filed_via): immutable, and the seal reads it. */
+export const YOUIYOUX_FILED_VIA = "youiyoux";
+/** The one chat card a pass's filings make for a project (youiyoux-intake.ts), drawn by chat-decide.ts: the new tasks,
+ * Approve all and each one's own Approve and Open. */
+export const YOUIYOUX_CARD_KIND = "youiyoux-requests";
+/** Where a person sees and approves everything waiting on them in the console (flow-triggers.ts NEEDS_YOU_HREF). */
+export const YOUIYOUX_HOME_PATH = "/work?view=needs-you";
+const text = (max) => z.string().min(1).max(max);
+const who = z.object({ kind: z.enum(["person", "agent"]), name: text(100) });
+// The published schema's date-time: an ISO timestamp with a zone.
+const when = z.string().max(40).regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/);
+export const YOUIYOUX_EVIDENCE = ["screenshot", "check", "changed-path", "manual-review"];
+/** A component prop as youiyoux names one: what an option may set. */
+const PROP = /^[A-Za-z_$][\w$]{0,63}$/;
+const value = z.union([z.string().max(2000), z.number().finite(), z.boolean()]);
+/** What an options request offers its agent: the one file to write (`.youi/proposals/<proposal>.json`), the props an
+ * option may set (enum values from `values`), and whether it may give the component new text. */
+export const youiyouxOfferSchema = z.object({
+    proposal: z.string().regex(PROPOSAL_ID),
+    file: text(500),
+    choices: z.record(z.string().regex(PROP), z.object({
+        type: z.enum(["enum", "string", "boolean", "number"]),
+        values: z.array(text(200)).max(100).optional(),
+        default: value.optional(),
+    })).refine(choices => Object.keys(choices).length <= 50, "at most 50 props"),
+    text: z.boolean(),
+});
+export const youiyouxTaskSchema = z.object({
+    title: text(120),
+    goal: text(4000),
+    touches: z.array(text(500)).max(50),
+    touchesKnown: z.boolean(),
+    why: text(500).optional(),
+    not: z.array(text(300)).max(10),
+    acceptance: z.array(z.object({ statement: text(300), evidence: z.array(z.enum(YOUIYOUX_EVIDENCE)).min(1) })).min(1).max(10),
+    /** An options request's: what its agent writes (optionsProblem holds it to the request). */
+    offer: youiyouxOfferSchema.optional(),
+});
+export const youiyouxRequestSchema = z.object({
+    schema: z.literal("youi.request/v1"),
+    id: z.string().regex(REQUEST_ID),
+    project: text(200),
+    kind: z.enum(["comment", "change", "options"]),
+    status: z.enum(["open", "addressed", "closed"]),
+    body: text(4000),
+    author: who,
+    createdAt: when,
+    updatedAt: when,
+    // Where the person pointed: the page, the component, and (when youiyoux knew it) the file and line that draw it.
+    target: z.object({ route: text(300), scope: z.enum(["here", "element"]), name: text(200), file: text(500).optional(), line: z.int().positive().max(Number.MAX_SAFE_INTEGER).optional() }),
+    task: youiyouxTaskSchema.optional(),
+    thread: z.array(z.unknown()).max(500),
+});
+export function readYouiyouxRequest(raw) {
+    return parseContract(youiyouxRequestSchema, raw);
+}
+/** The one file an options request's agent may write: `.youi/proposals/p-<the request's hex>.json`. */
+export const proposalIdOf = (request) => `p-${request.slice(2)}`;
+export const proposalFileOf = (proposal) => `.youi/proposals/${proposal}.json`;
+/** Why an options request can't be filed as youiyoux's contract has it, or null: it carries a task with an offer whose
+ * proposal is `p-<its own hex>`, whose file is that proposal's, and the task may touch that one file and nothing else. */
+export function optionsProblem(request) {
+    if (request.kind !== "options")
+        return null;
+    const offer = request.task?.offer;
+    if (request.task === undefined || offer === undefined)
+        return "it asks for options with no offer";
+    const proposal = proposalIdOf(request.id);
+    if (offer.proposal !== proposal)
+        return `its offer is for ${offer.proposal}, not ${proposal}`;
+    if (offer.file !== proposalFileOf(proposal))
+        return `its offer's file isn't ${proposalFileOf(proposal)}`;
+    if (!request.task.touchesKnown || request.task.touches.length !== 1 || request.task.touches[0] !== offer.file)
+        return "its task may touch more than its options file";
+    return null;
+}
+/** `youi.proposal/v1`: the options an agent puts on youiyoux's Screens canvas (youiyoux's packages/core/src/proposals.ts,
+ * mirrored). Toolroll checks only the shape and what it reads; youiyoux checks each option against the component's
+ * contract when it reads the file. */
+const OPTION_IDS = ["a", "b", "c", "d"];
+export const PROPOSAL_STATUSES = ["open", "chosen", "dismissed"];
+export const youiyouxProposalSchema = z.object({
+    $schema: z.string().max(500).optional(),
+    schema: z.literal("youi.proposal/v1"),
+    id: z.string().regex(PROPOSAL_ID),
+    project: text(200),
+    route: text(300),
+    target: z.object({
+        name: text(200), element: text(200).optional(), file: text(500).optional(),
+        line: z.int().positive().max(Number.MAX_SAFE_INTEGER).optional(), column: z.int().nonnegative().max(Number.MAX_SAFE_INTEGER).optional(),
+        box: z.object({ x: z.number().finite(), y: z.number().finite(), width: z.number().finite().nonnegative(), height: z.number().finite().nonnegative() }),
+        page: z.object({ width: z.number().finite().positive(), height: z.number().finite().positive() }).optional(),
+    }),
+    ask: text(1000),
+    author: who,
+    createdAt: when,
+    updatedAt: when,
+    options: z.array(z.object({
+        id: z.enum(OPTION_IDS),
+        label: text(60),
+        why: text(500),
+        set: z.array(z.object({ prop: z.string().regex(PROP), value })).max(20),
+        text: text(2000).nullable(),
+    }).refine(option => option.set.length > 0 || option.text !== null, "an option changes a prop or the text")).min(2).max(4),
+    status: z.enum(PROPOSAL_STATUSES),
+    choice: z.enum(OPTION_IDS).optional(),
+    decidedBy: who.optional(),
+    decidedAt: when.optional(),
+    request: z.string().regex(REQUEST_ID).optional(),
+    for: z.string().regex(REQUEST_ID),
+}).refine(doc => new Set(doc.options.map(option => option.id)).size === doc.options.length, "each option has its own letter")
+    .refine(doc => doc.choice === undefined || doc.options.some(option => option.id === doc.choice), "the choice is one of its options");
+export function readYouiyouxProposal(raw) {
+    return parseContract(youiyouxProposalSchema, raw);
+}
+/** What Toolroll writes beside a request (`youi.request-task/v1`): the task it became, how that task stands, and, when
+ * the console has an address, the task's link and `home`, where a person sees and approves all waiting work. */
+export const YOUIYOUX_TASK_STATUSES = ["queued", "needs-you", "building", "ready", "done", "failed", "stopped"];
+/** A link youiyoux opens: http or https, at most 2,000 characters, with no user name or password in it. */
+export const youiyouxLinkSchema = z.string().max(2000).refine(value => {
+    try {
+        const url = new URL(value);
+        return (url.protocol === "http:" || url.protocol === "https:") && url.username === "" && url.password === "";
+    }
+    catch {
+        return false;
+    }
+}, "an http or https address with no credentials");
+export const youiyouxRequestTaskSchema = z.strictObject({
+    schema: z.literal("youi.request-task/v1"),
+    request: z.string().regex(REQUEST_ID),
+    runner: z.literal("Toolroll"),
+    task: z.strictObject({ id: z.string().min(1).max(120), url: youiyouxLinkSchema.nullable() }),
+    home: youiyouxLinkSchema.optional(),
+    status: z.enum(YOUIYOUX_TASK_STATUSES),
+    detail: z.string().max(200),
+    updatedAt: when,
+});
+export function readYouiyouxRequestTask(raw) {
+    return parseContract(youiyouxRequestTaskSchema, raw);
+}

package/dist/control-setup.d.ts

@@ -13,6 +13,7 @@ export declare function previewSetup(store: Store, repo: string, inputs: SetupIn
     seconds?: never;
     provider?: never;
     model?: never;
+    models?: never;
 } | {
     message?: never;
     ok: true;
@@ -21,6 +22,13 @@ export declare function previewSetup(store: Store, repo: string, inputs: SetupIn
     seconds: number;
     provider: "claude" | "cline" | "codex" | "cursor" | "gemini" | "goose" | "opencode" | "openrouter" | "qwen";
     model: string;
+    models: {
+        rows: (import("./model-choices.js").DiffRow & {
+            inherited: import("./model-choices.js").Pair | null;
+        })[];
+        state: string;
+        change: string;
+    } | null;
 };
 export declare function approveSetup(store: Store, repo: string, inputs: SetupInputs, fingerprint: string, by: string, token: string, now: Date): {
     ok: false;
@@ -30,6 +38,7 @@ export declare function approveSetup(store: Store, repo: string, inputs: SetupIn
     seconds?: never;
     provider?: never;
     model?: never;
+    models?: never;
 } | {
     ok: true;
 };

package/dist/control-setup.js

@@ -2,6 +2,8 @@ import { createHash } from "node:crypto";
 import { hasDisguisedText } from "./decision.js";
 import { authenticateApprover } from "./scope.js";
 import { isProviderId, validateSpec } from "./provider.js";
+import { INSTALLATION_SCOPE } from "./agentconfig.js";
+import { ALL_SLOTS, applyModelChoices, DEFAULT_PRESET, presetChange, previewModelChange, rowAt } from "./model-choices.js";
 export function previewSetup(store, repo, inputs) {
     if (!isProviderId(inputs.provider))
         return { ok: false, message: "Choose an installed provider." };
@@ -18,19 +20,36 @@ export function previewSetup(store, repo, inputs) {
     const seconds = Number(inputs.seconds);
     if (!/^[1-9][0-9]*$/.test(inputs.seconds) || !Number.isInteger(seconds) || seconds < 1 || seconds > 3600)
         return { ok: false, message: "Setup timeout must be 1–3600 seconds." };
-    const fingerprint = createHash("sha256").update(JSON.stringify({ repo, inputs, beforeSetup: store.liveWorktreeSetup(repo), beforeConfig: store.phaseConfig(repo, "build") })).digest("hex");
-    return { ok: true, fingerprint, command, seconds, provider: inputs.provider, model: inputs.model.trim() };
+    const models = installationModels(store);
+    const fingerprint = createHash("sha256").update(JSON.stringify({ repo, inputs, beforeSetup: store.liveWorktreeSetup(repo), beforeConfig: store.phaseConfig(repo, "build"),
+        ...(models === null ? {} : { models: [models.state, models.change] }) })).digest("hex");
+    return { ok: true, fingerprint, command, seconds, provider: inputs.provider, model: inputs.model.trim(), models };
 }
 export function approveSetup(store, repo, inputs, fingerprint, by, token, now) {
     return store.transact(() => {
-        if (!authenticateApprover(store, by, token, repo).ok)
+        const proved = authenticateApprover(store, by, token, repo);
+        if (!proved.ok)
             return { ok: false, message: "Your operator credential is required." };
         const preview = previewSetup(store, repo, inputs);
         if (!preview.ok)
             return preview;
         if (preview.fingerprint !== fingerprint)
             return { ok: false, message: "Setup changed. Review it again." };
-        store.setPhaseConfig(repo, "build", preview.provider, preview.model, by, now);
+        if (preview.models !== null) {
+            // The installation's models, through Settings → Models' one write path (an instance operator's act). The proof
+            // above ran in this same transaction, so the generation read here is the one it was checked against.
+            if (!store.isInstanceOperator(by))
+                return { ok: false, message: "Models for this installation aren't chosen yet. An instance operator sets them up first." };
+            const applied = applyModelChoices(store, { scope: INSTALLATION_SCOPE, change: presetChange(DEFAULT_PRESET), expected: { state: preview.models.state, change: preview.models.change }, strict: true, knownProject: () => false }, { actor: by, generation: store.accountOf(by)?.generation ?? -1, method: proved.method, live: () => true }, now);
+            if (!applied.ok)
+                return { ok: false, message: applied.problem };
+        }
+        // The project's own builder only when it differs from what it inherits: a project left on the installation's
+        // routine builder keeps following the installation's sizes and presets.
+        const inherited = store.phaseConfig(INSTALLATION_SCOPE, "build");
+        const same = inherited !== null && inherited.provider === preview.provider && inherited.model === preview.model;
+        if (!same || store.phaseConfig(repo, "build") !== null)
+            store.setPhaseConfig(repo, "build", preview.provider, preview.model, by, now);
         if (preview.command === "")
             store.clearWorktreeSetup(repo, by, now);
         else
@@ -38,3 +57,11 @@ export function approveSetup(store, repo, inputs, fingerprint, by, token, now) {
         return { ok: true };
     });
 }
+// Last in the file, so the password tripwire's function positions (password-freshness.test.ts) stay as reviewed.
+/** A new installation, nothing chosen yet: setup applies the default preset ("Sized by job") with the project's
+ * builder, previewed here row by row, so the first task files on exact models for every size. */
+function installationModels(store) {
+    if (!ALL_SLOTS.every(slot => rowAt(store, INSTALLATION_SCOPE, slot) === null))
+        return null;
+    return previewModelChange(store, INSTALLATION_SCOPE, presetChange(DEFAULT_PRESET));
+}

package/dist/control-ui.d.ts

@@ -28,4 +28,10 @@ export declare function controlSetupHtml(data: {
     };
 }): Html;
 /** `fields` may still carry the session's csrf (a caller's habit): postForm writes the one CSRF field. */
-export declare function setupPreviewHtml(inputs: SetupInputs, fields: Record<string, string>): Html;
+export declare function setupPreviewHtml(inputs: SetupInputs, fields: Record<string, string>, models?: {
+    label: string;
+    rows: {
+        role: string;
+        model: string;
+    }[];
+} | null): Html;

package/dist/control-ui.js

@@ -27,7 +27,8 @@ export function controlSetupHtml(data) {
         html `<p>Give the agent the project's Toolroll handoff instructions.</p>${postForm("/control/instructions-preview", html `<button>Review instructions</button>`, { hidden: { repo: data.repo } })}`}</section><p><a href="/fleet">Configure planning, repair, and review agents</a> · <a href="/tasks/new">Describe a task</a></p>`;
 }
 /** `fields` may still carry the session's csrf (a caller's habit): postForm writes the one CSRF field. */
-export function setupPreviewHtml(inputs, fields) {
+export function setupPreviewHtml(inputs, fields, models = null) {
     const { csrf: _csrf, ...rest } = fields;
-    return html `<h1>Approve project setup</h1><div class="card"><p>${fields.repo ?? ""}</p><p><strong>Builder:</strong> ${inputs.provider} · ${inputs.model}</p><p><strong>Preparation:</strong></p><pre class="recap">${inputs.command || "No preparation command"}</pre><p>Preparation timeout: ${inputs.seconds} seconds.</p><p>The builder default applies to new tasks. Preparation applies to subsequent runs, including already approved tasks. Existing signed task settings and verification rules remain in force.</p>${postForm("/control/setup-approve", html `${reauth(html `<label>Your password<input type="password" name="token" autocomplete="current-password" required></label>`)}<button>Approve project setup</button>`, { hidden: { ...rest, ...inputs } })}</div>`;
+    const chosen = models === null ? "" : html `<p><strong>Models for every project:</strong> ${models.label}</p><ul>${models.rows.map(row => html `<li>${row.role}: <span class="mono">${row.model}</span></li>`)}</ul><p class="meta">Change them later in Settings → Models.</p>`;
+    return html `<h1>Approve project setup</h1><div class="card"><p>${fields.repo ?? ""}</p><p><strong>Builder:</strong> ${inputs.provider} · ${inputs.model}</p>${chosen}<p><strong>Preparation:</strong></p><pre class="recap">${inputs.command || "No preparation command"}</pre><p>Preparation timeout: ${inputs.seconds} seconds.</p><p>The builder default applies to new tasks. Preparation applies to subsequent runs, including already approved tasks. Existing signed task settings and verification rules remain in force.</p>${postForm("/control/setup-approve", html `${reauth(html `<label>Your password<input type="password" name="token" autocomplete="current-password" required></label>`)}<button>Approve project setup</button>`, { hidden: { ...rest, ...inputs } })}</div>`;
 }

package/dist/desktop-update.d.ts

@@ -97,7 +97,6 @@ export declare function sqliteLock(file: string, busyTimeoutMs?: number): Databa
 export declare function lockHeld(file: string): boolean;
 export declare const installationLock: (j: UpdateJournal) => DatabaseSync | null;
 export declare function desktopUpdateStatus(stateDir: string): {
-    version?: never;
     active: boolean;
     phase: string;
     detail: string;
@@ -111,6 +110,7 @@ export declare function desktopUpdateStatus(stateDir: string): {
     wasRunning?: never;
     backupPath?: never;
     updateId?: never;
+    version?: never;
     buildId?: never;
     workDir?: never;
 } | {

package/dist/dispatch.d.ts

@@ -6,6 +6,7 @@
  * fleet observations on top for people and agents reading the queue. A
  * diagnosis can go stale; it can never grant a lease.
  */
+import { type Runner } from "./runner.js";
 import { type ChatSnapshot, type ReviewRequestOrigin, type ReviewRetryState, type Store, type TaskState } from "./store.js";
 export declare const DEFAULT_MAX_OPEN_DECISIONS = 5;
 export type TaskReadinessBlocker = {
@@ -95,6 +96,20 @@ export declare function dispatchRoleFor(store: Store, taskRef: number, now: Date
 /** The first requirement this task fails, in words, or null. */
 export declare function missingCapability(store: Store, taskRef: number, dispatchRepo: string | null, now: Date): string | null;
 /** The read-side lifecycle answer. Project access limits dependency detail, never the readiness gate. */
+/** The builders that may take work in `repo`, as dispatch decides: registered and not retired (`all`), bound to the
+ * project (`eligible`; only the assigned one when a task names one), and checking in now (`alive`). The first-run
+ * "Builder connected" step reads the same answer, so it is done only when a task there could start. */
+export declare function buildersFor(store: Store, repo: string, now: Date, assignedRunner?: string | null): {
+    all: Runner[];
+    eligible: Runner[];
+    alive: Runner[];
+};
+/** Whether a task in `repo` could start for want of nothing but a person: a live builder bound to it. */
+export declare function builderReadyFor(store: Store, repo: string | null, now: Date): boolean;
+/** The project the first-run "Builder connected" step speaks for, on Chat and the board alike: the open one; else the
+ * saved project of the first filed task the viewer may see (All projects); else, only before any task exists, the
+ * first managed project. Null when tasks exist but none sits in a project the viewer may see: then nothing says done. */
+export declare function firstRunBuilderRepo(store: Store, selected: string | null, visible: (repo: string | null) => boolean, managed: readonly string[]): string | null;
 export declare function diagnoseTaskDispatch(store: Store, taskId: string, now: Date, readableRepos?: readonly string[] | null): DispatchDiagnosis | null;
 export declare function diagnosisIsDispatchable(diagnosis: DispatchDiagnosis | null): boolean;
 /** Attach the same lifecycle answer to the bounded fleet snapshot used by

package/dist/dispatch.js

@@ -160,6 +160,31 @@ function approvedProfile(scope) {
     return scope.approvedProfile ?? scope.profile ?? null;
 }
 /** The read-side lifecycle answer. Project access limits dependency detail, never the readiness gate. */
+/** The builders that may take work in `repo`, as dispatch decides: registered and not retired (`all`), bound to the
+ * project (`eligible`; only the assigned one when a task names one), and checking in now (`alive`). The first-run
+ * "Builder connected" step reads the same answer, so it is done only when a task there could start. */
+export function buildersFor(store, repo, now, assignedRunner = null) {
+    const all = store.listRunners().filter(one => one.retiredAt === null);
+    const bound = all.filter(one => one.repos.includes(repo));
+    const eligible = assignedRunner === null ? bound : bound.filter(one => one.name === assignedRunner);
+    return { all, eligible, alive: eligible.filter(one => isAlive(one, now)) };
+}
+/** Whether a task in `repo` could start for want of nothing but a person: a live builder bound to it. */
+export function builderReadyFor(store, repo, now) {
+    return repo !== null && buildersFor(store, repo, now).alive.length > 0;
+}
+/** The project the first-run "Builder connected" step speaks for, on Chat and the board alike: the open one; else the
+ * saved project of the first filed task the viewer may see (All projects); else, only before any task exists, the
+ * first managed project. Null when tasks exist but none sits in a project the viewer may see: then nothing says done. */
+export function firstRunBuilderRepo(store, selected, visible, managed) {
+    if (selected !== null)
+        return selected;
+    const placed = store.handle.prepare("SELECT repo FROM task_ref WHERE repo IS NOT NULL ORDER BY id").all();
+    const first = placed.find(row => visible(row.repo));
+    if (first !== undefined)
+        return first.repo;
+    return store.hasAnyWork() ? null : managed[0] ?? null;
+}
 export function diagnoseTaskDispatch(store, taskId, now, readableRepos = null) {
     const task = store.getTask(taskId);
     const ref = store.lookupRef(taskId);
@@ -271,9 +296,7 @@ export function diagnoseTaskDispatch(store, taskId, now, readableRepos = null) {
     const gap = missingCapability(store, ref.id, ref.repo, now);
     if (gap !== null)
         return answer("missing-requirement", "waiting", "Missing a requirement", gap, { action: "repair-capability", role });
-    const all = store.listRunners().filter(one => one.retiredAt === null);
-    const bound = all.filter(one => one.repos.includes(ref.repo));
-    const eligible = ref.assignedRunner === null ? bound : bound.filter(one => one.name === ref.assignedRunner);
+    const { all, eligible, alive } = buildersFor(store, ref.repo, now, ref.assignedRunner);
     if (eligible.length === 0) {
         const detail = ref.assignedRunner === null
             ? all.length === 0
@@ -282,7 +305,6 @@ export function diagnoseTaskDispatch(store, taskId, now, readableRepos = null) {
             : `This task is assigned to ${ref.assignedRunner}, but that builder is not connected to this project.`;
         return answer("no-worker-registered", "waiting", "Builder not connected", detail, { action: "start-worker", role });
     }
-    const alive = eligible.filter(one => isAlive(one, now));
     if (alive.length === 0) {
         return answer("no-worker-online", "waiting", "Builder disconnected", `${eligible.length === 1 ? "The builder for this project has" : "All builders for this project have"} stopped checking in. This task starts automatically when ${eligible.length === 1 ? "it reconnects" : "one reconnects"}.`, { action: "start-worker", role });
     }

package/dist/first-run.d.ts

@@ -25,7 +25,7 @@ export type FirstRunAction = {
 };
 /** `checking`: the answer is not in yet, so the step is shown neither done nor to do. */
 export type FirstRunStep = {
-    key: "agent" | "project" | "task";
+    key: "agent" | "project" | "builder" | "task";
     title: string;
     done: boolean;
     action: FirstRunAction | null;
@@ -39,8 +39,11 @@ export type FirstRunFacts = {
     firstResultAt: string | null;
     signInCommand?: string;
 };
-/** The three steps, each done or with the one action that does it; null once the first result has arrived. */
+/** The steps (the builder step is added by withBuilderStep), each done or with the one action that does it; null once the first result has arrived. */
 export declare function firstRunSteps(facts: FirstRunFacts): FirstRunStep[] | null;
+/** The builder step, before the first task: under `toolroll serve` nothing connects a builder, and a task filed then
+ * waits forever, so the steps never all read done without one. It leads to Start a builder, which shows the command. */
+export declare function withBuilderStep(steps: FirstRunStep[] | null, connected: boolean): FirstRunStep[] | null;
 export type OpenIssue = {
     number: number;
     title: string;

package/dist/first-run.js

@@ -1,5 +1,5 @@
 /**
- * The first run: three plain steps to a first result, and three first tasks
+ * The first run: four plain steps to a first result, and three first tasks
  * to try. Everything here is derived from live facts on each render; the
  * list retires permanently with the first Ready result (the
  * 'first-success-at' installation fact). A suggestion only drafts words in
@@ -8,6 +8,7 @@
 import { run } from "./exec.js";
 import { hardenedGit } from "./teardown-git.js";
 import { githubIssues } from "./issues.js";
+import { START_BUILDER_HREF } from "./needs-you.js";
 export const SIGN_IN_COMMAND = "claude auth login";
 export const SANDBOX_COMMAND = "npx toolroll demo";
 /** How a person starts on a real project (the demo hands off to this). */
@@ -27,7 +28,7 @@ export function signInCommandFor(states, platform) {
         return "codex login";
     return `npm install -g @anthropic-ai/claude-code${platform === "win32" ? ";" : " &&"} ${SIGN_IN_COMMAND}`;
 }
-/** The three steps, each done or with the one action that does it; null once the first result has arrived. */
+/** The steps (the builder step is added by withBuilderStep), each done or with the one action that does it; null once the first result has arrived. */
 export function firstRunSteps(facts) {
     if (facts.firstResultAt !== null)
         return null;
@@ -39,6 +40,16 @@ export function firstRunSteps(facts) {
         { key: "task", title: "Your first task", done: facts.hasTask, action: facts.hasTask ? null : { kind: "link", label: "New task", href: "/tasks/new" } },
     ];
 }
+/** The builder step, before the first task: under `toolroll serve` nothing connects a builder, and a task filed then
+ * waits forever, so the steps never all read done without one. It leads to Start a builder, which shows the command. */
+export function withBuilderStep(steps, connected) {
+    if (steps === null)
+        return null;
+    const builder = { key: "builder", title: "Builder connected", done: connected,
+        action: connected ? null : { kind: "link", label: "Start a builder", href: START_BUILDER_HREF } };
+    const task = steps.findIndex(one => one.key === "task");
+    return task < 0 ? [...steps, builder] : [...steps.slice(0, task), builder, ...steps.slice(task)];
+}
 export const GENERIC_FIRST_TASKS = [
     { source: "generic", label: "Add a test for an untested function", draft: "Find one function without a test and add a focused test for it." },
     { source: "generic", label: "Fix a lint warning", draft: "Fix one lint warning without changing behaviour." },

package/dist/flow-cadence.d.ts

@@ -13,26 +13,32 @@ import { type TriggerIo, type TriggerPass } from "./flow-triggers.js";
 import { type ReplyWatch, type ReplyWatchIo } from "./flow-replies.js";
 import { type StepIo, type StepPass } from "./flow-steps.js";
 import type { Store } from "./store.js";
+import { type Git } from "./landed-cleanup.js";
+import { type YouiyouxPass } from "./youiyoux-intake.js";
 /** How often the worker moves cards, checks triggers, reads replies and runs steps, builds or not. */
 export declare const FLOW_EVERY_MS = 15000;
 /** One pass of a kind for a project at a time in this process: a second one asked for while it runs is skipped
  * (`idle`), and the next cadence takes up whatever it would have done. Cards are also claimed in the database,
  * so passes in other processes can't act twice either. */
 export declare function alone<T>(kind: string, project: string, idle: T, run: () => Promise<T>): Promise<T>;
+/** `youiyouxGit`: the hardened git an options request's result is read with (the plane's own runner; gitOf by default). */
 export type FlowIo = {
     triggers: TriggerIo;
     replies: ReplyWatchIo;
     steps: StepIo;
     evidenceRoot?: string;
+    youiyouxGit?: Git;
 };
 export type FlowHousekeeping = {
     triggers: TriggerPass;
+    youiyoux: YouiyouxPass;
     replies: ReplyWatch;
     steps: StepPass;
     flows: FlowAdvance;
 };
-/** One project's flow pass: triggers (which may start cards), replies (which move waiting cards), steps, then moves.
- * `halted` (a stop or paused admission) skips everything that reaches outside; moves still run. */
+/** One project's flow pass: triggers (which may start cards), youiyoux requests (which file tasks that wait for a
+ * person, and move an options request's options to youiyoux's hub and a decision there back), replies (which move waiting cards), steps, then moves. `halted` (a stop or paused admission) skips
+ * everything that reaches outside; moves still run. */
 export declare function flowHousekeeping(store: Store, repo: string, clock: () => Date, io: FlowIo, halted: () => boolean): Promise<FlowHousekeeping>;
 /** Move one project's cards. Synchronous, so two can't overlap in a process; each move is checked against the
  * card's visit in its own transaction, so a pass in another process can't move a card twice. */

package/dist/flow-cadence.js

@@ -12,6 +12,8 @@ import { advanceFlows } from "./flow-engine.js";
 import { runFlowTriggers } from "./flow-triggers.js";
 import { watchFlowReplies } from "./flow-replies.js";
 import { runFlowSteps } from "./flow-steps.js";
+import { gitOf } from "./landed-cleanup.js";
+import { NO_YOUIYOUX_PASS, runYouiyoux } from "./youiyoux-intake.js";
 /** How often the worker moves cards, checks triggers, reads replies and runs steps, builds or not. */
 export const FLOW_EVERY_MS = 15_000;
 const running = new Set();
@@ -30,11 +32,22 @@ export async function alone(kind, project, idle, run) {
         running.delete(key);
     }
 }
-/** One project's flow pass: triggers (which may start cards), replies (which move waiting cards), steps, then moves.
- * `halted` (a stop or paused admission) skips everything that reaches outside; moves still run. */
+const NO_REQUESTS = NO_YOUIYOUX_PASS;
+/** One project's flow pass: triggers (which may start cards), youiyoux requests (which file tasks that wait for a
+ * person, and move an options request's options to youiyoux's hub and a decision there back), replies (which move waiting cards), steps, then moves. `halted` (a stop or paused admission) skips
+ * everything that reaches outside; moves still run. */
 export async function flowHousekeeping(store, repo, clock, io, halted) {
     const triggers = halted() ? { added: 0, checked: 0, problems: [] }
         : await alone("triggers", repo, { added: 0, checked: 0, problems: [] }, () => runFlowTriggers(store, repo, clock(), io.triggers));
+    const youiyoux = halted() ? NO_REQUESTS
+        : await alone("youiyoux", repo, NO_REQUESTS, async () => {
+            try {
+                return await runYouiyoux(store, repo, clock(), { dir: io.triggers.dir, env: process.env, git: io.youiyouxGit ?? gitOf(), evidenceRoot: io.evidenceRoot ?? null });
+            }
+            catch (error) {
+                return { ...NO_REQUESTS, problems: [`youiyoux: ${error instanceof Error ? error.message : "could not read requests"}`] };
+            }
+        });
     // One mailbox serves every project, so its reads are one at a time across them all.
     const replies = halted() ? { read: 0, taken: 0, problem: null }
         : await alone("replies", "*", { read: 0, taken: 0, problem: null }, () => watchFlowReplies(store, clock(), io.replies));
@@ -42,7 +55,7 @@ export async function flowHousekeeping(store, repo, clock, io, halted) {
         : await alone("steps", repo, { ran: 0, problems: [] }, () => runFlowSteps(store, repo, clock(), io.steps));
     // Last, so a step that just finished, or a card a trigger just added, moves now.
     const flows = moveCards(store, repo, clock(), io.evidenceRoot);
-    return { triggers, replies, steps, flows };
+    return { triggers, youiyoux, replies, steps, flows };
 }
 /** Move one project's cards. Synchronous, so two can't overlap in a process; each move is checked against the
  * card's visit in its own transaction, so a pass in another process can't move a card twice. */

package/dist/flow-card-task.d.ts

@@ -1,2 +1,11 @@
 import type { Store } from "./store.js";
+import { type TaskStatus } from "./task-status.js";
+/** A task's status as its page reads it, from the store alone (no evidence files); null when it can't be read. */
+/** `root`: where results' saved evidence is. Without it the receipt is read without its saved checks, so a completion
+ * (bound to the receipt read with them) doesn't read as one: a status that must say Complete passes it. */
+export declare function storedTaskStatus(store: Store, taskId: string, repo: string, now: Date, root?: string): {
+    status: TaskStatus;
+    activeTaskId: string;
+    live: ReturnType<Store["getRun"]>;
+} | null;
 export declare function flowCardTaskLine(store: Store, taskId: string, repo: string, now: Date, secrets?: readonly string[]): string;

package/dist/flow-card-task.js

@@ -19,14 +19,17 @@ function cardReason(text, fallback, secrets) {
         return fallback;
     return clean.length > 100 ? `${clean.slice(0, 99).trimEnd()}…` : clean;
 }
-export function flowCardTaskLine(store, taskId, repo, now, secrets = []) {
+/** A task's status as its page reads it, from the store alone (no evidence files); null when it can't be read. */
+/** `root`: where results' saved evidence is. Without it the receipt is read without its saved checks, so a completion
+ * (bound to the receipt read with them) doesn't read as one: a status that must say Complete passes it. */
+export function storedTaskStatus(store, taskId, repo, now, root) {
     const access = { principal: "operator", repos: [repo], dependencyRepos: [repo] };
-    const assignment = assignmentOf(store, taskId, now, access);
+    const assignment = assignmentOf(store, taskId, now, access, root);
     if (assignment === null)
-        return "Task unavailable";
+        return null;
     const work = taskWorkSummaryOf(store, assignment.activeTaskId, now, access);
     if (work === null)
-        return "Task unavailable";
+        return null;
     const live = work.liveRunId === null ? null : store.getRun(work.liveRunId);
     const facts = assignmentStatusFacts(assignment, { work: work.status, planning: live?.role === "planner" });
     // The canvas reads no evidence files. Keep the machine's recorded check visible
@@ -35,7 +38,13 @@ export function flowCardTaskLine(store, taskId, repo, now, secrets = []) {
     // With neither, nothing about the check was read here: the line says nothing about it, never a pass and never an ask.
     if (facts.checks?.status === "unavailable")
         facts.checks = check === null ? null : { ...facts.checks, status: check.status, exitCode: check.exitCode };
-    const status = taskStatusOf(facts);
+    return { status: taskStatusOf(facts), activeTaskId: assignment.activeTaskId, live };
+}
+export function flowCardTaskLine(store, taskId, repo, now, secrets = []) {
+    const read = storedTaskStatus(store, taskId, repo, now);
+    if (read === null)
+        return "Task unavailable";
+    const { status, live } = read;
     if (status.headline === "Needs you") {
         const fallback = status.need?.action.label ?? "Open the task";
         // The question itself is useful; routine approvals are clearer as the short action.
@@ -44,7 +53,7 @@ export function flowCardTaskLine(store, taskId, repo, now, secrets = []) {
         return `Waiting on you: ${what}`;
     }
     if (status.headline === "Building" && live !== null) {
-        const ref = store.lookupRef(assignment.activeTaskId);
+        const ref = store.lookupRef(read.activeTaskId);
         const checkpoint = store.latestCheckpointForRun(live.id);
         const progress = buildProgressOf(checkpoint?.taskRef !== ref?.id ? null : checkpoint?.snapshot.milestones.map(one => ({ description: null, state: one.state, note: one.note })));
         if (progress?.stuck != null)

package/dist/folder-look.d.ts

@@ -51,9 +51,12 @@ export type FolderLookRun = {
 };
 /** Starts one look. Production starts a child process; tests pass their own. */
 export type FolderLookRunner = (request: FolderLookRequest, deadlineMs: number) => FolderLookRun;
+/** `started`: when the process that answered was started, in this console's order of starts. A caller that joined a
+ * look already under way gets that look's start, never its own, so an older answer always reads as older. */
 export type FolderLook<T> = {
     ok: true;
     value: T;
+    started?: number;
 } | {
     ok: false;
     why: "no-answer" | "failed";

package/dist/folder-look.js

@@ -189,6 +189,8 @@ export const childLook = (request, deadlineMs) => {
 /** Looks whose process hasn't ended, by request: callers asking the same thing share one; each holds a child slot
  * until its process is gone. */
 const inFlight = new Map();
+/** Looks started so far: each look's place in that order is fixed when its process starts. */
+let starts = 0;
 /** The same request however its paths were spelled: resolved paths, roots in order. */
 function lookKey(request) {
     const sorted = (paths) => paths.map(one => resolve(one)).sort();
@@ -215,13 +217,15 @@ export async function lookFolders(request, options = {}) {
     if (run === undefined) {
         if (inFlight.size >= FOLDER_LOOK_CHILDREN)
             return { ok: false, why: "no-answer" };
+        let started;
         try {
-            run = (options.runner ?? childLook)(request, deadlineMs);
+            started = (options.runner ?? childLook)(request, deadlineMs);
         }
         catch {
             return { ok: false, why: "failed" };
         }
-        const mine = run;
+        const mine = { ...started, started: ++starts };
+        run = mine;
         inFlight.set(key, mine);
         const forget = () => { if (inFlight.get(key) === mine)
             inFlight.delete(key); };
@@ -238,7 +242,7 @@ export async function lookFolders(request, options = {}) {
         const answer = first.value;
         if (answer === null || typeof answer !== "object" || answer.ok !== true)
             return { ok: false, why: "failed" };
-        return { ok: true, value: answer.value };
+        return { ok: true, value: answer.value, started: run.started };
     }
     finally {
         clearTimeout(timer);
@@ -287,7 +291,7 @@ export async function lookIdentities(paths, options = {}) {
         if (row !== null && typeof row === "object" && text(row.path) && (row.real === null || text(row.real)))
             out.set(row.path, row.real);
     }
-    return { ok: true, value: out };
+    return { ok: true, value: out, ...(looked.started === undefined ? {} : { started: looked.started }) };
 }
 /** A project's own `.mcp.json` (parsed object, or null when absent or not one), read off the thread. */
 export async function lookProjectMcp(repo, options = {}) {