@vincemakes/kiso-runtime 0.39.2 → 0.40.1

package/dist/agent.d.ts

@@ -27,6 +27,13 @@ export interface PermissionPolicy {
 export interface AgentDefinition {
     readonly model: string;
     readonly systemPrompt?: string;
+    /** 0.40.0: the root a NEW session starts in, recorded once in its
+     *  profile (revision 1) — the resume picker scopes by it. Never read
+     *  for an existing session: where it started is history. */
+    readonly workspace?: string;
+    /** 0.40.0: the config profile that named this binding, recorded per
+     *  revision for display. Never part of drift. */
+    readonly profileName?: string;
     /** `Tool<any>` like the registry: typed tools register without casts. */
     readonly tools: readonly Tool<any>[];
     readonly store: SessionStore;
@@ -79,17 +86,29 @@ export interface AgentDefinition {
 export declare class AgentRuntime {
     #private;
     constructor(definition: AgentDefinition);
+    /** The ids alone, from the directory — no log is read (store.ids). */
     sessionIds(): string[];
     /** Session metadata for listings (`kiso sessions`). */
     sessions(): import("./store.js").SessionMeta[];
     /** Release every held fd and writer lock (E group: the CLI closes on exit). */
     close(): void;
-    /** Load an existing session from disk, or create a fresh one. */
+    /** Load an existing session from disk, or create a fresh one.
+     *
+     *  `acceptDrift` is accepted and INERT — the CLI's historical
+     *  `--accept-drift`, kept so the flag keeps parsing. Since the owner's
+     *  ruling of 2026-09-21 a changed binding never needs an
+     *  acknowledgement: the current configuration wins and is recorded. */
     session(options: {
         id: string;
         acceptDrift?: boolean;
     }): Promise<AgentSession>;
 }
+/** 0.40.0 — what an acknowledged drift replaced: the reasons it was
+ *  material, and the reasoning setting the acknowledgement reset. */
+export interface DriftAcknowledgement {
+    readonly reasons: readonly string[];
+    readonly reasoningReset: import("./provider/metadata.js").ReasoningSetting;
+}
 /** The one-liner the README promises. */
 export declare function createAgent(definition: AgentDefinition): AgentRuntime;
 /**

package/dist/agent.js

@@ -42,8 +42,9 @@ export class AgentRuntime {
         }
         this.#adapterPromise = resolveAdapter(definition);
     }
+    /** The ids alone, from the directory — no log is read (store.ids). */
     sessionIds() {
-        return this.#definition.store.list().map((m) => m.id);
+        return this.#definition.store.ids();
     }
     /** Session metadata for listings (`kiso sessions`). */
     sessions() {
@@ -53,7 +54,12 @@ export class AgentRuntime {
     close() {
         this.#definition.store.closeAll();
     }
-    /** Load an existing session from disk, or create a fresh one. */
+    /** Load an existing session from disk, or create a fresh one.
+     *
+     *  `acceptDrift` is accepted and INERT — the CLI's historical
+     *  `--accept-drift`, kept so the flag keeps parsing. Since the owner's
+     *  ruling of 2026-09-21 a changed binding never needs an
+     *  acknowledgement: the current configuration wins and is recorded. */
     async session(options) {
         const store = this.#definition.store;
         const records = store.load(options.id);
@@ -74,28 +80,47 @@ export class AgentRuntime {
             revision: 0,
             modelId: this.#definition.model,
             provider: startupScope ?? null,
+            profileName: this.#definition.profileName ?? null,
+            workspace: this.#definition.workspace ?? null,
             ...(this.#definition.systemPrompt !== undefined ? { systemPrompt: this.#definition.systemPrompt } : {}),
             registry: this.#registry,
         });
         let restored = null;
         let profilePending = false;
+        let driftAcknowledgement = null;
         if (meta.kind === "ok") {
             const drift = assessProfileDrift(meta.profile, {
                 provider: startupScope ?? null,
+                modelId: this.#definition.model,
                 systemPromptDigest: candidate.systemPromptDigest,
                 tools: candidate.tools,
             });
-            if (drift.kind === "material" && options.acceptDrift !== true) {
-                const listed = drift.reasons.map((r) => `- ${r}`).join("\n");
-                throw new Error(`the recorded execution profile no longer matches this process:\n${listed}\nre-open with acceptDrift (the CLI's --accept-drift flag) to proceed under the CURRENT configuration — the acknowledgement is recorded as a new revision; silently rebuilding is forbidden`);
-            }
             if (drift.kind === "material") {
-                // acknowledged: the current configuration wins, DURABLY.
+                // 0.40.1 (the owner's ruling of 2026-09-21): a DIFFERENT BINDING
+                // never blocks. A person may simply have switched models, so the
+                // CURRENT configuration wins — DURABLY, as the next revision —
+                // and the session says so. It used to refuse without an explicit
+                // `acceptDrift`, which turned "I moved to another provider"
+                // into an error the resume could not pass at all.
+                //
+                // Nothing provider-specific crosses the change: every adapter
+                // withholds foreign reasoning/continuation (MG-1 A5), so a new
+                // binding loses cache state, never correctness. The reasoning
+                // resets to defaults (owner-ruled: the recorded effort was a
+                // choice for the model that no longer answers) — and the session
+                // says so through `driftAcknowledgement`. The field's NAME is
+                // history: nothing is acknowledged any more, the change is
+                // recorded and stated.
+                driftAcknowledgement = { reasons: drift.reasons, reasoningReset: meta.profile.reasoning };
                 writeProfile(store.root, options.id, {
                     ...buildProfile({
                         revision: meta.profile.revision + 1,
                         modelId: this.#definition.model,
                         provider: startupScope ?? null,
+                        profileName: this.#definition.profileName ?? null,
+                        // history: where the session started is not where the
+                        // acknowledging process happens to be
+                        workspace: meta.profile.workspace,
                         ...(this.#definition.systemPrompt !== undefined ? { systemPrompt: this.#definition.systemPrompt } : {}),
                         registry: this.#registry,
                     }),
@@ -129,6 +154,8 @@ export class AgentRuntime {
                 : {}),
             ...(restored !== null ? { reasoning: restored.reasoning } : {}),
             ...(profilePending ? { profilePending: true } : {}),
+            ...(this.#definition.profileName !== undefined ? { profileName: this.#definition.profileName } : {}),
+            ...(driftAcknowledgement !== null ? { driftAcknowledgement } : {}),
             ...(this.#definition.systemPrompt !== undefined ? { systemPrompt: this.#definition.systemPrompt } : {}),
             registry: this.#registry,
             ...(this.#definition.permissionPolicy !== undefined || this.#definition.hooks !== undefined
@@ -148,7 +175,16 @@ export class AgentRuntime {
             ...(this.#definition.streamIdleMs !== undefined ? { streamIdleMs: this.#definition.streamIdleMs } : {}),
             ...(this.#definition.extensions !== undefined ? { extensions: this.#definition.extensions } : {}),
         };
-        return new AgentSession(options.id, log, store, adapter, config);
+        // 0.40.0: the last bill's time rides the RECORD, not the event.
+        let lastUsageAt;
+        for (let i = records.length - 1; i >= 0; i--) {
+            const e = records[i].event;
+            if (e.type === "usage" && e.known) {
+                lastUsageAt = records[i].ts;
+                break;
+            }
+        }
+        return new AgentSession(options.id, log, store, adapter, config, lastUsageAt);
     }
 }
 /** The one-liner the README promises. */

package/dist/compaction-policy.d.ts

@@ -0,0 +1,82 @@
+/**
+ * ADR-0055 Amendment 1 (A1b) — the in-run compaction policy, as data and
+ * pure decisions. The kernel only asks, before every request, what to
+ * append (LoopConfig.compact); this module answers the WHEN, and the
+ * session supplies the summary itself (session.ts compactionPoint).
+ *
+ * Every number here is a stated position, not a measurement, and the ADR
+ * says so: the tiers are the owner's ruling, the phase detector is a
+ * heuristic over round shapes that is reported and never proven, and the
+ * prune's break-even is arithmetic on one price table.
+ */
+import { type Event } from "@vincemakes/kiso-core";
+/** A1: soft makes compaction eligible (it waits for a phase end), hard
+ *  fires at the next settled round, emergency before the next request.
+ *  Emergency is `max(window − reserve, hard)` (the lead, 2026-09-18), so
+ *  soft ≤ hard ≤ emergency always holds: a small window never goes
+ *  negative, and DeepSeek's 384K max output on a 1M window puts emergency
+ *  at hard (700K) — an output over 300K is left to the one overflow
+ *  recovery. A5: the raw tail stays v1's `min(0.1·window, 100K)`. */
+export interface Tiers {
+    readonly soft: number;
+    readonly hard: number;
+    readonly emergency: number;
+    readonly tail: number;
+}
+export declare function tiersFor(windowTokens: number, reserve: number): Tiers;
+/**
+ * A1 — which tier a measured context is past, the most urgent first; the
+ * soft tier asks the phase detector. Null: no tier is crossed. Emergency
+ * only where it stands STRICTLY above hard (the lead, A1B-M1): at the
+ * clamp the two coincide, and that fire is hard — not prune-eligible.
+ */
+export declare function tierReason(used: number, t: Tiers, why: "request" | "overflow", phase: () => string | null): string | null;
+/**
+ * A3 rule 1's runners — the lead's table, matched on a command's first
+ * words once leading `VAR=value` assignments and the plain wrappers are
+ * stripped. A shell call not on it is not a test run. The CLI puts the
+ * user's configured `checks` in front of it.
+ */
+export declare const TEST_RUNNERS: readonly string[];
+/** Whether one shell command line runs a check: any `&&`/`;`/`|` segment
+ *  whose leading words, past assignments and wrappers, start a runner. */
+export declare function runsACheck(command: string, extra?: readonly string[]): boolean;
+/**
+ * A3 — does the LAST settled round end a phase? The rounds are the model
+ * turns since the last boundary, read off their tool calls. A new user
+ * turn since the last round is a phase end of its own. Returns the rule
+ * that fired, for the record, or null.
+ */
+export declare function phaseEnd(events: readonly Event[], sinceSeq: number, isCheck: (command: string) => boolean): string | null;
+/** The default number of the newest compactable results a prune keeps. */
+export declare const KEEP_COMPACTABLE_RESULTS = 4;
+/**
+ * The prune primitive's boundary (moved unchanged from the kernel, where
+ * the standing trigger that used it was removed — A4): drawn by
+ * compactable-result recentness, never user turns. The newest
+ * `keepResults` still-visible compactable results stay; the boundary is
+ * the (K+1)th-newest. A do-not-compact result is uncountable, exactly as
+ * the projection refuses to clear it. Undefined when nothing would clear.
+ */
+export declare function microcompactBoundarySeq(events: readonly Event[], keepResults?: number): number | undefined;
+/** A4(c): the requests a run is assumed to have left when nothing better
+ *  is known — a stated position, not a prediction. */
+export declare const REQUESTS_ASSUMED_LEFT = 50;
+/**
+ * A4(c) — a prune that drops `dropped` tokens and re-sends `keptAfter`
+ * tokens cold (everything after the first cleared result) pays only if at
+ * least `factor · keptAfter / dropped` requests follow. `factor` is
+ * (miss − hit) / hit from the model's price table: 49 at DeepSeek V4.1
+ * Flash off-peak (0.15 and 0.003 per million, 2026-09-19).
+ */
+export declare function pruneBreaksEven(dropped: number, keptAfter: number, factor: number, requestsLeft?: number): boolean;
+/** The factor for a price table: (miss − hit) / hit, or 49 (the DeepSeek
+ *  V4.1 Flash off-peak figure) when the table cannot say. */
+export declare function breakEvenFactor(missPerMillion: number | undefined, hitPerMillion: number | undefined): number;
+/**
+ * A4(b) with its (c) guard — the emergency prune, only where it pays. D is
+ * what the clear drops (the clearable results up to the boundary), S what
+ * is re-sent cold (everything from the first cleared result on, minus D).
+ * Undefined: nothing to clear, or too few requests left to earn it back.
+ */
+export declare function guardedPruneSeq(events: readonly Event[], factor: number, requestsLeft?: number, keepResults?: number): number | undefined;

package/dist/compaction-policy.js

@@ -0,0 +1,197 @@
+/**
+ * ADR-0055 Amendment 1 (A1b) — the in-run compaction policy, as data and
+ * pure decisions. The kernel only asks, before every request, what to
+ * append (LoopConfig.compact); this module answers the WHEN, and the
+ * session supplies the summary itself (session.ts compactionPoint).
+ *
+ * Every number here is a stated position, not a measurement, and the ADR
+ * says so: the tiers are the owner's ruling, the phase detector is a
+ * heuristic over round shapes that is reported and never proven, and the
+ * prune's break-even is arithmetic on one price table.
+ */
+import { DO_NOT_COMPACT, MICROCOMPACTABLE } from "@vincemakes/kiso-core";
+import { estimateEventTokens } from "./summarize.js";
+export function tiersFor(windowTokens, reserve) {
+    return {
+        soft: Math.min(0.5 * windowTokens, 400_000),
+        hard: Math.min(0.8 * windowTokens, 700_000),
+        emergency: Math.max(windowTokens - reserve, Math.min(0.8 * windowTokens, 700_000)),
+        tail: Math.min(0.1 * windowTokens, 100_000),
+    };
+}
+/**
+ * A1 — which tier a measured context is past, the most urgent first; the
+ * soft tier asks the phase detector. Null: no tier is crossed. Emergency
+ * only where it stands STRICTLY above hard (the lead, A1B-M1): at the
+ * clamp the two coincide, and that fire is hard — not prune-eligible.
+ */
+export function tierReason(used, t, why, phase) {
+    if (why === "overflow")
+        return "overflow";
+    if (used > t.emergency && t.emergency > t.hard)
+        return "emergency";
+    if (used > t.hard)
+        return "hard";
+    if (used > t.soft)
+        return phase();
+    return null;
+}
+/**
+ * A3 rule 1's runners — the lead's table, matched on a command's first
+ * words once leading `VAR=value` assignments and the plain wrappers are
+ * stripped. A shell call not on it is not a test run. The CLI puts the
+ * user's configured `checks` in front of it.
+ */
+export const TEST_RUNNERS = [
+    "npm test", "npm run test", "pnpm test", "yarn test", "bun test", "npx vitest", "npx jest", "npx mocha", "node --test",
+    "pytest", "python -m pytest", "go test", "cargo test", "make test", "mvn test", "gradle test", "dotnet test", "rspec",
+    "phpunit", "mix test", "swift test",
+];
+const WRAPPERS = new Set(["env", "time", "nice", "nohup", "command", "exec", "sudo"]);
+/** Whether one shell command line runs a check: any `&&`/`;`/`|` segment
+ *  whose leading words, past assignments and wrappers, start a runner. */
+export function runsACheck(command, extra = []) {
+    const runners = [...extra, ...TEST_RUNNERS];
+    return command.split(/&&|\|\||;|\|/).some((segment) => {
+        const words = segment.trim().split(/\s+/);
+        while (words.length > 0 && (WRAPPERS.has(words[0]) || /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0])))
+            words.shift();
+        if (words[0] === "timeout")
+            words.splice(0, 2);
+        const line = words.join(" ");
+        return runners.some((r) => line === r || line.startsWith(`${r} `));
+    });
+}
+const EDIT_TOOLS = new Set(["write_file", "edit_file"]);
+const READ_TOOLS = new Set(["read_file", "list_dir", "search_text", "read_skill"]);
+/**
+ * A3 — does the LAST settled round end a phase? The rounds are the model
+ * turns since the last boundary, read off their tool calls. A new user
+ * turn since the last round is a phase end of its own. Returns the rule
+ * that fired, for the record, or null.
+ */
+export function phaseEnd(events, sinceSeq, isCheck) {
+    const rounds = [];
+    let calls = [];
+    let userAfterLastRound = false;
+    for (const e of events) {
+        if (e.seq <= sinceSeq)
+            continue;
+        if (e.type === "tool_call_end")
+            calls.push(e);
+        else if (e.type === "user_input")
+            userAfterLastRound = true;
+        else if (e.type === "stop" && calls.length > 0) {
+            rounds.push({
+                edits: calls.some((c) => EDIT_TOOLS.has(c.name)),
+                readsOnly: calls.every((c) => READ_TOOLS.has(c.name)),
+                check: calls.some((c) => (c.name === "shell" && typeof c.input?.command === "string" && isCheck(c.input.command)) || (c.name === "delegate" && c.input?.check !== undefined)),
+            });
+            calls = [];
+            userAfterLastRound = false;
+        }
+    }
+    if (userAfterLastRound)
+        return "phase:turn";
+    const last = rounds.at(-1);
+    const prev = rounds.at(-2);
+    if (last === undefined)
+        return null;
+    if (last.check)
+        return "phase:check";
+    if (prev !== undefined && prev.edits && !last.edits)
+        return "phase:edits-done";
+    if (prev !== undefined && prev.readsOnly && last.edits)
+        return "phase:reads-done";
+    return null;
+}
+/** The default number of the newest compactable results a prune keeps. */
+export const KEEP_COMPACTABLE_RESULTS = 4;
+/**
+ * The prune primitive's boundary (moved unchanged from the kernel, where
+ * the standing trigger that used it was removed — A4): drawn by
+ * compactable-result recentness, never user turns. The newest
+ * `keepResults` still-visible compactable results stay; the boundary is
+ * the (K+1)th-newest. A do-not-compact result is uncountable, exactly as
+ * the projection refuses to clear it. Undefined when nothing would clear.
+ */
+export function microcompactBoundarySeq(events, keepResults = KEEP_COMPACTABLE_RESULTS) {
+    const callName = new Map();
+    let lastCleared = -1;
+    for (const ev of events) {
+        if (ev.type === "tool_call_end")
+            callName.set(ev.callId, ev.name);
+        if (ev.type === "microcompacted" && ev.beforeSeq > lastCleared)
+            lastCleared = ev.beforeSeq;
+    }
+    const visible = [];
+    for (const ev of events) {
+        if (ev.type !== "tool_result" || ev.seq <= lastCleared)
+            continue;
+        const name = callName.get(ev.callId);
+        if (name !== undefined && MICROCOMPACTABLE.has(name) && !(ev.tags ?? []).includes(DO_NOT_COMPACT))
+            visible.push(ev.seq);
+    }
+    if (visible.length <= keepResults)
+        return undefined;
+    return visible[visible.length - keepResults - 1];
+}
+/** A4(c): the requests a run is assumed to have left when nothing better
+ *  is known — a stated position, not a prediction. */
+export const REQUESTS_ASSUMED_LEFT = 50;
+/**
+ * A4(c) — a prune that drops `dropped` tokens and re-sends `keptAfter`
+ * tokens cold (everything after the first cleared result) pays only if at
+ * least `factor · keptAfter / dropped` requests follow. `factor` is
+ * (miss − hit) / hit from the model's price table: 49 at DeepSeek V4.1
+ * Flash off-peak (0.15 and 0.003 per million, 2026-09-19).
+ */
+export function pruneBreaksEven(dropped, keptAfter, factor, requestsLeft = REQUESTS_ASSUMED_LEFT) {
+    if (dropped <= 0)
+        return false;
+    return requestsLeft >= (factor * keptAfter) / dropped;
+}
+/** The factor for a price table: (miss − hit) / hit, or 49 (the DeepSeek
+ *  V4.1 Flash off-peak figure) when the table cannot say. */
+export function breakEvenFactor(missPerMillion, hitPerMillion) {
+    if (missPerMillion === undefined || hitPerMillion === undefined || hitPerMillion <= 0)
+        return 49;
+    return (missPerMillion - hitPerMillion) / hitPerMillion;
+}
+/**
+ * A4(b) with its (c) guard — the emergency prune, only where it pays. D is
+ * what the clear drops (the clearable results up to the boundary), S what
+ * is re-sent cold (everything from the first cleared result on, minus D).
+ * Undefined: nothing to clear, or too few requests left to earn it back.
+ */
+export function guardedPruneSeq(events, factor, requestsLeft = REQUESTS_ASSUMED_LEFT, keepResults = KEEP_COMPACTABLE_RESULTS) {
+    const beforeSeq = microcompactBoundarySeq(events, keepResults);
+    if (beforeSeq === undefined)
+        return undefined;
+    const callName = new Map();
+    let lastCleared = -1;
+    for (const ev of events) {
+        if (ev.type === "tool_call_end")
+            callName.set(ev.callId, ev.name);
+        if (ev.type === "microcompacted" && ev.beforeSeq > lastCleared)
+            lastCleared = ev.beforeSeq;
+    }
+    let dropped = 0;
+    let first;
+    for (const ev of events) {
+        if (ev.type !== "tool_result" || ev.seq <= lastCleared || ev.seq > beforeSeq)
+            continue;
+        const name = callName.get(ev.callId);
+        if (name === undefined || !MICROCOMPACTABLE.has(name) || (ev.tags ?? []).includes(DO_NOT_COMPACT))
+            continue;
+        dropped += estimateEventTokens(ev);
+        first ??= ev.seq;
+    }
+    if (first === undefined)
+        return undefined;
+    let after = 0;
+    for (const ev of events)
+        if (ev.seq >= first)
+            after += estimateEventTokens(ev);
+    return pruneBreaksEven(dropped, after - dropped, factor, requestsLeft) ? beforeSeq : undefined;
+}

package/dist/compose.d.ts

@@ -5,6 +5,11 @@
  */
 import type { ApprovalChain, Event, HookHost, KisoExtension, ToolRegistry } from "@vincemakes/kiso-core";
 import type { SessionConfig } from "./session.js";
+/** The base a run's system prompt is composed on: the session's prompt,
+ *  then the tool table (generated machinery sits BETWEEN the base and the
+ *  extension appends). One function, so an in-band summary outside a run
+ *  (ADR-0055 A2, /compact) sends the exact prefix a run sends. */
+export declare function runBasePrompt(systemPrompt: string | undefined, registry: ToolRegistry): string | undefined;
 /** The table, or "" when the registry is empty (no vocabulary, no tools). */
 export declare function composeToolTable(registry: ToolRegistry): string;
 /**

package/dist/compose.js

@@ -18,6 +18,14 @@ const TOOL_RULES = [
     { tool: "list_dir", line: "list with list_dir, never ls" },
     { tool: "shell", line: "shell for what the file tools cannot do: commands, git, the network, the system" },
 ];
+/** The base a run's system prompt is composed on: the session's prompt,
+ *  then the tool table (generated machinery sits BETWEEN the base and the
+ *  extension appends). One function, so an in-band summary outside a run
+ *  (ADR-0055 A2, /compact) sends the exact prefix a run sends. */
+export function runBasePrompt(systemPrompt, registry) {
+    const toolTable = composeToolTable(registry);
+    return toolTable === "" ? systemPrompt : systemPrompt === undefined ? toolTable : `${systemPrompt}\n\n${toolTable}`;
+}
 /** The table, or "" when the registry is empty (no vocabulary, no tools). */
 export function composeToolTable(registry) {
     const tools = registry.list();
@@ -73,7 +81,10 @@ export function composeHooks(existing, extensions) {
                 await h(payload, ctx);
         };
     };
-    for (const key of ["onPreLlm", "onEvent", "onPause", "onStop"]) {
+    // onRetry (ADR-0005 Amendment 2) is an observer like the rest: every
+    // source hears every retry, in order — the CLI's status row and an
+    // extension's logger must not be made to take turns.
+    for (const key of ["onPreLlm", "onEvent", "onPause", "onStop", "onRetry"]) {
         const handler = observers((h) => h[key]);
         if (handler !== undefined)
             out[key] = handler;

package/dist/context-anchor.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 0.40.0 (the owner's session) — what the context holds, anchored on the
+ * last BILLED request.
+ *
+ * The estimate alone read a Chinese-heavy context as ~470k while the
+ * provider billed 732,448 input tokens on a 1M window: the ctx row said
+ * "~53% left" and the microcompact trigger (window/2) never fired. The
+ * provider's own count of the last request is the truth; only what the log
+ * appended after it is estimated.
+ *
+ * The anchor is refused — the caller falls back to the estimate — when no
+ * bill describes the context any more: no usage yet, a usage the provider
+ * did not report (`known: false`), a usage at or before `floorSeq` (the
+ * session switched models since, and a different tokenizer counts
+ * differently), or one of the STALE_AFTER events after it, each of which
+ * changes what the next request carries.
+ */
+import { type Event, type Usage } from "@vincemakes/kiso-core";
+/**
+ * `usageTotal` turns one usage event into the tokens that request put in
+ * the context: its canonical prompt (fresh + cache read + cache write — the
+ * raw `inputTokens` means different things per route) plus its output.
+ * Returns undefined when the anchor is refused.
+ */
+export declare function contextAnchor(events: readonly Event[], usageTotal: (u: Usage) => number, floorSeq?: number): number | undefined;

package/dist/context-anchor.js

@@ -0,0 +1,46 @@
+/**
+ * 0.40.0 (the owner's session) — what the context holds, anchored on the
+ * last BILLED request.
+ *
+ * The estimate alone read a Chinese-heavy context as ~470k while the
+ * provider billed 732,448 input tokens on a 1M window: the ctx row said
+ * "~53% left" and the microcompact trigger (window/2) never fired. The
+ * provider's own count of the last request is the truth; only what the log
+ * appended after it is estimated.
+ *
+ * The anchor is refused — the caller falls back to the estimate — when no
+ * bill describes the context any more: no usage yet, a usage the provider
+ * did not report (`known: false`), a usage at or before `floorSeq` (the
+ * session switched models since, and a different tokenizer counts
+ * differently), or one of the STALE_AFTER events after it, each of which
+ * changes what the next request carries.
+ */
+import { estimateTokens } from "@vincemakes/kiso-core";
+const STALE_AFTER = new Set([
+    "compacted",
+    "microcompacted",
+    "summarized",
+    "user_input_replaced",
+    "model_output_abandoned",
+]);
+/**
+ * `usageTotal` turns one usage event into the tokens that request put in
+ * the context: its canonical prompt (fresh + cache read + cache write — the
+ * raw `inputTokens` means different things per route) plus its output.
+ * Returns undefined when the anchor is refused.
+ */
+export function contextAnchor(events, usageTotal, floorSeq = -1) {
+    let appended = 0;
+    for (let i = events.length - 1; i >= 0; i--) {
+        const e = events[i];
+        if (e.type === "usage")
+            return e.known && e.seq > floorSeq ? usageTotal(e) + appended : undefined;
+        if (STALE_AFTER.has(e.type))
+            return undefined;
+        if (e.type === "tool_result")
+            appended += estimateTokens([{ role: "tool", callId: e.callId, content: e.content, isError: e.isError }]);
+        else if (e.type === "user_input")
+            appended += estimateTokens([{ role: "user", content: e.content }]);
+    }
+    return undefined;
+}

package/dist/internal.d.ts

@@ -17,6 +17,7 @@ export * from "./session.js";
 export * from "./run.js";
 export * from "./recovery.js";
 export * from "./compose.js";
+export * from "./compaction-policy.js";
 export * from "./summarize.js";
 export * from "./store.js";
 export * from "./lock-adapter.js";
@@ -28,3 +29,5 @@ export { canonicalizeUsageForModel } from "./usage/canonical.js";
 export { BUILTIN_MANIFESTS, resolveContinuationScope, type ModelRef, type ProviderManifest } from "./provider/manifest.js";
 export * from "./checkpoint.js";
 export * from "./request-budget.js";
+export { readProfile, readSummary, writeSummary, type ExecutionProfile, type ProfileReadResult } from "./profile.js";
+export { SUMMARY_MIGRATION_MARKER, listSessionSidecars, migrateSummaries, sessionSummary, summarizeEvents, summaryMigrationPending, type SessionListing, type SessionSummary } from "./session-summary.js";

package/dist/internal.js

@@ -17,6 +17,7 @@ export * from "./session.js";
 export * from "./run.js";
 export * from "./recovery.js";
 export * from "./compose.js";
+export * from "./compaction-policy.js";
 export * from "./summarize.js";
 export * from "./store.js";
 export * from "./lock-adapter.js";
@@ -36,3 +37,6 @@ export { BUILTIN_MANIFESTS, resolveContinuationScope } from "./provider/manifest
 // and the request-budget accounting the CLI's status line reads.
 export * from "./checkpoint.js";
 export * from "./request-budget.js";
+// 0.40.0: the listing reads the recorded workspace and profile name.
+export { readProfile, readSummary, writeSummary } from "./profile.js";
+export { SUMMARY_MIGRATION_MARKER, listSessionSidecars, migrateSummaries, sessionSummary, summarizeEvents, summaryMigrationPending } from "./session-summary.js";

package/dist/profile.d.ts

@@ -48,6 +48,11 @@ export interface ExecutionProfile {
     /** the config profile NAME — the credential reference is at most the
      *  env-var name the config carries; never the secret. */
     readonly profileName: string | null;
+    /** 0.40.0: the realpath of the root the session STARTED in — history,
+     *  not configuration. Set at revision 1 and carried by every later
+     *  revision; null when the start is unknown (a legacy session's first
+     *  revision, or a sidecar written before the field existed). */
+    readonly workspace: string | null;
     readonly reasoning: ReasoningSetting;
     readonly systemPromptDigest: string;
     /** sorted by name; the digest below is DERIVED from this inventory. */
@@ -59,7 +64,10 @@ export declare function buildProfile(input: {
     readonly revision: number;
     readonly modelId: string;
     readonly provider: ProfileModelRef | null;
-    readonly profileName?: string;
+    readonly profileName?: string | null;
+    /** An INPUT, never derived here: revision 1 passes the starting root,
+     *  every later writer passes the prior revision's value. */
+    readonly workspace?: string | null;
     readonly reasoning?: ReasoningSetting;
     readonly systemPrompt?: string;
     readonly registry: ToolRegistry;
@@ -67,8 +75,14 @@ export declare function buildProfile(input: {
 export declare function profilePath(root: string, sessionId: string): string;
 /** Atomic, fail-closed write: a reader sees the previous revision or the
  *  new one, never a torn file — and the RENAME itself is made durable by
- *  the parent-directory fsync. */
+ *  the parent-directory fsync. 0.40.0 dogfood: the file holds two tenants
+ *  (`profile`, `summary`); writing one preserves the other. */
 export declare function writeProfile(root: string, sessionId: string, profile: ExecutionProfile): void;
+/** The 0.40.0 dogfood's `summary` tenant — what the session list reads
+ *  instead of the log. Preserves the `profile` tenant byte for byte. */
+export declare function writeSummary(root: string, sessionId: string, summary: import("./session-summary.js").SessionSummary): void;
+/** The summary tenant, or null (no sidecar, no summary, or unreadable). */
+export declare function readSummary(root: string, sessionId: string): import("./session-summary.js").SessionSummary | null;
 export type ProfileReadResult = {
     readonly kind: "ok";
     readonly profile: ExecutionProfile;
@@ -95,8 +109,9 @@ export type ProfileDrift = {
     readonly kind: "compatible-additions";
     readonly added: readonly string[];
 }
-/** WHO ANSWERS changed — the one class that blocks without an
- *  explicit acknowledgement. */
+/** WHO ANSWERS changed — NAMED, and recorded as the next revision under
+ *  the CURRENT configuration. Owner-ruled 2026-09-21: a changed binding
+ *  never blocks a resume — the person may simply have switched models. */
  | {
     readonly kind: "material";
     readonly reasons: readonly string[];
@@ -105,10 +120,14 @@ export type ProfileDrift = {
  *  never from digest inequality alone: every recorded tool present with
  *  identical hashes plus new names = compatible additions (a one-line
  *  notice); a missing name, a changed hash, a provider/model divergence,
- *  or a system-prompt divergence = MATERIAL (explicit resolution; a
- *  digest mismatch is never presented as restoration). */
+ *  or a system-prompt divergence = MATERIAL (the change is NAMED and
+ *  recorded as the next revision under the CURRENT configuration — it
+ *  blocks nothing; a digest mismatch is never presented as restoration). */
 export declare function assessProfileDrift(recorded: ExecutionProfile, current: {
     readonly provider: ProfileModelRef | null;
+    /** The model THIS process would run — needed because an unscoped binding
+     *  has no provider ref to carry it. */
+    readonly modelId: string;
     readonly systemPromptDigest: string;
     readonly tools: readonly ProfileToolRecord[];
 }): ProfileDrift;