@danypops/papyrus 0.53.1 → 0.54.2

package/package.json

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

package/src/constants.ts

@@ -1,3 +1,10 @@
+/** This package's own Vehicle manifest identity name -- the exact string createPapyrusVehicleRegistry
+ * constructs its VehicleRegistry with (handlers/registry.ts). Exported so a consumer that needs to
+ * name "the Vehicle behind Papyrus" (e.g. pi-papyrus's own persistent widget headers, via
+ * @danypops/vehicle-client-pi's vehicleWidgetTitle) has one real source instead of a second
+ * hand-typed "papyrus" literal that could silently drift from the registry's own. */
+export const PAPYRUS_VEHICLE_NAME = "papyrus";
+
 /** Long-running daemon transport and state. */
 export const DAEMON_HOST = "127.0.0.1";
 export const DAEMON_PORT_FILE = "port";

package/src/daemon/daemon.ts

@@ -42,6 +42,10 @@ const TASK_READ_ONLY_OPERATIONS = new Set([
 	"tasks.show",
 ]);
 
+/** Matches @danypops/vehicle-server's own STREAMING_IDLE_TIMEOUT_S (daemon.ts) -- see this file's
+ * own fetch handler for why Papyrus needs the identical fix applied directly, not inherited. */
+const VEHICLE_INVOKE_IDLE_TIMEOUT_S = 3_600;
+
 /** Start the supervised, long-running Papyrus service. */
 export async function serveMain(): Promise<void> {
 	const stateDir = daemonStateDir();
@@ -81,7 +85,19 @@ export async function serveMain(): Promise<void> {
 		hostname: DAEMON_HOST,
 		port: 0,
 		fetch: (request, bunServer) => {
-			if (new URL(request.url).pathname === "/push") return pushChannel.upgrade(request, bunServer) ?? undefined;
+			const pathname = new URL(request.url).pathname;
+			if (pathname === "/push") return pushChannel.upgrade(request, bunServer) ?? undefined;
+			// Bun.serve's own idleTimeout defaults to 10s and applies per-connection regardless of
+			// how long a given request is expected to take -- @danypops/vehicle-server's own daemon.ts
+			// (startBunListener) already fixed this for every Vehicle-backed daemon that goes through
+			// its shared startDaemon() substrate; Papyrus's own daemon.ts predates that substrate and
+			// has this separate, hand-rolled Bun.serve() call, so it needs the identical fix applied
+			// directly here. Real live incident (papyrus task d0eb81b7): tasks.run_gates/tasks.complete
+			// can legitimately take tens of seconds to actually run a caller's own gate command,
+			// sending zero response bytes the whole time -- just as exposed to Bun's 10s default as
+			// the streaming case, and neither gate.timeoutMs nor VehicleLimits.maxTimeoutMs ever gets a
+			// chance to apply if the raw TCP connection is already dead first.
+			if (pathname === "/vehicle/invoke") bunServer.timeout(request, VEHICLE_INVOKE_IDLE_TIMEOUT_S);
 			return app.fetch(request);
 		},
 		// A no-op fallback when pushChannel never calls server.upgrade() is safe: Bun only

package/src/domain/task-event.ts

@@ -141,6 +141,24 @@ export function normalizeTaskHistoryQuery(
 	return { limit, direction: query.direction ?? "desc", ...(query.cursor === undefined ? {} : { cursor: query.cursor }) };
 }
 
+/**
+ * Validates just the caller-supplied context fields (sessionId/reason) that are already fully
+ * known BEFORE a mutation method does anything else -- unlike actor/source (always filled with
+ * defaults by appendEvent, never caller-controlled in practice) or evidence (often not known
+ * until real work, e.g. gate results, has already happened). Exported specifically so a mutation
+ * method can call it BEFORE reserving an idempotency receipt (see TaskMutationCoordinator.prepare's
+ * own `validate` hook) rather than only discovering an invalid reason deep inside events.atomic(),
+ * after a receipt was already durably written as pending -- a real incident (task a54f0649): a
+ * validation failure that fires only after the reserve leaves that receipt permanently stuck,
+ * since nothing else in the call ever reaches the code path that marks it complete.
+ */
+export function validateEventContext(context: Pick<TaskEventContext, "sessionId" | "reason">): void {
+	if (context.sessionId !== undefined && context.sessionId.length > TASK_EVENT_ACTOR_MAX_LENGTH)
+		throw new Error(`sessionId cannot exceed ${TASK_EVENT_ACTOR_MAX_LENGTH} characters`);
+	if (context.reason !== undefined && context.reason.length > TASK_EVENT_REASON_MAX_LENGTH)
+		throw new Error(`reason cannot exceed ${TASK_EVENT_REASON_MAX_LENGTH} characters`);
+}
+
 export function validateTaskEvent(event: AppendTaskEvent): AppendTaskEvent {
 	for (const [field, value] of [
 		["actor", event.actor],
@@ -149,10 +167,7 @@ export function validateTaskEvent(event: AppendTaskEvent): AppendTaskEvent {
 		if (!value || value.length > TASK_EVENT_ACTOR_MAX_LENGTH)
 			throw new Error(`${field} must be between 1 and ${TASK_EVENT_ACTOR_MAX_LENGTH} characters`);
 	}
-	if (event.sessionId !== undefined && event.sessionId.length > TASK_EVENT_ACTOR_MAX_LENGTH)
-		throw new Error(`sessionId cannot exceed ${TASK_EVENT_ACTOR_MAX_LENGTH} characters`);
-	if (event.reason !== undefined && event.reason.length > TASK_EVENT_REASON_MAX_LENGTH)
-		throw new Error(`reason cannot exceed ${TASK_EVENT_REASON_MAX_LENGTH} characters`);
+	validateEventContext(event);
 	if (event.evidence !== undefined && new TextEncoder().encode(JSON.stringify(event.evidence)).byteLength > TASK_EVENT_MAX_EVIDENCE_BYTES) {
 		throw new Error(`task event evidence cannot exceed ${TASK_EVENT_MAX_EVIDENCE_BYTES} bytes`);
 	}

package/src/handlers/registry.ts

@@ -10,6 +10,7 @@ import type { ArtifactScopeStore } from "../artifact/artifact-scope-store.ts";
 import type { ArtifactStore } from "../artifact/artifact-store.ts";
 import type { ArtifactTrashStore } from "../artifact/artifact-trash-store.ts";
 import type { AuthorityRegistry } from "../authority-registry.ts";
+import { PAPYRUS_VEHICLE_NAME } from "../constants.ts";
 import type { Discussions } from "../discussion/discussion-service.ts";
 import type { Notes } from "../note/note-service.ts";
 import type { ProjectRegistryStore } from "../ports/project-registry-store.ts";
@@ -41,7 +42,7 @@ export interface PapyrusVehicleDeps {
 
 export function createPapyrusVehicleRegistry(deps: PapyrusVehicleDeps): VehicleRegistry {
 	const registry = new VehicleRegistry({
-		name: "papyrus",
+		name: PAPYRUS_VEHICLE_NAME,
 		version: "1.0.0",
 		description: "Papyrus's graph-artifact domains, one honest operation per real action.",
 	});

package/src/ops.ts

@@ -637,18 +637,35 @@ function gateOutputTail(text: string): string {
 	return text.length > GATE_OUTPUT_LIMIT ? text.slice(-GATE_OUTPUT_LIMIT) : text;
 }
 
+/**
+ * The one place "did this process gate pass, and what should its display output say" is decided,
+ * shared by the sync (runProcessGateSync) and async (executeGateCommand's caller) process-gate
+ * runners -- previously two hand-copied inline checks that already had to be fixed twice, by
+ * hand, more than once (gate.expect seeing stderr too; GATE_OUTPUT_LIMIT's truncation direction).
+ * `matchable` must be the FULL captured output (bounded only by GATE_MAX_BUFFER_BYTES / Node's own
+ * spawnSync maxBuffer, never GATE_OUTPUT_LIMIT), so gate.expect always sees the whole run, never
+ * the truncated display copy `output` becomes.
+ */
+function evaluateProcessGateResult(gate: Gate, code: number | null, matchable: string): { passed: boolean; output: string } {
+	const exitedZero = code === 0;
+	return {
+		passed: exitedZero && (gate.expect ? matchable.includes(gate.expect) : true),
+		output: gateOutputTail(matchable) || (exitedZero ? "ok" : `command exited with code ${code}`),
+	};
+}
+
+/** The other shared branch: a literal spawn-level failure (command not found, spawnSync's own maxBuffer exceeded, etc.) -- distinct from a process that ran and exited non-zero, which evaluateProcessGateResult above handles. Identical treatment on both the sync and async paths: the raw error message, tail-truncated like any other gate output. */
+function spawnErrorGateResult(gate: Gate, error: Error): GateResult {
+	return { gate, passed: false, output: gateOutputTail(error.message) };
+}
+
 function runProcessGateSync(gate: Gate, cwd?: string): GateResult {
 	const { spawnSync } = require_("node:child_process");
 	const { command, timeout } = processGateCommand(gate);
 	const result = spawnSync(command, { shell: true, encoding: "utf-8", timeout, ...(cwd ? { cwd } : {}) });
-	if (result.error) return { gate, passed: false, output: gateOutputTail(result.error.message) };
+	if (result.error) return spawnErrorGateResult(gate, result.error);
 	const combined = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
-	const passed = result.status === 0 && (gate.expect ? combined.includes(gate.expect) : true);
-	return {
-		gate,
-		passed,
-		output: gateOutputTail(combined) || (result.status === 0 ? "ok" : `command exited with code ${result.status}`),
-	};
+	return { gate, ...evaluateProcessGateResult(gate, result.status, combined) };
 }
 
 export function runGates(db: Db, artifactId: string, options: GateRunOptions = {}): GateResult[] {
@@ -670,11 +687,7 @@ export function runGates(db: Db, artifactId: string, options: GateRunOptions = {
  *      indefinitely after Papyrus considers the gate "timed out". Spawning detached (its own
  *      process group) and killing the negated pid on our own timer reaches the whole tree.
  */
-function executeGateCommand(
-	command: string,
-	timeout: number,
-	cwd?: string,
-): Promise<{ passed: boolean; output: string; matchable: string }> {
+function executeGateCommand(gate: Gate, command: string, timeout: number, cwd?: string): Promise<GateResult> {
 	// `spawn(..., { shell: true, detached: true })` instead of the `exec()` convenience wrapper:
 	// `detached` (needed to make the shell the leader of its own process group, so the negated pid
 	// below reaches every descendant, not just the shell) is not part of Node's `exec()`/
@@ -697,22 +710,15 @@ function executeGateCommand(
 		child.stdout?.on("data", append);
 		child.stderr?.on("data", append);
 
-		const finish = (result: { passed: boolean; output: string; matchable: string }): void => {
+		const finish = (result: GateResult): void => {
 			if (settled) return;
 			settled = true;
 			clearTimeout(timer);
 			resolve(result);
 		};
 
-		child.on("error", (error) => finish({ passed: false, output: gateOutputTail(error.message), matchable: error.message }));
-		child.on("close", (code) => {
-			// `matchable` carries the full (GATE_MAX_BUFFER_BYTES-bounded) buffer so the caller's
-			// gate.expect substring check sees the whole run, regardless of GATE_OUTPUT_LIMIT --
-			// `output` (below) is only ever the display copy.
-			const full = buffered.trim();
-			const output = gateOutputTail(full);
-			finish({ passed: code === 0, output: output || (code === 0 ? "ok" : `command exited with code ${code}`), matchable: full });
-		});
+		child.on("error", (error) => finish(spawnErrorGateResult(gate, error)));
+		child.on("close", (code) => finish({ gate, ...evaluateProcessGateResult(gate, code, buffered.trim()) }));
 
 		const timer = setTimeout(() => {
 			if (settled) return;
@@ -723,7 +729,7 @@ function executeGateCommand(
 					child.kill("SIGKILL");
 				}
 			}
-			finish({ passed: false, output: `gate command timed out after ${timeout}ms`, matchable: "" });
+			finish({ gate, passed: false, output: `gate command timed out after ${timeout}ms` });
 		}, timeout);
 	});
 }
@@ -761,12 +767,7 @@ export async function runGatesAsync(db: Db, artifactId: string, options: GateRun
 		if (gate.type === "command" || gate.type === "test") {
 			const { command, timeout: configuredTimeout } = processGateCommand(gate);
 			const timeout = remainingMs === undefined ? configuredTimeout : Math.max(1, Math.min(configuredTimeout, remainingMs));
-			const executed = await executeGateCommand(command, timeout, options.cwd);
-			results.push({
-				gate,
-				passed: executed.passed && (gate.expect ? executed.matchable.includes(gate.expect) : true),
-				output: executed.output,
-			});
+			results.push(await executeGateCommand(gate, command, timeout, options.cwd));
 		} else {
 			results.push(runNonProcessGate(gate));
 		}

package/src/task/task-lease-coordinator.ts

@@ -0,0 +1,52 @@
+import type { Artifact } from "../artifact/artifact.ts";
+import type { TaskLease, TaskLeaseView } from "../domain/task-lease.ts";
+import type { TaskLeaseStore } from "../stores/task-lease-store.ts";
+
+/**
+ * Task lease management (claim/heartbeat/release/get/reap), split out of the Tasks god class as
+ * part of a SOLID-audit-driven decomposition (see task b51419a0). A lease is orthogonal to
+ * lifecycle and Focus -- claiming a task does not start it, and does not require it to be
+ * Focused -- so its own concern (a single active worker per task, TTL-based) has nothing to do
+ * with status transitions, idempotency receipts, or checklist review, the other concerns that
+ * were previously interleaved with it in one class.
+ */
+export class TaskLeaseCoordinator {
+	constructor(
+		private readonly leases: TaskLeaseStore,
+		/** Delegates to Tasks.require() so lease methods get the identical not-found/wrong-kind checks every other Tasks method already enforces, without duplicating that logic here. */
+		private readonly requireTask: (id: string) => Artifact,
+	) {}
+
+	private present(lease: TaskLease): TaskLeaseView {
+		const task = this.requireTask(lease.taskId);
+		const { taskId: _taskId, ...details } = lease;
+		return { taskName: task.alias, taskTitle: task.title, ...details };
+	}
+
+	/** A lease is orthogonal to lifecycle and Focus: claiming a task does not start it, and does not require it to be Focused. */
+	claim(id: string, owner: string, ttlMs?: number, note?: string): TaskLeaseView {
+		this.requireTask(id);
+		return this.present(this.leases.claim(id, owner, ttlMs, note));
+	}
+
+	heartbeat(id: string, owner: string, token: string, ttlMs?: number): TaskLeaseView {
+		this.requireTask(id);
+		return this.present(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. */
+	release(id: string, owner: string, token: string): { released: boolean } {
+		this.requireTask(id);
+		return this.leases.release(id, owner, token);
+	}
+
+	get(id: string): TaskLeaseView | undefined {
+		this.requireTask(id);
+		const lease = this.leases.get(id);
+		return lease ? this.present(lease) : undefined;
+	}
+
+	reapStale(now: () => string = () => new Date().toISOString()): number {
+		return this.leases.reapExpired(now());
+	}
+}

package/src/task/task-mutation-coordinator.ts

@@ -0,0 +1,160 @@
+import { createHash } from "node:crypto";
+import type { ArtifactStore } from "../artifact/artifact-store.ts";
+import { TASK_MUTATION_IDEMPOTENCY_KEY_MAX_LENGTH, TASK_MUTATION_IDEMPOTENCY_RETENTION_MS } from "../constants.ts";
+import {
+	TaskMutationIdempotencyConflictError,
+	TaskMutationPendingError,
+	type TaskMutationRequestRecord,
+	type TaskMutationRequestStore,
+} from "../stores/task-mutation-request-store.ts";
+
+export class TaskMutationReceiptNotFoundError extends Error {}
+
+export interface TaskMutationRequestContext {
+	key?: string;
+	caller?: string;
+}
+
+export interface TaskMutationReceiptView {
+	receiptId: string;
+	operation: string;
+	state: "pending" | "completed";
+	taskName?: string;
+	taskTitle?: string;
+	taskStatus?: string;
+	result?: unknown;
+	createdAt: string;
+	updatedAt: string;
+	expiresAt: string;
+}
+
+function canonicalJson(value: unknown): string {
+	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+	if (typeof value === "object" && value !== null) {
+		return `{${Object.entries(value)
+			.filter(([, entry]) => entry !== undefined)
+			.sort(([left], [right]) => left.localeCompare(right))
+			.map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`)
+			.join(",")}}`;
+	}
+	return JSON.stringify(value) ?? "null";
+}
+
+/**
+ * Idempotency-key-backed mutation receipt plumbing, split out of the Tasks god class as part of
+ * a SOLID-audit-driven decomposition (see task b51419a0). Owns reserving a "pending" receipt
+ * before a real mutation runs, replaying an already-completed one, rejecting a genuinely
+ * different payload reused under the same key, and rejecting a NEW attempt against a
+ * task+operation that already has one in flight.
+ *
+ * `validate`, when supplied to prepare(), runs before anything else -- including before the
+ * existing/replay lookup -- specifically so a caller-supplied validation failure (e.g. an
+ * over-length `reason`) can never leave a receipt reserved with no way to ever mark it complete.
+ * This is the direct fix for a real incident (task a54f0649, discovered live completing task
+ * d0eb81b7): validation previously ran deep inside the CALLER's own atomic block (appendEvent's
+ * own validateTaskEvent), strictly AFTER prepare()'s reserving call had already durably written
+ * the receipt as pending. Once that validation threw, nothing downstream ever reached the code
+ * path that marks a receipt complete, permanently stranding it -- and since the pending-mutation
+ * lock is keyed on (taskId, operation) rather than the idempotency key, that stuck receipt then
+ * blocked every subsequent attempt on the same task+operation, under ANY key, until the record's
+ * 7-day retention window expired. No self-service recovery existed; the live incident required a
+ * direct database row deletion. Every caller that can determine its own event-context validity up
+ * front (reason/sessionId length, at minimum) should now pass a `validate` callback here instead
+ * of only validating once real mutation work is already underway.
+ */
+export class TaskMutationCoordinator {
+	constructor(
+		private readonly mutationRequests: TaskMutationRequestStore,
+		private readonly artifacts: ArtifactStore,
+	) {}
+
+	prepare<Result>(
+		operation: string,
+		taskId: string | undefined,
+		payload: unknown,
+		request: TaskMutationRequestContext,
+		reserve = true,
+		validate?: () => void,
+	): { record?: TaskMutationRequestRecord; replay?: Result; pending?: boolean } {
+		validate?.();
+		const key = request.key?.trim();
+		if (request.key !== undefined && (!key || key.length > TASK_MUTATION_IDEMPOTENCY_KEY_MAX_LENGTH)) {
+			throw new Error(`idempotency key must be between 1 and ${TASK_MUTATION_IDEMPOTENCY_KEY_MAX_LENGTH} characters`);
+		}
+		if (!key) return {};
+		const now = new Date().toISOString();
+		const scope = request.caller?.trim() || "anonymous";
+		const requestHash = createHash("sha256").update(canonicalJson({ operation, taskId, payload })).digest("hex");
+		this.mutationRequests.prune(now);
+		const existing = this.mutationRequests.get(scope, key, now);
+		if (existing) {
+			if (existing.requestHash !== requestHash) {
+				throw new TaskMutationIdempotencyConflictError(`idempotency key "${key}" was already used with a different mutation payload`);
+			}
+			if (existing.state === "completed" && existing.responseJson !== undefined) {
+				const replay = JSON.parse(existing.responseJson) as Result;
+				return {
+					record: existing,
+					replay:
+						typeof replay === "object" && replay !== null && "changed" in replay
+							? ({ ...replay, changed: false, replayed: true } as Result)
+							: replay,
+				};
+			}
+			return { record: existing, pending: true };
+		}
+		if (!reserve) return {};
+		const record: TaskMutationRequestRecord = {
+			scope,
+			key,
+			receiptId: crypto.randomUUID(),
+			...(taskId === undefined ? {} : { taskId }),
+			operation,
+			requestHash,
+			state: "pending",
+			createdAt: now,
+			updatedAt: now,
+			expiresAt: new Date(Date.parse(now) + TASK_MUTATION_IDEMPOTENCY_RETENTION_MS).toISOString(),
+		};
+		this.mutationRequests.put(record);
+		return { record };
+	}
+
+	rejectDifferentPending(taskId: string, operation: string, inspectionPending: boolean): void {
+		if (inspectionPending) return;
+		const pending = this.mutationRequests.findPending(taskId, operation, new Date().toISOString());
+		if (!pending) return;
+		throw new TaskMutationPendingError(
+			`an earlier ${operation} outcome is still pending; inspect tasks.mutation_status with its original idempotency_key before retrying`,
+			pending.receiptId,
+			pending.operation,
+		);
+	}
+
+	complete<Result>(record: TaskMutationRequestRecord | undefined, result: Result): Result {
+		if (!record) return result;
+		this.mutationRequests.complete(record.scope, record.key, JSON.stringify(result), new Date().toISOString());
+		return result;
+	}
+
+	status(keyInput: string, caller?: string): TaskMutationReceiptView {
+		const key = keyInput.trim();
+		if (!key || key.length > TASK_MUTATION_IDEMPOTENCY_KEY_MAX_LENGTH) {
+			throw new Error(`idempotency key must be between 1 and ${TASK_MUTATION_IDEMPOTENCY_KEY_MAX_LENGTH} characters`);
+		}
+		const now = new Date().toISOString();
+		const record = this.mutationRequests.get(caller?.trim() || "anonymous", key, now);
+		if (!record) throw new TaskMutationReceiptNotFoundError("no retained task mutation receipt exists for this idempotency key");
+		const task = record.taskId ? this.artifacts.get(record.taskId) : null;
+		return {
+			receiptId: record.receiptId,
+			operation: record.operation,
+			state: record.state,
+			...(task?.kind === "task" ? { taskName: task.alias, taskTitle: task.title, taskStatus: task.status } : {}),
+			...(record.responseJson === undefined ? {} : { result: JSON.parse(record.responseJson) as unknown }),
+			createdAt: record.createdAt,
+			updatedAt: record.updatedAt,
+			expiresAt: record.expiresAt,
+		};
+	}
+}

package/src/task/task-service.ts

@@ -12,8 +12,6 @@ import {
 	TASK_FOCUS_STALE_AFTER_MS,
 	TASK_LABEL_MAX_COUNT,
 	TASK_LABEL_MAX_LENGTH,
-	TASK_MUTATION_IDEMPOTENCY_KEY_MAX_LENGTH,
-	TASK_MUTATION_IDEMPOTENCY_RETENTION_MS,
 	TASK_PROJECT_LIST_MAX_RESULTS,
 	TASK_SCOPE_MAX_TASKS,
 	TASK_TITLE_MAX_LENGTH,
@@ -31,7 +29,8 @@ import type {
 	TaskHistoryQuery,
 	TaskLifecycleStatus,
 } from "../domain/task-event.ts";
-import type { TaskLease, TaskLeaseView } from "../domain/task-lease.ts";
+import { validateEventContext } from "../domain/task-event.ts";
+import type { TaskLeaseView } from "../domain/task-lease.ts";
 import {
 	normalizeProjectRoot,
 	type RegisterTaskProjectInput,
@@ -53,13 +52,21 @@ import { InMemoryTaskFocusStore, type TaskFocusStatus, type TaskFocusStore } fro
 import { InMemoryTaskLeaseStore, type TaskLeaseStore } from "../stores/task-lease-store.ts";
 import {
 	InMemoryTaskMutationRequestStore,
-	TaskMutationIdempotencyConflictError,
 	TaskMutationPendingError,
 	type TaskMutationRequestRecord,
 	type TaskMutationRequestStore,
 } from "../stores/task-mutation-request-store.ts";
 import { InMemoryTaskScopeStore, type TaskScopeStore } from "../stores/task-scope-store.ts";
 import { assertDependencyEdgeAllowed, TaskExecutionBoundExceededError } from "./task-execution.ts";
+import { TaskLeaseCoordinator } from "./task-lease-coordinator.ts";
+import {
+	TaskMutationCoordinator,
+	TaskMutationReceiptNotFoundError,
+	type TaskMutationReceiptView,
+	type TaskMutationRequestContext,
+} from "./task-mutation-coordinator.ts";
+
+export { TaskMutationReceiptNotFoundError, type TaskMutationReceiptView, type TaskMutationRequestContext };
 
 export interface UpdateTaskInput {
 	title?: string;
@@ -85,7 +92,6 @@ export type TaskStatus = TaskLifecycleStatus;
 
 export class TaskProjectNotFoundError extends Error {}
 export class TaskProjectAmbiguousError extends Error {}
-export class TaskMutationReceiptNotFoundError extends Error {}
 
 export class TaskInvalidTransitionError extends Error {
 	constructor(
@@ -99,11 +105,6 @@ export class TaskInvalidTransitionError extends Error {
 	}
 }
 
-export interface TaskMutationRequestContext {
-	key?: string;
-	caller?: string;
-}
-
 export interface TaskMutationMetadata {
 	changed: boolean;
 	operation: string;
@@ -115,19 +116,6 @@ export interface TaskMutationMetadata {
 
 export type TaskLifecycleMutationResult = Artifact & TaskMutationMetadata;
 
-export interface TaskMutationReceiptView {
-	receiptId: string;
-	operation: string;
-	state: "pending" | "completed";
-	taskName?: string;
-	taskTitle?: string;
-	taskStatus?: string;
-	result?: unknown;
-	createdAt: string;
-	updatedAt: string;
-	expiresAt: string;
-}
-
 export interface CreateTaskRequestContext {
 	key?: string;
 	caller?: string;
@@ -243,9 +231,14 @@ export class Tasks {
 		private readonly leases: TaskLeaseStore = new InMemoryTaskLeaseStore(),
 		private readonly createRequests: TaskCreateRequestStore = new InMemoryTaskCreateRequestStore(),
 		private readonly mutationRequests: TaskMutationRequestStore = new InMemoryTaskMutationRequestStore(),
-	) {}
+	) {
+		this.leaseCoordinator = new TaskLeaseCoordinator(this.leases, (id) => this.require(id));
+		this.mutationCoordinator = new TaskMutationCoordinator(this.mutationRequests, this.artifacts);
+	}
 
 	private readonly completionFlights = new Map<string, Promise<TaskCompletion>>();
+	private readonly leaseCoordinator: TaskLeaseCoordinator;
+	private readonly mutationCoordinator: TaskMutationCoordinator;
 
 	private require(id: string): Artifact {
 		const artifact = this.artifacts.get(id);
@@ -603,7 +596,9 @@ export class Tasks {
 				"Focus a non-terminal task before pausing; do not blindly retry pause.",
 			);
 		}
-		const prepared = inspection.pending ? inspection : this.prepareMutation<TaskFocusMutationResult>("pause", undefined, context, request);
+		const prepared = inspection.pending
+			? inspection
+			: this.prepareMutation<TaskFocusMutationResult>("pause", undefined, context, request, true, () => validateEventContext(context));
 		if (focus.status === "paused") {
 			return this.completeMutation(prepared.record, {
 				...focus,
@@ -646,7 +641,7 @@ export class Tasks {
 		}
 		const prepared = inspection.pending
 			? inspection
-			: this.prepareMutation<TaskFocusMutationResult>("unpause", undefined, context, request);
+			: this.prepareMutation<TaskFocusMutationResult>("unpause", undefined, context, request, true, () => validateEventContext(context));
 		if (focus.status === "active") {
 			return this.completeMutation(prepared.record, {
 				...focus,
@@ -695,37 +690,26 @@ export class Tasks {
 		return this.focusStore.reapStale(cutoff);
 	}
 
-	private presentLease(lease: TaskLease): TaskLeaseView {
-		const task = this.require(lease.taskId);
-		const { taskId: _taskId, ...details } = lease;
-		return { taskName: task.alias, taskTitle: task.title, ...details };
-	}
-
 	/** 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): TaskLeaseView {
-		this.require(id);
-		return this.presentLease(this.leases.claim(id, owner, ttlMs, note));
+		return this.leaseCoordinator.claim(id, owner, ttlMs, note);
 	}
 
 	heartbeatLease(id: string, owner: string, token: string, ttlMs?: number): TaskLeaseView {
-		this.require(id);
-		return this.presentLease(this.leases.heartbeat(id, owner, token, ttlMs));
+		return this.leaseCoordinator.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);
+		return this.leaseCoordinator.release(id, owner, token);
 	}
 
 	getLease(id: string): TaskLeaseView | undefined {
-		this.require(id);
-		const lease = this.leases.get(id);
-		return lease ? this.presentLease(lease) : undefined;
+		return this.leaseCoordinator.get(id);
 	}
 
 	reapStaleLeases(now: () => string = () => new Date().toISOString()): number {
-		return this.leases.reapExpired(now());
+		return this.leaseCoordinator.reapStale(now);
 	}
 
 	private allowedLifecycleActions(status: string): string[] {
@@ -742,86 +726,21 @@ export class Tasks {
 		payload: unknown,
 		request: TaskMutationRequestContext,
 		reserve = true,
+		validate?: () => void,
 	): { record?: TaskMutationRequestRecord; replay?: Result; pending?: boolean } {
-		const key = request.key?.trim();
-		if (request.key !== undefined && (!key || key.length > TASK_MUTATION_IDEMPOTENCY_KEY_MAX_LENGTH)) {
-			throw new Error(`idempotency key must be between 1 and ${TASK_MUTATION_IDEMPOTENCY_KEY_MAX_LENGTH} characters`);
-		}
-		if (!key) return {};
-		const now = new Date().toISOString();
-		const scope = request.caller?.trim() || "anonymous";
-		const requestHash = createHash("sha256").update(canonicalJson({ operation, taskId, payload })).digest("hex");
-		this.mutationRequests.prune(now);
-		const existing = this.mutationRequests.get(scope, key, now);
-		if (existing) {
-			if (existing.requestHash !== requestHash) {
-				throw new TaskMutationIdempotencyConflictError(`idempotency key "${key}" was already used with a different mutation payload`);
-			}
-			if (existing.state === "completed" && existing.responseJson !== undefined) {
-				const replay = JSON.parse(existing.responseJson) as Result;
-				return {
-					record: existing,
-					replay:
-						typeof replay === "object" && replay !== null && "changed" in replay
-							? ({ ...replay, changed: false, replayed: true } as Result)
-							: replay,
-				};
-			}
-			return { record: existing, pending: true };
-		}
-		if (!reserve) return {};
-		const record: TaskMutationRequestRecord = {
-			scope,
-			key,
-			receiptId: crypto.randomUUID(),
-			...(taskId === undefined ? {} : { taskId }),
-			operation,
-			requestHash,
-			state: "pending",
-			createdAt: now,
-			updatedAt: now,
-			expiresAt: new Date(Date.parse(now) + TASK_MUTATION_IDEMPOTENCY_RETENTION_MS).toISOString(),
-		};
-		this.mutationRequests.put(record);
-		return { record };
+		return this.mutationCoordinator.prepare<Result>(operation, taskId, payload, request, reserve, validate);
 	}
 
 	private rejectDifferentPendingMutation(taskId: string, operation: string, inspectionPending: boolean): void {
-		if (inspectionPending) return;
-		const pending = this.mutationRequests.findPending(taskId, operation, new Date().toISOString());
-		if (!pending) return;
-		throw new TaskMutationPendingError(
-			`an earlier ${operation} outcome is still pending; inspect tasks.mutation_status with its original idempotency_key before retrying`,
-			pending.receiptId,
-			pending.operation,
-		);
+		this.mutationCoordinator.rejectDifferentPending(taskId, operation, inspectionPending);
 	}
 
 	private completeMutation<Result>(record: TaskMutationRequestRecord | undefined, result: Result): Result {
-		if (!record) return result;
-		this.mutationRequests.complete(record.scope, record.key, JSON.stringify(result), new Date().toISOString());
-		return result;
+		return this.mutationCoordinator.complete(record, result);
 	}
 
 	mutationStatus(keyInput: string, caller?: string): TaskMutationReceiptView {
-		const key = keyInput.trim();
-		if (!key || key.length > TASK_MUTATION_IDEMPOTENCY_KEY_MAX_LENGTH) {
-			throw new Error(`idempotency key must be between 1 and ${TASK_MUTATION_IDEMPOTENCY_KEY_MAX_LENGTH} characters`);
-		}
-		const now = new Date().toISOString();
-		const record = this.mutationRequests.get(caller?.trim() || "anonymous", key, now);
-		if (!record) throw new TaskMutationReceiptNotFoundError("no retained task mutation receipt exists for this idempotency key");
-		const task = record.taskId ? this.artifacts.get(record.taskId) : null;
-		return {
-			receiptId: record.receiptId,
-			operation: record.operation,
-			state: record.state,
-			...(task?.kind === "task" ? { taskName: task.alias, taskTitle: task.title, taskStatus: task.status } : {}),
-			...(record.responseJson === undefined ? {} : { result: JSON.parse(record.responseJson) as unknown }),
-			createdAt: record.createdAt,
-			updatedAt: record.updatedAt,
-			expiresAt: record.expiresAt,
-		};
+		return this.mutationCoordinator.status(keyInput, caller);
 	}
 
 	transition(
@@ -854,7 +773,9 @@ export class Tasks {
 				);
 			}
 		}
-		const prepared = inspection.pending ? inspection : this.prepareMutation<TaskLifecycleMutationResult>(action, id, context, request);
+		const prepared = inspection.pending
+			? inspection
+			: this.prepareMutation<TaskLifecycleMutationResult>(action, id, context, request, true, () => validateEventContext(context));
 		if (task.status === intendedStatus) {
 			return this.completeMutation(prepared.record, {
 				...this.show(id),
@@ -946,7 +867,9 @@ export class Tasks {
 		}
 		if (task.status !== "review" && task.status !== "done") this.throwInvalidCompletion(task.status);
 		if (task.status === "review") this.requireNotBlocked(task);
-		const prepared = this.prepareMutation<TaskCompletion>("complete", id, { context, options }, request);
+		const prepared = this.prepareMutation<TaskCompletion>("complete", id, { context, options }, request, true, () =>
+			validateEventContext(context),
+		);
 		if (task.status === "done") return this.completeMutation(prepared.record, this.completedNoop(id, context, prepared.record));
 		const attemptId = prepared.record?.receiptId ?? crypto.randomUUID();
 		this.events.atomic(() =>
@@ -983,7 +906,9 @@ export class Tasks {
 			}
 			if (task.status !== "review" && task.status !== "done") this.throwInvalidCompletion(task.status);
 			if (task.status === "review") this.requireNotBlocked(task);
-			const prepared = this.prepareMutation<TaskCompletion>("complete", id, { context, options }, request);
+			const prepared = this.prepareMutation<TaskCompletion>("complete", id, { context, options }, request, true, () =>
+				validateEventContext(context),
+			);
 			if (task.status === "done") return this.completeMutation(prepared.record, this.completedNoop(id, context, prepared.record));
 			const attemptId = prepared.record?.receiptId ?? crypto.randomUUID();
 			this.events.atomic(() =>