pi-crew 0.8.14 → 0.9.1

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.

package/src/state/state-store.ts

@@ -227,6 +227,7 @@ export function createRunManifest(params: {
 	goal: string;
 	workspaceMode?: "single" | "worktree";
 	ownerSessionId?: string;
+	runKind?: "team-run" | "goal-loop" | "dynamic-workflow";
 }): { manifest: TeamRunManifest; tasks: TeamTaskState[]; paths: RunPaths } {
 	const paths = createRunPaths(params.cwd);
 	const now = new Date().toISOString();
@@ -249,6 +250,7 @@ export function createRunManifest(params: {
 		eventsPath: paths.eventsPath,
 		artifacts: [],
 		...(params.ownerSessionId ? { ownerSessionId: params.ownerSessionId } : {}),
+		runKind: params.runKind ?? "team-run",
 	};
 	fs.mkdirSync(paths.stateRoot, { recursive: true });
 	fs.mkdirSync(paths.artifactsRoot, { recursive: true });

package/src/state/types.ts

@@ -183,6 +183,8 @@ export interface TeamRunManifest {
 	runtimeResolution?: RuntimeResolutionState;
 	/** Effective run config snapshot used by async background workers. Optional for backward compatibility. */
 	runConfig?: unknown;
+	/** Background dispatch discriminator. Default "team-run" runs executeTeamRun; "goal-loop" / "dynamic-workflow" dispatch to their respective runners. Absent = "team-run" for backward compatibility. */
+	runKind?: "team-run" | "goal-loop" | "dynamic-workflow";
 	summary?: string;
 	policyDecisions?: PolicyDecision[];
 }
@@ -196,6 +198,86 @@ export interface UsageState {
 	turns?: number;
 }
 
+// ───────────────────────────────────────────────────────────────────────────
+// Goal loop types (P0/P1 — autonomous goal loop, Claude-Code-style /goal).
+// Spec: research-findings/goal-workflow/00-SPEC.md §2.3; plan 07-PLAN.md v3 §0b G2 + §0c.
+// ───────────────────────────────────────────────────────────────────────────
+
+/**
+ * Outer-state lifecycle of a goal loop. Inner per-turn state lives on each turn's TeamRunManifest.
+ *
+ * P1b (RFC v0.5 §P1b): `"stuck"` is NON-TERMINAL and RE-HINTABLE. Legal transitions:
+ *   running → stuck     (only by the background loop, after the oscillation detector fires)
+ *   stuck   → running   (only by `goal resume`, atomically via GoalStore.compareAndSetStatus)
+ *   stuck   → cancelled (by the idle-timeout sweeper OR `goal stop`)
+ */
+export type GoalLoopStatus =
+	| "running"
+	| "paused"
+	| "stuck"
+	| "achieved"
+	| "max_turns"
+	| "budget_exceeded"
+	| "blocked"
+	| "cancelled";
+
+/** One evaluation by the goal-judge model after a turn. */
+export interface GoalVerdict {
+	turn: number;
+	achieved: boolean;
+	/** "achieved: all tests pass" | "not-achieved: 2/8 tests failing" | "BLOCKED: <reason>" (BLOCKED: prefix → status='blocked'). */
+	reason: string;
+	evidenceRefs?: string[];
+	evaluatorModel: string;
+	evaluatedAt: string;
+}
+
+/** Persisted at <crewRoot>/state/goals/<goalId>.json by GoalStore. Survives session restart. */
+export interface GoalLoopState {
+	goalId: string;
+	ownerSessionId: string;
+	objective: string;
+	scope?: string;
+	/** Acceptance conditions as shell commands (exit 0 = pass). Reuses VerificationContract semantics. */
+	verification?: { commands: string[]; allowManualEvidence?: boolean };
+	state: GoalLoopStatus;
+	maxTurns: number;
+	turnsUsed: number;
+	budgetTotal?: number;
+	/** P1d (RFC v0.5 §P1d): when true, budget enforcement is skipped (explicit opt-out; audit-logged at start). */
+	budgetUnlimited?: boolean;
+	budgetWarning?: number;
+	budgetAbort?: number;
+	budgetUsed: number;
+	/**
+	 * P1a (RFC v0.5 §P1a): bookend integrity snapshot of project-manifest files
+	 * taken at goal start (only when verification.commands is declared). The
+	 * goal-loop-runner re-hashes before (T_snap) and after (T_verify_done) each
+	 * verification command to detect persistent manifest tampering. The literal
+	 * `"none-text-only"` marks goals started in text-only verification mode
+	 * (no objective oracle → no snapshot taken).
+	 */
+	verificationIntegrity?:
+		| { snapshot: Record<string, string>; takenAt: string }
+		| "none-text-only";
+	evaluatorModel: string;
+	workerModel?: string;
+	/** subagent_type / agent name for worker turns (default "executor"). */
+	workerAgent?: string;
+	team?: string;
+	cwd: string;
+	/** Feedback from turn N's verdict, prepended into turn N+1's manifest.goal (G1). */
+	nextTurnFeedback?: string;
+	/** The team-run of the current in-flight turn (for cancel/steer). */
+	currentRunId?: string;
+	verdicts: GoalVerdict[];
+	history: { runId: string; outcome: string; learnedAt: string; turn: number }[];
+	createdAt: string;
+	updatedAt: string;
+	/** Mirror of manifest.async for PID-liveness checks (cf. AsyncRunState). */
+	async?: { pid: number; logPath: string; spawnedAt: string };
+}
+
 export interface ModelAttemptState {
 	model: string;
 	success: boolean;

package/src/state/worker-atomic-writer.ts

@@ -0,0 +1,190 @@
+/**
+ * Phase 1.5 worker-thread atomic writer (RFC: 15-PHASE1.5-WORKER-WRITER-RFC.md).
+ *
+ * Background: multi-step goal-wrapped workflows crash silently and
+ * non-deterministically during batch transitions. The crash point moves to
+ * every `await` yield in the write path (mkdir, open, stat, rename,
+ * appendEvent). Sync replacements regress. Hypothesis: V8/libuv-level race
+ * during event-loop yields. Mitigation: route writes through a dedicated
+ * worker thread that performs SYNC fs operations with no internal yields.
+ *
+ * Opt-in via `PI_CREW_WORKER_ATOMIC_WRITER=1`. When disabled, callers fall
+ * back to the regular async path. Safe to ship behind a flag.
+ *
+ * Protocol (main → worker):
+ *   { kind: "write", id, filePath, content }
+ *   { kind: "mkdir", id, dirPath }
+ *   { kind: "append", id, filePath, content }
+ *
+ * Protocol (worker → main):
+ *   { kind: "done", id }
+ *   { kind: "error", id, message }
+ */
+import { Worker } from "node:worker_threads";
+import * as path from "node:path";
+import * as fs from "node:fs";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+
+let worker: Worker | undefined;
+let nextRequestId = 1;
+const pending = new Map<number, { resolve: () => void; reject: (e: Error) => void }>();
+
+/** Worker script source — runs SYNC fs ops with no internal yields. */
+const WORKER_SOURCE = `
+const { parentPort, workerData } = require("node:worker_threads");
+const fs = require("node:fs");
+const path = require("node:path");
+const crypto = require("node:crypto");
+
+function isSymlinkSafePath(filePath) {
+  try {
+    // Safe roots: the system temp dir (resolved through any symlinks, e.g.
+    // macOS /var → /private/var) and the current project cwd.
+    var tmpReal;
+    try { tmpReal = fs.realpathSync(require("node:os").tmpdir()); } catch (e2) { tmpReal = require("node:os").tmpdir(); }
+    var cwd = process.cwd();
+    // Accept a symlink ancestor as safe if the resolved target (a) IS a safe
+    // root, (b) is UNDER a safe root (target is a descendant), or (c) is an
+    // ANCESTOR of a safe root (target is a parent dir of a safe root).
+    // Case (c) is essential on macOS: /var → /private/var is an ancestor of
+    // the tmpdir /private/var/folders/…, so it must be allowed.
+    var isSafeAncestor = function (real) {
+      var roots = [tmpReal, cwd];
+      return roots.some(function (root) {
+        return real === root
+          || real.indexOf(root + path.sep) === 0
+          || root.indexOf(real + path.sep) === 0;
+      });
+    };
+    var currentPath = filePath;
+    while (currentPath !== path.dirname(currentPath)) {
+      var dir = path.dirname(currentPath);
+      try {
+        var stat = fs.lstatSync(dir);
+        if (stat.isSymbolicLink()) {
+          var real = fs.realpathSync(dir);
+          if (!isSafeAncestor(real)) return false;
+        }
+      } catch (e3) { /* not found — fine */ }
+      currentPath = dir;
+    }
+    return true;
+  } catch (e) { return true; }
+}
+
+function syncAtomicWriteFile(filePath, content) {
+  if (!isSymlinkSafePath(filePath)) throw new Error("Refusing to write: unsafe path: " + filePath);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tempPath = filePath + "." + crypto.randomUUID() + ".tmp";
+  try {
+    const fd = fs.openSync(tempPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o600);
+    try {
+      fs.writeFileSync(fd, content, "utf-8");
+    } finally {
+      fs.closeSync(fd);
+    }
+    fs.renameSync(tempPath, filePath);
+  } catch (error) {
+    try { fs.rmSync(tempPath, { force: true }); } catch {}
+    // If rename raced with another writer that produced identical content, swallow.
+    if (error && error.code === "EEXIST") {
+      try {
+        const existing = fs.readFileSync(filePath, "utf-8");
+        if (existing === content) return;
+      } catch {}
+    }
+    throw error;
+  }
+}
+
+function syncAppend(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.appendFileSync(filePath, content, "utf-8");
+}
+
+parentPort.on("message", (msg) => {
+  try {
+    if (msg.kind === "write") syncAtomicWriteFile(msg.filePath, msg.content);
+    else if (msg.kind === "mkdir") fs.mkdirSync(msg.dirPath, { recursive: true });
+    else if (msg.kind === "append") syncAppend(msg.filePath, msg.content);
+    else throw new Error("worker-atomic-writer: unknown message kind: " + msg.kind);
+    parentPort.postMessage({ kind: "done", id: msg.id });
+  } catch (error) {
+    parentPort.postMessage({ kind: "error", id: msg.id, message: error && error.message ? error.message : String(error) });
+  }
+});
+`;
+
+function getWorker(): Worker {
+	if (worker) return worker;
+	// Write worker source to a temp file (so Worker can load it as CJS via
+	// require() inside the worker, which always has CommonJS available).
+	const os = require("node:os");
+	const tmpPath = path.join(fs.mkdtempSync(path.join(os.tmpdir(), "pi-crew-waw-")), "worker.cjs");
+	fs.writeFileSync(tmpPath, WORKER_SOURCE, "utf-8");
+	worker = new Worker(tmpPath);
+	worker.on("message", (msg: { kind: string; id: number; message?: string }) => {
+		const entry = pending.get(msg.id);
+		if (!entry) return;
+		pending.delete(msg.id);
+		if (msg.kind === "done") entry.resolve();
+		else entry.reject(new Error(msg.message ?? "worker-atomic-writer: unknown error"));
+	});
+	worker.on("error", (error: Error) => {
+		// Reject ALL pending requests — worker died.
+		for (const [, entry] of pending) entry.reject(error);
+		pending.clear();
+	});
+	worker.unref(); // don't keep event loop alive (unless tests request it)
+	if (keepRefForTests) worker.ref();
+	return worker;
+}
+
+function dispatch(kind: "write" | "mkdir" | "append", payload: Record<string, unknown>): Promise<void> {
+	return new Promise((resolve, reject) => {
+		const id = nextRequestId++;
+		pending.set(id, { resolve, reject });
+		try {
+			getWorker().postMessage({ kind, id, ...payload });
+		} catch (error) {
+			pending.delete(id);
+			reject(error instanceof Error ? error : new Error(String(error)));
+		}
+	});
+}
+
+/** Whether the worker writer is enabled (env var opt-in). */
+export function isWorkerAtomicWriterEnabled(): boolean {
+	return process.env.PI_CREW_WORKER_ATOMIC_WRITER === "1" || process.env.PI_TEAMS_WORKER_ATOMIC_WRITER === "1";
+}
+
+/** Atomic-write a file via the worker thread. Sync fs ops inside worker. */
+export function atomicWriteFileViaWorker(filePath: string, content: string): Promise<void> {
+	return dispatch("write", { filePath, content });
+}
+
+/** Append to a file via the worker thread (used by event-log). */
+export function appendFileViaWorker(filePath: string, content: string): Promise<void> {
+	return dispatch("append", { filePath, content });
+}
+
+/** Terminate the worker (for tests / cleanup). */
+export function terminateWorkerAtomicWriter(): void {
+	if (worker) {
+		const w = worker;
+		worker = undefined;
+		w.terminate().catch(() => { /* ignore */ });
+	}
+	for (const [, entry] of pending) entry.reject(new Error("worker terminated"));
+	pending.clear();
+}
+
+/** Tests-only knob: keep the worker ref'd so the test runner doesn't exit
+ *  before promises resolve. Production code leaves this false (worker is
+ *  unref'd to avoid blocking process exit). */
+let keepRefForTests = false;
+export function __setKeepWorkerRefForTests(value: boolean): void {
+	keepRefForTests = value;
+}

package/src/utils/env-allowlist.ts

@@ -0,0 +1,30 @@
+/**
+ * Windows-essential environment variables that MUST be present in every
+ * subprocess env allowlist in pi-crew.
+ *
+ * Without them, child processes on Windows cannot locate the npm-global prefix
+ * (`%APPDATA%\npm`), the user profile, system DLLs (SystemRoot), cmd.exe
+ * (ComSpec), or a writable temp dir.
+ *
+ * Regression root cause (v0.9.0): env allowlists stripped these vars, so child
+ * pi/npm resolved the npm-global prefix via the literal `%APPDATA%` (cmd) /
+ * `${APPDATA}` (bash) expansion — but APPDATA was missing from the env, so the
+ * shell left the literal `${APPDATA}` in place. A phantom `${APPDATA}/npm`
+ * directory appeared in the project root and a literal `${APPDATA}` line leaked
+ * into `.gitignore`.
+ *
+ * USAGE: spread this constant into every `allowList` array:
+ *   `allowList: ["PATH", "HOME", ...WINDOWS_ESSENTIAL_ENV_VARS, ...]`
+ *
+ * The regression test `test/unit/env-allowlist.test.ts` enforces that no
+ * `src/` file hardcodes these vars inline — all sites MUST use this constant.
+ */
+export const WINDOWS_ESSENTIAL_ENV_VARS: readonly string[] = [
+	"APPDATA",
+	"LOCALAPPDATA",
+	"USERPROFILE",
+	"SystemRoot",
+	"ComSpec",
+	"TEMP",
+	"TMP",
+];