@danypops/papyrus 0.7.0 → 0.8.0

package/src/daemon.ts

@@ -1,15 +1,13 @@
 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 automation = taskAutomationSettings(process.env);
-	const service = createPapyrusService(dbPath(), { automation });
+	const service = createPapyrusService(dbPath());
 	const app = createApp({ service, token });
 	const server = Bun.serve({
 		hostname: DAEMON_HOST,
@@ -27,31 +25,17 @@ export function serveMain(): void {
 	const optimizeTimer = setInterval(() => {
 		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 = () => {
 		if (stopping) return;
 		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);
-	logEvent("info", "listening", { host: DAEMON_HOST, port: server.port, automationEnabled: automation.enabled });
+	logEvent("info", "listening", { host: DAEMON_HOST, port: server.port });
 }

package/src/db.ts

@@ -100,6 +100,8 @@ CREATE TABLE IF NOT EXISTS relation_names (
 CREATE TABLE IF NOT EXISTS task_focus (
 	scope       TEXT PRIMARY KEY CHECK (scope = 'global'),
 	task_id     TEXT NOT NULL UNIQUE REFERENCES artifacts(id),
+	status      TEXT NOT NULL CHECK (status IN ('active', 'paused')),
+	pause_reason TEXT,
 	updated_at  TEXT NOT NULL
 );
 CREATE TABLE IF NOT EXISTS task_events (
@@ -140,7 +142,7 @@ CREATE TABLE IF NOT EXISTS task_views (
 
 const SEED_SQL = `
 INSERT OR IGNORE INTO kinds VALUES ('doc','Knowledge — what we know (specs, decisions, research, designs)');
-INSERT OR IGNORE INTO kinds VALUES ('task','Work — what we are doing (goals, steps, checklists)');
+INSERT OR IGNORE INTO kinds VALUES ('task','Work — what we are doing (objectives, steps, checklists)');
 INSERT OR IGNORE INTO kinds VALUES ('rule','Governance — when doing X, follow Y');
 INSERT OR IGNORE INTO kinds VALUES ('skill','Parameterized workflow bundle — inputs and templates load tasks, rules, and docs');
 INSERT OR IGNORE INTO statuses VALUES ('draft','doc');
@@ -199,7 +201,7 @@ export function migrateDb(db: Db): MigrationResult {
 		throw new Error(`database schema ${from} is newer than supported ${SQLITE_SCHEMA_VERSION}`);
 	}
 	if (from === SQLITE_SCHEMA_VERSION) return { from, to: from, applied: [] };
-	if (from !== 1 && from !== 2 && from !== 3) throw new Error(`no explicit migration path from database schema ${from}`);
+	if (from !== 1 && from !== 2 && from !== 3 && from !== 4) throw new Error(`no explicit migration path from database schema ${from}`);
 	const applied: string[] = [];
 
 	inTransaction(db, () => {
@@ -280,6 +282,14 @@ export function migrateDb(db: Db): MigrationResult {
 			`);
 			applied.push("task-project-scope");
 		}
+		if (schemaVersion(db) === 4) {
+			db.exec(`
+				ALTER TABLE task_focus ADD COLUMN status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'paused'));
+				ALTER TABLE task_focus ADD COLUMN pause_reason TEXT;
+				PRAGMA user_version = 5;
+			`);
+			applied.push("task-focus-continuation");
+		}
 	});
 	return { from, to: schemaVersion(db), applied };
 }

package/src/domain/artifact.ts

@@ -30,6 +30,12 @@ export interface CreateArtifactInput {
 	templateId?: string;
 }
 
+export interface UpdateArtifactInput {
+	title?: string;
+	body?: string;
+	labels?: string[];
+}
+
 export interface ArtifactQuery {
 	kind?: string;
 	status?: string;

package/src/domain/task-event.ts

@@ -9,12 +9,15 @@ export type TaskLifecycleStatus = "todo" | "in-progress" | "review" | "rejected"
 
 export const TASK_EVENT_TYPES = [
 	"created",
+	"updated",
 	"started",
 	"submitted",
 	"completion_attempted",
 	"gates_evaluated",
-	"automation_enabled",
-	"automation_disabled",
+	"focus_set",
+	"focus_paused",
+	"focus_unpaused",
+	"focus_cleared",
 	"project_assigned",
 	"review_rejected",
 	"retried",

package/src/ops.ts

@@ -6,7 +6,7 @@ import { createRequire } from "node:module";
 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 { Artifact, CreateArtifactInput, UpdateArtifactInput } from "./domain/artifact.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";
@@ -204,6 +204,22 @@ export function linkArtifacts(db: Db, fromId: string, relation: string, toId: st
 	});
 }
 
+export function updateArtifactContent(db: Db, id: string, input: UpdateArtifactInput): Artifact | null {
+	const artifact = getArtifact(db, id);
+	if (!artifact) return null;
+	const now = new Date().toISOString();
+	inTransaction(db, () => {
+		db.prepare("UPDATE artifacts SET title = ?, body = ?, labels = ?, updated_at = ? WHERE id = ?").run(
+			input.title ?? artifact.title,
+			input.body ?? artifact.body,
+			JSON.stringify(input.labels ?? artifact.labels),
+			now,
+			id,
+		);
+	});
+	return getArtifact(db, id);
+}
+
 export function updateStatus(db: Db, id: string, status: string): Artifact | null {
 	const art = getArtifact(db, id);
 	if (!art) return null;

package/src/ports/artifact-store.ts

@@ -6,6 +6,7 @@ import type {
 	ArtifactQuery,
 	CreateArtifactInput,
 	RelationshipQuery,
+	UpdateArtifactInput,
 } from "../domain/artifact.ts";
 
 export interface ArtifactStore {
@@ -15,5 +16,6 @@ export interface ArtifactStore {
 	link(link: ArtifactLink): void;
 	setStatus(id: string, status: string): Artifact | null;
 	setExtra(id: string, extra: Record<string, unknown>): Artifact | null;
+	updateContent(id: string, input: UpdateArtifactInput): Artifact | null;
 	relationships(filter?: RelationshipQuery): ArtifactEdge[];
 }

package/src/ports/task-focus-store.ts

@@ -1,21 +1,43 @@
+export type TaskFocusStatus = "active" | "paused";
+
+export interface TaskFocusState {
+	taskId: string;
+	status: TaskFocusStatus;
+	updatedAt: string;
+	pauseReason?: string;
+}
+
 export interface TaskFocusStore {
-	get(): string | undefined;
-	set(taskId: string): void;
+	get(): TaskFocusState | undefined;
+	set(taskId: string): TaskFocusState;
+	pause(taskId: string, reason?: string): TaskFocusState;
+	unpause(taskId: string): TaskFocusState;
 	clear(taskId?: string): void;
 }
 
 export class InMemoryTaskFocusStore implements TaskFocusStore {
-	private taskId: string | undefined;
+	private state: TaskFocusState | undefined;
+
+	get(): TaskFocusState | undefined { return this.state; }
+
+	set(taskId: string): TaskFocusState {
+		this.state = { taskId, status: "active", updatedAt: new Date().toISOString() };
+		return this.state;
+	}
 
-	get(): string | undefined {
-		return this.taskId;
+	pause(taskId: string, reason?: string): TaskFocusState {
+		if (this.state?.taskId !== taskId) throw new Error(`task "${taskId}" is not focused`);
+		this.state = { ...this.state, status: "paused", updatedAt: new Date().toISOString(), ...(reason ? { pauseReason: reason } : {}) };
+		return this.state;
 	}
 
-	set(taskId: string): void {
-		this.taskId = taskId;
+	unpause(taskId: string): TaskFocusState {
+		if (this.state?.taskId !== taskId) throw new Error(`task "${taskId}" is not focused`);
+		this.state = { taskId, status: "active", updatedAt: new Date().toISOString() };
+		return this.state;
 	}
 
 	clear(taskId?: string): void {
-		if (taskId === undefined || taskId === this.taskId) this.taskId = undefined;
+		if (taskId === undefined || this.state?.taskId === taskId) this.state = undefined;
 	}
 }

package/src/service.ts

@@ -16,7 +16,6 @@ import type { TaskEventStore } from "./ports/task-event-store.ts";
 import type { TaskScopeStore } from "./ports/task-scope-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,
@@ -44,8 +43,6 @@ import { instantiateSkillWorkflow } from "./skill-execution.ts";
 
 export const EXPECTED_OPERATION_NAMES = [
 	"system.migrate",
-	"automation.status",
-	"automation.reconcile",
 	"artifact.create",
 	"artifact.query",
 	"artifact.show",
@@ -55,6 +52,7 @@ export const EXPECTED_OPERATION_NAMES = [
 	"gates.run",
 	"rules.injectable",
 	"tasks.create",
+	"tasks.update",
 	"tasks.list",
 	"tasks.graph",
 	"tasks.plan",
@@ -64,13 +62,16 @@ export const EXPECTED_OPERATION_NAMES = [
 	"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.set_automation",
 	"tasks.context",
 	"tasks.reject",
 	"tasks.retry",
@@ -123,6 +124,13 @@ function optionalString(input: OperationInput, key: string): string | undefined
 	return value;
 }
 
+function optionalStringArray(input: OperationInput, key: string): string[] | undefined {
+	const value = input[key];
+	if (value === undefined) return undefined;
+	if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) throw new Error(`${key} must be an array of strings`);
+	return value as string[];
+}
+
 function optionalNumber(input: OperationInput, key: string): number | undefined {
 	const value = input[key];
 	if (value === undefined) return undefined;
@@ -154,7 +162,6 @@ function handlers(
 	artifacts: ArtifactStore,
 	gates: GateRunner,
 	tasks: Tasks,
-	automation: TaskAutomationReconciler,
 	events: TaskEventStore,
 	scopes: TaskScopeStore,
 	migrate: () => unknown,
@@ -169,18 +176,19 @@ function handlers(
 		const context = eventContext(input);
 		return { ...context, source: context.source ?? source };
 	};
-	const taskFilter = (input: OperationInput) => ({
+	const artifactFilter = (input: OperationInput) => ({
 		status: optionalString(input, "status"),
 		text: optionalString(input, "text"),
 		limit: optionalNumber(input, "limit"),
+	});
+	const taskFilter = (input: OperationInput) => ({
+		...artifactFilter(input),
 		projectRoot: string(input, "project_root"),
 		scope: optionalString(input, "scope") as TaskViewMode | undefined,
 		rootTaskId: optionalString(input, "root_task_id"),
 	});
 	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);
@@ -246,6 +254,11 @@ function handlers(
 			projectRoot: string(input, "project_root"),
 			projectSource: "cwd",
 		}, eventContext(input)),
+		"tasks.update": (input) => tasks.update(string(input, "id"), {
+			...(input["title"] !== undefined ? { title: optionalString(input, "title")! } : {}),
+			...(input["body"] !== undefined ? { body: optionalString(input, "body")! } : {}),
+			...(input["labels"] !== undefined ? { labels: optionalStringArray(input, "labels")! } : {}),
+		}, eventContext(input)),
 		"tasks.list": (input) => tasks.list(taskFilter(input)),
 		"tasks.graph": (input) => tasks.graph(taskFilter(input)),
 		"tasks.plan": (input) => projectTaskExecution(tasks.graph(taskFilter(input))),
@@ -267,16 +280,16 @@ function handlers(
 			eventContext(input),
 		),
 		"tasks.active": (input) => tasks.active(taskFilter(input)),
-		"tasks.focus": (input) => tasks.focus(string(input, "id")),
+		"tasks.focused": (input) => tasks.focused(taskFilter(input)),
+		"tasks.focus": (input) => tasks.focus(string(input, "id"), eventContext(input)),
+		"tasks.pause": (input) => tasks.pauseFocus(eventContext(input)),
+		"tasks.unpause": (input) => tasks.unpauseFocus(eventContext(input)),
+		"tasks.clear_focus": (input) => tasks.clearFocus(eventContext(input)),
 		"tasks.start": (input) => tasks.transition(string(input, "id"), "start", eventContext(input)),
 		"tasks.submit": (input) => tasks.transition(string(input, "id"), "submit", eventContext(input)),
 		"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": (input) => taskContext(artifacts, tasks.active()?.id, new Set(tasks.list(taskFilter(input)).map((task) => task.id))),
 		"tasks.reject": (input) => tasks.transition(string(input, "id"), "reject", eventContext(input)),
 		"tasks.retry": (input) => tasks.transition(string(input, "id"), "retry", eventContext(input)),
@@ -288,7 +301,7 @@ function handlers(
 			labels: input["labels"] as string[] | undefined, extra: input["extra"] as Record<string, unknown> | undefined,
 			templateId: optionalString(input, "template_id") ?? optionalString(input, "templateId"),
 		}),
-		"docs.list": (input) => listDocuments(artifacts, taskFilter(input)),
+		"docs.list": (input) => listDocuments(artifacts, artifactFilter(input)),
 		"docs.show": (input) => showDocument(artifacts, string(input, "id")),
 		"docs.activate": (input) => transitionDocument(artifacts, string(input, "id"), "activate"),
 		"docs.archive": (input) => transitionDocument(artifacts, string(input, "id"), "archive"),
@@ -300,7 +313,7 @@ function handlers(
 			severity: optionalString(input, "severity") as "block" | "warn" | "info" | undefined,
 			labels: input["labels"] as string[] | undefined, extra: input["extra"] as Record<string, unknown> | undefined,
 		}),
-		"rules.list": (input) => listRules(artifacts, taskFilter(input)),
+		"rules.list": (input) => listRules(artifacts, artifactFilter(input)),
 		"rules.show": (input) => showRule(artifacts, string(input, "id")),
 		"rules.preview": (input) => previewRule(artifacts, string(input, "id")),
 		"rules.enable": (input) => transitionRule(artifacts, string(input, "id"), "enable"),
@@ -316,7 +329,7 @@ function handlers(
 			title: string(input, "title"), targetKind: string(input, "target_kind"), defaults: input["defaults"] as Record<string, unknown> | undefined,
 			required: input["required"] as string[] | undefined, body: optionalString(input, "body"), labels: input["labels"] as string[] | undefined,
 		}),
-		"skills.list": (input) => listSkills(artifacts, taskFilter(input)),
+		"skills.list": (input) => listSkills(artifacts, artifactFilter(input)),
 		"skills.show": (input) => showSkill(artifacts, string(input, "id")),
 		"skills.invoke": (input) => skillInvocation(artifacts, string(input, "id")),
 		"skills.run": (input) => instantiateSkillWorkflow(artifacts, string(input, "id"), {
@@ -343,7 +356,7 @@ function handlers(
 	};
 }
 
-export function createPapyrusService(path: string, options: { automation?: TaskAutomationSettings } = {}): PapyrusService {
+export function createPapyrusService(path: string): PapyrusService {
 	const db = openDb(path);
 	const artifacts = new SQLiteArtifactStore(db);
 	const gates = new SQLiteGateRunner(db);
@@ -351,8 +364,7 @@ export function createPapyrusService(path: string, options: { automation?: TaskA
 	const events = new SQLiteTaskEventStore(db);
 	const scopes = new SQLiteTaskScopeStore(db);
 	const tasks = new Tasks(artifacts, gates, focus, events, scopes);
-	const automation = new TaskAutomationReconciler(tasks, options.automation ?? taskAutomationSettings({}));
-	const registry = handlers(artifacts, gates, tasks, automation, events, scopes, () => migrateDb(db));
+	const registry = handlers(artifacts, gates, tasks, events, scopes, () => migrateDb(db));
 	const state = (): SchemaState => {
 		const current = schemaVersion(db);
 		return { current, required: SQLITE_SCHEMA_VERSION, migrationRequired: current !== SQLITE_SCHEMA_VERSION };
@@ -363,8 +375,8 @@ export function createPapyrusService(path: string, options: { automation?: TaskA
 		async execute(operation, input = {}) {
 			const handler = registry[operation as OperationName];
 			if (!handler) throw new UnknownOperationError(`unknown operation "${operation}"`);
-			if (operation !== "system.migrate" && operation !== "automation.status" && state().migrationRequired) {
-				throw new MigrationRequiredError("database migration required; run `papyrus migrate task-scope`");
+			if (operation !== "system.migrate" && state().migrationRequired) {
+				throw new MigrationRequiredError("database migration required; run `papyrus migrate task-focus`");
 			}
 			return handler(input);
 		},

package/src/task-service.ts

@@ -1,4 +1,13 @@
-import { TASK_EXECUTION_MAX_DEGREE, TASK_EXECUTION_MAX_EDGES, TASK_EXECUTION_MAX_NODES, TASK_SCOPE_MAX_TASKS } from "./constants.ts";
+import {
+	TASK_BODY_MAX_LENGTH,
+	TASK_EXECUTION_MAX_DEGREE,
+	TASK_EXECUTION_MAX_EDGES,
+	TASK_EXECUTION_MAX_NODES,
+	TASK_LABEL_MAX_COUNT,
+	TASK_LABEL_MAX_LENGTH,
+	TASK_SCOPE_MAX_TASKS,
+	TASK_TITLE_MAX_LENGTH,
+} from "./constants.ts";
 import type { Artifact } from "./domain/artifact.ts";
 import { checklistEntries, validateChecklist, type Checklist, type ProofReference } from "./domain/checklist.ts";
 import type { Gate, GateResult } from "./domain/gate.ts";
@@ -6,11 +15,17 @@ import type { AppendTaskEvent, TaskEventContext, TaskHistoryPage, TaskHistoryQue
 import { normalizeProjectRoot, taskScopeLabel, type TaskScopeSource, type TaskViewMode, type TaskViewSelection } from "./domain/task-scope.ts";
 import type { ArtifactStore } from "./ports/artifact-store.ts";
 import type { GateRunner } from "./ports/gate-runner.ts";
-import { InMemoryTaskFocusStore, type TaskFocusStore } from "./ports/task-focus-store.ts";
+import { InMemoryTaskFocusStore, type TaskFocusStatus, type TaskFocusStore } from "./ports/task-focus-store.ts";
 import { InMemoryTaskEventStore, type TaskEventStore } from "./ports/task-event-store.ts";
 import { InMemoryTaskScopeStore, type TaskScopeStore } from "./ports/task-scope-store.ts";
 import { assertDependencyEdgeAllowed } from "./task-execution.ts";
 
+export interface UpdateTaskInput {
+	title?: string;
+	body?: string;
+	labels?: string[];
+}
+
 export interface TaskFilter {
 	status?: string;
 	text?: string;
@@ -53,6 +68,13 @@ export interface ChecklistReview {
 	reason?: string;
 }
 
+export interface TaskFocus {
+	artifact: Artifact;
+	status: TaskFocusStatus;
+	updatedAt: string;
+	pauseReason?: string;
+}
+
 export interface TaskCompletionOptions {
 	focusSuccessor?: boolean;
 	gateDeadlineMs?: number;
@@ -70,6 +92,7 @@ export interface TaskCompletion {
 export interface TaskNode {
 	task: Artifact;
 	active?: boolean;
+	focusStatus?: TaskFocusStatus;
 	parentIds: string[];
 	childIds: string[];
 	dependencyIds: string[];
@@ -138,6 +161,28 @@ export class Tasks {
 		});
 	}
 
+	update(id: string, input: UpdateTaskInput, context: TaskEventContext = {}): Artifact {
+		const fields = (["title", "body", "labels"] as const).filter((field) => input[field] !== undefined);
+		if (fields.length === 0) throw new Error("task update requires title, body, or labels");
+		if (input.title !== undefined && (input.title.trim().length === 0 || input.title.length > TASK_TITLE_MAX_LENGTH)) {
+			throw new Error(`title must be between 1 and ${TASK_TITLE_MAX_LENGTH} characters`);
+		}
+		if (input.body !== undefined && input.body.length > TASK_BODY_MAX_LENGTH) throw new Error(`body cannot exceed ${TASK_BODY_MAX_LENGTH} characters`);
+		if (input.labels !== undefined) {
+			if (input.labels.length > TASK_LABEL_MAX_COUNT) throw new Error(`labels cannot exceed ${TASK_LABEL_MAX_COUNT} entries`);
+			if (input.labels.some((label) => label.length === 0 || label.length > TASK_LABEL_MAX_LENGTH)) {
+				throw new Error(`each label must be between 1 and ${TASK_LABEL_MAX_LENGTH} characters`);
+			}
+		}
+		return this.events.atomic(() => {
+			this.require(id);
+			const updated = this.artifacts.updateContent(id, input);
+			if (!updated) throw new Error(`task "${id}" not found`);
+			this.appendEvent({ taskId: id, type: "updated", evidence: { result: `fields:${fields.sort().join(",")}` } }, context);
+			return updated;
+		});
+	}
+
 	list(filter: TaskFilter = {}): Artifact[] {
 		const selection = this.scopeSelection(filter.projectRoot, filter.scope, filter.rootTaskId);
 		const limit = filter.limit ?? TASK_SCOPE_MAX_TASKS;
@@ -204,10 +249,12 @@ export class Tasks {
 			throw new Error(`task execution graph exceeds ${TASK_EXECUTION_MAX_NODES} nodes`);
 		}
 		const byId = new Map(tasks.map((task) => [task.id, task]));
-		const focusedId = this.focusStore.get();
+		const focus = this.focusStore.get();
+		const focusedId = focus?.taskId;
 		const nodes = new Map(tasks.map((task) => [task.id, {
 			task,
 			active: task.id === focusedId,
+			...(task.id === focusedId ? { focusStatus: focus!.status } : {}),
 			parentIds: [] as string[],
 			childIds: [] as string[],
 			dependencyIds: [] as string[],
@@ -247,25 +294,60 @@ export class Tasks {
 		return this.artifacts.get(id, { tree: true })!;
 	}
 
-	active(filter?: TaskFilter): Artifact | null {
-		const id = this.focusStore.get();
-		if (!id) return null;
-		const task = this.artifacts.get(id);
+	focused(filter?: TaskFilter): TaskFocus | null {
+		const focus = this.focusStore.get();
+		if (!focus) return null;
+		const task = this.artifacts.get(focus.taskId);
 		if (!task || task.kind !== "task" || task.status === "done" || task.status === "canceled") {
-			this.focusStore.clear(id);
+			this.focusStore.clear(focus.taskId);
 			return null;
 		}
 		if (filter?.projectRoot && !this.list(filter).some((candidate) => candidate.id === task.id)) return null;
-		return task;
+		return { artifact: task, status: focus.status, updatedAt: focus.updatedAt, ...(focus.pauseReason ? { pauseReason: focus.pauseReason } : {}) };
 	}
 
-	focus(id: string): Artifact {
-		const task = this.require(id);
-		if (task.status === "done" || task.status === "canceled") {
-			throw new Error(`cannot focus task from ${task.status}`);
-		}
-		this.focusStore.set(id);
-		return task;
+	active(filter?: TaskFilter): Artifact | null {
+		const focus = this.focused(filter);
+		return focus?.status === "active" ? focus.artifact : null;
+	}
+
+	focus(id: string, context: TaskEventContext = {}): Artifact {
+		return this.events.atomic(() => {
+			const task = this.require(id);
+			if (task.status === "done" || task.status === "canceled") throw new Error(`cannot focus task from ${task.status}`);
+			this.focusStore.set(id);
+			this.appendEvent({ taskId: id, type: "focus_set" }, context);
+			return task;
+		});
+	}
+
+	pauseFocus(context: TaskEventContext = {}): TaskFocus {
+		return this.events.atomic(() => {
+			const focus = this.focused();
+			if (!focus) throw new Error("no focused task");
+			const state = this.focusStore.pause(focus.artifact.id, context.reason);
+			this.appendEvent({ taskId: focus.artifact.id, type: "focus_paused" }, context);
+			return { artifact: focus.artifact, status: state.status, updatedAt: state.updatedAt, ...(state.pauseReason ? { pauseReason: state.pauseReason } : {}) };
+		});
+	}
+
+	unpauseFocus(context: TaskEventContext = {}): TaskFocus {
+		return this.events.atomic(() => {
+			const focus = this.focused();
+			if (!focus) throw new Error("no focused task");
+			const state = this.focusStore.unpause(focus.artifact.id);
+			this.appendEvent({ taskId: focus.artifact.id, type: "focus_unpaused" }, context);
+			return { artifact: focus.artifact, status: state.status, updatedAt: state.updatedAt };
+		});
+	}
+
+	clearFocus(context: TaskEventContext = {}): { cleared: boolean } {
+		return this.events.atomic(() => {
+			const focus = this.focusStore.get();
+			if (focus) this.appendEvent({ taskId: focus.taskId, type: "focus_cleared" }, context);
+			this.focusStore.clear();
+			return { cleared: focus !== undefined };
+		});
 	}
 
 	transition(id: string, action: TaskTransition, context: TaskEventContext = {}): Artifact {
@@ -324,19 +406,6 @@ 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);