opencode-swarm 7.66.3 → 7.68.0

package/README.md

@@ -38,6 +38,7 @@ Most AI coding tools let one model write code and ask that same model whether th
 - 🔬 **External Skill Curation Pipeline** — Opt-in discovery, quarantine, evaluation, and promotion of external skill candidates from configured sources (disabled by default; enable via `external_skills.curation_enabled: true` in config). Includes 7 tools: `external_skill_discover`, `external_skill_list`, `external_skill_inspect`, `external_skill_promote`, `external_skill_reject`, `external_skill_delete`, `external_skill_revoke`. Candidates pass through a 3-gate validation pipeline before evaluation: **prompt injection scan** (12 regex patterns), **unsafe instruction scan** (25 patterns), and **provenance integrity check** (SHA-256, timestamp, URL, publisher, and hash verification).
 - 🔄 **Phase completion gates** — completion-verify and drift verifier gates enforced before phase completion
 - 🔁 **Resumable sessions** — all state saved to `.swarm/`; pick up any project any day
+- 🖥️ **PR Monitor** — GitHub PR subscription and background polling via `gh` CLI; delivers real-time CI, review, and merge status updates via the AutomationEventBus (FR-001, opt-in via `pr_monitor.enabled: true`). Subscribe with `/swarm pr subscribe <pr-url|owner/repo#N|N>`; unsubscribe with `/swarm pr unsubscribe <pr-url|owner/repo#N|N>`; check status with `/swarm pr status`. Enable `auto_pr_feedback: true` in `pr_monitor` config to inject `[MODE: PR_FEEDBACK pr="URL"]` on CI failures and merge conflicts automatically.
 - 🌐 **20 languages** — TypeScript, Python, Go, Rust, Java, Kotlin, C/C++, C#, Ruby, Swift, Dart, PHP, JavaScript, CSS, Bash, PowerShell, INI, Regex (extending: see [docs/adding-a-language.md](docs/adding-a-language.md))
 - 🛡️ **Built-in security** — SAST, secrets scanning, dependency audit per task
 - 🔒 **Scope enforcement** — Validates write targets against declared scope with cross-process persistence, TTL expiry, and scope-aware destructive command blocking. **Handles both single-string and array-based path arguments** (`files[]`, `paths[]`, `targetFiles[]`) to prevent scope bypass via multi-file tool calls.
@@ -1100,6 +1101,9 @@ Control how tool outputs are summarized for LLM context.
 | `/swarm issue <issue-url\|owner/repo#N\|N> [--plan] [--trace]` | Ingest a GitHub issue for localization and resolution |
 | `/swarm pr-review <pr-url\|owner/repo#N\|N> [--council] [instructions...]` | Structured deep PR review with parallel lanes, reviewer confirmation, and critic challenge |
 | `/swarm pr-feedback [<pr-url\|owner/repo#N\|N>] [instructions...]` | Ingest and close known PR feedback (review comments, CI failures, conflicts) without a fresh review |
+| `/swarm pr subscribe <pr-url\|owner/repo#N\|N>` | Subscribe current session to PR monitoring (session-scoped); requires `pr_monitor.enabled: true` |
+| `/swarm pr unsubscribe <pr-url\|owner/repo#N\|N>` | Remove session's subscription to a PR |
+| `/swarm pr status` | List active PR subscriptions for current session with relative timestamps |
 | `/swarm deep-dive <scope> [--profile <name>] [--max-explorers <n>]` | Read-only codebase audit with parallel explorers, dual reviewers, and critic challenge |
 | `/swarm design-docs <description> [--out <dir>] [--lang <name>] [--update]` | Generate or sync language-agnostic design docs (requires `design_docs.enabled`) |
 | `/swarm dark-matter` | Detect hidden file couplings from co-change history |

package/dist/background/event-bus.d.ts

@@ -5,7 +5,7 @@
  * Events flow through the system without external dependencies.
  */
 /** Automation event types */
-export type AutomationEventType = 'queue.item.enqueued' | 'queue.item.dequeued' | 'queue.item.completed' | 'queue.item.failed' | 'queue.item.retry scheduled' | 'worker.started' | 'worker.stopped' | 'worker.error' | 'circuit.breaker.opened' | 'circuit.breaker.half-open' | 'circuit.breaker.closed' | 'loop.protection.triggered' | 'automation.started' | 'automation.stopped' | 'preflight.requested' | 'preflight.triggered' | 'preflight.skipped' | 'preflight.completed' | 'phase.boundary.detected' | 'phase.status.checked' | 'task.completed' | 'evidence.summary.generated' | 'evidence.summary.error' | 'curator.init.completed' | 'curator.init.llm_completed' | 'curator.init.llm_fallback' | 'curator.phase.completed' | 'curator.phase.llm_completed' | 'curator.phase.llm_fallback' | 'curator.drift.completed' | 'curator.docdrift.completed' | 'curator.error';
+export type AutomationEventType = 'queue.item.enqueued' | 'queue.item.dequeued' | 'queue.item.completed' | 'queue.item.failed' | 'queue.item.retry scheduled' | 'worker.started' | 'worker.stopped' | 'worker.error' | 'circuit.breaker.opened' | 'circuit.breaker.half-open' | 'circuit.breaker.closed' | 'loop.protection.triggered' | 'automation.started' | 'automation.stopped' | 'preflight.requested' | 'preflight.triggered' | 'preflight.skipped' | 'preflight.completed' | 'phase.boundary.detected' | 'phase.status.checked' | 'task.completed' | 'evidence.summary.generated' | 'evidence.summary.error' | 'curator.init.completed' | 'curator.init.llm_completed' | 'curator.init.llm_fallback' | 'curator.phase.completed' | 'curator.phase.llm_completed' | 'curator.phase.llm_fallback' | 'curator.drift.completed' | 'curator.docdrift.completed' | 'curator.error' | 'pr.subscribed' | 'pr.unsubscribed' | 'pr.status.updated' | 'pr.ci.failed' | 'pr.ci.passed' | 'pr.new.comment' | 'pr.merge.conflict' | 'pr.merge.conflict_resolved' | 'pr.merged' | 'pr.closed' | 'pr.review.approved' | 'pr.review.changes_requested' | 'pr.subscription.expired' | 'pr.error';
 /** Base automation event */
 export interface AutomationEvent<T = unknown> {
     type: AutomationEventType;

package/dist/background/index.d.ts

@@ -16,6 +16,8 @@ export { type AutomationEvent, AutomationEventBus, type AutomationEventType, } f
 export { createEvidenceSummaryIntegration, type EvidenceSummaryIntegrationConfig, type EvidenceSummaryTriggerEvent, type EvidenceSummaryTriggerPayload, } from './evidence-summary-integration';
 export { type AutomationFrameworkConfig, BackgroundAutomationManager, createAutomationManager, } from './manager';
 export { PlanSyncWorker, type PlanSyncWorkerOptions, type PlanSyncWorkerStatus, } from './plan-sync-worker';
+export { type PrEventSubscriberOptions, registerPrEventSubscribers, } from './pr-event-subscribers';
+export { PrMonitorWorker, type PrMonitorWorkerOptions, type PrMonitorWorkerStatus, } from './pr-monitor-worker';
 export { AutomationQueue, type QueueItem, type QueuePriority, type RetryMetadata, } from './queue';
 export { AutomationStatusArtifact, type AutomationStatusSnapshot, } from './status-artifact';
 export { type PhaseBoundaryResult, PhaseBoundaryTrigger, type PreflightHandler, type PreflightRequest, type PreflightRequestPayload, type PreflightTriggerConfig, type PreflightTriggerEventType, PreflightTriggerManager, } from './trigger';

package/dist/background/pr-event-subscribers.d.ts

@@ -0,0 +1,46 @@
+/**
+ * PR Event Bus Subscribers — Advisory notification delivery.
+ *
+ * Subscribes to PR events on the global event bus and delivers structured
+ * advisory messages to ALL active sessions that are subscribed to the
+ * relevant PR. Each event type is gated by a config flag from PrMonitorConfig.
+ *
+ * Fail-open: errors in delivery never crash the event bus.
+ * Dedup: advisories are deduped per session per PR+event type.
+ */
+import type { PrMonitorConfig } from '../config/schema';
+import { getAgentSession } from '../state';
+import { log } from '../utils';
+import { getGlobalEventBus } from './event-bus';
+import { listActive } from './pr-subscriptions';
+export interface PrEventSubscriberOptions {
+    directory: string;
+    config: PrMonitorConfig;
+}
+/**
+ * DI seam for testability. Exposes internal functions that are replaced
+ * in tests via the _internals object.
+ */
+export declare const _internals: {
+    handlePrEvent: typeof handlePrEvent;
+    getGlobalEventBus: typeof getGlobalEventBus;
+    listActive: typeof listActive;
+    getAgentSession: typeof getAgentSession;
+    log: typeof log;
+};
+/**
+ * Register subscribers on the global event bus for the three gated PR event
+ * types. Returns a cleanup function that unsubscribes all listeners.
+ *
+ * Skips event types whose config flag is disabled (false).
+ */
+export declare function registerPrEventSubscribers(options: PrEventSubscriberOptions): () => void;
+/**
+ * Handle a single PR event: look up active subscriptions matching the event's
+ * repo+PR, format an advisory, and push it to every matching session.
+ */
+declare function handlePrEvent(event: {
+    type: string;
+    payload: unknown;
+}, directory: string, config: PrMonitorConfig): Promise<void>;
+export {};

package/dist/background/pr-monitor-worker.d.ts

@@ -0,0 +1,154 @@
+/**
+ * PR Monitor Worker
+ *
+ * Background polling worker that periodically checks subscribed PRs for status
+ * changes (CI, comments, merge conflicts, merge/close events) and publishes
+ * automation events. Follows the PlanSyncWorker standalone class pattern with
+ * start/stop/dispose lifecycle and bounded, fail-open operation.
+ */
+import type { PrMonitorConfig } from '../config/schema';
+import { getMergeState, getPRComments, getPRReviewState, getPRStatus } from '../git/pr';
+import { type AutomationEventType, getGlobalEventBus } from './event-bus';
+import { listActive, sweepStale, unsubscribe, updateSnapshot } from './pr-subscriptions';
+/** Configuration options for PrMonitorWorker construction. */
+export interface PrMonitorWorkerOptions {
+    /** Project root directory (parent of .swarm/). */
+    directory: string;
+    /** Parsed pr_monitor config from schema. */
+    config: PrMonitorConfig;
+    /** Optional callback for emitted events (in addition to event bus). */
+    onEvent?: (event: AutomationEvent<unknown>) => void;
+}
+/** Worker status machine states. */
+export type PrMonitorWorkerStatus = 'stopped' | 'starting' | 'running' | 'stopping';
+/** Typed wrapper around AutomationEvent for PR monitor payloads. */
+export interface AutomationEvent<T = unknown> {
+    type: AutomationEventType;
+    timestamp: number;
+    payload: T;
+    source: string;
+}
+/**
+ * PR Monitor Worker.
+ *
+ * Standalone class that polls GitHub PRs for status changes using the gh CLI
+ * wrappers. Publishes typed automation events for CI failures, new comments,
+ * merge conflicts, merge/close transitions, and head-branch updates.
+ *
+ * Lifecycle: start() → running → stop() → stopped → dispose().
+ * Fail-open: construction and poll-cycle errors are logged, never thrown.
+ */
+export declare class PrMonitorWorker {
+    private readonly directory;
+    private readonly config;
+    private readonly onEvent?;
+    private status;
+    private pollTimer;
+    private disposed;
+    /** In-memory circuit-breaker state per PR correlationId. */
+    private readonly circuitBreakerMap;
+    /** In-memory review decision per PR correlationId (not persisted). */
+    private readonly reviewStateMap;
+    /** Accumulates merged/closed PR keys during the current poll cycle for sweep cleanup. */
+    private mergedOrClosedKeys;
+    constructor(options: PrMonitorWorkerOptions);
+    /**
+     * Start the polling worker. Fail-open: logs and returns on bad state
+     * instead of throwing.
+     */
+    start(): void;
+    /**
+     * Stop the polling worker. Clears the interval timer but does not
+     * interrupt an in-flight poll cycle — it will complete and the result
+     * is discarded.
+     */
+    stop(): void;
+    /**
+     * Stop and permanently prevent restart.
+     */
+    dispose(): void;
+    /**
+     * Get current worker status.
+     */
+    getStatus(): PrMonitorWorkerStatus;
+    /**
+     * Check if worker is currently running.
+     */
+    isRunning(): boolean;
+    /**
+     * Public entry point for a single poll cycle. Checks only disposed
+     * state (not running status) so it can be invoked directly in tests
+     * or manual polling scenarios.
+     */
+    pollCycle(): Promise<void>;
+    /**
+     * Internal poll cycle implementation: fetch subscriptions, detect
+     * changes, publish events, update snapshots, run sweep.
+     */
+    private executePollCycle;
+    /**
+     * Process subscriptions with a concurrency limit using a sliding window.
+     */
+    private processWithConcurrency;
+    /**
+     * Wrap a single PR poll with a configurable timeout.
+     * If the poll exceeds poll_timeout_ms, the timeout error is
+     * delegated to handlePollError (circuit-breaker accounting) and
+     * the method resolves — it never rethrows.
+     */
+    private pollWithTimeout;
+    /**
+     * Poll a single PR subscription: fetch current state, detect changes,
+     * publish events, and update the snapshot. Handles circuit-breaking.
+     */
+    private pollSinglePr;
+    /**
+     * Pure computation: compare current fetch results against the subscription
+     * snapshot and return all events/mutations to apply. No side effects.
+     */
+    private computeChanges;
+    /**
+     * Pure computation: detect CI transitions and push events into the array.
+     */
+    private computeCIEvents;
+    /**
+     * Apply computed changes: emit events, update merged/closed tracking,
+     * unsubscribe, and update snapshot. Checks isTimedOut before each
+     * state mutation to prevent stale writes after timeout.
+     */
+    private applyChanges;
+    /**
+     * Handle a poll error for a single PR: increment error count, apply
+     * circuit-breaker suspension with exponential backoff.
+     */
+    private handlePollError;
+    /**
+     * Publish an event to the global event bus and optional callback.
+     */
+    private emitEvent;
+    /**
+     * Run stale subscription sweep if cleanup_ttl_days > 0.
+     * Passes any merged/closed PR keys observed during the poll cycle
+     * so that sweepStale can remove subscriptions for those PRs.
+     */
+    private runSweep;
+    /**
+     * Serialize statusCheckRollup to a stable string for snapshot comparison.
+     */
+    private serializeChecks;
+    /**
+     * Parse a serialized check set back into an array.
+     */
+    private parseCheckSet;
+}
+export declare const _internals: {
+    getPRStatus: typeof getPRStatus;
+    getPRComments: typeof getPRComments;
+    getMergeState: typeof getMergeState;
+    getPRReviewState: typeof getPRReviewState;
+    listActive: typeof listActive;
+    updateSnapshot: typeof updateSnapshot;
+    unsubscribe: typeof unsubscribe;
+    sweepStale: typeof sweepStale;
+    getGlobalEventBus: typeof getGlobalEventBus;
+};

package/dist/background/pr-subscriptions.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Durable PR monitoring subscription store.
+ *
+ * Append-only JSONL event log under project-root
+ * `.swarm/pr-monitor/subscriptions.jsonl`. Each line is a full record snapshot;
+ * readers fold to the latest snapshot per `correlationId`. This tracks which PRs
+ * are actively being monitored by which sessions so the background poller knows
+ * what to watch.
+ *
+ * Concurrency: all writes (subscribe, unsubscribe, update, sweep) run under a
+ * single project-scoped lock via `withEvidenceLock`, so concurrent callers cannot
+ * interleave appends. Reads are lock-free (line-oriented; partial trailing lines
+ * are skipped defensively).
+ *
+ * Containment: the path is validated with `validateSwarmPath`, so it can never
+ * escape `.swarm/` (Invariant 4).
+ */
+export declare const PR_SUBSCRIPTIONS_FILE = "pr-monitor/subscriptions.jsonl";
+/**
+ * Register the lazy-start callback invoked after a successful subscription.
+ * Called once during plugin init to wire the PR monitor worker lifecycle.
+ */
+export declare function setOnSubscriptionCreated(callback: (directory: string, record: PrSubscriptionRecord) => void): void;
+export type PrSubscriptionStatus = 'active' | 'removed' | 'expired';
+/**
+ * A durable PR monitoring subscription record. Each append to the JSONL log
+ * is a full snapshot; readers fold by correlationId (last-write-wins).
+ */
+export interface PrSubscriptionRecord {
+    /** Composite key: `${sessionID}::${repoFullName}::${prNumber}`. */
+    correlationId: string;
+    sessionID: string;
+    prNumber: number;
+    /** e.g. "owner/repo". */
+    repoFullName: string;
+    prUrl: string;
+    headRefOid?: string;
+    /** Epoch ms — last time the poller checked this PR. */
+    lastCheckedAt: number;
+    lastCommentId?: string;
+    /** JSON stringified array of check names + conclusions. */
+    lastCheckRunSet?: string;
+    mergeableState?: string;
+    isWatching: boolean;
+    /** Guard for cleanup sweep — subscriptions with unaddressed events are retained. */
+    hasUnaddressedEvents: boolean;
+    status: PrSubscriptionStatus;
+    /** Epoch ms — when the subscription was first created. */
+    createdAt: number;
+    /** Epoch ms — when this snapshot was written. */
+    updatedAt: number;
+    errorCount: number;
+    /** Per-PR poll-interval override (FR-017). */
+    customPollIntervalSeconds?: number;
+    customFailureThreshold?: number;
+    customCooldownSeconds?: number;
+}
+export interface SubscribeInput {
+    sessionID: string;
+    prNumber: number;
+    repoFullName: string;
+    prUrl: string;
+    /** Max active subscriptions allowed (for limit enforcement). */
+    maxSubscriptions?: number;
+}
+/**
+ * Build the composite correlation key from session, repo, and PR number.
+ */
+export declare function buildCorrelationId(sessionID: string, repoFullName: string, prNumber: number): string;
+/**
+ * Subscribe to PR monitoring. Appends a new `active` subscription record. If an
+ * active subscription with the same correlationId already exists, returns the
+ * existing record (idempotent). Throws if the number of active subscriptions
+ * exceeds `input.maxSubscriptions` (when provided).
+ *
+ * Runs a lazy stale sweep before the append (same pattern as
+ * pending-delegations.ts).
+ */
+export declare function subscribe(directory: string, input: SubscribeInput): Promise<PrSubscriptionRecord>;
+/**
+ * Unsubscribe from PR monitoring. Appends a new record with `status='removed'`
+ * for the given correlationId. Correlation-key folding means the latest record
+ * wins. Returns the folded record after the write, or null if no active
+ * subscription was found.
+ */
+export declare function unsubscribe(directory: string, correlationId: string): Promise<PrSubscriptionRecord | null>;
+/**
+ * List all active subscriptions. Lock-free read that folds the JSONL and
+ * returns only records with `status='active'`.
+ */
+export declare function listActive(directory: string): Promise<PrSubscriptionRecord[]>;
+/**
+ * Look up an active subscription for a specific PR. Lock-free read.
+ */
+export declare function lookupByPr(directory: string, repoFullName: string, prNumber: number): Promise<PrSubscriptionRecord | null>;
+/**
+ * Update the snapshot for a given correlationId. Merges `updates` into the
+ * existing active record and appends the new snapshot. Returns the merged
+ * record, or null if no active subscription was found.
+ */
+export declare function updateSnapshot(directory: string, correlationId: string, updates: Partial<PrSubscriptionRecord>): Promise<PrSubscriptionRecord | null>;
+/**
+ * Sweep stale subscriptions. Marks subscriptions as `expired` when:
+ *   (a) They are `active` AND appear in the `mergedPrs` set (PR was merged/closed), OR
+ *   (b) They have had no state change for `ttlDays` AND `hasUnaddressedEvents` is false.
+ *
+ * Subscriptions with `hasUnaddressedEvents === true` are NEVER swept unless the
+ * PR is in the merged/closed set.
+ *
+ * @param directory - Project root directory
+ * @param ttlDays - Days of inactivity before considering a subscription stale
+ * @param mergedPrs - Set of "repoFullName::prNumber" strings for merged/closed PRs
+ * @returns Number of subscriptions swept
+ */
+export declare function sweepStale(directory: string, ttlDays: number, mergedPrs?: ReadonlySet<string>): Promise<number>;