pi-session-continuity 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.1 — 2026-07-09
+
+- Change the default automatic threshold from 75% to 70% to reduce immediate contention with Pi native auto-compaction thresholds.
+- Warn on session load when native Pi auto-compaction is still enabled while Pi Session Continuity automatic behavior is enabled.
+- Document the recommended project-local Pi setting `compaction.enabled=false` for projects that want Pi Session Continuity to own automatic handoffs.
+
 ## 0.1.0 — 2026-07-09
 
 - Add Pi package manifest for `pi-session-continuity`.

package/README.md

@@ -49,7 +49,7 @@ pi install npm:pi-session-continuity
 Pinned GitHub install:
 
 ```bash
-pi install git:github.com/bernardofortes/pi-session-continuity@v0.1.0
+pi install git:github.com/bernardofortes/pi-session-continuity@v0.1.1
 ```
 
 For local development only:
@@ -92,7 +92,7 @@ Defaults:
 ```json
 {
   "enabled": true,
-  "triggerAtPercent": 75,
+  "triggerAtPercent": 70,
   "keepRecentPercent": 20,
   "synthesisModel": "inherit",
   "synthesisEffort": "medium",
@@ -104,6 +104,22 @@ Defaults:
 
 In interactive Pi sessions, `/continuity settings` can update this file for the public config fields. In non-interactive contexts, edit the JSON directly or run `/continuity settings` for textual inspection.
 
+### Native Pi auto-compaction
+
+Pi native auto-compaction is enabled by default. When Pi Session Continuity automatic behavior is enabled, the package warns on session load if native Pi auto-compaction is still enabled because both systems can compete near the same context threshold.
+
+Recommended project-local Pi setting:
+
+```json
+{
+  "compaction": {
+    "enabled": false
+  }
+}
+```
+
+Save that in `<workspace>/<CONFIG_DIR_NAME>/settings.json` (normally `.pi/settings.json`). Pi Session Continuity does not change this setting automatically during install or load.
+
 ## Artifact layout
 
 ```text
@@ -136,7 +152,7 @@ npm pack --dry-run
 
 `npm run smoke:manual` prints a checklist template for the required clean Pi smoke assertions. The checklist must be executed from a clean Pi install pinned to a GitHub ref before public announcement. Record the Pi version, Node version, OS, install command, smoke transcript, and resulting artifact path.
 
-External validation commands such as `pi install git:github.com/bernardofortes/pi-session-continuity@v0.1.0`, git tags, releases, npm publishing, or uploads require separate explicit human approval.
+External validation commands such as `pi install git:github.com/bernardofortes/pi-session-continuity@v0.1.1`, git tags, releases, npm publishing, or uploads require separate explicit human approval.
 
 ## Known limitations in v0.1.0
 
@@ -152,6 +168,7 @@ External validation commands such as `pi install git:github.com/bernardofortes/p
 - Synthesis failure: no resume prompt is queued; inspect the failed artifact path if one was written.
 - Write failure: no resume prompt is queued; fix filesystem permissions or artifact path.
 - Stale pending artifact: `/continuity status` reports it as inert; v0.1.0 will not silently inject it after reload.
+- Native Pi auto-compaction warning: add project-local Pi settings with `compaction.enabled=false` if Pi Session Continuity should own automatic threshold handoffs. Manual `/compact` remains available.
 - Untrusted project: trust the project before relying on project-local config or automatic behavior.
 
 ## Update / uninstall
@@ -161,7 +178,7 @@ pi update --extension npm:pi-session-continuity
 pi remove npm:pi-session-continuity
 
 # For pinned GitHub installs:
-pi update --extension git:github.com/bernardofortes/pi-session-continuity@v0.1.0
+pi update --extension git:github.com/bernardofortes/pi-session-continuity@v0.1.1
 pi remove git:github.com/bernardofortes/pi-session-continuity
 ```
 

package/docs/product-spec.md

@@ -79,7 +79,7 @@ Default threshold config:
 
 ```json
 {
-  "triggerAtPercent": 75,
+  "triggerAtPercent": 70,
   "keepRecentPercent": 20
 }
 ```
@@ -90,6 +90,8 @@ Default threshold config:
 
 v0.1.0 may request native Pi compaction as token hygiene only after the Continuity Brief has been written. It must not treat native compaction proof as the source of continuity.
 
+Because Pi native auto-compaction is enabled by default, Pi Session Continuity must warn on session load when native Pi auto-compaction is still enabled while Pi Session Continuity automatic behavior is enabled. The warning must explain that native auto-compaction can compete with Continuity Handoff triggers and recommend disabling native auto-compaction in project-local Pi settings (`<workspace>/<CONFIG_DIR_NAME>/settings.json`) by setting `compaction.enabled` to `false`. The extension must not silently mutate Pi settings during install or load.
+
 Continuity Brief synthesis must reserve enough output budget for reasoning-capable models so effort tokens do not starve the final Markdown body. If threshold-triggered synthesis fails, automatic behavior should not retry on every subsequent turn; it should cool down and leave manual `/continuity checkpoint` available.
 
 ### v0.2+: later enhancements
@@ -108,7 +110,7 @@ Configuration should stay small for v0.1.0:
 ```json
 {
   "enabled": true,
-  "triggerAtPercent": 75,
+  "triggerAtPercent": 70,
   "keepRecentPercent": 20,
   "synthesisModel": "inherit",
   "synthesisEffort": "medium",
@@ -190,7 +192,7 @@ synthesisModel: "resolved-provider/model"
 synthesisEffort: "medium"
 tokenCountAtTrigger: 0
 contextWindow: 0
-triggerAtPercent: 75
+triggerAtPercent: 70
 keepRecentPercent: 20
 branchLeafBefore: "entry-id-or-null"
 ---
@@ -327,12 +329,12 @@ The injected prompt must include the saved Continuity Brief content read from di
 
 All user-visible messages should be short, verifiable, and product-prefixed. In interactive Pi TUI mode, detailed `/continuity status` and `/continuity settings` output should be rendered as intentional user-facing output, not as a persistent oversized widget or long background/internal-looking chatter. Notifications should not escalate to warning severity unless the headline is actually disabled, invalid, failed, or otherwise unsafe.
 
-The output should use human-readable labels only for the normal status panel. Do not repeat the same values in a separate diagnostics block; concrete paths that matter to the user, such as the artifact directory or last artifact path, should appear once in the main panel. Persistent footer/status-line text should stay compact, for example `Session Continuation @ 75%`, so it does not crowd the terminal footer.
+The output should use human-readable labels only for the normal status panel. Do not repeat the same values in a separate diagnostics block; concrete paths that matter to the user, such as the artifact directory or last artifact path, should appear once in the main panel. Persistent footer/status-line text should stay compact, for example `Session Continuation @ 70%`, so it does not crowd the terminal footer.
 
 Idle/enabled:
 
 ```text
-Pi Session Continuity: enabled · trigger 75% · keep 20%.
+Pi Session Continuity: enabled · trigger 70% · keep 20%.
 ```
 
 Explicitly disabled:
@@ -401,6 +403,12 @@ Invalid config:
 Pi Session Continuity disabled: invalid configuration in <path>.
 ```
 
+Native Pi auto-compaction also enabled:
+
+```text
+Pi Session Continuity warning: native Pi auto-compaction is still enabled and can compete with Continuity Handoff triggers. Recommended project setting: compaction.enabled=false in <CONFIG_DIR_NAME>/settings.json.
+```
+
 ## 12. Slash commands
 
 v0.1.0 commands:
@@ -541,7 +549,7 @@ Minimum Pi smoke checks must be represented by a runnable script or documented m
 3. `required-identity-present`: artifact includes `eventId`, `sessionId`, `sessionFile`, `createdAt`, and `updatedAt`.
 4. `reload-stale-is-inert`: reload does not inject a stale pending artifact; status reports it as inert.
 5. `duplicate-trigger-single-flight`: duplicate trigger while a handoff is active creates one artifact and one lock only.
-6. `threshold-percent-model-change`: threshold math preserves 75% trigger intent across at least two model context windows.
+6. `threshold-percent-model-change`: threshold math preserves 70% trigger intent across at least two model context windows.
 7. `synthesis-failure-no-prompt`: forced synthesis failure queues no resume prompt and reports failure.
 8. `write-failure-no-prompt`: forced artifact write failure queues no resume prompt and reports failure.
 9. `cross-session-rejected`: artifact from another `sessionId` is not used automatically.
@@ -612,7 +620,7 @@ Dependency placement must follow Pi package rules:
 Implementation must bind the product behavior to explicit Pi APIs:
 
 - Register one command, `continuity`, and dispatch subcommands from its args so users invoke `/continuity status`, `/continuity checkpoint`, and `/continuity settings`.
-- Use `session_start` to initialize session-scoped state, inspect stale same-session pending artifacts, and set visible status when UI is available.
+- Use `session_start` to initialize session-scoped state, inspect stale same-session pending artifacts, warn when native Pi auto-compaction is still enabled while Pi Session Continuity automatic behavior is enabled, and set visible status when UI is available.
 - Use `turn_end` or another documented low-risk post-turn event for automatic threshold checks. The threshold calculation must use `ctx.getContextUsage()` and the active model context window; if usage or model metadata is unavailable, automatic behavior skips with a visible/debuggable reason.
 - Use a single-flight in-memory latch plus the on-disk lock sentinel before synthesis starts.
 - Use `ctx.sessionManager.getSessionId()`, `ctx.sessionManager.getSessionFile()`, `ctx.sessionManager.getLeafId()`, and `ctx.sessionManager.getBranch()` when constructing artifact identity and synthesis input.

package/docs/release-readiness/v0.1.0-release-2026-07-09.md

@@ -0,0 +1,157 @@
+# v0.1.0 Release Validation — 2026-07-09
+
+Scope: `pi-session-continuity` v0.1.0 public GitHub tag and npm publish readiness.
+
+## Release refs
+
+- GitHub repository: `https://github.com/bernardofortes/pi-session-continuity`
+- Branch commit before tag: `7c120ec Prepare v0.1.0 public release docs`
+- Tag: `v0.1.0`
+- Remote tag check: `git ls-remote --tags origin v0.1.0` returned `refs/tags/v0.1.0`.
+
+## Local package gates
+
+Command set:
+
+```bash
+npm test
+npm run typecheck
+npm pack --dry-run
+npm publish --dry-run
+```
+
+Observed results:
+
+- `npm test`: PASS — 8 test files, 54 tests.
+- `npm run typecheck`: PASS — `tsc --noEmit`.
+- `npm pack --dry-run`: PASS — package `pi-session-continuity@0.1.0`, 29 files.
+- `npm publish --dry-run`: PASS — package contents accepted by npm dry-run.
+
+## Clean GitHub tag install smoke
+
+Used temporary Pi agent/project/session directories so the smoke did not depend on the local/default Pi profile.
+
+### Install/list/load
+
+```bash
+agent_dir=$(mktemp -d /tmp/psc-clean-agent-XXXXXX)
+repo='git:github.com/bernardofortes/pi-session-continuity@v0.1.0'
+PI_CODING_AGENT_DIR="$agent_dir" pi install "$repo" --no-approve
+PI_CODING_AGENT_DIR="$agent_dir" pi list | grep -A2 -F 'pi-session-continuity'
+PI_CODING_AGENT_DIR="$agent_dir" pi --no-session -p 'Reply with exactly PSC_SMOKE_OK.'
+```
+
+Environment:
+
+- OS: `Linux trader 5.15.0-185-generic #195-Ubuntu SMP Fri Jun 19 17:11:50 UTC 2026 x86_64 GNU/Linux`
+- Node: `v22.22.2`
+- Pi: `0.80.3`
+- Temporary agent dir: `/tmp/psc-clean-agent-IPTbLH`
+
+Observed output:
+
+```text
+Installed git:github.com/bernardofortes/pi-session-continuity@v0.1.0
+  git:github.com/bernardofortes/pi-session-continuity@v0.1.0
+    /tmp/psc-clean-agent-IPTbLH/git/github.com/bernardofortes/pi-session-continuity
+PSC_SMOKE_OK
+```
+
+Result: PASS for clean install/load from GitHub tag.
+
+### Command/status/config/remove assertions
+
+Temporary paths:
+
+- Project root: `/tmp/psc-smoke-root-odHazM`
+- Agent dir: `/tmp/psc-smoke-agent-Iq2Iyu`
+
+Observed `/continuity status` output included:
+
+```text
+Pi Session Continuity: enabled · trigger 75% · keep 20%.
+- Mode: Enabled
+- Artifacts: /tmp/psc-smoke-root-odHazM/.pi/session-continuity
+```
+
+Invalid config smoke used `.pi/session-continuity.json` with `keepRecentPercent >= triggerAtPercent` and observed:
+
+```text
+Pi Session Continuity disabled: invalid configuration in /tmp/psc-smoke-root-odHazM/.pi/session-continuity.json.
+- Mode: Disabled
+- Disabled reason: invalid configuration in /tmp/psc-smoke-root-odHazM/.pi/session-continuity.json
+```
+
+Remove smoke observed:
+
+```text
+Removed git:github.com/bernardofortes/pi-session-continuity@v0.1.0
+remove_passed
+```
+
+### Manual checkpoint artifact smoke
+
+`/continuity checkpoint` must run with a persisted Pi session. A `--no-session` smoke is invalid for this assertion because Continuity Brief identity requires a concrete `sessionFile`.
+
+Temporary paths:
+
+- Project root: `/tmp/psc-smoke2-root-04mfOn`
+- Agent dir: `/tmp/psc-smoke2-agent-b9LmdC`
+- Session dir: `/tmp/psc-smoke2-sessions-Cys5kD`
+
+Command:
+
+```bash
+PI_CODING_AGENT_DIR="$agent_dir" pi --session-dir "$session_dir" --approve -p '/continuity checkpoint'
+```
+
+Observed artifact:
+
+```text
+/tmp/psc-smoke2-root-04mfOn/.pi/session-continuity/019f481c-8aaa-7b63-8eda-edeb92428a22/archive/2026-07-09T18-22-26-111Z-d3d30593-cd25-46ad-b10d-c7dff0e0736c.md
+```
+
+Observed artifact fields:
+
+```text
+status: "archived"
+sessionFile: "/tmp/psc-smoke2-sessions-Cys5kD/2026-07-09T18-20-57-898Z_019f481c-8aaa-7b63-8eda-edeb92428a22.jsonl"
+# Continuity Brief
+```
+
+Result: PASS for checkpoint artifact creation and archive from GitHub tag in a persisted session.
+
+## npm publish status
+
+`npm publish --dry-run` passed before release. The first manual publish attempts were blocked until npm authentication and a token with explicit 2FA-bypass publish permission were available.
+
+Final publish command was run from the exact GitHub release tag:
+
+```bash
+git checkout v0.1.0
+NPM_CONFIG_USERCONFIG=/tmp/npmrc-publish npm publish --access public
+git checkout main
+rm -f /tmp/npmrc-publish
+```
+
+Observed publish output:
+
+```text
++ pi-session-continuity@0.1.0
+```
+
+Registry verification:
+
+```bash
+npm view pi-session-continuity@0.1.0 name version description
+```
+
+Observed output:
+
+```text
+name = 'pi-session-continuity'
+version = '0.1.0'
+description = 'Keep long-running Pi coding sessions recoverable with dull, durable handoffs.'
+```
+
+Result: PASS — npm package `pi-session-continuity@0.1.0` is published and visible in the npm registry.

package/extensions/session-continuity/index.ts

@@ -5,6 +5,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import {
+	detectNativeAutoCompaction,
 	loadConfig,
 	publicConfigFromResolved,
 	validateConfigDraftForPath,
@@ -73,6 +74,22 @@ export default function sessionContinuityExtension(pi: ExtensionAPI) {
 		return currentConfig;
 	}
 
+	function warnIfNativeAutoCompactionEnabled(
+		ctx: ExtensionContext,
+		config: ResolvedContinuityConfig,
+	): void {
+		if (!config.enabled || !config.valid || !config.trusted) return;
+		const nativeCompaction = detectNativeAutoCompaction(
+			ctx.cwd,
+			config.trusted,
+		);
+		if (!nativeCompaction.enabled) return;
+		ctx.ui.notify(
+			`${PRODUCT_NAME} warning: native Pi auto-compaction is still enabled and can compete with Continuity Handoff triggers. Recommended project setting: compaction.enabled=false in ${CONFIG_DIR_NAME}/settings.json.`,
+			"warning",
+		);
+	}
+
 	async function saveConfigDraft(
 		ctx: ExtensionContext,
 		draft: ContinuityConfig,
@@ -214,6 +231,7 @@ export default function sessionContinuityExtension(pi: ExtensionAPI) {
 				"warning",
 			);
 		}
+		warnIfNativeAutoCompactionEnabled(ctx, config);
 		notifyStatus(ctx, statusHeadlineForConfig(config));
 	});
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-session-continuity",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Keep long-running Pi coding sessions recoverable with dull, durable handoffs.",
   "license": "MIT",
   "type": "module",

package/src/config.ts

@@ -1,7 +1,11 @@
 import { existsSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+	getAgentDir,
+	SettingsManager,
+	type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
 import {
 	DEFAULT_ARTIFACT_DIRECTORY,
 	DEFAULT_KEEP_RECENT_PERCENT,
@@ -36,6 +40,13 @@ export interface ResolvedContinuityConfig extends ContinuityConfig {
 	errors: string[];
 }
 
+export interface NativeCompactionStatus {
+	enabled: boolean;
+	reserveTokens: number;
+	keepRecentTokens: number;
+	errors: string[];
+}
+
 export const DEFAULT_CONFIG: ContinuityConfig = {
 	enabled: true,
 	triggerAtPercent: DEFAULT_TRIGGER_AT_PERCENT,
@@ -336,6 +347,26 @@ export async function loadConfig(
 	return loadConfigFromDisk(ctx.cwd, configDirName, ctx.isProjectTrusted());
 }
 
+export function detectNativeAutoCompaction(
+	cwd: string,
+	projectTrusted: boolean,
+	agentDir = getAgentDir(),
+): NativeCompactionStatus {
+	const settingsManager = SettingsManager.create(cwd, agentDir, {
+		projectTrusted,
+	});
+	const settings = settingsManager.getCompactionSettings();
+	const errors = settingsManager
+		.drainErrors()
+		.map(({ scope, error }) => `${scope}: ${error.message}`);
+	return {
+		enabled: settings.enabled,
+		reserveTokens: settings.reserveTokens,
+		keepRecentTokens: settings.keepRecentTokens,
+		errors,
+	};
+}
+
 export function deriveKeepRecentTokens(
 	contextWindow: number,
 	keepRecentPercent: number,

package/src/constants.ts

@@ -56,7 +56,7 @@ export const ALLOWED_STATUSES = [
 	"failed",
 ] as const;
 
-export const DEFAULT_TRIGGER_AT_PERCENT = 75;
+export const DEFAULT_TRIGGER_AT_PERCENT = 70;
 export const DEFAULT_KEEP_RECENT_PERCENT = 20;
 export const DEFAULT_ARTIFACT_DIRECTORY = "session-continuity";
 export const DEFAULT_SYNTHESIS_MODEL = "inherit";