@staix/agent-mem 0.12.0 → 0.14.0

package/src/memory/metrics.ts

@@ -38,26 +38,38 @@ export function readMetrics(base: string, limit = METRICS_KEEP): MetricSample[]
 
 export type CaptureDropReason = "spool_full" | "cwd_removed" | "undrainable_expired" | "scope_unknown" | "project_archived" | "project_forgotten";
 const DROP_REASONS: readonly CaptureDropReason[] = ["spool_full", "cwd_removed", "undrainable_expired", "scope_unknown", "project_archived", "project_forgotten"];
-/** Numeric notice only, bounded to the rolling metric tail; never an all-time counter. */
+/** Numeric notice only, bounded to the rolling metric tail; never an all-time counter. Fails open to no counts: hooks never deny over metrics. */
 export function captureDropSummary(base: string): Partial<Record<CaptureDropReason, number>> {
+  const read = readCaptureDrops(base);
+  return read.readable ? read.counts : {};
+}
+
+/**
+ * The same bounded read, but it says when an existing metrics file could not be read (a person-facing report must not show that as zero, #132).
+ * An absent file is readable with no counts. `reason` is a fixed phrase, never file content.
+ */
+export function readCaptureDrops(base: string): { readable: true; counts: Partial<Record<CaptureDropReason, number>>; lines: number; malformedLines: number } | { readable: false; reason: string } {
   const counts: Partial<Record<CaptureDropReason, number>> = {};
-  let fd: number | undefined;
+  let fd: number | undefined, lines = 0, malformedLines = 0;
   try {
-    fd = openSync(metricsPath(base), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
-    const stat = fstatSync(fd); if (!stat.isFile()) return counts;
+    try { fd = openSync(metricsPath(base), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return { readable: true, counts, lines: 0, malformedLines: 0 }; return { readable: false, reason: "metrics.jsonl exists but cannot be opened" }; }
+    const stat = fstatSync(fd); if (!stat.isFile()) return { readable: false, reason: "metrics.jsonl is not a plain file" };
     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)) {
+    const tail = text.split("\n").filter(line => line.trim() !== "").slice(-METRICS_KEEP);
+    lines = tail.length;
+    for (const line of tail) {
       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 { malformedLines++; /* A malformed metric is never a notice; doctor reports how many were skipped. */ }
     }
-  } catch { /* Metric availability never denies the native call. */ }
+  } catch { return { readable: false, reason: "metrics.jsonl cannot be read or is not UTF-8" }; }
   finally { if (fd !== undefined) closeSync(fd); }
-  return counts;
+  return { readable: true, counts, lines, malformedLines };
 }

package/src/memory/migrate.ts

@@ -5,6 +5,7 @@ import { legacyEntries, legacyHead, readLegacySnapshot, type LegacyCheckpoint }
 import { acquireMutation } from "./mutation.ts";
 import { canonicalPath, realPath } from "./platform.ts";
 import { canonicalJSON, fsyncDirectory, generationDescriptor, generationDir, hashJSON, readProfileJSON, readSelector, resolveProfile, validGeneration, withProfileLock, writeProfileJSON, type BoundProfile } from "./generation.ts";
+import { label, PLAIN, singleLine, type Style } from "./style.ts";
 
 export interface SourcePrefix extends LegacyCheckpoint { tailBytes: number }
 interface MigrationJournal {
@@ -104,6 +105,7 @@ function refuseShardSelection(memoryDir: string): void {
 }
 
 export async function migrate(options: MigrateOptions): Promise<MigrationResult> {
+  if (readSelector(options.memoryDir).selector?.schema === "agent-mem.profile/v2") throw new Error("public prune view is forward-only; deactivation is unavailable");
   if (options.authorizedPerson !== true || options.tty !== true) throw new Error("migration requires an authorized person in a terminal");
   if (!["dry-run", "apply", "resume", "deactivate"].includes(options.mode) || options.generation !== undefined && !validGeneration(options.generation)) throw new Error("invalid migration request");
   const memoryDir = existsSync(options.memoryDir) ? realPath(options.memoryDir) : canonicalPath(options.memoryDir);
@@ -222,3 +224,32 @@ export async function migrate(options: MigrateOptions): Promise<MigrationResult>
     } finally { releaseGeneration(); }
   });
 }
+
+/** Render a migration result for a person; JSON output remains owned by the CLI. */
+export function migrationText(result: MigrationResult, s: Style = PLAIN): string {
+  const active = result.profile.kind === "generation";
+  const needsResume = result.mode === "resume" && !active;
+  const state = needsResume ? "attention" : result.mode === "dry-run" ? "preview" : "complete";
+  const groups = (value: Record<string, number>) => Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, count]) => `${singleLine(key)}=${count}`).join(", ");
+  const countRows = result.counts ? [
+    ["valid", result.counts.validRows], ["skipped", result.counts.skippedRows], ["tailBytes", result.counts.tailBytes],
+    ["expired", result.counts.expiredRows], ["eligible", result.counts.eligibleRows],
+  ].map(([key, value]) => `${label(s, "ok")} ${key} ${value}`) : [`${label(s, "skipped")} counts not returned for this mode`];
+  const operationCounts = result.counts ? groups(result.counts.byOp) : "", tierCounts = result.counts ? groups(result.counts.byTier) : "";
+  if (operationCounts) countRows.push(`${label(s, "ok")} operations ${operationCounts}`);
+  if (tierCounts) countRows.push(`${label(s, "ok")} tiers ${tierCounts}`);
+  let action = "none";
+  if (result.mode === "dry-run" && !active) action = "apply migration: amem migrate --apply";
+  else if (needsResume) action = "resume migration: amem migrate --resume";
+  else if (result.mode === "deactivate" && active) action = "deactivate generation: amem migrate --deactivate";
+  const lines = [
+    `${s.bold("amem migrate:")} ${state}${result.alreadyActive ? " (already active)" : ""}`,
+    `${label(s, "ok")} profile ${result.profile.kind}${result.profile.generation ? ` (generation ${result.profile.generation.slice(0, 8)})` : ""}`,
+    `${label(s, "ok")} home ${singleLine(result.profile.home)}`,
+    `${label(s, "ok")} current directory ${singleLine(result.profile.dir)}`,
+    ...countRows,
+    `${label(s, "ok")} effect ${singleLine(result.consequence)}`,
+    `Next action: ${action}`,
+  ];
+  return lines.join("\n");
+}

package/src/memory/mutation.ts

@@ -1,6 +1,7 @@
 import { Database } from "bun:sqlite";
 import { chmodSync, lstatSync } from "node:fs";
 import { join } from "node:path";
+import { realPath } from "./platform.ts";
 
 export const MUTATION_BUSY_TIMEOUT_MS = 3000;
 // ponytail: older hubs (before consuming this agent-mem), raw/legacy log writers and any segment editor
@@ -14,12 +15,31 @@ export function mutationDatabase(dir: string, busyTimeoutMs = MUTATION_BUSY_TIME
   return db;
 }
 
-/** Sync holds a separate connection across awaits; an unrelated call on the same MemoryStore cannot bypass it. */
-export function acquireMutation(dir: string): (() => void) | undefined {
-  const db = mutationDatabase(dir);
+declare const mutationBrand: unique symbol;
+/** Callable for compatibility; authority exists only in the module-private live registry. */
+export interface MutationHandle { (): void; readonly [mutationBrand]: true }
+const mutations = new WeakMap<MutationHandle, { dir: string; dev: number; ino: number; db: Database; active: boolean }>();
+export function assertMutationHandle(handle: MutationHandle, dir: string): void {
+  const state = mutations.get(handle), stat = lstatSync(dir);
+  if (!state || !state.active || !state.db.inTransaction || stat.isSymbolicLink() || !stat.isDirectory()
+    || realPath(dir) !== state.dir || stat.dev !== state.dev || stat.ino !== state.ino) throw new Error("mutation handle unavailable or directory changed");
+}
+/** Sync holds a separate connection across awaits; an unrelated call cannot bypass it. */
+export function acquireMutation(dir: string): MutationHandle | undefined {
+  const stat = lstatSync(dir);
+  if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error("mutation directory unavailable");
+  const canonical = realPath(dir), db = mutationDatabase(canonical);
   try { db.run("BEGIN IMMEDIATE"); }
   catch { db.close(); return undefined; }
-  return () => { try { db.run("ROLLBACK"); } finally { db.close(); } };
+  const release = (() => {
+    const state = mutations.get(release)!;
+    if (!state.active) return;
+    state.active = false;
+    try { db.run("ROLLBACK"); } finally { db.close(); }
+  }) as MutationHandle;
+  mutations.set(release, { dir: canonical, dev: stat.dev, ino: stat.ino, db, active: true });
+  try { assertMutationHandle(release, dir); } catch (error) { release(); throw error; }
+  return release;
 }
 
 /** Short local admission fence, never held across sync/network or data mutations. */

package/src/memory/note-add.ts

@@ -1,9 +1,9 @@
 import { KINDS, type Kind, type MemoryStore, type NoteInput, type Scope, type Tier } from "./store.ts";
+import { cliAttribution } from "./cli-attribution.ts";
 import type { StandalonePolicy } from "./policy.ts";
 
 /**
- * F6 (agent-mem#40): person note authoring. `amem note add` writes one curated note the person typed, through the configured policy. The note is authored by the
- * person (`peer: "person"`, `source: "person"`), which is why the command is person-only like every ordinary command (an agent marker is refused before it runs).
+ * F6 (agent-mem#40): note authoring writes one curated note through the configured policy. The invocation peer is recorded for attribution; source remains `person`.
  *
  * A `fail` note carries structured fields. Its body uses the same labelled lines an accepted `fail` candidate produces, so a note written here and one accepted
  * from `amem_remember` read alike and `fail` search and the plan guard see one shape.
@@ -59,7 +59,7 @@ export function buildNote(input: NoteAddInput, project: string): NoteInput {
     if (text.includes("\0")) refuse("the note text holds a NUL byte");
   }
   if (text.length > NOTE_MAX_CHARS) refuse(`the note is ${text.length} characters; the limit is ${NOTE_MAX_CHARS}`);
-  return { op: "note", project, scope: input.scope, tier: input.tier, kind: input.kind, peer: "person", source: "person", ...(title ? { title } : {}), text, about: [] };
+  return { op: "note", project, scope: input.scope, tier: input.tier, kind: input.kind, peer: cliAttribution()?.peer ?? "person", source: "person", ...(title ? { title } : {}), text, about: [] };
 }
 
 /**
@@ -68,7 +68,7 @@ export function buildNote(input: NoteAddInput, project: string): NoteInput {
  */
 export function noteAdd(store: MemoryStore, project: string, input: NoteAddInput, policy: StandalonePolicy): NoteAddResult {
   const note = buildNote(input, project);
-  if (!policy.screenStandalone({ ...(note.title ? { title: note.title } : {}), text: note.text, about: note.about })   /* no undefined field: the screen refuses one */) refuse("the note is refused by the configured privacy policy (secrets, personal data, deny paths and the patterns in amem.config.json); edit it or the policy and try again");
+  if (!policy.screenStandalone({ ...(note.title ? { title: note.title } : {}), text: note.text, about: note.about, peer: note.peer })) refuse("the note is refused by the configured privacy policy (secrets, personal data, deny paths and the patterns in amem.config.json); edit it or the policy and try again");
   return { id: store.note(note, input.tier === "short") };
 }
 

package/src/memory/prune-publisher-lineage.ts

@@ -0,0 +1,139 @@
+/** Private local publication authority, never a transport object or a native-row rewrite. */
+import { createHash, randomBytes } from "node:crypto";
+import { closeSync, constants, fstatSync, fsyncSync, linkSync, lstatSync, openSync, readFileSync, readSync, readdirSync, unlinkSync, writeFileSync, type Stats } from "node:fs";
+import { join } from "node:path";
+import { canonicalJSON, fsyncDirectory, type BoundProfile } from "./generation.ts";
+import { assertMutationHandle, type MutationHandle } from "./mutation.ts";
+import { realPath } from "./platform.ts";
+import { validatePruneRow, type PruneRow } from "./prune.ts";
+import type { PublicPruneLineage } from "./public-prune-witness.ts";
+import { resolveShardProfile } from "./shard.ts";
+
+export interface PublisherBoundaryV1 {
+  schema: "agent-mem.prune-publisher-boundary/v1";
+  generation: string; sealHash: string; machine: string; end: number; prefixSha256: string;
+}
+const fail = (): never => { throw new Error("prune publisher boundary unavailable or changed"); };
+function guard(value: unknown): asserts value { if (!value) fail(); }
+function owned(stat: Stats, directory = false, links = 1): void {
+  guard(!stat.isSymbolicLink() && (directory ? stat.isDirectory() : stat.isFile() && stat.nlink === links)
+    && stat.uid === process.getuid?.() && (stat.mode & 0o077) === 0);
+}
+function same(a: Stats, b: Stats): boolean { return a.dev === b.dev && a.ino === b.ino && a.size === b.size && a.mtimeMs === b.mtimeMs && a.ctimeMs === b.ctimeMs; }
+function bytes(file: string, limit: number, links = 1): Buffer {
+  const before = lstatSync(file); owned(before, false, links); guard(before.size <= limit);
+  const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const opened = fstatSync(fd); owned(opened, false, links); guard(same(before, opened));
+    const value = readFileSync(fd); guard(value.length === before.size && same(opened, fstatSync(fd)) && same(opened, lstatSync(file))); return value;
+  } finally { closeSync(fd); }
+}
+function context(profile: BoundProfile, mutation: MutationHandle): { machine: string; sealHash: string; log: string; file: string; local: string } {
+  assertMutationHandle(mutation, profile.dir);
+  guard(profile.kind === "generation" && profile.sharded && profile.foreignPruneFormat === "agent-mem.public-prune-witness/v1");
+  const current = resolveShardProfile(profile.home, profile.shardUser ? { user: true } : { project: profile.shardKey });
+  guard(current.generation === profile.generation && current.foreignPruneFormat === profile.foreignPruneFormat
+    && current.selectorRevision === profile.selectorRevision && realPath(current.dir) === realPath(profile.dir));
+  for (const dir of [profile.home, profile.dir, join(profile.dir, "local"), join(profile.dir, "log")]) owned(lstatSync(dir), true);
+  const rootMachine = JSON.parse(bytes(join(profile.home, "machine.json"), 4096).toString("utf8")) as { id?: unknown };
+  const shardMachine = JSON.parse(bytes(join(profile.dir, "machine.json"), 4096).toString("utf8")) as { id?: unknown };
+  guard(typeof rootMachine.id === "string" && /^[a-f0-9]{16}$/.test(rootMachine.id) && rootMachine.id === shardMachine.id);
+  // resolveShardProfile checks descriptor/sourceDigest; hash the original complete seal bytes too.
+  const sealHash = createHash("sha256").update(bytes(join(profile.dir, "generation-seal.json"), 4096)).digest("hex");
+  bytes(join(profile.dir, "generation.json"), 4096); bytes(join(profile.dir, "migration-sources.json"), 262144);
+  const machine = rootMachine.id, local = join(profile.dir, "local");
+  return { machine, sealHash, local, file: join(local, `publisher-boundary-${machine}.json`), log: join(profile.dir, "log", `${machine}.jsonl`) };
+}
+/** Streaming complete prefix and bounded line scan; no lifetime byte/row omission. */
+function inspect(log: string, end?: number, rows?: ReadonlyMap<string, { row: PruneRow; canonical: string }>): { end: number; hash: string; found: Set<string> } {
+  const before = lstatSync(log, { throwIfNoEntry: false });
+  if (!before) { guard(end === undefined || end === 0); return { end: 0, hash: createHash("sha256").digest("hex"), found: new Set() }; }
+  owned(before); const bound = end ?? before.size; guard(Number.isSafeInteger(bound) && bound >= 0 && bound <= before.size);
+  const fd = openSync(log, constants.O_RDONLY | constants.O_NOFOLLOW), digest = createHash("sha256"), chunk = Buffer.alloc(65536);
+  let position = 0, lineStart = 0, line: number[] = [], last = -1, boundaryNewline = bound === 0;
+  const found = new Set<string>(), older = new Set<string>();
+  try {
+    guard(same(before, fstatSync(fd)));
+    while (position < before.size) {
+      const count = readSync(fd, chunk, 0, Math.min(chunk.length, before.size - position), position); guard(count > 0);
+      if (position < bound) digest.update(chunk.subarray(0, Math.min(count, bound - position)));
+      for (let i = 0; i < count; i++) {
+        const byte = chunk[i]!; last = byte;
+        if (position + i + 1 === bound) boundaryNewline = byte === 10;
+        if (rows) {
+          if (byte === 10) {
+            guard(line.length > 0);
+            const value: unknown = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(Uint8Array.from(line)));
+            const id = value && typeof value === "object" && "id" in value && typeof value.id === "string" ? value.id : undefined;
+            const candidate = id === undefined ? undefined : rows.get(id);
+            const canonical = lineStart >= bound ? canonicalJSON(value) : undefined;
+            if (candidate) {
+              if (lineStart < bound) older.add(candidate.row.id);
+              else if (canonical === candidate.canonical) { validatePruneRow(value, candidate.row.generation, "synced"); found.add(candidate.row.id); }
+            }
+            line = []; lineStart = position + i + 1;
+          } else { line.push(byte); guard(line.length <= 1024 * 1024); }
+        }
+      }
+      position += count;
+      if (!rows && position === before.size) break;
+    }
+    guard(boundaryNewline && (before.size === 0 || last === 10) && same(before, fstatSync(fd)) && same(before, lstatSync(log)));
+    for (const id of older) found.delete(id);
+    return { end: bound, hash: digest.digest("hex"), found };
+  } finally { closeSync(fd); }
+}
+function decode(value: Buffer): PublisherBoundaryV1 {
+  const text = new TextDecoder("utf-8", { fatal: true }).decode(value), v = JSON.parse(text) as PublisherBoundaryV1;
+  guard(v && Object.keys(v).sort().join(",") === "end,generation,machine,prefixSha256,schema,sealHash"
+    && v.schema === "agent-mem.prune-publisher-boundary/v1" && /^[a-f0-9]{32}$/.test(v.generation)
+    && /^[a-f0-9]{16}$/.test(v.machine) && /^[a-f0-9]{64}$/.test(v.sealHash) && /^[a-f0-9]{64}$/.test(v.prefixSha256)
+    && Number.isSafeInteger(v.end) && v.end >= 0 && text === canonicalJSON(v) + "\n"); return v;
+}
+/** Recover only an exact private temp/final inode pair while holding the real kernel fence. */
+function recover(file: string, local: string): void {
+  const final = lstatSync(file, { throwIfNoEntry: false }); if (!final || final.nlink === 1) return;
+  owned(final, false, 2); decode(bytes(file, 4096, 2));
+  const candidates = readdirSync(local).filter(name => /^\.publisher-boundary-[a-f0-9]{32}\.tmp$/.test(name))
+    .map(name => join(local, name)).filter(name => { const stat = lstatSync(name); return stat.dev === final.dev && stat.ino === final.ino; });
+  guard(candidates.length === 1); const temp = candidates[0]!; owned(lstatSync(temp), false, 2);
+  guard(same(final, lstatSync(file)) && same(final, lstatSync(temp))); unlinkSync(temp); fsyncDirectory(local);
+}
+export function assertPublisherBoundary(profile: BoundProfile, mutation: MutationHandle): PublisherBoundaryV1 {
+  const ctx = context(profile, mutation); recover(ctx.file, ctx.local);
+  const value = decode(bytes(ctx.file, 4096));
+  guard(value.generation === profile.generation && value.machine === ctx.machine && value.sealHash === ctx.sealHash);
+  guard(inspect(ctx.log, value.end).hash === value.prefixSha256); assertMutationHandle(mutation, profile.dir); return value;
+}
+/** Explicit sync-only admission: existing complete own log is a conservative migration upper bound. */
+export function ensurePublisherBoundary(profile: BoundProfile, mutation: MutationHandle): PublisherBoundaryV1 {
+  const ctx = context(profile, mutation); recover(ctx.file, ctx.local);
+  if (lstatSync(ctx.file, { throwIfNoEntry: false })) return assertPublisherBoundary(profile, mutation);
+  const prefix = inspect(ctx.log), value: PublisherBoundaryV1 = { schema: "agent-mem.prune-publisher-boundary/v1", generation: profile.generation!,
+    sealHash: ctx.sealHash, machine: ctx.machine, end: prefix.end, prefixSha256: prefix.hash };
+  const temp = join(ctx.local, `.publisher-boundary-${randomBytes(16).toString("hex")}.tmp`), fd = openSync(temp, "wx", 0o600);
+  try { writeFileSync(fd, canonicalJSON(value) + "\n"); fsyncSync(fd); } finally { closeSync(fd); }
+  // A crash leaves either a harmless unregistered temp or an exact recoverable pair.
+  linkSync(temp, ctx.file); fsyncDirectory(ctx.local); unlinkSync(temp); fsyncDirectory(ctx.local);
+  return assertPublisherBoundary(profile, mutation);
+}
+/** Verify one candidate set with one complete JSONL parse, independent of the candidate count. */
+export function publisherPruneLineages(profile: BoundProfile, mutation: MutationHandle, rows: readonly PruneRow[]): Map<string, PublicPruneLineage> {
+  const boundary = assertPublisherBoundary(profile, mutation), candidates = new Map<string, { row: PruneRow; canonical: string }>();
+  for (const row of rows) {
+    if (row.machine !== boundary.machine || row.generation !== boundary.generation || row.placement !== "synced") continue;
+    validatePruneRow(row, boundary.generation, "synced");
+    const canonical = canonicalJSON(row), previous = candidates.get(row.id);
+    guard(!previous || previous.canonical === canonical); candidates.set(row.id, { row, canonical });
+  }
+  const result = new Map<string, PublicPruneLineage>();
+  if (!candidates.size) return result;
+  const ctx = context(profile, mutation), proof = inspect(ctx.log, boundary.end, candidates);
+  guard(proof.hash === boundary.prefixSha256); assertPublisherBoundary(profile, mutation);
+  for (const id of proof.found) result.set(id, { kind: "post-seal", seal: boundary.sealHash, end: boundary.end });
+  return result;
+}
+/** Compatibility entry point; batch callers avoid rescanning once per original. */
+export function publisherPruneLineage(profile: BoundProfile, mutation: MutationHandle, row: PruneRow): PublicPruneLineage | undefined {
+  return publisherPruneLineages(profile, mutation, [row]).get(row.id);
+}

package/src/memory/prune.ts

@@ -1,5 +1,6 @@
 import { canonicalJSON, hashJSON, validGeneration } from "./generation.ts";
 import { entryId, type Entry, type NoteEntry } from "./store.ts";
+import { label, PLAIN, singleLine, type Style } from "./style.ts";
 
 export const PRUNE_ROW_MAX_BYTES = 16_384, PRUNE_PLAN_MAX_BYTES = 262_144;
 export const PRUNE_ROW_MAX_TARGETS = 32, PRUNE_PLAN_MAX_ROWS = 16, PRUNE_PLAN_MAX_TARGETS = 256;
@@ -128,7 +129,7 @@ export function reducePruneRows(rows: readonly { row: unknown; placement: PruneP
 }
 function authenticate(port: PruneStorePort, auth: PruneAuthorization): void {
   guard(validGeneration(port.generation) && /^[a-f0-9]{16}$/.test(port.machine) && revision(port.selectorRevision()));
-  guard(auth.actor === "person" && typeof auth.authorize === "function" && auth.authorize() === true && typeof auth.project === "string" && auth.project.length > 0);
+  guard((auth.actor === "person" || auth.actor === "agent") && typeof auth.authorize === "function" && auth.authorize() === true && typeof auth.project === "string" && auth.project.length > 0);
 }
 function policyRevision(auth: PruneAuthorization): string {
   if (!auth.policy) return "local-only";
@@ -257,3 +258,29 @@ export function applyPrune(port: PruneStorePort, input: unknown, auth: PruneAuth
     });
   });
 }
+
+/** Human-readable preview or apply result. A preview is descriptive output, not a serialized sealed plan. */
+export function pruneText(result: PrunePlan | { completed: string[] }, s: Style = PLAIN): string {
+  if ("completed" in result) {
+    return [
+      `amem prune: ${s.ok("complete")}`,
+      `${label(s, result.completed.length ? "ok" : "skipped")} completed prune rows: ${result.completed.length}`,
+      ...result.completed.map(id => `  ${label(s, "ok")} ${id}`),
+      "Next action: none",
+    ].join("\n");
+  }
+  const targetIds = result.rows.flatMap(row => row.payload.targets.map(target => target.id));
+  const next = targetIds.length
+    ? "save this preview with --json, then amem prune --apply --plan <file>; keep --user if used in the preview"
+    : "none; the sealed plan contains no prune rows";
+  return [
+    `amem prune: ${s.attention("preview")}`,
+    `${label(s, "ok")} project: ${singleLine(result.project)}`,
+    ...(result.rows.length ? [`${label(s, "ok")} cutoff: ${result.rows[0]!.payload.cutoff}`] : []),
+    `${label(s, targetIds.length ? "attention" : "skipped")} selection: eligible ${result.counts.eligible}, selected ${result.counts.selected}, local ${result.counts.local}, synced ${result.counts.synced}`,
+    ...(result.hasMore ? ["more eligible entries remain beyond this plan"] : []),
+    ...result.rows.flatMap(row => row.payload.targets.map(target => `  ${label(s, "attention")} ${row.placement}: ${target.id} (expired ${target.expiredAt})`)),
+    `Next action: ${next}`,
+    ...(targetIds.length ? ["The readable preview is not a sealed JSON plan."] : []),
+  ].join("\n");
+}