pi-onlyne 1.2.0 → 1.2.2

package/src/agent.test.mjs

@@ -11,7 +11,6 @@ import { fileURLToPath } from "node:url";
 import { afterEach, test } from "node:test";
 
 import { OnlyneAgent } from "./agent.mjs";
-import { MAX_LINES, MAX_WIDTH } from "./activity.mjs";
 import { DEFAULT_IDLE_REMINDERS } from "./config.mjs";
 import { createFrameDecoder, encodeFrame } from "./frame.mjs";
 import { SEQ_BASE, readyReport } from "./protocol.mjs";
@@ -206,6 +205,7 @@ class FakeHost {
 /** The effect surface the agent drives, recorded for assertions. */
 function fakeSurface(options = {}) {
   const calls = { wakeUser: [], prose: [], entries: [], status: [], exits: [], widget: [] };
+  const flag = (value, fallback) => (value === undefined ? fallback : typeof value === "function" ? value() : value);
   return {
     calls,
     available: {
@@ -237,6 +237,9 @@ function fakeSurface(options = {}) {
     widget: (lines) => calls.widget.push(lines),
     welcome: () => {},
     isIdle: () => (options.idle === undefined ? true : options.idle()),
+    async waitingForInput() {
+      return Boolean(flag(options.waiting, true) && !flag(options.backgroundWork, false));
+    },
     exit: (reason) => calls.exits.push(reason),
   };
 }
@@ -345,7 +348,7 @@ test("every heartbeat names the Orca pane this process was spawned in", async ()
       orca: { pane_key: PANE_KEY, tab_id: PANE_TAB, leaf_id: PANE_LEAF, handle: "term_1" },
     });
     // The binding rides beside the state dimensions instead of replacing them.
-    assert.equal(observed.agent, "running");
+    assert.equal(observed.agent, "idle", "the default fake surface is waiting for input");
     assert.equal(observed.resource, "attached");
     assert.deepEqual(Object.keys(observed), [...OBSERVED_KEYS, "host"]);
     assert.equal(observed.version.generation, 1);
@@ -370,24 +373,6 @@ test("a reconnect reports the same pane", async () => {
   });
 });
 
-test("a second task in the same pane reports the same pane", async () => {
-  await inOrcaPane(PANE_ENV, async () => {
-    const { host } = await mountedAgent();
-    host.notify("assign", assignArgs());
-    await waitFor(() => (host.of("assign_ack").length === 1 ? true : null));
-    host.notify("probe", {});
-    await waitFor(() => (heartbeats(host).length ? true : null));
-
-    // The binding belongs to the process, not to the task: handing this pane
-    // another task cannot change where the process runs.
-    host.notify("assign", { ...assignArgs(), task_id: "22222222-2222-4222-8222-222222222222" });
-    await waitFor(() => (host.of("assign_ack").length === 2 ? true : null));
-    host.notify("probe", {});
-    const reports = await waitFor(() => (heartbeats(host).length >= 2 ? heartbeats(host) : null));
-    assert.deepEqual(reports.at(-1).host, reports[0].host);
-  });
-});
-
 test("a pi outside an Orca pane reports no host at all", async () => {
   await inOrcaPane({}, async () => {
     const { host } = await mountedAgent();
@@ -397,23 +382,7 @@ test("a pi outside an Orca pane reports no host at all", async () => {
 
     const [observed] = await waitFor(() => (heartbeats(host).length ? heartbeats(host) : null));
     assert.equal("host" in observed, false, "no pane, no binding");
-    assert.equal(observed.agent, "running", "the tuple is still a full observation");
-  });
-});
-
-test("a pane that exports no handle reports the pane without inventing one", async () => {
-  await inOrcaPane({ ORCA_PANE_KEY: PANE_KEY }, async () => {
-    const { host } = await mountedAgent();
-    host.notify("assign", assignArgs());
-    await waitFor(() => (host.of("assign_ack").length === 1 ? true : null));
-    host.notify("probe", {});
-
-    const [observed] = await waitFor(() => (heartbeats(host).length ? heartbeats(host) : null));
-    // The pane key carries both ids; the handle is a field the environment
-    // either has or has not, and a missing one is absent rather than empty.
-    assert.deepEqual(observed.host, {
-      orca: { pane_key: PANE_KEY, tab_id: PANE_TAB, leaf_id: PANE_LEAF },
-    });
+    assert.equal(observed.agent, "idle", "the tuple is still a full observation");
   });
 });
 
@@ -584,7 +553,7 @@ test("an assign sharing the hello reply's chunk waits for the welcome", async ()
   assert.deepEqual(acks[0], { task_id: TASK_ID, accepted: true });
 });
 
-test("turn hooks report running then idle, and the settle after them re-sends the assignment", async () => {
+test("a waiting turn end reports idle, and the settle after it re-sends the assignment", async () => {
   const { agent, host, surface } = await startAgent();
   agent.start();
   await waitFor(() => host.of("report").length >= 1);
@@ -616,6 +585,29 @@ test("turn hooks report running then idle, and the settle after them re-sends th
   assert.deepEqual(surface.calls.exits, [], "a task with a rung left is not failed");
 });
 
+test("a busy turn end reports no idle beat and does not settle the ladder", async () => {
+  const surface = fakeSurface({ waiting: false });
+  const { agent, host } = await startAgent({ surface });
+  agent.start();
+  await waitFor(() => host.of("report").length >= 1);
+  host.notify("assign", assignArgs());
+  await waitFor(() => (surface.calls.wakeUser.length === 1 ? true : null));
+
+  agent.onTurnStart();
+  await waitFor(() => host.of("report").find((report) => report.data?.observed?.agent === "running"));
+  agent.onTurnEnd();
+  agent.onSettled();
+  await waitFor(() => heartbeats(host).length >= 3);
+
+  assert.equal(
+    heartbeats(host).some((observed) => observed.agent === "idle"),
+    false,
+    "the turn-end beat follows the busy surface rather than assuming the hook means idle",
+  );
+  assert.equal(surface.calls.wakeUser.length, 1, "the ladder waits while the turn is still running");
+  assert.deepEqual(surface.calls.exits, []);
+});
+
 // The live case found this ordering too: pi's turn-end hook fires in the same
 // millisecond as the settle that reports the completion, so the turn-end
 // heartbeat lands after the completion report. The beat no longer carries a
@@ -640,9 +632,9 @@ test("a turn-end heartbeat after the completion never leaves the plugin", async
   assert.deepEqual(host.of("report").slice(reports), [], "the completion is the last report");
 });
 
-test("a busy pi holds the settle decision until it is idle", async () => {
-  let idle = false;
-  const surface = fakeSurface({ idle: () => idle });
+test("a busy pi holds the settle decision until it is waiting for input", async () => {
+  let waiting = false;
+  const surface = fakeSurface({ waiting: () => waiting });
   const { agent, host } = await startAgent({ surface, options: { settleFallbackMs: 40 } });
   agent.start();
   await waitFor(() => host.of("report").length >= 1);
@@ -653,20 +645,44 @@ test("a busy pi holds the settle decision until it is idle", async () => {
   await new Promise((resolve) => setTimeout(resolve, 80));
   assert.equal(surface.calls.wakeUser.length, 1, "a busy pi is not reminded");
 
-  idle = true;
+  waiting = true;
   const reminded = await waitFor(() =>
     surface.calls.wakeUser.length === 2 ? surface.calls.wakeUser : null,
   );
   assert.match(reminded[1].text, /build it/, "the decision waits for the idle it is about");
 });
 
+test("a live background task holds the ladder off until its task is terminal", async () => {
+  let backgroundWork = true;
+  const surface = fakeSurface({ backgroundWork: () => backgroundWork });
+  const { agent, host } = await startAgent({ surface, options: { settleFallbackMs: 40 } });
+  agent.start();
+  await waitFor(() => host.of("report").length >= 1);
+  host.notify("assign", assignArgs());
+  await waitFor(() => (surface.calls.wakeUser.length === 1 ? true : null));
+
+  agent.onTurnStart();
+  agent.onTurnEnd();
+  agent.onSettled();
+  await waitFor(() => heartbeats(host).at(-1)?.agent === "running");
+  await new Promise((resolve) => setTimeout(resolve, 80));
+  assert.equal(surface.calls.wakeUser.length, 1, "work off the agent loop keeps the ladder off");
+
+  backgroundWork = false;
+  agent.onSettled();
+  const reminded = await waitFor(() =>
+    surface.calls.wakeUser.length === 2 ? surface.calls.wakeUser : null,
+  );
+  assert.match(reminded[1].text, /build it/, "the terminal task releases the idle ladder");
+});
+
 // The idle ladder (`docs/SWARM-REFACTOR-GRILLME.md` §4.2): a turn that ends
 // without a completion exit re-sends the assignment, and the idle that finds the
 // bound spent fails the task instead of settling it `done`. The bound is the
 // workspace's (`config.mjs`, two by default) and the count lives on the record
 // `onAssign` wrote for the task, which is why a task can be reminded twice and
 // failed on the third idle without the tool ever being called.
-test("an idle without a completion is reminded, the idle past the bound fails the task, and a completed turn is not reminded", async () => {
+test("only settled idles spend ladder rungs, ordinary turns reset them, and the bound fails the task", async () => {
   const { agent, host, surface } = await startAgent();
   assert.equal(agent.idleReminders, DEFAULT_IDLE_REMINDERS, "the bound is the workspace's, two by default");
   agent.start();
@@ -683,35 +699,59 @@ test("an idle without a completion is reminded, the idle past the bound fails th
   await waitFor(() => (surface.calls.wakeUser.length === 1 ? true : null));
   assert.equal(surface.calls.wakeUser[0].parts.length, 1, "the injection carries the image");
 
-  // Two idles, two reminders: the assignment comes back whole — header, task
-  // text and all — and the model is told why it is seeing it again.
-  for (const rung of [1, 2]) {
-    agent.onTurnStart();
-    agent.onTurnEnd();
-    agent.onSettled();
-    const sent = await waitFor(() =>
-      surface.calls.wakeUser.length === 1 + rung ? surface.calls.wakeUser : null,
-    );
-    const reminder = sent.at(-1);
-    assert.match(reminder.text, new RegExp(`reminder ${rung} of 2`));
-    assert.match(reminder.text, /build it/, "the reminder carries the task text");
-    assert.match(
-      reminder.text,
-      /\[onlyne\] task 11111111-1111-4111-8111-111111111111 from role:planner \(kind task\)/,
-      "and the identity and source the injection named",
-    );
-    assert.match(reminder.text, /\[onlyne\] attachment saved to: .*shot\.png/, "the path travels as text");
-    assert.deepEqual(reminder.parts, [], "and the image itself is not handed over twice");
-    assert.doesNotMatch(reminder.text, /Read the incoming task/, "the role prose is already in the context");
-    assert.deepEqual(
-      host.of("report").filter((report) => report.kind === "complete"),
-      [],
-      `rung ${rung}: an open task is not settled while it has a rung left`,
-    );
-  }
+  // The first turn belongs to the session itself. Its settled idle spends rung
+  // one. The turn that reminder wakes does not reset the episode, so its own
+  // settled idle spends rung two rather than starting over.
+  agent.onTurnStart();
+  agent.onTurnEnd();
+  agent.onSettled();
+  const first = await waitFor(() =>
+    surface.calls.wakeUser.length === 2 ? surface.calls.wakeUser : null,
+  );
+  const firstReminder = first.at(-1);
+  assert.match(firstReminder.text, /reminder 1 of 2/);
+  assert.match(firstReminder.text, /build it/, "the reminder carries the task text");
+  assert.match(
+    firstReminder.text,
+    /\[onlyne\] task 11111111-1111-4111-8111-111111111111 from role:planner \(kind task\)/,
+    "and the identity and source the injection named",
+  );
+  assert.match(firstReminder.text, /\[onlyne\] attachment saved to: .*shot\.png/, "the path travels as text");
+  assert.deepEqual(firstReminder.parts, [], "and the image itself is not handed over twice");
+  assert.doesNotMatch(firstReminder.text, /Read the incoming task/, "the role prose is already in the context");
 
-  // The third idle: the bound is spent, so the open task fails and the session
-  // leaves — the tool was never called, and no completion was ever reported.
+  agent.onTurnStart();
+  agent.onTurnEnd();
+  agent.onSettled();
+  const secondRung = await waitFor(() =>
+    surface.calls.wakeUser.length === 3 ? surface.calls.wakeUser : null,
+  );
+  assert.match(secondRung.at(-1).text, /reminder 2 of 2/, "the reminder-woken turn keeps the episode's count");
+  assert.deepEqual(host.of("report").filter((report) => report.kind === "complete"), []);
+
+  // The next turn is the one the second reminder wakes, so it does not reset
+  // the episode. Let that turn end without a settle, then start a turn of the
+  // session's own: that ordinary turn begins a fresh episode.
+  agent.onTurnStart();
+  agent.onTurnEnd();
+  agent.onTurnStart();
+  agent.onTurnEnd();
+  agent.onSettled();
+  const reset = await waitFor(() =>
+    surface.calls.wakeUser.length === 4 ? surface.calls.wakeUser : null,
+  );
+  assert.match(reset.at(-1).text, /reminder 1 of 2/, "an ordinary turn clears the episode's rung count");
+
+  agent.onTurnStart();
+  agent.onTurnEnd();
+  agent.onSettled();
+  const secondFresh = await waitFor(() =>
+    surface.calls.wakeUser.length === 5 ? surface.calls.wakeUser : null,
+  );
+  assert.match(secondFresh.at(-1).text, /reminder 2 of 2/);
+
+  // The third idle in the fresh episode spends the bound, so the open task
+  // fails and the session leaves — the tool was never called.
   agent.onTurnStart();
   agent.onTurnEnd();
   agent.onSettled();
@@ -722,22 +762,22 @@ test("an idle without a completion is reminded, the idle past the bound fails th
     head: "no completion after 2 idle reminders",
   });
   assert.deepEqual(surface.calls.exits, ["failed"], "the ladder's failure leaves the session");
-  assert.equal(surface.calls.wakeUser.length, 3, "the bound is spent: no third reminder");
+  assert.equal(surface.calls.wakeUser.length, 5, "the bound is spent: no third reminder");
 
   // A turn that hands the outcome over is never reminded: the tool call is the
   // exit the ladder exists to get.
-  const second = await startAgent();
-  second.agent.start();
-  await waitFor(() => second.host.of("report").length >= 1);
-  second.host.notify("assign", assignArgs());
-  await waitFor(() => (second.surface.calls.wakeUser.length === 1 ? true : null));
-  second.agent.onTurnStart();
-  second.agent.onTurnEnd();
-  await second.agent.completeFromTool({ outcome: "done", text: "built it" });
-  second.agent.onSettled();
+  const completed = await startAgent();
+  completed.agent.start();
+  await waitFor(() => completed.host.of("report").length >= 1);
+  completed.host.notify("assign", assignArgs());
+  await waitFor(() => (completed.surface.calls.wakeUser.length === 1 ? true : null));
+  completed.agent.onTurnStart();
+  completed.agent.onTurnEnd();
+  await completed.agent.completeFromTool({ outcome: "done", text: "built it" });
+  completed.agent.onSettled();
   await new Promise((resolve) => setTimeout(resolve, 60));
-  assert.equal(second.surface.calls.wakeUser.length, 1, "the completion is the exit: no reminder follows it");
-  assert.deepEqual(second.surface.calls.exits, ["done"]);
+  assert.equal(completed.surface.calls.wakeUser.length, 1, "the completion is the exit: no reminder follows it");
+  assert.deepEqual(completed.surface.calls.exits, ["done"]);
 });
 
 test("an assigned task that never ran is not completed", async () => {
@@ -873,39 +913,10 @@ test("the exit waits for the client's acknowledgement of the completion report",
   assert.deepEqual(surface.calls.exits, ["done"]);
 });
 
-// A session that only ever reported `running` and then completed leaves the
-// ledger saying `running` forever: the client settles the row from the
-// completion report and hears nothing more. One final observation, sent after
-// the completion is acknowledged and before the process leaves, is what makes
-// an exited session read idle.
-test("a completion after a running beat publishes the settled observation before the exit", async () => {
-  const { agent, host, surface } = await startAgent();
-  agent.start();
-  await waitFor(() => host.of("report").length >= 1);
-  host.notify("assign", assignArgs());
-  await waitFor(() => (surface.calls.wakeUser.length === 1 ? true : null));
-  agent.onTurnStart();
-  await waitFor(() =>
-    host.of("report").find((report) => report.data?.observed?.agent === "running"),
-  );
-  agent.noteAssistantText("OK");
-
-  await agent.complete(TASK_ID, "done", "OK");
-  const reports = host.of("report").filter((report) => report.kind !== "ready");
-  const kinds = reports.map((report) => report.kind);
-  assert.deepEqual(
-    kinds.slice(-2),
-    ["complete", "heartbeat"],
-    "the settled observation follows the completion: " + JSON.stringify(kinds),
-  );
-  const settled = reports.at(-1).data.observed;
-  assert.equal(settled.agent, "idle");
-  assert.deepEqual(dimensionKeys(settled), OBSERVED_KEYS, "the last observation states the agent and nothing else");
-  assert.deepEqual(surface.calls.exits, ["done"]);
-});
-
-test("a session whose last beat was idle publishes no extra observation", async () => {
-  const { agent, host, surface } = await startAgent();
+test("a reconnect beat re-derives the phase from the surface", async () => {
+  let waiting = true;
+  const surface = fakeSurface({ waiting: () => waiting });
+  const { agent, host } = await startAgent({ surface });
   agent.start();
   await waitFor(() => host.of("report").length >= 1);
   host.notify("assign", assignArgs());
@@ -913,45 +924,21 @@ test("a session whose last beat was idle publishes no extra observation", async
   agent.onTurnStart();
   agent.onTurnEnd();
   await waitFor(() => host.of("report").find((report) => report.data?.observed?.agent === "idle"));
-  agent.noteAssistantText("OK");
-  const before = host.of("report").filter((report) => report.kind === "heartbeat").length;
-
-  await agent.complete(TASK_ID, "done", "OK");
-  assert.equal(
-    host.of("report").filter((report) => report.kind === "heartbeat").length,
-    before,
-    "an already-idle session needs no second idle observation",
-  );
-  assert.deepEqual(surface.calls.exits, ["done"]);
-});
-
-test("a queued completion and its settled observation flush in order after reconnect", async () => {
-  const { agent, host, surface } = await startAgent();
-  agent.start();
-  await waitFor(() => host.of("report").length >= 1);
-  host.notify("assign", assignArgs());
-  await waitFor(() => (surface.calls.wakeUser.length === 1 ? true : null));
-  agent.onTurnStart();
-  agent.onTurnEnd();
-  agent.noteAssistantText("done offline");
 
+  const beforeReconnect = host.frames.length;
+  waiting = false;
   for (const socket of [...host.sockets]) socket.destroy();
   await waitFor(() => (agent.status().connected === false ? true : null));
-  await agent.completeFromTool({ outcome: "done" });
-  assert.deepEqual(surface.calls.exits, [], "nothing exits before the report lands");
-
-  await waitFor(() => (host.connections >= 2 ? true : null));
-  await waitFor(() => (surface.calls.exits.length === 1 ? true : null));
-  const reports = host.of("report").filter((report) => report.kind !== "ready");
-  assert.deepEqual(
-    reports.slice(-2).map((report) => [report.kind, report.data.observed?.agent ?? null]),
-    [
-      ["complete", null],
-      ["heartbeat", "idle"],
-    ],
-    "the settled observation rides after the flushed completion: " + JSON.stringify(reports),
+  const beat = await waitFor(() => host.frames
+    .slice(beforeReconnect)
+    .map((entry) => entry.frame)
+    .find((frame) => frame.op === "report" && frame.args?.kind === "heartbeat"));
+  assert.equal(beat.args.data.observed.agent, "running", "the reconnect asks the surface again");
+  assert.equal(
+    heartbeats(host).at(-1).agent,
+    "running",
+    "the old idle beat does not survive the reconnect",
   );
-  assert.deepEqual(dimensionKeys(reports.at(-1).data.observed), OBSERVED_KEYS, "the flushed tail states the agent and nothing else");
 });
 
 test("an inbound image is written under the workspace and handed to pi", async () => {
@@ -986,7 +973,7 @@ test("a probe is answered with a heartbeat for the live task", async () => {
   const heartbeat = await waitFor(() =>
     host.of("report").find((report) => report.kind === "heartbeat" && report.data.task_id === TASK_ID),
   );
-  assert.equal(heartbeat.data.observed.agent, "running");
+  assert.equal(heartbeat.data.observed.agent, "idle", "the probe re-derives a waiting session");
   assert.ok(heartbeat.data.seq > SEQ_BASE, "each heartbeat advances the plugin's own sequence");
 });
 
@@ -1382,27 +1369,6 @@ test("a repeating fault folds into one panel line with a count", () => {
   assert.equal(surface.calls.widget.length, 3, "every event redraws the same panel");
 });
 
-test("the panel stays inside its line and width budget", () => {
-  const surface = fakeSurface({ widget: true });
-  const agent = new OnlyneAgent({
-    socketPath: join(tmpdir(), "pi-onlyne-unused-socket"),
-    cwd: tmpdir(),
-    role: "planner",
-    sessionId: SESSION_ID,
-    taskId: TASK_ID,
-    surface,
-    log: () => {},
-  });
-  for (let index = 0; index < 40; index += 1) {
-    agent.notice("in", `task ${index} from gateway:wechat:room ${"长".repeat(400)}`);
-  }
-  const [render] = surface.calls.widget.slice(-1);
-  assert.ok(render.length <= MAX_LINES, `panel grew to ${render.length} lines`);
-  for (const line of render) {
-    assert.ok(Array.from(line).length <= MAX_WIDTH, `line overruns its width: ${line}`);
-  }
-});
-
 test("a host without the widget keeps the footer line and the stderr line", async () => {
   const surface = fakeSurface();
   const { agent, host, logs } = await startAgent({ surface });

package/src/background-work.mjs

@@ -0,0 +1,176 @@
+// The one question a background-task extension makes necessary: is this
+// session's work still running somewhere the agent loop cannot see?
+//
+// `pi-background-tasks` and its relatives take a long command off the loop — the
+// tool call returns a task id at once and the child process carries on. pi then
+// waits for input while the work runs, so `ctx.isIdle()` alone would report a
+// session as idle with a task in flight. This probe reads the extension's own
+// live task list over the pi EventBus, and only when the extension is installed:
+// without one of its tools there is nothing to recognise, nothing to query, and
+// nothing to wait for.
+//
+// The contract is that package's documented `eventbus-v1` surface
+// (`pi-background-tasks/docs/api/eventbus-v1.md`): one request frame in, one
+// response frame out, both closed objects carrying a schema id. A response that
+// never arrives, a frame that does not parse, an error response, and a host with
+// no EventBus all read as "no background work known" and leave the plugin's own
+// judgement untouched.
+
+/** The tools that mark the extension as installed. */
+export const BACKGROUND_TOOL_NAMES = Object.freeze([
+  "bg_run",
+  "bg_run_pi_attested",
+  "bg_status",
+  "bg_logs",
+  "bg_kill",
+  "bg_delegate",
+  "bg_result",
+  "fusion_reason",
+  "fusion_investigate",
+  "fusion_research",
+  "fusion_validate",
+  "fusion_web_fetch",
+]);
+
+const REQUEST_CHANNEL = "pi-background-tasks:request:v1";
+const RESPONSE_CHANNEL = "pi-background-tasks:response:v1";
+const REQUEST_SCHEMA = "pi-background-tasks.extension-request.v1";
+const RESPONSE_SCHEMA = "pi-background-tasks.extension-response.v1";
+
+/** Task statuses that mean the work is still going. */
+const LIVE_TASK_STATUS = "running";
+
+/** How long one status query waits for its answer. */
+export const DEFAULT_STATUS_TIMEOUT_MS = 500;
+
+/** @param {string} name */
+export function isBackgroundTool(name) {
+  return BACKGROUND_TOOL_NAMES.includes(name);
+}
+
+let requestCounter = 0;
+
+function nextRequestId() {
+  requestCounter += 1;
+  return `onlyne-bg-status-${requestCounter}`;
+}
+
+function isResponseFor(frame, requestId) {
+  return frame
+    && typeof frame === "object"
+    && frame.schema_version === RESPONSE_SCHEMA
+    && frame.request_id === requestId;
+}
+
+/**
+ * One live-task question, asked of the EventBus and answered by whatever is
+ * listening. Every failure mode is inert: the probe reports `false` and says why
+ * once, then lets the caller's own judgement stand.
+ *
+ * @param {{
+ *   events?: { emit: (channel: string, data: unknown) => void, on: (channel: string, handler: (data: unknown) => void) => () => void } | null,
+ *   getToolNames?: () => string[] | null,
+ *   log?: (line: string) => void,
+ *   timeoutMs?: number,
+ * }} options
+ */
+export function createBackgroundProbe({
+  events = null,
+  getToolNames = null,
+  log = () => {},
+  timeoutMs = DEFAULT_STATUS_TIMEOUT_MS,
+} = {}) {
+  let installed = null;
+  const warned = new Set();
+  let unsubscribe = null;
+
+  const warnOnce = (reason) => {
+    if (warned.has(reason)) return;
+    warned.add(reason);
+    log(`background work: ${reason}`);
+  };
+
+  /** True once one of the extension's tools is registered; cached either way. */
+  function isInstalled() {
+    if (installed !== null) return installed;
+    let names = null;
+    try {
+      names = typeof getToolNames === "function" ? getToolNames() : null;
+    } catch (error) {
+      warnOnce(`tool list unreadable: ${error.message}`);
+      return false;
+    }
+    const list = Array.isArray(names) ? names : [];
+    installed = list.some(isBackgroundTool);
+    if (!installed) log("background work: no background-task extension in this session");
+    return installed;
+  }
+
+  /**
+   * One status round trip. The answer arrives on the response channel, so the
+   * listener lives exactly as long as the wait and the timer bounds it.
+   * @returns {Promise<boolean>}
+   */
+  function running() {
+    if (!isInstalled()) return Promise.resolve(false);
+    const bus = events;
+    if (!bus || typeof bus.emit !== "function" || typeof bus.on !== "function") {
+      warnOnce("event bus unavailable");
+      return Promise.resolve(false);
+    }
+    return new Promise((resolve) => {
+      const requestId = nextRequestId();
+      let settled = false;
+      let timer = null;
+      const finish = (answer) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        if (typeof unsubscribe === "function") unsubscribe();
+        unsubscribe = null;
+        resolve(answer);
+      };
+      try {
+        unsubscribe = bus.on(RESPONSE_CHANNEL, (frame) => {
+          if (!isResponseFor(frame, requestId)) return;
+          if (frame.ok !== true) {
+            warnOnce(`status query refused: ${String(frame.error ?? "unknown")}`);
+            finish(false);
+            return;
+          }
+          const tasks = frame.result?.tasks;
+          if (!Array.isArray(tasks)) {
+            warnOnce("status answer carried no task list");
+            finish(false);
+            return;
+          }
+          finish(tasks.some((task) => task?.status === LIVE_TASK_STATUS));
+        });
+        bus.emit(REQUEST_CHANNEL, {
+          schema_version: REQUEST_SCHEMA,
+          request_id: requestId,
+          operation: "status",
+          payload: {},
+        });
+      } catch (error) {
+        warnOnce(`status query failed: ${error.message}`);
+        finish(false);
+        return;
+      }
+      timer = setTimeout(() => {
+        warnOnce("status query timed out");
+        finish(false);
+      }, timeoutMs);
+      if (typeof timer?.unref === "function") timer.unref();
+    });
+  }
+
+  return {
+    installed: isInstalled,
+    running,
+    close() {
+      if (typeof unsubscribe === "function") unsubscribe();
+      unsubscribe = null;
+    },
+  };
+}