@danypops/papyrus 0.21.0 → 0.21.2

package/package.json

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

package/src/adapters/sqlite-gate-runner.ts

@@ -6,8 +6,8 @@ import { runGates, runGatesAsync } from "../ops.ts";
 export class SQLiteGateRunner implements GateRunner {
 	constructor(private readonly db: Db) {}
 
-	run(artifactId: string): GateResult[] {
-		return runGates(this.db, artifactId);
+	run(artifactId: string, options?: GateRunOptions): GateResult[] {
+		return runGates(this.db, artifactId, options);
 	}
 
 	runAsync(artifactId: string, options?: GateRunOptions): Promise<GateResult[]> {

package/src/cli.ts

@@ -157,6 +157,7 @@ const USAGE = `Usage:
   papyrus tasks show <id> [--json]
   papyrus tasks run-gates <id> [--json]
   papyrus tasks set-checklist <id> --checklist-json <json> [--json]
+  papyrus tasks set-gates <id> --gates-json <json> [--json]
   papyrus tasks context [--scope <project|graph|all>] [--root-task-id <id>] [--session-id <id>] [--json]
 
 A "--session-id" scopes Task Focus to one agent session; omit it to use the shared "global" Focus (today's behavior).
@@ -1322,6 +1323,14 @@ export async function runTaskCli(args: string[], client: TaskCliClient, projectR
 			human = `Updated checklist: ${artifactLabel(artifact)}`;
 			break;
 		}
+		case "set-gates": {
+			if (!id || dependencyId) throw new Error("tasks set-gates requires exactly one task id");
+			if (!gates) throw new Error("tasks set-gates requires --gates-json");
+			const artifact = await client.call<Record<string, unknown>, CliArtifact>("tasks.set_gates", { id, gates });
+			result = artifact;
+			human = `Updated gates: ${artifactLabel(artifact)}`;
+			break;
+		}
 		case "context": {
 			if (id) throw new Error("tasks context accepts no positional arguments");
 			const summary = await client.call<Record<string, unknown>, string | null>("tasks.context", {
@@ -1478,7 +1487,7 @@ export async function runTaskCli(args: string[], client: TaskCliClient, projectR
 			break;
 		}
 		default:
-			throw new Error("tasks action must be create, list, show, active, focused, focus, pause, unpause, clear-focus, update, graph, plan, context, history, scope, assign-project, complete, start, submit, reject, retry, cancel, depend, undepend, contain, uncontain, run-gates, or set-checklist");
+			throw new Error("tasks action must be create, list, show, active, focused, focus, pause, unpause, clear-focus, update, graph, plan, context, history, scope, assign-project, complete, start, submit, reject, retry, cancel, depend, undepend, contain, uncontain, run-gates, set-checklist, or set-gates");
 	}
 	return json ? JSON.stringify(result) : human;
 }

package/src/domain/gate.ts

@@ -1,12 +1,57 @@
+export const GATE_TYPES = ["file-exists", "command", "contains", "test"] as const;
+export type GateType = typeof GATE_TYPES[number];
+
 export interface Gate {
-	type: "file-exists" | "command" | "contains" | "test";
+	type: GateType;
 	target: string;
 	expect?: string;
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Validates a Gate[] the same way validateChecklist validates a Checklist -- gates previously had
+ * no validation at all (create() assigned `input.gates` to extra verbatim), and no way to change
+ * them after creation except by re-typing the whole task, silently accepted by "tasks update"
+ * (which only ever reads title/body/labels/status) as if it had worked. See Tasks.setGates.
+ */
+export function validateGates(value: unknown): Gate[] {
+	if (!Array.isArray(value)) throw new Error("gates must be an array");
+	return value.map((entry, index) => {
+		if (!isRecord(entry) || !GATE_TYPES.includes(entry["type"] as GateType)) {
+			throw new Error(`gate at index ${index} requires a valid type (${GATE_TYPES.join(", ")})`);
+		}
+		if (typeof entry["target"] !== "string" || entry["target"].trim().length === 0) {
+			throw new Error(`gate at index ${index} requires a non-empty target`);
+		}
+		if (entry["expect"] !== undefined && typeof entry["expect"] !== "string") {
+			throw new Error(`gate at index ${index} expect must be a string`);
+		}
+		return {
+			type: entry["type"] as GateType,
+			target: entry["target"],
+			...(typeof entry["expect"] === "string" ? { expect: entry["expect"] } : {}),
+		};
+	});
+}
+
 export interface GateRunOptions {
 	/** Absolute Unix epoch deadline for the full gate sequence. */
 	deadlineMs?: number;
+	/**
+	 * Working directory for "command"/"test" gates. Without this, a command gate inherits the
+	 * Papyrus daemon's own process cwd (its systemd unit's launch directory, e.g. the user's home
+	 * directory) rather than the task's project -- a real incident: a `bun test` command gate ran
+	 * against the daemon's home directory instead of the task's project, recursively discovering
+	 * and attempting to run every test file under every project on the machine, which exhausted
+	 * memory and crashed the `bun` process outright (SIGILL/SIGABRT), well past the configured
+	 * gate timeout because the timeout only ever terminated the immediate shell, not the process
+	 * group it spawned (see executeGateCommand). Task-scoped completion must always pass the
+	 * task's project_root here.
+	 */
+	cwd?: string;
 }
 
 export interface GateResult {

package/src/modules/tasks.ts

@@ -89,7 +89,7 @@ export const TASKS_OPERATION_NAMES = [
 	"tasks.create", "tasks.update", "tasks.list", "tasks.graph", "tasks.plan", "tasks.show", "tasks.history",
 	"tasks.scope", "tasks.set_scope", "tasks.assign_project", "tasks.active", "tasks.focused", "tasks.focus",
 	"tasks.pause", "tasks.unpause", "tasks.clear_focus", "tasks.start", "tasks.submit", "tasks.complete",
-	"tasks.run_gates", "tasks.set_checklist", "tasks.context", "tasks.reject", "tasks.retry", "tasks.cancel",
+	"tasks.run_gates", "tasks.set_checklist", "tasks.set_gates", "tasks.context", "tasks.reject", "tasks.retry", "tasks.cancel",
 	"tasks.depend", "tasks.undepend", "tasks.contain", "tasks.uncontain", "tasks.reap_stale_focus",
 ] as const;
 
@@ -157,6 +157,7 @@ export function tasksOperations(tasks: Tasks, artifacts: ArtifactStore, sessionI
 		define("tasks.complete", (input: OperationInput) => tasks.completeAsync(string(input, "id"), eventContext(input))),
 		define("tasks.run_gates", (input: OperationInput) => tasks.runGates(string(input, "id"), eventContext(input))),
 		define("tasks.set_checklist", (input: OperationInput) => tasks.setChecklist(string(input, "id"), input["checklist"] as Checklist)),
+		define("tasks.set_gates", (input: OperationInput) => tasks.setGates(string(input, "id"), input["gates"] as Parameters<Tasks["setGates"]>[1])),
 		define("tasks.context", (input: OperationInput) => taskContext(
 			artifacts,
 			tasks.active(taskFilter(input))?.id,

package/src/ops.ts

@@ -3,7 +3,6 @@
  * Enforces the schema protocol (kinds, statuses, relations) via FK + app validation.
  */
 import { createRequire } from "node:module";
-import { exec } from "node:child_process";
 import type { Db } from "./db.ts";
 import { inTransaction } from "./db.ts";
 import { ARTIFACT_TRASH_RETENTION_MS, DEFAULT_STATUS_BY_KIND } from "./constants.ts";
@@ -508,10 +507,11 @@ function readBoundedGateFile(path: string): string {
 	return readFileSync(path, "utf-8") as string;
 }
 
-export function runGates(db: Db, artifactId: string): GateResult[] {
+export function runGates(db: Db, artifactId: string, options: GateRunOptions = {}): GateResult[] {
 	const art = getArtifact(db, artifactId);
 	if (!art) throw new Error("artifact not found");
 	const gates = (art.extra["gates"] as Gate[]) ?? [];
+	const cwd = options.cwd;
 	return gates.map((gate) => {
 		switch (gate.type) {
 			case "file-exists": {
@@ -531,7 +531,7 @@ export function runGates(db: Db, artifactId: string): GateResult[] {
 			case "command": {
 				const { execSync } = require_("node:child_process");
 				try {
-					const output = execSync(gate.target, { encoding: "utf-8", timeout: GATE_COMMAND_TIMEOUT_MS, stdio: ["pipe", "pipe", "pipe"] }).trim();
+					const output = execSync(gate.target, { encoding: "utf-8", timeout: GATE_COMMAND_TIMEOUT_MS, stdio: ["pipe", "pipe", "pipe"], ...(cwd ? { cwd } : {}) }).trim();
 					const passed = gate.expect ? output.includes(gate.expect) : true;
 					return { gate, passed, output: output.slice(0, GATE_OUTPUT_LIMIT) };
 				} catch (e) {
@@ -541,7 +541,7 @@ export function runGates(db: Db, artifactId: string): GateResult[] {
 			case "test": {
 				const { execSync } = require_("node:child_process");
 				try {
-					execSync(`npx vitest run ${gate.target} --reporter=dot`, { encoding: "utf-8", timeout: GATE_TEST_TIMEOUT_MS, stdio: ["pipe", "pipe", "pipe"] });
+					execSync(`npx vitest run ${gate.target} --reporter=dot`, { encoding: "utf-8", timeout: GATE_TEST_TIMEOUT_MS, stdio: ["pipe", "pipe", "pipe"], ...(cwd ? { cwd } : {}) });
 					return { gate, passed: true, output: "tests passed" };
 				} catch (e) {
 					return { gate, passed: false, output: e instanceof Error ? e.message.slice(0, GATE_OUTPUT_LIMIT) : "tests failed" };
@@ -553,15 +553,64 @@ export function runGates(db: Db, artifactId: string): GateResult[] {
 	});
 }
 
-function executeGateCommand(command: string, timeout: number): Promise<{ passed: boolean; output: string }> {
+/**
+ * Runs one gate command with two invariants a prior implementation lacked (a real incident; see
+ * GateRunOptions.cwd's doc comment):
+ *   1. `cwd` is always explicit, never inherited from the daemon's own process cwd.
+ *   2. The whole process group is killed on timeout, not just the immediate shell. `exec()`'s own
+ *      `timeout` option only signals the process it directly spawned (the shell running
+ *      `command`); a shell's own child (e.g. `bun` under `sh -c "bun test"`) is not in general
+ *      killed by that signal and can be reparented and keep running -- and consuming memory --
+ *      indefinitely after Papyrus considers the gate "timed out". Spawning detached (its own
+ *      process group) and killing the negated pid on our own timer reaches the whole tree.
+ */
+function executeGateCommand(command: string, timeout: number, cwd?: string): Promise<{ passed: boolean; output: string }> {
+	// `spawn(..., { shell: true, detached: true })` instead of the `exec()` convenience wrapper:
+	// `detached` (needed to make the shell the leader of its own process group, so the negated pid
+	// below reaches every descendant, not just the shell) is not part of Node's `exec()`/
+	// `ExecOptions` type at all -- `spawn`'s options support it directly and correctly.
+	const { spawn } = require_("node:child_process") as typeof import("node:child_process");
 	return new Promise((resolve) => {
-		exec(command, { encoding: "utf8", timeout, maxBuffer: GATE_MAX_BUFFER_BYTES }, (error, stdout, stderr) => {
-			const output = `${stdout}${stderr}`.trim().slice(0, GATE_OUTPUT_LIMIT);
-			resolve({
-				passed: error === null,
-				output: output || (error ? error.message.slice(0, GATE_OUTPUT_LIMIT) : "ok"),
-			});
+		let settled = false;
+		let buffered = "";
+		let truncated = false;
+		const child = spawn(command, { shell: true, detached: true, ...(cwd ? { cwd } : {}) });
+
+		const append = (chunk: Buffer): void => {
+			if (truncated) return;
+			buffered += chunk.toString("utf8");
+			if (buffered.length > GATE_MAX_BUFFER_BYTES) {
+				buffered = buffered.slice(0, GATE_MAX_BUFFER_BYTES);
+				truncated = true;
+			}
+		};
+		child.stdout?.on("data", append);
+		child.stderr?.on("data", append);
+
+		const finish = (result: { passed: boolean; output: string }): void => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			resolve(result);
+		};
+
+		child.on("error", (error) => finish({ passed: false, output: error.message.slice(0, GATE_OUTPUT_LIMIT) }));
+		child.on("close", (code) => {
+			const output = buffered.trim().slice(0, GATE_OUTPUT_LIMIT);
+			finish({ passed: code === 0, output: output || (code === 0 ? "ok" : `command exited with code ${code}`) });
 		});
+
+		const timer = setTimeout(() => {
+			if (settled) return;
+			if (child.pid !== undefined) {
+				try {
+					process.kill(-child.pid, "SIGKILL");
+				} catch {
+					child.kill("SIGKILL");
+				}
+			}
+			finish({ passed: false, output: `gate command timed out after ${timeout}ms` });
+		}, timeout);
 	});
 }
 
@@ -599,7 +648,7 @@ export async function runGatesAsync(db: Db, artifactId: string, options: GateRun
 			const command = gate.type === "test" ? `npx vitest run ${gate.target} --reporter=dot` : gate.target;
 			const configuredTimeout = gate.type === "test" ? GATE_TEST_TIMEOUT_MS : GATE_COMMAND_TIMEOUT_MS;
 			const timeout = remainingMs === undefined ? configuredTimeout : Math.max(1, Math.min(configuredTimeout, remainingMs));
-			const executed = await executeGateCommand(command, timeout);
+			const executed = await executeGateCommand(command, timeout, options.cwd);
 			results.push({
 				gate,
 				passed: executed.passed && (gate.expect ? executed.output.includes(gate.expect) : true),

package/src/ports/gate-runner.ts

@@ -1,6 +1,6 @@
 import type { GateResult, GateRunOptions } from "../domain/gate.ts";
 
 export interface GateRunner {
-	run(artifactId: string): GateResult[];
+	run(artifactId: string, options?: GateRunOptions): GateResult[];
 	runAsync(artifactId: string, options?: GateRunOptions): Promise<GateResult[]>;
 }

package/src/service.ts

@@ -323,6 +323,7 @@ function handlers(
 		"tasks.complete": forwardToModule("tasks.complete"),
 		"tasks.run_gates": forwardToModule("tasks.run_gates"),
 		"tasks.set_checklist": forwardToModule("tasks.set_checklist"),
+		"tasks.set_gates": forwardToModule("tasks.set_gates"),
 		"tasks.context": forwardToModule("tasks.context"),
 		"tasks.reject": forwardToModule("tasks.reject"),
 		"tasks.retry": forwardToModule("tasks.retry"),

package/src/task-service.ts

@@ -12,7 +12,7 @@ import {
 import type { Artifact } from "./domain/artifact.ts";
 import { checklistEntries, validateChecklist, type Checklist, type ProofReference } from "./domain/checklist.ts";
 import { isDiscussionArtifact, readDiscussionExtra } from "./domain/discussion.ts";
-import type { Gate, GateResult } from "./domain/gate.ts";
+import { validateGates, type Gate, type GateResult } from "./domain/gate.ts";
 import type { AppendTaskEvent, TaskEventContext, TaskHistoryPage, TaskHistoryQuery, TaskLifecycleStatus } from "./domain/task-event.ts";
 import { normalizeProjectRoot, taskScopeLabel, type TaskScopeSource, type TaskViewMode, type TaskViewSelection } from "./domain/task-scope.ts";
 import type { ArtifactStore } from "./ports/artifact-store.ts";
@@ -141,7 +141,7 @@ export class Tasks {
 			if (input.parentId) this.require(input.parentId);
 			for (const dependency of input.dependsOn ?? []) this.require(dependency);
 			const extra: Record<string, unknown> = { ...(input.extra ?? {}) };
-			if (input.gates !== undefined) extra["gates"] = input.gates;
+			if (input.gates !== undefined) extra["gates"] = validateGates(input.gates);
 			if (input.checklist !== undefined) extra["checklist"] = validateChecklist(input.checklist);
 			const projectRoot = input.projectRoot === undefined ? undefined : normalizeProjectRoot(input.projectRoot);
 			if (input.parentId && this.scopes.get(input.parentId)?.projectRoot !== projectRoot) {
@@ -424,7 +424,7 @@ export class Tasks {
 		const attemptId = crypto.randomUUID();
 		this.events.atomic(() => this.appendEvent({ taskId: id, type: "completion_attempted", fromStatus: "review", toStatus: "review", attemptId }, context));
 		const checklist = this.reviewChecklist(task);
-		const results = this.gates.run(id);
+		const results = this.gates.run(id, { cwd: this.scopes.get(id)?.projectRoot });
 		return this.resolveCompletion(id, attemptId, results, checklist, context, options);
 	}
 
@@ -434,14 +434,17 @@ export class Tasks {
 		const attemptId = crypto.randomUUID();
 		this.events.atomic(() => this.appendEvent({ taskId: id, type: "completion_attempted", fromStatus: "review", toStatus: "review", attemptId }, context));
 		const checklist = this.reviewChecklist(task);
-		const results = await this.gates.runAsync(id, { deadlineMs: options.gateDeadlineMs });
+		// project_root, never the daemon's own inherited process cwd -- see GateRunOptions.cwd's doc
+		// comment for the real incident this fixes (a command gate once tested the daemon's entire
+		// home directory instead of the task's project and crashed the bun process outright).
+		const results = await this.gates.runAsync(id, { deadlineMs: options.gateDeadlineMs, cwd: this.scopes.get(id)?.projectRoot });
 		this.requireReview(id);
 		return this.resolveCompletion(id, attemptId, results, checklist, context, options);
 	}
 
 	async runGates(id: string, context: TaskEventContext = {}): Promise<GateResult[]> {
 		this.require(id);
-		const results = await this.gates.runAsync(id);
+		const results = await this.gates.runAsync(id, { cwd: this.scopes.get(id)?.projectRoot });
 		this.events.atomic(() => this.appendEvent({ taskId: id, type: "gates_evaluated", evidence: { gates: results, result: results.every((gate) => gate.passed) ? "passed" : "failed" } }, context));
 		return results;
 	}
@@ -456,6 +459,16 @@ export class Tasks {
 		return this.artifacts.setExtra(id, { ...task.extra, checklist: validateChecklist(checklist) })!;
 	}
 
+	/**
+	 * The only way to change a task's gates after creation. "tasks update" (title/body/labels/
+	 * status only) silently ignored a `gates` field with no error at all -- a real incident (see
+	 * GateRunOptions.cwd's doc comment for the crash this masked while debugging).
+	 */
+	setGates(id: string, gates: Gate[]): Artifact {
+		const task = this.require(id);
+		return this.artifacts.setExtra(id, { ...task.extra, gates: validateGates(gates) })!;
+	}
+
 	depend(id: string, dependencyId: string, context: TaskEventContext = {}): Artifact {
 		return this.events.atomic(() => {
 			this.require(id);