@sweny-ai/core 0.1.178 → 0.1.179

package/dist/journal.d.ts

@@ -2,23 +2,42 @@
  * Run journal (#363): an append-only log of one workflow run, enough to resume
  * a killed or failed run without re-running the nodes that already finished.
  *
- * File: `.sweny/runs/<run-id>/journal.ndjson` (mode 0600), one JSON record per
- * line. Every record carries the format version (`v`), a sequence number (`seq`)
- * and an authentication code (`h`, HMAC-SHA256 of the record without `h`, under
- * a per-run key). Each append is written and fsync'd before the executor moves
- * on, so a record on disk is a fact.
+ * Location: the journal never lives in the workspace. Each run gets a private
+ * directory in the user's sweny state dir (`$SWENY_STATE_DIR`, else
+ * `$XDG_STATE_HOME/sweny`, else `~/.local/state/sweny`):
  *
- * Integrity: the key is 32 random bytes made when the run starts and kept
- * OUTSIDE the workspace, in the user's sweny state dir
- * (`$SWENY_STATE_DIR`, else `$XDG_STATE_HOME/sweny`, else
- * `~/.local/state/sweny`), under `run-keys/` (dir 0700, file 0600). Anything
- * that can write the workspace but not that dir (an agent confined to the
- * workspace, a checked-out branch, an artifact) cannot mint a record resume
- * accepts. Both sandboxes deny reading the key dir; an unsandboxed agent
- * running as the same OS user can still read it, which is why resume also
- * checks the record sequence (see {@link buildResumePlan}) and every replayed
- * route against the workflow's real edges. A resume on another machine needs
- * the same state dir.
+ *   runs/<workspace-hash>/<run-id>/   (dirs 0700, files 0600, opened O_NOFOLLOW)
+ *     key             32 random bytes, the run's HMAC key
+ *     journal.ndjson  one JSON record per line, fsync'd per append
+ *     head.json       the record being appended, written (atomically) first
+ *     meta.json       run id, workspace hash, creation time; authenticated, drives retention
+ *     lock            the process that owns the run (pid + start time)
+ *
+ * Both agent sandboxes deny reading AND writing the whole `runs/` tree, so an
+ * agent confined to the workspace cannot read the key, edit or cut the
+ * journal, delete the lock or fake a run. The workspace keeps only user-facing
+ * artifacts (`.sweny/runs/<run-id>/output.md` and the run history record).
+ * Journals an older sweny wrote in the workspace are refused for resume.
+ *
+ * Integrity: every record carries the format version (`v`), a sequence number
+ * (`seq`) and `h`, an HMAC-SHA256 under the run key over the run id, the seq,
+ * the previous record's `h` and the record body. The chain means records
+ * cannot be reordered, duplicated, or spliced in from another run. The head
+ * file holds the full record being appended, written and renamed into place
+ * BEFORE the journal append: a crash between the two leaves a journal exactly
+ * one record short, and resume restores that record from the head. A journal
+ * shorter than that, or one that disagrees with the head, is refused, so the
+ * end of the journal cannot be cut away even by something that can write the
+ * state dir but not read the key.
+ *
+ * All of this holds only for an agent under an enforced sandbox. An
+ * unsandboxed agent running as the same OS user can read the key and rewrite
+ * the state dir. Each such visit is journaled (`agent:unsandboxed`), and a
+ * resume of that run warns and marks the receipt `journal_unsandboxed`.
+ * Resume also checks the record sequence (see {@link buildResumePlan}) and
+ * every replayed route against the workflow's real edges. A state dir whose
+ * real path is inside the workspace is refused. A resume on another machine
+ * needs the same state dir.
  *
  * Records, in run order:
  *   run:start        workflow / instruction / input / tool hashes, harness id, input (redacted)
@@ -30,17 +49,31 @@
  *   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), and the rung that chose it
- *   usage            spend of one agent attempt (cumulative; live while it runs, final when it returns)
+ *   usage            spend of one agent attempt (cumulative; one per model turn that raised it, written
+ *                    synchronously, and the final figure when the attempt returns)
+ *   agent:unsandboxed the visit's agent ran without an enforced sandbox
  *   run:end          success | failed | crashed
  *
+ * Failure: an append that cannot be written (head or journal) is fatal. The
+ * executor stops the run before the next model call or side effect and fails
+ * the node with the reason, so a resume never under-counts spend or repeats a
+ * write the journal did not see.
+ *
  * Spend: a resume seeds the run budget with every attempt's journaled usage,
- * so a crash never resets the whole-run ceiling.
+ * from authenticated records only, so a crash never resets the whole-run ceiling.
+ *
+ * Recovery: an unterminated tail that is not complete JSON (power loss
+ * mid-append) is truncated. An unterminated tail that IS complete JSON is
+ * never assumed torn: it must authenticate as the next record, or the journal
+ * is refused. Corruption in the middle of the file is refused.
  *
- * Recovery: a torn or corrupt tail (power loss mid-append) is truncated back to
- * the last valid record. Corruption in the middle of the file is refused.
+ * Lock: taken with O_CREAT|O_EXCL before anything is read or repaired, and
+ * held for the whole run or resume. A lock whose process is gone (pid not
+ * alive, or alive with a different start time) is taken over under a
+ * second exclusive lock, re-checked first, so two resumes cannot both win.
  *
- * Privacy: the journal is local and holds what the run needs to continue (node
- * data, eval verdicts, safe-output intents). It never holds environment values:
+ * Privacy: the journal holds what the run needs to continue (node data, eval
+ * verdicts, safe-output intents). It never holds environment values:
  * secret-looking keys, known token shapes, and the values of secret env vars
  * and skill credentials are replaced with `[redacted]` before anything is
  * written. Tool call inputs and outputs are not journaled.
@@ -56,11 +89,15 @@ import type { Logger, NodeResult, NodeUsage, RouteRung, Skill, Workflow } from "
 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;
+/**
+ * v3: each record's HMAC chains the run id and the previous record's HMAC.
+ * (v2 authenticated records one by one; v1 used a public checksum. Both are refused.)
+ */
+export declare const JOURNAL_SCHEMA_VERSION = 3;
+/** Where journals lived before v3: in the workspace. Never read for resume, only recognized to refuse. */
+export declare const LEGACY_JOURNAL_DIR: string;
 export declare const JOURNAL_FILE = "journal.ndjson";
-/** Journals kept on disk; the oldest beyond this are deleted when a new run starts. */
+/** Journals kept per workspace; the oldest beyond this are deleted when a new run starts. */
 export declare const JOURNAL_KEEP = 20;
 export declare const REDACTED = "[redacted]";
 /** sha256 (hex) of `value` as canonical JSON: keys sorted, undefined dropped. Same as run history's workflow hash. */
@@ -88,16 +125,69 @@ export declare function instructionHash(sources: Record<string, {
 export declare function toolsHash(skills: Map<string, Skill>, swenyVersion?: string, harnessId?: string, secrets?: string[]): string;
 /** sweny's per-user state dir: `$SWENY_STATE_DIR`, else `$XDG_STATE_HOME/sweny`, else `~/.local/state/sweny`. */
 export declare function swenyStateDir(env?: Record<string, string | undefined>): string;
-/** Where run keys live. Never inside the workspace. */
-export declare function runKeyDir(env?: Record<string, string | undefined>): string;
-/** The key file for one run in one workspace (the workspace path is hashed, not stored). */
-export declare function runKeyFile(cwd: string, runId: string, keyDir?: string): string;
+/** Where every run journal (and its key, head, meta and lock) lives. Agents can neither read nor write it. */
+export declare function runStateRoot(env?: Record<string, string | undefined>): string;
+/** The workspace's directory name under {@link runStateRoot}: its real path hashed, never stored. */
+export declare function workspaceScope(cwd: string): string;
+/** One run's private directory: `<state>/runs/<workspace-hash>/<run-id>/`. */
+export declare function journalDir(cwd: string, runId: string, root?: string): string;
+/** The run's key file (inside its private directory). */
+export declare function runKeyFile(cwd: string, runId: string, root?: string): string;
+/** Thrown when the journal's state dir resolves into the workspace, where an agent could edit it. */
+export declare class JournalLocationError extends Error {
+    constructor(dir: string, cwd: string);
+}
+/**
+ * Refuse a state dir that resolves into the workspace. Real paths are compared
+ * (the dir must exist), so a symlink anywhere in either chain counts as where
+ * it points. Throws {@link JournalLocationError}.
+ */
+export declare function assertStateOutsideWorkspace(dir: string, cwd: string): void;
 /** Thrown when a journal's key is missing or unreadable: its records cannot be checked. */
 export declare class JournalKeyError extends Error {
     constructor(file: string, why: string);
 }
 /** Read a run key. Throws {@link JournalKeyError}. */
 export declare function loadRunKey(file: string): Buffer;
+/** Thrown when the journal is shorter than, or disagrees with, the record its head file holds. */
+export declare class JournalRollbackError extends Error {
+    constructor(message: string);
+}
+/**
+ * The record being appended (seq 0 and no record before the first append).
+ * Written atomically BEFORE the record goes to the journal, so the journal is
+ * either at the head or exactly one record short of it (a crash in between),
+ * never anything else.
+ */
+export interface JournalHead {
+    seq: number;
+    record: JournalRecord | null;
+}
+/** Read and authenticate a run's head file. Throws {@link JournalRollbackError}. */
+export declare function loadJournalHead(dir: string, key: Buffer, runId: string): JournalHead;
+/** Thrown when another live process holds the run. */
+export declare class JournalLockedError extends Error {
+    readonly pid: number;
+    constructor(pid: number);
+}
+/** Start time (ms since epoch) of a process, where the OS exposes it cheaply (Linux); else undefined. */
+export declare function processStartTime(pid: number): number | undefined;
+/** Test seam for the lock: called after a stale lock was read, before it is taken over. */
+export interface LockHooks {
+    afterStaleRead?(): void;
+}
+/** An acquired run lock. */
+export interface RunLock {
+    readonly file: string;
+    release(): void;
+}
+/**
+ * Take a run's lock: O_CREAT|O_EXCL in the run's private dir. A lock whose
+ * process is gone is taken over under a second exclusive lock, and only if it
+ * still holds the exact bytes judged stale, so two processes racing for a
+ * stale lock cannot both win. Throws {@link JournalLockedError}.
+ */
+export declare function acquireRunLock(dir: string, hooks?: LockHooks): RunLock;
 /** True for keys like `GITHUB_TOKEN`, `apiKey`, `client-secret`, `Authorization`. */
 export declare function isSecretKey(key: string): boolean;
 /** Values of secret-named env vars / config entries, longest first (8+ chars, so short words never match). */
@@ -185,15 +275,20 @@ export declare class JournalMismatchError extends Error {
     readonly what: string[];
     constructor(what: string[]);
 }
-/** Thrown when another live process holds the run's journal. */
-export declare class JournalLockedError extends Error {
-    constructor(pid: number);
+/** Thrown when the journal cannot be written. Fatal: the executor stops the run before anything else happens. */
+export declare class JournalWriteError extends Error {
+    constructor(message: string);
 }
 export interface JournalRead {
     file: string;
+    /** Authenticated, chained records only: everything a resume replays or seeds spend from. */
     records: JournalRecord[];
-    /** Bytes dropped from a torn / corrupt tail (0 when the file was clean). */
+    /** Bytes dropped from a torn tail (0 when the file was clean). */
     truncatedBytes: number;
+    /** The last record is whole and authenticated but lost its line end (repair restores it). */
+    missingNewline?: boolean;
+    /** The last record was missing from the journal (a crash after the head write) and was restored from the head. */
+    restored?: boolean;
     /**
      * Set when an invalid record sits before valid ones (not a torn tail), or when
      * a whole record fails authentication (tampering, never a torn write). Not repairable.
@@ -202,18 +297,31 @@ export interface JournalRead {
     /** The line whose record failed authentication, when that is why the journal is refused. */
     forgedAtLine?: number;
 }
-/**
- * Read a journal. With `repair`, a torn tail is truncated on disk back to the
- * last valid record. Records are authenticated with the run's key (`key`, else
- * loaded from the state dir for the run the path names). Throws
- * {@link JournalVersionError} for another format and {@link JournalKeyError}
- * when the key is missing.
- */
-export declare function readJournal(file: string, opts?: {
+export interface ReadJournalOptions {
+    /** Truncate a torn tail on disk, restore a lost final line end, and re-append a record restored from the head. */
     repair?: boolean;
+    /** The run key; default: the `key` file next to the journal. */
     key?: Buffer;
-    keyDir?: string;
-}): JournalRead;
+    /** The run id the records are chained to; default: the journal's directory name. */
+    runId?: string;
+    /**
+     * The run's head; default: the authenticated `head.json` next to the journal.
+     * `false` skips the length check: only for inspecting raw bytes, never on a
+     * path that resumes.
+     */
+    head?: JournalHead | false;
+}
+/**
+ * Read a journal from a run's private directory. Records are authenticated
+ * and chained with the run key, then checked against the head: the journal
+ * must end at the head's record, or one short of it (then that record is
+ * restored from the head). Only an unterminated final segment that is not
+ * complete JSON is a torn append; with `repair` it is cut. Throws
+ * {@link JournalVersionError} for another format, {@link JournalKeyError}
+ * when the key is missing and {@link JournalRollbackError} when the journal
+ * was cut back or does not match its head.
+ */
+export declare function readJournal(file: string, opts?: ReadJournalOptions): JournalRead;
 export type VisitAction = "replay" | "write-stage" | "rerun";
 export interface PlannedVisit {
     node: string;
@@ -250,6 +358,12 @@ export interface ResumePlan {
     receipts: Map<string, OutputRecord>;
     /** Spend every earlier attempt journaled: the run budget starts here on resume. */
     priorSpend: Spend;
+    /**
+     * Nodes whose agent ran without an enforced sandbox in an earlier attempt.
+     * Such an agent could read the run key, so the journal's spend and write
+     * records are only as trustworthy as that agent.
+     */
+    unsandboxed: string[];
     /** The decider's mode at run start and its counters after the last journaled route (#357). */
     decider?: JournalDeciderState;
 }
@@ -321,8 +435,9 @@ export type JournalReplay = {
     kind: "checkpoint";
 } & JournalCheckpoint);
 /**
- * The executor's view of a journal (`ExecuteOptions.journal`). Every hook is
- * best effort except at resume, where `begin` refuses a changed run.
+ * The executor's view of a journal (`ExecuteOptions.journal`). A hook that
+ * cannot write its record throws {@link JournalWriteError}: the executor
+ * stops the run there. At resume, `begin` refuses a changed run.
  */
 export interface ExecutionJournal {
     begin(info: JournalBeginInfo): void;
@@ -337,23 +452,30 @@ export interface ExecutionJournal {
     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).
+     * attempt returned, otherwise a live report (written at once when it raises the spend).
      */
     usage?(node: string, iteration: number, attempt: number, usage: NodeUsage, final: boolean): void;
+    /** The visit's agent ran without an enforced sandbox: recorded so a resume can say so. */
+    uncontained?(node: string, iteration: number): void;
     /** Spend earlier attempts of this run already journaled (resume); the run budget starts from it. */
     priorSpend?(): Spend | undefined;
+    /** Receipt `degraded` entries this journal adds to the run (e.g. `journal_unsandboxed`). */
+    degraded?(): string[];
     /** 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;
-/** Test seam: called before each append; a throw simulates the process dying there. */
+/** Test seams: a throw simulates the process dying at that point of an append. */
 export interface JournalFaults {
+    /** Before anything of the record reaches the disk. */
     beforeAppend?(record: JournalRecord): void;
+    /** After the head holds the record, before the journal append. */
+    afterHeadUpdate?(record: JournalRecord): void;
+    /** Replaces the journal write (a throw is an I/O failure, not a process death). */
+    writeJournal?(fd: number, line: string): void;
 }
 export interface RunJournalOptions {
     runId: string;
-    /** Base directory; the journal goes in `<cwd>/.sweny/runs/<run-id>/`. Default: process.cwd(). */
+    /** The workspace the run belongs to (its real path, hashed, names the run's state dir). Default: process.cwd(). */
     cwd?: string;
     /** Workflow file the run came from, so `resume` can load it again. */
     workflowFile?: string;
@@ -362,57 +484,80 @@ export interface RunJournalOptions {
     env?: Record<string, string | undefined>;
     logger?: Logger;
     faults?: JournalFaults;
-    /** Journals kept on disk (default {@link JOURNAL_KEEP}). */
+    /** Journals kept per workspace (default {@link JOURNAL_KEEP}). */
     keep?: number;
-    /** Where run keys live (default {@link runKeyDir}). Never inside the workspace. */
-    keyDir?: string;
+    /** Where run journals live (default {@link runStateRoot}). Never inside the workspace. */
+    stateRoot?: string;
 }
 export interface ResumeJournalOptions extends RunJournalOptions {
     read: JournalRead;
     plan: ResumePlan;
+    /** The run's lock, taken before the journal was read ({@link lockRun}). */
+    lock: RunLock;
     /** Resume even though the workflow, instructions, input or tools changed. */
     force?: boolean;
     /** Re-send writes whose outcome cannot be confirmed on the provider. */
     allowRepeatWrites?: boolean;
 }
-export declare function journalDir(cwd: string, runId: string): string;
-/** Run ids with a journal on disk, oldest first. */
-export declare function listJournalRuns(cwd?: string): string[];
-/** Exact run id, or a unique prefix. */
-export declare function findJournalRun(ref: string, cwd?: string): string | undefined;
-/** Delete the oldest journals (and their keys) beyond `keep`, never `except`. Never throws. */
-export declare function pruneJournals(cwd: string, keep?: number, except?: string, keyDir?: string): number;
+/** A run's journal file. */
+export declare function journalFile(cwd: string, runId: string, root?: string): string;
+/**
+ * Runs of this workspace with a journal, oldest first. Only the state dir is
+ * read, and only runs whose metadata authenticates count: nothing in the
+ * workspace can add, hide or reorder a run.
+ */
+export declare function listJournalRuns(cwd?: string, root?: string): string[];
+/** Exact run id, or a unique prefix, among this workspace's journaled runs. */
+export declare function findJournalRun(ref: string, cwd?: string, root?: string): string | undefined;
+/** A journal an older sweny left in the workspace for this run id (or unique prefix), if any. Never read. */
+export declare function findLegacyJournal(ref: string, cwd?: string): string | undefined;
+/**
+ * Delete this workspace's oldest journals beyond `keep`, never `except`, by
+ * their authenticated creation time. Runs whose metadata does not
+ * authenticate are never deleted. Never throws.
+ */
+export declare function pruneJournals(cwd: string, keep?: number, except?: string, root?: string): number;
+/** Take a run's lock before reading its journal (resume). Throws {@link JournalLockedError}. */
+export declare function lockRun(cwd: string, runId: string, root?: string, hooks?: LockHooks): RunLock;
 export declare class RunJournal implements ExecutionJournal {
     readonly runId: string;
     readonly dir: string;
     readonly file: string;
     private readonly cwd;
+    private readonly root;
     private readonly opts;
     private readonly logger;
     private readonly resume?;
     private fd;
     private seq;
-    private dead;
+    /** MAC of the last record written: the next record chains to it. */
+    private prev;
+    /** Set once an append failed: every later append throws it again. */
+    private failure;
+    /** Set when a fault seam simulated the process dying: nothing more is written. */
+    private killed;
     private began;
     private closed;
     private secrets;
     private consumed;
-    /** Per-run HMAC key; lives only here and in the key file outside the workspace. */
+    /** Per-run HMAC key; lives only here and in the run's private state dir. */
     private key;
-    private readonly keyFile;
+    private lock;
     /** Last live usage record per attempt: time and spend, for throttling. */
     private lastUsage;
+    /** Visits already recorded as run without an enforced sandbox. */
+    private uncontainedVisits;
     private constructor();
     /** A journal for a new run. Nothing touches disk until the executor calls `begin`. */
     static create(opts: RunJournalOptions): RunJournal;
-    /** A journal that continues `opts.read` (already repaired) under the resume plan. */
+    /** A journal that continues `opts.read` (already repaired, under `opts.lock`) under the resume plan. */
     static openForResume(opts: ResumeJournalOptions): RunJournal;
-    /** False once an append failed: the rest of the run is not journaled. */
+    /** False once an append failed (or the process was simulated dead): the run cannot be resumed past that point. */
     get active(): boolean;
-    private takeLock;
-    /** The run dir is private (0700); no link on the path from cwd is followed (safe-file.ts). */
-    private makeDir;
     private releaseLock;
+    /** Mark the journal failed and throw: the run must stop here. */
+    private fail;
+    private simulatedDeath;
     private append;
     private closeFd;
     private clean;
@@ -423,9 +568,19 @@ export declare class RunJournal implements ExecutionJournal {
     checkpoint(node: string, iteration: number, cp: JournalCheckpoint): void;
     nodeEnd(node: string, iteration: number, result: NodeResult, writeState: WriteStageState): void;
     route(from: string, to: string | null, rung?: RouteRung, decider?: DeciderCounters): void;
+    /**
+     * Journal one usage report, synchronously, whenever it raises the attempt's
+     * spend (reports are cumulative; the largest figure seen per unit counts).
+     * Nothing is held back: harnesses report once per model turn (Claude Code
+     * per assistant message, ACP per usage update), so every turn's spend is on
+     * disk before the next turn runs, and a process killed at any point has lost
+     * at most the turn it was in.
+     */
     usage(node: string, iteration: number, attempt: number, usage: NodeUsage, final: boolean): void;
+    uncontained(node: string, iteration: number): void;
+    degraded(): string[];
     priorSpend(): Spend | undefined;
-    /** Close the run: `run:end`, then release the lock. Safe to call twice (one run:end). */
+    /** Close the run: `run:end` (when the journal still works), then release the lock. Never throws. */
     end(status: "success" | "failed" | "crashed"): void;
     wrapWrites(node: string, iteration: number, skills: Map<string, Skill>): Map<string, Skill>;
     private wrapTool;