@abot-ai/runtime 1.2.0 → 1.3.0

package/dist/src/web-ui/server.js

@@ -6,9 +6,11 @@ import { pathToFileURL } from "node:url";
 import { WebSocketServer } from "ws";
 import { inspectRuntimeConfigFileWithMeta } from "../runtime/config/loader.js";
 import { loadDotEnvFile } from "../shared/load-dotenv.js";
+import { createWebUiShutdown } from "./server-shutdown.js";
 import { ExternalBridgeWebBackend } from "./external-bridge-backend.js";
 import { LocalRuntimeWebBackend } from "./local-runtime-backend.js";
 import { resolveWebUiAddress } from "./web-ui-address.js";
+import { createLinkPreviewRouteHandler } from "./link-preview/routes.js";
 const DEFAULT_WEB_BACKEND = "runtime";
 const DEFAULT_BRIDGE_API_BASE = "http://127.0.0.1:8787/abot/api";
 const DEFAULT_BRIDGE_REALTIME_URL = "ws://127.0.0.1:8787/abot/realtime";
@@ -226,8 +228,11 @@ export function startWebUiServer(overrides = {}) {
             externalBridgeBackend.handleRealtimeConnection(client);
         });
     }
+    const handleLinkPreview = createLinkPreviewRouteHandler();
     const server = createServer((req, res) => {
         void (async () => {
+            if (await handleLinkPreview(req, res))
+                return;
             const pathname = new URL(req.url || "/", "http://localhost").pathname;
             if (pathname === "/web-config") {
                 sendJson(res, 200, {
@@ -301,7 +306,12 @@ export function startWebUiServer(overrides = {}) {
             wss.emit("connection", ws, req);
         });
     });
-    server.listen(options.port, options.host, () => {
+    const listenAbort = new AbortController();
+    server.listen({
+        port: options.port,
+        host: options.host,
+        signal: listenAbort.signal,
+    }, () => {
         console.log(`abot web UI listening on http://${options.host}:${options.port}`);
         if (localRuntimeBackend) {
             console.log("using local abot backend");
@@ -311,16 +321,9 @@ export function startWebUiServer(overrides = {}) {
             console.log(`using external bridge realtime ${options.realtimeUrl}`);
         }
     });
+    const schedulerStartup = localRuntimeBackend?.start(options.environments.map(({ id }) => id));
     return {
-        close: () => new Promise((resolveClose, reject) => {
-            wss.close();
-            server.close((error) => {
-                if (error)
-                    reject(error);
-                else
-                    resolveClose();
-            });
-        }),
+        close: createWebUiShutdown(server, wss, schedulerStartup, () => localRuntimeBackend?.stop(), listenAbort),
     };
 }
 const invokedPath = process.argv[1] ? pathToFileURL(process.argv[1]).href : "";

package/dist/src/web-ui/session-read-state/availability.d.ts

@@ -0,0 +1,16 @@
+/** Isolate UI sidecar failures; canonical session operations stay outside this boundary. */
+export declare function captureReadStateAvailability<T>(operation: () => Promise<T>): Promise<{
+    readStateStatus: "available";
+    value: Awaited<T>;
+} | {
+    readStateStatus: "unavailable";
+    value?: undefined;
+}>;
+export declare function unavailableSessionReadState(sessionId: string): {
+    sessionId: string;
+    readStateStatus: "unavailable";
+    unreadCount: null;
+    hasUnread: null;
+    lastReadAt: null;
+    lastReadMessageId: null;
+};

package/dist/src/web-ui/session-read-state/availability.js

@@ -0,0 +1,20 @@
+/** Isolate UI sidecar failures; canonical session operations stay outside this boundary. */
+export async function captureReadStateAvailability(operation) {
+    try {
+        return { readStateStatus: "available", value: await operation() };
+    }
+    catch (error) {
+        console.error("Web UI read tracking unavailable:", error);
+        return { readStateStatus: "unavailable" };
+    }
+}
+export function unavailableSessionReadState(sessionId) {
+    return {
+        sessionId,
+        readStateStatus: "unavailable",
+        unreadCount: null,
+        hasUnread: null,
+        lastReadAt: null,
+        lastReadMessageId: null,
+    };
+}

package/dist/src/web-ui/session-read-state/projection.d.ts

@@ -0,0 +1,17 @@
+import type { SessionSnapshotMessage } from "../../sessions/types.js";
+import type { WebReadState } from "./store.js";
+export type ReadBoundary = {
+    readThroughMessageId?: unknown;
+    readThroughRequestId?: unknown;
+};
+export declare function advanceReadCursor(state: WebReadState, sessionId: string, messages: SessionSnapshotMessage[], boundary: ReadBoundary, now: number): void;
+export declare function projectSessionReadState(state: WebReadState, sessionId: string, messages: SessionSnapshotMessage[]): {
+    sessionId: string;
+    readStateStatus: "available";
+    unreadCount: number;
+    hasUnread: boolean;
+    lastReadMessageId: string | null;
+    lastReadAt: number;
+    latestMessageId: string | number | null;
+    latestAssistantMessageId: string | number | null;
+};

package/dist/src/web-ui/session-read-state/projection.js

@@ -0,0 +1,71 @@
+function messageTimestamp(message) {
+    const value = typeof message.createdAt === "number"
+        ? message.createdAt
+        : Date.parse(String(message.createdAt));
+    return Number.isFinite(value) ? value : 0;
+}
+function cursorIndex(messages, cursor) {
+    if (!cursor)
+        return -1;
+    if (!cursor.messageId)
+        return -1;
+    return messages.findIndex((message) => String(message.id) === cursor.messageId &&
+        messageTimestamp(message) === cursor.createdAt);
+}
+function requestedAssistantIndex(messages, boundary) {
+    const id = boundary.readThroughMessageId;
+    const hasNumericBoundary = typeof id === "number" && Number.isSafeInteger(id) && id >= 0;
+    if (hasNumericBoundary)
+        return messages.findIndex((message) => message.role === "assistant" && String(message.id) === String(id));
+    const requestId = boundary.readThroughRequestId;
+    if (typeof requestId !== "string" || !requestId)
+        return -1;
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        if (message.role === "assistant" && message.requestId === requestId)
+            return index;
+    }
+    return -1;
+}
+export function advanceReadCursor(state, sessionId, messages, boundary, now) {
+    const nextIndex = requestedAssistantIndex(messages, boundary);
+    if (nextIndex < 0)
+        return;
+    const cursors = new Map(state.cursors);
+    const previous = cursors.get(sessionId);
+    const previousIndex = cursorIndex(messages, previous);
+    if (previousIndex >= nextIndex)
+        return;
+    const message = messages[nextIndex];
+    const createdAt = messageTimestamp(message);
+    if (previous && previous.createdAt > createdAt)
+        return;
+    cursors.set(sessionId, {
+        messageId: String(message.id),
+        createdAt,
+        lastReadAt: Math.max(now, (previous?.lastReadAt ?? state.initializedAt) + 1),
+    });
+    state.cursors = [...cursors];
+}
+export function projectSessionReadState(state, sessionId, messages) {
+    const cursor = new Map(state.cursors).get(sessionId);
+    const readIndex = cursorIndex(messages, cursor);
+    const unreadCount = messages.filter((message, index) => {
+        if (message.role !== "assistant")
+            return false;
+        if (messageTimestamp(message) <= state.initializedAt)
+            return false;
+        return index > readIndex;
+    }).length;
+    return {
+        sessionId,
+        readStateStatus: "available",
+        unreadCount,
+        hasUnread: unreadCount > 0,
+        lastReadMessageId: cursor?.messageId || null,
+        lastReadAt: cursor?.lastReadAt ?? state.initializedAt,
+        latestMessageId: messages.at(-1)?.id ?? null,
+        latestAssistantMessageId: [...messages].reverse().find((message) => message.role === "assistant")
+            ?.id ?? null,
+    };
+}

package/dist/src/web-ui/session-read-state/service.d.ts

@@ -0,0 +1,86 @@
+import type { RuntimeConfig, SessionStore } from "../../runtime/ports.js";
+import type { SessionSnapshot } from "../../sessions/types.js";
+import { type ReadBoundary } from "./projection.js";
+type Sessions = Pick<SessionStore, "getSessionSnapshot">;
+type Environment = {
+    services: {
+        config: RuntimeConfig;
+        sessions: Sessions;
+    };
+};
+export declare class WebSessionReadStates {
+    private readonly getEnvironment;
+    private readonly now;
+    private readonly stores;
+    private readonly initializedAt;
+    constructor(getEnvironment: (id: string) => Environment, now?: () => number);
+    private store;
+    initialize(environmentId: string): Promise<void>;
+    forget(environmentId: string, sessionId: string): Promise<void>;
+    reset(environmentId: string, sessionId: string): Promise<void>;
+    project(environmentId: string, snapshot: SessionSnapshot): Promise<{
+        sessionId: string;
+        readStateStatus: "unavailable";
+        unreadCount: null;
+        hasUnread: null;
+        lastReadAt: null;
+        lastReadMessageId: null;
+    } | {
+        sessionId: string;
+        readStateStatus: "available";
+        unreadCount: number;
+        hasUnread: boolean;
+        lastReadMessageId: string | null;
+        lastReadAt: number;
+        latestMessageId: string | number | null;
+        latestAssistantMessageId: string | number | null;
+    }>;
+    mark(environmentId: string, sessionId: string, boundary: ReadBoundary): Promise<{
+        sessionId: string;
+        readStateStatus: "available";
+        unreadCount: number;
+        hasUnread: boolean;
+        lastReadMessageId: string | null;
+        lastReadAt: number;
+        latestMessageId: string | number | null;
+        latestAssistantMessageId: string | number | null;
+    } | null>;
+    list(environmentId: string): Promise<{
+        sessions: {
+            sessionId: string;
+            readStateStatus: "available";
+            unreadCount: number;
+            hasUnread: boolean;
+            lastReadMessageId: string | null;
+            lastReadAt: number;
+            latestMessageId: string | number | null;
+            latestAssistantMessageId: string | number | null;
+            id: string;
+            title: string;
+            createdAt: number;
+            updatedAt: number;
+            lastMessagePreview: string;
+            lastMessageAt: number | null;
+        }[];
+        nextCursor: null;
+    } | {
+        sessions: {
+            sessionId: string;
+            readStateStatus: "unavailable";
+            unreadCount: null;
+            hasUnread: null;
+            lastReadAt: null;
+            lastReadMessageId: null;
+            id: string;
+            title: string;
+            createdAt: number;
+            updatedAt: number;
+            lastMessagePreview: string;
+            lastMessageAt: number | null;
+            latestMessageId: string | number | null;
+            latestAssistantMessageId: string | number | null;
+        }[];
+        nextCursor: null;
+    }>;
+}
+export {};

package/dist/src/web-ui/session-read-state/service.js

@@ -0,0 +1,89 @@
+import { createHash } from "node:crypto";
+import { join, resolve } from "node:path";
+import { SessionService } from "../../sessions/session-service.js";
+import { clientVisibleMessages, toSessionListItem, toSnapshotMessage, } from "../../sessions/record/projection.js";
+import { WebReadStateStore } from "./store.js";
+import { captureReadStateAvailability, unavailableSessionReadState, } from "./availability.js";
+import { advanceReadCursor, projectSessionReadState, } from "./projection.js";
+export class WebSessionReadStates {
+    getEnvironment;
+    now;
+    stores = new Map();
+    initializedAt;
+    constructor(getEnvironment, now = Date.now) {
+        this.getEnvironment = getEnvironment;
+        this.now = now;
+        this.initializedAt = now();
+    }
+    store(environmentId) {
+        const { paths } = this.getEnvironment(environmentId).services.config;
+        const identity = JSON.stringify([
+            environmentId,
+            resolve(paths.sessionsDir),
+        ]);
+        const existing = this.stores.get(identity);
+        if (existing)
+            return existing;
+        const filename = createHash("sha256").update(identity).digest("hex") + ".json";
+        const store = new WebReadStateStore(join(paths.runtimeDir, "web-ui", "read-state", filename), this.initializedAt);
+        this.stores.set(identity, store);
+        return store;
+    }
+    initialize(environmentId) {
+        return this.store(environmentId).initialize();
+    }
+    async forget(environmentId, sessionId) {
+        await captureReadStateAvailability(() => this.store(environmentId).forget(sessionId));
+    }
+    async reset(environmentId, sessionId) {
+        await captureReadStateAvailability(() => this.store(environmentId).reset(sessionId, this.now()));
+    }
+    async project(environmentId, snapshot) {
+        const result = await captureReadStateAvailability(() => this.store(environmentId).transaction((state) => projectSessionReadState(state, snapshot.sessionId, snapshot.messages)));
+        if (result.readStateStatus === "unavailable")
+            return unavailableSessionReadState(snapshot.sessionId);
+        return result.value;
+    }
+    async mark(environmentId, sessionId, boundary) {
+        const store = this.store(environmentId);
+        await store.initialize();
+        const sessions = this.getEnvironment(environmentId).services.sessions;
+        return store.transaction(async (state) => {
+            const snapshot = await sessions.getSessionSnapshot(sessionId, {
+                includeRequests: false,
+            });
+            if (!snapshot)
+                return null;
+            advanceReadCursor(state, sessionId, snapshot.messages, boundary, this.now());
+            return projectSessionReadState(state, sessionId, snapshot.messages);
+        });
+    }
+    async list(environmentId) {
+        const { sessionsDir } = this.getEnvironment(environmentId).services.config.paths;
+        // One canonical disk enumeration avoids mutable offset pages and sending
+        // every request event across the managed Runtime's bounded RPC transport.
+        const records = await new SessionService({ sessionsDir }).getAllSessions();
+        const projectedSessions = records.map((record) => ({
+            summary: toSessionListItem(record),
+            messages: clientVisibleMessages(record.messages).map((message) => toSnapshotMessage(record.id, message, record.requests ?? [])),
+        }));
+        const result = await captureReadStateAvailability(() => this.store(environmentId).transaction((state) => {
+            const sessions = projectedSessions.map(({ summary, messages }) => {
+                return {
+                    ...summary,
+                    ...projectSessionReadState(state, summary.id, messages),
+                };
+            });
+            return { sessions, nextCursor: null };
+        }));
+        if (result.readStateStatus === "unavailable")
+            return {
+                sessions: projectedSessions.map(({ summary }) => ({
+                    ...summary,
+                    ...unavailableSessionReadState(summary.id),
+                })),
+                nextCursor: null,
+            };
+        return result.value;
+    }
+}

package/dist/src/web-ui/session-read-state/store.d.ts

@@ -0,0 +1,22 @@
+export type WebReadCursor = {
+    messageId: string;
+    createdAt: number;
+    lastReadAt: number;
+};
+export type WebReadState = {
+    version: 1;
+    initializedAt: number;
+    cursors: Array<[string, WebReadCursor]>;
+};
+/** UI-owned state; never writes Runtime session records or model context. */
+export declare class WebReadStateStore {
+    private readonly initializedAt;
+    private readonly path;
+    constructor(path: string, initializedAt: number);
+    private load;
+    private save;
+    transaction<T>(operation: (state: WebReadState) => T | Promise<T>): Promise<T>;
+    initialize(): Promise<void>;
+    reset(sessionId: string, now: number): Promise<void>;
+    forget(sessionId: string): Promise<void>;
+}

package/dist/src/web-ui/session-read-state/store.js

@@ -0,0 +1,110 @@
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+const pendingWrites = new Map();
+function hasFileErrorCode(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}
+function isReadCursor(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const cursor = value;
+    if (typeof cursor.messageId !== "string")
+        return false;
+    if (!Number.isFinite(cursor.createdAt))
+        return false;
+    return Number.isFinite(cursor.lastReadAt);
+}
+function decodeReadState(raw) {
+    const state = JSON.parse(raw);
+    if (state?.version !== 1)
+        throw new Error("Unsupported Web UI read state.");
+    if (!Number.isFinite(state.initializedAt))
+        throw new Error("Invalid Web UI read boundary.");
+    if (!Array.isArray(state.cursors))
+        throw new Error("Invalid Web UI read cursors.");
+    for (const entry of state.cursors) {
+        if (!Array.isArray(entry) || entry.length !== 2)
+            throw new Error("Invalid Web UI read cursor entry.");
+        if (typeof entry[0] !== "string" || !isReadCursor(entry[1]))
+            throw new Error("Invalid Web UI read cursor entry.");
+    }
+    return state;
+}
+/** UI-owned state; never writes Runtime session records or model context. */
+export class WebReadStateStore {
+    initializedAt;
+    path;
+    constructor(path, initializedAt) {
+        this.initializedAt = initializedAt;
+        this.path = resolve(path);
+    }
+    async load() {
+        try {
+            return decodeReadState(await readFile(this.path, "utf8"));
+        }
+        catch (error) {
+            if (hasFileErrorCode(error, "ENOENT"))
+                return null;
+            throw error;
+        }
+    }
+    async save(state) {
+        await mkdir(dirname(this.path), { recursive: true });
+        const temporary = `${this.path}.${process.pid}.${randomUUID()}.tmp`;
+        try {
+            await writeFile(temporary, JSON.stringify(state), "utf8");
+            await rename(temporary, this.path);
+        }
+        catch (error) {
+            await rm(temporary, { force: true }).catch(() => undefined);
+            throw error;
+        }
+    }
+    async transaction(operation) {
+        const prior = pendingWrites.get(this.path) ?? Promise.resolve();
+        const pending = prior
+            .catch(() => undefined)
+            .then(async () => {
+            const existing = await this.load();
+            const state = existing ?? {
+                version: 1,
+                initializedAt: this.initializedAt,
+                cursors: [],
+            };
+            const before = JSON.stringify(state);
+            const result = await operation(state);
+            if (!existing || JSON.stringify(state) !== before)
+                await this.save(state);
+            return result;
+        });
+        pendingWrites.set(this.path, pending);
+        try {
+            return await pending;
+        }
+        finally {
+            if (pendingWrites.get(this.path) === pending)
+                pendingWrites.delete(this.path);
+        }
+    }
+    initialize() {
+        return this.transaction(() => undefined);
+    }
+    reset(sessionId, now) {
+        return this.transaction((state) => {
+            const cursors = new Map(state.cursors);
+            const previous = cursors.get(sessionId);
+            cursors.set(sessionId, {
+                messageId: "",
+                createdAt: 0,
+                lastReadAt: Math.max(now, (previous?.lastReadAt ?? state.initializedAt) + 1),
+            });
+            state.cursors = [...cursors];
+        });
+    }
+    forget(sessionId) {
+        return this.transaction((state) => {
+            state.cursors = state.cursors.filter(([id]) => id !== sessionId);
+        });
+    }
+}

package/docs/configuration.md

@@ -143,7 +143,21 @@ storage, privacy, retrieval, and management behavior.
 
 ## Paths
 
-`environment.paths.runtimeDir` is environment-local generated runtime state.
+`environment.paths.runtimeDir` is the generated runtime state base. A named
+environment profile without its own `paths.runtimeDir` uses
+`<base>/environments/<sha256(profileId)>`. The stable profile ID determines that
+directory; changing models or adding another profile does not move its state.
+`LLM_RUNTIME_DIR` takes precedence over profile paths and acts as the shared base
+when a profile is selected. Without a selected profile, the existing runtime
+directory layout is unchanged.
+
+An explicit `environment.profiles.<id>.paths.runtimeDir` is already a final
+environment directory and is preserved when there is no `LLM_RUNTIME_DIR`
+override. Explicit session, attachment and trace path overrides also remain
+final paths. Use distinct final paths for different environments. The resolved
+runtime directory owns local hosting, scheduling, passive memory, plugin state,
+and the default session, attachment and log paths. Shared, compiled, workspace
+and agent-work directories retain their configured sharing behavior.
 `environment.paths.attachmentsDir` stores runtime-managed attachment files
 referenced by session/request metadata. Images and supported document files
 share this store; document contents are read on demand by a request-bound tool
@@ -220,6 +234,32 @@ LLM_RUNTIME_PROFILE=dev npm run dev
 
 The active profile id becomes the runtime id used by the bridge.
 
+Existing populated state in an inherited base is never automatically moved or
+silently replaced by an empty environment. Loading stops with
+`runtime_environment_storage_assignment_required` until that state is explicitly
+assigned. For example, to retain an existing `prod` environment at `.runtime`
+and add an isolated `dev` environment:
+
+```json
+{
+  "environment": {
+    "default": "prod",
+    "paths": { "runtimeDir": ".runtime" },
+    "profiles": {
+      "prod": { "paths": { "runtimeDir": ".runtime" } },
+      "dev": {}
+    }
+  }
+}
+```
+
+This leaves existing Jobs and conversations in place and gives `dev` its own
+namespace. Preserve any previous explicit session, attachment and trace paths
+on the assigned profile too. Remove a shared `LLM_RUNTIME_DIR` override before
+making this assignment because environment variables keep their precedence.
+The stored Jobs must retain their original environment ID. Empty state folders
+and intentionally shared or compiled artifacts do not require assignment.
+
 ## Request Runner
 
 The runtime config owns host wiring, installed models, and plugin availability.

package/docs/long-term-memory.md

@@ -1,9 +1,10 @@
 # Passive Long-Term Memory
 
 ABot Runtime can retain selected user facts and preferences across sessions.
-This feature is passive: the model does not invoke a memory tool, and the
-Runtime core remains the only owner of retrieval, filtering, deduplication,
-storage, and deletion.
+Memory is stored in a Runtime-owned pool. The Runtime core owns retrieval,
+filtering, deduplication, storage, and deletion. The root model can request a
+focused recall through its built-in decision contract without invoking a plugin
+tool.
 
 Long-term memory is disabled by default. Enabling it is an explicit consumer
 choice because it may persist personal information between conversations.
@@ -47,8 +48,47 @@ reference context; it is never treated as a new user request or an instruction.
 
 Retrieval, candidate policy, filtering, deduplication, and persistence are
 shared by `supervisor.response` and `execution.response`; only their authoring
-contracts differ. Decision, planning, Worker, Reviewer, payload, and tool
-contexts do not receive the long-term memory projection.
+contracts differ. Automatic retrieval remains a terminal-response feature.
+Planner, Worker, Reviewer, payload, and tool contexts do not receive the memory
+projection.
+
+## Model-Requested Recall
+
+When memory is enabled, the Supervisor and Execution Agent root decisions may
+choose `recall_memory` with a concise query about a remembered fact or preference.
+This is an internal Runtime context request: it requires no plugin, capability
+selection, controls, payload generation, or delegated role.
+
+The existing memory service performs the search. The root receives a bounded
+passive result and then chooses its next action in the same request loop:
+
+- `found`: recalled records with their ids, provenance, and timestamps.
+- `empty`: the search returned no matching records.
+- `unavailable`: retrieval could not supply records; this does not mean the pool
+  contains no relevant memory.
+
+Queries have a 1,024-character limit. Results contain at most six whole records
+within a 6,000-character serialized budget; the combined root context uses the
+same bound and declares omitted records and recalls. The request's existing
+activation limit also applies to recall. `longTermMemory.maxRecallCallsPerRequest`
+sets the maximum number of explicit lookups per user request (default: 5, a
+positive integer). After that many calls, the model no longer receives the
+`recall_memory` action. The request continues normally, with earlier recall
+results still available. Changing the query or steering the active request does
+not reset this count; a new request starts fresh. No independent retry loop is
+introduced.
+The result is bound to the requesting root and current user steering version;
+superseded results are not projected into later decisions. Recalled facts are
+reference data, not new instructions or proof that work completed.
+
+The final response reuses explicit recall results without another automatic
+search. If the model does not request recall, the ordinary automatic terminal
+retrieval remains unchanged. Saving memory candidates keeps its existing
+background lifecycle in both execution policies.
+
+Recall still depends on the configured embedding provider. A stale vector index
+may be rebuilt during search, so the shorter orchestration path does not imply a
+fixed latency or offline lexical fallback.
 
 Both response paths also share the same configured response-experience
 methodology. It applies whether memory is enabled or disabled. Relevant memory
@@ -107,6 +147,7 @@ to it:
   "longTermMemory": {
     "enabled": true,
     "emitClientEvents": false,
+    "maxRecallCallsPerRequest": 5,
     "embeddingProfileId": "memory-embedding"
   }
 }

package/docs/runtime-invariant-coverage.md

@@ -10,7 +10,7 @@ the default `supervisor-worker-v1` policy and the opt-in
 | The handler resolves one compiled execution policy from the selected model profile and supplies its same authority to capability composition and the runner. Omission remains `supervisor-worker-v1`.                                                                                                                                                                                                                                                                       | `src/runtime/model/model-selection.ts`, `src/runtime/request/handler.ts`, `src/runtime/request/role-executor-composition.ts`                                                                                                                           | `model-execution-policy.test.ts`, `request-execution-policy-composition.test.ts`                                                                                                                                                             |
 | `supervisor-worker-v1` retains the delegated Supervisor, Planner, Worker, and Reviewer contracts; `execution-agent-v1` changes model-facing contracts and authority without adding another runner, ledger, reducer, capability engine, or finalizer.                                                                                                                                                                                                                        | `src/runtime/request/root-execution-kernel.ts`, `src/runtime/request/role-executor-composition.ts`                                                                                                                                                     | `root-execution-kernel-policy-mechanics.test.ts`, `supervisor-request-runner.test.ts`, `execution-agent-request-runner.test.ts`                                                                                                              |
 | Role choice is model-owned and limited to the exact subordinate contracts registered by the frozen policy.                                                                                                                                                                                                                                                                                                                                                                  | `src/runtime/steps/*`, `src/runtime/orchestration/role-executors/`, `src/runtime/orchestration/role-calls/`                                                                                                                                            | `role-executor-registry.test.ts`, `planner-decision.test.ts`, `execution-agent-advisory-executors.test.ts`                                                                                                                                   |
-| Every subordinate result returns to its exact caller through an exact-head ledger v17 commit. Under `supervisor-worker-v1`, terminal Planner and Worker results receive a runtime-owned, constant-size `work_result_v1` receipt; supplied work receipts are rejected, lineage is derived and fingerprint-verified from that ledger, and `execution-agent-v1` receives none. Planner Graph and Auditor outputs remain passive terminal child results.                        | `src/runtime/orchestration/role-calls/`, `src/runtime/steps/planner-graph/`, `src/runtime/steps/auditor-decision/`                                                                                                                                     | `role-call-ledger.test.ts`, `role-call-work-result-receipt-reducer.test.ts`, `role-call-planner-work-result-receipt.test.ts`, `execution-agent-advisory-executors.test.ts`, `supervisor-request-runner.test.ts`                              |
+| Every subordinate result returns to its exact caller through an exact-head ledger v18 commit. Under `supervisor-worker-v1`, terminal Planner and Worker results receive a runtime-owned, constant-size `work_result_v1` receipt; supplied work receipts are rejected, lineage is derived and fingerprint-verified from that ledger, and `execution-agent-v1` receives none. Planner Graph and Auditor outputs remain passive terminal child results.                        | `src/runtime/orchestration/role-calls/`, `src/runtime/steps/planner-graph/`, `src/runtime/steps/auditor-decision/`                                                                                                                                     | `role-call-ledger.test.ts`, `role-call-work-result-receipt-reducer.test.ts`, `role-call-planner-work-result-receipt.test.ts`, `execution-agent-advisory-executors.test.ts`, `supervisor-request-runner.test.ts`                              |
 | Planner's semantic contract requires declaring every currently known execution outcome before the first child dispatch; schema and parser mechanically bind exactly one independently completable production item per Worker dispatch. A directly bound Worker receives that item, explicit dependencies, supervision evidence, and its own capability-result lane without the broader request, Planner objective, or sibling execution summaries.                          | `src/runtime/steps/planner-decision/`, `src/runtime/steps/worker-decision/`, `src/runtime/context/request-tool-results.ts`                                                                                                                             | `planner-plan-contract.test.ts`, `planner-single-item-dispatch.test.ts`, `planner-worker-context-isolation.test.ts`, `planner-worker-tool-result-scope.test.ts`                                                                              |
 | Capability authority is validated against the frozen policy and bound to the exact authorized call and activation: Worker for the default policy, canonical root for the direct policy. Both use the same binding and adapter engine.                                                                                                                                                                                                                                       | `src/runtime/orchestration/role-calls/`, `src/runtime/orchestration/worker-capabilities/`, `src/runtime/request/root-execution-kernel.ts`                                                                                                              | `root-execution-kernel-policy-mechanics.test.ts`, `worker-capability-binding.test.ts`, `execution-agent-request-runner.test.ts`                                                                                                              |
 | Worker and root payloads use the same `tool_payload.raw` author; principal, controls, runtime-issued direct-Planner-item receipt, and admitted evidence are mechanically bounded before model invocation. Root and non-Planner Worker payloads retain the exact request source; a canonically bound Planner item omits it. Work-result receipts and derived lineage are stripped before Worker raw payload and result authoring while optional semantic checkpoints remain. | `src/runtime/orchestration/worker-capabilities/payload-author.ts`, `src/runtime/request/worker-capability-payload.ts`, `src/runtime/steps/worker-decision/`                                                                                            | `planner-worker-context-isolation.test.ts`, `registered-tool-worker-assignment-provenance.test.ts`, `worker-capability-payload-author.test.ts`, `worker-payload-dependency-projection-pr1.test.ts`, `execution-agent-request-runner.test.ts` |