@sayknow-cli/coding-agent 0.4.6 → 0.5.0

package/src/cli.ts

@@ -5,9 +5,17 @@
  * lightweight CLI runner from pi-utils.
  */
 import "@sayknow-cli/utils/postmortem";
+import { THINKING_EFFORTS } from "@sayknow-cli/ai";
 import { Args, type CliConfig, Command, type CommandEntry, Flags, run } from "@sayknow-cli/utils/cli";
 import { APP_NAME, formatBunRuntimeError, MIN_BUN_VERSION, VERSION } from "@sayknow-cli/utils/dirs";
+import { loadNative as loadNativeBindings } from "../../natives/native/loader-state.js";
 import { runFixtureReport } from "./cli/fixture-report";
+import { admitManagedOwnerBeforeCli, completeManagedOwnerRecovery } from "./skc-runtime/managed-owner-admission";
+import {
+	isManagedOwnerSupervisorArgv,
+	MANAGED_OWNER_CHILD_TOKEN_ENV,
+	runManagedOwnerSupervisor,
+} from "./skc-runtime/managed-owner-supervisor";
 import { isTmuxOwnerIsolationCliArgv, runTmuxOwnerIsolationCliFromStdin } from "./skc-runtime/tmux-owner-isolation-cli";
 import { smokeTestTabWorker } from "./tools/browser/tab-worker-smoke";
 
@@ -56,6 +64,7 @@ export const commands: CommandEntry[] = [
 	{ name: "migrate", load: () => import("./commands/migrate").then(m => m.default) },
 	{ name: "rlm", load: () => import("./commands/rlm").then(m => m.default) },
 	{ name: "update", load: () => import("./commands/update").then(m => m.default) },
+	{ name: "read", load: () => import("./commands/read").then(m => m.default) },
 	{ name: "plugin", load: () => import("./commands/plugin").then(m => m.default) },
 	{ name: "completion", load: () => import("./commands/completion").then(m => m.default) },
 	{ name: "launch", load: () => import("./commands/launch").then(m => m.default) },
@@ -112,6 +121,36 @@ Options:
 `);
 }
 
+export function interactiveBootstrapText(
+	argv: readonly string[],
+	stdinIsTTY = process.stdin.isTTY,
+	stdoutIsTTY = process.stdout.isTTY,
+): string | undefined {
+	if (!stdinIsTTY || !stdoutIsTTY || argv[0] !== "launch") return undefined;
+	for (let index = 1; index < argv.length; index++) {
+		const arg = argv[index];
+		if (
+			arg === "--print" ||
+			arg?.startsWith("--print=") ||
+			arg === "-p" ||
+			arg === "--export" ||
+			arg?.startsWith("--export=") ||
+			arg === "--list-models" ||
+			arg?.startsWith("--list-models=") ||
+			arg === "--mode" ||
+			arg?.startsWith("--mode=") ||
+			arg === "--help" ||
+			arg?.startsWith("--help=") ||
+			arg === "-h" ||
+			arg === "--version" ||
+			arg?.startsWith("--version=") ||
+			arg === "-v"
+		)
+			return undefined;
+	}
+	return "\u001b[?25h\u001b[38;5;45mSKC\u001b[0m warming workspace\r\n\r\n> ";
+}
+
 function isNotifyDaemonInternalFastPath(argv: string[]): boolean {
 	return argv[0] === "notify" && argv[1] === "daemon-internal";
 }
@@ -138,6 +177,46 @@ async function runChatDaemonInternalFastPath(argv: string[]): Promise<void> {
 	await runChatDaemonInternal(action === "discord-internal" ? "discord" : "slack", argv.slice(2));
 }
 
+type MemoryGuardNativeSmokeLoad = () => Record<string, unknown>;
+type WindowsJobMemoryProbeResult = Record<string, unknown> & { kind: string };
+type MemoryGuardNativeSmokeReceipt = {
+	api: "memory_guard_windows_job_probe_v1";
+	source: "pi_natives";
+	result: WindowsJobMemoryProbeResult;
+};
+
+export function isMemoryGuardNativeSmokeFastPath(argv: readonly string[]): boolean {
+	return (
+		argv.length === 3 && argv[0] === "internal" && argv[1] === "memory-guard-native-smoke" && argv[2] === "--json"
+	);
+}
+
+function parseWindowsJobMemoryProbeResult(value: unknown): WindowsJobMemoryProbeResult {
+	if (!value || typeof value !== "object") {
+		throw new Error("memory-guard-native-smoke: native probe returned a non-object result");
+	}
+	const result = value as Record<string, unknown>;
+	if (typeof result.kind !== "string") {
+		throw new Error("memory-guard-native-smoke: native probe result is missing a string kind tag");
+	}
+	return result as WindowsJobMemoryProbeResult;
+}
+
+export function runMemoryGuardNativeSmokeFastPath(
+	options: { loadNative?: MemoryGuardNativeSmokeLoad; writeStdout?: (text: string) => void } = {},
+): void {
+	const probe = (options.loadNative ?? loadNativeBindings)().probeWindowsJobMemory;
+	if (typeof probe !== "function") {
+		throw new Error("memory-guard-native-smoke: probeWindowsJobMemory export missing from native addon");
+	}
+	const receipt: MemoryGuardNativeSmokeReceipt = {
+		api: "memory_guard_windows_job_probe_v1",
+		source: "pi_natives",
+		result: parseWindowsJobMemoryProbeResult((probe as () => unknown)()),
+	};
+	(options.writeStdout ?? (text => process.stdout.write(text)))(`${JSON.stringify(receipt)}\n`);
+}
+
 function rootFixtureArg(argv: string[]): { present: boolean; id: string | undefined } {
 	for (let i = 0; i < argv.length; i++) {
 		const arg = argv[i];
@@ -208,8 +287,8 @@ export class RootHelpCommand extends Command {
 		tmux: Flags.boolean({ description: "Launch interactive startup inside tmux" }),
 		tools: Flags.string({ description: "Comma-separated list of tools to enable (default: all)" }),
 		thinking: Flags.string({
-			description: "Set thinking level: ultra, high, medium, low",
-			options: ["ultra", "high", "medium", "low"],
+			description: `Set thinking level: ${THINKING_EFFORTS.join(", ")}`,
+			options: [...THINKING_EFFORTS],
 		}),
 		hook: Flags.string({ description: "Load a hook/extension file (can be used multiple times)", multiple: true }),
 		extension: Flags.string({
@@ -287,9 +366,34 @@ export function normalizeResumeAlias(argv: readonly string[]): string[] {
 	return argv.length === 1 && argv[0] === "resume" ? ["--resume"] : [...argv];
 }
 
+function routeLegacyRootArgv(argv: readonly string[]): string[] | undefined {
+	if (argv[0] === "coordinator-mcp") return ["mcp-serve", "coordinator", ...argv.slice(1)];
+	if (argv[0] !== "--team") return undefined;
+	const sizeValues: string[] = [];
+	const remaining: string[] = [];
+	for (let index = 1; index < argv.length; index++) {
+		const arg = argv[index] ?? "";
+		if (arg === "--team-size") {
+			sizeValues.push(argv[index + 1] ?? "");
+			index++;
+		} else if (arg.startsWith("--team-size=")) {
+			sizeValues.push(arg.slice("--team-size=".length));
+		} else {
+			remaining.push(arg);
+		}
+	}
+	const size = sizeValues[0];
+	if (sizeValues.length !== 1 || !size || !/^[1-9]\d*$/.test(size)) {
+		return ["team", "0", "invalid legacy --team-size"];
+	}
+	return ["team", size, ...remaining];
+}
+
 /** Apply the same default-launch routing used by runCli after root fast paths. */
 export function routeRootArgv(argv: readonly string[]): string[] {
 	const normalizedArgv = normalizeResumeAlias(argv);
+	const legacyArgv = routeLegacyRootArgv(normalizedArgv);
+	if (legacyArgv) return legacyArgv;
 	const first = normalizedArgv[0];
 	return first === "--help" || first === "-h" || first === "--version" || first === "-v" || first === "help"
 		? normalizedArgv
@@ -321,10 +425,26 @@ export async function runCli(argv: string[]): Promise<void> {
 		}
 		// Re-exec could not be spawned; fall through and run in this process.
 	}
+	if (isMemoryGuardNativeSmokeFastPath(argv)) {
+		runMemoryGuardNativeSmokeFastPath();
+		return;
+	}
 	if (isTmuxOwnerIsolationCliArgv(argv)) {
 		await runTmuxOwnerIsolationCliFromStdin();
 		return;
 	}
+	if (isManagedOwnerSupervisorArgv(argv)) {
+		await runManagedOwnerSupervisor();
+		return;
+	}
+	if (process.env[MANAGED_OWNER_CHILD_TOKEN_ENV] !== undefined) {
+		const admission = await admitManagedOwnerBeforeCli();
+		if (admission.kind === "blocked") return;
+		if (admission.kind === "recovery") {
+			await completeManagedOwnerRecovery(admission.context);
+			return;
+		}
+	}
 	if (isNotifyDaemonInternalFastPath(argv)) {
 		await runNotifyDaemonInternalFastPath(argv);
 		return;
@@ -348,11 +468,9 @@ export async function runCli(argv: string[]): Promise<void> {
 		process.exitCode = await runFixtureReport(id);
 		return;
 	}
-	if (isStatsHelpFastPath(argv)) {
-		showStatsFastHelp();
-		return;
-	}
-	if (hasRootHelpFlag(argv)) {
+	const normalizedArgv = normalizeResumeAlias(argv);
+	const legacyArgv = routeLegacyRootArgv(normalizedArgv);
+	if (!legacyArgv && hasRootHelpFlag(normalizedArgv)) {
 		const { renderRootHelp } = await import("@sayknow-cli/utils/cli");
 		const { getExtraHelpText } = await import("./cli/fast-help");
 		renderRootHelp({ bin: APP_NAME, version: VERSION, commands: new Map([["launch", RootHelpCommand]]) });
@@ -362,14 +480,18 @@ export async function runCli(argv: string[]): Promise<void> {
 		}
 		return;
 	}
-	if (hasRootVersionFlag(argv)) {
+	if (!legacyArgv && hasRootVersionFlag(normalizedArgv)) {
 		process.stdout.write(`${APP_NAME}/${VERSION}\n`);
 		return;
 	}
+	const runArgv = legacyArgv ?? routeRootArgv(normalizedArgv);
+	if (isStatsHelpFastPath(runArgv)) {
+		showStatsFastHelp();
+		return;
+	}
+	const bootstrap = interactiveBootstrapText(runArgv);
+	if (bootstrap) process.stdout.write(bootstrap);
 	await installRuntimeGlobals();
-	// --help and --version are handled by run() directly, don't rewrite those.
-	// Everything else that isn't a known subcommand routes to "launch".
-	const runArgv = routeRootArgv(argv);
 	return run({ bin: APP_NAME, version: VERSION, argv: runArgv, commands, help: showHelp });
 }
 

package/src/commands/daemon.ts

@@ -1,7 +1,7 @@
 /**
  * Manage SKC background daemons (status/list/stop/reload).
  */
-import { Args, Command, Flags } from "@sayknow-cli/utils/cli";
+import { Args, CliParseError, Command, Flags } from "@sayknow-cli/utils/cli";
 import {
 	type DaemonCommandAction,
 	type DaemonCommandArgs,
@@ -15,6 +15,18 @@ import { runSdkSessionCli } from "../sdk/cli";
 
 const ACTIONS = [...DAEMON_ACTION_TOKENS, "discord-internal", "slack-internal", "session"] as const;
 
+function parsePositiveTimeout(raw: string | undefined, flagName: string): number | undefined {
+	if (raw === undefined) return undefined;
+	if (!/^[0-9]+$/.test(raw)) {
+		throw new CliParseError(`Expected ${flagName} to be a positive safe integer, got "${raw}"`);
+	}
+	const value = Number(raw);
+	if (!Number.isSafeInteger(value) || value <= 0) {
+		throw new CliParseError(`Expected ${flagName} to be a positive safe integer, got "${raw}"`);
+	}
+	return value;
+}
+
 export default class Daemon extends Command {
 	static description =
 		"Manage SKC background daemons and SDK sessions. Routine use: `skc daemon status` to check, `skc daemon restart` to reload (spawns one if none is running). `stop`/`list` and the escalation flags below are advanced primitives.";
@@ -41,8 +53,8 @@ export default class Daemon extends Command {
 		all: Flags.boolean({ description: "Target all registered daemon kinds" }),
 		json: Flags.boolean({ description: "Emit JSON output" }),
 		force: Flags.boolean({ description: "Allow hard-kill escalation when graceful stop times out" }),
-		"graceful-timeout-ms": Flags.integer({ description: "Cooperative stop timeout before escalation" }),
-		"kill-timeout-ms": Flags.integer({ description: "Wait for old pid death after SIGKILL" }),
+		"graceful-timeout-ms": Flags.string({ description: "Cooperative stop timeout before escalation" }),
+		"kill-timeout-ms": Flags.string({ description: "Wait for old pid death after SIGKILL" }),
 		"spawn-if-stopped": Flags.boolean({ description: "On reload, spawn even when no daemon is running" }),
 		smoke: Flags.boolean({ description: "Internal: run worker smoke without configuration or network" }),
 		"owner-id": Flags.string({ description: "Internal: daemon owner id" }),
@@ -64,6 +76,11 @@ export default class Daemon extends Command {
 		const rawAction = args.action ?? "status";
 		const positional = Array.isArray(args.kind) ? args.kind : args.kind ? [args.kind] : [];
 		const flagRec = flags as Record<string, unknown>;
+		const gracefulTimeoutMs = parsePositiveTimeout(
+			flagRec["graceful-timeout-ms"] as string | undefined,
+			"--graceful-timeout-ms",
+		);
+		const killTimeoutMs = parsePositiveTimeout(flagRec["kill-timeout-ms"] as string | undefined, "--kill-timeout-ms");
 		if (rawAction === "session") {
 			await runSdkSessionCli({
 				action: positional[0],
@@ -91,8 +108,8 @@ export default class Daemon extends Command {
 			json: Boolean(flags.json),
 			force: Boolean(flags.force),
 			verbose: Boolean(flags.verbose),
-			gracefulTimeoutMs: flagRec["graceful-timeout-ms"] as number | undefined,
-			killTimeoutMs: flagRec["kill-timeout-ms"] as number | undefined,
+			gracefulTimeoutMs,
+			killTimeoutMs,
 			spawnIfStopped: flagRec["spawn-if-stopped"] as boolean | undefined,
 			smoke: Boolean(flags.smoke),
 			ownerId: flagRec["owner-id"] as string | undefined,

package/src/commands/deep-interview.ts

@@ -2,7 +2,22 @@ import { Command, Flags } from "@sayknow-cli/utils/cli";
 import { runNativeDeepInterviewCommand } from "../skc-runtime/deep-interview-runtime";
 
 export default class DeepInterview extends Command {
-	static description = "Run native SKC deep-interview workflow";
+	static description = `Run native SKC deep-interview workflow.
+
+All deep-interview state operations go through this command — no skc state needed:
+  read                Print the persisted envelope, revision, content sha, and any pending draft
+  write               One-shot incremental JSON merge into state (--reset replaces; the locked
+                      intent contract survives a reset)
+  stage               Stage one JSON transition draft (--for <transition> --input '<json>'|@file)
+  check               Dry-run the staged draft against current state (same merge apply performs)
+  apply               Commit the staged draft with runtime-owned revision+sha CAS
+  discard             Remove the pending draft
+  clear               Clear deep-interview state for the session (lifecycle passthrough)
+  handoff             Hand off to the next workflow skill (lifecycle passthrough)
+
+Ambiguity is runtime-owned: apply/write derive current_ambiguity from the latest valid scored
+round and clamp it to the deterministic floor. Sessions resolve from --session-id, payload
+session_id, or SKC_SESSION_ID.`;
 	static strict = false;
 	static flags = {
 		quick: Flags.boolean({ description: "Seed a quick deep-interview run" }),
@@ -14,6 +29,11 @@ export default class DeepInterview extends Command {
 		"session-id": Flags.string({
 			description: "Route state/spec handoff through a session-scoped .skc/_session-{sessionid} directory",
 		}),
+		input: Flags.string({ description: "JSON payload (or @file) for the write/stage verbs" }),
+		for: Flags.string({
+			description: "Transition for stage: initialize-context | record-round | update-facts | merge-state",
+		}),
+		reset: Flags.boolean({ description: "With write: replace state instead of incremental merge" }),
 		write: Flags.boolean({ description: "Persist a final deep-interview spec through the sanctioned SKC CLI/API" }),
 		stage: Flags.string({ description: 'Spec stage for --write (currently "final")' }),
 		slug: Flags.string({ description: "Safe slug for .skc/_session-{sessionid}/specs/deep-interview-<slug>.md" }),
@@ -27,6 +47,11 @@ export default class DeepInterview extends Command {
 	};
 	static examples = [
 		'$ skc deep-interview --trace --standard "<idea>"',
+		"$ skc deep-interview read --json",
+		'$ skc deep-interview write --input \'{"state":{"threshold":0.05}}\' --json',
+		'$ skc deep-interview stage --for record-round --input \'{"state":{"rounds":[{"round":1,"round_key":"r1"}]}}\' --json',
+		"$ skc deep-interview check --json",
+		"$ skc deep-interview apply --json",
 		"$ skc deep-interview --write --stage final --slug my-feature --spec ./final-spec.md",
 		"$ skc deep-interview --write --stage final --slug my-feature --spec ./final-spec.md --deliberate",
 	];

package/src/commands/harness.ts

@@ -14,6 +14,7 @@ import { existsSync, readFileSync } from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { Args, Command, Flags } from "@sayknow-cli/utils/cli";
+import { $credentialEnv } from "@sayknow-cli/utils/env";
 import { classifyRecovery } from "../harness-control-plane/classifier";
 import { callEndpoint, EndpointUnreachableError } from "../harness-control-plane/control-endpoint";
 import {
@@ -565,20 +566,42 @@ function ownerIsolationPlatform(): NodeJS.Platform {
 		: "linux";
 }
 
+/**
+ * Operator override for the process-start probe command, resolved from trusted
+ * environment sources only.
+ *
+ * The result is spawned, so whatever can set it chooses which binary runs.
+ * `$env` merges the caller's `cwd/.env` into `process.env`, so reading it there
+ * would let repository content pick the command; resolve it the same way
+ * provider credentials are (launching shell plus SKC/user-owned `.env` files,
+ * never the project `.env`). A malformed override stays fatal rather than
+ * silently falling back to `ps`, matching the previous behavior.
+ */
+type ProcessStartCommandOverride = { kind: "none" } | { kind: "invalid" } | { kind: "command"; command: string[] };
+
+function processStartCommandOverride(): ProcessStartCommandOverride {
+	const configured = $credentialEnv("SKC_HARNESS_PROCESS_START_COMMAND");
+	if (!configured) return { kind: "none" };
+	try {
+		const parsed = JSON.parse(configured) as unknown;
+		if (!Array.isArray(parsed) || parsed.length === 0 || parsed.some(value => typeof value !== "string" || !value))
+			return { kind: "invalid" };
+		return { kind: "command", command: parsed as string[] };
+	} catch {
+		return { kind: "invalid" };
+	}
+}
+
+/** Test seam: the process-start command override as resolved from trusted env. */
+export function processStartCommandOverrideForTest(): ProcessStartCommandOverride {
+	return processStartCommandOverride();
+}
+
 function portableProcessStartTime(pid: number): string | null {
 	if (process.platform === "linux") return null;
-	const configured = process.env.SKC_HARNESS_PROCESS_START_COMMAND;
-	let command: string[] = ["ps", "-o", "lstart=", "-p"];
-	if (configured) {
-		try {
-			const parsed = JSON.parse(configured) as unknown;
-			if (!Array.isArray(parsed) || parsed.length === 0 || parsed.some(value => typeof value !== "string" || !value))
-				return null;
-			command = parsed;
-		} catch {
-			return null;
-		}
-	}
+	const override = processStartCommandOverride();
+	if (override.kind === "invalid") return null;
+	const command: string[] = override.kind === "command" ? override.command : ["ps", "-o", "lstart=", "-p"];
 	const result = Bun.spawnSync([...command, String(pid)], {
 		stdout: "pipe",
 		stderr: "ignore",

package/src/commands/read.ts

@@ -1,7 +1,7 @@
 /**
  * Show what the read tool will return for a given path.
  */
-import { Args, Command } from "@sayknow-cli/utils/cli";
+import { Args, Command, Flags } from "@sayknow-cli/utils/cli";
 import { type ReadCommandArgs, runReadCommand } from "../cli/read-cli";
 import { initTheme } from "../modes/theme/theme";
 
@@ -15,8 +15,16 @@ export default class Read extends Command {
 		}),
 	};
 
+	static flags = {
+		truncation: Flags.string({
+			options: ["head", "last", "both"],
+			description: "Which end of an over-budget result to keep",
+		}),
+	};
+
 	static examples = [
 		"skc read src/foo.ts",
+		"skc read src/foo.ts --truncation head",
 		"skc read src/foo.ts:50-100",
 		"skc read src/foo.ts:raw",
 		"skc read https://example.com",
@@ -25,9 +33,10 @@ export default class Read extends Command {
 	];
 
 	async run(): Promise<void> {
-		const { args } = await this.parse(Read);
+		const { args, flags } = await this.parse(Read);
 		const cmd: ReadCommandArgs = {
 			path: args.path ?? "",
+			truncation: flags.truncation as ReadCommandArgs["truncation"],
 		};
 		await initTheme();
 		await runReadCommand(cmd);

package/src/commands/sdk.ts

@@ -1,11 +1,13 @@
 import { createHash } from "node:crypto";
 import * as fs from "node:fs/promises";
+import * as os from "node:os";
 import * as path from "node:path";
-import { Args, Command, Flags } from "@sayknow-cli/utils/cli";
+import { Args, CliParseError, Command, Flags, renderCommandHelp } from "@sayknow-cli/utils/cli";
 import type { Args as ParsedArgs } from "../cli/args";
 import { Settings } from "../config/settings";
 import { applyStartupModelProfiles, createSessionManager } from "../main";
 import { initializeExtensions } from "../modes/runtime-init";
+import { ACP_MCP_REQUEST_TIMEOUT_MS, ACP_MCP_STARTUP_HEADROOM_MS } from "../sdk/acp/mcp";
 import { Broker } from "../sdk/broker/broker";
 import { completeBrokerProcess } from "../sdk/broker/internal";
 import {
@@ -25,6 +27,7 @@ import {
 	type SdkStartupRollbackResult,
 	SdkStartupRollbackTracker,
 } from "../sdk/startup-capability";
+import { runSdkServe } from "../sdk/transport/serve-cli";
 import {
 	type CapturedSessionTranscriptSnapshot,
 	type ResumeSessionIdentity,
@@ -284,24 +287,106 @@ export async function runSessionHost(
 		throw new Error("SDK startup did not complete before readiness cutoff.");
 	}
 
-	let opened: { parsed: ParsedArgs; sessionManager: SessionManager | undefined };
-	let created: CreateLifecycleAgentSessionResult;
-	try {
-		opened = await openLifecycleSessionManager(request, cwd, agentDir);
-		created = await createLifecycleAgentSession({ cwd, agentDir, sessionManager: opened.sessionManager });
-	} catch (error) {
+	// Inlined rather than extracted to a helper: TypeScript's definite-assignment
+	// analysis does not see a `Promise<never>` helper as terminating, so hoisting
+	// this would make `opened`/`created` "used before assigned" below.
+	const registrationFailure = async (error: unknown): Promise<SdkStartupFailure> => {
 		const rollback = new SdkStartupRollbackTracker();
 		rollback.recordAbsent();
 		const failure = normalizeSdkStartupFailure("registration", "failed", error);
 		await writeFailure(failure, rollback.result);
-		throw new Error(failure.message);
+		return failure;
+	};
+
+	let opened: { parsed: ParsedArgs; sessionManager: SessionManager | undefined };
+	let created: CreateLifecycleAgentSessionResult;
+	let mcpConfigDirectory: string | undefined;
+	try {
+		let mcpConfigPath: string | undefined;
+		try {
+			opened = await openLifecycleSessionManager(request, cwd, agentDir);
+			if (request.mcpServers && request.mcpServers.length > 0) {
+				mcpConfigDirectory = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), "skc-acp-mcp-")));
+				mcpConfigPath = path.join(mcpConfigDirectory, "mcp.json");
+				await Bun.write(
+					mcpConfigPath,
+					JSON.stringify({
+						mcpServers: Object.fromEntries(
+							request.mcpServers.map(server => [
+								server.name,
+								"url" in server
+									? {
+											type: server.type,
+											url: server.url,
+											...(server.headers ? { headers: server.headers } : {}),
+											timeout: ACP_MCP_REQUEST_TIMEOUT_MS,
+										}
+									: {
+											type: "stdio",
+											command: server.command,
+											args: server.args,
+											...(server.env ? { env: server.env } : {}),
+											noInheritEnv: true,
+											timeout: ACP_MCP_REQUEST_TIMEOUT_MS,
+										},
+							]),
+						),
+					}),
+				);
+			}
+		} catch (error) {
+			throw await registrationFailure(error);
+		}
+
+		// The longer MCP startup ceiling is scoped to ACP lifecycle launches only:
+		// it applies when this request actually carried `mcpServers`. Ordinary
+		// CLI/SDK `mcpConfigPath` consumers keep the manager's short default.
+		//
+		// This recheck deliberately sits OUTSIDE the registration catch above.
+		// Inside it, the throw would be caught, reclassified as
+		// `registration`/`failed`, and written a second time, losing the
+		// `startup`/`pending` outcome the readiness cutoff is supposed to report.
+		// Session-manager open and MCP config write already consumed part of the
+		// budget, so re-read the clock here rather than reusing the earlier check.
+		let mcpStartupTimeoutMs: number | undefined;
+		if (mcpConfigPath !== undefined) {
+			const remaining = request.semanticReadyDeadlineAt - now() - ACP_MCP_STARTUP_HEADROOM_MS;
+			if (remaining <= 0) {
+				const absent = new SdkStartupRollbackTracker();
+				absent.recordAbsent();
+				await writeFailure(
+					{
+						phase: "startup",
+						reason: "pending",
+						message: "SDK startup did not complete before readiness cutoff.",
+					},
+					absent.result,
+				);
+				throw new Error("SDK startup did not complete before readiness cutoff.");
+			}
+			mcpStartupTimeoutMs = remaining;
+		}
+
+		try {
+			created = await createLifecycleAgentSession({
+				cwd,
+				agentDir,
+				sessionManager: opened.sessionManager,
+				...(mcpConfigPath ? { mcpConfigPath } : {}),
+				...(mcpStartupTimeoutMs !== undefined ? { mcpStartupTimeoutMs } : {}),
+			});
+		} catch (error) {
+			throw await registrationFailure(error);
+		}
+	} finally {
+		if (mcpConfigDirectory) await fs.rm(mcpConfigDirectory, { recursive: true, force: true });
 	}
 	const { parsed } = opened;
 	if ("failure" in created) {
 		created.rollback.recordAbsent();
 		await writeFailure(created.failure, created.rollback.result);
 
-		throw new Error(created.failure.message);
+		throw created.failure;
 	}
 	const { session, capability, rollback } = created;
 	let sessionDisposal: Promise<void> | undefined;
@@ -423,19 +508,51 @@ export async function runSessionHost(
 	await new Promise<void>(() => {});
 }
 
+export type SdkInternalArgv = { action: "broker-internal"; agentDir: string } | { action: "session-host-internal" };
+
+/** Parses the exact private argv contracts used by SDK child-process spawns. */
+export function parseSdkInternalArgv(argv: readonly string[]): SdkInternalArgv {
+	if (argv[0] === "session-host-internal" && argv.length === 1) return { action: "session-host-internal" };
+	if (argv[0] === "broker-internal" && argv.length === 3 && argv[1] === "--agent-dir" && argv[2])
+		return { action: "broker-internal", agentDir: argv[2] };
+	throw new CliParseError("Invalid internal SDK invocation.");
+}
+
+class SdkServeHelp extends Command {
+	static description = "skc sdk serve --stdio | --socket <path> [--session <id>] [--pending-ceiling <bytes>]";
+	static flags = {
+		stdio: Flags.boolean({ description: "Serve SDK frames over standard input and output" }),
+		socket: Flags.string({ description: "Serve SDK frames over a Unix socket path" }),
+		session: Flags.string({ description: "Attach to a specific SDK session" }),
+		"pending-ceiling": Flags.string({ description: "Maximum queued relay bytes per direction" }),
+	};
+	async run(): Promise<void> {}
+}
+
 export default class Sdk extends Command {
-	static description = "SDK internal services";
-	static hidden = true;
-	static args = { action: Args.string({ required: true, options: ["broker-internal", "session-host-internal"] }) };
-	static flags = { "agent-dir": Flags.string({ description: "Internal broker agent directory" }) };
+	static description = "skc sdk serve --stdio | --socket <path> [--session <id>] [--pending-ceiling <bytes>]";
+	static hidden = false;
+	static delegateHelp = true;
+	static args = { action: Args.string({ required: false, options: ["serve"] }) };
+	static flags = SdkServeHelp.flags;
 	async run(): Promise<void> {
-		const { args, flags } = await this.parse(Sdk);
-		if (args.action === "session-host-internal") {
+		const action = this.argv[0];
+		if (this.argv.includes("--help") || this.argv.includes("-h")) {
+			renderCommandHelp("skc", action === "serve" ? "sdk serve" : "sdk", action === "serve" ? SdkServeHelp : Sdk);
+			return;
+		}
+		if (action === "serve") {
+			await runSdkServe(this.argv.slice(1));
+			return;
+		}
+		if (action !== "broker-internal" && action !== "session-host-internal")
+			throw new CliParseError("Expected action to be serve.");
+		const internal = parseSdkInternalArgv(this.argv);
+		if (internal.action === "session-host-internal") {
 			await runSessionHost();
 			return;
 		}
-		const agentDir = flags["agent-dir"] as string | undefined;
-		if (!agentDir) throw new Error("--agent-dir is required for sdk broker-internal.");
+		const agentDir = internal.agentDir;
 		const broker = new Broker({
 			agentDir,
 			resolveDirectoryMigration: async cwd => {

package/src/commands/team.ts

@@ -173,7 +173,7 @@ export default class Team extends Command {
 					"Supported operations:",
 					"send-message broadcast mailbox-list mailbox-mark-delivered mailbox-mark-notified notification-list notification-read notification-replay notification-mark-pane-attempt worker-startup-ack",
 					"create-task read-task list-tasks update-task claim-task transition-task-status release-task-claim",
-					"read-config read-manifest read-worker-status update-worker-status read-worker-heartbeat recover-stale-claims update-worker-heartbeat write-worker-inbox write-worker-identity",
+					"read-config read-manifest read-worker-status update-worker-status read-worker-heartbeat recover-stale-claims update-worker-heartbeat read-worker-memory-guard update-worker-memory-guard apply-worker-memory-guard write-worker-inbox write-worker-identity",
 					"append-event read-events read-traces await-event write-shutdown-request read-shutdown-ack read-monitor-snapshot write-monitor-snapshot read-task-approval write-task-approval",
 					"Completion example:",
 					'transition-task-status --input \'{"team_name":"demo","task_id":"task-1","to":"completed","claim_token":"...","completion_evidence":{"summary":"done","items":[{"kind":"command","status":"passed","summary":"focused tests passed","command":"bun test packages/coding-agent/test/skc-runtime/team-runtime.test.ts"}]}}\' --json',

package/src/commit/agentic/index.ts

@@ -1,6 +1,6 @@
 import * as path from "node:path";
 import { createInterface } from "node:readline/promises";
-import { $env, getProjectDir, isEnoent, prompt } from "@sayknow-cli/utils";
+import { $env, $pickenv, getProjectDir, isEnoent, prompt } from "@sayknow-cli/utils";
 import { applyChangelogProposals } from "../../commit/changelog";
 import { detectChangelogBoundaries } from "../../commit/changelog/detect";
 import { parseUnreleasedSection } from "../../commit/changelog/parse";
@@ -88,7 +88,7 @@ export async function runAgenticCommit(args: CommitCommandArgs): Promise<void> {
 	} else {
 		process.stdout.write("  └─ (none found)\n");
 	}
-	const forceFallback = $env.PI_COMMIT_TEST_FALLBACK?.toLowerCase() === "true";
+	const forceFallback = $pickenv("SKC_COMMIT_TEST_FALLBACK", "PI_COMMIT_TEST_FALLBACK")?.toLowerCase() === "true";
 	if (forceFallback) {
 		process.stdout.write("● Forcing fallback commit generation...\n");
 		const fallbackProposal = generateFallbackProposal(numstat);
@@ -152,7 +152,7 @@ export async function runAgenticCommit(args: CommitCommandArgs): Promise<void> {
 	}
 
 	if (!usedFallback && !commitState.proposal && !commitState.splitProposal) {
-		if ($env.PI_COMMIT_NO_FALLBACK?.toLowerCase() !== "true") {
+		if ($pickenv("SKC_COMMIT_NO_FALLBACK", "PI_COMMIT_NO_FALLBACK")?.toLowerCase() !== "true") {
 			process.stdout.write("● Agent did not provide proposal, using fallback...\n");
 			commitState.proposal = generateFallbackProposal(numstat);
 			usedFallback = true;