@danypops/papyrus 0.60.2 → 0.60.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.60.2",
+  "version": "0.60.4",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "main": "./src/index.ts",

package/src/artifact/artifact.ts

@@ -64,6 +64,11 @@ export interface UpdateArtifactInput {
 	alias?: string;
 }
 
+export interface ArtifactQueryCursor {
+	createdAt: string;
+	id: string;
+}
+
 export interface ArtifactQuery {
 	kind?: string;
 	status?: string;
@@ -74,6 +79,10 @@ export interface ArtifactQuery {
 	labels?: string[];
 	extraEquals?: Record<string, string | number | boolean>;
 	limit?: number;
+	/** Stable inventory ordering, independent of content updates. Defaults to updated_at descending. */
+	order?: "updated_desc" | "created_desc";
+	/** Exclusive keyset cursor for created_desc ordering. */
+	after?: ArtifactQueryCursor;
 	/** Trashed artifacts (see artifact-trash.ts) are excluded from every query by default; set true to include them, e.g. for a trash-listing view. */
 	includeTrashed?: boolean;
 	/**

package/src/cli/note-command.ts

@@ -59,6 +59,34 @@ const listCommand = buildCommand({
 	docs: { brief: "List open (draft/active) notes, or a specific status" },
 });
 
+const listPageCommand = buildCommand({
+	func: async function (
+		this: NoteContext,
+		flags: { status?: string; text?: string; limit?: number; cursor?: string; allProjects?: boolean },
+	) {
+		const page = (await this.client.call("notes.list_page", {
+			...(flags.allProjects ? {} : { project_root: this.projectRoot }),
+			...(flags.status ? { status: flags.status } : {}),
+			...(flags.text ? { text: flags.text } : {}),
+			...(flags.limit === undefined ? {} : { limit: flags.limit }),
+			...(flags.cursor ? { cursor: flags.cursor } : {}),
+		})) as { items: CliArtifact[]; nextCursor?: string };
+		const lines = page.items.map((note) => `[${note.status}] ${artifactLabel(note)}`);
+		if (page.nextCursor) lines.push(`Next cursor: ${page.nextCursor}`);
+		renderResult.call(this, page, lines.length > 0 ? lines.join("\n") : "No open notes.");
+	},
+	parameters: {
+		flags: {
+			status: { brief: "Filter by status (draft|active|archived)", kind: "parsed", parse: String, placeholder: "status", optional: true },
+			text: { brief: "Substring match against title/body", kind: "parsed", parse: String, placeholder: "text", optional: true },
+			limit: { brief: "Page size", kind: "parsed", parse: numberParser, optional: true },
+			cursor: { brief: "Opaque nextCursor from the preceding page", kind: "parsed", parse: String, placeholder: "cursor", optional: true },
+			allProjects: { brief: "Inventory Notes across every project", kind: "boolean", optional: true },
+		},
+	},
+	docs: { brief: "Cursor-paginate a stable Note inventory" },
+});
+
 const showCommand = buildCommand({
 	func: async function (this: NoteContext, _flags: Record<string, never>, id: string) {
 		const result = (await this.client.call("notes.show", { id, project_root: this.projectRoot })) as CliArtifact;
@@ -168,6 +196,7 @@ const app = buildApplication(
 		routes: {
 			capture: captureCommand,
 			list: listCommand,
+			page: listPageCommand,
 			show: showCommand,
 			history: historyCommand,
 			consume: consumeCommand,

package/src/cli/task-command.ts

@@ -456,6 +456,56 @@ const listCommand = buildCommand({
 	docs: { brief: "List Tasks" },
 });
 
+const listPageCommand = buildCommand({
+	func: async function (
+		this: TaskContext,
+		flags: {
+			status?: string;
+			text?: string;
+			limit?: number;
+			labelsJson?: string[];
+			scope?: "project" | "graph" | "all";
+			rootTaskId?: string;
+			sessionId?: string;
+			cursor?: string;
+		},
+	) {
+		const page = await this.client.call<Record<string, unknown>, { items: CliArtifact[]; nextCursor?: string }>("tasks.list_page", {
+			status: flags.status,
+			text: flags.text,
+			limit: flags.limit,
+			labels: flags.labelsJson,
+			project_root: this.projectRoot,
+			scope: flags.scope,
+			root_task_id: flags.rootTaskId,
+			session_id: flags.sessionId,
+			cursor: flags.cursor,
+		});
+		const rows = page.items.map((row) => artifactLabel(row));
+		if (page.nextCursor) rows.push(`Next cursor: ${page.nextCursor}`);
+		render.call(this, page, rows.length === 0 ? "No tasks found." : rows.join("\n"));
+	},
+	parameters: {
+		flags: {
+			status: { brief: "Filter by status", kind: "parsed", parse: String, placeholder: "status", optional: true },
+			text: { brief: "Substring match against title/body", kind: "parsed", parse: String, placeholder: "text", optional: true },
+			limit: { brief: "Page size", kind: "parsed", parse: numberParser, optional: true },
+			labelsJson: {
+				brief: "JSON string array of labels to filter by",
+				kind: "parsed",
+				parse: parseStringArray,
+				placeholder: "json",
+				optional: true,
+			},
+			scope: { brief: "project|graph|all", kind: "enum", values: ["project", "graph", "all"], optional: true },
+			rootTaskId: { brief: "Root task id, required with graph scope", kind: "parsed", parse: String, placeholder: "id", optional: true },
+			sessionId: { brief: "Scope to one agent session", kind: "parsed", parse: String, placeholder: "id", optional: true },
+			cursor: { brief: "Opaque nextCursor from the preceding page", kind: "parsed", parse: String, placeholder: "cursor", optional: true },
+		},
+	},
+	docs: { brief: "Cursor-paginate a stable Task inventory" },
+});
+
 const showCommand = buildCommand({
 	func: async function (this: TaskContext, _flags: Record<string, never>, id: string) {
 		const artifact = await this.client.call<Record<string, unknown>, CliArtifact>("tasks.show", { id });
@@ -963,6 +1013,7 @@ const app = buildApplication(
 			"mutation-status": mutationStatusCommand,
 			create: createCommand,
 			list: listCommand,
+			page: listPageCommand,
 			show: showCommand,
 			"run-gates": runGatesCommand,
 			"set-checklist": setChecklistCommand,

package/src/cli.ts

@@ -152,6 +152,7 @@ const USAGE = `Usage:
   papyrus playbooks undepend <id> <dependency-id> [--json]
   papyrus notes capture <request> [--title <title>] [--json]
   papyrus notes list [--status <draft|active|archived>] [--text <query>] [--limit <count>] [--json]
+  papyrus notes page [--status <draft|active|archived>] [--text <query>] [--limit <count>] [--cursor <cursor>] [--all-projects] [--json]
   papyrus notes show <id> [--json]
   papyrus notes consume <id> [--reason <reason>] [--json]
   papyrus notes promote <id> <target-id> [--reason <reason>] [--json]
@@ -204,6 +205,7 @@ const USAGE = `Usage:
   papyrus tasks uncontain <parent-id> <child-id> [--reason <reason>] [--session-id <id>] [--json]
   papyrus tasks create --title <title> [--body <body>] [--status <status>] [--labels-json <json>] [--extra-json <json>] [--gates-json <json>] [--checklist-json <json>] [--template-id <id>] [--parent-id <id>] [--depends-on-json <json>] [--session-id <id>] [--json]
   papyrus tasks list [--status <status>] [--text <query>] [--limit <count>] [--scope <project|graph|all>] [--root-task-id <id>] [--session-id <id>] [--json]
+  papyrus tasks page [--status <status>] [--text <query>] [--limit <count>] [--cursor <cursor>] [--scope <project|graph|all>] [--root-task-id <id>] [--session-id <id>] [--json]
   papyrus tasks show <id> [--json]
   papyrus tasks run-gates <id> [--json]
   papyrus tasks set-checklist <id> --checklist-json <json> [--json]

package/src/constants.ts

@@ -308,6 +308,9 @@ export const SESSION_IDENTITY_MAX_ROWS = 2_000;
 export const ARTIFACT_TRASH_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
 /** Persisted project and focused-graph Task view bounds. */
 export const TASK_SCOPE_MAX_TASKS = 1_000;
+/** Cursor-paged Task inventory bounds; pages stay comfortably below Vehicle response limits. */
+export const TASK_LIST_PAGE_DEFAULT_LIMIT = 100;
+export const TASK_LIST_PAGE_MAX_LIMIT = 200;
 /** Docs/Rules/Skills project scope listing bound, mirroring TASK_SCOPE_MAX_TASKS. */
 export const ARTIFACT_SCOPE_MAX_ARTIFACTS = 1_000;
 /** How many distinct registered projects a single Doc/Rule/Playbook may belong to at once, in "projects" scope mode. Kept alongside ARTIFACT_SCOPE_MAX_MEMBERS_PER_ARTIFACT (identical value) for the pure-project call sites/tests that predate mixed project+group membership. */

package/src/daemon/daemon.ts

@@ -11,6 +11,7 @@ import { PushChannel } from "@danypops/vehicle-server/push-channel";
 import { DAEMON_HOST, DB_OPTIMIZE_INTERVAL_MS, dbPath, metricsPath, WAL_CHECKPOINT_INTERVAL_MS } from "../constants.ts";
 import { logEvent, logger } from "../log/log.ts";
 import { createApp, createPapyrusService } from "../service.ts";
+import { createTaskMutationPushMiddleware } from "./task-mutation-push.ts";
 import {
 	clearDaemonPort,
 	clearSharedVehicleHandle,
@@ -81,6 +82,7 @@ export async function serveMain(): Promise<void> {
 	service.vehicle.useExecutionMiddleware(createVehicleMetricsMiddleware(vehicleMetrics, "papyrus"));
 	registerVehicleMetricsOperations(service.vehicle, vehicleMetrics, "papyrus");
 	const pushChannel = new PushChannel({ token });
+	service.vehicle.useExecutionMiddleware(createTaskMutationPushMiddleware((operation) => pushChannel.publish("tasks", { operation })));
 	const app = createApp({
 		service,
 		token,

package/src/daemon/task-mutation-push.ts

@@ -0,0 +1,18 @@
+import type { VehicleExecutionMiddleware } from "@danypops/vehicle-server";
+
+/**
+ * Publishes one invalidation only after a successful Vehicle task mutation.
+ * Kept as execution middleware so HTTP, LocalVehicleClient, jobs, and future
+ * transports all observe the same mutation rather than each transport trying
+ * to infer success from its own response framing.
+ */
+export function createTaskMutationPushMiddleware(publish: (operation: string) => void): VehicleExecutionMiddleware {
+	return {
+		id: "papyrus.task-mutation-push",
+		async intercept(request, next) {
+			const output = await next(request.input);
+			if (request.operation.name.startsWith("tasks.") && request.operation.effect !== "read") publish(request.operation.name);
+			return output;
+		},
+	};
+}

package/src/handlers/notes.ts

@@ -60,6 +60,21 @@ export function registerNotesVehicleOperations(registry: VehicleRegistry, notes:
 		(input) => input,
 	);
 
+	define(
+		"list_page",
+		"Cursor-paginates a stable Note inventory. Omit project_root only for an intentional cross-project audit; use nextCursor until absent.",
+		"read",
+		{
+			project_root: stringProp,
+			status: { type: "string", enum: ["draft", "active", "archived"] },
+			text: stringProp,
+			limit: numberProp,
+			cursor: stringProp,
+		},
+		[],
+		(input) => input,
+	);
+
 	define(
 		"show",
 		"Shows one note by id or title.",

package/src/handlers/tasks.ts

@@ -246,6 +246,7 @@ const readSchemaProps = {
 
 /** list-only: opts into full Artifact bodies instead of the lean summarizeArtifact() default (modules/tasks.ts). */
 const listSchemaProps = { ...readSchemaProps, full: booleanProp };
+const listPageSchemaProps = { ...listSchemaProps, cursor: stringProp };
 
 /** Same gate/checklist narrative lines the removed tool built client-side. */
 function completionContentText(labels: Map<string, string>, result: TaskCompletion): string {
@@ -447,6 +448,18 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 		},
 	);
 
+	define(
+		"list_page",
+		"Cursor-paginates a stable creation-ordered Task inventory. Use nextCursor until it is absent. Existing tasks.list remains the lean array convenience API.",
+		"read",
+		listPageSchemaProps,
+		["project_root"],
+		(input) => {
+			const rootTaskId = resolveRootTaskId(artifacts, tasks, input.project_root as string, input.root_task_id, input.root_task_name);
+			return { ...input, ...(rootTaskId ? { root_task_id: rootTaskId } : {}) };
+		},
+	);
+
 	define(
 		"graph",
 		"Returns the full task graph (nodes with parent/child/dependency ids) for the requested scope. project_root is required.",

package/src/modules/notes.ts

@@ -24,6 +24,7 @@ const MODULE_ID = "notes";
 export const NOTES_OPERATION_NAMES = [
 	"notes.capture",
 	"notes.list",
+	"notes.list_page",
 	"notes.show",
 	"notes.history",
 	"notes.consume",
@@ -57,6 +58,15 @@ export function notesOperations(notes: Notes): OperationDefinition[] {
 				limit: optionalNumber(input, "limit"),
 			}),
 		),
+		define("notes.list_page", (input: OperationInput) =>
+			notes.listPage({
+				projectRoot: optionalString(input, "project_root"),
+				status: optionalString(input, "status") as "draft" | "active" | "archived" | undefined,
+				text: optionalString(input, "text"),
+				limit: optionalNumber(input, "limit"),
+				cursor: optionalString(input, "cursor"),
+			}),
+		),
 		define("notes.show", (input: OperationInput) => notes.show(string(input, "id"), string(input, "project_root"))),
 		define("notes.history", (input: OperationInput) =>
 			notes.history(string(input, "id"), string(input, "project_root"), {

package/src/modules/tasks.ts

@@ -54,6 +54,7 @@ const taskFilter = (input: OperationInput) => ({
 	rootTaskId: optionalString(input, "root_task_id"),
 	sessionId: optionalString(input, "session_id") ?? optionalString(input, "sessionId"),
 	labels: optionalStringArray(input, "labels"),
+	cursor: optionalString(input, "cursor"),
 });
 
 /**
@@ -69,6 +70,7 @@ export const TASKS_OPERATION_NAMES = [
 	"tasks.create",
 	"tasks.update",
 	"tasks.list",
+	"tasks.list_page",
 	"tasks.graph",
 	"tasks.plan",
 	"tasks.show",
@@ -164,6 +166,13 @@ export function tasksOperations(tasks: Tasks, artifacts: ArtifactStore, sessionI
 			const rows = tasks.list(taskFilter(input));
 			return optionalBoolean(input, "full") === true ? rows : rows.map(summarizeArtifact);
 		}),
+		define("tasks.list_page", (input: OperationInput) => {
+			const page = tasks.listPage(taskFilter(input));
+			return {
+				...page,
+				items: optionalBoolean(input, "full") === true ? page.items : page.items.map(summarizeArtifact),
+			};
+		}),
 		define("tasks.graph", (input: OperationInput) => tasks.graph(taskFilter(input))),
 		define("tasks.plan", (input: OperationInput) => projectTaskExecution(tasks.graph(taskFilter(input)))),
 		define("tasks.show", (input: OperationInput) => tasks.show(string(input, "id"))),

package/src/note/note-service.ts

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import type { Artifact } from "../artifact/artifact.ts";
 import type { ArtifactStore } from "../artifact/artifact-store.ts";
 import { requireAtomicArtifactStore } from "../artifact/atomic-artifact-store.ts";
@@ -37,6 +38,27 @@ export interface ListNotesInput {
 	limit?: number;
 }
 
+export interface ListNotesPageInput {
+	/** Omit only for an explicit cross-project inventory. */
+	projectRoot?: string;
+	status?: "draft" | "active" | "archived";
+	text?: string;
+	limit?: number;
+	cursor?: string;
+}
+
+export interface NotesPage {
+	items: Artifact[];
+	nextCursor?: string;
+}
+
+interface NotesPageCursor {
+	v: 1;
+	createdAt: string;
+	id: string;
+	filterHash: string;
+}
+
 export interface ArchiveNoteInput extends NoteProvenance {
 	projectRoot: string;
 	disposition: NoteDisposition;
@@ -54,6 +76,29 @@ function optionalBounded(value: string | undefined, field: string, maximum: numb
 	return requiredBounded(value, field, maximum);
 }
 
+function notesPageFilterHash(input: ListNotesPageInput, projectRoot: string | undefined): string {
+	return createHash("sha256")
+		.update(JSON.stringify({ projectRoot, status: input.status, text: input.text }))
+		.digest("base64url");
+}
+
+function decodeNotesPageCursor(cursor: string | undefined, filterHash: string): NotesPageCursor | undefined {
+	if (cursor === undefined) return undefined;
+	try {
+		const parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8")) as Partial<NotesPageCursor>;
+		if (parsed.v !== 1 || !parsed.createdAt || !parsed.id || parsed.filterHash !== filterHash) throw new Error("invalid cursor");
+		return parsed as NotesPageCursor;
+	} catch {
+		throw new Error("notes page cursor is invalid or does not match the requested filters");
+	}
+}
+
+function encodeNotesPageCursor(note: Artifact, filterHash: string): string {
+	return Buffer.from(JSON.stringify({ v: 1, createdAt: note.created_at, id: note.id, filterHash } satisfies NotesPageCursor)).toString(
+		"base64url",
+	);
+}
+
 function noteTitle(body: string, requested?: string): string {
 	if (requested !== undefined) return requiredBounded(requested, "note title", NOTE_TITLE_MAX_CHARACTERS);
 	const firstLine = body.split(/\r?\n/, 1)[0]!.replace(/\s+/g, " ").trim();
@@ -110,6 +155,33 @@ export class Notes {
 		});
 	}
 
+	/** Cursor-paged inventory; omitting projectRoot intentionally enumerates notes across projects. */
+	listPage(input: ListNotesPageInput): NotesPage {
+		const projectRoot =
+			input.projectRoot === undefined ? undefined : requiredBounded(input.projectRoot, "project_root", TASK_PROJECT_ROOT_MAX_LENGTH);
+		const limit = input.limit ?? NOTE_LIST_DEFAULT_LIMIT;
+		if (!Number.isInteger(limit) || limit < 1 || limit > NOTE_LIST_MAX_LIMIT) {
+			throw new Error(`note limit must be an integer from 1 to ${NOTE_LIST_MAX_LIMIT}`);
+		}
+		const filterHash = notesPageFilterHash(input, projectRoot);
+		const cursor = decodeNotesPageCursor(input.cursor, filterHash);
+		const candidates = this.artifacts.query({
+			kind: "doc",
+			subtype: NOTE_SUBTYPE,
+			...(input.status ? { status: input.status } : { statuses: ["draft", "active"] }),
+			...(input.text ? { text: input.text } : {}),
+			...(projectRoot ? { extraEquals: { projectRoot } } : {}),
+			order: "created_desc",
+			...(cursor ? { after: { createdAt: cursor.createdAt, id: cursor.id } } : {}),
+			limit: limit + 1,
+		});
+		const items = candidates.slice(0, limit);
+		return {
+			items,
+			...(candidates.length > limit && items.length > 0 ? { nextCursor: encodeNotesPageCursor(items.at(-1)!, filterHash) } : {}),
+		};
+	}
+
 	show(id: string, projectRoot: string): Artifact {
 		const note = this.requireNote(id);
 		this.requireProject(note, projectRoot);

package/src/ops.ts

@@ -367,8 +367,14 @@ export function queryArtifacts(db: Db, filter: ArtifactQuery): Artifact[] {
 		conditions.push("json_extract(extra, ?) = ?");
 		params.push(`$.${key}`, value);
 	}
+	if (filter.after) {
+		if (filter.order !== "created_desc") throw new Error("artifact query cursor requires created_desc ordering");
+		if (!filter.after.createdAt || !filter.after.id) throw new Error("artifact query cursor is invalid");
+		conditions.push("(created_at < ? OR (created_at = ? AND id > ?))");
+		params.push(filter.after.createdAt, filter.after.createdAt, filter.after.id);
+	}
 	if (conditions.length) sql += ` WHERE ${conditions.join(" AND ")}`;
-	sql += " ORDER BY updated_at DESC";
+	sql += filter.order === "created_desc" ? " ORDER BY created_at DESC, id ASC" : " ORDER BY updated_at DESC, id ASC";
 	if (filter.limit !== undefined) {
 		if (!Number.isInteger(filter.limit) || filter.limit < 1) throw new Error("artifact query limit must be a positive integer");
 		sql += " LIMIT ?";

package/src/service.ts

@@ -409,6 +409,7 @@ function handlers(
 		"tasks.create": forwardToModule("tasks.create"),
 		"tasks.update": forwardToModule("tasks.update"),
 		"tasks.list": forwardToModule("tasks.list"),
+		"tasks.list_page": forwardToModule("tasks.list_page"),
 		"tasks.graph": forwardToModule("tasks.graph"),
 		"tasks.plan": forwardToModule("tasks.plan"),
 		"tasks.show": forwardToModule("tasks.show"),
@@ -487,6 +488,7 @@ function handlers(
 		"docs.update": forwardToModule("docs.update"),
 		"notes.capture": forwardToModule("notes.capture"),
 		"notes.list": forwardToModule("notes.list"),
+		"notes.list_page": forwardToModule("notes.list_page"),
 		"notes.show": forwardToModule("notes.show"),
 		"notes.history": forwardToModule("notes.history"),
 		"notes.consume": forwardToModule("notes.consume"),

package/src/task/task-service.ts

@@ -11,6 +11,8 @@ import {
 	TASK_EXECUTION_MAX_NODES,
 	TASK_LABEL_MAX_COUNT,
 	TASK_LABEL_MAX_LENGTH,
+	TASK_LIST_PAGE_DEFAULT_LIMIT,
+	TASK_LIST_PAGE_MAX_LIMIT,
 	TASK_SCOPE_MAX_TASKS,
 	TASK_TITLE_MAX_LENGTH,
 } from "../constants.ts";
@@ -98,6 +100,15 @@ export interface TaskFilter {
 	labels?: string[];
 }
 
+export interface TaskPageFilter extends TaskFilter {
+	cursor?: string;
+}
+
+export interface TaskPage {
+	items: Artifact[];
+	nextCursor?: string;
+}
+
 export type TaskStatus = TaskLifecycleStatus;
 
 export interface TaskMutationMetadata {
@@ -207,6 +218,45 @@ function canonicalJson(value: unknown): string {
 	return JSON.stringify(value) ?? "null";
 }
 
+interface TaskPageCursor {
+	v: 1;
+	createdAt: string;
+	id: string;
+	filterHash: string;
+}
+
+function taskPageFilterHash(filter: TaskFilter, selection: TaskViewSelection): string {
+	return createHash("sha256")
+		.update(
+			canonicalJson({
+				status: filter.status,
+				text: filter.text,
+				labels: [...(filter.labels ?? [])].sort(),
+				mode: selection.mode,
+				projectRoot: selection.projectRoot,
+				rootTaskId: selection.rootTaskId,
+			}),
+		)
+		.digest("base64url");
+}
+
+function encodeTaskPageCursor(task: Artifact, filterHash: string): string {
+	return Buffer.from(JSON.stringify({ v: 1, createdAt: task.created_at, id: task.id, filterHash } satisfies TaskPageCursor)).toString(
+		"base64url",
+	);
+}
+
+function decodeTaskPageCursor(cursor: string | undefined, filterHash: string): TaskPageCursor | undefined {
+	if (cursor === undefined) return undefined;
+	try {
+		const parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8")) as Partial<TaskPageCursor>;
+		if (parsed.v !== 1 || !parsed.createdAt || !parsed.id || parsed.filterHash !== filterHash) throw new Error("invalid cursor");
+		return parsed as TaskPageCursor;
+	} catch {
+		throw new Error("task page cursor is invalid or does not match the requested filters");
+	}
+}
+
 export class Tasks {
 	constructor(
 		private readonly artifacts: ArtifactStore,
@@ -428,6 +478,52 @@ export class Tasks {
 			.slice(0, limit);
 	}
 
+	/** Stable, cursor-paged Task inventory. Creation order is immutable, so content updates cannot move an item between pages. */
+	listPage(filter: TaskPageFilter = {}): TaskPage {
+		const selection = this.projectScope.scopeSelection(filter.projectRoot, filter.scope, filter.rootTaskId);
+		const limit = filter.limit ?? TASK_LIST_PAGE_DEFAULT_LIMIT;
+		if (!Number.isInteger(limit) || limit < 1 || limit > TASK_LIST_PAGE_MAX_LIMIT) {
+			throw new Error(`task page limit must be between 1 and ${TASK_LIST_PAGE_MAX_LIMIT}`);
+		}
+		const filterHash = taskPageFilterHash(filter, selection);
+		const cursor = decodeTaskPageCursor(filter.cursor, filterHash);
+		let candidates: Artifact[];
+		if (selection.mode === "all") {
+			candidates = this.artifacts.query({
+				kind: "task",
+				excludeSubtype: DISCUSSION_SUBTYPE,
+				status: filter.status,
+				text: filter.text,
+				labels: filter.labels,
+				order: "created_desc",
+				...(cursor ? { after: { createdAt: cursor.createdAt, id: cursor.id } } : {}),
+				limit: limit + 1,
+			});
+		} else {
+			const ids = this.scopes.taskIds(selection.projectRoot, TASK_SCOPE_MAX_TASKS + 1);
+			if (ids.length > TASK_SCOPE_MAX_TASKS) throw new Error(`task project scope exceeds ${TASK_SCOPE_MAX_TASKS} tasks`);
+			const selectedIds = selection.mode === "graph" ? this.descendantIds(selection.rootTaskId!, ids) : new Set(ids);
+			const text = filter.text?.toLowerCase();
+			const labels = filter.labels ?? [];
+			candidates = this.artifacts
+				.query({ kind: "task", excludeSubtype: DISCUSSION_SUBTYPE, ids: [...selectedIds] })
+				.filter((task) => filter.status === undefined || task.status === filter.status)
+				.filter((task) => text === undefined || task.title.toLowerCase().includes(text) || task.body.toLowerCase().includes(text))
+				.filter((task) => labels.every((label) => task.labels.includes(label)))
+				.sort((left, right) => right.created_at.localeCompare(left.created_at) || left.id.localeCompare(right.id))
+				.filter(
+					(task) =>
+						cursor === undefined || task.created_at < cursor.createdAt || (task.created_at === cursor.createdAt && task.id > cursor.id),
+				)
+				.slice(0, limit + 1);
+		}
+		const items = candidates.slice(0, limit);
+		return {
+			items,
+			...(candidates.length > limit && items.length > 0 ? { nextCursor: encodeTaskPageCursor(items.at(-1)!, filterHash) } : {}),
+		};
+	}
+
 	scopeSelection(projectRoot?: string, mode?: TaskViewMode, rootTaskId?: string): TaskViewSelection {
 		return this.projectScope.scopeSelection(projectRoot, mode, rootTaskId);
 	}