@danypops/papyrus 0.2.0 → 0.3.0

package/README.md

@@ -81,7 +81,7 @@ The `papyrus_*` tools are the low-level graph-store API:
 
 Agent-facing domain tools own lifecycle invariants and sit above this store API:
 
-- **`tasks`** — create/list/show/plan, replace evidence-bearing checklists, hierarchy/dependencies, start/fail/retry, non-blocking gates, and gate-enforced completion with automatic activation of newly ready successors
+- **`tasks`** — create/list/show/plan, manage the singleton active focus, replace evidence-bearing checklists, hierarchy/dependencies, lifecycle transitions, non-blocking gates, and review completion that focuses one deterministic ready successor without claiming effort
 - **`docs`** — create/list/show, activate/archive/reopen, and document-safe graph links
 - **`rules`** — create/list/show/preview, enable/disable, and attach governance gates to tasks
 - **`skills`** — create/list/show/invoke, enable/disable, create templates, and instantiate templates
@@ -105,12 +105,28 @@ Run `/tasks` for the interactive task panel:
 
 - `/` filters; arrow keys navigate; Enter opens task actions
 - `g` opens the programmatic Unicode graph; Tab switches dependency/composition views and arrow keys pan
-- advance the `pending → active → done` lifecycle or retry `failed → pending`
-- completing an active task runs only that task’s gates; success marks it done and activates every direct pending successor whose full prerequisite set is done
-- successors are never auto-completed: each must pass its own gates; fan-in, fan-out, diamonds, and disconnected DAGs remain explicit
-- inspect deterministic execution layers, readiness, a nested task hierarchy, composition, dependencies, evidence-bearing checklists, and verification gates
-- Show details keeps Checklist and Validation gates separate from incidental Metadata, then renders relationships as a Unicode graph footer; `↑/↓` scrolls and `←/→` pans wide graphs
-- the compact persistent widget shows active work in containment order, indents active children beneath active parents, and points to `/tasks` for the complete graph
+- advance the `todo → in-progress → review → done` lifecycle; failed review becomes `rejected`, retry returns to `in-progress`, and `canceled` is terminal
+- use **active** only as the independent singleton focus that auto-drive continues; focusing a task never changes its lifecycle
+- starting nested effort moves todo ancestors to in-progress; submitting enters review; completing review checks both typed checklist proofs and executable gates
+- passing review marks only that task done and focuses one deterministic ready successor while leaving the successor todo until effort starts
+- successors are never auto-completed; fan-in, fan-out, diamonds, and disconnected DAGs remain explicit
+- inspect deterministic execution layers, readiness, a box-drawn nested hierarchy, composition, dependencies, evidence-bearing checklists, and verification gates
+- lifecycle colors are semantic and redundant with text/glyphs: To-Do grey, in-progress yellow, review blue, rejected orange, done green, and canceled red; `▶` marks active focus
+- Show details keeps Checklist and Validation gates separate from incidental Metadata, then renders relationships as a Unicode box-drawing graph footer; `↑/↓` scrolls and `←/→` pans wide graphs
+- the compact persistent widget shows bounded open work in containment order and always retains the active focus
+
+Authenticated CLI parity covers the changed lifecycle and focus operations:
+
+```bash
+papyrus tasks active --json
+papyrus tasks focus <id> --json
+papyrus tasks start <id> --json
+papyrus tasks submit <id> --json
+papyrus tasks complete <id> --json
+papyrus tasks reject <id> --json
+papyrus tasks retry <id> --json
+papyrus tasks cancel <id> --json
+```
 
 Checklist criteria are an item-to-proof map. Every new item requires one or more typed references to inspectable evidence; proof presence does not imply that the evidence passed an executable gate:
 
@@ -127,9 +143,9 @@ checklist: {
 
 Proof types are `file`, `symbol`, `code`, `test`, `command`, `artifact`, and `url`. Existing array checklists remain readable as legacy items with `proof: missing`; Papyrus does not invent evidence.
 
-Papyrus also injects an Alef-style reconciliation block on every agent turn while work remains: `Current`, `Desired`, `Verify`, and `Next`. The agent is explicitly instructed to ask **“Did we accomplish this task?”** and run gates before marking it done. The injection disappears when every task is complete.
+Papyrus also injects an Alef-style reconciliation block on every agent turn while work remains: `Current`, `Desired`, `Verify`, and `Next`. The agent is explicitly instructed to ask **“Did we accomplish this task?”** and run review before marking it done. The injection disappears when every task is done or canceled.
 
-In TUI and RPC modes, the extension checks bounded active Tasks at Pi’s public `agent_settled` lifecycle boundary. If active work remains and no continuation is already pending, it queues one hidden next turn so the agent continues instead of handing off merely because a low-level run ended. Driving is single-flight and pauses after 20 automatic turns or 6 unchanged task snapshots. Use `/task-drive on`, `/task-drive off`, or `/task-drive status`; human input and task progress reset the bounded counters.
+In TUI and RPC modes, the extension checks the singleton active focus at Pi’s public `agent_settled` lifecycle boundary. If a focused task remains and no continuation is already pending, it queues one hidden next turn. No manual driving command is required. Driving is single-flight and pauses after 20 automatic turns or 6 unchanged task snapshots; human input and task progress reset the bounded counters automatically.
 
 ## Why
 
@@ -140,12 +156,20 @@ Papyrus keeps SQLite’s local simplicity while centralizing writes, migrations,
 Install the published Pi package, then install its supervised user service:
 
 ```bash
-pi install npm:@danypops/papyrus
+packed install npm:@danypops/papyrus
 ~/.pi/agent/npm/node_modules/.bin/papyrus service install
 ```
 
+Existing databases are never migrated on daemon boot. After upgrading across the task-lifecycle schema boundary, run the authenticated CLI migration explicitly:
+
+```bash
+~/.pi/agent/npm/node_modules/.bin/papyrus migrate task-lifecycle
+```
+
+Until that command succeeds, health reports `migrationRequired` and normal domain operations are rejected with actionable guidance. Migration is not exposed as a Pi tool or MCP action. New empty databases bootstrap directly at the current schema.
+
 Reload Pi once the service is active. Git installs remain available for development builds:
 
 ```bash
-pi install git:github.com/DanyPops/papyrus
+packed install git:github.com/DanyPops/papyrus
 ```

package/extension/src/{task-driver.ts → active-task-continuation.ts}

@@ -4,71 +4,62 @@ export interface ActiveTaskMarker {
 	updated_at: string;
 }
 
-export interface TaskDriverOptions {
+export interface ActiveTaskContinuationOptions {
 	maxTurns: number;
 	maxUnchangedTurns: number;
 }
 
-export interface TaskDriverState {
-	enabled: boolean;
+export interface ActiveTaskContinuationState {
 	queued: boolean;
 	consecutiveTurns: number;
 	unchangedTurns: number;
 	pausedReason?: string;
 }
 
-export interface TaskDriverDecision {
+export interface ActiveTaskContinuationDecision {
 	action: "continue" | "wait" | "pause";
 	reason: string;
 	prompt?: string;
 }
 
-const DISPLAYED_TASK_LIMIT = 3;
 const TITLE_LIMIT = 120;
 
-function fingerprint(tasks: ActiveTaskMarker[]): string {
-	return [...tasks]
-		.sort((left, right) => left.id.localeCompare(right.id))
-		.map((task) => `${task.id}:${task.updated_at}`)
-		.join("|");
+function fingerprint(task: ActiveTaskMarker): string {
+	return `${task.id}:${task.updated_at}`;
 }
 
-function continuationPrompt(tasks: ActiveTaskMarker[]): string {
-	const names = tasks.slice(0, DISPLAYED_TASK_LIMIT).map((task) => `- ${task.id}: ${task.title.slice(0, TITLE_LIMIT)}`);
+function continuationPrompt(task: ActiveTaskMarker): string {
 	return [
-		"Continue active Papyrus work now; do not hand off merely because the previous Pi run settled.",
-		"Reconcile the active Tasks, choose the next concrete action, use tools, run gates before completion, and continue until done, blocked, or the bounded task driver pauses.",
-		"Active tasks:",
-		...names,
+		"Continue the active Papyrus Task now; do not hand off merely because the previous Pi run settled.",
+		"Reconcile its lifecycle, take the next concrete action, use tools, submit it for review when implementation effort is ready, and run gates plus checklist review before completion.",
+		`Active task: ${task.id}: ${task.title.slice(0, TITLE_LIMIT)}`,
 	].join("\n");
 }
 
-export class TaskDriver {
-	private enabled = true;
+export class ActiveTaskContinuation {
 	private queued = false;
 	private consecutiveTurns = 0;
 	private unchangedTurns = 0;
 	private lastFingerprint: string | undefined;
 	private pausedReason: string | undefined;
 
-	constructor(private readonly options: TaskDriverOptions) {
+	constructor(private readonly options: ActiveTaskContinuationOptions) {
 		if (!Number.isInteger(options.maxTurns) || options.maxTurns < 1) throw new Error("maxTurns must be a positive integer");
 		if (!Number.isInteger(options.maxUnchangedTurns) || options.maxUnchangedTurns < 1) {
 			throw new Error("maxUnchangedTurns must be a positive integer");
 		}
 	}
 
-	evaluate(tasks: ActiveTaskMarker[], context: { idle: boolean; pendingMessages: boolean }): TaskDriverDecision {
-		if (!this.enabled) return { action: "wait", reason: "disabled" };
+	evaluate(task: ActiveTaskMarker | null, context: { idle: boolean; pendingMessages: boolean }): ActiveTaskContinuationDecision {
 		if (!context.idle) return { action: "wait", reason: "Pi is not settled" };
 		if (context.pendingMessages) return { action: "wait", reason: "Pi already has pending messages" };
 		if (this.queued) return { action: "wait", reason: "continuation already queued" };
-		if (tasks.length === 0) {
+		if (!task) {
 			this.resetProgress();
-			return { action: "wait", reason: "no active tasks" };
+			return { action: "wait", reason: "no active task" };
 		}
 
-		const currentFingerprint = fingerprint(tasks);
+		const currentFingerprint = fingerprint(task);
 		if (currentFingerprint !== this.lastFingerprint) {
 			this.lastFingerprint = currentFingerprint;
 			this.unchangedTurns = 0;
@@ -88,8 +79,8 @@ export class TaskDriver {
 		this.consecutiveTurns += 1;
 		return {
 			action: "continue",
-			reason: "active tasks remain",
-			prompt: continuationPrompt(tasks),
+			reason: "an active task remains",
+			prompt: continuationPrompt(task),
 		};
 	}
 
@@ -101,15 +92,8 @@ export class TaskDriver {
 		this.resetProgress();
 	}
 
-	setEnabled(enabled: boolean): void {
-		this.enabled = enabled;
-		if (enabled) this.resetProgress();
-		else this.queued = false;
-	}
-
-	status(): TaskDriverState {
+	status(): ActiveTaskContinuationState {
 		return {
-			enabled: this.enabled,
 			queued: this.queued,
 			consecutiveTurns: this.consecutiveTurns,
 			unchangedTurns: this.unchangedTurns,
@@ -117,7 +101,7 @@ export class TaskDriver {
 		};
 	}
 
-	private pause(reason: string): TaskDriverDecision {
+	private pause(reason: string): ActiveTaskContinuationDecision {
 		this.pausedReason = reason;
 		return { action: "pause", reason };
 	}

package/extension/src/artifact-format.ts

@@ -6,10 +6,12 @@ import {
 } from "../../src/constants.ts";
 
 const STATUS_GLYPHS: Record<string, string> = {
-	pending: "○",
-	active: "●",
+	todo: "○",
+	"in-progress": "●",
+	review: "◆",
+	rejected: "▲",
 	done: "■",
-	failed: "▲",
+	canceled: "×",
 };
 
 export interface MetadataFormatOptions {

package/extension/src/domain-tools.ts

@@ -29,7 +29,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "tasks",
 		label: "Tasks",
-		description: "Task domain tool. ACTIONS: create, list, show, plan, start, complete (runs gates, refuses done on failure, and starts newly ready successors), fail, retry, run_gates, set_checklist, depend, contain. Dependency graphs support deterministic execution layers, fan-in, and fan-out; cycles are rejected. Checklist is an item-to-proof map; every item requires one or more typed evidence references. Prefer this over low-level papyrus_* tools for task work.",
+		description: "Task domain tool. ACTIONS: create, list, show, plan, active, focus, start, submit, complete, reject, retry, cancel, run_gates, set_checklist, depend, contain. Lifecycle is todo → in-progress → review → done, with review failure → rejected and retry → in-progress; canceled is terminal. Active focus is independent and identifies the one task auto-drive continues. Completion runs gates and checklist-proof review, then focuses one deterministic ready successor without claiming effort. Dependency cycles are rejected. Prefer this over low-level papyrus_* tools for task work.",
 		parameters: Type.Object({
 			action: Type.String(),
 			id: Type.Optional(Type.String()),
@@ -63,6 +63,10 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 					const artifact = await callService<Record<string, unknown>, Artifact>("tasks.show", params);
 					return text(`${artifactLine(artifact)}\n\n${artifact.body}`, { artifact });
 				}
+				if (action === "active") {
+					const artifact = await callService<Record<string, unknown>, Artifact | null>("tasks.active", params);
+					return text(artifact ? `Active: ${artifactLine(artifact)}` : "No active task.", { artifact });
+				}
 				if (action === "plan") {
 					const plan = await callService<Record<string, unknown>, TaskExecutionPlan>("tasks.plan", params);
 					const byId = new Map(plan.nodes.map((node) => [node.id, node]));
@@ -83,17 +87,27 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 				if (action === "complete") {
 					const result = await callService<Record<string, unknown>, TaskCompletion>("tasks.complete", params);
 					const gates = result.gates.map((gate) => `${gate.passed ? "✓" : "✗"} ${gate.gate.type}: ${gate.gate.target} — ${gate.output}`).join("\n");
-					const started = result.started.length > 0 ? `\nStarted: ${result.started.map(artifactLine).join(", ")}` : "";
+					const checklist = result.checklist.map((item) => `${item.accepted ? "✓" : "✗"} proof: ${item.item}${item.reason ? ` — ${item.reason}` : ""}`).join("\n");
+					const focused = result.focused ? `\nActive: ${artifactLine(result.focused)}` : "";
 					const blocked = result.blocked.length > 0
 						? `\nBlocked: ${result.blocked.map((entry) => `${artifactLine(entry.artifact)} waits for ${entry.dependencyIds.join(", ")}`).join("; ")}`
 						: "";
-					return text(`${result.completed ? "Completed" : "Not completed"}: ${artifactLine(result.artifact)}${started}${blocked}${gates ? `\n${gates}` : ""}`, { ...result });
+					return text(`${result.completed ? "Completed" : "Rejected"}: ${artifactLine(result.artifact)}${focused}${blocked}${checklist ? `\n${checklist}` : ""}${gates ? `\n${gates}` : ""}`, { ...result });
 				}
 				if (action === "run_gates") {
 					const gates = await callService<Record<string, unknown>, GateResult[]>("tasks.run_gates", params);
 					return text(gates.map((gate) => `${gate.passed ? "✓" : "✗"} ${gate.gate.type}: ${gate.gate.target} — ${gate.output}`).join("\n") || "No gates configured.", { gates });
 				}
-				const operations = { start: "tasks.start", fail: "tasks.fail", retry: "tasks.retry", depend: "tasks.depend", contain: "tasks.contain" } as const;
+				const operations = {
+					focus: "tasks.focus",
+					start: "tasks.start",
+					submit: "tasks.submit",
+					reject: "tasks.reject",
+					retry: "tasks.retry",
+					cancel: "tasks.cancel",
+					depend: "tasks.depend",
+					contain: "tasks.contain",
+				} as const;
 				const operation = operations[action as keyof typeof operations];
 				if (!operation) return text(`Unknown tasks action: ${action}`);
 				const artifact = await callService<Record<string, unknown>, Artifact>(operation, params);

package/extension/src/index.ts

@@ -11,7 +11,6 @@ import type { ExtensionAPI, ExtensionContext, ExtensionUIContext, Theme } from "
 import { Type } from "typebox";
 import { truncateToWidth } from "@earendil-works/pi-tui";
 import {
-	TASK_DRIVER_ACTIVE_LIMIT,
 	TASK_DRIVER_MAX_TURNS,
 	TASK_DRIVER_MAX_UNCHANGED_TURNS,
 } from "../../src/constants.ts";
@@ -20,9 +19,10 @@ import type { GateResult } from "../../src/domain/gate.ts";
 import { formatMetadata } from "./artifact-format.ts";
 import { callService } from "./service-client.ts";
 import { registerDomainTools } from "./domain-tools.ts";
-import type { TaskGraph } from "../../src/task-service.ts";
-import { TaskDriver, type ActiveTaskMarker } from "./task-driver.ts";
+import type { TaskGraph, TaskStatus } from "../../src/task-service.ts";
+import { ActiveTaskContinuation, type ActiveTaskMarker } from "./active-task-continuation.ts";
 import { buildTaskWidgetProjection } from "./task-widget.ts";
+import { TASK_STATUS_PRESENTATION, taskTreeConnector } from "./task-presentation.ts";
 
 function text(t: string, details: Record<string, unknown> = {}) {
 	return { content: [{ type: "text" as const, text: t }], details };
@@ -32,13 +32,6 @@ function text(t: string, details: Record<string, unknown> = {}) {
 // Task widget (TodoOverlay pattern from rpiv-todo: factory form, requestRender)
 // ---------------------------------------------------------------------------
 
-const GLYPHS: Record<string, (theme: Theme) => string> = {
-	pending:   (t) => t.fg("dim", "○"),
-	active:    (t) => t.fg("warning", "●"),
-	done:      (t) => t.fg("success", "■"),
-	failed:    (t) => t.fg("error", "▲"),
-};
-
 const WIDGET_KEY = "pi-papyrus";
 
 class TaskOverlay {
@@ -103,22 +96,26 @@ class TaskOverlay {
 		const projection = buildTaskWidgetProjection(this.snapshot);
 		if (projection.total === 0) return [];
 
-		if (projection.activeTotal === 0) {
-			return [truncateToWidth(theme.bold("Tasks · no active tasks · /tasks"), width, "…")];
+		if (projection.openTotal === 0) {
+			return [truncateToWidth(theme.bold("Tasks · no open tasks · /tasks"), width, "…")];
 		}
 
+		const active = projection.rows.find((row) => row.active);
 		const lines = [
 			truncateToWidth(
-				theme.bold(`Tasks · ${GLYPHS.active!(theme)} ${projection.activeTotal} active`),
+				theme.bold(`Tasks · ${active ? theme.fg("accent", "▶ active") : "no active focus"} · ${projection.openTotal} open`),
 				width,
 				"…",
 			),
 		];
-		for (const row of projection.active) {
-			const hierarchy = row.depth === 0
-				? row.hasActiveChildren ? "▾" : "·"
-				: `${"  ".repeat(row.depth)}↳`;
-			lines.push(truncateToWidth(`  ${hierarchy} ${GLYPHS.active!(theme)} ${row.task.title}`, width, "…"));
+		for (let index = 0; index < projection.rows.length; index++) {
+			const row = projection.rows[index]!;
+			const laterSibling = projection.rows.slice(index + 1).some((candidate) => candidate.depth === row.depth);
+			const hierarchy = taskTreeConnector({ depth: row.depth, hasChildren: row.hasOpenChildren, hasLaterSibling: laterSibling });
+			const focus = row.active ? theme.fg("accent", "▶") : " ";
+			const presentation = TASK_STATUS_PRESENTATION[row.task.status as TaskStatus];
+			const glyph = presentation ? theme.fg(presentation.color, presentation.glyph) : theme.fg("muted", "?");
+			lines.push(truncateToWidth(`${focus} ${hierarchy} ${glyph} ${row.task.title}`, width, "…"));
 		}
 		return lines;
 	}
@@ -137,7 +134,7 @@ class TaskOverlay {
 
 export default async function (pi: ExtensionAPI) {
 	registerDomainTools(pi);
-	const taskDriver = new TaskDriver({
+	const taskContinuation = new ActiveTaskContinuation({
 		maxTurns: TASK_DRIVER_MAX_TURNS,
 		maxUnchangedTurns: TASK_DRIVER_MAX_UNCHANGED_TURNS,
 	});
@@ -145,11 +142,8 @@ export default async function (pi: ExtensionAPI) {
 	const driveActiveTasks = async (ctx: ExtensionContext): Promise<void> => {
 		if (ctx.mode !== "tui" && ctx.mode !== "rpc") return;
 		try {
-			const active = await callService<Record<string, unknown>, ActiveTaskMarker[]>("tasks.list", {
-				status: "active",
-				limit: TASK_DRIVER_ACTIVE_LIMIT,
-			});
-			const decision = taskDriver.evaluate(active, {
+			const active = await callService<Record<string, never>, ActiveTaskMarker | null>("tasks.active", {});
+			const decision = taskContinuation.evaluate(active, {
 				idle: ctx.isIdle(),
 				pendingMessages: ctx.hasPendingMessages(),
 			});
@@ -160,40 +154,13 @@ export default async function (pi: ExtensionAPI) {
 					display: false,
 				}, { triggerTurn: true, deliverAs: "nextTurn" });
 			} else if (decision.action === "pause" && ctx.hasUI) {
-				ctx.ui.notify(`Papyrus task driving paused: ${decision.reason}. Use /task-drive on to resume.`, "warning");
+				ctx.ui.notify(`Papyrus task driving paused: ${decision.reason}. Human input or task progress resumes it automatically.`, "warning");
 			}
 		} catch {
 			// The daemon may be unavailable during startup, reload, or shutdown.
 		}
 	};
 
-	pi.registerCommand("task-drive", {
-		description: "Control bounded automatic continuation while active Papyrus Tasks remain",
-		handler: async (args, ctx) => {
-			const action = args.trim().toLowerCase() || "status";
-			if (action === "on") {
-				taskDriver.setEnabled(true);
-				ctx.ui.notify("Papyrus task driving enabled", "info");
-				await driveActiveTasks(ctx);
-				return;
-			}
-			if (action === "off") {
-				taskDriver.setEnabled(false);
-				ctx.ui.notify("Papyrus task driving disabled", "info");
-				return;
-			}
-			if (action !== "status") {
-				ctx.ui.notify("Usage: /task-drive <on|off|status>", "warning");
-				return;
-			}
-			const status = taskDriver.status();
-			ctx.ui.notify(
-				`Papyrus task driving: ${status.enabled ? "on" : "off"} · ${status.consecutiveTurns}/${TASK_DRIVER_MAX_TURNS} automatic turns${status.pausedReason ? ` · paused: ${status.pausedReason}` : ""}`,
-				"info",
-			);
-		},
-	});
-
 	// ── Low-level graph-store tools ────────────────────────────────────
 
 	pi.registerTool({
@@ -393,13 +360,13 @@ export default async function (pi: ExtensionAPI) {
 	// retry, compaction retry, and queued follow-up processing have finished.
 
 	pi.on("input", (event) => {
-		if (event.source !== "extension") taskDriver.onHumanInput();
+		if (event.source !== "extension") taskContinuation.onHumanInput();
 	});
-	pi.on("agent_start", () => { taskDriver.onAgentStart(); });
+	pi.on("agent_start", () => { taskContinuation.onAgentStart(); });
 	pi.on("agent_settled", async (_event, ctx) => { await driveActiveTasks(ctx); });
 
 	// ── "Are we there yet?" — inject active tasks into every turn ──────
-	// The agent sees its open work items every turn. If there are failed
+	// The agent sees its open work items every turn. If there are rejected
 	// tasks, they're explicitly called out — the agent should address them.
 
 	pi.on("before_agent_start", async (event, _ctx) => {

package/extension/src/task-detail-format.ts

@@ -3,10 +3,12 @@ import { checklistEntries, type ProofReference } from "../../src/domain/checklis
 import { formatMetadata } from "./artifact-format.ts";
 
 const TASK_STATUS_GLYPHS: Record<string, string> = {
-	pending: "○",
-	active: "●",
+	todo: "○",
+	"in-progress": "●",
+	review: "◆",
+	rejected: "▲",
 	done: "■",
-	failed: "▲",
+	canceled: "×",
 };
 
 function proofLine(proof: ProofReference): string {

package/extension/src/task-graph.ts

@@ -10,9 +10,18 @@ import type { GraphRenderer } from "../../src/ports/graph-renderer.ts";
 import { projectTaskGraph, type TaskGraphView } from "../../src/task-graph-view.ts";
 import type { TaskGraph } from "../../src/task-service.ts";
 import { BeautifulMermaidRenderer } from "./beautiful-mermaid-renderer.ts";
+import { TASK_STATUS_PRESENTATION } from "./task-presentation.ts";
 
 const GRAPH_VIEWS: TaskGraphView[] = ["execution", "dependencies", "composition"];
 
+export function colorizeTaskGraphLine(theme: Theme, line: string): string {
+	let colored = line;
+	for (const presentation of Object.values(TASK_STATUS_PRESENTATION)) {
+		colored = colored.replaceAll(presentation.glyph, theme.fg(presentation.color, presentation.glyph));
+	}
+	return colored.replaceAll("▶", theme.fg("accent", "▶"));
+}
+
 export class TaskGraphViewport {
 	private viewIndex = 0;
 	private offsetX = 0;
@@ -51,7 +60,8 @@ export class TaskGraphViewport {
 			truncateToWidth(this.theme.bold(`Task graph · ${GRAPH_VIEWS[this.viewIndex]}`), contentWidth, ""),
 			truncateToWidth(this.theme.fg("dim", `Tab switch · arrows pan · Esc back${position}`), contentWidth, ""),
 			border,
-			...this.graphLines.slice(this.offsetY, end).map((line) => sliceByColumn(line, this.offsetX, contentWidth, true)),
+			...this.graphLines.slice(this.offsetY, end).map((line) =>
+				colorizeTaskGraphLine(this.theme, sliceByColumn(line, this.offsetX, contentWidth, true))),
 			border,
 		];
 	}

package/extension/src/task-presentation.ts

@@ -0,0 +1,26 @@
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
+import type { TaskStatus } from "../../src/task-service.ts";
+
+export interface TaskStatusPresentation {
+	label: string;
+	glyph: string;
+	color: ThemeColor;
+}
+
+export const TASK_STATUS_PRESENTATION: Record<TaskStatus, TaskStatusPresentation> = {
+	todo: { label: "To-Do", glyph: "○", color: "muted" },
+	"in-progress": { label: "in-progress", glyph: "●", color: "warning" },
+	review: { label: "review", glyph: "◆", color: "mdLink" },
+	rejected: { label: "rejected", glyph: "▲", color: "accent" },
+	done: { label: "done", glyph: "■", color: "success" },
+	canceled: { label: "canceled", glyph: "×", color: "error" },
+};
+
+export function taskTreeConnector(options: {
+	depth: number;
+	hasChildren: boolean;
+	hasLaterSibling: boolean;
+}): string {
+	if (options.depth === 0) return options.hasChildren ? "▾" : "·";
+	return `${"│ ".repeat(Math.max(0, options.depth - 1))}${options.hasLaterSibling ? "├─" : "└─"}`;
+}

package/extension/src/task-widget.ts

@@ -1,49 +1,56 @@
-import { TASK_WIDGET_ACTIVE_LIMIT } from "../../src/constants.ts";
+import { TASK_WIDGET_OPEN_LIMIT } from "../../src/constants.ts";
 import type { Artifact } from "../../src/domain/artifact.ts";
 import type { TaskGraph } from "../../src/task-service.ts";
 
 export interface TaskWidgetRow {
 	task: Artifact;
 	depth: number;
-	hasActiveChildren: boolean;
+	hasOpenChildren: boolean;
+	active: boolean;
 }
 
 export interface TaskWidgetProjection {
-	active: TaskWidgetRow[];
-	activeTotal: number;
+	rows: TaskWidgetRow[];
+	openTotal: number;
 	total: number;
 }
 
-/** Keep active work in containment order; /tasks owns full graph navigation. */
+function isOpen(task: Artifact): boolean {
+	return task.status !== "done" && task.status !== "canceled";
+}
+
+/** Keep bounded actionable work in containment order while always retaining active focus. */
 export function buildTaskWidgetProjection(
 	graph: TaskGraph,
-	activeLimit = TASK_WIDGET_ACTIVE_LIMIT,
+	openLimit = TASK_WIDGET_OPEN_LIMIT,
 ): TaskWidgetProjection {
-	const visibleNodes = graph.nodes.filter((node) => node.task.status !== "deleted");
-	const byId = new Map(visibleNodes.map((node) => [node.task.id, node]));
+	const byId = new Map(graph.nodes.map((node) => [node.task.id, node]));
 	const visited = new Set<string>();
 	const ordered: TaskWidgetRow[] = [];
 
-	const visit = (id: string, activeDepth: number): void => {
+	const visit = (id: string, openDepth: number): void => {
 		if (visited.has(id)) return;
 		const node = byId.get(id);
 		if (!node) return;
 		visited.add(id);
-		const active = node.task.status === "active";
-		if (active) ordered.push({ task: node.task, depth: activeDepth, hasActiveChildren: false });
-		const childDepth = active ? activeDepth + 1 : activeDepth;
+		const open = isOpen(node.task);
+		if (open) ordered.push({ task: node.task, depth: openDepth, hasOpenChildren: false, active: node.active === true });
+		const childDepth = open ? openDepth + 1 : openDepth;
 		for (const childId of node.childIds) visit(childId, childDepth);
 	};
 
 	for (const rootId of graph.rootIds) visit(rootId, 0);
-	for (const node of visibleNodes) visit(node.task.id, 0);
+	for (const node of graph.nodes) visit(node.task.id, 0);
 	for (let index = 0; index < ordered.length - 1; index++) {
-		ordered[index]!.hasActiveChildren = ordered[index + 1]!.depth > ordered[index]!.depth;
+		ordered[index]!.hasOpenChildren = ordered[index + 1]!.depth > ordered[index]!.depth;
 	}
-	const active = ordered.slice(0, Math.max(0, activeLimit));
-	return {
-		active,
-		activeTotal: ordered.length,
-		total: visibleNodes.length,
-	};
+
+	const limit = Math.max(0, openLimit);
+	let rows = ordered.slice(0, limit);
+	const active = ordered.find((row) => row.active);
+	if (active && !rows.some((row) => row.task.id === active.task.id) && limit > 0) {
+		rows = [...rows.slice(0, Math.max(0, limit - 1)), active]
+			.sort((left, right) => ordered.indexOf(left) - ordered.indexOf(right));
+	}
+	return { rows, openTotal: ordered.length, total: graph.nodes.length };
 }