@danypops/papyrus 0.20.0 → 0.21.1

package/README.md

@@ -179,6 +179,8 @@ papyrus discuss show <discussion-id> --json
 
 ## Tasks
 
+The `tasks` agent tool addresses a task by `name` (its exact title) wherever `id` would otherwise be required -- `dependency_name`/`parent_name`/`child_name`/`root_task_name`/`depends_on_names` are the name-based equivalents of `dependency_id`/`parent_id`/`child_id`/`root_task_id`/`depends_on`. Resolution is an exact, case-insensitive, trimmed title match scoped like a plain list call; an unmatched or ambiguous name fails with a clear error (ambiguous names list the real ids, since that's the one point disambiguation genuinely needs them). Task results returned to the agent likewise lead with name and status, never id, unless two tasks in the same result share a title -- id is a backend implementation detail, not a conversational handle. `id` itself still works exactly as before for every action.
+
 Run `/tasks` for the interactive task panel:
 
 - `/` filters; arrow keys navigate; Enter opens task actions; `s` switches among the persisted current-project, focused-root graph, and explicit all-projects views

package/extension/src/domain-tools.ts

@@ -33,6 +33,47 @@ function artifactLine(artifact: Artifact): string {
 	return `${artifact.id} [${artifact.status}] ${artifact.title}`;
 }
 
+/**
+ * Tasks-only: the model's primary interfacing point is the task's NAME, not its id -- id is a
+ * backend detail (a stable key other operations need, and titles aren't guaranteed unique), so
+ * it stays out of what the model reads by default. It only resurfaces when genuinely needed to
+ * tell two same-titled tasks apart (taskLines below), or in a matchTaskByName disambiguation
+ * error, never as a matter of course. This is scoped to the tasks tool specifically -- Docs/
+ * Rules/Skills/Discuss keep the shared artifactLine above unless a similar request covers them.
+ */
+export function taskLine(task: Artifact): string {
+	return `[${task.status}] ${task.title}`;
+}
+
+/** Appends " (id)" only for tasks whose title collides with another in this same result set. */
+export function taskLines(tasks: Artifact[]): string[] {
+	const titleCounts = new Map<string, number>();
+	for (const task of tasks) titleCounts.set(task.title, (titleCounts.get(task.title) ?? 0) + 1);
+	return tasks.map((task) => (titleCounts.get(task.title)! > 1 ? `${taskLine(task)} (${task.id})` : taskLine(task)));
+}
+
+/**
+ * Exact, case-insensitive, trimmed title match against an already-fetched candidate set. Throws
+ * a clear "not found" or "ambiguous -- use id" error rather than guessing at a fuzzy match -- id
+ * remains the one truly unambiguous key, so ambiguity is exactly where it's allowed to resurface.
+ * Pure and synchronous so it's directly testable without a service round-trip.
+ */
+export function matchTaskByName(candidates: Artifact[], name: string): string {
+	const needle = name.trim().toLowerCase();
+	const matches = candidates.filter((task) => task.title.trim().toLowerCase() === needle);
+	if (matches.length === 0) throw new Error(`no task named "${name}" found in this scope`);
+	if (matches.length > 1) {
+		throw new Error(`${matches.length} tasks are named "${name}": ${matches.map((task) => `${task.title} (${task.id})`).join(", ")} -- use id to disambiguate`);
+	}
+	return matches[0]!.id;
+}
+
+/** Resolves a task name to its id, scoped the same way a plain `tasks list` call would be (same project_root/session_id/scope). */
+async function resolveTaskIdByName(baseRequest: Record<string, unknown>, name: string): Promise<string> {
+	const candidates = await callService<Record<string, unknown>, Artifact[]>("tasks.list", { ...baseRequest, text: name });
+	return matchTaskByName(candidates, name);
+}
+
 /**
  * Shared "remove"/"restore" dispatch for every domain tool (tasks/docs/rules/skills) --
  * artifact.remove/restore are kind-agnostic composition-root operations (see service.ts),
@@ -67,10 +108,11 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "tasks",
 		label: "Tasks",
-		description: "Task domain tool. ACTIONS: create, update, list, show, history, scope, set_scope, assign_project, graph, plan, active, focused, focus, pause, unpause, clear_focus, start, submit, complete, reject, retry, cancel, run_gates, set_checklist, depend, undepend, contain, uncontain, remove, restore. Lifecycle is todo → in-progress → review → done, with review failure → rejected and retry → in-progress; canceled is terminal. update can recover a Task accidentally created terminal by setting status=todo with a reason, but cannot rewrite legitimate lifecycle history. Active focus is independent and identifies the one task auto-drive continues. Completion runs gates and checklist-proof review, then focuses one deterministic ready successor without claiming effort. Dependency cycles are rejected. undepend/uncontain are idempotent for an already-absent relationship and never start, complete, or focus work merely because an edge disappeared; uncontain removes both contains and part_of edges atomically. remove moves a Task to a time-gated trash (restorable via restore until the purge deadline; refuses if it is the live Task Focus). Prefer this over low-level papyrus_* tools for task work.",
+		description: "Task domain tool. ACTIONS: create, update, list, show, history, scope, set_scope, assign_project, graph, plan, active, focused, focus, pause, unpause, clear_focus, start, submit, complete, reject, retry, cancel, run_gates, set_checklist, depend, undepend, contain, uncontain, remove, restore. Lifecycle is todo → in-progress → review → done, with review failure → rejected and retry → in-progress; canceled is terminal. update can recover a Task accidentally created terminal by setting status=todo with a reason, but cannot rewrite legitimate lifecycle history. Active focus is independent and identifies the one task auto-drive continues. Completion runs gates and checklist-proof review, then focuses one deterministic ready successor without claiming effort. Dependency cycles are rejected. undepend/uncontain are idempotent for an already-absent relationship and never start, complete, or focus work merely because an edge disappeared; uncontain removes both contains and part_of edges atomically. remove moves a Task to a time-gated trash (restorable via restore until the purge deadline; refuses if it is the live Task Focus). PREFER addressing a task by `name` (its exact title) over `id` for every action -- id is a backend implementation detail, resolved from name automatically, and only needs to appear explicitly when a name is genuinely ambiguous (two tasks share a title; the error will say so and list the real ids to disambiguate with). Task results likewise show name and status, not id, unless two shown tasks share a title. `dependency_name`/`parent_name`/`child_name`/`root_task_name`/`depends_on_names` are the name-based equivalents of `dependency_id`/`parent_id`/`child_id`/`root_task_id`/`depends_on`. Prefer this over low-level papyrus_* tools for task work.",
 		parameters: Type.Object({
 			action: Type.String(),
 			id: Type.Optional(Type.String()),
+			name: Type.Optional(Type.String()),
 			title: Type.Optional(Type.String()),
 			body: Type.Optional(Type.String()),
 			status: Type.Optional(Type.String()),
@@ -86,17 +128,23 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 			checklist: Type.Optional(Type.Record(Type.String(), checklistCriterionSchema)),
 			template_id: Type.Optional(Type.String()),
 			parent_id: Type.Optional(Type.String()),
+			parent_name: Type.Optional(Type.String()),
 			child_id: Type.Optional(Type.String()),
+			child_name: Type.Optional(Type.String()),
 			dependency_id: Type.Optional(Type.String()),
+			dependency_name: Type.Optional(Type.String()),
 			depends_on: Type.Optional(Type.Array(Type.String())),
+			depends_on_names: Type.Optional(Type.Array(Type.String())),
 			project_root: Type.Optional(Type.String()),
 			scope: Type.Optional(Type.Union([Type.Literal("project"), Type.Literal("graph"), Type.Literal("all")])),
 			root_task_id: Type.Optional(Type.String()),
+			root_task_name: Type.Optional(Type.String()),
 		}),
 		renderCall(args, theme) { return renderPapyrusToolCall("Tasks", args, theme); },
 		renderResult(result, options, theme, context) { return renderPapyrusToolResult(result, options, theme, context); },
-		async execute(_id, params, _signal, _onUpdate, ctx) {
+		async execute(_id, rawParams, _signal, _onUpdate, ctx) {
 			try {
+				const params: Record<string, unknown> = { ...rawParams };
 				const action = params.action;
 				// Defaults to this Pi session's own id so Focus reads/writes are isolated per agent
 				// without depending on the model to know or supply its own session identity.
@@ -105,18 +153,37 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 				// session never gets this session's secret smuggled in on its behalf -- the cache only
 				// ever holds this extension's own registered session anyway (see session-identity.ts).
 				const resolvedSessionId = params.session_id ?? ctx.sessionManager.getSessionId();
-				const request = { ...params, project_root: params.project_root ?? ctx.cwd, actor: "agent", source: "pi-tool", session_id: resolvedSessionId, ...sessionSecretField(resolvedSessionId as string) };
+				const baseRequest = { project_root: params.project_root ?? ctx.cwd, actor: "agent", source: "pi-tool", session_id: resolvedSessionId, ...sessionSecretField(resolvedSessionId as string) };
+				// Resolves every *_name field to its *_id counterpart before dispatch, so every action
+				// below can go on reading id/dependency_id/parent_id/child_id/root_task_id exactly as
+				// before -- id-based calls are unaffected; name-based ones are transparently rewritten.
+				const resolveField = async (nameKey: string, idKey: string) => {
+					const nameValue = params[nameKey];
+					if (typeof nameValue === "string" && nameValue.length > 0 && !params[idKey]) {
+						params[idKey] = await resolveTaskIdByName(baseRequest, nameValue);
+					}
+				};
+				await resolveField("name", "id");
+				await resolveField("dependency_name", "dependency_id");
+				await resolveField("parent_name", "parent_id");
+				await resolveField("child_name", "child_id");
+				await resolveField("root_task_name", "root_task_id");
+				const dependsOnNames = params["depends_on_names"];
+				if (Array.isArray(dependsOnNames) && dependsOnNames.length > 0 && !params["depends_on"]) {
+					params["depends_on"] = await Promise.all(dependsOnNames.map((entry) => resolveTaskIdByName(baseRequest, String(entry))));
+				}
+				const request = { ...params, ...baseRequest };
 				if (action === "create") {
 					const artifact = await callService<Record<string, unknown>, Artifact>("tasks.create", request);
-					return text(`Created task ${artifactLine(artifact)}`, createArtifactDetails("tasks.create", artifact));
+					return text(`Created task ${taskLine(artifact)}`, createArtifactDetails("tasks.create", artifact));
 				}
 				if (action === "list") {
 					const rows = await callService<Record<string, unknown>, Artifact[]>("tasks.list", request);
-					return text(rows.length ? rows.map(artifactLine).join("\n") : "No tasks found.", createArtifactListDetails("tasks.list", rows));
+					return text(rows.length ? taskLines(rows).join("\n") : "No tasks found.", createArtifactListDetails("tasks.list", rows));
 				}
 				if (action === "show") {
 					const artifact = await callService<Record<string, unknown>, Artifact>("tasks.show", params);
-					return text(`${artifactLine(artifact)}\n\n${artifact.body}`, createArtifactDetails("tasks.show", artifact));
+					return text(`${taskLine(artifact)}\n\n${artifact.body}`, createArtifactDetails("tasks.show", artifact));
 				}
 				if (action === "history") {
 					const page = await callService<Record<string, unknown>, TaskHistoryPage>("tasks.history", request);
@@ -131,20 +198,20 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 				if (action === "active") {
 					const artifact = await callService<Record<string, unknown>, Artifact | null>("tasks.active", request);
 					return artifact
-						? text(`Active: ${artifactLine(artifact)}`, createArtifactDetails("tasks.active", artifact))
+						? text(`Active: ${taskLine(artifact)}`, createArtifactDetails("tasks.active", artifact))
 						: text("No active task.", createPreviewDetails("tasks.active", "Active task", "No active task."));
 				}
 				if (action === "focused") {
 					const focus = await callService<Record<string, unknown>, { artifact: Artifact; status: string } | null>("tasks.focused", request);
 					return focus
-						? text(`Focused (${focus.status}): ${artifactLine(focus.artifact)}`, createArtifactDetails("tasks.focused", focus.artifact))
+						? text(`Focused (${focus.status}): ${taskLine(focus.artifact)}`, createArtifactDetails("tasks.focused", focus.artifact))
 						: text("No focused task.", createPreviewDetails("tasks.focused", "Focused task", "No focused task."));
 				}
 				if (action === "pause" || action === "unpause") {
 					const operation = action === "pause" ? "tasks.pause" : "tasks.unpause";
 					const focus = await callService<Record<string, unknown>, { artifact: Artifact; status: string }>(operation, request);
 					emitTaskFocusEvent({ taskId: focus.artifact.id, sessionId: request.session_id as string, status: action === "pause" ? "paused" : "unpaused" });
-					return text(`Focused (${focus.status}): ${artifactLine(focus.artifact)}`, createArtifactDetails(operation, focus.artifact));
+					return text(`Focused (${focus.status}): ${taskLine(focus.artifact)}`, createArtifactDetails(operation, focus.artifact));
 				}
 				if (action === "clear_focus") {
 					const result = await callService<Record<string, unknown>, { cleared: boolean }>("tasks.clear_focus", request);
@@ -168,11 +235,16 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 				if (action === "plan") {
 					const plan = await callService<Record<string, unknown>, TaskExecutionPlan>("tasks.plan", request);
 					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 lines = plan.layers.flatMap((layer, index) => [
 						`Layer ${index + 1}`,
 						...layer.map((id) => {
 							const node = byId.get(id);
-							return node ? `  [${node.state}] ${node.id} ${node.title}` : `  [unknown] ${id}`;
+							if (!node) return `  [unknown] ${id}`;
+							return (titleCounts.get(node.title) ?? 0) > 1
+								? `  [${node.state}] ${node.title} (${node.id})`
+								: `  [${node.state}] ${node.title}`;
 						}),
 					]);
 					if (plan.cycleIds.length > 0) lines.push(`Invalid cycle: ${plan.cycleIds.join(", ")}`);
@@ -181,24 +253,25 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 				}
 				if (action === "set_checklist") {
 					const artifact = await callService<Record<string, unknown>, Artifact>("tasks.set_checklist", params);
-					return text(`Updated checklist: ${artifactLine(artifact)}`, createArtifactDetails("tasks.set_checklist", artifact));
+					return text(`Updated checklist: ${taskLine(artifact)}`, createArtifactDetails("tasks.set_checklist", artifact));
 				}
 				if (action === "complete") {
 					const result = await callService<Record<string, unknown>, TaskCompletion>("tasks.complete", request);
 					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: ${artifactLine(result.focused)}` : "";
+					const focused = result.focused ? `\nActive: ${taskLine(result.focused)}` : "";
+					const blockedLines = taskLines(result.blocked.map((entry) => entry.artifact));
 					const blocked = result.blocked.length > 0
-						? `\nBlocked: ${result.blocked.map((entry) => `${artifactLine(entry.artifact)} waits for ${entry.dependencyIds.join(", ")}`).join("; ")}`
+						? `\nBlocked: ${result.blocked.map((entry, index) => `${blockedLines[index]} waits for ${entry.dependencyIds.join(", ")}`).join("; ")}`
 						: "";
-					const output = `${result.completed ? "Completed" : "Rejected"}: ${artifactLine(result.artifact)}${focused}${blocked}${checklist ? `\n${checklist}` : ""}${gates ? `\n${gates}` : ""}`;
+					const output = `${result.completed ? "Completed" : "Rejected"}: ${taskLine(result.artifact)}${focused}${blocked}${checklist ? `\n${checklist}` : ""}${gates ? `\n${gates}` : ""}`;
 					return text(output, createPreviewDetails("tasks.complete", "Task completion", output));
 				}
 				if (action === "run_gates") {
 					const gates = await callService<Record<string, unknown>, GateResult[]>("tasks.run_gates", request);
 					return text(
 						gates.map((gate) => `${gate.passed ? "✓" : "✗"} ${gate.gate.type}: ${gate.gate.target} — ${gate.output}`).join("\n") || "No gates configured.",
-						createGateRunDetails("tasks.run_gates", params.id ?? "", gates.map((gate) => ({
+						createGateRunDetails("tasks.run_gates", (params.id as string | undefined) ?? "", gates.map((gate) => ({
 							passed: gate.passed, type: gate.gate.type, target: gate.gate.target, output: gate.output,
 						}))),
 					);
@@ -224,7 +297,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 				if (!operation) throw new Error(`unknown tasks action: ${action}`);
 				const artifact = await callService<Record<string, unknown>, Artifact>(operation, request);
 				if (operation === "tasks.focus") emitTaskFocusEvent({ taskId: artifact.id, sessionId: request.session_id as string, status: "focused" });
-				return text(artifactLine(artifact), createArtifactDetails(operation, artifact));
+				return text(taskLine(artifact), createArtifactDetails(operation, artifact));
 			} catch (error) {
 				throw new Error(`tasks failed: ${error instanceof Error ? error.message : error}`);
 			}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.20.0",
+  "version": "0.21.1",
   "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/domain/gate.ts

@@ -7,6 +7,18 @@ export interface Gate {
 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/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/task-service.ts

@@ -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;
 	}