@danypops/papyrus 0.44.1 → 0.44.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.44.1",
+  "version": "0.44.3",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],
@@ -35,7 +35,7 @@
   "files": ["src", "README.md"],
   "dependencies": {
     "@danypops/vehicle-core": "^0.10.0",
-    "@danypops/vehicle-client": "^0.5.0",
+    "@danypops/vehicle-client": "^0.6.0",
     "@danypops/vehicle-server": "^0.13.0"
   }
 }

package/src/client.ts

@@ -1,13 +1,19 @@
 import { spawn as spawnProcess } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { connectWithVersionCheck, spawnDetachedDaemon } from "@danypops/vehicle-client/daemon-client";
-import { readPackageVersion } from "@danypops/vehicle-client/version";
+import { connectWithVersionCheck, type ExpectedVersion, spawnDetachedDaemon } from "@danypops/vehicle-client/daemon-client";
+import { createLiveVersionExpectation } from "@danypops/vehicle-client/version";
 import { DAEMON_CLIENT_TIMEOUT_MS, DAEMON_DIR_ENV, DAEMON_PROBE_TIMEOUT_MS } from "./constants.ts";
 import { type DaemonHandle, daemonStateDir, readDaemonHandle } from "./daemon-state.ts";
 import type { OperationName, SchemaState } from "./service.ts";
 
-/** Compared against the running daemon's /health-reported version by connectWithVersionCheck below -- a long-lived daemon holds whatever code was loaded at its own start. */
-const PAPYRUS_VERSION = readPackageVersion(new URL("../package.json", import.meta.url), "Papyrus");
+/**
+ * Compared against the running daemon's /health-reported version by connectWithVersionCheck
+ * below. Re-read fresh on every call, not cached -- a module-level `const` here was the exact
+ * bug that caused repeated, never-self-healing daemon kill/respawn churn on any process that
+ * outlived an `npm update` (a respawned daemon runs the same source and reports the same real
+ * version, so a stale cached expectation never converges).
+ */
+const papyrusExpectedVersion = createLiveVersionExpectation(new URL("../package.json", import.meta.url), "Papyrus");
 
 export type FetchAdapter = (request: Request) => Promise<Response>;
 
@@ -89,7 +95,7 @@ export interface ConnectPapyrusClientOptions {
 	 */
 	env?: Record<string, string | undefined>;
 	/** Overrides the version connectWithVersionCheck compares against. Defaults to PAPYRUS_VERSION; test-only -- lets a test force a mismatch against a real daemon without a second build. */
-	expectedVersion?: string;
+	expectedVersion?: ExpectedVersion;
 }
 
 /**
@@ -126,7 +132,7 @@ export async function connectPapyrusClient(
 			fallbackMessage: "Papyrus daemon failed to start automatically; run `papyrus service install` or `papyrus serve` manually.",
 		},
 		{
-			expectedVersion: options.expectedVersion ?? PAPYRUS_VERSION,
+			expectedVersion: options.expectedVersion ?? papyrusExpectedVersion,
 			readVersion: async (client) => (await client.health()).version,
 			killStaleProcess: killStalePapyrusDaemon,
 		},

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) =>