@codeam/shared 2.75.7 → 2.75.9

package/dist/index.d.mts

@@ -948,6 +948,13 @@ interface PackStageDef {
      * 2026-08-08 — a clean Reviewer was mis-treated as "stage produced no commit".)
      */
     requiresCommit?: boolean;
+    /**
+     * Whether this stage is expected to leave a structured findings file
+     * (`PACK_FINDINGS_FILE`) at the repo root, which the runner parses into
+     * `PackHandoffRecord.findings` so the NEXT stage consumes an explicit list
+     * instead of re-deriving it from prose. Review-style stages set this.
+     */
+    producesFindings?: boolean;
 }
 interface PackDefinition {
     id: PackId;
@@ -960,11 +967,44 @@ interface PackDefinition {
 }
 type PackRunStatus = 'running' | 'paused' | 'stalled' | 'completed' | 'aborted' | 'failed';
 type PackStageStatus = 'pending' | 'active' | 'done' | 'failed' | 'skipped';
+type PackFindingSeverity = 'blocker' | 'major' | 'minor' | 'nit';
+type PackFindingResolution = 'fixed' | 'deferred' | 'wont_fix' | 'needs_verification';
+/**
+ * One review finding, machine-readable. A review-style stage writes a list of
+ * these to `PACK_FINDINGS_FILE` (repo root, committed with the stage — the
+ * same rail as `SPEC.pack.md`); the runner parses the file into the stage's
+ * handoff so the next stage gets an explicit list to verify one by one, and
+ * every finding either receives a verdict downstream or is visibly open.
+ */
+interface PackFinding {
+    /** Stable short id the next stage references (e.g. `R1`). */
+    id: string;
+    severity: PackFindingSeverity;
+    /** One line: what is wrong. */
+    title: string;
+    /** Why it matters / what was done, a few lines at most. */
+    detail?: string;
+    /** Repo-relative path, when the finding points at code. */
+    file?: string;
+    line?: number;
+    resolution: PackFindingResolution;
+    /** Commit that resolves it, when `resolution === 'fixed'` (model-claimed; the
+     *  stage's git-validated handoff commit is the authority). */
+    commit?: string;
+}
+/** Repo-root file a `producesFindings` stage writes. Root, NOT `.codeam/` — the
+ *  workflow article forbids agents from touching the pipeline ledger. */
+declare const PACK_FINDINGS_FILE = "REVIEW-FINDINGS.pack.json";
+/** Upper bound on parsed findings — a runaway list is truncated, not rejected. */
+declare const MAX_PACK_FINDINGS = 50;
+/** Heading every stage closes its reply with; the runner lifts the section
+ *  below it as the handoff summary instead of the reply's raw tail. */
+declare const PACK_HANDOFF_HEADING = "## Handoff";
 /** Mechanically captured proof of what a stage delivered. */
 interface PackHandoffRecord {
     /** Canonical 10-hex commit abbreviation (git-validated, never model-claimed). */
     commit: string;
-    /** Short summary of the stage's reply (first lines, capped). */
+    /** The reply's `## Handoff` section when present, else its tail (capped). */
     summary: string;
     /** `git diff --stat` summary line between the stage's start and end commits. */
     diffStat: string;
@@ -975,6 +1015,12 @@ interface PackHandoffRecord {
         tail: string;
     };
     durationMs: number;
+    /** Parsed `PACK_FINDINGS_FILE` for a `producesFindings` stage. Absent when
+     *  the stage does not produce findings; empty when it audited and found none. */
+    findings?: PackFinding[];
+    /** Why `findings` is absent/partial on a `producesFindings` stage (no file,
+     *  malformed JSON, truncated) or what an empty list checked — always honest. */
+    findingsNote?: string;
 }
 interface PackStageState {
     role: string;
@@ -985,7 +1031,21 @@ interface PackStageState {
     handoff?: PackHandoffRecord;
     /** Populated when status === 'failed' (or the run stalled on this stage). */
     error?: string;
-}
+    /**
+     * The stage's turn ended with a question for the user (a select prompt the
+     * app renders). The run is paused, NOT nudged — the user answers in the
+     * stage chat and taps Resume, which re-checks the stage's commit gate in the
+     * SAME conversation instead of starting a fresh one.
+     */
+    awaitingUser?: boolean;
+    /** How many fresh conversations this stage has had (1 = first attempt). */
+    attempts?: number;
+    /** Canonical HEAD when the stage's current attempt began — the diff base for
+     *  its handoff, kept stable across an in-place resume. */
+    startCommit?: string;
+}
+/** A control the user asked for mid-turn; it takes effect at the stage boundary. */
+type PackPendingControl = 'pause' | 'abort';
 interface PackRunState {
     runId: string;
     packId: PackId;
@@ -995,8 +1055,14 @@ interface PackRunState {
     /** Index into `stages` of the stage currently active/next. */
     currentStage: number;
     stages: PackStageState[];
-    /** Set when status is 'stalled' | 'failed' — the honest reason. */
+    /** Set when status is 'stalled' | 'failed' | 'paused' with a cause — the honest reason. */
     stalledReason?: string;
+    /** Canonical HEAD before the pipeline's first stage — every stage gets it so
+     *  "the pipeline's diff" is `git diff <baseCommit>..HEAD`, never a guess. */
+    baseCommit?: string;
+    /** Set while a pause/abort requested mid-turn waits for the stage boundary;
+     *  the UI shows "pausing after this stage" instead of a false PAUSED. */
+    pendingControl?: PackPendingControl;
     startedAt: string;
     updatedAt: string;
 }
@@ -1031,10 +1097,10 @@ declare function getPackDefinition(id: string): PackDefinition | null;
  * (PACK_WORKFLOW_ARTICLE) and the task + previous handoff are appended by the
  * runner at stage start.
  */
-declare const SPECIFIER_PROMPT = "# Role: Specifier\n\nYou turn the user's task into a precise, testable specification the rest of the pipeline implements against. You do NOT write implementation code.\n\nMethod:\n1. Read the task and explore the relevant parts of the codebase until you understand the real problem, the desired outcome, and the constraints the code imposes.\n2. Write the specification to `SPEC.pack.md` at the repo root:\n   - **Problem** \u2014 what is wrong or missing, and for whom.\n   - **Outcome** \u2014 what must be true when this is done.\n   - **Acceptance criteria** \u2014 a numbered checklist of observable, testable conditions. Each criterion must be verifiable by a test or a concrete manual check. They must fully cover the outcome.\n   - **Out of scope** \u2014 what this task deliberately does not touch.\n   - **Verification plan** \u2014 for each criterion, the level that proves it (unit / integration / manual) and why.\n3. Right-size: if the task is clearly too large for one pipeline run, narrow the criteria to a coherent first slice and record the rest under \"Out of scope / next\".\n\nHandoff bar: the spec file is committed; every acceptance criterion is testable as written; a competent implementer could start without asking you anything.";
-declare const CODER_PROMPT = "# Role: Coder\n\nYou implement the task with test-driven discipline. You are the only stage that adds behavior.\n\nMethod:\n1. Read the task \u2014 and `SPEC.pack.md` if a Specifier stage produced one; its acceptance criteria are your contract. Without a spec, derive the minimal criteria from the task itself before coding.\n2. Test-first where it fits: write the test that proves a criterion, watch it fail, implement until it passes. Where strict test-first doesn't fit, still land tests alongside the change.\n3. Match the project's existing style, structure, and conventions. Simplest design that fully solves the problem \u2014 no speculative abstractions, no \"while I'm here\" changes.\n4. Run the project's tests / linters / build and make them pass.\n\nHandoff bar: every acceptance criterion is implemented and covered by a test; the project's checks pass; the work is committed in focused commits.";
-declare const REVIEWER_PROMPT = "# Role: Reviewer\n\nYou are a skeptical senior reviewer with fresh eyes \u2014 you did NOT write this code, and your job is to find what's wrong, not to approve it. You also own architectural cleanliness for this change.\n\nMethod:\n1. Read the task, `SPEC.pack.md` (when present), and the diff of the pipeline's commits (`git log` + `git diff` against the state before the pipeline's first commit). Read enough surrounding code to judge in context.\n2. Audit, in priority order:\n   - **Correctness** \u2014 logic, edge cases, error paths. For each acceptance criterion: point to the test that proves it, and check the test would FAIL if the behavior broke.\n   - **Scope** \u2014 anything beyond the task is flagged and reverted unless it is load-bearing.\n   - **Design** \u2014 duplication, dead code, needless complexity, dependency direction, encapsulation. Verify every API/library call actually exists in the project's dependencies.\n   - **Conventions & naming** \u2014 matches the surrounding code; names say what things are.\n   - **Safety** \u2014 no secrets, credentials, or debugging remnants in code, tests, or fixtures.\n3. Fix what is justified \u2014 smallest change that resolves the finding, keeping behavior. Re-run the checks after material fixes.\n4. Record your findings honestly in your closing summary: what you found, what you fixed, what you deliberately left, and what you could not verify.\n\nHandoff bar: checks pass on YOUR final commit; every fix is committed; your summary lists findings \u2192 resolutions (an empty findings list must say what you checked).";
-declare const QA_PROMPT = "# Role: QA\n\nYou are the final gate. You verify the delivered work against the acceptance criteria as a whole \u2014 end to end, the way a demanding user would \u2014 and produce the run's closing report.\n\nMethod:\n1. Read the task and `SPEC.pack.md` (when present). Your contract is the acceptance criteria; without a spec, derive them from the task.\n2. For EACH criterion, verify it against the real project: run the relevant tests, execute the code paths where feasible, inspect actual behavior/output. Do not take earlier stages' word for anything.\n3. Run the project's full checks (tests, lint, types, build) one final time.\n4. Write `QA-REPORT.pack.md` at the repo root: per-criterion verdict (\u2705 verified / \u26A0\uFE0F partially / \u274C failed \u2014 with evidence for each), the checks' results, anything not verifiable in this environment (stated plainly), and a short \"ready to ship?\" conclusion.\n5. If a criterion FAILS: fix it only when the fix is small and unambiguous; otherwise mark it failed with exact evidence \u2014 the user decides. Never paper over a failure.\n\nHandoff bar: the report is committed; every verdict carries evidence; the conclusion is honest about anything unverified.";
+declare const SPECIFIER_PROMPT = "# Role: Specifier\n\nYou turn the user's task into a precise, testable specification the rest of the pipeline implements against. You do NOT write implementation code.\n\nMethod:\n1. Read the task and explore the relevant parts of the codebase until you understand the real problem, the desired outcome, and the constraints the code imposes.\n2. Write the specification to `SPEC.pack.md` at the repo root:\n   - **Problem** \u2014 what is wrong or missing, and for whom.\n   - **Outcome** \u2014 what must be true when this is done.\n   - **Acceptance criteria** \u2014 a numbered checklist of observable, testable conditions. Each criterion must be verifiable by a test or a concrete manual check. They must fully cover the outcome.\n   - **Out of scope** \u2014 what this task deliberately does not touch.\n   - **Verification plan** \u2014 for each criterion, the level that proves it (unit / integration / manual) and why.\n3. Right-size: if the task is clearly too large for one pipeline run, narrow the criteria to a coherent first slice and record the rest under \"Out of scope / next\".\n\n4. Close with a `## Handoff` section: the criteria count, what you scoped out, and any assumption the Coder must know.\n\nHandoff bar: the spec file is committed; every acceptance criterion is testable as written; a competent implementer could start without asking you anything.";
+declare const CODER_PROMPT = "# Role: Coder\n\nYou implement the task with test-driven discipline. You are the only stage that adds behavior.\n\nMethod:\n1. Read the task \u2014 and `SPEC.pack.md` if a Specifier stage produced one; its acceptance criteria are your contract. Without a spec, derive the minimal criteria from the task itself before coding.\n2. Test-first where it fits: write the test that proves a criterion, watch it fail, implement until it passes. Where strict test-first doesn't fit, still land tests alongside the change.\n3. Match the project's existing style, structure, and conventions. Simplest design that fully solves the problem \u2014 no speculative abstractions, no \"while I'm here\" changes.\n4. Run the project's tests / linters / build and make them pass.\n5. Close with a `## Handoff` section: which criteria are implemented (by number) and where their tests live, anything you consciously did NOT do, and what the Reviewer should look at first.\n\nHandoff bar: every acceptance criterion is implemented and covered by a test; the project's checks pass; the work is committed in focused commits.";
+declare const REVIEWER_PROMPT = "# Role: Reviewer\n\nYou are a skeptical senior reviewer with fresh eyes \u2014 you did NOT write this code, and your job is to find what's wrong, not to approve it. You also own architectural cleanliness for this change.\n\nMethod:\n1. Read the task, `SPEC.pack.md` (when present), and the diff of the pipeline's commits (`git log` + `git diff` against the state before the pipeline's first commit). Read enough surrounding code to judge in context.\n2. Audit, in priority order:\n   - **Correctness** \u2014 logic, edge cases, error paths. For each acceptance criterion: point to the test that proves it, and check the test would FAIL if the behavior broke.\n   - **Scope** \u2014 anything beyond the task is flagged and reverted unless it is load-bearing.\n   - **Design** \u2014 duplication, dead code, needless complexity, dependency direction, encapsulation. Verify every API/library call actually exists in the project's dependencies.\n   - **Conventions & naming** \u2014 matches the surrounding code; names say what things are.\n   - **Safety** \u2014 no secrets, credentials, or debugging remnants in code, tests, or fixtures.\n3. Fix what is justified \u2014 smallest change that resolves the finding, keeping behavior. Re-run the checks after material fixes.\n4. Write your findings as DATA to `REVIEW-FINDINGS.pack.json` at the repo root \u2014 the next stage verifies them one by one, so what is not in this file does not get verified. Exact shape:\n   ```json\n   {\n     \"findings\": [\n       {\n         \"id\": \"R1\",\n         \"severity\": \"blocker | major | minor | nit\",\n         \"title\": \"one line: what is wrong\",\n         \"detail\": \"why it matters and what you did about it\",\n         \"file\": \"src/path/to/file.ts\",\n         \"line\": 42,\n         \"resolution\": \"fixed | deferred | wont_fix | needs_verification\",\n         \"commit\": \"abcdef1234\"\n       }\n     ],\n     \"checked\": [\"what you audited when the list is empty: e.g. error paths of X, test coverage of Y\"]\n   }\n   ```\n   Every finding you fixed says `fixed` with its commit; anything you deliberately left says `deferred` or `wont_fix` with the reason in `detail`; anything you could not verify says `needs_verification`. An empty `findings` array is a valid, honest result \u2014 then `checked` must say what you looked at. Commit this file with your stage.\n5. Close with a `## Handoff` section: what you found (counts by severity), what you fixed, what you deliberately left, and what the next stage must verify.\n\nHandoff bar: checks pass on YOUR final commit; every fix is committed; `REVIEW-FINDINGS.pack.json` is committed and lists every finding with its resolution (an empty list says what you checked).";
+declare const QA_PROMPT = "# Role: QA\n\nYou are the final gate. You verify the delivered work against the acceptance criteria as a whole \u2014 end to end, the way a demanding user would \u2014 and produce the run's closing report.\n\nMethod:\n1. Read the task and `SPEC.pack.md` (when present). Your contract is the acceptance criteria; without a spec, derive them from the task.\n2. Read `REVIEW-FINDINGS.pack.json` (when present \u2014 the Reviewer's structured findings, also summarized in your handoff input). Every finding there is an item on YOUR checklist: a `fixed` one must be verified fixed without regression; a `deferred`/`wont_fix` one must be judged acceptable or escalated; a `needs_verification` one is yours to settle.\n3. For EACH criterion, verify it against the real project: run the relevant tests, execute the code paths where feasible, inspect actual behavior/output. Do not take earlier stages' word for anything.\n4. Run the project's full checks (tests, lint, types, build) one final time.\n5. Write `QA-REPORT.pack.md` at the repo root with two sections: **Acceptance criteria** \u2014 per-criterion verdict (\u2705 verified / \u26A0\uFE0F partially / \u274C failed \u2014 with evidence for each); **Review findings** \u2014 per finding id, verdict (\u2705 verified fixed / \u26A0\uFE0F still open / \u274C regressed \u2014 with evidence). Then the checks' results, anything not verifiable in this environment (stated plainly), and a short \"ready to ship?\" conclusion.\n6. If a criterion FAILS: fix it only when the fix is small and unambiguous; otherwise mark it failed with exact evidence \u2014 the user decides. Never paper over a failure.\n7. Close with a `## Handoff` section: the ship/no-ship conclusion, the failed or open items by id, and what you could not verify.\n\nHandoff bar: the report is committed; every verdict carries evidence; every finding id from the Reviewer appears in the report; the conclusion is honest about anything unverified.";
 
 /**
  * The pack **workflow article** — the shared constitution layer every stage
@@ -1043,7 +1109,40 @@ declare const QA_PROMPT = "# Role: QA\n\nYou are the final gate. You verify the
  * commit per stage with the role byline, stay in stage scope, never touch the
  * run ledger. Layered-constitution model adapted from swarm-forge.
  */
-declare const PACK_WORKFLOW_ARTICLE = "## Pipeline rules (you are one stage of an assembly line)\n\nYou are ONE specialist role in a multi-role pipeline running on this repository. Other specialist roles ran before you and/or run after you, each in a separate conversation. Follow these rules exactly:\n\n- **Do only your role's job.** The next stage exists for a reason \u2014 don't do its work, and don't redo a previous stage's work unless your role explicitly calls for correcting it.\n- **Work from the handoff.** The previous stage's handoff (commit + summary) is your input. Start by reading the current state of the working tree \u2014 it already contains all prior stages' work.\n- **Commit your work when your stage is complete.** One or more focused commits; the final state of the tree IS your handoff to the next stage. End every commit message with your role byline on its own line: `By <role>.`\n- **Never leave the tree broken.** Run the project's checks before finishing when the project has them; your stage ends with a working tree the next role can build on.\n- **Do not push, force-push, or touch remotes** \u2014 the pipeline works locally; publishing is the user's call at the end.\n- **Never read, edit, or commit anything under `.codeam/`** \u2014 that is the pipeline's own ledger, not project code.\n- **Finish decisively.** When your stage's job is done and committed, say so in 2-4 lines (what you did, what you verified, anything the next stage should know) and stop. Don't ask \"should I continue?\" \u2014 the pipeline advances automatically.\n- **If you are genuinely blocked** (contradictory requirements, missing access), say exactly what is blocking you and stop \u2014 the user is supervising and will decide.";
+declare const PACK_WORKFLOW_ARTICLE = "## Pipeline rules (you are one stage of an assembly line)\n\nYou are ONE specialist role in a multi-role pipeline running on this repository. Other specialist roles ran before you and/or run after you, each in a separate conversation. Follow these rules exactly:\n\n- **Do only your role's job.** The next stage exists for a reason \u2014 don't do its work, and don't redo a previous stage's work unless your role explicitly calls for correcting it.\n- **Work from the handoff.** The previous stage's handoff (commit + summary) is your input. Start by reading the current state of the working tree \u2014 it already contains all prior stages' work.\n- **Commit your work when your stage is complete.** One or more focused commits; the final state of the tree IS your handoff to the next stage. End every commit message with your role byline on its own line: `By <role>.`\n- **Never leave the tree broken.** Run the project's checks before finishing when the project has them; your stage ends with a working tree the next role can build on.\n- **Do not push, force-push, or touch remotes** \u2014 the pipeline works locally; publishing is the user's call at the end.\n- **Never read, edit, or commit anything under `.codeam/`** \u2014 that is the pipeline's own ledger, not project code.\n- **Finish with a `## Handoff` section.** When your stage's job is done and committed, end your reply with a heading `## Handoff` followed by 2-6 lines: what you did, what you verified, anything the next stage must know. That section \u2014 not the rest of your reply \u2014 is what the next role receives. Don't ask \"should I continue?\" \u2014 the pipeline advances automatically.\n- **If you need the user's decision** (contradictory requirements, a real product choice), ask ONE clear question and end your reply with 2-4 numbered options on their own lines (`1. \u2026`), then stop. The pipeline pauses until they answer in this conversation; keep working in it once they do, and commit as usual.\n- **If you are genuinely blocked** (missing access, a broken environment you cannot fix), say exactly what is blocking you and stop \u2014 the user is supervising and will decide.";
+
+interface ParsedPackFindings {
+    findings: PackFinding[];
+    /** What an empty list audited (`checked` in the file), when the stage said so. */
+    checked?: string[];
+    /** Human-readable caveat: entries dropped, list truncated. Absent when clean. */
+    note?: string;
+}
+type PackFindingsParseResult = {
+    ok: true;
+    value: ParsedPackFindings;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Parse the contents of `PACK_FINDINGS_FILE`. Accepts the documented shape
+ * `{ "findings": [...], "checked"?: [...] }`, a bare array, and either wrapped
+ * in a markdown fence. Individual entries are validated one by one: a bad entry
+ * is dropped and counted in `note`, it never poisons the rest. Unknown
+ * severity/resolution values are coerced to the conservative end
+ * (`major` / `needs_verification`) rather than dropped — a mislabeled finding
+ * is still a finding the next stage must look at.
+ */
+declare function parsePackFindings(raw: string): PackFindingsParseResult;
+/**
+ * Lift the `## Handoff` section from a stage reply (the workflow article asks
+ * every stage to close with one). Returns null when the reply has no such
+ * heading, so callers fall back to the reply's tail. Case-insensitive on the
+ * heading text, tolerant of `#`/`###`, stops at the next heading of the same
+ * or higher level.
+ */
+declare function extractHandoffSection(reply: string): string | null;
 
 /**
  * Wire-shape types for the CLI / IDE-plugin → backend producer endpoints
@@ -1989,4 +2088,4 @@ type UserEventName = (typeof USER_EVENTS)[keyof typeof USER_EVENTS];
  */
 declare const PREVIEW_DETECT_PROMPT: string;
 
-export { AGENT_REGISTRY, AGENT_STANDARD_BLOCK, AGENT_STANDARD_MARKER, AGENT_STANDARD_TEXT, type AgentAuth, type AgentAuthKind, type AgentId, type AgentMetadata, type AgentMode, type AgentModel, type AgentReviewFinding, type AgentReviewPlan, type AgentReviewReport, type AnswerResolvedEvent, type AwaitingAnswerEvent, type AwaitingAnswerOption, type BeadsActionCommand, type BeadsActionKind, type BeadsActionPayload, type BeadsActionRequest, type BeadsActionType, type BeadsConfigureAction, type BeadsDependencyDto, type BeadsDependencyKind, type BeadsIngestPayload, type BeadsIssueDto, type BeadsIssueStatus, type BeadsMemoryDto, type BeadsProjectDto, type BeadsProvisioningPayload, type BeadsProvisioningStatus, type BeadsSnapshotDto, type BeadsStatus, type BeadsStatusState, type BeadsStatusSummary, type BlameLineWire, type BrokeredIntegrationToken, CODER_PROMPT, type ChromeStep, type ChromeToolType, type CommitEntryWire, DEFAULT_API_BASE_URL, DEFAULT_GUARDRAIL_POLICY, DEP_TO_INTEGRATION, DEV_API_BASE_URL, type DerivedCredentialSource, type EnvVar, type FileBlameEvent, type FileChangeStatus, type FileChangedEvent, type FileHistoryEvent, type FileReviewStatus, GUARDRAIL_CATEGORIES, GUARDRAIL_CATEGORY_META, GUARDRAIL_CONFIGURE_COMMAND, GUARDRAIL_DISPOSITIONS, type GuardrailCategory, type GuardrailCategoryMeta, type GuardrailDisposition, type GuardrailPolicy, HANDOFF_FENCE_TAG, HEARTBEAT_INTERVAL_MS_DEFAULT, HOUSE_AGENT_ID, HOUSE_AGENT_NAME, HOUSE_AGENT_PROVIDER, HOUSE_AGENT_SUBTITLE, HOUSE_AGENT_VENDOR, type HandoffProposal, type HandoffResolution, type HunkLineType, INSTALL_SNIPPETS, INTEGRATION_BRANDING, INTEGRATION_REGISTRY, INTERNAL_TO_PUBLIC, type InputSuggestionChunk, type IntegrationApiKeyField, type IntegrationAuthKind, type IntegrationBranding, type IntegrationCategory, type IntegrationDefinition, type IntegrationDelivery, type IntegrationHealth, type IntegrationId, type IntegrationMcpDelivery, type IntegrationStatus, type IntegrationsManifest, type IntegrationsManifestEntry, LINKED_AGENT_IDS, type LinkedAgentId, MANAGED_AGENT_ENV, MANAGED_AGENT_SUBTITLE, MANAGED_PROVIDER_DISPLAY_NAMES, MANAGED_PROVIDER_IDS, MODEL_CONTEXT_WINDOW, MODEL_PRICING, type ManagedProviderId, type MissingService, type ModelPricing, type NormalizedMessage, OBSERVER_BRIDGE_PORT, PACK_ACTION_COMMAND, PACK_REGISTRY, PACK_START_COMMAND, PACK_STATUS_COMMAND, PACK_WORKFLOW_ARTICLE, PREVIEW_DETECT_PROMPT, PROTOCOL_VERSION, PUBLIC_TO_INTERNAL, type PackActionKind, type PackActionPayload, type PackDefinition, type PackHandoffRecord, type PackId, type PackRunState, type PackRunStatus, type PackStageDef, type PackStageState, type PackStageStatus, type PackStartPayload, type PendingReviewHunkEvent, type PendingReviewHunkLine, type PrCheck, type PrRef, type PrReviewEntry, type PrReviewVerdict, type PreviewDetection, type PreviewErrorStage, type PreviewState, type PreviewStatus, type PullRequestDetail, type PullRequestSummary, QA_PROMPT, REVIEWER_PROMPT, type RemoteCommand, type RepoStack, type RepoStackDetection, SKILL_REGISTRY, SPECIFIER_PROMPT, SQUAD_CONFIGURE_COMMAND, SQUAD_HOP_BUDGET_DEFAULT, SQUAD_HOP_BUDGET_MAX, SQUAD_HOP_BUDGET_MIN, SQUAD_SPECIALTIES, SQUAD_STATS_COMMAND, SSE_SOCKET_TIMEOUT_MS, STACK_TO_RECOMMENDED, SWITCH_AGENT_COMMAND, type SelectPrompt, type SkillDefinition, type SkillDelivery, type SkillFileDelivery, type SkillId, type SkillRail, type SkillsManifest, type SkillsManifestEntry, type SquadAutoConfig, type SquadConfigurePayload, type SquadConfigureResult, type SquadMemberActivity, type SquadRosterAgent, type SquadRosterData, type SquadStatsResult, type StartTaskFailedResult, type StartTaskPayload, type StreamingChunkEvent, type StreamingChunkKind, type SwitchAgentCommand, type SwitchAgentResult, type SwitchAgentStatus, type SwitchAgentStep, TERMINAL_AGENT_PREFIX, UNKNOWN_MODEL_PRICING, UPCOMING_INTEGRATION_IDS, USER_EVENTS, type UserEventName, clampHopBudget, classifyStack, detectedIntegrationsFromDeps, getAgent, getContextWindow, getEnabledAgents, getEnabledIntegrations, getIntegration, getIntegrationBranding, getIntegrationsByCategory, getPackDefinition, getPricing, getSkillDefinition, installableAgentIds, internalToPublic, isGuardrailDisposition, isKnownAgentId, isKnownIntegrationId, isKnownModel, isLinkedAgentId, isManagedProviderId, isNoopInstallSnippet, isPackId, isSkillId, normalizeAgentId, normalizeGuardrailPolicy, publicToInternal, recommendForDeps, renderToLines, resolveApiBaseUrl, skillHasRail, toRemoteCommand, tryGetContextWindow };
+export { AGENT_REGISTRY, AGENT_STANDARD_BLOCK, AGENT_STANDARD_MARKER, AGENT_STANDARD_TEXT, type AgentAuth, type AgentAuthKind, type AgentId, type AgentMetadata, type AgentMode, type AgentModel, type AgentReviewFinding, type AgentReviewPlan, type AgentReviewReport, type AnswerResolvedEvent, type AwaitingAnswerEvent, type AwaitingAnswerOption, type BeadsActionCommand, type BeadsActionKind, type BeadsActionPayload, type BeadsActionRequest, type BeadsActionType, type BeadsConfigureAction, type BeadsDependencyDto, type BeadsDependencyKind, type BeadsIngestPayload, type BeadsIssueDto, type BeadsIssueStatus, type BeadsMemoryDto, type BeadsProjectDto, type BeadsProvisioningPayload, type BeadsProvisioningStatus, type BeadsSnapshotDto, type BeadsStatus, type BeadsStatusState, type BeadsStatusSummary, type BlameLineWire, type BrokeredIntegrationToken, CODER_PROMPT, type ChromeStep, type ChromeToolType, type CommitEntryWire, DEFAULT_API_BASE_URL, DEFAULT_GUARDRAIL_POLICY, DEP_TO_INTEGRATION, DEV_API_BASE_URL, type DerivedCredentialSource, type EnvVar, type FileBlameEvent, type FileChangeStatus, type FileChangedEvent, type FileHistoryEvent, type FileReviewStatus, GUARDRAIL_CATEGORIES, GUARDRAIL_CATEGORY_META, GUARDRAIL_CONFIGURE_COMMAND, GUARDRAIL_DISPOSITIONS, type GuardrailCategory, type GuardrailCategoryMeta, type GuardrailDisposition, type GuardrailPolicy, HANDOFF_FENCE_TAG, HEARTBEAT_INTERVAL_MS_DEFAULT, HOUSE_AGENT_ID, HOUSE_AGENT_NAME, HOUSE_AGENT_PROVIDER, HOUSE_AGENT_SUBTITLE, HOUSE_AGENT_VENDOR, type HandoffProposal, type HandoffResolution, type HunkLineType, INSTALL_SNIPPETS, INTEGRATION_BRANDING, INTEGRATION_REGISTRY, INTERNAL_TO_PUBLIC, type InputSuggestionChunk, type IntegrationApiKeyField, type IntegrationAuthKind, type IntegrationBranding, type IntegrationCategory, type IntegrationDefinition, type IntegrationDelivery, type IntegrationHealth, type IntegrationId, type IntegrationMcpDelivery, type IntegrationStatus, type IntegrationsManifest, type IntegrationsManifestEntry, LINKED_AGENT_IDS, type LinkedAgentId, MANAGED_AGENT_ENV, MANAGED_AGENT_SUBTITLE, MANAGED_PROVIDER_DISPLAY_NAMES, MANAGED_PROVIDER_IDS, MAX_PACK_FINDINGS, MODEL_CONTEXT_WINDOW, MODEL_PRICING, type ManagedProviderId, type MissingService, type ModelPricing, type NormalizedMessage, OBSERVER_BRIDGE_PORT, PACK_ACTION_COMMAND, PACK_FINDINGS_FILE, PACK_HANDOFF_HEADING, PACK_REGISTRY, PACK_START_COMMAND, PACK_STATUS_COMMAND, PACK_WORKFLOW_ARTICLE, PREVIEW_DETECT_PROMPT, PROTOCOL_VERSION, PUBLIC_TO_INTERNAL, type PackActionKind, type PackActionPayload, type PackDefinition, type PackFinding, type PackFindingResolution, type PackFindingSeverity, type PackFindingsParseResult, type PackHandoffRecord, type PackId, type PackPendingControl, type PackRunState, type PackRunStatus, type PackStageDef, type PackStageState, type PackStageStatus, type PackStartPayload, type ParsedPackFindings, type PendingReviewHunkEvent, type PendingReviewHunkLine, type PrCheck, type PrRef, type PrReviewEntry, type PrReviewVerdict, type PreviewDetection, type PreviewErrorStage, type PreviewState, type PreviewStatus, type PullRequestDetail, type PullRequestSummary, QA_PROMPT, REVIEWER_PROMPT, type RemoteCommand, type RepoStack, type RepoStackDetection, SKILL_REGISTRY, SPECIFIER_PROMPT, SQUAD_CONFIGURE_COMMAND, SQUAD_HOP_BUDGET_DEFAULT, SQUAD_HOP_BUDGET_MAX, SQUAD_HOP_BUDGET_MIN, SQUAD_SPECIALTIES, SQUAD_STATS_COMMAND, SSE_SOCKET_TIMEOUT_MS, STACK_TO_RECOMMENDED, SWITCH_AGENT_COMMAND, type SelectPrompt, type SkillDefinition, type SkillDelivery, type SkillFileDelivery, type SkillId, type SkillRail, type SkillsManifest, type SkillsManifestEntry, type SquadAutoConfig, type SquadConfigurePayload, type SquadConfigureResult, type SquadMemberActivity, type SquadRosterAgent, type SquadRosterData, type SquadStatsResult, type StartTaskFailedResult, type StartTaskPayload, type StreamingChunkEvent, type StreamingChunkKind, type SwitchAgentCommand, type SwitchAgentResult, type SwitchAgentStatus, type SwitchAgentStep, TERMINAL_AGENT_PREFIX, UNKNOWN_MODEL_PRICING, UPCOMING_INTEGRATION_IDS, USER_EVENTS, type UserEventName, clampHopBudget, classifyStack, detectedIntegrationsFromDeps, extractHandoffSection, getAgent, getContextWindow, getEnabledAgents, getEnabledIntegrations, getIntegration, getIntegrationBranding, getIntegrationsByCategory, getPackDefinition, getPricing, getSkillDefinition, installableAgentIds, internalToPublic, isGuardrailDisposition, isKnownAgentId, isKnownIntegrationId, isKnownModel, isLinkedAgentId, isManagedProviderId, isNoopInstallSnippet, isPackId, isSkillId, normalizeAgentId, normalizeGuardrailPolicy, parsePackFindings, publicToInternal, recommendForDeps, renderToLines, resolveApiBaseUrl, skillHasRail, toRemoteCommand, tryGetContextWindow };

package/dist/index.d.ts

@@ -948,6 +948,13 @@ interface PackStageDef {
      * 2026-08-08 — a clean Reviewer was mis-treated as "stage produced no commit".)
      */
     requiresCommit?: boolean;
+    /**
+     * Whether this stage is expected to leave a structured findings file
+     * (`PACK_FINDINGS_FILE`) at the repo root, which the runner parses into
+     * `PackHandoffRecord.findings` so the NEXT stage consumes an explicit list
+     * instead of re-deriving it from prose. Review-style stages set this.
+     */
+    producesFindings?: boolean;
 }
 interface PackDefinition {
     id: PackId;
@@ -960,11 +967,44 @@ interface PackDefinition {
 }
 type PackRunStatus = 'running' | 'paused' | 'stalled' | 'completed' | 'aborted' | 'failed';
 type PackStageStatus = 'pending' | 'active' | 'done' | 'failed' | 'skipped';
+type PackFindingSeverity = 'blocker' | 'major' | 'minor' | 'nit';
+type PackFindingResolution = 'fixed' | 'deferred' | 'wont_fix' | 'needs_verification';
+/**
+ * One review finding, machine-readable. A review-style stage writes a list of
+ * these to `PACK_FINDINGS_FILE` (repo root, committed with the stage — the
+ * same rail as `SPEC.pack.md`); the runner parses the file into the stage's
+ * handoff so the next stage gets an explicit list to verify one by one, and
+ * every finding either receives a verdict downstream or is visibly open.
+ */
+interface PackFinding {
+    /** Stable short id the next stage references (e.g. `R1`). */
+    id: string;
+    severity: PackFindingSeverity;
+    /** One line: what is wrong. */
+    title: string;
+    /** Why it matters / what was done, a few lines at most. */
+    detail?: string;
+    /** Repo-relative path, when the finding points at code. */
+    file?: string;
+    line?: number;
+    resolution: PackFindingResolution;
+    /** Commit that resolves it, when `resolution === 'fixed'` (model-claimed; the
+     *  stage's git-validated handoff commit is the authority). */
+    commit?: string;
+}
+/** Repo-root file a `producesFindings` stage writes. Root, NOT `.codeam/` — the
+ *  workflow article forbids agents from touching the pipeline ledger. */
+declare const PACK_FINDINGS_FILE = "REVIEW-FINDINGS.pack.json";
+/** Upper bound on parsed findings — a runaway list is truncated, not rejected. */
+declare const MAX_PACK_FINDINGS = 50;
+/** Heading every stage closes its reply with; the runner lifts the section
+ *  below it as the handoff summary instead of the reply's raw tail. */
+declare const PACK_HANDOFF_HEADING = "## Handoff";
 /** Mechanically captured proof of what a stage delivered. */
 interface PackHandoffRecord {
     /** Canonical 10-hex commit abbreviation (git-validated, never model-claimed). */
     commit: string;
-    /** Short summary of the stage's reply (first lines, capped). */
+    /** The reply's `## Handoff` section when present, else its tail (capped). */
     summary: string;
     /** `git diff --stat` summary line between the stage's start and end commits. */
     diffStat: string;
@@ -975,6 +1015,12 @@ interface PackHandoffRecord {
         tail: string;
     };
     durationMs: number;
+    /** Parsed `PACK_FINDINGS_FILE` for a `producesFindings` stage. Absent when
+     *  the stage does not produce findings; empty when it audited and found none. */
+    findings?: PackFinding[];
+    /** Why `findings` is absent/partial on a `producesFindings` stage (no file,
+     *  malformed JSON, truncated) or what an empty list checked — always honest. */
+    findingsNote?: string;
 }
 interface PackStageState {
     role: string;
@@ -985,7 +1031,21 @@ interface PackStageState {
     handoff?: PackHandoffRecord;
     /** Populated when status === 'failed' (or the run stalled on this stage). */
     error?: string;
-}
+    /**
+     * The stage's turn ended with a question for the user (a select prompt the
+     * app renders). The run is paused, NOT nudged — the user answers in the
+     * stage chat and taps Resume, which re-checks the stage's commit gate in the
+     * SAME conversation instead of starting a fresh one.
+     */
+    awaitingUser?: boolean;
+    /** How many fresh conversations this stage has had (1 = first attempt). */
+    attempts?: number;
+    /** Canonical HEAD when the stage's current attempt began — the diff base for
+     *  its handoff, kept stable across an in-place resume. */
+    startCommit?: string;
+}
+/** A control the user asked for mid-turn; it takes effect at the stage boundary. */
+type PackPendingControl = 'pause' | 'abort';
 interface PackRunState {
     runId: string;
     packId: PackId;
@@ -995,8 +1055,14 @@ interface PackRunState {
     /** Index into `stages` of the stage currently active/next. */
     currentStage: number;
     stages: PackStageState[];
-    /** Set when status is 'stalled' | 'failed' — the honest reason. */
+    /** Set when status is 'stalled' | 'failed' | 'paused' with a cause — the honest reason. */
     stalledReason?: string;
+    /** Canonical HEAD before the pipeline's first stage — every stage gets it so
+     *  "the pipeline's diff" is `git diff <baseCommit>..HEAD`, never a guess. */
+    baseCommit?: string;
+    /** Set while a pause/abort requested mid-turn waits for the stage boundary;
+     *  the UI shows "pausing after this stage" instead of a false PAUSED. */
+    pendingControl?: PackPendingControl;
     startedAt: string;
     updatedAt: string;
 }
@@ -1031,10 +1097,10 @@ declare function getPackDefinition(id: string): PackDefinition | null;
  * (PACK_WORKFLOW_ARTICLE) and the task + previous handoff are appended by the
  * runner at stage start.
  */
-declare const SPECIFIER_PROMPT = "# Role: Specifier\n\nYou turn the user's task into a precise, testable specification the rest of the pipeline implements against. You do NOT write implementation code.\n\nMethod:\n1. Read the task and explore the relevant parts of the codebase until you understand the real problem, the desired outcome, and the constraints the code imposes.\n2. Write the specification to `SPEC.pack.md` at the repo root:\n   - **Problem** \u2014 what is wrong or missing, and for whom.\n   - **Outcome** \u2014 what must be true when this is done.\n   - **Acceptance criteria** \u2014 a numbered checklist of observable, testable conditions. Each criterion must be verifiable by a test or a concrete manual check. They must fully cover the outcome.\n   - **Out of scope** \u2014 what this task deliberately does not touch.\n   - **Verification plan** \u2014 for each criterion, the level that proves it (unit / integration / manual) and why.\n3. Right-size: if the task is clearly too large for one pipeline run, narrow the criteria to a coherent first slice and record the rest under \"Out of scope / next\".\n\nHandoff bar: the spec file is committed; every acceptance criterion is testable as written; a competent implementer could start without asking you anything.";
-declare const CODER_PROMPT = "# Role: Coder\n\nYou implement the task with test-driven discipline. You are the only stage that adds behavior.\n\nMethod:\n1. Read the task \u2014 and `SPEC.pack.md` if a Specifier stage produced one; its acceptance criteria are your contract. Without a spec, derive the minimal criteria from the task itself before coding.\n2. Test-first where it fits: write the test that proves a criterion, watch it fail, implement until it passes. Where strict test-first doesn't fit, still land tests alongside the change.\n3. Match the project's existing style, structure, and conventions. Simplest design that fully solves the problem \u2014 no speculative abstractions, no \"while I'm here\" changes.\n4. Run the project's tests / linters / build and make them pass.\n\nHandoff bar: every acceptance criterion is implemented and covered by a test; the project's checks pass; the work is committed in focused commits.";
-declare const REVIEWER_PROMPT = "# Role: Reviewer\n\nYou are a skeptical senior reviewer with fresh eyes \u2014 you did NOT write this code, and your job is to find what's wrong, not to approve it. You also own architectural cleanliness for this change.\n\nMethod:\n1. Read the task, `SPEC.pack.md` (when present), and the diff of the pipeline's commits (`git log` + `git diff` against the state before the pipeline's first commit). Read enough surrounding code to judge in context.\n2. Audit, in priority order:\n   - **Correctness** \u2014 logic, edge cases, error paths. For each acceptance criterion: point to the test that proves it, and check the test would FAIL if the behavior broke.\n   - **Scope** \u2014 anything beyond the task is flagged and reverted unless it is load-bearing.\n   - **Design** \u2014 duplication, dead code, needless complexity, dependency direction, encapsulation. Verify every API/library call actually exists in the project's dependencies.\n   - **Conventions & naming** \u2014 matches the surrounding code; names say what things are.\n   - **Safety** \u2014 no secrets, credentials, or debugging remnants in code, tests, or fixtures.\n3. Fix what is justified \u2014 smallest change that resolves the finding, keeping behavior. Re-run the checks after material fixes.\n4. Record your findings honestly in your closing summary: what you found, what you fixed, what you deliberately left, and what you could not verify.\n\nHandoff bar: checks pass on YOUR final commit; every fix is committed; your summary lists findings \u2192 resolutions (an empty findings list must say what you checked).";
-declare const QA_PROMPT = "# Role: QA\n\nYou are the final gate. You verify the delivered work against the acceptance criteria as a whole \u2014 end to end, the way a demanding user would \u2014 and produce the run's closing report.\n\nMethod:\n1. Read the task and `SPEC.pack.md` (when present). Your contract is the acceptance criteria; without a spec, derive them from the task.\n2. For EACH criterion, verify it against the real project: run the relevant tests, execute the code paths where feasible, inspect actual behavior/output. Do not take earlier stages' word for anything.\n3. Run the project's full checks (tests, lint, types, build) one final time.\n4. Write `QA-REPORT.pack.md` at the repo root: per-criterion verdict (\u2705 verified / \u26A0\uFE0F partially / \u274C failed \u2014 with evidence for each), the checks' results, anything not verifiable in this environment (stated plainly), and a short \"ready to ship?\" conclusion.\n5. If a criterion FAILS: fix it only when the fix is small and unambiguous; otherwise mark it failed with exact evidence \u2014 the user decides. Never paper over a failure.\n\nHandoff bar: the report is committed; every verdict carries evidence; the conclusion is honest about anything unverified.";
+declare const SPECIFIER_PROMPT = "# Role: Specifier\n\nYou turn the user's task into a precise, testable specification the rest of the pipeline implements against. You do NOT write implementation code.\n\nMethod:\n1. Read the task and explore the relevant parts of the codebase until you understand the real problem, the desired outcome, and the constraints the code imposes.\n2. Write the specification to `SPEC.pack.md` at the repo root:\n   - **Problem** \u2014 what is wrong or missing, and for whom.\n   - **Outcome** \u2014 what must be true when this is done.\n   - **Acceptance criteria** \u2014 a numbered checklist of observable, testable conditions. Each criterion must be verifiable by a test or a concrete manual check. They must fully cover the outcome.\n   - **Out of scope** \u2014 what this task deliberately does not touch.\n   - **Verification plan** \u2014 for each criterion, the level that proves it (unit / integration / manual) and why.\n3. Right-size: if the task is clearly too large for one pipeline run, narrow the criteria to a coherent first slice and record the rest under \"Out of scope / next\".\n\n4. Close with a `## Handoff` section: the criteria count, what you scoped out, and any assumption the Coder must know.\n\nHandoff bar: the spec file is committed; every acceptance criterion is testable as written; a competent implementer could start without asking you anything.";
+declare const CODER_PROMPT = "# Role: Coder\n\nYou implement the task with test-driven discipline. You are the only stage that adds behavior.\n\nMethod:\n1. Read the task \u2014 and `SPEC.pack.md` if a Specifier stage produced one; its acceptance criteria are your contract. Without a spec, derive the minimal criteria from the task itself before coding.\n2. Test-first where it fits: write the test that proves a criterion, watch it fail, implement until it passes. Where strict test-first doesn't fit, still land tests alongside the change.\n3. Match the project's existing style, structure, and conventions. Simplest design that fully solves the problem \u2014 no speculative abstractions, no \"while I'm here\" changes.\n4. Run the project's tests / linters / build and make them pass.\n5. Close with a `## Handoff` section: which criteria are implemented (by number) and where their tests live, anything you consciously did NOT do, and what the Reviewer should look at first.\n\nHandoff bar: every acceptance criterion is implemented and covered by a test; the project's checks pass; the work is committed in focused commits.";
+declare const REVIEWER_PROMPT = "# Role: Reviewer\n\nYou are a skeptical senior reviewer with fresh eyes \u2014 you did NOT write this code, and your job is to find what's wrong, not to approve it. You also own architectural cleanliness for this change.\n\nMethod:\n1. Read the task, `SPEC.pack.md` (when present), and the diff of the pipeline's commits (`git log` + `git diff` against the state before the pipeline's first commit). Read enough surrounding code to judge in context.\n2. Audit, in priority order:\n   - **Correctness** \u2014 logic, edge cases, error paths. For each acceptance criterion: point to the test that proves it, and check the test would FAIL if the behavior broke.\n   - **Scope** \u2014 anything beyond the task is flagged and reverted unless it is load-bearing.\n   - **Design** \u2014 duplication, dead code, needless complexity, dependency direction, encapsulation. Verify every API/library call actually exists in the project's dependencies.\n   - **Conventions & naming** \u2014 matches the surrounding code; names say what things are.\n   - **Safety** \u2014 no secrets, credentials, or debugging remnants in code, tests, or fixtures.\n3. Fix what is justified \u2014 smallest change that resolves the finding, keeping behavior. Re-run the checks after material fixes.\n4. Write your findings as DATA to `REVIEW-FINDINGS.pack.json` at the repo root \u2014 the next stage verifies them one by one, so what is not in this file does not get verified. Exact shape:\n   ```json\n   {\n     \"findings\": [\n       {\n         \"id\": \"R1\",\n         \"severity\": \"blocker | major | minor | nit\",\n         \"title\": \"one line: what is wrong\",\n         \"detail\": \"why it matters and what you did about it\",\n         \"file\": \"src/path/to/file.ts\",\n         \"line\": 42,\n         \"resolution\": \"fixed | deferred | wont_fix | needs_verification\",\n         \"commit\": \"abcdef1234\"\n       }\n     ],\n     \"checked\": [\"what you audited when the list is empty: e.g. error paths of X, test coverage of Y\"]\n   }\n   ```\n   Every finding you fixed says `fixed` with its commit; anything you deliberately left says `deferred` or `wont_fix` with the reason in `detail`; anything you could not verify says `needs_verification`. An empty `findings` array is a valid, honest result \u2014 then `checked` must say what you looked at. Commit this file with your stage.\n5. Close with a `## Handoff` section: what you found (counts by severity), what you fixed, what you deliberately left, and what the next stage must verify.\n\nHandoff bar: checks pass on YOUR final commit; every fix is committed; `REVIEW-FINDINGS.pack.json` is committed and lists every finding with its resolution (an empty list says what you checked).";
+declare const QA_PROMPT = "# Role: QA\n\nYou are the final gate. You verify the delivered work against the acceptance criteria as a whole \u2014 end to end, the way a demanding user would \u2014 and produce the run's closing report.\n\nMethod:\n1. Read the task and `SPEC.pack.md` (when present). Your contract is the acceptance criteria; without a spec, derive them from the task.\n2. Read `REVIEW-FINDINGS.pack.json` (when present \u2014 the Reviewer's structured findings, also summarized in your handoff input). Every finding there is an item on YOUR checklist: a `fixed` one must be verified fixed without regression; a `deferred`/`wont_fix` one must be judged acceptable or escalated; a `needs_verification` one is yours to settle.\n3. For EACH criterion, verify it against the real project: run the relevant tests, execute the code paths where feasible, inspect actual behavior/output. Do not take earlier stages' word for anything.\n4. Run the project's full checks (tests, lint, types, build) one final time.\n5. Write `QA-REPORT.pack.md` at the repo root with two sections: **Acceptance criteria** \u2014 per-criterion verdict (\u2705 verified / \u26A0\uFE0F partially / \u274C failed \u2014 with evidence for each); **Review findings** \u2014 per finding id, verdict (\u2705 verified fixed / \u26A0\uFE0F still open / \u274C regressed \u2014 with evidence). Then the checks' results, anything not verifiable in this environment (stated plainly), and a short \"ready to ship?\" conclusion.\n6. If a criterion FAILS: fix it only when the fix is small and unambiguous; otherwise mark it failed with exact evidence \u2014 the user decides. Never paper over a failure.\n7. Close with a `## Handoff` section: the ship/no-ship conclusion, the failed or open items by id, and what you could not verify.\n\nHandoff bar: the report is committed; every verdict carries evidence; every finding id from the Reviewer appears in the report; the conclusion is honest about anything unverified.";
 
 /**
  * The pack **workflow article** — the shared constitution layer every stage
@@ -1043,7 +1109,40 @@ declare const QA_PROMPT = "# Role: QA\n\nYou are the final gate. You verify the
  * commit per stage with the role byline, stay in stage scope, never touch the
  * run ledger. Layered-constitution model adapted from swarm-forge.
  */
-declare const PACK_WORKFLOW_ARTICLE = "## Pipeline rules (you are one stage of an assembly line)\n\nYou are ONE specialist role in a multi-role pipeline running on this repository. Other specialist roles ran before you and/or run after you, each in a separate conversation. Follow these rules exactly:\n\n- **Do only your role's job.** The next stage exists for a reason \u2014 don't do its work, and don't redo a previous stage's work unless your role explicitly calls for correcting it.\n- **Work from the handoff.** The previous stage's handoff (commit + summary) is your input. Start by reading the current state of the working tree \u2014 it already contains all prior stages' work.\n- **Commit your work when your stage is complete.** One or more focused commits; the final state of the tree IS your handoff to the next stage. End every commit message with your role byline on its own line: `By <role>.`\n- **Never leave the tree broken.** Run the project's checks before finishing when the project has them; your stage ends with a working tree the next role can build on.\n- **Do not push, force-push, or touch remotes** \u2014 the pipeline works locally; publishing is the user's call at the end.\n- **Never read, edit, or commit anything under `.codeam/`** \u2014 that is the pipeline's own ledger, not project code.\n- **Finish decisively.** When your stage's job is done and committed, say so in 2-4 lines (what you did, what you verified, anything the next stage should know) and stop. Don't ask \"should I continue?\" \u2014 the pipeline advances automatically.\n- **If you are genuinely blocked** (contradictory requirements, missing access), say exactly what is blocking you and stop \u2014 the user is supervising and will decide.";
+declare const PACK_WORKFLOW_ARTICLE = "## Pipeline rules (you are one stage of an assembly line)\n\nYou are ONE specialist role in a multi-role pipeline running on this repository. Other specialist roles ran before you and/or run after you, each in a separate conversation. Follow these rules exactly:\n\n- **Do only your role's job.** The next stage exists for a reason \u2014 don't do its work, and don't redo a previous stage's work unless your role explicitly calls for correcting it.\n- **Work from the handoff.** The previous stage's handoff (commit + summary) is your input. Start by reading the current state of the working tree \u2014 it already contains all prior stages' work.\n- **Commit your work when your stage is complete.** One or more focused commits; the final state of the tree IS your handoff to the next stage. End every commit message with your role byline on its own line: `By <role>.`\n- **Never leave the tree broken.** Run the project's checks before finishing when the project has them; your stage ends with a working tree the next role can build on.\n- **Do not push, force-push, or touch remotes** \u2014 the pipeline works locally; publishing is the user's call at the end.\n- **Never read, edit, or commit anything under `.codeam/`** \u2014 that is the pipeline's own ledger, not project code.\n- **Finish with a `## Handoff` section.** When your stage's job is done and committed, end your reply with a heading `## Handoff` followed by 2-6 lines: what you did, what you verified, anything the next stage must know. That section \u2014 not the rest of your reply \u2014 is what the next role receives. Don't ask \"should I continue?\" \u2014 the pipeline advances automatically.\n- **If you need the user's decision** (contradictory requirements, a real product choice), ask ONE clear question and end your reply with 2-4 numbered options on their own lines (`1. \u2026`), then stop. The pipeline pauses until they answer in this conversation; keep working in it once they do, and commit as usual.\n- **If you are genuinely blocked** (missing access, a broken environment you cannot fix), say exactly what is blocking you and stop \u2014 the user is supervising and will decide.";
+
+interface ParsedPackFindings {
+    findings: PackFinding[];
+    /** What an empty list audited (`checked` in the file), when the stage said so. */
+    checked?: string[];
+    /** Human-readable caveat: entries dropped, list truncated. Absent when clean. */
+    note?: string;
+}
+type PackFindingsParseResult = {
+    ok: true;
+    value: ParsedPackFindings;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Parse the contents of `PACK_FINDINGS_FILE`. Accepts the documented shape
+ * `{ "findings": [...], "checked"?: [...] }`, a bare array, and either wrapped
+ * in a markdown fence. Individual entries are validated one by one: a bad entry
+ * is dropped and counted in `note`, it never poisons the rest. Unknown
+ * severity/resolution values are coerced to the conservative end
+ * (`major` / `needs_verification`) rather than dropped — a mislabeled finding
+ * is still a finding the next stage must look at.
+ */
+declare function parsePackFindings(raw: string): PackFindingsParseResult;
+/**
+ * Lift the `## Handoff` section from a stage reply (the workflow article asks
+ * every stage to close with one). Returns null when the reply has no such
+ * heading, so callers fall back to the reply's tail. Case-insensitive on the
+ * heading text, tolerant of `#`/`###`, stops at the next heading of the same
+ * or higher level.
+ */
+declare function extractHandoffSection(reply: string): string | null;
 
 /**
  * Wire-shape types for the CLI / IDE-plugin → backend producer endpoints
@@ -1989,4 +2088,4 @@ type UserEventName = (typeof USER_EVENTS)[keyof typeof USER_EVENTS];
  */
 declare const PREVIEW_DETECT_PROMPT: string;
 
-export { AGENT_REGISTRY, AGENT_STANDARD_BLOCK, AGENT_STANDARD_MARKER, AGENT_STANDARD_TEXT, type AgentAuth, type AgentAuthKind, type AgentId, type AgentMetadata, type AgentMode, type AgentModel, type AgentReviewFinding, type AgentReviewPlan, type AgentReviewReport, type AnswerResolvedEvent, type AwaitingAnswerEvent, type AwaitingAnswerOption, type BeadsActionCommand, type BeadsActionKind, type BeadsActionPayload, type BeadsActionRequest, type BeadsActionType, type BeadsConfigureAction, type BeadsDependencyDto, type BeadsDependencyKind, type BeadsIngestPayload, type BeadsIssueDto, type BeadsIssueStatus, type BeadsMemoryDto, type BeadsProjectDto, type BeadsProvisioningPayload, type BeadsProvisioningStatus, type BeadsSnapshotDto, type BeadsStatus, type BeadsStatusState, type BeadsStatusSummary, type BlameLineWire, type BrokeredIntegrationToken, CODER_PROMPT, type ChromeStep, type ChromeToolType, type CommitEntryWire, DEFAULT_API_BASE_URL, DEFAULT_GUARDRAIL_POLICY, DEP_TO_INTEGRATION, DEV_API_BASE_URL, type DerivedCredentialSource, type EnvVar, type FileBlameEvent, type FileChangeStatus, type FileChangedEvent, type FileHistoryEvent, type FileReviewStatus, GUARDRAIL_CATEGORIES, GUARDRAIL_CATEGORY_META, GUARDRAIL_CONFIGURE_COMMAND, GUARDRAIL_DISPOSITIONS, type GuardrailCategory, type GuardrailCategoryMeta, type GuardrailDisposition, type GuardrailPolicy, HANDOFF_FENCE_TAG, HEARTBEAT_INTERVAL_MS_DEFAULT, HOUSE_AGENT_ID, HOUSE_AGENT_NAME, HOUSE_AGENT_PROVIDER, HOUSE_AGENT_SUBTITLE, HOUSE_AGENT_VENDOR, type HandoffProposal, type HandoffResolution, type HunkLineType, INSTALL_SNIPPETS, INTEGRATION_BRANDING, INTEGRATION_REGISTRY, INTERNAL_TO_PUBLIC, type InputSuggestionChunk, type IntegrationApiKeyField, type IntegrationAuthKind, type IntegrationBranding, type IntegrationCategory, type IntegrationDefinition, type IntegrationDelivery, type IntegrationHealth, type IntegrationId, type IntegrationMcpDelivery, type IntegrationStatus, type IntegrationsManifest, type IntegrationsManifestEntry, LINKED_AGENT_IDS, type LinkedAgentId, MANAGED_AGENT_ENV, MANAGED_AGENT_SUBTITLE, MANAGED_PROVIDER_DISPLAY_NAMES, MANAGED_PROVIDER_IDS, MODEL_CONTEXT_WINDOW, MODEL_PRICING, type ManagedProviderId, type MissingService, type ModelPricing, type NormalizedMessage, OBSERVER_BRIDGE_PORT, PACK_ACTION_COMMAND, PACK_REGISTRY, PACK_START_COMMAND, PACK_STATUS_COMMAND, PACK_WORKFLOW_ARTICLE, PREVIEW_DETECT_PROMPT, PROTOCOL_VERSION, PUBLIC_TO_INTERNAL, type PackActionKind, type PackActionPayload, type PackDefinition, type PackHandoffRecord, type PackId, type PackRunState, type PackRunStatus, type PackStageDef, type PackStageState, type PackStageStatus, type PackStartPayload, type PendingReviewHunkEvent, type PendingReviewHunkLine, type PrCheck, type PrRef, type PrReviewEntry, type PrReviewVerdict, type PreviewDetection, type PreviewErrorStage, type PreviewState, type PreviewStatus, type PullRequestDetail, type PullRequestSummary, QA_PROMPT, REVIEWER_PROMPT, type RemoteCommand, type RepoStack, type RepoStackDetection, SKILL_REGISTRY, SPECIFIER_PROMPT, SQUAD_CONFIGURE_COMMAND, SQUAD_HOP_BUDGET_DEFAULT, SQUAD_HOP_BUDGET_MAX, SQUAD_HOP_BUDGET_MIN, SQUAD_SPECIALTIES, SQUAD_STATS_COMMAND, SSE_SOCKET_TIMEOUT_MS, STACK_TO_RECOMMENDED, SWITCH_AGENT_COMMAND, type SelectPrompt, type SkillDefinition, type SkillDelivery, type SkillFileDelivery, type SkillId, type SkillRail, type SkillsManifest, type SkillsManifestEntry, type SquadAutoConfig, type SquadConfigurePayload, type SquadConfigureResult, type SquadMemberActivity, type SquadRosterAgent, type SquadRosterData, type SquadStatsResult, type StartTaskFailedResult, type StartTaskPayload, type StreamingChunkEvent, type StreamingChunkKind, type SwitchAgentCommand, type SwitchAgentResult, type SwitchAgentStatus, type SwitchAgentStep, TERMINAL_AGENT_PREFIX, UNKNOWN_MODEL_PRICING, UPCOMING_INTEGRATION_IDS, USER_EVENTS, type UserEventName, clampHopBudget, classifyStack, detectedIntegrationsFromDeps, getAgent, getContextWindow, getEnabledAgents, getEnabledIntegrations, getIntegration, getIntegrationBranding, getIntegrationsByCategory, getPackDefinition, getPricing, getSkillDefinition, installableAgentIds, internalToPublic, isGuardrailDisposition, isKnownAgentId, isKnownIntegrationId, isKnownModel, isLinkedAgentId, isManagedProviderId, isNoopInstallSnippet, isPackId, isSkillId, normalizeAgentId, normalizeGuardrailPolicy, publicToInternal, recommendForDeps, renderToLines, resolveApiBaseUrl, skillHasRail, toRemoteCommand, tryGetContextWindow };
+export { AGENT_REGISTRY, AGENT_STANDARD_BLOCK, AGENT_STANDARD_MARKER, AGENT_STANDARD_TEXT, type AgentAuth, type AgentAuthKind, type AgentId, type AgentMetadata, type AgentMode, type AgentModel, type AgentReviewFinding, type AgentReviewPlan, type AgentReviewReport, type AnswerResolvedEvent, type AwaitingAnswerEvent, type AwaitingAnswerOption, type BeadsActionCommand, type BeadsActionKind, type BeadsActionPayload, type BeadsActionRequest, type BeadsActionType, type BeadsConfigureAction, type BeadsDependencyDto, type BeadsDependencyKind, type BeadsIngestPayload, type BeadsIssueDto, type BeadsIssueStatus, type BeadsMemoryDto, type BeadsProjectDto, type BeadsProvisioningPayload, type BeadsProvisioningStatus, type BeadsSnapshotDto, type BeadsStatus, type BeadsStatusState, type BeadsStatusSummary, type BlameLineWire, type BrokeredIntegrationToken, CODER_PROMPT, type ChromeStep, type ChromeToolType, type CommitEntryWire, DEFAULT_API_BASE_URL, DEFAULT_GUARDRAIL_POLICY, DEP_TO_INTEGRATION, DEV_API_BASE_URL, type DerivedCredentialSource, type EnvVar, type FileBlameEvent, type FileChangeStatus, type FileChangedEvent, type FileHistoryEvent, type FileReviewStatus, GUARDRAIL_CATEGORIES, GUARDRAIL_CATEGORY_META, GUARDRAIL_CONFIGURE_COMMAND, GUARDRAIL_DISPOSITIONS, type GuardrailCategory, type GuardrailCategoryMeta, type GuardrailDisposition, type GuardrailPolicy, HANDOFF_FENCE_TAG, HEARTBEAT_INTERVAL_MS_DEFAULT, HOUSE_AGENT_ID, HOUSE_AGENT_NAME, HOUSE_AGENT_PROVIDER, HOUSE_AGENT_SUBTITLE, HOUSE_AGENT_VENDOR, type HandoffProposal, type HandoffResolution, type HunkLineType, INSTALL_SNIPPETS, INTEGRATION_BRANDING, INTEGRATION_REGISTRY, INTERNAL_TO_PUBLIC, type InputSuggestionChunk, type IntegrationApiKeyField, type IntegrationAuthKind, type IntegrationBranding, type IntegrationCategory, type IntegrationDefinition, type IntegrationDelivery, type IntegrationHealth, type IntegrationId, type IntegrationMcpDelivery, type IntegrationStatus, type IntegrationsManifest, type IntegrationsManifestEntry, LINKED_AGENT_IDS, type LinkedAgentId, MANAGED_AGENT_ENV, MANAGED_AGENT_SUBTITLE, MANAGED_PROVIDER_DISPLAY_NAMES, MANAGED_PROVIDER_IDS, MAX_PACK_FINDINGS, MODEL_CONTEXT_WINDOW, MODEL_PRICING, type ManagedProviderId, type MissingService, type ModelPricing, type NormalizedMessage, OBSERVER_BRIDGE_PORT, PACK_ACTION_COMMAND, PACK_FINDINGS_FILE, PACK_HANDOFF_HEADING, PACK_REGISTRY, PACK_START_COMMAND, PACK_STATUS_COMMAND, PACK_WORKFLOW_ARTICLE, PREVIEW_DETECT_PROMPT, PROTOCOL_VERSION, PUBLIC_TO_INTERNAL, type PackActionKind, type PackActionPayload, type PackDefinition, type PackFinding, type PackFindingResolution, type PackFindingSeverity, type PackFindingsParseResult, type PackHandoffRecord, type PackId, type PackPendingControl, type PackRunState, type PackRunStatus, type PackStageDef, type PackStageState, type PackStageStatus, type PackStartPayload, type ParsedPackFindings, type PendingReviewHunkEvent, type PendingReviewHunkLine, type PrCheck, type PrRef, type PrReviewEntry, type PrReviewVerdict, type PreviewDetection, type PreviewErrorStage, type PreviewState, type PreviewStatus, type PullRequestDetail, type PullRequestSummary, QA_PROMPT, REVIEWER_PROMPT, type RemoteCommand, type RepoStack, type RepoStackDetection, SKILL_REGISTRY, SPECIFIER_PROMPT, SQUAD_CONFIGURE_COMMAND, SQUAD_HOP_BUDGET_DEFAULT, SQUAD_HOP_BUDGET_MAX, SQUAD_HOP_BUDGET_MIN, SQUAD_SPECIALTIES, SQUAD_STATS_COMMAND, SSE_SOCKET_TIMEOUT_MS, STACK_TO_RECOMMENDED, SWITCH_AGENT_COMMAND, type SelectPrompt, type SkillDefinition, type SkillDelivery, type SkillFileDelivery, type SkillId, type SkillRail, type SkillsManifest, type SkillsManifestEntry, type SquadAutoConfig, type SquadConfigurePayload, type SquadConfigureResult, type SquadMemberActivity, type SquadRosterAgent, type SquadRosterData, type SquadStatsResult, type StartTaskFailedResult, type StartTaskPayload, type StreamingChunkEvent, type StreamingChunkKind, type SwitchAgentCommand, type SwitchAgentResult, type SwitchAgentStatus, type SwitchAgentStep, TERMINAL_AGENT_PREFIX, UNKNOWN_MODEL_PRICING, UPCOMING_INTEGRATION_IDS, USER_EVENTS, type UserEventName, clampHopBudget, classifyStack, detectedIntegrationsFromDeps, extractHandoffSection, getAgent, getContextWindow, getEnabledAgents, getEnabledIntegrations, getIntegration, getIntegrationBranding, getIntegrationsByCategory, getPackDefinition, getPricing, getSkillDefinition, installableAgentIds, internalToPublic, isGuardrailDisposition, isKnownAgentId, isKnownIntegrationId, isKnownModel, isLinkedAgentId, isManagedProviderId, isNoopInstallSnippet, isPackId, isSkillId, normalizeAgentId, normalizeGuardrailPolicy, parsePackFindings, publicToInternal, recommendForDeps, renderToLines, resolveApiBaseUrl, skillHasRail, toRemoteCommand, tryGetContextWindow };