@danypops/papyrus 0.46.2 → 0.47.0

package/README.md

@@ -46,6 +46,8 @@ Task project names are explicit registrations, never ambient-directory guesses.
 
 `tasks.create` accepts an optional `idempotency_key`. Replays with the same caller, canonical project root, key, and payload return the original response without another mutation; conflicting payload reuse is rejected. Keys are retained for seven days, isolated across callers and projects, and then expire. Retry only when reusing the exact key and payload; an unkeyed create remains unsafe to replay after an ambiguous transport failure.
 
+Task lifecycle mutations (`start`, `submit`, `reject`, `retry`, `cancel`, `reopen`, `complete`, `pause`, and `unpause`) are destination-state idempotent: repeating an already-achieved transition is a successful `changed: false` no-op and creates no duplicate history. Supply an `idempotency_key` for every mutation whose response could be lost. After an unknown outcome, call `tasks.show` and `tasks.mutation_status` with the original key, then replay only that exact operation/key if needed—never invent a new key from stale state. Completed receipts are retained for seven days; concurrent duplicate completion calls share one gate run. A genuinely incompatible transition returns typed `invalid-transition` details with current/intended status, allowed actions, and recovery guidance.
+
 Task lease responses are name-first: `tasks.claim`, `tasks.heartbeat_lease`, and `tasks.lease` return the reusable artifact alias as `taskName` plus `taskTitle`, not the backend UUID. Use `taskName` for later Task operations; retain the lease token for heartbeat or release.
 
 ### Context Mesh persistence model

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.46.2",
+  "version": "0.47.0",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],

package/src/cli/task-command.ts

@@ -102,10 +102,16 @@ const focusedCommand = buildCommand({
 
 function buildPauseUnpauseCommand(action: "pause" | "unpause") {
 	return buildCommand({
-		func: async function (this: TaskContext, flags: { sessionId?: string; sessionSecret?: string }) {
+		func: async function (this: TaskContext, flags: { sessionId?: string; sessionSecret?: string; idempotencyKey?: string }) {
 			const focus = await this.client.call<Record<string, unknown>, { artifact: CliArtifact; status: string }>(
 				`tasks.${action}` as OperationName,
-				{ actor: "user", source: "cli", session_id: flags.sessionId, session_secret: flags.sessionSecret },
+				{
+					actor: "user",
+					source: "cli",
+					session_id: flags.sessionId,
+					session_secret: flags.sessionSecret,
+					...(flags.idempotencyKey ? { idempotency_key: flags.idempotencyKey } : {}),
+				},
 			);
 			render.call(this, focus, `Focused (${focus.status}): ${artifactLabel(focus.artifact)}`);
 		},
@@ -119,6 +125,13 @@ function buildPauseUnpauseCommand(action: "pause" | "unpause") {
 					placeholder: "secret",
 					optional: true,
 				},
+				idempotencyKey: {
+					brief: "Retry key for this exact mutation",
+					kind: "parsed",
+					parse: String,
+					placeholder: "key",
+					optional: true,
+				},
 			},
 		},
 		docs: { brief: `${action === "pause" ? "Pause" : "Resume"} the active Task Focus` },
@@ -307,6 +320,21 @@ const eventFeedCommand = buildCommand({
 	docs: { brief: "Feed of raw Task lifecycle events across every task" },
 });
 
+const mutationStatusCommand = buildCommand({
+	func: async function (this: TaskContext, _flags: Record<string, never>, idempotencyKey: string) {
+		const receipt = await this.client.call<Record<string, unknown>, { receiptId: string; operation: string; state: string }>(
+			"tasks.mutation_status",
+			{ idempotency_key: idempotencyKey },
+		);
+		render.call(this, receipt, `${receipt.operation}: ${receipt.state} (${receipt.receiptId})`);
+	},
+	parameters: {
+		flags: {},
+		positional: { kind: "tuple", parameters: [{ brief: "Original idempotency key", parse: String, placeholder: "key" }] },
+	},
+	docs: { brief: "Resolve an unknown Task lifecycle mutation outcome" },
+});
+
 // -- CRUD -----------------------------------------------------------------------------------
 
 const createCommand = buildCommand({
@@ -788,12 +816,13 @@ const planCommand = buildCommand({
 });
 
 const completeCommand = buildCommand({
-	func: async function (this: TaskContext, flags: { sessionId?: string }, id: string) {
+	func: async function (this: TaskContext, flags: { sessionId?: string; idempotencyKey?: string }, id: string) {
 		const completion = await this.client.call<Record<string, unknown>, CliCompletion>("tasks.complete", {
 			id,
 			actor: "user",
 			source: "cli",
 			session_id: flags.sessionId,
+			...(flags.idempotencyKey ? { idempotency_key: flags.idempotencyKey } : {}),
 		});
 		const lines = [`${completion.completed ? "Completed" : "Rejected"}: ${artifactLabel(completion.artifact)}`];
 		if (completion.focused) lines.push(`Active: ${artifactLabel(completion.focused)}`);
@@ -806,24 +835,31 @@ const completeCommand = buildCommand({
 		render.call(this, completion, lines.join("\n"));
 	},
 	parameters: {
-		flags: { sessionId: { brief: "Scope to one agent session", kind: "parsed", parse: String, placeholder: "id", optional: true } },
+		flags: {
+			sessionId: { brief: "Scope to one agent session", kind: "parsed", parse: String, placeholder: "id", optional: true },
+			idempotencyKey: { brief: "Retry key for this exact mutation", kind: "parsed", parse: String, placeholder: "key", optional: true },
+		},
 		positional: { kind: "tuple", parameters: [{ brief: "Task id", parse: String, placeholder: "id" }] },
 	},
 	docs: { brief: "Run gates and checklist review, then complete" },
 });
 
 const startCommand = buildCommand({
-	func: async function (this: TaskContext, flags: { sessionId?: string }, id: string) {
+	func: async function (this: TaskContext, flags: { sessionId?: string; idempotencyKey?: string }, id: string) {
 		const artifact = await this.client.call<Record<string, unknown>, CliArtifact>("tasks.start", {
 			id,
 			actor: "user",
 			source: "cli",
 			session_id: flags.sessionId,
+			...(flags.idempotencyKey ? { idempotency_key: flags.idempotencyKey } : {}),
 		});
 		render.call(this, artifact, `Started: ${artifactLabel(artifact)}`);
 	},
 	parameters: {
-		flags: { sessionId: { brief: "Scope to one agent session", kind: "parsed", parse: String, placeholder: "id", optional: true } },
+		flags: {
+			sessionId: { brief: "Scope to one agent session", kind: "parsed", parse: String, placeholder: "id", optional: true },
+			idempotencyKey: { brief: "Retry key for this exact mutation", kind: "parsed", parse: String, placeholder: "key", optional: true },
+		},
 		positional: { kind: "tuple", parameters: [{ brief: "Task id", parse: String, placeholder: "id" }] },
 	},
 	docs: { brief: "Lifecycle transition: todo -> in-progress" },
@@ -831,17 +867,21 @@ const startCommand = buildCommand({
 
 function buildSimpleTransitionCommand(action: "submit" | "reject" | "retry" | "cancel" | "reopen", brief: string) {
 	return buildCommand({
-		func: async function (this: TaskContext, flags: { sessionId?: string }, id: string) {
+		func: async function (this: TaskContext, flags: { sessionId?: string; idempotencyKey?: string }, id: string) {
 			const artifact = await this.client.call<Record<string, unknown>, CliArtifact>(`tasks.${action}` as OperationName, {
 				id,
 				actor: "user",
 				source: "cli",
 				session_id: flags.sessionId,
+				...(flags.idempotencyKey ? { idempotency_key: flags.idempotencyKey } : {}),
 			});
 			render.call(this, artifact, `${action[0]!.toUpperCase()}${action.slice(1)}: ${artifactLabel(artifact)}`);
 		},
 		parameters: {
-			flags: { sessionId: { brief: "Scope to one agent session", kind: "parsed", parse: String, placeholder: "id", optional: true } },
+			flags: {
+				sessionId: { brief: "Scope to one agent session", kind: "parsed", parse: String, placeholder: "id", optional: true },
+				idempotencyKey: { brief: "Retry key for this exact mutation", kind: "parsed", parse: String, placeholder: "key", optional: true },
+			},
 			positional: { kind: "tuple", parameters: [{ brief: "Task id", parse: String, placeholder: "id" }] },
 		},
 		docs: { brief },
@@ -920,6 +960,7 @@ const app = buildApplication(
 			lease: leaseCommand,
 			"reap-stale-leases": reapStaleLeasesCommand,
 			"event-feed": eventFeedCommand,
+			"mutation-status": mutationStatusCommand,
 			create: createCommand,
 			list: listCommand,
 			show: showCommand,

package/src/cli.ts

@@ -162,8 +162,8 @@ const USAGE = `Usage:
   papyrus tasks graph [--session-id <id>] [--json]
   papyrus tasks active [--session-id <id>] [--json]
   papyrus tasks focused [--session-id <id>] [--json]
-  papyrus tasks pause [--session-id <id>] [--session-secret <secret>] [--json]
-  papyrus tasks unpause [--session-id <id>] [--session-secret <secret>] [--json]
+  papyrus tasks pause [--session-id <id>] [--session-secret <secret>] [--idempotency-key <key>] [--json]
+  papyrus tasks unpause [--session-id <id>] [--session-secret <secret>] [--idempotency-key <key>] [--json]
   papyrus tasks clear-focus [--session-id <id>] [--session-secret <secret>] [--json]
   papyrus tasks reap-stale-focus [--json]
   papyrus tasks claim <id> --owner <owner> [--ttl-ms <ms>] [--note <text>] [--json]
@@ -172,17 +172,19 @@ const USAGE = `Usage:
   papyrus tasks lease <id> [--json]
   papyrus tasks reap-stale-leases [--json]
   papyrus tasks event-feed [--cursor <n>] [--limit <n>] [--event-types-json <json>] [--json]
+  papyrus tasks mutation-status <idempotency-key> [--json]
   papyrus tasks history <id> [--json]
   papyrus tasks scope [project|all|graph <root-id>] [--json]
   papyrus tasks assign-project <id> [project-root] [--json]
   papyrus tasks focus <id> [--session-id <id>] [--session-secret <secret>] [--json]
   papyrus tasks update <id> [--title <title>] [--body <body>] [--labels-json <json>] [--status todo --reason <reason>] [--json]
-  papyrus tasks complete <id> [--session-id <id>] [--json]
-  papyrus tasks start <id> [--session-id <id>] [--json]
-  papyrus tasks submit <id> [--session-id <id>] [--json]
-  papyrus tasks reject <id> [--session-id <id>] [--json]
-  papyrus tasks retry <id> [--session-id <id>] [--json]
-  papyrus tasks cancel <id> [--session-id <id>] [--json]
+  papyrus tasks complete <id> [--session-id <id>] [--idempotency-key <key>] [--json]
+  papyrus tasks start <id> [--session-id <id>] [--idempotency-key <key>] [--json]
+  papyrus tasks submit <id> [--session-id <id>] [--idempotency-key <key>] [--json]
+  papyrus tasks reject <id> [--session-id <id>] [--idempotency-key <key>] [--json]
+  papyrus tasks retry <id> [--session-id <id>] [--idempotency-key <key>] [--json]
+  papyrus tasks cancel <id> [--session-id <id>] [--idempotency-key <key>] [--json]
+  papyrus tasks reopen <id> [--session-id <id>] [--idempotency-key <key>] [--json]
   papyrus tasks cancel-subtree <id> [--session-id <id>] [--json]
   papyrus tasks depend <id> <prerequisite-id> [--reason <reason>] [--session-id <id>] [--json]
   papyrus tasks undepend <id> <prerequisite-id> [--reason <reason>] [--session-id <id>] [--json]

package/src/constants.ts

@@ -9,7 +9,7 @@ export const DAEMON_PROBE_TIMEOUT_MS = 800;
 export const DAEMON_UNIT_NAME = "papyrus.service";
 export const DAEMON_DIR_ENV = "PAPYRUS_DAEMON_DIR";
 export const SQLITE_BUSY_TIMEOUT_MS = 5_000;
-export const SQLITE_SCHEMA_VERSION = 26;
+export const SQLITE_SCHEMA_VERSION = 27;
 export const SERVICE_MAX_BODY_BYTES = 1_048_576;
 
 export const WAL_CHECKPOINT_INTERVAL_MS = 60_000;
@@ -267,6 +267,8 @@ export const TASK_PROJECT_ALIAS_MAX_COUNT = 20;
 export const TASK_PROJECT_LIST_MAX_RESULTS = 100;
 export const TASK_CREATE_IDEMPOTENCY_KEY_MAX_LENGTH = 200;
 export const TASK_CREATE_IDEMPOTENCY_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+export const TASK_MUTATION_IDEMPOTENCY_KEY_MAX_LENGTH = 200;
+export const TASK_MUTATION_IDEMPOTENCY_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
 export const GRAPH_RENDER_PADDING_X = 2;
 export const GRAPH_RENDER_PADDING_Y = 1;
 export const GRAPH_RENDER_BOX_PADDING = 0;

package/src/db.ts

@@ -176,6 +176,24 @@ CREATE TABLE IF NOT EXISTS task_create_requests (
 	PRIMARY KEY (request_scope, idempotency_key)
 );
 CREATE INDEX IF NOT EXISTS task_create_requests_expiry_idx ON task_create_requests(expires_at);
+CREATE TABLE IF NOT EXISTS task_mutation_requests (
+	request_scope   TEXT NOT NULL,
+	idempotency_key TEXT NOT NULL,
+	receipt_id      TEXT NOT NULL UNIQUE,
+	task_id         TEXT REFERENCES artifacts(id) ON DELETE CASCADE,
+	operation       TEXT NOT NULL,
+	request_hash    TEXT NOT NULL,
+	state           TEXT NOT NULL CHECK (state IN ('pending', 'completed')),
+	response_json   TEXT,
+	created_at      TEXT NOT NULL,
+	updated_at      TEXT NOT NULL,
+	expires_at      TEXT NOT NULL,
+	PRIMARY KEY (request_scope, idempotency_key),
+	CHECK ((state = 'pending' AND response_json IS NULL) OR (state = 'completed' AND response_json IS NOT NULL))
+);
+CREATE INDEX IF NOT EXISTS task_mutation_requests_expiry_idx ON task_mutation_requests(expires_at);
+CREATE UNIQUE INDEX IF NOT EXISTS task_mutation_requests_pending_task_operation_idx
+	ON task_mutation_requests(task_id, operation) WHERE state = 'pending' AND task_id IS NOT NULL;
 CREATE TABLE IF NOT EXISTS artifact_events (
 	id                   INTEGER PRIMARY KEY AUTOINCREMENT,
 	artifact_id          TEXT NOT NULL REFERENCES artifacts(id),
@@ -799,6 +817,32 @@ const FUTURE_MIGRATIONS: ReadonlyArray<PapyrusMigration> = [
 			}
 		},
 	},
+	{
+		version: 27,
+		name: "task-lifecycle-mutation-receipts",
+		up: (db) => {
+			db.exec(`
+				CREATE TABLE IF NOT EXISTS task_mutation_requests (
+					request_scope   TEXT NOT NULL,
+					idempotency_key TEXT NOT NULL,
+					receipt_id      TEXT NOT NULL UNIQUE,
+					task_id         TEXT REFERENCES artifacts(id) ON DELETE CASCADE,
+					operation       TEXT NOT NULL,
+					request_hash    TEXT NOT NULL,
+					state           TEXT NOT NULL CHECK (state IN ('pending', 'completed')),
+					response_json   TEXT,
+					created_at      TEXT NOT NULL,
+					updated_at      TEXT NOT NULL,
+					expires_at      TEXT NOT NULL,
+					PRIMARY KEY (request_scope, idempotency_key),
+					CHECK ((state = 'pending' AND response_json IS NULL) OR (state = 'completed' AND response_json IS NOT NULL))
+				);
+				CREATE INDEX IF NOT EXISTS task_mutation_requests_expiry_idx ON task_mutation_requests(expires_at);
+				CREATE UNIQUE INDEX IF NOT EXISTS task_mutation_requests_pending_task_operation_idx
+					ON task_mutation_requests(task_id, operation) WHERE state = 'pending' AND task_id IS NOT NULL;
+			`);
+		},
+	},
 ];
 
 /**

package/src/domain-service-shared.ts

@@ -107,9 +107,8 @@ export type TransitionTable<Action extends string, Status extends string> = Reco
 /**
  * The from/to-table lookup+validation half of a transition, split out from runTransition
  * (below) so a caller with its own side effects gated on "is this action even valid from the
- * current status" (e.g. Tasks.transition's dependency-blocking check and focus-store
- * bookkeeping, which must run -- or not -- before the status write itself) can call this
- * directly instead of duplicating the same lookup+throw three times. Every other caller
+ * current status" can call this directly instead of duplicating the same lookup+throw.
+ * Task lifecycle now uses its richer retry-safe transition primitive instead. Every other caller
  * (Document/Rule/Playbook, none of which have that ordering constraint) uses runTransition
  * instead, which does this same check plus the write in one call.
  */

package/src/handlers/tasks.ts

@@ -19,17 +19,25 @@
  *
  * remove/remove_subtree/restore are not duplicated here -- see ./artifact-trash-vehicle.ts.
  */
-import { VehicleError, type VehicleLimits } from "@danypops/vehicle-core";
+import { VehicleError, type VehicleLimits, type VehicleOperationContext } from "@danypops/vehicle-core";
 import type { VehicleRegistry } from "@danypops/vehicle-server";
 import type { ArtifactStore } from "../artifact/artifact-store.ts";
-import { GATE_TIMEOUT_MAX_MS, TASK_CREATE_IDEMPOTENCY_KEY_MAX_LENGTH } from "../constants.ts";
+import { GATE_TIMEOUT_MAX_MS, TASK_CREATE_IDEMPOTENCY_KEY_MAX_LENGTH, TASK_MUTATION_IDEMPOTENCY_KEY_MAX_LENGTH } from "../constants.ts";
 import { PROOF_TYPES } from "../domain/checklist.ts";
 import { GATE_TYPES } from "../domain/gate.ts";
 import type { TaskViewMode } from "../domain/task-scope.ts";
 import { tasksOperations } from "../modules/tasks.ts";
 import type { SessionIdentity } from "../session-identity/session-identity-service.ts";
+import { TaskMutationIdempotencyConflictError, TaskMutationPendingError } from "../stores/task-mutation-request-store.ts";
 import type { TaskExecutionPlan } from "../task/task-execution.ts";
-import { type TaskCompletion, TaskProjectAmbiguousError, TaskProjectNotFoundError, type Tasks } from "../task/task-service.ts";
+import {
+	type TaskCompletion,
+	TaskInvalidTransitionError,
+	TaskMutationReceiptNotFoundError,
+	TaskProjectAmbiguousError,
+	TaskProjectNotFoundError,
+	type Tasks,
+} from "../task/task-service.ts";
 import {
 	booleanProp,
 	classifySessionAuthorization,
@@ -75,6 +83,13 @@ const GATE_OPERATION_LIMITS: VehicleLimits = {
 const objectProp = { type: "object" } as const;
 const arrayProp = { type: "array" } as const;
 const _boolProp = { type: "boolean" } as const;
+const mutationIdempotencyProp = {
+	type: "string",
+	minLength: 1,
+	maxLength: TASK_MUTATION_IDEMPOTENCY_KEY_MAX_LENGTH,
+	description:
+		"Retry key for this exact mutation. Reuse the same key after an unknown outcome; inspect mutation_status before choosing a new action.",
+} as const;
 
 const gateProp = {
 	type: "array",
@@ -251,13 +266,58 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 	 * 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 throwLifecycleError = (error: unknown): never => {
+		if (error instanceof TaskInvalidTransitionError) {
+			throw new VehicleError("invalid-transition", error.message, {
+				category: "conflict",
+				details: {
+					operation: error.operation,
+					currentStatus: error.currentStatus,
+					intendedStatus: error.intendedStatus,
+					allowedActions: [...error.allowedActions],
+					recovery: error.recovery,
+				},
+			});
+		}
+		if (error instanceof TaskMutationIdempotencyConflictError) {
+			throw new VehicleError("idempotency-key-conflict", error.message, { category: "conflict" });
+		}
+		if (error instanceof TaskMutationPendingError) {
+			throw new VehicleError("mutation-pending", error.message, {
+				category: "conflict",
+				details: { receiptId: error.receiptId, operation: error.operation },
+			});
+		}
+		if (error instanceof TaskMutationReceiptNotFoundError) {
+			throw new VehicleError("mutation-receipt-not-found", error.message, { category: "not_found" });
+		}
+		throw error;
+	};
+	const classifyLifecycle = <T>(run: () => T): T => {
+		try {
+			const result = run();
+			return result instanceof Promise ? (result.catch(throwLifecycleError) as T) : result;
+		} catch (error) {
+			return throwLifecycleError(error);
+		}
+	};
 	const call = (name: string, input: Record<string, unknown>): unknown =>
 		classifySessionAuthorization(() =>
 			classifyTaskCreateIdempotency(() =>
-				classifyTaskExecutionBounds(() => classifyTaskDependencyCycles(() => moduleOperations.get(name)!.execute(input))),
+				classifyTaskExecutionBounds(() =>
+					classifyTaskDependencyCycles(() => classifyLifecycle(() => moduleOperations.get(name)!.execute(input))),
+				),
 			),
 		);
 	const define = createOperationDefiner(registry, OWNER, "tasks", ["tasks:read", "tasks:write"], call);
+	const mutationInput = (
+		input: Record<string, unknown>,
+		context: VehicleOperationContext<Record<string, unknown>>,
+	): Record<string, unknown> => ({
+		...input,
+		idempotency_key: input.idempotency_key ?? context.idempotencyKey,
+		idempotency_caller: context.principal?.id ?? "anonymous",
+	});
 
 	const resolveProject = (reference: string) => {
 		try {
@@ -522,7 +582,8 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 	): void => {
 		define(action, description, "local-write", properties, required, resolve, (resolvedInput, context) => {
 			const claims = context.principal?.claims as { sessionId?: string; sessionSecret?: string } | undefined;
-			return call(`tasks.${action}`, { ...resolvedInput, session_id: claims?.sessionId, session_secret: claims?.sessionSecret });
+			const operationInput = action === "pause" || action === "unpause" ? mutationInput(resolvedInput, context) : resolvedInput;
+			return call(`tasks.${action}`, { ...operationInput, session_id: claims?.sessionId, session_secret: claims?.sessionSecret });
 		});
 	};
 
@@ -536,63 +597,67 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 			id: resolveTaskId(artifacts, 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 },
+	focusOperation(
+		"pause",
+		"Pauses Task Focus. Destination-state idempotent: replaying after success returns changed=false. Reuse idempotency_key after an unknown outcome.",
+		{ reason: stringProp, idempotency_key: mutationIdempotencyProp },
 		[],
-		resolveIdAndScope,
+		(input) => input,
 	);
-	define(
-		"cancel",
-		"Lifecycle transition to canceled (terminal) from todo/in-progress/review/rejected. Reversible via tasks.reopen if this turns out to be premature.",
-		"local-write",
-		{ id: stringProp, name: stringProp, reason: stringProp, session_id: stringProp, project_root: stringProp },
+	focusOperation(
+		"unpause",
+		"Resumes paused Task Focus. Destination-state idempotent: replaying after success returns changed=false. Reuse idempotency_key after an unknown outcome.",
+		{ idempotency_key: mutationIdempotencyProp },
 		[],
-		resolveIdAndScope,
+		(input) => input,
 	);
+	focusOperation("clear_focus", "Clears the active Task Focus.", {}, [], (input) => input);
 
-	define(
-		"reopen",
-		"Lifecycle transition: canceled -> todo. For a task legitimately canceled through a normal transition (e.g. a deliberate pause/park) that should resume -- distinct from tasks.update's status:todo path, which only recovers a task that was terminal at its own creation (a caller mistake), never one canceled/rejected later.",
-		"local-write",
-		{ id: stringProp, name: stringProp, reason: stringProp, session_id: stringProp, project_root: stringProp },
-		[],
-		resolveIdAndScope,
+	const transitionOperation = (action: "start" | "submit" | "reject" | "retry" | "cancel" | "reopen", description: string): void =>
+		define(
+			action,
+			`${description} Destination-state idempotent: a replay after success returns changed=false. After an unknown outcome, call tasks.show and mutation_status, then reuse the SAME idempotency_key; never retry with a new key from stale state.`,
+			"local-write",
+			{
+				id: stringProp,
+				name: stringProp,
+				reason: stringProp,
+				session_id: stringProp,
+				project_root: stringProp,
+				idempotency_key: mutationIdempotencyProp,
+			},
+			[],
+			resolveIdAndScope,
+			(input, context) => {
+				const result = call(`tasks.${action}`, mutationInput(input, context)) as {
+					title: string;
+					status: string;
+					changed: boolean;
+					receiptId?: string;
+					replayed?: boolean;
+				};
+				const text = result.changed
+					? `${result.title} transitioned to ${result.status}.`
+					: result.replayed
+						? `Recovered the prior ${action} receipt for ${result.title}; call tasks.show to confirm its current status before the next action.`
+						: `${result.title} was already ${result.status}; replay was a safe no-op.`;
+				return { ...result, content: [{ type: "text" as const, text }] };
+			},
+		);
+
+	transitionOperation("start", "Lifecycle transition: todo -> in-progress.");
+	transitionOperation("submit", "Lifecycle transition: in-progress -> review.");
+	transitionOperation("reject", "Lifecycle transition: review -> rejected.");
+	transitionOperation("retry", "Lifecycle transition: rejected -> in-progress.");
+	transitionOperation(
+		"cancel",
+		"Lifecycle transition to canceled (terminal) from todo/in-progress/review/rejected. Reversible via tasks.reopen if premature.",
 	);
+	transitionOperation("reopen", "Lifecycle transition: canceled -> todo for work that should resume.");
 
 	define(
 		"complete",
-		"Runs gates + checklist-proof review, then focuses one deterministic ready successor without claiming effort. Rejects (not completes) on gate/checklist failure.",
+		"Runs gates + checklist-proof review, then focuses one deterministic ready successor without claiming effort. Rejects on gate/checklist failure. Reuse the same idempotency_key after an unknown outcome so gates and history are not run twice; inspect mutation_status before choosing a new action. A replay after done is a changed=false no-op.",
 		"local-write",
 		{
 			id: stringProp,
@@ -603,11 +668,12 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 			scope: { type: "string", enum: ["project", "graph", "all"] },
 			root_task_id: stringProp,
 			root_task_name: stringProp,
+			idempotency_key: mutationIdempotencyProp,
 		},
 		[],
 		resolveIdAndScope,
-		async (input) => {
-			const result = (await call("tasks.complete", input)) as TaskCompletion;
+		async (input, context) => {
+			const result = (await call("tasks.complete", mutationInput(input, context))) 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) }] };
@@ -615,6 +681,16 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 		GATE_OPERATION_LIMITS,
 	);
 
+	define(
+		"mutation_status",
+		"Resolves an unknown lifecycle mutation outcome by the original idempotency_key. Read this receipt before selecting another transition; never invent a replacement key for the same attempt.",
+		"read",
+		{ idempotency_key: mutationIdempotencyProp },
+		["idempotency_key"],
+		(input) => input,
+		(input, context) => call("tasks.mutation_status", mutationInput(input, context)),
+	);
+
 	define(
 		"run_gates",
 		"Runs a Task's configured gates without transitioning its status -- for checking readiness before submit/complete.",

package/src/id-migration.ts

@@ -54,6 +54,7 @@ const FK_COLUMNS: ReadonlyArray<{ table: string; column: string }> = [
 	{ table: "task_events", column: "task_id" },
 	{ table: "task_scopes", column: "task_id" },
 	{ table: "task_views", column: "root_task_id" },
+	{ table: "task_mutation_requests", column: "task_id" },
 	{ table: "artifact_events", column: "artifact_id" },
 	{ table: "artifact_events", column: "related_id" },
 ];
@@ -68,6 +69,7 @@ const TEXT_SCAN_COLUMNS: ReadonlyArray<{ table: string; column: string }> = [
 	{ table: "artifacts", column: "extra" },
 	{ table: "task_events", column: "reason" },
 	{ table: "task_events", column: "evidence_json" },
+	{ table: "task_mutation_requests", column: "response_json" },
 ];
 
 /** Audit tables whose append-only guard must be suspended for exactly this migration's duration. */

package/src/index.ts

@@ -35,4 +35,12 @@ export { taskContext } from "./task/task-context.ts";
 export { projectTaskExecution, type TaskExecutionPlan, type TaskExecutionState } from "./task/task-execution.ts";
 export { projectTaskGraph, type TaskGraphView } from "./task/task-graph-view.ts";
 export { fallbackLabel, projectTaskRelationships } from "./task/task-relationship-view.ts";
-export type { TaskCompletion, TaskGraph, TaskNode, TaskStatus } from "./task/task-service.ts";
+export type {
+	TaskCompletion,
+	TaskGraph,
+	TaskLifecycleMutationResult,
+	TaskMutationReceiptView,
+	TaskNode,
+	TaskStatus,
+} from "./task/task-service.ts";
+export { TaskInvalidTransitionError, TaskMutationReceiptNotFoundError } from "./task/task-service.ts";