taskplane 0.28.7 → 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

@@ -3,7 +3,7 @@
  * @module orch/worktree
  */
 import { existsSync, mkdirSync, readdirSync, realpathSync, rmdirSync, rmSync } from "fs";
-import { execSync } from "child_process";
+import { execSync, execFileSync } from "child_process";
 import { join, basename, resolve } from "path";
 
 import { execLog } from "./execution.ts";
@@ -639,6 +639,57 @@ export function isRetriableRemoveError(stderr: string): boolean {
 	return false;
 }
 
+/**
+ * Detect Windows MAX_PATH ("Filename too long") errors from `git worktree remove`.
+ *
+ * On Windows with default `core.longpaths = false`, git refuses to delete
+ * paths that exceed MAX_PATH (260 characters). Deep `node_modules` trees
+ * commonly trip this. Native `cmd` `rd /s /q` uses a different deletion
+ * code path (NT object namespace, longer path tolerance) and usually
+ * succeeds where git fails.
+ *
+ * @param stderr - Error output from `git worktree remove`
+ * @returns true if the failure looks like the Windows MAX_PATH case
+ * @since TP-188 (#543)
+ */
+export function isWindowsMaxPathError(stderr: string): boolean {
+	if (process.platform !== "win32") return false;
+	return /filename too long/i.test(stderr);
+}
+
+/**
+ * Run `cmd /c rd /s /q <path>` to recursively delete a directory on Windows.
+ *
+ * Used as a fallback after `git worktree remove` fails with the Windows
+ * MAX_PATH ("Filename too long") error. Caller must ensure platform is win32
+ * and the path is absolute. Path separators are normalized to backslashes
+ * because cmd's `rd` is more reliable with native Windows paths.
+ *
+ * @param absolutePath - Absolute path to remove (forward or back slashes accepted)
+ * @returns { ok, stdout, stderr }
+ * @since TP-188 (#543)
+ */
+export function runWindowsCmdRd(
+	absolutePath: string,
+): { ok: boolean; stdout: string; stderr: string } {
+	const winPath = absolutePath.replace(/\//g, "\\");
+	try {
+		const stdout = execFileSync("cmd", ["/c", "rd", "/s", "/q", winPath], {
+			encoding: "utf-8",
+			timeout: 60_000,
+			stdio: ["pipe", "pipe", "pipe"],
+		}).toString().trim();
+		return { ok: true, stdout, stderr: "" };
+	} catch (err: unknown) {
+		const e = err as { stdout?: string; stderr?: string; message?: string };
+		return {
+			ok: false,
+			stdout: (e.stdout ?? "").toString().trim(),
+			stderr: (e.stderr ?? e.message ?? "unknown error").toString().trim(),
+		};
+	}
+}
+
 /**
  * Remove a git worktree and clean up its associated branch.
  *
@@ -733,6 +784,50 @@ export function removeWorktree(
 
 		lastError = removeResult.stderr;
 
+		// ── Windows MAX_PATH fallback (#543) ────────────────────────
+		// On Windows, `git worktree remove` fails with "Filename too long"
+		// when the worktree contains deep `node_modules` trees (most
+		// non-trivial Node projects) and `core.longpaths = false` (default).
+		// `cmd /c rd /s /q <path>` uses a different deletion code path
+		// that tolerates long paths better. Try it ONCE before classifying
+		// the error as terminal/retriable so other error classes still
+		// surface unchanged.
+		if (isWindowsMaxPathError(lastError)) {
+			execLog(
+				"cleanup",
+				"worktree",
+				`Windows MAX_PATH detected — falling back to cmd "rd /s /q"`,
+				{ path: worktreePath, attempt },
+			);
+			const fallback = runWindowsCmdRd(worktreePath);
+			if (fallback.ok) {
+				execLog(
+					"cleanup",
+					"worktree",
+					`cmd "rd /s /q" fallback succeeded; pruning git worktree state`,
+					{ path: worktreePath },
+				);
+				// The on-disk tree is gone; git's bookkeeping still has a
+				// stale entry. Prune so isRegisteredWorktree() returns false
+				// during post-removal verification below.
+				runGit(["worktree", "prune"], repoRoot);
+				break;
+			}
+			// Fallback also failed — enrich error so the operator sees both
+			// attempts, then fall through to the existing terminal/retry
+			// classification (which will throw because "Filename too long"
+			// is non-retriable per isRetriableRemoveError).
+			execLog(
+				"cleanup",
+				"worktree",
+				`cmd "rd /s /q" fallback failed`,
+				{ path: worktreePath, error: fallback.stderr.slice(0, 200) },
+			);
+			lastError =
+				`git worktree remove failed: ${lastError}; ` +
+				`cmd rd /s /q fallback failed: ${fallback.stderr}`;
+		}
+
 		// Check if error is terminal (non-retriable)
 		if (!isRetriableRemoveError(lastError)) {
 			throw new WorktreeError(
@@ -1806,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.7",
+  "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-reviewer.md

@@ -50,6 +50,74 @@ You handle a single review request and then exit.
 Do NOT just respond with text — the orchestrator reads the OUTPUT FILE to get
 your verdict. If you don't write the file, your review is lost.
 
+## Quality-check verification (code reviews only)
+
+**This section applies to code reviews only.** For plan reviews, skip this
+section entirely — there is no code to type-check or lint yet.
+
+Before returning a code-review verdict, run the project's declared
+typecheck / lint / format-check commands against the post-change tree. A
+behavioural-correctness APPROVE is **invalidated** by failing quality checks.
+
+The reviewer's tool allowlist already includes `bash`, so you can invoke these
+commands directly — no special tooling is required.
+
+### How to discover the commands
+
+1. **Project config first.** Read `.pi/taskplane-config.json` (or the legacy
+   `.pi/task-runner.yaml` / `.pi/task-runner.json` fallbacks) and look at
+   `taskRunner.testing.commands` — a `Record<string, string>` mapping a
+   command name (e.g. `typecheck`, `lint`, `format:check`) to a
+   shell command. Run any command whose key matches one of
+   `typecheck` / `tsc` / `types` / `lint` / `format:check`.
+   **Prefer `format:check` over `format`** — the latter typically rewrites
+   files in place, which would mutate the working tree the reviewer is
+   evaluating. If only a mutating `format` script is available in either
+   source, skip it and note this in the Summary; do not run mutating
+   commands from the reviewer.
+2. **Fallback to `package.json` scripts.** If step 1 did not yield any
+   relevant commands — either because `taskRunner.testing.commands` is
+   absent OR because it exists but contains no keys matching the
+   typecheck/lint/format-check set — read `package.json` and run any of
+   these scripts that exist, in this order:
+   `npm run typecheck`, `npm run lint`, `npm run format:check`.
+   Skip a script if `package.json#scripts` does not declare it — do not
+   invent commands.
+3. **Skip silently** if neither source yields a relevant command. Do not fail
+   the review just because the project has no quality-check pipeline
+   configured. Note this in the Summary so the operator knows quality checks
+   were not exercised.
+
+Do NOT run the project's full test suite from this section — that is the
+worker's Testing & Verification step. The quality checks here are
+**fast static checks** (typecheck, lint, format) that are cheap to run and
+high-signal for catching regressions the behavioural diff review would miss.
+
+### What to do with the results
+
+- **All quality checks pass** → proceed to behavioural code review as normal.
+- **A quality check fails** → surface each failing command as an entry in
+  **Issues Found** with severity `important`. Include:
+  - The command that failed (e.g. `npm run typecheck`)
+  - The first few lines of the failing output (file/line locations are
+    most useful)
+  - A concrete suggested fix where the failure makes one obvious
+- **Verdict downgrade rule:** If quality checks fail, the verdict is
+  **REVISE** — even if the behavioural code review would otherwise have
+  been APPROVE. Quality-check failures are blocking by definition: they
+  would surface at the worker's Testing & Verification step and force a
+  redo of the entire review cycle, so it is strictly cheaper to surface
+  them here.
+
+### Worked example (Issues Found entry)
+
+```
+1. **[npm run typecheck:1] [important]** — 5 strict-mode errors in
+   tests/foo.test.ts. Sample: "Argument of type 'undefined' is not
+   assignable to parameter of type 'string'" at line 42. Fix: narrow
+   `getThing()` return type or assert non-null at call site.
+```
+
 ## Verdict Criteria
 
 - **APPROVE** — Step will achieve its stated outcomes. Minor suggestions belong

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