pi-crew 0.9.61 → 0.9.64

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.9.61",
+  "version": "0.9.64",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",
@@ -61,7 +61,9 @@
     "types/",
     "CHANGELOG.md",
     "LICENSE",
-    "NOTICE.md"
+    "NOTICE.md",
+    "scripts/resource-sampler.mjs",
+    "scripts/analyze-run.mjs"
   ],
   "scripts": {
     "check": "npm run ci",
@@ -79,6 +81,7 @@
     "test:watch": "tsx --watch --test --test-concurrency=4 --test-timeout=30000 --test-force-exit 'test/unit/**/*.test.ts'",
     "test:integration": "node scripts/test-runner.mjs --test-concurrency=1 --test-timeout=300000 test/integration/*.test.ts",
     "test:smoke": "node scripts/test-runner.mjs --test-concurrency=1 --test-timeout=180000 test/smoke/*.smoke.ts",
+    "test:spike": "node scripts/test-runner.mjs --test-concurrency=2 --test-timeout=120000 --test-force-exit test/runtime/scratchpad/*.test.ts",
     "build:bundle": "node scripts/build-bundle.mjs",
     "test:bundle": "node --experimental-strip-types --test --test-force-exit test/unit/bundle-load.test.ts",
     "watch:bundle": "node scripts/watch-bundle.mjs",

package/src/agents/agent-config.ts

@@ -60,6 +60,10 @@ export interface AgentConfig {
 	fallbackModels?: string[];
 	thinking?: string;
 	tools?: string[];
+	/** Phase 1 scratchpad opt-in (execute tool). `false` wins over a
+	 * role default (F6 kill-switch); read-only roles are gated out regardless
+	 * (S-6) by `isScratchpadEnabledForRole`. Parsed from frontmatter `scratchpad:`. */
+	scratchpad?: boolean;
 	extensions?: string[];
 	/**
 	 * F1 (v0.7.9): extension denylist (case-insensitive plain names). Applied

package/src/agents/agent-serializer.ts

@@ -15,6 +15,7 @@ export function serializeAgent(agent: AgentConfig): string {
 		line("fallbackModels", agent.fallbackModels),
 		line("thinking", agent.thinking),
 		line("tools", agent.tools),
+		line("scratchpad", agent.scratchpad),
 		agent.extensions !== undefined ? (line("extensions", agent.extensions) ?? "extensions:") : undefined,
 		line("skills", agent.skills),
 		line("systemPromptMode", agent.systemPromptMode),

package/src/agents/discover-agents.ts

@@ -427,6 +427,14 @@ function parseAgentFile(filePath: string, source: ResourceSource): AgentConfig |
 			fallbackModels: parseCsv(frontmatter.fallbackModels),
 			thinking: frontmatter.thinking === "false" ? undefined : frontmatter.thinking || undefined,
 			tools: parseToolsField(frontmatter.tools),
+			// Phase 1 scratchpad opt-in (Q3: pi ignores unknown frontmatter keys; pi-crew
+			// is the sole consumer in the worker path — task arrives via -p, agent file
+			// is not re-read by pi). 3-STATE parse (NOT `=== "true"` like
+			// inheritProjectContext): omitted/malformed → undefined so the F6 kill-switch
+			// (`agent.scratchpad === false`) only fires on an EXPLICIT `scratchpad: false`,
+			// not on every agent without the key (which would wrongly kill role
+			// default-on). Only the literal "true"/"false" are honored.
+			scratchpad: frontmatter.scratchpad === "true" ? true : frontmatter.scratchpad === "false" ? false : undefined,
 			// SEC-1: Strip extensions/excludeExtensions for untrusted project-sourced
 			// agents (RCE prevention). Both `project` (.crew/agents/) and
 			// `project-pi` (.pi/agents/) are repo-adjacent / untrusted sources —

package/src/config/role-tools.ts

@@ -3,11 +3,17 @@
  * Uses the excludeTools option from pi v0.77.0.
  */
 
+import { permissionForRole } from "../runtime/role-permission.ts";
+
 export interface RoleToolConfig {
 	/** Explicit list of tools to use (if undefined, use all default tools) */
 	tools?: string[];
 	/** Tools to exclude from the default set */
 	excludeTools?: string[];
+	/** Phase 1 scratchpad: opt-in the persistent Bun-free JS evaluator (execute tool)
+	 * for this role. Only effective on WRITE roles — read-only roles are gated
+	 * out by `isScratchpadEnabledForRole` (S-6, privilege-elevation guard). */
+	scratchpad?: boolean;
 }
 
 export const ROLE_TOOL_CONFIGS: Record<string, RoleToolConfig> = {
@@ -44,9 +50,11 @@ export const ROLE_TOOL_CONFIGS: Record<string, RoleToolConfig> = {
 		excludeTools: ["edit", "write", "bash", "web"],
 	},
 
-	// Executor - Full access (default)
+	// Executor - Full access (default). Phase 1 scratchpad-enabled (stateful
+	// evaluator compounds intermediate results across execute calls).
 	executor: {
 		// No restrictions - full tool access
+		scratchpad: true,
 	},
 
 	// Reviewer - Read and review, no write
@@ -78,12 +86,16 @@ export const ROLE_TOOL_CONFIGS: Record<string, RoleToolConfig> = {
 	verifier: {
 		tools: ["read", "grep", "find", "ls", "bash"],
 		excludeTools: ["edit", "write", "web"],
+		// Phase 1 scratchpad: multi-cell test/verify flows reuse parsed state.
+		scratchpad: true,
 	},
 
 	// Test Engineer - Can write tests (F1: hyphenated key)
 	"test-engineer": {
 		tools: ["read", "edit", "write", "bash", "ls"],
 		excludeTools: ["web"],
+		// Phase 1 scratchpad: build/run test suites with state across cells.
+		scratchpad: true,
 	},
 };
 
@@ -116,3 +128,39 @@ export function getRestrictedRoles(): string[] {
 		.filter(([, config]) => config.tools !== undefined || config.excludeTools !== undefined)
 		.map(([role]) => role);
 }
+
+/** Agent frontmatter shape consumed by the scratchpad opt-in check. */
+export interface ScratchpadAgentOption {
+	scratchpad?: boolean;
+}
+
+/**
+ * Phase 1: is the scratchpad (execute tool) enabled for this role/agent?
+ *
+ * Decision order (load-bearing — do not reorder):
+ *  1. S-6 (SECURITY, privilege-elevation guard): read-only roles NEVER enable,
+ *     regardless of any agent frontmatter opt-in. A `scratchpad: true` on a
+ *     read-only role (e.g. security-reviewer, whose tool-set is read/grep/find
+ *     with NO bash) would grant full-trust JS execution (fs/network/env/
+ *     child_process) inside a role designed to have no execution — a real
+ *     elevation. `permissionForRole` is default-deny (unknown → read_only), so
+ *     typos/underscore/case-drift cannot bypass this.
+ *  2. F6 (kill-switch): `agent.scratchpad === false` WINS over the role default,
+ *     giving an emergency off-switch for an experimental full-trust feature.
+ *  3. agent explicit opt-in (`scratchpad: true`) OR role default (`scratchpad:
+ *     true` in ROLE_TOOL_CONFIGS).
+ *
+ * F10: `permissionForRole` and `getToolConfig` both expect HYPHENATED role
+ * strings (runtime convention); a raw underscore role would default-deny
+ * wrongly, so normalize FIRST.
+ */
+export function isScratchpadEnabledForRole(role: string, agent?: ScratchpadAgentOption): boolean {
+	// F10: normalize underscore→hyphen before every downstream lookup.
+	const normalized = role.includes("_") ? role.replaceAll("_", "-") : role;
+	// S-6 (điều kiện tiên quyết): read-only gate trước mọi agent flag.
+	if (permissionForRole(normalized) === "read_only") return false;
+	// F6: explicit-false agent override (kill-switch) wins over role default.
+	if (agent?.scratchpad === false) return false;
+	// agent explicit opt-in OR role default.
+	return agent?.scratchpad === true || getToolConfig(normalized).scratchpad === true;
+}

package/src/extension/notification-router.ts

@@ -10,6 +10,8 @@ export interface NotificationDescriptor {
 	title: string;
 	body?: string;
 	timestamp?: number;
+	/** When true, this is a dismiss/clear request for a previously-emitted notification (same id). Bypasses dedup/severity/quiet-hours; the deliver callback drops the matching notification. */
+	clear?: boolean;
 }
 
 export interface NotificationRouterOptions {
@@ -99,6 +101,29 @@ export class NotificationRouter {
 			...notification,
 			timestamp: notification.timestamp ?? now,
 		};
+		// Clear path: remove the id from `seen` so a future genuine re-occurrence
+		// can re-notify. Delivery is guarded on whether the id was actually in
+		// `seen` to keep the clear idempotent (bypassing dedup / severity filter /
+		// quiet hours when it does deliver — a clear must go through so the
+		// dashboard can drop the previously-emitted notification).
+		if (withTime.clear) {
+			const clearKey = notificationKey(withTime);
+			// Idempotent: only deliver the clear if the id was actually in `seen`
+			// (i.e., a notification for it was previously emitted and not yet
+			// cleared). This prevents multi-fire drift when the render loop calls
+			// clearHealthNotifications on consecutive ticks for the same terminal
+			// run — each clear after the first is a silent no-op that returns true.
+			const wasInSeen = this.seen.delete(clearKey);
+			if (wasInSeen) {
+				try {
+					this.opts.sink?.(withTime);
+				} catch (sinkError) {
+					logInternalError("notification-sink", sinkError);
+				}
+				this.deliver(withTime);
+			}
+			return true;
+		}
 		try {
 			this.opts.sink?.(withTime);
 		} catch (sinkError) {

package/src/extension/registration/lifecycle-handlers.ts

@@ -25,10 +25,9 @@ import { CrewBroker } from "../../runtime/broker/crew-broker.ts";
 import { terminateActiveChildPiProcesses } from "../../runtime/child-pi/child-pi.ts";
 import { listLiveAgents } from "../../runtime/live-session/live-agent-manager.ts";
 import type { createManifestCache } from "../../runtime/manifest-cache.ts";
-import { providerOfModelRef } from "../../runtime/model/model-fallback.ts";
 import { cleanupLegacyOrphanTempDirs, cleanupOrphanTempDirs, currentCrewDepth } from "../../runtime/model/pi-args.ts";
 import { clearProviderQuotaCache, noteProviderResponse } from "../../runtime/model/provider-quota.ts";
-import { currentSessionModel, noteSessionModel, noteSessionThinking } from "../../runtime/model/session-model.ts";
+import { noteSessionModel, noteSessionThinking, resolveProviderForResponse } from "../../runtime/model/session-model.ts";
 import { cleanupOrphanWorkers } from "../../runtime/orphan-worker-registry.ts";
 import { reconcileAllStaleRuns } from "../../runtime/recovery/crash-recovery.ts";
 import { CrewScheduler, type ScheduledJob } from "../../runtime/scheduling/scheduler.ts";
@@ -93,8 +92,7 @@ function installModelTrackingHandlers(pi: ExtensionAPI): void {
 	// providers. The event doesn't carry a provider field, so we attribute it
 	// to the currently tracked session model's provider.
 	pi.on("after_provider_response", (event) => {
-		const model = currentSessionModel();
-		const provider = model ? providerOfModelRef(model) : undefined;
+		const provider = resolveProviderForResponse();
 		if (provider) noteProviderResponse(provider, event.status, event.headers);
 	});
 }
@@ -666,12 +664,55 @@ function setupRenderLoop(
 		const currentSessionId = ctx.currentCtx?.sessionManager?.getSessionId();
 		const sessionManifests = filterManifestsForHealthNotifications(manifests, currentSessionId);
 		const now = Date.now();
+		// FIX #2: clear path — when a run is detected terminal, dismiss any
+		// previously-emitted health notification for it AND drop its cooldown
+		// (autoRecoveryLast) so a future genuine re-occurrence can re-notify.
+		// Keeps the dashboard clean and stops the 5-min re-fire cycle.
+		const clearHealthNotifications = (runId: string): void => {
+			for (const kind of ["recovery_dead_workers", "recovery_missing_heartbeat"]) {
+				const key = `${kind}_${runId}`;
+				ctx.autoRecoveryLast.delete(key);
+				ctx.notifyOperator({
+					id: key,
+					clear: true,
+					severity: "info",
+					source: "health",
+					runId,
+					title: `Cleared ${kind} for ${runId}`,
+				});
+			}
+		};
 		for (const run of sessionManifests) {
-			if (run.status !== "running") continue;
+			if (run.status !== "running") {
+				// GATE 1 — preloaded manifest says terminal. Purge any stale snapshot
+				// and clear previously-emitted health notifications so the dashboard
+				// stays clean (belt-and-suspenders with the FIX #1 fresh-read gate).
+				snapshotCache.invalidate(run.runId);
+				clearHealthNotifications(run.runId);
+				continue;
+			}
 			try {
+				// FIX #1: re-verify against a FRESH manifest read. The preloaded `run`
+				// (from lastPreloadedManifests) can lag the on-disk terminal
+				// transition; the manifest cache has a 500ms TTL + file watcher so it
+				// is the source of truth. A terminal run must NEVER reach
+				// maybeNotifyHealth. Also purge the stale snapshot + clear any
+				// previously-emitted health notification for this run.
+				const freshManifest = ctx.getManifestCache(extensionCtx.cwd).get(run.runId);
+				if (freshManifest?.status !== "running") {
+					snapshotCache.invalidate(run.runId);
+					clearHealthNotifications(run.runId);
+					continue;
+				}
 				const snapshot = snapshotCache.get(run.runId);
 				if (!snapshot) continue;
-				if (snapshot.manifest.status !== "running") continue;
+				if (snapshot.manifest.status !== "running") {
+					// GATE 2 — a running snapshot paired with a now-terminal manifest is
+					// stale. Purge it so subsequent ticks get a fresh view, and clear.
+					snapshotCache.invalidate(run.runId);
+					clearHealthNotifications(run.runId);
+					continue;
+				}
 				const summary = summarizeHeartbeats(snapshot, { now });
 				const maybeNotifyHealth = (kind: string, count: number, title: string, body: string): void => {
 					if (count <= 0) return;

package/src/extension/registration/lifecycle.ts

@@ -148,13 +148,19 @@ export async function configureNotifications(ctx: ExtensionContext, state: Lifec
 			sink: (notification) => state.notificationSink?.write(notification),
 		},
 		(notification: NotificationDescriptor) => {
-			deps.widgetState.notificationCount = (deps.widgetState.notificationCount ?? 0) + 1;
-			sendFollowUp(
-				deps.pi,
-				[notification.title, notification.body, notification.runId ? `Run: ${notification.runId}` : undefined]
-					.filter((line): line is string => Boolean(line))
-					.join("\n"),
-			);
+			if (notification.clear) {
+				// Clear/dismiss: decrement the counter (floor 0) and skip the
+				// follow-up message — this is a dismissal, not a new alert.
+				deps.widgetState.notificationCount = Math.max(0, (deps.widgetState.notificationCount ?? 0) - 1);
+			} else {
+				deps.widgetState.notificationCount = (deps.widgetState.notificationCount ?? 0) + 1;
+				sendFollowUp(
+					deps.pi,
+					[notification.title, notification.body, notification.runId ? `Run: ${notification.runId}` : undefined]
+						.filter((line): line is string => Boolean(line))
+						.join("\n"),
+				);
+			}
 			const currentCtx = deps.getCurrentCtx();
 			if (currentCtx) {
 				const uiConfig = loadConfig(currentCtx.cwd).config.ui;

package/src/prompt/prompt-runtime.ts

@@ -4,6 +4,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { startChildBrokerClient } from "../runtime/broker/crew-broker-child.ts";
 import { logInternalError } from "../utils/internal-error.ts";
 import { resolveRealContainedPath } from "../utils/safe-paths.ts";
+import { registerScratchpadLifecycle } from "./scratchpad-lifecycle.ts";
 
 export const PI_TEAMS_INHERIT_PROJECT_CONTEXT_ENV = "PI_TEAMS_INHERIT_PROJECT_CONTEXT";
 export const PI_TEAMS_INHERIT_SKILLS_ENV = "PI_TEAMS_INHERIT_SKILLS";
@@ -377,4 +378,9 @@ export default function registerPiTeamsPromptRuntime(pi: ExtensionAPI): void {
 		if (rewritten === event.systemPrompt) return;
 		return { systemPrompt: rewritten };
 	});
+
+	// ── Phase 1 scratchpad (T6): conditional `execute` tool + EngineManager
+	// lifecycle. Registers nothing when PI_CREW_SCRATCHPAD !== "1" (D3) and
+	// only flushes+kills the engine on session_shutdown reason "quit" (F3).
+	registerScratchpadLifecycle(pi);
 }