@danypops/papyrus 0.44.0 → 0.44.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.44.0",
+  "version": "0.44.2",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],
@@ -36,6 +36,6 @@
   "dependencies": {
     "@danypops/vehicle-core": "^0.10.0",
     "@danypops/vehicle-client": "^0.5.0",
-    "@danypops/vehicle-server": "^0.11.0"
+    "@danypops/vehicle-server": "^0.13.0"
   }
 }

package/src/daemon.ts

@@ -1,3 +1,5 @@
+import { join } from "node:path";
+import { acquireDaemonLock, releaseDaemonLock } from "@danypops/vehicle-server/paths";
 import { PushChannel } from "@danypops/vehicle-server/push-channel";
 import { DAEMON_HOST, DB_OPTIMIZE_INTERVAL_MS, dbPath, WAL_CHECKPOINT_INTERVAL_MS } from "./constants.ts";
 import { clearDaemonPort, daemonStateDir, loadOrCreateToken, writeDaemonPort } from "./daemon-state.ts";
@@ -28,6 +30,12 @@ const TASK_READ_ONLY_OPERATIONS = new Set([
 /** Start the supervised, long-running Papyrus service. */
 export function serveMain(): void {
 	const stateDir = daemonStateDir();
+	const lockPath = join(stateDir, "daemon.lock");
+	const lock = acquireDaemonLock(lockPath);
+	if (!lock.acquired) {
+		logEvent("info", "already_running", { holderPid: lock.holderPid });
+		return;
+	}
 	const token = loadOrCreateToken(stateDir);
 	const service = createPapyrusService(dbPath());
 	const pushChannel = new PushChannel({ token });
@@ -54,6 +62,7 @@ export function serveMain(): void {
 	});
 	if (!server.port) {
 		service.close();
+		releaseDaemonLock(lockPath);
 		throw new Error("Papyrus daemon failed to bind a listener");
 	}
 	writeDaemonPort(stateDir, server.port);
@@ -101,6 +110,7 @@ export function serveMain(): void {
 		clearInterval(reapFocusTimer);
 		clearInterval(purgeTrashTimer);
 		clearDaemonPort(stateDir);
+		releaseDaemonLock(lockPath);
 		service.close();
 		// .finally() re-throws rather than handling a rejection -- catching it first turns a bare
 		// unhandled-rejection warning into a real, queryable shutdown-failure log line.

package/src/playbook-definition.ts

@@ -45,6 +45,14 @@ export interface PlaybookExternalLink {
 	ownerIsFrom: boolean;
 }
 
+/** A Playbook's own composition tree (contains/depends_on nesting, step-level argument merging) is invalid: a cycle, excessive nesting depth, too many materialized tasks/linked artifacts, or conflicting argument types across nodes -- an ordinary, expected authoring mistake, not an unexpected crash. */
+export class PlaybookCompositionError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "PlaybookCompositionError";
+	}
+}
+
 export interface CompiledPlaybook {
 	definition: BlueprintDefinition;
 	/** The very first real leaf task in the whole tree's reading order -- what a caller should focus once materialized. */
@@ -118,7 +126,7 @@ interface CompileNodeResult {
 function mergeArgument(inputs: Record<string, BlueprintInputDefinition>, argument: PlaybookArgument): void {
 	const existing = inputs[argument.name];
 	if (existing && existing.type !== argument.type) {
-		throw new Error(
+		throw new PlaybookCompositionError(
 			`playbook composition declares conflicting types for argument "${argument.name}" (${existing.type} vs ${argument.type})`,
 		);
 	}
@@ -139,9 +147,9 @@ function compileNode(
 	parentRef: string | undefined,
 	incomingPrecedingRefs: string[],
 ): CompileNodeResult {
-	if (ancestorIds.has(playbookId)) throw new Error(`playbook composition cycle includes "${playbookId}"`);
+	if (ancestorIds.has(playbookId)) throw new PlaybookCompositionError(`playbook composition cycle includes "${playbookId}"`);
 	if (depth > PLAYBOOK_INVOCATION_MAX_CALL_DEPTH)
-		throw new Error(`playbook composition exceeds ${PLAYBOOK_INVOCATION_MAX_CALL_DEPTH} levels`);
+		throw new PlaybookCompositionError(`playbook composition exceeds ${PLAYBOOK_INVOCATION_MAX_CALL_DEPTH} levels`);
 	const nextAncestors = new Set([...ancestorIds, playbookId]);
 
 	const playbook = requirePlaybook(artifacts, playbookId);
@@ -156,7 +164,7 @@ function compileNode(
 	};
 	ctx.tasks.push(rootBlueprint);
 	if (ctx.tasks.length > PLAYBOOK_INVOCATION_MAX_CREATED_TASKS)
-		throw new Error(`playbook invocation exceeds ${PLAYBOOK_INVOCATION_MAX_CREATED_TASKS} tasks`);
+		throw new PlaybookCompositionError(`playbook invocation exceeds ${PLAYBOOK_INVOCATION_MAX_CREATED_TASKS} tasks`);
 
 	const edges = artifacts.relationships({ artifactIds: [playbookId] }).slice(0, PLAYBOOK_INVOCATION_MAX_LINKED_ARTIFACTS);
 	const composablePlaybookIds = nonTrashedPlaybookIds(
@@ -201,7 +209,7 @@ function compileNode(
 			const stepRef = `${rootRef}-s${index}`;
 			ctx.tasks.push({ ref: stepRef, title, body, parent: rootRef, dependsOn: cursorPrecedingRefs });
 			if (ctx.tasks.length > PLAYBOOK_INVOCATION_MAX_CREATED_TASKS)
-				throw new Error(`playbook invocation exceeds ${PLAYBOOK_INVOCATION_MAX_CREATED_TASKS} tasks`);
+				throw new PlaybookCompositionError(`playbook invocation exceeds ${PLAYBOOK_INVOCATION_MAX_CREATED_TASKS} tasks`);
 			if (headRef === undefined) headRef = stepRef;
 			cursorPrecedingRefs = [stepRef];
 			tailRef = stepRef;

package/src/task-execution.ts

@@ -1,6 +1,22 @@
 import { TASK_EXECUTION_MAX_DEGREE, TASK_EXECUTION_MAX_EDGES, TASK_EXECUTION_MAX_NODES } from "./constants.ts";
 import type { TaskGraph } from "./task-service.ts";
 
+/** A task execution graph is too large or too densely connected to process safely -- a distinct class (not a plain Error) so the Vehicle adapter layer can classify it into a capacity-category failure instead of an opaque handler-failed. */
+export class TaskExecutionBoundExceededError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "TaskExecutionBoundExceededError";
+	}
+}
+
+/** The requested dependency edge is invalid: a self-dependency, a cycle, or an endpoint missing from the graph it was checked against. */
+export class TaskDependencyCycleError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "TaskDependencyCycleError";
+	}
+}
+
 export type TaskExecutionState = "todo" | "in-progress" | "review" | "rejected" | "done" | "canceled" | "ready" | "blocked" | "invalid";
 
 export interface TaskExecutionNode {
@@ -31,16 +47,16 @@ function executionState(status: string, invalid: boolean, prerequisitesDone: boo
 
 function assertBounds(graph: TaskGraph): void {
 	if (graph.nodes.length > TASK_EXECUTION_MAX_NODES) {
-		throw new Error(`task execution graph exceeds ${TASK_EXECUTION_MAX_NODES} nodes`);
+		throw new TaskExecutionBoundExceededError(`task execution graph exceeds ${TASK_EXECUTION_MAX_NODES} nodes`);
 	}
 	for (const node of graph.nodes) {
 		if (node.dependencyIds.length > TASK_EXECUTION_MAX_DEGREE) {
-			throw new Error(`task "${node.task.id}" exceeds ${TASK_EXECUTION_MAX_DEGREE} prerequisites`);
+			throw new TaskExecutionBoundExceededError(`task "${node.task.id}" exceeds ${TASK_EXECUTION_MAX_DEGREE} prerequisites`);
 		}
 	}
 	const edgeCount = graph.nodes.reduce((count, node) => count + node.dependencyIds.length, 0);
 	if (edgeCount > TASK_EXECUTION_MAX_EDGES) {
-		throw new Error(`task execution graph exceeds ${TASK_EXECUTION_MAX_EDGES} dependency edges`);
+		throw new TaskExecutionBoundExceededError(`task execution graph exceeds ${TASK_EXECUTION_MAX_EDGES} dependency edges`);
 	}
 }
 
@@ -61,7 +77,7 @@ export function projectTaskExecution(graph: TaskGraph): TaskExecutionPlan {
 		for (const prerequisiteId of prerequisites) {
 			const dependentIds = successors.get(prerequisiteId)!;
 			if (dependentIds.length >= TASK_EXECUTION_MAX_DEGREE) {
-				throw new Error(`task "${prerequisiteId}" exceeds ${TASK_EXECUTION_MAX_DEGREE} successors`);
+				throw new TaskExecutionBoundExceededError(`task "${prerequisiteId}" exceeds ${TASK_EXECUTION_MAX_DEGREE} successors`);
 			}
 			dependentIds.push(node.task.id);
 		}
@@ -113,15 +129,16 @@ export function projectTaskExecution(graph: TaskGraph): TaskExecutionPlan {
 /** Reject a dependency edge when the prerequisite already reaches the dependent. */
 export function assertDependencyEdgeAllowed(graph: TaskGraph, id: string, dependencyId: string): void {
 	assertBounds(graph);
-	if (id === dependencyId) throw new Error(`task "${id}" cannot depend on itself`);
+	if (id === dependencyId) throw new TaskDependencyCycleError(`task "${id}" cannot depend on itself`);
 	const byId = new Map(graph.nodes.map((node) => [node.task.id, node]));
-	if (!byId.has(id) || !byId.has(dependencyId)) throw new Error("dependency endpoints must be present in the task graph");
+	if (!byId.has(id) || !byId.has(dependencyId))
+		throw new TaskDependencyCycleError("dependency endpoints must be present in the task graph");
 
 	const pending = [dependencyId];
 	const visited = new Set<string>();
 	while (pending.length > 0) {
 		const current = pending.pop()!;
-		if (current === id) throw new Error(`dependency cycle: "${id}" cannot depend on "${dependencyId}"`);
+		if (current === id) throw new TaskDependencyCycleError(`dependency cycle: "${id}" cannot depend on "${dependencyId}"`);
 		if (visited.has(current)) continue;
 		visited.add(current);
 		for (const prerequisiteId of byId.get(current)?.dependencyIds ?? []) pending.push(prerequisiteId);

package/src/task-service.ts

@@ -37,7 +37,7 @@ import { InMemoryTaskEventStore, type TaskEventStore } from "./ports/task-event-
 import { InMemoryTaskFocusStore, type TaskFocusStatus, type TaskFocusStore } from "./ports/task-focus-store.ts";
 import { InMemoryTaskLeaseStore, type TaskLeaseStore } from "./ports/task-lease-store.ts";
 import { InMemoryTaskScopeStore, type TaskScopeStore } from "./ports/task-scope-store.ts";
-import { assertDependencyEdgeAllowed } from "./task-execution.ts";
+import { assertDependencyEdgeAllowed, TaskExecutionBoundExceededError } from "./task-execution.ts";
 
 export interface UpdateTaskInput {
 	title?: string;
@@ -625,16 +625,16 @@ export class Tasks {
 		return this.events.atomic(() => {
 			this.require(id);
 			this.require(dependencyId);
-			const graph = this.graph();
+			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.show(id);
 			if (node.dependencyIds.length >= TASK_EXECUTION_MAX_DEGREE) {
-				throw new Error(`task "${id}" cannot exceed ${TASK_EXECUTION_MAX_DEGREE} prerequisites`);
+				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 Error(`task "${dependencyId}" cannot exceed ${TASK_EXECUTION_MAX_DEGREE} successors`);
+				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);
@@ -642,6 +642,23 @@ export class Tasks {
 		});
 	}
 
+	/**
+	 * Scopes the cycle-check graph to the two endpoints' shared project when they have one, instead
+	 * of building the whole daemon's graph -- a small project's own dependency check must never fail
+	 * just because unrelated tasks in other projects pushed the daemon-wide total over
+	 * TASK_EXECUTION_MAX_NODES. Falls back to the unscoped graph when the endpoints don't share a
+	 * known project (a genuine cross-project dependency), preserving the prior, correct behavior for
+	 * that rarer case.
+	 */
+	private dependencyCheckGraph(id: string, dependencyId: string): TaskGraph {
+		const sourceProject = this.scopes.get(id)?.projectRoot;
+		const targetProject = this.scopes.get(dependencyId)?.projectRoot;
+		if (sourceProject !== undefined && sourceProject === targetProject) {
+			return this.graph({ projectRoot: sourceProject, scope: "project" });
+		}
+		return this.graph();
+	}
+
 	/** 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(() => {
@@ -875,7 +892,7 @@ export class Tasks {
 	}
 
 	/**
-	 * Discuss's forcing behavior (see domain/discussion.ts): an active Discussion doc that
+	 * Discuss's forcing behavior (see discussions/discussion.ts): an active Discussion doc that
 	 * `blocks` this task refuses its completion until settled or deferred. A discussion whose
 	 * extra.discussion shape is missing or corrupt is treated as non-blocking rather than
 	 * crashing completion -- the same fail-open posture Task Focus's opt-in armor uses for an

package/src/vehicle/artifact-vehicle-shared.ts

@@ -5,8 +5,10 @@
  */
 import { defineVehicleSchema, type VehicleContentBlock, VehicleError, type VehicleSchemaCodec } from "@danypops/vehicle-core";
 import type { Artifact } from "../domain/artifact.ts";
+import { PlaybookCompositionError } from "../playbook-definition.ts";
 import type { ArtifactStore } from "../ports/artifact-store.ts";
-import type { TaskExecutionPlan } from "../task-execution.ts";
+import { InvalidSessionSecretError } from "../session-identity-service.ts";
+import { TaskDependencyCycleError, TaskExecutionBoundExceededError, type TaskExecutionPlan } from "../task-execution.ts";
 
 /**
  * VehicleRegistry only ever calls a schema's own safeParse -- jsonSchema is
@@ -60,6 +62,69 @@ export function validationError(message: string): VehicleError {
 	return new VehicleError("validation-failed", message, { category: "validation" });
 }
 
+/**
+ * tasks.focus/pause/unpause/clear_focus and playbooks.invoke all re-run
+ * sessionIdentity.assertAuthorized(session_id, session_secret) directly, bypassing the guarded
+ * tasks.focus operation (see modules/tasks.ts's guardFocusMutation and modules/playbooks.ts's own
+ * doc comment) -- a real, registered session's own auth failure is an ordinary, expected outcome,
+ * not an unexpected crash, so it must surface as its own classified VehicleError. Real incident:
+ * this used to arrive only inside .cause of an opaque "... handler failed", invisible to a caller
+ * that doesn't already know to dig for it. Anything else propagates unchanged, so vehicle-registry's
+ * own secure-by-default handler-failed opacity still applies to a genuine unexpected crash.
+ */
+export function classifySessionAuthorization<T>(run: () => T): T {
+	try {
+		return run();
+	} catch (error) {
+		if (error instanceof InvalidSessionSecretError) {
+			throw new VehicleError("invalid-session-secret", error.message, { category: "authorization" });
+		}
+		throw error;
+	}
+}
+
+/**
+ * A task execution graph (or a workflow/playbook run materializing one) that exceeds its own
+ * node/edge/degree bound is an ordinary, expected capacity failure, not an unexpected crash --
+ * must surface as its own classified VehicleError instead of vehicle-registry's generic
+ * handler-failed. Shared by tasks-vehicle.ts (create/depend/contain/graph/plan/complete) and
+ * playbooks-vehicle.ts (invoke, which materializes Tasks through the same shared engine).
+ */
+export function classifyTaskExecutionBounds<T>(run: () => T): T {
+	try {
+		return run();
+	} catch (error) {
+		if (error instanceof TaskExecutionBoundExceededError) {
+			throw new VehicleError("task-execution-bound-exceeded", error.message, { category: "capacity" });
+		}
+		throw error;
+	}
+}
+
+/** A self-dependency or dependency-cycle rejection (tasks.depend/undepend/create) is an ordinary, expected validation failure, not an unexpected crash. */
+export function classifyTaskDependencyCycles<T>(run: () => T): T {
+	try {
+		return run();
+	} catch (error) {
+		if (error instanceof TaskDependencyCycleError) {
+			throw new VehicleError("task-dependency-cycle", error.message, { category: "validation" });
+		}
+		throw error;
+	}
+}
+
+/** A Playbook's own composition tree (contains/depends_on nesting) is invalid -- a cycle, excessive depth/size, or conflicting argument types -- an ordinary, expected authoring mistake caught at playbooks.invoke/preview compile time, not an unexpected crash. */
+export function classifyPlaybookComposition<T>(run: () => T): T {
+	try {
+		return run();
+	} catch (error) {
+		if (error instanceof PlaybookCompositionError) {
+			throw new VehicleError("playbook-composition-invalid", error.message, { category: "validation" });
+		}
+		throw error;
+	}
+}
+
 /** A known LLM tool-calling quirk: a nested-object field arrives JSON-stringified rather than as a real object. Mutates input[key] in place when it's a string, leaves it untouched otherwise. */
 export function normalizeJsonEncodedField(input: Record<string, unknown>, key: string): void {
 	const value = input[key];

package/src/vehicle/playbooks-vehicle.ts

@@ -31,6 +31,9 @@ import type { SessionIdentity } from "../session-identity-service.ts";
 import type { Tasks } from "../task-service.ts";
 import {
 	buildWorkflowRunContent,
+	classifyPlaybookComposition,
+	classifySessionAuthorization,
+	classifyTaskExecutionBounds,
 	looseObjectSchema,
 	normalizeJsonEncodedField,
 	numberProp,
@@ -64,7 +67,19 @@ export function registerPlaybooksVehicleOperations(registry: VehicleRegistry, de
 	const moduleOperations = new Map(
 		playbooksOperations({ artifacts, events, scopes, artifactScopes, tasks, sessionIdentity }).map((op) => [op.name, op]),
 	);
-	const call = (name: string, input: Record<string, unknown>): unknown => moduleOperations.get(name)!.execute(input);
+	/**
+	 * Every playbooks.* action funnels through here. invoke's own module handler re-runs
+	 * sessionIdentity.assertAuthorized directly (see this file's own doc comment) and its
+	 * blueprint-materialization engine (workflow-execution.ts) can hit the same execution-graph
+	 * bounds tasks-vehicle.ts's own operations do -- classifying both reviewed domain error classes
+	 * at this one choke point covers every action that can throw them. Anything else propagates
+	 * unchanged -- vehicle-registry's own secure-by-default handler-failed opacity still applies to a
+	 * genuine unexpected crash (see artifact-vehicle-shared.ts's classify* helpers).
+	 */
+	const call = (name: string, input: Record<string, unknown>): unknown =>
+		classifySessionAuthorization(() =>
+			classifyTaskExecutionBounds(() => classifyPlaybookComposition(() => moduleOperations.get(name)!.execute(input))),
+		);
 
 	const define = (
 		action: string,

package/src/vehicle/tasks-vehicle.ts

@@ -28,6 +28,9 @@ import type { SessionIdentity } from "../session-identity-service.ts";
 import type { TaskExecutionPlan } from "../task-execution.ts";
 import type { TaskCompletion, Tasks } from "../task-service.ts";
 import {
+	classifySessionAuthorization,
+	classifyTaskDependencyCycles,
+	classifyTaskExecutionBounds,
 	labelsById,
 	looseObjectSchema,
 	numberProp,
@@ -144,7 +147,17 @@ function planContentText(plan: TaskExecutionPlan): string {
 export function registerTasksVehicleOperations(registry: VehicleRegistry, deps: TasksVehicleDeps): void {
 	const { tasks, artifacts, sessionIdentity } = deps;
 	const moduleOperations = new Map(tasksOperations(tasks, artifacts, sessionIdentity).map((op) => [op.name, op]));
-	const call = (name: string, input: Record<string, unknown>): unknown => moduleOperations.get(name)!.execute(input);
+	/**
+	 * Every tasks.* action funnels through here, so classifying a handful of reviewed domain error
+	 * classes (execution-graph bounds, dependency cycles, Task Focus authorization) at this one
+	 * choke point covers every action that can throw them. Anything else propagates unchanged --
+	 * vehicle-registry's own secure-by-default handler-failed opacity still applies to a genuine
+	 * unexpected crash (see artifact-vehicle-shared.ts's classify* helpers).
+	 */
+	const call = (name: string, input: Record<string, unknown>): unknown =>
+		classifySessionAuthorization(() =>
+			classifyTaskExecutionBounds(() => classifyTaskDependencyCycles(() => moduleOperations.get(name)!.execute(input))),
+		);
 
 	const define = (
 		action: string,

package/src/workflow-execution.ts

@@ -21,7 +21,7 @@ import type { ArtifactStore } from "./ports/artifact-store.ts";
 import { requireAtomicArtifactStore } from "./ports/atomic-artifact-store.ts";
 import type { TaskEventStore } from "./ports/task-event-store.ts";
 import type { TaskScopeStore } from "./ports/task-scope-store.ts";
-import { projectTaskExecution, type TaskExecutionPlan } from "./task-execution.ts";
+import { projectTaskExecution, TaskExecutionBoundExceededError, type TaskExecutionPlan } from "./task-execution.ts";
 import type { TaskGraph, TaskNode, TaskStatus } from "./task-service.ts";
 
 const RUN_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
@@ -304,7 +304,7 @@ export function materializeWorkflowDefinition(
 		rendered.blueprints.tasks.filter((task) => (task.dependsOn?.length ?? 0) === 0).length +
 		rendered.blueprints.skills.filter((call) => (call.dependsOn?.length ?? 0) === 0).length;
 	if (relationshipCount > TASK_EXECUTION_MAX_EDGES) {
-		throw new Error(`workflow run exceeds ${TASK_EXECUTION_MAX_EDGES} relationships`);
+		throw new TaskExecutionBoundExceededError(`workflow run exceeds ${TASK_EXECUTION_MAX_EDGES} relationships`);
 	}
 
 	const docs = rendered.blueprints.docs.map((blueprint) =>