@danypops/papyrus 0.15.2 → 0.17.0

package/extension/src/base-prompt-breakdown.ts

@@ -0,0 +1,55 @@
+import type { BuildSystemPromptOptions } from "@earendil-works/pi-coding-agent";
+import { CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN } from "../../src/constants.ts";
+import type { ContextSegmentItem } from "./context-budget.ts";
+
+/**
+ * Splits Pi's base system prompt into real structural sub-segments instead of one opaque
+ * number, using BeforeAgentStartEvent's own systemPromptOptions field -- Pi's own doc comment
+ * on it: "Extensions can inspect this to understand what Pi loaded without re-discovering
+ * resources." No new hook, no new risk: before_agent_start is already wired.
+ *
+ * Deliberately measures each INPUT's raw content size (tool snippet text, skill metadata,
+ * context file content) rather than attempting to byte-for-byte reproduce Pi's internal
+ * wrapping/tag format -- buildSystemPrompt() and formatSkillsForPrompt() are Pi-internal
+ * functions, not part of the public extension API Papyrus can call, so reproducing their
+ * exact template text here would be a real, silent drift risk if Pi ever changes it. The
+ * remainder item absorbs whatever wrapping/template text this doesn't attribute, so the
+ * segment's total always still matches the real observed prompt length exactly -- honesty
+ * preserved even though individual sub-segment sizes are approximate, matching the same
+ * known-segments-plus-honest-remainder pattern used everywhere else in this breakdown.
+ */
+export function buildBasePromptItems(options: BuildSystemPromptOptions, totalCharacters: number): ContextSegmentItem[] {
+	const items: ContextSegmentItem[] = [];
+
+	const toolSnippetEntries = Object.entries(options.toolSnippets ?? {});
+	// Mirrors buildSystemPrompt()'s own "- name: snippet\n" line shape closely enough to be a
+	// fair estimate without importing Pi-internal formatting code.
+	const toolSnippetsCharacters = toolSnippetEntries.reduce((sum, [name, snippet]) => sum + name.length + snippet.length + 4, 0);
+	if (toolSnippetsCharacters > 0) {
+		items.push({ label: `Tool snippets (${toolSnippetEntries.length} tools)`, estimatedTokens: toCeilTokens(toolSnippetsCharacters) });
+	}
+
+	const visibleSkills = (options.skills ?? []).filter((skill) => !skill.disableModelInvocation);
+	const skillsCharacters = visibleSkills.reduce((sum, skill) => sum + skill.name.length + skill.description.length + skill.filePath.length + 20, 0);
+	if (skillsCharacters > 0) {
+		items.push({ label: `Skills catalog (${visibleSkills.length} skills)`, estimatedTokens: toCeilTokens(skillsCharacters) });
+	}
+
+	const contextFiles = options.contextFiles ?? [];
+	const contextFilesCharacters = contextFiles.reduce((sum, file) => sum + file.path.length + file.content.length + 40, 0);
+	if (contextFilesCharacters > 0) {
+		items.push({ label: `Project context files (${contextFiles.length}, e.g. AGENTS.md)`, estimatedTokens: toCeilTokens(contextFilesCharacters) });
+	}
+
+	const knownCharacters = toolSnippetsCharacters + skillsCharacters + contextFilesCharacters;
+	const remainderCharacters = Math.max(0, totalCharacters - knownCharacters);
+	if (remainderCharacters > 0 || items.length === 0) {
+		items.push({ label: "Base template, guidelines, and formatting", estimatedTokens: toCeilTokens(remainderCharacters) });
+	}
+
+	return items;
+}
+
+function toCeilTokens(characters: number): number {
+	return Math.ceil(characters / CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN);
+}

package/extension/src/context-budget.ts

@@ -295,6 +295,8 @@ export interface BuildContextBreakdownInput {
 	skills: SkillCatalogFootprint;
 	/** Pi's own base system prompt size, cached from the last observed before_agent_start turn. Null before any turn has run yet. */
 	basePromptEstimatedTokens: number | null;
+	/** Structural sub-breakdown (tool snippets, Skills, context files, template remainder) from the same cached observation, built by buildBasePromptItems(). Empty when basePromptEstimatedTokens is null. */
+	basePromptItems?: ContextSegmentItem[];
 	/** From buildMessageHistoryTree() against the live session's real tree (ctx.sessionManager.getTree()). */
 	messageHistoryItems: ContextSegmentItem[];
 	/** buildMessageHistoryTree()'s activeTokens -- only entries on the current active path count toward the segment total; an abandoned /tree branch still appears in messageHistoryItems but contributes zero here. */
@@ -416,6 +418,7 @@ export function buildContextBreakdown(input: BuildContextBreakdownInput): Contex
 		label: input.basePromptEstimatedTokens === null ? "Base system prompt (not observed yet)" : "Base system prompt (Pi + host instructions)",
 		estimatedTokens: input.basePromptEstimatedTokens ?? 0,
 		...(input.basePromptEstimatedTokens === null ? { unknown: true } : {}),
+		...(input.basePromptItems && input.basePromptItems.length > 0 ? { items: input.basePromptItems } : {}),
 	};
 	const messageHistory: ContextSegment = {
 		key: "messageHistory",

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

@@ -27,9 +27,11 @@ import { ActiveTaskContinuation, automaticPauseReason, shouldResumeFocusOnHumanI
 import { buildTaskWidgetProjection, type TaskWidgetProjection } from "./task-widget.ts";
 import { TASK_STATUS_PRESENTATION, taskTreeConnector } from "./task-presentation.ts";
 import { buildContextInjection } from "./context-injection-telemetry.ts";
-import { buildContextBreakdown, buildMessageHistoryTree, buildTaskItemTree, computeContextBudget, computeRuleBudget, DEFAULT_RESERVE_TOKENS, type SessionEntryLike, type SessionTreeNodeLike } from "./context-budget.ts";
+import { buildContextBreakdown, buildMessageHistoryTree, buildTaskItemTree, computeContextBudget, computeRuleBudget, DEFAULT_RESERVE_TOKENS, type ContextSegmentItem, type SessionEntryLike, type SessionTreeNodeLike } from "./context-budget.ts";
+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,
@@ -164,8 +166,12 @@ export default async function (pi: ExtensionAPI) {
 	// Cached from the most recent before_agent_start observation: Pi's own base system prompt
 	// is only ever visible transiently inside that hook's event.systemPrompt, so /context
 	// reuses the size buildContextInjection already computes every turn rather than going
-	// without it entirely.
+	// without it entirely. basePromptItems is the structural sub-breakdown built from the same
+	// event's systemPromptOptions field ("Extensions can inspect this to understand what Pi
+	// loaded without re-discovering resources", per Pi's own doc comment) -- no new hook, no new
+	// risk, just reading a field before_agent_start already hands over.
 	let lastObservedBasePromptTokens: number | null = null;
+	let lastObservedBasePromptItems: ContextSegmentItem[] = [];
 	const taskContinuation = new ActiveTaskContinuation({
 		maxTurns: TASK_DRIVER_MAX_TURNS,
 		maxUnchangedTurns: TASK_DRIVER_MAX_UNCHANGED_TURNS,
@@ -192,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");
@@ -480,6 +487,7 @@ export default async function (pi: ExtensionAPI) {
 					taskItems: buildTaskItemTree(taskGraph),
 					skills,
 					basePromptEstimatedTokens: lastObservedBasePromptTokens,
+					basePromptItems: lastObservedBasePromptItems,
 					messageHistoryItems: messageHistory.items,
 					messageHistoryActiveTokens: messageHistory.activeTokens,
 				});
@@ -493,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);
@@ -504,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) => {
@@ -524,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 {
@@ -559,6 +590,7 @@ export default async function (pi: ExtensionAPI) {
 			});
 			previousContextInjectionFingerprint = injection.observation.fingerprint;
 			lastObservedBasePromptTokens = Math.ceil(injection.observation.before.characters / CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN);
+			lastObservedBasePromptItems = buildBasePromptItems(event.systemPromptOptions, injection.observation.before.characters);
 			pi.events.emit(PAPYRUS_CONTEXT_INJECTION_CHANNEL, injection.observation);
 			if (injection.prompt !== (event.systemPrompt ?? "")) return { systemPrompt: injection.prompt };
 		} 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.15.2",
+  "version": "0.17.0",
   "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/cli.ts

@@ -112,18 +112,20 @@ 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 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 +144,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 +912,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 +1005,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 +1028,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 +1082,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,14 +1107,14 @@ 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;
@@ -1206,7 +1246,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 +1348,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,8 @@ 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;
+/** 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/db.ts

@@ -210,6 +210,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 +293,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 +644,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";
@@ -92,10 +93,17 @@ export const TASKS_OPERATION_NAMES = [
 	"tasks.depend", "tasks.undepend", "tasks.contain", "tasks.uncontain",
 ] 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,10 @@ 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.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/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];
@@ -366,6 +371,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 +388,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 }));
@@ -467,7 +476,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`);
+	}
+}