@jitsusama/agentic-harness.core 0.1.0

package/dist/review/ask/run.js

@@ -0,0 +1,340 @@
+/**
+ * What was asked of whom, and what came back.
+ *
+ * A run is a record rather than a working state: it says who was
+ * asked, in which pass, and what each of them came back with. A
+ * finding points at its run by id, so a run that got edited under
+ * one would change what an already-recorded finding means. Nothing
+ * here mutates; substituting an outcome returns a new run.
+ *
+ * The counts are kept as a function rather than fields, because a
+ * stored count and a stored list of outcomes are two things that
+ * can disagree, and only one of them is the evidence.
+ */
+import { count } from "../../ui/count.js";
+/**
+ * What a round was given, in the shape a run records it.
+ *
+ * @see whatItRead
+ *
+ * The counterpart of `whatItRead`, and one helper for the same reason:
+ * it is one fact, six builders write it, and the last fact that had to
+ * reach all six reached four.
+ */
+export function whatItGave(request) {
+    return request.given === undefined ? {} : { given: request.given };
+}
+/** How many digits a sequence is padded to, so ids sort as text. */
+const SEQ_WIDTH = 6;
+/**
+ * Name a run.
+ *
+ * The round leads, so a bare id says what pass it was without
+ * anything having to look it up. The timestamp sorts. The sequence
+ * is part of the name rather than a tiebreak applied later, because
+ * two runs inside one millisecond would otherwise collide and make
+ * one run's findings unreachable, and it is zero-padded so it keeps
+ * sorting as text rather than putting 10 before 9.
+ */
+export function newRunId(round, at, seq) {
+    const stamp = at.toISOString().replace(/[-:.]/g, "").replace("Z", "");
+    return `${round}-${stamp}-${String(seq).padStart(SEQ_WIDTH, "0")}`;
+}
+/**
+ * What is wrong with the session rather than with the reviewers.
+ *
+ * Measured. Pi upgraded mid-session and deleted the versioned install
+ * directory the running session pins its children to, so every
+ * reviewer died on dispatch. The runner diagnosed it correctly and
+ * put the same sentence on all seven, and the round printed it seven
+ * times as though seven separate things had gone wrong.
+ *
+ * The repetition is not the cost. Seven failures beside a retry hint
+ * read as seven flaky reviewers, and retrying is the one thing that
+ * cannot work: it fails identically until the session restarts.
+ *
+ * Read off the outcome rather than sniffed out of the message. This
+ * matched a prefix first, which made one library string-match another
+ * library's prose, and both are free to reword: the diagnosis is a
+ * fact the dispatching side knows, so it is carried as one.
+ *
+ * One participant is enough. A stale install kills every reviewer it
+ * reaches, and a round where one dispatch raced the deletion is
+ * exactly as unrecoverable by retry as one where all seven did.
+ */
+export function staleRuntimeAdvisory(run) {
+    return run.outcomes.find((one) => one.advisory !== undefined)?.advisory;
+}
+/**
+ * One line for each participant that failed, without saying the same
+ * paragraph twice.
+ *
+ * The roll call has to survive an advisory: a reader needs to see who
+ * was asked and that none of them answered, or the round looks like it
+ * never ran. What it does not need is the advisory repeated under
+ * every name, which is what hoisting a sentence already on every
+ * outcome would otherwise produce, one copy longer than before.
+ *
+ * What was hoisted is told rather than worked out again. Deciding it
+ * twice means the two can disagree, and the way they disagree is the
+ * worst of both: a caller that suppressed the advisory gets a roll
+ * call of reviewers pointing at a line that is not there.
+ */
+export function failureLines(run, hoisted) {
+    const lines = [];
+    for (const outcome of run.outcomes) {
+        if (outcome.failure === undefined)
+            continue;
+        lines.push(outcome.failure === hoisted
+            ? `${outcome.participantId}: as above.`
+            : `${outcome.participantId}: ${outcome.failure}`);
+    }
+    return lines;
+}
+/**
+ * What became of each participant a limit took away.
+ *
+ * The round already records that a reviewer was stopped and where its
+ * answer was kept, and recorded both without ever printing them, which
+ * is most of the way to losing the answer regardless: nobody opens a
+ * ledger they have no reason to open. One line each, naming who, what
+ * stopped them and where to read what they said.
+ */
+export function stoppedNotes(run) {
+    const notes = [];
+    for (const outcome of run.outcomes) {
+        const stopped = outcome.stopped;
+        if (stopped === undefined)
+            continue;
+        const kept = outcome.answerPath === undefined
+            ? "nothing of its answer was kept"
+            : `its answer is at ${outcome.answerPath}`;
+        // A soft deadline is the round asking, not the round failing,
+        // and the ledger has to say so too. Reframing it in one surface
+        // and calling it a stop in the next just moves the alarm.
+        const how = stopped.limit === "soft-deadline"
+            ? "asked to wrap up early"
+            : `stopped (${stopped.limit})`;
+        notes.push(`${outcome.participantId} ${how}, ${count(outcome.findingIds.length, "finding")} read, ${kept}`);
+    }
+    return notes;
+}
+/**
+ * How a run went.
+ *
+ * Someone asked with no outcome at all counts as failed rather than
+ * as pending, since a run being reported on has finished and a
+ * participant that never reported is one that dropped. Answering
+ * nothing is an answer: a reviewer that read the change and had no
+ * complaint is not a failure, and counting it as one would make a
+ * clean review look broken.
+ *
+ * Unless the round is still open, where the same silence means the
+ * opposite. Nobody has asked those reviewers for anything yet: a
+ * started round that has recorded nothing summarised as seven failed
+ * out of seven, and every sentence built on that read as an
+ * accusation against reviewers who were at that moment working.
+ */
+export function runSummary(run) {
+    let answered = 0;
+    let reported = 0;
+    let findings = 0;
+    let tokens;
+    let cost;
+    for (const participant of run.participants) {
+        const outcome = run.outcomes.find((o) => o.participantId === participant.id);
+        if (outcome === undefined)
+            continue;
+        // Before the failure check, because a reviewer that died still
+        // spent what it spent.
+        if (outcome.usage?.tokens !== undefined) {
+            tokens = (tokens ?? 0) + outcome.usage.tokens;
+        }
+        if (outcome.usage?.cost !== undefined) {
+            cost = (cost ?? 0) + outcome.usage.cost;
+        }
+        if (outcome.failure !== undefined) {
+            reported += 1;
+            continue;
+        }
+        answered += 1;
+        findings += outcome.findingIds.length;
+    }
+    // A failure somebody recorded is a failure whatever state the round
+    // is in. Only silence changes meaning: on a settled round it is a
+    // participant that dropped, and on an open one it is a participant
+    // nobody has asked about yet.
+    const silent = run.participants.length - answered - reported;
+    const priced = run.outcomes.filter((outcome) => outcome.usage !== undefined).length;
+    return {
+        asked: run.participants.length,
+        answered,
+        failed: reported + (run.open === true ? 0 : silent),
+        pending: run.open === true ? silent : 0,
+        findings,
+        ...(tokens === undefined ? {} : { tokens }),
+        ...(cost === undefined ? {} : { cost }),
+        ...(priced > 0 && priced < run.participants.length
+            ? { partlyPriced: true }
+            : {}),
+    };
+}
+/**
+ * A retried outcome, carrying what the attempt it replaces cost.
+ *
+ * The findings are replaced, because the new attempt supersedes the
+ * old one and the round should not show both. The money is not: it
+ * was spent, and the reviewer being asked twice is precisely why the
+ * round cost what it did. Replacing the usage as well made the total
+ * fall after money had gone out, so the rounds with retries in them,
+ * which are the expensive ones, were the ones that under-reported.
+ */
+function billedWith(outcome, replaced) {
+    const before = replaced.usage;
+    if (before === undefined)
+        return outcome;
+    const tokens = sum(outcome.usage?.tokens, before.tokens);
+    const cost = sum(outcome.usage?.cost, before.cost);
+    if (tokens === undefined && cost === undefined)
+        return outcome;
+    return {
+        ...outcome,
+        usage: {
+            ...(tokens === undefined ? {} : { tokens }),
+            ...(cost === undefined ? {} : { cost }),
+        },
+    };
+}
+/** Two numbers added, where absent still means not told. */
+function sum(one, two) {
+    if (one === undefined)
+        return two;
+    return two === undefined ? one : one + two;
+}
+/**
+ * What a round read, in the shape a run records it.
+ *
+ * One helper rather than a conditional spread per builder, because
+ * these two are one fact. Recording the commit without the caveat is
+ * the failure this exists to stop: the run then claims the reviewers
+ * read the change when they read whatever the caller had checked out.
+ * Six sites spread the commit by hand, and it took until the ledger
+ * was counted to notice that half of them recorded nothing at all.
+ */
+export function whatItRead(read) {
+    return {
+        ...(read.witness === undefined ? {} : { witness: read.witness }),
+        ...(read.unpinned === undefined ? {} : { unpinned: read.unpinned }),
+    };
+}
+/**
+ * The commit an anchor from this round may claim.
+ *
+ * An anchor's witness means the commit it was formed against, and the
+ * substrate reads it to tell a thread the backend kept from one a
+ * force-push stranded. A round that fell back to the caller's
+ * checkout was never formed against the commit under review, so
+ * stamping it there makes the substrate confidently wrong in exactly
+ * the case the field exists to disambiguate.
+ *
+ * Nothing, then, rather than the commit: not knowing which tree a
+ * finding came from is the truth, and an anchor that says so degrades
+ * to what anchors did before witnesses existed. The run keeps both
+ * facts, because what the change is at and what the reviewers read
+ * are two different things and the ledger wants each.
+ */
+export function anchorWitness(read) {
+    return read.unpinned === undefined ? read.witness : undefined;
+}
+/** The identity a run asked under this id, if it asked one. */
+export function askedOf(run, participantId) {
+    return run.participants.find((p) => p.id === participantId);
+}
+/**
+ * Why a retry may not be given new settings, if it may not.
+ *
+ * A retry re-asks one participant and substitutes the answer into a
+ * round that already recorded who it asked and what each was set to.
+ * Asking on a different model puts one participant's answer into a run
+ * whose ledger names another, and the identity ledger cannot catch it,
+ * because the substitution keeps the held run's participants: nothing
+ * ever claims the new configuration.
+ *
+ * The clocks are the exception, and they are the reason somebody is
+ * retrying at all. How long a reviewer was allowed does not change
+ * what its findings mean, the ledger does not record it against the
+ * participant, and a reviewer stopped by a wall is refused the retry
+ * outright unless that wall moves. Refusing the one setting that makes
+ * the retry worth running would leave editing a committed file as the
+ * only road.
+ *
+ * A predicate rather than a branch inside the tool, so the rule can be
+ * read and tested without a round on disk to retry.
+ */
+export function retryCannotResettle(who, run, participantId) {
+    if (who === undefined)
+        return undefined;
+    const resettles = Object.values(who).flatMap((over) => Object.keys(over).filter((key) => !CLOCKS.has(key)));
+    if (resettles.length === 0)
+        return undefined;
+    return (`A retry re-asks "${participantId}" as round ${run.id} asked it, so ` +
+        `it cannot take new settings: its answer is substituted into that ` +
+        `round, whose ledger records what it originally asked under. ` +
+        `${resettles.map((key) => `"${key}"`).join(", ")} would change that. ` +
+        `Run a fresh council with who, or release the id and ask again. The ` +
+        `clocks are the exception and may be raised here, since how long a ` +
+        `reviewer was allowed does not change what it found.`);
+}
+/** The settings a retry may take, being the ones that change no meaning. */
+const CLOCKS = new Set([
+    "backstopMs",
+    "idleMs",
+    "answerMs",
+]);
+/**
+ * Replace one participant's outcome, returning a new run.
+ *
+ * This is what a retry does. The outcome keeps its position, since
+ * a retry that moved a reviewer to the end would reorder every
+ * report of the run for no reason a reader could see, and a
+ * participant who had no outcome yet gets one appended.
+ *
+ * Substituting for somebody outside the roster throws rather than
+ * refusing softly: it would make the run claim it asked somebody it
+ * never did, and no caller has a sensible way to carry on from
+ * that.
+ *
+ * What this attempt read is required rather than optional, since
+ * omitting it means "the same tree the round had", which is the most
+ * optimistic reading available and the wrong default for the case
+ * that matters: a retry that fell back leaves the round less faithful
+ * than it was. Pass an empty record to say there is nothing to add.
+ */
+export function substituteOutcome(run, outcome, read) {
+    if (askedOf(run, outcome.participantId) === undefined) {
+        throw new Error(`This run never asked "${outcome.participantId}", so there is no outcome of theirs to replace. It asked ${run.participants.map((p) => p.id).join(", ")}.`);
+    }
+    const at = run.outcomes.findIndex((o) => o.participantId === outcome.participantId);
+    const outcomes = at === -1
+        ? [...run.outcomes, outcome]
+        : run.outcomes.map((held, index) => index === at ? billedWith(outcome, held) : held);
+    // Filling the last gap in an interrupted round settles it.
+    //
+    // Without this the flag is one-way and the recovery it points at
+    // dead-ends: a session dies holding a council, every participant is
+    // asked again, and the completed round still reports itself as
+    // never settled forever. An alarm nobody can answer stops being
+    // read, which costs the one case it was raised for.
+    const waiting = run.participants.some((asked) => !outcomes.some((held) => held.participantId === asked.id));
+    // A retry that fell back to the caller's checkout makes the round
+    // less faithful than it was, and the run is the only place that can
+    // say so. Told rather than inferred, since only the caller knows
+    // which tree this attempt got, and one-way: a retry that happened
+    // to be pinned does not clear a caveat earned by the reviewers
+    // already in the round.
+    const fell = read?.unpinned === undefined ? {} : { unpinned: read.unpinned };
+    const { open: _wasOpen, ...rest } = run;
+    return waiting
+        ? { ...run, outcomes, ...fell }
+        : { ...rest, outcomes, ...fell };
+}

package/dist/review/ask/span.d.ts

@@ -0,0 +1,70 @@
+/**
+ * A finding that belongs to a stack rather than to one change.
+ *
+ * Reviewing a stack one change at a time hides the findings that only
+ * exist between changes: an interface introduced at the base and used
+ * wrongly at the tip, a migration split so the middle change cannot
+ * deploy on its own. Asking about the whole stack at once surfaces
+ * those, but only if a finding can say it is about several changes.
+ *
+ * So a span, and not a duplicate on each change. Repeating one
+ * observation on every change it touches makes a reader answer it
+ * three times and leaves three places to resolve it, and the thing
+ * that made it worth saying, that it is *between* them, is exactly
+ * what gets lost.
+ *
+ * A span names refs rather than positions. A stack renumbers itself
+ * every time somebody restacks it, so a finding recorded as "the
+ * second change" is wrong as soon as anything lands underneath.
+ */
+import type { Finding, FindingOrigin } from "../finding.js";
+/** The changes a finding is about, in stack order. */
+export interface FindingSpan {
+    /** One ref for an ordinary finding, several for a cross-change one. */
+    refs: string[];
+}
+/** A finding plus the changes it is about. */
+export interface SpannedFinding {
+    span: FindingSpan;
+    finding: Omit<Finding, "id">;
+}
+/** What came out of one stack-wide answer. */
+export interface StackHarvest {
+    /**
+     * Of the warnings, the ones about recorded entries rather than
+     * about the answer's shape. Named for the same reason the single
+     * change's harvest names them: the caller that needs them is the
+     * one replacing the whole list.
+     */
+    recordedWarnings?: string[];
+    findings: SpannedFinding[];
+    warnings: string[];
+}
+/**
+ * Read a stack-wide answer, warning about what it dropped.
+ *
+ * `witnessFor` is asked for the witness of the change a finding is
+ * said at, because each change has its own diff: checking a line
+ * finding on the tip against the base's diff would degrade a perfectly
+ * good anchor for no reason.
+ */
+export declare function harvestStackFindings(text: string, origin: FindingOrigin, stackRefs: readonly string[], witnessFor?: (ref: string) => string | undefined): StackHarvest;
+/**
+ * The stack answer, plus what the reviewer wrote down reaching it.
+ *
+ * The same bargain as a single change's round, with one extra
+ * requirement: a recorded finding still has to say which changes it is
+ * about, because a stack round's whole job is placing one. An entry
+ * that names none is dropped with a warning, exactly as it would be
+ * inside an answer.
+ */
+export declare function alsoRecordedInStack(said: StackHarvest, recorded: readonly unknown[] | undefined, origin: FindingOrigin, stackRefs: readonly string[], witnessFor?: (ref: string) => string | undefined): StackHarvest;
+/**
+ * Where a span gets said.
+ *
+ * The earliest change it touches, because that is where the decision
+ * was made and where a reader walking the stack meets it first. Saying
+ * it at the tip sends somebody to the consequence and leaves them to
+ * work back to the cause.
+ */
+export declare function saidAt(span: FindingSpan, stackRefs: readonly string[]): string;

package/dist/review/ask/span.js

@@ -0,0 +1,166 @@
+/**
+ * A finding that belongs to a stack rather than to one change.
+ *
+ * Reviewing a stack one change at a time hides the findings that only
+ * exist between changes: an interface introduced at the base and used
+ * wrongly at the tip, a migration split so the middle change cannot
+ * deploy on its own. Asking about the whole stack at once surfaces
+ * those, but only if a finding can say it is about several changes.
+ *
+ * So a span, and not a duplicate on each change. Repeating one
+ * observation on every change it touches makes a reader answer it
+ * three times and leaves three places to resolve it, and the thing
+ * that made it worth saying, that it is *between* them, is exactly
+ * what gets lost.
+ *
+ * A span names refs rather than positions. A stack renumbers itself
+ * every time somebody restacks it, so a finding recorded as "the
+ * second change" is wrong as soon as anything lands underneath.
+ */
+import { readWireFinding, SAID_NOTHING, saysTheSame } from "./harvest.js";
+import { ANSWER_WAS_CUT_OFF, isRecord, readAnswer, wireText } from "./wire.js";
+/**
+ * Read a stack-wide answer, warning about what it dropped.
+ *
+ * `witnessFor` is asked for the witness of the change a finding is
+ * said at, because each change has its own diff: checking a line
+ * finding on the tip against the base's diff would degrade a perfectly
+ * good anchor for no reason.
+ */
+export function harvestStackFindings(text, origin, stackRefs, witnessFor) {
+    const { parsed, truncated } = readAnswer(text, "findings");
+    const held = parsed?.findings;
+    if (!Array.isArray(held)) {
+        return {
+            findings: [],
+            // A reviewer that produced nothing has not broken a contract
+            // about the shape of an answer it never reached. Same rule as
+            // a single change's round, and for the same reason: it is the
+            // case a journal exists to rescue.
+            warnings: [
+                text.trim() === ""
+                    ? SAID_NOTHING
+                    : "Nothing in this answer parsed as a findings array, so no findings could be read from it. An answer with nothing to say should still say findings: [].",
+            ],
+        };
+    }
+    const findings = [];
+    const warnings = [];
+    if (truncated)
+        warnings.push(ANSWER_WAS_CUT_OFF);
+    for (const [index, entry] of held.entries()) {
+        const at = `findings[${index}]`;
+        const span = readSpan(entry, at, stackRefs, warnings);
+        if (span === undefined)
+            continue;
+        const read = readWireFinding(entry, at, origin, witnessFor?.(saidAt(span, stackRefs)));
+        warnings.push(...read.warnings);
+        if (read.finding !== undefined) {
+            findings.push({ span, finding: read.finding });
+        }
+    }
+    return { findings, warnings };
+}
+/**
+ * The stack answer, plus what the reviewer wrote down reaching it.
+ *
+ * The same bargain as a single change's round, with one extra
+ * requirement: a recorded finding still has to say which changes it is
+ * about, because a stack round's whole job is placing one. An entry
+ * that names none is dropped with a warning, exactly as it would be
+ * inside an answer.
+ */
+export function alsoRecordedInStack(said, recorded, origin, stackRefs, witnessFor) {
+    if (recorded === undefined || recorded.length === 0)
+        return said;
+    const findings = [...said.findings];
+    const recordedWarnings = [];
+    const before = findings.length;
+    // Keyed with the span, not just the finding. Two changes in a
+    // stack can carry the same line at the same path, which is what a
+    // stack is, so the same sentence about two of them is two findings
+    // and collapsing them would report the wrong change.
+    for (const [index, entry] of recorded.entries()) {
+        const at = `recorded[${index}]`;
+        const span = readSpan(entry, at, stackRefs, recordedWarnings);
+        if (span === undefined)
+            continue;
+        const read = readWireFinding(entry, at, origin, witnessFor?.(saidAt(span, stackRefs)));
+        recordedWarnings.push(...read.warnings);
+        const found = read.finding;
+        if (found === undefined)
+            continue;
+        if (findings.some((held) => sameSpannedFinding(held, { span, finding: found })))
+            continue;
+        findings.push({ span, finding: found });
+    }
+    const aboutTheAnswer = findings.length > before
+        ? said.warnings.filter((warning) => warning !== SAID_NOTHING)
+        : said.warnings;
+    return {
+        findings,
+        warnings: [...aboutTheAnswer, ...recordedWarnings],
+        recordedWarnings,
+    };
+}
+/**
+ * The same finding said about the same changes.
+ *
+ * The span has to match exactly while the finding is compared the
+ * forgiving way, because two changes in a stack can carry the same
+ * line at the same path, which is what a stack is: the same sentence
+ * about two of them is two findings, and collapsing them would report
+ * the wrong change.
+ */
+function sameSpannedFinding(one, two) {
+    return (JSON.stringify(one.span) === JSON.stringify(two.span) &&
+        saysTheSame(one.finding, two.finding));
+}
+/**
+ * Where a span gets said.
+ *
+ * The earliest change it touches, because that is where the decision
+ * was made and where a reader walking the stack meets it first. Saying
+ * it at the tip sends somebody to the consequence and leaves them to
+ * work back to the cause.
+ */
+export function saidAt(span, stackRefs) {
+    const ordered = inStackOrder(span.refs, stackRefs);
+    return ordered[0] ?? span.refs[0] ?? "";
+}
+/** The changes an entry claims to be about, or nothing plus a warning. */
+function readSpan(entry, at, stackRefs, warnings) {
+    if (!isRecord(entry)) {
+        warnings.push(`${at} is not an object, so it was dropped.`);
+        return undefined;
+    }
+    const claimed = Array.isArray(entry.refs) ? entry.refs : [];
+    const named = claimed.flatMap((value) => {
+        const ref = wireText(value);
+        return ref === undefined ? [] : [ref];
+    });
+    const known = named.filter((ref) => stackRefs.includes(ref));
+    const unknown = named.filter((ref) => !stackRefs.includes(ref));
+    if (unknown.length > 0) {
+        // Dropping the ref rather than the finding when others survive:
+        // a reviewer that named three changes and got one wrong still
+        // saw something real about the other two.
+        warnings.push(`${at} names ${unknown.join(", ")}, which ${unknown.length === 1 ? "is not a change" : "are not changes"} in this stack, so ${unknown.length === 1 ? "it was" : "they were"} left out.`);
+    }
+    if (known.length === 0) {
+        warnings.push(`${at} names no change in this stack, so it was dropped: a finding nobody can place is a finding nobody can read.`);
+        return undefined;
+    }
+    return { refs: inStackOrder(known, stackRefs) };
+}
+/**
+ * Refs in the order the stack reports them, roots before children.
+ *
+ * A span reported tip-first would read backwards against the stack it
+ * describes, and the order a model happened to list them in carries no
+ * meaning worth preserving.
+ */
+function inStackOrder(refs, stackRefs) {
+    const unique = [...new Set(refs)];
+    return unique.sort((a, b) => stackRefs.indexOf(a) - stackRefs.indexOf(b));
+}

package/dist/review/ask/stack-round.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Asking a roster about a whole stack at once.
+ *
+ * The fan-out is the council's, reused rather than rewritten: the
+ * rules worth getting right, that participants are asked concurrently,
+ * that a thrown error and a reported one are the same event, and that
+ * findings are numbered in roster order, are the same rules here and
+ * would have to change together. What differs is what a reply means. A
+ * council reply is findings about one change; a stack reply is
+ * findings about a stack, each naming the changes it is about.
+ *
+ * Which is why `record` takes a ref. A stack round produces findings
+ * for several changes at once, and the store needs to know which
+ * change each belongs to. A spanning finding is filed once, at its
+ * earliest change, because filing it on every change it touches makes
+ * a reader answer one observation three times.
+ */
+import type { Finding } from "../finding.js";
+import { type Ask, type CouncilResult } from "./council.js";
+import { type AskProgress } from "./progress.js";
+import type { Roster } from "./roster.js";
+import { type RoundGiven } from "./run.js";
+/** The impure things a stack round needs. */
+export interface StackCouncilDeps {
+    /**
+     * Run one participant against the prompt.
+     *
+     * Reporting matters most here: a stack round is the longest there
+     * is, because it reads every change.
+     */
+    ask: Ask;
+    /** File findings against one change in the stack. */
+    record(ref: string, findings: Omit<Finding, "id">[]): Promise<Finding[]>;
+    now(): Date;
+    /** Told what is happening while it happens. Optional. */
+    progress?: AskProgress;
+}
+/** What to ask, of whom, about which changes. */
+export interface StackCouncilRequest {
+    roster: Roster;
+    prompt: string;
+    /** Distinguishes two rounds started in the same millisecond. */
+    seq: number;
+    /** Every change in the stack, roots before children. */
+    stackRefs: string[];
+    /**
+     * The commit one change's anchors are formed against.
+     *
+     * Per change, because each has its own diff: checking a finding on
+     * the tip against the base's diff would degrade a good anchor for
+     * nothing.
+     */
+    witnessFor?: (ref: string) => string | undefined;
+    /** Said when the tree the reviewers read was not the stack's tip. */
+    unpinned?: string;
+    /**
+     * What the reviewers were handed, besides the changes.
+     *
+     * Not exempted the way the witness is. A stack is read in one tree
+     * under one set of conditions, so what its reviewers were given is
+     * a single fact however many changes they read.
+     */
+    given?: RoundGiven;
+}
+/** Ask a roster about a stack and file what it says. */
+export declare function runStackCouncil(request: StackCouncilRequest, deps: StackCouncilDeps): Promise<CouncilResult>;