@staix/agent-mem 0.11.0 → 0.13.0

package/src/memory/consolidate.ts

@@ -28,14 +28,15 @@ export class ConsolidationProposalError extends Error {
 const modelAnswer = (row: View) => row.peer === "amem-model" || row.text.startsWith("Model answer:");
 /** On-demand candidate writes only. Every source is screened once under one policy and source revision. */
 export async function proposeConsolidation(store: MemoryStore, candidates: CandidateStore, options: ConsolidationOptions): Promise<ConsolidationReport> {
-  if (options.actor !== "person") throw Error("consolidation requires person intent");
+  const actor = options.actor;
+  if (actor !== "person" && actor !== "agent") throw Error("invalid consolidation actor");
   if (options.allowed?.() === false) throw Error("consolidation unavailable");
   if (realPath(candidates.dir) !== realPath(store.profile.home)) throw Error("consolidation requires its own candidate home");
   const project = options.project, version = options.policyVersion(), policy = options.policy();
   if (!project.trim() || typeof version !== "string") throw Error("consolidation context unavailable");
   const sourceCurrent = store.beginRecallRead();
   const check = () => {
-    if (options.actor !== "person" || options.project !== project || options.allowed?.() === false || options.policyVersion() !== version) throw Error("consolidation context changed");
+    if (options.actor !== actor || options.project !== project || options.allowed?.() === false || options.policyVersion() !== version) throw Error("consolidation context changed");
     options.assertCurrent?.(); sourceCurrent();
   };
   check();

package/src/memory/decay-review.ts

@@ -74,7 +74,7 @@ export function decayPreview(store: MemoryStore, project: string, options: Decay
     return { project, profile: hashJSON(store.profile), days, at: new Date(now).toISOString(), cutoff: new Date(cutoff).toISOString(), demoteExpiresAt: store.shortExpiry(), entries: entries.slice(0, DECAY_PREVIEW_LIMIT), withheld, citedExemptions: counters === undefined ? null : citedExemptions, truncated: entries.length > DECAY_PREVIEW_LIMIT, citationHistory: "unknown" };
   });
 }
-/** Duplicate-group forgetting requires a separate person group review, never an implicit decay expansion. */
+/** Duplicate-group forgetting requires a separate group review, never an implicit decay expansion. */
 export function assertExactDecayForget(store: MemoryStore, ids: readonly string[], project: string): void {
   store.withDeferredPromotions(() => {
     for (const id of ids) {
@@ -104,10 +104,10 @@ export class DecayApplyError extends Error {
 }
 /** The host shows this exact plan; every selected revision/eligibility is rechecked before any append. */
 export function applyDecay(store: MemoryStore, plan: DecayPlan, options: DecayApplyOptions): { action: "demote" | "forget"; ids: string[]; expiresAt?: string } {
-  if (options.actor !== "person") throw Error("decay apply requires person authority");
+  if (options.actor !== "person" && options.actor !== "agent") throw Error("decay apply requires a valid actor");
   options.assertCurrent?.();
   const ids = options.ids === undefined ? plan.entries.map(entry => entry.target.id) : idsOf(options.ids);
-  if ((options.ids === undefined || options.forget) && options.confirmed !== true) throw Error("decay bulk/forget apply requires explicit person confirmation");
+  if ((options.ids === undefined || options.forget) && options.confirmed !== true) throw Error("decay bulk/forget apply requires explicit confirmation");
   if (hashJSON(store.profile) !== plan.profile || ids.some(id => !plan.entries.some(entry => entry.target.id === id))) throw Error("decay preview binding changed or target was not previewed");
   const action = options.forget ? "forget" : "demote";
   if (!ids.length) return { action, ids };
@@ -126,7 +126,7 @@ export function applyDecay(store: MemoryStore, plan: DecayPlan, options: DecayAp
     for (let index = 0; index < ids.length; index++) {
       const id = ids[index]!;
       try {
-        const result = options.forget ? store.forget(id, "person", plan.project, true) : store.demote(id, "person", plan.project, plan.demoteExpiresAt);
+        const result = options.forget ? store.forget(id, options.actor, plan.project, true) : store.demote(id, options.actor, plan.project, plan.demoteExpiresAt);
         if (!result) throw Error("decay target outcome unavailable");
         applied.push(id);
       } catch (error) { throw new DecayApplyError({ action, applied: [...applied], failed: id, remaining: ids.slice(index + 1), ...expiry }, error); }

package/src/memory/doctor.ts

@@ -4,12 +4,14 @@ import { join } from "node:path";
 import { Database } from "bun:sqlite";
 import { sessionStartBrief } from "../session-brief.ts";
 import { pendingSummary } from "./candidate-pending.ts";
+import { readCaptureDrops } from "./metrics.ts";
 import { walkShards } from "./catalog.ts";
 import { loadAmemConfig, repoConfigRoot } from "./config.ts";
 import { readSelector } from "./generation.ts";
 import { processLiveness, withGitTimeout } from "./platform.ts";
 import { endLikeSignal, STOP_SIGNALS } from "./sync-cadence.ts";
 import { boundRepoRoot } from "./repo-scope.ts";
+import { facts, label, PLAIN, type Style } from "./style.ts";
 import { shardDir } from "./shard.ts";
 import type { MemoryStore, View } from "./store.ts";
 import { nextSyncAt, readSyncState, remoteConfigured, syncDue, usableState } from "./sync-cadence.ts";
@@ -25,7 +27,7 @@ import { nextSyncAt, readSyncState, remoteConfigured, syncDue, usableState } fro
 export type SectionStatus = "ok" | "attention" | "skipped" | "unavailable";
 export type Section<T extends object = Record<string, unknown>> = { status: SectionStatus } & T;
 export const DOCTOR_SCHEMA = "amem.doctor/v1";
-export const CLIS = ["claude", "codex", "kimi", "pi"] as const;
+export const CLIS = ["claude", "codex", "kimi", "pi", "qwen"] as const;
 export type Cli = typeof CLIS[number];
 /** A CLI whose last capture is older than this is called stale. */
 export const CAPTURE_STALE_MS = 7 * 86400_000;
@@ -53,6 +55,8 @@ export interface DoctorReport {
   project: string;
   sections: {
     duplicates: Section; stale: Section; candidates: Section; capture: Section; brief: Section; index: Section; readers: Section; policy: Section; cadence: Section;
+    /** Added after v1 shipped (#132); additive, so the schema stays amem.doctor/v1. */
+    drops: Section;
   };
 }
 
@@ -218,7 +222,7 @@ function captureSection(options: DoctorOptions): Section {
     const needs = registered ? state !== "fresh" : state === "stale";
     if (needs) attention.push(cli);
     clis[cli] = { hook: registered ? "registered" : "manual", ...(registered ? { hookEvidence: "setup receipt" } : {}), ...(phase === "prepared" ? { setup: "prepared, not applied" } : {}), capture: state, lastCaptureAt: last, rows: entry?.rows ?? 0,
-      ...(needs || (!registered && state === "never") ? { hint: registered ? `the ${cli} hook is registered but its capture is ${state}: open a session${cli === "claude" ? "" : `, or run amem ingest ${cli}`}` : cli === "claude" ? "run amem setup claude --apply to register the capture hooks" : `run amem setup ${cli} --apply, or amem ingest ${cli} by hand` } : {}) };
+      ...(needs || (!registered && state === "never") ? { hint: registered ? cli === "codex" && state === "never" ? "the codex hook is registered but has never captured: approve it in Codex's /hooks trust review (setup never grants hook trust), then open a session" : `the ${cli} hook is registered but its capture is ${state}: open a session${cli === "claude" ? "" : `, or run amem ingest ${cli}`}` : cli === "claude" ? "run amem setup claude --apply to register the capture hooks" : `run amem setup ${cli} --apply, or amem ingest ${cli} by hand` } : {}) };
   }
   return { status: !readable ? "unavailable" : attention.length ? "attention" : "ok", ...(readable ? {} : { reason: "a capture database could not be read" }), clis };
 }
@@ -270,6 +274,17 @@ function policySection(options: DoctorOptions): Section {
   } catch (error) { return unavailable(message(error)); }
 }
 
+/** #132: capture rows hooks dropped, by reason, from the bounded rolling metrics tail (counts only; no row text is ever recorded there). */
+function dropsSection(options: DoctorOptions): Section {
+  const read = readCaptureDrops(options.home);
+  if (!read.readable) return unavailable(read.reason);   // an existing file doctor cannot read is never a healthy zero
+  // One torn line (an interrupted append) is reported, not fatal; a tail with lines of which none parses is a file doctor cannot decode.
+  if (read.lines > 0 && read.malformedLines === read.lines) return unavailable("metrics.jsonl has no decodable record in its recent tail");
+  const counts = read.counts, total = Object.values(counts).reduce((sum, n) => sum + (n ?? 0), 0);
+  return { status: total ? "attention" : "ok", window: "recent metrics tail", total, counts, ...(read.malformedLines ? { malformedLines: read.malformedLines } : {}),
+    ...(total ? { hint: "capture rows were dropped recently (see counts by reason); amem doctor --json keeps the numbers" } : {}) };
+}
+
 /** F16: which CLIs ingest at SessionEnd (setup receipts), and the person-owned sync cadence. amem registers no sync hook (a hook may not do network work). */
 function cadenceSection(options: DoctorOptions): Section {
   const ingest: Record<string, string> = {};
@@ -397,19 +412,57 @@ async function runDoctor(options: DoctorOptions): Promise<DoctorReport> {
   let sections: DoctorReport["sections"];
   try {
     await tick();
-    sections = { duplicates, stale, candidates, capture: captureSection(options), brief: await briefSection(options, curated, workBase, copyFailed), index, readers: readersSection(options), policy: policySection(options), cadence: cadenceSection(options) };
+    sections = { duplicates, stale, candidates, capture: captureSection(options), brief: await briefSection(options, curated, workBase, copyFailed), index, readers: readersSection(options), policy: policySection(options), cadence: cadenceSection(options), drops: dropsSection(options) };
     await tick();   // a signal that arrived during the last synchronous stage is handled while the guard is still installed
   } finally { try { curated?.close(); } finally { try { if (scratch) rmSync(scratch, { recursive: true, force: true }); } finally { unguard?.(); } } }
   return { schema: DOCTOR_SCHEMA, status: worst(Object.values(sections).map(section => section.status)), home: { path: options.home, source: options.homeSource }, project: options.project, sections };
 }
 
-export function doctorText(report: DoctorReport): string {
-  const mark = (status: SectionStatus) => status === "ok" ? "ok         " : status === "attention" ? "ATTENTION  " : status === "skipped" ? "skipped    " : "unavailable";
-  const lines = [`amem doctor: ${report.status}`, `home ${report.home.path} (${report.home.source}), project ${report.project}`];
-  for (const [name, section] of Object.entries(report.sections)) {
-    const { status, hint, reason, ...detail } = section as Section & { hint?: string; reason?: string };
-    lines.push(`${mark(status)} ${name}: ${JSON.stringify(detail)}${reason ? `  (${reason})` : ""}`);
-    if (hint) lines.push(`            -> ${hint}`);
+/** Section order and one-line descriptions for the person-facing report (#125). */
+const SECTION_TITLE: Record<keyof DoctorReport["sections"], string> = {
+  duplicates: "duplicate notes", stale: "stale path references", candidates: "review candidates", capture: "capture per CLI", brief: "session brief",
+  index: "index equals rebuild", readers: "reader leases", policy: "policy in effect", cadence: "ingest and sync cadence", drops: "recent capture drops",
+};
+
+function sectionDetail(name: string, detail: Record<string, unknown>, s: Style): string[] {
+  if (name === "capture" && detail.clis && typeof detail.clis === "object") {
+    return Object.entries(detail.clis as Record<string, Record<string, unknown>>).map(([cli, row]) => {
+      const capture = String(row.capture), mark = capture === "fresh" ? s.ok(capture) : capture === "stale" ? s.attention(capture) : s.dim(capture);
+      return `${cli.padEnd(7)} hook ${row.hook}${row.setup ? ` (${row.setup})` : ""}, capture ${mark}${row.lastCaptureAt ? ` (last ${row.lastCaptureAt})` : ""}, ${row.rows} rows`;
+    });
+  }
+  if (name === "cadence") {
+    const sync = (detail.sync ?? {}) as Record<string, unknown>, ingest = (detail.ingest ?? {}) as Record<string, string>;
+    return [`ingest ${Object.entries(ingest).map(([cli, how]) => `${cli} ${how}`).join(", ")}`,
+      `sync remote ${sync.remote}${sync.remote === "configured" ? `, last ok ${sync.lastOkAt ?? "never"}, failures ${sync.failures}${sync.due ? ", due" : ""}` : ""}`];
+  }
+  if (name === "drops") {
+    if (detail.counts === undefined) return [];   // unavailable: only its reason is shown
+    const counts = Object.entries((detail.counts ?? {}) as Record<string, number>);
+    return [counts.length ? `${counts.map(([reason, n]) => `${reason.replaceAll("_", " ")} ${n}`).join(", ")} (recent metrics tail)` : "none in the recent metrics tail"].map(line => detail.malformedLines ? `${line}; ${detail.malformedLines} malformed lines skipped` : line);
+  }
+  if (name === "brief" && typeof detail.tokens === "number") return [`${detail.tokens} of ${detail.budget} tokens${detail.coverage ? `, coverage ${facts(detail.coverage as Record<string, unknown>) || "complete"}` : ""}`];
+  const { examples, ...rest } = detail;
+  const line = facts(rest);
+  return [...(line ? [line] : []), ...(Array.isArray(examples) && examples.length ? [`examples ${examples.map(item => Array.isArray(item) ? item.join("=") : String(item)).join(", ")}`] : [])];
+}
+
+/** The person-facing report: overall state, one labelled row per section, then the next actions. `amem doctor --json` keeps the full report. */
+export function doctorText(report: DoctorReport, s: Style = PLAIN): string {
+  const entries = Object.entries(report.sections) as [keyof DoctorReport["sections"], Section & { hint?: string; reason?: string }][];
+  const count = (status: SectionStatus) => entries.filter(([, section]) => section.status === status).length;
+  const summary = facts({ attention: count("attention"), unavailable: count("unavailable"), skipped: count("skipped") });
+  const lines = [`${s.bold("amem doctor:")} ${report.status === "ok" ? s.ok(report.status) : report.status === "attention" ? s.attention(report.status) : s.error(report.status)}${summary ? `  (${summary})` : `  (all ${entries.length} checks ok)`}`,
+    `home     ${report.home.path} ${s.dim(`(${report.home.source})`)}`, `project  ${report.project}`, ""];
+  const actions: string[] = [];
+  for (const [name, section] of entries) {
+    const { status, hint, reason, ...detail } = section;
+    lines.push(`${label(s, status)} ${name}: ${s.dim(SECTION_TITLE[name])}`);
+    for (const line of sectionDetail(name, detail, s)) lines.push(`            ${line}`);
+    if (reason) lines.push(`            ${s.dim(`reason: ${reason}`)}`);
+    if (hint) actions.push(`${name}: ${hint}`);
+    if (name === "capture" && detail.clis) for (const [cli, row] of Object.entries(detail.clis as Record<string, { hint?: string }>)) if (row.hint) actions.push(`capture ${cli}: ${row.hint}`);
   }
+  lines.push("", actions.length ? "Next actions:" : "Next actions: none", ...actions.map(action => `  - ${action}`));
   return lines.join("\n");
 }

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 {
@@ -222,3 +223,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/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.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");
+}

package/src/memory/shard-migration.ts

@@ -11,6 +11,7 @@ import { assertNoLiveReaders } from "./reader-lease.ts";
 import { assertCuratedShardPaths, ensureShardDescriptor, shardDir, SHARDED_SCHEMA, userShardDir, SHARD_SCHEMA } from "./shard.ts";
 import { buildGenerationIndex, type Entry } from "./store.ts";
 import { readMigrationSources, type SourcePrefix } from "./migrate.ts";
+import { label, PLAIN, singleLine, type Style } from "./style.ts";
 
 const USER = Symbol("shared-user-shard");
 type Destination = string | typeof USER;
@@ -560,3 +561,40 @@ export async function migrateShards(options: ShardMigrationOptions): Promise<Sha
     return { mode: options.mode, generation, active: true, ...(alreadyActive ? { alreadyActive: true } : {}), counts: counts(plan), ...refusalSummary(plan), consequence: CONSEQUENCE, ...removalEvidence(journal) };
   });
 }
+
+/** Render a shard migration result for a person; JSON output remains owned by the CLI. */
+export function shardMigrationText(result: ShardMigrationResult, s: Style = PLAIN): string {
+  const counts = result.counts;
+  const groupRows = (name: string, value: Record<string, number>) => Object.entries(value).sort(([a], [b]) => a.localeCompare(b))
+    .map(([key, count]) => `${label(s, "ok")} ${name} ${singleLine(key)} ${count}`);
+  const countRows = [
+    ["rows", counts.rows], ["skipped", counts.skippedRows], ["userRows", counts.userRows], ["tailBytes", counts.tailBytes],
+    ["legacyRows", counts.legacyRows], ["generationRows", counts.generationRows], ["generationLocalRows", counts.generationLocalRows],
+    ["legacyLocalRows", counts.legacyLocalRows], ["legacyMainRows", counts.legacyMainRows], ["pruneRows", counts.pruneRows],
+    ["translatedPruneRows", counts.translatedPruneRows], ["refusedRows", counts.refusedRows],
+    ["sharedSupersededByPrivate", counts.sharedSupersededByPrivate], ["crossPrivateReplacement", counts.crossPrivateReplacement],
+    ["danglingRows", counts.danglingRows],
+  ].map(([key, value]) => {
+    const flagged = key === "refusedRows" && counts.refusedRows > 0 || key === "sharedSupersededByPrivate" && counts.sharedSupersededByPrivate > 0
+      || key === "crossPrivateReplacement" && counts.crossPrivateReplacement > 0 || key === "danglingRows" && counts.danglingRows > 0;
+    return `${label(s, flagged ? "attention" : "ok")} ${key} ${value}`;
+  });
+  const warnings = result.refusals ?? [];
+  const attention = warnings.length > 0 || counts.refusedRows > 0 || counts.danglingRows > 0 || (!result.active && result.mode === "resume");
+  const state = attention ? "attention" : result.mode === "dry-run" ? "preview" : result.active ? "complete" : "attention";
+  const action = warnings.length || counts.refusedRows > 0 || counts.danglingRows > 0 ? "resolve the listed refusals or flagged rows before retrying"
+    : result.mode === "dry-run" && (!result.active || counts.rows > 0) ? "apply shard migration: amem migrate --shards --apply"
+    : result.mode === "resume" && !result.active ? "resume shard migration: amem migrate --shards --resume"
+      : "none";
+  return [
+    `${s.bold("amem migrate --shards:")} ${state}${result.alreadyActive ? " (already active)" : ""}`,
+    `${label(s, "ok")} generation ${result.generation.slice(0, 8)}`,
+    ...countRows,
+    ...groupRows("shard rows", counts.byShard),
+    ...groupRows("project rows", counts.byProject),
+    ...(result.deadLeasesRemoved?.length ? [`${label(s, "ok")} dead reader leases removed ${result.deadLeasesRemoved.length}`] : []),
+    ...(warnings.length ? ["Refusals:", ...warnings.map(reason => `  ${label(s, "attention")} ${singleLine(reason)}`)] : []),
+    `${label(s, "ok")} effect ${singleLine(result.consequence)}`,
+    `Next action: ${action}`,
+  ].join("\n");
+}

package/src/memory/status-text.ts

@@ -0,0 +1,47 @@
+import { facts, label, PLAIN, type Style } from "./style.ts";
+
+/** The `amem status` object as the CLI builds it; `amem status --json` prints it unchanged. */
+export interface StatusView {
+  home: { path: string; source: string };
+  config: { machine: string | null; repo: string | null; denyPaths: number; piiPatterns: number } & Record<string, unknown>;
+  candidates: { unavailable: string } | ({ count: number; oldestExpiresInDays: number | null; dueWithin7Days: number; unshown: number; warning?: string });
+  active: boolean; generation?: string; phase?: string;
+  pending: Record<string, unknown> & { rows: number };
+  deadLeasesRemoved?: { lease: string; at: string }[]; refusals?: string[];
+}
+
+/** Person-facing `amem status` (#125): overall state, the effective home and policy, the counts that matter, then next actions. Zero counters are summarized, never listed. */
+export function statusText(status: StatusView, s: Style = PLAIN): string {
+  const actions: string[] = [], warnings: string[] = [];
+  const candidates = status.candidates;
+  let candidateLine: string, candidateState: "ok" | "attention" | "unavailable";
+  if ("unavailable" in candidates) { candidateState = "unavailable"; candidateLine = candidates.unavailable; warnings.push(candidates.unavailable); }
+  else {
+    candidateState = candidates.dueWithin7Days ? "attention" : "ok";
+    candidateLine = candidates.count ? `${candidates.count} pending${candidates.unshown ? ` (${candidates.unshown} never shown)` : ""}${candidates.oldestExpiresInDays !== null ? `, oldest expires in ${candidates.oldestExpiresInDays} days` : ""}` : "none pending";
+    if (candidates.warning) actions.push(candidates.warning);
+    else if (candidates.count) actions.push("review pending candidates: amem review walk");
+  }
+  const refusals = status.refusals ?? [];
+  const interrupted = status.phase === "captured" && !status.active;   // authoring refuses until activation (generation-index.ts)
+  const migrationState: "ok" | "attention" = refusals.length || status.pending.rows || interrupted ? "attention" : "ok";
+  if (interrupted) actions.push("a shard migration stopped after capture and authoring is refused until it activates: amem migrate --shards --resume");
+  if (refusals.length) warnings.push(...refusals.map(reason => `migration refusal: ${reason}`));
+  if (status.pending.rows && !interrupted) actions.push(`${status.pending.rows} old-layout rows wait for the shard migration: amem migrate --shards --resume carries them (amem migrate --shards --dry-run previews first)`);
+  const overall = candidateState === "unavailable" ? "unavailable" : candidateState === "attention" || migrationState === "attention" ? "attention" : "ok";
+  const { machine, repo, denyPaths, piiPatterns, ...limits } = status.config;
+  const pendingCounts = facts(Object.fromEntries(Object.entries(status.pending).filter(([key]) => !key.endsWith("Ids"))));
+  const lines = [
+    `${s.bold("amem status:")} ${overall === "ok" ? s.ok(overall) : overall === "attention" ? s.attention(overall) : s.error(overall)}`,
+    `home     ${status.home.path} ${s.dim(`(${status.home.source})`)}`,
+    "",
+    `${label(s, "ok")} policy: machine ${machine ?? "none (defaults)"}, repo ${repo ?? "none"}; ${denyPaths} deny paths, ${piiPatterns} PII patterns${facts(limits) ? `; ${facts(limits)}` : ""}`,
+    `${label(s, candidateState)} candidates: ${candidateLine}`,
+    `${label(s, migrationState)} layout: ${status.active ? `shards active${status.generation ? ` (generation ${status.generation.slice(0, 8)})` : ""}` : status.phase ? `shard migration ${status.phase}${interrupted ? ", not active" : ""}` : "single home"}; ${pendingCounts ? `pending ${pendingCounts}` : "no pending old-layout appends"}`,
+    ...(status.deadLeasesRemoved?.length ? [`            ${s.dim(`${status.deadLeasesRemoved.length} dead reader leases removed`)}`] : []),
+    ...(warnings.length ? ["", "Warnings:", ...warnings.map(warning => `  - ${s.attention(warning)}`)] : []),
+    "", actions.length ? "Next actions:" : "Next actions: none", ...actions.map(action => `  - ${action}`),
+    s.dim("Full report: amem status --json; health checks: amem doctor"),
+  ];
+  return lines.join("\n");
+}

package/src/memory/store.ts

@@ -1,3 +1,4 @@
+import { cliAttribution } from "./cli-attribution.ts";
 import { Database } from "bun:sqlite";
 import { createHash } from "node:crypto";
 import { appendFileSync, chmodSync, closeSync, constants, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
@@ -193,7 +194,7 @@ export interface StoreOptions { home?: string; memoryDir?: string; ttlMs?: numbe
   lifecycle?: "enforce" | "ignore";
   /** #27: read the `aliases` keys' curated rows as part of the `canonical` project (CLI and MCP only); the library default reads the raw key. Rows are presented under `canonical`. */
   reconcile?: { canonical: string; aliases: readonly string[] };
-  /** Person-only project import may initialize configured alias shards; read-only reconciliation still never creates them. */
+  /** Explicit project import may initialize configured alias shards; read-only reconciliation still never creates them. */
   createAliases?: boolean;
 }
 
@@ -589,7 +590,7 @@ export class MemoryStore {
     let applied = 0;
     if (apply) for (const group of groups) for (const head of group.heads) {
       if (head === group.target) continue;
-      if (!this.supersede(head, group.target, "user", project)) throw new Error("memory dedupe replacement refused; rerun to inspect current relations");
+      if (!this.supersede(head, group.target, cliAttribution()?.actor ?? "user", project)) throw new Error("memory dedupe replacement refused; rerun to inspect current relations");
       applied++;
     }
     return { groups, applied };
@@ -1587,7 +1588,7 @@ export function openShardStore(opts: StoreOptions & { project?: string; user?: b
   const userOverlay = opts.user === true ? undefined : openShardStore({ ...plain, project: undefined, user: true });
   const aliasStores: MemoryStore[] = [];
   try {
-    // #27: read-only reconciliation never creates an alias shard. A person-only project import explicitly can.
+    // #27: read-only reconciliation never creates an alias shard. An explicit project import can.
     if (opts.user !== true && reconcile && reconcile.canonical === opts.project) {
       for (const alias of reconcile.aliases) {
         if (alias === opts.project || !opts.createAliases && !existsSync(join(shardDir(home, alias), "generation.json"))) continue;
@@ -1600,7 +1601,7 @@ export function openShardStore(opts: StoreOptions & { project?: string; user?: b
   } catch (error) { for (const store of aliasStores) store.close(); userOverlay?.close(); throw error; }
 }
 
-/** Person-only migration receipt; this inspector reads raw rows without opening a store or writing any index. */
+/** Administrative migration receipt; this inspector reads raw rows without opening a store or writing any index. */
 export function summarizeRawExpiry(rawLines: string[], now: number, tailBytes: number): import("./migrate.ts").MigrationCounts {
   const bytes = Buffer.from(rawLines.filter(Boolean).join("\n") + (rawLines.length ? "\n" : ""));
   let malformed = 0;

package/src/memory/style.ts

@@ -0,0 +1,40 @@
+/**
+ * A tiny, dependency-free text style for person-facing CLI output (#125).
+ * Color is decoration only: every caller also prints a textual label, so plain output carries the same facts.
+ * JSON output never passes through this module.
+ */
+export interface Style {
+  readonly color: boolean;
+  ok(text: string): string;
+  attention(text: string): string;
+  error(text: string): string;
+  dim(text: string): string;
+  bold(text: string): string;
+}
+
+/** Color only for an interactive stdout, and never with NO_COLOR (any value, per no-color.org) or TERM=dumb. */
+export function colorEnabled(env: Readonly<Record<string, string | undefined>>, isTTY: boolean | undefined): boolean {
+  return isTTY === true && env.NO_COLOR === undefined && env.TERM !== "dumb";
+}
+
+const wrap = (on: boolean, open: number, close: number) => (text: string) => on ? `\x1b[${open}m${text}\x1b[${close}m` : text;
+export function style(color: boolean): Style {
+  return { color, ok: wrap(color, 32, 39), attention: wrap(color, 33, 39), error: wrap(color, 31, 39), dim: wrap(color, 2, 22), bold: wrap(color, 1, 22) };
+}
+export const PLAIN: Style = style(false);
+
+/** Data stays on one human-output row and cannot inject terminal or bidirectional controls. */
+export const singleLine = (text: string): string => text.replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu, " ");
+
+/** Status label, padded so the columns line up; the word is always present. */
+export function label(s: Style, state: "ok" | "attention" | "skipped" | "unavailable" | "error"): string {
+  const word = { ok: "OK", attention: "ATTENTION", skipped: "SKIPPED", unavailable: "UNAVAILABLE", error: "ERROR" }[state].padEnd(11);
+  return state === "ok" ? s.ok(word) : state === "attention" ? s.attention(word) : state === "skipped" ? s.dim(word) : s.error(word);
+}
+
+/** "key value" pairs, leaving out zero, empty and null values; returns "" when nothing material is left. */
+export function facts(values: Record<string, unknown>): string {
+  return Object.entries(values).filter(([, value]) => value !== 0 && value !== null && value !== undefined && value !== false && value !== ""
+    && !(Array.isArray(value) && value.length === 0) && !(typeof value === "object" && !Array.isArray(value) && Object.keys(value as object).length === 0))
+    .map(([key, value]) => `${key} ${typeof value === "object" ? Array.isArray(value) ? value.join(", ") : JSON.stringify(value) : String(value)}`).join(", ");
+}

package/src/memory/vault.ts

@@ -1,6 +1,7 @@
 import { validVaultPath } from "./generation.ts";
 import { createStandalonePolicy, type MemoryPolicy } from "./policy.ts";
 import type { MemoryStore, View, VaultEntry } from "./store.ts";
+import { label, PLAIN, singleLine, type Style } from "./style.ts";
 
 export interface VaultSelection { project: string; policy: MemoryPolicy; limit?: number }
 export type { VaultEntry } from "./store.ts";
@@ -29,6 +30,36 @@ export async function vaultCandidates(store: MemoryStore, options: VaultSelectio
     .sort((a, b) => b.at.localeCompare(a.at) || a.id.localeCompare(b.id)).slice(0, options.limit ?? 50);
 }
 
+/** Human-readable list of screened vault candidates; raw note text is intentionally omitted. */
+export function vaultCandidatesText(rows: readonly View[], s: Style = PLAIN): string {
+  return [
+    `amem vault-candidates: ${rows.length ? s.attention("attention") : s.ok("complete")}`,
+    `${label(s, rows.length ? "attention" : "skipped")} candidates: ${rows.length}`,
+    ...rows.map(row => {
+      const title = singleLine(row.title ?? "(untitled)").slice(0, 120);
+      return `  ${label(s, "attention")} ${singleLine(row.project)}: ${row.id}  ${row.kind}  ${title}`;
+    }),
+    `Next action: ${rows.length ? "open the source repository, then review a candidate with amem show <id> before recording it in your vault" : "none; no screened durable candidates are available"}`,
+  ].join("\n");
+}
+
+/** Human-readable cross-project list, preserving project grouping and omitting note bodies. */
+export function vaultCandidatesAllText(result: {
+  crossedProjects: boolean;
+  projects: readonly { project: string; candidates: readonly View[] }[];
+}, s: Style = PLAIN): string {
+  const count = result.projects.reduce((sum, group) => sum + group.candidates.length, 0);
+  return [
+    `amem vault-candidates: ${count ? s.attention("attention") : s.ok("complete")}${result.crossedProjects ? " (across projects)" : ""}`,
+    `${label(s, count ? "attention" : "skipped")} candidates: ${count}`,
+    ...result.projects.flatMap(group => group.candidates.map(row => {
+      const title = singleLine(row.title ?? "(untitled)").slice(0, 120);
+      return `  ${label(s, "attention")} ${singleLine(group.project)}: ${row.id}  ${row.kind}  ${title}`;
+    })),
+    `Next action: ${count ? (result.crossedProjects ? "open the candidate's source repository, then review it with amem show <id> before recording it in your vault" : "open the source repository, then review a candidate with amem show <id> before recording it in your vault") : "none; no screened durable candidates are available"}`,
+  ].join("\n");
+}
+
 /** Person-facing hosts authenticate intent before calling; no MCP vault-link tool is provided. */
 export async function recordVaultLink(store: MemoryStore, id: string, path: string, options: VaultSelection): Promise<string> {
   const policy = selection(options);

package/src/setup-toml.ts

@@ -162,11 +162,11 @@ function editTomlPath(text: string, path: readonly string[], value: unknown | un
       changes.push({ start: position, end: position, text: `${newline}${key} = ${inline(value)}${eol}` });
     }
     output = replace(text, changes);
-    // Removing the only child of an implicit table must retain its parsed empty parent value.
-    for (let depth = path.length - 1; depth > 0; depth--) {
-      const parent = path.slice(0, depth), wanted = at(expected, parent);
-      if (plain(wanted) && !Object.keys(wanted).length && at(parse(output), parent) === undefined) output += `${output && !output.endsWith("\n") ? eol : ""}[${parent.map(part => JSON.stringify(part)).join(".")}]${eol}`;
-    }
+  }
+  // Removing the only child of an implicit table must retain its parsed empty parent value.
+  for (let depth = path.length - 1; depth > 0; depth--) {
+    const parent = path.slice(0, depth), wanted = at(expected, parent);
+    if (plain(wanted) && !Object.keys(wanted).length && at(parse(output), parent) === undefined) output += `${output && !output.endsWith("\n") ? eol : ""}[${parent.map(part => JSON.stringify(part)).join(".")}]${eol}`;
   }
   if (!isDeepStrictEqual(shape(parse(output)), shape(expected))) return error();
   return output;