@staix/agent-hub 0.12.28 → 0.12.30

package/src/hub/events.ts

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

package/src/hub/git.ts

@@ -1,38 +1,2 @@
-import { spawnSync, type SpawnSyncOptionsWithStringEncoding, type SpawnSyncReturns } from "node:child_process";
-
-/**
- * The one helper for every git call the hub makes outside the sandbox (#281): the repository's own configuration
- * must not name a program the hub then runs with its own rights (defense in depth behind the seatbelt profile,
- * which refuses a sandboxed command the writes that would plant one). Every call gets:
- * - core.fsmonitor=false: the file-system monitor is an arbitrary command read from the repo config.
- * - core.hooksPath=/dev/null: hooks come from a non-directory, so every hook lookup fails closed.
- * - diff.external= (empty): no external diff driver.
- * - core.pager=cat and --no-pager: no pager, whatever the config says (stdout is a pipe everywhere anyway).
- * - credential.helper= (empty resets the list) and core.askpass= (empty fails closed), with GIT_TERMINAL_PROMPT=0:
- *   no hub command authenticates, so any prompt is a bug and must fail instead of running a configured helper.
- * git has no global switch for filter drivers or textconv: both are per-driver config keys. Of the hub's commands
- * only the snapshot's `add`/`restore` would run a filter driver, and only a content diff would run textconv — the
- * hub's one content diff is `diff --no-index`, which DOES read the repository's config (verified: a planted
- * diff.external runs for it), so that call passes `--no-ext-diff` and `--no-textconv` on top of the config here,
- * and the driver command of a filter lives in the `.git/config` the seatbelt profile refuses to a sandboxed
- * command. GIT_CONFIG_NOSYSTEM/global are left alone: those files are the user's own.
- */
-const SAFE_CONFIG = ["core.fsmonitor=false", "core.hooksPath=/dev/null", "diff.external=", "core.pager=cat", "credential.helper=", "core.askpass="];
-/** Hub memory sync (#258) pushes to the person's own remote: their global credential helper stays, the rest does not. */
-const CREDENTIAL_KEYS = new Set(["credential.helper=", "core.askpass="]);
-
-/**
- * `["git", ...safe options, ...args]`: use instead of a literal "git" argv anywhere under src/. `credentials` keeps the
- * person's credential helper, for a repository the hub created itself (the memory store), never a project's.
- */
-export const hubGitArgv = (args: string[], opts: { credentials?: boolean } = {}): string[] =>
-  ["git", "--no-pager", ...SAFE_CONFIG.filter((c) => !opts.credentials || !CREDENTIAL_KEYS.has(c)).flatMap((c) => ["-c", c]), ...args];
-
-/** The caller's env plus the no-prompt switch; existing keys (childEnv, GIT_OPTIONAL_LOCKS=0) pass through. */
-export const hubGitEnv = (env: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv => ({ ...env, GIT_TERMINAL_PROMPT: "0" });
-
-/** spawnSync form of the same call: the env option is merged with hubGitEnv, everything else passes through. */
-export function hubGitSync(args: string[], options: SpawnSyncOptionsWithStringEncoding): SpawnSyncReturns<string> {
-  const argv = hubGitArgv(args);
-  return spawnSync(argv[0]!, argv.slice(1), { ...options, env: hubGitEnv(options.env ?? process.env) });
-}
+// The portable core owns hardened git invocation; retain the hub names as identical exports.
+export { memoryGitArgv as hubGitArgv, memoryGitEnv as hubGitEnv, memoryGitSync as hubGitSync } from "@staix/agent-mem/platform";

package/src/hub/hub-tools.ts

@@ -57,7 +57,11 @@ export const TASK_TOOLS: HubTool[] = [
   tool("hub_task_list", "The task board. PII tasks show as [pii].", { state: { type: "string", enum: ["proposed", "in_progress", "in_review", "approved", "changes_requested"] }, ready: { type: "boolean", description: "only proposed tasks with nothing left to wait for" } }),
   tool("hub_review", "Give your verdict on a task you were asked to review: map the changed signatures and call sites to the task's plan or detail, read the check result (hub_task_show has it, with the done summary), and list what is unmet. Two changes_requested in a row move the task to another peer.", { id, head: { type: "string", description: "full SHA actually reviewed; enforce binds approval to the current PR head" }, verdict: { type: "string", enum: ["approved", "changes_requested"] }, note: str, unmet: { type: "array", items: str, description: "each requirement of the plan or detail that the change does not meet" } }, ["id", "verdict"]),
   tool("hub_checkpoint", "Answer a checkpoint request from the hub (quota or context window pressure): what you were doing, what is half done, what whoever continues must know. Write the same to .agenthub/checkpoint.md first if you can.", { summary: str, request_id: { type: "string", description: "The request id supplied by a context checkpoint request; required for context checkpoints" } }, ["summary"]),
-  tool("hub_remember", "Save a decision, finding, contract or fail to the memory all agents share (the hub's memory and claude-mem); the other agents also get it with their next message. A fail is an approach you tried that does not work, and why: the most useful note, it stops the others spending their quota on it. Do not retry what a fail note rules out without new evidence. Conclusions worth recalling, not chatter. A note on an open task is short-term until the task is approved, when its decisions, contracts and fails become long-term; horizon long keeps it now, scope shared lets the person's other projects find it.", { text: str, title: str, kind: { type: "string", enum: [...NOTE_KINDS] }, task: id, horizon: { type: "string", enum: ["short", "long"] }, scope: { type: "string", enum: ["project", "shared"] } }, ["text"]),
+  tool("hub_memory_search", "Search daemon-scoped visible memory, fails first. Query <=200 UTF-8 bytes; default 8, max 20 lines; whole output <=4 KB. Incomplete excerpts are marked. No project argument.", { query: { type: "string", maxLength: 200, description: "At most 200 UTF-8 bytes, enforced by the daemon" }, limit: { type: "integer", minimum: 1, maximum: 20 } }, ["query"]),
+  tool("hub_memory_show", "Read up to 8 visible memory ids or unique prefixes (6..64 UTF-8 bytes each). Original ids redirect; unavailable ids share one refusal. Whole output <=8 KB.", { ids: { type: "array", minItems: 1, maxItems: 8, items: { type: "string", minLength: 6, maxLength: 64, description: "6 to 64 UTF-8 bytes" } } }, ["ids"]),
+  tool("hub_memory_graph", "Read screened memory neighbourhoods, fails first. Up to 8 starts (<=200 UTF-8 bytes each), 1 or 2 hops; default 60/max 120 nodes, max 240 edges, whole output <=6 KB. No project argument.", { starts: { type: "array", minItems: 1, maxItems: 8, items: { type: "string", minLength: 1, maxLength: 200, description: "At most 200 UTF-8 bytes" } }, hops: { type: "integer", enum: [1, 2] }, limit: { type: "integer", minimum: 1, maximum: 120 } }, ["starts"]),
+  tool("hub_memory_correct", "Propose a correction to a visible memory entry. This creates a machine-local candidate only; a person accepts or rejects it with amem review. It never edits a note. id is an exact id or unique visible prefix; text and reason must each fit 4000 UTF-8 bytes.", { id: str, text: str, reason: str }, ["id", "text", "reason"]),
+  tool("hub_remember", "Save a decision, finding, contract or fail to the memory all agents share (the hub's memory and claude-mem); the other agents also get it with their next message. A fail is an approach you tried that does not work, and why: the most useful note, it stops the others spending their quota on it. Do not retry what a fail note rules out without new evidence. Conclusions worth recalling, not chatter. For kind fail, optional approach, symptom, cause, evidence and retry_when strings compose fixed labeled text; text may be omitted when structured fields are supplied. The complete text must fit 4000 UTF-8 bytes and is refused, never truncated, when oversized. A note on an open task is short-term until the task is approved, when its decisions, contracts and fails become long-term; horizon long keeps it now, scope shared lets the person's other projects find it.", { text: str, approach: str, symptom: str, cause: str, evidence: str, retry_when: str, title: str, kind: { type: "string", enum: [...NOTE_KINDS] }, task: id, horizon: { type: "string", enum: ["short", "long"] }, scope: { type: "string", enum: ["project", "shared"] } }),
 ];
 
 export const TASK_TOOL_NAMES = new Set(TASK_TOOLS.map((t) => t.name));

package/src/hub/lifecycle.ts

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

package/src/hub/manager.ts

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

package/src/hub/memory-candidates.ts

@@ -0,0 +1,103 @@
+import { looksSecret, type CandidateStore, type CounterKey, type MemoryStore, type View } from "@staix/agent-mem";
+import type { MemoryScreen } from "./read-tools.ts";
+import { PreEffectToolRefusal } from "./tool-refusal.ts";
+
+const bytes = (text: string) => Buffer.byteLength(text, "utf8");
+const refuse = (): never => { throw new PreEffectToolRefusal("memory read unavailable"); };
+export interface CorrectionInput { id: string; text: string; reason: string }
+
+/** Validate model input before resolving a memory id or opening the candidate sidecar. */
+export function correctionInput(args: unknown): CorrectionInput {
+  if (!args || typeof args !== "object" || Array.isArray(args)) refuse();
+  const input = args as Record<string, unknown>;
+  const string = (value: unknown, min: number, max: number): value is string => typeof value === "string" && value.trim().length > 0 && !value.includes("\0") && bytes(value) >= min && bytes(value) <= max;
+  if (Object.keys(input).some(key => !["id", "text", "reason"].includes(key)) || !string(input.id, 6, 64) || !string(input.text, 1, 4000) || !string(input.reason, 1, 4000)) refuse();
+  const result = { id: input.id, text: input.text, reason: input.reason } as CorrectionInput;
+  if (bytes(JSON.stringify(result)) > 8192) refuse();
+  return result;
+}
+
+function safe(value: unknown, screen: MemoryScreen): boolean {
+  try {
+    const text = typeof value === "string" ? value : JSON.stringify(value);
+    return !looksSecret(text) && screen([{ title: null, text }]).length === 1;
+  } catch { return false; }
+}
+
+function visibleId(input: string, screen: MemoryScreen): string {
+  if (typeof input !== "string" || bytes(input) < 6 || bytes(input) > 64 || !safe(input, screen)) refuse();
+  const id = input.replace(/^mem:/, "");
+  if (id.length < 6) refuse();
+  return id;
+}
+
+/** One screened projection per operation; never retained across calls or revisions. */
+function visibleResolver(store: MemoryStore, project: string, screen: MemoryScreen): (id: string) => View {
+  const all = screen(store.list({ project, limit: Number.MAX_SAFE_INTEGER, includeSuperseded: true })).filter(view => safe(view, screen));
+  const byId = new Map(all.map(view => [view.id, view]));
+  const promoted = new Map<string, View[]>();
+  for (const view of all) if (view.promotedFrom) {
+    const group = promoted.get(view.promotedFrom) ?? [];
+    group.push(view); promoted.set(view.promotedFrom, group);
+  }
+  const aliases = [...new Set([...byId.keys(), ...promoted.keys()])], exactAliases = new Set(aliases);
+  return id => {
+    const matched = exactAliases.has(id) ? [id] : aliases.filter(alias => alias.startsWith(id));
+    let found: View | undefined;
+    if (matched.length === 1) {
+      found = byId.get(matched[0]!);
+      if (!found) {
+        const copies = promoted.get(matched[0]!) ?? [];
+        if (copies.length === 1) found = copies[0];
+      }
+    } else if (matched.length === 0) {
+      // Older promotion chains need the core's redirect, but may terminate only in this screened snapshot.
+      const redirected = store.get(id, project);
+      found = redirected && byId.get(redirected.id);
+    }
+    if (!found || found.supersededBy) return refuse();
+    return found;
+  };
+}
+
+/** Resolve only screened visible ids and aliases; unavailable and ambiguous inputs have the same refusal. */
+export function resolveVisibleMemory(store: MemoryStore, project: string, screen: MemoryScreen, input: string): View {
+  const id = visibleId(input, screen); // Input rejection precedes any storage work.
+  try { return store.withDeferredPromotions(() => visibleResolver(store, project, screen)(id)); }
+  catch { return refuse(); }
+}
+
+export type MemoryCounterContext = Omit<CounterKey, "entryId" | "project">;
+export type MemoryCounterField = "rendered" | "delivered" | "cited";
+
+/** Sidecar-only observations: the absent fields stay unknown; no message body is persisted. */
+export class MemoryTelemetry {
+  constructor(private readonly sidecar: CandidateStore, private readonly store: MemoryStore, private readonly project: string, private readonly screen: MemoryScreen, private readonly memoryCheck?: () => void) {}
+
+  record(text: string, context: MemoryCounterContext, field: MemoryCounterField, privateTurn = false): void {
+    if (privateTurn || !["rendered", "delivered", "cited"].includes(field)) return;
+    try {
+      this.memoryCheck?.();
+      if (!safe(context, this.screen)) return;
+      const ids = new Set<string>();
+      for (const match of text.matchAll(/\bmem:([a-f0-9]{8,64})(?![a-zA-Z0-9])/g)) {
+        try { ids.add(visibleId(match[1]!, this.screen)); } catch { /* unavailable input */ }
+      }
+      if (!ids.size) return;
+      this.memoryCheck?.();
+      this.store.withDeferredPromotions(() => {
+        const resolve = visibleResolver(this.store, this.project, this.screen), seen = new Set<string>();
+        for (const id of ids) {
+          try {
+            this.memoryCheck?.();
+            const view = resolve(id);
+            if (seen.has(view.id)) continue;
+            seen.add(view.id);
+            this.memoryCheck?.();
+            this.sidecar.recordCounter({ ...context, project: this.project, entryId: view.id }, { [field]: 1 }, "public");
+          } catch { /* A hidden, ambiguous or unavailable citation reveals no counters or diagnostics. */ }
+        }
+      });
+    } catch { /* Sidecar telemetry never blocks a delivery or an answer. */ }
+  }
+}

package/src/hub/memory-fail.ts

@@ -0,0 +1,25 @@
+export const REMEMBER_TEXT_MAX_BYTES = 4000;
+const FAIL_FIELDS = [
+  ["approach", "Approach"], ["symptom", "Symptom"], ["cause", "Cause"], ["evidence", "Evidence"], ["retry_when", "Retry when"],
+] as const;
+
+/** Compose ordinary v1 text only. Validation precedes policy screening, storage and display caps. */
+export function composeRememberText(input: unknown): string {
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("memory note must be an object");
+  const note = input as Record<string, unknown>;
+  if (note.text !== undefined && typeof note.text !== "string") throw new Error("text must be a string");
+  const text = typeof note.text === "string" ? note.text.trim() : "";
+  const fields: string[] = [];
+  for (const [name, label] of FAIL_FIELDS) {
+    const value = note[name];
+    if (value === undefined) continue;
+    if (note.kind !== "fail") throw new Error(`${name} is only available for kind fail`);
+    if (typeof value !== "string" || !value.trim()) throw new Error(`${name} must be a nonempty string`);
+    fields.push(`${label}: ${value.trim()}`);
+  }
+  if (!text && !fields.length) throw new Error("text is required, or supply structured fields with kind fail");
+  const result = text && fields.length ? `${text}\n\n${fields.join("\n")}` : text || fields.join("\n");
+  const bytes = Buffer.byteLength(result, "utf8");
+  if (bytes > REMEMBER_TEXT_MAX_BYTES) throw new Error(`memory text is ${bytes} UTF-8 bytes; maximum is ${REMEMBER_TEXT_MAX_BYTES} bytes (refused without truncation)`);
+  return result;
+}

package/src/hub/memory-observations.ts

@@ -0,0 +1,47 @@
+import type { Envelope, PeerId } from "./envelope.ts";
+import { HUB } from "./envelope.ts";
+import type { MemoryCounterContext, MemoryTelemetry } from "./memory-candidates.ts";
+
+export type MemoryObservationContext = Omit<MemoryCounterContext, "deliveryId">;
+/** Only positively public context is returned. Missing identity fields remain unknown. */
+export type MemoryContext = (peer: PeerId, envelopes: readonly Envelope[]) => MemoryObservationContext | undefined;
+
+/** Bind an acknowledgement to the render's context, never to a later turn or session. */
+export class MemoryObservations {
+  private readonly pending = new Map<string, { peer: PeerId; context: MemoryObservationContext; text: string }>();
+  constructor(private readonly telemetry: MemoryTelemetry, private readonly context: MemoryContext) {}
+
+  delivery(peer: PeerId, deliveryId: string, out: Envelope[], field: "rendered" | "delivered"): void {
+    try {
+      if (field === "rendered") {
+        const context = this.context(peer, out);
+        if (!context || out.some(env => env.private)) return;
+        // Ordinary quoted citations are counted as citations, not as a fresh recall rendering.
+        const text = out.filter(env => env.kind === "presence" || env.from === HUB && /Memory brief \(/.test(env.body)).map(env => env.body).join("\n");
+        if (!text.includes("mem:")) return;
+        this.pending.set(deliveryId, { peer, context, text });
+        // ponytail: retain at most 2048 live render contexts; an evicted or pre-restart acknowledgement stays unknown.
+        // Persist ids-only render context with the journal if measurements need complete crash/recovery coverage.
+        while (this.pending.size > 2048) this.pending.delete(this.pending.keys().next().value!);
+        this.telemetry.record(text, { ...context, deliveryId }, "rendered");
+      } else {
+        const prior = this.pending.get(deliveryId);
+        if (!prior || prior.peer !== peer) return;
+        this.pending.delete(deliveryId);
+        const now = this.context(peer, out);
+        if (!now || out.some(env => env.private) || now.session !== prior.context.session) return;
+        this.telemetry.record(prior.text, { ...prior.context, deliveryId }, "delivered");
+      }
+    } catch { /* optional sidecar observations never change transport or task outcomes */ }
+  }
+
+  // ponytail: citations without a proven source delivery use message:/summary: observation ids, not journal receipts.
+  // Join citations to a verified source delivery if per-delivery causal ratios become a study requirement.
+  cite(peer: PeerId, text: string, deliveryId: string, envelopes: readonly Envelope[] = []): void {
+    try {
+      const context = this.context(peer, envelopes);
+      if (!context || envelopes.some(env => env.private)) return;
+      this.telemetry.record(text, { ...context, deliveryId }, "cited");
+    } catch { /* unknown, never a fabricated zero */ }
+  }
+}

package/src/hub/memory-plan-guard.ts

@@ -0,0 +1,33 @@
+import { extractNodes, nodePath, type View } from "@staix/agent-mem";
+import type { BriefTask } from "../memory/brief.ts";
+
+export interface PlanGuardContext { cwd: string; project: string; repo: string; deny?: string[] }
+
+/** Explicit plan/ref names only, with no filesystem probes or free-text inference. */
+export function planGuardNodes(task: BriefTask, context: PlanGuardContext): string[] {
+  // Task refs/plan allow 150 explicit inputs; v1 note extraction caps each result at 64 nodes.
+  // Normalize each input separately, retaining the original single-file symbol qualification rule.
+  const nodes = new Set<string>();
+  for (const path of [...(task.refs.paths ?? []), ...(task.plan?.paths ?? [])]) {
+    for (const node of extractNodes("", { ...context, paths: [path], checkExists: false })) nodes.add(node);
+  }
+  const onlyPath = nodes.size === 1 ? nodePath([...nodes][0]!) : undefined;
+  for (const symbol of task.plan?.symbols ?? []) {
+    for (const node of extractNodes("", { ...context, paths: onlyPath ? [onlyPath] : [], symbols: [symbol], checkExists: false })) nodes.add(node);
+  }
+  return [...nodes].sort();
+}
+const samePath = (a: string, b: string) => a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
+
+/** Fail.about is the source of the graph's rules_out edges in v1; there is no additional stored rules_out field. */
+export function matchingPlanFails<T extends Pick<View, "kind" | "about" | "supersededBy">>(task: BriefTask, notes: readonly T[], context: PlanGuardContext): T[] {
+  const nodes = planGuardNodes(task, context);
+  if (!nodes.length) return [];
+  return notes.filter(note => note.kind === "fail" && !note.supersededBy && note.about.some(about => nodes.some(node => {
+    if (node === about) return true;
+    if (node.startsWith("symbol:") && about.startsWith("symbol:")) return false; // Qualified symbols require both name and file identity.
+    const path = nodePath(node), other = nodePath(about);
+    // File/directory scope intersects at a whole path component, never a lexical substring.
+    return !!path && !!other && samePath(path, other);
+  })));
+}

package/src/hub/memory-policy.ts

@@ -0,0 +1,42 @@
+import { detectSignals, type Routing } from "./routing.ts";
+import { matchesPolicy } from "./path-policy.ts";
+import { looksSecret, type PromotionScreen } from "@staix/agent-mem";
+import { nodePath, pathCandidates } from "@staix/agent-mem";
+
+/**
+ * Whether a note is about a path the `pii.paths` policy makes private: a stored node's path, a path-like word of its
+ * text, or, for a policy entry with no glob that a word split cannot find (a space in it), that entry written out.
+ */
+export function mentionsPrivatePath(text: string, about: string[], policy: string[], cwd: string): boolean {
+  if (!policy.length) return false;
+  const nfc = (v: string) => v.normalize("NFC"), body = nfc(text), entries = policy.map(nfc);
+  const paths = [...about.map(nodePath), ...pathCandidates(body)].filter((p): p is string => p !== undefined).map(nfc);
+  if (paths.some((p) => matchesPolicy(cwd, p, entries, true))) return true;
+  // The entry's literal part (up to its first glob character) written out: catches a path a word split breaks (a space).
+  return entries.some((entry) => { const lit = entry.replace(/^\.\//, "").split(/[*?[\]{}]/)[0]!.replace(/\/+$/, ""); return /[/\s]/.test(lit) && body.includes(lit); });
+}
+
+/**
+ * Notes whose title, text, nodes, task key or project key match the PII patterns of `routing`, or that are about a path
+ * the project's `pii.paths` (`policy`) makes private, left out: what may go to a model.
+ */
+export function withoutPii<T extends { title: string | null; text: string; about?: string[]; task?: string | null; project?: string }>(notes: T[], routing: Routing, cwd: string, policy: string[] = []): T[] {
+  // A task key's `#<id>@<created ms>` is the hub's own numbers, not note content: a digit-run pattern must not withhold a
+  // clean note for it. The project part of the key stays screened.
+  const keyText = (k: string) => k.replace(/#\d+(?:@\d+)?$/, "");
+  return notes.filter((v) => !mentionsPrivatePath(`${v.title ?? ""}\n${v.text}`, v.about ?? [], policy, cwd) && !detectSignals({ title: v.title ?? "",
+    detail: [v.text, ...(v.about ?? []).map((n) => n.startsWith("task:") ? keyText(n) : n), keyText(v.task ?? ""), v.project ?? ""].join("\n"), refs: {} }, routing, cwd).includes("pii"));
+}
+
+/**
+ * The promotion screen for one project: another project's notes are left to that project's own processes; this one's
+ * move only when no secret, PII pattern or private path (`policy()`, read when asked) is in them.
+ */
+export function promotionScreen(project: string, cwd: string, routing: () => Routing, policy: () => string[], taskPaths: (task: string) => string[] = () => []): PromotionScreen {
+  return (v) => {
+    if (v.project !== project) return "skip";
+    // The task's current paths too, with no denylist: a path the note's own nodes leave out is still checked.
+    const screened = { ...v, about: [...v.about, ...(v.task ? taskPaths(v.task) : []).map((p) => `path:${p}`)] };
+    return looksSecret(`${v.title ?? ""}\n${v.text}`) || !withoutPii([screened], routing(), cwd, policy()).length ? "keep" : "promote";
+  };
+}

package/src/hub/memory-profile-check.ts

@@ -0,0 +1,170 @@
+import { accessSync, constants, lstatSync } from "node:fs";
+import { join, parse, resolve, sep } from "node:path";
+import { registeredProjects } from "../cli/upgrade.ts";
+import { ControlClient, readControl, type ControlDescriptor } from "./control-client.ts";
+import { canonicalPath, hubHome, realPath } from "./project.ts";
+import { processLiveness, type Liveness } from "../pi/process-signature.ts";
+import type { Project } from "./registry.ts";
+import type { UnboundMemoryProfileReceipt } from "./memory-profile.ts";
+
+export interface ExpectedMemoryProfile {
+  home: string;
+  profile: "shared-v1" | "generation";
+  generation?: string;
+  selectorRevision: string;
+}
+export interface RunningMemoryProfile extends ExpectedMemoryProfile {
+  agentMemVersion: string;
+  state: "ready" | "stale" | "unavailable";
+  skippedRows?: number;
+}
+export type UnboundMemoryProfile = UnboundMemoryProfileReceipt;
+export type ReportedMemoryProfile = RunningMemoryProfile | UnboundMemoryProfile;
+export interface ProfileEvidence {
+  project: Project;
+  liveness: Liveness;
+  descriptor?: ControlDescriptor;
+  status?: unknown;
+  /** Resolved only after authenticated status; unknown is never treated as a different home. */
+  canonicalHome?: string;
+}
+export interface CheckedMemoryDaemon {
+  projectId: string;
+  projectRoot: string;
+  pid: number | null;
+  instanceId: string | null;
+  hubVersion: string | null;
+  agentMemVersion: string | null;
+  memoryProfile: ReportedMemoryProfile | null;
+  scope: "same-home" | "different-home" | "unknown";
+  ready: boolean;
+  quiesced?: true;
+  reason?: string;
+}
+export interface MemoryProfileCheck {
+  ready: boolean;
+  expected: ExpectedMemoryProfile;
+  /** Only this registry was inventoried; other custom registries are outside this receipt. */
+  registryHome?: string;
+  daemons: CheckedMemoryDaemon[];
+  reason?: string;
+}
+const object = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
+const revision = (value: unknown): value is string => value === "absent" || typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+const generationCapable = (version: string): boolean => {
+  const parts = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/.exec(version);
+  return !!parts && (Number(parts[1]) > 0 || Number(parts[2]) >= 3);
+};
+function receipt(value: unknown): ReportedMemoryProfile | undefined {
+  if (!object(value) || typeof value.home !== "string" || !value.home || value.home.length > 4096 || typeof value.agentMemVersion !== "string") return undefined;
+  if (!Object.hasOwn(value, "profile") && ["disabled", "unavailable"].includes(String(value.state))) {
+    if (["generation", "selectorRevision", "skippedRows"].some(field => Object.hasOwn(value, field))) return undefined;
+    return { home: value.home, agentMemVersion: value.agentMemVersion, state: value.state as UnboundMemoryProfile["state"] };
+  }
+  if (!["shared-v1", "generation"].includes(String(value.profile)) || !["ready", "stale", "unavailable"].includes(String(value.state)) || !revision(value.selectorRevision)
+    || value.profile === "generation" && (typeof value.generation !== "string" || !/^[a-f0-9]{32}$/.test(value.generation))
+    || value.profile === "shared-v1" && value.generation !== undefined
+    || value.skippedRows !== undefined && (!Number.isSafeInteger(value.skippedRows) || Number(value.skippedRows) < 0)) return undefined;
+  return { home: value.home, profile: value.profile as RunningMemoryProfile["profile"], ...(value.generation ? { generation: value.generation as string } : {}),
+    selectorRevision: value.selectorRevision, state: value.state as RunningMemoryProfile["state"], agentMemVersion: value.agentMemVersion,
+    ...(value.skippedRows !== undefined ? { skippedRows: value.skippedRows as number } : {}) };
+}
+
+/** Evaluate finite evidence only; installed package metadata is deliberately not an input. */
+export function evaluateMemoryProfileCheck(expected: ExpectedMemoryProfile, evidence: readonly ProfileEvidence[]): MemoryProfileCheck {
+  const daemons: CheckedMemoryDaemon[] = [];
+  for (const item of evidence) {
+    if (item.liveness === "gone") continue;
+    const { project, descriptor, status } = item;
+    const result: CheckedMemoryDaemon = { projectId: project.id, projectRoot: project.root, pid: project.pid, instanceId: project.instanceId,
+      hubVersion: null, agentMemVersion: null, memoryProfile: null, scope: "unknown", ready: false };
+    const reject = (reason: string) => { result.reason = reason; daemons.push(result); };
+    if (item.liveness !== "live" || !project.pidSignature || !project.instanceId || !project.pid) { reject("running owner identity is unknown"); continue; }
+    if (!descriptor || descriptor.pid !== project.pid || descriptor.pidSignature !== project.pidSignature || descriptor.projectId !== project.id
+      || descriptor.instanceId !== project.instanceId || descriptor.cwd !== project.root || !object(status) || status.pid !== project.pid
+      || status.projectId !== project.id || status.instanceId !== project.instanceId || status.cwd !== project.root) { reject("authenticated running identity was not confirmed"); continue; }
+    if (typeof status.version === "string") result.hubVersion = status.version;
+    const bound = receipt(status.memoryProfile);
+    if (!bound || !item.canonicalHome) { reject("running memory home/profile receipt is unavailable"); continue; }
+    result.memoryProfile = bound; result.agentMemVersion = bound.agentMemVersion;
+    if (item.canonicalHome !== expected.home) { result.scope = "different-home"; result.reason = "different canonical memory home"; daemons.push(result); continue; }
+    result.scope = "same-home";
+    if (!result.hubVersion || !/^[0-9]+\.[0-9]+\.[0-9]+$/.test(result.hubVersion) || !generationCapable(bound.agentMemVersion)) { reject("running memory library does not confirm generation support"); continue; }
+    if (bound.profile === undefined) {
+      result.ready = true; result.quiesced = true; result.reason = `memory handle ${bound.state}; quiesced`; daemons.push(result); continue;
+    }
+    if (bound.state !== "ready") { reject("running memory binding is not ready"); continue; }
+    if (bound.profile !== expected.profile || bound.generation !== expected.generation || bound.selectorRevision !== expected.selectorRevision) { reject("running memory binding differs from the selected profile"); continue; }
+    result.ready = true; daemons.push(result);
+  }
+  const relevant = daemons.filter(row => row.scope !== "different-home");
+  const ready = relevant.every(row => row.ready);
+  return { ready, expected, daemons, ...(!relevant.length ? { reason: "no live binding in this registry for this memory home; quiesced in this inventory only" } : {}) };
+}
+
+/** Reuse the recovery planner's readonly SQLite reader: never constructs/migrates a Registry. */
+export function readProfileCheckProjects(registryHome = hubHome()): Project[] {
+  const absolute = resolve(registryHome), root = parse(absolute).root;
+  let cursor = root;
+  for (const part of absolute.slice(root.length).split(sep).filter(Boolean)) {
+    cursor = join(cursor, part);
+    let stat: ReturnType<typeof lstatSync>;
+    try { stat = lstatSync(cursor); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return []; throw new Error("profile-check registry path unavailable"); }
+    // Existing directory aliases are supported, but a dangling alias is not proof of an absent registry.
+    if (stat.isSymbolicLink()) { try { stat = lstatSync(realPath(cursor)); } catch { throw new Error("profile-check registry path unavailable"); } }
+    if (!stat.isDirectory() || !(Number(stat.mode) & 0o111)) throw new Error("profile-check registry path unavailable");
+    accessSync(cursor, constants.X_OK);
+  }
+  const file = join(absolute, "registry.db");
+  let stat: ReturnType<typeof lstatSync>;
+  try { stat = lstatSync(file); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return []; throw new Error("profile-check registry unavailable"); }
+  if (!stat.isFile() || stat.isSymbolicLink() || !(Number(stat.mode) & 0o444)) throw new Error("profile-check registry unavailable");
+  accessSync(file, constants.R_OK);
+  return registeredProjects(canonicalPath(absolute));
+}
+
+export async function probeMemoryProfile(project: Project): Promise<ProfileEvidence> {
+  const liveness = project.pid ? processLiveness(project.pid, project.pidSignature) : project.instanceId ? "unknown" : "gone";
+  const evidence: ProfileEvidence = { project, liveness };
+  if (liveness !== "live" || !project.pidSignature || !project.instanceId) return evidence;
+  const descriptor = readControl(project.stateDir);
+  evidence.descriptor = descriptor;
+  if (!descriptor || descriptor.pid !== project.pid || descriptor.pidSignature !== project.pidSignature || descriptor.projectId !== project.id
+    || descriptor.instanceId !== project.instanceId || descriptor.cwd !== project.root) return evidence;
+  let client: ControlClient | undefined;
+  try {
+    client = await ControlClient.connect(project.stateDir, { role: "console", projectId: project.id, instanceId: project.instanceId, projectRoot: project.root }, 3000, descriptor.protocol);
+    const reply = await client.request({ t: "status" }, 5000);
+    if (reply.t !== "status" || reply.ok === false) return evidence;
+    evidence.status = reply.status;
+    const bound = object(reply.status) ? receipt(reply.status.memoryProfile) : undefined;
+    if (bound) evidence.canonicalHome = canonicalPath(bound.home);
+    evidence.liveness = processLiveness(project.pid!, project.pidSignature);
+  } catch { /* A timeout, old protocol or refusal is unknown evidence, never permission to migrate. */ }
+  finally { client?.close(); }
+  return evidence;
+}
+
+export async function checkMemoryProfiles(expected: ExpectedMemoryProfile, options: {
+  registryHome?: string;
+  projects?: readonly Project[];
+  probe?: (project: Project) => Promise<ProfileEvidence>;
+} = {}): Promise<MemoryProfileCheck> {
+  let projects: readonly Project[];
+  let registryHome = resolve(options.registryHome ?? hubHome());
+  try { projects = options.projects ?? readProfileCheckProjects(registryHome); registryHome = canonicalPath(registryHome); }
+  catch { return { ready: false, expected, registryHome, daemons: [], reason: "project registry could not be read without mutation" }; }
+  const evidence: ProfileEvidence[] = [];
+  for (const project of projects) evidence.push(await (options.probe ?? probeMemoryProfile)(project));
+  return { ...evaluateMemoryProfileCheck({ ...expected, home: canonicalPath(expected.home) }, evidence), registryHome };
+}
+
+export function formatMemoryProfileCheck(result: MemoryProfileCheck): string {
+  const lines = [`memory profile-check: ${result.ready ? "ready" : "not ready"}`, `home: ${result.expected.home}`, `selected: ${result.expected.profile}${result.expected.generation ? ` ${result.expected.generation}` : ""}`];
+  if (result.registryHome) lines.push(`registry inventory: ${result.registryHome}`, "scope: this registry only; check other custom registries separately before migration");
+  if (result.reason) lines.push(result.reason);
+  for (const row of result.daemons) lines.push(`${row.projectId} pid:${row.pid ?? "unknown"} hub:${row.hubVersion ?? "unknown"} agent-mem:${row.agentMemVersion ?? "unknown"} ${row.quiesced ? "unbound" : row.memoryProfile?.profile ?? "unknown"}${row.memoryProfile?.generation ? ` ${row.memoryProfile.generation}` : ""}: ${row.quiesced ? row.reason : row.ready ? "ready" : row.reason ?? "not ready"}`);
+  return lines.join("\n");
+}