pi-crew 0.9.53 → 0.9.55

package/src/extension/crew-vibes/speed.ts

@@ -0,0 +1,286 @@
+import type { SpeedConfig } from "./config.ts";
+
+/**
+ * Token-speed engine ported from pi-speeed (MIT, attribution in NOTICE.md).
+ * Tracks output tok/s with a sliding window and suppresses unreliable
+ * burst-only readings. No stats/font handling — just the live + session avg.
+ */
+
+export type TokenEvent = { time: number; tokens: number };
+
+const COMPACTION_THRESHOLD = 5000;
+
+export type EngineConfig = Pick<SpeedConfig, "slidingWindowMs" | "minReliableDurationMs" | "maxDisplayTokS">;
+
+export function estimateTokensFromDelta(text: string): number {
+	if (!text) return 0;
+	const matches = text.match(/\w+|[^\s\w]/g);
+	return matches ? matches.length : 0;
+}
+
+export class TokenSpeedEngine {
+	private _isStreaming = false;
+	private _tokenCount = 0;
+	private _startTime = 0;
+	private _endTime = 0;
+	private _events: TokenEvent[] = [];
+	private _windowStartIndex = 0;
+	private _lastStableTokS = 0;
+	private _lastUsageOutput = 0;
+	private _config: EngineConfig;
+
+	constructor(config: EngineConfig) {
+		this._config = config;
+	}
+
+	updateConfig(config: EngineConfig): void {
+		this._config = config;
+	}
+
+	get isStreaming(): boolean {
+		return this._isStreaming;
+	}
+
+	get tokenCount(): number {
+		return this._tokenCount;
+	}
+
+	get elapsedMs(): number {
+		if (this._startTime === 0) return 0;
+		return this._isStreaming ? Date.now() - this._startTime : this._endTime - this._startTime;
+	}
+
+	get avgTokS(): number {
+		const elapsedSec = this.elapsedMs / 1000;
+		if (elapsedSec <= 0) return 0;
+		return this._tokenCount / elapsedSec;
+	}
+
+	sanitizeTokS(value: number | null, durationMs = this.elapsedMs): number | null {
+		if (value === null || !Number.isFinite(value) || value <= 0) return null;
+		if (durationMs < this._config.minReliableDurationMs) return null;
+		if (value > this._config.maxDisplayTokS) return null;
+		return value;
+	}
+
+	get tokS(): number {
+		const candidate = this.rawTokS;
+		const stable = this.sanitizeTokS(candidate);
+		if (stable !== null) this._lastStableTokS = stable;
+		return this._lastStableTokS;
+	}
+
+	get rawTokS(): number {
+		if (this.elapsedMs < this._config.slidingWindowMs) return this.avgTokS;
+		if (!this._isStreaming) return this.avgTokS;
+
+		const now = Date.now();
+		const windowStart = now - this._config.slidingWindowMs;
+
+		while (this._windowStartIndex < this._events.length && this._events[this._windowStartIndex].time < windowStart) {
+			this._windowStartIndex++;
+		}
+
+		if (this._windowStartIndex >= this._events.length) return this.avgTokS;
+
+		let windowTokenCount = 0;
+		for (let i = this._windowStartIndex; i < this._events.length; i++) {
+			windowTokenCount += this._events[i].tokens;
+		}
+		if (windowTokenCount === 0) return this.avgTokS;
+
+		const windowDuration = (now - this._events[this._windowStartIndex].time) / 1000;
+		if (windowDuration <= 0) return 0;
+
+		return windowTokenCount / windowDuration;
+	}
+
+	start(): void {
+		this._tokenCount = 0;
+		this._isStreaming = true;
+		this._startTime = Date.now();
+		this._endTime = this._startTime;
+		this._events = [];
+		this._windowStartIndex = 0;
+		this._lastStableTokS = 0;
+		this._lastUsageOutput = 0;
+	}
+
+	stop(): void {
+		this._isStreaming = false;
+		this._endTime = Date.now();
+		this._events = [];
+		this._windowStartIndex = 0;
+	}
+
+	recordDelta(delta: string, usageOutput?: number): void {
+		if (!this._isStreaming) return;
+		if (usageOutput !== undefined && usageOutput > 0) {
+			// usageOutput may be cumulative across message_update events. Track the
+			// delta to avoid inflating _tokenCount by N× the true total.
+			const increment = usageOutput - this._lastUsageOutput;
+			this._lastUsageOutput = usageOutput;
+			this.recordTokens(Math.max(0, increment));
+			return;
+		}
+		this.recordTokens(estimateTokensFromDelta(delta));
+	}
+
+	reconcileTotal(tokens: number): void {
+		if (tokens > 0) this._tokenCount = tokens;
+	}
+
+	recordTokens(tokens: number): void {
+		if (!this._isStreaming || tokens <= 0) return;
+		this._tokenCount += tokens;
+		this._events.push({ time: Date.now(), tokens });
+		if (this._windowStartIndex >= COMPACTION_THRESHOLD) this.compact();
+	}
+
+	private compact(): void {
+		if (this._windowStartIndex === 0) return;
+		this._events = this._events.slice(this._windowStartIndex);
+		this._windowStartIndex = 0;
+	}
+}
+
+export type CompletedMessageSpeed = {
+	outputTokens: number;
+	durationMs: number;
+	tokS: number | null;
+};
+
+function isSuccessfulStop(stopReason: string | undefined): boolean {
+	return stopReason !== "error" && stopReason !== "aborted";
+}
+
+export class SpeedTracker {
+	private readonly engine: TokenSpeedEngine;
+	private lastStableTokS: number | null = null;
+	private sessionOutputTokens = 0;
+	private sessionDurationMs = 0;
+
+	constructor(config: SpeedConfig) {
+		this.engine = new TokenSpeedEngine(config);
+	}
+
+	updateConfig(config: SpeedConfig): void {
+		this.engine.updateConfig(config);
+	}
+
+	get isStreaming(): boolean {
+		return this.engine.isStreaming;
+	}
+
+	get lastTokS(): number | null {
+		return this.lastStableTokS;
+	}
+
+	resetSession(): void {
+		this.sessionOutputTokens = 0;
+		this.sessionDurationMs = 0;
+	}
+
+	startMessage(): void {
+		this.engine.start();
+	}
+
+	recordDelta(delta: string, usageOutput?: number): void {
+		this.engine.recordDelta(delta, usageOutput);
+	}
+
+	stopMessage(): void {
+		if (this.engine.isStreaming) this.engine.stop();
+	}
+
+	liveTokS(): number | null {
+		const speed = this.engine.tokS;
+		return speed > 0 ? speed : this.lastStableTokS;
+	}
+
+	sessionAvgTokS(): number | null {
+		return this.sessionDurationMs > 0 ? this.sessionOutputTokens / (this.sessionDurationMs / 1000) : null;
+	}
+
+	finishMessage(outputTokens: number, stopReason: string | undefined): CompletedMessageSpeed | null {
+		if (!this.engine.isStreaming) return null;
+
+		this.engine.reconcileTotal(outputTokens);
+		const durationMs = this.engine.elapsedMs;
+		const tokens = this.engine.tokenCount;
+		const rawAvgTokS = durationMs > 0 ? tokens / (durationMs / 1000) : null;
+		const tokS = this.engine.sanitizeTokS(rawAvgTokS, durationMs);
+		this.lastStableTokS = tokS;
+		this.engine.stop();
+
+		if (tokS !== null && isSuccessfulStop(stopReason)) {
+			this.sessionOutputTokens += tokens;
+			this.sessionDurationMs += durationMs;
+		}
+
+		return { outputTokens: tokens, durationMs, tokS };
+	}
+}
+
+export class SpeedAnimator {
+	private from: number | null = null;
+	private target: number | null = null;
+	private startedAt = 0;
+	private durationMs: number;
+
+	constructor(durationMs: number) {
+		this.durationMs = durationMs;
+	}
+
+	updateDuration(durationMs: number): void {
+		this.durationMs = durationMs;
+	}
+
+	reset(value: number | null = null, now = Date.now()): void {
+		this.from = value;
+		this.target = value;
+		this.startedAt = now;
+	}
+
+	setTarget(target: number | null, now = Date.now()): number | null {
+		if (target === null) {
+			this.reset(null, now);
+			return null;
+		}
+
+		const current = this.value(now);
+		if (current === null) {
+			this.reset(target, now);
+			return target;
+		}
+
+		if (this.target !== null && Math.abs(target - this.target) < 0.05) return current;
+
+		this.from = current;
+		this.target = target;
+		this.startedAt = now;
+		return current;
+	}
+
+	value(now = Date.now()): number | null {
+		if (this.target === null) return null;
+		if (this.from === null || this.durationMs <= 0) return this.target;
+
+		const progress = Math.max(0, Math.min(1, (now - this.startedAt) / this.durationMs));
+		if (progress >= 1) {
+			this.from = this.target;
+			return this.target;
+		}
+
+		return this.from + (this.target - this.from) * progress;
+	}
+
+	isAnimating(now = Date.now()): boolean {
+		return (
+			this.target !== null &&
+			this.from !== null &&
+			Math.abs(this.target - this.from) >= 0.05 &&
+			now - this.startedAt < this.durationMs
+		);
+	}
+}

package/src/extension/cross-extension-rpc.ts

@@ -0,0 +1,350 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { TeamToolParamsValue } from "../schema/team-tool-schema.ts";
+import { resolveRealContainedPath } from "../utils/safe-paths.ts";
+import { withHmacVerification } from "./rpc-hmac.ts";
+// Lazy-loaded to avoid pulling team-tool.ts (and its entire runtime chain) into module load.
+import type { handleTeamTool as HandleTeamToolFn } from "./team-tool.ts";
+
+let _cachedHandleTeamTool: typeof HandleTeamToolFn | undefined;
+async function handleTeamTool(
+	params: Parameters<typeof HandleTeamToolFn>[0],
+	ctx: Parameters<typeof HandleTeamToolFn>[1],
+): Promise<Awaited<ReturnType<typeof HandleTeamToolFn>>> {
+	if (!_cachedHandleTeamTool) {
+		// LAZY: avoid pulling team-tool.ts (and its entire runtime chain) into module load.
+		const mod = await import("./team-tool.ts");
+		_cachedHandleTeamTool = mod.handleTeamTool;
+	}
+	return _cachedHandleTeamTool(params, ctx);
+}
+
+import { parseLiveControlRealtimeMessage, publishLiveControlRealtime } from "../runtime/live-control-realtime.ts";
+
+export interface EventBusLike {
+	on(event: string, handler: (data: unknown) => void): (() => void) | void;
+	emit(event: string, data: unknown): void;
+}
+
+export type RpcReply<T = unknown> = { success: true; data?: T } | { success: false; error: string };
+export const PI_CREW_RPC_VERSION = 1;
+
+export interface PiCrewRpcHandle {
+	unsubscribe(): void;
+}
+
+function requestId(raw: unknown): string | undefined {
+	return raw && typeof raw === "object" && !Array.isArray(raw) && typeof (raw as { requestId?: unknown }).requestId === "string"
+		? (raw as { requestId: string }).requestId
+		: undefined;
+}
+
+function reply(events: EventBusLike, channel: string, id: string | undefined, payload: RpcReply): void {
+	if (!id) return;
+	// SECURITY: Validate requestId format to prevent channel injection.
+	if (!/^[a-zA-Z0-9_-]+$/.test(id)) return;
+	events.emit(`${channel}:reply:${id}`, payload);
+}
+
+function textOf(result: Awaited<ReturnType<typeof handleTeamTool>>): string {
+	return result.content?.map((item) => (item.type === "text" ? item.text : "")).join("\n") ?? "";
+}
+
+// SECURITY: Strictly enumerate allowed operations per RPC channel.
+// Only read-only operations are permitted via RPC to prevent malicious extensions
+// from mutating run state without user consent.
+const RPC_ALLOWED_OPERATIONS = new Set([
+	// Read-only manifest/plan ops
+	"metrics-snapshot",
+	"inventory",
+	"read-manifest",
+	"list-tasks",
+	"read-task",
+	"read-events",
+	// Read-only agent ops
+	"list-agents",
+	"read-agent-status",
+	"read-agent-events",
+	"read-agent-transcript",
+	"read-agent-output",
+	"agent-dashboard",
+	// Mailbox read ops
+	"read-mailbox",
+	"read-delivery",
+	"read-heartbeat",
+	// No mutating ops (approve-plan, cancel-plan, steer-agent, stop-agent, etc.)
+	// — these require explicit intent confirmation and are NOT allowed via RPC.
+]);
+
+function isAllowedRpcOperation(operation: string): boolean {
+	return RPC_ALLOWED_OPERATIONS.has(operation);
+}
+
+// SECURITY (HIGH #4 fix): In-memory rate limiter for RPC run requests.
+// Prevents any extension from spawning unlimited child processes.
+const RPC_RATE_LIMIT_MAX = 5; // Max 5 RPC run requests...
+const RPC_RATE_LIMIT_WINDOW_MS = 60_000; // ...per 60 seconds
+const rpcRunTimestamps: number[] = [];
+
+function checkRpcRateLimit(): { allowed: boolean; retryAfterMs?: number } {
+	const now = Date.now();
+	// Evict entries older than the window
+	const cutoff = now - RPC_RATE_LIMIT_WINDOW_MS;
+	while (rpcRunTimestamps.length > 0 && rpcRunTimestamps[0] < cutoff) {
+		rpcRunTimestamps.shift();
+	}
+	if (rpcRunTimestamps.length >= RPC_RATE_LIMIT_MAX) {
+		const oldestInWindow = rpcRunTimestamps[0];
+		const retryAfterMs = oldestInWindow + RPC_RATE_LIMIT_WINDOW_MS - now;
+		return { allowed: false, retryAfterMs: Math.max(retryAfterMs, 1000) };
+	}
+	return { allowed: true };
+}
+
+function recordRpcRun(): void {
+	rpcRunTimestamps.push(Date.now());
+}
+
+/** Reset the RPC rate limiter. Used primarily for testing. */
+export function resetRpcRateLimit(): void {
+	rpcRunTimestamps.length = 0;
+}
+
+export function isAllowedRpcRunParams(
+	params: TeamToolParamsValue,
+	ctx: ExtensionContext,
+): {
+	ok: boolean;
+	error?: string;
+} {
+	// SECURITY: Require explicit intent for any RPC-initiated run creation.
+	// This prevents malicious extensions from spawning child Pi processes silently.
+	const cfg = params.config as Record<string, unknown> | undefined;
+	const intent = cfg?.intent as string | undefined;
+	if (!intent || typeof intent !== "string" || intent.trim().length === 0) {
+		return {
+			ok: false,
+			error: "RPC run requires config.intent (a non-empty intent string)",
+		};
+	}
+	// SECURITY: Validate cwd, if provided, resolves WITHIN the project directory (ctx.cwd).
+	// Arg order is (baseDir=ctx.cwd, targetPath=params.cwd): the project dir is the container,
+	// the caller-supplied cwd is the contained target. (Previously the args were swapped —
+	// resolveContainedPath(params.cwd, ".") — which validates that "." is inside params.cwd,
+	// trivially true for ANY path, so the check never rejected anything.)
+	// NOTE: defense-in-depth — handleTeamTool currently uses ctx.cwd and ignores params.cwd,
+	// but a correct guard here prevents a future regression from silently enabling cwd escape.
+	if (params.cwd && typeof params.cwd === "string") {
+		try {
+			resolveRealContainedPath(ctx.cwd, params.cwd);
+		} catch {
+			return {
+				ok: false,
+				error: "RPC run config.cwd must be within the project directory",
+			};
+		}
+	}
+	return { ok: true };
+}
+
+function on(events: EventBusLike, channel: string, handler: (raw: any) => unknown): () => void {
+	const unsub = events.on(channel, handler);
+	return typeof unsub === "function" ? unsub : () => {};
+}
+
+// SECURITY TRUST BOUNDARY: RPC channels (pi-crew:rpc:run, pi-crew:rpc:status,
+// pi-crew:rpc:live-control) are accessible to any extension on the shared event
+// bus. Mitigations: rate limiting, explicit intent, operation allowlist, cwd
+// containment validation, and HMAC origin signing (see rpc-hmac.ts).
+
+export function registerPiCrewRpc(
+	events: EventBusLike | undefined,
+	getCtx: () => ExtensionContext | undefined,
+): PiCrewRpcHandle | undefined {
+	if (!events) return undefined;
+	// Note: the prior loud startup warning has been replaced by a soft, opt-out
+	// info note emitted lazily by withHmacVerification only when an actual RPC
+	// request is processed (see rpc-hmac.ts). This avoids noisy output during
+	// every pi load for users who never wire cross-extension RPC.
+	const unsubs = [
+		on(
+			events,
+			"pi-crew:rpc:ping",
+			withHmacVerification(
+				(raw) =>
+					reply(events, "pi-crew:rpc:ping", requestId(raw), {
+						success: true,
+						data: { version: PI_CREW_RPC_VERSION },
+					}),
+				"pi-crew:rpc:ping",
+			),
+		),
+		on(
+			events,
+			"pi-crew:rpc:run",
+			withHmacVerification(async (raw) => {
+				const id = requestId(raw);
+				try {
+					// SECURITY (HIGH #4 fix): Rate limit RPC run requests
+					const rateLimit = checkRpcRateLimit();
+					if (!rateLimit.allowed) {
+						reply(events, "pi-crew:rpc:run", id, {
+							success: false,
+							error: `RPC run rate limit exceeded. Max ${RPC_RATE_LIMIT_MAX} requests per ${RPC_RATE_LIMIT_WINDOW_MS / 1000}s. Retry after ${Math.ceil((rateLimit.retryAfterMs ?? 60000) / 1000)}s.`,
+						});
+						return;
+					}
+					recordRpcRun();
+					const ctx = getCtx();
+					if (!ctx) throw new Error("No active pi-crew session context.");
+					// Validate payload: only allow known fields from TeamToolParamsValue
+					const ALLOWED_RPC_RUN_KEYS = new Set([
+						"goal",
+						"team",
+						"workflow",
+						"async",
+						"cwd",
+						"config",
+						"skill",
+						"model",
+						"budgetTotal",
+						"budgetWarning",
+						"budgetAbort",
+						"budgetUnlimited",
+					]);
+					let params: TeamToolParamsValue;
+					if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+						const filtered: Record<string, unknown> = {
+							...(raw as object),
+						};
+						// Strip any keys not in the allowlist to prevent injection of unexpected fields
+						for (const key of Object.keys(filtered)) {
+							if (!ALLOWED_RPC_RUN_KEYS.has(key)) delete filtered[key];
+						}
+						params = {
+							...filtered,
+							action: "run",
+						} as TeamToolParamsValue;
+					} else {
+						params = { action: "run" };
+					}
+					const permission = isAllowedRpcRunParams(params, ctx);
+					if (!permission.ok) {
+						reply(events, "pi-crew:rpc:run", id, {
+							success: false,
+							error: permission.error ?? "permission denied",
+						});
+						return;
+					}
+					const result = await handleTeamTool(params, ctx);
+					reply(
+						events,
+						"pi-crew:rpc:run",
+						id,
+						result.isError ? { success: false, error: textOf(result) } : { success: true, data: result.details },
+					);
+				} catch (error) {
+					reply(events, "pi-crew:rpc:run", id, {
+						success: false,
+						error: error instanceof Error ? error.message : String(error),
+					});
+				}
+			}, "pi-crew:rpc:run"),
+		),
+		on(
+			events,
+			"pi-crew:rpc:status",
+			withHmacVerification(async (raw) => {
+				const id = requestId(raw);
+				try {
+					const ctx = getCtx();
+					if (!ctx) throw new Error("No active pi-crew session context.");
+					const runId = raw && typeof raw === "object" && !Array.isArray(raw) ? (raw as { runId?: string }).runId : undefined;
+					const result = await handleTeamTool({ action: "status", runId }, ctx);
+					reply(
+						events,
+						"pi-crew:rpc:status",
+						id,
+						result.isError
+							? { success: false, error: textOf(result) }
+							: {
+									success: true,
+									data: {
+										text: textOf(result),
+										details: result.details,
+									},
+								},
+					);
+				} catch (error) {
+					reply(events, "pi-crew:rpc:status", id, {
+						success: false,
+						error: error instanceof Error ? error.message : String(error),
+					});
+				}
+			}, "pi-crew:rpc:status"),
+		),
+		on(
+			events,
+			"pi-crew:live-control",
+			withHmacVerification((raw) => {
+				const request = parseLiveControlRealtimeMessage(raw);
+				if (request) publishLiveControlRealtime(request);
+			}, "pi-crew:live-control"),
+		),
+		on(
+			events,
+			"pi-crew:rpc:live-control",
+			withHmacVerification(async (raw) => {
+				const id = requestId(raw);
+				try {
+					const ctx = getCtx();
+					if (!ctx) throw new Error("No active pi-crew session context.");
+					const obj = raw && typeof raw === "object" && !Array.isArray(raw) ? (raw as Record<string, unknown>) : {};
+					const rawOp = typeof obj.operation === "string" ? obj.operation : "steer-agent";
+					// SECURITY: Reject any operation not in the explicit allowlist.
+					// Mutating ops (approve-plan, cancel-plan, steer-agent, stop-agent, etc.)
+					// require user consent and are blocked here.
+					if (!isAllowedRpcOperation(rawOp)) {
+						reply(events, "pi-crew:rpc:live-control", id, {
+							success: false,
+							error: `RPC operation '${rawOp}' is not allowed. Allowed: ${[...RPC_ALLOWED_OPERATIONS].join(", ")}`,
+						});
+						return;
+					}
+					const result = await handleTeamTool(
+						{
+							action: "api",
+							runId: typeof obj.runId === "string" ? obj.runId : undefined,
+							config: {
+								operation: rawOp,
+								agentId: obj.agentId,
+								message: obj.message,
+								prompt: obj.prompt,
+							},
+						},
+						ctx,
+					);
+					reply(
+						events,
+						"pi-crew:rpc:live-control",
+						id,
+						result.isError
+							? { success: false, error: textOf(result) }
+							: {
+									success: true,
+									data: {
+										text: textOf(result),
+										details: result.details,
+									},
+								},
+					);
+				} catch (error) {
+					reply(events, "pi-crew:rpc:live-control", id, {
+						success: false,
+						error: error instanceof Error ? error.message : String(error),
+					});
+				}
+			}, "pi-crew:rpc:live-control"),
+		),
+	];
+	return { unsubscribe: () => unsubs.forEach((unsub) => unsub()) };
+}

package/src/extension/help.ts

@@ -0,0 +1,62 @@
+export function piTeamsHelp(): string {
+	return [
+		"pi-crew commands:",
+		"",
+		"Core:",
+		"- Agent can use the `team` tool autonomously; slash commands are manual controls.",
+		"- Tool action `recommend` suggests the best team/workflow for a goal.",
+		"- /teams — list teams, workflows, agents, recent runs",
+		"- /team-run [--team=name] [--workflow=name] [--async] [--worktree] <goal>",
+		"- /team-status <runId>",
+		"- /team-summary <runId>",
+		"- /team-resume <runId>",
+		"- /team-cancel <runId>",
+		"- /team-retry <runId> [taskId]",
+		"",
+		"Inspection:",
+		"- /team-events <runId>",
+		"- /team-artifacts <runId>",
+		"- /team-worktrees <runId>",
+		"- /team-api <runId> <operation> [taskId=<taskId>] [body=<message>]",
+		"- /team-dashboard",
+		"- /team-mascot",
+		"- /team-transcript <runId> [taskId]",
+		"- /team-result <runId> [taskId]",
+		"- /team-manager — interactive menu (alias: /team-cleanup-menu)",
+		"",
+		"Maintenance:",
+		"- /team-cleanup <runId> [--force]  (or scope=project/user for uninstall cleanup)",
+		"- /team-forget <runId> --confirm [--force]",
+		"- /team-prune --keep=20 --confirm",
+		"",
+		"Portability:",
+		"- /team-export <runId>",
+		"- /team-import <path-to-run-export.json> [--user]",
+		"- /team-imports",
+		"",
+		"Diagnostics:",
+		"- /team-health",
+		"- /team-doctor",
+		"- /team-init [--copy-builtins] [--overwrite]",
+		"- /team-config [key=value] [--unset=key.path] [--project]",
+		"- /team-autonomy [status|on|off|manual|suggested|assisted|aggressive] [--prefer-async] [--no-worktree-suggest]",
+		"- /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");
+}