pi-ui-extend 1.0.47 → 2.0.0

package/README.md

@@ -123,8 +123,26 @@ Later files override earlier ones. Disable modules with `disabledModules`, `PI_T
 
 ## Install
 
+### Download a ready-to-run release
+
+[GitHub Releases](https://github.com/dnaroid/pix/releases) contains published
+portable TUI archives and Pix Desktop installers when a release has completed
+the native build/verification pipeline. Choose **TUI** or **Desktop** and your
+OS/CPU: Windows x64, macOS Apple Silicon, macOS Intel, or Linux x64.
+
+These packages contain Node.js and the Pix/ACP runtime; no separate Node/npm
+installation is required to launch them. For TUI, extract the whole archive and
+run `pix` (macOS/Linux) or `pix.cmd` (Windows) from your terminal. For Desktop,
+use the `.dmg`, Windows installer, `.AppImage`, or `.deb` for your system.
+Git, tools needed by your projects, provider credentials and optional voice/
+clipboard helpers are separate. Unsigned/ad-hoc builds may show OS warnings;
+check the release notes before installing. See the [release guide](docs/release.md)
+for building, signing, checksums and updates. npm installation remains available below.
+
 ### Requirements
 
+The Node/npm requirements below apply to the npm/source installation channel.
+
 - **Node.js `>=22.19.0 <25`**
 - macOS, Linux, or Windows terminal with 256-color support
 - npm or another way to run the published npm package

package/dist/app/cli/release-update.d.ts

@@ -0,0 +1,4 @@
+export declare const PIX_RELEASES_URL = "https://github.com/dnaroid/pix/releases/latest";
+export declare function isReleaseInstall(packageRoot: string): boolean;
+export declare function fetchLatestReleaseVersion(_packageName: string, currentVersion: string, timeoutMs: number): Promise<string | undefined>;
+export declare function releaseUpdateHint(): string;

package/dist/app/cli/release-update.js

@@ -0,0 +1,25 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+export const PIX_RELEASES_URL = "https://github.com/dnaroid/pix/releases/latest";
+export function isReleaseInstall(packageRoot) {
+    // Presence alone fails closed: a damaged manifest must never enable global npm mutation.
+    return existsSync(join(packageRoot, ".pix-portable.json"));
+}
+export async function fetchLatestReleaseVersion(_packageName, currentVersion, timeoutMs) {
+    const response = await fetch("https://api.github.com/repos/dnaroid/pix/releases/latest", {
+        headers: { accept: "application/vnd.github+json", "User-Agent": `pix/${currentVersion}` },
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (response.status === 404)
+        return undefined;
+    if (!response.ok)
+        throw new Error(`GitHub Releases returned ${response.status}`);
+    const data = await response.json();
+    if (data.draft === true || data.prerelease === true)
+        return undefined;
+    return typeof data.tag_name === "string" && /^v\d+\.\d+\.\d+$/u.test(data.tag_name)
+        ? data.tag_name.slice(1) : undefined;
+}
+export function releaseUpdateHint() {
+    return `Download the complete package for your OS/CPU from ${PIX_RELEASES_URL}. Close Pix before replacing it. Settings and sessions remain in your user profile. This installation does not update global npm/Pi packages.`;
+}

package/dist/app/cli/update.d.ts

@@ -1,3 +1,4 @@
+export { isReleaseInstall } from "./release-update.js";
 type PixUpdateTestDeps = {
     checkPixUpdate: typeof checkPixUpdate;
     runCommand: typeof runCommand;
@@ -59,4 +60,3 @@ export declare function getPixSelfUpdateCommand(packageName: string, latestVersi
 export declare function getGlobalPiUpdateCommand(targetVersion: string, pixPackageRoot?: string): PixSelfUpdateCommand | undefined;
 export declare function runPixUpdateCli(argv?: readonly string[]): Promise<number>;
 declare function runCommand(command: PixSelfUpdateCommand): Promise<void>;
-export {};

package/dist/app/cli/update.js

@@ -3,6 +3,8 @@ import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { getAgentDir, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { fetchLatestReleaseVersion, isReleaseInstall, releaseUpdateHint } from "./release-update.js";
+export { isReleaseInstall } from "./release-update.js";
 const DEFAULT_UPDATE_TIMEOUT_MS = 10_000;
 const NPM_REGISTRY_URL = "https://registry.npmjs.org";
 const PI_PACKAGE_NAME = "@earendil-works/pi-coding-agent";
@@ -25,6 +27,7 @@ Options:
   -h, --help Show this help
 
 Inside the TUI, /update performs the same non-mutating check.
+Portable/Desktop GitHub Releases are replaced as a complete package; --force never changes global packages for those installations.
 The bundled skills payload under skills/ is copied into ~/.agents/skills on startup.
 The pi-tools-suite payload under external/pi-tools-suite is updated with Pix and linked into ~/.pi/agent/extensions on startup.`;
 }
@@ -54,7 +57,9 @@ export function getPixPackageVersion(packageRoot) {
 }
 export async function checkPixUpdate(options = {}) {
     const packageInfo = readPixPackageInfo(options.packageRoot);
-    return await checkPackageUpdate(packageInfo, options);
+    return await checkPackageUpdate(packageInfo, isReleaseInstall(packageInfo.packageRoot)
+        ? { ...options, fetchLatestVersion: options.fetchLatestVersion ?? fetchLatestReleaseVersion }
+        : options);
 }
 export async function checkPiUpdate(options = {}) {
     const packageRoot = options.packageRoot ?? findPiPackageRoot(options.pixPackageRoot);
@@ -133,7 +138,7 @@ async function checkPackageUpdate(packageInfo, options) {
     try {
         const latestVersion = await (options.fetchLatestVersion ?? fetchLatestNpmVersion)(packageInfo.name, packageInfo.version, options.timeoutMs ?? DEFAULT_UPDATE_TIMEOUT_MS);
         if (!latestVersion) {
-            return { ...base, status: "unknown", reason: "npm registry did not return a latest version" };
+            return { ...base, status: "unknown", reason: "the distribution channel did not return a latest version" };
         }
         return {
             ...base,
@@ -150,6 +155,11 @@ async function checkPackageUpdate(packageInfo, options) {
     }
 }
 export function formatPixUpdateCheck(result) {
+    if (isReleaseInstall(result.packageRoot)) {
+        return ["Pix update (GitHub Release)", `current: ${result.packageName} v${result.currentVersion}`,
+            ...(result.latestVersion ? [`latest: ${result.latestVersion}`] : []),
+            `status: ${result.status}${result.reason ? ` (${result.reason})` : ""}`, releaseUpdateHint()].join("\n");
+    }
     const lines = [
         "Pix update",
         `current: ${result.packageName} v${result.currentVersion}`,
@@ -204,6 +214,8 @@ export function formatGlobalPiCheck(result) {
     return lines.join("\n");
 }
 export function formatPixStartupUpdateDialog(result) {
+    if (isReleaseInstall(result.packageRoot))
+        return formatPixUpdateCheck(result);
     const lines = [
         "A new Pix version is available.",
         `current: ${result.packageName} v${result.currentVersion}`,
@@ -231,6 +243,8 @@ export function getGlobalPiUpdateCommand(targetVersion, pixPackageRoot = readPix
     return getGlobalPackageUpdateCommand(PI_PACKAGE_NAME, targetVersion, pixPackageRoot);
 }
 function getGlobalPackageUpdateCommand(packageName, version, packageRoot) {
+    if (isReleaseInstall(packageRoot))
+        return undefined;
     if (!packageRootLooksPackageManaged(packageRoot))
         return undefined;
     const installSpec = version ? `${packageName}@${version}` : packageName;
@@ -266,6 +280,10 @@ export async function runPixUpdateCli(argv = process.argv.slice(2)) {
     }
     const check = await pixUpdateDeps.checkPixUpdate();
     console.log(formatPixUpdateCheck(check));
+    if (isReleaseInstall(check.packageRoot)) {
+        // Portable/Desktop installs are replaced as a unit. Even --force must not modify global packages.
+        return options.checkOnly && check.status !== "unknown" && check.status !== "unavailable" ? 0 : 1;
+    }
     let globalPiCheck = checkGlobalPiInstall(check.packageRoot);
     console.log(`\n${formatGlobalPiCheck(globalPiCheck)}`);
     if (options.checkOnly)

package/dist/app/commands/command-session-actions.js

@@ -9,7 +9,7 @@ import { createId } from "../id.js";
 import { runProcess } from "../process.js";
 import { copyTextToClipboard } from "../screen/clipboard.js";
 import { formatAccountUsageReport, queryAccountUsageReport } from "../model/model-usage-status.js";
-import { checkGlobalPiInstall, checkPixUpdate, formatGlobalPiCheck, formatPixUpdateCheck, parsePixUpdateArgs, pixUpdateUsage, } from "../cli/update.js";
+import { checkGlobalPiInstall, isReleaseInstall, checkPixUpdate, formatGlobalPiCheck, formatPixUpdateCheck, parsePixUpdateArgs, pixUpdateUsage, } from "../cli/update.js";
 import { createStartupInfoMessage } from "../cli/startup-info.js";
 import { createReloadContextInventory, formatReloadContextInventory } from "./reload-context-inventory.js";
 import { getCompleteSessionStats } from "../session/session-stats.js";
@@ -259,6 +259,17 @@ export class SessionCommandActions {
         const result = await checkPixUpdate();
         if (!isCommandScopeActive(this.host, scope))
             return;
+        if (isReleaseInstall(result.packageRoot)) {
+            this.host.addEntry({ id: createId("system"), kind: "system", text: formatPixUpdateCheck(result) });
+            this.host.setSessionStatus(runtime.session);
+            if (result.status === "newer")
+                this.host.toast.info("A new Pix release is available");
+            else if (result.status === "current")
+                this.host.toast.success("Pix is up to date");
+            else
+                this.host.toast.warning("Pix update check incomplete");
+            return;
+        }
         const globalPiResult = checkGlobalPiInstall(result.packageRoot);
         const forceHint = options.force ? "\n\n/update is check-only. To force a reinstall, run `pix update --force` in your shell and restart Pix." : "";
         this.host.addEntry({

package/docs/desktop-mvp.md

@@ -39,7 +39,9 @@ current product non-goals.
   markdown/diff rendering, or authentication management.
 - Bundling Node or a platform-specific standalone `pix-acp` executable in this
   first slice. Development uses Node plus pix-acp's pinned pi npm dependency;
-  distributable sidecar packaging is a follow-up milestone.
+  distributable packaging is now governed by
+  [`release-distribution.md`](../specs/release-distribution.md), using bundled Node,
+  Pix and ACP resources for release builds while preserving source-mode development.
 - Reimplementing the pi runtime in Rust or the webview.
 
 ## Behavior

package/docs/release.md

@@ -2,6 +2,125 @@
 
 Use this checklist before publishing `pi-ui-extend` so installs work on macOS, Linux, and Windows and the `pi-tools-suite` extension payload is included.
 
+## Downloadable TUI and Desktop releases
+
+One stable `vX.Y.Z` tag produces npm publication and a **draft GitHub Release**
+containing portable TUI and Desktop installers. The contract is in
+[`specs/release-distribution.md`](../specs/release-distribution.md).
+
+| Target | TUI | Desktop |
+| --- | --- | --- |
+| Windows x64 | `.zip` with `pix.cmd` | NSIS `-setup.exe` and `.msi` |
+| macOS Apple Silicon | `.tar.gz` with `pix` | `.dmg` |
+| macOS Intel | `.tar.gz` with `pix` | `.dmg` |
+| Linux x64 | `.tar.gz` with `pix` | `.AppImage` and `.deb` |
+
+Each download contains its own pinned Node.js and dependencies. Users do not need
+Node/npm to launch Pix. Keep the complete TUI directory together and run its
+launcher from a terminal; add that directory to PATH or symlink `pix` on Unix.
+Desktop includes ACP and does not require an npm-installed Pix. Git, shells,
+project runtimes, optional helpers and provider credentials remain separate.
+macOS release packages require 13.5 or newer, matching the bundled Node 24 binary.
+Linux bundles are built on Ubuntu 22.04; do not advertise support for older
+glibc/WebKit environments without running additional compatibility tests.
+
+### Local build
+
+Select a supported Node on PATH (`.node-version` is the CI/build pin), install
+Rust and the platform's [Tauri build prerequisites](https://v2.tauri.app/start/prerequisites/), then run:
+
+```bash
+npm ci --ignore-scripts
+npm ci --prefix acp --ignore-scripts
+npm ci --prefix desktop --ignore-scripts
+npm run release:build
+# Or specify this machine's target:
+npm run release:build -- macos-arm64
+# Only the portable TUI archive:
+npm run release:build -- macos-arm64 --tui-only
+```
+
+Use the corresponding native machine/runner for each target. Cross-host packaging
+is rejected because native modules must match both CPU and OS. Output is under
+`.artifacts/releases/<target>/assets/`. Builds test the real unpacked package and
+the relocated/installed GUI, including an app copied from a mounted read-only DMG.
+The release builder sets `CI=true` even locally so DMG creation does not need Finder
+automation permissions. Development commands (`dev:desktop`, `watch:all`,
+`build:desktop`) remain separate and do not make distributable bundles.
+
+To iterate on the Desktop wrapper after preparing its runtime, use
+`npm run release:build:desktop -- <target>`; rebuild the full release after any
+Pix/ACP/dependency change. `release:smoke` and `release:smoke:desktop` rerun checks
+against already built artifacts. These harnesses create temporary user profiles;
+do not invoke `verify.mjs` or the native diagnostic directly with your real HOME.
+
+### Package contents and size checks
+
+The TUI archive includes Pix and its Node runtime, **not ACP**. The Desktop
+runtime additionally includes ACP. Preparation cleans generated `dist` directories
+before compilation so old emitted files or Vosk models cannot leak into a release;
+it does not delete source files or the user's `models/` directory.
+
+The packager removes foreign esbuild/PTY/clipboard variants and debug source maps,
+then shares only ACP packages proven equivalent to the parent installation by
+file content and dependency graph. Different dependency versions/contexts remain
+isolated. Runtime TypeScript, declarations, native binaries for this target,
+WASM and license files are preserved.
+
+Inspect `.artifacts/releases/<target>/pix/SIZE.json` for TUI and
+`.artifacts/releases/<target>/desktop/pix/SIZE.json` for the Desktop backend.
+Adjacent `OPTIMIZATIONS.json` reports explain the pruning and sharing decisions.
+Sizes count regular-file bytes, not filesystem block allocation. The native
+Desktop host and signing metadata are additional to its backend payload.
+
+Builds fail above these budgets: TUI 384 MiB unpacked / 160 MiB download;
+Desktop backend 512 MiB unpacked / 240 MiB installer. The limits live in
+`scripts/release/size-budget.mjs`; review dependency growth before changing them.
+CI also uploads `size-<target>` report artifacts separately from release assets.
+Smoke tests execute native esbuild, PTY and extension loading after unpacking,
+and additionally exercise ACP and the native application for Desktop.
+
+### CI and publishing
+
+The `Publish` workflow uses native Ubuntu 22.04 x64, macOS 15 ARM64, macOS 15 Intel
+and Windows 2022 x64 runners. `Actions → Publish → Run workflow` builds and tests
+all packages without publishing anything. The ten installers/archives are
+available as four Actions artifacts. On a version-tag push, the final job waits
+for the full native matrix and npm publication, validates the complete set,
+adds `SHA256SUMS`, and uploads everything to a draft release. Only then review
+the release notes/signing status and click **Publish release** in GitHub.
+
+The draft is intentional: an unsigned or incomplete first build must not silently
+become the public latest version. Reruns can replace draft assets, but the release
+script refuses to overwrite published assets. Publish a new version for fixes.
+Checksums detect damaged downloads; they do not replace trusted code signatures.
+
+### Optional signing secrets
+
+Without signing secrets, macOS builds use ad-hoc signatures and Windows installers
+are unsigned. Such builds are suitable for testing but may trigger OS warnings.
+Trusted signing/notarization cannot be configured without the maintainer's keys.
+
+For macOS, configure repository Actions secrets `APPLE_CERTIFICATE` (base64 P12),
+`APPLE_CERTIFICATE_PASSWORD`, and `APPLE_SIGNING_IDENTITY` (Developer ID Application).
+For Tauri notarization also set `APPLE_ID`, `APPLE_PASSWORD` (app-specific password)
+and `APPLE_TEAM_ID`. The workflow imports the certificate into a temporary keychain,
+signs nested runtime binaries before the app, and cleans the keychain afterwards.
+The Node executable has separate JIT/native-addon entitlements. An ad-hoc signature
+is not Developer ID signing. The TUI tarball is not a notarized installer; test its
+download/quarantine UX separately before promising warning-free installation.
+
+For Windows, configure `WINDOWS_CERTIFICATE` (base64 PFX) and
+`WINDOWS_CERTIFICATE_PASSWORD`. The workflow imports it into the runner's user
+certificate store, passes its thumbprint to Tauri and removes it afterwards.
+Hardware-backed/cloud signing requires adapting that signing step to the selected
+provider; the PFX path does not claim to cover every certificate provider.
+
+Keep keys out of the repository and out of release files. Official references:
+[macOS signing](https://v2.tauri.app/distribute/sign/macos/),
+[Windows signing](https://v2.tauri.app/distribute/sign/windows/), and
+[Tauri resource bundling](https://v2.tauri.app/develop/resources/).
+
 ## Local release check
 
 ```bash
@@ -20,7 +139,7 @@ The normative CI invariants are recorded in [`specs/ci-release.md`](../specs/ci-
 The GitHub Actions release workflow has two different responsibilities and they should stay separate:
 
 - `build-and-test` runs on Ubuntu, macOS, and Windows. This is the cross-platform correctness gate: type checks, unit/integration tests, platform-specific host checks, and the Pix build belong here.
-- Package smoke tests validate the artifact a user actually installs. Run the full payload/tarball smoke test on Ubuntu, and a smaller pack/install/CLI sanity check on Windows. A separate macOS package smoke job is unnecessary unless packaging gains macOS-specific behavior.
+- npm package smoke tests run the full payload/tarball test on Ubuntu and a smaller pack/install/CLI check on Windows. Portable/Tauri release artifacts additionally run smoke tests on all four native targets.
 
 Keep CI tests deterministic across runner speed and operating systems:
 
@@ -58,7 +177,12 @@ npm run publish-npm -- 0.2.0      # exact version
 
 The command requires a clean working tree on `master`, pulls latest from `origin/master`, runs `release:check`, runs `npm version`, runs the tarball smoke test, then pushes the branch and `v*` tag. The tag workflow verifies that `package.json` matches the tag before `npm publish --access public`.
 
-Only the root `package.json` version is bumped for Pix releases. Do not bump `external/pi-tools-suite/package.json` unless publishing the suite as a separate package.
+The root `package.json` version is authoritative. Its npm `version` hook synchronizes
+ACP, Desktop, Tauri, Cargo and lockfile versions and stages them before npm creates
+the release commit/tag. `npm run release:version:check` detects drift; use
+`npm run release:version` to repair manifests after a manual root-version edit.
+Only stable `X.Y.Z` versions within MSI bounds are supported by this release path.
+Do not bump `external/pi-tools-suite/package.json` unless publishing the suite separately.
 
 ## Tarball smoke test
 
@@ -96,6 +220,14 @@ Some modules have optional runtime dependencies or host services:
 
 ## Update UX
 
+Portable TUI and packaged Desktop detect their `.pix-portable.json` marker and
+check stable GitHub Releases instead of npm. `/update`, `pix update --check`, and
+the Desktop report point to a complete replacement download. `pix update` or
+`--force` cannot modify global npm/Pi packages for these installs. Close Pix before
+replacing the complete package; sessions/settings remain in the user profile.
+Automatic binary replacement/Tauri Updater is not enabled in this first release
+pipeline. The following package-manager behavior applies only to npm installs.
+
 - `/update` inside Pix performs a non-mutating Pix update check and reports whether the global Pi package in the same package-manager prefix matches Pix's pinned Pi SDK version.
 - `pix update --check` performs the same compatibility check without a TTY and never mutates either package.
 - `pix update` first updates a package-manager installation of Pix when needed, then installs the global `@earendil-works/pi-coding-agent` at the exact version pinned by the resulting Pix package. This keeps the shared `pi-tools-suite` host ABI aligned. The next Pix startup refreshes the user extension link.

package/external/pi-tools-suite/src/dcp/context-map-telemetry.ts

@@ -0,0 +1,96 @@
+import { detectToolGroupSpans, findConversationIndexEntry } from "./conversation-index.js"
+import { estimateMessageTokens, stripStaleDcpMetadataFromMessage } from "./pruner-metadata.js"
+import type { CompressionCandidate } from "./pruner-types.js"
+import type { DcpState } from "./state.js"
+
+export interface DcpContextMapTelemetry {
+  readonly revision: number
+  readonly sessionEpoch: number
+  readonly generatedAt: number
+  readonly tokenEstimates: {
+    readonly candidate: number
+    readonly protected: number
+    readonly compressed: number
+    readonly retained: number
+  }
+}
+
+type ContextMapKind = keyof DcpContextMapTelemetry["tokenEstimates"]
+
+function isSafeNonnegativeInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0
+}
+
+/** Capture immediately after applyPruning, before any await or carrier changes. */
+export function captureDcpContextTokenEstimates(
+  entries: DcpState["conversationIndexSnapshot"],
+  preparedMessages: readonly any[],
+  metadata: DcpState["messageMetaSnapshot"],
+): number[] | undefined {
+  if (entries.length !== preparedMessages.length) return undefined
+  const tokens: number[] = []
+  for (let index = 0; index < entries.length; index++) {
+    const entry = entries[index]!
+    const message = preparedMessages[index]
+    if (entry.index !== index || entry.role !== (message?.role ?? "")) return undefined
+    const cached = entry.visibleId ? metadata.get(entry.visibleId) : undefined
+    // Reuse the body estimate made by this exact pruning pass. Non-addressable
+    // messages have no cache; only these need the ordinary content estimator.
+    const estimate = cached?.contentHash === entry.contentHash && cached.tokenEstimate !== undefined
+      ? cached.tokenEstimate
+      : estimateMessageTokens(stripStaleDcpMetadataFromMessage(message))
+    if (!isSafeNonnegativeInteger(estimate)) return undefined
+    tokens.push(estimate)
+  }
+  return tokens
+}
+
+/** Classifies the already-prepared provider projection without reading history or planning. */
+export function projectDcpContextMapTelemetry(
+  entries: DcpState["conversationIndexSnapshot"],
+  candidate: CompressionCandidate | null,
+  preparedTokenEstimates: readonly number[] | undefined,
+  revision: number,
+  sessionEpoch: number,
+  generatedAt = Date.now(),
+): DcpContextMapTelemetry | undefined {
+  if (
+    entries.length === 0 || entries.length !== preparedTokenEstimates?.length ||
+    !isSafeNonnegativeInteger(revision) || revision === 0 || !isSafeNonnegativeInteger(sessionEpoch) ||
+    !isSafeNonnegativeInteger(generatedAt) || generatedAt === 0 || !Number.isFinite(new Date(generatedAt).getTime())
+  ) return undefined
+
+  const protectedIndexes = new Set<number>()
+  for (const group of detectToolGroupSpans(entries)) {
+    if (!group.complete) {
+      for (let index = group.startIndex; index <= group.endIndex; index++) protectedIndexes.add(index)
+    }
+  }
+  const candidateIndexes = new Set<number>()
+  if (candidate) {
+    const start = findConversationIndexEntry(entries, candidate.startId)?.index
+    const end = findConversationIndexEntry(entries, candidate.endId)?.index
+    if (start !== undefined && end !== undefined) {
+      for (let index = Math.min(start, end); index <= Math.max(start, end); index++) candidateIndexes.add(index)
+    }
+  }
+
+  const tokenEstimates: Record<ContextMapKind, number> = {
+    candidate: 0, protected: 0, compressed: 0, retained: 0,
+  }
+  for (let index = 0; index < entries.length; index++) {
+    const entry = entries[index]!
+    const tokens = preparedTokenEstimates[index]
+    if (!isSafeNonnegativeInteger(tokens)) return undefined
+    const kind: ContextMapKind = entry.origin === "dcp-control" ? "retained"
+      : protectedIndexes.has(index) ? "protected"
+      : candidateIndexes.has(index) ? "candidate"
+      : entry.origin === "block" && entry.blockId !== undefined ? "compressed"
+      : "retained"
+    if (!Number.isSafeInteger(tokenEstimates[kind] + tokens)) return undefined
+    tokenEstimates[kind] += tokens
+  }
+  const total = tokenEstimates.candidate + tokenEstimates.protected + tokenEstimates.compressed + tokenEstimates.retained
+  if (!Number.isSafeInteger(total) || total <= 0) return undefined
+  return { revision, sessionEpoch, generatedAt, tokenEstimates }
+}

package/external/pi-tools-suite/src/dcp/index.ts

@@ -78,6 +78,7 @@ import { inferDcpBlockedReason, planDcpBudget, type DcpBlockedReason } from "./p
 import { createBudgetedAutoCompressionBlock } from "./auto-compress-budget.js"
 import { compressionPlanningTokens, outstandingCompressionTokens, resetCompressionProgress, routineRecoveryTokens, trackCompressionProgress } from "./compression-progress.js"
 import { captureDcpTransactionGuard, cloneDcpTransactionState, runDcpStateTransaction, invalidateDcpStateOwner } from "./state-transaction.js"
+import { captureDcpContextTokenEstimates, projectDcpContextMapTelemetry } from "./context-map-telemetry.js"
 
 const PIX_DCP_RUNTIME_STATS_SYMBOL = Symbol.for("pix.dcp.runtime-stats")
 
@@ -163,7 +164,15 @@ export default async function dcpModule(pi: ExtensionAPI, dependencies: { config
 	const state = dependencies.state ?? createState()
 	// Pix ACP runs one pi process per session. Expose only this tiny live metric
 	// to the patched RPC session-stats surface; DCP state remains extension-owned.
-	runtimeGlobals[PIX_DCP_RUNTIME_STATS_SYMBOL] = () => ({ tokensSaved: state.tokensSaved })
+	let contextMapRevision = 0
+	let contextMapPass = 0
+	let contextMap: ReturnType<typeof projectDcpContextMapTelemetry> | undefined
+	// This process-local bridge is read-only. Its map is produced only by the
+	// existing context pass, never by Desktop inspection or a streaming delta.
+	runtimeGlobals[PIX_DCP_RUNTIME_STATS_SYMBOL] = () => ({
+		tokensSaved: state.tokensSaved,
+		contextMap: contextMap?.sessionEpoch === state.sessionEpoch ? contextMap : undefined,
+	})
 	let journalMirror: DcpJournalMirror | undefined
 	let journalSupported = false
 	let journalBlockedReason: string | undefined
@@ -283,6 +292,8 @@ export default async function dcpModule(pi: ExtensionAPI, dependencies: { config
 		try { ctx.ui.notify(message, "warning") } catch { /* Headless/notification failure is not a persistence failure. */ }
 	}
 	const invalidateOwner = () => {
+		contextMap = undefined
+		contextMapPass++
 			invalidateDcpStateOwner(state)
 			routinePressureTracker.reset()
 			// Successful exposure belongs to the old provider/branch too, not only
@@ -353,6 +364,8 @@ export default async function dcpModule(pi: ExtensionAPI, dependencies: { config
 
 	// ── 5. session_start: restore state from session entries ──────────────────
 	pi.on("session_start", async (event, ctx) => {
+		contextMap = undefined
+		contextMapPass++
 		resetState(state)
 		routinePressureTracker.reset()
 		freshToolResults.reset()
@@ -387,6 +400,8 @@ export default async function dcpModule(pi: ExtensionAPI, dependencies: { config
 	// Journal operations are committed at the mutation boundary; shutdown does
 	// not write a full runtime snapshot.
 	pi.on("session_shutdown", async () => {
+		contextMap = undefined
+		contextMapPass++
 		routinePressureTracker.reset()
 		freshToolResults.reset()
 		journalMirror = undefined
@@ -472,6 +487,9 @@ export default async function dcpModule(pi: ExtensionAPI, dependencies: { config
 	// ── 10. context: apply pruning and inject nudges ──────────────────────────
 	pi.on("context", async (event, ctx) => {
 		const contextEpoch = state.sessionEpoch
+		const mapPass = ++contextMapPass
+		contextMap = undefined
+		let mapEntries = state.conversationIndexSnapshot
 		const effectiveConfig = configForContext(ctx)
 		ensureEphemeralJournal(ctx)
 		const contextMessages = event.messages
@@ -509,6 +527,18 @@ export default async function dcpModule(pi: ExtensionAPI, dependencies: { config
 				state: summarizeDcpState(state, effectiveConfig),
 				...details,
 			}, ctx)
+			if (mapPass === contextMapPass) {
+				contextMap = providerReady
+					? projectDcpContextMapTelemetry(
+						mapEntries,
+						candidate ?? emergencyCompressionCandidate,
+						mapTokenEstimates,
+						++contextMapRevision,
+						contextEpoch,
+						Date.now(),
+					)
+					: undefined
+			}
 			return { messages }
 		}
 
@@ -545,6 +575,8 @@ export default async function dcpModule(pi: ExtensionAPI, dependencies: { config
 			writeDcpDebugLog(effectiveConfig, "context.rehydrated_tool_records", { ...rehydration }, ctx)
 		}
 		let prunedMessages = applyPruning(contextMessages, state, effectiveConfig)
+		mapEntries = state.conversationIndexSnapshot
+		let mapTokenEstimates = captureDcpContextTokenEstimates(mapEntries, prunedMessages, state.messageMetaSnapshot)
 		// Stable IDs and any pruning decisions that affect this provider-visible
 		// projection must be committed before the request can use them.
 		await persistJournalState(ctx, state)
@@ -1011,6 +1043,8 @@ export default async function dcpModule(pi: ExtensionAPI, dependencies: { config
 						// Re-apply pruning so the new block takes effect on this
 						// same context pass instead of the next one.
 						prunedMessages = preparedProjection ?? applyPruning(contextMessages, state, effectiveConfig)
+						mapEntries = state.conversationIndexSnapshot
+						mapTokenEstimates = captureDcpContextTokenEstimates(mapEntries, prunedMessages, state.messageMetaSnapshot)
 						const clearedAnchors = clearDcpNudgeAnchors(state)
 						warnedProgress.clear()
 						state.progressRecovery = undefined
@@ -1128,6 +1162,8 @@ export default async function dcpModule(pi: ExtensionAPI, dependencies: { config
 				)
 				if (emergencyPruneResult.prunedToolCallIds.length > 0) {
 					prunedMessages = applyPruning(contextMessages, state, effectiveConfig)
+					mapEntries = state.conversationIndexSnapshot
+					mapTokenEstimates = captureDcpContextTokenEstimates(mapEntries, prunedMessages, state.messageMetaSnapshot)
 					const clearedAnchors = clearDcpNudgeAnchors(state)
 					state.consecutiveIgnoredStrongNudges = 0
 					state.progressRecovery = undefined

package/external/pi-tools-suite/src/dcp/pruner-replay-context.ts

@@ -0,0 +1,35 @@
+import type { DcpState } from "./state.js";
+import { stableMessageKeys } from "./pruner-message-ids.js";
+
+/** Match the SDK provider transform, not UI visibility or tool-result errors. */
+export function isReplayableContextMessage(message: any): boolean {
+  return !(message?.role === "assistant" &&
+    (message.stopReason === "error" || message.stopReason === "aborted"));
+}
+
+/**
+ * SDK retry removes failed attempts from live agent state but keeps them in
+ * JSONL. Reload restores them; the provider later omits error/aborted assistants.
+ * Normalize before exact block replay so those history-only attempts cannot
+ * split a range that was committed from the live, post-retry context.
+ *
+ * Older blocks may explicitly include such an attempt. Keep every referenced
+ * occurrence until the existing matcher has checked its exact ID/order/hash;
+ * neither membership arrays nor signed message contents are rewritten. Any
+ * remaining attempts are omitted after replay, before new IDs/plans are built.
+ */
+export function prepareDcpReplayMessages(messages: any[], state: DcpState): any[] {
+  if (messages.every(isReplayableContextMessage)) return messages;
+
+  const referencedIds = new Set<string>();
+  for (const block of state.compressionBlocks) {
+    if (!block.active) continue;
+    for (const members of [block.mutationMembers, block.sourceMembers]) {
+      for (const member of members ?? []) referencedIds.add(member.stableId);
+    }
+  }
+  const keys = stableMessageKeys(messages);
+  return messages.filter((message, index) =>
+    isReplayableContextMessage(message) || referencedIds.has(keys[index]!),
+  );
+}

package/external/pi-tools-suite/src/dcp/pruner.ts

@@ -5,6 +5,7 @@ import { stripStaleDcpMetadataFromMessage } from "./pruner-metadata.js";
 import { injectMessageIds } from "./pruner-message-ids.js";
 import { copyRawMutationHash } from "./conversation-index.js";
 import { applyToolOutputPruning } from "./pruner-tools.js";
+import { isReplayableContextMessage, prepareDcpReplayMessages } from "./pruner-replay-context.js";
 
 export type {
   CompressionCandidate,
@@ -54,7 +55,7 @@ export function applyPruning(
 ): any[] {
   // Deep-clone each message and its content to prevent mutations from
   // affecting the original objects across context events.
-  const msgs: any[] = messages.map((m: any) => {
+  let msgs: any[] = messages.map((m: any) => {
     const clone = { ...m };
     if (Array.isArray(clone.content)) {
       clone.content = clone.content.map((contentBlock: any) =>
@@ -70,6 +71,8 @@ export function applyPruning(
     return stripped;
   });
 
+  msgs = prepareDcpReplayMessages(msgs, state);
+
   // 1. Count user turns → update state.currentTurn. Do this before inserting
   // synthetic compression summaries; the raw session is the source of truth.
   state.currentTurn = msgs.filter((m) => m.role === "user").length;
@@ -79,6 +82,11 @@ export function applyPruning(
   syncCompressionBlocks(msgs, state, config);
   applyCompressionBlocks(msgs, state);
 
+  // Terminal attempts retained solely for old exact ledgers must not become
+  // new addressable source, protocol groups or budget pressure. Raw session
+  // entries remain untouched; this is the same omission the provider makes.
+  msgs = msgs.filter(isReplayableContextMessage);
+
   // Existing explicit/emergency pruning decisions are replayed, but routine
   // context construction never discovers new retroactive deletions. A new user
   // turn must remain append-only for provider prefix caching; destructive

package/external/pi-tools-suite/src/todo/index.ts

@@ -10,6 +10,7 @@ import { applyTaskMutation } from "./state/state-reducer.js";
 import { getState, replaceState } from "./state/store.js";
 import {
 	activateTodoStateScope,
+	appendTodoStateSnapshot,
 	DEFAULT_PROMPT_GUIDELINES,
 	DEFAULT_PROMPT_SNIPPET,
 	publishTodoState,
@@ -456,6 +457,7 @@ export default function (pi: ExtensionAPI) {
 		}
 		const autoClear = autoClearCompletedTodos(result.state);
 		replaceState(autoClear.state);
+		appendTodoStateSnapshot(pi as any, action, params as Record<string, unknown>);
 		publishTodoState(pi as any, ctx, action, params as Record<string, unknown>);
 		if (todoThinkingEnabled) applyTodoThinkingAfterCommit(result.state, ctx, { action, params });
 		try {

package/external/pi-tools-suite/src/todo/todo.ts

@@ -249,7 +249,7 @@ export function publishTodoState(
 	publishRpcSessionState(ctx as TodoStateEventContext | undefined, TODO_STATE_EVENT, snapshot);
 }
 
-function appendTodoStateSnapshot(
+export function appendTodoStateSnapshot(
 	pi: TodoStateEntryWriter,
 	action: TaskAction,
 	params: Record<string, unknown>,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ui-extend",
-  "version": "1.0.47",
+  "version": "2.0.0",
   "description": "Pix: a workspace-first terminal UI for Pi with tabs, readable tool activity, voice input, and bundled agent tools.",
   "private": false,
   "repository": {
@@ -59,7 +59,7 @@
     "rebuild:all": "npm run build:desktop",
     "check": "npm run check:inner",
     "precheck:inner": "npm run generate-schemas --silent",
-    "check:inner": "npm run sync:sdk-pin:check --silent && tsc --noEmit && npm run test:inner",
+    "check:inner": "npm run sync:sdk-pin:check --silent && npm run release:version:check --silent && tsc --noEmit && npm run test:inner && npm run test:release",
     "test": "npm run test:inner",
     "test:inner": "node --import tsx --test \"tests/**/*.test.ts\"",
     "test:tools-suite": "npm --prefix external/pi-tools-suite test",
@@ -82,6 +82,15 @@
     "smoke-test": "bash scripts/smoke-test-package.sh",
     "smoke-test:cli": "node scripts/smoke-test-package-cli.mjs",
     "release:check": "npm run check && npm run build:pix && npm run pack:dry-run",
+    "release:version": "node scripts/release/sync-version.mjs",
+    "release:version:check": "node scripts/release/sync-version.mjs --check",
+    "version": "node scripts/release/sync-version.mjs --stage",
+    "release:prepare": "node scripts/release/prepare.mjs",
+    "release:build": "node scripts/release/bundle.mjs",
+    "release:build:desktop": "node scripts/release/build-desktop.mjs",
+    "release:smoke": "node scripts/release/smoke.mjs",
+    "release:smoke:desktop": "node scripts/release/smoke-desktop.mjs",
+    "test:release": "node --test scripts/release/test/*.test.mjs",
     "publish-npm": "bash scripts/publish.sh",
     "generate-schemas": "tsx scripts/generate-schemas.ts",
     "generate-schemas:check": "tsx scripts/generate-schemas.ts --check",