opencode-swarm 7.167.1 → 7.168.0

package/dist/commands/close.d.ts

@@ -1,402 +1,10 @@
-import * as fsSync from 'node:fs';
-import { loadPluginConfigWithMeta } from '../config';
-import type { Plan } from '../config/plan-schema';
-import { type KnowledgeConfig, type PluginConfig } from '../config/schema';
-import { archiveEvidence } from '../evidence/manager';
-import { getGitRepositoryStatus, resetToMainAfterMerge, resetToRemoteBranch } from '../git/branch';
-import { createCuratorLLMDelegate } from '../hooks/curator-llm-factory';
-import { runCuratorPostMortem } from '../hooks/curator-postmortem';
-import { checkHivePromotions } from '../hooks/hive-promoter';
-import { curateAndStoreSwarm } from '../hooks/knowledge-curator';
-import { reconcilePhaseClose } from '../hooks/knowledge-receipt-ledger.js';
-import { closeSnapshotCoordinationInitialization } from '../session/snapshot-coordination-init.js';
-import { closeRepoMemory } from '../tools/repo-graph/indexed-storage';
-/** Narrow seam for receipt/plan ordering tests. */
-export declare const closeReceiptLifecycleInternals: {
-    recordPhaseCloseIntent: (directory: string, phase: string, sessionId?: string, taskId?: string) => Promise<import("../hooks/knowledge-receipt-ledger.js").ReceiptLedgerResult<{
-        event_id: string;
-    }>>;
-    reconcilePhaseClose: typeof reconcilePhaseClose;
-};
-import { runFinalizeRewardSweep } from '../memory/finalize-reward-sweep';
-import { type SessionReflectionResult } from '../services/session-reflection';
-import { endAgentSession, resetSwarmStatePreservingSingletons } from '../state';
-import { collectGarbageBestEffort, sleep } from '../utils/bun-compat.js';
-import { type CloseTerminalResult } from '../workflow/close-terminal.js';
-import { type SqliteRowCounts } from './archive-sqlite';
-interface PlanPhase {
-    id: number;
-    name: string;
-    status: string;
-    tasks: Array<{
-        id: string;
-        status: string;
-        close_reason?: string;
-    }>;
-}
-interface PlanData {
-    title: string;
-    phases: PlanPhase[];
-}
-/**
- * Close-command wrapper around the exact-task terminal reconciliation service.
- *
- * Deliberately NOT named `closePlanTerminalState`: `src/plan/manager.ts` exports a
- * distinct function by that name (ledger-first phase/projection persistence), which
- * `reconcileCloseTerminalState` itself calls downstream. Keeping the two identifiers
- * distinct avoids a same-name collision across close.ts / close-terminal.ts /
- * plan/manager.ts. The `_internals` key below stays `closePlanTerminalState` so the
- * existing test seam is unchanged.
- */
-declare function reconcileCloseTerminalStateForPlan(directory: string, targetPlan: Plan, options: {
-    actor: string;
-    requestedClosedTaskIds: string[];
-    closedPhaseIds: number[];
-    originalStatuses?: Map<string, string>;
-}): Promise<CloseTerminalResult | undefined>;
-interface CloseCommandOptions {
-    sessionID?: string;
-    skillReviewTimeoutMs?: number;
-}
-interface CurationCounts {
-    stored: number;
-    /** Issue #2077: surfaced for the reflection knowledge-delta report. */
-    reinforced: number;
-    skipped: number;
-    rejected: number;
-    quarantined: number;
-}
-interface CloseKnowledgeEntry {
-    created_at?: string;
-}
-export type ArchiveRequiredness = 'required' | 'optional';
-export type ArchiveAttempt = 'not_attempted' | 'succeeded' | 'failed';
-export type ArchiveValidation = 'not_applicable' | 'passed' | 'failed';
-export type ArchiveSourceDisposition = 'absent' | 'retained' | 'removed';
-export interface ArtifactArchiveResult {
-    artifact: string;
-    requiredness: ArchiveRequiredness;
-    attempt: ArchiveAttempt;
-    validation: ArchiveValidation;
-    source_disposition: ArchiveSourceDisposition;
-    method: string;
-    reason_code: string;
-    /** Counts only (no row content), present for validated sqlite snapshots. */
-    row_counts?: SqliteRowCounts;
-    /** Non-sensitive diagnostic. */
-    detail?: string;
-}
-export interface ArchiveStageContext {
-    directory: string;
-    swarmDir: string;
-    config: PluginConfig;
-    warnings: string[];
-}
-export interface CloseStageContext {
-    directory: string;
-    swarmDir: string;
-    planData: PlanData;
-    planExists: boolean;
-    planAlreadyDone: boolean;
-    config: KnowledgeConfig;
-    projectName: string;
-    warnings: string[];
-    closedPhases: number[];
-    closedTasks: string[];
-    sessionStart: string | undefined;
-    isForced: boolean;
-    runSkillReview: boolean;
-    options: CloseCommandOptions;
-    phases: PlanPhase[];
-    inProgressPhases: PlanPhase[];
-    curationSucceeded: boolean;
-    curationResult: CurationCounts | undefined;
-    allLessons: string[];
-    explicitLessons: string[];
-    retroLessons: string[];
-    knowledgeSkillHint: string;
-    skillReviewSummary: string;
-    postMortemSummary: string;
-    sessionReflection: SessionReflectionResult | undefined;
-    hivePromoted: number;
-    sessionKnowledgeCreated: number;
-    fallbackKnowledgeCreated: number;
-    /** Issue #2077: FR-015 dedup drop count (retro lessons dropped as already-known). */
-    dedupDropped: number;
-    /** Issue #2077: false when the dedup knowledge read failed (fail-open). */
-    dedupAvailable: boolean;
-    /** Issue #2077: total retro lessons before dedup. */
-    retroLessonTotal: number;
-    /** Issue #2077: full-auto state computed once, reused at reflection + menu render. */
-    fullAuto: boolean;
-    originalStatuses: Map<string, string>;
-    guaranteeResult: {
-        closedPhaseIds: number[];
-        closedTaskIds: string[];
-    };
-    terminalizationError?: string;
-    archiveResult: string;
-    archivedFileCount: number;
-    archivedActiveStateFiles: Set<string>;
-    archivedActiveStateDirs: Set<string>;
-    archiveFailureReasons: Map<string, string>;
-    /** Structured per-artifact results — single source of truth (issue #2030). */
-    archiveResults: ArtifactArchiveResult[];
-    /** True when the archive STAGE threw wholesale (e.g. mkdir EACCES/ENOSPC). */
-    archiveStageFailed: boolean;
-    timestamp: string;
-    archiveDir: string;
-    archiveSuffix: string;
-    args: string[];
-}
-declare function archiveCloseSummary(ctx: Pick<CloseStageContext, 'archiveStageFailed' | 'archiveDir' | 'warnings'>, closeSummaryPath: string, summaryWritten: boolean): Promise<void>;
-declare function countSessionKnowledgeEntries(entries: CloseKnowledgeEntry[], sessionStart: string | undefined, fallbackCount: number): number;
-/**
- * Backward-compatible wrapper that returns only the copied count.
- * Direct callers (including tests) that expect a number continue to work.
- * Use copyDirRecursiveWithFailures when per-file failure tracking is needed.
- */
-declare function copyDirRecursive(src: string, dest: string): Promise<number>;
-/**
- * Flat-file artifacts to include in the archive bundle.
- * Each entry is a relative path under .swarm/.
- *
- * plan-ledger.jsonl is included so the archive bundle is a self-contained
- * forensic snapshot of the session: the ledger holds the full audit trail of
- * task state transitions and snapshot events that plan.json/plan.md don't
- * preserve.
- */
-export declare const ARCHIVE_ARTIFACTS: string[];
-/**
- * Active-state flat files to clean after archiving so future swarms start clean.
- *
- * plan.json, plan.md, and plan-ledger.jsonl are all removed so the next /swarm
- * session starts with a clean slate. The user's original ask for /swarm close
- * was to "archive plan files so future swarms aren't confused" — leaving a
- * terminal-state plan.json in place violates that invariant because the next
- * session's loadPlan() would pick it up as if it were still active.
- *
- * CRITICAL: the ledger must also be removed. Without this, loadPlan()'s Step 4
- * would see no plan.json but a surviving ledger, call replayFromLedger(), and
- * materialize the CLOSED plan back into plan.json on the next session. The
- * ledger is a second backing store for the same "terminal-state plan" and
- * leaving it behind re-enables the exact bug this cleanup is meant to fix.
- * The archive-first guard below ensures we only delete files we successfully
- * copied to the archive bundle, so the audit trail is preserved in the bundle.
- *
- * knowledge-rejected.jsonl, repo-graph.json, doc-manifest.json,
- * dark-matter.md, telemetry.jsonl, and swarm.db are
- * session-generated artifacts that do not persist meaningfully across sessions —
- * they are recreated on next session init and must be removed to avoid stale-state
- * interference.
- *
- * The SQLite WAL sidecars swarm.db-shm and swarm.db-wal are deliberately NOT in
- * either list (the archive-first guard would preserve them anyway): since #2483
- * they are removed immediately AFTER the swarm.db unlink by
- * removeSqliteSidecarsAfterClose, deliberately reversing #1692. Post-unlink the
- * sidecar paths are meaningless for future opens (no new opener can attach),
- * live processes keep their already-open fds so deleting the PATH cannot
- * corrupt them, and a Windows open-handle collision yields EBUSY which the
- * helper skips fail-open.
- *
- * Note: knowledge.jsonl is intentionally NOT cleaned because it contains cumulative
- * project knowledge (lessons learned) that should persist across sessions and finalize
- * cycles. The archive step still creates a backup for safety.
- * close-summary.md is NOT cleaned because it is written as the final close output
- * AFTER the clean stage runs. spec.md IS cleaned: it is single-session state coupled
- * to the plan lifecycle (the plan it produced is removed above), so leaving it behind
- * makes the next session pick up a stale spec via readEffectiveSpecSync and mis-route
- * the architect into CLARIFY-SPEC/overwrite prompts. It is archived first (archive-first
- * guard), so the forensic copy is preserved in the bundle. The earlier "spec.md may not
- * exist" rationale was wrong — handoff.md is equally optional and is cleaned the same way.
- * session-reflection.md is a single-session snapshot (not cumulative like
- * knowledge.jsonl) so it IS cleaned to maintain the clean-slate invariant.
- * spec-staleness.json and spec-snapshot.md are the same class of single-session
- * spec-drift state as spec.md. spec-staleness.json is an existence-only gate
- * checked unconditionally by enforceSpecDriftGate, which hard-blocks the core
- * write tools (save_plan, update_task_status, phase_complete,
- * lean_turbo_run_phase, lean_turbo_acquire_locks) with SPEC_DRIFT_BLOCK — a
- * survivor would block the NEXT session against drift that no longer applies.
- * spec-snapshot.md is its companion diff source, feeding the mismatch shown in
- * the SPEC_DRIFT_BLOCK message. Both are archived first (archive-first guard),
- * then cleaned so the next session starts drift-free.
- */
-export declare const ACTIVE_STATE_TO_CLEAN: string[];
-/**
- * Active-state directories to archive and clean after archiving.
- * These contain session-generated data that must be removed so future
- * swarms start clean. Each entry is a relative path under .swarm/.
- */
-export declare const ACTIVE_STATE_DIRS_TO_CLEAN: string[];
-/**
- * Guarantee all phases and tasks in a plan are marked complete/closed.
- * Mutates planData in place. Returns actual IDs of newly closed phases and
- * tasks so the caller can track only genuinely new closures (idempotent).
- */
-declare function guaranteeAllPlansComplete(planData: PlanData): {
-    closedPhaseIds: number[];
-    closedTaskIds: string[];
-};
-export interface GitAlignResult {
-    gitAlignResult: string;
-    prunedBranches: string[];
-}
-export interface CleanStageResult {
-    cleanedFiles: string[];
-    configBackupsRemoved: number;
-    swarmPlanFilesRemoved: number;
-    /**
-     * Stale atomic-write temp files MOVED into `.swarm/quarantine/<batch>/`
-     * (issue #2035). Quarantine is a recoverable move with a manifest — the
-     * pre-#2035 blind `.tmp.*` unlink sweep is gone; preserved candidates
-     * (recent/active/tracked/ambiguous) are counted in `residuePreserved`.
-     */
-    residueQuarantined: number;
-    residuePreserved: number;
-}
-/**
- * Emit the single `close_archive_result` telemetry event whose payload is the
- * SAME `ctx.archiveResults` array the user-facing prose derives from, so the
- * two cannot disagree (issue #2030 item 6). Called AFTER `runCleanStage` so
- * `source_disposition` can be finalized truthfully: artifacts that were
- * successfully archived AND then unlinked by the clean stage report `'removed'`;
- * artifacts preserved (absent, or failed/retained) keep their archive-time
- * disposition. Counts only — no row content (issue items 4/9).
- */
-export declare function emitCloseArchiveResult(ctx: CloseStageContext, cleanResult: CleanStageResult): void;
-/**
- * STAGE 1: FINALIZE
- *
- * Writes retrospectives for in-progress phases (or a session-level retro for
- * plan-free closes), curates lessons, promotes to hive, runs skill review,
- * persists terminal plan state, and runs post-mortem. All state mutations are
- * written back to ctx so the caller can build the close summary.
- */
-export declare function runFinalizeStage(ctx: CloseStageContext): Promise<void>;
-/**
- * STAGE 2: ARCHIVE
- *
- * Creates a timestamped archive bundle under .swarm/archive/, copies flat-file
- * artifacts and active-state directories, then runs the evidence retention
- * policy. All state mutations (archive path, counts, success sets) are written
- * back to ctx so the caller can build the close summary.
- */
-export declare function runArchiveStage(ctx: CloseStageContext): Promise<void>;
-/**
- * Runs the evidence-retention sub-logic of STAGE 2 (ARCHIVE).
- * Reads max_age_days / max_bundles / cache_max_bytes / cache_max_records from
- * config.evidence (FR-016, issue #1184) and calls archiveEvidence. The report
- * overload is used so the documents-cache prune runs when cache caps are set.
- * Fail-open: pushes a warning on error but never throws.
- */
-export declare function runArchiveEvidenceRetention(ctx: ArchiveStageContext): Promise<void>;
-/**
- * Delete one archived active-state artifact, tolerating the short-lived file
- * locks Windows antivirus and SQLite sidecars can retain after handle close.
- * Non-transient errors fail immediately; the retry budget is bounded to
- * 375 ms so `/swarm close` remains responsive.
- */
-declare function unlinkActiveStateFileWithRetry(filePath: string): Promise<void>;
-/**
- * Remove the SQLite WAL sidecars (swarm.db-wal / swarm.db-shm) immediately
- * after the clean stage unlinks swarm.db (#2483, deliberately reversing the
- * #1692 preserve decision): once the main db is unlinked the sidecar paths
- * are meaningless for future opens — no new opener can attach — and live
- * processes keep their already-open fds, so deleting the PATH cannot corrupt
- * them. Best-effort and per-file fail-open: ENOENT (already gone) and EBUSY
- * (Windows open-handle collision) are skipped silently.
- */
-export declare function removeSqliteSidecarsAfterClose(swarmDir: string): void;
-export declare function runCleanStage(ctx: CloseStageContext): Promise<CleanStageResult>;
-/**
- * STAGE 4: ALIGN
- *
- * Performs safe git alignment to main (resetToMainAfterMerge / resetToRemoteBranch
- * via _internals), handling post-merge scenarios and non-git directories.
- * Returns { gitAlignResult, prunedBranches } so the orchestrator can build
- * the close summary. All warnings are pushed into ctx.warnings.
- */
-export declare function runAlignStage(ctx: CloseStageContext): Promise<GitAlignResult>;
-/**
- * Builds the `/swarm finalize --dry-run` report. Purely READ-ONLY: inspects the
- * plan and the filesystem and describes what a real finalize WOULD do, without
- * acquiring the finalize lock, creating an archive bundle, deleting any file,
- * running git, or tearing down session state. (#1692)
- *
- * The archive-first guard means the clean stage only removes files it first
- * archived successfully; this report approximates that by listing existing
- * clean-set members as "would remove" and notes the approximation.
- */
-export declare function runFinalizeDryRun(directory: string, swarmDir: string, planData: PlanData, planExists: boolean): Promise<string>;
-/**
- * Handles /swarm close command - performs full terminal session finalization:
- * 0. Guarantee: mark all incomplete phases/tasks as closed
- * 1. Finalize: write retrospectives, produce terminal summary
- * 2. Archive: create timestamped bundle of swarm artifacts
- * 3. Clean: clear active-state files that confuse future swarms
- * 4. Align: safe git alignment to main
- *
- * Must be idempotent - safe to run multiple times.
- */
-export declare function handleCloseCommand(directory: string, args: string[], options?: CloseCommandOptions): Promise<string>;
-/**
- * Acquire the finalize lock for the close command (FR-012).
- * Wraps tryAcquireLock with a directory-only API.
- */
-declare function acquireFinalizeLock(directory: string): Promise<{
-    acquired: boolean;
-    release?: () => Promise<void>;
-}>;
-/**
- * Issue #2077: detect full-auto state for the action-menu prompt suppression.
- * Combines the in-memory session flag (hasActiveFullAuto) with the durable
- * run state (isFullAutoRunActive reads .swarm/full-auto-state.json) so a
- * process restart mid-run does not silently re-enable the interactive menu
- * prompt. The durable check is sync and takes a state lock; if it throws,
- * fall back to the in-memory flag alone. Caller MUST guard with a defined
- * sessionID to avoid the cross-session leak (hasActiveFullAuto(undefined)
- * scans all sessions).
- */
-declare function detectFullAuto(directory: string, sessionID: string): boolean;
-export declare const _internals: {
-    closeSnapshotCoordinationInitialization: typeof closeSnapshotCoordinationInitialization;
-    closeRepoMemory: typeof closeRepoMemory;
-    unlinkActiveStateFileWithRetry: typeof unlinkActiveStateFileWithRetry;
-    unlink: typeof fsSync.promises.unlink;
-    unlinkSidecarSync: typeof fsSync.unlinkSync;
-    sleep: typeof sleep;
-    collectGarbageBestEffort: typeof collectGarbageBestEffort;
-    ACTIVE_STATE_DIRS_TO_CLEAN: string[];
-    countSessionKnowledgeEntries: typeof countSessionKnowledgeEntries;
-    CLOSE_SKILL_REVIEW_TIMEOUT_MS: number;
-    CLOSE_REFLECTION_TIMEOUT_MS: number;
-    detectFullAuto: typeof detectFullAuto;
-    guaranteeAllPlansComplete: typeof guaranteeAllPlansComplete;
-    getGitRepositoryStatus: typeof getGitRepositoryStatus;
-    resetToMainAfterMerge: typeof resetToMainAfterMerge;
-    resetToRemoteBranch: typeof resetToRemoteBranch;
-    copyDirRecursive: typeof copyDirRecursive;
-    loadPluginConfigWithMeta: typeof loadPluginConfigWithMeta;
-    curateAndStoreSwarm: typeof curateAndStoreSwarm;
-    checkHivePromotions: typeof checkHivePromotions;
-    runCuratorPostMortem: typeof runCuratorPostMortem;
-    createCuratorLLMDelegate: typeof createCuratorLLMDelegate;
-    resetSwarmStatePreservingSingletons: typeof resetSwarmStatePreservingSingletons;
-    runFinalizeStage: typeof runFinalizeStage;
-    runFinalizeRewardSweep: typeof runFinalizeRewardSweep;
-    acquireFinalizeLock: typeof acquireFinalizeLock;
-    runArchiveStage: typeof runArchiveStage;
-    archiveCloseSummary: typeof archiveCloseSummary;
-    runArchiveEvidenceRetention: typeof runArchiveEvidenceRetention;
-    runCleanStage: typeof runCleanStage;
-    runAlignStage: typeof runAlignStage;
-    runFinalizeDryRun: typeof runFinalizeDryRun;
-    archiveEvidence: typeof archiveEvidence;
-    closePlanTerminalState: typeof reconcileCloseTerminalStateForPlan;
-    endAgentSession: typeof endAgentSession;
-    flushAndDrainTelemetry: () => Promise<void>;
-    finalizeContextTelemetry: (directory: string) => void;
-    finalizeCoreEvents: (directory: string) => void;
-    finalizeShellAudit: (directory: string) => void;
-};
-export {};
+export { runAlignStage } from './close/align-stage.js';
+export { emitCloseArchiveResult, runArchiveEvidenceRetention, runArchiveStage, } from './close/archive-stage.js';
+export { runCleanStage } from './close/clean-stage.js';
+export { ACTIVE_STATE_DIRS_TO_CLEAN, ACTIVE_STATE_TO_CLEAN, ARCHIVE_ARTIFACTS, } from './close/constants.js';
+export type { ArchiveAttempt, ArchiveRequiredness, ArchiveSourceDisposition, ArchiveStageContext, ArchiveValidation, ArtifactArchiveResult, CleanStageResult, CloseStageContext, GitAlignResult, } from './close/context.js';
+export { removeSqliteSidecarsAfterClose } from './close/db-helpers.js';
+export { runFinalizeDryRun } from './close/dry-run.js';
+export { runFinalizeStage } from './close/finalize-stage.js';
+export { _internals, closeReceiptLifecycleInternals, } from './close/internals.js';
+export { handleCloseCommand } from './close/orchestrator.js';

package/dist/commands/reset.d.ts

@@ -1,3 +1,6 @@
+import * as fs from 'node:fs';
+import { clearPlanLedgerForReset } from '../plan/ledger.js';
+import { withPlanLifecycleLock } from '../plan/manager.js';
 import { type ResetBackupResult } from './reset-backup';
 /**
  * _internals DI seam so tests can stub the pre-deletion backup without touching
@@ -6,6 +9,13 @@ import { type ResetBackupResult } from './reset-backup';
  */
 export declare const _internals: {
     backupSwarmStateBeforeReset: (directory: string, kind: 'reset' | 'reset-session', relEntries: string[]) => ResetBackupResult;
+    clearPlanLedgerForReset: typeof clearPlanLedgerForReset;
+    withPlanLifecycleLock: typeof withPlanLifecycleLock;
+    existsSync: typeof fs.existsSync;
+    readFileSync: typeof fs.readFileSync;
+    unlinkSync: typeof fs.unlinkSync;
+    writeFileSync: typeof fs.writeFileSync;
+    rmSync: typeof fs.rmSync;
 };
 /**
  * Handles the /swarm reset command.

package/dist/commands/rollback.d.ts

@@ -1,3 +1,12 @@
+import { clearPlanLedgerForReset, peekPlanFromLedger, replacePlanLedgerWithRoot } from '../plan/ledger';
+import { withPlanLifecycleLock } from '../plan/manager';
+/** Test-only seam for the atomic ledger re-root lifecycle transition. */
+export declare const _internals: {
+    replacePlanLedgerWithRoot: typeof replacePlanLedgerWithRoot;
+    clearPlanLedgerForReset: typeof clearPlanLedgerForReset;
+    peekPlanFromLedger: typeof peekPlanFromLedger;
+    withPlanLifecycleLock: typeof withPlanLifecycleLock;
+};
 /**
  * Handle /swarm rollback command
  * Restores .swarm/ state from a checkpoint using direct overwrite

package/dist/config/schema.d.ts

@@ -1395,6 +1395,7 @@ export declare const WorktreeIsolationConfigSchema: z.ZodObject<{
     }>>;
     serialization_release_after_dispatches: z.ZodDefault<z.ZodNumber>;
     serialization_release_after_ms: z.ZodDefault<z.ZodNumber>;
+    session_create_timeout_ms: z.ZodDefault<z.ZodNumber>;
     runtime_isolation: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         port_base: z.ZodOptional<z.ZodNumber>;
@@ -1889,6 +1890,26 @@ export declare const LaneLivenessWatchdogConfigSchema: z.ZodObject<{
     stall_token_threshold: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strict>;
 export type LaneLivenessWatchdogConfig = z.infer<typeof LaneLivenessWatchdogConfigSchema>;
+/**
+ * Issue #2507 dispatch protection: an action-local spawn-protection circuit
+ * plus a token-bucket dispatch rate limit for native task delegations.
+ *
+ * Default-ON follows the guardrails family (`guardrails.enabled` defaults
+ * true): the numbers are deliberately conservative (10 dispatches per second
+ * with a burst of 10 never waits in normal use), and every knob is
+ * user-overridable — set `enabled: false` to opt out entirely, or
+ * `rate_per_second: 0` to disable only the limiter. Parameter surface
+ * adopted with credit from opencode-ensemble (reimplemented per ADR 0002 —
+ * no upstream code is ported).
+ */
+export declare const DispatchProtectionConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    spawn_failure_threshold: z.ZodDefault<z.ZodNumber>;
+    half_open_after_ms: z.ZodDefault<z.ZodNumber>;
+    rate_per_second: z.ZodDefault<z.ZodNumber>;
+    burst_capacity: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export type DispatchProtectionConfig = z.infer<typeof DispatchProtectionConfigSchema>;
 /**
  * Issue #2384: deprecated transcript-row settlement for Profile A PR-review
  * base/micro discovery lanes is an explicit compatibility opt-in. Omitted
@@ -2001,6 +2022,13 @@ export declare const PluginConfigSchema: z.ZodObject<{
         stall_min_steps: z.ZodDefault<z.ZodNumber>;
         stall_token_threshold: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strict>>;
+    dispatch_protection: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        spawn_failure_threshold: z.ZodDefault<z.ZodNumber>;
+        half_open_after_ms: z.ZodDefault<z.ZodNumber>;
+        rate_per_second: z.ZodDefault<z.ZodNumber>;
+        burst_capacity: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
     pr_review_legacy_transcript_compatibility: z.ZodOptional<z.ZodBoolean>;
     gates: z.ZodOptional<z.ZodObject<{
         syntax_check: z.ZodDefault<z.ZodObject<{
@@ -2801,6 +2829,7 @@ export declare const PluginConfigSchema: z.ZodObject<{
         }>>;
         serialization_release_after_dispatches: z.ZodDefault<z.ZodNumber>;
         serialization_release_after_ms: z.ZodDefault<z.ZodNumber>;
+        session_create_timeout_ms: z.ZodDefault<z.ZodNumber>;
         runtime_isolation: z.ZodOptional<z.ZodObject<{
             enabled: z.ZodDefault<z.ZodBoolean>;
             port_base: z.ZodOptional<z.ZodNumber>;

package/dist/db/project-db.d.ts

@@ -39,6 +39,14 @@ export declare function projectDbPath(directory: string): string;
  * workspace just to check for a missing record.
  */
 export declare function projectDbExists(directory: string): boolean;
+/**
+ * Open the existing project database for one observational callback.
+ *
+ * Unlike `getProjectDb`, this never creates directories, negotiates WAL, runs
+ * migrations, or enters the shared connection cache. It is the only suitable
+ * path for lifecycle previews such as `/swarm close --dry-run`.
+ */
+export declare function withProjectDbReadOnly<T>(directory: string, read: (db: Database) => T): T | null;
 /**
  * Best-effort WAL checkpoint before close (issue #2480 checkpoint policy).
  *

package/dist/db/sqlite-loader.d.ts

@@ -51,8 +51,9 @@ interface NodeDatabaseSync {
     loadExtension(path: string): void;
     close(): void;
 }
-type NodeDatabaseSyncCtor = new (filename: string, options?: {
+type NodeDatabaseSyncCtor = new (filename: string | URL, options?: {
     allowExtension?: boolean;
+    readOnly?: boolean;
 }) => NodeDatabaseSync;
 /**
  * Build a `bun:sqlite`-`Database`-compatible constructor backed by `node:sqlite`'s

package/dist/dispatch/spawn-circuit.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Action-local spawn-protection circuit for native task delegations
+ * (issue #2507 / ADR 0002 G3 — reimplemented, no upstream code ported).
+ *
+ * Ownership boundary (one accounting owner per failure category,
+ * docs/invocation-failures.md): this circuit owns repeated ACTUAL dispatch
+ * failures of the SAME semantic action on the native `task` route. Policy
+ * denials stay with the gate-denial tracker, shell-structural failures with
+ * the non-transient circuit, PR-review lane provider-terminal with the
+ * PR-review resilience circuit, provable-non-acceptance launch retry with
+ * #2473, and lane liveness with #2506.
+ *
+ * State machine (the src/pr-review/circuit.ts timed HALF_OPEN precedent):
+ * CLOSED -> (threshold failures) -> OPEN -> (denyUntil elapses, next dispatch
+ * admitted) -> HALF_OPEN (exactly one probe) -> completed probe closes |
+ * failed probe re-opens with a fresh interval.
+ *
+ * The state is process-local, invocation-owned, and bounded — the
+ * docs/invocation-failures.md contract for action circuits (only the
+ * PR-review resilience circuit is durable).
+ */
+/** Bounded memory: same discipline as MAX_TRACKED_ACTION_CIRCUITS. */
+export declare const MAX_TRACKED_SPAWN_CIRCUITS = 500;
+export declare const SPAWN_CIRCUIT_TTL_MS: number;
+/** Bounded armed-digest map (late toolAfter results must not grow it). */
+export declare const MAX_ARMED_DISPATCH_IDENTITIES = 500;
+/** Frozen denial code — gate-denial-tracker exempts exactly this code. */
+export declare const SPAWN_CIRCUIT_DENIAL_CODE = "SPAWN PROTECTION CIRCUIT OPEN";
+export interface SpawnCircuitEntry {
+    state: 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+    sessionID: string;
+    invocationID: string;
+    actionDigest: string;
+    failureCount: number;
+    openedAt: number;
+    denyUntil: number;
+    /** Denials issued in the current OPEN episode (reset on each OPEN). */
+    denialsInEpisode: number;
+    updatedAt: number;
+}
+export declare function invocationIdForSession(sessionID: string): string;
+/**
+ * Compute the dispatch identity for a tool + args WITHOUT storing anything.
+ * Shared by armDispatchIdentity (before-hook step 0) and by the after-hook
+ * recorder's fallback (which must not re-insert into the bounded armed map
+ * — a stored-but-never-consumed entry would evict legitimate pending
+ * identities under review feedback WD-1).
+ */
+export declare function dispatchIdentityFor(tool: string, args: unknown): {
+    digest: string;
+    pattern: string;
+};
+/**
+ * Arm the pre-mutation dispatch identity for a callID. Step 0 of the
+ * fail-closed tool.execute.before region calls this BEFORE any hook can
+ * mutate `output.args` (skill / delegate-directive injection), so the
+ * toolAfter recorder consumes the SAME digest the circuit was keyed with —
+ * a corrected success can never clear a phantom key (plan Round 1
+ * revision 2).
+ */
+export declare function armDispatchIdentity(callID: string, tool: string, args: unknown): {
+    digest: string;
+    pattern: string;
+};
+/** Consume the armed identity for a callID (fallback: undefined). */
+export declare function takeArmedDispatchIdentity(callID: string): {
+    digest: string;
+    pattern: string;
+} | undefined;
+/**
+ * Record one ACTUAL dispatch failure for the matching action. Returns the
+ * entry and whether this call performed the CLOSED->OPEN transition (the
+ * caller emits exactly one bounded telemetry event on that transition).
+ */
+export declare function noteDispatchSpawnFailure(input: {
+    sessionID: string;
+    invocationID: string;
+    actionDigest: string;
+    threshold: number;
+    halfOpenAfterMs: number;
+    now?: number;
+}): {
+    entry: SpawnCircuitEntry;
+    opened: boolean;
+};
+/**
+ * Deny when the matching action's circuit is OPEN (before its interval
+ * elapses) or when a half-open probe is already in flight. When the open
+ * interval has elapsed, this call is ADMITTED as the single probe.
+ * Throws an Error whose leading token is the frozen
+ * SPAWN_CIRCUIT_DENIAL_CODE so the gate-denial tracker can exempt it.
+ */
+export declare function assertDispatchSpawnCircuitAdmits(input: {
+    sessionID: string;
+    invocationID: string;
+    actionDigest: string;
+    threshold: number;
+    halfOpenAfterMs: number;
+    now?: number;
+}): void;
+/**
+ * A corrected successful execution clears ONLY the matching action's entry
+ * (and closes an in-flight half-open probe). Failures of other actions are
+ * never touched.
+ */
+export declare function noteDispatchSpawnSuccess(input: {
+    sessionID: string;
+    invocationID: string;
+    actionDigest: string;
+}): void;
+export declare function getSpawnCircuitEntry(input: {
+    sessionID: string;
+    invocationID: string;
+    actionDigest: string;
+}): SpawnCircuitEntry | undefined;
+export declare function spawnCircuitIsTaskTool(tool: string): boolean;
+/** Test seam: reset all circuits + armed identities between test files. */
+export declare function _clearAllSpawnCircuits(): void;
+export declare const _internals: {
+    now: () => number;
+};