@staix/agent-mem 0.3.1 → 0.4.0

package/src/mcp.ts

@@ -0,0 +1,122 @@
+import { once } from "node:events";
+import type { Readable, Writable } from "node:stream";
+
+const string = (maxLength: number, minLength = 1) => ({ type: "string", minLength, maxLength });
+const limit = { type: "integer", minimum: 1, maximum: 100 };
+const object = (properties: Record<string, unknown>, required: string[] = []) => ({ type: "object", properties, required, additionalProperties: false });
+const tool = <Name extends string>(name: Name, description: string, inputSchema: ReturnType<typeof object>, readOnlyHint = true) => ({ name, description, inputSchema,
+  annotations: { readOnlyHint, destructiveHint: false, openWorldHint: false } });
+
+/** Frozen #13 P2 surface. Storage scope comes from startup, never tool arguments. */
+export const MCP_TOOLS = [
+  tool("amem_search", "Search screened memory in this project. Capture results are recall, not curated evidence.", object({ query: string(1000), limit, since: string(40), includeCapture: { type: "boolean" } }, ["query"])),
+  tool("amem_show", "Show a screened memory entry in this project by its exact id or unique prefix.", object({ id: string(80) }, ["id"])),
+  tool("amem_timeline", "Read screened memory near an entry or time in this project.", object({ id: string(80), since: string(40), limit })),
+  tool("amem_graph", "Read the screened curated-memory neighbourhood. Capture is never graph evidence.", object({ start: string(500), hops: { type: "integer", minimum: 1, maximum: 2 }, limit }, ["start"])),
+  tool("amem_work_state_read", "Read project work lists; closed lists/items can be included explicitly.", object({ list: string(200), includeClosed: { type: "boolean" } })),
+  tool("amem_work_state_write", "Append scalar project work-list fields; null clears, task selects an item, list status done closes.", object({ list: string(200), fields: { type: "object", minProperties: 1, maxProperties: 64,
+    additionalProperties: { type: ["string", "number", "boolean", "null"], maxLength: 4000 } } }, ["list", "fields"]), false),
+  tool("amem_remember", "Propose a general memory candidate for person acceptance. Never writes directly to curated notes.", object({ text: string(3000), title: string(200), kind: { type: "string", enum: ["decision", "finding", "contract", "fail"] } }, ["text"]), false),
+  tool("amem_vault_candidates", "List screened durable curated notes eligible for a person to move to the vault. Read only.", object({ limit })),
+  tool("amem_capacity", "Read this machine's bounded capture capacity proposal; applying it is person-only.", object({})),
+] as const;
+export type McpToolName = typeof MCP_TOOLS[number]["name"];
+export type McpHandlers = Record<McpToolName, (args: Record<string, unknown>) => unknown | Promise<unknown>>;
+export interface McpOptions {
+  input?: Readable;
+  output?: Writable;
+  tools: McpHandlers;
+  close?: () => void | Promise<void>;
+  version?: string;
+}
+const FRAME_BYTES = 65_536, RESULT_BYTES = 262_144;
+const protocols = ["2025-06-18", "2025-03-26", "2024-11-05"];
+const plain = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v) && (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null);
+
+/** The deliberately small schema vocabulary of the nine tools, shared with runtime validation. */
+function valid(value: unknown, raw: unknown): boolean {
+  const s = raw as Record<string, any>, type = value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
+  const types = Array.isArray(s.type) ? s.type : [s.type];
+  if (!types.includes(type) && !(type === "number" && Number.isSafeInteger(value) && types.includes("integer"))) return false;
+  if (s.enum && !s.enum.includes(value)) return false;
+  if (typeof value === "string" && (value.length < (s.minLength ?? 0) || value.length > (s.maxLength ?? FRAME_BYTES) || value.includes("\0"))) return false;
+  if (typeof value === "number" && (!Number.isFinite(value) || value < (s.minimum ?? -Infinity) || value > (s.maximum ?? Infinity))) return false;
+  if (plain(value)) {
+    const keys = Object.keys(value);
+    if (keys.length < (s.minProperties ?? 0) || keys.length > (s.maxProperties ?? 64)) return false;
+    if ((s.required ?? []).some((key: string) => !Object.hasOwn(value, key))) return false;
+    for (const key of keys) {
+      if (["__proto__", "prototype", "constructor"].includes(key) || key.length > 200) return false;
+      if (Object.hasOwn(s.properties ?? {}, key)) { if (!valid(value[key], s.properties[key])) return false; }
+      else if (s.additionalProperties === false || !plain(s.additionalProperties) || !valid(value[key], s.additionalProperties)) return false;
+    }
+  } else if (type === "object") return false;
+  return true;
+}
+
+/** MCP 2025-06-18 basic/transports: newline stdio only. Sequential, bounded, no listener or timer. */
+export async function serveMcp(options: McpOptions): Promise<void> {
+  const input = options.input ?? process.stdin, output = options.output ?? process.stdout;
+  let phase: "new" | "initializing" | "ready" = "new";
+  const send = async (response: unknown) => { if (!output.write(JSON.stringify(response) + "\n")) await once(output, "drain"); };
+  const error = (id: unknown, code: number, message: string) => send({ jsonrpc: "2.0", id, error: { code, message } });
+  const handle = async (line: string) => {
+    let msg: unknown;
+    try { msg = JSON.parse(line); } catch { await error(null, -32700, "Parse error"); return; }
+    if (!plain(msg) || msg.jsonrpc !== "2.0" || typeof msg.method !== "string") { await error(null, -32600, "Invalid request"); return; }
+    if (!Object.hasOwn(msg, "id")) {
+      if (msg.method === "notifications/initialized" && phase === "initializing") phase = "ready";
+      return; // Notifications never invoke a mutating handler.
+    }
+    const id = msg.id;
+    if (!(typeof id === "string" && id.length <= 200 || typeof id === "number" && Number.isSafeInteger(id))) { await error(null, -32600, "Invalid request id"); return; }
+    if (msg.method === "ping") { await send({ jsonrpc: "2.0", id, result: {} }); return; }
+    if (msg.method === "initialize") {
+      if (phase !== "new" || !plain(msg.params) || typeof msg.params.protocolVersion !== "string" || !plain(msg.params.capabilities) || !plain(msg.params.clientInfo)) { await error(id, -32602, "Invalid initialization"); return; }
+      phase = "initializing";
+      await send({ jsonrpc: "2.0", id, result: { protocolVersion: protocols.includes(msg.params.protocolVersion) ? msg.params.protocolVersion : protocols[0],
+        capabilities: { tools: { listChanged: false } }, serverInfo: { name: "amem", version: options.version ?? "unreleased" } } });
+      return;
+    }
+    if (phase !== "ready") { await error(id, -32002, "Initialize the session first"); return; }
+    if (msg.method === "tools/list") {
+      const params = msg.params;
+      if (params !== undefined && params !== null && (!plain(params) || Object.keys(params).some(key => key !== "cursor" && key !== "_meta") || params.cursor !== undefined && params.cursor !== null || params._meta !== undefined && (!plain(params._meta) || Object.keys(params._meta).length > 0))) { await error(id, -32602, "Invalid tool listing arguments"); return; }
+      await send({ jsonrpc: "2.0", id, result: { tools: MCP_TOOLS } }); return;
+    }
+    if (msg.method !== "tools/call") { await error(id, -32601, "Method not found"); return; }
+    const params = msg.params;
+    if (!plain(params) || Object.keys(params).some(k => !["name", "arguments", "_meta"].includes(k)) || typeof params.name !== "string") { await error(id, -32602, "Invalid tool call"); return; }
+    const definition = MCP_TOOLS.find(t => t.name === params.name), args = params.arguments ?? {};
+    if (!definition || !valid(args, definition.inputSchema)) { await error(id, -32602, "Invalid tool name or arguments"); return; }
+    let result: unknown;
+    try {
+      const value = await options.tools[definition.name](args as Record<string, unknown>), text = JSON.stringify(value);
+      if (text === undefined || Buffer.byteLength(text) > RESULT_BYTES) throw new Error("result unavailable");
+      result = { content: [{ type: "text", text }] };
+    } catch { result = { isError: true, content: [{ type: "text", text: "Memory operation unavailable or refused; no partial result is shown." }] }; }
+    await send({ jsonrpc: "2.0", id, result });
+  };
+  let pending = "", overflow = false;
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  const consume = async (chunk: string) => {
+    let start = 0;
+    for (;;) {
+      const newline = chunk.indexOf("\n", start), part = chunk.slice(start, newline < 0 ? undefined : newline);
+      if (!overflow) {
+        if (Buffer.byteLength(pending) + Buffer.byteLength(part) > FRAME_BYTES) { overflow = true; pending = ""; }
+        else pending += part;
+      }
+      if (newline < 0) return;
+      if (overflow) await error(null, -32600, "Request exceeds the 64 KiB frame bound");
+      else if (pending.trim()) await handle(pending);
+      pending = ""; overflow = false; start = newline + 1;
+    }
+  };
+  try {
+    for await (const chunk of input) await consume(typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true }));
+    await consume(decoder.decode());
+    // A truncated frame on EOF is not an accepted request and must never cause a write.
+    if (pending.trim() || overflow) await error(null, -32700, "Incomplete request at EOF");
+  } finally { await options.close?.(); }
+}

package/src/memory/candidates.ts

@@ -14,6 +14,7 @@ export interface CandidateTarget { id: string; revision: string }
 export type CandidateInput = { project: string } & (
   | { kind: "correction"; target: CandidateTarget; proposedText: string; reason: string; noteKind?: "decision" | "contract" | "fail" }
   | { 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 }
 );
 export type CandidateStatus = "pending" | "accepting" | "accepted" | "rejected";
@@ -50,6 +51,8 @@ function validate(input: CandidateInput): void {
     if (!validTarget(input.target) || !text(input.proposedText) || !text(input.reason) || input.noteKind !== undefined && !["decision", "contract", "fail"].includes(input.noteKind)) throw new Error("invalid correction candidate");
   } else if (input.kind === "fail") {
     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 === "decay") {
     if (!validTarget(input.target) || !text(input.reason)) throw new Error("invalid decay candidate");
   } else throw new Error("invalid candidate kind");
@@ -73,8 +76,9 @@ export class CandidateStore {
   readonly path: string;
   private readonly db: Database;
   private readonly now: () => number;
-  constructor(options: { home?: string; now?: () => number } = {}) {
-    this.dir = options.home === undefined ? memoryHome() : join(options.home, "memory");
+  constructor(options: { home?: string; memoryDir?: string; now?: () => number } = {}) {
+    if (options.memoryDir !== undefined && options.home !== undefined) throw new Error("choose a home or an exact memory directory");
+    this.dir = options.memoryDir ?? (options.home === undefined ? memoryHome() : join(options.home, "memory"));
     this.now = options.now ?? Date.now;
     mkdirSync(this.dir, { recursive: true, mode: 0o700 }); chmodSync(this.dir, 0o700);
     this.path = join(this.dir, "candidates.db");
@@ -112,7 +116,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"].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"].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();
@@ -147,7 +151,7 @@ export class CandidateStore {
   }
   accept(id: string, context: CandidateAcceptance): CandidateAcceptanceResult {
     personOnly(context.actor); publicOnly(context.verdict);
-    if (realPath(context.store.dir) !== realPath(this.dir) || typeof context.policy !== "function") throw new Error("candidate acceptance requires its memory store and a current host policy");
+    if (realPath(context.store.profile.home) !== realPath(this.dir) || typeof context.policy !== "function") throw new Error("candidate acceptance requires its memory store and a current host policy");
     return context.store.withDeferredPromotions(() => this.acceptDeferred(id, context));
   }
   private acceptDeferred(id: string, context: CandidateAcceptance): CandidateAcceptanceResult {
@@ -157,21 +161,21 @@ export class CandidateStore {
     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 resolve = () => {
-      const target = candidate.input.target;
+      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 = resolve(), data = candidate.input;
-    const body = data.kind === "correction" ? `${data.proposedText}\n\nReason: ${data.reason}`
+    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", project: data.kind === "correction" ? target!.project : context.project,
+    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.target?.revision ?? "none"}\nTarget entry: ${data.target?.id ?? "none"}\n\n${body}` };
+      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 => {

package/src/memory/capacity.ts

@@ -0,0 +1,179 @@
+import { spawnSync } from "node:child_process";
+import { appendFileSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { totalmem } from "node:os";
+import { join } from "node:path";
+import { memoryBase } from "./home.ts";
+import { walkShards } from "./catalog.ts";
+import { captureShardGrowth, captureShardStats, readCaptureConfigFile, CAPTURE_DEFAULT_CAP_MB, CAPTURE_DEFAULT_RETENTION_DAYS, type CaptureConfig } from "./capture.ts";
+
+/**
+ * #13 R7: the capacity advisor. `capacityReport()` reads this machine's load and proposes capture bounds; the
+ * `amem capacity` CLI renders it and `amem capacity apply` writes the home default config after a preview. An
+ * agent may read the proposal through this library function; applying stays person-only at the CLI.
+ *
+ * Proposal rule (owner decision, 2026-10-17): P1 is shrink-only — the proposed cap and retention are the largest
+ * values not exceeding the current ones whose projection stays within the disk-share bound (default 2% of free
+ * space, configurable) and whose measured search and hook readings stay within R2/R3. Growth proposals are a
+ * follow-up after the agent-hub release; growing in P1 is the person's explicit `amem capacity apply --cap-mb N`.
+ * The reason names the binding constraint: `disk-share retention`, `disk-share cap`, `R3 search RSS`, `R2 hook cost`, or `none`.
+ *
+ * Metrics: a small rolling `metrics.jsonl` in the memory home (not a memory log: it is trimmed, never synced).
+ * `scripts/measure-budget.ts` writes only to its synthetic home; the P3 hooks will append real samples per invocation.
+ */
+
+export interface MetricSample { at: string; kind: "hook" | "search"; wallMs?: number; rssMB?: number; idleMB?: number }
+const METRICS_MAX_BYTES = 64 * 1024, METRICS_KEEP = 200;
+
+export function metricsPath(base: string): string {
+  return join(base, "metrics.jsonl");
+}
+
+/** Append samples, trimming the rolling file when it outgrows its bound (newest samples win). */
+export function appendMetrics(base: string, samples: MetricSample[]): void {
+  mkdirSync(base, { recursive: true, mode: 0o700 });
+  const file = metricsPath(base);
+  appendFileSync(file, samples.map((s) => JSON.stringify(s)).join("\n") + "\n", { mode: 0o600 });
+  try {
+    if (statSync(file).size <= METRICS_MAX_BYTES) return;
+    const lines = readFileSync(file, "utf8").split("\n").filter(Boolean).slice(-METRICS_KEEP);
+    writeFileSync(file, lines.join("\n") + "\n", { mode: 0o600 });
+  } catch { /* a trim failure loses nothing: the file simply stays larger */ }
+}
+
+/** The newest samples first-preserved order (oldest to newest); malformed lines are skipped. */
+export function readMetrics(base: string, limit = METRICS_KEEP): MetricSample[] {
+  let lines: string[] = [];
+  try { lines = readFileSync(metricsPath(base), "utf8").split("\n").filter(Boolean); } catch { return []; }
+  const out: MetricSample[] = [];
+  for (const line of lines.slice(-limit)) {
+    try {
+      const s = JSON.parse(line) as MetricSample;
+      if ((s?.kind === "hook" || s?.kind === "search") && typeof s.at === "string") out.push(s);
+    } catch { /* a malformed line is skipped */ }
+  }
+  return out;
+}
+
+const p95 = (samples: number[]): number | null => samples.length ? [...samples].sort((a, b) => a - b)[Math.max(0, Math.ceil(samples.length * 0.95) - 1)]! : null;
+
+function diskReadings(path: string): { freeBytes: number; totalBytes: number } {
+  const df = spawnSync("df", ["-k", path], { encoding: "utf8" });
+  const line = df.stdout?.trim().split("\n").at(-1) ?? "";
+  const fields = line.split(/\s+/);
+  const total = Number(fields[1]), avail = Number(fields[3]);
+  if (df.status !== 0 || !Number.isFinite(total) || !Number.isFinite(avail)) throw new Error(`df could not read ${path}`);
+  return { freeBytes: avail * 1024, totalBytes: total * 1024 };
+}
+
+/** Best-effort memory pressure: macOS `memory_pressure`, Linux `/proc/pressure/memory`; null when neither answers. */
+function memoryPressure(): string | null {
+  if (process.platform === "darwin") {
+    const r = spawnSync("/usr/bin/memory_pressure", [], { encoding: "utf8" });
+    const free = /System-wide memory free percentage:\s*(\d+)%/.exec(r.stdout ?? "")?.[1];
+    if (free !== undefined) return `free ${free}%`;
+    const level = /The system has (?:memory pressure level )?(\w+)/.exec(r.stdout ?? "")?.[1];
+    return level ?? null;
+  }
+  try {
+    const avg10 = /avg10=([\d.]+)/.exec(readFileSync("/proc/pressure/memory", "utf8"))?.[1];
+    return avg10 === undefined ? null : `avg10 ${avg10}`;
+  } catch { return null; }
+}
+
+export interface CapacityReport {
+  at: string;
+  capture: { shards: number; bytes: number; rows: number; rowsPerDay: number; bytesPerDay: number };
+  disk: { freeBytes: number; totalBytes: number };
+  memory: { totalBytes: number; pressure: string | null };
+  metrics: { samples: number; hookP95Ms: number | null; hookRssMB: number | null; searchP95Ms: number | null; searchRssMB: number | null };
+  projected: { days: number; bytes: number };
+  current: CaptureConfig;
+  diskShare: number;
+  proposal: { capMb: number; retentionDays: number; reason: string };
+}
+
+const MB = 1048576, GROWTH_DAYS = 7, PROJECT_DAYS = 30;
+
+export function capacityReport(opts: {
+  home?: string; memoryDir?: string; diskShare?: number; now?: () => number;
+  /** Tests and fixtures inject machine readings; the CLI always uses the native ones. */
+  inject?: { disk?: { freeBytes: number; totalBytes: number }; memoryPressure?: string | null; metrics?: MetricSample[] };
+} = {}): CapacityReport {
+  if (opts.memoryDir !== undefined && opts.home !== undefined) throw new Error("choose a home or an exact memory directory");
+  const base = opts.memoryDir ?? memoryBase(opts.home);
+  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 rowsPerDay = growthRows / GROWTH_DAYS, bytesPerDay = growthBytes / GROWTH_DAYS;
+  const disk = opts.inject?.disk ?? diskReadings(base);
+  const pressure = opts.inject?.memoryPressure !== undefined ? opts.inject.memoryPressure : memoryPressure();
+  const samples = opts.inject?.metrics ?? readMetrics(base);
+  const hookWalls = samples.filter((s) => s.kind === "hook" && typeof s.wallMs === "number").map((s) => s.wallMs!);
+  const hookRss = samples.filter((s) => s.kind === "hook" && typeof s.rssMB === "number").map((s) => s.rssMB!);
+  const searchWalls = samples.filter((s) => s.kind === "search" && typeof s.wallMs === "number").map((s) => s.wallMs!);
+  const searchRss = samples.filter((s) => s.kind === "search" && typeof s.rssMB === "number").map((s) => s.rssMB!);
+  const metrics = { samples: samples.length, hookP95Ms: p95(hookWalls), hookRssMB: p95(hookRss), searchP95Ms: p95(searchWalls), searchRssMB: p95(searchRss) };
+
+  const homeConfig = readCaptureConfigFile(join(base, "capture-config.json"));
+  const current: CaptureConfig = {
+    capMb: homeConfig.capMb ?? CAPTURE_DEFAULT_CAP_MB,
+    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.
+  const budgetBytes = diskShare * disk.freeBytes;
+  let { capMb, retentionDays } = current;
+  const binding: string[] = [];
+  if (bytesPerDay > 0 && bytesPerDay * retentionDays > budgetBytes) {
+    retentionDays = Math.max(1, Math.floor(budgetBytes / bytesPerDay));
+    binding.push("disk-share retention: steady-state capture at the current growth exceeds the disk-share bound");
+  }
+  if (capMb * MB > budgetBytes) {
+    capMb = Math.max(1, Math.floor(budgetBytes / MB));
+    binding.push("disk-share cap: the cap exceeds the disk-share bound");
+  }
+  if (metrics.searchRssMB !== null && metrics.searchRssMB > 200) {
+    retentionDays = Math.max(1, Math.floor(retentionDays / 2));
+    binding.push("R3 search RSS: measured peak search memory exceeds 200 MB");
+  }
+  if ((metrics.hookRssMB !== null && metrics.hookRssMB > 100) || (metrics.hookP95Ms !== null && metrics.hookP95Ms > 150)) {
+    capMb = Math.max(1, Math.floor(capMb / 2));
+    binding.push("R2 hook cost: measured hook latency or RSS exceeds the budget");
+  }
+  const reason = binding.length ? binding.join("; ") : "none: current bounds fit the disk share and the measured R2/R3 readings";
+  return {
+    at: new Date(now()).toISOString(),
+    capture: { shards: shards.length, bytes, rows, rowsPerDay, bytesPerDay },
+    disk,
+    memory: { totalBytes: totalmem(), pressure },
+    metrics,
+    projected: { days: PROJECT_DAYS, bytes: Math.round(bytes + bytesPerDay * PROJECT_DAYS) },
+    current,
+    diskShare,
+    proposal: { capMb, retentionDays, reason },
+  };
+}
+
+/** The non-JSON rendering of `amem capacity`. */
+export function capacityText(report: CapacityReport): string {
+  const mb = (n: number): string => `${(n / MB).toFixed(1)} MB`;
+  return [
+    `capture: ${report.capture.rows} rows, ${mb(report.capture.bytes)} in ${report.capture.shards} shard(s), +${report.capture.rowsPerDay.toFixed(1)} rows/day, +${mb(report.capture.bytesPerDay)}/day`,
+    `disk: ${mb(report.disk.freeBytes)} free of ${mb(report.disk.totalBytes)}; memory: ${mb(report.memory.totalBytes)} total${report.memory.pressure ? `, pressure ${report.memory.pressure}` : ""}`,
+    `metrics: ${report.metrics.samples} samples (hook p95 ${report.metrics.hookP95Ms?.toFixed(1) ?? "?"} ms, search peak ${report.metrics.searchRssMB?.toFixed(1) ?? "?"} MB)`,
+    `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})`,
+  ].join("\n");
+}