toolroll 0.9.25 → 0.9.27

package/dist/integrations-ui.js

@@ -6,12 +6,13 @@
  */
 import { STATE_WORDS } from "./integrations.js";
 import { whenUtc } from "./when-html.js";
+import { brandMarkHtml } from "./brand-mark.js";
 const e = (value) => String(value ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
 const when = (at) => whenUtc(at);
 export const INTEGRATIONS_CSS = `.integrations{max-width:760px;min-width:0}.integrations h2{margin:24px 0 6px;font-size:.9375rem}` +
     `.integrations .integration{display:grid;grid-template-columns:minmax(0,1fr) auto;gap:4px 16px;align-items:start;padding:12px 0;border-top:1px solid var(--so-line);min-width:0}` +
     `.integrations .integration>:not(.integration-action),.integrations .integration-body>*{grid-column:1}.integrations .integration-body{display:contents}.integrations .integration:first-of-type{border-top:0}.integrations .integration-head{margin:0;display:flex;flex-wrap:wrap;gap:6px 10px;align-items:center;min-width:0}` +
-    `.integrations .integration-head strong{overflow-wrap:anywhere}.integrations .integration p{margin:2px 0 0;min-width:0;overflow-wrap:anywhere}` +
+    `.integrations .integration .integration-body>*{margin-left:calc(var(--brand-mark) + 10px)}.integrations .integration-head strong{overflow-wrap:anywhere}.integrations .integration p{margin:2px 0 0;min-width:0;overflow-wrap:anywhere}` +
     `.integrations .integration-action{grid-column:2;grid-row:1 / span 3;align-self:center;margin:0}.integrations .integration-action button,.integrations .integration-action .button-link{min-height:44px;white-space:nowrap}` +
     `.integrations .integration .integration-action button{width:auto}.integrations .integration .integration-action a.integration-quiet{background:var(--so-paper);color:var(--so-ink);border:1px solid var(--so-input-line)}` +
     `.integrations .integration-fix{color:var(--so-danger)}.integrations code{overflow-wrap:anywhere}.integrations details{margin-top:4px;font-size:.8125rem}.integrations summary{cursor:pointer;padding:4px 0}` +
@@ -21,7 +22,7 @@ export const INTEGRATIONS_CSS = `.integrations{max-width:760px;min-width:0}.inte
     `.integration-state--not-set-up,.integration-state--checking{color:var(--so-muted);background:var(--so-neutral-soft)}` +
     // A phone: the action sits at the right of the name line, and the facts under it run on as one line.
     `@media (max-width:760px){.integrations h2{margin:16px 0 0}.integrations .integration{gap:0 12px;padding:6px 0 8px}.integrations .integration-head{min-height:44px}` +
-    `.integrations .integration-action{grid-row:1;align-self:center}.integrations .integration-body{display:block;grid-column:1 / -1;line-height:1.35}` +
+    `.integrations .integration-action{grid-row:1;align-self:center}.integrations .integration-body{display:block;grid-column:1 / -1;line-height:1.35;padding-left:calc(var(--brand-mark) + 10px)}.integrations .integration .integration-body>*{margin-left:0}` +
     `.integrations .integration-body>p{margin:0}.integrations .integration-body>p.meta{display:inline}.integrations .integration-body>p.meta+p.meta::before{content:" · "}` +
     `.integrations .integration-body>:not(.meta){margin-top:4px}.integrations .integration-body>:not(.meta)+p.meta{display:block;margin-top:2px}.integrations details{margin-top:2px}}`;
 const GROUPS = [
@@ -39,6 +40,12 @@ function action(one, csrf) {
         return `<p class="integration-action"><a class="button-link${a.kind === "setup" ? " integration-quiet" : ""}" href="${e(a.href)}">${a.label}</a></p>`;
     return "";
 }
+/** Which mark a row shows: email is Gmail's only when the account is a Gmail address; a custom tool is a letter. */
+function markFor(one) {
+    if (one.custom)
+        return null;
+    return one.key === "email" && /@(gmail|googlemail)\.com$/i.test(one.account ?? "") ? "gmail" : one.key;
+}
 function row(one, csrf) {
     const badge = !one.checked && one.state === "connected"
         ? `<span class="integration-state integration-state--checking"><i aria-hidden="true"></i>Checking</span>`
@@ -53,7 +60,7 @@ function row(one, csrf) {
         ? `<p class="meta">Failed ${when(one.lastErrorAt ?? "")}</p>`
         : `<details><summary>Last error ${one.lastErrorAt === null ? "" : when(one.lastErrorAt)}</summary><p class="meta">${e(one.lastError)}</p></details>`;
     return `<div class="integration" data-integration="${e(one.key)}" data-state="${one.state}">` +
-        `<p class="integration-head"><strong>${e(one.name)}</strong> ${badge}</p>` +
+        `<p class="integration-head">${brandMarkHtml(markFor(one), one.name, one.state === "connected")}<strong>${e(one.name)}</strong> ${badge}</p>` +
         action(one, csrf) +
         `<div class="integration-body">${facts === "" ? "" : `<p class="meta">${facts}</p>`}${fix}${run}${history}${lastError}</div></div>`;
 }

package/dist/integrations.d.ts

@@ -36,6 +36,8 @@ export type Integration = {
     lastErrorAt: string | null;
     usedBy: string[];
     action: IntegrationAction;
+    /** A project's own MCP tool: it shows a letter, never a logo matched by name. */
+    custom?: true;
 };
 export declare const STATE_WORDS: Record<IntegrationState, string>;
 export type ProbeResult = {

package/dist/integrations.js

@@ -383,7 +383,7 @@ function targets(io) {
             const href = `/settings/tools?repo=${encodeURIComponent(repo)}#tool-${encodeURIComponent(tool.name)}`;
             const test = tool.lastTest;
             list.push({
-                key: `mcp:${repo}:${tool.name}`, group: "tools", name: tool.name, configured: true, account: basename(repo),
+                key: `mcp:${repo}:${tool.name}`, group: "tools", name: tool.name, configured: true, account: basename(repo), ...(tool.source === "custom" ? { custom: true } : {}),
                 setup: place(href), fix: place(href), usedBy: [`Tasks in ${basename(repo)}`],
                 activity: test === null ? NO_ACTIVITY : test.ok ? { okAt: test.at, error: null, errorAt: null, failing: false } : { okAt: null, error: test.problem, errorAt: test.at, failing: false },
                 probe: async (check) => {
@@ -432,7 +432,7 @@ function targets(io) {
 }
 // ---------------------------------------------------------------- the list
 function combine(target, row) {
-    const base = { key: target.key, group: target.group, name: target.name, usedBy: target.usedBy };
+    const base = { key: target.key, group: target.group, name: target.name, usedBy: target.usedBy, ...(target.custom ? { custom: true } : {}) };
     const checked = target.probe === null || row !== undefined;
     const lastSuccessAt = later(row?.okAt ?? null, target.activity.okAt);
     const checkError = row?.error ?? null, checkErrorAt = row?.errorAt ?? null;

package/dist/mate-tools.js

@@ -761,7 +761,7 @@ export const MATE_TOOLS = [
     },
     {
         name: "get_project_tools",
-        description: "Read a project's tools (the MCP servers its builds get, and only those), the services that connect by signing in, the common tools list and servers found on this computer. A service in connectBySigningIn (Stripe, Notion, Linear, Sentry, Jira…) connects in one click: the person signs in on the service's own page, so give them its connect link and never propose tool_add for it. Add/remove others with propose_action tool_add/tool_remove; secrets are set only on the Tools page.",
+        description: "Read a project's tools (the MCP servers its builds get, and only those), the services that connect by signing in, the common tools list and servers found on this computer. A service in connectBySigningIn (Stripe, Notion, Linear, Sentry, Jira…) connects in one click: the person signs in on the service's own page, so give them its connect link (for this repo; another project has its own) and never propose tool_add for it. When saying a service is connected, name the project it is connected to (its list_repos name). Add/remove others with propose_action tool_add/tool_remove; secrets are set only on the Tools page.",
         inputSchema: schema({ repo: REPO_ARG }, ["repo"]),
         handle: (ctx, args) => {
             const repo = repoPathOf(ctx.who, args["repo"]);

package/dist/mcp-connect.d.ts

@@ -12,7 +12,17 @@ export type OneClick = {
     about: string;
     reads?: readonly string[];
 };
-/** Services verified to connect this way (their servers speak streamable HTTP and register clients on the spot). */
+/**
+ * Services that connect this way: their servers speak streamable HTTP and
+ * advertise registering clients on the spot. Advertising isn't accepting:
+ * Figma's server advertises it, but its registration answers 403 to any app
+ * Figma hasn't approved, so Figma connects through its desktop app instead
+ * (LOCAL_APPS). A service is listed only when its registration accepts
+ * Toolroll; mcp-connect.test.ts replays each one's answer (no live calls).
+ *
+ * Signed in end to end, live: Mobbin. The rest register in replayed checks
+ * only, until someone signs in to each for real.
+ */
 export declare const ONE_CLICK: readonly OneClick[];
 /**
  * The list, with one service standing in on this computer when the person
@@ -22,12 +32,19 @@ export declare const ONE_CLICK: readonly OneClick[];
  */
 export declare function oneClickServices(environment?: NodeJS.ProcessEnv): typeof ONE_CLICK;
 export declare const oneClickOf: (id: string) => OneClick | null;
-/** Where each service stands in a project: connected by signing in, open to connect, or its name taken by a tool set up another way. */
+/** An app on this computer that Connect adds without a sign-in (LOCAL_APPS): its tool, name and one line of how. */
+export declare const localConnectOf: (id: string) => {
+    id: string;
+    label: string;
+    about: string;
+} | null;
+/** Where each service stands in a project: connected, open to connect, or its name taken by a tool set up another way. `local` connects with no sign-in. */
 export declare function connectionsOf(store: Store, repo: string): {
     id: string;
     label: string;
     about: string;
     state: "connected" | "open" | "taken";
+    local?: true;
 }[];
 /**
  * Whether an action only reads: its name has a reading verb, and every other
@@ -39,7 +56,8 @@ export declare function readsOnly(action: string, subjects: readonly string[]):
  * What a research step may use of a project's connected services: each
  * signed-in service's read-only actions, as its last test listed them —
  * by server (`reads`, for Codex's `enabled_tools`) and named the way Claude
- * allows them (`mcp__<service>__<action>`). A service not connected, without
+ * allows them (`mcp__<service>__<action>`). `local` is the loopback host of
+ * each app on this computer it reads (its proxy lets only those through). A service not connected, without
  * read-only actions, or left out of this run (`launched`) gives nothing.
  */
 export type ResearchTools = {
@@ -49,6 +67,7 @@ export type ResearchTools = {
     }[];
     allowed: string[];
     reads: Record<string, string[]>;
+    local: string[];
 };
 export declare function researchToolsOf(tools: readonly ProjectTool[], launched?: ReadonlySet<string> | null): ResearchTools;
 /** Where a service sends the person back after they sign in. */

package/dist/mcp-connect.js

@@ -13,9 +13,20 @@
  */
 import { createHash, randomBytes } from "node:crypto";
 import { homedir } from "node:os";
-import { addToolTo, projectToolsOf, readToolSecrets, setToolSecrets, testToolOf } from "./project-tools.js";
+import { basename } from "node:path";
+import { LOCAL_APPS, addToolTo, catalogTool, localAppOf, projectToolsOf, readToolSecrets, setToolSecrets, testToolOf } from "./project-tools.js";
 import { envValue } from "./names.js";
-/** Services verified to connect this way (their servers speak streamable HTTP and register clients on the spot). */
+/**
+ * Services that connect this way: their servers speak streamable HTTP and
+ * advertise registering clients on the spot. Advertising isn't accepting:
+ * Figma's server advertises it, but its registration answers 403 to any app
+ * Figma hasn't approved, so Figma connects through its desktop app instead
+ * (LOCAL_APPS). A service is listed only when its registration accepts
+ * Toolroll; mcp-connect.test.ts replays each one's answer (no live calls).
+ *
+ * Signed in end to end, live: Mobbin. The rest register in replayed checks
+ * only, until someone signs in to each for real.
+ */
 export const ONE_CLICK = [
     { id: "stripe", label: "Stripe", url: "https://mcp.stripe.com/", about: "Payments, customers, refunds and invoices." },
     { id: "notion", label: "Notion", url: "https://mcp.notion.com/mcp", about: "Pages and databases: search, read and write." },
@@ -36,8 +47,6 @@ export const ONE_CLICK = [
     // Mobbin's sign-in is its Supabase auth server, on another origin: its protected-resource metadata names it.
     { id: "mobbin", label: "Mobbin", url: "https://api.mobbin.com/mcp", about: "Real app screens and flows to learn from.",
         reads: ["screen", "flow", "app", "site", "element", "pattern", "ui", "ios", "android", "web"] },
-    { id: "figma", label: "Figma", url: "https://mcp.figma.com/mcp", about: "Design files and frames.",
-        reads: ["file", "frame", "node", "image", "screenshot", "design", "context", "metadata", "variable", "defs", "component", "style", "code", "connect", "map", "figjam"] },
     { id: "posthog", label: "PostHog", url: "https://mcp.posthog.com/mcp", about: "Product analytics, funnels and events.",
         reads: ["insight", "run", "event", "definition", "property", "properties"] },
     { id: "betterstack", label: "Better Stack", url: "https://mcp.betterstack.com", about: "Uptime checks and incidents.",
@@ -65,13 +74,28 @@ export function oneClickServices(environment = process.env) {
     return ONE_CLICK.some(one => one.id === id) ? ONE_CLICK.map(one => one.id === id ? standIn : one) : [...ONE_CLICK, standIn];
 }
 export const oneClickOf = (id) => oneClickServices().find(one => one.id === id) ?? null;
-/** Where each service stands in a project: connected by signing in, open to connect, or its name taken by a tool set up another way. */
+/** What to use when a service won't let Toolroll sign in by itself. */
+const INSTEAD = { figma: "Connect Figma (desktop app) instead." };
+/** An app on this computer that Connect adds without a sign-in (LOCAL_APPS): its tool, name and one line of how. */
+export const localConnectOf = (id) => {
+    const app = LOCAL_APPS.find(one => one.tool === id), tool = catalogTool(id);
+    return app === undefined || tool === null ? null : { id, label: tool.label, about: app.connect };
+};
+/** Where each service stands in a project: connected, open to connect, or its name taken by a tool set up another way. `local` connects with no sign-in. */
 export function connectionsOf(store, repo) {
     const tools = projectToolsOf(store, repo);
-    return oneClickServices().map(service => {
+    const signIn = oneClickServices().map(service => {
         const had = tools.find(one => one.name === service.id);
         return { id: service.id, label: service.label, about: service.about, state: had === undefined ? "open" : had.spec.url === service.url && had.spec.bearer === ACCESS ? "connected" : "taken" };
     });
+    const local = LOCAL_APPS.flatMap(app => {
+        const one = localConnectOf(app.tool);
+        if (one === null)
+            return [];
+        const had = tools.find(tool => tool.name === one.id);
+        return [{ ...one, state: had === undefined ? "open" : localAppOf(had.spec) !== null ? "connected" : "taken", local: true }];
+    });
+    return [...signIn, ...local];
 }
 /** The verbs that only read. An action named by anything else is withheld from research. */
 const READING = new Set(["list", "get", "search", "find", "read", "query", "describe", "fetch", "view", "export-image"]);
@@ -91,10 +115,15 @@ export function readsOnly(action, subjects) {
     return words.some(word => READING.has(word)) && words.every(word => READING.has(word) || QUALIFIERS.has(word) || subject(word));
 }
 export function researchToolsOf(tools, launched = null) {
-    const research = { services: [], allowed: [], reads: {} };
-    for (const service of oneClickServices()) {
+    const research = { services: [], allowed: [], reads: {}, local: [] };
+    // Signed-in services, then apps on this computer (each exactly as listed: its own address, no key).
+    const readable = [
+        ...oneClickServices().map(service => ({ id: service.id, label: service.label, reads: service.reads, is: (spec) => spec.url === service.url && spec.bearer === ACCESS })),
+        ...LOCAL_APPS.map(app => ({ id: app.tool, label: catalogTool(app.tool)?.label ?? app.tool, reads: app.reads, is: (spec) => localAppOf(spec) === app })),
+    ];
+    for (const service of readable) {
         const tool = tools.find(one => one.name === service.id);
-        if (service.reads === undefined || tool === undefined || tool.spec.url !== service.url || tool.spec.bearer !== ACCESS || (launched !== null && !launched.has(tool.name)))
+        if (service.reads === undefined || tool === undefined || !service.is(tool.spec) || (launched !== null && !launched.has(tool.name)))
             continue;
         const reads = (tool.lastTest?.ok ? tool.lastTest.tools : []).filter(action => readsOnly(action, service.reads));
         if (reads.length === 0)
@@ -102,6 +131,8 @@ export function researchToolsOf(tools, launched = null) {
         research.services.push({ id: service.id, label: service.label });
         research.allowed.push(...reads.map(action => `mcp__${service.id}__${action}`));
         research.reads[service.id] = reads;
+        if (localAppOf(tool.spec) !== null)
+            research.local.push(new URL(tool.spec.url).host);
     }
     return research;
 }
@@ -181,6 +212,9 @@ export async function startConnect(input, fetcher = fetch, now = Date.now()) {
     try {
         const registered = await fetcher(server.register, { method: "POST", headers: { "content-type": "application/json", accept: "application/json" }, signal: AbortSignal.timeout(10_000),
             body: JSON.stringify({ client_name: "Toolroll", redirect_uris: [redirect], grant_types: ["authorization_code", "refresh_token"], response_types: ["code"], token_endpoint_auth_method: "none" }) });
+        // Figma's answer (Oct 2026): it registers only apps it has approved. Said before reading a body that may not be JSON.
+        if (registered.status === 401 || registered.status === 403)
+            return { ok: false, said: `${service.label} doesn't let other apps sign in this way yet.${INSTEAD[service.id] === undefined ? "" : ` ${INSTEAD[service.id]}`}` };
         const body = await registered.json();
         if (!registered.ok || typeof body.client_id !== "string")
             return { ok: false, said: `${service.label} didn't let Toolroll register (HTTP ${registered.status}).` };
@@ -251,11 +285,13 @@ export async function finishConnect(store, visit, code, now, options = {}) {
     }
     setToolSecrets(visit.repo, spec.name, { [ACCESS]: tokens.access, [CLIENT]: visit.clientId, [TOKEN_URL]: visit.token, [RESOURCE]: visit.resource,
         ...(tokens.refresh === null ? {} : { [REFRESH]: tokens.refresh }), ...(tokens.expires === null ? {} : { [EXPIRES]: tokens.expires }), ...(visit.clientSecret === null ? {} : { [CLIENT_SECRET]: visit.clientSecret }) }, home);
+    // The success line names the project it went to: the page and chat may be looking at another.
+    const to = basename(visit.repo);
     if (options.test === false)
-        return { ok: true, said: `${service.label} is connected.` };
+        return { ok: true, said: `${service.label} is connected to ${to}.` };
     const tested = await testToolOf(store, visit.repo, spec.name, now, { home, ...(options.omitEnv === undefined ? {} : { omitEnv: options.omitEnv }) });
-    return tested?.ok ? { ok: true, said: `${service.label} is connected: ${tested.tools.length} action${tested.tools.length === 1 ? "" : "s"}. Let a teammate use it from its page.` }
-        : { ok: true, said: `${service.label} is signed in, but its test didn't pass yet: ${tested?.problem ?? "no answer"}.` };
+    return tested?.ok ? { ok: true, said: `${service.label} is connected to ${to}: ${tested.tools.length} action${tested.tools.length === 1 ? "" : "s"}. Let a teammate use it from its page.` }
+        : { ok: true, said: `${service.label} is signed in for ${to}, but its test didn't pass yet: ${tested?.problem ?? "no answer"}.` };
 }
 /** Keep connected services signed in: any token expiring within ten minutes is refreshed (the worker's pass, and before a teammate's call). */
 export async function refreshConnections(store, repos, now, options = {}) {

package/dist/operate.d.ts

@@ -1,7 +1,7 @@
 import { type IntegrationIo } from "./integrations.js";
 import { type OnboardIo } from "./agent-onboard.js";
 import { type TriggerIo } from "./flow-triggers.js";
-import { type StepIo } from "./flow-steps.js";
+import type { StepIo } from "./flow-steps.js";
 import type { FetchLike } from "./flow-share.js";
 import { type Store } from "./store.js";
 import { type DispatchAdapter } from "./sync.js";
@@ -61,6 +61,8 @@ export type OperateOptions = {
     flowTriggerIo?: Partial<TriggerIo>;
     /** Injected by tests: how flow check and update steps run commands and reach GitHub and Linear. */
     flowStepIo?: Partial<StepIo>;
+    /** Injected by tests: how often a worker's flow passes run beside its builds (default FLOW_EVERY_MS). */
+    flowEveryMs?: number;
     /** Injected by tests: how `flows import` fetches a flow file's address. */
     flowFetch?: FetchLike;
     /** Injected by tests: how `integrations` checks reach services (fetch, gh, sign-in checks, mail servers). */

package/dist/operate.js

@@ -31,13 +31,11 @@ import { startCodexLimits } from "./codex-limits.js";
 import { packageVersion, startMonitoring, targetOf } from "./monitoring.js";
 import { origin, readMonitoring } from "./monitoring-settings.js";
 import { logEvent } from "./log.js";
-import { advanceFlows } from "./flow-engine.js";
-import { readHooksBase, runFlowTriggers } from "./flow-triggers.js";
-import { watchFlowReplies } from "./flow-replies.js";
+import { FLOW_EVERY_MS, flowHousekeeping, moveCards, moveCardsAfter } from "./flow-cadence.js";
+import { readHooksBase } from "./flow-triggers.js";
 import { sendTeammateSummaries } from "./teammate-admin.js";
 import { runRequestedUndos, sendTeammateWeeklies } from "./teammate-week.js";
 import { refreshConnections } from "./mcp-connect.js";
-import { runFlowSteps } from "./flow-steps.js";
 import { followDiscord } from "./discord.js";
 import { followTeams } from "./teams.js";
 import { loadDiscordCredentials } from "./discord-api.js";
@@ -835,6 +833,7 @@ export async function runOperate(command, argv, write, options = {}) {
             ...(options.dispatchAdapter === undefined ? {} : { dispatchAdapter: options.dispatchAdapter }),
             ...(options.flowTriggerIo === undefined ? {} : { flowTriggerIo: options.flowTriggerIo }),
             ...(options.flowStepIo === undefined ? {} : { flowStepIo: options.flowStepIo }),
+            ...(options.flowEveryMs === undefined ? {} : { flowEveryMs: options.flowEveryMs }),
             ...(options.flowFetch === undefined ? {} : { flowFetch: options.flowFetch }),
             ...(options.integrationIo === undefined ? {} : { integrationIo: options.integrationIo }),
             ...(options.shouldStop === undefined ? {} : { shouldStop: options.shouldStop }),
@@ -2007,6 +2006,24 @@ async function buildCommand(positional, flags, context) {
  * run opens and no attempt is spent, reported as its own skip reason. */
 class StaleAuthorization extends Error {
 }
+/** How a worker's flow pass reaches outside: the tests' seams, or the real commands, network and folders. */
+function flowIoOf(context, pool, git, base) {
+    const dir = dirname(context.databaseFile);
+    return {
+        triggers: { gh: context.flowTriggerIo?.gh ?? run, fetch: context.flowTriggerIo?.fetch ?? fetch, dir: context.flowTriggerIo?.dir ?? dir,
+            // A schedule's script (v90) runs like a code step: the same runner, in a clean folder beside the step copies.
+            shell: context.flowTriggerIo?.shell ?? context.flowStepIo?.shell ?? run, scratch: context.flowTriggerIo?.scratch ?? context.flowStepIo?.scratch ?? join(pool, "flow-checks"),
+            ...(context.flowTriggerIo?.mail === undefined ? {} : { mail: context.flowTriggerIo.mail }) },
+        // Replies to cards' emails (v91): read about once a minute, and only while a card is in an email conversation.
+        replies: { fetch: context.flowTriggerIo?.fetch ?? fetch, dir: context.flowTriggerIo?.dir ?? dir,
+            ...(context.flowTriggerIo?.mail === undefined ? {} : { mail: context.flowTriggerIo.mail }) },
+        // Check and update steps run outside a model: an approved command in a fresh copy of the card's work, or a comment on the issue it came from.
+        steps: { gh: context.flowStepIo?.gh ?? run, git: context.flowStepIo?.git ?? git, shell: context.flowStepIo?.shell ?? run, fetch: context.flowStepIo?.fetch ?? fetch,
+            dir: context.flowStepIo?.dir ?? dir, scratch: context.flowStepIo?.scratch ?? join(pool, "flow-checks"), base,
+            ...(context.evidenceRoot === undefined ? {} : { evidenceRoot: context.evidenceRoot }) },
+        ...(context.evidenceRoot === undefined ? {} : { evidenceRoot: context.evidenceRoot }),
+    };
+}
 /**
  * One scheduling pass: the M1 loop, without the human typing each step.
  *
@@ -2130,26 +2147,13 @@ async function tickCommand(flags, context) {
     // Triggers first: a schedule, GitHub, Linear or another flow may start
     // cards, which then move in the same pass. Checking an outside service is
     // `gh` or one HTTPS request, never a model, and only when it is due.
-    const triggerPass = buildsOnly || context.shouldStop?.() === true || context.shouldPauseAdmission?.() === true ? { added: 0, checked: 0, problems: [] }
-        : await runFlowTriggers(store, repo, clock(), { gh: context.flowTriggerIo?.gh ?? run, fetch: context.flowTriggerIo?.fetch ?? fetch, dir: context.flowTriggerIo?.dir ?? dirname(context.databaseFile),
-            // A schedule's script (v90) runs like a code step: the same runner, in a clean folder beside the step copies.
-            shell: context.flowTriggerIo?.shell ?? context.flowStepIo?.shell ?? run, scratch: context.flowTriggerIo?.scratch ?? context.flowStepIo?.scratch ?? join(pool, "flow-checks"),
-            ...(context.flowTriggerIo?.mail === undefined ? {} : { mail: context.flowTriggerIo.mail }) });
-    // Replies to cards' emails (v91): read about once a minute, and only while
-    // a card is in an email conversation. A reply moves a waiting card on here,
-    // before its next step runs.
-    const replyPass = buildsOnly || context.shouldStop?.() === true || context.shouldPauseAdmission?.() === true ? { read: 0, taken: 0, problem: null }
-        : await watchFlowReplies(store, clock(), { fetch: context.flowTriggerIo?.fetch ?? fetch, dir: context.flowTriggerIo?.dir ?? dirname(context.databaseFile),
-            ...(context.flowTriggerIo?.mail === undefined ? {} : { mail: context.flowTriggerIo.mail }) });
-    // Check and update steps run outside a model: an approved command in a
-    // fresh copy of the card's work, or a comment on the issue it came from.
-    const stepPass = buildsOnly || context.shouldStop?.() === true || context.shouldPauseAdmission?.() === true ? { ran: 0, problems: [] }
-        : await runFlowSteps(store, repo, clock(), {
-            gh: context.flowStepIo?.gh ?? run, git: context.flowStepIo?.git ?? git, shell: context.flowStepIo?.shell ?? run, fetch: context.flowStepIo?.fetch ?? fetch,
-            dir: context.flowStepIo?.dir ?? dirname(context.databaseFile), scratch: context.flowStepIo?.scratch ?? join(pool, "flow-checks"), base,
-            ...(context.evidenceRoot === undefined ? {} : { evidenceRoot: context.evidenceRoot }),
-        });
-    const flowPass = buildsOnly ? { moved: 0, filed: [], problems: [] } : advanceFlows(store, repo, clock(), context.evidenceRoot === undefined ? {} : { evidenceRoot: context.evidenceRoot });
+    // Each part is one at a time per project, so the worker's own flow cadence (runWatchLoop) and this pass never
+    // run the same part twice at once.
+    const housekeeping = buildsOnly ? null : await flowHousekeeping(store, repo, clock, flowIoOf(context, pool, git, base), () => context.shouldStop?.() === true || context.shouldPauseAdmission?.() === true);
+    const triggerPass = housekeeping?.triggers ?? { added: 0, checked: 0, problems: [] };
+    const replyPass = housekeeping?.replies ?? { read: 0, taken: 0, problem: null };
+    const stepPass = housekeeping?.steps ?? { ran: 0, problems: [] };
+    const flowPass = housekeeping?.flows ?? { moved: 0, filed: [], problems: [] };
     // Each AI teammate's daily summary to its manager (v92), once, after 5 pm; its weekly report (v97), Monday mornings.
     if (!buildsOnly)
         try {
@@ -2177,9 +2181,19 @@ async function tickCommand(flags, context) {
             flowPass.problems.push(`tool sign-ins: ${error instanceof Error ? error.message : "could not renew"}`);
         }
     }
-    const replied = replyPass.taken > 0 || replyPass.problem !== null;
-    const flows = flowPass.moved + flowPass.filed.length + flowPass.problems.length + triggerPass.added + triggerPass.problems.length + stepPass.ran + stepPass.problems.length === 0 && !replied ? {} : { flows: { ...flowPass,
-            ...(triggerPass.added + triggerPass.problems.length === 0 ? {} : { triggers: triggerPass }), ...(stepPass.ran + stepPass.problems.length === 0 ? {} : { steps: stepPass }), ...(replied ? { replies: replyPass } : {}) } };
+    // A build, research or check finishing below moves its card at once (moveCardsAfter), not a pass later: by then
+    // other builds may hold the worker for minutes.
+    let settled = 0;
+    const settleFinished = () => {
+        const finished = dispatched.slice(settled).filter(one => one.outcome !== "skipped" && one.outcome !== "contest").map(one => one.id);
+        settled = dispatched.length;
+        if (finished.length === 0)
+            return;
+        const after = moveCardsAfter(store, repo, finished, clock(), context.evidenceRoot);
+        flowPass.moved += after.moved;
+        flowPass.filed.push(...after.filed);
+        flowPass.problems.push(...after.problems);
+    };
     // Tournament housekeeping before the ordinary pass (stage 4): interrupted
     // races recover by CAS, and an ANSWERED question re-admits its parked
     // agent — fresh claim, fresh slot, remaining budget only, the SAME
@@ -2544,6 +2558,7 @@ async function tickCommand(flags, context) {
     const attestedThisPass = new Map();
     let untakenTrial = null;
     for (const ref of ready) {
+        settleFinished();
         untakenTrial?.giveBack();
         untakenTrial = null;
         // The build budget governs UNATTENDED admissions (round-1 finding 4):
@@ -3913,6 +3928,7 @@ async function tickCommand(flags, context) {
     // only claim, worktree, and rail, and its run then re-proves the
     // chain-entry dispatch proof inside build() before any money moves.
     for (const pending of buildsOnly ? [] : store.pendingChainAdmissions(repo)) {
+        settleFinished();
         if (context.shouldStop?.() === true || context.shouldPauseAdmission?.() === true)
             break;
         if (built >= max)
@@ -4323,6 +4339,10 @@ async function tickCommand(flags, context) {
     // Existing worker pass owns durable lead handoffs; reads never create events.
     if (!buildsOnly)
         syncAssignmentHandoffs(store, clock(), auth.runner.repos, context.evidenceRoot);
+    settleFinished();
+    const replied = replyPass.taken > 0 || replyPass.problem !== null;
+    const flows = flowPass.moved + flowPass.filed.length + flowPass.problems.length + triggerPass.added + triggerPass.problems.length + stepPass.ran + stepPass.problems.length === 0 && !replied ? {} : { flows: { ...flowPass,
+            ...(triggerPass.added + triggerPass.problems.length === 0 ? {} : { triggers: triggerPass }), ...(stepPass.ran + stepPass.problems.length === 0 ? {} : { steps: stepPass }), ...(replied ? { replies: replyPass } : {}) } };
     const summary = () => {
         const lines = [`Considered ${considered}, built ${built}, parked ${parked}, broke ${broke}.`];
         for (const entry of routines) {
@@ -7544,6 +7564,52 @@ async function runWatchLoop(args) {
             const ran = await runWaitingChecks(store, context.evidenceRoot, { now: context.clock, shouldStop: stopping });
             if (ran > 0)
                 progress(`watch: ran ${ran} follow-up check(s)`);
+            // A finished check may send a build's card down its failure path: now, not on the next beat.
+            if (ran > 0)
+                moveCards(store, repo, context.clock(), context.evidenceRoot);
+        },
+    });
+    // Flows on their own cadence (flow-cadence.ts), not between builds: while builds hold every slot of this
+    // project, a card whose step finished still moves within one beat. Moves run apart from triggers, replies
+    // and steps, so a long check script doesn't hold them either. Neither starts a build: a card entering a
+    // build zone files its task, which waits for a free slot like any other.
+    const flowEveryMs = context.flowEveryMs ?? FLOW_EVERY_MS;
+    const flowPool = text(flags, "pool") ?? join(dirname(databasePath(process.env, homedir())), "worktrees");
+    const flowGit = context.gitRunner ?? run;
+    const flowsDid = (moved, filed, did) => {
+        if (moved + filed === 0)
+            return;
+        store.bumpWake();
+        progress(`watch: ${did}`);
+    };
+    const flowMoves = startMaintenance({
+        intervalMs: flowEveryMs,
+        shouldStop: stopping,
+        onError: error => progress(`watch: flow cards couldn't move — ${describe(error)}; they try again shortly`),
+        run: async () => {
+            if (paused())
+                return;
+            const moved = moveCards(store, repo, context.clock(), context.evidenceRoot);
+            flowsDid(moved.moved, moved.filed.length, `moved ${moved.moved} flow card(s), filed ${moved.filed.length} task(s)`);
+        },
+    });
+    const flowSteps = startMaintenance({
+        intervalMs: flowEveryMs,
+        shouldStop: stopping,
+        onError: error => progress(`watch: a flow pass failed — ${describe(error)}; it runs again shortly`),
+        run: async () => {
+            if (paused())
+                return;
+            let base = text(flags, "base");
+            if (base === undefined) {
+                const head = await flowGit("git", ["symbolic-ref", "--short", "-q", "HEAD"], { cwd: repo });
+                // A detached HEAD: the tick says so; steps wait for a branch rather than guessing one.
+                if (head.code !== 0 || head.stdout.trim() === "")
+                    return;
+                base = head.stdout.trim();
+            }
+            const pass = await flowHousekeeping(store, repo, context.clock, flowIoOf(context, flowPool, flowGit, base), admissionStopped);
+            flowsDid(pass.flows.moved + pass.triggers.added + pass.steps.ran + pass.replies.taken, pass.flows.filed.length, `flow pass — ${pass.triggers.added} card(s) added, ${pass.replies.taken} reply(ies) taken, ${pass.steps.ran} step(s) run, ${pass.flows.moved} moved`);
         },
     });
     const modelWatch = startMaintenance({
@@ -7780,6 +7846,8 @@ async function runWatchLoop(args) {
         await Promise.all(lanes);
         await maintenance.stop();
         await followUpChecks.stop();
+        await flowMoves.stop();
+        await flowSteps.stop();
         await modelWatch.stop();
         clearInterval(heartbeat);
         followController.abort();

package/dist/project-tools.d.ts

@@ -48,6 +48,21 @@ export type ResolvedTool = {
 export declare const TOOL_CATALOG: readonly (ToolSpec & {
     label: string;
 })[];
+/**
+ * Apps that serve their own MCP on this computer: Connect adds them like a
+ * common tool (`connect` is its one line of how), a test that can't reach one
+ * says why (`offline`), and research may read what `reads` names (see
+ * readsOnly in mcp-connect.ts). The only loopback address research reaches.
+ */
+export type LocalApp = {
+    tool: string;
+    connect: string;
+    offline: string;
+    reads: readonly string[];
+};
+export declare const LOCAL_APPS: readonly LocalApp[];
+/** The local app a project's tool is, when it is one exactly as listed (same name and address). */
+export declare function localAppOf(spec: Pick<ToolSpec, "name" | "url">): LocalApp | null;
 export declare function catalogTool(id: string): (ToolSpec & {
     label: string;
 }) | null;

package/dist/project-tools.js

@@ -51,7 +51,20 @@ export const TOOL_CATALOG = [
         about: "Reads Sentry issues and errors." },
     { label: "Supabase (read-only)", name: "supabase", transport: "stdio", command: "npx", args: ["-y", "@supabase/mcp-server-supabase@0.13.0", "--read-only"], url: null, secrets: [{ name: "SUPABASE_ACCESS_TOKEN", optional: false }], bearer: null, headerSecrets: {},
         about: "Reads Supabase tables and schema, without changing anything." },
+    // Figma's Dev Mode server, run by its desktop app on this computer and signed in as the app is: no key.
+    { label: "Figma (desktop app)", name: "figma-desktop", transport: "http", command: null, args: [], url: "http://127.0.0.1:3845/mcp", secrets: [], bearer: null, headerSecrets: {},
+        about: "Code, images, variables and metadata from what you select in the Figma desktop app." },
 ];
+export const LOCAL_APPS = [
+    { tool: "figma-desktop", connect: "Open the Figma desktop app, turn on the Dev Mode MCP server in Preferences, then Connect.",
+        offline: "The Figma desktop app isn't running, or its Dev Mode MCP server is off. Open Figma and turn the server on in Preferences.",
+        reads: ["code", "image", "screenshot", "variable", "defs", "metadata", "design", "context", "connect", "map", "figjam"] },
+];
+/** The local app a project's tool is, when it is one exactly as listed (same name and address). */
+export function localAppOf(spec) {
+    const app = LOCAL_APPS.find(one => one.tool === spec.name);
+    return app !== undefined && spec.url !== null && spec.url === catalogTool(app.tool)?.url ? app : null;
+}
 export function catalogTool(id) {
     return TOOL_CATALOG.find(one => one.name === id) ?? null;
 }
@@ -513,7 +526,7 @@ async function exchangeHttp(spec, values, timeoutMs, request) {
         return { ok: true, result: answered.message.result };
     }
     catch (error) {
-        return { ok: false, problem: error instanceof Error && error.name === "TimeoutError" ? `It did not answer within ${Math.round(timeoutMs / 1000)} seconds.` : "It could not be reached." };
+        return { ok: false, problem: error instanceof Error && error.name === "TimeoutError" ? `It did not answer within ${Math.round(timeoutMs / 1000)} seconds.` : localAppOf(spec)?.offline ?? "It could not be reached." };
     }
 }
 /** One line of a server's own words, never a secret. */

package/dist/result-shots.d.ts

@@ -15,6 +15,8 @@ export type ResultShot = {
     caption: string;
     /** Within Telegram's photo limits, so it shows an inline preview. */
     photo: boolean;
+    /** Captioned with its item's number (flow-items.ts): an album shows it on this photo, not only on the first. */
+    numbered?: true;
 };
 export type ResultShotsPlan = 
 /** Nothing to send and nothing to say: off, pruned by retention, none saved, or all already sent. */
@@ -38,7 +40,9 @@ export type ResultShotsPlan =
  * Every byte returned was verified this instant; a channel uploads them with
  * no wait in between, or asks again.
  */
-export declare function resultShotsFor(store: Store, evidenceRoot: string | undefined, repos: readonly string[], row: Pick<Notification, "kind" | "recipient" | "taskId" | "taskRef" | "run">, sent?: ReadonlySet<number>): ResultShotsPlan;
+export declare function resultShotsFor(store: Store, evidenceRoot: string | undefined, repos: readonly string[], row: Pick<Notification, "kind" | "recipient" | "taskId" | "taskRef" | "run"> & {
+    dedupeKey?: string;
+}, sent?: ReadonlySet<number>): ResultShotsPlan;
 /** A row that carries a result's screenshots: one a person asked for with results, or one a flow sends them. */
 export declare function isShotsKind(kind: string): boolean;
 /** A screenshot whose result message is not posted yet waits for that message's own next try (at least a second). */

package/dist/result-shots.js

@@ -19,6 +19,7 @@ import { imageDimensions, readVerifiedProofForRun, readVerifiedReport, RETENTION
 import { resultImageFileName, verifyResultImage } from "./chat-evidence.js";
 import { publicChatText } from "./chat-display.js";
 import { chatTitle } from "./chat-voice.js";
+import { itemCaption, readFlowItems } from "./flow-items.js";
 import { FLOW_SHOTS_KIND, RESULT_SHOTS_KIND } from "./store.js";
 /** "Up to 4": the most screenshots one result ever sends. */
 export const RESULT_SHOTS_MAX = 4;
@@ -58,6 +59,28 @@ function reportCaptions(store, root, taskRef, run) {
     }
     return captions;
 }
+/** A flow visit's item screenshots from this run, in item order, each with its numbered caption (flow-items.ts). */
+function itemCaptions(store, dedupeKey, run) {
+    const captions = new Map();
+    const visit = /^flow-shots:([1-9][0-9]{0,14}):([1-9][0-9]{0,9})$/.exec(dedupeKey ?? "");
+    const kept = visit === null ? null : store.flowSend(Number(visit[1]), Number(visit[2]));
+    if (kept === null)
+        return captions;
+    let content;
+    try {
+        content = JSON.parse(kept.contentJson);
+    }
+    catch {
+        return captions;
+    }
+    if (content.shots?.run !== run)
+        return captions;
+    readFlowItems(content.items).forEach((item, index) => {
+        if (item.shot !== null && !captions.has(item.shot))
+            captions.set(item.shot, publicChatText(itemCaption(index + 1, item), 200).trim());
+    });
+    return captions;
+}
 function isPhoto(bytes, format) {
     const size = imageDimensions(bytes, format);
     if (size === null || size.width === 0 || size.height === 0)
@@ -92,7 +115,13 @@ export function resultShotsFor(store, evidenceRoot, repos, row, sent = new Set()
     const latest = store.runsFor(row.taskRef).find(one => one.finishedAt !== null && ["builder", "repair", "scout"].includes(one.role));
     if (family?.current.id !== row.taskId || latest?.id !== row.run)
         return line("a newer result replaced this one");
-    const chosen = store.artifactsFor(row.run).filter(one => one.kind === "screenshot").slice(0, limit);
+    // After research, a flow's message numbers the report's items (flow-items.ts): their screenshots go first, in that
+    // order, each captioned with its item's number, so "2." here is item 2 in the text.
+    const items = row.kind === FLOW_SHOTS_KIND ? itemCaptions(store, row.dedupeKey, row.run) : new Map();
+    const order = [...items.keys()];
+    const rank = (id) => { const at = order.indexOf(id); return at < 0 ? order.length : at; };
+    const chosen = store.artifactsFor(row.run).filter(one => one.kind === "screenshot")
+        .map((one, at) => ({ one, at })).sort((a, b) => rank(a.one.id) - rank(b.one.id) || a.at - b.at).map(({ one }) => one).slice(0, limit);
     if (chosen.length === 0)
         return { kind: "none", why: "none" };
     const captions = ownCaptions(store, evidenceRoot, row.run);
@@ -107,11 +136,12 @@ export function resultShotsFor(store, evidenceRoot, repos, row, sent = new Set()
             return line(verified.problem);
         }
         const own = captions.get(SCREENSHOT_CAPTURE.exec(artifact.capture)?.[1] ?? "") ?? reported.get(artifact.id) ?? null;
+        const item = items.get(artifact.id);
         shots.push({
             artifact: artifact.id, sha256: artifact.sha256, bytes: verified.bytes, format: verified.format,
             fileName: resultImageFileName(row.taskId, row.run, artifact.id, verified.format),
-            caption: index === 0 ? (own === null ? title : `${title} · ${own}`) : own ?? `${title} · screenshot ${index + 1}`,
-            photo: isPhoto(verified.bytes, verified.format),
+            caption: item !== undefined ? item : index === 0 ? (own === null ? title : `${title} · ${own}`) : own ?? `${title} · screenshot ${index + 1}`,
+            photo: isPhoto(verified.bytes, verified.format), ...(item === undefined ? {} : { numbered: true }),
         });
     }
     const remaining = shots.filter(one => !sent.has(one.artifact));