pi-tuck 1.0.26 → 1.0.28

package/CHANGELOG.md

@@ -3,6 +3,53 @@
 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
+
+- **A run that a custom message started could lose that message after a cut in the middle of the run.** pi-tuck protected only a prompt the
+  user typed. A tool-loop cut in a run that an extension started with a custom message kept the message neither whole nor quoted, so 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. Runs started by typed prompts are unchanged. A custom message with no text has
+  nothing to quote and stays unprotected, as before.
+
+### Added
+
+- A seeded lifecycle sequence test drives real Pi through orders of prompts, handled prompts, custom-message runs, tree moves, new
+  sessions, compactions and aborts. It checks invariants read from outputs only. It reproduces 1.0.23's stale-cut bug and found this one.
+
+### Release gates
+
+- **Shipped without a live gate, because its replay matches 1.0.26 exactly:** 13,946 requests, 0 different, 0 dead tasks, clips 17 → 17.
+  Strict stress: 0 findings. Tests (745) and CI. The packed tarball loaded in the real installed Pi.
+
 ## [1.0.26] - 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.24`.
-- To pin a version, add it: `pi install npm:pi-tuck@1.0.24`.
+- 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
 
@@ -102,7 +102,7 @@ pi-tuck's tools appear only after its first cut. Before that there is nothing ou
 
 | Command | Does |
 |---|---|
-| `/tuck` | Says in words what pi-tuck is doing in this session: the version this session loaded (an open session keeps it until Pi restarts), how many cuts pi-tuck made and the last one's size before and after, whether the cut point adapts or is fixed by `cutAt`, and how search works here. It is for you; the model sees nothing new. |
+| `/tuck` | Says in words what pi-tuck is doing in this session: the version this session loaded (an open session keeps it until Pi restarts), how many cuts and retries pi-tuck made and the last cut's size before and after, whether the cut point adapts or is fixed by `cutAt`, and how search works here. It is for you; the model sees nothing new. |
 | `/tuck-semantic on\|off\|status` | Turns semantic search on or off for this session, or shows its state. |
 | `/tuck-incident on\|next\|off\|status` | Records this session's compaction decisions to a file you can attach to a bug report. |
 
@@ -131,8 +131,11 @@ Known limits today:
 - A host that patches a large section into the system prompt could get a refusal that a cut would have fit (1.0.0 to 1.0.16; fixed in 1.0.17). pi-tuck plans a prompt's cut when the prompt arrives, before other extensions change the system prompt. A host engine that adds a section of thousands of tokens for one turn could push that turn's first request over the room, and the final guard refused it. Now the guard plans the cut against the system prompt as finally sent, and refuses only if that cut does not fit either ([`CHANGELOG.md`](CHANGELOG.md) 1.0.17).
 - Semantic recall never started in `pi -p` (1.0.0 to 1.0.20; fixed in 1.0.21). pi-tuck skipped semantic recall whenever Pi ran with no UI, to keep a one-shot run from starting the first-time download, and that also skipped a runtime that was already installed. Jobs run with `pi -p` searched by keyword only, while `tuck_search` said semantic recall was being set up. RPC mode was not affected ([`CHANGELOG.md`](CHANGELOG.md) 1.0.21).
 - pi-tuck refused requests that fit the window, and could strand a session (1.0.0 to 1.0.21; fixed in 1.0.22). It refused at the room, the window less the full reply reserve, where native Pi still sends. With Pi's defaults and a large setup, a session could be refused at every prompt. The final refusal now sits at the window less a reply floor ([`CHANGELOG.md`](CHANGELOG.md) 1.0.22).
+- pi-tuck 1.0.25 failed to load in an installed Pi ("Cannot find module '@earendil-works/pi-ai/utils/estimate'"); fixed in 1.0.26, and 1.0.25 is deprecated. Since 1.0.23, the check of Pi's own reply cap also never ran in an installed Pi, for the same reason: Pi's extension loader resolves only a few pi-ai entry points for an installed package. It loaded only in tests and the eval harness, and the installed package fell back to the same 4,096-token margin without it. Fixed in 1.0.26, which was loaded in a real installed Pi before publishing ([`CHANGELOG.md`](CHANGELOG.md) 1.0.26).
+- 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).
@@ -193,7 +196,9 @@ A bad file is reported at session start, and pi-tuck uses the defaults.
 
 pi-tuck keeps room for the model's reply. Since 1.0.20 that room is Pi's `compaction.reserveTokens` (default 16,384), the same as native Pi. It rises to the model's `maxTokens` for the rest of the branch only after a reply on that branch did not fit: a reply that stopped for length, or a request refused as a context overflow. A transient error such as a 503 keeps the native room. This is read from the current branch at each decision, so resume, fork and `/tree` follow the branch, and a new session starts at `reserveTokens` again. A host that passes its own reserve keeps its own. Before 1.0.20, pi-tuck always reserved the larger of the two, so with a large `maxTokens` it cut earlier than native Pi.
 
-Since 1.0.22, pi-tuck refuses a request only past a line near the window. Pi sets each request's reply cap to the window less its own estimate of the request less a 4,096-token safety margin, and since 1.0.23 pi-tuck reads that margin from Pi. A request above the room goes out only if Pi's own cap still leaves the reply floor. The floor is the larger of the biggest reply seen on the branch and 3,584 tokens, capped at the model's own reply cap. After a reply that stopped for length or was refused as a context overflow, the floor is the reserve. The line never sits below the room, where 1.0.21 also sends. Before it refuses, pi-tuck cuts to the band, cuts to the room, makes a smaller summary and clips a fresh tool result, in that order. A run's request always carries the whole prompt that started the run: if it cannot fit after every reduction, pi-tuck stops the run with a notice saying to shorten the prompt or use a larger window. Each refusal, and each request sent above the room, leaves one `pi-tuck-capacity` entry in the session; it is never sent to the model, and never appears in summaries or recall.
+Since 1.0.22, pi-tuck refuses a request only past a line near the window. Pi sets each request's reply cap to the window less its own estimate of the request less a 4,096-token safety margin, and since 1.0.26 pi-tuck loads Pi's own reply clamp and estimator from the running Pi's install (a host that embeds Pi falls back to the same 4,096-token margin). Since 1.0.25, each point that sends a request above the room checks Pi's own cap on the request it would send. When that leaves less than the reply floor, pi-tuck cuts deeper, with up to three re-plans and then the deepest cut that still carries the whole prompt, and refuses only if that leaves less than the floor too. The floor is the larger of the biggest reply seen on the branch and 3,584 tokens, capped at the model's own reply cap. After a reply that stopped for length or was refused as a context overflow, the floor is the reserve. The line never sits below the room, where 1.0.21 also sends. Before it refuses, pi-tuck cuts to the band, cuts to the room, makes a smaller summary and clips a fresh tool result, in that order. A run's request always carries the whole prompt that started the run: if it cannot fit after every reduction, pi-tuck stops the run with a notice saying to shorten the prompt or use a larger window. Each refusal, and each request sent above the room, leaves one `pi-tuck-capacity` entry in the session; it is never sent to the model, and never appears in summaries or recall.
+
+Since 1.0.25, after a reply that stops for length with thinking only, pi-tuck retries the turn once, leaving the stopped reply out of the request. It uses the deepest cut that still carries the whole prompt when that gives the reply more room, and otherwise retries uncut. A retried reply that stops again ends the run. When a run ends on a reply cut at the output limit, pi-tuck says so ("the last reply stopped at the model's output limit and may be cut off"): in the interface, or on stderr when there is no UI. The notice never enters the model's context.
 
 pi-tuck estimates the request's size, and it scales that estimate by the worst gap it has seen between its count and the provider's. In a small window, an upstream that spends far more context on tool schemas (some OpenRouter upstreams do) can leave too little room. If a small window refuses, use a larger window, or pin one upstream as below.
 

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 = "e95edde95c614d01e1cbf6489134676fac0c1bbf6aa57ef639ffac1e7e105041";
+export declare const BUILD_ID = "e9c750b757776bf44ad79939b633f178ef9a8f14acfab1c8bb6311d692c79e61";

package/dist/src/build-id.js

@@ -1 +1 @@
-export const BUILD_ID = "e95edde95c614d01e1cbf6489134676fac0c1bbf6aa57ef639ffac1e7e105041";
+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;