@gajae-code/coding-agent 0.11.6 → 0.11.7

package/src/commands/sdk.ts

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { Args, Command, Flags } from "@gajae-code/utils/cli";
+import { Args, CliParseError, Command, Flags, renderCommandHelp } from "@gajae-code/utils/cli";
 import type { Args as ParsedArgs } from "../cli/args";
 import { Settings } from "../config/settings";
 import { applyStartupModelProfiles, createSessionManager } from "../main";
@@ -25,6 +25,7 @@ import {
 	type SdkStartupRollbackResult,
 	SdkStartupRollbackTracker,
 } from "../sdk/startup-capability";
+import { runSdkServe } from "../sdk/transport/serve-cli";
 import {
 	type CapturedSessionTranscriptSnapshot,
 	type ResumeSessionIdentity,
@@ -423,19 +424,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 = "gjc 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 = "gjc 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("gjc", 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/config/keybindings.ts

@@ -172,7 +172,7 @@ export const KEYBINDINGS = {
 	},
 	"app.session.fork": {
 		defaultKeys: [],
-		description: "Fork session",
+		description: "Branch from message",
 	},
 	"app.session.resume": {
 		defaultKeys: [],

package/src/config/model-profiles.ts

@@ -257,6 +257,20 @@ export const BUILTIN_MODEL_PROFILES: readonly ModelProfileDefinition[] = [
 		critic: "minimax-code/minimax-m3:xhigh",
 		architect: "minimax-code/minimax-m3:xhigh",
 	}),
+	profile("alibaba-token-plan-balanced", ["alibaba-token-plan"], {
+		default: "alibaba-token-plan/qwen3.8-max-preview:medium",
+		executor: "alibaba-token-plan/deepseek-v4-pro:xhigh",
+		planner: "alibaba-token-plan/glm-5.2:high",
+		architect: "alibaba-token-plan/qwen3.8-max-preview:xhigh",
+		critic: "alibaba-token-plan/glm-5.2:high",
+	}),
+	profile("alibaba-token-plan-qwenmaxxing", ["alibaba-token-plan"], {
+		default: "alibaba-token-plan/qwen3.8-max-preview:medium",
+		executor: "alibaba-token-plan/qwen3.8-max-preview:low",
+		planner: "alibaba-token-plan/qwen3.8-max-preview:medium",
+		architect: "alibaba-token-plan/qwen3.8-max-preview:xhigh",
+		critic: "alibaba-token-plan/qwen3.8-max-preview:xhigh",
+	}),
 	profile("opus-codex", ["anthropic", "openai-codex"], {
 		default: "anthropic/claude-opus-4-8:xhigh",
 		executor: "openai-codex/gpt-5.6-terra:low",
@@ -315,6 +329,8 @@ const PROFILE_PRESENTATION: Record<string, ModelProfilePresentation> = {
 	"minimax-eco": { displayName: "MiniMax Eco", providerGroup: "MINIMAX" },
 	"minimax-medium": { displayName: "MiniMax Medium", providerGroup: "MINIMAX" },
 	"minimax-pro": { displayName: "MiniMax Pro", providerGroup: "MINIMAX" },
+	"alibaba-token-plan-balanced": { displayName: "Balanced", providerGroup: "ALIBABA TOKEN PLAN" },
+	"alibaba-token-plan-qwenmaxxing": { displayName: "QwenMaxxing", providerGroup: "ALIBABA TOKEN PLAN" },
 	"opus-codex": { displayName: "Opus + Codex", providerGroup: "COMBOS" },
 	"codex-opencodego": { displayName: "Codex + OpenCodeGo", providerGroup: "COMBOS" },
 	"fable-opus-codex": { displayName: "Fable + Opus + Codex", providerGroup: "COMBOS" },
@@ -330,6 +346,7 @@ const PROFILE_GROUP_ORDER = [
 	"GROK",
 	"CURSOR",
 	"MINIMAX",
+	"ALIBABA TOKEN PLAN",
 	"COMBOS",
 ];
 
@@ -347,6 +364,7 @@ const PROFILE_RECOMMENDATIONS: Record<string, string> = {
 	"grok-build": "grok-build-pro",
 	cursor: "cursor-medium",
 	"minimax-code": "minimax-medium",
+	"alibaba-token-plan": "alibaba-token-plan-balanced",
 };
 
 export function getModelProfilePresentation(

package/src/config/settings-schema.ts

@@ -819,6 +819,15 @@ export const SETTINGS_SCHEMA = {
 		type: "boolean",
 		default: true,
 	},
+	"statusLine.showActionHints": {
+		type: "boolean",
+		default: true,
+		ui: {
+			tab: "appearance",
+			label: "Status Line Action Hints",
+			description: "Show contextual keyboard shortcuts in the status line",
+		},
+	},
 
 	"statusLine.leftSegments": { type: "array", default: [] as StatusLineSegmentId[] },
 
@@ -2451,9 +2460,9 @@ export const SETTINGS_SCHEMA = {
 		default: false,
 		ui: {
 			tab: "tools",
-			label: "Insane Search Fallback",
+			label: "Insane Search Fallback (Compatibility)",
 			description:
-				"Opt in to the vendored insane-search escalation for blocked public URL reads (403/WAF/JS-gated). Off by default. Requires preinstalled python3 + curl_cffi (and node + playwright/stealth for the browser phase); changes network posture by enabling TLS/browser impersonation for public pages.",
+				"Compatibility-only preference. Remote renderer fallback stays disabled because it cannot preserve validated per-hop network routing.",
 		},
 	},
 
@@ -3290,25 +3299,66 @@ export const SETTINGS_SCHEMA = {
 	},
 	"providers.image": {
 		type: "enum",
-		values: ["auto", "openai", "gemini", "openrouter", "antigravity"] as const,
+		values: ["auto", "openai", "gemini", "openrouter", "antigravity", "custom"] as const,
 		default: "auto",
 		ui: {
 			tab: "providers",
-			label: "Image Provider",
-			description: "Provider for image generation tool",
+			label: "Image Generation",
+			description: "Provider and model for image generation tool",
 			options: [
 				{
 					value: "auto",
 					label: "Auto",
 					description: "Priority: GPT model image tool > Antigravity > OpenRouter > Gemini",
 				},
-				{ value: "openai", label: "OpenAI", description: "Uses the active GPT Responses/Codex model" },
+				{ value: "openai", label: "OpenAI", description: "Uses gpt-image-2 via OpenAI Responses/Codex" },
 				{ value: "gemini", label: "Gemini", description: "Requires GEMINI_API_KEY" },
 				{ value: "openrouter", label: "OpenRouter", description: "Requires OPENROUTER_API_KEY" },
 				{ value: "antigravity", label: "Antigravity", description: "Requires login with google-antigravity" },
+				{
+					value: "custom",
+					label: "Custom",
+					description: "OpenAI-compatible endpoint (set providers.imageCustomUrl)",
+				},
 			],
 		},
 	},
+	"providers.imageModel": {
+		type: "string",
+		default: undefined,
+		ui: {
+			tab: "providers",
+			label: "Image Model",
+			description: "Override the default image generation model for the selected provider",
+		},
+	},
+	"providers.imageCustomUrl": {
+		type: "string",
+		default: undefined,
+		ui: {
+			tab: "providers",
+			label: "Image Custom URL",
+			description: "Base URL for custom OpenAI-compatible image endpoint",
+		},
+	},
+	"providers.imageCustomKey": {
+		type: "string",
+		default: undefined,
+		ui: {
+			tab: "providers",
+			label: "Image Custom API Key",
+			description: "API key for custom OpenAI-compatible image endpoint",
+		},
+	},
+	"providers.imageCustomKeyEnv": {
+		type: "string",
+		default: undefined,
+		ui: {
+			tab: "providers",
+			label: "Image Custom API Key Env",
+			description: "Environment variable name holding the API key for custom image endpoint",
+		},
+	},
 
 	"providers.kimiApiFormat": {
 		type: "enum",
@@ -3740,6 +3790,7 @@ export interface StatusLineSettings {
 	maxRows: number;
 	showHookStatus: boolean;
 	showSkillHud: boolean;
+	showActionHints: boolean;
 	leftSegments: StatusLineSegmentId[];
 	rightSegments: StatusLineSegmentId[];
 	segmentOptions: Record<string, unknown>;

package/src/defaults/gjc/skills/ultragoal/SKILL.md

@@ -123,10 +123,12 @@ An active Ultragoal run must not give up on a blocker by pausing the goal and as
 - **`resolvable`** — anything the agent can act on: failing tests, missing implementation, a dependency to install, an ambiguous-but-inferable detail, investigation. **Never pause.** Exhaust autonomous resolution first: investigate, `gjc ultragoal steer --kind add_subgoal --title "Investigate blocker" --objective "..." --evidence "..." --rationale "..."`, delegate an `executor`, or preserve the blocker durably with `gjc ultragoal checkpoint --status blocked` / `gjc ultragoal record-review-blockers` and keep scheduling the next goal.
 - **`human_blocked`** — only the user can act: credentials/secrets, a manual or physical step, an external approval/decision, access the agent lacks. Pause is the last resort and is gated.
 
-`goal({"op":"pause"})` is **blocked at runtime** while an Ultragoal run is active unless the latest durable ledger event classifies the current blocker as `human_blocked`. To pause, record the classification immediately before pausing and cite the human-only dependency as evidence:
+`goal({"op":"pause"})` is **blocked at runtime** while an Ultragoal run is active unless the latest `blocker_classified` ledger event is `human_blocked` and a later bound clean pause terminal critic verdict is recorded for it (see [Terminal critic gate](#terminal-critic-gate)). `assertUltragoalPauseAllowed` first consumes a pre-existing give-up nudge (a durable ledger write) before it runs the read-only pause diagnostic; only `isUltragoalPauseBlocked` is a pure reader. To pause, first record the human-only classification and capture its event id, then record the terminal critic's clean bound pause verdict, and only then pause:
 
 ```sh
 gjc ultragoal classify-blocker --classification human_blocked --evidence "<the specific human-only dependency>" [--goal-id <id>]
+gjc ultragoal record-critic-verdict --terminus pause --classification-event-id <eventId> --verdict OKAY --evidence "<terminal critic evidence>"
+goal({"op":"pause"})
 ```
 
 Recording `--classification resolvable` is an audit note only; it never authorizes a pause. The `ask` tool stays blocked during active runs regardless of classification — record unresolved decisions as durable blockers instead of prompting.
@@ -343,6 +345,44 @@ Provide one `artifactRefs` entry per live surface actually exercised, using the
 
 For CLI replay artifacts, the JSON at `path` must be an object like `{"schemaVersion":1,"kind":"cli-replay","replaySafe":true,"command":["bun","-e","console.log(\"ultragoal-cli-ok\")"],"cwd":".","env":{"LC_ALL":"C"},"timeoutMs":30000,"expectedExitCode":0,"recordedStdout":"ultragoal-cli-ok\n","recordedStderr":"","invariants":[{"type":"substring","value":"ultragoal-cli-ok"},{"type":"not-substring","value":"error"}]}`. Accepted replay fields are `command` (string array), optional `cwd`, safe `env`, `timeoutMs`, `expectedExitCode`, `recordedStdout`, `recordedStderr`, `normalization`, and `invariants`. The conservative command allowlist is intentionally small: `bun --version`, `node --version`, deterministic `bun/node -e "console.log(...)"`, `npm|pnpm|yarn --version`, `npm|pnpm|yarn list`, read-only `git status|rev-parse|merge-base|diff|show|log` with safe args, and `gjc read|status`. `env` must contain only safe deterministic variables, never credentials or machine/user-specific secrets. `normalization` is optional and, when provided, must be exactly the string `"default"` (the built-in normalizer already strips ANSI codes, normalizes line endings, scrubs paths, and trims trailing whitespace); object-shaped normalization is rejected. Invariants may be substring, regex, or not-substring checks; when present, they replace exact `recordedStdout` equality — without `invariants`, replayed normalized stdout must match `recordedStdout` exactly. Unsafe, non-deterministic, credentialed, interactive, or otherwise unallowlisted commands require audited `replayExempt` metadata with exact fields `reasonCode`, `reason`, `approvedBy`, and `fallbackArtifactRefs` plus a structurally valid same-surface fallback artifact. `reason` must be substantive and audited, and `approvedBy` must identify the verifier. Allowed `reasonCode` values are exactly `unsafe_side_effect`, `requires_credentials`, `requires_network`, `non_deterministic_external`, `destructive`, `interactive_only`, and `platform_unavailable`.
 
+## Terminal critic gate
+
+The terminal critic gate is a fail-closed, once-per-run-terminus review. It guards both terminal exits with a read-only `critic` role agent's `OKAY` verdict; it does not run per story. It is additive to, and does not change, the existing per-story `architect` review and `executor` QA/red-team lanes.
+
+### Completion terminus
+
+Before assembling the final-aggregate `--quality-gate-json`, the leader delegates the terminal critic. Only the final-aggregate completion checkpoint requires the additional top-level `criticReview` key; `criticReview` is tolerated but ignored on non-final checkpoints. A clean final aggregate requires `verdict: "OKAY"`, non-empty `evidence`, and an empty `blockers` array:
+
+```json
+{
+  "criticReview": {
+    "verdict": "OKAY",
+    "evidence": "terminal critic review of the final required-goal state",
+    "blockers": []
+  }
+}
+```
+
+### Pause/blocked terminus
+
+At a `human_blocked` terminus, the leader first runs `gjc ultragoal classify-blocker --classification human_blocked` (capturing that classification's ledger `eventId`), then delegates the terminal critic and records its verdict with `gjc ultragoal record-critic-verdict --terminus pause --classification-event-id <eventId>` before calling `goal({"op":"pause"})`. The pause is allowed only when a later fresh `critic_verdict` ledger receipt exists with `terminus: "pause"`, `verdict: "OKAY"`, non-empty evidence, an empty blockers array, the current `planGeneration`, and a `classificationEventId` bound to the latest `blocker_classified` event, which must be `human_blocked`. Freshness is scoped to the final required-goal state, so required-goal or steer changes stale the receipt, and a newer classification supersedes an older verdict.
+
+The critic must verify that the `human_blocked` classification is genuine, including catching false pauses where needed resources exist locally or the asserted blocker is resolvable. A `REJECT` (or `ITERATE`) verdict refuses the terminal pause; the run keeps executing. The pause (`goal({"op":"pause"})`) is the gated terminal park-and-wait exit — a per-goal `gjc ultragoal checkpoint --status blocked` remains available as non-terminal blocker bookkeeping that never signals run completion and keeps the blocker outstanding until resolved.
+
+### Invocation and containment
+
+At each terminus, the leader gives the read-only `critic` role agent `brief.md`, `goals.json`, `ledger.jsonl`, and the cumulative change set. For completion, invoke it before assembling the final-aggregate gate JSON. For pause, invoke it after the `human_blocked` classification and before `goal({"op":"pause"})`. The terminal critic must not spawn nested `ralplan`, `team`, `deep-interview`, or `ultragoal` workflows. This creates no interactive surface: `ask` remains blocked while an Ultragoal run is active.
+
+### Non-OKAY loop and ceiling
+
+For completion-side `ITERATE` or `REJECT`, the leader MUST first record the terminal verdict so the run-level counter observes it: `gjc ultragoal record-critic-verdict --terminus completion --verdict <ITERATE|REJECT> --evidence "<critic findings>"`; then record the findings with `gjc ultragoal record-review-blockers` and reopen the run. The dedicated counter ceiling is 5, independently of the give-up nudge budget, and is **RUN-LEVEL**: it counts every non-OKAY terminal-critic verdict across the whole run and all reopen cycles. On reaching that ceiling, both pause and final completion are blocked until a human or leader records `gjc ultragoal record-critic-gate-override --evidence "<authorization evidence>"`. There is no automatic pause override.
+
+This gate is always fail-closed and has no grandfathering: in-flight runs must obtain a terminal verdict when they reach a terminus.
+
+#### Deferred / out of scope
+
+Gating active-aggregate `goal drop` after nudge exhaustion is a known follow-up not covered by this gate; `drop` remains governed by the existing nudge discipline.
+
 ## Review mode
 
 `gjc ultragoal review` runs the same hardened gate against an already implemented PR, branch, or worktree. Use `--pr <number>` for a PR, `--branch <ref>` for a branch diff, omit both for the current worktree, and pass `--spec <path>` when a real contract exists. `--mode review-only` emits the verdict/findings without creating fix work; `--mode review-start` records review blockers for follow-up. Review mode validates the same `executorQa` shape and live-surface artifacts as `checkpoint --status complete`. A thin or derived-only contract can never clean-pass: the verdict is capped at `inconclusive: weak-contract` until a supplied spec or equivalent strong acceptance criteria are available.
@@ -372,4 +412,5 @@ The skill tool then dispatches `/skill:ralplan` or `/skill:deep-interview` same-
 - Never call `goal({"op":"complete"})` unless the aggregate run or legacy per-story goal is actually complete.
 - In aggregate mode, intermediate and final story checkpoints update durable `goals.json` state and append receipt proof to `ledger.jsonl`; the final story checkpoint creates the final aggregate receipt before the agent may call `goal({"op":"complete"})`.
 - Completion checkpoints require `--quality-gate-json` only. Shell commands and hooks must not mutate goal state; the agent reconciles inline goal-tool state after durable completion.
+- Final-aggregate completion additionally requires a `criticReview` `OKAY`; a `human_blocked` pause additionally requires a fresh `OKAY` `critic_verdict` receipt.
 - Treat `ledger.jsonl` as the durable audit trail; checkpoint after every success or failure.

package/src/discovery/ssh.ts

@@ -5,11 +5,12 @@
  * Priority: 5 (low, project/user config discovery)
  */
 import * as path from "node:path";
-import { getSSHConfigPath, tryParseJson } from "@gajae-code/utils";
+import { getSSHConfigPath, logger, tryParseJson } from "@gajae-code/utils";
 import { registerProvider } from "../capability";
 import { readFile } from "../capability/fs";
 import { type SSHHost, sshCapability } from "../capability/ssh";
 import type { LoadContext, LoadResult, SourceMeta } from "../capability/types";
+import { validateSshDestination } from "../ssh/utils";
 import { expandTilde } from "../tools/path-utils";
 import { createSourceMeta, expandEnvVarsDeep } from "./helpers";
 
@@ -58,6 +59,16 @@ function normalizeHost(
 		warnings.push(`Missing host for SSH entry: ${name}`);
 		return null;
 	}
+	const destinationError = validateSshDestination(raw.username, raw.host);
+	if (destinationError) {
+		warnings.push(`Invalid destination for SSH entry ${name}: ${destinationError}`);
+		logger.warn("Ignoring SSH entry with invalid destination", {
+			name,
+			path: source.path,
+			reason: destinationError,
+		});
+		return null;
+	}
 
 	const port = parsePort(raw.port);
 	if (raw.port !== undefined && port === undefined) {

package/src/eval/py/kernel.ts

@@ -8,9 +8,6 @@
  * Shutdown writes `{"type":"exit"}` and escalates to SIGTERM/SIGKILL on
  * timeout.
  */
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
 import { $env, isBunTestRuntime, logger, Snowflake } from "@gajae-code/utils";
 import type { Subprocess } from "bun";
 import { $ } from "bun";
@@ -18,7 +15,7 @@ import { Settings } from "../../config/settings";
 import { type KernelDisplayOutput, renderKernelDisplay } from "./display";
 import { resolvePythonIpcTrace, resolvePythonSkipCheck } from "./env";
 import { PYTHON_PRELUDE } from "./prelude";
-import RUNNER_SCRIPT from "./runner.py" with { type: "text" };
+import { ensureRunnerScript } from "./runner-artifact";
 import { ensurePythonRuntime, filterEnv, type PythonRuntimeOptions } from "./runtime";
 
 export type { KernelDisplayOutput, PythonStatusEvent } from "./display";
@@ -27,23 +24,6 @@ export { renderKernelDisplay } from "./display";
 // Dual-read: `GJC_PYTHON_IPC_TRACE` is preferred, then legacy `PI_PYTHON_IPC_TRACE`.
 const TRACE_IPC = resolvePythonIpcTrace($env);
 
-// Cache the runner script on disk so the subprocess loads it normally. Cached
-// per script hash so installs don't race across versions.
-const RUNNER_CACHE_DIR = path.join(os.tmpdir(), "gjc-python-runner");
-let RUNNER_SCRIPT_PATH: string | null = null;
-
-async function ensureRunnerScript(): Promise<string> {
-	if (RUNNER_SCRIPT_PATH) return RUNNER_SCRIPT_PATH;
-	await fs.promises.mkdir(RUNNER_CACHE_DIR, { recursive: true });
-	const hash = Bun.hash(RUNNER_SCRIPT).toString(36);
-	const target = path.join(RUNNER_CACHE_DIR, `runner-${hash}.py`);
-	if (!fs.existsSync(target)) {
-		await Bun.write(target, RUNNER_SCRIPT);
-	}
-	RUNNER_SCRIPT_PATH = target;
-	return target;
-}
-
 const SHUTDOWN_GRACE_MS = 1_000;
 const STARTUP_TIMEOUT_MS = 10_000;
 // How long to wait after SIGINT for the runner to emit `done`. If the cell is

package/src/eval/py/runner-artifact.ts

@@ -0,0 +1,84 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { postmortem } from "@gajae-code/utils";
+import RUNNER_SCRIPT from "./runner.py" with { type: "text" };
+
+const DIRECTORY_MODE = 0o700;
+const FILE_MODE = 0o600;
+const DIRECTORY_PREFIX = "gjc-python-runner-";
+
+interface RunnerScriptArtifact {
+	directory: string;
+	scriptPath: string;
+}
+
+async function initializeRunnerScript(tempRoot: string): Promise<RunnerScriptArtifact> {
+	const directory = await fs.mkdtemp(path.join(tempRoot, DIRECTORY_PREFIX));
+	try {
+		if (process.platform !== "win32") await fs.chmod(directory, DIRECTORY_MODE);
+		const scriptPath = path.join(directory, "runner.py");
+		const handle = await fs.open(scriptPath, "wx", FILE_MODE);
+		try {
+			await handle.writeFile(RUNNER_SCRIPT, { encoding: "utf8" });
+			if (process.platform !== "win32") await handle.chmod(FILE_MODE);
+		} finally {
+			await handle.close();
+		}
+		return { directory, scriptPath };
+	} catch (error) {
+		await fs.rm(directory, { recursive: true, force: true }).catch(() => {});
+		throw error;
+	}
+}
+
+export interface RunnerScriptCache {
+	ensureRunnerScript(): Promise<string>;
+	cleanup(): Promise<void>;
+}
+
+export function createRunnerScriptCache(tempRoot: string): RunnerScriptCache {
+	let initialization: Promise<RunnerScriptArtifact> | null = null;
+	let artifact: RunnerScriptArtifact | null = null;
+	let cleanupAttempt: Promise<void> | null = null;
+
+	return {
+		async ensureRunnerScript() {
+			if (artifact) return artifact.scriptPath;
+			if (!initialization) initialization = initializeRunnerScript(tempRoot);
+			try {
+				artifact = await initialization;
+				return artifact.scriptPath;
+			} catch (error) {
+				if (initialization) initialization = null;
+				throw error;
+			}
+		},
+		async cleanup() {
+			if (cleanupAttempt) return await cleanupAttempt;
+			cleanupAttempt = (async () => {
+				const initialized = await initialization?.catch(() => null);
+				const directory = artifact?.directory ?? initialized?.directory;
+				artifact = null;
+				initialization = null;
+				if (directory) await fs.rm(directory, { recursive: true, force: true });
+			})();
+			try {
+				await cleanupAttempt;
+			} finally {
+				cleanupAttempt = null;
+			}
+		},
+	};
+}
+
+/** @internal Test-only initializer for isolated artifact assertions. */
+export function createRunnerScriptInitializer(tempRoot: string): () => Promise<string> {
+	return createRunnerScriptCache(tempRoot).ensureRunnerScript;
+}
+
+const processRunnerScriptCache = createRunnerScriptCache(os.tmpdir());
+
+export const ensureRunnerScript = () => processRunnerScriptCache.ensureRunnerScript();
+
+postmortem.register("python-runner-artifact", () => processRunnerScriptCache.cleanup());