@danypops/papyrus 0.44.12 → 0.45.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.44.12",
+  "version": "0.45.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

@@ -747,7 +747,7 @@ const startCommand = buildCommand({
 	docs: { brief: "Lifecycle transition: todo -> in-progress" },
 });
 
-function buildSimpleTransitionCommand(action: "submit" | "reject" | "retry" | "cancel", brief: string) {
+function buildSimpleTransitionCommand(action: "submit" | "reject" | "retry" | "cancel" | "reopen", brief: string) {
 	return buildCommand({
 		func: async function (this: TaskContext, flags: { sessionId?: string }, id: string) {
 			const artifact = await this.client.call<Record<string, unknown>, CliArtifact>(`tasks.${action}` as OperationName, {
@@ -868,6 +868,7 @@ const app = buildApplication(
 			reject: buildSimpleTransitionCommand("reject", "Lifecycle transition: review -> rejected"),
 			retry: buildSimpleTransitionCommand("retry", "Lifecycle transition: rejected -> in-progress"),
 			cancel: buildSimpleTransitionCommand("cancel", "Lifecycle transition to canceled"),
+			reopen: buildSimpleTransitionCommand("reopen", "Lifecycle transition: canceled -> todo"),
 			"cancel-subtree": cancelSubtreeCommand,
 			depend: buildDependencyCommand(
 				"tasks.depend",

package/src/domain/task-event.ts

@@ -26,6 +26,7 @@ export const TASK_EVENT_TYPES = [
 	"retried",
 	"completed",
 	"canceled",
+	"reopened",
 	"dependency_added",
 	"dependency_removed",
 	"containment_added",

package/src/handlers/discuss.ts

@@ -17,6 +17,7 @@ import type { VehicleContentBlock } from "@danypops/vehicle-core";
 import type { VehicleRegistry } from "@danypops/vehicle-server";
 import type { Artifact } from "../artifact/artifact.ts";
 import type { ArtifactStore } from "../artifact/artifact-store.ts";
+import { DISCUSSION_OPTION_DESCRIPTION_MAX_LENGTH, DISCUSSION_OPTION_MAX_LENGTH, DISCUSSION_OPTIONS_MAX_COUNT } from "../constants.ts";
 import type { DiscussionAndRounds, Discussions } from "../discussion/discussion-service.ts";
 import { DISCUSSION_SUBTYPE, type DiscussionRound } from "../domain/discussion.ts";
 import { discussOperations } from "../modules/discuss.ts";
@@ -118,6 +119,16 @@ function defaultActorToAgent(input: Record<string, unknown>): void {
 
 const optionsUnionSchema = { type: "array" } as const;
 
+/**
+ * Shared suffix for open/reply's own description -- interpolates the real, enforced bounds
+ * (domain/discussion.ts's validateDiscussionOptions) rather than a hand-typed number that can
+ * silently drift out of sync with the actual limit. A prior version of this description stated
+ * the option count bound but not the per-option/per-description character bound at all --
+ * confirmed live: a caller had no way to know a 250-character description would be rejected
+ * until it already had been (see discuss-vehicle.test.ts's oversized-description regression).
+ */
+const OPTION_BOUNDS_TEXT = `Each option is at most ${DISCUSSION_OPTION_MAX_LENGTH} characters (up to ${DISCUSSION_OPTIONS_MAX_COUNT} total); each description is at most ${DISCUSSION_OPTION_DESCRIPTION_MAX_LENGTH} characters.`;
+
 export function registerDiscussVehicleOperations(registry: VehicleRegistry, discussions: Discussions, artifacts: ArtifactStore): void {
 	const moduleOperations = new Map(discussOperations(discussions).map((op) => [op.name, op]));
 	const call = <Output>(name: string, input: Record<string, unknown>): Output => moduleOperations.get(name)!.execute(input) as Output;
@@ -152,7 +163,7 @@ export function registerDiscussVehicleOperations(registry: VehicleRegistry, disc
 
 	define(
 		"open",
-		"Opens a new Discussion and starts round 1. Optionally poses a structured choice via options (2-10 entries) + options_mode ('single' mutually exclusive, 'multi' allows several) -- each option a bare string (self-evident) or {title, description} (a real tradeoff worth spelling out; description REQUIRED once there are 3+ options). Optionally blocks one or more Tasks immediately via blocks_task_ids/blocks_task_names. Pass live:true to get a human's answer synchronously in this same call, via an interactive prompt -- only takes effect with an interactive UI available, otherwise degrades silently to the normal durably-recorded round.",
+		`Opens a new Discussion and starts round 1. Optionally poses a structured choice via options (2-10 entries) + options_mode ('single' mutually exclusive, 'multi' allows several) -- each option a bare string (self-evident) or {title, description} (a real tradeoff worth spelling out; description REQUIRED once there are 3+ options). ${OPTION_BOUNDS_TEXT} Optionally blocks one or more Tasks immediately via blocks_task_ids/blocks_task_names. Pass live:true to get a human's answer synchronously in this same call, via an interactive prompt -- only takes effect with an interactive UI available, otherwise degrades silently to the normal durably-recorded round.`,
 		"local-write",
 		{
 			title: stringProp,
@@ -182,7 +193,7 @@ export function registerDiscussVehicleOperations(registry: VehicleRegistry, disc
 
 	define(
 		"reply",
-		"Adds a round to an existing Discussion. Refused once deferred or settled -- resume first. Answers a currently pending posed choice via `selected` (validated against it), or poses a new choice via options/options_mode. Prefer `name` over `id`. Pass live:true to get a human's answer synchronously in this same call, via the pending choice's picker if one was posed, otherwise a freeform question -- only takes effect with an interactive UI available, otherwise degrades silently to the normal durably-recorded round.",
+		`Adds a round to an existing Discussion. Refused once deferred or settled -- resume first. Answers a currently pending posed choice via \`selected\` (validated against it), or poses a new choice via options/options_mode. ${OPTION_BOUNDS_TEXT} Prefer \`name\` over \`id\`. Pass live:true to get a human's answer synchronously in this same call, via the pending choice's picker if one was posed, otherwise a freeform question -- only takes effect with an interactive UI available, otherwise degrades silently to the normal durably-recorded round.`,
 		"local-write",
 		{
 			id: stringProp,

package/src/handlers/tasks.ts

@@ -244,7 +244,7 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 
 	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.",
+		"Recovers an accidentally-terminal task via status=todo + reason (only a task whose status was terminal at its own creation -- not one that reached canceled/rejected through a real, later transition; use tasks.reopen for that), or changes title/body/labels, without rewriting real history. Never touches gates -- use set_gates.",
 		"local-write",
 		{
 			id: stringProp,
@@ -453,7 +453,16 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 	);
 	define(
 		"cancel",
-		"Lifecycle transition to canceled (terminal) from todo/in-progress/review/rejected.",
+		"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 },
+		[],
+		resolveIdAndScope,
+	);
+
+	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 },
 		[],

package/src/modules/tasks.ts

@@ -86,6 +86,7 @@ export const TASKS_OPERATION_NAMES = [
 	"tasks.reject",
 	"tasks.retry",
 	"tasks.cancel",
+	"tasks.reopen",
 	"tasks.cancel_subtree",
 	"tasks.depend",
 	"tasks.undepend",
@@ -201,6 +202,7 @@ export function tasksOperations(tasks: Tasks, artifacts: ArtifactStore, sessionI
 		define("tasks.reject", (input: OperationInput) => tasks.transition(string(input, "id"), "reject", eventContext(input))),
 		define("tasks.retry", (input: OperationInput) => tasks.transition(string(input, "id"), "retry", eventContext(input))),
 		define("tasks.cancel", (input: OperationInput) => tasks.transition(string(input, "id"), "cancel", eventContext(input))),
+		define("tasks.reopen", (input: OperationInput) => tasks.transition(string(input, "id"), "reopen", eventContext(input))),
 		define("tasks.cancel_subtree", (input: OperationInput) => tasks.cancelSubtree(string(input, "id"), eventContext(input))),
 		define("tasks.depend", (input: OperationInput) =>
 			tasks.depend(string(input, "id"), string(input, "dependency_id"), eventContext(input)),

package/src/service.ts

@@ -371,6 +371,7 @@ function handlers(
 		"tasks.reject": forwardToModule("tasks.reject"),
 		"tasks.retry": forwardToModule("tasks.retry"),
 		"tasks.cancel": forwardToModule("tasks.cancel"),
+		"tasks.reopen": forwardToModule("tasks.reopen"),
 		"tasks.cancel_subtree": forwardToModule("tasks.cancel_subtree"),
 		"tasks.depend": forwardToModule("tasks.depend"),
 		"tasks.undepend": forwardToModule("tasks.undepend"),

package/src/task/task-service.ts

@@ -78,7 +78,7 @@ export interface CreateTaskInput {
 	projectSource?: TaskScopeSource;
 }
 
-export type TaskTransition = "start" | "submit" | "reject" | "retry" | "cancel";
+export type TaskTransition = "start" | "submit" | "reject" | "retry" | "cancel" | "reopen";
 
 export interface TaskBlockage {
 	artifact: Artifact;
@@ -134,6 +134,17 @@ const TASK_TRANSITIONS: Record<TaskTransition, { from: TaskStatus[]; to: TaskSta
 	reject: { from: ["review"], to: "rejected" },
 	retry: { from: ["rejected"], to: "in-progress" },
 	cancel: { from: ["todo", "in-progress", "review", "rejected"], to: "canceled" },
+	/**
+	 * Distinct from tasks.update's status:todo path (recoverCreation, below): that path only ever
+	 * recovers a task whose entire history is a single "created" event already at a terminal status
+	 * (a creation-time mistake) -- it deliberately refuses a task that reached canceled through a
+	 * real, later transition. reopen is the missing counterpart for exactly that case: a task
+	 * legitimately canceled (e.g. a deliberate "pause/park", since there is no direct
+	 * in-progress -> todo transition) can be brought back to todo and driven through the normal
+	 * lifecycle again, without rewriting its real history the way recoverCreation's own
+	 * terminal-at-creation check exists to prevent.
+	 */
+	reopen: { from: ["canceled"], to: "todo" },
 };
 
 export class Tasks {
@@ -511,9 +522,14 @@ export class Tasks {
 				this.focusStore.set(id, context.sessionId);
 			}
 			const updated = this.artifacts.setStatus(id, transition.to)!;
-			const eventType = { start: "started", submit: "submitted", reject: "review_rejected", retry: "retried", cancel: "canceled" }[
-				action
-			] as AppendTaskEvent["type"];
+			const eventType = {
+				start: "started",
+				submit: "submitted",
+				reject: "review_rejected",
+				retry: "retried",
+				cancel: "canceled",
+				reopen: "reopened",
+			}[action] as AppendTaskEvent["type"];
 			this.appendEvent({ taskId: id, type: eventType, fromStatus: task.status as TaskStatus, toStatus: transition.to }, context);
 			if (action === "start" || action === "retry") this.propagateProgressToAncestors(id, context);
 			if (action === "retry") this.focusStore.set(id, context.sessionId);