opencode-swarm 7.183.1 → 7.184.1

package/dist/plan/ledger.d.ts

@@ -226,7 +226,9 @@ export declare function readLedgerEvents(directory: string): Promise<LedgerEvent
  * @param directory - The working directory
  * @param planId - Unique identifier for the plan
  */
-export declare function initLedger(directory: string, planId: string, initialPlanHash?: string, initialPlan?: Plan): Promise<void>;
+export declare function initLedger(directory: string, planId: string, initialPlanHash?: string, initialPlan?: Plan, options?: {
+    preCommitCheck?: () => void;
+}): Promise<void>;
 /**
  * Read and validate the current plan epoch identity without creating,
  * adopting, or appending any ledger state.
@@ -264,6 +266,8 @@ export declare function appendLedgerEvent(directory: string, eventInput: LedgerE
      */
     expectedLedgerHash?: string;
     planHashAfter?: string;
+    /** Synchronous authority fence inside the evidence lock. */
+    preCommitCheck?: () => void;
 }): Promise<LedgerEvent>;
 /**
  * Append a ledger event with optimistic retry on stale-writer conflicts.
@@ -303,6 +307,7 @@ export declare function appendLedgerEventWithRetry(directory: string, eventInput
     maxRetries?: number;
     backoffMs?: number;
     verifyValid?: () => Promise<boolean> | boolean;
+    preCommitCheck?: () => void;
 }): Promise<LedgerEvent | null>;
 /**
  * Take a snapshot with bounded retry and always-visible warning logging (FR-004).
@@ -351,6 +356,8 @@ export declare function takeSnapshotEvent(directory: string, plan: Plan, options
     expectedSeq?: number;
     /** Previous durable hash used to preserve the ledger hash chain. */
     expectedLedgerHash?: string;
+    /** Synchronous authority fence immediately before ledger append. */
+    preCommitCheck?: () => void;
 }): Promise<LedgerEvent>;
 export interface TruncatedLedgerRecoveryResult {
     archivePath: string;
@@ -379,13 +386,17 @@ export declare function clearPlanLedgerForReset(directory: string): Promise<void
  * Existing JSONL bytes are content-addressed before the SQLite transaction;
  * the portable export is published only after the new SQLite root commits.
  */
-export declare function replacePlanLedgerWithRoot(directory: string, plan: Plan, source: string): Promise<void>;
+export declare function replacePlanLedgerWithRoot(directory: string, plan: Plan, source: string, options?: {
+    preCommitCheck?: () => void;
+}): Promise<void>;
 /**
  * Options for replayFromLedger
  */
 interface ReplayOptions {
     /** If true, use the latest snapshot to speed up replay */
     useSnapshot?: boolean;
+    /** Optional authority fence for recovery-side durable publications. */
+    preCommitCheck?: () => void;
 }
 /**
  * Result of a status-aware ledger replay.
@@ -449,7 +460,8 @@ export declare function peekPlanFromLedger(directory: string, _options?: ReplayO
  *    `replayWithIntegrity`'s bug — it hid genuine replay failures).
  *
  * @param directory - The working directory
- * @param _options - Optional replay options (reserved)
+ * @param _options - Optional replay options, including an authority fence for
+ *   recovery-side quarantine publications
  * @returns {@link ReplayStatusResult} with plan, truncated flag, and bad suffix
  */
 export declare function replayFromLedgerWithStatus(directory: string, _options?: ReplayOptions): Promise<ReplayStatusResult>;
@@ -526,10 +538,14 @@ export interface QuarantineResult {
  *
  * @param directory - The working directory
  * @param badSuffix - The corrupted content to quarantine
+ * @param options - Optional authority fence checked immediately before writing
+ *   the quarantine side file
  * @returns {@link QuarantineResult} with the written path (or null) and the
  *   number of parseable lines salvaged from the suffix
  */
-export declare function quarantineLedgerSuffix(directory: string, badSuffix: string): Promise<QuarantineResult>;
+export declare function quarantineLedgerSuffix(directory: string, badSuffix: string, options?: {
+    preCommitCheck?: () => void;
+}): Promise<QuarantineResult>;
 /**
  * Metadata describing an approved snapshot recovered from the ledger.
  */

package/dist/plan/manager.d.ts

@@ -6,6 +6,15 @@
 export declare class PlanConcurrentModificationError extends Error {
     constructor(message: string);
 }
+/**
+ * Internal control-flow error used to stop every recovery rung when the
+ * coordinator's captured hydration generation is no longer authoritative.
+ * Broad availability catches must rethrow this instead of trying a fallback
+ * that could publish stale durable state.
+ */
+export declare class PlanRecoverySupersededError extends Error {
+    constructor(message?: string);
+}
 /**
  * Thrown when savePlan detects that the incoming plan would silently drop one
  * or more tasks from the prior plan without the caller acknowledging the
@@ -61,6 +70,7 @@ export declare const _internals: {
     readPlanJsonUtf8: typeof readPlanJsonUtf8;
     readPlanFileUtf8: typeof readPlanFileUtf8;
     verifyWrittenPlanJson: typeof verifyWrittenPlanJson;
+    writeRebuildPlanMarkdown: typeof writeRebuildPlanMarkdown;
     ledgerExists: typeof ledgerExists;
     replayFromLedger: typeof replayFromLedger;
     loadLastApprovedPlan: typeof loadLastApprovedPlan;
@@ -91,6 +101,7 @@ export declare function retryCasWithBackoff(directory: string, eventInput: Ledge
     planHashAfter?: string;
     verifyValid?: () => Promise<boolean> | boolean;
     maxRetries?: number;
+    preCommitCheck?: () => void;
 }): Promise<LedgerEvent | null>;
 /**
  * Load plan.json ONLY without auto-migration from plan.md.
@@ -114,7 +125,9 @@ export declare function isPlanMdInSync(directory: string, plan: Plan, cache?: Ma
 /**
  * Regenerate plan.md from valid plan.json (auto-heal case 1).
  */
-export declare function regeneratePlanMarkdown(directory: string, plan: Plan): Promise<void>;
+export declare function regeneratePlanMarkdown(directory: string, plan: Plan, options?: {
+    preCommitCheck?: () => void;
+}): Promise<void>;
 /**
  * Load and validate plan from .swarm/plan.json with auto-heal sync.
  *
@@ -128,7 +141,9 @@ export declare function regeneratePlanMarkdown(directory: string, plan: Plan): P
  * 3. .swarm/plan.md exists only -> migrate from plan.md, save both files, return Plan
  * 4. Neither exists -> return null
  */
-export declare function loadPlan(directory: string, cache?: Map<string, Promise<string | null>>): Promise<RuntimePlan | null>;
+export declare function loadPlan(directory: string, cache?: Map<string, Promise<string | null>>, options?: {
+    preCommitCheck?: () => void;
+}): Promise<RuntimePlan | null>;
 /**
  * Recovery-path helper for callers that legitimately need to replace the
  * plan task set without explicit per-id acknowledgement (e.g. rebuilding
@@ -146,6 +161,7 @@ export declare function loadPlan(directory: string, cache?: Map<string, Promise<
 export declare function savePlanWithAutoAcknowledgedRemovals(directory: string, plan: Plan, source: string, reason: string, options?: {
     preserveCompletedStatuses?: boolean;
     planLockAlreadyHeld?: boolean;
+    preCommitCheck?: () => void;
 }): Promise<{
     removedCount: number;
 }>;
@@ -216,6 +232,7 @@ export declare function savePlan(directory: string, plan: Plan, options?: {
      */
     preCommitCheck?: () => void;
 }): Promise<PlanSaveDurability>;
+declare function writeRebuildPlanMarkdown(tempPath: string, content: string): Promise<void>;
 /**
  * Rebuild plan from ledger events.
  * Replays the ledger to reconstruct plan state, then writes the result.
@@ -226,6 +243,7 @@ export declare function savePlan(directory: string, plan: Plan, options?: {
  */
 export declare function rebuildPlan(directory: string, plan?: Plan, options?: {
     reason?: string;
+    preCommitCheck?: () => void;
 }): Promise<Plan | null>;
 /**
  * Write terminal plan state through the managed write path (FR-002, FR-005, FR-006).

package/dist/services/config-doctor.d.ts

@@ -5,6 +5,30 @@
  * classifies findings by severity, and proposes safe auto-fixes.
  */
 import type { PluginConfig } from '../config/schema';
+/**
+ * Current config format version (issue #2504). Version 3 introduces the
+ * governed v8 defaults-flip rows below; a config stamped at this version has
+ * acknowledged those default changes.
+ */
+export declare const CURRENT_CONFIG_FORMAT_VERSION = 3;
+/**
+ * Governed v8 default flips (issue #2504). Unlike DEPRECATED_FIELDS (key
+ * renames surfaced through `availableMigrations`), these are default-value
+ * changes surfaced as info-severity `defaults-flip` findings — they never
+ * rewrite user keys (explicit user values always win), they inform the owner
+ * of the change, the one-line kill switch, and the conservative preset that
+ * restores the pre-flip (v7) default. Evidence for every entry is cited in
+ * docs/defaults-governance.md.
+ */
+export declare const DEFAULT_FLIPS: ReadonlyArray<{
+    field: string;
+    v7Default: string;
+    v8Default: string;
+    killSwitch: string;
+    preset: 'conservative';
+    sinceVersion: number;
+    evidence: string;
+}>;
 /**
  * Lean Turbo evidence-requiring gates and the registered producer tool that
  * writes each gate's evidence (issue #2470: every evidence-requiring gate must

package/dist/services/injection-budget.d.ts

@@ -70,7 +70,7 @@ export declare function allocateInjectionBudget(systemEnhancerDemandTokens: numb
  * therefore already inside the final measurement (attribution only — adding
  * them again would double-count).
  */
-export type InjectionProducer = 'system-enhancer' | 'knowledge-injector' | 'context-capsule' | 'memory-recall' | 'advisory-queue' | 'swarm-command-banner' | 'linked-cohort-advisory' | 'spec-drift-advisory' | 'final-accounting-warning';
+export type InjectionProducer = 'system-enhancer' | 'knowledge-injector' | 'context-capsule' | 'memory-recall' | 'advisory-queue' | 'swarm-command-banner' | 'guidance-carrier-fence' | 'linked-cohort-advisory' | 'spec-drift-advisory' | 'final-accounting-warning';
 export type InjectionSurface = 'system' | 'messages';
 export interface ProducerAccounting {
     /** Tokens the producer asked the ledger for this turn (claims only). */
@@ -79,10 +79,15 @@ export interface ProducerAccounting {
     granted: number;
     /** Tokens actually emitted to the model-visible surface. */
     emitted: number;
-    /** Tokens the producer wanted but did not emit (its own pruning). */
+    /** Tokens the producer wanted but did not reach the model-visible surface, whether pruned locally or rejected during downstream carrier delivery. */
     truncated: number;
     surface: InjectionSurface;
 }
+declare const injectionBudgetReceiptBrand: unique symbol;
+/** Opaque, one-shot handle for a turn-ledger reservation. */
+export interface InjectionBudgetReceipt {
+    readonly [injectionBudgetReceiptBrand]: true;
+}
 export interface TurnLedgerSummary {
     generation: number;
     totalBudget: number;
@@ -112,13 +117,25 @@ export declare function beginTurnLedger(sessionID: string, totalBudget: number,
  * preserving #1617's fail-open contract; the caller is expected to report that
  * the hard ceiling was unavailable.
  */
-export declare function claimTurnBudget(sessionID: string, producer: InjectionProducer, requestedTokens: number, opts?: {
-    localMaxTokens?: number;
-    surface?: InjectionSurface;
-}): {
+interface TurnBudgetClaimResult {
     granted: number;
     ledgerPresent: boolean;
     ceilingActive: boolean;
+}
+export declare function claimTurnBudget(sessionID: string, producer: InjectionProducer, requestedTokens: number, opts?: {
+    localMaxTokens?: number;
+    surface?: InjectionSurface;
+}): TurnBudgetClaimResult;
+/**
+ * Claim from the ledger and return an opaque receipt that can settle exactly
+ * this claim. A missing ledger keeps the normal fail-open grant and produces
+ * no receipt because there is no reservation to commit or refund.
+ */
+export declare function claimTurnBudgetWithReceipt(sessionID: string, producer: InjectionProducer, requestedTokens: number, opts?: {
+    localMaxTokens?: number;
+    surface?: InjectionSurface;
+}): TurnBudgetClaimResult & {
+    receipt?: InjectionBudgetReceipt;
 };
 /**
  * Record a producer's grant without claiming through `claimTurnBudget`.
@@ -132,13 +149,33 @@ export declare function claimTurnBudget(sessionID: string, producer: InjectionPr
  * exceed `totalBudget`.
  */
 export declare function recordProducerGrant(sessionID: string, producer: InjectionProducer, requestedTokens: number, grantedTokens: number, surface: InjectionSurface): void;
+/**
+ * Record an allocator-derived producer grant and return a receipt tied to the
+ * exact ledger generation and charged amount. `expectedGeneration` prevents a
+ * delayed transform from booking into a newer request's replacement ledger.
+ */
+export declare function recordProducerGrantWithReceipt(sessionID: string, producer: InjectionProducer, requestedTokens: number, grantedTokens: number, surface: InjectionSurface, options?: {
+    expectedGeneration?: number;
+    retractEmissionOnRefund?: boolean;
+    emittedTokensOnRefund?: number;
+}): InjectionBudgetReceipt | undefined;
 /**
  * Record what a producer actually emitted (and pruned itself) this turn.
  * Producers that never claim (fixed/base content: advisory queue, banners,
  * the context-budget warning, the final-accounting warning) still record their
  * emission here so the final accounting can include them.
  */
-export declare function recordProducerEmission(sessionID: string, producer: InjectionProducer, emittedTokens: number, truncatedTokens: number, surface: InjectionSurface): void;
+export declare function recordProducerEmission(sessionID: string, producer: InjectionProducer, emittedTokens: number, truncatedTokens: number, surface: InjectionSurface, options?: {
+    expectedGeneration?: number;
+}): void;
+/**
+ * Record a direct producer emission and return a receipt that retracts exactly
+ * that emission if its carrier is not delivered. A generation mismatch is a
+ * no-op, so an old staged transform cannot write into a replacement ledger.
+ */
+export declare function recordProducerEmissionWithReceipt(sessionID: string, producer: InjectionProducer, emittedTokens: number, surface: InjectionSurface, options?: {
+    expectedGeneration?: number;
+}): InjectionBudgetReceipt | undefined;
 /**
  * Snapshot of the session's current turn ledger (null when absent).
  */
@@ -148,7 +185,9 @@ export declare function recordProducerEmission(sessionID: string, producer: Inje
  * recorded them, and the final accounting must not count bytes the model
  * never sees. Floors at zero; no-op without a ledger or producer entry.
  */
-export declare function deductProducerEmission(sessionID: string, producer: InjectionProducer, removedTokens: number): void;
+export declare function deductProducerEmission(sessionID: string, producer: InjectionProducer, removedTokens: number, options?: {
+    expectedGeneration?: number;
+}): void;
 export declare function getTurnLedgerSummary(sessionID: string): TurnLedgerSummary | null;
 /**
  * Emitted tokens recorded for one producer this turn (0 when no ledger or the
@@ -156,6 +195,14 @@ export declare function getTurnLedgerSummary(sessionID: string): TurnLedgerSumma
  * knowledge-injector reads the system-enhancer's actual emission from here.
  */
 export declare function getProducerEmission(sessionID: string, producer: InjectionProducer): number;
+/** Commit exactly one live receipt. Repeated or stale commits are no-ops. */
+export declare function commitInjectionBudgetReceipt(receipt: InjectionBudgetReceipt): boolean;
+/**
+ * Refund exactly one live receipt. Repeated, post-commit, or stale-generation
+ * refunds are no-ops. Grant receipts configured for emission retraction also
+ * move only their still-emitted amount into that producer's truncation count.
+ */
+export declare function refundInjectionBudgetReceipt(receipt: InjectionBudgetReceipt): boolean;
 /**
  * Advance the turn generation for a session: the current ledger is discarded so
  * the next request composition starts from a fresh generation. Called when
@@ -173,3 +220,4 @@ export declare function clearTurnLedger(sessionID: string): void;
  * review on PR #2415: the reset pattern must cover ALL module-scoped maps).
  */
 export declare function clearAllTurnLedgers(): void;
+export {};

package/dist/session/hydration-ownership.d.ts

@@ -1,13 +1,15 @@
 /**
- * Project-owned, generation-fenced hydration state (issue #2667).
+ * Project-owned, authority-fenced hydration state (issues #2667/#2668).
  *
  * The live maps on `swarmState` are process-resident and keyed by sessionID;
  * hydration is a per-PROJECT operation. This module owns the per-project
  * registries that scope a hydration's blast radius to the project that
  * initiated it and fence stale generations from publishing over newer state:
  *
- * - `projectHydrationGenerations` — monotonic counter per canonical project
- *   key, bumped ONLY when a hydration is initiated (`beginHydrationScope`).
+ * - `projectHydrationAuthorities` — bounded records containing a per-project
+ *   generation and a process-monotonic authority epoch. The generation is
+ *   bumped ONLY when a hydration is initiated (`beginHydrationScope`), while
+ *   the epoch changes whenever an evicted/reset project is reintroduced.
  *   Session creation NEVER bumps it; new sessions stamp `current + 1` so a
  *   session created while generation `g` is latest survives any later apply
  *   at `g`.
@@ -16,10 +18,12 @@
  * - `hydratedAggregateKeys` — the toolAggregates keys each project's last
  *   hydration published, so a re-hydration replaces only its own keys.
  *
- * Fence rule: a hydration whose scope generation `g` satisfies
- * `projectHydrationGenerations[K] > g` is REJECTED before any mutation —
- * some newer hydration began for that project. Stamp rule: an accepted
- * hydration at `g` evicts only sessions owned by `K` with
+ * Fence rule: a hydration is current only while both its generation and its
+ * authority epoch match the bounded record for its project. This prevents an
+ * evicted project entry from being reintroduced with a numerically reused
+ * generation and accidentally reviving an old scope (ABA). Session stamp
+ * rule: an accepted hydration at `{ generation: g, authorityEpoch: e }`
+ * evicts owned sessions from an older epoch, or sessions in epoch `e` with
  * `hydrationStamp <= g`.
  *
  * All maps are bounded (FIFO) with an explicit reset path
@@ -32,10 +36,17 @@ export declare const MAX_TRACKED_PROJECTS = 32;
 export declare const MAX_DIRECTORY_KEY_MEMO = 64;
 /** Opaque cache payload owned by state.ts; opaque here by design. */
 export type ProjectRehydrationCache = unknown;
+/** Opaque process-local authority token for a project's current record. */
+export interface HydrationAuthorityToken {
+    projectKey: string;
+    generation: number;
+    authorityEpoch: number;
+}
 /** Fence token captured when a hydration is initiated; see beginHydrationScope. */
 export interface HydrationScope {
     projectKey: string;
     generation: number;
+    authorityEpoch: number;
 }
 /**
  * Resolve the canonical project key for a directory spelling through a
@@ -58,8 +69,8 @@ export interface HydrationScope {
  */
 export declare function hydrationProjectKey(directory: string): string;
 /**
- * Begin a hydration scope: bump the project's generation counter and return
- * the fence token. The token must be captured when the hydration is
+ * Begin a hydration scope: bump the project's generation, mint a non-reusable
+ * authority, and return the fence token. The token must be captured when the hydration is
  * INITIATED (e.g. at `loadSnapshot` entry) and carried into
  * `rehydrateState`, which refuses to apply it once any newer generation has
  * begun.
@@ -67,6 +78,22 @@ export declare function hydrationProjectKey(directory: string): string;
 export declare function beginHydrationScope(directory: string): HydrationScope;
 /** Latest initiated hydration generation for a project (0 when never). */
 export declare function currentHydrationGeneration(projectKey: string): number;
+/**
+ * Capture the current project authority without beginning a hydration. This
+ * is used by direct session rehydration, which needs an exact record to fence
+ * across awaits but must preserve the session-creation/no-generation-bump
+ * contract.
+ */
+export declare function captureCurrentHydrationAuthority(projectKey: string): HydrationAuthorityToken;
+/** Return whether an exact authority token still names the current record. */
+export declare function isHydrationAuthorityCurrent(authority: HydrationAuthorityToken): boolean;
+/**
+ * Return whether a captured hydration scope is still the latest initiated
+ * scope for its project. Exact generation+epoch equality is intentional: a
+ * scope whose project registry entry was evicted or reset is no longer current
+ * either, even if a numerically equal generation is visible at the check.
+ */
+export declare function isHydrationScopeCurrent(scope: HydrationScope): boolean;
 /**
  * Stamp value for a session created NOW under `projectKey`:
  * `current + 1`, i.e. newer than any already-initiated hydration, so an
@@ -74,10 +101,10 @@ export declare function currentHydrationGeneration(projectKey: string): number;
  */
 export declare function nextSessionHydrationStamp(projectKey: string): number;
 export declare function getRehydrationCache(projectKey: string): ProjectRehydrationCache | undefined;
-export declare function setRehydrationCache(projectKey: string, cache: ProjectRehydrationCache): void;
+export declare function setRehydrationCache(projectKey: string, cache: ProjectRehydrationCache, authority?: HydrationAuthorityToken): boolean;
 /** Record the aggregate keys a project's hydration published (replace set). */
-export declare function recordHydratedAggregateKeys(projectKey: string, keys: Set<string>): void;
+export declare function recordHydratedAggregateKeys(projectKey: string, keys: Set<string>, authority?: HydrationAuthorityToken): boolean;
 /** The aggregate keys the project's last hydration published (empty if none). */
-export declare function hydratedAggregateKeysFor(projectKey: string): Set<string>;
+export declare function hydratedAggregateKeysFor(projectKey: string, authority?: HydrationAuthorityToken): Set<string>;
 /** Reset every registry (invariant 8: bounded state with an explicit reset). */
 export declare function clearHydrationOwnershipState(): void;

package/dist/session/snapshot-coordination-init.d.ts

@@ -1,7 +1,11 @@
 /** Post-resolution SQLite snapshot import/readiness lifecycle (#2481). */
+import { loadPlan } from '../plan/manager.js';
 import { type HydrationScope } from './hydration-ownership.js';
-import type { SnapshotData } from './snapshot-writer.js';
-type ReadinessState = 'running' | 'succeeded' | 'failed' | 'timed_out' | 'closing';
+import { readSnapshotFileStrict } from './snapshot-reader.js';
+import { importSnapshotRowsOnce } from './snapshot-store.js';
+import { writeSnapshotProjection } from './snapshot-writer.js';
+type ReadinessState = 'running' | 'succeeded' | 'superseded' | 'failed' | 'timed_out' | 'closing';
+export type SnapshotCoordinationInitializationOutcome = 'succeeded' | 'superseded';
 interface ReadinessEntry {
     attemptId: number;
     generation: number;
@@ -42,9 +46,12 @@ export declare function closeSnapshotCoordinationInitialization(directory: strin
 export declare function markSnapshotCoordinationClosing(directory: string): void;
 export declare const _snapshotCoordinationInternals: {
     entries: Map<string, ReadinessEntry>;
-    initialize: (directory: string, scope?: HydrationScope) => Promise<void>;
+    initialize: (directory: string, scope?: HydrationScope) => Promise<SnapshotCoordinationInitializationOutcome>;
+    loadPlan: typeof loadPlan;
+    readSnapshotFileStrict: typeof readSnapshotFileStrict;
+    importSnapshotRowsOnce: typeof importSnapshotRowsOnce;
     renameLegacySnapshot: (from: string, to: string) => void;
-    writeProjection: (directory: string, snapshot: SnapshotData) => Promise<void>;
+    writeProjection: typeof writeSnapshotProjection;
     timeoutMs: number;
 };
 export {};

package/dist/session/snapshot-reader.d.ts

@@ -4,7 +4,11 @@
  */
 import type { AgentSessionState } from '../state';
 import { type HydrationScope } from './hydration-ownership.js';
+import { recordInterruptedExecution } from './restart-reconciliation.js';
 import type { SerializedAgentSession, SnapshotData } from './snapshot-writer';
+export declare const _internals: {
+    recordInterruptedExecution: typeof recordInterruptedExecution;
+};
 /**
  * Transient session fields that must be reset on rehydration.
  * Centralised here to keep the reset logic DRY and auditable.
@@ -35,9 +39,10 @@ export declare function readSnapshotFileStrict(directory: string, relativePath:
 /**
  * Rehydrate swarmState from a SnapshotData object.
  *
- * Issue #2667 — project-owned and generation-fenced:
+ * Issues #2667/#2668 — project-owned and authority-fenced:
  * - With a `directory`, this replaces ONLY the state owned by that project
- *   (sessions whose `owningProjectKey` matches and whose `hydrationStamp` is
+ *   (sessions whose `owningProjectKey` matches and whose authority epoch is
+ *   older than the applying epoch, or whose current-epoch `hydrationStamp` is
  *   at or below the applying generation). Other projects' live state — and
  *   this project's sessions created after the hydration began — survive.
  * - With an explicit `scope` captured at initiation, the apply is refused
@@ -66,8 +71,8 @@ export declare function rehydrateState(snapshot: SnapshotData, directory?: strin
  * Called on plugin init to restore state from previous session.
  * NEVER throws - swallows any errors silently.
  *
- * Issue #2667: a hydration scope is captured at entry so the eventual
- * rehydrateState apply is generation-fenced — a loadSnapshot whose 5 s init
+ * Issues #2667/#2668: a hydration scope is captured at entry so the eventual
+ * rehydrateState apply is authority-fenced — a loadSnapshot whose 5 s init
  * timeout (src/index.ts) abandoned the await is refused once any newer
  * hydration for the same project has begun.
  */

package/dist/session/snapshot-writer.d.ts

@@ -3,7 +3,6 @@
  * Persists swarmState as independently keyed SQLite coordination rows and a
  * non-authoritative, versioned file projection.
  */
-import { rename as fsRename } from 'node:fs/promises';
 import { TASK_WORKFLOW_SCHEMA_MARKER } from '../gate-evidence.js';
 import type { AgentSessionState, DelegationEntry, ToolAggregate } from '../state';
 import { swarmState } from '../state';
@@ -190,7 +189,7 @@ export declare function serializeAgentSession(s: AgentSessionState): SerializedA
  * Silently swallows errors (non-fatal — never crash the plugin).
  */
 export declare function writeSnapshot(directory: string, state: typeof swarmState): Promise<void>;
-export declare function writeSnapshotProjection(directory: string, snapshot: SnapshotData): Promise<void>;
+export declare function writeSnapshotProjection(directory: string, snapshot: SnapshotData, shouldCommit?: () => boolean): Promise<void>;
 /**
  * Create a snapshot writer hook suitable for use in tool.execute.after.
  * Writes state immediately on every call.  Concurrent calls are serialised so
@@ -211,5 +210,5 @@ export declare const _internals: {
     writeSnapshot: typeof writeSnapshot;
     createSnapshotWriterHook: typeof createSnapshotWriterHook;
     flushPendingSnapshot: typeof flushPendingSnapshot;
-    rename: typeof fsRename;
+    rename: (from: string, to: string, shouldCommit?: () => boolean) => void | Promise<void>;
 };

package/dist/state.d.ts

@@ -7,6 +7,7 @@
  * and delegation chains.
  */
 import type { OpencodeClient } from '@opencode-ai/sdk';
+import { type Plan } from './config/plan-schema';
 import type { CouncilAgent } from './council/types';
 import { type QaGates } from './db/qa-gate-profile.js';
 import { type EnvironmentProfile } from './environment/profile.js';
@@ -14,8 +15,26 @@ import { type TaskWorkflowMetadata } from './gate-evidence';
 import type { EscalationTracker } from './prm/escalation.js';
 import type { PatternMatch, PrmEpisodeState } from './prm/types.js';
 import type { ReviewRouteEvidence } from './review/routing-enforcement.js';
+import { getRehydrationCache } from './session/hydration-ownership.js';
 import { AgentRunContext } from './state/agent-run-context.js';
+export { getRehydrationCache };
 export { AgentRunContext } from './state/agent-run-context.js';
+/** Optional controls for rebuilding the project-owned rehydration cache. */
+export interface RehydrationCacheBuildOptions {
+    /**
+     * Explicitly recovered plan state.  Presence of this property, including a
+     * null value, means the caller already resolved the authoritative plan and
+     * the builder must not fall back to the derived plan.json projection.
+     */
+    planOverride?: Plan | null;
+    /** Return false when the captured hydration scope was superseded mid-read. */
+    shouldCommit?: () => boolean;
+}
+/** Result of a cache rebuild, including whether its publication committed. */
+export interface RehydrationCacheBuildResult {
+    committed: boolean;
+    reason?: 'superseded';
+}
 /**
  * Represents a single tool call entry for tracking purposes
  */
@@ -470,11 +489,21 @@ export interface AgentSessionState {
      * Hydration generation this session was created/restored AT.
      * `startAgentSession` stamps `currentGeneration + 1` (newer than any
      * in-flight hydration); `rehydrateState` stamps its applying generation.
-     * A hydration at generation `g` evicts only owned sessions with
-     * `hydrationStamp <= g`, so live sessions created after `g` began always
-     * survive. Also never snapshotted.
+     * A hydration at authority `{ generation: g, epoch: e }` evicts owned
+     * sessions from another epoch and same-epoch sessions with
+     * `hydrationStamp <= g`, so sessions created after `g` began survive only
+     * within the same authority incarnation.
+     * `hydrationAuthorityEpoch` disambiguates a numerically reused generation
+     * after bounded project-authority eviction or reset. Also never snapshotted.
      */
     hydrationStamp?: number;
+    /**
+     * Process-local authority epoch paired with `hydrationStamp`. A session from
+     * an older project-authority incarnation is stale even when its numeric
+     * generation is larger than the current generation (issue #2668 ABA guard).
+     * Deliberately omitted from snapshots with the other ownership fields.
+     */
+    hydrationAuthorityEpoch?: number;
     /** Pattern type to detection count mapping */
     prmPatternCounts: Map<string, number>;
     /** Current escalation level (0=none, 1=guidance, 2=strong guidance, 3=hard stop) */
@@ -1378,7 +1407,7 @@ export declare function _resetCouncilDisagreementWarnings(): void;
  * refreshed after compaction by the compaction hook (src/hooks/compaction-customizer.ts).
  * Non-fatal: missing/malformed files leave an empty cache.
  */
-export declare function buildRehydrationCache(directory: string): Promise<void>;
+export declare function buildRehydrationCache(directory: string, options?: RehydrationCacheBuildOptions): Promise<RehydrationCacheBuildResult>;
 /**
  * Synchronously applies the cached plan+evidence data to a session.
  * Merge rules:
@@ -1398,7 +1427,7 @@ export declare function applyRehydrationCache(session: AgentSessionState, projec
  * Builds (or refreshes) the rehydration cache from disk, then applies it
  * to the target session.
  */
-export declare function rehydrateSessionFromDisk(directory: string, session: AgentSessionState): Promise<void>;
+export declare function rehydrateSessionFromDisk(directory: string, session: AgentSessionState, shouldCommit?: () => boolean): Promise<void>;
 /**
  * Check if Turbo Mode is enabled for a specific session or ANY session.
  * @param sessionID - Optional session ID to check. If provided, checks only that session.
@@ -1615,6 +1644,7 @@ export declare const _internals: {
     buildRehydrationCache: typeof buildRehydrationCache;
     applyRehydrationCache: typeof applyRehydrationCache;
     rehydrateSessionFromDisk: typeof rehydrateSessionFromDisk;
+    rehydratePrSubscriptions: typeof rehydratePrSubscriptions;
     isCouncilGateActive: typeof isCouncilGateActive;
     defaultRunContext: typeof defaultRunContext;
 };

package/dist/tools/phase-complete.d.ts

@@ -150,6 +150,7 @@ export declare const MAX_OUTPUT_BYTES = 512000;
 declare function allCompletedTasksHavePassedGateEvidence(directory: string, tasks: Array<{
     id: string;
     status: string;
+    files_touched?: string[];
 }>): Promise<boolean>;
 /**
  * Execute the phase_complete tool

package/dist/tools/save-plan.d.ts

@@ -3,8 +3,20 @@
  * Allows the Architect agent to save structured plans to .swarm/plan.json and .swarm/plan.md.
  */
 import type { ToolDefinition } from '@opencode-ai/plugin/tool';
+import { loadPluginConfigWithMeta } from '../config';
 import { type ExecutionProfile } from '../config/plan-schema';
 import { takeSnapshotWithRetry } from '../plan/ledger';
+/**
+ * DI seam for hermetic config-load substitution in tests (AGENTS.md invariant 7).
+ * Mirrors `src/tools/apply-patch.ts`. Tests override
+ * `_internals.loadPluginConfigWithMeta` and restore it in `afterEach` instead of
+ * writing real config files or using `mock.module` (which leaks across test
+ * files in Bun's shared runner). Used by the #2504 conservative-preset
+ * new-plan default below.
+ */
+export declare const _internals: {
+    loadPluginConfigWithMeta: typeof loadPluginConfigWithMeta;
+};
 /** Test seam for the snapshot retry helper (FR-004). */
 export declare const _test_exports: {
     takeSnapshotWithRetry: typeof takeSnapshotWithRetry;

package/dist/tools/update-task-status.d.ts

@@ -84,7 +84,7 @@ export interface ReviewerGateResult {
     nextAction?: string;
 }
 declare function hasPassedDurableGateEvidence(workingDirectory: string, taskId: string): boolean;
-export declare function checkReviewerGate(taskId: string, workingDirectory?: string, stageBParallelEnabled?: boolean, sessionID?: string, fallbackDir?: string): ReviewerGateResult;
+export declare function checkReviewerGate(taskId: string, workingDirectory?: string, stageBParallelEnabled?: boolean, sessionID?: string, fallbackDir?: string, currentDeclaredFiles?: readonly string[] | null): ReviewerGateResult;
 /**
  * Wrapper around checkReviewerGate that appends a diff-scope advisory warning.
  * Keeps checkReviewerGate synchronous for backward compatibility.