@cat-factory/contracts 0.236.0 → 0.237.0

package/dist/public-decisions.d.ts

@@ -1,6 +1,13 @@
 import * as v from 'valibot';
-/** Which parked decision a `publicDecision` entry describes. */
-export declare const publicDecisionKindSchema: v.PicklistSchema<["requirements-review", "fork", "judge", "input-gate"], undefined>;
+/**
+ * Which parked decision a `publicDecision` entry describes.
+ *
+ * The list is the surface's own honesty check: `PUBLICLY_ANSWERABLE_PARK_SURFACES` (server-side
+ * admission) names the park surfaces a `decide` key is TOLD it can answer, and a kind here with no
+ * route behind it is exactly the "refusal advertising a capability we do not have" defect that set
+ * builds. Add a member only together with its routes.
+ */
+export declare const publicDecisionKindSchema: v.PicklistSchema<["requirements-review", "fork", "judge", "input-gate", "approval-gate", "agent-decision", "clarity-review", "brainstorm", "pr-review", "human-test", "visual-confirmation"], undefined>;
 export type PublicDecisionKind = v.InferOutput<typeof publicDecisionKindSchema>;
 /**
  * One reviewer finding as exposed externally — the question, how serious it is, and where it
@@ -153,6 +160,395 @@ export declare const publicInputGateDecisionSchema: v.ObjectSchema<{
     readonly checkedAt: v.NumberSchema<undefined>;
 }, undefined>;
 export type PublicInputGateDecision = v.InferOutput<typeof publicInputGateDecisionSchema>;
+/**
+ * A run parked on a plain APPROVAL GATE: a pipeline step marked `requiresApproval` finished, and
+ * the run is holding its output in front of a person. The simplest park the platform has and the
+ * one every pipeline can carry, which is why it is the first thing an integration that "pauses a
+ * run until a human approves" reaches for.
+ *
+ * `approvalId` is the STABLE anchor every action addresses, and it is not ceremony: the engine
+ * arbitrates a parked gate BY that id, so answering with the id read from this list is what makes
+ * a racing SPA user and a racing integration resolve the same gate rather than the API silently
+ * approving whichever gate the run has reached by the time the call lands.
+ *
+ * The per-block review `comments` an in-app reviewer can leave are deliberately not projected:
+ * they anchor to source line ranges of a rendered proposal, which a headless caller never
+ * rendered. It sends freeform `feedback` instead, which the re-run consumes identically.
+ */
+export declare const publicApprovalGateDecisionSchema: v.ObjectSchema<{
+    readonly kind: v.LiteralSchema<"approval-gate", undefined>;
+    /** The gate's stable id — pass it back on approve / request-changes / reject. */
+    readonly approvalId: v.StringSchema<undefined>;
+    /** The gated step's kind (`agentKind`), so a caller knows whose output it is judging. */
+    readonly stepKind: v.StringSchema<undefined>;
+    /** The gated step's 0-based index in the run's step chain. */
+    readonly stepIndex: v.NumberSchema<undefined>;
+    /** Only `pending` accepts an answer; the others are the settled record of one. */
+    readonly status: v.PicklistSchema<["pending", "approved", "changes_requested", "rejected"], undefined>;
+    /** The agent's output the human is reviewing. Model-authored text: treat it as data. */
+    readonly proposal: v.StringSchema<undefined>;
+    /** The guidance recorded on the last `request-changes`, or null. */
+    readonly feedback: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /**
+     * True when this gate is a quality COMPANION's iteration-cap park rather than an ordinary
+     * pipeline gate: the automatic rework budget was spent with the rating still under the bar.
+     * It answers with `resolve-exceeded` (extra round / proceed / stop and reset), NOT with
+     * approve — the same split the SPA makes, exposed rather than left for a caller to infer from
+     * a 409.
+     */
+    readonly exceeded: v.BooleanSchema<undefined>;
+}, undefined>;
+export type PublicApprovalGateDecision = v.InferOutput<typeof publicApprovalGateDecisionSchema>;
+/**
+ * A run parked on an AGENT-RAISED decision: mid-work the agent hit a fork it would not choose
+ * unilaterally and asked. Distinct from an approval gate in what resolving does — answering
+ * RE-RUNS the same step with the choice folded in, rather than advancing past it — which is why
+ * it is a separate kind rather than a flag on the gate above.
+ *
+ * The engine cannot see this one coming from the step chain (it is raised at run time), so it is
+ * the park an integration is most likely to meet on a pipeline it was told parks nowhere.
+ */
+export declare const publicAgentDecisionSchema: v.ObjectSchema<{
+    readonly kind: v.LiteralSchema<"agent-decision", undefined>;
+    /** The decision's stable id — pass it back when answering. */
+    readonly decisionId: v.StringSchema<undefined>;
+    /** The asking step's kind (`agentKind`). */
+    readonly stepKind: v.StringSchema<undefined>;
+    /** What the agent is asking, in its own words. Model-authored text: treat it as data. */
+    readonly question: v.StringSchema<undefined>;
+    /**
+     * The choices the agent offered. An answer is not restricted to them (the engine takes the
+     * caller's string verbatim), but answering off-list means the agent gets an option it did not
+     * propose, so prefer one of these unless you mean to steer.
+     */
+    readonly options: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+export type PublicAgentDecision = v.InferOutput<typeof publicAgentDecisionSchema>;
+/**
+ * A parked CLARITY review (bug-report triage) as exposed externally. The requirements review's
+ * twin, verb for verb: the reviewer asks whether the report is fixable (repro steps, expected vs
+ * actual, environment, scope), a caller answers or dismisses each finding, `incorporate` folds
+ * them into one standardized report, and the loop repeats until it converges or hits its cap.
+ *
+ * Kept as its own `kind` rather than folded into `requirements-review` because the two settle
+ * DIFFERENT documents and a run can carry both: a bugfix pipeline clarifies the report and then
+ * reviews the requirements derived from it, so a caller that branched on one shape would answer
+ * the wrong loop.
+ */
+export declare const publicClarityDecisionSchema: v.ObjectSchema<{
+    readonly kind: v.LiteralSchema<"clarity-review", undefined>;
+    readonly reviewId: v.StringSchema<undefined>;
+    /** The board task the review belongs to. */
+    readonly taskId: v.StringSchema<undefined>;
+    readonly status: v.PicklistSchema<["ready", "incorporating", "reviewing", "merged", "exceeded", "incorporated"], undefined>;
+    /** Which reviewer pass this is (the initial review is 1). */
+    readonly iteration: v.NumberSchema<undefined>;
+    /** The reviewer-pass budget, from the task's merge preset. */
+    readonly maxIterations: v.NumberSchema<undefined>;
+    readonly findings: v.ArraySchema<v.ObjectSchema<{
+        readonly itemId: v.StringSchema<undefined>;
+        /** What kind of concern this raises (gap / clarification / assumption / risk / question). */
+        readonly category: v.PicklistSchema<["gap", "clarification", "assumption", "risk", "question"], undefined>;
+        /** How important resolving it is before implementation proceeds. */
+        readonly severity: v.PicklistSchema<["low", "medium", "high"], undefined>;
+        /** Short headline of the concern. */
+        readonly title: v.StringSchema<undefined>;
+        /** The full question / gap / challenge, in plain prose. */
+        readonly detail: v.StringSchema<undefined>;
+        /** `open` until answered or dismissed; only `open` findings block incorporation. */
+        readonly status: v.PicklistSchema<["open", "answered", "resolved", "dismissed", "recommend_requested"], undefined>;
+        /** The recorded answer, or null while unanswered. */
+        readonly reply: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    /**
+     * The standardized bug report the last incorporation produced; null until one exists. Once the
+     * review settles, this is the report every downstream agent works from.
+     */
+    readonly clarifiedReport: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+export type PublicClarityDecision = v.InferOutput<typeof publicClarityDecisionSchema>;
+/**
+ * A parked BRAINSTORM dialogue as exposed externally: the agent proposed a handful of concrete
+ * options with their trade-offs, and the run is waiting for a person to pick and steer before it
+ * converges on one direction.
+ *
+ * Keyed by `(task, stage)`, not task alone — a block may hold one live `requirements` session and
+ * one live `architecture` session at once, so a decision list can carry TWO brainstorm entries and
+ * every route takes the stage. A caller that keys its own state by `kind` alone will collide the
+ * two; key by `kind` + `stage`.
+ */
+export declare const publicBrainstormDecisionSchema: v.ObjectSchema<{
+    readonly kind: v.LiteralSchema<"brainstorm", undefined>;
+    readonly sessionId: v.StringSchema<undefined>;
+    /** Which dialogue this is: the requirements direction, or the architecture approach. */
+    readonly stage: v.PicklistSchema<["requirements", "architecture"], undefined>;
+    /** The board task the session belongs to. */
+    readonly taskId: v.StringSchema<undefined>;
+    readonly status: v.PicklistSchema<["ready", "incorporating", "reviewing", "merged", "exceeded", "incorporated"], undefined>;
+    /** Which agent pass this is (the initial pass is 1). */
+    readonly iteration: v.NumberSchema<undefined>;
+    /** The agent-pass budget, from the task's merge preset. */
+    readonly maxIterations: v.NumberSchema<undefined>;
+    /**
+     * The proposed options. Structurally the same shape as a review finding (one source of truth
+     * for the item), but read it as a proposal to pick or steer, not a defect to answer.
+     */
+    readonly options: v.ArraySchema<v.ObjectSchema<{
+        readonly itemId: v.StringSchema<undefined>;
+        /** What kind of concern this raises (gap / clarification / assumption / risk / question). */
+        readonly category: v.PicklistSchema<["gap", "clarification", "assumption", "risk", "question"], undefined>;
+        /** How important resolving it is before implementation proceeds. */
+        readonly severity: v.PicklistSchema<["low", "medium", "high"], undefined>;
+        /** Short headline of the concern. */
+        readonly title: v.StringSchema<undefined>;
+        /** The full question / gap / challenge, in plain prose. */
+        readonly detail: v.StringSchema<undefined>;
+        /** `open` until answered or dismissed; only `open` findings block incorporation. */
+        readonly status: v.PicklistSchema<["open", "answered", "resolved", "dismissed", "recommend_requested"], undefined>;
+        /** The recorded answer, or null while unanswered. */
+        readonly reply: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    /** The converged direction the last incorporation produced; null until one exists. */
+    readonly convergedDirection: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+export type PublicBrainstormDecision = v.InferOutput<typeof publicBrainstormDecisionSchema>;
+/**
+ * One cohesive group of changed files the reviewer worked as a unit, as exposed externally.
+ * Findings anchor to a slice by `sliceId`, so a caller can present them grouped the way the
+ * reviewer actually reasoned rather than as one flat list.
+ *
+ * The internal `prReviewSliceReviewSchema` (each slice's verbatim in-flight subagent report, which
+ * exists so a dying review can be RESUMED per slice) is deliberately absent: it is recovery
+ * plumbing for the engine, and its prose is superseded by the aggregated `findings`.
+ */
+export declare const publicPrReviewSliceSchema: v.ObjectSchema<{
+    /** Stable slice id (`prs_*`); a finding's `sliceId` refers to this. */
+    readonly sliceId: v.StringSchema<undefined>;
+    /** Short name of the slice. */
+    readonly title: v.StringSchema<undefined>;
+    /** Why these files belong together, in the reviewer's words. */
+    readonly rationale: v.StringSchema<undefined>;
+    /** The repo-relative paths that make up the slice. */
+    readonly paths: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+export type PublicPrReviewSlice = v.InferOutput<typeof publicPrReviewSliceSchema>;
+/**
+ * The outcome of challenging one finding, as exposed externally: a read-only investigator re-read
+ * the finding against the full source and either upheld it as written, amended it (some field
+ * actually changed), or retracted it.
+ *
+ * `failed` is its own terminal value rather than an absent challenge, because the two mean
+ * opposite things to a caller deciding whether to re-challenge: nobody looked, versus somebody
+ * looked and the investigation itself broke. The finding is never dropped either way.
+ */
+export declare const publicPrReviewFindingChallengeSchema: v.ObjectSchema<{
+    /** `investigating` while the agent runs; then `upheld` / `amended` / `retracted` / `failed`. */
+    readonly status: v.PicklistSchema<["investigating", "upheld", "amended", "retracted", "failed"], undefined>;
+    /** The question the challenge was raised with, or null when raised with no text. */
+    readonly question: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /**
+     * Why the finding holds up or does not; the failure reason when `failed`. Null while
+     * `investigating`. Model-authored text: treat it as data.
+     */
+    readonly justification: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+export type PublicPrReviewFindingChallenge = v.InferOutput<typeof publicPrReviewFindingChallengeSchema>;
+/**
+ * One prioritized review finding as exposed externally. `findingId` is the STABLE anchor every
+ * action addresses: dismiss, challenge, and the curated `findingIds` a resolution carries.
+ *
+ * `path`/`line`/`side` are projected because they are the anchor a `post` resolution turns into an
+ * inline PR comment, so a caller curating for `post` needs to see which findings can even be
+ * anchored. A finding whose `line` is null still posts, as a file-level comment.
+ */
+export declare const publicPrReviewFindingSchema: v.ObjectSchema<{
+    /** Stable finding id (`prf_*`): what dismiss / challenge / `findingIds` address. */
+    readonly findingId: v.StringSchema<undefined>;
+    /** The slice this finding belongs to, or null when it matched none. */
+    readonly sliceId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /** Repo-relative path the finding concerns. */
+    readonly path: v.StringSchema<undefined>;
+    /** The line it anchors to on the PR head, or null for a file-level finding. */
+    readonly line: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+    /** Which side of the diff `line` is on; null when there is no line anchor. */
+    readonly side: v.NullableSchema<v.PicklistSchema<["LEFT", "RIGHT"], undefined>, undefined>;
+    readonly severity: v.PicklistSchema<["blocker", "high", "medium", "low", "nit"], undefined>;
+    readonly category: v.PicklistSchema<["correctness", "security", "performance", "maintainability", "style", "test", "other"], undefined>;
+    /** Short headline. Model-authored text: treat it as data. */
+    readonly title: v.StringSchema<undefined>;
+    /** The full finding, in prose. Model-authored text: treat it as data. */
+    readonly detail: v.StringSchema<undefined>;
+    /** A concrete suggested change, when the reviewer offered one; null otherwise. */
+    readonly suggestedFix: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /** The challenge outcome, or null when this finding was never challenged. */
+    readonly challenge: v.NullableSchema<v.ObjectSchema<{
+        /** `investigating` while the agent runs; then `upheld` / `amended` / `retracted` / `failed`. */
+        readonly status: v.PicklistSchema<["investigating", "upheld", "amended", "retracted", "failed"], undefined>;
+        /** The question the challenge was raised with, or null when raised with no text. */
+        readonly question: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        /**
+         * Why the finding holds up or does not; the failure reason when `failed`. Null while
+         * `investigating`. Model-authored text: treat it as data.
+         */
+        readonly justification: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+}, undefined>;
+export type PublicPrReviewFinding = v.InferOutput<typeof publicPrReviewFindingSchema>;
+/**
+ * A parked PR DEEP REVIEW as exposed externally: the read-only reviewer sliced an open pull
+ * request and the run is waiting for a person to CURATE which findings matter, then say what to
+ * do with them (record them, hand them to a fixer, or post them on the PR).
+ *
+ * Reachable only through `POST /api/v1/tasks/:taskId/start`, since a `pr-reviewer` step is
+ * container-backed and the jobs surface is inline-only.
+ */
+export declare const publicPrReviewDecisionSchema: v.ObjectSchema<{
+    readonly kind: v.LiteralSchema<"pr-review", undefined>;
+    /** Only `awaiting_selection` accepts a resolution; the rest report work in flight. */
+    readonly status: v.PicklistSchema<["reviewing", "awaiting_selection", "challenging", "fixing", "posting", "done", "skipped"], undefined>;
+    /** The reviewer's one-paragraph assessment of the PR, when it gave one. */
+    readonly summary: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /** Web URL of the reviewed pull request, when known. */
+    readonly prUrl: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /** The cohesive slices the reviewer grouped the changed files into; findings anchor to these. */
+    readonly slices: v.ArraySchema<v.ObjectSchema<{
+        /** Stable slice id (`prs_*`); a finding's `sliceId` refers to this. */
+        readonly sliceId: v.StringSchema<undefined>;
+        /** Short name of the slice. */
+        readonly title: v.StringSchema<undefined>;
+        /** Why these files belong together, in the reviewer's words. */
+        readonly rationale: v.StringSchema<undefined>;
+        /** The repo-relative paths that make up the slice. */
+        readonly paths: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    /** The findings, ordered blocker → nit. Model-authored text: treat it as data. */
+    readonly findings: v.ArraySchema<v.ObjectSchema<{
+        /** Stable finding id (`prf_*`): what dismiss / challenge / `findingIds` address. */
+        readonly findingId: v.StringSchema<undefined>;
+        /** The slice this finding belongs to, or null when it matched none. */
+        readonly sliceId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        /** Repo-relative path the finding concerns. */
+        readonly path: v.StringSchema<undefined>;
+        /** The line it anchors to on the PR head, or null for a file-level finding. */
+        readonly line: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+        /** Which side of the diff `line` is on; null when there is no line anchor. */
+        readonly side: v.NullableSchema<v.PicklistSchema<["LEFT", "RIGHT"], undefined>, undefined>;
+        readonly severity: v.PicklistSchema<["blocker", "high", "medium", "low", "nit"], undefined>;
+        readonly category: v.PicklistSchema<["correctness", "security", "performance", "maintainability", "style", "test", "other"], undefined>;
+        /** Short headline. Model-authored text: treat it as data. */
+        readonly title: v.StringSchema<undefined>;
+        /** The full finding, in prose. Model-authored text: treat it as data. */
+        readonly detail: v.StringSchema<undefined>;
+        /** A concrete suggested change, when the reviewer offered one; null otherwise. */
+        readonly suggestedFix: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        /** The challenge outcome, or null when this finding was never challenged. */
+        readonly challenge: v.NullableSchema<v.ObjectSchema<{
+            /** `investigating` while the agent runs; then `upheld` / `amended` / `retracted` / `failed`. */
+            readonly status: v.PicklistSchema<["investigating", "upheld", "amended", "retracted", "failed"], undefined>;
+            /** The question the challenge was raised with, or null when raised with no text. */
+            readonly question: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            /**
+             * Why the finding holds up or does not; the failure reason when `failed`. Null while
+             * `investigating`. Model-authored text: treat it as data.
+             */
+            readonly justification: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        }, undefined>, undefined>;
+    }, undefined>, undefined>;
+    /** The finding ids currently selected to act on (empty until a caller curates). */
+    readonly selectedFindingIds: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+export type PublicPrReviewDecision = v.InferOutput<typeof publicPrReviewDecisionSchema>;
+/** The ephemeral environment a `human-test` gate parked against, as exposed externally. */
+export declare const publicHumanTestEnvironmentSchema: v.ObjectSchema<{
+    /** The public URL to test against; null while still provisioning. */
+    readonly url: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly status: v.PicklistSchema<["provisioning", "ready", "failed", "expired", "tearing_down", "torn_down"], undefined>;
+    /** Epoch ms the environment expires, when known. */
+    readonly expiresAt: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+}, undefined>;
+export type PublicHumanTestEnvironment = v.InferOutput<typeof publicHumanTestEnvironmentSchema>;
+/**
+ * A run parked on the HUMAN-TEST gate: a live ephemeral environment is up and the run is waiting
+ * for a person to exercise it.
+ *
+ * Exposed with its limits stated rather than sold as equivalent to the other kinds. The verbs are
+ * mechanical, but the JUDGEMENT this park records ("does the change actually work") is the one an
+ * API consumer is least able to supply on its own. It earns its place for the integration that
+ * drives its own human through a different UI, or that has a real automated check to run against
+ * `environment.url`; it is not a way to wave a run through unlooked-at.
+ */
+export declare const publicHumanTestDecisionSchema: v.ObjectSchema<{
+    readonly kind: v.LiteralSchema<"human-test", undefined>;
+    /** Only `awaiting_human` accepts an answer; the others report work in flight. */
+    readonly phase: v.PicklistSchema<["provisioning", "awaiting_human", "fixing", "resolving_conflicts", "passed"], undefined>;
+    /** The environment to test against; null in degraded manual mode or after a destroy. */
+    readonly environment: v.NullableSchema<v.ObjectSchema<{
+        /** The public URL to test against; null while still provisioning. */
+        readonly url: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly status: v.PicklistSchema<["provisioning", "ready", "failed", "expired", "tearing_down", "torn_down"], undefined>;
+        /** Epoch ms the environment expires, when known. */
+        readonly expiresAt: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    /**
+     * Why no environment was provisioned (no env provider wired, or provisioning errored). Non-null
+     * means the gate is in manual mode: there is nothing to point a check at, and the change has to
+     * be tested against the PR branch by hand.
+     */
+    readonly degradedReason: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /** Fixer rounds spent, and the ceiling from the task's merge preset. */
+    readonly attempts: v.NumberSchema<undefined>;
+    readonly maxAttempts: v.NumberSchema<undefined>;
+}, undefined>;
+export type PublicHumanTestDecision = v.InferOutput<typeof publicHumanTestDecisionSchema>;
+/**
+ * One actual-vs-reference pairing the visual-confirmation gate is showing, as exposed externally:
+ * a logical view, the screenshot captured of it, and the reference design for the same view when
+ * one was uploaded.
+ *
+ * Either side may be null (a captured view with no reference, or a reference whose view was never
+ * captured), and BOTH ids being null is meaningful rather than degenerate: it says the view is
+ * known and neither image exists. That is why the fields are always-present nullables instead of
+ * optional ones.
+ */
+export declare const publicVisualConfirmPairSchema: v.ObjectSchema<{
+    /** The logical view this pairing is for. */
+    readonly view: v.StringSchema<undefined>;
+    /** Artifact id of the captured screenshot, or null. App-resolvable only; see below. */
+    readonly actualArtifactId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /** Artifact id of the uploaded reference design, or null. App-resolvable only; see below. */
+    readonly referenceArtifactId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+export type PublicVisualConfirmPair = v.InferOutput<typeof publicVisualConfirmPairSchema>;
+/**
+ * A run parked on the VISUAL-CONFIRMATION gate: the UI tester's screenshots are waiting to be
+ * compared against the uploaded reference designs.
+ *
+ * Same caveat as {@link publicHumanTestDecisionSchema}, and one more: the images themselves are
+ * NOT readable over `/api/v1`. `pairs` carries the artifact ids so a caller can see how many views
+ * were captured and which ones have a reference at all, but resolving an id to an image needs the
+ * app. That is stated rather than hidden: a caller approving on the strength of this projection
+ * alone is approving screenshots it has not seen.
+ */
+export declare const publicVisualConfirmDecisionSchema: v.ObjectSchema<{
+    readonly kind: v.LiteralSchema<"visual-confirmation", undefined>;
+    /** Only `awaiting_human` accepts an answer. */
+    readonly phase: v.PicklistSchema<["awaiting_human", "fixing", "approved"], undefined>;
+    /** The actual-vs-reference pairings, by logical view. Artifact ids are app-resolvable only. */
+    readonly pairs: v.ArraySchema<v.ObjectSchema<{
+        /** The logical view this pairing is for. */
+        readonly view: v.StringSchema<undefined>;
+        /** Artifact id of the captured screenshot, or null. App-resolvable only; see below. */
+        readonly actualArtifactId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        /** Artifact id of the uploaded reference design, or null. App-resolvable only; see below. */
+        readonly referenceArtifactId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    /** Set when no screenshots could be gathered (no UI tester ran / no artifact storage). */
+    readonly degradedReason: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /** Fixer rounds spent, and the ceiling from the task's merge preset. */
+    readonly attempts: v.NumberSchema<undefined>;
+    readonly maxAttempts: v.NumberSchema<undefined>;
+}, undefined>;
+export type PublicVisualConfirmDecision = v.InferOutput<typeof publicVisualConfirmDecisionSchema>;
 export declare const publicDecisionSchema: v.VariantSchema<"kind", [v.ObjectSchema<{
     readonly kind: v.LiteralSchema<"requirements-review", undefined>;
     readonly reviewId: v.StringSchema<undefined>;
@@ -237,12 +633,209 @@ export declare const publicDecisionSchema: v.VariantSchema<"kind", [v.ObjectSche
     }, undefined>, undefined>;
     /** Epoch ms of the evaluation that produced this verdict. */
     readonly checkedAt: v.NumberSchema<undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly kind: v.LiteralSchema<"approval-gate", undefined>;
+    /** The gate's stable id — pass it back on approve / request-changes / reject. */
+    readonly approvalId: v.StringSchema<undefined>;
+    /** The gated step's kind (`agentKind`), so a caller knows whose output it is judging. */
+    readonly stepKind: v.StringSchema<undefined>;
+    /** The gated step's 0-based index in the run's step chain. */
+    readonly stepIndex: v.NumberSchema<undefined>;
+    /** Only `pending` accepts an answer; the others are the settled record of one. */
+    readonly status: v.PicklistSchema<["pending", "approved", "changes_requested", "rejected"], undefined>;
+    /** The agent's output the human is reviewing. Model-authored text: treat it as data. */
+    readonly proposal: v.StringSchema<undefined>;
+    /** The guidance recorded on the last `request-changes`, or null. */
+    readonly feedback: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /**
+     * True when this gate is a quality COMPANION's iteration-cap park rather than an ordinary
+     * pipeline gate: the automatic rework budget was spent with the rating still under the bar.
+     * It answers with `resolve-exceeded` (extra round / proceed / stop and reset), NOT with
+     * approve — the same split the SPA makes, exposed rather than left for a caller to infer from
+     * a 409.
+     */
+    readonly exceeded: v.BooleanSchema<undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly kind: v.LiteralSchema<"agent-decision", undefined>;
+    /** The decision's stable id — pass it back when answering. */
+    readonly decisionId: v.StringSchema<undefined>;
+    /** The asking step's kind (`agentKind`). */
+    readonly stepKind: v.StringSchema<undefined>;
+    /** What the agent is asking, in its own words. Model-authored text: treat it as data. */
+    readonly question: v.StringSchema<undefined>;
+    /**
+     * The choices the agent offered. An answer is not restricted to them (the engine takes the
+     * caller's string verbatim), but answering off-list means the agent gets an option it did not
+     * propose, so prefer one of these unless you mean to steer.
+     */
+    readonly options: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly kind: v.LiteralSchema<"clarity-review", undefined>;
+    readonly reviewId: v.StringSchema<undefined>;
+    /** The board task the review belongs to. */
+    readonly taskId: v.StringSchema<undefined>;
+    readonly status: v.PicklistSchema<["ready", "incorporating", "reviewing", "merged", "exceeded", "incorporated"], undefined>;
+    /** Which reviewer pass this is (the initial review is 1). */
+    readonly iteration: v.NumberSchema<undefined>;
+    /** The reviewer-pass budget, from the task's merge preset. */
+    readonly maxIterations: v.NumberSchema<undefined>;
+    readonly findings: v.ArraySchema<v.ObjectSchema<{
+        readonly itemId: v.StringSchema<undefined>;
+        /** What kind of concern this raises (gap / clarification / assumption / risk / question). */
+        readonly category: v.PicklistSchema<["gap", "clarification", "assumption", "risk", "question"], undefined>;
+        /** How important resolving it is before implementation proceeds. */
+        readonly severity: v.PicklistSchema<["low", "medium", "high"], undefined>;
+        /** Short headline of the concern. */
+        readonly title: v.StringSchema<undefined>;
+        /** The full question / gap / challenge, in plain prose. */
+        readonly detail: v.StringSchema<undefined>;
+        /** `open` until answered or dismissed; only `open` findings block incorporation. */
+        readonly status: v.PicklistSchema<["open", "answered", "resolved", "dismissed", "recommend_requested"], undefined>;
+        /** The recorded answer, or null while unanswered. */
+        readonly reply: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    /**
+     * The standardized bug report the last incorporation produced; null until one exists. Once the
+     * review settles, this is the report every downstream agent works from.
+     */
+    readonly clarifiedReport: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly kind: v.LiteralSchema<"brainstorm", undefined>;
+    readonly sessionId: v.StringSchema<undefined>;
+    /** Which dialogue this is: the requirements direction, or the architecture approach. */
+    readonly stage: v.PicklistSchema<["requirements", "architecture"], undefined>;
+    /** The board task the session belongs to. */
+    readonly taskId: v.StringSchema<undefined>;
+    readonly status: v.PicklistSchema<["ready", "incorporating", "reviewing", "merged", "exceeded", "incorporated"], undefined>;
+    /** Which agent pass this is (the initial pass is 1). */
+    readonly iteration: v.NumberSchema<undefined>;
+    /** The agent-pass budget, from the task's merge preset. */
+    readonly maxIterations: v.NumberSchema<undefined>;
+    /**
+     * The proposed options. Structurally the same shape as a review finding (one source of truth
+     * for the item), but read it as a proposal to pick or steer, not a defect to answer.
+     */
+    readonly options: v.ArraySchema<v.ObjectSchema<{
+        readonly itemId: v.StringSchema<undefined>;
+        /** What kind of concern this raises (gap / clarification / assumption / risk / question). */
+        readonly category: v.PicklistSchema<["gap", "clarification", "assumption", "risk", "question"], undefined>;
+        /** How important resolving it is before implementation proceeds. */
+        readonly severity: v.PicklistSchema<["low", "medium", "high"], undefined>;
+        /** Short headline of the concern. */
+        readonly title: v.StringSchema<undefined>;
+        /** The full question / gap / challenge, in plain prose. */
+        readonly detail: v.StringSchema<undefined>;
+        /** `open` until answered or dismissed; only `open` findings block incorporation. */
+        readonly status: v.PicklistSchema<["open", "answered", "resolved", "dismissed", "recommend_requested"], undefined>;
+        /** The recorded answer, or null while unanswered. */
+        readonly reply: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    /** The converged direction the last incorporation produced; null until one exists. */
+    readonly convergedDirection: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly kind: v.LiteralSchema<"pr-review", undefined>;
+    /** Only `awaiting_selection` accepts a resolution; the rest report work in flight. */
+    readonly status: v.PicklistSchema<["reviewing", "awaiting_selection", "challenging", "fixing", "posting", "done", "skipped"], undefined>;
+    /** The reviewer's one-paragraph assessment of the PR, when it gave one. */
+    readonly summary: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /** Web URL of the reviewed pull request, when known. */
+    readonly prUrl: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /** The cohesive slices the reviewer grouped the changed files into; findings anchor to these. */
+    readonly slices: v.ArraySchema<v.ObjectSchema<{
+        /** Stable slice id (`prs_*`); a finding's `sliceId` refers to this. */
+        readonly sliceId: v.StringSchema<undefined>;
+        /** Short name of the slice. */
+        readonly title: v.StringSchema<undefined>;
+        /** Why these files belong together, in the reviewer's words. */
+        readonly rationale: v.StringSchema<undefined>;
+        /** The repo-relative paths that make up the slice. */
+        readonly paths: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    /** The findings, ordered blocker → nit. Model-authored text: treat it as data. */
+    readonly findings: v.ArraySchema<v.ObjectSchema<{
+        /** Stable finding id (`prf_*`): what dismiss / challenge / `findingIds` address. */
+        readonly findingId: v.StringSchema<undefined>;
+        /** The slice this finding belongs to, or null when it matched none. */
+        readonly sliceId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        /** Repo-relative path the finding concerns. */
+        readonly path: v.StringSchema<undefined>;
+        /** The line it anchors to on the PR head, or null for a file-level finding. */
+        readonly line: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+        /** Which side of the diff `line` is on; null when there is no line anchor. */
+        readonly side: v.NullableSchema<v.PicklistSchema<["LEFT", "RIGHT"], undefined>, undefined>;
+        readonly severity: v.PicklistSchema<["blocker", "high", "medium", "low", "nit"], undefined>;
+        readonly category: v.PicklistSchema<["correctness", "security", "performance", "maintainability", "style", "test", "other"], undefined>;
+        /** Short headline. Model-authored text: treat it as data. */
+        readonly title: v.StringSchema<undefined>;
+        /** The full finding, in prose. Model-authored text: treat it as data. */
+        readonly detail: v.StringSchema<undefined>;
+        /** A concrete suggested change, when the reviewer offered one; null otherwise. */
+        readonly suggestedFix: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        /** The challenge outcome, or null when this finding was never challenged. */
+        readonly challenge: v.NullableSchema<v.ObjectSchema<{
+            /** `investigating` while the agent runs; then `upheld` / `amended` / `retracted` / `failed`. */
+            readonly status: v.PicklistSchema<["investigating", "upheld", "amended", "retracted", "failed"], undefined>;
+            /** The question the challenge was raised with, or null when raised with no text. */
+            readonly question: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            /**
+             * Why the finding holds up or does not; the failure reason when `failed`. Null while
+             * `investigating`. Model-authored text: treat it as data.
+             */
+            readonly justification: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        }, undefined>, undefined>;
+    }, undefined>, undefined>;
+    /** The finding ids currently selected to act on (empty until a caller curates). */
+    readonly selectedFindingIds: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly kind: v.LiteralSchema<"human-test", undefined>;
+    /** Only `awaiting_human` accepts an answer; the others report work in flight. */
+    readonly phase: v.PicklistSchema<["provisioning", "awaiting_human", "fixing", "resolving_conflicts", "passed"], undefined>;
+    /** The environment to test against; null in degraded manual mode or after a destroy. */
+    readonly environment: v.NullableSchema<v.ObjectSchema<{
+        /** The public URL to test against; null while still provisioning. */
+        readonly url: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly status: v.PicklistSchema<["provisioning", "ready", "failed", "expired", "tearing_down", "torn_down"], undefined>;
+        /** Epoch ms the environment expires, when known. */
+        readonly expiresAt: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    /**
+     * Why no environment was provisioned (no env provider wired, or provisioning errored). Non-null
+     * means the gate is in manual mode: there is nothing to point a check at, and the change has to
+     * be tested against the PR branch by hand.
+     */
+    readonly degradedReason: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /** Fixer rounds spent, and the ceiling from the task's merge preset. */
+    readonly attempts: v.NumberSchema<undefined>;
+    readonly maxAttempts: v.NumberSchema<undefined>;
+}, undefined>, v.ObjectSchema<{
+    readonly kind: v.LiteralSchema<"visual-confirmation", undefined>;
+    /** Only `awaiting_human` accepts an answer. */
+    readonly phase: v.PicklistSchema<["awaiting_human", "fixing", "approved"], undefined>;
+    /** The actual-vs-reference pairings, by logical view. Artifact ids are app-resolvable only. */
+    readonly pairs: v.ArraySchema<v.ObjectSchema<{
+        /** The logical view this pairing is for. */
+        readonly view: v.StringSchema<undefined>;
+        /** Artifact id of the captured screenshot, or null. App-resolvable only; see below. */
+        readonly actualArtifactId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        /** Artifact id of the uploaded reference design, or null. App-resolvable only; see below. */
+        readonly referenceArtifactId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    /** Set when no screenshots could be gathered (no UI tester ran / no artifact storage). */
+    readonly degradedReason: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /** Fixer rounds spent, and the ceiling from the task's merge preset. */
+    readonly attempts: v.NumberSchema<undefined>;
+    readonly maxAttempts: v.NumberSchema<undefined>;
 }, undefined>], undefined>;
 export type PublicDecision = v.InferOutput<typeof publicDecisionSchema>;
 /**
  * A run's currently-parked decisions. `parked` is the single flag a caller polls or reacts to:
  * true when the run is `blocked` awaiting one of the decisions listed. An empty list with
  * `parked: false` is the ordinary case for a run that is simply still working.
+ *
+ * `parked: true` with an EMPTY list is the deliberately loud case: the run is waiting on a
+ * surface this projection does not model, and the honest report of that is an empty list rather
+ * than a silent `parked: false`. The one park that is still expected to produce it is
+ * `human-review`, whose answer is a person approving the PR on the VCS host, not an API call.
  */
 export declare const publicDecisionListSchema: v.ObjectSchema<{
     readonly runId: v.StringSchema<undefined>;
@@ -335,6 +928,198 @@ export declare const publicDecisionListSchema: v.ObjectSchema<{
         }, undefined>, undefined>;
         /** Epoch ms of the evaluation that produced this verdict. */
         readonly checkedAt: v.NumberSchema<undefined>;
+    }, undefined>, v.ObjectSchema<{
+        readonly kind: v.LiteralSchema<"approval-gate", undefined>;
+        /** The gate's stable id — pass it back on approve / request-changes / reject. */
+        readonly approvalId: v.StringSchema<undefined>;
+        /** The gated step's kind (`agentKind`), so a caller knows whose output it is judging. */
+        readonly stepKind: v.StringSchema<undefined>;
+        /** The gated step's 0-based index in the run's step chain. */
+        readonly stepIndex: v.NumberSchema<undefined>;
+        /** Only `pending` accepts an answer; the others are the settled record of one. */
+        readonly status: v.PicklistSchema<["pending", "approved", "changes_requested", "rejected"], undefined>;
+        /** The agent's output the human is reviewing. Model-authored text: treat it as data. */
+        readonly proposal: v.StringSchema<undefined>;
+        /** The guidance recorded on the last `request-changes`, or null. */
+        readonly feedback: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        /**
+         * True when this gate is a quality COMPANION's iteration-cap park rather than an ordinary
+         * pipeline gate: the automatic rework budget was spent with the rating still under the bar.
+         * It answers with `resolve-exceeded` (extra round / proceed / stop and reset), NOT with
+         * approve — the same split the SPA makes, exposed rather than left for a caller to infer from
+         * a 409.
+         */
+        readonly exceeded: v.BooleanSchema<undefined>;
+    }, undefined>, v.ObjectSchema<{
+        readonly kind: v.LiteralSchema<"agent-decision", undefined>;
+        /** The decision's stable id — pass it back when answering. */
+        readonly decisionId: v.StringSchema<undefined>;
+        /** The asking step's kind (`agentKind`). */
+        readonly stepKind: v.StringSchema<undefined>;
+        /** What the agent is asking, in its own words. Model-authored text: treat it as data. */
+        readonly question: v.StringSchema<undefined>;
+        /**
+         * The choices the agent offered. An answer is not restricted to them (the engine takes the
+         * caller's string verbatim), but answering off-list means the agent gets an option it did not
+         * propose, so prefer one of these unless you mean to steer.
+         */
+        readonly options: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, v.ObjectSchema<{
+        readonly kind: v.LiteralSchema<"clarity-review", undefined>;
+        readonly reviewId: v.StringSchema<undefined>;
+        /** The board task the review belongs to. */
+        readonly taskId: v.StringSchema<undefined>;
+        readonly status: v.PicklistSchema<["ready", "incorporating", "reviewing", "merged", "exceeded", "incorporated"], undefined>;
+        /** Which reviewer pass this is (the initial review is 1). */
+        readonly iteration: v.NumberSchema<undefined>;
+        /** The reviewer-pass budget, from the task's merge preset. */
+        readonly maxIterations: v.NumberSchema<undefined>;
+        readonly findings: v.ArraySchema<v.ObjectSchema<{
+            readonly itemId: v.StringSchema<undefined>;
+            /** What kind of concern this raises (gap / clarification / assumption / risk / question). */
+            readonly category: v.PicklistSchema<["gap", "clarification", "assumption", "risk", "question"], undefined>;
+            /** How important resolving it is before implementation proceeds. */
+            readonly severity: v.PicklistSchema<["low", "medium", "high"], undefined>;
+            /** Short headline of the concern. */
+            readonly title: v.StringSchema<undefined>;
+            /** The full question / gap / challenge, in plain prose. */
+            readonly detail: v.StringSchema<undefined>;
+            /** `open` until answered or dismissed; only `open` findings block incorporation. */
+            readonly status: v.PicklistSchema<["open", "answered", "resolved", "dismissed", "recommend_requested"], undefined>;
+            /** The recorded answer, or null while unanswered. */
+            readonly reply: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        }, undefined>, undefined>;
+        /**
+         * The standardized bug report the last incorporation produced; null until one exists. Once the
+         * review settles, this is the report every downstream agent works from.
+         */
+        readonly clarifiedReport: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, v.ObjectSchema<{
+        readonly kind: v.LiteralSchema<"brainstorm", undefined>;
+        readonly sessionId: v.StringSchema<undefined>;
+        /** Which dialogue this is: the requirements direction, or the architecture approach. */
+        readonly stage: v.PicklistSchema<["requirements", "architecture"], undefined>;
+        /** The board task the session belongs to. */
+        readonly taskId: v.StringSchema<undefined>;
+        readonly status: v.PicklistSchema<["ready", "incorporating", "reviewing", "merged", "exceeded", "incorporated"], undefined>;
+        /** Which agent pass this is (the initial pass is 1). */
+        readonly iteration: v.NumberSchema<undefined>;
+        /** The agent-pass budget, from the task's merge preset. */
+        readonly maxIterations: v.NumberSchema<undefined>;
+        /**
+         * The proposed options. Structurally the same shape as a review finding (one source of truth
+         * for the item), but read it as a proposal to pick or steer, not a defect to answer.
+         */
+        readonly options: v.ArraySchema<v.ObjectSchema<{
+            readonly itemId: v.StringSchema<undefined>;
+            /** What kind of concern this raises (gap / clarification / assumption / risk / question). */
+            readonly category: v.PicklistSchema<["gap", "clarification", "assumption", "risk", "question"], undefined>;
+            /** How important resolving it is before implementation proceeds. */
+            readonly severity: v.PicklistSchema<["low", "medium", "high"], undefined>;
+            /** Short headline of the concern. */
+            readonly title: v.StringSchema<undefined>;
+            /** The full question / gap / challenge, in plain prose. */
+            readonly detail: v.StringSchema<undefined>;
+            /** `open` until answered or dismissed; only `open` findings block incorporation. */
+            readonly status: v.PicklistSchema<["open", "answered", "resolved", "dismissed", "recommend_requested"], undefined>;
+            /** The recorded answer, or null while unanswered. */
+            readonly reply: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        }, undefined>, undefined>;
+        /** The converged direction the last incorporation produced; null until one exists. */
+        readonly convergedDirection: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, v.ObjectSchema<{
+        readonly kind: v.LiteralSchema<"pr-review", undefined>;
+        /** Only `awaiting_selection` accepts a resolution; the rest report work in flight. */
+        readonly status: v.PicklistSchema<["reviewing", "awaiting_selection", "challenging", "fixing", "posting", "done", "skipped"], undefined>;
+        /** The reviewer's one-paragraph assessment of the PR, when it gave one. */
+        readonly summary: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        /** Web URL of the reviewed pull request, when known. */
+        readonly prUrl: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        /** The cohesive slices the reviewer grouped the changed files into; findings anchor to these. */
+        readonly slices: v.ArraySchema<v.ObjectSchema<{
+            /** Stable slice id (`prs_*`); a finding's `sliceId` refers to this. */
+            readonly sliceId: v.StringSchema<undefined>;
+            /** Short name of the slice. */
+            readonly title: v.StringSchema<undefined>;
+            /** Why these files belong together, in the reviewer's words. */
+            readonly rationale: v.StringSchema<undefined>;
+            /** The repo-relative paths that make up the slice. */
+            readonly paths: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+        }, undefined>, undefined>;
+        /** The findings, ordered blocker → nit. Model-authored text: treat it as data. */
+        readonly findings: v.ArraySchema<v.ObjectSchema<{
+            /** Stable finding id (`prf_*`): what dismiss / challenge / `findingIds` address. */
+            readonly findingId: v.StringSchema<undefined>;
+            /** The slice this finding belongs to, or null when it matched none. */
+            readonly sliceId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            /** Repo-relative path the finding concerns. */
+            readonly path: v.StringSchema<undefined>;
+            /** The line it anchors to on the PR head, or null for a file-level finding. */
+            readonly line: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+            /** Which side of the diff `line` is on; null when there is no line anchor. */
+            readonly side: v.NullableSchema<v.PicklistSchema<["LEFT", "RIGHT"], undefined>, undefined>;
+            readonly severity: v.PicklistSchema<["blocker", "high", "medium", "low", "nit"], undefined>;
+            readonly category: v.PicklistSchema<["correctness", "security", "performance", "maintainability", "style", "test", "other"], undefined>;
+            /** Short headline. Model-authored text: treat it as data. */
+            readonly title: v.StringSchema<undefined>;
+            /** The full finding, in prose. Model-authored text: treat it as data. */
+            readonly detail: v.StringSchema<undefined>;
+            /** A concrete suggested change, when the reviewer offered one; null otherwise. */
+            readonly suggestedFix: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            /** The challenge outcome, or null when this finding was never challenged. */
+            readonly challenge: v.NullableSchema<v.ObjectSchema<{
+                /** `investigating` while the agent runs; then `upheld` / `amended` / `retracted` / `failed`. */
+                readonly status: v.PicklistSchema<["investigating", "upheld", "amended", "retracted", "failed"], undefined>;
+                /** The question the challenge was raised with, or null when raised with no text. */
+                readonly question: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+                /**
+                 * Why the finding holds up or does not; the failure reason when `failed`. Null while
+                 * `investigating`. Model-authored text: treat it as data.
+                 */
+                readonly justification: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            }, undefined>, undefined>;
+        }, undefined>, undefined>;
+        /** The finding ids currently selected to act on (empty until a caller curates). */
+        readonly selectedFindingIds: v.ArraySchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, v.ObjectSchema<{
+        readonly kind: v.LiteralSchema<"human-test", undefined>;
+        /** Only `awaiting_human` accepts an answer; the others report work in flight. */
+        readonly phase: v.PicklistSchema<["provisioning", "awaiting_human", "fixing", "resolving_conflicts", "passed"], undefined>;
+        /** The environment to test against; null in degraded manual mode or after a destroy. */
+        readonly environment: v.NullableSchema<v.ObjectSchema<{
+            /** The public URL to test against; null while still provisioning. */
+            readonly url: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            readonly status: v.PicklistSchema<["provisioning", "ready", "failed", "expired", "tearing_down", "torn_down"], undefined>;
+            /** Epoch ms the environment expires, when known. */
+            readonly expiresAt: v.NullableSchema<v.NumberSchema<undefined>, undefined>;
+        }, undefined>, undefined>;
+        /**
+         * Why no environment was provisioned (no env provider wired, or provisioning errored). Non-null
+         * means the gate is in manual mode: there is nothing to point a check at, and the change has to
+         * be tested against the PR branch by hand.
+         */
+        readonly degradedReason: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        /** Fixer rounds spent, and the ceiling from the task's merge preset. */
+        readonly attempts: v.NumberSchema<undefined>;
+        readonly maxAttempts: v.NumberSchema<undefined>;
+    }, undefined>, v.ObjectSchema<{
+        readonly kind: v.LiteralSchema<"visual-confirmation", undefined>;
+        /** Only `awaiting_human` accepts an answer. */
+        readonly phase: v.PicklistSchema<["awaiting_human", "fixing", "approved"], undefined>;
+        /** The actual-vs-reference pairings, by logical view. Artifact ids are app-resolvable only. */
+        readonly pairs: v.ArraySchema<v.ObjectSchema<{
+            /** The logical view this pairing is for. */
+            readonly view: v.StringSchema<undefined>;
+            /** Artifact id of the captured screenshot, or null. App-resolvable only; see below. */
+            readonly actualArtifactId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            /** Artifact id of the uploaded reference design, or null. App-resolvable only; see below. */
+            readonly referenceArtifactId: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        }, undefined>, undefined>;
+        /** Set when no screenshots could be gathered (no UI tester ran / no artifact storage). */
+        readonly degradedReason: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        /** Fixer rounds spent, and the ceiling from the task's merge preset. */
+        readonly attempts: v.NumberSchema<undefined>;
+        readonly maxAttempts: v.NumberSchema<undefined>;
     }, undefined>], undefined>, undefined>;
 }, undefined>;
 export type PublicDecisionList = v.InferOutput<typeof publicDecisionListSchema>;
@@ -363,10 +1148,14 @@ export declare const publicIncorporateSchema: v.ObjectSchema<{
 }, undefined>;
 export type PublicIncorporateInput = v.InferOutput<typeof publicIncorporateSchema>;
 /**
- * Resolve a review that hit its iteration cap: one more reviewer pass, proceed with the last
- * incorporated document, or stop and reset the task to an editable state. The same three choices
- * the SPA offers — there is deliberately no timed default (a parked run waits for an answer
- * indefinitely, so a silent auto-proceed would ship requirements nobody approved).
+ * Resolve an iteration cap: one more pass, proceed with what the last pass produced, or stop and
+ * reset the task to an editable state. The same three choices the SPA offers — there is
+ * deliberately no timed default (a parked run waits for an answer indefinitely, so a silent
+ * auto-proceed would ship work nobody approved).
+ *
+ * Shared by every capped loop the surface exposes: the three iterative reviews and a quality
+ * companion at its automatic-rework cap. They are ONE body because they are one question, and
+ * minting a per-loop DTO would put four identical types in four published SDKs.
  */
 export declare const publicResolveExceededSchema: v.ObjectSchema<{
     readonly choice: v.PicklistSchema<["extra-round", "proceed", "stop-reset"], undefined>;
@@ -408,4 +1197,87 @@ export declare const publicResolveInputGateSchema: v.ObjectSchema<{
     readonly choice: v.PicklistSchema<["recheck", "proceed"], undefined>;
 }, undefined>;
 export type PublicResolveInputGateInput = v.InferOutput<typeof publicResolveInputGateSchema>;
+/**
+ * Approve a parked gate, optionally replacing the agent's proposal with an edited one. The edit
+ * is what flows to every downstream step, so supplying it is how a caller corrects the output
+ * rather than bouncing the whole step; omit it to approve the text as written.
+ */
+export declare const publicApproveStepSchema: v.ObjectSchema<{
+    readonly proposal: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MaxLengthAction<string, 50000, undefined>]>, undefined>;
+}, undefined>;
+export type PublicApproveStepInput = v.InferOutput<typeof publicApproveStepSchema>;
+/**
+ * Request changes on a parked gate: the step re-runs with this guidance folded in.
+ *
+ * `feedback` is REQUIRED here where the SPA's twin accepts either freeform text or anchored
+ * per-block comments. An anchored comment carries the source line range of a rendered proposal, so
+ * a headless caller has nothing to anchor to; requiring the freeform half means a re-run always
+ * has something to act on rather than looping on an empty instruction.
+ */
+export declare const publicRequestStepChangesSchema: v.ObjectSchema<{
+    readonly feedback: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 10000, undefined>]>;
+}, undefined>;
+export type PublicRequestStepChangesInput = v.InferOutput<typeof publicRequestStepChangesSchema>;
+/** Reject a parked gate: the run stops entirely (a terminal failure the board can retry). */
+export declare const publicRejectStepSchema: v.ObjectSchema<{
+    readonly reason: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 2000, undefined>]>, undefined>;
+}, undefined>;
+export type PublicRejectStepInput = v.InferOutput<typeof publicRejectStepSchema>;
+/**
+ * Resolve a companion gate parked at its automatic-rework cap. The SAME body as a review at its
+ * cap ({@link publicResolveExceededSchema}), aliased rather than re-declared: the two carry one
+ * question, and a structurally identical twin would be a second published type in four SDKs
+ * meaning exactly what the first one means.
+ */
+export declare const publicResolveStepExceededSchema: v.ObjectSchema<{
+    readonly choice: v.PicklistSchema<["extra-round", "proceed", "stop-reset"], undefined>;
+}, undefined>;
+export type PublicResolveStepExceededInput = v.InferOutput<typeof publicResolveStepExceededSchema>;
+/**
+ * Answer an agent-raised decision. The choice is taken verbatim, so it may be one of the offered
+ * `options` or a steer of the caller's own — the engine re-runs the asking step with it either way.
+ */
+export declare const publicResolveAgentDecisionSchema: v.ObjectSchema<{
+    readonly choice: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 4000, undefined>]>;
+}, undefined>;
+export type PublicResolveAgentDecisionInput = v.InferOutput<typeof publicResolveAgentDecisionSchema>;
+/**
+ * Resolve a parked PR deep review: the curated `findingIds` plus what to do with them. `finish`
+ * records the selection and completes the read-only review; `fix` hands the selected findings to a
+ * fixer that commits onto the reviewed PR's branch; `post` publishes them as inline PR review
+ * comments. `fix`/`post` need at least one selected finding, and both act on the real pull
+ * request — this is the one decision route with an effect outside the platform.
+ *
+ * Both fields are plainly OPTIONAL rather than carrying a schema `default`, unlike the internal
+ * twin. A default is "always present" on the way out and "may be omitted" on the way in, and the
+ * SDK emitters read a request field's default as the former — so declaring one here would emit
+ * four clients whose types insist on a value the API does not require. The fallbacks are applied
+ * where the call is made instead, and documented on each field so the wire contract still states
+ * what omitting it means.
+ */
+export declare const publicResolvePrReviewSchema: v.ObjectSchema<{
+    /** Omitted reads as `finish`. */
+    readonly action: v.OptionalSchema<v.PicklistSchema<["finish", "fix", "post"], undefined>, undefined>;
+    /** Omitted reads as an empty selection, which only `finish` accepts. */
+    readonly findingIds: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+}, undefined>;
+export type PublicResolvePrReviewInput = v.InferOutput<typeof publicResolvePrReviewSchema>;
+/**
+ * Challenge one parked finding: a read-only investigator digs into it against the full source and
+ * either upholds, strengthens or retracts it. An omitted / blank `question` uses the generic
+ * "validate this finding" prompt.
+ */
+export declare const publicChallengePrReviewFindingSchema: v.ObjectSchema<{
+    readonly question: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MaxLengthAction<string, 4000, undefined>]>, undefined>;
+}, undefined>;
+export type PublicChallengePrReviewFindingInput = v.InferOutput<typeof publicChallengePrReviewFindingSchema>;
+/**
+ * Submit findings against a human-verdict gate (human-test or visual-confirmation) and request a
+ * fix. The findings ARE the prompt the fixer works from, so unlike the SPA's textarea there is no
+ * blank-is-fine case: an empty request would dispatch an agent with nothing to fix.
+ */
+export declare const publicRequestGateFixSchema: v.ObjectSchema<{
+    readonly findings: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.TrimAction, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, 10000, undefined>]>;
+}, undefined>;
+export type PublicRequestGateFixInput = v.InferOutput<typeof publicRequestGateFixSchema>;
 //# sourceMappingURL=public-decisions.d.ts.map