@gavin-hu/my-pi-agent 0.12.0 → 0.13.1

package/extensions/job/README.md

@@ -38,10 +38,11 @@ How the `job` call and its result look in the transcript — the call line as a
   killing, and clearing.
 - Reports finished jobs to the model at the start of the next turn, or — for
   jobs started with `wake: true` — by triggering one turn.
-- Kills session-owned jobs on shutdown so no process is left behind; start a
-  job with `detached: true` to keep it running and reattach next session. A
-  detached POSIX job points its own output straight at its log file, so it keeps
-  logging after this process ends.
+- Kills session-owned jobs on shutdown so no process is left behind; on POSIX,
+  start a job with `detached: true` to keep it running and reattach next session.
+  A detached job points its own output straight at its log file, so it keeps
+  logging after this process ends. Windows has neither a process group to leave
+  nor a shell `EXIT` trap, so it refuses the detach instead of faking one.
 
 ## Tool
 
@@ -53,7 +54,7 @@ How the `job` call and its result look in the transcript — the call line as a
 | `cwd` | Working directory (`start`); defaults to the session cwd. |
 | `label` | Short display label (`start`); defaults to the command. |
 | `wake` | Wake the agent with one triggered turn when it finishes (`start`). |
-| `detached` | Leave it running when the session ends (`start`). |
+| `detached` | Leave it running when the session ends (`start`); POSIX only, refused on Windows. |
 | `stdin` | Give the job a stdin pipe so `send` can write to it (`start`); not with `detached`. |
 | `id` | Job id such as `j1` (`status`/`logs`/`send`/`kill`/`wait`/`clear`). |
 | `lines` | Log lines to return (`logs`, 1–2000). |
@@ -191,7 +192,7 @@ document, project wins):
 | `enabled` | `true` | Track jobs at all. |
 | `showStatus` | `true` | Show the `▸ N` / `✗ N` status chips. |
 | `wakeOnFinish` | `false` | Wake the agent when any job finishes. |
-| `detachedByDefault` | `false` | Leave jobs running when the session ends. |
+| `detachedByDefault` | `false` | Leave jobs running when the session ends; inert on Windows. |
 | `maxJobs` | `20` | Finished jobs kept before the oldest are pruned. |
 | `maxLogLines` | `100` | Log lines returned by `logs`. |
 | `maxLogBytes` | `8388608` | Bytes a log segment may reach before it rotates to `<id>.log.1`; `0` keeps logs unbounded. |
@@ -214,8 +215,8 @@ rewritten.
 - **`unknown` still has no exit code on some paths.** A POSIX job is wrapped in
   an `EXIT` trap that writes `$?` to a per-job `.status` file, so a job
   reattached after its session died reports its real exit code. `exec cmd`
-  replaces the shell and bypasses the trap, and Windows has no equivalent, so
-  those jobs settle as `unknown`.
+  replaces the shell and bypasses the trap, and a Windows job has no equivalent,
+  so those settle as `unknown`.
 - **Another session's jobs are shown, but not managed here.** Records are merged
   from every session file so ids stay unique and a peer's job is not reaped, and
   `list`/`/jobs` show them tagged `peer` (a dead session's records are adopted
@@ -236,10 +237,13 @@ rewritten.
   keep appending to the moved inode, or lose everything. Its log therefore grows
   without the `maxLogBytes` cap; `logs` still reads a bounded tail, and the file
   can be emptied by hand.
-- **Windows is best-effort.** Tree-kill uses `taskkill /T`; POSIX uses process
-  groups. A detached job only escapes the parent process on POSIX, where its
-  shell writes the log directly; on Windows it keeps the parent pipe and is
-  captured only until the session ends.
+- **Windows cannot detach a job.** There is no process group to leave and no
+  shell `EXIT` trap, so `detached: true` is refused with the three alternatives
+  (`detached: false`, WSL, a `subagent`) rather than starting a job that would
+  die with the session while claiming to outlive it. `job.detachedByDefault` is
+  inert there instead of failing every start with a config set on another
+  machine, and `doctor` names both facts. Tree-kill is still `taskkill /T`, and a
+  job reported only after its process is gone settles as `unknown`.
 
 ## Non-goals
 

package/extensions/job/format.ts

@@ -13,8 +13,8 @@
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { truncateToWidth } from "@earendil-works/pi-tui";
 import { formatDuration } from "../../lib/format.ts";
+import { clip, LABEL_WIDTH, labelLine } from "../../lib/tui/columns.ts";
 import { GLYPHS, SEPARATORS } from "../../lib/tui/glyphs.ts";
 import { paint, type TuiRole } from "../../lib/tui/tokens.ts";
 import type { JobRecord, JobStatus } from "./types.ts";
@@ -22,9 +22,6 @@ import type { JobRecord, JobStatus } from "./types.ts";
 /** Longest sanitized log line kept for display; longer lines are clipped. */
 const MAX_LOG_LINE = 200;
 
-/** Longest label shown in the transcript or `/jobs` screen. */
-const MAX_DISPLAY_LABEL = 48;
-
 /** ESC-introduced sequences: OSC, CSI, and single-character escapes. */
 const OSC = /\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)/g;
 const CSI = /\u001b\[[0-?]*[ -/]*[@-~]/g;
@@ -111,7 +108,7 @@ function statusWord(job: JobRecord): string {
 
 /** A label clipped to one safe display line. */
 export function clipLabel(text: string): string {
-	return truncateToWidth(sanitizeLogLine(text), MAX_DISPLAY_LABEL, "…");
+	return labelLine(text, sanitizeLogLine);
 }
 
 /** A job's label (falling back to its command) clipped to one safe display line. */
@@ -180,7 +177,7 @@ export function formatCallText(action: string, args: Record<string, unknown>, ar
 		case "start": {
 			const command = typeof args.command === "string" ? sanitizeLogLine(args.command.trim()) : "";
 			if (!command) return argsComplete ? "start" : "start …";
-			const preview = truncateToWidth(command, MAX_DISPLAY_LABEL, "…");
+			const preview = clip(command, LABEL_WIDTH);
 			return `start → ${preview}`;
 		}
 		case "kill":
@@ -188,7 +185,7 @@ export function formatCallText(action: string, args: Record<string, unknown>, ar
 		case "send": {
 			if (!target) return "send";
 			const input = typeof args.input === "string" ? sanitizeLogLine(args.input) : "";
-			const preview = input ? truncateToWidth(input, MAX_DISPLAY_LABEL, "…") : "";
+			const preview = input ? clip(input, LABEL_WIDTH) : "";
 			const parts = [preview, args.eof === true ? "EOF" : ""].filter(Boolean).join(" + ");
 			return parts ? `send ${target} → ${parts}` : `send ${target}`;
 		}

package/extensions/job/runtime.ts

@@ -127,6 +127,8 @@ export interface RuntimeOptions {
 	killTree?: KillTreeFn;
 	startToken?: StartTokenFn;
 	now?: () => number;
+	/** Platform seam: whether this is Windows. Defaults to the running platform. */
+	isWindows?: () => boolean;
 	/** Fixed config, for tests; production loads it per cwd. */
 	config?: JobsConfig;
 }
@@ -202,6 +204,7 @@ export function createJobsRuntime(options: RuntimeOptions = {}): JobsRuntime {
 	const killTree = options.killTree ?? defaultKillTree;
 	const startToken = options.startToken ?? defaultStartToken;
 	const now = options.now ?? (() => Date.now());
+	const isWindows = options.isWindows ?? (() => process.platform === "win32");
 
 	const jobs = new Map<string, Job>();
 	const handles = new Map<string, Handle>();
@@ -717,7 +720,20 @@ export function createJobsRuntime(options: RuntimeOptions = {}): JobsRuntime {
 		if (!config.enabled) throw new Error("jobs are disabled.");
 		ui.attach(ctx);
 		const wantsStdin = startOptions.stdin === true;
-		const detached = startOptions.detached ?? config.detachedByDefault;
+		// Windows has no process group to leave and no shell `EXIT` trap to record an
+		// exit code, so a job there cannot outlive the session: refusing an explicit
+		// detach is the honest answer, and it happens before any id is reserved.
+		// `detachedByDefault` stays inert instead of failing every start with a config
+		// the user set on another machine; `doctor` names that.
+		const windows = isWindows();
+		if (windows && startOptions.detached === true) {
+			throw new Error(
+				"A detached job cannot outlive the session on Windows: there is no process group to leave " +
+					"and no shell EXIT trap to record its exit code. Start it with `detached: false`, " +
+					"run it under WSL, or move the work into a `subagent`.",
+			);
+		}
+		const detached = windows ? false : (startOptions.detached ?? config.detachedByDefault);
 		// A detached job outlives this process, so a stdin pipe owned by this session
 		// would hand it EOF the moment the session ends; refuse instead of silently
 		// dropping the pipe (or the detach).
@@ -732,14 +748,15 @@ export function createJobsRuntime(options: RuntimeOptions = {}): JobsRuntime {
 		// so a peer that advanced the shared counter cannot hand us a live job's id.
 		const id = store.nextId(jobs.keys());
 		const logPath = store.logPath(id);
-		const statusPath = process.platform === "win32" ? null : store.statusPath(id);
-		// A detached POSIX job points its own output at the log, so it keeps logging
-		// and survives after this process ends; Windows keeps the parent pipe.
-		const detachOutput = detached && process.platform !== "win32";
+		// Only a POSIX shell has an `EXIT` trap to record a status, and only a detached
+		// job points its own output at the log so it keeps logging after this process
+		// ends (which on Windows is never: `detached` is false there).
+		const statusPath = windows ? null : store.statusPath(id);
+		const detachOutput = detached;
 
 		// Wrap the command so a POSIX shell records its exit status; the path travels
 		// in the environment so the shell never has to quote it.
-		const program = withExitTrap(startOptions.command, process.platform === "win32", detachOutput);
+		const program = withExitTrap(startOptions.command, windows, detachOutput);
 		const env: NodeJS.ProcessEnv = { ...process.env };
 		if (statusPath) env[STATUS_ENV] = statusPath;
 		if (detachOutput) env[LOG_ENV] = logPath;

package/extensions/job/status.ts

@@ -7,8 +7,10 @@
  * shell never has to quote it). A later session reads that file when it finds a
  * dead pid and reports `exited`/`failed` instead of `unknown`.
  *
- * Windows shells have no equivalent trap, so those jobs keep the old behavior:
- * a reattached job with no code stays `unknown`.
+ * Windows shells have no equivalent trap. A Windows job is never detached (the
+ * runtime refuses it), so the missing trap is not a second limitation: a job
+ * reported only after its process is gone still settles as `unknown`, which
+ * `doctor` names.
  */
 
 import { closeSync, existsSync, openSync, readSync, statSync } from "node:fs";

package/extensions/memory/README.md

@@ -39,9 +39,15 @@ How the `memory` call and its result look in the transcript — the call line as
 - Re-reads each store when its file changes on disk (compared by mtime and size),
   so an external edit lands in the same session without a restart.
 - Exposes `/memory`: in the TUI it opens a picker to add, edit, or forget a
-  single note, filter by scope, and reload; elsewhere it lists the store.
-  `/memory path`, `edit`, and `clear` print the file paths, open the multi-line
-  editor, and clear a scope.
+  single note, merge two notes into one, move a note to the other scope, filter
+  by scope, and reload; elsewhere it lists the store. `/memory path`, `edit`, and `clear` print the file paths,
+  open the multi-line editor, and clear a scope; `/memory doctor` reports store
+  health.
+- Reports store health with `/memory doctor`: note counts and file bytes per
+  scope, how much of the `maxInjectBytes` budget the injection uses and which
+  scope overflowed it, and the near-duplicate pairs the conservative key already
+  considers one fact. It is read-only — the report names the pair and the picker
+  merges it.
 - Loads and writes the project store only when the project is trusted, sanitizes
   every note to one terminal-safe line, and writes atomically.
 
@@ -91,24 +97,49 @@ or stem both survive.
 
 | Command | What it does |
 |---|---|
-| `/memory` | In the TUI, open the picker (add, edit, or forget a note; `s`/Tab filters by scope; `r` reloads). Other modes notify the stored notes. |
+| `/memory` | In the TUI, open the picker (add, edit, forget, merge, or move notes; `s`/Tab filters by scope; `r` reloads). Other modes notify the stored notes. |
 | `/memory list` | Notify the stored notes and counts. |
 | `/memory path` | Notify the two file paths and whether the project store is trusted. |
 | `/memory reload` | Re-read the stores from disk and report what changed. |
+| `/memory doctor` | Report counts, file bytes, the injection budget with the notes it omits, and near-duplicate pairs. Read-only. |
 | `/memory edit [project\|global]` | Open the multi-line editor prefilled with the file and save the result. |
 | `/memory clear [project\|global]` | Clear a scope after a confirmation. |
 
 Bulk deletion lives only in the command, behind a confirm — the model cannot wipe
 memory in one call.
 
+### Picker keys
+
+| Key | Action |
+|---|---|
+| `Enter` / `e` | Edit the focused note in the shared inline editor. |
+| `a` | Add a note to the active scope. |
+| `d` | Forget the focused note after a `y`/`N` confirm. |
+| `m` | Mark the focused note as a merge source; `m` on a second note in the same scope opens the editor pre-filled with `"<first>; <second>"`. `m` on the marked note unmarks it. |
+| `p` | Move the focused note to the other scope: project → global, or global → project. No confirmation; `p` again moves it back, and a move into an untrusted project is refused. |
+| `s` / `Tab` | Cycle the scope filter. |
+| `r` | Re-read the stores. |
+| `Esc` | Cancel the mark, the editor, or the screen, in that order. |
+
+A merge is one write: the store replaces the first note in place and drops the
+second, so a cancelled or failed merge leaves both notes as they were. Two notes
+in different scopes are refused — the stores are separate files.
+
+A move is two writes across those files, ordered target first: the note is added
+to the destination and only then removed from the source. If the second write
+fails the note is in both scopes — a duplicate `/memory doctor` reports and `m`
+merges — rather than gone. A note the destination already holds is not
+duplicated, and the move still removes it from the source.
+
 ## Behaviour by mode
 
 The tool and the context injection work in every mode (`tui`, `rpc`, `json`,
-`print`). The picker opened by a bare `/memory` requires `ctx.mode === "tui"`, and
-`/memory edit` and `/memory clear` require `ctx.hasUI`; in JSON and print sessions
-the command reports that the interactive form needs a TUI session. Memory itself is
-external state, so it is not reconstructed from the session tree and tree
-navigation does not change it.
+`print`), and `/memory doctor` reports through `notify` everywhere. The picker
+opened by a bare `/memory` requires `ctx.mode === "tui"`, and `/memory edit` and
+`/memory clear` require `ctx.hasUI`; in JSON and print sessions the command
+reports that the interactive form needs a TUI session. Memory itself is external
+state, so it is not reconstructed from the session tree and tree navigation does
+not change it.
 
 ## Configuration
 
@@ -152,10 +183,11 @@ skill. Mitigations:
 - The near-duplicate guard on `add` is deliberately conservative: it folds
   case, whitespace runs, and trailing sentence punctuation only, never word
   order, stemming, or internal punctuation. Two paraphrases can therefore still
-  both be stored; use `update` to consolidate them.
+  both be stored; `/memory doctor` reports the pairs the key does consider equal,
+  and `m` in the picker merges them under wording you write.
 - `update` replaces every exact match of `text`; a replacement that already
 exists under a different note can leave a duplicate. Forget the old note first
-when consolidating.
+when consolidating, or merge the pair in the picker afterward.
 - Only one note per line; multi-line notes are collapsed to a single line.
 
 ## Non-goals
@@ -180,6 +212,15 @@ when consolidating.
 
 ## Design notes
 
+- **Health reads the injection it describes.** `injectionPlan` is the same
+  cap arithmetic `buildInjection` joins into the context body, so the doctor
+  cannot claim notes fit while recall drops them; `buildInjection` is a join over
+  that plan, which is why the report needed no second budget model.
+- **A merge is one transform.** `applyMerge` replaces the first note and drops
+  the second inside the same read-modify-write the other mutations use, so a
+  cancelled or failed merge cannot leave one note gone and the other not. The
+  editor is pre-filled with both notes, but the wording saved is the user's — the
+  duplicate rule stays conservative and nothing is folded automatically.
 - **External storage, deliberately.** `goal`/`todo` keep state in tool-result
   `details` because it follows the active branch. Memory is the opposite: it must
   outlive the branch and be editable outside Pi, so it is plain files read at
@@ -207,11 +248,12 @@ when consolidating.
 | `types.ts` | `MemoryScope`, `MemoryAction`, `MemoryDetails`, the context type. |
 | `config.ts` | Defaults and the `memory` section of `bytefly.json` loading/clamping. |
 | `schema.ts` | TypeBox params/result and pure validation of action, scope, and text. |
-| `store.ts` | Paths, parse/read, file stamps, add/update/forget/clear transforms, atomic queued write. |
+| `store.ts` | Paths, parse/read, file stamps, add/update/forget/merge/clear transforms, atomic queued write. |
+| `doctor.ts` | The health report (pure): counts, file bytes, the injection plan's omissions, and near-duplicate pairs. |
 | `runtime.ts` | Session view of both stores, stamp-based refresh, trust gating, mutations. |
 | `format.ts` | Pure call/result/notice text and the bounded injection body. |
 | `errors.ts` | `messageOf`, the shared error-text extraction for the tool and command. |
-| `tui.ts` | The `/memory` picker component (note list, inline editor, scope filter), drawn from the `lib/tui/` kit (`titleRule`, `dockListFrame`, `listRow`, `emptyState`). |
+| `tui.ts` | The `/memory` picker component (note list, inline editor, merge mark, scope move, scope filter), drawn from the `lib/tui/` kit (`titleRule`, `dockListFrame`, `listRow`, `emptyState`). |
 | `tools.ts` | `registerTool("memory", …)`. |
 | `commands.ts` | `registerCommand("memory", …)`. |
 

package/extensions/memory/commands.ts

@@ -12,6 +12,7 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { withRailsSuppressed } from "../../lib/rails.ts";
 import { messageOf } from "./errors.ts";
+import { formatHealth, memoryHealth } from "./doctor.ts";
 import { formatNotice, scopeLabel } from "./format.ts";
 import type { MemoryRuntime } from "./runtime.ts";
 import { MemoryPickerComponent } from "./tui.ts";
@@ -30,10 +31,10 @@ function notify(ctx: ExtensionCommandContext, message: string, kind: "info" | "w
 }
 
 /** `/memory` subcommands and the scope argument accepted by `edit`/`clear`. */
-const MEMORY_SUBCOMMANDS = ["list", "path", "reload", "edit", "clear"];
+const MEMORY_SUBCOMMANDS = ["list", "path", "reload", "doctor", "edit", "clear"];
 
 /** Usage line shared by the command description and the unknown-subcommand warning. */
-const MEMORY_USAGE = "/memory [list | path | reload | edit [project|global] | clear [project|global]]";
+const MEMORY_USAGE = "/memory [list | path | reload | doctor | edit [project|global] | clear [project|global]]";
 
 /** Subcommand on the first token, scope on the second for `edit`/`clear`. */
 function completeMemoryArg(prefix: string): Array<{ value: string; label: string }> | null {
@@ -74,6 +75,8 @@ async function openPicker(pi: ExtensionAPI, runtime: MemoryRuntime, ctx: Extensi
 						add: (scope, text) => runtime.add(scope, text),
 						update: (scope, from, to) => runtime.update(scope, from, to),
 						forget: (scope, entry) => runtime.forget(scope, entry),
+						merge: (scope, first, second, merged) => runtime.merge(scope, first, second, merged),
+						move: (from, to, text) => runtime.move(from, to, text),
 					},
 					() => {
 						stopTimer();
@@ -140,6 +143,21 @@ export function registerCommands(pi: ExtensionAPI, runtime: MemoryRuntime): void
 					);
 					return;
 				}
+				case "doctor": {
+					// Read-only: the report names what to fix, and `m` in the picker merges a pair.
+					notify(
+						ctx,
+						formatHealth(
+							memoryHealth({
+								entries: runtime.entries(),
+								sizes: runtime.sizes(),
+								trusted: runtime.trusted(),
+								config: runtime.config(),
+							}),
+						),
+					);
+					return;
+				}
 				case "edit": {
 					if (!ctx.hasUI) {
 						notify(ctx, "Editing memory requires an interactive session.", "warning");

package/extensions/memory/doctor.ts

@@ -0,0 +1,137 @@
+/**
+ * Memory health: what the two stores hold, and whether recall is already
+ * dropping notes (pure).
+ *
+ * The report answers the questions a user cannot see from the notes alone: how
+ * many notes and bytes each store carries, how much of the `maxInjectBytes`
+ * budget the injection uses and which scope overflowed it, and which notes the
+ * conservative `duplicateKey` already considers the same fact. It never changes
+ * anything — consolidation is the picker's `m` merge, and the doctor only names
+ * the pair to merge.
+ *
+ * Byte counts are the store file's size on disk (what a user can reason about
+ * and compare with the cap), plus the injected body's size; both are exact UTF-8
+ * bytes, not a rounded display.
+ */
+
+import { clip } from "../../lib/tui/columns.ts";
+import type { MemoryConfig } from "./config.ts";
+import { injectionPlan, type MemoryEntries } from "./format.ts";
+import { duplicateKey } from "./store.ts";
+import { MEMORY_SCOPES, type MemoryScope } from "./types.ts";
+
+/** Longest note text a duplicate line shows. */
+const PAIR_NOTE_WIDTH = 60;
+/** Label column for the report's rows. */
+const LABEL_WIDTH = 11;
+
+/** One store's counts. */
+export interface ScopeHealth {
+	notes: number;
+	/** File size in bytes; `undefined` when the store was not read. */
+	bytes?: number;
+}
+
+/** Two notes the comparison key treats as one fact, in stored order. */
+export interface DuplicatePair {
+	scope: MemoryScope;
+	/** The note `add` would have kept. */
+	kept: string;
+	/** The note `add` would have refused as a near-duplicate. */
+	duplicate: string;
+}
+
+export interface MemoryHealth {
+	trusted: boolean;
+	inject: boolean;
+	/** The `maxInjectBytes` cap in effect. */
+	cap: number;
+	project: ScopeHealth;
+	global: ScopeHealth;
+	/** Present while injection is on: the body's bytes and what did not fit. */
+	injection?: { bytes: number; omitted: Record<MemoryScope, number> };
+	duplicates: DuplicatePair[];
+}
+
+export interface HealthInput {
+	entries: MemoryEntries;
+	sizes: Record<MemoryScope, number | undefined>;
+	trusted: boolean;
+	config: MemoryConfig;
+}
+
+/** Every near-duplicate pair, computed with the store's own comparison key. */
+export function duplicatePairs(entries: MemoryEntries): DuplicatePair[] {
+	const pairs: DuplicatePair[] = [];
+	for (const scope of MEMORY_SCOPES) {
+		const kept = new Map<string, string>();
+		for (const note of entries[scope]) {
+			const key = duplicateKey(note);
+			const first = kept.get(key);
+			if (first === undefined) kept.set(key, note);
+			else pairs.push({ scope, kept: first, duplicate: note });
+		}
+	}
+	return pairs;
+}
+
+/** Derive the report from the current stores and config. */
+export function memoryHealth({ entries, sizes, trusted, config }: HealthInput): MemoryHealth {
+	const scope = (name: MemoryScope): ScopeHealth => {
+		const size = sizes[name];
+		return size === undefined ? { notes: entries[name].length } : { notes: entries[name].length, bytes: size };
+	};
+	const plan = config.inject ? injectionPlan(entries, config.maxInjectBytes) : undefined;
+	return {
+		trusted,
+		inject: config.inject,
+		cap: config.maxInjectBytes,
+		project: scope("project"),
+		global: scope("global"),
+		...(plan ? { injection: { bytes: Buffer.byteLength(plan.lines.join("\n"), "utf-8"), omitted: plan.omitted } } : {}),
+		duplicates: duplicatePairs(entries),
+	};
+}
+
+function row(label: string, text: string): string {
+	return `  ${label.padEnd(LABEL_WIDTH)}${text}`;
+}
+
+/** `3 notes · 412 B`, or the reason a store was not read. */
+function scopeText(health: MemoryHealth, name: MemoryScope): string {
+	const scope = health[name];
+	if (name === "project" && !health.trusted) return "unavailable (untrusted project)";
+	const notes = `${scope.notes} note${scope.notes === 1 ? "" : "s"}`;
+	if (scope.bytes === undefined) return scope.notes === 0 ? notes : `${notes} · size unknown`;
+	return `${notes} · ${scope.bytes} B`;
+}
+
+function injectionText(health: MemoryHealth): string {
+	if (!health.inject) return "off (memory.inject is false)";
+	if (!health.injection) return "nothing to inject";
+	const { bytes, omitted } = health.injection;
+	const missing = omitted.project + omitted.global;
+	if (missing === 0) return `${bytes} B of ${health.cap} B · all notes fit`;
+	const scopes = MEMORY_SCOPES.filter((name) => omitted[name] > 0).map((name) => `${name} ${omitted[name]}`);
+	return `${bytes} B of ${health.cap} B · ${missing} omitted (${scopes.join(", ")})`;
+}
+
+function pairLine(pair: DuplicatePair): string {
+	const kept = clip(pair.kept, PAIR_NOTE_WIDTH);
+	const duplicate = clip(pair.duplicate, PAIR_NOTE_WIDTH);
+	return `    ${pair.scope}  "${kept}" ≈ "${duplicate}"`;
+}
+
+/** The `/memory doctor` notice: plain text, one row per fact. */
+export function formatHealth(health: MemoryHealth): string {
+	const count = health.duplicates.length;
+	const duplicates = count === 0 ? "none" : `${count} pair${count === 1 ? "" : "s"} (merge with m in /memory)`;
+	return [
+		"Memory health",
+		row("project", scopeText(health, "project")),
+		row("global", scopeText(health, "global")),
+		row("injection", injectionText(health)),
+		row("duplicates", duplicates),
+		...health.duplicates.map(pairLine),
+	].join("\n");
+}

package/extensions/memory/format.ts

@@ -104,13 +104,21 @@ export function formatNotice(entries: MemoryEntries): string {
 }
 
 /**
- * The hidden `[MEMORY]` context body, or `undefined` when nothing is stored.
+ * The hidden `[MEMORY]` context body split into its lines, plus what did not fit.
  *
  * Sections are emitted project-then-global. When the notes do not fit under
  * `maxBytes`, the remainder is replaced by one `(+N more)` tail so the model
- * knows to call the tool for the rest.
+ * knows to call the tool for the rest. `omitted` says which store overflowed, for
+ * the health report; `buildInjection` only needs the lines.
  */
-export function buildInjection(entries: MemoryEntries, maxBytes: number): string | undefined {
+export interface InjectionPlan {
+	lines: string[];
+	/** Notes that did not fit, per scope. */
+	omitted: Record<MemoryScope, number>;
+}
+
+/** Plan the injected body, or `undefined` when nothing is stored. */
+export function injectionPlan(entries: MemoryEntries, maxBytes: number): InjectionPlan | undefined {
 	const sections: Array<[MemoryScope, string[]]> = [];
 	if (entries.project.length > 0) sections.push(["project", entries.project]);
 	if (entries.global.length > 0) sections.push(["global", entries.global]);
@@ -119,7 +127,7 @@ export function buildInjection(entries: MemoryEntries, maxBytes: number): string
 	const lines = [MEMORY_CONTEXT_MARKER, INTRO];
 	let used = lines.reduce((total, line) => total + bytes(line) + 1, 0);
 	const limit = Math.max(0, maxBytes - TAIL_RESERVE);
-	let omitted = 0;
+	const omitted: Record<MemoryScope, number> = { project: 0, global: 0 };
 
 	for (const [scope, list] of sections) {
 		const header = `${scope}:`;
@@ -127,7 +135,7 @@ export function buildInjection(entries: MemoryEntries, maxBytes: number): string
 		for (const entry of list) {
 			const line = `- ${entry}`;
 			if (used + bytes(header) + 1 + bytes(line) + 1 > limit) {
-				omitted += 1;
+				omitted[scope] += 1;
 				continue;
 			}
 			rendered.push(line);
@@ -138,6 +146,15 @@ export function buildInjection(entries: MemoryEntries, maxBytes: number): string
 			used += bytes(header) + 1;
 		}
 	}
-	if (omitted > 0) lines.push(`- (+${omitted} more; use the memory tool)`);
-	return lines.join("\n");
+	const missing = omitted.project + omitted.global;
+	if (missing > 0) lines.push(`- (+${missing} more; use the memory tool)`);
+	return { lines, omitted };
+}
+
+/**
+ * The hidden `[MEMORY]` context body, or `undefined` when nothing is stored.
+ * Bounded by `maxBytes`, with one tail naming what did not fit.
+ */
+export function buildInjection(entries: MemoryEntries, maxBytes: number): string | undefined {
+	return injectionPlan(entries, maxBytes)?.lines.join("\n");
 }

package/extensions/memory/runtime.ts

@@ -15,6 +15,7 @@ import {
 	applyAdd,
 	applyClear,
 	applyForget,
+	applyMerge,
 	applyUpdate,
 	memoryFileStamp,
 	mutateMemoryFile,
@@ -40,6 +41,13 @@ interface AddResult {
 	existing?: string;
 }
 
+/** Outcome of a scope move: whether the source lost the note, and a target match. */
+export interface MoveResult {
+	moved: boolean;
+	/** The note the target store already had, when it matched as a near-duplicate. */
+	existing?: string;
+}
+
 export interface MemoryRuntime {
 	/** Resolve paths and load notes for a session; returns a warning message, if any. */
 	load(cwd: string, trusted: boolean): Promise<string | undefined>;
@@ -61,6 +69,16 @@ export interface MemoryRuntime {
 	update(scope: MemoryScope, from: string, to: string): Promise<boolean>;
 	forget(scope: MemoryScope, entry: string): Promise<boolean>;
 	clear(scope: MemoryScope): Promise<boolean>;
+	/** File size of each store in bytes; `undefined` when it was not read. */
+	sizes(): Record<MemoryScope, number | undefined>;
+	/** Merge two notes in `scope` into one, in a single write. */
+	merge(scope: MemoryScope, first: string, second: string, merged: string): Promise<boolean>;
+	/**
+	 * Move a note from one scope to the other: written to the target first, then
+	 * removed from the source, so a failure between the two leaves a duplicate
+	 * rather than losing the note.
+	 */
+	move(from: MemoryScope, to: MemoryScope, entry: string): Promise<MoveResult>;
 	/** Drop cached state on shutdown. */
 	reset(): void;
 }
@@ -150,6 +168,14 @@ export function createMemoryRuntime(pi: Pick<ExtensionAPI, "exec">): MemoryRunti
 		},
 		config: () => config,
 		paths: () => paths,
+		sizes: () => {
+			// A store we may not read reports no size, the same way `refresh` refuses
+			// to cache a stamp for it.
+			return {
+				project: trusted ? stampOf("project")?.size : undefined,
+				global: stampOf("global")?.size,
+			};
+		},
 		trusted: () => trusted,
 		entries: () => {
 			refresh();
@@ -188,6 +214,29 @@ export function createMemoryRuntime(pi: Pick<ExtensionAPI, "exec">): MemoryRunti
 			commit(scope, result.entries);
 			return result.changed;
 		},
+		async merge(scope, first, second, merged) {
+			requireTrusted(scope);
+			const result = await mutateMemoryFile(pathFor(scope), (content) => applyMerge(content, first, second, merged));
+			commit(scope, result.entries);
+			return result.changed;
+		},
+		async move(from, to, entry) {
+			if (from === to) throw new Error(`The note is already in ${scopeLabel(from)} memory.`);
+			// Refuse before any write: an untrusted target, or a note that is not in the
+			// source, must leave both stores exactly as they were.
+			requireTrusted(to);
+			// `entries()` refreshes both stores from disk first, so the check is against
+			// what is on disk now, not the cache a previous call left behind.
+			if (!this.entries()[from].includes(entry)) {
+				throw new Error(`No ${scopeLabel(from)} memory note matches "${entry}".`);
+			}
+			// Target first: the one failure possible across two files then leaves the note
+			// in both scopes, where `/memory doctor` reports it and `m` merges it, instead
+			// of deleting the only copy.
+			const added = await this.add(to, entry);
+			const moved = await this.forget(from, entry);
+			return added.existing === undefined ? { moved } : { moved, existing: added.existing };
+		},
 		reset: () => {
 			paths = undefined;
 			config = DEFAULT_MEMORY_CONFIG;