@staix/agent-hub 0.34.0 → 0.35.0

package/src/hub/kimi-usage.ts

@@ -1,30 +1,43 @@
 import { KimiWireReader, kimiCountedTokens, type KimiWireReason, type KimiWireRow } from "../adapters/kimi-wire-usage.ts";
+import type { TaskAttribution } from "./attribution.ts";
 import { TokenWindow } from "./token-window.ts";
 
 /**
  * The hub's own count of Kimi's consumption (#285 phase 2): the wire-log rows of the session the adapter owns become `usage` and
- * `tokens` events and a rolling 5 h window against `budget.kimi_tokens_5h`. Read at a turn end and when a `usage_update` arrives:
- * no watcher, no timer. The ports keep the event log, the budget and the clock in the daemon.
+ * `tokens` events and a rolling 5 h window against `budget.kimi_tokens_5h`. Read at a turn end, when a `usage_update` arrives and for
+ * a bounded backoff after each cue. Each scheduled slice returns to the event loop before the next one. The ports keep the event log,
+ * the budget, the clock and delayed scheduling in the daemon.
  */
 export const KIMI_WINDOW_MS = 5 * 3_600_000;
 /** A turn's rows are written after it starts: a row older than the hub's first sight of the session (less this slack) is history. */
 const FLOOR_SLACK_MS = 1000;
 const PASSES = 16;
+const FOLLOW_UP_DELAYS_MS = [250, 1000, 2000] as const;
+const TURN_INTERVAL_LIMIT = 32;
 /** Failures a retry can cure: the log was not there yet, or was cut mid-write. Anything else says the count no longer matches the log. */
 const TRANSIENT: ReadonlySet<KimiWireReason> = new Set(["no-index", "io-error", "partial-line"]);
 
+export type KimiUsageScheduler = (delayMs: number, run: () => void) => () => void;
+export interface KimiTurnStart { id: string; startedAt: number; attribution: TaskAttribution }
+export interface KimiRowAttribution { attribution: TaskAttribution; turn?: string }
+interface KimiTurnInterval extends KimiTurnStart { endedAt?: number }
+
 export interface KimiUsagePorts {
   /** Kimi's data home. */
   home: string;
   /** Per-call byte bound of the reader (its default otherwise); a test shrinks it to force several passes. */
   maxBytes?: number;
+  /** Numeric I/O observations for deterministic benchmarks; no path, row or native text. */
+  observe?(stats: { bytes: number; discovery: number }): void;
   now(): number;
   /** `budget.kimi_tokens_5h`, read live: 0 turns the window off, never the events. */
   ceiling(): number;
   /** The adapter's own session id, undefined when none is bound. */
   session(peer: string): string | undefined;
-  /** One usage event and its counted tokens (`counted` is the one rule in `kimiCountedTokens`). */
-  record(peer: string, row: KimiWireRow, counted: number): void;
+  /** One delayed drain at a time. Its cancellation leaves no live timer. Production uses an unreferenced timer. */
+  schedule?: KimiUsageScheduler;
+  /** One usage event and its counted tokens (`counted` is the one rule in `kimiCountedTokens`), with its captured turn attribution. */
+  record(peer: string, row: KimiWireRow, counted: number, attributed: KimiRowAttribution): void;
   /** The window as a reading: `used` is not clamped here. */
   report(peer: string, window: { used: number; resetsAt: number; ceiling: number }): void;
   /** The count cannot be trusted now: the peer's `tokens` reading is dropped, so it shows unknown rather than a short number. */
@@ -33,7 +46,20 @@ export interface KimiUsagePorts {
   notice(line: string): void;
 }
 
-interface Bound { session: string; reader: KimiWireReader; floor: number; unknown?: KimiWireReason; noticed?: KimiWireReason }
+interface Bound {
+  session: string;
+  reader: KimiWireReader;
+  floor: number;
+  turns: KimiTurnInterval[];
+  followUp: number;
+  passes: number;
+  backlog: boolean;
+  burst: boolean;
+  reportPending: boolean;
+  pending?: () => void;
+  unknown?: KimiWireReason;
+  noticed?: KimiWireReason;
+}
 
 export class KimiUsage {
   private readonly bound = new Map<string, Bound>();
@@ -41,6 +67,7 @@ export class KimiUsage {
   private readonly seen = new Set<string>();
   /** A log that stopped matching the count leaves the window short of the truth until its rows age out. */
   private readonly taintedUntil = new Map<string, number>();
+  private stopped = false;
 
   constructor(private readonly ports: KimiUsagePorts) {}
 
@@ -65,42 +92,110 @@ export class KimiUsage {
   }
 
   /** The peer went offline: its log is no longer read, so an unreadable state of it must not hold the other peers' figure unknown. */
-  drop(peer: string): void { this.bound.delete(peer); }
+  drop(peer: string): void {
+    const held = this.bound.get(peer);
+    if (held) this.cancel(held);
+    this.bound.delete(peer);
+  }
+
+  /** Stop only delayed work. A final synchronous offline read can still use the bound readers. */
+  stop(): void {
+    this.stopped = true;
+    for (const state of this.bound.values()) this.cancel(state);
+  }
 
   /** A new window: the old counts would pause the peer again at once (after a budget resume). */
   reset(): void { this.window.reset(); this.taintedUntil.clear(); }
 
-  /** Called when a turn starts. It only binds the session and fixes the history floor: nothing is read here, and what the log already holds is not this hub's to count. */
-  turnStarted(peer: string): void { this.bind(peer); }
+  /** Called when a turn starts. It binds the session, fixes the history floor and captures this turn's immutable attribution. */
+  turnStarted(peer: string, turn?: KimiTurnStart): void {
+    const bound = this.bind(peer);
+    if (!bound || !turn || bound.turns.some(interval => interval.id === turn.id)) return;
+    bound.turns.push({ ...turn, attribution: { ...turn.attribution } });
+    if (bound.turns.length > TURN_INTERVAL_LIMIT) bound.turns.splice(0, bound.turns.length - TURN_INTERVAL_LIMIT);
+  }
+
+  turnEnded(peer: string, turn: string, endedAt: number): void {
+    const bound = this.bound.get(peer);
+    const index = bound?.turns.findIndex(interval => interval.id === turn) ?? -1;
+    if (!bound || index < 0) return;
+    bound.turns[index] = { ...bound.turns[index]!, endedAt };
+  }
+
+  private cancel(bound: Bound): void {
+    bound.pending?.(); bound.pending = undefined; bound.burst = false; bound.followUp = 0;
+  }
 
   private bind(peer: string): Bound | undefined {
-    const session = this.ports.session(peer);
-    if (!session) return undefined;
-    const held = this.bound.get(peer);
+    const session = this.ports.session(peer), held = this.bound.get(peer);
+    if (!session) {
+      if (held) this.cancel(held);
+      this.bound.delete(peer);
+      return undefined;
+    }
     if (held?.session === session) return held;
-    const next: Bound = { session, reader: new KimiWireReader({ home: this.ports.home, sessionId: session, ...(this.ports.maxBytes ? { maxBytes: this.ports.maxBytes } : {}) }), floor: this.ports.now() - FLOOR_SLACK_MS };
+    if (held) this.cancel(held);
+    const next: Bound = {
+      session,
+      reader: new KimiWireReader({ home: this.ports.home, sessionId: session, ...(this.ports.maxBytes ? { maxBytes: this.ports.maxBytes } : {}) }),
+      floor: this.ports.now() - FLOOR_SLACK_MS,
+      turns: [], followUp: 0, passes: 0, backlog: false, burst: false, reportPending: false,
+    };
     this.bound.set(peer, next);
     return next;
   }
 
-  collect(peer: string): void {
+  collect(peer: string, scheduled = false, terminal = false): void {
     const bound = this.bind(peer);
     if (!bound) return;
-    let added = 0, more = false;
-    for (let pass = 0; pass < PASSES; pass++) {
-      const read = bound.reader.read();
-      // Each successful pass has already moved the reader's offsets: its rows are recorded now, before a later pass can fail, or they would
-      // never be read again and the count would be short.
-      if (read.status === "unknown") { this.unknown(peer, bound, read.reason); return; }
-      added += this.record(peer, bound, read.rows);
-      more = read.more;
-      if (!more) break;
+    try {
+      if (bound.passes >= PASSES) bound.passes = 0;
+      let added = 0, more = false;
+      // Without a scheduler or for the terminal offline read, retain the bounded synchronous drain. Other scheduled work uses one slice per invocation.
+      for (let pass = 0, slices = terminal || !this.ports.schedule ? PASSES : 1; pass < slices; pass++) {
+        const read = bound.reader.readSlice();
+        // A successful slice records and commits every row before a later slice can fail. An event failure leaves the slice uncommitted,
+        // so the next drain reads it again and the seen set removes only rows whose events already succeeded.
+        if (read.status === "unknown") { bound.backlog = false; bound.passes = 0; this.unknown(peer, bound, read.reason); return; }
+        this.ports.observe?.(bound.reader.stats());
+        try { added += this.record(peer, bound, read.rows); }
+        catch (error) { bound.backlog = false; bound.passes = 0; throw error; }
+        read.commit();
+        more = read.more;
+        bound.backlog = more;
+        bound.passes = more ? bound.passes + 1 : 0;
+        if (!more) break;
+      }
+      const recovered = bound.unknown !== undefined;
+      bound.unknown = undefined;
+      // ponytail: PASSES slices per cue burst. A longer backlog continues in the next burst, and no figure is reported until it is
+      // caught up: a window that is still catching up would be short. Upgrade: seek to the end at bind.
+      if (!more && (added > 0 || recovered || bound.reportPending)) { this.report(peer); bound.reportPending = false; }
+    } finally {
+      if (this.bound.get(peer) === bound) this.schedule(peer, bound, scheduled);
+    }
+  }
+
+  private schedule(peer: string, bound: Bound, scheduled: boolean): void {
+    const schedule = this.ports.schedule;
+    if (!schedule || this.stopped) return;
+    const run = () => {
+      bound.pending = undefined;
+      if (this.bound.get(peer) === bound) try { this.collect(peer, true); } catch { /* scheduled retries stay bounded */ }
+    };
+    if (bound.backlog && bound.passes < PASSES) {
+      if (!bound.pending) bound.pending = schedule(0, run);
+      return;
+    }
+    if (bound.pending) {
+      // A fresh cue during the last pending follow-up still gets a complete bounded retry sequence, without adding another timer.
+      if (!scheduled && bound.followUp >= FOLLOW_UP_DELAYS_MS.length - 1) { bound.burst = true; bound.followUp = 0; }
+      return;
     }
-    const recovered = bound.unknown !== undefined;
-    bound.unknown = undefined;
-    // ponytail: PASSES x the reader's per-call bound. A longer unread backlog (a resumed session with a huge log) is finished by the next
-    // call, and no figure is reported until it is: a window that is still catching up would be short. Upgrade: seek to the end at bind.
-    if (!more && (added > 0 || recovered)) this.report(peer);
+    if (!bound.burst) { bound.burst = true; bound.followUp = 0; }
+    if (bound.followUp >= FOLLOW_UP_DELAYS_MS.length) { bound.burst = false; bound.followUp = 0; return; }
+    const delay = FOLLOW_UP_DELAYS_MS[bound.followUp++]!;
+    bound.pending = schedule(delay, run);
   }
 
   private record(peer: string, bound: Bound, rows: KimiWireRow[]): number {
@@ -108,15 +203,23 @@ export class KimiUsage {
     const now = this.ports.now();
     for (const row of rows) {
       if (this.seen.has(row.id) || row.at < bound.floor) continue;
+      const counted = kimiCountedTokens(row), attributed = this.attribute(bound, row.at);
+      this.ports.record(peer, row, counted, attributed);
       this.seen.add(row.id);
-      const counted = kimiCountedTokens(row);
-      this.ports.record(peer, row, counted);
       this.window.add(Math.min(row.at, now), counted);
+      if (counted > 0) bound.reportPending = true;
       added += counted;
     }
     return added;
   }
 
+  private attribute(bound: Bound, at: number): KimiRowAttribution {
+    const matches = bound.turns.filter(interval => at >= interval.startedAt && (interval.endedAt === undefined || at <= interval.endedAt));
+    if (matches.length !== 1) return { attribution: { attribution: "unattributed" } };
+    const turn = matches[0]!;
+    return { attribution: { ...turn.attribution }, turn: turn.id };
+  }
+
   private unknown(peer: string, bound: Bound, reason: KimiWireReason): void {
     bound.unknown = reason;
     try { this.ports.forget(peer); } catch { /* the reading ages out on its own */ }

package/src/hub/lifecycle.ts

@@ -1,8 +1,9 @@
+import { waitForStartupReadiness, type StartupOwner } from "./startup-readiness.ts";
 import { resolveProjectRuntime, recordProjectRuntime, confirmProjectRuntime, readProjectRuntimeForCaller, projectRuntimeRefusal, type ProjectRuntimeSelection } from "./project-runtime.ts";
 import { scheduleRuntimeCapturePrune } from "./runtime-capture-prune.ts";
 import { createProjectRuntimeAccess, type ProjectRuntimeAccess } from "./project-runtime-state.ts";
 import { isDatabaseBusyReply, RecoveryDatabaseBusy } from "./recovery-error.ts";
-import { spawn } from "node:child_process";
+import { spawn, type ChildProcess } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
@@ -176,7 +177,7 @@ export async function runProjectDaemon(project: Project, unattended = false): Pr
   }
 }
 
-export async function startProject(project: Project, options: { unattended?: boolean; env?: NodeJS.ProcessEnv; liveTest?: boolean; current?: () => void } = {}): Promise<any> {
+export async function startProject(project: Project, options: { unattended?: boolean; env?: NodeJS.ProcessEnv; liveTest?: boolean; current?: () => void; starting?: (pid: number) => void } = {}): Promise<any> {
   options.current?.();
   assertLifecycleAvailable(project.root);
   const registry = new Registry();
@@ -195,6 +196,7 @@ export async function startProject(project: Project, options: { unattended?: boo
     if (before.state !== "stopped" && before.state !== "starting") throw new Error(before.error ?? before.state);
     if (!existsSync(join(project.root, ".agenthub", "config.json"))) throw new Error("project is not initialized; run ahub init there first");
     let launchedRuntime: ProjectRuntimeSelection | undefined;
+    let startupChild: ChildProcess | undefined, startupSignature: string | undefined, launchFailed = false;
     if (before.state === "stopped") {
       const launchEnv = { ...(options.env ?? process.env) };
       // Expired operation ids must not make an ordinary startup load a retired snapshot.
@@ -225,26 +227,40 @@ export async function startProject(project: Project, options: { unattended?: boo
             env: { ...launchEnv, AGENTHUB_STATE_DIR: project.stateDir, AGENTHUB_PROJECT_DIR: project.root,
               AGENTHUB_UNATTENDED: options.unattended ? "1" : "0" },
           });
-          child.on("error", () => {}); // bounded readiness below reports failure with the project's log path
+          startupChild = child;
+          child.on("error", () => { launchFailed = true; }); // The bound child is observed by the readiness wait, never stopped on timeout.
           child.unref();
         } finally { closeSync(log); }
       });
     }
-    const deadline = Date.now() + 12_000;
-    while (Date.now() < deadline) {
-      const observed = await inspectProject(registry.get(project.id) ?? project);
-      options.current?.();
-      if (observed.state === "running") {
+    const startupOwner = (): StartupOwner => {
+      if (!startupChild) return undefined; // A competing starter owns this claim; join without claiming its child.
+      const claim = registry.get(project.id);
+      if (!claim || claim.root !== project.root || claim.stateDir !== project.stateDir) throw new Error("project registration changed; refresh before starting");
+      const claimed = claim.instanceId !== null;
+      if (claimed && claim.pid !== startupChild.pid) return undefined;
+      if (launchFailed || startupChild.exitCode !== null || startupChild.signalCode !== null || startupChild.pid === undefined) return { state: "gone" };
+      // A still-unreaped owned child cannot have its PID reused. Capture the full identity once it is observable.
+      startupSignature ??= processSignature(startupChild.pid);
+      if (!startupSignature || claimed && claim.pidSignature !== startupSignature) return { state: "unknown" };
+      const state = processLiveness(startupChild.pid, startupSignature);
+      const fresh = registry.get(project.id);
+      if (!fresh || fresh.root !== project.root || fresh.stateDir !== project.stateDir || fresh.instanceId !== claim.instanceId || fresh.pid !== claim.pid || fresh.pidSignature !== claim.pidSignature) return undefined;
+      if (startupChild.exitCode !== null || startupChild.signalCode !== null || state === "gone") return { state: "gone" };
+      return state === "live" ? { state: "live", pid: startupChild.pid } : { state: "unknown" };
+    };
+    return await waitForStartupReadiness<any>({
+      now: () => performance.now(), sleep: ms => Bun.sleep(ms), current: () => { options.current?.(); }, owner: startupOwner,
+      inspect: timeoutMs => inspectProject(registry.get(project.id) ?? project, timeoutMs),
+      starting: options.starting,
+      confirm: status => {
+        options.current?.();
         admitRunningRuntime();
-        if (launchedRuntime) confirmProjectRuntime(project, launchedRuntime, observed.status, registry, runtimeAccess);
+        if (launchedRuntime) confirmProjectRuntime(project, launchedRuntime, status, registry, runtimeAccess);
         // Unknown references defer maintenance; cache cleanup never changes a confirmed startup outcome.
         try { scheduleRuntimeCapturePrune(); } catch { /* retain captures on unreadable inventory or cleanup failure */ }
-        return observed.status;
-      }
-      if (observed.state === "incompatible" || observed.state === "missing") throw new Error(observed.error ?? observed.state);
-      await Bun.sleep(100);
-    }
-    throw new Error(`hub readiness not confirmed; inspect ${join(project.stateDir, "hub.log")} before retrying`);
+      },
+    });
   } finally { registry.close(); }
 }
 

package/src/hub/limits.ts

@@ -39,6 +39,15 @@ export class Limiter {
    * answers: "Yes." to two different questions is two messages, not a repeat.
    */
   admit(from: PeerId, to: PeerId[] | undefined, priority: Priority, body: string, parent = "", group?: string): string | undefined {
+    return this.decide(true, from, to, priority, body, parent, group);
+  }
+
+  /** Same decision without spending buckets, recording repeat keys, or pruning history. */
+  peek(from: PeerId, to: PeerId[] | undefined, priority: Priority, body: string, parent = "", group?: string): string | undefined {
+    return this.decide(false, from, to, priority, body, parent, group);
+  }
+
+  private decide(consume: boolean, from: PeerId, to: PeerId[] | undefined, priority: Priority, body: string, parent: string, group?: string): string | undefined {
     const now = this.now();
     const audience = to?.length ? [...new Set(to)].sort() : ["*"];
     const key = `${from}\0${audience.join(",")}\0${parent}\0${body.trim().replace(/\s+/g, " ")}`;
@@ -48,8 +57,8 @@ export class Limiter {
       if (last !== undefined && now - last < this.cfg.repeat_window_s * 1000) {
         return `the same message went to ${to?.length ? audience.join(", ") : "everyone"} ${Math.round((now - last) / 1000)} s ago`;
       }
-      for (const key of keys) this.recent.set(key, now);
-      if (this.recent.size > 1000) for (const [k, at] of this.recent) if (now - at >= this.cfg.repeat_window_s * 1000) this.recent.delete(k);
+      if (consume) for (const key of keys) this.recent.set(key, now);
+      if (consume && this.recent.size > 1000) for (const [k, at] of this.recent) if (now - at >= this.cfg.repeat_window_s * 1000) this.recent.delete(k);
     }
     const wanted: [string, number, number][] = []; // key, capacity, refill per ms
     if (this.cfg.sender_per_min > 0) wanted.push([`s\0${from}`, this.cfg.sender_per_min, this.cfg.sender_per_min / 60_000]);
@@ -68,11 +77,11 @@ export class Limiter {
     const short = filled.filter((f) => f.b.tokens < 1);
     if (short.length) {
       const wait = Math.max(...short.map((f) => Math.ceil(Math.round((1 - f.b.tokens) / f.rate) / 1000))); // whole ms first: 1/(1/x) is not always x
-      if (this.cfg.repeat_window_s > 0) for (const key of keys) this.recent.delete(key); // refused, so not sent
+      if (consume && this.cfg.repeat_window_s > 0) for (const key of keys) this.recent.delete(key); // refused, so not sent
       const what = short.some((f) => f.key.startsWith("i\0") || f.key.startsWith("gi\0")) ? "important messages" : "messages";
       return `rate limited: too many ${what} from ${from}; retry after ${wait} s${what === "important messages" ? ", or send it without [IMPORTANT]" : ""}`;
     }
-    for (const f of filled) this.buckets.set(f.key, { tokens: f.b.tokens - 1, at: now });
+    if (consume) for (const f of filled) this.buckets.set(f.key, { tokens: f.b.tokens - 1, at: now });
     return undefined;
   }
 }

package/src/hub/manager.ts

@@ -132,7 +132,8 @@ export function projectConsole(options: { registry: Registry; lifecycle: Lifecyc
       // #1057: the worktree shelf's person actions. The refresh is the one that reads GitHub, so it gets the delivery reads' deadline in its own branch below.
       const worktreeAction = ["worktree_override_set", "worktree_override_clear", "worktrees_refresh_prs"].includes(String(input.action));
       // The settings actions (#269) reach the project hub as an ordinary session's: this dashboard opens no settings session.
-      if (!["snapshot", "send", "pause", "resume", "permit", "propose", "intake", "assign", "backlog_pull", "backlog_return", "planning", "planning_undo", "planner_pull", "backlog_split", "release_new", "release_change", "setting", "setting_undo", "setting_preview", "setting_reload", "config_edit_preview", "config_edit_apply", "start_peer", "sdlc_queue", "sdlc_release", "result_seen", "results_read_all", "results_unread_last"].includes(String(input.action)) && !worktreeAction) return { ok: false, error: "invalid dashboard action" };
+      if (!["snapshot", "send", "pause", "resume", "permit", "propose", "intake", "assign", "backlog_pull", "backlog_return", "planning", "planning_undo", "planner_pull", "backlog_split", "release_new", "release_change", "setting", "setting_undo", "setting_preview", "setting_reload", "model_preview", "model_confirm", "config_edit_preview", "config_edit_apply", "start_peer", "sdlc_queue", "sdlc_release", "result_seen", "results_read_all", "results_unread_last"].includes(String(input.action)) && !worktreeAction) return { ok: false, error: "invalid dashboard action" };
+      const visualSelector = input.action === "snapshot" ? visualSnapshotSelector(input) : {};
       client = await ControlClient.connect(project.stateDir, { role: "console", projectId: project.id, projectRoot: project.root, instanceId: input.instanceId });
       const deliveryRead = input.action === "sdlc_queue" || input.action === "sdlc_release";
       let nominalMs = 10_000;
@@ -143,7 +144,7 @@ export function projectConsole(options: { registry: Registry; lifecycle: Lifecyc
       else if (input.action === "worktrees_refresh_prs") nominalMs = 40_000; // up to 25 s of bounded gh reads plus two git passes
       const timeoutMs = options.forwardTimeoutMs?.(String(input.action), nominalMs) ?? nominalMs;
       const result = await client.request(input.action === "snapshot"
-        ? { t: "ui_snapshot", after: input.after ?? 0, ...(input.reviewRefresh === true && input.reviewTask !== undefined ? { reviewTask: input.reviewTask, reviewRefresh: true } : {}), ...(input.memory !== undefined ? { memory: input.memory } : {}), ...(dashboardView(input.view) ? { view: input.view } : {}) }
+        ? { t: "ui_snapshot", after: input.after ?? 0, ...visualSelector, ...(input.reviewRefresh === true && input.reviewTask !== undefined ? { reviewTask: input.reviewTask, reviewRefresh: true } : {}), ...(input.memory !== undefined ? { memory: input.memory } : {}), ...(dashboardView(input.view) ? { view: input.view } : {}) }
         : { t: "ui_action", action: input, instanceId: input.instanceId }, timeoutMs);
       // ControlClient resolves its deadline as this exact sentinel; a hub refusal stays a known failure.
       if (input.action === "intake" && result.ok === false && result.error === `no answer from the hub within ${Math.round(timeoutMs / 1000)} s`) {
@@ -379,3 +380,15 @@ export async function stopManager(options: ManagerOptions = {}): Promise<void> {
   }
   throw new Error("manager shutdown is still pending; project hubs were not changed");
 }
+
+/** Closed read selectors only; no caller path, policy or arbitrary control fields are forwarded. */
+export function visualSnapshotSelector(input: Record<string, unknown>): Record<string, string | number> {
+  const keys = ["visual", "visualTask", "visualAsset"].filter(key => Object.hasOwn(input, key));
+  if (!keys.length) return {};
+  if (keys.length !== 1) throw new Error("visual selector is ambiguous; select one visual or task and retry");
+  const key = keys[0]!, value = input[key];
+  const id = "[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}";
+  if (key === "visualTask" ? Number.isSafeInteger(value) && Number(value) > 0
+    : typeof value === "string" && new RegExp(key === "visualAsset" ? `^${id}:(before|after)$` : `^${id}$`).test(value)) return { [key]: value as string | number };
+  throw new Error("visual selector is invalid; select a current visual or task and retry");
+}

package/src/hub/memory-policy.ts

@@ -65,9 +65,10 @@ export function isTrustedReviewPackage(env: Envelope): boolean {
     && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(env.refs.reviewPackage);
 }
 
-/** Only structured review carriers are excluded; ordinary review tool capture stays unchanged. */
+/** Structured review and visual tool bodies never enter observer capture, including refused inputs. */
 export function reviewCaptureExcluded(tool: string, args: string): boolean {
   const name = tool.replace(/^mcp__[^ ]+__/, "");
+  if (name === "hub_visual" || name === "hub_visual_show") return true;
   if (["review_comment_put", "review_comment_delete", "review_comment_send", "review_blob"].includes(name)) return true;
   if (name !== "hub_review") return false;
   try {

package/src/hub/memory-sync-attestation.ts

@@ -0,0 +1,54 @@
+import { types } from "node:util";
+import { createPlacementAttestation, PlacementWriterContextError, type SyncOptions } from "@staix/agent-mem";
+
+/** The closed vocabulary of `PlacementWriterContextError.category` and `.causeClass` (agent-mem 0.23.0). Anything else projects as unknown. */
+const CATEGORIES = ["running CLI", "host package", "setup receipt", "declared writer", "active locator", "home floor", "writer renewal", "unknown"] as const;
+const CAUSE_CLASSES = ["missing", "changed", "unavailable"] as const;
+export type WriterRefusalCategory = typeof CATEGORIES[number];
+export type WriterRefusalCause = typeof CAUSE_CLASSES[number];
+/** Public-safe projection of a writer-context refusal: two closed words, never the package's message, a path or a version. */
+export interface WriterRefusal { category: WriterRefusalCategory; causeClass: WriterRefusalCause }
+
+/** Reads a refusal without trusting its prototype chain or getters, and without keeping its message. */
+export function writerRefusalOf(error: unknown): WriterRefusal | undefined {
+  if (!error || typeof error !== "object" || types.isProxy(error)) return undefined;
+  // The SDK throws this concrete class. Exact prototype identity avoids walking an arbitrary prototype chain.
+  if (Object.getPrototypeOf(error) !== PlacementWriterContextError.prototype) return undefined;
+  const category = Object.getOwnPropertyDescriptor(error, "category")?.value, causeClass = Object.getOwnPropertyDescriptor(error, "causeClass")?.value;
+  return {
+    category: (CATEGORIES as readonly unknown[]).includes(category) ? category as WriterRefusalCategory : "unknown",
+    causeClass: (CAUSE_CLASSES as readonly unknown[]).includes(causeClass) ? causeClass as WriterRefusalCause : "unavailable",
+  };
+}
+
+/** Legacy quiet classification reads only an ordinary error's own string, never a getter or proxy. */
+export function memorySyncErrorText(error: unknown): string | undefined {
+  if (typeof error === "string") return error;
+  if (!error || typeof error !== "object" || types.isProxy(error) || !types.isNativeError(error)) return undefined;
+  const descriptor = Object.getOwnPropertyDescriptor(error, "message");
+  return descriptor && "value" in descriptor && typeof descriptor.value === "string" ? descriptor.value : undefined;
+}
+
+/**
+ * The attestation the hub hands one `syncMemory` pass (#1173). It is agent-mem's own `createPlacementAttestation`, bound to this
+ * installation and this memory home; the hub supplies no writer facts of its own and never caches a result past the pass.
+ * The transport turns any thrown refusal into a generic "unavailable" result, so the wrapper keeps the first typed refusal for the
+ * caller to project; the error is rethrown unchanged so the transport still fails closed.
+ */
+export function hostPlacementAttestation(home: string, create: typeof createPlacementAttestation = createPlacementAttestation): {
+  attest: NonNullable<SyncOptions["placementAttestation"]>;
+  refusal: () => WriterRefusal | undefined;
+} {
+  let inner: ReturnType<typeof createPlacementAttestation> | undefined;
+  let refused: WriterRefusal | undefined;
+  const attest: NonNullable<SyncOptions["placementAttestation"]> = () => {
+    try {
+      inner ??= create(home);
+      return inner();
+    } catch (error) {
+      refused ??= writerRefusalOf(error);
+      throw error;
+    }
+  };
+  return { attest, refusal: () => refused };
+}

package/src/hub/memory-sync-state.ts

@@ -1,14 +1,19 @@
 import { createHash } from "node:crypto";
 
 /** Safe, process-local view of the most recent machine memory sync. */
-export type MemorySyncCause = "declined" | "remote" | "binding" | "stopped" | "transport" | "unknown";
+export type MemorySyncCause = "declined" | "remote" | "binding" | "stopped" | "transport" | "writer" | "unknown";
+/** Closed words of a refused writer attestation (agent-mem `PlacementWriterContextError`); never its message, a path or a version. */
+export interface MemorySyncWriterRefusal { writerCategory?: string; writerCauseClass?: string }
+export const WRITER_CATEGORIES: readonly string[] = ["running CLI", "host package", "setup receipt", "declared writer", "active locator", "home floor", "writer renewal", "unknown"];
+export const WRITER_CAUSE_CLASSES: readonly string[] = ["missing", "changed", "unavailable"];
+const closedWriter = (value: unknown, allowed: readonly string[]): string | undefined => typeof value === "string" && allowed.includes(value) ? value : undefined;
 export interface MemorySyncPlacementCounts { withheldCount: number; exportedCount: number }
 export type MemorySyncOutcome =
   | { state: "notrun" }
   | { state: "not-configured"; at: number }
   | { state: "stopped"; at: number }
   | { state: "ok"; at: number; withheldCount?: number; exportedCount?: number }
-  | { state: "failed"; at: number; cause: MemorySyncCause; declinedCount?: number; declinedIdsKnown?: false; placementActive?: false };
+  | { state: "failed"; at: number; cause: MemorySyncCause; declinedCount?: number; declinedIdsKnown?: false; placementActive?: false } & MemorySyncWriterRefusal;
 
 export interface MemorySyncState {
   outcome: MemorySyncOutcome;
@@ -19,7 +24,7 @@ export interface MemorySyncState {
 export type MemorySyncEvent =
   | { type: "success"; at: number; withheldCount?: number; exportedCount?: number }
   | { type: "quiet"; at: number; state: "not-configured" | "stopped" }
-  | { type: "failure"; at: number; cause: MemorySyncCause; declinedCount?: number; declinedIdsFingerprint?: string; declinedIdsKnown?: false; failureDetailHash?: string; placementActive?: false };
+  | { type: "failure"; at: number; cause: MemorySyncCause; declinedCount?: number; declinedIdsFingerprint?: string; declinedIdsKnown?: false; failureDetailHash?: string; placementActive?: false } & MemorySyncWriterRefusal;
 
 export const initialMemorySyncState = (): MemorySyncState => ({ outcome: { state: "notrun" } });
 const MAX_DECLINED_ROWS = 20_000;
@@ -50,14 +55,20 @@ export function memorySyncPlacementCounts(value: unknown): MemorySyncPlacementCo
 export function reduceMemorySync(state: MemorySyncState, event: MemorySyncEvent): { state: MemorySyncState; logFailure: boolean } {
   if (event.type === "success") return { state: { outcome: { state: "ok", at: event.at, ...placementCounts(event.withheldCount, event.exportedCount) } }, logFailure: false };
   if (event.type === "quiet") return { state: { outcome: { state: event.state, at: event.at } }, logFailure: false };
-  const signature = [event.cause, event.declinedCount ?? "", event.declinedIdsFingerprint ?? (event.declinedIdsKnown === false ? "ids-unknown" : ""), event.failureDetailHash ?? ""].join("\0");
+  const signature = [event.cause, event.declinedCount ?? "", event.declinedIdsFingerprint ?? (event.declinedIdsKnown === false ? "ids-unknown" : ""), event.failureDetailHash ?? "", event.cause === "writer" ? closedWriter(event.writerCategory, WRITER_CATEGORIES) ?? "" : "", event.cause === "writer" ? closedWriter(event.writerCauseClass, WRITER_CAUSE_CLASSES) ?? "" : ""].join("\0");
   const changed = state.failureSignature !== signature;
   return {
-    state: { outcome: { state: "failed", at: event.at, cause: event.cause, ...(event.declinedCount === undefined ? {} : { declinedCount: event.declinedCount }), ...(event.declinedIdsKnown === false ? { declinedIdsKnown: false as const } : {}), ...(event.cause === "declined" && event.placementActive === false ? { placementActive: false as const } : {}) }, failureSignature: signature },
+    state: { outcome: { state: "failed", at: event.at, cause: event.cause, ...(event.declinedCount === undefined ? {} : { declinedCount: event.declinedCount }), ...(event.declinedIdsKnown === false ? { declinedIdsKnown: false as const } : {}), ...(event.cause === "declined" && event.placementActive === false ? { placementActive: false as const } : {}), ...writerFields(event) }, failureSignature: signature },
     logFailure: changed,
   };
 }
 
+function writerFields(value: { cause?: string } & MemorySyncWriterRefusal): MemorySyncWriterRefusal {
+  if (value.cause !== "writer") return {};
+  const writerCategory = closedWriter(value.writerCategory, WRITER_CATEGORIES), writerCauseClass = closedWriter(value.writerCauseClass, WRITER_CAUSE_CLASSES);
+  return { ...(writerCategory ? { writerCategory } : {}), ...(writerCauseClass ? { writerCauseClass } : {}) };
+}
+
 export interface MemorySyncView {
   state: "disabled" | "unavailable" | "notrun" | "not-configured" | "stopped" | "ok" | "failed" | "unknown";
   at?: number;
@@ -67,6 +78,8 @@ export interface MemorySyncView {
   withheldCount?: number;
   exportedCount?: number;
   placementActive?: false;
+  writerCategory?: string;
+  writerCauseClass?: string;
   nextStep?: string;
 }
 
@@ -75,6 +88,7 @@ export function memorySyncNextStep(cause: MemorySyncCause): string {
     : cause === "remote" ? "configure a private sync remote"
     : cause === "binding" ? "ahub memory profile-check"
     : cause === "stopped" ? "retry after hub restart"
+    : cause === "writer" ? "repair the amem install and its host pin, then a person runs amem migrate --sync-placement --dry-run"
     : "run ahub memory sync as a person";
 }
 
@@ -91,6 +105,7 @@ export function memorySyncView(state: MemorySyncState, availability: "enabled" |
     ...(outcome.declinedCount === undefined ? {} : { declinedCount: outcome.declinedCount }),
     ...(outcome.declinedIdsKnown === false ? { declinedIdsKnown: false } : {}),
     ...(outcome.cause === "declined" && outcome.placementActive === false ? { placementActive: false } : {}),
+    ...writerFields(outcome),
     nextStep: memorySyncNextStep(outcome.cause),
   };
 }