@sema-agent/core 7.52.0 → 7.54.0

package/dist/core/auto-compaction.d.ts

@@ -1,11 +1,12 @@
 import { type AgentMessage, type CompactionSettings, type Session, type ThinkingLevel } from "../internal/harness.js";
-import type { Message, Model, Tool } from "../internal/llm.js";
+import { type Message, type Model, type Tool } from "../internal/llm.js";
 import type { ContextWindowOverlay } from "./context-settings.js";
 import type { PostCompactContext, PreCompactContext, PreCompactResult } from "./hooks.js";
 import type { TraceEvent } from "./trace.js";
 import type { Brain } from "./types.js";
 import type { TaskEvent, TaskEventIdentity } from "./task-event.js";
 import type { CompactionEffect } from "./frame-settlement.js";
+import type { MintedAttachmentFrame } from "./user-attachment.js";
 /**
  * Default summarization focus, applied when a task does not provide `compaction.instructions`.
  * Addresses the common fidelity failure where summaries drop specific facts.
@@ -101,6 +102,32 @@ export interface CompactionForkContext {
      *  eligibility gate refuses a snapshot from a different model (see the engine-side twin's doc). */
     modelId?: string;
 }
+/**
+ * What a compaction pass reports at the moment it commits ({@link MaybeCompactOptions.onStarted}) — and the
+ * whole content of its `compaction_started` wire frame. `pass` is minted HERE, by the one function every lane
+ * runs, so no lane can number its own passes; the frame that ends the pass carries the same value.
+ */
+export interface CompactionPassStart {
+    readonly pass: string;
+    /** The trigger this pass runs under — the value it hands the `preCompact` hook. */
+    readonly trigger: "auto" | "manual" | "forced";
+    /** Engine clock, epoch ms, at the commit. */
+    readonly startedAt: number;
+}
+/** What a landed compaction asks its restore for ({@link MaybeCompactOptions.workingFileAttachments}). */
+export interface CompactionRestoreAsk {
+    /** The files to re-read, most recent first — already without the ones the context the summary leaves still shows. */
+    readonly candidates: readonly string[];
+    readonly maxFiles: number;
+    /** What one file may deliver, in its own text (before the Read's line numbers — the unit `maxCharsPerFile` counts),
+     *  and all of them together, in the file contents the frames send (line numbers included — the unit of the
+     *  window's share); an image costs the engine estimate's fixed weight × `charsPerToken` in both. */
+    readonly perFileChars: number;
+    readonly totalChars: number;
+    readonly charsPerToken: number;
+    /** The reads the context the summary leaves still shows (canonical keys) — the restore dedups against them. */
+    readonly preserveKeys: readonly string[];
+}
 export interface MaybeCompactOptions {
     /** Disclosure channel for CONTAINED host-callback failures in this scope (the RB-463
      *  isolation primitive's bounded first-failure per site). Absent ⇒ failures are counted only. */
@@ -267,31 +294,26 @@ export interface MaybeCompactOptions {
      */
     forceUnderThreshold?: boolean;
     /**
-     * Working-file attachments (LONGRUN-2, CC-compact parity review 2026-06-12): after a successful
-     * summary, re-read up to `maxFiles` of the files the summarized region MODIFIED (from
-     * CompactionDetails.modifiedFiles) and append their current on-disk contents to the summary text.
-     * Why: LONGRUN-2 measured the model spending ≈2.3 extra read calls per compaction re-fetching
-     * files it had just lost — each one a full request round-trip at post-compaction context size.
-     * CC ships the same idea ("attachments", ≤5 files × ~5k tokens). Bounded: per-file char cap plus
-     * a total cap that self-scales to ~15% of the model window, so small windows never drown in
-     * attachments; the §25.2 freedTokens measurement naturally accounts for the added mass (the
-     * anti-thrash floor stays truthful). Reader failures skip the file (best-effort, never fails the
-     * compaction). Absent (default) = current behavior, paths-only.
-     * Pick order (design/71 P2-① resolved the LONGRUN-2b limitation): `maxFiles` picks the most
-     * RECENTLY touched files first (`CompactionDetails.modifiedFilesByRecency`, recency threaded
-     * through the engine fileOps accumulator); alphabetical `modifiedFiles` remains the fallback for
-     * details persisted before the field existed.
+     * The post-compaction restore: after a summary lands, re-read up to `maxFiles`
+     * of the files the conversation had read (or, without read tracking, modified) that the context the summary leaves
+     * no longer shows, and append each as an attachment frame — its own engine-note message after the compaction entry
+     * (summary, kept tail, restored files: the reference's post-compact order, cli296.js:249517 `hookResults`). Why: without it the model spends ≈2.3 extra read round-trips per
+     * compaction re-fetching what it just lost (LONGRUN-2). Bounded: a per-file cap in the file's own characters and a
+     * total, in the file contents the frames send (line numbers included), that self-scales to ~15% of the window; a
+     * file over either is a frame that names it and says it is too large, never part of its contents. The post measurement counts the frames, so the anti-thrash floor stays truthful. Absent ⇒ no restore.
+     * Pick order: most recently READ first (`recentlyReadFiles`), else most recently modified
+     * (`CompactionDetails.modifiedFilesByRecency`), else the alphabetical `modifiedFiles` of older details.
      */
     workingFileAttachments?: {
-        /** Read a task workspace file; null/throw = skip it. Wired by the Runner from the task's ExecutionEnv. */
-        readFile: (path: string) => Promise<string | null | {
-            withheld: {
-                pattern: string;
-            };
-        }>;
-        /** Max modified files to attach. Default 3. */
+        /** Re-read the candidates and mint their frames — the engine's one read of a file for the model, deduplicated against
+         *  the context the summary leaves (`preserveKeys` = the reads that context still shows). Side-effect free: each frame
+         *  carries the commit its delivery owes, run here once the frame is in the transcript. Wired by the Runner. */
+        restore: (ask: CompactionRestoreAsk) => Promise<ReadonlyArray<MintedAttachmentFrame>>;
+        /** A minted restore frame the transcript would not take (not delivered, nothing committed) — the operator's line. */
+        undelivered?: (label: string, reason: string) => void;
+        /** Max files to restore. Default 3. */
         maxFiles?: number;
-        /** Per-file char cap (≈4 chars/token). Default 16_000 (~4k tokens). */
+        /** Per-file cap in the file's own characters (≈4 chars/token). Default 16_000 (~4k tokens). */
         maxCharsPerFile?: number;
         /**
          * CC-parity selection set: the files the task has READ, most recent
@@ -313,9 +335,9 @@ export interface MaybeCompactOptions {
         instructionSourcePaths?: ReadonlyArray<string>;
         /**
          * `recentlyReadFiles` yields CANONICAL keys (resolveKey
-         * output — the same coordinate `ReadFileState` is keyed in), but `instructionSourcePaths` and the
-         * kept-tail scan inside `maybeCompact` (which reads raw tool-call arguments via
-         * `extractFileOpsFromMessage`) do NOT share that coordinate — a model-typed relative path and its
+         * output — the same coordinate `ReadFileState` is keyed in, and the one an attachment frame's recorded
+         * read carries), but `instructionSourcePaths` and the kept tail's Read tool calls (raw model-typed
+         * arguments) do NOT share that coordinate — a model-typed relative path and its
          * canonical form are different strings, so a plain `Set.has()` between them silently never matches
          * even for the identical file. Optional callback (present exactly when there's a containment root
          * to resolve against — i.e. hands enabled) that canonicalizes a raw path the SAME way the hands
@@ -340,29 +362,18 @@ export interface MaybeCompactOptions {
         isDedupStubResult?: (resultText: string) => boolean;
     };
     /**
-     * Fires ONCE per LANDED compaction (after `appendCompaction` committed the new baseline), with the
-     * files that were attached WHOLE (untruncated) into the summary. The Runner wires this to the read-state
-     * invalidation (`applyContextShrinkToReadFileState`): the summary just replaced the history the read-dedup
-     * stubs point at, so stale entries must drop and the re-attached content re-registers. Kept OUTSIDE
-     * `workingFileAttachments` deliberately — the invalidation is owed even when attachments are disabled
-     * (an empty array then). Best-effort: a throwing callback must not fail the landed compaction.
+     * Fires ONCE per LANDED compaction (after `appendCompaction` committed the new baseline and the restore frames were
+     * appended), immediately followed by the delivered restore frames' commits — the read state's clear and the restore's
+     * entries land together, after the baseline; a compaction that does not land touches neither. The Runner wires this to
+     * the read-state invalidation (`applyContextShrinkToReadFileState`): the summary just replaced the history the
+     * read-dedup stubs point at. Kept OUTSIDE `workingFileAttachments` deliberately — the invalidation is owed even when
+     * the restore is off. Best-effort: a throwing callback must not fail the landed compaction.
      *
-     * `preserveReadState`:
-     * canonical-coordinate paths (same shape as `normalizePath`'s output) whose read-state entry must
-     * survive the compaction's clear even though they are NOT in `attachedComplete` — every file
-     * `maybeCompact` deliberately skipped re-attaching, for EITHER exclusion reason (kept-tail-visible,
-     * or matches a declared instruction source). Without this the read-state clear (see
-     * `applyContextShrinkToReadFileState`) would wipe them anyway, defeating both the read-before-edit gate
-     * and the next read's dedup for exactly the files this optimization was supposed to leave untouched.
-     * (The instruction-source half of this was missing in an earlier revision: `instructionSources` and
-     * `seededFiles` are independent `ProjectMemoryLoad` fields — a path can be declared in the former
-     * without ever being seeded via the latter, so an instruction-excluded file the model explicitly Read
-     * has a live, non-seeded entry that needs the SAME preservation as a kept-tail one.)
+     * `preserveReadState`: canonical-coordinate paths whose entry survives the clear — every file the context the summary
+     * leaves still shows (a kept-tail read or attachment frame) or that a declared instruction source re-seeds; the restore
+     * deduplicates against the same set.
      */
-    onApplied?: (attachedComplete: ReadonlyArray<{
-        path: string;
-        content: string;
-    }>, preserveReadState?: ReadonlyArray<string>) => void;
+    onApplied?: (preserveReadState: ReadonlyArray<string>) => void;
     /**
      * #1036 — THE COMMIT-BEAT EFFECT SINK: what this compaction did to the transcript, reported
      * once, right after the `appendCompaction` that landed it. `summarizedEntryIds` = every entry id
@@ -432,7 +443,7 @@ export interface MaybeCompactOptions {
      * Inputs:
      *  - `messagesToSummarize`: the message range that would be summarized this boundary.
      *  - `previousSummary`: the prior compaction's summary (present on the UPDATE/iterative-merge path).
-     *  - `modifiedFiles`: files the summarized range modified, newest-first (same source the working-file
+     *  - `modifiedFiles`: files the summarized range modified, newest-first (same source the restore's
      *    attachments use), so a provider can decide whether the reused summary is still representative.
      */
     summaryProvider?: (input: {
@@ -482,6 +493,17 @@ export interface MaybeCompactOptions {
      * not optional there, so a preCompact `block` is IGNORED on "forced").
      */
     trigger?: "auto" | "manual" | "forced";
+    /**
+     * The pass has COMMITTED: the trigger gate passed, a valid cut point exists and no `preCompact` handler
+     * blocked it, and nothing has yet consulted the summary provider or called the model. Fired exactly once per
+     * pass — a retry inside the summary call is the same pass — and never for a pass that ends before this point
+     * (under threshold, held under the floor, disabled, nothing to compact, blocked, or cut by its own signal while
+     * the `preCompact` hook ran). A pass that fired it ends
+     * in `compacted: true` or a throw, so the caller that put a frame on the wire here owes the matching end.
+     * Observe-only: a throw — or the rejection of an `async` callback, which this seat does not await — is
+     * contained and never reaches the pass.
+     */
+    onStarted?: (start: CompactionPassStart) => void;
     /**
      * design/134 (CC PreCompact parity) — fired AFTER the trigger gate and a CONFIRMED valid cut point
      * (so every invocation corresponds to a compaction that would actually happen), BEFORE the
@@ -553,6 +575,10 @@ export declare function maybeCompact(opts: MaybeCompactOptions): Promise<{
      *  nothing to do looked identical to one that never wanted to run; the caller's outcome event
      *  (`compaction_outcome{outcome:"noop"}`) reads this flag. */
     noop?: true;
+    /** The id of the pass this result concludes — the value {@link MaybeCompactOptions.onStarted} was handed.
+     *  Set exactly when `compacted` is true: every other return of this function ends before the pass commits,
+     *  and a pass that commits and does not land THROWS (the caller learned the id from the start callback). */
+    pass?: string;
     tokensBefore?: number;
     /** The §25.2 STRUCTURAL pre/post delta in ONE coordinate — the only subtractable quantity here.
      *  Absent ⇒ the post measurement failed and no delta was taken. */
@@ -594,7 +620,7 @@ export declare function maybeCompact(opts: MaybeCompactOptions): Promise<{
      *  consult → clamp dry run + 门A/门B gating (everything before the summary call). `summaryMs` = the
      *  summary LLM leg (`compact()`: serialization → clamp → completion, incl. any PTL retries) — ABSENT
      *  on a provider-reuse pass (no LLM call happened; its provider consult time sits in `prepareMs`).
-     *  `persistMs` = working-file attachments → session rewrite (`appendCompaction`) → post measurement →
+     *  `persistMs` = restore reads → session rewrite (`appendCompaction`) → restore frames → post measurement →
      *  observers. The phases tile the pass exactly: prepareMs + (summaryMs ?? 0) + persistMs ===
      *  durationMs. `ptlRetries` = reactive prompt-too-long retries burned inside this pass's summary
      *  call(s) (both split-turn legs accumulate into the one counter; 0 on provider reuse). Set only when
@@ -669,6 +695,8 @@ export declare function maybeCompact(opts: MaybeCompactOptions): Promise<{
 /** What a landed compaction hands the wire frame. Structural, so both the full `maybeCompact` result
  *  and the settle lane's narrower `EndOfTaskCompaction` satisfy it without either importing the other. */
 export interface CompactedFrameSource {
+    /** The pass this landing concludes (see {@link MaybeCompactOptions.onStarted}). */
+    pass?: string;
     tokensBefore?: number;
     freedTokens?: number;
     postTriggerTokens?: number;
@@ -703,6 +731,34 @@ export interface CompactedFrameSource {
 export declare function mintCompactedEvent(comp: CompactedFrameSource, trigger: "auto" | "manual" | "forced", identity: TaskEventIdentity): Extract<TaskEvent, {
     type: "compacted";
 }>;
+/**
+ * THE mint of the `compaction_started` wire frame — the opening half of the pair whose closing half is the
+ * `compacted` frame above (or a `compaction_outcome` that carries the same `pass`). One function, three
+ * lanes, as the landing's: the frame is the start report itself plus the identity envelope, so a lane that
+ * wants to announce a pass can only announce the one `maybeCompact` committed.
+ */
+export declare function mintCompactionStartedEvent(start: CompactionPassStart, identity: TaskEventIdentity): Extract<TaskEvent, {
+    type: "compaction_started";
+}>;
+/**
+ * One compaction pass's account on the wire: the `onStarted` seat to hand `maybeCompact`, and the id the frame
+ * that ENDS the pass must carry. A lane makes one per pass, hands `onStarted` to the pass, and spreads
+ * {@link CompactionPassReport.end} into every `compaction_outcome` the pass can end with after it committed — a
+ * pass that threw before it committed leaves it empty, which is exactly "no start was announced, so no `pass`
+ * names it". The landing needs no spread: `maybeCompact` returns the id and `mintCompactedEvent` reads it.
+ */
+export interface CompactionPassReport {
+    readonly onStarted: (start: CompactionPassStart) => void;
+    /** The announced pass's id; `undefined` until a start went on the wire. */
+    readonly pass: string | undefined;
+    /** `{ pass }` once a start was announced, `{}` before — for the frame that ends the pass. */
+    readonly end: {
+        pass?: string;
+    };
+}
+export declare function compactionPassReport(sink: {
+    push(event: TaskEvent): void;
+}, ident: () => TaskEventIdentity): CompactionPassReport;
 /**
  * How many cross-session message frames the summarized prefix held: the engine-note user messages
  * whose text is the drain's `<cross-session-message …>` envelope, before the kept tail begins. The
@@ -737,7 +793,7 @@ export declare function countSummarizedCrossSessionMessages(branch: ReadonlyArra
  *   5. (COMPACTION-LIVE-AUDIT D-1, evaluated BEFORE rule 3) a TRIM-FORCED landing with
  *      `freedTokens ≤ 0` → negative-yield: BACKOFF ON. The trim layer deceives the usage-anchored
  *      estimate down into the sawtooth trough (live: est 18807 on a ~55k session), the forced pass
- *      finds little compressible history, and summary + working-file attachments make the transcript
+ *      finds little compressible history, and summary + restore frames make the transcript
  *      LARGER (live: 18807→44609, 12679→35214). `freedTokens` is the structural pre/post delta
  *      (clamped ≥0, so ≤0 means "freed nothing") — orthogonal to rule 2/3's threshold test, which
  *      misses this shape because the bloated post (44609) can still sit UNDER the threshold (44800),

package/dist/core/auto-compaction.js

@@ -1,11 +1,13 @@
 import { CROSS_SESSION_MESSAGE_TAG } from "../agents/cross-session-envelope.js";
-import { DEFAULT_CHARS_PER_TOKEN, DEFAULT_CLAMP_TOLERANCE, DEFAULT_COMPACTION_SETTINGS, CompactionError, compact, computeFileLists, dryRunSummarizationClamp, estimateContextTokens, estimateTokens, formatFileOperations, formatPersistedOutputRefs, prepareCompaction, shouldCompact, } from "../internal/harness.js";
+import { DEFAULT_CHARS_PER_TOKEN, DEFAULT_CLAMP_TOLERANCE, DEFAULT_COMPACTION_SETTINGS, CompactionError, compact, computeFileLists, dryRunSummarizationClamp, estimateContextTokens, estimateTokens, formatFileOperations, formatPersistedOutputRefs, prepareCompaction, shouldCompact, uuidv7, } from "../internal/harness.js";
 import { fileArgPath } from "./tool-registry.js";
+import { userAttachmentOf } from "../internal/llm.js";
 import { contextEditFrontier, resolveTriggerWindow } from "./context-edit.js";
 import { selectCompactionEpoch } from "../prompt-assembly/epoch.js";
 import { brainToRuntime } from "./runtime.js";
 import { defuseFenceMarkers, sanitizeUntrustedText } from "./untrusted-text.js";
-import { createSafeNotifier } from "./safe-notify.js";
+import { createSafeNotifier, observeThenableRejection } from "./safe-notify.js";
+import { thrownText } from "./thrown-value.js";
 export const DEFAULT_COMPACTION_INSTRUCTIONS = "Preserve verbatim every code, identifier, name, number, file path, error message, credential " +
     "reference, and explicit user instruction or decision mentioned anywhere in the conversation. " +
     "When in doubt, keep the specific detail rather than generalizing it.";
@@ -18,10 +20,6 @@ export function sanitizeCompactionInstructions(text) {
         ? cps.slice(0, COMPACTION_INSTRUCTIONS_MAX_CHARS).join("")
         : defused;
 }
-const WORKING_FILE_BREAKOUT_TAGS = ["working-file", "summary"];
-function escapeWorkingFilePathAttr(path) {
-    return path.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/[\r\n]+/g, " ");
-}
 const COMPACTION_MANUAL_CANCEL_FLAG = "semaCompactionManualCancel";
 export function isCompactionManualCancel(err) {
     return (typeof err === "object" && err !== null && err[COMPACTION_MANUAL_CANCEL_FLAG] === true);
@@ -152,6 +150,12 @@ export async function maybeCompact(opts) {
             ? `${specInstructions}\n\n${hookSanitized}`
             : hookSanitized
         : specInstructions;
+    const signalAtCommit = opts.signal;
+    if (signalAtCommit?.aborted === true) {
+        throw Object.assign(new CompactionError("aborted", "compaction cancelled before the pass committed — nothing was summarized or persisted"), opts.manualCancelSignal?.aborted === true ? { [COMPACTION_MANUAL_CANCEL_FLAG]: true } : {});
+    }
+    const pass = uuidv7();
+    notifier.notify(() => observeThenableRejection(opts.onStarted?.({ pass, trigger, startedAt: Date.now() }), notifier, "compaction.onStarted"), "compaction.onStarted");
     const maxReuse = opts.maxConsecutiveProviderReuse ?? 3;
     const forceRealSummary = maxReuse > 0 && (opts.consecutiveProviderReuse ?? 0) >= maxReuse;
     let providerSummary;
@@ -330,10 +334,15 @@ export async function maybeCompact(opts) {
         details = res.value.details;
     }
     const persistStartAt = summaryEndAt ?? Date.now();
-    let summaryWithAttachments = summary;
-    const attachedFiles = [];
-    const attachedComplete = [];
+    let restoreFrames = [];
     const att = opts.workingFileAttachments;
+    const undelivered = (label, reason) => {
+        try {
+            att?.undelivered?.(label, reason);
+        }
+        catch {
+        }
+    };
     const recentlyRead = att?.recentlyReadFiles?.() ?? [];
     const rawCandidateFiles = recentlyRead.length > 0 ? recentlyRead : (details?.modifiedFilesByRecency ?? details?.modifiedFiles);
     const maxFilesForSelection = Math.max(1, att?.maxFiles ?? 3);
@@ -346,6 +355,9 @@ export async function maybeCompact(opts) {
                 const dedupStub = att?.isDedupStubResult;
                 for (let i = firstKeptIdx; i < branch.length; i++) {
                     const entry = branch[i];
+                    const frame = entry?.type === "message" ? userAttachmentOf(entry.message) : undefined;
+                    if (frame?.observation !== undefined && (frame.outcome === "attached" || frame.outcome === "partial"))
+                        keptTailReadPathsRaw.add(frame.observation.key);
                     if (entry.type !== "message" || entry.message.role !== "assistant")
                         continue;
                     const msg = entry.message;
@@ -426,44 +438,13 @@ export async function maybeCompact(opts) {
         const maxFiles = maxFilesForSelection;
         const perFileCap = Math.max(200, att.maxCharsPerFile ?? 16_000);
         const windowShareChars = windowKnown ? Math.floor(window * 0.15) * cpt : Number.POSITIVE_INFINITY;
-        let remaining = Math.min(maxFiles * perFileCap, windowShareChars);
-        const blocks = [];
-        for (const path of candidateFiles.slice(0, maxFiles)) {
-            if (remaining <= 0)
-                break;
-            let content = null;
-            let withheldPattern;
-            try {
-                const r = await att.readFile(path);
-                if (typeof r === "string")
-                    content = r;
-                else if (r !== null && typeof r === "object")
-                    withheldPattern = r.withheld.pattern;
-            }
-            catch {
-                content = null;
-            }
-            if (withheldPattern !== undefined) {
-                blocks.push(`<working-file path="${escapeWorkingFilePathAttr(path)}" withheld="content withheld: matches the sensitive-path read deny list (pattern ${escapeWorkingFilePathAttr(withheldPattern)})"/>`);
-                continue;
-            }
-            if (content === null)
-                continue;
-            const cap = Math.min(perFileCap, remaining);
-            const wasClipped = content.length > cap;
-            const clipped = wasClipped
-                ? `${content.slice(0, cap)}\n[... ${content.length - cap} more characters truncated — read the file for the rest]`
-                : content;
-            remaining -= clipped.length;
-            blocks.push(`<working-file path="${escapeWorkingFilePathAttr(path)}">\n${sanitizeUntrustedText(clipped, WORKING_FILE_BREAKOUT_TAGS)}\n</working-file>`);
-            attachedFiles.push({ path, chars: Math.min(content.length, cap), truncated: wasClipped });
-            if (!wasClipped)
-                attachedComplete.push({ path, content });
-        }
-        if (blocks.length > 0) {
-            summaryWithAttachments +=
-                "\n\nCurrent on-disk contents of files touched in the summarized work (re-read at compaction time — trust these over any excerpts in the summary above):\n" +
-                    blocks.join("\n");
+        try {
+            restoreFrames = await att.restore({ candidates: candidateFiles, maxFiles, perFileChars: perFileCap, totalChars: Math.min(maxFiles * perFileCap, windowShareChars), charsPerToken: cpt, preserveKeys: excludedReadStatePreserveKeys });
+        }
+        catch (err) {
+            restoreFrames = [];
+            for (const path of candidateFiles.slice(0, maxFiles))
+                undelivered(path, `the restore failed: ${thrownText(err)}`);
         }
     }
     let preChars = 0;
@@ -478,7 +459,7 @@ export async function maybeCompact(opts) {
     if (opts.signal?.aborted === true) {
         throw Object.assign(new Error("compaction cancelled before commit — the abort signal fired during the summary call; nothing was persisted"), opts.manualCancelSignal?.aborted === true ? { [COMPACTION_MANUAL_CANCEL_FLAG]: true } : {});
     }
-    await opts.session.appendCompaction(summaryWithAttachments, firstKeptEntryId, summaryTokensBefore, {
+    await opts.session.appendCompaction(summary, firstKeptEntryId, summaryTokensBefore, {
         ...(details ?? {}),
         ...(restatedEpoch !== undefined ? { promptEpoch: restatedEpoch } : {}),
         ...(restatedListings !== undefined ? { announcedListings: restatedListings } : {}),
@@ -496,6 +477,26 @@ export async function maybeCompact(opts) {
         catch {
         }
     }
+    const delivered = [];
+    for (const f of restoreFrames) {
+        try {
+            await opts.session.appendMessage({ role: "user", content: [...f.seed.content], timestamp: Date.now(), provenance: "engine-note", attachment: f.seed.attachment });
+            delivered.push(f);
+        }
+        catch (err) {
+            for (const g of restoreFrames.slice(delivered.length))
+                undelivered(g.seed.attachment.label, `the transcript did not take the restore frame: ${thrownText(err)}`);
+            break;
+        }
+    }
+    try {
+        opts.onApplied?.(excludedReadStatePreserveKeys);
+        for (const f of delivered)
+            f.commit?.();
+    }
+    catch {
+    }
+    const attachedFiles = delivered.flatMap(({ seed: { attachment: a } }) => ((a.outcome === "attached" || a.outcome === "partial") && a.dataBlocks.end > a.dataBlocks.start ? [{ path: a.label, chars: a.chars, truncated: a.truncated }] : []));
     if (opts.gitRestate !== undefined) {
         try {
             await opts.gitRestate.land();
@@ -510,11 +511,6 @@ export async function maybeCompact(opts) {
         catch {
         }
     }
-    try {
-        opts.onApplied?.(attachedComplete, excludedReadStatePreserveKeys);
-    }
-    catch {
-    }
     if (ca !== undefined && restatedEpoch !== undefined) {
         try {
             ca.apply(restatedEpoch.identity);
@@ -555,6 +551,7 @@ export async function maybeCompact(opts) {
     return {
         contextUsage,
         compacted: true,
+        pass,
         tokensBefore: summaryTokensBefore,
         freedTokens,
         triggerTokens: tokens,
@@ -585,6 +582,7 @@ export function mintCompactedEvent(comp, trigger, identity) {
     return {
         type: "compacted",
         trigger,
+        ...(comp.pass !== undefined ? { pass: comp.pass } : {}),
         tokensBefore: comp.tokensBefore ?? 0,
         ...(comp.freedTokens !== undefined ? { freedTokens: comp.freedTokens } : {}),
         ...(comp.postTriggerTokens !== undefined ? { tokensAfter: comp.postTriggerTokens } : {}),
@@ -601,6 +599,24 @@ export function mintCompactedEvent(comp, trigger, identity) {
         ...identity,
     };
 }
+export function mintCompactionStartedEvent(start, identity) {
+    return { type: "compaction_started", trigger: start.trigger, pass: start.pass, startedAt: start.startedAt, ...identity };
+}
+export function compactionPassReport(sink, ident) {
+    let pass;
+    return {
+        onStarted: (start) => {
+            sink.push(mintCompactionStartedEvent(start, ident()));
+            pass = start.pass;
+        },
+        get pass() {
+            return pass;
+        },
+        get end() {
+            return pass !== undefined ? { pass } : {};
+        },
+    };
+}
 export function countSummarizedCrossSessionMessages(branch, firstKeptEntryId) {
     const firstKeptIdx = branch.findIndex((e) => e.id === firstKeptEntryId);
     const summarized = firstKeptIdx >= 0 ? branch.slice(0, firstKeptIdx) : branch;

package/dist/core/auto-mode-prompt.d.ts

@@ -47,14 +47,16 @@ export interface DerivedDenyRule {
  * The effective READ-deny table as the classifier's deny lines — one line per row, the row's reach in the
  * engine's own `Read(...)` path-rule grammar.
  *
- * A read-deny row is a run of path SEGMENTS matched anywhere in a path — the entry itself and everything under
+ * An UNANCHORED read-deny row is a run of path SEGMENTS matched anywhere in a path — the entry itself and everything under
  * it — and its `*` never crosses a `/` (read-deny.ts: `.ssh` refuses `~/.ssh/id_rsa` and `/srv/x/.ssh/config`
  * alike; a `**` segment matches exactly one segment). The rule grammar reaches the path a pattern names and
  * everything under it, so the line is `//**` + `/` + the row with every run of stars written `*` (one segment,
  * as in the row): `.ssh` ⇒ `Read(//**\/.ssh)`, `**\/secrets/**` ⇒ `Read(//**\/*\/secrets/*)`, `*` (every
  * path) ⇒ `Read(//**\/*)`. A row that names no segment at all (`""`, `/`) is not stated. A HOME-ANCHORED row
  * (`~/<run>`, read-deny.ts `READ_DENY_HOME_WORD`) is the rule grammar's home word with the same reach:
- * `~/.sema/settings.json` ⇒ `Read(~/.sema/settings.json)`.
+ * `~/.sema/settings.json` ⇒ `Read(~/.sema/settings.json)`; a ROOTED row (`/etc/shadow`, anchored at the filesystem
+ * root) is the rule grammar's absolute path: `Read(//etc/shadow)`. Which of the three a row is, is the one judge's
+ * answer (`readDenyRowAnchor`), asked here as everywhere a row is read.
  *
  * The text of a row can come from a task (a spawned task's author included) and it is spliced into a trusted
  * prompt, so a row is stated as a rule and nothing else: every character the grammar or the prompt must not

package/dist/core/auto-mode-prompt.js

@@ -1,7 +1,7 @@
 import { AUTO_MODE_DEFAULT_WINDOW_MAX_CHARS, AUTO_MODE_DEFAULT_WINDOW_MAX_ENTRIES, AUTO_MODE_DEFAULTS_SENTINEL } from "./auto-mode-defaults.js";
 import { AUTO_MODE_BASE_PROMPT, AUTO_MODE_PERMISSIONS_EXTERNAL } from "./auto-mode-prompt-assets.js";
 import { cutEnginePrefix, cutEngineSegments, flattenableUserText } from "./untrusted-text.js";
-import { readDenyPatternRun } from "../tools/fs/read-deny.js";
+import { readDenyPatternRun, readDenyRowAnchor } from "../tools/fs/read-deny.js";
 import { renderContentBlock, renderUserAttachmentView, userAttachmentOf } from "../internal/llm.js";
 export { AUTO_MODE_DEFAULTS_SENTINEL } from "./auto-mode-defaults.js";
 function mergeRuleSection(user, defaultsInner) {
@@ -36,12 +36,13 @@ export function readDenyClassifierRules(entries, rules = []) {
         out.push(line);
     };
     for (const { pattern, caseSensitive } of entries) {
-        const { homeAnchored, run } = readDenyPatternRun(pattern);
+        const { run } = readDenyPatternRun(pattern);
         const segments = run.split("/").filter((seg) => seg.length > 0);
         if (segments.length === 0)
             continue;
         const stated = statedPattern(segments.join("/"));
-        push({ rule: homeAnchored ? `Read(~/${stated})` : `Read(//**/${stated})`, ...(caseSensitive !== true && /[A-Za-z]/.test(stated) ? { anyCase: true } : {}) });
+        const anchor = readDenyRowAnchor(pattern);
+        push({ rule: anchor === "home" ? `Read(~/${stated})` : anchor === "root" ? `Read(//${stated})` : `Read(//**/${stated})`, ...(caseSensitive !== true && /[A-Za-z]/.test(stated) ? { anyCase: true } : {}) });
     }
     for (const { tool, pattern } of rules) {
         if (!/^[A-Za-z][A-Za-z0-9_]*$/.test(tool) || pattern.length === 0)

package/dist/core/canonical-json.d.ts

@@ -1,3 +1,4 @@
+import { type ReceiptFault } from "./mods/kernel/receive.js";
 /**
  * design/80 D-1 §2 (slice 1a.2) — the engine-only **vetted canonical serializer** used to mint a stable,
  * opaque {@link boundInputHashOf | boundInputHash} over a pending tool call's arguments.
@@ -60,3 +61,71 @@ export declare const UNCANONICALIZABLE = "<uncanonicalizable>";
  * The hex digest is fixed-length and opaque — exactly what the operator sees / the D-G signer signs.
  */
 export declare function boundInputHashOf(value: unknown): string;
+/**
+ * The {@link boundInputHashOf} digest of `value` when an approval can be bound to it ({@link bindableValueOf}), else `undefined` —
+ * the digest a license is compared by, one only those bytes have. Over the bindable domain the canonical form is exact (no
+ * sentinel token stands for part of it), so the digest is the bytes; outside it there is none to give.
+ */
+export declare function exactBoundInputHashOf(value: unknown): string | undefined;
+/**
+ * Why a value is outside the bindable domain: its top is not the payload's shape, a refusal of the receipt it is read by, or one of
+ * JSON's own five — a number that is not finite, a hole in a list, a named member on a list, an `undefined` list element, one
+ * object met twice.
+ */
+export type BindingFault = ReceiptFault | {
+    readonly kind: "not-container" | "not-finite" | "hole" | "list-member" | "undefined-element" | "shared";
+    readonly path: readonly string[];
+};
+/**
+ * THE judge of the BINDABLE domain — the values an approval can be bound to, and so the only values with an exact digest: plain
+ * JSON data (records, dense lists, strings, finite numbers, booleans, `null`; a record member that is `undefined` is kept as it
+ * is, as absent from JSON) under a top of the payload's own shape (`top`: a call's arguments are a RECORD — the default, and the
+ * only shape an exact digest is taken of; a question's answers are a LIST), a tree (no object met twice), at most 256 levels of
+ * containers. Read by the engine's one receipt of a caller's value in {@link BINDING_RECEIPT} (nothing of the caller's runs: a
+ * getter, a hidden or symbol-keyed member, a Proxy, a function, a symbol, a bigint, a Map / Set / Date / binary or any other kind
+ * of object, a cycle, nesting past the levels — each refused), then JSON's own five on the receipt's frozen copy. Ok ⇒ that copy.
+ */
+export declare function bindableValueOf(value: unknown, top?: BindingTop): {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly fault: BindingFault;
+};
+/** The top a bound payload has: a call's arguments are a record, a question's answers a list. */
+export type BindingTop = "record" | "list";
+/** THE capture of a caller-supplied payload the engine persists and later compares (a durable decide's edit — a record —, a
+ *  question's answers — a list): the judge's receipt ({@link bindableValueOf}) kept in the form a durable store's JSON round trip
+ *  hands back ({@link jsonFormOf}). */
+export declare function capturedJsonOf(value: unknown, top?: BindingTop): {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly fault: BindingFault;
+};
+/** One clause naming a binding fault, its path rooted at `args` (`value` is what the judge was given: for a value that is not
+ *  data, its `typeof` is read at the fault's place). The text holds the value's own member names: contain it to show it. */
+export declare function describeBindingFault(value: unknown, fault: BindingFault): string;
+/**
+ * Recursion-depth ceiling. Makes {@link encode} TOTAL against the two ways a naive recursive walk throws:
+ * a CIRCULAR reference (infinite recursion → `Maximum call stack size`) and pathological DEEP nesting (a
+ * RangeError before the JS stack limit). At/below this depth a deterministic sentinel is emitted instead of
+ * recursing — so {@link boundInputHashOf} can never throw. This is load-bearing (MAJOR-4): digests are read after a remote
+ * VM is paused (the park's target mint compares one), where a throw would skip the unpause compensation and leak the VM.
+ * 256 is far below the engine's stack limit yet far deeper than any real tool-arg payload. It is also the bindable domain's
+ * bound ({@link BINDING_RECEIPT}), so no value with an exact digest meets the sentinel.
+ */
+export declare const MAX_DEPTH = 256;
+/** Canonical JSON (recursively sorted keys, no whitespace) — the erasure protocol's ONE comparison
+ *  and hash basis: `selectHash` complains bind to it, and evidence rows are written/compared in this
+ *  form so a re-serialized import (key order changed by a middle layer) still compares equal. The memory
+ *  export bundle's section hashes are sha256 over it, and a backend that hashes or compares the same
+ *  records calls this function — the bytes are the contract, so there is no second copy to keep in step.
+ *
+ *  Not {@link canonicalize}: that one emits a type-tagged, length-prefixed form that is not JSON and is
+ *  never compared across runtimes; this one emits JSON text for JSON-shaped input (an `undefined` member
+ *  omitted, an `undefined` / function / symbol array element as `null`, a scalar through `JSON.stringify`,
+ *  an object read by its own enumerable keys with no `toJSON` call). The two answer different questions
+ *  and their outputs are not interchangeable. */
+export declare function canonicalJsonStringify(value: unknown): string;