pi-crew 0.8.13 → 0.9.0

package/src/runtime/workspace-lock.ts

@@ -0,0 +1,448 @@
+/**
+ * workspace-lock.ts — Per-cwd workspace lock with startTime-safe liveness (P1g).
+ *
+ * RFC: research-findings/goal-workflow/13-VISION-RFC.md v0.5 §P1g + D10.
+ *
+ * Closes #8 (multi-goal clobber) and the B-2 PID-recycling gap. Each
+ * `workspaceMode:"single"` goal acquires this lock for its entire lifetime,
+ * serializing concurrent goals that share a cwd.
+ *
+ * Lockfile location: `<crewRoot>/state/workspace-locks/<sha256(absCwd)>.lock`
+ * Lockfile contents: { pid, startTime, heartbeat, goalId, acquiredAt }
+ *
+ * ─── LIVENESS = stale-reconciler startTime pattern (D10, B-2 fix) ───
+ * A lock is STALE iff EITHER:
+ *   (a) the recorded pid's CURRENT startTime ≠ the lockfile startTime
+ *       (the PID was recycled to a different process), OR
+ *   (b) the heartbeat is older than HEARTBEAT_STALE_MS (default 60s)
+ *       (the process crashed without exiting / heartbeat stopped).
+ *
+ * Why NOT child-pi.ts killProcessPid (B-2): killProcessPid uses
+ * process.kill(pid, 0) which is PID-only — vulnerable to PID recycling. The
+ * startTime + before/after re-verify pattern is TOCTOU-correct.
+ *
+ * getProcessStartTime is NOT exported from stale-reconciler.ts, so its logic
+ * is REPLICATED here (RFC §P1g explicitly permits importing OR replicating).
+ * The replication matches stale-reconciler.ts:112 field-for-field.
+ *
+ * Granularity: per-goal, held for the goal's lifetime (release() on goal end).
+ * Contention: default QUEUE (poll until released or stale);
+ *             opts.failOnWorkspaceBusy:true → THROW instead of queue.
+ */
+
+import { createHash } from "node:crypto";
+import {
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	readdirSync,
+	unlinkSync,
+	openSync,
+	closeSync,
+	statSync,
+	writeFileSync,
+} from "node:fs";
+import * as path from "node:path";
+import { atomicWriteJson } from "../state/atomic-write.ts";
+import { projectCrewRoot, userCrewRoot } from "../utils/paths.ts";
+
+/** Heartbeat staleness threshold (ms). Default 60s per RFC §P1g. */
+const DEFAULT_HEARTBEAT_STALE_MS = 60_000;
+
+/** Polling interval while queued waiting for a held lock (ms). */
+const DEFAULT_LOCK_POLL_MS = 500;
+
+/**
+ * Resolve a pid's process start time in ms, reusing the stale-reconciler
+ * pattern (src/runtime/stale-reconciler.ts:112). Returns undefined if the
+ * process is gone or /proc is unavailable (non-Linux). The absolute value
+ * matters less than its uniqueness per PID lifecycle. Used to detect PID
+ * recycling: a recycled PID has a different startTime than the recorded one.
+ *
+ * Callers (esp. tests) may inject a custom resolver to simulate PID recycling
+ * deterministically without spawning real processes.
+ */
+export type StartTimeResolver = (pid: number) => number | undefined;
+
+export const defaultStartTimeResolver: StartTimeResolver = (pid: number): number | undefined => {
+	try {
+		const stat = readFileSync(`/proc/${pid}/stat`, "utf-8");
+		const lastParen = stat.lastIndexOf(")");
+		if (lastParen === -1) return undefined;
+		const fieldsAfterComm = stat.slice(lastParen + 1).trim().split(/\s+/);
+		// starttime is at index 19 (the 20th field after comm) of /proc/<pid>/stat.
+		const startTimeClockTicks = Number(fieldsAfterComm[19]);
+		if (!Number.isFinite(startTimeClockTicks)) return undefined;
+		// Convert clock ticks to ms (~CLK_TCK). Absolute uniqueness is what matters.
+		return Math.floor(startTimeClockTicks * 10);
+	} catch {
+		return undefined;
+	}
+};
+
+/** Lockfile contents (persisted as JSON). */
+export interface WorkspaceLockContents {
+	pid: number;
+	startTime: number | undefined;
+	heartbeat: number;
+	goalId: string;
+	acquiredAt: string;
+}
+
+/**
+ * Opaque handle returned by acquireWorkspaceLock. Call release() to free the
+ * lock when the goal ends. release() is a no-op if the lock was already
+ * reclaimed/re-acquired by another goal (guarded by goalId + pid + startTime).
+ */
+export interface WorkspaceLockHandle {
+	readonly cwd: string;
+	readonly goalId: string;
+	readonly lockPath: string;
+	/** The startTime value written to the lockfile at acquire (release guard). */
+	readonly startTime: number | undefined;
+	release(): void;
+}
+
+export interface AcquireWorkspaceLockOptions {
+	/** Throw instead of queue when the workspace is already held (default: queue). */
+	failOnWorkspaceBusy?: boolean;
+	/** Override the heartbeat-staleness threshold (ms). */
+	heartbeatStaleMs?: number;
+	/** Override the polling interval while queued (ms). */
+	pollMs?: number;
+	/** Test injection: override process start time resolution. */
+	startTimeResolver?: StartTimeResolver;
+	/** Test injection: override current time (ms). Default Date.now(). */
+	now?: () => number;
+	/** Test injection: override the current pid. Default process.pid. */
+	pid?: number;
+	/** Abort waiting when this signal aborts. */
+	signal?: AbortSignal;
+}
+
+/**
+ * Resolve the lockfile path for a cwd. Lockfiles live under the project's
+ * `.crew/state/workspace-locks/` (or user crew-root fallback) and are named by
+ * the sha256 of the absolute cwd to avoid filesystem-unsafe characters and to
+ * normalize symlink-equivalent paths.
+ */
+export function workspaceLockPath(cwd: string): string {
+	const absCwd = path.resolve(cwd);
+	const crewRoot = projectCrewRoot(absCwd) ?? userCrewRoot();
+	const locksDir = path.join(crewRoot, "state", "workspace-locks");
+	const hash = createHash("sha256").update(absCwd).digest("hex");
+	return path.join(locksDir, `${hash}.lock`);
+}
+
+/** Read + parse a lockfile. Returns undefined if missing/corrupt. */
+function readLock(lockPath: string): WorkspaceLockContents | undefined {
+	if (!existsSync(lockPath)) return undefined;
+	try {
+		const parsed = JSON.parse(readFileSync(lockPath, "utf-8"));
+		if (!parsed || typeof parsed !== "object") return undefined;
+		return parsed as WorkspaceLockContents;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Write the lockfile atomically (temp+rename+fsync via atomicWriteJson).
+ * Used for HEARTBEAT refresh only (a claim that already owns the lock is refreshing its
+ * timestamp — overwrite is correct because the owner verified ownership first).
+ */
+function writeLock(lockPath: string, contents: WorkspaceLockContents): void {
+	mkdirSync(path.dirname(lockPath), { recursive: true });
+	atomicWriteJson(lockPath, contents);
+}
+
+/**
+ * CLAIM the lockfile atomically via O_EXCL (cold-review #3 NIT #N1 fix).
+ * The previous claim used temp+rename (writeLock), which is NOT cross-process atomic —
+ * two goals that both observed a free lock in the same tick could both writeLock and
+ * both believe they own it (the same class of TOCTOU cold-review #2 caught for CAS).
+ * O_EXCL (openSync "wx") IS atomic at the OS level: only one process can create the
+ * file. Returns true on success, false if the file already exists (EEXIST). Stale
+ * lockfiles older than the threshold are force-deleted + retried once.
+ */
+/**
+ * CLAIM the lockfile atomically via O_EXCL (cold-review #3 NIT #N1 fix).
+ * The previous claim used temp+rename (writeLock), which is NOT cross-process atomic —
+ * two goals that both observed a free/stale lock in the same tick could both writeLock
+ * and both believe they own it (the same class of TOCTOU cold-review #2 caught for CAS).
+ * O_EXCL (openSync "wx") IS atomic at the OS level: only one process can create the file.
+ *
+ * `forceOverwrite`: when the caller has ALREADY verified (via isLockStale) that the existing
+ * lock is logically stale (e.g. PID recycled — a stronger signal than mtime age), the caller
+ * passes forceOverwrite:true and claimLock unlinks then claims, bypassing the mtime age check.
+ * (Without this, a stale-by-PID-recycling lock whose mtime is recent would never be claimed,
+ *  because tryCreate sees EEXIST and the mtime age check fails — infinite re-queue = hang.)
+ *
+ * Returns true on success, false if the file already exists and is not stale.
+ */
+function claimLock(lockPath: string, contents: WorkspaceLockContents, staleReclaimMs: number, forceOverwrite = false): boolean {
+	mkdirSync(path.dirname(lockPath), { recursive: true });
+	const json = JSON.stringify(contents);
+	const tryCreate = (): boolean => {
+		try {
+			const fd = openSync(lockPath, "wx"); // O_EXCL — throws EEXIST if it exists.
+			try {
+				writeFileSync(fd, json);
+			} finally {
+				closeSync(fd);
+			}
+			return true;
+		} catch (error) {
+			const code = (error as NodeJS.ErrnoException).code;
+			if (code !== "EEXIST") throw error;
+			return false;
+		}
+	};
+	if (forceOverwrite) {
+		// Caller verified the existing lock is logically stale; remove it and claim. A concurrent
+		// reclaimer might re-create between our unlink and our open — that's fine, we lose the race
+		// and return false, falling through to the queue path.
+		try { unlinkSync(lockPath); } catch { /* best-effort */ }
+		return tryCreate();
+	}
+	if (tryCreate()) return true;
+	// Stale recovery by mtime age: if the lockfile is older than staleReclaimMs, force-delete + retry.
+	try {
+		const stat = statSync(lockPath);
+		if (Date.now() - stat.mtimeMs > staleReclaimMs) {
+			try { unlinkSync(lockPath); } catch { /* fall through */ }
+			return tryCreate();
+		}
+	} catch { /* fall through to false */ }
+	return false;
+}
+
+/**
+ * Is the lock STALE? RFC §P1g + D10 dual-check:
+ *   (a) startTime mismatch → PID recycled to a different process, OR
+ *   (b) heartbeat older than heartbeatStaleMs → crash w/o exit / abandoned.
+ *
+ * On platforms where startTime is unavailable (non-Linux), only the heartbeat
+ * check applies (weaker PID-reuse detection — documented platform limitation,
+ * matching stale-reconciler.ts).
+ */
+function isLockStale(
+	lock: WorkspaceLockContents,
+	resolveStartTime: StartTimeResolver,
+	heartbeatStaleMs: number,
+	now: number,
+): { stale: boolean; reason?: string } {
+	// (a) startTime mismatch → PID recycled to a different process.
+	if (lock.startTime !== undefined) {
+		const currentStartTime = resolveStartTime(lock.pid);
+		if (currentStartTime !== undefined && currentStartTime !== lock.startTime) {
+			return { stale: true, reason: "pid_recycled" };
+		}
+		// currentStartTime === undefined: process gone OR /proc unavailable →
+		// fall through to the heartbeat check (corroborating evidence).
+	}
+	// (b) heartbeat older than threshold → crash without exit / abandoned.
+	const heartbeatAge = now - lock.heartbeat;
+	if (heartbeatAge > heartbeatStaleMs) {
+		return { stale: true, reason: "heartbeat_stale" };
+	}
+	return { stale: false };
+}
+
+/**
+ * Acquire the workspace lock for `goalId` at `cwd`. If the lock is held by a
+ * live goal, the default behavior is QUEUE (poll until released or the holder
+ * goes stale); with opts.failOnWorkspaceBusy:true, throws instead.
+ *
+ * Stale locks (PID recycled or heartbeat expired) are reclaimed transparently.
+ *
+ * The returned handle's release() deletes the lockfile ONLY if it still
+ * belongs to this goal+pid+startTime — so a stale handle cannot clobber a
+ * lock reclaimed and re-acquired by another goal after this goal went stale.
+ *
+ * In-process serialization: the read→stale-check→write sequence is
+ * synchronous within one event-loop tick, so concurrent in-process acquires
+ * cannot both observe a free lock and both write (no interleave between the
+ * sync read and sync write).
+ */
+export async function acquireWorkspaceLock(
+	cwd: string,
+	goalId: string,
+	opts: AcquireWorkspaceLockOptions = {},
+): Promise<WorkspaceLockHandle> {
+	const lockPath = workspaceLockPath(cwd);
+	const resolveStartTime = opts.startTimeResolver ?? defaultStartTimeResolver;
+	const heartbeatStaleMs = opts.heartbeatStaleMs ?? DEFAULT_HEARTBEAT_STALE_MS;
+	const pollMs = opts.pollMs ?? DEFAULT_LOCK_POLL_MS;
+	const now = opts.now ?? Date.now;
+	const pid = opts.pid ?? process.pid;
+	const writtenStartTime = resolveStartTime(pid);
+
+	while (true) {
+		// Poll-loop: re-check the lock each tick until free/stale or aborted.
+		if (opts.signal?.aborted) {
+			throw new Error(
+				`workspace lock acquisition aborted for goal ${goalId} (cwd=${cwd})`,
+			);
+		}
+		const existing = readLock(lockPath);
+		// Classify the existing lock: "absent" / "stale" (PID recycled or heartbeat dead) / "live".
+		// Cold-review #3 NIT #N1 fix: when stale, pass forceOverwrite:true to claimLock so it
+		// unlinks the stale file before claiming. Without this, a stale-by-PID lock whose mtime
+		// is recent would never pass claimLock's mtime age check (it would return false) and the
+		// acquireWorkspaceLock poll loop would re-queue forever = hang.
+		const existingKind: "absent" | "stale" | "live" = !existing
+			? "absent"
+			: (isLockStale(existing, resolveStartTime, heartbeatStaleMs, now()).stale ? "stale" : "live");
+		if (existingKind !== "live") {
+			// Claim the lock (covers both no-lock and stale-lock cases).
+			// Cold-review #3 NIT #N1 fix: claim via O_EXCL (claimLock), NOT temp+rename — two
+			// processes racing past the isLockStale check could both writeLock and both believe
+			// they own the lock. claimLock atomically creates the file; if it returns false we
+			// lost the race, so fall through to the queue/re-throw path below.
+			const contents: WorkspaceLockContents = {
+				pid,
+				startTime: writtenStartTime,
+				heartbeat: now(),
+				goalId,
+				acquiredAt: new Date(now()).toISOString(),
+			};
+			const claimed = claimLock(lockPath, contents, heartbeatStaleMs, existingKind === "stale");
+			if (claimed) {
+				return {
+					cwd,
+					goalId,
+					lockPath,
+					startTime: writtenStartTime,
+					release(): void {
+						safeRelease(lockPath, goalId, pid, writtenStartTime);
+					},
+				};
+			}
+			// claimLock lost the race (another process claimed between our stale-check and
+			// our claim). Fall through to the busy path (throw or queue) — re-check next tick.
+		}
+		// Lock is held and live.
+		if (opts.failOnWorkspaceBusy) {
+			throw new Error(
+				`workspace busy: cwd=${cwd} held by goalId=${existing!.goalId} (pid=${existing!.pid})`,
+			);
+		}
+		// Queue: wait for the next poll interval, then re-check.
+		await sleepOrAbort(pollMs, opts.signal);
+	}
+}
+
+/**
+ * Delete the lockfile at `lockPath` only if it still belongs to
+ * (goalId, pid, startTime). A stale handle (whose lock was reclaimed and
+ * re-acquired by another goal) must NOT delete the new owner's lock.
+ */
+function safeRelease(
+	lockPath: string,
+	goalId: string,
+	pid: number,
+	writtenStartTime: number | undefined,
+): void {
+	try {
+		const current = readLock(lockPath);
+		if (
+			current &&
+			current.goalId === goalId &&
+			current.pid === pid &&
+			current.startTime === writtenStartTime
+		) {
+			unlinkSync(lockPath);
+		}
+	} catch {
+		/* best-effort — release must never throw into a finally block */
+	}
+}
+
+/** Sleep that resolves after `ms`, or rejects early if `signal` aborts. */
+function sleepOrAbort(ms: number, signal?: AbortSignal): Promise<void> {
+	if (!signal) return new Promise<void>((r) => setTimeout(r, ms));
+	return new Promise<void>((resolve, reject) => {
+		const timer = setTimeout(resolve, ms);
+		signal.addEventListener(
+			"abort",
+			() => {
+				clearTimeout(timer);
+				reject(new Error("workspace lock acquisition aborted"));
+			},
+			{ once: true },
+		);
+	});
+}
+
+/**
+ * Reclaim all stale locks under `dir` (the workspace-locks directory). Returns
+ * the list of reclaimed lock paths. Stale = PID recycled OR heartbeat older
+ * than threshold. Corrupt/unreadable locks are also reclaimed.
+ *
+ * Useful as a startup or periodic sweep to clear locks left by crashed
+ * processes before any goal tries to acquire them.
+ */
+/**
+ * Peek whether the workspace is currently locked by a live owner (without acquiring).
+ * Used by `goal start` / `goal resume` to fail-fast with a clear error BEFORE spawning.
+ * Returns the goalId of the current owner if busy, undefined if free (or lock missing).
+ */
+export function isWorkspaceBusy(
+	cwd: string,
+	opts: { startTimeResolver?: StartTimeResolver; heartbeatStaleMs?: number; now?: () => number } = {},
+): string | undefined {
+	const lockPath = workspaceLockPath(cwd);
+	const resolveStartTime = opts.startTimeResolver ?? defaultStartTimeResolver;
+	const heartbeatStaleMs = opts.heartbeatStaleMs ?? DEFAULT_HEARTBEAT_STALE_MS;
+	const now = opts.now ?? Date.now;
+	const existing = readLock(lockPath);
+	if (!existing) return undefined;
+	const { stale } = isLockStale(existing, resolveStartTime, heartbeatStaleMs, now());
+	return stale ? undefined : existing.goalId;
+}
+
+export function reclaimStaleLocks(
+	dir: string,
+	opts: {
+		heartbeatStaleMs?: number;
+		startTimeResolver?: StartTimeResolver;
+		now?: () => number;
+	} = {},
+): string[] {
+	const resolveStartTime = opts.startTimeResolver ?? defaultStartTimeResolver;
+	const heartbeatStaleMs = opts.heartbeatStaleMs ?? DEFAULT_HEARTBEAT_STALE_MS;
+	const now = opts.now ?? Date.now;
+	const reclaimed: string[] = [];
+	if (!existsSync(dir)) return reclaimed;
+	let entries: string[];
+	try {
+		entries = readdirSync(dir);
+	} catch {
+		return reclaimed;
+	}
+	for (const entry of entries) {
+		if (!entry.endsWith(".lock")) continue;
+		const lockPath = path.join(dir, entry);
+		const lock = readLock(lockPath);
+		if (!lock) {
+			// Corrupt/empty — reclaim.
+			try {
+				unlinkSync(lockPath);
+				reclaimed.push(lockPath);
+			} catch {
+				/* best-effort */
+			}
+			continue;
+		}
+		if (isLockStale(lock, resolveStartTime, heartbeatStaleMs, now()).stale) {
+			try {
+				unlinkSync(lockPath);
+				reclaimed.push(lockPath);
+			} catch {
+				/* best-effort */
+			}
+		}
+	}
+	return reclaimed;
+}

package/src/schema/config-schema.ts

@@ -59,6 +59,31 @@ export const PiTeamsWorktreeConfigSchema = Type.Object({
 	seedPaths: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
 }, { additionalProperties: false });
 
+/**
+ * Goal-wrap config (RFC v0.5 vision: apply `goal` completion-guarantee to builtin workflows).
+ * Per-workflow toggle. When enabled, a builtin workflow runs as the WORKER TURN inside a
+ * goal loop (worker → judge → feedback → redo until achieved / maxTurns / budget / stuck).
+ * Default OFF — opt-in per workflow. Only applies to builtin workflows that have a clear
+ * 'done' condition (implementation, fast-fix). Read-only workflows (review, research) are
+ * not goal-wrappable.
+ */
+export const GoalWrapWorkflowConfigSchema = Type.Object({
+	enabled: Type.Optional(Type.Boolean()),
+	maxTurns: Type.Optional(Type.Integer({ minimum: 1, maximum: 50 })),
+	evaluatorModel: Type.Optional(Type.String({ minLength: 1 })),
+	verification: Type.Optional(Type.Object({
+		commands: Type.Array(Type.String({ minLength: 1 })),
+		mode: Type.Optional(Type.Literal("text-only")),
+	}, { additionalProperties: false })),
+	budgetTotal: Type.Optional(Type.Integer({ minimum: 1000 })),
+	budgetUnlimited: Type.Optional(Type.Boolean()),
+}, { additionalProperties: false });
+
+export const PiTeamsGoalWrapConfigSchema = Type.Record(
+	Type.String({ minLength: 1 }),
+	GoalWrapWorkflowConfigSchema,
+);
+
 export const AgentOverrideSchema = Type.Object({
 	disabled: Type.Optional(Type.Boolean()),
 	model: Type.Optional(Type.Union([Type.String({ minLength: 1 }), Type.Literal(false)])),
@@ -152,6 +177,7 @@ export const PiTeamsConfigSchema = Type.Object({
 	runtime: Type.Optional(PiTeamsRuntimeConfigSchema),
 	control: Type.Optional(PiTeamsControlConfigSchema),
 	worktree: Type.Optional(PiTeamsWorktreeConfigSchema),
+	goalWrap: Type.Optional(PiTeamsGoalWrapConfigSchema),
 	agents: Type.Optional(PiTeamsAgentsConfigSchema),
 	tools: Type.Optional(PiTeamsToolsConfigSchema),
 	telemetry: Type.Optional(PiTeamsTelemetryConfigSchema),

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

@@ -72,6 +72,12 @@ export const TeamToolParams = Type.Object({
 				Type.Literal("anchor"),
 				Type.Literal("auto-summarize"),
 				Type.Literal("auto_boomerang"),
+				Type.Literal("goal"),
+				Type.Literal("workflow-create"),
+				Type.Literal("workflow-get"),
+				Type.Literal("workflow-list"),
+				Type.Literal("workflow-save"),
+				Type.Literal("workflow-delete"),
 			],
 			{ description: "Team action. Defaults to 'list' when omitted." },
 		),
@@ -244,8 +250,14 @@ export const TeamToolParams = Type.Object({
 	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: 1,
+				"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,
+		}),
+	),
+	budgetUnlimited: Type.Optional(
+		Type.Boolean({
+			description:
+				"When true, skip budget enforcement entirely (explicit opt-out). Goal-start validation requires budgetTotal>=1000 OR budgetUnlimited:true; audit-logged when set. The validation itself is enforced in a later integration task.",
 		}),
 	),
 	budgetWarning: Type.Optional(
@@ -264,6 +276,19 @@ export const TeamToolParams = Type.Object({
 			maximum: 1,
 		}),
 	),
+	runKind: Type.Optional(
+		Type.Union(
+			[
+				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.",
+			},
+		),
+	),
 });
 
 export interface TeamToolParamsValue {
@@ -312,7 +337,13 @@ export interface TeamToolParamsValue {
 		| "search"
 		| "orchestrate"
 		| "schedule"
-		| "scheduled";
+		| "scheduled"
+		| "goal"
+		| "workflow-create"
+		| "workflow-get"
+		| "workflow-list"
+		| "workflow-save"
+		| "workflow-delete";
 	resource?: "agent" | "team" | "workflow";
 	team?: string;
 	workflow?: string;
@@ -352,10 +383,14 @@ export interface TeamToolParamsValue {
 	once?: string | number;
 	/** Mark certain bash commands as excludeFromContext to reduce context tokens (default: false). */
 	excludeContextBash?: boolean;
-	/** Total token budget for the run. When set, enables budget tracking. */
+	/** Total token budget for the run. When set, enables budget tracking (minimum 1000). */
 	budgetTotal?: number;
+	/** When true, skip budget enforcement entirely (explicit opt-out). */
+	budgetUnlimited?: boolean;
 	/** Budget warning threshold as a fraction (0-1). Default: 0.8. */
 	budgetWarning?: number;
 	/** Budget abort threshold as a fraction (0-1). Default: 0.95. */
 	budgetAbort?: number;
+	/** Background dispatch discriminator. Default "team-run". "goal-loop"/"dynamic-workflow" dispatch to their runners (P0/P2). */
+	runKind?: "team-run" | "goal-loop" | "dynamic-workflow";
 }

package/src/state/atomic-write.ts

@@ -3,6 +3,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { logInternalError } from "../utils/internal-error.ts";
+import { isWorkerAtomicWriterEnabled, atomicWriteFileViaWorker } from "./worker-atomic-writer.ts";
 import { sleepSync } from "../utils/sleep.ts";
 
 function hashContent(content: string): string {
@@ -380,6 +381,14 @@ export function atomicWriteFile(filePath: string, content: string, expectedHash?
 
 
 export async function atomicWriteFileAsync(filePath: string, content: string): Promise<void> {
+	// 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
+	// non-deterministic V8/libuv crash during event-loop yields in multi-step
+	// goal-wrapped workflows.
+	if (isWorkerAtomicWriterEnabled()) {
+		return atomicWriteFileViaWorker(filePath, content);
+	}
 	if (!isSymlinkSafePath(filePath)) throw new Error(`Refusing to write: target is a symlink or inside untrusted directory: ${filePath}`);
 	await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
 	const tempPath = `${filePath}.${crypto.randomUUID()}.tmp`;

package/src/state/contracts.ts

@@ -77,6 +77,20 @@ const TEAM_EVENT_TYPES = [
 	"phase.completed",
 	"phase.skipped",
 	"phase.failed",
+	// Goal loop events (P0/P1) — autonomous goal-loop coordinator.
+	"goal.loop_start",
+	"goal.turn_start",
+	"goal.turn_evaluated",
+	"goal.budget_warning",
+	"goal.loop_end",
+	"goal.feedback_steered",
+	"goal.state_changed",
+	// Dynamic workflow events (P2) — script-driven orchestration.
+	"dwf.started",
+	"dwf.phase_started",
+	"dwf.phase_completed",
+	"dwf.completed",
+	"dwf.failed",
 ] as const;
 export type TeamEventType = typeof TEAM_EVENT_TYPES[number];
 

package/src/state/crew-init.ts

@@ -22,8 +22,19 @@ import { updateGitignore } from "./gitignore-manager.ts";
 // Re-export updateGitignore for backwards compatibility with tests.
 export { updateGitignore };
 
-/** README content for the .crew directory. */
-const CREW_README = `# .crew — pi-crew Runtime Directory
+/**
+ * README content for the .crew directory.
+ *
+ * Defined as a function (not a `const`) to avoid the Temporal Dead Zone race
+ * documented in issue #28 + RFC 17. When this module is loaded via
+ * `jiti.import()` (pi's extension loader) wrapped in an async function, a
+ * `const` initializer can be hit in TDZ by functions hoisted above it (the
+ * same pattern that bit `crewInitPromise` in team-tool/run.ts — see commit
+ * fixing it). A function declaration is hoisted with its body available
+ * immediately, so callers always get the fully-built string.
+ */
+function buildCrewReadme(): string {
+	return `# .crew — pi-crew Runtime Directory
 
 This directory contains pi-crew runtime state and artifacts.
 
@@ -50,7 +61,7 @@ To clear cache:
 team action='cache' action='clear'
 \`\`\`
 `;
-
+}
 /**
  * Find the project root by walking up from start directory.
  * Inline implementation to avoid module dependency on paths.ts.
@@ -249,13 +260,15 @@ export async function ensureCrewDirectory(cwd: string): Promise<void> {
 	}
 
 	// 3. Write README.md (always overwrite to keep it current)
-	fs.writeFileSync(safeJoin(crewRoot, "README.md"), CREW_README, "utf-8");
+	fs.writeFileSync(safeJoin(crewRoot, "README.md"), buildCrewReadme(), "utf-8");
 
 	// 4. Update .gitignore at project root
 	const repoRoot = findProjectRoot(cwd);
 	if (repoRoot) {
 		const gitignorePath = safeJoin(repoRoot, ".gitignore");
-		await updateGitignore(gitignorePath);
+		// LAZY: dodge the jiti ESM/CJS interop TDZ race on the static `import { updateGitignore }` above (issue #28, RFC 17). At this point the module body has fully evaluated, so the dynamic import resolves to a live binding.
+		const { updateGitignore: updateGitignoreFn } = await import("./gitignore-manager.ts");
+		await updateGitignoreFn(gitignorePath);
 	}
 }
 

package/src/state/event-log.ts

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { isWorkerAtomicWriterEnabled, appendFileViaWorker } from "./worker-atomic-writer.ts";
 import { DEFAULT_EVENT_LOG } from "../config/defaults.ts";
 import { atomicWriteFile } from "./atomic-write.ts";
 import { errors } from "../errors.ts";
@@ -443,7 +444,12 @@ export async function appendEventAsync(eventsPath: string, event: AppendTeamEven
 
 		if (!skippedDueToSize) {
 			const line = JSON.stringify(redactSecrets(fullEvent)) + "\n";
-			await fs.promises.appendFile(eventsPath, line, { encoding: "utf-8", flag: "a" });
+			// Phase 1.5: when worker atomic writer is enabled, append via worker.
+			if (isWorkerAtomicWriterEnabled()) {
+				await appendFileViaWorker(eventsPath, line);
+			} else {
+				await fs.promises.appendFile(eventsPath, line, { encoding: "utf-8", flag: "a" });
+			}
 			// FIX: fsync to ensure event content is flushed to disk before persisting
 			// the sequence number. This closes the crash window between appendFile and
 			// persistSequence where sequence reuse could occur on restart.