pi-crew 0.10.4 → 0.10.6

package/src/runtime/foreground-watchdog.ts

@@ -69,6 +69,13 @@ export function startForegroundWatchdog(opts: WatchdogOptions): void {
 	// Don't stack watchdogs for the same run
 	if (activeWatchdogs.has(runId)) return;
 
+	// ARCH-5: cap consecutive no-progress wake notices at 2, then send one
+	// final guidance message and go quiet — a ~24-notices/2h drip trains the
+	// user to ignore the watchdog. Reset on any sign of progress (run ends or
+	// leaves the hung state).
+	let consecutiveHungNotices = 0;
+	const HUNG_NOTICE_CAP = 2;
+
 	const check = (): void => {
 		// Check if max monitor time exceeded
 		if (Date.now() - startTime > maxMonitorMs) {
@@ -105,15 +112,27 @@ export function startForegroundWatchdog(opts: WatchdogOptions): void {
 			const now = Date.now();
 			if (isLikelyOrphanedActiveRun(manifest, agents, now)) {
 				const detail = `status=${manifest.status}, updatedAt=${manifest.updatedAt}, agents=${agents.length}`;
+				consecutiveHungNotices += 1;
 				try {
-					pi.sendUserMessage(
-						`pi-crew watchdog: run ${runId} appears hung (${detail}). Consider running team action='cancel' runId='${runId}' or team action='doctor'.`,
-						{ deliverAs: "followUp" },
-					);
+					if (consecutiveHungNotices <= HUNG_NOTICE_CAP) {
+						pi.sendUserMessage(
+							`pi-crew watchdog: run ${runId} appears hung (${detail}). Consider running team action='cancel' runId='${runId}' or team action='doctor'.`,
+							{ deliverAs: "followUp" },
+						);
+					} else if (consecutiveHungNotices === HUNG_NOTICE_CAP + 1) {
+						// One-time handoff, then silence — still monitoring, no more drips.
+						pi.sendUserMessage(
+							`pi-crew watchdog: run ${runId} is still hung after ${consecutiveHungNotices} checks — going quiet now. Intervene via team action='cancel' runId='${runId}', team action='doctor', or leave it; a completion notice will still fire.`,
+							{ deliverAs: "followUp" },
+						);
+					}
 				} catch {
 					/* non-critical */
 				}
-				// Don't stop — keep monitoring. The assistant or user may intervene.
+				// Keep monitoring (ARCH-5: silently past the cap — no more notices).
+			} else {
+				// Run is alive and progressing — reset the no-progress wake counter.
+				consecutiveHungNotices = 0;
 			}
 		} catch {
 			// Non-critical — skip this check

package/src/runtime/live-session/live-session-runtime.ts

@@ -273,7 +273,7 @@ function numberField(obj: Record<string, unknown> | undefined, keys: string[]):
 
 /**
  * F7: resolve the enabledModels allowlist for the current project, but only
- * if the `runtime.reliability.scopeModels` toggle is ON. Returns an empty
+ * if the `reliability.scopeModels` toggle is ON. Returns an empty
  * array when the toggle is off or no allowlist is configured — the routing
  * gate treats empty patterns as "no enforcement" (no-op). Best-effort:
  * any failure to read the toggle or the allowlist silently disables the gate

package/src/runtime/model/model-scope.ts

@@ -1,7 +1,7 @@
 /**
  * model-scope.ts — Opt-in model-scope enforcement (F7).
  *
- * When `runtime.reliability.scopeModels` is enabled, subagent model choices
+ * When `reliability.scopeModels` is enabled, subagent model choices
  * that fall outside the user's pi `enabledModels` allowlist are flagged:
  *   - Caller-supplied (per-spawn override / step / team role) out-of-scope
  *     → HARD ERROR to orchestrator (fail fast before spawn).
@@ -128,7 +128,7 @@ export function checkModelScope(
  * Read the user's `enabledModels` allowlist from pi's SettingsManager.
  * Returns an empty array when the SettingsManager export is unavailable, the
  * allowlist is unset, or any error occurs (best-effort, never throws). The
- * caller should still gate on `runtime.reliability.scopeModels` — an empty
+ * caller should still gate on `reliability.scopeModels` — an empty
  * patterns array is a no-op (nothing to enforce against).
  *
  * @internal Only the runtime spawn layers should call this. Pure module: pure

package/src/runtime/run-tracker.ts

@@ -1,8 +1,6 @@
 import * as fs from "node:fs";
-import * as path from "node:path";
-import { loadRunManifestById } from "../state/stores/state-store.ts";
+import { createRunPaths, loadRunManifestById } from "../state/stores/state-store.ts";
 import type { TeamRunManifest, TeamTaskState } from "../state/types.ts";
-import { projectCrewRoot } from "../utils/paths.ts";
 import { isFinishedRunStatus } from "./process-status.ts";
 
 export interface RunWaitResult {
@@ -11,6 +9,19 @@ export interface RunWaitResult {
 	/** True when the waiter was released early by `detachRunPromise` while the
 	 *  run itself keeps executing (see that function). */
 	detached?: boolean;
+	/** F1 (2026-09-12 live battery): set when the waiter was released early
+	 * because a task PARKED on `ask` — the broker pushes this via
+	 * `resolveRunPromise` so the sync caller's tool call returns with the
+	 * question instead of blocking until the watchdog kills the worker. The
+	 * run keeps executing; the leader answers via `team action='respond'`
+	 * then re-blocks via `team action='wait'`. */
+	waiting?: {
+		taskId: string;
+		questionId: string;
+		question: string;
+		deadline: number;
+		options?: string[];
+	};
 }
 
 export interface ActiveRunPromise {
@@ -32,7 +43,22 @@ const activeRunPromises = new Map<string, ActiveRunPromise>();
  */
 const detachRequests = new Set<string>();
 
+/** F1 tombstones (2026-09-12): resolveRunPromise deletes the live entry after
+ *  resolving it, so a register+resolve landing BETWEEN two poll ticks of a
+ *  slow-path waiter orphaned the payload (the waiter held no reference to the
+ *  entry). A waiter on the polling path consumes the tombstone instead.
+ *  Bounded — oldest evicted past the limit (detached runs never wait). */
+const resolvedRunResults = new Map<string, RunWaitResult>();
+const RESOLVED_TOMBSTONE_LIMIT = 32;
+
 export function registerRunPromise(runId: string): ActiveRunPromise {
+	// Idempotent (F1 live-probe fix, 2026-09-12): run.ts pre-registers BEFORE
+	// startForegroundRun so the waitForRun that runs immediately after can hit
+	// the medium path; executeTeamRunCore's later `void registerRunPromise(...)`
+	// must NOT overwrite the entry (an overwrite strands waiters holding the
+	// old promise — the waiting-push would resolve a promise nobody awaits).
+	const existing = activeRunPromises.get(runId);
+	if (existing) return existing;
 	detachRequests.delete(runId);
 	let resolve!: (value: RunWaitResult) => void;
 	let reject!: (reason: unknown) => void;
@@ -85,6 +111,13 @@ export function resolveRunPromise(runId: string, result: RunWaitResult): void {
 		entry.resolve(result);
 		activeRunPromises.delete(runId);
 	}
+	// F1 tombstone: a slow-path waiter (register/await race, or register+resolve
+	// between two ticks) must still see the push. Cheap Map.set; bounded above.
+	resolvedRunResults.set(runId, result);
+	if (resolvedRunResults.size > RESOLVED_TOMBSTONE_LIMIT) {
+		const oldest = resolvedRunResults.keys().next().value;
+		if (oldest !== undefined) resolvedRunResults.delete(oldest);
+	}
 }
 
 export function rejectRunPromise(runId: string, reason: unknown): void {
@@ -95,6 +128,17 @@ export function rejectRunPromise(runId: string, reason: unknown): void {
 	}
 }
 
+function raceRunPromise(entry: ActiveRunPromise, timeoutMs: number, deadline: number): Promise<RunWaitResult> {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const remaining = Math.max(0, deadline - Date.now());
+	const timeoutPromise = new Promise<never>((_, reject) => {
+		timer = setTimeout(() => reject(new Error(`waitForRun timed out after ${timeoutMs}ms`)), remaining);
+	});
+	return Promise.race([entry.promise, timeoutPromise]).finally(() => {
+		if (timer) clearTimeout(timer);
+	});
+}
+
 /**
  * Wait for a team run to reach a terminal status.
  * - If the run is already finished on disk, returns immediately.
@@ -124,17 +168,7 @@ export async function waitForRun(
 
 	// Medium path: foreground promise registered in this process
 	const entry = activeRunPromises.get(runId);
-	if (entry) {
-		let timer: ReturnType<typeof setTimeout> | undefined;
-		const timeoutPromise = new Promise<never>((_, reject) => {
-			timer = setTimeout(() => reject(new Error(`waitForRun timed out after ${timeoutMs}ms`)), timeoutMs);
-		});
-		try {
-			return await Promise.race([entry.promise, timeoutPromise]);
-		} finally {
-			if (timer) clearTimeout(timer);
-		}
-	}
+	if (entry) return await raceRunPromise(entry, timeoutMs, deadline);
 
 	// Slow path: background run — poll with exponential backoff capped at pollIntervalMs.
 	// This path is ALSO taken by a foreground run whose executeTeamRun has not
@@ -147,13 +181,24 @@ export async function waitForRun(
 			const current = loadRunManifestById(cwd, runId);
 			if (current) return { ...current, detached: true };
 		}
+		// F1 live-probe fix (2026-09-12): a foreground promise may appear AFTER
+		// this waiter started (register/await race — the waiting-push from the
+		// broker resolves the ENTRY, which the polling loop would otherwise
+		// never observe). Re-check each tick and switch to the promise path with
+		// the REMAINING budget; evidence team_20260912053049 (parked 05:31:14,
+		// push no-op'd, waiter polled until the watchdog killed the worker).
+		const entryNow = activeRunPromises.get(runId);
+		if (entryNow) return await raceRunPromise(entryNow, timeoutMs, deadline);
 		if (attempt === 0) {
 			// Early exit: if the run directory doesn't exist, don't waste time polling.
-			// Use projectCrewRoot() to honour the .pi/teams/ fallback for .pi-based
-			// projects (see issue #29). Without this, the hardcoded `.crew/state/runs/`
-			// path never resolves in projects that use the `.pi/` layout, the throw
-			// escapes via subagent-manager.ts:281, and pi crashes with uncaughtException.
-			const runDir = path.join(projectCrewRoot(cwd), "state", "runs", runId);
+			// Resolve through createRunPaths (scopeBaseRoot) so the probe matches where
+			// runs are CREATED: project scope — incl. the .pi/teams/ fallback for
+			// .pi-based projects (issue #29) — for cwds under a repo root, and USER
+			// scope for markerless cwds (issue #54). The previous projectCrewRoot(cwd)
+			// join always looked at <cwd>/.crew/state/runs for a markerless cwd, so
+			// RUN/WAIT instantly threw "Run not found" while the user-scope crew kept
+			// running. createRunPaths is pure path math (no mkdir), so it is safe here.
+			const runDir = createRunPaths(cwd, runId).stateRoot;
 			if (!fs.existsSync(runDir)) {
 				throw new Error(`Run ${runId} not found. No run directory at ${runDir}`);
 			}
@@ -162,6 +207,15 @@ export async function waitForRun(
 		if (fresh && isFinishedRunStatus(fresh.manifest.status)) {
 			return fresh;
 		}
+		// F1 tombstone: a push that resolved (and evicted) the live entry between
+		// ticks lands here — consume it so the leader sees the question, not a
+		// 600s block. Terminal-on-disk above still wins (a finished run outranks
+		// a stale waiting payload).
+		const tombstone = resolvedRunResults.get(runId);
+		if (tombstone) {
+			resolvedRunResults.delete(runId);
+			return tombstone;
+		}
 		const delay = Math.min(pollIntervalMs, 50 * 2 ** Math.min(attempt, 6)); // max ~3.2s
 		await new Promise((r) => setTimeout(r, delay));
 		attempt++;
@@ -176,6 +230,7 @@ export function hasActiveRunPromise(runId: string): boolean {
 
 export function clearRunPromisesForTest(): void {
 	detachRequests.clear();
+	resolvedRunResults.clear();
 	for (const entry of activeRunPromises.values()) {
 		entry.reject(new Error("Cleared by test"));
 	}

package/src/runtime/skill-instructions.ts

@@ -1,14 +1,14 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { fileURLToPath } from "node:url";
 import type { AgentConfig } from "../agents/agent-config.ts";
 import type { TeamRole } from "../teams/team-config.ts";
 import { logInternalError } from "../utils/internal-error.ts";
+import { packageRoot } from "../utils/paths.ts";
 import { isSafePathId, resolveRealContainedPath } from "../utils/safe-paths.ts";
 import type { WorkflowStep } from "../workflows/workflow-config.ts";
 import { CONFIDENCE_THRESHOLDS, getWeightedSkillsForRole, registerSkillEffectivenessHooks } from "./skill-effectiveness.ts";
 
-const PACKAGE_SKILLS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "skills");
+const PACKAGE_SKILLS_DIR = path.join(packageRoot(), "skills");
 
 import * as os from "node:os";
 // peer-dep.ts resolves @earendil-works/pi-coding-agent robustly across install
@@ -121,8 +121,24 @@ function collectTaskSkillNames(input: ResolveTaskSkillsInput | undefined): strin
 	if (input.agent?.skills?.length) names.push(...input.agent.skills);
 	if (Array.isArray(input.teamRole?.skills)) names.push(...input.teamRole.skills);
 	if (Array.isArray(input.step?.skills)) names.push(...input.step.skills);
-	if (Array.isArray(input.override)) names.push(...input.override);
-	return unique(names);
+	// SKILL-HYGIENE-2: support wildcard (`*`) and denylist (`!name`) syntax in override.
+	// - `*` is a marker (no-op; defaults already included via defaultSkillsForRole).
+	// - `!name` removes `name` from the final selection.
+	// - Other names are added (existing additive behavior).
+	const denylist = new Set<string>();
+	if (Array.isArray(input.override)) {
+		for (const item of input.override) {
+			if (item === "*") {
+				// wildcard marker; defaults already in names via defaultSkillsForRole
+			} else if (item.startsWith("!")) {
+				denylist.add(item.slice(1));
+			} else {
+				names.push(item);
+			}
+		}
+	}
+	if (denylist.size === 0) return unique(names);
+	return unique(names).filter((n) => !denylist.has(n));
 }
 
 export function resolveTaskSkillNames(input: ResolveTaskSkillsInput): string[] {

package/src/runtime/task-runner/child-executor.ts

@@ -107,7 +107,7 @@ async function appendBackgroundLogAsync(bgLogPath: string, eventLine: string): P
 
 /**
  * F7: resolve the enabledModels allowlist for the child-process spawn path,
- * but only if `runtime.reliability.scopeModels` is ON. Returns [] (no-op)
+ * but only if `reliability.scopeModels` is ON. Returns [] (no-op)
  * when the toggle is off or the allowlist is empty. Best-effort: any failure
  * to read config or the allowlist silently disables the gate so spawn is
  * never blocked by a misconfiguration.

package/src/runtime/task-runner/prompt-builder.ts

@@ -35,10 +35,11 @@ function readOnlyRoleInstructions(role: string): string {
 	].join("\n");
 }
 
-export function coordinationBridgeInstructions(task: TeamTaskState): string {
+export function coordinationBridgeInstructions(task: TeamTaskState, opts?: { includeMailboxTarget?: boolean }): string {
+	const includeMailboxTarget = opts?.includeMailboxTarget ?? true;
 	return [
 		"# Crew Coordination Channel",
-		`Mailbox target for this task: ${task.id}`,
+		...(includeMailboxTarget ? [`Mailbox target for this task: ${task.id}`] : []),
 		"Use the run mailbox contract for coordination with the leader/orchestrator:",
 		"- If blocked or uncertain, report the blocker in your final result and, when mailbox tools/API are available, send an inbox/outbox message addressed to the leader.",
 		"- Never guess implementation details that materially affect decisions. If the `ask` tool is available and you need a clarification, a decision, or a missing requirement before you can proceed safely, call `ask` and wait — a parked question is cheaper than a wrong build.",
@@ -262,7 +263,10 @@ export async function renderTaskPrompt(
 	// computation for parallel siblings in the same batch.
 	const stableComponents = precomputedStableComponents ?? (await computeStablePrefixComponents(manifest, step, task, agent));
 
-	// Stable prefix: role instructions, coordination, workspace tree — rarely changes
+	// Stable prefix: role instructions, coordination, workspace tree — rarely changes.
+	// ARCH-3 (byte-stable worker prefix): per-task values (Task ID, Task cwd, mailbox
+	// target) live in dynamicSuffix so siblings sharing a run+role produce a
+	// byte-identical prefix and hit provider KV-cache across the batch.
 	const stablePrefix = [
 		"# pi-crew Worker Runtime Context",
 		`Run ID: ${manifest.runId}`,
@@ -271,8 +275,6 @@ export async function renderTaskPrompt(
 		`State root: ${manifest.stateRoot}`,
 		`Artifacts root: ${manifest.artifactsRoot}`,
 		`Events path: ${manifest.eventsPath}`,
-		`Task ID: ${task.id}`,
-		`Task cwd: ${task.cwd}`,
 		`Workspace mode: ${manifest.workspaceMode}`,
 		"",
 		"Protocol:",
@@ -280,10 +282,14 @@ export async function renderTaskPrompt(
 		"- Report blockers and verification evidence in the final result.",
 		"- Do not claim completion without evidence.",
 		"- Follow the Task Packet contract below; escalate if any contract field is impossible to satisfy.",
+		// PROMPT-2 (port of OMO-slim task-rejection, improved phrasing): a
+		// universal lane-guard for every role — complements the per-agent reject
+		// sections in agents/*.md with a scaffold-level instruction.
+		"- If a task falls outside your role, do not attempt partial work. Return a concise rejection to the leader naming the lane that should own it.",
 		"",
 		readOnlyRoleInstructions(task.role),
 		"",
-		coordinationBridgeInstructions(task),
+		coordinationBridgeInstructions(task, { includeMailboxTarget: false }),
 		"",
 		stableComponents.treeBlock,
 		"",
@@ -291,9 +297,13 @@ export async function renderTaskPrompt(
 		"",
 		toolGuidanceBlock(agent),
 		"",
-		// O4: project knowledge (.crew/knowledge.md) — workers don't load the
-		// pi-crew extension (spawned with --no-extensions), so before_agent_start
-		// never fires for them. Inject here so every worker sees project knowledge.
+		// O4 (ARCH-2 corrected): project knowledge (.crew/knowledge.md). Builtin
+		// workers don't load the pi-crew extension (agents declare no `extensions:`
+		// in frontmatter), so before_agent_start knowledge injection doesn't fire
+		// for them — and the knowledge-injection hook now early-returns on
+		// PI_CREW_KIND=subagent, so even agents that DO declare the extension
+		// can't double-inject. This prompt-builder fragment is the single source
+		// of worker project knowledge.
 		stableComponents.knowledgeFragment,
 	]
 		.filter(Boolean)
@@ -301,6 +311,9 @@ export async function renderTaskPrompt(
 
 	// Dynamic suffix: goal, step, skills, task packet, dependency context, memory — changes per task
 	const dynamicSuffix = [
+		`Task ID: ${task.id}`,
+		`Task cwd: ${task.cwd}`,
+		`Mailbox target: ${task.id}`,
 		`Goal:\n${manifest.goal}`,
 		"",
 		`Step: ${step.id}`,

package/src/schema/config-schema.ts

@@ -270,6 +270,7 @@ export const PiTeamsReliabilityConfigSchema = Type.Object(
 		ambientStatusInjection: Type.Optional(Type.Boolean()),
 		perWriteValidation: Type.Optional(Type.Boolean()),
 		scopeModels: Type.Optional(Type.Boolean()),
+		loopGuard: Type.Optional(Type.Boolean()),
 	},
 	{ additionalProperties: false },
 );

package/src/skills/discover-skills.ts

@@ -1,15 +1,15 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { fileURLToPath } from "node:url";
 // peer-dep.ts resolves @earendil-works/pi-coding-agent robustly across install
 // layouts. See src/runtime/peer-dep.ts (split-scope install fix).
 import { getAgentDir } from "../runtime/peer-dep.ts";
 import { logInternalError } from "../utils/internal-error.ts";
+import { packageRoot } from "../utils/paths.ts";
 import { isSafePathId, resolveContainedPath, resolveRealContainedPath } from "../utils/safe-paths.ts";
 import { parseSkillFrontmatter, type SkillValidationError, validateSkillFrontmatter } from "./validate.ts";
 
-const PACKAGE_SKILLS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "skills");
+const PACKAGE_SKILLS_DIR = path.join(packageRoot(), "skills");
 
 const CACHE_TTL_MS = 30_000; // 30 seconds
 let cache: { skills: SkillDescriptor[]; cachedAt: number; cwd: string } | null = null;

package/src/ui/settings-overlay.ts

@@ -304,6 +304,41 @@ const SETTINGS: SettingDef[] = [
 		tab: "advanced",
 		description: "Remove /tmp/pi-crew-* directories after reconciliation (1h age threshold).",
 	},
+	{
+		id: "reliability.loopGuard",
+		label: "Tool Loop Guard",
+		type: "boolean",
+		tab: "advanced",
+		description: "Warn at 3 / block at 5 identical consecutive read-only tool results (ARCH-1).",
+	},
+	{
+		id: "reliability.perWriteValidation",
+		label: "Per-Write Validation",
+		type: "boolean",
+		tab: "advanced",
+		description: "Validate state writes as they are made (default on).",
+	},
+	{
+		id: "reliability.ambientStatusInjection",
+		label: "Ambient Status Injection",
+		type: "boolean",
+		tab: "advanced",
+		description: "Inject a compact crew-status note into context on every LLM call while runs are in-flight.",
+	},
+	{
+		id: "reliability.forcePreflight",
+		label: "Force Preflight (audit override)",
+		type: "boolean",
+		tab: "advanced",
+		description: "Skip usage-threshold BLOCK/WARN preflight. Default false (enforce). Audit/debug only.",
+	},
+	{
+		id: "reliability.scopeModels",
+		label: "Scope Models (F7)",
+		type: "boolean",
+		tab: "advanced",
+		description: "Enforce user enabledModels allowlist on subagent model choices. Default false.",
+	},
 	{
 		id: "telemetry.enabled",
 		label: "Telemetry",
@@ -359,6 +394,11 @@ const EFFECTIVE_DEFAULTS: Record<string, unknown> = {
 	"reliability.autoRetry": false,
 	"reliability.autoRecover": false,
 	"reliability.cleanupOrphanedTempDirs": true,
+	"reliability.loopGuard": true,
+	"reliability.perWriteValidation": true,
+	"reliability.ambientStatusInjection": true,
+	"reliability.forcePreflight": false,
+	"reliability.scopeModels": false,
 	"telemetry.enabled": false,
 	"notifications.enabled": false,
 };

package/src/utils/frontmatter.ts

@@ -35,7 +35,13 @@ function parseLines(raw: string): Record<string, string> {
 		const separator = trimmed.indexOf(":");
 		if (separator === -1) continue;
 		const key = trimmed.slice(0, separator).trim();
-		const value = trimmed.slice(separator + 1).trim();
+		let value = trimmed.slice(separator + 1).trim();
+		// Strip one pair of symmetric surrounding double quotes so quoted
+		// frontmatter values (required by strict YAML when the value contains
+		// ": ") behave identically to unquoted ones for every consumer.
+		if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
+			value = value.slice(1, -1);
+		}
 		if (key) frontmatter[key] = value;
 	}
 	return frontmatter;

package/src/utils/ndjson.ts

@@ -17,7 +17,15 @@ export const MAX_BROKER_FRAME_BYTES = 256 * 1024;
 // BrokerError — typed protocol errors
 // ============================================================================
 
-export type BrokerErrorCode = "oversize-frame" | "auth" | "protocol" | "timeout" | "close" | "not-implemented" | "rate-limit";
+export type BrokerErrorCode =
+	| "oversize-frame"
+	| "auth"
+	| "protocol"
+	| "timeout"
+	| "request-timeout"
+	| "close"
+	| "not-implemented"
+	| "rate-limit";
 
 export class BrokerError extends Error {
 	readonly code: BrokerErrorCode;