@tekmidian/pai 0.35.1 → 0.36.0

package/dist/{pick-aWhenqjE.mjs → program-BnMNFb4O.mjs}

@@ -1,23 +1,24 @@
-import { n as openRegistry } from "./db-BtuN768f.mjs";
-import { _ as warn$1, a as fmtDate, c as ok$1, d as scaffoldProjectDirs, f as shortenPath, h as smartDecodeDir, i as err, l as renderTable, m as slugify, n as dim$1, o as header, p as slugFromPath, r as encodeDir, s as now, t as bold$1, u as resolvePath } from "./utils-BAxjW3j8.mjs";
-import { a as slugify$1, i as parseSessionFilename } from "./migrate-fLD6rAdO.mjs";
-import { n as ensurePaiMarker } from "./pai-marker-B20KqhA8.mjs";
-import { n as openFederation } from "./db-CYmBWcjh.mjs";
-import { i as indexProject, n as indexAll, t as embedChunks } from "./sync--BoxBBok.mjs";
-import { t as STOP_WORDS } from "./stop-words-BaMEGVeY.mjs";
-import { n as populateSlugs, r as searchMemory } from "./search-C32zQ0V0.mjs";
-import { n as formatDetection, r as formatDetectionJson, t as detectProject } from "./detect-Bf2z-oKB.mjs";
-import { _ as transcriptFiles, a as readBodyFile, c as loadScanConfig, d as saveScanConfig, f as upsertProject, g as scanTranscriptFolders, h as findMovedProjects, i as findNotesDir$1, m as claudeProjectsDir, n as applyContinue, o as extractAndStoreTriples, p as upsertSession, r as findLatestNote, s as cmdScan, t as appendCheckpointToNote, u as resolveHome } from "./checkpoint-block-D3rm4dAJ.mjs";
-import { a as schedulerLogPath, i as paiSocketPath, n as daemonLogPath, r as daemonPidPath } from "./runtime-paths-B0P1TvUr.mjs";
-import { t as PaiClient } from "./ipc-client-aVKVERjJ.mjs";
-import { a as expandHome, c as UNROUTED, i as ensureConfigDir, n as CONFIG_FILE$2, o as loadConfig, s as OWNER_LABEL_PREFIX, t as CONFIG_DIR } from "./config-BSkVcvfq.mjs";
-import { i as humanDuration, t as createStorageBackend } from "./factory-BGH0COXb.mjs";
-import { s as kgQuery } from "./kg-entity-r8duqhi9.mjs";
-import { _ as scanSessions, a as renderDedupedSessions, c as probeResume, d as callAiBroker, f as fetchLiveSessions, g as resolveSessionByNameOrId, h as fmtAge, i as normalizeName$2, l as restoreTopLevel, m as sendToSession, o as hasConversation, p as revealItermSession, r as buildDeduped, s as launchInDir, u as printExitDir } from "./main-resolver-CNSqU8wo.mjs";
+import { t as openRegistry } from "./db-Ca5qfsMC.mjs";
+import { _ as warn$1, a as fmtDate, c as ok$1, d as resolvePath, f as scaffoldProjectDirs, g as smartDecodeDir, h as slugify, i as err, m as slugFromPath, n as dim$1, o as header, p as shortenPath, r as encodeDir, s as now, t as bold$1, u as renderTable } from "./utils-9Err2RBW.mjs";
+import { a as slugify$1, i as parseSessionFilename } from "./migrate-Cjzeefn9.mjs";
+import { n as ensurePaiMarker } from "./pai-marker-CHtbJMwJ.mjs";
+import { t as openFederation } from "./db-a1ixZQjr.mjs";
+import { i as indexProject, n as indexAll, t as embedChunks } from "./sync-BWbe8JTg.mjs";
+import { t as STOP_WORDS } from "./stop-words-Hfu8u22w.mjs";
+import { a as searchMemory, i as populateSlugs } from "./search-Rpk1cSBC.mjs";
+import { n as formatDetection, r as formatDetectionJson, t as detectProject } from "./detect-CdaA48EI.mjs";
+import { _ as transcriptFiles, a as readBodyFile, c as loadScanConfig, d as saveScanConfig, f as upsertProject, g as scanTranscriptFolders, h as findMovedProjects, i as findNotesDir$1, m as claudeProjectsDir, n as applyContinue, o as extractAndStoreTriples, p as upsertSession, r as findLatestNote, s as cmdScan, t as appendCheckpointToNote, u as resolveHome } from "./checkpoint-block-DKYxCkBL.mjs";
+import { a as schedulerLogPath, i as paiSocketPath, n as daemonLogPath, r as daemonPidPath } from "./runtime-paths-rni52zHX.mjs";
+import { t as PaiClient } from "./ipc-client-BmypMNYk.mjs";
+import { a as expandHome, c as UNROUTED, i as ensureConfigDir, n as CONFIG_FILE$2, o as loadConfig, s as OWNER_LABEL_PREFIX, t as CONFIG_DIR } from "./config-B64vFg14.mjs";
+import { r as humanDuration, t as createStorageBackend } from "./factory-Bsp7xOpO.mjs";
+import { s as kgQuery } from "./kg-entity-DbOMPdF9.mjs";
+import { _ as scanSessions, a as renderDedupedSessions, c as probeResume, d as callAiBroker, f as fetchLiveSessions, g as resolveSessionByNameOrId, h as fmtAge, i as normalizeName$2, l as restoreTopLevel, m as sendToSession, o as hasConversation, p as revealItermSession, r as buildDeduped, s as launchInDir, t as cmdMain, u as printExitDir } from "./main-resolver-BAbhKpeX.mjs";
 import { appendFileSync, chmodSync, copyFileSync, createReadStream, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir, platform, tmpdir } from "node:os";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import chalk from "chalk";
+import { Command } from "commander";
 import { fileURLToPath } from "node:url";
 import { execFile, execFileSync, execSync, spawn, spawnSync } from "node:child_process";
 import { createInterface } from "node:readline";
@@ -214,10 +215,7 @@ function getProject$2(db, slug) {
 }
 function requireProject(db, slug) {
 	const project = getProject$2(db, slug);
-	if (!project) {
-		console.error(err(`Project not found: ${slug}`));
-		process.exit(1);
-	}
+	if (!project) throw new Error(`Project not found: ${slug}`);
 	return project;
 }
 /**
@@ -420,18 +418,21 @@ function cmdAdd(db, rawPath, opts) {
 	];
 	if (!validTypes.includes(type)) {
 		console.error(err(`Invalid type "${type}". Valid: ${validTypes.join(", ")}`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	const ephemeral = unregistrableReason(rootPath);
 	if (ephemeral) {
 		console.error(err(`Refusing to register ${shortenPath(rootPath, 60)}`));
 		console.error(dim$1(`  That is ${ephemeral}.`));
 		console.error(dim$1(`  A project needs a durable location — move it, then register.`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	if (db.prepare("SELECT id FROM projects WHERE slug = ? OR root_path = ?").get(slug, rootPath)) {
 		console.error(err(`Project already registered (slug: ${slug} or path: ${rootPath})`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	const dirName = basename(rootPath).toLowerCase();
 	const matches = db.prepare(`SELECT slug, root_path FROM projects WHERE status = 'active' AND slug != ?`).all(slug).filter((s) => basename(s.root_path).toLowerCase() === dirName || s.slug.replace(/-\d+$/, "") === slug.replace(/-\d+$/, ""));
@@ -600,7 +601,8 @@ function cmdAlias(db, slug, alias) {
 	requireProject(db, slug);
 	if (db.prepare("SELECT id FROM projects WHERE slug = ?").get(alias)) {
 		console.error(err(`"${alias}" is already a project slug — cannot use as alias.`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	const project = getProject$2(db, slug);
 	try {
@@ -608,7 +610,7 @@ function cmdAlias(db, slug, alias) {
 		console.log(ok$1(`Alias added: ${bold$1(alias)} → ${slug}`));
 	} catch {
 		console.error(err(`Alias "${alias}" is already registered.`));
-		process.exit(1);
+		process.exitCode = 1;
 	}
 }
 function cmdEdit(db, slug, opts) {
@@ -625,7 +627,8 @@ function cmdEdit(db, slug, opts) {
 	];
 	if (opts.type && !validTypes.includes(opts.type)) {
 		console.error(err(`Invalid type "${opts.type}". Valid: ${validTypes.join(", ")}`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	const ts = now();
 	if (opts.displayName) {
@@ -649,7 +652,6 @@ function cmdDetect(db, pathArg, opts) {
 			console.log(warn$1(`No registered project found for: ${cwd}`));
 			console.log(dim$1("  Run 'pai project add .' to register this directory."));
 		}
-		process.exit(0);
 		return;
 	}
 	if (opts.json) {
@@ -747,7 +749,8 @@ function cmdGo(db, query) {
 	const all = db.prepare("SELECT * FROM projects WHERE status = 'active' ORDER BY updated_at DESC").all();
 	if (!all.length) {
 		console.error(err("No active projects registered. Run: pai project add <path>"));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	const q = query.trim().toLowerCase();
 	const exact = getProject$2(db, query);
@@ -786,7 +789,8 @@ function cmdGo(db, query) {
 		});
 		console.error();
 		console.error(dim$1("  Use a more specific name or the exact slug."));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	const scored = all.map((p) => {
 		const distSlug = levenshtein(q, p.slug.toLowerCase());
@@ -805,14 +809,15 @@ function cmdGo(db, query) {
 		console.error();
 		console.error(dim$1("  Run: pai project list  (to see all projects)"));
 	}
-	process.exit(1);
+	process.exitCode = 1;
 }
 function cmdRebind(db, slug, newPath) {
 	const project = requireProject(db, slug);
 	const resolved = resolve(newPath.startsWith("~/") ? join(homedir(), newPath.slice(2)) : newPath);
 	if (!existsSync(resolved)) {
 		console.error(err(`Path does not exist: ${resolved}`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	let isDir = false;
 	try {
@@ -820,13 +825,15 @@ function cmdRebind(db, slug, newPath) {
 	} catch {}
 	if (!isDir) {
 		console.error(err(`Path is not a directory: ${resolved}`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	const newEncoded = encodeDir(resolved);
 	const conflict = db.prepare("SELECT slug FROM projects WHERE encoded_dir = ? AND id != ?").get(newEncoded, project.id);
 	if (conflict) {
 		console.error(err(`Path is already registered to project: ${bold$1(conflict.slug)}\n`) + dim$1(`  ${resolved}\n`) + dim$1(`  Archive or move that project first, or choose a different path.`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	const ts = now();
 	db.prepare("UPDATE projects SET root_path = ?, encoded_dir = ?, updated_at = ? WHERE id = ?").run(resolved, newEncoded, ts, project.id);
@@ -960,16 +967,19 @@ function cmdName(db, identifier, shortname, opts) {
 	const project = resolveIdentifier(db, identifier) ?? requireProject(db, identifier);
 	if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(shortname)) {
 		console.error(err(`Invalid name "${shortname}". Use letters, digits, hyphens, underscores. Must start with a letter.`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	if (db.prepare("SELECT id FROM projects WHERE slug = ? AND id != ?").get(shortname, project.id)) {
 		console.error(err(`"${shortname}" is already a project slug.`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	const conflictAlias = db.prepare("SELECT project_id FROM aliases WHERE alias = ?").get(shortname);
 	if (conflictAlias && conflictAlias.project_id !== project.id) {
 		console.error(err(`"${shortname}" is already used by another project.`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	if (!conflictAlias) db.prepare("INSERT INTO aliases (alias, project_id) VALUES (?, ?)").run(shortname, project.id);
 	if (opts.permission) {
@@ -983,7 +993,8 @@ function cmdUnname(db, shortname) {
 	const alias = db.prepare("SELECT project_id FROM aliases WHERE alias = ?").get(shortname);
 	if (!alias) {
 		console.error(err(`No named project found: "${shortname}"`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	db.prepare("DELETE FROM aliases WHERE alias = ?").run(shortname);
 	const remaining = db.prepare("SELECT COUNT(*) AS cnt FROM aliases WHERE project_id = ?").get(alias.project_id);
@@ -1147,7 +1158,8 @@ function cmdConfig(db, identifier, opts) {
 	if (!identifier) {
 		console.error(err("Specify a project: pai project config <name-or-slug>"));
 		console.error(dim$1("  Or use --defaults for global defaults, --options for available keys."));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	const project = resolveIdentifier(db, identifier) ?? requireProject(db, identifier);
 	let config = getSessionConfig(project);
@@ -1692,7 +1704,8 @@ function cmdMerge(db, fromSlug, intoSlug, opts = {}) {
 	} catch (e) {
 		if (e instanceof MergeError) {
 			console.error(err(`  ${e.message}`));
-			process.exit(1);
+			process.exitCode = 1;
+			return;
 		}
 		throw e;
 	}
@@ -1766,14 +1779,14 @@ function cmdHere(db, name, opts = {}) {
 		target = realpathSync(opts.cwd ?? process.cwd());
 	} catch {
 		console.error(err(`Cannot resolve the current directory.`));
-		process.exit(1);
+		process.exitCode = 1;
 		return;
 	}
 	const encoded = encodeDir(target);
 	const matches = findProjectsByName(db, name);
 	if (matches.length > 1) {
 		console.error(err(`"${name}" matches ${matches.length} projects — name one exactly:\n`) + matches.map((m) => dim$1(`  ${m.slug}  (${m.display_name})\n`)).join(""));
-		process.exit(1);
+		process.exitCode = 1;
 		return;
 	}
 	const owner = db.prepare("SELECT id, slug, display_name FROM projects WHERE encoded_dir = ?").get(encoded);
@@ -1781,7 +1794,7 @@ function cmdHere(db, name, opts = {}) {
 		const p = matches[0];
 		if (owner && owner.id !== p.id) {
 			console.error(err(`This directory is already registered to ${bold$1(owner.slug)}.\n`) + dim$1(`  ${target}\n`) + dim$1(`  Merge them: pai project merge ${owner.slug} ${p.slug} --execute`));
-			process.exit(1);
+			process.exitCode = 1;
 			return;
 		}
 		let sameAlready = false;
@@ -1809,7 +1822,7 @@ function cmdHere(db, name, opts = {}) {
 	}
 	if (owner) {
 		console.error(err(`This directory is already registered as ${bold$1(owner.slug)} (${owner.display_name}).\n`) + dim$1(`  Rename it instead: pai project edit ${owner.slug} --display-name "${name}"`));
-		process.exit(1);
+		process.exitCode = 1;
 		return;
 	}
 	const slug = slugFromName(name);
@@ -1834,7 +1847,8 @@ function cmdUnregister(db, slug, opts = {}) {
        FROM projects p WHERE p.slug = ?`).get(slug);
 	if (!row) {
 		console.error(err(`  No project with slug "${slug}".`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	console.log();
 	console.log(bold$1(`  Unregister ${row.slug}`));
@@ -1847,7 +1861,8 @@ function cmdUnregister(db, slug, opts = {}) {
 		console.log(dim$1(`      pai project merge ${row.slug} <into> --execute`));
 		console.log(dim$1(`  Or pass --force if the sessions are genuinely worthless.`));
 		console.log();
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	if (!opts.execute) {
 		console.log(dim$1("  Preview — nothing was changed. Re-run with --execute to unregister."));
@@ -1873,7 +1888,7 @@ function cmdUnregister(db, slug, opts = {}) {
 //#region src/cli/commands/project/projects-index.ts
 function registerProjectsCommands(projectsCmd, getDb) {
 	projectsCmd.command("list", { isDefault: true }).description("Show the unified deduped listing (same as `pai`).\nUse --all to include cold / zero-session / archived projects.").option("--all", "Show all entries including cold / zero-session / archived projects").option("-n, --n <count>", "Max rows to show", "20").action(async (opts) => {
-		const { cmdMain } = await import("./main-resolver-CNSqU8wo.mjs").then((n) => n.n);
+		const { cmdMain } = await import("./main-resolver-Dxh444GO.mjs");
 		await cmdMain(getDb(), void 0, void 0, opts);
 	});
 	projectsCmd.command("list-raw").description("Raw registry listing with slug, path, status, last_active columns").option("--all", "Include archived projects (default: active only)").option("--status <status>", "Filter by status: active | archived").option("--tag <tag>", "Filter by tag").option("--type <type>", "Filter by type").action((opts) => {
@@ -1884,7 +1899,7 @@ function registerProjectsCommands(projectsCmd, getDb) {
 		const project = resolveIdentifier(db, identifier);
 		if (!project) {
 			console.error(`Project not found: ${identifier}`);
-			process.exit(1);
+			process.exitCode = 1;
 			return;
 		}
 		if (existsSync(project.root_path)) {
@@ -1984,7 +1999,8 @@ const SESSION_REGISTRY_PATH = join(homedir(), ".claude", "session-registry.json"
 function cmdMigrate$1(db) {
 	if (!existsSync(SESSION_REGISTRY_PATH)) {
 		console.error(err(`session-registry.json not found: ${SESSION_REGISTRY_PATH}`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	let registry;
 	try {
@@ -1992,7 +2008,8 @@ function cmdMigrate$1(db) {
 		registry = JSON.parse(raw);
 	} catch (e) {
 		console.error(err(`Failed to parse session-registry.json: ${e}`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	const projects = registry.projects ?? [];
 	if (!projects.length) {
@@ -2326,7 +2343,8 @@ function cmdDedupe(db, opts) {
 		if (backup) console.log(ok$1(`Registry backed up to ${bold$1(backup)}`));
 		else {
 			console.error(err("Could not back up the registry — refusing to merge without one."));
-			process.exit(1);
+			process.exitCode = 1;
+			return;
 		}
 	}
 	const totals = {
@@ -2362,7 +2380,8 @@ function cmdDedupe(db, opts) {
 		run();
 	} catch (e) {
 		console.error(err(`Merge failed and was rolled back: ${String(e)}`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	console.log();
 	console.log(ok$1(`Merged ${totals.deletedRows} duplicate row(s).`));
@@ -2481,7 +2500,10 @@ function cmdRebuild(db) {
 function cmdLookup(db, fsPath) {
 	const resolved = resolve(fsPath);
 	const row = db.prepare("SELECT slug FROM projects WHERE root_path = ?").get(resolved);
-	if (!row) process.exit(1);
+	if (!row) {
+		process.exitCode = 1;
+		return;
+	}
 	process.stdout.write(row.slug + "\n");
 }
 function registerRegistryCommands(registryCmd, getDb) {
@@ -2502,7 +2524,8 @@ function registerRegistryCommands(registryCmd, getDb) {
 			const resolved = resolveHome(opts.addDir);
 			if (!existsSync(resolved)) {
 				console.error(err(`Directory not found: ${resolved}`));
-				process.exit(1);
+				process.exitCode = 1;
+				return;
 			}
 			const display = resolved.startsWith(homedir()) ? "~" + resolved.slice(homedir().length) : resolved;
 			if (config.scan_dirs.includes(display) || config.scan_dirs.includes(resolved)) console.log(warn$1(`Already configured: ${display}`));
@@ -2567,13 +2590,15 @@ function registerEmbedCommand(memoryCmd, getDb) {
 			federation = openFederation();
 		} catch (e) {
 			console.error(err(`Failed to open federation database: ${e}`));
-			process.exit(1);
+			process.exitCode = 1;
+			return;
 		}
 		if (projectSlug) {
 			const project = registryDb.prepare("SELECT id, slug FROM projects WHERE slug = ?").get(projectSlug);
 			if (!project) {
 				console.error(err(`Project not found: ${projectSlug}`));
-				process.exit(1);
+				process.exitCode = 1;
+				return;
 			}
 			await runEmbed(federation, project.id, project.slug, parseInt(opts.batchSize ?? "50", 10));
 		} else await runEmbed(federation, void 0, void 0, parseInt(opts.batchSize ?? "50", 10));
@@ -2598,13 +2623,15 @@ function registerIndexCommand(memoryCmd, getDb) {
 			federation = openFederation();
 		} catch (e) {
 			console.error(err(`Failed to open federation database: ${e}`));
-			process.exit(1);
+			process.exitCode = 1;
+			return;
 		}
 		if (projectSlug) {
 			const project = registryDb.prepare("SELECT id, slug, display_name, root_path FROM projects WHERE slug = ? AND status = 'active'").get(projectSlug);
 			if (!project) {
 				console.error(err(`Project not found or not active: ${projectSlug}`));
-				process.exit(1);
+				process.exitCode = 1;
+				return;
 			}
 			console.log(dim$1(`Indexing ${project.display_name} (${project.slug})...`));
 			const result = await indexProject(federation, project.id, project.root_path);
@@ -2638,7 +2665,8 @@ function registerSearchCommand(memoryCmd, getDb) {
 			federation = openFederation();
 		} catch (e) {
 			console.error(err(`Failed to open federation database: ${e}`));
-			process.exit(1);
+			process.exitCode = 1;
+			return;
 		}
 		const config = loadConfig();
 		const searchConfig = config.search;
@@ -2650,7 +2678,8 @@ function registerSearchCommand(memoryCmd, getDb) {
 			"hybrid"
 		].includes(mode)) {
 			console.error(err(`Invalid mode: ${mode}. Use keyword, semantic, or hybrid.`));
-			process.exit(1);
+			process.exitCode = 1;
+			return;
 		}
 		let projectIds;
 		if (opts.project) {
@@ -2669,7 +2698,7 @@ function registerSearchCommand(memoryCmd, getDb) {
 		else if (mode === "semantic" || mode === "hybrid") {
 			const backend = await createStorageBackend(config);
 			try {
-				const { generateEmbedding } = await import("./embeddings-Bn86ssxR.mjs").then((n) => n.i);
+				const { generateEmbedding } = await import("./embeddings-CEBGrzwu.mjs");
 				console.log(dim$1("Generating query embedding..."));
 				const queryEmbedding = await generateEmbedding(query, true);
 				if (mode === "semantic") results = await backend.searchSemantic(queryEmbedding, searchOpts);
@@ -2718,13 +2747,13 @@ function registerSearchCommand(memoryCmd, getDb) {
 			return;
 		}
 		if (opts.rerank !== false) {
-			const { rerankResults } = await import("./reranker-CMNZcfVx.mjs").then((n) => n.r);
+			const { rerankResults } = await import("./reranker-CwTCNsgA.mjs");
 			console.log(dim$1("Reranking with cross-encoder..."));
 			results = await rerankResults(query, results, { topK: maxResults });
 		}
 		const recencyDays = parseInt(opts.recency ?? String(searchConfig.recencyBoostDays), 10);
 		if (recencyDays > 0) {
-			const { applyRecencyBoost } = await import("./search-C32zQ0V0.mjs").then((n) => n.o);
+			const { applyRecencyBoost } = await import("./search-CfPpJAWQ.mjs");
 			console.log(dim$1(`Applying recency boost (half-life: ${recencyDays} days)...`));
 			results = applyRecencyBoost(results, recencyDays);
 		}
@@ -2764,7 +2793,8 @@ function registerStatsCommands(memoryCmd, getDb) {
 			federation = openFederation();
 		} catch (e) {
 			console.error(err(`Failed to open federation database: ${e}`));
-			process.exit(1);
+			process.exitCode = 1;
+			return;
 		}
 		try {
 			federation.pragma("busy_timeout = 4000");
@@ -2787,7 +2817,8 @@ function registerStatsCommands(memoryCmd, getDb) {
 			const project = registryDb.prepare("SELECT id, slug, display_name FROM projects WHERE slug = ?").get(projectSlug);
 			if (!project) {
 				console.error(err(`Project not found: ${projectSlug}`));
-				process.exit(1);
+				process.exitCode = 1;
+				return;
 			}
 			const fileStats = federation.prepare("SELECT COUNT(*) as files FROM memory_files WHERE project_id = ?").get(project.id);
 			const chunkStats = federation.prepare("SELECT COUNT(*) as chunks FROM memory_chunks WHERE project_id = ?").get(project.id);
@@ -2863,7 +2894,8 @@ function registerStatsCommands(memoryCmd, getDb) {
 			if (val === void 0) {
 				console.error(err(`Unknown setting: ${key}`));
 				console.log(dim$1(`  Valid keys: mode, rerank, recencyBoostDays, defaultLimit, snippetLength`));
-				process.exit(1);
+				process.exitCode = 1;
+				return;
 			}
 			console.log(String(val));
 			return;
@@ -2878,14 +2910,16 @@ function registerStatsCommands(memoryCmd, getDb) {
 		if (!validKeys.has(key)) {
 			console.error(err(`Unknown setting: ${key}`));
 			console.log(dim$1(`  Valid keys: ${[...validKeys].join(", ")}`));
-			process.exit(1);
+			process.exitCode = 1;
+			return;
 		}
 		let fileConfig = {};
 		if (existsSync(CONFIG_FILE$2)) try {
 			fileConfig = JSON.parse(readFileSync(CONFIG_FILE$2, "utf-8"));
 		} catch {
 			console.error(err(`Could not parse ${CONFIG_FILE$2}`));
-			process.exit(1);
+			process.exitCode = 1;
+			return;
 		}
 		if (!fileConfig.search || typeof fileConfig.search !== "object") fileConfig.search = {};
 		let parsed;
@@ -2896,7 +2930,8 @@ function registerStatsCommands(memoryCmd, getDb) {
 				"hybrid"
 			].includes(value)) {
 				console.error(err(`Invalid mode: ${value}. Must be keyword, semantic, or hybrid.`));
-				process.exit(1);
+				process.exitCode = 1;
+				return;
 			}
 			parsed = value;
 		} else if (key === "rerank") parsed = value === "true" || value === "1" || value === "on";
@@ -2904,7 +2939,8 @@ function registerStatsCommands(memoryCmd, getDb) {
 			parsed = parseInt(value, 10);
 			if (isNaN(parsed)) {
 				console.error(err(`Invalid number: ${value}`));
-				process.exit(1);
+				process.exitCode = 1;
+				return;
 			}
 		}
 		fileConfig.search[key] = parsed;
@@ -2915,7 +2951,7 @@ function registerStatsCommands(memoryCmd, getDb) {
 			console.log(dim$1(`  Restart daemon to apply: pai daemon restart`));
 		} catch (e) {
 			console.error(err(`Could not write config: ${e}`));
-			process.exit(1);
+			process.exitCode = 1;
 		}
 	});
 }
@@ -2924,9 +2960,9 @@ function registerStatsCommands(memoryCmd, getDb) {
 //#region src/cli/commands/memory/sources-cmd.ts
 function registerSourcesCommand(memoryCmd) {
 	memoryCmd.command("sources").description("Show what the indexer has taken in: composition by source, which roots\ncontent enters from, the heaviest single files, and how many chunks are\nrewritten per day (which distinguishes a finite backlog from a treadmill).").option("--limit <n>", "Rows per section (default 8)", "8").action(async (opts) => {
-		const { createStorageBackend } = await import("./factory-BGH0COXb.mjs").then((n) => n.n);
-		const { loadConfig } = await import("./config-BSkVcvfq.mjs").then((n) => n.r);
-		const { cmdMemorySources } = await import("./sources-BDwN0B8i.mjs");
+		const { createStorageBackend } = await import("./factory-CrokPMk2.mjs");
+		const { loadConfig } = await import("./config-C_ErGddD.mjs");
+		const { cmdMemorySources } = await import("./sources-D8ZdNfvK.mjs");
 		let backend;
 		try {
 			backend = await createStorageBackend(loadConfig());
@@ -3079,7 +3115,8 @@ function registerIdentityCommands(identityCmd) {
 		const normalized = normalizeEmail(email);
 		if (!normalized) {
 			console.error(err("pai identity: ") + `Not a usable email address: ${email}`);
-			process.exit(1);
+			process.exitCode = 1;
+			return;
 		}
 		const config = readConfig();
 		const id = identityOf(config);
@@ -3118,7 +3155,8 @@ function registerIdentityCommands(identityCmd) {
 		const normalized = normalizeEmail(email);
 		if (!normalized) {
 			console.error(err("pai identity: ") + `Not a usable email address: ${email}`);
-			process.exit(1);
+			process.exitCode = 1;
+			return;
 		}
 		const config = readConfig();
 		const id = identityOf(config);
@@ -3236,7 +3274,8 @@ function cmdInstall$1() {
 		writeClaudeJson(config);
 	} catch (e) {
 		console.error(err(`Failed to write ~/.claude.json: ${e}`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	console.log(ok$1("PAI MCP server registered in ~/.claude.json."));
 	console.log(dim$1(`  Binary: ${mcpBin}`));
@@ -3443,7 +3482,7 @@ async function cmdStatus$2() {
 		console.log(dim$1("    Start with: pai daemon serve"));
 		console.log(dim$1("    Or install as service: pai daemon install"));
 		console.log();
-		process.exit(1);
+		process.exitCode = 1;
 	}
 }
 function cmdRestart() {
@@ -3470,7 +3509,7 @@ function cmdRestart() {
 	} catch (e) {
 		const msg = e instanceof Error ? e.message : String(e);
 		console.error(err(`restart error: ${msg}`));
-		process.exit(1);
+		process.exitCode = 1;
 	}
 }
 function cmdInstall() {
@@ -3486,7 +3525,8 @@ function cmdInstall() {
 		console.log(ok$1(`  Wrote launchd plist: ${PLIST_PATH}`));
 	} catch (e) {
 		console.error(err(`  Failed to write plist: ${e}`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	try {
 		spawnSync("launchctl", ["unload", PLIST_PATH], { encoding: "utf8" });
@@ -3516,7 +3556,8 @@ function cmdInstall() {
 			console.log(ok$1("  Updated ~/.claude.json to use daemon shim."));
 		} catch (e) {
 			console.error(err(`  Failed to write ~/.claude.json: ${e}`));
-			process.exit(1);
+			process.exitCode = 1;
+			return;
 		}
 	}
 	console.log();
@@ -3585,7 +3626,7 @@ async function cmdMigrate(connectionString) {
 	});
 	if (result.status !== 0) {
 		console.error(err("  Migration failed. Check output above."));
-		process.exit(result.status ?? 1);
+		process.exitCode = result.status ?? 1;
 	}
 }
 function cmdLogs(opts) {
@@ -3603,13 +3644,13 @@ function cmdLogs(opts) {
 	} catch (e) {
 		const msg = e instanceof Error ? e.message : String(e);
 		console.error(err(`Could not read log: ${msg}`));
-		process.exit(1);
+		process.exitCode = 1;
 	}
 }
 function registerDaemonCommands(daemonCmd) {
 	daemonCmd.command("serve").description("Start the PAI daemon in the foreground").action(async () => {
-		const { serve } = await import("./daemon-Hnu6-HDD.mjs").then((n) => n.t);
-		const { loadConfig: lc, ensureConfigDir } = await import("./config-BSkVcvfq.mjs").then((n) => n.r);
+		const { serve } = await import("./daemon-DJEFqV84.mjs");
+		const { loadConfig: lc, ensureConfigDir } = await import("./config-C_ErGddD.mjs");
 		ensureConfigDir();
 		await serve(lc());
 	});
@@ -3824,14 +3865,16 @@ function registerRestoreCommands(program) {
 			resolvedDir = backupPath.startsWith("~") ? backupPath.replace(/^~/, HOME) : backupPath;
 			if (!existsSync(resolvedDir)) {
 				console.error(err(`Backup directory not found: ${resolvedDir}`));
-				process.exit(1);
+				process.exitCode = 1;
+				return;
 			}
 		} else {
 			const backups = listBackups();
 			if (backups.length === 0) {
 				console.error(err(`No backups found in ${BACKUPS_DIR}`));
 				console.log(dim$1("  Run 'pai backup' to create one."));
-				process.exit(1);
+				process.exitCode = 1;
+				return;
 			}
 			console.log(`\n${bold$1("Available backups")} (newest first):\n`);
 			backups.forEach((name, i) => {
@@ -3859,7 +3902,7 @@ function registerRestoreCommands(program) {
 		if (hasSql && opts.postgres) console.log(warn$1("  Postgres database will be dropped and recreated from the backup."));
 		if (!(opts.yes || await confirm("Proceed with restore?"))) {
 			console.log(dim$1("Restore cancelled."));
-			process.exit(0);
+			return;
 		}
 		console.log();
 		const results = [];
@@ -3968,7 +4011,8 @@ function registerRestoreCommands(program) {
 			console.log(`  ${dim$1("Restart:")} pai daemon restart\n`);
 		} else {
 			console.log(`\n  ${warn$1("Some items failed — check output above.")}\n`);
-			process.exit(1);
+			process.exitCode = 1;
+			return;
 		}
 	});
 }
@@ -4053,6 +4097,65 @@ function writeJsonAtomic(path, data, opts = {}) {
 	}
 }
 
+//#endregion
+//#region src/cli/lib/exit.ts
+/**
+* Safe process termination for the CLI.
+*
+* Node's stdout/stderr are ASYNCHRONOUS when they point at a pipe (and
+* synchronous when they point at a TTY or a regular file). `process.exit()`
+* tears the process down immediately, before any still-in-flight async
+* write completes — so a command whose output is piped (`pai ... | less`,
+* `| wc -c`, a subshell capture, etc.) can have its output silently
+* truncated or dropped entirely, while the same command run against a TTY
+* or redirected to a file prints correctly. Exit code is still 0, so the
+* failure is invisible.
+*
+* The robust fix, used everywhere it is possible, is to never call
+* `process.exit()` at all: set `process.exitCode` and let the command
+* return normally. Once the event loop has nothing left to do, Node exits
+* on its own — and a natural exit always flushes pending writes first.
+*
+* `exitAfterFlush` exists for the rare call site where control flow
+* genuinely cannot return (e.g. deep inside a callback with no path back
+* to the caller). It waits for both stdout and stderr to drain before
+* calling `process.exit()`.
+*/
+function streamDrained(stream) {
+	if (!stream.writableLength) return Promise.resolve();
+	return new Promise((resolve) => {
+		stream.once("drain", () => resolve());
+		const check = () => {
+			if (!stream.writableLength) resolve();
+		};
+		setImmediate(check);
+	});
+}
+/**
+* Wait for stdout and stderr to finish flushing, then exit with `code`.
+* Never returns (the return type documents that; callers should not
+* expect code after this call to run).
+*/
+async function exitAfterFlush(code) {
+	await drainStdio();
+	process.exit(code);
+}
+/**
+* Wait for stdout and stderr to finish flushing, without exiting.
+*
+* Belt-and-suspenders backstop for cli/index.ts: every command path avoids
+* process.exit() so a natural process exit — which always flushes pending
+* writes — can do the flushing. This makes that explicit and awaited at the
+* one place every command path funnels through, instead of trusting that
+* nothing between here and process shutdown (a dependency's keep-alive
+* socket being unref'd, a timer, anything else that can make the event loop
+* look "empty") lets Node begin tearing down before a write that's still
+* asynchronously in flight to a pipe has actually reached the OS.
+*/
+async function drainStdio() {
+	await Promise.all([streamDrained(process.stdout), streamDrained(process.stderr)]);
+}
+
 //#endregion
 //#region src/cli/commands/setup/utils.ts
 /**
@@ -4088,7 +4191,7 @@ function createRl() {
 		line$1();
 		line$1(c.dim("  Setup cancelled. Run `pai setup` again to restart."));
 		line$1();
-		process.exit(0);
+		exitAfterFlush(0);
 	});
 	return rl;
 }
@@ -6948,7 +7051,8 @@ function cmdOpen(opts) {
 	if (!existsSync(vaultPath)) {
 		console.error(err(`Vault not found at: ${vaultPath}`));
 		console.error(dim$1("  Run: pai obsidian sync"));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	const url = `obsidian://open?vault=${encodeURIComponent(vaultName)}`;
 	console.log(dim$1(`  Opening: ${url}`));
@@ -6958,7 +7062,8 @@ function cmdOpen(opts) {
 	} catch (e) {
 		console.error(err(`  Failed to open Obsidian: ${e}`));
 		console.error(dim$1("  Ensure Obsidian is installed and the vault is registered in Obsidian."));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 }
 function registerObsidianCommands(obsidianCmd, getDb) {
@@ -6997,7 +7102,7 @@ async function cmdExplore(note, opts) {
 	const depth = parseInt(opts.depth ?? "3", 10);
 	const direction = opts.direction ?? "both";
 	const mode = opts.mode ?? "all";
-	const { zettelExplore } = await import("./zettelkasten-W-h8G2is.mjs");
+	const { zettelExplore } = await import("./zettelkasten-CvjmMghT.mjs");
 	const result = zettelExplore(getFedDb(), {
 		startNote: note,
 		depth,
@@ -7049,7 +7154,8 @@ function registerExploreCommand(parent) {
 			await cmdExplore(note, opts);
 		} catch (e) {
 			console.error(err(`  Error: ${e}`));
-			process.exit(1);
+			process.exitCode = 1;
+			return;
 		}
 	});
 }
@@ -7061,7 +7167,7 @@ async function cmdHealth(opts) {
 	const projectPath = opts.project;
 	const recentDays = parseInt(opts.days ?? "30", 10);
 	const includeTypes = opts.include ? opts.include.split(",").map((s) => s.trim()) : void 0;
-	const { zettelHealth } = await import("./zettelkasten-W-h8G2is.mjs");
+	const { zettelHealth } = await import("./zettelkasten-CvjmMghT.mjs");
 	const result = zettelHealth(getFedDb(), {
 		scope,
 		projectPath,
@@ -7114,7 +7220,8 @@ function registerHealthCommand(parent) {
 			await cmdHealth(opts);
 		} catch (e) {
 			console.error(err(`  Error: ${e}`));
-			process.exit(1);
+			process.exitCode = 1;
+			return;
 		}
 	});
 }
@@ -7124,13 +7231,14 @@ function registerHealthCommand(parent) {
 async function cmdSurprise(note, opts) {
 	if (!opts.vaultProjectId) {
 		console.error(err("  --vault-project-id is required"));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	const vaultProjectId = parseInt(opts.vaultProjectId, 10);
 	const limit = parseInt(opts.limit ?? "10", 10);
 	const minSimilarity = parseFloat(opts.minSimilarity ?? "0.3");
 	const minGraphDistance = parseInt(opts.minDistance ?? "3", 10);
-	const { zettelSurprise } = await import("./zettelkasten-W-h8G2is.mjs");
+	const { zettelSurprise } = await import("./zettelkasten-CvjmMghT.mjs");
 	const db = getFedDb();
 	console.log();
 	console.log(header("  PAI Zettel Surprise"));
@@ -7168,7 +7276,8 @@ function registerSurpriseCommand(parent) {
 			await cmdSurprise(note, opts);
 		} catch (e) {
 			console.error(err(`  Error: ${e}`));
-			process.exit(1);
+			process.exitCode = 1;
+			return;
 		}
 	});
 }
@@ -7178,12 +7287,13 @@ function registerSurpriseCommand(parent) {
 async function cmdSuggest(note, opts) {
 	if (!opts.vaultProjectId) {
 		console.error(err("  --vault-project-id is required"));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	const vaultProjectId = parseInt(opts.vaultProjectId, 10);
 	const limit = parseInt(opts.limit ?? "5", 10);
 	const excludeLinked = opts.excludeLinked !== false;
-	const { zettelSuggest } = await import("./zettelkasten-W-h8G2is.mjs");
+	const { zettelSuggest } = await import("./zettelkasten-CvjmMghT.mjs");
 	const db = getFedDb();
 	console.log();
 	console.log(header("  PAI Zettel Suggest"));
@@ -7219,7 +7329,8 @@ function registerSuggestCommand(parent) {
 			await cmdSuggest(note, opts);
 		} catch (e) {
 			console.error(err(`  Error: ${e}`));
-			process.exit(1);
+			process.exitCode = 1;
+			return;
 		}
 	});
 }
@@ -7229,12 +7340,13 @@ function registerSuggestCommand(parent) {
 async function cmdConverse(question, opts) {
 	if (!opts.vaultProjectId) {
 		console.error(err("  --vault-project-id is required"));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	const vaultProjectId = parseInt(opts.vaultProjectId, 10);
 	const depth = parseInt(opts.depth ?? "2", 10);
 	const limit = parseInt(opts.limit ?? "15", 10);
-	const { zettelConverse } = await import("./zettelkasten-W-h8G2is.mjs");
+	const { zettelConverse } = await import("./zettelkasten-CvjmMghT.mjs");
 	const db = getFedDb();
 	console.log();
 	console.log(header("  PAI Zettel Converse"));
@@ -7278,7 +7390,8 @@ function registerConverseCommand(parent) {
 			await cmdConverse(question, opts);
 		} catch (e) {
 			console.error(err(`  Error: ${e}`));
-			process.exit(1);
+			process.exitCode = 1;
+			return;
 		}
 	});
 }
@@ -7288,14 +7401,15 @@ function registerConverseCommand(parent) {
 async function cmdThemes(opts) {
 	if (!opts.vaultProjectId) {
 		console.error(err("  --vault-project-id is required"));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	const vaultProjectId = parseInt(opts.vaultProjectId, 10);
 	const lookbackDays = parseInt(opts.days ?? "30", 10);
 	const minClusterSize = parseInt(opts.minSize ?? "3", 10);
 	const maxThemes = parseInt(opts.maxThemes ?? "10", 10);
 	const similarityThreshold = parseFloat(opts.threshold ?? "0.65");
-	const { zettelThemes } = await import("./zettelkasten-W-h8G2is.mjs");
+	const { zettelThemes } = await import("./zettelkasten-CvjmMghT.mjs");
 	const db = getFedDb();
 	console.log();
 	console.log(header("  PAI Zettel Themes"));
@@ -7339,7 +7453,8 @@ function registerThemesCommand(parent) {
 			await cmdThemes(opts);
 		} catch (e) {
 			console.error(err(`  Error: ${e}`));
-			process.exit(1);
+			process.exitCode = 1;
+			return;
 		}
 	});
 }
@@ -7436,7 +7551,8 @@ async function cmdList$2(opts) {
 	} catch (e) {
 		console.error(err(`  Failed to reach PAI daemon: ${e}`));
 		console.error(dim$1("  Is the daemon running? Try: pai daemon status"));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	console.log();
 	console.log(header("  PAI Observations"));
@@ -7489,7 +7605,8 @@ async function cmdSearch(query, opts) {
 	} catch (e) {
 		console.error(err(`  Failed to reach PAI daemon: ${e}`));
 		console.error(dim$1("  Is the daemon running? Try: pai daemon status"));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	const q = query.toLowerCase();
 	const observations = allObservations.filter((o) => (o.title ?? "").toLowerCase().includes(q) || (o.narrative ?? "").toLowerCase().includes(q) || (o.tool_input_summary ?? "").toLowerCase().includes(q)).slice(0, limit);
@@ -7528,7 +7645,8 @@ async function cmdStats$1() {
 	} catch (e) {
 		console.error(err(`  Failed to reach PAI daemon: ${e}`));
 		console.error(dim$1("  Is the daemon running? Try: pai daemon status"));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	console.log();
 	console.log(header("  PAI Observation Statistics"));
@@ -7573,7 +7691,8 @@ function registerObservationCommands(parent) {
 			await cmdList$2(opts);
 		} catch (e) {
 			console.error(err(`  Error: ${e}`));
-			process.exit(1);
+			process.exitCode = 1;
+			return;
 		}
 	});
 	parent.command("search <query>").description("Search observations by title or narrative text").option("--project <slug>", "Filter by project slug").option("--type <type>", "Filter by type").option("--limit <n>", "Maximum results", "20").action(async (query, opts) => {
@@ -7581,7 +7700,8 @@ function registerObservationCommands(parent) {
 			await cmdSearch(query, opts);
 		} catch (e) {
 			console.error(err(`  Error: ${e}`));
-			process.exit(1);
+			process.exitCode = 1;
+			return;
 		}
 	});
 	parent.command("stats").description("Show observation statistics: totals, by type, by project").action(async () => {
@@ -7589,7 +7709,8 @@ function registerObservationCommands(parent) {
 			await cmdStats$1();
 		} catch (e) {
 			console.error(err(`  Error: ${e}`));
-			process.exit(1);
+			process.exitCode = 1;
+			return;
 		}
 	});
 }
@@ -7671,7 +7792,8 @@ async function cmdTelemetry(opts) {
 	} catch (e) {
 		console.error(err(`  Failed to reach PAI daemon: ${e}`));
 		console.error(dim$1("  Is the daemon running? Try: pai daemon status"));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	if (opts.json) {
 		console.log(JSON.stringify(rows ?? [], null, 2));
@@ -7714,7 +7836,8 @@ function registerSkillCommands(parent) {
 			await cmdTelemetry(opts);
 		} catch (e) {
 			console.error(err(`  Error: ${e}`));
-			process.exit(1);
+			process.exitCode = 1;
+			return;
 		}
 	});
 }
@@ -7993,7 +8116,8 @@ async function runUpdate() {
 	const repoDir = stepVerifyRepo();
 	if (!repoDir) {
 		line();
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	const didStash = stepStash(repoDir);
 	const newCommitsLog = stepPull(repoDir);
@@ -8002,7 +8126,8 @@ async function runUpdate() {
 		line();
 		error("Update failed at build step. Check errors above.");
 		line();
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	stepRestartDaemon(repoDir);
 	stepRefreshClaudeMd(repoDir, newCommitsLog);
@@ -8070,7 +8195,8 @@ async function cmdStatus() {
 		console.log(dim$1(`  ${msg}`));
 		console.log(dim$1("  Start it with: pai daemon serve"));
 		console.log();
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 }
 async function cmdSet(opts) {
@@ -8088,7 +8214,8 @@ async function cmdSet(opts) {
 		];
 		if (!validModes.includes(opts.mode)) {
 			console.error(err(`Invalid mode: ${opts.mode}. Valid: ${validModes.join(", ")}`));
-			process.exit(1);
+			process.exitCode = 1;
+			return;
 		}
 		patch.mode = opts.mode;
 	}
@@ -8112,7 +8239,8 @@ async function cmdSet(opts) {
 		console.error(err("No changes specified. Use --mode, --enable, --disable, etc."));
 		console.log(dim$1("  Example: pai notify set --mode voice"));
 		console.log(dim$1("  Example: pai notify set --mode auto --enable macos --disable ntfy"));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	try {
 		const { config } = await client.setNotificationConfig(patch);
@@ -8123,7 +8251,8 @@ async function cmdSet(opts) {
 	} catch (e) {
 		const msg = e instanceof Error ? e.message : String(e);
 		console.error(err(`  Failed: ${msg}`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 }
 async function cmdTest(opts) {
@@ -8146,7 +8275,8 @@ async function cmdTest(opts) {
 	} catch (e) {
 		const msg = e instanceof Error ? e.message : String(e);
 		console.error(err(`  Failed: ${msg}`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 }
 async function cmdSend(event, message, opts) {
@@ -8160,7 +8290,8 @@ async function cmdSend(event, message, opts) {
 	];
 	if (!validEvents.includes(event)) {
 		console.error(err(`Invalid event: ${event}. Valid: ${validEvents.join(", ")}`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	try {
 		const result = await client.sendNotification({
@@ -8174,7 +8305,8 @@ async function cmdSend(event, message, opts) {
 	} catch (e) {
 		const msg = e instanceof Error ? e.message : String(e);
 		console.error(err(`  Failed: ${msg}`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 }
 function registerNotifyCommands(notifyCmd) {
@@ -8852,8 +8984,8 @@ async function escalate(task, headline, detail, state, now, opts) {
 	state.alarmedAt[task.id] = now;
 	let delivered = false;
 	try {
-		const { routeNotification } = await import("./router-i9S19Usg.mjs").then((n) => n.n);
-		const { loadConfig } = await import("./config-BSkVcvfq.mjs").then((n) => n.r);
+		const { routeNotification } = await import("./router-BMkOb62X.mjs");
+		const { loadConfig } = await import("./config-C_ErGddD.mjs");
 		delivered = (await routeNotification({
 			event: "error",
 			title: `PAI: ${headline}`,
@@ -8885,6 +9017,51 @@ function saveState$1(state, file) {
 	writeJsonAtomic(file, state, { backup: false });
 }
 /**
+* Fold in any completion a concurrent `pai task done` wrote while this tick
+* was busy with the rest of the list.
+*
+* A tick holds one in-memory `state` for its whole run and saves it exactly
+* once, at the end. For a morning routine with several due tasks that run is
+* not instantaneous — each dispatch waits out AIBroker's spawn-readiness
+* window in turn, so the tick can still be working through task 4 minutes
+* after task 1 was launched. `pai task done` has no such window: it loads,
+* releases the claim, stamps `lastSeenDue` to the next occurrence, and saves,
+* all in well under a second. If the session for task 1 finishes and closes
+* it while the tick is still on task 4, the CLI's write lands on disk first —
+* and the tick's blind save at the end, built from the snapshot it took
+* before any of this happened, overwrites it: `lastSeenDue` reverts to the
+* occurrence that was just completed, and `startedAt`/`claimSeenAt` come back
+* because this tick never learned they had been released. The next tick then
+* reads that reverted date as "due advanced by one period, unclaimed" — which
+* is `wasTicked`'s exact definition of a hand-tick — and redispatches a task
+* that already finished. Reproduced against a live poller run; see the
+* negative control referenced in Notes/TODO.md.
+*
+* `lastSeenDue` only ever moves forward in normal operation, so a disk value
+* strictly ahead of what this tick computed can only mean a concurrent writer
+* — there is exactly one, `pai task done` — saw a later completion than this
+* tick's stale snapshot knew about. Whenever that happens, this tick's own
+* value is the stale one: defer to disk for that task's date, and carry the
+* claim release forward too, since a more-advanced date with no such release
+* is not a state `pai task done` ever produces.
+*
+* Scoped to exactly the fields `pai task done` touches (`releaseClaim` plus
+* the `lastSeenDue` stamp) — the two writers race over nothing else, so a
+* broader merge would only add risk without removing any.
+*/
+function reconcileWithDisk(state, stateFile) {
+	const onDisk = loadState$1(stateFile);
+	for (const [id, oursDue] of Object.entries(state.lastSeenDue)) {
+		const diskDue = onDisk.lastSeenDue[id];
+		if (diskDue !== void 0 && diskDue > oursDue) {
+			state.lastSeenDue[id] = diskDue;
+			delete state.startedAt[id];
+			delete state.claimSeenAt[id];
+			delete state.failedProbes[id];
+		}
+	}
+}
+/**
 * Multiple of the expected duration past which a task is flagged even though it
 * keeps reporting `busy`. A session can be alive and still wrong — stuck in a
 * loop, waiting on a prompt that will never come. Liveness is not progress.
@@ -9018,11 +9195,7 @@ async function tick(opts) {
 			case "abandoned":
 				note = `claimed ${d.elapsedMinutes}m ago, past the ${d.thresholdMinutes}m limit — releasing the claim`;
 				if (!opts.dryRun) {
-					await opts.provider.setLabels(task.id, task.labels.filter((l) => l.toLowerCase() !== RUNNING_LABEL));
-					delete state.startedAt[task.id];
-					delete state.failedProbes[task.id];
-					delete state.claimSeenAt[task.id];
-					await clearRunningMark(task, opts);
+					await releaseClaim(task, opts.provider, state);
 					report.stuck++;
 				}
 				break;
@@ -9042,7 +9215,10 @@ async function tick(opts) {
 			note
 		});
 	}
-	if (!opts.dryRun) saveState$1(state, stateFile);
+	if (!opts.dryRun) {
+		reconcileWithDisk(state, stateFile);
+		saveState$1(state, stateFile);
+	}
 	return report;
 }
 /**
@@ -9127,7 +9303,7 @@ async function handleDispatch(task, overdue, opts, state, now) {
 		};
 	}
 	await opts.provider.setLabels(task.id, task.labels);
-	await clearRunningMark(task, opts);
+	await clearRunningMark(task, opts.provider);
 	const fails = (state.failedDispatches[task.id] ?? 0) + 1;
 	state.failedDispatches[task.id] = fails;
 	const detail = `${result.outcome}${result.reason ? " — " + result.reason : ""}`;
@@ -9205,15 +9381,44 @@ async function markRunning(task, opts, startedAt) {
 * exactly the stale-state problem this whole subsystem keeps producing, so the
 * cleanup is attached to the release rather than to the happy path.
 */
-async function clearRunningMark(task, opts) {
-	const { listComments, deleteComment } = opts.provider;
+async function clearRunningMark(task, provider) {
+	const { listComments, deleteComment } = provider;
 	if (!listComments || !deleteComment) return;
 	try {
-		const comments = await listComments.call(opts.provider, task.id);
-		for (const c of comments) if (c.content.includes(RUNNING_COMMENT_MARK)) await deleteComment.call(opts.provider, c.id);
+		const comments = await listComments.call(provider, task.id);
+		for (const c of comments) if (c.content.includes(RUNNING_COMMENT_MARK)) await deleteComment.call(provider, c.id);
 	} catch {}
 }
 /**
+* Release a claim on a task: strip the interlock label, remove the progress
+* marker, and forget the transient run state that made this poller believe
+* something was still working on it.
+*
+* This is every effect of ending a run except the tracker-side completion
+* itself — factored out so `handleComplete` and the "abandoned" release below
+* cannot drift apart, and so anything else that ends a claim (`pai task done`
+* included) gets the identical cleanup rather than a hand-rolled subset of it.
+* A partial version of this — closing the task but skipping this call — is
+* exactly what left `pai-running` and the transient state behind on every
+* `pai task done` before this existed: the next occurrence of a recurring task
+* inherited a live-looking claim it never made, and the poller spent the
+* morning asking a session whether it was still working on a task it had
+* already finished.
+*
+* Only ever removes `RUNNING_LABEL` from the label array — never replaces it —
+* so any other label the user put on the task survives. Only ever deletes this
+* task's own entries from `startedAt` / `claimSeenAt` / `failedProbes` —
+* `lastSeenDue` and `history` are untouched, exactly as `handleComplete` always
+* left them.
+*/
+async function releaseClaim(task, provider, state) {
+	await provider.setLabels(task.id, task.labels.filter((l) => l.toLowerCase() !== RUNNING_LABEL));
+	await clearRunningMark(task, provider);
+	delete state.startedAt[task.id];
+	delete state.failedProbes[task.id];
+	delete state.claimSeenAt[task.id];
+}
+/**
 * Put a hand-ticked task's schedule back.
 *
 * Deliberately after the dispatch and never in its place: the run is the point,
@@ -9235,12 +9440,8 @@ async function restoreSchedule(task, restoreTo, opts, state) {
 }
 async function handleComplete(task, durationMinutes, opts, state, now) {
 	if (opts.dryRun) return `would clear ${RUNNING_LABEL}, ${durationMinutes ?? "?"}m`;
-	await opts.provider.setLabels(task.id, task.labels.filter((l) => l.toLowerCase() !== RUNNING_LABEL));
-	await clearRunningMark(task, opts);
 	const wasStuck = (state.failedProbes[task.id] ?? 0) > 0;
-	delete state.startedAt[task.id];
-	delete state.failedProbes[task.id];
-	delete state.claimSeenAt[task.id];
+	await releaseClaim(task, opts.provider, state);
 	if (durationMinutes !== null && !wasStuck) {
 		const hist = state.history[task.id] ?? [];
 		hist.push(durationMinutes);
@@ -10005,6 +10206,15 @@ function registerTaskCommands(taskCmd) {
 		if (opts.archive !== false) archived = await archiveTaskThread(provider, id);
 		await provider.complete(id);
 		console.log(chalk.green(`  Completed ${id}.`));
+		try {
+			const task = await provider.getTask(id);
+			if (task) {
+				const state = loadState$1(STATE_FILE$1);
+				await releaseClaim(task, provider, state);
+				if (task.due) state.lastSeenDue[id] = task.due;
+				saveState$1(state, STATE_FILE$1);
+			}
+		} catch {}
 		if (archived) {
 			const what = `${archived.commentCount} comment${archived.commentCount === 1 ? "" : "s"}`;
 			console.log(archived.written ? dim(`  Discussion saved (${what}) → ${archived.path}`) : dim(`  Discussion already saved (${what}), unchanged.`));
@@ -10166,7 +10376,8 @@ async function cmdCheck(context, opts) {
 	const threshold = opts.threshold ? parseFloat(opts.threshold) : void 0;
 	if (threshold !== void 0 && (isNaN(threshold) || threshold < 0 || threshold > 1)) {
 		console.error(err("  --threshold must be a number between 0 and 1"));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	try {
 		const result = await client.topicCheck({
@@ -10179,7 +10390,10 @@ async function cmdCheck(context, opts) {
 			return;
 		}
 		printTopicResult(result);
-		if (result.shifted) process.exit(1);
+		if (result.shifted) {
+			process.exitCode = 1;
+			return;
+		}
 	} catch (e) {
 		const msg = e instanceof Error ? e.message : String(e);
 		console.log();
@@ -10187,7 +10401,8 @@ async function cmdCheck(context, opts) {
 		console.log(dim$1(`  ${msg}`));
 		console.log(dim$1("  Start it with: pai daemon serve"));
 		console.log();
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 }
 function registerTopicCommands(topicCmd) {
@@ -10378,7 +10593,8 @@ async function cmdBackfill(opts) {
 	const limit = opts.limit ? parseInt(opts.limit, 10) : void 0;
 	if (limit !== void 0 && (isNaN(limit) || limit < 1)) {
 		console.error(err("  --limit must be a positive integer"));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	console.log();
 	console.log(header("  PAI KG Backfill"));
@@ -10408,7 +10624,8 @@ async function cmdBackfill(opts) {
 	} catch (e) {
 		const msg = e instanceof Error ? e.message : String(e);
 		console.error(err(`  ${msg}`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 }
 async function cmdQuery$1(opts) {
@@ -10423,7 +10640,8 @@ async function cmdQuery$1(opts) {
 		const asOf = opts.asOf ? new Date(opts.asOf) : void 0;
 		if (asOf && isNaN(asOf.getTime())) {
 			console.error(err(`  Invalid --as-of date: ${opts.asOf}`));
-			process.exit(1);
+			process.exitCode = 1;
+			return;
 		}
 		const triples = await kgQuery(pool, {
 			subject: opts.subject,
@@ -10685,7 +10903,8 @@ async function cmdQuery(sql, opts) {
 	} catch (e) {
 		const msg = e instanceof Error ? e.message : String(e);
 		console.error(err(`  ${msg}`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 }
 async function cmdTables(opts) {
@@ -10709,7 +10928,8 @@ async function cmdTables(opts) {
 	} catch (e) {
 		const msg = e instanceof Error ? e.message : String(e);
 		console.error(err(`  ${msg}`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 }
 async function cmdSchema(table, opts) {
@@ -10730,7 +10950,8 @@ async function cmdSchema(table, opts) {
 	} catch (e) {
 		const msg = e instanceof Error ? e.message : String(e);
 		console.error(err(`  ${msg}`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 }
 function registerDbCommands(dbCmd) {
@@ -11052,7 +11273,8 @@ function cmdList(db, projectSlug, opts) {
 		const project = getProject$1(db, projectSlug);
 		if (!project) {
 			console.error(err(`Project not found: ${projectSlug}`));
-			process.exit(1);
+			process.exitCode = 1;
+			return;
 		}
 		where.push("s.project_id = ?");
 		params.push(project.id);
@@ -11117,7 +11339,8 @@ function cmdInfo(db, projectSlug, sessionNumber) {
 	const project = getProject$1(db, projectSlug);
 	if (!project) {
 		console.error(err(`Project not found: ${projectSlug}`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	const session = resolveSession(db, project, sessionNumber);
 	console.log();
@@ -11138,13 +11361,15 @@ function cmdRename(db, projectSlug, numberOrLatest, newSlug) {
 	const project = getProject$1(db, projectSlug);
 	if (!project) {
 		console.error(err(`Project not found: ${projectSlug}`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	const session = resolveSession(db, project, numberOrLatest);
 	const notesDir = getNotesDir(project);
 	if (!existsSync(notesDir)) {
 		console.error(err(`Notes directory not found: ${notesDir}`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	const titleSlug = toTitleCase$1(newSlug);
 	const newFilename = formatFilename(session.number, session.date, titleSlug);
@@ -11155,7 +11380,8 @@ function cmdRename(db, projectSlug, numberOrLatest, newSlug) {
 			renameSync(oldPath, newPath);
 		} catch (e) {
 			console.error(err(`Failed to rename file: ${e}`));
-			process.exit(1);
+			process.exitCode = 1;
+			return;
 		}
 	} else {
 		console.log(warn$1(`  Note: file not found at expected path: ${session.filename}`));
@@ -11190,7 +11416,8 @@ function cmdSlug(db, projectSlug, numberOrLatest, opts) {
 	const project = getProject$1(db, projectSlug);
 	if (!project) {
 		console.error(err(`Project not found: ${projectSlug}`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	const session = resolveSession(db, project, numberOrLatest);
 	const transcriptPath = findLatestTranscript(project.encoded_dir);
@@ -11217,7 +11444,8 @@ function cmdTag(db, projectSlug, sessionNumber, rawTags) {
 	const project = getProject$1(db, projectSlug);
 	if (!project) {
 		console.error(err(`Project not found: ${projectSlug}`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	const session = resolveSession(db, project, sessionNumber);
 	if (rawTags.length === 0) {
@@ -11254,13 +11482,15 @@ function cmdRoute(db, projectSlug, sessionNumber, targetProjectSlug, opts) {
 	const project = getProject$1(db, projectSlug);
 	if (!project) {
 		console.error(err(`Project not found: ${projectSlug}`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	const session = resolveSession(db, project, sessionNumber);
 	const targetProject = db.prepare("SELECT id, slug, display_name FROM projects WHERE slug = ?").get(targetProjectSlug);
 	if (!targetProject) {
 		console.error(err(`Target project not found: ${targetProjectSlug}`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	const validTypes = [
 		"related",
@@ -11270,7 +11500,8 @@ function cmdRoute(db, projectSlug, sessionNumber, targetProjectSlug, opts) {
 	const linkType = opts.type ?? "related";
 	if (!validTypes.includes(linkType)) {
 		console.error(err(`Invalid link type "${linkType}". Valid: ${validTypes.join(", ")}`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	try {
 		db.prepare(`INSERT INTO links (session_id, target_project_id, link_type, created_at)
@@ -11370,10 +11601,10 @@ function cmdActive(db, opts) {
 	], rows));
 }
 async function cmdAutoRoute(opts) {
-	const { autoRoute, formatAutoRoute, formatAutoRouteJson } = await import("./auto-route-DVM3U2ZY.mjs");
-	const { openRegistry } = await import("./db-BtuN768f.mjs").then((n) => n.t);
-	const { createStorageBackend } = await import("./factory-BGH0COXb.mjs").then((n) => n.n);
-	const { loadConfig } = await import("./config-BSkVcvfq.mjs").then((n) => n.r);
+	const { autoRoute, formatAutoRoute, formatAutoRouteJson } = await import("./auto-route-Byf8ENXj.mjs");
+	const { openRegistry } = await import("./db-XEwJbuGO.mjs");
+	const { createStorageBackend } = await import("./factory-CrokPMk2.mjs");
+	const { loadConfig } = await import("./config-C_ErGddD.mjs");
 	const config = loadConfig();
 	const registryDb = openRegistry();
 	const federation = await createStorageBackend(config);
@@ -11484,10 +11715,10 @@ function touchCheckpointSentinel(notesDir) {
 function cmdCheckpoint(message, opts) {
 	const minGapSeconds = parseInt(opts.minGap ?? "300", 10);
 	const notesDir = findNotesDirForCwd();
-	if (!notesDir) process.exit(0);
-	if (checkpointTooRecent(notesDir, minGapSeconds)) process.exit(0);
+	if (!notesDir) return;
+	if (checkpointTooRecent(notesDir, minGapSeconds)) return;
 	const notePath = findLatestNoteFile(notesDir);
-	if (!notePath) process.exit(0);
+	if (!notePath) return;
 	const block = `\n## Checkpoint — ${(/* @__PURE__ */ new Date()).toISOString()}\n${message}\n`;
 	const tmpPath = `${notePath}.checkpoint.tmp`;
 	try {
@@ -11497,10 +11728,9 @@ function cmdCheckpoint(message, opts) {
 		try {
 			if (existsSync(tmpPath)) renameSync(tmpPath, tmpPath + ".dead");
 		} catch {}
-		process.exit(0);
+		return;
 	}
 	touchCheckpointSentinel(notesDir);
-	process.exit(0);
 }
 
 //#endregion
@@ -11573,22 +11803,26 @@ function cmdPause(db, opts) {
 			body = readBodyFile(opts.bodyFile).trim();
 		} catch (err) {
 			console.error(chalk.red("pai pause: ") + `Could not read checkpoint body from ${opts.bodyFile}: ${String(err)}`);
-			process.exit(1);
+			process.exitCode = 1;
+			return;
 		}
 		if (!body) {
 			console.error(chalk.red("pai pause: ") + `Checkpoint body at ${opts.bodyFile} is empty.`);
-			process.exit(1);
+			process.exitCode = 1;
+			return;
 		}
 	} else if (!opts.noBody) {
 		printMissingBodyError();
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	const cwd = process.cwd();
 	const project = resolveProjectByCwd(db, cwd);
 	if (!project) {
 		console.error(chalk.red("pai pause: ") + `Current directory is not within a registered PAI project.
   cwd: ${cwd}`);
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	const session = db.prepare("SELECT * FROM sessions WHERE project_id = ? ORDER BY number DESC LIMIT 1").get(project.id);
 	const notePath = resolveNotePath(project);
@@ -11615,7 +11849,8 @@ function cmdPause(db, opts) {
 	});
 	if (result.action === "failed") {
 		console.error(chalk.red("pai pause: ") + `Failed to write TODO.md: ${result.error}`);
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	if (opts.dryRun) {
 		console.log("\n" + chalk.bold("Dry run — would write to:") + " " + chalk.cyan(result.path ?? "?"));
@@ -11884,31 +12119,71 @@ function readWorkingTree(cwd) {
 * nothing asked". The handover survives in the session note either way, but
 * `## Continue` is what the next session is shown, so what sits there matters.
 */
+/** Cap on `@n=` file-declaration lines, so the whole message stays ≤25 lines. */
+const MAX_AT_LINES = 17;
+/** Flatten a prompt (or any field value) to a single trimmed line. */
+function flattenField(text) {
+	return text.replace(/\s*\n\s*/g, " ").trim();
+}
+/**
+* Strip a git-porcelain status prefix off a `changes` entry, leaving the path.
+*
+* Porcelain lines are a 1-2 char status field, a space, then the path (e.g.
+* `"M src/foo.ts"`, `" M src/foo.ts"`, `"?? x.ts"`). The stripped result falls
+* back to the trimmed original whenever the pattern does not match, so a
+* surprising entry still produces a usable `@n=` line instead of an empty one.
+*/
+function pathOf(entry) {
+	return entry.replace(/^\s*\S{1,2}\s+/, "").trim() || entry.trim();
+}
+/**
+* Build the auto-checkpoint body as a single AG2 (Agentish v2) message of kind
+* `T` (task/handover). Pure function of its inputs so it can be unit-tested
+* without touching the filesystem or git.
+*
+* Field layout — see the AG2 validator for the authoritative rules:
+*   i = ckpt-<sanitised timestamp>
+*   g = the most recent prompt (goal)
+*   d = the earlier prompts, joined by " | " ("?" when there are none)
+*   t = "?" always — a mechanical handover runs no tests
+*   @n = one declaration per changed file, capped at MAX_AT_LINES so the
+*        whole message stays within AG2's 25-line limit
+*   z = a note summarising the working tree, capped at 200 chars
+*/
+function ag2Checkpoint(prompts, tree, ts) {
+	const id = `ckpt-${ts.replace(/[^A-Za-z0-9._-]/g, "-")}`;
+	const g = flattenField(prompts[0]);
+	const d = prompts.length > 1 ? prompts.slice(1).map(flattenField).join(" | ") : "?";
+	const lines = [
+		"T",
+		`i=${id}`,
+		`g=${g}`,
+		`d=${d}`,
+		"t=?"
+	];
+	let extra = 0;
+	if (tree) {
+		const shown = tree.changes.slice(0, MAX_AT_LINES);
+		extra = Math.max(0, tree.changes.length - MAX_AT_LINES) + tree.overflow;
+		shown.forEach((entry, i) => lines.push(`@${i + 1}=${pathOf(entry)}`));
+	}
+	let z;
+	if (!tree) z = "auto ckpt (no model)";
+	else {
+		const dirty = tree.changes.length;
+		const head = tree.head ?? "nohead";
+		z = `auto ckpt (no model); ${tree.branch}@${head}; ${dirty} dirty`;
+		if (extra > 0) z += `; +${extra} paths`;
+		z += "; git status for detail";
+	}
+	lines.push(`z=${z.length > 200 ? z.slice(0, 200) : z}`);
+	return lines.join("\n");
+}
 function buildAutosaveBody(input) {
 	const ts = input.timestamp ?? (/* @__PURE__ */ new Date()).toISOString();
 	const prompts = recentPrompts(input.transcriptPaths ?? []);
 	if (prompts.length === 0) return "";
-	const tree = readWorkingTree(input.cwd);
-	const dirty = tree?.changes.length ?? 0;
-	const out = [`_Automatic checkpoint — ${ts}. Written without the model, from the transcript and the working tree. A model-authored checkpoint replaces this; it is here so an interrupted session still leaves something._`];
-	if (prompts.length > 0) {
-		out.push("", "### What was being asked", "");
-		for (const p of prompts) out.push(`- ${p.replace(/\s*\n\s*/g, " ")}`);
-	}
-	if (tree) {
-		out.push("", "### Working tree", "");
-		out.push(`- Branch: \`${tree.branch}\``);
-		if (tree.head) out.push(`- HEAD: ${tree.head}`);
-		if (dirty === 0) out.push("- Clean — nothing uncommitted.");
-		else {
-			out.push(`- ${dirty} uncommitted path(s)${tree.overflow > 0 ? ` (+${tree.overflow} more)` : ""}:`);
-			out.push("");
-			out.push("```");
-			out.push(...tree.changes);
-			out.push("```");
-		}
-	}
-	return out.join("\n");
+	return ag2Checkpoint(prompts, readWorkingTree(input.cwd), ts);
 }
 
 //#endregion
@@ -11936,10 +12211,10 @@ function cmdHandover(db, projectSlug, numberOrLatest, sessionId) {
 	let project;
 	if (projectSlug) {
 		project = db.prepare("SELECT id, slug, display_name, root_path, encoded_dir FROM projects WHERE slug = ?").get(projectSlug);
-		if (!project) process.exit(0);
+		if (!project) return;
 	} else {
 		const row = resolveProjectByCwd(db, process.cwd());
-		if (!row) process.exit(0);
+		if (!row) return;
 		project = row;
 	}
 	let session;
@@ -11957,7 +12232,422 @@ function cmdHandover(db, projectSlug, numberOrLatest, sessionId) {
 		cwd: process.cwd(),
 		body: buildStopBody(project, sessionId)
 	});
-	process.exit(0);
+}
+
+//#endregion
+//#region src/hooks/ts/lib/context-fill.ts
+/**
+* context-fill.ts — "how full is this session's context window, right now?"
+*
+* No hook payload carries this number directly (verified: PreCompact,
+* UserPromptSubmit and PostToolUse stdin never include `context_window`).
+* Two sources can reconstruct it, in order of preference:
+*
+*   1. STATUSLINE STATE FILE — statusline-command.sh receives the exact
+*      figure from Claude Code (`.context_window.used_percentage` /
+*      `.context_window.context_window_size`) on every render and persists
+*      it to `${TMPDIR}/pai-context-<session_id>.json`. This is authoritative
+*      but depends on the status line having rendered recently — a session
+*      whose terminal isn't drawing a status line (headless, backgrounded)
+*      leaves this file missing or stale.
+*
+*   2. TRANSCRIPT USAGE — every `message.usage` entry in the session's own
+*      .jsonl transcript already reports the token accounting for that one
+*      API call: `input_tokens + cache_read_input_tokens +
+*      cache_creation_input_tokens` on the MOST RECENT such entry *is* the
+*      current context fill, because each request resends the full context.
+*      This is why it must be the last entry's fields summed, never a sum
+*      across entries — summing across entries is a running token-spend
+*      total, not a fill reading (see calculateSessionTokens, a different
+*      metric answering a different question).
+*
+* When neither source is available, the answer is UNKNOWN, not zero. A zero
+* reads as "plenty of room" and would silently suppress every downstream
+* decision that depends on this number (the compaction handover chief among
+* them) for the entire session.
+*/
+/** Fallback window size when nothing on hand reports one. Matches the
+*  default statusline-command.sh already falls back to. */
+const DEFAULT_CONTEXT_WINDOW = 2e5;
+/** How many trailing lines of the transcript to scan for a usage entry.
+*  A single turn is rarely more than a handful of JSONL lines (assistant
+*  text + tool_use/tool_result pairs), so 40 comfortably covers one turn
+*  even a busy one, without reading the whole file on every check. */
+const TRANSCRIPT_TAIL_LINES = 40;
+/** A statusline reading older than this is treated as not there at all —
+*  a stale number is worse than none, because it looks confident. */
+const STATUSLINE_STALE_MS = 300 * 1e3;
+function unknownReading(windowSize) {
+	return {
+		status: "unknown",
+		usedTokens: null,
+		windowSize,
+		fraction: null,
+		source: "unknown"
+	};
+}
+function statuslineStateFilePath(sessionId) {
+	return join(tmpdir(), `pai-context-${sessionId}.json`);
+}
+/**
+* Read the state file statusline-command.sh writes on every render.
+* Returns null when the file is missing, unparsable, or older than
+* STATUSLINE_STALE_MS — all three mean "not a source right now".
+*/
+function readStatuslineFill(sessionId, now = Date.now()) {
+	if (!sessionId) return null;
+	const path = statuslineStateFilePath(sessionId);
+	if (!existsSync(path)) return null;
+	let raw;
+	try {
+		raw = JSON.parse(readFileSync(path, "utf-8"));
+	} catch {
+		return null;
+	}
+	if (typeof raw.timestamp !== "number" || now - raw.timestamp > STATUSLINE_STALE_MS) return null;
+	if (typeof raw.used_percentage !== "number" || typeof raw.context_window_size !== "number") return null;
+	const windowSize = raw.context_window_size;
+	return {
+		status: "ok",
+		usedTokens: Math.round(raw.used_percentage / 100 * windowSize),
+		windowSize,
+		fraction: raw.used_percentage / 100,
+		source: "statusline"
+	};
+}
+/**
+* Sum the three context-carrying fields of ONE usage object — never across
+* usage objects. A single `message.usage` already reports what that one API
+* call sent as context; adding another entry's numbers to it produces a
+* cumulative spend figure, not a fill reading, and can exceed the window
+* size many times over on a long session (the exact defect this helper
+* exists to not repeat — see the PreCompact header fix in the same change).
+*/
+function usageTotal(usage) {
+	return (usage.input_tokens || 0) + (usage.cache_read_input_tokens || 0) + (usage.cache_creation_input_tokens || 0);
+}
+/**
+* Derive context fill from the tail of a .jsonl transcript: the most recent
+* `message.usage` entry, read from the end backwards so a trailing line with
+* no usage field (a plain text turn, a tool_result) doesn't hide one just
+* before it.
+*/
+function contextFillFromTranscript(transcriptPath, windowSize = DEFAULT_CONTEXT_WINDOW) {
+	if (!transcriptPath || !existsSync(transcriptPath)) return unknownReading(windowSize);
+	let raw;
+	try {
+		raw = readFileSync(transcriptPath, "utf-8");
+	} catch {
+		return unknownReading(windowSize);
+	}
+	const tail = raw.trim().split("\n").filter((l) => l.trim()).slice(-TRANSCRIPT_TAIL_LINES);
+	for (let i = tail.length - 1; i >= 0; i--) {
+		let entry;
+		try {
+			entry = JSON.parse(tail[i]);
+		} catch {
+			continue;
+		}
+		const usage = entry?.message?.usage;
+		if (usage && typeof usage === "object") {
+			const usedTokens = usageTotal(usage);
+			return {
+				status: "ok",
+				usedTokens,
+				windowSize,
+				fraction: usedTokens / windowSize,
+				source: "transcript"
+			};
+		}
+	}
+	return unknownReading(windowSize);
+}
+function getContextFill(input, now = Date.now()) {
+	const windowSize = input.windowSize ?? DEFAULT_CONTEXT_WINDOW;
+	if (input.sessionId) {
+		const fromStatusline = readStatuslineFill(input.sessionId, now);
+		if (fromStatusline) return fromStatusline;
+	}
+	if (input.transcriptPath) return contextFillFromTranscript(input.transcriptPath, windowSize);
+	return unknownReading(windowSize);
+}
+const DEFAULT_AUTOCOMPACT_PCT = 80;
+/** How many of the most recent compact_boundary events to consider, and to
+*  take the minimum of. */
+const MEASURED_TRIGGER_SAMPLE_SIZE = 3;
+/** How many of a project's most-recently-modified transcripts to scan for
+*  compact_boundary events. compact_boundary events cluster in whichever
+*  files were touched most recently — a full-history scan would cost a lot
+*  for a long-lived project and buy nothing this doesn't already get from
+*  the last handful of files. */
+const MEASURED_TRIGGER_MAX_FILES = 8;
+const THRESHOLD_MARGIN_TOKENS = {
+	warmup: 1e5,
+	refresh: 4e4,
+	immediate: 15e3
+};
+/** Real default — overridable per-call so tests never touch the user's
+*  actual ~/.claude/projects/ (a live directory this very session writes to). */
+const CLAUDE_PROJECTS_DIR = join(homedir(), ".claude", "projects");
+function encodeProjectPath(cwd) {
+	return cwd.replace(/[/\s.-]/g, "-");
+}
+function listProjectTranscripts(cwd, projectsDir) {
+	const projectDir = join(projectsDir, encodeProjectPath(cwd));
+	if (!existsSync(projectDir)) return [];
+	const candidates = [];
+	const collect = (dir) => {
+		if (!existsSync(dir)) return;
+		let entries;
+		try {
+			entries = readdirSync(dir);
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			if (!entry.endsWith(".jsonl")) continue;
+			const full = join(dir, entry);
+			try {
+				candidates.push({
+					path: full,
+					mtimeMs: statSync(full).mtimeMs
+				});
+			} catch {}
+		}
+	};
+	collect(projectDir);
+	collect(join(projectDir, "sessions"));
+	candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+	return candidates.slice(0, MEASURED_TRIGGER_MAX_FILES).map((c) => c.path);
+}
+/**
+* Every compact_boundary sample found in a project's most-recently-modified
+* transcripts, newest first.
+*/
+function readCompactBoundarySamples(cwd, projectsDir) {
+	const samples = [];
+	for (const path of listProjectTranscripts(cwd, projectsDir)) {
+		let raw;
+		try {
+			raw = readFileSync(path, "utf-8");
+		} catch {
+			continue;
+		}
+		for (const line of raw.split("\n")) {
+			if (!line.trim()) continue;
+			let entry;
+			try {
+				entry = JSON.parse(line);
+			} catch {
+				continue;
+			}
+			if (entry.type !== "system" || entry.subtype !== "compact_boundary") continue;
+			const preTokens = entry.compactMetadata?.preTokens;
+			if (typeof preTokens !== "number" || !Number.isFinite(preTokens)) continue;
+			const timestampMs = entry.timestamp ? Date.parse(entry.timestamp) : NaN;
+			if (!Number.isFinite(timestampMs)) continue;
+			samples.push({
+				preTokens,
+				timestampMs
+			});
+		}
+	}
+	samples.sort((a, b) => b.timestampMs - a.timestampMs);
+	return samples;
+}
+/**
+* The measured compaction trigger for a project, or null when it has no
+* compaction history yet (a brand-new project, or one whose transcripts
+* this process cannot read). Minimum of the most recent
+* MEASURED_TRIGGER_SAMPLE_SIZE compact_boundary events — see the module
+* comment above for why minimum, not mean.
+*/
+function measureCompactionTrigger(cwd, projectsDir = CLAUDE_PROJECTS_DIR) {
+	if (!cwd) return null;
+	const samples = readCompactBoundarySamples(cwd, projectsDir).slice(0, MEASURED_TRIGGER_SAMPLE_SIZE);
+	if (samples.length === 0) return null;
+	return Math.min(...samples.map((s) => s.preTokens));
+}
+/**
+* Read CLAUDE_AUTOCOMPACT_PCT_OVERRIDE from the environment. Absent →
+* DEFAULT_AUTOCOMPACT_PCT. Present but not a finite number in (0, 100] →
+* also DEFAULT_AUTOCOMPACT_PCT, logged, so a typo in the override degrades
+* to the documented default instead of silently producing nonsense
+* thresholds (0, negative, or a fraction so large no session ever reaches
+* it).
+*/
+function resolveAutocompactPct(env = process.env) {
+	const raw = env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE;
+	if (raw === void 0 || raw === "") return DEFAULT_AUTOCOMPACT_PCT;
+	const parsed = Number(raw);
+	if (!Number.isFinite(parsed) || parsed <= 0 || parsed > 100) {
+		console.error(`[context-fill] CLAUDE_AUTOCOMPACT_PCT_OVERRIDE="${raw}" is not a usable percentage — falling back to the default ${DEFAULT_AUTOCOMPACT_PCT}.`);
+		return DEFAULT_AUTOCOMPACT_PCT;
+	}
+	return parsed;
+}
+/**
+* Derive warmup/refresh/immediate thresholds from a fill reading, preferring
+* this project's own measured compaction history over the configured
+* override chain — see the module comment above for why. Margins are
+* clamped at 0 (and logged) for a window small enough that a margin would
+* otherwise go negative — a pathological input should degrade to "fire
+* immediately", never to a threshold below zero.
+*/
+function contextFillThresholds(reading, env = process.env, opts = {}) {
+	const windowConfirmed = reading.source === "statusline";
+	const autocompactPct = resolveAutocompactPct(env);
+	const configuredTriggerTokens = Math.round(reading.windowSize * (autocompactPct / 100));
+	const measured = opts.measuredTrigger !== void 0 ? opts.measuredTrigger : opts.cwd ? measureCompactionTrigger(opts.cwd) : null;
+	const triggerSource = measured !== null ? "measured" : "configured";
+	const effectiveTriggerTokens = measured !== null ? measured : configuredTriggerTokens;
+	if (triggerSource === "measured") console.error(`[context-fill] trigger source: MEASURED — ${effectiveTriggerTokens} tokens (minimum of the most recent ${MEASURED_TRIGGER_SAMPLE_SIZE} compact_boundary events for this project; the configured chain would have given ${configuredTriggerTokens}).`);
+	else console.error(`[context-fill] trigger source: CONFIGURED — no compaction history for this project yet, using ${effectiveTriggerTokens} tokens (${autocompactPct}% of a ${reading.windowSize}-token window).`);
+	const clamp = (name, value) => {
+		if (value >= 0) return value;
+		console.error(`[context-fill] ${name} threshold went negative (${value}) for a ${reading.windowSize}-token window — clamping to 0.`);
+		return 0;
+	};
+	return {
+		warmupTokens: clamp("warmup", effectiveTriggerTokens - THRESHOLD_MARGIN_TOKENS.warmup),
+		refreshTokens: clamp("refresh", effectiveTriggerTokens - THRESHOLD_MARGIN_TOKENS.refresh),
+		immediateTokens: clamp("immediate", effectiveTriggerTokens - THRESHOLD_MARGIN_TOKENS.immediate),
+		effectiveTriggerTokens,
+		autocompactPct,
+		triggerSource,
+		windowConfirmed
+	};
+}
+/**
+* Which named thresholds `usedTokens` has newly crossed, given the ones that
+* have already fired this session. Ascending order (warmup before refresh).
+*
+* A single check can return more than one name — e.g. a session first
+* observed at 99% of its window crosses warmup and refresh in the same tick,
+* because there was no earlier clean crossing to catch it at. That is the
+* "fire immediately" case: the caller enqueues one handover and marks every
+* newly-crossed name fired, rather than waiting for a crossing that already
+* happened.
+*/
+function crossedThresholds(usedTokens, thresholds, alreadyFired) {
+	const fired = new Set(alreadyFired);
+	return [["warmup", thresholds.warmupTokens], ["refresh", thresholds.refreshTokens]].filter(([name, tokens]) => !fired.has(name) && usedTokens >= tokens).map(([name]) => name);
+}
+/**
+* True once a session is at or above the "no time left for a clean crossing"
+* floor (0.985 of the window). Purely informational for callers — it never
+* gates whether `crossedThresholds` fires (a poll-based check already fires
+* any unfired threshold the moment `usedTokens` reaches it, on whatever tick
+* observes it) — but it distinguishes "this crossed on schedule" from "this
+* was first observed already almost out of room", which is worth a different
+* log line and, for a caller that queues work, a higher priority.
+*/
+function isImmediate(usedTokens, thresholds) {
+	return usedTokens >= thresholds.immediateTokens;
+}
+
+//#endregion
+//#region src/session/context-handover-trigger.ts
+/**
+* context-handover-trigger.ts — decide whether THIS check is the moment a
+* session should get its threshold-triggered pre-compaction handover, and
+* enqueue it with the daemon if so.
+*
+* Called from the same live hooks that already drive the AG2 rolling
+* autosave (UserPromptSubmit, PostToolUse) — see
+* cli/commands/session/autosave.ts. Reuses the context-fill reading and the
+* derived thresholds from hooks/ts/lib/context-fill.ts; this module only
+* adds the "have we already fired this one" bookkeeping and the enqueue.
+*
+* Never throws. A daemon that isn't running, a stale reading, an unknown
+* fill — every one of those is a reason to do nothing this check and try
+* again next time, not a reason to interrupt the hook that called this.
+*/
+/** The enqueue only needs to hand the item to the daemon's queue file — the
+*  actual LLM call happens later, asynchronously, in the worker loop. A
+*  short bound keeps a rare (at most twice per session) daemon hiccup from
+*  making the calling hook wait anywhere near as long as a normal IPC call
+*  is allowed to. */
+const ENQUEUE_TIMEOUT_MS = 2e3;
+/** Both thresholds fired — nothing left to check for the rest of the session. */
+const ALL_THRESHOLDS = ["warmup", "refresh"];
+function firedThresholdsPath(sessionId) {
+	return join(tmpdir(), `pai-context-handover-fired-${sessionId}.json`);
+}
+function loadFiredThresholds(sessionId) {
+	const path = firedThresholdsPath(sessionId);
+	if (!existsSync(path)) return [];
+	try {
+		const raw = JSON.parse(readFileSync(path, "utf-8"));
+		return Array.isArray(raw.fired) ? raw.fired : [];
+	} catch {
+		return [];
+	}
+}
+function saveFiredThresholds(sessionId, fired) {
+	try {
+		writeFileSync(firedThresholdsPath(sessionId), JSON.stringify({ fired }), "utf-8");
+	} catch {}
+}
+async function enqueueContextHandover(payload) {
+	await new PaiClient().call("work_queue_enqueue", {
+		type: "context-handover",
+		priority: 3,
+		payload: {
+			sessionId: payload.sessionId,
+			cwd: payload.cwd,
+			transcriptPath: payload.transcriptPath,
+			threshold: payload.threshold,
+			urgent: payload.urgent
+		}
+	}, ENQUEUE_TIMEOUT_MS);
+}
+const defaultDeps = {
+	getReading: (input) => getContextFill({
+		sessionId: input.sessionId,
+		transcriptPath: input.transcriptPath
+	}),
+	loadFired: loadFiredThresholds,
+	saveFired: saveFiredThresholds,
+	enqueue: enqueueContextHandover
+};
+/**
+* Check this session's current context fill against the derived thresholds
+* and enqueue a context-handover job for any newly-crossed one. Returns the
+* threshold name(s) newly fired this call — empty when nothing crossed, the
+* reading is unknown, or every threshold has already fired.
+*
+* A single check that crosses both warmup and refresh in one jump (a
+* session first observed already close to compaction) enqueues ONE job,
+* tagged with the more urgent of the two, and marks both fired — one
+* model-written handover already covers what either alone would have.
+*/
+async function checkAndEnqueueContextHandover(input, deps = defaultDeps) {
+	const alreadyFired = deps.loadFired(input.sessionId);
+	if (ALL_THRESHOLDS.every((t) => alreadyFired.includes(t))) return [];
+	const reading = deps.getReading(input);
+	if (reading.status !== "ok" || reading.usedTokens === null) return [];
+	const thresholds = contextFillThresholds(reading, process.env, { cwd: input.cwd });
+	if (!thresholds.windowConfirmed) console.error(`[context-handover-trigger] session ${input.sessionId}: window size not confirmed — using the assumed default (${reading.windowSize} tokens) rather than a reading Claude Code reported.`);
+	const newlyCrossed = crossedThresholds(reading.usedTokens, thresholds, alreadyFired);
+	if (newlyCrossed.length === 0) return [];
+	const urgent = isImmediate(reading.usedTokens, thresholds);
+	const mostUrgent = newlyCrossed[newlyCrossed.length - 1];
+	try {
+		await deps.enqueue({
+			sessionId: input.sessionId,
+			cwd: input.cwd,
+			transcriptPath: input.transcriptPath,
+			threshold: mostUrgent,
+			urgent
+		});
+	} catch (err) {
+		console.error(`[context-handover-trigger] session ${input.sessionId}: enqueue failed, will retry next check: ${err}`);
+		return [];
+	}
+	deps.saveFired(input.sessionId, [...alreadyFired, ...newlyCrossed]);
+	console.error(`[context-handover-trigger] session ${input.sessionId}: crossed [${newlyCrossed.join(", ")}] at ${reading.usedTokens} tokens (trigger=${thresholds.effectiveTriggerTokens}, triggerSource=${thresholds.triggerSource}, autocompactPct=${thresholds.autocompactPct}, urgent=${urgent}).`);
+	return newlyCrossed;
 }
 
 //#endregion
@@ -11990,17 +12680,28 @@ function touchSentinel(rootPath) {
 		writeFileSync(sentinelPath(rootPath), String(Date.now()), "utf8");
 	} catch {}
 }
-function cmdAutosave(db, opts) {
+async function cmdAutosave(db, opts) {
 	const minGap = parseInt(opts.minGap ?? String(DEFAULT_MIN_GAP), 10);
 	const cwd = process.cwd();
 	const project = resolveProjectByCwd(db, cwd);
-	if (!project) process.exit(0);
-	if (!opts.dryRun && tooRecent(project.root_path, minGap)) process.exit(0);
+	if (!project) return;
+	if (!opts.dryRun && tooRecent(project.root_path, minGap)) return;
+	const transcriptPaths = findTranscripts(resolveTranscriptDir(project), opts.sessionId);
+	if (opts.sessionId && !opts.dryRun) {
+		const liveTranscript = transcriptPaths[transcriptPaths.length - 1];
+		try {
+			await checkAndEnqueueContextHandover({
+				sessionId: opts.sessionId,
+				cwd,
+				transcriptPath: liveTranscript
+			});
+		} catch {}
+	}
 	const body = buildAutosaveBody({
 		cwd,
-		transcriptPaths: findTranscripts(resolveTranscriptDir(project), opts.sessionId)
+		transcriptPaths
 	});
-	if (!body) process.exit(0);
+	if (!body) return;
 	const session = db.prepare("SELECT * FROM sessions WHERE project_id = ? ORDER BY number DESC LIMIT 1").get(project.id);
 	const result = applyContinue({
 		rootPath: project.root_path,
@@ -12014,10 +12715,9 @@ function cmdAutosave(db, opts) {
 	if (opts.dryRun) {
 		console.log(result.block);
 		console.log(`\n[dry-run] action would be: ${result.action}`);
-		process.exit(0);
+		return;
 	}
 	touchSentinel(project.root_path);
-	process.exit(0);
 }
 
 //#endregion
@@ -12154,7 +12854,8 @@ function cmdGoto(db, query, opts) {
 		let msg = String(resolveErr).replace(/^Error: /, "");
 		if (msg.includes("No session found matching")) msg += `\n\nTip: pai find "${query}"  — search prompt history by keywords`;
 		console.error(err(msg));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	const { session: matchedSession, friendlyName } = resolved;
 	let resumableUuid;
@@ -12176,7 +12877,8 @@ function cmdGoto(db, query, opts) {
 		projectDir = realpathSync(rawDir);
 	} catch {
 		console.error(err(`session "${query}": directory does not exist or cannot be resolved.\n  Registry says: ${rawDir}\n  The directory may have moved or been deleted.`));
-		process.exit(1);
+		process.exitCode = 1;
+		return;
 	}
 	const name = friendlyName ?? query;
 	const promptArg = `/Name ${name}\ngo`;
@@ -12220,10 +12922,12 @@ function cmdGoto(db, query, opts) {
 			});
 			if (result.error) {
 				console.error(err(`Failed to launch claude: ${result.error.message}`));
-				process.exit(1);
+				process.exitCode = 1;
+				return;
 			}
 			printExitDir(projectDir);
-			process.exit(result.status ?? 0);
+			process.exitCode = result.status ?? 0;
+			return;
 		} else {
 			process.stderr.write(chalk.yellow(`\n  Resume failed for ${resumableUuid.slice(0, 8)}: ${probe.reason ?? "unknown error"}\n  Starting fresh session in same directory.\n\n`));
 			const result = spawnSync("claude", [
@@ -12237,10 +12941,12 @@ function cmdGoto(db, query, opts) {
 			});
 			if (result.error) {
 				console.error(err(`Failed to launch claude: ${result.error.message}`));
-				process.exit(1);
+				process.exitCode = 1;
+				return;
 			}
 			printExitDir(projectDir);
-			process.exit(result.status ?? 0);
+			process.exitCode = result.status ?? 0;
+			return;
 		}
 	} else {
 		const result = spawnSync("claude", [
@@ -12254,10 +12960,11 @@ function cmdGoto(db, query, opts) {
 		});
 		if (result.error) {
 			console.error(err(`Failed to launch claude: ${result.error.message}`));
-			process.exit(1);
+			process.exitCode = 1;
+			return;
 		}
 		printExitDir(projectDir);
-		process.exit(result.status ?? 0);
+		process.exitCode = result.status ?? 0;
 	}
 }
 
@@ -12505,8 +13212,8 @@ function registerSessionCommands(sessionCmd, getDb) {
 	sessionCmd.command("checkpoint <message>").description("Append a timestamped checkpoint to the active session note.\nDesigned for hooks (PostToolUse, UserPromptSubmit) — fast and silent.\nRate-limited: skips silently if last checkpoint was < --min-gap seconds ago.").option("--min-gap <seconds>", "Minimum seconds between checkpoints (default: 300 = 5 minutes)", "300").action((message, opts) => {
 		cmdCheckpoint(message, opts);
 	});
-	sessionCmd.command("autosave").description("Refresh the ## Continue checkpoint from the transcript and working tree.\nRuns unattended from live hooks so an interrupted session still leaves\na usable handover. Writes in auto mode, so a model-authored checkpoint\nfor the same session is preserved untouched. Silent; always exits 0.").option("--session-id <uuid>", "Claude session UUID — the key that decides whether an existing authored\ncheckpoint belongs to this session and must be left alone.").option("--min-gap <seconds>", "Minimum seconds between autosaves, shared across all triggers (default: 240)", "240").option("--dry-run", "Print the block that would be written and exit").action((opts) => {
-		cmdAutosave(getDb(), opts);
+	sessionCmd.command("autosave").description("Refresh the ## Continue checkpoint from the transcript and working tree.\nRuns unattended from live hooks so an interrupted session still leaves\na usable handover. Writes in auto mode, so a model-authored checkpoint\nfor the same session is preserved untouched. Silent; always exits 0.").option("--session-id <uuid>", "Claude session UUID — the key that decides whether an existing authored\ncheckpoint belongs to this session and must be left alone.").option("--min-gap <seconds>", "Minimum seconds between autosaves, shared across all triggers (default: 240)", "240").option("--dry-run", "Print the block that would be written and exit").action(async (opts) => {
+		await cmdAutosave(getDb(), opts);
 	});
 	sessionCmd.command("active").description("Show currently active Claude Code sessions.\nDetects live sessions by checking which JSONL transcript files\nwere recently modified in ~/.claude/projects/.").option("--minutes <n>", "Consider sessions active if modified within N minutes (default: 60)", "60").option("--json", "Output raw JSON instead of formatted display").action((opts) => {
 		cmdActive(getDb(), opts);
@@ -12900,8 +13607,8 @@ function analyzeProject(db, project) {
 async function countVectorDbPaths(oldPaths) {
 	if (oldPaths.length === 0) return 0;
 	try {
-		const { loadConfig } = await import("./config-BSkVcvfq.mjs").then((n) => n.r);
-		const { PostgresBackend } = await import("./postgres-BALUE11K.mjs");
+		const { loadConfig } = await import("./config-C_ErGddD.mjs");
+		const { PostgresBackend } = await import("./postgres-BVme6qX0.mjs");
 		const config = loadConfig();
 		if (config.storageBackend !== "postgres") return 0;
 		const pgBackend = new PostgresBackend(config.postgres ?? {});
@@ -12921,8 +13628,8 @@ async function countVectorDbPaths(oldPaths) {
 async function updateVectorDbPaths(moves) {
 	if (moves.length === 0) return 0;
 	try {
-		const { loadConfig } = await import("./config-BSkVcvfq.mjs").then((n) => n.r);
-		const { PostgresBackend } = await import("./postgres-BALUE11K.mjs");
+		const { loadConfig } = await import("./config-C_ErGddD.mjs");
+		const { PostgresBackend } = await import("./postgres-BVme6qX0.mjs");
 		const config = loadConfig();
 		if (config.storageBackend !== "postgres") return 0;
 		const pgBackend = new PostgresBackend(config.postgres ?? {});
@@ -13228,7 +13935,8 @@ function registerSessionCleanupCommand(sessionCmd, getDb) {
 			const p = getProject(db, projectSlug);
 			if (!p) {
 				console.error(err(`Project not found: ${projectSlug}`));
-				process.exit(1);
+				process.exitCode = 1;
+				return;
 			}
 			projects = [p];
 		} else projects = getAllProjects(db);
@@ -14204,5 +14912,245 @@ async function cmdPick(db, opts = {}) {
 }
 
 //#endregion
-export { registerProjectsCommands as A, registerRestoreCommands as C, registerIdentityCommands as D, registerMcpCommands as E, resolveIdentifier as M, registerMemoryCommands as O, registerSetupCommand as S, registerDaemonCommands as T, registerUpdateCommand as _, cmdEnd as a, registerZettelCommands as b, cmdGoto as c, registerHelpCommand as d, registerDbCommands as f, registerNotifyCommands as g, registerTaskCommands as h, cmdPauseAll as i, findMovedPath as j, registerRegistryCommands as k, cmdPause as l, registerTopicCommands as m, cmdFind as n, registerSessionCleanupCommand as o, registerKgCommands as p, cmdClearNames as r, registerSessionCommands as s, cmdPick as t, cmdList as u, registerSkillCommands as v, registerBackupCommands as w, registerObsidianCommands as x, registerObservationCommands as y };
-//# sourceMappingURL=pick-aWhenqjE.mjs.map
+//#region src/cli/program.ts
+/**
+* PAI CLI — Commander program builder.
+*
+* Constructs the full `pai` command tree WITHOUT parsing argv. This separation
+* lets the documentation generator (scripts/build-docs.mjs) import and introspect
+* the live program object — the single source of truth for `--help`, the
+* generated man pages, and `pai help <area>`.
+*
+* The thin entry point (cli/index.ts) imports buildProgram() and calls parse().
+*/
+function getVersion() {
+	try {
+		const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "../../package.json");
+		return JSON.parse(readFileSync(pkgPath, "utf8")).version ?? "0.0.0";
+	} catch {
+		return "0.0.0";
+	}
+}
+let _db = null;
+function getDb() {
+	if (!_db) try {
+		_db = openRegistry();
+	} catch (e) {
+		throw new Error(`Failed to open PAI registry: ${e}`);
+	}
+	return _db;
+}
+/**
+* Build and return the fully configured `pai` Commander program.
+* Does NOT call parse — the caller (cli/index.ts) does that.
+*/
+function buildProgram() {
+	const program = new Command();
+	program.name("pai").description("PAI Knowledge OS — Personal AI Infrastructure CLI").version(getVersion(), "-V, --version", "Print version and exit").addHelpText("after", `
+Daily commands:
+  pai                     Show your work: live tabs + recent sessions + recent projects
+  pai <name>              Switch / resume / fresh — universal
+  pai pause [all]         Pause current (or all live) sessions
+  pai end                 Finalize current session
+
+Subcommands (rarely needed):
+  pai projects ...        Project registry management (cd, rebind, info, ...)
+  pai registry ...        Registry maintenance (scan, ...)
+  pai memory ...          Memory engine (index, search, ...)
+  pai shell-init          Shell integration (eval "$(pai shell-init)")
+
+Recovery:
+  pai clear-names         Wipe corrupt iTerm tab-name store
+
+Examples:
+  pai aibroker            Switch to the live AIBroker tab in iTerm
+  pai mdf                 Find sessions where you worked on MDF
+  pai 81c5c3dc            Resume session by UUID prefix
+  pai --all               Show everything including cold and zero-session projects`);
+	registerProjectsCommands(program.command("projects").description("Manage registered projects (list, cd, add, info, ...)"), getDb);
+	registerProjectsCommands(program.command("project").description("Alias for `pai projects`"), getDb);
+	const sessionCmd = program.command("session").description("Session management: list, info, checkpoint, handover, cleanup, slug, tag, route.\nShort forms: `pai pause`, `pai end`, `pai resume <name>`.");
+	registerSessionCommands(sessionCmd, getDb);
+	registerSessionCleanupCommand(sessionCmd, getDb);
+	program.command("sessions").description("Alias for `pai` — show the unified deduped listing.").option("--all", "Show all entries including cold / zero-session / archived projects").option("-n, --n <count>", "Max candidates for history search", "20").action(async (opts) => {
+		await cmdMain(getDb(), void 0, void 0, opts);
+	});
+	registerRegistryCommands(program.command("registry").description("Registry maintenance: scan, migrate, stats, rebuild"), getDb);
+	registerMemoryCommands(program.command("memory").description("Memory engine: index, search, and status"), getDb);
+	registerIdentityCommands(program.command("identity").description("Declare who you are: self addresses and where mail is delivered"));
+	registerMcpCommands(program.command("mcp").description("MCP server management: install and status"));
+	registerDaemonCommands(program.command("daemon").description("PAI daemon management: serve, status, restart, install, uninstall, logs"));
+	registerBackupCommands(program);
+	registerRestoreCommands(program);
+	registerSetupCommand(program);
+	registerUpdateCommand(program);
+	registerNotifyCommands(program.command("notify").description("Notification config: status, get, set, test, send"));
+	registerTaskCommands(program.command("task").alias("tasks").description("Task bus: list, add, dispatch, and complete cross-session work"));
+	registerTopicCommands(program.command("topic").description("Topic shift detection: check whether context has drifted to a different project"));
+	registerKgCommands(program.command("kg").description("Temporal knowledge graph: backfill, query, list, stats"));
+	registerDbCommands(program.command("db").description("Database inspection: query, tables, schema (sqlite or postgres)"));
+	registerObsidianCommands(program.command("obsidian").description("Obsidian vault: sync project notes, view status, open in Obsidian"), getDb);
+	registerZettelCommands(program.command("zettel").description("Zettelkasten intelligence: explore, surprise, converse, themes, health, suggest"), getDb);
+	registerObservationCommands(program.command("observation").description("Observation capture: list, search, and stats"));
+	registerSkillCommands(program.command("skill").description("Skill telemetry and (future) discovery for the self-educating skill system"));
+	registerHelpCommand(program);
+	program.command("pause [target]").description("Save state and display safe-exit instructions for the current session.\nWrites a ## Continue checkpoint to the project's TODO.md.\nUse `pai pause all` to pause every live session via AIBroker.").option("--dry-run", "Preview changes without writing them").option("--body-file <path>", "File holding the checkpoint markdown to persist ('-' reads stdin). Required unless --no-body.").option("--session-id <uuid>", "Claude Code session UUID — recorded as the `claude --resume` handle").option("--no-body", "Deliberately write a metadata-only checkpoint (no content)").option("--exit", "(pause all only) Also send /exit to each session after pausing").option("--only <name>", "(pause all only) Pause just the sessions whose name or id contains <name>.\nFor rehearsing the real thing against one session before trusting it with\nevery open tab — a dry run exercises enumeration but never sends anything,\nwhich is exactly how a broken send survived until it was needed.").option("--wait <ms>", "(pause all only) Max milliseconds to wait for a session to finish its\ncheckpoint before /exit. Not a fixed delay — sessions are exited as soon\nas they return to the prompt, and any still busy at the deadline are left\nopen rather than killed mid-write. (default: 180000)", "180000").action(async (target, opts) => {
+		if (target === "all") await cmdPauseAll({
+			exit: opts.exit,
+			dryRun: opts.dryRun,
+			only: opts.only,
+			wait: opts.wait !== void 0 ? parseInt(opts.wait, 10) : void 0
+		});
+		else {
+			if (target !== void 0) {
+				console.error(err(`Unknown target: ${target}. Did you mean 'pai pause all'?`));
+				process.exitCode = 1;
+				return;
+			}
+			cmdPause(getDb(), {
+				dryRun: opts.dryRun,
+				bodyFile: opts.bodyFile,
+				sessionId: opts.sessionId,
+				noBody: opts.body === false
+			});
+		}
+	});
+	program.command("end").description("Finalize a session: save state, mark note Completed, display safe-exit instructions.").option("--dry-run", "Preview all changes without writing them").option("--body-file <path>", "File holding the checkpoint markdown to persist ('-' reads stdin). Required unless --no-body.").option("--session-id <uuid>", "Claude Code session UUID — recorded as the `claude --resume` handle").option("--no-body", "Deliberately write a metadata-only checkpoint (no content)").action((opts) => {
+		cmdEnd(getDb(), {
+			dryRun: opts.dryRun,
+			bodyFile: opts.bodyFile,
+			sessionId: opts.sessionId,
+			noBody: opts.body === false
+		});
+	});
+	program.command("clear-names").description("Recovery: wipe corrupted iTerm2 session name state.\nClears ~/.aibroker/session-names.json AND user.paiName from all live iTerm2 sessions.\nAfter running this, use /Name to re-label each tab.").option("--dry-run", "Preview what would be cleared without making changes").action(async (opts) => {
+		await cmdClearNames(opts);
+	});
+	program.command("resume <name>", { hidden: true }).description("Go to a session by name or UUID (prefer: pai <name>)").option("--dry-run", "Print the exact argv and cwd, then exit without launching").action((name, opts) => {
+		cmdGoto(getDb(), name, { dryRun: opts.dryRun });
+	});
+	program.command("cd <identifier>", { hidden: true }).description("cd to a project directory (shell wrapper handles the actual cd)").action((identifier) => {
+		const db = getDb();
+		const project = resolveIdentifier(db, identifier);
+		if (!project) {
+			console.error(`Project not found: ${identifier}`);
+			process.exitCode = 1;
+			return;
+		}
+		if (existsSync(project.root_path)) {
+			process.stdout.write(project.root_path + "\n");
+			return;
+		}
+		process.stderr.write(warn$1(`Path not found: ${project.root_path}\n`) + dim$1("  Searching for moved location...\n"));
+		const result = findMovedPath(project.root_path);
+		if (result.found) {
+			const newPath = result.found;
+			const newEncoded = encodeDir(newPath);
+			const ts = now();
+			db.prepare("UPDATE projects SET root_path = ?, encoded_dir = ?, updated_at = ? WHERE id = ?").run(newPath, newEncoded, ts, project.id);
+			process.stderr.write(ok$1(`Project moved: ${shortenPath(project.root_path, 50)}\n`) + dim$1(`  → ${newPath}\n`) + ok$1("Registry updated.\n"));
+			process.stdout.write(newPath + "\n");
+			return;
+		}
+		if (result.ambiguous) {
+			process.stderr.write(warn$1(`Multiple directories named "${basename(project.root_path)}" found:\n`));
+			for (const candidate of result.ambiguous) process.stderr.write(dim$1(`  ${candidate}\n`));
+			process.stderr.write(dim$1(`\n  Disambiguate with: pai projects rebind ${project.slug} <path>\n`));
+			process.exitCode = 1;
+			return;
+		}
+		process.stderr.write(err(`Project "${project.slug}" root_path "${project.root_path}" does not exist on disk\n  and no folder named "${basename(project.root_path)}" was found in scan dirs.\n`) + dim$1(`  Fix with: pai projects rebind ${project.slug} <new-path>\n`));
+		process.exitCode = 1;
+	});
+	program.command("notes [project-slug]", { hidden: true }).description("Markdown session notes — list notes, optionally filtered to a project.").option("--limit <n>", "Maximum number of notes to show", "20").option("--status <status>", "Filter by status: open | completed | compacted").action((projectSlug, opts) => {
+		cmdList(getDb(), projectSlug, opts);
+	}).command("list [project-slug]").description("List markdown session notes (same as: pai notes)").option("--limit <n>", "Maximum number of notes to show", "20").option("--status <status>", "Filter by status: open | completed | compacted").action((projectSlug, opts) => {
+		cmdList(getDb(), projectSlug, opts);
+	});
+	program.command("find <query>", { hidden: true }).description("Search prompt history for matching sessions.").option("-n, --n <count>", "Maximum number of sessions to show", "20").option("--json", "Output as JSON array").action(async (query, opts) => {
+		await cmdFind(query, opts);
+	});
+	program.command("shell-init").description("Emit shell integration code. Add to ~/.zshrc: eval \"$(pai shell-init)\"").action(() => {
+		process.stdout.write(`# PAI shell integration — generated by: pai shell-init
+pai() {
+  if [[ "$1" == "cd" ]]; then
+    local dir=$(command pai cd "$2" 2>/dev/null)
+    if [[ -n "$dir" && -d "$dir" ]]; then
+      builtin cd "$dir"
+      echo "-> $dir"
+    else
+      echo "Project not found: $2" >&2
+      return 1
+    fi
+  elif [[ "$1" == "projects" && "$2" == "cd" ]]; then
+    local dir=$(command pai projects cd "$3" 2>/dev/null)
+    if [[ -n "$dir" && -d "$dir" ]]; then
+      builtin cd "$dir"
+      echo "-> $dir"
+    else
+      echo "Project not found: $3" >&2
+      return 1
+    fi
+  elif [[ $# -eq 0 ]]; then
+    # Bare \`pai\` → interactive picker. fzf draws on /dev/tty; the picker writes
+    # a chosen directory to PAI_PICK_OUT when you press Ctrl-G (cd only), which we
+    # then cd into here (a child process can't change this shell's cwd itself).
+    local __pai_f
+    __pai_f=$(mktemp -t pai-pick 2>/dev/null) || { command pai; return $?; }
+    PAI_PICK_OUT="$__pai_f" command pai
+    local __pai_rc=$?
+    local __pai_dir=""
+    [[ -s "$__pai_f" ]] && __pai_dir=$(cat "$__pai_f")
+    command rm -f "$__pai_f"
+    if [[ -n "$__pai_dir" && -d "$__pai_dir" ]]; then
+      builtin cd "$__pai_dir"
+      echo "-> $__pai_dir"
+    fi
+    return $__pai_rc
+  else
+    command pai "$@"
+  fi
+}
+
+# Print the working directory after an interactive Claude Code session exits.
+# A SessionEnd hook can't do this reliably: Claude Code does not fire SessionEnd
+# on /exit (anthropics/claude-code#17885) and may reap the hook mid-run (#41577).
+# Running it from the shell, after \`claude\` returns, sidesteps both.
+claude() {
+  local __pai_skip=0 __pai_arg
+  for __pai_arg in "$@"; do
+    case "$__pai_arg" in
+      -p|--print) __pai_skip=1 ;;
+    esac
+  done
+  command claude "$@"
+  local __pai_rc=$?
+  if [[ -t 1 && $__pai_skip -eq 0 ]]; then
+    printf '\\n\\033[2m📂 Working directory:\\033[0m %s\\n\\033[2m   cd "%s"\\033[0m\\n' "$PWD" "$PWD"
+  fi
+  return $__pai_rc
+}
+`);
+	});
+	program.command("query [query] [pick]", {
+		isDefault: true,
+		hidden: true
+	}).description("Find and launch a session by topic, name, or UUID.\nNo arg → deduped session listing\nName   → switch live tab, or resume, or start fresh\nUUID   → direct resume via filesystem scan\nTopic  → history search → candidate list → pick #").option("-y, --auto", "Auto-pick #1 without prompting").option("--dry-run", "Print what would happen without launching").option("-n, --n <count>", "Max candidates for history search", "20").option("--all", "Show all entries including cold / zero-session / archived projects").option("--list", "Skip the interactive picker; print the static session listing").action(async (query, pick, opts) => {
+		if (query === void 0 && !opts.list) {
+			await cmdPick(getDb(), {
+				all: opts.all,
+				dryRun: opts.dryRun
+			});
+			return;
+		}
+		const pickN = pick !== void 0 ? parseInt(pick, 10) : void 0;
+		await cmdMain(getDb(), query, pickN, opts);
+	});
+	program.configureOutput({ writeErr: (str) => process.stderr.write(err(str)) });
+	program.exitOverride();
+	return program;
+}
+
+//#endregion
+export { drainStdio as n, buildProgram as t };
+//# sourceMappingURL=program-BnMNFb4O.mjs.map