@danypops/papyrus 0.5.0 → 0.6.0

package/README.md

@@ -37,6 +37,8 @@ papyrus tasks plan
 papyrus tasks depend <task-id> <prerequisite-id>
 papyrus tasks start <task-id>
 papyrus tasks complete <task-id>
+papyrus tasks automate <task-id> <on|off>
+papyrus automation status
 ```
 
 For repository work, install the versioned ownership guard once:
@@ -138,8 +140,31 @@ papyrus tasks complete <id> --json
 papyrus tasks reject <id> --json
 papyrus tasks retry <id> --json
 papyrus tasks cancel <id> --json
+papyrus tasks automate <id> <on|off> --json
+papyrus automation status --json
+papyrus automation run --json
 ```
 
+### Opt-in supervised automation
+
+Background graph reconciliation is off by default and requires two independent opt-ins: daemon configuration and `automation.enabled` on each Task. Only opted-in Tasks already in `review` are eligible for automatic gate/checklist review; Papyrus never skips the review lifecycle. When one completes, directly dependent opted-in successors that become ready may move from `todo` to `in-progress`. Every completion, rejection, and start is written to append-only history with actor `daemon`, source `automation-reconciler`, reason, and bounded gate evidence.
+
+Enable the daemon with a systemd user-service override and restart it:
+
+```ini
+[Service]
+Environment=PAPYRUS_AUTOMATION_ENABLED=1
+```
+
+```bash
+systemctl --user edit papyrus.service
+systemctl --user restart papyrus.service
+papyrus tasks automate <task-id> on
+papyrus automation status
+```
+
+Secure defaults are a 60-second interval, 10 Task transitions per sweep, gate concurrency 1, and a 120-second sweep deadline. Optional environment settings are `PAPYRUS_AUTOMATION_INTERVAL_MS` (10 seconds–1 hour), `PAPYRUS_AUTOMATION_MAX_TASKS` (1–100), `PAPYRUS_AUTOMATION_GATE_CONCURRENCY` (1–4), and `PAPYRUS_AUTOMATION_MAX_RUNTIME_MS` (1 ms–10 minutes). Candidate scans are capped at 1,000 review Tasks, sweeps are single-flight, subprocess gates inherit the sweep deadline, result arrays are bounded by the Task limit, and logs contain counts rather than gate output. `papyrus automation run` uses the same policy and refuses to reconcile while global automation is disabled.
+
 Checklist criteria are an item-to-proof map. Every new item requires one or more typed references to inspectable evidence; proof presence does not imply that the evidence passed an executable gate:
 
 ```ts

package/extension/src/domain-tools.ts

@@ -31,7 +31,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "tasks",
 		label: "Tasks",
-		description: "Task domain tool. ACTIONS: create, list, show, history, graph, plan, active, focus, start, submit, complete, reject, retry, cancel, run_gates, set_checklist, depend, contain. Lifecycle is todo → in-progress → review → done, with review failure → rejected and retry → in-progress; canceled is terminal. 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. Prefer this over low-level papyrus_* tools for task work.",
+		description: "Task domain tool. ACTIONS: create, list, show, history, graph, plan, active, focus, start, submit, complete, reject, retry, cancel, run_gates, set_checklist, set_automation, depend, contain. Lifecycle is todo → in-progress → review → done, with review failure → rejected and retry → in-progress; canceled is terminal. 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. Prefer this over low-level papyrus_* tools for task work.",
 		parameters: Type.Object({
 			action: Type.String(),
 			id: Type.Optional(Type.String()),
@@ -44,6 +44,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 			direction: Type.Optional(Type.Union([Type.Literal("asc"), Type.Literal("desc")])),
 			reason: Type.Optional(Type.String()),
 			session_id: Type.Optional(Type.String()),
+			enabled: Type.Optional(Type.Boolean()),
 			labels: Type.Optional(Type.Array(Type.String())),
 			extra: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
 			gates: Type.Optional(Type.Array(Type.Record(Type.String(), Type.Unknown()))),
@@ -123,6 +124,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 					reject: "tasks.reject",
 					retry: "tasks.retry",
 					cancel: "tasks.cancel",
+					set_automation: "tasks.set_automation",
 					depend: "tasks.depend",
 					contain: "tasks.contain",
 				} as const;

package/extension/src/tasks.ts

@@ -30,6 +30,12 @@ const STATUS_ACTIONS: Record<string, string[]> = {
 
 type TaskRow = Artifact;
 
+function taskAutomationEnabled(task: Artifact): boolean {
+	const automation = task.extra["automation"];
+	return typeof automation === "object" && automation !== null && !Array.isArray(automation)
+		&& (automation as Record<string, unknown>)["enabled"] === true;
+}
+
 export interface TaskHierarchyRow {
 	task: TaskRow;
 	depth: number;
@@ -86,9 +92,11 @@ export async function showTasks(ctx: ExtensionCommandContext): Promise<void> {
 		if (action.type !== "action" || !action.row) continue;
 
 		const active = graph.nodes.find((node) => node.task.id === action.row!.id)?.active === true;
+		const automationEnabled = taskAutomationEnabled(action.row);
 		const choices = [
 			"Show details",
 			...(!active && action.row.status !== "done" && action.row.status !== "canceled" ? ["Make active"] : []),
+			...(action.row.status !== "done" && action.row.status !== "canceled" ? [automationEnabled ? "Disable automation" : "Enable automation"] : []),
 			...(action.row.status === "review" ? ["Run gates"] : []),
 			...(STATUS_ACTIONS[action.row.status] ?? []),
 		];
@@ -107,6 +115,20 @@ export async function showTasks(ctx: ExtensionCommandContext): Promise<void> {
 			} catch (error) {
 				ctx.ui.notify(`Focus failed: ${error instanceof Error ? error.message : error}`, "error");
 			}
+		} else if (choice === "Enable automation" || choice === "Disable automation") {
+			try {
+				const enabled = choice === "Enable automation";
+				const updated = await callService<Record<string, unknown>, Artifact>("tasks.set_automation", {
+					id: action.row.id,
+					enabled,
+					actor: "user",
+					source: "tasks-tui",
+				});
+				action.row.extra = updated.extra;
+				ctx.ui.notify(`Automation ${enabled ? "enabled" : "disabled"}: ${action.row.title}`, enabled ? "warning" : "info");
+			} catch (error) {
+				ctx.ui.notify(`Automation setting failed: ${error instanceof Error ? error.message : error}`, "error");
+			}
 		} else if (choice === "Run gates") {
 			try {
 				const results = await callService<Record<string, unknown>, GateResult[]>("tasks.run_gates", { id: action.row.id, actor: "user", source: "tasks-tui" });

package/package.json

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

@@ -1,5 +1,5 @@
 import type { Db } from "../db.ts";
-import type { GateResult } from "../domain/gate.ts";
+import type { GateResult, GateRunOptions } from "../domain/gate.ts";
 import type { GateRunner } from "../ports/gate-runner.ts";
 import { runGates, runGatesAsync } from "../ops.ts";
 
@@ -10,7 +10,7 @@ export class SQLiteGateRunner implements GateRunner {
 		return runGates(this.db, artifactId);
 	}
 
-	runAsync(artifactId: string): Promise<GateResult[]> {
-		return runGatesAsync(this.db, artifactId);
+	runAsync(artifactId: string, options?: GateRunOptions): Promise<GateResult[]> {
+		return runGatesAsync(this.db, artifactId, options);
 	}
 }

package/src/cli.ts

@@ -10,6 +10,7 @@ import { serveMain } from "./daemon.ts";
 import type { GateResult } from "./domain/gate.ts";
 import type { TaskExecutionPlan } from "./task-execution.ts";
 import type { TaskBlockage, TaskCompletion } from "./task-service.ts";
+import type { TaskAutomationResult, TaskAutomationSettings } from "./task-automation.ts";
 
 export interface SystemdUnitOptions {
 	bunBin: string;
@@ -57,6 +58,7 @@ const USAGE = `Usage:
   papyrus serve
   papyrus service <install|start|stop|restart|status>
   papyrus migrate task-history [--json]
+  papyrus automation <status|run> [--json]
   papyrus skills run <id> [--arguments-json <json>] [--run-id <id>] [--json]
   papyrus tasks plan [--json]
   papyrus tasks graph [--json]
@@ -69,6 +71,7 @@ const USAGE = `Usage:
   papyrus tasks reject <id> [--json]
   papyrus tasks retry <id> [--json]
   papyrus tasks cancel <id> [--json]
+  papyrus tasks automate <id> <on|off> [--json]
   papyrus tasks depend <id> <prerequisite-id> [--json]`;
 
 function usage(): never {
@@ -116,6 +119,20 @@ export async function runMigrationCli(args: string[], client: TaskCliClient): Pr
 	return `Migrated schema ${result.from} → ${result.to}: ${result.applied.join(", ")}`;
 }
 
+export async function runAutomationCli(args: string[], client: TaskCliClient): Promise<string> {
+	const json = args.includes("--json");
+	const positional = args.filter((argument) => argument !== "--json");
+	if (positional.length !== 1 || (positional[0] !== "status" && positional[0] !== "run")) {
+		throw new Error("automation requires exactly `status` or `run`");
+	}
+	if (positional[0] === "status") {
+		const status = await client.call<Record<string, never>, TaskAutomationSettings & { inFlight: boolean }>("automation.status", {});
+		return json ? JSON.stringify(status) : `Automation: ${status.enabled ? "enabled" : "disabled"} · interval ${status.intervalMs}ms · max ${status.maxTasksPerSweep} tasks · concurrency ${status.gateConcurrency}`;
+	}
+	const result = await client.call<Record<string, never>, TaskAutomationResult>("automation.reconcile", {});
+	return json ? JSON.stringify(result) : `Automation sweep: ${result.examined} examined · ${result.completed} completed · ${result.rejected} rejected · ${result.started} started · ${result.errors.length} errors${result.skipped ? ` · skipped ${result.skipped}` : ""}`;
+}
+
 export async function runSkillCli(args: string[], client: TaskCliClient): Promise<string> {
 	const json = args.includes("--json");
 	const positional: string[] = [];
@@ -241,6 +258,18 @@ export async function runTaskCli(args: string[], client: TaskCliClient): Promise
 			human = `${action[0]!.toUpperCase()}${action.slice(1)}: ${artifactLabel(artifact)}`;
 			break;
 		}
+		case "automate": {
+			if (!id || (dependencyId !== "on" && dependencyId !== "off") || positional.length !== 3) throw new Error("tasks automate requires a task id and on or off");
+			const artifact = await client.call<Record<string, unknown>, CliArtifact>("tasks.set_automation", {
+				id,
+				enabled: dependencyId === "on",
+				actor: "user",
+				source: "cli",
+			});
+			result = artifact;
+			human = `Automation ${dependencyId}: ${artifactLabel(artifact)}`;
+			break;
+		}
 		case "depend": {
 			if (!id || !dependencyId || positional.length !== 3) throw new Error("tasks depend requires a task id and prerequisite id");
 			const artifact = await client.call<{ id: string; dependency_id: string }, CliArtifact>("tasks.depend", {
@@ -252,7 +281,7 @@ export async function runTaskCli(args: string[], client: TaskCliClient): Promise
 			break;
 		}
 		default:
-			throw new Error("tasks action must be active, focus, graph, plan, history, complete, start, submit, reject, retry, cancel, or depend");
+			throw new Error("tasks action must be active, focus, graph, plan, history, complete, start, submit, reject, retry, cancel, automate, or depend");
 	}
 	return json ? JSON.stringify(result) : human;
 }
@@ -265,6 +294,11 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
 		console.log(await runTaskCli(args.slice(1), client));
 		return;
 	}
+	if (command === "automation") {
+		const client = await connectPapyrusClient();
+		console.log(await runAutomationCli(args.slice(1), client));
+		return;
+	}
 	if (command === "skills") {
 		const client = await connectPapyrusClient();
 		console.log(await runSkillCli(args.slice(1), client));

package/src/constants.ts

@@ -15,6 +15,7 @@ export const GATE_COMMAND_TIMEOUT_MS = 30_000;
 export const GATE_TEST_TIMEOUT_MS = 60_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;
 
 /** Compact task-context limits keep recurring prompt injection bounded. */
 export const TASK_CONTEXT_CURRENT_LIMIT = 3;
@@ -48,6 +49,19 @@ export const TASK_HISTORY_MAX_LIMIT = 100;
 export const TASK_EVENT_MAX_EVIDENCE_BYTES = 65_536;
 export const TASK_EVENT_ACTOR_MAX_LENGTH = 128;
 export const TASK_EVENT_REASON_MAX_LENGTH = 2_000;
+/** Explicitly opt-in supervised Task graph reconciliation bounds. */
+export const TASK_AUTOMATION_INTERVAL_MS = 60_000;
+export const TASK_AUTOMATION_MIN_INTERVAL_MS = 10_000;
+export const TASK_AUTOMATION_MAX_INTERVAL_MS = 3_600_000;
+export const TASK_AUTOMATION_MAX_TASKS_PER_SWEEP = 10;
+export const TASK_AUTOMATION_HARD_MAX_TASKS_PER_SWEEP = 100;
+export const TASK_AUTOMATION_GATE_CONCURRENCY = 1;
+export const TASK_AUTOMATION_MAX_GATE_CONCURRENCY = 4;
+export const TASK_AUTOMATION_MAX_RUNTIME_MS = 120_000;
+export const TASK_AUTOMATION_HARD_MAX_RUNTIME_MS = 600_000;
+export const TASK_AUTOMATION_MAX_CANDIDATE_SCAN = 1_000;
+export const TASK_AUTOMATION_ERROR_ID_MAX_LENGTH = 128;
+export const TASK_AUTOMATION_ERROR_MESSAGE_MAX_LENGTH = 500;
 export const GRAPH_RENDER_PADDING_X = 2;
 export const GRAPH_RENDER_PADDING_Y = 1;
 export const GRAPH_RENDER_BOX_PADDING = 0;

package/src/daemon.ts

@@ -1,12 +1,15 @@
 import { DAEMON_HOST, DB_OPTIMIZE_INTERVAL_MS, WAL_CHECKPOINT_INTERVAL_MS, dbPath } from "./constants.ts";
 import { clearDaemonPort, daemonStateDir, loadOrCreateToken, writeDaemonPort } from "./daemon-state.ts";
 import { createApp, createPapyrusService } from "./service.ts";
+import { scheduleTaskAutomation, taskAutomationSettings, type TaskAutomationResult } from "./task-automation.ts";
+import { logEvent } from "./log.ts";
 
 /** Start the supervised, long-running Papyrus service. */
 export function serveMain(): void {
 	const stateDir = daemonStateDir();
 	const token = loadOrCreateToken(stateDir);
-	const service = createPapyrusService(dbPath());
+	const automation = taskAutomationSettings(process.env);
+	const service = createPapyrusService(dbPath(), { automation });
 	const app = createApp({ service, token });
 	const server = Bun.serve({
 		hostname: DAEMON_HOST,
@@ -19,11 +22,23 @@ export function serveMain(): void {
 	}
 	writeDaemonPort(stateDir, server.port);
 	const checkpointTimer = setInterval(() => {
-		try { service.checkpoint(); } catch (error) { console.error("[papyrus] checkpoint failed", error); }
+		try { service.checkpoint(); } catch (error) { logEvent("error", "checkpoint_failed", { message: error instanceof Error ? error.message : String(error) }); }
 	}, WAL_CHECKPOINT_INTERVAL_MS);
 	const optimizeTimer = setInterval(() => {
-		try { service.optimize(); } catch (error) { console.error("[papyrus] optimize failed", error); }
+		try { service.optimize(); } catch (error) { logEvent("error", "optimize_failed", { message: error instanceof Error ? error.message : String(error) }); }
 	}, DB_OPTIMIZE_INTERVAL_MS);
+	const stopAutomation = scheduleTaskAutomation(automation, async () => {
+		const result = await service.execute("automation.reconcile", {}) as TaskAutomationResult;
+		logEvent(result.errors.length > 0 ? "warn" : "info", "automation_sweep", {
+			examined: result.examined,
+			completed: result.completed,
+			rejected: result.rejected,
+			started: result.started,
+			errors: result.errors.length,
+			timedOut: result.timedOut,
+			skipped: result.skipped,
+		});
+	}, (error) => logEvent("error", "automation_sweep_failed", { message: error instanceof Error ? error.message : String(error) }));
 
 	let stopping = false;
 	const shutdown = () => {
@@ -31,11 +46,12 @@ export function serveMain(): void {
 		stopping = true;
 		clearInterval(checkpointTimer);
 		clearInterval(optimizeTimer);
+		stopAutomation();
 		clearDaemonPort(stateDir);
 		service.close();
 		void server.stop(true).finally(() => process.exit(0));
 	};
 	process.on("SIGINT", shutdown);
 	process.on("SIGTERM", shutdown);
-	console.error(`[papyrus] listening on ${DAEMON_HOST}:${server.port}`);
+	logEvent("info", "listening", { host: DAEMON_HOST, port: server.port, automationEnabled: automation.enabled });
 }

package/src/domain/gate.ts

@@ -4,6 +4,11 @@ export interface Gate {
 	expect?: string;
 }
 
+export interface GateRunOptions {
+	/** Absolute Unix epoch deadline for the full gate sequence. */
+	deadlineMs?: number;
+}
+
 export interface GateResult {
 	gate: Gate;
 	passed: boolean;

package/src/domain/task-event.ts

@@ -13,6 +13,8 @@ export const TASK_EVENT_TYPES = [
 	"submitted",
 	"completion_attempted",
 	"gates_evaluated",
+	"automation_enabled",
+	"automation_disabled",
 	"review_rejected",
 	"retried",
 	"completed",

package/src/log.ts

@@ -0,0 +1,6 @@
+export type LogLevel = "info" | "warn" | "error";
+
+/** Credential-safe structured daemon event. Callers must pass bounded, non-sensitive fields. */
+export function logEvent(level: LogLevel, event: string, fields: Record<string, unknown> = {}): void {
+	console.error(JSON.stringify({ timestamp: new Date().toISOString(), level, component: "papyrus-daemon", event, ...fields }));
+}

package/src/ops.ts

@@ -7,7 +7,7 @@ import { exec } from "node:child_process";
 import type { Db } from "./db.ts";
 import { inTransaction } from "./db.ts";
 import type { Artifact, CreateArtifactInput } from "./domain/artifact.ts";
-import type { Gate, GateResult } from "./domain/gate.ts";
+import type { Gate, GateResult, GateRunOptions } from "./domain/gate.ts";
 export type { Artifact } from "./domain/artifact.ts";
 export type { Gate, GateResult } from "./domain/gate.ts";
 export type CreateInput = CreateArtifactInput;
@@ -20,6 +20,7 @@ import {
 	GATE_TEST_TIMEOUT_MS,
 	GATE_OUTPUT_LIMIT,
 	GATE_MAX_BUFFER_BYTES,
+	GATE_FILE_MAX_BYTES,
 } from "./constants.ts";
 
 const require_ = createRequire(import.meta.url);
@@ -234,6 +235,12 @@ export function injectableRules(db: Db): Array<{ id: string; title: string; body
 	});
 }
 
+function readBoundedGateFile(path: string): string {
+	const { readFileSync, statSync } = require_("node:fs");
+	if (statSync(path).size > GATE_FILE_MAX_BYTES) throw new Error(`file exceeds ${GATE_FILE_MAX_BYTES} bytes`);
+	return readFileSync(path, "utf-8") as string;
+}
+
 export function runGates(db: Db, artifactId: string): GateResult[] {
 	const art = getArtifact(db, artifactId);
 	if (!art) throw new Error("artifact not found");
@@ -246,9 +253,8 @@ export function runGates(db: Db, artifactId: string): GateResult[] {
 				return { gate, passed: exists, output: exists ? "exists" : "not found" };
 			}
 			case "contains": {
-				const { readFileSync } = require_("node:fs");
 				try {
-					const content = readFileSync(gate.target, "utf-8");
+					const content = readBoundedGateFile(gate.target);
 					const found = gate.expect ? content.includes(gate.expect) : content.length > 0;
 					return { gate, passed: found, output: found ? "found" : `"${gate.expect ?? ""}" not found` };
 				} catch {
@@ -299,9 +305,8 @@ function runNonProcessGate(gate: Gate): GateResult {
 		return { gate, passed: exists, output: exists ? "exists" : "not found" };
 	}
 	if (gate.type === "contains") {
-		const { readFileSync } = require_("node:fs");
 		try {
-			const content = readFileSync(gate.target, "utf-8");
+			const content = readBoundedGateFile(gate.target);
 			const found = gate.expect ? content.includes(gate.expect) : content.length > 0;
 			return { gate, passed: found, output: found ? "found" : `"${gate.expect ?? ""}" not found` };
 		} catch {
@@ -312,15 +317,21 @@ function runNonProcessGate(gate: Gate): GateResult {
 }
 
 /** Gate runner for daemon request paths; subprocess gates never block the event loop. */
-export async function runGatesAsync(db: Db, artifactId: string): Promise<GateResult[]> {
+export async function runGatesAsync(db: Db, artifactId: string, options: GateRunOptions = {}): Promise<GateResult[]> {
 	const art = getArtifact(db, artifactId);
 	if (!art) throw new Error("artifact not found");
 	const gates = (art.extra["gates"] as Gate[]) ?? [];
 	const results: GateResult[] = [];
 	for (const gate of gates) {
+		const remainingMs = options.deadlineMs === undefined ? undefined : options.deadlineMs - Date.now();
+		if (remainingMs !== undefined && remainingMs <= 0) {
+			results.push({ gate, passed: false, output: "gate runtime deadline exceeded" });
+			continue;
+		}
 		if (gate.type === "command" || gate.type === "test") {
 			const command = gate.type === "test" ? `npx vitest run ${gate.target} --reporter=dot` : gate.target;
-			const timeout = gate.type === "test" ? GATE_TEST_TIMEOUT_MS : GATE_COMMAND_TIMEOUT_MS;
+			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);
 			results.push({
 				gate,

package/src/ports/gate-runner.ts

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

package/src/service.ts

@@ -13,6 +13,7 @@ import type { GateRunner } from "./ports/gate-runner.ts";
 import type { TaskEventStore } from "./ports/task-event-store.ts";
 import { projectTaskExecution } from "./task-execution.ts";
 import { Tasks, type TaskStatus } from "./task-service.ts";
+import { TaskAutomationReconciler, taskAutomationSettings, type TaskAutomationSettings } from "./task-automation.ts";
 import {
 	createArtifactTemplate,
 	createDocument,
@@ -40,6 +41,8 @@ import { instantiateSkillWorkflow } from "./skill-execution.ts";
 
 export const EXPECTED_OPERATION_NAMES = [
 	"system.migrate",
+	"automation.status",
+	"automation.reconcile",
 	"artifact.create",
 	"artifact.query",
 	"artifact.show",
@@ -61,6 +64,7 @@ export const EXPECTED_OPERATION_NAMES = [
 	"tasks.complete",
 	"tasks.run_gates",
 	"tasks.set_checklist",
+	"tasks.set_automation",
 	"tasks.context",
 	"tasks.reject",
 	"tasks.retry",
@@ -144,6 +148,7 @@ function handlers(
 	artifacts: ArtifactStore,
 	gates: GateRunner,
 	tasks: Tasks,
+	automation: TaskAutomationReconciler,
 	events: TaskEventStore,
 	migrate: () => unknown,
 ): Record<OperationName, OperationHandler> {
@@ -164,6 +169,8 @@ function handlers(
 	});
 	return {
 		"system.migrate": () => migrate(),
+		"automation.status": () => automation.status(),
+		"automation.reconcile": () => automation.reconcile(),
 		"artifact.create": (input) => {
 			const normalized = normalizeCreateInput(input);
 			if (normalized.kind !== "task") return artifacts.create(normalized);
@@ -241,6 +248,10 @@ function handlers(
 		"tasks.complete": (input) => tasks.completeAsync(string(input, "id"), eventContext(input)),
 		"tasks.run_gates": (input) => tasks.runGates(string(input, "id"), eventContext(input)),
 		"tasks.set_checklist": (input) => tasks.setChecklist(string(input, "id"), input["checklist"] as Checklist),
+		"tasks.set_automation": (input) => {
+			if (typeof input["enabled"] !== "boolean") throw new Error("enabled must be a boolean");
+			return tasks.setAutomation(string(input, "id"), input["enabled"], eventContext(input));
+		},
 		"tasks.context": () => taskContext(artifacts, tasks.active()?.id),
 		"tasks.reject": (input) => tasks.transition(string(input, "id"), "reject", eventContext(input)),
 		"tasks.retry": (input) => tasks.transition(string(input, "id"), "retry", eventContext(input)),
@@ -293,14 +304,15 @@ function handlers(
 	};
 }
 
-export function createPapyrusService(path: string): PapyrusService {
+export function createPapyrusService(path: string, options: { automation?: TaskAutomationSettings } = {}): PapyrusService {
 	const db = openDb(path);
 	const artifacts = new SQLiteArtifactStore(db);
 	const gates = new SQLiteGateRunner(db);
 	const focus = new SQLiteTaskFocusStore(db);
 	const events = new SQLiteTaskEventStore(db);
 	const tasks = new Tasks(artifacts, gates, focus, events);
-	const registry = handlers(artifacts, gates, tasks, events, () => migrateDb(db));
+	const automation = new TaskAutomationReconciler(tasks, options.automation ?? taskAutomationSettings({}));
+	const registry = handlers(artifacts, gates, tasks, automation, events, () => migrateDb(db));
 	const state = (): SchemaState => {
 		const current = schemaVersion(db);
 		return { current, required: SQLITE_SCHEMA_VERSION, migrationRequired: current !== SQLITE_SCHEMA_VERSION };
@@ -311,7 +323,7 @@ export function createPapyrusService(path: string): PapyrusService {
 		async execute(operation, input = {}) {
 			const handler = registry[operation as OperationName];
 			if (!handler) throw new UnknownOperationError(`unknown operation "${operation}"`);
-			if (operation !== "system.migrate" && state().migrationRequired) {
+			if (operation !== "system.migrate" && operation !== "automation.status" && state().migrationRequired) {
 				throw new MigrationRequiredError("database migration required; run `papyrus migrate task-history`");
 			}
 			return handler(input);

package/src/task-automation.ts

@@ -0,0 +1,188 @@
+import {
+	TASK_AUTOMATION_ERROR_ID_MAX_LENGTH,
+	TASK_AUTOMATION_ERROR_MESSAGE_MAX_LENGTH,
+	TASK_AUTOMATION_GATE_CONCURRENCY,
+	TASK_AUTOMATION_HARD_MAX_RUNTIME_MS,
+	TASK_AUTOMATION_HARD_MAX_TASKS_PER_SWEEP,
+	TASK_AUTOMATION_INTERVAL_MS,
+	TASK_AUTOMATION_MAX_CANDIDATE_SCAN,
+	TASK_AUTOMATION_MAX_GATE_CONCURRENCY,
+	TASK_AUTOMATION_MAX_INTERVAL_MS,
+	TASK_AUTOMATION_MAX_RUNTIME_MS,
+	TASK_AUTOMATION_MAX_TASKS_PER_SWEEP,
+	TASK_AUTOMATION_MIN_INTERVAL_MS,
+} from "./constants.ts";
+import type { Artifact } from "./domain/artifact.ts";
+import { projectTaskExecution } from "./task-execution.ts";
+import type { Tasks } from "./task-service.ts";
+
+export interface TaskAutomationSettings {
+	enabled: boolean;
+	intervalMs: number;
+	maxTasksPerSweep: number;
+	gateConcurrency: number;
+	maxRuntimeMs: number;
+}
+
+export interface TaskAutomationResult {
+	skipped?: "disabled" | "in-flight";
+	examined: number;
+	completed: number;
+	rejected: number;
+	started: number;
+	errors: Array<{ taskId: string; message: string }>;
+	timedOut: boolean;
+}
+
+function boundedInteger(
+	env: Record<string, string | undefined>,
+	name: string,
+	fallback: number,
+	minimum: number,
+	maximum: number,
+): number {
+	const source = env[name];
+	if (source === undefined || source === "") return fallback;
+	const value = Number(source);
+	if (!Number.isInteger(value) || value < minimum || value > maximum) {
+		throw new Error(`${name} must be an integer between ${minimum} and ${maximum}`);
+	}
+	return value;
+}
+
+export function taskAutomationSettings(env: Record<string, string | undefined> = process.env): TaskAutomationSettings {
+	const enabled = env["PAPYRUS_AUTOMATION_ENABLED"] === "1";
+	if (env["PAPYRUS_AUTOMATION_ENABLED"] !== undefined && env["PAPYRUS_AUTOMATION_ENABLED"] !== "0" && !enabled) {
+		throw new Error("PAPYRUS_AUTOMATION_ENABLED must be 0 or 1");
+	}
+	return {
+		enabled,
+		intervalMs: boundedInteger(env, "PAPYRUS_AUTOMATION_INTERVAL_MS", TASK_AUTOMATION_INTERVAL_MS, TASK_AUTOMATION_MIN_INTERVAL_MS, TASK_AUTOMATION_MAX_INTERVAL_MS),
+		maxTasksPerSweep: boundedInteger(env, "PAPYRUS_AUTOMATION_MAX_TASKS", TASK_AUTOMATION_MAX_TASKS_PER_SWEEP, 1, TASK_AUTOMATION_HARD_MAX_TASKS_PER_SWEEP),
+		gateConcurrency: boundedInteger(env, "PAPYRUS_AUTOMATION_GATE_CONCURRENCY", TASK_AUTOMATION_GATE_CONCURRENCY, 1, TASK_AUTOMATION_MAX_GATE_CONCURRENCY),
+		maxRuntimeMs: boundedInteger(env, "PAPYRUS_AUTOMATION_MAX_RUNTIME_MS", TASK_AUTOMATION_MAX_RUNTIME_MS, 1, TASK_AUTOMATION_HARD_MAX_RUNTIME_MS),
+	};
+}
+
+function automationEnabled(task: Artifact): boolean {
+	const automation = task.extra["automation"];
+	return typeof automation === "object"
+		&& automation !== null
+		&& !Array.isArray(automation)
+		&& (automation as Record<string, unknown>)["enabled"] === true;
+}
+
+function emptyResult(skipped?: TaskAutomationResult["skipped"]): TaskAutomationResult {
+	return { ...(skipped ? { skipped } : {}), examined: 0, completed: 0, rejected: 0, started: 0, errors: [], timedOut: false };
+}
+
+function boundedError(taskId: string, error: unknown): TaskAutomationResult["errors"][number] {
+	const message = error instanceof Error ? error.message : String(error);
+	return {
+		taskId: taskId.slice(0, TASK_AUTOMATION_ERROR_ID_MAX_LENGTH),
+		message: message.slice(0, TASK_AUTOMATION_ERROR_MESSAGE_MAX_LENGTH),
+	};
+}
+
+export interface TaskAutomationScheduler {
+	setInterval(callback: () => void, intervalMs: number): unknown;
+	clearInterval(handle: unknown): void;
+}
+
+const SYSTEM_SCHEDULER: TaskAutomationScheduler = {
+	setInterval: (callback, intervalMs) => setInterval(callback, intervalMs),
+	clearInterval: (handle) => clearInterval(handle as ReturnType<typeof setInterval>),
+};
+
+export function scheduleTaskAutomation(
+	settings: TaskAutomationSettings,
+	sweep: () => Promise<unknown>,
+	onError: (error: unknown) => void,
+	scheduler: TaskAutomationScheduler = SYSTEM_SCHEDULER,
+): () => void {
+	if (!settings.enabled) return () => {};
+	const handle = scheduler.setInterval(() => { void sweep().catch(onError); }, settings.intervalMs);
+	return () => scheduler.clearInterval(handle);
+}
+
+export class TaskAutomationReconciler {
+	private inFlight = false;
+
+	constructor(
+		private readonly tasks: Tasks,
+		private readonly settings: TaskAutomationSettings,
+		private readonly now: () => number = () => Date.now(),
+	) {}
+
+	status(): TaskAutomationSettings & { inFlight: boolean } {
+		return { ...this.settings, inFlight: this.inFlight };
+	}
+
+	async reconcile(): Promise<TaskAutomationResult> {
+		if (!this.settings.enabled) return emptyResult("disabled");
+		if (this.inFlight) return emptyResult("in-flight");
+		this.inFlight = true;
+		try { return await this.runSweep(); }
+		finally { this.inFlight = false; }
+	}
+
+	private async runSweep(): Promise<TaskAutomationResult> {
+		const result = emptyResult();
+		const deadline = this.now() + this.settings.maxRuntimeMs;
+		const candidates = this.tasks.list({ status: "review", limit: TASK_AUTOMATION_MAX_CANDIDATE_SCAN })
+			.filter(automationEnabled)
+			.sort((left, right) => left.id.localeCompare(right.id))
+			.slice(0, this.settings.maxTasksPerSweep);
+		const completedIds = new Set<string>();
+
+		for (let offset = 0; offset < candidates.length; offset += this.settings.gateConcurrency) {
+			if (this.now() >= deadline) { result.timedOut = true; break; }
+			const batch = candidates.slice(offset, offset + this.settings.gateConcurrency);
+			await Promise.all(batch.map(async (task) => {
+				result.examined += 1;
+				try {
+					const completion = await this.tasks.completeAsync(task.id, {
+						actor: "daemon",
+						source: "automation-reconciler",
+						reason: "automation-enabled review reconciliation",
+					}, { focusSuccessor: false, gateDeadlineMs: deadline });
+					if (completion.completed) {
+						result.completed += 1;
+						completedIds.add(task.id);
+					} else result.rejected += 1;
+				} catch (error) {
+					result.errors.push(boundedError(task.id, error));
+				}
+			}));
+		}
+
+		let remaining = Math.max(0, this.settings.maxTasksPerSweep - result.examined);
+		if (remaining > 0 && completedIds.size > 0 && this.now() < deadline) {
+			let graph: ReturnType<Tasks["graph"]>;
+			try { graph = this.tasks.graph(); }
+			catch (error) {
+				result.errors.push(boundedError("graph", error));
+				return result;
+			}
+			const stateById = new Map(projectTaskExecution(graph).nodes.map((node) => [node.id, node.state]));
+			for (const node of [...graph.nodes].sort((left, right) => left.task.id.localeCompare(right.task.id))) {
+				if (remaining === 0 || this.now() >= deadline) break;
+				if (node.task.status !== "todo" || !automationEnabled(node.task) || stateById.get(node.task.id) !== "ready") continue;
+				if (!node.dependencyIds.some((id) => completedIds.has(id))) continue;
+				try {
+					this.tasks.transition(node.task.id, "start", {
+						actor: "daemon",
+						source: "automation-reconciler",
+						reason: "automation-enabled successor became ready",
+					});
+					result.started += 1;
+					remaining -= 1;
+				} catch (error) {
+					result.errors.push(boundedError(node.task.id, error));
+				}
+			}
+		}
+		if (this.now() >= deadline) result.timedOut = true;
+		return result;
+	}
+}

package/src/task-service.ts

@@ -46,6 +46,11 @@ export interface ChecklistReview {
 	reason?: string;
 }
 
+export interface TaskCompletionOptions {
+	focusSuccessor?: boolean;
+	gateDeadlineMs?: number;
+}
+
 export interface TaskCompletion {
 	artifact: Artifact;
 	gates: GateResult[];
@@ -215,23 +220,23 @@ export class Tasks {
 		});
 	}
 
-	complete(id: string, context: TaskEventContext = {}): TaskCompletion {
+	complete(id: string, context: TaskEventContext = {}, options: TaskCompletionOptions = {}): TaskCompletion {
 		const task = this.requireReview(id);
 		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);
-		return this.resolveCompletion(id, attemptId, results, checklist, context);
+		return this.resolveCompletion(id, attemptId, results, checklist, context, options);
 	}
 
-	async completeAsync(id: string, context: TaskEventContext = {}): Promise<TaskCompletion> {
+	async completeAsync(id: string, context: TaskEventContext = {}, options: TaskCompletionOptions = {}): Promise<TaskCompletion> {
 		const task = this.requireReview(id);
 		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);
+		const results = await this.gates.runAsync(id, { deadlineMs: options.gateDeadlineMs });
 		this.requireReview(id);
-		return this.resolveCompletion(id, attemptId, results, checklist, context);
+		return this.resolveCompletion(id, attemptId, results, checklist, context, options);
 	}
 
 	async runGates(id: string, context: TaskEventContext = {}): Promise<GateResult[]> {
@@ -251,6 +256,19 @@ export class Tasks {
 		return this.artifacts.setExtra(id, { ...task.extra, checklist: validateChecklist(checklist) })!;
 	}
 
+	setAutomation(id: string, enabled: boolean, context: TaskEventContext = {}): Artifact {
+		return this.events.atomic(() => {
+			const task = this.require(id);
+			const current = task.extra["automation"];
+			const automation = typeof current === "object" && current !== null && !Array.isArray(current)
+				? current as Record<string, unknown>
+				: {};
+			const updated = this.artifacts.setExtra(id, { ...task.extra, automation: { ...automation, enabled } })!;
+			this.appendEvent({ taskId: id, type: enabled ? "automation_enabled" : "automation_disabled" }, context);
+			return updated;
+		});
+	}
+
 	depend(id: string, dependencyId: string): Artifact {
 		this.require(id);
 		this.require(dependencyId);
@@ -345,6 +363,7 @@ export class Tasks {
 		gates: GateResult[],
 		checklist: ChecklistReview[],
 		context: TaskEventContext,
+		options: TaskCompletionOptions,
 	): TaskCompletion {
 		const failed = gates.some((gate) => !gate.passed) || checklist.some((item) => !item.accepted);
 		if (failed) {
@@ -361,10 +380,10 @@ export class Tasks {
 				return { artifact, gates, checklist, completed: false, focused: this.active(), blocked: [] };
 			});
 		}
-		return this.events.atomic(() => this.finish(id, attemptId, gates, checklist, context));
+		return this.events.atomic(() => this.finish(id, attemptId, gates, checklist, context, options));
 	}
 
-	private finish(id: string, attemptId: string, gates: GateResult[], checklist: ChecklistReview[], context: TaskEventContext): TaskCompletion {
+	private finish(id: string, attemptId: string, gates: GateResult[], checklist: ChecklistReview[], context: TaskEventContext, options: TaskCompletionOptions): TaskCompletion {
 		const successorIds = this.relationships(id)
 			.filter((edge) => edge.relation === "depends_on" && edge.to === id)
 			.map((edge) => edge.from);
@@ -392,7 +411,7 @@ export class Tasks {
 				blocked.push({ artifact: successor, dependencyIds });
 				continue;
 			}
-			if (!focused) {
+			if (options.focusSuccessor !== false && !focused) {
 				this.focusStore.set(successor.id);
 				focused = successor;
 			}