pi-crew 0.11.0 → 0.11.2

package/docs/runtime-flow.md

@@ -1,148 +0,0 @@
-# pi-crew Runtime Flow
-
-This document is a compact map of the runtime paths used by `pi-crew`.
-
-## Main sequence
-
-```text
-User / model
-  │ calls team({ action: "run", ... }) or /team-run
-  ▼
-handleTeamTool()
-  │ validates schema and routes action
-  ▼
-handleRun()
-  ├─ discoverTeams/discoverWorkflows/discoverAgents
-  ├─ validateWorkflowForTeam
-  ├─ expandParallelResearchWorkflow when applicable
-  ├─ createRunManifest + tasks.json + goal artifact
-  ├─ if async=true ─────────────────────────────────────────────┐
-  │   spawnBackgroundTeamRun()                                  │
-  │     ├─ resolve jiti-register.mjs                            │
-  │     ├─ fail-fast if jiti missing                            │
-  │     ├─ node --import jiti-register.mjs background-runner.ts  │
-  │     └─ parent schedules early-exit guard                    │
-  │                                                            ▼
-  │   background-runner.ts
-  │     ├─ append async.started
-  │     ├─ write async.pid startup marker
-  │     ├─ rediscover team/workflow/agents
-  │     └─ executeTeamRun()
-  │
-  └─ if foreground/default
-      ├─ startForegroundRun schedules session-bound run, or
-      └─ executeTeamRun inline for scaffold/non-scheduled paths
-
-executeTeamRun()
-  ├─ write run.running
-  ├─ materialize queued/running agent records lazily
-  ├─ build task graph index
-  ├─ while queued tasks exist
-  │   ├─ taskGraphSnapshot
-  │   ├─ resolveBatchConcurrency
-  │   ├─ getReadyTasks
-  │   ├─ append task.progress batch event
-  │   ├─ mapConcurrent ready batch
-  │   │   └─ runTeamTask()
-  │   │       ├─ prepare workspace/worktree
-  │   │       ├─ build task packet
-  │   │       ├─ render prompt + dependency context
-  │   │       ├─ choose model candidates from Pi config
-  │   │       ├─ spawn child Pi process
-  │   │       ├─ ChildPiLineObserver parses stdout/stderr
-  │   │       ├─ append per-agent events/output
-  │   │       ├─ update agent progress/task state
-  │   │       ├─ parse final JSONL/session usage
-  │   │       └─ write result/log/transcript/metadata artifacts
-  │   ├─ merge task updates monotonically
-  │   ├─ optional adaptive plan injection
-  │   ├─ save tasks/agents/progress
-  │   └─ write batch artifact
-  ├─ policy closeout
-  └─ run.completed / run.failed / run.blocked / run.cancelled
-```
-
-## Action router
-
-| Action | Handler | Purpose |
-|---|---|---|
-| `run` | `team-tool/run.ts` | Create and execute a run, foreground or async. |
-| `status` | `team-tool.ts` | Show manifest/tasks/agents/events and mark stale async runs failed. |
-| `summary` | `session-summary.ts`/summary handler | Write/read run summary artifact. |
-| `events` | `team-tool.ts` | Tail durable run events. |
-| `artifacts` | `team-tool.ts` | List run artifacts. |
-| `resume` | `team-tool.ts` | Requeue failed/cancelled/skipped/running tasks. |
-| `cancel` | `team-tool.ts` | Mark queued/running tasks cancelled and request foreground interrupt. |
-| `forget` | `run-maintenance.ts` | Delete run state/artifacts with confirmation. |
-| `prune` | `run-maintenance.ts` | Remove old finished runs with confirmation. |
-| `export` | `run-export.ts` | Create portable run bundle. |
-| `import` / `imports` | `run-import.ts` / `import-index.ts` | Store/list imported bundles. |
-| `config` | `config.ts` + config action | Show/update user/project config. |
-| `doctor` | `team-tool/doctor.ts` | Platform/resource/runtime diagnostics. |
-| `validate` | `validate-resources.ts` | Validate agents/teams/workflows. |
-| `recommend` | `team-recommendation.ts` | Suggest team/workflow/action for a goal. |
-| management | `management.ts` | Create/update/delete/rename teams, agents, workflows. |
-| API | `team-tool/api.ts` | File-backed observability/control/mailbox API. |
-
-## Worker modes
-
-| Mode | Behavior |
-|---|---|
-| `child-process` | Default. Launches real child `pi` processes per task. |
-| `scaffold` | Explicit dry-run. No child Pi worker execution. |
-| `live-session` | Experimental/gated in-process/live agent path. |
-| `auto` | Resolves to child-process unless config/env requests otherwise. |
-
-## Important files
-
-```text
-src/extension/register.ts              Pi extension entry/wiring
-src/extension/team-tool/run.ts         run creation and foreground/async split
-src/runtime/background-runner.ts       detached async entrypoint
-src/runtime/async-runner.ts            background spawn command/options
-src/runtime/team-runner.ts             workflow/task graph scheduler
-src/runtime/task-runner.ts             single task execution
-src/runtime/child-pi.ts                child Pi process and output observer
-src/runtime/model-fallback.ts          configured model candidates/routing
-src/runtime/concurrency.ts             batch concurrency decisions
-src/runtime/process-status.ts          pid/liveness/stale detection
-src/state/state-store.ts               manifest/tasks persistence
-src/state/event-log.ts                 JSONL run events
-src/runtime/crew-agent-records.ts      aggregate + per-agent status files
-```
-
-## Environment variables
-
-| Env | Effect |
-|---|---|
-| `PI_CREW_EXECUTE_WORKERS=0` | Disable real workers, use scaffold behavior. |
-| `PI_TEAMS_EXECUTE_WORKERS=0` | Legacy alias for worker disable. |
-| `PI_CREW_ENABLE_EXPERIMENTAL_LIVE_SESSION=1` | Allow experimental live-session runtime. |
-| `PI_CREW_MOCK_LIVE_SESSION=success` | Test hook for live-session mock. |
-| `PI_TEAMS_MOCK_CHILD_PI` | Test hook for mocked child Pi execution. |
-| `PI_CREW_DEPTH`, `PI_CREW_MAX_DEPTH` | Canonical subagent recursion guard. |
-| `PI_TEAMS_DEPTH`, `PI_TEAMS_MAX_DEPTH` | Legacy recursion guard aliases. |
-| `PI_TEAMS_HOME` | Override user config/state home in tests. |
-| `PI_TEAMS_PI_BIN` | Override child `pi` executable. |
-| `PI_CODING_AGENT_DIR` | Override Pi settings/models directory for model discovery. |
-| `PI_CREW_ASYNC_EARLY_EXIT_GUARD=0` | Disable 3s background early-exit guard. |
-
-## State transition summary
-
-```text
-queued/planning/running  ── completed
-                         ├─ failed
-                         ├─ blocked
-                         └─ cancelled
-```
-
-Task states follow the same durable contract plus `skipped`. Terminal states are monotonic during parallel merge.
-
-## Observability tips
-
-- Use `/team-dashboard` for a UI overview.
-- Use `team status runId=...` for canonical state and stale async detection.
-- Read `background.log` for early import/spawn errors.
-- Read `events.jsonl` for event chronology.
-- Read `agents/{taskId}/status.json` for per-agent model/progress/tool status.
-- Read `artifacts/{runId}/transcripts/{taskId}.jsonl` for raw child Pi transcript.

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

@@ -1,22 +0,0 @@
-/**
- * Capacity-stage helpers (shared by renderCapacity, which remains exported
- * for its unit tests after the footer retirement).
- *
- * The speed-UI parts of this module (braille/PUA spinner frames,
- * intervalForSpeed) were REMOVED with the tok/s speed UI (maintainer
- * decision 2026-09-14) — pi's built-in working indicator is always used.
- */
-
-/**
- * Pick the capacity stage index (0..levels-1) for a context-fill percent.
- * Ported from pi-chonk's chonkIndex.
- */
-export function capacityIndex(percent: number | null | undefined, levels = 6): number {
-	if (percent === null || percent === undefined || !Number.isFinite(percent)) return 0;
-	return Math.max(0, Math.min(levels - 1, Math.floor((Math.max(0, Math.min(100, percent)) / 100) * levels)));
-}
-
-/** The last two stages are "danger" stages and get the error color. */
-export function isDangerStage(index: number, levels: number): boolean {
-	return index >= Math.max(0, levels - 2);
-}

package/src/extension/crew-vibes/font-detect.ts

@@ -1,71 +0,0 @@
-import { existsSync, readFileSync } from "node:fs";
-import { homedir, platform } from "node:os";
-import { join } from "node:path";
-
-/**
- * Detect whether the crew-vibes PUA font (U+E700..U+E70F) file exists
- * on disk.  This is a *best-effort* heuristic — file existence does NOT
- * guarantee the terminal can render PUA glyphs (many terminals have their
- * own font stacks).  For reliable animation, braille fallback frames are
- * used by default; PUA frames are only activated when the user explicitly
- * (used by the capacity icons).
- */
-
-function fontPath(): string {
-	const os = platform();
-	const home = homedir();
-	if (os === "darwin") return join(home, "Library", "Fonts", "crew-vibes.ttf");
-	if (os === "linux") return join(home, ".local", "share", "fonts", "crew-vibes.ttf");
-	if (os === "win32") {
-		const local = process.env.LOCALAPPDATA ?? join(home, "AppData", "Local");
-		return join(local, "Microsoft", "Windows", "Fonts", "crew-vibes.ttf");
-	}
-	return "";
-}
-
-let _hasFontFile: boolean | null = null;
-
-/** Returns true when crew-vibes.ttf exists in the platform font directory. */
-export function hasCrewFontFile(): boolean {
-	if (_hasFontFile !== null) return _hasFontFile;
-	const p = fontPath();
-	_hasFontFile = p !== "" && existsSync(p);
-	return _hasFontFile;
-}
-
-let _isWebTerminal: boolean | null = null;
-
-/** Returns true when running in a web-based terminal (gotty, wetty, etc.)
- * where system fonts are not available for PUA rendering. */
-export function isWebTerminal(): boolean {
-	if (_isWebTerminal !== null) return _isWebTerminal;
-	if (process.env.GOTTY || process.env.WEBTERM) {
-		_isWebTerminal = true;
-		return true;
-	}
-	if (process.env.TERM === "dumb") {
-		_isWebTerminal = true;
-		return true;
-	}
-	try {
-		// Check current process and ancestors — gotty is often the grandparent
-		// (gotty → tmux → pi), so /proc/self/cgroup may not contain it.
-		let pid = process.pid;
-		for (let i = 0; i < 6 && pid > 1; i++) {
-			const cgroup = readFileSync(`/proc/${pid}/cgroup`, "utf8");
-			if (cgroup.includes("gotty") || cgroup.includes("wetty")) {
-				_isWebTerminal = true;
-				return true;
-			}
-			const match = cgroup.match(/\d+:.*:(.*)/);
-			// Read PPid from status
-			const status = readFileSync(`/proc/${pid}/status`, "utf8");
-			const ppid = status.match(/^PPid:\s+(\d+)/m);
-			pid = ppid ? Number.parseInt(ppid[1], 10) : 1;
-		}
-	} catch {
-		// not Linux or /proc not available
-	}
-	_isWebTerminal = false;
-	return false;
-}

package/src/ui/dynamic-border.ts

@@ -1,35 +0,0 @@
-import type { CrewTheme } from "./theme-adapter.ts";
-
-export interface DynamicCrewBorderOptions {
-	color?: (value: string) => string;
-	char?: string;
-}
-
-export class DynamicCrewBorder {
-	private readonly theme: CrewTheme;
-	private readonly color?: (value: string) => string;
-	private readonly char: string;
-	private cachedWidth = -1;
-	private cachedLine = "";
-
-	constructor(theme: CrewTheme, options: DynamicCrewBorderOptions = {}) {
-		this.theme = theme;
-		this.color = options.color;
-		this.char = options.char && options.char.length > 0 ? options.char : "─";
-	}
-
-	render(width: number): string[] {
-		const w = Math.max(0, width);
-		if (w !== this.cachedWidth) {
-			const line = this.char.repeat(w);
-			this.cachedLine = this.color ? this.color(line) : this.theme.fg("border", line);
-			this.cachedWidth = w;
-		}
-		return [this.cachedLine];
-	}
-
-	invalidate(): void {
-		this.cachedWidth = -1;
-		this.cachedLine = "";
-	}
-}

package/src/ui/loaders.ts

@@ -1,6 +0,0 @@
-/**
- * CrewBorderedLoader and CountdownTimer were removed (UI-animation-audit C9).
- * They were dead production code — referenced only by test/unit/loaders.test.ts
- * (now deleted) and never instantiated in src/ or re-exported from the public
- * index.  If a new loader component is needed, add it here.
- */

package/src/ui/overlay-stack.ts

@@ -1,148 +0,0 @@
-/**
- * PR-G3 (UI-4) — minimal overlay stack for z-order, focus, and dismissal
- * chaining.
- *
- * Before this, src/ui/ had no central router for overlay z-order/focus/
- * dismissal. Overlays (ConfirmOverlay, MailboxDetailOverlay, AgentPickerOverlay,
- * HelpOverlay, …) each manage their own `handleInput`, and a caller that wants
- * two overlays up at once had no way to express "the top one gets input and
- * ESC dismisses it, restoring focus to the one below".
- *
- * The `OverlayStack` is a LIFO stack of overlays. The top of the stack owns
- * input focus and is rendered last (i.e. on top). Popping or dismissing the
- * top restores focus to the next overlay down. Every overlay already exposes
- * the `InteractiveComponent` contract (render + invalidate + handleInput), so
- * existing overlays opt in automatically with zero rewrite.
- *
- * This is intentionally additive: no existing overlay is required to use it.
- * Callers that want centralized z-order/focus management opt in by pushing
- * overlays here.
- */
-
-import type { InteractiveComponent } from "./component.ts";
-
-/**
- * An overlay is an interactive component occupying one z-layer. Anything with
- * `render` + `invalidate` + `handleInput` qualifies (ConfirmOverlay,
- * MailboxDetailOverlay, AgentPickerOverlay, RunDashboard, …).
- */
-export type Overlay = InteractiveComponent;
-
-export interface OverlayStackOptions {
-	/**
-	 * Invoked after the top-of-stack changes (push / pop / dismissTop / clear).
-	 * Use it to (re)wire host focus or request a repaint. Optional.
-	 */
-	onTopChanged?: () => void;
-}
-
-/**
- * LIFO overlay stack providing z-order, focus, and dismissal chaining.
- *
- * - `push(o)`  → `o` becomes the new focus/top layer.
- * - `top()`    → the focused overlay (or undefined when empty).
- * - `handleInput(data)` → routed to the top overlay only; returns false when
- *   the stack is empty so callers can fall back to base input handling.
- * - `dismissTop()` / `pop()` → removes the top overlay, restoring focus below.
- * - `render(width)` → renders the top overlay by default; `{ composite: true }`
- *   returns every layer bottom-to-top for custom compositing.
- */
-export class OverlayStack {
-	private readonly stack: Overlay[] = [];
-	private readonly onTopChanged?: () => void;
-
-	constructor(options: OverlayStackOptions = {}) {
-		this.onTopChanged = options.onTopChanged;
-	}
-
-	/** Number of overlays currently on the stack. */
-	get size(): number {
-		return this.stack.length;
-	}
-
-	/** Whether the stack currently holds any overlays. */
-	isEmpty(): boolean {
-		return this.stack.length === 0;
-	}
-
-	/** Push a new overlay on top. It becomes the input/render focus. */
-	push(overlay: Overlay): void {
-		this.stack.push(overlay);
-		this.notifyTopChanged();
-	}
-
-	/** Remove and return the top overlay, or undefined if the stack is empty. */
-	pop(): Overlay | undefined {
-		const overlay = this.stack.pop();
-		this.notifyTopChanged();
-		return overlay;
-	}
-
-	/** The top-of-stack overlay (the focus/render target), or undefined when empty. */
-	top(): Overlay | undefined {
-		return this.stack.at(-1);
-	}
-
-	/** Peek at the overlay at a given depth (0 = bottom). */
-	at(index: number): Overlay | undefined {
-		return this.stack[index];
-	}
-
-	/**
-	 * Dismiss the top overlay. Equivalent to `pop()` but returns a boolean so
-	 * callers can chain dismissal (e.g. ESC closes the topmost, then the next).
-	 * Returns true when an overlay was dismissed, false when the stack is empty.
-	 */
-	dismissTop(): boolean {
-		if (this.stack.length === 0) return false;
-		this.stack.pop();
-		this.notifyTopChanged();
-		return true;
-	}
-
-	/**
-	 * Route a raw input chunk to the top-of-stack overlay.
-	 * @returns true if an overlay handled it (stack non-empty); false if the
-	 *   stack is empty so the caller may fall back to base input handling.
-	 */
-	handleInput(data: string): boolean {
-		const overlay = this.top();
-		if (!overlay) return false;
-		overlay.handleInput(data);
-		return true;
-	}
-
-	/**
-	 * Render the stack. By default returns the top overlay's lines (the common
-	 * modal case where the top covers what is below). Pass `{ composite: true }`
-	 * to receive every layer's lines in bottom-to-top order for custom
-	 * compositing. Returns `[]` when the stack is empty.
-	 */
-	render(width: number, options: { composite?: boolean } = {}): string[] {
-		if (this.stack.length === 0) return [];
-		if (options.composite) {
-			const lines: string[] = [];
-			for (const overlay of this.stack) {
-				lines.push(...overlay.render(width));
-			}
-			return lines;
-		}
-		return this.stack.at(-1)!.render(width);
-	}
-
-	/** Invalidate every overlay on the stack (e.g. on theme change). */
-	invalidateAll(): void {
-		for (const overlay of this.stack) overlay.invalidate();
-	}
-
-	/** Remove every overlay from the stack. */
-	clear(): void {
-		const hadOverlays = this.stack.length > 0;
-		this.stack.length = 0;
-		if (hadOverlays) this.notifyTopChanged();
-	}
-
-	private notifyTopChanged(): void {
-		this.onTopChanged?.();
-	}
-}