@obversa/runtime 0.1.0

package/dist/core/git.d.ts

@@ -0,0 +1,152 @@
+/** Local Git helpers used by workspace-aware jobs. */
+interface GitOpts {
+    cwd: string;
+    signal?: AbortSignal;
+    excludePaths?: string[];
+    includePaths?: string[];
+}
+/** True when `cwd` is inside a git work tree. Never throws. */
+export declare function isRepo(opts: GitOpts): Promise<boolean>;
+/** The checked-out branch name, or undefined on a detached HEAD / non-repo. */
+export declare function currentBranch(opts: GitOpts): Promise<string | undefined>;
+/** The git worktree root containing `cwd`, or undefined outside a git repo. */
+export declare function gitRoot(opts: GitOpts): Promise<string | undefined>;
+/** The HEAD commit sha, or undefined when the branch has no commits yet. */
+export declare function headSha(opts: GitOpts): Promise<string | undefined>;
+/** Stage every change in the work tree (`git add -A`). */
+export declare function stageAll(opts: GitOpts): Promise<void>;
+/** True when there is something staged to commit. */
+export declare function hasStagedChanges(opts: GitOpts): Promise<boolean>;
+/** True when the work tree (staged or unstaged) has any change. */
+export declare function isDirty(opts: GitOpts): Promise<boolean>;
+/**
+ * A content hash of the workspace's observable state: HEAD, every pending
+ * tracked change (staged + unstaged, with content), the porcelain status, and
+ * the CONTENT of untracked files (hashed by git itself, so a revisit to a
+ * byte-identical tree fingerprints identically). Whole-workspace hashes omit
+ * ignored files; `includePaths` observes ignored content explicitly selected
+ * by the caller. Scoped hashes omit unrelated commits. This is the
+ * deterministic evidence channel behind `noProgress`: two iterations with the
+ * same fingerprint left the observed workspace in the same state. Returns
+ * undefined outside a git work tree; the caller treats that channel as
+ * absent, never as "unchanged". Never throws.
+ */
+export declare function workspaceFingerprint(opts: GitOpts): Promise<string | undefined>;
+interface GitIndexState {
+    readonly mode: string;
+    readonly oid: string;
+}
+interface GitDirtyState {
+    readonly status: string;
+    readonly kind: 'file' | 'symlink' | 'missing';
+    readonly mode: number;
+    readonly digest: string | null;
+    readonly lines: readonly string[];
+}
+export interface GitWorkspaceFileState {
+    readonly path: string;
+    readonly index: GitIndexState | null;
+    readonly dirty: GitDirtyState | null;
+}
+export interface GitWorkspaceSnapshot {
+    readonly root: string;
+    readonly head: string | null;
+    readonly files: readonly GitWorkspaceFileState[];
+}
+export interface GitWorkspaceDelta {
+    readonly headChanged: boolean;
+    readonly changedPaths: readonly string[];
+    readonly filesChanged: number;
+    readonly linesChanged: number;
+}
+/**
+ * Capture the Git-visible entry state for one attempt. Clean tracked files are
+ * represented by their index object; only already-dirty bytes are read and
+ * reduced to hashes. No workspace content is retained in the snapshot.
+ */
+export declare function captureGitWorkspaceSnapshot(opts: GitOpts): Promise<GitWorkspaceSnapshot>;
+/** Compare two snapshots without treating untouched entry dirt as attempt work. */
+export declare function compareGitWorkspaceSnapshots(before: GitWorkspaceSnapshot, after: GitWorkspaceSnapshot, signal?: AbortSignal): Promise<GitWorkspaceDelta>;
+export interface CommitInput {
+    subject: string;
+    /** The structured body. Joined to the subject with a blank line. */
+    body?: string;
+    /** Commit even with an empty index (default false). */
+    allowEmpty?: boolean;
+}
+/**
+ * Commit the staged index. The message is passed on stdin (`-F -`) so an
+ * arbitrarily-shaped body never has to survive shell escaping. The repo's
+ * configured author is used. The runtime never changes commit authorship.
+ * Returns the new sha, or undefined when there was nothing to commit and
+ * `allowEmpty` was not set.
+ */
+export declare function commit(input: CommitInput, opts: GitOpts): Promise<string | undefined>;
+/** Recent commit messages from one branch, used only to explain a merge. */
+export declare function branchCommits(opts: {
+    cwd: string;
+    ref: string;
+    max: number;
+    signal?: AbortSignal;
+}): Promise<Array<{
+    subject: string;
+    body: string;
+}>>;
+export interface WorktreeHandle {
+    /** The isolated working directory. */
+    dir: string;
+    /** The branch checked out there. */
+    branch: string;
+}
+/**
+ * Fork an isolated worktree on a new branch from `base` (default HEAD). Each
+ * concurrent writer gets its own working dir and branch, so siblings never
+ * collide on files or the index.
+ */
+export declare function addWorktree(repoDir: string, opts: {
+    branch: string;
+    base?: string;
+    signal?: AbortSignal;
+}): Promise<WorktreeHandle>;
+/** Remove a worktree (force-discards anything uncommitted left in it). */
+export declare function removeWorktree(repoDir: string, dir: string, opts?: {
+    signal?: AbortSignal;
+}): Promise<void>;
+/** Delete a branch ref (used to clean up a merged fork branch). */
+export declare function deleteBranch(repoDir: string, branch: string, opts?: {
+    signal?: AbortSignal;
+}): Promise<void>;
+export interface MergeResult {
+    ok: boolean;
+    conflict: boolean;
+}
+/**
+ * Land a fork branch back into the branch checked out at `repoDir` (`--no-ff`).
+ * On conflict the merge is aborted so the target stays clean and the caller can
+ * fail the node. The runtime does not auto-resolve (a merge-resolver is a separate
+ * layer).
+ */
+export declare function mergeBranch(repoDir: string, branch: string, opts?: {
+    signal?: AbortSignal;
+    message?: string;
+}): Promise<MergeResult>;
+/**
+ * Begin a `--no-ff --no-commit` merge WITHOUT aborting on conflict, so a resolver
+ * can synthesise the result. `clean` means it merged cleanly (staged, ready to
+ * commit); otherwise `conflicted` lists the unresolved paths (with markers).
+ */
+export declare function mergeNoCommit(repoDir: string, branch: string, opts?: {
+    signal?: AbortSignal;
+}): Promise<{
+    clean: boolean;
+    conflicted: string[];
+}>;
+/** Paths with unresolved merge conflicts. */
+export declare function conflictedFiles(repoDir: string, opts?: {
+    signal?: AbortSignal;
+}): Promise<string[]>;
+/** Abort an in-progress merge. */
+export declare function mergeAbort(repoDir: string, opts?: {
+    signal?: AbortSignal;
+}): Promise<void>;
+export {};

package/dist/core/guards.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Hardening gates that keep a convergence loop honest without spending a
+ * model call — deterministic conditions in the supervisor-orchestrator
+ * tradition, adapted to the Obversa runtime:
+ *
+ * - `ratchet`: a measured metric may only hold or improve against a
+ *   runtime-owned baseline that is written **only in the improving
+ *   direction**, so the agent can never loosen its own bar.
+ * - `writeScope`: every pending workspace change introduced since loop entry
+ *   must match a declared glob, so pre-existing dirt cannot wedge a scoped job.
+ * - `sampled`: run an expensive condition on a deterministic bucket of
+ *   iterations (a sha256 cut, so re-runs land on the same side), treating the
+ *   unsampled rest as met — how a costly judge stays affordable on a
+ *   high-iteration loop.
+ */
+import type { Condition, ConditionInput, JobContext } from './types.js';
+export interface RatchetOptions {
+    /** The metric key to read from the command's JSON output. */
+    metric: string;
+    /** Which way is better: `down` (default; the value must not rise — lint
+     *  errors, bundle bytes, TODO count) or `up` (must not fall — coverage). */
+    direction?: 'down' | 'up';
+    /** Where baselines live. Default `<OBVERSA_HOME|~/.obversa>/ratchets` — outside
+     *  the workspace, so the baseline is never edited or committed by the loop
+     *  it constrains. */
+    baselineDir?: string;
+    cwd?: string;
+    timeoutMs?: number;
+    env?: Record<string, string>;
+}
+/**
+ * Deterministic gate over a **measured, monotone** signal. Runs `command`,
+ * reads `metric` from its JSON output (`{"metrics": {"<name>": n}}`, or a
+ * bare object), and is met only when the value holds or improves on the
+ * stored baseline. The baseline is runtime-owned and written only in the
+ * improving direction — the first run seeds it — so the constrained loop can
+ * neither loosen nor forget its own bar. Everything else fails closed: a
+ * command failure, missing metric, or unparsable output is "not met".
+ */
+export declare function ratchet(command: string, args: string[] | undefined, opts: RatchetOptions): Condition;
+/** Minimal glob → RegExp: `**` crosses directories, `*` stays inside one,
+ *  `?` is a single char. Enough for scope declarations without a dependency. */
+export declare function globToRegExp(glob: string): RegExp;
+export interface WriteScopeOptions {
+    cwd?: string;
+    /** Compare pending changes with loop entry, or require the whole tree to fit. */
+    mode?: 'delta' | 'absolute';
+}
+/**
+ * Met only when every staged, unstaged, or untracked change introduced since
+ * the enclosing loop started matches a declared glob. This ignores untouched
+ * pre-existing dirt without hiding a body edit to an already-dirty file. Use
+ * `mode: 'absolute'` when the complete pending state must fit the scope.
+ * Outside a loop, evaluation is absolute. A workspace that is not a git
+ * repository fails closed.
+ */
+export declare function writeScope(globs: string[], opts?: WriteScopeOptions): Condition;
+export interface SampledOptions {
+    /** Stable sampling key; default `<path>:<iteration>`, so a re-run of the
+     *  same iteration lands on the same side of the cut. */
+    key?: string | ((ctx: JobContext) => string);
+}
+/**
+ * Run `condition` on a deterministic fraction of evaluations and treat the
+ * rest as met. The bucket is a sha256 cut of a stable key (not `Math.random`),
+ * so the same iteration always samples the same way — an expensive judge on
+ * `rate: 0.25` really runs every ~4th iteration, reproducibly. Deterministic
+ * gates cost nothing; sample only what spends.
+ */
+export declare function sampled(rate: number, condition: ConditionInput, opts?: SampledOptions): Condition;

package/dist/core/isolated.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `isolated(job)` runs any Job in its own git worktree on a fork branch, and lands
+ * its work back into the parent branch on pass. The concurrency boundary as a Job
+ * wrapper, not a node type.
+ *
+ * dag nodes can already fork a worktree (`isolation: 'worktree'`), but that only
+ * works for predeclared nodes. A Tend loop dispatches dynamically: it discovers each
+ * ticket at runtime and routes it to the right shape of sub-loop, and each dispatch
+ * wants its own isolated worktree so parallel tickets never collide on files or the
+ * index. `isolated()` makes that composable: wrap the dispatched Job.
+ *
+ * On pass: any uncommitted remainder is committed in the worktree, then the fork
+ * branch merges back (`--no-ff`). Land-back merges are serialised across all
+ * `isolated()` jobs in the process, so concurrent dispatch cannot race the parent
+ * index/HEAD. A conflict fails, or is synthesised when asked. The worktree
+ * is always removed; a cleanly-merged fork branch is deleted. A non-repo workspace
+ * degrades to running in place (a warning, no isolation).
+ *
+ * NOTE: dag's own runNodeJob holds parallel worktree/land-back logic (plus per-team
+ * environments). The two should be unified (dag delegating to `isolated()`) once
+ * `isolated()` grows environment support; until then the land-back logic lives in
+ * both deliberately, to avoid destabilising the dag path.
+ */
+import type { Job } from './types.js';
+import type { ReasoningRecorder } from '@obversa/api';
+export interface IsolatedOptions {
+    /** Label for the fork branch and the child path. Default 'isolated'. */
+    label?: string;
+    /** On a land-back conflict: 'fail' (default) or 'synthesize'. */
+    onConflict?: 'fail' | 'synthesize';
+    /**
+     * A record of why this stage's change exists. It watches the stage's own
+     * events and, when the stage passes with something to commit, supplies the
+     * message for the commit that carries the change. A stage that changed
+     * nothing produces no commit, so it is never asked for one.
+     */
+    record?: ReasoningRecorder;
+}
+/** Wrap a Job so it runs in an isolated worktree and lands back on pass. */
+export declare function isolated(job: Job, opts?: IsolatedOptions): Job;

package/dist/core/job.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Job builders. A `Job` is the unit of work; these are the common shapes.
+ * The agent launch (`agentJob`) is deliberately provider-agnostic: it only
+ * ever calls `Engine.run`, so it knows nothing about Claude, the CLI, an SDK,
+ * an HTTP API, or any framework — swap the engine and the same job runs.
+ */
+import type { Outcome, Job, JobContext, ProofArtifact } from './types.js';
+/** Shared state key holding every engine answer the run recorded so far.
+ * Written by the runtime beside each engine:usage event; read by workflow
+ * layers that must compare what answered against what was declared. */
+export declare const RECORDED_ENGINE_USAGE = "obversa:recorded-engine-usage";
+/** One recorded engine answer: the answering model and the job path that
+ * produced it. */
+export interface RecordedEngineUsage {
+    readonly model: string;
+    readonly path: readonly string[];
+    /** The review side this answer belongs to, set by the workflow layer
+     * that built the job. Untagged entries (advisors, agentCheck) belong
+     * to neither side and are outside the recorded-family gate. */
+    readonly role?: 'writer' | 'reviewer';
+    /** The stage name this answer belongs to. */
+    readonly stage?: string;
+}
+import type { AgentRequest, EngineRef } from '../engines/engine.js';
+import { type LoopErrorCode } from './errors.js';
+import { type AgentDef } from './agent.js';
+import { kickback, revisionRequest } from './feedback.js';
+export interface AgentJobConfig {
+    /** Tag this job's engine answers with the review side and stage they
+     * belong to, so a workflow layer can compare recorded sides without
+     * inferring them from paths. Untagged answers are outside such gates. */
+    readonly recordAs?: {
+        readonly role: 'writer' | 'reviewer';
+        readonly stage: string;
+    };
+    /** Job label (for events). Defaults to the agent's name, then `'agent'`. */
+    label?: string;
+    /**
+     * A reusable agent definition — supplies `system` (persona + skills), `model`, and
+     * `tools` (the job's `system` and `model` override it when also set). The
+     * persona lives in markdown via `fromFile`; this is the typed wrapper around it.
+     */
+    agent?: AgentDef;
+    /** The prompt, or a function of the context (e.g. include the iteration). */
+    prompt: string | ((ctx: JobContext) => string | Promise<string>);
+    system?: string | ((ctx: JobContext) => string);
+    /** Engine override: a registered name, your own `Engine`, or the default. */
+    engine?: EngineRef;
+    /** Bare model id — passed straight through to the engine. */
+    model?: string;
+    maxTokens?: number;
+    tools?: string[];
+    allowedTools?: string[];
+    workspaceMode?: AgentRequest['workspaceMode'];
+    /**
+     * Mark this turn a leaf: forbid spawning sub-agents (the engine disallows the sub-agent
+     * tool), so a branch bottoms out here. Falls back to the agent def's `leaf`.
+     */
+    leaf?: boolean;
+    /**
+     * Append the current `ctx.lastReview` / revision feedback to the prompt. This
+     * keeps implementation agents from having to remember to manually read the
+     * runtime feedback channel in every prompt function.
+     */
+    consumeFeedback?: boolean;
+    /**
+     * Append a compact DAG-position block: this node, its direct dependencies, and
+     * its direct dependents, without handing the agent the whole orchestration graph.
+     */
+    graphContext?: boolean;
+    /**
+     * Bounded, visible escalation: the worker may ask for a consult by replying
+     * with a `<consult_advisor>` block. The runtime runs one model-pinned advisor turn,
+     * records the question/reply, and then gives the reply back to the worker in a
+     * fresh turn. This is the sanctioned alternative to shelling out to another
+     * model from inside a leaf.
+     */
+    advisor?: AdvisorConfig;
+    /** Working dir for the turn. Default: the workspace dir (the worktree). */
+    cwd?: string;
+    /**
+     * Env vars pinned for this leaf's engine subprocess — the most specific
+     * layer, over any `withEnv` overlay and the running environment's vars.
+     * Engines that spawn no subprocess ignore it.
+     */
+    env?: Record<string, string>;
+    /**
+     * Soft timeout for each worker or fallback invocation. Advisor consults
+     * inherit it unless overridden; each invocation receives its own window.
+     */
+    timeoutMs?: number;
+    /** Extra hard-timeout window after `timeoutMs` for completed final results. */
+    timeoutGraceMs?: number;
+    /** Fallback route(s) used when the primary engine hits a configured error. */
+    fallback?: AgentRoute | AgentRoute[];
+    /** Error codes that may spill to `fallback`. Default: RATE_LIMIT and QUOTA. */
+    fallbackOn?: LoopErrorCode[];
+    /**
+     * Map the agent's raw text into an `Outcome`. Default: `pass`, with the text
+     * as the summary. Return `fail` to keep an enclosing loop going. `text` is
+     * the reply after the capture scrub (injected env values and secret-shaped
+     * tokens are redacted) before the outcome enters persisted records.
+     */
+    outcome?: (text: string, ctx: JobContext) => Outcome | Promise<Outcome>;
+}
+export interface AdvisorConfig {
+    engine?: EngineRef;
+    model?: string;
+    systemPrompt?: string;
+    maxCalls?: number;
+    maxTokens?: number;
+    timeoutMs?: number;
+    timeoutGraceMs?: number;
+}
+export interface AgentRoute {
+    engine?: EngineRef;
+    model?: string;
+    timeoutMs?: number;
+    timeoutGraceMs?: number;
+}
+export type ProofDescriptor = ProofArtifact;
+export type ProofProducer = (ctx: JobContext) => ProofDescriptor | Promise<ProofDescriptor>;
+/** Run one fresh agent turn through whichever engine is selected. */
+export declare function agentJob(config: AgentJobConfig): Job;
+export { kickback, revisionRequest };
+/** A deterministic step from a plain function — for glue, checks, side effects. */
+/**
+ * What a `fnJob` function may return: a full outcome, a one-line summary (the
+ * step passed, and this is what it did), or nothing (the step passed; its
+ * label is the summary). A throw is a fail carrying the error.
+ */
+export type FnJobResult = Outcome | string | void;
+export declare function fnJob(label: string, fn: (ctx: JobContext) => FnJobResult | Promise<FnJobResult>): Job;
+export declare function prove(name: string, producer: ProofProducer): Job;

package/dist/core/limits.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Provider-limit plumbing shared by the engines and the runner.
+ *
+ * Engines report a provider-neutral `EngineError`. The runtime maps rate-limit
+ * and quota failures to a `LoopError` while preserving `retryAfterMs` and
+ * `resetAt`. The runner reads that hint through `waitMsFor` to decide whether
+ * to wait, pause, or fail (see `onLimit`).
+ *
+ * Keeping the reset-time math in one place means every engine and the policy
+ * agree on what "a known, bounded wait" means.
+ */
+import type { LoopError } from './errors.js';
+export { retryAfterHeaderToMs } from '@obversa/core/command';
+/** True when an error is one the `onLimit` policy governs. */
+export declare function isLimitError(error: LoopError | undefined): error is LoopError;
+/**
+ * The wait a limit error implies, in ms, or `undefined` when no reset is known.
+ * Prefers an explicit `retryAfterMs`; falls back to `resetAt - now` (floored at
+ * 0 so an already-passed reset waits nothing rather than going negative). BUDGET
+ * never refreshes within a run, so it never yields a wait.
+ */
+export declare function waitMsFor(error: LoopError, now?: number): number | undefined;

package/dist/core/loop.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The loop primitive. `loop(config)` returns a `Job`, so loop jobs nest by simply
+ * passing one as another's `body` or `review`.
+ *
+ * Lifecycle of one loop:
+ *   1. `start` gate (one-or-many conditions) — unmet => `aborted`.
+ *   2. repeat, up to `max`:
+ *        run `body` (fresh context each turn) → `stopOn`? → `until`?
+ *        if `until` is met and there's a `review`, run it:
+ *          review `pass`  => loop completes `pass`
+ *          review !pass   => re-enter the loop  ← "review fails, run main loop again"
+ *      with no `until`, a `pass` body ends the loop; `max` reached => `exhausted`.
+ *   3. `onComplete` post-action runs once, whatever the status.
+ *
+ * The review-restart cycle is bounded: by `max` (shared with ordinary
+ * iterations) and, independently, by `maxReviewRestarts`. The failed review is
+ * threaded to the next iteration as `ctx.lastReview` so the body can act on it.
+ *
+ * Every piece of user code (conditions, the body, hooks, the review) is guarded:
+ * a throw is classified and ends the loop with `fail`, but `loop:end` and the
+ * `onComplete` post-action still run.
+ */
+import type { LoopConfig, Job } from './types.js';
+export declare function loop(config: LoopConfig): Job;

package/dist/core/merge.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Merge as synthesis. A raw `git merge` either applies cleanly or fails on conflict.
+ * `mergeSynthesis` instead has an agent resolve each conflicted file coherently
+ * (preserving both intents), and writes a merge commit body that synthesises what the
+ * two branches were each trying to do, not "merge branch X".
+ *
+ * It is text-in/text-out, so it works through any `Engine` (no tool-use needed): the
+ * conflicted file content goes in, the resolved content comes back. One call per
+ * conflicted file plus one for the synthesis body, and nothing when the merge is
+ * already clean. The merge is aborted if resolution throws, so the target is never
+ * left half-merged.
+ */
+import type { JobContext } from './types.js';
+import type { EngineRef } from '../engines/engine.js';
+export declare const mergeLock: import("p-limit").LimitFunction;
+export interface MergeSynthesisConfig {
+    /** The branch to land into the current workspace. */
+    branch: string;
+    /** Conventional subject for the merge commit. */
+    message?: string;
+    engine?: EngineRef;
+    model?: string;
+}
+export interface MergeSynthesisResult {
+    ok: boolean;
+    /** Whether a conflict had to be resolved. */
+    conflict: boolean;
+    sha?: string;
+}
+export declare function mergeSynthesis(ctx: JobContext, config: MergeSynthesisConfig): Promise<MergeSynthesisResult>;

package/dist/core/pipeline.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `pipeline(name, stages)` is declarative ordered stages as sugar over `dag()`: the
+ * Job graph is the pipeline. Each stage becomes a dag node that `needs` the stage
+ * before it; an explicit `needs` replaces that default, so fan-out/fan-in is still
+ * just edges. All dag semantics apply unchanged: a skipped stage (unmet `when`) counts
+ * green so the chain continues, and an optional stage's failure neither fails the
+ * pipeline nor blocks the next stage (its consumers must tolerate its artifacts being
+ * absent).
+ */
+import type { ConditionInput, DagConfig, Job, JobMeta } from './types.js';
+export interface PipelineStage {
+    name: string;
+    job: Job;
+    /** Gate (one or many): when unmet the stage is skipped, not failed. */
+    when?: ConditionInput;
+    /** A failure here does not fail the pipeline, and does not block later stages. */
+    optional?: boolean;
+    /**
+     * Explicit dependencies, replacing the default `[previous stage]` entirely
+     * (`[]` detaches the stage). This is how a linear pipeline grows fan-out
+     * (two stages needing the same producer) and fan-in (one stage needing both).
+     */
+    needs?: string[];
+    /** Per-stage isolation override (dag's per-node `isolate`). */
+    isolate?: boolean;
+    /** Kickback allowlist for this stage (dag's per-node `acceptsKickbackTo`). */
+    acceptsKickbackTo?: string[];
+}
+/** Ordered named stages, auto-chained: stage i needs stage i-1. Sugar over `dag`. */
+export declare function pipeline(name: string, stages: PipelineStage[], opts?: Omit<DagConfig, 'name' | 'nodes'>): Job;
+/**
+ * Render a `kind:'dag'` job's stages as a GitHub-markdown table (one row per
+ * node, in the meta's node order). Accepts the `Job` itself or its `JobMeta`.
+ */
+export declare function renderPipelineTable(source: Job | JobMeta): string;

package/dist/core/process.d.ts

@@ -0,0 +1,11 @@
+import { type RunChildOptions, type RunChildResult } from '@obversa/core';
+export declare const DEFAULT_PROCESS_TIMEOUT_MS: number;
+export declare const DEFAULT_PROCESS_GRACE_MS: number;
+export declare const DEFAULT_PROCESS_OUTPUT_BYTES: number;
+export type RuntimeProcessOptions = Omit<RunChildOptions, 'timeoutMs' | 'killGraceMs' | 'maxOutputBytes' | 'hooks'> & {
+    readonly timeoutMs?: number;
+    readonly killGraceMs?: number;
+    readonly maxOutputBytes?: number;
+};
+export declare function runRuntimeProcess(options: RuntimeProcessOptions): Promise<RunChildResult>;
+export declare function processText(output: Uint8Array): string;

package/dist/core/progress.d.ts

@@ -0,0 +1,82 @@
+/**
+ * No-progress (stall) detection: the third hard stop, alongside `max` and
+ * `budget`. `max` bounds how many attempts a loop gets and `budget` bounds what
+ * they cost; neither can tell slow-but-real convergence from the same failure
+ * repeating. This module detects the latter, so a stalled loop exits at
+ * iteration N+window instead of running to its cap.
+ *
+ * The decision rule is NOVELTY, not change. An iteration makes progress when it
+ * reaches a state this run has never seen:
+ *
+ *   - the workspace fingerprint (HEAD + pending diff + untracked content) is new
+ *     — so an agent oscillating A→B→A gets no credit for the return trip;
+ *   - a caller-supplied `signal` value is new — the escape hatch for loop jobs whose
+ *     progress lives outside the worktree (a queue length, a passing-test count);
+ *   - the gate confidence beats its previous best by `minConfidenceDelta` — a
+ *     high-water mark, so judge jitter around a flat score is not progress but
+ *     slow, steady improvement accumulates until it clears the bar;
+ *   - (opt-in, `gate: true`) the failing until-gate's diagnostic OUTPUT is new
+ *     — the same failure signature repeating is stall evidence, for
+ *     deterministic gates whose output is stable across identical failures.
+ *
+ * `window` consecutive iterations with evidence and no novelty = stalled. The
+ * default is deliberately conservative (any channel's novelty counts): a false
+ * "stalled" on work that was actually converging is worse than one more
+ * iteration. An iteration with NO evidence channel at all (no git workspace, no
+ * confidence, no signal) is indeterminate — it neither extends nor resets the
+ * stall run, and the detector reports itself inert so the loop can warn once.
+ * Gate/review reasons are deliberately NOT compared: judge prose varies between
+ * identical verdicts, so it is quoted in the report but never used as evidence.
+ */
+import type { NoProgressConfig, NoProgressInput, StallReport } from './types.js';
+export type { NoProgressConfig, NoProgressInput, StallReport } from './types.js';
+/** One completed, non-converged iteration as the tracker sees it. */
+export interface ProgressSample {
+    iteration: number;
+    /** Workspace fingerprint, when the workspace is a git repo. */
+    fingerprint?: string;
+    /** The confidence that gated this turn (review ?? until ?? body). */
+    confidence?: number;
+    /** The custom signal value, when a `signal` fn is configured. */
+    signal?: string;
+    /** The failing gate's diagnostic OUTPUT — never the prose reason. */
+    gate?: string;
+    /** The gate/review reason — reporting only, never evidence. */
+    reason?: string;
+}
+/** Resolve the `noProgress` sugar (`3` ⇒ `{ window: 3 }`) with defaults applied. */
+export declare function resolveNoProgress(input: NoProgressInput | undefined): (Required<Pick<NoProgressConfig, 'window' | 'minConfidenceDelta' | 'gate'>> & NoProgressConfig) | undefined;
+/**
+ * The novelty tracker behind `LoopConfig.noProgress`. Feed it one sample per
+ * non-converged iteration; it returns a `StallReport` the moment `window`
+ * consecutive samples show evidence and no novelty.
+ */
+export declare class ProgressTracker {
+    readonly window: number;
+    readonly minConfidenceDelta: number;
+    /** Every state this run has reached, namespaced by channel. */
+    private readonly seen;
+    /** Confidence high-water mark — the best score at the last progress point. */
+    private best;
+    /** The current run of consecutive no-progress iterations. */
+    private stalledRun;
+    private lastEvidence;
+    private lastReason;
+    private indeterminate;
+    private sampled;
+    constructor(cfg: {
+        window: number;
+        minConfidenceDelta: number;
+    });
+    /**
+     * Record one iteration. Returns a `StallReport` when this sample fills the
+     * window, else undefined.
+     */
+    record(sample: ProgressSample): StallReport | undefined;
+    /**
+     * True when the detector has seen a full window of samples and none carried
+     * any evidence channel — detection is configured but cannot fire. The loop
+     * uses this to warn once instead of failing silently-inert.
+     */
+    isInert(): boolean;
+}

package/dist/core/redact.d.ts

@@ -0,0 +1 @@
+export { redactEnvValues, redactSecrets, scrubCapture, } from '@obversa/core/command';