@staix/agent-mem 0.5.0 → 0.7.0

package/src/memory/capture.ts

@@ -1,12 +1,16 @@
 import { Database } from "bun:sqlite";
 import { createHash, randomBytes } from "node:crypto";
-import { chmodSync, closeSync, existsSync, mkdirSync, openSync, opendirSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { chmodSync, closeSync, existsSync, lstatSync, mkdirSync, openSync, opendirSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { looksSecret } from "./screen.ts";
-import { isDenied } from "./platform.ts";
+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, resolveAlias } from "./shard.ts";
-import { machineId } from "./store.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";
 
 /**
@@ -39,15 +43,12 @@ export const CAPTURE_DEFAULT_CAP_MB = 512;
 export const CAPTURE_DEFAULT_RETENTION_DAYS = 90;
 /** Well under the 150 ms R2 wall budget even with process startup: contention spools instead of waiting. */
 export const CAPTURE_BUSY_TIMEOUT_MS = 25;
-export const CAPTURE_MAX_EXCERPT = 2000;
-export const CAPTURE_MAX_PATHS = 32;
 /** Eviction and drain work per invocation, so a shrunk cap or a long outage is worked off over many hooks. */
 export const CAPTURE_EVICT_BATCH_ROWS = 256;
 export const CAPTURE_EVICT_MAX_BATCHES = 4;
 /** Wall-time bound for one invocation's eviction: with the batch bound, an append stays inside R2 after a cap shrink. */
 export const CAPTURE_EVICT_MAX_MS = 25;
 export const CAPTURE_DRAIN_MAX_LINES = 1000;
-const ROW_OVERHEAD_BYTES = 96;
 const SPOOL = "spool.jsonl";
 const DRAINING = "spool.jsonl.draining";
 const SPOOL_DIR = "spool";
@@ -58,12 +59,7 @@ const segmentName = /^spool-[0-9a-f-]+\.jsonl(?:\.offset-(\d+)(-skip)?)?(?:\.dra
 let spoolSequence = 0;
 const spoolToken = () => `${Date.now().toString(16).padStart(13, "0")}-${process.pid.toString(16).padStart(8, "0")}-${(spoolSequence++).toString(16).padStart(8, "0")}-${randomBytes(12).toString("hex")}`;
 
-export interface CaptureInput {
-  project: string; agent: string; event: string;
-  tool?: string; paths?: string[]; status?: string; excerpt?: string;
-  /** Tests and the spool replay pin the time; hooks leave it to the store clock. */
-  at?: string;
-}
+export interface CaptureInput extends CaptureFields { project: string }
 export interface CaptureRow {
   id: number; at: string; project: string; agent: string; event: string;
   tool: string | null; paths: string[]; status: string | null; excerpt: string;
@@ -80,10 +76,29 @@ export interface CaptureOptions {
   /** Host-supplied R6 values win over the shard and home config files. */
   capMb?: number; retentionDays?: number;
   busyTimeoutMs?: number;
+  /** Host-only brief view: open existing capture only, without schema/index/replay writes. */
+  readOnly?: boolean;
+  /** Host-only row ceiling for the read-only snapshot; overflow is unavailable, never empty. */
+  maxReadRows?: number;
+  /** Host-only optional brief: retain the newest maxReadRows ids, with explicit partial coverage. */
+  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 type CaptureAppend = { id: number } | { spooled: true };
+export interface CaptureAppendOptions {
+  /** Opaque stable source receipt for deterministic transcript replay. Requires an explicit source timestamp. */
+  receipt?: string;
+}
+export type CaptureAppend = { id: number; already?: true } | { spooled: true };
 
 /** One row after validation, deny-filtering, bounding and screening: what both the insert and the spool carry. */
 interface NormalizedCapture {
@@ -122,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,
   };
 }
 
@@ -154,28 +173,90 @@ 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. */
   private contended = false;
+  private readonly readOnly: boolean;
+  private recentReadIds?: number[];
+  /** True when the optional recent snapshot excludes older capture rows. */
+  readonly recentReadTruncated: boolean = false;
 
   constructor(opts: CaptureOptions) {
     if (typeof opts.project !== "string" || !opts.project.trim()) throw new Error("capture shards need a project key");
     if (opts.memoryDir !== undefined && opts.home !== undefined) throw new Error("choose a home or an exact memory directory");
+    this.readOnly = opts.readOnly === true;
+    if (opts.readOnly !== undefined && typeof opts.readOnly !== "boolean") throw new Error("invalid capture read-only option");
+    if (opts.recentReadRows !== undefined && (typeof opts.recentReadRows !== "boolean" || !this.readOnly)) throw new Error("recent capture rows require a read-only store");
+    const maxReadRows = opts.maxReadRows ?? 128;
+    if (this.readOnly && (!Number.isSafeInteger(maxReadRows) || maxReadRows < 1 || maxReadRows >= Number.MAX_SAFE_INTEGER)) throw new Error("invalid capture read row bound");
     this.base = opts.memoryDir ?? memoryBase(opts.home);
-    const machine = opts.machine ?? machineId(this.base).id;
+    const machine = opts.machine ?? (this.readOnly ? this.existingMachine() : machineId(this.base).id);
+    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);
-    ensureShardDescriptor(this.base, this.key);
+    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
+        || readShardDescriptor(this.base, shardKeyHash(this.key))?.key !== this.key) throw new Error("capture shard identity unavailable");
+    } else ensureShardDescriptor(this.base, this.key);
     this.dir = captureShardDir(this.base, opts.project, machine);
-    mkdirSync(this.dir, { recursive: true, mode: 0o700 });
-    chmodSync(this.dir, 0o700); // mkdir's mode applies only when it creates the directory
+    if (!this.readOnly) {
+      mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+      chmodSync(this.dir, 0o700); // mkdir's mode applies only when it creates the directory
+    }
+    if (this.readOnly) for (const file of [join(this.dir, "config.json"), join(this.base, "capture-config.json")]) {
+      const stat = lstatSync(file, { throwIfNoEntry: false });
+      if (stat && (!stat.isFile() || stat.isSymbolicLink() || stat.size > 64 * 1024)) throw new Error("capture configuration unavailable");
+    }
     const config = readCaptureConfig(this.dir, this.base); // each invocation: a config change applies at the next hook
     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.
+      for (const directory of [this.base, join(this.base, "projects"), join(this.base, "projects", shardKeyHash(this.key)),
+        join(this.base, "projects", shardKeyHash(this.key), "machine"), this.dir]) {
+        const stat = lstatSync(directory);
+        if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("capture read path unavailable");
+      }
+      const stat = lstatSync(file);
+      if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("capture database unavailable");
+      const timeout = opts.busyTimeoutMs ?? 0;
+      if (!Number.isSafeInteger(timeout) || timeout < 0 || timeout > 3000) throw new Error("invalid capture busy timeout");
+      const db = this.db = new Database(file, { readonly: true });
+      try {
+        db.run(`PRAGMA busy_timeout = ${timeout}`); db.run("PRAGMA cache_size = -2048"); db.run("PRAGMA mmap_size = 0");
+        db.run("BEGIN");
+        if (opts.recentReadRows) {
+          // The existing rows_at index supplies the reverse time/id walk; retain ids only.
+          // One sentinel records excluded history without counting or loading its bodies.
+          const sql = "SELECT id FROM rows INDEXED BY rows_at ORDER BY at DESC, id DESC LIMIT ?";
+          const plan = db.query(`EXPLAIN QUERY PLAN ${sql}`).all(maxReadRows + 1) as { detail: string }[];
+          if (plan.some(row => row.detail.includes("TEMP B-TREE"))) throw new Error("capture recent index unavailable");
+          const recent = db.query(sql).all(maxReadRows + 1) as { id: number }[];
+          this.recentReadIds = recent.slice(0, maxReadRows).map(row => row.id);
+          this.recentReadTruncated = recent.length > maxReadRows;
+        } else {
+          const count = (db.query("SELECT COUNT(*) AS n FROM (SELECT 1 FROM rows LIMIT ?)").get(maxReadRows + 1) as { n: number }).n;
+          if (count > maxReadRows) throw new Error("capture brief row bound exceeded");
+        }
+        if (resolveAlias(this.base, this.requestedKey) !== this.key) throw new Error("capture alias binding changed");
+      } catch (error) { db.close(); throw error; }
+      this.migrated = 0;
+      return;
+    }
     const db = new Database(file, { create: true });
     this.db = db;
     try { chmodSync(file, 0o600); } catch { /* best effort */ }
@@ -195,6 +276,20 @@ export class CaptureStore {
     this.migrated = this.contended ? 0 : this.migrateLegacy();
   }
 
+  private existingMachine(): string {
+    const file = join(this.base, "machine.json"), stat = lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 4096) throw new Error("capture machine identity unavailable");
+    const value = JSON.parse(readFileSync(file, "utf8")) as { id?: unknown };
+    if (typeof value?.id !== "string" || !/^[a-f0-9]{16}$/.test(value.id)) throw new Error("capture machine identity unavailable");
+    return value.id;
+  }
+  private writable(): void {
+    if (this.readOnly) throw new Error("capture store is read-only");
+  }
+  private checkReadBinding(): void {
+    if (this.readOnly && resolveAlias(this.base, this.requestedKey) !== this.key) throw new Error("capture alias binding changed");
+  }
+
   /** The pre-T1 machine-wide store hands this project key's rows AND spool lines to the shard, once; an emptied legacy store goes away. */
   private migrateLegacy(): number {
     const legacyDir = join(this.base, "capture"); // the pre-T1 machine-wide location (this branch never shipped)
@@ -270,6 +365,7 @@ export class CaptureStore {
   private mcpReady = false;
   /** One-time MCP read cost only: hooks neither create this derived index nor scan history to fill it. */
   private ensureMcpFts(): boolean {
+    if (this.readOnly) return !!this.db.query("SELECT 1 FROM sqlite_master WHERE name = 'mcp_fts' AND type = 'table'").get();
     if (!fts5Available()) return false;
     if (this.mcpReady) return true;
     try {
@@ -303,46 +399,54 @@ export class CaptureStore {
    * and a later drainer — under any screen — inserts exactly that row. On lock contention the row goes to the spool
    * and the caller exits fast (R2); the next uncontended writer replays it with its original timestamp.
    */
-  append(input: CaptureInput): CaptureAppend {
+  append(input: CaptureInput, options: CaptureAppendOptions = {}): CaptureAppend {
+    this.writable();
     const str = (v: unknown, max: number) => typeof v === "string" && v.length > 0 && v.length <= max;
     if (!str(input.project, 400) || !str(input.agent, 64) || !str(input.event, 64)) throw new Error("capture rows need a project, an agent and an event");
     if (input.at !== undefined && (typeof input.at !== "string" || !Number.isFinite(Date.parse(input.at)))) throw new Error("capture row time must be a parseable time string");
+    const receipt = options.receipt;
+    if (receipt !== undefined && (typeof receipt !== "string" || !/^[a-f0-9]{64}$/.test(receipt) || input.at === undefined)) throw new Error("capture receipt needs a stable time and a 64-hex digest");
     const row = this.normalize(input);
+    // Reuse the immutable spool format and its existing unique index: a crash between capture and cursor
+    // advance replays exactly the same screened line, whether first written directly or under contention.
+    const spoolId = receipt === undefined ? null : createHash("sha256").update(this.spoolLine(row, receipt)).digest("hex");
     if (this.contended) {
-      this.spool(row);
+      this.spool(row, receipt);
       return { spooled: true };
     }
     try {
       this.drain(); // replay earlier spooled rows first, so row ids stay in hook order
       // The row and its running byte count commit or roll back together: a lock after the INSERT cannot spool a duplicate.
-      const id = this.db.transaction(() => this.insertRow(row, null)).immediate();
+      const result = this.db.transaction((): CaptureAppend => {
+        const id = this.insertRow(row, spoolId);
+        if (id !== undefined) return { id };
+        const prior = this.db.query("SELECT id FROM rows WHERE spool_id = ?").get(spoolId) as { id: number } | null;
+        if (!prior) throw new Error("capture receipt lookup failed");
+        return { id: prior.id, already: true };
+      }).immediate();
       try { this.evict(); } catch (error) {
         if (!lockError(error)) throw error; // the row is already committed; a locked eviction simply resumes on a later append
       }
-      return { id: id! };
+      return result;
     } catch (error) {
       if (!lockError(error)) throw error;
-      this.spool(row);
+      this.spool(row, receipt);
       return { spooled: true };
     }
   }
 
   /** The one place input becomes a row: caps fields, deny-filters paths, screens the excerpt, counts its bytes. */
   private normalize(input: CaptureInput): NormalizedCapture {
-    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 ? this.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);
-    if (excerpt && this.screen(excerpt)) excerpt = "[secret-screened]";
-    return { at, project: input.project, agent: input.agent, event: input.event, tool, paths, status, excerpt,
-      bytes: Buffer.byteLength(excerpt) + Buffer.byteLength(JSON.stringify(paths)) + ROW_OVERHEAD_BYTES };
+    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 };
   }
 
-  private spool(row: NormalizedCapture): void {
-    this.spoolRaw(JSON.stringify({ ...row, nonce: randomBytes(12).toString("hex") }));
+  private spoolLine(row: NormalizedCapture, nonce = randomBytes(12).toString("hex")): string {
+    return JSON.stringify({ ...row, nonce });
+  }
+
+  private spool(row: NormalizedCapture, nonce?: string): void {
+    this.spoolRaw(this.spoolLine(row, nonce));
   }
 
   /**
@@ -355,6 +459,7 @@ export class CaptureStore {
    * already-open shared inode cannot be made immutable by a newer reader.
    */
   drain(): { drained: number; skipped: number } {
+    this.writable();
     let budget = CAPTURE_DRAIN_MAX_LINES, byteBudget = SPOOL_MAX_BYTES, drained = 0, skipped = 0;
     if (this.contended) return { drained, skipped };
     const started = performance.now();
@@ -469,6 +574,7 @@ export class CaptureStore {
    * deleted; the curated store is a different file this class never opens (AC5).
    */
   evict(): { expired: number; trimmed: number } {
+    this.writable();
     if (this.contended) return { expired: 0, trimmed: 0 };
     const start = performance.now();
     const expired = this.evictWhere("at < ?", [new Date(this.now() - this.retentionDays * 24 * 3600_000).toISOString()], start);
@@ -501,7 +607,9 @@ export class CaptureStore {
   }
 
   rows(f: { project?: string; sinceId?: number; limit?: number } = {}): CaptureRow[] {
+    this.checkReadBinding();
     const where: string[] = [], bind: (string | number)[] = [];
+    if (this.recentReadIds) { where.push("id IN (SELECT value FROM json_each(?))"); bind.push(JSON.stringify(this.recentReadIds)); }
     if (f.project) { where.push("project = ?"); bind.push(f.project); }
     if (f.sinceId !== undefined) { where.push("id > ?"); bind.push(f.sinceId); }
     const rows = this.db.query(`SELECT * FROM rows${where.length ? ` WHERE ${where.join(" AND ")}` : ""} ORDER BY id LIMIT ?`).all(...bind, f.limit ?? 1000) as RawRow[];
@@ -510,7 +618,12 @@ export class CaptureStore {
 
   /** Exact-project, bounded body pages; MCP screens before filling its public candidate window. */
   readPage(window: ReadWindow & { query?: string; match?: "substring" }): { rows: CaptureRow[]; next?: ReadRef; engine?: "fts5" | "substring" } {
+    this.checkReadBinding();
     const { columns, where, bind } = readWindowSql(window, "id");
+    if (this.recentReadIds) {
+      if (window.query !== undefined) throw new Error("recent capture brief does not support query indexes");
+      where.push("id IN (SELECT value FROM json_each(?))"); bind.push(JSON.stringify(this.recentReadIds));
+    }
     const engine = window.query === undefined ? undefined : window.match !== "substring" && this.ensureMcpFts() ? "fts5" : "substring";
     if (window.query !== undefined && engine === "fts5") {
       const match = ftsTerms(window.query); if (!match) return { rows: [], engine };
@@ -522,6 +635,7 @@ export class CaptureStore {
   }
 
   stats(): { rows: number; bytes: number; capMb: number; retentionDays: number; fileBytes: number } {
+    this.checkReadBinding();
     let fileBytes = 0;
     try { fileBytes = statSync(join(this.dir, "capture.db")).size; } catch { /* not created yet */ }
     return { rows: (this.db.query("SELECT COUNT(*) AS n FROM rows").get() as { n: number }).n, bytes: this.bytes(), capMb: this.capMb, retentionDays: this.retentionDays, fileBytes };

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