@staix/agent-mem 0.5.0 → 0.6.0

package/src/memory/aliases.ts

@@ -0,0 +1,83 @@
+import { appendFileSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const SHARD_SCHEMA = "agent-hub.memory.shard/v1";
+
+export interface AliasOp { schema: typeof SHARD_SCHEMA; op: "alias"; at: string; machine: string; alias: string; key: string; actor: string }
+/**
+ * #27 option 2: the person's removal of one alias. An append-only op in the same local `aliases.jsonl` (never a shared-v1 segment, so no shared-v1 reader sees a new op
+ * kind there: an older reader skips the line and keeps resolving the alias, which is the C1 "local only" placement). The latest op for an alias wins, so after an
+ * `unalias` the key resolves to itself again, and a later `alias` op maps it again.
+ */
+export interface UnaliasOp { schema: typeof SHARD_SCHEMA; op: "unalias"; at: string; machine: string; alias: string; actor: string }
+export type AliasLogOp = AliasOp | UnaliasOp;
+
+export function aliasLogPath(base: string): string {
+  return join(base, "aliases.jsonl");
+}
+
+/**
+ * One person-reviewed alias op, appended to `aliases.jsonl`. An alias never chains (its target must not itself be
+ * an alias), and a machine that races the append keeps both ops: the latest one wins at read time.
+ */
+export function appendAlias(base: string, input: { alias: string; key: string; actor: string; machine: string; at?: string }): AliasOp {
+  const alias = input.alias.trim(), key = input.key.trim();
+  if (!alias || !key) throw new Error("an alias needs both keys");
+  if (alias === key) throw new Error("an alias cannot target itself");
+  if (resolveAlias(base, key) !== key) throw new Error("an alias cannot target another alias");
+  // The other direction too, using only the latest op per alias: a target abandoned by a later retarget or a removal is free again.
+  const currentTargets = new Set(effectiveAliases(base).values());
+  if (currentTargets.has(alias)) throw new Error("an alias target cannot become an alias");
+  const op: AliasOp = { schema: SHARD_SCHEMA, op: "alias", at: input.at ?? new Date().toISOString(), machine: input.machine, alias, key, actor: input.actor };
+  mkdirSync(base, { recursive: true, mode: 0o700 });
+  appendFileSync(aliasLogPath(base), JSON.stringify(op) + "\n", { mode: 0o600 });
+  return op;
+}
+
+/** Every alias and unalias op in order (the full history); a malformed or unknown line is skipped, never fatal. */
+export function listAliases(base: string): AliasLogOp[] {
+  let text = "";
+  try { text = readFileSync(aliasLogPath(base), "utf8"); } catch { return []; }
+  const ops: AliasLogOp[] = [];
+  for (const line of text.split("\n").filter(Boolean)) {
+    try {
+      const op = JSON.parse(line) as AliasLogOp;
+      if (op?.schema !== SHARD_SCHEMA || typeof op.alias !== "string") continue;
+      if (op.op === "alias" && typeof op.key === "string") ops.push(op);
+      else if (op.op === "unalias") ops.push(op);
+    } catch { /* a malformed line is skipped */ }
+  }
+  return ops;
+}
+
+/** The aliases in force: for each alias key the latest op decides, and an `unalias` removes it. Map of alias key to canonical key. */
+export function effectiveAliases(base: string): Map<string, string> {
+  const latest = new Map<string, string>();
+  for (const op of listAliases(base)) { if (op.op === "alias") latest.set(op.alias, op.key); else latest.delete(op.alias); }
+  return latest;
+}
+
+/** The canonical key for a possibly aliased one: the latest op for it, one hop (aliases never chain). An unaliased key is its own canonical key. */
+export function resolveAlias(base: string, key: string): string {
+  return effectiveAliases(base).get(key) ?? key;
+}
+
+/** Every key currently aliased to `canonical`, sorted (the keys whose curated rows the CLI and MCP project filter now covers, #27 option 1). */
+export function aliasedKeys(base: string, canonical: string): string[] {
+  return [...effectiveAliases(base)].filter(([, key]) => key === canonical).map(([alias]) => alias).sort();
+}
+
+/**
+ * One person-reviewed removal, appended to `aliases.jsonl`. Nothing is rewritten: the alias line stays in the history and the later op wins. Refused when the key is
+ * not aliased now, so a typo never records a removal that means nothing.
+ */
+export function appendUnalias(base: string, input: { alias: string; actor: string; machine: string; at?: string }): UnaliasOp {
+  const alias = input.alias.trim();
+  if (!alias) throw new Error("an alias removal needs the alias key");
+  if (!effectiveAliases(base).has(alias)) throw new Error(`no alias to remove: ${alias} is not aliased now`);
+  const op: UnaliasOp = { schema: SHARD_SCHEMA, op: "unalias", at: input.at ?? new Date().toISOString(), machine: input.machine, alias, actor: input.actor };
+  mkdirSync(base, { recursive: true, mode: 0o700 });
+  appendFileSync(aliasLogPath(base), JSON.stringify(op) + "\n", { mode: 0o600 });
+  return op;
+}
+

package/src/memory/capacity.ts

@@ -1,8 +1,10 @@
 import { spawnSync } from "node:child_process";
-import { appendFileSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync } from "node:fs";
 import { totalmem } from "node:os";
 import { join } from "node:path";
 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 { captureShardGrowth, captureShardStats, readCaptureConfigFile, CAPTURE_DEFAULT_CAP_MB, CAPTURE_DEFAULT_RETENTION_DAYS, type CaptureConfig } from "./capture.ts";
 
@@ -11,49 +13,16 @@ import { captureShardGrowth, captureShardStats, readCaptureConfigFile, CAPTURE_D
  * `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`.
+ * Proposal rule (owner decision, 2026-10-17, item 2): the proposed cap and retention are the largest values 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, and they may be above
+ * the current ones. The cap is the disk-share bound itself; retention is the share over the daily growth, up to a 365-day ceiling. R2 halves the cap
+ * and R3 halves the retention. The reason names every binding constraint: `disk-share retention` or `retention ceiling`, `disk-share cap`,
+ * `R3 search RSS`, `R2 hook cost`. The advisor never writes: applying stays person-only, preview first.
  *
  * 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 } {
@@ -93,6 +62,8 @@ export interface CapacityReport {
 }
 
 const MB = 1048576, GROWTH_DAYS = 7, PROJECT_DAYS = 30;
+// ponytail: the advisor never proposes more than a year of retention. The ceiling keeps a quiet home's proposal finite; the upgrade path is a person setting (a configured ceiling) once someone wants longer.
+const RETENTION_CEILING_DAYS = 365;
 
 export function capacityReport(opts: {
   home?: string; memoryDir?: string; diskShare?: number; now?: () => number;
@@ -133,16 +104,20 @@ export function capacityReport(opts: {
   // 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;
+  // 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.
+  const retentionCeiling = Math.max(RETENTION_CEILING_DAYS, current.retentionDays);
+  let capMb = Math.max(1, Math.floor(budgetBytes / MB));
+  let retentionDays = retentionCeiling;
   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");
+  const fitDays = bytesPerDay > 0 ? Math.floor(budgetBytes / bytesPerDay) : Infinity;
+  if (fitDays < retentionCeiling) {
+    retentionDays = Math.max(1, fitDays);
+    binding.push("disk-share retention: steady-state capture at the current growth fills the disk-share bound");
+  } else {
+    binding.push(`retention ceiling: ${retentionCeiling} days fit the disk share, so the ceiling stops growth`);
   }
+  binding.push("disk-share cap: the cap is the largest size the disk-share bound allows");
   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");
@@ -151,7 +126,7 @@ export function capacityReport(opts: {
     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";
+  const reason = binding.join("; ");
   return {
     at: new Date(now()).toISOString(),
     capture: { shards: shards.length, bytes, rows, rowsPerDay, bytesPerDay },

package/src/memory/capture-input.ts

@@ -0,0 +1,31 @@
+import { looksSecret } from "./screen.ts";
+import { isDenied } from "./platform.ts";
+
+export const CAPTURE_MAX_EXCERPT = 2000;
+export const CAPTURE_MAX_PATHS = 32;
+const ROW_OVERHEAD_BYTES = 96;
+
+export interface CaptureFields {
+  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 NormalizedCaptureFields {
+  at: string; agent: string; event: string;
+  tool: string | null; paths: string[]; status: string | null; excerpt: string; bytes: number;
+}
+
+/** 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 {
+  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);
+  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

@@ -1,12 +1,13 @@
 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 { machineId } from "./machine.ts";
 import { readWindowSql, readRef, type ReadWindow, type ReadRef, ftsTerms, fts5Available } from "./search-fts.ts";
 
 /**
@@ -39,15 +40,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 +56,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 +73,20 @@ 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;
 }
-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 {
@@ -158,24 +161,77 @@ export class CaptureStore {
   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) {
+      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 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 +251,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 +340,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 +374,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));
+    return { at, project: input.project, agent, event, tool, paths, status, excerpt, bytes };
+  }
+
+  private spoolLine(row: NormalizedCapture, nonce = randomBytes(12).toString("hex")): string {
+    return JSON.stringify({ ...row, nonce });
   }
 
-  private spool(row: NormalizedCapture): void {
-    this.spoolRaw(JSON.stringify({ ...row, nonce: randomBytes(12).toString("hex") }));
+  private spool(row: NormalizedCapture, nonce?: string): void {
+    this.spoolRaw(this.spoolLine(row, nonce));
   }
 
   /**
@@ -355,6 +434,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 +549,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 +582,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 +593,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 +610,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/machine.ts

@@ -0,0 +1,31 @@
+import { randomBytes } from "node:crypto";
+import { linkSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface Machine { id: string; label: string }
+/** Random per `~/.agenthub`, with a person-given label; created on first use. */
+export function machineId(dir: string): Machine {
+  const file = join(dir, "machine.json");
+  const read = (): Machine | undefined => {
+    try {
+      const m = JSON.parse(readFileSync(file, "utf8")) as Machine;
+      if (/^[0-9a-f]{16}$/.test(m?.id)) return { id: m.id, label: typeof m.label === "string" ? m.label : m.id };
+    } catch { /* none, or unreadable */ }
+    return undefined;
+  };
+  const found = read();
+  if (found) return found;
+  // Hubs of several projects can start at once on a fresh home: each writes its own temp file and links it into place,
+  // which fails if another got there first; then everyone reads the one identity that won.
+  const id = randomBytes(8).toString("hex");
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const tmp = `${file}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ id, label: id }) + "\n", { mode: 0o600 });
+  try { linkSync(tmp, file); } catch { /* another process created it: its identity wins */ } finally { rmSync(tmp, { force: true }); }
+  // A file that is there but holds no valid id is never overwritten (another process may be reading it): the store
+  // fails to open, so the hub says hub memory is unavailable instead of filing notes under no machine.
+  const won = read();
+  if (!won) throw new Error(`${file} holds no valid machine id; remove it and a new one is made`);
+  return won;
+}
+

package/src/memory/metrics.ts

@@ -0,0 +1,63 @@
+import { closeSync, constants, fstatSync, openSync, readSync, appendFileSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** Rolling resource samples; importing this leaf never loads a memory store or capacity probe. */
+export interface MetricSample { at: string; kind: "hook" | "search"; wallMs?: number; rssMB?: number; rawRssMB?: number; idleMB?: number; captureDrops?: number; captureDropReason?: CaptureDropReason }
+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;
+}
+
+
+export type CaptureDropReason = "spool_full" | "cwd_removed" | "undrainable_expired" | "scope_unknown";
+const DROP_REASONS: readonly CaptureDropReason[] = ["spool_full", "cwd_removed", "undrainable_expired", "scope_unknown"];
+/** Numeric notice only, bounded to the rolling metric tail; never an all-time counter. */
+export function captureDropSummary(base: string): Partial<Record<CaptureDropReason, number>> {
+  const counts: Partial<Record<CaptureDropReason, number>> = {};
+  let fd: number | undefined;
+  try {
+    fd = openSync(metricsPath(base), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const stat = fstatSync(fd); if (!stat.isFile()) return counts;
+    const start = Math.max(0, stat.size - METRICS_MAX_BYTES), bytes = Buffer.alloc(stat.size - start);
+    const length = readSync(fd, bytes, 0, bytes.length, start);
+    let text = new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, length));
+    if (start) text = text.slice(text.indexOf("\n") + 1);
+    for (const line of text.split("\n").filter(Boolean).slice(-METRICS_KEEP)) {
+      try {
+        const sample = JSON.parse(line) as MetricSample;
+        if (sample.kind !== "hook" || !DROP_REASONS.includes(sample.captureDropReason!) || !Number.isSafeInteger(sample.captureDrops) || sample.captureDrops! <= 0) continue;
+        const reason = sample.captureDropReason!;
+        counts[reason] = (counts[reason] ?? 0) + sample.captureDrops!;
+      } catch { /* A malformed metric is never a notice. */ }
+    }
+  } catch { /* Metric availability never denies the native call. */ }
+  finally { if (fd !== undefined) closeSync(fd); }
+  return counts;
+}