@staix/agent-hub 0.12.28 → 0.12.30

package/src/cli/memory.ts

@@ -1,203 +1,103 @@
-import { extractNodes, GOAL_STATES, KINDS, looksSecret, MemoryStore, setMachineLabel, type GoalState, type GoalView, type Kind, type Tier, type View } from "../memory/store.ts";
-import { syncMemory, type SyncOptions } from "../memory/sync.ts";
-import { importClaudeMem } from "../memory/import.ts";
+import { detectCliIdentity } from "./identity.ts";
+import { createStalenessProbe } from "../hub/memory-staleness.ts";
+import { looksSecret, type MemoryStore, type StoreOptions } from "@staix/agent-mem";
+import type { SyncOptions } from "@staix/agent-mem";
+import { MEMORY_USAGE as CORE_MEMORY_USAGE, rawMemoryCommand, rawGoalCommand } from "@staix/agent-mem";
+import { memoryProjectKey } from "@staix/agent-mem";
+import { mentionsPrivatePath, promotionScreen, withoutPii } from "../hub/memory-policy.ts";
 import { currentRouting, detectSignals } from "../hub/routing.ts";
-import { memoryProjectKey, mentionsPrivatePath, projectChain, promotionScreen, withoutPii } from "../memory/recall.ts";
 import { loadConfig } from "../hub/daemon.ts";
+import { bindProfileMemory, openProfileMemory, MEMORY_PROFILE_UNAVAILABLE, type MemoryProfileReceipt } from "../hub/memory-profile.ts";
 
+export { GOAL_USAGE } from "@staix/agent-mem";
+export const MEMORY_USAGE = `${CORE_MEMORY_USAGE} | decay [--days N] [--json] | profile-check [--json]`;
+
+const fail = (message: string): never => { throw new Error(message); };
 /** The project's config, or none when there is no valid one (reading memory needs none). */
 const loadConfigSafe = (cwd: string) => { try { return loadConfig(cwd); } catch { return undefined; } };
 
-/**
- * #258: `ahub memory`, straight on the machine's store (no hub needed). Reading is anyone's; promote, demote, forget,
- * supersede and rebuild are a person's (the identity gate refuses agent shells).
- */
-export const MEMORY_USAGE = "usage: ahub memory [list] [--tier short|long] [--kind <kind>] [--peer <p>] [--machine <id>] [--since <iso>] [--limit N] | search <words> | show <id> | graph <id|node> [--hops 1|2] | promote|demote|forget <id> | supersede <old> <new> | rebuild | sync [--remote <url>] | machine [--label <name>] | import claude-mem [--db <path>] [--limit N] [--restart] | dedupe [--apply] | suggestions | confirm|reject <suggestion id>  [--json]";
-export const GOAL_USAGE = "usage: ahub goal [list] [--all] | show <id> | new <title> [--milestone <text>]... [--depends <id>]... [--shared] | link <id> <task id> | state <id> open|active|blocked|done|dropped | done <id> | take <id> [--force]  [--json]";
 
-const fail = (message: string): never => { throw new Error(message); };
-const one = (v: View) => `${v.id.slice(0, 8)}  ${v.at.slice(0, 16).replace("T", " ")}  ${v.tier.padEnd(5)} ${v.kind.padEnd(8)} ${v.peer.padEnd(8)} ${v.scope === "shared" ? "shared " : ""}${`${v.title ? `${v.title}: ` : ""}${v.text}`.replace(/\s+/g, " ").slice(0, 100)}${v.supersededBy ? `  (superseded by ${v.supersededBy.slice(0, 8)})` : ""}`;
-function detail(v: View): string[] {
-  return [`${v.id}  ${v.kind}, ${v.tier}-term${v.expiresAt ? ` until ${v.expiresAt}` : ""}, ${v.scope}`, `by ${v.peer} on machine ${v.machine}, ${v.at}, project ${v.project}${v.task ? `, task ${v.task}` : ""}`,
-    ...(v.promotedFrom ? [`promoted from ${v.promotedFrom}`] : []), ...(v.supersededBy ? [`superseded by ${v.supersededBy}`] : []), ...(v.about.length ? [`about: ${v.about.join(", ")}`] : []), "", ...(v.title ? [v.title] : []), v.text];
+/** Bind each command at entry; the CLI closes default opens and injected stores remain caller-owned. */
+function commandStores(provided?: MemoryStore, options: StoreOptions = {}) {
+  try { return { ...(provided ? bindProfileMemory(provided) : openProfileMemory(options)), owned: !provided }; }
+  catch { throw new Error(MEMORY_PROFILE_UNAVAILABLE); }
+}
+function profileOutput(text: string, json: boolean, profile: MemoryProfileReceipt | undefined, person: boolean): string {
+  if (!profile) return text;
+  if (profile.state !== "ready") throw new Error(MEMORY_PROFILE_UNAVAILABLE);
+  if (json) return text;
+  return `${text}\nmemory profile: ${profile.profile}${profile.generation ? ` ${person ? profile.generation : profile.generation.slice(0, 8)}` : ""}${person && profile.skippedRows ? `; skipped malformed legacy rows: ${profile.skippedRows}` : ""}`;
 }
 
-export async function memoryCommand(args: string[], cwd: string, opts: { store?: MemoryStore; sync?: Omit<SyncOptions, "remote"> } = {}): Promise<string> {
-  const json = args.includes("--json");
-  const rest = args.filter((a) => a !== "--json");
-  const flag = (name: string) => { const i = rest.indexOf(name); if (i < 0) return undefined; const v = rest[i + 1] ?? fail(`${name} needs a value`); rest.splice(i, 2); return v; };
-  const sub = rest[0] && !rest[0].startsWith("--") ? rest.shift()! : "list";
-  // The project's private paths (`pii.paths`): a note about one is withheld like a note matching a PII pattern. A config
-  // that does not load fails the read closed: its privacy policy is not dropped for agent-readable output.
+/** Hub wrapper: current project policy and TTL stay here; parsing and storage commands belong to the core. */
+export async function memoryCommand(args: string[], cwd: string, opts: { store?: MemoryStore; sync?: Omit<SyncOptions, "remote">; now?: () => number; person?: boolean } = {}): Promise<string> {
+  const person = opts.person ?? detectCliIdentity(process.env).role === "console";
   const privatePaths = (): string[] => { try { return loadConfig(cwd).pii?.paths ?? []; } catch (e) { return fail(`the project's config does not load (${(e as Error).message}); fix it before reading hub memory`); } };
-  // A store opened here promotes this project's notes only through its current policy (privatePaths fails closed).
-  // The project's own short-term lifetime, so a deadline this command writes (a demotion) matches what its hub would write.
-  const store = opts.store ?? new MemoryStore({ ttlMs: (loadConfigSafe(cwd)?.memory.short_ttl_days ?? 14) * 24 * 3600_000, screen: promotionScreen(memoryProjectKey(cwd), cwd, () => currentRouting(cwd), () => privatePaths()) });
-  const actor = "user";
-  const project = memoryProjectKey(cwd);
-  const need = (v: View | undefined, id: string) => v ?? fail(`no memory entry ${id} (ahub memory list shows the ids)`);
-  try {
-    switch (sub) {
-      case "list": case "search": {
-        const tier = flag("--tier"), kind = flag("--kind"), peer = flag("--peer"), machine = flag("--machine"), since = flag("--since"), limit = flag("--limit");
-        if (since !== undefined && Number.isNaN(Date.parse(since))) fail(`--since needs a date or time (ISO 8601), not ${since}`);
-        if (tier && tier !== "short" && tier !== "long") fail("--tier takes short or long");
-        if (kind && !KINDS.includes(kind as Kind)) fail(`--kind takes ${KINDS.join(", ")}`);
-        if (limit && !(Number(limit) > 0)) fail("--limit takes a positive number");
-        const q = sub === "search" ? rest.join(" ") || fail("usage: ahub memory search <words>") : rest.length ? fail(MEMORY_USAGE) : undefined;
-        // Agent shells may run this: notes are screened under this project's current PII policy, as briefs and recall are
-        // (a shared note was accepted under another project's patterns). The dashboard shows a person everything.
-        const all = store.list({ project, ...(tier ? { tier: tier as Tier } : {}), ...(kind ? { kind: kind as Kind } : {}), ...(peer ? { peer } : {}), ...(machine ? { machine } : {}), ...(since ? { since } : {}), ...(q ? { q } : {}), limit: Number.MAX_SAFE_INTEGER });
-        // Screened first, then cut to the limit: withheld entries never crowd out readable ones.
-        const readable = withoutPii(all, currentRouting(cwd), cwd, privatePaths()), rows = readable.slice(0, limit ? Number(limit) : 50);
-        if (json) return JSON.stringify(rows, null, 2);
-        const c = store.counts(project);
-        const withheld = all.length - readable.length;
-        return [`hub memory for ${project} on machine ${c.machine.label}: ${c.long} long-term, ${c.short} short-term`, ...(rows.length ? rows.map(one) : ["(nothing)"]),
-          ...(withheld ? [`(${withheld} withheld: they match a PII pattern; the dashboard shows them)`] : [])].join("\n");
-      }
-      case "show": {
-        const id = rest[0] ?? fail("usage: ahub memory show <id>");
-        const v = need(store.get(id, project), id);
-        if (!withoutPii([v], currentRouting(cwd), cwd, privatePaths()).length) fail(`${v.id.slice(0, 8)} is withheld: it matches a PII pattern (the dashboard shows it)`);
-        return json ? JSON.stringify(v, null, 2) : detail(v).join("\n");
-      }
-      case "graph": {
-        const hops = Number(flag("--hops") ?? 1);
-        if (hops !== 1 && hops !== 2) fail("--hops takes 1 or 2");
-        const start = rest[0] ?? fail("usage: ahub memory graph <id|node>");
-        const node = start.includes(":") && !start.startsWith("mem:") ? start : `mem:${need(store.get(start, project), start).id}`;
-        const g = store.graph(project, node, hops);
-        return json ? JSON.stringify(g, null, 2) : [`${g.nodes.length} nodes, ${g.edges.length} edges around ${node}`, ...g.edges.map((e) => `${e.from} -${e.rel}-> ${e.to}`)].join("\n");
-      }
-      case "promote": { const v = need(store.get(rest[0] ?? fail(MEMORY_USAGE), project), rest[0]!); if (v.supersededBy) fail(`${v.id.slice(0, 8)} is replaced by ${v.supersededBy.slice(0, 8)}: promote that one instead`); const id = store.promote(v.id, actor, project) ?? fail(v.project !== project ? `${v.id.slice(0, 8)} is another project's note: promote it from that project` : `${v.id.slice(0, 8)} stays short-term: it holds a secret, matches a PII pattern or is about a private path`); return id === v.id ? `${v.id.slice(0, 8)} is already long-term` : `promoted to long-term as ${id.slice(0, 8)}`; }
-      case "demote": { const v = need(store.get(rest[0] ?? fail(MEMORY_USAGE), project), rest[0]!); if (v.tier !== "long") return `${v.id.slice(0, 8)} is already short-term`; store.demote(v.id, actor, project); return `demoted ${v.id.slice(0, 8)}: it expires ${store.get(v.id, project)?.expiresAt ?? "with its short-term lifetime"}`; }
-      case "forget": { const v = need(store.forget(rest[0] ?? fail(MEMORY_USAGE), actor, project), rest[0]!); return `forgot ${v.id.slice(0, 8)}${v.local ? "" : "; it stays in the sync remote's git history until a person rewrites it (docs/memory.md)"}`; }
-      case "supersede": {
-        if (rest.length !== 2) fail("usage: ahub memory supersede <old> <new>");
-        return store.supersede(rest[0]!, rest[1]!, actor, project) ? `${rest[0]} is superseded by ${rest[1]}` : fail("both ids must name different entries, and the newer one must reach as far: shared for a shared entry, long-term for a long-term one (ahub memory promote it first)");
-      }
-      case "sync": {
-        const remote = flag("--remote");
-        if (rest.length) fail("usage: ahub memory sync [--remote <private git url>]");
-        const r = await syncMemory(store, { ...opts.sync, ...(remote ? { remote } : {}) });
-        if (json) return JSON.stringify(r, null, 2);
-        if (!r.ok) fail(`hub memory sync: ${r.error}`);
-        return `synced${r.pushed ? " and pushed" : ""}: ${r.entries} long-term entries visible here${r.warning ? `\nnote: ${r.warning}` : ""}`;
-      }
-      case "dedupe": {
-        const apply = rest.includes("--apply");
-        if (rest.some(arg => arg !== "--apply")) fail("usage: ahub memory dedupe [--apply] [--json]");
-        const result = store.dedupe(project, apply);
-        if (json) return JSON.stringify(result, null, 2);
-        return [result.groups.length ? `${result.groups.length} duplicate import group(s)${apply ? `; appended ${result.applied} supersede operation(s)` : "; use --apply to reconcile"}` : "no duplicate import groups to reconcile",
-          ...result.groups.map(g => `${g.members.map(v => v.id.slice(0, 8)).join(", ")} -> ${g.target.slice(0, 8)}: ${g.members[0]!.text}`)].join("\n");
-      }
-      case "import": {
-        const db = flag("--db"), limit = flag("--limit");
-        const restart = rest.includes("--restart");
-        if (restart) rest.splice(rest.indexOf("--restart"), 1);
-        if (rest[0] !== "claude-mem" || rest.length !== 1) fail("usage: ahub memory import claude-mem [--db <path>] [--limit N] [--restart]");
-        if (limit && !(Number(limit) > 0)) fail("--limit takes a positive number");
-        const routing = currentRouting(cwd);
-        const policy = privatePaths(); // a note about a private path never reaches the synced log
-        const key = memoryProjectKey(cwd);
-        const nodes = (text: string) => extractNodes(text, { cwd, project: key, repo: key.startsWith("github.com/") ? key.slice("github.com/".length) : key, checkExists: false });
-        const r = importClaudeMem(store, { project: key, chain: projectChain(cwd), nodes, restart, isPii: (text) => detectSignals({ title: text, detail: "", refs: {} }, routing, cwd).includes("pii") || mentionsPrivatePath(text, [], policy, cwd), ...(db ? { db } : {}), ...(limit ? { limit: Number(limit) } : {}) });
-        if (json) return JSON.stringify(r, null, 2);
-        return `imported ${r.added} of ${r.read} hub notes from claude-mem as long-term entries (skipped: ${r.skipped.model} model answers, ${r.skipped.pii} PII, ${r.skipped.secret} secret-looking; other candidates were empty, malformed or already imported)${r.more ? "\nmore remain: run it again" : ""}`;
-      }
-      case "suggestions": {
-        const pending = store.suggestions(project).filter((x) => x.status === "suggested");
-        if (json) return JSON.stringify(pending, null, 2);
-        return pending.length ? pending.map((x) => `${x.id.slice(0, 8)}  ${x.from.slice(0, 8)} ${x.rel} ${x.to.slice(0, 8)}  (suggested by the hub's model ${x.at}; not evidence until confirmed)`).join("\n") : "no edge suggestions waiting";
-      }
-      case "confirm": case "reject": {
-        const x = store.judge(rest[0] ?? fail(`usage: ahub memory ${sub} <suggestion id>`), sub, actor, project) ?? fail(`no suggestion ${rest[0]} (ahub memory suggestions lists them)`);
-        return `${sub === "confirm" ? "confirmed" : "rejected"}: ${x.from.slice(0, 8)} ${x.rel} ${x.to.slice(0, 8)}`;
-      }
-      case "machine": {
-        const label = flag("--label");
-        const m = label ? setMachineLabel(store.dir, label) : store.machine;
-        return json ? JSON.stringify(m) : `this machine: ${m.id} (${m.label})`;
-      }
-      case "rebuild": { store.rebuild(); const c = store.counts(); return `rebuilt the index from ${c.segments} segment${c.segments === 1 ? "" : "s"}: ${c.long} long-term, ${c.short} short-term entries`; }
-      default: return fail(MEMORY_USAGE);
+  const rest = args.filter(arg => arg !== "--json");
+  if (rest[0] === "decay") {
+    if (!person) fail("memory decay requires person authority");
+    let days = 90;
+    if (rest.length !== 1) {
+      if (rest.length !== 3 || rest[1] !== "--days" || !/^[1-9][0-9]*$/.test(rest[2]!)) fail("usage: ahub memory decay [--days N] [--json] (N must be a positive integer)");
+      days = Number(rest[2]);
     }
-  } finally { if (!opts.store) store.close(); }
-}
-
-const goalOne = (g: GoalView, me: string) => `${g.id.slice(0, 8)}  ${g.state.padEnd(7)} ${g.title}${g.scope === "shared" ? "  [shared]" : ""}  ${leaseText(g, me)}`;
-function leaseText(g: GoalView, me: string): string {
-  const who = (m: string) => m === me ? "this machine" : `machine ${m.slice(0, 8)}`;
-  if (g.lease.holder) return `held by ${who(g.lease.holder)} until ${g.lease.until}${g.lease.conflict.length ? `, CONFLICT with ${g.lease.conflict.map(who).join(", ")} (the earlier claim holds; a person settles it with ahub goal take --force)` : ""}`;
-  return g.lease.expired ? `free (${who(g.lease.lastHolder!)}'s lease ended ${g.lease.until})` : "free";
+    const cutoffMs = (opts.now ?? Date.now)() - days * 24 * 3600_000;
+    if (!Number.isSafeInteger(days) || !Number.isFinite(cutoffMs) || Math.abs(cutoffMs) > 8_640_000_000_000_000) fail("--days is outside the supported date range");
+    const cutoff = new Date(cutoffMs).toISOString();
+    const project = memoryProjectKey(cwd), routing = currentRouting(cwd), paths = privatePaths();
+    // Review must not promote a held source while reading it: only explicit person actions may append rows.
+    const context = commandStores(opts.store, { deferPromotions: true, now: opts.now });
+    const store = context.store;
+    try {
+      context.binding.assertCurrent();
+      const candidates = store.withDeferredPromotions(() => {
+        const goals = store.goals(project).filter(goal => goal.state !== "done" && goal.state !== "dropped");
+        const linkedTasks = new Set(goals.flatMap(goal => goal.links.map(link => link.task)));
+        const openGoals = new Set(goals.map(goal => `goal:${goal.id}`));
+        return withoutPii(store.list({ project, tier: "long", limit: Number.MAX_SAFE_INTEGER }).filter(note =>
+          note.project === project && Date.parse(note.at) < cutoffMs
+          && !(note.task && linkedTasks.has(note.task))
+          && !note.about.some(node => openGoals.has(node) || (node.startsWith("task:") && linkedTasks.has(node.slice(5))))), routing, cwd, paths);
+      });
+      const profile = context.binding.status(store);
+      if (args.includes("--json")) return profileOutput(JSON.stringify({ days, cutoff, candidates, memoryProfile: profile }), true, profile, person);
+      const text = candidates.length
+        ? [`${candidates.length} decay candidate${candidates.length === 1 ? "" : "s"} older than ${days} days (review only):`, ...candidates.map(note => `mem:${note.id} ${note.at} ${note.kind}: ${note.title ?? note.text}`)].join("\n")
+        : `no decay candidates older than ${days} days`;
+      return profileOutput(text, false, profile, person);
+    } finally { if (context.owned) store.close(); }
+  }
+  let showStale = false;
+  const context = commandStores(opts.store, { ttlMs: (loadConfigSafe(cwd)?.memory.short_ttl_days ?? 14) * 24 * 3600_000,
+    screen: promotionScreen(memoryProjectKey(cwd), cwd, () => currentRouting(cwd), privatePaths) });
+  try {
+    context.binding.assertCurrent();
+    const text = await rawMemoryCommand(args, cwd, { ...opts, store: context.store, open: () => context.store,
+      readable: notes => {
+      const paths = privatePaths(), visible = withoutPii(notes, currentRouting(cwd), cwd, paths);
+      if (args[0] !== "show" || args.includes("--json")) return visible;
+      const stale = createStalenessProbe({ cwd, privatePaths: paths, deny: loadConfigSafe(cwd)?.local.deny ?? [] });
+      showStale = visible.some(note => stale(note.about));
+      return visible;
+    },
+      importPolicy: () => {
+      const routing = currentRouting(cwd), policy = privatePaths();
+      return text => detectSignals({ title: text, detail: "", refs: {} }, routing, cwd).includes("pii") || mentionsPrivatePath(text, [], policy, cwd);
+    },
+    });
+    return profileOutput(showStale ? `${text}\n(stale?)` : text, args.includes("--json"), context.binding.status(context.store), person);
+  } finally { if (context.owned) context.store.close(); }
 }
 
-/**
- * #258: `ahub goal`, long-term tasks. Listing and showing are anyone's; new, link, state, done and take are a
- * person's. A peer links its own board task with hub_task_propose's `goal`.
- */
-export async function goalCommand(args: string[], cwd: string, opts: { store?: MemoryStore; link?: (goal: string, task: string) => Promise<string> } = {}): Promise<string> {
-  const json = args.includes("--json");
-  const rest = args.filter((a) => a !== "--json");
-  const take = (name: string) => { const out: string[] = []; for (let i = rest.indexOf(name); i >= 0; i = rest.indexOf(name)) { out.push(rest[i + 1] ?? fail(`${name} needs a value`)); rest.splice(i, 2); } return out; };
-  const sub = rest[0] && !rest[0].startsWith("--") ? rest.shift()! : "list";
-  const store = opts.store ?? new MemoryStore();
-  const project = memoryProjectKey(cwd);
-  const me = store.machine.id;
-  // Only this project's long-term tasks and shared ones, like every other lookup an agent may run.
-  const need = (id: string | undefined) => store.goalOf(id?.replace(/^goal:/, "") ?? fail(GOAL_USAGE), project) ?? fail(`no long-term task ${id} for this project (ahub goal list shows them)`);
-  // Agent shells may read goals and a goal syncs to every machine: titles and milestones pass the same screen as notes
-  // (PII patterns, pii.paths; a config that does not load fails closed).
+export async function goalCommand(args: string[], cwd: string, opts: { store?: MemoryStore; link?: (goal: string, task: string) => Promise<string>; person?: boolean } = {}): Promise<string> {
+  const person = opts.person ?? detectCliIdentity(process.env).role === "console";
   const policy = (): string[] => { try { return loadConfig(cwd).pii?.paths ?? []; } catch (e) { return fail(`the project's config does not load (${(e as Error).message}); fix it before using long-term tasks`); } };
-  const clean = (title: string, milestones: string[], of = project) => !looksSecret(`${title}\n${milestones.join("\n")}`) && withoutPii([{ title, text: milestones.join("\n"), project: of }], currentRouting(cwd), cwd, policy()).length > 0;
+  const context = commandStores(opts.store);
   try {
-    switch (sub) {
-      case "list": {
-        const all = rest.includes("--all");
-        const listed = store.goals(project).filter((g) => all || (g.state !== "done" && g.state !== "dropped"));
-        const goals = listed.filter((g) => clean(g.title, g.milestones, g.project)), withheld = listed.length - goals.length;
-        if (json) return JSON.stringify(goals, null, 2);
-        return [...(goals.length ? goals.map((g) => goalOne(g, me)) : [`no ${all ? "" : "open "}long-term tasks for ${project} (ahub goal new <title>)`]),
-          ...(withheld ? [`(${withheld} withheld: they match a PII pattern or a private path)`] : [])].join("\n");
-      }
-      case "show": {
-        const g = need(rest[0]);
-        if (!clean(g.title, g.milestones, g.project)) fail(`${g.id.slice(0, 8)} is withheld: it matches a PII pattern or a private path`);
-        if (json) return JSON.stringify(g, null, 2);
-        return [goalOne(g, me), `${g.id}, project ${g.project}, created ${g.at} on machine ${g.machine.slice(0, 8)}`,
-          ...g.milestones.map((m) => `milestone: ${m}`), ...g.dependsOn.map((d) => `depends on ${d.slice(0, 8)}`),
-          ...(g.links.length ? g.links.map((l) => `board task ${l.task} (linked ${l.at} on machine ${l.machine.slice(0, 8)})`) : ["no board tasks linked yet"])].join("\n");
-      }
-      case "new": {
-        const milestones = take("--milestone"), depends = take("--depends").map((d) => need(d).id);
-        const shared = rest.includes("--shared");
-        const title = rest.filter((a) => a !== "--shared").join(" ").trim() || fail(GOAL_USAGE);
-        if (!clean(title, milestones)) fail("a long-term task syncs to every machine: this one holds a secret, a PII pattern or a private path and is not saved");
-        const id = store.goal({ project, scope: shared ? "shared" : "project", title, milestones, dependsOn: depends, actor: "user" });
-        return `long-term task ${id.slice(0, 8)} created: ${title}`;
-      }
-      case "link": {
-        const g = need(rest[0]);
-        const task = rest[1] ?? fail("usage: ahub goal link <id> <task id>");
-        if (!/^\d+$/.test(task)) fail("the task is a board task id of this project");
-        return await (opts.link ?? fail("linking needs this project's hub running (ahub up)"))(g.id, task);
-      }
-      case "state": case "done": {
-        const g = need(rest[0]);
-        const state = (sub === "done" ? "done" : rest[1]) as GoalState;
-        if (!GOAL_STATES.includes(state)) fail(`the state is one of ${GOAL_STATES.join(", ")}`);
-        store.goalState(g.id, state, "user");
-        return `long-term task ${g.id.slice(0, 8)} is ${state}`;
-      }
-      case "take": {
-        const g = need(rest[0]);
-        const r = store.take(g.id, "user", { force: rest.includes("--force") });
-        if (!r.ok) fail(`held by machine ${r.holder.slice(0, 8)} until ${r.until}; wait for it to expire or take it over with --force`);
-        return `this machine holds long-term task ${g.id.slice(0, 8)} until ${r.until}${rest.includes("--force") ? " (earlier claims are void)" : ""}`;
-      }
-      default: return fail(GOAL_USAGE);
-    }
-  } finally { if (!opts.store) store.close(); }
+    context.binding.assertCurrent();
+    const text = await rawGoalCommand(args, cwd, { ...opts, store: context.store, open: () => context.store,
+      clean: (title, milestones, project) => !looksSecret(`${title}\n${milestones.join("\n")}`) && withoutPii([{ title, text: milestones.join("\n"), project }], currentRouting(cwd), cwd, policy()).length > 0,
+    });
+    return profileOutput(text, args.includes("--json"), context.binding.status(context.store), person);
+  } finally { if (context.owned) context.store.close(); }
 }

package/src/cli/output.ts

@@ -7,6 +7,7 @@ import { formatReport, formatTaskReport, type Report, type TaskReport } from "..
 
 export interface DoctorCheck { section: "Tools" | "Hub" | "Config" | "Models" | "Memory"; level: "ok" | "warn" | "fail" | "unknown"; name: string; detail: string }
 export interface StatusOutput {
+  memoryProfile?: { profile?: string; generation?: string; state?: string; agentMemVersion?: string; skippedRows?: number; error?: string };
   taskWip?: Record<string, { wip: number; wipLimit: number }>;
   pid?: number; controlPort?: number; cwd?: string; version?: string; peers: Record<string, any>; roleInfo?: Record<string, any>; budget?: Record<string, any>;
   tasks?: Record<string, number>; models?: { backends?: any[] }; permissionDefaults?: any[]; deliveryError?: string; crash?: string[]; switchyard?: string;
@@ -184,6 +185,11 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
   if (data.roleInfo) data = { ...data, peers: Object.fromEntries(Object.entries(data.peers).map(([peer, value]) => [peer, { ...value, ...data.roleInfo?.[peer] }])) };
   const out = lines(`agent-hub${data.version ? ` ${data.version}` : ""}  pid ${data.pid ?? "unknown"}  control 127.0.0.1:${data.controlPort ?? "unknown"}`, columns, "info");
   if (data.cwd) out.push(...lines(data.cwd, columns));
+  if (data.memoryProfile) {
+    const memory = data.memoryProfile;
+    const profile = memory.profile === "generation" ? `generation ${memory.generation?.slice(0, 8) ?? "unknown"}` : memory.profile ?? "unbound";
+    out.push(...detail("memory", `${profile}; ${memory.state ?? "unknown"}; agent-mem ${memory.agentMemVersion ?? "unknown"}${memory.skippedRows ? `; malformed legacy rows skipped: ${memory.skippedRows}` : ""}${memory.error ? `; ${memory.error}` : ""}`, columns, memory.state === "unavailable" ? "attention" : undefined));
+  }
   if (data.deliveryError) out.push(...detail("delivery storage", `${data.deliveryError}; dispatch is stopped`, columns, "failure"));
   for (const pending of data.permissionDefaults ?? []) out.push(...detail("permission default", `${pending.peer}: never-ask from ${pending.source}, stays ask until a person confirms in ahub console`, columns, "attention"));
   for (const crash of data.crash ?? []) out.push(...detail("crash recovery", crash, columns, "attention"));

package/src/cli/recovery-package.ts

@@ -1,8 +1,9 @@
 import { spawn } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { hubHome } from "../hub/project.ts";
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createRequire } from "node:module";
+import { hubHome, realPath } from "../hub/project.ts";
 
 export type CommandResult = { code: number; stdout: string; stderr: string };
 export type RunCommand = (args: string[], options?: { cwd?: string; env?: NodeJS.ProcessEnv; timeoutMs?: number }) => Promise<CommandResult>;
@@ -32,28 +33,76 @@ export function exactVersion(version: string): string {
   return version;
 }
 
-export function packageDigest(root: string): string {
+const MEMORY_ASSETS = ["src", "bin", "package.json", "README.md", "LICENSE"] as const;
+
+/** The sole runtime dependency is a bounded first-party package, never an arbitrary dependency tree. */
+function memoryRuntime(root: string, dependencyRoot?: string): string | undefined {
+  const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+  const deps = pkg.dependencies ?? {};
+  if (!Object.keys(deps).length) return undefined;
+  const version = deps["@staix/agent-mem"];
+  if (Object.keys(deps).length !== 1 || typeof version !== "string" || !/^\d+\.\d+\.\d+$/.test(version)) throw new Error("unsupported runtime dependencies in recovery package");
+  let dir = dependencyRoot ? join(dependencyRoot, "node_modules/@staix/agent-mem")
+    : dirname(createRequire(join(root, "package.json")).resolve("@staix/agent-mem"));
+  if (dependencyRoot && !existsSync(dir)) throw new Error("memory runtime dependency is unavailable");
+  if (dependencyRoot) for (const name of ["node_modules", "node_modules/@staix", "node_modules/@staix/agent-mem"]) {
+    if (lstatSync(join(dependencyRoot, name)).isSymbolicLink()) throw new Error("runtime package must not contain symlinks");
+  }
+  for (;;) {
+    const manifest = join(dir, "package.json");
+    if (existsSync(manifest)) {
+      const memory = JSON.parse(readFileSync(manifest, "utf8"));
+      if (memory.name === "@staix/agent-mem") {
+        if (memory.version !== version || Object.keys(memory.dependencies ?? {}).length) throw new Error("memory runtime dependency identity/version mismatch");
+        return realPath(dir);
+      }
+    }
+    const parent = dirname(dir);
+    if (dependencyRoot || parent === dir) throw new Error("memory runtime dependency is unavailable");
+    dir = parent;
+  }
+}
+
+export function preserveRuntimeDependencies(root: string, destination: string): void {
+  const memory = memoryRuntime(root);
+  if (!memory) return;
+  const target = join(destination, "node_modules/@staix/agent-mem");
+  mkdirSync(target, { recursive: true });
+  for (const name of MEMORY_ASSETS) {
+    if (lstatSync(join(memory, name)).isSymbolicLink()) throw new Error("runtime package must not contain symlinks");
+    cpSync(join(memory, name), join(target, name), { recursive: true, dereference: false });
+  }
+}
+
+export function packageDigest(root: string, options: { ownDependencies?: boolean; dependencyRoot?: string } = {}): string {
   const hash = createHash("sha256");
+  const file = (path: string, name: string) => { hash.update(name); hash.update("\0"); hash.update(readFileSync(path)); hash.update("\0"); };
   const visit = (directory: string, prefix = "") => {
     for (const item of readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
       if (item.isSymbolicLink()) throw new Error("runtime package must not contain symlinks");
       const name = `${prefix}${item.name}`;
       if (item.isDirectory()) visit(join(directory, item.name), `${name}/`);
-      else { hash.update(name); hash.update("\0"); hash.update(readFileSync(join(directory, item.name))); hash.update("\0"); }
+      else file(join(directory, item.name), name);
     }
   };
-  // Only runtime assets; never copy or hash a checkout's private state or dependencies.
+  // Only runtime assets and the exact first-party package; never private state or unrelated dependencies.
   for (const name of ["src", "plugins", "templates", ".claude-plugin"]) visit(join(root, name), `${name}/`);
   hash.update(readFileSync(join(root, "package.json")));
+  const memory = memoryRuntime(root, options.ownDependencies ? root : options.dependencyRoot);
+  if (memory) for (const name of MEMORY_ASSETS) {
+    const path = join(memory, name), stat = lstatSync(path), prefix = `node_modules/@staix/agent-mem/${name}`;
+    if (stat.isSymbolicLink()) throw new Error("runtime package must not contain symlinks");
+    if (stat.isDirectory()) visit(path, `${prefix}/`); else file(path, prefix);
+  }
   return hash.digest("hex");
 }
 
-export function verifyPackage(root: string, version: string): string {
+export function verifyPackage(root: string, version: string, options: { ownDependencies?: boolean; dependencyRoot?: string } = {}): string {
   const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
   const plugin = JSON.parse(readFileSync(join(root, "plugins/agent-hub/.claude-plugin/plugin.json"), "utf8"));
   if (pkg.name !== "@staix/agent-hub" || pkg.version !== version || plugin.version !== version ||
       !existsSync(join(root, "src/cli/main.js"))) throw new Error("staged package identity/version mismatch");
-  return packageDigest(root);
+  return packageDigest(root, options);
 }
 
 export async function registryRelease(version: string, run: RunCommand = runCommand): Promise<{ version: string; integrity: string }> {
@@ -92,7 +141,7 @@ export async function stageRelease(version: string, integrity: string, run: RunC
   const root = join(destination, "node_modules/@staix/agent-hub");
   if (existsSync(destination)) {
     const saved = JSON.parse(readFileSync(join(destination, "verified.json"), "utf8"));
-    const digest = verifyPackage(root, version);
+    const digest = verifyPackage(root, version, { dependencyRoot: destination });
     if (saved.integrity !== integrity || saved.digest !== digest) throw new Error("cached release changed; refusing it");
     return { root, digest };
   }
@@ -104,7 +153,7 @@ export async function stageRelease(version: string, integrity: string, run: RunC
     const install = await run([process.execPath, "install", "--ignore-scripts", "--cwd", temporary], { timeoutMs: 180_000 });
     if (install.code !== 0) throw new Error("package staging failed; installed runtime was not changed");
     const staged = join(temporary, "node_modules/@staix/agent-hub");
-    const digest = verifyPackage(staged, version);
+    const digest = verifyPackage(staged, version, { dependencyRoot: temporary });
     // Bun's lock records the registry integrity actually used, not a later metadata query.
     const lock = JSON.parse(readFileSync(join(temporary, "bun.lock"), "utf8").replace(/,\s*([}\]])/g, "$1"));
     const row = lock.packages?.["@staix/agent-hub"];

package/src/cli/upgrade-runtime.ts

@@ -8,7 +8,7 @@ import { ControlClient, PROTOCOL, RECOVERY_SOURCE_PROTOCOLS, readControl } from
 import { awaitStopped, inspectProject } from "../hub/lifecycle.ts";
 import type { Project } from "../hub/registry.ts";
 import { hubHome } from "../hub/project.ts";
-import { packageDigest, registryRelease, runCommand, stageRelease, verifyPackage, type RunCommand } from "./recovery-package.ts";
+import { packageDigest, preserveRuntimeDependencies, registryRelease, runCommand, stageRelease, verifyPackage, type RunCommand } from "./recovery-package.ts";
 import { inspectTerminals, closeTerminal, createTerminal, launcherOf, recordPath, waitForIdle, shellQuote, type SessionRef, type TerminalBinding, type TerminalRecoveryOptions } from "./terminal-recovery.ts";
 import { FinalRefusal, planFingerprint, registeredProjects, targetReadsWaivers, type Inspection, type PlannedProject, type ProjectProgress, type RecoveryDriver, type RecoveryOperation, type RecoveryPeer, type UpgradePlan } from "./upgrade.ts";
 import { readEvents } from "../hub/events.ts";
@@ -307,7 +307,7 @@ export function preserveSource(plan: UpgradePlan, home = hubHome()): string {
   const base = join(home, "releases");
   const dest = join(base, `source-${plan.sourceDigest}`);
   if (existsSync(dest)) {
-    if (packageDigest(dest) !== plan.sourceDigest) throw new Error("preserved source package changed");
+    if (packageDigest(dest, { ownDependencies: true }) !== plan.sourceDigest) throw new Error("preserved source package changed");
     return dest;
   }
   mkdirSync(base, { recursive: true, mode: 0o700 });
@@ -317,15 +317,16 @@ export function preserveSource(plan: UpgradePlan, home = hubHome()): string {
     for (const name of ["src", "plugins", "templates", ".claude-plugin", "package.json", "README.md", "LICENSE", "CHANGELOG.md"]) {
       cpSync(join(plan.sourceRoot, name), join(temporary, name), { recursive: true, dereference: false });
     }
-    if (packageDigest(temporary) !== plan.sourceDigest) throw new Error("source changed while being preserved");
+    preserveRuntimeDependencies(plan.sourceRoot, temporary);
+    if (packageDigest(temporary, { ownDependencies: true }) !== plan.sourceDigest) throw new Error("source changed while being preserved");
     renameSync(temporary, dest);
   } finally { rmSync(temporary, { recursive: true, force: true }); }
   return dest;
 }
 
-export function makeRecoveryDriver(run: RunCommand = runCommand): RecoveryDriver {
-  const now = () => Date.now();
-  const sleep = (ms: number) => Bun.sleep(ms);
+export function makeRecoveryDriver(run: RunCommand = runCommand, liveTestPeer?: string, clock?: Pick<RecoveryDriver, "now" | "sleep">): RecoveryDriver {
+  const now = clock?.now ?? (() => Date.now());
+  const sleep = clock?.sleep ?? ((ms: number) => Bun.sleep(ms));
   const env = (op: RecoveryOperation, project?: Project): NodeJS.ProcessEnv => {
     const value = { ...process.env };
     // Do not carry one project's gateway, auth overrides or unattended mode into another.
@@ -333,6 +334,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand): RecoveryDriver
       (project && /(?:_API_KEY|_ACCESS_TOKEN|_SECRET|_TOKEN)$/.test(key))) delete value[key];
     value.AGENTHUB_HOME = hubHome(); value.AGENTHUB_RECOVERY_OPERATION = op.id;
     value.AGENTHUB_UNATTENDED = "0";
+    if (liveTestPeer) value.AGENTHUB_PEER_ID = liveTestPeer;
     if (project) {
       value.AGENTHUB_PROJECT_DIR = project.root; value.AGENTHUB_STATE_DIR = project.stateDir;
       delete value.CODEX_HOME; delete value.CLAUDE_CONFIG_DIR;
@@ -345,7 +347,7 @@ export function makeRecoveryDriver(run: RunCommand = runCommand): RecoveryDriver
     return value;
   };
   const command = async (op: RecoveryOperation, args: string[], project?: Project) => {
-    const result = await run([process.execPath, join(op.targetRoot!, "src/cli/main.js"), ...(project ? ["--project", project.root] : []), ...args],
+    const result = await run([process.execPath, join(op.targetRoot!, "src/cli/main.js"), ...(project ? ["--project", project.root] : []), ...(liveTestPeer ? ["--live-test"] : []), ...args],
       { env: env(op, project), cwd: project?.root ?? op.plan.projects[0]!.project.root, timeoutMs: 180_000 });
     if (result.code !== 0) throw new Error(`target command ${args[0]} failed; inspect recovery state before retrying`);
     return result;
@@ -433,21 +435,56 @@ export function makeRecoveryDriver(run: RunCommand = runCommand): RecoveryDriver
     if (result.manualRequired) throw new Error(`${peer}: closing terminal ${retired.handle} of the stopped target's session was not verified; manual-required`);
     progress.terminals[key] = true; save();
   };
-  const attachedId = async (planned: PlannedProject, peer: string, op: RecoveryOperation): Promise<string> => {
-    for (const deadline = now() + RECONNECT_WAIT_MS; ;) {
-      const current = (await inspectRecovery(planned.project)).peers.find((p) => p.id === peer && p.state !== "offline");
-      const id = peer === "codex" ? current?.threadId : current?.sessionId;
-      if (id) return id;
-      if (now() >= deadline) throw new Error(`${peer}: the new session reported no id within ${RECONNECT_WAIT_MS / 1000} s; wait until it attaches first`);
-      await sleep(1000);
+  /** #414: an idle terminal is not an authenticated peer. Keep its receipt while waiting, including on resume. */
+  const awaitAttachment = async (planned: PlannedProject, progress: ProjectProgress, op: RecoveryOperation, binding: TerminalBinding, save: () => void, expectedSession: string | null = binding.sessionId): Promise<string> => {
+    const deadline = now() + RECONNECT_WAIT_MS;
+    let live: Inspection;
+    for (;;) {
+      live = await inspectRecovery(planned.project);
+      if (live.state === "running" && (live.instanceId !== progress.instanceId || live.version !== op.plan.version || live.recovery?.operationId !== op.id)) throw new Error(`${binding.peer}: target identity changed while awaiting attachment`);
+      const peer = live.peers.find((p) => p.id === binding.peer);
+      const session = binding.peer === "codex" ? peer?.threadId : peer?.sessionId;
+      const changed = !!session && expectedSession !== null && session !== expectedSession;
+      // #64: only the original zero-turn Claude may change identity without an operator choice. Re-read persistence
+      // at attachment, not at the plan or wait start; an already accepted replacement is bound to its own id.
+      const zeroTurn = changed && binding.peer === "claude" && (planned.terminals as TerminalBinding[]).some((p) => p.peer === "claude" && p.sessionId === binding.sessionId) && !claudeTranscriptExists(binding);
+      if (changed && !zeroTurn) throw new Error(`${binding.peer}: a different conversation attached while awaiting ${binding.sessionId}`);
+      if (now() > deadline) break;
+      if (live.state === "running" && peer && ["idle", "busy", "paused"].includes(peer.state) && session) {
+        if (zeroTurn) waiveRecoveryPeers(planned.project.stateDir, op.id, { claude: "zero-turn" });
+        return session;
+      }
+      if (now() >= deadline) break;
+      await sleep(Math.min(1000, deadline - now()));
     }
+    const terminal: NonNullable<ProjectProgress["attachmentTimeouts"]>[string]["terminal"] = { handle: binding.handle, incarnationId: binding.incarnationId, state: "unknown" };
+    try {
+      const result = await run([orcaExecutable(), "terminal", "show", "--terminal", binding.handle, "--json"], { timeoutMs: 3000 });
+      const value = JSON.parse(result.stdout), shown = value.result?.terminal;
+      if (result.code === 0 && value.ok === true && shown?.handle === binding.handle && shown.incarnationId === binding.incarnationId) {
+        if (["idle", "busy", "exited"].includes(shown.state)) terminal.state = shown.state;
+        if (typeof shown.connected === "boolean") terminal.connected = shown.connected;
+        if (typeof shown.orphaned === "boolean") terminal.orphaned = shown.orphaned;
+      }
+    } catch { /* unavailable metadata stays unknown; raw output/errors never enter the receipt */ }
+    const peer = live.peers.find((p) => p.id === binding.peer);
+    const session = binding.peer === "codex" ? peer?.threadId : peer?.sessionId;
+    (progress.attachmentTimeouts ??= {})[binding.peer] = { at: now(), terminal,
+      hub: { state: live.state, ...(live.instanceId ? { instanceId: live.instanceId } : {}), ...(peer ? { peerState: peer.state } : {}), ...(session ? { sessionId: session } : {}) },
+      lastHubConnectAttempt: "unknown" };
+    save();
+    throw new Error(`${binding.peer}: attachment not verified within ${RECONNECT_WAIT_MS / 1000} s; terminal ${binding.handle} retained; resume after it attaches (native-start diagnostic recorded; last hub connect attempt unknown)`);
   };
   return {
     now, sleep, inspect: inspectRecovery,
     stage: async (op) => {
-      if (packageDigest(op.sourceRoot) !== op.plan.sourceDigest) throw new FinalRefusal("preserved source changed");
-      const target = op.plan.kind === "restart" ? { root: op.sourceRoot, digest: verifyPackage(op.sourceRoot, op.plan.version) }
+      if (packageDigest(op.sourceRoot, { ownDependencies: true }) !== op.plan.sourceDigest) throw new FinalRefusal("preserved source changed");
+      const target = op.plan.kind === "restart" ? { root: op.sourceRoot, digest: verifyPackage(op.sourceRoot, op.plan.version, { ownDependencies: true }) }
         : await stageRelease(op.plan.version, op.plan.integrity!, run);
+      const identityPath = join(target.root, "src/cli/identity.ts");
+      if (liveTestPeer && (!existsSync(identityPath) || !readFileSync(identityPath, "utf8").includes("export const LIVE_TEST_SUPPORTED = true;"))) {
+        throw new FinalRefusal("target does not support live-test delegation; choose a supporting target before retrying; runtimes unchanged");
+      }
       // #215: the protocol and waiver checks are properties of these bytes. Once they passed (the runner recorded the
       // digest), a resume does not check again, so a transient probe failure cannot refuse an operation for good;
       // changed bytes are the runner's final "staged target changed".
@@ -592,7 +629,10 @@ export function makeRecoveryDriver(run: RunCommand = runCommand): RecoveryDriver
             : `${original.peer}: its launcher in terminal ${evidence.handle} is running but no ${original.peer} session ${evidence.attached ? "with an id " : ""}attached yet; no terminal was created; wait until it attaches, or end it and close terminal ${evidence.handle} first`);
         const receipt = progress.terminals[key];
         if (receipt && receipt !== "pending" && receipt !== "failed") {
-          progress.terminals[key] = await revalidateTerminal(planned, progress, receipt as TerminalBinding, true); save();
+          const binding = receipt as TerminalBinding;
+          const sessionId = await awaitAttachment(planned, progress, op, binding, save, fresh() && binding.sessionId === original.sessionId ? null : binding.sessionId);
+          progress.terminals[key] = { ...binding, sessionId }; save();
+          progress.terminals[key] = await revalidateTerminal(planned, progress, progress.terminals[key] as TerminalBinding, true); save();
           continue;
         }
         // #215: the pending row of the receipt table, used wherever a pending launch meets an attached session.
@@ -669,7 +709,9 @@ export function makeRecoveryDriver(run: RunCommand = runCommand): RecoveryDriver
           throw new Error(`${original.peer}: original session restoration needs manual verification${restored.blockers[0] ? ` (${restored.blockers[0].message})` : ""}; wait until it attaches, or end that launch and close its terminal${handle ? ` ${handle}` : ""} first`);
         }
         // The daemon's id is authoritative: a fresh session is recorded under the id it reports once attached.
-        progress.terminals[key] = fresh() ? { ...restored.newBinding, sessionId: await attachedId(planned, original.peer, op) } : restored.newBinding; save();
+        progress.terminals[key] = restored.newBinding; save();
+        const sessionId = await awaitAttachment(planned, progress, op, restored.newBinding, save, fresh() ? null : restored.newBinding.sessionId);
+        progress.terminals[key] = { ...restored.newBinding, sessionId }; save();
       }
       if (group === "claude") for (const id of planned.reconnectOnly ?? []) {
         // #206: nothing is launched for an unmanaged session; its plugin reconnects by itself, within a bound.

package/src/cli/upgrade.ts

@@ -53,6 +53,14 @@ export interface ProjectProgress {
   phase: "pending" | "prepared" | "stopped" | "started" | "peers-restored" | "verified";
   instanceId?: string;
   terminals: Record<string, unknown>;
+  /** #414: last bounded native-attachment timeout, metadata only; never terminal output or task text. */
+  attachmentTimeouts?: Record<string, {
+    at: number;
+    terminal: { handle: string; incarnationId: string; state: "unknown" | "idle" | "busy" | "exited"; connected?: boolean; orphaned?: boolean };
+    hub: { state: string; instanceId?: string; peerState?: string; sessionId?: string };
+    /** Client-side attempts are not recorded by the hub; an offline peer is not evidence of an attempt. */
+    lastHubConnectAttempt: "unknown";
+  }>;
   releaseRequested?: boolean;
   /** #215: peers the operator moved to a fresh session, with the session or thread id whose continuity is lost. */
   fresh?: Record<string, { lost: string; reason: string; at: number }>;