chore: audit cleanup — bg-shell kill result, diagnostics stderr, /mcp out

Closes four audit findings:

- BackgroundShellStore.kill returns a structured result so callers can
  distinguish killed / not-found / already-exited / signal-failed.
  shell_kill tool surfaces signal-failed as an error so the model
  doesn't assume the process is gone when the OS refused our signal.
- Diagnostics checker errors surface to stderr unconditionally
  instead of only under CODEBASE_DEBUG; a hanging checker is no
  longer a black box for end users running default settings.
- /mcp stub command removed. Sitting on a placeholder that admits
  it's a placeholder feels worse than not having the command at all;
  tracked in docs/TECHNICAL_DEBT.md for when we ship real MCP.
- Stale Phase-N references scrubbed from agent/agent.ts,
  agent/router.ts, tools/registry.ts, skills/loader.ts,
  skills/platform-loader.ts so docs match shipped code.

Author: halfaipg

src/agent/agent.ts

@@ -194,8 +194,8 @@ export function createAgent(opts: CreateAgentOptions = {}): AgentBundle {
 			tools: tools.map((t) => ({ name: t.name, description: t.description })),
 		});
 
-	// MEMORY.md gets concatenated onto the system prompt at agent creation.
-	// Reload-after-save is a Phase 11 polish item.
+	// MEMORY.md gets concatenated onto the system prompt at agent creation;
+	// edits during a session don't take effect until next launch.
 	// Project-instruction file (first of AGENTS.md / CLAUDE.md / CODEX.md /
 	// .cursorrules) gets pinned to the prompt so the agent sees the
 	// project's conventions on every turn. Memory addendum is appended
@@ -314,15 +314,15 @@ export function createAgent(opts: CreateAgentOptions = {}): AgentBundle {
 						});
 					})
 					.catch((err) => {
-						// Diagnostics failures are non-fatal — surface only when the
-						// user opted into debug. Silent before; that buried a real
+						// Diagnostics failures are non-fatal — but always-stderr
+						// instead of debug-only, because the previous behavior
+						// (silent under default settings) hid a real production
 						// bug where a checker hung and the user thought the tool
-						// itself was slow.
-						if (process.env.CODEBASE_DEBUG === "1") {
-							process.stderr.write(
-								`[diagnostics] ${absPath}: ${err instanceof Error ? err.message : String(err)}\n`,
-							);
-						}
+						// itself was slow. Visible to anyone watching the terminal;
+						// the agent keeps running.
+						process.stderr.write(
+							`[diagnostics] ${absPath}: ${err instanceof Error ? err.message : String(err)}\n`,
+						);
 					});
 			}
 			return undefined;

src/agent/router.ts

@@ -29,8 +29,8 @@ export async function routeUserInput(glue: GlueClient, text: string, options: Ro
 	if (intent === "plan") {
 		return { kind: "plan" };
 	}
-	// agent + clarify both go through the main agent for now; clarify-as-soft-hint
-	// could surface a system reminder when we wire steering messages in Phase 11b.
+	// agent + clarify both go through the main agent. A future "clarify" mode
+	// could surface a system reminder via agent.steer() before running the turn.
 	return { kind: "agent" };
 }
 

src/commands/builtins.ts

@@ -1,6 +1,5 @@
 import { execSync } from "node:child_process";
 import { existsSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import { CredentialsStore } from "../auth/credentials.js";
@@ -657,19 +656,6 @@ const projects: Command = {
 	},
 };
 
-const mcp: Command = {
-	name: "mcp",
-	description: "Manage MCP (Model Context Protocol) servers — placeholder until Phase 9 lands.",
-	handler: (_args, ctx) => {
-		const configPath = join(homedir(), ".codebase", "config.json");
-		ctx.emit(
-			"MCP support is on the Phase 9 roadmap; the runtime hasn't shipped it yet.\n" +
-				`When it lands, server config will live at ${configPath} under "mcp_servers".`,
-		);
-		return { handled: true };
-	},
-};
-
 const redo: Command = {
 	name: "redo",
 	aliases: ["retry"],
@@ -729,7 +715,6 @@ export const BUILTIN_COMMANDS: readonly Command[] = [
 	resume,
 	init,
 	projects,
-	mcp,
 	pwd,
 	redo,
 	debug,

src/skills/loader.ts

@@ -6,9 +6,11 @@ import type { Asset, AssetSource, PromptAsset, SkillAsset, TemplateAsset } from
  * call, so loaders can come and go (e.g. PlatformLoader becomes
  * available after the user runs `codebase auth login`).
  *
- * Phase 7 ships LocalLoader (reads ~/.codebase/skills/*.md). Phase 7+
- * ships PlatformLoader (fetches from codebase.foundation/api/cli/...)
- * — see platform-loader.ts for the planned wire format.
+ * Loaders today: BundledLoader (ships with the binary) and
+ * PlatformLoader (fetches from codebase.foundation/api/cli/... when
+ * signed in). LocalLoader (~/.codebase/skills/*.md) is queued.
+ * Resolution order is platform > bundled, matching the "operator
+ * overrides project" precedence the rest of the CLI uses.
  */
 export interface AssetLoader {
 	source: AssetSource;

src/skills/platform-loader.ts

@@ -57,11 +57,10 @@ export interface PlatformLoaderOptions {
  *   not signed in         → returns [] without a network call
  *   network error         → returns the last cached body if any,
  *                           else [] (silent — never crashes a session)
- *   404 (endpoint TBD)    → caches an empty bundle, returns []
- *                           (no warning — the backend half is
- *                           expected to land later, see
- *                           docs/plans/2026-05-09-codebase-cli-
- *                           oauth-server-side.md §3-4)
+ *   404                   → caches an empty bundle, returns []
+ *                           (no warning — the user's tier may not
+ *                           include skills, or the endpoint may not
+ *                           be live yet on a particular deployment)
  *   200                   → caches body + ETag, returns shaped list
  *   304 (ETag match)      → bumps the cache timestamp, returns cached
  */

src/tools/background-shell-store.test.ts

@@ -58,14 +58,14 @@ describe("BackgroundShellStore", () => {
 		expect(final?.endedAt).toBeGreaterThan(0);
 	});
 
-	it("kill() on an unknown id is a no-op", async () => {
-		await expect(store.kill("does-not-exist")).resolves.toBeUndefined();
+	it("kill() on an unknown id reports not-found", async () => {
+		await expect(store.kill("does-not-exist")).resolves.toEqual({ outcome: "not-found" });
 	});
 
-	it("kill() on an already-exited shell is a no-op", async () => {
+	it("kill() on an already-exited shell reports already-exited", async () => {
 		const record = store.spawn("true", process.cwd());
 		await waitUntil(() => (store.get(record.id)?.status !== "running" ? true : undefined));
-		await expect(store.kill(record.id)).resolves.toBeUndefined();
+		await expect(store.kill(record.id)).resolves.toEqual({ outcome: "already-exited" });
 	});
 
 	it("killAllSync() SIGTERMs every running shell", async () => {

src/tools/background-shell-store.ts

@@ -19,6 +19,18 @@ export interface BackgroundShellRecord {
 
 export type BackgroundShellListener = (shells: readonly BackgroundShellRecord[]) => void;
 
+/**
+ * Result returned by `BackgroundShellStore.kill`. The caller needs to know
+ * whether the process actually went down; a previous void return swallowed
+ * the difference between "killed cleanly", "wasn't there", and "tried to
+ * signal but the OS said no" — that hid real bugs in tool callers.
+ */
+export type BackgroundShellKillResult =
+	| { outcome: "killed"; signal: "SIGTERM" | "SIGKILL" }
+	| { outcome: "not-found" }
+	| { outcome: "already-exited" }
+	| { outcome: "signal-failed" };
+
 /**
  * Tracks long-running shell processes that the agent spawned with
  * `shell({ background: true })`. The agent's tool turn returns
@@ -115,31 +127,50 @@ export class BackgroundShellStore {
 	/**
 	 * Terminate a running shell. SIGTERM first; if the process is still
 	 * around after `gracePeriodMs`, SIGKILL. Resolves once the exit
-	 * handler has fired. No-op if the id is unknown or already exited.
+	 * handler has fired.
+	 *
+	 * Returns a structured result so the caller can act on the outcome:
+	 *   - `"killed"`         — process exited after our signal
+	 *   - `"not-found"`      — unknown id
+	 *   - `"already-exited"` — id known but the process had already left
+	 *   - `"signal-failed"`  — both SIGTERM and SIGKILL threw (rare; e.g.
+	 *                          stale PID reuse). Likely already dead.
 	 */
-	async kill(id: string, gracePeriodMs = 2000): Promise<void> {
-		const child = this.processes.get(id);
-		if (!child) return;
+	async kill(id: string, gracePeriodMs = 2000): Promise<BackgroundShellKillResult> {
+		// Order matters: an exited process is dropped from `processes` but
+		// stays in `records`. Check records first so we report
+		// already-exited rather than not-found for shells we still know
+		// about.
 		const record = this.records.get(id);
-		if (!record || record.status !== "running") return;
-		return new Promise<void>((resolve) => {
+		if (!record) return { outcome: "not-found" };
+		if (record.status !== "running") return { outcome: "already-exited" };
+		const child = this.processes.get(id);
+		if (!child) return { outcome: "already-exited" };
+		return new Promise<BackgroundShellKillResult>((resolve) => {
+			let sigtermThrew = false;
+			let sigkillThrew = false;
 			const onExit = () => {
 				clearTimeout(killTimer);
-				resolve();
+				if (sigtermThrew && sigkillThrew) {
+					// Both threw but the process exited anyway — likely it was
+					// already dying. Surface as signal-failed so the caller
+					// can decide whether to retry differently.
+					resolve({ outcome: "signal-failed" });
+					return;
+				}
+				resolve({ outcome: "killed", signal: sigkillThrew ? "SIGTERM" : sigtermThrew ? "SIGKILL" : "SIGTERM" });
 			};
 			child.once("exit", onExit);
 			try {
 				child.kill("SIGTERM");
 			} catch {
-				// Process already gone; the exit handler may have fired
-				// or be about to. Resolve once child emits or after the
-				// timer trips.
+				sigtermThrew = true;
 			}
 			const killTimer = setTimeout(() => {
 				try {
 					child.kill("SIGKILL");
 				} catch {
-					// Same — best effort.
+					sigkillThrew = true;
 				}
 			}, gracePeriodMs);
 		});

src/tools/registry.ts

@@ -28,7 +28,7 @@ import { createWriteFile } from "./write-file.js";
 
 /**
  * Returns every built-in tool, configured against the given context.
- * Phase 2 commits append factories to this list one by one.
+ * Add new tools by importing their factory and appending it here.
  */
 export function buildTools(ctx: ToolContext): AgentTool<any>[] {
 	return [

src/tools/shell-kill.ts

@@ -45,7 +45,19 @@ export function createShellKill(ctx: ToolContext): AgentTool<typeof Params> {
 					],
 				};
 			}
-			await ctx.backgroundShells.kill(params.task_id);
+			const result = await ctx.backgroundShells.kill(params.task_id);
+			if (result.outcome === "signal-failed") {
+				return {
+					details: undefined,
+					content: [
+						{
+							type: "text",
+							text: `Background shell ${params.task_id} did not respond to SIGTERM/SIGKILL — it may already be dead, or the OS refused the signal. Check with shell_output.`,
+						},
+					],
+					isError: true,
+				};
+			}
 			const after = ctx.backgroundShells.get(params.task_id);
 			return {
 				details: undefined,