@staix/agent-hub 0.12.29 → 0.12.31

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");
+}

package/src/hub/memory-profile.ts

@@ -0,0 +1,192 @@
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import {
+  CandidateStore, MemoryStore, realPath, memoryHome, resolveProfile,
+  type BoundProfile, type ProfileInput, type StoreOptions,
+} from "@staix/agent-mem";
+import packageJson from "../../package.json";
+
+const EXPECTED_AGENT_MEM_VERSION = packageJson.dependencies["@staix/agent-mem"];
+
+/** Validate metadata located through the actual imported entry, never the hub pin alone. */
+export function assertAgentMemVersion(metadata: unknown, expectedVersion = EXPECTED_AGENT_MEM_VERSION): string {
+  if (!metadata || typeof metadata !== "object") throw new Error("cannot attest loaded agent-mem version");
+  const value = metadata as { name?: unknown; version?: unknown };
+  if (value.name !== "@staix/agent-mem" || typeof value.version !== "string"
+    || !/^\d+\.\d+\.\d+$/.test(value.version) || value.version !== expectedVersion) {
+    throw new Error("loaded agent-mem version does not match the exact dependency pin");
+  }
+  return value.version;
+}
+
+const loadedAgentMem = (() => {
+  try {
+    if (!new URL(import.meta.url).pathname.endsWith("/src/hub/memory-profile.ts")) throw new Error("unattested bundled memory implementation");
+    const entry = import.meta.resolve("@staix/agent-mem");
+    if (!new URL(entry).pathname.endsWith("/src/index.ts")) throw new Error("unknown agent-mem entry layout");
+    // The package exports src/index.ts. Bundles without this resolvable layout
+    // cannot attest the imported implementation and must refuse to open memory.
+    const metadata: unknown = JSON.parse(readFileSync(new URL("../package.json", entry), "utf8"));
+    const actual = metadata && typeof metadata === "object" && typeof (metadata as { version?: unknown }).version === "string"
+      ? (metadata as { version: string }).version : "unknown";
+    try { return { version: assertAgentMemVersion(metadata), valid: true }; }
+    catch { return { version: actual, valid: false }; }
+  } catch { return { version: "unknown", valid: false }; }
+})();
+export const AGENT_MEM_VERSION = loadedAgentMem.version;
+function assertLoadedAgentMem(): void {
+  if (!loadedAgentMem.valid) throw new Error("cannot attest loaded agent-mem version against the exact dependency pin");
+}
+export const MEMORY_PROFILE_UNAVAILABLE = "memory profile unavailable; inspect the selector and generation state, run ahub memory profile-check; use amem migrate --deactivate only to stop using the selected generation";
+const UNAVAILABLE = MEMORY_PROFILE_UNAVAILABLE;
+
+/** No handle was opened; distinct from an unavailable, still-bound handle. */
+export interface UnboundMemoryProfileReceipt {
+  state: "disabled" | "unavailable";
+  home: string;
+  agentMemVersion: string;
+  error?: string;
+  profile?: never;
+  generation?: never;
+  selectorRevision?: never;
+  skippedRows?: never;
+}
+
+export interface MemoryProfileReceipt {
+  profile: BoundProfile["kind"];
+  generation?: string;
+  state: "ready" | "unavailable";
+  selectorRevision: string;
+  home: string;
+  agentMemVersion: string;
+  error?: string;
+  skippedRows: number;
+}
+
+function canonicalHome(path: string): string {
+  if (existsSync(path)) return realPath(path);
+  const parent = dirname(path);
+  return parent === path ? resolve(path) : join(canonicalHome(parent), basename(path));
+}
+function sameProfile(a: BoundProfile, b: BoundProfile): boolean {
+  return a.home === b.home && a.dir === b.dir && a.kind === b.kind
+    && a.generation === b.generation && a.selectorRevision === b.selectorRevision;
+}
+function homeFor(opts: Pick<StoreOptions, "home">): string {
+  return canonicalHome(opts.home === undefined ? memoryHome() : join(canonicalHome(opts.home), "memory"));
+}
+function receipt(profile: BoundProfile, state: MemoryProfileReceipt["state"], skippedRows = 0): MemoryProfileReceipt {
+  return {
+    profile: profile.kind, ...(profile.generation === undefined ? {} : { generation: profile.generation }),
+    state, home: profile.home, selectorRevision: profile.selectorRevision, agentMemVersion: AGENT_MEM_VERSION, skippedRows,
+    ...(state === "unavailable" ? { error: UNAVAILABLE } : {}),
+  };
+}
+
+/** Inspect selection without constructing a store, index, or candidate sidecar. */
+export function selectedMemoryProfile(opts: StoreOptions = {}): MemoryProfileReceipt {
+  assertLoadedAgentMem();
+  return receipt(resolveProfile(homeFor(opts)), "ready");
+}
+
+export class MemoryProfileBinding {
+  readonly home: string;
+  readonly profile: BoundProfile;
+  readonly explicitProfile: ProfileInput;
+  private readonly options: Pick<StoreOptions, "home">;
+  private readonly directMemoryDir: string | undefined;
+  private unavailable = false;
+
+  constructor(opts: StoreOptions = {}, private readonly onUnavailable?: (neutralReason: string) => void, directMemoryDir?: string) {
+    assertLoadedAgentMem();
+    this.options = { home: opts.home };
+    this.directMemoryDir = directMemoryDir;
+    this.home = directMemoryDir === undefined ? homeFor(this.options) : canonicalHome(directMemoryDir);
+    this.profile = Object.freeze({ ...resolveProfile(this.home) });
+    this.explicitProfile = this.profile.kind === "shared-v1" ? "shared-v1" : Object.freeze({ generation: this.profile.generation! });
+  }
+
+  assertCurrent(): void {
+    if (this.unavailable) throw new Error(UNAVAILABLE);
+    try {
+      const currentHome = this.directMemoryDir === undefined ? homeFor(this.options) : canonicalHome(this.directMemoryDir);
+      const current = resolveProfile(currentHome);
+      if (currentHome !== this.home || !sameProfile(current, this.profile)) throw new Error(UNAVAILABLE);
+    } catch {
+      this.invalidate();
+      throw new Error(UNAVAILABLE);
+    }
+  }
+
+  /** Entry fence only; migration requires quiescing and closing all consumers first. */
+  run<T>(work: () => T): T {
+    this.assertCurrent();
+    return work();
+  }
+
+  private invalidate(): void {
+    if (this.unavailable) return;
+    this.unavailable = true;
+    try { this.onUnavailable?.(UNAVAILABLE); } catch { /* Observer failures cannot undo the latch. */ }
+  }
+
+  status(store?: MemoryStore): MemoryProfileReceipt {
+    try { this.assertCurrent(); } catch { /* Report the latched state without exposing metadata errors. */ }
+    let skippedRows = 0;
+    if (!this.unavailable && store) {
+      try { skippedRows = store.bridgeStatus()?.skippedRows ?? 0; } catch { this.invalidate(); }
+    }
+    return receipt(this.profile, this.unavailable ? "unavailable" : "ready", skippedRows);
+  }
+
+  candidateOptions(opts: { home?: string; now?: () => number } = {}): { home?: string; now?: () => number } {
+    this.assertCurrent();
+    const inheritedHome = this.directMemoryDir === undefined ? this.options.home
+      : homeFor({}) === this.home ? undefined : dirname(this.home);
+    const options = { ...opts, home: opts.home ?? inheritedHome };
+    if (homeFor(options) !== this.home) throw new Error(UNAVAILABLE);
+    return options;
+  }
+}
+
+export function openProfileMemory(opts: StoreOptions = {}, onUnavailable?: (neutralReason: string) => void): {
+  store: MemoryStore; binding: MemoryProfileBinding;
+} {
+  const binding = new MemoryProfileBinding(opts, onUnavailable);
+  binding.assertCurrent();
+  const raw = new MemoryStore({ ...opts, profile: binding.explicitProfile });
+  try {
+    binding.assertCurrent();
+    if (!sameProfile(raw.profile, binding.profile)) throw new Error(UNAVAILABLE);
+    // ponytail: entry checks exclude an in-flight cutover; quiesce and close
+    // consumers before migration. Upgrade to a public core pre-write hook if
+    // atomic cutover across an in-flight operation becomes required.
+    return { store: raw, binding };
+  } catch (error) {
+    raw.close();
+    throw error;
+  }
+}
+
+/** Bind a caller-owned store only when it exactly matches the current person selection. */
+export function bindProfileMemory(store: MemoryStore, onUnavailable?: (neutralReason: string) => void): {
+  store: MemoryStore; binding: MemoryProfileBinding;
+} {
+  const binding = new MemoryProfileBinding({}, onUnavailable, store.profile.home);
+  binding.assertCurrent();
+  if (!sameProfile(store.profile, binding.profile)) throw new Error(UNAVAILABLE);
+  return { store, binding };
+}
+
+export function openProfileCandidates(binding: MemoryProfileBinding, opts: { home?: string; now?: () => number } = {}): CandidateStore {
+  const options = binding.candidateOptions(opts);
+  const raw = new CandidateStore(options);
+  try {
+    binding.assertCurrent();
+    if (canonicalHome(raw.dir) !== binding.home) throw new Error(UNAVAILABLE);
+    return raw;
+  } catch (error) {
+    raw.close();
+    throw error;
+  }
+}