@staix/agent-hub 0.12.41 → 0.12.43

package/plugins/agent-hub/server.js

@@ -4300,7 +4300,7 @@ function ownerStillAlive(pid, signature) {
     return false;
   }
 }
-var PiToolSettlementFailure, PiPromptNotStarted, PiPromptUncertain, PiPeer;
+var PiToolSettlementFailure, PiPromptNotStarted, PiPromptUncertain, TERMINAL_OWNER_MAX_AGE_MS = 1000, PiPeer;
 var init_pi = __esm(() => {
   init_launch();
   init_envelope();
@@ -4381,6 +4381,7 @@ var init_pi = __esm(() => {
     ownerPid;
     ownerSignature;
     ownerMonitor;
+    terminalOwnerObservation;
     tuiExit;
     resolveTuiExit;
     tuiCommands = new Map;
@@ -4409,7 +4410,7 @@ var init_pi = __esm(() => {
       if (this.opts.mode === "headless")
         return this.state === "idle" || !this.proc || this.proc.exitCode !== null || this.proc.signalCode !== null;
       if (this.state === "idle")
-        return this.ownerClaimed && !!this.ownerPid && processSignature(this.ownerPid) === this.ownerSignature;
+        return this.ownerClaimed && !!this.ownerPid && this.readOwnerSignature(this.ownerPid) === this.ownerSignature;
       return this.stopping && !this.ownerClaimed && (!this.ownerPid || !ownerStillAlive(this.ownerPid, this.ownerSignature));
     }
     get replacementReady() {
@@ -4633,6 +4634,7 @@ var init_pi = __esm(() => {
       return Response.json({ decisions, ...reservation ? { reservation } : {} });
     }
     async startImpl() {
+      this.terminalOwnerObservation = undefined;
       this.stopping = false;
       this.rosterDetached = false;
       this.rosterUnownedRun = false;
@@ -4687,7 +4689,7 @@ var init_pi = __esm(() => {
             return Response.json({ ok: false, error: "Pi session identity is missing" }, { status: 400 });
           if (body.type === "session_start" && this.ownerClaimed && (body.ownerToken !== this.ownerToken || body.pid !== this.ownerPid || body.signature !== this.ownerSignature || this.sessionId && body.sessionId !== this.sessionId || this.sessionFile && body.sessionFile !== this.sessionFile))
             return Response.json({ ok: false, error: "Pi session owner or identity already claimed" }, { status: 409 });
-          if (body.type === "session_start" && (!Number.isInteger(body.pid) || !body.signature || processSignature(body.pid) !== body.signature))
+          if (body.type === "session_start" && (!Number.isInteger(body.pid) || !body.signature || this.readOwnerSignature(body.pid) !== body.signature))
             return Response.json({ ok: false, error: "Pi process identity is not verified" }, { status: 409 });
           this.handleBridgeEvent(body);
           return Response.json({ ok: true });
@@ -4743,7 +4745,7 @@ var init_pi = __esm(() => {
       this.sessionId = state.data.sessionId;
       this.sessionFile = state.data.sessionFile;
       if (!this.ownerClaimed) {
-        const pid = this.proc?.pid, signature = pid ? processSignature(pid) : undefined;
+        const pid = this.proc?.pid, signature = pid ? this.readOwnerSignature(pid) : undefined;
         if (!pid || !signature)
           throw new Error("Pi headless owner process identity is not verified");
         this.ownerPid = pid;
@@ -4757,11 +4759,27 @@ var init_pi = __esm(() => {
       this.started = true;
       this.setState("idle");
     }
+    readOwnerSignature(pid) {
+      return (this.opts.signature ?? processSignature)(pid);
+    }
     verifiedOwner() {
-      return this.ownerClaimed && !!this.ownerPid && !!this.ownerSignature && processSignature(this.ownerPid) === this.ownerSignature;
+      return this.ownerClaimed && !!this.ownerPid && !!this.ownerSignature && this.readOwnerSignature(this.ownerPid) === this.ownerSignature;
+    }
+    rememberTerminalOwner() {
+      if (!this.ownerClaimed || !this.ownerPid || !this.ownerSignature)
+        return;
+      this.terminalOwnerObservation = {
+        pid: this.ownerPid,
+        signature: this.ownerSignature,
+        sessionId: this.sessionId,
+        sessionFile: this.sessionFile,
+        ownerToken: this.ownerToken,
+        checkedAt: performance.now()
+      };
     }
     terminalOwner(_launchId) {
-      if (this.opts.mode !== "tui" || !this.started || this.stopping || this.rosterDetached || !this.verifiedOwner() || !this.sessionId || !this.sessionFile || this.opts.sessionId && this.opts.sessionId !== this.sessionId || this.opts.sessionFile && this.opts.sessionFile !== this.sessionFile)
+      const observed = this.terminalOwnerObservation;
+      if (this.opts.mode !== "tui" || !this.started || this.stopping || this.rosterDetached || this.state === "offline" || !this.ownerClaimed || !observed || performance.now() - observed.checkedAt > TERMINAL_OWNER_MAX_AGE_MS || observed.pid !== this.ownerPid || observed.signature !== this.ownerSignature || observed.sessionId !== this.sessionId || observed.sessionFile !== this.sessionFile || observed.ownerToken !== this.ownerToken || !this.sessionId || !this.sessionFile || this.opts.sessionId && this.opts.sessionId !== this.sessionId || this.opts.sessionFile && this.opts.sessionFile !== this.sessionFile)
         return;
       const generation = this.sessionGeneration;
       return generation && this.ownerPid ? { generation, nativePid: this.ownerPid } : undefined;
@@ -4780,6 +4798,7 @@ var init_pi = __esm(() => {
     async detachForRoster() {
       if (this.opts.mode !== "tui")
         throw new Error("Pi roster detach requires a personal TUI");
+      this.terminalOwnerObservation = undefined;
       this.rosterDetached = true;
       this.rosterEpoch++;
       this.setState("offline");
@@ -4841,6 +4860,7 @@ var init_pi = __esm(() => {
       if (reason !== undefined)
         this.requestedStopReason = reason;
       this.rosterEpoch++;
+      this.terminalOwnerObservation = undefined;
       this.stopping = true;
       for (const id of this.activeDeliveryIds)
         this.delivery({ id, state: "needs_review", reason: reason ?? "Pi session stopped before settlement" });
@@ -5159,6 +5179,7 @@ var init_pi = __esm(() => {
           this.opts.log?.(`[${this.id}] Pi session identity mismatch`);
           return;
         }
+        this.rememberTerminalOwner();
         this.startOwnerMonitor();
         if (this.opts.mode === "tui") {
           this.started = true;
@@ -5177,7 +5198,7 @@ var init_pi = __esm(() => {
         if (this.opts.mode === "tui")
           this.reportExit(exit);
       }
-      if (event.type === "tool_abort" && this.agentRunning && this.ownerClaimed && this.ownerPid && this.ownerSignature && processSignature(this.ownerPid) === this.ownerSignature && event.sessionId === this.sessionId && event.generation === this.budgetGeneration && typeof event.toolCallId === "string" && event.toolCallId.length > 0 && event.toolCallId.length <= 512) {
+      if (event.type === "tool_abort" && this.agentRunning && this.ownerClaimed && this.ownerPid && this.ownerSignature && this.readOwnerSignature(this.ownerPid) === this.ownerSignature && event.sessionId === this.sessionId && event.generation === this.budgetGeneration && typeof event.toolCallId === "string" && event.toolCallId.length > 0 && event.toolCallId.length <= 512) {
         const pending = this.pendingToolGenerations.get(event.toolCallId);
         if (pending && pending.generation === event.generation)
           pending.abort.abort();
@@ -5416,6 +5437,7 @@ var init_pi = __esm(() => {
       } catch {}
     }
     fail(error) {
+      this.terminalOwnerObservation = undefined;
       const approvalStopReason = this.approvalStopReason;
       this.abortTools();
       this.agentRunning = false;
@@ -5445,24 +5467,39 @@ var init_pi = __esm(() => {
       this.clearOwnerMonitor();
       if (this.opts.mode !== "tui" || !this.ownerPid || !this.ownerSignature)
         return;
-      this.ownerMonitor = setInterval(() => {
-        if (!this.ownerPid || ownerStillAlive(this.ownerPid, this.ownerSignature))
-          return;
-        const exit = this.exitMetadata("owner_lost");
-        this.stopping = true;
-        this.ownerClaimed = false;
-        this.clearOwnerMonitor();
-        this.resolveTuiExit?.();
-        this.resolveTuiExit = undefined;
-        for (const pending of this.tuiCommands.values())
-          pending.reject(new Error("Pi owner exited"));
-        this.tuiCommands.clear();
-        this.tuiQueue = [];
-        this.fail(new Error("Pi owner process exited without session_shutdown"));
-        this.reportExit(exit);
-      }, 500);
+      this.ownerMonitor = setInterval(() => this.checkOwner(), 500);
       this.ownerMonitor.unref?.();
     }
+    checkOwner() {
+      if (!this.ownerPid) {
+        this.terminalOwnerObservation = undefined;
+        return;
+      }
+      const current = this.readOwnerSignature(this.ownerPid);
+      if (current !== undefined && current === this.ownerSignature) {
+        this.rememberTerminalOwner();
+        return;
+      }
+      this.terminalOwnerObservation = undefined;
+      if (current === undefined) {
+        try {
+          process.kill(this.ownerPid, 0);
+          return;
+        } catch {}
+      }
+      const exit = this.exitMetadata("owner_lost");
+      this.stopping = true;
+      this.ownerClaimed = false;
+      this.clearOwnerMonitor();
+      this.resolveTuiExit?.();
+      this.resolveTuiExit = undefined;
+      for (const pending of this.tuiCommands.values())
+        pending.reject(new Error("Pi owner exited"));
+      this.tuiCommands.clear();
+      this.tuiQueue = [];
+      this.fail(new Error("Pi owner process exited without session_shutdown"));
+      this.reportExit(exit);
+    }
     clearOwnerMonitor() {
       if (this.ownerMonitor)
         clearInterval(this.ownerMonitor);
@@ -7868,7 +7905,7 @@ var init_hub_tools = __esm(() => {
   CONDUCTOR_TOOLS = [
     tool("hub_status", "Inspect public team state, holds, quota windows, task counts and pending approval peer/tool/age. Only the configured conductor may use this tool.", {}),
     tool("hub_task_show", "Read a task's public view and history, its done summary and check result included. PII tasks remain stubs. Only the conductor and the task's current owner and reviewer may use this tool.", { id }, ["id"]),
-    tool("hub_task_assign", "Name an owner (default role) or reviewer. Only the conductor may name a reviewer through this tool. A proposer may redirect an unaccepted proposed task's owner; a task that still waits reserves that owner. Pull-only peers receive work when named or when they claim it. With an explicit capabilities list, the conductor needs assign capability for either role, the proposer only to give ownership to another peer.", { id, peer: str2, role: { type: "string", enum: ["owner", "reviewer"] } }, ["id", "peer"]),
+    tool("hub_task_assign", "Name an owner (default role) or reviewer. Only the conductor may name a reviewer through this tool. A proposer may redirect an unaccepted proposed task's owner; a task that still waits reserves that owner. Pull-only peers receive work when named while attached or when they claim it; a peer that cannot take the task is refused with the reason, and the task is unchanged. With an explicit capabilities list, the conductor needs assign capability for either role, the proposer only to give ownership to another peer.", { id, peer: str2, role: { type: "string", enum: ["owner", "reviewer"] } }, ["id", "peer"]),
     tool("hub_task_escalate", "Escalate a task through the normal task flow, as the conductor. Requires assign capability when explicitly listed.", { id }, ["id"]),
     tool("hub_peer_start", "Start local, kimi, qwen, jcode, pi, claude or codex in the start mode a person set for it; you cannot choose the mode. A headless peer starts at once. A TUI peer (claude, and pi and codex by default) opens in a terminal with a fixed command; when the hub cannot open a terminal the call fails with the command for the person to run.", { peer: { type: "string", enum: CONDUCTOR_START_PEERS } }, ["peer"]),
     tool("hub_peer_hold", "Hold a peer's deliveries as the conductor. This hold is separate from the person's hold and budget pauses.", { peer: str2 }, ["peer"]),
@@ -8562,7 +8599,9 @@ function decodeAgyHook(event, value) {
   if ((event === "PreToolUse" || event === "PostToolUse") && (!call || typeof call.name !== "string" || call.name.length > 128 || !record3(call.args)))
     return;
   const native = call?.args;
-  const observedRead = call?.name === "view_file" && typeof native?.AbsolutePath === "string";
+  const readPath = call?.name === "view_file" ? native?.AbsolutePath : call?.name === "read_file" ? native?.Path : undefined;
+  const observedRead = typeof readPath === "string";
+  const range = observedRead && Number.isSafeInteger(native?.StartLine) && native.StartLine > 0 ? { offset: native.StartLine, ...Number.isSafeInteger(native?.EndLine) && native.EndLine >= native.StartLine ? { limit: native.EndLine - native.StartLine + 1 } : {} } : {};
   const phase = { SessionStart: "session", PreInvocation: "start", PostInvocation: "post", PreToolUse: "pre", PostToolUse: "post", Stop: "stop" }[event];
   return {
     event,
@@ -8571,7 +8610,7 @@ function decodeAgyHook(event, value) {
     transcriptPath: value.transcriptPath,
     workspacePaths: value.workspacePaths,
     tool: observedRead ? "Read" : typeof call?.name === "string" ? call.name : "",
-    input: observedRead ? { file_path: native.AbsolutePath } : native ?? {},
+    input: observedRead ? { file_path: readPath, ...range } : native ?? {},
     ...Number.isSafeInteger(value.stepIdx) && value.stepIdx >= 0 ? { toolUseId: `${value.conversationId}:${value.stepIdx}` } : {},
     ...Number.isSafeInteger(value.invocationNum) && value.invocationNum >= 0 ? { invocation: value.invocationNum } : {},
     ...event === "Stop" ? { fullyIdle: value.fullyIdle, terminationReason: typeof value.terminationReason === "string" ? value.terminationReason : "" } : {}
@@ -9190,6 +9229,14 @@ function runAgyTui(argv, cwd, env) {
     });
   });
 }
+function agyVersionGate(stdout) {
+  const version = stdout.trim();
+  if (version === "1.4.2")
+    return { ok: true };
+  if (/^1\.4\.\d+$/.test(version))
+    return { ok: true, message: `agy ${version}: only 1.4.2 is T0-verified; launching on the 1.4.x line unverified` };
+  return { ok: false, message: "agy P1 requires the Antigravity CLI 1.4.x line (1.4.2 verified)" };
+}
 async function runAgyEntry(ctx) {
   const { args, cwd, stateDir, cliDir, connect, fail } = ctx;
   if (ctx.instance)
@@ -9207,8 +9254,11 @@ async function runAgyEntry(ctx) {
     return;
   }
   const version = spawnSync4("agy", ["--version"], { encoding: "utf8", timeout: 5000, maxBuffer: 4096, env: peerChildEnv("agy") });
-  if (version.status !== 0 || version.stdout.trim() !== "1.4.2")
-    fail("agy P1 requires the verified Antigravity CLI 1.4.2");
+  const gate = agyVersionGate(version.status === 0 ? version.stdout : "");
+  if (!gate.ok)
+    fail(gate.message);
+  if (gate.message)
+    console.error(gate.message);
   const hub = await connect();
   let options;
   let pluginWritten = false;
@@ -18416,7 +18466,7 @@ init_spec_read();
 // package.json
 var package_default = {
   name: "@staix/agent-hub",
-  version: "0.12.41",
+  version: "0.12.43",
   description: "Native multi-agent hub: Claude Code, Codex, Kimi Code, Pi and local inference as peers in one project",
   license: "MIT",
   type: "module",

package/src/adapters/agy/entry.ts

@@ -33,6 +33,14 @@ function runAgyTui(argv: string[], cwd: string, env: NodeJS.ProcessEnv): Promise
   });
 }
 
+/** agy auto-updates, so the 1.4.x line launches; only 1.4.2 has a T0 receipt and other patches warn (#589). */
+export function agyVersionGate(stdout: string): { ok: true; message?: string } | { ok: false; message: string } {
+  const version = stdout.trim();
+  if (version === "1.4.2") return { ok: true };
+  if (/^1\.4\.\d+$/.test(version)) return { ok: true, message: `agy ${version}: only 1.4.2 is T0-verified; launching on the 1.4.x line unverified` };
+  return { ok: false, message: "agy P1 requires the Antigravity CLI 1.4.x line (1.4.2 verified)" };
+}
+
 export async function runAgyEntry(ctx: NativeCliEntryContext): Promise<void> {
   const { args, cwd, stateDir, cliDir, connect, fail } = ctx;
   if (ctx.instance) fail("extra Antigravity TUI instances are not verified in P1");
@@ -45,7 +53,9 @@ export async function runAgyEntry(ctx: NativeCliEntryContext): Promise<void> {
   const argv = nativeArgs;
   if (preview) { console.log(JSON.stringify({ command: "agy", args: argv.map(publicArg), mode: "tui", permission: "unmanaged", mcp: ".agents/plugins/agent-hub/", writes: false })); return; }
   const version = spawnSync("agy", ["--version"], { encoding: "utf8", timeout: 5000, maxBuffer: 4096, env: peerChildEnv("agy") });
-  if (version.status !== 0 || version.stdout.trim() !== "1.4.2") fail("agy P1 requires the verified Antigravity CLI 1.4.2");
+  const gate = agyVersionGate(version.status === 0 ? version.stdout : "");
+  if (!gate.ok) fail(gate.message);
+  if (gate.message) console.error(gate.message);
   const hub = await connect();
   let options: AgyMcpOptions | undefined;
   let pluginWritten = false;

package/src/adapters/agy/hooks.ts

@@ -19,10 +19,15 @@ export function decodeAgyHook(event: string, value: unknown): NativeFactsInput |
   if ((event === "PreToolUse" || event === "PostToolUse") && (!call || typeof call.name !== "string" || call.name.length > 128 || !record(call.args))) return;
   const native = call?.args as Record<string, unknown> | undefined;
   // Only the observed native read is classified. Unobserved edits never receive a scoped grant or effect attribution.
-  const observedRead = call?.name === "view_file" && typeof native?.AbsolutePath === "string";
+  // 1.4.2 names it view_file(AbsolutePath); 1.4.3 renamed it read_file(Path, optional StartLine/EndLine).
+  const readPath = call?.name === "view_file" ? native?.AbsolutePath : call?.name === "read_file" ? native?.Path : undefined;
+  const observedRead = typeof readPath === "string";
+  // A line range is a partial read: carry it as offset/limit so it never counts as a whole-file view.
+  const range = observedRead && Number.isSafeInteger(native?.StartLine) && (native!.StartLine as number) > 0
+    ? { offset: native!.StartLine as number, ...(Number.isSafeInteger(native?.EndLine) && (native!.EndLine as number) >= (native!.StartLine as number) ? { limit: (native!.EndLine as number) - (native!.StartLine as number) + 1 } : {}) } : {};
   const phase = ({ SessionStart: "session", PreInvocation: "start", PostInvocation: "post", PreToolUse: "pre", PostToolUse: "post", Stop: "stop" } as const)[event as typeof EVENTS[number]];
   return { event: event as NativeFactsInput["event"], phase, sessionId: value.conversationId, transcriptPath: value.transcriptPath,
-    workspacePaths: value.workspacePaths as string[], tool: observedRead ? "Read" : typeof call?.name === "string" ? call.name : "", input: observedRead ? { file_path: native!.AbsolutePath } : native ?? {},
+    workspacePaths: value.workspacePaths as string[], tool: observedRead ? "Read" : typeof call?.name === "string" ? call.name : "", input: observedRead ? { file_path: readPath, ...range } : native ?? {},
     ...(Number.isSafeInteger(value.stepIdx) && (value.stepIdx as number) >= 0 ? { toolUseId: `${value.conversationId}:${value.stepIdx}` } : {}),
     ...(Number.isSafeInteger(value.invocationNum) && (value.invocationNum as number) >= 0 ? { invocation: value.invocationNum as number } : {}),
     ...(event === "Stop" ? { fullyIdle: value.fullyIdle as boolean, terminationReason: typeof value.terminationReason === "string" ? value.terminationReason : "" } : {}) };

package/src/adapters/pi.ts

@@ -52,10 +52,14 @@ export interface PiOptions {
   onApprovalStop?: (reason: string) => void;
   /** How long stop() waits for a graceful TUI owner exit before verified teardown. Tests shrink this. */
   stopGraceMs?: number;
+  /** Host process-identity reader; never supplied by bridge events or peer config. */
+  signature?: typeof processSignature;
 }
 export interface PiTuiLaunch { cmd: string; args: string[]; env: NodeJS.ProcessEnv; }
 type RpcMessage = { type?: string; id?: string | number; command?: string; success?: boolean; data?: any; [key: string]: any };
 type VerifiedEmptyResume = { sessionId: string };
+type TerminalOwnerObservation = { pid: number; signature: string; sessionId: string; sessionFile: string; ownerToken: string; checkedAt: number };
+const TERMINAL_OWNER_MAX_AGE_MS = 1_000;
 function ownerStillAlive(pid: number, signature: string | undefined): boolean { const current = processSignature(pid); if (current !== undefined) return current === signature; try { process.kill(pid, 0); return true; } catch { return false; } }
 
 
@@ -121,6 +125,7 @@ export class PiPeer extends BasePeer {
   private ownerPid?: number;
   private ownerSignature?: string;
   private ownerMonitor?: ReturnType<typeof setInterval>;
+  private terminalOwnerObservation?: TerminalOwnerObservation;
   private tuiExit?: Promise<void>;
   private resolveTuiExit?: () => void;
   private tuiCommands = new Map<string, { command: Record<string, unknown>; resolve: (value: any) => void; reject: (error: Error) => void }>();
@@ -139,7 +144,7 @@ export class PiPeer extends BasePeer {
     if (this.state === "busy" || this.starting || this.activeTools) return false;
     if (this.sessionFile && !existsSync(this.sessionFile) && (this.activityObserved || this.persistedOnce)) return false;
     if (this.opts.mode === "headless") return this.state === "idle" || !this.proc || this.proc.exitCode !== null || this.proc.signalCode !== null;
-    if (this.state === "idle") return this.ownerClaimed && !!this.ownerPid && processSignature(this.ownerPid) === this.ownerSignature;
+    if (this.state === "idle") return this.ownerClaimed && !!this.ownerPid && this.readOwnerSignature(this.ownerPid) === this.ownerSignature;
     return this.stopping && !this.ownerClaimed && (!this.ownerPid || !ownerStillAlive(this.ownerPid, this.ownerSignature));
   }
   /** Explicit replacement may retain an unpersisted identity, but never a live/unknown owner or active effects. */
@@ -337,6 +342,7 @@ export class PiPeer extends BasePeer {
   }
 
   private async startImpl(): Promise<void> {
+    this.terminalOwnerObservation = undefined;
     this.stopping = false;
     this.rosterDetached = false; this.rosterUnownedRun = false;
     this.requestedStopReason = undefined;
@@ -366,7 +372,7 @@ export class PiPeer extends BasePeer {
       }
       if (request.method !== "POST") return new Response("method not allowed", { status: 405 });
       const body = await request.json() as any;
-      if (url.pathname === "/event") { if (body.type === "session_start" && this.stopping) return Response.json({ ok: false, error: "Pi launch has ended" }, { status: 409 }); if (body.type === "session_start" && (typeof body.sessionId !== "string" || !body.sessionId || typeof body.sessionFile !== "string" || !body.sessionFile)) return Response.json({ ok: false, error: "Pi session identity is missing" }, { status: 400 }); if (body.type === "session_start" && this.ownerClaimed && (body.ownerToken !== this.ownerToken || body.pid !== this.ownerPid || body.signature !== this.ownerSignature || (this.sessionId && body.sessionId !== this.sessionId) || (this.sessionFile && body.sessionFile !== this.sessionFile))) return Response.json({ ok: false, error: "Pi session owner or identity already claimed" }, { status: 409 }); if (body.type === "session_start" && (!Number.isInteger(body.pid) || !body.signature || processSignature(body.pid) !== body.signature)) return Response.json({ ok: false, error: "Pi process identity is not verified" }, { status: 409 }); this.handleBridgeEvent(body); return Response.json({ ok: true }); }
+      if (url.pathname === "/event") { if (body.type === "session_start" && this.stopping) return Response.json({ ok: false, error: "Pi launch has ended" }, { status: 409 }); if (body.type === "session_start" && (typeof body.sessionId !== "string" || !body.sessionId || typeof body.sessionFile !== "string" || !body.sessionFile)) return Response.json({ ok: false, error: "Pi session identity is missing" }, { status: 400 }); if (body.type === "session_start" && this.ownerClaimed && (body.ownerToken !== this.ownerToken || body.pid !== this.ownerPid || body.signature !== this.ownerSignature || (this.sessionId && body.sessionId !== this.sessionId) || (this.sessionFile && body.sessionFile !== this.sessionFile))) return Response.json({ ok: false, error: "Pi session owner or identity already claimed" }, { status: 409 }); if (body.type === "session_start" && (!Number.isInteger(body.pid) || !body.signature || this.readOwnerSignature(body.pid) !== body.signature)) return Response.json({ ok: false, error: "Pi process identity is not verified" }, { status: 409 }); this.handleBridgeEvent(body); return Response.json({ ok: true }); }
       if (url.pathname === "/ack") {
         const pending = this.tuiCommands.get(String(body.id));
         if (!pending) return Response.json({ ok: false }, { status: 404 });
@@ -415,7 +421,7 @@ export class PiPeer extends BasePeer {
     // The hub spawned this headless owner and get_state proved its session. Pin the same
     // identity a native extension claim uses, including fakes that do not load the extension.
     if (!this.ownerClaimed) {
-      const pid = this.proc?.pid, signature = pid ? processSignature(pid) : undefined;
+      const pid = this.proc?.pid, signature = pid ? this.readOwnerSignature(pid) : undefined;
       if (!pid || !signature) throw new Error("Pi headless owner process identity is not verified");
       this.ownerPid = pid; this.ownerSignature = signature;
       this.ownerToken = String(this._tuiLaunch?.env.AGENTHUB_PI_OWNER_TOKEN ?? ""); this.ownerClaimed = true;
@@ -426,12 +432,26 @@ export class PiPeer extends BasePeer {
     this.setState("idle");
   }
 
+  private readOwnerSignature(pid: number): string | undefined { return (this.opts.signature ?? processSignature)(pid); }
+
   private verifiedOwner(): boolean {
-    return this.ownerClaimed && !!this.ownerPid && !!this.ownerSignature && processSignature(this.ownerPid) === this.ownerSignature;
+    return this.ownerClaimed && !!this.ownerPid && !!this.ownerSignature && this.readOwnerSignature(this.ownerPid) === this.ownerSignature;
+  }
+
+  private rememberTerminalOwner(): void {
+    if (!this.ownerClaimed || !this.ownerPid || !this.ownerSignature) return;
+    this.terminalOwnerObservation = { pid: this.ownerPid, signature: this.ownerSignature, sessionId: this.sessionId,
+      sessionFile: this.sessionFile, ownerToken: this.ownerToken, checkedAt: performance.now() };
   }
 
   terminalOwner(_launchId: string): { generation: string; nativePid: number } | undefined {
-    if (this.opts.mode !== "tui" || !this.started || this.stopping || this.rosterDetached || !this.verifiedOwner() || !this.sessionId || !this.sessionFile ||
+    const observed = this.terminalOwnerObservation;
+    // Reconciliation reads the monitor's bounded observation, never spawning ps on its 1 s tick.
+    // Effect admission and teardown keep their fresh process-identity checks.
+    if (this.opts.mode !== "tui" || !this.started || this.stopping || this.rosterDetached || this.state === "offline" ||
+        !this.ownerClaimed || !observed || performance.now() - observed.checkedAt > TERMINAL_OWNER_MAX_AGE_MS ||
+        observed.pid !== this.ownerPid || observed.signature !== this.ownerSignature || observed.sessionId !== this.sessionId ||
+        observed.sessionFile !== this.sessionFile || observed.ownerToken !== this.ownerToken || !this.sessionId || !this.sessionFile ||
         this.opts.sessionId && this.opts.sessionId !== this.sessionId || this.opts.sessionFile && this.opts.sessionFile !== this.sessionFile) return undefined;
     const generation = this.sessionGeneration;
     return generation && this.ownerPid ? { generation, nativePid: this.ownerPid } : undefined;
@@ -448,6 +468,7 @@ export class PiPeer extends BasePeer {
   /** Withdraw hub admission without shutting down a person's Pi TUI or its bridge. */
   async detachForRoster(): Promise<void> {
     if (this.opts.mode !== "tui") throw new Error("Pi roster detach requires a personal TUI");
+    this.terminalOwnerObservation = undefined;
     this.rosterDetached = true; this.rosterEpoch++;
     this.setState("offline");
     clearTimeout(this.executionBudgetTimer); this.executionBudgetTimer = undefined;
@@ -489,6 +510,7 @@ export class PiPeer extends BasePeer {
   async stop(reason?: string): Promise<void> {
     if (reason !== undefined) this.requestedStopReason = reason;
     this.rosterEpoch++;
+    this.terminalOwnerObservation = undefined;
     this.stopping = true; // fence new calls before withdrawing both turn and idle-shell execution
     for (const id of this.activeDeliveryIds) this.delivery({ id, state: "needs_review", reason: reason ?? "Pi session stopped before settlement" });
     this.activeDeliveryIds.clear();
@@ -713,6 +735,7 @@ export class PiPeer extends BasePeer {
       this.sessionId = String(event.sessionId ?? ""); this.sessionFile = String(event.sessionFile ?? "");
       this.ownerPid = Number.isInteger(event.pid) ? event.pid : undefined; this.ownerSignature = typeof event.signature === "string" ? event.signature : undefined;
       if ((this.opts.sessionId && this.sessionId !== this.opts.sessionId) || (this.opts.sessionFile && this.sessionFile !== this.opts.sessionFile)) { this.opts.log?.(`[${this.id}] Pi session identity mismatch`); return; }
+      this.rememberTerminalOwner();
       this.startOwnerMonitor(); if (this.opts.mode === "tui") { this.started = true; this.setState("idle"); }
     }
     if (event.type === "session_shutdown") {
@@ -723,7 +746,7 @@ export class PiPeer extends BasePeer {
       if (this.opts.mode === "tui") this.reportExit(exit);
     }
     if (event.type === "tool_abort" && this.agentRunning && this.ownerClaimed && this.ownerPid && this.ownerSignature
-      && processSignature(this.ownerPid) === this.ownerSignature && event.sessionId === this.sessionId && event.generation === this.budgetGeneration
+      && this.readOwnerSignature(this.ownerPid) === this.ownerSignature && event.sessionId === this.sessionId && event.generation === this.budgetGeneration
       && typeof event.toolCallId === "string" && event.toolCallId.length > 0 && event.toolCallId.length <= 512) {
       const pending = this.pendingToolGenerations.get(event.toolCallId);
       if (pending && pending.generation === event.generation) pending.abort.abort();
@@ -846,6 +869,7 @@ export class PiPeer extends BasePeer {
   }
 
   private fail(error: Error): void {
+    this.terminalOwnerObservation = undefined;
     const approvalStopReason = this.approvalStopReason;
     this.abortTools();
     this.agentRunning = false;
@@ -866,18 +890,24 @@ export class PiPeer extends BasePeer {
   private startOwnerMonitor(): void {
     this.clearOwnerMonitor();
     if (this.opts.mode !== "tui" || !this.ownerPid || !this.ownerSignature) return;
-    this.ownerMonitor = setInterval(() => {
-      if (!this.ownerPid || ownerStillAlive(this.ownerPid, this.ownerSignature)) return;
-      const exit = this.exitMetadata("owner_lost");
-      this.stopping = true; this.ownerClaimed = false; this.clearOwnerMonitor();
-      this.resolveTuiExit?.(); this.resolveTuiExit = undefined;
-      for (const pending of this.tuiCommands.values()) pending.reject(new Error("Pi owner exited"));
-      this.tuiCommands.clear(); this.tuiQueue = [];
-      this.fail(new Error("Pi owner process exited without session_shutdown"));
-      this.reportExit(exit);
-    }, 500);
+    this.ownerMonitor = setInterval(() => this.checkOwner(), 500);
     this.ownerMonitor.unref?.();
   }
+  private checkOwner(): void {
+    if (!this.ownerPid) { this.terminalOwnerObservation = undefined; return; }
+    const current = this.readOwnerSignature(this.ownerPid);
+    if (current !== undefined && current === this.ownerSignature) { this.rememberTerminalOwner(); return; }
+    this.terminalOwnerObservation = undefined;
+    // Unknown process identity retains the existing live-owner fence, but is never terminal proof.
+    if (current === undefined) { try { process.kill(this.ownerPid, 0); return; } catch { /* positively gone */ } }
+    const exit = this.exitMetadata("owner_lost");
+    this.stopping = true; this.ownerClaimed = false; this.clearOwnerMonitor();
+    this.resolveTuiExit?.(); this.resolveTuiExit = undefined;
+    for (const pending of this.tuiCommands.values()) pending.reject(new Error("Pi owner exited"));
+    this.tuiCommands.clear(); this.tuiQueue = [];
+    this.fail(new Error("Pi owner process exited without session_shutdown"));
+    this.reportExit(exit);
+  }
   private clearOwnerMonitor(): void { if (this.ownerMonitor) clearInterval(this.ownerMonitor); this.ownerMonitor = undefined; }
   private async endApprovalTurn(generation: number, reason: string): Promise<void> {
     if (!this.agentRunning || generation !== this.budgetGeneration || this.approvalStopReason !== reason || !this.acceptingTools || this.state === "offline") return;

package/src/cli/completion.ts

@@ -0,0 +1,173 @@
+import { HELP } from "./help.ts";
+
+/** An option's value: a fixed list, a path, free text, or none (a flag). */
+type Value = readonly string[] | "path" | "text" | null;
+interface Node { children: Set<string>; options: Map<string, Value>; equals: Set<string> }
+
+/** Printed instead of candidates when the shell should complete file names. */
+export const FILES = "__files__";
+const WORD = /^[a-z][a-z0-9-]*$/;
+const ALTERNATION = /^[a-z][a-z0-9-]*(\|[a-z][a-z0-9-]*)*$/;
+
+/** Split at spaces outside brackets; a bracket group stays one token. */
+function tokens(text: string): string[] {
+  const out: string[] = [];
+  let depth = 0, current = "";
+  for (const ch of text) {
+    if (ch === "[") depth++;
+    if (ch === "]") depth--;
+    if (ch === " " && depth === 0) { if (current) out.push(current); current = ""; } else current += ch;
+  }
+  if (current) out.push(current);
+  return out;
+}
+
+/** Split at ` | ` outside brackets: `ahub sdlc status [task] | explain <task>` has two alternatives. */
+function alternatives(text: string): string[] {
+  const out: string[] = [];
+  let depth = 0, start = 0;
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === "[") depth++;
+    if (text[i] === "]") depth--;
+    if (depth === 0 && text.startsWith(" | ", i)) { out.push(text.slice(start, i)); start = i + 3; i += 2; }
+  }
+  return [...out, text.slice(start)];
+}
+
+/**
+ * A value spec: `a|b|<iso>` offers the literals a and b; an upper-case word (`N`) is a placeholder. Inside angle
+ * brackets the words are placeholders (`<path|id>` is a path, `<id|node>` free text), except a list of three or more
+ * (`<blue|teal|violet|ochre>`) and the keywords none and inherit.
+ */
+// ponytail: the keyword list is what help uses today; a new keyword inside <> needs adding here.
+function value(spec: string): Value {
+  if (spec.startsWith("<")) {
+    const parts = spec.slice(1, -1).split("|");
+    if (parts.length >= 3) return parts;
+    if (/path|dir|file/.test(spec)) return "path";
+    const keywords = parts.filter(part => part === "none" || part === "inherit");
+    return keywords.length ? keywords : "text";
+  }
+  const literal = spec.split("|").filter(part => /^[a-z0-9][\w.-]*$/.test(part));
+  if (literal.length) return literal;
+  return /path|dir|file/.test(spec) ? "path" : "text";
+}
+
+/** Options in a token group: `--flag`, `--name <value>`, `--name a|b`, `--name=a|b`; a group never lends its value to another. */
+function options(group: string[], into: Node): void {
+  for (let i = 0; i < group.length; i++) {
+    const token = group[i]!;
+    if (token.startsWith("[")) { options(tokens(token.slice(1, -1)), into); continue; }
+    const eq = /^(--?[a-zA-Z][\w-]*)=(.+)$/.exec(token);
+    if (eq) { into.options.set(eq[1]!, value(eq[2]!)); into.equals.add(eq[1]!); continue; }
+    if (!/^--?[a-zA-Z][\w-]*$/.test(token)) continue;
+    const next = group[i + 1];
+    if (next !== undefined && !next.startsWith("-") && !next.startsWith("[") && next !== "|") { into.options.set(token, value(next)); i++; }
+    else if (!into.options.has(token)) into.options.set(token, null);
+  }
+}
+
+let table: Map<string, Node> | undefined;
+/** The completion table, read from the `ahub help` entries so it cannot drift from what help documents. */
+export function completionTable(): Map<string, Node> {
+  if (table) return table;
+  const nodes = new Map<string, Node>();
+  const node = (path: readonly string[]) => {
+    const key = path.join(" ");
+    let found = nodes.get(key);
+    if (!found) { found = { children: new Set(), options: new Map(), equals: new Set() }; nodes.set(key, found); }
+    if (path.length) node(path.slice(0, -1)).children.add(path.at(-1)!);
+    return found;
+  };
+  const root = node([]);
+  root.options.set("--project", "path").set("--live-test", null).set("--help", null).set("-h", null);
+  for (const { usage } of HELP) {
+    if (usage.includes("<command>")) continue; // the global --project and --live-test forms, set above
+    let parent: string[] = [];
+    alternatives(usage.replace(/^ahub /, "")).forEach((alt, index) => {
+      const parts = tokens(alt);
+      if (parts[0]?.startsWith("-")) { options(parts, index ? node(parent.slice(0, -1)) : root); return; }
+      let prefixes: string[][] = [index ? parent.slice(0, -1) : []];
+      let i = 0;
+      for (; i < parts.length && ALTERNATION.test(parts[i]!); i++) prefixes = prefixes.flatMap(prefix => parts[i]!.split("|").map(word => [...prefix, word]));
+      const sub = parts[i]?.match(/^\[([a-z][a-z0-9-]*(?:\|[a-z][a-z0-9-]*)+)\]$/);
+      for (const path of prefixes) {
+        const target = node(path);
+        if (sub) for (const word of sub[1]!.split("|")) node([...path, word]);
+        options(parts.slice(i), target);
+      }
+      parent = prefixes[0]!;
+    });
+  }
+  return (table = nodes);
+}
+
+/** Candidates for the last word, given every word after `ahub`. Static: no daemon, project or network. */
+export function completeWords(words: readonly string[]): string[] {
+  const nodes = completionTable(), root = nodes.get("")!;
+  const cur = words.at(-1) ?? "";
+  const path: string[] = [];
+  let pending: Value | undefined;
+  let positional = false; // after a positional argument no subcommand can follow
+  const optionOf = (name: string) => nodes.get(path.join(" "))?.options.get(name) ?? root.options.get(name);
+  for (const word of words.slice(0, -1)) {
+    if (pending !== undefined) { pending = undefined; continue; }
+    if (word.startsWith("-")) { const kind = optionOf(word); if (kind && !word.includes("=")) pending = kind; continue; }
+    if (!positional && nodes.get(path.join(" "))?.children.has(word)) path.push(word);
+    else positional = true;
+  }
+  const values = (kind: Value, prefix = "") => kind === "path" ? [FILES] : Array.isArray(kind) ? kind.map(v => prefix + v) : [];
+  if (pending !== undefined) return values(pending).filter(v => v === FILES || v.startsWith(cur));
+  const eq = /^(--?[\w-]+)=/.exec(cur);
+  if (eq) return values(optionOf(eq[1]!) ?? null, eq[0]).filter(v => v === FILES || v.startsWith(cur));
+  const here = nodes.get(path.join(" "))!;
+  // An option documented as `--name=value` is offered as `--name=`; the shell adds no space after it.
+  const opts = [...new Set([...here.options.keys(), ...(path.length ? [] : root.options.keys())])].map(o => here.equals.has(o) ? `${o}=` : o);
+  const children = positional ? [] : [...here.children];
+  const candidates = cur.startsWith("-") ? opts : [...children, ...(cur && children.length ? [] : opts)];
+  const matched = candidates.filter(c => c.startsWith(cur)).sort();
+  return matched.length || cur.startsWith("-") || children.length ? matched : [FILES];
+}
+
+const SCRIPTS: Record<string, string> = {
+  zsh: `#compdef ahub
+# ahub zsh completion: candidates come from \`ahub __complete\`, read from ahub's own help entries.
+_ahub() {
+  local -a c
+  c=("\${(@f)$(ahub __complete -- "\${(@)words[2,CURRENT]}" 2>/dev/null)}")
+  c=(\${c:#})
+  if [[ "\${c[1]}" == ${FILES} ]]; then _files; return; fi
+  compadd -Q -S '' -- \${(M)c:#*=}
+  compadd -Q -- \${c:#*=}
+}
+compdef _ahub ahub
+`,
+  bash: `# ahub bash completion: candidates come from \`ahub __complete\`, read from ahub's own help entries.
+_ahub() {
+  local IFS=$'\\n' cur=\${COMP_WORDS[COMP_CWORD]}
+  local c=($(ahub __complete -- "\${COMP_WORDS[@]:1:COMP_CWORD}" 2>/dev/null))
+  if [ "\${c[0]}" = ${FILES} ]; then COMPREPLY=($(compgen -f -- "$cur")); else COMPREPLY=("\${c[@]}"); fi
+  case "\${COMPREPLY[*]}" in *=) compopt -o nospace 2>/dev/null ;; esac
+}
+complete -o default -F _ahub ahub
+`,
+  fish: `# ahub fish completion: candidates come from \`ahub __complete\`, read from ahub's own help entries.
+function __ahub_complete
+    set -l cur (commandline -ct)
+    # "$cur" keeps an empty current word as an argument: Tab after a space completes the next word
+    set -l out (ahub __complete -- (commandline -opc)[2..-1] "$cur" 2>/dev/null)
+    if test "$out[1]" = ${FILES}
+        __fish_complete_path (commandline -ct)
+    else
+        printf '%s\\n' $out
+    end
+end
+complete -c ahub -f -a '(__ahub_complete)'
+`,
+};
+
+export const COMPLETION_SHELLS = Object.keys(SCRIPTS);
+/** The script for one shell, or undefined for a shell ahub does not support. */
+export function completionScript(shell: string | undefined): string | undefined {
+  return shell === undefined ? undefined : SCRIPTS[shell];
+}