taskplane 0.25.7 → 0.26.1

package/bin/rpc-wrapper.mjs

@@ -294,7 +294,6 @@ function displayProgress(state) {
  * Per RPC protocol spec: split on \n, strip optional trailing \r,
  * do NOT use Node readline (splits on U+2028/U+2029).
  *
- * Reuses the proven pattern from task-runner.ts:910-975.
  */
 function attachJsonlReader(stream, onLine) {
 	const decoder = new StringDecoder("utf8");

package/bin/taskplane.mjs

@@ -3184,7 +3184,7 @@ ${c.bold}Examples:${c.reset}
 ${c.bold}Getting started:${c.reset}
   1. pi install npm:taskplane       # Install the pi package
   2. cd my-project && taskplane init    # Scaffold project config
-  3. pi                             # Start pi — /task and /orch are ready
+  3. pi                             # Start pi — /orch is ready
 `);
 }
 

package/dashboard/public/app.js

@@ -1379,6 +1379,49 @@ function renderSupervisorConversation(supervisor) {
   $supervisorConversationSection.innerHTML = html;
 }
 
+/**
+ * Human-readable labels for supervisor recovery action identifiers.
+ * The supervisor LLM writes snake_case action names to actions.jsonl.
+ * This map translates them to operator-friendly labels for the dashboard.
+ */
+const RECOVERY_ACTION_LABELS = {
+  // Conflict resolution
+  conflict_resolve_checkout_ours:   "Auto-resolved merge conflict (kept task changes)",
+  conflict_resolve_checkout_theirs: "Auto-resolved merge conflict (kept base changes)",
+  conflict_resolve_manual:          "Manual conflict resolution applied",
+
+  // Merge agent
+  merge_retry:                      "Retried merge agent",
+  merge_session_kill:               "Terminated stalled merge agent",
+  merge_force:                      "Forced merge with partial results",
+
+  // Worker / task
+  worker_wrap_up:                   "Sent wrap-up signal to stalled worker",
+  task_retry:                       "Retried failed task",
+  task_skip:                        "Skipped task — unblocked dependents",
+  wave_force_merge:                 "Force-merged wave with mixed results",
+
+  // Git / worktree
+  lock_clear:                       "Cleared stale git lock file",
+  worktree_remove:                  "Removed stale worktree",
+  worktree_prune:                   "Pruned stale worktrees",
+
+  // Batch lifecycle
+  abort_hard:                       "Hard-aborted batch",
+  batch_resume:                     "Resumed batch after recovery",
+  supervisor_handoff:               "Supervisor session handoff",
+
+  // Diagnostics (usually not shown — filtered as non-recovery)
+  initial_status_check:             "Checked initial batch status",
+  completion_status_check:          "Verified batch completion status",
+  read_state:                       "Read batch state",
+};
+
+/** Format a recovery action type string into a human-readable label. */
+function formatRecoveryActionLabel(type) {
+  return RECOVERY_ACTION_LABELS[type] || type.replace(/_/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+}
+
 /** Merge supervisor actions and Tier 0 recovery events into a unified timeline.
  *  Actions from actions.jsonl and recovery events from events.jsonl are combined
  *  and sorted chronologically (per R002: show both Tier 0 and supervisor actions).
@@ -1451,7 +1494,7 @@ function renderSupervisorActions(supervisor) {
     html += `  <div class="supervisor-action-right">`;
     html += `    <div class="supervisor-action-header">`;
     if (tier) html += `<span class="supervisor-action-tier">${tier}</span>`;
-    html += `      <span class="supervisor-action-type">${escapeHtml(type)}</span>`;
+    html += `      <span class="supervisor-action-type" title="${escapeHtml(type)}">${escapeHtml(formatRecoveryActionLabel(type))}</span>`;
     if (target) html += `<span class="supervisor-action-target">${escapeHtml(target)}</span>`;
     if (outcome) html += `<span class="supervisor-action-outcome ${outcomeCls}">${escapeHtml(outcome)}</span>`;
     html += `    </div>`;

package/dashboard/server.cjs

@@ -1121,18 +1121,19 @@ function buildDashboardState() {
 
   // TP-164: Inject merge snapshot telemetry into the telemetry map so
   // `telemetry[sessionName]` resolves for the merge pane.
-  // Only inject when a JSONL-backed entry is absent or stale — the snapshot
-  // provides real-time tool-call / cost / context data even before the
-  // JSONL accumulator has accumulated enough events.
+  // Snapshots are the PRIMARY source for merge telemetry — merge agents don't
+  // write to .pi/telemetry/*.jsonl (the JSONL path is for lane workers only).
+  // Inject snapshot data when no JSONL-backed entry exists for this session.
   for (const snap of Object.values(runtimeMergeSnapshots)) {
     const key = snap.sessionName;
     if (!key) continue;
     const agent = snap.agent;
     if (!agent) continue;
-    // Only inject if there is no existing telemetry entry, or if the snapshot
-    // is more recent than the latest accumulator update.
+    // Only inject if there is no existing JSONL-backed telemetry entry.
+    // Merge agents don't emit to .pi/telemetry/, so existing will always be
+    // absent unless something else wrote to it — in that case defer to it.
     const existing = telemetry[key];
-    if (!existing || (snap.updatedAt && snap.updatedAt > (existing._updatedAt || 0))) {
+    if (!existing) {
       telemetry[key] = {
         inputTokens: agent.inputTokens || 0,
         outputTokens: agent.outputTokens || 0,

package/extensions/task-orchestrator.ts

@@ -18,7 +18,7 @@
  *   .pi/task-orchestrator.yaml  — orchestrator-specific settings
  *   .pi/task-runner.yaml        — task areas, worker/reviewer config (shared)
  *
- * Usage: pi -e extensions/task-orchestrator.ts -e extensions/task-runner.ts
+ * Usage: pi -e extensions/task-orchestrator.ts
  */
 
 // Re-export all named exports for tests and other consumers

package/extensions/taskplane/config-loader.ts

@@ -25,6 +25,8 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync } from "
 import { join } from "path";
 import { homedir } from "os";
 import { parse as yamlParse } from "yaml";
+import { resolvePointer, loadWorkspaceConfig } from "./workspace.ts";
+import type { PointerResolution } from "./types.ts";
 
 import {
 	CONFIG_VERSION,
@@ -1264,3 +1266,54 @@ export function toTaskConfig(config: TaskplaneConfig): {
 		},
 	};
 }
+
+// ── Task Runner Config Loader ───────────────────────────────────────────
+//
+// loadConfig and _resetPointerWarning for task execution consumers.
+
+/** Track whether a pointer warning has been logged this session (log once). */
+let _pointerWarningLogged = false;
+
+/**
+ * Resolve the workspace pointer for config and agent path redirection.
+ * Returns null in repo mode (TASKPLANE_WORKSPACE_ROOT not set).
+ */
+function resolveTaskRunnerPointer(): PointerResolution | null {
+	const wsRoot = process.env.TASKPLANE_WORKSPACE_ROOT;
+	if (!wsRoot) return null;
+	try {
+		const wsConfig = loadWorkspaceConfig(wsRoot);
+		const result = resolvePointer(wsRoot, wsConfig);
+		if (result?.warning && !_pointerWarningLogged) {
+			_pointerWarningLogged = true;
+			console.error(`[task-runner] pointer: ${result.warning}`);
+		}
+		return result;
+	} catch {
+		return null;
+	}
+}
+
+/** Reset pointer warning state (for testing only). */
+export function _resetPointerWarning(): void {
+	_pointerWarningLogged = false;
+}
+
+/**
+ * Load task-runner config via the unified config loader.
+ *
+ * Returns the legacy snake_case TaskConfig shape. Wraps loadProjectConfig
+ * with pointer resolution and error handling.
+ */
+export function loadConfig(cwd: string): ReturnType<typeof toTaskConfig> {
+	try {
+		const pointer = resolveTaskRunnerPointer();
+		const unified = loadProjectConfig(cwd, pointer?.configRoot);
+		return toTaskConfig(unified);
+	} catch (err: unknown) {
+		if (err instanceof ConfigLoadError && err.code === "CONFIG_LEGACY_FIELD") {
+			throw err;
+		}
+		return toTaskConfig(deepClone(DEFAULT_PROJECT_CONFIG));
+	}
+}

package/extensions/taskplane/context-window.ts

@@ -0,0 +1,66 @@
+/**
+ * Context Window Resolution Utilities
+ *
+ * Canonical home for context window resolution logic used when spawning workers.
+ *
+ * The original `resolveContextWindow(config: TaskConfig, ctx: ExtensionContext)` signature
+ * has been adapted to accept only the fields it actually uses, avoiding a dependency
+ * on the task-runner-internal `TaskConfig` type. Behavior is identical.
+ *
+ * @since TP-161
+ */
+
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+// ── Context Window Constants ──────────────────────────────────────────
+
+/** Default fallback context window when neither config nor model provides a value. */
+export const FALLBACK_CONTEXT_WINDOW: number = 200_000;
+
+// ── Context Window Resolution ─────────────────────────────────────────
+
+/**
+ * Resolve the effective context window size for worker spawning.
+ *
+ * Resolution order (first non-zero value wins):
+ *   1. Explicit user config (configuredWindow > 0)
+ *   2. Auto-detect from pi model registry (ctx.model.contextWindow)
+ *   3. Fallback to 200K tokens
+ *
+ * A configuredWindow of 0 (or undefined) signals "auto-detect" — the default
+ * when no explicit value is configured. This allows pi's model registry to
+ * provide the real context window for the active model.
+ *
+ * @param configuredWindow - The `worker_context_window` from config (0 = auto-detect)
+ * @param ctx - The pi ExtensionContext for model registry auto-detection, or null
+ * @returns Object with `contextWindow` (resolved size) and `source` (diagnostic label)
+ *
+ * @example
+ * // With explicit config
+ * resolveContextWindow(500_000, ctx) // → { contextWindow: 500000, source: "explicit config" }
+ *
+ * // With auto-detect (config = 0)
+ * resolveContextWindow(0, ctx) // → { contextWindow: 200000, source: "auto-detected from anthropic/claude-opus-4-6" }
+ *
+ * // With fallback (no config, no model)
+ * resolveContextWindow(undefined, null) // → { contextWindow: 200000, source: "fallback 200000" }
+ */
+export function resolveContextWindow(
+	configuredWindow: number | undefined,
+	ctx: ExtensionContext | null,
+): { contextWindow: number; source: string } {
+	// 1. Explicit user config — non-zero means the user set it deliberately
+	if (configuredWindow && configuredWindow > 0) {
+		return { contextWindow: configuredWindow, source: "explicit config" };
+	}
+
+	// 2. Auto-detect from pi model registry
+	const modelWindow = ctx?.model?.contextWindow;
+	if (modelWindow && modelWindow > 0) {
+		const modelId = ctx?.model ? `${ctx.model.provider}/${ctx.model.id}` : "unknown";
+		return { contextWindow: modelWindow, source: `auto-detected from ${modelId}` };
+	}
+
+	// 3. Fallback
+	return { contextWindow: FALLBACK_CONTEXT_WINDOW, source: `fallback ${FALLBACK_CONTEXT_WINDOW}` };
+}

package/extensions/taskplane/execution.ts

@@ -15,20 +15,11 @@ import { allocateLanes } from "./waves.ts";
 import { resolveOperatorId } from "./naming.ts";
 import { runGit } from "./git.ts";
 import { resolveTaskplanePackageFile, resolveTaskplaneAgentTemplate } from "./path-resolver.ts";
+import { resolvePointer, loadWorkspaceConfig } from "./workspace.ts";
 
 // ── Taskplane Package File Resolution ────────────────────────────────
 // getNpmGlobalRoot() and resolveTaskplanePackageFile() consolidated in path-resolver.ts (TP-157)
 
-// ── Task Runner Extension Path Resolution ────────────────────────────
-
-/**
- * Find the task-runner extension path for lane sessions.
- * @see resolveTaskplanePackageFile for resolution order
- */
-function resolveTaskRunnerExtensionPath(repoRoot: string): string {
-	return resolveTaskplanePackageFile(repoRoot, join("extensions", "task-runner.ts"));
-}
-
 // ── RPC Wrapper Path Resolution ──────────────────────────────────────
 
 /**
@@ -50,7 +41,7 @@ function resolveTaskRunnerExtensionPath(repoRoot: string): string {
 /**
  * Structured log helper for lane execution.
  *
- * All execution logs go to stderr (same pattern as task-runner.ts).
+ * All execution logs go to stderr.
  * Format: [orch] {laneId}/{taskId}: {message}
  * Correlation fields: batchId, laneId, taskId, sessionName.
  * No PII — only IDs and paths.
@@ -378,9 +369,8 @@ export function resolveCanonicalTaskPaths(
 
 	if (isWorkspaceMode) {
 		// Workspace mode: use worktree-relative path when the task folder is
-		// inside the lane's repo (same logic as TASK_AUTOSTART resolution).
-		// The worker writes .DONE and STATUS.md in the worktree, so the engine
-		// must look there too.
+		// inside the lane's repo. The worker writes .DONE and STATUS.md in
+		// the worktree, so the engine must look there too.
 		if (folderNorm.startsWith(repoRootNorm + "/")) {
 			const relPath = folderNorm.slice(repoRootNorm.length + 1);
 			resolvedFolder = join(worktreePath, relPath);
@@ -1392,7 +1382,7 @@ export function computeTransitiveDependents(
  *
  * Git worktrees only contain tracked (committed) files. If a user creates
  * task folders (PROMPT.md, STATUS.md) but doesn't commit them, the worktree
- * won't have those files and TASK_AUTOSTART will fail with "file not found".
+ * won't have those files and the worker will fail with "file not found".
  *
  * This function checks each wave task's folder for untracked or modified files,
  * stages them, and creates a commit on the current branch. This must run BEFORE
@@ -1640,7 +1630,7 @@ export function ensureTaskFilesCommitted(
 /**
  * Runtime backend selector for lane execution.
  *
- * - `"legacy"`: Session-backed path (spawnLaneSession → task-runner TASK_AUTOSTART)
+ * - `"legacy"`: Session-backed path (spawnLaneSession, deprecated)
  * - `"v2"`: Direct-child path (lane-runner → agent-host → pi --mode rpc)
  *
  * @since TP-105
@@ -1677,7 +1667,7 @@ export async function executeWave(
 	// ── Stage 0: Ensure task files are committed ────────────────
 	// Task folders may contain untracked files (PROMPT.md, STATUS.md) that
 	// won't appear in worktrees unless committed. Stage and commit them now,
-	// before worktree creation, so workers can find their TASK_AUTOSTART paths.
+	// before worktree creation, so workers can find their task files.
 	// Pass orchBranch so the staging commit is reflected in the orch branch
 	// before worktrees are allocated from it.
 	try {
@@ -2257,6 +2247,110 @@ function loadLocalAgentPrompt(stateRoot: string, agentName: string): string {
 	return "";
 }
 
+// ── Agent Definition Loading ─────────────────────────────────────────
+
+/** Track whether an agent pointer warning has been logged this session (log once). */
+let _execPointerWarningLogged = false;
+
+/**
+ * Reset agent pointer warning state for testing.
+ * @since TP-161
+ */
+export function resetPointerWarning(): void {
+	_execPointerWarningLogged = false;
+}
+
+/**
+ * Resolve agent files using the workspace pointer (workspace mode only).
+ * Returns the agentRoot from the pointer, or null in repo mode / on failure.
+ */
+function resolveAgentPointerRoot(): string | null {
+	const wsRoot = process.env.TASKPLANE_WORKSPACE_ROOT;
+	if (!wsRoot) return null;
+	try {
+		const wsConfig = loadWorkspaceConfig(wsRoot);
+		const result = resolvePointer(wsRoot, wsConfig);
+		if (result?.warning && !_execPointerWarningLogged) {
+			_execPointerWarningLogged = true;
+			console.error(`[execution] pointer: ${result.warning}`);
+		}
+		return result?.agentRoot ?? null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Load a complete agent definition (systemPrompt + tools + model) by name.
+ *
+ * Resolution order:
+ *   1. cwd/.pi/agents/<name>.md
+ *   2. cwd/agents/<name>.md
+ *   3. pointer.agentRoot/<name>.md (workspace mode only)
+ *   4. Base package templates/agents/<name>.md
+ *
+ * If a local file has `standalone: true` in frontmatter, it is used as-is
+ * (no base composition). Otherwise, base + local are composed.
+ *
+ * @param cwd - Working directory (project root) to search for local agent files
+ * @param name - Agent name (e.g., "task-worker", "task-reviewer")
+ * @returns Composed agent definition, or null if no base and no local file found
+ * @since TP-161
+ */
+export function loadAgentDef(cwd: string, name: string): { systemPrompt: string; tools: string; model: string } | null {
+	const localPaths = [
+		join(cwd, ".pi", "agents", `${name}.md`),
+		join(cwd, "agents", `${name}.md`),
+	];
+
+	// In workspace mode, add pointer-resolved agent root as fallback
+	const agentRoot = resolveAgentPointerRoot();
+	if (agentRoot) {
+		localPaths.push(join(agentRoot, `${name}.md`));
+	}
+
+	// Load base from package
+	let baseDef: { fm: Record<string, string>; body: string } | null = null;
+	try {
+		const basePath = resolveTaskplaneAgentTemplate(name);
+		if (existsSync(basePath)) {
+			baseDef = parseAgentFile(basePath);
+		}
+	} catch { /* fall through */ }
+
+	// Load local override (first found wins)
+	let localDef: { fm: Record<string, string>; body: string } | null = null;
+	for (const p of localPaths) {
+		localDef = parseAgentFile(p);
+		if (localDef) break;
+	}
+
+	// No base and no local → null
+	if (!baseDef && !localDef) return null;
+
+	// Local with standalone: true → use local as-is, ignore base
+	if (localDef?.fm.standalone === "true") {
+		return {
+			systemPrompt: localDef.body,
+			tools: localDef.fm.tools || "read,grep,find,ls",
+			model: localDef.fm.model || "",
+		};
+	}
+
+	// Compose base + local
+	const basePrompt = baseDef?.body || "";
+	const localPrompt = localDef?.body || "";
+	const composedPrompt = localPrompt
+		? basePrompt + "\n\n---\n\n## Project-Specific Guidance\n\n" + localPrompt
+		: basePrompt;
+
+	// Local frontmatter overrides base (tools, model)
+	const tools = localDef?.fm.tools || baseDef?.fm.tools || "read,grep,find,ls";
+	const model = localDef?.fm.model || baseDef?.fm.model || "";
+
+	return { systemPrompt: composedPrompt.trim(), tools, model };
+}
+
 export function resolveRuntimeStateRoot(
 	repoRoot: string,
 	workspaceRoot?: string,

package/extensions/taskplane/extension.ts

@@ -426,6 +426,26 @@ export function executeIntegration(
 ): IntegrationResult {
 	const { orchBranch, currentBranch, batchId } = context;
 
+	// Check if the orch branch is already an ancestor of the current branch
+	// (i.e., already merged — supervisor may have done a manual conflict resolution).
+	// If so, skip the merge entirely and go straight to cleanup.
+	const alreadyMergedCheck = deps.runGit(["merge-base", "--is-ancestor", orchBranch, "HEAD"]);
+	if (alreadyMergedCheck.ok) {
+		return performCleanup(deps, orchBranch, {
+			success: true,
+			integratedLocally: true,
+			commitCount: "0",
+			message:
+				`✅ Already integrated \u2014 all task work is present in \`${currentBranch}\`.\n` +
+				`\n` +
+				`The orch branch was merged manually (e.g., during conflict resolution) before\n` +
+				`this command ran. No additional merge was needed.\n` +
+				`\n` +
+				`🧹 Running cleanup: removing orch branch and clearing batch state.`,
+			error: "",
+		});
+	}
+
 	if (mode === "ff") {
 		// Fast-forward merge.
 		// Stash any dirty working tree files first — workspace mode leaves