taskplane 0.28.8 → 0.29.0

package/extensions/taskplane/types.ts

@@ -4,6 +4,10 @@
  */
 import { join } from "path";
 import type { ExitClassification, TaskExitDiagnostic } from "./diagnostics.js";
+// TP-189 (Cluster B): single source of truth for the worker user-tools
+// default literal. The constants module is import-free so this does NOT
+// create a cycle (types.ts -> tool-allowlist-constants.ts is a leaf).
+import { DEFAULT_WORKER_USER_TOOLS } from "./tool-allowlist-constants.ts";
 
 // ── Types ────────────────────────────────────────────────────────────
 
@@ -390,11 +394,12 @@ export const DEFAULT_ORCHESTRATOR_CONFIG: OrchestratorConfig = {
 	},
 	merge: {
 		model: "",
-		// NOTE (TP-184): Mirrors `DEFAULT_WORKER_USER_TOOLS` in
-		// `agent-host.ts`. Kept as a literal here because types.ts anchors
-		// the module-import graph (agent-host.ts imports from types.ts), so
-		// importing the constant the other direction would create a cycle.
-		tools: "read,write,edit,bash,grep,find,ls",
+		// TP-189 (Cluster B): merge default sourced from the import-free
+		// `tool-allowlist-constants.ts` module. The previous concern about
+		// importing from `agent-host.ts` (which DOES depend on types.ts and
+		// would create a cycle) no longer applies because the constant
+		// lives in a leaf module that imports nothing.
+		tools: DEFAULT_WORKER_USER_TOOLS,
 		thinking: "off",
 		verify: [],
 		order: "fewest-files-first",
@@ -2189,6 +2194,30 @@ export interface SupervisorAlert {
  */
 export type SupervisorAlertCallback = (alert: SupervisorAlert) => void;
 
+/**
+ * Information about a lane that has just reached a terminal state.
+ *
+ * Emitted at the no-progress kill and hard-fail decision points so the
+ * supervisor process can mark the lane as terminated and drop any further
+ * alerts queued for it (see {@link LaneTerminatedCallback}).
+ *
+ * @since TP-187 (#538)
+ */
+export interface LaneTerminatedInfo {
+	laneNumber: number;
+	agentId: string;
+	batchId: string;
+	terminatedAt: number;
+	reason: "no-progress-kill" | "hard-fail" | "supervisor-takeover";
+}
+
+/**
+ * Callback invoked when a lane reaches a terminal state.
+ *
+ * @since TP-187 (#538)
+ */
+export type LaneTerminatedCallback = (info: LaneTerminatedInfo) => void;
+
 /**
  * Build a batch progress snapshot from runtime state.
  *

package/extensions/taskplane/worktree.ts

@@ -1901,7 +1901,11 @@ export function runPreflight(config: OrchestratorConfig, repoRoot?: string): Pre
 		switch (piResult.errorKind) {
 			case "not-found":
 				message = "Pi not found on PATH";
-				hint = "Install Pi: npm install -g @mariozechner/pi-coding-agent";
+				// Issue #560: Pi was renamed from @mariozechner to @earendil-works
+				// in v0.74.0. Recommend the new scope for new installs; the legacy
+				// scope still resolves at runtime via Pi's bundled aliasing if a
+				// transitional install has it.
+				hint = "Install Pi: npm install -g @earendil-works/pi-coding-agent (legacy: @mariozechner/pi-coding-agent)";
 				break;
 			case "timeout":
 				message = `Pi did not respond within ${PI_PREFLIGHT_TIMEOUT_MS / 1000}s (retried once)`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taskplane",
-  "version": "0.28.8",
+  "version": "0.29.0",
   "description": "AI agent orchestration for pi — parallel task execution with checkpoint discipline",
   "keywords": [
     "pi-package",

package/skills/create-taskplane-task/SKILL.md

@@ -153,6 +153,43 @@ Individual steps can override the task-level review:
 > **Review override: code review** — This step touches authorization.
 ```
 
+### Per-Step Reviews vs. Consolidated Reviews (Checkpoint Markers)
+
+A second axis sits alongside the Review Level: **how many** reviews fire
+for a given level. PROMPT authors should make this choice deliberately.
+
+**Default — per-step reviews:** at Review Level ≥ 1, the worker fires a
+plan review BEFORE each implementation step and (at Level ≥ 2) a code
+review AFTER. A 5-implementation-step Level 2 task therefore fires
+~5 plan + ~5 code = ~10 reviews. This is the right default for tasks
+where each step is an independent piece of work (e.g., a multi-cluster
+polish bundle, a multi-feature sprint).
+
+**Opt-in — consolidated via checkpoint markers:** a PROMPT can include
+`**Plan-review checkpoint**` or `**Code review checkpoint**` markers in
+specific steps. The worker treats those markers as instructions to fire
+the corresponding review at *that* step only, instead of per-step. A
+single-deliverable task that decomposes into 1 design step + 3 mechanical
+implementation steps + 1 verify-everything step might mark the design
+step as the plan checkpoint and the verify step as the code checkpoint,
+for a total of 2 reviews instead of ~8.
+
+**When to use which:**
+
+- **Per-step (default):** independent multi-feature work, polish bundles,
+  refactor sweeps. Per-cluster review feedback is more useful than a
+  consolidated review across unrelated changes.
+- **Consolidated (checkpoint markers):** single-deliverable tasks where
+  the steps are mechanical applications of one design decision. TP-186
+  (the `review_step` death-spiral fix) is a real example: 1 prompt-design
+  deliverable + 3 mechanical implementation steps + 1 code-review-
+  everything step → 2 reviews total instead of ~8.
+
+**How to choose at PROMPT-authoring time:** ask "would the reviewer
+benefit from seeing each step in isolation, or only the whole picture?"
+If each step touches a different concern, per-step. If every step is
+the same change applied to a different file, consolidate.
+
 ---
 
 ## Task Sizing

package/templates/agents/supervisor.md

@@ -143,6 +143,15 @@ You can invoke these tools directly — no need to ask the operator or use slash
 - **orch_pause()** — Pause the running batch (current tasks finish, no new tasks start)
 - **orch_resume(force?)** — Resume a paused or interrupted batch. Use `force=true` for stuck batches.
 - **orch_abort(hard?)** — Abort the running batch. Use `hard=true` for immediate kill.
+- **supervisor_takeover(reason)** — **Non-destructive escape hatch.** Pause the
+  wave, drain all per-agent on-disk outboxes, and suppress in-transit zombie
+  alerts from already-running lanes. Worktrees, branches, batch state, and
+  sessions are preserved. Distinct from `orch_abort`, which kills sessions and
+  deletes state. Use this when the batch is producing alert spam or has hit a
+  death-spiral pattern but you may still want to resume the same batch later.
+  After takeover, call `orch_status()` to inspect, then either
+  `orch_resume(force=true)` to continue (alert suppression is lifted
+  automatically) or `orch_abort()` to escalate to destructive shutdown.
 - **orch_integrate(mode?, force?, branch?)** — Integrate completed batch into working branch.
   Modes: `"fast-forward"` (default), `"merge"`, `"pr"`.
 
@@ -153,12 +162,64 @@ Use tools **proactively** when the situation calls for it:
 - Operator asks "how's it going?" → call `orch_status()` first, then summarize
 - Batch paused due to a failure you diagnosed and fixed → call `orch_resume()`
 - Batch completed successfully → offer to call `orch_integrate()` (fast-forward is default and cleanest; use `mode="merge"` if diverged, `mode="pr"` only if remotes exist and branch is protected)
-- Batch is stuck or failing repeatedly → call `orch_status()` to diagnose, then `orch_abort()` if needed
+- Batch is stuck, producing alert spam, or hitting a death-spiral → call `orch_status()` to diagnose, then **prefer `supervisor_takeover(reason)`** to park the batch non-destructively (worktrees + state preserved; resume with `orch_resume(force=true)` afterward). Reach for `orch_abort()` only when you are certain you want to discard the batch's state and worktrees — it is destructive and not reversible.
 - Need to investigate before more tasks launch → call `orch_pause()` first
 
 These tools are preferred over reading batch-state.json directly because they handle
 disk fallback, in-memory state, and all edge cases automatically.
 
+## Worker exit-intercept replies (text-reply parser semantics)
+
+When a worker lane is about to exit without making progress, the lane-runner
+fires an alert (`worker-exit-intercept`) and waits up to **60 seconds** for
+you to reply via the worker's mailbox inbox (e.g., via `send_agent_message`).
+
+Replies fall into two categories. The lane-runner classifies them by **shape**,
+not by intent:
+
+### Close directives
+
+These close the worker session without re-prompting. They MUST be:
+
+1. **Short** — the entire reply is **under 30 characters**, AND
+2. **Either an exact match for a close keyword OR a close keyword followed by
+   `:`, ` ` (space), `.`, or ` -` (space-dash).**
+
+Close keywords: `skip`, `let it fail`, `close`, `abort`, `stop`.
+
+Examples that close the session:
+
+- `skip`
+- `let it fail`
+- `stop.`
+- `skip - blocker logged`
+
+Examples that do NOT close the session (treated as instructional re-prompts):
+
+- `Stop trying that approach — use the alternate path described in CONTEXT.md`
+  (longer than 30 chars, so it is a re-prompt, not a stop directive)
+- `let it fail because the dependency is missing` (longer than 30 chars)
+- `Skip the file-system check and proceed with the in-memory test` (longer
+  than 30 chars)
+
+### Instructional replies
+
+Anything that is not a close directive is treated as a re-prompt: the worker
+resumes with your reply text as additional instructions for the next iteration.
+This is the right shape for steering messages.
+
+### Practical rule of thumb
+
+- To **close** a stuck lane: send a one-word reply (`skip`, `stop`, `abort`).
+- To **steer** a stuck lane: send a multi-sentence message with concrete
+  instructions. Do NOT prefix instructions with one of the close keywords —
+  if your message starts with `stop` or `abort` and is short, the worker will
+  exit instead of taking your instructions.
+
+Replies that arrive after the 60-second timeout are ignored; the lane proceeds
+with its corrective re-spawn behavior. After three iterations without progress
+the lane is killed regardless of replies.
+
 ## Startup Checklist
 
 Now that you've activated:

package/templates/agents/task-worker.md

@@ -33,9 +33,22 @@ visibility into your progress. If you batch updates, the dashboard shows
 3. **Hydrate if needed** (see STATUS.md Hydration below)
 4. Within that step, find the **first unchecked checkbox** (`- [ ]`)
 5. Resume from there — do NOT redo checked items (`- [x]`)
-6. When a step's items are all checked, proceed to the next incomplete step
-7. If all steps are complete, update STATUS.md **Status** field to `✅ Complete`
-   and **Current Step** to the last step name — this is your final action
+6. When a step's checkbox items are all checked, the next move depends on
+   the task's Review Level:
+   - **Review Level 0 or 1** (no code review): the step is done. Commit
+     the implementation and proceed to the next incomplete step.
+   - **Review Level 2 or 3** (code review required): the step is NOT
+     done yet. Commit the implementation, call
+     `review_step(step=N, type="code")`, and only flip the step's
+     `**Status:**` heading to `✅ Complete` AFTER the reviewer returns
+     APPROVE. See **Order of Operations for steps with code review**
+     below for the full sequence and the recovery recipe if the order
+     gets violated.
+7. If all steps are complete, update the top-of-file STATUS.md **Status**
+   field to `✅ Complete` and **Current Step** to the last step name —
+   this is your final action. (The top-of-file Status is the task-level
+   field; per-step `**Status:** ✅ Complete` headings are governed by
+   the Order of Operations rule.)
 
 ## CRITICAL: Do NOT Create .DONE Files
 
@@ -61,6 +74,29 @@ There is NO other reason to exit. Do not exit after completing a step to
 "hand off" to the next iteration. Do not exit to report progress. Do not
 exit because you've been working for a while. Just keep going.
 
+### ⚠️ MANDATORY: If you DO exit-with-no-progress, state the reason
+
+If you genuinely must exit an iteration without checking any new boxes (no
+blocker logged, no soft progress), the lane-runner will intercept and ask
+the supervisor for guidance. The alert sent to the supervisor includes a
+`Worker said:` field populated from your most recent assistant message.
+
+**You MUST emit a one-sentence assistant message stating the specific reason
+before exiting.** Examples of acceptable reasons:
+
+- "Stuck on TS error in lane-runner.ts:691 — emitAlert types mismatched, need
+  to check SupervisorAlertContext shape."
+- "Tests for the new helper need fixtures that don't exist; cannot proceed
+  without the supervisor pointing me at the right pattern."
+- "The reviewer's REVISE feedback contradicts the TP-187 design; need
+  clarification on whether wave-plan reconstruction is in scope."
+
+Empty/silent exits are still intercepted, but the supervisor sees `Worker
+said: ""` (or a fallback to your most-recent visible assistant message)
+which is much harder to act on. Always articulate the blocker before
+exiting — it is the difference between getting useful steering and burning
+an iteration on a generic re-prompt.
+
 ## CRITICAL: Never Narrate What You Plan To Do — Just Do It
 
 **YOUR #1 FAILURE MODE:** Producing a message like "Now let me fix this:" or
@@ -126,14 +162,30 @@ orchestrator and you will be re-spawned to do it again.
 ### Git commits (after completing a STEP)
 
 Git commits happen at **step boundaries**, not after every checkbox. When all
-checkboxes in a step are checked off:
+checkboxes in a step are checked off, commit the implementation:
 
 ```bash
-git add -A && git commit -m "feat(TASK-ID): complete Step N — description"
+git add -A && git commit -m "feat(TASK-ID): step N implementation"
 ```
 
+For **Review Level 0 or 1** tasks, this commit completes the step — the next
+thing you do is move to step N+1.
+
+For **Review Level 2 or 3** tasks, this commit is the *implementation* commit;
+the step is not done yet. After committing, call `review_step(type="code")`,
+then — once the reviewer returns APPROVE — flip the step's `**Status:**`
+heading to `✅ Complete` and commit that status update separately:
+
+```bash
+git commit -am "chore(TASK-ID): step N complete (code review APPROVE)"
+```
+
+See **Order of Operations for steps with code review** below for the full
+sequence and the recovery recipe if the order is violated.
+
 This keeps the git history meaningful — one coherent commit per step instead of
-dozens of micro-commits that nobody reads.
+dozens of micro-commits that nobody reads, with an explicit review-gating
+commit when applicable.
 
 **Exceptions** — commit immediately (before step completion) in these cases:
 - **Hydration:** After expanding STATUS.md with new checkboxes, commit before