@danypops/pi-papyrus 0.59.0 → 0.59.2

package/extension/src/index.ts

@@ -42,7 +42,7 @@ import { ensureTypingCourtesyTracking, isLiveAskPending } from "./discuss/discus
 import { resolveNameFields } from "./domain-tools.ts";
 import { buildNoteWidgetSection, type NoteWidgetRow } from "./note/note-widget.ts";
 import { PLAYBOOK_BRIDGE_MAX_PLAYBOOKS, registerPlaybookBridge } from "./playbook/playbook-bridge.ts";
-import { callService, subscribeTaskPushChannel } from "./service-client.ts";
+import { callService, callServicePassive, subscribeTaskPushChannel } from "./service-client.ts";
 import { cacheSessionSecret, forgetSessionSecret, sessionSecretField } from "./session-identity.ts";
 import {
 	ActiveTaskContinuation,
@@ -152,8 +152,10 @@ export function buildTaskWidgetSection(
 export class TaskOverlay {
 	private widgetGroup: PapyrusWidgetGroup | undefined;
 	private snapshot: TaskGraph = { nodes: [], rootIds: [] };
+	private degraded = false;
 	private projectRoot: string | undefined;
 	private sessionId: string | undefined;
+	private generation = 0;
 	private readonly poll = new BoundedPoll();
 	private pushChannel: PushChannelClient | undefined;
 	private readonly rotation = new AutoRotatingWindow({
@@ -167,11 +169,13 @@ export class TaskOverlay {
 	}
 
 	setProjectRoot(projectRoot: string): void {
+		if (projectRoot !== this.projectRoot) this.generation++;
 		this.projectRoot = projectRoot;
 	}
 	// Scopes the widget's "active" glyph to this Pi session's own Focus, so a second
 	// concurrent agent's focused task never shows as active in this session's widget.
 	setSessionId(sessionId: string): void {
+		if (sessionId !== this.sessionId) this.generation++;
 		this.sessionId = sessionId;
 	}
 
@@ -183,15 +187,22 @@ export class TaskOverlay {
 	 */
 	async refresh(): Promise<void> {
 		if (!this.projectRoot) return;
+		const generation = this.generation;
+		const sessionId = this.sessionId;
+		let snapshot = this.snapshot;
+		let degraded = false;
 		try {
-			this.snapshot = await callService<Record<string, unknown>, TaskGraph>("tasks.graph", {
+			snapshot = await callServicePassive<Record<string, unknown>, TaskGraph>("tasks.graph", {
 				limit: 500,
 				project_root: this.projectRoot,
-				session_id: this.sessionId,
+				session_id: sessionId,
 			});
 		} catch {
-			this.snapshot = { nodes: [], rootIds: [] };
+			degraded = true;
 		}
+		if (generation !== this.generation) return;
+		this.snapshot = snapshot;
+		this.degraded = degraded;
 		try {
 			this.widgetGroup?.requestUpdate();
 		} catch {
@@ -217,12 +228,15 @@ export class TaskOverlay {
 	/** Theme-free existence check -- PapyrusWidgetGroup's own eager (pre-paint) hide decision needs
 	 * this without needing a theme, which is only ever available inside the widget's own render(width). */
 	hasOpenWork(): boolean {
-		return buildTaskWidgetProjection(this.snapshot).openTotal > 0;
+		return this.degraded || buildTaskWidgetProjection(this.snapshot).openTotal > 0;
 	}
 
-	/** undefined when there is no open work to show -- PapyrusWidgetGroup's own signal to omit this section entirely. */
+	/** Returns current tasks, retaining stale rows or an unavailable status while the service recovers. */
 	buildSection(theme: Theme): WidgetSection | undefined {
-		return buildTaskWidgetSection(theme, buildTaskWidgetProjection(this.snapshot), this.rotation);
+		const section = buildTaskWidgetSection(theme, buildTaskWidgetProjection(this.snapshot), this.rotation);
+		if (section) return this.degraded ? { ...section, label: `${section.label} · stale` } : section;
+		if (this.degraded) return { label: "Tasks · unavailable", render: () => ["Papyrus service unavailable; retrying."] };
+		return undefined;
 	}
 
 	/**
@@ -240,6 +254,7 @@ export class TaskOverlay {
 	}
 
 	dispose(): void {
+		this.generation++;
 		this.stopPolling();
 		this.pushChannel?.close();
 		this.pushChannel = undefined;
@@ -258,7 +273,9 @@ export class NoteOverlay {
 	private widgetGroup: PapyrusWidgetGroup | undefined;
 	private notes: NoteWidgetRow[] = [];
 	private totalOpenCount = 0;
+	private degraded = false;
 	private projectRoot: string | undefined;
+	private generation = 0;
 	private readonly poll = new BoundedPoll();
 	private readonly rotation = new AutoRotatingWindow({
 		totalRows: 0,
@@ -271,22 +288,31 @@ export class NoteOverlay {
 	}
 
 	setProjectRoot(projectRoot: string): void {
+		if (projectRoot !== this.projectRoot) this.generation++;
 		this.projectRoot = projectRoot;
 	}
 
 	async refresh(): Promise<void> {
 		if (!this.projectRoot) return;
+		const generation = this.generation;
+		const projectRoot = this.projectRoot;
+		let notes = this.notes;
+		let totalOpenCount = this.totalOpenCount;
+		let degraded = false;
 		try {
-			const rows = await callService<Record<string, unknown>, Artifact[]>("notes.list", {
-				project_root: this.projectRoot,
+			const rows = await callServicePassive<Record<string, unknown>, Artifact[]>("notes.list", {
+				project_root: projectRoot,
 				limit: NOTE_LIST_MAX_LIMIT,
 			});
-			this.totalOpenCount = rows.length;
-			this.notes = rows.slice(0, NOTE_WIDGET_OPEN_LIMIT).map((row) => ({ id: row.id, title: row.title }));
+			totalOpenCount = rows.length;
+			notes = rows.slice(0, NOTE_WIDGET_OPEN_LIMIT).map((row) => ({ id: row.id, title: row.title }));
 		} catch {
-			this.totalOpenCount = 0;
-			this.notes = [];
+			degraded = true;
 		}
+		if (generation !== this.generation) return;
+		this.totalOpenCount = totalOpenCount;
+		this.notes = notes;
+		this.degraded = degraded;
 		try {
 			this.widgetGroup?.requestUpdate();
 		} catch {
@@ -296,12 +322,15 @@ export class NoteOverlay {
 
 	/** Theme-free existence check -- see TaskOverlay's own hasOpenWork() for why this needs to stay theme-free. */
 	hasOpenNotes(): boolean {
-		return this.totalOpenCount > 0;
+		return this.degraded || this.totalOpenCount > 0;
 	}
 
-	/** undefined when there are no open notes -- PapyrusWidgetGroup's own signal to omit this section entirely. */
+	/** Returns current notes, retaining stale rows or an unavailable status while the service recovers. */
 	buildSection(): WidgetSection | undefined {
-		return buildNoteWidgetSection(this.notes, this.totalOpenCount, this.rotation);
+		const section = buildNoteWidgetSection(this.notes, this.totalOpenCount, this.rotation);
+		if (section) return this.degraded ? { ...section, label: `${section.label} · stale` } : section;
+		if (this.degraded) return { label: "Notes · unavailable", render: () => ["Papyrus service unavailable; retrying."] };
+		return undefined;
 	}
 
 	startPolling(intervalMs: number = NOTE_WIDGET_POLL_INTERVAL_MS): void {
@@ -315,6 +344,7 @@ export class NoteOverlay {
 	}
 
 	dispose(): void {
+		this.generation++;
 		this.stopPolling();
 		this.widgetGroup = undefined;
 		this.projectRoot = undefined;
@@ -441,7 +471,7 @@ export class PapyrusWidgetGroup {
 // Entry point
 // ---------------------------------------------------------------------------
 
-export default async function (pi: ExtensionAPI) {
+export default function (pi: ExtensionAPI) {
 	setTaskFocusEventBus(pi);
 	registerPlaybookBridge(pi);
 	let contextInjectionSequence = 0;
@@ -492,7 +522,12 @@ export default async function (pi: ExtensionAPI) {
 					session_id: sessionId,
 					...sessionSecretField(sessionId),
 				});
-				emitTaskFocusEvent({ taskId: paused.artifact.id, sessionId, status: "paused", effort: extractDeclaredEffort(paused.artifact.extra) });
+				emitTaskFocusEvent({
+					taskId: paused.artifact.id,
+					sessionId,
+					status: "paused",
+					effort: extractDeclaredEffort(paused.artifact.extra),
+				});
 				if (ctx.hasUI) ctx.ui.notify(`Papyrus task driving paused: ${decision.reason}. Human input resumes it automatically.`, "warning");
 			}
 		} catch {
@@ -717,15 +752,25 @@ export default async function (pi: ExtensionAPI) {
 
 	// ── Interactive artifact browsers ──────────────────────────────────
 
-	// Lazy imports keep TUI components out of non-interactive startup paths.
-	const [tasksModule, docsModule, notesModule, rulesModule, playbooksModule, discussModule] = await Promise.all([
-		import("./task/tasks.ts"),
-		import("./docs/docs.ts"),
-		import("./note/notes.ts"),
-		import("./rules/rules.ts"),
-		import("./playbook/playbooks.ts"),
-		import("./discuss/discuss.ts"),
-	]);
+	// Command modules are loaded on first use. Registration itself stays synchronous,
+	// so interactive-only TUI code cannot delay extension startup.
+	const loadTasks = () => import("./task/tasks.ts");
+	const loadDocs = () => import("./docs/docs.ts");
+	const loadNotes = () => import("./note/notes.ts");
+	const loadRules = () => import("./rules/rules.ts");
+	let loadedPlaybooks: Awaited<ReturnType<typeof importPlaybooks>> | undefined;
+	let playbooksPromise: ReturnType<typeof importPlaybooks> | undefined;
+	function importPlaybooks() {
+		return import("./playbook/playbooks.ts");
+	}
+	function loadPlaybooks() {
+		playbooksPromise ??= importPlaybooks().then((module) => {
+			loadedPlaybooks = module;
+			return module;
+		});
+		return playbooksPromise;
+	}
+	const loadDiscuss = () => import("./discuss/discuss.ts");
 	let overlay: TaskOverlay | undefined;
 	let noteOverlay: NoteOverlay | undefined;
 	let widgetGroup: PapyrusWidgetGroup | undefined;
@@ -735,20 +780,20 @@ export default async function (pi: ExtensionAPI) {
 		handler: async (_args, ctx) => {
 			overlay?.setProjectRoot(ctx.cwd);
 			overlay?.setSessionId(ctx.sessionManager.getSessionId());
-			await tasksModule.showTasks(ctx);
+			await (await loadTasks()).showTasks(ctx);
 			await overlay?.refresh();
 		},
 	});
 	pi.registerCommand("docs", {
 		description: "Browse and manage Papyrus documents (interactive)",
 		handler: async (_args, ctx) => {
-			await docsModule.showDocs(ctx);
+			await (await loadDocs()).showDocs(ctx);
 		},
 	});
 	pi.registerCommand("note", {
 		description: "Capture a deferred request directly in Papyrus",
 		handler: async (args, ctx) => {
-			await notesModule.captureNote(args, ctx);
+			await (await loadNotes()).captureNote(args, ctx);
 			await noteOverlay?.refresh();
 		},
 	});
@@ -756,34 +801,38 @@ export default async function (pi: ExtensionAPI) {
 		description: "Browse and triage the project Notes inbox",
 		handler: async (_args, ctx) => {
 			noteOverlay?.setProjectRoot(ctx.cwd);
-			await notesModule.showNotes(ctx);
+			await (await loadNotes()).showNotes(ctx);
 			await noteOverlay?.refresh();
 		},
 	});
 	pi.registerCommand("rules", {
 		description: "Browse, preview, and toggle Papyrus rules (interactive)",
 		handler: async (_args, ctx) => {
-			await rulesModule.showRules(ctx);
+			await (await loadRules()).showRules(ctx);
 		},
 	});
 	pi.registerCommand("playbooks", {
 		description: "Browse, edit, and invoke Papyrus playbooks -- trigger/steps guidance an agent reads and follows (interactive)",
 		handler: async (_args, ctx) => {
-			await playbooksModule.showPlaybooks(ctx);
+			await (await loadPlaybooks()).showPlaybooks(ctx);
 		},
 	});
 	pi.registerCommand("playbook", {
 		description:
 			"Open one Papyrus playbook directly by name (tab-completes active playbook titles) and place its invocation in the editor; no argument opens the full /playbooks browser instead",
-		getArgumentCompletions: (argumentPrefix) => playbooksModule.playbookArgumentCompletions(argumentPrefix),
+		getArgumentCompletions: (argumentPrefix) => {
+			if (loadedPlaybooks) return loadedPlaybooks.playbookArgumentCompletions(argumentPrefix);
+			void loadPlaybooks();
+			return [];
+		},
 		handler: async (args, ctx) => {
-			await playbooksModule.openPlaybookByName(args, ctx);
+			await (await loadPlaybooks()).openPlaybookByName(args, ctx);
 		},
 	});
 	pi.registerCommand("discuss", {
 		description: "Browse Papyrus Discussions and reply, defer, resume, settle, or block/unblock a task (interactive)",
 		handler: async (_args, ctx) => {
-			await discussModule.showDiscussions(ctx);
+			await (await loadDiscuss()).showDiscussions(ctx);
 		},
 	});
 
@@ -797,22 +846,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
-		}
+	let sessionGeneration = 0;
+	pi.on("session_start", (_event, ctx) => {
+		const generation = ++sessionGeneration;
+		const sessionId = ctx.sessionManager.getSessionId();
+		// Identity registration is best-effort lifecycle bookkeeping. It starts now but
+		// cannot hold Pi's first paint behind a daemon connection or retry budget.
+		void callServicePassive<Record<string, unknown>, { sessionId: string; secret: string }>("session.register", {
+			session_id: sessionId,
+		})
+			.then(({ secret }) => {
+				if (generation === sessionGeneration) cacheSessionSecret(sessionId, secret);
+			})
+			.catch(() => {});
 		if (!ctx.hasUI) return;
 		// Attached from session start, not lazily on first ask -- a per-ask listener would only see
 		// keystrokes from the moment that tool call happens to begin, missing typing already in
@@ -824,7 +870,7 @@ export default async function (pi: ExtensionAPI) {
 		overlay ??= new TaskOverlay();
 		overlay.setWidgetGroup(widgetGroup);
 		overlay.setProjectRoot(ctx.cwd);
-		overlay.setSessionId(ctx.sessionManager.getSessionId());
+		overlay.setSessionId(sessionId);
 
 		noteOverlay ??= new NoteOverlay();
 		noteOverlay.setWidgetGroup(widgetGroup);
@@ -832,10 +878,11 @@ export default async function (pi: ExtensionAPI) {
 
 		widgetGroup.setOverlays(overlay, noteOverlay);
 
-		await overlay.refresh();
-		overlay.startPolling(TASK_WIDGET_POLL_INTERVAL_MS);
-		await noteOverlay.refresh();
-		noteOverlay.startPolling(NOTE_WIDGET_POLL_INTERVAL_MS);
+		void Promise.all([overlay.refresh(), noteOverlay.refresh()]).then(() => {
+			if (generation !== sessionGeneration) return;
+			overlay?.startPolling(TASK_WIDGET_POLL_INTERVAL_MS);
+			noteOverlay?.startPolling(NOTE_WIDGET_POLL_INTERVAL_MS);
+		});
 	});
 
 	pi.on("session_before_compact", () => {
@@ -847,20 +894,18 @@ export default async function (pi: ExtensionAPI) {
 	pi.on("session_tree", async () => {
 		await Promise.all([overlay?.refresh(), noteOverlay?.refresh()]);
 	});
-	pi.on("session_shutdown", async (_event, ctx) => {
+	pi.on("session_shutdown", (_event, ctx) => {
+		sessionGeneration++;
 		overlay?.dispose();
 		overlay = undefined;
 		noteOverlay?.dispose();
 		noteOverlay = undefined;
 		widgetGroup?.dispose();
 		widgetGroup = 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
-		}
+		const sessionId = ctx.sessionManager.getSessionId();
+		const secret = sessionSecretField(sessionId);
+		forgetSessionSecret(sessionId);
+		void callServicePassive("session.release", { session_id: sessionId, ...secret }).catch(() => {});
 	});
 
 	// Update widgets after any papyrus tool call

package/extension/src/playbook/playbook-bridge.ts

@@ -21,7 +21,7 @@
 import type { Artifact } from "@danypops/papyrus";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { buildActivationContext } from "../context/activation-context.ts";
-import { callService } from "../service-client.ts";
+import { callService, callServicePassive } from "../service-client.ts";
 
 export const PLAYBOOK_BRIDGE_MAX_PLAYBOOKS = 100;
 
@@ -34,8 +34,14 @@ function slugify(title: string): string {
 	return slug.length > 0 ? slug : "playbook";
 }
 
-async function activePlaybooks(projectRoot?: string, capabilities: readonly string[] = []): Promise<Artifact[]> {
-	return callService<Record<string, unknown>, Artifact[]>("playbooks.list", {
+type ServiceCall = <Input extends Record<string, unknown>, Output>(operation: "playbooks.list", input: Input) => Promise<Output>;
+
+async function activePlaybooks(
+	projectRoot?: string,
+	capabilities: readonly string[] = [],
+	serviceCall: ServiceCall = callService,
+): Promise<Artifact[]> {
+	return serviceCall<Record<string, unknown>, Artifact[]>("playbooks.list", {
 		status: "active",
 		full: true,
 		limit: PLAYBOOK_BRIDGE_MAX_PLAYBOOKS,
@@ -70,8 +76,9 @@ export function playbookInjectionPreview(playbook: Pick<Artifact, "title" | "ext
 export async function planPlaybookCommandRegistrations(
 	projectRoot?: string,
 	capabilities: readonly string[] = [],
+	serviceCall: ServiceCall = callService,
 ): Promise<Array<{ name: string; id: string; title: string; trigger: string }>> {
-	const playbooks = await activePlaybooks(projectRoot, capabilities);
+	const playbooks = await activePlaybooks(projectRoot, capabilities, serviceCall);
 	const usedNames = new Set<string>();
 	return playbooks.map((playbook) => {
 		let name = playbookCommandName(playbook.title);
@@ -82,10 +89,18 @@ export async function planPlaybookCommandRegistrations(
 	});
 }
 
-export function registerPlaybookBridge(pi: ExtensionAPI): void {
-	const refresh = async (projectRoot?: string) => {
+export interface PlaybookBridgeHandle {
+	/** Explicit test/shutdown boundary for the most recently scheduled discovery refresh. */
+	waitForRefresh(): Promise<void>;
+}
+
+export function registerPlaybookBridge(pi: ExtensionAPI): PlaybookBridgeHandle {
+	let generation = 0;
+	let latestRefresh = Promise.resolve();
+	const refresh = async (projectRoot: string | undefined, scheduledGeneration: number) => {
 		try {
-			const registrations = await planPlaybookCommandRegistrations(projectRoot, pi.getActiveTools?.() ?? []);
+			const registrations = await planPlaybookCommandRegistrations(projectRoot, pi.getActiveTools?.() ?? [], callServicePassive);
+			if (scheduledGeneration !== generation) return;
 			for (const { name, id, title, trigger } of registrations) {
 				pi.registerCommand(name, {
 					description: trigger,
@@ -126,8 +141,13 @@ export function registerPlaybookBridge(pi: ExtensionAPI): void {
 			// "no new/updated playbook commands this cycle", not a broken session start.
 		}
 	};
-	pi.on("resources_discover", async (event) => {
-		await refresh(event?.cwd);
+	pi.on("resources_discover", (event) => {
+		const scheduledGeneration = ++generation;
+		latestRefresh = refresh(event?.cwd, scheduledGeneration);
 		return {};
 	});
+	pi.on("session_shutdown", () => {
+		generation++;
+	});
+	return { waitForRefresh: () => latestRefresh };
 }

package/extension/src/service-client.ts

@@ -25,6 +25,13 @@ const client: RetryingClient<PapyrusClient> = createRetryingClient<PapyrusClient
 	connectRetry: true,
 });
 
+// Passive lifecycle work must fail fast when the daemon is absent. The regular
+// client keeps its restart-surviving retry budget for explicit user/tool calls.
+const passiveClient: RetryingClient<PapyrusClient> = createRetryingClient<PapyrusClient>(() => connector(), {
+	label: "Papyrus passive",
+	connectRetry: false,
+});
+
 export async function papyrusClient(): Promise<PapyrusClient> {
 	return client.call(async (resolved) => resolved);
 }
@@ -33,14 +40,24 @@ export async function callService<Input extends Record<string, unknown>, Output>
 	return client.call((resolved) => resolved.call<Input, Output>(operation, input));
 }
 
+/** Fail-fast daemon call for widgets, discovery, and lifecycle bookkeeping. */
+export async function callServicePassive<Input extends Record<string, unknown>, Output>(
+	operation: OperationName,
+	input: Input,
+): Promise<Output> {
+	return passiveClient.call((resolved) => resolved.call<Input, Output>(operation, input));
+}
+
 export function setPapyrusClientConnectorForTests(value: ClientConnector): void {
 	connector = value;
 	client.reset();
+	passiveClient.reset();
 }
 
 export function resetPapyrusClientForTests(): void {
 	connector = () => connectPapyrusClient();
 	client.reset();
+	passiveClient.reset();
 }
 
 let pushChannelTargetResolver: typeof resolvePushChannelTarget = resolvePushChannelTarget;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/pi-papyrus",
-  "version": "0.59.0",
+  "version": "0.59.2",
   "description": "Pi host extension for Papyrus: native tools, TUI panels, and context injection over the daemon-backed graph store",
   "license": "MIT",
   "type": "module",
@@ -20,7 +20,7 @@
   },
   "dependencies": {
     "@danypops/jittor": "^0.19.2",
-    "@danypops/papyrus": "^0.60.7",
+    "@danypops/papyrus": "^0.60.10",
     "@danypops/vehicle-client": "^0.10.3",
     "@danypops/vehicle-core": "^0.18.5",
     "@danypops/vehicle-server": "^0.25.2",
@@ -28,6 +28,7 @@
     "malevich-tui-components": "^0.32.1"
   },
   "devDependencies": {
+    "@danypops/pi-extension-harness": "^0.8.3",
     "@danypops/pi-tui-harness": "^0.0.2",
     "@danypops/vehicle-client-pi": "^0.46.0",
     "@danypops/vehicle-conformance": "^0.3.0",