@danypops/papyrus 0.31.1 → 0.32.0

package/extension/src/domain-tools.ts

@@ -1,6 +1,7 @@
 import type { AgentToolUpdateCallback, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import type { Artifact } from "../../src/domain/artifact.ts";
+import type { TaskLease } from "../../src/domain/task-lease.ts";
 import { PROOF_TYPES } from "../../src/domain/checklist.ts";
 import type { GateResult } from "../../src/domain/gate.ts";
 import type { TaskExecutionPlan } from "../../src/task-execution.ts";
@@ -237,7 +238,7 @@ export function registerTasksTool(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "tasks",
 		label: "Tasks",
-		description: "Task domain tool. ACTIONS: create, update, list, show, history, scope, set_scope, assign_project, graph, plan, active, focused, focus, pause, unpause, clear_focus, start, submit, complete, reject, retry, cancel, run_gates, set_checklist, depend, undepend, contain, uncontain, remove, restore. Lifecycle is todo → in-progress → review → done, with review failure → rejected and retry → in-progress; canceled is terminal. update can recover a Task accidentally created terminal by setting status=todo with a reason, but cannot rewrite legitimate lifecycle history. 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. undepend/uncontain are idempotent for an already-absent relationship and never start, complete, or focus work merely because an edge disappeared; uncontain removes both contains and part_of edges atomically. remove moves a Task to a time-gated trash (restorable via restore until the purge deadline; refuses if it is the live Task Focus). PREFER addressing a task by `name` (its exact title) over `id` for every action -- id is a backend implementation detail, resolved from name automatically, and only needs to appear explicitly when a name is genuinely ambiguous (two tasks share a title; the error will say so and list the real ids to disambiguate with). Task results likewise show name and status, not id, unless two shown tasks share a title. `dependency_name`/`parent_name`/`child_name`/`root_task_name`/`depends_on_names` are the name-based equivalents of `dependency_id`/`parent_id`/`child_id`/`root_task_id`/`depends_on`. Prefer this over low-level papyrus_* tools for task work.",
+		description: "Task domain tool. ACTIONS: create, update, list, show, history, scope, set_scope, assign_project, graph, plan, active, focused, focus, pause, unpause, clear_focus, start, submit, complete, reject, retry, cancel, run_gates, set_checklist, depend, undepend, contain, uncontain, remove, restore, claim, heartbeat_lease, release_lease, lease, event_feed. Lifecycle is todo → in-progress → review → done, with review failure → rejected and retry → in-progress; canceled is terminal. update can recover a Task accidentally created terminal by setting status=todo with a reason, but cannot rewrite legitimate lifecycle history. 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. undepend/uncontain are idempotent for an already-absent relationship and never start, complete, or focus work merely because an edge disappeared; uncontain removes both contains and part_of edges atomically. remove moves a Task to a time-gated trash (restorable via restore until the purge deadline; refuses if it is the live Task Focus). claim/heartbeat_lease/release_lease/lease manage a bounded work-reservation lease -- independent of both lifecycle status and Focus, so multiple sessions can Focus the same task while only one owner holds its lease at a time; claim throws if a DIFFERENT owner already holds a live lease, release/heartbeat require the exact token claim returned. `owner` defaults to this session's own id when omitted. PREFER addressing a task by `name` (its exact title) over `id` for every action -- id is a backend implementation detail, resolved from name automatically, and only needs to appear explicitly when a name is genuinely ambiguous (two tasks share a title; the error will say so and list the real ids to disambiguate with). Task results likewise show name and status, not id, unless two shown tasks share a title. `dependency_name`/`parent_name`/`child_name`/`root_task_name`/`depends_on_names` are the name-based equivalents of `dependency_id`/`parent_id`/`child_id`/`root_task_id`/`depends_on`. Prefer this over low-level papyrus_* tools for task work.",
 		parameters: Type.Object({
 			action: Type.String(),
 			id: Type.Optional(Type.String()),
@@ -268,6 +269,11 @@ export function registerTasksTool(pi: ExtensionAPI): void {
 			scope: Type.Optional(Type.Union([Type.Literal("project"), Type.Literal("graph"), Type.Literal("all")])),
 			root_task_id: Type.Optional(Type.String()),
 			root_task_name: Type.Optional(Type.String()),
+			owner: Type.Optional(Type.String()),
+			token: Type.Optional(Type.String()),
+			ttl_ms: Type.Optional(Type.Number()),
+			note: Type.Optional(Type.String()),
+			event_types: Type.Optional(Type.Array(Type.String())),
 		}),
 		renderCall(args, theme) { return renderPapyrusToolCall("Tasks", args, theme); },
 		renderResult(result, options, theme, context) { return renderPapyrusToolResult(result, options, theme, context); },
@@ -413,6 +419,23 @@ export function registerTasksTool(pi: ExtensionAPI): void {
 						}))),
 					);
 				}
+				if (action === "event_feed") {
+					const page = await callService<Record<string, unknown>, { events: Array<{ id: number; occurredAt: string; taskId: string; type: string }>; nextCursor?: number }>("tasks.event_feed", { cursor: params.cursor, limit: params.limit, event_types: params.event_types });
+					const output = page.events.length === 0 ? "No events." : page.events.map((event) => `${event.id} ${event.occurredAt} ${event.taskId} ${event.type}`).join("\n");
+					return text(page.nextCursor !== undefined ? `${output}\n\n(more available -- resume with cursor: ${page.nextCursor})` : output, createPreviewDetails("tasks.event_feed", "Task event feed", output));
+				}
+				if (action === "claim" || action === "heartbeat_lease" || action === "release_lease" || action === "lease") {
+					const leaseRequest = { ...request, owner: (params.owner as string | undefined) ?? resolvedSessionId };
+					if (action === "release_lease") {
+						const released = await callService<Record<string, unknown>, { released: boolean }>("tasks.release_lease", leaseRequest);
+						const output = released.released ? "Lease released." : "No live lease to release.";
+						return text(output, createPreviewDetails("tasks.release_lease", "Task lease", output));
+					}
+					const operation = action === "claim" ? "tasks.claim" : action === "heartbeat_lease" ? "tasks.heartbeat_lease" : "tasks.lease";
+					const lease = await callService<Record<string, unknown>, TaskLease | null>(operation, leaseRequest);
+					const output = lease ? `Leased by "${lease.owner}" until ${lease.leaseExpiresAt} (token ${lease.token}).` : "No live lease.";
+					return text(output, createPreviewDetails(operation, "Task lease", output));
+				}
 				const trashResult = await handleArtifactRemoveRestore(action, params);
 				if (trashResult) return trashResult;
 				const operations = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.31.1",
+  "version": "0.32.0",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],

package/src/adapters/sqlite-task-event-store.ts

@@ -1,11 +1,14 @@
 import type { Db } from "../db.ts";
 import { inTransaction } from "../db.ts";
 import {
+	normalizeTaskEventFeedQuery,
 	normalizeTaskHistoryQuery,
 	validateTaskEvent,
 	type AppendTaskEvent,
 	type TaskEvent,
 	type TaskEventEvidence,
+	type TaskEventFeedPage,
+	type TaskEventFeedQuery,
 	type TaskEventType,
 	type TaskHistoryPage,
 	type TaskHistoryQuery,
@@ -89,4 +92,22 @@ export class SQLiteTaskEventStore implements TaskEventStore {
 		const events = rows.slice(0, limit).map(mapRow);
 		return { events, ...(hasMore ? { nextCursor: events.at(-1)!.id } : {}) };
 	}
+
+	feed(query: TaskEventFeedQuery = {}): TaskEventFeedPage {
+		const { limit, cursor, eventTypes } = normalizeTaskEventFeedQuery(query);
+		const typeFilter = eventTypes ? `AND event_type IN (${eventTypes.map(() => "?").join(", ")})` : "";
+		const params: unknown[] = [];
+		if (cursor !== undefined) params.push(cursor);
+		if (eventTypes) params.push(...eventTypes);
+		params.push(limit + 1);
+		const rows = this.db.prepare(`
+			SELECT * FROM task_events
+			WHERE 1=1 ${cursor === undefined ? "" : "AND id > ?"} ${typeFilter}
+			ORDER BY id ASC
+			LIMIT ?
+		`).all(...params) as TaskEventRow[];
+		const hasMore = rows.length > limit;
+		const events = rows.slice(0, limit).map(mapRow);
+		return { events, ...(hasMore ? { nextCursor: events.at(-1)!.id } : {}) };
+	}
 }

package/src/adapters/sqlite-task-lease-store.ts

@@ -0,0 +1,98 @@
+import { TASK_LEASE_DEFAULT_TTL_MS } from "../constants.ts";
+import type { Db } from "../db.ts";
+import { inTransaction } from "../db.ts";
+import { isLeaseExpired, validateLeaseNote, validateLeaseOwner, validateLeaseTtlMs, type TaskLease } from "../domain/task-lease.ts";
+import type { TaskLeaseStore } from "../ports/task-lease-store.ts";
+
+interface TaskLeaseRow {
+	task_id: string;
+	owner: string;
+	token: string;
+	claimed_at: string;
+	lease_expires_at: string;
+	heartbeat_at: string | null;
+	note: string | null;
+}
+
+function fromRow(row: TaskLeaseRow): TaskLease {
+	return {
+		taskId: row.task_id,
+		owner: row.owner,
+		token: row.token,
+		claimedAt: row.claimed_at,
+		leaseExpiresAt: row.lease_expires_at,
+		...(row.heartbeat_at ? { heartbeatAt: row.heartbeat_at } : {}),
+		...(row.note ? { note: row.note } : {}),
+	};
+}
+
+export class SQLiteTaskLeaseStore implements TaskLeaseStore {
+	constructor(private readonly db: Db) {}
+
+	private row(taskId: string): TaskLeaseRow | undefined {
+		return (this.db.prepare("SELECT * FROM task_leases WHERE task_id = ?").get(taskId) as TaskLeaseRow | null) ?? undefined;
+	}
+
+	claim(taskId: string, owner: string, ttlMs: number = TASK_LEASE_DEFAULT_TTL_MS, note?: string): TaskLease {
+		validateLeaseOwner(owner);
+		validateLeaseNote(note);
+		validateLeaseTtlMs(ttlMs);
+		return inTransaction(this.db, () => {
+			const now = new Date();
+			const nowIso = now.toISOString();
+			const existing = this.row(taskId);
+			const current = existing ? fromRow(existing) : undefined;
+			if (current && !isLeaseExpired(current, nowIso) && current.owner !== owner) {
+				throw new Error(`task "${taskId}" is already leased by "${current.owner}" until ${current.leaseExpiresAt}`);
+			}
+			const renewingSameOwner = current !== undefined && !isLeaseExpired(current, nowIso) && current.owner === owner;
+			const token = renewingSameOwner ? current!.token : crypto.randomUUID();
+			const claimedAt = renewingSameOwner ? current!.claimedAt : nowIso;
+			const leaseExpiresAt = new Date(now.getTime() + ttlMs).toISOString();
+			this.db.prepare(`
+				INSERT INTO task_leases (task_id, owner, token, claimed_at, lease_expires_at, heartbeat_at, note)
+				VALUES (?, ?, ?, ?, ?, NULL, ?)
+				ON CONFLICT(task_id) DO UPDATE SET owner = excluded.owner, token = excluded.token, claimed_at = excluded.claimed_at,
+					lease_expires_at = excluded.lease_expires_at, heartbeat_at = NULL, note = excluded.note
+			`).run(taskId, owner, token, claimedAt, leaseExpiresAt, note ?? null);
+			return fromRow(this.row(taskId)!);
+		});
+	}
+
+	heartbeat(taskId: string, owner: string, token: string, ttlMs: number = TASK_LEASE_DEFAULT_TTL_MS): TaskLease {
+		validateLeaseTtlMs(ttlMs);
+		return inTransaction(this.db, () => {
+			const nowIso = new Date().toISOString();
+			const existing = this.row(taskId);
+			const current = existing ? fromRow(existing) : undefined;
+			if (!current || isLeaseExpired(current, nowIso)) throw new Error(`task "${taskId}" has no live lease to renew`);
+			if (current.owner !== owner || current.token !== token) throw new Error(`lease for task "${taskId}" is held by a different owner/token`);
+			const leaseExpiresAt = new Date(Date.now() + ttlMs).toISOString();
+			this.db.prepare("UPDATE task_leases SET lease_expires_at = ?, heartbeat_at = ? WHERE task_id = ?").run(leaseExpiresAt, nowIso, taskId);
+			return fromRow(this.row(taskId)!);
+		});
+	}
+
+	release(taskId: string, owner: string, token: string): { released: boolean } {
+		return inTransaction(this.db, () => {
+			const nowIso = new Date().toISOString();
+			const existing = this.row(taskId);
+			const current = existing ? fromRow(existing) : undefined;
+			if (!current || isLeaseExpired(current, nowIso)) return { released: false };
+			if (current.owner !== owner || current.token !== token) throw new Error(`lease for task "${taskId}" is held by a different owner/token`);
+			this.db.prepare("DELETE FROM task_leases WHERE task_id = ?").run(taskId);
+			return { released: true };
+		});
+	}
+
+	get(taskId: string): TaskLease | undefined {
+		const existing = this.row(taskId);
+		if (!existing) return undefined;
+		const lease = fromRow(existing);
+		return isLeaseExpired(lease, new Date().toISOString()) ? undefined : lease;
+	}
+
+	reapExpired(olderThanIso: string): number {
+		return this.db.prepare("DELETE FROM task_leases WHERE lease_expires_at < ?").run(olderThanIso).changes;
+	}
+}

package/src/cli.ts

@@ -148,6 +148,12 @@ const USAGE = `Usage:
   papyrus tasks unpause [--session-id <id>] [--session-secret <secret>] [--json]
   papyrus tasks clear-focus [--session-id <id>] [--session-secret <secret>] [--json]
   papyrus tasks reap-stale-focus [--json]
+  papyrus tasks claim <id> --owner <owner> [--ttl-ms <ms>] [--note <text>] [--json]
+  papyrus tasks heartbeat-lease <id> --owner <owner> --token <token> [--ttl-ms <ms>] [--json]
+  papyrus tasks release-lease <id> --owner <owner> --token <token> [--json]
+  papyrus tasks lease <id> [--json]
+  papyrus tasks reap-stale-leases [--json]
+  papyrus tasks event-feed [--cursor <n>] [--limit <n>] [--event-types-json <json>] [--json]
   papyrus tasks history <id> [--json]
   papyrus tasks scope [project|all|graph <root-id>] [--json]
   papyrus tasks assign-project <id> [project-root] [--json]
@@ -182,6 +188,7 @@ function usage(): never {
 type TaskCliClient = Pick<PapyrusClient, "call">;
 type MigrationResult = { from: number; to: number; applied: string[] };
 type CliArtifact = { id: string; title: string; status: string; body?: string };
+type CliTaskLease = { taskId: string; owner: string; token: string; claimedAt: string; leaseExpiresAt: string; heartbeatAt?: string; note?: string };
 type CliCompletion = Omit<TaskCompletion, "artifact" | "blocked"> & {
 	artifact: CliArtifact;
 	blocked: Array<Omit<TaskBlockage, "artifact"> & { artifact: CliArtifact }>;
@@ -1320,6 +1327,12 @@ export async function runTaskCli(args: string[], client: TaskCliClient, projectR
 	let limit: number | undefined;
 	let listScope: "project" | "graph" | "all" | undefined;
 	let rootTaskId: string | undefined;
+	let owner: string | undefined;
+	let token: string | undefined;
+	let ttlMs: number | undefined;
+	let note: string | undefined;
+	let cursor: number | undefined;
+	let eventTypes: string[] | undefined;
 	for (let index = 0; index < args.length; index++) {
 		const argument = args[index]!;
 		if (argument === "--json") continue;
@@ -1375,6 +1388,22 @@ export async function runTaskCli(args: string[], client: TaskCliClient, projectR
 			continue;
 		}
 		if (argument === "--root-task-id") { rootTaskId = args[++index]; if (!rootTaskId) throw new Error("--root-task-id requires a value"); continue; }
+		if (argument === "--owner") { owner = args[++index]; if (!owner) throw new Error("--owner requires a value"); continue; }
+		if (argument === "--token") { token = args[++index]; if (!token) throw new Error("--token requires a value"); continue; }
+		if (argument === "--note") { note = args[++index]; if (note === undefined) throw new Error("--note requires a value"); continue; }
+		if (argument === "--ttl-ms") {
+			const value = args[++index];
+			if (!value || Number.isNaN(Number(value))) throw new Error("--ttl-ms requires a numeric value");
+			ttlMs = Number(value);
+			continue;
+		}
+		if (argument === "--cursor") {
+			const value = args[++index];
+			if (!value || Number.isNaN(Number(value))) throw new Error("--cursor requires a numeric value");
+			cursor = Number(value);
+			continue;
+		}
+		if (argument === "--event-types-json") { eventTypes = parseJsonStringArrayFlag(args[++index]!, "--event-types-json"); continue; }
 		if (argument.startsWith("--")) throw new Error(`unknown tasks option ${argument}`);
 		positional.push(argument);
 	}
@@ -1426,6 +1455,53 @@ export async function runTaskCli(args: string[], client: TaskCliClient, projectR
 			human = `Reaped ${reaped.removed} stale Focus scope(s).`;
 			break;
 		}
+		case "claim": {
+			if (!id || dependencyId) throw new Error("tasks claim requires exactly one task id");
+			if (!owner) throw new Error("tasks claim requires --owner");
+			const lease = await client.call<Record<string, unknown>, CliTaskLease>("tasks.claim", { id, owner, ttl_ms: ttlMs, note });
+			result = lease;
+			human = `Claimed by "${lease.owner}" until ${lease.leaseExpiresAt} (token ${lease.token}).`;
+			break;
+		}
+		case "heartbeat-lease": {
+			if (!id || dependencyId) throw new Error("tasks heartbeat-lease requires exactly one task id");
+			if (!owner || !token) throw new Error("tasks heartbeat-lease requires --owner and --token");
+			const lease = await client.call<Record<string, unknown>, CliTaskLease>("tasks.heartbeat_lease", { id, owner, token, ttl_ms: ttlMs });
+			result = lease;
+			human = `Renewed until ${lease.leaseExpiresAt}.`;
+			break;
+		}
+		case "release-lease": {
+			if (!id || dependencyId) throw new Error("tasks release-lease requires exactly one task id");
+			if (!owner || !token) throw new Error("tasks release-lease requires --owner and --token");
+			const released = await client.call<Record<string, unknown>, { released: boolean }>("tasks.release_lease", { id, owner, token });
+			result = released;
+			human = released.released ? "Lease released." : "No live lease to release.";
+			break;
+		}
+		case "lease": {
+			if (!id || dependencyId) throw new Error("tasks lease requires exactly one task id");
+			const lease = await client.call<Record<string, unknown>, CliTaskLease | null>("tasks.lease", { id });
+			result = lease;
+			human = lease ? `Leased by "${lease.owner}" until ${lease.leaseExpiresAt}.` : "No live lease.";
+			break;
+		}
+		case "reap-stale-leases": {
+			if (id) throw new Error("tasks reap-stale-leases accepts no positional arguments");
+			const reaped = await client.call<Record<string, unknown>, { removed: number }>("tasks.reap_stale_leases", {});
+			result = reaped;
+			human = `Reaped ${reaped.removed} expired lease(s).`;
+			break;
+		}
+		case "event-feed": {
+			if (id) throw new Error("tasks event-feed accepts no positional arguments");
+			const page = await client.call<Record<string, unknown>, import("./domain/task-event.ts").TaskEventFeedPage>("tasks.event_feed", { cursor, limit, event_types: eventTypes });
+			result = page;
+			human = page.events.length === 0
+				? "No events."
+				: page.events.map((event) => `${event.id} ${event.occurredAt} ${event.taskId} ${event.type}`).join("\n");
+			break;
+		}
 		case "create": {
 			if (id) throw new Error("tasks create accepts no positional arguments");
 			if (!title) throw new Error("tasks create requires --title");

package/src/constants.ts

@@ -7,7 +7,7 @@ export const DAEMON_PROBE_TIMEOUT_MS = 800;
 export const DAEMON_UNIT_NAME = "papyrus.service";
 export const DAEMON_DIR_ENV = "PAPYRUS_DAEMON_DIR";
 export const SQLITE_BUSY_TIMEOUT_MS = 5_000;
-export const SQLITE_SCHEMA_VERSION = 19;
+export const SQLITE_SCHEMA_VERSION = 20;
 export const SERVICE_MAX_BODY_BYTES = 1_048_576;
 
 export const WAL_CHECKPOINT_INTERVAL_MS = 60_000;
@@ -134,6 +134,15 @@ export const TASK_HISTORY_MAX_LIMIT = 100;
 export const TASK_EVENT_MAX_EVIDENCE_BYTES = 65_536;
 export const TASK_EVENT_ACTOR_MAX_LENGTH = 128;
 export const TASK_EVENT_REASON_MAX_LENGTH = 2_000;
+/** Task lease claims: bounded work reservation, orthogonal to Task lifecycle and Focus. */
+export const TASK_LEASE_DEFAULT_TTL_MS = 10 * 60 * 1000;
+export const TASK_LEASE_MIN_TTL_MS = 1_000;
+export const TASK_LEASE_MAX_TTL_MS = 4 * 60 * 60 * 1000;
+export const TASK_LEASE_OWNER_MAX_LENGTH = 128;
+export const TASK_LEASE_NOTE_MAX_LENGTH = 500;
+/** Global, cross-task sequenced Task event feed (readiness/lifecycle subscriptions), distinct from tasks.history's per-task cursor. */
+export const TASK_EVENT_FEED_DEFAULT_LIMIT = 50;
+export const TASK_EVENT_FEED_MAX_LIMIT = 200;
 /** Deferred human Note payload, inbox, and provenance bounds. */
 export const NOTE_BODY_MAX_CHARACTERS = 10_000;
 export const NOTE_TITLE_MAX_CHARACTERS = 80;

package/src/db.ts

@@ -256,6 +256,16 @@ BEGIN SELECT RAISE(ABORT, 'discussion_rounds are append-only'); END;
 CREATE TRIGGER IF NOT EXISTS discussion_rounds_no_delete BEFORE DELETE ON discussion_rounds
 WHEN NOT EXISTS (SELECT 1 FROM artifact_trash WHERE artifact_id = OLD.discussion_id AND purge_after <= strftime('%Y-%m-%dT%H:%M:%fZ','now'))
 BEGIN SELECT RAISE(ABORT, 'discussion_rounds are append-only except during an explicit, elapsed-grace-period artifact trash purge'); END;
+CREATE TABLE IF NOT EXISTS task_leases (
+	task_id           TEXT PRIMARY KEY REFERENCES artifacts(id),
+	owner             TEXT NOT NULL,
+	token             TEXT NOT NULL,
+	claimed_at        TEXT NOT NULL,
+	lease_expires_at  TEXT NOT NULL,
+	heartbeat_at      TEXT,
+	note              TEXT
+);
+CREATE INDEX IF NOT EXISTS task_leases_expiry_idx ON task_leases(lease_expires_at);
 `;
 
 const SEED_SQL = `
@@ -545,6 +555,27 @@ const FUTURE_MIGRATIONS: ReadonlyArray<PapyrusMigration> = [
 			if (!existing.has("option_descriptions")) db.exec("ALTER TABLE discussion_rounds ADD COLUMN option_descriptions TEXT");
 		},
 	},
+	{
+		version: 20,
+		name: "task-leases",
+		// See domain/task-lease.ts. One row per task (a task has at most one live lease at a time),
+		// same PRIMARY KEY-per-task shape as task_focus -- but a lease is deliberately orthogonal to
+		// Focus (multiple sessions can focus the same task; only one owner can hold its lease).
+		up: (db) => {
+			db.exec(`
+				CREATE TABLE IF NOT EXISTS task_leases (
+					task_id           TEXT PRIMARY KEY REFERENCES artifacts(id),
+					owner             TEXT NOT NULL,
+					token             TEXT NOT NULL,
+					claimed_at        TEXT NOT NULL,
+					lease_expires_at  TEXT NOT NULL,
+					heartbeat_at      TEXT,
+					note              TEXT
+				);
+				CREATE INDEX IF NOT EXISTS task_leases_expiry_idx ON task_leases(lease_expires_at);
+			`);
+		},
+	},
 ];
 
 /**

package/src/domain/task-event.ts

@@ -1,5 +1,7 @@
 import {
 	TASK_EVENT_ACTOR_MAX_LENGTH,
+	TASK_EVENT_FEED_DEFAULT_LIMIT,
+	TASK_EVENT_FEED_MAX_LIMIT,
 	TASK_EVENT_MAX_EVIDENCE_BYTES,
 	TASK_EVENT_REASON_MAX_LENGTH,
 	TASK_HISTORY_DEFAULT_LIMIT,
@@ -28,6 +30,7 @@ export const TASK_EVENT_TYPES = [
 	"dependency_removed",
 	"containment_added",
 	"containment_removed",
+	"became_ready",
 ] as const;
 
 export type TaskEventType = typeof TASK_EVENT_TYPES[number];
@@ -86,6 +89,39 @@ export interface TaskHistoryPage {
 	nextCursor?: number;
 }
 
+/**
+ * A bounded, sequenced, cross-task replay feed -- distinct from TaskHistoryQuery, which is
+ * scoped to one task. A consumer resumes exactly where it left off via nextCursor rather than
+ * re-scanning the whole graph; always ascending (a subscription only ever replays forward).
+ */
+export interface TaskEventFeedQuery {
+	cursor?: number;
+	limit?: number;
+	eventTypes?: TaskEventType[];
+}
+
+export interface TaskEventFeedPage {
+	events: TaskEvent[];
+	nextCursor?: number;
+}
+
+export function normalizeTaskEventFeedQuery(query: TaskEventFeedQuery = {}): Required<Pick<TaskEventFeedQuery, "limit">> & Pick<TaskEventFeedQuery, "cursor" | "eventTypes"> {
+	const limit = query.limit ?? TASK_EVENT_FEED_DEFAULT_LIMIT;
+	if (!Number.isInteger(limit) || limit < 1 || limit > TASK_EVENT_FEED_MAX_LIMIT) {
+		throw new Error(`task event feed limit must be between 1 and ${TASK_EVENT_FEED_MAX_LIMIT}`);
+	}
+	if (query.cursor !== undefined && (!Number.isInteger(query.cursor) || query.cursor < 0)) {
+		throw new Error("task event feed cursor must be a non-negative integer");
+	}
+	if (query.eventTypes !== undefined) {
+		if (query.eventTypes.length === 0) throw new Error("task event feed eventTypes, if provided, must be non-empty");
+		for (const type of query.eventTypes) {
+			if (!TASK_EVENT_TYPES.includes(type)) throw new Error(`unknown task event type "${type}"`);
+		}
+	}
+	return { limit, cursor: query.cursor, eventTypes: query.eventTypes };
+}
+
 export function normalizeTaskHistoryQuery(query: TaskHistoryQuery = {}): Required<Pick<TaskHistoryQuery, "limit" | "direction">> & Pick<TaskHistoryQuery, "cursor"> {
 	const limit = query.limit ?? TASK_HISTORY_DEFAULT_LIMIT;
 	if (!Number.isInteger(limit) || limit < 1 || limit > TASK_HISTORY_MAX_LIMIT) {

package/src/domain/task-lease.ts

@@ -0,0 +1,42 @@
+import { TASK_LEASE_MAX_TTL_MS, TASK_LEASE_MIN_TTL_MS, TASK_LEASE_NOTE_MAX_LENGTH, TASK_LEASE_OWNER_MAX_LENGTH } from "../constants.ts";
+
+/**
+ * A bounded work reservation on a Task, independent of both the Task's own lifecycle status
+ * and of per-scope Task Focus -- expresses "I intend to work this" for concurrent workers
+ * coordinating over the same Task graph, without claiming the Task actually started or that
+ * any particular session is looking at it.
+ */
+export interface TaskLease {
+	taskId: string;
+	owner: string;
+	token: string;
+	claimedAt: string;
+	leaseExpiresAt: string;
+	heartbeatAt?: string;
+	note?: string;
+}
+
+export function validateLeaseOwner(owner: string): string {
+	if (owner.length === 0 || owner.length > TASK_LEASE_OWNER_MAX_LENGTH) {
+		throw new Error(`lease owner must be between 1 and ${TASK_LEASE_OWNER_MAX_LENGTH} characters`);
+	}
+	return owner;
+}
+
+export function validateLeaseNote(note: string | undefined): string | undefined {
+	if (note !== undefined && note.length > TASK_LEASE_NOTE_MAX_LENGTH) {
+		throw new Error(`lease note cannot exceed ${TASK_LEASE_NOTE_MAX_LENGTH} characters`);
+	}
+	return note;
+}
+
+export function validateLeaseTtlMs(ttlMs: number): number {
+	if (!Number.isFinite(ttlMs) || ttlMs < TASK_LEASE_MIN_TTL_MS || ttlMs > TASK_LEASE_MAX_TTL_MS) {
+		throw new Error(`lease ttl_ms must be between ${TASK_LEASE_MIN_TTL_MS} and ${TASK_LEASE_MAX_TTL_MS}`);
+	}
+	return ttlMs;
+}
+
+export function isLeaseExpired(lease: Pick<TaskLease, "leaseExpiresAt">, now: string): boolean {
+	return lease.leaseExpiresAt <= now;
+}

package/src/modules/tasks.ts

@@ -19,7 +19,7 @@
  * including the composition root's own helpers.
  */
 import type { Checklist } from "../domain/checklist.ts";
-import type { TaskEventContext, TaskEventDirection } from "../domain/task-event.ts";
+import type { TaskEventContext, TaskEventDirection, TaskEventFeedQuery } from "../domain/task-event.ts";
 import type { TaskViewMode } from "../domain/task-scope.ts";
 import type { OperationDefinition } from "../module-registry.ts";
 import type { ArtifactStore } from "../ports/artifact-store.ts";
@@ -92,6 +92,7 @@ export const TASKS_OPERATION_NAMES = [
 	"tasks.pause", "tasks.unpause", "tasks.clear_focus", "tasks.start", "tasks.submit", "tasks.complete",
 	"tasks.run_gates", "tasks.set_checklist", "tasks.set_gates", "tasks.context", "tasks.reject", "tasks.retry", "tasks.cancel",
 	"tasks.depend", "tasks.undepend", "tasks.contain", "tasks.uncontain", "tasks.reap_stale_focus",
+	"tasks.claim", "tasks.heartbeat_lease", "tasks.release_lease", "tasks.lease", "tasks.reap_stale_leases", "tasks.event_feed",
 ] as const;
 
 export function tasksOperations(tasks: Tasks, artifacts: ArtifactStore, sessionIdentity: SessionIdentity): OperationDefinition[] {
@@ -171,5 +172,15 @@ export function tasksOperations(tasks: Tasks, artifacts: ArtifactStore, sessionI
 		define("tasks.undepend", (input: OperationInput) => tasks.undepend(string(input, "id"), string(input, "dependency_id"), eventContext(input))),
 		define("tasks.contain", (input: OperationInput) => tasks.contain(string(input, "parent_id"), string(input, "child_id"), eventContext(input))),
 		define("tasks.uncontain", (input: OperationInput) => tasks.uncontain(string(input, "parent_id"), string(input, "child_id"), eventContext(input))),
+		define("tasks.claim", (input: OperationInput) => tasks.claimLease(string(input, "id"), string(input, "owner"), optionalNumber(input, "ttl_ms"), optionalString(input, "note"))),
+		define("tasks.heartbeat_lease", (input: OperationInput) => tasks.heartbeatLease(string(input, "id"), string(input, "owner"), string(input, "token"), optionalNumber(input, "ttl_ms"))),
+		define("tasks.release_lease", (input: OperationInput) => tasks.releaseLease(string(input, "id"), string(input, "owner"), string(input, "token"))),
+		define("tasks.lease", (input: OperationInput) => tasks.getLease(string(input, "id")) ?? null),
+		define("tasks.reap_stale_leases", () => ({ removed: tasks.reapStaleLeases() })),
+		define("tasks.event_feed", (input: OperationInput) => tasks.eventFeed({
+			cursor: optionalNumber(input, "cursor"),
+			limit: optionalNumber(input, "limit"),
+			eventTypes: optionalStringArray(input, "event_types") as TaskEventFeedQuery["eventTypes"],
+		})),
 	];
 }

package/src/ports/task-event-store.ts

@@ -1,9 +1,21 @@
-import { normalizeTaskHistoryQuery, validateTaskEvent, type AppendTaskEvent, type TaskEvent, type TaskHistoryPage, type TaskHistoryQuery } from "../domain/task-event.ts";
+import {
+	normalizeTaskEventFeedQuery,
+	normalizeTaskHistoryQuery,
+	validateTaskEvent,
+	type AppendTaskEvent,
+	type TaskEvent,
+	type TaskEventFeedPage,
+	type TaskEventFeedQuery,
+	type TaskHistoryPage,
+	type TaskHistoryQuery,
+} from "../domain/task-event.ts";
 
 export interface TaskEventStore {
 	atomic<T>(operation: () => T): T;
 	append(event: AppendTaskEvent): TaskEvent;
 	history(taskId: string, query?: TaskHistoryQuery): TaskHistoryPage;
+	/** Bounded, sequenced, cross-task replay feed -- see TaskEventFeedQuery. */
+	feed(query?: TaskEventFeedQuery): TaskEventFeedPage;
 }
 
 export class InMemoryTaskEventStore implements TaskEventStore {
@@ -40,4 +52,14 @@ export class InMemoryTaskEventStore implements TaskEventStore {
 		const events = ordered.slice(0, limit);
 		return { events, ...(ordered.length > limit ? { nextCursor: events.at(-1)!.id } : {}) };
 	}
+
+	feed(query: TaskEventFeedQuery = {}): TaskEventFeedPage {
+		const { limit, cursor, eventTypes } = normalizeTaskEventFeedQuery(query);
+		const types = eventTypes ? new Set(eventTypes) : undefined;
+		const ordered = this.events
+			.filter((event) => (cursor === undefined || event.id > cursor) && (types === undefined || types.has(event.type)))
+			.sort((left, right) => left.id - right.id);
+		const events = ordered.slice(0, limit);
+		return { events, ...(ordered.length > limit ? { nextCursor: events.at(-1)!.id } : {}) };
+	}
 }

package/src/ports/task-lease-store.ts

@@ -0,0 +1,82 @@
+import { TASK_LEASE_DEFAULT_TTL_MS } from "../constants.ts";
+import { isLeaseExpired, validateLeaseNote, validateLeaseOwner, validateLeaseTtlMs, type TaskLease } from "../domain/task-lease.ts";
+
+export interface TaskLeaseStore {
+	/**
+	 * Creates a new lease, or renews the caller's own live lease in place (same token, extended
+	 * expiry). Throws if a *different* owner already holds a live (non-expired) lease.
+	 */
+	claim(taskId: string, owner: string, ttlMs?: number, note?: string): TaskLease;
+	/** Extends an existing live lease's expiry. Throws if no live lease exists, or owner/token do not match the current holder -- a stale or forged renewal must never silently succeed. */
+	heartbeat(taskId: string, owner: string, token: string, ttlMs?: number): TaskLease;
+	/** No-op (released: false) if no live lease exists. Throws if a live lease exists but owner/token do not match -- releasing a claim you don't hold is a real conflict, not a benign no-op. */
+	release(taskId: string, owner: string, token: string): { released: boolean };
+	/** The current live lease, or undefined if none exists or it has expired (an expired row reads as absent even before a reap sweep runs). */
+	get(taskId: string): TaskLease | undefined;
+	/** Deletes every lease row whose leaseExpiresAt is strictly before olderThanIso. Returns how many were removed. */
+	reapExpired(olderThanIso: string): number;
+}
+
+function newToken(): string {
+	return crypto.randomUUID();
+}
+
+export class InMemoryTaskLeaseStore implements TaskLeaseStore {
+	private readonly leases = new Map<string, TaskLease>();
+
+	claim(taskId: string, owner: string, ttlMs: number = TASK_LEASE_DEFAULT_TTL_MS, note?: string): TaskLease {
+		validateLeaseOwner(owner);
+		validateLeaseNote(note);
+		validateLeaseTtlMs(ttlMs);
+		const now = new Date();
+		const nowIso = now.toISOString();
+		const current = this.leases.get(taskId);
+		if (current && !isLeaseExpired(current, nowIso) && current.owner !== owner) {
+			throw new Error(`task "${taskId}" is already leased by "${current.owner}" until ${current.leaseExpiresAt}`);
+		}
+		const lease: TaskLease = {
+			taskId,
+			owner,
+			token: current && !isLeaseExpired(current, nowIso) && current.owner === owner ? current.token : newToken(),
+			claimedAt: current && !isLeaseExpired(current, nowIso) && current.owner === owner ? current.claimedAt : nowIso,
+			leaseExpiresAt: new Date(now.getTime() + ttlMs).toISOString(),
+			...(note !== undefined ? { note } : {}),
+		};
+		this.leases.set(taskId, lease);
+		return lease;
+	}
+
+	heartbeat(taskId: string, owner: string, token: string, ttlMs: number = TASK_LEASE_DEFAULT_TTL_MS): TaskLease {
+		validateLeaseTtlMs(ttlMs);
+		const nowIso = new Date().toISOString();
+		const current = this.leases.get(taskId);
+		if (!current || isLeaseExpired(current, nowIso)) throw new Error(`task "${taskId}" has no live lease to renew`);
+		if (current.owner !== owner || current.token !== token) throw new Error(`lease for task "${taskId}" is held by a different owner/token`);
+		const renewed: TaskLease = { ...current, leaseExpiresAt: new Date(Date.now() + ttlMs).toISOString(), heartbeatAt: nowIso };
+		this.leases.set(taskId, renewed);
+		return renewed;
+	}
+
+	release(taskId: string, owner: string, token: string): { released: boolean } {
+		const nowIso = new Date().toISOString();
+		const current = this.leases.get(taskId);
+		if (!current || isLeaseExpired(current, nowIso)) return { released: false };
+		if (current.owner !== owner || current.token !== token) throw new Error(`lease for task "${taskId}" is held by a different owner/token`);
+		this.leases.delete(taskId);
+		return { released: true };
+	}
+
+	get(taskId: string): TaskLease | undefined {
+		const current = this.leases.get(taskId);
+		if (!current || isLeaseExpired(current, new Date().toISOString())) return undefined;
+		return current;
+	}
+
+	reapExpired(olderThanIso: string): number {
+		let removed = 0;
+		for (const [taskId, lease] of this.leases) {
+			if (lease.leaseExpiresAt < olderThanIso) { this.leases.delete(taskId); removed++; }
+		}
+		return removed;
+	}
+}

package/src/service.ts

@@ -6,6 +6,7 @@ import { SQLiteGateRunner } from "./adapters/sqlite-gate-runner.ts";
 import { SQLiteArtifactScopeStore } from "./adapters/sqlite-artifact-scope-store.ts";
 import { SQLiteGraphProjectionStore } from "./adapters/sqlite-graph-projection-store.ts";
 import { SQLiteTaskFocusStore } from "./adapters/sqlite-task-focus-store.ts";
+import { SQLiteTaskLeaseStore } from "./adapters/sqlite-task-lease-store.ts";
 import { SQLiteTaskEventStore } from "./adapters/sqlite-task-event-store.ts";
 import { SQLiteTaskScopeStore } from "./adapters/sqlite-task-scope-store.ts";
 import { SQLiteSessionIdentityStore } from "./adapters/sqlite-session-identity-store.ts";
@@ -339,6 +340,12 @@ function handlers(
 		"tasks.undepend": forwardToModule("tasks.undepend"),
 		"tasks.contain": forwardToModule("tasks.contain"),
 		"tasks.uncontain": forwardToModule("tasks.uncontain"),
+		"tasks.claim": forwardToModule("tasks.claim"),
+		"tasks.heartbeat_lease": forwardToModule("tasks.heartbeat_lease"),
+		"tasks.release_lease": forwardToModule("tasks.release_lease"),
+		"tasks.lease": forwardToModule("tasks.lease"),
+		"tasks.reap_stale_leases": forwardToModule("tasks.reap_stale_leases"),
+		"tasks.event_feed": forwardToModule("tasks.event_feed"),
 		"tasks.reap_stale_focus": forwardToModule("tasks.reap_stale_focus"),
 		"docs.create": forwardToModule("docs.create"),
 		"docs.list": forwardToModule("docs.list"),
@@ -426,7 +433,8 @@ export function createPapyrusService(path: string): PapyrusService {
 	const focus = new SQLiteTaskFocusStore(db);
 	const events = new SQLiteTaskEventStore(db);
 	const scopes = new SQLiteTaskScopeStore(db);
-	const tasks = new Tasks(artifacts, gates, focus, events, scopes);
+	const leases = new SQLiteTaskLeaseStore(db);
+	const tasks = new Tasks(artifacts, gates, focus, events, scopes, leases);
 	const notes = new Notes(artifacts);
 	const projections = new SQLiteGraphProjectionStore(db);
 	const artifactScopes = new SQLiteArtifactScopeStore(db);

package/src/task-service.ts

@@ -13,12 +13,14 @@ import type { Artifact } from "./domain/artifact.ts";
 import { checklistEntries, validateChecklist, type Checklist, type ProofReference } from "./domain/checklist.ts";
 import { DISCUSSION_SUBTYPE, isDiscussionArtifact, readDiscussionExtra } from "./domain/discussion.ts";
 import { validateGates, type Gate, type GateResult } from "./domain/gate.ts";
-import type { AppendTaskEvent, TaskEventContext, TaskHistoryPage, TaskHistoryQuery, TaskLifecycleStatus } from "./domain/task-event.ts";
+import type { AppendTaskEvent, TaskEventContext, TaskEventFeedPage, TaskEventFeedQuery, TaskHistoryPage, TaskHistoryQuery, TaskLifecycleStatus } from "./domain/task-event.ts";
 import { normalizeProjectRoot, taskScopeLabel, type TaskScopeSource, type TaskViewMode, type TaskViewSelection } from "./domain/task-scope.ts";
 import type { ArtifactStore } from "./ports/artifact-store.ts";
 import type { GateRunner } from "./ports/gate-runner.ts";
 import { InMemoryTaskFocusStore, type TaskFocusStatus, type TaskFocusStore } from "./ports/task-focus-store.ts";
 import { InMemoryTaskEventStore, type TaskEventStore } from "./ports/task-event-store.ts";
+import { InMemoryTaskLeaseStore, type TaskLeaseStore } from "./ports/task-lease-store.ts";
+import type { TaskLease } from "./domain/task-lease.ts";
 import { InMemoryTaskScopeStore, type TaskScopeStore } from "./ports/task-scope-store.ts";
 import { assertDependencyEdgeAllowed } from "./task-execution.ts";
 
@@ -126,6 +128,7 @@ export class Tasks {
 		private readonly focusStore: TaskFocusStore = new InMemoryTaskFocusStore(),
 		private readonly events: TaskEventStore = new InMemoryTaskEventStore(),
 		private readonly scopes: TaskScopeStore = new InMemoryTaskScopeStore(),
+		private readonly leases: TaskLeaseStore = new InMemoryTaskLeaseStore(),
 	) {}
 
 	private require(id: string): Artifact {
@@ -403,6 +406,32 @@ export class Tasks {
 		return this.focusStore.reapStale(cutoff);
 	}
 
+	/** A lease is orthogonal to lifecycle and Focus: claiming a task does not start it, and does not require it to be Focused. */
+	claimLease(id: string, owner: string, ttlMs?: number, note?: string): TaskLease {
+		this.require(id);
+		return this.leases.claim(id, owner, ttlMs, note);
+	}
+
+	heartbeatLease(id: string, owner: string, token: string, ttlMs?: number): TaskLease {
+		this.require(id);
+		return this.leases.heartbeat(id, owner, token, ttlMs);
+	}
+
+	/** Idempotent for an already-absent or already-expired lease, matching undepend/uncontain's precedent -- never throws merely because there was nothing left to release. */
+	releaseLease(id: string, owner: string, token: string): { released: boolean } {
+		this.require(id);
+		return this.leases.release(id, owner, token);
+	}
+
+	getLease(id: string): TaskLease | undefined {
+		this.require(id);
+		return this.leases.get(id);
+	}
+
+	reapStaleLeases(now: () => string = () => new Date().toISOString()): number {
+		return this.leases.reapExpired(now());
+	}
+
 	transition(id: string, action: TaskTransition, context: TaskEventContext = {}): Artifact {
 		return this.events.atomic(() => {
 			const task = this.require(id);
@@ -459,6 +488,11 @@ export class Tasks {
 		return this.events.history(id, query);
 	}
 
+	/** Bounded, sequenced, cross-task replay feed -- see TaskEventFeedQuery. Not scoped to any one task, unlike history(). */
+	eventFeed(query: TaskEventFeedQuery = {}): TaskEventFeedPage {
+		return this.events.feed(query);
+	}
+
 	setChecklist(id: string, checklist: Checklist): Artifact {
 		const task = this.require(id);
 		return this.artifacts.setExtra(id, { ...task.extra, checklist: validateChecklist(checklist) })!;
@@ -498,10 +532,16 @@ export class Tasks {
 	/** Idempotent: undepending an already-absent dependency is a no-op. Never starts, completes, or focuses work — only removes the edge. */
 	undepend(id: string, dependencyId: string, context: TaskEventContext = {}): Artifact {
 		return this.events.atomic(() => {
-			this.require(id);
-			this.require(dependencyId);
+			const task = this.require(id);
+			const dependency = this.require(dependencyId);
 			const removed = this.artifacts.unlink({ from: id, relation: "depends_on", to: dependencyId }, context);
 			if (removed) this.appendEvent({ taskId: id, type: "dependency_removed", reason: context.reason }, context);
+			// Only meaningful if the removed edge was itself unmet -- removing an already-satisfied
+			// dependency, or removing one from a task that was already unblocked, changes nothing.
+			if (removed && task.status === "todo" && dependency.status !== "done") {
+				const stillBlocking = this.dependencyIds(id).filter((remainingId) => this.require(remainingId).status !== "done");
+				if (stillBlocking.length === 0) this.appendEvent({ taskId: id, type: "became_ready" }, context);
+			}
 			return this.show(id);
 		});
 	}
@@ -676,6 +716,9 @@ export class Tasks {
 				blocked.push({ artifact: successor, dependencyIds });
 				continue;
 			}
+			// Every successor whose last unmet dependency was this completion, not only the one
+			// auto-focused below -- readiness is a real state change for all of them.
+			this.appendEvent({ taskId: successor.id, type: "became_ready" }, context);
 			if (options.focusSuccessor !== false && !focused) {
 				this.focusStore.set(successor.id, context.sessionId);
 				focused = successor;