pi-crew 0.9.12 → 0.9.13

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## [v0.9.13] — chain feature + raw worker output + anti-zombie hardening (2026-06-29)
+
+Context/compaction efficiency work + a live `chain` feature that wires previously-dead code, plus two root-cause zombie fixes. The unifying theme: **deliver the right context efficiently and never leave orphaned state behind.**
+
+### Features
+
+- **Section-aware knowledge injection** (`knowledge-injection.ts`) — `.crew/knowledge.md` is no longer injected as a uniform head-only block. CONVENTIONS sections (always-relevant: Code Style, Environment, Architecture, Testing, Release Process) are injected in full; SESSION-LOG sections (per-version post-mortems, incidents) are IDF-scored against the task/goal and budget-capped (5 KB), drop-whole with a head-slice fallback and a section-index recovery net. Cuts knowledge-token waste for trivial tasks (a `team action='run'` with a trivial goal went from ~4 000 tokens of mostly-irrelevant session-log noise to ~2 095 tokens of conventions + matching session-log) without starving architecture-relevant tasks. Backward compatible: `readKnowledge(cwd)` with no query keeps the legacy head-only path. Verified live (post-restart research run): worker knowledge dropped from ~4 000 tokens (95 % session-log noise) to ~2 095 tokens, with the synthesized Architecture reference present.
+
+- **Live `chain` feature** (`team action='run', chain='"a" -> "b" -> "c"'`) — `ChainRunner` was complete and unit-tested but had ZERO production callers. Each step now runs a REAL team run via an injected `handleRun`, with handoff context (including the previous step's output text) passed forward through a `# Previous Steps in This Chain` block prepended to the step's goal. This also makes `enrichContextFromHandoffs`'s honesty markers (`__chainHistoryNotes`) reachable in production. See `src/extension/team-tool/{chain-dispatch,chain-executor}.ts`.
+
+### Bug fixes
+
+- **Raw worker result + dependency-context tee recovery (output)** — `results/<id>.txt` was 16 K-capped at child-pi stream-parse time (`compactContentPart` caps assistant text at `MAX_ASSISTANT_TEXT_CHARS`), and the dependency-context path re-read the same capped text circularly (no tee, unlike sharedReads). Now: (a) `ChildPiLineObserver` captures the RAW final assistant text before the transcript's compaction, and `task-runner` writes it as the authoritative `results/<id>.txt` (monotonic-safe fallback to transcript-derived `finalText`); the transcript stays 16 K-capped (telemetry memory bound unchanged). (b) `collectDependencyOutputContext` now uses `readIfSmallWithTee` (matching sharedReads) and `renderDependencyOutputContext` surfaces the `Full output (if you need the missing middle): <path>` hint, breaking the circular re-read. Verified live: a research run's analyst result went from a 16 K-capped file with a `[pi-crew compacted N chars]` marker to a 33 KB RAW file with zero data-loss markers; the downstream writer received 33 K of raw dependency context. Tracing in `research-findings/output-handling-deep-dive.md`.
+
+- **Truncated-content recovery hints** — truncation markers in knowledge (`knowledge-injection.ts`), agent memory (`agent-memory.ts`), and dependency output now embed the absolute path + a `read`-tool hint so workers can recover the dropped tail instead of silently losing it. Tee threshold lowered 2× → 1.25× (`TEE_THRESHOLD_MULTIPLIER`) so the 32–64 KB band gets a recovery path. Live-session system prompt no longer duplicates the MEMORY block (it was already injected via `renderTaskPrompt().full`).
+
+- **background-runner watchdog (anti-zombie processes)** — the keepAlive interval (`setInterval(()=>{}, 5000)`, no `unref`) cleared only in `runCleanup`, so a hung team run (stuck child Pi, deadlocked lock, or a test that spawns a run without cleanup) left the process alive indefinitely. The existing parent-guard only fires when the parent DIES; here the parent hung too, so it never fired. Fix: a watchdog timer alongside keepAlive aborts via the shared `AbortController` (propagates → child-pi → kills child processes) and force-exits after a 15 s grace if the abort does not propagate. Default 2 h (generous for legitimate long runs); override via `PI_CREW_MAX_RUN_MS`. Verified live: normal run exits cleanly (watchdog cleared, 0 `watchdog_fired` events); isolated hang fires at exactly `MAX` ms.
+
+- **Test state isolation (anti-zombie UI rows)** — `useProjectState(cwd)` returns `findRepoRoot(cwd) !== undefined`, and `scopeBaseRoot` falls back to the EXTENSION-GLOBAL state dir (`~/.pi/agent/extensions/pi-crew/state/runs/`) when cwd is NOT a git repo. Tests that create a tmpdir WITHOUT `git init` and call `createRunManifest`/`writeRunFixture`/`createRunPaths` were leaking run records into that global dir — the one the crew widget reads — creating persistent fake-agent rows after every test run. Fix: the shared `createTrackedTempDir` helper and `state-store.test.ts`'s `makeResolvedTempDir` now create a `.git` marker dir so records land in `<tmpdir>/.crew/` (auto-cleaned). Protects all current and future callers. Verified: state-store + cov + chain-executor tests left global state 2 → 2 (zero leak).
+
+### Docs
+
+- **README** — removed 182 lines of version-by-version highlights (v0.9.0 → v0.9.12, v0.8.x, v0.7.0) that duplicated CHANGELOG.md. README now flows intro → `## Features` straight. Version tags remain only where they qualify a feature (e.g. `(L4, v0.9.8)`) — useful for deciding whether to upgrade.
+
+### Stats
+
+29 files changed · ~2 498 insertions / ~189 deletions across 7 commits.
+
+### Verification
+
+- `npx tsc --noEmit`: clean.
+- 44/44 new + modified unit tests pass (`raw-final-text`, `dependency-tee`, `chain-executor`, `chain-handoff-markers`, `background-runner-watchdog`).
+- Live (post-restart): chain 2-step run produced enriched step-2 goal with step 1's output; raw worker result verified end-to-end (33 KB analyst result, 0 markers); watchdog verified on normal path (clean exit) + hang path (fires at MAX ms).
+
 ## [v0.9.12] — TUI UI/UX polish (21 findings) (2026-06-27)
 
 Comprehensive TUI UX review of pi-crew's UI layer (`src/ui/` + `src/utils/visual.ts`). 21 findings (5×P1, 10×P2, 6×P3), all addressed. Full review with evidence-backed file:line citations: `research-findings/pi-crew-uiux-review.md`.

package/README.md

@@ -39,141 +39,7 @@ npm: pi-crew
 repo: https://github.com/baphuongna/pi-crew
 ```
 
-**v0.9.4 / v0.9.5 / v0.9.8 / v0.9.9**: See [CHANGELOG.md](CHANGELOG.md).
-
-### Highlights (v0.6.4 → v0.9.9)
-
-A long arc of **trust, cliff-resilience, and robustness** work. Principle: *build
-trust and cliff-resilience, stay lean, delete before adding.*
-
-#### v0.9.5 — fix "team run hangs forever at 25%" (2026-06-23)
-Two coupled runtime bugs caused recurring "run stuck at 25% (1/4)" failures
-across 4+ consecutive review/fast-fix runs. The combined symptom: scheduler
-appears to stop responding right after the first task (explorer) finishes, no
-progress to task 2, and `team action='status'` returns "Run not found" with
-**no diagnostic trail** to investigate. Manual `kill` of the parent `pi`
-process was the only workaround.
-
-- **🩹 Bug X (proximate cause)** — `purgeStaleActiveRunIndex`
-  (`src/runtime/crash-recovery.ts`) destroyed a run's `stateRoot` based on a
-  **frozen** `entry.updatedAt` (set once at registration, never refreshed).
-  Any long-running legitimate async run (≥5 min) whose worker had exited
-  lost its entire durable state. `saveRunTasks()` then silently no-op'd on
-  the missing dir, and the workflow could never advance. Fix: corroborate
-  liveness via the on-disk `manifest.updatedAt` AND the team-level
-  `heartbeat.json`; keep `stateRoot` on cancel so runs stay queryable and
-  resumable.
-- **🩹 Bug Y (root cause — why the scheduler died in the first place)** —
-  `src/runtime/background-runner.ts` redirected only `console.log` /
-  `console.error` to the log file. The first post-detach `console.debug`
-  call from `team-runner.ts:242` (inside `mergeTaskUpdatesPreservingTerminal`
-  → "Skipping stale merge") hit the disconnected stdout pipe → unhandled
-  `EPIPE` → process exit. Prior investigators concluded (incorrectly) that
-  the cause was a native crash, because diagnostic `[DIAG]` handlers never
-  fired on the EPIPE. Fix: extend the console redirect to `console.debug` /
-  `console.warn`, and wrap `fs.writeSync` in try-catch so any log-write
-  failure can never crash the scheduler.
-- **🧪 Regression coverage** — 7 new tests: 3 in
-  `test/unit/crash-recovery-purge-liveness.test.ts` (fresh-manifest-kept,
-  orphan-cancelled-preserved, fresh-heartbeat-kept) + 4 in
-  `test/unit/background-runner-console-redirect.test.ts` (drift-detector
-  pattern that exercises undefined / valid / EBADF / post-toggle logFd).
-- **📖 See [CHANGELOG.md](CHANGELOG.md) for full details**, including
-  why prior attempts to diagnose the hang kept destroying the only
-  evidence (Bug X nuked the stateRoot before anyone could read the EPIPE
-  crash in Bug Y).
-
-> **Recovering a stuck run from v0.9.4 or earlier:** the `stateRoot` for
-> those runs is already gone. Re-dispatch the workflow — new runs are
-> fully protected.
-
-#### v0.9.4 — macOS CI fixture (2026-06-23)
-- **🧪 BSD-vs-GNU grep fix** — benchmark test fixtures used
-  `grep --help` (exits 0 on GNU/Linux, exits 2 on BSD/macOS). Switched
-  the exit-0 fixture to `echo ok`; the not-in-allowlist fixture is now
-  `ls`. CI matrix is now green on all 3 OSes.
-- **📌 Process note** — this release re-commits to: **tag/publish ONLY
-  after the full OS matrix CI is green.** v0.9.3 was published mid-CI-run
-  (the macOS job hadn't finished); the package itself was correct (the
-  broken file is test-only and not shipped), but the repo CI went red.
-  v0.9.4 restores green CI. v0.9.5 follows the same discipline.
-
-#### v0.9.0 — goal loops + dynamic workflows (2026-06-18)
-Two new features, both modeled on Claude Code, built on a shared `runKind`
-background-dispatch discriminator.
-
-- **🎯 Autonomous goal loops** — `team action='goal'` runs a self-directed
-  multi-turn loop: a **worker** does a turn, a separate **LLM judge**
-  (capability-locked, no tools) evaluates the transcript + verification against
-  the objective, and on "not-achieved" the reason is fed into the next turn's
-  prompt. Stops on `achieved` / `maxTurns` / budget / `BLOCKED:` / user `stop`.
-  See [docs/goals.md](docs/goals.md).
-- **📜 Dynamic workflows (`.dwf.ts`)** — author orchestration as a TypeScript
-  script (JS loops/branch/cross-review) instead of a static step list. Runs in
-  the background, spawns subagents via `ctx.agent()`/`ctx.fanOut()`, holds
-  intermediate results in JS variables, and only `ctx.setResult()` reaches the
-  main context. `workflow-create`/`-delete` are ACE-gated (`confirm:true`,
-  user-confirmed). See [docs/dynamic-workflows.md](docs/dynamic-workflows.md).
-- **🛡️ Goal-wrap** (RFC v0.5 vision) — apply the goal completion-guarantee to
-  existing builtin workflows (`implementation`, `fast-fix`, `default`) via
-  per-workflow `.crew/config.json` toggle. Single-step workflows goal-wrap
-  end-to-end; multi-step workflows auto-downgrade to a normal team-run because
-  they crash non-deterministically under the V8/libuv event-loop (see [Known
-  limitations](#known-limitations)).
-- **🔐 Phase 1 integrity hardening** (P1a–P1g) — verification bookend snapshots,
-  anti-oscillation (`stuck` non-terminal + resumable), budget enforcement
-  (required or explicit opt-out), nonce-token feedback sanitization, secret
-  redaction at artifact-write (O(n) fix), global worker cap + workspace lock
-  (O_EXCL, startTime-safe). B2 confused-deputy (auto-detecting verification
-  commands) refused — user must declare verification explicitly.
-- **🧪 Phase 1.5 fast-follow** — opt-in mitigation toggles for residual risks:
-  `PI_CREW_VERIFICATION_SANITIZE_ENV=1` (strip provider secrets from the
-  verification subprocess), `PI_CREW_VERIFICATION_WORKTREE=1` (run verification
-  in a pristine git worktree at the T_snap commit SHA),
-  `PI_CREW_BG_REPORT_ON_FATAL=1` (V8 diagnostic report on fatal).
-- **🐛 TDZ fix** (Phase 1.5 #4) — live `team action='run' workflow='<dynamic>'`
-  was failing with a misleading "must export a default async function" error.
-  Root cause was a Temporal Dead Zone race in `team-tool/run.ts` when loaded via
-  the full Pi extension pipeline (`index.ts → … → run.ts`). Fixed by
-  `let`→`var` on the latch + lazy dynamic imports at call sites.
-
-#### v0.8.x — hardening & reliability (2026-06-17)
-- **🛠️ Split-scope install fix (v0.8.11)** — `team` runs no longer crash with
-  `Cannot find module '@earendil-works/pi-coding-agent'` when pi-crew and pi
-  live in separate node_modules trees (the default for `pi install`). New
-  `src/runtime/peer-dep.ts` resolves the ESM-only peer dep across 6 strategies.
-- **🔄 Model fallback on transient 5xx (v0.8.11)** — a hard-down provider
-  (`500 api_error "unknown error"`) now triggers the configured fallback
-  model instead of aborting the run. `isRetryableModelFailure` extended.
-- **🧊 Cold-start race eliminated (v0.8.6 → v0.8.10)** — under tsx, concurrent
-  subagent spawns raced module instantiation (`existsSync` / `CREW_README` /
-  `effectiveRunConfig` / `validateWorkflowForTeam`). Fixed graph-wide: warm at
-  registration + gate at spawn boundaries + per-site latches. 6/6 repro clean.
-- **🔒 Cross-project leak fixed (v0.8.8)** — ambient status / compaction no
-  longer bleed foreign-project runs into the current session. Cwd-scope
-  barrier (`isInProjectScope`), version-independent.
-- **🩺 Doctor runtime-warmup status (v0.8.7)** — `team doctor` shows whether
-  the module-graph warmup fired.
-- **🔍 Cold-verifier agent (v0.8.4)** — adversarial cross-check that re-derives
-  claims WITHOUT trusting prior analysis, catching confirmation bias.
-- **⚡ Per-write validator (v0.8.5)** — zero-cost `JSON.parse` on every
-  `write`/`edit`, appends a `🔴` blocker on malformed files.
-- **🎨 Terminal status (v0.8.3)** — tab title + Ghostty native progress bar.
-- **🧠 Skill confidence revived (v0.8.2)** — `adjustConfidence()` was dead
-  code; the effectiveness system now actually learns.
-- **🔧 Tool-restriction unification (v0.8.0)** — single `resolveToolPolicy`
-  across both spawn paths.
-- **🎯 F6/F1 interop granularity (v0.7.9)** — 7 skill roots, `.pi/agents/`
-  tier, tool wildcards, `excludeExtensions` denylist.
-
-#### v0.7.0 — Phase 0 + Phase 1 roadmap
-- **🛡️ Compaction resilience (O10)** — in-flight runs survive auto-compact.
-- **💰 Cost visibility (O1)** — per-role token + cost attribution.
-- **✋ Plan-level HITL (O5)** — `requirePlanApproval` gates any workflow.
-- **🧠 Cross-run memory (O4)** — `.crew/knowledge.md` injected every run.
-- **🎯 Single-agent cliff hedge** — `team plan singleAgent=true`.
 
----
 
 ## Features
 
@@ -697,7 +563,7 @@ npm run ci           # full CI-equivalent check
 npm pack --dry-run   # package verification
 ```
 
-Stats: **366 source files** (70K lines) · **506 test files** (66K lines) · **4,792 tests, 0 failures** · **CI: Ubuntu ✅ macOS ✅ Windows ✅**
+Stats: **431 source files** (87K lines) · **606 test files** (85K lines) · **~5,860 tests, 0 failures** · **CI: Ubuntu ✅ macOS ✅ Windows ✅**
 
 ---
 

package/package.json

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

package/src/extension/knowledge-injection.ts

@@ -9,6 +9,16 @@
  * Philosophy (Round 6 stress-test): radically downsized. Just a Markdown
  * file the user can edit, surfaced into every run. No vector DB, no
  * embeddings, no graph. Simple = trustworthy.
+ *
+ * B2 section-aware injection (2026-06-28): knowledge.md splits cleanly into
+ * CONVENTIONS (always-relevant: Code Style, Environment, Architecture,
+ * Testing, Release Process — ~2.5KB) and SESSION-LOG (per-version post-
+ * mortems, incidents, fix detail — ~29KB, rarely relevant). Conventions
+ * are ALWAYS injected; session-log sections are injected on-demand via
+ * header-token IDF scoring against the task/goal, capped at
+ * MAX_SESSION_LOG_BYTES. Non-matched session-log is summarized as a section
+ * index with a `read` path-hint so the worker can recover any omitted topic.
+ * Design doc: research-findings/b2-section-aware-design.md.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -17,20 +27,179 @@ import { projectCrewRoot } from "../utils/paths.ts";
 
 /** The knowledge file, relative to the project crew root. */
 export const KNOWLEDGE_FILENAME = "knowledge.md";
-/** Cap injected knowledge to avoid unbounded system-prompt growth. */
-const MAX_KNOWLEDGE_BYTES = 16_000;
+
+/**
+ * Session-log injection cap (B2). Conventions are always injected in full;
+ * matched session-log sections are capped here to bound total prompt size.
+ * Sized so 2-3 typical sections (~1-2.5KB each) fit, while the largest single
+ * outlier (v0.9.10 IN PROGRESS, ~7KB) is excluded from a full-match scenario.
+ */
+const MAX_SESSION_LOG_BYTES = 5_000;
+
+/**
+ * Relevance context for section-aware injection. When omitted (or when goal/
+ * taskText are both absent), injection falls back to conventions-only — no
+ * IDF computation, no session-log body. This keeps callers without query
+ * context (main-session hook, legacy tests) stable.
+ */
+export interface KnowledgeQuery {
+	/** The team run goal (broad topic signal). */
+	goal?: string;
+	/** The step/task instruction text (narrow topic signal). */
+	taskText?: string;
+	/** The worker role (reserved for future role-floor/boost; not scored yet). */
+	role?: string;
+}
+
+/**
+ * Headers of sections always treated as CONVENTIONS (universal project rules).
+ * Anything NOT matching these (after the convention run) is SESSION-LOG.
+ * Header-matching is prefix + case-insensitive against the H2 title.
+ */
+const CONVENTION_HEADERS = ["Code Style", "Environment", "Architecture", "Testing", "Release Process"];
 
 /** Resolve the knowledge file path for a cwd (may not exist yet). */
 export function knowledgePath(cwd: string): string {
 	return path.join(projectCrewRoot(cwd), KNOWLEDGE_FILENAME);
 }
 
-/** Read knowledge content, truncated to a safe size. "" if absent/empty. */
-export function readKnowledge(cwd: string): string {
+interface KnowledgeSection {
+	/** H2 header text (without leading `## `). */
+	header: string;
+	/** Full section body including the `## ` header line. */
+	body: string;
+	/** Header tokens (lowercased, stopword-filtered) for IDF scoring. */
+	headerTokens: Set<string>;
+}
+
+const STOPWORDS = new Set([
+	"the", "a", "an", "is", "are", "of", "to", "in", "for", "and", "or", "not",
+	"with", "this", "that", "it", "be", "on", "at", "by", "do", "does", "how",
+	"what", "when", "from", "fix", "fixes", "fixed", "v0", "v1", "released",
+	"progress", "uncommitted", "not", "pushed", "published", "session", "post",
+]);
+
+/** Tokenize header text into a Set of lowercased non-stopword tokens. */
+function tokenizeHeader(header: string): Set<string> {
+	const tokens = new Set<string>();
+	for (const raw of header.toLowerCase().split(/[^a-z0-9.]+/)) {
+		// keep dot-paths (e.g. "run.lock", "config.ts") and alphanumerics >= 2 chars
+		const t = raw.replace(/^\.+|\.+$/g, "");
+		if (t.length >= 2 && !STOPWORDS.has(t) && !/^\d+$/.test(t)) tokens.add(t);
+	}
+	return tokens;
+}
+
+/** Parse knowledge.md into (conventions, sessionLog) sections by H2 header. */
+function parseKnowledgeSections(content: string): { conventions: KnowledgeSection[]; sessionLog: KnowledgeSection[] } {
+	const lines = content.split(/\r?\n/);
+	const sections: KnowledgeSection[] = [];
+	let current: { header: string; lines: string[] } | null = null;
+	for (const line of lines) {
+		const m = /^##\s+(.+?)\s*$/.exec(line);
+		if (m) {
+			if (current) sections.push({ header: current.header, body: current.lines.join("\n"), headerTokens: tokenizeHeader(current.header) });
+			current = { header: m[1]!, lines: [line] };
+		} else if (current) {
+			current.lines.push(line);
+		}
+	}
+	if (current) sections.push({ header: current.header, body: current.lines.join("\n"), headerTokens: tokenizeHeader(current.header) });
+
+	// Classify: a section is a CONVENTION if its header starts-with one of the
+	// known convention titles. Once we leave the convention run (first non-
+	// matching H2 after conventions), everything else is SESSION-LOG. This is
+	// self-healing: if knowledge.md is restructured, the classifier adapts.
+	const conventions: KnowledgeSection[] = [];
+	const sessionLog: KnowledgeSection[] = [];
+	let leftConventionRun = false;
+	for (const sec of sections) {
+		const isConvention = !leftConventionRun && CONVENTION_HEADERS.some((c) => sec.header.toLowerCase().startsWith(c.toLowerCase()));
+		if (isConvention) conventions.push(sec);
+		else {
+			leftConventionRun = true;
+			sessionLog.push(sec);
+		}
+	}
+	return { conventions, sessionLog };
+}
+
+/** Compute IDF (inverse document frequency) over session-log header tokens. */
+function computeIdf(sections: KnowledgeSection[]): Map<string, number> {
+	const N = sections.length;
+	const df = new Map<string, number>();
+	for (const s of sections) for (const token of s.headerTokens) df.set(token, (df.get(token) ?? 0) + 1);
+	const idf = new Map<string, number>();
+	for (const [token, freq] of df) idf.set(token, Math.log(N / freq)); // standard IDF; freq >= 1
+	return idf;
+}
+
+/** Tokenize a free-form query (goal/taskText) the same way as headers. */
+function tokenizeQuery(query: string): Set<string> {
+	const tokens = new Set<string>();
+	for (const raw of query.toLowerCase().split(/[^a-z0-9.]+/)) {
+		const t = raw.replace(/^\.+|\.+$/g, "");
+		if (t.length >= 2 && !STOPWORDS.has(t) && !/^\d+$/.test(t)) tokens.add(t);
+	}
+	return tokens;
+}
+
+/** Score a section by summed IDF of query tokens present in its header. */
+function scoreSection(queryTokens: Set<string>, headerTokens: Set<string>, idf: Map<string, number>): number {
+	let score = 0;
+	for (const token of queryTokens) if (headerTokens.has(token)) score += idf.get(token) ?? 0;
+	return score;
+}
+
+/**
+ * Select session-log sections relevant to the query, capped at budgetBytes.
+ * Greedy by descending score (then original order), drop-whole policy with a
+ * head-slice fallback for the single best match if nothing else fits (so a
+ * matched query never returns zero bytes).
+ */
+function selectSessionLog(query: string, sessionLog: KnowledgeSection[], budgetBytes: number): KnowledgeSection[] {
+	if (sessionLog.length === 0 || !query.trim()) return [];
+	const idf = computeIdf(sessionLog);
+	const queryTokens = tokenizeQuery(query);
+	// Match = ANY header-token overlap with the query. IDF still drives RANKING
+	// (rarer overlap ranks first), but a token that happens to appear in every
+	// section (IDF=0) must still count as a match — otherwise a query for a
+	// common-but-relevant keyword (e.g. "redaction") would return nothing.
+	const scored = sessionLog
+		.map((sec, idx) => {
+			const overlap = [...queryTokens].filter((t) => sec.headerTokens.has(t));
+			return { sec, score: overlap.reduce((sum, t) => sum + (idf.get(t) ?? 0), 0), idx, hasOverlap: overlap.length > 0 };
+		})
+		.filter((x) => x.hasOverlap);
+	if (scored.length === 0) return [];
+	scored.sort((a, b) => b.score - a.score || a.idx - b.idx);
+
+	const selected: KnowledgeSection[] = [];
+	let used = 0;
+	let bestMatch: { sec: KnowledgeSection; score: number } | undefined;
+	for (const { sec, score } of scored) {
+		if (score > (bestMatch?.score ?? -1)) bestMatch = { sec, score };
+		if (used + sec.body.length <= budgetBytes) {
+			selected.push(sec);
+			used += sec.body.length;
+		}
+	}
+	// Head-slice fallback: if the best match didn't fit (or nothing fit), inject
+	// a head-sliced copy of the single best match so the query isn't empty.
+	if (selected.length === 0 && bestMatch) {
+		const sliced = bestMatch.sec.body.slice(0, Math.max(0, budgetBytes));
+		selected.push({ ...bestMatch.sec, body: `${sliced}\n\n<!-- section truncated (session-log budget ${budgetBytes} bytes). Full file: use \`read\`. -->` });
+	}
+	return selected;
+}
+
+/** Read knowledge content. "" if absent/empty. */
+export function readKnowledge(cwd: string, query?: KnowledgeQuery): string {
 	try {
 		const p = knowledgePath(cwd);
 		const stat = tryStat(p);
 		if (!stat) {
+			sectionCache.delete(p);
 			knowledgeCache.delete(p);
 			return "";
 		}
@@ -39,14 +208,46 @@ export function readKnowledge(cwd: string): string {
 		// For a run with N workers this is N redundant readFileSync of the same
 		// file. Cache by (mtimeMs, size) and only re-read when the file changes.
 		const cacheKey = `${stat.mtimeMs}:${stat.size}`;
-		const cached = knowledgeCache.get(p);
-		if (cached && cached.key === cacheKey) return cached.content;
-		let content = fs.readFileSync(p, "utf8").trim();
-		if (content.length > MAX_KNOWLEDGE_BYTES) {
-			content = `${content.slice(0, MAX_KNOWLEDGE_BYTES)}\n\n<!-- knowledge.md truncated at ${MAX_KNOWLEDGE_BYTES} bytes -->`;
+
+		// B2: when no query context is provided (main-session hook, legacy
+		// callers, tests), keep the simple head-only path. This preserves the
+		// 4 existing unit tests exactly (they call readKnowledge(cwd)).
+		if (!query || (!query.goal && !query.taskText)) {
+			const cached = knowledgeCache.get(p);
+			if (cached && cached.key === cacheKey) return cached.content;
+			let content = fs.readFileSync(p, "utf8").trim();
+			if (content.length > MAX_KNOWLEDGE_HEAD_BYTES) {
+				content = `${content.slice(0, MAX_KNOWLEDGE_HEAD_BYTES)}\n\n<!-- knowledge.md truncated at ${MAX_KNOWLEDGE_HEAD_BYTES} bytes (head shown). Full file: ${p} — use the \`read\` tool if you need sections beyond the head. -->`;
+			}
+			knowledgeCache.set(p, { key: cacheKey, content });
+			return content;
+		}
+
+		// Section-aware path: cache parsed sections, select per-query.
+		const cachedSections = sectionCache.get(p);
+		let parsed: { conventions: KnowledgeSection[]; sessionLog: KnowledgeSection[] };
+		if (cachedSections && cachedSections.key === cacheKey) {
+			parsed = { conventions: cachedSections.conventions, sessionLog: cachedSections.sessionLog };
+		} else {
+			const content = fs.readFileSync(p, "utf8").trim();
+			parsed = parseKnowledgeSections(content);
+			sectionCache.set(p, { key: cacheKey, conventions: parsed.conventions, sessionLog: parsed.sessionLog });
+		}
+
+		const queryText = [query.goal, query.taskText].filter(Boolean).join(" \n ");
+		const matchedSessionLog = selectSessionLog(queryText, parsed.sessionLog, MAX_SESSION_LOG_BYTES);
+
+		const parts: string[] = [];
+		// Conventions: always full.
+		for (const sec of parsed.conventions) parts.push(sec.body);
+		// Matched session-log (drop-whole, budget-capped).
+		for (const sec of matchedSessionLog) parts.push(sec.body);
+		// Always: section-index of ALL session-log headers (recovery safety net).
+		if (parsed.sessionLog.length > 0) {
+			const indexLines = parsed.sessionLog.map((s) => `  - ${s.header}`);
+			parts.push(`<!-- Session-log sections in knowledge.md (not injected unless matched above — use \`read\` for detail):\n${indexLines.join("\n")}\nFull file: ${p} -->`);
 		}
-		knowledgeCache.set(p, { key: cacheKey, content });
-		return content;
+		return parts.join("\n").trim();
 	} catch {
 		return "";
 	}
@@ -68,9 +269,19 @@ interface CachedKnowledge {
 }
 const knowledgeCache = new Map<string, CachedKnowledge>();
 
+interface CachedSections {
+	key: string;
+	conventions: KnowledgeSection[];
+	sessionLog: KnowledgeSection[];
+}
+const sectionCache = new Map<string, CachedSections>();
+
+/** Head cap for the no-query (legacy / main-session) path. */
+const MAX_KNOWLEDGE_HEAD_BYTES = 2_000;
+
 /** Build the injected prompt fragment (empty if no knowledge). */
-export function buildKnowledgeFragment(cwd: string): string {
-	const content = readKnowledge(cwd);
+export function buildKnowledgeFragment(cwd: string, query?: KnowledgeQuery): string {
+	const content = readKnowledge(cwd, query);
 	if (!content) return "";
 	return [
 		"",
@@ -85,8 +296,18 @@ export function buildKnowledgeFragment(cwd: string): string {
 
 /**
  * Register the knowledge-injection hook. Appends project knowledge to the
- * system prompt on every agent start (main session + each crew worker,
- * since workers are child Pi processes that also fire before_agent_start).
+ * MAIN session's system prompt on `before_agent_start`. This hook does NOT
+ * fire for crew workers: they are spawned with `--no-extensions`, so the
+ * extension layer (and this hook) never loads in their process. Workers
+ * instead receive knowledge via `buildKnowledgeFragment(task.cwd)` injected
+ * into their prompt stablePrefix by `prompt-builder.ts`. Do NOT "fix" this
+ * perceived gap by making the hook reach workers — it would cause
+ * double-injection. (Verified by research workflow 2026-06-28.)
+ *
+ * The hook calls buildKnowledgeFragment(cwd) with NO query — so the main
+ * session gets conventions-only (no session-log noise), which is the right
+ * default for an interactive session that doesn't have a single task focus.
+ * Workers (which DO have a task) use the section-aware path via prompt-builder.
  */
 export function registerKnowledgeInjection(pi: ExtensionAPI): void {
 	pi.on("before_agent_start", (event: BeforeAgentStartEvent) => {

package/src/extension/team-tool/chain-dispatch.ts

@@ -0,0 +1,103 @@
+/**
+ * Team-tool entry point for the `chain` feature.
+ *
+ * Dispatched from `handleRun` (run.ts) via an early-return guard:
+ *   if (params.chain) → handleChainRun(params, ctx, handleRun)
+ *
+ * `handleRun` is passed by reference (NOT imported) to break the
+ * run.ts ↔ chain-dispatch.ts import cycle. This file imports only
+ * chain-runner, handoff-manager, chain-executor, and the shared
+ * tool-result helpers — none of which import run.ts.
+ *
+ * @see src/extension/team-tool/chain-executor.ts (ChainTeamRunExecutor)
+ * @see src/runtime/chain-runner.ts (ChainRunner.runChain, parseChainString)
+ */
+
+import { ChainRunner, parseChainString } from "../../runtime/chain-runner.ts";
+import { HandoffManager } from "../../runtime/handoff-manager.ts";
+import { ChainTeamRunExecutor, type HandleRunFn } from "./chain-executor.ts";
+import { result, type TeamContext } from "./context.ts";
+import type { TeamToolParamsValue } from "../../schema/team-tool-schema.ts";
+import type { PiTeamsToolResult } from "../tool-result.ts";
+
+/**
+ * Execute a chain expression (`"a -> b -> c"`). Each step runs a real team run
+ * via the injected `handleRun`, with handoff context passed forward through the
+ * goal text. Returns a multi-line summary plus structured `data` for the TUI.
+ *
+ * @param params  - Must contain `chain`. `team`/`workflow`/`model` are forwarded
+ *                  as per-step overrides when a step does not declare its own.
+ * @param ctx     - The team tool context (cwd is used to load run manifests).
+ * @param handleRun - The run.ts `handleRun` function reference (injected).
+ */
+export async function handleChainRun(
+	params: TeamToolParamsValue,
+	ctx: TeamContext,
+	handleRun: HandleRunFn,
+): Promise<PiTeamsToolResult> {
+	const chainString = params.chain;
+	if (!chainString || chainString.trim().length === 0) {
+		return result("Chain expression is empty.", { action: "run", status: "error" }, true);
+	}
+
+	const spec = parseChainString(chainString);
+	if (spec.steps.length === 0) {
+		return result(
+			"Chain must contain at least one step. Use the form: \"step1 -> step2 -> step3\".",
+			{ action: "run", status: "error" },
+			true,
+		);
+	}
+
+	// Construct the concrete executor with per-step overrides forwarded from the
+	// chain invocation (overridden by any step that parsed to a @team reference).
+	const executor = new ChainTeamRunExecutor({
+		handleRun,
+		ctx,
+		overrides: {
+			team: params.team,
+			workflow: params.workflow,
+			model: params.model,
+		},
+	});
+
+	// Surface the global continueOnError from the parsed spec (e.g. --continue-on-error=true).
+	const runner = new ChainRunner(executor, new HandoffManager());
+	const chainResult = await runner.runChain(spec, {}, undefined);
+
+	// Build a readable multi-line summary.
+	const lines: string[] = [
+		`Chain ${chainResult.success ? "completed" : "ended"}: ${spec.steps.length} step(s), ${chainResult.totalHandoffs.length} handoff(s).`,
+		"",
+	];
+	for (const s of chainResult.steps) {
+		const runId = executor.stepRunIds[s.step - 1];
+		const tag =
+			s.outcome === "success" ? "✓"
+			: s.outcome === "failure" ? "✗"
+			: s.outcome === "partial" ? "≈"
+			: "⊘";
+		lines.push(
+			`${tag} Step ${s.step} [${s.name}]: ${s.outcome} (${s.duration}ms)${runId ? ` runId=${runId}` : ""}${s.error ? ` | ${s.error}` : ""}`,
+		);
+	}
+	lines.push("");
+	lines.push(
+		`Total: ${chainResult.totalDuration}ms${chainResult.totalTokens !== undefined ? `, ${chainResult.totalTokens} tokens` : ""}`,
+	);
+
+	return result(
+		lines.join("\n"),
+		{
+			action: "run",
+			status: chainResult.success ? "ok" : "error",
+			data: {
+				chain: true,
+				steps: chainResult.steps.length,
+				totalTokens: chainResult.totalTokens,
+				runIds: executor.stepRunIds,
+			},
+		},
+		!chainResult.success,
+	);
+}