@staix/agent-mem 0.6.0 → 0.7.0

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 };
+}
+

package/src/memory/capacity.ts

@@ -6,6 +6,7 @@ import { memoryBase } from "./home.ts";
 import { readMetrics, type MetricSample } from "./metrics.ts";
 export { appendMetrics, readMetrics, metricsPath, type MetricSample } from "./metrics.ts";
 import { walkShards } from "./catalog.ts";
+import { lifecycleResolver } from "./lifecycle.ts";
 import { captureShardGrowth, captureShardStats, readCaptureConfigFile, CAPTURE_DEFAULT_CAP_MB, CAPTURE_DEFAULT_RETENTION_DAYS, type CaptureConfig } from "./capture.ts";
 
 /**
@@ -59,6 +60,116 @@ export interface CapacityReport {
   current: CaptureConfig;
   diskShare: number;
   proposal: { capMb: number; retentionDays: number; reason: string };
+  /** #15 D7: the per-shard split of the global capture budget (the disk share, less what forgotten shards still hold), one row per non-forgotten shard. A proposal: applying it is person-only. */
+  split: ShardSplit[];
+  /** Why `split` is empty although shards exist: the budget cannot give each shard its 1 MB minimum. Absent when the split was made. */
+  splitRefused?: string;
+}
+
+export interface ShardSplit { key: string; capMb: number; retentionDays: number; reason: string }
+export interface SplitInput {
+  /** The global capture budget in bytes: the disk-share bound the single-shard advisor already uses. */
+  budgetBytes: number;
+  shards: { key: string; useBytes: number; growthBytesPerDay: number; lastAt: string | null }[];
+  now: number;
+}
+
+const ACTIVITY_HALF_LIFE_DAYS = 14, ACTIVITY_FLOOR = 0.02, SPLIT_HORIZON_DAYS = 30;
+// ponytail: a quiet shard keeps its last month of rows, counted from its last capture, so a proposal never empties a shard that merely went quiet (gc evicts by
+// age from now). That floor is the one case allowed above the year ceiling: a shard idle for more than 335 days keeps idle days plus the floor. The upgrade path is a configured floor.
+const SPLIT_RETENTION_FLOOR_DAYS = 30;
+
+/** Share `amount` whole MB over `items` in proportion to weight x want, no item above its want (a bounded water-fill); the shares sum to at most `amount`. */
+function waterFill(items: { key: string; weight: number; want: number }[], amount: number): Map<string, number> {
+  const out = new Map<string, number>(items.map(item => [item.key, 0]));
+  let free = items.filter(item => item.want > 0), remaining = amount;
+  for (let guard = 0; guard <= items.length && free.length; guard++) {
+    const total = free.reduce((sum, item) => sum + item.weight * item.want, 0);
+    const share = (item: (typeof items)[number]) => remaining * item.weight * item.want / total;
+    const high = free.filter(item => share(item) > item.want);
+    if (high.length) { for (const item of high) { out.set(item.key, item.want); remaining -= item.want; } free = free.filter(item => !high.includes(item)); continue; }
+    for (const item of free) out.set(item.key, Math.floor(share(item)));
+    break;
+  }
+  return out;
+}
+
+/**
+ * #15 D7: split one global capture budget across shards. Only capture is in it: the inputs are capture bytes, capture growth and the last capture time,
+ * so curated notes, goals and work lists have no quantity here to evict.
+ *
+ * Each shard has an activity weight, 0.5 per 14 days since its last capture (a shard with none counts as a year cold), plus a small floor. What a shard needs
+ * is what it holds now plus 30 days of its growth scaled by that weight. Three cases, by what fits:
+ * 1. every need fits: each shard gets its need and the surplus goes by weight.
+ * 2. every shard's use fits but not every need: each shard gets its use first (rounded up to whole MB, at least 1), and only the headroom is shared, by weight times
+ *    the growth it asked for, so a cold shard keeps what it holds and a hot one gets the room.
+ * 3. the use itself does not fit: the budget is shared by weight times need, between 1 MB and the need, so cold shards shrink first, and a shard pushed
+ *    below what it holds says so.
+ * The caps are whole MB, each at least 1 (a cap of 0 is not a bound), and their sum never exceeds the budget. When the budget holds fewer whole MB than there are shards, no split can
+ * satisfy both, so the function refuses with `SplitBudgetError` instead of returning an over-budget proposal.
+ * A shard's retention is the activity window, but never shorter than its idle time plus a month: gc counts age from now, so a shorter window would delete rows the shard still holds.
+ */
+/** The budget cannot give every shard its 1 MB minimum: there is no valid split to propose. */
+export class SplitBudgetError extends Error {}
+
+export function capacitySplit(input: SplitInput): ShardSplit[] {
+  if (!Number.isFinite(input.budgetBytes) || input.budgetBytes < 0) throw new Error("the capture budget must be a finite number of bytes, zero or more");
+  if (!Number.isFinite(input.now)) throw new Error("the split needs a clock");
+  for (const shard of input.shards) {
+    if (!Number.isFinite(shard.useBytes) || shard.useBytes < 0) throw new Error(`shard use must be a finite number of bytes, zero or more (${shard.key})`);
+    if (!Number.isFinite(shard.growthBytesPerDay) || shard.growthBytesPerDay < 0) throw new Error(`shard growth must be a finite number of bytes per day, zero or more (${shard.key})`);
+  }
+  const shards = [...input.shards].sort((a, b) => a.key.localeCompare(b.key));
+  if (!shards.length) return [];
+  const budgetMb = Math.floor(input.budgetBytes / MB);
+  if (budgetMb < shards.length) throw new SplitBudgetError(`the capture budget holds ${budgetMb} MB, fewer than the ${shards.length} shards that each need a 1 MB minimum; free disk or raise --disk-share before splitting`);
+  const rows = shards.map((shard) => {
+    const lastMs = shard.lastAt === null ? Number.NaN : Date.parse(shard.lastAt);
+    const known = Number.isFinite(lastMs), days = known ? Math.max(0, (input.now - lastMs) / (24 * 3600_000)) : 365;
+    const activity = Math.pow(0.5, days / ACTIVITY_HALF_LIFE_DAYS);
+    const weight = activity + ACTIVITY_FLOOR;
+    const useMb = shard.useBytes / MB, growthMb = shard.growthBytesPerDay / MB;
+    const base = Math.max(1, Math.ceil(useMb)), need = Math.max(base, Math.ceil(useMb + growthMb * SPLIT_HORIZON_DAYS * activity));
+    const windowDays = Math.round(SPLIT_RETENTION_FLOOR_DAYS + (RETENTION_CEILING_DAYS - SPLIT_RETENTION_FLOOR_DAYS) * activity);
+    // A shard with no capture time holds no row to protect; the idle floor applies to a known last capture only.
+    const retentionDays = Math.max(windowDays, known ? Math.ceil(days) + SPLIT_RETENTION_FLOOR_DAYS : 0);
+    return { key: shard.key, useMb, activity, weight, base, need, retentionDays, cap: 1 };
+  });
+  const totalNeed = rows.reduce((sum, row) => sum + row.need, 0), totalBase = rows.reduce((sum, row) => sum + row.base, 0);
+  const reasons = new Map<string, string>();
+  if (totalNeed <= budgetMb) {
+    const surplus = budgetMb - totalNeed, totalWeight = rows.reduce((sum, row) => sum + row.weight, 0);
+    for (const row of rows) {
+      row.cap = row.need + Math.floor(surplus * row.weight / totalWeight);
+      reasons.set(row.key, `fits the budget: keeps its ${row.useMb.toFixed(1)} MB in use plus growth headroom for ${SPLIT_HORIZON_DAYS} days at its recent activity (weight ${row.activity.toFixed(2)})`);
+    }
+  } else if (totalBase <= budgetMb) {
+    const extra = waterFill(rows.map(row => ({ key: row.key, weight: row.weight, want: row.need - row.base })), budgetMb - totalBase);
+    for (const row of rows) {
+      row.cap = row.base + (extra.get(row.key) ?? 0);
+      reasons.set(row.key, `budget is tight: keeps the ${row.useMb.toFixed(1)} MB it holds, and its growth headroom is shared by recent activity (weight ${row.activity.toFixed(2)})`);
+    }
+  } else {
+    // The use itself does not fit: shares by weight x need, between 1 MB and the need; fix the violators of one bound at a time and share what is left.
+    let free = [...rows], remaining = budgetMb;
+    const fixed = new Map<string, number>();
+    for (let guard = 0; guard <= rows.length && free.length; guard++) {
+      const total = free.reduce((sum, row) => sum + row.weight * row.need, 0);
+      const share = (row: (typeof rows)[number]) => remaining * row.weight * row.need / total;
+      const low = free.filter(row => share(row) < 1), high = free.filter(row => share(row) > row.need);
+      if (low.length) { for (const row of low) { fixed.set(row.key, 1); remaining -= 1; } free = free.filter(row => !low.includes(row)); continue; }
+      if (high.length) { for (const row of high) { fixed.set(row.key, row.need); remaining -= row.need; } free = free.filter(row => !high.includes(row)); continue; }
+      for (const row of free) fixed.set(row.key, Math.max(1, Math.floor(share(row))));
+      free = [];
+    }
+    for (const row of rows) {
+      row.cap = fixed.get(row.key) ?? 1;
+      reasons.set(row.key, row.cap < row.useMb
+        ? `budget forces shrink: the global budget is smaller than what the shards hold, and this shard's recent activity (weight ${row.activity.toFixed(2)}) ranks it ${row.cap <= 1 ? "last: the 1 MB minimum" : "below the others"}`
+        : `budget is tight: capped below its growth headroom by recent activity (weight ${row.activity.toFixed(2)}), still above what it holds`);
+    }
+  }
+  return rows.map(row => ({ key: row.key, capMb: row.cap, retentionDays: row.retentionDays, reason: reasons.get(row.key)! }));
 }
 
 const MB = 1048576, GROWTH_DAYS = 7, PROJECT_DAYS = 30;
@@ -75,15 +186,24 @@ export function capacityReport(opts: {
   mkdirSync(base, { recursive: true, mode: 0o700 }); // a report on a fresh home still needs a path df can read
   const now = opts.now ?? Date.now;
   const since = new Date(now() - GROWTH_DAYS * 24 * 3600_000).toISOString();
-  const shards = walkShards(base);
-  let bytes = 0, rows = 0, growthRows = 0, growthBytes = 0;
-  for (const shard of shards) for (const dir of shard.machineDirs) {
-    const total = captureShardStats(dir);
-    rows += total.rows;
-    bytes += total.bytes;
-    const growth = captureShardGrowth(dir, since);
-    growthRows += growth.rows;
-    growthBytes += growth.bytes;
+  const shards = walkShards(base), stateOf = lifecycleResolver(base);
+  let bytes = 0, rows = 0, growthRows = 0, growthBytes = 0, forgottenBytes = 0;
+  const perShard: SplitInput["shards"] = [];
+  for (const shard of shards) {
+    let useBytes = 0, growthShard = 0, lastAt: string | null = null;
+    for (const dir of shard.machineDirs) {
+      const total = captureShardStats(dir);
+      rows += total.rows;
+      bytes += total.bytes;
+      useBytes += total.bytes;
+      if (total.lastAt && (lastAt === null || total.lastAt > lastAt)) lastAt = total.lastAt;
+      const growth = captureShardGrowth(dir, since);
+      growthRows += growth.rows;
+      growthBytes += growth.bytes;
+      growthShard += growth.bytes;
+    }
+    if (stateOf(shard.key) === "forgotten") forgottenBytes += useBytes;
+    else perShard.push({ key: shard.key, useBytes, growthBytesPerDay: growthShard / GROWTH_DAYS, lastAt });
   }
   const rowsPerDay = growthRows / GROWTH_DAYS, bytesPerDay = growthBytes / GROWTH_DAYS;
   const disk = opts.inject?.disk ?? diskReadings(base);
@@ -101,8 +221,8 @@ export function capacityReport(opts: {
     retentionDays: homeConfig.retentionDays ?? CAPTURE_DEFAULT_RETENTION_DAYS,
   };
   const diskShare = opts.diskShare ?? 0.02;
-  // ponytail: the 2026-10-17 owner decision keeps R6 caps per shard in P1, while the disk-share budget is
-  // machine-wide; #15 T5 (D7) owns the machine-total split. Until then a home with N shards can hold N x cap.
+  // The single proposal below is one shard's bounds (the home default). #15 T5 (D7): `split` shares the machine-wide budget across the shards, so a
+  // home with N shards no longer holds N x cap once the person applies it (`amem capacity apply --split`).
   const budgetBytes = diskShare * disk.freeBytes;
   // Growth (owner decision 2026-10-17, item 2): propose the largest cap and retention that fit the disk share, above the current values when there is room.
   // The cap's ceiling is the disk-share bound itself. A person's own setting above the retention ceiling is never proposed down for the ceiling alone.
@@ -127,6 +247,10 @@ export function capacityReport(opts: {
     binding.push("R2 hook cost: measured hook latency or RSS exceeds the budget");
   }
   const reason = binding.join("; ");
+  // The split shares the same disk-share budget; what a forgotten shard still holds on disk is not available to the others.
+  let split: ShardSplit[] = [], splitRefused: string | undefined;
+  try { split = capacitySplit({ budgetBytes: Math.max(0, budgetBytes - forgottenBytes), shards: perShard, now: now() }); }
+  catch (error) { if (!(error instanceof SplitBudgetError)) throw error; splitRefused = error.message; }
   return {
     at: new Date(now()).toISOString(),
     capture: { shards: shards.length, bytes, rows, rowsPerDay, bytesPerDay },
@@ -137,6 +261,8 @@ export function capacityReport(opts: {
     current,
     diskShare,
     proposal: { capMb, retentionDays, reason },
+    split,
+    ...(splitRefused ? { splitRefused } : {}),
   };
 }
 
@@ -150,5 +276,7 @@ export function capacityText(report: CapacityReport): string {
     `projected capture in ${report.projected.days} days: ${mb(report.projected.bytes)}`,
     `current: cap ${report.current.capMb} MB, retention ${report.current.retentionDays} days`,
     `proposal: cap ${report.proposal.capMb} MB, retention ${report.proposal.retentionDays} days (${report.proposal.reason})`,
+    ...(report.splitRefused ? [`split: none proposed (${report.splitRefused})`] : []),
+    ...(report.split.length ? ["split of the global budget per shard (a proposal: amem capacity apply --split):", ...report.split.map(row => `  ${row.key}: cap ${row.capMb} MB, retention ${row.retentionDays} days (${row.reason})`)] : []),
   ].join("\n");
 }

package/src/memory/capture-input.ts

@@ -1,5 +1,6 @@
 import { looksSecret } from "./screen.ts";
 import { isDenied } from "./platform.ts";
+import { stripPrivateSpans } from "./private-spans.ts";
 
 export const CAPTURE_MAX_EXCERPT = 2000;
 export const CAPTURE_MAX_PATHS = 32;
@@ -17,14 +18,18 @@ export interface NormalizedCaptureFields {
 }
 
 /** Pure capture shaping; no store, project lookup or filesystem operation is loaded or invoked here. */
-export function normalizeCaptureFields(input: CaptureFields, now: () => number = Date.now, screen: (text: string) => boolean = looksSecret): NormalizedCaptureFields {
+/** The caps a person's configuration may lower (F4); the built-in caps are the ceiling, so a larger value is ignored. */
+export interface CaptureCaps { excerptBytes?: number; paths?: number; denyPaths?: readonly string[] }
+export function normalizeCaptureFields(input: CaptureFields, now: () => number = Date.now, screen: (text: string) => boolean = looksSecret, caps: CaptureCaps = {}): NormalizedCaptureFields {
+  const maxExcerpt = Math.min(CAPTURE_MAX_EXCERPT, caps.excerptBytes ?? CAPTURE_MAX_EXCERPT), maxPaths = Math.min(CAPTURE_MAX_PATHS, caps.paths ?? CAPTURE_MAX_PATHS);
   const str = (v: unknown, max: number) => typeof v === "string" && v.length > 0 && v.length <= max;
   // Canonical UTC ISO text, so text order is time order for eviction (`at < cutoff`) and search (`at >= notBefore`).
   const at = new Date(input.at === undefined ? now() : Date.parse(input.at)).toISOString();
   const tool = str(input.tool, 64) ? input.tool! : null;
   const status = str(input.status, 64) ? input.status! : null;
-  const paths = (input.paths ?? []).map(String).filter((p) => p && !isDenied(p)).slice(0, CAPTURE_MAX_PATHS).map((p) => p.slice(0, 400));
-  let excerpt = (input.excerpt ?? "").slice(0, CAPTURE_MAX_EXCERPT);
+  const paths = (input.paths ?? []).map(String).filter((p) => p && !isDenied(p, caps.denyPaths ? [...caps.denyPaths] : [])).slice(0, maxPaths).map((p) => p.slice(0, 400));
+  // `<private>` spans go first: they are never screened, counted or stored. The cap applies to what is left.
+  let excerpt = stripPrivateSpans(input.excerpt ?? "").slice(0, maxExcerpt);
   if (excerpt && screen(excerpt)) excerpt = "[secret-screened]";
   return { at, agent: input.agent, event: input.event, tool, paths, status, excerpt,
     bytes: Buffer.byteLength(excerpt) + Buffer.byteLength(JSON.stringify(paths)) + ROW_OVERHEAD_BYTES };