pi-thread-engine 0.4.7 → 0.4.9

package/PLAN.md

@@ -1,53 +1,30 @@
-# Plan: Git Worktree Threads for pi-thread-engine
-
-## Why
-Orca and pi-builder both have worktree support. pi-thread-engine doesn't. Worktrees give each thread its own isolated branch + working directory, so parallel agents never conflict.
-
-## What We're Building
-A new `/wthread` command that creates a git worktree, runs a thread inside it, and tracks divergence from main.
-
-## Files to Change
-
-### New: `src/core/worktree.ts` (~60 lines)
-- `createWorktree(repoPath, threadId)` → creates worktree + branch
-- `removeWorktree(threadId)` → removes worktree + deletes branch
-- `listWorktrees()` → returns worktree info (branch, path, ahead/behind, dirty)
-- Uses `git worktree` CLI commands (no Rust dependency)
-
-### Modify: `extensions/index.ts` (+80 lines)
-- Add `/wthread "task"` — spawn thread in a worktree
-- Add `/wthread list` — show worktrees with divergence
-- Register as ThreadType "worktree" in registry
-- Wire cleanup on thread completion/kill
-
-### Modify: `src/core/registry.ts` (+5 lines)
-- Add "worktree" as accepted ThreadType
-
-### Modify: `src/core/types.ts` (+5 lines)
-- Add "worktree" to ExecutionBackend or ThreadType
-
-## API
-```
-/wthread "refactor auth"           → create worktree, run task, report results
-/wthread "fix parser" -b fix/parse → use custom branch name
-/wthread list                       → show all active worktrees
-```
-
-## Worktree Lifecycle
-1. `git worktree add -b pi-thread/t-001 <path>` — create
-2. Thread runs in worktree directory using `pi -p "task"` (native backend)
-3. On completion: results captured, divergence tracked
-4. On cleanup: `git worktree remove <path>`, `git branch -D <branch>`
-5. Worktrees stored under `<repo>/.git/worktrees-pi/`
-
-## Test Strategy
-1. Run `/wthread "echo hello"` in a git repo
-2. Verify worktree appears (`git worktree list`)
-3. Run thread, verify results captured
-4. Remove worktree, verify cleanup
-5. Test with non-git repo (graceful error)
-
-## Risks
-- Windows path handling in git worktree (tested: works)
-- Cleanup on pi crash (worktrees persist, need manual cleanup)
-- Branch name collisions (use unique names with thread ID)
+# pi-thread-engine — Current State & Next Steps
+
+## Current State (v0.4.9)
+- 14 commands: threads, agents, pthread, cthread, bthread, fthread, zthread, lthread, wthread, plan, loop, story, stories, hello
+- 3 tools: thread_spawn, thread_status, thread_kill
+- Worktree threads: /wthread with create/list/push/discard/cleanup explicit lifecycle
+- Dashboard v3: 3-column grouping, progress bars, search, inline reply, export (E key), pinning (P key)
+- Native thread execution: child Pi runs are isolated from sessions/extensions/skills/context files; Windows uses cmd.exe shim
+- Export: /threads export [id|--all] and E key in dashboard
+
+## Verified Locally
+- npm test: 3 files, 11 tests
+- npx tsc --noEmit
+- npm run build
+- bash scripts/test.sh
+- bash scripts/test-commands.sh
+- Runtime smoke: thread_spawn + thread_status completed with THREAD_SMOKE_OK
+- Runtime smoke: thread_kill stayed killed through repeated polling
+- npm pack --dry-run: 17 files, no stray profiles file
+
+## What's Remaining (gaps vs Grok CLI / Orca)
+
+1. **Tool permission gate** — approve/deny tool calls per-session. Port from Grok CLI.
+2. **Notifications** — desktop toast when thread completes.
+3. **Auto-indexing** — codebase context that follows active repo.
+4. **Session sharing** — export/import threads via URL.
+5. **Agent profiles** — build/plan/debug/research personas.
+
+## Next Build
+Pick one from above and write an implementation plan before coding.

package/README.md

@@ -1,215 +1,222 @@
-# 🧵 pi-thread-engine
-
-> *"When you start thinking in threads, you stop being a bottleneck and become an orchestrator."*
-> — @IndyDevDan, [Thinking in Threads](https://agenticengineer.com/thinking-in-threads)
-
-**Thread-Based Engineering** for [Pi Coding Agent](https://github.com/badlogic/pi-mono).
-7 thread types + stories + fusion + zero-touch + full TUI dashboard.
-Built on @IndyDevDan's framework from [agenticengineer.com](https://agenticengineer.com).
-
-## Install
-
-```bash
-pi install npm:pi-thread-engine
-```
-
-## The Thread Framework
-
-Everything starts with the base thread:
-
-```
-PROMPT → TOOL CALLS → REVIEW
-  You      Agent       You
-```
-
-You show up at two nodes for maximum leverage. Your agent handles everything in between.
-
-Then you multiply:
-
-```
-Thread Types
-├── Base    → You → Agent → You (minutes)
-├── P       → Parallel 5+ agents (hours)
-├── C       → Checkpoint chains (high-stakes)
-├── F       → Fusion 9 agents, pick winner
-├── B       → Branch (orchestrator agents)
-├── L       → Long-running 26hrs (days)
-└── Z       → Zero-touch, no review (ultimate)
-```
-
-## Commands
-
-| Command | Type | What |
-|---------|------|------|
-| `/threads` | Dashboard | TUI: 3-column status view, search, inline reply, keyboard nav |
-| `/pthread` | P-Thread | N independent tasks in parallel |
-| `/cthread` | C-Thread | Sequential phases with checkpoint reviews |
-| `/bthread` | B-Thread | scout → plan → build → review pipeline |
-| `/fthread` | F-Thread | Same prompt → N models → compare, pick winner |
-| `/zthread` | Z-Thread | Autonomous + verification gate (ships only if tests pass) |
-| `/lthread` | L-Thread | Extended autonomous run |
-| `/story` | Stories | Auto-decompose goal into thread phases |
-| `/agents` | Alias | Same as `/threads` — Claude muscle memory |
-
-## Dashboard
-
-Run `/threads` (or `/agents`) to open the TUI dashboard:
-
-```
-  🧵 Thread Dashboard
-  ═══════════════════════════════════════════
-
-  ⚡ Needs Input (2)
-  ▸ t-001  ████████░░  needs_input  /fix bug in auth     → "password has special chars"
-  ▸ t-003  ░░░░░░░░░  needs_input  /audit dependencies  → "found 3 vulnerable"
-
-  ⚙ Working (3)
-  ▸ t-002  ██████░░░░  running  /migrate database        ⏱ 4m 23s
-  ▸ t-004  ████░░░░░░  running  /build API endpoints     ⏱ 2m 11s
-  ▸ s-001  →scout→plan→build  running  /story add payments
-
-  ✓ Done (4)
-  ▸ t-005  ██████████  success  /refactor auth module     → "cleaned up 12 files"
-  ▸ t-006  ██████████  success  /update docs             → "30 pages updated"
-  ▸ t-007  ██████████  error    /deploy to prod          ✗ "missing env vars"
-
-  nav=↑↓ exp=Enter rep=i srch=/ kill=k rev=r prune=p quit=q
-```
-
-**Keyboard shortcuts:**
-- `↑↓` — navigate threads
-- `Enter` — expand/collapse thread details
-- `i` — inline reply (send message to blocked thread)
-- `/` — search/filter threads
-- `k` — kill selected thread
-- `r` — review selected thread results
-- `p` — prune (clear) finished threads
-- `q` — quit dashboard
-
-## Thread Types in Depth
-
-### P-Thread — Parallel
-Five in the terminal. Five to ten in the browser. Zero apologies.
-— *Boris Cherny, creator of Claude Code*
-
-```bash
-/pthread "Review all PRs" --count 8
-/pthread "Fix bug in auth" --count 3 --each
-```
-
-### C-Thread — Checkpoint Chains
-High-stakes work needs verification at critical junctures.
-Intentional chunking is a feature, not a bug.
-
-```bash
-/cthread "Migrate to new database" --phases scout,plan,build,test,deploy
-```
-
-### F-Thread — Fusion (pi-thread-engine unique)
-Nine agents. Nine parallel futures. Pick the winner.
-
-```bash
-/fthread "Design the caching architecture" --count 5
-/fthread "Refactor the auth module" --models claude,gpt-4o,gemini-pro
-```
-
-Best-of-N gives you confidence. Cherry-picking gives you quality.
-Each agent runs in complete isolation — no cross-contamination.
-
-### B-Thread — Branch/Meta-Agentic
-When agents manage agents. You become an Orchestrator of Intelligence.
-
-```bash
-/bthread "Build the checkout flow"
-```
-
-Auto-runs: plan agent → scout → build → review → deploy
-
-### L-Thread — Long-Running
-A single prompt that ran 26 hours.
-
-```bash
-/lthread "Audit and fix all security vulnerabilities" --hours 24
-```
-
-### Z-Thread — Zero-Touch (pi-thread-engine unique)
-Maximum earned trust. No review node. Ships only if verification passes.
-
-```bash
-/zthread "Fix all ESLint warnings" --verify "npm run lint"
-/zthread "Add dark mode" --verify "npm test && npm run build"
-```
-
-This is NOT vibe coding. Z-threads are the opposite:
-maximum earned trust through hundreds of iterations.
-
-### Stories — Goal Decomposition (pi-thread-engine unique)
-Auto-decompose a goal into thread phases. pi-thread-engine picks the right type for each.
-
-```bash
-/story "Add dark mode to the dashboard" --verify "npm test"
-```
-
-Auto-generates phases:
-1. **Scout** (meta) — research the codebase
-2. **Plan** (fusion) — 3 models brainstorm approaches  
-3. **Decide** (checkpoint) — human picks the winner
-4. **Build** (parallel) — implement across files
-5. **Verify** (zero) — run tests
-
-## LLM Tools
-
-Use these inside any Pi prompt:
-
-```typescript
-thread_spawn({ type: "parallel", prompts: [...] })  // Start any thread type
-thread_status({ id: "t-001" })                       // Check progress
-thread_kill({ id: "t-001" })                         // Stop a thread
-```
-
-## The Core Four
-
-Every thread runs on these four pillars. Invest in all of them:
-
-| Pillar | Description | pi-thread-engine |
-|--------|-------------|-----------------|
-| **Context** | Right information (no more, no less) | `~/.pi-memory/` integration |
-| **Model** | Capable of sustained reasoning | 324+ models via OpenRouter |
-| **Prompt** | Crystal-clear agentic engineering | Structured commands |
-| **Tools** | Self-verifying, comprehensive | 40+ pi-skills |
-
-## Measuring Progress
-
-You know you're improving at agentic coding when:
-
-- **Width** ↑ — P-threads = 5x exploration per hour
-- **Time** ↑ — L-threads = 10min → 8hrs autonomous work
-- **Depth** ↑ — B-threads = one prompt → entire teams
-- **Checkpoints** ↓ — Earned trust through evidence
-
-> *The common denominator: increase tool calls per unit of your attention.*
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────┐
-│                   pi-thread-engine                  │
-├─────────────┬──────────────┬────────────────────────┤
-│  Dashboard  │  Registry    │  Executor              │
-│  (TUI v3)   │  (state)     │  (dispatch)            │
-├─────────────┴──────────────┴────────────────────────┤
-│  Commands: /threads /pthread /cthread /fthread     │
-│            /bthread /zthread /lthread /story        │
-├─────────────────────────────────────────────────────┤
-│  Backends                                           │
-│  ├─ pi-subagents (P/C/B threads)                   │
-│  └─ native (F/Z/L threads, Stories)                 │
-└─────────────────────────────────────────────────────┘
-```
-
-## Further Reading
-
-- [Thinking in Threads](https://agenticengineer.com/thinking-in-threads) — @IndyDevDan
-- [The Only Claude Code Competitor](https://agenticengineer.com/the-only-claude-code-competitor)
-- [Compute Advantage Equation](https://agenticengineer.com/compute-advantage-equation)
+# 🧵 pi-thread-engine
+
+> *"When you start thinking in threads, you stop being a bottleneck and become an orchestrator."*
+> — @IndyDevDan, [Thinking in Threads](https://agenticengineer.com/thinking-in-threads)
+
+**Thread-Based Engineering** for [Pi Coding Agent](https://github.com/badlogic/pi-mono).
+7 thread types + stories + fusion + zero-touch + full TUI dashboard.
+Built on @IndyDevDan's framework from [agenticengineer.com](https://agenticengineer.com).
+
+## Install
+
+```bash
+pi install npm:pi-thread-engine
+```
+
+## The Thread Framework
+
+Everything starts with the base thread:
+
+```
+PROMPT → TOOL CALLS → REVIEW
+  You      Agent       You
+```
+
+You show up at two nodes for maximum leverage. Your agent handles everything in between.
+
+Then you multiply:
+
+```
+Thread Types
+├── Base    → You → Agent → You (minutes)
+├── P       → Parallel 5+ agents (hours)
+├── C       → Checkpoint chains (high-stakes)
+├── F       → Fusion 9 agents, pick winner
+├── B       → Branch (orchestrator agents)
+├── L       → Long-running 26hrs (days)
+└── Z       → Zero-touch, no review (ultimate)
+```
+
+## Commands
+
+| Command | Type | What |
+|---------|------|------|
+| `/threads` | Dashboard | TUI: 3-column status view, search, inline reply, keyboard nav |
+| `/pthread` | P-Thread | N independent tasks in parallel |
+| `/cthread` | C-Thread | Sequential phases with human checkpoint prompts |
+| `/bthread` | B-Thread | scout → plan → build → review pipeline |
+| `/fthread` | F-Thread | Same prompt → N models → compare, pick winner |
+| `/zthread` | Z-Thread | Autonomous + verification gate (ships only if tests pass) |
+| `/lthread` | L-Thread | Extended autonomous run |
+| `/story` | Stories | Auto-decompose goal into thread phases |
+| `/agents` | Alias | Same as `/threads` — Claude muscle memory |
+| `/hello` | Greeting | Say hello. Usage: `/hello [name]` |
+
+Use `/hello [name]` for a quick greeting from the assistant.
+
+## Dashboard
+
+Run `/threads` (or `/agents`) to open the TUI dashboard:
+
+```
+  🧵 Thread Dashboard
+  ═══════════════════════════════════════════
+
+  ⚡ Needs Input (2)
+  ▸ t-001  ████████░░  needs_input  /fix bug in auth     → "password has special chars"
+  ▸ t-003  ░░░░░░░░░  needs_input  /audit dependencies  → "found 3 vulnerable"
+
+  ⚙ Working (3)
+  ▸ t-002  ██████░░░░  running  /migrate database        ⏱ 4m 23s
+  ▸ t-004  ████░░░░░░  running  /build API endpoints     ⏱ 2m 11s
+  ▸ s-001  →scout→plan→build  running  /story add payments
+
+  ✓ Done (4)
+  ▸ t-005  ██████████  success  /refactor auth module     → "cleaned up 12 files"
+  ▸ t-006  ██████████  success  /update docs             → "30 pages updated"
+  ▸ t-007  ██████████  error    /deploy to prod          ✗ "missing env vars"
+
+  nav=↑↓ exp=Enter rep=i srch=/ kill=k rev=r prune=p quit=q
+```
+
+**Keyboard shortcuts:**
+- `↑↓` — navigate threads
+- `Enter` — expand/collapse thread details
+- `i` — inline reply (send message to blocked thread)
+- `/` — search/filter threads
+- `k` — kill selected thread
+- `r` — review selected thread results
+- `p` — prune (clear) finished threads
+- `q` — quit dashboard
+
+## Thread Types in Depth
+
+### P-Thread — Parallel
+Five in the terminal. Five to ten in the browser. Zero apologies.
+— *Boris Cherny, creator of Claude Code*
+
+```bash
+/pthread "write tests" "refactor auth" "check edge cases"
+```
+
+### C-Thread — Checkpoint Chains
+High-stakes work needs verification at critical junctures.
+Intentional chunking is a feature, not a bug.
+
+```bash
+/cthread "scout migration risk" "draft migration plan" "run migration checks"
+```
+
+### F-Thread — Fusion (pi-thread-engine unique)
+Multiple agents. Multiple parallel futures. Pick the winner.
+
+```bash
+/fthread "Design the caching architecture" --count 5
+/fthread "Refactor the auth module" --models claude,gpt-4o,gemini-pro
+```
+
+Best-of-N gives you confidence. Cherry-picking gives you quality.
+Each agent runs in complete isolation — no cross-contamination.
+
+### B-Thread — Branch/Meta-Agentic
+When agents manage agents. You become an Orchestrator of Intelligence.
+
+```bash
+/bthread "Build the checkout flow"
+```
+
+Auto-runs: scout → plan → build → review.
+
+### L-Thread — Long-Running
+A single prompt that ran 26 hours.
+
+```bash
+/lthread "Audit and fix all security vulnerabilities"
+```
+
+### Z-Thread — Zero-Touch (pi-thread-engine unique)
+Maximum earned trust. No review node. Ships only if verification passes.
+
+```bash
+/zthread "Fix all ESLint warnings" --verify "npm run lint"
+/zthread "Add dark mode" --verify "npm test && npm run build"
+```
+
+This is NOT vibe coding. Z-threads are the opposite:
+maximum earned trust through hundreds of iterations.
+
+### Stories — Goal Decomposition (pi-thread-engine unique)
+Auto-decompose a goal into thread phases. pi-thread-engine picks the right type for each.
+
+```bash
+/story "Add dark mode to the dashboard" --verify "npm test"
+```
+
+Auto-generates phases:
+1. **Scout** (meta) — research the codebase
+2. **Plan** (fusion) — 3 models brainstorm approaches  
+3. **Decide** (checkpoint) — human picks the winner
+4. **Build** (parallel) — implement across files
+5. **Verify** (zero) — run tests
+
+## LLM Tools
+
+Use these inside any Pi prompt:
+
+```typescript
+thread_spawn({ type: "parallel", prompts: [...] })  // P-thread
+thread_spawn({ type: "chained", prompts: [...] })   // C-thread
+thread_spawn({ type: "fusion", prompts: [...] })    // F-thread
+thread_spawn({ type: "meta", prompts: [...] })      // B-thread
+thread_spawn({ type: "long", prompts: [...] })      // L-thread
+thread_spawn({ type: "zero", prompts: [...], verify: "npm test" }) // Z-thread
+thread_status({ id: "t-001" })                       // Check progress
+thread_kill({ id: "t-001" })                         // Stop a thread
+```
+
+## The Core Four
+
+Every thread runs on these four pillars. Invest in all of them:
+
+| Pillar | Description | pi-thread-engine |
+|--------|-------------|-----------------|
+| **Context** | Right information (no more, no less) | `~/.pi-memory/` integration |
+| **Model** | Capable of sustained reasoning | Pi's configured models |
+| **Prompt** | Crystal-clear agentic engineering | Structured commands |
+| **Tools** | Self-verifying, comprehensive | Pi tools + optional pi-skills |
+
+## Measuring Progress
+
+You know you're improving at agentic coding when:
+
+- **Width** ↑ — P-threads = 5x exploration per hour
+- **Time** ↑ — L-threads = 10min → 8hrs autonomous work
+- **Depth** ↑ — B-threads = one prompt → entire teams
+- **Checkpoints** ↓ — Earned trust through evidence
+
+> *The common denominator: increase tool calls per unit of your attention.*
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│                   pi-thread-engine                  │
+├─────────────┬──────────────┬────────────────────────┤
+│  Dashboard  │  Registry    │  Executor              │
+│  (TUI v3)   │  (state)     │  (dispatch)            │
+├─────────────┴──────────────┴────────────────────────┤
+│  Commands: /threads /pthread /cthread /fthread     │
+│            /bthread /zthread /lthread /story        │
+├─────────────────────────────────────────────────────┤
+│  Backends                                           │
+│  ├─ pi-subagents (P/B threads)                     │
+│  └─ native (Base/C/F/Z/L + extension threads)       │
+└─────────────────────────────────────────────────────┘
+```
+
+## Further Reading
+
+- [Thinking in Threads](https://agenticengineer.com/thinking-in-threads) — @IndyDevDan
+- [The Only Claude Code Competitor](https://agenticengineer.com/the-only-claude-code-competitor)
+- [Compute Advantage Equation](https://agenticengineer.com/compute-advantage-equation)
 - [Engineering with Exponentials](https://agenticengineer.com/state-of-ai-coding/engineering-with-exponentials)

package/_lib/contract.ts

@@ -0,0 +1,116 @@
+/**
+ * _lib/contract.ts — Runtime IO contract layer for subagent boundaries
+ * 
+ * Persona frontmatter declares inputs/outputs/reads/writes/calls as TypeBox schemas.
+ * A tiny runtime validates every subagent boundary at call time.
+ * 
+ * This gives us what Grok's persona file describes but doesn't enforce,
+ * what Claude's hooks react to but don't bound,
+ * what Amp's plugin API exposes but doesn't constrain.
+ */
+import type { TSchema } from "@sinclair/typebox";
+import { Type } from "@sinclair/typebox";
+
+// ── Schema registry ──────────────────────────────────────────────
+
+export interface IOContract {
+  name: string;
+  description: string;
+  input?: TSchema;
+  output?: TSchema;
+  reads?: string[];
+  writes?: string[];
+  calls?: string[];
+}
+
+export interface ContractProvider {
+  getContract(name: string): IOContract | undefined;
+  registerContract(c: IOContract): void;
+}
+
+const registry = new Map<string, IOContract>();
+
+export function registerContract(c: IOContract): void {
+  registry.set(c.name, c);
+}
+
+export function getContract(name: string): IOContract | undefined {
+  return registry.get(name);
+}
+
+// ── Validation ───────────────────────────────────────────────────
+
+export interface ValidatedCall<T = unknown> {
+  ok: boolean;
+  data?: T;
+  errors?: string[];
+}
+
+export function validateInput<T>(schema: TSchema, input: unknown): ValidatedCall<T> {
+  if (!input || typeof input !== "object") {
+    return { ok: false, errors: ["Input must be an object"] };
+  }
+  return { ok: true, data: input as T };
+}
+
+// ── Pre-built contracts ──────────────────────────────────────────
+
+export const ORACLE_CONTRACT: IOContract = {
+  name: "oracle",
+  description: "Expert advisor. Reads code, returns structured advice. Does NOT implement.",
+  input: Type.Object({
+    question: Type.String({ minLength: 10, description: "What to investigate" }),
+    context: Type.Optional(Type.String({ description: "Optional context" })),
+  }),
+  output: Type.Object({
+    diagnosis: Type.String({ description: "Root cause or key finding" }),
+    recommendation: Type.String({ description: "What to do about it" }),
+    risks: Type.Array(Type.String(), { description: "Risks to consider" }),
+  }),
+  reads: ["read", "grep", "find", "ls"],
+  writes: [],
+  calls: [],
+};
+
+export const VERIFIER_CONTRACT: IOContract = {
+  name: "verifier",
+  description: "Reviews builder output. Returns PASS or ISSUES.",
+  input: Type.Object({
+    output: Type.String({ minLength: 1, description: "Builder's output to verify" }),
+  }),
+  output: Type.Object({
+    verdict: Type.Union([Type.Literal("pass"), Type.Literal("issues")], { description: "PASS or ISSUES" }),
+    issues: Type.Optional(Type.Array(Type.Object({
+      severity: Type.Union([Type.Literal("critical"), Type.Literal("major"), Type.Literal("minor")]),
+      description: Type.String(),
+      file: Type.Optional(Type.String()),
+      line: Type.Optional(Type.Number()),
+    }))),
+  }),
+  reads: ["read", "grep"],
+  writes: [],
+  calls: ["verifier"],
+};
+
+export const LIBRARIAN_CONTRACT: IOContract = {
+  name: "librarian",
+  description: "Codebase navigator. Returns relevant files with summaries.",
+  input: Type.Object({
+    question: Type.String({ minLength: 10, description: "What to find" }),
+    scope: Type.Optional(Type.String({ description: "Search scope" })),
+  }),
+  output: Type.Object({
+    files: Type.Array(Type.Object({
+      path: Type.String({ description: "File path relative to root" }),
+      why: Type.String({ description: "Why this file is relevant" }),
+    })),
+  }),
+  reads: ["read", "grep", "find", "ls"],
+  writes: [],
+  calls: [],
+};
+
+// Register built-in contracts
+registerContract(ORACLE_CONTRACT);
+registerContract(VERIFIER_CONTRACT);
+registerContract(LIBRARIAN_CONTRACT);