@cat-factory/contracts 0.343.0 → 0.344.0

package/dist/agent-presentation.d.ts

@@ -100,7 +100,7 @@ export declare const agentPresentationSchema: v.ObjectSchema<{
      * to the deployment and paired on the frontend (an unpaired one degrades to the generic
      * panel — the `pairById` `missing` bucket). Omitted ⇒ the generic step-detail panel.
      */
-    readonly resultView: v.OptionalSchema<v.UnionSchema<[v.PicklistSchema<readonly ["outcome", "requirements-review", "clarity-review", "brainstorm", "tester", "human-test", "visual-confirm", "gate", "consensus-session", "generic-structured", "service-spec", "follow-ups", "merger", "initiative-tracker", "initiative-planning", "doc-interview", "fork-decision", "binary-candidates", "judge", "pr-review", "ralph-loop"], undefined>, v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "Consumer id must be <namespace>:<name> (lowercase a-z0-9, dash-separated)">]>], undefined>, undefined>;
+    readonly resultView: v.OptionalSchema<v.UnionSchema<[v.PicklistSchema<readonly ["outcome", "requirements-review", "clarity-review", "brainstorm", "tester", "human-test", "visual-confirm", "gate", "consensus-session", "generic-structured", "service-spec", "follow-ups", "merger", "initiative-tracker", "initiative-planning", "doc-interview", "fork-decision", "binary-candidates", "judge", "pr-review", "bug-fishing", "ralph-loop"], undefined>, v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "Consumer id must be <namespace>:<name> (lowercase a-z0-9, dash-separated)">]>], undefined>, undefined>;
     /**
      * When true the kind is INTERNAL: the platform dispatches it for a flow of its own and the
      * builder palette never offers it as a placeable block. The environment analyst is the model —
@@ -181,7 +181,7 @@ export declare const customAgentKindSchema: v.ObjectSchema<{
          * to the deployment and paired on the frontend (an unpaired one degrades to the generic
          * panel — the `pairById` `missing` bucket). Omitted ⇒ the generic step-detail panel.
          */
-        readonly resultView: v.OptionalSchema<v.UnionSchema<[v.PicklistSchema<readonly ["outcome", "requirements-review", "clarity-review", "brainstorm", "tester", "human-test", "visual-confirm", "gate", "consensus-session", "generic-structured", "service-spec", "follow-ups", "merger", "initiative-tracker", "initiative-planning", "doc-interview", "fork-decision", "binary-candidates", "judge", "pr-review", "ralph-loop"], undefined>, v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "Consumer id must be <namespace>:<name> (lowercase a-z0-9, dash-separated)">]>], undefined>, undefined>;
+        readonly resultView: v.OptionalSchema<v.UnionSchema<[v.PicklistSchema<readonly ["outcome", "requirements-review", "clarity-review", "brainstorm", "tester", "human-test", "visual-confirm", "gate", "consensus-session", "generic-structured", "service-spec", "follow-ups", "merger", "initiative-tracker", "initiative-planning", "doc-interview", "fork-decision", "binary-candidates", "judge", "pr-review", "bug-fishing", "ralph-loop"], undefined>, v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "Consumer id must be <namespace>:<name> (lowercase a-z0-9, dash-separated)">]>], undefined>, undefined>;
         /**
          * When true the kind is INTERNAL: the platform dispatches it for a flow of its own and the
          * builder palette never offers it as a placeable block. The environment analyst is the model —

package/dist/bugFishing.d.ts

@@ -0,0 +1,379 @@
+import * as v from 'valibot';
+/**
+ * The ANGLES an expedition fishes from, each one pass of the read-only agent over the
+ * codebase. They are deliberately disjoint LENSES rather than a difficulty ladder: one pass
+ * asked to find everything returns the shallow half of everything, whereas a pass told to
+ * think only about concurrency reads the same files with a question that makes the race
+ * visible.
+ *
+ * A PERSISTED closed vocabulary: a phase id is written onto the step's recorded phases and
+ * onto every finding, so a value retired here still comes back out of stored runs. Nothing
+ * renders a phase by looking its id up — {@link bugFishingPhaseSchema} carries the title and
+ * goal it ran under — and {@link describeBugFishingPhase} names an unrecognised id as retired
+ * rather than guessing at a current member or rendering `undefined`.
+ */
+export declare const BUG_FISHING_PHASE_IDS: readonly ['control-flow', 'error-handling', 'boundaries', 'concurrency', 'state-lifecycle', 'contracts', 'footguns', 'requirements'];
+export declare const bugFishingPhaseIdSchema: v.PicklistSchema<readonly ["control-flow", "error-handling", "boundaries", "concurrency", "state-lifecycle", "contracts", "footguns", "requirements"], undefined>;
+export type BugFishingPhaseId = v.InferOutput<typeof bugFishingPhaseIdSchema>;
+/** Whether `id` is a phase angle this build still ships. Derived from the picklist itself. */
+export declare function isBugFishingPhaseId(id: string): id is BugFishingPhaseId;
+/** What one angle is, and what the pass fishing it is told to look for. */
+export interface BugFishingPhaseDescriptor {
+    id: string;
+    /** Short human label (the window's phase header, the create form's checkbox). */
+    title: string;
+    /** One line saying what this pass is hunting — rendered to the human AND to the agent. */
+    goal: string;
+    /** The concrete prompt focus the agent is given for this pass. */
+    focus: string;
+    /** True for an id this build no longer ships (a stored run naming a retired angle). */
+    retired?: boolean;
+}
+/**
+ * The shipped angle catalog, in the order an expedition fishes them. Ordered so the angles
+ * that most often hide a real defect run first, because an expedition a human stops early has
+ * then still covered the ground worth covering.
+ */
+export declare const BUG_FISHING_PHASES: readonly BugFishingPhaseDescriptor[];
+/**
+ * The descriptor for a phase id, including one this build no longer ships.
+ *
+ * A retired angle is NAMED as retired rather than dropped or guessed onto a current member:
+ * stored runs keep the id they ran under, and the reader that hits it first is the window
+ * telling a human what an expedition actually covered. Answering `undefined` there would put
+ * an empty header over real findings.
+ */
+export declare function describeBugFishingPhase(id: string): BugFishingPhaseDescriptor;
+/** How serious a finding is, ordered critical → low. The window groups and colours by this. */
+export declare const bugFishingSeveritySchema: v.PicklistSchema<["critical", "high", "medium", "low"], undefined>;
+export type BugFishingSeverity = v.InferOutput<typeof bugFishingSeveritySchema>;
+/** Severity order (most severe first) — the one place the ranking is stated. */
+export declare const BUG_FISHING_SEVERITY_ORDER: readonly BugFishingSeverity[];
+/**
+ * What KIND of defect a finding is. Distinct from severity: an expedition is explicitly
+ * fishing for more than crashes, and a `footgun` that will cost a week next quarter is a
+ * different decision from an `edge-case` that fires today.
+ */
+export declare const bugFishingFindingKindSchema: v.PicklistSchema<["bug", "logic-gap", "edge-case", "footgun", "requirement-gap", "other"], undefined>;
+export type BugFishingFindingKind = v.InferOutput<typeof bugFishingFindingKindSchema>;
+/** How sure the agent is that the finding is real — its own judgement, never platform-derived. */
+export declare const bugFishingConfidenceSchema: v.PicklistSchema<["high", "medium", "low"], undefined>;
+export type BugFishingConfidence = v.InferOutput<typeof bugFishingConfidenceSchema>;
+/** A phase's lifecycle across the expedition's successive dispatches. */
+export declare const bugFishingPhaseStatusSchema: v.PicklistSchema<["pending", "fishing", "completed", "failed"], undefined>;
+export type BugFishingPhaseStatus = v.InferOutput<typeof bugFishingPhaseStatusSchema>;
+/**
+ * One planned angle of the expedition, as recorded on the step.
+ *
+ * `title` and `goal` are COPIED from the catalog when the expedition is planned rather than
+ * looked up at render time, so a run keeps naming the angle it actually fished even after that
+ * angle is retired or reworded.
+ */
+export declare const bugFishingPhaseSchema: v.ObjectSchema<{
+    /** The angle's id (a {@link BUG_FISHING_PHASE_IDS} member when it was planned). */
+    readonly id: v.StringSchema<undefined>;
+    /** The angle's label as it stood when this expedition planned it. */
+    readonly title: v.StringSchema<undefined>;
+    /** What this pass was told to hunt, as it stood when this expedition planned it. */
+    readonly goal: v.StringSchema<undefined>;
+    readonly status: v.PicklistSchema<["pending", "fishing", "completed", "failed"], undefined>;
+    /** The agent's one-paragraph account of what it covered; null until the pass settles. */
+    readonly summary: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+    /** Epoch ms the pass settled (completed or failed); null while pending / fishing. */
+    readonly settledAt: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, undefined>;
+    /** Why the pass failed, when it did. Null otherwise. */
+    readonly failureReason: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+}, undefined>;
+export type BugFishingPhase = v.InferOutput<typeof bugFishingPhaseSchema>;
+/**
+ * How far a marked finding's spawn has got.
+ *
+ * - `pending`: the CLAIM. Written BEFORE the task exists, which is what makes marking safe
+ *   against two people (or a retried request) marking one finding at the same time: the second
+ *   claim finds the first and is refused, rather than both creating a task and a run.
+ * - `spawned`: terminal. The task exists and its run was started.
+ * - `failed`: the claim was taken and the work behind it did not land, carrying the cause. The
+ *   finding is markable again, because nothing was created for it.
+ */
+export declare const bugFishingSpawnStatusSchema: v.PicklistSchema<["pending", "spawned", "failed"], undefined>;
+export type BugFishingSpawnStatus = v.InferOutput<typeof bugFishingSpawnStatusSchema>;
+/**
+ * The record of a finding a human MARKED to be addressed: the bug-fix task the platform
+ * spawned for it, and the pipeline that task runs.
+ *
+ * It is what links the expedition to the work it caused: the window reads the spawned task's
+ * live status through it, and the spawned block carries the expedition's own block id back the
+ * other way (`Block.expeditionId`).
+ *
+ * Written TWICE, and the first write is the point. A spawn creates a board task and starts a run,
+ * so it is an external side effect in a path two callers can enter at once; the record is
+ * therefore taken as a `pending` CLAIM before any of that happens and settled to `spawned` or
+ * `failed` after. Reading it as "there is a fix task" means reading {@link
+ * bugFishingSpawnStatusSchema}, never merely the presence of this record.
+ */
+export declare const bugFishingSpawnSchema: v.ObjectSchema<{
+    /** How far the spawn has got; see {@link bugFishingSpawnStatusSchema}. */
+    readonly status: v.PicklistSchema<["pending", "spawned", "failed"], undefined>;
+    /** The spawned task block's id, minted with the claim so the claimer can recognise its own. */
+    readonly taskId: v.StringSchema<undefined>;
+    /**
+     * The run started on the task. Null while the claim is `pending`, and on a `spawned` record
+     * whose task was created but whose run reported no id.
+     */
+    readonly executionId: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+    /** The pipeline the spawned task runs (the resolved default, or the caller's override). */
+    readonly pipelineId: v.StringSchema<undefined>;
+    /** Who marked the finding. Null for a system-initiated marking. */
+    readonly requestedBy: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+    /** Epoch ms the claim was taken. */
+    readonly requestedAt: v.NumberSchema<undefined>;
+    /** Why the spawn failed, on a `failed` record. Null otherwise. */
+    readonly failureReason: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+}, undefined>;
+export type BugFishingSpawn = v.InferOutput<typeof bugFishingSpawnSchema>;
+/**
+ * How long a `pending` spawn claim holds a finding before another marking may take it.
+ *
+ * The claim is held across a board insert and a run start, so it is normally seconds. The window
+ * exists for the one case the claimer cannot clean up after itself: a process killed between
+ * taking the claim and settling it, which would otherwise leave the finding claimed by nobody,
+ * forever, with no fix task to show for it. Generous enough that it can never expire under a
+ * merely slow start, which would be exactly the double spawn the claim exists to prevent.
+ */
+export declare const BUG_FISHING_SPAWN_CLAIM_TTL_MS: number;
+/**
+ * Whether a finding is still OPEN: nothing is being done about it, so it may be marked (or
+ * dismissed) right now.
+ *
+ * Here rather than in the engine because both sides have to agree about it and neither owns the
+ * answer: the engine refuses a second marking with it, and the window counts "N left to triage"
+ * and decides which rows the working list shows with it. Stated once, the two cannot drift into
+ * a window that offers a mark the engine will refuse.
+ *
+ * Three ways to be open: nothing has been claimed, the last attempt `failed` (nothing was created,
+ * so there is nothing to collide with), or a `pending` claim has outlived
+ * {@link BUG_FISHING_SPAWN_CLAIM_TTL_MS} and its claimer is gone. A `spawned` record is terminal:
+ * the task exists, and marking again would file the same bug twice.
+ */
+export declare function bugFishingSpawnIsClaimable(spawn: BugFishingSpawn | null | undefined, now: number): boolean;
+/**
+ * One finding, id-stamped by the engine and anchored to the phase that surfaced it.
+ *
+ * `evidence` is kept apart from `detail` on purpose: an expedition that cannot point at the
+ * code it is describing is speculating, and separating the two makes that visible to the human
+ * triaging it rather than something they have to infer from the prose.
+ */
+export declare const bugFishingFindingSchema: v.ObjectSchema<{
+    /** Engine-minted stable id (`bff_*`); the marking requests carry these ids. */
+    readonly id: v.StringSchema<undefined>;
+    /** The phase that surfaced it (a phase id; see {@link describeBugFishingPhase}). */
+    readonly phaseId: v.StringSchema<undefined>;
+    /** Repo-relative path the finding concerns; empty when it is not anchored to one file. */
+    readonly path: v.StringSchema<undefined>;
+    /** The line the finding anchors to, or null. */
+    readonly line: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, undefined>;
+    readonly severity: v.PicklistSchema<["critical", "high", "medium", "low"], undefined>;
+    readonly kind: v.PicklistSchema<["bug", "logic-gap", "edge-case", "footgun", "requirement-gap", "other"], undefined>;
+    readonly confidence: v.PicklistSchema<["high", "medium", "low"], undefined>;
+    /** Short headline. */
+    readonly title: v.StringSchema<undefined>;
+    /** The full finding, in prose: what is wrong and what happens because of it. */
+    readonly detail: v.StringSchema<undefined>;
+    /** How the defect manifests: the concrete inputs / interleaving / state that triggers it. */
+    readonly failureScenario: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+    /** What the agent actually read that supports the claim (code it can point at). */
+    readonly evidence: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+    /** A concrete suggested change, when the agent offered one. */
+    readonly suggestedFix: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+    /**
+     * The bug-fix task spawned for this finding, when a human marked it. Null when nobody has.
+     * A record with a `failed` status is a mark that did not land: the finding is markable again,
+     * so a reader deciding whether this finding is being worked on reads the STATUS, not the
+     * presence of the record.
+     */
+    readonly spawn: v.OptionalSchema<v.NullableSchema<v.ObjectSchema<{
+        /** How far the spawn has got; see {@link bugFishingSpawnStatusSchema}. */
+        readonly status: v.PicklistSchema<["pending", "spawned", "failed"], undefined>;
+        /** The spawned task block's id, minted with the claim so the claimer can recognise its own. */
+        readonly taskId: v.StringSchema<undefined>;
+        /**
+         * The run started on the task. Null while the claim is `pending`, and on a `spawned` record
+         * whose task was created but whose run reported no id.
+         */
+        readonly executionId: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+        /** The pipeline the spawned task runs (the resolved default, or the caller's override). */
+        readonly pipelineId: v.StringSchema<undefined>;
+        /** Who marked the finding. Null for a system-initiated marking. */
+        readonly requestedBy: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+        /** Epoch ms the claim was taken. */
+        readonly requestedAt: v.NumberSchema<undefined>;
+        /** Why the spawn failed, on a `failed` record. Null otherwise. */
+        readonly failureReason: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+    }, undefined>, undefined>, undefined>;
+    /** Set when a human dismissed the finding: it stays on the record, struck through. */
+    readonly dismissed: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
+}, undefined>;
+export type BugFishingFinding = v.InferOutput<typeof bugFishingFindingSchema>;
+/**
+ * The expedition lifecycle on a `bug-fisher` step:
+ * - `fishing`: a phase's read-only container job is in flight (or the next one is about to be).
+ * - `awaiting_triage`: every phase settled; parked for the human to finish triaging.
+ * - `done`: the human finished the expedition (the run advances past it).
+ *
+ * There is deliberately no `skipped`: an expedition with no angles cannot be asked for, because
+ * an empty selection means "fish every angle" (see `planBugFishingPhases`).
+ *
+ * There is deliberately no `triaging` state: marking a finding is available from the moment
+ * its phase lands, INCLUDING while later phases are still fishing, which is the whole reason
+ * the angles run as separate passes.
+ */
+export declare const bugFishingStatusSchema: v.PicklistSchema<["fishing", "awaiting_triage", "done"], undefined>;
+export type BugFishingStatus = v.InferOutput<typeof bugFishingStatusSchema>;
+/**
+ * Live bug-fishing state carried on the run's `bug-fisher` step. Created by the engine when
+ * the step first runs (planning the phases from the task's selection), extended by each
+ * phase's completion, and mutated by the human's markings.
+ */
+export declare const bugFishingStepStateSchema: v.ObjectSchema<{
+    readonly status: v.PicklistSchema<["fishing", "awaiting_triage", "done"], undefined>;
+    /** The planned angles, in the order they are fished. */
+    readonly phases: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+        /** The angle's id (a {@link BUG_FISHING_PHASE_IDS} member when it was planned). */
+        readonly id: v.StringSchema<undefined>;
+        /** The angle's label as it stood when this expedition planned it. */
+        readonly title: v.StringSchema<undefined>;
+        /** What this pass was told to hunt, as it stood when this expedition planned it. */
+        readonly goal: v.StringSchema<undefined>;
+        readonly status: v.PicklistSchema<["pending", "fishing", "completed", "failed"], undefined>;
+        /** The agent's one-paragraph account of what it covered; null until the pass settles. */
+        readonly summary: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+        /** Epoch ms the pass settled (completed or failed); null while pending / fishing. */
+        readonly settledAt: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, undefined>;
+        /** Why the pass failed, when it did. Null otherwise. */
+        readonly failureReason: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+    }, undefined>, undefined>, readonly []>;
+    /**
+     * Index into {@link bugFishingStepStateSchema}'s `phases` of the pass currently being fished
+     * (or about to be). Equal to `phases.length` once every angle has settled, which is what the
+     * `awaiting_triage` status says in the other direction; an index rather than a pointer so an
+     * empty phase list still has an unambiguous value.
+     */
+    readonly currentPhaseIndex: v.OptionalSchema<v.NumberSchema<undefined>, 0>;
+    /** Every finding surfaced so far, oldest phase first, severity-ordered within a phase. */
+    readonly findings: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
+        /** Engine-minted stable id (`bff_*`); the marking requests carry these ids. */
+        readonly id: v.StringSchema<undefined>;
+        /** The phase that surfaced it (a phase id; see {@link describeBugFishingPhase}). */
+        readonly phaseId: v.StringSchema<undefined>;
+        /** Repo-relative path the finding concerns; empty when it is not anchored to one file. */
+        readonly path: v.StringSchema<undefined>;
+        /** The line the finding anchors to, or null. */
+        readonly line: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, undefined>;
+        readonly severity: v.PicklistSchema<["critical", "high", "medium", "low"], undefined>;
+        readonly kind: v.PicklistSchema<["bug", "logic-gap", "edge-case", "footgun", "requirement-gap", "other"], undefined>;
+        readonly confidence: v.PicklistSchema<["high", "medium", "low"], undefined>;
+        /** Short headline. */
+        readonly title: v.StringSchema<undefined>;
+        /** The full finding, in prose: what is wrong and what happens because of it. */
+        readonly detail: v.StringSchema<undefined>;
+        /** How the defect manifests: the concrete inputs / interleaving / state that triggers it. */
+        readonly failureScenario: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+        /** What the agent actually read that supports the claim (code it can point at). */
+        readonly evidence: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+        /** A concrete suggested change, when the agent offered one. */
+        readonly suggestedFix: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+        /**
+         * The bug-fix task spawned for this finding, when a human marked it. Null when nobody has.
+         * A record with a `failed` status is a mark that did not land: the finding is markable again,
+         * so a reader deciding whether this finding is being worked on reads the STATUS, not the
+         * presence of the record.
+         */
+        readonly spawn: v.OptionalSchema<v.NullableSchema<v.ObjectSchema<{
+            /** How far the spawn has got; see {@link bugFishingSpawnStatusSchema}. */
+            readonly status: v.PicklistSchema<["pending", "spawned", "failed"], undefined>;
+            /** The spawned task block's id, minted with the claim so the claimer can recognise its own. */
+            readonly taskId: v.StringSchema<undefined>;
+            /**
+             * The run started on the task. Null while the claim is `pending`, and on a `spawned` record
+             * whose task was created but whose run reported no id.
+             */
+            readonly executionId: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+            /** The pipeline the spawned task runs (the resolved default, or the caller's override). */
+            readonly pipelineId: v.StringSchema<undefined>;
+            /** Who marked the finding. Null for a system-initiated marking. */
+            readonly requestedBy: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+            /** Epoch ms the claim was taken. */
+            readonly requestedAt: v.NumberSchema<undefined>;
+            /** Why the spawn failed, on a `failed` record. Null otherwise. */
+            readonly failureReason: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+        }, undefined>, undefined>, undefined>;
+        /** Set when a human dismissed the finding: it stays on the record, struck through. */
+        readonly dismissed: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
+    }, undefined>, undefined>, readonly []>;
+    /** Identifier of the model that fished, for transparency. */
+    readonly model: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+    /**
+     * The pipeline a marked finding's spawned task runs when the marking names none: the
+     * workspace's `bugFishingFixPipelineId`, else the built-in bug-fix preset. Resolved when the
+     * expedition is planned and recorded here, so the window can state the default it will use
+     * without a second read and the record says which default a spawn actually took.
+     */
+    readonly defaultFixPipelineId: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
+}, undefined>;
+export type BugFishingStepState = v.InferOutput<typeof bugFishingStepStateSchema>;
+/**
+ * The LENIENT structured shape the read-only `bug-fisher` container agent returns as
+ * `result.custom` for ONE phase (the engine mints the finding ids and stamps the phase).
+ * Every field falls back to a safe default (`v.fallback`) — exactly like
+ * `prReviewAgentOutputSchema` — so a partially-malformed reply degrades sensibly rather than
+ * failing a pass whose other findings are fine.
+ */
+export declare const bugFishingAgentOutputSchema: v.ObjectSchema<{
+    /** What this pass covered and what it concluded, in one paragraph. */
+    readonly summary: v.SchemaWithFallback<v.OptionalSchema<v.StringSchema<undefined>, undefined>, undefined>;
+    /** The findings this pass surfaced. */
+    readonly findings: v.SchemaWithFallback<v.ArraySchema<v.SchemaWithFallback<v.ObjectSchema<{
+        readonly path: v.SchemaWithFallback<v.StringSchema<undefined>, "">;
+        readonly line: v.SchemaWithFallback<v.OptionalSchema<v.NumberSchema<undefined>, undefined>, undefined>;
+        readonly severity: v.SchemaWithFallback<v.PicklistSchema<["critical", "high", "medium", "low"], undefined>, "medium">;
+        readonly kind: v.SchemaWithFallback<v.PicklistSchema<["bug", "logic-gap", "edge-case", "footgun", "requirement-gap", "other"], undefined>, "other">;
+        readonly confidence: v.SchemaWithFallback<v.PicklistSchema<["high", "medium", "low"], undefined>, "medium">;
+        readonly title: v.SchemaWithFallback<v.StringSchema<undefined>, "">;
+        readonly detail: v.SchemaWithFallback<v.StringSchema<undefined>, "">;
+        readonly failureScenario: v.SchemaWithFallback<v.OptionalSchema<v.StringSchema<undefined>, undefined>, undefined>;
+        readonly evidence: v.SchemaWithFallback<v.OptionalSchema<v.StringSchema<undefined>, undefined>, undefined>;
+        readonly suggestedFix: v.SchemaWithFallback<v.OptionalSchema<v.StringSchema<undefined>, undefined>, undefined>;
+    }, undefined>, {
+        readonly path: "";
+        readonly severity: 'medium';
+        readonly kind: 'other';
+        readonly confidence: 'medium';
+        readonly title: "";
+        readonly detail: "";
+    }>, undefined>, readonly []>;
+}, undefined>;
+export type BugFishingAgentOutput = v.InferOutput<typeof bugFishingAgentOutputSchema>;
+/**
+ * Mark findings to be addressed: each one spawns its OWN bug-fix task, linked back to the
+ * expedition. Accepted while the expedition is still fishing later phases as well as once it
+ * has parked, because a completed phase's findings are actionable the moment they land.
+ *
+ * `pipelineId` overrides, for THIS request only, the pipeline the spawned tasks run; omitted
+ * ⇒ the expedition's resolved default (the workspace's `bugFishingFixPipelineId`, else the
+ * built-in bug-fix preset).
+ */
+export declare const addressBugFishingFindingsSchema: v.ObjectSchema<{
+    /** The findings to act on. At least one; an unknown or already-spawned id is refused. */
+    readonly findingIds: v.SchemaWithPipe<readonly [v.ArraySchema<v.StringSchema<undefined>, undefined>, v.MinLengthAction<string[], 1, undefined>]>;
+    /** Pipeline the spawned tasks run; omitted ⇒ the expedition's default. */
+    readonly pipelineId: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+export type AddressBugFishingFindingsInput = v.InferOutput<typeof addressBugFishingFindingsSchema>;
+/**
+ * Finish a parked expedition: the human is done triaging and the run advances past the step.
+ * Takes no fields — every marking already happened through its own request, so there is no
+ * curated selection left to carry here.
+ */
+export declare const resolveBugFishingSchema: v.ObjectSchema<{}, undefined>;
+export type ResolveBugFishingInput = v.InferOutput<typeof resolveBugFishingSchema>;
+//# sourceMappingURL=bugFishing.d.ts.map

package/dist/bugFishing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bugFishing.d.ts","sourceRoot":"","sources":["../src/bugFishing.ts"],"names":[],"mappings":"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"}