@alisio/core 0.5.2 → 0.7.0

package/dist/forge/state-store.js

@@ -0,0 +1,50 @@
+import { DEFAULT_STATE_TOTAL_BYTES, planCommit, } from "./state-delta.js";
+export class SqliteStateStore {
+    #db;
+    #now;
+    #maxTotalBytes;
+    constructor(db, options = {}) {
+        this.#db = db;
+        this.#now = options.now ?? Date.now;
+        const max = options.maxTotalBytes ?? DEFAULT_STATE_TOTAL_BYTES;
+        this.#maxTotalBytes = typeof max === "function" ? max : () => max;
+    }
+    /** Live values and every revision (tombstones included) of a root session. */
+    snapshot(rootSessionId) {
+        const snapshot = { values: {}, revisions: {} };
+        for (const [key, entry] of this.#read(rootSessionId)) {
+            snapshot.revisions[key] = entry.revision;
+            if (entry.valueJson !== "")
+                snapshot.values[key] = JSON.parse(entry.valueJson);
+        }
+        return snapshot;
+    }
+    /**
+     * Applies a delta against the snapshot it was built from. Throws `STATE_CONFLICT` or
+     * `BUDGET_EXCEEDED` without writing anything. Returns the number of rows written.
+     */
+    commit(rootSessionId, snapshot, ops) {
+        return this.#db.transaction(() => {
+            const plan = planCommit({
+                current: this.#read(rootSessionId),
+                snapshot,
+                ops,
+                maxTotalBytes: this.#maxTotalBytes(),
+            });
+            const upsert = this.#db.prepare(`INSERT INTO forge_state(root_session_id,key,value_json,revision,updated_at)
+         VALUES(?,?,?,?,?)
+         ON CONFLICT(root_session_id,key) DO UPDATE SET
+           value_json=excluded.value_json, revision=excluded.revision, updated_at=excluded.updated_at`);
+            const now = this.#now();
+            for (const write of plan.writes)
+                upsert.run(rootSessionId, write.key, write.valueJson, write.revision, now);
+            return plan.writes.length;
+        });
+    }
+    #read(rootSessionId) {
+        const rows = this.#db
+            .prepare("SELECT key, value_json, revision FROM forge_state WHERE root_session_id=?")
+            .all(rootSessionId);
+        return new Map(rows.map((row) => [row.key, { valueJson: row.value_json, revision: Number(row.revision) }]));
+    }
+}

package/dist/forge/task-log.d.ts

@@ -0,0 +1,9 @@
+export declare const TASK_LOG_MAX_BYTES: number;
+export declare class TaskLog {
+    #private;
+    constructor(path: string, max?: number);
+    /** Appends one line (a newline is added). Over the bound, one marker line is written and the rest dropped. */
+    write(line: string): void;
+    /** Resolves when everything written so far reached the file. */
+    flush(): Promise<void>;
+}

package/dist/forge/task-log.js

@@ -0,0 +1,42 @@
+/**
+ * The live log of an execution, `<sessionDir>/tasks/<executionId>.log` (spec §9.4): bounded,
+ * created `0600`, best effort. The model can `tail` it while a long script runs. A failure to
+ * write never affects the execution.
+ */
+import { appendFile, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+export const TASK_LOG_MAX_BYTES = 256 * 1024;
+export class TaskLog {
+    #path;
+    #max;
+    #written = 0;
+    #closed = false;
+    #chain = Promise.resolve();
+    constructor(path, max = TASK_LOG_MAX_BYTES) {
+        this.#path = path;
+        this.#max = max;
+    }
+    /** Appends one line (a newline is added). Over the bound, one marker line is written and the rest dropped. */
+    write(line) {
+        if (this.#closed)
+            return;
+        const text = line.endsWith("\n") ? line : `${line}\n`;
+        const bytes = Buffer.byteLength(text);
+        let data = text;
+        if (this.#written + bytes > this.#max) {
+            this.#closed = true;
+            data = "[log truncated: size limit reached]\n";
+        }
+        this.#written += Buffer.byteLength(data);
+        this.#chain = this.#chain
+            .then(async () => {
+            await mkdir(dirname(this.#path), { recursive: true, mode: 0o700 });
+            await appendFile(this.#path, data, { mode: 0o600 });
+        })
+            .catch(() => { });
+    }
+    /** Resolves when everything written so far reached the file. */
+    async flush() {
+        await this.#chain;
+    }
+}

package/dist/forge/verdict.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Who decides how an execution ends (spec §5.2, D5). Pure: no I/O.
+ *
+ * The host's own stop (a user cancellation, or its deadline) decides the terminal state whatever
+ * the guest said afterwards; a guest that merely noticed the same thing first reports the same
+ * code; anything else keeps the guest's own outcome. A guest that says TIMEOUT or CANCELLED when
+ * the host stopped nothing is only reporting a failure: the terminal states are the host's alone.
+ */
+import type { ForgeErrorCode } from "./errors.ts";
+import type { EngineOutcome } from "./ports.ts";
+import type { ForgeStatus } from "./result.ts";
+export interface Verdict {
+    status: ForgeStatus;
+    error?: {
+        code: ForgeErrorCode;
+        message: string;
+    };
+    value?: unknown;
+}
+export declare function verdictOf(outcome: EngineOutcome, stop: "cancelled" | "timeout" | undefined, timeoutMs: number): Verdict;

package/dist/forge/verdict.js

@@ -0,0 +1,28 @@
+const timedOut = (timeoutMs) => ({
+    status: "timed_out",
+    error: { code: "TIMEOUT", message: `Execution exceeded ${timeoutMs} ms` },
+});
+const cancelled = () => ({
+    status: "cancelled",
+    error: { code: "CANCELLED", message: "Execution was cancelled" },
+});
+export function verdictOf(outcome, stop, timeoutMs) {
+    if (stop === "timeout")
+        return timedOut(timeoutMs);
+    if (stop === "cancelled")
+        return cancelled();
+    if (outcome.kind === "completed")
+        return {
+            status: "succeeded",
+            ...(outcome.value !== undefined ? { value: outcome.value } : {}),
+        };
+    if (outcome.code === "TIMEOUT" || outcome.code === "CANCELLED")
+        return {
+            status: "failed",
+            error: {
+                code: "SCRIPT_RUNTIME",
+                message: `the script reported ${outcome.code} on its own: ${outcome.message}`,
+            },
+        };
+    return { status: "failed", error: { code: outcome.code, message: outcome.message } };
+}

package/dist/forge-isolate.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The entry the compiled `alisio` binary runs for its hidden `__forge-isolate` command (spec D-21):
+ * the body of a Forja process isolate. It is a separate export on purpose, so the CLI loads it
+ * without loading the application, the configuration or SQLite.
+ */
+export { runProcessIsolate } from "./forge/javascript/hosts/isolate-main.ts";

package/dist/forge-isolate.js

@@ -0,0 +1,6 @@
+/**
+ * The entry the compiled `alisio` binary runs for its hidden `__forge-isolate` command (spec D-21):
+ * the body of a Forja process isolate. It is a separate export on purpose, so the CLI loads it
+ * without loading the application, the configuration or SQLite.
+ */
+export { runProcessIsolate } from "./forge/javascript/hosts/isolate-main.js";

package/dist/index.d.ts

@@ -41,7 +41,29 @@ export { ToolRegistry } from "./core/registry.ts";
 export { RunClock } from "./core/run-clock.ts";
 export { AgentRunner, type CompactionResult, defaultTokenBudget, type RunnerOptions, type RunnerSettingsPatch, type RunOptions, } from "./core/runner.ts";
 export { CircuitBreaker, type CircuitBreakerOptions, type CircuitState, DECISION_LIMITS, DEFAULT_DECISIONS_CONFIG, type DecisionAttempt, DecisionError, type DecisionMetricEntry, DecisionMetrics, type DecisionMetricsSnapshot, type DecisionOutcome, DecisionRegistry, DecisionService, type DecisionServiceDeps, type DecisionStatus, type DecisionsConfig, formatDecisionStatsSection, formatDecisionsReport, HEALTH_TIMEOUT_MS, type RegisteredDecisionProvider, splitSupported, validateAnswers, validateRequest, } from "./decisions/index.ts";
+export { canonicalJson, hashCanonical } from "./eval/canonical.ts";
+export { CASSETTE_SUFFIX, type Cassette, type CassetteCall, CassetteFormatError, type CassetteHeader, type CassetteMeta, CassetteRecorder, CassetteWriteError, MAX_CASSETTE_BYTES, MAX_CASSETTE_DIR_BYTES, parseCassette, RecordingProvider, ReplayDivergenceError, ReplayExhausted, ReplayProvider, ReplayUnconsumedError, readCassette, serializeCassette, type WriteOptions, writeCassette, } from "./eval/cassette.ts";
+export { type Conditions, compareReports, compareVariants, EvalCompareError, type EvalComparison, type Interval, type MetricDelta, parseReport, renderComparisonMarkdown, renderVariantComparisonMarkdown, type TaskComparison, type TokenComparison, type VariantComparison, type Verdict, } from "./eval/compare.ts";
+export { CONFIG_HASH_COVERAGE, type ConfigHashExtras, checkTaskPolicy, computeConfigHash, type EvalApplication, EvalBudgetExceeded, type EvalRunMode, EvalRunRefusedError, type InvokerPermissions, type RunTaskOptions, runTask, } from "./eval/engine.ts";
+export { buildExportBundle, type EvalExportBundle, EvalExportRefusedError, type ExportContext, } from "./eval/export.ts";
+export { computeFingerprint, type FingerprintDiff, type FingerprintDiffEntry, } from "./eval/fingerprint.ts";
+export { EvalPathError, resolveInside } from "./eval/paths.ts";
+export { interleaveVariants, mulberry32, type PlannedRun, planRuns, type VariantStep, } from "./eval/plan.ts";
+export { type BuildReportOptions, buildReport, EvalReportError, estimateRunCost, lowPowerTasks, MIN_POWER_K, renderReportMarkdown, } from "./eval/report.ts";
+export { type RunEvaluationOptions, type RunEvaluationResult, type RunVariantsOptions, runEvaluation, runVariantEvaluations, } from "./eval/run-suite.ts";
+export { findSecrets, redactSecrets } from "./eval/secrets.ts";
+export { median, passAtK, passPowK, sampleVariance, wilsonInterval, } from "./eval/stats.ts";
+export { EvalSuiteError, type LoadedSuite, loadSuite, MAX_VERIFIER_TIMEOUT_MS, } from "./eval/suite.ts";
+export { applyConfigOverrides, EvalVariantError, loadVariantsFile, resolveVariants, type VariantsFile, } from "./eval/variants.ts";
+export { runVerifier, runVerifiers, snapshotTree, type ToolEvent, type TreeSnapshot, type VerifierContext, type VerifierResult, type VerifierStatus, } from "./eval/verifiers.ts";
 export { type ExtensionConflict, ExtensionRegistry } from "./extensions/registry.ts";
+export { ForgeError } from "./forge/errors.ts";
+export { downloadSize as pyodideDownloadSize, inspectPyodide, installPyodide, PyodideIntegrityError, pyodideDir, } from "./forge/python/pyodide-install.ts";
+export { PYODIDE_MANIFEST, type PyodideManifest, type PyodideProfile, } from "./forge/python/pyodide-manifest.ts";
+export { describePythonBackends } from "./forge/python/status.ts";
+export { createPythonBackends } from "./forge/python/wiring.ts";
+export { describeForge, type ForgeStatus, forgeEngineFor } from "./forge/runtime.ts";
+export { emptyScratch, listScratch, openScratchFile, SCRATCH_LIST_LIMIT, type ScratchFileInfo, } from "./forge/scratch-files.ts";
 export * from "./goal/index.ts";
 export { HerdrBridge } from "./integrations/herdr.ts";
 export { McpConnector, type McpServerInfo, type McpStatus, type McpToolInfo, } from "./mcp/connector.ts";
@@ -62,7 +84,7 @@ export { type ExternalDirectoryDecision, type ExternalDirectoryHandler, type Ext
 export { BlobStore, type BlobStoreOptions, BlobTooLarge } from "./runtime/blobs.ts";
 export { clipLines, unifiedPatch } from "./runtime/diff.ts";
 export { exists, fileSize, readHead, readJson, readText, which } from "./runtime/fs.ts";
-export { newId, ulid } from "./runtime/ids.ts";
+export { type IdSource, newId, newUuid, seededIdSource, setIdSource, ulid, } from "./runtime/ids.ts";
 export { defaultGlobalRoots, isPathSpec, PLUGIN_KEYWORD, resolvePluginSpec, } from "./runtime/modules.ts";
 export { findWorkspace, inside, outsideRootsMessage, safePath, workspaceKey, } from "./runtime/paths.ts";
 export { isMissingCommand, type ProcessResult, RIPGREP_INSTALL_HINT, runProcess, } from "./runtime/process.ts";

package/dist/index.js

@@ -40,7 +40,29 @@ export { ToolRegistry } from "./core/registry.js";
 export { RunClock } from "./core/run-clock.js";
 export { AgentRunner, defaultTokenBudget, } from "./core/runner.js";
 export { CircuitBreaker, DECISION_LIMITS, DEFAULT_DECISIONS_CONFIG, DecisionError, DecisionMetrics, DecisionRegistry, DecisionService, formatDecisionStatsSection, formatDecisionsReport, HEALTH_TIMEOUT_MS, splitSupported, validateAnswers, validateRequest, } from "./decisions/index.js";
+export { canonicalJson, hashCanonical } from "./eval/canonical.js";
+export { CASSETTE_SUFFIX, CassetteFormatError, CassetteRecorder, CassetteWriteError, MAX_CASSETTE_BYTES, MAX_CASSETTE_DIR_BYTES, parseCassette, RecordingProvider, ReplayDivergenceError, ReplayExhausted, ReplayProvider, ReplayUnconsumedError, readCassette, serializeCassette, writeCassette, } from "./eval/cassette.js";
+export { compareReports, compareVariants, EvalCompareError, parseReport, renderComparisonMarkdown, renderVariantComparisonMarkdown, } from "./eval/compare.js";
+export { CONFIG_HASH_COVERAGE, checkTaskPolicy, computeConfigHash, EvalBudgetExceeded, EvalRunRefusedError, runTask, } from "./eval/engine.js";
+export { buildExportBundle, EvalExportRefusedError, } from "./eval/export.js";
+export { computeFingerprint, } from "./eval/fingerprint.js";
+export { EvalPathError, resolveInside } from "./eval/paths.js";
+export { interleaveVariants, mulberry32, planRuns, } from "./eval/plan.js";
+export { buildReport, EvalReportError, estimateRunCost, lowPowerTasks, MIN_POWER_K, renderReportMarkdown, } from "./eval/report.js";
+export { runEvaluation, runVariantEvaluations, } from "./eval/run-suite.js";
+export { findSecrets, redactSecrets } from "./eval/secrets.js";
+export { median, passAtK, passPowK, sampleVariance, wilsonInterval, } from "./eval/stats.js";
+export { EvalSuiteError, loadSuite, MAX_VERIFIER_TIMEOUT_MS, } from "./eval/suite.js";
+export { applyConfigOverrides, EvalVariantError, loadVariantsFile, resolveVariants, } from "./eval/variants.js";
+export { runVerifier, runVerifiers, snapshotTree, } from "./eval/verifiers.js";
 export { ExtensionRegistry } from "./extensions/registry.js";
+export { ForgeError } from "./forge/errors.js";
+export { downloadSize as pyodideDownloadSize, inspectPyodide, installPyodide, PyodideIntegrityError, pyodideDir, } from "./forge/python/pyodide-install.js";
+export { PYODIDE_MANIFEST, } from "./forge/python/pyodide-manifest.js";
+export { describePythonBackends } from "./forge/python/status.js";
+export { createPythonBackends } from "./forge/python/wiring.js";
+export { describeForge, forgeEngineFor } from "./forge/runtime.js";
+export { emptyScratch, listScratch, openScratchFile, SCRATCH_LIST_LIMIT, } from "./forge/scratch-files.js";
 export * from "./goal/index.js";
 export { HerdrBridge } from "./integrations/herdr.js";
 export { McpConnector, } from "./mcp/connector.js";
@@ -61,7 +83,7 @@ export { PathAccess, } from "./runtime/access.js";
 export { BlobStore, BlobTooLarge } from "./runtime/blobs.js";
 export { clipLines, unifiedPatch } from "./runtime/diff.js";
 export { exists, fileSize, readHead, readJson, readText, which } from "./runtime/fs.js";
-export { newId, ulid } from "./runtime/ids.js";
+export { newId, newUuid, seededIdSource, setIdSource, ulid, } from "./runtime/ids.js";
 export { defaultGlobalRoots, isPathSpec, PLUGIN_KEYWORD, resolvePluginSpec, } from "./runtime/modules.js";
 export { findWorkspace, inside, outsideRootsMessage, safePath, workspaceKey, } from "./runtime/paths.js";
 export { isMissingCommand, RIPGREP_INSTALL_HINT, runProcess, } from "./runtime/process.js";

package/dist/permissions/decide.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The effect gate of a tool call as a pure decision (spec D-25). The runner, `availableTools`, the
+ * legacy `execute` tool and the Forja nested-call dispatcher all ask this one function, so a call
+ * made from inside a script gets exactly the decision a direct call would get; there is no second
+ * permission system.
+ *
+ * Rules, kept from the runner they were extracted from:
+ *  - `read` and `internal` always run; `write`, `process` and `external` run when the policy says so.
+ *  - A tool with no declared effect is `external`.
+ *  - A capability tool (`analysis.run`) also runs on the `--allow-analysis` flag alone, and on a
+ *    stored grant; the grant never widens the effect.
+ *  - Otherwise the call asks, but only for `write`, `process` and `external`, and only when a
+ *    person can be asked. Anything else is denied.
+ *
+ * The policy is read by reference on purpose: an "allow for the session" answer widens the very
+ * same object, and the next decision must see it.
+ */
+import type { ToolDefinition } from "@alisio/sdk";
+import type { Policy } from "../core/contracts.ts";
+export type EffectDecision = {
+    kind: "allow";
+    via: "effect" | "flag" | "grant";
+} | {
+    kind: "ask";
+} | {
+    kind: "deny";
+};
+export interface DecideContext {
+    /** Whether an interactive approval could be opened for this call. */
+    approvals: boolean;
+    /** Whether the tool's capability holds a stored grant for the session. */
+    capabilityGranted: boolean;
+}
+/** The tool's effect; a tool that declares none is treated as `external`. */
+export declare const effectOf: (tool: Pick<ToolDefinition, "effect">) => string;
+/** Whether the policy lets an effect run without asking. */
+export declare const effectAllowed: (policy: Policy, effect: string) => boolean;
+/** Whether an effect can ever be put to a person (`read` and `internal` never are). */
+export declare const effectAskable: (effect: string) => effect is "write" | "process" | "external";
+/** A tool's capability is pre-allowed by the policy alone (`--allow-analysis`). */
+export declare const capabilityFlagAllowed: (policy: Policy, tool: Pick<ToolDefinition, "capability">) => boolean;
+export declare function decideEffect(policy: Policy, tool: Pick<ToolDefinition, "effect" | "capability">, context: DecideContext): EffectDecision;

package/dist/permissions/decide.js

@@ -0,0 +1,24 @@
+/** The tool's effect; a tool that declares none is treated as `external`. */
+export const effectOf = (tool) => tool.effect ?? "external";
+/** Whether the policy lets an effect run without asking. */
+export const effectAllowed = (policy, effect) => effect === "read" ||
+    effect === "internal" ||
+    ((effect === "write" || effect === "process" || effect === "external") && !!policy[effect]);
+/** Whether an effect can ever be put to a person (`read` and `internal` never are). */
+export const effectAskable = (effect) => effect === "write" || effect === "process" || effect === "external";
+/** A tool's capability is pre-allowed by the policy alone (`--allow-analysis`). */
+export const capabilityFlagAllowed = (policy, tool) => tool.capability === "analysis.run" && !!policy.analysis;
+export function decideEffect(policy, tool, context) {
+    const effect = effectOf(tool);
+    const byEffect = effectAllowed(policy, effect);
+    if (tool.capability) {
+        // A broad process grant or --allow-analysis: allowed, audited as a flag decision.
+        if (byEffect || capabilityFlagAllowed(policy, tool))
+            return { kind: "allow", via: "flag" };
+        if (context.capabilityGranted)
+            return { kind: "allow", via: "grant" };
+    }
+    else if (byEffect)
+        return { kind: "allow", via: "effect" };
+    return context.approvals && effectAskable(effect) ? { kind: "ask" } : { kind: "deny" };
+}

package/dist/plan/exit-plan.js

@@ -15,6 +15,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { textResult } from "@alisio/sdk";
 import { EXIT_PLAN_TOOL } from "../core/opt-in.js";
+import { newUuid } from "../runtime/ids.js";
 import { objectSchema } from "../tools/standard.js";
 import { DIAGRAM_MAX_BYTES, DIAGRAM_MAX_NODES, validateDiagrams, } from "./diagrams.js";
 import { buildPlanManifest } from "./manifest.js";
@@ -118,7 +119,7 @@ export function registerExitPlan(registry, deps) {
                 throw new Error("exit_plan needs the whole plan in the `plan` field");
             const sessionId = context.session;
             const title = planTitle(plan, input.title);
-            const planId = crypto.randomUUID();
+            const planId = newUuid();
             const reviewable = !!sessionId && deps.ui.interactive() && !deps.readOnly;
             const revision = sessionId ? nextPlanRevision(deps.store, sessionId) : 1;
             const previous = sessionId

package/dist/resources/context.d.ts

@@ -16,7 +16,8 @@ export interface ProjectContextOptions {
 }
 export declare class ProjectContext implements ContextSource {
     readonly workspace: string;
-    extras: Array<() => Promise<string>>;
+    /** Extra system-prompt sections; `sessionId` lets one depend on the session (the scratchpad path). */
+    extras: Array<(sessionId?: string) => Promise<string>>;
     readonly cwd: string;
     private options;
     /** Per session: nested instruction file path → fingerprint already attached. */

package/dist/resources/context.js

@@ -18,6 +18,7 @@ const PREAMBLE = "You are Alisio, a coding assistant. Follow the user's task. To
 const HEADER = "# Project instructions (AGENTS.md)\nFiles are listed from the global and repository root down to the current directory; when they conflict, the closest file wins. Explicit user prompts override these instructions. Instructions for nested directories are attached when you touch paths below them.";
 export class ProjectContext {
     workspace;
+    /** Extra system-prompt sections; `sessionId` lets one depend on the session (the scratchpad path). */
     extras = [];
     cwd;
     options;
@@ -143,7 +144,7 @@ export class ProjectContext {
         if (files.length)
             chunks.push(HEADER, ...this.capped(files));
         for (const extra of this.extras)
-            chunks.push(await extra());
+            chunks.push(await extra(sessionId));
         return chunks.join("\n\n");
     }
     /** Keeps the closest files within the byte budget; drops or truncates the farthest ones. */

package/dist/runtime/access.d.ts

@@ -23,6 +23,15 @@ export interface PathAccessOptions {
     approve?: ExternalDirectoryHandler;
     /** Fully locked: declared roots are ignored and no external directory is ever approvable. */
     readOnly?: boolean;
+    /**
+     * The verified scratchpad of a session's ROOT session (Forja, spec §9.4), created on first use.
+     * When given, that folder is an authorized root: a path inside it needs no directory approval.
+     * Absent when Forja is off, so nothing changes; ignored under `--read-only`. A failure to
+     * provide it just means "no scratchpad".
+     */
+    scratchpad?: (session: string) => Promise<string | undefined>;
+    /** `forge.scratch.maxBytes`, read on every check: the quota of one scratchpad. */
+    scratchMaxBytes?: () => number;
 }
 export interface ResolvePathOptions {
     /** Workspace to resolve a relative path against (child sessions may use a worktree). */
@@ -41,11 +50,36 @@ export declare class PathAccess {
     private readonly roots;
     private readonly approve?;
     private readonly readOnly;
+    private readonly scratchpad?;
+    private readonly scratchMaxBytes?;
     /** Session-approved directory subtrees (allow for the session). */
     private readonly approved;
     /** Canonicalized roots, memoized; a nonexistent declared root never matches. */
     private readonly canonical;
     constructor(options: PathAccessOptions);
+    /**
+     * `target` made safe inside the session's scratchpad, or undefined when it is not there: outside
+     * it, no session, no scratchpad, or a symlink on the way (an escaping link is "outside").
+     */
+    private scratchTarget;
+    /** Whether an already resolved path lies in the session's verified scratchpad (never read-only). */
+    isScratchPath(target: string, session?: string): Promise<boolean>;
+    /** Scratchpad writers in flight, one queue per scratchpad directory (see `lockScratch`). */
+    private scratchLocks;
+    /**
+     * Serializes the quota check and the write that follows it (L1): two parallel writes that each
+     * fit would otherwise both pass the check and together overflow. Resolves to the release. Keyed
+     * by the scratchpad directory, so a child session shares the lock of its root session.
+     */
+    lockScratch(session: string | undefined): Promise<() => void>;
+    /**
+     * Why a write of about `incomingBytes` into the session's scratchpad must be refused (spec §9.4,
+     * FJ-AC-34), or undefined when it fits. Nothing is ever deleted to make room: the model is told,
+     * plainly, that the scratchpad is full.
+     */
+    scratchQuotaProblem(session: string | undefined, incomingBytes: number, 
+    /** Files the write replaces: their current size is not counted twice. */
+    replacing?: readonly string[]): Promise<string | undefined>;
     /** Extra roots actually in force (always empty under `--read-only`). */
     get extraRoots(): readonly string[];
     /** Directory subtrees approved for the session (diagnostics and tests). */

package/dist/runtime/access.js

@@ -13,6 +13,7 @@
  */
 import { lstat, realpath } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
+import { scratchUsage } from "../forge/session-dir.js";
 import { inside, outsideRootsMessage, safePath } from "./paths.js";
 /** Nearest existing ancestor directory of `target`, canonicalized; used as the approval boundary. */
 async function nearestExistingDirectory(target) {
@@ -38,6 +39,8 @@ export class PathAccess {
     roots;
     approve;
     readOnly;
+    scratchpad;
+    scratchMaxBytes;
     /** Session-approved directory subtrees (allow for the session). */
     approved = new Set();
     /** Canonicalized roots, memoized; a nonexistent declared root never matches. */
@@ -48,6 +51,80 @@ export class PathAccess {
         this.readOnly = !!options.readOnly;
         if (options.approve && !options.readOnly)
             this.approve = options.approve;
+        if (options.scratchpad && !options.readOnly)
+            this.scratchpad = options.scratchpad;
+        if (options.scratchMaxBytes)
+            this.scratchMaxBytes = options.scratchMaxBytes;
+    }
+    /**
+     * `target` made safe inside the session's scratchpad, or undefined when it is not there: outside
+     * it, no session, no scratchpad, or a symlink on the way (an escaping link is "outside").
+     */
+    async scratchTarget(target, session) {
+        if (!this.scratchpad || !session)
+            return undefined;
+        try {
+            const base = await this.scratchpad(session);
+            if (!base || !inside(base, target))
+                return undefined;
+            return await safePath(base, target);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Whether an already resolved path lies in the session's verified scratchpad (never read-only). */
+    async isScratchPath(target, session) {
+        return (await this.scratchTarget(target, session)) !== undefined;
+    }
+    /** Scratchpad writers in flight, one queue per scratchpad directory (see `lockScratch`). */
+    scratchLocks = new Map();
+    /**
+     * Serializes the quota check and the write that follows it (L1): two parallel writes that each
+     * fit would otherwise both pass the check and together overflow. Resolves to the release. Keyed
+     * by the scratchpad directory, so a child session shares the lock of its root session.
+     */
+    async lockScratch(session) {
+        const base = this.scratchpad && session
+            ? await this.scratchpad(session).catch(() => undefined)
+            : undefined;
+        const key = base ?? "";
+        const previous = this.scratchLocks.get(key) ?? Promise.resolve();
+        let release = () => { };
+        const mine = new Promise((resolve) => {
+            release = resolve;
+        });
+        const tail = previous.then(() => mine);
+        this.scratchLocks.set(key, tail);
+        await previous;
+        return () => {
+            release();
+            if (this.scratchLocks.get(key) === tail)
+                this.scratchLocks.delete(key);
+        };
+    }
+    /**
+     * Why a write of about `incomingBytes` into the session's scratchpad must be refused (spec §9.4,
+     * FJ-AC-34), or undefined when it fits. Nothing is ever deleted to make room: the model is told,
+     * plainly, that the scratchpad is full.
+     */
+    async scratchQuotaProblem(session, incomingBytes, 
+    /** Files the write replaces: their current size is not counted twice. */
+    replacing = []) {
+        if (!this.scratchpad || !this.scratchMaxBytes || !session)
+            return undefined;
+        const base = await this.scratchpad(session).catch(() => undefined);
+        if (!base)
+            return undefined;
+        const max = this.scratchMaxBytes();
+        let used = await scratchUsage(base);
+        for (const path of replacing)
+            used -= (await lstat(path).catch(() => undefined))?.size ?? 0;
+        used = Math.max(0, used);
+        if (used + incomingBytes <= max)
+            return undefined;
+        return (`The session scratchpad is full: ${used} of ${max} bytes used and this write needs about ` +
+            `${incomingBytes}. Nothing was deleted; remove files you no longer need, or ask the user to clear it.`);
     }
     /** Extra roots actually in force (always empty under `--read-only`). */
     get extraRoots() {
@@ -88,6 +165,9 @@ export class PathAccess {
         const root = await this.rootFor(target, workspace);
         if (root)
             return safePath(root, target);
+        const scratch = await this.scratchTarget(target, options.session);
+        if (scratch)
+            return scratch;
         if (this.readOnly)
             throw new Error(outsideRootsMessage(target, "--read-only disables access outside the workspace; run without it to allow it"));
         const boundary = await nearestExistingDirectory(target);

package/dist/runtime/ids.d.ts

@@ -6,3 +6,24 @@
 export declare function ulid(now?: number): string;
 /** A prefixed id such as `art_01J…` or `exec_01J…`. */
 export declare const newId: (prefix: string, now?: number) => string;
+/**
+ * A replacement for the random identifiers the runtime generates (session ids, plan ids, forge
+ * execution ids, `ulid`-based ids). The reliability lab installs a seeded one while it records or
+ * replays a cassette so the requests a run sends do not depend on fresh randomness. Nothing
+ * installs one in normal use, and then every function here behaves exactly as before.
+ */
+export interface IdSource {
+    /** A UUID (the shape of `crypto.randomUUID()`). */
+    uuid(): string;
+    /** The 26-character body of a `ulid` (the argument is the caller's clock, which a source may ignore). */
+    ulid(now?: number): string;
+}
+/** Installs (or, with `undefined`, removes) the process-wide id source. */
+export declare function setIdSource(source?: IdSource): void;
+/** A random v4 UUID, or the next one of the installed id source. */
+export declare const newUuid: () => string;
+/**
+ * A deterministic source: the n-th UUID (and the n-th ULID) depends only on `seed`. UUIDs are
+ * v4-shaped; ULIDs carry a counter in their time part, so they stay sortable by creation order.
+ */
+export declare function seededIdSource(seed: string): IdSource;

package/dist/runtime/ids.js

@@ -1,4 +1,4 @@
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 /** Crockford base32 (no I, L, O, U), the ULID alphabet. */
 const ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
 /**
@@ -7,6 +7,8 @@ const ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
  * millisecond sort arbitrarily, which is fine for row ids and folder names.
  */
 export function ulid(now = Date.now()) {
+    if (installed)
+        return installed.ulid(now);
     let time = "";
     let t = Math.max(0, Math.floor(now));
     for (let i = 0; i < 10; i++) {
@@ -30,3 +32,41 @@ export function ulid(now = Date.now()) {
 }
 /** A prefixed id such as `art_01J…` or `exec_01J…`. */
 export const newId = (prefix, now) => `${prefix}_${ulid(now)}`;
+let installed;
+/** Installs (or, with `undefined`, removes) the process-wide id source. */
+export function setIdSource(source) {
+    installed = source;
+}
+/** A random v4 UUID, or the next one of the installed id source. */
+export const newUuid = () => (installed ? installed.uuid() : randomUUID());
+/**
+ * A deterministic source: the n-th UUID (and the n-th ULID) depends only on `seed`. UUIDs are
+ * v4-shaped; ULIDs carry a counter in their time part, so they stay sortable by creation order.
+ */
+export function seededIdSource(seed) {
+    let uuids = 0;
+    let ulids = 0;
+    const digest = (kind, n) => createHash("sha256").update(`${seed}\0${kind}\0${n}`).digest();
+    return {
+        uuid() {
+            const bytes = digest("uuid", uuids++).subarray(0, 16);
+            bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x40;
+            bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
+            const hex = bytes.toString("hex");
+            return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+        },
+        ulid() {
+            let time = "";
+            let t = ulids;
+            for (let i = 0; i < 10; i++) {
+                time = (ALPHABET[t % 32] ?? "0") + time;
+                t = Math.floor(t / 32);
+            }
+            const bytes = digest("ulid", ulids++);
+            let random = "";
+            for (let i = 0; i < 16; i++)
+                random += ALPHABET[(bytes[i] ?? 0) & 31];
+            return time + random;
+        },
+    };
+}

package/dist/runtime/process.d.ts

@@ -27,7 +27,8 @@ export declare function runProcess(command: string, args: string[], options: {
     timeoutMs?: number;
     maxBytes?: number;
     env?: Record<string, string>;
-    onData?: (chunk: string) => void;
+    /** Live text; the second argument says which stream it came from. */
+    onData?: (chunk: string, stream: "stdout" | "stderr") => void;
     /** On cancellation: SIGTERM the process group, then SIGKILL after this grace (default 5s). */
     killGraceMs?: number;
     /**