@danypops/papyrus 0.16.0 → 0.17.1

package/extension/src/domain-tools.ts

@@ -8,6 +8,7 @@ import type { TaskHistoryPage } from "../../src/domain/task-event.ts";
 import type { TaskCompletion, TaskGraph } from "../../src/task-service.ts";
 import type { SkillWorkflowRunResult } from "../../src/skill-execution.ts";
 import { emitTaskFocusEvent } from "./task-focus-events.ts";
+import { sessionSecretField } from "./session-identity.ts";
 import { NOTE_DISPOSITIONS } from "../../src/note-service.ts";
 import { callService } from "./service-client.ts";
 import { renderPapyrusToolCall, renderPapyrusToolResult } from "./tool-rendering/index.ts";
@@ -77,7 +78,12 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 				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.
-				const request = { ...params, project_root: params.project_root ?? ctx.cwd, actor: "agent", source: "pi-tool", session_id: params.session_id ?? ctx.sessionManager.getSessionId() };
+				// session_secret is looked up by the resolved session_id itself (not blindly the
+				// current session's), so a model that explicitly overrides session_id to a DIFFERENT
+				// 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) };
 				if (action === "create") {
 					const artifact = await callService<Record<string, unknown>, Artifact>("tasks.create", request);
 					return text(`Created task ${artifactLine(artifact)}`, createArtifactDetails("tasks.create", artifact));

package/extension/src/index.ts

@@ -31,6 +31,7 @@ import { buildContextBreakdown, buildMessageHistoryTree, buildTaskItemTree, comp
 import { buildBasePromptItems } from "./base-prompt-breakdown.ts";
 import { showContextView } from "./context-view.ts";
 import { emitTaskFocusEvent, setTaskFocusEventBus } from "./task-focus-events.ts";
+import { cacheSessionSecret, forgetSessionSecret, sessionSecretField } from "./session-identity.ts";
 import { renderPapyrusToolCall, renderPapyrusToolResult } from "./tool-rendering/index.ts";
 import {
 	createArtifactDetails,
@@ -197,6 +198,7 @@ export default async function (pi: ExtensionAPI) {
 					source: "task-continuation",
 					reason: automaticPauseReason(decision.reason),
 					session_id: sessionId,
+					...sessionSecretField(sessionId),
 				});
 				emitTaskFocusEvent({ taskId: paused.artifact.id, sessionId, status: "paused" });
 				if (ctx.hasUI) ctx.ui.notify(`Papyrus task driving paused: ${decision.reason}. Human input resumes it automatically.`, "warning");
@@ -499,6 +501,19 @@ export default async function (pi: ExtensionAPI) {
 	// ── Task widget (TodoOverlay pattern: factory form, requestRender) ──
 
 	pi.on("session_start", async (_event, ctx) => {
+		// Registers this session's identity with the daemon as early as possible -- before any
+		// Focus-mutating call could plausibly happen -- shrinking (not eliminating; see
+		// domain/session-identity.ts) the first-touch race window. Best-effort: the daemon may be
+		// unavailable during startup, and every other Focus-mutating call already tolerates an
+		// unregistered/never-armored session_id (opt-in armor), so a missed registration here is
+		// not worth surfacing to the user.
+		try {
+			const sessionId = ctx.sessionManager.getSessionId();
+			const { secret } = await callService<Record<string, unknown>, { sessionId: string; secret: string }>("session.register", { session_id: sessionId });
+			cacheSessionSecret(sessionId, secret);
+		} catch {
+			// intentionally silent -- see comment above
+		}
 		if (!ctx.hasUI) return;
 		overlay ??= new TaskOverlay();
 		overlay.setUI(ctx.ui);
@@ -510,7 +525,17 @@ export default async function (pi: ExtensionAPI) {
 	pi.on("session_before_compact", () => { taskContinuation.onCompaction(); });
 	pi.on("session_compact", async () => { await overlay?.refresh(); });
 	pi.on("session_tree", async () => { await overlay?.refresh(); });
-	pi.on("session_shutdown", async () => { overlay?.dispose(); overlay = undefined; });
+	pi.on("session_shutdown", async (_event, ctx) => {
+		overlay?.dispose();
+		overlay = undefined;
+		try {
+			const sessionId = ctx.sessionManager.getSessionId();
+			await callService("session.release", { session_id: sessionId, ...sessionSecretField(sessionId) });
+			forgetSessionSecret(sessionId);
+		} catch {
+			// intentionally silent -- see session_start's comment above
+		}
+	});
 
 	// Update widget after any papyrus tool call
 	pi.on("tool_execution_end", async (event) => {
@@ -530,7 +555,7 @@ export default async function (pi: ExtensionAPI) {
 			const sessionId = ctx.sessionManager.getSessionId();
 			const focus = await callService<Record<string, unknown>, { artifact: Artifact; status: string; pauseReason?: string } | null>("tasks.focused", { session_id: sessionId });
 			if (focus && shouldResumeFocusOnHumanInput(focus.status, focus.pauseReason)) {
-				await callService("tasks.unpause", { actor: "system", source: "task-continuation", reason: "human input resumed automatic task continuation", session_id: sessionId });
+				await callService("tasks.unpause", { actor: "system", source: "task-continuation", reason: "human input resumed automatic task continuation", session_id: sessionId, ...sessionSecretField(sessionId) });
 				emitTaskFocusEvent({ taskId: focus.artifact.id, sessionId, status: "unpaused" });
 			}
 		} catch {

package/extension/src/session-identity.ts

@@ -0,0 +1,22 @@
+/**
+ * Client-side cache for the extension's own session_secret, registered with the daemon at
+ * session_start and released at session_shutdown (see index.ts). Keyed by sessionId (not a
+ * single "current" variable) defensively -- multiple call sites reference an explicit
+ * sessionId already, and a Map costs nothing extra for real correctness. See
+ * src/domain/session-identity.ts (daemon side) for the full design rationale.
+ */
+const secretsBySessionId = new Map<string, string>();
+
+export function cacheSessionSecret(sessionId: string, secret: string): void {
+	secretsBySessionId.set(sessionId, secret);
+}
+
+export function forgetSessionSecret(sessionId: string): void {
+	secretsBySessionId.delete(sessionId);
+}
+
+/** Spread into any Focus-mutating request body alongside session_id -- empty object when no secret is cached for this sessionId (unregistered, or registration hasn't completed yet), matching the daemon's opt-in-armor default. */
+export function sessionSecretField(sessionId: string | undefined): { session_secret?: string } {
+	const secret = sessionId ? secretsBySessionId.get(sessionId) : undefined;
+	return secret ? { session_secret: secret } : {};
+}

package/extension/src/tasks.ts

@@ -8,6 +8,7 @@ import { DynamicBorder, rawKeyHint } from "@earendil-works/pi-coding-agent";
 import { Container, Input, Spacer, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { callService } from "./service-client.ts";
 import { emitTaskFocusEvent } from "./task-focus-events.ts";
+import { sessionSecretField } from "./session-identity.ts";
 import { showTaskDetails } from "./task-detail-view.ts";
 import { showTaskGraph } from "./task-graph.ts";
 
@@ -175,7 +176,7 @@ export async function showTasks(ctx: ExtensionCommandContext): Promise<void> {
 			}
 		} else if (choice === "Make active") {
 			try {
-				const focused = await callService<Record<string, unknown>, Artifact>("tasks.focus", { id: action.row.id, actor: "user", source: "tasks-tui", session_id: sessionId });
+				const focused = await callService<Record<string, unknown>, Artifact>("tasks.focus", { id: action.row.id, actor: "user", source: "tasks-tui", session_id: sessionId, ...sessionSecretField(sessionId) });
 				emitTaskFocusEvent({ taskId: focused.id, sessionId, status: "focused" });
 				ctx.ui.notify(`Active: ${action.row.title}`, "info");
 			} catch (error) {
@@ -184,11 +185,11 @@ export async function showTasks(ctx: ExtensionCommandContext): Promise<void> {
 		} else if (choice === "Pause focus" || choice === "Resume focus" || choice === "Clear focus") {
 			try {
 				if (choice === "Clear focus") {
-					await callService("tasks.clear_focus", { actor: "user", source: "tasks-tui", session_id: sessionId });
+					await callService("tasks.clear_focus", { actor: "user", source: "tasks-tui", session_id: sessionId, ...sessionSecretField(sessionId) });
 					emitTaskFocusEvent({ taskId: null, sessionId, status: "cleared" });
 				} else {
 					const operation = choice === "Pause focus" ? "tasks.pause" : "tasks.unpause";
-					const result = await callService<Record<string, unknown>, { artifact: Artifact; status: string }>(operation, { actor: "user", source: "tasks-tui", session_id: sessionId });
+					const result = await callService<Record<string, unknown>, { artifact: Artifact; status: string }>(operation, { actor: "user", source: "tasks-tui", session_id: sessionId, ...sessionSecretField(sessionId) });
 					emitTaskFocusEvent({ taskId: result.artifact.id, sessionId, status: choice === "Pause focus" ? "paused" : "unpaused" });
 				}
 				ctx.ui.notify(choice === "Clear focus" ? "Task focus cleared" : choice, "info");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.16.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"],
@@ -41,6 +41,7 @@
   },
   "files": ["src", "extension", "README.md"],
   "dependencies": {
-    "beautiful-mermaid": "1.1.3"
+    "beautiful-mermaid": "1.1.3",
+    "@danypops/daemon-kit": "^0.2.0"
   }
 }

package/src/adapters/sqlite-session-identity-store.ts

@@ -0,0 +1,46 @@
+import { SESSION_IDENTITY_MAX_ROWS } from "../constants.ts";
+import type { Db } from "../db.ts";
+import { inTransaction } from "../db.ts";
+import type { SessionIdentityRecord, SessionIdentityStore } from "../ports/session-identity-store.ts";
+
+export class SQLiteSessionIdentityStore implements SessionIdentityStore {
+	constructor(private readonly db: Db) {}
+
+	find(sessionId: string): SessionIdentityRecord | undefined {
+		const row = this.db.prepare("SELECT session_id, secret_hash, registered_at, last_seen_at FROM session_identities WHERE session_id = ?").get(sessionId) as
+			| { session_id: string; secret_hash: string; registered_at: string; last_seen_at: string }
+			| null;
+		return row ? { sessionId: row.session_id, secretHash: row.secret_hash, registeredAt: row.registered_at, lastSeenAt: row.last_seen_at } : undefined;
+	}
+
+	upsert(record: SessionIdentityRecord): void {
+		inTransaction(this.db, () => {
+			this.evictOldestBeyondCap(record.sessionId);
+			this.db.prepare(`
+				INSERT INTO session_identities (session_id, secret_hash, registered_at, last_seen_at)
+				VALUES (?, ?, ?, ?)
+				ON CONFLICT(session_id) DO UPDATE SET secret_hash = excluded.secret_hash, registered_at = excluded.registered_at, last_seen_at = excluded.last_seen_at
+			`).run(record.sessionId, record.secretHash, record.registeredAt, record.lastSeenAt);
+		});
+	}
+
+	remove(sessionId: string): void {
+		this.db.prepare("DELETE FROM session_identities WHERE session_id = ?").run(sessionId);
+	}
+
+	touch(sessionId: string, lastSeenAt: string): void {
+		this.db.prepare("UPDATE session_identities SET last_seen_at = ? WHERE session_id = ?").run(lastSeenAt, sessionId);
+	}
+
+	count(): number {
+		return (this.db.prepare("SELECT COUNT(*) AS count FROM session_identities").get() as { count: number }).count;
+	}
+
+	/** Bounds distinct registered session identities; evicts the least-recently-seen beyond the cap. Mirrors SQLiteTaskFocusStore.evictOldestBeyondCap exactly. */
+	private evictOldestBeyondCap(sessionId: string): void {
+		const exists = this.db.prepare("SELECT 1 FROM session_identities WHERE session_id = ?").get(sessionId);
+		if (exists) return;
+		if (this.count() < SESSION_IDENTITY_MAX_ROWS) return;
+		this.db.exec("DELETE FROM session_identities WHERE session_id = (SELECT session_id FROM session_identities ORDER BY last_seen_at ASC LIMIT 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

@@ -112,18 +112,21 @@ const USAGE = `Usage:
   papyrus notes promote <id> <target-id> [--reason <reason>] [--json]
   papyrus notes archive <id> <completed|duplicate|declined|superseded> [--reason <reason>] [--json]
   papyrus log append --source <id> --level <debug|info|warning|error> --message <text> --operation-id <id> [--source-label <text>] [--fields-json <json>] [--session-id <id>] [--occurred-at <iso>] [--global] [--json]
+  papyrus session register --session-id <id> [--json]
+  papyrus session release --session-id <id> [--session-secret <secret>] [--json]
   papyrus log query --source <id> [--since <iso>] [--level <debug|info|warning|error>] [--limit <count>] [--json]
   papyrus tasks plan [--session-id <id>] [--json]
   papyrus tasks graph [--session-id <id>] [--json]
   papyrus tasks active [--session-id <id>] [--json]
   papyrus tasks focused [--session-id <id>] [--json]
-  papyrus tasks pause [--session-id <id>] [--json]
-  papyrus tasks unpause [--session-id <id>] [--json]
-  papyrus tasks clear-focus [--session-id <id>] [--json]
+  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]
-  papyrus tasks focus <id> [--session-id <id>] [--json]
+  papyrus tasks focus <id> [--session-id <id>] [--session-secret <secret>] [--json]
   papyrus tasks update <id> [--title <title>] [--body <body>] [--labels-json <json>] [--status todo --reason <reason>] [--json]
   papyrus tasks complete <id> [--session-id <id>] [--json]
   papyrus tasks start <id> [--session-id <id>] [--json]
@@ -142,7 +145,8 @@ const USAGE = `Usage:
   papyrus tasks set-checklist <id> --checklist-json <json> [--json]
   papyrus tasks context [--scope <project|graph|all>] [--root-task-id <id>] [--session-id <id>] [--json]
 
-A "--session-id" scopes Task Focus to one agent session; omit it to use the shared "global" Focus (today's behavior).`;
+A "--session-id" scopes Task Focus to one agent session; omit it to use the shared "global" Focus (today's behavior).
+Once a session id is registered ("papyrus session register"), mutating its Focus (focus/pause/unpause/clear-focus) requires the matching "--session-secret"; an unregistered session id is unaffected.`;
 
 function usage(): never {
 	console.error(USAGE);
@@ -909,6 +913,33 @@ export async function runLogCli(args: string[], client: TaskCliClient, projectRo
 	throw new Error("log action must be append or query");
 }
 
+export async function runSessionIdentityCli(args: string[], client: TaskCliClient): Promise<string> {
+	const json = args.includes("--json");
+	const positional: string[] = [];
+	let sessionId: string | undefined;
+	let secret: string | undefined;
+	for (let index = 0; index < args.length; index++) {
+		const argument = args[index]!;
+		if (argument === "--json") continue;
+		if (argument === "--session-id") { sessionId = args[++index]; continue; }
+		if (argument === "--session-secret") { secret = args[++index]; continue; }
+		if (argument.startsWith("--")) throw new Error(`unknown session option ${argument}`);
+		positional.push(argument);
+	}
+	const [action] = positional;
+	if (action === "register") {
+		if (!sessionId) throw new Error("session register requires --session-id");
+		const result = await client.call<Record<string, unknown>, { sessionId: string; secret: string }>("session.register", { session_id: sessionId });
+		return json ? JSON.stringify(result) : JSON.stringify(result, null, 2);
+	}
+	if (action === "release") {
+		if (!sessionId) throw new Error("session release requires --session-id");
+		const result = await client.call<Record<string, unknown>, { released: boolean }>("session.release", { session_id: sessionId, ...(secret ? { session_secret: secret } : {}) });
+		return json ? JSON.stringify(result) : JSON.stringify(result, null, 2);
+	}
+	throw new Error("session action must be register or release");
+}
+
 export async function runNoteCli(args: string[], client: TaskCliClient, projectRoot: string = process.cwd()): Promise<string> {
 	const json = args.includes("--json");
 	const positional: string[] = [];
@@ -975,6 +1006,7 @@ export async function runTaskCli(args: string[], client: TaskCliClient, projectR
 	const updateInput: { title?: string; body?: string; labels?: string[]; status?: "todo" } = {};
 	let reason: string | undefined;
 	let sessionId: string | undefined;
+	let sessionSecret: string | undefined;
 	let title: string | undefined;
 	let body: string | undefined;
 	let status: string | undefined;
@@ -997,6 +1029,11 @@ export async function runTaskCli(args: string[], client: TaskCliClient, projectR
 			if (!sessionId) throw new Error("--session-id requires a value");
 			continue;
 		}
+		if (argument === "--session-secret") {
+			sessionSecret = args[++index];
+			if (!sessionSecret) throw new Error("--session-secret requires a value");
+			continue;
+		}
 		if (argument === "--title" || argument === "--body" || argument === "--labels-json" || argument === "--status" || argument === "--reason") {
 			const value = args[++index];
 			if (value === undefined) throw new Error(`${argument} requires a value`);
@@ -1046,6 +1083,10 @@ export async function runTaskCli(args: string[], client: TaskCliClient, projectR
 	const reasonSupportedActions = new Set(["update", "depend", "undepend", "contain", "uncontain"]);
 	if (reason !== undefined && !reasonSupportedActions.has(action ?? "")) throw new Error("--reason is only supported by tasks update, depend, undepend, contain, and uncontain");
 	const sessionScope = sessionId ? { session_id: sessionId } : {};
+	// Only meaningful alongside a registered session_id (see session.register); required by the
+	// daemon only for the specific Focus-mutating operations below (focus/pause/unpause/clear_focus)
+	// once that session_id has been armored (see session-identity-service.ts assertAuthorized).
+	const sessionSecretField = sessionSecret ? { session_secret: sessionSecret } : {};
 	let result: unknown;
 	let human: string;
 	switch (action) {
@@ -1067,18 +1108,25 @@ export async function runTaskCli(args: string[], client: TaskCliClient, projectR
 		case "unpause": {
 			if (id) throw new Error(`tasks ${action} accepts no positional arguments`);
 			const operation = action === "pause" ? "tasks.pause" : "tasks.unpause";
-			const focus = await client.call<Record<string, unknown>, { artifact: CliArtifact; status: string }>(operation, { actor: "user", source: "cli", ...sessionScope });
+			const focus = await client.call<Record<string, unknown>, { artifact: CliArtifact; status: string }>(operation, { actor: "user", source: "cli", ...sessionScope, ...sessionSecretField });
 			result = focus;
 			human = `Focused (${focus.status}): ${artifactLabel(focus.artifact)}`;
 			break;
 		}
 		case "clear-focus": {
 			if (id) throw new Error("tasks clear-focus accepts no positional arguments");
-			const cleared = await client.call<Record<string, unknown>, { cleared: boolean }>("tasks.clear_focus", { actor: "user", source: "cli", ...sessionScope });
+			const cleared = await client.call<Record<string, unknown>, { cleared: boolean }>("tasks.clear_focus", { actor: "user", source: "cli", ...sessionScope, ...sessionSecretField });
 			result = cleared;
 			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");
@@ -1206,7 +1254,7 @@ export async function runTaskCli(args: string[], client: TaskCliClient, projectR
 		}
 		case "focus": {
 			if (!id || dependencyId) throw new Error("tasks focus requires exactly one task id");
-			const active = await client.call<Record<string, unknown>, CliArtifact>("tasks.focus", { id, actor: "user", source: "cli", ...sessionScope });
+			const active = await client.call<Record<string, unknown>, CliArtifact>("tasks.focus", { id, actor: "user", source: "cli", ...sessionScope, ...sessionSecretField });
 			result = active;
 			human = `Active: ${artifactLabel(active)}`;
 			break;
@@ -1308,6 +1356,11 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
 		console.log(await runLogCli(args.slice(1), client));
 		return;
 	}
+	if (command === "session") {
+		const client = await connectPapyrusClient();
+		console.log(await runSessionIdentityCli(args.slice(1), client));
+		return;
+	}
 	if (command === "migrate") {
 		const client = await connectPapyrusClient();
 		console.log(await runMigrationCli(args.slice(1), client));

package/src/constants.ts

@@ -7,7 +7,7 @@ export const DAEMON_PROBE_TIMEOUT_MS = 800;
 export const DAEMON_UNIT_NAME = "papyrus.service";
 export const DAEMON_DIR_ENV = "PAPYRUS_DAEMON_DIR";
 export const SQLITE_BUSY_TIMEOUT_MS = 5_000;
-export const SQLITE_SCHEMA_VERSION = 12;
+export const SQLITE_SCHEMA_VERSION = 13;
 export const SERVICE_MAX_BODY_BYTES = 1_048_576;
 
 export const WAL_CHECKPOINT_INTERVAL_MS = 60_000;
@@ -146,6 +146,19 @@ 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. */
 export const TASK_SCOPE_MAX_TASKS = 1_000;
 /** Docs/Rules/Skills project scope listing bound, mirroring TASK_SCOPE_MAX_TASKS. */

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[];
 }
@@ -210,6 +211,12 @@ CREATE TABLE IF NOT EXISTS log_entries (
 CREATE INDEX IF NOT EXISTS log_entries_source_idx ON log_entries(source_id, occurred_at, id);
 CREATE TRIGGER IF NOT EXISTS log_entries_no_update BEFORE UPDATE ON log_entries
 BEGIN SELECT RAISE(ABORT, 'log_entries are immutable once written; retention trimming is the only supported deletion path'); END;
+CREATE TABLE IF NOT EXISTS session_identities (
+	session_id    TEXT PRIMARY KEY,
+	secret_hash   TEXT NOT NULL,
+	registered_at TEXT NOT NULL,
+	last_seen_at  TEXT NOT NULL
+);
 `;
 
 const SEED_SQL = `
@@ -287,6 +294,7 @@ const CORE_LEDGER_VERSIONS: ReadonlyArray<{ version: number; name: string; check
 	{ version: 2, name: "docs-rules-skills-project-scope", checksum: "8b16d8f631ad628f4799ff09b1ebe8be28343e4f677d52bf2a39a8bedc19e64e" },
 	{ version: 3, name: "log-domain", checksum: "c87f43c22b2608619ada9a529d7899ae74b7f38cd554135c8034116fc96e1eff" },
 	{ version: 4, name: "remove-discourse", checksum: "b923f41c44460f0aaeb2f4e60e28f8b8e1425d03f527955bd991434b46de4c82" },
+	{ version: 5, name: "session-identity", checksum: "1c6a165bbe37f82a100fd34762db70c3f8ab15ff20c3a53c2e60448edc815a5e" },
 ];
 
 export function migrationLedger(db: Db): ModuleMigrationRow[] {
@@ -637,6 +645,22 @@ export function migrateDb(db: Db): MigrationResult {
 			`);
 			applied.push("remove-discourse");
 		}
+		if (schemaVersion(db) === 12) {
+			// See domain/session-identity.ts and verify-caller-identity-behind-papyrus-mutation-
+			// attribution-koxt: first-touch capability binding for session_id, the one place it is
+			// behavior-affecting today (Task Focus). Purely additive -- a session_id that never
+			// registers here behaves exactly as before.
+			db.exec(`
+				CREATE TABLE IF NOT EXISTS session_identities (
+					session_id    TEXT PRIMARY KEY,
+					secret_hash   TEXT NOT NULL,
+					registered_at TEXT NOT NULL,
+					last_seen_at  TEXT NOT NULL
+				);
+				PRAGMA user_version = 13;
+			`);
+			applied.push("session-identity");
+		}
 		if (schemaVersion(db) !== SQLITE_SCHEMA_VERSION) throw new Error(`no explicit migration path from database schema ${from}`);
 	});
 	if (schemaVersion(db) === SQLITE_SCHEMA_VERSION) ensureCoreLedger(db, true);

package/src/domain/session-identity.ts

@@ -0,0 +1,50 @@
+/**
+ * domain/session-identity.ts — closes the gap flagged by
+ * verify-caller-identity-behind-papyrus-mutation-attribution-koxt: session_id was, until now,
+ * pure caller-supplied free text at the RPC boundary, yet scope-task-focus-and-its-
+ * tuicontext-injection-to-the-request-8d5n made it load-bearing for *behavior* (Task Focus
+ * is keyed by session_id) -- a forged session_id can pause/unpause/clear/redirect a live
+ * session's Focus, not merely mislabel history.
+ *
+ * The real constraint this design works within: Papyrus's daemon authenticates every client
+ * with ONE shared bearer token per machine (src/daemon-state.ts) -- every authenticated
+ * caller looks identical to the daemon. Checked directly against Bun's public server API:
+ * no SO_PEERCRED-equivalent exists for either a TCP or a Unix-socket listener, so real
+ * kernel-verified per-process identity is not cheaply achievable; building it would mean FFI
+ * against libc, disproportionate to this task. Pi's session ids are uuidv7 (time-ordered, not
+ * cryptographically opaque -- confirmed by reading @earendil-works/pi-coding-agent's
+ * session-manager.ts source), so they were never meant to double as secrets either.
+ *
+ * The actual cryptographic primitive (secret generation, hashing, constant-time verify,
+ * first-touch registration semantics) is NOT reimplemented here -- it lives in
+ * @danypops/daemon-kit's session-identity module. That gap (a shared bearer token cannot
+ * distinguish callers; a session id needs a real credential once it becomes behavior-
+ * affecting) is generic to every daemon-kit-shaped daemon, not Papyrus-specific -- Papyrus's
+ * own daemon.ts/service.ts predates daemon-kit and has not migrated onto it, but this one
+ * capability is adopted narrowly regardless (daemon-kit's exports map is designed for
+ * exactly this: "a consumer only pulls in what it uses"). This file only wires that generic
+ * primitive to Papyrus's own SQLite storage (see adapters/sqlite-session-identity-store.ts)
+ * and to Task Focus specifically, the one place session_id is behavior-affecting today.
+ *
+ * Deliberately "opt-in armor", not a breaking migration: a session_id that was never
+ * registered behaves exactly as before (open), so every already-open session and every
+ * caller that never calls session.register (bare CLI use of the "global" scope, older
+ * Papyrus builds, test fixtures) is unaffected. Every real Pi session becomes armored
+ * automatically the moment its extension fires session_start.
+ *
+ * Explicitly NOT solved by this: a race at first contact (whoever registers a session_id
+ * first becomes its legitimate owner) -- an attacker who wins that race before the real
+ * session ever registers still prevails. This is a real, disclosed, accepted residual limit,
+ * not oversold as "verified identity"; scribe's own prior art never solved caller identity
+ * either. Registering as soon as the extension's session_start hook fires (before any
+ * Focus-mutating call could plausibly happen) shrinks this window to something small, not
+ * zero.
+ *
+ * actor/source free-text fields are explicitly NOT in scope here -- they remain audit-trail
+ * labeling only, never a security boundary, matching the conclusion already reached when this
+ * task was deferred from add-a-generic-mutation-event-log-to-the-papyrus-artifactstor-at6h.
+ */
+
+export function assertValidSessionId(sessionId: string): void {
+	if (typeof sessionId !== "string" || sessionId.length === 0) throw new Error("session_id is required");
+}

package/src/modules/session-identity.ts

@@ -0,0 +1,38 @@
+/**
+ * modules/session-identity.ts — the session-identity domain as a registered Papyrus-native
+ * module. Deliberately self-contained: no artifact/task infrastructure imports, matching the
+ * precedent set by modules/logs.ts. See domain/session-identity.ts for the design rationale.
+ */
+import type { OperationDefinition } from "../module-registry.ts";
+import type { SessionIdentity } from "../session-identity-service.ts";
+
+const MODULE_ID = "session-identity";
+
+type OperationInput = Record<string, unknown>;
+
+function string(input: OperationInput, key: string): string {
+	const value = input[key];
+	if (typeof value !== "string" || value.length === 0) throw new Error(`${key} is required`);
+	return value;
+}
+
+function optionalString(input: OperationInput, key: string): string | undefined {
+	const value = input[key];
+	if (value === undefined) return undefined;
+	if (typeof value !== "string") throw new Error(`${key} must be a string`);
+	return value;
+}
+
+/** This module's own operation names, the single source of truth src/service.ts's EXPECTED_OPERATION_NAMES spreads in rather than re-listing by hand. */
+export const SESSION_IDENTITY_OPERATION_NAMES = ["session.register", "session.release"] as const;
+
+/** Registers every session.* operation against one SessionIdentity instance. */
+export function sessionIdentityOperations(sessionIdentity: SessionIdentity): OperationDefinition[] {
+	const define = <Input, Output>(name: string, execute: (input: Input) => Output): OperationDefinition<Input, Output> => ({
+		name, moduleId: MODULE_ID, execute,
+	});
+	return [
+		define("session.register", (input: OperationInput) => sessionIdentity.register(string(input, "session_id"))),
+		define("session.release", (input: OperationInput) => sessionIdentity.release(string(input, "session_id"), optionalString(input, "session_secret"))),
+	];
+}

package/src/modules/tasks.ts

@@ -23,6 +23,7 @@ import type { TaskEventContext, TaskEventDirection } from "../domain/task-event.
 import type { TaskViewMode } from "../domain/task-scope.ts";
 import type { OperationDefinition } from "../module-registry.ts";
 import type { ArtifactStore } from "../ports/artifact-store.ts";
+import type { SessionIdentity } from "../session-identity-service.ts";
 import { taskContext } from "../task-context.ts";
 import { projectTaskExecution } from "../task-execution.ts";
 import { Tasks, type TaskStatus } from "../task-service.ts";
@@ -89,13 +90,20 @@ 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): OperationDefinition[] {
+export function tasksOperations(tasks: Tasks, artifacts: ArtifactStore, sessionIdentity: SessionIdentity): OperationDefinition[] {
 	const define = <Input, Output>(name: string, execute: (input: Input) => Output): OperationDefinition<Input, Output> => ({
 		name, moduleId: MODULE_ID, execute,
 	});
+	// Enforced only for the operations where session_id is BEHAVIOR-affecting (it selects
+	// which Task Focus row is mutated), not for every session_id-carrying operation -- see
+	// domain/session-identity.ts. A session_id with no registered identity passes through
+	// unchanged (opt-in armor).
+	const guardFocusMutation = (input: OperationInput): void => {
+		sessionIdentity.assertAuthorized(eventContext(input).sessionId, optionalString(input, "session_secret"));
+	};
 	return [
 		define("tasks.create", (input: OperationInput) => tasks.create({
 			title: string(input, "title"),
@@ -139,10 +147,11 @@ export function tasksOperations(tasks: Tasks, artifacts: ArtifactStore): Operati
 		)),
 		define("tasks.active", (input: OperationInput) => tasks.active(taskFilter(input))),
 		define("tasks.focused", (input: OperationInput) => tasks.focused(taskFilter(input))),
-		define("tasks.focus", (input: OperationInput) => tasks.focus(string(input, "id"), eventContext(input))),
-		define("tasks.pause", (input: OperationInput) => tasks.pauseFocus(eventContext(input))),
-		define("tasks.unpause", (input: OperationInput) => tasks.unpauseFocus(eventContext(input))),
-		define("tasks.clear_focus", (input: OperationInput) => tasks.clearFocus(eventContext(input))),
+		define("tasks.focus", (input: OperationInput) => { guardFocusMutation(input); return tasks.focus(string(input, "id"), eventContext(input)); }),
+		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/session-identity-store.ts

@@ -0,0 +1,9 @@
+import type { SessionIdentityRecord, SessionIdentityStore as DaemonKitSessionIdentityStore } from "@danypops/daemon-kit/session-identity";
+
+/**
+ * Papyrus's persistence port for @danypops/daemon-kit's storage-agnostic session-identity
+ * primitive -- re-exported under this project's own port naming convention (src/ports/*)
+ * rather than importing the daemon-kit interface name directly at every call site.
+ */
+export type SessionIdentityStore = DaemonKitSessionIdentityStore;
+export type { SessionIdentityRecord };

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

@@ -8,6 +8,7 @@ import { SQLiteGraphProjectionStore } from "./adapters/sqlite-graph-projection-s
 import { SQLiteTaskFocusStore } from "./adapters/sqlite-task-focus-store.ts";
 import { SQLiteTaskEventStore } from "./adapters/sqlite-task-event-store.ts";
 import { SQLiteTaskScopeStore } from "./adapters/sqlite-task-scope-store.ts";
+import { SQLiteSessionIdentityStore } from "./adapters/sqlite-session-identity-store.ts";
 import type { CreateArtifactInput } from "./domain/artifact.ts";
 import { AuthorityRegistry, AuthorizedArtifactWriter, type AuthorityClaim } from "./authority-registry.ts";
 import type { TaskEventContext } from "./domain/task-event.ts";
@@ -24,6 +25,7 @@ import {
 import { Notes, NOTE_SUBTYPE } from "./note-service.ts";
 import { Logs } from "./log-service.ts";
 import { SQLiteLogStore } from "./adapters/sqlite-log-store.ts";
+import { SessionIdentity, InvalidSessionSecretError } from "./session-identity-service.ts";
 import { OperationRegistry } from "./module-registry.ts";
 import { docsOperations, DOCS_OPERATION_NAMES } from "./modules/docs.ts";
 import { graphProjectionOperations, GRAPH_PROJECTION_OPERATION_NAMES } from "./modules/graph-projection.ts";
@@ -31,6 +33,7 @@ import { logsOperations, LOGS_OPERATION_NAMES } from "./modules/logs.ts";
 import { notesOperations, NOTES_OPERATION_NAMES } from "./modules/notes.ts";
 import { rulesOperations, RULES_OPERATION_NAMES } from "./modules/rules.ts";
 import { skillsOperations, SKILLS_OPERATION_NAMES } from "./modules/skills.ts";
+import { sessionIdentityOperations, SESSION_IDENTITY_OPERATION_NAMES } from "./modules/session-identity.ts";
 import { tasksOperations, TASKS_OPERATION_NAMES } from "./modules/tasks.ts";
 
 /**
@@ -68,6 +71,7 @@ export const EXPECTED_OPERATION_NAMES = [
 	...SKILLS_OPERATION_NAMES,
 	...GRAPH_PROJECTION_OPERATION_NAMES,
 	...LOGS_OPERATION_NAMES,
+	...SESSION_IDENTITY_OPERATION_NAMES,
 ] as const;
 
 export type OperationName = typeof EXPECTED_OPERATION_NAMES[number];
@@ -77,6 +81,7 @@ type OperationHandler = (input: OperationInput) => unknown;
 export class UnknownOperationError extends Error {}
 export class MigrationRequiredError extends Error {}
 export class PayloadTooLargeError extends Error {}
+export { InvalidSessionSecretError };
 
 function string(input: OperationInput, key: string): string {
 	const value = input[key];
@@ -166,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;
 }
 
@@ -313,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"),
@@ -366,6 +374,8 @@ function handlers(
 		"graph_projection.checkpoint": forwardToModule("graph_projection.checkpoint"),
 		"logs.append": forwardToModule("logs.append"),
 		"logs.query": forwardToModule("logs.query"),
+		"session.register": forwardToModule("session.register"),
+		"session.release": forwardToModule("session.release"),
 	};
 }
 
@@ -381,11 +391,13 @@ export function createPapyrusService(path: string): PapyrusService {
 	const projections = new SQLiteGraphProjectionStore(db);
 	const artifactScopes = new SQLiteArtifactScopeStore(db);
 	const logs = new Logs(new SQLiteLogStore(db));
+	const sessionIdentity = new SessionIdentity(new SQLiteSessionIdentityStore(db));
 	const authority = createAuthorityRegistry();
 	const moduleRegistry = new OperationRegistry();
 	moduleRegistry.registerAll(notesOperations(notes));
 	moduleRegistry.registerAll(logsOperations(logs));
-	moduleRegistry.registerAll(tasksOperations(tasks, artifacts));
+	moduleRegistry.registerAll(sessionIdentityOperations(sessionIdentity));
+	moduleRegistry.registerAll(tasksOperations(tasks, artifacts, sessionIdentity));
 	moduleRegistry.registerAll(docsOperations(artifacts, artifactScopes, authority));
 	moduleRegistry.registerAll(rulesOperations(artifacts, artifactScopes));
 	moduleRegistry.registerAll(skillsOperations({ artifacts, events, scopes, artifactScopes, authority }));
@@ -408,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();
@@ -467,7 +480,7 @@ export function createApp(deps: { service: PapyrusService; token: string }): { f
 					}
 					return json({ result: await deps.service.execute(body.op, input as OperationInput) });
 				} catch (error) {
-					const status = error instanceof PayloadTooLargeError ? 413 : error instanceof UnknownOperationError ? 404 : 400;
+					const status = error instanceof PayloadTooLargeError ? 413 : error instanceof UnknownOperationError ? 404 : error instanceof InvalidSessionSecretError ? 403 : 400;
 					return json({ error: error instanceof Error ? error.message : String(error) }, { status });
 				}
 			}

package/src/session-identity-service.ts

@@ -0,0 +1,55 @@
+import { isSessionRegistered, registerSessionIdentity, releaseSessionIdentity, verifySessionSecret } from "@danypops/daemon-kit/session-identity";
+import { assertValidSessionId } from "./domain/session-identity.ts";
+import type { SessionIdentityStore } from "./ports/session-identity-store.ts";
+
+export interface RegisterSessionIdentityResult {
+	sessionId: string;
+	secret: string;
+}
+
+/** Thrown by assertSessionAuthorized when a session_id has a registered identity but the caller did not present a matching session_secret. A distinguishable type so service.ts can map it to HTTP 403, separate from generic validation's 400. */
+export class InvalidSessionSecretError extends Error {}
+
+/**
+ * Thin Papyrus-side wrapper over @danypops/daemon-kit's storage-agnostic session-identity
+ * primitive: validates input shape, binds it to Papyrus's own SQLite-backed store, and
+ * exposes the exact three operations Task Focus enforcement needs (see
+ * assertAuthorizedForFocus in src/modules/tasks.ts). See domain/session-identity.ts for the
+ * full design rationale and its explicitly accepted residual limits.
+ */
+export class SessionIdentity {
+	constructor(private readonly store: SessionIdentityStore) {}
+
+	register(sessionId: string): RegisterSessionIdentityResult {
+		assertValidSessionId(sessionId);
+		return registerSessionIdentity(this.store, sessionId);
+	}
+
+	release(sessionId: string, secret: string | undefined): { released: boolean } {
+		assertValidSessionId(sessionId);
+		const wasRegistered = isSessionRegistered(this.store, sessionId);
+		releaseSessionIdentity(this.store, sessionId, secret);
+		return { released: wasRegistered && !isSessionRegistered(this.store, sessionId) };
+	}
+
+	isRegistered(sessionId: string): boolean {
+		return isSessionRegistered(this.store, sessionId);
+	}
+
+	verify(sessionId: string, secret: string | undefined): boolean {
+		return verifySessionSecret(this.store, sessionId, secret);
+	}
+
+	/**
+	 * The enforcement point for a Focus-mutating operation: opt-in armor, matching
+	 * domain/session-identity.ts's design -- a sessionId with no registered identity passes
+	 * through unauthenticated exactly as before (undefined sessionId included, since that maps
+	 * to Task Focus's "global" scope, never armored). Only once a sessionId is registered does
+	 * a matching session_secret become mandatory.
+	 */
+	assertAuthorized(sessionId: string | undefined, secret: string | undefined): void {
+		if (sessionId === undefined) return;
+		if (!this.isRegistered(sessionId)) return;
+		if (!this.verify(sessionId, secret)) throw new InvalidSessionSecretError(`session "${sessionId}" is registered; a valid session_secret is required to mutate its Task Focus`);
+	}
+}

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