@staix/agent-hub 0.12.27 → 0.12.29

package/src/cli/preview.ts

@@ -99,7 +99,13 @@ export function launcherPreview(tool: "claude" | "codex" | "kimi" | "pi" | "qwen
     const mode = value("--mode") ?? startModeOf(config.peers, "pi"); // #269: the same default `ahub pi` takes
     const backend = value("--backend") ?? config.pi.backend;
     if (!["headless", "tui"].includes(mode) || !["auto", "dgx", "mlx"].includes(backend) || (value("--session-id") && value("--session-file"))) throw new Error("invalid Pi options");
-    for (let i = 0; i < args.length; i += 2) if (!["--mode", "--backend", "--model", "--session-id", "--session-file"].includes(args[i]!)) throw new Error("unknown Pi option");
+    if (args.includes("--replace-session") && (!value("--session-file") || value("--session-id"))) throw new Error("--replace-session requires --session-file, without --session-id");
+    for (let i = 0; i < args.length; i++) {
+      if (args[i] === "--replace-session") continue;
+      if (!["--mode", "--backend", "--model", "--session-id", "--session-file"].includes(args[i]!) || !value(args[i]!)) throw new Error("unknown Pi option");
+      i++;
+    }
+    if (args.includes("--replace-session")) unresolved.push({ field: "session replacement", reason: "requires a person, a validated managed file and an offline settled owner at runtime; preview changes nothing" });
     const models = relayModelIds({ enableHubAuto: true, mlx: config.mlx.enabled === false ? undefined : config.mlx, mlxAlias: "mlx/fast", allowedDGXmodels: { "dgx/coding": config.pi.dgx_coding, "dgx/fast": config.pi.dgx_fast } });
     const pi = buildPiLaunch({
       stateDir, cmd: nativeCommand(config.pi.cmd, ["pi"]), mode: mode as "headless" | "tui", backend: backend as "auto" | "dgx" | "mlx",

package/src/cli/upgrade-runtime.ts

@@ -323,7 +323,7 @@ export function preserveSource(plan: UpgradePlan, home = hubHome()): string {
   return dest;
 }
 
-export function makeRecoveryDriver(run: RunCommand = runCommand): RecoveryDriver {
+export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?: string): RecoveryDriver {
   const now = () => Date.now();
   const sleep = (ms: number) => Bun.sleep(ms);
   const env = (op: RecoveryOperation, project?: Project): NodeJS.ProcessEnv => {
@@ -333,6 +333,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand): RecoveryDriver
       (project && /(?:_API_KEY|_ACCESS_TOKEN|_SECRET|_TOKEN)$/.test(key))) delete value[key];
     value.AGENTHUB_HOME = hubHome(); value.AGENTHUB_RECOVERY_OPERATION = op.id;
     value.AGENTHUB_UNATTENDED = "0";
+    if (liveTestPeer) value.AGENTHUB_PEER_ID = liveTestPeer;
     if (project) {
       value.AGENTHUB_PROJECT_DIR = project.root; value.AGENTHUB_STATE_DIR = project.stateDir;
       delete value.CODEX_HOME; delete value.CLAUDE_CONFIG_DIR;
@@ -345,7 +346,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand): RecoveryDriver
     return value;
   };
   const command = async (op: RecoveryOperation, args: string[], project?: Project) => {
-    const result = await run([process.execPath, join(op.targetRoot!, "src/cli/main.js"), ...(project ? ["--project", project.root] : []), ...args],
+    const result = await run([process.execPath, join(op.targetRoot!, "src/cli/main.js"), ...(project ? ["--project", project.root] : []), ...(liveTestPeer ? ["--live-test"] : []), ...args],
       { env: env(op, project), cwd: project?.root ?? op.plan.projects[0]!.project.root, timeoutMs: 180_000 });
     if (result.code !== 0) throw new Error(`target command ${args[0]} failed; inspect recovery state before retrying`);
     return result;
@@ -448,6 +449,10 @@ export function makeRecoveryDriver(run: RunCommand = runCommand): RecoveryDriver
       if (packageDigest(op.sourceRoot) !== op.plan.sourceDigest) throw new FinalRefusal("preserved source changed");
       const target = op.plan.kind === "restart" ? { root: op.sourceRoot, digest: verifyPackage(op.sourceRoot, op.plan.version) }
         : await stageRelease(op.plan.version, op.plan.integrity!, run);
+      const identityPath = join(target.root, "src/cli/identity.ts");
+      if (liveTestPeer && (!existsSync(identityPath) || !readFileSync(identityPath, "utf8").includes("export const LIVE_TEST_SUPPORTED = true;"))) {
+        throw new FinalRefusal("target does not support live-test delegation; choose a supporting target before retrying; runtimes unchanged");
+      }
       // #215: the protocol and waiver checks are properties of these bytes. Once they passed (the runner recorded the
       // digest), a resume does not check again, so a transient probe failure cannot refuse an operation for good;
       // changed bytes are the runner's final "staged target changed".

package/src/hub/bus.ts

@@ -46,6 +46,11 @@ export interface BusOptions {
    * the console and the log see it as published.
    */
   silence?: (env: Envelope, peer: PeerId) => string | undefined;
+  /**
+   * Optional: an `important` envelope was just queued for a pull-only peer (issue #398). Advisory only: nothing was
+   * dequeued, steered or journaled for it, and the queue still waits for `Bus.pull`; a throw is swallowed.
+   */
+  onImportantQueued?: (peer: PeerId, counts: { queued: number; important: number }) => void;
 }
 
 /** Serializable delivery state used by the controlled restart coordinator. Bodies stay in the private daemon file. */
@@ -732,6 +737,10 @@ export class Bus {
       if (this.journal) this.pendingOutcomes.push({ id: crypto.randomUUID(), peer: id, state: "failed", createdAt: Date.now(), originals: [lost!], out: [], reason: "queue capacity exceeded" });
       this.emit({ t: "overflow", env: lost!, peer: id });
     }
+    if (queuedEnv.priority === "important" && this.peers.get(id)?.pullOnly) {
+      // Advisory only (issue #398): the envelope stays queued for `pull`; the hook must never affect it.
+      try { this.opts.onImportantQueued?.(id, { queued: queue.length, important: queue.filter((e) => e.priority === "important").length }); } catch { /* a nudge never stops an enqueue */ }
+    }
     this.onQueues?.();
     if (!this.suppressDrain) this.persist();
     if (!this.suppressDrain) void this.drain(id);

package/src/hub/daemon.ts

@@ -38,6 +38,7 @@ import { ensureMlx, type MlxOptions } from "../models/mlx.ts";
 import { PiToolReceipts, packPiShellResult } from "../pi/tool-receipts.ts";
 import { PreEffectToolRefusal } from "./tool-refusal.ts";
 import { processSignature } from "../pi/process-signature.ts";
+import { recordPiReplacement, validatePiSession } from "../pi/session.ts";
 import { profile, proxyEnv, type SandboxNetwork } from "../local/sandbox.ts";
 import { DEFAULT_NETWORK_ALLOW, startEgressProxy, type EgressProxy } from "../local/proxy.ts";
 import { runTool, toolResultFailed, TOOL_SCHEMAS, type ToolApproval, type ApprovalObserver, type ToolContext } from "../local/tools.ts";
@@ -489,6 +490,11 @@ class WsPeer extends BasePeer {
     if (deliveryId) this.delivered.add(deliveryId);
     this.sock.send(JSON.stringify({ t: "deliver", envs, generation: this.generation, ...(deliveryId ? { deliveryId } : {}) }));
   }
+  /** Advisory nudge (issue #398): important work waits in the pull queue. Not a delivery: nothing to settle or journal. */
+  notifyQueued(counts: { queued: number; important: number }): void {
+    if (!this.sock || !this.pullOnly) return;
+    this.sock.send(JSON.stringify({ t: "queued", queued: counts.queued, important: counts.important }));
+  }
   owns(sock: Sock): boolean { return this.sock === sock; }
   nativeStarted(session: string): void {
     if (!this.sock) return;
@@ -769,7 +775,8 @@ export async function startDaemon(opts: DaemonOptions) {
   const staleOff = config.experiments?.stale_notices === "deliver";
   if (staleOff) log("experiment: stale notices are delivered as before 0.12.4 (the issue #106 ablation)");
   const requestedPeerStops = new Set<string>();
-  const bus = new Bus({ rostered: membershipAllowed, deliveryHeld: peer => requestedPeerStops.has(peer) || rosterChanging === peer, journal, batchMax: config.batch_max, batchMs: config.batch_ms, queueCap: config.queue_cap, condense: (envs) => inference?.condense(envs) ?? Promise.resolve(envs), admit, relevant: (peer, env) => env.refs?.supervision || env.refs?.backlog ? relevantNotice(peer, env) : staleOff || relevantNotice(peer, env), silence });
+  const bus = new Bus({ rostered: membershipAllowed, deliveryHeld: peer => requestedPeerStops.has(peer) || rosterChanging === peer, journal, batchMax: config.batch_max, batchMs: config.batch_ms, queueCap: config.queue_cap, condense: (envs) => inference?.condense(envs) ?? Promise.resolve(envs), admit, relevant: (peer, env) => env.refs?.supervision || env.refs?.backlog ? relevantNotice(peer, env) : staleOff || relevantNotice(peer, env), silence,
+    onImportantQueued: (peer, counts) => { const p = bus.peers.get(peer); if (p instanceof WsPeer) p.notifyQueued(counts); } });
   startupCleanup.push(() => bus.closeJournal());
   const manualPaused = new Set<PeerId>(bus.manualPausedPeers()); // recovery never lifts an operator's pause
   const conductorHolds = new ConductorHolds(join(opts.stateDir, "hub.db"));
@@ -1452,9 +1459,12 @@ export async function startDaemon(opts: DaemonOptions) {
       supervision.checkRound();
       try {
         for (const audit of drainCliAudits(opts.stateDir)) {
-          const refused = audit.outcome !== "run";
-          event({ type: "agent_cli", peer: audit.peer, command: audit.command, refused });
-          notify(refused ? `${audit.peer} refused ahub ${audit.command}` : `${audit.peer} ran ahub ${audit.command} as ${audit.peer}`);
+          const delegated = audit.outcome === "delegated";
+          const refused = audit.outcome !== "run" && !delegated;
+          event({ type: "agent_cli", peer: audit.peer, command: audit.command, refused, ...(delegated ? { delegated: true } : {}) });
+          notify(refused ? `${audit.peer} refused ahub ${audit.command}` : delegated
+            ? `${audit.peer} ran ahub ${audit.command} with delegated live-test console authority`
+            : `${audit.peer} ran ahub ${audit.command} as ${audit.peer}`);
         }
       } catch { log("CLI audit outbox unavailable; inspect state before retrying an agent command"); }
       for (const peer of bus.knownPeers()) {
@@ -2406,6 +2416,7 @@ export async function startDaemon(opts: DaemonOptions) {
   let piAutoRestartAt = -Infinity;
   let piAutoRestartPending = false;
   const replacingPi = new Set<PiPeer>();
+  const piReplacementAuthority = Symbol("console Pi replacement");
   /** pi.auto_start at hub start (#269): in Pi's start mode, and said out loud when it could not be done. */
   const autoStartPi = () => void hubStart("pi", "pi.auto_start").then(
     (result) => { if (result.ok !== true) notify(`pi.auto_start did not start Pi: ${String(result.error)}`); },
@@ -2414,7 +2425,8 @@ export async function startDaemon(opts: DaemonOptions) {
     replacingPi.add(pi);
     try { await pi.stop(); } finally { replacingPi.delete(pi); }
   }
-  function startPeer(peer: string, args: { model?: string; route?: string; mode?: "headless" | "tui"; backend?: "auto" | "dgx" | "mlx"; sessionId?: string; sessionFile?: string; fresh?: boolean; unattended?: boolean; providerProfile?: string }): Promise<Record<string, unknown>> {
+  function startPeer(peer: string, args: { model?: string; route?: string; mode?: "headless" | "tui"; backend?: "auto" | "dgx" | "mlx"; sessionId?: string; sessionFile?: string; replaceSession?: boolean; fresh?: boolean; unattended?: boolean; providerProfile?: string }, replacementAuthority?: symbol): Promise<Record<string, unknown>> {
+    if (args.replaceSession !== undefined && (args.replaceSession !== true || replacementAuthority !== piReplacementAuthority || peer !== "pi")) return Promise.resolve({ ok: false, error: "Pi session replacement requires explicit person authorization" });
     if (stopping) return Promise.resolve({ ok: false, error: "hub is stopping" });
     if (!membershipAllowed(peer)) return Promise.resolve({ ok: false, error: `${peer} is off roster; a person can add it with ahub roster add ${peer}` });
     if (rosterChanging === peer) return Promise.resolve({ ok: false, error: `${peer} roster change is in progress` });
@@ -2544,7 +2556,7 @@ export async function startDaemon(opts: DaemonOptions) {
     };
   }
 
-  async function startPeerOnce(peer: string, args: { model?: string; route?: string; mode?: "headless" | "tui"; backend?: "auto" | "dgx" | "mlx"; sessionId?: string; sessionFile?: string; fresh?: boolean; unattended?: boolean; providerProfile?: string }): Promise<Record<string, unknown>> {
+  async function startPeerOnce(peer: string, args: { model?: string; route?: string; mode?: "headless" | "tui"; backend?: "auto" | "dgx" | "mlx"; sessionId?: string; sessionFile?: string; replaceSession?: boolean; fresh?: boolean; unattended?: boolean; providerProfile?: string }): Promise<Record<string, unknown>> {
     let unmute: (() => void) | undefined;
     try {
       return await startPeerBody(peer, args, (p) => { unmute = muteState(p); });
@@ -2553,7 +2565,7 @@ export async function startDaemon(opts: DaemonOptions) {
     }
   }
 
-  async function startPeerBody(peer: string, args: { model?: string; route?: string; mode?: "headless" | "tui"; backend?: "auto" | "dgx" | "mlx"; sessionId?: string; sessionFile?: string; fresh?: boolean; unattended?: boolean; providerProfile?: string }, mute: (p: PeerAdapter) => void): Promise<Record<string, unknown>> {
+  async function startPeerBody(peer: string, args: { model?: string; route?: string; mode?: "headless" | "tui"; backend?: "auto" | "dgx" | "mlx"; sessionId?: string; sessionFile?: string; replaceSession?: boolean; fresh?: boolean; unattended?: boolean; providerProfile?: string }, mute: (p: PeerAdapter) => void): Promise<Record<string, unknown>> {
     if (peer === "jcode" && args.mode !== undefined && args.mode !== "headless") return { ok: false, error: "Jcode native TUI driving is unverified; use headless" };
     if (peer === "qwen" && args.mode !== undefined && args.mode !== "headless") return { ok: false, error: "Qwen TUI is not offered before its native verification; use ahub qwen --mode headless" };
     if (peer === "kimi") {
@@ -2581,7 +2593,18 @@ export async function startDaemon(opts: DaemonOptions) {
       if (args.model !== undefined && !["dgx/coding", "dgx/fast", "mlx/fast"].includes(args.model)) return { ok: false, error: "unknown Pi model alias" };
     }
     const existing = bus.peers.get(peer);
-    if (peer === "pi" && existing instanceof PiPeer) {
+    if (args.replaceSession) {
+      if (recoveryActive()) return { ok: false, error: "recovery is holding session replacement" };
+      if (!args.sessionFile || args.sessionId || args.fresh) return { ok: false, error: "Pi replacement requires --replace-session --session-file <managed-file>, without --session-id or fresh" };
+      if (!(existing instanceof PiPeer) || !existing.replacementReady || piReceipts?.unsettled || [...permissions.values()].some(p => p.peer === "pi")) return { ok: false, error: "Pi replacement requires an existing offline, settled owner with no live/unknown process, tools, receipts or approvals" };
+      const selected = validatePiSession(opts.stateDir, opts.cwd, args.sessionFile);
+      const previous = existing.recoveryMetadata();
+      recordPiReplacement(opts.stateDir, instanceId, previous, selected);
+      args = { ...args, ...selected };
+      mute(existing);
+      await stopPiForReplacement(existing);
+    }
+    if (peer === "pi" && existing instanceof PiPeer && !args.replaceSession) {
       let saved = existing.recoveryMetadata();
       const launch = saved.launch as Record<string, unknown>;
       if ((args.sessionId && saved.sessionId && args.sessionId !== saved.sessionId) || (args.sessionFile && saved.sessionFile && args.sessionFile !== saved.sessionFile)) return { ok: false, error: "Pi already owns a different session; refusing to replace its identity" };
@@ -3876,6 +3899,9 @@ export async function startDaemon(opts: DaemonOptions) {
         writeStatus(); // the claim has to be visible before the preface, or a standing-by session takes the id back
         void ensurePreface(c.peer).finally(() => {
           if (sock.readyState === WebSocket.OPEN && membershipAllowed(c.peer!)) ws.attach(sock);
+          // Important work queued while no session held the id gets its nudge now (#398); a push session ignores it.
+          const important = ws.owns(sock) ? bus.queuedImportant(c.peer!) : 0;
+          if (important) ws.notifyQueued({ queued: bus.queued(c.peer!), important });
         });
       }
       return void reply({ t: "welcome", projectId, instanceId, cwd: opts.cwd, protocol: PROTOCOL });
@@ -3935,7 +3961,7 @@ export async function startDaemon(opts: DaemonOptions) {
           peer.lastInboxAt = Date.now();
           writeStatus();
           if (envs.length) log(`${peer.id} read ${envs.length} queued message(s) through hub_inbox`);
-          return void reply({ ok: true, envs, waiting: bus.queued(peer.id) });
+          return void reply({ ok: true, envs, waiting: bus.queued(peer.id), waitingImportant: bus.queuedImportant(peer.id) });
         } catch { return void reply({ ok: false, error: "delivery journal unavailable" }); }
       }
       case "delivery_complete": {
@@ -4181,7 +4207,7 @@ export async function startDaemon(opts: DaemonOptions) {
           writeStatus();
           // #269: `ahub ui --settings` is the same person's command; its ticket marks the session it opens.
           if (msg.settings === true) notify("settings session opened from ahub ui --settings: for 15 minutes that dashboard session may change permission modes, routing and start settings");
-          return void reply({ t: "ui", ok: true, url: dashboard.issue(msg.settings === true), ...(msg.settings === true ? { settings: true } : {}) });
+          return void reply({ t: "ui", ok: true, url: dashboard.issue(msg.settings === true, msg.liveTest === true), ...(msg.settings === true ? { settings: true } : {}), ...(msg.liveTest === true ? { liveTest: true } : {}) });
         } catch {
           return void reply({ t: "ui", ok: false, error: "could not start the dashboard" });
         }
@@ -4255,7 +4281,7 @@ export async function startDaemon(opts: DaemonOptions) {
         if (c.role !== "console") return void reply({ t: "started", ok: false, error: "start is a console command; use hub_peer_start with the conductor role" });
         if (recoveryActive() && !(recoveryPhase === "restored" && msg.operationId === recoveryOperationId)) return void reply({ t: "started", ok: false, error: "recovery is holding mutations" });
         if (recoveryActive() && !recoveryPeerAllowed(String(msg.peer))) return void reply({ t: "started", ok: false, error: "peer is not part of the recovery roster" });
-        startPeer(String(msg.peer), msg.args ?? {})
+        startPeer(String(msg.peer), msg.args ?? {}, msg.args?.replaceSession === true ? piReplacementAuthority : undefined)
           .catch((e: Error) => ({ ok: false, error: e.message }))
           .then((r) => {
             if (!r.ok) log(`start ${msg.peer} failed: ${r.error}`);

package/src/hub/events.ts

@@ -43,7 +43,7 @@ export type HubEvent =
   | ({ type: "turn_end"; peer: string; turn: string; ms: number; tokens?: number; files?: number; snapshotMs?: number; preparedRoles?: RoleIdentity[] | null } & Partial<TaskAttribution>)
   | { type: "native_turn_end"; peer: string; id?: string }
   | { type: "conduct"; peer: string; action: string; task?: number; target?: string }
-  | { type: "agent_cli"; peer: string; command: string; refused: boolean }
+  | { type: "agent_cli"; peer: string; command: string; refused: boolean; delegated?: true }
   | { type: "permission"; id: string; peer: string; event: "requested" | "answered" | "expired" | "cancelled"; latencyMs?: number; surface?: "console" | "dashboard" | "terminal"; option?: "allow_once" | "allow_always" | "reject_once" | "reject_always" }
   /** Completed native turns that received supervision, not feed enqueues or inferred costs. */
   | { type: "supervision_turn"; peer: string; turn: string; tokens?: number; ms?: number }

package/src/hub/lifecycle.ts

@@ -138,7 +138,7 @@ export async function runProjectDaemon(project: Project, unattended = false): Pr
   }
 }
 
-export async function startProject(project: Project, options: { unattended?: boolean; env?: NodeJS.ProcessEnv } = {}): Promise<any> {
+export async function startProject(project: Project, options: { unattended?: boolean; env?: NodeJS.ProcessEnv; liveTest?: boolean } = {}): Promise<any> {
   assertLifecycleAvailable();
   const registry = new Registry();
   try {
@@ -160,7 +160,7 @@ export async function startProject(project: Project, options: { unattended?: boo
         // Native sessions can outlive the operation which launched them. An expired
         // operation ID must not make a later ordinary startup load a retired snapshot.
         if (launchEnv.AGENTHUB_RECOVERY_OPERATION !== recoveryLock()) delete launchEnv.AGENTHUB_RECOVERY_OPERATION;
-        const child = spawn(process.execPath, [join(import.meta.dir, "../cli/main.ts"), "--project", project.root, "daemon",
+        const child = spawn(process.execPath, [join(import.meta.dir, "../cli/main.ts"), "--project", project.root, ...(options.liveTest ? ["--live-test"] : []), "daemon",
           ...(options.unattended ? ["--unattended"] : [])], {
           cwd: project.root, detached: true, stdio: ["ignore", log, log],
           env: { ...launchEnv, AGENTHUB_STATE_DIR: project.stateDir, AGENTHUB_PROJECT_DIR: project.root,

package/src/hub/manager.ts

@@ -21,12 +21,12 @@ export type Lifecycle = {
   startProject(project: Project, options?: { unattended?: boolean; env?: NodeJS.ProcessEnv }): Promise<any>;
   stopProject(project: Project, expectedInstance?: string): Promise<void>;
 };
-export type ManagerOptions = { registry?: Registry; lifecycle?: Lifecycle; home?: string; cli?: string; orphanWatchMs?: number;
+export type ManagerOptions = { registry?: Registry; lifecycle?: Lifecycle; home?: string; cli?: string; orphanWatchMs?: number; liveTest?: boolean;
   /** Test clock seam: maps nominal forwarding deadlines, never comes from dashboard input. */
   forwardTimeoutMs?: (action: string, nominalMs: number) => number };
 type ManagerHandle = { stop(): Promise<void>; stopped: Promise<void> };
 type Manifest = { port: number; protocol: number; instanceId: string; pid: number; pidSignature?: string };
-const active = new Map<string, { handle: ManagerHandle; issue(): string }>();
+const active = new Map<string, { handle: ManagerHandle; issue(liveTest?: boolean): string }>();
 const CONTROL_TIMEOUT = 3000;
 // A current CLI may authenticate the previous protocol-9 manager while
 // refreshing it, then launch the current manager implementation.
@@ -178,7 +178,7 @@ export async function startManager(options: ManagerOptions = {}): Promise<Manage
     };
     dashboard = startDashboard({ projects: list, snapshot: (after, input = {}) => act({ ...input, action: "snapshot", after }), action: act });
     server = Bun.serve({ hostname: "127.0.0.1", port: 0, maxRequestBodySize: 1024,
-      fetch(req) {
+      async fetch(req) {
         if (req.headers.has("origin")) return new Response("forbidden", { status: 403 });
         if (req.headers.get("authorization") !== `Bearer ${token}`) return new Response("unauthorized", { status: 401 });
         if (req.method !== "POST") return new Response("POST required", { status: 405 });
@@ -186,7 +186,10 @@ export async function startManager(options: ManagerOptions = {}): Promise<Manage
         if (expected && expected !== instanceId) return Response.json({ ok: false, error: "manager instance changed" }, { status: 409 });
         if (stopping) return Response.json({ ok: false, error: "manager is stopping" }, { status: 409 });
         const path = new URL(req.url).pathname;
-        if (path === "/open") return Response.json({ ok: true, instanceId, protocol: PROTOCOL, url: dashboard!.issue() });
+        if (path === "/open") {
+          const input = await req.json().catch(() => ({})) as { liveTest?: boolean };
+          return Response.json({ ok: true, instanceId, protocol: PROTOCOL, url: dashboard!.issue(false, input.liveTest === true), ...(input.liveTest === true ? { liveTest: true } : {}) });
+        }
         if (path === "/stop") { setTimeout(() => void stop(), 0); return Response.json({ ok: true, instanceId }); }
         return new Response("not found", { status: 404 });
       },
@@ -204,31 +207,32 @@ export async function startManager(options: ManagerOptions = {}): Promise<Manage
     }, options.orphanWatchMs ?? 10_000);
     orphanWatch.unref?.();
     const handle = { stop, stopped };
-    active.set(home, { handle, issue: () => dashboard!.issue() });
+    active.set(home, { handle, issue: (liveTest) => dashboard!.issue(false, liveTest) });
     return handle;
   } catch (error) { cleanup(); throw error; }
 }
 
-async function managerRequest(home: string, path: "/open" | "/stop"): Promise<{ status: Manifest; body: any }> {
+async function managerRequest(home: string, path: "/open" | "/stop", liveTest = false): Promise<{ status: Manifest; body: any }> {
   const status = readManifest(home);
   if (!status) throw new Error("manager manifest is unavailable");
   if (!SUPPORTED_MANAGER_PROTOCOLS.has(status.protocol)) throw new Error("manager protocol is incompatible; use its matching CLI to stop it");
   const token = readFileSync(files(home).token, "utf8").trim();
   if (!token) throw new Error("manager token is unavailable");
   const response = await fetch(`http://127.0.0.1:${status.port}${path}`, {
-    method: "POST", headers: { authorization: `Bearer ${token}`, "x-agenthub-instance": status.instanceId }, signal: AbortSignal.timeout(CONTROL_TIMEOUT),
+    method: "POST", headers: { authorization: `Bearer ${token}`, "x-agenthub-instance": status.instanceId }, ...(liveTest ? { body: JSON.stringify({ liveTest: true }) } : {}), signal: AbortSignal.timeout(CONTROL_TIMEOUT),
   });
   if (!response.ok) throw new Error(`manager refused request (${response.status}); ownership was not verified`);
   const body = await response.json() as { ok?: boolean; instanceId?: string; url?: string };
   if (!body.ok || body.instanceId !== status.instanceId) throw new Error("manager identity changed; refresh before retrying");
+  if (liveTest && (body as { liveTest?: boolean }).liveTest !== true) throw new Error("manager cannot restrict delegated dashboard content; use a live-test-capable manager");
   return { status, body };
 }
 
 export async function openManager(options: ManagerOptions = {}): Promise<string> {
   const home = options.home ?? hubHome();
   const local = active.get(home);
-  if (local) return local.issue();
-  try { return (await managerRequest(home, "/open")).body.url; }
+  if (local) return local.issue(options.liveTest);
+  try { return (await managerRequest(home, "/open", options.liveTest)).body.url; }
   catch (error) {
     const old = readManifest(home);
     if (old && processLiveness(old.pid, old.pidSignature) !== "gone") throw error;
@@ -246,7 +250,7 @@ export async function openManager(options: ManagerOptions = {}): Promise<string>
   const deadline = Date.now() + 8000;
   let error: unknown;
   while (Date.now() < deadline) {
-    try { return (await managerRequest(home, "/open")).body.url; }
+    try { return (await managerRequest(home, "/open", options.liveTest)).body.url; }
     catch (caught) { error = caught; await Bun.sleep(100); }
   }
   throw new Error(`manager readiness not confirmed: ${safeError(error)}; see ${join(f.dir, "manager.log")}`);

package/src/hub/ui.ts

@@ -10,7 +10,7 @@ import { createHash, randomBytes } from "node:crypto";
 import { readFileSync } from "node:fs";
 
 /** What a request's session may do (#269): `settings` while a session opened by `ahub ui --settings` is inside its window. */
-export interface DashboardSession { settings: boolean; settingsUntil?: number }
+export interface DashboardSession { settings: boolean; settingsUntil?: number; liveTest?: true }
 export interface DashboardOptions {
   snapshot: (after: number, input?: Record<string, unknown>, session?: DashboardSession) => unknown | Promise<unknown>;
   action: (input: Record<string, unknown>, session?: DashboardSession) => unknown | Promise<unknown>;
@@ -30,8 +30,8 @@ const secret = () => randomBytes(32).toString("hex");
 /** Separate browser surface. Only the authenticated control console may construct it and issue tickets. */
 export function startDashboard(options: DashboardOptions) {
   const now = options.now ?? Date.now;
-  const tickets = new Map<string, { expires: number; settings: boolean }>();
-  const sessions = new Map<string, { expires: number; settingsUntil?: number }>();
+  const tickets = new Map<string, { expires: number; settings: boolean; liveTest?: true }>();
+  const sessions = new Map<string, { expires: number; settingsUntil?: number; liveTest?: true }>();
   // Inject the same pure public-board model used by the console before computing CSP hashes.
   const html = readFileSync(new URL("../ui/index.html", import.meta.url), "utf8")
     .replace("/* BOARD_MODEL */", () => `const boardColumns = ${boardColumns.toString()}; const peerPalette = ${JSON.stringify(PEER_PALETTE)};`)
@@ -57,7 +57,7 @@ export function startDashboard(options: DashboardOptions) {
   }
   const sessionOf = (cookie: string | undefined): DashboardSession => {
     const until = cookie ? sessions.get(cookie)?.settingsUntil : undefined;
-    return until !== undefined && until > now() ? { settings: true, settingsUntil: until } : { settings: false };
+    return { ...(until !== undefined && until > now() ? { settings: true, settingsUntil: until } : { settings: false }), ...(cookie && sessions.get(cookie)?.liveTest ? { liveTest: true as const } : {}) };
   };
   const server = Bun.serve({
     hostname: "127.0.0.1",
@@ -99,7 +99,7 @@ export function startDashboard(options: DashboardOptions) {
         if (!issued || !tickets.delete(ticket)) return reject(401, "ticket expired or used; run ahub ui");
         if (sessions.size >= LIMIT) return reject(429, "too many sessions; try later");
         const session = secret();
-        sessions.set(session, { expires: now() + SESSION_MS, ...(issued.settings ? { settingsUntil: now() + SETTINGS_MS } : {}) });
+        sessions.set(session, { expires: now() + SESSION_MS, ...(issued.settings ? { settingsUntil: now() + SETTINGS_MS } : {}), ...(issued.liveTest ? { liveTest: true } : {}) });
         return json({ ok: true }, 200, { "Set-Cookie": `${cookieName}=${session}; HttpOnly; SameSite=Strict; Path=/; Max-Age=${SESSION_MS / 1000}` });
       }
       if (path === "/projects") {
@@ -131,6 +131,9 @@ export function startDashboard(options: DashboardOptions) {
         }
       }
       try {
+        if (sessionOf(cookie).liveTest && !["start", "stop", "pause", "resume", "permit", "start_peer", "setting", "setting_undo", "setting_preview", "sdlc_queue", "sdlc_release"].includes(String(input.action))) {
+          return reject(403, "live-test dashboard cannot write person-attributed content; use peer tools");
+        }
         if (input.action === "sdlc_queue" || input.action === "sdlc_release") server.timeout(req, 35);
         else if (input.action === "backlog_split") server.timeout(req, Math.ceil((BACKLOG_SPLIT_SCREEN_TIMEOUT_MS + HUB_DB_BUSY_TIMEOUT_MS + 5_000) / 1000) + 5);
         return json(await options.action(input, sessionOf(cookie)));
@@ -149,11 +152,11 @@ export function startDashboard(options: DashboardOptions) {
   return {
     origin,
     /** `settings`: the ticket of `ahub ui --settings`, whose session may raise authority for SETTINGS_MS (#269). */
-    issue(settings = false): string {
+    issue(settings = false, liveTest = false): string {
       prune(tickets);
       if (tickets.size >= LIMIT) tickets.delete(tickets.keys().next().value!);
       const ticket = secret();
-      tickets.set(ticket, { expires: now() + TICKET_MS, settings });
+      tickets.set(ticket, { expires: now() + TICKET_MS, settings, ...(liveTest ? { liveTest: true } : {}) });
       return `${origin}/#${ticket}`;
     },
     stop() {

package/src/pi/session.ts

@@ -0,0 +1,28 @@
+import { readFileSync, openSync, closeSync, fsyncSync, mkdirSync } from "node:fs";
+import { join, relative, resolve, dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+import { realPath } from "../hub/project.ts";
+import { atomicPrivateJSON } from "../hub/recovery-store.ts";
+
+/** One validation boundary for ordinary starts and explicit preserved-history selection. */
+export function validatePiSession(stateDir: string, cwd: string, sessionFile: string, sessionId?: string): { sessionFile: string; sessionId: string } {
+  const file = realPath(sessionFile), sessions = realPath(join(stateDir, "pi-sessions"));
+  const rel = relative(sessions, file);
+  if (!rel || rel.startsWith("..") || resolve(sessions, rel) !== file) throw new Error("Pi session file is outside the managed project session directory");
+  const header = JSON.parse(readFileSync(file, "utf8").split("\n", 1)[0]!);
+  if (header.type !== "session" || typeof header.id !== "string" || !header.id || typeof header.cwd !== "string" || realPath(header.cwd) !== realPath(cwd) || (sessionId && header.id !== sessionId)) throw new Error("Pi session header does not match the requested project/session");
+  return { sessionFile: file, sessionId: header.id };
+}
+
+/** The private selection record must reach storage before any prior owner is revoked. No transcript bodies. */
+export function recordPiReplacement(stateDir: string, instanceId: string, previous: Record<string, unknown>, selected: { sessionFile: string; sessionId: string }): string {
+  const directory = join(stateDir, "pi-session-replacements");
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const file = join(directory, `${randomUUID()}.json`);
+  atomicPrivateJSON(file, { schema: 1, at: Date.now(), instanceId, previous, selected });
+  for (const path of [file, directory, dirname(directory)]) {
+    const fd = openSync(path, "r");
+    try { fsyncSync(fd); } finally { closeSync(fd); }
+  }
+  return file;
+}

package/src/pi/tool-receipts.ts

@@ -64,6 +64,7 @@ export class PiToolReceipts {
     return work;
   }
 
+  get unsettled(): boolean { return this.pending.size > 0 || !!this.db.query("SELECT 1 FROM pi_tool_receipts WHERE state != 'done' LIMIT 1").get(); }
   get inFlight(): number { return this.pending.size; }
   async drain(): Promise<void> { await Promise.allSettled(this.pending.values()); }