pi-messenger 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -1,6 +1,36 @@
 # Changelog
 
-## [Unreleased]
+## [0.15.0] - 2026-07-30
+
+### Added
+- Added an optional Team layer with reusable profiles, project charter/memory, role-aware tasks, approval gates, worker context, and overlay signals.
+- Added `team.setup` for first-run Team setup with profile activation, starter charter creation, and next-step guidance.
+- Surfaced rejected approval-gated tasks separately with `task.revise` / `task.revise-tree` guidance.
+
+### Fixed
+- Migrated extension tool schemas from `@sinclair/typebox` to `typebox` 1.x and updated the local test/tsconfig references to the new package entry.
+- Guarded status heartbeat updates against stale pi session contexts after reloads or session replacement while preserving non-stale errors, fixing #26, #25, and #18. Thanks to Kire Howard (`MatrixJockey`), `MartinMayday`, and Hydro (`HydroToxin`) for the reports, and to Riwut Libinuko (`cakriwut`) for #19.
+- Excluded the orchestrator-only `pi-messenger-crew` skill from worker prompts to avoid irrelevant skill loading during Crew task execution. Thanks to Varun Maliwal (`vmaliwal`) for #15.
+- Fixed auto-opened Crew overlays after planning to use the live session cwd.
+- Restored `.js` extension path handling in Crew worker and lobby tool configuration.
+- Made enum schemas load under typebox compatibility shims that do not expose `Type.Unsafe`, fixing #23. Thanks to David Moshal (`davidmoshal`) for #24.
+- Enforced `crew.concurrency.max` in overlay-driven worker spawning paths. Thanks to Martin Hátaš (`MartinHatas`) for #17.
+- Prevented the legacy `npx pi-messenger` installer from creating a duplicate extension copy when the native `pi install npm:pi-messenger` package flow is already configured, fixing #22. Thanks to David Moshal (`davidmoshal`) for the report.
+- Crew planner, worker, reviewer, analyst, lobby, and revision agents now fall back to the host session model when no task, request, role, or config model override is set, fixing #20. Thanks to Velinus (`velinussage`) for the report.
+- Crew subprocess launches use `pi.cmd` on Windows and task reset paths now refuse active workers before making tasks startable again, addressing #11. Thanks to Logan Laughlin (`llaughlin`) for the report.
+- Compacted streaming `message_update` artifacts and stopped retaining every parsed event in memory, fixing the transcript amplification in #27. Thanks to Hugo Ruíz (`hugotown`) and `aeturnal` for the measurements, and to `suse-coder` (#13) and Tom (`monotykamary`) (#4) for the earlier reports of the resulting stalls and jank.
+- Crew subprocesses now fail fast on terminal provider usage/quota/auth 4xx JSON events instead of waiting through retry loops, fixing #21. Thanks to Velinus (`velinussage`) for the report.
+
+### Changed
+- `readFeedEvents` now reads only a bounded tail of `feed.jsonl` in backward 64KB chunks instead of parsing the whole file, making overlay feed reads on large histories dramatically faster (~1,800x on a 100k-event feed). Non-positive limits now return no events.
+- Overlay rendering, auto-spawn/refill checks, and stuck-agent heartbeats now reuse a single Crew task snapshot per frame instead of rescanning the task directory per section, roughly quadrupling render-helper throughput on large task lists.
+- Aligned Team built-in roles and sample profiles with the packaged `pi-subagents` role vocabulary while keeping Crew as the execution engine.
+- Moved pi core packages and `typebox` to peer dependencies for packaged installs.
+
+## [0.14.1] - 2026-04-04
+
+### Changed
+- Added a `promptSnippet` for `pi_messenger` so Pi 0.59+ includes it in the default tool prompt section and reliably surfaces Crew/coordination workflows.
 
 ## [0.14.0] - 2026-04-03
 

package/README.md

@@ -154,6 +154,59 @@ Error responses use `{ error: { code, message, details? } }` shape.
 
 Any skills you already have in `~/.pi/agent/skills/` are automatically available to crew workers — no setup needed.
 
+### Team Layer
+
+Team is an optional layer around Crew. Crew still plans and executes tasks; Team adds project-local roles, a charter, durable memory, reusable JSON profiles, and high-risk approval gates. Active Team state lives in `.pi/messenger/team/`. Reusable profiles live in `~/.pi/agent/messenger/team-profiles/`.
+
+Most users should talk to their agent in plain language:
+
+```text
+Use the review squad for this cleanup.
+Use a migration team and pause before risky database changes.
+Research this first, then plan the implementation.
+Approve the auth API task.
+Reject the migration task; it needs rollback tests.
+```
+
+The agent maps those requests to Team actions. If a task needs approval, the agent should ask in plain language and continue after you approve. The tool calls are mainly for agents and power users:
+
+```typescript
+pi_messenger({ action: "team.setup", name: "migration-squad" })
+pi_messenger({ action: "team.memory.note", type: "decision", message: "Auth API changes require reviewer sign-off." })
+pi_messenger({ action: "team.roles" })
+pi_messenger({ action: "team.status" })
+```
+
+`team.setup` activates the profile, saves an editable JSON copy if needed, creates a starter charter when the project does not have one, and returns the next planning/status commands.
+
+When Team is active, planner task JSON may include `role` and `riskLabels`. Tasks persist those as `role`, `risk_labels`, and `approval`; existing tasks without those fields still work. Workers receive bounded Team role, charter, memory, and approval context. `work` skips tasks that require approval but are not approved and returns pending approvals under `needsApproval`; rejected tasks are surfaced separately with `task.revise` / `task.revise-tree` guidance.
+
+Team's built-in role names follow the packaged `pi-subagents` vocabulary where possible: `context-builder`, `delegate`, `oracle`, `planner`, `researcher`, `reviewer`, `scout`, and `worker`. Roles resolve from those built-in defaults, the active profile, and optional filesystem metadata from `pi-subagents` markdown files when present. `pi-messenger` only reads those files; it does not require or call the subagent extension, and Crew still uses its own Crew agents for execution.
+
+Built-in sample profiles are available immediately and are saved as editable JSON the first time you activate them:
+
+```typescript
+pi_messenger({ action: "team.setup", name: "migration-squad" }) // migrations with approval gates
+pi_messenger({ action: "team.setup", name: "review-squad" })    // scout/reviewer/worker cleanup flow
+pi_messenger({ action: "team.setup", name: "research-squad" })  // research-first planning flow
+```
+
+A saved profile looks like this:
+
+```json
+{
+  "name": "migration-squad",
+  "description": "Scout, implement, and review high-risk migrations with lead approval gates",
+  "roles": {
+    "scout": { "description": "Map affected schemas, APIs, and rollback paths before implementation" },
+    "worker": { "description": "Implement the approved migration in small, reversible steps" },
+    "reviewer": { "description": "Review migration safety, compatibility, rollback, and tests" }
+  },
+  "approval": { "mode": "risk-labels", "labels": ["database", "migration", "destructive", "api-contract"] },
+  "memory": { "inject": ["decision", "interface", "risk", "handoff"], "maxCharsPerType": 4000 }
+}
+```
+
 ### Crew Configuration
 
 Crew spawns multiple LLM sessions in parallel — it can burn tokens fast. Start with a cheap worker model and scale up once you've seen the workflow. Add this to `~/.pi/agent/pi-messenger.json`:
@@ -162,7 +215,7 @@ Crew spawns multiple LLM sessions in parallel — it can burn tokens fast. Start
 { "crew": { "models": { "worker": "claude-haiku-4-5" } } }
 ```
 
-The planner and reviewer keep their frontmatter defaults; only workers (the bulk of the spend) get the cheap model. Override per-role as needed:
+By default, Crew agents inherit the host session model unless a task, request, role, config, or agent frontmatter model says otherwise. Override per-role as needed:
 
 ```json
 {
@@ -216,10 +269,10 @@ Full config reference (all fields optional — only set what you want to change)
 | `dependencies` | Dependency scheduling mode: `advisory` or `strict` | `"advisory"` |
 | `coordination` | Worker coordination level: `none`, `minimal`, `moderate`, `chatty` | `"chatty"` |
 | `messageBudgets` | Max outgoing messages per worker per level (sends rejected after limit) | `{ none: 0, minimal: 2, moderate: 5, chatty: 10 }` |
-| `models.planner` | Model for planner agent | `anthropic/claude-opus-4-6` |
-| `models.worker` | Model for workers (overridden by per-task or per-wave `model` param) | `anthropic/claude-haiku-4-5` |
-| `models.reviewer` | Model for reviewer agent | `anthropic/claude-opus-4-6` |
-| `models.analyst` | Model for analyst (plan-sync) agent | `anthropic/claude-haiku-4-5` |
+| `models.planner` | Model for planner agent | host session model, then agent frontmatter |
+| `models.worker` | Model for workers (overridden by per-task or per-wave `model` param) | host session model, then agent frontmatter |
+| `models.reviewer` | Model for reviewer agent | host session model, then agent frontmatter |
+| `models.analyst` | Model for analyst (plan-sync) agent | host session model, then agent frontmatter |
 | `thinking.planner` | Thinking level for planner agent | (from frontmatter) |
 | `thinking.worker` | Thinking level for worker agents | (from frontmatter) |
 | `thinking.reviewer` | Thinking level for reviewer agents | (from frontmatter) |
@@ -231,10 +284,12 @@ Full config reference (all fields optional — only set what you want to change)
 | `work.maxWaves` | Max autonomous waves | `50` |
 | `work.shutdownGracePeriodMs` | Grace period before SIGTERM on abort | `30000` |
 | `work.env` | Environment variables passed to spawned workers | `{}` |
+| `artifacts.enabled` | Write compact Crew debug artifacts | `true` |
+| `artifacts.cleanupDays` | Retention setting for Crew artifacts | `7` |
 
 ### Default Agent Models
 
-Each crew agent ships with a default model in its frontmatter. Override any of these via `crew.models.<role>` in config:
+Each crew agent ships with a fallback model in its frontmatter. Override any role via `crew.models.<role>` in config:
 
 | Agent | Role | Default Model |
 |-------|------|---------------|
@@ -275,6 +330,8 @@ Agent definitions live in `crew/agents/` within the extension. To customize one
 | `task.list` | List all tasks |
 | `task.show` | Show task details (`id` required) |
 | `task.start` | Start a task (`id` required) |
+| `task.approve` | Approve an approval-gated task (`id` required) |
+| `task.reject` | Reject an approval-gated task (`id` required, `reason` optional) |
 | `task.done` | Complete a task (`id` required, `summary` optional) |
 | `task.block` | Block a task (`id` + `reason` required) |
 | `task.unblock` | Unblock a task (`id` required) |
@@ -286,6 +343,24 @@ Agent definitions live in `crew/agents/` within the extension. To customize one
 | `crew.install` | Show discovered crew agents and their sources |
 | `crew.uninstall` | Remove stale shared-directory crew agent copies |
 
+### Team
+
+| Action | Description |
+|--------|-------------|
+| `team.setup` | Activate a profile, create a starter charter if missing, and show next steps (`name` optional, defaults to `migration-squad`) |
+| `team.profile.list` | List built-in samples and saved reusable JSON team profiles |
+| `team.profile.use` | Activate a profile (`name` required; saves a sample/default profile if missing) |
+| `team.profile.save` | Save the active profile under `name` |
+| `team.charter.show` | Show the project team charter |
+| `team.charter.create` | Create or replace the charter (`name` + `message` required) |
+| `team.charter.update` | Append a charter update (`message` required) |
+| `team.memory.note` | Append team memory (`type`: `decision`, `interface`, `risk`, or `handoff`; `message` required) |
+| `team.memory.list` | List team memory (`type` and `limit` optional) |
+| `team.roles` | Resolve Team roles from packaged-vocabulary defaults, profile config, and optional subagent metadata |
+| `team.status` | Summarize team/profile/charter, roles, memory counts, and needs-lead tasks |
+
+Approval-gated tasks use the Crew task commands `task.approve` and `task.reject`. Rejected tasks stay blocked from work and are surfaced with `task.revise` / `task.revise-tree` next steps.
+
 ### Swarm (Spec-Based)
 
 | Action | Description |

package/config-overlay.ts

@@ -2,10 +2,10 @@
  * Pi Messenger - Config Overlay Component
  */
 
-import type { Component, Focusable, TUI } from "@mariozechner/pi-tui";
-import { matchesKey, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
-import type { Theme } from "@mariozechner/pi-coding-agent";
-import { getAutoRegisterPaths, saveAutoRegisterPaths, matchesAutoRegisterPath } from "./config.js";
+import type { Component, Focusable, TUI } from "@earendil-works/pi-tui";
+import { matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { getAutoRegisterPaths, saveAutoRegisterPaths, matchesAutoRegisterPath } from "./config.ts";
 
 export class MessengerConfigOverlay implements Component, Focusable {
   readonly width = 60;
@@ -19,7 +19,8 @@ export class MessengerConfigOverlay implements Component, Focusable {
   constructor(
     private tui: TUI,
     private theme: Theme,
-    private done: () => void
+    private done: () => void,
+    private cwd: string,
   ) {
     this.paths = getAutoRegisterPaths();
   }
@@ -63,12 +64,11 @@ export class MessengerConfigOverlay implements Component, Focusable {
   }
 
   private addCurrentPath(): void {
-    const cwd = process.cwd();
-    if (this.paths.includes(cwd)) {
+    if (this.paths.includes(this.cwd)) {
       this.statusMessage = "Already in list";
       return;
     }
-    this.paths.push(cwd);
+    this.paths.push(this.cwd);
     this.selectedIndex = this.paths.length - 1;
     this.dirty = true;
     this.statusMessage = "Added current folder";
@@ -88,8 +88,7 @@ export class MessengerConfigOverlay implements Component, Focusable {
     const w = this.width;
     const innerW = w - 2;
     const lines: string[] = [];
-    const cwd = process.cwd();
-    const isCurrentInList = matchesAutoRegisterPath(cwd, this.paths);
+    const isCurrentInList = matchesAutoRegisterPath(this.cwd, this.paths);
 
     const border = (s: string) => this.theme.fg("dim", s);
     const pad = (s: string, len: number) => s + " ".repeat(Math.max(0, len - visibleWidth(s)));
@@ -106,7 +105,7 @@ export class MessengerConfigOverlay implements Component, Focusable {
     lines.push(emptyRow());
 
     // Current folder status
-    const cwdDisplay = truncateToWidth(cwd, Math.max(10, innerW - 20));
+    const cwdDisplay = truncateToWidth(this.cwd, Math.max(10, innerW - 20));
     lines.push(row(`Current folder: ${cwdDisplay}`));
     const statusColor = isCurrentInList ? "accent" : "dim";
     lines.push(row(`Auto-register: ${this.theme.fg(statusColor, isCurrentInList ? "YES" : "NO")}`));
@@ -126,7 +125,7 @@ export class MessengerConfigOverlay implements Component, Focusable {
       for (let i = 0; i < this.paths.length; i++) {
         const path = this.paths[i];
         const isSelected = i === this.selectedIndex;
-        const isCurrent = path === cwd;
+        const isCurrent = path === this.cwd;
         
         const marker = isSelected ? this.theme.fg("accent", "▸") : " ";
         const suffix = isCurrent ? this.theme.fg("dim", " (current)") : "";

package/config.ts

@@ -125,8 +125,7 @@ export function getAutoRegisterPaths(): string[] {
   }
 }
 
-export function loadConfig(cwd: string): MessengerConfig {
-  const projectPath = join(cwd, ".pi", "pi-messenger.json");
+function buildConfig(projectConfig?: Partial<MessengerConfig> | null): MessengerConfig {
   const extensionGlobalPath = join(homedir(), ".pi", "agent", "pi-messenger.json");
   const mainSettingsPath = join(homedir(), ".pi", "agent", "settings.json");
 
@@ -140,9 +139,6 @@ export function loadConfig(cwd: string): MessengerConfig {
   // Load extension-specific global config
   const extensionConfig = readJsonFile(extensionGlobalPath) as Partial<MessengerConfig> | null;
 
-  // Load project config (highest priority)
-  const projectConfig = readJsonFile(projectPath) as Partial<MessengerConfig> | null;
-
   const merged = { 
     ...DEFAULT_CONFIG, 
     ...settingsConfig,
@@ -201,3 +197,13 @@ export function loadConfig(cwd: string): MessengerConfig {
     ...sharedFields,
   };
 }
+
+export function loadGlobalConfig(): MessengerConfig {
+  return buildConfig();
+}
+
+export function loadConfig(cwd: string): MessengerConfig {
+  const projectPath = join(cwd, ".pi", "pi-messenger.json");
+  const projectConfig = readJsonFile(projectPath) as Partial<MessengerConfig> | null;
+  return buildConfig(projectConfig);
+}

package/crew/agents/crew-worker.md

@@ -37,15 +37,15 @@ read({ path: ".pi/messenger/crew/tasks/<TASK_ID>.md" })
 
 ## Phase 2.5: Load Relevant Skills
 
-If your task prompt includes an **Available Skills** section, read any that match what you're building before starting implementation.
+If your task prompt includes an **Available Skills** section, read skills that match what you're building (for example a framework, testing library, or domain-specific tool) before starting implementation.
 
-If skills are marked **Recommended for this task**, read those first.
+You already have every `pi_messenger` action you need in this prompt, so do not load Crew orchestration references. If skills are marked **Recommended for this task**, read those first.
 
 ```typescript
 read({ path: "<skill-path-from-the-list>" })
 ```
 
-Skip this phase if no Available Skills section is present.
+Skip this phase if no Available Skills section is present or no skills match your implementation work.
 
 ## Phase 3: Start Task & Reserve Files
 

package/crew/agents.ts

@@ -10,28 +10,30 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import { discoverCrewAgents, type CrewAgentConfig } from "./utils/discover.js";
-import { truncateOutput } from "./utils/truncate.js";
+import { discoverCrewAgents, type CrewAgentConfig } from "./utils/discover.ts";
+import { truncateOutput } from "./utils/truncate.ts";
 import {
   createProgress,
   parseJsonlLine,
   updateProgress,
-  getFinalOutput,
+  getAssistantText,
+  compactEventForArtifact,
+  getTerminalProviderError,
   type PiEvent,
-} from "./utils/progress.js";
+} from "./utils/progress.ts";
 import {
   getArtifactPaths,
   ensureArtifactsDir,
   writeArtifact,
   writeMetadata,
   appendJsonl
-} from "./utils/artifacts.js";
-import { loadCrewConfig, getTruncationForRole, type CrewConfig } from "./utils/config.js";
-import { removeLiveWorker, updateLiveWorker } from "./live-progress.js";
-import { autonomousState, waitForConcurrencyChange } from "./state.js";
-import { registerWorker, unregisterWorker, killAll } from "./registry.js";
-import type { AgentTask, AgentResult } from "./types.js";
-import { generateMemorableName } from "../lib.js";
+} from "./utils/artifacts.ts";
+import { loadCrewConfig, getTruncationForRole, type CrewConfig } from "./utils/config.ts";
+import { removeLiveWorker, updateLiveWorker } from "./live-progress.ts";
+import { autonomousState, waitForConcurrencyChange } from "./state.ts";
+import { registerWorker, unregisterWorker, killAll } from "./registry.ts";
+import type { AgentTask, AgentResult } from "./types.ts";
+import { generateMemorableName } from "../lib.ts";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -52,10 +54,16 @@ export function shutdownAllWorkers(): void {
 export function resolveModel(
   taskModel?: string,
   paramModel?: string,
+  roleModel?: string,
   configModel?: string,
+  sessionModel?: string,
   agentModel?: string,
 ): string | undefined {
-  return taskModel ?? paramModel ?? configModel ?? agentModel;
+  return taskModel ?? paramModel ?? roleModel ?? configModel ?? sessionModel ?? agentModel;
+}
+
+export function getPiCommand(): string {
+  return process.platform === "win32" ? "pi.cmd" : "pi";
 }
 
 export function pushModelArgs(args: string[], model: string): void {
@@ -138,7 +146,7 @@ export async function spawnAgents(
   // Setup artifacts directory if enabled
   const artifactsDir = path.join(crewDir, "artifacts");
   if (config.artifacts.enabled) {
-    ensureArtifactsDir(artifactsDir);
+    ensureArtifactsDir(artifactsDir, config.artifacts.cleanupDays);
   }
 
   const results: AgentResult[] = [];
@@ -254,7 +262,7 @@ async function runAgent(
       ? { ...process.env, ...envOverrides, ...workerFlag }
       : undefined;
 
-    const proc = spawn("pi", args, {
+    const proc = spawn(getPiCommand(), args, {
       cwd,
       stdio: ["ignore", "pipe", "pipe"],
       ...(env ? { env } : {}),
@@ -266,7 +274,8 @@ async function runAgent(
     let discoveredWorkerName: string | null = null;
 
     let jsonlBuffer = "";
-    const events: PiEvent[] = [];
+    let fullOutput = "";
+    let terminalProviderError: string | null = null;
 
     proc.stdout?.on("data", (data) => {
       try {
@@ -277,12 +286,19 @@ async function runAgent(
         for (const line of lines) {
           const event = parseJsonlLine(line);
           if (event) {
-            events.push(event);
             updateProgress(progress, event, startTime);
+            const assistantText = getAssistantText(event);
+            if (assistantText) fullOutput = assistantText;
             if (artifactPaths) {
-              try { appendJsonl(artifactPaths.jsonlPath, line); }
+              try { appendJsonl(artifactPaths.jsonlPath, JSON.stringify(compactEventForArtifact(event))); }
               catch { artifactPaths = undefined; }
             }
+            const providerError = getTerminalProviderError(event);
+            if (providerError && !terminalProviderError) {
+              terminalProviderError = providerError;
+              progress.error = providerError;
+              proc.kill("SIGTERM");
+            }
             if (task.taskId) {
               updateLiveWorker(cwd, task.taskId, {
                 taskId: task.taskId,
@@ -308,11 +324,12 @@ async function runAgent(
         removeLiveWorker(cwd, task.taskId);
         unregisterWorker(cwd, task.taskId);
       }
-      progress.status = code === 0 ? "completed" : "failed";
+      const exitCode = terminalProviderError ? 1 : code ?? 1;
+      progress.status = exitCode === 0 ? "completed" : "failed";
       progress.durationMs = Date.now() - startTime;
-      if (stderr && code !== 0) progress.error = stderr;
+      if (terminalProviderError) progress.error = terminalProviderError;
+      else if (stderr && exitCode !== 0) progress.error = stderr;
 
-      const fullOutput = getFinalOutput(events);
       const truncation = truncateOutput(fullOutput, maxOutput, artifactPaths?.outputPath);
 
       if (artifactPaths) {
@@ -322,7 +339,7 @@ async function runAgent(
             runId,
             agent: task.agent,
             index,
-            exitCode: code ?? 1,
+            exitCode,
             durationMs: progress.durationMs,
             tokens: progress.tokens,
             truncated: truncation.truncated,
@@ -337,7 +354,7 @@ async function runAgent(
 
       resolve({
         agent: task.agent,
-        exitCode: code ?? 1,
+        exitCode,
         output: truncation.text,
         truncated: truncation.truncated,
         progress,

package/crew/handlers/coordination.ts

@@ -7,16 +7,21 @@
  * time — no runtime worker state.
  */
 
-import type { Task } from "../types.js";
-import type { CrewConfig } from "../utils/config.js";
-import { readFeedEvents, type FeedEvent } from "../../feed.js";
-import * as store from "../store.js";
+import type { Task } from "../types.ts";
+import type { CrewConfig } from "../utils/config.ts";
+import { readFeedEvents, type FeedEvent } from "../../feed.ts";
+import * as store from "../store.ts";
+import * as teamStore from "../team/store.ts";
+
+interface CoordinationPromptOptions {
+  readOnly?: boolean;
+}
 
 // =============================================================================
 // Dependency Section
 // =============================================================================
 
-export function buildDependencySection(cwd: string, task: Task, config: CrewConfig): string {
+export function buildDependencySection(cwd: string, task: Task, config: CrewConfig, options: CoordinationPromptOptions = {}): string {
   if (config.dependencies === "advisory") {
     const lines: string[] = [
       "## Dependency Status\n",
@@ -51,10 +56,12 @@ export function buildDependencySection(cwd: string, task: Task, config: CrewConf
     if (config.coordination !== "none") {
       lines.push("- DM in-progress workers for API details they're building.");
     }
+    if (!options.readOnly) lines.push("- Reserve your files before editing to prevent conflicts.");
     lines.push(
-      "- Reserve your files before editing to prevent conflicts.",
       "- Do NOT block yourself because a dependency isn't done. Work around it.",
-      "- Log any local definitions in your progress for later reconciliation.",
+      options.readOnly
+        ? "- Log findings, assumptions, and handoff notes in your progress for later reconciliation."
+        : "- Log any local definitions in your progress for later reconciliation.",
     );
 
     return lines.join("\n") + "\n\n";
@@ -130,6 +137,7 @@ export function buildCoordinationContext(
   task: Task,
   config: CrewConfig,
   concurrentTasks: Task[],
+  options: CoordinationPromptOptions = {},
 ): string {
   if (config.coordination === "none") return "";
 
@@ -164,17 +172,36 @@ These tasks are being worked on by other workers in this wave. Discover their ag
     const concurrentIds = new Set(concurrentTasks.map(t => t.id));
     const ready = store.getReadyTasks(cwd, { advisory: config.dependencies === "advisory" })
       .filter(t => t.id !== task.id && !concurrentIds.has(t.id));
-    if (ready.length > 0) {
+    const claimable = ready.filter(t => !teamStore.taskNeedsApproval(t));
+    const needsApproval = ready.filter(teamStore.taskPendingApproval);
+    const rejected = ready.filter(teamStore.taskNeedsRevision);
+    if (claimable.length > 0) {
       out += `## Ready Tasks
 
-After completing your current task, you can claim one of these:
+${options.readOnly ? "After completing your current task, only claim one of these if it fits your read-only assignment:" : "After completing your current task, you can claim one of these:"}
 `;
-      for (const t of ready) {
+      for (const t of claimable) {
         const deps = t.depends_on.length > 0 ? ` (deps: ${t.depends_on.join(", ")})` : "";
         out += `- ${t.id}: ${t.title}${deps}\n`;
       }
       out += "\n";
     }
+    if (needsApproval.length > 0) {
+      out += `## Ready Tasks Needing Approval
+
+These tasks are ready but require lead approval before anyone can claim them:
+`;
+      for (const t of needsApproval) out += `- ${t.id}: ${t.title} — approve with \`pi_messenger({ action: "task.approve", id: "${t.id}" })\`\n`;
+      out += "\n";
+    }
+    if (rejected.length > 0) {
+      out += `## Rejected Tasks Needing Revision
+
+These tasks need revision before they can be approved or claimed:
+`;
+      for (const t of rejected) out += `- ${t.id}: ${t.title}${t.approval?.feedback ? ` — ${t.approval.feedback}` : ""} — revise with \`pi_messenger({ action: "task.revise", id: "${t.id}", prompt: "Address approval feedback" })\`\n`;
+      out += "\n";
+    }
   }
 
   return out;
@@ -184,13 +211,23 @@ After completing your current task, you can claim one of these:
 // Coordination Instructions
 // =============================================================================
 
-export function buildCoordinationInstructions(config: CrewConfig): string {
+export function buildCoordinationInstructions(config: CrewConfig, options: CoordinationPromptOptions = {}): string {
   const level = config.coordination;
   if (level === "none") return "";
 
   const budget = config.messageBudgets?.[level] ?? (level === "chatty" ? 10 : 5);
 
   if (level === "minimal") {
+    if (options.readOnly) {
+      return `## Coordination
+
+**Message budget: ${budget} messages this session.** The system enforces this.
+
+Use \`pi_messenger({ action: "list" })\` to see active workers if your investigation overlaps with their work. Message a worker only when you need concrete context or a handoff detail.
+
+`;
+    }
+
     return `## Coordination
 
 **Message budget: ${budget} messages this session.** The system enforces this.
@@ -220,7 +257,16 @@ Do NOT edit files reserved by another worker without coordinating first.
 
 `;
 
-  out += `### Announce yourself
+  out += options.readOnly
+    ? `### Announce yourself
+After joining the mesh and starting your task, announce what you are investigating:
+
+\`\`\`typescript
+pi_messenger({ action: "broadcast", message: "Starting <task-id> (<title>) — investigating <scope>" })
+\`\`\`
+
+`
+    : `### Announce yourself
 After joining the mesh and starting your task, announce what you're working on:
 
 \`\`\`typescript
@@ -243,7 +289,16 @@ If a peer asks you a direct question, reply briefly. Ignore messages that don't
 `;
   }
 
-  out += `### On completion
+  out += options.readOnly
+    ? `### On completion
+Announce what you found or recommend:
+
+\`\`\`typescript
+pi_messenger({ action: "broadcast", message: "Completed <task-id>: found <summary>" })
+\`\`\`
+
+`
+    : `### On completion
 Announce what you built:
 
 \`\`\`typescript
@@ -253,7 +308,9 @@ pi_messenger({ action: "broadcast", message: "Completed <task-id>: <file> export
 ### Reservations
 Before editing files, check if another worker has reserved them via \`pi_messenger({ action: "list" })\`. If a file you need is reserved, message the owner to coordinate. Do NOT edit reserved files without coordinating first.
 
-### Questions about dependencies
+`;
+
+  out += `### Questions about dependencies
 If your task depends on a completed task and something about its implementation is unclear, read the code and the task's progress log at \`.pi/messenger/crew/tasks/<task-id>.progress.md\`. Dependency authors are from previous waves and are no longer in the mesh.
 
 `;
@@ -266,7 +323,7 @@ After completing your assigned task, check if there are ready tasks you can pick
 pi_messenger({ action: "task.ready" })
 \`\`\`
 
-If a task is ready, claim and implement it. If \`task.start\` fails (another worker claimed it first), check for other ready tasks. Only claim if your current task completed cleanly and quickly.
+If a task is ready, claim it only if it matches your assignment mode. If \`task.start\` fails (another worker claimed it first or the task needs approval), check for other ready tasks. Only claim if your current task completed cleanly and quickly.
 
 `;
   }