@gobing-ai/spur 0.4.0 → 0.4.1

package/plugins/sp/lib/transcript.ts

@@ -16,14 +16,35 @@ export interface Span {
     tokens: Tokens;
 }
 
-type Block = Partial<Record<'type' | 'id' | 'name' | 'text' | 'tool_use_id', string>>;
+export interface Block {
+    type?: string;
+    id?: string;
+    name?: string;
+    text?: string;
+    tool_use_id?: string;
+    /** Claude tool_result error flag (1146 R4): a failed subagent call is counted. */
+    is_error?: boolean;
+}
 
 export interface Row {
     type?: string;
+    /** Claude `system` rows carry the compaction subtype (1146 R4). */
+    subtype?: string;
     timestamp?: string;
     isMeta?: boolean;
     isCompactSummary?: boolean;
-    message?: { id?: string; content?: unknown; usage?: Record<string, number | undefined> };
+    id?: string; // pi: the row id doubles as the once-per-message usage key
+    message?: {
+        id?: string;
+        role?: string;
+        content?: unknown;
+        usage?: Record<string, number | undefined>;
+        toolCallId?: string;
+        /** pi toolResult rows name their tool here (1146 R4). */
+        toolName?: string;
+        /** pi toolResult error flag (1146 R4). */
+        isError?: boolean;
+    };
 }
 
 /** Running measurement of one segment or window. */
@@ -33,11 +54,13 @@ export interface Acc {
     asks: Map<string, number>;
     toolIds: Set<string>;
     messages: Map<string, Tokens>;
+    compactions: number;
 }
 
 const SESSION_ID = /^[A-Za-z0-9_-]+$/;
 /** Host tools whose call→result gap is the operator answering, not the agent working. */
-const OPERATOR_TOOLS = new Set(['AskUserQuestion']);
+const OPERATOR_TOOLS = new Set(['AskUserQuestion', 'ask_user_question']);
+const PI_ROLES = new Set(['user', 'assistant', 'toolResult']);
 
 export const zeroTokens = (): Tokens => ({ input: 0, cacheCreate: 0, cacheRead: 0, output: 0 });
 
@@ -67,6 +90,16 @@ export function formatTokenSplit(t: Tokens | null): string {
 
 /** Operator prompt text, or undefined for tool results, meta rows and compaction summaries. */
 export function promptText(row: Row): string | undefined {
+    if (row.type === 'message') {
+        // pi (1130): only a user-role message with text content is a prompt; toolResult rows are not.
+        if (row.message?.role !== 'user') return undefined;
+        // pi (1138 R2): a skill-injected body is activity, not an operator prompt.
+        if (isInjectedPrompt(row)) return undefined;
+        const content = row.message.content;
+        if (typeof content === 'string') return content;
+        if (!Array.isArray(content)) return undefined;
+        return (content as Block[]).find((b) => b.type === 'text')?.text;
+    }
     if (row.type !== 'user' || row.isMeta || row.isCompactSummary) return undefined;
     const content = row.message?.content;
     if (typeof content === 'string') return content;
@@ -74,6 +107,24 @@ export function promptText(row: Row): string | undefined {
     return (content as Block[]).find((b) => b.type === 'text')?.text;
 }
 
+/**
+ * 1138 R2: a pi user row whose first text block, after leading whitespace, opens with
+ * `<skill name="`, is an injected body (pi has no `isMeta` to key on). It is accumulated as
+ * activity and must not open a segment. Operator text that merely CONTAINS `<skill` later in the
+ * body is still a prompt. Claude rows are unaffected: their injected bodies already arrive as `isMeta`.
+ */
+export function isInjectedPrompt(row: Row): boolean {
+    if (row.type !== 'message' || row.message?.role !== 'user') return false;
+    const content = row.message.content;
+    const text =
+        typeof content === 'string'
+            ? content
+            : Array.isArray(content)
+              ? (content as Block[]).find((b) => b.type === 'text')?.text
+              : undefined;
+    return typeof text === 'string' && text.replace(/^\s+/, '').startsWith('<skill name="');
+}
+
 export function sumTokens(all: Tokens[]): Tokens {
     const total = zeroTokens();
     for (const t of all) for (const k of Object.keys(total) as (keyof Tokens)[]) total[k] += t[k];
@@ -95,11 +146,38 @@ export const newAcc = (ts: number): Acc => ({
     asks: new Map(),
     toolIds: new Set(),
     messages: new Map(),
+    compactions: 0,
 });
 
 /** Fold one timestamped non-prompt record into a segment or window. */
 export function accumulate(acc: Acc, row: Row, ts: number): void {
     acc.last = Math.max(acc.last, ts);
+    if (row.type === 'message') {
+        // pi (1130): mirrors the importer's field semantics (piRole / normalizeOmpToolCall /
+        // ompToolResultTiming) — toolCall blocks on assistant rows, results paired by toolCallId.
+        const m = row.message;
+        if (m?.role === 'assistant') {
+            const blocks = Array.isArray(m.content) ? (m.content as Block[]) : [];
+            for (const b of blocks) {
+                if (b.type === 'toolCall' && b.id) {
+                    acc.toolIds.add(b.id);
+                    if (b.name && OPERATOR_TOOLS.has(b.name)) acc.asks.set(b.id, ts);
+                }
+            }
+            const u = m.usage;
+            if (u && row.id)
+                acc.messages.set(row.id, {
+                    input: u.input ?? 0,
+                    cacheCreate: u.cacheWrite ?? 0,
+                    cacheRead: u.cacheRead ?? 0,
+                    output: u.output ?? 0,
+                });
+        } else if (m?.role === 'toolResult' && m.toolCallId && acc.asks.has(m.toolCallId)) {
+            acc.askMs += ts - (acc.asks.get(m.toolCallId) ?? ts);
+        }
+        return;
+    }
+    if (row.type === 'compaction') acc.compactions++; // pi-only row type (1130 R4)
     const blocks = Array.isArray(row.message?.content) ? (row.message.content as Block[]) : [];
     for (const b of blocks) {
         if (b.type === 'tool_use' && b.id) {
@@ -121,8 +199,29 @@ export function accumulate(acc: Acc, row: Row, ts: number): void {
     }
 }
 
+/**
+ * 1146 R4: a compaction boundary in either host shape — pi writes a `compaction` row, Claude a
+ * `system` row with `subtype:"compact_boundary"`.
+ */
+export function isCompaction(row: Row): boolean {
+    return row.type === 'compaction' || (row.type === 'system' && row.subtype === 'compact_boundary');
+}
+
+/** First row matching a known shape decides: `type:"message"` with a pi role → pi, else Claude. */
+export function sniffFormat(rows: Row[]): 'claude' | 'pi' | 'unknown' {
+    for (const row of rows) {
+        if (row.type === 'message' && PI_ROLES.has(row.message?.role ?? '')) return 'pi';
+        if (row.type === 'user' || row.type === 'assistant') return 'claude';
+    }
+    return 'unknown';
+}
+
 /** Timestamped rows in file order; malformed lines counted, timestamp-less rows dropped. */
-export function parseRows(lines: string[]): { rows: [Row, number][]; skippedLines: number } {
+export function parseRows(lines: string[]): {
+    rows: [Row, number][];
+    skippedLines: number;
+    format: 'claude' | 'pi' | 'unknown';
+} {
     const rows: [Row, number][] = [];
     let skippedLines = 0;
     for (const line of lines) {
@@ -137,7 +236,7 @@ export function parseRows(lines: string[]): { rows: [Row, number][]; skippedLine
         const ts = row.timestamp ? Date.parse(row.timestamp) : Number.NaN;
         if (!Number.isNaN(ts)) rows.push([row, ts]);
     }
-    return { rows, skippedLines };
+    return { rows, skippedLines, format: sniffFormat(rows.map(([r]) => r)) };
 }
 
 export type Resolved = { ok: true; path: string } | { ok: false; reason: string };
@@ -149,7 +248,23 @@ export function resolveTranscript(
 ): Resolved {
     if (override) return existsSync(override) ? { ok: true, path: override } : { ok: false, reason: 'no transcript' };
     const id = env.CLAUDE_CODE_SESSION_ID;
-    if (!id) return { ok: false, reason: 'no host session id (CLAUDE_CODE_SESSION_ID); pass --transcript <path>' };
+    if (!id) {
+        // 1138 R1: pi exports PI_SESSION_FILE (an exact path) and no Claude session id. Order is
+        // explicit override → Claude id → PI_SESSION_FILE; PI_SESSION_ID is never used for lookup
+        // because pi's filename embeds a timestamp, so the path is not derivable from the id.
+        const piFile = env.PI_SESSION_FILE;
+        if (piFile !== undefined && piFile !== '') {
+            return existsSync(piFile)
+                ? { ok: true, path: piFile }
+                : { ok: false, reason: `PI_SESSION_FILE ${piFile} does not exist` };
+        }
+        return {
+            ok: false,
+            reason:
+                'no host session id; pass --transcript <path> (pi: ~/.pi/agent/sessions/<cwd-slug>/<file>.jsonl, ' +
+                'or set PI_SESSION_FILE)',
+        };
+    }
     if (!SESSION_ID.test(id)) return { ok: false, reason: 'refusing a session id with path characters' };
     if (!existsSync(projectsRoot)) return { ok: false, reason: `no transcript root ${projectsRoot}` };
     for (const dir of readdirSync(projectsRoot)) {

package/plugins/sp/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "sp",
-    "version": "0.4.0",
+    "version": "0.4.1",
     "description": "Spur — a local-first harness engineering toolkit that wraps mainstream coding agents with constraint checking, workflow orchestration, and history analytics.",
     "extensions": {
         "pi": ["./hooks/pi/guard-extension.ts"]

package/plugins/sp/references/roles.md

@@ -62,7 +62,7 @@ roles:
     stages: [verify, review, dogfood]
   - id: planner
     tier: capable-2
-    commands: [dev-plan, dev-refine, dev-brainstorm, dev-idea, dev-runall, dev-parallel, dev-next, dev-job-resume, dev-arch, dev-refineall, dev-find-next, dev-feature-change]
+    commands: [dev-plan, dev-refine, dev-brainstorm, dev-find-way, dev-idea, dev-runall, dev-parallel, dev-next, dev-job-resume, dev-arch, dev-refineall, dev-find-next, dev-feature-change]
     stages: [plan, refine, brainstorm]
 ```
 

package/plugins/sp/scripts/batch-plan.mjs

@@ -0,0 +1,335 @@
+#!/usr/bin/env node
+// @bun
+
+// plugins/sp/scripts/batch-plan.ts
+import { readFileSync } from "fs";
+
+// plugins/sp/lib/plan-projection.generated.mjs
+function planLetter(index) {
+  if (!Number.isInteger(index) || index < 0 || index > 25) {
+    throw new Error(`plan letter out of range: ${index} (expected 0..25)`);
+  }
+  return String.fromCharCode(65 + index);
+}
+function planChild(parent, index) {
+  if (!Number.isInteger(index) || index < 0 || index > 8) {
+    throw new Error(`plan child index out of range: ${index} (expected 0..8 under ${parent})`);
+  }
+  if (parent.length !== 1 || !/[A-Z]/.test(parent)) {
+    throw new Error(`plan child parent must be a single letter: ${parent}`);
+  }
+  return `${parent}${index + 1}`;
+}
+var PREPARE_ID = "prepare";
+var REPORT_ID = "report";
+var PHASE_ID_PREFIX = "phase.";
+var TASK_ID_PREFIX = "task.";
+var WAVE_SIZE = 24;
+var TITLE_CAP = 60;
+function isStateMachine(def) {
+  return def.kind !== "transition-flow" && def.kind !== "dag";
+}
+function hasDisplay(s) {
+  return s.display !== undefined;
+}
+function resolvePhaseTitle(states, phase) {
+  for (const s of states) {
+    if (s.display?.phase === phase && s.display.phaseTitle !== undefined)
+      return s.display.phaseTitle;
+  }
+  return phase;
+}
+function childText(label, title, id) {
+  return id.startsWith("prepare.") || id.startsWith("task.") || id === PREPARE_ID || id === REPORT_ID ? `${label} ${title}` : `${label} ${title} · ${id}`;
+}
+function buildPhasedPlan(def) {
+  if (!isStateMachine(def))
+    return null;
+  const annotated = def.states.filter(hasDisplay);
+  if (annotated.length === 0)
+    return null;
+  const items = [
+    { label: "A", id: PREPARE_ID, outcome: "pending", title: "Prepare", text: "A Prepare" },
+    {
+      label: "A1",
+      id: "prepare.1",
+      outcome: "pending",
+      parent: "A",
+      title: "Quick readiness",
+      text: "A1 Quick readiness"
+    },
+    { label: "A2", id: "prepare.2", outcome: "pending", parent: "A", title: "Prepare Git", text: "A2 Prepare Git" },
+    {
+      label: "A3",
+      id: "prepare.3",
+      outcome: "pending",
+      parent: "A",
+      title: "Publish plan",
+      text: "A3 Publish plan"
+    }
+  ];
+  const phases = [];
+  for (const s of def.states) {
+    if (s.display !== undefined && !phases.includes(s.display.phase))
+      phases.push(s.display.phase);
+  }
+  for (const [phaseIndex, phase] of phases.entries()) {
+    const letter = planLetter(phaseIndex + 1);
+    const phaseTitle = resolvePhaseTitle(def.states, phase);
+    items.push({
+      label: letter,
+      id: `${PHASE_ID_PREFIX}${phase}`,
+      outcome: "pending",
+      title: phaseTitle,
+      text: `${letter} ${phaseTitle}`
+    });
+    let childIndex = 0;
+    for (const s of def.states) {
+      if (s.display?.phase !== phase || s.display.show === "on-entry")
+        continue;
+      const label = planChild(letter, childIndex++);
+      const title = s.display.title ?? s.id;
+      items.push({
+        label,
+        id: s.id,
+        outcome: "pending",
+        parent: letter,
+        title,
+        text: childText(label, title, s.id)
+      });
+    }
+  }
+  return items;
+}
+function validatePhaseTable(def) {
+  if (!isStateMachine(def))
+    return [];
+  const annotated = def.states.filter(hasDisplay);
+  if (annotated.length === 0)
+    return [];
+  const errors = [];
+  const terminals = new Set(def.terminalStates ?? []);
+  for (const s of def.states) {
+    if (s.display === undefined && !terminals.has(s.id)) {
+      errors.push(`state "${s.id}" has no display phase — every non-terminal state must declare display when any state does`);
+    }
+    if (s.display !== undefined && terminals.has(s.id)) {
+      errors.push(`terminal state "${s.id}" must not declare display`);
+    }
+  }
+  const phases = [];
+  for (const s of annotated) {
+    if (!phases.includes(s.display.phase))
+      phases.push(s.display.phase);
+  }
+  if (phases.length > 25) {
+    errors.push(`${phases.length} phases exceed the 25 plan letters (B-Z); split the workflow or drop phase rows`);
+  }
+  for (const phase of phases) {
+    const members = annotated.filter((s) => s.display.phase === phase);
+    if (members.length > 9) {
+      errors.push(`phase "${phase}" has ${members.length} states — at most 9 digit children fit under one letter`);
+    }
+    const titles = [...new Set(members.map((s) => s.display.phaseTitle).filter((t) => t !== undefined))];
+    if (titles.length > 1) {
+      errors.push(`phase "${phase}" has conflicting phaseTitle values: ${titles.map((t) => `"${t}"`).join(", ")}`);
+    }
+  }
+  return errors;
+}
+function insertOnEntry(items, stateId, def) {
+  if (!isStateMachine(def))
+    return items;
+  if (items.some((i) => i.id === stateId))
+    return items;
+  const display = def.states.find((s) => s.id === stateId)?.display;
+  if (display === undefined || (def.terminalStates ?? []).includes(stateId))
+    return items;
+  const phaseRow = items.find((i) => i.id === `${PHASE_ID_PREFIX}${display.phase}`);
+  if (phaseRow === undefined)
+    return items;
+  const children = items.filter((i) => i.parent === phaseRow.label);
+  const label = planChild(phaseRow.label, children.length);
+  const title = display.title ?? stateId;
+  const item = {
+    label,
+    id: stateId,
+    outcome: "pending",
+    parent: phaseRow.label,
+    title,
+    text: childText(label, title, stateId)
+  };
+  const last = children.at(-1) ?? phaseRow;
+  const at = items.indexOf(last) + 1;
+  return [...items.slice(0, at), item, ...items.slice(at)];
+}
+function truncateTitle(name) {
+  if (name.length <= TITLE_CAP)
+    return name;
+  return `${name.slice(0, TITLE_CAP - 1).replace(/[\uD800-\uDBFF]$/, "")}…`;
+}
+function buildBatchPlan(tasks) {
+  const waves = [];
+  for (let offset = 0;offset < tasks.length; offset += WAVE_SIZE) {
+    const items = [
+      { label: "A", id: PREPARE_ID, outcome: "pending", title: "Prepare batch", text: "A Prepare batch" },
+      {
+        label: "A1",
+        id: "prepare.1",
+        outcome: "pending",
+        parent: "A",
+        title: "Resolve and freeze task set",
+        text: "A1 Resolve and freeze task set"
+      },
+      {
+        label: "A2",
+        id: "prepare.2",
+        outcome: "pending",
+        parent: "A",
+        title: "Order by dependencies",
+        text: "A2 Order by dependencies"
+      },
+      {
+        label: "A3",
+        id: "prepare.3",
+        outcome: "pending",
+        parent: "A",
+        title: "Prepare Git",
+        text: "A3 Prepare Git"
+      },
+      {
+        label: "A4",
+        id: "prepare.4",
+        outcome: "pending",
+        parent: "A",
+        title: "Publish plan",
+        text: "A4 Publish plan"
+      }
+    ];
+    tasks.slice(offset, offset + WAVE_SIZE).forEach((task, i) => {
+      const label = planLetter(i + 1);
+      const title = `${task.wbs} ${truncateTitle(task.name)}`;
+      items.push({
+        label,
+        id: `${TASK_ID_PREFIX}${task.wbs}`,
+        outcome: "pending",
+        title,
+        text: `${label} ${title}`
+      });
+    });
+    items.push({ label: "Z", id: REPORT_ID, outcome: "pending", title: "Batch report", text: "Z Batch report" });
+    waves.push(items);
+  }
+  return waves;
+}
+function taskPhaseChildren(taskLetter, plan) {
+  if (!Array.isArray(plan))
+    return [];
+  return plan.filter((i) => i.id.startsWith(PHASE_ID_PREFIX) && i.label.length === 1).map((row, i) => {
+    const label = planChild(taskLetter, i);
+    return {
+      label,
+      id: row.id,
+      outcome: row.outcome,
+      parent: taskLetter,
+      title: row.title,
+      text: `${label} ${row.title}`
+    };
+  });
+}
+function hostStatus(outcome) {
+  if (outcome === "completed")
+    return "completed";
+  if (outcome === "active")
+    return "in_progress";
+  return "pending";
+}
+function hostText(item) {
+  const hostDecided = item.outcome === "skipped" || item.outcome === "failed" || item.outcome === "unattempted" || item.outcome === "blocked";
+  return hostDecided ? `${item.text} [${item.outcome}]` : item.text;
+}
+
+// plugins/sp/scripts/batch-plan.ts
+var BATCH_PLAN_USAGE = "usage: batch-plan.ts waves --tasks <tasks.json> | task-children --letter <A-Z> --plan <plan.json>";
+function readJsonFile(path) {
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+function isBatchTask(value) {
+  return typeof value === "object" && value !== null && typeof value.wbs === "string" && typeof value.name === "string";
+}
+function main(argv) {
+  const mode = argv[0];
+  if (mode === "waves") {
+    if (argv[1] !== "--tasks" || argv[2] === undefined) {
+      process.stderr.write(`${BATCH_PLAN_USAGE}
+`);
+      return 2;
+    }
+    let tasks;
+    try {
+      tasks = readJsonFile(argv[2]);
+    } catch (error) {
+      process.stderr.write(`batch-plan: cannot read ${argv[2]} \u2014 ${error instanceof Error ? error.message : String(error)}
+`);
+      return 1;
+    }
+    if (!Array.isArray(tasks) || !tasks.every(isBatchTask)) {
+      process.stderr.write(`batch-plan: --tasks file must be a JSON array of {wbs, name}
+`);
+      return 1;
+    }
+    process.stdout.write(`${JSON.stringify({ waves: buildBatchPlan(tasks) })}
+`);
+    return 0;
+  }
+  if (mode === "task-children") {
+    let letter = "";
+    let planPath = "";
+    for (let i = 1;i + 1 < argv.length; i += 2) {
+      if (argv[i] === "--letter")
+        letter = argv[i + 1] ?? "";
+      else if (argv[i] === "--plan")
+        planPath = argv[i + 1] ?? "";
+    }
+    if (!/^[A-Z]$/.test(letter) || planPath === "") {
+      process.stderr.write(`${BATCH_PLAN_USAGE}
+`);
+      return 2;
+    }
+    let payload;
+    try {
+      payload = readJsonFile(planPath);
+    } catch (error) {
+      process.stderr.write(`batch-plan: cannot read ${planPath} \u2014 ${error instanceof Error ? error.message : String(error)}
+`);
+      return 1;
+    }
+    const plan = Array.isArray(payload) ? payload : payload.plan;
+    if (!Array.isArray(plan)) {
+      process.stderr.write("batch-plan: --plan file must be a plan array or a todo --json payload with a `plan` field\n");
+      return 1;
+    }
+    process.stdout.write(`${JSON.stringify(taskPhaseChildren(letter, plan))}
+`);
+    return 0;
+  }
+  process.stderr.write(`${BATCH_PLAN_USAGE}
+`);
+  return 2;
+}
+{
+  process.exit(main(process.argv.slice(2)));
+}
+export {
+  validatePhaseTable,
+  taskPhaseChildren,
+  planLetter,
+  planChild,
+  main,
+  insertOnEntry,
+  hostText,
+  hostStatus,
+  buildPhasedPlan,
+  buildBatchPlan,
+  BATCH_PLAN_USAGE
+};

package/plugins/sp/scripts/batch-plan.ts

@@ -0,0 +1,100 @@
+#!/usr/bin/env bun
+/**
+ * batch-plan — letters-first batch plan surface (task 1104, feature I13).
+ *
+ * The projection logic lives in packages/app/src/workflow/plan-projection.ts (unit-tested
+ * there); this script is ADR-130 glue — argv/IO only — over the bundled core in
+ * ../lib/plan-projection.generated.* (regenerate: `bun run build:plugin-lib && bun run build:scripts`).
+ *
+ * Modes:
+ *   waves --tasks <file>  file: JSON array of {wbs, name}; prints `{ waves: [...] }` — waves
+ *                         of 24 tasks as A Prepare batch + A1..A4 + B..Y task rows + Z Batch report.
+ *   task-children --letter <A-Z> --plan <file>
+ *                         file: a `workflow show --format todo --json` payload (or a bare plan
+ *                         array); prints the task's phase digits as a JSON array.
+ * Exit 0 on success, 1 on unreadable/invalid input, 2 on usage error. Runs under bare
+ * `node batch-plan.mjs` (committed twin) — keep the twin in lockstep.
+ */
+import { readFileSync } from 'node:fs';
+import type { BatchTask, PhasedPlanItem } from '../lib/plan-projection.generated.mjs';
+import { buildBatchPlan, taskPhaseChildren } from '../lib/plan-projection.generated.mjs';
+
+export * from '../lib/plan-projection.generated.mjs';
+
+export const BATCH_PLAN_USAGE =
+    'usage: batch-plan.ts waves --tasks <tasks.json> | task-children --letter <A-Z> --plan <plan.json>';
+
+function readJsonFile(path: string): unknown {
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+function isBatchTask(value: unknown): value is BatchTask {
+    return (
+        typeof value === 'object' &&
+        value !== null &&
+        typeof (value as BatchTask).wbs === 'string' &&
+        typeof (value as BatchTask).name === 'string'
+    );
+}
+
+export function main(argv: string[]): number {
+    const mode = argv[0];
+    if (mode === 'waves') {
+        if (argv[1] !== '--tasks' || argv[2] === undefined) {
+            process.stderr.write(`${BATCH_PLAN_USAGE}\n`);
+            return 2;
+        }
+        let tasks: unknown;
+        try {
+            tasks = readJsonFile(argv[2]);
+        } catch (error) {
+            process.stderr.write(
+                `batch-plan: cannot read ${argv[2]} — ${error instanceof Error ? error.message : String(error)}\n`,
+            );
+            return 1;
+        }
+        if (!Array.isArray(tasks) || !tasks.every(isBatchTask)) {
+            process.stderr.write('batch-plan: --tasks file must be a JSON array of {wbs, name}\n');
+            return 1;
+        }
+        process.stdout.write(`${JSON.stringify({ waves: buildBatchPlan(tasks) })}\n`);
+        return 0;
+    }
+    if (mode === 'task-children') {
+        let letter = '';
+        let planPath = '';
+        for (let i = 1; i + 1 < argv.length; i += 2) {
+            if (argv[i] === '--letter') letter = argv[i + 1] ?? '';
+            else if (argv[i] === '--plan') planPath = argv[i + 1] ?? '';
+        }
+        if (!/^[A-Z]$/.test(letter) || planPath === '') {
+            process.stderr.write(`${BATCH_PLAN_USAGE}\n`);
+            return 2;
+        }
+        let payload: unknown;
+        try {
+            payload = readJsonFile(planPath);
+        } catch (error) {
+            process.stderr.write(
+                `batch-plan: cannot read ${planPath} — ${error instanceof Error ? error.message : String(error)}\n`,
+            );
+            return 1;
+        }
+        // Accept a bare plan array or a full `workflow show --format todo --json` payload.
+        const plan = Array.isArray(payload) ? payload : (payload as { plan?: PhasedPlanItem[] }).plan;
+        if (!Array.isArray(plan)) {
+            process.stderr.write(
+                'batch-plan: --plan file must be a plan array or a todo --json payload with a `plan` field\n',
+            );
+            return 1;
+        }
+        process.stdout.write(`${JSON.stringify(taskPhaseChildren(letter, plan as PhasedPlanItem[]))}\n`);
+        return 0;
+    }
+    process.stderr.write(`${BATCH_PLAN_USAGE}\n`);
+    return 2;
+}
+
+if (import.meta.main) {
+    process.exit(main(process.argv.slice(2)));
+}