pi-crew 0.8.3 → 0.8.5

package/CHANGELOG.md

@@ -1,5 +1,99 @@
 # Changelog
 
+## [0.8.5] — Per-write validator (T5) + validateWorkflowForTeam race note (2026-06-16)
+
+Third APPLIED technique from the pi-ecosystem distillation (pi-lens /
+apmantza — the "inline channel"). Adds real-time feedback on file
+writes/edits: a CHEAP synchronous validator runs on every `write`/`edit`
+tool result and appends a `🔴` blocker to the tool result on failure, so
+malformed files are caught the moment they're written — not at the next
+load.
+
+### Latency-safe v1 design (deliberate scope)
+
+pi-lens runs LSP servers + linters per write. That is expensive and would
+cause latency storms if naively ported (seconds of spawn per edit, firing in
+the main session AND every worker). This v1 ships ONLY zero-cost, zero-spawn,
+synchronous validators:
+
+- **`json` → `JSON.parse`** (nanoseconds, built-in, no process spawn).
+
+The registry is extensible — process-spawning validators (`.js` → `node
+--check`, `.sh` → `bash -n`, `.py` → `py_compile`) are a FUTURE opt-in
+(never default-on), and will need to be async + debounced (pi-lens's
+`inFlightPipelines` / debounce-window pattern) when added.
+
+### Contract guarantees
+- Synchronous. No `await`, no `spawn`, no disk write.
+- One disk READ per validated file (after a cheap extension check, so
+  non-validated files cost nothing).
+- Dedup by content: the same path+content is validated at most once per
+  process.
+- Silent on success; appends exactly one TextContent block on failure.
+- Best-effort: any internal error is swallowed (never breaks a write).
+- Toggle: `runtime.reliability.perWriteValidation` (default `true` → opt-out).
+
+### Files
+- NEW `src/runtime/per-write-validator.ts` — `validateJson`, the extensible
+  `PerWriteValidator` registry, dedup cache, `validateWrittenFile`, and
+  `buildValidationBlocker`. Test seams: `setPerWriteValidatorsForTest`,
+  `resetPerWriteValidatorCache`.
+- `src/config/types.ts` — `reliability.perWriteValidation?: boolean`.
+- `src/extension/register.ts` — `pi.on("tool_result", ...)` handler for
+  `write`/`edit` (pi-crew previously subscribed only to `tool_call`).
+- NEW `test/unit/t5-per-write-validator.test.ts` (15 tests).
+- NEW `.github/issues/2026-06-16-validateworkflowf-team-cold-start-race.md` —
+  honest note that the `validateWorkflowForTeam` cold-start error (same
+  class as v0.8.1's `existsSync`) was NOT actually fixed by v0.8.1's latch
+  (that covered only the peer-dep namespace). Documents the corrected
+  root cause (tsx makes every named import a runtime namespace access) and
+  4 candidate fixes for the later pass.
+
+typecheck clean; full suite 0 failures.
+
+## [0.8.4] — cold-verifier agent (T9) (2026-06-16)
+
+Second APPLIED technique from the pi-ecosystem distillation (piolium /
+Vigolium — cold-verifier pattern). Adds a new builtin agent whose value is
+**independence**: it re-derives claims from ground truth WITHOUT trusting
+prior reviewer/verifier analysis, breaking the confirmation-bias drift the
+chained `reviewer` → `verifier` path can introduce.
+
+### Why
+piolium splits security verification across ~10 narrow agents, including a
+`cold-verifier` whose prompt enforces file-access isolation ("MUST NOT read
+any file other than the single finding draft"). pi-crew's default `verifier`
+instead *correlates* findings against reviewer output ("Trust dependency
+context") — efficient, but it inherits the reviewer's blind spots. There was
+**no** adversarial cross-check agent (confirmed: zero agents reference
+cold/isolation/unbiased semantics).
+
+### What
+NEW builtin `cold-verifier` agent (`agents/cold-verifier.md`):
+- Read-only + `bash` (runs tests fresh, reads its OWN output — never a
+  cached prior-worker log).
+- Prompt-enforced isolation discipline: don't trust prior findings, treat
+  each as an *unverified hypothesis*, actively look for contradicting evidence.
+- Distinct `COLD_VERIFICATION` output block with a `CLAIMS_REFUTED` field
+  (the highest-value output — inherited claims your independent check
+  contradicts).
+- `maxTurns: 12` (tighter than verifier's 15 — it's a focused cross-check).
+
+Use `verifier` for fast finding-correlation; use `cold-verifier` when the
+cost of a wrong "PASS" is high (security changes, release gates, data-loss
+paths). Both can run in the same workflow.
+
+### Files
+- NEW `agents/cold-verifier.md` — the agent (auto-discovered).
+- `src/agents/discover-agents.ts` — add `cold-verifier` to the SEC-001
+  `PROTECTED_AGENT_NAMES` blocklist (can't be shadowed by a dynamic reg).
+- `src/ui/settings-overlay.ts` — add to the settings-overlay agent list.
+- `test/unit/agent-discovery-cache.test.ts` — mirror the protected-names list.
+- NEW `test/unit/t9-cold-verifier.test.ts` (5 tests): discovery, parse,
+  isolation-discipline content, SEC-001 protection, frontmatter shape.
+
+typecheck clean; full suite 1905 ok / 0 fail.
+
 ## [0.8.3] — Terminal tab title + Ghostty native progress bar (T4) (2026-06-16)
 
 First APPLIED technique from the pi-ecosystem distillation (pi-status /

package/agents/cold-verifier.md

@@ -0,0 +1,66 @@
+---
+name: cold-verifier
+description: Independently re-verify findings WITHOUT trusting prior analysis — an unbiased cold check to catch confirmation bias the chained reviewer/verifier path can introduce
+model: false
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+tools: read, grep, find, ls, bash
+maxTurns: 12
+---
+
+You are a **cold verifier**. Your value is independence: you re-check claims against ground truth WITHOUT trusting the analysis that came before you. The chained `reviewer` → `verifier` path can drift into confirmation bias (each worker rationalizes the prior worker's framing). You break that loop by starting cold.
+
+## Isolation Rules (THE CORE DISCIPLINE)
+
+Distilled from piolium's cold-verifier pattern: prompt-enforced file-access isolation layered on top of context isolation.
+
+You **MUST NOT**:
+- Read other workers' notes, debate transcripts, or `.crew/artifacts/.../results/*.txt` reasoning files.
+- Read the reviewer's or verifier's finding drafts as if they were ground truth.
+- Be primed by the goal framing beyond the literal acceptance criteria. Re-derive what "done" means from the spec, not from someone's summary of it.
+- Start from the conclusion that the work is correct (or incorrect). Start from evidence.
+
+You **MUST**:
+- Re-derive each claim from the codebase + test output directly.
+- Treat every inherited finding as an *unverified hypothesis* until you confirm it yourself.
+- Actively look for evidence that *contradicts* the prior verdict, not just evidence that supports it.
+
+## Strategy
+
+### Turn 1: Establish ground truth independently
+Run the test suite / build / lint fresh and read the *actual output*:
+```bash
+npm test 2>&1 | tail -40
+```
+Do NOT read a cached log from a prior worker — re-run and read your own output. If a prior worker claims "tests pass", confirm the green output yourself.
+
+### Turn 2-N: Verify each claim from source
+For each claim in the task/goal, open the *actual source files* and confirm:
+- Does the code do what's claimed?
+- Do tests actually cover the claimed behavior (not just pass for unrelated reasons)?
+- Is there a claim that is true *in isolation* but false *in context* (e.g. a function works but is never called, a check passes but the input is never reachable)?
+
+Look specifically for:
+- **False confirmations**: a prior worker said "verified" but the evidence is weaker than implied (e.g. a test passes but asserts the wrong thing).
+- **Missing cases**: the prior analysis didn't consider an edge case, error path, or interaction.
+- **Scope creep masquerading as done**: the stated goal is met but a regression was introduced elsewhere.
+
+## What makes you different from `verifier`
+
+The default `verifier` *correlates* findings against reviewer output ("Trust dependency context"). That's efficient but inherits the reviewer's blind spots. You are the **adversarial cross-check**: assume the prior verdict *might be wrong* and try to find where. Use `verifier` for fast correlation; use `cold-verifier` when the cost of a wrong "PASS" is high (security changes, release gates, data-loss paths).
+
+## Output Format
+
+End with exactly this block:
+
+```
+COLD_VERIFICATION: PASS|FAIL|INCONCLUSIVE
+INDEPENDENT_TEST_RESULTS: X passed, Y failed, Z skipped (from your OWN run, not a cached log)
+CLAIMS_CONFIRMED_INDEPENDENTLY: N/M inherited claims reproduced from source
+CLAIMS_REFUTED: any inherited claim your independent check contradicts (highest-value output)
+MISSING_COVERAGE: cases the prior analysis overlooked
+EVIDENCE: file:line references + your own test output
+```
+
+If you cannot refute a claim after honest effort, that is itself evidence the claim is solid — say so explicitly rather than inventing doubt.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",

package/src/agents/discover-agents.ts

@@ -48,6 +48,7 @@ const PROTECTED_AGENT_NAMES = new Set([
 	"critic",
 	"reviewer",
 	"verifier",
+	"cold-verifier", // T9 (v0.8.4): adversarial cold cross-check agent
 	"writer",
 	"security-reviewer",
 ]);

package/src/config/types.ts

@@ -180,6 +180,15 @@ export interface CrewReliabilityConfig {
 	cleanupOrphanedTempDirs?: boolean;
 	/** Inject a compact ambient crew-status note into the agent's context on every LLM call while crew runs are in-flight, so the agent stays continuously aware of active runs without calling the `team` tool. No-op when no runs are active. Default: true. */
 	ambientStatusInjection?: boolean;
+	/**
+	 * Per-write validation (T5). On every `write`/`edit` tool result, run a
+	 * zero-cost synchronous validator for the file type and append a `🔴`
+	 * blocker to the tool result on failure (e.g. malformed JSON). v1 ships
+	 * JSON only (`JSON.parse` — instant, no process spawn); process-spawning
+	 * validators (.js/.sh/.py) are a future opt-in. Default: true (opt-out).
+	 * Set to `false` to disable.
+	 */
+	perWriteValidation?: boolean;
 	/**
 	 * Opt-in model scope enforcement (F7). When true, subagent model choices
 	 * that fall outside the user's pi `enabledModels` allowlist are flagged:

package/src/extension/register.ts

@@ -82,6 +82,7 @@ import {
 import { RenderScheduler } from "../ui/render-scheduler.ts";
 import { runEventBus } from "../ui/run-event-bus.ts";
 import { createTerminalStatusController, type TerminalStatusController } from "../ui/terminal-status.ts";
+import { extractPathFromInput, validateWrittenFile, buildValidationBlocker } from "../runtime/per-write-validator.ts";
 import { createRunSnapshotCache } from "../ui/run-snapshot-cache.ts";
 import { closeWatcher } from "../utils/fs-watch.ts";
 import { RunWatcherRegistry } from "../utils/run-watcher-registry.ts";
@@ -1986,6 +1987,27 @@ export function registerPiTeams(pi: ExtensionAPI): void {
 		};
 	});
 
+	// T5 (v0.8.5): per-write validation. On write/edit, run a zero-cost
+	// SYNCHRONOUS validator (v1: JSON.parse) and append a 🔴 blocker to the
+	// tool result on failure — catches malformed config the moment it's
+	// written, not at the next load. Latency-safe by construction: no process
+	// spawn, one disk read ONLY for validated extensions, dedup'd by content.
+	// Toggle via runtime.reliability.perWriteValidation (default true).
+	// Process-spawning validators (.js/.sh/.py) are a future opt-in.
+	pi.on("tool_result", (event, ctx) => {
+		try {
+			if (event.toolName !== "write" && event.toolName !== "edit") return;
+			if (loadConfig(ctx.cwd).config.reliability?.perWriteValidation === false) return;
+			const filePath = extractPathFromInput(event.input);
+			if (!filePath) return;
+			const result = validateWrittenFile(filePath);
+			if (!result || result.ok) return;
+			return { content: [...event.content, buildValidationBlocker(filePath, result.error ?? "validation failed")] };
+		} catch {
+			// best-effort: never break a tool result
+		}
+	});
+
 	registerTeamTool(pi, {
 		foregroundControllers,
 		startForegroundRun,

package/src/runtime/per-write-validator.ts

@@ -0,0 +1,183 @@
+/**
+ * Per-write validator — real-time feedback on file writes/edits (T5).
+ *
+ * Distilled from pi-lens (apmantza) — the "inline channel": on every
+ * `write`/`edit` tool result, run a CHEAP synchronous validator for the file
+ * type and, on failure, append a `🔴` blocker block to the tool result the
+ * agent sees next. This catches silent-breaking errors (malformed JSON
+ * config) at the moment they're introduced instead of at the next load.
+ *
+ * CRITICAL LATENCY-SAFETY DESIGN (the reason this is a careful slice, not the
+ * full pi-lens pipeline): pi-lens runs LSP servers + linters per write. That
+ * is expensive and would cause latency storms if naively ported (seconds of
+ * spawn per edit, firing in the main session AND every worker). This module's
+ * v1 deliberately ships ONLY zero-cost, zero-spawn, synchronous validators:
+ *
+ *   - `json` → `JSON.parse` (nanoseconds, built-in, no process spawn).
+ *
+ * The registry is extensible — future validators (`.js` → `node --check`,
+ * `.sh` → `bash -n`, `.py` → `py_compile`) are process-spawning and MUST be
+ * added behind an explicit opt-in (never default-on) to preserve the
+ * latency guarantee. A process-spawning validator would also need to be async
+ * and debounced (pi-lens's `inFlightPipelines` / debounce-window pattern),
+ * which the current sync contract intentionally avoids.
+ *
+ * Contract guarantees for v1:
+ *   - Synchronous. No `await`, no `spawn`, no disk write.
+ *   - One disk READ per validated file (after a cheap extension check, so
+ *     non-validated files cost nothing).
+ *   - Dedup by content: the same path+content is validated at most once per
+ *     process (a repeated identical write doesn't re-report).
+ *   - Silent on success; appends exactly one TextContent block on failure.
+ *   - Best-effort: any internal error is swallowed (never breaks a write).
+ *
+ * @module per-write-validator
+ */
+
+import { readFileSync } from "node:fs";
+import { extname as pathExtname } from "node:path";
+
+/** Outcome of validating a file's content. */
+export interface ValidationResult {
+	ok: boolean;
+	/** Human-readable error message when `ok` is false. */
+	error?: string;
+}
+
+/** A synchronous validator: content + path → result. */
+export type PerWriteValidator = (content: string, filePath: string) => ValidationResult;
+
+// ─────────────────────────────────────────────────────────────────────────
+// Validators (zero-cost, synchronous, dependency-free for v1)
+// ─────────────────────────────────────────────────────────────────────────
+
+/** JSON: parse with `JSON.parse`. Catches malformed config/manifests instantly. */
+export function validateJson(content: string, _filePath: string): ValidationResult {
+	if (content.trim() === "") return { ok: true }; // empty file is valid JSON absence, not a parse error
+	try {
+		JSON.parse(content);
+		return { ok: true };
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return { ok: false, error: `Invalid JSON: ${message}` };
+	}
+}
+
+/**
+ * Registry of default-on validators, keyed by extension (lowercase, no dot).
+ * ONLY zero-cost synchronous validators belong here. Process-spawning
+ * validators must be registered via a future opt-in path (see module doc).
+ */
+const DEFAULT_VALIDATORS: ReadonlyMap<string, PerWriteValidator> = new Map([
+	["json", validateJson],
+]);
+
+// ─────────────────────────────────────────────────────────────────────────
+// Dedup cache (path → last-validated content). Bounded; small.
+// ─────────────────────────────────────────────────────────────────────────
+
+const MAX_DEDUP_ENTRIES = 256;
+const seenContent = new Map<string, string>();
+
+function rememberSeen(path: string, content: string): void {
+	if (seenContent.has(path)) seenContent.delete(path); // refresh LRU position
+	seenContent.set(path, content);
+	while (seenContent.size > MAX_DEDUP_ENTRIES) {
+		const oldest = seenContent.keys().next().value;
+		if (oldest === undefined) break;
+		seenContent.delete(oldest);
+	}
+}
+
+/** Test seam: reset the dedup cache between tests. */
+export function resetPerWriteValidatorCache(): void {
+	seenContent.clear();
+}
+
+/**
+ * Replace the validator registry (test seam). Production uses
+ * DEFAULT_VALIDATORS; tests inject a custom map to exercise specific extensions.
+ */
+let validators: ReadonlyMap<string, PerWriteValidator> = DEFAULT_VALIDATORS;
+
+export function setPerWriteValidatorsForTest(map: ReadonlyMap<string, PerWriteValidator> | undefined): void {
+	validators = map ?? DEFAULT_VALIDATORS;
+}
+
+/**
+ * Normalise an extension to the registry key form (lowercase, no leading dot).
+ * "" for files with no extension.
+ */
+export function extensionKey(filePath: string): string {
+	return pathExtname(filePath).replace(/^\./, "").toLowerCase();
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Path extraction from a tool_result event input (defensive — pi-ai types
+// aren't exported here, so accept a record and probe common field names).
+// ─────────────────────────────────────────────────────────────────────────
+
+const PATH_FIELDS = ["filePath", "path", "file"] as const;
+
+/** Extract the written/edited path from a tool result input, if present. */
+export function extractPathFromInput(input: unknown): string | undefined {
+	if (!input || typeof input !== "object") return undefined;
+	const record = input as Record<string, unknown>;
+	for (const field of PATH_FIELDS) {
+		const value = record[field];
+		if (typeof value === "string" && value.length > 0) return value;
+	}
+	return undefined;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Core entry point
+// ─────────────────────────────────────────────────────────────────────────
+
+/**
+ * Validate a just-written/edited file. Returns `null` when there is nothing
+ * to report (no validator for the extension, dedup hit, file unreadable, or
+ * the content is valid). Returns a `ValidationResult` with `ok:false` when the
+ * content fails validation.
+ *
+ * Reads the file from disk (it's already written by `tool_result` time) so the
+ * logic is uniform across `write` (full content) and `edit` (patch). The disk
+ * read happens ONLY after a cheap extension check, so non-validated files cost
+ * nothing.
+ */
+export function validateWrittenFile(filePath: string): ValidationResult | null {
+	const key = extensionKey(filePath);
+	const validator = validators.get(key);
+	if (!validator) return null; // cheap skip: no validator for this file type
+	let content: string;
+	try {
+		content = readFileSync(filePath, "utf-8");
+	} catch {
+		// Unreadable / missing / permission denied — can't validate; never block.
+		return null;
+	}
+	// Dedup: identical content already validated this process → don't re-report.
+	if (seenContent.get(filePath) === content) return null;
+	rememberSeen(filePath, content);
+	const result = validator(content, filePath);
+	return result.ok ? null : result;
+}
+
+/**
+ * Build the TextContent block to append to a tool_result on validation failure.
+ * Uses a strong `🔴` prefix so the agent treats it as a real signal and fixes
+ * the file before continuing.
+ */
+export function buildValidationBlocker(filePath: string, error: string): { type: "text"; text: string } {
+	return {
+		type: "text",
+		text: [
+			"",
+			"🔴 pi-crew per-write check FAILED",
+			`   ${filePath}`,
+			`   ${error}`,
+			"   The file you just wrote is malformed. Fix it now — a broken file here will",
+			"   silently fail the next load/parse. Re-write the file with valid content before continuing.",
+		].join("\n"),
+	};
+}

package/src/ui/settings-overlay.ts

@@ -377,7 +377,7 @@ class AgentOverridesSubmenu {
 		this.onCancel = onCancel;
 		const existing = (config.agents as Record<string, unknown>)?.overrides as Record<string, { model?: string; thinking?: string }> | undefined;
 		this.overrides = existing ? structuredClone(existing) : {};
-		this.agents = ["explorer", "planner", "analyst", "critic", "executor", "reviewer", "security-reviewer", "test-engineer", "verifier", "writer"];
+		this.agents = ["explorer", "planner", "analyst", "critic", "executor", "reviewer", "security-reviewer", "test-engineer", "verifier", "cold-verifier", "writer"];
 	}
 
 	invalidate(): void {}