@danypops/papyrus 0.54.2 → 0.54.4

package/src/ops.ts

@@ -2,7 +2,6 @@
  * ops.ts — typed operations over the Papyrus DB.
  * Enforces the schema protocol (kinds, statuses, relations) via FK + app validation.
  */
-import { createRequire } from "node:module";
 import type { Artifact, ArtifactQuery, CreateArtifactInput, UpdateArtifactInput } from "./artifact/artifact.ts";
 import { generateUniqueAlias, isValidAlias, slugify } from "./artifact/artifact-alias.ts";
 import type { ArtifactTrashRecord } from "./artifact/artifact-trash.ts";
@@ -22,25 +21,11 @@ import {
 	normalizeArtifactEventQuery,
 	resolveArtifactEvent,
 } from "./artifact/artifact-event.ts";
-import type { Gate, GateResult, GateRunOptions } from "./domain/gate.ts";
 
 export type { Artifact } from "./artifact/artifact.ts";
-export type { Gate, GateResult } from "./domain/gate.ts";
 export type CreateInput = CreateArtifactInput;
 
-import {
-	DEFAULT_GRAPH_DEPTH,
-	DEFAULT_GRAPH_MAX_NODES,
-	GATE_COMMAND_TIMEOUT_MS,
-	GATE_FILE_MAX_BYTES,
-	GATE_MAX_BUFFER_BYTES,
-	GATE_OUTPUT_LIMIT,
-	GATE_TEST_TIMEOUT_MS,
-	MAX_GRAPH_DEPTH,
-	MAX_GRAPH_NODES,
-} from "./constants.ts";
-
-const require_ = createRequire(import.meta.url);
+import { DEFAULT_GRAPH_DEPTH, DEFAULT_GRAPH_MAX_NODES, MAX_GRAPH_DEPTH, MAX_GRAPH_NODES } from "./constants.ts";
 
 interface ResolvedCreateInput extends CreateInput {
 	kind: string;
@@ -592,185 +577,3 @@ export function injectableRules(db: Db): Array<{ id: string; title: string; body
 		return { id: art.id, title: art.title, body: art.body, extra: art.extra };
 	});
 }
-
-function readBoundedGateFile(path: string): string {
-	const { readFileSync, statSync } = require_("node:fs");
-	if (statSync(path).size > GATE_FILE_MAX_BYTES) throw new Error(`file exceeds ${GATE_FILE_MAX_BYTES} bytes`);
-	return readFileSync(path, "utf-8") as string;
-}
-
-/**
- * Shared by the sync and async process-gate runners so "test" is never a second, independently
- * maintained copy of "command"'s own command-template selection.
- *
- * "test" runs `gate.target` verbatim, exactly like "command" -- the only real difference is a
- * more generous default timeout (GATE_TEST_TIMEOUT_MS vs GATE_COMMAND_TIMEOUT_MS), since a test
- * suite routinely runs longer than an arbitrary command. It previously wrapped target in
- * `npx vitest run ${target} --reporter=dot`, silently wrong for every real consumer in this
- * ecosystem (all Bun-native, none use vitest): a target that was itself a full command (e.g.
- * `bun test path/to.test.ts`, exactly what every existing gate/checklist example here has always
- * shown) got parsed by vitest as three separate positional args, triggering vitest's own broad
- * discovery across the whole repo instead of running the intended command at all -- a real
- * incident (task ab1463e2) that produced an unrelated multi-suite vitest failure cascade instead
- * of the actual target ever running.
- */
-function processGateCommand(gate: Gate): { command: string; timeout: number } {
-	if (gate.type === "test") return { command: gate.target, timeout: gate.timeoutMs ?? GATE_TEST_TIMEOUT_MS };
-	return { command: gate.target, timeout: gate.timeoutMs ?? GATE_COMMAND_TIMEOUT_MS };
-}
-
-/**
- * spawnSync + manual stdout/stderr concatenation, not execSync: execSync's return value is stdout
- * only. Many real commands (bun test's own per-test lines and its pass/fail summary among them)
- * write their actual output to stderr, so an execSync-based match against gate.expect saw only the
- * first line of a banner and never the result -- every such gate failed regardless of whether the
- * command actually passed. This one function now serves both "command" and "test" gates;
- * previously "test" was a second, separately-maintained execSync path that never checked
- * gate.expect at all.
- */
-/**
- * Keeps the LAST GATE_OUTPUT_LIMIT characters, not the first -- a real command's own meaningful
- * pass/fail summary is its last lines, not its first (setup/banner noise). See GATE_OUTPUT_LIMIT's
- * own doc comment (constants.ts) for the real incident this fixes.
- */
-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 spawnErrorGateResult(gate, result.error);
-	const combined = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
-	return { gate, ...evaluateProcessGateResult(gate, result.status, combined) };
-}
-
-export function runGates(db: Db, artifactId: string, options: GateRunOptions = {}): GateResult[] {
-	const art = getArtifact(db, artifactId);
-	if (!art) throw new Error("artifact not found");
-	const gates = (art.extra.gates as Gate[]) ?? [];
-	const cwd = options.cwd;
-	return gates.map((gate) => (gate.type === "command" || gate.type === "test" ? runProcessGateSync(gate, cwd) : runNonProcessGate(gate)));
-}
-
-/**
- * Runs one gate command with two invariants a prior implementation lacked (a real incident; see
- * GateRunOptions.cwd's doc comment):
- *   1. `cwd` is always explicit, never inherited from the daemon's own process cwd.
- *   2. The whole process group is killed on timeout, not just the immediate shell. `exec()`'s own
- *      `timeout` option only signals the process it directly spawned (the shell running
- *      `command`); a shell's own child (e.g. `bun` under `sh -c "bun test"`) is not in general
- *      killed by that signal and can be reparented and keep running -- and consuming memory --
- *      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(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()`/
-	// `ExecOptions` type at all -- `spawn`'s options support it directly and correctly.
-	const { spawn } = require_("node:child_process") as typeof import("node:child_process");
-	return new Promise((resolve) => {
-		let settled = false;
-		let buffered = "";
-		let truncated = false;
-		const child = spawn(command, { shell: true, detached: true, ...(cwd ? { cwd } : {}) });
-
-		const append = (chunk: Buffer): void => {
-			if (truncated) return;
-			buffered += chunk.toString("utf8");
-			if (buffered.length > GATE_MAX_BUFFER_BYTES) {
-				buffered = buffered.slice(0, GATE_MAX_BUFFER_BYTES);
-				truncated = true;
-			}
-		};
-		child.stdout?.on("data", append);
-		child.stderr?.on("data", append);
-
-		const finish = (result: GateResult): void => {
-			if (settled) return;
-			settled = true;
-			clearTimeout(timer);
-			resolve(result);
-		};
-
-		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;
-			if (child.pid !== undefined) {
-				try {
-					process.kill(-child.pid, "SIGKILL");
-				} catch {
-					child.kill("SIGKILL");
-				}
-			}
-			finish({ gate, passed: false, output: `gate command timed out after ${timeout}ms` });
-		}, timeout);
-	});
-}
-
-function runNonProcessGate(gate: Gate): GateResult {
-	if (gate.type === "file-exists") {
-		const { existsSync } = require_("node:fs");
-		const exists = existsSync(gate.target);
-		return { gate, passed: exists, output: exists ? "exists" : "not found" };
-	}
-	if (gate.type === "contains") {
-		try {
-			const content = readBoundedGateFile(gate.target);
-			const found = gate.expect ? content.includes(gate.expect) : content.length > 0;
-			return { gate, passed: found, output: found ? "found" : `"${gate.expect ?? ""}" not found` };
-		} catch {
-			return { gate, passed: false, output: "file not readable" };
-		}
-	}
-	return { gate, passed: false, output: `unknown gate type: ${String(gate.type)}` };
-}
-
-/** Gate runner for daemon request paths; subprocess gates never block the event loop. */
-export async function runGatesAsync(db: Db, artifactId: string, options: GateRunOptions = {}): Promise<GateResult[]> {
-	const art = getArtifact(db, artifactId);
-	if (!art) throw new Error("artifact not found");
-	const gates = (art.extra.gates as Gate[]) ?? [];
-	const results: GateResult[] = [];
-	for (const gate of gates) {
-		const remainingMs = options.deadlineMs === undefined ? undefined : options.deadlineMs - Date.now();
-		if (remainingMs !== undefined && remainingMs <= 0) {
-			results.push({ gate, passed: false, output: "gate runtime deadline exceeded" });
-			continue;
-		}
-		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));
-			results.push(await executeGateCommand(gate, command, timeout, options.cwd));
-		} else {
-			results.push(runNonProcessGate(gate));
-		}
-	}
-	return results;
-}

package/src/service.ts

@@ -594,7 +594,7 @@ export function createApp(deps: {
 	 * (daemon.ts) wires this to a PushChannel; tests and other embedders can ignore it.
 	 */
 	onOperationExecuted?: (operation: string, input: OperationInput) => void;
-	/** Defaults to a no-op (createVehicleHttpApp's own default) -- daemon.ts wires vehicleLogger() so a failed invocation is actually logged, not silently discarded. */
+	/** Defaults to a no-op (createVehicleHttpApp's own default) -- daemon.ts wires log/log.ts's own `logger` so a failed invocation is actually logged, not silently discarded. */
 	logger?: Logger;
 	/**
 	 * Backs GET /daemon/diagnose -- "who am I, and what happened recently" (see

package/src/stores/sqlite-gate-runner.ts

@@ -1,6 +1,6 @@
 import type { Db } from "../db.ts";
 import type { GateResult, GateRunOptions } from "../domain/gate.ts";
-import { runGates, runGatesAsync } from "../ops.ts";
+import { runGates, runGatesAsync } from "../domain/gate-execution.ts";
 import type { GateRunner } from "./gate-runner.ts";
 
 export class SQLiteGateRunner implements GateRunner {

package/src/stores/task-mutation-request-store.ts

@@ -56,6 +56,10 @@ export class InMemoryTaskMutationRequestStore implements TaskMutationRequestStor
 	}
 
 	put(record: TaskMutationRequestRecord): void {
+		// Checked in the same order sqlite-task-mutation-request-store.ts's own catch-and-reclassify
+		// does: a still-pending (taskId, operation) always becomes the more specific
+		// TaskMutationPendingError first, regardless of which underlying constraint actually
+		// collided (SQLite's partial unique pending index, or the PRIMARY KEY check below).
 		if (record.state === "pending" && record.taskId) {
 			const existing = this.findPending(record.taskId, record.operation, record.createdAt);
 			if (existing) {
@@ -66,7 +70,18 @@ export class InMemoryTaskMutationRequestStore implements TaskMutationRequestStor
 				);
 			}
 		}
-		this.records.set(this.recordKey(record.scope, record.key), { ...record });
+		// Mirror SQLite's own PRIMARY KEY (request_scope, idempotency_key): a genuine duplicate
+		// (scope, key) is always rejected, never silently overwritten -- SQLite throws on any such
+		// collision regardless of whether the colliding row's other columns match, so this does too,
+		// rather than only checking receiptId. Every real write path already dedupes via
+		// mutationRequests.get() before ever calling put() twice for the same (scope, key)
+		// (task-service.ts's prepareMutation()), so this is unreachable through normal application
+		// flow today -- it only guards a caller that talks to the store interface directly.
+		const recordKey = this.recordKey(record.scope, record.key);
+		if (this.records.has(recordKey)) {
+			throw new Error(`task mutation request already exists for scope "${record.scope}" key "${record.key}"`);
+		}
+		this.records.set(recordKey, { ...record });
 	}
 
 	complete(scope: string, key: string, responseJson: string, updatedAt: string): void {

package/src/task/task-edges.ts

@@ -0,0 +1,106 @@
+import type { Artifact, ArtifactEdge } from "../artifact/artifact.ts";
+import type { ArtifactStore } from "../artifact/artifact-store.ts";
+import { TASK_EXECUTION_MAX_DEGREE } from "../constants.ts";
+import type { AppendTaskEvent, TaskEventContext } from "../domain/task-event.ts";
+import type { TaskEventStore } from "../stores/task-event-store.ts";
+import { assertDependencyEdgeAllowed, TaskExecutionBoundExceededError } from "./task-execution.ts";
+// Type-only import: erased entirely at compile time, so this does not create a real runtime
+// circular dependency even though task-service.ts also imports TaskEdges (a real value) from
+// this file -- only one direction of this pair carries an actual runtime import.
+import type { TaskGraph } from "./task-service.ts";
+
+/**
+ * Task dependency/containment edge mutations (depend/undepend/contain/uncontain), split out of
+ * the Tasks god class as part of a SOLID-audit-driven decomposition (see task b51419a0 and the
+ * "TaskEdges" child of "Epic: Modularize papyrus/pi-papyrus god-files into building-block
+ * modules"), mirroring the TaskLeaseCoordinator/TaskMutationCoordinator/TaskFocusCoordinator/
+ * TaskProjectScope precedent in this same directory.
+ *
+ * Unlike those simpler extractions, this one only owns the mutation side of edges -- it reads the
+ * graph/relationships it needs through injected callbacks (dependencyCheckGraph/dependencyIds/
+ * relationships) rather than duplicating that graph-construction machinery, since those reads are
+ * shared with concerns that stay on Tasks (list/graph/buildGraph, progress propagation, blockage
+ * checks in transition/complete).
+ */
+export class TaskEdges {
+	constructor(
+		private readonly artifacts: Pick<ArtifactStore, "link" | "unlink">,
+		private readonly events: TaskEventStore,
+		/** Delegates to Tasks.require() so edge 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,
+		/** Delegates to Tasks.show() -- every edge mutation returns the affected task's own current (post-mutation) view. */
+		private readonly showTask: (id: string) => Artifact,
+		/** Delegates to Tasks' own actor/source/sessionId/reason defaulting so every event this collaborator appends looks identical to one Tasks itself would have appended. */
+		private readonly appendEvent: (event: Omit<AppendTaskEvent, "actor" | "source">, context: TaskEventContext) => void,
+		/** Delegates to Tasks' own private dependencyCheckGraph() -- project-scoped cycle-check graph construction, which itself composes list()/graph()/buildGraph(), all of which stay on Tasks. */
+		private readonly dependencyCheckGraph: (id: string, dependencyId: string) => TaskGraph,
+		/** Delegates to Tasks' own private dependencyIds() -- bounded prerequisite lookup, also used outside edge mutations (transition's blockage check). */
+		private readonly dependencyIds: (id: string) => string[],
+		/** Delegates to Tasks' own private relationships() -- bounded relationship lookup, also used outside edge mutations (parentIds/progress propagation). */
+		private readonly relationships: (id: string) => ArtifactEdge[],
+	) {}
+
+	depend(id: string, dependencyId: string, context: TaskEventContext = {}): Artifact {
+		return this.events.atomic(() => {
+			this.requireTask(id);
+			this.requireTask(dependencyId);
+			const graph = this.dependencyCheckGraph(id, dependencyId);
+			assertDependencyEdgeAllowed(graph, id, dependencyId);
+			const node = graph.nodes.find((entry) => entry.task.id === id)!;
+			if (node.dependencyIds.includes(dependencyId)) return this.showTask(id);
+			if (node.dependencyIds.length >= TASK_EXECUTION_MAX_DEGREE) {
+				throw new TaskExecutionBoundExceededError(`task "${id}" cannot exceed ${TASK_EXECUTION_MAX_DEGREE} prerequisites`);
+			}
+			const successorCount = graph.nodes.filter((entry) => entry.dependencyIds.includes(dependencyId)).length;
+			if (successorCount >= TASK_EXECUTION_MAX_DEGREE) {
+				throw new TaskExecutionBoundExceededError(`task "${dependencyId}" cannot exceed ${TASK_EXECUTION_MAX_DEGREE} successors`);
+			}
+			this.artifacts.link({ from: id, relation: "depends_on", to: dependencyId }, context);
+			this.appendEvent({ taskId: id, type: "dependency_added", reason: context.reason }, context);
+			return this.showTask(id);
+		});
+	}
+
+	/** 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(() => {
+			const task = this.requireTask(id);
+			const dependency = this.requireTask(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.requireTask(remainingId).status !== "done");
+				if (stillBlocking.length === 0) this.appendEvent({ taskId: id, type: "became_ready" }, context);
+			}
+			return this.showTask(id);
+		});
+	}
+
+	contain(parentId: string, childId: string, context: TaskEventContext = {}): Artifact {
+		return this.events.atomic(() => {
+			this.requireTask(parentId);
+			this.requireTask(childId);
+			const alreadyContained = this.relationships(parentId).some(
+				(edge) => edge.relation === "contains" && edge.from === parentId && edge.to === childId,
+			);
+			this.artifacts.link({ from: parentId, relation: "contains", to: childId }, context);
+			this.artifacts.link({ from: childId, relation: "part_of", to: parentId }, context);
+			if (!alreadyContained) this.appendEvent({ taskId: parentId, type: "containment_added", reason: context.reason }, context);
+			return this.showTask(parentId);
+		});
+	}
+
+	/** Idempotent: removing an already-absent containment is a no-op. Both contains/part_of edges are removed atomically. */
+	uncontain(parentId: string, childId: string, context: TaskEventContext = {}): Artifact {
+		return this.events.atomic(() => {
+			this.requireTask(parentId);
+			this.requireTask(childId);
+			const removedContains = this.artifacts.unlink({ from: parentId, relation: "contains", to: childId }, context);
+			this.artifacts.unlink({ from: childId, relation: "part_of", to: parentId }, context);
+			if (removedContains) this.appendEvent({ taskId: parentId, type: "containment_removed", reason: context.reason }, context);
+			return this.showTask(parentId);
+		});
+	}
+}

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

@@ -0,0 +1,189 @@
+import type { Artifact } from "../artifact/artifact.ts";
+import type { ArtifactStore } from "../artifact/artifact-store.ts";
+import { TASK_FOCUS_STALE_AFTER_MS } from "../constants.ts";
+import { type AppendTaskEvent, type TaskEventContext, validateEventContext } from "../domain/task-event.ts";
+import type { TaskEventStore } from "../stores/task-event-store.ts";
+import type { TaskFocusStatus, TaskFocusStore } from "../stores/task-focus-store.ts";
+import { TaskInvalidTransitionError } from "./task-lifecycle-errors.ts";
+import type { TaskMutationCoordinator, TaskMutationRequestContext } from "./task-mutation-coordinator.ts";
+// Type-only import: erased entirely at compile time, so this does not create a real runtime
+// circular dependency even though task-service.ts also imports TaskFocusCoordinator (a real
+// value) from this file -- only one direction of this pair carries an actual runtime import.
+import type { TaskFilter, TaskMutationMetadata } from "./task-service.ts";
+
+export interface TaskFocus {
+	artifact: Artifact;
+	status: TaskFocusStatus;
+	updatedAt: string;
+	pauseReason?: string;
+}
+
+export type TaskFocusMutationResult = TaskFocus & TaskMutationMetadata;
+
+/**
+ * Task Focus (the single active/paused task per session scope), split out of the Tasks god class
+ * as part of a SOLID-audit-driven decomposition (see task b51419a0 and the "TaskFocusCoordinator"
+ * child of "Epic: Modularize papyrus/pi-papyrus god-files into building-block modules"), mirroring
+ * the existing TaskLeaseCoordinator/TaskMutationCoordinator precedent in this same directory.
+ *
+ * Focus is orthogonal to lifecycle and lease: focusing a task does not start it, and does not
+ * claim its lease -- so this concern has nothing to do with status transitions or worker
+ * exclusivity, the other concerns that were previously interleaved with it in one class.
+ */
+export class TaskFocusCoordinator {
+	constructor(
+		private readonly artifacts: Pick<ArtifactStore, "get">,
+		private readonly focusStore: TaskFocusStore,
+		private readonly events: TaskEventStore,
+		private readonly mutationCoordinator: TaskMutationCoordinator,
+		/** Delegates to Tasks.require() so Focus 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,
+		/** Delegates to Tasks.list() for the projectRoot-membership check in focused() -- list() is itself part of the project-scope concern, not duplicated here. */
+		private readonly listTasks: (filter?: TaskFilter) => Artifact[],
+		/** Delegates to Tasks' own actor/source/sessionId/reason defaulting so every event this coordinator appends looks identical to one Tasks itself would have appended. */
+		private readonly appendEvent: (event: Omit<AppendTaskEvent, "actor" | "source">, context: TaskEventContext) => void,
+	) {}
+
+	focused(filter?: TaskFilter): TaskFocus | null {
+		const focus = this.focusStore.get(filter?.sessionId);
+		if (!focus) return null;
+		const task = this.artifacts.get(focus.taskId);
+		if (task?.kind !== "task" || task.status === "done" || task.status === "canceled") {
+			this.focusStore.clear(focus.taskId, filter?.sessionId);
+			return null;
+		}
+		if (filter?.projectRoot && !this.listTasks(filter).some((candidate) => candidate.id === task.id)) return null;
+		return {
+			artifact: task,
+			status: focus.status,
+			updatedAt: focus.updatedAt,
+			...(focus.pauseReason ? { pauseReason: focus.pauseReason } : {}),
+		};
+	}
+
+	active(filter?: TaskFilter): Artifact | null {
+		const focus = this.focused(filter);
+		return focus?.status === "active" ? focus.artifact : null;
+	}
+
+	focus(id: string, context: TaskEventContext = {}): Artifact {
+		return this.events.atomic(() => {
+			const task = this.requireTask(id);
+			if (task.status === "done" || task.status === "canceled") throw new Error(`cannot focus task from ${task.status}`);
+			this.focusStore.set(id, context.sessionId);
+			this.appendEvent({ taskId: id, type: "focus_set" }, context);
+			return task;
+		});
+	}
+
+	pauseFocus(context: TaskEventContext = {}, request: TaskMutationRequestContext = {}): TaskFocusMutationResult {
+		const inspection = this.mutationCoordinator.prepare<TaskFocusMutationResult>("pause", undefined, context, request, false);
+		if (inspection.replay) return inspection.replay;
+		const focus = this.focused({ sessionId: context.sessionId });
+		if (!focus) {
+			throw new TaskInvalidTransitionError(
+				"pause",
+				"none",
+				"paused",
+				["focus"],
+				"Focus a non-terminal task before pausing; do not blindly retry pause.",
+			);
+		}
+		const prepared = inspection.pending
+			? inspection
+			: this.mutationCoordinator.prepare<TaskFocusMutationResult>("pause", undefined, context, request, true, () =>
+					validateEventContext(context),
+				);
+		if (focus.status === "paused") {
+			return this.mutationCoordinator.complete(prepared.record, {
+				...focus,
+				changed: false,
+				operation: "pause",
+				currentStatus: "paused",
+				intendedStatus: "paused",
+				...(prepared.record ? { receiptId: prepared.record.receiptId } : {}),
+			});
+		}
+		return this.events.atomic(() => {
+			const state = this.focusStore.pause(focus.artifact.id, context.reason, context.sessionId);
+			this.appendEvent({ taskId: focus.artifact.id, type: "focus_paused" }, context);
+			return this.mutationCoordinator.complete(prepared.record, {
+				artifact: focus.artifact,
+				status: state.status,
+				updatedAt: state.updatedAt,
+				...(state.pauseReason ? { pauseReason: state.pauseReason } : {}),
+				changed: true,
+				operation: "pause",
+				currentStatus: "paused",
+				intendedStatus: "paused",
+				...(prepared.record ? { receiptId: prepared.record.receiptId } : {}),
+			});
+		});
+	}
+
+	unpauseFocus(context: TaskEventContext = {}, request: TaskMutationRequestContext = {}): TaskFocusMutationResult {
+		const inspection = this.mutationCoordinator.prepare<TaskFocusMutationResult>("unpause", undefined, context, request, false);
+		if (inspection.replay) return inspection.replay;
+		const focus = this.focused({ sessionId: context.sessionId });
+		if (!focus) {
+			throw new TaskInvalidTransitionError(
+				"unpause",
+				"none",
+				"active",
+				["focus"],
+				"Focus a non-terminal task before resuming; do not blindly retry unpause.",
+			);
+		}
+		const prepared = inspection.pending
+			? inspection
+			: this.mutationCoordinator.prepare<TaskFocusMutationResult>("unpause", undefined, context, request, true, () =>
+					validateEventContext(context),
+				);
+		if (focus.status === "active") {
+			return this.mutationCoordinator.complete(prepared.record, {
+				...focus,
+				changed: false,
+				operation: "unpause",
+				currentStatus: "active",
+				intendedStatus: "active",
+				...(prepared.record ? { receiptId: prepared.record.receiptId } : {}),
+			});
+		}
+		return this.events.atomic(() => {
+			const state = this.focusStore.unpause(focus.artifact.id, context.sessionId);
+			this.appendEvent({ taskId: focus.artifact.id, type: "focus_unpaused" }, context);
+			return this.mutationCoordinator.complete(prepared.record, {
+				artifact: focus.artifact,
+				status: state.status,
+				updatedAt: state.updatedAt,
+				changed: true,
+				operation: "unpause",
+				currentStatus: "active",
+				intendedStatus: "active",
+				...(prepared.record ? { receiptId: prepared.record.receiptId } : {}),
+			});
+		});
+	}
+
+	clearFocus(context: TaskEventContext = {}): { cleared: boolean } {
+		return this.events.atomic(() => {
+			const focus = this.focusStore.get(context.sessionId);
+			if (focus) this.appendEvent({ taskId: focus.taskId, type: "focus_cleared" }, context);
+			this.focusStore.clear(undefined, context.sessionId);
+			return { cleared: focus !== undefined };
+		});
+	}
+
+	/**
+	 * Time-based reclamation of Focus scopes nobody has touched in TASK_FOCUS_STALE_AFTER_MS,
+	 * independent of and in addition to the TASK_FOCUS_MAX_SCOPES hard cap -- see
+	 * clean-up-stale-per-session-task-focus-rows-on-real-session-l-9i7s and constants.ts's
+	 * comment on why this is deliberately not driven by session_start/session_shutdown.
+	 * No task-lifecycle event is appended: this is daemon housekeeping, not a caller-driven
+	 * mutation, and there is no longer a specific session/actor to attribute it to.
+	 */
+	reapStaleFocus(now: () => string = () => new Date().toISOString()): number {
+		const cutoff = new Date(new Date(now()).getTime() - TASK_FOCUS_STALE_AFTER_MS).toISOString();
+		return this.focusStore.reapStale(cutoff);
+	}
+}

package/src/task/task-lifecycle-errors.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared lifecycle-transition error, split into its own file so both task-service.ts (transition/
+ * complete) and task-focus-coordinator.ts (pause/unpause) can throw the identical class without a
+ * runtime circular import between them -- task-service.ts still re-exports this under the same
+ * name for backward compatibility with every existing consumer (src/index.ts's public surface,
+ * handlers/tasks.ts's `instanceof` check).
+ */
+export class TaskInvalidTransitionError extends Error {
+	constructor(
+		readonly operation: string,
+		readonly currentStatus: string,
+		readonly intendedStatus: string,
+		readonly allowedActions: readonly string[],
+		readonly recovery: string,
+	) {
+		super(`cannot ${operation} task from ${currentStatus}; intended status is ${intendedStatus}`);
+	}
+}