@staix/agent-mem 0.6.0 → 0.8.0

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

package/src/memory/capture.ts

@@ -7,7 +7,10 @@ import { normalizeCaptureFields, type CaptureFields } from "./capture-input.ts";
 export { CAPTURE_MAX_EXCERPT, CAPTURE_MAX_PATHS } from "./capture-input.ts";
 import { memoryBase } from "./home.ts";
 import { captureShardDir, ensureShardDescriptor, readShardDescriptor, resolveAlias, shardKeyHash } from "./shard.ts";
+import { assertProjectActive } from "./lifecycle.ts";
 import { machineId } from "./machine.ts";
+import { loadAmemConfig, repoConfigRoot } from "./config.ts";
+import { fold } from "./policy.ts";
 import { readWindowSql, readRef, type ReadWindow, type ReadRef, ftsTerms, fts5Available } from "./search-fts.ts";
 
 /**
@@ -81,6 +84,15 @@ export interface CaptureOptions {
   recentReadRows?: boolean;
   /** Excerpt screen; defaults to the built-in secret screen. A host passes its stricter policy. */
   screen?: (text: string) => boolean;
+  /** Caps a caller may lower (F4); the built-in caps and the person's configured caps are the ceiling, so a larger value is ignored (a host can tighten, never loosen). */
+  excerptBytes?: number; capturePaths?: number;
+  /** The working directory the capture belongs to: its repository's `.amem/config` narrows the policy (deny paths, caps) for this store. Absent: the machine configuration only. */
+  cwd?: string;
+  /**
+   * #15 T5: a writable open of an archived or forgotten project is refused (the person took it out of recall; `amem project unarchive` brings an archived one back).
+   * `ignore` is for the maintenance that must still reach the shard (gc, export): it never appends.
+   */
+  lifecycle?: "enforce" | "ignore";
 }
 export interface CaptureAppendOptions {
   /** Opaque stable source receipt for deterministic transcript replay. Requires an explicit source timestamp. */
@@ -125,13 +137,17 @@ export function writeCaptureConfigFile(path: string, config: Partial<CaptureConf
   return next;
 }
 
-/** The effective R6 settings for a shard directory: shard config over the home default over the built-in defaults. */
+/**
+ * The effective R6 settings for a shard directory: the shard's config over the home default (`capture-config.json`, which the capacity advisor writes)
+ * over the person's machine configuration (`amem.config.json` `capture`, F4) over the built-in defaults. A malformed machine configuration throws.
+ */
 export function readCaptureConfig(dir: string, base?: string): CaptureConfig {
   const homeDefault = base === undefined ? {} : readCaptureConfigFile(join(base, "capture-config.json"));
   const shard = readCaptureConfigFile(join(dir, "config.json"));
+  const machine = base === undefined ? {} : loadAmemConfig(base).config.capture;
   return {
-    capMb: shard.capMb ?? homeDefault.capMb ?? CAPTURE_DEFAULT_CAP_MB,
-    retentionDays: shard.retentionDays ?? homeDefault.retentionDays ?? CAPTURE_DEFAULT_RETENTION_DAYS,
+    capMb: shard.capMb ?? homeDefault.capMb ?? machine.capMb ?? CAPTURE_DEFAULT_CAP_MB,
+    retentionDays: shard.retentionDays ?? homeDefault.retentionDays ?? machine.retentionDays ?? CAPTURE_DEFAULT_RETENTION_DAYS,
   };
 }
 
@@ -157,6 +173,7 @@ export class CaptureStore {
   private readonly db: Database;
   private readonly now: () => number;
   private readonly screen: (text: string) => boolean;
+  private readonly caps: import("./capture-input.ts").CaptureCaps;
   private readonly capMb: number;
   private readonly retentionDays: number;
   /** Set when the schema setup itself met the lock: appends spool without touching the database again. */
@@ -179,6 +196,7 @@ export class CaptureStore {
     if (this.readOnly && !/^[a-f0-9]{16}$/.test(machine)) throw new Error("capture machine identity unavailable");
     this.requestedKey = opts.project;
     this.key = resolveAlias(this.base, opts.project);
+    if (!this.readOnly && opts.lifecycle !== "ignore") assertProjectActive(this.base, this.key);
     if (this.readOnly) {
       const descriptor = lstatSync(join(this.base, "projects", shardKeyHash(this.key), "project.json"));
       if (!descriptor.isFile() || descriptor.isSymbolicLink() || descriptor.size > 4096
@@ -197,7 +215,14 @@ export class CaptureStore {
     this.capMb = opts.capMb ?? config.capMb;
     this.retentionDays = opts.retentionDays ?? config.retentionDays;
     this.now = opts.now ?? Date.now;
-    this.screen = opts.screen ?? looksSecret;
+    const configured = loadAmemConfig(this.base, opts.cwd === undefined ? undefined : repoConfigRoot(opts.cwd)).config;
+    // F4: the person's PII patterns screen every excerpt and their deny paths filter every path, whoever appends (hook, ingest or library). A host's own `screen` replaces only the secret part.
+    const patterns = configured.piiPatterns.map(fold).filter(Boolean);
+    const base = opts.screen ?? looksSecret;
+    this.screen = patterns.length ? (text: string) => base(text) || patterns.some(pattern => fold(text).includes(pattern)) : base;
+    const lowest = (a: number | undefined, b: number | undefined) => a === undefined ? b : b === undefined ? a : Math.min(a, b);
+    this.caps = { excerptBytes: lowest(opts.excerptBytes, configured.excerptBytes), paths: lowest(opts.capturePaths, configured.capturePaths),
+      ...(configured.denyPaths.length ? { denyPaths: configured.denyPaths } : {}) };
     const file = join(this.dir, "capture.db");
     if (this.readOnly) {
       // Refuse absent/cold state without authoring machine, shard, schema, FTS or spool metadata.
@@ -412,7 +437,7 @@ export class CaptureStore {
 
   /** The one place input becomes a row: caps fields, deny-filters paths, screens the excerpt, counts its bytes. */
   private normalize(input: CaptureInput): NormalizedCapture {
-    const { at, agent, event, tool, paths, status, excerpt, bytes } = normalizeCaptureFields(input, () => this.now(), text => this.screen(text));
+    const { at, agent, event, tool, paths, status, excerpt, bytes } = normalizeCaptureFields(input, () => this.now(), text => this.screen(text), this.caps);
     return { at, project: input.project, agent, event, tool, paths, status, excerpt, bytes };
   }
 

package/src/memory/catalog.ts

@@ -1,11 +1,12 @@
 import { Database } from "bun:sqlite";
-import { chmodSync, existsSync, readdirSync } from "node:fs";
+import { chmodSync, existsSync, lstatSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { memoryBase } from "./home.ts";
 import { effectiveAliases, readShardDescriptor, SHARDED_SCHEMA } from "./shard.ts";
 import { readProfileJSON, validGeneration } from "./generation.ts";
 import { captureShardStats, readCaptureConfig } from "./capture.ts";
 import { openShardStore } from "./store.ts";
+import { lifecycleResolver, type LifecycleState } from "./lifecycle.ts";
 
 /**
  * #15 D3 (storage part only): the user-level catalog of project shards. `catalog.db` in the memory home is derived
@@ -20,12 +21,16 @@ export interface CatalogProject {
   captureRows: number; captureBytes: number; captureLastAt: string | null;
   curatedEntries: number | null; curatedLastAt: string | null; curatedAvailable: boolean;
   capMb: number; retentionDays: number;
+  /** #15 T5: the person's lifecycle decision (`lifecycle.jsonl`); forgotten projects stay in the scan so the state is visible, and listings leave them out. */
+  state: LifecycleState;
+  /** Bytes the shard directory holds on disk (its logs, indexes, capture and work lists), counting files and never following a link. */
+  diskBytes: number;
 }
 
-interface CatalogRow { hash: string; key: string; local: number; aliases: string; capture_rows: number; capture_bytes: number; capture_last_at: string | null; curated_entries: number | null; curated_last_at: string | null; cap_mb: number; retention_days: number }
+interface CatalogRow { hash: string; key: string; local: number; aliases: string; capture_rows: number; capture_bytes: number; capture_last_at: string | null; curated_entries: number | null; curated_last_at: string | null; cap_mb: number; retention_days: number; state: string; disk_bytes: number }
 
 const fromRow = (r: CatalogRow): CatalogProject => ({ hash: r.hash, key: r.key, local: r.local === 1, aliases: JSON.parse(r.aliases) as string[],
-  captureRows: r.capture_rows, captureBytes: r.capture_bytes, captureLastAt: r.capture_last_at, curatedEntries: r.curated_entries, curatedLastAt: r.curated_last_at, curatedAvailable: r.curated_entries !== null, capMb: r.cap_mb, retentionDays: r.retention_days });
+  captureRows: r.capture_rows, captureBytes: r.capture_bytes, captureLastAt: r.capture_last_at, curatedEntries: r.curated_entries, curatedLastAt: r.curated_last_at, curatedAvailable: r.curated_entries !== null, capMb: r.cap_mb, retentionDays: r.retention_days, state: r.state === "archived" || r.state === "forgotten" ? r.state : "active", diskBytes: r.disk_bytes });
 
 /** Interrupted splits expose capture facts, but cannot authorize any curated store open or initialization. */
 function capturedSelection(base: string): boolean {
@@ -41,7 +46,7 @@ function curatedStats(base: string, hash: string, key: string, captured: boolean
   const dir = join(base, "projects", hash);
   // A capture-only descriptor is not permission to initialize a curated store while listing the catalog.
   if (!existsSync(join(dir, "generation.json")) && !existsSync(join(dir, "generation-seal.json"))) return { entries: 0, lastAt: null };
-  const store = openShardStore({ memoryDir: base, project: key, deferPromotions: true });
+  const store = openShardStore({ memoryDir: base, project: key, deferPromotions: true, lifecycle: "ignore" });
   try {
     const db = new Database(join(dir, "index.db"), { readonly: true });
     try {
@@ -52,6 +57,23 @@ function curatedStats(base: string, hash: string, key: string, captured: boolean
   } finally { store.close(); }
 }
 
+/** Bytes of regular files under a shard directory. A link is not followed (counted as nothing), an unreadable entry as nothing: the figure is a lower bound, never a guess. */
+export function directoryBytes(dir: string, depth = 0): number {
+  if (depth > 12) return 0;
+  let total = 0;
+  let entries: import("node:fs").Dirent[] = [];
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return 0; }
+  for (const entry of entries) {
+    const path = join(dir, entry.name);
+    try {
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) total += directoryBytes(path, depth + 1);
+      else if (entry.isFile()) total += lstatSync(path).size;
+    } catch { /* vanished or unreadable: not counted */ }
+  }
+  return total;
+}
+
 /** Every readable shard with its machine-scope directories; the walk behind the catalog and the capacity advisor. */
 export function walkShards(base: string): { hash: string; key: string; local: boolean; machineDirs: string[] }[] {
   const projectsDir = join(base, "projects");
@@ -75,6 +97,7 @@ export function scanCatalog(base: string): CatalogProject[] {
   const captured = capturedSelection(base);
   // The latest op per alias (a removal included): an alias lists only under the key it currently points at, never under a past target or after `alias remove`.
   const latest = effectiveAliases(base);
+  const stateOf = lifecycleResolver(base);
   const out: CatalogProject[] = [];
   for (const shard of walkShards(base)) {
     let rows = 0, bytes = 0, lastAt: string | null = null;
@@ -88,11 +111,17 @@ export function scanCatalog(base: string): CatalogProject[] {
     const curated = curatedStats(base, shard.hash, shard.key, captured);
     out.push({ hash: shard.hash, key: shard.key, local: shard.local,
       aliases: [...latest.entries()].filter(([, key]) => key === shard.key).map(([alias]) => alias).sort(),
-      captureRows: rows, captureBytes: bytes, captureLastAt: lastAt, curatedEntries: curated.entries, curatedLastAt: curated.lastAt, curatedAvailable: curated.entries !== null, capMb: config.capMb, retentionDays: config.retentionDays });
+      captureRows: rows, captureBytes: bytes, captureLastAt: lastAt, curatedEntries: curated.entries, curatedLastAt: curated.lastAt, curatedAvailable: curated.entries !== null, capMb: config.capMb, retentionDays: config.retentionDays,
+      state: stateOf(shard.key), diskBytes: directoryBytes(join(base, "projects", shard.hash)) });
   }
   return out.sort((a, b) => a.key.localeCompare(b.key));
 }
 
+/** A fresh scan of the shards for a read-only command (`amem usage`, `amem projects`): it writes nothing, `catalog.db` included. */
+export function readCatalogFresh(base: string): CatalogProject[] {
+  return scanCatalog(base);
+}
+
 /** Rewrite `catalog.db` from the shards in one transaction: the same shards always reproduce the same rows. */
 export function rebuildCatalog(opts: { home?: string } = {}): CatalogProject[] {
   const base = memoryBase(opts.home);
@@ -105,12 +134,13 @@ export function rebuildCatalog(opts: { home?: string } = {}): CatalogProject[] {
     db.transaction(() => {
       const columns = db.query("PRAGMA table_info(projects)").all() as { name: string; notnull: number }[];
       // This database is disposable. Rebuild older derived schemas instead of coercing unavailable into zero.
-      if (columns.length && (!columns.some(column => column.name === "curated_entries" && column.notnull === 0) || !columns.some(column => column.name === "curated_last_at"))) db.run("DROP TABLE projects");
+      if (columns.length && (!columns.some(column => column.name === "curated_entries" && column.notnull === 0) || !columns.some(column => column.name === "curated_last_at")
+        || !columns.some(column => column.name === "state") || !columns.some(column => column.name === "disk_bytes"))) db.run("DROP TABLE projects");
       db.run(`CREATE TABLE IF NOT EXISTS projects (hash TEXT PRIMARY KEY, key TEXT NOT NULL, local INTEGER NOT NULL, aliases TEXT NOT NULL,
-        capture_rows INTEGER NOT NULL, capture_bytes INTEGER NOT NULL, capture_last_at TEXT, curated_entries INTEGER, curated_last_at TEXT, cap_mb REAL NOT NULL, retention_days REAL NOT NULL)`);
+        capture_rows INTEGER NOT NULL, capture_bytes INTEGER NOT NULL, capture_last_at TEXT, curated_entries INTEGER, curated_last_at TEXT, cap_mb REAL NOT NULL, retention_days REAL NOT NULL, state TEXT NOT NULL DEFAULT 'active', disk_bytes INTEGER NOT NULL DEFAULT 0)`);
       db.run("DELETE FROM projects");
-      for (const p of projects) db.query("INSERT INTO projects (hash, key, local, aliases, capture_rows, capture_bytes, capture_last_at, curated_entries, curated_last_at, cap_mb, retention_days) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)")
-        .run(p.hash, p.key, p.local ? 1 : 0, JSON.stringify(p.aliases), p.captureRows, p.captureBytes, p.captureLastAt, p.curatedEntries, p.curatedLastAt, p.capMb, p.retentionDays);
+      for (const p of projects) db.query("INSERT INTO projects (hash, key, local, aliases, capture_rows, capture_bytes, capture_last_at, curated_entries, curated_last_at, cap_mb, retention_days, state, disk_bytes) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)")
+        .run(p.hash, p.key, p.local ? 1 : 0, JSON.stringify(p.aliases), p.captureRows, p.captureBytes, p.captureLastAt, p.curatedEntries, p.curatedLastAt, p.capMb, p.retentionDays, p.state, p.diskBytes);
     }).immediate();
   } finally { db.close(); }
   return projects;
@@ -127,8 +157,11 @@ export function readCatalog(opts: { home?: string } = {}): CatalogProject[] {
     db = new Database(file, { readonly: true });
     db.run("PRAGMA busy_timeout = 3000");
     const columns = new Set((db.query("PRAGMA table_info(projects)").all() as { name: string }[]).map(column => column.name));
-    if (!columns.has("curated_entries") || !columns.has("curated_last_at")) throw new Error("catalog schema needs rebuild");
+    if (!columns.has("curated_entries") || !columns.has("curated_last_at") || !columns.has("state") || !columns.has("disk_bytes")) throw new Error("catalog schema needs rebuild");
+    // The state is the person's decision in lifecycle.jsonl, which changes without touching a shard: read it live, never from the cached row.
+    const stateOf = lifecycleResolver(base);
     return (db.query("SELECT * FROM projects ORDER BY key").all() as CatalogRow[]).map(fromRow)
+      .map(project => ({ ...project, state: stateOf(project.key) }))
       .map(project => captured ? { ...project, curatedEntries: null, curatedLastAt: null, curatedAvailable: false } : project);
   } catch { return rebuildCatalog(opts); }
   finally { db?.close(); }