pi-crew 0.9.57 → 0.9.59

package/src/runtime/team-runner.ts

@@ -1245,59 +1245,27 @@ async function cancelRunFromSignal(ctx: SchedulerContext): Promise<SchedulerDeci
  * @param ctx  The scheduler context; `ctx.tasks` and `ctx.manifest` are
  *             mutated in-place to reflect the rerun or abort.
  */
-async function handleFailedTask(ctx: SchedulerContext): Promise<SchedulerDecision | null> {
-	const failed = ctx.tasks.find((task) => task.status === "failed");
-	if (!failed) return null;
-
-	// #4 (assessment): honor limits.maxRetriesPerTask — re-queue an eligible
-	// failed task for a bounded whole-task rerun instead of immediately
-	// aborting the run. Before #4, the recovery ledger recorded `rerun_task`
-	// entries with state:"planned" but never executed them (decorative).
-	// Default-off: maxRetriesPerTask=0 → original abort behavior preserved.
-	const rerun = shouldRerunFailedTask(failed, ctx.input.limits);
-	if (rerun.rerun) {
-		ctx.tasks = ctx.tasks.map((item) =>
-			item.id === failed.id
-				? {
-						...item,
-						status: "queued" as const,
-						policy: {
-							...(item.policy ?? {}),
-							retryCount: rerun.newRetryCount,
-						},
-						error: undefined,
-						finishedAt: undefined,
-					}
-				: item,
-		);
-		await saveRunTasksAsync(ctx.manifest, ctx.tasks);
-		await appendEventAsync(ctx.manifest.eventsPath, {
-			type: "recovery.rerun_task",
-			runId: ctx.manifest.runId,
-			taskId: failed.id,
-			message: `Re-queuing failed task for whole-task rerun: ${rerun.reason}`,
-			data: {
-				attempt: rerun.newRetryCount,
-				maxRetries: ctx.input.limits?.maxRetriesPerTask ?? 0,
-				scenario: "task_failed",
-			},
-		});
-		return { kind: "continue" }; // loop re-processes the re-queued task
-	}
-	// RT-1: drain in-flight units and merge settled results BEFORE terminalising
-	// tasks. The streaming-dispatch path only adds to ctx.pendingUnits — it
-	// never updates ctx.tasks to "running" — so ctx.tasks is stale ("queued")
-	// for in-flight tasks. A direct saveRunTasksAsync would overwrite disk
-	// "running" with the stale "queued" status, then markBlocked maps that to
-	// "skipped". team resume never re-queues skipped tasks → permanent work
-	// loss. Draining first preserves settled results and gives non-settled
-	// in-flight tasks a re-queueable terminal status (cancelled, not skipped).
-	//
-	// #3 refactor: drainPendingUnits now RETURNS the settled outcomes directly,
-	// so we collect inflightTaskIds before draining (it clears the map), then
-	// consume the returned outcomes — no redundant re-await of the same promises.
-	// After drain, ctx.pendingUnits is empty, so the finally-block
-	// drainPendingUnits call (~:2419) is a no-op (idempotent — no double-drain).
+/**
+ * RT-NEW-2: terminalise a run as "failed" while draining in-flight dispatch
+ * units FIRST and merging their settled results under the run lock.
+ *
+ * Extracted verbatim from handleFailedTask (the FIXED reference) so every
+ * abort path behaves identically: drain pendingUnits (abort controller +
+ * await allSettled + clear), merge fulfilled outcomes into manifest/tasks
+ * under withRunLock (flushPendingAtomicWrites + loadRunManifestById +
+ * mergeArtifacts + mergeTaskUpdatesPreservingTerminal + save both), cancel
+ * (not skip) non-settled in-flight tasks so team resume can re-queue them,
+ * then markBlocked the remaining never-dispatched queued tasks.
+ *
+ * Previously enforceRunBudget skipped the drain+merge and called
+ * markBlocked directly — in-flight tasks (still "queued" in ctx.tasks since
+ * streaming dispatch never sets "running") were clobbered to "skipped",
+ * which team resume never re-queues → permanent work loss.
+ */
+async function terminaliseRunWithDrain(
+	ctx: SchedulerContext,
+	opts: { cancelMessage: string; blockedMessage: string; failedReason: string },
+): Promise<{ manifest: TeamRunManifest; tasks: TeamTaskState[] }> {
 	const inflightTaskIds = new Set<string>();
 	for (const unit of ctx.pendingUnits.values()) {
 		for (const id of unit.taskIds) inflightTaskIds.add(id);
@@ -1332,24 +1300,74 @@ async function handleFailedTask(ctx: SchedulerContext): Promise<SchedulerDecisio
 		ctx.manifest = mergeResult.resultManifest;
 		ctx.tasks = mergeResult.resultTasks;
 	}
-	// RT-1: cancel in-flight tasks that did NOT settle (e.g. rejected promises)
-	// so team resume CAN re-queue them. markBlocked maps queued→skipped, which
-	// resume never re-queues — work would be lost permanently. Only cancel
-	// tasks that are both in-flight AND still non-terminal (settled tasks with
-	// a terminal status are preserved).
+	// Cancel in-flight tasks that did NOT settle (e.g. rejected promises)
+	// so team resume CAN re-queue them. markBlocked maps queued→skipped,
+	// which resume never re-queues — work would be lost permanently. Only
+	// cancel tasks that are both in-flight AND still non-terminal (settled
+	// tasks with a terminal status are preserved).
 	ctx.tasks = cancelNonTerminalTasks(
 		ctx.tasks,
 		"cancelled",
-		`Cancelled by failed task '${failed.id}'.`,
+		opts.cancelMessage,
 		(task) => inflightTaskIds.has(task.id) && isNonTerminalTaskStatus(task.status),
 	);
-	// RT-1: remaining queued tasks (never dispatched) → skipped (original
-	// behavior preserved for downstream tasks not yet in-flight).
-	ctx.tasks = markBlocked(ctx.tasks, `Blocked by failed task '${failed.id}'.`);
+	// Remaining queued tasks (never dispatched) → skipped (original behavior
+	// preserved for downstream tasks not yet in-flight).
+	ctx.tasks = markBlocked(ctx.tasks, opts.blockedMessage);
 	await saveRunTasksAsync(ctx.manifest, ctx.tasks);
 	saveCrewAgents(ctx.manifest, recordsForMaterializedTasks(ctx.manifest, ctx.tasks, ctx.runtimeKind));
-	ctx.manifest = updateRunStatus(ctx.manifest, "failed", `Failed at task '${failed.id}'.`);
-	return { kind: "return", result: { manifest: ctx.manifest, tasks: ctx.tasks } };
+	ctx.manifest = updateRunStatus(ctx.manifest, "failed", opts.failedReason);
+	return { manifest: ctx.manifest, tasks: ctx.tasks };
+}
+
+async function handleFailedTask(ctx: SchedulerContext): Promise<SchedulerDecision | null> {
+	const failed = ctx.tasks.find((task) => task.status === "failed");
+	if (!failed) return null;
+
+	// #4 (assessment): honor limits.maxRetriesPerTask — re-queue an eligible
+	// failed task for a bounded whole-task rerun instead of immediately
+	// aborting the run. Before #4, the recovery ledger recorded `rerun_task`
+	// entries with state:"planned" but never executed them (decorative).
+	// Default-off: maxRetriesPerTask=0 → original abort behavior preserved.
+	const rerun = shouldRerunFailedTask(failed, ctx.input.limits);
+	if (rerun.rerun) {
+		ctx.tasks = ctx.tasks.map((item) =>
+			item.id === failed.id
+				? {
+						...item,
+						status: "queued" as const,
+						policy: {
+							...(item.policy ?? {}),
+							retryCount: rerun.newRetryCount,
+						},
+						error: undefined,
+						finishedAt: undefined,
+					}
+				: item,
+		);
+		await saveRunTasksAsync(ctx.manifest, ctx.tasks);
+		await appendEventAsync(ctx.manifest.eventsPath, {
+			type: "recovery.rerun_task",
+			runId: ctx.manifest.runId,
+			taskId: failed.id,
+			message: `Re-queuing failed task for whole-task rerun: ${rerun.reason}`,
+			data: {
+				attempt: rerun.newRetryCount,
+				maxRetries: ctx.input.limits?.maxRetriesPerTask ?? 0,
+				scenario: "task_failed",
+			},
+		});
+		return { kind: "continue" }; // loop re-processes the re-queued task
+	}
+	// RT-NEW-2: drain in-flight units + merge settled results, then cancel
+	// non-settled in-flight tasks and markBlocked the rest — via the shared
+	// terminaliseRunWithDrain helper (extracted from this function verbatim).
+	const result = await terminaliseRunWithDrain(ctx, {
+		cancelMessage: `Cancelled by failed task '${failed.id}'.`,
+		blockedMessage: `Blocked by failed task '${failed.id}'.`,
+		failedReason: `Failed at task '${failed.id}'.`,
+	});
+	return { kind: "return", result };
 }
 
 /**
@@ -2098,8 +2116,8 @@ async function advanceWorkflowPhases(ctx: SchedulerContext): Promise<void> {
  */
 async function enforceRunBudget(ctx: SchedulerContext): Promise<SchedulerDecision | null> {
 	const input = ctx.input;
-	let tasks = ctx.tasks;
-	let manifest = ctx.manifest;
+	const tasks = ctx.tasks;
+	const manifest = ctx.manifest;
 	// Per-task budget enforcement: check cumulative usage after each batch merge.
 	// This prevents a single task from consuming 100% of the budget before
 	// abort triggers (the goal-loop only checks at turn boundaries).
@@ -2121,12 +2139,16 @@ async function enforceRunBudget(ctx: SchedulerContext): Promise<SchedulerDecisio
 					threshold: "abort",
 				},
 			});
-			tasks = markBlocked(tasks, `Budget abort threshold exceeded: ${message}`);
-			await saveRunTasksAsync(manifest, tasks);
-			manifest = updateRunStatus(manifest, "failed", message);
-			ctx.tasks = tasks;
-			ctx.manifest = manifest;
-			return { kind: "return", result: { manifest, tasks } };
+			// RT-NEW-2: drain in-flight units + merge settled results before
+			// terminalising, so in-flight tasks become completed/cancelled (not
+			// skipped). Same shared helper handleFailedTask uses. Run-failed
+			// reason stays the budget message.
+			const result = await terminaliseRunWithDrain(ctx, {
+				cancelMessage: `Cancelled by budget abort: ${message}`,
+				blockedMessage: `Budget abort threshold exceeded: ${message}`,
+				failedReason: message,
+			});
+			return { kind: "return", result };
 		}
 
 		if (budgetCheck.warning) {

package/src/runtime/verification/completion-guard.ts

@@ -94,7 +94,16 @@ export function collectToolCallsFromEvent(event: unknown): Array<{ tool: string;
 }
 
 function transcriptText(input: CompletionMutationGuardInput): string {
-	if (input.transcriptPath && fs.existsSync(input.transcriptPath)) return fs.readFileSync(input.transcriptPath, "utf-8");
+	if (input.transcriptPath) {
+		try {
+			return fs.readFileSync(input.transcriptPath, "utf-8");
+		} catch (error) {
+			// NEW-P4: TOCTOU fix — only ENOENT (transcript deleted between check and read)
+			// falls back to stdout; any other read error propagates as before.
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") return input.stdout ?? "";
+			throw error;
+		}
+	}
 	return input.stdout ?? "";
 }
 

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

@@ -8,17 +8,69 @@ import { type TSchema, Type, TypeRegistry } from "@sinclair/typebox";
 // LLM tool definition) see the compact `{ type: "string", enum: [...] }`
 // (~600 chars vs ~1890 for anyOf+const), and Value.Check validates via
 // the registered predicate.
+//
+// GUARD (v0.9.58 — load-crash fix): TypeRegistry was added in
+// @sinclair/typebox@0.34.50. Pi installs ALL extensions into ONE shared
+// npm store with hoisted deps, and on update it only checks the extension's
+// own package.json version — if pi-crew is already latest, it does NOT re-
+// resolve transitive deps. So an install could land pi-crew@0.9.57 (which
+// needs TypeRegistry) over a stale hoisted @sinclair/typebox@0.34.49 (which
+// lacks it). Under ESM↔CJS interop, `import { TypeRegistry }` then resolves
+// to `undefined`, and the unguarded top-level `TypeRegistry.Set(...)` crashed
+// extension load: "Cannot read properties of undefined (reading 'Set')".
+//
+// We now feature-detect TypeRegistry and skip registration when it is absent;
+// buildStringEnum() falls back to a verbose-but-validating anyOf-of-literals
+// in that case, so the extension ALWAYS loads regardless of the store's
+// typebox. buildStringEnum() is exported so unit tests cover BOTH branches.
 // ─────────────────────────────────────────────────────────────────────────
-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 });
+
+// Feature-detect TypeRegistry.Set (typebox >= 0.34.50). Guarded so a stale
+// hoisted typebox (e.g. 0.34.49 in a shared npm store) cannot crash load.
+export const HAS_TYPE_REGISTRY =
+	typeof TypeRegistry === "object" && TypeRegistry !== null && typeof (TypeRegistry as { Set?: unknown }).Set === "function";
+
+/** Numeric-string regex: optional sign, integer part, optional decimal.
+ *  Accepts "0", "0.8", "5000", "-1", "42". Used by the optional numeric
+ *  fields below to accept the stringified forms pi-ai's tool-argument
+ *  coercion emits when a Union has a string-literal branch (Literal("")).
+ *  handleTeamTool coerces the string form back to a number before handlers
+ *  run, so the TeamToolParamsValue interface (which types these as number)
+ *  still holds at runtime. */
+const NUMERIC_STRING_RE = "^-?\\d+(\\.\\d+)?$";
+
+if (HAS_TYPE_REGISTRY) {
+	TypeRegistry.Set("StringEnum", (schema, value) => {
+		const s = schema as { enum?: unknown[] };
+		return typeof value === "string" && Array.isArray(s.enum) && s.enum.includes(value);
+	});
+}
+
+/**
+ * Build a compact `{ type: "string", enum: [...] }` action-enum schema that
+ * Value.Check can validate.
+ *
+ * - Registry branch (typebox >= 0.34.50): registered "StringEnum" kind →
+ *   compact enum (EXT-7 optimization, ~600 chars).
+ * - Fallback branch (stale hoisted typebox < 0.34.50): `anyOf` of
+ * `Type.Literal`s → ~3x larger JSON but natively validating with no custom
+ *   kind, so Value.Check still works. This is what keeps pi-crew loadable on
+ *   installs whose shared store still carries an older @sinclair/typebox.
+ *
+ * `hasRegistry` is injectable so unit tests exercise BOTH branches against the
+ * real typebox Type/Value (test/unit/schema/stringenum-typebox-guard.test.ts).
+ *
+ * Empty string is the unset marker (calling models emit "" for an omitted
+ * action; the handler treats it as "list"). It must be a plain member so
+ * JSON-Schema consumers (pi-ai validation) accept it without coercion.
+ */
+export function buildStringEnum(values: readonly string[], description: string, opts: { hasRegistry?: boolean } = {}): TSchema {
+	const hasRegistry = opts.hasRegistry ?? HAS_TYPE_REGISTRY;
+	if (hasRegistry) {
+		return Type.Unsafe({ [KIND]: "StringEnum", type: "string", enum: ["", ...values], description });
+	}
+	return Type.Union([Type.Literal(""), ...values.map((v) => Type.Literal(v))], { description });
 }
 
 // ───────────────────────────────────────────────────────────────────────────
@@ -160,7 +212,24 @@ const sharedFields = {
 		}),
 	),
 	replyFrom: Type.Optional(Type.String({ description: "Task ID sending the reply." })),
-	replyDeadline: Type.Optional(Type.Integer({ description: "Ms epoch deadline for a reply." })),
+	replyDeadline: Type.Optional(
+		// Allow the empty-string unset marker (models emit "" when no deadline is
+		// set; pi-ai validateToolArguments runs BEFORE the handler and rejects a
+		// bare Integer for ""). Mirror the other falsy-allowances (budgetTotal:0).
+		// Also accept stringified numbers ("123456") — pi-ai coercion stringifies
+		// numeric values when a Union has a string-literal branch. handleTeamTool
+		// coerces strings back to numbers before handlers run.
+		Type.Union(
+			[
+				Type.Literal(""),
+				Type.Integer({ description: "Ms epoch deadline for a reply." }),
+				Type.String({ pattern: NUMERIC_STRING_RE }),
+			],
+			{
+				description: "Ms epoch deadline for a reply.",
+			},
+		),
+	),
 	planPath: Type.Optional(
 		Type.String({
 			description: "Path to a markdown plan document for orchestration.",
@@ -174,9 +243,18 @@ const sharedFields = {
 		}),
 	),
 	interval: Type.Optional(
-		Type.Number({
-			description: "Interval in milliseconds between recurring scheduled runs.",
-		}),
+		// Empty-string unset marker accepted (models emit "" when no interval; pi-ai
+		// validateToolArguments rejects bare Number for "" before the handler runs).
+		// Also accept stringified numbers (pi-ai coercion); handleTeamTool coerces
+		// back to number.
+		Type.Union(
+			[
+				Type.Literal(""),
+				Type.Number({ description: "Interval in milliseconds between recurring scheduled runs." }),
+				Type.String({ pattern: NUMERIC_STRING_RE }),
+			],
+			{ description: "Interval in milliseconds between recurring scheduled runs." },
+		),
 	),
 	once: Type.Optional(
 		// Boolean false accepted: calling models emit false for unset; treated as omitted.
@@ -212,20 +290,44 @@ const sharedFields = {
 		}),
 	),
 	budgetWarning: Type.Optional(
-		Type.Number({
-			description:
-				"Budget warning threshold as a fraction (0-1). Default: 0.8 (80%). Emits warning event when this threshold is crossed.",
-			minimum: 0,
-			maximum: 1,
-		}),
+		// Empty-string unset marker accepted (Tier-9: models emit "" when unset).
+		// Also accept stringified numbers (pi-ai coercion); handleTeamTool coerces.
+		Type.Union(
+			[
+				Type.Literal(""),
+				Type.Number({
+					description:
+						"Budget warning threshold as a fraction (0-1). Default: 0.8 (80%). Emits warning event when this threshold is crossed.",
+					minimum: 0,
+					maximum: 1,
+				}),
+				Type.String({ pattern: NUMERIC_STRING_RE }),
+			],
+			{
+				description:
+					"Budget warning threshold as a fraction (0-1). Default: 0.8 (80%). Emits warning event when this threshold is crossed.",
+			},
+		),
 	),
 	budgetAbort: Type.Optional(
-		Type.Number({
-			description:
-				"Budget abort threshold as a fraction (0-1). Default: 0.95 (95%). Aborts further execution when this threshold is crossed.",
-			minimum: 0,
-			maximum: 1,
-		}),
+		// Empty-string unset marker accepted (Tier-9: models emit "" when unset).
+		// Also accept stringified numbers (pi-ai coercion); handleTeamTool coerces.
+		Type.Union(
+			[
+				Type.Literal(""),
+				Type.Number({
+					description:
+						"Budget abort threshold as a fraction (0-1). Default: 0.95 (95%). Aborts further execution when this threshold is crossed.",
+					minimum: 0,
+					maximum: 1,
+				}),
+				Type.String({ pattern: NUMERIC_STRING_RE }),
+			],
+			{
+				description:
+					"Budget abort threshold as a fraction (0-1). Default: 0.95 (95%). Aborts further execution when this threshold is crossed.",
+			},
+		),
 	),
 	runKind: Type.Optional(
 		Type.Union([Type.Literal(""), Type.Literal("team-run"), Type.Literal("goal-loop"), Type.Literal("dynamic-workflow")], {
@@ -234,11 +336,23 @@ const sharedFields = {
 		}),
 	),
 	tokenBudget: Type.Optional(
-		Type.Number({
-			description:
-				"Per-workflow token budget for dynamic-workflow runs. When set, ctx.agent() auto-rejects with ok:false once exhausted. Accumulated from each agent run's reported usage. Overrides workflow.maxTokenBudget.",
-			minimum: 0,
-		}),
+		// Empty-string unset marker accepted (Tier-9: models emit "" when unset).
+		// Also accept stringified numbers (pi-ai coercion); handleTeamTool coerces.
+		Type.Union(
+			[
+				Type.Literal(""),
+				Type.Number({
+					description:
+						"Per-workflow token budget for dynamic-workflow runs. When set, ctx.agent() auto-rejects with ok:false once exhausted. Accumulated from each agent run's reported usage. Overrides workflow.maxTokenBudget.",
+					minimum: 0,
+				}),
+				Type.String({ pattern: NUMERIC_STRING_RE }),
+			],
+			{
+				description:
+					"Per-workflow token budget for dynamic-workflow runs. When set, ctx.agent() auto-rejects with ok:false once exhausted. Accumulated from each agent run's reported usage. Overrides workflow.maxTokenBudget.",
+			},
+		),
 	),
 	args: Type.Optional(Type.Any()),
 	analysis: Type.Optional(
@@ -267,7 +381,7 @@ const sharedFields = {
 const ACTION_DESCRIPTION = "Team action. Defaults to 'list' when omitted.";
 
 const RUN_ACTIONS = ["run", "parallel", "plan", "orchestrate", "resume", "retry", "wait", "steer", "goal"] as const;
-const runActions = Type.Optional(stringEnum(RUN_ACTIONS, ACTION_DESCRIPTION));
+const runActions = Type.Optional(buildStringEnum(RUN_ACTIONS, ACTION_DESCRIPTION));
 
 const STATUS_ACTIONS = [
 	"status",
@@ -287,10 +401,10 @@ const STATUS_ACTIONS = [
 	"recommend",
 	"help",
 ] as const;
-const statusActions = Type.Optional(stringEnum(STATUS_ACTIONS, ACTION_DESCRIPTION));
+const statusActions = Type.Optional(buildStringEnum(STATUS_ACTIONS, ACTION_DESCRIPTION));
 
 const CONTROL_ACTIONS = ["cancel", "invalidate", "respond", "cleanup", "prune", "forget", "doctor"] as const;
-const controlActions = Type.Optional(stringEnum(CONTROL_ACTIONS, ACTION_DESCRIPTION));
+const controlActions = Type.Optional(buildStringEnum(CONTROL_ACTIONS, ACTION_DESCRIPTION));
 
 const MANAGE_ACTIONS = [
 	"create",
@@ -310,10 +424,10 @@ const MANAGE_ACTIONS = [
 	"imports",
 	"export",
 ] as const;
-const manageActions = Type.Optional(stringEnum(MANAGE_ACTIONS, ACTION_DESCRIPTION));
+const manageActions = Type.Optional(buildStringEnum(MANAGE_ACTIONS, ACTION_DESCRIPTION));
 
 const AUTOMATE_ACTIONS = ["schedule", "scheduled", "anchor", "auto-summarize", "auto_boomerang", "api"] as const;
-const automateActions = Type.Optional(stringEnum(AUTOMATE_ACTIONS, ACTION_DESCRIPTION));
+const automateActions = Type.Optional(buildStringEnum(AUTOMATE_ACTIONS, ACTION_DESCRIPTION));
 
 // ─── Domain schemas (additionalProperties: true — Phase 1, not tightened) ────
 
@@ -343,8 +457,8 @@ export const allActionLiterals = ([runActions, statusActions, controlActions, ma
 			(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.
+		// buildStringEnum 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 !== "");
 	},
 );
@@ -366,7 +480,7 @@ export type TeamAction =
 export const TeamToolParams = Type.Object(
 	{
 		action: Type.Optional(
-			stringEnum(
+			buildStringEnum(
 				allActionLiterals.map((l) => (l as { const: string }).const),
 				ACTION_DESCRIPTION,
 			),

package/src/skills/validate.ts

@@ -20,11 +20,16 @@
  * The validator runs once per skill at discovery. Discovery is already cached
  * (`CACHE_TTL_MS = 30_000` in discover-skills.ts) so the validation cost is
  * bounded regardless of how many skills exist.
+ *
+ * NEW-P5: the `yaml` package is now LAZY-LOADED on first parse (see getYaml)
+ * instead of imported at module load, so its ~280KB CJS graph only enters the
+ * process when a skill frontmatter is actually validated. The public sync API
+ * is unchanged.
  */
 
 import * as fs from "node:fs";
+import { createRequire } from "node:module";
 import * as path from "node:path";
-import yaml from "yaml";
 
 /**
  * Properties allowed in SKILL.md frontmatter.
@@ -57,6 +62,27 @@ const NAME_MAX_LEN = 64;
 const DESCRIPTION_MAX_LEN = 1024;
 const VERSION_REGEX = /^\d+\.\d+(\.\d+)?(-[A-Za-z0-9.-]+)?$/;
 
+// NEW-P5: lazy-load the `yaml` package on FIRST USE instead of at module load.
+// Skill validation is rare (once per skill at discovery, and discovery is
+// cached for 30s), but the `yaml` parser is ~280KB — eagerly importing it at
+// module load would pull its whole CJS graph (stringify/schema/parse) into
+// every cold start even when no skill frontmatter is ever validated. The
+// synchronous lazy pattern via createRequire keeps the public (sync) API of
+// parseSkillFrontmatter/validateSkillFrontmatter unchanged. In the esbuild
+// bundle, yaml is a bundled CJS module resolved through the injected
+// createRequire shim (same mechanism as utils/git.ts's hosted-git-info).
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+let yamlModule: typeof import("yaml") | undefined;
+function getYaml(): typeof import("yaml") {
+	if (!yamlModule) {
+		// LAZY: defer dynamic import of node:module to its call site.
+		const require = createRequire(import.meta.url);
+		// eslint-disable-next-line @typescript-eslint/no-require-imports
+		yamlModule = require("yaml") as typeof import("yaml");
+	}
+	return yamlModule;
+}
+
 /**
  * Structured error so callers (capability inventory, logs) can present
  * actionable diagnostics instead of silently dropping malformed skills.
@@ -104,7 +130,7 @@ export function parseSkillFrontmatter(content: string): { ok: true; data: Record
 	const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
 	if (!match) return { ok: true, data: {} };
 	try {
-		const parsed = yaml.parse(match[1]);
+		const parsed = getYaml().parse(match[1]);
 		if (parsed === null || parsed === undefined) return { ok: true, data: {} };
 		if (typeof parsed !== "object" || Array.isArray(parsed)) {
 			return {

package/src/state/atomic-write.ts

@@ -537,16 +537,16 @@ export type WriteDurability = "full" | "best-effort";
 /** Options accepted by atomicWriteFile (forward-compatible string | object form). */
 export type AtomicWriteOptions =
 	| string // legacy: expectedHash
-	| { expectedHash?: string; durability?: WriteDurability; mode?: number };
+	| { expectedHash?: string; durability?: WriteDurability; mode?: number; compact?: boolean };
 
-function normalizeOptions(arg: unknown): { expectedHash?: string; durability: WriteDurability; mode?: number } {
-	if (typeof arg === "string") return { expectedHash: arg, durability: "full", mode: undefined };
+function normalizeOptions(arg: unknown): { expectedHash?: string; durability: WriteDurability; mode?: number; compact?: boolean } {
+	if (typeof arg === "string") return { expectedHash: arg, durability: "full", mode: undefined, compact: undefined };
 	if (arg && typeof arg === "object") {
-		const o = arg as { expectedHash?: string; durability?: WriteDurability; mode?: number };
+		const o = arg as { expectedHash?: string; durability?: WriteDurability; mode?: number; compact?: boolean };
 		const durability: WriteDurability = o.durability === "best-effort" ? "best-effort" : "full";
-		return { expectedHash: o.expectedHash, durability, mode: o.mode };
+		return { expectedHash: o.expectedHash, durability, mode: o.mode, compact: o.compact };
 	}
-	return { durability: "full", mode: undefined };
+	return { durability: "full", mode: undefined, compact: undefined };
 }
 
 export function atomicWriteFile(filePath: string, content: string, options?: AtomicWriteOptions): void {
@@ -720,7 +720,7 @@ export function atomicWriteFile(filePath: string, content: string, options?: Ato
 
 export async function atomicWriteFileAsync(filePath: string, content: string, options?: AtomicWriteOptions): Promise<void> {
 	cancelPendingCoalescedWrite(filePath);
-	const { durability } = normalizeOptions(options);
+	const { durability, mode } = normalizeOptions(options);
 	// Phase 1.5 (RFC 15): when the worker-thread atomic writer is enabled
 	// (PI_CREW_WORKER_ATOMIC_WRITER=1), dispatch to a dedicated worker thread
 	// that performs SYNC fs ops with no internal yields. Mitigates the
@@ -736,7 +736,11 @@ export async function atomicWriteFileAsync(filePath: string, content: string, op
 	let fd: fs.promises.FileHandle | undefined;
 	try {
 		const O_NOFOLLOW = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
-		fd = await fs.promises.open(tempPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | O_NOFOLLOW, 0o600);
+		fd = await fs.promises.open(
+			tempPath,
+			fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | O_NOFOLLOW,
+			mode ?? 0o600,
+		);
 		// Post-open verification: on Windows O_NOFOLLOW is 0, so verify FD is a regular file
 		const openedStat = await fd.stat();
 		if (!openedStat.isFile()) {
@@ -802,11 +806,16 @@ export async function atomicWriteFileAsync(filePath: string, content: string, op
 }
 
 export function atomicWriteJson<T>(filePath: string, value: T, options?: AtomicWriteOptions): void {
-	atomicWriteFile(filePath, `${JSON.stringify(value, null, 2)}\n`, options);
+	// PERF-6: compact (no indentation) for machine-only state files — pretty-printing
+	// inflates them ~30-40%. Default stays pretty for human-debuggable files.
+	const { compact } = normalizeOptions(options);
+	atomicWriteFile(filePath, `${compact ? JSON.stringify(value) : JSON.stringify(value, null, 2)}\n`, options);
 }
 
 export async function atomicWriteJsonAsync<T>(filePath: string, value: T, options?: AtomicWriteOptions): Promise<void> {
-	await atomicWriteFileAsync(filePath, `${JSON.stringify(value, null, 2)}\n`, options);
+	// PERF-6: mirror the sync variant's compact knob.
+	const { compact } = normalizeOptions(options);
+	await atomicWriteFileAsync(filePath, `${compact ? JSON.stringify(value) : JSON.stringify(value, null, 2)}\n`, options);
 }
 
 // 2.1 — atomic-write coalescer. Buffer the latest payload per filePath and
@@ -871,14 +880,16 @@ export function atomicWriteJsonCoalesced<T>(
 		atomicWriteJson(filePath, value, options);
 		return;
 	}
-	const content = `${JSON.stringify(value, null, 2)}\n`;
+	// PERF-6: honor compact — normalize BEFORE serializing so the buffered content
+	// uses the caller's preferred formatting.
+	const normalized = normalizeOptions(options);
+	const content = `${normalized.compact ? JSON.stringify(value) : JSON.stringify(value, null, 2)}\n`;
 	const previous = pendingAtomicWrites.get(filePath);
 	if (previous) clearTimeout(previous.timer);
 	const timer = setTimeout(() => flushOnePendingAtomicWrite(filePath), coalesceMs);
 	timer.unref();
 	// Issue 2 fix: increment generation for each new entry
 	const generation = ++writeGeneration;
-	const normalized = normalizeOptions(options);
 	pendingAtomicWrites.set(filePath, {
 		content,
 		timer,

package/src/state/contracts.ts

@@ -81,6 +81,7 @@ export const TEAM_EVENT_TYPES = [
 	"worktree.dirty",
 	"async.spawned",
 	"async.started",
+	"async.signal",
 	"async.completed",
 	"async.failed",
 	"async.stale",