@staix/agent-mem 0.7.0 → 0.9.1

package/src/memory/store.ts

@@ -15,10 +15,10 @@ import { assertCuratedShardPaths, ensureShardDescriptor, readShardDescriptor, re
 import { readCaptureConfig, type CaptureRow } from "./capture.ts";
 import { assertSharedV1Op } from "./ops-contract.ts";
 import { generationDescriptor, generationDir, fsyncDirectory, canonicalJSON, hashJSON, readProfileJSON, resolveProfile, writeProfileJSON, readSelector, type BoundProfile, type ProfileInput, validateVaultLinkRow, vaultLinkId, type VaultLink, type VaultLinkRow } from "./generation.ts";
-import { GenerationIndex, explicitExpirySnapshot, GENERATION_TABLES } from "./generation-index.ts";
+import { GenerationIndex, coalesceGenerationSource, explicitExpirySnapshot, GENERATION_TABLES } from "./generation-index.ts";
 import { legacyEntries, readLegacySnapshot, SegmentReader, type LegacyCheckpoint } from "./bridge.ts";
 import { readMigrationSources } from "./migrate.ts";
-import type { PruneStorePort } from "./prune.ts";
+import type { PruneSourceRow, PruneStorePort } from "./prune.ts";
 import { isDeepStrictEqual } from "node:util";
 import { registerReaderLease } from "./reader-lease.ts";
 
@@ -189,6 +189,8 @@ export interface StoreOptions { home?: string; memoryDir?: string; ttlMs?: numbe
   lifecycle?: "enforce" | "ignore";
   /** #27: read the `aliases` keys' curated rows as part of the `canonical` project (CLI and MCP only); the library default reads the raw key. Rows are presented under `canonical`. */
   reconcile?: { canonical: string; aliases: readonly string[] };
+  /** Person-only project import may initialize configured alias shards; read-only reconciliation still never creates them. */
+  createAliases?: boolean;
 }
 
 const MIGRATION_BOOTSTRAP = Symbol("migration index bootstrap");
@@ -382,6 +384,37 @@ export class MemoryStore {
       return work(entries);
     });
   }
+  /**
+   * Exact original transport placement; View.local describes tier, not a verified publication choice.
+   * ponytail: a legacy (shared-v1) home reads its whole snapshot under a 32 MiB byte budget on every call and refuses past it, so consolidation and its acceptance are unavailable for a legacy home that large. Upgrade: migrate the home to a generation (its placements come from the indexed `generation_rows`), or keep a placement index for legacy homes.
+   */
+  entryPlacements(ids: readonly string[], project: string): ReadonlyMap<string, "local" | "synced"> {
+    if (!ids.length || ids.length > 256 || new Set(ids).size !== ids.length || ids.some(id => !/^[a-f0-9]{32}$/.test(id)) || !project.trim()) throw Error("invalid placement batch");
+    return this.withStoreFences(stores => {
+      const wanted = new Set(ids), found = new Map<string, "local" | "synced">(), reader = new SegmentReader(32 * 1024 * 1024);
+      const add = (id: string, placement: "local" | "synced") => { if (wanted.has(id) && (placement === "synced" || !found.has(id))) found.set(id, placement); };
+      assertProjectActive(this.profile.home, project);
+      for (const store of stores) {
+        if (store.generationIndex) {
+          store.generationIndex.refresh(0, reader);
+          const rows = store.db.query("SELECT id,local FROM generation_rows WHERE id IN (SELECT value FROM json_each(?))").all(JSON.stringify(ids)) as { id: string; local: number }[];
+          for (const row of rows) add(row.id, row.local ? "local" : "synced");
+        } else {
+          // Strict bounded verification includes locations, never guesses transport from tier or View.local.
+          const presence = new Map<string, PruneSourceRow>();
+          for (const segment of readLegacySnapshot(store.dir, { reader })) for (const row of legacyEntries([segment], { strict: true })) {
+            if (row.op === "note" && wanted.has(row.id)) {
+              const located = coalesceGenerationSource(presence.get(row.id), row, segment);
+              presence.set(row.id, located); add(row.id, located.placement);
+            }
+          }
+          store.ensureFresh(); // Refresh only after the strict bounded source read succeeds.
+        }
+      }
+      for (const id of ids) { const view = this.get(id, project); if (!view || view.id !== id || view.project !== project || !found.has(id)) throw Error("entry placement unavailable"); }
+      return found;
+    });
+  }
   private withStoreFences<T>(work: (stores: readonly MemoryStore[]) => T): T {
     const unique = new Map<string, MemoryStore>();
     for (const store of this.readStores()) { const dir = realPath(store.dir); if (!unique.has(dir)) unique.set(dir, store); }
@@ -461,14 +494,19 @@ export class MemoryStore {
    * An entry from another store with its own time (`ahub memory import claude-mem`): the same source row always gives
    * the same id, so a second import writes nothing. Returns the id and whether it was new.
    */
-  importNote(n: NoteInput, at: string): { id: string; added: boolean } {
+  importNote(n: NoteInput, at: string, identity: { machine?: string; expectedId?: string } = {}): { id: string; added: boolean } {
     if (this.bootstrapOnly) throw new Error("migration bootstrap cannot import memory");
-    if (this.userOverlay && n.scope === "shared") return this.userOverlay.importNote(n, at);
+    if (this.userOverlay && n.scope === "shared") return this.userOverlay.importNote(n, at, identity);
+    if (this.profile.sharded && !this.profile.shardUser && n.scope === "project" && n.project !== this.profile.shardKey) {
+      const owner = this.aliasStores.find(store => store.profile.shardKey === n.project);
+      if (owner) return owner.importNote(n, at, identity);
+    }
     if (this.profile.sharded && (this.profile.shardUser ? n.scope !== "shared" : n.scope !== "project" || n.project !== this.profile.shardKey)) throw new Error("entry does not belong to this curated shard");
     assertSharedV1Op(n.op);
-    // A fixed machine: the same observation imported on two machines is one entry once they sync.
-    const body = { schema: MEMORY_SCHEMA, at, machine: "claude-mem", ...n, text: stripPrivateSpans(n.text).slice(0, MAX_TEXT), ...(n.title ? { title: stripPrivateSpans(n.title).slice(0, MAX_TITLE) } : {}) } as Omit<Entry, "id">;
+    // A fixed machine: the same observation imported on two machines is one entry once they sync. A project import preserves the exported identity instead.
+    const body = { schema: MEMORY_SCHEMA, at, machine: identity.machine ?? "claude-mem", ...n, text: stripPrivateSpans(n.text).slice(0, MAX_TEXT), ...(n.title ? { title: stripPrivateSpans(n.title).slice(0, MAX_TITLE) } : {}) } as Omit<Entry, "id">;
     const id = entryId(body);
+    if (identity.expectedId !== undefined && identity.expectedId !== id) throw new Error("project import entry identity changed");
     return this.withMutation(() => {
       this.generationIndex?.assertAppendable(n.tier === "short", this.machine.id);
       // The source tuple also recognizes legacy ids whose nodes depended on the checkout or extractor version.
@@ -975,6 +1013,21 @@ export class MemoryStore {
       .sort((a, b) => b.at.localeCompare(a.at) || a.id.localeCompare(b.id)).slice(0, f.limit ?? 200);
   }
 
+  /** The verified authored log rows behind the current export selection, including legacy absent/null optional fields. */
+  portableNotes(project: string): NoteEntry[] {
+    const selected = this.list({ project, limit: Number.MAX_SAFE_INTEGER, includeSuperseded: true });
+    const wanted = new Set(selected.map(view => view.id)), authored = new Map<string, NoteEntry>();
+    for (const store of this.readStores()) {
+      const rows = store.generationIndex ? store.generationIndex.snapshot(false).rows.map(item => item.row) : legacyEntries(readLegacySnapshot(store.dir));
+      for (const row of rows) if (row.op === "note" && wanted.has(row.id) && !authored.has(row.id)) authored.set(row.id, row);
+    }
+    return selected.map(view => {
+      const row = authored.get(view.id);
+      if (!row) throw new Error("exported note's authored row is unavailable");
+      return row;
+    });
+  }
+
   /** Exact-project body pages for policy-aware callers. Relations still fold over complete metadata. */
   readPage(window: ReadWindow & { query?: string; includeSuperseded?: boolean }): { rows: View[]; next?: ReadRef } {
     this.ensureFresh(); this.prune();
@@ -1507,12 +1560,13 @@ export function openShardStore(opts: StoreOptions & { project?: string; user?: b
   const userOverlay = opts.user === true ? undefined : openShardStore({ ...plain, project: undefined, user: true });
   const aliasStores: MemoryStore[] = [];
   try {
-    // #27: an aliased key that has a shard of its own is read beside this one; one that never had a shard has nothing to read and is not created.
+    // #27: read-only reconciliation never creates an alias shard. A person-only project import explicitly can.
     if (opts.user !== true && reconcile && reconcile.canonical === opts.project) {
       for (const alias of reconcile.aliases) {
-        if (alias === opts.project || !existsSync(join(shardDir(home, alias), "generation.json"))) continue;
+        if (alias === opts.project || !opts.createAliases && !existsSync(join(shardDir(home, alias), "generation.json"))) continue;
         assertCuratedShardPaths(home, { project: alias });
-        aliasStores.push(new MemoryStore(plain, { token: MIGRATION_BOOTSTRAP, profile: resolveShardProfile(home, { project: alias }), authoring: true }));
+        aliasStores.push(opts.createAliases ? openShardStore({ ...plain, project: alias })
+          : new MemoryStore(plain, { token: MIGRATION_BOOTSTRAP, profile: resolveShardProfile(home, { project: alias }), authoring: true }));
       }
     }
     return new MemoryStore(opts, { token: MIGRATION_BOOTSTRAP, profile, authoring: true, userOverlay, aliasStores });

package/src/memory/sync-cadence.ts

@@ -61,14 +61,24 @@ export const SYNC_IF_DUE_DEADLINE_MS = 30_000;
  */
 export const STOP_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT"] as const;
 export type StopCause = "person" | "deadline";
-export function stopSignal(ms: number, emitter: { on(name: string, fn: () => void): unknown; off(name: string, fn: () => void): unknown }, names: readonly string[] = STOP_SIGNALS): { signal: AbortSignal; dispose: () => void; cause: () => StopCause | undefined } {
+export function stopSignal(ms: number, emitter: { on(name: string, fn: () => void): unknown; off(name: string, fn: () => void): unknown }, names: readonly string[] = STOP_SIGNALS): { signal: AbortSignal; dispose: () => void; cause: () => StopCause | undefined; signalName: () => string | undefined } {
   const controller = new AbortController(), deadline = AbortSignal.timeout(ms);
-  let cause: StopCause | undefined;
+  let cause: StopCause | undefined, named: string | undefined;
   // The first thing that ends the run is its cause: a person who closes the terminal after the deadline already fired did not stop it.
-  const stop = () => { cause ??= "person"; controller.abort(); };
+  const handlers = names.map(name => [name, () => { if (cause === undefined) { cause = "person"; named = name; } controller.abort(); }] as const);
   deadline.addEventListener("abort", () => { cause ??= "deadline"; }, { once: true });
-  for (const name of names) emitter.on(name, stop);
-  return { signal: AbortSignal.any([controller.signal, deadline]), dispose: () => { for (const name of names) emitter.off(name, stop); }, cause: () => cause };
+  for (const [name, handler] of handlers) emitter.on(name, handler);
+  return { signal: AbortSignal.any([controller.signal, deadline]), dispose: () => { for (const [name, handler] of handlers) emitter.off(name, handler); }, cause: () => cause, signalName: () => named };
+}
+
+/**
+ * End this process the way the signal would have, once amem's own handlers are removed (a handler suppresses the default action, so a run a person ended would otherwise exit 1
+ * instead of 130, 143, 129). SIGQUIT's default action is a core dump, and Bun honours it: a re-raised SIGQUIT on Linux writes a core file the size of the process image (measured
+ * 5.9 GB, taking seconds, in a container with `ulimit -c unlimited`) while the shell waits for the exit, so it exits with the status that death would have had (128 + 3) at once.
+ */
+export function endLikeSignal(name: string): void {
+  if (name === "SIGQUIT") process.exit(128 + 3);
+  process.kill(process.pid, name as NodeJS.Signals);
 }
 
 /**

package/src/memory/sync.ts

@@ -45,13 +45,19 @@ async function git(dir: string, args: string[], signal?: AbortSignal, ms = STEP_
   const unregister = group ? register(p.pid) : () => {};
   // SIGTERM first, so git removes its lock files; SIGKILL only if it is still there after a grace period.
   let hard: ReturnType<typeof setTimeout> | undefined;
-  const kill = () => { send("SIGTERM"); hard ??= setTimeout(() => send("SIGKILL"), 2_000); };
+  let signalled = false;
+  const kill = () => { signalled = true; send("SIGTERM"); hard ??= setTimeout(() => send("SIGKILL"), 2_000); };
   const timer = setTimeout(kill, ms);
   signal?.addEventListener("abort", kill, { once: true });
   try {
     const [code, out, err] = await Promise.all([p.exited, new Response(p.stdout).text(), new Response(p.stderr).text()]);
     return { code, out: out.trim(), err: err.trim() };
-  } finally { unregister(); clearTimeout(timer); if (hard) clearTimeout(hard); signal?.removeEventListener("abort", kill); }
+  } finally {
+    // git is gone, but a transport child in its group that ignored SIGTERM (a credential helper, a proxy) may not be, and the timer that would have killed it is cleared below. Once the
+    // group was signalled, SIGKILL whatever is left of it (ESRCH when nothing is) before it is forgotten: it would otherwise live on at ppid 1 holding the repository.
+    if (group && signalled) try { process.kill(-p.pid, "SIGKILL"); } catch { /* the group is already gone */ }
+    unregister(); clearTimeout(timer); if (hard) clearTimeout(hard); signal?.removeEventListener("abort", kill);
+  }
 }
 
 export { git as syncGit };
@@ -67,13 +73,19 @@ export async function generationSyncGit(dir: string, args: string[], signal?: Ab
   const unregister = group ? register(p.pid) : () => {};
   // SIGTERM first, so git removes its lock files; SIGKILL only if it is still there after a grace period.
   let hard: ReturnType<typeof setTimeout> | undefined;
-  const kill = () => { send("SIGTERM"); hard ??= setTimeout(() => send("SIGKILL"), 2_000); };
+  let signalled = false;
+  const kill = () => { signalled = true; send("SIGTERM"); hard ??= setTimeout(() => send("SIGKILL"), 2_000); };
   const timer = setTimeout(kill, ms);
   signal?.addEventListener("abort", kill, { once: true });
   try {
     const [code, out, err] = await Promise.all([p.exited, new Response(p.stdout).text(), new Response(p.stderr).text()]);
     return { code, out: out.trim(), err: err.trim() };
-  } finally { unregister(); clearTimeout(timer); if (hard) clearTimeout(hard); signal?.removeEventListener("abort", kill); }
+  } finally {
+    // git is gone, but a transport child in its group that ignored SIGTERM (a credential helper, a proxy) may not be, and the timer that would have killed it is cleared below. Once the
+    // group was signalled, SIGKILL whatever is left of it (ESRCH when nothing is) before it is forgotten: it would otherwise live on at ppid 1 holding the repository.
+    if (group && signalled) try { process.kill(-p.pid, "SIGKILL"); } catch { /* the group is already gone */ }
+    unregister(); clearTimeout(timer); if (hard) clearTimeout(hard); signal?.removeEventListener("abort", kill);
+  }
 }
 
 

package/src/setup-toml.ts

@@ -263,6 +263,11 @@ export function updateTomlArray(text: string, path: readonly string[], expectedA
     for (let index = 0; index < array.elements.length; index++) if (!keep.has(index)) {
       const element = array.elements[index]!; changes.push({ start: element.removeFrom, end: element.end, text: "" });
       if (element.comma !== undefined) changes.push({ start: element.comma, end: element.comma + 1, text: "" });
+      else {
+        // The last element has no comma of its own: drop the same-line comma that append inserted after the kept element before it, or `[a,]` remains. A comma followed by a comment or newline was the person's own and stays.
+        const before = [...keep].filter(kept => kept < index).at(-1), previous = before === undefined ? undefined : array.elements[before];
+        if (previous?.comma !== undefined && !append.length && /^[ \t]*$/.test(text.slice(previous.comma + 1, element.start))) changes.push({ start: previous.comma, end: previous.comma + 1, text: "" });
+      }
     }
     if (append.length) {
       const last = [...keep].at(-1), element = last === undefined ? undefined : array.elements[last];

package/src/setup.ts

@@ -142,11 +142,11 @@ export function planSetup(target: string, mode: SetupPlan["mode"] = "preview", o
   const pluginNotes: string[] = [];
   if (targets.includes("claude")) {
     const settings = json(read(c.paths.claude[1]!));
-    try {
-      const registry = json(read(join(dirname(c.paths.claude[1]!), "plugins", "installed_plugins.json")));
-      const ids = new Set([...Object.keys(record(settings.enabledPlugins ?? {})), ...Object.keys(record(registry.plugins ?? {}))].filter(key => /^agent-mem(?:@[A-Za-z0-9._-]+)?$/.test(key)));
-      for (const id of ids) pluginNotes.push(`Installed Claude plugin ${id} detected: if enabled, direct setup would duplicate its MCP server and seven hooks. Choose plugin installation or direct setup; disable/uninstall the plugin before applying direct setup.`);
-    } catch { /* Optional plugin metadata must never prevent setup or recovery; authoritative settings/receipts keep their guards. */ }
+    // The settings-derived ids are computed outside the registry guard, so a broken installed_plugins.json cannot hide them.
+    const ids = new Set<string>();
+    try { for (const key of Object.keys(record(settings.enabledPlugins ?? {}))) ids.add(key); } catch { /* Optional plugin metadata must never prevent setup or recovery. */ }
+    try { for (const key of Object.keys(record(json(read(join(dirname(c.paths.claude[1]!), "plugins", "installed_plugins.json"))).plugins ?? {}))) ids.add(key); } catch { /* Optional plugin metadata must never prevent setup or recovery; authoritative settings/receipts keep their guards. */ }
+    for (const id of [...ids].filter(key => /^agent-mem(?:@[A-Za-z0-9._-]+)?$/.test(key))) pluginNotes.push(`Installed Claude plugin ${id} detected: if enabled, direct setup would duplicate its MCP server and seven hooks. Choose plugin installation or direct setup; disable/uninstall the plugin before applying direct setup.`);
   }
   return { targets, mode, actions: targets.map(target => {
     const prior = receipt(c, target, false); for (const file of c.paths[target]) read(file);
@@ -156,7 +156,7 @@ export function planSetup(target: string, mode: SetupPlan["mode"] = "preview", o
     const unchanged = !!prior && prior.phase === "applied" && prior.intent === intent(c, target) && prior.changes.every((change, index) => { try { const live = read(change.path); restoreChange(prior, change, index, live); return managedAfter(target, index, change.before, change.after, live); } catch { return false; } });
     const add = command(target, c.bun, c.entry), remove = [target, "mcp", "remove", ...(target === "claude" ? ["--scope", "user"] : []), "amem"];
     return { target, available: available(c, target, options), files: c.paths[target], receipt: journal(c, target), registration: mode === "undo" ? null : add, lifecycle: mode === "undo" ? "restore original MCP/hook files" : lifecycle(target), hooks: mode === "undo" || unchanged ? [] : plannedHooks(c, target), mcpChange: mode === "undo" ? prior ? "restore" : "unchanged" : unchanged ? "unchanged" : hasAmem ? "replace" : "add", commands: mode === "undo" || prior?.intent === intent(c, target) || !add || !available(c, target, options) ? [] : [...(hasAmem ? [remove] : []), add], state: prior && prior.intent !== intent(c, target) ? "runtime changed; managed entries will update" : prior?.phase ?? "not installed" };
-  }), notes: [...pluginNotes, ...(/(?:\/installs\/bun\/[^/]+|\/Cellar\/bun\/[^/]+)\/(?:bin\/)?bun$/.test(c.bun) ? ["this bun path is version-specific; rerun setup --apply after changing Bun"] : []), "Preview only unless --apply or --undo is confirmed in a person's terminal.", "Native registration commands run in a private staging HOME; only the listed configuration files are published.", "Original file bytes restore exactly when untouched; otherwise undo preserves CLI-owned changes and restores only managed entries, refusing edits to those entries.", "No AGENTS.md, CLAUDE.md or rule files are edited.", `A private ${join(c.state, "setup.lock")} serializes mutations; temporary ${join(realPath(tmpdir()), "amem-setup-*")} staging homes are removed.`, "Codex requires its native /hooks review before newly registered hooks run; setup does not grant hook trust. Runtime registrations use the PATH-resolved absolute Bun path without resolving its stable symlink; setup all reports and skips missing clients."] };
+  }), notes: [...pluginNotes, ...(/\/[^/]*\d+\.\d+[^/]*\/(?:bin\/)?bun$/.test(c.bun) ? ["this bun path is version-specific; rerun setup --apply after changing Bun"] : []), "Preview only unless --apply or --undo is confirmed in a person's terminal.", "Native registration commands run in a private staging HOME; only the listed configuration files are published.", "Original file bytes restore exactly when untouched; otherwise undo preserves CLI-owned changes and restores only managed entries, refusing edits to those entries.", "No AGENTS.md, CLAUDE.md or rule files are edited.", `A private ${join(c.state, "setup.lock")} serializes mutations; temporary ${join(realPath(tmpdir()), "amem-setup-*")} staging homes are removed.`, "Codex requires its native /hooks review before newly registered hooks run; setup does not grant hook trust. Runtime registrations use the PATH-resolved absolute Bun path without resolving its stable symlink; setup all reports and skips missing clients."] };
 }
 function verifyNativeMcp(target: SetupTarget, env: Env, cwd: string): void {
   // In older free-form Pi CLIs, an unknown subcommand can be treated as a model prompt.