@abot-ai/runtime 1.2.0 → 1.3.1

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/plugins.md

@@ -300,13 +300,19 @@ Node filesystem APIs do not provide inode compare-and-swap, so a completely
 independent writer that ignores this coordination can still race in the final
 existing-file commit window. Consumers that require stronger multi-process
 coordination must place the work root behind a versioned or transactional store.
-Mutation path traversal requires Linux procfs and no-follow file-descriptor
-support. The plugin fails closed when either safety primitive is unavailable.
-
-The bundled `local-search` plugin also requires Linux procfs and no-follow
-file-descriptor support. It holds the selected file or directory through a
-stable descriptor for the complete ripgrep invocation and fails closed when
-that authority cannot be established.
+Mutation path traversal requires no-follow directory handles. On Linux the
+plugin anchors operations through procfs. On macOS an isolated Node child
+inherits the held directory handle, verifies its current directory against
+that handle, and performs basename-relative operations from the pinned current
+directory. Each descendant transition is verified before mutation. The parent
+Runtime never changes its current directory, and unavailable authority fails
+closed. Directory inspection uses the same platform-specific authority.
+
+The bundled `local-search` plugin holds the selected file or directory through
+a stable descriptor for the complete ripgrep invocation. Linux directory
+searches use procfs; macOS searches inherit the verified current directory of
+an isolated Node child. File content searches use the held input descriptor on
+both platforms. A search fails closed when its authority cannot be established.
 
 All output and structured data must be bounded at the producer. The shared SDK
 reserves wrapper headroom by rejecting plugin results above 128 KiB before they
@@ -316,8 +322,8 @@ and rendered text. A truncated success reports machine-readable truncation
 metadata; an operation that cannot produce a truthful bounded result fails
 explicitly.
 
-The bundled `exec` plugin is intentionally a Linux-only integration with
-non-interactive `/bin/bash`. Its configured working directory is constrained to
+The bundled `exec` plugin supports Linux and macOS with non-interactive
+`/bin/bash`. Commands must use utilities available on the host. Its configured working directory is constrained to
 agent-work or workspace roots, but the shell runs with the Runtime process
 permissions and is not an operating-system sandbox.