pi-crew 0.11.1 → 0.11.2

package/src/config/config-validation.ts

@@ -21,6 +21,7 @@ import type {
 	CrewTelemetryConfig,
 	CrewToolsConfig,
 	CrewUiConfig,
+	CrewWebhookConfig,
 	CrewWorktreeConfig,
 	GoalWrapWorkflowConfig,
 	PersistenceConfig,
@@ -583,6 +584,19 @@ function parsePolicyConfig(value: unknown): CrewPolicyConfig | undefined {
 function parseNotificationsConfig(value: unknown): CrewNotificationsConfig | undefined {
 	const obj = asRecord(value);
 	if (!obj) return undefined;
+	// US-030: webhook block — field-wise parse mirroring the schema (url must
+	// be a non-empty string; an invalid/missing url parses to "" which the
+	// notifier treats as disabled — zero network). Sensitive: schema marks the
+	// block user-config-only; this parser stays shape-neutral.
+	const webhookObj = asRecord(obj.webhook);
+	const webhook: CrewWebhookConfig | undefined = webhookObj
+		? {
+				url: parseWithSchema(Type.String({ minLength: 1 }), webhookObj.url) ?? "",
+				enabled: parseWithSchema(Type.Boolean(), webhookObj.enabled),
+				secret: parseWithSchema(Type.String({ minLength: 1 }), webhookObj.secret),
+				allowLocalhost: parseWithSchema(Type.Boolean(), webhookObj.allowLocalhost),
+			}
+		: undefined;
 	const notifications: CrewNotificationsConfig = {
 		enabled: parseWithSchema(Type.Boolean(), obj.enabled),
 		severityFilter: parseWithSchema(
@@ -597,6 +611,7 @@ function parseNotificationsConfig(value: unknown): CrewNotificationsConfig | und
 		batchWindowMs: parseWithSchema(Type.Integer({ minimum: 0, maximum: 60_000 }), obj.batchWindowMs),
 		quietHours: parseWithSchema(Type.String({ pattern: "^\\d{2}:\\d{2}-\\d{2}:\\d{2}$" }), obj.quietHours),
 		sinkRetentionDays: parsePositiveInteger(obj.sinkRetentionDays, 90),
+		webhook,
 	};
 	return Object.values(notifications).some((entry) => entry !== undefined) ? notifications : undefined;
 }

package/src/config/config.ts

@@ -264,12 +264,47 @@ function unsetPath(record: Record<string, unknown>, dottedPath: string): void {
 	delete target[parts[parts.length - 1]!];
 }
 
+// F08 (RR-016): the JSON depth guard below MAX_JSON_DEPTH containers of TRUE
+// nesting — measured by an explicit-stack walk over the parsed value, NOT by a
+// JSON.parse reviver counter. The previous reviver incremented once per VALUE,
+// so a shallow-but-wide config (48 agent model overrides = 101 values) was
+// rejected as "too deep" and the ENTIRE file was discarded — silently losing
+// every resource limit in it, while a genuinely 96-level-deep document with 99
+// values was accepted. Keeping this a real depth limit preserves the guard
+// against pathological nesting without punishing wide configs.
+const MAX_CONFIG_SIZE = 10 * 1024 * 1024;
+const MAX_JSON_DEPTH = 100;
+
+/**
+ * Deepest container (object/array) nesting level of a parsed JSON value;
+ * scalars do not add depth. Iterative (explicit stack) on purpose: a recursive
+ * walk would itself stack-overflow on the exact input this guard exists to
+ * reject. Cost is O(nodes) and it is only run once per config parse (which the
+ * 2s loadConfig cache already amortizes).
+ */
+function measureJsonDepth(root: unknown): number {
+	let maxDepth = 0;
+	const stack: Array<{ value: unknown; depth: number }> = [{ value: root, depth: 1 }];
+	while (stack.length > 0) {
+		const frame = stack.pop()!;
+		if (frame.depth > maxDepth) maxDepth = frame.depth;
+		const children: unknown[] = Array.isArray(frame.value)
+			? frame.value
+			: frame.value !== null && typeof frame.value === "object"
+				? Object.values(frame.value as Record<string, unknown>)
+				: [];
+		for (const child of children) {
+			if (child !== null && typeof child === "object") stack.push({ value: child, depth: frame.depth + 1 });
+		}
+	}
+	return maxDepth;
+}
+
 function readConfigRecord(filePath: string): Record<string, unknown> {
 	if (!fs.existsSync(filePath)) return {};
 	// Defense-in-depth: reject config files larger than 10 MB before parsing.
-	// This prevents memory exhaustion and blocks deeply nested JSON that could
-	// cause stack overflow during parsing.
-	const MAX_CONFIG_SIZE = 10 * 1024 * 1024;
+	// This prevents memory exhaustion from oversized files. (Behaviour kept
+	// unchanged by F08/RR-016: the byte-size limit stays a separate, hard cap.)
 	const stat = fs.statSync(filePath);
 	if (stat.size > MAX_CONFIG_SIZE) {
 		logInternalError(
@@ -279,17 +314,16 @@ function readConfigRecord(filePath: string): Record<string, unknown> {
 		);
 		return {};
 	}
-	// Parse with depth limit to prevent stack overflow from deeply nested JSON.
-	// Nesting beyond 100 levels is almost certainly an attack or malformed file.
-	const MAX_JSON_DEPTH = 100;
-	let depth = 0;
-	const raw = JSON.parse(fs.readFileSync(filePath, "utf-8"), (_key, value) => {
-		if (++depth > MAX_JSON_DEPTH) {
-			throw new Error(`config JSON exceeds max depth ${MAX_JSON_DEPTH}`);
-		}
-		return value;
-	}) as unknown;
+	// Plain parse first (V8's JSON.parse is iterative — a 1e6-deep document
+	// parses without a stack overflow), then the iterative depth walk above.
+	const raw = JSON.parse(fs.readFileSync(filePath, "utf-8")) as unknown;
 	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+	const depth = measureJsonDepth(raw);
+	if (depth > MAX_JSON_DEPTH) {
+		throw new Error(
+			`config JSON nesting depth ${depth} exceeds max depth ${MAX_JSON_DEPTH} (fix: reduce nesting in ${filePath}, or delete the file to fall back to defaults)`,
+		);
+	}
 	return raw as Record<string, unknown>;
 }
 

package/src/config/env-vars.ts

@@ -237,6 +237,25 @@ export const CREW_ENV_VARS: Record<string, CrewEnvVarSpec> = {
 		parser: "boolean",
 		doc: "'1'/'true' allows PI_TEAMS_MOCK_CHILD_PI mock mode (mock-fixtures.ts:40)",
 	},
+	PI_CREW_TEST_ASYNC_INLINE: {
+		name: "PI_CREW_TEST_ASYNC_INLINE",
+		parser: "boolean",
+		doc: "'1' runs async team runs IN-PROCESS instead of spawning a detached background-runner (test seam; requires PI_CREW_ALLOW_MOCK=1 — see async-runner.ts spawnBackgroundTeamRun)",
+	},
+	PI_CREW_BACKGROUND_RUNNER_ENTRY: {
+		name: "PI_CREW_BACKGROUND_RUNNER_ENTRY",
+		parser: "boolean",
+		doc: "'1' marks this process as a directly-invoked background-runner entry (set by async-runner spawn; module import without it skips main() — background-runner.ts entry guard)",
+	},
+	PI_CREW_PROMPT_BREAKDOWN: {
+		name: "PI_CREW_PROMPT_BREAKDOWN",
+		parser: "boolean",
+		doc: "'1' writes a per-section prompt token breakdown artifact metadata/<task>.prompt-breakdown.json (SR-02 phase 1, prompt-builder.ts)",
+	},
+	PI_CREW_PROMPT_SKILLS: {
+		name: "PI_CREW_PROMPT_SKILLS",
+		doc: "'full' inlines complete skill bodies in worker prompts (SR-02 escape hatch); default injects compact index entries (name+description+path, read-on-demand)",
+	},
 	PI_CREW_ASYNC_EARLY_EXIT_GUARD: {
 		name: "PI_CREW_ASYNC_EARLY_EXIT_GUARD",
 		doc: "'0' skips the async-run early-exit guard (team-tool/run.ts:103)",
@@ -257,6 +276,10 @@ export const CREW_ENV_VARS: Record<string, CrewEnvVarSpec> = {
 		name: "PI_CREW_DEBUG_BUDGET",
 		doc: "'1' logs token budget (team-tool/run.ts:498)",
 	},
+	PI_CREW_DEBUG_STALE: {
+		name: "PI_CREW_DEBUG_STALE",
+		doc: "'1' writes a forensic sidecar log of every STALE verdict from the stale reconciler (stale-reconciler.ts:287) — the reconciler may run in ANY host process, hence a fixed env gate",
+	},
 	PI_CREW_DWF_SCRIPT_TIMEOUT_MS: {
 		name: "PI_CREW_DWF_SCRIPT_TIMEOUT_MS",
 		parser: "int",
@@ -415,6 +438,18 @@ export const CREW_ENV_VARS: Record<string, CrewEnvVarSpec> = {
 		name: "PI_CREW_AUTO_EXIT",
 		doc: "'1' → the worker shuts its session down after the final settled turn — spec §5.2 D7 (written by prepareSurfaceSpawn, read by surface-worker.ts)",
 	},
+	PI_CREW_AUTO_PRUNE_KEEP: {
+		name: "PI_CREW_AUTO_PRUNE_KEEP",
+		parser: "int",
+		default: "10",
+		doc: "DP-01: number of most-recent finished runs the session-start auto-prune retains (was hard-coded 10). Invalid/negative → 10 with a warning (run-maintenance.ts:resolveAutoPruneKeep)",
+	},
+	PI_CREW_AUTO_PRUNE_AGE_FLOOR_HOURS: {
+		name: "PI_CREW_AUTO_PRUNE_AGE_FLOOR_HOURS",
+		parser: "int",
+		default: "24",
+		doc: "DP-01: auto-prune never deletes a finished run younger than this many hours, even beyond top-keep — evidence/incident runs survive a session restart (0 disables; run-maintenance.ts:resolveAutoPruneAgeFloorMs)",
+	},
 	PI_CREW_SURFACE: {
 		name: "PI_CREW_SURFACE",
 		doc: "surface provider kind for this worker ('tmux'|'herdr') — arms the worker-side recorder/parent-guard (written by prepareSurfaceSpawn.ts:214, read by surface-worker.ts)",

package/src/config/types.ts

@@ -219,6 +219,23 @@ export interface CrewPolicyConfig {
 
 export type CrewNotificationSeverity = "info" | "warning" | "error" | "critical";
 
+/**
+ * US-030: opt-in outbound webhook on run terminal transitions.
+ * SENSITIVE (user config only — the schema marks this block `sensitive`):
+ * a project-level webhook URL would let an untrusted repo exfiltrate run
+ * metadata (incl. the goal first line) to an attacker-controlled endpoint.
+ */
+export interface CrewWebhookConfig {
+	/** Target URL. Must be http(s); localhost/loopback/link-local refused unless `allowLocalhost`. */
+	url: string;
+	/** Master switch. Absent + url set = enabled; `false` disables (zero network). */
+	enabled?: boolean;
+	/** Shared secret → `x-pi-crew-signature: sha256=<hmac-sha256(body, secret)>` header. */
+	secret?: string;
+	/** Explicit SSRF-guard bypass for localhost/127.0.0.0/8/[::1]/169.254.0.0/16 targets. */
+	allowLocalhost?: boolean;
+}
+
 export interface CrewNotificationsConfig {
 	enabled?: boolean;
 	severityFilter?: CrewNotificationSeverity[];
@@ -226,6 +243,8 @@ export interface CrewNotificationsConfig {
 	batchWindowMs?: number;
 	quietHours?: string;
 	sinkRetentionDays?: number;
+	/** US-030: outbound webhook on run terminal transitions. Opt-in only — no URL configured means disabled (zero network calls). */
+	webhook?: CrewWebhookConfig;
 }
 
 export interface CrewObservabilityConfig {

package/src/errors.ts

@@ -1,4 +1,4 @@
-// pi-crew structured error module — taxonomy mapping E001–E006.
+// pi-crew structured error module — taxonomy mapping E001–E013.
 /**
  * @fileoverview Error types and structured error handling for pi-crew.
  *
@@ -6,7 +6,7 @@
  * matching fallow's E001-E004 pattern. It exports three main constructs:
  *
  * - {@link ErrorCode} — a `const` object and string-literal union type alias
- *   enumerating machine-readable error codes (E001–E006). Implemented as a
+ *   enumerating machine-readable error codes (E001–E013). Implemented as a
  *   `const` object rather than a TypeScript `enum` so that Node's
  *   `--experimental-strip-types` can load this module (enum syntax is not
  *   supported in strip-only mode).

package/src/extension/async-notifier.ts

@@ -8,6 +8,7 @@ import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { extractSessionId } from "../utils/session-utils.ts";
 import { listRuns } from "./run-index.ts";
+import type { WebhookNotifier } from "./webhook-notify.ts";
 
 export interface AsyncNotifierState {
 	seenFinishedRunIds: Set<string>;
@@ -20,6 +21,13 @@ export interface AsyncNotifierState {
 export interface AsyncNotifierOptions {
 	generation?: number;
 	isCurrent?: (generation: number) => boolean;
+	/**
+	 * US-030 (docs/specs/US-030.md): outbound webhook sink, invoked ONCE per
+	 * observed terminal transition — the same point (and dedupe memory) as the
+	 * completion toast below. The sink handles quiet-hours, SSRF, HMAC and
+	 * retry internally and NEVER throws. Optional — absent = disabled.
+	 */
+	webhookNotifier?: WebhookNotifier;
 }
 
 function isFinished(status: string): boolean {
@@ -177,6 +185,21 @@ export function startAsyncRunNotifier(
 				// 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;
+				// US-030: outbound webhook on the terminal transition. Only the three
+				// spec statuses (completed/failed/cancelled) — "blocked" runs do not
+				// notify. Fire-and-forget: the sink is contractually non-throwing, the
+				// try/catch is belt-only so a webhook failure can NEVER suppress the
+				// local toast (or reach the run lifecycle path).
+				if (
+					options.webhookNotifier &&
+					(current.status === "completed" || current.status === "failed" || current.status === "cancelled")
+				) {
+					try {
+						options.webhookNotifier.notifyTerminalRun(current);
+					} catch (error) {
+						logInternalError("async-notifier.webhook", error, current.runId);
+					}
+				}
 				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

@@ -4,7 +4,6 @@ export function piTeamsHelp(): string {
 		"",
 		"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>",
@@ -12,36 +11,48 @@ export function piTeamsHelp(): string {
 		"- /team-resume <runId>",
 		"- /team-cancel <runId>",
 		"- /team-retry <runId> [taskId]",
+		"- /team-respond <runId> <taskId|--all> <message>",
+		"- /team-follow-up <runId> <taskId> <prompt>",
+		"- /team-goal — autonomous goal loop (sub-actions: start/status/pause/resume/stop/step/clear)",
+		"- /workflows — list static + dynamic workflows",
 		"",
 		"Inspection:",
 		"- /team-events <runId>",
 		"- /team-artifacts <runId>",
+		"- /team-result <runId> [taskId]",
+		"- /team-transcript <runId> [taskId]",
 		"- /team-worktrees <runId>",
-		"- /team-api <runId> <operation> [taskId=<taskId>] [body=<message>]",
+		"- /team-api <runId> <operation> [key=value]",
+		"- /team-metrics [filter]",
 		"- /team-dashboard",
-		"- /schedules [log <jobId-or-name>] — list scheduled jobs / tail latest run output",
 		"- /team-mascot",
-		"- /team-transcript <runId> [taskId]",
-		"- /team-result <runId> [taskId]",
-		"- /team-manager — interactive menu (alias: /team-cleanup-menu)",
 		"",
 		"Maintenance:",
+		"- /team-manager — interactive menu (alias: /team-cleanup-menu)",
 		"- /team-forget <runId> --confirm [--force]",
 		"- /team-prune --keep=20 --confirm",
+		"- /team-invalidate <runId>",
+		"",
+		"Skills:",
+		"- /skill-list [--json] — list builtin skill templates",
+		"- /skill-create <template-id> [--var key=value...] [--project]",
 		"",
 		"Portability:",
 		"- /team-export <runId>",
-		"- /team-import <path-to-run-export.json> [--user]",
+		"- /team-import <path-to-run-export.json>",
 		"- /team-imports",
 		"",
-		"Diagnostics:",
+		"Diagnostics & config:",
 		"- /team-doctor",
+		"- /team-validate",
 		"- /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-settings [list|get <key>|set <key> <value>|unset <key>|path|scope]",
+		"- /team-autonomy [status|on|off|manual|suggested|assisted|aggressive]",
 		"- /team-help",
 		"",
+		"Non-team commands: /schedules [log <jobId-or-name>], /crew-view <runId> <taskId>, /crew-back, /team-vibes [on|off], /crew-brief [on|off|status]",
+		"",
 		"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>]",

package/src/extension/knowledge-injection.ts

@@ -23,6 +23,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { sanitizeAgentSystemPrompt } from "../agents/discover-agents.ts";
+import { getCrewEnv } from "../config/env-vars.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { projectCrewRoot } from "../utils/paths.ts";
 import type { BeforeAgentStartEvent, ExtensionAPI } from "./pi-api.ts";
@@ -463,7 +464,7 @@ export function registerKnowledgeInjection(pi: ExtensionAPI): void {
 		// ARCH-2: never fire in child worker processes — knowledge reaches
 		// workers via prompt-builder's stablePrefix fragment; firing here too
 		// would double-inject.
-		if (process.env.PI_CREW_KIND === "subagent") return;
+		if (getCrewEnv("PI_CREW_KIND") === "subagent") return;
 		const options =
 			(
 				event as BeforeAgentStartEvent & {

package/src/extension/management.ts

@@ -175,22 +175,27 @@ function findResource(ctx: ManagementContext, resource: "agent" | "team" | "work
 	const sourceMatches = (item: { name: string; source: ResourceSource }) =>
 		(scope === "user" || scope === "project" ? item.source === scope : item.source !== "builtin") && item.name === normalized;
 	// Search in the correct scope array directly to avoid allAgents shadowing issue.
+	// Tier 9e (2026-09-21): the DEFAULT pool must include PROJECT resources —
+	// the error message already promises "mutable user/project scopes", but the
+	// pool was `[...builtin, ...user]` and `sourceMatches` then drops every
+	// builtin entry, degenerating the default to USER ONLY. A project resource
+	// was invisible unless the caller guessed scope:'project'.
 	if (resource === "agent") {
 		const discovery = discoverAgents(ctx.cwd);
 		const pool =
-			scope === "user" ? discovery.user : scope === "project" ? discovery.project : [...discovery.builtin, ...discovery.user];
+			scope === "user" ? discovery.user : scope === "project" ? discovery.project : [...discovery.user, ...discovery.project];
 		return pool.filter(sourceMatches);
 	}
 	if (resource === "team") {
 		const discovery = discoverTeams(ctx.cwd);
 		const pool =
-			scope === "user" ? discovery.user : scope === "project" ? discovery.project : [...discovery.builtin, ...discovery.user];
+			scope === "user" ? discovery.user : scope === "project" ? discovery.project : [...discovery.user, ...discovery.project];
 		return pool.filter(sourceMatches);
 	}
 	{
 		const discovery = discoverWorkflows(ctx.cwd);
 		const pool =
-			scope === "user" ? discovery.user : scope === "project" ? discovery.project : [...discovery.builtin, ...discovery.user];
+			scope === "user" ? discovery.user : scope === "project" ? discovery.project : [...discovery.user, ...discovery.project];
 		return pool.filter(sourceMatches);
 	}
 }

package/src/extension/notification-sink.ts

@@ -23,12 +23,29 @@ function rotateOldFiles(dir: string, retentionDays: number, now = Date.now()): v
 	}
 }
 
+/**
+ * JSONL notification sink.
+ *
+ * RR-020 Fix 2: writes are gated on the crew root ALREADY existing — this sink
+ * is attached at session start (lifecycle.ts) and the router pushes `info`
+ * notices through it before any severity filter, which used to create an empty
+ * `<crewRoot>/state/notifications/` tree (and with it the crew root) on every
+ * project. A project that never ran a team now stays untouched; once the crew
+ * root exists the sink behaves exactly as before.
+ */
 export function createJsonlSink(crewRoot: string, retentionDays = 7): NotificationSink {
 	const dir = path.join(crewRoot, "state", "notifications");
 	let lastRotateDate = "";
 	return {
 		write(notification: NotificationDescriptor): void {
 			try {
+				// RR-020 Fix 2: never materialise the project crew root. The router
+				// calls this sink BEFORE its severity filter (notification-router.ts),
+				// so an `info` notice on session start used to mkdir `<crewRoot>/`
+				// (→ `<crewRoot>/state/notifications/`) for a project that never ran
+				// a team. Persist only when the crew root already exists — a project
+				// that has real crew state keeps every notification exactly as before.
+				if (!fs.existsSync(crewRoot)) return;
 				const timestamp = notification.timestamp ?? Date.now();
 				const date = new Date(timestamp).toISOString().slice(0, 10);
 				if (date !== lastRotateDate) {

package/src/extension/registration/command-utils.ts

@@ -23,8 +23,34 @@ export function commandText(result: { content?: Array<{ type: string; text?: str
 	return result.content?.map((item) => item.text ?? "").join("\n") ?? "";
 }
 
-export async function notifyCommandResult(ctx: ExtensionCommandContext, text: string): Promise<void> {
-	ctx.ui.notify(text.length > 800 ? `${text.slice(0, 797)}...` : text, "info");
+/** Hard cap for command-result notifications (spec W5: cap value stays 800). */
+export const NOTIFY_TEXT_CAP = 800;
+
+/** Explicit marker appended whenever a command-result notification is clipped. */
+export const TRUNCATION_MARKER = "\n… [truncated]";
+
+export interface NotifyCommandResultOptions {
+	/**
+	 * Pointer appended AFTER the truncation marker when clipping occurs (e.g.
+	 * the on-disk log path so the full output stays reachable). Included
+	 * INSIDE the cap — the body shrinks to make room. Ignored when the text
+	 * fits without clipping.
+	 */
+	truncatedFooter?: string;
+}
+
+export async function notifyCommandResult(
+	ctx: ExtensionCommandContext,
+	text: string,
+	options: NotifyCommandResultOptions = {},
+): Promise<void> {
+	if (text.length <= NOTIFY_TEXT_CAP) {
+		ctx.ui.notify(text, "info");
+		return;
+	}
+	const tail = `${TRUNCATION_MARKER}${options.truncatedFooter ?? ""}`;
+	const bodyLength = Math.max(0, NOTIFY_TEXT_CAP - tail.length);
+	ctx.ui.notify(`${text.slice(0, bodyLength)}${tail}`, "info");
 }
 
 export function parseScalar(raw: string): unknown {

package/src/extension/registration/commands/dashboard.ts

@@ -105,12 +105,22 @@ export function registerDashboardCommands(pi: ExtensionAPI, deps: RegisterTeamCo
 	pi.registerCommand("team-dashboard", {
 		description: "Open a pi-crew run dashboard overlay",
 		handler: async (_args: string, ctx: ExtensionCommandContext) => {
+			// W4 (slash-commands fix spec): headless invocation previously fell
+			// through to openTeamDashboard's silent `if (!ctx.hasUI) return;`
+			// no-op — notify + return here instead so headless users get an
+			// actionable pointer instead of silence.
+			if (!ctx.hasUI) {
+				ctx.ui.notify("team-dashboard needs a UI session — headless runs can use /team-status instead.", "info");
+				return;
+			}
 			await openTeamDashboard(ctx);
 		},
 	});
 
 	pi.registerCommand("team-mascot", {
-		description: "Show an animated mascot splash",
+		// W4: cosmetic command is a documented silent no-op without a UI
+		// session (handler's `if (!ctx.hasUI) return;` stays).
+		description: "Show an animated mascot splash (UI session only)",
 		handler: async (args: string, ctx: ExtensionCommandContext) => {
 			if (!ctx.hasUI) return;
 			const tokens = args.trim().split(/\s+/).filter(Boolean);

package/src/extension/registration/commands/manage.ts

@@ -1,5 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { fileURLToPath } from "node:url";
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { getBuiltinTemplates, instantiateTemplate, listTemplates } from "../../../skills/skill-templates.ts";
 import { atomicWriteFile } from "../../../state/atomic-write.ts";
@@ -9,6 +10,29 @@ import { commandText, notifyCommandResult, parseScalar, pushUnset, setNestedConf
 import type { RegisterTeamCommandsDeps } from "./shared.ts";
 import { handleTeamTool, openTeamSettingsOverlay, teamCommandContext } from "./shared.ts";
 
+/**
+ * Resolve the user-level skills directory (<pi-crew package root>/skills).
+ *
+ * ESM-safe replacement for the former `require.resolve("../../../../package.json",
+ * { paths: [__dirname] })`: neither `require` nor `__dirname` exists under
+ * strip-types source loading or inside the esbuild ESM bundle (dist/index.mjs).
+ * Anchoring on `import.meta.url` and walking up to the nearest package.json
+ * yields the package root under BOTH layouts — src/.../commands/manage.ts and
+ * dist/index.mjs sit at different depths, so a fixed relative hop count cannot
+ * serve both.
+ */
+export function resolveUserSkillsDir(): string {
+	let dir = fileURLToPath(new URL(".", import.meta.url));
+	for (;;) {
+		if (fs.existsSync(path.join(dir, "package.json"))) return path.join(dir, "skills");
+		const parent = path.dirname(dir);
+		if (parent === dir) {
+			throw new Error(`pi-crew: cannot locate package root (no package.json above ${dir})`);
+		}
+		dir = parent;
+	}
+}
+
 export function registerManageCommands(pi: ExtensionAPI, deps: RegisterTeamCommandsDeps): void {
 	pi.registerCommand("team-prune", {
 		description: "Prune old finished pi-crew runs, keeping the newest N",
@@ -210,16 +234,20 @@ export function registerManageCommands(pi: ExtensionAPI, deps: RegisterTeamComma
 					return idx === -1 ? [s, ""] : [s.slice(0, idx), s.slice(idx + 1)];
 				});
 			const templateId = tokens.find((t) => !t.startsWith("--") && !t.includes("="));
+			const availableTemplateIds = listTemplates().map((t) => t.id);
 			if (!templateId) {
 				await notifyCommandResult(
 					ctx,
-					"Usage: /skill-create <template-id> [--var key=value...] [--project]\nRun /skill-list to see available templates.",
+					`Usage: /skill-create <template-id> [--var key=value...] [--project]\nAvailable templates: ${availableTemplateIds.join(", ")}`,
 				);
 				return;
 			}
 			const template = getBuiltinTemplates().find((t) => t.id === templateId);
 			if (!template) {
-				await notifyCommandResult(ctx, `Unknown template '${templateId}'. Run /skill-list to see available templates.`);
+				await notifyCommandResult(
+					ctx,
+					`Unknown template '${templateId}'.\nUsage: /skill-create <template-id> [--var key=value...] [--project]\nAvailable templates: ${availableTemplateIds.join(", ")}`,
+				);
 				return;
 			}
 			const variables: Record<string, string> = {};
@@ -249,19 +277,7 @@ export function registerManageCommands(pi: ExtensionAPI, deps: RegisterTeamComma
 				await notifyCommandResult(ctx, error instanceof Error ? error.message : String(error));
 				return;
 			}
-			const skillsDir = path.resolve(
-				cwd,
-				useProject
-					? "skills"
-					: path.join(
-							path.dirname(
-								require.resolve("../../../../package.json", {
-									paths: [__dirname],
-								}),
-							),
-							"skills",
-						),
-			);
+			const skillsDir = useProject ? path.resolve(cwd, "skills") : resolveUserSkillsDir();
 			const skillDir = path.join(skillsDir, template.id);
 			const skillPath = path.join(skillDir, "SKILL.md");
 			try {

package/src/extension/registration/commands/run.ts

@@ -109,6 +109,10 @@ export function registerRunCommands(pi: ExtensionAPI, deps: RegisterTeamCommands
 			const taskToken = tokens[0] === "--all" ? tokens.shift() : tokens.shift();
 			const taskId = taskToken === "--all" ? undefined : taskToken;
 			const message = tokens.join(" ") || undefined;
+			if (!runId || !taskToken || !message) {
+				await notifyCommandResult(ctx, "Usage: /team-respond <runId> <taskId|--all> <message>…");
+				return;
+			}
 			const result = await handleTeamTool({ action: "respond", runId, taskId, message }, teamCommandContext(ctx));
 			await notifyCommandResult(ctx, commandText(result));
 		},
@@ -163,7 +167,19 @@ export function registerRunCommands(pi: ExtensionAPI, deps: RegisterTeamCommands
 
 	pi.registerCommand("team-goal", {
 		description:
-			"Autonomous goal loop control: [start|status|pause|resume|stop|step|clear] [goalId] [--objective=...] [--evaluatorModel=...] [--maxTurns=N]",
+			"Autonomous goal loop control (defaults to status): [start|status|pause|resume|stop|cancel|reset|step|clear] [goalId] [--objective=...] [--evaluatorModel=...] [--maxTurns=N]",
+		// Suggest the stop-aliases only while completing the FIRST argument:
+		// pi hands `getArgumentCompletions` the whole argument text (there is no
+		// argument-index parameter), so any whitespace in it means the cursor is
+		// already past arg 1 — nothing useful to suggest for goalId/flags.
+		getArgumentCompletions: (argumentPrefix: string) => {
+			if (argumentPrefix.includes(" ")) return [];
+			const prefix = argumentPrefix.trim();
+			return [
+				{ value: "cancel", label: "cancel", description: "stop the goal loop (alias of stop)" },
+				{ value: "reset", label: "reset", description: "stop the goal loop (alias of stop)" },
+			].filter((item) => item.value.startsWith(prefix));
+		},
 		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"]);
@@ -203,7 +219,13 @@ export function registerRunCommands(pi: ExtensionAPI, deps: RegisterTeamCommands
 					metricRegistry: deps.getMetricRegistry?.(),
 				},
 			);
-			await notifyCommandResult(ctx, commandText(result));
+			const text = commandText(result);
+			const trimmed = text.trim();
+			const hint =
+				!trimmed || trimmed === "[]"
+					? "\nNo metrics yet — observability may be disabled for this team. Set `observability: true` in the team frontmatter to enable."
+					: "";
+			await notifyCommandResult(ctx, text + hint);
 		},
 	});
 

package/src/extension/registration/commands/shared.ts

@@ -576,6 +576,29 @@ export async function openTeamDashboard(ctx: ExtensionContext): Promise<void> {
 			deps.getRunSnapshotCache?.(cmdCtx.cwd).invalidate(selection.runId);
 			continue;
 		}
+		// US-020: dashboard `x` cancel — dispatches the EXISTING cancel channel
+		// (control-domain handleCancel). The 2-step dashboard gate is the user's
+		// explicit intent; `intent` satisfies requireIntentForDestructiveActions
+		// when that policy is on. Dashboard reopens on continue (selection kept).
+		if (selection.action === "cancel" && selection.runId) {
+			// F4 pattern: surface backend rejections at error level, truncate long text.
+			const cancelResult = await handleTeamTool(
+				{
+					action: "cancel",
+					runId: selection.runId,
+					config: { intent: "dashboard cancel keystroke (2-step confirm)" },
+				},
+				teamCommandContext(cmdCtx),
+			);
+			const cancelText = commandText(cancelResult);
+			depsNotify(
+				cmdCtx,
+				cancelText.length > 800 ? `${cancelText.slice(0, 797)}...` : cancelText,
+				cancelResult.isError ? "error" : "info",
+			);
+			deps.getRunSnapshotCache?.(cmdCtx.cwd).invalidate(selection.runId);
+			continue;
+		}
 		if (selection.action === "plan-approve" || selection.action === "plan-deny") {
 			await handlePlanDashboardAction(cmdCtx, selection);
 			deps.getRunSnapshotCache?.(cmdCtx.cwd).invalidate(selection.runId);