@basou/core 0.9.0 → 0.11.0

package/dist/index.d.ts

@@ -1411,12 +1411,14 @@ declare const SessionMetricsSchema: z.ZodObject<{
 /** Inferred runtime type for {@link SessionMetricsSchema}. */
 type SessionMetrics = z.infer<typeof SessionMetricsSchema>;
 /**
- * Tamper-evidence head anchor for sessions whose `events.jsonl` was written
- * with hash chaining (import / in-place re-import): `head_hash` is the hex
- * sha-256 of the last written event line (excluding the trailing newline),
- * `event_count` the number of chained lines. Absent on live / ad-hoc /
- * pre-feature sessions. Additive optional => no schema_version bump.
- * `.strict()` because the import writer fully owns the shape.
+ * Tamper-evidence head anchor for a session whose `events.jsonl` is hash
+ * chained: `head_hash` is the hex sha-256 of the last written event line
+ * (excluding the trailing newline), `event_count` the number of chained lines.
+ * Written by the import / in-place re-import writers and, for a live session
+ * (`exec` / `run` / ad-hoc), by the finalize once it reaches a terminal status.
+ * Absent on a still-live session (the anchor is stamped at finalize) and on a
+ * pre-feature unchained session. Additive optional => no schema_version bump.
+ * `.strict()` because the writers fully own the shape.
  */
 declare const SessionIntegritySchema: z.ZodObject<{
     head_hash: z.ZodString;
@@ -1553,6 +1555,35 @@ declare function enumerateSessionDirs(paths: BasouPaths): Promise<string[]>;
  *   or the zod error).
  */
 declare function readSessionYaml(paths: BasouPaths, sessionId: string): Promise<Session>;
+/**
+ * Apply a terminal-status mutation to a live session's `session.yaml` AND, in
+ * the same locked write, stamp the tamper-evidence head anchor derived from the
+ * on-disk `events.jsonl` tail. Used by the `exec` / `run` orchestrators for
+ * BOTH terminal writers (the normal end-of-run finalize and the spawn-failure
+ * `failed` finalize).
+ *
+ * Why locked + anchor-from-tail: live appends chain the LOG only and leave the
+ * anchor for finalize. Reading the final tail under the session lock means a
+ * foreign line appended just before finalize (e.g. a `decision record` attached
+ * to a still-running session) is included in the anchor, and a foreign attach
+ * that arrives after the terminal status is set is rejected by the attach gate
+ * — so the anchor can never disagree with the at-rest log. The whole-document
+ * read-modify-write also preserves any field a foreign locked writer set (e.g.
+ * a task attach's `task_id`).
+ *
+ * The anchor is written only when the log is actually chained with at least one
+ * line; a legacy unchained session (and an empty log) is left with no
+ * `integrity` anchor, matching the import writers. The mutator receives the
+ * full {@link Session} document and typically sets
+ * `session.session.status` / `ended_at` / `invocation.exit_code` /
+ * `related_files`.
+ *
+ * Throws the {@link inspectChainTail} errors (torn / mixed log), the
+ * {@link readSessionYaml} errors, a zod error if the mutation produces an
+ * invalid document, or `Error("Failed to overwrite YAML file")` on a disk
+ * failure.
+ */
+declare function finalizeSessionYaml(paths: BasouPaths, sessionId: string, mutate: (session: Session) => void): Promise<void>;
 /**
  * Classify a `running` session as suspect using one of two rules:
  *
@@ -1680,6 +1711,86 @@ declare function chainEvents(events: ReadonlyArray<Event>, sessionId: string): C
  */
 declare function chainRawJsonLines(rawLines: ReadonlyArray<string>, sessionId: string): ChainedEvents;
 
+/**
+ * The chain state of an existing `events.jsonl`, as needed by the live append
+ * and finalize paths.
+ *
+ * - `chained` — whether the NEXT line written to this log must carry a
+ *   `prev_hash`. True for an empty / not-yet-created log (a fresh session
+ *   chains from its genesis) and for a log whose FIRST complete line already
+ *   carries `prev_hash`. False for a legacy / pre-feature log whose first line
+ *   is unchained (so it stays unchained — we never half-chain a file).
+ * - `head` — the `prev_hash` value the next line carries when `chained`:
+ *   `genesisHash(sessionId)` for an empty log, otherwise `lineHash` of the LAST
+ *   complete line's raw bytes. Meaningless (set to the genesis hash) when
+ *   `chained` is false.
+ * - `count` — number of complete (newline-terminated) lines on disk; the
+ *   `event_count` an integrity anchor records.
+ */
+type ChainTailState = {
+    chained: boolean;
+    head: string;
+    count: number;
+};
+/**
+ * Inspect `<sessions>/<sessionId>/events.jsonl` to decide how the next append
+ * (or the finalize anchor) must treat the chain. READ-ONLY; the caller MUST
+ * already hold the session lock so the inspected tail cannot move underneath a
+ * subsequent append.
+ *
+ * Chained-ness is decided from the FIRST complete line (does the log claim to
+ * be chained), and the head pointer is taken from the LAST complete line. If
+ * the first and last lines DISAGREE — a mixed / partially-tampered file — the
+ * call THROWS rather than extending a broken chain; verify is the detector, the
+ * writer must not deepen a break. An unterminated final line (a torn tail from
+ * a crashed prior append) also THROWS so a new line is never glued onto a
+ * fragment.
+ *
+ * Throws `Error("Failed to read events.jsonl")` for non-ENOENT I/O,
+ * `Error("Unterminated final line in events.jsonl")` for a torn tail, and
+ * `Error("events.jsonl is partially chained")` for a mixed first/last line.
+ */
+declare function inspectChainTail(paths: BasouPaths, sessionId: string): Promise<ChainTailState>;
+/**
+ * Append one event to `<sessions>/<sessionId>/events.jsonl`, threading the
+ * tamper-evidence hash chain. The caller MUST already hold the session lock
+ * (`acquireLock(paths, "session", sessionId)`); this function does NOT acquire
+ * it, so it composes inside a larger caller-owned critical section (the
+ * convention used by `decision record`, `session note`, task attach and
+ * approval resolution) without re-entrant lock deadlock.
+ *
+ * The event is validated against {@link EventSchema}, then — if the existing
+ * log is chained (or empty) — written with a `prev_hash` back-pointer derived
+ * from the real on-disk tail (see {@link inspectChainTail}); a legacy unchained
+ * log keeps receiving plain unchained lines. The single serializer
+ * ({@link serializeEventLine}) is shared with the bulk writers so the bytes a
+ * chain hashes can never diverge from another path's bytes.
+ *
+ * Does NOT touch `session.yaml.integrity`: the head anchor is written once, at
+ * the terminal-status finalize, by {@link finalizeSessionYaml}. A still-live
+ * session therefore has a chained log but no anchor yet, which `verify` reports
+ * as the benign `in_progress`.
+ *
+ * Throws `"Invalid Basou event payload"` on validation failure, the
+ * {@link inspectChainTail} errors on a torn / mixed log, or `"Failed to append
+ * event to events.jsonl"` on a disk failure. The native error is attached as
+ * `cause`.
+ */
+declare function appendChainedEventLocked(paths: BasouPaths, sessionId: string, event: unknown): Promise<{
+    chained: boolean;
+}>;
+/**
+ * Self-locking wrapper around {@link appendChainedEventLocked} for callers that
+ * do NOT already hold the session lock (the `exec` / `run` orchestrators, which
+ * append one event at a time to a session they own). Acquires the session lock,
+ * appends, and releases. Each append is a short-lived lock hold — the lock is
+ * NEVER held across a child process — so a foreign attach can interleave safely
+ * and the next append chains onto the true tail.
+ */
+declare function appendChainedEvent(paths: BasouPaths, sessionId: string, event: unknown): Promise<{
+    chained: boolean;
+}>;
+
 /**
  * Append a single Basou event to `<sessionDir>/events.jsonl`.
  *
@@ -1688,10 +1799,13 @@ declare function chainRawJsonLines(rawLines: ReadonlyArray<string>, sessionId: s
  * Validation enforces the per-variant contract (required fields, source
  * vocabulary, strict variants such as `adapter_output`).
  *
- * Appended lines are NOT hash-chained: chaining is exclusive to the bulk
- * import writers ({@link writeEventsBulk} with `chain: true`), and imported
- * sessions reject every append path, so a chained file never receives an
- * unchained appended line.
+ * This LOW-LEVEL writer does NOT hash-chain — it writes the validated event as
+ * a plain line. Hash-chained appends go through `appendChainedEvent` /
+ * `appendChainedEventLocked` (the live `exec` / `run` / attach / approval
+ * paths), and the bulk import writers chain via {@link writeEventsBulk} with
+ * `chain: true`. A direct caller of this raw export can still add an unchained
+ * line to a chained log; that is DETECTED by `basou verify`
+ * (`missing_prev_hash`), not prevented — a documented boundary.
  *
  * Atomicity: writes go through `appendFile` which uses `O_APPEND`. Lines up
  * to `PIPE_BUF` bytes (Linux 4096 / macOS 512) are written atomically by the
@@ -1758,10 +1872,15 @@ declare function writeEventsBulk(sessionDir: string, events: Event[], options?:
  *   (an import crashed between the events write and the yaml write, or the
  *   yaml was deleted out of band). Benign: a re-import / `--force` repairs it.
  * - `tampered` — a real integrity break (see {@link ChainBreakReason}).
+ * - `in_progress` — a chained log whose session is still LIVE (a non-terminal
+ *   status: initialized / running / waiting_approval). The internal
+ *   back-pointer chain is fully verified, but the tail and head anchor are
+ *   forgiven because a live session's log is legitimately still growing and its
+ *   anchor is not written until the terminal finalize. Informational, exit 0.
  * - `verified` — every back-pointer, genesis, session-id and line-discipline
  *   check passed AND the head anchor matches the on-disk log.
  */
-type ChainVerdictStatus = "verified" | "unchained" | "empty" | "incomplete" | "tampered";
+type ChainVerdictStatus = "verified" | "unchained" | "empty" | "incomplete" | "in_progress" | "tampered";
 /** Machine-readable detail for a `tampered` (or `incomplete`) verdict. */
 type ChainBreakReason = 
 /** The file does not end with `\n`; chained writers always terminate the last line. */
@@ -1818,6 +1937,11 @@ type ChainVerdict = {
  *   and finally the head anchor (`incomplete` when `session.yaml` is entirely
  *   absent; `tampered` when it is present without a matching anchor).
  *
+ * - When the chained log belongs to a LIVE session (a non-terminal status),
+ *   the internal chain is verified but a torn tail / absent / mismatching
+ *   anchor is FORGIVEN as `in_progress`: a live session's tail is legitimately
+ *   still growing and its anchor is written only at the terminal finalize.
+ *
  * NON-CRYPTOGRAPHIC: the anchor lives in `session.yaml`, which is itself
  * editable; an attacker rewriting BOTH files consistently is not detected.
  * Signing is a follow-up.
@@ -1825,6 +1949,12 @@ type ChainVerdict = {
  * Throws `Error("Failed to read events.jsonl")` only for non-ENOENT I/O
  * failures (EACCES etc.) — an unreadable file is an environment problem, not
  * a verdict.
+ *
+ * READ-ONLY and lock-free: a session being finalized concurrently can leave the
+ * two files momentarily out of step (old events read before a finalize, new
+ * anchor read after it). A strict `anchor_mismatch` is therefore re-snapshotted
+ * ONCE before being returned — a genuine mismatch is deterministic across the
+ * retry, while a finalize-in-flight resolves within it.
  */
 declare function verifyEventsChain(paths: BasouPaths, sessionId: string): Promise<ChainVerdict>;
 
@@ -2006,8 +2136,8 @@ declare function isValidPrefixedId(value: string): boolean;
  * Self-edges are rejected so the audit trail stays monotonic.
  */
 declare const TaskStatusSchema: z.ZodEnum<{
-    planned: "planned";
     in_progress: "in_progress";
+    planned: "planned";
     done: "done";
     cancelled: "cancelled";
 }>;
@@ -2027,8 +2157,8 @@ declare const TaskSchema: z.ZodObject<{
         title: z.ZodString;
         label: z.ZodOptional<z.ZodString>;
         status: z.ZodEnum<{
-            planned: "planned";
             in_progress: "in_progress";
+            planned: "planned";
             done: "done";
             cancelled: "cancelled";
         }>;
@@ -2778,6 +2908,13 @@ declare function renderHandoff(input: HandoffRendererInput): Promise<HandoffRend
  */
 declare function parseDuration(input: string): number;
 
+/**
+ * Coarse human duration from milliseconds: "3h 05m" / "12m 30s" / "8s".
+ * Shared by the work-stats surfaces (`basou stats`, `basou session show`) and
+ * the report renderer so they format identically.
+ */
+declare function formatDurationMs(ms: number): string;
+
 /**
  * Resolve a possibly-truncated session id prefix to a full session id by
  * scanning `<paths.sessions>/`. Existing message contract (carried over
@@ -2889,122 +3026,6 @@ type SanitizeRelatedFilesResult = {
  */
 declare function sanitizeRelatedFiles(paths: ReadonlyArray<string>, opts: SanitizePathOptions): SanitizeRelatedFilesResult;
 
-/**
- * Internal abstraction over child-process execution.
- *
- * The v0.1 implementation is intentionally minimal:
- * - Optional UTF-8 stdout/stderr capture (`capture: "buffer"`, default) or
- *   pass-through to the parent's stdio (`capture: "none"`).
- * - No stream callbacks for partial chunks.
- * - No event emission. Callers wire any event flow separately.
- *
- * The boundary is internal: ProcessRunner is not part of the public
- * adapter surface. Adapters do not import or instantiate it directly;
- * CLI / Core orchestration owns construction and invocation.
- */
-/**
- * Output capture mode.
- *
- * - `"buffer"` (default): pipe stdout/stderr to the runner and accumulate
- *   the full UTF-8 string into {@link RunResult}.
- * - `"none"`: inherit the parent's stdio. The child writes directly to the
- *   parent terminal in real time and {@link RunResult.stdout} /
- *   {@link RunResult.stderr} are empty strings. `stdin` cannot be combined
- *   with `"none"` because the child has no writable stdin pipe.
- */
-type CaptureMode = "buffer" | "none";
-type RunOptions = {
-    /**
-     * Working directory for the child process. Required: callers resolve
-     * the workspace root themselves; the runner does not validate cwd
-     * existence and surfaces native spawn errors via classification.
-     */
-    readonly cwd: string;
-    /**
-     * Environment variables for the child. When omitted, the parent's
-     * `process.env` is inherited verbatim. Callers wanting a sanitized
-     * environment must build it explicitly.
-     */
-    readonly env?: NodeJS.ProcessEnv;
-    /**
-     * External cancellation. Aborting the signal triggers a two-stage
-     * kill (SIGTERM, then SIGKILL after a short grace period).
-     */
-    readonly signal?: AbortSignal;
-    /**
-     * Internal timeout in milliseconds. Must be a positive finite number.
-     * Triggers the same two-stage kill as `signal`.
-     */
-    readonly timeout_ms?: number;
-    /**
-     * Optional input written to the child's stdin. The pipe is closed
-     * after the value is written. Incompatible with `capture: "none"`.
-     */
-    readonly stdin?: string | Buffer;
-    /**
-     * Output capture mode. Defaults to `"buffer"`. See {@link CaptureMode}.
-     */
-    readonly capture?: CaptureMode;
-    /**
-     * Invoked synchronously immediately after the child has been spawned,
-     * before the runner waits for completion. Callers use this to retain a
-     * reference for parent-side cleanup (e.g. an `exit` hook that SIGKILLs
-     * the child if the parent is forcibly terminated). The runner takes no
-     * action if the callback throws.
-     */
-    readonly onSpawn?: (child: ChildProcess) => void;
-};
-type RunResult = {
-    readonly command: string;
-    readonly args: readonly string[];
-    readonly cwd: string;
-    /** `null` when the process was killed by a signal. */
-    readonly exit_code: number | null;
-    readonly signal: NodeJS.Signals | null;
-    readonly stdout: string;
-    readonly stderr: string;
-    /** ISO 8601 timestamp captured before spawn. */
-    readonly started_at: string;
-    /** ISO 8601 timestamp captured on the `close` event. */
-    readonly ended_at: string;
-    readonly duration_ms: number;
-    readonly pid: number | null;
-};
-type ProcessRunner = {
-    run(command: string, args: readonly string[], options: RunOptions): Promise<RunResult>;
-};
-
-/**
- * Spawn-based ProcessRunner implementation.
- *
- * Behavior:
- * - `shell: false` and `detached: false`. The process group is not
- *   detached, but the OS does not guarantee the child is reaped when
- *   the parent terminates abruptly; callers handle SIGINT/SIGTERM/exit
- *   hooks themselves.
- * - `capture: "buffer"` (default): `stdio: ['pipe', 'pipe', 'pipe']`,
- *   stdout / stderr are decoded as UTF-8 and accumulated as full
- *   strings (no streaming callbacks).
- * - `capture: "none"`: `stdio: ['inherit', 'inherit', 'inherit']`, the
- *   child writes directly to the parent terminal in real time and
- *   `RunResult.stdout` / `stderr` are empty strings. `stdin` is
- *   incompatible with this mode (the child has no writable stdin pipe)
- *   and the combination is rejected before spawn.
- * - `timeout_ms` and `AbortSignal` both trigger a two-stage kill:
- *   `SIGTERM`, then `SIGKILL` after `DEFAULT_KILL_GRACE_MS` (5_000 ms).
- * - A non-zero `exit_code` does not throw; it is returned via
- *   `RunResult`. Spawn-time errors throw with a pathless message and
- *   the original error attached as `cause`.
- *
- * Error message contract: messages never include `cwd` or absolute
- * command paths. The original errno (and any nested wrapping) is
- * preserved on `Error.cause`, allowing callers to classify with
- * `findErrorCode` when needed.
- */
-declare class ChildProcessRunner implements ProcessRunner {
-    run(command: string, args: readonly string[], options: RunOptions): Promise<RunResult>;
-}
-
 /**
  * Schema version of the on-disk Basou v0.1 formats these JSON Schemas describe.
  * It tracks {@link SchemaVersionSchema} (the `schema_version` field), NOT the
@@ -3342,6 +3363,253 @@ declare function computeWorkStats(input: WorkStatsInput): Promise<WorkStatsResul
  */
 declare function sessionWorkStatsFromEvents(sessionId: string, inner: Session["session"], events: ReadonlyArray<Event>, now: Date, eventsUnreadable?: boolean): SessionWorkStats;
 
+type ReportRendererInput = {
+    paths: BasouPaths;
+    /** ISO timestamp stamped into the report header and used as the clock. */
+    nowIso: string;
+    /** Optional subject line surfaced in the report title. */
+    title?: string;
+    /**
+     * IANA timezone passed through to {@link computeWorkStats} (it labels the
+     * time figures with the zone). The CLI omits this (host default); tests and
+     * the SDK pass a fixed value for deterministic output. [Codex #5]
+     */
+    timeZone?: string;
+    onWarning?: (warning: ReplayWarning, sessionId: string) => void;
+    onSessionSkip?: (sessionId: string, reason: SessionSkipReason) => void;
+    onTaskSkip?: (taskId: string, reason: TaskSkipReason) => void;
+};
+type ReportSessionItem = {
+    id: string;
+    label: string | null;
+    status: SessionStatus;
+    source: SessionSourceKind;
+    startedAt: string;
+    activeMs: number;
+    outputTokens: number;
+};
+type ReportDecisionItem = {
+    id: string;
+    title: string;
+    occurredAt: string;
+};
+type ReportTaskItem = {
+    id: string;
+    title: string;
+    status: TaskStatus;
+};
+type ReportApprovalItem = {
+    id: string;
+    reason: string;
+    status: ApprovalStatus;
+    riskLevel: RiskLevel;
+};
+type TaskStatusCount = {
+    status: TaskStatus;
+    count: number;
+};
+/**
+ * Curated, purpose-built structured shape behind `basou report generate
+ * --json`. Deliberately NOT the full {@link WorkStatsResult} — report's JSON
+ * stays a stable contract decoupled from the stats schema. Field names avoid
+ * the word "billable": a report is a neutral work-explanation export, not a
+ * billing artifact. [Codex #2]
+ */
+type ReportData = {
+    generatedAt: string;
+    title?: string;
+    /** Earliest session start .. latest session end (or `now` for open sessions). */
+    period: {
+        from: string | null;
+        to: string | null;
+    };
+    sessions: {
+        total: number;
+        byStatus: StatusCount[];
+        items: ReportSessionItem[];
+    };
+    volume: {
+        outputTokens: number;
+        reasoningTokens: number;
+        commandCount: number;
+        fileChangedCount: number;
+        decisionCount: number;
+        tokensAvailable: boolean;
+    };
+    time: {
+        activeMs: number;
+        machineActiveMs: number;
+        machineAvailable: boolean;
+        spanMs: number;
+        commandTimeMs: number;
+        timeZone: string;
+    };
+    decisions: {
+        count: number;
+        items: ReportDecisionItem[];
+    };
+    approvals: {
+        pending: number;
+        approved: number;
+        rejected: number;
+        expired: number;
+        items: ReportApprovalItem[];
+    };
+    tasks: {
+        total: number;
+        byStatus: TaskStatusCount[];
+        items: ReportTaskItem[];
+    };
+    /** Union of related files across non-`import` sessions (full; markdown truncates). */
+    changedFiles: string[];
+    integrity: {
+        total: number;
+        verified: number;
+        unchained: number;
+        empty: number;
+        incomplete: number;
+        in_progress: number;
+        tampered: number;
+        /** Session ids whose chain is `tampered`, surfaced for follow-up. */
+        tamperedSessions: string[];
+    };
+};
+type ReportRendererResult = {
+    body: string;
+    data: ReportData;
+};
+/**
+ * Render a neutral "work report" — a point-in-time export that explains the
+ * work captured in a workspace: how much, what was decided / approved /
+ * undertaken, which files changed, and whether the local provenance is
+ * internally consistent. It composes existing read primitives only and writes
+ * nothing; the caller chooses where `body` goes (stdout / a file) and whether
+ * to emit the structured `data` as JSON.
+ *
+ * Warning surfaces mirror the sibling renderers: `loadSessionEntries` (suspect
+ * classification) and the decision-aggregation replay (with the same
+ * unreadable-skip wrapper as `decisions-renderer.ts`) report through the
+ * callbacks. {@link computeWorkStats} runs SILENTLY here — it re-reads the same
+ * sessions/events, so surfacing its warnings too would double-emit. [Codex #6]
+ */
+declare function renderReport(input: ReportRendererInput): Promise<ReportRendererResult>;
+
+/**
+ * Internal abstraction over child-process execution.
+ *
+ * The v0.1 implementation is intentionally minimal:
+ * - Optional UTF-8 stdout/stderr capture (`capture: "buffer"`, default) or
+ *   pass-through to the parent's stdio (`capture: "none"`).
+ * - No stream callbacks for partial chunks.
+ * - No event emission. Callers wire any event flow separately.
+ *
+ * The boundary is internal: ProcessRunner is not part of the public
+ * adapter surface. Adapters do not import or instantiate it directly;
+ * CLI / Core orchestration owns construction and invocation.
+ */
+/**
+ * Output capture mode.
+ *
+ * - `"buffer"` (default): pipe stdout/stderr to the runner and accumulate
+ *   the full UTF-8 string into {@link RunResult}.
+ * - `"none"`: inherit the parent's stdio. The child writes directly to the
+ *   parent terminal in real time and {@link RunResult.stdout} /
+ *   {@link RunResult.stderr} are empty strings. `stdin` cannot be combined
+ *   with `"none"` because the child has no writable stdin pipe.
+ */
+type CaptureMode = "buffer" | "none";
+type RunOptions = {
+    /**
+     * Working directory for the child process. Required: callers resolve
+     * the workspace root themselves; the runner does not validate cwd
+     * existence and surfaces native spawn errors via classification.
+     */
+    readonly cwd: string;
+    /**
+     * Environment variables for the child. When omitted, the parent's
+     * `process.env` is inherited verbatim. Callers wanting a sanitized
+     * environment must build it explicitly.
+     */
+    readonly env?: NodeJS.ProcessEnv;
+    /**
+     * External cancellation. Aborting the signal triggers a two-stage
+     * kill (SIGTERM, then SIGKILL after a short grace period).
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * Internal timeout in milliseconds. Must be a positive finite number.
+     * Triggers the same two-stage kill as `signal`.
+     */
+    readonly timeout_ms?: number;
+    /**
+     * Optional input written to the child's stdin. The pipe is closed
+     * after the value is written. Incompatible with `capture: "none"`.
+     */
+    readonly stdin?: string | Buffer;
+    /**
+     * Output capture mode. Defaults to `"buffer"`. See {@link CaptureMode}.
+     */
+    readonly capture?: CaptureMode;
+    /**
+     * Invoked synchronously immediately after the child has been spawned,
+     * before the runner waits for completion. Callers use this to retain a
+     * reference for parent-side cleanup (e.g. an `exit` hook that SIGKILLs
+     * the child if the parent is forcibly terminated). The runner takes no
+     * action if the callback throws.
+     */
+    readonly onSpawn?: (child: ChildProcess) => void;
+};
+type RunResult = {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+    /** `null` when the process was killed by a signal. */
+    readonly exit_code: number | null;
+    readonly signal: NodeJS.Signals | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    /** ISO 8601 timestamp captured before spawn. */
+    readonly started_at: string;
+    /** ISO 8601 timestamp captured on the `close` event. */
+    readonly ended_at: string;
+    readonly duration_ms: number;
+    readonly pid: number | null;
+};
+type ProcessRunner = {
+    run(command: string, args: readonly string[], options: RunOptions): Promise<RunResult>;
+};
+
+/**
+ * Spawn-based ProcessRunner implementation.
+ *
+ * Behavior:
+ * - `shell: false` and `detached: false`. The process group is not
+ *   detached, but the OS does not guarantee the child is reaped when
+ *   the parent terminates abruptly; callers handle SIGINT/SIGTERM/exit
+ *   hooks themselves.
+ * - `capture: "buffer"` (default): `stdio: ['pipe', 'pipe', 'pipe']`,
+ *   stdout / stderr are decoded as UTF-8 and accumulated as full
+ *   strings (no streaming callbacks).
+ * - `capture: "none"`: `stdio: ['inherit', 'inherit', 'inherit']`, the
+ *   child writes directly to the parent terminal in real time and
+ *   `RunResult.stdout` / `stderr` are empty strings. `stdin` is
+ *   incompatible with this mode (the child has no writable stdin pipe)
+ *   and the combination is rejected before spawn.
+ * - `timeout_ms` and `AbortSignal` both trigger a two-stage kill:
+ *   `SIGTERM`, then `SIGKILL` after `DEFAULT_KILL_GRACE_MS` (5_000 ms).
+ * - A non-zero `exit_code` does not throw; it is returned via
+ *   `RunResult`. Spawn-time errors throw with a pathless message and
+ *   the original error attached as `cause`.
+ *
+ * Error message contract: messages never include `cwd` or absolute
+ * command paths. The original errno (and any nested wrapping) is
+ * preserved on `Error.cause`, allowing callers to classify with
+ * `findErrorCode` when needed.
+ */
+declare class ChildProcessRunner implements ProcessRunner {
+    run(command: string, args: readonly string[], options: RunOptions): Promise<RunResult>;
+}
+
 type AppendBasouGitignoreResult = {
     /** True if the block was appended (or the file was newly created). */
     readonly appended: boolean;
@@ -3754,4 +4022,4 @@ declare function overwriteYamlFile(filePath: string, value: unknown): Promise<vo
  */
 declare const BASOU_CORE_VERSION = "0.1.0";
 
-export { ACTIVE_GAP_CAP_MS, type ActiveTimeBasis, type AdapterOutputEvent, type AppendBasouGitignoreResult, type AppendEventToExistingInput, type AppendEventToExistingResult, type Approval, type ApprovalApprovedEvent, type ApprovalExpiredEvent, ApprovalIdSchema, type ApprovalLocation, type ApprovalRejectedEvent, type ApprovalRequestedEvent, ApprovalSchema, type ApprovalStatus, ApprovalStatusSchema, type ArchiveTaskInput, type ArchiveTaskResult, type AttachTaskInput, type AttachUpdateTaskStatusInput, type AttachableStatus, BASOU_CORE_VERSION, type BasouPaths, type BulkChainResult, CLAUDE_IMPORT_SOURCE, CODEX_IMPORT_SOURCE, type CaptureMode, type ChainBreakReason, type ChainVerdict, type ChainVerdictStatus, type ChainedEvents, ChildProcessRunner, type ClaudeTranscriptRecord, type ClaudeTranscriptToPayloadOptions, type CodexRolloutRecord, type CodexRolloutToPayloadOptions, type CommandExecutedEvent, type CommandLookup, type CreateAdHocSessionInput, type CreateAdHocSessionResult, type CreateAdHocTaskInput, type CreateManifestInput, type CreateTaskInput, type CreateTaskResult, type DayWorkStats, DecisionIdSchema, type DecisionRecordedEvent, type DecisionsRendererInput, type DecisionsRendererResult, type DeleteTaskInput, type DeleteTaskResult, type DiffResult, type EditTaskInput, type EditTaskResult, type Event, EventIdSchema, EventSchema, EventSourceSchema, FailedToFinalizeError, type FileChange, type FileChangeStatus, type FileChangedEvent, GENERATED_END, GENERATED_START, type GitSnapshot, type GitSnapshotEvent, type HandoffRendererInput, type HandoffRendererResult, ID_PREFIXES, type IdPrefix, type ImportSessionOptions, type ImportSessionResult, IsoTimestampSchema, JSON_SCHEMA_VERSION, type JsonSchemaArtifact, type LoadSessionEntriesOptions, type LoadTaskEntriesOptions, type LoadedApproval, type LockHandle, type LockScope, type Manifest, ManifestSchema, type MarkerSection, type MeasureAvailability, type NoteAddedEvent, type PrefixedId, type ProcessRunner, type RechainOptions, type RechainResult, type ReconcileAllResult, type ReconcileAllTasksInput, type ReconcileAllTasksOptions, type ReconcileFailure, type ReconcileResult, type ReconcileTaskInput, type RefreshLinkageInput, type RefreshLinkageResult, type ReimportOptions, type ReimportResult, type ReplayOptions, type ReplayWarning, type RiskLevel, RiskLevelSchema, type RunOptions, type RunResult, STUCK_THRESHOLD_MS, type SanitizePathOptions, type SanitizeRelatedFilesResult, SchemaVersionSchema, type Session, type SessionEndedEvent, type SessionEntry, SessionIdSchema, type SessionImportPayload, SessionImportPayloadSchema, type SessionInnerImportInput, SessionInnerImportSchema, type SessionIntegrity, SessionIntegritySchema, type SessionMetrics, SessionMetricsSchema, SessionSchema, type SessionSkipReason, type SessionSourceKind, SessionSourceKindSchema, type SessionStartedEvent, type SessionStatus, type SessionStatusChangedEvent, SessionStatusSchema, type SessionWorkStats, type SourceWorkStats, type StatusCount, StatusSchema, type StatusSnapshot, type SuspectReason, type Task, type TaskArchivedEvent, type TaskCreatedEvent, type TaskDeletedEvent, type TaskDocument, TaskIdSchema, type TaskLinkageRefreshedEvent, type TaskReconciledEvent, TaskSchema, type TaskSkipReason, type TaskStatus, type TaskStatusChangedEvent, TaskStatusSchema, TaskWriteAfterEventError, type TaskWriteAfterEventPhase, type TokenTotals, type UpdateAdHocTaskStatusInput, type UpdateTaskStatusInput, type UpdateTaskStatusResult, type WorkStatsInput, type WorkStatsResult, type WorkStatsTotals, WorkspaceIdSchema, type WriteEventsBulkOptions, type WriteTaskFileMode, acquireLock, appendBasouGitignore, appendEvent, appendEventToExistingSession, archiveTask, assertBasouRootSafe, basouPaths, buildJsonSchemas, buildStatusSnapshot, chainEvents, chainRawJsonLines, classifySuspect, claudeCodeAdapterMetadata, claudeTranscriptToImportPayload, codexRolloutToImportPayload, computeWorkStats, createAdHocSessionWithEvent, createManifest, createTaskWithEvent, deleteTask, editTask, ensureBasouDirectory, enumerateApprovals, enumerateArchivedTaskIds, enumerateSessionDirs, enumerateTaskIds, findErrorCode, genesisHash, getDiff, getSnapshot, importSessionFromJson, isImportDerivedSource, isLazyExpired, isValidPrefixedId, lineHash, linkYamlFile, loadApproval, loadSessionEntries, loadTaskEntries, overwriteYamlFile, parseDuration, parseMarkers, prefixedUlid, readAllEvents, readManifest, readMarkdownFile, readSessionYaml, readStatus, readTaskFile, readTaskFileWithArchiveFallback, readYamlFile, rechainSessionInPlace, reconcileAllTasks, reconcileTask, refreshTaskLinkedSessions, reimportPreservingId, renderDecisions, renderHandoff, renderWithMarkers, replayEvents, resolveClaudeCodeCommand, resolveRepositoryRoot, resolveSessionId, resolveTaskId, sanitizePath, sanitizeRelatedFiles, sanitizeWorkingDirectory, serializeEventLine, serializeJsonSchema, sessionWorkStatsFromEvents, summarizeAdapterOutput, tryRemoteUrl, ulid, updateTaskStatusWithEvent, verifyEventsChain, writeEventsBulk, writeManifest, writeMarkdownFile, writeStatus, writeTaskFile, writeYamlFile };
+export { ACTIVE_GAP_CAP_MS, type ActiveTimeBasis, type AdapterOutputEvent, type AppendBasouGitignoreResult, type AppendEventToExistingInput, type AppendEventToExistingResult, type Approval, type ApprovalApprovedEvent, type ApprovalExpiredEvent, ApprovalIdSchema, type ApprovalLocation, type ApprovalRejectedEvent, type ApprovalRequestedEvent, ApprovalSchema, type ApprovalStatus, ApprovalStatusSchema, type ArchiveTaskInput, type ArchiveTaskResult, type AttachTaskInput, type AttachUpdateTaskStatusInput, type AttachableStatus, BASOU_CORE_VERSION, type BasouPaths, type BulkChainResult, CLAUDE_IMPORT_SOURCE, CODEX_IMPORT_SOURCE, type CaptureMode, type ChainBreakReason, type ChainTailState, type ChainVerdict, type ChainVerdictStatus, type ChainedEvents, ChildProcessRunner, type ClaudeTranscriptRecord, type ClaudeTranscriptToPayloadOptions, type CodexRolloutRecord, type CodexRolloutToPayloadOptions, type CommandExecutedEvent, type CommandLookup, type CreateAdHocSessionInput, type CreateAdHocSessionResult, type CreateAdHocTaskInput, type CreateManifestInput, type CreateTaskInput, type CreateTaskResult, type DayWorkStats, DecisionIdSchema, type DecisionRecordedEvent, type DecisionsRendererInput, type DecisionsRendererResult, type DeleteTaskInput, type DeleteTaskResult, type DiffResult, type EditTaskInput, type EditTaskResult, type Event, EventIdSchema, EventSchema, EventSourceSchema, FailedToFinalizeError, type FileChange, type FileChangeStatus, type FileChangedEvent, GENERATED_END, GENERATED_START, type GitSnapshot, type GitSnapshotEvent, type HandoffRendererInput, type HandoffRendererResult, ID_PREFIXES, type IdPrefix, type ImportSessionOptions, type ImportSessionResult, IsoTimestampSchema, JSON_SCHEMA_VERSION, type JsonSchemaArtifact, type LoadSessionEntriesOptions, type LoadTaskEntriesOptions, type LoadedApproval, type LockHandle, type LockScope, type Manifest, ManifestSchema, type MarkerSection, type MeasureAvailability, type NoteAddedEvent, type PrefixedId, type ProcessRunner, type RechainOptions, type RechainResult, type ReconcileAllResult, type ReconcileAllTasksInput, type ReconcileAllTasksOptions, type ReconcileFailure, type ReconcileResult, type ReconcileTaskInput, type RefreshLinkageInput, type RefreshLinkageResult, type ReimportOptions, type ReimportResult, type ReplayOptions, type ReplayWarning, type ReportApprovalItem, type ReportData, type ReportDecisionItem, type ReportRendererInput, type ReportRendererResult, type ReportSessionItem, type ReportTaskItem, type RiskLevel, RiskLevelSchema, type RunOptions, type RunResult, STUCK_THRESHOLD_MS, type SanitizePathOptions, type SanitizeRelatedFilesResult, SchemaVersionSchema, type Session, type SessionEndedEvent, type SessionEntry, SessionIdSchema, type SessionImportPayload, SessionImportPayloadSchema, type SessionInnerImportInput, SessionInnerImportSchema, type SessionIntegrity, SessionIntegritySchema, type SessionMetrics, SessionMetricsSchema, SessionSchema, type SessionSkipReason, type SessionSourceKind, SessionSourceKindSchema, type SessionStartedEvent, type SessionStatus, type SessionStatusChangedEvent, SessionStatusSchema, type SessionWorkStats, type SourceWorkStats, type StatusCount, StatusSchema, type StatusSnapshot, type SuspectReason, type Task, type TaskArchivedEvent, type TaskCreatedEvent, type TaskDeletedEvent, type TaskDocument, TaskIdSchema, type TaskLinkageRefreshedEvent, type TaskReconciledEvent, TaskSchema, type TaskSkipReason, type TaskStatus, type TaskStatusChangedEvent, type TaskStatusCount, TaskStatusSchema, TaskWriteAfterEventError, type TaskWriteAfterEventPhase, type TokenTotals, type UpdateAdHocTaskStatusInput, type UpdateTaskStatusInput, type UpdateTaskStatusResult, type WorkStatsInput, type WorkStatsResult, type WorkStatsTotals, WorkspaceIdSchema, type WriteEventsBulkOptions, type WriteTaskFileMode, acquireLock, appendBasouGitignore, appendChainedEvent, appendChainedEventLocked, appendEvent, appendEventToExistingSession, archiveTask, assertBasouRootSafe, basouPaths, buildJsonSchemas, buildStatusSnapshot, chainEvents, chainRawJsonLines, classifySuspect, claudeCodeAdapterMetadata, claudeTranscriptToImportPayload, codexRolloutToImportPayload, computeWorkStats, createAdHocSessionWithEvent, createManifest, createTaskWithEvent, deleteTask, editTask, ensureBasouDirectory, enumerateApprovals, enumerateArchivedTaskIds, enumerateSessionDirs, enumerateTaskIds, finalizeSessionYaml, findErrorCode, formatDurationMs, genesisHash, getDiff, getSnapshot, importSessionFromJson, inspectChainTail, isImportDerivedSource, isLazyExpired, isValidPrefixedId, lineHash, linkYamlFile, loadApproval, loadSessionEntries, loadTaskEntries, overwriteYamlFile, parseDuration, parseMarkers, prefixedUlid, readAllEvents, readManifest, readMarkdownFile, readSessionYaml, readStatus, readTaskFile, readTaskFileWithArchiveFallback, readYamlFile, rechainSessionInPlace, reconcileAllTasks, reconcileTask, refreshTaskLinkedSessions, reimportPreservingId, renderDecisions, renderHandoff, renderReport, renderWithMarkers, replayEvents, resolveClaudeCodeCommand, resolveRepositoryRoot, resolveSessionId, resolveTaskId, sanitizePath, sanitizeRelatedFiles, sanitizeWorkingDirectory, serializeEventLine, serializeJsonSchema, sessionWorkStatsFromEvents, summarizeAdapterOutput, tryRemoteUrl, ulid, updateTaskStatusWithEvent, verifyEventsChain, writeEventsBulk, writeManifest, writeMarkdownFile, writeStatus, writeTaskFile, writeYamlFile };