@staix/agent-mem 0.5.0 → 0.7.0

package/src/memory/candidate-pending.ts

@@ -0,0 +1,119 @@
+import { Database } from "bun:sqlite";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * F7 (agent-mem#40): pending-review visibility. This leaf imports only `bun:sqlite` and node built-ins, so the SessionStart hook can read it without loading the
+ * candidate store (no create, no prune, no schema change on that path).
+ *
+ * AC4, "no candidate expires without having been shown": a candidate's age expiry (30 days from creation) only deletes it once it was SHOWN, and not before a grace period after
+ * it was first shown, or once the person decided it (accepted or rejected). Only `amem review walk` stamps `shown_at`, after it has written the candidate to the terminal. The
+ * brief line and `amem review list` print no candidate content, and the SessionStart hook cannot know the context was read, so none of them stamps: the brief line informs, it does
+ * not count as showing. An unshown pending candidate stays however old it is. The 500-per-project count cap keeps unshown pending rows first, then shown pending rows (owed their
+ * grace), then decided ones, so it only reaches an unshown candidate when 500 of them wait.
+ */
+export const CANDIDATE_AGE_MS = 30 * 86400_000;
+/** After a candidate is first shown it stays at least this long, so the person has a real chance to act on what the brief said. */
+export const CANDIDATE_SHOWN_GRACE_MS = 7 * 86400_000;
+/** A candidate this close to expiry is flagged in `amem status`. */
+export const CANDIDATE_DUE_MS = 7 * 86400_000;
+const DAY_MS = 86400_000;
+
+export interface PendingSummary {
+  /** Candidates waiting for the person (status pending or an interrupted accepting). */
+  count: number;
+  /** Whole days until the soonest of them can expire, counting an unshown one as shown now (so at least the grace period). 0 when it may go today. Null with nothing pending. */
+  oldestExpiresInDays: number | null;
+  /** How many are within CANDIDATE_DUE_MS of their 30-day age expiry (an unshown one is protected beyond it, shown or not it is flagged so the person acts). */
+  dueWithin7Days: number;
+  /** How many were never shown. */
+  unshown: number;
+}
+export const EMPTY_PENDING: PendingSummary = { count: 0, oldestExpiresInDays: null, dueWithin7Days: 0, unshown: 0 };
+
+/**
+ * Open the sidecar read-only. A WAL database whose `-wal` and `-shm` files are gone (a truncating checkpoint, a copy) cannot be opened read-only, so the fallback is an immutable
+ * open: it writes nothing and creates nothing, at the price of not seeing a write another process has not checkpointed yet, which a count line can live with. Undefined when
+ * neither opens (a missing or unreadable file).
+ */
+function openReadOnly(file: string): Database | undefined {
+  // A construction that succeeds can still fail at its first read (no -wal or -shm to attach to), so each form is proven with a real query before it is returned.
+  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.query("SELECT 1 FROM sqlite_master LIMIT 1").get(); return db; }
+    catch { try { db?.close(); } catch { /* nothing to close */ } }
+  }
+  return undefined;
+}
+
+/** The first-shown column, added in place: an old database gets it when a `CandidateStore` opens, a reader treats its absence as "never shown". */
+export function hasShownColumn(db: Database): boolean {
+  return (db.query("PRAGMA table_info(candidates)").all() as { name: string }[]).some(column => column.name === "shown_at");
+}
+
+/** The instant a pending candidate becomes deletable: the later of its age expiry and the end of its grace period (counted from `now` while it is unshown). */
+export function expiresAt(createdAt: number, shownAt: number | null, now: number): number {
+  return Math.max(createdAt + CANDIDATE_AGE_MS, (shownAt ?? now) + CANDIDATE_SHOWN_GRACE_MS);
+}
+
+/**
+ * Read-only summary of the pending candidates of one project (with its aliases), or of every project when `projects` is undefined. Never throws. No file means nothing is
+ * pending (`EMPTY_PENDING`); a file that exists but cannot be read gives `null`, so `amem status` can say "unavailable" instead of a false zero.
+ */
+export function pendingSummary(base: string, projects: readonly string[] | undefined, now: number): PendingSummary;
+export function pendingSummary(base: string, projects: readonly string[] | undefined, now: number, strict: true): PendingSummary | null;
+export function pendingSummary(base: string, projects: readonly string[] | undefined, now: number, strict?: true): PendingSummary | null {
+  const file = join(base, "candidates.db");
+  if (!existsSync(file)) return EMPTY_PENDING;
+  const unreadable = strict ? null : EMPTY_PENDING;
+  let db: Database | undefined;
+  try {
+    db = openReadOnly(file);
+    if (!db) return unreadable;
+    db.run("PRAGMA busy_timeout = 0");
+    const shown = hasShownColumn(db);
+    const where = projects === undefined ? "" : " AND project IN (SELECT value FROM json_each(?))";
+    const rows = db.query(`SELECT at, ${shown ? "shown_at" : "NULL AS shown_at"} FROM candidates WHERE status IN ('pending', 'accepting')${where}`)
+      .all(...(projects === undefined ? [] : [JSON.stringify(projects)])) as { at: number; shown_at: number | null }[];
+    if (!rows.length) return EMPTY_PENDING;
+    let soonest = Infinity, due = 0, unshown = 0;
+    for (const row of rows) {
+      const at = expiresAt(row.at, row.shown_at, now);
+      soonest = Math.min(soonest, at);
+      if (row.at + CANDIDATE_AGE_MS - now <= CANDIDATE_DUE_MS) due++;   // by age: an unshown row is protected past it, but the person should hear it is old
+      if (row.shown_at === null) unshown++;
+    }
+    return { count: rows.length, oldestExpiresInDays: Math.max(0, Math.ceil((soonest - now) / DAY_MS)), dueWithin7Days: due, unshown };
+  } catch { return unreadable; }   // fail open: a locked or unreadable sidecar costs the brief this line, never the brief
+  finally { try { db?.close(); } catch { /* nothing to close */ } }
+}
+
+/** The one brief line. Numbers only, so it can carry no private text. */
+export function pendingLine(summary: PendingSummary): string | undefined {
+  if (!summary.count || summary.oldestExpiresInDays === null) return undefined;
+  const plural = (n: number, word: string) => `${n} ${word}${n === 1 ? "" : "s"}`;
+  return `${plural(summary.count, "candidate")} pending, oldest expires in ${plural(summary.oldestExpiresInDays, "day")}`;
+}
+
+/**
+ * Stamp the first time candidates were shown (`shown_at` stays at its first value). Best effort and zero-wait: on a locked, absent or pre-column database it stamps
+ * nothing, which only keeps candidates longer. Returns how many rows it stamped.
+ */
+export function markShown(base: string, projects: readonly string[], now: number, ids?: readonly string[]): number {
+  const file = join(base, "candidates.db");
+  if (!existsSync(file) || !projects.length) return 0;
+  let db: Database | undefined;
+  try {
+    db = new Database(file);
+    db.run("PRAGMA busy_timeout = 0");
+    if (!hasShownColumn(db)) return 0;
+    const filter = ids === undefined ? "" : " AND id IN (SELECT value FROM json_each(?))";
+    return db.query(`UPDATE candidates SET shown_at = ? WHERE shown_at IS NULL AND status IN ('pending', 'accepting') AND project IN (SELECT value FROM json_each(?))${filter}`)
+      .run(now, JSON.stringify(projects), ...(ids === undefined ? [] : [JSON.stringify(ids)])).changes;
+  } catch { return 0; }
+  finally { try { db?.close(); } catch { /* nothing to close */ } }
+}

package/src/memory/candidates.ts

@@ -2,9 +2,12 @@ import { Database } from "bun:sqlite";
 import { createHash } from "node:crypto";
 import { chmodSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
+import { CANDIDATE_SHOWN_GRACE_MS, hasShownColumn } from "./candidate-pending.ts";
+import { oneLine } from "./note-add.ts";
 import { memoryHome } from "./home.ts";
 import { realPath } from "./platform.ts";
-import { MemoryStore, type NoteInput, type View } from "./store.ts";
+import { stripPrivateDeep } from "./private-spans.ts";
+import { MemoryStore, type GoalView, type NoteInput, type View } from "./store.ts";
 
 export const CANDIDATE_DB_BUSY_TIMEOUT_MS = 3000;
 export const CANDIDATE_RETENTION = { count: 500, ageMs: 30 * 86400_000 } as const;
@@ -16,6 +19,7 @@ export type CandidateInput = { project: string } & (
   | { kind: "fail"; target?: CandidateTarget; approach: string; symptom: string; cause: string; evidenceRefs: string[]; retryWhen: string }
   | { kind: "memory"; text: string; title?: string; noteKind?: "decision" | "finding" | "contract" | "fail" }
   | { kind: "decay"; target: CandidateTarget; reason: string }
+  | { kind: "promotion"; target: CandidateTarget; goalId: string }
 );
 export type CandidateStatus = "pending" | "accepting" | "accepted" | "rejected";
 export interface Candidate { id: string; createdAt: string; status: CandidateStatus; input: CandidateInput; acceptedNoteId: string | null }
@@ -29,7 +33,7 @@ export interface CandidateAcceptance {
   actor: "person" | "agent";
   verdict: CandidateVerdict;
   store: MemoryStore;
-  policy: (candidate: Candidate, target: View | undefined, note: NoteInput) => boolean;
+  policy: (candidate: Candidate, target: View | undefined, note: NoteInput, goal?: GoalView) => boolean;
 }
 export interface CandidateAcceptanceResult { candidateId: string; noteId: string; alreadyAccepted: boolean }
 
@@ -53,12 +57,28 @@ function validate(input: CandidateInput): void {
     if (input.target !== undefined && !validTarget(input.target) || ![input.approach, input.symptom, input.cause, input.retryWhen].every(x => text(x)) || !Array.isArray(input.evidenceRefs) || input.evidenceRefs.length < 1 || input.evidenceRefs.length > 16 || !input.evidenceRefs.every(x => text(x, 400))) throw new Error("invalid fail candidate");
   } else if (input.kind === "memory") {
     if (!text(input.text, 3000) || input.title !== undefined && !text(input.title, 200) || input.noteKind !== undefined && !["decision", "finding", "contract", "fail"].includes(input.noteKind)) throw new Error("invalid memory candidate");
+  } else if (input.kind === "promotion") {
+    if (!validTarget(input.target) || !entryId(input.goalId)) throw new Error("invalid promotion candidate");
   } else if (input.kind === "decay") {
     if (!validTarget(input.target) || !text(input.reason)) throw new Error("invalid decay candidate");
   } else throw new Error("invalid candidate kind");
   if (Buffer.byteLength(canonical(input), "utf8") > 16_384) throw new Error("candidate payload exceeds 16 KiB");
 }
 
+/** The same normalized identity used by put(), without a sidecar write or a capped listing. */
+export function candidateInputId(rawInput: CandidateInput): string {
+  const input = stripPrivateDeep(rawInput); validate(input);
+  return hash({ schema: "agent-mem.candidate/v1", input });
+}
+/** Exact correction body shared by proposal validation and person acceptance. */
+export function acceptedCorrectionText(input: Extract<CandidateInput, { kind: "correction" }>, id = candidateInputId(input)): string {
+  const data = stripPrivateDeep(input);
+  return `Accepted candidate: ${id}\nTarget revision: ${data.target.revision}\nTarget entry: ${data.target.id}\n\n${data.proposedText}\n\nReason: ${data.reason}`;
+}
+export function goalPromotionLinked(view: Pick<View, "task" | "about">, goal: Pick<GoalView, "id" | "links">): boolean {
+  const tasks = new Set(goal.links.map(link => link.task));
+  return !!view.task && tasks.has(view.task) || view.about.some(node => node === `goal:${goal.id}` || node.startsWith("task:") && tasks.has(node.slice(5)));
+}
 /** Includes current lifecycle state, so a changed promotion, supersession or demotion makes a proposal stale. */
 export function candidateTargetRevision(target: View): string {
   return hash({ ...target, about: [...target.about].sort(), supersedes: [...target.supersedes].sort() });
@@ -71,6 +91,23 @@ function counterKey(key: CounterKey): CounterKey {
 }
 
 /** Explicitly opened machine-local data. Importing this module never opens a store or registers a consumer. */
+/** Run `work`, retrying only SQLite's "database is locked" for at most about two seconds; any other error, or the last lock error, is thrown. */
+function retryLocked(work: () => void): void {
+  const until = Date.now() + 2000;
+  for (let delay = 5;; delay = Math.min(delay * 2, 100)) {
+    try { work(); return; }
+    catch (error) {
+      if (!/database is locked|SQLITE_BUSY/i.test((error as Error).message) || Date.now() >= until) throw error;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, delay);
+    }
+  }
+}
+
+/** The queue holds the cap's worth of candidates nobody has seen. Named so a caller (the MCP tool) can map it; the message is worded for an agent, which cannot run the person-only commands itself. */
+export class CandidateQueueFull extends Error {
+  readonly code = "candidate_queue_full";
+  constructor(readonly waiting: number) { super(`${waiting} unshown candidates await the person's review; no more are accepted until they have run \`amem review\`. Ask the person to review them`); this.name = "CandidateQueueFull"; }
+}
 export class CandidateStore {
   readonly dir: string;
   readonly path: string;
@@ -88,18 +125,27 @@ export class CandidateStore {
     this.path = join(this.dir, "candidates.db");
     this.db = new Database(this.path, { create: true });
     this.db.run(`PRAGMA busy_timeout = ${CANDIDATE_DB_BUSY_TIMEOUT_MS}`);
-    chmodSync(this.path, 0o600); this.db.run("PRAGMA journal_mode = WAL");
+    chmodSync(this.path, 0o600);
+    // `journal_mode = WAL` takes a lock that busy_timeout does not always wait for, so several processes opening a brand-new home at once (every `amem mcp` builds this store at
+    // startup) can see "database is locked". It is retried for a bounded time: the first caller switches the mode, the others then find it already WAL.
+    retryLocked(() => this.db.run("PRAGMA journal_mode = WAL"));
     this.db.run("CREATE TABLE IF NOT EXISTS candidates (id TEXT PRIMARY KEY, project TEXT NOT NULL, kind TEXT NOT NULL, payload TEXT NOT NULL, at INTEGER NOT NULL, status TEXT NOT NULL, note_id TEXT)");
+    // F7 / AC4: when a candidate was first shown to the person. In place and nullable: an older database gains it here, and a reader without it treats every row as unshown.
+    // Several processes open this store at once (every `amem mcp` builds it at startup), so the check and the ALTER are one immediate transaction: the loser waits, then sees the column.
+    if (!hasShownColumn(this.db)) this.db.transaction(() => { if (!hasShownColumn(this.db)) this.db.run("ALTER TABLE candidates ADD COLUMN shown_at INTEGER"); }).immediate();
     this.db.run("CREATE TABLE IF NOT EXISTS counters (id TEXT PRIMARY KEY, project TEXT NOT NULL, payload TEXT NOT NULL, at INTEGER NOT NULL, rendered INTEGER, delivered INTEGER, cited INTEGER)");
     this.prune();
   }
   close(): void { this.db.close(); }
   private prune(): void {
     this.db.transaction(() => {
-      for (const [table, retention] of [["candidates", CANDIDATE_RETENTION], ["counters", COUNTER_RETENTION]] as const) {
-        this.db.query(`DELETE FROM ${table} WHERE at <= ?`).run(this.now() - retention.ageMs);
-        this.db.query(`DELETE FROM ${table} WHERE rowid IN (SELECT rowid FROM (SELECT rowid, row_number() OVER (PARTITION BY project ORDER BY at DESC, rowid DESC) AS rank FROM ${table}) WHERE rank > ?)`).run(retention.count);
-      }
+      const now = this.now();
+      // Candidates (AC4, no candidate expires unshown): by age only a decided one, or a pending one that was shown and has had its grace period, goes. By count three tiers decide who is
+      // kept: unshown pending first, then shown pending, then decided, so a cap eviction takes decided rows before a shown one (which is owed its grace) and shown ones before an unseen one.
+      this.db.query("DELETE FROM candidates WHERE at <= ? AND (status IN ('accepted', 'rejected') OR (shown_at IS NOT NULL AND shown_at <= ?))").run(now - CANDIDATE_RETENTION.ageMs, now - CANDIDATE_SHOWN_GRACE_MS);
+      this.db.query(`DELETE FROM candidates WHERE rowid IN (SELECT rowid FROM (SELECT rowid, row_number() OVER (PARTITION BY project ORDER BY CASE WHEN status IN ('pending', 'accepting') AND shown_at IS NULL THEN 2 WHEN status IN ('pending', 'accepting') THEN 1 ELSE 0 END DESC, at DESC, rowid DESC) AS rank FROM candidates) WHERE rank > ?)`).run(CANDIDATE_RETENTION.count);
+      this.db.query("DELETE FROM counters WHERE at <= ?").run(now - COUNTER_RETENTION.ageMs);
+      this.db.query("DELETE FROM counters WHERE rowid IN (SELECT rowid FROM (SELECT rowid, row_number() OVER (PARTITION BY project ORDER BY at DESC, rowid DESC) AS rank FROM counters) WHERE rank > ?)").run(COUNTER_RETENTION.count);
     }).immediate();
   }
   private decode(row: { id: string; payload: string; at: number; status: CandidateStatus; note_id: string | null }): Candidate {
@@ -107,11 +153,22 @@ export class CandidateStore {
     if (hash({ schema: "agent-mem.candidate/v1", input }) !== row.id) throw new Error("candidate content hash mismatch");
     return { id: row.id, createdAt: new Date(row.at).toISOString(), status: row.status, input, acceptedNoteId: row.note_id };
   }
-  put(input: CandidateInput, verdict: CandidateVerdict): string {
-    publicOnly(verdict); validate(input); this.prune();
-    const payload = canonical(input), id = hash({ schema: "agent-mem.candidate/v1", input });
-    this.db.query("INSERT OR IGNORE INTO candidates (id, project, kind, payload, at, status) VALUES (?, ?, ?, ?, ?, 'pending')").run(id, input.project, input.kind, payload, this.now());
-    this.prune(); return id;
+  put(rawInput: CandidateInput, verdict: CandidateVerdict): string {
+    // `<private>` spans are never stored: dropped before the input is validated, hashed (so the id) or written.
+    const input = stripPrivateDeep(rawInput);
+    publicOnly(verdict); validate(input);
+    const payload = canonical(input), id = candidateInputId(input);
+    // Prune, count, insert and prune again are ONE immediate transaction: concurrent proposers (several agents) cannot all pass the count and then let the cap evict an unseen candidate.
+    return this.db.transaction((): string => {
+      this.prune();
+      // AC4: a new candidate never pushes an unshown one out. With the cap's worth waiting the person has to review first, and the refusal says so (a named error an MCP tool can map).
+      const waiting = (this.db.query("SELECT COUNT(*) AS n FROM candidates WHERE project = ? AND status IN ('pending', 'accepting') AND shown_at IS NULL").get(input.project) as { n: number }).n;
+      const known = this.db.query("SELECT 1 FROM candidates WHERE id = ?").get(id);
+      if (!known && waiting >= CANDIDATE_RETENTION.count) throw new CandidateQueueFull(waiting);
+      this.db.query("INSERT OR IGNORE INTO candidates (id, project, kind, payload, at, status) VALUES (?, ?, ?, ?, ?, 'pending')").run(id, input.project, input.kind, payload, this.now());
+      this.prune();
+      return id;
+    }).immediate();
   }
   get(id: string, project: string): Candidate | undefined {
     if (!candidateId(id) || !text(project, 400)) throw new Error("invalid candidate identity");
@@ -120,7 +177,7 @@ export class CandidateStore {
     return row ? this.decode(row) : undefined;
   }
   list(filter: CandidateFilter): Candidate[] {
-    if (!text(filter.project, 400) || filter.status !== undefined && !["pending", "accepting", "accepted", "rejected", "all"].includes(filter.status) || filter.kind !== undefined && !["correction", "fail", "decay", "memory"].includes(filter.kind)) throw new Error("invalid candidate filter");
+    if (!text(filter.project, 400) || filter.status !== undefined && !["pending", "accepting", "accepted", "rejected", "all"].includes(filter.status) || filter.kind !== undefined && !["correction", "fail", "decay", "memory", "promotion"].includes(filter.kind)) throw new Error("invalid candidate filter");
     const limit = filter.limit ?? CANDIDATE_RETENTION.count;
     if (!Number.isSafeInteger(limit) || limit < 1 || limit > CANDIDATE_RETENTION.count) throw new Error("candidate limit must be 1..500");
     this.prune();
@@ -163,42 +220,82 @@ export class CandidateStore {
     if (!candidate) throw new Error("candidate unavailable");
     if (candidate.status === "accepted") return { candidateId: id, noteId: candidate.acceptedNoteId!, alreadyAccepted: true };
     if (candidate.status !== "pending") throw new Error("candidate is rejected or acceptance was interrupted; no automatic replay");
-    if (candidate.input.kind === "decay") throw new Error("decay candidates are listing-only; no automatic mutation is available");
+    const data = candidate.input;
+    if (data.kind === "decay") throw new Error("decay candidates are listing-only; no automatic mutation is available");
+    if (data.kind === "promotion") return this.acceptPromotion(candidate, data, context);
+    const execute = () => {
+      const resolve = () => {
+        const target = data.kind === "memory" ? undefined : data.target;
+        if (!target) return undefined;
+        const current = context.store.get(target.id, context.project);
+        if (!current || current.id !== target.id || candidateTargetRevision(current) !== target.revision) throw new Error("candidate target revision is stale");
+        return current;
+      };
+      const target = resolve();
+      const body = data.kind === "memory" ? data.text : data.kind === "correction" ? `${data.proposedText}\n\nReason: ${data.reason}`
+        : `Approach: ${oneLine(data.approach)}\nSymptom: ${oneLine(data.symptom)}\nCause: ${oneLine(data.cause)}\nEvidence: ${data.evidenceRefs.map(oneLine).join(", ")}\nRetry when: ${oneLine(data.retryWhen)}`;
+      const note: NoteInput = { op: "note", ...(data.kind === "memory" && data.title ? { title: data.title } : {}), project: data.kind === "correction" ? target!.project : context.project,
+        scope: data.kind === "correction" ? target!.scope : "project",
+        // A demoted synced target is logically short, but replacing it locally would narrow its reach (X04).
+        tier: data.kind === "correction" && target!.local ? "short" : "long",
+        kind: data.kind === "fail" ? "fail" : data.noteKind ?? (target?.kind === "contract" || target?.kind === "fail" ? target.kind : "decision"), peer: "person", source: "person", about: [...target?.about ?? []],
+        text: data.kind === "correction" ? acceptedCorrectionText(data, id) : `Accepted candidate: ${id}\nTarget revision: ${(data.kind === "memory" ? undefined : data.target)?.revision ?? "none"}\nTarget entry: ${(data.kind === "memory" ? undefined : data.target)?.id ?? "none"}\n\n${body}` };
+      if (note.text.length > 4000) throw new Error("accepted candidate text exceeds the v1 note limit");
+      if (context.policy(structuredClone(candidate), target && structuredClone(target), structuredClone(note)) !== true) throw new Error("candidate refused by current host policy");
+      return context.store.withAcceptedNote(note, append => {
+        resolve(); // Recheck under the same mutation lock as the note and supersede appends.
+        const started = this.beginAcceptance(id, context.project);
+        if (started) return { candidateId: id, noteId: started, alreadyAccepted: true };
+        // ponytail: the sidecar receipt and v1 append are not one transaction. An interrupted 'accepting' row refuses
+        // automatic replay; add explicit person-audited recovery before offering background acceptance retries.
+        const noteId = append();
+        if (data.kind === "correction" && !context.store.supersede(target!.id, noteId, "person", context.project)) throw new Error("candidate replacement refused; inspect the accepted note before recovery");
+        this.db.query("UPDATE candidates SET status = 'accepted', note_id = ? WHERE id = ? AND project IN (SELECT value FROM json_each(?))").run(noteId, id, this.scope(context.project));
+        return { candidateId: id, noteId, alreadyAccepted: false };
+      });
+    };
+    const target = data.kind === "memory" ? undefined : data.target;
+    if (!target) return execute();
+    const current = context.store.get(target.id, context.project);
+    if (!current || current.id !== target.id || candidateTargetRevision(current) !== target.revision) throw new Error("candidate target revision is stale");
+    return context.store.withCurrentEntries([target.id], context.project, execute);
+  }
+  private acceptPromotion(candidate: Candidate, data: Extract<CandidateInput, { kind: "promotion" }>, context: CandidateAcceptance): CandidateAcceptanceResult {
     const resolve = () => {
-      const target = candidate.input.kind === "memory" ? undefined : candidate.input.target;
-      if (!target) return undefined;
-      const current = context.store.get(target.id, context.project);
-      if (!current || current.id !== target.id || candidateTargetRevision(current) !== target.revision) throw new Error("candidate target revision is stale");
-      return current;
+      const target = context.store.get(data.target.id, context.project);
+      if (!target || target.id !== data.target.id || candidateTargetRevision(target) !== data.target.revision || target.tier !== "short" || target.supersededBy) throw Error("candidate target revision is stale");
+      const goal = context.store.goalOf(data.goalId, context.project);
+      if (!goal || goal.id !== data.goalId || goal.state !== "done" || !goalPromotionLinked(target, goal)) throw Error("promotion requires a current done goal and a linked short note");
+      return { target, goal };
     };
-    const target = resolve(), data = candidate.input;
-    const body = data.kind === "memory" ? data.text : data.kind === "correction" ? `${data.proposedText}\n\nReason: ${data.reason}`
-      : `Approach: ${data.approach}\nSymptom: ${data.symptom}\nCause: ${data.cause}\nEvidence: ${data.evidenceRefs.join(", ")}\nRetry when: ${data.retryWhen}`;
-    const note: NoteInput = { op: "note", ...(data.kind === "memory" && data.title ? { title: data.title } : {}), project: data.kind === "correction" ? target!.project : context.project,
-      scope: data.kind === "correction" ? target!.scope : "project",
-      // A demoted synced target is logically short, but replacing it locally would narrow its reach (X04).
-      tier: data.kind === "correction" && target!.local ? "short" : "long",
-      kind: data.kind === "fail" ? "fail" : data.noteKind ?? (target?.kind === "contract" || target?.kind === "fail" ? target.kind : "decision"), peer: "person", source: "person", about: [...target?.about ?? []],
-      text: `Accepted candidate: ${id}\nTarget revision: ${(data.kind === "memory" ? undefined : data.target)?.revision ?? "none"}\nTarget entry: ${(data.kind === "memory" ? undefined : data.target)?.id ?? "none"}\n\n${body}` };
-    if (note.text.length > 4000) throw new Error("accepted candidate text exceeds the v1 note limit");
-    if (context.policy(structuredClone(candidate), target && structuredClone(target), structuredClone(note)) !== true) throw new Error("candidate refused by current host policy");
-    return context.store.withAcceptedNote(note, append => {
-      resolve(); // Recheck under the same mutation lock as the note and supersede appends.
-      const started = this.db.transaction(() => {
-        const current = this.get(id, context.project);
-        if (!current) throw new Error("candidate unavailable");
-        if (current.status === "accepted") return current.acceptedNoteId!;
-        if (current.status !== "pending") throw new Error("candidate is rejected or acceptance was interrupted; no automatic replay");
-        this.db.query("UPDATE candidates SET status = 'accepting' WHERE id = ? AND project IN (SELECT value FROM json_each(?))").run(id, this.scope(context.project));
-        return undefined;
-      }).immediate();
-      if (started) return { candidateId: id, noteId: started, alreadyAccepted: true };
-      // ponytail: the sidecar receipt and v1 append are not one transaction. An interrupted 'accepting' row refuses
-      // automatic replay; add explicit person-audited recovery before offering background acceptance retries.
-      const noteId = append();
-      if (data.kind === "correction" && !context.store.supersede(target!.id, noteId, "person", context.project)) throw new Error("candidate replacement refused; inspect the accepted note before recovery");
-      this.db.query("UPDATE candidates SET status = 'accepted', note_id = ? WHERE id = ? AND project IN (SELECT value FROM json_each(?))").run(noteId, id, this.scope(context.project));
-      return { candidateId: id, noteId, alreadyAccepted: false };
+    resolve();
+    return context.store.withCurrentEntries([data.target.id], context.project, () => {
+      const { target, goal } = resolve();
+      const note: NoteInput = { op: "note", project: target.project, scope: target.scope, tier: "long", kind: target.kind, peer: target.peer, source: target.source as NoteInput["source"], text: target.text, about: [...target.about],
+        ...(target.title ? { title: target.title } : {}), ...(target.task ? { task: target.task } : {}), promotedFrom: target.id };
+      if (context.policy(structuredClone(candidate), structuredClone(target), structuredClone(note), structuredClone(goal)) !== true) throw Error("candidate refused by current host policy");
+      resolve();
+      const replay = this.beginAcceptance(candidate.id, context.project); if (replay) return { candidateId: candidate.id, noteId: replay, alreadyAccepted: true };
+      // A thrown append remains accepting: its authored-row outcome needs person-audited recovery.
+      const noteId = context.store.promote(target.id, "person", context.project);
+      if (noteId === undefined) {
+        this.db.query("UPDATE candidates SET status = 'pending' WHERE id = ? AND project IN (SELECT value FROM json_each(?)) AND status = 'accepting'").run(candidate.id, this.scope(context.project));
+        throw Error("promotion unavailable or declined; candidate remains pending");
+      }
+      const promoted = context.store.get(noteId, context.project);
+      if (noteId === target.id || !promoted || promoted.id !== noteId || promoted.tier !== "long" || promoted.promotedFrom !== target.id) throw Error("promotion outcome unconfirmed; inspect the accepting candidate");
+      this.db.query("UPDATE candidates SET status = 'accepted', note_id = ? WHERE id = ? AND project IN (SELECT value FROM json_each(?))").run(noteId, candidate.id, this.scope(context.project));
+      return { candidateId: candidate.id, noteId, alreadyAccepted: false };
     });
   }
+  private beginAcceptance(id: string, project: string): string | undefined {
+    return this.db.transaction(() => {
+      const current = this.get(id, project);
+      if (!current) throw Error("candidate unavailable");
+      if (current.status === "accepted") return current.acceptedNoteId!;
+      if (current.status !== "pending") throw Error("candidate is rejected or acceptance was interrupted; no automatic replay");
+      this.db.query("UPDATE candidates SET status = 'accepting' WHERE id = ? AND project IN (SELECT value FROM json_each(?))").run(id, this.scope(project));
+      return undefined;
+    }).immediate();
+  }
 }

package/src/memory/capacity-split.ts

@@ -0,0 +1,76 @@
+import { lstatSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { capacityReport, type ShardSplit } from "./capacity.ts";
+import { readCaptureConfigFile, writeCaptureConfigFile, type CaptureConfig } from "./capture.ts";
+import { walkShards } from "./catalog.ts";
+import { lifecycleResolver } from "./lifecycle.ts";
+import { machineId } from "./store.ts";
+
+/**
+ * #15 T5 / D7: `amem capacity apply --split`. Writes each shard's own capture config (`machine/<id>/config.json`, which overrides the home default) with its
+ * share of the global budget. Person-only like the other apply (the CLI refuses an agent marker and a missing terminal before this runs), and in two steps:
+ * a preview that records which shards, which current configs and which target values the person is shown, and a `--confirm` that writes exactly those
+ * target values and nothing recomputed. It refuses unless the set of shards and every shard's current config are unchanged, and unless the preview is younger
+ * than `PREVIEW_MAX_AGE_MS`: a week-old preview cannot write a cap the person never saw, and free disk drifting a little between the two steps changes nothing
+ * that is written. A forgotten shard is never written. This changes capture bounds only: gc and the capture path apply them later, in bounded
+ * batches (R2); nothing is evicted here, and no curated note, goal or work list is read or written.
+ */
+
+export interface SplitTarget { key: string; dir: string; current: Partial<CaptureConfig>; target: CaptureConfig; reason: string }
+export interface SplitPreview { at: number; split: SplitTarget[]; skipped: string[] }
+/** A preview older than this is refused: the person saw those values, but the readings behind them are stale. */
+export const PREVIEW_MAX_AGE_MS = 3600_000;
+
+const previewPath = (base: string): string => join(base, "capacity-split.preview.json");
+
+/**
+ * One target per non-forgotten shard that has a directory of this machine. A shard that only another machine has (a synced home) is never written here: that
+ * machine's config is its own, so the shard is left out and named in `skipped`. The directory is matched by its name, which is portable, not by a path suffix.
+ */
+function targets(base: string, split: ShardSplit[]): { targets: SplitTarget[]; skipped: string[] } {
+  const dirs = new Map(walkShards(base).map(shard => [shard.key, shard.machineDirs]));
+  const stateOf = lifecycleResolver(base);
+  const machine = machineId(base).id;
+  const out: SplitTarget[] = [], skipped: string[] = [];
+  for (const row of split) {
+    if (stateOf(row.key) === "forgotten") continue;
+    const dir = (dirs.get(row.key) ?? []).find(candidate => basename(candidate) === machine);
+    if (!dir) { skipped.push(row.key); continue; }
+    out.push({ key: row.key, dir, current: readCaptureConfigFile(join(dir, "config.json")), target: { capMb: row.capMb, retentionDays: row.retentionDays }, reason: row.reason });
+  }
+  return { targets: out, skipped };
+}
+
+export function previewSplit(base: string, opts: { diskShare?: number; now?: () => number } = {}): SplitPreview & { confirm: string } {
+  const report = capacityReport({ memoryDir: base, ...(opts.diskShare !== undefined ? { diskShare: opts.diskShare } : {}) });
+  if (report.splitRefused) throw new Error(`capacity apply --split: ${report.splitRefused}`);
+  const found = targets(base, report.split);
+  const preview: SplitPreview = { at: (opts.now ?? Date.now)(), split: found.targets, skipped: found.skipped };
+  writeFileSync(previewPath(base), JSON.stringify(preview) + "\n", { mode: 0o600 });
+  return { ...preview, confirm: "re-run with --confirm to write each shard's share" };
+}
+
+export function applySplit(base: string, opts: { diskShare?: number; now?: () => number } = {}): { split: SplitTarget[]; written: { key: string; cap_mb: number; retention_days: number }[] } {
+  const file = previewPath(base);
+  let approved: SplitPreview;
+  try {
+    const stat = lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1024 * 1024) throw new Error();
+    approved = JSON.parse(readFileSync(file, "utf8")) as SplitPreview;
+  } catch { throw new Error("capacity apply --split needs a preview first; re-run without --confirm"); }
+  const report = capacityReport({ memoryDir: base, ...(opts.diskShare !== undefined ? { diskShare: opts.diskShare } : {}) });
+  if (report.splitRefused) throw new Error(`capacity apply --split: ${report.splitRefused}`);
+  const live = targets(base, report.split).targets;
+  const age = (opts.now ?? Date.now)() - approved.at;
+  if (!Number.isFinite(age) || age < 0 || age > PREVIEW_MAX_AGE_MS) throw new Error("capacity preview is out of date (older than an hour); re-run without --confirm");
+  // What was previewed is what is written: the same shards, each with the config the person saw replaced by the target the person saw.
+  const identity = (rows: SplitTarget[]) => JSON.stringify(rows.map(({ key, dir, current }) => ({ key, dir, current })));
+  if (!Array.isArray(approved.split) || identity(approved.split) !== identity(live)) throw new Error("capacity preview changed (a shard appeared or went, or a shard's config moved); re-run without --confirm");
+  const written = approved.split.map(row => {
+    const next = writeCaptureConfigFile(join(row.dir, "config.json"), row.target);
+    return { key: row.key, cap_mb: next.capMb ?? row.target.capMb, retention_days: next.retentionDays ?? row.target.retentionDays };
+  });
+  rmSync(file, { force: true });
+  return { split: approved.split, written };
+}
+