@galaxyproject/orbit 0.0.0 → 0.9.0

package/extensions/orbit/tools.ts

@@ -0,0 +1,1300 @@
+/**
+ * Orbit-extension-specific tool registrations.
+ *
+ * Plans, steps, and decisions live as markdown sections inside the project
+ * notebook (`notebook.md`) — the agent maintains them via the generic
+ * Edit/Write tools. The only tools registered here are:
+ *   - GTN tutorial discovery / fetch
+ *   - Galaxy invocation tracking (record + poll status from the notebook)
+ *   - Galaxy skills fetch (operational know-how from galaxyproject/galaxy-skills)
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "@sinclair/typebox";
+import { getNotebookPath } from "./state";
+import { defaultDeps as proposalDeps, noteProposalBinding } from "./proposal-commands";
+import {
+  readNotebook,
+  writeNotebook,
+  withNotebookLock,
+  withNotebookCas,
+  findInvocationBlocks,
+  locateInvocationBlock,
+  upsertInvocationBlock,
+  applyInvocationUpdates,
+  statNotebook,
+  NotebookChangedError,
+  type InvocationYaml,
+  type InvocationPollUpdate,
+} from "./notebook-writer";
+import {
+  isTerminalJobState,
+  locateJobBlock,
+  upsertJobBlock,
+  type JobYaml,
+} from "./galaxy-job-block";
+import {
+  ambiguousAnchorMessage,
+  listNotebookAnchors,
+  resolveNotebookAnchor,
+  unknownAnchorMessage,
+  UnknownAnchorError,
+} from "./notebook-anchors";
+import {
+  INVOCATION_SCHEDULED_OK,
+  INVOCATION_SCHEDULING_DONE,
+  getGalaxyConfig,
+  galaxyGetInvocation,
+  sameGalaxyServer,
+  verifyGalaxyRun,
+  type InvocationDetail,
+} from "./galaxy-api";
+import { listEnabledSkillRepos, findSkillRepo } from "./skills";
+import { fetchSkillFile, githubRawBase } from "./skills-discovery";
+import {
+  STAGING_REPO_NAME,
+  VENDOR_REPO_NAME,
+  hasBundledContent,
+  isBundledRepo,
+  isReservedRepo,
+  readBundledRepoFile,
+} from "./vendor-skills";
+import { GTN_API, gtnPageText, gtnTopics, gtnTutorials, gtnUrl } from "../../shared/gtn.js";
+import type { GalaxyToolFamily } from "../../shared/galaxy-tool-family.js";
+
+/**
+ * A record call's label has to say something.
+ *
+ * Not politeness: `parseInvocationBlock` requires a label, so a block written
+ * with an empty one stops parsing, and then the next call to the same tool
+ * cannot find it and treats the run as unrecorded. Refusing here is what keeps
+ * the block readable by the same parser that has to find it again.
+ */
+function requireLabel(label: string): string {
+  const trimmed = label.trim();
+  if (!trimmed) {
+    throw new Error(
+      "label cannot be empty -- it is what the Activity panel and the notebook " +
+        "show for this run. Give it something like 'BWA alignment'.",
+    );
+  }
+  return trimmed;
+}
+
+/**
+ * Reduce a GTN page to the agent's text. The reduction is shared with the browser shell
+ * (shared/gtn.js): it drops chrome, prefers the most specific content region, and degrades
+ * on malformed HTML rather than leaking an unterminated script body.
+ */
+function stripGtnHtml(html: string): string {
+  return gtnPageText(html);
+}
+
+/**
+ * Resolve a caller-supplied anchor against the notebook, or refuse.
+ *
+ * The record tools wrote whatever they were handed, so an anchor the notebook
+ * has never heard of produced a block bound to nothing: the run still shows up
+ * and still polls, but every consumer that looks a step up by anchor -- the
+ * evidence gate first among them -- reads "no opinion" instead of "broken".
+ * Rejecting costs the model one retry and hands it the list to retry with.
+ */
+function requireAnchor(content: string, input: string): string {
+  const resolved = resolveNotebookAnchor(content, input);
+  if (resolved.kind === "resolved") return resolved.anchor;
+  throw new UnknownAnchorError(
+    resolved.kind === "ambiguous"
+      ? ambiguousAnchorMessage(input, resolved.candidates)
+      : unknownAnchorMessage(input, listNotebookAnchors(content)),
+  );
+}
+
+/** The refusal both record tools hand back: nothing written, reason named. */
+function recordFailure(message: string): {
+  content: { type: "text"; text: string }[];
+  details: Record<string, unknown>;
+} {
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify({ success: false, error: message }) }],
+    details: { error: true } as Record<string, unknown>,
+  };
+}
+
+export function registerPlanTools(pi: ExtensionAPI, family: GalaxyToolFamily): void {
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Tool: Search/browse GTN topics and tutorials
+  // ─────────────────────────────────────────────────────────────────────────────
+  pi.registerTool({
+    name: "gtn_search",
+    label: "Search GTN Tutorials",
+    description: `Browse GTN topics and discover tutorials. Call with no arguments to list all
+topics. Provide a topic ID to list its tutorials. Use query to filter tutorials by keyword
+in their title or objectives. Use this to find tutorial URLs before fetching with gtn_fetch.`,
+    parameters: Type.Object({
+      topic: Type.Optional(
+        Type.String({
+          description: "Topic ID to list tutorials for (e.g., 'transcriptomics', 'introduction')",
+        }),
+      ),
+      query: Type.Optional(
+        Type.String({
+          description: "Keyword to filter tutorials by title or objectives (case-insensitive)",
+        }),
+      ),
+    }),
+    async execute(_toolCallId, params, signal, _onUpdate, _ctx) {
+      try {
+        if (!params.topic) {
+          const resp = await fetch(`${GTN_API}/topics.json`, { signal });
+          if (!resp.ok) {
+            return {
+              content: [{ type: "text", text: `Error: GTN API returned HTTP ${resp.status}` }],
+              details: { error: true },
+            };
+          }
+
+          const listing = gtnTopics(await resp.json());
+          if (!listing) {
+            return {
+              content: [{ type: "text", text: "Error: GTN returned an unexpected topics payload" }],
+              details: { error: true },
+            };
+          }
+          return {
+            content: [{ type: "text", text: JSON.stringify(listing, null, 2) }],
+            details: { count: listing.count },
+          };
+        }
+
+        const resp = await fetch(`${GTN_API}/topics/${params.topic}.json`, { signal });
+        if (!resp.ok) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Error: Topic "${params.topic}" not found (HTTP ${resp.status}). Use gtn_search with no arguments to list available topics.`,
+              },
+            ],
+            details: { error: true },
+          };
+        }
+
+        const listing = gtnTutorials(await resp.json(), params.query);
+        if (!listing) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Error: Topic "${params.topic}" returned an unexpected payload.`,
+              },
+            ],
+            details: { error: true },
+          };
+        }
+        return {
+          content: [{ type: "text", text: JSON.stringify(listing, null, 2) }],
+          details: { topic: params.topic, count: listing.count },
+        };
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return {
+          content: [{ type: "text", text: `Error searching GTN: ${msg}` }],
+          details: { error: true },
+        };
+      }
+    },
+    renderResult: (result) => {
+      const d = result.details as { count?: number; topic?: string; error?: boolean } | undefined;
+      if (d?.error) {
+        return new Text("❌ GTN search failed");
+      }
+      if (d?.topic) {
+        return new Text(`📚 Found ${d.count || 0} tutorials in "${d.topic}"`);
+      }
+      return new Text(`📚 Found ${d?.count || 0} GTN topics`);
+    },
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Tool: Fetch GTN tutorial content
+  // ─────────────────────────────────────────────────────────────────────────────
+  pi.registerTool({
+    name: "gtn_fetch",
+    label: "Fetch GTN Tutorial",
+    description: `Fetch a Galaxy Training Network (GTN) tutorial page and return its content as
+readable text. Only URLs on training.galaxyproject.org are allowed. Use gtn_search first to
+discover valid tutorial URLs — do not guess or construct URLs. Use this to read tutorial
+instructions, tool names, parameters, and workflow steps so you can follow along and reproduce
+analyses in Galaxy.`,
+    parameters: Type.Object({
+      url: Type.String({
+        description: "URL of the GTN tutorial page (must be on training.galaxyproject.org)",
+      }),
+    }),
+    async execute(_toolCallId, params, signal, _onUpdate, _ctx) {
+      const checked = gtnUrl(params.url);
+      if (checked.problem !== undefined) {
+        return {
+          content: [{ type: "text", text: `Error: ${checked.problem}` }],
+          details: { error: true },
+        };
+      }
+
+      try {
+        const response = await fetch(params.url, { signal });
+
+        if (!response.ok) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Error: Failed to fetch tutorial (HTTP ${response.status})`,
+              },
+            ],
+            details: { error: true },
+          };
+        }
+
+        const html = await response.text();
+        const text = stripGtnHtml(html);
+
+        return {
+          content: [
+            {
+              type: "text",
+              text,
+            },
+          ],
+          details: { url: params.url, length: text.length },
+        };
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return {
+          content: [{ type: "text", text: `Error fetching tutorial: ${msg}` }],
+          details: { error: true },
+        };
+      }
+    },
+    renderResult: (result) => {
+      const d = result.details as { url?: string; length?: number; error?: boolean } | undefined;
+      if (d?.error) {
+        return new Text("❌ GTN fetch failed");
+      }
+      return new Text(`📖 Fetched GTN tutorial (${d?.length || 0} chars)`);
+    },
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Tool: Fetch a SKILL.md or reference doc from a configured skills repo
+  // ─────────────────────────────────────────────────────────────────────────────
+  pi.registerTool({
+    name: "skills_fetch",
+    label: "Fetch Skill",
+    description: `Load operational know-how from a skills repo. The system
+prompt's "Skills repositories" section lists the repos and the canonical paths
+inside each; a repo marked bundled there is read from the package, and any other
+is fetched and cached locally for 24h. If \`repo\` is omitted, the first enabled
+repo is used (typically \`galaxy-skills\`).
+
+\`repo: "${STAGING_REPO_NAME}"\` reads Orbit's staging skills (ones that have not
+moved to a permanent repo yet), listed in the router under that name. \`repo: "${VENDOR_REPO_NAME}"\` reads Galaxy workflow
+reference material bundled with Orbit. Both are always offline. The
+${VENDOR_REPO_NAME} material is deliberately absent from the router, so its
+paths are not listed there: a hint names the exact file when it becomes
+relevant, and a wrong path answers with the entry points that do exist.`,
+    parameters: Type.Object({
+      repo: Type.Optional(
+        Type.String({
+          description:
+            "Name of the skills repo to fetch from (e.g. 'galaxy-skills'), " +
+            `'${STAGING_REPO_NAME}' for Orbit's staging skills, or ` +
+            `'${VENDOR_REPO_NAME}' for bundled reference material. ` +
+            "Omit to use the default (first enabled repo).",
+        }),
+      ),
+      path: Type.String({
+        description:
+          "Relative path inside the repo. For a repo the router lists, use the " +
+          "path it prints, e.g. 'skills/collection-manipulation/SKILL.md'; a " +
+          "skill's own reference docs sit beside it, e.g. " +
+          `'skills/galaxy-mcp-reference/gotchas.md'. For '${VENDOR_REPO_NAME}', ` +
+          "use the path a hint gave you.",
+      }),
+    }),
+    async execute(_toolCallId, params, signal, _onUpdate, _ctx) {
+      // Normalised once, up front, so every branch below reasons about the same
+      // string. The reserved-name branch used to take the model's raw input.
+      const cleanPath = params.path.replace(/^\/+/, "").replace(/\\/g, "/");
+      if (cleanPath.includes("..") || cleanPath === "") {
+        return {
+          content: [{ type: "text", text: `Error: Invalid skill path "${params.path}"` }],
+          details: { error: true },
+        };
+      }
+
+      // A reserved name reads from the package, but only when the user has not
+      // claimed it: configuring a repo called "foundry" or "orbit" has to win, or
+      // an explicitly chosen branch is silently answered from the package.
+      // Checked before the read, not after a miss, because the bundled tree
+      // holds a whole skills mirror and would answer for paths that belong to it.
+      const reserved = params.repo;
+      if (isReservedRepo(reserved) && !findSkillRepo(reserved)) {
+        if (!hasBundledContent(reserved)) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Error: this build of Orbit ships nothing under "${reserved}".`,
+              },
+            ],
+            details: { error: true, repo: reserved, path: cleanPath },
+          };
+        }
+        const res = readBundledRepoFile({ name: reserved }, cleanPath);
+        if (res.ok) {
+          return {
+            content: [{ type: "text", text: res.text }],
+            details: {
+              repo: reserved,
+              path: cleanPath,
+              length: res.text.length,
+              bundled: true,
+            },
+          };
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error: ${res.error}. Available: ${res.available.join(", ") || "(none)"}.`,
+            },
+          ],
+          details: { error: true, repo: reserved, path: cleanPath },
+        };
+      }
+
+      const repo = findSkillRepo(params.repo);
+      if (!repo) {
+        const enabled =
+          listEnabledSkillRepos()
+            .map((r) => r.name)
+            .join(", ") || "(none)";
+        return {
+          content: [
+            {
+              type: "text",
+              text: params.repo
+                ? `Error: Skills repo "${params.repo}" is not configured or is disabled. Enabled: ${enabled}.`
+                : `Error: No skills repos are enabled. Configure one in Preferences → Skills.`,
+            },
+          ],
+          details: { error: true },
+        };
+      }
+
+      // A repo still on its shipped URL and branch is served from the package:
+      // the content was reviewed at a pinned commit and works with no network.
+      // Point it at another branch and it goes back to being fetched, which is
+      // how a skill author evaluates a change before it is merged.
+      //
+      // Gated on the content actually being there. If the vendor tree is missing
+      // -- a packaging regression, a half-finished install -- falling through to
+      // the network is a worse day than usual, not a session with no skills.
+      if (isBundledRepo(repo) && hasBundledContent(repo.name)) {
+        const res = readBundledRepoFile(repo, cleanPath);
+        if (res.ok) {
+          return {
+            content: [{ type: "text", text: res.text }],
+            details: { repo: repo.name, path: cleanPath, length: res.text.length, bundled: true },
+          };
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error: ${res.error}. Available: ${res.available.join(", ") || "(none)"}.`,
+            },
+          ],
+          details: { error: true, repo: repo.name, path: cleanPath },
+        };
+      }
+
+      const rawBase = githubRawBase(repo.url, repo.branch);
+      if (!rawBase) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error: Repo URL "${repo.url}" must be a GitHub repo (https://github.com/<owner>/<repo>).`,
+            },
+          ],
+          details: { error: true },
+        };
+      }
+
+      const res = await fetchSkillFile(repo, cleanPath, signal);
+      if (!res.ok) {
+        if (res.status) {
+          return {
+            content: [
+              {
+                type: "text",
+                text:
+                  `Error: Failed to fetch "${cleanPath}" from ${repo.name} (HTTP ${res.status}). ` +
+                  `Check the path against the skills router in the system prompt.`,
+              },
+            ],
+            details: { error: true, repo: repo.name, path: cleanPath },
+          };
+        }
+        return {
+          content: [{ type: "text", text: `Error fetching skill: ${res.error}` }],
+          details: { error: true, repo: repo.name, path: cleanPath },
+        };
+      }
+      return {
+        content: [{ type: "text", text: res.text }],
+        details: { repo: repo.name, path: cleanPath, length: res.text.length, cached: res.cached },
+      };
+    },
+    renderResult: (result) => {
+      const d = result.details as
+        | {
+            repo?: string;
+            path?: string;
+            length?: number;
+            cached?: boolean;
+            bundled?: boolean;
+            error?: boolean;
+          }
+        | undefined;
+      if (d?.error) return new Text("❌ Skill fetch failed");
+      const tag = d?.bundled ? "(bundled)" : d?.cached ? "(cached)" : "(fetched)";
+      return new Text(`📘 ${d?.repo}/${d?.path} ${tag} (${d?.length || 0} chars)`);
+    },
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Tool: Record a Galaxy invocation in the notebook
+  // ─────────────────────────────────────────────────────────────────────────────
+  pi.registerTool({
+    name: "galaxy_invocation_record",
+    label: "Record Galaxy Invocation",
+    description: `Name the plan step a Galaxy workflow invocation belongs to. The harness
+records the run; you name the step it belongs to. Orbit already wrote a \`loom-invocation\`
+block the moment ${family.tool("invoke_workflow")} returned, so this normally just sets \`label\` and
+\`notebook_anchor\` on the block already carrying that id -- the run is pollable either way.
+If no block carries the id (a submission Orbit could not see, such as one made from inside
+code mode), this creates one. Both arguments are checked before anything is written: the
+anchor must resolve in notebook.md, and the invocation id must exist on the Galaxy server.`,
+    parameters: Type.Object({
+      invocationId: Type.String({
+        description: `Galaxy invocation ID returned from ${family.tool("invoke_workflow")}`,
+      }),
+      notebookAnchor: Type.String({
+        description:
+          "Anchor of the plan step this run belongs to, e.g. 'plan-a-step-3'. It must " +
+          "already exist in notebook.md, either as a {#anchor} on the step or as a " +
+          "heading; an anchor nothing resolves to is rejected.",
+      }),
+      label: Type.String({
+        description: "Human-readable description for status display, e.g. 'BWA alignment'",
+      }),
+      proposalId: Type.Optional(
+        Type.String({
+          description:
+            "The approved proposal this run carries out (the id from loom_propose that the " +
+            "user approved). Recorded alongside the run; it doesn't approve anything.",
+        }),
+      ),
+    }),
+    async execute(_toolCallId, params, signal, _onUpdate, _ctx) {
+      const notebookPath = getNotebookPath();
+      if (!notebookPath) return recordFailure("No notebook open.");
+
+      const cfg = getGalaxyConfig();
+      const galaxyServerUrl = cfg?.url || "";
+
+      try {
+        // Ask Galaxy before writing anything down. An id Galaxy has never heard
+        // of records nothing: the poller 404s on it every tick, the Activity
+        // panel shows a run that doesn't exist, and whatever the model really
+        // submitted stays untracked.
+        const check = await verifyGalaxyRun("invocation", params.invocationId, signal);
+        if (check.outcome === "absent") {
+          return recordFailure(
+            `Galaxy has no invocation "${params.invocationId}" (${check.detail}). ` +
+              `Nothing was recorded -- re-read the id from the ${family.tool("invoke_workflow")} result.`,
+          );
+        }
+        // A failed check plus an aborted call is the user cancelling, not Galaxy
+        // being unreachable. Recording an unverified block for a turn they
+        // stopped would leave them a record of something nobody confirmed.
+        if (check.outcome === "unreachable" && signal?.aborted) {
+          return recordFailure("Cancelled before Galaxy could confirm the invocation.");
+        }
+        const serverVerified = check.outcome === "found";
+
+        const submittedAt = new Date().toISOString();
+        // Guarded write: the poller and the agent both write this file while we
+        // are talking to Galaxy, and an unguarded whole-file rewrite would drop
+        // whatever landed in between. Resolving the anchor inside means it is
+        // checked against the bytes we're about to rewrite rather than a copy
+        // read earlier -- a block bound to a step that was renamed away is
+        // exactly the silent-nothing the check exists to stop.
+        const { inv, annotated } = await withNotebookLock(notebookPath, () =>
+          withNotebookCas(notebookPath, (content) => {
+            const notebookAnchor = requireAnchor(content, params.notebookAnchor);
+            const label = requireLabel(params.label);
+            // The harness writes a block the moment a submission answers, so
+            // the usual case here is a block that already exists. Annotating
+            // it means label and anchor only: the rest -- status, the poller's
+            // counters, the server it was submitted to, and its
+            // `server_verified` verdict -- belongs to whoever wrote it, and a
+            // fresh record object would reset a running invocation to
+            // `in_progress` and throw away the progress already polled.
+            //
+            // Presence and contents come from one physical block, so this
+            // cannot decide "nothing carries this id" about a block the upsert
+            // is nonetheless going to overwrite.
+            const found = locateInvocationBlock(content, params.invocationId);
+            if (found.present && !found.record) {
+              throw new Error(
+                `A loom-invocation block for ${params.invocationId} is already in the notebook ` +
+                  `but cannot be read -- it is missing a required field or has been hand-edited. ` +
+                  `Nothing was changed; fix or remove that block first.`,
+              );
+            }
+            const record: InvocationYaml = found.record
+              ? { ...found.record, notebookAnchor, label }
+              : {
+                  invocationId: params.invocationId,
+                  galaxyServerUrl,
+                  notebookAnchor,
+                  label,
+                  submittedAt,
+                  status: "in_progress",
+                  serverVerified,
+                };
+            // Only a block this call creates carries provenance, and it is the
+            // agent's: the harness did not see this submission happen.
+            return {
+              content: upsertInvocationBlock(
+                content,
+                record,
+                found.present ? undefined : { submittedBy: "agent" },
+              ),
+              result: { inv: record, annotated: found.present },
+            };
+          }),
+        );
+
+        const where = `${inv.invocationId} (${inv.label}) at ${inv.notebookAnchor}`;
+        const proposal = params.proposalId
+          ? await noteProposalBinding(proposalDeps, {
+              proposalId: params.proposalId,
+              notebookAnchor: inv.notebookAnchor,
+              run: { kind: "invocation", id: inv.invocationId },
+            })
+          : undefined;
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  success: true,
+                  invocationId: inv.invocationId,
+                  notebookAnchor: inv.notebookAnchor,
+                  label: inv.label,
+                  status: inv.status,
+                  annotated,
+                  serverVerified: inv.serverVerified,
+                  ...(proposal ? { proposal } : {}),
+                  message: annotated
+                    ? `Bound invocation ${where}. Orbit had already recorded the run; this ` +
+                      `named the step it belongs to.`
+                    : serverVerified
+                      ? `Recorded invocation ${where}.`
+                      : `Recorded invocation ${where}, but Galaxy could not confirm it ` +
+                        `(${check.detail}). The block says server_verified: false; the poller ` +
+                        `clears that on its first successful poll.`,
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+          details: {
+            invocationId: inv.invocationId,
+            notebookAnchor: inv.notebookAnchor,
+            serverVerified: inv.serverVerified,
+            annotated,
+          } as Record<string, unknown>,
+        };
+      } catch (error) {
+        return recordFailure(error instanceof Error ? error.message : String(error));
+      }
+    },
+    renderResult: (result) => {
+      const d = result.details as
+        | {
+            invocationId?: string;
+            notebookAnchor?: string;
+            serverVerified?: boolean;
+            annotated?: boolean;
+            error?: boolean;
+          }
+        | undefined;
+      if (d?.error) return new Text("❌ Failed to record invocation");
+      const unconfirmed = d?.serverVerified === false ? " (unconfirmed)" : "";
+      const verb = d?.annotated ? "Bound" : "Recorded";
+      return new Text(
+        `🔗 ${verb} invocation ${d?.invocationId} → ${d?.notebookAnchor}${unconfirmed}`,
+      );
+    },
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Tool: Record a Galaxy tool run (job) in the notebook
+  // ─────────────────────────────────────────────────────────────────────────────
+  pi.registerTool({
+    name: "galaxy_job_record",
+    label: "Record Galaxy Job",
+    description: `Name the plan step a Galaxy TOOL run belongs to, the same way
+galaxy_invocation_record does for a workflow. The harness records the run; you name the step
+it belongs to. Orbit already wrote a \`loom-job\` block the moment ${family.tool("run_tool")} returned, so
+this normally just sets \`label\` and \`notebook_anchor\` on the block already carrying that
+job id -- the poller is watching it either way. If no block carries the id, this creates one.
+Both arguments are checked before anything is written: the anchor must resolve in notebook.md,
+and the job id must exist on the Galaxy server. \`toolId\` is used only when creating.`,
+    parameters: Type.Object({
+      jobId: Type.String({ description: `Galaxy job ID returned from ${family.tool("run_tool")}` }),
+      notebookAnchor: Type.String({
+        description:
+          "Anchor of the plan step this run belongs to, e.g. 'plan-a-step-3'. It must " +
+          "already exist in notebook.md, either as a {#anchor} on the step or as a " +
+          "heading; an anchor nothing resolves to is rejected.",
+      }),
+      label: Type.String({
+        description: "Human-readable description for status display, e.g. 'BWA alignment'",
+      }),
+      toolId: Type.Optional(
+        Type.String({
+          description:
+            "Galaxy tool id, e.g. 'bwa_mem' — shown if no label fits. Only used when this " +
+            "call creates the block; an existing block keeps the tool id it was recorded with.",
+        }),
+      ),
+      proposalId: Type.Optional(
+        Type.String({
+          description:
+            "The approved proposal this run carries out (the id from loom_propose that the " +
+            "user approved). Recorded alongside the run; it doesn't approve anything.",
+        }),
+      ),
+    }),
+    async execute(_toolCallId, params, signal, _onUpdate, _ctx) {
+      const notebookPath = getNotebookPath();
+      if (!notebookPath) return recordFailure("No notebook open.");
+
+      const cfg = getGalaxyConfig();
+      try {
+        const check = await verifyGalaxyRun("job", params.jobId, signal);
+        if (check.outcome === "absent") {
+          return recordFailure(
+            `Galaxy has no job "${params.jobId}" (${check.detail}). Nothing was recorded -- ` +
+              `re-read the id from the ${family.tool("run_tool")} result. A tool run returns a job id, ` +
+              `not a dataset id.`,
+          );
+        }
+        if (check.outcome === "unreachable" && signal?.aborted) {
+          return recordFailure("Cancelled before Galaxy could confirm the job.");
+        }
+        const serverVerified = check.outcome === "found";
+
+        const submittedAt = new Date().toISOString();
+        const { job, annotated } = await withNotebookLock(notebookPath, () =>
+          withNotebookCas(notebookPath, (content) => {
+            const notebookAnchor = requireAnchor(content, params.notebookAnchor);
+            const label = requireLabel(params.label);
+            // Same rules as the invocation side: annotate means label and
+            // anchor only, and presence and contents come from one physical
+            // block. See the comments there.
+            const found = locateJobBlock(content, params.jobId);
+            if (found.present && !found.record) {
+              throw new Error(
+                `A loom-job block for ${params.jobId} is already in the notebook but cannot be ` +
+                  `read. Nothing was changed; fix or remove that block first.`,
+              );
+            }
+            const record: JobYaml = found.record
+              ? { ...found.record, notebookAnchor, label }
+              : {
+                  jobId: params.jobId,
+                  galaxyServerUrl: cfg?.url || "",
+                  notebookAnchor,
+                  label,
+                  toolId: params.toolId,
+                  submittedAt,
+                  status: "in_progress",
+                  serverVerified,
+                };
+            return {
+              content: upsertJobBlock(
+                content,
+                record,
+                found.present ? undefined : { submittedBy: "agent" },
+              ),
+              result: { job: record, annotated: found.present },
+            };
+          }),
+        );
+
+        const where = `${job.jobId} (${job.label}) at ${job.notebookAnchor}`;
+        const proposal = params.proposalId
+          ? await noteProposalBinding(proposalDeps, {
+              proposalId: params.proposalId,
+              notebookAnchor: job.notebookAnchor,
+              run: { kind: "job", id: job.jobId },
+            })
+          : undefined;
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  success: true,
+                  jobId: job.jobId,
+                  notebookAnchor: job.notebookAnchor,
+                  label: job.label,
+                  status: job.status,
+                  annotated,
+                  serverVerified: job.serverVerified,
+                  ...(proposal ? { proposal } : {}),
+                  message: annotated
+                    ? `Bound job ${where}. Orbit had already recorded the run; this named the ` +
+                      `step it belongs to.`
+                    : serverVerified
+                      ? `Recorded job ${where}. The background poller will advance it and notify on completion.`
+                      : `Recorded job ${where}, but Galaxy could not confirm it (${check.detail}). ` +
+                        `The block says server_verified: false; the poller clears that on its ` +
+                        `first successful poll.`,
+                },
+                null,
+                2,
+              ),
+            },
+          ],
+          details: {
+            jobId: job.jobId,
+            notebookAnchor: job.notebookAnchor,
+            serverVerified: job.serverVerified,
+            annotated,
+          } as Record<string, unknown>,
+        };
+      } catch (error) {
+        return recordFailure(error instanceof Error ? error.message : String(error));
+      }
+    },
+    renderResult: (result) => {
+      const d = result.details as
+        | {
+            jobId?: string;
+            notebookAnchor?: string;
+            serverVerified?: boolean;
+            annotated?: boolean;
+            error?: boolean;
+          }
+        | undefined;
+      if (d?.error) return new Text("❌ Failed to record job");
+      const unconfirmed = d?.serverVerified === false ? " (unconfirmed)" : "";
+      const verb = d?.annotated ? "Bound" : "Recorded";
+      return new Text(`🔗 ${verb} job ${d?.jobId} → ${d?.notebookAnchor}${unconfirmed}`);
+    },
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Tool: Poll all in-flight invocations and update notebook YAML
+  // ─────────────────────────────────────────────────────────────────────────────
+  pi.registerTool({
+    name: "galaxy_invocation_check_all",
+    label: "Check All Galaxy Invocations",
+    description: `Scan the notebook for in-flight loom-invocation blocks, poll Galaxy for each,
+and apply deterministic state transitions: an invocation Galaxy has finished scheduling whose
+jobs have all stopped becomes completed (or failed, if any errored); anything still scheduling,
+running, queued or paused stays in_progress. Updates the YAML blocks in place. Returns a summary
+list.`,
+    parameters: Type.Object({}),
+    async execute(_toolCallId, _params, signal, _onUpdate, _ctx) {
+      return await checkInvocations(undefined, signal);
+    },
+    renderResult: (result) => {
+      const d = result.details as { checked?: number; error?: boolean } | undefined;
+      if (d?.error) return new Text("❌ Invocation check failed");
+      return new Text(`🔍 Checked ${d?.checked || 0} invocation(s)`);
+    },
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Tool: Poll one invocation by id
+  // ─────────────────────────────────────────────────────────────────────────────
+  pi.registerTool({
+    name: "galaxy_invocation_check_one",
+    label: "Check Galaxy Invocation",
+    description: `Poll a single Galaxy invocation by id. Same auto-transition rules as
+galaxy_invocation_check_all. Errors if the invocation isn't recorded in the notebook.`,
+    parameters: Type.Object({
+      invocationId: Type.String({ description: "Galaxy invocation ID to check" }),
+    }),
+    async execute(_toolCallId, params, signal, _onUpdate, _ctx) {
+      return await checkInvocations(params.invocationId, signal);
+    },
+    renderResult: (result) => {
+      const d = result.details as { checked?: number; error?: boolean } | undefined;
+      if (d?.error) return new Text("❌ Invocation check failed");
+      return new Text(`🔍 Checked ${d?.checked || 0} invocation(s)`);
+    },
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Internal: shared poll loop for the two check tools
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface CheckResultEntry {
+  invocationId: string;
+  notebookAnchor: string;
+  label: string;
+  invocationState: string;
+  /** The block's status before this poll, so a transition can name both ends. */
+  priorStatus: InvocationYaml["status"];
+  jobSummary: { ok: number; running: number; queued: number; error: number; other: number };
+  /** The raw Galaxy states behind `jobSummary.other`, counted, so they can be named. */
+  otherStates: Record<string, number>;
+  /** Jobs Galaxy could still advance: running + queued + the non-terminal half of `other`. */
+  activeJobs: number;
+  /** The status this poll wrote, when it wrote one. Absent on a no-op poll. */
+  newStatus?: InvocationYaml["status"];
+  lastPolledAt?: string;
+  autoAction?: string;
+}
+
+const TERMINAL_INVOCATION_STATES = INVOCATION_SCHEDULING_DONE;
+
+/** Galaxy job states that mean "this job failed", as opposed to ended some other way. */
+const FAILED_JOB_STATES: ReadonlySet<string> = new Set(["error", "failed", "deleted"]);
+
+/** "1 paused, 2 skipped" — for naming the states hiding behind `other`. */
+function describeStates(counts: Record<string, number>): string {
+  return Object.entries(counts)
+    .map(([state, n]) => `${n} ${state}`)
+    .join(", ");
+}
+
+/** What one invocation's jobs add up to. */
+export interface InvocationJobRollup {
+  summary: { ok: number; running: number; queued: number; error: number; other: number };
+  /** The raw Galaxy states behind `summary.other`, counted. */
+  otherStates: Record<string, number>;
+  /** Jobs Galaxy could still advance: running + queued + the non-terminal half of `other`. */
+  activeJobs: number;
+  totalJobs: number;
+  completedSteps: number;
+}
+
+/** Count an invocation's jobs by state, keeping what `other` is actually made of. */
+export function rollUpInvocationJobs(inv: InvocationDetail): InvocationJobRollup {
+  const summary = { ok: 0, running: 0, queued: 0, error: 0, other: 0 };
+  // What is actually behind `other`, counted by state. The rollup can't tell a
+  // paused job (Galaxy will run it) from a skipped one (a conditional step that
+  // never will), and both used to be ignored outright.
+  const otherStates: Record<string, number> = {};
+  let activeOther = 0;
+  let totalJobs = 0;
+  let completedSteps = 0;
+  for (const invStep of inv.steps) {
+    let stepJobs = 0;
+    let stepOk = 0;
+    for (const job of invStep.jobs) {
+      stepJobs++;
+      totalJobs++;
+      if (job.state === "ok") {
+        summary.ok++;
+        stepOk++;
+      } else if (job.state === "running") summary.running++;
+      else if (job.state === "queued" || job.state === "new" || job.state === "waiting")
+        summary.queued++;
+      else if (FAILED_JOB_STATES.has(job.state)) summary.error++;
+      else {
+        summary.other++;
+        const state = job.state || "unknown";
+        otherStates[state] = (otherStates[state] ?? 0) + 1;
+        // `skipped` and `stopped` are over; `paused`, `upload`,
+        // `setting_metadata`, `deleting` and friends are not.
+        if (!isTerminalJobState(job.state)) activeOther++;
+      }
+    }
+    // A step that runs no job (a workflow input, a step mapped over an empty
+    // collection) is done once Galaxy has scheduled it. A subworkflow step also
+    // has no job of its own, but its work is still going until the subworkflow
+    // finishes, so it isn't counted that way.
+    const doneWithoutJobs =
+      stepJobs === 0 && invStep.state === "scheduled" && !invStep.subworkflow_invocation_id;
+    if ((stepJobs > 0 && stepJobs === stepOk) || doneWithoutJobs) completedSteps++;
+  }
+  return {
+    summary,
+    otherStates,
+    activeJobs: summary.running + summary.queued + activeOther,
+    totalJobs,
+    completedSteps,
+  };
+}
+
+/**
+ * True while Galaxy could still advance this invocation — either it hasn't
+ * finished scheduling, or a job it already scheduled is still moving.
+ *
+ * The poller asks this about an invocation whose notebook block has vanished:
+ * a live run nobody is watching is worth saying out loud, a finished one isn't.
+ */
+export function isInvocationLive(inv: InvocationDetail): boolean {
+  if (!TERMINAL_INVOCATION_STATES.has(inv.state)) return true;
+  return rollUpInvocationJobs(inv).activeJobs > 0;
+}
+
+interface CheckInvocationsResult {
+  content: { type: "text"; text: string }[];
+  details: Record<string, unknown>;
+}
+
+export async function checkInvocations(
+  specificId: string | undefined,
+  signal?: AbortSignal,
+): Promise<CheckInvocationsResult> {
+  const notebookPath = getNotebookPath();
+  if (!notebookPath) {
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: JSON.stringify({ success: false, error: "No notebook open." }),
+        },
+      ],
+      details: { error: true } as Record<string, unknown>,
+    };
+  }
+
+  if (!getGalaxyConfig()) {
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: JSON.stringify({ success: false, error: "Galaxy credentials not configured." }),
+        },
+      ],
+      details: { error: true } as Record<string, unknown>,
+    };
+  }
+
+  // Phase 1 — decide what to poll. Read under the lock so we see any Orbit
+  // write (a just-finished invocation_record) whole, but hold it only for the
+  // read: there is no network I/O in here.
+  const blocks = await withNotebookLock(notebookPath, async () =>
+    findInvocationBlocks(await readNotebook(notebookPath)),
+  );
+
+  let toCheck: InvocationYaml[];
+  if (specificId) {
+    const found = blocks.find((b) => b.invocationId === specificId);
+    if (!found) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify({
+              success: false,
+              error: `Invocation ${specificId} not found in notebook.`,
+            }),
+          },
+        ],
+        details: { error: true } as Record<string, unknown>,
+      };
+    }
+    toCheck = [found];
+  } else {
+    toCheck = blocks.filter((b) => b.status === "in_progress");
+  }
+
+  if (toCheck.length === 0) {
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: JSON.stringify({
+            success: true,
+            results: [],
+            message: "No in-progress invocations.",
+          }),
+        },
+      ],
+      details: { checked: 0 } as Record<string, unknown>,
+    };
+  }
+
+  // Phase 2 — talk to Galaxy with no lock held and nothing pinned in memory
+  // about the notebook. These GETs are the slow part (one round trip per
+  // in-flight invocation); before #391 they sat between the read and the write,
+  // so every notebook write the agent made meanwhile was overwritten by a
+  // seconds-stale snapshot. Errors stay per-block: a 502 on one invocation must
+  // not cost the others their update.
+  const results: CheckResultEntry[] = [];
+  const updates: InvocationPollUpdate[] = [];
+
+  for (const block of toCheck) {
+    try {
+      // galaxyGetInvocation asks for step details, which the counters below
+      // depend on: without them every step's `jobs` list is empty, neither the
+      // completed nor the failed branch can fire, and the block sits at
+      // in_progress forever with no toast and no transition.
+      const inv = await galaxyGetInvocation(block.invocationId, signal);
+
+      const { summary, otherStates, activeJobs, totalJobs, completedSteps } =
+        rollUpInvocationJobs(inv);
+
+      let autoAction: string | undefined;
+      let transition: InvocationPollUpdate["transition"];
+
+      // Two questions, both of which the old predicate skipped: is Galaxy done
+      // handing out jobs, and is any job it already handed out still moving? A
+      // workflow whose first two steps are ok while the third is still being
+      // scheduled is not finished, and neither is one holding a paused job.
+      const schedulingDone = TERMINAL_INVOCATION_STATES.has(inv.state);
+
+      if (schedulingDone && activeJobs === 0) {
+        const ended = describeStates(otherStates);
+        if (inv.state === "cancelled") {
+          // A cancel is not a failure and not a completion, and the block has
+          // no third word for it -- so it lands terminal (nothing is coming
+          // that would move it again) and the summary says what happened.
+          const unfinished = summary.error > 0 ? `, ${summary.error} did not` : "";
+          transition = {
+            status: "failed",
+            summary: `Workflow cancelled: ${summary.ok} job(s) finished before it stopped${unfinished}`,
+          };
+          autoAction = "cancelled";
+        } else if (summary.error > 0) {
+          transition = {
+            status: "failed",
+            summary: `Workflow failed: ${summary.error} job(s) errored, ${summary.ok} succeeded`,
+          };
+          autoAction = "failed";
+        } else if (inv.state === "failed") {
+          // Galaxy failed to schedule the workflow. No job carries the failure,
+          // so without this the block sits at in_progress with nothing left to
+          // poll it into a terminal state.
+          transition = {
+            status: "failed",
+            summary: `Workflow failed: Galaxy reported invocation state "failed"`,
+          };
+          autoAction = "failed";
+        } else if (summary.ok > 0 && INVOCATION_SCHEDULED_OK.has(inv.state)) {
+          transition = {
+            status: "completed",
+            summary:
+              `Workflow completed: ${summary.ok} jobs succeeded` + (ended ? ` (${ended})` : ""),
+          };
+          autoAction = "completed";
+        }
+      } else {
+        // A cancel is not instant: Galaxy moves the invocation to `cancelled`
+        // and then deletes its jobs one at a time. Naming it is what lets the
+        // renderer tell a deliberate stop from a failure -- it has no
+        // invocation state to look at, only this sentence -- and without it the
+        // loudest surface in the product raises a red alarm about something the
+        // user asked for.
+        const stopping = inv.state === "cancelled" || inv.state === "cancelling";
+        const tail =
+          activeJobs > 0
+            ? `${activeJobs} still running`
+            : stopping
+              ? `waiting for Galaxy to finish the cancel (state: ${inv.state})`
+              : `invocation still scheduling (state: ${inv.state})`;
+        if (stopping) {
+          // Deliberately not gated on the failed counter. Right after a cancel
+          // every job is still running, so nothing has landed in it yet -- and
+          // that is exactly the window where the panel would otherwise say the
+          // run is going along fine.
+          //
+          // "did not finish" rather than "failed" because the counter cannot
+          // tell the two apart: rollUpInvocationJobs scores a `deleted` job
+          // beside a genuinely errored one, so a run that broke and was then
+          // cancelled has both in the same number. It is the word the panel
+          // itself uses for a stopping row.
+          transition = {
+            status: "in_progress",
+            summary: `Workflow cancelling: ${summary.error} job(s) did not finish, ${tail}`,
+          };
+          autoAction = "cancelling";
+        } else if (summary.error > 0) {
+          // A failure with work still in flight. Keep the block in_progress so
+          // the rest stays under observation -- terminal blocks are never polled
+          // again -- but say so in the summary and let the poller raise it once.
+          transition = {
+            status: "in_progress",
+            summary: `Workflow in progress: ${summary.error} job(s) failed, ${tail}`,
+          };
+          autoAction = "failing";
+        }
+      }
+
+      // Always update the block — even if the rolled-up status didn't
+      // change, the per-poll counters (and last_polled_at) did, and the
+      // renderer wants those for the live progress bar. Status and summary
+      // ride along only on a transition, so a no-op poll can't overwrite an
+      // edit the agent made to the block while we were talking to Galaxy.
+      const lastPolledAt = new Date().toISOString();
+      updates.push({
+        invocationId: block.invocationId,
+        totalSteps: inv.steps.length,
+        completedSteps,
+        totalJobs,
+        completedJobs: summary.ok,
+        failedJobs: summary.error,
+        lastPolledAt,
+        // We just got an answer out of Galaxy for this id, which is the proof a
+        // block recorded `server_verified: false` is waiting for -- but only if
+        // the answer came from the server the block names. A profile switch
+        // must not let another server's `inv-1` certify this one.
+        serverVerified: sameGalaxyServer(block.galaxyServerUrl, getGalaxyConfig()?.url),
+        transition,
+      });
+
+      results.push({
+        invocationId: block.invocationId,
+        notebookAnchor: block.notebookAnchor,
+        label: block.label,
+        invocationState: inv.state,
+        priorStatus: block.status,
+        jobSummary: summary,
+        otherStates,
+        activeJobs,
+        newStatus: transition?.status,
+        lastPolledAt,
+        autoAction,
+      });
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      results.push({
+        invocationId: block.invocationId,
+        notebookAnchor: block.notebookAnchor,
+        label: block.label,
+        invocationState: "error_checking",
+        priorStatus: block.status,
+        jobSummary: { ok: 0, running: 0, queued: 0, error: 0, other: 0 },
+        otherStates: {},
+        activeJobs: 0,
+        autoAction: `check_error: ${msg}`,
+      });
+    }
+  }
+
+  // Phase 3 — persist. The lock still keeps two Orbit writers from losing each
+  // other's updates, but the guarantee now comes from re-reading inside it
+  // rather than from having held it across the poll: whoever gets the lock
+  // second folds their blocks into content that already contains the first
+  // writer's. A write that loses to an outside writer between our read and our
+  // rename fails the stamp check and is retried against fresh content rather
+  // than silently overwriting it.
+  if (updates.length > 0) {
+    const { applied, transitioned } = await withNotebookLock(notebookPath, () =>
+      persistInvocationUpdates(notebookPath, updates),
+    );
+    // A transition we didn't actually record isn't news. The poller turns
+    // "completed"/"failed" straight into a user-facing toast, so leaving the
+    // flag on a block that was deleted mid-poll — or that another poller had
+    // already advanced — would announce a state change nothing wrote.
+    //
+    // "failing" and "cancelling" never change the status, so they can't be
+    // checked against the transitions; they're news as long as the counters
+    // and summary carrying them landed somewhere.
+    for (const entry of results) {
+      const announced =
+        entry.autoAction === "completed" ||
+        entry.autoAction === "failed" ||
+        entry.autoAction === "cancelled";
+      if (announced && !transitioned.has(entry.invocationId)) entry.autoAction = undefined;
+      const midFlight = entry.autoAction === "failing" || entry.autoAction === "cancelling";
+      if (midFlight && !applied.has(entry.invocationId)) {
+        entry.autoAction = undefined;
+      }
+    }
+  }
+
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify({ success: true, checked: results.length, results }, null, 2),
+      },
+    ],
+    // Expose the per-invocation results so the background poller can fire a
+    // completion notification for any invocation that just reached a terminal
+    // state (autoAction "completed"/"failed"). The agent-facing summary already
+    // travels in `content`; this is for the headless poller path.
+    details: { checked: results.length, results } as Record<string, unknown>,
+  };
+}
+
+// A write only loses the stamp check when someone else wrote in the microseconds
+// between our read and our rename; three attempts is far more than convergence
+// needs, and bounding it keeps a pathological writer from spinning us.
+const MAX_PERSIST_ATTEMPTS = 3;
+
+/**
+ * Read -> fold in the polled blocks -> write, retrying against fresh content if
+ * the notebook changed under us. Call with the notebook lock held. Returns the
+ * invocation ids this call wrote, and separately those whose status it changed.
+ *
+ * The stamp is taken *before* the read on purpose. Stamping afterwards would
+ * let a write that landed between the read and the stat look unchanged — the
+ * exact clobber this is here to stop — whereas stamping first can only ever
+ * cost us a spurious retry.
+ */
+async function persistInvocationUpdates(
+  notebookPath: string,
+  updates: InvocationPollUpdate[],
+): Promise<{ applied: Set<string>; transitioned: Set<string> }> {
+  let lastError: unknown;
+  for (let attempt = 0; attempt < MAX_PERSIST_ATTEMPTS; attempt++) {
+    const stamp = await statNotebook(notebookPath);
+    // Read regardless of the stat, so a notebook that's actually gone or
+    // unreadable fails with its own ENOENT/EACCES instead of being dressed up
+    // as a race.
+    const fresh = await readNotebook(notebookPath);
+    // Readable but unstattable: without a stamp there's no compare-and-swap,
+    // and an unguarded whole-file write is the thing #391 is about. Treat it as
+    // a lost race rather than quietly downgrading to one.
+    if (!stamp) {
+      lastError = new NotebookChangedError(notebookPath);
+      continue;
+    }
+    const { content, applied, transitioned } = applyInvocationUpdates(fresh, updates);
+    // Every block was deleted or already has a newer poll on disk — nothing to
+    // write, so don't rewrite the file (and don't risk a race) for no change.
+    if (applied.length === 0) return { applied: new Set(), transitioned: new Set() };
+    try {
+      await writeNotebook(notebookPath, content, stamp);
+      return { applied: new Set(applied), transitioned: new Set(transitioned) };
+    } catch (error) {
+      if (!(error instanceof NotebookChangedError)) throw error;
+      lastError = error;
+    }
+  }
+  // Surface it: the poller's catch drops the tick (so no completion toast fires
+  // for a transition we failed to record) and the next tick re-polls.
+  throw lastError;
+}