@jskit-ai/assistant-core 0.2.2 → 0.2.3

package/test/claudeProcess.test.js

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, rename, rm, writeFile } from "node:fs/promises";
 import os, { tmpdir } from "node:os";
 import path, { join } from "node:path";
 import { test } from "node:test";
@@ -29,6 +29,9 @@ test("native command construction preserves tool-free constraints without granti
   assert.deepEqual(JSON.parse(coding[coding.indexOf("--mcp-config") + 1]), { mcpServers: { application: { type: "sdk", name: "application" } } });
 });
 
+// Account queries whose credentials are not the subject read them from nowhere.
+const ABSENT_CLAUDE_CONFIG = join(tmpdir(), "jskit-absent-claude-config");
+
 async function fixture(t, body) {
   const directory = await mkdtemp(join(tmpdir(), "jskit-claude-process-"));
   t.after(() => rm(directory, { recursive: true, force: true }));
@@ -110,10 +113,10 @@ test("Claude model configuration maps background calls and resets external setti
 });
 
 test("Claude status reads native JSON and returns only public account details", async () => {
-  const status = await readClaudeCodeAuthStatus({ credentialHome: { home: "/home/fixture" }, commandRunner: async (input) => {
+  const status = await readClaudeCodeAuthStatus({ credentialHome: { home: "/home/fixture-json" }, commandRunner: async (input) => {
     assert.deepEqual(input.args, ["auth", "status", "--json"]);
     assert.equal(input.timeout, 30_000);
-    assert.equal(input.credentialHome.home, "/home/fixture");
+    assert.equal(input.credentialHome.home, "/home/fixture-json");
     return { ok: true, stdout: JSON.stringify({ loggedIn: true, email: "owner@example.test", authMethod: "claude.ai", subscriptionType: "max", accessToken: "not-public" }) };
   } });
   assert.equal(status.loggedIn, true);
@@ -122,8 +125,10 @@ test("Claude status reads native JSON and returns only public account details",
 });
 
 test("Claude signed-out JSON is normal while failed and malformed status responses stay errors", async () => {
+  // Reads of one account share an entry, so each response gets its own account.
+  let account = 0;
   const readStatus = (result) => readClaudeCodeAuthStatus({
-    credentialHome: { home: "/home/fixture" }, commandRunner: async () => result
+    credentialHome: { home: `/home/fixture-signed-out-${account += 1}` }, commandRunner: async () => result
   });
   const signedOut = { ok: false, exitCode: 1, stdout: JSON.stringify({ loggedIn: false, authMethod: "none" }) };
   assert.deepEqual(await readStatus(signedOut), {
@@ -144,7 +149,7 @@ test("Claude signed-out JSON is normal while failed and malformed status respons
   }
 });
 
-test("Claude status shares concurrent reads and invalidates when native account files change", async (t) => {
+test("Claude status shares one read per account and invalidates only when its credentials change", async (t) => {
   const home = await mkdtemp(path.join(os.tmpdir(), "claude-auth-status-"));
   t.after(() => rm(home, { recursive: true, force: true }));
   const configRoot = path.join(home, ".claude");
@@ -163,16 +168,32 @@ test("Claude status shares concurrent reads and invalidates when native account
     await readClaudeCodeAuthStatus(input);
     assert.equal(calls, 1);
   }
-  for (const file of [path.join(configRoot, ".credentials.json"), path.join(home, ".claude.json"), path.join(configRoot, ".claude.json")]) {
-    email = `${calls}@example.test`;
-    // Deliberately not JSON: the wrapper must never parse native credentials.
-    await writeFile(file, "native-account-changed");
-    assert.equal((await readClaudeCodeAuthStatus(input)).email, email);
-    await rm(file);
-    const before = calls;
+  // macOS reuses nothing: file metadata cannot show Keychain changes.
+  if (process.platform === "darwin") return;
+  // Claude Code rewrites .claude.json during ordinary turns: the account is unchanged.
+  for (const file of [path.join(home, ".claude.json"), path.join(configRoot, ".claude.json")]) {
+    await writeFile(file, "rewritten-during-a-turn");
     await readClaudeCodeAuthStatus(input);
-    assert.equal(calls, before + 1);
+    assert.equal(calls, 1, `${path.basename(path.dirname(file))}/.claude.json does not bust the read`);
   }
+  // Another command path and host runner reading the same account share its entry.
+  const otherRunner = async () => assert.fail("The same account is read once.");
+  await readClaudeCodeAuthStatus({ ...input, command: "/opt/other/bin/claude", commandRunner: otherRunner,
+    env: { ...input.env, PATH: "/opt/other/bin", HOME: home } });
+  assert.equal(calls, 1);
+  // Sign-in writes the credentials and sign-out removes them.
+  const credentials = path.join(configRoot, ".credentials.json");
+  email = "second@example.test";
+  // Deliberately not JSON: the wrapper must never parse native credentials.
+  await writeFile(credentials, "native-account-changed");
+  assert.equal((await readClaudeCodeAuthStatus(input)).email, email);
+  assert.equal(calls, 2);
+  await rm(credentials);
+  await readClaudeCodeAuthStatus(input);
+  assert.equal(calls, 3);
+  // A different identity variable is a different account.
+  await readClaudeCodeAuthStatus({ ...input, env: { ...input.env, CLAUDE_CODE_OAUTH_TOKEN: "fixture-token" } });
+  assert.equal(calls, 4);
 });
 
 test("Claude status failures do not poison later reads or share across credential homes", async () => {
@@ -182,15 +203,15 @@ test("Claude status failures do not poison later reads or share across credentia
     return calls === 1 ? { ok: false, error: "Temporary failure" }
       : { ok: true, stdout: JSON.stringify({ loggedIn: false }) };
   };
-  const input = { env: {}, credentialHome: { home: "/home/fixture" }, commandRunner };
+  const input = { env: {}, credentialHome: { home: "/home/fixture-failure" }, commandRunner };
   assert.equal((await readClaudeCodeAuthStatus(input)).error, "Temporary failure");
   assert.equal((await readClaudeCodeAuthStatus(input)).error, undefined);
   assert.equal(calls, 2);
-  await readClaudeCodeAuthStatus({ ...input, credentialHome: { home: "/home/another" } });
+  await readClaudeCodeAuthStatus({ ...input, credentialHome: { home: "/home/fixture-failure-another" } });
   assert.equal(calls, 3);
 });
 
-test("a Claude status read that cannot finish keeps Claude's recent answer for unchanged account files", {
+test("a Claude status answer holds until the credentials change, even across its own .claude.json rewrite", {
   skip: process.platform === "darwin"
 }, async (t) => {
   const home = await mkdtemp(path.join(os.tmpdir(), "claude-auth-status-"));
@@ -199,44 +220,45 @@ test("a Claude status read that cannot finish keeps Claude's recent answer for u
   let now = realNow();
   Date.now = () => now;
   t.after(() => { Date.now = realNow; });
+  const configRoot = path.join(home, ".claude");
+  await mkdir(configRoot);
+  const credentials = path.join(configRoot, ".credentials.json");
+  await writeFile(credentials, "signed-in");
   const signedIn = { ok: true, stdout: JSON.stringify({ loggedIn: true, email: "owner@example.test", authMethod: "claude.ai" }) };
-  const signedInStatus = { loggedIn: true, email: "owner@example.test", authMethod: "claude.ai", subscriptionType: "" };
-  const timedOut = { ok: false, exitCode: 1, timedOut: true, error: "Command timed out." };
   let calls = 0;
   let result = signedIn;
-  const input = { env: { CLAUDE_CONFIG_DIR: path.join(home, ".claude") }, credentialHome: { home },
-    commandRunner: async () => { calls += 1; return result; } };
+  const input = { env: { CLAUDE_CONFIG_DIR: configRoot }, credentialHome: { home }, commandRunner: async () => {
+    calls += 1;
+    // Each native status run rewrites ~/.claude.json a few seconds later.
+    await writeFile(path.join(home, ".claude.json"), `status-run-${calls}`);
+    return result;
+  } };
   assert.equal((await readClaudeCodeAuthStatus(input)).email, "owner@example.test");
-  // An overloaded host times the next read out, or refuses to start it for now.
-  for (const unfinished of [timedOut, { ok: false, exitCode: 1, retryable: true, error: "Memory-pressure spike." }]) {
-    now += 31_000;
-    result = unfinished;
-    assert.deepEqual(await readClaudeCodeAuthStatus(input), signedInStatus);
-  }
-  // That answer is reused for the normal window, so the busy host is not probed again at once.
-  const probes = calls;
+  now += 10 * 60_000;
+  assert.equal((await readClaudeCodeAuthStatus(input)).email, "owner@example.test");
+  assert.equal(calls, 1, "the answer is not read again on a timer or after the run's own rewrite");
+  // Sign-out removes the credentials: Claude is asked again at once.
+  await rm(credentials);
+  result = { ok: false, exitCode: 1, stdout: JSON.stringify({ loggedIn: false }) };
+  assert.equal((await readClaudeCodeAuthStatus(input)).loggedIn, false);
+  assert.equal(calls, 2);
+  // A read the host timed out is reported and not asked again at once.
+  await writeFile(credentials, "signed-in-again");
+  result = { ok: false, exitCode: 1, timedOut: true, error: "Command timed out." };
+  assert.equal((await readClaudeCodeAuthStatus(input)).error, "Command timed out.");
   now += 29_000;
-  assert.deepEqual(await readClaudeCodeAuthStatus(input), signedInStatus);
-  assert.equal(calls, probes);
-  // A read that ran and failed is still reported.
+  assert.equal((await readClaudeCodeAuthStatus(input)).error, "Command timed out.");
+  assert.equal(calls, 3);
+  // A read that ran and failed is reported, and asked again next time.
   now += 2_000;
   result = { ok: false, exitCode: 2, error: "Claude Code crashed." };
   assert.equal((await readClaudeCodeAuthStatus(input)).error, "Claude Code crashed.");
-  // Changed account files need Claude's own new answer.
-  await mkdir(path.join(home, ".claude"));
-  await writeFile(path.join(home, ".claude", ".credentials.json"), "native-account-changed");
-  result = timedOut;
-  assert.equal((await readClaudeCodeAuthStatus(input)).error, "Command timed out.");
-  // The recent answer expires: an old one is not kept forever.
-  now += 31_000;
   result = signedIn;
   assert.equal((await readClaudeCodeAuthStatus(input)).loggedIn, true);
-  now += 5 * 60_000 + 1;
-  result = timedOut;
-  assert.equal((await readClaudeCodeAuthStatus(input)).error, "Command timed out.");
+  assert.equal(calls, 5);
 });
 
-test("an unfinished Claude status read with no recent answer is reported without probing again at once", {
+test("an unfinished Claude status read is reported without probing again at once", {
   skip: process.platform === "darwin"
 }, async (t) => {
   const realNow = Date.now;
@@ -535,13 +557,18 @@ test("Claude account queries isolate concurrent identities and deduplicate each
   for (const method of ["readCatalogue", "readPlanUsage"]) {
     const pending = new Map(["first", "second"].map(id => [id, Promise.withResolvers()]));
     const calls = [];
+    const native = id => ({ command: process.execPath, async stop() { return { scopeEmpty: true }; },
+      get initialization() { calls.push(id); return pending.get(id).promise; },
+      client: { request() { calls.push(id); return pending.get(id).promise; } } });
+    // Plan usage borrows each account's conversation; the model list starts its own Claude.
+    const starting = ["first", "second"];
     const queries = createClaudeAccountQueries({
-      accountIdentity: async context => context.id,
-      processes: () => [...pending].map(([id, held]) => ({ accountIdentity: id, process: {
-        get initialization() { calls.push(id); return held.promise; },
-        client: { request() { calls.push(id); return held.promise; } }
-      } })),
-      createProcess() { throw new Error("An owned account process should be reused."); }
+      accountIdentity: async context => context.id, configRoot: ABSENT_CLAUDE_CONFIG,
+      processes: () => method === "readPlanUsage" ? starting.map(id => ({ accountIdentity: id, process: native(id) })) : [],
+      createProcess() {
+        if (method === "readPlanUsage") throw new Error("An owned account process should be reused.");
+        return native(starting.shift());
+      }
     });
     const first = queries[method]({ id: "first" });
     const duplicate = queries[method]({ id: "first" });
@@ -683,15 +710,131 @@ test("Claude plan usage starts one temporary Claude per idle interval and marks
   await queries.invalidate();
 });
 
+test("Claude plan usage starts one temporary Claude per account for every owner polling it", async (t) => {
+  const realNow = Date.now;
+  let now = Date.parse("2026-10-29T03:00:00Z");
+  Date.now = () => now;
+  t.after(() => { Date.now = realNow; });
+  const starts = [];
+  let stops = 0;
+  // Three account-query owners in one server process, none with a live conversation.
+  const owners = ["first", "second", "third"].map(owner => createClaudeAccountQueries({
+    accountIdentity: async context => context.account,
+    createProcess(input) {
+      starts.push([owner, input.purpose]);
+      return { client: { request: async () => ({ rate_limits_available: true, rate_limits: {
+        seven_day: { utilization: 23, resets_at: "2026-11-04T05:00:00Z" }, limits: [] } }) },
+      async stop() { stops++; return { scopeEmpty: true }; } };
+    }
+  }));
+  t.after(() => Promise.all(owners.map(queries => queries.invalidate())));
+  const account = { account: "plan-usage-shared-across-owners" };
+  // Requests that arrive while the account is read share that one read.
+  const concurrent = await Promise.all(owners.map(queries => queries.readPlanUsage(account)));
+  assert.deepEqual(starts, [["first", "usage"]]);
+  for (const reading of concurrent) assert.deepEqual(reading, concurrent[0]);
+  assert.equal(concurrent[0].windows[0].remainingPercent, 77);
+  // An hour of every owner polling once a minute.
+  for (let minute = 1; minute < 60; minute++) {
+    now += 60_000;
+    for (const queries of owners) assert.equal((await queries.readPlanUsage(account)).status, "available");
+  }
+  assert.equal(starts.length, 12, "the account started more than one temporary Claude per idle interval");
+  assert.equal(stops, starts.length, "a temporary usage process outlived its read");
+  // Another account is read on its own.
+  await owners[1].readPlanUsage({ account: "plan-usage-another-account" });
+  assert.equal(starts.length, 13);
+});
+
+test("Claude plan usage reuses another owner's live reading instead of starting a temporary Claude", async (t) => {
+  const realNow = Date.now;
+  let now = Date.parse("2026-10-29T03:00:00Z");
+  Date.now = () => now;
+  t.after(() => { Date.now = realNow; });
+  const account = "plan-usage-live-in-another-owner";
+  const answer = { rate_limits_available: true, rate_limits: {
+    seven_day: { utilization: 23, resets_at: "2026-11-04T05:00:00Z" }, limits: [] } };
+  let liveReads = 0;
+  const starts = [];
+  const createProcess = () => {
+    starts.push("usage");
+    return { client: { request: async () => answer }, async stop() { return { scopeEmpty: true }; } };
+  };
+  const withConversation = createClaudeAccountQueries({ accountIdentity: async () => account, createProcess,
+    processes: () => [{ accountIdentity: account, process: { client: { request: async () => { liveReads++; return answer; } } } }] });
+  const idle = createClaudeAccountQueries({ accountIdentity: async () => account, createProcess });
+  t.after(() => Promise.all([withConversation.invalidate(), idle.invalidate()]));
+  const live = await withConversation.readPlanUsage({});
+  assert.equal(liveReads, 1);
+  // Only the idle owner's page stays open: the account's verified reading serves it
+  // until that reading is an idle interval old.
+  for (let minute = 1; minute <= 4; minute++) {
+    now += 60_000;
+    const reading = await idle.readPlanUsage({});
+    assert.equal(reading.checkedAt, live.checkedAt);
+    assert.equal(reading.status, "available");
+  }
+  assert.deepEqual(starts, [], "a temporary Claude started while the account had a recent verified reading");
+  now += 60_000;
+  await idle.readPlanUsage({});
+  assert.deepEqual(starts, ["usage"]);
+});
+
+test("Claude model list starts a Claude only after its account, credentials or Claude Code changed", async (t) => {
+  const root = await mkdtemp(join(tmpdir(), "jskit-claude-catalogue-"));
+  t.after(() => rm(root, { recursive: true, force: true }));
+  const configRoot = join(root, ".claude");
+  await mkdir(configRoot);
+  // Sign-in, a token refresh and an update each replace the file at a stable path.
+  const replace = async (file, contents) => {
+    await writeFile(`${file}.next`, contents);
+    await rename(`${file}.next`, file);
+  };
+  const credentials = join(configRoot, ".credentials.json");
+  const command = join(root, "claude");
+  await replace(credentials, "signed in");
+  await replace(command, "2.1.1");
+  const realNow = Date.now;
+  let now = realNow();
+  Date.now = () => now;
+  t.after(() => { Date.now = realNow; });
+  let account = "account";
+  const starts = [];
+  const queries = createClaudeAccountQueries({ accountIdentity: async () => account, configRoot,
+    // A conversation that started before every change below.
+    processes: () => [{ accountIdentity: account, process: { command, initialization: { models: [{ value: "live" }] } } }],
+    createProcess({ purpose }) {
+      starts.push(purpose);
+      return { command, initialization: { models: [{ value: `read-${starts.length}` }] },
+        async stop() { return { scopeEmpty: true }; } };
+    } });
+  const model = async () => (await queries.readCatalogue({})).models[0].value;
+  // Reconnects, tab returns and closed sessions ask about four times an hour.
+  const askForADay = async (expected) => {
+    for (let read = 0; read < 96; read++, now += 15 * 60_000) assert.equal(await model(), expected);
+  };
+  await askForADay("read-1");
+  assert.deepEqual(starts, ["catalogue"]);
+  await replace(credentials, "refreshed");
+  await askForADay("read-2");
+  await replace(command, "2.1.2");
+  await askForADay("read-3");
+  account = "other account";
+  await askForADay("read-4");
+  assert.deepEqual(starts, ["catalogue", "catalogue", "catalogue", "catalogue"]);
+  await queries.invalidate();
+  assert.equal(await model(), "read-5");
+});
+
 test("Claude account queries label temporary startup and reuse each account's recent reading", async () => {
   const starts = [];
   let stops = 0;
   const queries = createClaudeAccountQueries({
-    accountIdentity: async () => "private-account-identity",
+    accountIdentity: async () => "private-account-identity", configRoot: ABSENT_CLAUDE_CONFIG,
     createProcess(input) {
       starts.push(input);
       return {
-        initialization: { models: [] },
+        initialization: { models: [] }, command: process.execPath,
         client: { request: async () => ({ rate_limits_available: false }) },
         async stop() { stops++; return { scopeEmpty: true }; }
       };
@@ -753,10 +896,11 @@ for (const method of ["readCatalogue", "readPlanUsage"]) {
         // Usage reads count as native reads of the borrowed conversation process.
         processes: () => method === "readPlanUsage" ? [{ accountIdentity: "account", process: { client: {
           request: async () => { starts++; return { rate_limits_available: true, rate_limits: { limits: [] } }; } } } }] : [],
+        configRoot: ABSENT_CLAUDE_CONFIG,
         createProcess() {
           starts++;
           return {
-            initialization: { models: [{ value: `model-${starts}` }] },
+            initialization: { models: [{ value: `model-${starts}` }] }, command: process.execPath,
             client: { request: async () => ({ rate_limits_available: true, rate_limits: {} }) },
             async stop() {
               stops++;

package/test/claudeTurn.test.js

@@ -579,6 +579,16 @@ test("a native error result is failure information rather than an assistant answ
   assert.equal(events.some(event => event.type === "message"), false);
 });
 
+test("a turn whose account signed out ends at once with the not-connected message", async () => {
+  const { turn, send } = fixture();
+  await send();
+  // Claude Code's own answer when its credentials were removed under it.
+  await turn.receive({ type: "result", subtype: "success", is_error: true, result: "Not logged in · Please run /login" });
+  assert.equal(turn.read().active, false);
+  assert.equal(turn.read().status, "failed");
+  assert.equal(turn.read().error, "Claude isn't connected. Sign in to Claude, then send your message again.");
+});
+
 function renewalFixture() {
   const input = { clientMessageId: "renewal-operation", prompt: "Approved prompt", timeoutMs: 100 };
   const uuid = claudeNativeMessageId(input.clientMessageId);
@@ -926,15 +936,50 @@ test("Claude status retains active instructions and applies changed guidance onc
   assert.equal(f.processes.length, 2, "Idle readiness installs the changed instructions");
 });
 
-test("Claude active status still rejects account replacement", async t => {
+test("Claude active status keeps a running turn across an account change; idle admission applies it", async t => {
   const f = await publishedClaudeFixture(t);
   await f.send();
+  const running = f.entry.process;
   f.behavior.account = "account-b";
+  const state = await f.owner.ensureReady(f.entry);
+  assert.equal(state.turn.active, true);
+  assert.equal(f.entry.process, running, "the running turn keeps its process");
+  await f.frame({ type: "result", subtype: "success", result: "Done" });
+  // Once idle, the existing account guard applies.
   await assert.rejects(f.owner.ensureReady(f.entry), { code: "claude_account_changed" });
   assert.equal(f.entry.process, null);
 });
 
-test("Claude account change stops running processes without reopening saved conversations", async t => {
+test("Claude account change stops and waits on nothing; a running turn keeps its process", async t => {
+  const f = await publishedClaudeFixture(t);
+  f.context.sessionId = "session-a";
+  await f.send();
+  const running = f.entry.process;
+  const touched = [];
+  const application = {
+    readContext: async () => { touched.push("read-context"); throw new Error("A saved conversation was reopened"); },
+    terminals: { close: async sessionId => { touched.push(`close-terminals:${sessionId}`); return { ok: true, closed: 0 }; } }
+  };
+  // Cancelled account reads are still settling; the change must not wait for them.
+  const reads = Promise.withResolvers();
+  let invalidated = 0;
+  let returned = false;
+  const change = f.owner.invalidateRuntimes({ provider: "claude", reason: "claude-auth-change" }, application,
+    { queries: { invalidate: () => { invalidated++; return reads.promise; } }, failure: error => { throw error; } });
+  void change.then(() => { returned = true; });
+  await new Promise(resolve => setImmediate(resolve));
+  assert.equal(returned, true, "the change returned without waiting for the cancelled account reads");
+  reads.resolve();
+  assert.deepEqual(await change, { ok: true, closed: 0 });
+  assert.equal(invalidated, 1, "the account's cached reads were dropped");
+  assert.deepEqual(touched, [], "no terminal closed and no saved conversation reopened");
+  assert.equal(f.entry.process, running, "the running process was not stopped");
+  assert.equal(f.entry.turn.active, true, "the running turn continues");
+  await f.frame({ type: "result", subtype: "success", result: "Done" });
+  assert.equal(f.entry.turn.state, "completed", "the turn finishes normally");
+});
+
+test("Claude server shutdown stops running processes without reopening saved conversations", async t => {
   const f = await publishedClaudeFixture(t);
   f.context.sessionId = "session-a";
   await f.send();
@@ -944,7 +989,7 @@ test("Claude account change stops running processes without reopening saved conv
     readContext: async () => { throw new Error("A saved conversation was reopened"); },
     terminals: { close: async sessionId => { closedTerminals.push(sessionId); return { ok: true, closed: 0 }; } }
   };
-  const result = await f.owner.invalidateRuntimes({ provider: "claude", reason: "claude-auth-change" }, application,
+  const result = await f.owner.invalidateRuntimes({ reason: "server-shutdown" }, application,
     { queries: { invalidate: async () => {} }, failure: error => { throw error; } });
   assert.equal(result.ok, true);
   assert.equal(f.entry.process, null, "the running process stopped");
@@ -1871,6 +1916,97 @@ test("consecutive steers queue together without waiting for or sending an interr
   assert.deepEqual(events.filter(event => event.type === "diagnostic" && event.stage === "steering_queued").length, 2);
 });
 
+// Claude Code reads a queued message only when the running tool call returns. A
+// foreground wait (`until …; do sleep 20; done`) held a person's question for ten
+// minutes, so a waiting steer moves foreground work to the background instead.
+function steeringFixture() {
+  const f = fixture();
+  const requests = [];
+  f.client.interrupt = async () => assert.fail("Steering never interrupts");
+  f.client.request = async request => { requests.push(request); return {}; };
+  // Claude Code acknowledges streamed input as queued; the replay comes when it reads it.
+  f.client.send = async (_message, { messageId }) => {
+    await f.turn.receive({ type: "command_lifecycle", command_uuid: messageId, state: "queued" });
+  };
+  async function read(id) {
+    const uuid = claudeNativeMessageId(id);
+    await f.turn.receive({ type: "command_lifecycle", command_uuid: uuid, state: "started" });
+    await f.turn.receive({ type: "user", uuid });
+  }
+  return { ...f, requests, read };
+}
+
+test("a steer queued behind a running command asks Claude to background it, never to interrupt it", async () => {
+  const { turn, send, read, requests, events } = steeringFixture();
+  await send();
+  await read("first");
+  await turn.receive({ type: "assistant", uuid: "wait-call", message: { id: "wait-api", stop_reason: "tool_use",
+    content: [{ type: "tool_use", id: "wait", name: "Bash", input: { command: "until grep -q done out; do sleep 20; done" } }] } });
+  await turn.receive({ type: "system", subtype: "task_started", task_id: "wait-task" });
+  assert.deepEqual(requests, [], "A first message and its commands stay in the foreground");
+  await turn.prepareSteering();
+  await send("question", { steer: true });
+  await delay(0);
+  assert.deepEqual(requests, [{ subtype: "background_tasks" }]);
+  assert.equal(events.filter(event => event.type === "diagnostic" && event.stage === "steering_backgrounded").length, 1);
+  await turn.receive({ type: "user", uuid: "wait-result", message: { content: [{ type: "tool_result", tool_use_id: "wait",
+    content: "Command was manually backgrounded by user with ID: wait-task." }] } });
+  await read("question");
+  await turn.receive({ type: "system", subtype: "task_started", task_id: "later-task" });
+  await delay(0);
+  assert.equal(requests.length, 1, "A message Claude has read no longer moves work");
+  turn.stop();
+});
+
+test("a steer still waiting when Claude starts another command backgrounds that command too", async () => {
+  const { turn, send, read, requests } = steeringFixture();
+  await send();
+  await read("first");
+  // The person writes while Claude is choosing its next tool: nothing runs yet.
+  await turn.prepareSteering();
+  await send("question", { steer: true });
+  await turn.receive({ type: "system", subtype: "task_started", task_id: "new-wait" });
+  await delay(0);
+  assert.deepEqual(requests, [{ subtype: "background_tasks" }, { subtype: "background_tasks" }]);
+  await read("question");
+  turn.stop();
+});
+
+test("a steer during Claude's follow-up to a finished background task moves that follow-up's command", async () => {
+  const { turn, send, read, requests } = steeringFixture();
+  await send();
+  await read("first");
+  await turn.receive({ type: "system", subtype: "task_started", task_id: "verify" });
+  await turn.receive({ type: "result", subtype: "success", result: "Verification runs in the background." });
+  await turn.receive({ type: "command_lifecycle", command_uuid: claudeNativeMessageId("first"), state: "completed" });
+  assert.deepEqual([turn.read().phase, turn.read().pendingCommands], ["background", 0]);
+  // Claude reads the task notification and starts waiting in the foreground.
+  await turn.receive({ type: "system", subtype: "task_notification", task_id: "verify", status: "completed" });
+  await turn.receive({ type: "system", subtype: "task_started", task_id: "follow-up-wait" });
+  assert.deepEqual(requests, []);
+  await turn.prepareSteering();
+  await send("question", { steer: true });
+  await delay(0);
+  assert.deepEqual(requests, [{ subtype: "background_tasks" }]);
+  await read("question");
+  turn.stop();
+});
+
+test("a refused background request leaves the steer delivered and reports it", async () => {
+  const { turn, send, read, requests, client, events } = steeringFixture();
+  await send();
+  await read("first");
+  client.request = async request => { requests.push(request); throw new Error("Unsupported control request: background_tasks"); };
+  await turn.prepareSteering();
+  await send("question", { steer: true });
+  await delay(0);
+  assert.deepEqual(requests, [{ subtype: "background_tasks" }]);
+  assert.equal(turn.read().pendingCommands, 2, "The steer stays delivered and queued for Claude");
+  const failed = events.find(event => event.type === "diagnostic" && event.stage === "steering_background_failed");
+  assert.equal(failed?.error, "Unsupported control request: background_tasks");
+  turn.stop();
+});
+
 test("folded internal command preserves the original published answer owner", async t => {
   const f = await publishedClaudeFixture(t);
   await f.send();
@@ -2305,6 +2441,41 @@ for (const action of ["steer", "set", "resume"]) test(`Claude ${action} queues a
   assert.equal(f.entry.nativeTurn.read().active, false, "The main response settles the completed worker's turn");
 });
 
+for (const action of ["steer", "set", "resume"]) test(`Claude ${action} moves a running command to the background so Claude reads it at once`, async t => {
+  const f = await publishedClaudeFixture(t);
+  if (action === "resume") await f.owner.updateGoal(f.entry, { action: "set", objective: "Finish checks", messageId: "first" });
+  else await f.send("first");
+  await f.frame({ type: "assistant", uuid: "wait-call", message: { id: "wait-api", stop_reason: "tool_use",
+    content: [{ type: "tool_use", id: "wait", name: "Bash", input: { command: "until grep -q done out; do sleep 20; done" } }] } });
+  const native = f.entry.process;
+  const requests = [];
+  native.client.request = async request => { requests.push(request); return {}; };
+  native.client.interrupt = async () => assert.fail("A steer must not send Stop");
+  const send = native.client.send;
+  const queued = Promise.withResolvers();
+  // Claude Code 2.1.308 acknowledges the input as queued while the wait loop runs.
+  native.client.send = async (message, input) => {
+    await f.frame({ type: "command_lifecycle", command_uuid: input.messageId, state: "queued" });
+    queued.resolve({ message, input });
+  };
+  const goal = action === "steer" ? null : (await f.owner.readGoal(f.entry)).goal;
+  const delivering = action === "steer" ? f.send("next") : f.owner.updateGoal(f.entry, { action, objective: "Finish checks",
+    messageId: "next", ...(action === "resume" ? { threadId: f.conversationId, createdAt: goal.createdAt } : {}) });
+  const { message, input } = await queued.promise;
+  await delay(0);
+  assert.deepEqual(requests, [{ subtype: "background_tasks" }]);
+  assert.equal(f.processes.length, 1, "The running process and its command are kept");
+  // The wait loop returns as backgrounded; Claude then reads the queued input.
+  await f.frame({ type: "user", uuid: "wait-result", message: { content: [{ type: "tool_result", tool_use_id: "wait",
+    content: "Command was manually backgrounded by user with ID: wait-task." }] } });
+  await f.frame({ type: "command_lifecycle", command_uuid: input.messageId, state: "started" });
+  await send(message, input);
+  await delivering;
+  await f.frame({ type: "system", subtype: "task_started", task_id: "wait-task" });
+  await delay(0);
+  assert.equal(requests.length, 1, "Once Claude reads the input, later commands stay in the foreground");
+});
+
 test("Claude context inspection reuses the native owner and reports the selected model's current usage", async t => {
   const f = await publishedClaudeFixture(t);
   const requests = [];