pi-tuck 1.0.27 → 1.0.28

package/CHANGELOG.md

@@ -3,6 +3,33 @@
 All notable changes to pi-tuck. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
 [Semantic Versioning](https://semver.org/).
 
+## [1.0.28] - 2026-11-10
+
+### Changed
+
+- **One owner for each piece of state that had several, the user-approved state refactor.** Requests are unchanged.
+  - The **pending cut** has one view, which every consumer reads: the request, `tuck_search`, the history tools, Pi's threshold path, the
+    band, the boundary save, `/tuck`, and the clamp, deepest-cut and retry previews.
+  - The **run** is one record, reset in one place. It holds the starting prompt as an entry, a typed prompt or a custom message.
+  - **Reply fit** has one reader behind the reserve and the floor.
+  - **Semantic setup** has an explicit state, which `/tuck` and the notices derive from.
+
+### Fixed
+
+- **A plan made for a prompt that another extension handled could still answer Pi's own compaction check before a later run.** A plan now
+  answers that check only until the next tick, unless its own run starts. The cut it made was valid but deeper than needed.
+
+### Release gates
+
+- **Shipped without a live gate, because its replay matches 1.0.27:** 13,946 requests on 29 recordings, 0 lost and 0 dead tasks, clips
+  17 → 17. In the final run, one recording (live32-t02-M) showed 32 differing requests. Two more runs of this build on that recording matched
+  1.0.27 exactly, as did two more runs of 1.0.27, so it was noise.
+- **Strict stress:** 0 findings.
+- **The lifecycle sequence test:** 41 seeds and 1,107 events, clean.
+- **An independent review** found 2 notice-only differences from 1.0.27, both fixed with tests: the length-stop notice after a tree move
+  inside another extension's settle, and the "set up" notice for a setup that finishes in a later session.
+- Tests (802) and CI. The packed tarball loaded in the real installed Pi.
+
 ## [1.0.27] - 2026-11-10
 
 ### Fixed

package/README.md

@@ -64,8 +64,8 @@ Then start a new Pi session. That is all. pi-tuck takes over Pi's compaction, bo
 
 - Needs Pi 1.2.0 or later (tested on 1.2.0 and 1.4.0), on macOS or Linux. On an older Pi, pi-tuck stays off, Pi's own compaction runs, and pi-tuck says so once. Full features on macOS with Apple silicon; elsewhere, compaction and word recall.
 - On macOS with Apple silicon, the first session also downloads a local search model in the background (about 390 MB, once), and says once when it is set up. Until it is ready, search works by keyword. See [Semantic search](#semantic-search).
-- Prefer GitHub? `pi install git:github.com/galyavin/pi-tuck@v1.0.26`.
-- To pin a version, add it: `pi install npm:pi-tuck@1.0.26`.
+- Prefer GitHub? `pi install git:github.com/galyavin/pi-tuck@v1.0.27`.
+- To pin a version, add it: `pi install npm:pi-tuck@1.0.27`.
 
 ## Uninstall
 
@@ -135,6 +135,7 @@ Known limits today:
 - A request above the room could be admitted and then refused, leaving the session stuck where native Pi would have sent (1.0.22 to 1.0.24; fixed in 1.0.25). pi-tuck checked its line in its own corrected token count, while Pi's reply cap uses Pi's own estimate, which is higher when the provider counts fewer tokens than pi-tuck's raw measure ([`CHANGELOG.md`](CHANGELOG.md) 1.0.25).
 - Near the 1.0.22 refusal line, replies were cut to a few hundred tokens (1.0.22; fixed in 1.0.23). 1.0.22 left only its reply floor and did not count Pi's 4,096-token margin on the reply cap ([`CHANGELOG.md`](CHANGELOG.md) 1.0.23).
 - Cost of the 1.0.22 change: between the room and the window, the reply reserve no longer cushions a wrong count. At a cold start an undercount can reach the provider. A provider that errors is caught and learned from; a server that truncates silently truncates, as it does for native Pi. With a setup above the room, cuts are forced and frequent, each freeing little, which beats a stranded session ([`CHANGELOG.md`](CHANGELOG.md) 1.0.22).
+- A run that a custom message started could lose that message after a cut in the middle of the run (fixed in 1.0.27). pi-tuck protected only a prompt the user typed, so a tool-loop cut in a run an extension started with a custom message kept the message neither whole nor quoted, and later requests lacked the instruction that started the run. Now such a message gets the same protection as a typed prompt: it is kept, or quoted whole in the summary, and the guard checks it. A custom message with no text has nothing to quote and stays unprotected ([`CHANGELOG.md`](CHANGELOG.md) 1.0.27).
 - A prompt's cut could reach a run it was not planned for (fixed in 1.0.24). pi-tuck plans a prompt's cut when the prompt arrives. When another extension handled that prompt, no run started, and the plan waited for the next run. A run started by a custom message carried a cut sized for the prompt that never ran, deeper than needed. After a move in the session tree (`/tree`), the plan was applied on the new branch, where its kept entry was not present, so the request lost the custom message that started the run, even on a branch that needed no cut ([`CHANGELOG.md`](CHANGELOG.md) 1.0.24).
 - Four `tuck_search` faults, fixed in 1.0.23: it said semantic recall was still indexing when the history was fully indexed; in the turn after a prompt's cut it ranked nothing ("nothing is out of view"); a keyword-search timeout on a very long history failed the whole search, where now the semantic results still answer; and the timeout message named a pattern instead of the history's size ([`CHANGELOG.md`](CHANGELOG.md) 1.0.23).
 - pi-tuck cut earlier than native Pi when a model's reply cap is above Pi's reserve (1.0.0 to 1.0.19; fixed in 1.0.20). It reserved the larger of Pi's `compaction.reserveTokens` and the model's `maxTokens`: with `maxTokens` 32,768 and a reserve of 16,384 on an 81,920 window, its room fell to 49,152 tokens, where native Pi compacts at 65,536 ([`CHANGELOG.md`](CHANGELOG.md) 1.0.20).

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export type { CompactionOptions } from "./src/compaction.js";
 export { installCompaction } from "./src/compaction.js";
 export { inspectIncident, readableIncident } from "./src/diagnostic-replay.js";
 export { createSemanticRecall, SemanticRecallController } from "./src/semantic-recall.js";
-export type { SemanticRecallConfig, PriorResult, SemanticState } from "./src/semantic-recall.js";
+export type { SemanticRecallConfig, PriorResult, SemanticState, SemanticSetup } from "./src/semantic-recall.js";
 export { ensureSemanticRuntime } from "./src/setup.js";
 /** pi-tuck as a Pi extension: compaction and history recall always; semantic recall too, unless `pi-tuck.json` in Pi's agent folder
  * says `{"semanticRecall": false}`. Its runtime is set up in the background the first time a session starts. The same file's `"cutAt"`

package/dist/index.js

@@ -43,14 +43,21 @@ export default async function (pi) {
     }
     const semanticRecall = createSemanticRecall();
     // `/tuck-semantic off` holds for the rest of the session, including over a setup that finishes later.
-    let off = false;
     const settings = readSettings(join(getAgentDir(), "pi-tuck.json"));
     // Semantic recall runs on Metal, so only on Apple silicon; elsewhere the model is not offered tuck_search at all.
     const appleSilicon = process.platform === "darwin" && process.arch === "arm64";
-    const handle = await installCompaction(pi, { semanticRecall, search: appleSilicon, cutAt: settings.cutAt, onSemanticSetting: async (enabled) => { off = !enabled; } });
-    if (settings.semanticRecall === false)
+    const handle = await installCompaction(pi, { semanticRecall, search: appleSilicon, cutAt: settings.cutAt, onSemanticSetting: async (enabled) => {
+            if (!enabled)
+                semanticRecall.setSetup("off-user");
+            else if (semanticRecall.status().setup === "off-user")
+                semanticRecall.setSetup("starting", { installed: existsSync(runtimeConfigPath(defaultRoot())) });
+        } });
+    if (settings.semanticRecall === false) {
+        semanticRecall.setSetup("off-settings");
+        pi.on("session_start", () => { semanticRecall.setSetup("off-settings"); });
         return;
-    let session = 0, said = "", setup, announced = false;
+    }
+    let session = 0, said = "", announced = false, setup;
     // A context outlives its session (a setup can finish after /new); a notice to an ended session is dropped.
     // With no UI (pi -p), Pi shows no notices, so a settings error or an off or failing semantic recall would go unsaid: write each to stderr
     // instead, once per session. stderr is the operator's; it never enters the model's context.
@@ -75,49 +82,55 @@ export default async function (pi) {
         said = message;
         say(ctx, message, level);
     } };
+    const announce = (ctx, state, detail) => {
+        semanticRecall.setSetup(state, detail);
+        const notice = semanticRecall.setupNotice();
+        if (notice)
+            (state === "off-platform" || state === "off-project" ? once : say)(ctx, notice.message, notice.level);
+    };
     pi.on("session_shutdown", () => { session++; });
     pi.on("session_start", (_event, ctx) => {
         const current = ++session;
-        off = false;
         stderrSaid.clear();
         if (settings.error)
             once(ctx, `pi-tuck: ${settings.error}; using the defaults.`, "warning");
         if (!appleSilicon)
-            return once(ctx, "pi-tuck: semantic recall needs macOS on Apple silicon; compaction and word recall work.", "info");
+            return announce(ctx, "off-platform");
         // Semantic recall keeps its runtime and indexes outside the project it serves, so not when Pi runs in a folder that holds its
         // agent folder, such as the home folder.
         if (within(real(getAgentDir()), real(ctx.cwd)))
-            return once(ctx, "pi-tuck: semantic recall is off here because Pi's agent folder is inside this folder; open Pi in a project folder to use it.", "info");
+            return announce(ctx, "off-project");
         // A run with no UI (pi -p, RPC, JSON) uses a runtime that is already installed: that needs no download. It does not start a first-time
         // setup, which would outlast a one-shot run, and it says why, so tuck_search and /tuck name the real state.
         const installed = existsSync(runtimeConfigPath(defaultRoot()));
-        if (!ctx.hasUI && !installed) {
-            semanticRecall.refuse("Semantic recall is not set up yet; start Pi once in an interactive session to set it up. Word recall works meanwhile");
-            return say(ctx, "pi-tuck: semantic recall is not set up yet; start Pi once in an interactive session to set it up. Word recall works.", "warning");
-        }
-        if (!semanticRecall.status().configured)
-            semanticRecall.refuse(installed ? "Semantic recall is starting; word recall works meanwhile" : "Semantic recall is being set up; word recall works meanwhile");
-        setup ??= ensureSemanticRuntime(defaultRoot(), message => { announced = true; say(ctx, message, "info"); });
+        if (!ctx.hasUI && !installed)
+            return announce(ctx, "not-installed");
+        // The download's announcement outlives the session that made it: a session that starts while the shared setup is still running
+        // owes the "set up" notice once, as before the refactor.
+        semanticRecall.setSetup("starting", { installed, announced });
+        setup ??= ensureSemanticRuntime(defaultRoot(), message => {
+            announced = true;
+            if (current === session && semanticRecall.status().setup !== "off-user")
+                announce(ctx, "starting", { installed, notice: message, announced: true });
+        });
         setup.then(async () => {
-            if (current !== session || off)
+            if (current !== session || semanticRecall.status().setup === "off-user")
                 return;
             try {
-                await handle.setSemanticEnabled(true, ctx); // reads the runtime's configuration through the outside-project check
-                // The download was announced, so its end is too: once, when semantic recall first starts on it.
-                if (announced && current === session) {
+                await handle.setSemanticEnabled(true, ctx);
+                if (current === session && semanticRecall.status().setup !== "off-user") {
+                    announce(ctx, "ready", { announced });
                     announced = false;
-                    say(ctx, "pi-tuck: semantic recall is set up. Search by meaning works from the first cut on.", "info");
                 }
             }
             catch (error) {
-                if (current === session)
-                    say(ctx, `pi-tuck: semantic recall could not start (${reason(error)}); it tries again when a session starts.`, "warning");
+                if (current === session && semanticRecall.status().setup !== "off-user")
+                    announce(ctx, "failed", { stage: "start", reason: reason(error) });
             }
         }, error => {
             setup = undefined; // the next session start tries again
-            semanticRecall.refuse(`Semantic recall setup failed: ${reason(error)}`);
-            if (current === session)
-                say(ctx, `pi-tuck: semantic recall setup failed (${reason(error)}). Word recall works; setup retries when a session starts.`, "warning");
+            if (current === session && semanticRecall.status().setup !== "off-user")
+                announce(ctx, "failed", { stage: "setup", reason: reason(error) });
         });
     });
 }

package/dist/src/build-id.d.ts

@@ -1 +1 @@
-export declare const BUILD_ID = "480a4cbd70d99cf72adcc93f282c17434d1997e54d3f38fe2f26b3c642f50b2f";
+export declare const BUILD_ID = "e9c750b757776bf44ad79939b633f178ef9a8f14acfab1c8bb6311d692c79e61";

package/dist/src/build-id.js

@@ -1 +1 @@
-export const BUILD_ID = "480a4cbd70d99cf72adcc93f282c17434d1997e54d3f38fe2f26b3c642f50b2f";
+export const BUILD_ID = "e9c750b757776bf44ad79939b633f178ef9a8f14acfab1c8bb6311d692c79e61";

package/dist/src/compaction.d.ts

@@ -74,6 +74,8 @@ export declare function installCompaction(pi: ExtensionAPI, options?: Compaction
     close: () => Promise<void>;
     semanticRecall: SemanticRecallController;
     setSemanticEnabled: (enabled: boolean, ctx: ExtensionContext) => Promise<{
+        setup: import("./semantic-recall.js").SemanticSetup;
+        setupMessage: string | null;
         enabled: boolean;
         configured: boolean;
         cleanupError: string | null;
@@ -119,6 +121,8 @@ export declare function installCompaction(pi: ExtensionAPI, options?: Compaction
     semanticStatus: () => {
         host?: unknown;
         local: {
+            setup: import("./semantic-recall.js").SemanticSetup;
+            setupMessage: string | null;
             enabled: boolean;
             configured: boolean;
             cleanupError: string | null;