pi-crew 0.8.14 → 0.9.1

package/skills/orchestration/SKILL.md

@@ -15,7 +15,7 @@ Use this skill when orchestrating multi-phase tasks across pi-crew teams and wor
 
 ## Role definition
 
-You are the orchestrator — bạn là người điều phối, không phải người thực thi.
+You are the orchestrator — the coordinator, not the executor.
 
 You decompose, dispatch, verify, and iterate. You do NOT edit code directly. If you find yourself opening a file to fix a typo "real quick," stop — spawn a worker instead.
 
@@ -25,35 +25,35 @@ Adapted from oh-my-pi's orchestrate command pattern for pi-crew context.
 
 ### 1. Do not yield until everything is closed
 
-Không trả lại control khi vẫn còn việc chưa xong. Run every phase to completion. The orchestrator owns the full lifecycle — from first dispatch to final green gate.
+Do not yield control while work remains unfinished. Run every phase to completion. The orchestrator owns the full lifecycle — from first dispatch to final green gate.
 
 ### 2. Enumerate the full surface before dispatching
 
-Before writing any task packet, read every referenced file and understand the complete work surface. Liệt kê toàn bộ surface trước khi giao việc — không giao việc khi chưa hiểu hết scope.
+Before writing any task packet, read every referenced file and understand the complete work surface. Enumerate the entire surface before assigning work — do not assign work before you fully understand the scope.
 
 ### 3. Parallelize maximally
 
-Every set of edits with disjoint file scope MUST ship as one batch. Nếu 5 tasks chỉnh 5 file khác nhau và không phụ thuộc nhau, dispatch tất cả cùng lúc. Never serialize what can be parallelized.
+Every set of edits with disjoint file scope MUST ship as one batch. If 5 tasks edit 5 different files and are independent of one another, dispatch all of them at once. Never serialize what can be parallelized.
 
 ### 4. Each task assignment is self-contained
 
-Subagents have no shared context. Mỗi worker chỉ biết những gì bạn ghi trong task packet. Include all necessary context, file paths, constraints, and acceptance criteria in every task.
+Subagents have no shared context. Each worker only knows what you write in the task packet. Include all necessary context, file paths, constraints, and acceptance criteria in every task.
 
 ### 5. Verify after every phase before launching the next
 
-Run appropriate gates between phases: typecheck, tests, lint. Không bỏ qua verification — một phase đỏ không được phép chuyển sang phase tiếp theo.
+Run appropriate gates between phases: typecheck, tests, lint. Do not skip verification — a red phase must not advance to the next phase.
 
 ### 6. Commit policy — green only
 
-Commit after each green phase. Never commit a red tree. Chỉ commit khi tất cả gates pass. If the phase fails, fix it first.
+Commit after each green phase. Never commit a red tree. Only commit when all gates pass. If the phase fails, fix it first.
 
 ### 7. Respawn, do not absorb
 
-If a subagent returns incomplete or broken work, spawn a corrective subagent with a focused fix-up task packet. Không tự sửa lỗi của worker — respawn worker mới để sửa.
+If a subagent returns incomplete or broken work, spawn a corrective subagent with a focused fix-up task packet. Do not fix a worker's mistakes yourself — respawn a new worker to fix them.
 
 ### 8. No scope creep, no scope shrink
 
-Maintain the original scope exactly. Không mở rộng scope vì "thấy thêm việc," cũng không thu hẹp vì "tạm đủ." If scope needs to change, escalate to the requester.
+Maintain the original scope exactly. Do not expand scope because you "spot more work," and do not shrink it because "it's good enough for now." If scope needs to change, escalate to the requester.
 
 ## Workflow (7 steps)
 
@@ -69,7 +69,7 @@ Maintain the original scope exactly. Không mở rộng scope vì "thấy thêm
 - Materialize the full work surface as ordered phases.
 - For each phase, enumerate: files to touch, workers needed, dependencies on other phases.
 - Phases must be ordered by dependency; tasks within a phase must be independent (disjoint file scope).
-- Write the plan down — không giữ plan trong head.
+- Write the plan down — do not keep the plan in your head.
 
 ### Step 3 — Dispatch phase
 
@@ -117,7 +117,7 @@ If ANY answer is NO → Stop. Complete planning before dispatching.
 
 ## Anti-patterns
 
-These are the behaviours that kill orchestration quality — tránh xa:
+These are the behaviours that kill orchestration quality — avoid them:
 
 | Anti-pattern | Why it's wrong |
 |---|---|

package/src/agents/agent-config.ts

@@ -92,6 +92,10 @@ export interface AgentConfig {
 	effort?: "low" | "medium" | "high";
 	/** Tools to explicitly forbid for this agent. Takes precedence over allowedTools. */
 	disallowedTools?: string[];
+	/** Disable ALL tools (Pi `--no-tools`). Used by capability-locked agents like the goal-judge (P1)
+	 *  that must have NO agency — only emit a verdict. §0c C6: an empty `tools:[]` is INSUFFICIENT
+	 *  because pi-args.ts skips empty arrays, leaving default tools enabled. */
+	disableTools?: boolean;
 	disabled?: boolean;
 	override?: { source: "config"; path: string };
 }

package/src/config/config.ts

@@ -60,6 +60,7 @@ import type {
 	CrewToolsConfig,
 	CrewUiConfig,
 	CrewWorktreeConfig,
+	GoalWrapWorkflowConfig,
 	LoadedPiTeamsConfig,
 	PiTeamsAutonomousConfig,
 	PiTeamsAutonomyProfile,
@@ -912,6 +913,43 @@ function parseWorktreeConfig(value: unknown): CrewWorktreeConfig | undefined {
 		: undefined;
 }
 
+/** Parse goalWrap config (RFC v0.5 vision: apply goal completion-guarantee to builtins). */
+function parseGoalWrapConfig(
+	value: unknown,
+): Record<string, GoalWrapWorkflowConfig> | undefined {
+	const obj = asRecord(value);
+	if (!obj) return undefined;
+	const result: Record<string, GoalWrapWorkflowConfig> = {};
+	let hasAny = false;
+	for (const [workflowName, entry] of Object.entries(obj)) {
+		const entryObj = asRecord(entry);
+		if (!entryObj) continue;
+		const parsed: GoalWrapWorkflowConfig = {
+			enabled: parseWithSchema(Type.Boolean(), entryObj.enabled),
+			maxTurns: parseWithSchema(Type.Integer({ minimum: 1, maximum: 50 }), entryObj.maxTurns),
+			evaluatorModel: parseWithSchema(Type.String({ minLength: 1 }), entryObj.evaluatorModel),
+			budgetTotal: parseWithSchema(Type.Integer({ minimum: 1000 }), entryObj.budgetTotal),
+			budgetUnlimited: parseWithSchema(Type.Boolean(), entryObj.budgetUnlimited),
+		};
+		// Parse verification sub-object.
+		const verObj = asRecord(entryObj.verification);
+		if (verObj) {
+			const commands = Array.isArray(verObj.commands)
+				? verObj.commands.filter((c): c is string => typeof c === "string" && c.length > 0)
+				: undefined;
+			const mode = verObj.mode === "text-only" ? "text-only" as const : undefined;
+			if (commands || mode) {
+				parsed.verification = { ...(commands ? { commands } : { commands: [] }), ...(mode ? { mode } : {}) };
+			}
+		}
+		if (Object.values(parsed).some((v) => v !== undefined)) {
+			result[workflowName] = parsed;
+			hasAny = true;
+		}
+	}
+	return hasAny ? result : undefined;
+}
+
 function parseAgentOverride(value: unknown): AgentOverrideConfig | undefined {
 	const obj = asRecord(value);
 	if (!obj) return undefined;
@@ -1232,6 +1270,7 @@ export function parseConfig(raw: unknown): PiTeamsConfig {
 		runtime: parseRuntimeConfig(obj.runtime),
 		control: parseControlConfig(obj.control),
 		worktree: parseWorktreeConfig(obj.worktree),
+		goalWrap: parseGoalWrapConfig(obj.goalWrap),
 		agents: parseAgentsConfig(obj.agents),
 		tools: parseToolsConfig(obj.tools),
 		telemetry: parseTelemetryConfig(obj.telemetry),

package/src/config/types.ts

@@ -84,6 +84,16 @@ export interface CrewWorktreeConfig {
 	seedPaths?: string[];
 }
 
+/** Goal-wrap config (RFC v0.5 vision: apply `goal` completion-guarantee to builtin workflows). */
+export interface GoalWrapWorkflowConfig {
+	enabled?: boolean;
+	maxTurns?: number;
+	evaluatorModel?: string;
+	verification?: { commands: string[]; mode?: "text-only" };
+	budgetTotal?: number;
+	budgetUnlimited?: boolean;
+}
+
 export interface CrewUiConfig {
 	widgetPlacement?: "aboveEditor" | "belowEditor";
 	widgetMaxLines?: number;
@@ -217,6 +227,7 @@ export interface PiTeamsConfig {
 	runtime?: CrewRuntimeConfig;
 	control?: CrewControlConfig;
 	worktree?: CrewWorktreeConfig;
+	goalWrap?: Record<string, GoalWrapWorkflowConfig>;
 	agents?: CrewAgentsConfig;
 	tools?: CrewToolsConfig;
 	telemetry?: CrewTelemetryConfig;

package/src/extension/action-suggestions.ts

@@ -28,7 +28,8 @@ export const KNOWN_TEAM_ACTIONS = [
 	"config", "init", "recommend", "autonomy", "api", "settings", "steer",
 	"invalidate", "health", "graph", "onboard", "explain", "cache",
 	"checkpoint", "search", "orchestrate", "schedule", "scheduled", "anchor",
-	"auto-summarize", "auto_boomerang",
+	"auto-summarize", "auto_boomerang", "goal",
+	"workflow-create", "workflow-get", "workflow-list", "workflow-save", "workflow-delete",
 ] as const;
 
 /**

package/src/extension/async-notifier.ts

@@ -110,6 +110,16 @@ export function startAsyncRunNotifier(ctx: ExtensionContext, state: AsyncNotifie
 				const current = markDeadAsyncRunIfNeeded(run) ?? run;
 				if (!isFinished(current.status) || state.seenFinishedRunIds.has(current.runId)) continue;
 				state.seenFinishedRunIds.add(current.runId);
+				// Suppress notifications for INTERNAL goal-loop sub-runs.
+				// The outer goal-loop creates a synthetic 'goal-turn' workflow per turn
+				// (see buildTurnWorkflow in goal-loop-runner.ts). These runs are
+				// implementation details of the autonomous loop — the user only cares
+				// about the OUTER goal-loop's status (runKind:'goal-loop'), which has
+				// its own event stream + status command. Without this filter, every
+				// turn that hits e.g. a transient model rate limit triggers an
+				// alarming 'Error: pi-crew run failed' toast for an internal sub-run
+				// the user never started directly.
+				if (current.workflow === "goal-turn" && current.team.startsWith("goal-")) continue;
 				const level = current.status === "completed" ? "info" : current.status === "cancelled" ? "warning" : "error";
 				ctx.ui.notify(`pi-crew run ${current.status}: ${current.runId} (${current.team}/${current.workflow ?? "none"})`, level);
 			}

package/src/extension/help.ts

@@ -43,6 +43,20 @@ export function piTeamsHelp(): string {
 		"- /team-validate",
 		"- /team-help",
 		"",
+		"Goal loops (P0/P1 — autonomous goal loop):",
+		"- team action='goal' config.subAction='start' config.objective='...' config.evaluatorModel='...' [config.maxTurns=20] [budgetTotal=N]",
+		"- team action='goal' config.subAction='status' [config.goalId=<id>]",
+		"- team action='goal' config.subAction='pause|resume|stop|step|clear' config.goalId=<id>",
+		"",
+		"Dynamic workflows (P2/P3 — JS-script orchestration):",
+		"- Place a .dwf.ts under .crew/workflows/ then: team action='run' workflow='<name>' goal='...'",
+		"- team action='workflow-list'",
+		"- team action='workflow-get' config.name='<name>'",
+		"- team action='workflow-create' confirm=true config.name='<name>' config.script='<.dwf.ts source>'  (USER-initiated only; ACE-gated)",
+		"- team action='workflow-save' config.name='<name>' config.script='<source>'",
+		"- team action='workflow-delete' confirm=true config.name='<name>'",
+		"- /workflows — list dynamic workflows",
+		"",
 		"Real child workers are enabled by default. Use runtime.mode=scaffold or executeWorkers=false only for dry runs.",
 	].join("\n");
 }

package/src/extension/registration/commands.ts

@@ -381,6 +381,33 @@ export function registerTeamCommands(pi: ExtensionAPI, deps: RegisterTeamCommand
 		},
 	});
 
+	pi.registerCommand("team-goal", {
+		description: "Autonomous goal loop control: [start|status|pause|resume|stop|step|clear] [goalId] [--objective=...] [--evaluatorModel=...] [--maxTurns=N]",
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			const tokens = args.trim().split(/\s+/).filter(Boolean);
+			const knownSubs = new Set(["start", "status", "pause", "resume", "stop", "step", "clear", "cancel", "reset"]);
+			const subAction = tokens[0] && knownSubs.has(tokens[0]) ? tokens[0] : "status";
+			const positional = tokens.filter((token) => !token.includes("=") && !token.startsWith("--") && token !== subAction);
+			const goalId = positional[0];
+			const config: Record<string, unknown> = { subAction };
+			if (goalId) config.goalId = goalId;
+			for (const token of tokens.filter((item) => item.includes("="))) {
+				const [key, ...rest] = token.split("=");
+				if (key) config[key.replace(/^--/, "")] = parseScalar(rest.join("="));
+			}
+			const result = await handleTeamTool({ action: "goal", config }, teamCommandContext(ctx));
+			await notifyCommandResult(ctx, commandText(result));
+		},
+	});
+
+	pi.registerCommand("workflows", {
+		description: "List all workflows (static + dynamic .dwf.ts)",
+		handler: async (_args: string, ctx: ExtensionCommandContext) => {
+			const result = await handleTeamTool({ action: "workflow-list" }, teamCommandContext(ctx));
+			await notifyCommandResult(ctx, commandText(result));
+		},
+	});
+
 	pi.registerCommand("team-metrics", { description: "Show pi-crew metrics snapshot: [filter]", handler: async (args: string, ctx: ExtensionCommandContext) => {
 		const filter = args.trim() || undefined;
 		const result = await handleTeamTool({ action: "api", config: { operation: "metrics-snapshot", filter } }, { ...teamCommandContext(ctx), metricRegistry: deps.getMetricRegistry?.() });

package/src/extension/team-tool/destructive-gate.ts

@@ -20,7 +20,7 @@
  *  5. Otherwise → blocked with a reason telling the user what to pass.
  */
 
-export const DESTRUCTIVE_TEAM_ACTIONS = new Set(["delete", "forget", "prune", "cleanup"]);
+export const DESTRUCTIVE_TEAM_ACTIONS = new Set(["delete", "forget", "prune", "cleanup", "workflow-create", "workflow-save", "workflow-delete"]);
 
 export interface TeamToolInputLike {
 	action?: unknown;

package/src/extension/team-tool/goal-wrap.ts

@@ -0,0 +1,288 @@
+/**
+ * goal-wrap.ts — Apply the `goal` completion-guarantee to builtin workflows.
+ *
+ * RFC v0.5 vision: when `goalWrap[workflowName].enabled` is set in .crew/config.json,
+ * the builtin workflow runs as the WORKER TURN inside a goal loop (worker → judge →
+ * feedback → redo until achieved / maxTurns / budget / stuck).
+ *
+ * Design (A + D confirmed with user):
+ *   - OUTER wrap: the builtin workflow IS the worker turn (judge evaluates the whole thing)
+ *   - KEEP .workflow.md: no convert; the existing adaptive planner (e.g. `implementation`)
+ *     keeps its flexibility; we just re-run it per turn with the judge's feedback.
+ *   - Per-workflow toggle via team-setting config.
+ *
+ * Reuses the Phase 1 goal infrastructure: GoalStore, GoalLoopState, runGoalLoop. The
+ * builtin workflow's per-turn execution goes through executeTeamRun (same as a normal
+ * goal worker turn), so Phase 1's protections (integrity snapshot, budget guard,
+ * nonce-token feedback, worker cap, workspace lock) all apply.
+ */
+
+import { createRunPaths, saveRunManifest } from "../../state/state-store.ts";
+import { atomicWriteJson } from "../../state/atomic-write.ts";
+import { appendEvent } from "../../state/event-log.ts";
+import { spawnBackgroundTeamRun } from "../../subagents/async-entry.ts";
+import { GoalStore } from "../../runtime/goal-state-store.ts";
+import { snapshotManifests } from "../../runtime/verification-integrity.ts";
+import { logInternalError } from "../../utils/internal-error.ts";
+import { loadConfig } from "../../config/config.ts";
+import type { GoalLoopState, TeamRunManifest } from "../../state/types.ts";
+import type { GoalWrapWorkflowConfig } from "../../config/types.ts";
+import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
+import type { WorkflowConfig } from "../../workflows/workflow-config.ts";
+import { result, type TeamContext } from "./context.ts";
+
+/** Builtin workflows eligible for goal-wrap (have a clear "done" condition). */
+export const GOAL_WRAP_ELIGIBLE_BUILTINS = new Set([
+	"implementation",
+	"fast-fix",
+	"default",
+]);
+
+/**
+ * Maximum number of workflow steps allowed for goal-wrap.
+ *
+ * Multi-step workflows (>=2 steps in their .workflow.md definition) crash
+ * non-deterministically when run as goal-wrap worker turns in the background
+ * goal-loop process. Root cause: V8/libuv-level race during event-loop yields
+ * in the team-runner batch transition (see investigation commit a9f6e09 +
+ * Phase 1.5 RFC 15). Sync fs workarounds regress; worker-thread isolation
+ * doesn't help. The crash is NOT in fs writes.
+ *
+ * Decision: REFUSE goal-wrap for multi-step workflows rather than ship a
+ * feature with hidden non-deterministic crashes. Single-step workflows
+ * (e.g. implementation, which has only the adaptive `assess` step and
+ * injects more tasks via the adaptive planner) work reliably end-to-end.
+ *
+ * Users who want goal completion-guarantee on multi-step work should use
+ * `team action='run' workflow=<multi-step>` for the one-shot execution, or
+ * break the work into single-step goals.
+ */
+export const GOAL_WRAP_MAX_STEPS = 1;
+
+// GoalWrapWorkflowConfig is re-exported from config/types.ts (single source of truth).
+export type { GoalWrapWorkflowConfig };
+
+/** Read the goal-wrap config for a given workflow name (merged user + project config). */
+export function readGoalWrapConfig(
+	cwd: string,
+	workflowName: string,
+): GoalWrapWorkflowConfig | undefined {
+	const loaded = loadConfig(cwd);
+	const cfg = loaded.config?.goalWrap as Record<string, GoalWrapWorkflowConfig> | undefined;
+	if (!cfg) return undefined;
+	return cfg[workflowName];
+}
+
+/** Is goal-wrap enabled for this workflow (per config)? */
+export function isGoalWrapEnabled(cwd: string, workflowName: string): boolean {
+	if (!GOAL_WRAP_ELIGIBLE_BUILTINS.has(workflowName)) return false;
+	const wc = readGoalWrapConfig(cwd, workflowName);
+	return wc?.enabled === true;
+}
+
+/**
+ * Validate a goal-wrap config entry. Returns an error string if invalid, undefined if OK.
+ * Mirrors the Phase 1 validation: budget required (or unlimited), evaluatorModel required.
+ */
+export function validateGoalWrapConfig(
+	wc: GoalWrapWorkflowConfig,
+): string | undefined {
+	if (!wc.evaluatorModel) {
+		return "goalWrap config requires evaluatorModel (the goal-judge model). No silent default.";
+	}
+	const hasBudget = typeof wc.budgetTotal === "number" && wc.budgetTotal >= 1000;
+	if (!wc.budgetUnlimited && !hasBudget) {
+		return "goalWrap config requires either budgetTotal (>=1000) OR budgetUnlimited:true. No silent unbounded-spend default.";
+	}
+	if (wc.budgetUnlimited && hasBudget) {
+		return "goalWrap config: budgetTotal and budgetUnlimited are mutually exclusive.";
+	}
+	return undefined;
+}
+
+/**
+ * Start a goal-wrapped run. Creates a GoalLoopState + goal-loop manifest + spawns the
+ * background goal-loop process. The worker turn's workflow is the resolved builtin.
+ *
+ * The goal-loop-runner's buildTurnWorkflow() generates a 1-step "goal-turn" workflow; for
+ * goal-wrap we OVERRIDE that by storing the target workflow name on the GoalLoopState
+ * and having the runner use it per turn. (See the `team` field carry-through.)
+ */
+/**
+ * Persist `async: { pid, logPath, spawnedAt }` on a goal-loop manifest and write
+ * it atomically to disk. This is the missing piece that makes goal-loop runs
+ * detectable by async-notifier.markDeadAsyncRunIfNeeded — without it, the
+ * notifier returns early on `!run.async` and the goal appears to hang at "1/3"
+ * forever even after the background runner has died.
+ *
+ * Mirrors the normal-run path in run.ts:371-372 which writes the async field on
+ * the team-run manifest via `atomicWriteJson(paths.manifestPath, asyncManifest)`.
+ */
+export function persistAsyncOnGoalLoopManifest(
+	manifestPath: string,
+	manifest: TeamRunManifest,
+	spawned: { pid: number; logPath: string },
+): void {
+	const asyncGoalManifest = {
+		...manifest,
+		async: { pid: spawned.pid, logPath: spawned.logPath, spawnedAt: new Date().toISOString() },
+	};
+	atomicWriteJson(manifestPath, asyncGoalManifest);
+}
+/**
+ * Decide whether a workflow should be goal-wrapped.
+ *
+ * Returns one of:
+ *   { enabled: true }                          — goal-wrap is enabled AND safe
+ *   { enabled: false, reason: "config-off" }     — goal-wrap not enabled in config
+ *   { enabled: false, reason: "multi-step" }     — enabled but refused (multi-step
+ *                                                workflows crash non-deterministically
+ *                                                in the background goal-loop process
+ *                                                due to V8/libuv race; see GOAL_WRAP_MAX_STEPS)
+ *   { enabled: false, reason: "invalid-config" } — config present but invalid
+ *
+ * Use this in run.ts to decide whether to route to startGoalWrappedRun or fall
+ * through to the normal team-run path. NEVER refuse with an error — when
+ * goal-wrap is unsafe for a given workflow, silently fall back so the user
+ * still gets the workflow run they asked for.
+ */
+export function shouldGoalWrap(cwd: string, workflow: WorkflowConfig): { enabled: true } | { enabled: false; reason: "config-off" | "multi-step" | "invalid-config"; message?: string } {
+	const wc = readGoalWrapConfig(cwd, workflow.name);
+	if (!wc || wc.enabled !== true) {
+		return { enabled: false, reason: "config-off" };
+	}
+	const validationError = validateGoalWrapConfig(wc);
+	if (validationError) {
+		return { enabled: false, reason: "invalid-config", message: validationError };
+	}
+	if (workflow.steps.length > GOAL_WRAP_MAX_STEPS) {
+		return {
+			enabled: false,
+			reason: "multi-step",
+			message: `goal-wrap disabled for '${workflow.name}' (${workflow.steps.length} steps): multi-step workflows crash non-deterministically in the background goal-loop (V8/libuv race). Running as a normal one-shot team run instead.`,
+		};
+	}
+	return { enabled: true };
+}
+
+export async function startGoalWrappedRun(
+	params: TeamToolParamsValue,
+	ctx: TeamContext,
+	workflow: WorkflowConfig,
+	goal: string,
+): Promise<ReturnType<typeof result>> {
+	const cwd = ctx.cwd;
+	const wc = readGoalWrapConfig(cwd, workflow.name);
+	if (!wc || wc.enabled !== true) {
+		return result(`goal-wrap is not enabled for workflow '${workflow.name}' in .crew/config.json.`, { action: "run", status: "error" }, true);
+	}
+	const validationError = validateGoalWrapConfig(wc);
+	if (validationError) {
+		return result(`Invalid goalWrap config for '${workflow.name}': ${validationError}`, { action: "run", status: "error" }, true);
+	}
+
+	try {
+		const store = new GoalStore(cwd);
+		const goalId = store.createGoalId();
+		const ownerSessionId = ctx.sessionId ?? "unknown";
+		const now = new Date().toISOString();
+		const maxTurns = typeof wc.maxTurns === "number" && wc.maxTurns > 0 ? wc.maxTurns : 5; // goal-wrap default: tighter than standalone goal's 20
+
+		// P1a integrity snapshot (only when verification.commands declared).
+		const verification = wc.verification;
+		const isTextOnly = verification?.mode === "text-only" || !verification?.commands?.length;
+		let verificationIntegrity: GoalLoopState["verificationIntegrity"];
+		if (isTextOnly) {
+			verificationIntegrity = "none-text-only";
+		} else {
+			try {
+				verificationIntegrity = { snapshot: snapshotManifests(cwd), takenAt: now };
+			} catch (error) {
+				logInternalError("goal-wrap.integritySnapshot", error, `goalId=${goalId}`);
+				verificationIntegrity = "none-text-only";
+			}
+		}
+
+		const goalState: GoalLoopState = {
+			goalId,
+			ownerSessionId,
+			objective: goal,
+			state: "running",
+			maxTurns,
+			turnsUsed: 0,
+			budgetTotal: typeof wc.budgetTotal === "number" ? wc.budgetTotal : undefined,
+			budgetUnlimited: wc.budgetUnlimited || undefined,
+			budgetWarning: 0.8,
+			budgetAbort: 0.95,
+			budgetUsed: 0,
+			verificationIntegrity,
+			verification: verification as { commands: string[]; allowManualEvidence?: boolean } | undefined,
+			evaluatorModel: wc.evaluatorModel!,
+			workerAgent: params.agent ?? "executor",
+			workerModel: typeof params.model === "string" ? params.model : undefined,
+			team: typeof params.team === "string" ? params.team : undefined,
+			cwd,
+			verdicts: [],
+			history: [],
+			createdAt: now,
+			updatedAt: now,
+		};
+		// Carry the target workflow name so the runner uses it (not the default goal-turn).
+		// Stored on the state via a documented extension field.
+		(goalState as GoalLoopState & { goalWrapWorkflow?: string }).goalWrapWorkflow = workflow.name;
+		store.save(goalState);
+
+		const paths = createRunPaths(cwd, goalId);
+		const goalLoopManifest: TeamRunManifest = {
+			schemaVersion: 1,
+			runId: goalId,
+			sessionId: ownerSessionId,
+			team: `goal-wrap-${goalId}`,
+			workflow: "goal-loop",
+			goal,
+			status: "queued",
+			workspaceMode: "single",
+			createdAt: now,
+			updatedAt: now,
+			cwd,
+			stateRoot: paths.stateRoot,
+			artifactsRoot: paths.artifactsRoot,
+			tasksPath: paths.tasksPath,
+			eventsPath: paths.eventsPath,
+			artifacts: [],
+			ownerSessionId,
+			runKind: "goal-loop",
+		};
+		saveRunManifest(goalLoopManifest);
+		appendEvent(paths.eventsPath, { type: "goal.loop_start", runId: goalId, data: { goalId, objective: goal, maxTurns, goalWrapWorkflow: workflow.name } });
+
+		const spawned = await spawnBackgroundTeamRun(goalLoopManifest);
+		const pid = spawned.pid ?? 0;
+		// FIX: persist async.pid on the OUTER goal-loop manifest (not just goal state).
+		// Without this, async-notifier.markDeadAsyncRunIfNeeded returns early on
+		// `!run.async` and the user sees the goal hang at "1/3" forever even after the
+		// background runner dies (it currently dies silently due to a multi-step
+		// atomic-write bug — see investigation report). Mirrors run.ts:371-372 which
+		// writes asyncManifest = { ...effectiveManifest, async: {...} } to manifestPath.
+		persistAsyncOnGoalLoopManifest(paths.manifestPath, goalLoopManifest, { pid, logPath: spawned.logPath });
+		const withAsync = { ...goalState, async: { pid, logPath: spawned.logPath, spawnedAt: new Date().toISOString() } };
+		store.save(withAsync);
+
+		return result(
+			[
+				`Goal-wrapped '${workflow.name}' started (background pid=${pid}).`,
+				`Goal ${goalId} [running] — worker = '${workflow.name}' workflow, judged each turn by ${wc.evaluatorModel}.`,
+				`  turn: 0/${maxTurns}   budget: ${wc.budgetUnlimited ? "∞ (unlimited)" : `${wc.budgetTotal}`}`,
+				verification?.commands?.length ? `  verification: ${verification.commands.join(", ")}` : "  verification: text-only (no objective oracle)",
+				``,
+				`Next: \`team action='goal' config.subAction='status' config.goalId='${goalId}'\`.`,
+				`Log: ${spawned.logPath}`,
+			].join("\n"),
+			{ action: "run", status: "ok", runId: goalId, artifactsRoot: paths.artifactsRoot, data: { goalId, goalWrap: true, workflow: workflow.name, pid } },
+			false,
+		);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return result(`goal-wrap start failed: ${message}`, { action: "run", status: "error" }, true);
+	}
+}