pi-tuck 1.0.26 → 1.0.28

package/dist/src/diagnostics.d.ts

@@ -1,6 +1,6 @@
 import { type RecallPolicy } from './recall.js';
 import type { SessionEntry } from '@earendil-works/pi-coding-agent';
-export declare const DIAGNOSTIC_BUILD = "e95edde95c614d01e1cbf6489134676fac0c1bbf6aa57ef639ffac1e7e105041";
+export declare const DIAGNOSTIC_BUILD = "e9c750b757776bf44ad79939b633f178ef9a8f14acfab1c8bb6311d692c79e61";
 export interface Receipt {
     id: string;
     build: string;

package/dist/src/request-capacity.d.ts

@@ -22,10 +22,15 @@ export declare const REPLY_FLOOR_MIN = 3584;
 export declare const thinkingOnlyLength: (message: AgentMessage) => boolean;
 /** Thinking-only exhaustion uses the observed largest reply, not the full reserve. Every other failed length/overflow keeps its override. */
 export declare const needsFullReplyReserve: (message: AgentMessage) => boolean;
-/** Read the whole current branch, including replies before cuts. No session-local fallback flag. */
+/** One branch reader for the reserve override and reply floor, including history before cuts. */
+export declare function replyFit(branch: readonly SessionEntry[]): {
+    failed: boolean;
+    largestOutput: number;
+    thinkingStop: boolean;
+};
 export declare function branchReplyFloor(branch: readonly SessionEntry[], reserve: number): number;
 /** Admission never promises more output than a model with a positive reply cap can produce. */
 export declare function requestReplyFloor(branch: readonly SessionEntry[], reserve: number, maxTokens?: number): number;
-/** Check decoded text, including a whole verbatim user quote in our summary; never JSON-escaped substring matching. */
-export declare function carriesPrompt(messages: Messages, prompt: string): boolean;
+/** Check decoded starting text, native or quoted whole with its original role; never JSON-escaped substring matching. */
+export declare function carriesPrompt(messages: Messages, prompt: string, role?: 'user' | 'custom'): boolean;
 export {};

package/dist/src/request-capacity.js

@@ -64,41 +64,46 @@ export const thinkingOnlyLength = (message) => message.role === 'assistant' && m
 /** Thinking-only exhaustion uses the observed largest reply, not the full reserve. Every other failed length/overflow keeps its override. */
 export const needsFullReplyReserve = (message) => message.role === 'assistant' &&
     (message.stopReason === 'length' && !thinkingOnlyLength(message) || message.stopReason === 'error' && isContextOverflow(message));
-/** Read the whole current branch, including replies before cuts. No session-local fallback flag. */
-export function branchReplyFloor(branch, reserve) {
-    let largest = REPLY_FLOOR_MIN, thinkingStop = false;
+/** One branch reader for the reserve override and reply floor, including history before cuts. */
+export function replyFit(branch) {
+    let failed = false, largestOutput = 0, thinkingStop = false;
     for (const entry of branch) {
         if (entry.type !== 'message' || entry.message.role !== 'assistant')
             continue;
         const message = entry.message;
-        if (needsFullReplyReserve(message))
-            return reserve;
+        failed ||= needsFullReplyReserve(message);
         thinkingStop ||= thinkingOnlyLength(message);
         const output = message.usage?.output;
-        if (typeof output === 'number' && Number.isFinite(output) && output > largest)
-            largest = output;
+        if (typeof output === 'number' && Number.isFinite(output) && output > largestOutput)
+            largestOutput = output;
     }
-    // Include the exhausted thinking reply itself, even across later cuts/restarts. Its observed output must fit again;
-    // requestReplyFloor applies the model cap. Ordinary branches retain their existing reserve cap.
-    return thinkingStop ? Math.ceil(largest) : Math.min(reserve, Math.ceil(largest));
+    return { failed, largestOutput, thinkingStop };
+}
+export function branchReplyFloor(branch, reserve) {
+    const { failed, largestOutput, thinkingStop } = replyFit(branch);
+    if (failed)
+        return reserve;
+    // Include exhausted thinking output across cuts/restarts; requestReplyFloor applies the model cap.
+    const largest = Math.ceil(Math.max(REPLY_FLOOR_MIN, largestOutput));
+    return thinkingStop ? largest : Math.min(reserve, largest);
 }
 /** Admission never promises more output than a model with a positive reply cap can produce. */
 export function requestReplyFloor(branch, reserve, maxTokens) {
     const floor = branchReplyFloor(branch, reserve);
     return maxTokens !== undefined && maxTokens > 0 ? Math.min(floor, maxTokens) : floor;
 }
-/** Check decoded text, including a whole verbatim user quote in our summary; never JSON-escaped substring matching. */
-export function carriesPrompt(messages, prompt) {
+/** Check decoded starting text, native or quoted whole with its original role; never JSON-escaped substring matching. */
+export function carriesPrompt(messages, prompt, role = 'user') {
     if (!prompt.length)
         return true;
     return messages.some(message => {
-        if (message.role === 'user') {
+        if (message.role === role) {
             const text = typeof message.content === 'string' ? message.content : message.content.flatMap(block => block.type === 'text' ? [block.text] : []).join('\n');
             return text.includes(prompt);
         }
         if (message.role !== 'compactionSummary')
             return false;
         const split = splitSummary(message.summary);
-        return split !== null && split !== undefined && parseRecords(split.body, split.version).some(record => record.kind === 'excerpt' && record.role === 'user' && record.text.includes(prompt));
+        return split !== null && split !== undefined && parseRecords(split.body, split.version).some(record => record.kind === 'excerpt' && record.role === role && record.text.includes(prompt));
     });
 }

package/dist/src/run.d.ts

@@ -0,0 +1,52 @@
+import { type ExtensionContext, type SessionEntry, type SessionBoundaryDraft } from '@earendil-works/pi-coding-agent';
+import type { Clip } from './clip.js';
+export type CutEntry = {
+    type: 'compaction';
+    summary: string;
+    firstKeptEntryId: string;
+    tokensBefore: number;
+    details?: unknown;
+};
+type Context = Pick<ExtensionContext, 'cwd' | 'sessionManager'>;
+export interface CutView {
+    session: ExtensionContext['sessionManager'];
+    keptFromId: string | undefined;
+    viewStart: number;
+    hasTuckCut: boolean;
+    pending: boolean;
+}
+/** The only owner of a cut that requests carry before Pi saves it. */
+export declare class PendingCut {
+    private cut?;
+    private branchLength;
+    private preview?;
+    plan(cut: CutEntry, branchLength: number): void;
+    clear(): void;
+    take(): CutEntry | undefined;
+    view(ctx: Context, entries?: readonly SessionBoundaryDraft[]): CutView;
+}
+/** Text bridges before Pi appends the starting message. Once visible, every reader uses its entry id.
+ * Bind on the first request/compaction read after message_end (which Pi emits before appending), before steering can replace it. */
+export declare class StartingPrompt {
+    private readonly branchLength;
+    readonly role: 'user' | 'custom';
+    private entryId?;
+    private bridge?;
+    constructor(bridge: string, branchLength: number, role?: 'user' | 'custom');
+    id(branch: readonly SessionEntry[]): string | undefined;
+    text(branch: readonly SessionEntry[]): string;
+}
+export interface Run {
+    phase: 'decided' | 'starting' | 'admitted' | 'failed';
+    claimed: boolean;
+    expired: boolean;
+    prompt?: StartingPrompt;
+    cut: PendingCut;
+    clips: Map<string, Clip>;
+    pendingBoundaryCommit: boolean;
+    thinkingRetryPending: boolean;
+    failure?: Error;
+    refusalReceipted: boolean;
+}
+export declare const createRun: (phase: Run["phase"]) => Run;
+export {};

package/dist/src/run.js

@@ -0,0 +1,89 @@
+import { SessionManager } from '@earendil-works/pi-coding-agent';
+import { hasTuckCut } from './history-tools.js';
+import { viewStart } from './semantic-recall.js';
+import { textOf } from './tuck/core/content.js';
+/** The only owner of a cut that requests carry before Pi saves it. */
+export class PendingCut {
+    cut;
+    branchLength = 0;
+    preview;
+    plan(cut, branchLength) { this.cut = cut; this.branchLength = branchLength; this.preview = undefined; }
+    clear() { this.cut = undefined; this.branchLength = 0; this.preview = undefined; }
+    take() { const cut = this.cut; this.clear(); return cut; }
+    view(ctx, entries = []) {
+        const live = ctx.sessionManager, leaf = live.getLeafId?.(), held = this.preview;
+        // Native entries are append-only; a leaf move invalidates both the saved and pending views, as in the eligibility cache.
+        if (!entries.length && leaf !== undefined && held && held.manager === live && held.cwd === ctx.cwd && held.leaf === leaf)
+            return held.view;
+        const branch = live.getBranch(), cut = this.cut;
+        const remember = (view) => {
+            if (!entries.length && leaf !== undefined)
+                this.preview = { manager: live, cwd: ctx.cwd, leaf, view };
+            return view;
+        };
+        if (!cut && !entries.length) {
+            const last = branch.findLast(entry => entry.type === 'compaction');
+            return remember({ session: live, keptFromId: last?.type === 'compaction' ? last.firstKeptEntryId : undefined,
+                viewStart: viewStart(branch), hasTuckCut: hasTuckCut(branch), pending: false });
+        }
+        // A compact-all plan predates the prompt. Keep from the first appended entry, skipping our capacity receipts.
+        const keptFromId = cut && (cut.firstKeptEntryId || branch.slice(this.branchLength)
+            .find(entry => entry.type !== 'custom' || entry.customType !== 'pi-tuck-capacity')?.id || '');
+        const header = live.getHeader();
+        if (!header)
+            throw new Error("Missing native session header for the prompt's cut");
+        const session = SessionManager.inMemory(ctx.cwd, undefined, [header, ...branch]);
+        if (cut)
+            session.appendCompaction(cut.summary, keptFromId, 0, cut.details, true);
+        // Retry/settlement drafts model the same request view, including an omitted failed reply.
+        for (const entry of entries) {
+            if (entry.type === 'context_edit')
+                session.appendContextEdit(entry.targetId, entry.replacement);
+            else if (entry.type === 'compaction')
+                session.appendCompaction(entry.summary, entry.firstKeptEntryId, 0, entry.details, true, entry.usage);
+            else if (entry.type === 'custom')
+                session.appendCustomEntry(entry.customType, entry.data);
+            else
+                session.appendCustomMessageEntry(entry.customType, entry.content, entry.display, entry.details);
+        }
+        const previewBranch = session.getBranch(), last = previewBranch.findLast(entry => entry.type === 'compaction');
+        return remember({ session, keptFromId: last?.type === 'compaction' ? last.firstKeptEntryId : undefined,
+            viewStart: viewStart(previewBranch), hasTuckCut: hasTuckCut(previewBranch), pending: Boolean(cut) });
+    }
+}
+/** Text bridges before Pi appends the starting message. Once visible, every reader uses its entry id.
+ * Bind on the first request/compaction read after message_end (which Pi emits before appending), before steering can replace it. */
+export class StartingPrompt {
+    branchLength;
+    role;
+    entryId;
+    bridge;
+    constructor(bridge, branchLength, role = 'user') {
+        this.branchLength = branchLength;
+        this.role = role;
+        this.bridge = bridge;
+    }
+    id(branch) {
+        if (!this.entryId && this.bridge !== undefined) {
+            const text = this.bridge;
+            this.entryId = branch.slice(this.branchLength).find(entry => this.role === 'custom'
+                ? entry.type === 'custom_message' && textOf(entry.content) === text
+                : entry.type === 'message' && entry.message.role === 'user' && textOf(entry.message.content).includes(text))?.id;
+            if (this.entryId)
+                this.bridge = undefined;
+        }
+        return this.entryId;
+    }
+    text(branch) {
+        const id = this.id(branch), entry = branch.find(entry => entry.id === id);
+        if (entry?.type === 'message' && entry.message.role === 'user')
+            return textOf(entry.message.content);
+        if (entry?.type === 'custom_message')
+            return textOf(entry.content);
+        if (this.bridge !== undefined)
+            return this.bridge;
+        throw new Error('The starting prompt entry is no longer on this branch');
+    }
+}
+export const createRun = (phase) => ({ phase, claimed: false, expired: false,
+    cut: new PendingCut(), clips: new Map(), pendingBoundaryCommit: false, thinkingRetryPending: false, refusalReceipted: false });

package/dist/src/semantic-recall.d.ts

@@ -101,7 +101,7 @@ export interface SemanticGroup {
 export interface SemanticPage {
     status: string;
     notice: string;
-    coverage: ReturnType<SemanticRecallController["status"]>;
+    coverage: ReturnType<SemanticRecallController["requestCoverage"]>;
     groups: SemanticGroup[];
     method?: string;
 }
@@ -127,6 +127,20 @@ export declare const MAX_INDEX_UNITS = 8000;
 /** The wait before the next automatic attempt, given how many were already armed since the last success. */
 export declare function healDelayMs(attempts: number, integrity: boolean, delays?: readonly number[], steady?: number): number;
 export type SemanticState = 'disabled' | 'unavailable' | 'preparing' | 'ready' | 'waiting';
+export type SemanticSetup = 'off-settings' | 'off-user' | 'not-installed' | 'off-platform' | 'off-project' | 'starting' | 'failed' | 'ready';
+interface SetupDetail {
+    installed?: boolean;
+    reason?: string;
+    stage?: 'setup' | 'start';
+    notice?: string;
+    announced?: boolean;
+}
+/** Setup and operator wording have one owner; runtime indexing state remains separate. */
+export declare function semanticSetupMessage(setup: SemanticSetup, detail?: SetupDetail): string | null;
+export declare function semanticSetupNotice(setup: SemanticSetup, detail?: SetupDetail): {
+    message: string;
+    level: 'info' | 'warning';
+} | undefined;
 /** Where the current view starts, as a branch position: the latest compaction entry's first kept entry. Earlier entries were compacted away. With no compaction, nothing is out of view. */
 export declare function viewStart(branch: SessionEntry[]): number;
 /** `pendingKeptId`: the first kept entry of a cut pi-tuck has applied to the requests but Pi has not yet saved (a prompt's cut is saved at the end of
@@ -147,6 +161,8 @@ export declare class SemanticRecallController {
     private cleanupError;
     private dirty;
     private operations;
+    private setup;
+    private setupDetail;
     private _enabled;
     private _current?;
     private _task?;
@@ -190,7 +206,13 @@ export declare class SemanticRecallController {
     onStateChange(listener: (state: SemanticState, reason: string | null) => void): () => void;
     private touch;
     /** A host that could not configure the runtime records why a requested start failed. The controller stays disabled and `lastError` carries the reason until the next `enable`. */
+    setSetup(setup: SemanticSetup, detail?: SetupDetail): void;
+    /** Compatibility for hosts that already record an external start failure. */
     refuse(reason: string): void;
+    setupNotice(): {
+        message: string;
+        level: "info" | "warning";
+    } | undefined;
     configure(config: SemanticRecallConfig): void;
     /** Ordinary external settings remain caller-selected/outside-project. The
      * optional override is a current-process verified dependency, not Task data. */
@@ -199,6 +221,52 @@ export declare class SemanticRecallController {
     }): Promise<void>;
     enable(): void;
     status(): {
+        setup: SemanticSetup;
+        setupMessage: string | null;
+        enabled: boolean;
+        configured: boolean;
+        cleanupError: string | null;
+        state: SemanticState;
+        snapshotId: string | null;
+        throughEntryId: string | null;
+        eligibleSources: number;
+        totalUnits: number;
+        coveredUnits: number;
+        indexingComplete: boolean;
+        lastError: string | null;
+        window: {
+            indexedCharacters: number;
+            windowCharacters: number;
+            outOfViewCharacters: number;
+            eligibleCharacters: number;
+            oldestCoveredEntryId: string | null;
+            oldestCoveredTime: string | null;
+            conversation: {
+                indexedCharacters: number;
+                outOfViewCharacters: number;
+            };
+            toolResults: {
+                indexedCharacters: number;
+                outOfViewCharacters: number;
+                oldestCoveredTime: string | null;
+            };
+        } | null;
+        recovery: {
+            attempts: number;
+            integrity: boolean;
+            retryAt: string | null;
+        } | null;
+        operations: {
+            preparationEmbeddings: number;
+            queryEmbeddings: number;
+        };
+        limits: {
+            keyword: number;
+            broad: number;
+        };
+    };
+    /** The existing model-facing coverage contract: setup metadata belongs to operator status, not the request. */
+    requestCoverage(): {
         enabled: boolean;
         configured: boolean;
         cleanupError: string | null;
@@ -251,6 +319,8 @@ export declare class SemanticRecallController {
     private index;
     private prepare;
     waitForReady(timeoutMs?: number, signal?: AbortSignal, expectedSnapshotId?: string, forSearch?: boolean): Promise<{
+        setup: SemanticSetup;
+        setupMessage: string | null;
         enabled: boolean;
         configured: boolean;
         cleanupError: string | null;
@@ -306,7 +376,7 @@ export declare class SemanticRecallController {
     private assemble;
     private focus;
     private evidence;
-    disable(joinSearches?: boolean): Promise<void>;
+    disable(joinSearches?: boolean, userOff?: boolean): Promise<void>;
     private closeResources;
     private stopOwner;
     /** A search, or a wait for readiness, is demand: it lets background work start and keeps it alive for IDLE_STOP_MS after the last one. */

package/dist/src/semantic-recall.js

@@ -188,6 +188,44 @@ const SCORE_CHUNK = 1024;
 export function healDelayMs(attempts, integrity, delays = HEAL_DELAYS_MS, steady = HEAL_STEADY_MS) { return integrity ? steady : delays[attempts] ?? steady; }
 /** Errors that mean "the history moved or a slice ended; try again", not that the runtime failed. They do not make the state `unavailable`. */
 const CHURN = /indexing incomplete|history changed|source changed before|branch or source changed|cancelled/i;
+/** Setup and operator wording have one owner; runtime indexing state remains separate. */
+export function semanticSetupMessage(setup, detail = {}) {
+    switch (setup) {
+        case 'not-installed': return 'Semantic recall is not set up yet; start Pi once in an interactive session to set it up. Word recall works meanwhile';
+        case 'starting': return detail.installed ? 'Semantic recall is starting; word recall works meanwhile' : 'Semantic recall is being set up; word recall works meanwhile';
+        case 'failed': return detail.stage === 'start' ? detail.reason ?? 'Semantic recall could not start' : `Semantic recall setup failed: ${detail.reason}`;
+        default: return null;
+    }
+}
+export function semanticSetupNotice(setup, detail = {}) {
+    let message, level = 'info';
+    switch (setup) {
+        case 'off-platform':
+            message = 'pi-tuck: semantic recall needs macOS on Apple silicon; compaction and word recall work.';
+            break;
+        case 'off-project':
+            message = "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.";
+            break;
+        case 'not-installed':
+            message = 'pi-tuck: semantic recall is not set up yet; start Pi once in an interactive session to set it up. Word recall works.';
+            level = 'warning';
+            break;
+        case 'starting':
+            message = detail.notice;
+            break;
+        case 'ready':
+            if (detail.announced)
+                message = 'pi-tuck: semantic recall is set up. Search by meaning works from the first cut on.';
+            break;
+        case 'failed':
+            message = detail.stage === 'start'
+                ? `pi-tuck: semantic recall could not start (${detail.reason}); it tries again when a session starts.`
+                : `pi-tuck: semantic recall setup failed (${detail.reason}). Word recall works; setup retries when a session starts.`;
+            level = 'warning';
+            break;
+    }
+    return message ? { message, level } : undefined;
+}
 const PROBE_TEXT = 'pi-tuck semantic recall status probe';
 class LocalWorker {
     config;
@@ -497,7 +535,7 @@ export function semanticEligibleSources(ctx, policy, access, pendingKeptId) {
     const orders = new Map(branch.map((entry, order) => [entry.id, order]));
     const sources = eligible.flatMap(entry => { const order = orders.get(entry.id); const row = recall.discoveryEntry(entry, attempts, links); if (!row)
         return []; const { sourceText: unusedText, ranges: unusedRanges, ...readable } = row; return [{ entry, row: readable, sourceText: row.sourceText, ranges: row.ranges, order, sha: hash({ entry, order, row: readable, ranges: row.ranges, index: indices.get(entry.id) }) }]; });
-    const pending = pendingKeptId === undefined ? -1 : branch.findIndex(e => e.id === pendingKeptId), start = Math.max(viewStart(branch), pending);
+    const pending = pendingKeptId === undefined ? -1 : pendingKeptId === '' ? branch.length : branch.findIndex(e => e.id === pendingKeptId), start = Math.max(viewStart(branch), pending);
     const session = ctx.sessionManager.getSessionId(), id = hash({ session, project: resolve(ctx.cwd), branch: branch.map(e => [e.id, e.parentId]), sources: sources.map(s => [s.entry.id, s.sha]), ...(pending >= 0 ? { pendingKeptId } : {}) });
     return { id, session, project: ctx.cwd, sources, units: [], complete: false, throughEntryId: sources.at(-1)?.entry.id ?? null, viewStart: start, indexed: new Set() };
 }
@@ -517,6 +555,8 @@ export class SemanticRecallController {
     dirty = false;
     operations = { preparationEmbeddings: 0, queryEmbeddings: 0 };
     // The fields below decide `status().state`; their setters announce a change to `onStateChange` listeners.
+    setup = 'off-user';
+    setupDetail = {};
     _enabled = false;
     _current;
     _task;
@@ -568,7 +608,10 @@ export class SemanticRecallController {
         }
         catch { } }); }
     /** A host that could not configure the runtime records why a requested start failed. The controller stays disabled and `lastError` carries the reason until the next `enable`. */
-    refuse(reason) { this.error = reason; }
+    setSetup(setup, detail = {}) { const announced = setup === 'ready' && this.setupDetail.announced; this.setup = setup; this.setupDetail = announced ? { ...detail, announced: true } : detail; this.touch(); }
+    /** Compatibility for hosts that already record an external start failure. */
+    refuse(reason) { this.setSetup('failed', { stage: 'start', reason }); }
+    setupNotice() { return semanticSetupNotice(this.setup, this.setupDetail); }
     configure(config) { if (this.enabled || this.worker || this.task)
         throw new Error('Disable before changing semantic configuration'); for (const [key, max] of [['queryWaitMs', 120000], ['prepareWorkMs', 120000], ['maxUnits', MAX_INDEX_UNITS], ['maxSourceCharacters', 2000000]]) {
         const value = config[key];
@@ -592,9 +635,11 @@ export class SemanticRecallController {
     }
     enable() { if (this.closing || this.joiningSearches || this.cleanupError)
         throw new Error('Semantic cleanup is unresolved; retry close before enable'); if (!this.config)
-        throw new Error('Optional local semantic runtime is not configured'); this.enabled = true; this.error = null; this.healReason = null; this.healAttempts = 0; this.cancelHeal(); if (this.provider && this.active)
+        throw new Error('Optional local semantic runtime is not configured'); this.setSetup('ready'); this.enabled = true; this.error = null; this.healReason = null; this.healAttempts = 0; this.cancelHeal(); if (this.provider && this.active)
         this.schedule(this.provider); }
-    status() { return { enabled: this.enabled, configured: Boolean(this.config), cleanupError: this.cleanupError, state: (!this.enabled ? 'disabled' : this.healReason !== null || (this.error !== null && !CHURN.test(this.error)) ? 'unavailable' : this.task || this.timer ? 'preparing' : this.current?.complete ? 'ready' : 'waiting'), snapshotId: this.current?.id ?? null, throughEntryId: this.current?.throughEntryId ?? null, eligibleSources: this.current?.sources.length ?? 0, totalUnits: this.current?.units.length ?? 0, coveredUnits: this.current?.indexed.size ?? 0, indexingComplete: Boolean(this.current?.complete), lastError: this.error ?? this.healReason, window: this.current ? windowCoverage(this.current) : null, recovery: this.healReason === null ? null : { attempts: this.healAttempts, integrity: this.healIntegrity, retryAt: this.healRetryAt === null ? null : new Date(this.healRetryAt).toISOString() }, operations: { ...this.operations }, limits: { keyword: 16000, broad: 20000 } }; }
+    status() { return { setup: this.setup, setupMessage: semanticSetupMessage(this.setup, this.setupDetail), enabled: this.enabled, configured: Boolean(this.config), cleanupError: this.cleanupError, state: (!this.enabled ? 'disabled' : this.healReason !== null || (this.error !== null && !CHURN.test(this.error)) ? 'unavailable' : this.task || this.timer ? 'preparing' : this.current?.complete ? 'ready' : 'waiting'), snapshotId: this.current?.id ?? null, throughEntryId: this.current?.throughEntryId ?? null, eligibleSources: this.current?.sources.length ?? 0, totalUnits: this.current?.units.length ?? 0, coveredUnits: this.current?.indexed.size ?? 0, indexingComplete: Boolean(this.current?.complete), lastError: this.error ?? this.healReason ?? semanticSetupMessage(this.setup, this.setupDetail), window: this.current ? windowCoverage(this.current) : null, recovery: this.healReason === null ? null : { attempts: this.healAttempts, integrity: this.healIntegrity, retryAt: this.healRetryAt === null ? null : new Date(this.healRetryAt).toISOString() }, operations: { ...this.operations }, limits: { keyword: 16000, broad: 20000 } }; }
+    /** The existing model-facing coverage contract: setup metadata belongs to operator status, not the request. */
+    requestCoverage() { const { setup, setupMessage, ...coverage } = this.status(); return coverage; }
     schedule(provider) { this.provider = provider; if (!this.enabled || this.timer || !this.active || this.healTimer)
         return; this.timer = setTimeout(() => { this.timer = undefined; if (this.task) {
         this.dirty = true;
@@ -858,10 +903,10 @@ export class SemanticRecallController {
         if (signal?.aborted)
             throw abort();
         if (!this.enabled)
-            return { status: 'disabled', notice: 'Optional semantic recall is disabled; ordinary word recall remains available.', coverage: this.status(), groups: [] };
+            return { status: 'disabled', notice: 'Optional semantic recall is disabled; ordinary word recall remains available.', coverage: this.requestCoverage(), groups: [] };
         this.demand();
         this.searched = true;
-        const deadline = performance.now() + (this.config.queryWaitMs ?? 30000), incomplete = () => ({ status: 'indexing_incomplete', notice: 'No semantic ranking performed: nothing of the requested eligible snapshot is indexed yet.', coverage: this.status(), groups: [] }), unavailable = () => ({ status: 'unavailable', notice: 'Local semantic preparation unavailable; permitted ordinary recall remains available.', coverage: this.status(), groups: [] });
+        const deadline = performance.now() + (this.config.queryWaitMs ?? 30000), incomplete = () => ({ status: 'indexing_incomplete', notice: 'No semantic ranking performed: nothing of the requested eligible snapshot is indexed yet.', coverage: this.requestCoverage(), groups: [] }), unavailable = () => ({ status: 'unavailable', notice: 'Local semantic preparation unavailable; permitted ordinary recall remains available.', coverage: this.requestCoverage(), groups: [] });
         const queryGeneration = this.generation;
         let bound;
         try {
@@ -884,7 +929,7 @@ export class SemanticRecallController {
             if (!(this.current?.id === bound.id && ((this.current.complete && !this.current.units.length) || (indexedPrefix(this.current) > 0 && this.worker !== undefined && !this.recycle && !this.idling)))) {
                 if (page)
                     return page;
-                return { status: 'indexing_incomplete', notice: 'No semantic ranking performed: nothing is out of view, so the whole history is in your context.', coverage: this.status(), groups: [] };
+                return { status: 'indexing_incomplete', notice: 'No semantic ranking performed: nothing is out of view, so the whole history is in your context.', coverage: this.requestCoverage(), groups: [] };
             }
         }
         else {
@@ -915,7 +960,7 @@ export class SemanticRecallController {
             return failure && !CHURN.test(failure) ? unavailable() : incomplete();
         }
         if (!snapshot.units.length)
-            return { status: 'no_matches', notice: 'No eligible original source units in this snapshot.', coverage: this.status(), method: 'embedding', groups: [] };
+            return { status: 'no_matches', notice: 'No eligible original source units in this snapshot.', coverage: this.requestCoverage(), method: 'embedding', groups: [] };
         try {
             const worker = await this.runtime(snapshot.project);
             this.recheckGrown(provider, snapshot, bound.id);
@@ -947,7 +992,7 @@ export class SemanticRecallController {
             // What the caller already read only spares it a repeat. A reference that does not match this history spares nothing, and it must not fail the search.
             const usable = prior.filter(reference => { const source = snapshot.sources.find(s => s.entry.id === reference.entryId); return Number.isSafeInteger(reference.start) && Number.isSafeInteger(reference.end) && reference.start <= reference.end && source !== undefined && reference.sourceSha === source.sha && reference.end <= source.sourceText.length; }), ignored = prior.length - usable.length;
             const previous = [...usable, ...(words?.hits ?? []).map((hit) => ({ entryId: hit.entryId, start: hit.read.offset, end: hit.read.offset + hit.read.limit, sourceSha: snapshot.sources.find(s => s.entry.id === hit.entryId)?.sha }))];
-            return { status: 'ok', notice: 'Related original evidence, not current truth or proof that every qualification was found. Scores do not establish authority, event time or supersession. Sources preserve recorded time and original order.' + (ignored ? ` ${ignored} of the priorResults did not match this history and were ignored, so their text may appear again.` : '') + ` Semantic ranking covers ${covered.conversation.indexedCharacters} of ${covered.conversation.outOfViewCharacters} characters of earlier conversation and ${covered.toolResults.indexedCharacters} of ${covered.toolResults.outOfViewCharacters} characters of earlier tool output (newest first, back to ${covered.toolResults.oldestCoveredTime ?? covered.oldestCoveredTime ?? 'an unknown time'}); use tuck_recall for the rest.` + (older ? ` This ranking covers the history through entry ${snapshot.throughEntryId}: later entries are still being indexed, so search them by keyword.` : ''), coverage: { ...this.status(), window: covered }, method: 'embedding', groups: this.assemble(ranked.map(hit => hit.unit), snapshot, previous) };
+            return { status: 'ok', notice: 'Related original evidence, not current truth or proof that every qualification was found. Scores do not establish authority, event time or supersession. Sources preserve recorded time and original order.' + (ignored ? ` ${ignored} of the priorResults did not match this history and were ignored, so their text may appear again.` : '') + ` Semantic ranking covers ${covered.conversation.indexedCharacters} of ${covered.conversation.outOfViewCharacters} characters of earlier conversation and ${covered.toolResults.indexedCharacters} of ${covered.toolResults.outOfViewCharacters} characters of earlier tool output (newest first, back to ${covered.toolResults.oldestCoveredTime ?? covered.oldestCoveredTime ?? 'an unknown time'}); use tuck_recall for the rest.` + (older ? ` This ranking covers the history through entry ${snapshot.throughEntryId}: later entries are still being indexed, so search them by keyword.` : ''), coverage: { ...this.requestCoverage(), window: covered }, method: 'embedding', groups: this.assemble(ranked.map(hit => hit.unit), snapshot, previous) };
         }
         catch (error) {
             if (error instanceof Error && error.name === 'SemanticAccessError') {
@@ -959,7 +1004,7 @@ export class SemanticRecallController {
                 throw abort();
             }
             this.heal(error);
-            return { status: 'unavailable', notice: 'Local semantic search failed; ordinary recall remains available. ' + (error instanceof Error ? error.message : 'failure'), coverage: this.status(), groups: [] };
+            return { status: 'unavailable', notice: 'Local semantic search failed; ordinary recall remains available. ' + (error instanceof Error ? error.message : 'failure'), coverage: this.requestCoverage(), groups: [] };
         }
     }
     assemble(units, snapshot, previous) {
@@ -1016,7 +1061,8 @@ export class SemanticRecallController {
         return { source, start, end };
     }
     evidence(source, start, end) { return { ...source.row, sourceOrder: source.order, sourceSha: source.sha, text: source.sourceText.slice(start, end), textOffset: start, totalCharacters: source.sourceText.length, read: { entryId: source.entry.id, offset: start, limit: end - start }, complete: start === 0 && end === source.sourceText.length }; }
-    async disable(joinSearches = true) { if (joinSearches)
+    async disable(joinSearches = true, userOff = true) { if (userOff)
+        this.setSetup('off-user'); if (joinSearches)
         this.joiningSearches++; try {
         if (!this.closing) {
             const stop = this.stopOwner();
@@ -1142,7 +1188,7 @@ export class SemanticRecallController {
     // A source that can no longer be read stops recall; the reason stays readable until the next enable, so this never looks like recall that was never on.
     async revoked(error) { await this.disable(false); this.error = error instanceof Error ? error.message : 'Source access denied'; }
     async invalidate() { await this.disable(); this.error = 'Caller invalidated semantic source access; explicit enable required'; }
-    async close() { await this.disable(); this.provider = undefined; this.searched = false; } // a closed controller serves a new session, which has not searched; a disable and enable keeps it
+    async close() { await this.disable(true, false); this.provider = undefined; this.searched = false; } // a closed controller serves a new session, which has not searched; a disable and enable keeps it
 }
 export const createSemanticRecall = (config) => new SemanticRecallController(config);
 /** Consolidate only source-bound coordinate overlap; equal text in distinct events is retained.

package/dist/src/status.d.ts

@@ -12,6 +12,7 @@ export declare function statusText(input: {
         customType?: unknown;
         data?: unknown;
     }[];
+    pending?: boolean;
     cutAt: number | undefined;
     search: boolean;
     semantic: {

package/dist/src/status.js

@@ -18,7 +18,7 @@ export function statusText(input) {
     const cuts = input.branch.filter(e => e.type === "compaction"), ours = cuts.filter(e => e.details?.compactor === "pi-tuck");
     const last = ours.at(-1), before = last?.tokensBefore, after = last?.details?.tokensAfter;
     const count = (n) => n.toLocaleString("en-US");
-    const cutLine = ours.length === 0 ? "Cuts: none yet in this session. The recall tools appear after the first cut."
+    const cutLine = ours.length === 0 ? input.pending ? "Cuts: none saved yet in this session." : "Cuts: none yet in this session. The recall tools appear after the first cut."
         : `Cuts: ${ours.length} by pi-tuck in this session` + (typeof before === "number" && typeof after === "number" ? `, the last from ${count(before)} to ${count(after)} tokens.` : ".");
     const native = cuts.length - ours.length;
     const retries = input.branch.filter(entry => entry.type === "custom" && entry.customType === "pi-tuck-capacity" &&
@@ -31,6 +31,7 @@ export function statusText(input) {
         `pi-tuck ${input.version} (the version this session loaded; restart Pi after an update).`,
         cutLine,
         ...(retries ? [`Retries: ${retries} after thinking-only length stops in this session.`] : []),
+        ...(input.pending ? ["A cut is pending: requests already carry it; the first boundary saves it."] : []),
         ...(native > 0 ? [`Pi's own compaction cut ${native} time${native === 1 ? "" : "s"} in this session.`] : []),
         input.cutAt === undefined ? "Cut point: adapts by itself." : `Cut point: fixed at cutAt ${input.cutAt} of the input room. Remove cutAt from pi-tuck.json to let it adapt.`,
         searchLine,