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

package/extensions/file-browse/client.ts

@@ -11,7 +11,7 @@
  * and `bun build --no-bundle` needs no separate asset.
  */
 
-import { THEME_TOGGLE_JS } from "../../lib/web/index.ts";
+import { SIDEBAR_COLLAPSE_MAX, THEME_TOGGLE_JS } from "../../lib/web/index.ts";
 
 export const CLIENT_JS = `(function () {
 	"use strict";
@@ -183,7 +183,7 @@ export const CLIENT_JS = `(function () {
 
 	var panel = document.querySelector("details.bf-app__sidebar");
 	if (panel && window.matchMedia) {
-		var mq = window.matchMedia("(max-width: 860px)");
+		var mq = window.matchMedia("(max-width: ${SIDEBAR_COLLAPSE_MAX}px)");
 		var syncSide = function () { panel.open = !mq.matches; };
 		syncSide();
 		if (mq.addEventListener) mq.addEventListener("change", syncSide);
@@ -289,11 +289,11 @@ export const CLIENT_JS = `(function () {
 		});
 	}
 
-	function flash(button, label) {
+	function flash(button, label, message) {
 		var original = button.textContent;
 		button.textContent = label;
 		var status = document.getElementById("copy-status");
-		if (status) status.textContent = label === "copied" ? "Copied to clipboard" : "Copy failed";
+		if (status) status.textContent = message;
 		window.setTimeout(function () { button.textContent = original; }, 1200);
 	}
 
@@ -310,8 +310,8 @@ export const CLIENT_JS = `(function () {
 			}
 			source
 				.then(function (text) { return copyText(text); })
-				.then(function () { flash(button, "copied"); })
-				.catch(function () { flash(button, "failed"); });
+				.then(function () { flash(button, "copied", "Copied to clipboard"); })
+				.catch(function () { flash(button, "failed", "Copy failed"); });
 		});
 	});
 
@@ -483,7 +483,6 @@ export const CLIENT_JS = `(function () {
 			option.id = "palette-option-" + index;
 			option.setAttribute("role", "option");
 			option.setAttribute("data-index", String(index));
-			option.setAttribute("aria-selected", index === 0 ? "true" : "false");
 			appendHighlighted(option, result.path, result.positions);
 			paletteList.appendChild(option);
 		});

package/extensions/file-browse/files.ts

@@ -46,7 +46,6 @@ const TEXT_EXTS = new Set([
 	".ini",
 	".cfg",
 	".conf",
-	".env",
 	".xml",
 	".csv",
 	".tsv",
@@ -89,9 +88,6 @@ const TEXT_EXTS = new Set([
 	".vue",
 	".svelte",
 	".astro",
-	".gitignore",
-	".gitattributes",
-	".editorconfig",
 ]);
 const TEXT_NAMES = new Set([
 	"license",

package/extensions/file-browse/git.ts

@@ -137,8 +137,8 @@ interface RepoState {
 const INSERTIONS = /(\d+) insertions?\(\+\)/;
 const DELETIONS = /(\d+) deletions?\(-\)/;
 
-/** A count from a `--shortstat` line, or `0` when the line does not carry it. */
-function shortstatCount(text: string, pattern: RegExp): number {
+/** A count from a diffstat summary line, or `0` when the line does not carry it. */
+function summaryCount(text: string, pattern: RegExp): number {
 	const match = pattern.exec(text);
 	return match ? Number(match[1]) : 0;
 }
@@ -218,17 +218,16 @@ export function createGitDiff(
 			const current = await state();
 			if (!current) return undefined;
 			const args = diffArgs(effectiveMode(mode, current.hasCommits));
-			const [stat, shortstat] = await Promise.all([
-				run(["diff", "--no-color", "--stat", ...args, "--"], { cwd: root }),
-				run(["diff", "--no-color", "--shortstat", ...args, "--"], { cwd: root }),
-			]);
-			const summary = shortstat.code === 0 ? shortstat.stdout : "";
+			const stat = await run(["diff", "--no-color", "--stat", ...args, "--"], { cwd: root });
+			const output = stat.code === 0 ? stat.stdout : "";
+			const trimmed = output.trimEnd();
+			const summary = trimmed.slice(trimmed.lastIndexOf("\n") + 1);
 			return {
 				mode,
 				files: current.files.filter((file) => inMode(file, mode)),
-				stat: stat.code === 0 ? stat.stdout.trim() : "",
-				insertions: shortstatCount(summary, INSERTIONS),
-				deletions: shortstatCount(summary, DELETIONS),
+				stat: output.trim(),
+				insertions: summaryCount(summary, INSERTIONS),
+				deletions: summaryCount(summary, DELETIONS),
 			};
 		},
 		async file(rel, mode) {

package/extensions/file-browse/html.ts

@@ -12,6 +12,7 @@ import { GLYPHS } from "../../lib/tui/glyphs.ts";
 import {
 	brandLockup,
 	docHead,
+	SIDEBAR_COLLAPSE_MAX,
 	WEB_BASE_CSS,
 	WEB_COMPONENTS_CSS,
 	WEB_LAYOUT_CSS,
@@ -61,7 +62,7 @@ export interface ChangeSummary {
 }
 
 /** Whether a path carries a change marker: a changed file, or a directory above one. */
-export function isChanged(summary: ChangeSummary | undefined, rel: string, isDir: boolean): boolean {
+function isChanged(summary: ChangeSummary | undefined, rel: string, isDir: boolean): boolean {
 	if (!summary || !rel) return false;
 	return isDir ? summary.dirs.has(rel) : summary.files.has(rel);
 }
@@ -169,6 +170,16 @@ body.palette-open{overflow:hidden}
 .browse-keys dt{white-space:nowrap}
 .browse-keys dd{margin:0;color:var(--muted);font-size:var(--fs-sm)}
 .browse-kbd{display:inline-block;min-width:20px;padding:1px 6px;border:1px solid var(--border);border-bottom-width:2px;border-radius:var(--radius-sm);background:var(--surface);color:var(--text);font:var(--fs-xs) var(--font-mono);text-align:center}
+/* Wide screens: pin quick open and the filter, and scroll the tree on its own
+   box. The sidebar is a details element, whose content sits in an anonymous
+   wrapper with no definite height, so the panel fills the sidebar by absolute
+   positioning; below the sidebar breakpoint the disclosure keeps normal page
+   scroll. */
+@media not (max-width:${SIDEBAR_COLLAPSE_MAX}px){
+.browse-sidebar{position:relative;overflow:hidden}
+.browse-side{position:absolute;inset:0;display:flex;flex-direction:column;overflow:hidden}
+.browse-side .bf-tree{flex:1 1 auto;min-height:0;overflow:auto}
+}
 @media (max-width:820px){
 .browse-root{order:9;flex:1 1 100%;direction:ltr;text-align:left}
 }
@@ -238,7 +249,7 @@ ${SPRITE}
   <button type="button" class="bf-btn bf-btn--icon bf-theme-toggle" id="theme-toggle" aria-label="Toggle light and dark theme" title="Toggle light and dark theme"><span class="theme-glyph" aria-hidden="true">☾</span></button>
 </div><div class="browse-progress" aria-hidden="true"><span class="browse-progress__fill" id="progress-fill"></span></div></header>
 <div class="bf-app__body">
-  <details class="bf-app__sidebar" open>
+  <details class="bf-app__sidebar browse-sidebar" open>
     <summary class="bf-panel__summary">Files</summary>
     <aside class="bf-panel browse-side">
       <button type="button" class="browse-quick-open" id="quick-open" aria-haspopup="dialog"><span>quick open</span><kbd>/</kbd></button>
@@ -252,7 +263,7 @@ ${SPRITE}
 ${layout.main}
   </main>
 </div>
-<footer class="bf-app__footer">served from ${escapeHtml(layout.rootLabel)} · read-only · ${layout.footerNote}</footer>
+<footer class="bf-app__footer">served from ${escapeHtml(layout.rootLabel)} · read-only · ${escapeHtml(layout.footerNote)}</footer>
 ${layout.keys && layout.keys.length > 0 ? renderKeysSheet(layout.keys) : ""}
 <script src="/app.js" defer></script>
 </body>
@@ -283,7 +294,7 @@ function renderTreeNode(node: TreeNode, currentRel: string, summary?: ChangeSumm
 	const expanded = node.children.length > 0;
 	const isDir = node.isDir;
 	const spec = isDir ? FOLDER_ICON : languageOf(node.name);
-	const href = isDir ? (node.rel ? `/browse/${encodePath(node.rel)}` : "/browse/") : `/view/${encodePath(node.rel)}`;
+	const href = hrefFor(node);
 	const current = node.rel === currentRel ? ` aria-current="page"` : "";
 	const twisty = isDir
 		? `<button type="button" class="bf-tree__tw bf-tree__tw--toggle" aria-expanded="${expanded}" aria-label="${escapeHtml(node.name)}">${expanded ? "▾" : "▸"}</button>`
@@ -495,7 +506,7 @@ export function renderFilePage(page: FilePage): string {
 		mainClass: rendered ? "browse-page browse-measure" : "browse-page",
 		keys,
 		main: `    <div class="bf-card">${head}${content}</div>\n    ${note}`,
-		footerNote: escapeHtml(page.rel),
+		footerNote: page.rel,
 		git: page.git,
 		summary: page.summary,
 	});
@@ -715,7 +726,7 @@ export function renderFileDiffPage(page: FileDiffPage): string {
 		mainClass: "browse-page",
 		keys,
 		main: `    <div class="bf-card">${head}${content}</div>\n    ${note}`,
-		footerNote: `diff · ${escapeHtml(modeScope(page.mode))}`,
+		footerNote: `diff · ${modeScope(page.mode)}`,
 		git: page.git,
 		summary: page.summary,
 	});
@@ -726,7 +737,6 @@ export interface ErrorPage {
 	status: number;
 	message: string;
 	tree: TreeNode;
-	rel: string;
 	git?: GitStatus;
 }
 

package/extensions/file-browse/router.ts

@@ -7,6 +7,7 @@
  * tested without a socket.
  */
 
+import type { Stats } from "node:fs";
 import { stat } from "node:fs/promises";
 import { THEME_JS } from "../../lib/web/index.ts";
 import { CLIENT_JS } from "./client.ts";
@@ -87,8 +88,8 @@ function jsonResponse(status: number, value: unknown): ServeResponse {
 	};
 }
 
-async function treeFor(ctx: ServeContext, _currentRel: string): Promise<TreeNode> {
-	return buildTree(ctx.root, _currentRel, ctx.config.maxDirEntries);
+async function treeFor(ctx: ServeContext, currentRel: string): Promise<TreeNode> {
+	return buildTree(ctx.root, currentRel, ctx.config.maxDirEntries);
 }
 
 /** Resolve the header's git context, never failing the request. */
@@ -153,18 +154,30 @@ async function errorResponse(
 		status,
 		message,
 		tree,
-		rel: "",
 		git: await gitFor(ctx),
 	});
 	return { status, headers: { ...HTML_SECURITY, ...extra }, body };
 }
 
-async function browse(ctx: ServeContext, rawRel: string): Promise<ServeResponse> {
+/** Resolve a request path once and render the directory or file page it names. */
+async function renderPath(ctx: ServeContext, rawRel: string, raw: boolean): Promise<ServeResponse> {
 	const abs = await resolveRequestPath(ctx.root, rawRel);
 	const rel = relativePath(ctx.root, abs);
-	const info = await stat(abs).catch(() => undefined);
-	if (!info || !info.isDirectory()) return view(ctx, rawRel, false);
+	const info: Stats | undefined = await stat(abs).catch(() => undefined);
+	if (info?.isDirectory()) return directoryResponse(ctx, rel);
+	if (!info) throw new HttpError(404, "That path does not exist.");
+	return fileResponse(ctx, rel, raw);
+}
 
+async function browse(ctx: ServeContext, rawRel: string): Promise<ServeResponse> {
+	return renderPath(ctx, rawRel, false);
+}
+
+async function view(ctx: ServeContext, rawRel: string, raw: boolean): Promise<ServeResponse> {
+	return renderPath(ctx, rawRel, raw);
+}
+
+async function directoryResponse(ctx: ServeContext, rel: string): Promise<ServeResponse> {
 	const listing = await listDirectory(ctx.root, rel, ctx.config.maxDirEntries);
 	const tree = await treeFor(ctx, rel);
 	const git = await gitFor(ctx);
@@ -184,13 +197,7 @@ async function browse(ctx: ServeContext, rawRel: string): Promise<ServeResponse>
 	);
 }
 
-async function view(ctx: ServeContext, rawRel: string, raw: boolean): Promise<ServeResponse> {
-	const abs = await resolveRequestPath(ctx.root, rawRel);
-	const rel = relativePath(ctx.root, abs);
-	const info = await stat(abs).catch(() => undefined);
-	if (info?.isDirectory()) return browse(ctx, rawRel);
-	if (!info) throw new HttpError(404, "That path does not exist.");
-
+async function fileResponse(ctx: ServeContext, rel: string, raw: boolean): Promise<ServeResponse> {
 	const file = await readFileView(ctx.root, rel, ctx.config.maxFileBytes, ctx.config.maxTextLines, ctx.config.markdown);
 	const tree = await treeFor(ctx, rel);
 	const git = await gitFor(ctx);
@@ -375,7 +382,9 @@ export async function handleRequest(
 		if (pathname.startsWith("/raw/")) return await raw(ctx, pathname.slice("/raw/".length));
 		return errorResponse(ctx, 404, "That page does not exist.");
 	} catch (error) {
-		if (error instanceof HttpError) return errorResponse(ctx, error.status, error.message);
-		return errorResponse(ctx, 500, "Something went wrong reading that path.");
+		const status = error instanceof HttpError ? error.status : 500;
+		const message = error instanceof HttpError ? error.message : "Something went wrong reading that path.";
+		if (pathname.startsWith("/api/")) return jsonResponse(status, { error: message });
+		return errorResponse(ctx, status, message);
 	}
 }

package/extensions/goal/README.md

@@ -93,6 +93,10 @@ the branch, so the note appears whether the todos were written by the model, by
 
 `goal` is allowlisted in `plan-mode` (alongside `todo`), so the model can record
 or update the objective during read-only exploration without leaving plan mode.
+Plan mode also reads the goal: it restates an active one in its injected context,
+and when a plan is approved with no goal at all it offers to record the plan's
+title as the goal (`lib/goal-state.ts` is the reader). An existing goal — active
+or achieved — is never replaced by that offer.
 
 ### `/goal` command
 
@@ -232,7 +236,9 @@ depends on config.
   todo list still holds open items appends one line to the model-facing result
   naming the count. The list is replayed from the branch by
   `lib/todo-state.ts` (shared with plan's approval-time merge, which reads the
-  same channel), never by importing the `todo` extension. Only the text is
+  same channel), never by importing the `todo` extension. The same reasoning
+  applies to the goal itself: `lib/goal-state.ts` owns the entry type and the
+  objective limit, and plan reads the published goal through it. Only the text is
   affected: `details` and `structuredContent` stay the goal alone, and the
   transcript result is still the status header.
 - **One verb table.** `GOAL_VERBS` is the only list of reserved words: the

package/extensions/goal/schema.ts

@@ -9,10 +9,14 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type, type Static } from "typebox";
 import { sanitizeLine } from "../../lib/format.ts";
+import { MAX_GOAL_OBJECTIVE } from "../../lib/goal-state.ts";
 import { GOAL_ACTIONS, GOAL_STATUSES, type Goal, type GoalStatus } from "./types.ts";
 
-/** Maximum length of the objective. */
-export const MAX_OBJECTIVE = 2000;
+/**
+ * Maximum length of the objective. Owned by `lib/goal-state.ts`, so a reader of
+ * the published state applies the same limit as this validator.
+ */
+export const MAX_OBJECTIVE = MAX_GOAL_OBJECTIVE;
 
 const GoalStatusEnum = StringEnum(GOAL_STATUSES, {
 	description: 'Whether the goal is still being pursued. Defaults to "active".',

package/extensions/goal/types.ts

@@ -15,8 +15,12 @@ export const GOAL_ACTIONS = ["set", "achieve", "clear"] as const;
 
 export type GoalAction = (typeof GOAL_ACTIONS)[number];
 
-/** Custom-entry type used to persist a goal set outside the tool (the `/goal` command). */
-export const GOAL_ENTRY_TYPE = "goal";
+/**
+ * Custom-entry type used to persist a goal set outside the tool (the `/goal`
+ * command). Owned by `lib/goal-state.ts` because another extension's reader
+ * dispatches on it; re-exported here so goal's own modules keep one import.
+ */
+export { GOAL_ENTRY_TYPE } from "../../lib/goal-state.ts";
 
 /** How an achieved goal renders in the persistent widget. */
 export type AchievedStyle = "show" | "hide";

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/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");