@abot-ai/runtime 1.2.0 → 1.3.1

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` |

package/docs/runtime-library.md

@@ -41,12 +41,35 @@ const handle = runtime.host.start({
   toolRegistry: runtime.tools,
 });
 
+await handle.ready;
+
 process.on("SIGINT", async () => {
   await handle.stop();
   process.exit(0);
 });
 ```
 
+The default host starts the scheduler automatically, including persisted Jobs.
+Overlapping handles for the same scheduler share its lifetime: `stop()` closes
+that handle's Bridge, and only the last handle stops the scheduler. `start()` remains
+synchronous for compatibility; the optional `ready` promise exposes asynchronous
+startup errors and requests wait for readiness. A failed startup releases its own
+resources even when a consumer does not read `ready`. Custom injected hosts may
+keep the existing `{ stop }` handle.
+
+Supply adapter overrides before starting a host. A different session store,
+configuration, model client, attachment store, tool registry or memory service
+rebuilds the scheduler's request graph as well as ordinary requests. Session
+storage remains backed by the injected store, through the composed deletion
+guard. Use the host's effective graph consistently; do not start the original
+graph alongside its replacement against the same scheduler directory. An event
+observer override alone keeps the existing admission and scheduler lifetime.
+
+Session deletion finishes attachment cleanup before acknowledging the deletion
+receipt. An explicit repeat retries only failed cleanup, through the same owner
+for Web, Bridge and local clients. Web shutdown closes HTTP/WebSocket intake and
+prevents new environment initialization before awaiting pending startup work.
+
 ## Runtime Config
 
 The default host reads `runtime.config.json`, then lets environment variables

package/docs/runtime-public-contracts.md

@@ -131,7 +131,9 @@ not create `planner.plan.*` state or events.
 Runtime capabilities use the stable tool event envelope. Adapter-owned
 presentation metadata supplies the tool, operation and action type; target
 metadata contains only resolved logical paths. Physical
-roots, opaque subject identities and authored payload bodies are never exposed.
+roots and opaque subject identities are never exposed. A plugin may opt into
+bounded input or result excerpts through its declared event presentation.
+These excerpts are display data, not additional model instructions or evidence.
 These events describe capability execution only. Only `planner.plan.*` events
 report canonical item-status changes or semantic progress.
 
@@ -146,6 +148,31 @@ Tool events use the current tool execution boundary:
 A `tool.completed` event with `ok: true` proves only that the tool step
 succeeded. It does not prove the user request is complete.
 
+Registered-tool events may include an optional `executionId` shared by their
+payload, approval and execution stages. Clients correlate with
+`(requestId, executionId)` rather than matching tool names or arrival order.
+Payload publication still occurs after canonical admission. Older events without
+this field do not establish a lifecycle pairing.
+
+The same adapter boundary may include `executorRole` and `roleCallId` from the
+canonical role call. Clients can place the action under its executor even when
+the active role has changed before completion. These fields are display identity;
+they do not change runtime stages, tool parameters, approval inputs or evidence.
+The root role identifier remains `supervisor` regardless of its selected contract.
+
+`eventPresentation.resultMetadata` maps optional display keys to existing tool
+result fields through `{path, kind}` descriptors. Paths select `output` or an
+own-property path under `data` (at most four segments). Kinds are `preview`,
+`number` and `boolean`, with at most 16 mappings. A preview is limited to 1,200
+characters and 20 lines, with a 2,400-character total preview budget per event;
+its companion `<key>Truncated` flag describes preview clipping, independently
+of source-result truncation. Missing or mismatched fields are omitted. Valid
+declared values take precedence over generic metadata; omitted fields retain
+the existing fallback metadata. Projection
+does not mutate tool results, canonical evidence, action references or model
+context. The client renders excerpts as inert text and never reconstructs an
+old result by re-reading the current file or memory store.
+
 ## ToolRegistry
 
 `ToolRegistry` owns active tool capability discovery and execution:
@@ -177,6 +204,10 @@ retained for compatibility. They must not select a request path or role.
 Model-facing availability and controls come from the registered
 `normalInvocation` contract.
 
+A normal-invocation contract accepts at most 32 operations. This bounds the
+registered operation catalog; it does not limit invocation frequency or the
+number of user-created scheduled Jobs.
+
 Every plugin-handler return is normalized by `ToolRegistry` into one complete
 `ToolExecutionResult`, whether the operation succeeds or fails. The selected
 tool identity is Runtime-owned; plugins provide the operation result. The

package/package.json

@@ -83,6 +83,8 @@
     "dist/src/web-ui/",
     "runtime.config.schema.json",
     "src/runtime/README.md",
+    "src/runtime/scheduler/README.md",
+    "src/runtime/local-host/README.md",
     "LICENSE",
     "docs/architecture.md",
     "docs/bridge-compatibility.md",
@@ -172,5 +174,5 @@
   },
   "type": "module",
   "types": "./dist/src/runtime/index.d.ts",
-  "version": "1.2.0"
+  "version": "1.3.1"
 }

package/plugins/code-outline/plugin.json

@@ -17,6 +17,21 @@
         "inspect_code_outline": {
           "description": "Extract a bounded outline of symbols, selectors, elements, and imports from one source file beneath the configured agent work directory or configured workspace sources, without returning the full file.",
           "routingCapability": "semantic_lookup",
+          "eventPresentation": {
+            "metadata": {
+              "displayTarget": { "param": "path", "kind": "string" },
+              "maxSymbols": { "param": "maxSymbols", "kind": "number" }
+            },
+            "resultMetadata": {
+              "outputPreview": { "path": "output", "kind": "preview" },
+              "lineCount": { "path": "data.lineCount", "kind": "number" },
+              "returnedItemCount": { "path": "data.truncation.returnedSymbols", "kind": "number" },
+              "totalItemCount": { "path": "data.truncation.totalSymbols", "kind": "number" },
+              "sourceTruncated": { "path": "data.truncation.symbolsTruncated", "kind": "boolean" },
+              "importsTruncated": { "path": "data.truncation.importsTruncated", "kind": "boolean" },
+              "outputTruncated": { "path": "data.truncation.output.truncated", "kind": "boolean" }
+            }
+          },
           "runtimePathBindings": [
             {
               "operationId": "inspect_code_outline",

package/plugins/document-reader/plugin.json

@@ -13,6 +13,23 @@
           "description": "Extract bounded text from an attached or configured-root PDF, DOCX, XLSX, PPTX, TXT, CSV, Markdown, JSON, or RTF document. Use source for an attachment id/name or configured-root path. Use source_mode=working_path with path for a runtime/session artifact beneath the current execution working directory. Document bytes remain outside model context, and results expose only attachment identities or logical runtime paths.",
           "routingCapability": "filesystem_inspection",
           "developmentRoles": ["inspect", "verify"],
+          "eventPresentation": {
+            "metadata": {
+              "source": { "param": "source", "kind": "string" },
+              "displayTarget": { "param": "path", "kind": "string" },
+              "sourceMode": { "param": "source_mode", "kind": "string" },
+              "startChar": { "param": "start_char", "kind": "number" },
+              "maxChars": { "param": "max_chars", "kind": "number" }
+            },
+            "resultMetadata": {
+              "outputPreview": { "path": "output", "kind": "preview" },
+              "startChar": { "path": "data.startChar", "kind": "number" },
+              "endChar": { "path": "data.endChar", "kind": "number" },
+              "totalCharacters": { "path": "data.totalCharacters", "kind": "number" },
+              "inputBytes": { "path": "data.inputBytes", "kind": "number" },
+              "sourceTruncated": { "path": "data.truncated", "kind": "boolean" }
+            }
+          },
           "runtimePathBindings": [
             {
               "operationId": "read_document",

package/plugins/exec/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "exec",
   "version": "1.0.0",
-  "description": "Execute, observe, and cancel bounded non-interactive Linux /bin/bash processes.",
+  "description": "Execute, observe, and cancel bounded non-interactive /bin/bash processes on Linux and macOS.",
   "extensions": {
     "ai.abot.runtime": {
       "version": 1,
@@ -19,7 +19,7 @@
       "capabilities": {
         "exec": {
           "catalogGroups": ["read", "write", "exec"],
-          "description": "Execute one bounded non-interactive Linux /bin/bash command. The explicit cwd must resolve inside agent work or the configured workspace; `.` means the agent-work root and `workspace/...` selects the workspace. The shell itself runs with the runtime process permissions and is not an operating-system sandbox. A command still running after the foreground window yields a process ID and cursor that exec_wait can resume without restarting it. Prefer dedicated inspection and file-mutation capabilities when they can express the task.",
+          "description": "Execute one bounded non-interactive /bin/bash command on Linux or macOS. The explicit cwd must resolve inside agent work or the configured workspace; `.` means the agent-work root and `workspace/...` selects the workspace. The shell itself runs with the runtime process permissions and is not an operating-system sandbox. A command still running after the foreground window yields a process ID and cursor that exec_wait can resume without restarting it. Prefer dedicated inspection and file-mutation capabilities when they can express the task.",
           "routingCapability": "filesystem_inspection",
           "developmentRoles": ["inspect", "establish", "verify", "auxiliary"],
           "eventPresentation": {
@@ -31,7 +31,7 @@
           "skills": ["exec_skill"],
           "operations": {
             "execute_command": {
-              "summary": "Execute one bounded non-interactive Linux /bin/bash command in an explicit existing agent-work or workspace directory. The cwd boundary is not an OS sandbox. Full-access availability does not authorize servers, GUI automation, installs, service changes, background work, or other sensitive effects.",
+              "summary": "Execute one bounded non-interactive /bin/bash command on Linux or macOS in an explicit existing agent-work or workspace directory. The cwd boundary is not an OS sandbox. Full-access availability does not authorize servers, GUI automation, installs, service changes, background work, or other sensitive effects.",
               "input": {
                 "type": "object",
                 "additionalProperties": false,

package/plugins/exec/skills/exec_skill/SKILL.md

@@ -1,7 +1,7 @@
 # Exec Skill
 
 - Use `exec` for narrow shell-native discovery or verification when a dedicated tool is insufficient.
-- `exec` v1 is available only on Linux with executable `/bin/bash`; it does not select a Windows shell or another fallback shell.
+- `exec` is available on Linux and macOS with executable `/bin/bash`; it does not select a Windows shell or another fallback shell. Commands must use the utilities and options available on the host.
 - Resolve `.` and ordinary relative `cwd` values from the configured agent work directory. They are never rewritten to the active Worker working directory. Use `workspace/...` only when the configured workspace is explicitly intended.
 - Always provide an explicit existing `cwd`. For an existing project, use its project path. To create a new project, use an existing parent `cwd` (normally `.`) and create the project path in the command.
 - The cwd is restricted to configured roots, but the shell runs with the runtime process permissions and is not an operating-system sandbox.

package/plugins/exec/source/process-manager.ts

@@ -1,6 +1,4 @@
 import { spawn, type ChildProcessByStdio } from "node:child_process";
-import { constants } from "node:fs";
-import { access } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import type { Readable } from "node:stream";
 import { StringDecoder } from "node:string_decoder";
@@ -8,13 +6,13 @@ import { StringDecoder } from "node:string_decoder";
 import { sanitizeJsonText } from "../../../src/plugin-sdk/index.js";
 
 import { ExecPluginError } from "./errors.js";
+import { assertSupportedShell, EXEC_SHELL } from "./shell-platform.js";
 import type {
   ExecProcessSnapshot,
   ExecStreamSnapshot,
   ExecTerminationReason,
 } from "./types.js";
 
-const EXEC_SHELL = "/bin/bash";
 const COMPLETED_PROCESS_RETENTION_MS = 5 * 60_000;
 const MAX_ACTIVE_PROCESSES_PER_SCOPE = 4;
 
@@ -115,23 +113,6 @@ export type ExecProcessManager = Readonly<{
   release(processId: string, scope: string): Promise<void>;
 }>;
 
-async function assertSupportedShell(): Promise<void> {
-  if (process.platform !== "linux") {
-    throw new ExecPluginError(
-      "exec_platform_unsupported",
-      "The exec plugin v1 requires Linux and /bin/bash.",
-    );
-  }
-  try {
-    await access(EXEC_SHELL, constants.X_OK);
-  } catch {
-    throw new ExecPluginError(
-      "exec_shell_unavailable",
-      "The exec plugin cannot start because executable /bin/bash is unavailable.",
-    );
-  }
-}
-
 export function createExecProcessManager(): ExecProcessManager {
   const processes = new Map<string, ManagedExecProcess>();
 

package/plugins/exec/source/shell-platform.ts

@@ -0,0 +1,29 @@
+import { constants } from "node:fs";
+import { access } from "node:fs/promises";
+
+import { ExecPluginError } from "./errors.js";
+
+export const EXEC_SHELL = "/bin/bash";
+
+function isSupportedExecPlatform(platform: NodeJS.Platform): boolean {
+  return platform === "linux" || platform === "darwin";
+}
+
+export async function assertSupportedShell(
+  platform: NodeJS.Platform = process.platform,
+): Promise<void> {
+  if (!isSupportedExecPlatform(platform)) {
+    throw new ExecPluginError(
+      "exec_platform_unsupported",
+      "The exec plugin requires Linux or macOS and executable /bin/bash.",
+    );
+  }
+  try {
+    await access(EXEC_SHELL, constants.X_OK);
+  } catch {
+    throw new ExecPluginError(
+      "exec_shell_unavailable",
+      "The exec plugin cannot start because executable /bin/bash is unavailable.",
+    );
+  }
+}

package/plugins/exec/src/index.cjs

@@ -558,11 +558,34 @@ function resolveExecScopedPath(pluginContext, executionContext, rawPath, cwd) {
 
 // plugins/exec/source/process-manager.ts
 var import_node_child_process = require("node:child_process");
-var import_node_fs2 = require("node:fs");
-var import_promises3 = require("node:fs/promises");
 var import_node_crypto2 = require("node:crypto");
 var import_node_string_decoder = require("node:string_decoder");
+
+// plugins/exec/source/shell-platform.ts
+var import_node_fs2 = require("node:fs");
+var import_promises3 = require("node:fs/promises");
 var EXEC_SHELL = "/bin/bash";
+function isSupportedExecPlatform(platform) {
+  return platform === "linux" || platform === "darwin";
+}
+async function assertSupportedShell(platform = process.platform) {
+  if (!isSupportedExecPlatform(platform)) {
+    throw new ExecPluginError(
+      "exec_platform_unsupported",
+      "The exec plugin requires Linux or macOS and executable /bin/bash."
+    );
+  }
+  try {
+    await (0, import_promises3.access)(EXEC_SHELL, import_node_fs2.constants.X_OK);
+  } catch {
+    throw new ExecPluginError(
+      "exec_shell_unavailable",
+      "The exec plugin cannot start because executable /bin/bash is unavailable."
+    );
+  }
+}
+
+// plugins/exec/source/process-manager.ts
 var COMPLETED_PROCESS_RETENTION_MS = 5 * 6e4;
 var MAX_ACTIVE_PROCESSES_PER_SCOPE = 4;
 var CappedTextBuffer = class {
@@ -602,22 +625,6 @@ var CappedTextBuffer = class {
     });
   }
 };
-async function assertSupportedShell() {
-  if (process.platform !== "linux") {
-    throw new ExecPluginError(
-      "exec_platform_unsupported",
-      "The exec plugin v1 requires Linux and /bin/bash."
-    );
-  }
-  try {
-    await (0, import_promises3.access)(EXEC_SHELL, import_node_fs2.constants.X_OK);
-  } catch {
-    throw new ExecPluginError(
-      "exec_shell_unavailable",
-      "The exec plugin cannot start because executable /bin/bash is unavailable."
-    );
-  }
-}
 function createExecProcessManager() {
   const processes = /* @__PURE__ */ new Map();
   const unknownProcess = () => new ExecPluginError(

package/plugins/filesystem/plugin.json

@@ -26,6 +26,9 @@
               "startLine": { "param": "start_line", "kind": "number" },
               "endLine": { "param": "end_line", "kind": "number" },
               "locator": { "param": "locator", "kind": "string" }
+            },
+            "resultMetadata": {
+              "outputPreview": { "path": "output", "kind": "preview" }
             }
           },
           "skills": [],
@@ -77,7 +80,11 @@
           "developmentRoles": ["mutate"],
           "eventPresentation": {
             "metadata": {
-              "path": { "param": "path", "kind": "string" }
+              "path": { "param": "path", "kind": "string" },
+              "inputPreview": { "param": "instruction", "kind": "string" }
+            },
+            "resultMetadata": {
+              "outputPreview": { "path": "output", "kind": "preview" }
             }
           },
           "payloadChannelSpec": {
@@ -177,6 +184,10 @@
           "eventPresentation": {
             "metadata": {
               "path": { "param": "path", "kind": "string" }
+            },
+            "resultMetadata": {
+              "outputPreview": { "path": "output", "kind": "preview" },
+              "sourceTruncated": { "path": "data.truncation.truncated", "kind": "boolean" }
             }
           },
           "skills": ["read_file_skill"],
@@ -208,7 +219,11 @@
           "developmentRoles": ["establish", "mutate"],
           "eventPresentation": {
             "metadata": {
-              "path": { "param": "path", "kind": "string" }
+              "path": { "param": "path", "kind": "string" },
+              "inputPreview": { "param": "content", "kind": "string" }
+            },
+            "resultMetadata": {
+              "outputPreview": { "path": "output", "kind": "preview" }
             }
           },
           "payloadChannelSpec": {

package/plugins/filesystem/source/atomic-write.ts

@@ -11,6 +11,7 @@ import {
 } from "./bounded-io.js";
 import { fail, isNodeErrorCode, rethrowFilesystemError } from "./errors.js";
 import { openMutationParent } from "./mutation-parent.js";
+import { writeWithDirectoryAuthority } from "./directory-authority-write.js";
 
 export async function atomicWriteText(
   input: Readonly<{
@@ -20,6 +21,10 @@ export async function atomicWriteText(
   }>,
 ): Promise<void> {
   assertMutationContentSize(input.content);
+  if (requiresIsolatedDirectoryAuthority()) {
+    await writeWithDirectoryAuthority(input);
+    return;
+  }
   const parent = await openMutationParent(input.target);
   const targetPath = `${parent.procPath}/${parent.targetName}`;
   const anchoredTarget = Object.freeze({
@@ -113,3 +118,7 @@ async function syncDirectoryBestEffort(
     // The prepared file itself is always synced before the atomic install.
   }
 }
+
+function requiresIsolatedDirectoryAuthority(): boolean {
+  return process.platform === "darwin";
+}

package/plugins/filesystem/source/bounded-io.ts

@@ -1,12 +1,6 @@
 import { createHash } from "node:crypto";
 import { constants, type BigIntStats } from "node:fs";
-import {
-  opendir,
-  open,
-  realpath,
-  stat,
-  type FileHandle,
-} from "node:fs/promises";
+import { open, realpath, stat, type FileHandle } from "node:fs/promises";
 import { relative, sep } from "node:path";
 import { StringDecoder } from "node:string_decoder";
 import { TextDecoder } from "node:util";
@@ -19,7 +13,10 @@ export const MAX_MUTATION_BYTES = 1_048_576;
 export const READ_HEAD_BYTES = 24_576;
 export const READ_TAIL_BYTES = 12_288;
 export const DEV_SCAN_BYTES = 1_048_576;
-export const DIRECTORY_ENTRY_LIMIT = 160;
+export {
+  readDirectorySample,
+  DIRECTORY_ENTRY_LIMIT,
+} from "./directory-sample.js";
 
 export type BoundedText = Readonly<{
   text: string;
@@ -350,97 +347,6 @@ export function assertMutationContentSize(content: string): number {
   return byteCount;
 }
 
-export async function readDirectorySample(
-  target: ResolvedRuntimeToolPath,
-): Promise<Readonly<{ entries: readonly string[]; truncated: boolean }>> {
-  const entries: string[] = [];
-  let handle: FileHandle | undefined;
-  try {
-    if (
-      typeof constants.O_DIRECTORY !== "number" ||
-      typeof constants.O_NOFOLLOW !== "number"
-    ) {
-      fail(
-        "filesystem_safe_io_unsupported",
-        "This platform does not provide the no-follow directory operation required for a safe read.",
-      );
-    }
-    handle = await open(
-      target.absolutePath,
-      constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW,
-    );
-    const before = await handle.stat({ bigint: true });
-    if (!before.isDirectory()) {
-      fail("not_a_directory", `Expected a directory: ${target.logicalPath}`);
-    }
-    const [canonicalRoot, canonicalTarget] = await Promise.all([
-      realpath(target.rootPath),
-      realpath(target.absolutePath),
-    ]);
-    const rootRelative = relative(canonicalRoot, canonicalTarget);
-    if (
-      rootRelative === ".." ||
-      rootRelative.startsWith(`..${sep}`) ||
-      rootRelative.startsWith(sep)
-    ) {
-      fail(
-        "filesystem_path_changed",
-        `Directory changed outside its configured root: ${target.logicalPath}`,
-      );
-    }
-    const pathIdentity = await stat(canonicalTarget, { bigint: true });
-    if (
-      !pathIdentity.isDirectory() ||
-      pathIdentity.dev !== before.dev ||
-      pathIdentity.ino !== before.ino
-    ) {
-      fail(
-        "filesystem_path_changed",
-        `Directory changed while it was being opened: ${target.logicalPath}`,
-      );
-    }
-    const directory = await opendir(`/proc/self/fd/${handle.fd}`);
-    for await (const entry of directory) {
-      if (entries.length >= DIRECTORY_ENTRY_LIMIT) {
-        await assertDirectoryStable(handle, before, target.logicalPath);
-        entries.sort((left, right) => left.localeCompare(right));
-        return Object.freeze({
-          entries: Object.freeze(entries),
-          truncated: true,
-        });
-      }
-      entries.push(`${entry.name}${entry.isDirectory() ? "/" : ""}`);
-    }
-    await assertDirectoryStable(handle, before, target.logicalPath);
-    entries.sort((left, right) => left.localeCompare(right));
-    return Object.freeze({ entries: Object.freeze(entries), truncated: false });
-  } catch (error: unknown) {
-    return rethrowFilesystemError(error, "inspect", target.logicalPath);
-  } finally {
-    await handle?.close().catch(() => undefined);
-  }
-}
-
-async function assertDirectoryStable(
-  handle: FileHandle,
-  before: BigIntStats,
-  logicalPath: string,
-): Promise<void> {
-  const after = await handle.stat({ bigint: true });
-  if (
-    !after.isDirectory() ||
-    after.dev !== before.dev ||
-    after.ino !== before.ino ||
-    after.mtimeNs !== before.mtimeNs ||
-    after.ctimeNs !== before.ctimeNs
-  ) {
-    fail(
-      "filesystem_read_changed",
-      `Directory changed while it was being read: ${logicalPath}`,
-    );
-  }
-}
-
 function rejectBinary(buffer: Buffer, logicalPath: string): void {
   if (buffer.includes(0)) {
     fail(

package/plugins/filesystem/source/directory-authority-write.ts

@@ -0,0 +1,64 @@
+import type { ResolvedRuntimeToolPath } from "../../../src/plugin-sdk/index.js";
+import {
+  DirectoryAuthorityError,
+  runDirectoryAuthorityTask,
+} from "../../../src/shared/directory-authority/index.js";
+import type { MutationTargetVersion } from "./bounded-io.js";
+import { fail, rethrowFilesystemError } from "./errors.js";
+import { openMutationRoot } from "./mutation-parent.js";
+import {
+  commitDirectoryWrite,
+  type DirectoryWriteInput,
+} from "./directory-write-task.js";
+
+export async function writeWithDirectoryAuthority(
+  input: Readonly<{
+    target: ResolvedRuntimeToolPath;
+    content: string;
+    expectedVersion: MutationTargetVersion;
+  }>,
+): Promise<void> {
+  const root = await openMutationRoot(input.target);
+  const expected = input.expectedVersion;
+  const expectedVersion: DirectoryWriteInput["expectedVersion"] =
+    expected.kind === "absent"
+      ? { kind: "absent" }
+      : {
+          ...expected,
+          device: String(expected.device),
+          inode: String(expected.inode),
+          modifiedNs: String(expected.modifiedNs),
+          changedNs: String(expected.changedNs),
+        };
+  try {
+    await runDirectoryAuthorityTask({
+      directoryPath: input.target.rootPath,
+      directoryFd: root.fd,
+      input: {
+        relativePath: input.target.relativePath,
+        content: input.content,
+        expectedVersion,
+      },
+      task: commitDirectoryWrite,
+    });
+  } catch (error) {
+    if (error instanceof DirectoryAuthorityError) {
+      if (error.code.startsWith("filesystem_")) {
+        fail(
+          error.code,
+          `Safe write failed: ${input.target.logicalPath}`,
+          error.data,
+        );
+      }
+      if (error.code.startsWith("directory_authority_")) {
+        fail(
+          "filesystem_path_changed",
+          `Directory authority was lost: ${input.target.logicalPath}`,
+        );
+      }
+    }
+    rethrowFilesystemError(error, "write", input.target.logicalPath);
+  } finally {
+    await root.close().catch(() => undefined);
+  }
+}

package/plugins/filesystem/source/directory-sample-task.ts

@@ -0,0 +1,23 @@
+/** Self-contained trusted task, run with an already verified directory cwd. */
+export async function sampleDirectoryTask(
+  input: Readonly<{ maxEntries: number }>,
+): Promise<
+  Readonly<{
+    entries: readonly string[];
+    truncated: boolean;
+  }>
+> {
+  const { opendir } =
+    require("node:fs/promises") as typeof import("node:fs/promises");
+  const entries: string[] = [];
+  const directory = await opendir(".");
+  for await (const entry of directory) {
+    if (entries.length >= input.maxEntries) {
+      entries.sort((left, right) => left.localeCompare(right));
+      return { entries, truncated: true };
+    }
+    entries.push(`${entry.name}${entry.isDirectory() ? "/" : ""}`);
+  }
+  entries.sort((left, right) => left.localeCompare(right));
+  return { entries, truncated: false };
+}