toolroll 0.9.25 → 0.9.26

package/dist/desktop-update.d.ts

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

package/dist/flow-cadence.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Flow passes that don't wait for builds. The worker's pass used to move
+ * cards only between builds, so a card whose research finished sat still
+ * while another build ran (Oct 4: five minutes). Now the worker runs these
+ * passes on their own cadence beside its builds, and a finished build,
+ * research or check moves its card at once.
+ *
+ * Model-free and cheap: nothing here starts a build. Cards entering a build
+ * zone file their task, which waits for a free slot like any other.
+ */
+import { type FlowAdvance } from "./flow-engine.js";
+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";
+/** 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>;
+export type FlowIo = {
+    triggers: TriggerIo;
+    replies: ReplyWatchIo;
+    steps: StepIo;
+    evidenceRoot?: string;
+};
+export type FlowHousekeeping = {
+    triggers: TriggerPass;
+    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. */
+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. */
+export declare function moveCards(store: Store, repo: string, now: Date, evidenceRoot: string | undefined): FlowAdvance;
+/** A build, research or check just finished: move the cards in this project, and in the project of any flow whose
+ * card that task belongs to (a build zone may build in another project), now rather than on the next pass. */
+export declare function moveCardsAfter(store: Store, repo: string, tasks: readonly string[], now: Date, evidenceRoot: string | undefined): FlowAdvance;

package/dist/flow-cadence.js

@@ -0,0 +1,78 @@
+/**
+ * Flow passes that don't wait for builds. The worker's pass used to move
+ * cards only between builds, so a card whose research finished sat still
+ * while another build ran (Oct 4: five minutes). Now the worker runs these
+ * passes on their own cadence beside its builds, and a finished build,
+ * research or check moves its card at once.
+ *
+ * Model-free and cheap: nothing here starts a build. Cards entering a build
+ * zone file their task, which waits for a free slot like any other.
+ */
+import { advanceFlows } from "./flow-engine.js";
+import { runFlowTriggers } from "./flow-triggers.js";
+import { watchFlowReplies } from "./flow-replies.js";
+import { runFlowSteps } from "./flow-steps.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();
+/** 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 async function alone(kind, project, idle, run) {
+    const key = `${kind}\u0000${project}`;
+    if (running.has(key))
+        return idle;
+    running.add(key);
+    try {
+        return await run();
+    }
+    finally {
+        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. */
+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));
+    // 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));
+    const steps = halted() ? { ran: 0, problems: [] }
+        : 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 };
+}
+/** 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. */
+export function moveCards(store, repo, now, evidenceRoot) {
+    try {
+        return advanceFlows(store, repo, now, evidenceRoot === undefined ? {} : { evidenceRoot });
+    }
+    catch (error) {
+        return { moved: 0, filed: [], problems: [`flows: ${error instanceof Error ? error.message : "could not move cards"}`] };
+    }
+}
+/** A build, research or check just finished: move the cards in this project, and in the project of any flow whose
+ * card that task belongs to (a build zone may build in another project), now rather than on the next pass. */
+export function moveCardsAfter(store, repo, tasks, now, evidenceRoot) {
+    const projects = new Set([repo]);
+    for (const task of tasks) {
+        try {
+            const card = store.flowCardByTask(task) ?? store.flowCardByTask(store.taskFamilyOf(task, null, true)?.root.id ?? task);
+            const flow = card === null ? null : store.getFlow(card.flow);
+            if (flow !== null)
+                projects.add(flow.repo);
+        }
+        catch { /* not a task with a card */ }
+    }
+    const outcome = { moved: 0, filed: [], problems: [] };
+    for (const project of projects) {
+        const moved = moveCards(store, project, now, evidenceRoot);
+        outcome.moved += moved.moved;
+        outcome.filed.push(...moved.filed);
+        outcome.problems.push(...moved.problems);
+    }
+    return outcome;
+}

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/scout.d.ts

@@ -25,8 +25,9 @@ export declare function scoutBrowserLaunch(tool: Pick<ToolSpec, "command" | "arg
 export declare function scoutBrowser(url: string): Record<string, unknown>;
 /** The scout's environment while its proxy runs (review 827): web fetch and the provider's own traffic go through
  * the same public-web-only proxy as its browser, so only public addresses (and the project's demo) are reachable.
- * The one direct address is its own browser's port, when it has one (review 828): the proxy refuses loopback. */
-export declare function scoutProxyEnv(proxy: string, browserUrl?: string | null): Record<string, string>;
+ * The direct addresses are its own browser's port, when it has one (review 828), and an app on this computer it
+ * reads (`local`: Figma's desktop server): the proxy refuses loopback. */
+export declare function scoutProxyEnv(proxy: string, browserUrl?: string | null, local?: readonly string[]): Record<string, string>;
 export type ScoutRequest = {
     /** v105: what's left of a monthly budget this API-key work counts toward (the CLI's own cap), when one does. */
     maxBudgetUsd?: number;