@phnx-labs/agents-cli 1.20.35 → 1.20.37

package/dist/lib/sync-umbrella.d.ts

@@ -1,11 +1,12 @@
 /**
  * Umbrella `agents sync` orchestration — "make this machine current".
  *
- * Bare `agents sync` fetches remote state (config repos + secrets + sessions)
- * then reconciles it into every installed agent's version home. Each stage is
- * an existing exported library function; this module only sequences them and
- * decides — from the flags — which stages run (`planUmbrellaStages`). The
- * planner is pure so the flag matrix is unit-tested without any I/O.
+ * Bare `agents sync` fetches the config repos then reconciles them into every
+ * installed agent's version home. Secrets and sessions are opt-in stages
+ * (`--secrets` / `--sessions`) — see `planUmbrellaStages` for why they're off by
+ * default. Each stage is an existing exported library function; this module only
+ * sequences them and decides — from the flags — which stages run. The planner is
+ * pure so the flag matrix is unit-tested without any I/O.
  *
  * Stage backends:
  *   repos    -> git pull of ~/.agents + enabled ~/.agents-* extras (pullRepo)
@@ -32,11 +33,17 @@ export interface UmbrellaPlan {
 }
 /**
  * Decide which stages run. Pure — no I/O. Semantics:
- *   bare (no flags)        fetch all three, then reconcile
+ *   bare (no flags)        fetch repos, then reconcile
  *   --local                reconcile only, no fetch
- *   --cloud                fetch (all, or the selected subset), skip reconcile
+ *   --cloud                fetch repos (or the selected subset), skip reconcile
  *   --repos/--secrets/...  fetch only the selected types, then reconcile
  * `--local` wins over everything; `--cloud` suppresses reconcile.
+ *
+ * Secrets and sessions are NOT part of the bare default — they are opt-in via
+ * `--secrets` / `--sessions`. Pulling every secret bundle onto the machine on a
+ * bare `agents sync` is more blast radius than the verb should carry by
+ * default, and session transcripts are queryable on demand (`agents sessions
+ * --host <machine>`) so they don't need eager mirroring.
  */
 export declare function planUmbrellaStages(f: UmbrellaFlags): UmbrellaPlan;
 export interface UmbrellaResult {

package/dist/lib/sync-umbrella.js

@@ -1,11 +1,12 @@
 /**
  * Umbrella `agents sync` orchestration — "make this machine current".
  *
- * Bare `agents sync` fetches remote state (config repos + secrets + sessions)
- * then reconciles it into every installed agent's version home. Each stage is
- * an existing exported library function; this module only sequences them and
- * decides — from the flags — which stages run (`planUmbrellaStages`). The
- * planner is pure so the flag matrix is unit-tested without any I/O.
+ * Bare `agents sync` fetches the config repos then reconciles them into every
+ * installed agent's version home. Secrets and sessions are opt-in stages
+ * (`--secrets` / `--sessions`) — see `planUmbrellaStages` for why they're off by
+ * default. Each stage is an existing exported library function; this module only
+ * sequences them and decides — from the flags — which stages run. The planner is
+ * pure so the flag matrix is unit-tested without any I/O.
  *
  * Stage backends:
  *   repos    -> git pull of ~/.agents + enabled ~/.agents-* extras (pullRepo)
@@ -20,11 +21,17 @@ import { getUserAgentsDir, getEnabledExtraRepos } from './state.js';
 import { listRemoteBundles, pullBundle } from './secrets/sync.js';
 /**
  * Decide which stages run. Pure — no I/O. Semantics:
- *   bare (no flags)        fetch all three, then reconcile
+ *   bare (no flags)        fetch repos, then reconcile
  *   --local                reconcile only, no fetch
- *   --cloud                fetch (all, or the selected subset), skip reconcile
+ *   --cloud                fetch repos (or the selected subset), skip reconcile
  *   --repos/--secrets/...  fetch only the selected types, then reconcile
  * `--local` wins over everything; `--cloud` suppresses reconcile.
+ *
+ * Secrets and sessions are NOT part of the bare default — they are opt-in via
+ * `--secrets` / `--sessions`. Pulling every secret bundle onto the machine on a
+ * bare `agents sync` is more blast radius than the verb should carry by
+ * default, and session transcripts are queryable on demand (`agents sessions
+ * --host <machine>`) so they don't need eager mirroring.
  */
 export function planUmbrellaStages(f) {
     if (f.local) {
@@ -39,8 +46,9 @@ export function planUmbrellaStages(f) {
             reconcile: !f.cloud,
         };
     }
-    // No per-type selector: bare = all + reconcile; --cloud = all, no reconcile.
-    return { fetchRepos: true, fetchSecrets: true, fetchSessions: true, reconcile: !f.cloud };
+    // No per-type selector: bare = repos + reconcile; --cloud = repos, no
+    // reconcile. Secrets/sessions stay off unless explicitly selected above.
+    return { fetchRepos: true, fetchSecrets: false, fetchSessions: false, reconcile: !f.cloud };
 }
 /**
  * Execute the planned stages in order: repos -> secrets -> sessions -> reconcile.
@@ -103,10 +111,10 @@ export async function runUmbrellaSync(args) {
         }
     }
     if (plan.fetchSessions) {
-        // Gate exactly like the daemon: a missing r2.backups bundle is a clean no-op,
-        // not an error that fails the whole sync.
-        const { isSyncConfigured } = await import('./session/sync/config.js');
-        if (isSyncConfigured()) {
+        // Gate exactly like the daemon: an off switch or a missing r2.backups bundle
+        // is a clean no-op, not an error that fails the whole sync.
+        const { isSyncConfigured, isSyncEnabled } = await import('./session/sync/config.js');
+        if (isSyncEnabled() && isSyncConfigured()) {
             const { syncSessions } = await import('./session/sync/sync.js');
             const r = await syncSessions();
             result.sessions = { ran: true, pushed: r.pushed, pulled: r.pulled, merged: r.merged };

package/dist/lib/teams/forEach.d.ts

@@ -0,0 +1,110 @@
+import type { AgentManager, AgentProcess, EffortLevel } from './agents.js';
+import { type ForEachSpec, type ForEachTeammate } from '../workflows.js';
+/**
+ * Parse a producer's stdout into the item list `expandForEach` fans out over.
+ *
+ * Two shapes are accepted (issue #343), tried in order:
+ *   1. A JSON array — `["a","b","c"]` (each element coerced to a trimmed string).
+ *   2. Newline-delimited — one item per line.
+ *
+ * Empty lines / entries are dropped so a trailing newline or a `[]` never
+ * fabricates a phantom teammate. Pure and deterministic — no I/O.
+ */
+export declare function parseProducedItems(stdout: string): string[];
+export interface ProduceItemsOptions {
+    /** Working directory for the producer command. */
+    cwd?: string | null;
+    /** Environment for the producer command (defaults to the current process env). */
+    env?: NodeJS.ProcessEnv;
+    /** Kill the producer after this many ms (default 120_000). */
+    timeoutMs?: number;
+    /**
+     * Resolve an `itemsRef` (`${step}`-style reference) to a prior step's produced
+     * list. When a spec carries `itemsRef` and this resolver returns a list, the
+     * producer command is skipped entirely.
+     */
+    resolveItemsRef?: (ref: string) => string[] | undefined;
+}
+/**
+ * Resolve a `for_each` spec's item list at runtime (issue #343): either by
+ * running its `produce:` shell command and parsing stdout, or by resolving an
+ * `itemsRef` to a prior step's list. The resulting items feed `expandForEach` /
+ * `runForEach`.
+ *
+ * `itemsRef` wins when a resolver is supplied and returns a list; otherwise the
+ * `produce` command runs. A spec with neither a resolvable ref nor a produce
+ * command is a hard error — there is nothing to fan out over.
+ */
+export declare function produceItems(spec: ForEachSpec, opts?: ProduceItemsOptions): Promise<string[]>;
+/**
+ * Evaluate a verify panel's `keep_if` gate against its boolean votes (issue
+ * #343). A `true` vote is a skeptic confirming the finding should be kept.
+ *
+ *   - `all`      — every skeptic must vote keep.
+ *   - `any`      — at least one skeptic votes keep.
+ *   - `majority` — strictly more than half vote keep (a tie does NOT pass).
+ *
+ * An empty panel returns false: with no votes there is nothing affirming the
+ * item, so the conservative gate drops it.
+ */
+export declare function evaluateKeepIf(votes: boolean[], keepIf: 'majority' | 'all' | 'any'): boolean;
+/** Per-item verdict after tallying its verify panel. */
+export interface ForEachItemVerdict {
+    /** The produced item this verdict is for. */
+    item: string;
+    /** Zero-based index in the (capped) produced list. */
+    itemIndex: number;
+    /** The stage teammate that handled this item. */
+    stageName: string;
+    /** Whether the item survives its `keep_if` gate (true when it has no panel). */
+    kept: boolean;
+    /** The votes that were tallied (empty when the item has no verify panel). */
+    votes: boolean[];
+    /** The gate applied (undefined when the item has no verify panel). */
+    keepIf?: 'majority' | 'all' | 'any';
+}
+/**
+ * Tally the verify panels of an expanded `for_each` and gate each item (issue
+ * #343). Groups verify teammates by the stage teammate they depend on, reads a
+ * boolean vote per verify teammate via `readVote`, and applies `keep_if`.
+ *
+ * An item with no verify panel is kept unconditionally (there is no gate).
+ * Pure and deterministic: `readVote` is the only place runtime state enters, so
+ * this is unit-testable with a synthetic vote reader.
+ */
+export declare function tallyForEach(teammates: ForEachTeammate[], readVote: (verify: ForEachTeammate) => boolean): ForEachItemVerdict[];
+export interface RunForEachOptions {
+    /** Working directory for the spawned teammates. */
+    cwd?: string | null;
+    /**
+     * Name of the producer teammate the stage teammates should depend on. When
+     * set, each stage runs `--after` the producer so it can't start before the
+     * list is available.
+     */
+    producerName?: string;
+    /** Default effort for spawned teammates (per-item overrides live in the spec). */
+    effort?: EffortLevel;
+    /** Concurrency cap for the wave; falls back to the spec's `concurrency`. */
+    concurrency?: number;
+}
+export interface RunForEachResult {
+    /** The expanded descriptors (stage + verify), in spawn order. */
+    teammates: ForEachTeammate[];
+    /** The AgentProcess handles returned by `spawn`, aligned to `teammates`. */
+    spawned: AgentProcess[];
+    /** Items the producer emitted (pre-cap). */
+    producedCount: number;
+    /** Items actually fanned out (post-cap). */
+    usedCount: number;
+    /** How many items the runaway guard dropped. */
+    truncated: number;
+}
+/**
+ * Expand a `for_each` spec against a producer's output and stage every
+ * resulting teammate into the given team via the dynamic-add path.
+ *
+ * Returns the descriptors and the spawned handles so a caller can drive the
+ * supervisor and later gather results (e.g. to evaluate a `verify` panel's
+ * `keep_if` gate — that vote-counting lives downstream, not here).
+ */
+export declare function runForEach(mgr: AgentManager, teamName: string, spec: ForEachSpec, items: string[], opts?: RunForEachOptions): Promise<RunForEachResult>;

package/dist/lib/teams/forEach.js

@@ -0,0 +1,186 @@
+/**
+ * Runtime wiring for declarative dynamic fan-out (issue #343).
+ *
+ * The declarative shape (`for_each:` in WORKFLOW.md / routine `run:` blocks) is
+ * parsed and expanded by `src/lib/workflows.ts` (`parseForEachBlock`,
+ * `expandForEach`). This module is the thin bridge that stages the expanded
+ * teammate descriptors into the EXISTING teams substrate — one
+ * `AgentManager.spawn` per descriptor, which the DAG supervisor then picks up
+ * mid-flight via `rescanFromDisk` / `startReady`
+ * (`src/lib/teams/supervisor.ts:98-103`).
+ *
+ * It deliberately adds NO new orchestration engine: `spawn` with an `--after`
+ * chain is the whole mechanism, so cycle detection, wave scheduling, and
+ * cross-vendor/rotation dispatch all carry over unchanged.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { posixShellPath } from '../platform/exec.js';
+import { expandForEach } from '../workflows.js';
+const execFileAsync = promisify(execFile);
+/**
+ * Parse a producer's stdout into the item list `expandForEach` fans out over.
+ *
+ * Two shapes are accepted (issue #343), tried in order:
+ *   1. A JSON array — `["a","b","c"]` (each element coerced to a trimmed string).
+ *   2. Newline-delimited — one item per line.
+ *
+ * Empty lines / entries are dropped so a trailing newline or a `[]` never
+ * fabricates a phantom teammate. Pure and deterministic — no I/O.
+ */
+export function parseProducedItems(stdout) {
+    const trimmed = stdout.trim();
+    if (trimmed === '')
+        return [];
+    // JSON array form first — only when it actually looks like one, so a plain
+    // line that happens to start with '[' doesn't get swallowed by a parse error.
+    if (trimmed.startsWith('[')) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (Array.isArray(parsed)) {
+                return parsed
+                    .map((x) => (x == null ? '' : typeof x === 'string' ? x : String(x)))
+                    .map((s) => s.trim())
+                    .filter((s) => s.length > 0);
+            }
+        }
+        catch {
+            // Not valid JSON — fall through to newline parsing.
+        }
+    }
+    // Newline-delimited form.
+    return trimmed
+        .split(/\r?\n/)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/**
+ * Resolve a `for_each` spec's item list at runtime (issue #343): either by
+ * running its `produce:` shell command and parsing stdout, or by resolving an
+ * `itemsRef` to a prior step's list. The resulting items feed `expandForEach` /
+ * `runForEach`.
+ *
+ * `itemsRef` wins when a resolver is supplied and returns a list; otherwise the
+ * `produce` command runs. A spec with neither a resolvable ref nor a produce
+ * command is a hard error — there is nothing to fan out over.
+ */
+export async function produceItems(spec, opts = {}) {
+    if (spec.itemsRef && opts.resolveItemsRef) {
+        const resolved = opts.resolveItemsRef(spec.itemsRef);
+        if (resolved)
+            return resolved;
+    }
+    if (!spec.produce) {
+        if (spec.itemsRef) {
+            throw new Error(`for_each itemsRef '${spec.itemsRef}' could not be resolved and no produce command is set`);
+        }
+        throw new Error('for_each has neither a produce command nor a resolvable itemsRef');
+    }
+    // The producer is a shell command string (e.g. "rg -l 'x' src/"), so it runs
+    // under `sh -c` exactly like a teammate command — resolved portably, because
+    // /bin/sh does not exist on Windows (there it's Git's sh.exe from PATH).
+    // maxBuffer is raised well above the default 1MB so a producer emitting a
+    // large list isn't truncated silently mid-stream.
+    const { stdout } = await execFileAsync(posixShellPath(), ['-c', spec.produce], {
+        cwd: opts.cwd ?? undefined,
+        env: opts.env ?? process.env,
+        timeout: opts.timeoutMs ?? 120_000,
+        maxBuffer: 64 * 1024 * 1024,
+        encoding: 'utf-8',
+    });
+    return parseProducedItems(stdout);
+}
+/**
+ * Evaluate a verify panel's `keep_if` gate against its boolean votes (issue
+ * #343). A `true` vote is a skeptic confirming the finding should be kept.
+ *
+ *   - `all`      — every skeptic must vote keep.
+ *   - `any`      — at least one skeptic votes keep.
+ *   - `majority` — strictly more than half vote keep (a tie does NOT pass).
+ *
+ * An empty panel returns false: with no votes there is nothing affirming the
+ * item, so the conservative gate drops it.
+ */
+export function evaluateKeepIf(votes, keepIf) {
+    const total = votes.length;
+    if (total === 0)
+        return false;
+    const yes = votes.reduce((n, v) => (v ? n + 1 : n), 0);
+    switch (keepIf) {
+        case 'all':
+            return yes === total;
+        case 'any':
+            return yes >= 1;
+        case 'majority':
+            return yes * 2 > total;
+    }
+}
+/**
+ * Tally the verify panels of an expanded `for_each` and gate each item (issue
+ * #343). Groups verify teammates by the stage teammate they depend on, reads a
+ * boolean vote per verify teammate via `readVote`, and applies `keep_if`.
+ *
+ * An item with no verify panel is kept unconditionally (there is no gate).
+ * Pure and deterministic: `readVote` is the only place runtime state enters, so
+ * this is unit-testable with a synthetic vote reader.
+ */
+export function tallyForEach(teammates, readVote) {
+    const stages = teammates.filter((t) => t.role === 'stage');
+    const verifiersByStage = new Map();
+    for (const t of teammates) {
+        if (t.role !== 'verify')
+            continue;
+        const stageName = t.after[0];
+        if (!stageName)
+            continue;
+        const list = verifiersByStage.get(stageName) ?? [];
+        list.push(t);
+        verifiersByStage.set(stageName, list);
+    }
+    return stages.map((stage) => {
+        const panel = verifiersByStage.get(stage.name) ?? [];
+        if (panel.length === 0) {
+            return {
+                item: stage.item,
+                itemIndex: stage.itemIndex,
+                stageName: stage.name,
+                kept: true,
+                votes: [],
+            };
+        }
+        const keepIf = panel[0].keep_if ?? 'majority';
+        const votes = panel.map((v) => readVote(v));
+        return {
+            item: stage.item,
+            itemIndex: stage.itemIndex,
+            stageName: stage.name,
+            kept: evaluateKeepIf(votes, keepIf),
+            votes,
+            keepIf,
+        };
+    });
+}
+/**
+ * Expand a `for_each` spec against a producer's output and stage every
+ * resulting teammate into the given team via the dynamic-add path.
+ *
+ * Returns the descriptors and the spawned handles so a caller can drive the
+ * supervisor and later gather results (e.g. to evaluate a `verify` panel's
+ * `keep_if` gate — that vote-counting lives downstream, not here).
+ */
+export async function runForEach(mgr, teamName, spec, items, opts = {}) {
+    const { teammates, producedCount, usedCount, truncated } = expandForEach(spec, items, {
+        producerName: opts.producerName,
+    });
+    const effort = opts.effort ?? 'medium';
+    const spawned = [];
+    for (const t of teammates) {
+        const agent = await mgr.spawn(teamName, t.agentType, t.prompt, opts.cwd ?? null, null, // mode: inherit team default
+        effort, null, // parentSessionId
+        null, // workspaceDir
+        null, // version
+        t.name, t.after);
+        spawned.push(agent);
+    }
+    return { teammates, spawned, producedCount, usedCount, truncated };
+}

package/dist/lib/teams/index.d.ts

@@ -14,4 +14,5 @@ export { type EffortLevel } from './agents.js';
 export { collapseEvents, getToolBreakdown, groupAndFlattenEvents, summarizeEvents, getDelta, filterEventsByPriority, getLastTool, getToolUses, getLastMessages, getQuickStatus, getStatusSummary, AgentSummary, PRIORITY, type QuickStatus, } from './summarizer.js';
 export { extractFileOpsFromBash } from './file_ops.js';
 export { debug } from './debug.js';
+export { runForEach, type RunForEachOptions, type RunForEachResult, } from './forEach.js';
 export { createWorktree, removeWorktree, isGitRepo, getGitRoot, hasUncommittedChanges, getWorktreePath, getWorktreeBranch, } from './worktree.js';

package/dist/lib/teams/index.js

@@ -12,4 +12,5 @@ export { resolveAgentsDir, resolveBaseDir, } from './persistence.js';
 export { collapseEvents, getToolBreakdown, groupAndFlattenEvents, summarizeEvents, getDelta, filterEventsByPriority, getLastTool, getToolUses, getLastMessages, getQuickStatus, getStatusSummary, AgentSummary, PRIORITY, } from './summarizer.js';
 export { extractFileOpsFromBash } from './file_ops.js';
 export { debug } from './debug.js';
+export { runForEach, } from './forEach.js';
 export { createWorktree, removeWorktree, isGitRepo, getGitRoot, hasUncommittedChanges, getWorktreePath, getWorktreeBranch, } from './worktree.js';

package/dist/lib/teams/pr-watch.d.ts

@@ -0,0 +1,226 @@
+/**
+ * A CI check result. Shaped after `gh pr checks <pr> --json name,state,link,workflow`,
+ * where `state` is one of SUCCESS | FAILURE | PENDING | ERROR | CANCELLED | SKIPPING | ...
+ *
+ * Note on identity: `gh pr checks` exposes NO stable check-run id — `link` is the
+ * per-run URL, which changes every time a workflow re-runs. So dedupe keys off the
+ * check NAME (stable across re-runs), not the link (see `checkDedupeKey`). `link`
+ * is retained only for the human-facing prompt and for scraping run logs.
+ */
+export interface PrCheck {
+    name: string;
+    state: string;
+    link?: string;
+    workflow?: string;
+}
+/** A PR review comment. Shaped after GitHub's `repos/{owner}/{repo}/pulls/{n}/comments`. */
+export interface PrReviewComment {
+    id: number;
+    body: string;
+    user?: string;
+    path?: string;
+    html_url?: string;
+}
+/** One PR under watch, with its current CI + comment snapshot. */
+export interface PrSnapshot {
+    /** The PR URL (https://github.com/{owner}/{repo}/pull/{n}). */
+    prUrl: string;
+    /**
+     * Name of the teammate whose work opened this PR — the `--after` anchor the
+     * spawned fix/bugfix teammate links to. Null when the PR can't be traced to a
+     * named teammate (the reaction still fires, just without a dependency edge).
+     */
+    sourceTeammate: string | null;
+    checks: PrCheck[];
+    comments: PrReviewComment[];
+}
+/**
+ * Default cap on how many fix/bugfix waves pr-watch spawns for a single PR before
+ * it gives up and escalates to a human. A persistently-RED PR re-runs CI on every
+ * follow-up commit; without a cap the loop would spawn teammates without bound
+ * (issue #338). Configurable via `--max-waves`.
+ */
+export declare const DEFAULT_MAX_WAVES = 3;
+/** A decision to spawn a follow-up teammate. Pure output of `decidePrActions`. */
+export type PrWatchAction = {
+    kind: 'ci-fix';
+    prUrl: string;
+    sourceTeammate: string | null;
+    check: PrCheck;
+    /** Idempotency key — record it in `handled` once acted on so it never re-fires. */
+    dedupeKey: string;
+    /** 1-based wave number for this PR (used to name the spawned teammate uniquely). */
+    wave: number;
+} | {
+    kind: 'review-fix';
+    prUrl: string;
+    sourceTeammate: string | null;
+    comment: PrReviewComment;
+    dedupeKey: string;
+    wave: number;
+} | {
+    /**
+     * The per-PR wave budget is exhausted — stop spawning, escalate to a human.
+     * Emitted once per PR (deduped via `needsHumanKey`) instead of an N+1th fix.
+     */
+    kind: 'needs-human';
+    prUrl: string;
+    sourceTeammate: string | null;
+    /** What triggered the escalation (e.g. `CI check "test"`). */
+    subject: string;
+    /** Waves already spent on this PR when the cap was hit. */
+    waves: number;
+    dedupeKey: string;
+};
+/** The spawnable subset of actions — everything except the `needs-human` escalation. */
+export type PrWatchSpawnAction = Extract<PrWatchAction, {
+    kind: 'ci-fix' | 'review-fix';
+}>;
+/** True when a check is in a terminal failing state. */
+export declare function isFailedCheck(check: PrCheck): boolean;
+/**
+ * Idempotency key for a failed check on a PR — dedupe by check NAME.
+ *
+ * The name is the ONLY identity that's stable across re-runs: when a fixer pushes
+ * a follow-up commit, GitHub creates a fresh workflow run with a new `link` URL but
+ * the SAME check name. Keying off `link` (as an earlier draft did) would treat every
+ * re-run as a brand-new failure and spawn an unbounded chain of fixers (issue #338).
+ * Keying off the name means a re-run of the same check is recognised as the same
+ * logical failure; the per-PR wave counter then bounds how many times we retry it.
+ */
+export declare function checkDedupeKey(prUrl: string, check: PrCheck): string;
+/** Idempotency key for a review comment on a PR — dedupe by comment id. */
+export declare function commentDedupeKey(prUrl: string, comment: PrReviewComment): string;
+/** Idempotency key for the one-shot "needs human" escalation on a PR. */
+export declare function needsHumanKey(prUrl: string): string;
+/**
+ * The pure heart of pr-watch: given a PR snapshot, the set of dedupe keys already
+ * acted on, and how many fix waves each PR has already spent, decide which
+ * follow-up teammates to spawn. Emits:
+ *   - one `ci-fix` action per NEW failed check (dedup by check NAME)
+ *   - one `review-fix` action per NEW review comment (dedup by comment id)
+ *   - a single `needs-human` action (per PR) once the wave budget is exhausted,
+ *     INSTEAD of spawning — so a persistently-failing PR escalates rather than
+ *     spawning teammates without bound (issue #338).
+ *
+ * `waves` maps a PR URL to the number of fix/bugfix teammates already spawned for
+ * it; once that reaches `maxWaves`, no further spawns are emitted for that PR.
+ * Both the CI-fix and comment-routing paths draw from the SAME per-PR budget, so
+ * neither can loop unboundedly.
+ *
+ * No network, no side effects, no reference to state beyond the passed
+ * `handled` / `waves` — so the same failure never spawns twice and the caller
+ * stays in control of when a wave is "spent".
+ */
+export declare function decidePrActions(snapshot: PrSnapshot, handled: ReadonlySet<string>, waves?: ReadonlyMap<string, number>, maxWaves?: number): PrWatchAction[];
+/**
+ * Build the task prompt for a CI-fix teammate. Pure so it's unit-testable: the
+ * failing check + the fetched logs are injected as data.
+ */
+export declare function buildCiFixPrompt(action: Extract<PrWatchAction, {
+    kind: 'ci-fix';
+}>, logs: string): string;
+/**
+ * Build the task prompt for a review-comment bugfix teammate. Pure so it's
+ * unit-testable: the review comment is injected as data.
+ */
+export declare function buildReviewFixPrompt(action: Extract<PrWatchAction, {
+    kind: 'review-fix';
+}>): string;
+/** Parse an owner/repo/number triple out of a GitHub PR URL. Returns null when it doesn't match. */
+export declare function parsePrUrl(prUrl: string): {
+    owner: string;
+    repo: string;
+    number: number;
+} | null;
+/** Fetch the current CI checks for a PR via `gh pr checks`. Returns [] on any gh error. */
+export declare function fetchPrChecks(prUrl: string): Promise<PrCheck[]>;
+/** Fetch review comments for a PR via `gh api`. Returns [] on any gh error. */
+export declare function fetchPrReviewComments(prUrl: string): Promise<PrReviewComment[]>;
+/** Fetch the failing-run logs for a check via `gh run view --log-failed`. Best-effort, truncated. */
+export declare function fetchCiFailureLogs(check: PrCheck, maxChars?: number): Promise<string>;
+/** Collect a live PR snapshot from `gh`. The poll-mode seam for `runPrWatch`. */
+export declare function pollPrSnapshot(prUrl: string, sourceTeammate: string | null): Promise<PrSnapshot>;
+/** A PR to watch, paired with the teammate that opened it. */
+export interface WatchTarget {
+    prUrl: string;
+    sourceTeammate: string | null;
+}
+export interface PrWatchDeps {
+    /** Discover which PRs to watch this pass (teammates may open PRs mid-run). */
+    resolveTargets: () => Promise<WatchTarget[]>;
+    /** Snapshot one PR's CI + review comments. Defaults to `pollPrSnapshot`. */
+    pollSnapshot?: (prUrl: string, sourceTeammate: string | null) => Promise<PrSnapshot>;
+    /** Fetch CI failure logs for a ci-fix action. Defaults to `fetchCiFailureLogs`. */
+    fetchLogs?: (check: PrCheck) => Promise<string>;
+    /**
+     * React to one decided spawn action: spawn the fix/bugfix teammate. The prompt
+     * is pre-built with logs/comment injected. Return the spawned teammate label for
+     * logging, or null if the spawn was skipped. `needs-human` actions never reach
+     * here — they surface as a `needs-human` event instead.
+     */
+    react: (action: PrWatchSpawnAction, prompt: string) => Promise<string | null>;
+    /**
+     * True when a previously-spawned reaction has finished. Once its fixer settles,
+     * the dedupe guard for that check clears so a check that is STILL red can spawn
+     * its next (budget-bounded) wave; without this, a check would only ever get one
+     * fix attempt per pr-watch run. Optional — when omitted, a check gets a single
+     * wave until pr-watch restarts.
+     */
+    reactionSettled?: (label: string) => Promise<boolean>;
+    /** Progress sink — one call per notable event (poll, spawn, escalate, error). */
+    onEvent?: (event: PrWatchEvent) => void;
+}
+export type PrWatchEvent = {
+    type: 'poll';
+    targets: number;
+    timestamp: string;
+} | {
+    type: 'spawned';
+    action: PrWatchSpawnAction;
+    label: string | null;
+    timestamp: string;
+} | {
+    type: 'needs-human';
+    prUrl: string;
+    subject: string;
+    waves: number;
+    timestamp: string;
+} | {
+    type: 'error';
+    prUrl: string;
+    message: string;
+    timestamp: string;
+};
+export interface PrWatchOptions {
+    intervalMs?: number;
+    /** Stop after this many polls (0 / undefined = run until signalled). */
+    maxPolls?: number;
+    /** Seed of already-handled dedupe keys (e.g. restored from disk). */
+    handled?: Set<string>;
+    /** Per-PR fix-wave counts, carried across restarts so the budget survives a restart. */
+    waves?: Map<string, number>;
+    /** Cap on fix waves per PR before escalating to a human. Defaults to DEFAULT_MAX_WAVES. */
+    maxWaves?: number;
+    /** Abort signal — resolves the loop at the next interval boundary. */
+    shouldStop?: () => boolean;
+}
+export interface PrWatchResult {
+    polls: number;
+    spawned: number;
+    /** How many PRs escalated to a human (wave budget exhausted). */
+    neededHuman: number;
+    handled: Set<string>;
+    waves: Map<string, number>;
+    stoppedBy: 'max-polls' | 'signal';
+}
+/**
+ * Run the pr-watch poll loop. Each pass: retire the dedupe guards of any fixers
+ * that have finished (so a still-red check can spawn its next wave), resolve watch
+ * targets, snapshot each PR, decide actions against the running `handled` set and
+ * per-PR `waves` budget, then react — spawning fresh fixers, or emitting a
+ * one-shot `needs-human` event once a PR's wave budget is spent. Every acted-on
+ * dedupe key is recorded so a failure/comment never spawns twice within a wave,
+ * and `waves` hard-caps the total spawns per PR (issue #338).
+ */
+export declare function runPrWatch(deps: PrWatchDeps, opts?: PrWatchOptions): Promise<PrWatchResult>;