@gr8ful/spf 0.1.0

package/dist/core/permissions.d.ts

@@ -0,0 +1,78 @@
+/**
+ * What an agent may CHANGE, enforced in code after the fact.
+ *
+ * `tools:` is a capability list, not a sandbox, and two holes make it
+ * unenforceable on its own:
+ *
+ *   * `bash` runs anything. A builder handed bash to run a test suite can also
+ *     run `git checkout adws/` — which is not hypothetical: one did, discarding
+ *     uncommitted changes to the very quality check it was about to be judged by.
+ *   * `write` reaches any path, not just the one report file an agent was given
+ *     it for. A reviewer configured with "no edit, so it cannot quietly fix"
+ *     could still rewrite the code it was reviewing.
+ *
+ * So permission is verified the way every other claim in this system is —
+ * after the fact, against the repo itself. `snapshot()` fingerprints the working
+ * tree's change-set before an agent runs; `enforce()` compares it afterwards and
+ * fails the phase if the agent touched anything outside its allowlist.
+ *
+ * Comparing change-sets, rather than watching for writes, is what catches the
+ * `git checkout` case: a path that was modified before the agent ran and is clean
+ * afterwards has been reverted, and a reversion is a modification. Appearing,
+ * disappearing, and changing all count.
+ *
+ * A breach is NOT a gate violation. Gates are for work an agent can be asked to
+ * redo; a breach cannot be corrected by re-prompting, because the write already
+ * happened. It aborts the phase and names every offending path.
+ *
+ * Two keys drive it, both in spf.config.yaml:
+ *     defaults.protected_files   paths no agent may touch unless it names them itself
+ *     agents[].writes      undefined = unrestricted · [] = read-only · [...] = only these
+ */
+import type { AgentConfig, SFConfig } from "./data_types.ts";
+export declare class PermissionBreach extends Error {
+}
+interface RunLike {
+    repo_root: string;
+    cfg: SFConfig;
+}
+/**
+ * Fingerprint every path the working tree currently differs on.
+ *
+ * Tracked files carry their numstat counts, so an edit to an already-dirty
+ * file still registers as a change. Untracked files are listed by name.
+ * Gitignored paths never appear, which is why the session runtime under
+ * `data_dir` — where handoff files legitimately land — needs no special case.
+ */
+export declare function snapshot(run: RunLike): Record<string, string>;
+/** Every path whose state differs — appeared, vanished, or was rewritten. */
+export declare function changedPaths(before: Record<string, string>, after: Record<string, string>): string[];
+/**
+ * The session runtime, which EVERY agent must be able to write.
+ *
+ * `context_handoff/` is the one place agents hand work to each other, and an
+ * agent's own prompts, raw_output.jsonl, and envelope.json land beside it.
+ * Scout writes its findings there, the reviewer its review, the planner its
+ * plan — a read-only agent is read-only with respect to the REPO, never with
+ * respect to its own report.
+ *
+ * This is granted from `data_dir` rather than left to .gitignore. The runtime
+ * is normally ignored, so it never even appears in a snapshot — but an agent's
+ * ability to record its work must not hang on a gitignore entry that someone
+ * can delete or that a changed `data_dir` can outgrow.
+ */
+export declare function alwaysWritable(cfg: SFConfig): string[];
+/** Session runtime first, then the agent's own list, then what is protected. */
+export declare function permitted(p: string, agent: AgentConfig, cfg: SFConfig): boolean;
+/**
+ * Compare the tree against `before`; undo and raise if the agent overstepped.
+ *
+ * Returns the paths it legitimately changed, so the trace records what an
+ * agent actually touched rather than only what it claimed in its envelope.
+ *
+ * Detection alone would leave the repo holding the unauthorized change while
+ * reporting a failure, so anything the agent introduced outside its allowlist
+ * is rolled back before the phase dies. What it cannot undo, it names.
+ */
+export declare function enforce(run: RunLike, _phase: unknown, agent: AgentConfig, before: Record<string, string>): string[];
+export {};

package/dist/core/permissions.js

@@ -0,0 +1,187 @@
+/**
+ * What an agent may CHANGE, enforced in code after the fact.
+ *
+ * `tools:` is a capability list, not a sandbox, and two holes make it
+ * unenforceable on its own:
+ *
+ *   * `bash` runs anything. A builder handed bash to run a test suite can also
+ *     run `git checkout adws/` — which is not hypothetical: one did, discarding
+ *     uncommitted changes to the very quality check it was about to be judged by.
+ *   * `write` reaches any path, not just the one report file an agent was given
+ *     it for. A reviewer configured with "no edit, so it cannot quietly fix"
+ *     could still rewrite the code it was reviewing.
+ *
+ * So permission is verified the way every other claim in this system is —
+ * after the fact, against the repo itself. `snapshot()` fingerprints the working
+ * tree's change-set before an agent runs; `enforce()` compares it afterwards and
+ * fails the phase if the agent touched anything outside its allowlist.
+ *
+ * Comparing change-sets, rather than watching for writes, is what catches the
+ * `git checkout` case: a path that was modified before the agent ran and is clean
+ * afterwards has been reverted, and a reversion is a modification. Appearing,
+ * disappearing, and changing all count.
+ *
+ * A breach is NOT a gate violation. Gates are for work an agent can be asked to
+ * redo; a breach cannot be corrected by re-prompting, because the write already
+ * happened. It aborts the phase and names every offending path.
+ *
+ * Two keys drive it, both in spf.config.yaml:
+ *     defaults.protected_files   paths no agent may touch unless it names them itself
+ *     agents[].writes      undefined = unrestricted · [] = read-only · [...] = only these
+ */
+import { spawnSync } from "node:child_process";
+import { unlinkSync } from "node:fs";
+import path from "node:path";
+export class PermissionBreach extends Error {
+}
+function git(args, cwd) {
+    const result = spawnSync("git", args, { cwd, encoding: "utf-8" });
+    return result.status === 0 ? result.stdout : "";
+}
+/**
+ * Fingerprint every path the working tree currently differs on.
+ *
+ * Tracked files carry their numstat counts, so an edit to an already-dirty
+ * file still registers as a change. Untracked files are listed by name.
+ * Gitignored paths never appear, which is why the session runtime under
+ * `data_dir` — where handoff files legitimately land — needs no special case.
+ */
+export function snapshot(run) {
+    const fingerprints = {};
+    for (const line of git(["diff", "HEAD", "--numstat"], run.repo_root).split("\n")) {
+        const fields = line.split("\t");
+        if (fields.length >= 3) {
+            const p = fields[fields.length - 1].trim();
+            fingerprints[p] = `${fields[0]},${fields[1]}`;
+        }
+    }
+    for (const p of git(["ls-files", "--others", "--exclude-standard"], run.repo_root).split("\n")) {
+        if (p.trim())
+            fingerprints[p.trim()] = "untracked";
+    }
+    return fingerprints;
+}
+/** Every path whose state differs — appeared, vanished, or was rewritten. */
+export function changedPaths(before, after) {
+    const all = new Set([...Object.keys(before), ...Object.keys(after)]);
+    return [...all].filter((p) => before[p] !== after[p]).sort();
+}
+/**
+ * Translate a pattern, with `*` stopping at a path separator.
+ *
+ * A naive glob-to-regex would let `*` cross `/`, which quietly widens every
+ * pattern: `adws/adw_*.ts` would match `adws/adw_data/sessions/x/y.ts` as well
+ * as the ADW scripts it means. `**` is the way to say "cross directories".
+ */
+function globToRegex(pattern) {
+    let out = "";
+    let i = 0;
+    while (i < pattern.length) {
+        const char = pattern[i];
+        if (pattern.startsWith("**", i)) {
+            out += ".*";
+            i += 2;
+        }
+        else if (char === "*") {
+            out += "[^/]*";
+            i += 1;
+        }
+        else if (char === "?") {
+            out += "[^/]";
+            i += 1;
+        }
+        else {
+            out += char.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+            i += 1;
+        }
+    }
+    return new RegExp(`^${out}$`);
+}
+function matches(p, pattern) {
+    if (pattern.endsWith("/"))
+        return p.startsWith(pattern); // directory prefix
+    if (pattern.includes("*") || pattern.includes("?"))
+        return globToRegex(pattern).test(p);
+    return p === pattern;
+}
+/**
+ * The session runtime, which EVERY agent must be able to write.
+ *
+ * `context_handoff/` is the one place agents hand work to each other, and an
+ * agent's own prompts, raw_output.jsonl, and envelope.json land beside it.
+ * Scout writes its findings there, the reviewer its review, the planner its
+ * plan — a read-only agent is read-only with respect to the REPO, never with
+ * respect to its own report.
+ *
+ * This is granted from `data_dir` rather than left to .gitignore. The runtime
+ * is normally ignored, so it never even appears in a snapshot — but an agent's
+ * ability to record its work must not hang on a gitignore entry that someone
+ * can delete or that a changed `data_dir` can outgrow.
+ */
+export function alwaysWritable(cfg) {
+    return [cfg.defaults.data_dir.replace(/\/+$/, "") + "/"];
+}
+/** Session runtime first, then the agent's own list, then what is protected. */
+export function permitted(p, agent, cfg) {
+    if (alwaysWritable(cfg).some((pattern) => matches(p, pattern)))
+        return true;
+    if ((agent.writes || []).some((pattern) => matches(p, pattern)))
+        return true; // naming a path is what unlocks a protected one
+    if (cfg.defaults.protected_files.some((pattern) => matches(p, pattern)))
+        return false;
+    return agent.writes === undefined || agent.writes === null; // unrestricted = undefined/null, [] = no repo writes
+}
+/**
+ * Undo one unauthorized change. Returns a word describing what happened.
+ *
+ * Only changes the agent INTRODUCED are undone. A path that was already dirty
+ * when the agent started is left exactly as it is: the operator had
+ * uncommitted work there, and discarding it to tidy up would be the same harm
+ * this module exists to prevent, committed by the cleanup instead of the agent.
+ */
+function rollBack(run, p, before, after) {
+    if (p in before) {
+        // Already dirty beforehand. If it is gone from the diff now, the agent
+        // reverted an engineer's uncommitted work and the content is not ours
+        // to reconstruct — say so loudly rather than pretend it was handled.
+        return !(p in after)
+            ? "REVERTED-BY-AGENT (uncommitted work lost, cannot restore)"
+            : "left as-is (was already modified)";
+    }
+    if (after[p] === "untracked") {
+        try {
+            unlinkSync(path.join(run.repo_root, p));
+            return "deleted";
+        }
+        catch (error) {
+            return `could not delete (${error.message})`;
+        }
+    }
+    const result = spawnSync("git", ["checkout", "--", p], { cwd: run.repo_root, encoding: "utf-8" });
+    return result.status === 0 ? "rolled back" : "could not roll back";
+}
+/**
+ * Compare the tree against `before`; undo and raise if the agent overstepped.
+ *
+ * Returns the paths it legitimately changed, so the trace records what an
+ * agent actually touched rather than only what it claimed in its envelope.
+ *
+ * Detection alone would leave the repo holding the unauthorized change while
+ * reporting a failure, so anything the agent introduced outside its allowlist
+ * is rolled back before the phase dies. What it cannot undo, it names.
+ */
+export function enforce(run, _phase, agent, before) {
+    const after = snapshot(run);
+    const touched = changedPaths(before, after);
+    const breaches = touched.filter((p) => !permitted(p, agent, run.cfg));
+    if (breaches.length === 0)
+        return touched;
+    const outcomes = new Map(breaches.map((p) => [p, rollBack(run, p, before, after)]));
+    const scope = agent.writes && agent.writes.length === 0
+        ? "read-only"
+        : agent.writes
+            ? `limited to ${JSON.stringify(agent.writes)}`
+            : `barred from ${JSON.stringify(run.cfg.defaults.protected_files)}`;
+    const detail = [...outcomes.entries()].map(([p, outcome]) => `  - ${p} — ${outcome}`).join("\n");
+    throw new PermissionBreach(`${agent.name} is ${scope} but modified ${breaches.length} path(s):\n${detail}`);
+}

package/dist/core/prompts.d.ts

@@ -0,0 +1,4 @@
+/** Prompt rendering: load system/user refs from config, replace {{placeholders}}. */
+export declare function render(templatePath: string, variables: Record<string, string>): string;
+/** Save the exact prompt sent, before execution — the audit copy. */
+export declare function save(directory: string, name: string, content: string): string;

package/dist/core/prompts.js

@@ -0,0 +1,17 @@
+/** Prompt rendering: load system/user refs from config, replace {{placeholders}}. */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+export function render(templatePath, variables) {
+    let text = readFileSync(templatePath, "utf-8");
+    for (const [key, value] of Object.entries(variables)) {
+        text = text.split(`{{${key}}}`).join(value);
+    }
+    return text;
+}
+/** Save the exact prompt sent, before execution — the audit copy. */
+export function save(directory, name, content) {
+    mkdirSync(directory, { recursive: true });
+    const filePath = path.join(directory, name);
+    writeFileSync(filePath, content);
+    return filePath;
+}

package/dist/core/quality.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Deterministic lint, typecheck, build, and test blocks — configured, not
+ * hardcoded. A known command is not a judgement call. Anything whose
+ * invocation you can write down belongs here as code — it runs in
+ * milliseconds, costs nothing, and returns the same answer every time.
+ * Agents are for the parts that need reading and deciding.
+ *
+ * `quality.checks`/`quality.suites` in spf.config.yaml name the commands and
+ * group them into what a chain actually runs. There is no packaged default
+ * suite — an unconfigured suite fails at agents.validate() time, before
+ * anything spawns, rather than silently reporting green the way a
+ * placeholder echo command used to.
+ */
+import type { EventRecord, Phase, QualityCheckSpec, QualityConfig, QualityResult, VerifyOutputT } from "./data_types.ts";
+export declare class QualityNotConfigured extends Error {
+}
+interface RunLike {
+    cfg: {
+        quality: QualityConfig;
+    };
+    phases: Phase[];
+    context_handoff_dir: string;
+    repo_root: string;
+    console: {
+        note: (message: string) => void;
+    };
+    tracer: {
+        event: (record: EventRecord) => string;
+    };
+    adw_id: string;
+}
+/** Every suite name declared anywhere in `quality.suites`, checked names included. */
+export declare function resolveSuite(run: RunLike, suiteName: string): QualityCheckSpec[];
+/**
+ * Run every check in a configured suite and collect ALL failures — one pass
+ * tells you everything.
+ *
+ * Ordering contract for the caller: a failing check does NOT fail the phase.
+ * The runner did its job; the CODE is what failed. Hand this result to the
+ * builder and let the bounded repair loop decide the run's fate. Throws
+ * QualityNotConfigured (via resolveSuite) if the suite or any of its checks
+ * isn't in the config — before any check runs, let alone any agent spawns.
+ */
+export declare function runSuite(run: RunLike, suiteName: string): QualityResult;
+/**
+ * The `test` suite alone — the deterministic test phase most chains use.
+ *
+ * This is what replaces a `tester` agent once the command is written down. An
+ * agent rediscovering the runner on every run costs a fortune to learn what a
+ * subprocess already knows; the repair loop is unchanged, because a failure
+ * still reaches the builder through `asEnvelope` below.
+ */
+export declare function runTests(run: RunLike): QualityResult;
+/** Every configured check, across every configured suite's union — the `all` suite. */
+export declare function runQuality(run: RunLike): QualityResult;
+/**
+ * Wrap a deterministic result so an agent can be handed it directly.
+ *
+ * Agents hand each other typed envelopes; code blocks return QualityResult.
+ * This is the adapter, so a failing lint or test run flows back into the
+ * builder through exactly the same door an agent's report would — the ADW
+ * script is the only thing that knows the difference.
+ */
+export declare function asEnvelope(result: QualityResult, what: string): VerifyOutputT;
+export {};

package/dist/core/quality.js

@@ -0,0 +1,194 @@
+/**
+ * Deterministic lint, typecheck, build, and test blocks — configured, not
+ * hardcoded. A known command is not a judgement call. Anything whose
+ * invocation you can write down belongs here as code — it runs in
+ * milliseconds, costs nothing, and returns the same answer every time.
+ * Agents are for the parts that need reading and deciding.
+ *
+ * `quality.checks`/`quality.suites` in spf.config.yaml name the commands and
+ * group them into what a chain actually runs. There is no packaged default
+ * suite — an unconfigured suite fails at agents.validate() time, before
+ * anything spawns, rather than silently reporting green the way a
+ * placeholder echo command used to.
+ */
+import { spawnSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import * as v from "valibot";
+import { VerifyOutput, makeEventRecord } from "./data_types.js";
+import { nowIso, operatorEnv } from "./utils.js";
+// How much of a failing command's output rides back inside the envelope. Enough
+// for a builder to act on without opening the artifact; bounded so a runaway
+// stack trace can't swamp the next agent's context.
+const TAIL_CHARS = 4_000;
+export class QualityNotConfigured extends Error {
+}
+/** Every suite name declared anywhere in `quality.suites`, checked names included. */
+export function resolveSuite(run, suiteName) {
+    const names = run.cfg.quality.suites[suiteName];
+    if (!names || names.length === 0) {
+        const known = Object.keys(run.cfg.quality.suites);
+        throw new QualityNotConfigured(`quality.suites.${suiteName} is not configured — add it to spf.config.yaml` +
+            (known.length > 0 ? ` (configured suites: ${known.join(", ")})` : " (no suites are configured yet)"));
+    }
+    const specs = [];
+    const missing = [];
+    for (const name of names) {
+        const spec = run.cfg.quality.checks.find((c) => c.name === name);
+        if (spec)
+            specs.push(spec);
+        else
+            missing.push(name);
+    }
+    if (missing.length > 0) {
+        throw new QualityNotConfigured(`quality.suites.${suiteName} names check(s) not in quality.checks: ${missing.join(", ")}`);
+    }
+    return specs;
+}
+function checkDir(run, name) {
+    const seq = run.phases.length > 0 ? run.phases[run.phases.length - 1].seq : 0;
+    const dirPath = path.join(run.context_handoff_dir, "quality", `${String(seq).padStart(2, "0")}_${name}`);
+    mkdirSync(dirPath, { recursive: true });
+    return dirPath;
+}
+function shellJoin(argv) {
+    return argv
+        .map((arg) => (/[\s"'$`\\!*?[\](){}<>|&;#~]/.test(arg) ? `'${arg.replace(/'/g, `'\\''`)}'` : arg))
+        .join(" ");
+}
+function runCheck(spec, run) {
+    const phase = run.phases[run.phases.length - 1];
+    const outputDir = checkDir(run, spec.name);
+    const outputArtifact = path.join(outputDir, "command.log");
+    const command = shellJoin(spec.argv);
+    const env = operatorEnv(); // the engineer's own shell environment
+    run.console.note(`quality ${spec.name}: ${command}`);
+    const startedAt = nowIso();
+    const clock = performance.now();
+    let stdout = "";
+    let stderr = "";
+    let returncode;
+    try {
+        const completed = spawnSync(spec.argv[0], spec.argv.slice(1), {
+            cwd: run.repo_root,
+            env,
+            encoding: "utf-8",
+            timeout: spec.timeout_seconds * 1000,
+        });
+        if (completed.error && completed.error.code === "ENOENT") {
+            // A missing binary lands here as exit 127 with the real message — no
+            // pre-flight probe needed, and none wanted.
+            returncode = 127;
+            stderr = completed.error.message;
+        }
+        else if (completed.signal === "SIGTERM" && completed.status === null) {
+            returncode = 124;
+            stdout = completed.stdout || "";
+            stderr = (completed.stderr || "") + `\nTimed out after ${spec.timeout_seconds}s.`;
+        }
+        else {
+            returncode = completed.status ?? 1;
+            stdout = completed.stdout || "";
+            stderr = completed.stderr || "";
+        }
+    }
+    catch (error) {
+        returncode = 127;
+        stderr = error.message;
+    }
+    const duration = (performance.now() - clock) / 1000;
+    writeFileSync(outputArtifact, `$ ${command}\nexit: ${returncode}\nduration_seconds: ${duration.toFixed(3)}\n` +
+        `\n--- stdout ---\n${stdout}\n--- stderr ---\n${stderr}\n`);
+    const passed = returncode === 0;
+    run.tracer.event(makeEventRecord({
+        adw_id: run.adw_id,
+        phase_id: phase.phase_id,
+        type: "tool_call",
+        name: `quality:${spec.name}`,
+        payload: {
+            area: spec.area,
+            operation: spec.operation,
+            command,
+            returncode,
+            passed,
+            output_artifact: outputArtifact,
+        },
+        started_at: startedAt,
+        ended_at: nowIso(),
+    }));
+    run.console.note(`quality ${spec.name}: ${passed ? "passed" : "failed"} (exit ${returncode}, ${duration.toFixed(1)}s)`);
+    return {
+        name: spec.name,
+        area: spec.area,
+        operation: spec.operation,
+        command,
+        returncode,
+        passed,
+        duration_seconds: duration,
+        output_artifact: outputArtifact,
+        output_tail: (stdout + stderr).slice(-TAIL_CHARS),
+    };
+}
+/**
+ * Run every check in a configured suite and collect ALL failures — one pass
+ * tells you everything.
+ *
+ * Ordering contract for the caller: a failing check does NOT fail the phase.
+ * The runner did its job; the CODE is what failed. Hand this result to the
+ * builder and let the bounded repair loop decide the run's fate. Throws
+ * QualityNotConfigured (via resolveSuite) if the suite or any of its checks
+ * isn't in the config — before any check runs, let alone any agent spawns.
+ */
+export function runSuite(run, suiteName) {
+    const specs = resolveSuite(run, suiteName);
+    const checks = specs.map((spec) => runCheck(spec, run));
+    // A failure is the command, its exit code, and what it actually printed —
+    // everything a builder needs to repair without opening a log or being told
+    // what the error "means" by a parser that guessed.
+    const failures = checks
+        .filter((check) => !check.passed)
+        .map((check) => `${check.name}: \`${check.command}\` exited ${check.returncode}\n${check.output_tail}`.trimEnd());
+    return {
+        passed: failures.length === 0,
+        checks,
+        failures,
+        artifacts: checks.map((check) => check.output_artifact),
+    };
+}
+/**
+ * The `test` suite alone — the deterministic test phase most chains use.
+ *
+ * This is what replaces a `tester` agent once the command is written down. An
+ * agent rediscovering the runner on every run costs a fortune to learn what a
+ * subprocess already knows; the repair loop is unchanged, because a failure
+ * still reaches the builder through `asEnvelope` below.
+ */
+export function runTests(run) {
+    return runSuite(run, "test");
+}
+/** Every configured check, across every configured suite's union — the `all` suite. */
+export function runQuality(run) {
+    return runSuite(run, "all");
+}
+/**
+ * Wrap a deterministic result so an agent can be handed it directly.
+ *
+ * Agents hand each other typed envelopes; code blocks return QualityResult.
+ * This is the adapter, so a failing lint or test run flows back into the
+ * builder through exactly the same door an agent's report would — the ADW
+ * script is the only thing that knows the difference.
+ */
+export function asEnvelope(result, what) {
+    return v.parse(VerifyOutput.schema, {
+        status: result.passed ? "success" : "fail",
+        summary: result.passed
+            ? `${what}: all ${result.checks.length} check(s) passed`
+            : `${what}: ${result.failures.length} of ${result.checks.length} check(s) failed`,
+        artifacts: result.artifacts,
+        notes_for_next_agent: result.passed
+            ? ""
+            : "Fix every failure below. The output is verbatim from the command — trust it over any summary.",
+        passed: result.passed,
+        failures: result.failures,
+    });
+}

package/dist/core/runner.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The Run object: config + adw_id + agent_map + tracer + console, bound once.
+ *
+ * `run.phase(params, fn)` is the ONE phase primitive — an async scope for all
+ * three kinds (engineer, agent, code), replacing Python's `with run.phase(...)
+ * as ph:` context manager (JS has no direct equivalent, so the callback form
+ * is the idiomatic stand-in). Success must be earned: every phase defaults to
+ * fail; only a clean exit flips it (agent phases additionally require a
+ * parsed envelope + green gates, enforced inside ph.call).
+ */
+import { type GitHandle } from "./git_helper.ts";
+import { Console } from "./console.ts";
+import { Tracer } from "./tracer.ts";
+import { type AgentCall, type EnvelopeBase, type Phase, type PhaseParams, type SFConfig } from "./data_types.ts";
+interface AgentMapEntry {
+    session_id: string;
+    model: string;
+    coding_agent: string;
+}
+export interface PhaseHandle {
+    log(payload: Record<string, unknown>): void;
+    call<T extends EnvelopeBase>(call: AgentCall<T>): Promise<T>;
+}
+export interface RunInit {
+    cfg: SFConfig;
+    adwId: string;
+    tracer: Tracer;
+    engineer: string;
+    /** Absolute. Resolved once, upstream, by paths.resolveAnchor(). */
+    repoRoot: string;
+    /** From the same paths.resolveAnchor() call as repoRoot — for prompts.resolveRef(). */
+    sfDir: string | null;
+    /** Absolute. Resolved once, upstream, by paths.resolveDataPaths(). */
+    dataDir: string;
+}
+export declare class Run {
+    cfg: SFConfig;
+    adw_id: string;
+    tracer: Tracer;
+    console: Console;
+    engineer: string;
+    phases: Phase[];
+    tokens: number;
+    cost: number;
+    repo_root: string;
+    /** Every git operation for this run, bound to repo_root. Never call git_helper directly. */
+    git: GitHandle;
+    /** From the same anchor as repo_root — null if no .spf/ dir exists. */
+    spf_dir: string | null;
+    /** Absolute. Sibling of it: flue.db (Flue's own conversation store), sessions/. */
+    data_dir: string;
+    session_dir: string;
+    context_handoff_dir: string;
+    agent_map: Record<string, AgentMapEntry>;
+    private seq;
+    private agentMapPath;
+    constructor(init: RunInit);
+    saveAgentMap(agent: string, entry: AgentMapEntry): void;
+    addUsage(tokens: number, cost: number): void;
+    phase<T>(params: PhaseParams, fn: (ph: PhaseHandle) => Promise<T>): Promise<T>;
+    /**
+     * Finalize the run and return its exit code. Call this exactly once.
+     *
+     * Two criteria, not one. Every phase must have passed, AND the ADW's own
+     * acceptance test must hold. They are different questions on purpose: a
+     * test phase that ran a red suite succeeded at its job. Pass `accepted=`
+     * so the exit code, the session status, and the banner are decided
+     * together and cannot disagree.
+     */
+    finish(accepted?: boolean, reason?: string): number;
+}
+export {};