@sayknow-cli/coding-agent 0.3.12 → 0.3.13

package/scripts/g004-tmux-smoke.ts

@@ -1,100 +1,260 @@
-// G004 real-tmux smoke: exercises forceCloseSkcTmuxSession against LIVE tmux
-// sessions (tmux 3.6a). Proves the wrapper hard-kills SKC-managed live panes
-// (where remove refuses), refuses non-SKC sessions, and enforces session-id
-// matching. Produces durable evidence; not part of the unit suite.
+// G004 real-tmux smoke: exercises forceCloseSkcTmuxSession refusal boundaries
+// against live tmux sessions. Generation-bound successful TERM/verdict/cleanup is
+// covered by the issue evidence harness; this smoke proves incomplete and non-SKC
+// live owners are never hard-killed.
 import assert from "node:assert";
+import { randomUUID } from "node:crypto";
+import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
 
 import {
 	buildSkcTmuxExactOptionTarget,
+	buildSkcTmuxExactSessionTarget,
 	buildSkcTmuxProfileCommands,
 	resolveSkcTmuxCommand,
 } from "../src/skc-runtime/tmux-common";
 import { forceCloseSkcTmuxSession, removeSkcTmuxSession, statusSkcTmuxSession } from "../src/skc-runtime/tmux-sessions";
 
-const tmux = resolveSkcTmuxCommand(process.env);
+const runId = randomUUID().slice(0, 8);
+const suffix = `${process.pid}-${runId}`;
+const privateTmpdir = mkdtempSync(path.join(tmpdir(), "g4-"));
+chmodSync(privateTmpdir, 0o700);
+const socket = `g4-${runId}`;
+const wrapper = path.join(privateTmpdir, "tmux-private.sh");
+const scopeUnit = `skc-g004-${suffix}.scope`;
+const tmuxBootstrapEnv: NodeJS.ProcessEnv = {
+	...process.env,
+	TMUX: "",
+	TMUX_PANE: "",
+	TMUX_TMPDIR: privateTmpdir,
+};
+const tmuxBinary = resolveSkcTmuxCommand(tmuxBootstrapEnv);
+const privateEnv: NodeJS.ProcessEnv = {
+	...tmuxBootstrapEnv,
+	SKC_TMUX_COMMAND: wrapper,
+};
+let scopeRunner: Bun.Subprocess<"ignore", "ignore", "pipe"> | null = null;
 
-function sh(args: string[]): { code: number; err: string } {
-	const r = Bun.spawnSync([tmux, ...args], { stdout: "pipe", stderr: "pipe" });
-	return { code: r.exitCode, err: r.stderr.toString().trim() };
+function shellQuote(value: string): string {
+	return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+function bounded(value: string): string {
+	return value.trim().slice(0, 512) || "no diagnostic";
+}
+
+function sh(args: string[]): { code: number; out: string; err: string } {
+	try {
+		const r = Bun.spawnSync([wrapper, ...args], { env: privateEnv, stdout: "pipe", stderr: "pipe" });
+		return { code: r.exitCode, out: r.stdout.toString().trim(), err: r.stderr.toString().trim() };
+	} catch (error) {
+		return { code: -1, out: "", err: bounded(String(error)) };
+	}
 }
 
 function makeRawSession(name: string): void {
 	const r = sh(["new-session", "-d", "-s", name, "sleep 600"]);
-	if (r.code !== 0) throw new Error(`failed to create tmux session ${name}: ${r.err}`);
+	if (r.code !== 0) throw new Error(`failed to create private tmux session ${name}: ${bounded(r.err)}`);
 }
 
 function tagAsSkc(name: string, sessionId?: string): void {
-	const target = buildSkcTmuxExactOptionTarget(name);
-	for (const cmd of buildSkcTmuxProfileCommands(target, process.env, { sessionId })) {
+	const target = buildSkcTmuxExactOptionTarget(name, { env: privateEnv });
+	for (const cmd of buildSkcTmuxProfileCommands(target, privateEnv, { sessionId })) {
 		const r = sh(cmd.args);
-		if (r.code !== 0) throw new Error(`failed to tag ${name} (${cmd.description}): ${r.err}`);
+		if (r.code !== 0) throw new Error(`failed to tag ${name} (${cmd.description}): ${bounded(r.err)}`);
 	}
 }
 
 function exists(name: string): boolean {
-	return sh(["has-session", "-t", `=${name}`]).code === 0;
+	return sh(["has-session", "-t", buildSkcTmuxExactSessionTarget(name, { env: privateEnv })]).code === 0;
+}
+
+function isPrivateSessionAbsent(name: string): boolean {
+	const result = sh(["has-session", "-t", buildSkcTmuxExactSessionTarget(name, { env: privateEnv })]);
+	return result.code !== 0 && /(?:no server running|can't find session|no sessions)/i.test(result.err);
 }
 
-function killQuiet(name: string): void {
-	sh(["kill-session", "-t", `=${name}`]);
+function privateServerPid(session: string): number | null {
+	const result = sh([
+		"display-message",
+		"-p",
+		"-t",
+		buildSkcTmuxExactOptionTarget(session, { env: privateEnv }),
+		"#{pid}",
+	]);
+	const pid = Number.parseInt(result.out, 10);
+	return result.code === 0 && Number.isSafeInteger(pid) && pid > 0 ? pid : null;
+}
+
+function scopeIsActive(): boolean {
+	return (
+		Bun.spawnSync(["systemctl", "--user", "is-active", "--quiet", scopeUnit], { stdout: "ignore", stderr: "ignore" })
+			.exitCode === 0
+	);
+}
+
+function serverIsProvenInScope(session: string): boolean {
+	const pid = privateServerPid(session);
+	if (pid == null) return false;
+	const controlGroup = Bun.spawnSync(
+		["systemctl", "--user", "show", scopeUnit, "--property=ControlGroup", "--value"],
+		{ stdout: "pipe", stderr: "ignore" },
+	);
+	const group = controlGroup.stdout.toString().trim();
+	if (controlGroup.exitCode !== 0 || !group.startsWith("/")) return false;
+	try {
+		return readFileSync(`/proc/${pid}/cgroup`, "utf8")
+			.split("\n")
+			.some(line => line.endsWith(group));
+	} catch {
+		return false;
+	}
+}
+
+async function makeFirstPrivateSession(name: string): Promise<void> {
+	if (process.platform !== "linux") {
+		makeRawSession(name);
+		return;
+	}
+	try {
+		scopeRunner = Bun.spawn(
+			[
+				"systemd-run",
+				"--user",
+				"--quiet",
+				"--collect",
+				`--setenv=TMUX_TMPDIR=${privateTmpdir}`,
+				"--scope",
+				`--unit=${scopeUnit}`,
+				wrapper,
+				"new-session",
+				"-d",
+				"-s",
+				name,
+				"sleep 600",
+			],
+			{ env: privateEnv, stdout: "ignore", stderr: "pipe" },
+		);
+	} catch (error) {
+		throw new Error(`failed to provision private user scope ${scopeUnit}: ${bounded(String(error))}`);
+	}
+	for (let attempt = 0; attempt < 50; attempt += 1) {
+		if (scopeIsActive() && exists(name) && serverIsProvenInScope(name)) return;
+		await Bun.sleep(50);
+	}
+	throw new Error(`failed to provision a proven private user scope ${scopeUnit}`);
+}
+
+async function cleanupOwnedResources(names: string[]): Promise<void> {
+	const failures: string[] = [];
+	for (const name of names) {
+		const result = sh(["kill-session", "-t", buildSkcTmuxExactSessionTarget(name, { env: privateEnv })]);
+		if (result.code !== 0 && !isPrivateSessionAbsent(name)) failures.push(`session ${name}: ${bounded(result.err)}`);
+	}
+	const server = sh(["kill-server"]);
+	if (server.code !== 0) {
+		const probe = sh(["list-sessions"]);
+		if (!/(?:no server running|failed to connect to server|error connecting to)/i.test(probe.err))
+			failures.push(`server: ${bounded(server.err)}`);
+	}
+	if (process.platform === "linux") {
+		const stop = Bun.spawnSync(["systemctl", "--user", "stop", scopeUnit], { stdout: "pipe", stderr: "pipe" });
+		const state = Bun.spawnSync(
+			["systemctl", "--user", "show", scopeUnit, "--property=ActiveState", "--property=LoadState", "--value"],
+			{ stdout: "pipe", stderr: "pipe" },
+		);
+		const states = state.stdout.toString().trim().split("\n");
+		const scopeAbsent = state.exitCode === 0 && (states.includes("inactive") || states.includes("not-found"));
+		if (stop.exitCode !== 0 && !scopeAbsent) failures.push(`scope stop: ${bounded(stop.stderr.toString())}`);
+		if (!scopeAbsent)
+			failures.push(`scope remains present: ${bounded(state.stderr.toString() || state.stdout.toString())}`);
+		if (scopeRunner != null) {
+			const exited = await Promise.race([scopeRunner.exited.then(() => true), Bun.sleep(3_000).then(() => false)]);
+			if (!exited) {
+				try {
+					scopeRunner.kill();
+				} catch (error) {
+					failures.push(`scope runner: ${bounded(String(error))}`);
+				}
+				const killed = await Promise.race([
+					scopeRunner.exited.then(() => true),
+					Bun.sleep(1_000).then(() => false),
+				]);
+				if (!killed) failures.push("scope runner did not exit after scope cleanup");
+			}
+		}
+	}
+	try {
+		rmSync(privateTmpdir, { recursive: true });
+	} catch (error) {
+		if (existsSync(privateTmpdir)) failures.push(`temporary directory: ${bounded(String(error))}`);
+	}
+	if (existsSync(privateTmpdir)) failures.push("temporary directory remains present");
+	if (failures.length > 0) throw new Error(`g004 cleanup incomplete: ${failures.join("; ")}`);
 }
 
-const suffix = `${process.pid}-${Date.now()}`;
 const live = `skc_g004live_${suffix}`;
 const raw = `g004raw_${suffix}`;
 const mism = `skc_g004mism_${suffix}`;
-const cleanup: string[] = [live, raw, mism];
+const cleanup = [live, raw, mism];
 
 try {
-	// 1. SKC-managed LIVE session: remove refuses, force-close hard-kills.
-	makeRawSession(live);
+	writeFileSync(wrapper, `#!/bin/sh\nexec ${shellQuote(tmuxBinary)} -L ${shellQuote(socket)} "$@"\n`, { mode: 0o700 });
+	chmodSync(wrapper, 0o700);
+
+	// 1. Incompletely tagged LIVE session: remove refuses and force-close fails closed.
+	await makeFirstPrivateSession(live);
 	tagAsSkc(live, "sess-g004");
-	const status = statusSkcTmuxSession(live);
+	const status = statusSkcTmuxSession(live, privateEnv);
 	assert.equal(status.profile, "1", "session must be recognized as SKC-managed");
 	assert.ok(status.panePids.length > 0, "session must have a live pane (sleep)");
-	console.log(`[g004] live SKC session up: ${live} panePids=${status.panePids.length}`);
+	process.stdout.write(`[g004] incomplete SKC session up: ${live} panePids=${status.panePids.length}\n`);
 
 	let removeRefused = false;
 	try {
-		removeSkcTmuxSession(live);
+		removeSkcTmuxSession(live, privateEnv);
 	} catch (e) {
 		removeRefused = /skc_tmux_session_live/.test(String(e));
 	}
 	assert.ok(removeRefused, "removeSkcTmuxSession must REFUSE a live pane");
-	console.log("[g004] remove refused live session (expected)");
 
-	const closed = forceCloseSkcTmuxSession(live, process.env, "sess-g004");
-	assert.equal(closed.name, live);
-	assert.ok(!exists(live), "force-close must hard-kill the live SKC session");
-	console.log("[g004] force-close hard-killed the live SKC session (id-matched)");
+	let ownerUnverifiable = false;
+	try {
+		await forceCloseSkcTmuxSession(live, privateEnv, "sess-g004");
+	} catch (e) {
+		ownerUnverifiable = /skc_tmux_owner_unverifiable/.test(String(e));
+	}
+	assert.ok(ownerUnverifiable, "force-close must refuse incomplete owner provenance");
+	assert.ok(exists(live), "incompletely tagged session must be left untouched");
+	process.stdout.write("[g004] force-close refused incomplete owner provenance (expected)\n");
 
 	// 2. Non-SKC (untagged) session: force-close must refuse.
 	makeRawSession(raw);
 	let notManaged = false;
 	try {
-		forceCloseSkcTmuxSession(raw, process.env);
+		await forceCloseSkcTmuxSession(raw, privateEnv);
 	} catch (e) {
-		notManaged = /skc_tmux_session_(not_managed|not_found)/.test(String(e));
+		notManaged = /skc_tmux_session_(not_managed|not_found|untagged)/.test(String(e));
 	}
 	assert.ok(notManaged, "force-close must refuse a non-SKC tmux session");
 	assert.ok(exists(raw), "non-SKC session must be left untouched");
-	killQuiet(raw);
-	console.log("[g004] force-close refused + preserved non-SKC session (expected)");
+	process.stdout.write("[g004] force-close refused + preserved non-SKC session (expected)\n");
 
 	// 3. SKC session with a MISMATCHED expected session id: must refuse.
 	makeRawSession(mism);
 	tagAsSkc(mism, "sess-real");
 	let idMismatch = false;
 	try {
-		forceCloseSkcTmuxSession(mism, process.env, "sess-WRONG");
+		await forceCloseSkcTmuxSession(mism, privateEnv, "sess-WRONG");
 	} catch (e) {
 		idMismatch = /skc_tmux_session_id_mismatch/.test(String(e));
 	}
 	assert.ok(idMismatch, "force-close must refuse on session-id mismatch");
 	assert.ok(exists(mism), "mismatched session must be left untouched");
-	console.log("[g004] force-close refused on session-id mismatch (expected)");
-
-	console.log("[g004] PASS: forceCloseSkcTmuxSession verified against live tmux");
+	process.stdout.write("[g004] force-close refused on session-id mismatch (expected)\n");
 } finally {
-	for (const name of cleanup) killQuiet(name);
+	await cleanupOwnedResources(cleanup);
 }
+
+process.stdout.write("[g004] PASS: forceCloseSkcTmuxSession refusal boundaries verified against live tmux\n");

package/scripts/generate-docs-index.ts

@@ -40,6 +40,8 @@ if (docsDir === undefined) {
 const glob = new Glob("**/*.md");
 const entries: string[] = [];
 for await (const relativePath of glob.scan(docsDir)) {
+	// Maintainer-only doc: never embed it in the shipped docs index.
+	if (relativePath.endsWith("FORK_MAINTENANCE.md")) continue;
 	entries.push(relativePath.split(path.sep).join("/"));
 }
 entries.sort();

package/src/cli/daemon-cli.ts

@@ -12,8 +12,14 @@ import type {
 	DaemonKind,
 	DaemonOperationOptions,
 	DaemonOperationResult,
-	DaemonStatus,
 } from "../daemon/control-types";
+import {
+	DAEMON_ACTION_TOKENS,
+	DAEMON_EXIT,
+	formatDaemonResult,
+	formatDaemonStatus,
+	resolveDaemonAction,
+} from "../daemon/operator-contract";
 
 export type DaemonCliAction = "list" | "status" | "stop" | "reload";
 
@@ -26,6 +32,8 @@ export interface DaemonCommandArgs {
 	gracefulTimeoutMs?: number;
 	killTimeoutMs?: number;
 	spawnIfStopped?: boolean;
+	/** Show runtime detail and the full roots list in human output. */
+	verbose?: boolean;
 }
 
 export interface DaemonCommandDeps {
@@ -33,18 +41,20 @@ export interface DaemonCommandDeps {
 	controllers?: BuiltInDaemonController[];
 }
 
-const KNOWN_ACTIONS: DaemonCliAction[] = ["list", "status", "stop", "reload"];
 const KNOWN_KINDS: DaemonKind[] = ["telegram"];
 
 export function parseDaemonArgs(argv: string[]): DaemonCommandArgs | undefined {
 	if (argv.length === 0 || argv[0] !== "daemon") return undefined;
 	const rest = argv.slice(1);
-	const action = (KNOWN_ACTIONS as string[]).includes(rest[0] ?? "") ? (rest[0] as DaemonCliAction) : "status";
-	const positional = (KNOWN_ACTIONS as string[]).includes(rest[0] ?? "") ? rest.slice(1) : rest;
+	const resolved = resolveDaemonAction(rest[0]);
+	const isActionToken = (DAEMON_ACTION_TOKENS as readonly string[]).includes(rest[0] ?? "");
+	const action = (resolved ?? "status") as DaemonCliAction;
+	const positional = isActionToken ? rest.slice(1) : rest;
 	const kinds: DaemonKind[] = [];
 	let all = false;
 	let json = false;
 	let force = false;
+	let verbose = false;
 	let gracefulTimeoutMs: number | undefined;
 	let killTimeoutMs: number | undefined;
 	let spawnIfStopped: boolean | undefined;
@@ -53,34 +63,14 @@ export function parseDaemonArgs(argv: string[]): DaemonCommandArgs | undefined {
 		if (arg === "--all") all = true;
 		else if (arg === "--json") json = true;
 		else if (arg === "--force") force = true;
+		else if (arg === "--verbose" || arg === "-v") verbose = true;
 		else if (arg === "--spawn-if-stopped") spawnIfStopped = true;
 		else if (arg === "--graceful-timeout-ms") gracefulTimeoutMs = Number.parseInt(positional[++i], 10);
 		else if (arg === "--kill-timeout-ms") killTimeoutMs = Number.parseInt(positional[++i], 10);
 		else if (!arg.startsWith("--") && (KNOWN_KINDS as string[]).includes(arg)) kinds.push(arg as DaemonKind);
 	}
-	return { action, kinds, all, json, force, gracefulTimeoutMs, killTimeoutMs, spawnIfStopped };
+	return { action, kinds, all, json, force, verbose, gracefulTimeoutMs, killTimeoutMs, spawnIfStopped };
 }
-
-function formatStatus(status: DaemonStatus): string {
-	const parts = [
-		`${status.kind}: ${status.health}`,
-		status.configured ? undefined : "(not configured)",
-		status.pid !== undefined ? `pid=${status.pid}` : undefined,
-		status.ownerId ? `owner=${status.ownerId}` : undefined,
-		status.rootCount !== undefined ? `roots=${status.rootCount}` : undefined,
-		`mode=${status.runtime.mode}`,
-	].filter(Boolean);
-	let line = parts.join(" ");
-	if (status.runtime.warning) line += `\n  warning: ${status.runtime.warning}`;
-	return line;
-}
-
-function formatResult(result: DaemonOperationResult): string {
-	const head = `${result.kind} ${result.action}: ${result.ok ? "ok" : "failed"} — ${result.message}`;
-	const warnings = result.warnings.map(w => `\n  warning: ${w}`).join("");
-	return head + warnings;
-}
-
 export async function runDaemonCommand(cmd: DaemonCommandArgs, deps: DaemonCommandDeps = {}): Promise<void> {
 	const unknownKinds = cmd.kinds.filter(kind => !(KNOWN_KINDS as string[]).includes(kind));
 	if (unknownKinds.length > 0) {
@@ -98,7 +88,7 @@ export async function runDaemonCommand(cmd: DaemonCommandArgs, deps: DaemonComma
 		if (cmd.json) {
 			process.stdout.write(`${JSON.stringify(statuses, null, 2)}\n`);
 		} else {
-			process.stdout.write(`${statuses.map(formatStatus).join("\n")}\n`);
+			process.stdout.write(`${statuses.map(s => formatDaemonStatus(s, { verbose: cmd.verbose })).join("\n")}\n`);
 		}
 		return;
 	}
@@ -116,7 +106,7 @@ export async function runDaemonCommand(cmd: DaemonCommandArgs, deps: DaemonComma
 	if (cmd.json) {
 		process.stdout.write(`${JSON.stringify(results, null, 2)}\n`);
 	} else {
-		process.stdout.write(`${results.map(formatResult).join("\n")}\n`);
+		process.stdout.write(`${results.map(formatDaemonResult).join("\n")}\n`);
 	}
-	if (results.some(r => !r.ok)) process.exitCode = 1;
+	if (results.some(r => !r.ok)) process.exitCode = DAEMON_EXIT.failure;
 }

package/src/cli/malloc-env-guard.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from "bun:test";
+import {
+	buildMallocReexecArgv,
+	formatMallocEnvNotice,
+	hasMacOSMallocEnv,
+	MACOS_MALLOC_ENV_VARS,
+	MALLOC_ENV_REEXEC_GUARD,
+	shouldReexecForMacOSMallocEnv,
+} from "./malloc-env-guard";
+
+describe("hasMacOSMallocEnv", () => {
+	it("detects MallocStackLogging", () => {
+		expect(hasMacOSMallocEnv({ MallocStackLogging: "0" })).toBe(true);
+	});
+
+	it("detects MallocStackLoggingNoCompact", () => {
+		expect(hasMacOSMallocEnv({ MallocStackLoggingNoCompact: "1" })).toBe(true);
+	});
+
+	it("is false when neither var is present", () => {
+		expect(hasMacOSMallocEnv({ PATH: "/usr/bin", HOME: "/home/x" })).toBe(false);
+	});
+
+	it("is false for an empty environment", () => {
+		expect(hasMacOSMallocEnv({})).toBe(false);
+	});
+});
+
+describe("shouldReexecForMacOSMallocEnv", () => {
+	it("is true on darwin with a malloc var and no loop guard", () => {
+		expect(shouldReexecForMacOSMallocEnv({ MallocStackLogging: "0" }, "darwin")).toBe(true);
+	});
+
+	it("is false off darwin even when a malloc var is present", () => {
+		expect(shouldReexecForMacOSMallocEnv({ MallocStackLogging: "0" }, "linux")).toBe(false);
+		expect(shouldReexecForMacOSMallocEnv({ MallocStackLogging: "0" }, "win32")).toBe(false);
+	});
+
+	it("is false when the loop guard is already set (already re-exec'd)", () => {
+		expect(shouldReexecForMacOSMallocEnv({ MallocStackLogging: "0", [MALLOC_ENV_REEXEC_GUARD]: "1" }, "darwin")).toBe(
+			false,
+		);
+	});
+
+	it("is false on darwin when no malloc var is present", () => {
+		expect(shouldReexecForMacOSMallocEnv({ PATH: "/usr/bin" }, "darwin")).toBe(false);
+	});
+});
+
+describe("buildMallocReexecArgv", () => {
+	it("drops the embedded virtual entry for a POSIX compiled binary", () => {
+		expect(buildMallocReexecArgv(["/exe", "/$bunfs/root/cli", "run", "--flag"], "/exe")).toEqual([
+			"/exe",
+			"run",
+			"--flag",
+		]);
+	});
+
+	it("drops the embedded virtual entry for a Windows compiled binary", () => {
+		expect(buildMallocReexecArgv(["C:/exe.exe", "B:\\~BUN\\root\\cli", "run"], "C:/exe.exe")).toEqual([
+			"C:/exe.exe",
+			"run",
+		]);
+	});
+
+	it("drops the percent-encoded embedded virtual entry", () => {
+		expect(buildMallocReexecArgv(["/exe", "B:\\%7EBUN\\root\\cli", "run"], "/exe")).toEqual(["/exe", "run"]);
+	});
+
+	it("keeps the on-disk script for a source/dev-link run", () => {
+		expect(
+			buildMallocReexecArgv(["/usr/bin/bun", "/repo/packages/coding-agent/src/cli.ts", "run", "-x"], "/usr/bin/bun"),
+		).toEqual(["/usr/bin/bun", "/repo/packages/coding-agent/src/cli.ts", "run", "-x"]);
+	});
+
+	it("handles a source run with no user args", () => {
+		expect(buildMallocReexecArgv(["/usr/bin/bun", "/repo/cli.ts"], "/usr/bin/bun")).toEqual([
+			"/usr/bin/bun",
+			"/repo/cli.ts",
+		]);
+	});
+});
+
+describe("formatMallocEnvNotice", () => {
+	it("names both env vars and the permanent launchctl fix", () => {
+		const notice = formatMallocEnvNotice();
+		for (const name of MACOS_MALLOC_ENV_VARS) {
+			expect(notice).toContain(name);
+		}
+		expect(notice).toContain("launchctl unsetenv MallocStackLogging");
+		expect(notice).toContain("launchctl unsetenv MallocStackLoggingNoCompact");
+		expect(notice.endsWith("\n")).toBe(true);
+	});
+});
+
+describe("module constants", () => {
+	it("exposes exactly the two macOS malloc env vars", () => {
+		expect([...MACOS_MALLOC_ENV_VARS]).toEqual(["MallocStackLogging", "MallocStackLoggingNoCompact"]);
+	});
+
+	it("uses a namespaced loop-guard variable", () => {
+		expect(MALLOC_ENV_REEXEC_GUARD).toBe("SKC_MALLOC_ENV_REEXEC");
+	});
+});

package/src/cli/malloc-env-guard.ts

@@ -0,0 +1,149 @@
+/**
+ * macOS malloc-stack-logging launch boundary.
+ *
+ * On macOS, an inherited `MallocStackLogging` / `MallocStackLoggingNoCompact`
+ * environment variable (from an Xcode scheme's malloc diagnostics, Instruments,
+ * `launchctl setenv`, or a debug-attached shell) makes libmalloc print
+ *
+ *   MallocStackLogging: can't turn off malloc stack logging because it was not enabled.
+ *
+ * to the stderr of every TTY-attached process. Bun snapshots the spawn-default
+ * environment at process startup — before any JS runs — so neither
+ * `delete process.env.X` nor a real libc `unsetenv()` cleans the environment
+ * that children inherit by default (verified on Bun 1.3.14). Inside the TUI,
+ * every PTY-spawned child then repeats the warning straight into the rendered
+ * frame and corrupts the display.
+ *
+ * The only way to hand children a clean startup snapshot is to start the primary
+ * process with a clean environment. This module re-execs the exact invocation
+ * once (darwin-only) with a `filterProcessEnv`-scrubbed environment and a
+ * `SKC_MALLOC_ENV_REEXEC` loop guard, before any fast path or subprocess spawn.
+ * The re-exec'd process — and therefore every downstream lane: `Bun.spawn`
+ * defaults, `node:child_process`, the native PTY, the tmux owner, plugin
+ * installs, and subagents — starts from a clean snapshot.
+ *
+ * The initial contaminated process's own libmalloc line is emitted by libc
+ * before any JS runs and cannot be suppressed from inside the process; it
+ * appears at most once per launch. A one-time actionable notice is written to
+ * interactive stderr (outside the rendered frame) pointing at the permanent
+ * `launchctl unsetenv` fix.
+ */
+
+import { filterProcessEnv } from "@sayknow-cli/utils/env";
+import type { Subprocess } from "bun";
+
+/** Env vars that make macOS libmalloc write to a TTY when inherited. */
+export const MACOS_MALLOC_ENV_VARS = ["MallocStackLogging", "MallocStackLoggingNoCompact"] as const;
+
+/** Loop guard set on the scrubbed re-exec so it never re-execs itself again. */
+export const MALLOC_ENV_REEXEC_GUARD = "SKC_MALLOC_ENV_REEXEC";
+
+/** True when at least one macOS malloc-stack-logging var is present in `env`. */
+export function hasMacOSMallocEnv(env: Record<string, string | undefined>): boolean {
+	return MACOS_MALLOC_ENV_VARS.some(name => env[name] !== undefined);
+}
+
+/**
+ * True iff we must re-exec to escape a contaminated macOS startup snapshot:
+ * darwin, not already inside the scrubbed re-exec, and at least one malloc var
+ * present. Off darwin or on the re-exec'd child this is always false, so the
+ * common launch path pays only two cheap lookups.
+ */
+export function shouldReexecForMacOSMallocEnv(
+	env: Record<string, string | undefined>,
+	platform: NodeJS.Platform,
+): boolean {
+	return platform === "darwin" && env[MALLOC_ENV_REEXEC_GUARD] === undefined && hasMacOSMallocEnv(env);
+}
+
+/**
+ * Reconstruct the argv that re-runs the exact same program image.
+ *
+ * - Compiled single-file executable: argv[1] is the embedded virtual entry
+ *   (`/$bunfs/…` on POSIX, `B:\~BUN\…` on Windows), which must be dropped — the
+ *   executable re-embeds its own entry. Re-run `[exe, ...userArgs]`.
+ * - Source / dev-link run: argv[1] is the on-disk script that must be passed
+ *   back to the interpreter. Re-run `[interpreter, script, ...userArgs]`.
+ */
+export function buildMallocReexecArgv(argv: readonly string[], execPath: string): string[] {
+	const entry = argv[1];
+	const isCompiledEntry =
+		typeof entry === "string" && (entry.includes("/$bunfs/") || entry.includes("~BUN") || entry.includes("%7EBUN"));
+	if (isCompiledEntry) {
+		return [execPath, ...argv.slice(2)];
+	}
+	return [execPath, ...argv.slice(1)];
+}
+
+/** One-time, human-actionable notice pointing at the permanent environment fix. */
+export function formatMallocEnvNotice(): string {
+	return (
+		"sayknow-cli: detected macOS malloc-stack-logging environment variables " +
+		"(MallocStackLogging / MallocStackLoggingNoCompact); relaunching once with a " +
+		"scrubbed environment so they do not flood the terminal.\n" +
+		"  Remove them permanently with:\n" +
+		"    unset MallocStackLogging MallocStackLoggingNoCompact\n" +
+		"    launchctl unsetenv MallocStackLogging\n" +
+		"    launchctl unsetenv MallocStackLoggingNoCompact\n"
+	);
+}
+
+/**
+ * Re-exec the current process once with a scrubbed environment and propagate the
+ * child's exit code. Callers MUST gate this behind `shouldReexecForMacOSMallocEnv`.
+ *
+ * Returns the child exit code, or `null` if the re-exec could not be spawned (in
+ * which case the caller falls back to running in the current, contaminated
+ * process — degraded but functional; the native PTY boundary and
+ * `filterProcessEnv` still keep managed children clean).
+ */
+export async function reexecWithScrubbedMallocEnv(): Promise<number | null> {
+	const cleanEnv = filterProcessEnv(process.env);
+	cleanEnv[MALLOC_ENV_REEXEC_GUARD] = "1";
+	const childArgv = buildMallocReexecArgv(process.argv, process.execPath);
+
+	// Surface the diagnostic exactly once, before the TUI enters its alternate
+	// screen, and only on an interactive terminal (piped/CI stderr is not a TTY,
+	// so libmalloc stays silent there and the notice would just be noise).
+	if (process.stderr.isTTY) {
+		process.stderr.write(formatMallocEnvNotice());
+	}
+
+	let child: Subprocess;
+	try {
+		child = Bun.spawn(childArgv, {
+			env: cleanEnv,
+			stdin: "inherit",
+			stdout: "inherit",
+			stderr: "inherit",
+		});
+	} catch {
+		return null;
+	}
+
+	// Keep the wrapper alive on SIGINT/SIGTERM so it reaps the child and
+	// propagates its exit code instead of dying first, and forward the signal so
+	// the scrubbed child terminates too. Interactive Ctrl-C is delivered to the
+	// whole foreground process group (and the TUI's raw mode turns it into a 0x03
+	// byte, not a signal, anyway), so re-forwarding is a harmless no-op once the
+	// child is already handling or exiting. Targeted delivery — `kill -INT <pid>`
+	// or a supervisor's `child.kill("SIGINT")` — reaches only the wrapper, so
+	// without forwarding the launch would be uncancellable outside a terminal.
+	const forwardSignal = (signal: NodeJS.Signals) => () => {
+		try {
+			child.kill(signal);
+		} catch {
+			// Child already gone; nothing to forward.
+		}
+	};
+	const onSigint = forwardSignal("SIGINT");
+	const onSigterm = forwardSignal("SIGTERM");
+	process.on("SIGINT", onSigint);
+	process.on("SIGTERM", onSigterm);
+	try {
+		return await child.exited;
+	} finally {
+		process.off("SIGINT", onSigint);
+		process.off("SIGTERM", onSigterm);
+	}
+}