@danypops/papyrus 0.39.0 → 0.41.0

package/README.md

@@ -80,11 +80,11 @@ papyrus skills run <skill-id> \
   --json
 ```
 
-The existing `artifact-template` skill subtype remains a compatibility mechanism for one-artifact templates with metadata `{targetKind, defaults, required}`. Instantiate it through the `skills` tool's `instantiate` action with `template_id`; defaults merge recursively, explicit arrays replace defaults, required paths such as `extra.owner` are validated, and target-kind mismatches are rejected.
+The existing `artifact-template` skill subtype remains a compatibility mechanism for one-artifact templates with metadata `{targetKind, defaults, required}`. Instantiate it via the `skills.instantiate` operation with `template_id`; defaults merge recursively, explicit arrays replace defaults, required paths such as `extra.owner` are validated, and target-kind mismatches are rejected.
 
 ### Removing an artifact
 
-Artifacts are never hard-deleted on request: every artifact gets a permanent, immutable `created` row in the mutation event log the moment it exists, so removal is a real, time-gated trash rather than a status flip. `remove` (any of the `tasks`/`docs`/`rules`/`skills` domain tools, or `papyrus artifact remove <id> [--reason <text>]`) moves an artifact to the trash: it is immediately excluded from every list/query, still directly reachable by id, and fully recoverable via `restore` until its purge deadline (30 days later) passes. `remove` refuses a Task that is the live Task Focus in any scope.
+Artifacts are never hard-deleted on request: every artifact gets a permanent, immutable `created` row in the mutation event log the moment it exists, so removal is a real, time-gated trash rather than a status flip. `remove` (the shared `artifact.remove`/`artifact.remove_subtree` operations every agent-facing domain routes through, or `papyrus artifact remove <id> [--reason <text>]`) moves an artifact to the trash: it is immediately excluded from every list/query, still directly reachable by id, and fully recoverable via `restore` until its purge deadline (30 days later) passes. `remove` refuses a Task that is the live Task Focus in any scope.
 
 Once the deadline passes, the daemon's periodic sweep performs a real, cascading, irreversible deletion — the one deliberate, narrow exception to Papyrus's otherwise-absolute append-only history, enforced by the database itself (not merely application code) via a trigger condition checked at delete time.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.39.0",
+  "version": "0.41.0",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],
@@ -34,7 +34,7 @@
   },
   "files": ["src", "README.md"],
   "dependencies": {
-    "@danypops/vehicle-core": "^0.1.1",
+    "@danypops/vehicle-core": "^0.2.0",
     "@danypops/vehicle-client": "^0.1.1",
     "@danypops/vehicle-server": "^0.3.2"
   }

package/src/modules/skills.ts

@@ -17,12 +17,15 @@
  * extraction.
  */
 import type { AuthorityRegistry } from "../authority-registry.ts";
-import { assignSkillProject, createArtifactTemplate, createSkill, listSkills, showSkill, skillInvocation, transitionSkill, updateSkill } from "../domain-services.ts";
+import type { Artifact, CreateArtifactInput } from "../domain/artifact.ts";
+import type { ArtifactEventContext } from "../domain/artifact-event.ts";
+import { assignSkillProject, createArtifactTemplate, createSkill, instantiateTemplate, listSkills, showSkill, skillInvocation, transitionSkill, updateSkill } from "../domain-services.ts";
 import type { OperationDefinition } from "../module-registry.ts";
 import type { ArtifactScopeStore } from "../ports/artifact-scope-store.ts";
 import type { ArtifactStore } from "../ports/artifact-store.ts";
 import type { TaskEventStore } from "../ports/task-event-store.ts";
 import type { TaskScopeStore } from "../ports/task-scope-store.ts";
+import type { Tasks, TaskStatus } from "../task-service.ts";
 import { instantiateSkillWorkflow } from "../workflow-execution.ts";
 
 const MODULE_ID = "skills";
@@ -76,6 +79,45 @@ export interface SkillsModuleDeps {
 	authority: AuthorityRegistry;
 }
 
+function normalizeCreateInput(input: OperationInput): CreateArtifactInput {
+	const { template_id, ...rest } = input;
+	return { ...rest, templateId: typeof template_id === "string" ? template_id : undefined } as CreateArtifactInput;
+}
+
+/**
+ * skills.instantiate's own branching logic (compatibility-template creation vs. a
+ * task-target template's tasks.create() call) -- shared between service.ts's raw RPC
+ * forwarder and skills-vehicle.ts's Vehicle operation, the two real callers, instead
+ * of reimplemented in each. Takes `tasks: Tasks` directly rather than through
+ * SkillsModuleDeps: a genuine cross-module dependency, the same category as
+ * rules.injectable and the module comment's own reason skills.instantiate isn't
+ * registered as an operation here.
+ */
+export interface InstantiateSkillDeps {
+	artifacts: ArtifactStore;
+	tasks: Tasks;
+	authority: AuthorityRegistry;
+}
+
+export function instantiateSkillOrTemplate(deps: InstantiateSkillDeps, input: OperationInput, context?: ArtifactEventContext): Artifact {
+	const templateId = string(input, "template_id");
+	const template = deps.artifacts.get(templateId);
+	// Note ownership for a non-task template target is enforced inside instantiateTemplate's
+	// own rejectsNoteTemplate for the non-task branch below -- nothing else currently claims
+	// an unresolved (pre-template-resolution) kind, so there is no check to perform here.
+	if (template?.extra["targetKind"] !== "task") return instantiateTemplate(deps.artifacts, templateId, normalizeCreateInput(input), deps.authority, context);
+	return deps.tasks.create({
+		title: optionalString(input, "title") as string,
+		body: optionalString(input, "body"),
+		status: optionalString(input, "status") as TaskStatus | undefined,
+		labels: input["labels"] as string[] | undefined,
+		extra: input["extra"] as Record<string, unknown> | undefined,
+		templateId,
+		projectRoot: string(input, "project_root"),
+		projectSource: "cwd",
+	}, context);
+}
+
 /** Registers every skills.* operation except skills.instantiate (see module comment). Behavior is unchanged from the prior inline handlers in src/service.ts. */
 /** This module's own operation names, the single source of truth src/service.ts's EXPECTED_OPERATION_NAMES spreads in rather than re-listing by hand. skills.instantiate is deliberately absent -- see the module comment above. */
 export const SKILLS_OPERATION_NAMES = [

package/src/service.ts

@@ -24,7 +24,6 @@ import type { TaskEventStore } from "./ports/task-event-store.ts";
 import type { TaskScopeStore } from "./ports/task-scope-store.ts";
 import { Tasks, type TaskStatus } from "./task-service.ts";
 import {
-	instantiateTemplate,
 	listInjectableRules,
 } from "./domain-services.ts";
 import { Notes, NOTE_SUBTYPE } from "./note-service.ts";
@@ -40,7 +39,7 @@ import { graphProjectionOperations, GRAPH_PROJECTION_OPERATION_NAMES } from "./m
 import { logsOperations, LOGS_OPERATION_NAMES } from "./modules/logs.ts";
 import { notesOperations, NOTES_OPERATION_NAMES } from "./modules/notes.ts";
 import { rulesOperations, RULES_OPERATION_NAMES } from "./modules/rules.ts";
-import { skillsOperations, SKILLS_OPERATION_NAMES } from "./modules/skills.ts";
+import { instantiateSkillOrTemplate, skillsOperations, SKILLS_OPERATION_NAMES } from "./modules/skills.ts";
 import { playbooksOperations, PLAYBOOKS_OPERATION_NAMES } from "./modules/playbooks.ts";
 import { sessionIdentityOperations, SESSION_IDENTITY_OPERATION_NAMES } from "./modules/session-identity.ts";
 import { discussOperations, DISCUSS_OPERATION_NAMES } from "./modules/discuss.ts";
@@ -432,24 +431,7 @@ function handlers(
 		"playbooks.uncontain": forwardToModule("playbooks.uncontain"),
 		"playbooks.depend": forwardToModule("playbooks.depend"),
 		"playbooks.undepend": forwardToModule("playbooks.undepend"),
-		"skills.instantiate": (input) => {
-			const templateId = string(input, "template_id");
-			const template = artifacts.get(templateId);
-			// Note ownership for a non-task template target is enforced inside instantiateTemplate's
-			// own rejectsNoteTemplate for the non-task branch below -- nothing else currently claims
-			// an unresolved (pre-template-resolution) kind, so there is no check to perform here.
-			if (template?.extra["targetKind"] !== "task") return instantiateTemplate(artifacts, templateId, normalizeCreateInput(input), authority, eventContext(input));
-			return tasks.create({
-				title: optionalString(input, "title") as string,
-				body: optionalString(input, "body"),
-				status: optionalString(input, "status") as TaskStatus | undefined,
-				labels: input["labels"] as string[] | undefined,
-				extra: input["extra"] as Record<string, unknown> | undefined,
-				templateId,
-				projectRoot: string(input, "project_root"),
-				projectSource: "cwd",
-			}, eventContextFor(input, "template-instantiation"));
-		},
+		"skills.instantiate": (input) => instantiateSkillOrTemplate({ artifacts, tasks, authority }, input, eventContextFor(input, "template-instantiation")),
 		"graph_projection.apply": forwardToModule("graph_projection.apply"),
 		"graph_projection.checkpoint": forwardToModule("graph_projection.checkpoint"),
 		"logs.append": forwardToModule("logs.append"),
@@ -486,7 +468,7 @@ export function createPapyrusService(path: string): PapyrusService {
 	const sessionIdentity = new SessionIdentity(new SQLiteSessionIdentityStore(db));
 	const discussions = new Discussions(artifacts, new SQLiteDiscussionRoundStore(db));
 	const authority = createAuthorityRegistry();
-	const vehicle = createPapyrusVehicleRegistry({ artifacts, scopes: artifactScopes, authority, notes });
+	const vehicle = createPapyrusVehicleRegistry({ artifacts, scopes: artifactScopes, authority, notes, events, taskScopes: scopes, tasks, sessionIdentity });
 	const moduleRegistry = new OperationRegistry();
 	moduleRegistry.registerAll(notesOperations(notes));
 	moduleRegistry.registerAll(logsOperations(logs));

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

@@ -3,8 +3,10 @@
  * VehicleRegistry projection (notes-vehicle.ts, rules-vehicle.ts, docs-vehicle.ts,
  * artifact-trash-vehicle.ts).
  */
-import { defineVehicleSchema, type VehicleSchemaCodec } from "@danypops/vehicle-core";
+import { defineVehicleSchema, type VehicleSchemaCodec, type VehicleContentBlock } from "@danypops/vehicle-core";
 import type { Artifact } from "../domain/artifact.ts";
+import type { ArtifactStore } from "../ports/artifact-store.ts";
+import type { TaskExecutionPlan } from "../task-execution.ts";
 
 /**
  * VehicleRegistry only ever calls a schema's own safeParse -- jsonSchema is
@@ -42,6 +44,17 @@ export const passthroughOutput: VehicleSchemaCodec<unknown> = defineVehicleSchem
 export const stringProp = { type: "string" } as const;
 export const numberProp = { type: "number" } as const;
 
+/** 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];
+	if (typeof value !== "string") return;
+	try {
+		input[key] = JSON.parse(value);
+	} catch {
+		throw new Error(`${key} must be valid JSON`);
+	}
+}
+
 /** Exact match semantics as the Pi-extension helper this replaces (domain-tools.ts's matchArtifactByName) -- case-insensitive exact title match, refuses to guess between ambiguous matches. */
 export function matchArtifactByName(candidates: readonly Artifact[], name: string): string {
 	const needle = name.trim().toLowerCase();
@@ -67,3 +80,47 @@ export function resolveArtifactIdWidened(name: string, fetchCandidates: () => re
 		return matchArtifactByName(fetchWidened(), name);
 	}
 }
+
+/** Synchronous equivalent of pi-papyrus's own artifactLabelsById -- server-side, a direct ArtifactStore.get() replaces the extra RPC round-trip that helper needed client-side. Disambiguates same-titled artifacts by appending their id. */
+export function labelsById(artifacts: ArtifactStore, ids: readonly string[]): Map<string, string> {
+	const uniqueIds = [...new Set(ids)];
+	const resolved = uniqueIds.map((id) => artifacts.get(id)).filter((artifact): artifact is Artifact => artifact !== null);
+	const titleCounts = new Map<string, number>();
+	for (const artifact of resolved) titleCounts.set(artifact.title, (titleCounts.get(artifact.title) ?? 0) + 1);
+	return new Map(resolved.map((artifact) => [artifact.id, (titleCounts.get(artifact.title) ?? 0) > 1 ? `${artifact.title} (${artifact.id})` : artifact.title]));
+}
+
+export interface WorkflowRunNarrativeInput {
+	runId: string;
+	created: { docs: readonly string[]; rules: readonly string[]; tasks: readonly string[] };
+	rootTaskIds: readonly string[];
+	execution: TaskExecutionPlan;
+}
+
+/**
+ * Shared between skills.run and playbooks.invoke's Vehicle operations -- both produce the
+ * same shaped narrative (ready roots, context docs, scoped rules, an execution tree), only
+ * the headline and whether an "entry task focused" line is present differ. Builds the model-
+ * facing `content` text directly, so the model reads a summary instead of the raw execution
+ * DAG -- the same shape pi-papyrus's own hand-rolled skills/playbooks tools built client-side,
+ * now built once here where the run result is actually produced.
+ */
+export function buildWorkflowRunContent(artifacts: ArtifactStore, headline: string, input: WorkflowRunNarrativeInput, extraLines: readonly string[] = []): VehicleContentBlock {
+	const nodeById = new Map(input.execution.nodes.map((node) => [node.id, node]));
+	const rootLabels = input.rootTaskIds.map((id) => nodeById.get(id)?.title ?? "unknown task");
+	const createdLabels = labelsById(artifacts, [...input.created.docs, ...input.created.rules]);
+	const titleCounts = new Map<string, number>();
+	for (const node of input.execution.nodes) titleCounts.set(node.title, (titleCounts.get(node.title) ?? 0) + 1);
+	const executionLines = input.execution.nodes
+		.map((node) => ((titleCounts.get(node.title) ?? 0) > 1 ? `  [${node.state}] ${node.title} (${node.id})` : `  [${node.state}] ${node.title}`))
+		.join("\n");
+	const text = [
+		headline,
+		...extraLines,
+		`Ready roots: ${rootLabels.join(", ") || "none"}.`,
+		`Context docs: ${input.created.docs.map((id) => createdLabels.get(id) ?? "unknown document").join(", ") || "none"}.`,
+		`Scoped rules: ${input.created.rules.map((id) => createdLabels.get(id) ?? "unknown rule").join(", ") || "none"}.`,
+		...(executionLines ? ["Execution:", executionLines] : []),
+	].join("\n");
+	return { type: "text", text };
+}

package/src/vehicle/papyrus-vehicle.ts

@@ -1,11 +1,12 @@
 /**
  * Composition root for every domain projected onto Vehicle -- one VehicleRegistry,
  * one HTTP mount (see service.ts's createApp). Operation names are already globally
- * unique via their own dotted prefix (notes.*, rules.*, docs.*, artifact.*), so
- * merging costs nothing and avoids a separate registry/mount/client per domain.
+ * unique via their own dotted prefix (notes.*, rules.*, docs.*, skills.*, playbooks.*,
+ * artifact.*), so merging costs nothing and avoids a separate registry/mount/client
+ * per domain.
  *
- * skills, playbooks, discuss, and tasks still register via pi-papyrus's own
- * pi.registerTool() in domain-tools.ts, not here.
+ * discuss still registers via pi-papyrus's own pi.registerTool() in domain-tools.ts,
+ * not here -- see the papyrus Vehicle migration task for why.
  */
 import { VehicleRegistry } from "@danypops/vehicle-server";
 import type { AuthorityRegistry } from "../authority-registry.ts";
@@ -13,16 +14,27 @@ import type { Notes } from "../note-service.ts";
 import type { ArtifactScopeStore } from "../ports/artifact-scope-store.ts";
 import type { ArtifactStore } from "../ports/artifact-store.ts";
 import type { ArtifactTrashStore } from "../ports/artifact-trash-store.ts";
+import type { SessionIdentity } from "../session-identity-service.ts";
+import type { TaskEventStore } from "../ports/task-event-store.ts";
+import type { TaskScopeStore } from "../ports/task-scope-store.ts";
+import type { Tasks } from "../task-service.ts";
 import { registerArtifactTrashOperations } from "./artifact-trash-vehicle.ts";
 import { registerDocsVehicleOperations } from "./docs-vehicle.ts";
 import { registerNotesVehicleOperations } from "./notes-vehicle.ts";
+import { registerPlaybooksVehicleOperations } from "./playbooks-vehicle.ts";
 import { registerRulesVehicleOperations } from "./rules-vehicle.ts";
+import { registerSkillsVehicleOperations } from "./skills-vehicle.ts";
+import { registerTasksVehicleOperations } from "./tasks-vehicle.ts";
 
 export interface PapyrusVehicleDeps {
 	artifacts: ArtifactStore & ArtifactTrashStore;
 	scopes: ArtifactScopeStore;
 	authority: AuthorityRegistry;
 	notes: Notes;
+	events: TaskEventStore;
+	taskScopes: TaskScopeStore;
+	tasks: Tasks;
+	sessionIdentity: SessionIdentity;
 }
 
 export function createPapyrusVehicleRegistry(deps: PapyrusVehicleDeps): VehicleRegistry {
@@ -30,6 +42,9 @@ export function createPapyrusVehicleRegistry(deps: PapyrusVehicleDeps): VehicleR
 	registerNotesVehicleOperations(registry, deps.notes, deps.artifacts);
 	registerRulesVehicleOperations(registry, deps.artifacts, deps.scopes);
 	registerDocsVehicleOperations(registry, deps.artifacts, deps.scopes, deps.authority);
+	registerSkillsVehicleOperations(registry, { artifacts: deps.artifacts, events: deps.events, scopes: deps.taskScopes, artifactScopes: deps.scopes, authority: deps.authority, tasks: deps.tasks });
+	registerPlaybooksVehicleOperations(registry, { artifacts: deps.artifacts, events: deps.events, scopes: deps.taskScopes, artifactScopes: deps.scopes, tasks: deps.tasks, sessionIdentity: deps.sessionIdentity });
+	registerTasksVehicleOperations(registry, { tasks: deps.tasks, artifacts: deps.artifacts, sessionIdentity: deps.sessionIdentity });
 	registerArtifactTrashOperations(registry, deps.artifacts);
 	return registry;
 }

package/src/vehicle/playbooks-vehicle.ts

@@ -0,0 +1,243 @@
+/**
+ * Playbooks projected as a real VehicleRegistry: one VehicleOperation per real action.
+ * Wraps modules/playbooks.ts's operation definitions. remove/restore/remove_subtree are
+ * not duplicated here -- see ./artifact-trash-vehicle.ts.
+ *
+ * playbooks.invoke's own module handler calls tasks.focus() directly (bypassing the
+ * guarded tasks.focus operation, per modules/playbooks.ts's own doc comment) and re-runs
+ * that exact guard itself via sessionIdentity.assertAuthorized(session_id, session_secret).
+ * Those two fields never belong in this operation's model-visible inputSchema -- a model
+ * has no business knowing or supplying a session secret. Instead they travel through
+ * VehicleInvocationOptions.principal.claims, populated by pi-papyrus's own
+ * resolveInvocation hook (see vehicle-notes-client.ts) from its own already-cached
+ * session_secret, the same value the hand-rolled tool used to thread through as a raw
+ * input field. A caller with no cached secret for this session (unregistered, or a non-Pi
+ * Vehicle client) simply gets the guard's own no-op-when-unset default, unchanged.
+ *
+ * invoke's output carries its own `content` block (see @danypops/vehicle-core's
+ * WithVehicleContent) built from the same execution-DAG summary pi-papyrus's hand-rolled
+ * tool used to build client-side.
+ */
+import { bindVehicleOperation, defineVehicleOperation, type VehicleOperationContext } from "@danypops/vehicle-core";
+import type { VehicleRegistry } from "@danypops/vehicle-server";
+import { listPlaybooks } from "../domain-services.ts";
+import { playbooksOperations } from "../modules/playbooks.ts";
+import type { PlaybookInvocationResult, PlaybookMissingArguments } from "../playbook-execution.ts";
+import type { ArtifactScopeStore } from "../ports/artifact-scope-store.ts";
+import type { ArtifactStore } from "../ports/artifact-store.ts";
+import type { TaskEventStore } from "../ports/task-event-store.ts";
+import type { TaskScopeStore } from "../ports/task-scope-store.ts";
+import type { SessionIdentity } from "../session-identity-service.ts";
+import type { Tasks } from "../task-service.ts";
+import { buildWorkflowRunContent, looseObjectSchema, normalizeJsonEncodedField, numberProp, passthroughOutput, resolveArtifactIdWidened, stringProp } from "./artifact-vehicle-shared.ts";
+
+const OWNER = "playbooks";
+const LIMITS = { defaultTimeoutMs: 5_000, maxTimeoutMs: 30_000, maxRequestBytes: 65_536, maxResponseBytes: 262_144 };
+
+export interface PlaybooksVehicleDeps {
+	artifacts: ArtifactStore;
+	events: TaskEventStore;
+	scopes: TaskScopeStore;
+	artifactScopes: ArtifactScopeStore;
+	tasks: Tasks;
+	sessionIdentity: SessionIdentity;
+}
+
+/** Unscoped resolution -- a Playbook is commonly cross-project (e.g. a lab-deploy playbook), matching the hand-rolled tool's own resolutionRequest choice. */
+function resolvePlaybookId(artifacts: ArtifactStore, scopes: ArtifactScopeStore, id: unknown, name: unknown): string {
+	if (typeof id === "string" && id.length > 0) return id;
+	if (typeof name !== "string" || name.length === 0) throw new Error("id or name is required");
+	return resolveArtifactIdWidened(name, () => listPlaybooks(artifacts, scopes, { text: name }));
+}
+
+export function registerPlaybooksVehicleOperations(registry: VehicleRegistry, deps: PlaybooksVehicleDeps): void {
+	const { artifacts, events, scopes, artifactScopes, tasks, sessionIdentity } = deps;
+	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);
+
+	const define = (
+		action: string,
+		description: string,
+		effect: "read" | "local-write",
+		properties: Record<string, { type: string; enum?: readonly string[] }>,
+		required: readonly string[],
+		resolve: (input: Record<string, unknown>) => Record<string, unknown>,
+		execute?: (input: Record<string, unknown>, context: VehicleOperationContext<Record<string, unknown>>) => unknown,
+	): void => {
+		const operation = defineVehicleOperation({
+			name: `playbooks.${action}`,
+			version: 1,
+			description,
+			input: looseObjectSchema(properties, required),
+			output: passthroughOutput,
+			permissions: ["playbooks:read", "playbooks:write"],
+			effect,
+			idempotency: { mode: effect === "read" ? "safe" : "unsafe" },
+			limits: LIMITS,
+		});
+		registry.register(OWNER, bindVehicleOperation(operation, () => async (context) => (execute ?? ((input: Record<string, unknown>) => call(`playbooks.${action}`, input)))(resolve(context.input), context)));
+	};
+
+	define(
+		"create",
+		"Creates a Playbook -- prose: a trigger and an ordered list of steps. `arguments` declares named inputs: [{name, description?, required?}] (required defaults true), referenced in step text as {{name}}. project_root is optional (omitted = unscoped).",
+		"local-write",
+		{ title: stringProp, body: stringProp, trigger: stringProp, steps: { type: "array" }, tools: { type: "array" }, arguments: { type: "array" }, labels: { type: "array" }, extra: { type: "object" }, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		["title"],
+		(input) => {
+			normalizeJsonEncodedField(input, "arguments");
+			return input;
+		},
+	);
+
+	define(
+		"list",
+		"Lists Playbooks matching an optional status/text filter, scoped to project_root when given.",
+		"read",
+		{ status: stringProp, text: stringProp, limit: numberProp, project_root: stringProp },
+		[],
+		(input) => input,
+	);
+
+	define(
+		"show",
+		"Shows one Playbook by id or title.",
+		"read",
+		{ id: stringProp, name: stringProp },
+		[],
+		(input) => ({ ...input, id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name) }),
+	);
+
+	define(
+		"preview",
+		"Renders a Playbook's whole composition tree as text, with no side effects.",
+		"read",
+		{ id: stringProp, name: stringProp, arguments: { type: "object" } },
+		[],
+		(input) => {
+			normalizeJsonEncodedField(input, "arguments");
+			return { ...input, id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name) };
+		},
+	);
+
+	define(
+		"invoke",
+		"Compiles the Playbook's steps and composition tree into real Tasks wired with dependsOn, and focuses the first one -- one step surfaces at a time as it becomes focused, exactly like any other Task. `arguments` supplies known values as {name: value}; if a declared REQUIRED argument is still missing, nothing is created and missingArguments is returned instead -- ask the human for these (discuss tool, live:true) and invoke again, never guess. Drive the returned entryTaskId forward with the tasks tool (start/submit/complete).",
+		"local-write",
+		{ id: stringProp, name: stringProp, run_id: stringProp, arguments: { type: "object" }, project_root: stringProp },
+		[],
+		(input) => {
+			normalizeJsonEncodedField(input, "arguments");
+			return { ...input, id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name) };
+		},
+		(input, context) => {
+			const claims = context.principal?.claims as { sessionId?: string; sessionSecret?: string } | undefined;
+			const invocation = call("playbooks.invoke", {
+				...input,
+				session_id: claims?.sessionId,
+				session_secret: claims?.sessionSecret,
+			}) as PlaybookInvocationResult | PlaybookMissingArguments;
+			if ("missingArguments" in invocation) {
+				const text = `Missing required argument(s): ${invocation.missingArguments.join(", ")}. Nothing was created -- ask the human for these (discuss tool, live:true), then invoke again.`;
+				return { ...invocation, content: [{ type: "text" as const, text }] };
+			}
+			const nodeById = new Map(invocation.execution.nodes.map((node) => [node.id, node]));
+			const entryLabel = nodeById.get(invocation.entryTaskId)?.title ?? invocation.entryTaskId;
+			const content = buildWorkflowRunContent(
+				artifacts,
+				`Invoked playbook run ${invocation.runId}: ${invocation.created.tasks.length} task(s), ${invocation.created.rules.length} rule(s), ${invocation.created.docs.length} doc(s) created.`,
+				invocation,
+				[`Entry task now focused: ${entryLabel}. Drive it forward with the tasks tool (start/submit/complete) -- contains/depends_on wiring auto-focuses each next step.`],
+			);
+			return { ...invocation, content: [content] };
+		},
+	);
+
+	define(
+		"enable",
+		"Enables a Playbook.",
+		"local-write",
+		{ id: stringProp, name: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		[],
+		(input) => ({ ...input, id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name) }),
+	);
+
+	define(
+		"disable",
+		"Disables a Playbook.",
+		"local-write",
+		{ id: stringProp, name: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		[],
+		(input) => ({ ...input, id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name) }),
+	);
+
+	define(
+		"assign_project",
+		"Reassigns a Playbook's project_root, or unscopes it when project_root is omitted.",
+		"local-write",
+		{ id: stringProp, name: stringProp, project_root: stringProp },
+		[],
+		(input) => ({ ...input, id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name) }),
+	);
+
+	define(
+		"update",
+		"Changes a Playbook's title/body/labels (at least one required). Refused for a read-only external projection.",
+		"local-write",
+		{ id: stringProp, name: stringProp, title: stringProp, body: stringProp, labels: { type: "array" }, actor: stringProp, source: stringProp, session_id: stringProp },
+		[],
+		(input) => ({ ...input, id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name) }),
+	);
+
+	define(
+		"contain",
+		"Nests a child Playbook inside a parent -- the child's steps run AFTER the parent's own. Prefer parent_name/child_name over parent_id/child_id -- resolved server-side.",
+		"local-write",
+		{ parent_id: stringProp, parent_name: stringProp, child_id: stringProp, child_name: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		[],
+		(input) => ({
+			...input,
+			parent_id: resolvePlaybookId(artifacts, artifactScopes, input.parent_id, input.parent_name),
+			child_id: resolvePlaybookId(artifacts, artifactScopes, input.child_id, input.child_name),
+		}),
+	);
+
+	define(
+		"uncontain",
+		"Removes a parent/child Playbook nesting. Idempotent -- a no-op if the edge is already absent.",
+		"local-write",
+		{ parent_id: stringProp, parent_name: stringProp, child_id: stringProp, child_name: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		[],
+		(input) => ({
+			...input,
+			parent_id: resolvePlaybookId(artifacts, artifactScopes, input.parent_id, input.parent_name),
+			child_id: resolvePlaybookId(artifacts, artifactScopes, input.child_id, input.child_name),
+		}),
+	);
+
+	define(
+		"depend",
+		"Chains a prerequisite Playbook before another -- it must fully complete FIRST. Prefer dependency_name over dependency_id.",
+		"local-write",
+		{ id: stringProp, name: stringProp, dependency_id: stringProp, dependency_name: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		[],
+		(input) => ({
+			...input,
+			id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name),
+			dependency_id: resolvePlaybookId(artifacts, artifactScopes, input.dependency_id, input.dependency_name),
+		}),
+	);
+
+	define(
+		"undepend",
+		"Removes a Playbook dependency. Idempotent -- a no-op if the edge is already absent.",
+		"local-write",
+		{ id: stringProp, name: stringProp, dependency_id: stringProp, dependency_name: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		[],
+		(input) => ({
+			...input,
+			id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name),
+			dependency_id: resolvePlaybookId(artifacts, artifactScopes, input.dependency_id, input.dependency_name),
+		}),
+	);
+}

package/src/vehicle/skills-vehicle.ts

@@ -0,0 +1,194 @@
+/**
+ * Skills projected as a real VehicleRegistry: one VehicleOperation per real action.
+ * Wraps modules/skills.ts's operation definitions plus skills.instantiate (composition-
+ * root-only in the module -- see instantiateSkillOrTemplate's own doc comment).
+ * remove/restore/remove_subtree are not duplicated here -- see ./artifact-trash-vehicle.ts.
+ *
+ * skills.run's output carries its own `content` block (see @danypops/vehicle-core's
+ * WithVehicleContent) built from the same execution-DAG summary pi-papyrus's hand-rolled
+ * tool used to build client-side -- the model reads a summary, not the raw node/layer/
+ * cycleId structure.
+ */
+import { bindVehicleOperation, defineVehicleOperation } from "@danypops/vehicle-core";
+import type { VehicleRegistry } from "@danypops/vehicle-server";
+import type { AuthorityRegistry } from "../authority-registry.ts";
+import { listSkills } from "../domain-services.ts";
+import { instantiateSkillOrTemplate, skillsOperations } from "../modules/skills.ts";
+import type { ArtifactScopeStore } from "../ports/artifact-scope-store.ts";
+import type { ArtifactStore } from "../ports/artifact-store.ts";
+import type { TaskEventStore } from "../ports/task-event-store.ts";
+import type { TaskScopeStore } from "../ports/task-scope-store.ts";
+import type { Tasks } from "../task-service.ts";
+import type { WorkflowRunResult } from "../workflow-execution.ts";
+import { buildWorkflowRunContent, looseObjectSchema, numberProp, passthroughOutput, resolveArtifactIdWidened, stringProp } from "./artifact-vehicle-shared.ts";
+
+const OWNER = "skills";
+const LIMITS = { defaultTimeoutMs: 5_000, maxTimeoutMs: 30_000, maxRequestBytes: 65_536, maxResponseBytes: 262_144 };
+
+export interface SkillsVehicleDeps {
+	artifacts: ArtifactStore;
+	events: TaskEventStore;
+	scopes: TaskScopeStore;
+	artifactScopes: ArtifactScopeStore;
+	authority: AuthorityRegistry;
+	/** Only for skills.instantiate's task-target branch -- see instantiateSkillOrTemplate. */
+	tasks: Tasks;
+}
+
+function resolveSkillId(artifacts: ArtifactStore, scopes: ArtifactScopeStore, projectRoot: string | undefined, id: unknown, name: unknown): string {
+	if (typeof id === "string" && id.length > 0) return id;
+	if (typeof name !== "string" || name.length === 0) throw new Error("id or name is required");
+	return resolveArtifactIdWidened(
+		name,
+		() => listSkills(artifacts, scopes, { text: name, projectRoot }),
+		projectRoot === undefined ? undefined : () => listSkills(artifacts, scopes, { text: name }),
+	);
+}
+
+function resolveTemplateId(artifacts: ArtifactStore, scopes: ArtifactScopeStore, projectRoot: string | undefined, id: unknown, name: unknown): string | undefined {
+	if (typeof id === "string" && id.length > 0) return id;
+	if (typeof name !== "string" || name.length === 0) return undefined;
+	return resolveArtifactIdWidened(
+		name,
+		() => listSkills(artifacts, scopes, { text: name, projectRoot }),
+		projectRoot === undefined ? undefined : () => listSkills(artifacts, scopes, { text: name }),
+	);
+}
+
+export function registerSkillsVehicleOperations(registry: VehicleRegistry, deps: SkillsVehicleDeps): void {
+	const { artifacts, events, scopes, artifactScopes, authority, tasks } = deps;
+	const moduleOperations = new Map(skillsOperations({ artifacts, events, scopes, artifactScopes, authority }).map((op) => [op.name, op]));
+	const call = (name: string, input: Record<string, unknown>): unknown => moduleOperations.get(name)!.execute(input);
+
+	const define = (
+		action: string,
+		description: string,
+		effect: "read" | "local-write",
+		properties: Record<string, { type: string; enum?: readonly string[] }>,
+		required: readonly string[],
+		resolve: (input: Record<string, unknown>) => Record<string, unknown>,
+		execute?: (input: Record<string, unknown>) => unknown,
+	): void => {
+		const operation = defineVehicleOperation({
+			name: `skills.${action}`,
+			version: 1,
+			description,
+			input: looseObjectSchema(properties, required),
+			output: passthroughOutput,
+			permissions: ["skills:read", "skills:write"],
+			effect,
+			idempotency: { mode: effect === "read" ? "safe" : "unsafe" },
+			limits: LIMITS,
+		});
+		registry.register(OWNER, bindVehicleOperation(operation, () => async (context) => (execute ?? ((input: Record<string, unknown>) => call(`skills.${action}`, input)))(resolve(context.input))));
+	};
+
+	define(
+		"create",
+		"Creates a Skill -- a parameterized Task/Rule/Doc bundle, distinct from a prompt-only skill. project_root is optional (omitted = unscoped).",
+		"local-write",
+		{ title: stringProp, body: stringProp, trigger: stringProp, steps: { type: "array" }, tools: { type: "array" }, definition: { type: "object" }, labels: { type: "array" }, extra: { type: "object" }, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		["title"],
+		(input) => input,
+	);
+
+	define(
+		"create_template",
+		"Creates a compatibility artifact-template (defaults/required fields for a target kind), distinct from a workflow Skill.",
+		"local-write",
+		{ title: stringProp, target_kind: stringProp, defaults: { type: "object" }, required: { type: "array" }, body: stringProp, labels: { type: "array" }, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		["title", "target_kind"],
+		(input) => input,
+	);
+
+	define(
+		"list",
+		"Lists Skills matching an optional status/text filter, scoped to project_root when given.",
+		"read",
+		{ status: stringProp, text: stringProp, limit: numberProp, project_root: stringProp },
+		[],
+		(input) => input,
+	);
+
+	define(
+		"show",
+		"Shows one Skill by id or title.",
+		"read",
+		{ id: stringProp, name: stringProp, project_root: stringProp },
+		[],
+		(input) => ({ ...input, id: resolveSkillId(artifacts, artifactScopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+
+	define(
+		"invoke",
+		"Renders a Skill's own preview text with no side effects.",
+		"read",
+		{ id: stringProp, name: stringProp, project_root: stringProp },
+		[],
+		(input) => ({ ...input, id: resolveSkillId(artifacts, artifactScopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+
+	define(
+		"run",
+		"Validates arguments and atomically creates one scoped workflow run: real Tasks/Rules/Docs wired with dependsOn, one step surfacing at a time as it becomes focused -- no text dump. project_root is required here (no ambient cwd server-side); pass it explicitly.",
+		"local-write",
+		{ id: stringProp, name: stringProp, run_id: stringProp, arguments: { type: "object" }, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		["project_root"],
+		(input) => ({ ...input, id: resolveSkillId(artifacts, artifactScopes, input.project_root as string | undefined, input.id, input.name) }),
+		(input) => {
+			const run = call("skills.run", input) as WorkflowRunResult;
+			const content = buildWorkflowRunContent(artifacts, `Created Skill run ${run.runId}: ${run.created.tasks.length} tasks, ${run.created.rules.length} rules, ${run.created.docs.length} docs.`, run);
+			return { ...run, content: [content] };
+		},
+	);
+
+	define(
+		"enable",
+		"Enables a Skill.",
+		"local-write",
+		{ id: stringProp, name: stringProp, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		[],
+		(input) => ({ ...input, id: resolveSkillId(artifacts, artifactScopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+
+	define(
+		"disable",
+		"Disables a Skill.",
+		"local-write",
+		{ id: stringProp, name: stringProp, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		[],
+		(input) => ({ ...input, id: resolveSkillId(artifacts, artifactScopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+
+	define(
+		"instantiate",
+		"Instantiates a compatibility artifact-template (template_id/template_name) -- a task-target template calls tasks.create() directly; any other target creates a plain artifact. project_root is required here (no ambient cwd server-side).",
+		"local-write",
+		{ template_id: stringProp, template_name: stringProp, title: stringProp, body: stringProp, status: stringProp, labels: { type: "array" }, extra: { type: "object" }, subtype: stringProp, kind: stringProp, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		["title", "project_root"],
+		(input) => {
+			const templateId = resolveTemplateId(artifacts, artifactScopes, input.project_root as string | undefined, input.template_id, input.template_name);
+			if (!templateId) throw new Error("template_id or template_name is required");
+			return { ...input, template_id: templateId };
+		},
+		(input) => instantiateSkillOrTemplate({ artifacts, tasks, authority }, input, { actor: input.actor as string | undefined, source: input.source as string | undefined, sessionId: (input.session_id ?? input.sessionId) as string | undefined }),
+	);
+
+	define(
+		"assign_project",
+		"Reassigns a Skill's project_root, or unscopes it when project_root is omitted.",
+		"local-write",
+		{ id: stringProp, name: stringProp, project_root: stringProp },
+		[],
+		(input) => ({ ...input, id: resolveSkillId(artifacts, artifactScopes, undefined, input.id, input.name) }),
+	);
+
+	define(
+		"update",
+		"Changes a Skill's title/body/labels (at least one required). Refused for a read-only external projection.",
+		"local-write",
+		{ id: stringProp, name: stringProp, title: stringProp, body: stringProp, labels: { type: "array" }, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		[],
+		(input) => ({ ...input, id: resolveSkillId(artifacts, artifactScopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+}

package/src/vehicle/tasks-vehicle.ts

@@ -0,0 +1,407 @@
+/**
+ * Tasks projected as a real VehicleRegistry: one VehicleOperation per real action.
+ * Wraps modules/tasks.ts's operation definitions -- the largest domain (37 actions),
+ * already fully extracted server-side.
+ *
+ * tasks.focus/pause/unpause/clear_focus keep two things the raw RPC tool used to
+ * handle client-side, since neither is expressible inside a stateless Vehicle
+ * operation's own input/output contract:
+ *
+ *  - session_secret authorizes which session's Task Focus row gets mutated
+ *    (modules/tasks.ts's own guardFocusMutation). It must never be a model-visible
+ *    input field -- it travels through VehicleInvocationOptions.principal.claims,
+ *    the same mechanism playbooks.invoke uses (see vehicle-notes-client.ts).
+ *  - papyrus.task-focus.v1 is a same-process Pi extension event bus broadcast (a
+ *    token-cost router or similar can correlate its own telemetry with the
+ *    currently focused task) with no Vehicle-transport equivalent -- fired from
+ *    pi-papyrus's own onInvoked hook (see vehicle-client-pi's registerVehicleTools),
+ *    not from this module, since a remote HTTP Vehicle consumer has no such bus.
+ *
+ * remove/remove_subtree/restore are not duplicated here -- see ./artifact-trash-vehicle.ts.
+ */
+import { bindVehicleOperation, defineVehicleOperation, type VehicleOperationContext } from "@danypops/vehicle-core";
+import type { VehicleRegistry } from "@danypops/vehicle-server";
+import type { TaskExecutionPlan } from "../task-execution.ts";
+import type { TaskCompletion, Tasks } from "../task-service.ts";
+import type { TaskViewMode } from "../domain/task-scope.ts";
+import { tasksOperations } from "../modules/tasks.ts";
+import type { ArtifactStore } from "../ports/artifact-store.ts";
+import type { SessionIdentity } from "../session-identity-service.ts";
+import { labelsById, looseObjectSchema, numberProp, passthroughOutput, resolveArtifactIdWidened, stringProp } from "./artifact-vehicle-shared.ts";
+
+const OWNER = "tasks";
+const LIMITS = { defaultTimeoutMs: 5_000, maxTimeoutMs: 30_000, maxRequestBytes: 65_536, maxResponseBytes: 262_144 };
+
+const objectProp = { type: "object" } as unknown as { type: string };
+const arrayProp = { type: "array" } as unknown as { type: string };
+const boolProp = { type: "boolean" } as unknown as { type: string };
+
+export interface TasksVehicleDeps {
+	tasks: Tasks;
+	artifacts: ArtifactStore;
+	sessionIdentity: SessionIdentity;
+}
+
+/**
+ * Resolves an id from either an explicit id or a title lookup scoped to the exact
+ * same view (project_root/scope/root_task_id) a plain tasks.list call under those
+ * same filters would use -- name resolution must never search a wider or narrower
+ * scope than the caller's own view. tasks.list itself requires project_root (see
+ * modules/tasks.ts's taskFilter), so resolving by name does too: there is no
+ * ambient cwd server-side to default to, unlike the removed client-side tool.
+ *
+ * A two-task action (depend/contain) routinely names tasks that live in two
+ * different projects. When the caller didn't already pin an explicit `scope`, a
+ * miss under the narrow filter retries once against `scope: "all"` before giving
+ * up -- the same widen-once behavior the removed tool's own resolveArtifactIdByName
+ * carried, hard-won from real cross-project depend/contain friction.
+ */
+function resolveTaskId(
+	tasks: Tasks,
+	filter: { projectRoot?: string; scope?: TaskViewMode; rootTaskId?: string },
+	id: unknown,
+	name: unknown,
+): string {
+	if (typeof id === "string" && id.length > 0) return id;
+	if (typeof name !== "string" || name.length === 0) throw new Error("id or name is required");
+	if (!filter.projectRoot) throw new Error("project_root is required when resolving a task by name");
+	return resolveArtifactIdWidened(
+		name,
+		() => tasks.list({ ...filter, text: name }),
+		filter.scope === undefined ? () => tasks.list({ ...filter, scope: "all", text: name }) : undefined,
+	);
+}
+
+/** Resolves root_task_name first and scoped to "project" only, matching the removed tool's own resolution order -- every other name lookup below must see the caller's FINAL scope/root selection, which root_task_id itself feeds into. */
+function resolveRootTaskId(tasks: Tasks, projectRoot: string | undefined, rootTaskId: unknown, rootTaskName: unknown): string | undefined {
+	if (typeof rootTaskId === "string" && rootTaskId.length > 0) return rootTaskId;
+	if (typeof rootTaskName !== "string" || rootTaskName.length === 0) return undefined;
+	return resolveTaskId(tasks, { projectRoot, scope: "project" }, undefined, rootTaskName);
+}
+
+function resolveArrayField(tasks: Tasks, filter: { projectRoot?: string; scope?: TaskViewMode; rootTaskId?: string }, ids: unknown, names: unknown): string[] | undefined {
+	if (Array.isArray(ids)) return ids as string[];
+	if (!Array.isArray(names) || names.length === 0) return undefined;
+	return names.map((entry) => resolveTaskId(tasks, filter, undefined, String(entry)));
+}
+
+const readSchemaProps = { status: stringProp, text: stringProp, limit: numberProp, project_root: stringProp, scope: { type: "string", enum: ["project", "graph", "all"] }, root_task_id: stringProp, root_task_name: stringProp, session_id: stringProp, labels: arrayProp };
+
+/** Same gate/checklist narrative lines the removed tool built client-side. */
+function completionContentText(labels: Map<string, string>, result: TaskCompletion): string {
+	const gates = result.gates.map((gate) => `${gate.passed ? "✓" : "✗"} ${gate.gate.type}: ${gate.gate.target} — ${gate.output}`).join("\n");
+	const checklist = result.checklist.map((item) => `${item.accepted ? "✓" : "✗"} proof: ${item.item}${item.reason ? ` — ${item.reason}` : ""}`).join("\n");
+	const focused = result.focused ? `\nActive: ${result.focused.title} (${result.focused.id})` : "";
+	const blocked = result.blocked.length > 0
+		? `\nBlocked: ${result.blocked.map((entry) => `${entry.artifact.title} (${entry.artifact.id}) waits for ${entry.dependencyIds.map((id) => labels.get(id) ?? "unknown task").join(", ")}`).join("; ")}`
+		: "";
+	return `${result.completed ? "Completed" : "Rejected"}: ${result.artifact.title} (${result.artifact.id})${focused}${blocked}${checklist ? `\n${checklist}` : ""}${gates ? `\n${gates}` : ""}`;
+}
+
+function planContentText(plan: TaskExecutionPlan): string {
+	const byId = new Map(plan.nodes.map((node) => [node.id, node]));
+	const titleCounts = new Map<string, number>();
+	for (const node of plan.nodes) titleCounts.set(node.title, (titleCounts.get(node.title) ?? 0) + 1);
+	const nodeLabel = (id: string): string => {
+		const node = byId.get(id);
+		if (!node) return "unknown task";
+		return (titleCounts.get(node.title) ?? 0) > 1 ? `${node.title} (${node.id})` : node.title;
+	};
+	const lines = plan.layers.flatMap((layer, index) => [
+		`Layer ${index + 1}`,
+		...layer.map((id) => `  [${byId.get(id)?.state ?? "unknown"}] ${nodeLabel(id)}`),
+	]);
+	if (plan.cycleIds.length > 0) lines.push(`Invalid cycle: ${plan.cycleIds.map(nodeLabel).join(", ")}`);
+	return lines.join("\n") || "No tasks in execution plan.";
+}
+
+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);
+
+	const define = (
+		action: string,
+		description: string,
+		effect: "read" | "local-write",
+		properties: Record<string, { type: string; enum?: readonly string[] }>,
+		required: readonly string[],
+		resolve: (input: Record<string, unknown>) => Record<string, unknown>,
+		execute?: (input: Record<string, unknown>, context: VehicleOperationContext<Record<string, unknown>>) => unknown,
+	): void => {
+		const operation = defineVehicleOperation({
+			name: `tasks.${action}`,
+			version: 1,
+			description,
+			input: looseObjectSchema(properties, required),
+			output: passthroughOutput,
+			permissions: ["tasks:read", "tasks:write"],
+			effect,
+			idempotency: { mode: effect === "read" ? "safe" : "unsafe" },
+			limits: LIMITS,
+		});
+		registry.register(OWNER, bindVehicleOperation(operation, () => async (context) => (execute ?? ((input: Record<string, unknown>) => call(`tasks.${action}`, input)))(resolve(context.input), context)));
+	};
+
+	/** Shared by every action taking a single id/name: resolves root_task_name first, then name -> id against the final scope. */
+	const resolveIdAndScope = (input: Record<string, unknown>): Record<string, unknown> => {
+		const projectRoot = input.project_root as string | undefined;
+		const rootTaskId = resolveRootTaskId(tasks, projectRoot, input.root_task_id, input.root_task_name);
+		const scope = input.scope as TaskViewMode | undefined;
+		const filter = { projectRoot, scope, rootTaskId };
+		return {
+			...input,
+			...(rootTaskId ? { root_task_id: rootTaskId } : {}),
+			id: resolveTaskId(tasks, filter, input.id, input.name),
+		};
+	};
+
+	define(
+		"create",
+		"Creates a Task -- work: desired outcomes, gates, checklists, and dependencies. project_root is required (no ambient cwd server-side). Prefer parent_name/depends_on_names over parent_id/depends_on -- resolved server-side.",
+		"local-write",
+		{ title: stringProp, body: stringProp, status: stringProp, labels: arrayProp, extra: objectProp, gates: arrayProp, checklist: objectProp, template_id: stringProp, parent_id: stringProp, parent_name: stringProp, depends_on: arrayProp, depends_on_names: arrayProp, project_root: stringProp, session_id: stringProp },
+		["title", "project_root"],
+		(input) => {
+			const projectRoot = input.project_root as string;
+			const filter = { projectRoot };
+			const parentId = typeof input.parent_id === "string" && input.parent_id.length > 0 ? input.parent_id : (typeof input.parent_name === "string" && input.parent_name.length > 0 ? resolveTaskId(tasks, filter, undefined, input.parent_name) : undefined);
+			const dependsOn = resolveArrayField(tasks, filter, input.depends_on, input.depends_on_names);
+			return { ...input, ...(parentId ? { parent_id: parentId } : {}), ...(dependsOn ? { depends_on: dependsOn } : {}) };
+		},
+	);
+
+	define(
+		"update",
+		"Recovers an accidentally-terminal task via status=todo + reason, or changes title/body/labels, without rewriting real history. Never touches gates -- use set_gates.",
+		"local-write",
+		{ id: stringProp, name: stringProp, title: stringProp, body: stringProp, labels: arrayProp, status: stringProp, reason: stringProp, session_id: stringProp, project_root: stringProp },
+		[],
+		resolveIdAndScope,
+	);
+
+	define("list", "Lists Tasks matching an optional status/text/labels filter, scoped to project_root. project_root is required (no ambient cwd server-side).", "read", readSchemaProps, ["project_root"], (input) => {
+		const rootTaskId = resolveRootTaskId(tasks, input.project_root as string, input.root_task_id, input.root_task_name);
+		return { ...input, ...(rootTaskId ? { root_task_id: rootTaskId } : {}) };
+	});
+
+	define(
+		"graph",
+		"Returns the full task graph (nodes with parent/child/dependency ids) for the requested scope. project_root is required.",
+		"read",
+		readSchemaProps,
+		["project_root"],
+		(input) => {
+			const rootTaskId = resolveRootTaskId(tasks, input.project_root as string, input.root_task_id, input.root_task_name);
+			return { ...input, ...(rootTaskId ? { root_task_id: rootTaskId } : {}) };
+		},
+	);
+
+	define(
+		"plan",
+		"Projects the task graph into layered execution order (ready/blocked/invalid states, cycle detection). project_root is required.",
+		"read",
+		readSchemaProps,
+		["project_root"],
+		(input) => {
+			const rootTaskId = resolveRootTaskId(tasks, input.project_root as string, input.root_task_id, input.root_task_name);
+			return { ...input, ...(rootTaskId ? { root_task_id: rootTaskId } : {}) };
+		},
+		(input) => {
+			const plan = call("tasks.plan", input) as TaskExecutionPlan;
+			return { ...plan, content: [{ type: "text" as const, text: planContentText(plan) }] };
+		},
+	);
+
+	define("show", "Shows one Task by id or title.", "read", { id: stringProp, name: stringProp, project_root: stringProp, scope: { type: "string", enum: ["project", "graph", "all"] }, root_task_id: stringProp, root_task_name: stringProp }, [], resolveIdAndScope);
+
+	define(
+		"history",
+		"Task's append-only lifecycle event history, cursor-paginated.",
+		"read",
+		{ id: stringProp, name: stringProp, limit: numberProp, cursor: numberProp, direction: { type: "string", enum: ["asc", "desc"] }, project_root: stringProp, scope: { type: "string", enum: ["project", "graph", "all"] }, root_task_id: stringProp, root_task_name: stringProp },
+		[],
+		resolveIdAndScope,
+	);
+
+	define("scope", "Describes the current task-view scope selection for project_root.", "read", { project_root: stringProp }, ["project_root"], (input) => input);
+
+	define(
+		"set_scope",
+		"Sets the task-view scope (project/graph/all) for project_root, optionally pinned to root_task_id.",
+		"local-write",
+		{ project_root: stringProp, scope: { type: "string", enum: ["project", "graph", "all"] }, root_task_id: stringProp, root_task_name: stringProp },
+		["project_root", "scope"],
+		(input) => {
+			const rootTaskId = resolveRootTaskId(tasks, input.project_root as string, input.root_task_id, input.root_task_name);
+			return { ...input, ...(rootTaskId ? { root_task_id: rootTaskId } : {}) };
+		},
+	);
+
+	define(
+		"assign_project",
+		"Reassigns a Task's project_root.",
+		"local-write",
+		{ id: stringProp, name: stringProp, project_root: stringProp, session_id: stringProp },
+		["project_root"],
+		(input) => ({ ...input, id: resolveTaskId(tasks, { projectRoot: input.project_root as string | undefined }, input.id, input.name) }),
+	);
+
+	define("active", "The current active Task (the one being worked on) for this scope. project_root is required.", "read", readSchemaProps, ["project_root"], (input) => input);
+	define("focused", "The current focused Task and its focus status (focused/paused) for this session's scope. project_root is required.", "read", readSchemaProps, ["project_root"], (input) => input);
+
+	const focusOperation = (
+		action: "focus" | "pause" | "unpause" | "clear_focus",
+		description: string,
+		properties: Record<string, { type: string; enum?: readonly string[] }>,
+		required: readonly string[],
+		resolve: (input: Record<string, unknown>) => Record<string, unknown>,
+	): void => {
+		const operation = defineVehicleOperation({
+			name: `tasks.${action}`,
+			version: 1,
+			description,
+			input: looseObjectSchema(properties, required),
+			output: passthroughOutput,
+			permissions: ["tasks:read", "tasks:write"],
+			effect: "local-write",
+			idempotency: { mode: "unsafe" },
+			limits: LIMITS,
+		});
+		registry.register(OWNER, bindVehicleOperation(operation, () => async (context) => {
+			const claims = context.principal?.claims as { sessionId?: string; sessionSecret?: string } | undefined;
+			return call(`tasks.${action}`, { ...resolve(context.input), session_id: claims?.sessionId, session_secret: claims?.sessionSecret });
+		}));
+	};
+
+	focusOperation("focus", "Sets the active Task Focus (singular per scope) to this Task. Multiple sessions can focus the same task while only one holds its lease.", { id: stringProp, name: stringProp, project_root: stringProp }, [], (input) => ({ ...input, id: resolveTaskId(tasks, { projectRoot: input.project_root as string | undefined }, input.id, input.name) }));
+	focusOperation("pause", "Pauses the active Task Focus without clearing it.", { reason: stringProp }, [], (input) => input);
+	focusOperation("unpause", "Resumes a paused Task Focus.", {}, [], (input) => input);
+	focusOperation("clear_focus", "Clears the active Task Focus.", {}, [], (input) => input);
+
+	define("start", "Lifecycle transition: todo -> in-progress.", "local-write", { id: stringProp, name: stringProp, reason: stringProp, session_id: stringProp, project_root: stringProp }, [], resolveIdAndScope);
+	define("submit", "Lifecycle transition: in-progress -> review.", "local-write", { id: stringProp, name: stringProp, reason: stringProp, session_id: stringProp, project_root: stringProp }, [], resolveIdAndScope);
+	define("reject", "Lifecycle transition: review -> rejected.", "local-write", { id: stringProp, name: stringProp, reason: stringProp, session_id: stringProp, project_root: stringProp }, [], resolveIdAndScope);
+	define("retry", "Lifecycle transition: rejected -> in-progress.", "local-write", { id: stringProp, name: stringProp, reason: stringProp, session_id: stringProp, project_root: stringProp }, [], resolveIdAndScope);
+	define("cancel", "Lifecycle transition to canceled (terminal) from todo/in-progress/review/rejected.", "local-write", { id: stringProp, name: stringProp, reason: stringProp, session_id: stringProp, project_root: stringProp }, [], resolveIdAndScope);
+
+	define(
+		"complete",
+		"Runs gates + checklist-proof review, then focuses one deterministic ready successor without claiming effort. Rejects (not completes) on gate/checklist failure.",
+		"local-write",
+		{ id: stringProp, name: stringProp, reason: stringProp, session_id: stringProp, project_root: stringProp, scope: { type: "string", enum: ["project", "graph", "all"] }, root_task_id: stringProp, root_task_name: stringProp },
+		[],
+		resolveIdAndScope,
+		async (input) => {
+			const result = (await call("tasks.complete", input)) as TaskCompletion;
+			const dependencyIds = result.blocked.flatMap((entry) => entry.dependencyIds);
+			const labels = labelsById(artifacts, dependencyIds);
+			return { ...result, content: [{ type: "text" as const, text: completionContentText(labels, result) }] };
+		},
+	);
+
+	define(
+		"run_gates",
+		"Runs a Task's configured gates without transitioning its status -- for checking readiness before submit/complete.",
+		"read",
+		{ id: stringProp, name: stringProp, session_id: stringProp, project_root: stringProp, scope: { type: "string", enum: ["project", "graph", "all"] }, root_task_id: stringProp, root_task_name: stringProp },
+		[],
+		resolveIdAndScope,
+		async (input) => {
+			const gates = (await call("tasks.run_gates", input)) as Array<{ gate: { type: string; target: string }; passed: boolean; output: string }>;
+			const text = gates.map((gate) => `${gate.passed ? "✓" : "✗"} ${gate.gate.type}: ${gate.gate.target} — ${gate.output}`).join("\n") || "No gates configured.";
+			return { gates, content: [{ type: "text" as const, text }] };
+		},
+	);
+
+	define("set_checklist", "Replaces a Task's evidence-bearing checklist (proof requirements) in full.", "local-write", { id: stringProp, name: stringProp, checklist: objectProp, project_root: stringProp }, ["checklist"], resolveIdAndScope);
+	define("set_gates", "Replaces a Task's gate commands in full.", "local-write", { id: stringProp, name: stringProp, gates: arrayProp, project_root: stringProp }, ["gates"], resolveIdAndScope);
+
+	define(
+		"context",
+		"The full plan-reconciliation context (the system prompt itself only carries a one-line pointer) -- call explicitly after a compaction or before reconciling. project_root is required.",
+		"read",
+		readSchemaProps,
+		["project_root"],
+		(input) => ({ ...input, verbosity: "full" }),
+		(input) => {
+			const summary = call("tasks.context", input) as string | null;
+			const text = summary ?? "No open tasks.";
+			return { context: summary, content: [{ type: "text" as const, text }] };
+		},
+	);
+
+	define(
+		"cancel_subtree",
+		"Cancels a Task and its whole containment subtree in one call, skipping tasks already done/canceled.",
+		"local-write",
+		{ id: stringProp, name: stringProp, reason: stringProp, session_id: stringProp, project_root: stringProp, scope: { type: "string", enum: ["project", "graph", "all"] }, root_task_id: stringProp, root_task_name: stringProp },
+		[],
+		resolveIdAndScope,
+		(input) => {
+			const outcome = call("tasks.cancel_subtree", input) as { canceled: string[]; skipped: string[] };
+			const text = `Canceled ${outcome.canceled.length} task(s)${outcome.skipped.length > 0 ? `, skipped ${outcome.skipped.length} already-terminal` : ""}.`;
+			return { ...outcome, content: [{ type: "text" as const, text }] };
+		},
+	);
+
+	const scopeProp = { type: "string", enum: ["project", "graph", "all"] } as const;
+
+	define(
+		"depend",
+		"Adds a dependency edge (this task waits for dependency_id/dependency_name). Dependency edges form an executable DAG -- self-dependencies and cycles are rejected. A name resolved outside project_root's own scope is retried once against every project before failing, unless scope is pinned explicitly.",
+		"local-write",
+		{ id: stringProp, name: stringProp, dependency_id: stringProp, dependency_name: stringProp, project_root: stringProp, scope: scopeProp, session_id: stringProp },
+		[],
+		(input) => {
+			const filter = { projectRoot: input.project_root as string | undefined, scope: input.scope as TaskViewMode | undefined };
+			return { ...input, id: resolveTaskId(tasks, filter, input.id, input.name), dependency_id: resolveTaskId(tasks, filter, input.dependency_id, input.dependency_name) };
+		},
+	);
+
+	define(
+		"undepend",
+		"Removes a dependency edge. Idempotent -- a no-op if the edge is already absent.",
+		"local-write",
+		{ id: stringProp, name: stringProp, dependency_id: stringProp, dependency_name: stringProp, project_root: stringProp, scope: scopeProp, session_id: stringProp },
+		[],
+		(input) => {
+			const filter = { projectRoot: input.project_root as string | undefined, scope: input.scope as TaskViewMode | undefined };
+			return { ...input, id: resolveTaskId(tasks, filter, input.id, input.name), dependency_id: resolveTaskId(tasks, filter, input.dependency_id, input.dependency_name) };
+		},
+	);
+
+	define(
+		"contain",
+		"Nests a child Task inside a parent (parent_id/parent_name contains child_id/child_name) -- explicit hierarchy, distinct from depends_on execution ordering. A name resolved outside project_root's own scope is retried once against every project before failing, unless scope is pinned explicitly.",
+		"local-write",
+		{ parent_id: stringProp, parent_name: stringProp, child_id: stringProp, child_name: stringProp, project_root: stringProp, scope: scopeProp, session_id: stringProp },
+		[],
+		(input) => {
+			const filter = { projectRoot: input.project_root as string | undefined, scope: input.scope as TaskViewMode | undefined };
+			return { ...input, parent_id: resolveTaskId(tasks, filter, input.parent_id, input.parent_name), child_id: resolveTaskId(tasks, filter, input.child_id, input.child_name) };
+		},
+	);
+
+	define(
+		"uncontain",
+		"Removes a parent/child nesting. Idempotent -- a no-op if the edge is already absent.",
+		"local-write",
+		{ parent_id: stringProp, parent_name: stringProp, child_id: stringProp, child_name: stringProp, project_root: stringProp, scope: scopeProp, session_id: stringProp },
+		[],
+		(input) => {
+			const filter = { projectRoot: input.project_root as string | undefined, scope: input.scope as TaskViewMode | undefined };
+			return { ...input, parent_id: resolveTaskId(tasks, filter, input.parent_id, input.parent_name), child_id: resolveTaskId(tasks, filter, input.child_id, input.child_name) };
+		},
+	);
+
+	define("claim", "Claims this Task's lease under owner (defaults to session_id). Throws if a different owner already holds one.", "local-write", { id: stringProp, name: stringProp, owner: stringProp, ttl_ms: numberProp, note: stringProp, project_root: stringProp, session_id: stringProp }, [], (input) => ({ ...input, id: resolveTaskId(tasks, { projectRoot: input.project_root as string | undefined }, input.id, input.name), owner: input.owner ?? input.session_id }));
+	define("heartbeat_lease", "Extends this Task's lease -- needs the exact owner/token claim() returned.", "local-write", { id: stringProp, name: stringProp, owner: stringProp, token: stringProp, ttl_ms: numberProp, project_root: stringProp, session_id: stringProp }, ["owner", "token"], (input) => ({ ...input, id: resolveTaskId(tasks, { projectRoot: input.project_root as string | undefined }, input.id, input.name) }));
+	define("release_lease", "Releases this Task's lease -- needs the exact owner/token claim() returned.", "local-write", { id: stringProp, name: stringProp, owner: stringProp, token: stringProp, project_root: stringProp, session_id: stringProp }, ["owner", "token"], (input) => ({ ...input, id: resolveTaskId(tasks, { projectRoot: input.project_root as string | undefined }, input.id, input.name) }));
+	define("lease", "Shows this Task's current lease, if any.", "read", { id: stringProp, name: stringProp, project_root: stringProp }, [], (input) => ({ ...input, id: resolveTaskId(tasks, { projectRoot: input.project_root as string | undefined }, input.id, input.name) }));
+
+	define("event_feed", "Cursor-paginated feed of raw Task lifecycle events across every task, optionally filtered by event_types.", "read", { cursor: numberProp, limit: numberProp, event_types: arrayProp }, [], (input) => input);
+}
+
+/** Kept out of the registry deliberately, matching the removed tool's own ACTIONS list -- system maintenance, not an agent-facing action. Exposed via reapStale* CLI/cron paths, not a Vehicle operation. */
+export const TASKS_MAINTENANCE_OPERATIONS = ["tasks.reap_stale_focus", "tasks.reap_stale_leases"] as const;