@staix/agent-mem 0.0.0-stage → 0.1.0

package/src/memory/commands.ts

@@ -0,0 +1,203 @@
+import { extractNodes, GOAL_STATES, KINDS, MemoryStore, setMachineLabel, type GoalState, type GoalView, type Kind, type Tier, type View } from "./store.ts";
+import { syncMemory, type SyncOptions } from "./sync.ts";
+import { importClaudeMem } from "./import.ts";
+import { memoryProjectKey, projectChain } from "./project.ts";
+
+export interface MemoryCommandOptions {
+  store?: MemoryStore;
+  sync?: Omit<SyncOptions, "remote">;
+  open: () => MemoryStore;
+  readable: (notes: View[]) => View[];
+  importPolicy: () => (text: string) => boolean;
+}
+export interface GoalCommandOptions {
+  store?: MemoryStore;
+  link?: (goal: string, task: string) => Promise<string>;
+  open: () => MemoryStore;
+  clean: (title: string, milestones: string[], project: string) => boolean;
+}
+
+/**
+ * #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];
+}
+
+export async function rawMemoryCommand(args: string[], cwd: string, opts: MemoryCommandOptions): 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";
+  const store = opts.store ?? opts.open();
+  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 = opts.readable(all), 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 (!opts.readable([v]).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 isPii = opts.importPolicy();
+        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, ...(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);
+    }
+  } 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";
+}
+
+/**
+ * #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 rawGoalCommand(args: string[], cwd: string, opts: GoalCommandOptions): 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 ?? opts.open();
+  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)`);
+  const clean = (title: string, milestones: string[], of = project) => opts.clean(title, milestones, of);
+  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(); }
+}

package/src/memory/home.ts

@@ -0,0 +1,10 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { canonicalPath } from "./platform.ts";
+
+/** Core memory directory. AGENTHUB_HOME retains its historical parent-home meaning. */
+export function memoryHome(env: NodeJS.ProcessEnv = process.env): string {
+  const own = env.AMEM_HOME?.trim();
+  if (own) return canonicalPath(own);
+  return join(canonicalPath(env.AGENTHUB_HOME?.trim() || join(homedir(), ".agenthub")), "memory");
+}

package/src/memory/import.ts

@@ -0,0 +1,90 @@
+import { Database } from "bun:sqlite";
+import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { createHash, randomBytes } from "node:crypto";
+import { realPath } from "./platform.ts";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { KINDS, looksSecret, type Kind, type MemoryStore } from "./store.ts";
+
+/** The claude-mem store is another program's: opened read-only, never written, its locks waited on briefly. */
+export const CLAUDE_MEM_BUSY_TIMEOUT_MS = 3000;
+/** Titles `ahub ask --remember` gives a model's answer (ask.ts ASK_NOTE_TITLE): never imported as a finding. */
+const MODEL_ANSWER = "ahub ask (model answer)";
+
+export interface ImportResult { read: number; added: number; skipped: { model: number; pii: number; secret: number }; more: boolean; cursor: number }
+
+/** Machine-local progress is disposable; malformed/unreadable state simply replays the idempotent import. */
+function readCursors(file: string): Record<string, number> {
+  try {
+    const value: unknown = JSON.parse(readFileSync(file, "utf8"));
+    if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+    return Object.fromEntries(Object.entries(value).filter(([, id]) => Number.isSafeInteger(id) && id >= 0));
+  } catch { return {}; }
+}
+function writeCursor(file: string, key: string, cursor: number, log: (line: string) => void): void {
+  const temp = `${file}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+  try {
+    writeFileSync(temp, JSON.stringify({ ...readCursors(file), [key]: cursor }) + "\n", { mode: 0o600, flag: "wx" });
+    renameSync(temp, file);
+  } catch { log("claude-mem import progress could not be saved; the next run may replay handled rows"); }
+  finally { try { rmSync(temp, { force: true }); } catch { /* disposable progress */ } }
+}
+
+/**
+ * #258 phase 3: copy the hub's own notes from claude-mem (observations whose metadata names a `peer`: `hub_remember`
+ * and the hub's task notes) into long-term hub memory as `source: claude-mem` under the hub memory key `project`, for
+ * the projects in `chain` (claude-mem files them under the repository's basename). Model answers, PII-pattern text and secret-looking text are skipped.
+ * Idempotent: an observation always maps to the same entry.
+ */
+export function importClaudeMem(store: MemoryStore, opts: { project: string; chain: string[]; isPii: (text: string) => boolean; nodes?: (text: string) => string[]; db?: string; limit?: number; restart?: boolean; log?: (line: string) => void }): ImportResult {
+  const file = opts.db ?? join(homedir(), ".claude-mem", "claude-mem.db");
+  if (!existsSync(file)) throw new Error(`no claude-mem store at ${file}`);
+  const limit = opts.limit ?? 10_000;
+  if (!Number.isSafeInteger(limit) || limit <= 0) throw new Error("--limit takes a positive integer");
+  const state = join(store.dir, "import-state.json");
+  const name = opts.chain.at(-1) ?? "";
+  const key = createHash("sha256").update(JSON.stringify([realPath(file), name, opts.project])).digest("hex");
+  let cursor = opts.restart ? 0 : readCursors(state)[key] ?? 0;
+  const db = new Database(file, { readonly: true });
+  db.run(`PRAGMA busy_timeout = ${CLAUDE_MEM_BUSY_TIMEOUT_MS}`);
+  const result: ImportResult = { read: 0, added: 0, skipped: { model: 0, pii: 0, secret: 0 }, more: false, cursor };
+  try {
+    const max = db.query("SELECT MAX(id) AS id FROM observations WHERE project = ? AND metadata LIKE '%\"peer\"%'").get(name) as { id: number | null };
+    if ((max.id ?? 0) < cursor) cursor = 0;
+    const rows = db.query("SELECT id, project, title, text, narrative, created_at_epoch, metadata FROM observations WHERE project = ? AND id > ? AND metadata LIKE '%\"peer\"%' ORDER BY id LIMIT ?")
+      .all(name, cursor, limit) as { id: number; project: string | null; title: string | null; text: string | null; narrative: string | null; created_at_epoch: number | null; metadata: string | null }[];
+    // The hub files its claude-mem notes under the repository's own name (the chain's last); the names above it are other
+    // projects (a superproject) whose notes and privacy policy are not this one's. ponytail: claude-mem keys projects by
+    // basename, so two unrelated repositories with one name still share it.
+    const project = opts.project;
+    result.read = rows.length;
+    result.more = rows.length === limit;
+    const handle = (r: typeof rows[number]) => {
+      let meta: Record<string, unknown>;
+      try { meta = JSON.parse(r.metadata ?? "{}"); } catch { return; }
+      if (!meta || typeof meta !== "object" || typeof meta.peer !== "string" || !meta.peer) return;
+      const title = r.title ?? "", text = (r.text ?? r.narrative ?? "").trim();
+      if (!text) return;
+      if (meta.source === "ahub ask" || title.startsWith(MODEL_ANSWER)) { result.skipped.model++; return; }
+      if (opts.isPii(`${title}\n${text}`)) { result.skipped.pii++; return; }
+      if (looksSecret(`${title}\n${text}`)) { result.skipped.secret++; return; }
+      const kind: Kind = KINDS.includes(meta.kind as Kind) ? meta.kind as Kind : "finding";
+      const at = new Date(r.created_at_epoch ?? 0).toISOString();
+      const { added } = store.importNote({ op: "note", project, scope: "project", tier: "long", kind, peer: meta.peer.slice(0, 32), ...(title ? { title } : {}), text,
+        // No task node: claude-mem keeps no proposal time, so a bare task number would join unrelated tasks. The text's
+        // own paths and symbols place the note in the graph.
+        about: opts.nodes?.(`${title}\n${text}`) ?? [], source: "claude-mem" }, at);
+      if (added) result.added++;
+    };
+    for (const row of rows) {
+      handle(row);
+      cursor = row.id; // only fully handled rows, including every skip
+    }
+  } finally {
+    db.close();
+    result.cursor = cursor;
+    writeCursor(state, key, cursor, opts.log ?? console.error);
+  }
+  store.refresh();
+  return result;
+}

package/src/memory/platform.ts

@@ -0,0 +1,131 @@
+// Single-source platform helpers. Hub, local and Pi modules re-export these functions unchanged.
+import { realpathSync } from "node:fs";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import { spawnSync, execFileSync, type SpawnSyncOptionsWithStringEncoding, type SpawnSyncReturns } from "node:child_process";
+import { createHash } from "node:crypto";
+
+const canonical = (path: string): string => {
+  const absolute = resolve(path);
+  try {
+    return realpathSync(absolute);
+  } catch {
+    const parent = dirname(absolute);
+    return parent === absolute ? absolute : join(canonical(parent), basename(absolute));
+  }
+};
+
+export function canonicalPath(path: string): string {
+  return canonical(path);
+}
+
+/**
+ * realpathSync, except that Bun (1.3.14, and 1.4.2 still: #121) throws ENOENT for an existing path containing a
+ * backslash (issue #26). Such a path goes to the system realpath, which handles it and returns every component as
+ * stored on disk: guardPath checks names, and on a case-insensitive disk `.GIT/config` or `id_rſa` would otherwise
+ * pass for another file. A missing path or a dangling symlink still throws, which guardPath relies on. Other paths take
+ * realpathSync's answer unchanged.
+ */
+export function realPath(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch (error) {
+    if (!resolve(path).includes("\\")) throw error; // a relative path can sit under a backslash directory too
+    // The path as given: resolve() would fold a `..` after a symlink by text. GNU realpath accepts a dangling last
+    // component unless told -e; the BSD one on macOS refuses it by default.
+    const argv = process.platform === "darwin" ? ["/bin/realpath", "--", path] : ["realpath", "-e", "--", path];
+    const r = spawnSync(argv[0]!, argv.slice(1), { encoding: "utf8" });
+    if (r.status !== 0 || !r.stdout.endsWith("\n")) throw error;
+    return r.stdout.slice(0, -1);
+  }
+}
+
+/** One denylist for core extraction, hub path guards, sandbox rules and capture. */
+// `.agenthub/archive` holds reset state directories, including task text and PII.
+export const DENY_SEGMENTS = [".maru/secrets", ".agenthub/state", ".agenthub/archive"];
+/** Regex sources, matched against a file's basename. */
+export const DENY_NAMES = ["^\\.env", "\\.pem$", "\\.key$", "^id_rsa", "^id_ed25519", "^credentials(\\.|$)", "^auth\\.json$", "^\\.netrc$", "^\\.npmrc$", "^\\.pypirc$"];
+
+const hasSegment = (rel: string, seg: string) => `/${rel}/`.includes(`/${seg}/`);
+
+/** True when a path names something the worker must never read, write or report. `extra`: substrings from `local.deny`. */
+export function isDenied(path: string, extra: string[] = []): boolean {
+  const norm = path.split(sep).join("/");
+  return DENY_SEGMENTS.some((s) => hasSegment(norm, s)) || DENY_NAMES.some((re) => new RegExp(re).test(basename(norm))) || extra.some((e) => e && norm.includes(e));
+}
+
+/**
+ * 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 memoryGitArgv = (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 memoryGitEnv = (env: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv => ({ ...env, GIT_TERMINAL_PROMPT: "0" });
+
+/** spawnSync form of the same call: the env option is merged with memoryGitEnv, everything else passes through. */
+export function memoryGitSync(args: string[], options: SpawnSyncOptionsWithStringEncoding): SpawnSyncReturns<string> {
+  const argv = memoryGitArgv(args);
+  return spawnSync(argv[0]!, argv.slice(1), { ...options, env: memoryGitEnv(options.env ?? process.env) });
+}
+
+/**
+ * The one process-identity contract behind the Pi owner claim, every later liveness
+ * re-inspection, the terminal-recovery launcher signature and any other hub identity
+ * hash: pid plus the `ps` rendering of its start time and command. `lstart` follows
+ * the reader's TZ and locale, so the read pins LC_ALL=C and TZ=UTC, the same contract
+ * as `processTable` in src/hub/child-process.ts. Without the pin a writer and a reader
+ * in different environments hash different strings for the same process and the valid
+ * owner is refused (#174, #177). Only the `ps` invocation is pinned; the user's own
+ * environment is untouched. Node APIs only: the extension runs inside Pi, not Bun.
+ */
+export function processSignature(pid: number): string | undefined {
+  try {
+    const text = execFileSync("ps", ["-p", String(pid), "-o", "lstart=,comm="], { encoding: "utf8", env: { ...process.env, LC_ALL: "C", TZ: "UTC" } }).trim();
+    return text ? createHash("sha256").update(text).digest("hex") : undefined;
+  } catch { return undefined; }
+}
+
+export type Liveness = "live" | "gone" | "unknown";
+
+/**
+ * #226: the one ownership check behind every recorded pid (hub manifest, registry claim, recovery runner, manager
+ * owner, launcher records). With a recorded `signature` the identity decides: equal is live, different is gone (the
+ * pid was reused, after a reboot for example, also by a process we may not signal), and a pid that exists but whose
+ * identity cannot be read is unknown. Without one (records written by 0.12.20 and older) the pid probe answers as it
+ * always did: live, gone on ESRCH, unknown otherwise. Unknown is never gone.
+ */
+// ponytail: `ps lstart` is derived from boot time plus the process's age; a wall-clock step on Linux can change it for a
+// live process, which then reads as gone (a second hub could take its claim). Upgrade path: a boot-id or start-tick
+// (Linux /proc/<pid>/stat field 22) component in the signature.
+export function processLiveness(pid: unknown, signature?: string | null, identity: (pid: number) => string | undefined = processSignature): Liveness {
+  if (typeof pid !== "number" || !Number.isSafeInteger(pid) || pid <= 0) return "unknown";
+  if (signature) {
+    let current: string | undefined;
+    try { current = identity(pid); } catch { /* unreadable: the pid probe below decides between gone and unknown */ }
+    if (current) return current === signature ? "live" : "gone";
+  }
+  try { process.kill(pid, 0); return signature ? "unknown" : "live"; }
+  catch (error) { return (error as NodeJS.ErrnoException).code === "ESRCH" ? "gone" : "unknown"; }
+}

package/src/memory/project.ts

@@ -0,0 +1,72 @@
+import { createHash } from "node:crypto";
+import { basename, dirname, resolve } from "node:path";
+import { readFileSync } from "node:fs";
+import { memoryGitSync, realPath } from "./platform.ts";
+
+/** Project names from the outermost superproject down to this repo. */
+export function projectChain(cwd: string): string[] {
+  const git = (dir: string, arg: string) => memoryGitSync(["-C", dir, "rev-parse", arg], { encoding: "utf8" }).stdout?.trim() ?? "";
+  const top = git(cwd, "--show-toplevel");
+  if (!top) return [basename(cwd)];
+
+  // claude-mem's native identity for a worktree is [parent, parent/worktree].
+  // The worktree's .git file points into <parent>/.git/worktrees/<name>; the
+  // ordinary superproject walk below remains unchanged for repos and submodules.
+  const gitFile = resolve(top, ".git");
+  try {
+    const match = readFileSync(gitFile, "utf8").trim().match(/^gitdir:\s*(.+)$/i);
+    if (match) {
+      const gitDir = resolve(top, match[1]!);
+      if (/[/\\]\.git[/\\]worktrees[/\\][^/\\]+$/.test(gitDir)) {
+        const parentRoot = dirname(dirname(dirname(gitDir)));
+        const parent = projectChain(parentRoot);
+        const parentName = basename(parentRoot);
+        return [...parent, `${parentName}/${basename(top)}`];
+      }
+    }
+  } catch {
+    // A missing or unreadable .git file falls through to git's normal chain.
+  }
+
+  const chain: string[] = [];
+  for (let dir = top; dir && chain.length < 8; dir = git(dir, "--show-superproject-working-tree")) {
+    chain.unshift(basename(dir));
+  }
+  return chain.length ? chain : [basename(cwd)];
+}
+
+/**
+ * #258: the name hub memory files a project's entries under. The project's `origin` remote, normalized to host and
+ * path (`github.com/owner/repo`), is the same on every machine and unique; without one, the git chain plus a hash of
+ * the directory keeps two unrelated repositories that share a name apart (that key is this machine's only).
+ */
+export function memoryProjectKey(cwd: string): string {
+  const url = memoryGitSync(["-C", cwd, "remote", "get-url", "origin"], { encoding: "utf8" }).stdout?.trim() ?? "";
+  // A URL's default port is not part of the repository (`ssh://git@github.com:22/o/r` is `github.com/o/r`); any other
+  // port is, since another service may run there. An scp-style `host:path` has no port.
+  const u = /^([a-z+]+):\/\/(?:[^@/]+@)?(\[[^\]/]+\]|[^/:]+)(?::(\d*))?\/(.+?)(?:\.git)?\/?$/i.exec(url); // an IPv6 host is bracketed
+  const defaults: Record<string, string> = { ssh: "22", "git+ssh": "22", "ssh+git": "22", https: "443", http: "80", git: "9418" };
+  // A URL's path is absolute (`ssh://h/team/r` is /team/r) unless it starts with `~`; an scp-style path is relative to the
+  // remote home (`h:team/r` is ~/team/r) unless it starts with `/`. Two different repositories on a self-hosted server.
+  const scp = u || url.includes("://") ? null : /^(?:[^@/]+@)?(\[[^\]/]+\]|[^/:]+):(.+?)(?:\.git)?\/?$/.exec(url); // a file:// remote has no host; an IPv6 host is bracketed
+  const m = u ? [!u[3] || u[3] === defaults[u[1]!.toLowerCase()] ? u[2]! : `${u[2]}:${u[3]}`, u[4]!] as const
+    : scp ? [scp[1]!, scp[2]!.startsWith("/") ? scp[2]!.replace(/^\/+/, "") : scp[2]!.startsWith("~") ? scp[2]! : `~/${scp[2]}`] as const : undefined;
+  if (m && m[1]) {
+    const host = m[0].toLowerCase();
+    // GitHub serves one repository under every form, and its owner and repository names ignore case.
+    return host === "github.com" ? `${host}/${m[1].replace(/^~\/?/, "").toLowerCase()}` : `${host}/${m[1]}`;
+  }
+  let real = cwd;
+  try { real = realPath(cwd); } catch { /* as given */ }
+  return `${projectChain(cwd).join("/")}@${createHash("sha256").update(real).digest("hex").slice(0, 8)}`;
+}
+
+/**
+ * Every path-like word of a text (`dir/file`, `file.ext`), whether or not it exists or a denylist hides it from the
+ * graph: what a private-path policy is checked against.
+ */
+export const pathCandidates = (text: string): string[] => [...new Set(text.normalize("NFC").match(/\/?[\p{L}\p{M}\p{N}_.~-]+(?:\/[\p{L}\p{M}\p{N}_.~-]+)+|[\p{L}\p{M}\p{N}_-]+\.\p{L}[\p{L}\p{M}\p{N}_]{0,9}/gu) ?? [])]; // any script, combining marks included; an absolute path keeps its slash
+
+/** The file a graph node names: `path:<p>` and `symbol:<name>@<p>`; nothing for other nodes. */
+export const nodePath = (n: string): string | undefined => n.startsWith("path:") ? n.slice(5) : n.startsWith("symbol:") && n.includes("@") ? n.slice(n.lastIndexOf("@") + 1) : undefined;
+