@danypops/papyrus 0.17.0 → 0.17.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.17.0",
+  "version": "0.17.2",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],
@@ -42,6 +42,6 @@
   "files": ["src", "extension", "README.md"],
   "dependencies": {
     "beautiful-mermaid": "1.1.3",
-    "@danypops/daemon-kit": "^0.2.0"
+    "@danypops/daemon-kit": "^0.2.1"
   }
 }

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

@@ -7,6 +7,7 @@ import { createHash } from "node:crypto";
 import { createRequire } from "node:module";
 import { mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
+import { runMigrations, type SqliteMigrationRunner } from "@danypops/daemon-kit/storage";
 import { SQLITE_BUSY_TIMEOUT_MS, SQLITE_SCHEMA_VERSION } from "./constants.ts";
 
 const require_ = createRequire(import.meta.url);
@@ -20,7 +21,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[];
 }
@@ -362,6 +364,47 @@ function bootstrapEmptyDatabase(db: Db): void {
 	ensureCoreLedger(db, false);
 }
 
+/**
+ * Version the hardcoded, sequential if-chain below produces once fully applied. Frozen
+ * forever, per this same function's own "deliberately not a hand-enumerated allow-list"
+ * history below: that chain is never edited once shipped, only ever extended with a new
+ * `if` branch -- except a NEW branch is no longer how migrations beyond this version are
+ * added (see FUTURE_MIGRATIONS). The legacy chain itself stays byte-for-byte as it always
+ * was: same SQL, same single all-or-nothing transaction, same dynamic post-hoc gap check.
+ */
+const LEGACY_MIGRATION_CHAIN_TARGET_VERSION = 13;
+
+/**
+ * A migration beyond LEGACY_MIGRATION_CHAIN_TARGET_VERSION. Runs through @danypops/
+ * daemon-kit's generic runMigrations engine (one transaction per migration, daemon-kit's
+ * default) via dbMigrationRunner below, instead of a new branch appended to the legacy
+ * if-chain -- the exact reuse daemon-kit's storage module was refactored (v0.2.1) to allow,
+ * since Papyrus's dual bun:sqlite/node:sqlite Db abstraction could never satisfy that
+ * engine's original bun:sqlite-only signature.
+ */
+export interface PapyrusMigration {
+	version: number;
+	name: string;
+	up: (db: Db) => void;
+}
+
+/** Currently empty -- no schema version beyond LEGACY_MIGRATION_CHAIN_TARGET_VERSION exists yet. The next migration is appended here, never as a new branch in the legacy chain above. */
+const FUTURE_MIGRATIONS: ReadonlyArray<PapyrusMigration> = [];
+
+/**
+ * Adapts Papyrus's own Db/inTransaction to daemon-kit's storage-agnostic
+ * SqliteMigrationRunner port, so its runMigrations engine (written against bun:sqlite's
+ * concrete Database) runs unmodified against Papyrus's dual-runtime Db abstraction instead.
+ */
+export function dbMigrationRunner(db: Db): SqliteMigrationRunner<Db> {
+	return {
+		raw: db,
+		userVersion: () => schemaVersion(db),
+		setUserVersion: (version) => db.exec(`PRAGMA user_version = ${version}`),
+		transaction: (fn) => inTransaction(db, fn),
+	};
+}
+
 export function migrateDb(db: Db): MigrationResult {
 	const from = schemaVersion(db);
 	if (from > SQLITE_SCHEMA_VERSION) {
@@ -377,11 +420,17 @@ export function migrateDb(db: Db): MigrationResult {
 	// migrating any already-deployed database sitting at schema 8, 9, or 10 (including the real
 	// production database at the time this was found) would have thrown "no explicit migration
 	// path" before ever reaching the migration chain below. Checked dynamically after the chain
-	// runs instead: if schemaVersion(db) hasn't reached SQLITE_SCHEMA_VERSION once every
-	// `schemaVersion(db) === N` step below has had its chance to fire, `from` was never a valid
-	// starting point (a genuine gap in the chain) -- structurally cannot drift out of sync the
-	// way a separate, parallel enumeration did.
-	inTransaction(db, () => {
+	// runs instead: if schemaVersion(db) hasn't reached LEGACY_MIGRATION_CHAIN_TARGET_VERSION once
+	// every `schemaVersion(db) === N` step below has had its chance to fire, `from` was never a
+	// valid starting point (a genuine gap in the chain) -- structurally cannot drift out of sync
+	// the way a separate, parallel enumeration did.
+	//
+	// Guarded by `from < LEGACY_MIGRATION_CHAIN_TARGET_VERSION`: a database already at or past
+	// that version (only reachable once FUTURE_MIGRATIONS below has entries) must skip this
+	// entire frozen chain, not merely fail to match any of its branches -- entering it and
+	// falling through to the final gap check would otherwise misreport a database correctly
+	// mid-way through FUTURE_MIGRATIONS as "no explicit migration path".
+	if (from < LEGACY_MIGRATION_CHAIN_TARGET_VERSION) inTransaction(db, () => {
 		if (schemaVersion(db) === 1) {
 			db.exec(`
 				INSERT OR IGNORE INTO statuses VALUES ('todo','task');
@@ -660,9 +709,25 @@ export function migrateDb(db: Db): MigrationResult {
 			`);
 			applied.push("session-identity");
 		}
-		if (schemaVersion(db) !== SQLITE_SCHEMA_VERSION) throw new Error(`no explicit migration path from database schema ${from}`);
+		if (schemaVersion(db) !== LEGACY_MIGRATION_CHAIN_TARGET_VERSION) throw new Error(`no explicit migration path from database schema ${from}`);
 	});
-	if (schemaVersion(db) === SQLITE_SCHEMA_VERSION) ensureCoreLedger(db, true);
+
+	// Guarded by length: runMigrations treats an empty migrations array's "target version" as
+	// 0 (see its own sorted.at(-1) ?? 0), which would misreport a database the legacy chain
+	// already advanced past 0 as a downgrade. FUTURE_MIGRATIONS is empty only when there is
+	// nothing beyond LEGACY_MIGRATION_CHAIN_TARGET_VERSION to apply -- exactly the case where
+	// skipping the call is correct, not merely convenient.
+	if (FUTURE_MIGRATIONS.length > 0) {
+		const beforeFuture = schemaVersion(db);
+		runMigrations(dbMigrationRunner(db), [...FUTURE_MIGRATIONS]);
+		const afterFuture = schemaVersion(db);
+		for (const migration of FUTURE_MIGRATIONS) {
+			if (migration.version > beforeFuture && migration.version <= afterFuture) applied.push(migration.name);
+		}
+	}
+
+	if (schemaVersion(db) !== SQLITE_SCHEMA_VERSION) throw new Error(`no explicit migration path from database schema ${from}`);
+	ensureCoreLedger(db, true);
 	return { from, to: schemaVersion(db), applied };
 }
 

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);