@danypops/papyrus 0.44.11 → 0.45.0

package/package.json

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

@@ -16,6 +16,17 @@ export const WAL_CHECKPOINT_INTERVAL_MS = 60_000;
 export const DB_OPTIMIZE_INTERVAL_MS = 24 * 60 * 60_000;
 export const GATE_COMMAND_TIMEOUT_MS = 30_000;
 export const GATE_TEST_TIMEOUT_MS = 60_000;
+/**
+ * Ceiling a Gate's own explicit `timeoutMs` (domain/gate.ts) may request, overriding
+ * GATE_COMMAND_TIMEOUT_MS/GATE_TEST_TIMEOUT_MS for that one gate -- e.g. a task whose gate is a
+ * full monorepo test run that legitimately takes longer than either type default. Real, confirmed
+ * bug this exists for: a caller had no way to declare a longer-than-default gate timeout at all --
+ * `tasks.set_gates` silently accepted and dropped an experimental `timeoutMs` field before this.
+ * handlers/tasks.ts's GATE_OPERATION_LIMITS derives its own outer Vehicle transport deadline from
+ * this same constant, so the outer deadline can never fire strictly before a single gate honoring
+ * this ceiling has had a chance to.
+ */
+export const GATE_TIMEOUT_MAX_MS = 300_000;
 export const GATE_OUTPUT_LIMIT = 200;
 export const GATE_MAX_BUFFER_BYTES = 1_048_576;
 export const GATE_FILE_MAX_BYTES = 1_048_576;

package/src/domain/gate.ts

@@ -1,3 +1,5 @@
+import { GATE_TIMEOUT_MAX_MS } from "../constants.ts";
+
 export const GATE_TYPES = ["file-exists", "command", "contains", "test"] as const;
 export type GateType = (typeof GATE_TYPES)[number];
 
@@ -5,6 +7,8 @@ export interface Gate {
 	type: GateType;
 	target: string;
 	expect?: string;
+	/** Overrides GATE_COMMAND_TIMEOUT_MS/GATE_TEST_TIMEOUT_MS for this one "command"/"test" gate, bounded by GATE_TIMEOUT_MAX_MS (see its own doc comment). */
+	timeoutMs?: number;
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -29,10 +33,17 @@ export function validateGates(value: unknown): Gate[] {
 		if (entry.expect !== undefined && typeof entry.expect !== "string") {
 			throw new Error(`gate at index ${index} expect must be a string`);
 		}
+		if (
+			entry.timeoutMs !== undefined &&
+			(!Number.isInteger(entry.timeoutMs) || (entry.timeoutMs as number) < 1_000 || (entry.timeoutMs as number) > GATE_TIMEOUT_MAX_MS)
+		) {
+			throw new Error(`gate at index ${index} timeoutMs must be an integer between 1000 and ${GATE_TIMEOUT_MAX_MS}`);
+		}
 		return {
 			type: entry.type as GateType,
 			target: entry.target,
 			...(typeof entry.expect === "string" ? { expect: entry.expect } : {}),
+			...(typeof entry.timeoutMs === "number" ? { timeoutMs: entry.timeoutMs } : {}),
 		};
 	});
 }

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/shared.ts

@@ -9,6 +9,7 @@ import {
 	defineVehicleSchema,
 	type VehicleContentBlock,
 	VehicleError,
+	type VehicleLimits,
 	type VehicleOperationContext,
 	type VehicleSchemaCodec,
 } from "@danypops/vehicle-core";
@@ -244,6 +245,14 @@ export type DefineOperation = (
 	required: readonly string[],
 	resolve: (input: Record<string, unknown>) => Record<string, unknown>,
 	execute?: (input: Record<string, unknown>, context: VehicleOperationContext<Record<string, unknown>>) => unknown,
+	/**
+	 * Overrides this one operation's own Vehicle transport limits, distinct from every other
+	 * operation this same createOperationDefiner call produces. For an operation that shells out
+	 * to and waits on a real external command (e.g. tasks.run_gates/tasks.complete) rather than an
+	 * instant CRUD read/write -- see handlers/tasks.ts's GATE_OPERATION_LIMITS for the motivating
+	 * case. Omit to keep the definer's own default limits, unchanged for every other action.
+	 */
+	limits?: VehicleLimits,
 ) => void;
 
 const STANDARD_OPERATION_LIMITS = { defaultTimeoutMs: 5_000, maxTimeoutMs: 30_000, maxRequestBytes: 65_536, maxResponseBytes: 262_144 };
@@ -262,7 +271,7 @@ export function createOperationDefiner(
 	permissions: readonly [string, string],
 	defaultCall: (name: string, input: Record<string, unknown>) => unknown,
 ): DefineOperation {
-	return (action, description, effect, properties, required, resolve, execute) => {
+	return (action, description, effect, properties, required, resolve, execute, limits) => {
 		const operation = defineVehicleOperation({
 			name: `${domain}.${action}`,
 			version: 1,
@@ -272,7 +281,7 @@ export function createOperationDefiner(
 			permissions: [...permissions],
 			effect,
 			idempotency: { mode: effect === "read" ? "safe" : "unsafe" },
-			limits: STANDARD_OPERATION_LIMITS,
+			limits: limits ?? STANDARD_OPERATION_LIMITS,
 		});
 		registry.register(
 			owner,

package/src/handlers/tasks.ts

@@ -19,8 +19,10 @@
  *
  * remove/remove_subtree/restore are not duplicated here -- see ./artifact-trash-vehicle.ts.
  */
+import type { VehicleLimits } from "@danypops/vehicle-core";
 import type { VehicleRegistry } from "@danypops/vehicle-server";
 import type { ArtifactStore } from "../artifact/artifact-store.ts";
+import { GATE_TIMEOUT_MAX_MS } from "../constants.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";
@@ -40,7 +42,31 @@ import {
 } from "./shared.ts";
 
 const OWNER = "tasks";
-const LIMITS = { defaultTimeoutMs: 5_000, maxTimeoutMs: 30_000, maxRequestBytes: 65_536, maxResponseBytes: 262_144 };
+
+/**
+ * tasks.run_gates/tasks.complete's own Vehicle transport limits, distinct from every other
+ * tasks.* CRUD action's shared STANDARD_OPERATION_LIMITS (createOperationDefiner's own default,
+ * 5s). Those two operations shell out to and wait on a real, caller-configured external command
+ * (domain/gate.ts's Gate.timeoutMs) -- the shared 5s CRUD default was an accidental inheritance,
+ * not a deliberate choice, and aborted the RPC call for any gate command that took longer than a
+ * few seconds, even a genuinely successful one (confirmed live, twice, with hard numbers: a real
+ * ~13s gate failed deterministically every time; a ~28s gate flapped around a separate, unrelated
+ * 30s inner per-gate-type default).
+ *
+ * defaultTimeoutMs is derived from GATE_TIMEOUT_MAX_MS (the longest a single gate's own explicit
+ * timeoutMs may request) plus a buffer for process-spawn/RPC/serialization overhead, so the outer
+ * transport deadline can never fire strictly before a single gate honoring that ceiling has had a
+ * chance to. A task with SEVERAL gates each near that ceiling can still exceed this default in
+ * aggregate (gates run sequentially -- see ops.ts's runGatesAsync); there is no aggregate
+ * task-level gate-time budget yet. maxTimeoutMs gives a caller who knows its gates are
+ * collectively slower room to explicitly request a longer deadline.
+ */
+const GATE_OPERATION_LIMITS: VehicleLimits = {
+	defaultTimeoutMs: GATE_TIMEOUT_MAX_MS + 60_000,
+	maxTimeoutMs: GATE_TIMEOUT_MAX_MS * 4,
+	maxRequestBytes: 65_536,
+	maxResponseBytes: 262_144,
+};
 
 const objectProp = { type: "object" } as unknown as { type: string };
 const arrayProp = { type: "array" } as unknown as { type: string };
@@ -218,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,
@@ -427,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 },
 		[],
@@ -456,6 +491,7 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 			const labels = labelsById(artifacts, dependencyIds);
 			return { ...result, content: [{ type: "text" as const, text: completionContentText(labels, result) }] };
 		},
+		GATE_OPERATION_LIMITS,
 	);
 
 	define(
@@ -484,6 +520,7 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 				"No gates configured.";
 			return { gates, content: [{ type: "text" as const, text }] };
 		},
+		GATE_OPERATION_LIMITS,
 	);
 
 	define(
@@ -496,7 +533,7 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 	);
 	define(
 		"set_gates",
-		"Replaces a Task's gate commands in full.",
+		"Replaces a Task's gate commands in full. Each gate is {type, target, expect?, timeoutMs?} -- timeoutMs overrides the default per-type command timeout (30s)/test timeout (60s) for a legitimately slower gate, up to a bounded ceiling.",
 		"local-write",
 		{ id: stringProp, name: stringProp, gates: arrayProp, project_root: stringProp },
 		["gates"],

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/ops.ts

@@ -601,8 +601,9 @@ function readBoundedGateFile(path: string): string {
 /** Shared by the sync and async process-gate runners so "test" is never a second, independently
  * maintained copy of "command"'s own command-template/timeout selection. */
 function processGateCommand(gate: Gate): { command: string; timeout: number } {
-	if (gate.type === "test") return { command: `npx vitest run ${gate.target} --reporter=dot`, timeout: GATE_TEST_TIMEOUT_MS };
-	return { command: gate.target, timeout: GATE_COMMAND_TIMEOUT_MS };
+	if (gate.type === "test")
+		return { command: `npx vitest run ${gate.target} --reporter=dot`, timeout: gate.timeoutMs ?? GATE_TEST_TIMEOUT_MS };
+	return { command: gate.target, timeout: gate.timeoutMs ?? GATE_COMMAND_TIMEOUT_MS };
 }
 
 /**

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