@danypops/papyrus 0.17.0 → 0.17.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.17.0",
+  "version": "0.17.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-task-focus-store.ts

@@ -31,6 +31,10 @@ export class SQLiteTaskFocusStore implements TaskFocusStore {
 		});
 	}
 
+	reapStale(olderThanIso: string): number {
+		return this.db.prepare("DELETE FROM task_focus WHERE updated_at < ?").run(olderThanIso).changes;
+	}
+
 	private transition(taskId: string, expected: TaskFocusStatus, status: TaskFocusStatus, reason: string | undefined, scope: string | undefined): TaskFocusState {
 		const current = this.get(scope);
 		if (current?.taskId !== taskId) throw new Error(`task "${taskId}" is not focused`);

package/src/cli.ts

@@ -122,6 +122,7 @@ const USAGE = `Usage:
   papyrus tasks pause [--session-id <id>] [--session-secret <secret>] [--json]
   papyrus tasks unpause [--session-id <id>] [--session-secret <secret>] [--json]
   papyrus tasks clear-focus [--session-id <id>] [--session-secret <secret>] [--json]
+  papyrus tasks reap-stale-focus [--json]
   papyrus tasks history <id> [--json]
   papyrus tasks scope [project|all|graph <root-id>] [--json]
   papyrus tasks assign-project <id> [project-root] [--json]
@@ -1119,6 +1120,13 @@ export async function runTaskCli(args: string[], client: TaskCliClient, projectR
 			human = cleared.cleared ? "Task focus cleared." : "No focused task.";
 			break;
 		}
+		case "reap-stale-focus": {
+			if (id) throw new Error("tasks reap-stale-focus accepts no positional arguments");
+			const reaped = await client.call<Record<string, unknown>, { removed: number }>("tasks.reap_stale_focus", {});
+			result = reaped;
+			human = `Reaped ${reaped.removed} stale Focus scope(s).`;
+			break;
+		}
 		case "create": {
 			if (id) throw new Error("tasks create accepts no positional arguments");
 			if (!title) throw new Error("tasks create requires --title");

package/src/constants.ts

@@ -146,6 +146,17 @@ export const TASK_FOCUS_DEFAULT_SCOPE = "global";
 export const TASK_FOCUS_SCOPE_MAX_LENGTH = 128;
 /** Hard cap on distinct concurrent focus scopes (sessions); oldest-updated scope is evicted beyond this. */
 export const TASK_FOCUS_MAX_SCOPES = 500;
+/**
+ * A Task Focus row not touched by any Focus-mutating operation (focus/pause/unpause) in this
+ * long is eligible for time-based reaping (see Tasks.reapStaleFocus), independent of the
+ * TASK_FOCUS_MAX_SCOPES hard cap above -- see clean-up-stale-per-session-task-focus-rows-
+ * on-real-session-l-9i7s. Deliberately NOT driven by Pi's session_start/session_shutdown
+ * hooks: a "resume" reuses the exact same session_id as a prior process incarnation, so
+ * neither hook reliably signals "this session is gone forever" -- only real elapsed time
+ * without any Focus activity does. 30 days is long enough that a genuine multi-week pause-
+ * and-resume workflow survives; short enough to actually bound long-run accumulation.
+ */
+export const TASK_FOCUS_STALE_AFTER_MS = 30 * 24 * 60 * 60 * 1000;
 /** Hard cap on registered session_identities rows (see domain/session-identity.ts); oldest-seen identity is evicted beyond this, mirroring TASK_FOCUS_MAX_SCOPES. */
 export const SESSION_IDENTITY_MAX_ROWS = 2_000;
 /** Persisted project and focused-graph Task view bounds. */

package/src/daemon.ts

@@ -25,12 +25,22 @@ 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);
+	// Daily cadence (reusing DB_OPTIMIZE_INTERVAL_MS) is plenty against a 30-day staleness
+	// threshold (TASK_FOCUS_STALE_AFTER_MS) -- see clean-up-stale-per-session-task-focus-rows-
+	// on-real-session-l-9i7s.
+	const reapFocusTimer = setInterval(() => {
+		try {
+			const removed = service.reapStaleFocus();
+			if (removed > 0) logEvent("info", "stale_focus_reaped", { removed });
+		} catch (error) { logEvent("error", "reap_stale_focus_failed", { message: error instanceof Error ? error.message : String(error) }); }
+	}, DB_OPTIMIZE_INTERVAL_MS);
 	let stopping = false;
 	const shutdown = () => {
 		if (stopping) return;
 		stopping = true;
 		clearInterval(checkpointTimer);
 		clearInterval(optimizeTimer);
+		clearInterval(reapFocusTimer);
 		clearDaemonPort(stateDir);
 		service.close();
 		void server.stop(true).finally(() => process.exit(0));

package/src/db.ts

@@ -20,7 +20,8 @@ const DatabaseCtor = (
 ) as new (path: string, opts?: { create?: boolean }) => Db;
 
 export interface DbStatement {
-	run(...params: unknown[]): { lastInsertRowid: number | bigint };
+	/** changes: number of rows the statement affected. Both bun:sqlite and node:sqlite's real run() return this at runtime; declared here so callers (e.g. reapStale) can rely on it without an unsafe cast. */
+	run(...params: unknown[]): { lastInsertRowid: number | bigint; changes: number };
 	get(...params: unknown[]): unknown;
 	all(...params: unknown[]): unknown[];
 }

package/src/modules/tasks.ts

@@ -90,7 +90,7 @@ export const TASKS_OPERATION_NAMES = [
 	"tasks.scope", "tasks.set_scope", "tasks.assign_project", "tasks.active", "tasks.focused", "tasks.focus",
 	"tasks.pause", "tasks.unpause", "tasks.clear_focus", "tasks.start", "tasks.submit", "tasks.complete",
 	"tasks.run_gates", "tasks.set_checklist", "tasks.context", "tasks.reject", "tasks.retry", "tasks.cancel",
-	"tasks.depend", "tasks.undepend", "tasks.contain", "tasks.uncontain",
+	"tasks.depend", "tasks.undepend", "tasks.contain", "tasks.uncontain", "tasks.reap_stale_focus",
 ] as const;
 
 export function tasksOperations(tasks: Tasks, artifacts: ArtifactStore, sessionIdentity: SessionIdentity): OperationDefinition[] {
@@ -151,6 +151,7 @@ export function tasksOperations(tasks: Tasks, artifacts: ArtifactStore, sessionI
 		define("tasks.pause", (input: OperationInput) => { guardFocusMutation(input); return tasks.pauseFocus(eventContext(input)); }),
 		define("tasks.unpause", (input: OperationInput) => { guardFocusMutation(input); return tasks.unpauseFocus(eventContext(input)); }),
 		define("tasks.clear_focus", (input: OperationInput) => { guardFocusMutation(input); return tasks.clearFocus(eventContext(input)); }),
+		define("tasks.reap_stale_focus", () => ({ removed: tasks.reapStaleFocus() })),
 		define("tasks.start", (input: OperationInput) => tasks.transition(string(input, "id"), "start", eventContext(input))),
 		define("tasks.submit", (input: OperationInput) => tasks.transition(string(input, "id"), "submit", eventContext(input))),
 		define("tasks.complete", (input: OperationInput) => tasks.completeAsync(string(input, "id"), eventContext(input))),

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

@@ -30,6 +30,8 @@ export interface TaskFocusStore {
 	clear(taskId?: string, scope?: string): void;
 	/** Clears this task's Focus in every scope (session), not just one — for lifecycle events (e.g. cancel) that are not scoped to a single caller. */
 	clearEverywhere(taskId: string): void;
+	/** Deletes every Focus row whose updatedAt is strictly before olderThanIso (see TASK_FOCUS_STALE_AFTER_MS). Returns how many rows were removed. */
+	reapStale(olderThanIso: string): number;
 }
 
 export class InMemoryTaskFocusStore implements TaskFocusStore {
@@ -74,6 +76,14 @@ export class InMemoryTaskFocusStore implements TaskFocusStore {
 		}
 	}
 
+	reapStale(olderThanIso: string): number {
+		let removed = 0;
+		for (const [key, focus] of this.state) {
+			if (focus.updatedAt < olderThanIso) { this.state.delete(key); removed++; }
+		}
+		return removed;
+	}
+
 	private evictOldest(): void {
 		let oldestKey: string | undefined;
 		let oldestAt: string | undefined;

package/src/service.ts

@@ -171,6 +171,8 @@ export interface PapyrusService {
 	execute(operation: string, input?: OperationInput): Promise<unknown>;
 	checkpoint(): void;
 	optimize(): void;
+	/** Time-based Task Focus reclamation (see Tasks.reapStaleFocus); returns how many rows were removed, for daemon logging. */
+	reapStaleFocus(): number;
 	close(): void;
 }
 
@@ -318,6 +320,7 @@ function handlers(
 		"tasks.undepend": forwardToModule("tasks.undepend"),
 		"tasks.contain": forwardToModule("tasks.contain"),
 		"tasks.uncontain": forwardToModule("tasks.uncontain"),
+		"tasks.reap_stale_focus": forwardToModule("tasks.reap_stale_focus"),
 		"docs.create": forwardToModule("docs.create"),
 		"docs.list": forwardToModule("docs.list"),
 		"docs.show": forwardToModule("docs.show"),
@@ -417,6 +420,7 @@ export function createPapyrusService(path: string): PapyrusService {
 		},
 		checkpoint: () => { db.exec("PRAGMA wal_checkpoint(PASSIVE)"); },
 		optimize: () => { db.exec("PRAGMA optimize"); },
+		reapStaleFocus: () => tasks.reapStaleFocus(),
 		close: () => {
 			db.exec("PRAGMA optimize");
 			db.close();

package/src/task-service.ts

@@ -5,6 +5,7 @@ import {
 	TASK_EXECUTION_MAX_NODES,
 	TASK_LABEL_MAX_COUNT,
 	TASK_LABEL_MAX_LENGTH,
+	TASK_FOCUS_STALE_AFTER_MS,
 	TASK_SCOPE_MAX_TASKS,
 	TASK_TITLE_MAX_LENGTH,
 } from "./constants.ts";
@@ -383,6 +384,19 @@ export class Tasks {
 		});
 	}
 
+	/**
+	 * Time-based reclamation of Focus scopes nobody has touched in TASK_FOCUS_STALE_AFTER_MS,
+	 * independent of and in addition to the TASK_FOCUS_MAX_SCOPES hard cap -- see
+	 * clean-up-stale-per-session-task-focus-rows-on-real-session-l-9i7s and constants.ts's
+	 * comment on why this is deliberately not driven by session_start/session_shutdown.
+	 * No task-lifecycle event is appended: this is daemon housekeeping, not a caller-driven
+	 * mutation, and there is no longer a specific session/actor to attribute it to.
+	 */
+	reapStaleFocus(now: () => string = () => new Date().toISOString()): number {
+		const cutoff = new Date(new Date(now()).getTime() - TASK_FOCUS_STALE_AFTER_MS).toISOString();
+		return this.focusStore.reapStale(cutoff);
+	}
+
 	transition(id: string, action: TaskTransition, context: TaskEventContext = {}): Artifact {
 		return this.events.atomic(() => {
 			const task = this.require(id);