@zergai/ztc 0.4.0-beta.1 → 0.5.0-beta.1

package/dist/app/session_manager.js

@@ -4,96 +4,242 @@
  * Eliminates duplicated session logic between TUI (cli_ratatui.ts) and headless (headless.ts).
  * Each renderer provides its own deps for message access and logging.
  */
-import { saveSession, saveSessionToFile, saveMuxStateOnly, cleanupOldSessions } from '../session.js';
+import { randomUUID } from 'node:crypto';
+import { createUsageSnapshot, mergeUsageSnapshots } from '../usage_snapshot.js';
+import { createDiagnosticSnapshot, captureSessionDiagnosticSnapshot, mergeDiagnosticSnapshots, recordDiagnosticEvent } from '../diagnostics/session_export.js';
+import { saveSession, saveSessionToFile, saveMuxStateOnly, cleanupOldSessions, retainCurrentSession, loadSessionFromFile } from '../session.js';
 import { pruneZtcTempDirs } from '../utils/ztc_cleanup.js';
 import { configStore } from '../config.js';
-import { estimateConversationTokens, formatTokenCount, getContextStatus, contextStatusFromUsed, resolveAutoCompact, } from '../utils/context.js';
+import { estimateConversationTokens, formatTokenCount, getContextStatus, getContextWindowSize, contextStatusFromUsed, resolveAutoCompact, } from '../utils/context.js';
 import { compactConversation, describeCompaction, compactMessages, smartSummarizer, localSummarizer } from '../utils/compaction.js';
-import { stripEphemeralMessages } from '../utils/ephemeral.js';
+import { prepareSessionMessages } from './session_messages.js';
 /**
  * Manages session persistence, auto-save timers, and context compaction.
  */
 export class SessionManager {
     deps;
+    diagnostics = createDiagnosticSnapshot();
+    usage = createUsageSnapshot();
+    jobDiagnosticStates = new Map();
     autoSaveTimer = null;
     saveQueue = Promise.resolve();
-    cleanupDone = false;
+    muxSnapshot;
+    muxCapture = null;
+    muxGeneration = 0;
+    cleanupPromise = null;
     constructor(deps) {
         this.deps = deps;
     }
     setSessionId(sessionId) {
+        if (this.deps.sessionId !== sessionId) {
+            this.diagnostics = createDiagnosticSnapshot();
+            this.usage = createUsageSnapshot();
+            this.jobDiagnosticStates.clear();
+            this.muxSnapshot = undefined;
+            this.muxCapture = null;
+            this.muxGeneration++;
+        }
         this.deps.sessionId = sessionId;
     }
+    /** Capture the current agent before replacement, then return detached canonical facts. */
+    getDiagnostics() {
+        const current = this.deps.getRuntimeState?.().diagnostics;
+        if (current)
+            this.diagnostics = mergeDiagnosticSnapshots(this.diagnostics, current);
+        this.diagnostics = captureSessionDiagnosticSnapshot({ messages: this.deps.getMessages(), diagnostics: this.diagnostics });
+        return structuredClone(this.diagnostics);
+    }
+    restoreDiagnostics(snapshot) {
+        if (snapshot)
+            this.diagnostics = mergeDiagnosticSnapshots(this.diagnostics, snapshot);
+    }
+    getUsageSnapshot() {
+        const current = this.deps.getRuntimeState?.().usage;
+        if (current)
+            this.usage = mergeUsageSnapshots(this.usage, current);
+        return structuredClone(this.usage);
+    }
+    restoreUsageSnapshot(snapshot) {
+        if (snapshot)
+            this.usage = mergeUsageSnapshots(this.usage, snapshot);
+    }
+    recordHostDiagnostic(kind, data) {
+        this.diagnostics = recordDiagnosticEvent(this.diagnostics, {
+            id: randomUUID(), kind, origin: 'host', storedRole: null,
+            timestamp: new Date().toISOString(), data,
+        });
+    }
+    recordCommandJob(job) {
+        // Observation polling must not create duplicate transitions or imply fresh output.
+        const state = JSON.stringify([job.status, job.ended_at ?? null, job.exit_code ?? null]);
+        if (this.jobDiagnosticStates.get(job.job_id) === state)
+            return;
+        this.jobDiagnosticStates.set(job.job_id, state);
+        this.recordHostDiagnostic('job', {
+            jobId: job.job_id, status: job.status, command: job.command, cwd: job.cwd,
+            startedAt: job.started_at, endedAt: job.ended_at ?? null, exitCode: job.exit_code ?? null,
+            error: job.error ?? null, logReference: job.log_path, logAvailability: 'not_verified',
+            outputTruncated: job.output_truncated ?? null, droppedBytes: job.dropped_bytes ?? null,
+        });
+    }
     /**
      * Run one-time cleanup of stale sessions and temp dirs.
      * Called after session load so we never delete a session the caller
      * is about to resume.
      */
     runStartupCleanup() {
-        if (this.cleanupDone)
-            return;
-        this.cleanupDone = true;
-        void cleanupOldSessions(process.cwd()).catch(() => { });
-        void pruneZtcTempDirs().catch(() => { });
+        if (this.cleanupPromise)
+            return this.cleanupPromise;
+        this.cleanupPromise = (async () => {
+            if (!this.deps.sessionFile) {
+                try {
+                    await retainCurrentSession(this.deps.getSessionCwd?.() ?? process.cwd(), this.deps.sessionId);
+                    await cleanupOldSessions(this.deps.getSessionCwd?.() ?? process.cwd(), configStore.get().sessionRetentionCount ?? null);
+                }
+                catch (error) {
+                    this.deps.debugLog(`[SessionManager.cleanup] Session retention skipped: ${error.message}`);
+                }
+            }
+            await pruneZtcTempDirs().catch(() => { });
+        })();
+        return this.cleanupPromise;
     }
     /**
      * Save the current session, filtering out ephemeral system messages.
      */
     async save(options = {}) {
+        options.signal?.throwIfAborted();
+        // Start a fresh renderer projection outside the durability queue. Required
+        // admission saves wait only briefly, retaining the last detached projection
+        // if the renderer is unavailable; a responsive renderer supplies its current
+        // layout even on the first required save.
+        if (options.captureLayout ?? true) {
+            const capture = this.refreshMuxState();
+            if (options.required && options.captureLayout !== true) {
+                let timer;
+                try {
+                    await Promise.race([capture, new Promise(resolve => { timer = setTimeout(resolve, 250); })]);
+                }
+                finally {
+                    clearTimeout(timer);
+                }
+            }
+            else
+                await capture;
+        }
+        options.signal?.throwIfAborted();
         const pendingSave = this.saveQueue.then(() => this.writeCurrentSession(options));
         this.saveQueue = pendingSave.catch(() => { });
         return pendingSave;
     }
+    async refreshMuxState() {
+        if (!this.deps.getMuxState)
+            return;
+        if (this.muxCapture)
+            return this.muxCapture;
+        const generation = this.muxGeneration;
+        const read = this.deps.getMuxState;
+        const capture = (async () => {
+            try {
+                const state = await read.call(this.deps);
+                if (generation === this.muxGeneration && state !== undefined)
+                    this.muxSnapshot = structuredClone(state);
+            }
+            catch (error) {
+                this.deps.debugLog(`[SessionManager.save] Optional layout unavailable: ${String(error)}`);
+            }
+        })();
+        this.muxCapture = capture;
+        try {
+            await capture;
+        }
+        finally {
+            if (this.muxCapture === capture)
+                this.muxCapture = null;
+        }
+    }
     async writeCurrentSession(options) {
-        const messages = this.deps.getMessages();
-        const muxState = this.deps.getMuxState ? await this.deps.getMuxState() : undefined;
-        const runtimeState = this.deps.getRuntimeState ? this.deps.getRuntimeState() : undefined;
-        const hostedSettings = this.deps.getHostedSettings ? this.deps.getHostedSettings() : undefined;
-        const hasRuntimeState = runtimeState !== undefined && (runtimeState.mode !== undefined
+        options.signal?.throwIfAborted();
+        await this.deps.flushToolResponses?.();
+        const muxState = structuredClone(this.muxSnapshot);
+        // Capture transcript and runtime together after raw receipt durability;
+        // optional layout replies never gate required restart state.
+        const messages = structuredClone(this.deps.getMessages());
+        const capturedRuntime = this.deps.getRuntimeState ? structuredClone(this.deps.getRuntimeState()) : undefined;
+        if (capturedRuntime?.diagnostics)
+            this.restoreDiagnostics(capturedRuntime.diagnostics);
+        if (capturedRuntime?.usage)
+            this.restoreUsageSnapshot(capturedRuntime.usage);
+        this.diagnostics = captureSessionDiagnosticSnapshot({ messages, diagnostics: this.diagnostics });
+        const hasDiagnostics = this.diagnostics.events.length > 0 || this.diagnostics.omittedEvents > 0
+            || this.diagnostics.omittedTextBytes > 0;
+        const hasUsage = this.usage.receipts.length > 0 || this.usage.omittedReceipts > 0;
+        const runtimeState = {
+            ...capturedRuntime,
+            authMode: configStore.getResolvedAuthMode(),
+            routerOrigin: configStore.getResolvedAuthMode() === 'direct' ? undefined : configStore.get().zergProxyUrl,
+            ...(hasUsage ? { usage: structuredClone(this.usage) } : {}),
+            ...(hasDiagnostics ? { diagnostics: structuredClone(this.diagnostics) } : {}),
+        };
+        const hostedSettings = this.deps.getHostedSettings ? structuredClone(this.deps.getHostedSettings()) : undefined;
+        const paneSpecs = this.deps.getPaneSpecs ? structuredClone(this.deps.getPaneSpecs()) : undefined;
+        const hasRuntimeState = runtimeState !== undefined && (runtimeState.environment != null
+            || runtimeState.mode !== undefined
             || runtimeState.planFile !== undefined
             || runtimeState.artifactPath !== undefined
             // A live goal counts as runtime state worth persisting on its own; a null
             // goal (serialize() with no goal) does not, so empty sessions stay unwritten.
-            || runtimeState.goal != null);
+            || runtimeState.goal != null
+            || Boolean(runtimeState.evidence?.records.length)
+            || hasDiagnostics
+            || hasUsage);
         if (messages.length === 0 && !muxState && !hasRuntimeState && !options.persistEmpty)
             return;
-        // Filter out ephemeral system messages (startup banners, transient toasts).
-        // See utils/ephemeral.ts — messages are dropped if either (a) they carry
-        // `metadata.ephemeral === true` or (b) they match a legacy content prefix
-        // (for backward compat with already-persisted sessions).
-        const TOOL_RESULT_PERSIST_CAP = 2000;
-        const persistMessages = stripEphemeralMessages(messages).map(m => {
-            if (!m.metadata?.toolResult)
-                return m;
-            // Truncate tool_result content for session persistence — the full
-            // output is redundant (buildRequest truncates old results anyway)
-            // and bloats the session file.
-            try {
-                const results = JSON.parse(m.content);
-                const trimmed = results.map(r => ({
-                    ...r,
-                    content: r.content.length > TOOL_RESULT_PERSIST_CAP
-                        ? r.content.slice(0, TOOL_RESULT_PERSIST_CAP) + '…'
-                        : r.content,
-                }));
-                return { ...m, content: JSON.stringify(trimmed) };
-            }
-            catch {
-                return m;
-            }
-        });
+        const persistMessages = prepareSessionMessages(messages);
         try {
             const model = configStore.getModel();
             const provider = configStore.getProvider();
-            const paneSpecs = this.deps.getPaneSpecs ? this.deps.getPaneSpecs() : undefined;
+            let writtenPath;
             if (this.deps.sessionFile) {
-                await saveSessionToFile(this.deps.sessionFile, this.deps.sessionId, process.cwd(), persistMessages, model, provider, muxState, paneSpecs, runtimeState, hostedSettings);
+                writtenPath = await saveSessionToFile(this.deps.sessionFile, this.deps.sessionId, this.deps.getSessionCwd?.() ?? process.cwd(), persistMessages, model, provider, muxState, paneSpecs, runtimeState, hostedSettings, options.signal);
                 this.deps.debugLog(`[SessionManager.save] Saved ${this.deps.sessionId} to ${this.deps.sessionFile} (${persistMessages.length} messages)`);
             }
             else {
-                await saveSession(this.deps.sessionId, process.cwd(), persistMessages, model, provider, muxState, paneSpecs, runtimeState, hostedSettings);
+                writtenPath = await saveSession(this.deps.sessionId, this.deps.getSessionCwd?.() ?? process.cwd(), persistMessages, model, provider, muxState, paneSpecs, runtimeState, hostedSettings, options.signal);
                 this.deps.debugLog(`[SessionManager.save] Saved ${this.deps.sessionId} with ${persistMessages.length} messages`);
             }
+            if (this.deps.onCheckpoint || persistMessages.some(message => message.attachments?.length)) {
+                const saved = await loadSessionFromFile(writtenPath, false);
+                if (!saved)
+                    throw new Error('Written session checkpoint could not be read back.');
+                // The writer detaches its checkpoint before adopting uploaded images.
+                // Rebind only unchanged live sources after the canonical commit; never
+                // replace messages that arrived or were edited while disk I/O yielded.
+                // Preserve attachment object identity for already captured steering and
+                // queue owners, which may still hold that exact accepted upload.
+                const current = this.deps.getMessages();
+                let rebound = false;
+                for (const message of current) {
+                    const source = persistMessages.find(candidate => candidate.id === message.id
+                        && candidate.role === message.role && candidate.content === message.content);
+                    const committed = saved.messages.find(candidate => candidate.id === message.id);
+                    if (!source || !committed)
+                        continue;
+                    for (const attachment of message.attachments ?? []) {
+                        const captured = source.attachments?.find(candidate => candidate.id === attachment.id);
+                        const durable = committed.attachments?.find(candidate => candidate.id === attachment.id);
+                        if (!captured || !durable?.durable
+                            || JSON.stringify(attachment) !== JSON.stringify(captured)
+                            || JSON.stringify(attachment) === JSON.stringify(durable))
+                            continue;
+                        Object.assign(attachment, durable);
+                        rebound = true;
+                    }
+                }
+                if (rebound)
+                    this.deps.setMessages([...current]);
+                this.deps.onCheckpoint?.(saved);
+            }
         }
         catch (err) {
             const msg = err.message;
@@ -117,11 +263,12 @@ export class SessionManager {
     async saveMuxOnly() {
         if (!this.deps.getMuxState)
             return false;
-        const muxState = await this.deps.getMuxState();
+        await this.refreshMuxState();
+        const muxState = structuredClone(this.muxSnapshot);
         if (!muxState)
             return false;
         try {
-            return await saveMuxStateOnly(this.deps.sessionId, process.cwd(), muxState);
+            return await saveMuxStateOnly(this.deps.sessionId, this.deps.getSessionCwd?.() ?? process.cwd(), muxState);
         }
         catch (err) {
             this.deps.debugLog(`[SessionManager.saveMuxOnly] Error: ${err.message}`);
@@ -153,8 +300,8 @@ export class SessionManager {
         // /context); fall back to the char/4 estimate only before the first API call.
         const realUsed = this.deps.getContextTokens?.() ?? 0;
         const status = realUsed > 0
-            ? contextStatusFromUsed(realUsed, model, this.deps.getContextWindow?.())
-            : getContextStatus(messages, model);
+            ? contextStatusFromUsed(realUsed, model, (configStore.getModelContextWindow(model) !== undefined ? configStore.getModelContextWindow(model) : this.deps.getContextWindow?.()))
+            : getContextStatus(messages, model, configStore.getModelContextWindow(model));
         const threshold = opts?.threshold ?? configStore.getAutoCompactThreshold();
         const targetPercent = configStore.getCompactionTargetPercent();
         const triggerMode = configStore.getCompactionTriggerMode();
@@ -164,7 +311,7 @@ export class SessionManager {
         const decision = resolveAutoCompact({
             used: realUsed > 0 ? realUsed : estimateConversationTokens(messages),
             model,
-            windowOverride: this.deps.getContextWindow?.(),
+            windowOverride: (configStore.getModelContextWindow(model) !== undefined ? configStore.getModelContextWindow(model) : this.deps.getContextWindow?.()),
             thresholdPercent: threshold,
             triggerMode,
             tokenBudget: configStore.getContextTokenBudget(),
@@ -176,13 +323,17 @@ export class SessionManager {
             role: 'system',
             content: `Context ${Math.round(status.percentage)}% full. Auto-compacting...`,
         });
-        const summarizer = this.buildSummarizer();
+        const onUsage = this.deps.getUsageObserver?.();
+        const activityFinished = onUsage?.workerStarted?.();
+        const summarizer = this.buildSummarizer(onUsage);
+        const checkpointSources = this.captureCheckpointSources(messages);
         try {
             const compaction = configStore.getCompactionSettings();
             const result = await compactConversation(messages, model, {
                 method: compaction.method,
                 jev: compaction.jev,
                 summarizer,
+                onUsage,
                 targetPercentage: targetPercent,
                 keepRecentMin: 10,
                 targetTokens: decision.targetTokens,
@@ -198,8 +349,8 @@ export class SessionManager {
                 });
                 return false;
             }
-            this.deps.setMessages(result.messages);
-            const newStatus = getContextStatus(result.messages, model);
+            this.deps.setMessages(this.preserveCheckpointSources(result.messages, checkpointSources));
+            const newStatus = getContextStatus(result.messages, model, configStore.getModelContextWindow(model));
             const verb = describeCompaction(result);
             this.deps.addMessage({
                 role: 'system',
@@ -215,6 +366,9 @@ export class SessionManager {
             this.deps.debugLog(`[SessionManager.maybeAutoCompact] Error: ${err.message}`);
             return false;
         }
+        finally {
+            activityFinished?.();
+        }
     }
     /**
      * Force compaction regardless of threshold (aggressive settings).
@@ -225,16 +379,23 @@ export class SessionManager {
         if (messages.length < 3)
             return false;
         const model = configStore.getModel();
-        const summarizer = this.buildSummarizer();
+        const onUsage = this.deps.getUsageObserver?.();
+        const activityFinished = onUsage?.workerStarted?.();
+        const summarizer = this.buildSummarizer(onUsage);
+        const checkpointSources = this.captureCheckpointSources(messages);
         this.deps.debugLog('[SessionManager.forceCompact] Forcing aggressive compaction');
         try {
-            const result = await compactMessages(messages, model, summarizer, 30, 5);
+            // A provider can reject request structure before its token window fills.
+            // Forced recovery must shrink even when the history already fits 30% of
+            // that window; otherwise the next request repeats the same rejection.
+            const targetTokens = Math.max(1, Math.min(Math.floor((getContextWindowSize(model, configStore.getModelContextWindow(model)) || estimateConversationTokens(messages)) * 0.3), Math.floor(estimateConversationTokens(messages) / 2)));
+            const result = await compactMessages(messages, model, summarizer, 30, 5, targetTokens);
             if (result.removed === 0) {
                 this.deps.debugLog('[SessionManager.forceCompact] Nothing to compact — all messages are recent or system');
                 return false;
             }
-            this.deps.setMessages(result.messages);
-            const newStatus = getContextStatus(result.messages, model);
+            this.deps.setMessages(this.preserveCheckpointSources(result.messages, checkpointSources));
+            const newStatus = getContextStatus(result.messages, model, configStore.getModelContextWindow(model));
             this.deps.debugLog(`[SessionManager.forceCompact] Compacted ${result.removed} msgs: ${formatTokenCount(result.tokensBefore)} → ${formatTokenCount(result.tokensAfter)} (${Math.round(newStatus.percentage)}%)`);
             return true;
         }
@@ -242,6 +403,9 @@ export class SessionManager {
             this.deps.debugLog(`[SessionManager.forceCompact] Error: ${err.message}`);
             return false;
         }
+        finally {
+            activityFinished?.();
+        }
     }
     /**
      * Start periodic auto-save.
@@ -261,15 +425,54 @@ export class SessionManager {
             this.autoSaveTimer = null;
         }
     }
-    /**
-     * Build a summarizer function using the current config's provider/API key.
-     */
-    buildSummarizer() {
+    /** Capture source signatures before awaiting, including IDs of ordinary rows. */
+    captureCheckpointSources(messages) {
+        // A summarizer may evict settled calls. Retain their actual sources first.
+        this.getDiagnostics();
+        return new Map(messages.map(message => [message.id, this.checkpointSourceState(message)]));
+    }
+    checkpointSourceState(message) {
+        return message.toolCalls?.length || message.metadata?.toolResult === true
+            || message.metadata?.toolCheckpoint === true || message.metadata?.taskHandoffCorrection
+            ? JSON.stringify(message) : null;
+    }
+    /** Preserve current invocation and correction sources without restoring old settled history. */
+    preserveCheckpointSources(compacted, before) {
+        const required = new Set((this.deps.getRuntimeState?.().taskHandoffInput?.corrections ?? [])
+            .filter(correction => correction.deliveryState !== 'delivered')
+            .map(correction => correction.sourceMessageId));
+        const live = this.deps.getMessages();
+        const byId = new Map(live.map(message => [message.id, message]));
+        const unresolved = (message) => Boolean(message.toolCalls?.some(call => call.status === 'pending'
+            || call.status === 'running' || (call.result === undefined && call.error === undefined)));
+        const changed = (message) => {
+            const state = this.checkpointSourceState(message);
+            return state !== null && (!before.has(message.id) || before.get(message.id) !== state);
+        };
+        const rebound = compacted.map(message => {
+            const current = byId.get(message.id);
+            if (!current)
+                return message;
+            return unresolved(message) || unresolved(current) || required.has(message.id)
+                || current.metadata?.taskHandoffCorrection || changed(current) ? structuredClone(current) : message;
+        });
+        const retained = new Set(rebound.map(message => message.id));
+        const sources = live.filter(message => {
+            const raw = message.metadata?.taskHandoffCorrection;
+            const pending = raw && typeof raw === 'object' && 'deliveryState' in raw && raw.deliveryState !== 'delivered';
+            return !retained.has(message.id) && (required.has(message.id) || pending || unresolved(message) || changed(message));
+        });
+        // Accepted corrections and original unresolved calls are never replaced
+        // by a summarizer's guess about delivery or completion. Read live state
+        // after the summarizer awaits so newly accepted sources also survive.
+        return [...rebound, ...structuredClone(sources)];
+    }
+    buildSummarizer(onUsage) {
         const provider = configStore.getProvider();
         const apiKey = configStore.getApiKey(provider);
         return async (msgs) => {
             if (apiKey) {
-                return smartSummarizer(msgs, { provider, apiKey });
+                return smartSummarizer(msgs, { provider, apiKey, onUsage });
             }
             return localSummarizer(msgs);
         };

package/dist/app/session_messages.d.ts

@@ -0,0 +1,3 @@
+import type { Message } from '../types.js';
+/** Preserve authored sources while bounding historical tool-result copies. */
+export declare function prepareSessionMessages(messages: readonly Message[]): Message[];

package/dist/app/session_messages.js

@@ -0,0 +1,60 @@
+import { describeDiagnosticTruncation, redactDiagnosticValue } from '../diagnostics/session_export.js';
+import { stripEphemeralMessages } from '../utils/ephemeral.js';
+/** Preserve authored sources while bounding historical tool-result copies. */
+export function prepareSessionMessages(messages) {
+    const TOOL_RESULT_PERSIST_CAP = 2000;
+    // Argument labels can identify credentials echoed without labels in output.
+    // Hash the same redacted source as the diagnostic ledger, before trimming it.
+    const credentialContext = messages.map(message => ({
+        content: message.content, args: message.toolCalls?.map(call => call.args) ?? [],
+    }));
+    return stripEphemeralMessages(messages).map(m => {
+        if (!m.metadata?.toolResult)
+            return m;
+        // Truncate tool_result content for session persistence — the full
+        // output is redundant (buildRequest truncates old results anyway)
+        // and bloats the session file.
+        try {
+            const results = JSON.parse(m.content);
+            const truncations = {};
+            const trimmed = results.map(r => {
+                if (typeof r.content !== 'string' || r.content.length <= TOOL_RESULT_PERSIST_CAP)
+                    return r;
+                const content = r.content.slice(0, TOOL_RESULT_PERSIST_CAP) + '…';
+                const prior = m.metadata?.toolResultTruncation;
+                const previous = prior && typeof prior === 'object'
+                    ? prior[r.tool_use_id] : undefined;
+                if (previous && typeof previous === 'object' && 'originalBytes' in previous && 'retainedBytes' in previous
+                    && 'sha256' in previous && 'reference' in previous && 'availability' in previous
+                    && typeof previous.originalBytes === 'number' && Number.isSafeInteger(previous.originalBytes)
+                    && typeof previous.retainedBytes === 'number' && Number.isSafeInteger(previous.retainedBytes)
+                    && previous.originalBytes >= previous.retainedBytes && previous.retainedBytes >= 0
+                    && typeof previous.sha256 === 'string' && /^[a-f0-9]{64}$/.test(previous.sha256)
+                    && previous.reference === `sha256:${previous.sha256}`
+                    && (previous.availability === 'unavailable' || previous.availability === 'truncated')
+                    && content === r.content) {
+                    // An already trimmed checkpoint carries the original source identity.
+                    truncations[r.tool_use_id] = { originalBytes: previous.originalBytes,
+                        retainedBytes: previous.retainedBytes, sha256: previous.sha256,
+                        reference: previous.reference, availability: previous.availability };
+                }
+                else {
+                    const redacted = redactDiagnosticValue({ credentialContext, fullText: r.content,
+                        retainedText: content }, { propertyNames: path => path.length > 0 });
+                    const { field: _field, ...provenance } = describeDiagnosticTruncation('content', redacted.fullText, redacted.retainedText, 'unavailable');
+                    truncations[r.tool_use_id] = provenance;
+                }
+                return { ...r, content };
+            });
+            const prior = m.metadata?.toolResultTruncation;
+            return { ...m, content: JSON.stringify(trimmed), metadata: { ...m.metadata,
+                    ...(Object.keys(truncations).length ? { toolResultTruncation: {
+                            ...(prior && typeof prior === 'object' ? prior : {}), ...truncations,
+                        } } : {}),
+                } };
+        }
+        catch {
+            return m;
+        }
+    });
+}

package/dist/app/task_scope_router.d.ts

@@ -0,0 +1,20 @@
+import { type AgentFactoryOptions } from '../agent/factory.js';
+import type { UsageReceipt } from '../usage_snapshot.js';
+type ScopeDecision = {
+    route: 'steer' | 'divergent';
+    source: 'classifier' | 'fallback';
+};
+/** Classify a busy submission independently of the live task's backend, tools,
+ * credentials binding, and cancellation. Failure always preserves steering. */
+export declare function classifyBusyInput(options: {
+    backendOptions: AgentFactoryOptions;
+    currentTask: string;
+    inputText: string;
+    hosted: boolean;
+    /** Dedicated routing cancellation only; never pass the parent's run signal. */
+    signal?: AbortSignal;
+    /** One accounting observation per dispatched request, including cancellation.
+     * Published synchronously on cancellation before the host retires its scope. */
+    onUsage?: (receipt: UsageReceipt) => void;
+}): Promise<ScopeDecision>;
+export {};