comisai 1.0.45 → 1.0.46

package/node_modules/@comis/skills/dist/tools/builtin/orchestrate/orchestrate-durable.d.ts

@@ -0,0 +1,139 @@
+import { type ComisLogger, type DurableRunRecord } from "@comis/core";
+import { type Result } from "@comis/shared";
+/**
+ * The narrow durable-run store port the orchestrate runner needs — the two
+ * methods it calls, a structural subset of the daemon's durable-run store, so
+ * the daemon threads the real store directly and @comis/skills never imports it.
+ */
+export interface OrchestrateDurableRuns {
+    /** Idempotent upsert keyed on `rootRunId`; COALESCE-preserves a prior checkpointRef/scriptRef. */
+    upsertCheckpoint(record: DurableRunRecord): Promise<Result<void, Error>>;
+    /** Read the durable row for a root run id (the resume lookup). */
+    getByRootRun(rootRunId: string): Promise<Result<DurableRunRecord | undefined, Error>>;
+    /**
+     * Mark the row terminal on a NON-resumable completion (success or a non-timeout
+     * failure) so `listResumable` stops re-surfacing a finished run on every boot and
+     * the orphan sweep never false-orphans it — mirroring the graph coordinator /
+     * sub-agent runner terminal write. A structural subset of the daemon's
+     * `DurableRunPort.markCompleted`; optional so a minimal store stub compiles (the
+     * concrete store always provides it, and the runner skips it on a resumable timeout).
+     */
+    markCompleted?(rootRunId: string): Promise<Result<void, Error>>;
+}
+/**
+ * The fs read seam — injected so the resume loader is pure/macOS-unit-testable.
+ * The production default reads the real workspace file.
+ */
+export interface OrchestrateDurableFs {
+    /** Whether the resolved absolute path exists. */
+    exists(absPath: string): boolean;
+    /** Read the pinned script bytes (utf8); the caller catches a throw. */
+    read(absPath: string): string;
+}
+/** The production fs seam — the real workspace read. */
+export declare const defaultOrchestrateDurableFs: OrchestrateDurableFs;
+/** The pinned re-spawn spec the loader resolves — the PINNED bytes are the sole source. */
+export interface ResumeSpec {
+    /** The pinned script path relative to the workspace (`<runId>.<language>`). */
+    readonly scriptRef: string;
+    /** The pinned script bytes — re-spawned VERBATIM, never a re-supplied param. */
+    readonly scriptBytes: string;
+    /** The interpreter language, derived from the scriptRef extension. */
+    readonly language: "ts" | "js" | "py";
+}
+/** Inputs shared by the row builders (the content-free durable pointers + clock). */
+export interface DurableRowInput {
+    /** The tree-stable root run id — the durable row's idempotency key. */
+    readonly rootRunId: string;
+    /** The pinned script path relative to the workspace (`<runId>.<language>`). */
+    readonly scriptRef: string;
+    /** The last checkpoint ref, when one exists (omitted at run start). */
+    readonly checkpointRef?: string;
+    /** The injected wall clock (no ambient-clock read). */
+    readonly nowMs: number;
+}
+/**
+ * Build the resumable durable-run record: a FLAT `spawnTree` (so the resume
+ * engine's DAG-vs-flat discriminator routes it to the flat arm), `status:
+ * "running"` (the boot-resume scan set), the pinned `scriptRef`, and `stepIndex:
+ * -1` (the never-sent sentinel; the store omits the `outward_step` column on the
+ * upsert, so the outward-send counter is untouched). Content-free.
+ */
+export declare function buildResumableRow(input: DurableRowInput): DurableRunRecord;
+/**
+ * Register the run as a resumable durable row at run START (scriptRef set), so a
+ * daemon restart mid-run finds it. Forwards the store's Result — the caller
+ * treats a failure as non-fatal (the run still proceeds; the timeout path
+ * re-affirms the row).
+ */
+export declare function registerDurableRun(runs: OrchestrateDurableRuns, input: DurableRowInput): Promise<Result<void, Error>>;
+/**
+ * The skip-clean decision on a run failure: when the durable store seam is
+ * present (the resume surface is on), re-affirm the row resumable and signal the
+ * runner to SKIP the run-end cleanup, so the pinned script + the last checkpoint
+ * survive for a resume. The re-affirm is best-effort — the row already exists
+ * from run start, so a store error does NOT flip the decision. With no store
+ * seam it is a no-op and the run cleans normally.
+ */
+export declare function markResumable(runs: OrchestrateDurableRuns | undefined, input: DurableRowInput): Promise<{
+    skipCleanup: boolean;
+}>;
+/**
+ * Terminal cleanup for a NON-resumable orchestrate run (success OR a non-timeout
+ * failure): mark the durable row completed — so `listResumable` stops re-surfacing
+ * a finished run and the boot sweep never false-orphans it, mirroring the graph
+ * coordinator / sub-agent runner terminal write — and unlink the pinned
+ * `<runId>.<language>` script at the workspace ROOT (the run-end `cleanupRun` wipes
+ * only `results/`). Only a resumable TIMEOUT keeps the row + script, and it never
+ * calls this. Best-effort: a store/fs failure is logged (never thrown into the
+ * run's terminal path); `markCompleted` absent (a minimal stub) ⇒ that half no-ops.
+ */
+export declare function finalizeCompletedRun(runs: OrchestrateDurableRuns | undefined, input: {
+    rootRunId: string;
+    scriptRef: string;
+    workspacePath: string;
+    runId: string;
+}, logger?: ComisLogger): Promise<void>;
+/** A refusal class resolveScriptSource surfaces to the runner (mapped to a tool error). */
+export interface ResumeInputRefusal {
+    /** The tool-error code the runner throws (a subset of the tool-error codes). */
+    readonly code: "not_implemented" | "not_found";
+    readonly message: string;
+    readonly hint: string;
+}
+/** The resolved script source the runner spawns (fresh params, or the pinned bytes). */
+export interface ResolvedScriptSource {
+    readonly script: string;
+    readonly language: "ts" | "js" | "py";
+    /** The workspace-relative script path (`<runId>.<language>`, or the pinned scriptRef). */
+    readonly scriptName: string;
+}
+/**
+ * Resolve what the runner spawns, applying the fail-CLOSED resume contract:
+ *   - no `resumeRunId` ⇒ the fresh `script`/`language` params;
+ *   - `resumeRunId` with the surface OFF (no store) ⇒ REFUSE `not_implemented`
+ *     (NEVER silently run the caller's `script` — a resume takes no fresh bytes);
+ *   - `resumeRunId` with the surface ON ⇒ load + return the PINNED bytes (the
+ *     `script` param is IGNORED), or REFUSE `not_found` when it can't be loaded.
+ */
+export declare function resolveScriptSource(params: {
+    script: string;
+    language: "ts" | "js" | "py";
+    resumeRunId?: string;
+}, runs: OrchestrateDurableRuns | undefined, fs: OrchestrateDurableFs, ctx: {
+    workspacePath: string;
+    runId: string;
+}): Promise<Result<ResolvedScriptSource, ResumeInputRefusal>>;
+/**
+ * Load the pinned re-spawn spec for a resume: read the durable row, resolve the
+ * pinned `scriptRef` CONFINED under the workspace (a `..`/absolute escape is
+ * refused before any read), and read the pinned bytes. The pinned bytes are the
+ * SOLE source — this loader takes no script param, so a resume can never smuggle
+ * new bytes. Every failure (missing row, no scriptRef, unknown extension, a
+ * missing or unreadable file, a store error, a traversal escape) honest-degrades
+ * to an `err` reason the runner surfaces — never a throw that crashes the run.
+ */
+export declare function loadResumeSpec(runs: OrchestrateDurableRuns, fs: OrchestrateDurableFs, input: {
+    resumeRunId: string;
+    workspacePath: string;
+}): Promise<Result<ResumeSpec, string>>;

package/node_modules/@comis/skills/dist/tools/builtin/orchestrate/orchestrate-durable.js

@@ -0,0 +1,191 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * `orchestrate-durable` — the resumable-durable-row lifecycle for the flat
+ * `orchestrate` runner, kept OUT of the runner so `orchestrate-tool.ts` stays
+ * under the file-size cap (the same extraction that moved the jailed-child
+ * engine into `orchestrate-repair.ts`).
+ *
+ * The flat runner becomes the first RE-RUNNABLE durable kind. When the durable
+ * store seam is threaded (i.e. the resume surface is enabled) the runner:
+ *   1. registers a resumable row carrying the PINNED script path (`scriptRef`,
+ *      the workspace-relative `<runId>.<language>`) at run START, so a
+ *      mid-pipeline daemon restart's boot sweep finds it;
+ *   2. on a TIMEOUT, re-affirms the row resumable and SKIPS the run-end
+ *      `cleanupRun`, so the pinned script + the last checkpoint survive for a
+ *      later resume — their lifetime is owned by the durable row + the
+ *      checkpoint's longer TTL, and the orphan sweep reclaims a truly-dead run;
+ *   3. on an explicit resume, loads the PINNED bytes back and re-spawns THEM —
+ *      a resume NEVER accepts new script bytes.
+ *
+ * Everything here is pure over TWO injected seams — a narrow durable-run store
+ * port (`upsertCheckpoint`/`getByRootRun`) and an fs read seam — so the whole
+ * lifecycle is macOS-unit-testable with no real sqlite or spawn. The store port
+ * is a structural subset of the daemon's durable-run store, so the daemon threads
+ * the real store directly and @comis/skills never imports it concretely (the
+ * mint-lease closure precedent).
+ *
+ * The row is content-free: `{rootRunId, scriptRef, checkpointRef}` — a path + an
+ * id pointer, never the script bytes or the checkpoint body. The build mirrors
+ * the graph coordinator's checkpoint row but with a FLAT `spawnTree` (a
+ * `string[]`, so the DAG-vs-flat discriminator routes it to the flat arm) and
+ * NEVER writes the outward-send counter (`stepIndex` maps to `outward_step`,
+ * owned solely by the store's `allocateOutwardStep`; `upsertCheckpoint` omits
+ * the column, so a checkpoint between two outward sends cannot reset it).
+ *
+ * @module
+ */
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { safePath } from "@comis/core";
+import { ok, err } from "@comis/shared";
+/** The production fs seam — the real workspace read. */
+export const defaultOrchestrateDurableFs = {
+    exists: (absPath) => existsSync(absPath),
+    read: (absPath) => readFileSync(absPath, "utf8"),
+};
+// ---------------------------------------------------------------------------
+// The resumable-row lifecycle.
+// ---------------------------------------------------------------------------
+/**
+ * Build the resumable durable-run record: a FLAT `spawnTree` (so the resume
+ * engine's DAG-vs-flat discriminator routes it to the flat arm), `status:
+ * "running"` (the boot-resume scan set), the pinned `scriptRef`, and `stepIndex:
+ * -1` (the never-sent sentinel; the store omits the `outward_step` column on the
+ * upsert, so the outward-send counter is untouched). Content-free.
+ */
+export function buildResumableRow(input) {
+    return {
+        rootRunId: input.rootRunId,
+        spawnTree: [],
+        caps: [],
+        leaseIds: [],
+        budgetConsumed: 0,
+        cronOrigin: null,
+        stepIndex: -1,
+        status: "running",
+        lastHeartbeatAt: input.nowMs,
+        scriptRef: input.scriptRef,
+        ...(input.checkpointRef !== undefined ? { checkpointRef: input.checkpointRef } : {}),
+    };
+}
+/**
+ * Register the run as a resumable durable row at run START (scriptRef set), so a
+ * daemon restart mid-run finds it. Forwards the store's Result — the caller
+ * treats a failure as non-fatal (the run still proceeds; the timeout path
+ * re-affirms the row).
+ */
+export function registerDurableRun(runs, input) {
+    return runs.upsertCheckpoint(buildResumableRow(input));
+}
+/**
+ * The skip-clean decision on a run failure: when the durable store seam is
+ * present (the resume surface is on), re-affirm the row resumable and signal the
+ * runner to SKIP the run-end cleanup, so the pinned script + the last checkpoint
+ * survive for a resume. The re-affirm is best-effort — the row already exists
+ * from run start, so a store error does NOT flip the decision. With no store
+ * seam it is a no-op and the run cleans normally.
+ */
+export async function markResumable(runs, input) {
+    if (runs === undefined)
+        return { skipCleanup: false };
+    await runs.upsertCheckpoint(buildResumableRow(input));
+    return { skipCleanup: true };
+}
+/**
+ * Terminal cleanup for a NON-resumable orchestrate run (success OR a non-timeout
+ * failure): mark the durable row completed — so `listResumable` stops re-surfacing
+ * a finished run and the boot sweep never false-orphans it, mirroring the graph
+ * coordinator / sub-agent runner terminal write — and unlink the pinned
+ * `<runId>.<language>` script at the workspace ROOT (the run-end `cleanupRun` wipes
+ * only `results/`). Only a resumable TIMEOUT keeps the row + script, and it never
+ * calls this. Best-effort: a store/fs failure is logged (never thrown into the
+ * run's terminal path); `markCompleted` absent (a minimal stub) ⇒ that half no-ops.
+ */
+export async function finalizeCompletedRun(runs, input, logger) {
+    if (runs === undefined)
+        return; // resume surface off — nothing durable to finalize.
+    const done = await runs.markCompleted?.(input.rootRunId);
+    if (done !== undefined && !done.ok) {
+        logger?.warn({ runId: input.runId, rootRunId: input.rootRunId, err: done.error, errorKind: "internal", hint: "the durable row could not be marked completed — the watchdog orphan-sweep eventually reclaims the stale 'running' row (no live impact)" }, "orchestrate durable markCompleted failed (non-fatal)");
+    }
+    try {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- safePath-confined to the run workspace; scriptRef is a store-minted <runId>.<language> path
+        unlinkSync(safePath(input.workspacePath, input.scriptRef));
+    }
+    catch (e) {
+        logger?.debug({ runId: input.runId, err: e instanceof Error ? e : undefined, hint: "best-effort unlink of the pinned script failed; a later workspace teardown reclaims it" }, "orchestrate pinned-script cleanup failed (non-fatal)");
+    }
+}
+/**
+ * Resolve what the runner spawns, applying the fail-CLOSED resume contract:
+ *   - no `resumeRunId` ⇒ the fresh `script`/`language` params;
+ *   - `resumeRunId` with the surface OFF (no store) ⇒ REFUSE `not_implemented`
+ *     (NEVER silently run the caller's `script` — a resume takes no fresh bytes);
+ *   - `resumeRunId` with the surface ON ⇒ load + return the PINNED bytes (the
+ *     `script` param is IGNORED), or REFUSE `not_found` when it can't be loaded.
+ */
+export async function resolveScriptSource(params, runs, fs, ctx) {
+    const scriptName = `${ctx.runId}.${params.language}`;
+    if (params.resumeRunId === undefined) {
+        return ok({ script: params.script, language: params.language, scriptName });
+    }
+    if (runs === undefined) {
+        return err({
+            code: "not_implemented",
+            message: "Resume requires the durable-resume surface (autonomy.durability.orchestrateResume), which is not enabled for this agent.",
+            hint: "Enable orchestrateResume for this agent, or omit resumeRunId to run a fresh script.",
+        });
+    }
+    const loaded = await loadResumeSpec(runs, fs, {
+        resumeRunId: params.resumeRunId,
+        workspacePath: ctx.workspacePath,
+    });
+    if (!loaded.ok) {
+        return err({ code: "not_found", message: "The orchestrate run to resume could not be loaded.", hint: loaded.error });
+    }
+    return ok({ script: loaded.value.scriptBytes, language: loaded.value.language, scriptName: loaded.value.scriptRef });
+}
+/**
+ * Load the pinned re-spawn spec for a resume: read the durable row, resolve the
+ * pinned `scriptRef` CONFINED under the workspace (a `..`/absolute escape is
+ * refused before any read), and read the pinned bytes. The pinned bytes are the
+ * SOLE source — this loader takes no script param, so a resume can never smuggle
+ * new bytes. Every failure (missing row, no scriptRef, unknown extension, a
+ * missing or unreadable file, a store error, a traversal escape) honest-degrades
+ * to an `err` reason the runner surfaces — never a throw that crashes the run.
+ */
+export async function loadResumeSpec(runs, fs, input) {
+    const rowResult = await runs.getByRootRun(input.resumeRunId);
+    if (!rowResult.ok)
+        return err("the durable run lookup failed");
+    const row = rowResult.value;
+    if (row === undefined)
+        return err("no durable run found to resume");
+    const scriptRef = row.scriptRef;
+    if (!scriptRef)
+        return err("the durable run has no pinned script — not a resumable run");
+    const language = languageFromScriptRef(scriptRef);
+    if (language === undefined)
+        return err("the pinned script has no recognized language extension");
+    let absPath;
+    try {
+        absPath = safePath(input.workspacePath, scriptRef);
+    }
+    catch {
+        return err("the pinned script path escapes the workspace");
+    }
+    if (!fs.exists(absPath))
+        return err("the pinned script is gone (checkpoint reclaimed)");
+    let scriptBytes;
+    try {
+        scriptBytes = fs.read(absPath);
+    }
+    catch {
+        return err("the pinned script could not be read");
+    }
+    return ok({ scriptRef, scriptBytes, language });
+}
+/** Derive the interpreter language from a `<runId>.<language>` scriptRef extension. */
+function languageFromScriptRef(scriptRef) {
+    const ext = scriptRef.slice(scriptRef.lastIndexOf(".") + 1);
+    return ext === "ts" || ext === "js" || ext === "py" ? ext : undefined;
+}

package/node_modules/@comis/skills/dist/tools/builtin/orchestrate/orchestrate-executor-cores.d.ts

@@ -8,9 +8,10 @@ export interface OrchestrateFileCoreContext {
 /** A file core the executor calls: `(args, ctx) => result` over the workspace. */
 export type OrchestrateFileCore = (args: Record<string, unknown>, ctx: OrchestrateFileCoreContext) => Promise<unknown>;
 /**
- * The seven `{kind:"executor"}` file cores: the four read builtins
- * (read/grep/find/ls), and the three ResultRef slicers (jq, plus the QRY query
- * engine `sql`/`jsonpath`). All run DAEMON-side over the run-scoped workspace.
+ * The eight `{kind:"executor"}` file cores: the four read builtins
+ * (read/grep/find/ls), the three ResultRef slicers (jq, plus the QRY query
+ * engine `sql`/`jsonpath`), and the one mutating builtin (`write`). All run
+ * DAEMON-side over the run-scoped workspace, path-confined by `safePath`.
  */
 export interface OrchestrateFileCores {
     read: OrchestrateFileCore;
@@ -18,10 +19,12 @@ export interface OrchestrateFileCores {
     find: OrchestrateFileCore;
     ls: OrchestrateFileCore;
     jq: OrchestrateFileCore;
-    /** QRY-01: DuckDB SQL over a CSV/JSONL/JSON ResultRef (daemon-side, hardened). */
+    /** DuckDB SQL over a CSV/JSONL/JSON ResultRef (daemon-side, hardened). */
     sql: OrchestrateFileCore;
-    /** QRY-02: precise JSON extraction via DuckDB `json_extract` (NO eval lib). */
+    /** Precise JSON extraction via DuckDB `json_extract` (NO eval lib). */
     jsonpath: OrchestrateFileCore;
+    /** Run-scoped, run-ephemeral write confined to results/writes (safePath; the first mutating core). */
+    write: OrchestrateFileCore;
 }
 /** A daemon-side web-search core: `(args, ctx) => result` (the jail can't fetch). */
 export type OrchestrateWebSearchCore = (args: Record<string, unknown>, ctx: {
@@ -45,7 +48,7 @@ export interface OrchestrateExecutorCoresDeps {
 }
 /**
  * Screen a model-supplied DuckDB query for the extension / file-write / network
- * verbs and url-readers a read-only slicer must never run (T-221-QRY-01). Pure —
+ * verbs and url-readers a read-only slicer must never run. Pure —
  * returns a human reason on the FIRST hit, or `null` when the query is safe to
  * spawn. Called BEFORE `execFile` so a malicious query NEVER reaches `duckdb`.
  *

package/node_modules/@comis/skills/dist/tools/builtin/orchestrate/orchestrate-executor-cores.js

@@ -1,6 +1,7 @@
 import { execFile } from "node:child_process";
 import { safePath, systemNowMs } from "@comis/core";
 import { createComisReadTool } from "../file-tools/read-tool.js";
+import { createComisWriteTool } from "../file-tools/write-tool.js";
 import { createComisGrepTool } from "../file-tools/grep-tool.js";
 import { createComisFindTool } from "../file-tools/find-tool.js";
 import { createComisLsTool } from "../file-tools/ls-tool.js";
@@ -9,11 +10,11 @@ import { createWebSearchTool } from "../web-search-tool/index.js";
 function errorResult(error) {
     return { error };
 }
-/** Bound a duckdb stderr diagnostic before it crosses the jail boundary (IN-04). */
+/** Bound a duckdb stderr diagnostic before it crosses the jail boundary. */
 const DUCKDB_STDERR_MAX_CHARS = 500;
 /**
  * Scrub a duckdb stderr diagnostic for the `{ error }` returned to the jailed
- * client (IN-04). DuckDB error text can echo the offending SQL AND absolute host
+ * client. DuckDB error text can echo the offending SQL AND absolute host
  * paths (e.g. a failed `read_json_auto('/abs/...')` names the path); the jailed
  * client must never see daemon-side host paths. Replace any absolute path-like
  * run (`/...`, `~/...`, `C:\...`) with `<path>` and bound the length. Pure.
@@ -34,12 +35,24 @@ const JQ_MAX_BUFFER_BYTES = 8 * 1024 * 1024;
 const DEFAULT_SQL_TIMEOUT_MS = 10_000;
 /** Bound the captured duckdb stdout so a huge slice cannot blow the daemon's heap. */
 const SQL_MAX_BUFFER_BYTES = 8 * 1024 * 1024;
+/**
+ * The RUN-SCOPED, EPHEMERAL write root (relative to the lease workspace) the
+ * `write` core confines to — a subdir UNDER `results/`, which
+ * `ResultRefStore.cleanupRun` reaps WHOLESALE on run end. Confining here (NOT the
+ * persistent per-agent workspace root) makes the write genuinely run-ephemeral
+ * (a file written this run is gone after the run's cleanupRun) AND isolates it
+ * from the workspace-root discovery/config subtrees (`skills/`,
+ * `.learned-skills/`, memory, config): a `../`/absolute/`../../skills/…` path that
+ * escapes this root is refused by `safePath` BEFORE any write, so a run can never
+ * persist a cross-run skill into the top-priority skill-discovery path.
+ */
+const WRITE_SUBDIR = "results/writes";
 /**
  * Build the DuckDB hardening prelude prepended before the (untrusted) model
  * query on EVERY `-c` payload. The ORDER is load-bearing — each statement runs
  * left-to-right and the security knobs LOCK once restrictive, so they must be
  * set BEFORE the model query (which is appended after this prelude) so the query
- * cannot widen them from inside its own SQL (CR-01):
+ * cannot widen them from inside its own SQL:
  *
  *   1. `allowed_directories=['<workspaceDir>']` — the run's workspace is the ONLY
  *      directory DuckDB may read; these allow-roots are queryable IRRESPECTIVE of
@@ -62,7 +75,8 @@ const SQL_MAX_BUFFER_BYTES = 8 * 1024 * 1024;
  */
 function buildDuckDbHardeningPrelude(workspaceDir) {
     // Single-quote-escape the workspace path for the SQL string-list literal
-    // (a data-dir / agent-id containing a quote must not break out — mirrors WR-01).
+    // (a data-dir / agent-id containing a quote must not break out — same
+    // escaping as the jsonpath core's path literal).
     const escWs = workspaceDir.replace(/'/g, "''");
     return (`SET allowed_directories=['${escWs}']; ` +
         "SET enable_external_access=false; " +
@@ -72,7 +86,7 @@ function buildDuckDbHardeningPrelude(workspaceDir) {
 /**
  * Statement keywords that let DuckDB install an extension, load one, attach an
  * external database, or read/write a file/URL outside the confined `results/`
- * input — the daemon-side SSRF / exfil / file-write surface (T-221-QRY-01). The
+ * input — the daemon-side SSRF / exfil / file-write surface. The
  * query engine is a read-only slicer; ANY of these in a model-supplied query is
  * refused BEFORE `duckdb` is ever spawned. Matched as whole words, case-insensitive.
  */
@@ -97,7 +111,7 @@ const DANGEROUS_URL_SCHEMES = ["http://", "https://", "s3://", "gcs://", "gs://"
  * DuckDB local-file / environment table functions that have NO legitimate use
  * over a tabular `results/` ResultRef — they read raw file bytes, enumerate a
  * directory, or read a daemon env var from an ARBITRARY absolute host path with
- * none of the {@link DANGEROUS_SQL_KEYWORDS} and no url-scheme (CR-01). The real
+ * none of the {@link DANGEROUS_SQL_KEYWORDS} and no url-scheme. The real
  * confinement is `enable_external_access=false` + `allowed_directories` in
  * {@link buildDuckDbHardeningPrelude} (which blocks ALL readers off the allow-root,
  * including future ones); this denylist is belt-and-suspenders for the pure-exfil
@@ -118,7 +132,7 @@ const DANGEROUS_SQL_READERS = [
 ];
 /**
  * Screen a model-supplied DuckDB query for the extension / file-write / network
- * verbs and url-readers a read-only slicer must never run (T-221-QRY-01). Pure —
+ * verbs and url-readers a read-only slicer must never run. Pure —
  * returns a human reason on the FIRST hit, or `null` when the query is safe to
  * spawn. Called BEFORE `execFile` so a malicious query NEVER reaches `duckdb`.
  *
@@ -196,7 +210,7 @@ export function createOrchestrateExecutorCores(deps) {
         };
     }
     /**
-     * The `jq` core (READ-02): resolve the workspace-confined path and run the
+     * The `jq` core: resolve the workspace-confined path and run the
      * system `jq` over it (no shell — `execFile`). Returns the parsed slice, or a
      * content-free `{ error }` on a bad path / missing binary / non-zero exit.
      */
@@ -260,7 +274,7 @@ export function createOrchestrateExecutorCores(deps) {
         log.debug({ step: "duckdb-spawn", toolName }, "orchestrate duckdb spawning");
         // Confine the daemon-side duckdb to the run's workspace: the prelude sets
         // allowed_directories=[<ws>] + enable_external_access=false + lock BEFORE the
-        // (untrusted) model query (CR-01), and the process cwd is the workspace so a
+        // (untrusted) model query, and the process cwd is the workspace so a
         // workspace-relative `results/...` read resolves inside the allow-root rather
         // than against the daemon's cwd.
         const payload = buildDuckDbHardeningPrelude(workspaceDir) + query;
@@ -280,7 +294,7 @@ export function createOrchestrateExecutorCores(deps) {
                     resolve(errorResult(missing
                         ? "duckdb is not installed on the host"
                         : // Scrub absolute host paths + bound length before the error
-                            // crosses the jail boundary (IN-04): a duckdb diagnostic can
+                            // crosses the jail boundary: a duckdb diagnostic can
                             // echo the offending SQL/path; the jailed client must not see
                             // daemon-side host paths.
                             `duckdb error: ${scrubDuckDbStderr(stderr) || "non-zero exit"}`));
@@ -293,7 +307,7 @@ export function createOrchestrateExecutorCores(deps) {
         });
     }
     /**
-     * The `sql` core (QRY-01): run a model-supplied DuckDB query over the
+     * The `sql` core: run a model-supplied DuckDB query over the
      * workspace-confined ResultRef file. Path-confined (`safePath`), then screened
      * (`rejectDangerousSql` — INSTALL/LOAD/ATTACH/COPY/EXPORT/url-readers refused
      * BEFORE any spawn, the SSRF/exfil floor), then run through the hardened
@@ -321,7 +335,7 @@ export function createOrchestrateExecutorCores(deps) {
         }
         // Screen the model query for extension / file-write / network verbs, the
         // pure-exfil local-file readers, + url readers BEFORE spawning duckdb
-        // (T-221-QRY-01 / CR-01) — refuse, never spawn, on a hit. The running duckdb
+        // — refuse, never spawn, on a hit. The running duckdb
         // is ALSO confined to the workspace via the hardening prelude (defense in depth).
         const rejection = rejectDangerousSql(query);
         if (rejection !== null) {
@@ -331,7 +345,7 @@ export function createOrchestrateExecutorCores(deps) {
         return await runDuckDb(query, ctx.workspaceDir, "sql", started);
     };
     /**
-     * The `jsonpath` core (QRY-02): extract a precise value from a JSON ResultRef
+     * The `jsonpath` core: extract a precise value from a JSON ResultRef
      * via DuckDB `json_extract` — NO eval-based JSONPath library (banned, RCE CVEs).
      * Path-confined (`safePath`), the expr validated to a conservative `$`-dot/bracket
      * grammar (`isSafeJsonPath`) so it carries no SQL/quote injection, then compiled
@@ -359,8 +373,8 @@ export function createOrchestrateExecutorCores(deps) {
             return errorResult("jsonpath path escapes the workspace");
         }
         // Validate the JSONPath to the conservative dot/bracket grammar so it cannot
-        // inject SQL/quotes into the json_extract literal (the no-eval safety floor,
-        // T-221-QRY-03). Refused BEFORE any spawn.
+        // inject SQL/quotes into the json_extract literal (the no-eval safety
+        // floor). Refused BEFORE any spawn.
         if (!isSafeJsonPath(expr)) {
             log.warn({ errorKind: "validation", hint: "jsonpath expr is not a safe $-rooted dot/bracket path — refusing", toolName: "jsonpath" }, "orchestrate jsonpath unsafe expr blocked");
             return errorResult("jsonpath expr must be a $-rooted dot/bracket path (e.g. $.items[0].price) — wildcards/filters/functions are not supported");
@@ -368,7 +382,7 @@ export function createOrchestrateExecutorCores(deps) {
         // Compile the JSONPath into a DuckDB json_extract query over read_json_auto.
         // The path literal is the safePath-confined absolute path; the expr passed the
         // grammar gate above. read_json_auto yields one row of the doc as `j`.
-        // WR-01: single-quote-escape absPath before interpolating it into the SQL
+        // Single-quote-escape absPath before interpolating it into the SQL
         // string literal. `safePath` confines the LOCATION (under the workspace) but
         // does NOT escape SQL metacharacters; an operator data-dir / agent-id
         // containing a `'` (agentId is only z.string().min(1)) would otherwise break
@@ -377,6 +391,76 @@ export function createOrchestrateExecutorCores(deps) {
         const query = `SELECT json_extract(j, '${expr}') AS value FROM read_json_auto('${escPath}') t(j)`;
         return await runDuckDb(query, ctx.workspaceDir, "jsonpath", started);
     };
+    /**
+     * The `write` core: the FIRST general writing core on this surface. Adapts the
+     * shipped `createComisWriteTool` under `ctx.workspaceDir` — a MINIMAL,
+     * run-EPHEMERAL write to the run's workspace root (the SAME root the read cores
+     * read). Path-confined FIRST via `safePath` (a `..`/absolute escape is refused
+     * BEFORE any write, mirroring the jq/sql/jsonpath cores), and the write tool
+     * re-confines via its own `resolveWritePath`/`safePath` (defense in depth). Any
+     * path escape or write guard (device/protected/…) that would throw is
+     * honest-degraded to a content-free `{ error }` (never a throw), so a jailed
+     * write can never crash the executor or write outside the run workspace. NOT a
+     * persistent store, NOT an arbitrary/absolute path.
+     */
+    const write = async (args, ctx) => {
+        const started = systemNowMs();
+        const rawPath = typeof args.path === "string" ? args.path : "";
+        if (rawPath === "") {
+            log.warn({ errorKind: "validation", hint: "write called without a string `path`", toolName: "write" }, "orchestrate write missing path");
+            return errorResult("write requires a string `path`");
+        }
+        // Resolve the RUN-SCOPED, EPHEMERAL write root (<workspace>/results/writes) —
+        // NOT the persistent workspace root. results/ is reaped wholesale by
+        // ResultRefStore.cleanupRun on run end, so a write here is genuinely
+        // run-ephemeral and isolated from the workspace-root discovery/config
+        // subtrees (skills/, .learned-skills/, memory, config).
+        let writeRoot;
+        try {
+            writeRoot = safePath(ctx.workspaceDir, WRITE_SUBDIR);
+        }
+        catch (err) {
+            log.warn({ err, errorKind: "validation", hint: "the run-scoped write root escaped the workspace — refusing", toolName: "write" }, "orchestrate write root unresolvable");
+            return errorResult("write refused: the run workspace is unavailable");
+        }
+        // Confine the target under the run-scoped write root BEFORE any write (the same
+        // safePath confinement the jq/sql/jsonpath cores use). A `..`/absolute escape —
+        // or a `../…/skills/…` traversal back into the workspace-root discovery path —
+        // is refused here; the write lands under results/writes only.
+        try {
+            safePath(writeRoot, rawPath);
+        }
+        catch (err) {
+            log.warn({ err, errorKind: "validation", hint: "write path escaped the run workspace — refusing", toolName: "write" }, "orchestrate write path traversal blocked");
+            return errorResult("write path escapes the run workspace");
+        }
+        // Run the shipped write tool under the confined run-scoped root — it re-confines
+        // via its own safePath. Any remaining write guard that throws honest-degrades
+        // to a content-free { error } (the daemon-side host path never crosses the jail).
+        try {
+            const tool = createComisWriteTool(writeRoot);
+            const result = await tool.execute("tool.invoke", args);
+            log.debug({ step: "write-core", toolName: "write", durationMs: systemNowMs() - started }, "orchestrate write core executed");
+            return result;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            // The shipped write tool throws PREFIXED errors ([stale_file],
+            // [write_secret_blocked], [file_too_large], [invalid_config], [protected_file],
+            // [dir_create_failed], [write_error], [device_file], [jupyter_rejected],
+            // [missing_path]). Preserve the DISTINCT failure CLASS (the bracketed kind) so
+            // a jailed script can tell a secret-blocked / stale-file / protected-file
+            // refusal apart and recover — collapsing them all to "not writable" was
+            // misleading. We surface ONLY the [kind] token (a fixed lower_snake enum),
+            // never the interpolated tail, which can echo an absolute host path
+            // (device_file / dir_create_failed name a path) — the jail must not see it.
+            const kind = /^\[([a-z_]+)\]/.exec(message)?.[1];
+            log.warn({ err, errorKind: "validation", hint: "write refused by a workspace write guard", toolName: "write", writeErrorKind: kind ?? "unknown" }, "orchestrate write failed");
+            return errorResult(kind !== undefined
+                ? `write refused (${kind})`
+                : "write refused: the path is not writable in the run workspace");
+        }
+    };
     const fileExecutors = {
         read: fileCore((w) => createComisReadTool(w), "read"),
         grep: fileCore((w) => createComisGrepTool(w), "grep"),
@@ -385,6 +469,7 @@ export function createOrchestrateExecutorCores(deps) {
         jq,
         sql,
         jsonpath,
+        write,
     };
     const webSearch = async (args, _ctx) => {
         const started = systemNowMs();