pi-worklist 0.1.0

package/AGENTS.md

@@ -0,0 +1,10 @@
+# pi-worklist agent notes
+
+- Read Pi's installed `docs/extensions.md`, `docs/tui.md`, `docs/packages.md`, and `docs/session-format.md` before changing extension APIs.
+- Session Tasks are canonical versioned custom-entry snapshots and must remain branch-aware.
+- Project Goals are canonical in `<git-root>/.pi/worklist.json` and every mutation must use the cross-process lock plus atomic rename.
+- Never add a project lifecycle path that bypasses explicit confirmation.
+- Keep the widget compact and width-safe.
+- Keep the model-facing schema compatible with Google providers by using `StringEnum` for string enums.
+- Run `npm run check`, `npm audit`, `npm run pack:check`, and the real Pi RPC test before release.
+- Do not manually add a changelog.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Max Miller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# pi-worklist
+
+`pi-worklist` gives Pi two deliberately different lists.
+Session Tasks track the concrete work in the current coding session.
+Project Goals track the larger outcomes shared by every Pi session in a Git repository.
+
+## Features
+
+- Branch-aware Session Tasks survive `/resume` and follow `/tree`, `/fork`, and `/clone`.
+- A new Pi session starts with an empty Session Task list.
+- Project Goals persist at `<git-root>/.pi/worklist.json` and can be committed with the repository.
+- `/tasks` opens an interactive two-section dashboard.
+- A compact widget shows the active Project Goal and up to three unfinished Session Tasks.
+- The `worklist` model tool manages both scopes through one consistent API.
+- Project Goal completion, reopening, archival, and deletion require explicit user intent.
+- Cross-process locking and atomic replacement prevent concurrent Pi processes from losing updates or corrupting the project file.
+
+## Install
+
+Install from npm after the first release:
+
+```sh
+pi install npm:pi-worklist
+```
+
+Install directly from GitHub:
+
+```sh
+pi install git:github.com/max-miller1204/pi-worklist
+```
+
+Try a checkout without installing it:
+
+```sh
+pi -e ./src/extension.ts
+```
+
+## Usage
+
+Run `/tasks` with no arguments to open the dashboard.
+Use Tab to switch lists, arrow keys to navigate, `a` to add, `e` to edit, Space or Enter to advance status, `d` to delete, and Escape to close.
+
+Direct commands are useful in RPC mode and scripts:
+
+```text
+/tasks session list
+/tasks session add Write regression tests
+/tasks session status <id> doing
+/tasks project list
+/tasks project add Replace legacy authentication
+/tasks project set_active <id>
+/tasks project complete <id>
+```
+
+Typing a Project Goal lifecycle command is explicit user intent.
+The model-facing tool instead requires `confirm=true`, and its prompt rules prohibit setting that flag without an explicit request.
+
+## Storage semantics
+
+Session Tasks are stored as versioned Pi custom entries in the current session tree.
+They do not enter model context directly.
+Only the active goal and an intentionally bounded list of incomplete tasks are added to the current turn's system prompt.
+
+Project Goals use a schema-versioned JSON file at `.pi/worklist.json` in the canonical Git root.
+The file is human-readable and suitable for version control.
+A malformed or unsupported file is reported and never overwritten automatically.
+Project Goal operations are unavailable outside a Git repository, while Session Tasks continue to work normally.
+
+## Model tool
+
+The `worklist` tool accepts `scope=session|project` and actions including `list`, `add`, `update`, `set_status`, `set_active`, `complete`, `reopen`, `archive`, and `delete`.
+Session Task statuses are `todo`, `doing`, and `done`.
+Project Goal statuses are `open`, `active`, `done`, and `archived`.
+Only activation is a non-destructive direct Project Goal status change.
+
+## Development
+
+```sh
+git clone https://github.com/max-miller1204/pi-worklist.git
+cd pi-worklist
+npm install
+npm run check
+npm run pack:check
+```
+
+The test suite includes a real Pi RPC load test in a temporary Git repository.
+The package uses TypeScript source directly because Pi loads extensions through jiti.
+
+## Publishing and the Pi gallery
+
+The package contains the `pi-package` npm keyword and a `pi.extensions` manifest.
+Publishing it to npm makes it discoverable by the package gallery at <https://pi.dev/packages> without a separate submission process.
+Run the full validation suite before `npm publish`.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,68 @@
+{
+	"name": "pi-worklist",
+	"version": "0.1.0",
+	"description": "A Pi extension for session tasks and project goals.",
+	"type": "module",
+	"keywords": [
+		"pi-package",
+		"pi",
+		"extension",
+		"worklist",
+		"tasks",
+		"goals"
+	],
+	"author": "Max Miller",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/max-miller1204/pi-worklist.git"
+	},
+	"homepage": "https://github.com/max-miller1204/pi-worklist#readme",
+	"bugs": {
+		"url": "https://github.com/max-miller1204/pi-worklist/issues"
+	},
+	"files": [
+		"src",
+		"AGENTS.md",
+		"README.md",
+		"package.json"
+	],
+	"main": "./src/extension.ts",
+	"pi": {
+		"extensions": [
+			"./src/extension.ts"
+		]
+	},
+	"scripts": {
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"typecheck": "tsc --noEmit",
+		"format": "biome format --write .",
+		"format:check": "biome format .",
+		"lint": "biome lint --write .",
+		"lint:check": "biome lint .",
+		"check": "npm run typecheck && npm run format:check && npm run lint:check && npm run test",
+		"pack:check": "npm pack --dry-run",
+		"verify": "npm run check && npm run pack:check"
+	},
+	"dependencies": {
+		"proper-lockfile": "^4.1.2"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-agent-core": "*",
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*",
+		"typebox": "*"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.2.4",
+		"@types/node": "^24.0.0",
+		"@types/proper-lockfile": "^4.1.4",
+		"typescript": "^5.9.0",
+		"vitest": "^3.2.0"
+	},
+	"engines": {
+		"node": ">=20"
+	}
+}

package/src/extension.ts

@@ -0,0 +1,228 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { WorklistParamsSchema } from "./schema.ts";
+import { readProjectWorklist } from "./project-store.ts";
+import { SessionStore } from "./session-store.ts";
+import {
+	executeWorklist,
+	formatProjectGoals,
+	formatSessionTasks,
+	getProjectPath,
+	WORKLIST_EXECUTION_MODE,
+} from "./tool.ts";
+import type { ProjectGoal, ProjectGoalStatus, SessionTaskStatus } from "./types.ts";
+import { buildPromptSummary, buildWidgetLines, Dashboard, type DashboardAction } from "./ui.ts";
+
+export interface ParsedCommand {
+	scope: "session" | "project";
+	action: string;
+	id?: string;
+	title?: string;
+	status?: SessionTaskStatus | ProjectGoalStatus;
+	confirm?: boolean;
+}
+
+export function parseTasksCommand(args: string): ParsedCommand | null {
+	const parts = args.trim().split(/\s+/).filter(Boolean);
+	if (parts.length < 2 || !["session", "project"].includes(parts[0])) return null;
+	const scope = parts.shift() as "session" | "project";
+	const action = parts.shift();
+	if (!action) return null;
+	if (action === "list") return { scope, action };
+	if (action === "add") return { scope, action, title: parts.join(" ") };
+	if (action === "update") return { scope, action, id: parts.shift(), title: parts.join(" ") };
+	if (action === "status")
+		return { scope, action: "set_status", id: parts[0], status: parts[1] as ParsedCommand["status"] };
+	if (["complete", "reopen", "archive", "delete", "set_active"].includes(action)) {
+		return { scope, action, id: parts[0], confirm: scope === "project" && action !== "set_active" };
+	}
+	return null;
+}
+
+export default function worklistExtension(pi: ExtensionAPI): void {
+	const sessionStore = new SessionStore(pi);
+	let projectPath: string | null = null;
+	let projectGoals: ProjectGoal[] = [];
+	let latestContext: ExtensionContext | undefined;
+
+	async function refreshProject(): Promise<void> {
+		if (!projectPath) {
+			projectGoals = [];
+			return;
+		}
+		const result = await readProjectWorklist(projectPath);
+		if (result.error) throw new Error(result.error);
+		projectGoals = result.data.goals;
+	}
+
+	async function updateUi(ctx: ExtensionContext): Promise<void> {
+		latestContext = ctx;
+		await refreshProject();
+		const lines = buildWidgetLines(sessionStore.getTasks(), projectGoals);
+		if (!lines.length) ctx.ui.setWidget("pi-worklist", undefined);
+		else if (ctx.mode === "tui") {
+			ctx.ui.setWidget(
+				"pi-worklist",
+				(_tui, theme) =>
+					new Text(
+						lines.map((line, index) => (index === 0 ? theme.fg("accent", line) : line)).join("\n"),
+						0,
+						0,
+					),
+			);
+		} else ctx.ui.setWidget("pi-worklist", lines);
+	}
+
+	async function execute(params: ParsedCommand, ctx: ExtensionContext) {
+		const result = await executeWorklist(params, ctx, { sessionStore, projectPath });
+		await updateUi(ctx);
+		return result;
+	}
+
+	pi.registerTool({
+		name: "worklist",
+		label: "Worklist",
+		description:
+			"Manage branch-aware session tasks or repository-wide project goals. Project complete, reopen, archive, and delete require confirm=true after explicit user intent.",
+		promptSnippet: "Manage Session Tasks and repository-scoped Project Goals",
+		promptGuidelines: [
+			"Use worklist to maintain Session Tasks for multi-step work and update them as verified work progresses.",
+			"Use worklist with scope=project only when the user asks to manage the project roadmap.",
+			"Never set worklist confirm=true for a project lifecycle action unless the user explicitly requested that exact completion, reopening, archival, or deletion.",
+		],
+		parameters: WorklistParamsSchema,
+		executionMode: WORKLIST_EXECUTION_MODE,
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			const result = await executeWorklist(params, ctx, { sessionStore, projectPath });
+			await updateUi(ctx);
+			return { content: [{ type: "text", text: result.content }], details: result.details };
+		},
+		renderCall(args, theme) {
+			return new Text(
+				theme.fg("toolTitle", theme.bold("worklist ")) + theme.fg("muted", `${args.scope} ${args.action}`),
+				0,
+				0,
+			);
+		},
+		renderResult(result, _options, theme) {
+			const block = result.content.find((item) => item.type === "text");
+			return new Text(theme.fg("muted", block?.type === "text" ? block.text : ""), 0, 0);
+		},
+	});
+
+	async function handleDashboardAction(action: DashboardAction, ctx: ExtensionContext): Promise<boolean> {
+		if (action.kind === "close") return false;
+		if (action.kind === "add") {
+			const title = await ctx.ui.input(
+				`Add ${action.scope === "session" ? "session task" : "project goal"}`,
+				"Title",
+			);
+			if (title?.trim()) await execute({ scope: action.scope, action: "add", title: title.trim() }, ctx);
+			return true;
+		}
+		if (action.kind === "edit") {
+			const title = await ctx.ui.input("Edit title", "New title");
+			if (title?.trim())
+				await execute({ scope: action.scope, action: "update", id: action.id, title: title.trim() }, ctx);
+			return true;
+		}
+		if (action.kind === "delete") {
+			const confirmed = await ctx.ui.confirm("Delete item?", "This cannot be undone.");
+			if (confirmed)
+				await execute(
+					{ scope: action.scope, action: "delete", id: action.id, confirm: action.scope === "project" },
+					ctx,
+				);
+			return true;
+		}
+		if (action.scope === "session") {
+			const task = sessionStore.getTasks().find((item) => item.id === action.id);
+			if (task) {
+				const status: SessionTaskStatus =
+					task.status === "todo" ? "doing" : task.status === "doing" ? "done" : "todo";
+				await execute({ scope: "session", action: "set_status", id: task.id, status }, ctx);
+			}
+			return true;
+		}
+		const goal = projectGoals.find((item) => item.id === action.id);
+		if (!goal) return true;
+		if (goal.status === "open") await execute({ scope: "project", action: "set_active", id: goal.id }, ctx);
+		else {
+			const actionName = goal.status === "active" ? "complete" : "reopen";
+			const confirmed = await ctx.ui.confirm(`${actionName} project goal?`, goal.title);
+			if (confirmed) await execute({ scope: "project", action: actionName, id: goal.id, confirm: true }, ctx);
+		}
+		return true;
+	}
+
+	pi.registerCommand("tasks", {
+		description:
+			"Open Worklist, or use: /tasks <session|project> <list|add|update|status|complete|reopen|archive|delete|set_active> ...",
+		handler: async (args, ctx) => {
+			if (args.trim()) {
+				const parsed = parseTasksCommand(args);
+				if (!parsed || (parsed.action === "add" && !parsed.title)) {
+					ctx.ui.notify("Usage: /tasks <session|project> <action> [id/status/title]", "error");
+					return;
+				}
+				try {
+					const result = await execute(parsed, ctx);
+					ctx.ui.notify(result.content, "info");
+				} catch (error) {
+					ctx.ui.notify(String(error), "error");
+				}
+				return;
+			}
+			if (ctx.mode !== "tui") {
+				ctx.ui.notify(
+					`${formatSessionTasks(sessionStore.getTasks())}\n\n${formatProjectGoals(projectGoals)}`,
+					"info",
+				);
+				return;
+			}
+			let again = true;
+			while (again) {
+				await refreshProject();
+				const action = await ctx.ui.custom<DashboardAction>((tui, theme, _keys, done) => {
+					const dashboard = new Dashboard(sessionStore.getTasks(), projectGoals, theme, done);
+					return {
+						render: (width) => dashboard.render(width),
+						invalidate: () => dashboard.invalidate(),
+						handleInput: (data) => {
+							dashboard.handleInput(data);
+							tui.requestRender();
+						},
+					};
+				});
+				again = action ? await handleDashboardAction(action, ctx) : false;
+			}
+		},
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		sessionStore.reconstruct(ctx);
+		projectPath = getProjectPath(ctx.cwd);
+		try {
+			await updateUi(ctx);
+		} catch (error) {
+			ctx.ui.notify(String(error), "error");
+		}
+	});
+	pi.on("session_tree", async (_event, ctx) => {
+		sessionStore.reconstruct(ctx);
+		try {
+			await updateUi(ctx);
+		} catch (error) {
+			ctx.ui.notify(String(error), "error");
+		}
+	});
+	pi.on("before_agent_start", async (event) => {
+		const summary = buildPromptSummary(sessionStore.getTasks(), projectGoals);
+		if (!summary) return;
+		return { systemPrompt: `${event.systemPrompt}\n\n${summary}` };
+	});
+	pi.on("session_shutdown", () => {
+		latestContext?.ui.setWidget("pi-worklist", undefined);
+		latestContext = undefined;
+	});
+}

package/src/git.ts

@@ -0,0 +1,31 @@
+import { execSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+
+export interface GitRootResult {
+	root: string | null;
+	isGit: boolean;
+	error?: string;
+}
+
+export function resolveGitRoot(cwd: string): GitRootResult {
+	try {
+		const raw = execSync("git rev-parse --show-toplevel", {
+			cwd,
+			encoding: "utf8",
+			stdio: ["pipe", "pipe", "pipe"],
+			timeout: 10000,
+		});
+		const top = raw.trim();
+		if (!top) return { root: null, isGit: false, error: "not a git repository" };
+		const canonical = realpathSync(top);
+		return { root: canonical, isGit: true };
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		return { root: null, isGit: false, error: message };
+	}
+}
+
+export function getWorklistPath(gitRoot: string): string {
+	return resolve(gitRoot, ".pi", "worklist.json");
+}

package/src/project-store.ts

@@ -0,0 +1,121 @@
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { randomBytes } from "node:crypto";
+import lockfile from "proper-lockfile";
+import type { ProjectGoal, ProjectWorklist } from "./types.ts";
+import { PROJECT_WORKLIST_VERSION } from "./types.ts";
+
+export interface ProjectStoreResult<T> {
+	data: T;
+	error?: string;
+}
+
+export type ProjectMutation<T> = (current: ProjectWorklist) => {
+	worklist: ProjectWorklist;
+	result: T;
+};
+
+export function isProjectWorklist(value: unknown): value is ProjectWorklist {
+	if (typeof value !== "object" || value === null) return false;
+	const obj = value as Record<string, unknown>;
+	if (obj.version !== PROJECT_WORKLIST_VERSION) return false;
+	if (!Array.isArray(obj.goals)) return false;
+	for (const g of obj.goals) {
+		if (typeof g !== "object" || g === null) return false;
+		const goal = g as Record<string, unknown>;
+		if (typeof goal.id !== "string") return false;
+		if (typeof goal.title !== "string") return false;
+		if (goal.description !== undefined && typeof goal.description !== "string") return false;
+		if (!["open", "active", "done", "archived"].includes(goal.status as string)) return false;
+		if (typeof goal.createdAt !== "string") return false;
+		if (typeof goal.updatedAt !== "string") return false;
+	}
+	return true;
+}
+
+export function createEmptyWorklist(): ProjectWorklist {
+	return { version: PROJECT_WORKLIST_VERSION, goals: [] };
+}
+
+export async function readProjectWorklist(path: string): Promise<ProjectStoreResult<ProjectWorklist>> {
+	try {
+		const text = await readFile(path, "utf8");
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(text);
+		} catch {
+			return {
+				data: createEmptyWorklist(),
+				error: `Malformed project file ${path}: invalid JSON`,
+			};
+		}
+		if (!isProjectWorklist(parsed)) {
+			return {
+				data: createEmptyWorklist(),
+				error: `Malformed or unsupported schema in ${path}. Fix the file manually; it will not be overwritten.`,
+			};
+		}
+		return { data: parsed };
+	} catch (err) {
+		const code = (err as NodeJS.ErrnoException).code;
+		if (code === "ENOENT") {
+			return { data: createEmptyWorklist() };
+		}
+		return {
+			data: createEmptyWorklist(),
+			error: `Cannot read project file ${path}: ${String(err)}`,
+		};
+	}
+}
+
+export async function mutateProjectWorklist<T>(
+	path: string,
+	mutate: ProjectMutation<T>,
+): Promise<ProjectStoreResult<T>> {
+	const dir = dirname(path);
+	await mkdir(dir, { recursive: true });
+
+	const release = await lockfile.lock(dir, {
+		lockfilePath: resolve(dir, ".worklist.lock"),
+		retries: { retries: 20, factor: 1.5, minTimeout: 10, maxTimeout: 250 },
+		stale: 10000,
+	});
+	let tempName: string | undefined;
+
+	try {
+		const readResult = await readProjectWorklist(path);
+		if (readResult.error) {
+			return { data: undefined as unknown as T, error: readResult.error };
+		}
+
+		const { worklist, result } = mutate(readResult.data);
+		if (!isProjectWorklist(worklist)) {
+			return {
+				data: undefined as unknown as T,
+				error: "Project mutation produced an invalid worklist",
+			};
+		}
+
+		tempName = resolve(dir, `.worklist-${randomBytes(8).toString("hex")}.tmp`);
+		await writeFile(tempName, `${JSON.stringify(worklist, null, 2)}\n`, "utf8");
+		await rename(tempName, path);
+		tempName = undefined;
+		return { data: result };
+	} catch (err) {
+		return {
+			data: undefined as unknown as T,
+			error: `Project mutation failed: ${String(err)}`,
+		};
+	} finally {
+		if (tempName) await rm(tempName, { force: true });
+		await release();
+	}
+}
+
+export function sortGoals(goals: ProjectGoal[]): ProjectGoal[] {
+	return goals.slice().sort((a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime());
+}
+
+export function generateId(prefix?: string): string {
+	return `${prefix ? `${prefix}-` : ""}${Date.now().toString(36)}-${randomBytes(4).toString("hex")}`;
+}

package/src/schema.ts

@@ -0,0 +1,61 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type, type TUnsafe } from "typebox";
+
+const ScopeSchema: TUnsafe<"session" | "project"> = StringEnum(["session", "project"] as const, {
+	description: "Whether to operate on session tasks or project goals.",
+});
+
+const ActionSchema: TUnsafe<
+	"list" | "add" | "update" | "set_status" | "delete" | "complete" | "reopen" | "archive" | "set_active"
+> = StringEnum(
+	["list", "add", "update", "set_status", "delete", "complete", "reopen", "archive", "set_active"] as const,
+	{
+		description:
+			"Action to perform. 'complete', 'reopen', 'archive', and 'delete' on project goals require confirm=true.",
+	},
+);
+
+export const SessionTaskStatusSchema: TUnsafe<"todo" | "doing" | "done"> = StringEnum([
+	"todo",
+	"doing",
+	"done",
+] as const);
+
+export const ProjectGoalStatusSchema: TUnsafe<"open" | "active" | "done" | "archived"> = StringEnum([
+	"open",
+	"active",
+	"done",
+	"archived",
+] as const);
+
+const StatusSchema: TUnsafe<"todo" | "doing" | "done" | "open" | "active" | "archived"> = StringEnum(
+	["todo", "doing", "done", "open", "active", "archived"] as const,
+	{
+		description:
+			"Target status for set_status. Project set_status only accepts active; lifecycle actions use complete, reopen, and archive.",
+	},
+);
+
+export const WorklistParamsSchema = Type.Object({
+	scope: ScopeSchema,
+	action: ActionSchema,
+	id: Type.Optional(
+		Type.String({
+			description: "Task or goal ID (for update, set_status, delete, complete, reopen, archive, set_active).",
+		}),
+	),
+	title: Type.Optional(Type.String({ description: "Title for add/update." })),
+	description: Type.Optional(Type.String({ description: "Description for project goal add/update." })),
+	status: Type.Optional(StatusSchema),
+	goalId: Type.Optional(
+		Type.String({
+			description: "Associate a session task with a project goal ID.",
+		}),
+	),
+	confirm: Type.Optional(
+		Type.Boolean({
+			description:
+				"Required boolean for destructive project-goal actions: complete, reopen, archive, delete. Set to true ONLY when the user explicitly requested the action.",
+		}),
+	),
+});

package/src/session-store.ts

@@ -0,0 +1,91 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { SessionSnapshot, SessionTask, SessionTaskStatus } from "./types.ts";
+import { SESSION_SNAPSHOT_VERSION } from "./types.ts";
+
+export const SESSION_SNAPSHOT_TYPE = "worklist-session-snapshot";
+
+export class SessionStore {
+	private tasks: SessionTask[] = [];
+	private mutationQueue: Promise<unknown> = Promise.resolve();
+
+	constructor(private readonly pi: ExtensionAPI) {}
+
+	getTasks(): SessionTask[] {
+		return this.tasks.slice();
+	}
+
+	setTasks(tasks: SessionTask[]): void {
+		this.tasks = tasks.slice();
+	}
+
+	reconstruct(ctx: ExtensionContext): void {
+		this.tasks = [];
+		const branch = ctx.sessionManager.getBranch();
+		for (const entry of branch) {
+			if (entry.type !== "custom") continue;
+			if (entry.customType !== SESSION_SNAPSHOT_TYPE) continue;
+			const data = entry.data as SessionSnapshot | undefined;
+			if (data && data.version === SESSION_SNAPSHOT_VERSION && Array.isArray(data.tasks)) {
+				this.tasks = data.tasks.slice();
+			}
+		}
+	}
+
+	private async serialized<T>(fn: () => Promise<T>): Promise<T> {
+		const next = this.mutationQueue.then(fn);
+		this.mutationQueue = next.catch(() => undefined);
+		return next;
+	}
+
+	async addTask(title: string, goalId?: string): Promise<SessionTask> {
+		return this.serialized(async () => {
+			const id = `st-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+			const task: SessionTask = { id, title, status: "todo", goalId };
+			this.tasks = [...this.tasks, task];
+			this.persist();
+			return task;
+		});
+	}
+
+	async updateTask(
+		id: string,
+		updates: Partial<Pick<SessionTask, "title" | "goalId">>,
+	): Promise<SessionTask | null> {
+		return this.serialized(async () => {
+			const index = this.tasks.findIndex((t) => t.id === id);
+			if (index === -1) return null;
+			const updated = { ...this.tasks[index], ...updates };
+			this.tasks = [...this.tasks.slice(0, index), updated, ...this.tasks.slice(index + 1)];
+			this.persist();
+			return updated;
+		});
+	}
+
+	async setTaskStatus(id: string, status: SessionTaskStatus): Promise<SessionTask | null> {
+		return this.serialized(async () => {
+			const index = this.tasks.findIndex((t) => t.id === id);
+			if (index === -1) return null;
+			const updated = { ...this.tasks[index], status };
+			this.tasks = [...this.tasks.slice(0, index), updated, ...this.tasks.slice(index + 1)];
+			this.persist();
+			return updated;
+		});
+	}
+
+	async deleteTask(id: string): Promise<boolean> {
+		return this.serialized(async () => {
+			const before = this.tasks.length;
+			this.tasks = this.tasks.filter((t) => t.id !== id);
+			if (this.tasks.length === before) return false;
+			this.persist();
+			return true;
+		});
+	}
+
+	private persist(): void {
+		this.pi.appendEntry(SESSION_SNAPSHOT_TYPE, {
+			version: SESSION_SNAPSHOT_VERSION,
+			tasks: this.tasks.slice(),
+		});
+	}
+}

package/src/tool.ts

@@ -0,0 +1,303 @@
+/* eslint-disable no-case-declarations */
+import type { ExtensionContext, ToolExecutionMode } from "@earendil-works/pi-coding-agent";
+import type {
+	ProjectGoal,
+	ProjectGoalStatus,
+	SessionTask,
+	SessionTaskStatus,
+	WorklistToolDetails,
+} from "./types.ts";
+import { generateId, mutateProjectWorklist, readProjectWorklist, sortGoals } from "./project-store.ts";
+import type { SessionStore } from "./session-store.ts";
+import { getWorklistPath, resolveGitRoot } from "./git.ts";
+
+export interface ToolDeps {
+	sessionStore: SessionStore;
+	projectPath: string | null;
+}
+
+export function getProjectPath(cwd: string): string | null {
+	const result = resolveGitRoot(cwd);
+	if (!result.isGit || !result.root) return null;
+	return getWorklistPath(result.root);
+}
+
+export function formatSessionTasks(tasks: SessionTask[]): string {
+	if (tasks.length === 0) return "No session tasks.";
+	return tasks
+		.map((t) => {
+			const marker = t.status === "done" ? "[x]" : t.status === "doing" ? "[~]" : "[ ]";
+			const goal = t.goalId ? ` (goal:${t.goalId})` : "";
+			return `${marker} ${t.id}: ${t.title}${goal}`;
+		})
+		.join("\n");
+}
+
+export function formatProjectGoals(goals: ProjectGoal[]): string {
+	if (goals.length === 0) return "No project goals.";
+	return sortGoals(goals)
+		.map((g) => `[${g.status}] ${g.id}: ${g.title}${g.description ? ` - ${g.description}` : ""}`)
+		.join("\n");
+}
+
+export async function executeWorklist(
+	params: {
+		scope: "session" | "project";
+		action: string;
+		id?: string;
+		title?: string;
+		description?: string;
+		status?: SessionTaskStatus | ProjectGoalStatus;
+		goalId?: string;
+		confirm?: boolean;
+	},
+	_ctx: ExtensionContext,
+	deps: ToolDeps,
+): Promise<{ content: string; details: WorklistToolDetails }> {
+	const { sessionStore, projectPath } = deps;
+
+	if (params.scope === "session") {
+		switch (params.action) {
+			case "list": {
+				const tasks = sessionStore.getTasks();
+				return {
+					content: formatSessionTasks(tasks),
+					details: { scope: "session", action: "list", tasks },
+				};
+			}
+			case "add": {
+				if (!params.title) throw new Error("title is required for session add");
+				const task = await sessionStore.addTask(params.title, params.goalId);
+				const tasks = sessionStore.getTasks();
+				return {
+					content: `Added session task ${task.id}: ${task.title}`,
+					details: { scope: "session", action: "add", tasks },
+				};
+			}
+			case "update": {
+				if (!params.id) throw new Error("id is required for session update");
+				const updates: Partial<Pick<SessionTask, "title" | "goalId">> = {};
+				if (params.title !== undefined) updates.title = params.title;
+				if (params.goalId !== undefined) updates.goalId = params.goalId;
+				const task = await sessionStore.updateTask(params.id, updates);
+				if (!task) throw new Error(`Session task ${params.id} not found`);
+				const tasks = sessionStore.getTasks();
+				return {
+					content: `Updated session task ${task.id}`,
+					details: { scope: "session", action: "update", tasks },
+				};
+			}
+			case "set_status": {
+				if (!params.id) throw new Error("id is required for session set_status");
+				if (!params.status || !["todo", "doing", "done"].includes(params.status)) {
+					throw new Error("status must be todo, doing, or done for session tasks");
+				}
+				const task = await sessionStore.setTaskStatus(params.id, params.status as SessionTaskStatus);
+				if (!task) throw new Error(`Session task ${params.id} not found`);
+				const tasks = sessionStore.getTasks();
+				return {
+					content: `Set session task ${task.id} to ${task.status}`,
+					details: { scope: "session", action: "set_status", tasks },
+				};
+			}
+			case "delete": {
+				if (!params.id) throw new Error("id is required for session delete");
+				const removed = await sessionStore.deleteTask(params.id);
+				if (!removed) throw new Error(`Session task ${params.id} not found`);
+				const tasks = sessionStore.getTasks();
+				return {
+					content: `Deleted session task ${params.id}`,
+					details: { scope: "session", action: "delete", tasks },
+				};
+			}
+			default:
+				throw new Error(`Unknown session action: ${params.action}`);
+		}
+	}
+
+	if (params.scope === "project") {
+		if (!projectPath) {
+			throw new Error(
+				"Project goals require a git repository. Session tasks are still available outside git.",
+			);
+		}
+
+		switch (params.action) {
+			case "list": {
+				const { data, error } = await readProjectWorklist(projectPath);
+				if (error) throw new Error(error);
+				return {
+					content: formatProjectGoals(data.goals),
+					details: { scope: "project", action: "list", goals: data.goals },
+				};
+			}
+			case "add": {
+				if (!params.title) throw new Error("title is required for project add");
+				const now = new Date().toISOString();
+				const goal: ProjectGoal = {
+					id: generateId("goal"),
+					title: params.title,
+					description: params.description,
+					status: "open",
+					createdAt: now,
+					updatedAt: now,
+				};
+				const result = await mutateProjectWorklist(projectPath, (worklist) => ({
+					worklist: {
+						...worklist,
+						goals: sortGoals([...worklist.goals, goal]),
+					},
+					result: goal,
+				}));
+				if (result.error) throw new Error(result.error);
+				return {
+					content: `Added project goal ${result.data.id}: ${result.data.title}`,
+					details: {
+						scope: "project",
+						action: "add",
+						goals: sortGoals([...(await readProjectWorklist(projectPath)).data.goals]),
+					},
+				};
+			}
+			case "update": {
+				if (!params.id) throw new Error("id is required for project update");
+				{
+					const result = await mutateProjectWorklist(projectPath, (worklist) => {
+						const index = worklist.goals.findIndex((g) => g.id === params.id);
+						if (index === -1) return { worklist, result: null };
+						const updated: ProjectGoal = { ...worklist.goals[index] };
+						if (params.title !== undefined) updated.title = params.title;
+						if (params.description !== undefined) updated.description = params.description;
+						updated.updatedAt = new Date().toISOString();
+						const goals = [...worklist.goals];
+						goals[index] = updated;
+						return { worklist: { ...worklist, goals }, result: updated };
+					});
+					if (result.error) throw new Error(result.error);
+					if (!result.data) throw new Error(`Project goal ${params.id} not found`);
+					return {
+						content: `Updated project goal ${result.data.id}`,
+						details: {
+							scope: "project",
+							action: "update",
+							goals: (await readProjectWorklist(projectPath)).data.goals,
+						},
+					};
+				}
+			}
+			case "set_status": {
+				if (params.status !== "active") {
+					throw new Error(
+						"Project set_status only accepts active. Use complete, reopen, or archive with confirm=true for lifecycle changes.",
+					);
+				}
+				return executeWorklist({ ...params, action: "set_active" }, _ctx, deps);
+			}
+			case "set_active": {
+				if (!params.id) throw new Error("id is required for project set_active");
+				{
+					const result = await mutateProjectWorklist(projectPath, (worklist) => {
+						const target = worklist.goals.find((goal) => goal.id === params.id);
+						if (!target) return { worklist, result: { goal: null, blocked: false } };
+						if (target.status === "done" || target.status === "archived") {
+							return { worklist, result: { goal: target, blocked: true } };
+						}
+						const now = new Date().toISOString();
+						const goals = worklist.goals.map((goal) =>
+							goal.id === params.id
+								? { ...goal, status: "active" as ProjectGoalStatus, updatedAt: now }
+								: goal.status === "active"
+									? { ...goal, status: "open" as ProjectGoalStatus, updatedAt: now }
+									: goal,
+						);
+						return {
+							worklist: { ...worklist, goals },
+							result: { goal: goals.find((goal) => goal.id === params.id) ?? null, blocked: false },
+						};
+					});
+					if (result.error) throw new Error(result.error);
+					if (result.data.blocked)
+						throw new Error(
+							"A done or archived Project Goal must be reopened with confirm=true before activation.",
+						);
+					if (!result.data.goal) throw new Error(`Project goal ${params.id} not found`);
+					return {
+						content: `Activated project goal ${result.data.goal.id}`,
+						details: {
+							scope: "project",
+							action: "set_active",
+							goals: (await readProjectWorklist(projectPath)).data.goals,
+						},
+					};
+				}
+			}
+			case "complete":
+			case "reopen":
+			case "archive":
+			case "delete": {
+				if (!params.id) throw new Error(`id is required for project ${params.action}`);
+				if (params.confirm !== true) {
+					return {
+						content: `Project goal ${params.action} requires explicit user intent. Set confirm=true only when the user explicitly requested this action.`,
+						details: {
+							scope: "project",
+							action: params.action,
+							requiresConfirm: true,
+						},
+					};
+				}
+				if (params.action === "delete") {
+					{
+						const result = await mutateProjectWorklist(projectPath, (worklist) => {
+							const goals = worklist.goals.filter((g) => g.id !== params.id);
+							const removed = goals.length !== worklist.goals.length;
+							return { worklist: { ...worklist, goals }, result: removed };
+						});
+						if (result.error) throw new Error(result.error);
+						if (!result.data) throw new Error(`Project goal ${params.id} not found`);
+						return {
+							content: `Deleted project goal ${params.id}`,
+							details: {
+								scope: "project",
+								action: "delete",
+								goals: (await readProjectWorklist(projectPath)).data.goals,
+							},
+						};
+					}
+				}
+				{
+					const targetStatus: ProjectGoalStatus =
+						params.action === "complete" ? "done" : params.action === "reopen" ? "open" : "archived";
+					const result = await mutateProjectWorklist(projectPath, (worklist) => {
+						const index = worklist.goals.findIndex((g) => g.id === params.id);
+						if (index === -1) return { worklist, result: null };
+						const updated: ProjectGoal = {
+							...worklist.goals[index],
+							status: targetStatus,
+						};
+						updated.updatedAt = new Date().toISOString();
+						const goals = [...worklist.goals];
+						goals[index] = updated;
+						return { worklist: { ...worklist, goals }, result: updated };
+					});
+					if (result.error) throw new Error(result.error);
+					if (!result.data) throw new Error(`Project goal ${params.id} not found`);
+					return {
+						content: `Project goal ${result.data.id} is now ${result.data.status}`,
+						details: {
+							scope: "project",
+							action: params.action,
+							goals: (await readProjectWorklist(projectPath)).data.goals,
+						},
+					};
+				}
+			}
+			default:
+				throw new Error(`Unknown project action: ${params.action}`);
+		}
+	}
+
+	throw new Error(`Unknown scope: ${params.scope}`);
+}
+
+export const WORKLIST_EXECUTION_MODE = "sequential" as ToolExecutionMode;

package/src/types.ts

@@ -0,0 +1,40 @@
+export type SessionTaskStatus = "todo" | "doing" | "done";
+export type ProjectGoalStatus = "open" | "active" | "done" | "archived";
+
+export interface SessionTask {
+	id: string;
+	title: string;
+	status: SessionTaskStatus;
+	goalId?: string;
+}
+
+export interface ProjectGoal {
+	id: string;
+	title: string;
+	description?: string;
+	status: ProjectGoalStatus;
+	createdAt: string;
+	updatedAt: string;
+}
+
+export interface SessionSnapshot {
+	version: number;
+	tasks: SessionTask[];
+}
+
+export interface ProjectWorklist {
+	version: number;
+	goals: ProjectGoal[];
+}
+
+export interface WorklistToolDetails {
+	scope: "session" | "project";
+	action: string;
+	tasks?: SessionTask[];
+	goals?: ProjectGoal[];
+	error?: string;
+	requiresConfirm?: boolean;
+}
+
+export const SESSION_SNAPSHOT_VERSION = 1;
+export const PROJECT_WORKLIST_VERSION = 1;

package/src/ui.ts

@@ -0,0 +1,104 @@
+import type { ProjectGoal, SessionTask } from "./types.ts";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+
+export function buildWidgetLines(tasks: SessionTask[], goals: ProjectGoal[]): string[] {
+	const active = goals.find((goal) => goal.status === "active");
+	const pending = tasks.filter((task) => task.status !== "done");
+	if (!active && pending.length === 0) return [];
+	const lines: string[] = [];
+	if (active) lines.push(`Goal: ${active.title}`);
+	for (const task of pending.slice(0, 3)) {
+		lines.push(`${task.status === "doing" ? "●" : "○"} ${task.title}`);
+	}
+	if (pending.length > 3) lines.push(`+${pending.length - 3} more`);
+	return lines;
+}
+
+export function buildPromptSummary(tasks: SessionTask[], goals: ProjectGoal[], maxItems = 8): string {
+	const active = goals.find((goal) => goal.status === "active");
+	const pending = tasks.filter((task) => task.status !== "done").slice(0, maxItems);
+	if (!active && pending.length === 0) return "";
+	const lines = ["[WORKLIST]"];
+	if (active) lines.push(`Active project goal: ${active.title}`);
+	if (pending.length) {
+		lines.push("Incomplete session tasks:");
+		for (const task of pending) lines.push(`- [${task.status === "doing" ? "doing" : "todo"}] ${task.title}`);
+	}
+	const remaining = tasks.filter((task) => task.status !== "done").length - pending.length;
+	if (remaining > 0) lines.push(`- ...and ${remaining} more`);
+	return lines.join("\n");
+}
+
+export type DashboardAction =
+	| { kind: "close" }
+	| { kind: "add"; scope: "session" | "project" }
+	| { kind: "edit"; scope: "session" | "project"; id: string }
+	| { kind: "advance"; scope: "session" | "project"; id: string }
+	| { kind: "delete"; scope: "session" | "project"; id: string };
+
+export class Dashboard {
+	private scope: "session" | "project" = "session";
+	private selected = 0;
+	constructor(
+		private readonly tasks: SessionTask[],
+		private readonly goals: ProjectGoal[],
+		private readonly theme: Theme,
+		private readonly done: (action: DashboardAction) => void,
+	) {}
+
+	private items(): Array<SessionTask | ProjectGoal> {
+		return this.scope === "session" ? this.tasks : this.goals.filter((goal) => goal.status !== "archived");
+	}
+
+	handleInput(data: string): void {
+		const items = this.items();
+		if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) {
+			this.done({ kind: "close" });
+			return;
+		}
+		if (matchesKey(data, Key.tab) || matchesKey(data, Key.left) || matchesKey(data, Key.right)) {
+			this.scope = this.scope === "session" ? "project" : "session";
+			this.selected = 0;
+			return;
+		}
+		if (matchesKey(data, Key.up)) this.selected = Math.max(0, this.selected - 1);
+		if (matchesKey(data, Key.down))
+			this.selected = Math.min(Math.max(0, items.length - 1), this.selected + 1);
+		if (data === "a") {
+			this.done({ kind: "add", scope: this.scope });
+			return;
+		}
+		const item = items[this.selected];
+		if (!item) return;
+		if (data === "e") this.done({ kind: "edit", scope: this.scope, id: item.id });
+		else if (data === "d") this.done({ kind: "delete", scope: this.scope, id: item.id });
+		else if (matchesKey(data, Key.enter) || matchesKey(data, Key.space)) {
+			this.done({ kind: "advance", scope: this.scope, id: item.id });
+		}
+	}
+
+	render(width: number): string[] {
+		const th = this.theme;
+		const lines = [
+			th.fg("accent", th.bold("Worklist")),
+			`${this.scope === "session" ? th.fg("accent", "[Session Tasks]") : "Session Tasks"}  ${this.scope === "project" ? th.fg("accent", "[Project Goals]") : "Project Goals"}`,
+			"",
+		];
+		const items = this.items();
+		if (!items.length) lines.push(th.fg("dim", "  No items. Press a to add one."));
+		items.forEach((item, index) => {
+			const status = item.status;
+			const marker = status === "done" ? "✓" : status === "doing" || status === "active" ? "●" : "○";
+			const prefix = index === this.selected ? th.fg("accent", ">") : " ";
+			lines.push(`${prefix} ${marker} ${item.title} ${th.fg("dim", item.id)}`);
+		});
+		lines.push(
+			"",
+			th.fg("dim", "tab switch  ↑↓ navigate  a add  e edit  space/enter advance  d delete  esc close"),
+		);
+		return lines.map((line) => truncateToWidth(line, width));
+	}
+
+	invalidate(): void {}
+}