chainlesschain 0.162.160 → 0.162.161

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/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
+}

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

@@ -16,11 +16,167 @@ import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { getHomeDir } from "./paths.js";
 
-export const _deps = { spawn, spawnSync };
-
 export const DEFAULT_HEARTBEAT_INTERVAL_MS = 5000;
 export const DEFAULT_HEARTBEAT_STALE_MS = 120000;
 
+/**
+ * Pid identity tolerance (Gap 1: OS pid reuse). A pid alone does not identify
+ * a process — after the worker dies the OS can hand the same pid to an
+ * unrelated process, making `kill(pid, 0)` lie: the session shows "running"
+ * until the heartbeat goes stale and, far worse, `stopBackgroundAgent` would
+ * `taskkill /T /F` an innocent process tree. The state file records
+ * `startedAt` (launcher clock, written just before the spawn), so we compare
+ * it against the pid's REAL creation time. Reuse is one-sided: a process
+ * that took over the pid can only have been created AFTER the original
+ * worker died — i.e. noticeably later than startedAt. Creation at/before
+ * startedAt (± tolerance for clock skew and spawn latency) is our process.
+ */
+export const PID_IDENTITY_TOLERANCE_MS = 60000;
+
+const START_TIME_CACHE_TTL_MS = 10000;
+const _startTimeCache = new Map();
+
+/** CIM_DATETIME (`20260711120000.500000+480`) → epoch ms, null when unparseable. */
+export function parseCimDateToMs(raw) {
+  const m =
+    /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})\.(\d{6})([+-])(\d{3})$/.exec(
+      String(raw || "").trim(),
+    );
+  if (!m) return null;
+  const localAsUtc = Date.UTC(
+    Number(m[1]),
+    Number(m[2]) - 1,
+    Number(m[3]),
+    Number(m[4]),
+    Number(m[5]),
+    Number(m[6]),
+    Math.floor(Number(m[7]) / 1000),
+  );
+  const offsetMinutes = (m[8] === "-" ? -1 : 1) * Number(m[9]);
+  return localAsUtc - offsetMinutes * 60000;
+}
+
+/**
+ * Read a process's creation time (epoch ms) with ONE synchronous probe, or
+ * null when it cannot be determined (missing tools, permissions, platform
+ * quirks). Callers must treat null as "unknown" and FAIL OPEN to the legacy
+ * kill(pid, 0) answer — a broken probe must never declare a live worker dead
+ * (nor green-light killing a process we could not identify as ours; see the
+ * per-call-site policy).
+ */
+function defaultReadProcessStartTimeMs(pid) {
+  const target = Number(pid);
+  if (!Number.isInteger(target) || target <= 0) return null;
+  if (process.platform === "win32") {
+    // wmic first (fast, ~100-300ms); PowerShell CIM as fallback (wmic is
+    // removed from recent Windows 11 builds).
+    try {
+      const r = spawnSync(
+        "wmic",
+        [
+          "process",
+          "where",
+          `ProcessId=${target}`,
+          "get",
+          "CreationDate",
+          "/value",
+        ],
+        { windowsHide: true, encoding: "utf8", timeout: 5000 },
+      );
+      if (!r.error && r.status === 0) {
+        const m = /CreationDate=([^\r\n]+)/.exec(r.stdout || "");
+        const ms = m ? parseCimDateToMs(m[1]) : null;
+        if (ms !== null) return ms;
+      }
+    } catch {
+      /* fall through to PowerShell */
+    }
+    try {
+      const script =
+        `$p = Get-CimInstance Win32_Process -Filter 'ProcessId=${target}' -ErrorAction SilentlyContinue; ` +
+        "if ($p -and $p.CreationDate) { [DateTimeOffset]::new($p.CreationDate).ToUnixTimeMilliseconds() }";
+      const r = spawnSync(
+        "powershell",
+        ["-NoProfile", "-NonInteractive", "-Command", script],
+        { windowsHide: true, encoding: "utf8", timeout: 10000 },
+      );
+      if (!r.error && r.status === 0) {
+        const n = Number(String(r.stdout || "").trim());
+        if (Number.isFinite(n) && n > 0) return n;
+      }
+    } catch {
+      /* fail open below */
+    }
+    return null;
+  }
+  // POSIX: `ps -o lstart=` gives an absolute start timestamp on Linux + macOS
+  // (procps and BSD ps both support it; busybox ps does not → null → open).
+  try {
+    const r = spawnSync("ps", ["-o", "lstart=", "-p", String(target)], {
+      encoding: "utf8",
+      timeout: 5000,
+    });
+    if (!r.error && r.status === 0) {
+      const t = Date.parse(String(r.stdout || "").trim());
+      if (Number.isFinite(t) && t > 0) return t;
+    }
+  } catch {
+    /* fail open below */
+  }
+  return null;
+}
+
+/**
+ * Kill a whole process tree (Gap 2 orphan reclaim). Windows: `taskkill /T`.
+ * POSIX: negative-pid group signal (the worker spawns the agent child
+ * detached → its own group), falling back to a direct kill.
+ */
+function defaultKillProcessTree(pid, signal = "SIGKILL") {
+  const target = Number(pid);
+  if (!Number.isInteger(target) || target <= 0) return false;
+  try {
+    if (process.platform === "win32") {
+      const r = spawnSync("taskkill", ["/PID", String(target), "/T", "/F"], {
+        windowsHide: true,
+        encoding: "utf8",
+      });
+      return !r.error && r.status === 0;
+    }
+    try {
+      process.kill(-target, signal);
+      return true;
+    } catch {
+      process.kill(target, signal);
+      return true;
+    }
+  } catch {
+    return false;
+  }
+}
+
+export const _deps = {
+  spawn,
+  spawnSync,
+  readProcessStartTimeMs: defaultReadProcessStartTimeMs,
+  killProcessTree: defaultKillProcessTree,
+};
+
+/** Cached probe (default impl only — injected probes run uncached for tests). */
+function processStartTimeMs(pid) {
+  if (_deps.readProcessStartTimeMs !== defaultReadProcessStartTimeMs) {
+    const raw = _deps.readProcessStartTimeMs(pid);
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : null;
+  }
+  const key = Number(pid);
+  const at = Date.now();
+  const hit = _startTimeCache.get(key);
+  if (hit && at - hit.at < START_TIME_CACHE_TTL_MS) return hit.value;
+  const value = defaultReadProcessStartTimeMs(key);
+  _startTimeCache.set(key, { at, value });
+  return value;
+}
+
 function nowMs(options = {}) {
   return typeof options.now === "number" ? options.now : Date.now();
 }
@@ -136,6 +292,55 @@ export function isProcessAlive(pid) {
   }
 }
 
+/**
+ * Is the live process at `pid` the SAME process the state file recorded at
+ * `expectedStartedAtMs` — or a pid-reusing stranger? (Gap 1.)
+ *
+ * - dead pid → false (not the same process; it is no process at all)
+ * - no anchor (legacy state without startedAt) → true (legacy semantics)
+ * - probe failed → true (FAIL OPEN: never declare a live worker dead — and
+ *   never kill — on the strength of a broken probe; callers fall back to the
+ *   plain kill(pid,0) behavior this system always had)
+ * - creation time > startedAt + tolerance → false (a reuser can only be
+ *   born after the original died)
+ */
+export function isSameProcess(pid, expectedStartedAtMs, options = {}) {
+  if (!isProcessAlive(pid)) return false;
+  const expected = Number(expectedStartedAtMs);
+  if (!Number.isFinite(expected) || expected <= 0) return true;
+  const actual = processStartTimeMs(pid);
+  if (actual === null) return true;
+  const tolerance = Number.isFinite(Number(options.toleranceMs))
+    ? Number(options.toleranceMs)
+    : PID_IDENTITY_TOLERANCE_MS;
+  return actual <= expected + tolerance;
+}
+
+/**
+ * Reap a lost worker's recorded agent child (Gap 2). The worker persists
+ * `agentPid` + `agentStartedAt` per turn; when the WORKER dies (crash /
+ * pid-reuse detection) nothing used to kill that grandchild — it kept
+ * running unsupervised. Kill it, tree-wide, IF we can prove identity:
+ *
+ * - `agentStartedAt` anchor is REQUIRED — unlike the read-only liveness
+ *   probe, this path kills, so a legacy state without the anchor fails
+ *   CLOSED (no kill) rather than risking a pid-reused stranger;
+ * - with the anchor present, a failed creation-time probe fails open to the
+ *   kill (the orphan leak is the common case, reuse the rare one — and the
+ *   anchor already bounds the window to this session's lifetime).
+ *
+ * @returns {boolean} true when a kill was actually issued
+ */
+export function reclaimOrphanAgentProcess(state) {
+  const agentPid = Number(state?.agentPid);
+  if (!Number.isInteger(agentPid) || agentPid <= 0) return false;
+  if (agentPid === Number(state?.pid)) return false; // never the worker itself
+  const anchor = Number(state?.agentStartedAt);
+  if (!Number.isFinite(anchor) || anchor <= 0) return false; // fail closed
+  if (!isSameProcess(agentPid, anchor)) return false; // reused / already gone
+  return _deps.killProcessTree(agentPid, "SIGKILL") === true;
+}
+
 export function normalizeBackgroundAgentTitle(title) {
   const value = String(title || "").trim();
   if (!value) throw new Error("Background agent title cannot be empty");
@@ -164,12 +369,34 @@ export function effectiveBackgroundAgentState(state, options = {}) {
       endedAt: state.endedAt || t,
       lostReason: "process-exited",
     };
+  } else if (!isSameProcess(state.pid, state.startedAt)) {
+    // Gap 1: the pid is alive but belongs to a process created well after
+    // this session started — the OS reused the worker's pid.
+    next = {
+      ...state,
+      status: "lost",
+      endedAt: state.endedAt || t,
+      lostReason: "pid-reused",
+    };
   }
-  if (next !== state && options.persist !== false) {
-    try {
-      writeBackgroundAgentState(next);
-    } catch {
-      /* best-effort; callers still get the corrected state */
+  if (next !== state) {
+    // Gap 2: the worker is gone (dead pid or pid-reused stranger) — reap the
+    // recorded agent grandchild so a crashed worker never leaves it running
+    // unsupervised. A merely-stale heartbeat with a live, verified worker
+    // still owns its child, so isSameProcess gates the reclaim.
+    if (!isSameProcess(state.pid, state.startedAt)) {
+      try {
+        reclaimOrphanAgentProcess(state);
+      } catch {
+        /* best-effort */
+      }
+    }
+    if (options.persist !== false) {
+      try {
+        writeBackgroundAgentState(next);
+      } catch {
+        /* best-effort; callers still get the corrected state */
+      }
     }
   }
   return next;
@@ -430,6 +657,7 @@ export function launchBackgroundAgent({
     pid: null,
     workerPid: null,
     agentPid: null,
+    agentStartedAt: null,
     status: "running",
     startedAt: Date.now(),
     heartbeatAt: Date.now(),
@@ -496,7 +724,35 @@ export function readBackgroundAgentLog(id, options = {}) {
 export function stopBackgroundAgent(id) {
   const state = effectiveBackgroundAgentState(readBackgroundAgentState(id));
   if (!state) throw new Error(`Background agent not found: ${id}`);
-  if (state.status !== "running") return { ...state, stopped: false };
+  if (state.status !== "running") {
+    // Gap 2: stopping an already-lost session still reaps a leaked agent
+    // child recorded before the worker died (identity-guarded inside).
+    if (state.status === "lost") {
+      try {
+        reclaimOrphanAgentProcess(state);
+      } catch {
+        /* best-effort */
+      }
+    }
+    return { ...state, stopped: false };
+  }
+  // Gap 1: last-instant identity re-check before the kill — never
+  // taskkill/SIGTERM a pid the OS has re-assigned to an unrelated process.
+  if (!isSameProcess(state.pid, state.startedAt)) {
+    try {
+      reclaimOrphanAgentProcess(state);
+    } catch {
+      /* best-effort */
+    }
+    const lost = {
+      ...state,
+      status: "lost",
+      endedAt: Date.now(),
+      lostReason: "pid-reused",
+    };
+    writeBackgroundAgentState(lost);
+    return { ...lost, stopped: false };
+  }
   if (process.platform === "win32") {
     const killed = _deps.spawnSync(
       "taskkill",
@@ -517,6 +773,30 @@ export function stopBackgroundAgent(id) {
     } catch {
       process.kill(Number(state.pid), "SIGTERM");
     }
+    // The worker detaches the agent child into its OWN process group (so a
+    // crashed worker's child can be group-killed) — which also means the
+    // worker-group SIGTERM above no longer reaches it. Kill the agent group
+    // explicitly, identity-guarded via its agentStartedAt anchor.
+    const agentPid = Number(state.agentPid);
+    const anchor = Number(state.agentStartedAt);
+    if (
+      Number.isInteger(agentPid) &&
+      agentPid > 0 &&
+      agentPid !== Number(state.pid) &&
+      Number.isFinite(anchor) &&
+      anchor > 0 &&
+      isSameProcess(agentPid, anchor)
+    ) {
+      try {
+        process.kill(-agentPid, "SIGTERM");
+      } catch {
+        try {
+          process.kill(agentPid, "SIGTERM");
+        } catch {
+          /* already gone */
+        }
+      }
+    }
   }
   const next = {
     ...state,