@sweny-ai/core 0.1.176 → 0.1.178

package/dist/harness/acp.js

@@ -48,7 +48,7 @@ import { spawn } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { consoleLogger } from "../types.js";
-import { finishAgentEnv, heldCredentials, parseList, reportWithheldEnv, resolveEnvScope, resolveSandboxMode, scopeAgentEnv, withPushBlocked, } from "../agent-env.js";
+import { finishAgentEnv, heldCredentials, parseList, reportWithheldEnv, resolveEnvScope, resolveSandboxMode, scopeAgentEnv, withPushBlocked, mcpWithheld, } from "../agent-env.js";
 import { ACP_CAPABILITIES } from "./capabilities.js";
 import { policyGate, resolveHarnessPolicy, TOOL_CLASSES } from "./policy.js";
 import { gitCredentialPolicy } from "../git-credentials.js";
@@ -739,7 +739,7 @@ export class AcpHarness {
         try {
             // Dry run: external MCP servers cannot be classified per tool, so only
             // sweny's own (already read-filtered) skill tools remain.
-            const servers = readOnly
+            const servers = mcpWithheld(readOnly, req.agentAccess)
                 ? {}
                 : { ...this.defaultMcpServers, ...req.mcpServers, ...this.mcpServers };
             if (req.tools.length > 0) {

package/dist/harness/claude-code.js

@@ -11,7 +11,7 @@
 import { query, createSdkMcpServer, tool as sdkTool } from "@anthropic-ai/claude-agent-sdk";
 import { createRequire } from "node:module";
 import { consoleLogger } from "../types.js";
-import { AGENT_AUTH_VARS, finishAgentEnv, reportWithheldEnv, parseList, resolveEnvScope, scopeAgentEnv, withPushBlocked, resolveAgentSandbox, } from "../agent-env.js";
+import { AGENT_AUTH_VARS, finishAgentEnv, reportWithheldEnv, parseList, resolveEnvScope, scopeAgentEnv, withPushBlocked, mcpWithheld, resolveAgentSandbox, } from "../agent-env.js";
 import { gitCredentialGap, policyGate } from "./policy.js";
 import { gitCredentialPolicy } from "../git-credentials.js";
 import { CLAUDE_CODE_CAPABILITIES } from "./capabilities.js";
@@ -324,13 +324,14 @@ export class ClaudeCodeHarness {
             ...req,
             readOnly,
             disallowedTools: disallowedTools.length > 0 ? disallowedTools : undefined,
-            strictMcp: readOnly || policy.strict || policy.exclusiveMcp === true,
+            strictMcp: mcpWithheld(readOnly, req.agentAccess) || policy.strict || policy.exclusiveMcp === true,
             sandboxMode: policy.sandbox,
             agentAccess: {
                 envVars: req.agentAccess?.envVars ?? [],
                 domains: policy.egress,
                 withhold: req.agentAccess?.withhold,
                 noPush: req.agentAccess?.noPush,
+                noMcp: req.agentAccess?.noMcp,
             },
             stagedWrite: !!req.agentAccess?.noPush && !readOnly,
             strict: policy.strict || this.policyMode === "strict",
@@ -483,7 +484,8 @@ export class ClaudeCodeHarness {
         const abort = makeAbort(timeoutMs, signal);
         let stream;
         try {
-            const allMcpServers = readOnly
+            // Read-only and staged runs: no skill or external MCP server (it may write).
+            const allMcpServers = mcpWithheld(!!readOnly, agentAccess)
                 ? {}
                 : { ...this.defaultMcpServers, ...opts.mcpServers, ...this.mcpServers };
             if (useBridge) {
@@ -520,7 +522,7 @@ export class ClaudeCodeHarness {
                     // project .mcp.json, plugins). strictMcpConfig limits MCP to the
                     // servers passed above, which under readOnly is only sweny-core.
                     // A strict policy (#365) makes it exclusive for write nodes too.
-                    ...(readOnly || opts.strictMcp ? { strictMcpConfig: true } : {}),
+                    ...(mcpWithheld(!!readOnly, agentAccess) || opts.strictMcp ? { strictMcpConfig: true } : {}),
                     ...(disallowedTools && disallowedTools.length > 0 ? { disallowedTools } : {}),
                     // CC-08: ask the SDK to produce validated structured output when the
                     // node declares an output schema. The SDK then returns the parsed

package/dist/harness/codex.js

@@ -28,7 +28,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { consoleLogger } from "../types.js";
-import { CODEX_AUTH_VARS, CODEX_ENV_PREFIXES, checkSandboxSupport, finishAgentEnv, heldCredentials, parseList, reportWithheldEnv, resolveCodexAuthEnv, resolveEnvScope, resolveSandboxMode, scopeAgentEnv, withPushBlocked, } from "../agent-env.js";
+import { CODEX_AUTH_VARS, CODEX_ENV_PREFIXES, checkSandboxSupport, finishAgentEnv, heldCredentials, parseList, reportWithheldEnv, resolveCodexAuthEnv, resolveEnvScope, resolveSandboxMode, scopeAgentEnv, withPushBlocked, mcpWithheld, } from "../agent-env.js";
 import { CODEX_CAPABILITIES } from "./capabilities.js";
 import { policyGate, resolveHarnessPolicy } from "./policy.js";
 import { gitCredentialPolicy } from "../git-credentials.js";
@@ -816,7 +816,7 @@ export class CodexHarness {
         try {
             // Dry run: external MCP servers cannot be classified per tool, so only
             // sweny's own (already read-filtered) skill tools remain.
-            const servers = readOnly
+            const servers = mcpWithheld(readOnly, req.agentAccess)
                 ? {}
                 : { ...this.defaultMcpServers, ...req.mcpServers, ...this.mcpServers };
             const { args: mcpArgs, unsupported } = this.mcpArgs(servers);

package/dist/harness/pi.js

@@ -34,7 +34,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { consoleLogger } from "../types.js";
-import { PI_AUTH_VARS, PI_ENV_PREFIXES, finishAgentEnv, heldCredentials, parseList, reportWithheldEnv, resolveEnvScope, resolvePiProvider, resolveSandboxMode, scopeAgentEnv, withPushBlocked, } from "../agent-env.js";
+import { PI_AUTH_VARS, PI_ENV_PREFIXES, finishAgentEnv, heldCredentials, parseList, reportWithheldEnv, resolveEnvScope, resolvePiProvider, resolveSandboxMode, scopeAgentEnv, withPushBlocked, mcpWithheld, } from "../agent-env.js";
 import { PI_CAPABILITIES } from "./capabilities.js";
 import { policyGate, resolveHarnessPolicy } from "./policy.js";
 import { gitCredentialPolicy } from "../git-credentials.js";
@@ -788,7 +788,7 @@ export class PiHarness {
             // Dry run: external MCP servers cannot be classified per tool (and a
             // `--tools` allowlist cannot name tools it has not seen), so only sweny's
             // own (already read-filtered) skill tools remain.
-            const servers = readOnly
+            const servers = mcpWithheld(readOnly, req.agentAccess)
                 ? {}
                 : { ...this.defaultMcpServers, ...req.mcpServers, ...this.mcpServers };
             const { entries, unsupported } = piMcpServers(servers);

package/dist/index.d.ts

@@ -27,8 +27,8 @@ export { EVALUATOR_KINDS, EVAL_POLICIES, REQUIRES_ON_FAIL, NODE_ON_FAIL, MCP_TRA
 export { consoleLogger } from "./types.js";
 export { execute, RouteEvaluationError } from "./executor.js";
 export type { ExecuteOptions } from "./executor.js";
-export { systemOneProvider, DecideError, gateVerdict, DECIDER_MIN_CONFIDENCE, DECIDER_MIN_MARGIN } from "./decider.js";
-export type { DecisionProvider, DeciderConfig, DeciderMode, DeciderRecord, SystemOneOptions } from "./decider.js";
+export { systemOneProvider } from "./decider.js";
+export type { DeciderConfig, DeciderOperatorConfig } from "./decider.js";
 export { BudgetGuard, describeOverrun, minLimits, toLimits } from "./budget.js";
 export type { Budget, BudgetOverrun, BudgetUnit, SpendLimits } from "./budget.js";
 export { resolveNodePermissions, buildNodePolicy } from "./node-policy.js";

package/dist/index.js

@@ -27,8 +27,8 @@ export { EVALUATOR_KINDS, EVAL_POLICIES, REQUIRES_ON_FAIL, NODE_ON_FAIL, MCP_TRA
 export { consoleLogger } from "./types.js";
 // Executor
 export { execute, RouteEvaluationError } from "./executor.js";
-// Decision models, shadow mode (#357)
-export { systemOneProvider, DecideError, gateVerdict, DECIDER_MIN_CONFIDENCE, DECIDER_MIN_MARGIN } from "./decider.js";
+// Decision models (#357): config types and the provider adapter only
+export { systemOneProvider } from "./decider.js";
 // Least-privilege nodes and safe outputs (#365)
 export { BudgetGuard, describeOverrun, minLimits, toLimits } from "./budget.js";
 export { resolveNodePermissions, buildNodePolicy } from "./node-policy.js";

package/dist/journal.d.ts

@@ -29,7 +29,7 @@
  *   output:intent    a write is about to be applied (idempotency key + tool)
  *   output:applied   the write returned (key + the ids it produced)
  *   node:end         final result of the visit and the write-stage counters
- *   route            the edge taken after the visit (null = the run ended)
+ *   route            the edge taken after the visit (null = the run ended), and the rung that chose it
  *   usage            spend of one agent attempt (cumulative; live while it runs, final when it returns)
  *   run:end          success | failed | crashed
  *
@@ -52,9 +52,10 @@
  * (the process died between the API call and the receipt) is looked up on the
  * provider by a marker embedded in the body before anything is re-sent.
  */
-import type { Logger, NodeResult, NodeUsage, Skill, Workflow } from "./types.js";
+import type { Logger, NodeResult, NodeUsage, RouteRung, Skill, Workflow } from "./types.js";
 import type { SafeOutputIntent, WriteStageState } from "./safe-outputs.js";
 import { type Spend } from "./budget.js";
+import type { DeciderCounters } from "./decider.js";
 /** v2: records are authenticated with a per-run HMAC key (v1 used a public checksum and is refused). */
 export declare const JOURNAL_SCHEMA_VERSION = 2;
 export declare const JOURNAL_DIR: string;
@@ -139,6 +140,10 @@ export interface RunStartRecord extends JournalRecord {
     sweny_version?: string;
     input: unknown;
     input_redacted: boolean;
+    decider?: {
+        mode: "on" | "off";
+        reason?: string;
+    };
 }
 export interface WriteStateSnapshot {
     counts: Array<[string, number]>;
@@ -218,6 +223,8 @@ export interface PlannedVisit {
     status?: NodeResult["status"];
     /** Route taken after the visit: a node id, null for run end, undefined when not journaled. */
     next?: string | null;
+    /** Who chose that route, when it was a decision (#357). */
+    rung?: RouteRung;
     /** Writes the checkpointed write stage already applied (receipts in the journal). */
     applied: number;
     /** Writes with an intent but no receipt: checked on the provider before anything is re-sent. */
@@ -243,6 +250,8 @@ export interface ResumePlan {
     receipts: Map<string, OutputRecord>;
     /** Spend every earlier attempt journaled: the run budget starts here on resume. */
     priorSpend: Spend;
+    /** The decider's mode at run start and its counters after the last journaled route (#357). */
+    decider?: JournalDeciderState;
 }
 /**
  * Check that the records are a sequence the executor can write: one run:start
@@ -281,6 +290,21 @@ export interface JournalBeginInfo {
     config: Record<string, string>;
     writeState: WriteStageState;
     harnessId?: string;
+    /** Whether the run's decider ran (#357), journaled so a resume keeps the same mode. */
+    decider?: {
+        mode: "on" | "off";
+        reason?: string;
+    };
+}
+/**
+ * The decider as an earlier attempt left it (#357): its mode at run start and
+ * the breaker / cap counters after the last journaled route. Cap and breaker
+ * are per logical run, so a resume continues them.
+ */
+export interface JournalDeciderState {
+    mode: "on" | "off";
+    reason?: string;
+    counters?: DeciderCounters;
 }
 export interface JournalCheckpoint {
     result: NodeResult;
@@ -292,6 +316,7 @@ export type JournalReplay = {
     kind: "complete";
     result: NodeResult;
     next?: string | null;
+    rung?: RouteRung;
 } | ({
     kind: "checkpoint";
 } & JournalCheckpoint);
@@ -308,7 +333,8 @@ export interface ExecutionJournal {
     /** The skill map the write stage applies through: write tools journaled and made idempotent. */
     wrapWrites(node: string, iteration: number, skills: Map<string, Skill>): Map<string, Skill>;
     nodeEnd(node: string, iteration: number, result: NodeResult, writeState: WriteStageState): void;
-    route(from: string, to: string | null): void;
+    /** The edge taken after a visit, and for a decision the rung that chose it (#357), so resume replays it. */
+    route(from: string, to: string | null, rung?: RouteRung, decider?: DeciderCounters): void;
     /**
      * Spend of one agent attempt, cumulative for the attempt: `final` when the
      * attempt returned, otherwise a live report (the journal may throttle those).
@@ -316,6 +342,8 @@ export interface ExecutionJournal {
     usage?(node: string, iteration: number, attempt: number, usage: NodeUsage, final: boolean): void;
     /** Spend earlier attempts of this run already journaled (resume); the run budget starts from it. */
     priorSpend?(): Spend | undefined;
+    /** The decider state earlier attempts of this run journaled (resume); undefined otherwise. */
+    deciderResume?(): JournalDeciderState | undefined;
 }
 /** Minimum gap between two live usage records of one attempt. Final reports are always written. */
 export declare const USAGE_JOURNAL_INTERVAL_MS = 2000;
@@ -382,18 +410,19 @@ export declare class RunJournal implements ExecutionJournal {
     /** False once an append failed: the rest of the run is not journaled. */
     get active(): boolean;
     private takeLock;
-    /** The run dir is private (0700); its parents are created as usual. */
+    /** The run dir is private (0700); no link on the path from cwd is followed (safe-file.ts). */
     private makeDir;
     private releaseLock;
     private append;
     private closeFd;
     private clean;
     begin(info: JournalBeginInfo): void;
+    deciderResume(): JournalDeciderState | undefined;
     replay(node: string, iteration: number): JournalReplay | undefined;
     nodeStart(node: string, iteration: number): void;
     checkpoint(node: string, iteration: number, cp: JournalCheckpoint): void;
     nodeEnd(node: string, iteration: number, result: NodeResult, writeState: WriteStageState): void;
-    route(from: string, to: string | null): void;
+    route(from: string, to: string | null, rung?: RouteRung, decider?: DeciderCounters): void;
     usage(node: string, iteration: number, attempt: number, usage: NodeUsage, final: boolean): void;
     priorSpend(): Spend | undefined;
     /** Close the run: `run:end`, then release the lock. Safe to call twice (one run:end). */

package/dist/journal.js

@@ -29,7 +29,7 @@
  *   output:intent    a write is about to be applied (idempotency key + tool)
  *   output:applied   the write returned (key + the ids it produced)
  *   node:end         final result of the visit and the write-stage counters
- *   route            the edge taken after the visit (null = the run ended)
+ *   route            the edge taken after the visit (null = the run ended), and the rung that chose it
  *   usage            spend of one agent attempt (cumulative; live while it runs, final when it returns)
  *   run:end          success | failed | crashed
  *
@@ -59,6 +59,7 @@ import path from "node:path";
 import { resolveNodePermissions } from "./node-policy.js";
 import { CURRENT_SPEC_VERSION } from "./migrations.js";
 import { spendOf } from "./budget.js";
+import { ensureDirNoFollow, openNoFollow, writeFileNoFollow } from "./safe-file.js";
 /** v2: records are authenticated with a per-run HMAC key (v1 used a public checksum and is refused). */
 export const JOURNAL_SCHEMA_VERSION = 2;
 export const JOURNAL_DIR = path.join(".sweny", "runs");
@@ -292,13 +293,15 @@ export function redact(value, secrets = []) {
             return v.map((x) => walk(x, depth + 1));
         if (v && typeof v === "object") {
             const out = {};
+            // defineProperty, not assignment: a key named `__proto__` stays a plain key.
+            const put = (k, x) => Object.defineProperty(out, k, { value: x, enumerable: true, writable: true, configurable: true });
             for (const [k, x] of Object.entries(v)) {
                 if (typeof x === "string" && isSecretKey(k) && x.length > 0) {
-                    out[k] = REDACTED;
+                    put(k, REDACTED);
                     redacted = true;
                 }
                 else if (x !== undefined && typeof x !== "function") {
-                    out[k] = walk(x, depth + 1);
+                    put(k, walk(x, depth + 1));
                 }
             }
             return out;
@@ -466,6 +469,13 @@ const RECORD_TYPES = new Set([
 const isPosInt = (v) => typeof v === "number" && Number.isInteger(v) && v > 0;
 const isName = (v) => typeof v === "string" && v.length > 0;
 const isAmount = (v) => typeof v === "number" && Number.isFinite(v) && v >= 0;
+const isRung = (v) => v === "expr" || v === "decider" || v === "agent";
+const isCount = (v) => typeof v === "number" && Number.isInteger(v) && v >= 0;
+const isCounters = (v) => typeof v === "object" &&
+    v !== null &&
+    isCount(v.calls) &&
+    isCount(v.failures) &&
+    typeof v.open === "boolean";
 /**
  * Check that the records are a sequence the executor can write: one run:start
  * first; nothing but run:resume after run:end; a visit starts only where the
@@ -582,6 +592,10 @@ export function checkRecordSequence(records) {
                     bad(r, `routes from ${String(r.from)}, but the visit that ended is ${cur.node}`);
                 if (r.to !== null && !isName(r.to))
                     bad(r, "has no valid target");
+                if (r.rung !== undefined && !isRung(r.rung))
+                    bad(r, "has an unknown rung");
+                if (r.decider !== undefined && !isCounters(r.decider))
+                    bad(r, "has invalid decider counters");
                 cur.routed = true;
                 next = r.to;
                 break;
@@ -662,6 +676,7 @@ export function buildResumePlan(records) {
     const receipts = new Map();
     let attempts = 1;
     let lastStatus;
+    let deciderCounters;
     for (const r of records) {
         switch (r.type) {
             case "run:resume":
@@ -680,6 +695,7 @@ export function buildResumePlan(records) {
                     // Re-run of a visit an earlier attempt did not finish (or finished failed).
                     delete v.end;
                     delete v.next;
+                    delete v.rung;
                 }
                 break;
             }
@@ -698,8 +714,14 @@ export function buildResumePlan(records) {
             case "route": {
                 const from = r.from;
                 const v = [...order].reverse().find((x) => x.node === from);
-                if (v)
+                if (v) {
                     v.next = r.to ?? null;
+                    if (isRung(r.rung))
+                        v.rung = r.rung;
+                }
+                // Calls already made count even if the visit later re-runs.
+                if (isCounters(r.decider))
+                    deciderCounters = r.decider;
                 break;
             }
             case "output:intent":
@@ -732,6 +754,7 @@ export function buildResumePlan(records) {
                 action: "replay",
                 status: v.end.result.status,
                 next: v.next,
+                ...(v.rung ? { rung: v.rung } : {}),
                 applied,
                 unconfirmed,
             });
@@ -775,6 +798,9 @@ export function buildResumePlan(records) {
         intents,
         receipts,
         priorSpend: journaledSpend(records),
+        ...(start.decider
+            ? { decider: { ...start.decider, ...(deciderCounters ? { counters: { ...deciderCounters } } : {}) } }
+            : {}),
     };
 }
 /**
@@ -1005,12 +1031,11 @@ export class RunJournal {
                 throw err;
         }
         this.makeDir();
-        fs.writeFileSync(lock, String(process.pid), { mode: 0o600 });
+        writeFileNoFollow(lock, String(process.pid), { root: this.cwd, mode: 0o600 });
     }
-    /** The run dir is private (0700); its parents are created as usual. */
+    /** The run dir is private (0700); no link on the path from cwd is followed (safe-file.ts). */
     makeDir() {
-        fs.mkdirSync(path.dirname(this.dir), { recursive: true });
-        fs.mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+        ensureDirNoFollow(this.dir, this.cwd);
     }
     releaseLock() {
         try {
@@ -1052,8 +1077,7 @@ export class RunJournal {
         try {
             if (this.fd === undefined) {
                 this.makeDir();
-                this.fd = fs.openSync(this.file, "a", 0o600);
-                fs.fchmodSync(this.fd, 0o600);
+                this.fd = openNoFollow(this.file, { root: this.cwd, append: true, mode: 0o600 });
             }
             fs.writeSync(this.fd, JSON.stringify(record) + "\n");
             fs.fsyncSync(this.fd);
@@ -1126,7 +1150,7 @@ export class RunJournal {
         try {
             this.makeDir();
             // Journals hold node output: keep them out of commits (an agent's `git add -A` included).
-            fs.writeFileSync(path.join(this.dir, ".gitignore"), "*\n");
+            writeFileNoFollow(path.join(this.dir, ".gitignore"), "*\n", { root: this.cwd, mode: 0o644 });
             this.takeLock();
         }
         catch {
@@ -1154,8 +1178,12 @@ export class RunJournal {
             ...(this.opts.swenyVersion ? { sweny_version: this.opts.swenyVersion } : {}),
             input: input.value,
             input_redacted: input.redacted,
+            ...(info.decider ? { decider: info.decider } : {}),
         });
     }
+    deciderResume() {
+        return this.resume?.plan.decider;
+    }
     replay(node, iteration) {
         const plan = this.resume?.plan;
         if (!plan)
@@ -1173,6 +1201,7 @@ export class RunJournal {
                 kind: "complete",
                 result: structuredClone(end.result),
                 ...(visit.next !== undefined ? { next: visit.next } : {}),
+                ...(visit.rung ? { rung: visit.rung } : {}),
             };
         }
         if (visit.action === "write-stage") {
@@ -1210,8 +1239,8 @@ export class RunJournal {
             write_state: { counts: [...writeState.counts], total: writeState.total, seen: [...writeState.seen] },
         });
     }
-    route(from, to) {
-        this.append("route", { from, to });
+    route(from, to, rung, decider) {
+        this.append("route", { from, to, ...(rung ? { rung } : {}), ...(decider ? { decider } : {}) });
     }
     usage(node, iteration, attempt, usage, final) {
         const s = spendOf(usage);

package/dist/safe-file.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Files the sweny process writes into an agent-writable workspace.
+ *
+ * An agent can leave a symlink or a hard link where sweny is about to write
+ * (`.sweny/runs/<id>/output.md` -> `~/.bashrc`), or swap a directory on the
+ * path for a link. These helpers never follow a link: every directory between
+ * the trusted root and the file must be a real directory owned by this user,
+ * the final component is opened `O_NOFOLLOW`, and the file written must be a
+ * regular file with one link (a replaced link or special file is unlinked and
+ * created fresh with `O_EXCL`). Data goes through the descriptor that was
+ * checked; the mode is set on it.
+ *
+ * Race with a process that swaps a checked directory for a link (TOCTOU):
+ * Node has no `openat(2)`, so the parent chain is checked by pathname and the
+ * file opened by pathname. After the open, {@link assertOpenedUnder} re-checks
+ * the chain (realpath equals the lexical path, every component a real owned
+ * directory) and requires that the pathname now names the very inode the
+ * descriptor holds (dev and ino). A swap before the open either leaves a link
+ * on the path or moves the opened inode off it; both fail closed before a byte
+ * is written. Residual risk: an `O_CREAT` through a swapped directory can leave
+ * an empty file outside the workspace before the check fails, and the unlink of
+ * a planted link or special file is by pathname (checked just before, not
+ * atomic). A regular file is never unlinked or truncated by pathname.
+ *
+ * Node only.
+ */
+/**
+ * Create `dir` and its missing parents below `root`, checking each component
+ * under `root` with lstat: a real directory, owned by this user. `root` itself
+ * is trusted. A `dir` outside `root` is created as usual and only its last
+ * component is checked.
+ */
+export declare function ensureDirNoFollow(dir: string, root: string, mode?: number): void;
+export interface NoFollowOptions {
+    /**
+     * Trusted base dir (the workspace root): every component below it, and the
+     * file, must be owned by this user. Default: the file's own dir, with no
+     * ownership check (a runner-owned GITHUB_STEP_SUMMARY, say).
+     */
+    root?: string;
+    /** File mode, set on the descriptor. Default 0o600. */
+    mode?: number;
+    /** Mode for directories created on the way. Default 0o700. */
+    dirMode?: number;
+    /** Append to an existing regular file instead of replacing it. */
+    append?: boolean;
+    /** Create missing directories. Default true. */
+    mkdirs?: boolean;
+}
+/**
+ * Open `file` for writing without following a link. Replace mode unlinks what
+ * is there and creates a fresh file; append mode refuses anything but a
+ * regular, singly linked file (owned by this user when under `root`).
+ * Returns the descriptor; the caller closes it.
+ */
+/**
+ * Fail unless `fd` is the file `file` names now, below `root`, with no link
+ * anywhere between them: the directory's realpath is the realpath of `root`
+ * plus the same relative path, each component under `root` is a real
+ * directory (owned by this user when `owned`), and `lstat(file)` has the
+ * descriptor's dev and ino. See the module comment for the race it closes.
+ */
+export declare function assertOpenedUnder(fd: number, file: string, root: string, owned?: boolean): void;
+export declare function openNoFollow(file: string, opts?: NoFollowOptions): number;
+/**
+ * `{ root: cwd }` when `file` is inside `cwd` (the workspace, where the agent
+ * can write), else `{}`: an operator path elsewhere is only opened without
+ * following a final link.
+ */
+export declare function workspaceRoot(file: string, cwd?: string): {
+    root?: string;
+};
+/** Write (or append) `data` to `file` through {@link openNoFollow}. Throws on any refusal. */
+export declare function writeFileNoFollow(file: string, data: string | Uint8Array, opts?: NoFollowOptions): void;