pi-crew 0.9.50 → 0.9.52

package/docs/followup-review-2026-05-12.md

@@ -1,297 +0,0 @@
-# Follow-up Review — pi-crew (2026-05-12, round 2)
-
-Author: Droid (Factory) | Related: `docs/followup-plan-2026-05-12.md`, commit `926e6ee`.
-
-Review after commit `926e6ee` applied the B1–B9 + A1–A2 fixes from `followup-plan-2026-05-12.md`.
-
-## Result summary
-
-- `npm run typecheck` → Passed
-- `npm run test:unit` → **1411 tests / 1408 pass / 0 fail / 3 skip** (previously: 1389/1400 with 8 bash-on-Windows failures)
-- `npm run check:lazy-imports` → **FAILS on Windows** (details below)
-
-## Per-item status
-
-| # | Item | Status | Notes |
-|---|---|---|---|
-| B1 | bash portability | ✅ Done | `resolveShellForScript` + `resolveBashCmd` in `src/utils/resolve-shell.ts`. Applied to `post-checks.ts` + `iteration-hooks.ts`. The 8 previously failing tests pass. |
-| B2 | `worktree-manager.test.ts` | ⚠️ Partial | Has 3 tests (branch recovery, reuse, clean leader). Missing the `linkNodeModulesIfPresent` reject-file test. |
-| B3 | `artifact-store.test.ts` | ✅ Done | Hash integrity + path traversal + nested dirs. |
-| B4 | lock parity test | ✅ Done | 2 new tests: stale recovery sync+async, active lock throws. |
-| B5 | setup-hook env filter | ⚠️ Partial | `sanitizeEnvSecrets` applied. Uses a deny-list `SECRET_KEY_PATTERN` instead of the allow-list proposed in the plan. |
-| B6 | worktree checked-out hint | ✅ Done | try/catch + actionable error message. |
-| B7 | LAZY marker | ✅ Done | Marker at `team-tool.ts:58`. |
-| B8 | redaction roundtrip | ✅ Done | 3 tests (api_key, bearer, on-disk). |
-| B9 | CI grep-check | ❌ Broken on Windows | Script uses `sed`, fails on Windows. |
-| A1 | branchExists remote-tracking | ✅ Done | Returns `{ local, remoteOnly }`. |
-| A2 | jiti fallback robust | ✅ Done | 3 candidates: `lib/jiti-register.mjs`, `register.mjs`, `dist/register.mjs`. |
-| A3 | test alias cleanup | ⏭️ Skipped | Plan noted "not urgent". |
-
----
-
-## Issues to address next
-
-### C1 — (Medium, ~10 minutes) `scripts/check-lazy-imports.mjs` doesn't run on Windows
-
-**File:** `scripts/check-lazy-imports.mjs`
-
-**Problem:**
-- The script uses `execSync("sed -n '...' ...")` to read the preceding line → `sed` isn't available on Windows by default.
-- When sed fails, every line falls into the `catch` block → `bad.push(line)` → 13 false positives.
-- `npm run ci` will always fail on a Windows dev machine.
-
-**Proposed fix:** use plain Node instead of sed.
-
-```js
-import { execSync } from "node:child_process";
-import { readFileSync } from "node:fs";
-
-const out = execSync(`git grep -nE "await import\\(" -- "src/**/*.ts"`, { encoding: "utf-8" });
-const bad = [];
-const fileCache = new Map();
-
-for (const line of out.split("\n").filter(Boolean)) {
-	if (line.includes("// LAZY:")) continue;
-	const m = line.match(/^([^:]+):(\d+):/);
-	if (!m) continue;
-	const [, file, lineNum] = m;
-	if (!fileCache.has(file)) fileCache.set(file, readFileSync(file, "utf-8").split(/\r?\n/));
-	const lines = fileCache.get(file);
-	const prevLine = lines[Number(lineNum) - 2] ?? "";
-	if (!prevLine.includes("// LAZY:")) bad.push(line);
-}
-
-if (bad.length) {
-	console.error("Dynamic imports without `// LAZY:` marker:\n" + bad.join("\n"));
-	process.exit(1);
-}
-console.log("All dynamic imports have `// LAZY:` marker.");
-```
-
-**Test:** run `npm run check:lazy-imports` on both Linux and Windows → both should print "All dynamic imports have `// LAZY:` marker."
-
----
-
-### C2 — (Medium, ~20 minutes) `sanitizeEnvSecrets` uses a deny-list, not meeting the defense-in-depth goal of plan B5
-
-**File:** `src/utils/env-filter.ts`
-
-**Current state:**
-```ts
-export function sanitizeEnvSecrets(env: NodeJS.ProcessEnv): Record<string, string> {
-	const filtered: Record<string, string> = {};
-	for (const [key, value] of Object.entries(env)) {
-		if (value !== undefined && !SECRET_KEY_PATTERN.test(key)) filtered[key] = value;
-	}
-	return filtered;
-}
-```
-
-**Problem:**
-- The deny-list only blocks keys matching `SECRET_KEY_PATTERN`. Variables whose names don't match (e.g. `DB_PASS`, `MY_KEY_FOO`, `INTERNAL_TOKEN_LEGACY`) will leak into the setup hook.
-- The original plan B5 proposed an allow-list `["PATH", "HOME", "USERPROFILE", "TEMP", "TMP", "LANG", "PI_*"]` → much safer for user-provided hooks.
-
-**Proposed fix:** add an overload with an allow-list, keeping the deny-list as the default for `buildChildPiSpawnOptions` (backward-compat).
-
-```ts
-export interface SanitizeOptions {
-	allowList?: string[];   // glob-like, supports trailing * (e.g. "PI_*")
-}
-
-export function sanitizeEnvSecrets(env: NodeJS.ProcessEnv, options?: SanitizeOptions): Record<string, string> {
-	const filtered: Record<string, string> = {};
-	if (options?.allowList && options.allowList.length > 0) {
-		const matchers = options.allowList.map((p) => {
-			if (p.endsWith("*")) return (k: string) => k.startsWith(p.slice(0, -1));
-			return (k: string) => k === p;
-		});
-		for (const [key, value] of Object.entries(env)) {
-			if (value !== undefined && matchers.some((fn) => fn(key))) filtered[key] = value;
-		}
-		return filtered;
-	}
-	for (const [key, value] of Object.entries(env)) {
-		if (value !== undefined && !SECRET_KEY_PATTERN.test(key)) filtered[key] = value;
-	}
-	return filtered;
-}
-```
-
-**Apply at `worktree-manager.ts:runSetupHook`:**
-
-```ts
-env: sanitizeEnvSecrets(process.env, {
-	allowList: ["PATH", "HOME", "USERPROFILE", "TEMP", "TMP", "TMPDIR", "LANG", "LC_ALL", "PI_*"],
-}),
-```
-
-**Tests to add:** `test/unit/env-filter.test.ts`:
-- Allow-list pass-through for matching keys + reject the rest.
-- Glob `PI_*` matches `PI_HOME`, `PI_CREW_X` but not `PIPELINE`.
-- Default deny-list keeps old behavior.
-
----
-
-### C3 — (Low, ~10 minutes) `resolveShellForScript` doesn't handle `.cmd/.bat` correctly on Windows
-
-**File:** `src/utils/resolve-shell.ts`
-
-**Current state:**
-```ts
-if (scriptPath.endsWith(".cmd") || scriptPath.endsWith(".bat")) {
-	return { command: scriptPath, args: [] };
-}
-```
-
-**Problem:**
-- Node ≥ 20 blocks spawning `.bat/.cmd` directly without `shell: true` (CVE-2024-27980). The `execFileSync/spawn` code path will throw `EINVAL` or `ENOENT`.
-- Consequence: post-check / iteration-hook written as `.cmd/.bat` will fail silently on Node 20+.
-
-**Proposed fix:**
-```ts
-if (scriptPath.endsWith(".cmd") || scriptPath.endsWith(".bat")) {
-	return { command: process.env.ComSpec ?? "cmd.exe", args: ["/d", "/s", "/c", scriptPath] };
-}
-```
-
-**Tests to add:** in `test/unit/resolve-shell.test.ts` (create new):
-- Linux: `.sh` → `{ bash, [path] }`.
-- Windows + `.ps1` → `{ powershell, ["-File", path] }`.
-- Windows + `.cmd` → `{ cmd.exe, ["/d", "/s", "/c", path] }`.
-
----
-
-### C4 — (Low, ~15 minutes) Missing test for `linkNodeModulesIfPresent` rejecting a file source (BUG-006 regression guard)
-
-**File:** `test/unit/worktree-manager.test.ts`
-
-**Problem:**
-- Plan B2 required this test but the commit didn't add it. If someone modifies `linkNodeModulesIfPresent` and removes the `isDirectory()` check, BUG-006 will regress without a test catching it.
-
-**Proposed fix:** add one test (assuming `linkNodeModulesIfPresent` is exported or tested indirectly via `prepareTaskWorkspace` with `worktree.linkNodeModules=true`):
-
-```ts
-test("prepareTaskWorkspace skips linkNodeModules when source is a file", () => {
-	const repo = fs.mkdtempSync(path.join(os.tmpdir(), "pi-crew-wt-fn-"));
-	initGitRepo(repo);
-	// Place a FILE at node_modules instead of a directory
-	fs.writeFileSync(path.join(repo, "node_modules"), "not a dir", "utf-8");
-	// Write project config to enable linkNodeModules
-	const cfgDir = path.join(repo, ".crew");
-	fs.mkdirSync(cfgDir, { recursive: true });
-	fs.writeFileSync(path.join(cfgDir, "config.json"), JSON.stringify({
-		worktree: { linkNodeModules: true },
-	}), "utf-8");
-	const manifest = minimalManifest(repo, "run-fn");
-	const task = minimalTask("task-fn", repo);
-	const result = prepareTaskWorkspace(manifest, task);
-	assert.equal(result.nodeModulesLinked, false);
-	fs.rmSync(repo, { recursive: true, force: true });
-});
-```
-
----
-
-### C5 — (Low, ~5 minutes) `prepareTaskWorkspace` error message affected by locale
-
-**File:** `src/worktree/worktree-manager.ts:127-140` (try/catch around `worktree add`)
-
-**Problem:**
-- The regex `/already checked out/` only matches when git runs with an English locale. On a user machine with `LANG=vi_VN` or Git for Windows with a different locale, the original message differs → falls back to throwing the raw error.
-
-**Proposed fix:** force an English locale for the internal git command, or broaden the regex.
-
-Option A (simpler): broaden the regex
-```ts
-if (/already checked out|is already used by worktree/i.test(msg)) { ... }
-```
-
-Option B (recommended): force `LANG=C` in the `git()` helper:
-```ts
-function git(cwd: string, args: string[]): string {
-	return execFileSync("git", args, {
-		cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"],
-		env: { ...process.env, LANG: "C", LC_ALL: "C" },
-	}).trim();
-}
-```
-
-Option B standardizes all git output → also improves debugging.
-
----
-
-### C6 — (Info, ~5 minutes) `branchExists` remote-only creates local from HEAD, may "lose" the remote's commits
-
-**File:** `src/worktree/worktree-manager.ts:prepareTaskWorkspace`
-
-**Current state:**
-```ts
-if (exists.local) {
-	git(repoRoot, ["worktree", "add", worktreePath, branch]);
-} else {
-	git(repoRoot, ["worktree", "add", "-b", branch, worktreePath, "HEAD"]);  // ← both remoteOnly and "doesn't exist" fall here
-}
-```
-
-**Problem:**
-- When `remoteOnly === true`, plan A1 proposed creating local from HEAD to avoid divergent tracking. The current code does exactly that, but:
-  - The user pushed the branch from another machine → expects the worktree to contain that code.
-  - There's no log/warning → silent drop.
-
-**Proposed fix:** emit an info event/log when hitting the remoteOnly branch:
-```ts
-} else {
-	if (exists.remoteOnly) {
-		logInternalError("worktree.branchRemoteOnly", new Error(`Branch '${branch}' exists only on remote; creating local from HEAD instead of tracking remote.`), `branch=${branch}`);
-	}
-	git(repoRoot, ["worktree", "add", "-b", branch, worktreePath, "HEAD"]);
-}
-```
-
-(Or push it out via a run event if there's a convenient event bus.)
-
----
-
-## Implementation priority
-
-| # | Item | Severity | Effort | Recommendation |
-|---|---|---|---|---|
-| 1 | C1 (lazy-imports cross-platform) | Medium | 10 minutes | Current sprint — block CI failure on Windows |
-| 2 | C2 (allow-list env filter) | Medium | 20 minutes | Current sprint — defense-in-depth |
-| 3 | C3 (.cmd/.bat on Node 20+) | Low | 10 minutes | Current sprint — ensure B1 is truly portable |
-| 4 | C4 (test linkNodeModules file source) | Low | 15 minutes | Current sprint — close B2's regression gap |
-| 5 | C5 (git locale-safe error parsing) | Low | 5 minutes | Next sprint |
-| 6 | C6 (warn on remote-only branch) | Info | 5 minutes | Next sprint |
-
-**Total effort:** ~65 minutes for the hardening batch.
-
----
-
-## Proposed commit batches
-
-- **Batch 1 (must-fix CI):** C1 + C3 → 1 PR "scripts/cmd portability fix" (~20 minutes).
-- **Batch 2 (security/test):** C2 + C4 → 1 PR "env allow-list + worktree regression test" (~35 minutes).
-- **Batch 3 (polish):** C5 + C6 → 1 PR "git locale + remote-only branch hint" (~10 minutes).
-
----
-
-## Positive notes after round 3 review
-
-- The 8 previously failing bash-on-Windows tests now pass 100%.
-- The DRY refactor of `sanitizeEnvSecrets` (extracted from `child-pi.ts`) is good.
-- The `worktree-manager` resume logic + actionable error is very helpful for UX.
-- The lock parity test covers both sync/async paths (exactly the BUG-004 goal).
-- The artifact hash test correctly verifies the invariant `sha256(file) == contentHash`.
-- `resolveJitiRegisterPath` now tolerates various jiti packaging layouts.
-- The `branchExists` upgrade to `{local, remoteOnly}` is accurate per plan A1.
-
----
-
-## Verification
-
-```
-npm run typecheck                  → Passed
-npm run check:lazy-imports         → Fails on Windows (sed not found)
-npm run test:unit                  → 1411 tests, 1408 pass, 0 fail, 3 skip (227s)
-git show 926e6ee --stat            → 16 files changed, 797(+) 22(-)
-```

package/docs/goals.md

@@ -1,59 +0,0 @@
-# Goal Loops (`team action='goal')
-
-pi-crew v0.9.0 introduces an autonomous goal loop, modeled on Claude Code's `/goal`.
-
-## What it does
-
-A goal loop turns a single objective into a long-running, self-directed multi-turn
-process:
-
-1. A **worker** agent does one turn of work (`executeTeamRun`).
-2. A separate **evaluator** model (the "goal-judge") reads the turn's transcript +
-   tool calls + verification results and returns a verdict:
-   `{ achieved: bool, reason: string, evidenceRefs?: string[] }`.
-3. If **not achieved**, the `reason` is prepended to the next turn's prompt and the
-   loop continues.
-4. Stops on: `achieved` / `maxTurns` reached / `budgetAbort` exceeded / `BLOCKED:` /
-   user `stop`.
-
-## Usage
-
-```
-team action='goal', config.subAction='start',
-      config.objective='Migrate src/auth from JS to TS. Done when tsc --noEmit=0 and test/auth passes.',
-      config.evaluatorModel='haiku',
-      config.maxTurns=20,
-      budgetTotal=500000
-```
-
-Sub-actions: `start | status | pause | resume | stop | step | clear`.
-
-Slash command: `/team-goal start --objective='...' --evaluatorModel='...'`
-
-## Design notes (see `research-findings/goal-workflow/`)
-
-- **One manifest per turn** — `TEAM_RUN_STATUS_TRANSITIONS` + `shouldMergeTaskUpdate`
-  block re-driving a terminal manifest, so each turn is a fresh `createRunManifest`.
-  The goal loop owns OUTER state in `GoalLoopState` at
-  `<crewRoot>/state/goals/<goalId>.json`.
-- **Feedback via `manifest.goal`** — the verdict's `reason` is composed into the next
-  turn's `manifest.goal` (re-read lazily each render). `session.steer` is NOT used
-  (it's a no-op for child-process runs).
-- **Budget via `collectRunMetrics`** — `budgetUsed = Σ over turns of collectRunMetrics(cwd, turnRunId).totalTokens`.
-  (`loadRunMetrics`/`saveRunMetrics` have 0 callers — do not use.)
-- **Judge lockdown** — the synthesized `goal-judge` AgentConfig sets `disableTools:true`
-  (Pi `--no-tools`), `excludeTools:[bash,read,write,edit]`, `inheritContext:false`,
-  `excludeContextBash:true`, `parentContext:undefined`, `maxTurns:1`. An empty
-  `tools:[]` is INSUFFICIENT because `pi-args.ts` skips empty arrays.
-- **Trust boundary** — the judge is capability-locked (no agency, only emits a verdict).
-
-## Background spawn
-
-The loop runs in the background via `runKind:'goal-loop'` (background-runner.ts
-dispatch). The handler `handleGoal('start')` writes the `GoalLoopState`; the
-background process calls `runGoalLoop` which loops `executeTeamRun` per turn.
-
-## Hooks
-
-- `before_goal_step` — fires before each turn.
-- `before_goal_abort` — fires before a budget/maxTurns abort.

package/docs/implementation-plan-top3.md

@@ -1,333 +0,0 @@
-# Implementation Plan: Top 3 Features from oh-my-pi v15
-
-> Date: 2026-05-13
-> Based on: `D:/my/my_project/source/oh-my-pi` research
-> Target: pi-crew v0.2.x
-
----
-
-## Priority Order
-
-1. **Typed Crew Errors** — Quick win, no dependencies
-2. **Conflict Detection** — High value, standalone module
-3. **Issue-PR Protocol** — Medium complexity, GitHub integration
-
----
-
-## 1. Typed Crew Errors
-
-### Why
-Current pi-crew uses generic `Error` types with string matching:
-```typescript
-catch (e) {
-  if (e instanceof Error && e.message.includes("deadletter")) { ... }
-}
-```
-
-Pattern from oh-my-pi: use typed sentinel errors with `instanceof` discrimination.
-
-### Files to create/modify
-
-**Create:** `src/runtime/errors/crew-errors.ts`
-
-```typescript
-/**
- * Typed error sentinels for pi-crew operations.
- * Follows oh-my-pi pattern from compaction/errors.ts.
- */
-
-export class CrewCancelledError extends Error {
-  readonly name = "CrewCancelledError" as const;
-  constructor(message = "Crew run cancelled") { super(message); }
-}
-
-export class CrewTimeoutError extends Error {
-  readonly name = "CrewTimeoutError" as const;
-  constructor(public readonly maxDurationMs: number) {
-    super(`Crew run exceeded timeout of ${maxDurationMs}ms`);
-  }
-}
-
-export class CrewDeadletterError extends Error {
-  readonly name = "CrewDeadletterError" as const;
-  constructor(
-    public readonly agentId: string,
-    public readonly reason: string,
-  ) {
-    super(`Agent ${agentId} deadlettered: ${reason}`);
-  }
-}
-
-export class CrewAbortError extends Error {
-  readonly name = "CrewAbortError" as const;
-  constructor(message = "Crew run aborted") { super(message); }
-}
-
-export class CrewManifestError extends Error {
-  readonly name = "CrewManifestError" as const;
-  constructor(message: string, public readonly runId?: string) { super(message); }
-}
-
-export class CrewLockError extends Error {
-  readonly name = "CrewLockError" as const;
-  constructor(message: string, public readonly lockPath?: string) { super(message); }
-}
-
-/**
- * Outcome of a crew run attempt.
- * Used by RunTracker and HealthWatcher.
- */
-export type CrewRunOutcome = "ok" | "cancelled" | "deadletter" | "failed" | "timeout" | "aborted";
-```
-
-**Update:** `src/runtime/task-runner.ts`, `src/runtime/team-runner.ts`, `src/runtime/crash-recovery.ts`
-
-Replace string matching with `instanceof` checks.
-
-### Implementation
-
-```bash
-# 1. Create file
-cat > src/runtime/errors/crew-errors.ts << 'EOF'
-// (content above)
-EOF
-
-# 2. Update imports in affected files
-# From: catch (e) { if (e instanceof Error && e.message.includes("deadletter")) ... }
-# To: catch (e) { if (e instanceof CrewDeadletterError) ... }
-```
-
-### Effort: LOW (1-2 hours)
-
----
-
-## 2. Conflict Detection
-
-### Why
-When multiple pi-crew agents edit the same file in a worktree, git merge conflicts can occur. Current pi-crew has no conflict detection — agents see garbled `<<<<<<< HEAD` markers with no structured way to resolve them.
-
-### Architecture
-
-```
-pi-crew worktree agents edit files
-         ↓
-   WorktreeManager detects file change
-         ↓
-   ConflictDetector.scanFileForConflicts(path)
-         ↓
-   Returns ConflictBlock[] + registers in ConflictHistory
-         ↓
-   Read tool appends conflict warning footer
-         ↓
-   Agent calls write({ path: "conflict://<id>", content })
-         ↓
-   ConflictResolver.spliceConflict() → clean file
-```
-
-### Files to create
-
-**Create:** `src/utils/conflict-detect.ts` (fork from oh-my-pi, ~400 lines)
-
-Key exports:
-- `scanConflictLines(lines, firstLineNumber)` → `ConflictBlock[]`
-- `scanFileForConflicts(path)` → `{ blocks, scanTruncated }`
-- `ConflictHistory` class
-- `ConflictEntry` interface
-- `parseConflictUri(raw)` → `ParsedConflictUri | null`
-- `spliceConflict(text, entry, replacement)` → `string`
-- `expandContentTokens(content, entry)` → `string` (handles @ours/@theirs/@base/@both)
-- `renderConflictRegion(entry, scope)` → `{ lines, startLine }`
-- `formatConflictWarning(entries)` → `string`
-
-**Create:** `src/runtime/conflict-registry.ts`
-
-```typescript
-/**
- * Global conflict registry for pi-crew.
- * Attaches ConflictHistory to each live session.
- */
-import { ConflictHistory, getConflictHistory } from "../utils/conflict-detect.ts";
-import type { LiveAgentHandle } from "./live-agent-manager.ts";
-
-export function getAgentConflicts(handle: LiveAgentHandle): ConflictHistory {
-  if (!handle.conflictHistory) {
-    handle.conflictHistory = new ConflictHistory();
-  }
-  return handle.conflictHistory;
-}
-```
-
-**Modify:** `src/extension/registration/tools/read-tool.ts`
-
-After reading file content:
-1. Call `scanConflictLines(lines, 1)`
-2. For each block, call `conflictHistory.register(...)`
-3. Append `formatConflictWarning(entries)` to output
-
-**Modify:** `src/extension/registration/tools/write-tool.ts`
-
-Add `conflict://<N>` handling:
-1. Parse URI with `parseConflictUri(path)`
-2. Look up `ConflictEntry` from `ConflictHistory`
-3. Call `expandContentTokens(content, entry)`
-4. Call `spliceConflict(originalText, entry, expandedContent)`
-5. Write result to `entry.absolutePath`
-
-### Integration points
-
-| File | Change |
-|------|--------|
-| `src/extension/registration/tools/read-tool.ts` | Append conflict warning to file content |
-| `src/extension/registration/tools/write-tool.ts` | Handle `conflict://` protocol |
-| `src/runtime/live-agent-manager.ts` | Add `conflictHistory?: ConflictHistory` to handle |
-| `src/utils/conflict-detect.ts` | New file (fork from oh-my-pi) |
-| `src/runtime/conflict-registry.ts` | New file (global registry) |
-
-### Edge cases to handle
-
-1. **Nested conflicts** — oh-my-pi handles by requiring strict marker shape
-2. **Multi-file conflicts** — `ConflictHistory.invalidatePath()` when file is resolved
-3. **Retry after partial resolution** — `ConflictEntry` id stays stable
-4. **Large files** — `scanFileForConflicts` caps at 10MB
-5. **Diff3 conflicts** — Support `|||||||` base section
-
-### Test plan
-
-```typescript
-// test/unit/conflict-detect.test.ts
-test("scanConflictLines detects single 2-way block", () => {
-  const lines = ["<<<<<<< HEAD", "our changes", "=======", "their changes", ">>>>>>> feature"];
-  const blocks = scanConflictLines(lines, 1);
-  assert(blocks.length === 1);
-  assert(blocks[0].oursLines[0] === "our changes");
-});
-
-test("scanConflictLines ignores non-column-0 markers", () => {
-  const lines = ["  <<<<<<< indented", "=======", ">>>>>>>"];
-  const blocks = scanConflictLines(lines, 1);
-  assert(blocks.length === 0);
-});
-
-test("scanConflictLines detects diff3 3-way block", () => {
-  // ...with ||||||| base marker
-});
-```
-
-### Effort: MEDIUM (4-8 hours)
-
----
-
-## 3. Issue-PR Protocol
-
-### Why
-pi-crew workflow agents can benefit from issue/PR integration:
-- Create issue from failed task
-- Link workflow tasks to GitHub issues
-- PR review workflow (`pr://` protocol)
-
-### URL shapes to support
-
-```
-issue://              — list recent issues (default repo from cwd)
-issue://owner/repo    — list issues for repo
-issue://123           — single issue (repo from cwd)
-issue://owner/repo/123 — fully qualified
-issue://owner/repo/123?comments=0 — suppress comments
-
-pr://                 — list recent PRs
-pr://owner/repo       — list PRs for repo
-pr://owner/repo/456  — single PR
-pr://owner/repo/456/diff — PR diff
-```
-
-### Files to create/modify
-
-**Create:** `src/internal-urls/issue-pr-protocol.ts` (port from oh-my-pi, ~577 lines)
-
-Key exports:
-- `IssuePrProtocol` class implementing `ProtocolHandler`
-- `parseIssueUrl(url)` → `ParsedIssue`
-- `parsePrUrl(url)` → `ParsedPr`
-- `fetchIssue(parsed)` → `string` (markdown)
-- `fetchPr(parsed)` → `string` (markdown)
-- `fetchPrDiff(parsed)` → `string` (unified diff)
-
-**Modify:** `src/internal-urls/router.ts`
-
-Register `issue://` and `pr://` handlers.
-
-**Create:** `src/tools/gh-cache.ts` (fork from oh-my-pi `tools/github-cache.ts`)
-
-SQLite-backed cache for GitHub API responses. Shared across sessions.
-
-### Dependencies
-
-1. **GitHub CLI (`gh`)** — oh-my-pi uses `gh issue list`, `gh pr list`, `gh api`
-2. **SQLite** — via `better-sqlite3` or similar
-3. **Git config** — Need to resolve default repo from `git remote get-url origin`
-
-### Implementation details
-
-```typescript
-interface ParsedIssue {
-  kind: "single" | "list";
-  repo?: string;  // undefined = derive from cwd
-  number?: number;
-  state?: "open" | "closed" | "all";
-  limit?: number;
-  comments?: boolean;
-}
-
-interface ParsedPr {
-  kind: "single" | "list" | "diff";
-  repo?: string;
-  number?: number;
-  state?: "open" | "closed" | "merged" | "all";
-  limit?: number;
-  diffMode?: "list" | "all";
-}
-```
-
-**Fetching:**
-- List: `gh issue list --repo owner/repo --state open --limit 30`
-- Single: `gh issue view 123 --repo owner/repo --comments`
-- PR: `gh pr view 456 --repo owner/repo --comments`
-- Diff: `gh pr diff 456 --repo owner/repo`
-
-**Caching:**
-- Cache key: `{repo, number, type}` hash
-- TTL: 5 minutes for list, 1 hour for single items
-- Invalidate on write operations (create/close/reopen)
-
-### Integration with pi-crew
-
-**New tool:** `read-issue` / `read-pr`
-```typescript
-// agents can call:
-// read({ path: "issue://123" }) → markdown of the issue
-// read({ path: "pr://456" }) → markdown of the PR
-```
-
-**New slash command:** `/issue` or use the existing `/crew`:
-```
-/crew create-issue "Task failed: fix memory leak in cache" --labels=bug --assignee=me
-/crew link-issue TICKET-123 --task=explorer-1
-```
-
-### Effort: MEDIUM-HIGH (8-12 hours)
-
----
-
-## Summary
-
-| Feature | Effort | Risk | Priority |
-|---------|--------|------|----------|
-| Typed Crew Errors | LOW | None | 1 |
-| Conflict Detection | MEDIUM | Git operations, large file handling | 2 |
-| Issue-PR Protocol | MEDIUM-HIGH | GitHub auth, gh CLI dependency | 3 |
-
-## Recommended execution order
-
-1. **Day 1:** Typed Crew Errors (quick win)
-2. **Day 2-3:** Conflict Detection
-3. **Day 4-5:** Issue-PR Protocol (if time permits)