pi-session-continuity 0.1.0

package/docs/release-readiness/local-v1-readiness-2026-07-07.md

@@ -0,0 +1,76 @@
+# Local v1 Readiness Report — Pi Session Continuity
+
+Date: 2026-07-07
+Status: Local v1 readiness candidate
+Scope: Local validation only; no external install, tag, release, publish, push, upload, or repository mutation performed.
+
+## Summary
+
+Pi Session Continuity has local v0.1.0 readiness evidence across package shape, artifact/config behavior, manual checkpoint handoff, status/settings, automatic threshold triggering, compaction hygiene, tests/smoke collateral, and public documentation.
+
+The product invariant remains intact:
+
+```text
+Durable Continuity Brief first.
+Resume prompt is injected from the disk artifact.
+Compaction is token hygiene, not the source of continuity.
+```
+
+## Episode evidence
+
+| Episode | Status | Primary evidence |
+| --- | --- | --- |
+| EPN-0001 package skeleton | Done | `specforge/runs/RUN-0001/autonomous-loop-result.yaml`; `docs/deploys/deploy-2026-07-07-SCOPE-0001-package-skeleton.md` |
+| EPN-0002 core artifact engine | Done | `specforge/runs/RUN-0002/autonomous-loop-result.yaml`; `docs/deploys/deploy-2026-07-07-SCOPE-0002-core-artifact-engine.md` |
+| EPN-0003 manual checkpoint | Done | `specforge/runs/RUN-0003/autonomous-loop-result.yaml`; `docs/deploys/deploy-2026-07-07-SCOPE-0003-manual-checkpoint.md` |
+| EPN-0004 status/settings | Done | `specforge/runs/RUN-0004/autonomous-loop-result.yaml`; `docs/deploys/deploy-2026-07-07-SCOPE-0004-status-settings.md` |
+| EPN-0005 automatic threshold | Done | `specforge/runs/RUN-0005/autonomous-loop-result.yaml`; `docs/deploys/deploy-2026-07-07-SCOPE-0005-automatic-threshold.md` |
+| EPN-0006 compaction hygiene | Done | `specforge/runs/RUN-0006/autonomous-loop-result.yaml`; `docs/deploys/deploy-2026-07-07-SCOPE-0006-compaction-hygiene.md` |
+| EPN-0007 tests + smoke scripts | Done | `specforge/runs/RUN-0007/autonomous-loop-result.yaml`; `docs/deploys/deploy-2026-07-07-SCOPE-0007-tests-smoke.md` |
+| EPN-0008 public docs/release readiness | Done | `specforge/runs/RUN-0008/autonomous-loop-result.yaml`; `docs/deploys/deploy-2026-07-07-SCOPE-0008-public-docs-release-readiness.md` |
+| EPN-0009 dogfood hardening/local readiness | Done | `specforge/runs/RUN-0009/autonomous-loop-result.yaml`; `docs/deploys/deploy-2026-07-07-SCOPE-0009-dogfood-hardening-local-readiness.md` |
+
+## Final local gates
+
+Final RUN-0009 local gates:
+
+- `npm test` — `CMD-0002`
+- `npm run typecheck` — `CMD-0003`
+- `npm run smoke:manual` — `CMD-0004`
+- `npm pack --dry-run` — `CMD-0007`
+- forbidden runtime terminology grep — `CMD-0008`
+- final reviewer verdict — `specforge/runs/RUN-0009/subagents/JUDGE-0001.md` (PASS)
+
+## Local capability coverage
+
+- Package manifest: `package.json` declares `pi-session-continuity` v0.1.0, `pi-package` keyword, Pi extension entrypoint, scripts, peer/dev dependency placement, and packaged docs/scripts.
+- Runtime entrypoint: `extensions/session-continuity/index.ts` registers `/continuity` and lifecycle hooks.
+- Config: `src/config.ts` covers trusted-project loading, validation, percentage math, and artifact directory resolution.
+- Artifact contract: `src/artifact.ts` covers frontmatter, mandatory headings, status transitions, resume prompt rejection for non-pending artifacts, and directive-looking content boundaries.
+- Handoff: `src/handoff.ts` writes/re-reads disk artifacts before queueing prompts, suppresses duplicates, archives after queue, and treats compaction as post-safe-path hygiene.
+- Status/settings: `src/status.ts` reports complete status/settings fields and stale same-session pending artifacts.
+- Automatic threshold: `src/trigger.ts` provides pure trigger decisions for disabled/untrusted/invalid/unavailable/below-threshold/threshold-reached states.
+- Tests: `test/*.test.ts` cover local product gates, including package/docs/smoke collateral.
+- Smoke template: `scripts/smoke/manual-checks.sh` lists all required manual Pi smoke assertions with PASS/FAIL fields.
+
+## Deferrals and residual risks
+
+External validation is intentionally not performed in this local readiness run. Before public tag or announcement, Bernardo must explicitly approve the external validation step and then run/record at least:
+
+```bash
+pi -e git:github.com/<owner>/pi-session-continuity@v0.1.0
+pi install git:github.com/<owner>/pi-session-continuity@v0.1.0
+```
+
+Required clean-install smoke evidence remains:
+
+- package loads from GitHub ref without local workspace paths;
+- `/continuity status` appears and reports config state;
+- `/continuity checkpoint` writes a valid artifact;
+- resume prompt is queued from the exact saved artifact;
+- invalid config and untrusted project behavior are explicit and safe;
+- package removal works without manual code cleanup.
+
+## Decision point
+
+Local v1 readiness is accepted by RUN-0009 final gates and reviewer PASS. The next decision is whether Bernardo approves external clean-install/tag/release validation. No external action should happen without that separate approval.

package/extensions/session-continuity/index.ts

@@ -0,0 +1,317 @@
+import {
+	CONFIG_DIR_NAME,
+	type ExtensionAPI,
+	type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import {
+	loadConfig,
+	publicConfigFromResolved,
+	validateConfigDraftForPath,
+	writeConfigToDisk,
+	type ContinuityConfig,
+	type ResolvedContinuityConfig,
+	type SynthesisEffort,
+} from "../../src/config.js";
+import {
+	AUTOMATIC_FAILURE_COOLDOWN_MS,
+	PRODUCT_NAME,
+} from "../../src/constants.js";
+import { createHandoffState, runContinuityHandoff } from "../../src/handoff.js";
+import {
+	findStalePendingArtifacts,
+	footerStatusForMessage,
+	formatSettings,
+	formatStatus,
+	notifyStatus,
+	statusHeadlineForConfig,
+} from "../../src/status.js";
+import { decideAutomaticTrigger } from "../../src/trigger.js";
+
+export default function sessionContinuityExtension(pi: ExtensionAPI) {
+	const state = createHandoffState();
+	let currentConfig: ResolvedContinuityConfig | undefined;
+	let staleNotificationSent = false;
+
+	pi.registerMessageRenderer(
+		"session-continuity-panel",
+		(message, _options, theme) => {
+			const content =
+				typeof message.content === "string" ? message.content : "";
+			const [headline = "", ...rest] = content.split("\n");
+			const text = [theme.bold(headline), ...rest].join("\n");
+			return new Text(text, 1, 1);
+		},
+	);
+
+	function showCommandOutput(ctx: ExtensionContext, message: string): void {
+		if (!ctx.hasUI) {
+			process.stdout.write(`${message}\n`);
+			return;
+		}
+		notifyStatus(ctx, message);
+	}
+
+	function showCommandPanel(ctx: ExtensionContext, message: string): void {
+		if (ctx.hasUI && ctx.mode === "tui") {
+			pi.sendMessage({
+				customType: "session-continuity-panel",
+				content: message,
+				display: true,
+				details: { product: PRODUCT_NAME },
+			});
+			ctx.ui.setStatus("session-continuity", footerStatusForMessage(message));
+			return;
+		}
+		showCommandOutput(ctx, message);
+	}
+
+	async function refreshConfig(
+		ctx: ExtensionContext,
+	): Promise<ResolvedContinuityConfig> {
+		currentConfig = await loadConfig(ctx, CONFIG_DIR_NAME);
+		return currentConfig;
+	}
+
+	async function saveConfigDraft(
+		ctx: ExtensionContext,
+		draft: ContinuityConfig,
+	): Promise<ResolvedContinuityConfig | undefined> {
+		const config = currentConfig ?? (await refreshConfig(ctx));
+		const errors = validateConfigDraftForPath(draft, config.configPath);
+		if (errors.length > 0) {
+			ctx.ui.notify(
+				`${PRODUCT_NAME}: settings not saved. ${errors.join("; ")}`,
+				"warning",
+			);
+			return undefined;
+		}
+		await writeConfigToDisk(config.configPath, draft);
+		const refreshed = await refreshConfig(ctx);
+		ctx.ui.notify(`${PRODUCT_NAME}: settings saved.`, "info");
+		ctx.ui.setStatus(
+			"session-continuity",
+			footerStatusForMessage(statusHeadlineForConfig(refreshed)),
+		);
+		return refreshed;
+	}
+
+	function triggerPercentChoices(predicate: (value: number) => boolean) {
+		return Array.from({ length: 10 }, (_, index) => 50 + index * 5)
+			.filter(predicate)
+			.map((value) => `${value}%`);
+	}
+
+	function keepPercentChoices(predicate: (value: number) => boolean) {
+		return [5, 10, 15, 20, 25].filter(predicate).map((value) => `${value}%`);
+	}
+
+	async function openSettingsMenu(
+		ctx: ExtensionContext,
+		initialConfig: ResolvedContinuityConfig,
+	): Promise<void> {
+		if (!ctx.hasUI || ctx.mode !== "tui" || !initialConfig.trusted) {
+			showCommandPanel(ctx, formatSettings(initialConfig));
+			return;
+		}
+
+		let config = initialConfig;
+		for (;;) {
+			const choice = await ctx.ui.select("Pi Session Continuity settings", [
+				`Enabled: ${config.enabled ? "on" : "off"}`,
+				`Trigger threshold: ${config.triggerAtPercent}%`,
+				`Keep after handoff: ${config.keepRecentPercent}%`,
+				`Synthesis model: ${config.synthesisModel}`,
+				`Synthesis effort: ${config.synthesisEffort}`,
+				`Artifact directory: ${config.artifactDirectory}`,
+				"Done",
+			]);
+			if (!choice || choice === "Done") return;
+
+			const draft = publicConfigFromResolved(config);
+			if (choice.startsWith("Enabled:")) {
+				const enabled = await ctx.ui.select("Enable automatic handoffs?", [
+					"on",
+					"off",
+				]);
+				if (!enabled) continue;
+				draft.enabled = enabled === "on";
+			} else if (choice.startsWith("Trigger threshold:")) {
+				const trigger = await ctx.ui.select(
+					"Trigger when context reaches",
+					triggerPercentChoices((value) => value > draft.keepRecentPercent),
+				);
+				if (!trigger) continue;
+				draft.triggerAtPercent = Number.parseInt(trigger, 10);
+			} else if (choice.startsWith("Keep after handoff:")) {
+				const keep = await ctx.ui.select(
+					"Keep recent context after handoff",
+					keepPercentChoices((value) => value < draft.triggerAtPercent),
+				);
+				if (!keep) continue;
+				draft.keepRecentPercent = Number.parseInt(keep, 10);
+			} else if (choice.startsWith("Synthesis model:")) {
+				const model = await ctx.ui.input(
+					'Synthesis model ("inherit" or provider/model)',
+					config.synthesisModel,
+				);
+				if (!model) continue;
+				draft.synthesisModel = model.trim();
+			} else if (choice.startsWith("Synthesis effort:")) {
+				const effort = await ctx.ui.select("Synthesis effort", [
+					"inherit",
+					"minimal",
+					"low",
+					"medium",
+					"high",
+					"xhigh",
+				]);
+				if (!effort) continue;
+				draft.synthesisEffort = effort as SynthesisEffort;
+			} else if (choice.startsWith("Artifact directory:")) {
+				const artifactDirectory = await ctx.ui.input(
+					"Artifact directory (relative to Pi config dir unless absolute)",
+					config.artifactDirectory,
+				);
+				if (!artifactDirectory) continue;
+				draft.artifactDirectory = artifactDirectory.trim();
+			} else {
+				notifyStatus(ctx, formatSettings(config));
+				continue;
+			}
+
+			const refreshed = await saveConfigDraft(ctx, draft);
+			if (refreshed) config = refreshed;
+		}
+	}
+
+	pi.on("session_start", async (_event, ctx) => {
+		const config = await refreshConfig(ctx);
+		if (!config.trusted) {
+			notifyStatus(
+				ctx,
+				`${PRODUCT_NAME}: automatic behavior disabled because project is not trusted. Config path: ${config.configPath}.`,
+			);
+			return;
+		}
+		if (!config.valid) {
+			notifyStatus(
+				ctx,
+				`${PRODUCT_NAME} disabled: invalid configuration in ${config.configPath}.`,
+			);
+			return;
+		}
+
+		const stale = await findStalePendingArtifacts(
+			config.artifactDirectoryPath,
+			ctx.sessionManager.getSessionId(),
+		);
+		if (stale[0] && !staleNotificationSent) {
+			staleNotificationSent = true;
+			const lockDetail = stale[0].lockPath ? ` lock: ${stale[0].lockPath}` : "";
+			ctx.ui.notify(
+				`${PRODUCT_NAME}: stale pending Continuity Brief found for this session; leaving it inert. ${stale[0].path}${lockDetail}`,
+				"warning",
+			);
+		}
+		notifyStatus(ctx, statusHeadlineForConfig(config));
+	});
+
+	pi.on("turn_end", async (_event, ctx) => {
+		const config = currentConfig ?? (await refreshConfig(ctx));
+		const decision = decideAutomaticTrigger(config, ctx.getContextUsage());
+		if (!decision.shouldRun) {
+			if (decision.reason === "usage-unavailable") {
+				ctx.ui.notify(
+					`${PRODUCT_NAME}: automatic trigger skipped because context usage is unavailable.`,
+					"warning",
+				);
+			}
+			if (decision.reason === "window-unavailable") {
+				ctx.ui.notify(
+					`${PRODUCT_NAME}: automatic trigger skipped because context usage or model window is unavailable.`,
+					"warning",
+				);
+			}
+			return;
+		}
+		if (
+			state.lastAutomaticFailureAt &&
+			Date.now() - state.lastAutomaticFailureAt < AUTOMATIC_FAILURE_COOLDOWN_MS
+		) {
+			return;
+		}
+		ctx.ui.notify(
+			`${PRODUCT_NAME}: context threshold reached; preparing Continuity Handoff.`,
+			"info",
+		);
+		await runContinuityHandoff(pi, ctx, config, state, {
+			reason: "threshold",
+			requestCompaction: true,
+		});
+	});
+
+	pi.registerCommand("continuity", {
+		description: "Pi Session Continuity: status, checkpoint, and settings",
+		getArgumentCompletions(prefix) {
+			return ["status", "checkpoint", "settings"]
+				.filter((item) => item.startsWith(prefix))
+				.map((value) => ({ value, label: value }));
+		},
+		handler: async (args, ctx) => {
+			const tokens = args.trim().split(/\s+/).filter(Boolean);
+			const subcommand = tokens[0] ?? "settings";
+			const config = await refreshConfig(ctx);
+
+			if (subcommand === "status") {
+				const stale = config.trusted
+					? await findStalePendingArtifacts(
+							config.artifactDirectoryPath,
+							ctx.sessionManager.getSessionId(),
+						)
+					: [];
+				const stalePath = stale[0]
+					? `${stale[0].path}${stale[0].lockPath ? ` (lock: ${stale[0].lockPath})` : ""}`
+					: undefined;
+				showCommandPanel(ctx, formatStatus(config, state, stalePath));
+				return;
+			}
+
+			if (subcommand === "settings") {
+				await openSettingsMenu(ctx, config);
+				return;
+			}
+
+			if (subcommand === "checkpoint") {
+				if (!config.trusted) {
+					showCommandOutput(
+						ctx,
+						`${PRODUCT_NAME}: checkpoint disabled because project is not trusted. Config path: ${config.configPath}.`,
+					);
+					return;
+				}
+				if (!config.valid) {
+					showCommandOutput(
+						ctx,
+						`${PRODUCT_NAME} disabled: invalid configuration in ${config.configPath}.`,
+					);
+					return;
+				}
+				if (!config.enabled) {
+					showCommandOutput(ctx, `${PRODUCT_NAME}: disabled by configuration.`);
+					return;
+				}
+				await runContinuityHandoff(pi, ctx, config, state, {
+					reason: "manual",
+					requestCompaction: false,
+				});
+				return;
+			}
+
+			showCommandOutput(
+				ctx,
+				`${PRODUCT_NAME}: unknown subcommand '${subcommand}'. Use /continuity status, /continuity checkpoint, or /continuity settings.`,
+			);
+		},
+	});
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "pi-session-continuity",
+  "version": "0.1.0",
+  "description": "Keep long-running Pi coding sessions recoverable with dull, durable handoffs.",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "session-continuity",
+    "continuity",
+    "checkpoint",
+    "long-running-sessions",
+    "coding-agents"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bernardofortes/pi-session-continuity.git"
+  },
+  "homepage": "https://github.com/bernardofortes/pi-session-continuity#readme",
+  "files": [
+    "extensions",
+    "src",
+    "docs",
+    "scripts",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/session-continuity/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "smoke:manual": "bash scripts/smoke/manual-checks.sh"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "@types/node": "^22.10.2",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/scripts/smoke/manual-checks.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cat <<'SMOKE'
+# Pi Session Continuity manual smoke checklist
+
+Use this checklist in a clean Pi process after installing from a pinned GitHub ref.
+Do not run external install/tag/release/publish steps without separate explicit approval.
+
+Environment record:
+- Pi version/commit:
+- Node version:
+- OS:
+- Install command:
+- Workspace:
+- Config path:
+- Artifact directory:
+
+For each assertion, record PASS or FAIL, the command(s) run, and concrete evidence paths/output.
+
+| ID | Assertion | Result | Evidence |
+| --- | --- | --- | --- |
+| manual-checkpoint-writes-artifact | `/continuity checkpoint` writes a valid Continuity Brief with required frontmatter and mandatory headings. | PASS/FAIL | |
+| resume-uses-disk-artifact | The queued resume prompt contains the exact saved artifact body read from disk. | PASS/FAIL | |
+| required-identity-present | Artifact includes `eventId`, `sessionId`, `sessionFile`, `createdAt`, and `updatedAt`. | PASS/FAIL | |
+| reload-stale-is-inert | Reload does not inject a stale pending artifact; `/continuity status` reports it as inert. | PASS/FAIL | |
+| duplicate-trigger-single-flight | Duplicate trigger while a handoff is active creates one artifact and one lock only. | PASS/FAIL | |
+| threshold-percent-model-change | Threshold math preserves 65% trigger intent across at least two model context windows. | PASS/FAIL | |
+| synthesis-failure-no-prompt | Forced synthesis failure queues no resume prompt and reports failure. | PASS/FAIL | |
+| write-failure-no-prompt | Forced artifact write failure queues no resume prompt and reports failure. | PASS/FAIL | |
+| cross-session-rejected | Artifact from another `sessionId` is not used automatically. | PASS/FAIL | |
+
+Suggested transcript structure:
+
+```text
+[ASSERTION-ID]
+command(s):
+observed:
+evidence path(s):
+result: PASS|FAIL
+```
+SMOKE