chainlesschain 0.162.160 → 0.162.162

package/src/gateways/ws/background-agent-protocol.js

@@ -8,17 +8,37 @@
  * Routes (request → reply):
  *   bg-list      {all?}            → {type:"bg-list", sessions}
  *   bg-view      {bgId, lines?}    → {type:"bg-view", session, log}
- *   bg-attach    {bgId, lines?}    → {type:"bg-attach", bgId, hello, log}
+ *   bg-attach    {bgId, lines?, sinceSeq?} → {type:"bg-attach", bgId, hello,
+ *                                    log, latestSeq, [reattached, replayed,
+ *                                    replayTruncated]}
  *   bg-prompt    {bgId, text}      → {type:"bg-prompt", bgId, sent}
  *   bg-stop-turn {bgId}            → {type:"bg-stop-turn", bgId, sent}
  *   bg-detach    {bgId}            → {type:"bg-detach", bgId}
  *   bg-stop      {bgId}            → {type:"bg-stop", session}   (kill whole session)
  *
- * While attached, the server pushes unsolicited frames to that client:
- *   {type:"bg-event", bgId, event}   worker lifecycle events (turn-started /
+ * While attached, the server pushes unsolicited frames to that client, each
+ * stamped with a per-attachment monotonic `seq` (additive; older clients
+ * ignore it) so the client can detect gaps and request a replay:
+ *   {type:"bg-event", bgId, seq, event}  worker lifecycle events (turn-started /
  *                                    turn-ended / idle / accepted / error /
  *                                    transport-closed)
- *   {type:"bg-log",   bgId, chunk}   log-file delta (500ms poll)
+ *   {type:"bg-log",   bgId, seq, chunk}  log-file delta (500ms poll)
+ *
+ * Reconnect resilience: a panel whose WS blipped re-sends bg-attach with the
+ * last `seq` it saw (`sinceSeq`); the still-live relay re-pushes the frames it
+ * missed (bounded buffer) and reports `latestSeq`. If the missed range was
+ * already evicted, `replayTruncated:true` tells the client to full-resync from
+ * the log. If the relay was fully torn down (WS closed → cleanup), the fresh
+ * attach returns hello + log tail as before and the client resets its tracker.
+ *
+ * Backpressure: if the WS client drains too slowly (ws.bufferedAmount over the
+ * high water), DROPPABLE frames (bg-log) are shed while CRITICAL ones (bg-event
+ * lifecycle) are always delivered. Dropped frames are still recorded (seq
+ * advances), so the gap on the next delivered frame trips the client's
+ * replaySince recovery. A one-shot {type:"bg-lag", bgId, lagging:true} marks
+ * the start and {type:"bg-lag", bgId, lagging:false, dropped, latestSeq} the
+ * recovery — the UI shows "catching up" instead of freezing. bg-lag frames
+ * carry no seq (out-of-band control; the gap tracker ignores them).
  *
  * The state file's `transport.token` is the local takeover capability — it is
  * NEVER sent over WS. Sessions are serialized with `interactive: true/false`
@@ -26,6 +46,12 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
+import { EventReplayBuffer } from "../../lib/event-seq-replay.js";
+import {
+  BackpressurePolicy,
+  CRITICAL,
+  DROPPABLE,
+} from "../../lib/backpressure-policy.js";
 
 const LOG_POLL_MS = 500;
 
@@ -139,6 +165,20 @@ export async function handleBgAttach(server, clientId, id, ws, message) {
     if (existing) {
       // Idempotent re-attach: reply with the live handshake instead of
       // stacking a second relay (a reconnecting panel re-sends bg-attach).
+      // If the panel reports the last seq it saw (`sinceSeq`), replay the
+      // push frames it missed while the WS was blipped — re-sent as normal
+      // bg-event/bg-log frames (their original seq), so the client's gap
+      // tracker sees a contiguous run. `replayTruncated` tells the client the
+      // hole predates our buffer and it must full-resync (re-read the log).
+      const sinceSeq = Number(message.sinceSeq);
+      let replayTruncated = false;
+      let replayed = 0;
+      if (Number.isFinite(sinceSeq)) {
+        const { frames, truncated } = existing.buffer.replaySince(sinceSeq);
+        replayTruncated = truncated;
+        replayed = frames.length;
+        for (const frame of frames) server._send(ws, frame);
+      }
       server._send(ws, {
         id,
         type: "bg-attach",
@@ -146,6 +186,9 @@ export async function handleBgAttach(server, clientId, id, ws, message) {
         hello: existing.hello,
         log: "",
         reattached: true,
+        latestSeq: existing.buffer.latestSeq,
+        replayed,
+        replayTruncated,
       });
       return;
     }
@@ -172,6 +215,42 @@ export async function handleBgAttach(server, clientId, id, ws, message) {
       );
     }
 
+    // Per-attachment replay buffer: stamps a monotonic seq on every push frame
+    // and retains a bounded tail so a reconnecting client can fill gaps
+    // (bg-attach { sinceSeq }). One buffer per relay instance — seq restarts
+    // at 1 on a fresh attach, so the client resets its tracker then.
+    const buffer = new EventReplayBuffer();
+    // Backpressure: if the WS client drains too slowly (ws.bufferedAmount grows
+    // past the high water), shed DROPPABLE frames (bg-log — recoverable) while
+    // still delivering CRITICAL ones (bg-event lifecycle). Dropped frames are
+    // still RECORDED (seq advances), so the seq gap on the next delivered frame
+    // trips the client's replaySince recovery; a one-shot bg-lag notice lets
+    // the UI show "catching up" instead of freezing. Buffer stays 0 in the
+    // normal case → byte-identical legacy behavior.
+    const backpressure = new BackpressurePolicy();
+    const bufferedBytes = () =>
+      ws && Number.isFinite(ws.bufferedAmount) ? ws.bufferedAmount : 0;
+    const pushFrame = (base, frameClass) => {
+      const frame = buffer.record(base); // record always → seq advances, replay recovers drops
+      const d = backpressure.evaluate(bufferedBytes(), frameClass);
+      if (d.lagStarted)
+        server._send(ws, { type: "bg-lag", bgId, lagging: true });
+      if (d.send) server._send(ws, frame);
+      if (d.lagEnded) {
+        server._send(ws, {
+          type: "bg-lag",
+          bgId,
+          lagging: false,
+          dropped: d.dropped,
+          latestSeq: buffer.latestSeq,
+        });
+      }
+    };
+    const pushEvent = (event) =>
+      pushFrame({ type: "bg-event", bgId, event }, CRITICAL);
+    const pushLog = (chunk) =>
+      pushFrame({ type: "bg-log", bgId, chunk }, DROPPABLE);
+
     const { connectBackgroundSession } =
       await import("../../lib/background-session-transport.js");
     let conn;
@@ -179,16 +258,10 @@ export async function handleBgAttach(server, clientId, id, ws, message) {
       conn = await connectBackgroundSession({
         pipePath: session.transport.pipe,
         token: session.transport.token,
-        onEvent: (event) => {
-          server._send(ws, { type: "bg-event", bgId, event });
-        },
+        onEvent: (event) => pushEvent(event),
         onClose: () => {
           if (dropAttachment(client, bgId)) {
-            server._send(ws, {
-              type: "bg-event",
-              bgId,
-              event: { type: "transport-closed" },
-            });
+            pushEvent({ type: "transport-closed" });
           }
         },
       });
@@ -212,7 +285,7 @@ export async function handleBgAttach(server, clientId, id, ws, message) {
         if (text.length > offset) {
           const chunk = text.slice(offset);
           offset = text.length;
-          server._send(ws, { type: "bg-log", bgId, chunk });
+          pushLog(chunk);
         }
       } catch {
         /* transient read failures skip one tick */
@@ -220,7 +293,7 @@ export async function handleBgAttach(server, clientId, id, ws, message) {
     }, LOG_POLL_MS);
     poll.unref?.();
 
-    attachments(client).set(bgId, { conn, poll, hello: conn.hello });
+    attachments(client).set(bgId, { conn, poll, hello: conn.hello, buffer });
     server._send(ws, {
       id,
       type: "bg-attach",
@@ -229,6 +302,7 @@ export async function handleBgAttach(server, clientId, id, ws, message) {
       log: readBackgroundAgentLog(bgId, {
         lines: Number(message.lines) || 100,
       }),
+      latestSeq: buffer.latestSeq,
     });
   } catch (err) {
     sendError(server, id, ws, "BG_ATTACH_FAILED", err.message);

package/src/lib/agent-authority.js

@@ -0,0 +1,251 @@
+/**
+ * Cross-agent authority envelope + approval binding (P0 security slice —
+ * CLAUDE_CODE_CLI_INCREMENTAL_GAP_ANALYSIS_2026-07-12 §"权限来源与跨 Agent
+ * 授权边界").
+ *
+ * When Subagent, Team, Remote Control, Inbound Channel, Hook and MCP all feed
+ * text into one session, "who said this" is a security boundary: another
+ * agent's "the user approved" MUST NOT gain the user's authority, and an
+ * external channel message MUST NOT silently widen the session's permissions.
+ *
+ * This module is the single source of truth for two invariants the runtime
+ * enforces at every trust seam:
+ *
+ *   1. **Who may approve.** Only the local user (UI-owned stdin), an explicit
+ *      permission tool, or a *paired + authenticated + approve-scoped* remote
+ *      device may answer a permission gate. Model / subagent / teammate /
+ *      channel / hook messages top out at `steer` — the string "approved" in
+ *      their payload is just text.
+ *
+ *   2. **What an approval authorizes.** An approval is bound to
+ *      `tool_call_id + normalized_arguments + policy_digest`. A replayed or
+ *      mis-routed approval, or one issued for arguments that have since
+ *      changed, fails the binding check — so a stale "yes" can never green-light
+ *      a different (or tampered) tool call.
+ *
+ * `origin` is always assigned by trusted dispatch code from HOW a message
+ * arrived (which socket / which authenticated device / which internal caller)
+ * — it is never read from untrusted message *content*, which is the whole
+ * point: a model cannot label its own text `origin:"user"`.
+ *
+ * Pure + dependency-light (only node:crypto) so every seam — remote-session
+ * protocol, channels, hooks, subagent dispatch — can share it.
+ */
+
+import { createHash, timingSafeEqual } from "node:crypto";
+
+/** Where a message / approval entered the runtime. Assigned by trusted code. */
+export const ORIGIN = Object.freeze({
+  USER: "user", // the human at the local UI (owns stdin)
+  MODEL: "model", // the assistant's own output
+  SUBAGENT: "subagent", // a spawned sub-agent
+  TEAMMATE: "teammate", // another agent in a team run
+  CHANNEL: "channel", // an inbound channel (webhook / telegram)
+  HOOK: "hook", // a settings/plugin hook result
+  REMOTE: "remote", // a paired remote-control device
+  SYSTEM: "system", // internal runtime event
+  PERMISSION_TOOL: "permission_tool", // an explicit permission-answering tool
+});
+
+/** What a message is allowed to do. Ordered least → most privileged. */
+export const AUTHORITY = Object.freeze({
+  NONE: "none", // ignored for control purposes
+  STEER: "steer", // may add a user turn / guide the conversation
+  APPROVE: "approve", // may answer a permission gate (approve/deny a tool)
+  MANAGE: "manage", // may also manage session lifecycle
+});
+
+const AUTHORITY_RANK = Object.freeze({
+  none: 0,
+  steer: 1,
+  approve: 2,
+  manage: 3,
+});
+
+/** Numeric rank for an authority string (unknown → 0). */
+export function authorityRank(authority) {
+  return AUTHORITY_RANK[authority] ?? 0;
+}
+
+/** Remote scopes that already imply the ability to answer a permission gate. */
+function scopeGrantsApprove(context) {
+  const scopes = normalizeScopes(context);
+  return scopes.has("approve") || scopes.has("manage");
+}
+
+function scopeGrantsSteer(context) {
+  const scopes = normalizeScopes(context);
+  return (
+    scopes.has("prompt") ||
+    scopes.has("interrupt") ||
+    scopes.has("observe") ||
+    scopeGrantsApprove(context)
+  );
+}
+
+function normalizeScopes(context = {}) {
+  const raw = Array.isArray(context.scopes)
+    ? context.scopes
+    : context.scope
+      ? [context.scope]
+      : [];
+  return new Set(raw.map((s) => String(s || "").toLowerCase()));
+}
+
+/**
+ * The MAXIMUM authority an origin may exercise given its authentication
+ * context. This is a ceiling — a caller still passes the specific action
+ * through `canApprove` / `assertCanApprove`.
+ *
+ * The only paths to `approve` are: the local user (`manage`), an explicit
+ * permission tool, or a remote device that is BOTH authenticated AND was
+ * granted the approve scope at pairing. Everything an agent or external
+ * message can say tops out at `steer`.
+ */
+export function authorityForOrigin(origin, context = {}) {
+  switch (origin) {
+    case ORIGIN.USER:
+      return AUTHORITY.MANAGE;
+    case ORIGIN.PERMISSION_TOOL:
+      return AUTHORITY.APPROVE;
+    case ORIGIN.REMOTE:
+      // A paired Remote Approval Bridge acts for the user ONLY when the pairing
+      // is authenticated AND carries the approve scope. Never on the strength
+      // of the message alone.
+      if (context.authenticated === true && scopeGrantsApprove(context)) {
+        return normalizeScopes(context).has("manage")
+          ? AUTHORITY.MANAGE
+          : AUTHORITY.APPROVE;
+      }
+      if (context.authenticated === true && scopeGrantsSteer(context)) {
+        return AUTHORITY.STEER;
+      }
+      return AUTHORITY.NONE;
+    case ORIGIN.MODEL:
+    case ORIGIN.SUBAGENT:
+    case ORIGIN.TEAMMATE:
+    case ORIGIN.CHANNEL:
+    case ORIGIN.HOOK:
+    case ORIGIN.SYSTEM:
+      // May guide the conversation, never speak with the user's approval
+      // authority. "The user approved" in their text is just text.
+      return AUTHORITY.STEER;
+    default:
+      return AUTHORITY.NONE;
+  }
+}
+
+/**
+ * True when this envelope may answer a permission gate. An envelope is
+ * `{ origin, authenticated?, scope?/scopes?, principalId?, sessionId?, … }`.
+ */
+export function canApprove(envelope = {}) {
+  return (
+    authorityRank(authorityForOrigin(envelope.origin, envelope)) >=
+    AUTHORITY_RANK.approve
+  );
+}
+
+/** True when this envelope may manage session lifecycle. */
+export function canManageSession(envelope = {}) {
+  return (
+    authorityRank(authorityForOrigin(envelope.origin, envelope)) >=
+    AUTHORITY_RANK.manage
+  );
+}
+
+/**
+ * Throw a clear, log-safe error when an envelope is NOT allowed to approve.
+ * Callers gate every "resolve a permission" seam through this so the rule
+ * lives in exactly one place.
+ */
+export function assertCanApprove(envelope = {}) {
+  if (canApprove(envelope)) return;
+  const who = envelope.origin || "unknown";
+  const got = authorityForOrigin(envelope.origin, envelope);
+  throw new Error(
+    `origin "${who}" (authority "${got}") is not authorized to approve tool calls — ` +
+      "only the local user, a paired approve-scoped remote device, or an explicit permission tool may",
+  );
+}
+
+// ── Approval binding ─────────────────────────────────────────────────────────
+
+/**
+ * Deterministic, key-order-independent serialization of tool arguments, so
+ * two structurally-equal argument objects hash identically and ANY real value
+ * change hashes differently. Non-objects serialize via JSON.
+ */
+export function normalizeToolArgs(args) {
+  return stableStringify(args === undefined ? null : args);
+}
+
+function stableStringify(value) {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value === undefined ? null : value);
+  }
+  if (Array.isArray(value)) {
+    return "[" + value.map(stableStringify).join(",") + "]";
+  }
+  const keys = Object.keys(value).sort();
+  return (
+    "{" +
+    keys
+      .map((k) => JSON.stringify(k) + ":" + stableStringify(value[k]))
+      .join(",") +
+    "}"
+  );
+}
+
+/**
+ * The identity an approval authorizes: the exact tool call (`toolCallId`), its
+ * normalized arguments, and the policy in force (`policyDigest`). Change any
+ * one and the digest changes, so a "yes" for one call can never be replayed
+ * onto another or onto tampered arguments.
+ */
+export function approvalBindingDigest({ toolCallId, args, policyDigest } = {}) {
+  const h = createHash("sha256");
+  h.update("cc-approval-binding-v1\n");
+  h.update(String(toolCallId ?? "") + "\n");
+  h.update(normalizeToolArgs(args) + "\n");
+  h.update(String(policyDigest ?? "") + "\n");
+  return "ab_" + h.digest("hex").slice(0, 32);
+}
+
+function timingSafeEqualStr(a, b) {
+  const ba = Buffer.from(String(a), "utf8");
+  const bb = Buffer.from(String(b), "utf8");
+  if (ba.length !== bb.length) return false;
+  return timingSafeEqual(ba, bb);
+}
+
+/**
+ * Verify an incoming approval targets the expected pending request. Each side
+ * may be a precomputed digest string or a `{toolCallId, args, policyDigest}`
+ * descriptor. Returns false on any mismatch or missing input (fail closed).
+ * Comparison is constant-time.
+ */
+export function verifyApprovalBinding(expected, provided) {
+  if (!expected || !provided) return false;
+  const e =
+    typeof expected === "string" ? expected : approvalBindingDigest(expected);
+  const p =
+    typeof provided === "string" ? provided : approvalBindingDigest(provided);
+  if (!e || !p) return false;
+  return timingSafeEqualStr(e, p);
+}
+
+/**
+ * A compact, log-safe provenance string for the permission/audit log so it is
+ * always clear WHICH principal, over WHICH session, with WHICH authority
+ * requested or answered a permission. Carries no secrets.
+ */
+export function describeAuthorityChain(envelope = {}) {
+  const parts = [`origin=${envelope.origin || "unknown"}`];
+  if (envelope.principalId) parts.push(`principal=${envelope.principalId}`);
+  if (envelope.sessionId) parts.push(`session=${envelope.sessionId}`);
+  if (envelope.parentAgentId) parts.push(`parent=${envelope.parentAgentId}`);
+  if (envelope.correlationId) parts.push(`corr=${envelope.correlationId}`);
+  parts.push(`authority=${authorityForOrigin(envelope.origin, envelope)}`);
+  return parts.join(" ");
+}

package/src/lib/agents.js

@@ -15,6 +15,21 @@
  *   model            model override for runs of this agent
  *   maxTurns         per-run iteration cap for this agent (positive integer)
  *   isolation        "worktree" → run in a fresh git worktree (gap 2026-07-11)
+ *   permission-mode  child permission mode (tighten-only vs parent)
+ *   skills           capability allow-list — skills the child may use
+ *   mcp-servers      capability allow-list — MCP servers the child may use
+ *   hooks            capability allow-list — hooks the child may run
+ *   memory           whether the child may read permanent memory
+ *   effort           reasoning effort (low|medium|high|xhigh)
+ *   background       run detached
+ *   context          "fresh" (default, isolated) | "fork" (inherit parent)
+ *   max-depth/max-children  ceilings this agent imposes on its own descendants
+ *   budget           { tokens, cost, time } caps
+ *
+ * The extended P1 contract (permission/skills/mcp/hooks/memory/effort/
+ * background/context/depth/children/budget) is normalized into a `contract`
+ * field via subagent-contract.js; the top-level tools/maxTurns/isolation are
+ * kept as-is for the existing spawn path.
  *
  * Project scope shadows personal on a name clash. Discovery + parse are pure
  * (inject fs/path/home) so the whole thing is unit-testable.
@@ -26,6 +41,7 @@ import { homedir } from "node:os";
 import yaml from "js-yaml";
 import { projectRootBase } from "./project-root.cjs";
 import { discoverPluginAgentLayers } from "./plugin-runtime/agents.js";
+import { normalizeSubagentContract } from "./subagent-contract.js";
 
 const _deps = { fs: fsDefault, path: pathDefault };
 
@@ -147,6 +163,9 @@ export function parseAgentFile(file, scope, opts = {}) {
     maxTurns:
       Number.isFinite(maxTurns) && maxTurns > 0 ? Math.floor(maxTurns) : null,
     isolation: data.isolation === "worktree" ? "worktree" : null,
+    // Extended P1 subagent contract (permission/skills/mcp/hooks/memory/effort/
+    // background/context/depth/children/budget), normalized + validated.
+    contract: normalizeSubagentContract(data),
     systemPrompt: body || "",
   };
 }

package/src/lib/background-agent-phase.js

@@ -0,0 +1,100 @@
+/**
+ * Background-agent phase vocabulary + dashboard grouping (P0 state-machine
+ * slice — CLAUDE_CODE_CLI_INCREMENTAL_GAP_ANALYSIS_2026-07-12 §"后台 Agent
+ * 状态机").
+ *
+ * A session has two orthogonal axes:
+ *   - `status` — running | completed | failed | stopped | lost — owned by the
+ *     supervisor's liveness reconciliation.
+ *   - `phase`  — the live sub-state WHILE running, persisted by the worker.
+ *
+ * Historically the worker only emitted "turn" (a turn is executing) and
+ * "idle" (between turns, transport open), and the dashboard mislabeled *idle*
+ * as "Needs input" — so an agent that had simply finished a turn and was
+ * parked shouted for attention it didn't need. Claude-Code's Agent View keeps
+ * these distinct (Working / Needs input / Idle / …).
+ *
+ * This module is the single source of truth that (a) names the fuller phase
+ * vocabulary the runtime is growing into and (b) classifies a session into a
+ * dashboard group, crucially separating `idle` (finished a turn, nothing
+ * blocking) from a genuine *needs-input* state (a human decision — a question
+ * or a pending permission — is blocking progress). Pure + zero-dependency so
+ * the worker, the supervisor and the REPL dashboard can all share it without a
+ * worker ever importing UI code.
+ */
+
+/**
+ * Canonical running sub-phases. `working`/`idle` are the steady states;
+ * `needs_input`/`waiting_permission` mark a turn that cannot advance without a
+ * human. `starting` is the brief pre-first-turn window.
+ */
+export const BACKGROUND_AGENT_PHASES = Object.freeze({
+  STARTING: "starting",
+  WORKING: "working",
+  IDLE: "idle",
+  NEEDS_INPUT: "needs_input",
+  WAITING_PERMISSION: "waiting_permission",
+});
+
+/**
+ * Aliases accepted from producers / older state schemas → canonical phase.
+ * The legacy worker emits "turn" for a live turn; map it to `working` so old
+ * on-disk states and new ones classify identically. Kebab and *_approval
+ * spellings are tolerated because different producers naturally reach for
+ * different casing.
+ */
+const PHASE_ALIASES = new Map([
+  ["turn", BACKGROUND_AGENT_PHASES.WORKING],
+  ["working", BACKGROUND_AGENT_PHASES.WORKING],
+  ["starting", BACKGROUND_AGENT_PHASES.STARTING],
+  ["idle", BACKGROUND_AGENT_PHASES.IDLE],
+  ["needs_input", BACKGROUND_AGENT_PHASES.NEEDS_INPUT],
+  ["needs-input", BACKGROUND_AGENT_PHASES.NEEDS_INPUT],
+  ["awaiting_input", BACKGROUND_AGENT_PHASES.NEEDS_INPUT],
+  ["question", BACKGROUND_AGENT_PHASES.NEEDS_INPUT],
+  ["waiting_permission", BACKGROUND_AGENT_PHASES.WAITING_PERMISSION],
+  ["waiting-permission", BACKGROUND_AGENT_PHASES.WAITING_PERMISSION],
+  ["waiting_approval", BACKGROUND_AGENT_PHASES.WAITING_PERMISSION],
+  ["awaiting_approval", BACKGROUND_AGENT_PHASES.WAITING_PERMISSION],
+]);
+
+/**
+ * Normalize a raw phase value to a canonical phase, or null when absent /
+ * unrecognized (callers treat null as "no declared phase"). Never throws.
+ */
+export function normalizeBackgroundAgentPhase(value) {
+  if (typeof value !== "string") return null;
+  return PHASE_ALIASES.get(value.trim().toLowerCase()) || null;
+}
+
+/** Phases where a human decision is blocking progress → "Needs input". */
+const BLOCKING_PHASES = new Set([
+  BACKGROUND_AGENT_PHASES.NEEDS_INPUT,
+  BACKGROUND_AGENT_PHASES.WAITING_PERMISSION,
+]);
+
+/**
+ * Dashboard group for a session. Running sessions split by phase:
+ *   - a pending approval OR a blocking phase (needs_input / waiting_permission)
+ *     → "needs-input" (a human decision unblocks it)
+ *   - "idle" (finished a turn, transport open, available but nothing blocking)
+ *     → "idle"
+ *   - everything else (working / turn / starting / unknown) → "working"
+ * Terminal statuses map to their own groups; lost/unknown → "failed".
+ *
+ * `pendingApprovals` wins over `phase` because an approval that is genuinely
+ * pending blocks progress regardless of the phase label the worker last wrote.
+ */
+export function phaseGroupKey(session) {
+  const status = session?.status;
+  if (status === "running") {
+    if (Number(session?.pendingApprovals) > 0) return "needs-input";
+    const phase = normalizeBackgroundAgentPhase(session?.phase);
+    if (BLOCKING_PHASES.has(phase)) return "needs-input";
+    if (phase === BACKGROUND_AGENT_PHASES.IDLE) return "idle";
+    return "working";
+  }
+  if (status === "completed") return "completed";
+  if (status === "stopped") return "stopped";
+  return "failed"; // failed | lost | unknown
+}