@staix/agent-mem 0.5.0 → 0.7.0

package/src/memory/decay-review.ts

@@ -0,0 +1,136 @@
+import { Database } from "bun:sqlite";
+import { lstatSync } from "node:fs";
+import { join } from "node:path";
+import { hashJSON } from "./generation.ts";
+import { candidateTargetRevision, type CandidateTarget, type Counter } from "./candidates.ts";
+import { MemoryStore, type View } from "./store.ts";
+
+export const DECAY_DEFAULT_DAYS = 90, DECAY_PREVIEW_LIMIT = 64, DECAY_SCAN_LIMIT = 5000;
+export interface DecayEntry { target: CandidateTarget; view: View }
+export interface DecayPlan {
+  project: string; profile: string; days: number; at: string; cutoff: string; demoteExpiresAt: string;
+  entries: DecayEntry[]; withheld: number; citedExemptions: number | null; truncated: boolean;
+  /** Missing/zero observations do not prove the note was never cited. */
+  citationHistory: "unknown";
+}
+export interface DecayOptions {
+  now?: () => number; days?: number; ids?: readonly string[]; aliases?: readonly string[]; counters?: () => readonly Counter[] | undefined;
+  screen?: (view: View) => boolean; assertCurrent?: () => void;
+}
+function idsOf(ids: readonly string[]): string[] {
+  const normalized = ids.map(id => id.replace(/^mem:/, ""));
+  if (normalized.length > DECAY_PREVIEW_LIMIT || new Set(normalized).size !== normalized.length || normalized.some(id => !/^[a-f0-9]{32}$/.test(id))) throw Error("name up to 64 distinct exact entry ids");
+  return normalized;
+}
+/** Advisory telemetry without opening/pruning the candidate writer. Unavailable is unknown, never zero. */
+export function readDecayCounters(base: string, projects: readonly string[]): Counter[] | undefined {
+  const file = join(base, "candidates.db");
+  let db: Database | undefined;
+  try {
+    const stat = lstatSync(file, { throwIfNoEntry: false });
+    if (!stat || !stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) return undefined;
+    db = new Database(file, { readonly: true }); db.run("PRAGMA busy_timeout = 0");
+    const rows = db.query("SELECT id,payload,at,rendered,delivered,cited FROM counters WHERE project IN (SELECT value FROM json_each(?)) AND cited > 0 ORDER BY at DESC").all(JSON.stringify(projects)) as { id: string; payload: string; at: number; rendered: number | null; delivered: number | null; cited: number | null }[];
+    return rows.map(row => ({ id: row.id, key: JSON.parse(row.payload), createdAt: new Date(row.at).toISOString(), rendered: row.rendered, delivered: row.delivered, cited: row.cited }));
+  } catch { return undefined; }
+  finally { try { db?.close(); } catch { /* An unavailable telemetry close cannot authorize a mutation. */ } }
+}
+function citedIds(project: string, aliases: readonly string[], counters: readonly Counter[] | undefined): Set<string> {
+  const ids = new Set<string>();
+  for (const row of counters ?? []) {
+    if (!row?.key || ![project, ...aliases].includes(row.key.project) || !Number.isSafeInteger(row.cited) || !(row.cited! > 0)) continue;
+    // Counter timestamps describe delivery, not a later citation update. Any retained positive exempts.
+    ids.add(row.key.entryId);
+  }
+  return ids;
+}
+/** Age/goal selection is independent of telemetry; retained positive citations may only exempt entries. */
+export function decayPreview(store: MemoryStore, project: string, options: DecayOptions = {}): DecayPlan {
+  options.assertCurrent?.();
+  if (!project.trim() || store.profile.sharded && !store.profile.shardUser && store.profile.shardKey !== project) throw Error("decay project does not match the bound store");
+  const now = (options.now ?? Date.now)(), days = options.days ?? DECAY_DEFAULT_DAYS, cutoff = now - days * 86400_000;
+  if (!Number.isSafeInteger(days) || days < 1 || !Number.isFinite(now) || !Number.isFinite(cutoff) || Math.abs(cutoff) > 8_640_000_000_000_000) throw Error("decay days are outside the supported range");
+  const requested = options.ids === undefined ? undefined : idsOf(options.ids);
+  return store.withDeferredPromotions(() => {
+    const goals = store.goals(project).filter(goal => ["open", "active", "blocked"].includes(goal.state));
+    const tasks = new Set(goals.flatMap(goal => goal.links.map(link => link.task))), goalNodes = new Set(goals.map(goal => `goal:${goal.id}`));
+    let counters: readonly Counter[] | undefined;
+    try { counters = options.counters?.(); } catch { /* Telemetry is advisory; an unreadable snapshot is unknown. */ }
+    const cited = citedIds(project, options.aliases ?? [], counters);
+    // ponytail: list materializes the existing core corpus before slicing; a scoped pager is the upgrade for large homes.
+    const rows = requested ? requested.map(id => store.get(id, project)) : store.list({ project, tier: "long", limit: DECAY_SCAN_LIMIT + 1 });
+    if (rows.length > DECAY_SCAN_LIMIT) throw Error("decay preview scan bound exceeded; name exact ids to narrow it");
+    const entries: DecayEntry[] = []; let withheld = 0, citedExemptions = 0;
+    for (let index = 0; index < rows.length; index++) {
+      const view = rows[index];
+      const eligible = view && (!requested || view.id === requested[index]) && view.project === project && view.tier === "long" && !view.supersededBy && Number.isFinite(Date.parse(view.at)) && Date.parse(view.at) < cutoff
+        && !(view.task && tasks.has(view.task)) && !view.about.some(node => goalNodes.has(node) || node.startsWith("task:") && tasks.has(node.slice(5)));
+      if (!eligible) { if (requested) throw Error("requested entry is not eligible for decay"); continue; }
+      if (cited.has(view.id)) { citedExemptions++; if (requested) throw Error("requested entry has a retained recorded citation"); continue; }
+      if (options.screen && !options.screen(structuredClone(view))) { withheld++; if (requested) throw Error("requested entry is withheld by current policy"); continue; }
+      entries.push({ target: { id: view.id, revision: candidateTargetRevision(view) }, view: structuredClone(view) });
+    }
+    options.assertCurrent?.();
+    return { project, profile: hashJSON(store.profile), days, at: new Date(now).toISOString(), cutoff: new Date(cutoff).toISOString(), demoteExpiresAt: store.shortExpiry(), entries: entries.slice(0, DECAY_PREVIEW_LIMIT), withheld, citedExemptions: counters === undefined ? null : citedExemptions, truncated: entries.length > DECAY_PREVIEW_LIMIT, citationHistory: "unknown" };
+  });
+}
+/** Duplicate-group forgetting requires a separate person group review, never an implicit decay expansion. */
+export function assertExactDecayForget(store: MemoryStore, ids: readonly string[], project: string): void {
+  store.withDeferredPromotions(() => {
+    for (const id of ids) {
+      const targets = store.forgetTargets(id, project);
+      if (targets.length !== 1 || targets[0]?.id !== id) throw Error("decay forget expands beyond reviewed exact entries; review the imported copy group separately");
+    }
+  });
+}
+
+export interface DecayApplyOptions extends Omit<DecayOptions, "days"> {
+  actor: "person" | "agent"; confirmed?: boolean; forget?: boolean;
+}
+export interface DecayApplyReport { action: "demote" | "forget"; applied: string[]; failed: string; remaining: string[]; expiresAt?: string }
+export class DecayApplyError extends Error {
+  jsonOutput = false;
+  readonly failedMayHaveChanged = true;
+  constructor(readonly report: DecayApplyReport, cause: unknown) {
+    super("decay apply stopped; the failed target may have changed, inspect before retrying", { cause }); this.name = "DecayApplyError";
+  }
+  get applied(): readonly string[] { return this.report.applied; }
+  get failed(): string { return this.report.failed; }
+  get remaining(): readonly string[] { return this.report.remaining; }
+  render(): string {
+    if (this.jsonOutput) return JSON.stringify({ ok: false, ...this.report, failedMayHaveChanged: this.failedMayHaveChanged });
+    return `${this.message}; applied: ${this.report.applied.join(", ") || "none"}; failed: ${this.report.failed}; remaining: ${this.report.remaining.join(", ") || "none"}${this.report.expiresAt ? `; completed demotions expire: ${this.report.expiresAt}` : ""}`;
+  }
+}
+/** The host shows this exact plan; every selected revision/eligibility is rechecked before any append. */
+export function applyDecay(store: MemoryStore, plan: DecayPlan, options: DecayApplyOptions): { action: "demote" | "forget"; ids: string[]; expiresAt?: string } {
+  if (options.actor !== "person") throw Error("decay apply requires person authority");
+  options.assertCurrent?.();
+  const ids = options.ids === undefined ? plan.entries.map(entry => entry.target.id) : idsOf(options.ids);
+  if ((options.ids === undefined || options.forget) && options.confirmed !== true) throw Error("decay bulk/forget apply requires explicit person confirmation");
+  if (hashJSON(store.profile) !== plan.profile || ids.some(id => !plan.entries.some(entry => entry.target.id === id))) throw Error("decay preview binding changed or target was not previewed");
+  const action = options.forget ? "forget" : "demote";
+  if (!ids.length) return { action, ids };
+  if (!options.forget && (!Number.isFinite(Date.parse(plan.demoteExpiresAt)) || new Date(plan.demoteExpiresAt).toISOString() !== plan.demoteExpiresAt || Date.parse(plan.demoteExpiresAt) <= (options.now ?? Date.now)())) throw Error("decay demotion expiry is spent; preview again");
+  if (!options.forget) store.assertDemotionExpiry(plan.demoteExpiresAt);
+  return store.withCurrentEntries(ids, plan.project, current => {
+    const fresh = decayPreview(store, plan.project, { ...options, days: plan.days, ids });
+    for (const view of current) {
+      const expected = plan.entries.find(entry => entry.target.id === view.id)?.target.revision;
+      if (!expected || candidateTargetRevision(view) !== expected || !fresh.entries.some(entry => entry.target.id === view.id && entry.target.revision === expected)) throw Error("decay target changed since preview");
+    }
+    if (options.forget) assertExactDecayForget(store, ids, plan.project);
+    options.assertCurrent?.();
+    // All checks precede effects. The failed target may itself have appended before an I/O error.
+    const applied: string[] = [], expiry = options.forget ? {} : { expiresAt: plan.demoteExpiresAt };
+    for (let index = 0; index < ids.length; index++) {
+      const id = ids[index]!;
+      try {
+        const result = options.forget ? store.forget(id, "person", plan.project, true) : store.demote(id, "person", plan.project, plan.demoteExpiresAt);
+        if (!result) throw Error("decay target outcome unavailable");
+        applied.push(id);
+      } catch (error) { throw new DecayApplyError({ action, applied: [...applied], failed: id, remaining: ids.slice(index + 1), ...expiry }, error); }
+    }
+    return { action, ids, ...expiry };
+  });
+}

package/src/memory/doctor.ts

@@ -0,0 +1,412 @@
+import { copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Database } from "bun:sqlite";
+import { sessionStartBrief } from "../session-brief.ts";
+import { pendingSummary } from "./candidate-pending.ts";
+import { walkShards } from "./catalog.ts";
+import { loadAmemConfig, repoConfigRoot } from "./config.ts";
+import { readSelector } from "./generation.ts";
+import { processLiveness } from "./platform.ts";
+import { STOP_SIGNALS } from "./sync-cadence.ts";
+import { boundRepoRoot } from "./repo-scope.ts";
+import { shardDir } from "./shard.ts";
+import type { MemoryStore, View } from "./store.ts";
+import { nextSyncAt, readSyncState, remoteConfigured, syncDue, usableState } from "./sync-cadence.ts";
+
+/**
+ * F15, `amem doctor`: one report over the memory home. It writes nothing into the home. Every check that needs a store (the notes, the brief, the index proof) runs on a
+ * private scratch copy of the logs in a temporary directory that is removed afterwards: opening the live store would take a reader lease, refresh and checkpoint the live
+ * index, and the live work list would run its migration. The live index is only snapshotted (a read-only connection and `VACUUM INTO`), so "index equals rebuild" compares the
+ * index the way a reader would refresh it with a full rebuild, without anyone's index being touched. A home nobody used, and a project the home has not seen, stay absent.
+ * Every section is `ok`, `attention` (something to look at), `skipped` (nothing to check here, with the reason: not a problem) or `unavailable` (it could not be
+ * checked, with the reason), never a silent zero.
+ */
+export type SectionStatus = "ok" | "attention" | "skipped" | "unavailable";
+export type Section<T extends object = Record<string, unknown>> = { status: SectionStatus } & T;
+export const DOCTOR_SCHEMA = "amem.doctor/v1";
+export const CLIS = ["claude", "codex", "kimi", "pi"] as const;
+export type Cli = typeof CLIS[number];
+/** A CLI whose last capture is older than this is called stale. */
+export const CAPTURE_STALE_MS = 7 * 86400_000;
+/** A sync remote whose last success is older than this needs attention. */
+export const SYNC_STALE_MS = 7 * 86400_000;
+const DEFAULT_BRIEF_TOKENS = 1200;
+const COPY_LIMIT_BYTES = 64 * 1024 * 1024;
+/** Notes read per project for the duplicate and stale checks; a report says when a project has more. */
+export const LIST_ALL = 100_000;
+const MAX_IDS = 10;
+
+export interface DoctorOptions {
+  home: string; homeSource: string; cwd: string; project: string; aliases: readonly string[]; now: number;
+  /** Opens this project's curated store on `base`, the way the other person reads do (a split home through its project shard). Doctor passes a private scratch base, never the live home. */
+  openCurated: (base: string) => MemoryStore;
+  /** The cadence command the person runs from their own shell; shown in the report, never installed. */
+  syncCommand?: string;
+  /** Test seam: called with the scratch directory right after it is made, before anything else runs. The CLI never sets it. */
+  afterScratch?: (dir: string) => void;
+}
+export interface DoctorReport {
+  schema: typeof DOCTOR_SCHEMA;
+  status: SectionStatus;
+  home: { path: string; source: string };
+  project: string;
+  sections: {
+    duplicates: Section; stale: Section; candidates: Section; capture: Section; brief: Section; index: Section; readers: Section; policy: Section; cadence: Section;
+  };
+}
+
+const worst = (values: SectionStatus[]): SectionStatus => values.includes("attention") ? "attention" : values.includes("unavailable") ? "unavailable" : "ok";
+const message = (error: unknown): string => (error instanceof Error ? error.message : String(error)).split("\n")[0]!.slice(0, 200);
+const unavailable = (reason: string): Section => ({ status: "unavailable", reason });
+const skipped = (reason: string): Section => ({ status: "skipped", reason });
+const ids = (list: string[]): string[] => list.slice(0, MAX_IDS).map(id => id.slice(0, 8));
+const regularDir = (path: string): boolean => { try { const stat = lstatSync(path); return stat.isDirectory() && !stat.isSymbolicLink(); } catch { return false; } };
+const regularFile = (path: string): boolean => { try { const stat = lstatSync(path); return stat.isFile() && !stat.isSymbolicLink(); } catch { return false; } };
+
+type Layout = "shared-v1" | "generation" | "split";
+function layoutOf(home: string): Layout {
+  if (existsSync(join(home, "shards.json"))) return "split";
+  return readSelector(home).selector?.kind === "generation" ? "generation" : "shared-v1";
+}
+
+/** Whether this project's curated notes already exist, so there is something to copy. */
+function curatedPresent(home: string, project: string, layout: Layout): boolean {
+  if (layout === "split") return existsSync(join(shardDir(home, project), "generation.json"));
+  if (layout === "generation") return true;
+  return regularDir(join(home, "log"));
+}
+
+/** What a scratch copy leaves out: databases, locks, repositories, the machine-local capture and work trees, spools and ingest cursors. */
+const SKIP = /\.db(-wal|-shm)?$|\.lock$|\.tmp$|^\.git$|\.git$|^spool$|^ingest$|^readers$/;
+class TooBig extends Error {}
+function copyTree(from: string, to: string, budget: { bytes: number }, skipNames: ReadonlySet<string> = new Set()): void {
+  mkdirSync(to, { recursive: true, mode: 0o700 });
+  for (const name of readdirSync(from)) {
+    if (SKIP.test(name) || skipNames.has(name)) continue;
+    const source = join(from, name), stat = lstatSync(source);
+    if (stat.isSymbolicLink()) throw new Error("the memory home holds a link where a plain file or directory is expected");
+    if (stat.isDirectory()) copyTree(source, join(to, name), budget, skipNames);
+    else if (stat.isFile()) { budget.bytes += stat.size; if (budget.bytes > COPY_LIMIT_BYTES) throw new TooBig(); copyFileSync(source, join(to, name)); }
+  }
+}
+
+/** The curated side of the home, without any database: the logs of this project (and its aliases), and the small files that bind them. */
+function copyCurated(options: DoctorOptions, layout: Layout, scratch: string, budget: { bytes: number }): void {
+  const home = options.home;
+  for (const name of readdirSync(home)) {      // top-level plain files: machine.json, shards.json, profile.json, aliases.jsonl, lifecycle.jsonl, the configuration
+    if (SKIP.test(name) || !regularFile(join(home, name))) continue;
+    const stat = statSync(join(home, name)); budget.bytes += stat.size; if (budget.bytes > COPY_LIMIT_BYTES) throw new TooBig();
+    copyFileSync(join(home, name), join(scratch, name));
+  }
+  if (layout === "split") {
+    for (const key of [options.project, ...options.aliases]) {
+      const dir = shardDir(home, key);
+      if (existsSync(join(dir, "generation.json"))) copyTree(dir, join(scratch, "projects", dir.split("/").pop()!), budget, new Set(["machine", "work"]));
+    }
+    if (regularDir(join(home, "user"))) copyTree(join(home, "user"), join(scratch, "user"), budget);
+  } else {
+    if (layout === "generation") copyTree(join(home, "generations"), join(scratch, "generations"), budget);
+    for (const folder of ["log", "local"]) if (regularDir(join(home, folder))) copyTree(join(home, folder), join(scratch, folder), budget);   // shared-v1's logs; a generation's legacy input
+  }
+}
+
+/** The work logs of this project and its aliases, in a private base of their own: the brief opens a work list read-write and migrates its index. */
+function copyWork(options: DoctorOptions, base: string, budget: { bytes: number }): boolean {
+  let any = false;
+  for (const name of ["machine.json", "aliases.jsonl", "lifecycle.jsonl"]) if (regularFile(join(options.home, name))) { mkdirSync(base, { recursive: true, mode: 0o700 }); copyFileSync(join(options.home, name), join(base, name)); }
+  for (const key of [options.project, ...options.aliases]) {
+    const dir = shardDir(options.home, key), log = join(dir, "work", "log");
+    if (!regularDir(log)) continue;
+    copyTree(log, join(base, "projects", dir.split("/").pop()!, "work", "log"), budget);
+    if (regularFile(join(dir, "project.json"))) copyFileSync(join(dir, "project.json"), join(base, "projects", dir.split("/").pop()!, "project.json"));
+    any = true;
+  }
+  return any;
+}
+
+/** A snapshot of the live shared-v1 index (a read-only connection, so no checkpoint, no lease), or false when there is none. */
+function snapshotIndex(live: string, to: string): boolean {
+  const file = join(live, "index.db");
+  if (!regularFile(file)) return false;
+  const forms: (() => Database)[] = [
+    () => new Database(file, { readonly: true }),
+    () => new Database(`file:${encodeURI(file).replace(/\?/g, "%3F").replace(/#/g, "%23")}?immutable=1`, { readonly: true } as ConstructorParameters<typeof Database>[1]),
+  ];
+  for (const open of forms) {
+    let db: Database | undefined;
+    try { db = open(); db.run("PRAGMA busy_timeout = 1000"); db.run(`VACUUM INTO '${to.replaceAll("'", "''")}'`); return true; }
+    catch { /* the next form */ } finally { try { db?.close(); } catch { /* nothing to close */ } }
+  }
+  throw new Error("the live index could not be snapshotted");
+}
+
+function duplicatesAndStale(options: DoctorOptions, rows: View[], store: MemoryStore): { duplicates: Section; stale: Section } {
+  const groups = new Map<string, string[]>();
+  for (const row of rows) {
+    const key = JSON.stringify([row.kind, (row.title ?? "").trim().toLowerCase(), row.text.replace(/\s+/g, " ").trim().toLowerCase()]);
+    groups.set(key, [...(groups.get(key) ?? []), row.id]);
+  }
+  const same = [...groups.values()].filter(group => group.length > 1).map(group => group.sort());
+  let legacy = 0;
+  try { legacy = store.dedupe(options.project, false).groups.length; } catch { /* the legacy preview is optional */ }
+  const truncated = rows.length >= LIST_ALL;
+  const duplicates: Section = { status: same.length || legacy || truncated ? "attention" : "ok", notes: rows.length, identicalGroups: same.length,
+    ...(same.length ? { examples: same.slice(0, MAX_IDS).map(group => group.map(id => id.slice(0, 8))) } : {}), importedGroups: legacy,
+    ...(truncated ? { truncated: `only the newest ${LIST_ALL} notes were read` } : {}),
+    ...(legacy ? { hint: "amem dedupe previews the imported duplicates; amem dedupe --apply reconciles them" } : {}) };
+  const root = boundRepoRoot(options.cwd, options.home, options.project);
+  let stale: Section;
+  if (!root) stale = skipped("run doctor from inside this project's repository to check its path references");
+  else {
+    const missing = rows.filter(row => { const paths = row.about.filter(node => node.startsWith("path:")).map(node => node.slice(5)); return paths.length > 0 && paths.every(path => !existsSync(join(root, path))); });
+    stale = { status: missing.length ? "attention" : "ok", checked: rows.length, missingReferences: missing.length, ...(missing.length ? { examples: ids(missing.map(row => row.id)) } : {}) };
+  }
+  return { duplicates, stale };
+}
+
+/** The incremental index, as a reader would refresh it from the snapshot of the live one, against a full rebuild of the same logs. Both live in the scratch copy. */
+function indexSection(store: MemoryStore, layout: Layout, snapshotted: boolean): Section {
+  if (layout !== "shared-v1") return skipped("a curated split or generation home builds and seals its index when it is created; amem rebuild repeats it");
+  try {
+    store.list({ limit: 1 });                         // brings the snapshot level with the logs, as the next reader would
+    const incremental = store.dump(); store.rebuild();
+    return incremental === store.dump() ? { status: "ok", liveIndex: snapshotted ? "snapshotted" : "absent" }
+      : { status: "attention", liveIndex: snapshotted ? "snapshotted" : "absent", hint: "the index differs from a rebuild of the logs: run amem rebuild" };
+  } catch (error) { return unavailable(message(error)); }
+}
+
+function receiptPhase(home: string, cli: Cli): "applied" | "prepared" | null {
+  try {
+    const file = join(home, "setup", `${cli}.json`), stat = lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 4 * 1024 * 1024) return null;
+    const value = JSON.parse(readFileSync(file, "utf8")) as { target?: unknown; phase?: unknown };
+    return value.target === cli && (value.phase === "applied" || value.phase === "prepared") ? value.phase : null;
+  } catch { return null; }
+}
+
+/**
+ * Per CLI: is a capture hook registered, and when did it last capture. "Registered" is what the setup receipt says (`hookEvidence`): a hook the person removed by hand
+ * afterwards still shows as registered until `amem setup <cli> --apply` or `--undo` is run again. A CLI without a receipt is `manual`.
+ */
+function captureSection(options: DoctorOptions): Section {
+  const keys = [options.project, ...options.aliases];
+  const seen = new Map<string, { rows: number; last: string | null }>();
+  let readable = true;
+  for (const shard of walkShards(options.home)) {
+    if (!keys.includes(shard.key)) continue;
+    for (const dir of shard.machineDirs) {
+      const file = join(dir, "capture.db");
+      if (!existsSync(file)) continue;
+      let db: Database | undefined;
+      try {
+        db = new Database(file, { readonly: true }); db.run("PRAGMA busy_timeout = 1000");
+        for (const row of db.query("SELECT agent, COUNT(*) AS n, MAX(at) AS last FROM rows GROUP BY agent").all() as { agent: string; n: number; last: string | null }[]) {
+          const prior = seen.get(row.agent);
+          seen.set(row.agent, { rows: (prior?.rows ?? 0) + row.n, last: prior?.last && prior.last > (row.last ?? "") ? prior.last : row.last });
+        }
+      } catch { readable = false; } finally { db?.close(); }
+    }
+  }
+  const clis: Record<string, unknown> = {};
+  const attention: string[] = [];
+  for (const cli of CLIS) {
+    const phase = receiptPhase(options.home, cli), registered = phase === "applied", entry = seen.get(cli);
+    const last = entry?.last ?? null, ageMs = last === null ? null : options.now - Date.parse(last);
+    const state = last === null ? "never" : ageMs! > CAPTURE_STALE_MS ? "stale" : "fresh";
+    // A registered hook that is not fresh, or any CLI whose capture went stale, needs a look. A CLI without a hook that never captured is just not used here: reported, not flagged.
+    const needs = registered ? state !== "fresh" : state === "stale";
+    if (needs) attention.push(cli);
+    clis[cli] = { hook: registered ? "registered" : "manual", ...(registered ? { hookEvidence: "setup receipt" } : {}), ...(phase === "prepared" ? { setup: "prepared, not applied" } : {}), capture: state, lastCaptureAt: last, rows: entry?.rows ?? 0,
+      ...(needs || (!registered && state === "never") ? { hint: registered ? `the ${cli} hook is registered but its capture is ${state}: open a session${cli === "claude" ? "" : `, or run amem ingest ${cli}`}` : cli === "claude" ? "run amem setup claude --apply to register the capture hooks" : `run amem setup ${cli} --apply, or amem ingest ${cli} by hand` } : {}) };
+  }
+  return { status: !readable ? "unavailable" : attention.length ? "attention" : "ok", ...(readable ? {} : { reason: "a capture database could not be read" }), clis };
+}
+
+/**
+ * The SessionStart brief's size for this project: the brief the SessionStart worker builds (the native parent's deferred brief is smaller and is not what is measured).
+ * It is built from the scratch copy of the curated logs and of the work logs; the capture section reads this machine's capture database read-only and only when it exists.
+ */
+async function briefSection(options: DoctorOptions, curated: MemoryStore | undefined, workBase: string | undefined, copyFailed: string | undefined): Promise<Section> {
+  if (copyFailed) return unavailable(copyFailed);
+  let configured: number | undefined;
+  try { configured = loadAmemConfig(options.home, repoConfigRoot(options.cwd)).config.briefBytes; } catch { /* the policy section reports it */ }
+  const budget = Math.min(DEFAULT_BRIEF_TOKENS, configured ?? Number.MAX_SAFE_INTEGER);
+  try {
+    const result = await sessionStartBrief({ cwd: options.cwd, base: options.home, project: options.project, now: () => options.now,
+      measureOnly: { ...(curated ? { curated } : {}), ...(workBase ? { workBase } : {}) } });
+    if (result.context === "") return unavailable("the brief is empty for this project (archived, forgotten or its binding changed)");
+    const tight = result.tokens > budget * 0.9;
+    return { status: result.partial || tight ? "attention" : "ok", tokens: result.tokens, budget, coverage: result.coverage,
+      ...(result.partial ? { hint: "a section is partial or unavailable in the brief: see coverage" } : tight ? { hint: "the brief uses over 90% of its budget" } : {}) };
+  } catch (error) { return unavailable(message(error)); }
+}
+
+function readersSection(options: DoctorOptions): Section {
+  const dir = join(options.home, "readers");
+  if (!existsSync(dir)) return { status: "ok", live: 0, stale: 0, unreadable: 0 };
+  if (!regularDir(dir)) return unavailable("the readers directory is not a plain directory");
+  let live = 0, stale = 0, unreadable = 0;
+  try {
+    for (const name of readdirSync(dir).filter(file => file.endsWith(".json")).sort()) {
+      try {
+        const stat = lstatSync(join(dir, name));
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 4096) throw new Error();
+        const value = JSON.parse(readFileSync(join(dir, name), "utf8")) as { pid?: unknown; signature?: unknown };
+        const liveness = processLiveness(value.pid, typeof value.signature === "string" ? value.signature : undefined);
+        if (liveness === "gone") stale++; else live++;
+      } catch { unreadable++; }
+    }
+  } catch (error) { return unavailable(message(error)); }
+  return { status: stale || unreadable ? "attention" : "ok", live, stale, unreadable, ...(stale || unreadable ? { hint: "a reader lease of a process that is gone is cleared by the next reader; an unreadable one needs a look" } : {}) };
+}
+
+function policySection(options: DoctorOptions): Section {
+  try {
+    const { config, source } = loadAmemConfig(options.home, repoConfigRoot(options.cwd));
+    return { status: "ok", machine: source.machine, repo: source.repo, denyPaths: config.denyPaths.length, piiPatterns: config.piiPatterns.length,
+      ...(config.briefBytes !== undefined ? { briefBytes: config.briefBytes } : {}), ...(config.excerptBytes !== undefined ? { excerptBytes: config.excerptBytes } : {}),
+      ...(config.capturePaths !== undefined ? { capturePaths: config.capturePaths } : {}) };
+  } catch (error) { return unavailable(message(error)); }
+}
+
+/** F16: which CLIs ingest at SessionEnd (setup receipts), and the person-owned sync cadence. amem registers no sync hook (a hook may not do network work). */
+function cadenceSection(options: DoctorOptions): Section {
+  const ingest: Record<string, string> = {};
+  for (const cli of CLIS) ingest[cli] = receiptPhase(options.home, cli) === "applied" ? (cli === "claude" ? "hooks" : "session end") : "manual";
+  const remote = remoteConfigured(options.home), state = usableState(readSyncState(options.home), options.now), next = nextSyncAt(state);
+  const command = options.syncCommand ?? "amem sync --if-due";
+  const stale = remote && (state.lastOkAt === null || options.now - Date.parse(state.lastOkAt) > SYNC_STALE_MS || state.failures >= 3);
+  const sync = { remote: remote ? "configured" : "none", lastAttemptAt: state.lastAttemptAt, lastOkAt: state.lastOkAt, failures: state.failures,
+    nextAttemptAt: next === null ? null : new Date(next).toISOString(), due: remote ? syncDue(state, options.now) : false,
+    ...(remote ? { schedule: `run \`${command}\` from your own shell (for example a zshexit or bash EXIT trap): it needs a terminal like every mutating command; amem registers no sync hook and runs nothing between sessions` } : {}) };
+  const manual = CLIS.filter(cli => ingest[cli] === "manual");
+  return { status: stale ? "attention" : "ok", ingest, ...(manual.length ? { manual } : {}), sync,
+    ...(stale ? { hint: state.failures >= 3 ? "sync has failed repeatedly; amem sync --force shows why" : "no recent successful sync: run amem sync" } : {}) };
+}
+
+/**
+ * Let the event loop run once. Doctor's stages are mostly synchronous (a git lookup is a `spawnSync`), and Bun runs a signal handler only when the loop turns: a signal that arrives
+ * during a stalled call would otherwise wait for the end of doctor, where the handler is already removed and the signal is lost. Between stages this lets the handler act at once.
+ * (Measured: with every tick removed a stalled git call loses the signal; removing any ONE tick does not, because other `await`s between stages turn the loop too. They are
+ * redundant on purpose, so a later stage that stops awaiting cannot silently reopen the gap: `test/doctor.test.ts` stalls every git call, one at a time.)
+ */
+const tick = (): Promise<void> => new Promise(resolve => setTimeout(resolve, 0));
+
+/** `amem-doctor-<pid>-<random>`: the owner's pid is in the name so a later run can tell a leftover from a live run. */
+const SCRATCH = /^amem-doctor-(\d+)-[A-Za-z0-9]{6}$/, OLD_SCRATCH = /^amem-doctor-[A-Za-z0-9]{6}$/;
+const OLD_SCRATCH_AGE_MS = 24 * 3600_000;
+
+/**
+ * Remove scratch directories an earlier doctor left behind (it was killed by something no handler sees, or by a version that had none). A directory goes only when it is a plain
+ * directory this user owns, named exactly as doctor names them, and its owner pid is gone: a live pid, or one that cannot be told, keeps its directory (a reused pid costs
+ * a leftover, never a live run's data). A directory from before the pid was in the name has no owner to ask, so it goes only after a day. Returns how many were removed. Never throws.
+ */
+export function sweepStaleScratch(tmp: string = tmpdir(), alive: (pid: number) => boolean = pid => processLiveness(pid) !== "gone", now: number = Date.now(), uid: number | undefined = typeof process.getuid === "function" ? process.getuid() : undefined): number {
+  let removed = 0;
+  let names: string[] = [];
+  try { names = readdirSync(tmp); } catch { return 0; }
+  for (const name of names) {
+    const owner = SCRATCH.exec(name), old = !owner && OLD_SCRATCH.test(name);
+    if (!owner && !old) continue;
+    try {
+      const path = join(tmp, name), stat = lstatSync(path);
+      if (!stat.isDirectory() || stat.isSymbolicLink() || (uid !== undefined && stat.uid !== uid)) continue;
+      if (owner ? alive(Number(owner[1])) : now - stat.mtimeMs < OLD_SCRATCH_AGE_MS) continue;
+      rmSync(path, { recursive: true, force: true }); removed++;
+    } catch { /* gone already, or not ours to remove */ }
+  }
+  return removed;
+}
+
+/**
+ * Keep doctor's scratch directory removed however this process ends while doctor runs. Install it first, then `adopt` the directory once `mkdtemp` has made it: a signal that
+ * arrives in between meets a handler, which has nothing to remove yet but still ends the process with the signal. A handler cannot be left out of the picture: with one installed the
+ * default action is suppressed, so after removing the directory it removes itself and re-raises the signal, which ends the process with the status the shell expects (and only when
+ * no other handler of the host remains, so it never double-fires). An `exit` handler covers a throw. Everything is removed again by `release` once doctor finished normally.
+ * SIGKILL cannot be handled by anyone: the next doctor's `sweepStaleScratch` removes that directory.
+ */
+function guardScratch(): { adopt: (dir: string) => void; release: () => void } {
+  let dir: string | undefined;
+  const remove = () => { if (dir) try { rmSync(dir, { recursive: true, force: true }); } catch { /* best effort */ } };
+  const handlers = STOP_SIGNALS.map(name => {
+    const handler = () => {
+      remove();
+      process.off(name, handler);
+      if (process.listenerCount(name) !== 0) return;       // another handler of the host remains: it decides how the process ends
+      // 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. Exit with the status that death would have had instead (128 + 3), at once. The other
+      // three are re-raised, so a parent sees the signal itself (`signalCode`).
+      if (name === "SIGQUIT") process.exit(128 + 3);
+      process.kill(process.pid, name);
+    };
+    process.on(name, handler);
+    return [name, handler] as const;
+  });
+  process.on("exit", remove);
+  return { adopt: made => { dir = made; }, release: () => { for (const [name, handler] of handlers) process.off(name, handler); process.off("exit", remove); } };
+}
+
+export async function doctorReport(options: DoctorOptions): Promise<DoctorReport> {
+  let scratch: string | undefined, unguard: (() => void) | undefined;
+  let duplicates: Section, stale: Section, index: Section;
+  let curated: MemoryStore | undefined, workBase: string | undefined, copyFailed: string | undefined;
+  try {
+    let layout: Layout | undefined;
+    try { layout = layoutOf(options.home); } catch (error) { throw new Error(`the memory profile cannot be read: ${message(error)}`); }
+    sweepStaleScratch();
+    // The guard is installed BEFORE the directory exists and told its name afterwards: a signal in the few microseconds between `mkdtemp` and a guard installed after it would
+    // meet no handler, take the default action and strand the directory (measured: 4 of 60 runs when a signal lands the instant it appears).
+    const guard = guardScratch(); unguard = guard.release;
+    scratch = mkdtempSync(join(tmpdir(), `amem-doctor-${process.pid}-`));      // a scratch directory, never inside the home: a home nobody used stays absent
+    guard.adopt(scratch);
+    options.afterScratch?.(scratch);
+    const budget = { bytes: 0 };
+    try {
+      // The work logs go to a private base of their own, whether or not the project has curated notes: the brief's work section opens a list read-write.
+      workBase = join(scratch, "work-base"); copyWork(options, workBase, budget);
+      if (!curatedPresent(options.home, options.project, layout)) {
+        duplicates = stale = index = skipped("no curated notes for this project yet");
+      } else {
+        const home = join(scratch, "home"); mkdirSync(home, { mode: 0o700 });
+        copyCurated(options, layout, home, budget);
+        const snapshotted = layout === "shared-v1" && snapshotIndex(options.home, join(home, "index.db"));
+        curated = options.openCurated(home);
+        const rows = curated.list({ project: options.project, limit: LIST_ALL });
+        await tick();
+        ({ duplicates, stale } = duplicatesAndStale(options, rows, curated));
+        await tick();
+        // The brief is measured after this and before the index proof's rebuild only because the brief reads rows, not the index tables.
+        index = indexSection(curated, layout, snapshotted);
+      }
+    } catch (error) {
+      copyFailed = error instanceof TooBig ? "the logs are over 64 MiB: the brief and the checks that need a copy were not run" : message(error);
+      workBase = undefined; duplicates = stale = index = unavailable(copyFailed);
+    }
+  } catch (error) { copyFailed = message(error); duplicates = stale = index = unavailable(copyFailed); }
+  await tick();
+  let candidates: Section;
+  try {
+    const summary = pendingSummary(options.home, [options.project, ...options.aliases], options.now, true);
+    candidates = summary === null ? unavailable("candidates.db exists but cannot be read")
+      : { status: summary.dueWithin7Days ? "attention" : "ok", ...summary, ...(summary.dueWithin7Days ? { hint: "run amem review walk" } : {}) };
+  } catch (error) { candidates = unavailable(message(error)); }
+  let sections: DoctorReport["sections"];
+  try {
+    await tick();
+    sections = { duplicates, stale, candidates, capture: captureSection(options), brief: await briefSection(options, curated, workBase, copyFailed), index, readers: readersSection(options), policy: policySection(options), cadence: cadenceSection(options) };
+    await tick();   // a signal that arrived during the last synchronous stage is handled while the guard is still installed
+  } finally { try { curated?.close(); } finally { try { if (scratch) rmSync(scratch, { recursive: true, force: true }); } finally { unguard?.(); } } }
+  return { schema: DOCTOR_SCHEMA, status: worst(Object.values(sections).map(section => section.status)), home: { path: options.home, source: options.homeSource }, project: options.project, sections };
+}
+
+export function doctorText(report: DoctorReport): string {
+  const mark = (status: SectionStatus) => status === "ok" ? "ok         " : status === "attention" ? "ATTENTION  " : status === "skipped" ? "skipped    " : "unavailable";
+  const lines = [`amem doctor: ${report.status}`, `home ${report.home.path} (${report.home.source}), project ${report.project}`];
+  for (const [name, section] of Object.entries(report.sections)) {
+    const { status, hint, reason, ...detail } = section as Section & { hint?: string; reason?: string };
+    lines.push(`${mark(status)} ${name}: ${JSON.stringify(detail)}${reason ? `  (${reason})` : ""}`);
+    if (hint) lines.push(`            -> ${hint}`);
+  }
+  return lines.join("\n");
+}

package/src/memory/editor.ts

@@ -0,0 +1,58 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Launch the person's editor on a private temporary file and return what they wrote. Import-light on purpose (node built-ins only).
+ *
+ * - `$VISUAL` then `$EDITOR`; an EMPTY `VISUAL` does not hide a set `EDITOR` (`||`, not `??`).
+ * - The command is run without a shell. A value that names an existing file is one command (so an editor path with a space works unquoted); otherwise it is split like a shell
+ *   would for quotes and backslashes only (`"/path with space/code" --wait`), with no expansion of variables, globs or substitutions.
+ * - SIGINT is ignored in this process while the editor runs (as git does), so Ctrl-C reaches the editor and not us: we are still here afterwards to remove the note text. A SIGKILL or
+ *   a power cut can still leave it, in a 0700 directory as a 0600 file, under the person's own temporary directory.
+ * - An editor that is killed by a signal, or exits non-zero, writes nothing.
+ */
+export interface EditorSpawn { (argv: string[]): { exitCode: number | null; signalCode?: string | number | null } }
+const spawnReal: EditorSpawn = argv => { const done = Bun.spawnSync(argv, { stdin: "inherit", stdout: "inherit", stderr: "inherit" }); return { exitCode: done.exitCode, signalCode: done.signalCode ?? null }; };
+
+export function splitCommand(command: string): string[] {
+  const out: string[] = [];
+  let current = "", started = false, quote: "'" | '"' | undefined;
+  for (let i = 0; i < command.length; i++) {
+    const c = command[i]!;
+    if (quote) {
+      if (c === quote) quote = undefined;
+      else if (c === "\\" && quote === '"' && (command[i + 1] === '"' || command[i + 1] === "\\")) current += command[++i];
+      else current += c;
+    } else if (c === "'" || c === '"') { quote = c; started = true; }
+    else if (c === "\\" && i + 1 < command.length) { current += command[++i]; started = true; }
+    else if (/\s/.test(c)) { if (started || current) { out.push(current); current = ""; started = false; } }
+    else { current += c; started = true; }
+  }
+  if (quote) throw new Error("the editor command has an unclosed quote");
+  if (started || current) out.push(current);
+  return out;
+}
+
+export function editorArgv(env: Readonly<Record<string, string | undefined>>, file: string): string[] {
+  const editor = (env.VISUAL?.trim() || env.EDITOR?.trim() || "");
+  if (!editor) throw new Error("no editor: set $VISUAL or $EDITOR, or pass the text as an argument");
+  const argv = existsSync(editor) ? [editor] : splitCommand(editor);
+  if (!argv.length) throw new Error("no editor: $VISUAL or $EDITOR names no command");
+  return [...argv, file];
+}
+
+export function runEditor(env: Readonly<Record<string, string | undefined>>, initial: string, spawn: EditorSpawn = spawnReal): string {
+  const dir = mkdtempSync(join(tmpdir(), "amem-note-")), file = join(dir, "note.txt");
+  const ignore = () => { /* Ctrl-C belongs to the editor while it runs */ };
+  try {
+    const argv = editorArgv(env, file);
+    writeFileSync(file, initial, { mode: 0o600 });
+    process.on("SIGINT", ignore);
+    let done: ReturnType<EditorSpawn>;
+    try { done = spawn(argv); } finally { process.off("SIGINT", ignore); }
+    if (done.signalCode !== null && done.signalCode !== undefined) throw new Error(`the editor was stopped by ${done.signalCode}; nothing was written`);
+    if (done.exitCode !== 0) throw new Error(`the editor exited with status ${done.exitCode ?? "unknown"}; nothing was written`);
+    return readFileSync(file, "utf8");
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+}