pi-crew 0.9.56 → 0.9.57

package/src/runtime/{completion-guard.ts → verification/completion-guard.ts}

@@ -1,5 +1,5 @@
 import * as fs from "node:fs";
-import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
+import type { TeamRunManifest, TeamTaskState } from "../../state/types.ts";
 
 // ============================================================================
 // Phase 1.2: Completion Mutation Guard — detects tasks that claim success but

package/src/runtime/{green-contract.ts → verification/green-contract.ts}

@@ -1,4 +1,4 @@
-import type { GreenLevel, VerificationContract, VerificationEvidence } from "../state/types.ts";
+import type { GreenLevel, VerificationContract, VerificationEvidence } from "../../state/types.ts";
 
 const GREEN_ORDER: Record<GreenLevel, number> = {
 	none: 0,

package/src/runtime/{post-checks.ts → verification/post-checks.ts}

@@ -5,10 +5,10 @@
  * Distilled from pi-autoresearch's post-check / backpressure pattern.
  */
 import { execFileSync } from "node:child_process";
-import { WINDOWS_ESSENTIAL_ENV_VARS } from "../utils/env-allowlist.ts";
-import { sanitizeEnvSecrets } from "../utils/env-filter.ts";
-import { resolveShellForScript } from "../utils/resolve-shell.ts";
-import { resolveRealContainedPath } from "../utils/safe-paths.ts";
+import { WINDOWS_ESSENTIAL_ENV_VARS } from "../../utils/env-allowlist.ts";
+import { sanitizeEnvSecrets } from "../../utils/env-filter.ts";
+import { resolveShellForScript } from "../../utils/resolve-shell.ts";
+import { resolveRealContainedPath } from "../../utils/safe-paths.ts";
 
 /** Default timeout for post-check scripts (5 minutes). */
 const DEFAULT_TIMEOUT_MS = 300_000;

package/src/runtime/{verification-gates.ts → verification/verification-gates.ts}

@@ -12,11 +12,11 @@
 import { spawn } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { writeArtifact } from "../state/artifact-store.ts";
-import type { GreenLevel, VerificationCommandResult, VerificationContract } from "../state/types.ts";
-import { WINDOWS_ESSENTIAL_ENV_VARS } from "../utils/env-allowlist.ts";
-import { sanitizeEnvSecrets } from "../utils/env-filter.ts";
-import { redactSecretString } from "../utils/redaction.ts";
+import { writeArtifact } from "../../state/stores/artifact-store.ts";
+import type { GreenLevel, VerificationCommandResult, VerificationContract } from "../../state/types.ts";
+import { WINDOWS_ESSENTIAL_ENV_VARS } from "../../utils/env-allowlist.ts";
+import { sanitizeEnvSecrets } from "../../utils/env-filter.ts";
+import { redactSecretString } from "../../utils/redaction.ts";
 
 /**
  * Phase 1.5 #1 (RFC 13 §6 info-disclosure mitigation): sanitize the env passed

package/src/runtime/{verification-integrity.ts → verification/verification-integrity.ts}

@@ -28,7 +28,7 @@
 import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { logInternalError } from "../utils/internal-error.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
 
 /**
  * Fixed set of project-manifest files considered by {@link snapshotManifests}.

package/src/schema/config-schema.ts

@@ -72,6 +72,7 @@ export const PiTeamsRuntimeConfigSchema = Type.Object(
 			),
 		),
 		excludeContextBash: Type.Optional(Type.Boolean()),
+		agentExtensions: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
 		isolationPolicy: Type.Optional(
 			Type.Object(
 				{

package/src/schema/team-tool-schema.ts

@@ -1,4 +1,25 @@
-import { type TSchema, Type } from "@sinclair/typebox";
+import { type TSchema, Type, TypeRegistry } from "@sinclair/typebox";
+
+// ─────────────────────────────────────────────────────────────────────────
+// EXT-7: Compact enum action schema. TypeBox has no built-in type that
+// produces JSON Schema `{ enum: [...] }` AND validates via Value.Check.
+// Type.Unsafe defaults to Kind 'Unsafe' which Value.Check throws on.
+// We register a custom 'StringEnum' kind once: JSON Schema consumers (the
+// LLM tool definition) see the compact `{ type: "string", enum: [...] }`
+// (~600 chars vs ~1890 for anyOf+const), and Value.Check validates via
+// the registered predicate.
+// ─────────────────────────────────────────────────────────────────────────
+TypeRegistry.Set("StringEnum", (schema, value) => {
+	const s = schema as { enum?: unknown[] };
+	return typeof value === "string" && Array.isArray(s.enum) && s.enum.includes(value);
+});
+const KIND = Symbol.for("TypeBox.Kind");
+function stringEnum(values: readonly string[], description: string): TSchema {
+	// Empty string accepted: calling models emit "" for unset action; the handler
+	// treats it as omitted (defaults to "list"). Must be a plain enum member so
+	// JSON-Schema consumers (pi-ai validation) accept it without coercion.
+	return Type.Unsafe({ [KIND]: "StringEnum", type: "string", enum: ["", ...values], description });
+}
 
 // ───────────────────────────────────────────────────────────────────────────
 // API-5 facade split: the 54-action mega-tool schema is split into 5 domain
@@ -8,24 +29,18 @@ import { type TSchema, Type } from "@sinclair/typebox";
 // `TeamToolParams` is re-exported as a TypeBox Union for backward compat.
 // ───────────────────────────────────────────────────────────────────────────
 
-const SkillOverride = Type.Unsafe({
-	description:
-		"Skill name(s) to add to role/default skills, an array of skill names, or false to disable all injected skills for this run.",
-	anyOf: [
-		{ type: "string", maxLength: 2048 },
-		{
-			type: "array",
-			maxItems: 32,
-			items: { type: "string", maxLength: 80 },
-		},
-		{ type: "boolean" },
-	],
-});
+const SkillOverride = Type.Union(
+	[Type.String({ maxLength: 2048 }), Type.Array(Type.String({ maxLength: 80 }), { maxItems: 32 }), Type.Boolean()],
+	{
+		description:
+			"Skill name(s) to add to role/default skills, an array of skill names, or false to disable all injected skills for this run.",
+	},
+);
 
-const FreeformConfig = Type.Unsafe({
+// Freeform object: Type.Record + Any is TypeBox-native (no custom Unsafe kind),
+// so Value.Check/Compile can walk it without throwing "Unknown type".
+const FreeformConfig = Type.Record(Type.String(), Type.Any(), {
 	description: "Resource config for management actions.",
-	type: "object",
-	additionalProperties: true,
 });
 
 /**
@@ -38,7 +53,7 @@ const FreeformConfig = Type.Unsafe({
  */
 const sharedFields = {
 	resource: Type.Optional(
-		Type.Union([Type.Literal("agent"), Type.Literal("team"), Type.Literal("workflow")], {
+		Type.Union([Type.Literal(""), Type.Literal("agent"), Type.Literal("team"), Type.Literal("workflow")], {
 			description: "Resource kind for get/create/update/delete/list. Defaults to all for list.",
 		}),
 	),
@@ -75,7 +90,9 @@ const sharedFields = {
 	runId: Type.Optional(
 		Type.String({
 			description: "Run ID for status, cancel, or resume.",
-			pattern: "^[A-Za-z0-9_-]+$",
+			// Empty string allowed: calling models emit "" for unset keys; the handler
+			// treats it as omitted (see normalizeTeamParams in team-tool.ts).
+			pattern: "^$|^[A-Za-z0-9_-]+$",
 		}),
 	),
 	taskId: Type.Optional(Type.String({ description: "Task ID for respond action." })),
@@ -93,12 +110,12 @@ const sharedFields = {
 		}),
 	),
 	workspaceMode: Type.Optional(
-		Type.Union([Type.Literal("single"), Type.Literal("worktree")], {
+		Type.Union([Type.Literal(""), Type.Literal("single"), Type.Literal("worktree")], {
 			description: "Workspace isolation mode. Worktree mode is planned after MVP.",
 		}),
 	),
 	context: Type.Optional(
-		Type.Union([Type.Literal("fresh"), Type.Literal("fork")], {
+		Type.Union([Type.Literal(""), Type.Literal("fresh"), Type.Literal("fork")], {
 			description: "Child context mode for workers.",
 		}),
 	),
@@ -106,7 +123,7 @@ const sharedFields = {
 	model: Type.Optional(Type.String({ description: "Model override for direct runs." })),
 	skill: Type.Optional(SkillOverride),
 	scope: Type.Optional(
-		Type.Union([Type.Literal("user"), Type.Literal("project"), Type.Literal("both")], {
+		Type.Union([Type.Literal(""), Type.Literal("user"), Type.Literal("project"), Type.Literal("both")], {
 			description: "Resource scope for discovery or management.",
 		}),
 	),
@@ -127,8 +144,8 @@ const sharedFields = {
 		}),
 	),
 	keep: Type.Optional(
-		Type.Integer({
-			minimum: 0,
+		// Boolean false accepted: calling models emit false for unset; treated as omitted.
+		Type.Union([Type.Boolean(), Type.Integer({ minimum: 0 })], {
 			description: "Number of finished runs to keep for prune.",
 		}),
 	),
@@ -162,7 +179,8 @@ const sharedFields = {
 		}),
 	),
 	once: Type.Optional(
-		Type.Union([Type.String(), Type.Number()], {
+		// Boolean false accepted: calling models emit false for unset; treated as omitted.
+		Type.Union([Type.Boolean(), Type.String(), Type.Number()], {
 			description: "ISO timestamp or epoch ms for a one-time scheduled run.",
 		}),
 	),
@@ -172,11 +190,20 @@ const sharedFields = {
 		}),
 	),
 	budgetTotal: Type.Optional(
-		Type.Number({
-			description:
-				"Total token budget for the run. When set, enables budget tracking with default 80% warning and 95% abort thresholds. Minimum 1000 — this is a MISCONFIGURATION GUARD (catches typos / silent-abort configs like budgetTotal:1, which would abort on turn 1), NOT a usefulness guarantee; a productive multi-turn goal needs far more than 1000 tokens.",
-			minimum: 1000,
-		}),
+		// 0 accepted as "unset/disabled" (models emit 0 for off); still rejects 1-999
+		// as the MISCONFIGURATION GUARD against typo'd silent-abort configs.
+		Type.Union(
+			[
+				Type.Literal(0),
+				Type.Number({
+					minimum: 1000,
+				}),
+			],
+			{
+				description:
+					"Total token budget for the run. When set, enables budget tracking with default 80% warning and 95% abort thresholds. Minimum 1000 — this is a MISCONFIGURATION GUARD (catches typos / silent-abort configs like budgetTotal:1, which would abort on turn 1), NOT a usefulness guarantee; a productive multi-turn goal needs far more than 1000 tokens. 0 = unset.",
+			},
+		),
 	),
 	budgetUnlimited: Type.Optional(
 		Type.Boolean({
@@ -201,7 +228,7 @@ const sharedFields = {
 		}),
 	),
 	runKind: Type.Optional(
-		Type.Union([Type.Literal("team-run"), Type.Literal("goal-loop"), Type.Literal("dynamic-workflow")], {
+		Type.Union([Type.Literal(""), Type.Literal("team-run"), Type.Literal("goal-loop"), Type.Literal("dynamic-workflow")], {
 			description:
 				'Background dispatch discriminator. Default "team-run" runs the normal executeTeamRun workflow; "goal-loop" (P0/P1) and "dynamic-workflow" (P2/P3) dispatch to their respective background runners. Absent = "team-run" for backward compatibility.',
 		}),
@@ -239,99 +266,54 @@ const sharedFields = {
 
 const ACTION_DESCRIPTION = "Team action. Defaults to 'list' when omitted.";
 
-const runActions = Type.Optional(
-	Type.Union(
-		[
-			Type.Literal("run"),
-			Type.Literal("parallel"),
-			Type.Literal("plan"),
-			Type.Literal("orchestrate"),
-			Type.Literal("resume"),
-			Type.Literal("retry"),
-			Type.Literal("wait"),
-			Type.Literal("steer"),
-			Type.Literal("goal"),
-		],
-		{ description: ACTION_DESCRIPTION },
-	),
-);
+const RUN_ACTIONS = ["run", "parallel", "plan", "orchestrate", "resume", "retry", "wait", "steer", "goal"] as const;
+const runActions = Type.Optional(stringEnum(RUN_ACTIONS, ACTION_DESCRIPTION));
 
-const statusActions = Type.Optional(
-	Type.Union(
-		[
-			Type.Literal("status"),
-			Type.Literal("list"),
-			Type.Literal("get"),
-			Type.Literal("events"),
-			Type.Literal("artifacts"),
-			Type.Literal("summary"),
-			Type.Literal("graph"),
-			Type.Literal("search"),
-			Type.Literal("health"),
-			Type.Literal("worktrees"),
-			Type.Literal("checkpoint"),
-			Type.Literal("cache"),
-			Type.Literal("explain"),
-			Type.Literal("onboard"),
-			Type.Literal("recommend"),
-			Type.Literal("help"),
-		],
-		{ description: ACTION_DESCRIPTION },
-	),
-);
+const STATUS_ACTIONS = [
+	"status",
+	"list",
+	"get",
+	"events",
+	"artifacts",
+	"summary",
+	"graph",
+	"search",
+	"health",
+	"worktrees",
+	"checkpoint",
+	"cache",
+	"explain",
+	"onboard",
+	"recommend",
+	"help",
+] as const;
+const statusActions = Type.Optional(stringEnum(STATUS_ACTIONS, ACTION_DESCRIPTION));
 
-const controlActions = Type.Optional(
-	Type.Union(
-		[
-			Type.Literal("cancel"),
-			Type.Literal("invalidate"),
-			Type.Literal("respond"),
-			Type.Literal("cleanup"),
-			Type.Literal("prune"),
-			Type.Literal("forget"),
-			Type.Literal("doctor"),
-		],
-		{ description: ACTION_DESCRIPTION },
-	),
-);
+const CONTROL_ACTIONS = ["cancel", "invalidate", "respond", "cleanup", "prune", "forget", "doctor"] as const;
+const controlActions = Type.Optional(stringEnum(CONTROL_ACTIONS, ACTION_DESCRIPTION));
 
-const manageActions = Type.Optional(
-	Type.Union(
-		[
-			Type.Literal("create"),
-			Type.Literal("update"),
-			Type.Literal("delete"),
-			Type.Literal("init"),
-			Type.Literal("config"),
-			Type.Literal("validate"),
-			Type.Literal("autonomy"),
-			Type.Literal("settings"),
-			Type.Literal("workflow-create"),
-			Type.Literal("workflow-get"),
-			Type.Literal("workflow-list"),
-			Type.Literal("workflow-save"),
-			Type.Literal("workflow-delete"),
-			Type.Literal("import"),
-			Type.Literal("imports"),
-			Type.Literal("export"),
-		],
-		{ description: ACTION_DESCRIPTION },
-	),
-);
+const MANAGE_ACTIONS = [
+	"create",
+	"update",
+	"delete",
+	"init",
+	"config",
+	"validate",
+	"autonomy",
+	"settings",
+	"workflow-create",
+	"workflow-get",
+	"workflow-list",
+	"workflow-save",
+	"workflow-delete",
+	"import",
+	"imports",
+	"export",
+] as const;
+const manageActions = Type.Optional(stringEnum(MANAGE_ACTIONS, ACTION_DESCRIPTION));
 
-const automateActions = Type.Optional(
-	Type.Union(
-		[
-			Type.Literal("schedule"),
-			Type.Literal("scheduled"),
-			Type.Literal("anchor"),
-			Type.Literal("auto-summarize"),
-			Type.Literal("auto_boomerang"),
-			Type.Literal("api"),
-		],
-		{ description: ACTION_DESCRIPTION },
-	),
-);
+const AUTOMATE_ACTIONS = ["schedule", "scheduled", "anchor", "auto-summarize", "auto_boomerang", "api"] as const;
+const automateActions = Type.Optional(stringEnum(AUTOMATE_ACTIONS, ACTION_DESCRIPTION));
 
 // ─── Domain schemas (additionalProperties: true — Phase 1, not tightened) ────
 
@@ -356,11 +338,39 @@ export const AutomateDomainParams = Type.Object({ action: automateActions, ...sh
  * (RunDomainParams etc.) are kept for the facade dispatch + backward compat.
  */
 export const allActionLiterals = ([runActions, statusActions, controlActions, manageActions, automateActions] as TSchema[]).flatMap(
-	(set) => set.anyOf ?? [],
+	(set) => {
+		const literals =
+			(set.anyOf as { const: string }[] | undefined) ??
+			(Array.isArray(set.enum) ? set.enum.map((v: unknown) => ({ const: v })) : []) ??
+			[];
+		// stringEnum accepts "" as an unset marker for model callers; it is NOT an
+		// action, so exclude it from the literal/type/suggestion derivations.
+		return literals.filter((l) => l.const !== "");
+	},
 );
+
+/**
+ * EXT-8: Single source of truth for the valid `action` type. Derived from the
+ * domain action arrays (the same arrays `allActionLiterals` reads), so the
+ * `TeamToolParamsValue.action` interface field, schema enum, and suggestions
+ * can never drift apart. Adding/removing an action in any `*_ACTIONS` array
+ * propagates to every consumer automatically.
+ */
+export type TeamAction =
+	| (typeof RUN_ACTIONS)[number]
+	| (typeof STATUS_ACTIONS)[number]
+	| (typeof CONTROL_ACTIONS)[number]
+	| (typeof MANAGE_ACTIONS)[number]
+	| (typeof AUTOMATE_ACTIONS)[number];
+
 export const TeamToolParams = Type.Object(
 	{
-		action: Type.Optional(Type.Union(allActionLiterals, { description: ACTION_DESCRIPTION })),
+		action: Type.Optional(
+			stringEnum(
+				allActionLiterals.map((l) => (l as { const: string }).const),
+				ACTION_DESCRIPTION,
+			),
+		),
 		...sharedFields,
 	},
 	{ additionalProperties: true },
@@ -370,61 +380,7 @@ export const TeamToolParams = Type.Object(
 export type TeamDomain = "run" | "status" | "control" | "manage" | "automate";
 
 export interface TeamToolParamsValue {
-	action?:
-		| "run"
-		| "parallel"
-		| "plan"
-		| "status"
-		| "wait"
-		| "list"
-		| "get"
-		| "cancel"
-		| "retry"
-		| "resume"
-		| "respond"
-		| "create"
-		| "update"
-		| "delete"
-		| "doctor"
-		| "cleanup"
-		| "events"
-		| "artifacts"
-		| "worktrees"
-		| "forget"
-		| "summary"
-		| "prune"
-		| "export"
-		| "import"
-		| "imports"
-		| "help"
-		| "validate"
-		| "config"
-		| "init"
-		| "recommend"
-		| "autonomy"
-		| "api"
-		| "settings"
-		| "steer"
-		| "invalidate"
-		| "health"
-		| "graph"
-		| "onboard"
-		| "explain"
-		| "cache"
-		| "checkpoint"
-		| "search"
-		| "orchestrate"
-		| "schedule"
-		| "scheduled"
-		| "anchor"
-		| "auto-summarize"
-		| "auto_boomerang"
-		| "goal"
-		| "workflow-create"
-		| "workflow-get"
-		| "workflow-list"
-		| "workflow-save"
-		| "workflow-delete";
+	action?: TeamAction;
 	resource?: "agent" | "team" | "workflow";
 	team?: string;
 	workflow?: string;

package/src/state/README.md

@@ -0,0 +1,44 @@
+# src/state/ — Cluster Map
+
+Persistent state layer for pi-crew runs. Organized into subdirectories by
+responsibility (Phase 7 reorg).
+
+## Root (shared infrastructure)
+
+| File | Responsibility |
+|------|---------------|
+| `types.ts` | Core state types (`TeamRunManifest`, `TeamTaskState`, schema versions) |
+| `types-eval.ts` | Evaluation-related types |
+| `contracts.ts` | Status transitions, task-status enums |
+| `tiered-eval.ts` | Tiered evaluation logic |
+| `crew-init.ts` | Crew initialization / bootstrap |
+| `decision-ledger.ts` | Decision recording |
+| `gitignore-manager.ts` | `.gitignore` management for crew dirs |
+| `hook-instinct-bridge.ts` | Bridge between hooks and instinct store |
+| `hook-integrations.ts` | Hook integration points |
+| `session-state-map.ts` | Session → state mapping |
+| `usage.ts` | Token/cost usage tracking |
+| `atomic-write.ts` | Atomic file writes (widely used — kept at root) |
+
+## `event-log/` — Event journaling
+
+Event append/read, rotation/compaction, JSONL writing, and worker-thread
+atomic writes.
+
+- `event-log.ts`, `event-log-rotation.ts`, `event-reconstructor.ts`,
+  `jsonl-writer.ts`, `worker-atomic-writer.ts`
+
+## `stores/` — Persisted data stores
+
+Manifest, artifact, blob, observation, health, instinct, run-graph/metrics
+stores, and the active-run registry.
+
+- `state-store.ts`, `run-cache.ts`, `artifact-store.ts`, `blob-store.ts`,
+  `observation-store.ts`, `health-store.ts`, `instinct-store.ts`,
+  `active-run-registry.ts`, `run-graph.ts`, `run-metrics.ts`
+
+## `coordination/` — Concurrency & IPC
+
+File locks, mailbox messaging, task scheduling, and task claims.
+
+- `locks.ts`, `mailbox.ts`, `schedule.ts`, `task-claims.ts`

package/src/state/atomic-write.ts

@@ -4,7 +4,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { logInternalError } from "../utils/internal-error.ts";
 import { sleepSync } from "../utils/sleep.ts";
-import { atomicWriteFileViaWorker, isWorkerAtomicWriterEnabled } from "./worker-atomic-writer.ts";
+import { atomicWriteFileViaWorker, isWorkerAtomicWriterEnabled } from "./event-log/worker-atomic-writer.ts";
 
 function hashContent(content: string): string {
 	return crypto.createHash("sha256").update(content, "utf-8").digest("hex");
@@ -596,8 +596,16 @@ export function atomicWriteFile(filePath: string, content: string, options?: Ato
 	// Write temp with restrictive permissions
 	const O_NOFOLLOW = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
 	let fd: number | undefined;
+	// ST-7: track the temp-file lifecycle independently of `fd`. `fd` is cleared
+	// (set to undefined) right after the successful close — BEFORE the rename
+	// attempt (line ~621) — so gating temp cleanup on `fd !== undefined` leaks
+	// the temp file when the rename fails. `tempNeedsCleanup` stays true from
+	// open until the rename consumes the temp, so the finally block always
+	// removes a leftover instead of being skipped by the stale `fd` guard.
+	let tempNeedsCleanup = false;
 	try {
 		fd = fs.openSync(tempPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | O_NOFOLLOW, mode ?? 0o600);
+		tempNeedsCleanup = true; // ST-7: temp file now exists on disk
 		// Post-open verification: on Windows O_NOFOLLOW is 0, so verify FD is a regular file
 		const openedStat = fs.fstatSync(fd);
 		if (!openedStat.isFile()) {
@@ -636,6 +644,10 @@ export function atomicWriteFile(filePath: string, content: string, options?: Ato
 			}
 			// Issue 1 fix: use link+unlink instead of rename to avoid following symlinks
 			renameWithLinkSync(tempPath, filePath);
+			// ST-7: rename consumed the temp file — it no longer exists at tempPath, so
+			// the finally block must NOT try to remove it (and must not be gated on
+			// `fd`, which is already undefined here from the close at line ~621).
+			tempNeedsCleanup = false;
 			// FIX (2026-07-01 mailbox-replay CI flake): fsync the parent directory
 			// after rename so the directory entry update is durable. On most Linux
 			// filesystems, rename is journaled but the journal flush isn't always
@@ -679,8 +691,12 @@ export function atomicWriteFile(filePath: string, content: string, options?: Ato
 			throw renameError;
 		}
 	} finally {
-		// Issue 4 fix: always clean up temp file, regardless of success or error path.
-		// This ensures no orphaned temp files remain when errors occur at any point.
+		// ST-7: temp cleanup must be gated on `tempNeedsCleanup` (whether a leftover
+		// temp file still exists), NOT on `fd !== undefined`. `fd` is set to undefined
+		// right after the successful close — BEFORE the rename attempt — so the old
+		// `fd !== undefined` guard skipped `rmSync(tempPath)` whenever the rename
+		// failed, leaking the temp file. `tempNeedsCleanup` is true from open until
+		// the rename consumes the temp, so this branch fires exactly when needed.
 		if (fd !== undefined) {
 			// A-02: close fd if still open before cleanup. If an error occurred
 			// between openSync and the normal closeSync (e.g. fstat/write/fsync
@@ -691,6 +707,8 @@ export function atomicWriteFile(filePath: string, content: string, options?: Ato
 			} catch {
 				/* fd may already be closed */
 			}
+		}
+		if (tempNeedsCleanup) {
 			try {
 				fs.rmSync(tempPath, { force: true });
 			} catch {
@@ -764,6 +782,9 @@ export async function atomicWriteFileAsync(filePath: string, content: string, op
 		// A-02: close fd if still open before cleanup. If an error occurred
 		// between open and the normal close (e.g. stat/writeFile/sync threw),
 		// the FileHandle would leak.
+		// ST-7: unlike the sync path, the async `rm(tempPath)` below is
+		// UNCONDITIONAL (not gated on `fd`), so a rename failure here does NOT
+		// leak the temp file. Verified during the ST-7 audit — no fix needed.
 		if (fd) {
 			try {
 				await fd.close();