taskplane 0.22.10 → 0.22.12

package/extensions/taskplane/types.ts

@@ -98,6 +98,26 @@ export interface ParsedTask {
 	resolvedRepoId?: string;
 	/** Optional explicit segment DAG metadata from `## Segment DAG`. */
 	explicitSegmentDag?: PromptSegmentDagMetadata;
+	/**
+	 * Repo ID that owns task packet files (v4, TP-081).
+	 * Populated by execution engine in workspace mode. Undefined in repo mode.
+	 */
+	packetRepoId?: string;
+	/**
+	 * Absolute path to task folder in the packet repo worktree (v4, TP-081).
+	 * Populated by execution engine. Undefined if not yet resolved.
+	 */
+	packetTaskPath?: string;
+	/**
+	 * Segment IDs for this task (v4, TP-081).
+	 * Populated from TaskSegmentPlan during execution.
+	 */
+	segmentIds?: string[];
+	/**
+	 * Currently active segment ID (v4, TP-081).
+	 * Null when no segment is active.
+	 */
+	activeSegmentId?: string | null;
 }
 
 /** Build a stable segment ID from task + repo identity (`<taskId>::<repoId>`). */
@@ -205,7 +225,7 @@ export interface TaskArea {
 export interface TaskRunnerConfig {
 	task_areas: Record<string, TaskArea>;
 	reference_docs: Record<string, string>;
-	/** Named testing/verification commands (e.g., { test: "npx vitest run" }). Used for baseline fingerprinting (TP-032). */
+	/** Named testing/verification commands (e.g., { test: "node --test tests/*.test.ts" }). Used for baseline fingerprinting (TP-032). */
 	testing_commands?: Record<string, string>;
 	/**
 	 * Model fallback behavior when a configured model becomes unavailable mid-batch.
@@ -1015,6 +1035,12 @@ export interface OrchBatchRuntimeState {
 	 * Populated from persisted state on resume; defaults used for new batches.
 	 */
 	diagnostics?: BatchDiagnostics;
+	/**
+	 * v4 segment records carried forward across resume cycles (TP-081).
+	 * Populated from persisted state on resume; empty for new batches
+	 * and repo-mode batches.
+	 */
+	segments?: PersistedSegmentRecord[];
 	/**
 	 * Unknown top-level fields from loaded persisted state.
 	 * Carried forward so they survive serialization roundtrips.
@@ -2304,15 +2330,22 @@ export function defaultBatchDiagnostics(): BatchDiagnostics {
  *         exit summaries, batch cost). Task records gain optional
  *         `exitDiagnostic` alongside legacy `exitReason`.
  *         Both new sections are optional for v1/v2 migration paths.
+ *   v4 — Segment execution (TP-081). Adds optional `segments` array
+ *         for persisting per-segment runtime state. Task records gain
+ *         optional `packetRepoId`, `packetTaskPath`, `segmentIds`, and
+ *         `activeSegmentId` fields. All v4-specific fields are optional
+ *         for backward compatibility with v1/v2/v3 migration paths.
+ *         When migrating from v3, `segments` defaults to `[]` and
+ *         task-level segment fields default to `undefined`.
  *
  * Compatibility policy:
- *   - loadBatchState() accepts v1, v2, and v3 files. v1 and v2 are
- *     auto-upconverted to v3 in memory (chained: v1→v2→v3).
+ *   - loadBatchState() accepts v1, v2, v3, and v4 files. v1→v2→v3→v4
+ *     auto-upconverted in memory (chained).
  *     The on-disk file is NOT rewritten during load.
- *   - saveBatchState() always writes v3.
- *   - Schema versions > 3 are rejected with STATE_SCHEMA_INVALID.
+ *   - saveBatchState() always writes v4.
+ *   - Schema versions > 4 are rejected with STATE_SCHEMA_INVALID.
  */
-export const BATCH_STATE_SCHEMA_VERSION = 3;
+export const BATCH_STATE_SCHEMA_VERSION = 4;
 
 /**
  * Canonical file path for persisted batch state.
@@ -2431,6 +2464,99 @@ export interface PersistedTaskRecord {
 	 * falling back to `exitReason` for display.
 	 */
 	exitDiagnostic?: TaskExitDiagnostic;
+	/**
+	 * Repo ID that owns task packet files (PROMPT.md/STATUS.md/.DONE) (v4, TP-081).
+	 *
+	 * In workspace mode, this is the `taskPacketRepo` from routing config.
+	 * Undefined in repo mode or for pre-v4 state files.
+	 */
+	packetRepoId?: string;
+	/**
+	 * Absolute path to the task folder in the packet repo worktree (v4, TP-081).
+	 *
+	 * Used by resume to locate packet files without re-running discovery.
+	 * Undefined in repo mode or for pre-v4 state files.
+	 */
+	packetTaskPath?: string;
+	/**
+	 * Segment IDs belonging to this task (v4, TP-081).
+	 *
+	 * Array of segment ID strings (`<taskId>::<repoId>`).
+	 * Empty array for repo-mode tasks or single-repo tasks.
+	 * Undefined for pre-v4 state files.
+	 */
+	segmentIds?: string[];
+	/**
+	 * Currently executing segment ID (v4, TP-081).
+	 *
+	 * Null when no segment is active (all completed or not started).
+	 * Undefined for pre-v4 state files.
+	 */
+	activeSegmentId?: string | null;
+}
+
+// ── Segment-Level Persisted State (v4, TP-081) ──────────────────────
+
+/**
+ * Segment execution status within a batch.
+ *
+ * State machine mirrors `LaneTaskStatus` but applies at segment granularity:
+ *   pending → running → succeeded
+ *                     → failed
+ *                     → stalled
+ *   pending → skipped  (prior segment failed, or task skipped)
+ *
+ * @since v4 (TP-081)
+ */
+export type PersistedSegmentStatus = "pending" | "running" | "succeeded" | "failed" | "stalled" | "skipped";
+
+/**
+ * Persisted record of a single segment's execution state.
+ *
+ * A segment is a repo-scoped execution unit within a task. Each task
+ * may have one or more segments (one per repo the task touches).
+ *
+ * Contains everything `/orch-resume` needs to reconstruct segment-level
+ * progress without re-running discovery.
+ *
+ * @since v4 (TP-081)
+ */
+export interface PersistedSegmentRecord {
+	/** Stable segment identifier (`<taskId>::<repoId>`, e.g., "TP-002::api") */
+	segmentId: string;
+	/** Parent task identifier */
+	taskId: string;
+	/** Repo ID this segment targets */
+	repoId: string;
+	/** Segment execution status */
+	status: PersistedSegmentStatus;
+	/** Lane ID the segment executed on (e.g., "lane-1"), empty if not yet assigned */
+	laneId: string;
+	/** TMUX session name used for this segment */
+	sessionName: string;
+	/** Absolute path to the worktree used for this segment */
+	worktreePath: string;
+	/** Git branch name checked out for this segment */
+	branch: string;
+	/** Epoch ms when segment execution started (null if not yet started) */
+	startedAt: number | null;
+	/** Epoch ms when segment execution ended (null if still pending/running) */
+	endedAt: number | null;
+	/** Number of retry attempts for this segment */
+	retries: number;
+	/**
+	 * Segment IDs this segment depends on (intra-task DAG edges).
+	 * Empty array for the first segment in a task or for tasks with no intra-task deps.
+	 */
+	dependsOnSegmentIds: string[];
+	/**
+	 * Structured exit diagnostic for this segment.
+	 * Optional: absent for segments that haven't exited yet.
+	 * Uses the same `TaskExitDiagnostic` shape from diagnostics.ts.
+	 */
+	exitDiagnostic?: TaskExitDiagnostic;
+	/** Human-readable exit reason (legacy compat, same as task-level) */
+	exitReason: string;
 }
 
 /**
@@ -2545,9 +2671,17 @@ export interface PersistedRepoMergeOutcome {
  *   data alongside legacy `exitReason` string).
  * - Both sections are required in v3. Migration from v1/v2 fills
  *   conservative defaults (see `defaultResilienceState()` / `defaultBatchDiagnostics()`).
+ *
+ * v4 additions (TP-081):
+ * - `segments` array (required): per-segment execution records for multi-repo
+ *   task execution. Empty array in repo mode or for pre-v4 migration.
+ * - Task records gain optional `packetRepoId`, `packetTaskPath`, `segmentIds`,
+ *   and `activeSegmentId` for segment-level tracking.
+ * - Migration from v3 fills `segments` as `[]` and leaves task-level segment
+ *   fields as `undefined`.
  */
 export interface PersistedBatchState {
-	/** Schema version — must equal BATCH_STATE_SCHEMA_VERSION (currently 3) */
+	/** Schema version — must equal BATCH_STATE_SCHEMA_VERSION (currently 4) */
 	schemaVersion: number;
 	/** Current batch execution phase */
 	phase: OrchBatchPhase;
@@ -2596,14 +2730,24 @@ export interface PersistedBatchState {
 	errors: string[];
 	/**
 	 * Resilience state for retry/recovery tracking (v3, TP-030).
-	 * Required in v3. Migration from v1/v2 fills conservative defaults.
+	 * Required in v3+. Migration from v1/v2 fills conservative defaults.
 	 */
 	resilience: ResilienceState;
 	/**
 	 * Batch-level diagnostics for cost tracking and exit summaries (v3, TP-030).
-	 * Required in v3. Migration from v1/v2 fills conservative defaults.
+	 * Required in v3+. Migration from v1/v2 fills conservative defaults.
 	 */
 	diagnostics: BatchDiagnostics;
+	/**
+	 * Per-segment execution records for multi-repo task execution (v4, TP-081).
+	 *
+	 * Each entry represents one repo-scoped segment of a task. In repo mode
+	 * or for single-repo tasks, this array is empty (segment tracking is
+	 * implicit via task records).
+	 *
+	 * Required in v4. Migration from v1/v2/v3 fills empty array.
+	 */
+	segments: PersistedSegmentRecord[];
 	/**
 	 * Unknown top-level fields captured during deserialization.
 	 * Preserved on roundtrip to avoid data loss from future schema extensions
@@ -3213,3 +3357,97 @@ export function createRepoModeContext(
 	};
 }
 
+
+// ── Agent Mailbox Types (TP-089) ─────────────────────────────────────
+
+/**
+ * Mailbox directory name under .pi/.
+ * @since TP-089
+ */
+export const MAILBOX_DIR_NAME = "mailbox";
+
+/**
+ * Maximum content size in UTF-8 bytes.
+ * Steering messages should be concise directives; larger context should be
+ * written to a separate file and referenced by path.
+ * @since TP-089
+ */
+export const MAILBOX_MAX_CONTENT_BYTES = 4096;
+
+/**
+ * Message types for the agent mailbox system.
+ *
+ * | Type       | Direction           | Purpose                                    |
+ * |------------|---------------------|--------------------------------------------|
+ * | `steer`    | supervisor → agent  | Course correction. Agent must follow.       |
+ * | `query`    | supervisor → agent  | Request for status/info. Agent replies.     |
+ * | `abort`    | supervisor → agent  | Graceful stop. Agent wraps up and exits.    |
+ * | `info`     | supervisor → agent  | FYI context. No action required.            |
+ * | `reply`    | agent → supervisor  | Response to query or steer acknowledgment.  |
+ * | `escalate` | agent → supervisor  | Agent-initiated: blocked or needs guidance. |
+ *
+ * @since TP-089
+ */
+export type MailboxMessageType = "steer" | "query" | "abort" | "info" | "reply" | "escalate";
+
+/**
+ * Set of valid mailbox message types for runtime validation.
+ * @since TP-089
+ */
+export const MAILBOX_MESSAGE_TYPES: ReadonlySet<string> = new Set<MailboxMessageType>([
+	"steer", "query", "abort", "info", "reply", "escalate",
+]);
+
+/**
+ * Message format for the file-based agent mailbox.
+ *
+ * Messages are written as JSON files in batch-scoped, session-scoped
+ * directories. The rpc-wrapper checks the inbox on every `message_end`
+ * event and injects pending messages into the agent's LLM context via
+ * pi's `steer` RPC command.
+ *
+ * @see docs/specifications/taskplane/agent-mailbox-steering.md
+ * @since TP-089
+ */
+export interface MailboxMessage {
+	/** Unique message ID: `{timestamp}-{5char-hex-nonce}` */
+	id: string;
+	/** Batch ID — must match current batch for validation */
+	batchId: string;
+	/** Sender identifier: `"supervisor"` or session name */
+	from: string;
+	/** Target session name or `"_broadcast"` */
+	to: string;
+	/** Epoch milliseconds (Date.now()) */
+	timestamp: number;
+	/** Message type */
+	type: MailboxMessageType;
+	/** Message body (max 4KB UTF-8 bytes) */
+	content: string;
+	/** Whether the sender expects a reply (default: false) */
+	expectsReply?: boolean;
+	/** Reference to a previous message ID for threading (default: null) */
+	replyTo?: string | null;
+}
+
+/**
+ * Input options for writeMailboxMessage.
+ *
+ * The caller provides these fields; the utility generates `id`, `batchId`,
+ * `to`, and `timestamp` from its own arguments.
+ *
+ * @since TP-089
+ */
+export interface WriteMailboxMessageOpts {
+	/** Sender identifier: `"supervisor"` or session name */
+	from: string;
+	/** Message type */
+	type: MailboxMessageType;
+	/** Message body (max 4KB UTF-8 bytes) */
+	content: string;
+	/** Whether the sender expects a reply (default: false) */
+	expectsReply?: boolean;
+	/** Reference to a previous message ID for threading (default: null) */
+	replyTo?: string | null;
+}
+

package/extensions/taskplane/verification.ts

@@ -27,10 +27,15 @@
  *   6. Truncate to 512 chars (bound fingerprint size)
  *
  * **Fallback for non-JSON output:**
- *   If vitest JSON parsing fails (truncated, missing, non-JSON), produce a
- *   single fingerprint with kind: "command_error" and the first 512 chars
+ *   If legacy Vitest JSON parsing fails (truncated, missing, non-JSON), produce
+ *   a single fingerprint with kind: "command_error" and the first 512 chars
  *   of stderr (or stdout) as messageNorm.
  *
+ * **Compatibility note:**
+ *   Taskplane's default tests use Node.js native `node:test`. The Vitest parser
+ *   in this module is retained only for backward compatibility when projects
+ *   provide custom `testing.commands` that still emit Vitest JSON.
+ *
  * @module orch/verification
  */
 import { spawnSync } from "child_process";
@@ -300,20 +305,20 @@ function classifyFailureKind(message: string): TestFingerprint["kind"] {
 }
 
 /**
- * Parse vitest JSON reporter output into test fingerprints.
+ * Parse legacy Vitest JSON reporter output into test fingerprints.
  *
- * Expects the stdout to contain a JSON object matching vitest's JSON reporter format.
+ * Expects stdout to contain a JSON object matching Vitest's JSON reporter format.
  * Only failed tests produce fingerprints (passed tests are irrelevant for baseline diffing).
  *
  * If JSON parsing fails or the structure is unexpected, returns null to signal
  * that the caller should use fallback fingerprinting.
  *
  * @param commandId - The command that produced this output
- * @param stdout    - Raw stdout from the vitest command
+ * @param stdout    - Raw stdout from the Vitest command (legacy compatibility path)
  * @returns Array of fingerprints for failed tests, or null if parsing fails
  */
 export function parseVitestOutput(commandId: string, stdout: string): TestFingerprint[] | null {
-	// Try to extract JSON from stdout (vitest may prepend/append non-JSON lines)
+	// Try to extract JSON from stdout (Vitest may prepend/append non-JSON lines)
 	let json: VitestJsonResult;
 	try {
 		// First attempt: parse the whole stdout as JSON
@@ -363,7 +368,7 @@ export function parseVitestOutput(commandId: string, stdout: string): TestFinger
 		}
 
 		// Suite-level failures: testResults[].status === "failed" with no assertion-level details.
-		// This covers setup/import/runtime-at-file-load errors where vitest marks the file as
+		// This covers setup/import/runtime-at-file-load errors where Vitest marks the file as
 		// failed but produces no assertionResults (or only non-failed ones).
 		if (testFile.status === "failed") {
 			const hasFailedAssertions = hasAssertions && assertions!.some(a => a.status === "failed");
@@ -388,7 +393,7 @@ export function parseVitestOutput(commandId: string, stdout: string): TestFinger
  * Parse test output into normalized fingerprints.
  *
  * Strategy:
- * 1. Try vitest JSON adapter
+ * 1. Try legacy Vitest JSON adapter
  * 2. If parsing fails: produce a fallback command_error fingerprint
  *
  * The adapter pattern is extensible — future parsers for jest, pytest, etc.
@@ -416,7 +421,7 @@ export function parseTestOutput(commandResult: CommandResult): TestFingerprint[]
 		return [];
 	}
 
-	// Try vitest JSON adapter
+	// Try legacy Vitest JSON adapter
 	const vitestFingerprints = parseVitestOutput(commandId, stdout);
 	if (vitestFingerprints !== null && vitestFingerprints.length > 0) {
 		return vitestFingerprints;

package/package.json

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

package/templates/agents/supervisor.md

@@ -68,7 +68,7 @@ Every action you take falls into one of three categories:
 ### Diagnostic (always allowed — no confirmation needed)
 - Reading batch-state.json, STATUS.md, events.jsonl, merge results
 - Running `git status`, `git log`, `git diff`
-- Running test suites (`npx vitest run`, etc.)
+- Running test suites (`node --experimental-strip-types --experimental-test-module-mocks --no-warnings --import ./tests/loader.mjs --test ...`, etc.)
 - Listing tmux sessions (`tmux list-sessions`)
 - Checking worktree health (`git worktree list`)
 - Reading any file for diagnostics

package/templates/agents/task-worker.md

@@ -201,8 +201,29 @@ a reviewer agent. The tool takes two parameters: `step` (number) and `type`
 documentation/delivery). These are low-risk steps where review overhead exceeds
 value.
 
+### ⚠️ CRITICAL: Plan review happens BEFORE implementation
+
+**The plan review MUST happen BEFORE you write any code for that step.**
+The entire purpose of plan review is to catch design issues, missing cases, and
+wrong approaches BEFORE you spend tokens implementing them. If you implement
+first and then request plan review, the reviewer's feedback is wasted — the
+code is already written.
+
+**Correct sequence:**
+1. Hydrate step checkboxes (expand the plan)
+2. Commit the hydrated STATUS.md
+3. **Call `review_step(step=N, type="plan")` — BEFORE writing any code**
+4. Handle verdict (APPROVE → implement; REVISE → fix plan, re-review)
+5. Implement the step (write code, check off items)
+6. Commit implementation
+7. Call `review_step(step=N, type="code")` — AFTER implementation
+
+**WRONG sequence (violates the protocol):**
+1. ~~Hydrate, implement, check off, commit, THEN call plan review~~ ❌
+   This makes plan review pointless — the work is already done.
+
 **Handling verdicts:**
-- **APPROVE** → proceed to next step
+- **APPROVE** → proceed (to implementation after plan review; to next step after code review)
 - **RETHINK** → reconsider your plan approach, adjust, then implement
 - **REVISE** → read the review file in `.reviews/` for detailed feedback,
   address the issues, commit fixes, then **call `review_step` again** for re-review.
@@ -211,14 +232,16 @@ value.
 
 **Example flow for a Review Level 2 task, Step 3:**
 1. Read Step 3 requirements
-2. Call `review_step(step=3, type="plan")` → get plan feedback
-3. Capture baseline: run `git rev-parse HEAD` and save the SHA
-4. Implement Step 3
-5. Commit changes
-6. Call `review_step(step=3, type="code", baseline="<saved SHA>")` → get code feedback
-7. If REVISE: fix issues, commit, call `review_step(step=3, type="code")` again
-8. Repeat 7 until APPROVE (max 2 code review cycles per step)
-9. Move to Step 4
+2. Hydrate Step 3 checkboxes, commit STATUS.md
+3. Call `review_step(step=3, type="plan")` → get plan feedback (**NO CODE YET**)
+4. If REVISE: adjust plan, re-request plan review
+5. If APPROVE: capture baseline SHA (`git rev-parse HEAD`)
+6. Implement Step 3 (write code, check off items)
+7. Commit changes
+8. Call `review_step(step=3, type="code", baseline="<saved SHA>")` → get code feedback
+9. If REVISE: fix issues, commit, call `review_step(step=3, type="code")` again
+10. Repeat 9 until APPROVE (max 2 code review cycles per step)
+11. Move to Step 4
 
 If the `review_step` tool is not available (e.g., non-orchestrated mode), skip
 this protocol entirely — the task-runner handles reviews externally.
@@ -252,30 +275,24 @@ Run tests at two different scopes depending on where you are in the task:
 
 ### During implementation steps (targeted tests)
 
-After implementing each step, run **targeted tests** for fast feedback:
+After implementing each step, run **targeted tests** for fast feedback.
+Use file-targeted runs for the test files that cover your changes:
 
 ```bash
-cd extensions && npx vitest run --changed
+cd extensions && node --experimental-strip-types --experimental-test-module-mocks --no-warnings --import ./tests/loader.mjs --test tests/some-specific.test.ts
 ```
 
-- Vitest's `--changed` flag uses git to find modified files since the last commit
-  and runs only tests related to those files.
-- Workers commit at step boundaries, so between commits the changed set is
-  exactly "what this step modified" — this naturally targets the right tests.
-- Alternatively, run specific test files that cover the code you modified:
-  `npx vitest run tests/some-specific.test.ts`
-- **If `--changed` returns no tests:** That's fine — it means your changes don't
-  have directly related test files. The full suite in the Testing step will catch
-  any indirect regressions.
-- **If targeted tests fail:** Fix the failure before proceeding. Don't accumulate
-  failures across steps.
+- Node's native runner does not provide a reliable project-level `--changed`
+  equivalent; select targeted files explicitly.
+- If multiple files are relevant, pass multiple `--test` paths.
+- **If targeted tests fail:** fix them before proceeding. Don't accumulate failures.
 
 ### During the Testing & Verification step (full suite)
 
 Run the **full test suite** as a quality gate:
 
 ```bash
-cd extensions && npx vitest run
+cd extensions && node --experimental-strip-types --experimental-test-module-mocks --no-warnings --import ./tests/loader.mjs --test tests/*.test.ts
 ```
 
 - ALL tests must pass — zero failures allowed.