@staix/agent-hub 0.34.0 → 0.35.0

package/src/cli/model.ts

@@ -0,0 +1,52 @@
+import { isNativeModelToken } from "../adapters/model-token.ts";
+import type { RuntimeModelStatus } from "../hub/model-overrides.ts";
+
+export const MODEL_USAGE = "usage: ahub model set <peer> <model> | clear <peer> | list [--json]";
+const peerToken = (value: unknown): value is string => typeof value === "string" && /^[a-z][a-z0-9-]{0,31}$/.test(value);
+export function parseModelCommand(args: readonly string[]): { op: "list" | "set" | "clear"; peer?: string; model?: string; json: boolean } {
+  const [op, peer, model, ...extra] = args;
+  if (op === "list" && (args.length === 1 || args.length === 2 && peer === "--json")) return { op, json: peer === "--json" };
+  if (op === "clear" && args.length === 2 && peerToken(peer)) return { op, peer, json: false };
+  if (op === "set" && !extra.length && args.length === 3 && peerToken(peer) && isNativeModelToken(model)) return { op, peer, model, json: false };
+  throw new Error(MODEL_USAGE);
+}
+
+/** Closed metadata projection: an older or malformed reply never supplies display prose. */
+export function projectModelStatus(value: unknown): RuntimeModelStatus | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const row: Record<string, unknown> = {};
+  try {
+    for (const key of ["peer", "effectiveModel", "desiredModel", "source", "pendingNextTurn", "unsupported"]) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (descriptor && "value" in descriptor) row[key] = descriptor.value;
+    }
+  } catch { return null; }
+  if (!peerToken(row.peer) || !(row.effectiveModel === null || isNativeModelToken(row.effectiveModel)) || !(row.desiredModel === null || isNativeModelToken(row.desiredModel)) || !(typeof row.source === "string" && ["override", "instance", "launch", "native default", "native thread default (was override)"].includes(row.source)) || typeof row.pendingNextTurn !== "boolean") return null;
+  let unsupported: RuntimeModelStatus["unsupported"];
+  if (row.unsupported !== undefined) {
+    if (!row.unsupported || typeof row.unsupported !== "object" || Array.isArray(row.unsupported)) return null;
+    let reasonCode: unknown, kind: unknown;
+    try {
+      const code = Object.getOwnPropertyDescriptor(row.unsupported, "reasonCode"), adapter = Object.getOwnPropertyDescriptor(row.unsupported, "kind");
+      reasonCode = code && "value" in code ? code.value : undefined;
+      kind = adapter && "value" in adapter ? adapter.value : undefined;
+    } catch { return null; }
+    if (kind !== undefined && !peerToken(kind)) return null;
+    if (reasonCode === "unverified_setter") unsupported = { reasonCode, ...(kind ? { kind } : {}), reason: `unsupported live: ${kind ?? "retained peer"} (version unverified) has no verified model setter`, nextStep: `restart this peer with ahub restart ${row.peer}` };
+    else if (reasonCode === "unmanaged_attachment") unsupported = { reasonCode, reason: "unsupported live: this attachment has no verified live model setter", nextStep: `change the native setting or restart this peer with ahub restart ${row.peer}` };
+    else if (reasonCode === "acp_setter_unavailable") {
+      if (!peerToken(kind)) return null;
+      let version: unknown;
+      try {
+        const descriptor = Object.getOwnPropertyDescriptor(row.unsupported, "version");
+        if (descriptor && !("value" in descriptor)) return null;
+        version = descriptor?.value;
+      } catch { return null; }
+      if (version !== undefined && !(isNativeModelToken(version) && /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/.test(version))) return null;
+      unsupported = { reasonCode, kind, ...(typeof version === "string" ? { version } : {}), reason: `unsupported live: ${kind} ${version ?? "unknown"} lacks a setter receipt or compat admission`, nextStep: `restart this peer with ahub restart ${row.peer}` };
+    }
+    else return null;
+  }
+  return { peer: row.peer, effectiveModel: row.effectiveModel, desiredModel: row.desiredModel, source: row.source as RuntimeModelStatus["source"], pendingNextTurn: row.pendingNextTurn,
+    ...(unsupported ? { unsupported } : {}) };
+}

package/src/cli/output.ts

@@ -1,3 +1,5 @@
+import { projectModelStatus } from "./model.ts";
+import type { RuntimeModelStatus } from "../hub/model-overrides.ts";
 import type { QueueBackpressureStatus } from "../hub/queue-backpressure.ts";
 import { definitionOf } from "../adapters/registry.ts";
 import { windowKind } from "../hub/window-kind.ts";
@@ -14,6 +16,8 @@ import type { SpecsStatus } from "../hub/specs-task.ts";
 
 export interface DoctorCheck { section: "Tools" | "Hub" | "Config" | "Models" | "Memory"; level: "ok" | "warn" | "fail" | "unknown"; name: string; detail: string }
 export interface StatusOutput {
+  runtimeModels?: RuntimeModelStatus[];
+  runtimeModelsUnavailable?: boolean;
   roomsUnavailable?: unknown;
   roomsOpening?: boolean;
   controlWriteTiming?: { active: number; slowRequests: number; blockedLoopSamples: number; droppedActive: number; droppedRecent: number; droppedLogs: number; droppedSpans?: number; droppedMetadata?: number; expiredRequests?: number };
@@ -33,7 +37,7 @@ export interface StatusOutput {
   pendingTaskOffers?: readonly { task: number; peer: string }[];
   isolatedChecks?: { pending?: number; orphans?: string[]; unknownReceipts?: readonly string[]; maintenanceUnavailable?: boolean };
   memoryRead?: { truncated: boolean; scanned: number; limit: number };
-  memoryProfile?: { profile?: string; generation?: string; state?: string; agentMemVersion?: string; skippedRows?: number; error?: string; sync?: { state: "disabled" | "unavailable" | "notrun" | "not-configured" | "stopped" | "ok" | "failed" | "unknown"; at?: number; cause?: string; declinedCount?: number; declinedIdsKnown?: false; withheldCount?: number; exportedCount?: number; placementActive?: false; nextStep?: string } };
+  memoryProfile?: { profile?: string; generation?: string; state?: string; agentMemVersion?: string; skippedRows?: number; error?: string; sync?: { state: "disabled" | "unavailable" | "notrun" | "not-configured" | "stopped" | "ok" | "failed" | "unknown"; at?: number; cause?: string; declinedCount?: number; declinedIdsKnown?: false; withheldCount?: number; exportedCount?: number; placementActive?: false; writerCategory?: string; writerCauseClass?: string; nextStep?: string } };
   /** #784 AC3: `active`, `reviewWait` and `reserved` add up to `wip`; absent from an older hub. */
   taskWip?: Record<string, { wip: number; wipLimit: number; active?: number; reviewWait?: number; reserved?: number }>;
   pid?: number; controlPort?: number; cwd?: string; version?: string; peers: Record<string, any>; roleInfo?: Record<string, any>; actionPolicyInfo?: Record<string, { note: string; enforceable: boolean }>; budget?: Record<string, any>; planner?: { peers?: string[]; source?: string };
@@ -43,6 +47,14 @@ export interface StatusOutput {
 /** `peers`: one note per peer that shows no number, and why (no quota, nothing read yet); absent from an older hub. */
 export interface BudgetOutput { budget: Record<string, any>; gate?: number; peers?: { peer: string; kind?: string; note: string }[] }
 export interface RosterRow { peer: string; on: boolean; startMode: string; state: string; queued: number; tasks: number }
+export function renderRuntimeModels(models: readonly RuntimeModelStatus[], columns?: number): Span[][] {
+  const out = rows(["PEER", "EFFECTIVE MODEL", "SOURCE", "STATE"], models.map(row => [span(row.peer, "info", true), span(row.effectiveModel ?? "not reported"), span(row.source), span(row.pendingNextTurn ? "pending next turn" : "current")]), columns);
+  for (const row of models) {
+    if (row.pendingNextTurn) out.push(...lines(`${row.peer}: next turn ${row.desiredModel ?? "native default"}; the active turn is unchanged.`, columns, "attention"));
+    if (row.unsupported) out.push(...lines(`${row.peer}: ${row.unsupported.reason}; ${row.unsupported.nextStep}`, columns, "attention"));
+  }
+  return out;
+}
 export function renderRoster(data: RosterRow[], columns?: number): Span[][] {
   return rows(["PEER", "ROSTER", "START", "STATE", "Q", "TASKS"], data.map(row => [span(row.peer, "info", true), span(row.on ? "on" : "off", row.on ? "success" : "muted", true), span(row.startMode, undefined, true), span(row.state, stateTone(row.state), true), span(row.queued, undefined, true), span(row.tasks, undefined, true)]), columns);
 }
@@ -218,6 +230,8 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
   if (data.roleInfo) data = { ...data, peers: Object.fromEntries(Object.entries(data.peers).map(([peer, value]) => [peer, { ...value, ...data.roleInfo?.[peer] }])) };
   const out = lines(`agent-hub${data.version ? ` ${data.version}` : ""}  pid ${data.pid ?? "unknown"}  control 127.0.0.1:${data.controlPort ?? "unknown"}`, columns, "info");
   if (data.cwd) out.push(...lines(data.cwd, columns));
+  if (data.runtimeModelsUnavailable === true) out.push(...lines("Runtime models unavailable: could not read a bounded model catalog; run ahub model list for the cause. For a known peer, use ahub model set <peer> <model> or ahub model clear <peer>; repair storage or reduce the retained peer catalog as indicated before listing again.", columns, "attention"));
+  else if (Array.isArray(data.runtimeModels)) out.push(...renderRuntimeModels(data.runtimeModels.map(projectModelStatus).filter((row): row is RuntimeModelStatus => row !== null), columns));
   const timing = data.controlWriteTiming;
   if (full && timing && Object.values(timing).every(value => Number.isSafeInteger(value) && value >= 0)) {
     out.push(...lines(`control writes: active ${timing.active}, slow ${timing.slowRequests}, loop delays ${timing.blockedLoopSamples}, dropped ${timing.droppedActive + timing.droppedLogs + (timing.droppedSpans ?? 0) + (timing.droppedMetadata ?? 0)}, expired ${timing.expiredRequests ?? 0}; timings in hub.log`, columns, timing.slowRequests || timing.blockedLoopSamples ? "attention" : undefined));
@@ -290,6 +304,14 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
   let settling = false;
   const peerDetails = Object.entries(data.peers).map(([id, p]) => {
     const out: Span[][] = [];
+    // #1310: the current owner, when the hub reported one. Shown before the standby rows so the owner is never inferred from them. Every value is re-checked here: a pid is a positive integer, a time is
+    // finite, and a native session id is shown only when it is a short plain token; anything else is left out rather than cleaned up.
+    const owner = p.ownerAttachment;
+    if (owner && typeof owner === "object" && Number.isFinite(owner.attachedAt)) {
+      const pid = Number.isSafeInteger(owner.ownerPid) && owner.ownerPid > 0 ? `pid ${owner.ownerPid}` : "pid unknown";
+      const native = typeof owner.nativeSessionId === "string" && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(owner.nativeSessionId) ? `native session ${owner.nativeSessionId}` : "native session unverified";
+      out.push(...detail(`${id} owner`, `${pid}; attached ${relative(owner.attachedAt, now)}; ${native}`, columns, "muted"));
+    }
     for (const session of Array.isArray(p.standbySessions) ? p.standbySessions : []) {
       if (!session || typeof session.id !== "string" || !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(session.id)) continue;
       const pid = Number.isSafeInteger(session.pid) && session.pid > 0 ? String(session.pid) : "unknown";

package/src/cli/recovery-package.ts

@@ -212,24 +212,32 @@ export function stageCurrentRuntime(sourceRoot: string, version: string, home =
   } finally { if (!registry) owner.close(); }
 }
 
+/** #1253: npm 12 wraps `npm view --json` output for one package in a one-element array; npm 11 printed the value itself. Anything else is not one release. */
+function npmViewJson(stdout: string): unknown {
+  let value: unknown;
+  try { value = JSON.parse(stdout); } catch { return undefined; }
+  if (!Array.isArray(value)) return value;
+  return value.length === 1 ? value[0] : undefined;
+}
+
 export async function registryRelease(version: string, run: RunCommand = runCommand): Promise<{ version: string; integrity: string }> {
   exactVersion(version);
   const result = await run(["npm", "view", `@staix/agent-hub@${version}`, "version", "dist.integrity", "--json"], { timeoutMs: 30_000 });
   if (result.code !== 0) throw new Error(`registry metadata unavailable for @staix/agent-hub@${version}`);
-  const data = JSON.parse(result.stdout);
-  if (data.version !== version || typeof data["dist.integrity"] !== "string" || !data["dist.integrity"].startsWith("sha512-")) {
-    throw new Error("registry returned an unexpected release identity");
+  const data = npmViewJson(result.stdout) as Record<string, unknown> | undefined;
+  const integrity = data?.["dist.integrity"];
+  if (data?.version !== version || typeof integrity !== "string" || !integrity.startsWith("sha512-")) {
+    throw new Error(`registry returned an unexpected release identity for @staix/agent-hub@${version} (expected one release with a sha512 integrity from \`npm view --json\`); check \`npm view @staix/agent-hub@${version} version dist.integrity --json\` and your npm version`);
   }
-  return { version, integrity: data["dist.integrity"] };
+  return { version, integrity };
 }
 
 /** #272: the registry's latest release, the target when `--to` is left out. */
 export async function latestRelease(run: RunCommand = runCommand): Promise<string> {
   const result = await run(["npm", "view", "@staix/agent-hub", "version", "--json"], { timeoutMs: 30_000 });
   if (result.code !== 0) throw new Error("registry metadata unavailable for @staix/agent-hub; name the release with --to <version>");
-  let version: unknown;
-  try { version = JSON.parse(result.stdout); } catch { /* reported below */ }
-  if (typeof version !== "string") throw new Error("registry returned an unexpected latest release; name the release with --to <version>");
+  const version = npmViewJson(result.stdout);
+  if (typeof version !== "string") throw new Error("registry returned an unexpected latest release (expected one version from `npm view --json`); check `npm view @staix/agent-hub version --json`, or name the release with --to <version>");
   return exactVersion(version);
 }
 

package/src/cli/reset.ts

@@ -149,7 +149,7 @@ export function resetRuntime(stateDir: string, project: Project): { settled: str
     const db = openHubDatabase(file);
     try {
       db.transaction(() => {
-        for (const table of ["budget_pauses", "conductor_holds"]) {
+        for (const table of ["budget_pauses", "conductor_holds", "model_overrides"]) {
           if (db.query("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(table)) db.run(`DELETE FROM ${table}`);
         }
       })();

package/src/cli/status-lines.ts

@@ -1,11 +1,11 @@
 import { projectRoomUnavailable } from "../rooms/status.ts";
 import type { ContextView } from "../hub/context-window.ts";
-import { memorySyncNextStep, type MemorySyncCause } from "../hub/memory-sync-state.ts";
+import { memorySyncNextStep, WRITER_CATEGORIES, WRITER_CAUSE_CLASSES, type MemorySyncCause } from "../hub/memory-sync-state.ts";
 // What `ahub status` prints for a peer and for a model backend, kept pure so it can be checked.
 
 export interface PeerRow { permissionMode?: string; context?: ContextView; state?: string; queued?: number; queuedImportant?: number; needsReview?: number; heldBy?: string; holdNote?: string; reviewObserverHoldNote?: string; liveAccepted?: string[]; oldestQueuedAt?: number; importantWaitingSince?: number; importantWaitingNote?: string; attached?: boolean; attachMode?: "channel" | "tools-only"; attachEvidence?: string; toolsOnly?: string; pullOnly?: boolean; lastInboxAt?: number | null; permissionNote?: string; reviewerUnavailable?: string; paused?: string; servedBy?: string; requestedModel?: string }
 export interface BackendRow { kind?: string; alias?: string; state?: string; active?: number; requestedModel?: string; actualModel?: string; provider?: string; coolingUntil?: string; failures?: number; failingUntil?: string }
-export interface MemorySyncRow { state?: string; at?: number; cause?: string; declinedCount?: number; declinedIdsKnown?: false; withheldCount?: number; exportedCount?: number; placementActive?: false; nextStep?: string }
+export interface MemorySyncRow { state?: string; at?: number; cause?: string; declinedCount?: number; declinedIdsKnown?: false; withheldCount?: number; exportedCount?: number; placementActive?: false; writerCategory?: string; writerCauseClass?: string; nextStep?: string }
 export interface ReviewInputHealthRow { state?: string; cause?: string | null }
 
 /** Aliases are already namespaced ("dgx/coding"); only an alias that is not gets its kind in front of it. */
@@ -32,11 +32,15 @@ export function memorySyncLine(sync: MemorySyncRow, time = (at: number) => new D
     && Number.isSafeInteger(sync.exportedCount) && sync.exportedCount! >= 0)
     return `ok${stamp}; ${sync.withheldCount} row${sync.withheldCount === 1 ? "" : "s"} withheld locally; ${sync.exportedCount} exported`;
   if (state !== "failed") return `${state}${stamp}`;
-  const causes = ["declined", "remote", "binding", "stopped", "transport", "unknown"];
+  const causes = ["declined", "remote", "binding", "stopped", "transport", "writer", "unknown"];
   const cause = (causes.includes(sync.cause ?? "") ? sync.cause : "unknown") as MemorySyncCause;
   if (cause === "declined" && sync.placementActive === false) {
     const declined = Number.isSafeInteger(sync.declinedCount) && sync.declinedCount! >= 0 ? String(sync.declinedCount) : "unknown";
-    return "machine sync blocked: " + declined + " declined rows; per-row placement is not active on this store. Activation is person-only: preview with `amem migrate --sync-placement --dry-run` and declare every writer via --writer-root. The hub does not yet supply the fresh placementAttestation required for active-placement sync (#1173). Inspect with `ahub memory declined`.";
+    return "machine sync blocked: " + declined + " declined rows; per-row placement is not active on this store. Activation is person-only: preview with `amem migrate --sync-placement --dry-run` and declare every writer via --writer-root. Inspect with `ahub memory declined`.";
+  }
+  if (cause === "writer") {
+    const category = WRITER_CATEGORIES.includes(sync.writerCategory ?? "") ? sync.writerCategory : "unknown", causeClass = WRITER_CAUSE_CLASSES.includes(sync.writerCauseClass ?? "") ? sync.writerCauseClass : "unavailable";
+    return `failed (writer attestation refused: ${category}, ${causeClass})${stamp}; next: ${memorySyncNextStep("writer")}`;
   }
   const count = Number.isSafeInteger(sync.declinedCount) && sync.declinedCount! >= 0 ? `, ${sync.declinedCount} declined` : "";
   const ids = cause === "declined" && sync.declinedIdsKnown === false ? "; declined ID set unknown" : "";

package/src/hub/budget.ts

@@ -54,7 +54,7 @@ export interface BudgetConfig {
   wait_max_min: number;
 }
 // wait_max_min is off here, as approvals.notify is: a project config turns it on (30 unless it says otherwise).
-export const DEFAULT_BUDGET: BudgetConfig = { gate: 0.9, stale_min: 30, poll_min: 10, checkpoint_timeout_s: 90, kimi_tokens_5h: 0, wait_max_min: 0 };
+export const DEFAULT_BUDGET: BudgetConfig = { gate: 0.99, stale_min: 30, poll_min: 10, checkpoint_timeout_s: 90, kimi_tokens_5h: 0, wait_max_min: 0 };
 
 export type BudgetLedgerEntry =
   | { type: "budget_pause"; peer: PeerId; reason: string; window: string; resetsAt: number; by: "hub" | "person" }

package/src/hub/bus.ts

@@ -9,6 +9,7 @@ import { DELIVERY_RETRY_WARNING } from "./delivery-hints.ts";
 import { MAX_DEFERRED_HUB, RecoveryDeferredHubError, validateDeferredHub } from "./deferred-hub.ts";
 import { parseRemotePeerId } from "../rooms/application.ts";
 import { PreEffectToolRefusal } from "./tool-refusal.ts";
+import { stripRecordLines } from "../memory/records.ts";
 
 export type { DeliveryReceipt } from "./peers.ts";
 
@@ -214,6 +215,10 @@ export class Bus {
    * peer was handed (the request is in it, never condensed), so a reply that answers an invocation is found by identity, not by addressing.
    */
   onAnswer?: (peer: PeerId, text: string, answers: readonly Envelope[]) => boolean;
+  /** Completed adapter answers only, under the same public-input observer ceiling as memory delivery. */
+  onFinalAnswer?: (peer: PeerId, text: string, context: { out: readonly Envelope[]; originals: readonly Envelope[] }) => void;
+  /** Count-only forwarding telemetry; never emitted for a private, review-scoped or unbound answer. */
+  onFinalAnswerBytes?: (peer: PeerId, counts: { before: number; after: number }) => void;
   /** Host ledger authority; absent or unknown never permits invocation replay. */
   canRetryInvocation?: (id: string) => boolean;
   onInvocationUncertain?: (id: string) => void;
@@ -315,7 +320,10 @@ export class Bus {
     peer.onDelivery = (receipt) => { if (this.peers.get(peer.id) === peer) this.deliveryReceipt(peer.id, receipt); };
     peer.onDoing = (kind, text) => { if (kind === "reset") this.clearReviewProvenance(peer.id); if (!this.closed && this.peers.get(peer.id) === peer) this.opts.doing?.(peer.id, kind, text); };
     this.opts.doing?.(peer.id, "reset"); // a new adapter never shows what the one it replaces was doing
-    peer.onMessage = (text, opts) => {
+    // A final still traverses the current onMessage observer exactly once. This one-shot
+    // marker is host-local, never a caller-supplied envelope or wire field.
+    let finalMessage: { body: string; options: EnvelopeOpts | undefined; complete: boolean } | undefined;
+    const receive = (text: string, opts?: EnvelopeOpts, final = false, complete = true) => {
       if (!this.isRostered(peer.id)) return `off roster: ${peer.id}`;
       // #445 C2: an answer to an invocation is found by what the peer was handed, never by how the answer is addressed, so a headless agent whose final answer is
       // normally shared with every peer cannot leak it. It is the invocation's answer when it names the request itself (an adapter may report its delivery complete before
@@ -331,12 +339,29 @@ export class Bus {
           : parentId === undefined && this.invocationTurnOpen(peer.id)
             ? pushedInvocation ? pushed : pulledInvocation ? pulled : undefined
             : undefined;
+      let finalPriority: Priority | undefined;
+      if (final) {
+        const context = parentId === undefined ? pulled ?? pushed : namedPush ? pushed : namedPull ? pulled : undefined;
+        const raw = text;
+        finalPriority = parseMarker(raw).priority;
+        // Strip before invocation routing, publication, journaling, digests or the console event tap.
+        text = stripRecordLines(raw);
+        let observable = !this.closed && this.peers.get(peer.id) === peer && !!context && opts?.private !== true && !remoteId(peer.id) && !opts?.to?.some(remoteId) && !answerParent;
+        try {
+          observable &&= this.opts.reviewObserverInputExcluded?.(peer.id, context!.originals) !== true &&
+            ![...context!.out, ...context!.originals].some(env => env.private || isReviewObserverExcluded(env) || isInvocationKind(env) || remoteId(env.from) || env.to?.some(remoteId));
+        } catch { observable = false; }
+        if (observable) {
+          if (complete) try { this.onFinalAnswer?.(peer.id, raw, context!); } catch { /* capture is optional and never changes answer routing */ }
+          try { this.onFinalAnswerBytes?.(peer.id, { before: Buffer.byteLength(parseMarker(raw).body), after: Buffer.byteLength(parseMarker(text).body) }); } catch { /* count-only observer */ }
+        }
+      }
       if (this.onAnswer && answerParent && (namedPush || namedPull || parentId === undefined && this.invocationTurnOpen(peer.id))) {
         let taken = false;
         try { taken = this.onAnswer(peer.id, text, answerParent.out) === true; } catch { taken = true; } // a throwing host never turns a callee's answer into a broadcast
         if (taken) return;
       }
-      const { priority, body } = parseMarker(text);
+      const parsed = parseMarker(text), priority = finalPriority ?? parsed.priority, body = parsed.body;
       if (!body) return;
       // What the peer was handed differs from what it stands for once a delivery was condensed; both the audience
       // and the priority ceiling are about what it stands for.
@@ -393,6 +418,19 @@ export class Bus {
       if (hushed.length) this.note(peer.id, noteLine(HUB, "decision", `your message was not delivered to ${hushed.map((h) => h.peer).join(", ")}: ${hushed[0]!.reason}`));
       return heldBack ? hushed[0]!.reason : published.dropped === "hop" ? published : undefined;
     };
+    peer.onMessage = (text, opts) => {
+      if (this.peers.get(peer.id) !== peer) return;
+      const marker = finalMessage?.body === text && finalMessage.options === opts ? finalMessage : undefined;
+      if (marker) finalMessage = undefined; // Consume before observers can emit nested diagnostics.
+      return receive(text, opts, marker !== undefined, marker?.complete ?? true);
+    };
+    peer.onFinalAnswer = (text, opts, complete = true) => {
+      if (this.closed || this.peers.get(peer.id) !== peer) return;
+      const previous = finalMessage;
+      finalMessage = { body: text, options: opts, complete };
+      try { return peer.onMessage?.(text, opts); }
+      finally { finalMessage = previous; }
+    };
     peer.onFailed = (envs, failure) => {
       // The adapter got the condensed list; what has to come back is what that list replaced.
       const last = this.lastDelivery.get(peer.id);

package/src/hub/code-facts.ts

@@ -95,9 +95,13 @@ export class CodeFacts {
       catch{throw Error("code facts cleanup unconfirmed");}
     }
   }
-  constructor(private readonly options:{env?:NodeJS.ProcessEnv;timeoutMs?:number;now?:()=>number}={}) {}
+  /** #1261: `trace` is a read-only timing tap for tests (the step's name, its wall time in ms and its outcome). Absent in production, where it costs one undefined check per step; it never changes an answer, a bound or a cap. */
+  constructor(private readonly options:{env?:NodeJS.ProcessEnv;timeoutMs?:number;now?:()=>number;trace?:(step:string,ms:number,outcome:string)=>void}={}) {}
   private git(repo:string,args:string[]) {
-    return hubGitSync(["-C",repo,...args],{encoding:"utf8",env:hubGitEnv(childEnv(),{repositoryIsolation:true}),timeout:5000,maxBuffer:1024*1024});
+    const trace=this.options.trace,t0=trace?performance.now():0;
+    const r=hubGitSync(["-C",repo,...args],{encoding:"utf8",env:hubGitEnv(childEnv(),{repositoryIsolation:true}),timeout:5000,maxBuffer:1024*1024});
+    trace?.(`git ${args.slice(0,2).join(" ")}`,performance.now()-t0,r.error?.message??`status ${r.status}`);
+    return r;
   }
   private value(repo:string,args:string[]):string {const r=this.git(repo,args);if(r.status!==0)throw Error();return r.stdout.trim();}
   private nativeEnv(cwd:string):NodeJS.ProcessEnv {
@@ -115,7 +119,7 @@ export class CodeFacts {
   private async run(bin:string,args:string[],cwd:string):Promise<{code:number;out:string}> {
     if(this.closing || this.active?.cancelled)return {code:1,out:""};
     return new Promise(resolve=>{
-      let child:ReturnType<typeof spawn>;
+      let child:ReturnType<typeof spawn>;const trace=this.options.trace,t0=trace?performance.now():0;
       try{child=spawn(process.execPath,["-e",LAUNCHER,"--",bin,...args],{cwd,env:this.nativeEnv(cwd),detached:true,stdio:["ignore","pipe","ignore","pipe"]});}catch{resolve({code:1,out:""});return;}
       let size=0,done=false,failed=false,control="";const parts:Buffer[]=[];
       let ended=false;const outputEnd=new Promise<void>(resolveEnd=>child.stdout!.once("end",()=>{ended=true;resolveEnd();}));
@@ -125,6 +129,7 @@ export class CodeFacts {
         if(!ended)code=null;
         try{await stopOwnedProcess(child,{group:true,termMs:50,killMs:500});}catch{this.failedChild=child;code=null;}
         if(this.cancelActive===cancel)this.cancelActive=undefined;
+        trace?.(`ripwire ${args.find(a=>a.startsWith("--"))?.split("=")[0]??"launch"}`,performance.now()-t0,failed?"failed, capped or cancelled":`code ${code}`);
         resolve({code:failed?1:code??1,out:!failed && code!==null?Buffer.concat(parts).toString("utf8"):""});
       };
       const cancel=()=>{void finish(null);};this.cancelActive=cancel;
@@ -157,7 +162,9 @@ export class CodeFacts {
       if(this.git(repo,["worktree","add","--detach","--no-checkout",cwd,head]).status!==0)throw Error();registered=true;
       if(this.git(cwd,["read-tree",head]).status!==0)throw Error();
       // --batch needs explicit object ids; no working-tree filters or checkout hooks are invoked.
+      const catAt=this.options.trace?performance.now():0;
       const result=hubGitSync(["-C",repo,"cat-file","--batch"],{input:entries.map(e=>e.oid).join("\n")+"\n",encoding:"latin1",env:hubGitEnv(childEnv(),{repositoryIsolation:true}),timeout:5000,maxBuffer:MAX_TREE_BYTES+1024*1024});
+      this.options.trace?.("git cat-file --batch",performance.now()-catAt,result.error?.message??`status ${result.status}`);
       if(result.status!==0)throw Error();
       const bytes=Buffer.from(result.stdout,"latin1");let offset=0,total=0;
       for(const entry of entries){

package/src/hub/completions.ts

@@ -26,6 +26,8 @@ export interface SettleFacts {
   runningChecks: number;
   /** Rows held or in `needs_review`: uncertain, so never settled. */
   heldDeliveries: number;
+  /** Native background work when the adapter exposes an inventory; null means the inventory exists but is unreadable or incomplete. */
+  nativeBackground?: number | null;
 }
 
 export type RunState = "working" | "needs-input" | "settled";
@@ -33,7 +35,7 @@ export type RunState = "working" | "needs-input" | "settled";
 /** The one rule. A permission or question wins over everything else: the person has to act, so the run is needs-input and never "done". */
 export function settleVerdict(facts: SettleFacts): RunState {
   if (facts.openPermissions > 0 || facts.openQuestions > 0) return "needs-input";
-  if (!facts.signal || facts.queuedContinuations > 0 || facts.ownedChildren > 0 || facts.runningChecks > 0 || facts.heldDeliveries > 0) return "working";
+  if (!facts.signal || facts.queuedContinuations > 0 || facts.ownedChildren > 0 || facts.runningChecks > 0 || facts.heldDeliveries > 0 || facts.nativeBackground === null || (facts.nativeBackground ?? 0) > 0) return "working";
   return "settled";
 }
 

package/src/hub/config-apply.ts

@@ -226,6 +226,7 @@ const schema: Record<string, Check> = {
     else if (key === "remote") remoteRunnerConfig(value);
     else if (/^[a-z][a-z0-9_]{0,47}$/.test(key)) text(value, `${k}.${key}`); else fail(`${k}.${key}`, "unknown key");
   } },
+  visuals: block({ retention_days: number(1, 3650, true) }),
   snapshots: block({ enabled: bool, keep: number(1, 1_000_000, true) }), research: block({ enabled: bool, runners: researchRunners }), bench: block({ enabled: bool }),
   worktrees: block({ quiet_days: number(0, 3650, true), alert_over: number(0, 100_000, true) }),
   // #1053: how long an unanswered question waits (`ttl_s`, 1 minute to 30 days) and, per adapter kind, how long a `hub_ask` call waits for the person before it answers `pending`.
@@ -276,7 +277,7 @@ const restart: Record<string, string> = {
   profile: "Session tool schemas and profile contracts are bound at startup", profile_overrides: "Session tool schemas and profile contracts are bound at startup",
   text_projection: "Converter and cache ownership are bound at startup", corpus: "The corpus index is bound to its roots at startup", terminal: "Terminal provider is supplied by the daemon lifecycle", bench: "Benchmark execution environment is selected before work starts",
 };
-const live = new Set(["action_policy", "permission", "roster", "roles", "planner", "conductor", "protect_instruction_files", "task_sweep", "capabilities", "invocation", "research", "snapshots", "worktrees", "tasks.wip_limits", "tasks.escalate_after", "tasks.auto_pull", "tasks.queue_backpressure", "schedules", "approvals.notify", "questions", "pet", "specs"]);
+const live = new Set(["visuals", "action_policy", "permission", "roster", "roles", "planner", "conductor", "protect_instruction_files", "task_sweep", "capabilities", "invocation", "research", "snapshots", "worktrees", "tasks.wip_limits", "tasks.escalate_after", "tasks.auto_pull", "tasks.queue_backpressure", "schedules", "approvals.notify", "questions", "pet", "specs"]);
 const nextMemory = new Set(["memory.inject_tokens", "memory.brief_items", "memory.suggest_edges"]);
 /** Closed top-level schema; leaf overrides retain the existing session/runtime boundaries. */
 export function configApply(key: string, scopes: readonly ConfigIdentityScope[] = []): ApplyRule {

package/src/hub/control-client.ts

@@ -21,7 +21,7 @@ export const PROTOCOL = 17;
 /** The descriptor's legacy protocol field remains this floor for previous published clients. */
 export const PROTOCOL_MIN = 16;
 // Literal metadata is read without executing a recovery target; consistency is pinned in tests.
-export const DAEMON_FEATURES = ["project_autonomy", "conductor_recovery", "encrypted_rooms", "external_adapter_instances", "external_adapter_modules", "configured_acp", "native_hook_launch", "task_cancel", "invocation", "recovery_deferred_hub", "peer_instances", "role_stages", "task_planners", "release_trains", "reviewer_pool", "native_tui_launch", "terminal_owner", "cli_audit_delegated", "action_policy_floor", "calendar_schedules", "research_records", "research_dispatch", "research_dropped_offers", "research_experiments", "research_comparisons", "research_runners", "task_handoff", "session_identity", "schema_guard", "design_specs", "queue_discard_states", "tool_write_idempotency", "research_evidence", "review_comments", "questions", "accepted_delivery_settlement", "completions", "review_observer_input_state", "task_handoff_key", "task_handoff_seq", "peer_takeover"] as const;
+export const DAEMON_FEATURES = ["model_overrides", "visuals", "project_autonomy", "conductor_recovery", "encrypted_rooms", "external_adapter_instances", "external_adapter_modules", "configured_acp", "native_hook_launch", "task_cancel", "invocation", "recovery_deferred_hub", "peer_instances", "role_stages", "task_planners", "release_trains", "reviewer_pool", "native_tui_launch", "terminal_owner", "cli_audit_delegated", "action_policy_floor", "calendar_schedules", "research_records", "research_dispatch", "research_dropped_offers", "research_experiments", "research_comparisons", "research_runners", "task_handoff", "session_identity", "schema_guard", "design_specs", "queue_discard_states", "tool_write_idempotency", "research_evidence", "review_comments", "questions", "accepted_delivery_settlement", "completions", "review_observer_input_state", "task_handoff_key", "task_handoff_seq", "peer_takeover"] as const;
 /** Protocols a current coordinator may authenticate while upgrading a running source. */
 export const RECOVERY_SOURCE_PROTOCOLS = [9, 10, 11, 12, 13, 14, 15, 16, PROTOCOL] as const;