@staix/agent-hub 0.12.16 → 0.12.17

package/src/cli/main.ts

@@ -1,7 +1,8 @@
 #!/usr/bin/env bun
 import { currentRouting } from "../hub/routing.ts";
 import { spawn, spawnSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { chmodSync, existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { ControlClient, readControl } from "../hub/control-client.ts";
@@ -11,12 +12,11 @@ import { projectContext, realPath } from "../hub/project.ts";
 import { Registry, type Project } from "../hub/registry.ts";
 import { inspectProject, startProject, stopProject, runProjectDaemon } from "../hub/lifecycle.ts";
 import { openManager, startManager, stopManager } from "../hub/manager.ts";
-import type { BusEvent } from "../hub/bus.ts";
 import { OmniRoute } from "../omniroute/client.ts";
 import { MemoryClient } from "../memory/client.ts";
 import { init, planInit } from "./init.ts";
 import { launcherPreview } from "./preview.ts";
-import { buildLaunch, claudeObservationHooks, UNATTENDED_WARNING } from "./launch.ts";
+import { buildLaunch, claudeObservationHooks, nativeLaunchEnv, UNATTENDED_WARNING } from "./launch.ts";
 import { nextStep, parseList, pluginState, type InstalledPlugin, type Marketplace } from "./setup.ts";
 import { CLASSES } from "../hub/board.ts";
 import { VERSION } from "../version.ts";
@@ -36,6 +36,10 @@ import { parseSince, readEvents } from "../hub/events.ts";
 import { formatReport, summarize } from "../hub/report.ts";
 import { hasTree, planUndo, repoOf, restore, Turns } from "../hub/snapshots.ts";
 import { pathWarnings } from "../hub/conflicts.ts";
+import { classifyPeerCommand, cliCommandLabel, detectCliIdentity, peerCommandRefusal } from "./identity.ts";
+import { recordCliAudit } from "./identity-audit.ts";
+import { runConsole } from "./console.ts";
+import { renderTailEvent } from "./tail-render.ts";
 
 /** `--since 7d|24h|<iso>` for export and report; everything when absent. */
 const since = (): number => {
@@ -56,7 +60,8 @@ const USAGE = `agent-hub ${VERSION}: Claude Code, Codex and Kimi as peers in one
   ahub ui --all --stop           stop only the dashboard manager
   ahub setup [--yes]            install or update the Claude Code channel plugin from this package, then run doctor
   ahub init [--dry-run --json]   preview or write .agenthub/config.json and the AGENTS.md marker block (drops a legacy CLAUDE.md block)
-  ahub up [--unattended]        start the daemon for this directory
+  ahub up [--unattended] [--no-console]  start the daemon; interactive terminals enter console
+  ahub console [--panels]      enter the human console, leaving the daemon running on exit
   ahub upgrade --to <version> [--dry-run] [--yes]   review and upgrade running projects
   ahub restart [--dry-run] [--yes]                 recover this project's runtime
   ahub recovery status|resume|abort <operation-id> inspect, resume or cancel a preflight
@@ -129,10 +134,21 @@ const projectConfig = () => {
   return config;
 };
 const stateDir = selected.stateDir;
+const identity = detectCliIdentity(process.env);
+const commandLabel = cliCommandLabel(cmd, args);
+const commandAccess = classifyPeerCommand(cmd, args);
+function audit(outcome: "run" | "refused" | "invalid"): void {
+  if (identity.role === "console") return;
+  try { recordCliAudit(stateDir, identity.role === "tools" ? identity.peer : "unknown", commandLabel, outcome); }
+  catch { console.error("ahub: CLI audit could not be recorded (outbox unavailable or full)"); }
+}
+if (identity.role === "invalid") { audit("invalid"); fail(`${identity.reason}; use ahub console or a terminal with no agent markers`); }
+if (identity.role === "tools" && commandAccess === "console") { audit("refused"); fail(peerCommandRefusal(identity.peer, commandLabel)); }
+if (identity.role === "tools") audit("run");
 try { process.chdir(cwd); } catch { fail(`project directory is unavailable: ${cwd}`); }
 const unattendedEnv = process.env.AGENTHUB_UNATTENDED === "1";
 const lifecycle = { inspectProject, startProject, stopProject };
-const connect = () => ControlClient.connect(stateDir, { role: "console", projectRoot: cwd });
+const connect = () => ControlClient.connect(stateDir, identity.role === "tools" ? { role: "tools", peer: identity.peer, projectRoot: cwd } : { role: "console", projectRoot: cwd });
 
 function registeredProject(): Project {
   const registry = new Registry();
@@ -147,14 +163,15 @@ async function healthy(): Promise<boolean> {
   finally { hub?.close(); }
 }
 
-function exec(bin: string, argv: string[]): never {
-  const res = spawnSync(bin, argv, { cwd, stdio: "inherit", env: { ...childEnv(), AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd } });
+function exec(bin: string, argv: string[], tool?: "claude" | "codex"): never {
+  const env = tool ? nativeLaunchEnv(tool, childEnv()) : childEnv();
+  const res = spawnSync(bin, argv, { cwd, stdio: "inherit", env: { ...env, AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd } });
   if (res.error) fail(`cannot run ${bin}: ${res.error.message}`);
   process.exit(res.status ?? 1);
 }
 
 function execWithEnv(bin: string, argv: string[], extra: NodeJS.ProcessEnv): never {
-  const env: NodeJS.ProcessEnv = { ...extra, AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd };
+  const env: NodeJS.ProcessEnv = { ...nativeLaunchEnv("pi", extra), AGENTHUB_STATE_DIR: stateDir, AGENTHUB_PROJECT_DIR: cwd };
   delete env.AGENTHUB_RECOVERY_OPERATION;
   delete env.AGENTHUB_UNATTENDED;
   const res = spawnSync(bin, argv, { cwd, stdio: "inherit", env });
@@ -284,26 +301,11 @@ function fail(message: string): never {
   process.exit(1);
 }
 
-function render(e: BusEvent): string {
-  if (e.t === "state") return `  . ${e.peer} is ${e.state}`;
-  if (e.t === "undeliverable") return `  ! gave up delivering ${e.env.id} (from ${e.env.from}) to ${e.peer}`;
-  if (e.t === "envelope" && e.env.from === "hub" && e.env.kind !== "chat") {
-    return `${new Date(e.env.ts).toLocaleTimeString()} hub -> ${e.env.to?.join(",")} [${e.env.kind}${e.env.refs?.task ? ` #${e.env.refs.task}` : ""}]\n${e.env.body.split("\n")[0]!.replace(/^/, "    ")}`;
-  }
-  if (e.t === "overflow") return `  ! ${e.peer}'s queue is full: dropped ${e.env.id} (from ${e.env.from})`;
-  if (e.t === "stale") return `  . dropped ${e.env.id} (from ${e.env.from}) for ${e.peer}: ${e.reason}`;
-  if (e.t === "quiet") return `  . ${e.env.id} (from ${e.env.from}) not delivered to ${e.peers.join(", ")}: turn-free cohort`;
-  const { env } = e;
-  const note = e.dropped === "hop" ? " [not delivered: hop limit]" : e.dropped === "fyi" ? " [fyi: record only]" : "";
-  const head = `${env.from} -> ${env.to?.join(",") ?? "*"}${env.priority === "important" ? " !" : ""}${note}`;
-  return `${new Date(env.ts).toLocaleTimeString()} ${head}\n${env.body.replace(/^/gm, "    ")}`;
-}
-
 async function taskOp(op: string, a: Record<string, unknown>): Promise<string> {
   const hub = await connect();
   const res = await hub.request({ t: "task", op, args: a });
   hub.close();
-  if (!res.ok) fail(res.error);
+  if (!res.ok) { audit("refused"); fail(res.error); }
   return res.text;
 }
 
@@ -488,11 +490,17 @@ const commands: Record<string, () => Promise<void> | void> = {
     await runProjectDaemon(registeredProject(), unattendedEnv || args.includes("--unattended"));
   },
 
+  console: async () => {
+    if (args.some(arg => arg !== "--panels")) fail("usage: ahub console [--panels]");
+    await runConsole({ client: await connect(), cwd, stateDir, panels: args.includes("--panels") });
+  },
+
   up: async () => {
     const unattended = unattendedEnv || args.includes("--unattended");
     if (unattended) console.error(UNATTENDED_WARNING);
     const status = await startProject(registeredProject(), { unattended });
     console.log(`ahub up (ws://127.0.0.1:${status.controlPort}), state in ${stateDir}`);
+    if (process.stdin.isTTY && process.stdout.isTTY && !args.includes("--no-console")) await runConsole({ client: await connect(), cwd, stateDir });
   },
 
   claude: async () => {
@@ -504,7 +512,12 @@ const commands: Record<string, () => Promise<void> | void> = {
     const control = readControl(stateDir);
     if (control?.instanceId) {
       process.env.AGENTHUB_INSTANCE_ID = control.instanceId;
-      await recordTerminalLaunch("claude", cwd, stateDir, control.instanceId);
+      const terminal = await recordTerminalLaunch("claude", cwd, stateDir, control.instanceId);
+      if (!terminal) process.env.AGENTHUB_LAUNCH_ID = randomUUID();
+      // Native hook identity exists in an ordinary terminal too; this is not an Orca recovery record.
+      const file = join(stateDir, "claude-launch.json");
+      writeFileSync(`${file}.tmp`, JSON.stringify({ instanceId: control.instanceId, launchId: process.env.AGENTHUB_LAUNCH_ID }), { mode: 0o600 });
+      chmodSync(`${file}.tmp`, 0o600); renameSync(`${file}.tmp`, file);
     }
     // `--settings` outranks project and user settings, so the tee has to wrap whichever status line would have won:
     // project local, then project, then user.
@@ -520,7 +533,7 @@ const commands: Record<string, () => Promise<void> | void> = {
     const facts = claudeObservationHooks(projectConfig(), { script: join(import.meta.dir, "facts-hook.ts"), stateDir });
     const launch = buildLaunch("claude", args, { unattended: unattendedEnv, statusLine: { script: join(import.meta.dir, "statusline-tee.ts"), stateDir, ...(original ? { original } : {}) }, ...(facts ? { facts } : {}) });
     if (launch.warning) console.error(launch.warning);
-    exec(launch.cmd, launch.args);
+    exec(launch.cmd, launch.args, "claude");
   },
 
   codex: async () => {
@@ -538,7 +551,7 @@ const commands: Record<string, () => Promise<void> | void> = {
     if (control?.instanceId) await recordTerminalLaunch("codex", cwd, stateDir, control.instanceId);
     const launch = buildLaunch("codex", args, { unattended: unattendedEnv, proxyUrl: res.proxyUrl, codexBin: projectConfig().codex_bin });
     if (launch0.warning) console.error(launch0.warning);
-    exec(launch.cmd, launch.args);
+    exec(launch.cmd, launch.args, "codex");
   },
 
   kimi: async () => {
@@ -663,7 +676,7 @@ const commands: Record<string, () => Promise<void> | void> = {
   tail: async () => {
     const hub = await connect();
     hub.onPush = (msg) => {
-      if (msg.t === "event") console.log(render(msg.e));
+      if (msg.t === "event") console.log(renderTailEvent(msg.e));
       else if (msg.t === "context") console.log(`  ${msg.peer}: ${contextLine(msg.reading)}`);
       else if (msg.t === "notice") console.log(`  * ${msg.line}`);
       else if (msg.t === "permission") {
@@ -998,9 +1011,29 @@ const commands: Record<string, () => Promise<void> | void> = {
   },
 };
 
-const run = commands[cmd] ?? (() => fail(`unknown command "${cmd}"\n\n${USAGE}`));
+async function runConductorCommand(): Promise<void> {
+  let op: string;
+  let input: Record<string, unknown>;
+  if (cmd === "task") {
+    op = args[0] === "assign" ? "hub_task_assign" : "hub_task_escalate";
+    if (!args[1] || (args[0] === "assign" && !args[2]) || args.length !== (args[0] === "assign" ? 3 : 2)) fail("usage: ahub task assign <id> <peer> | escalate <id>");
+    input = { id: Number(args[1]), ...(args[0] === "assign" ? { peer: args[2] } : {}) };
+  } else if (cmd === "pause" || cmd === "resume") {
+    if (args.length !== 1) fail(`usage: ahub ${cmd} <peer>`);
+    op = cmd === "pause" ? "hub_peer_hold" : "hub_peer_release";
+    input = { peer: args[0] };
+  } else {
+    // Native TUIs return a human launch command through the daemon; an agent shell never executes it.
+    if (args.length && !(cmd === "pi" && args.length === 2 && args[0] === "--mode" && ["headless", "tui"].includes(args[1] ?? ""))) fail(`conductor starts accept no launch overrides; use ahub ${cmd}${cmd === "pi" ? " [--mode headless|tui]" : ""}`);
+    op = "hub_peer_start";
+    input = { peer: cmd, ...(cmd === "pi" ? { mode: args[1] ?? "headless" } : {}) };
+  }
+  console.log(await taskOp(op, input));
+}
+const run = identity.role === "tools" && commandAccess === "conductor" ? runConductorCommand : commands[cmd] ?? (() => fail(`unknown command "${cmd}"\n\n${USAGE}`));
 try {
   await run();
 } catch (e) {
+  audit("refused");
   fail((e as Error).message);
 }

package/src/cli/tail-render.ts

@@ -0,0 +1,17 @@
+import type { BusEvent } from "../hub/bus.ts";
+
+export function renderTailEvent(e: BusEvent): string {
+  if (e.t === "state") return `  . ${e.peer} is ${e.state}`;
+  if (e.t === "undeliverable") return `  ! gave up delivering ${e.env.id} (from ${e.env.from}) to ${e.peer}`;
+  if (e.t === "envelope" && e.env.from === "hub" && e.env.kind !== "chat") {
+    return `${new Date(e.env.ts).toLocaleTimeString()} hub -> ${e.env.to?.join(",")} [${e.env.kind}${e.env.refs?.task ? ` #${e.env.refs.task}` : ""}]\n${e.env.body.split("\n")[0]!.replace(/^/, "    ")}`;
+  }
+  if (e.t === "overflow") return `  ! ${e.peer}'s queue is full: dropped ${e.env.id} (from ${e.env.from})`;
+  if (e.t === "stale") return `  . dropped ${e.env.id} (from ${e.env.from}) for ${e.peer}: ${e.reason}`;
+  if (e.t === "quiet") return `  . ${e.env.id} (from ${e.env.from}) not delivered to ${e.peers.join(", ")}: turn-free cohort`;
+  const { env } = e;
+  const note = e.dropped === "hop" ? " [not delivered: hop limit]" : e.dropped === "fyi" ? " [fyi: record only]" : "";
+  const head = `${env.from} -> ${env.to?.join(",") ?? "*"}${env.priority === "important" ? " !" : ""}${note}`;
+  return `${new Date(env.ts).toLocaleTimeString()} ${head}\n${env.body.replace(/^/gm, "    ")}`;
+}
+

package/src/cli/upgrade-runtime.ts

@@ -114,7 +114,7 @@ export async function makeUpgradePlan(kind: "restart" | "upgrade", version: stri
     catch { source = { state: "unavailable", peers: [], blockers: ["source recovery metadata could not be authenticated"] }; }
     if (source.state === "stopped" || source.state === "missing") continue;
     const blockers = [...source.blockers];
-    if (!RECOVERY_SOURCE_PROTOCOLS.includes(source.protocol as (typeof RECOVERY_SOURCE_PROTOCOLS)[number]) || source.state !== "running") blockers.push("manual-bootstrap-required: an authenticated protocol-9, protocol-10, protocol-11, protocol-12, protocol-13 or protocol-14 source is required");
+    if (!RECOVERY_SOURCE_PROTOCOLS.includes(source.protocol as (typeof RECOVERY_SOURCE_PROTOCOLS)[number]) || source.state !== "running") blockers.push("manual-bootstrap-required: an authenticated protocol-9, protocol-10, protocol-11, protocol-12, protocol-13, protocol-14 or protocol-15 source is required");
     if (source.recovery?.operationId && source.recovery.phase !== "released") blockers.push(`existing recovery operation ${source.recovery.operationId} must be resolved first`);
     const sessions: { codex?: string; claude?: string; pi?: SessionRef } = {};
     for (const peer of source.peers) {

package/src/hub/board.ts

@@ -18,6 +18,8 @@ export type TaskPlan = Partial<Record<(typeof PLAN_KEYS)[number], string[]>>;
 /** Task outcomes older than this are pruned: demotion (issue #36) reads one week, seven half-lives. */
 export const OUTCOMES_KEPT_MS = 7 * 24 * 3_600_000;
 
+export const TASK_MOVE_REASONS = ["manual", "budget", "offline", "idle", "rejections", "declined", "inference_failed", "delivery_failed"] as const;
+export type TaskMoveReason = (typeof TASK_MOVE_REASONS)[number];
 export interface HistoryEntry {
   at: number;
   by: PeerId;
@@ -27,6 +29,8 @@ export interface HistoryEntry {
   owner?: PeerId | null;
   /** On a hand-over: the new owner's split profile then (#109); absent when it was unknown. */
   profile?: string;
+  /** Structured cause recorded at the operation source, never inferred from note text. */
+  reason?: TaskMoveReason;
   /** Persisted task-idle ladder; never counted as fresh task activity (#186). */
   sweep?: SweepRecord;
 }
@@ -122,14 +126,14 @@ export class Board {
 
   /** The only way a task changes. Validates the move, records who did what, returns the new row. */
   /** A `plan` in the patch replaces the old one whole: a new plan is the owner's current intent, not an addition. */
-  update(id: number, by: PeerId, event: string, patch: Partial<Pick<Task, "state" | "owner" | "reviewer" | "refs" | "plan" | "rejections">>, note?: string, extra: Pick<HistoryEntry, "profile" | "sweep"> = {}): Task {
+  update(id: number, by: PeerId, event: string, patch: Partial<Pick<Task, "state" | "owner" | "reviewer" | "refs" | "plan" | "rejections">>, note?: string, extra: Pick<HistoryEntry, "profile" | "sweep" | "reason"> = {}): Task {
     const task = this.get(id);
     if (!task) throw new Error(`no task #${id}`);
     if (patch.state && patch.state !== task.state && !MOVES[task.state].includes(patch.state)) {
       throw new Error(`task #${id} is ${task.state}: cannot move to ${patch.state}`);
     }
     const next = { ...task, ...patch, refs: { ...task.refs, ...patch.refs } };
-    const history = [...task.history, { at: Date.now(), by, event, ...(note ? { note } : {}), ...("owner" in patch ? { owner: next.owner } : {}), ...(extra.profile ? { profile: extra.profile } : {}), ...(extra.sweep ? { sweep: extra.sweep } : {}) }];
+    const history = [...task.history, { at: Date.now(), by, event, ...(note ? { note } : {}), ...("owner" in patch ? { owner: next.owner } : {}), ...(extra.profile ? { profile: extra.profile } : {}), ...(extra.sweep ? { sweep: extra.sweep } : {}), ...(extra.reason && TASK_MOVE_REASONS.includes(extra.reason) ? { reason: extra.reason } : {}) }];
     this.db
       .query("UPDATE tasks SET state = ?, owner = ?, reviewer = ?, refs = ?, plan = ?, rejections = ?, history = ?, updated = ? WHERE id = ?")
       .run(next.state, next.owner, next.reviewer, JSON.stringify(next.refs), JSON.stringify(next.plan ?? {}), next.rejections, JSON.stringify(history), Date.now(), id);

package/src/hub/bus.ts

@@ -82,6 +82,8 @@ function resolveTo(to: PeerId[], originals: Envelope[] | undefined): PeerId[] {
 
 const SEEN_CAP = 2048;
 const MAX_ATTEMPTS = 3;
+// ponytail: one digest carries at most ten originals; larger supervision windows split into bounded deliveries.
+// Revisit this ceiling after measuring native supervision cost, rather than bypassing the delivery limit.
 const DIGEST_MAX = 10;
 const NOTES_KEPT = 10;
 
@@ -100,6 +102,8 @@ export class Bus {
   private readonly manualPaused = new Set<PeerId>();
   private readonly timers = new Map<PeerId, ReturnType<typeof setTimeout>>();
   private readonly draining = new Set<PeerId>();
+  /** Still pending while an asynchronous condensation runs; never includes native dispatches. */
+  private readonly preparing = new Map<PeerId, Envelope[]>();
   private readonly seen = new Map<string, Envelope>();
   private readonly taps = new Set<(e: BusEvent) => void>();
   private readonly withdrawn = new Set<string>();
@@ -119,6 +123,10 @@ export class Bus {
    * and is never corrected once the queue empties (measured: status.json kept `queued 4` on an empty queue).
    */
   onQueues?: () => void;
+  /** Actual transport admission, using originals even when a digest was condensed. Never an enqueue metric. */
+  onDelivered?: (peer: PeerId, originals: Envelope[]) => void;
+  /** Synchronous native failure observation, before queue callbacks can finish turn metrics. */
+  onDeliveryFailed?: (peer: PeerId) => void;
   private recoveryHeld = false;
   private steering = 0;
   private condensing = 0;
@@ -389,7 +397,9 @@ export class Bus {
     const id = receipt.id;
     const before = this.journal.get(id);
     const state: JournalDeliveryState = receipt.state === "accepted" ? "accepted" : receipt.state === "completed" ? "completed" : receipt.state === "failed_safe" ? "failed" : "needs_review";
+    if (state === "failed" || state === "needs_review") this.deliveryFailed(peer);
     this.journal.transition(id, state, receipt.reason);
+    if (before?.state === "dispatching" && (state === "accepted" || state === "completed")) this.delivered(peer, before.originals);
     if (state === "failed") {
       if (before) this.failed(peer, before.originals, before.originals.some((e) => e.private) ? "private delivery failed" : receipt.reason);
     }
@@ -525,7 +535,8 @@ export class Bus {
         this.activeDeliveries.set(deliveryId, id);
         if (this.journal) this.durableHandoff(id, deliveryId, [env], [env]);
         const steerResult = this.journal ? peer.steer([env], deliveryId) : peer.steer([env]);
-        steerResult.then(() => {}).catch(() => {
+        steerResult.then(() => { this.delivered(id, [env]); }).catch(() => {
+          this.deliveryFailed(id);
           if (this.journal) this.journal.transition(deliveryId, "needs_review", "adapter steering outcome is uncertain");
           this.activeDeliveries.delete(deliveryId);
           if (!this.journal) this.enqueue(id, env, true);
@@ -570,8 +581,7 @@ export class Bus {
    * dropped if the refused steer tries to queue it later.
    */
   withdraw(envelopeId: string): boolean {
-    this.withdrawn.add(envelopeId);
-    if (this.withdrawn.size > 256) this.withdrawn.delete(this.withdrawn.values().next().value as string);
+    this.markWithdrawn(envelopeId);
     let removed = false;
     for (const queue of this.queues.values()) {
       const i = queue.findIndex((e) => e.id === envelopeId);
@@ -582,6 +592,49 @@ export class Bus {
     return removed;
   }
 
+  /** Revoke pending feed copies only; accepted/dispatching journal records and native turns are untouched. */
+  revokeSupervision(peer: PeerId): number {
+    const queue = this.queues.get(peer);
+    if (!queue && !this.preparing.has(peer)) return 0;
+    let removed = 0;
+    const discarded = new Set<string>();
+    for (let i = (queue?.length ?? 0) - 1; i >= 0; i--) {
+      const env = queue![i]!;
+      if (env.from !== HUB || !env.refs?.supervision) continue;
+      queue!.splice(i, 1);
+      removed++;
+      discarded.add(env.id);
+      this.markWithdrawn(env.id);
+      this.discardQueued(peer, env, "supervision role or feed revoked");
+    }
+    for (const env of this.preparing.get(peer) ?? []) {
+      if (env.from !== HUB || !env.refs?.supervision || discarded.has(env.id)) continue;
+      this.markWithdrawn(env.id);
+      this.discardQueued(peer, env, "supervision role or feed revoked during preparation");
+      removed++;
+    }
+    if (removed) { this.persist(); this.onQueues?.(); }
+    return removed;
+  }
+
+  private discardQueued(peer: PeerId, env: Envelope, reason: string): void {
+    if (this.journal) this.pendingOutcomes.push({ id: crypto.randomUUID(), peer, state: "discarded", createdAt: Date.now(), originals: [env], out: [], reason });
+    this.emit({ t: "stale", env, peer, reason });
+  }
+
+  private delivered(peer: PeerId, originals: Envelope[]): void {
+    try { this.onDelivered?.(peer, originals); } catch { /* observation must never affect delivery settlement */ }
+  }
+
+  private deliveryFailed(peer: PeerId): void {
+    try { this.onDeliveryFailed?.(peer); } catch { /* observation must never affect delivery settlement */ }
+  }
+
+  private markWithdrawn(id: string): void {
+    this.withdrawn.add(id);
+    if (this.withdrawn.size > 256) this.withdrawn.delete(this.withdrawn.values().next().value as string);
+  }
+
   queued(id: PeerId): number {
     return this.queues.get(id)?.length ?? 0;
   }
@@ -599,8 +652,23 @@ export class Bus {
     if (this.withdrawn.has(env.id)) return;
     const queue = this.queues.get(id) ?? [];
     this.queues.set(id, queue);
-    if (front) queue.unshift(env);
-    else queue.push(env);
+    const key = env.from === HUB && env.refs?.supervision ? env.refs.supervisionKey : undefined;
+    const replace = !front && key ? queue.findIndex((old) => old.from === HUB && old.refs?.supervision && old.refs.supervisionKey === key && !this.attempts.has(`${id}:${old.id}`)) : -1;
+    const preparing = !front && key ? this.preparing.get(id)?.find((old) => old.from === HUB && old.refs?.supervision && old.refs.supervisionKey === key && !this.attempts.has(`${id}:${old.id}`) && !this.withdrawn.has(old.id)) : undefined;
+    let queuedEnv = preparing ? { ...env, ts: Math.min(preparing.ts, env.ts) } : env;
+    if (replace >= 0) {
+      const old = queue[replace]!;
+      // Keep the first milestone's deadline, so continuous updates cannot create another batching window.
+      queuedEnv = { ...queuedEnv, ts: Math.min(old.ts, queuedEnv.ts) };
+      queue[replace] = queuedEnv;
+      this.markWithdrawn(old.id);
+      this.discardQueued(id, old, "superseded supervision milestone");
+    } else if (front) queue.unshift(queuedEnv);
+    else queue.push(queuedEnv);
+    if (preparing && !this.withdrawn.has(preparing.id)) {
+      this.markWithdrawn(preparing.id);
+      this.discardQueued(id, preparing, "superseded supervision milestone during preparation");
+    }
     if (queue.length > this.opts.queueCap) {
       const victim = queue.findIndex((e) => e.priority !== "important");
       const [lost] = queue.splice(victim === -1 ? 0 : victim, 1);
@@ -614,7 +682,8 @@ export class Bus {
 
   /** 0 = deliver now; otherwise how long the oldest envelope still has to wait for company. */
   private wait(queue: Envelope[]): number {
-    if (queue.length >= this.opts.batchMax || queue.some((e) => e.priority === "important")) return 0;
+    const supervisionOnly = queue.every((e) => e.from === HUB && e.refs?.supervision && e.priority === "status");
+    if ((!supervisionOnly && queue.length >= this.opts.batchMax) || queue.some((e) => e.priority === "important")) return 0;
     return Math.max(0, queue[0]!.ts + this.opts.batchMs - Date.now());
   }
 
@@ -656,6 +725,7 @@ export class Bus {
         // may checkpoint during that wait; it must not checkpoint the batch out of existence.
         if (!this.journal) this.prefaces.delete(id);
         const batch = this.take(id, queue, !this.journal);
+        this.preparing.set(id, batch);
         const delivery = preface ? [preface, ...batch] : batch;
         const mayCondense = this.opts.condense && !delivery.some((e) => e.priority === "important");
         this.condensing += mayCondense ? 1 : 0;
@@ -679,11 +749,12 @@ export class Bus {
         for (const e of out) if (!this.seen.has(e.id)) this.seen.set(e.id, e);
         while (this.seen.size > SEEN_CAP) this.seen.delete(this.seen.keys().next().value as string);
         this.lastDelivery.set(id, { out, originals: delivery });
+        this.preparing.delete(id); // from here on the transport/journal owns settlement
         const deliveryId = crypto.randomUUID();
         if (this.journal) { this.durableHandoff(id, deliveryId, delivery, out); this.activeDeliveries.set(deliveryId, id); }
         try {
           if (this.journal) await peer.deliver(out, deliveryId);
-          else await peer.deliver(out);
+          else { await peer.deliver(out); this.delivered(id, delivery); }
         } catch {
           if (this.journal) this.uncertain(id, deliveryId, "adapter delivery outcome is uncertain");
           else this.failed(id, delivery);
@@ -691,11 +762,11 @@ export class Bus {
         }
       }
     } catch { this.storageError = "delivery journal unavailable"; }
-    finally { this.draining.delete(id); this.onQueues?.(); }
+    finally { this.preparing.delete(id); this.draining.delete(id); this.onQueues?.(); }
   }
 
   private isRelevant(id: PeerId, env: Envelope): boolean {
-    return this.opts.relevant?.(id, env) ?? true;
+    return !this.withdrawn.has(env.id) && (this.opts.relevant?.(id, env) ?? true);
   }
 
   /**
@@ -704,7 +775,7 @@ export class Bus {
    * this recipient's copy goes: the other queues keep theirs, and no other delivery record changes.
    */
   private dropIrrelevant(id: PeerId, queue: Envelope[]): boolean {
-    if (!this.opts.relevant) return false;
+    if (!this.opts.relevant && !this.withdrawn.size) return false;
     let dropped = false;
     for (let i = queue.length - 1; i >= 0; i--) {
       const env = queue[i]!;
@@ -757,6 +828,7 @@ export class Bus {
   }
 
   private failed(id: PeerId, envs: Envelope[], reason = "delivery failed without an error detail"): void {
+    if (!this.journal) this.deliveryFailed(id);
     this.lastFailure.set(id, reason.replace(/\s+/g, " ").slice(0, 300));
     if (envs.some((env) => !(env.from === HUB && env.kind === "presence") && (this.attempts.get(`${id}:${env.id}`) ?? 0) + 1 >= MAX_ATTEMPTS)) {
       this.failureStreak.set(id, (this.failureStreak.get(id) ?? 0) + 1);

package/src/hub/child-process.ts

@@ -11,6 +11,17 @@ export function childEnv(source: NodeJS.ProcessEnv = process.env): NodeJS.Proces
   return env;
 }
 
+/** Every native child owns its marker; caller vendor markers must not leak across peers (#193). */
+export function peerChildEnv(peer: string, source: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  const env = childEnv(source);
+  delete env.CLAUDECODE;
+  delete env.CLAUDE_CODE_SESSION_ID;
+  delete env.CODEX_THREAD_ID;
+  delete env.AGENTHUB_PEER_ID;
+  env.AGENTHUB_PEER_ID = peer;
+  return env;
+}
+
 /** One process: its identity is the pid with its start time (`lstart`, which exec keeps); group and command are evidence. */
 export interface ProcRow {
   pid: number;