@staix/agent-hub 0.18.0 → 0.20.0

package/src/cli/agents.ts

@@ -4,19 +4,81 @@ import { assessVersion, COMPAT, describe, isCompatId, readTrust, trustFile, writ
 /** #691: what `ahub agents` and `ahub doctor` show for each gated native CLI. */
 export interface AgentVersionRow { id: CompatId; executable?: string; verdict: CompatVerdict; policy: string }
 
-/** `commands` carries the configured argv (codex_bin, jcode_cmd, qwen_cmd); the probe words follow it. */
+const PROBE_ENV = { JCODE_NO_TELEMETRY: "1", JCODE_DISABLE_CLAUDE_MCP: "1" };
+
+/** The one place that decides what is run for an id: the configured argv (including pi.cmd) plus the probe words. */
+function probeTarget(id: CompatId, commands: Partial<Record<CompatId, readonly string[]>>): { executable: string; args: string[] } | undefined {
+  const [defaultBin, ...words] = COMPAT[id].probe;
+  const [bin = defaultBin, ...prefix] = commands[id] ?? [defaultBin];
+  const executable = Bun.which(bin) ?? undefined;
+  return executable ? { executable, args: [...prefix, ...words] } : undefined;
+}
+
+function probeRow(id: CompatId, executable: string | undefined, stdout: string | undefined, trusted: ReturnType<typeof readTrust>): AgentVersionRow {
+  if (!executable) return { id, verdict: { ok: false, state: "unknown", reason: `${COMPAT[id].label} not found on PATH` }, policy: describe(id) };
+  return { id, executable, verdict: assessVersion(id, stdout === undefined ? undefined : COMPAT[id].parse(stdout), trusted), policy: describe(id) };
+}
+
+/** `commands` carries the configured argv (including pi.cmd); the probe words follow it. */
 export function agentVersions(commands: Partial<Record<CompatId, readonly string[]>> = {}): AgentVersionRow[] {
   const trusted = readTrust();
   return (Object.keys(COMPAT) as CompatId[]).map(id => {
-    const [defaultBin, ...words] = COMPAT[id].probe;
-    const [bin = defaultBin, ...prefix] = commands[id] ?? [defaultBin];
-    const executable = Bun.which(bin) ?? undefined;
-    if (!executable) return { id, verdict: { ok: false, state: "unknown", reason: `${COMPAT[id].label} not found on PATH` }, policy: describe(id) };
-    const result = spawnSync(executable, [...prefix, ...words], { encoding: "utf8", timeout: 10_000, maxBuffer: 64 * 1024, env: { ...process.env, JCODE_NO_TELEMETRY: "1", JCODE_DISABLE_CLAUDE_MCP: "1" } });
-    return { id, executable, verdict: assessVersion(id, result.status === 0 ? COMPAT[id].parse(result.stdout ?? "") : undefined, trusted), policy: describe(id) };
+    const target = probeTarget(id, commands);
+    if (!target) return probeRow(id, undefined, undefined, trusted);
+    const result = spawnSync(target.executable, target.args, { encoding: "utf8", timeout: 10_000, maxBuffer: 64 * 1024, env: { ...process.env, ...PROBE_ENV } });
+    return probeRow(id, target.executable, result.status === 0 ? result.stdout ?? "" : undefined, trusted);
   });
 }
 
+const PROBE_OUTPUT_CAP = 64 * 1024;
+/** After the probe process ends, how long a descendant that kept the pipe open may still be read before the reader is cancelled. */
+const PROBE_EXIT_GRACE_MS = 250;
+
+/**
+ * One bounded probe run. Output is read as a stream and counted as it arrives: past the cap the probe is killed and the
+ * reader cancelled, so a chatty or endless CLI never accumulates in memory. A deadline kills the probe and cancels the
+ * reader, and a descendant that inherited stdout cannot hold the reader past the grace after the probe's own exit.
+ * ponytail: only the probe process is killed, not its descendants; a stray one ends on its own or when its pipe closes.
+ * The upgrade is a process group via child_process (as `jcodeVersionAsync` does).
+ */
+async function runProbe(executable: string, args: readonly string[], timeoutMs: number, graceMs = PROBE_EXIT_GRACE_MS): Promise<string | undefined> {
+  const child = Bun.spawn([executable, ...args], { stdout: "pipe", stderr: "ignore", stdin: "ignore", env: { ...process.env, ...PROBE_ENV }, timeout: timeoutMs, killSignal: "SIGKILL" });
+  const reader = child.stdout.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0, overflow = false, cancelled = false;
+  const release = () => { if (cancelled) return; cancelled = true; void reader.cancel().catch(() => undefined); };
+  const pump = (async () => {
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) return;
+        total += value.byteLength;
+        if (total > PROBE_OUTPUT_CAP) { overflow = true; child.kill("SIGKILL"); release(); return; }
+        chunks.push(value);
+      }
+    } catch { /* a cancelled or failed read ends the probe with what was counted */ }
+  })();
+  const deadline = setTimeout(() => { child.kill("SIGKILL"); release(); }, timeoutMs + graceMs);
+  let grace: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const code = await child.exited;
+    grace = setTimeout(release, graceMs);
+    await pump;
+    return code === 0 && !overflow ? Buffer.concat(chunks).toString("utf8") : undefined;
+  } finally { clearTimeout(deadline); clearTimeout(grace); release(); }
+}
+
+/** #843 AC3: the same probe for the daemon, which must not block its event loop for up to ten seconds an id. */
+export async function agentVersionsAsync(commands: Partial<Record<CompatId, readonly string[]>> = {}, timeoutMs = 10_000, graceMs = PROBE_EXIT_GRACE_MS): Promise<AgentVersionRow[]> {
+  const trusted = readTrust();
+  return Promise.all((Object.keys(COMPAT) as CompatId[]).map(async id => {
+    const target = probeTarget(id, commands);
+    if (!target) return probeRow(id, undefined, undefined, trusted);
+    try { return probeRow(id, target.executable, await runProbe(target.executable, target.args, timeoutMs, graceMs), trusted); }
+    catch { return probeRow(id, target.executable, undefined, trusted); }
+  }));
+}
+
 export function runAgents(args: string[], commands: Partial<Record<CompatId, readonly string[]>>, fail: (message: string) => never): void {
   const [sub, id, version, ...rest] = args.filter(arg => arg !== "--json");
   if (sub === "trust") {

package/src/cli/claude-shell-wrapper.ts

@@ -0,0 +1,54 @@
+import { request } from "node:http";
+import { isAbsolute, basename } from "node:path";
+
+export const HOST_SHELL_PROTOCOL = Object.freeze({ chunkBytes: 16 * 1024, frameBytes: 24 * 1024, failure: 125, maximumMs: 3_600_000, refusal: "host shell execution refused" });
+
+async function output(stream: NodeJS.WriteStream, data: Buffer): Promise<void> {
+  await new Promise<void>((resolve, reject) => stream.write(data, error => error ? reject(error) : resolve()));
+}
+
+async function main(): Promise<number> {
+  const [socket, ticket, ...extra] = process.argv.slice(2);
+  if (!socket || !isAbsolute(socket) || socket.length > 4096 || !ticket || !/^[a-f0-9]{64}$/.test(ticket) || extra.length) throw new Error();
+  const body = JSON.stringify({ ticket });
+  const call = request({ socketPath: socket, path: "/execute", method: "POST", headers: { "content-type": "application/json", "content-length": Buffer.byteLength(body), connection: "close" } });
+  const connection = new Promise<import("node:http").IncomingMessage>((resolve, reject) => { call.once("response", resolve); call.once("error", reject); });
+  const opening = setTimeout(() => call.destroy(new Error()), 5000);
+  const total = setTimeout(() => call.destroy(new Error()), HOST_SHELL_PROTOCOL.maximumMs + 10_000);
+  let response: import("node:http").IncomingMessage | undefined;
+  try {
+    call.end(body); response = await connection; clearTimeout(opening);
+    if (response.statusCode !== 200 || response.headers["content-type"] !== "application/x-ndjson") throw new Error();
+    let pending = "", status: number | undefined;
+    for await (const raw of response) {
+      const chunk = Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
+      if (chunk.length > 1024 * 1024) throw new Error();
+      pending += chunk.toString("utf8");
+      for (let end; (end = pending.indexOf("\n")) >= 0;) {
+        if (end > HOST_SHELL_PROTOCOL.frameBytes) throw new Error();
+        const line = pending.slice(0, end); pending = pending.slice(end + 1);
+        if (!line || status !== undefined) throw new Error();
+        const frame = JSON.parse(line);
+        if (!frame || typeof frame !== "object" || Array.isArray(frame)) throw new Error();
+        const keys = Object.keys(frame).sort().join(",");
+        if (frame.type === "exit" && keys === "code,type" && Number.isSafeInteger(frame.code) && frame.code >= 0 && frame.code <= 255) { status = frame.code; continue; }
+        if (!["stdout", "stderr"].includes(frame.type) || keys !== "data,type" || typeof frame.data !== "string" || frame.data.length > 4 * Math.ceil(HOST_SHELL_PROTOCOL.chunkBytes / 3)) throw new Error();
+        const bytes = Buffer.from(frame.data, "base64");
+        if (bytes.length > HOST_SHELL_PROTOCOL.chunkBytes || bytes.toString("base64") !== frame.data) throw new Error();
+        await output(frame.type === "stdout" ? process.stdout : process.stderr, bytes);
+      }
+      if (pending.length > HOST_SHELL_PROTOCOL.frameBytes) throw new Error();
+    }
+    if (pending || status === undefined) throw new Error();
+    return status;
+  } finally { clearTimeout(opening); clearTimeout(total); response?.destroy(); call.destroy(); }
+}
+
+// The filename fence also keeps this inert if a host imports the protocol constants through a bundle.
+if (import.meta.main && basename(process.argv[1] ?? "") === "claude-shell-wrapper.ts") {
+  process.stdout.on("error", () => {}); process.stderr.on("error", () => {});
+  void main().then(code => { process.exitCode = code; }, async () => {
+    try { await output(process.stderr, Buffer.from(`${HOST_SHELL_PROTOCOL.refusal}\n`)); } catch { /* broken caller pipe */ }
+    process.exitCode = HOST_SHELL_PROTOCOL.failure;
+  });
+}

package/src/cli/main.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-import { conductorOperation } from "../hub/operational-authority.ts";
+import { conductorOperation, OPERATIONAL_PERSON_GUIDANCE } from "../hub/operational-authority.ts";
 import type { DeliverableRow } from "../hub/tasks.ts";
 import { kimiSourceRow } from "../hub/budget-notes.ts";
 import { hubGitSync, hubGitEnv } from "../hub/git.ts";
@@ -487,12 +487,17 @@ function startupDiagnostic(error: unknown): string {
   return message.replace(/[\p{Cc}\p{Cf}]/gu, " ").replace(/\s+/g, " ").trim().slice(0, 512) || "invalid startup configuration";
 }
 
-function fail(message: string, refusalAudited=false): never {
-  if(operationalAuditReady){if(refusalAudited)operationalRefusalRecorded=true;if(!operationalRefusalRecorded)audit("refused");}
+function fail(message: string, refusalAudited=false, authorityRefused?:boolean): never {
+  if(operationalAuditReady && authorityRefused!==false){if(refusalAudited)operationalRefusalRecorded=true;if(!operationalRefusalRecorded)audit("refused");}
   console.error(`ahub: ${message}`);
   process.exit(1);
 }
 
+function operationalIncomplete(result: {complete?:boolean;incompleteReason?:unknown;truncated?:boolean}, history: "log"|"event"): void {
+  if(result.complete===false)console.error(`ahub: operational output is incomplete: ${typeof result.incompleteReason==="string"?terminalText(result.incompleteReason).replace(/[\r\n]+/g," ").slice(0,200):"public privacy or history coverage unavailable"}`);
+  else if(result.truncated)console.error(`ahub: operational ${history} history is truncated`);
+}
+
 async function taskOp(op: string, a: Record<string, unknown>, throwOnError = false, connection?: ControlClient, timeoutMs?: number): Promise<string> {
   const hub = connection ?? await connect();
   try {
@@ -501,11 +506,11 @@ async function taskOp(op: string, a: Record<string, unknown>, throwOnError = fal
     if (!res.ok) {
       if (throwOnError) throw new Error(res.error);
       if(res.refusalAudited===true)operationalRefusalRecorded=true;
-      audit("refused");
+      if(!operationalAuditReady || res.authorityRefused!==false)audit("refused");
       // #711: an agent shell refused something only the person may do is told why it counts as an agent. The refusal and the authority stay as they were.
       const cause = agentShellCause(identity, String(res.error));
       if (cause) console.error(`ahub: ${res.error}\n${cause}`), process.exit(1);
-      fail(res.error);
+      fail(res.error,res.refusalAudited===true,res.authorityRefused);
     }
     return res.text;
   } finally { if (!connection) hub.close(); }
@@ -1065,7 +1070,7 @@ const commands: Record<string, () => Promise<void> | void> = {
         const { one, rest: flags } = takeFlags(rest, ["--peer"], []);
         if (flags.length) fail("usage: ahub queue list [--peer <id>] [--json] [--full] [--color=auto|always|never]");
         const result = await hub.request({ t: "queue", op: "list", ...(one["--peer"] ? { peer: one["--peer"] } : {}) });
-        if (!result.ok) fail(result.error,result.refusalAudited===true);
+        if (!result.ok) fail(result.error,result.refusalAudited===true,result.authorityRefused);
         if (options.json) return console.log(JSON.stringify(result.deliveries, null, 2));
         printOutput(renderQueue(result.deliveries, options.columns, Date.now()), options.color);
         return;
@@ -1077,7 +1082,7 @@ const commands: Record<string, () => Promise<void> | void> = {
         if (others.length || !one["--peer"] || (one["--state"] !== undefined && !["queued", "needs_review"].includes(one["--state"]))) fail("usage: ahub queue discard --peer <id> --reason <text> [--state queued|needs_review] [--yes]");
         if (yes && !one["--reason"]?.trim()) fail("ahub queue discard needs --reason <text> with --yes: it is recorded on every discarded delivery");
         const result = await hub.request({ t: "queue", op: "discard", peer: one["--peer"], ...(one["--state"] ? { state: one["--state"] } : {}), ...(yes ? { confirmed: true, reason: one["--reason"] } : {}) }, 60_000);
-        if (!result.ok) fail(result.error,result.refusalAudited===true);
+        if (!result.ok) fail(result.error,result.refusalAudited===true,result.authorityRefused);
         if (options.json) return console.log(JSON.stringify(result, null, 2));
         if (!yes) return console.log(`${result.count} ${result.state} deliver${result.count === 1 ? "y" : "ies"} for ${result.peer}; nothing discarded. Run again with --reason <text> --yes to discard them.`);
         console.log(`discarded ${result.discarded} of ${result.count} ${result.state} deliver${result.count === 1 ? "y" : "ies"} for ${result.peer}${result.refused ? `; ${result.refused} refused (${Object.entries(result.refusedBy ?? {}).map(([why, n]) => `${why} ${n}`).join(", ")})` : ""}`);
@@ -1088,7 +1093,7 @@ const commands: Record<string, () => Promise<void> | void> = {
       if (operation === "show") {
         if (flags.length) fail("usage: ahub queue show <id>");
         const shown = await hub.request({ t: "queue", op: "show", id });
-        if (!shown.ok) fail(shown.error,shown.refusalAudited===true);
+        if (!shown.ok) fail(shown.error,shown.refusalAudited===true,shown.authorityRefused);
         if (options.json) return console.log(JSON.stringify(shown.delivery, null, 2));
         return printOutput(renderQueueShow(shown.delivery, options.columns, Date.now()), options.color);
       }
@@ -1098,11 +1103,11 @@ const commands: Record<string, () => Promise<void> | void> = {
       let revision = parsedRevision;
       if (revision === undefined) {
         const shown = await hub.request({ t: "queue", op: "show", id });
-        if (!shown.ok) fail(shown.error,shown.refusalAudited===true);
+        if (!shown.ok) fail(shown.error,shown.refusalAudited===true,shown.authorityRefused);
         revision = shown.delivery.revision;
       }
       const result = await hub.request({ t: "queue", op: "resolve", id, revision, action: one["--action"], reason: one["--reason"] });
-      if (!result.ok) fail(result.error,result.refusalAudited===true);
+      if (!result.ok) fail(result.error,result.refusalAudited===true,result.authorityRefused);
       if (options.json) console.log(JSON.stringify(result.delivery, null, 2));
       else printOutput(renderQueueShow(result.delivery, options.columns, Date.now()), options.color);
     } finally { hub.close(); }
@@ -1566,7 +1571,7 @@ const commands: Record<string, () => Promise<void> | void> = {
       const reply = await hub.request({ t: "peer_stop", peer }, 35_000);
       if (reply.ok !== true) {
         const error = String(reply.error ?? "peer stop request refused");
-        fail(/unknown (?:control )?(?:message|request|command)(?:\b|:)|this hub does not know "peer_stop"/i.test(error) ? `${error}; upgrade the running hub to use ahub stop` : error,reply.refusalAudited===true);
+        fail(/unknown (?:control )?(?:message|request|command)(?:\b|:)|this hub does not know "peer_stop"/i.test(error) ? `${error}; upgrade the running hub to use ahub stop` : error,reply.refusalAudited===true,reply.authorityRefused);
       }
       console.log(`${peer}: ${reply.state}`);
     } finally { hub.close(); }
@@ -1602,7 +1607,7 @@ const commands: Record<string, () => Promise<void> | void> = {
     const hub = await connect();
     try {
       requireNamedPeerFeature(hub, peer);
-      const request = async (message: Record<string, unknown>) => { const reply = await hub.request(message, 35_000); if (reply.ok !== true) fail(String(reply.error ?? "roster request refused"),reply.refusalAudited===true); return reply; };
+      const request = async (message: Record<string, unknown>) => { const reply = await hub.request(message, 35_000); if (reply.ok !== true) fail(String(reply.error ?? "roster request refused"),reply.refusalAudited===true,reply.authorityRefused); return reply; };
       if (sub === "list") {
         const view = await request({ t: "settings_get" });
         if (!Array.isArray(view.roster)) fail("upgrade the running hub to use ahub roster");
@@ -1668,7 +1673,7 @@ const commands: Record<string, () => Promise<void> | void> = {
         const reply = await hub.request(message, 35_000);
         if (reply.ok !== true) {
           const error = String(reply.error ?? "settings request refused");
-          fail(/unknown (?:control )?(?:message|request|command)(?:\b|:)|this hub does not know "settings_/i.test(error) ? `${error}; upgrade the running hub to use ahub settings` : error,reply.refusalAudited===true);
+          fail(/unknown (?:control )?(?:message|request|command)(?:\b|:)|this hub does not know "settings_/i.test(error) ? `${error}; upgrade the running hub to use ahub settings` : error,reply.refusalAudited===true,reply.authorityRefused);
         }
         return reply;
       };
@@ -1798,14 +1803,14 @@ const commands: Record<string, () => Promise<void> | void> = {
 
   logs: async () => {
     if (identity.role !== "tools") return exec("tail", [args.includes("-f") ? "-f" : "-n100", join(stateDir, "hub.log")]);
-    const hub=await connect();const pending:string[]=[];let ready=false;
-    hub.onPush=message=>{if(message.t==="operational_log" && typeof message.line==="string"){if(ready)console.log(message.line);else if(pending.length<100)pending.push(message.line);}};
+    const hub=await connect();const pending:string[]=[];let ready=false,incompleteShown=false;
+    hub.onPush=message=>{if(message.t==="operational_log" && typeof message.line==="string"){if(message.complete===false && !incompleteShown){operationalIncomplete(message,"log");incompleteShown=true;}if(ready)console.log(message.line);else if(pending.length<100)pending.push(message.line);}};
     try {
       const result=await hub.request({t:"conductor_operational",op:"logs",follow:args.includes("-f")});
-      if(result.ok!==true)fail(String(result.error??"operational logs unavailable"),result.refusalAudited===true);
+      if(result.ok!==true)fail(String(result.error??"operational logs unavailable"),result.refusalAudited===true,result.authorityRefused);
       for(const line of result.lines??[])console.log(line);
       ready=true;for(const line of pending)console.log(line);
-      if(result.truncated)console.error("ahub: operational log history is truncated");
+      if(!incompleteShown){operationalIncomplete(result,"log");if(result.complete===false)incompleteShown=true;}
       if(args.includes("-f"))await new Promise<void>(resolve=>{
         const finish=()=>{process.off("SIGINT",finish);resolve();};
         hub.onClose=finish;process.once("SIGINT",finish);
@@ -1815,7 +1820,7 @@ const commands: Record<string, () => Promise<void> | void> = {
   export: async () => {
     if(identity.role==="tools") {
       const hub=await connect();
-      try {const result=await hub.request({t:"conductor_operational",op:"export",since:since()});if(result.ok!==true)fail(String(result.error??"operational export unavailable"),result.refusalAudited===true);for(const row of result.events??[])console.log(JSON.stringify(row));if(result.truncated)console.error("ahub: operational event history is truncated");}
+      try {const result=await hub.request({t:"conductor_operational",op:"export",since:since()});if(result.ok!==true)fail(String(result.error??"operational export unavailable"),result.refusalAudited===true,result.authorityRefused);for(const row of result.events??[])console.log(JSON.stringify(row));operationalIncomplete(result,"event");}
       finally {hub.close();}
       return;
     }
@@ -2230,7 +2235,7 @@ const commands: Record<string, () => Promise<void> | void> = {
     }
     if (args.includes("--orphans")) {
       if(identity.role==="tools" && args.includes("--kill")) {
-        const hub=await connect();try {const result=await hub.request({t:"conductor_operational",op:"orphans"},10_000);if(result.ok!==true)fail(String(result.error??"orphan inspection unavailable"),result.refusalAudited===true);console.log(JSON.stringify(result,null,2));}finally{hub.close();}return;
+        const hub=await connect();try {const result=await hub.request({t:"conductor_operational",op:"orphans"},10_000);if(result.ok!==true)fail(String(result.error??"orphan inspection unavailable"),result.refusalAudited===true,result.authorityRefused);console.log(JSON.stringify(result,null,2));}finally{hub.close();}return;
       }
       return orphanDoctor(args.includes("--kill"), options);
     }
@@ -2392,16 +2397,17 @@ function inspectDoctorRouting(cwd: string): { routing?: Routing; errors: string[
 async function runConductorCommand(): Promise<void> {
   const operation=conductorOperation(cmd,args);
   if(operation) {
-    const denial=()=>peerCommandRefusal(identity.role==="tools"?identity.peer:"unknown",commandLabel);
+    const unavailable=`conductor authorization unavailable; nothing was executed; ${OPERATIONAL_PERSON_GUIDANCE}`;
     const descriptor=readControl(stateDir);
-    if(!descriptor?.instanceId || !descriptor.projectId || !descriptor.pid || !descriptor.pidSignature || processLiveness(descriptor.pid,descriptor.pidSignature)!=="live")fail(denial());
+    if(!descriptor?.instanceId || !descriptor.projectId || !descriptor.pid || !descriptor.pidSignature || processLiveness(descriptor.pid,descriptor.pidSignature)!=="live")fail(unavailable);
     let hub:ControlClient;
-    try {hub=await connect(750);} catch {fail(denial());}
+    try {hub=await connect(3000);} catch {fail(unavailable);}
     let release:(()=>void)|undefined;
     try {
       let result:any;
-      try {result=await hub.request({t:"conductor_operational",op:"authorize",command:operation},750);} catch {fail(denial());}
-      if(result.ok!==true || !hub.instanceId)fail(`${denial()}${result.error?`; ${String(result.error)}`:""}`,result.refusalAudited===true);
+      try {result=await hub.request({t:"conductor_operational",op:"authorize",command:operation},3000);} catch {fail(unavailable);}
+      if(result.ok!==true)fail(result.authorityRefused===true || result.authorityRefused===false?String(result.error??unavailable):unavailable,result.refusalAudited===true,result.authorityRefused);
+      if(!hub.instanceId)fail(unavailable);
       release=ControlClient.pinInstance(stateDir,hub.instanceId);
       await commands[cmd]!();
     } finally {release?.();hub.close();}

package/src/cli/output.ts

@@ -14,6 +14,8 @@ export interface StatusOutput {
   retainedConfig?: readonly { key: string; reason: string }[];
   /** #572 AC3: advisory, present while the project root checkout is on a branch other than the default. */
   mainCheckout?: string;
+  /** #843 AC3: installed agent CLIs not on a verified version; ids, version, state and a receipt path only. */
+  agentDrift?: readonly { id: string; version: string; state: string; receipt: string }[];
   taskStalls?: readonly { task: number; cause: { kind: string; peer?: string; dependency?: number; code: string } }[];
   pendingTaskOffers?: readonly { task: number; peer: string }[];
   isolatedChecks?: { pending?: number; orphans?: string[]; unknownReceipts?: readonly string[]; maintenanceUnavailable?: boolean };
@@ -204,6 +206,7 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
   if (data.cwd) out.push(...lines(data.cwd, columns));
   for (const pending of data.pendingRestart ?? []) out.push(...detail("pending restart", `${pending.key}: ${pending.reason}`, columns, "attention"));
   if (data.mainCheckout) out.push(...detail("main checkout", data.mainCheckout, columns, "attention"));
+  for (const drift of data.agentDrift ?? []) out.push(...detail("agent CLI drift", `${drift.id} ${drift.version} ${drift.state}; last receipt ${drift.receipt}`, columns, "attention"));
   if (data.retainedConfig?.length) {
     out.push(...detail("config retained", `${data.retainedConfig.map(row => row.key).join(", ")}; run ahub settings reload`, columns, "attention"));
     for (const pending of data.retainedConfig) out.push(...detail("retained reason", `${pending.key}: ${pending.reason}`, columns, "attention"));
@@ -262,6 +265,7 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
     if (p.permissionNote) out.push(...detail("permission", p.permissionNote, columns, "muted"));
     if (typeof p.statusNotice?.message === "string" && p.statusNotice.message) out.push(...detail("status notice", p.statusNotice.message, columns, "attention"));
     if (p.requestedModel && p.servedBy && p.requestedModel !== p.servedBy) out.push(...detail("requested model", p.requestedModel, columns));
+    if (p.reviewScope === "code" || p.reviewScope === "full") out.push(...detail("review scope", p.reviewScope === "code" ? "code only (cannot run tests or read CI; the merger gates on exact-head CI)" : "full", columns, "muted")); // #852
     if (typeof p.modelSource === "string" && p.modelSource) out.push(...detail("model source", flat(p.modelSource), columns, "muted")); // an extra Jcode instance (#685): names only, never a URL or token
     if (typeof p.importantWaitingSince === "number" && p.importantWaitingNote) out.push(...detail("important waiting", `${p.importantWaitingNote.replace(/^\d+ important messages? waiting/, "important messages waiting")}`, columns, "attention"));
     if (typeof p.oldestQueuedAt === "number") out.push(...detail(`${id} oldest queued`, relative(p.oldestQueuedAt, now), columns, "muted"));

package/src/hub/agent-drift.ts

@@ -0,0 +1,61 @@
+import { COMPAT, type CompatId } from "../adapters/compat.ts";
+import type { AgentVersionRow } from "../cli/agents.ts";
+import { HUB, newEnvelope, sanitize, type PeerId } from "./envelope.ts";
+
+/** #843 AC3: an installed gated CLI whose version is not `verified`. Ids, version, state and one receipt path, never output of the CLI. */
+export interface DriftedAgent { id: CompatId; version: string; state: "in-line" | "trusted" | "refused"; receipt: string }
+
+/** A version string that is safe to carry in a notice and a marker: what `COMPAT[id].parse` yields for a real CLI. */
+const SAFE_VERSION = /^[0-9A-Za-z][0-9A-Za-z.+_-]{0,63}$/;
+
+/**
+ * Pure: which rows are drift. A missing executable is not drift (no executable, no version), and a CLI whose
+ * version could not be read has no (id, version) to announce, so `unknown` is never drift either.
+ */
+export function driftedAgents(rows: readonly AgentVersionRow[]): DriftedAgent[] {
+  const out: DriftedAgent[] = [];
+  for (const row of rows) {
+    const { verdict } = row;
+    if (!row.executable || verdict.state === "verified" || verdict.state === "unknown") continue;
+    const version = verdict.version;
+    if (!version || !SAFE_VERSION.test(version)) continue;
+    out.push({ id: row.id, version, state: verdict.state, receipt: COMPAT[row.id].receipt });
+  }
+  return out;
+}
+
+/** Durable key of one notice: the (id, version) and the planner it was queued for. */
+export const driftMarker = (agent: Pick<DriftedAgent, "id" | "version">, planner: PeerId): string => `${agent.id}:${agent.version}@${planner}`;
+
+export const driftNoticeBody = (agent: DriftedAgent): string =>
+  sanitize(`Agent CLI drift: ${agent.id} ${agent.version} ${agent.state}; last receipt ${agent.receipt}`);
+
+export interface DriftDeps {
+  /** True when the (id, version, planner) marker is new and now recorded (durable: `Board.recordAgentDriftNotice`). */
+  record(marker: string): boolean;
+  /** Undo a record whose notice could not be queued, so the next sweep tries again. */
+  forget(marker: string): void;
+  /** The effective planner holders from the settled role map. */
+  planners(): readonly PeerId[];
+  isRostered(peer: PeerId): boolean;
+  publish(env: ReturnType<typeof newEnvelope>): PeerId[];
+}
+
+/**
+ * One notice per (id, version) to each effective planner, kept durably per recipient: a planner that was queued is
+ * never told again, and one that could not be queued (or was not rostered yet) is retried alone by the next sweep.
+ * With no rostered planner nothing is recorded. Returns the notices queued.
+ */
+export function noticeDrift(drift: readonly DriftedAgent[], deps: DriftDeps): number {
+  const planners = deps.planners().filter(peer => deps.isRostered(peer));
+  let sent = 0;
+  for (const agent of drift) for (const planner of planners) {
+    const marker = driftMarker(agent, planner);
+    if (!deps.record(marker)) continue;
+    try {
+      if (!deps.publish(newEnvelope(HUB, driftNoticeBody(agent), { to: [planner], kind: "task" })).includes(planner)) throw new Error("the notice was not queued");
+      sent++;
+    } catch { deps.forget(marker); }
+  }
+  return sent;
+}

package/src/hub/board.ts

@@ -72,6 +72,10 @@ export interface HistoryEntry {
   reviewCost?: ReviewCost;
   /** #223 R4: on a verdict, whether the reviewer's context was new for it; set by the hub, never by the reviewer. */
   reviewContext?: "fresh" | "continuing";
+  /** #852: a verdict by a `code`-scope reviewer says so; a `full` reviewer's verdict carries nothing, so existing rows are unchanged. */
+  reviewScope?: "code";
+  /** #852 AC3: a `code`-scope reviewer's changes_requested with no open finding. It is recorded, returns the task to its owner and counts toward nothing. */
+  evidenceOnly?: true;
   /** Structured review report bound to the reviewed artifact, stored in the existing history JSON. */
   reviewFindings?: ReviewFindingSet;
   /**
@@ -259,6 +263,8 @@ export class Board {
     this.db.run("CREATE TABLE IF NOT EXISTS task_stalls (task INTEGER PRIMARY KEY, payload TEXT NOT NULL)");
     // #481 S7: one row per log-tier band breach episode already announced, so a restart never repeats the notice.
     this.db.run("CREATE TABLE IF NOT EXISTS band_notices (marker TEXT PRIMARY KEY, at INTEGER NOT NULL)");
+    // #843 AC3: one row per (agent id, installed version, planner) already queued, so a restart never repeats it.
+    this.db.run("CREATE TABLE IF NOT EXISTS agent_drift_notices (marker TEXT PRIMARY KEY, at INTEGER NOT NULL)");
     // Derived status-cache generation: only Board task/stall writes advance it, never journal writes.
     this.db.run("CREATE TABLE IF NOT EXISTS board_status_revision (id INTEGER PRIMARY KEY CHECK(id=1), revision INTEGER NOT NULL)");
     this.db.run("INSERT OR IGNORE INTO board_status_revision VALUES (1,0)");
@@ -373,6 +379,12 @@ export class Board {
     if (!/^[a-z_]{1,64}:#[1-9][0-9]{0,9}:log$/.test(marker)) throw new Error("invalid band notice marker");
     return this.db.query("INSERT OR IGNORE INTO band_notices(marker, at) VALUES(?, ?)").run(marker, Date.now()).changes > 0;
   }
+  /** True when the (id, version, planner) marker was new and is now recorded; false when it was announced before. */
+  recordAgentDriftNotice(marker: string): boolean {
+    if (!/^[a-z][a-z0-9-]{0,31}:[0-9A-Za-z][0-9A-Za-z.+_-]{0,63}@[0-9A-Za-z][0-9A-Za-z._-]{0,63}$/.test(marker)) throw new Error("invalid agent drift marker");
+    return this.db.query("INSERT OR IGNORE INTO agent_drift_notices(marker, at) VALUES(?, ?)").run(marker, Date.now()).changes > 0;
+  }
+  forgetAgentDriftNotice(marker: string): void { this.db.query("DELETE FROM agent_drift_notices WHERE marker=?").run(marker); }
   clearStall(task: number): void { this.taskWrite(() => this.db.query("DELETE FROM task_stalls WHERE task=?").run(task)); }
   stalls(): TaskStall[] {
     return (this.db.query("SELECT payload FROM task_stalls ORDER BY task").all() as { payload: string }[]).flatMap(row => {
@@ -398,7 +410,7 @@ 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" | "planner" | "reviewer" | "reserved" | "refs" | "plan" | "rejections" | "signals" | "sdlc" | "role" | "cancelled" | "codeSymbols">>, note?: string, extra: Pick<HistoryEntry, "plannerReason" | "planAuthor" | "selfReview" | "profile" | "sweep" | "reason" | "from" | "capacity" | "withheld" | "noWrites" | "reviewCost" | "reviewContext" | "reviewFindings" | "unmetCriteria" | "deliverables" | "planObservation" | "planDeparture" | "planDepartureInvalidated" | keyof ReviewerHistory> = {}, expectedFlowRevision?: number, codeSymbolsAuthority?: typeof HOST_CODE_SYMBOLS): Task {
+  update(id: number, by: PeerId, event: string, patch: Partial<Pick<Task, "state" | "owner" | "planner" | "reviewer" | "reserved" | "refs" | "plan" | "rejections" | "signals" | "sdlc" | "role" | "cancelled" | "codeSymbols">>, note?: string, extra: Pick<HistoryEntry, "plannerReason" | "planAuthor" | "selfReview" | "profile" | "sweep" | "reason" | "from" | "capacity" | "withheld" | "noWrites" | "reviewCost" | "reviewContext" | "reviewScope" | "evidenceOnly" | "reviewFindings" | "unmetCriteria" | "deliverables" | "planObservation" | "planDeparture" | "planDepartureInvalidated" | keyof ReviewerHistory> = {}, expectedFlowRevision?: number, codeSymbolsAuthority?: typeof HOST_CODE_SYMBOLS): Task {
     const task = this.get(id);
     if (!task) throw new Error(`no task #${id}`);
     if (expectedFlowRevision !== undefined && (!Number.isSafeInteger(expectedFlowRevision) || expectedFlowRevision < 0 || task.history.length !== expectedFlowRevision)) throw new Error("task flow revision changed");
@@ -454,7 +466,7 @@ export class Board {
     // Disabling reporting must not let plan or repository refs edits/reverts resurrect prior consent.
     const repositoryRefsChanged = patch.refs !== undefined && JSON.stringify([task.refs.repo, task.refs.paths]) !== JSON.stringify([next.refs.repo, next.refs.paths]);
     const departureInvalidated = extra.planDepartureInvalidated === true || hasDeparture && (planChanged || repositoryRefsChanged);
-    const history = [...task.history, { at: Date.now(), by, event, ...plannerHistory, ...authorHistory, ...(extra.selfReview === true ? { selfReview: true as const } : {}), ...(planRevision ? { planRevision } : {}), ...(extra.planObservation ? { planObservation: extra.planObservation } : {}), ...(extra.planDeparture ? { planDeparture: extra.planDeparture } : {}), ...(departureInvalidated ? { planDepartureInvalidated: true as const } : {}), ...reviewMetadata, ...(note ? { note } : {}), ...(patch.cancelled?.supersededBy ? { supersededBy: patch.cancelled.supersededBy } : {}), ...("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 } : {}), ...(extra.from ? { from: extra.from } : {}), ...(extra.capacity === true ? { capacity: true as const } : {}), ...(extra.withheld && (note || reviewFindings) ? { withheld: true as const } : {}), ...(reviewFindings ? { reviewFindings } : {}), ...(unmetCriteria?.length ? { unmetCriteria } : {}), ...(deliverables ? { deliverables } : {}), ...(extra.reviewContext === "fresh" || extra.reviewContext === "continuing" ? { reviewContext: extra.reviewContext } : {}), ...(extra.reviewCost ? { reviewCost: extra.reviewCost } : {}), ...(event === "done" && extra.noWrites === true ? { noWrites: true as const } : {}) }];
+    const history = [...task.history, { at: Date.now(), by, event, ...plannerHistory, ...authorHistory, ...(extra.selfReview === true ? { selfReview: true as const } : {}), ...(planRevision ? { planRevision } : {}), ...(extra.planObservation ? { planObservation: extra.planObservation } : {}), ...(extra.planDeparture ? { planDeparture: extra.planDeparture } : {}), ...(departureInvalidated ? { planDepartureInvalidated: true as const } : {}), ...reviewMetadata, ...(note ? { note } : {}), ...(patch.cancelled?.supersededBy ? { supersededBy: patch.cancelled.supersededBy } : {}), ...("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 } : {}), ...(extra.from ? { from: extra.from } : {}), ...(extra.capacity === true ? { capacity: true as const } : {}), ...(extra.withheld && (note || reviewFindings) ? { withheld: true as const } : {}), ...(reviewFindings ? { reviewFindings } : {}), ...(unmetCriteria?.length ? { unmetCriteria } : {}), ...(deliverables ? { deliverables } : {}), ...(extra.reviewContext === "fresh" || extra.reviewContext === "continuing" ? { reviewContext: extra.reviewContext } : {}), ...(extra.reviewScope === "code" ? { reviewScope: "code" as const } : {}), ...(extra.evidenceOnly === true && event === "changes_requested" ? { evidenceOnly: true as const } : {}), ...(extra.reviewCost ? { reviewCost: extra.reviewCost } : {}), ...(event === "done" && extra.noWrites === true ? { noWrites: true as const } : {}) }];
     this.taskWrite(() => {
       const result = this.db.query("UPDATE tasks SET state = ?, owner = ?, reviewer = ?, reserved = ?, refs = ?, plan = ?, rejections = ?, signals = ?, history = ?, sdlc = ?, task_role = ?, cancelled = ?, updated = ?, planner = ? WHERE id = ?")
         .run(next.state, next.owner, next.reviewer, next.reserved ?? null, JSON.stringify(next.refs), JSON.stringify(next.plan ?? {}), next.rejections, JSON.stringify(next.signals), JSON.stringify(history), next.sdlc ? JSON.stringify(next.sdlc) : null, next.role ?? null, next.cancelled ? JSON.stringify(next.cancelled) : null, Date.now(), planner, id);