opencode-swarm 7.153.0 → 7.153.2

package/dist/observability/catalog.d.ts

@@ -1,7 +1,7 @@
 /**
  * The event catalog (issue #2029).
  *
- * Exactly 49 entries, matching the `TelemetryEvent` union at
+ * Exactly 50 entries, matching the `TelemetryEvent` union at
  * `src/telemetry.ts:15-131`. Thirty-eight predate the #2029 contract; the 39th is
  * `agent_conflict_detected` (previously emitted through a force-cast past the
  * type system), the 40th is `close_archive_result` (issue #2030 — the
@@ -16,9 +16,11 @@
  * `skill_usage_health` storage audit for the issue-#2038
  * `.swarm/skill-usage.jsonl` store and its authoritative pending sidecar,
  * the 48th is the bounded `core_events_health` storage audit for the
- * issue-#2039 `.swarm/events.jsonl` store, and the 49th is the bounded
+ * issue-#2039 `.swarm/events.jsonl` store, the 49th is the bounded
  * `shell_audit_health` storage audit for the issue-#2040
- * `.swarm/session/shell-audit.jsonl` security-audit store. These late additions are instances
+ * `.swarm/session/shell-audit.jsonl` security-audit store, and the 50th is
+ * the bounded `trajectory_health` storage audit for the issue-#2041
+ * `.swarm/trajectories/` PRM session store. These late additions are instances
  * of the defect class this contract exists to close: an event kind entering
  * the stream with no registration.
  *
@@ -73,7 +75,7 @@ export interface CatalogEntry {
     /**
      * Whether an event of this kind must carry `trace.parentSpanId`.
      *
-     * `false` for all 49 entries today, and that is a truthful statement about
+     * `false` for all 50 entries today, and that is a truthful statement about
      * the current system rather than a placeholder: no producer supplies a
      * parent span, so `createObservation` never sets one. Setting this to `true`
      * for a kind whose producer cannot supply a parent would make every

package/dist/prm/index.d.ts

@@ -26,7 +26,7 @@ import { formatCourseCorrectionForInjection, generateCourseCorrection } from './
 import { EscalationTracker } from './escalation';
 import { detectPatterns } from './pattern-detector';
 import { recordReplayEntry, startReplayRecording } from './replay';
-import { cleanupOldTrajectoryFiles, clearTrajectoryCache, getInMemoryTrajectory, readTrajectory } from './trajectory-store';
+import { clearTrajectoryCache, getInMemoryTrajectory, readTrajectoryWithCoverage, scheduleTrajectoryCleanup } from './trajectory-store';
 import type { PrmConfig } from './types';
 /**
  * Test-only dependency-injection seam — see `gitignore-warning.ts:_internals`.
@@ -38,12 +38,12 @@ import type { PrmConfig } from './types';
  */
 export declare const _internals: {
     getAgentSession: typeof getAgentSession;
-    readTrajectory: typeof readTrajectory;
+    readTrajectoryWithCoverage: typeof readTrajectoryWithCoverage;
     getInMemoryTrajectory: typeof getInMemoryTrajectory;
     detectPatterns: typeof detectPatterns;
     generateCourseCorrection: typeof generateCourseCorrection;
     formatCourseCorrectionForInjection: typeof formatCourseCorrectionForInjection;
-    cleanupOldTrajectoryFiles: typeof cleanupOldTrajectoryFiles;
+    scheduleTrajectoryCleanup: typeof scheduleTrajectoryCleanup;
     clearTrajectoryCache: typeof clearTrajectoryCache;
     recordReplayEntry: typeof recordReplayEntry;
     startReplayRecording: typeof startReplayRecording;

package/dist/prm/replay.d.ts

@@ -60,8 +60,25 @@ declare function sanitizeFilename(input: string): string;
  */
 export declare function startReplayRecording(sessionID: string, directory: string): Promise<string | null>;
 /**
- * Appends a ReplayEntry to the replay artifact file.
- * Non-blocking: errors are caught and logged, never thrown.
+ * Hard budgets for replay artifacts (issue #2041 Required 1 — the PRM budget
+ * set covers replays as well as trajectories). Replays are write-only
+ * best-effort diagnostics: at the cap, further entries for that artifact are
+ * skipped with a one-time warning rather than rotated (rotation would create
+ * unbounded sibling files, which is exactly what this cap exists to prevent).
+ * The 7-day age sweep + per-directory count cap in trajectory-store's
+ * `cleanupOldTrajectoryFiles` bound the directory as a whole.
+ */
+export declare const REPLAY_LIMITS: {
+    /** Per-artifact byte ceiling. */
+    readonly maxBytes: number;
+    /** Stat cadence per artifact (bytes are tracked in memory between stats). */
+    readonly checkIntervalEntries: 16;
+    /** Bound on tracked artifacts (Invariant 8). */
+    readonly maxTrackedArtifacts: 256;
+};
+/**
+ * Appends a ReplayEntry to the replay artifact file, enforcing the per-artifact
+ * byte cap. Non-blocking: errors are caught and logged, never thrown.
  *
  * @param artifactPath - Path to the replay artifact file
  * @param sessionID - Session identifier
@@ -72,5 +89,15 @@ export declare const _test_exports: {
     readonly isPathSafe: typeof isPathSafe;
     readonly isWithinReplaysDir: typeof isWithinReplaysDir;
     readonly sanitizeFilename: typeof sanitizeFilename;
+    readonly REPLAY_LIMITS: {
+        /** Per-artifact byte ceiling. */
+        readonly maxBytes: number;
+        /** Stat cadence per artifact (bytes are tracked in memory between stats). */
+        readonly checkIntervalEntries: 16;
+        /** Bound on tracked artifacts (Invariant 8). */
+        readonly maxTrackedArtifacts: 256;
+    };
+    /** Test isolation: drop per-artifact byte-cap bookkeeping. */
+    readonly resetReplayByteTracking: () => void;
 };
 export {};

package/dist/prm/trajectory-store.d.ts

@@ -1,40 +1,215 @@
 /**
- * TRAJECTORY STORE (Session-Level)
+ * TRAJECTORY STORE (Session-Level) — bounded (issue #2041)
  *
  * Per-session trajectory storage for PRM pattern detection.
- * Writes to .swarm/trajectories/{sessionId}.jsonl
+ * Writes to .swarm/trajectories/{sessionId}.jsonl (+ a small
+ * {sessionId}.jsonl.meta.json checkpoint and a transient {sessionId}.jsonl.lock).
+ *
+ * Bounded session-trajectory contract (mirrors the #2040 shell-audit store):
+ * - ONE knob, `maxLines`, governs BOTH the in-memory cache trim and the disk
+ *   compaction: over budget, the newest floor(maxLines/2) entries are retained
+ *   (the cache has always used exactly this rule — the disk now matches it).
+ * - The disk byte ceiling sessionMaxBytesFor(maxLines) is SOVEREIGN and is
+ *   enforced at APPEND time (the stat needed for torn-tail re-framing doubles
+ *   as the size probe): over ceiling, compaction runs before the append.
+ * - A line-count check runs every `checkIntervalAppends` appends (the only
+ *   part that needs a read; it is tail-bounded, never a whole-file read).
+ * - Readers (`readTrajectory`, `getCurrentStep`) read a bounded tail window and
+ *   disclose coverage; `getCurrentStep` also consults the atomically persisted
+ *   checkpoint so a restart never scans history to continue step numbering.
+ * - Crash semantics: compaction publishes via tmp+rename (a partial rewrite is
+ *   never visible); the checkpoint is written after the data rewrite under the
+ *   same lock, and merges `max(previous, observed)` so it can only ratchet UP.
+ *   Compaction keeps the NEWEST entries, so the global max step always survives
+ *   on disk — except when every retained line is corrupt, in which case the
+ *   checkpoint alone preserves step continuity (that is why it exists).
+ * - Two writers: an in-process per-key promise chain (same-process appends
+ *   never burn the cross-process retry budget) plus a per-file `.lock`
+ *   (wx existence create — the PID inside is diagnostic only, never
+ *   liveness-checked — stale-break, bounded retry). Lock exhaustion skips the
+ *   append with a warning — telemetry loss is preferred over file corruption
+ *   in this best-effort store — and is counted into `trajectory_health`.
  *
  * Coexists with task-level trajectory-logger.ts which writes to
- * .swarm/evidence/{taskId}/trajectory.jsonl for audit/evidence.
+ * .swarm/evidence/{taskId}/trajectory.jsonl for audit/evidence (bounded by its
+ * own write-side truncation; untouched by this contract).
  */
+import { telemetry } from '../telemetry';
 import type { TrajectoryEntry } from './types';
+/**
+ * Hard budgets for the bounded session-trajectory contract (issue #2041).
+ * Exported for tests and for the retention registry's documented contract.
+ */
+export declare const TRAJECTORY_LIMITS: {
+    /** Line-count compaction check cadence (append-path, amortized). */
+    readonly checkIntervalAppends: 25;
+    /** Tail-bounded read window for readTrajectoryWithCoverage. */
+    readonly readMaxBytes: number;
+    /** Tail-bounded read window for getCurrentStep (newest lines carry max step). */
+    readonly stepReadMaxBytes: number;
+    /** Tail-bounded input window for compaction (legacy files may be huge). */
+    readonly compactMaxBytes: number;
+    /** A JSONL line longer than this is shed as oversize (append skips it). */
+    readonly maxLineBytes: number;
+    /** Estimated bytes per entry used to derive the per-session byte ceiling. */
+    readonly estimatedLineBytes: 512;
+    /** Floor for the derived per-session byte ceiling. */
+    readonly minSessionMaxBytes: number;
+    /** Per-file cross-process lock: bounded retries, then skip + warn. */
+    readonly lockRetries: 20;
+    readonly lockRetryDelayMs: 5;
+    /** A lock older than this is considered crashed and broken. */
+    readonly lockStaleMs: number;
+    /** Per-directory session-file count cap (age-sweep backstop). */
+    readonly maxFilesPerDir: 200;
+    /** Unlinks per cleanup invocation (converges across runs). */
+    readonly maxDeletionsPerRun: 256;
+    /** Default age sweep horizon for trajectories/ and replays/. */
+    readonly defaultMaxAgeDays: 7;
+    /** Debounce for the lazily scheduled cleanup pass. */
+    readonly cleanupDebounceMs: number;
+    /** Cooldown for append_skip health events (lock-exhaust observability). */
+    readonly appendSkipEventCooldownMs: 60000;
+};
+/**
+ * Sovereign per-session disk byte ceiling, derived from the same `maxLines`
+ * knob that governs cache trimming and line-count compaction.
+ */
+export declare function sessionMaxBytesFor(maxLines: number): number;
+/** Test/DI seam — see `gitignore-warning.ts:_internals` for the convention. */
+export declare const _internals: {
+    telemetry: typeof telemetry;
+};
 /**
  * Returns cached trajectory entries for a session (empty array if not cached).
+ *
+ * @param sessionId - Session identifier
+ * @param directory - Workspace root that owns the session's trajectory file
  */
-export declare function getInMemoryTrajectory(sessionId: string): TrajectoryEntry[];
+export declare function getInMemoryTrajectory(sessionId: string, directory: string): TrajectoryEntry[];
 /**
  * Clears trajectory cache (for test isolation or session cleanup).
+ *
+ * With a sessionId but no directory, every root's entry for that session is
+ * cleared (suffix scan over the bounded map) — reset paths that legitimately
+ * lack a directory still release the cached window.
  */
 export declare function clearTrajectoryCache(sessionId?: string): void;
+interface TrajectoryCheckpoint {
+    version: 1;
+    highestStep: number;
+    droppedEntries: number;
+    /**
+     * Cumulative bytes discarded whole — chiefly the pre-window portion of an
+     * oversized file that a tail-bounded compaction rewrote away (shed
+     * windowed entries also contribute their bytes here, alongside their
+     * counts in droppedEntries: the two metrics are independent dimensions
+     * of the same loss). Without this, a compaction whose window kept every
+     * windowed entry (droppedEntries delta 0) would silently erase megabytes
+     * beyond the window while coverage still reported `complete`. Optional
+     * on READ for checkpoints written before this field existed.
+     */
+    droppedBytes?: number;
+    compactedAt: string;
+}
+/**
+ * Reads a session's persisted step checkpoint (null when absent/corrupt).
+ *
+ * Production consumers: `getCurrentStep` (restart continuity) and the consensus
+ * corpus's default PRM coverage signal (dropped-by-compaction disclosure).
+ */
+export declare function readTrajectoryCheckpoint(sessionId: string, directory: string): Promise<TrajectoryCheckpoint | null>;
+/**
+ * One bounded stat of a session's trajectory file (null when absent).
+ *
+ * Production consumer: the consensus corpus's default PRM coverage verdict —
+ * a file larger than the read window means the live bounded read was
+ * window-truncated, exactly matching `readTrajectoryWithCoverage`'s coverage
+ * semantics so the two paths cannot diverge (implementation-review round 1).
+ */
+export declare function trajectoryFileBytes(sessionId: string, directory: string): Promise<number | null>;
 /**
- * Appends a single TrajectoryEntry to the session's trajectory file.
+ * Appends a single TrajectoryEntry to the session's trajectory file, enforcing
+ * the bounded session-trajectory contract on disk as well as in memory.
  *
  * @param sessionId - Session identifier
  * @param entry - Trajectory entry to append
  * @param directory - Base directory (workspace root)
- * @param maxLines - Maximum lines before in-memory cache trimming (default 1000)
+ * @param maxLines - Line budget for BOTH the in-memory cache trim and disk
+ *   compaction (compaction retains the newest floor(maxLines/2) entries; the
+ *   derived byte ceiling sessionMaxBytesFor(maxLines) is sovereign)
  */
 export declare function appendTrajectoryEntry(sessionId: string, entry: TrajectoryEntry, directory: string, maxLines?: number): Promise<void>;
+export type TrajectoryCoverage = 'complete' | 'truncated' | 'empty';
+export interface TrajectoryReadWithCoverage {
+    entries: TrajectoryEntry[];
+    coverage: TrajectoryCoverage;
+    /** Entries removed by prior compactions (persisted checkpoint total). */
+    droppedByCompaction: number;
+    skippedMalformed: number;
+}
 /**
- * Reads all TrajectoryEntry records from a session's trajectory file.
+ * Tail-bounded read of a session's trajectory with explicit coverage
+ * disclosure (issue #2041 Required 3/4). Reads at most
+ * TRAJECTORY_LIMITS.readMaxBytes regardless of file size; the returned entries
+ * are the newest window in file order.
+ *
+ * `maxLines` is the SAME knob the append path uses: a cold read populates the
+ * in-memory cache trimmed to the configured budget, so a legacy pre-fix file
+ * cannot inflate the cache PRM pattern detection reads (review round 1).
+ */
+export declare function readTrajectoryWithCoverage(sessionId: string, directory: string, maxLines?: number): Promise<TrajectoryReadWithCoverage>;
+/**
+ * Reads the newest bounded window of TrajectoryEntry records from a session's
+ * trajectory file.
  *
  * @param sessionId - Session identifier
  * @param directory - Base directory (workspace root)
+ * @param maxLines - Optional cache-trim budget (same knob as the append path)
  * @returns Array of trajectory entries (empty array if file doesn't exist)
  */
-export declare function readTrajectory(sessionId: string, directory: string): Promise<TrajectoryEntry[]>;
+export declare function readTrajectory(sessionId: string, directory: string, maxLines?: number): Promise<TrajectoryEntry[]>;
 export declare const _test_exports: {
     readonly MAX_TRACKED_TRAJECTORY_SESSIONS: 500;
+    readonly TRAJECTORY_LIMITS: {
+        /** Line-count compaction check cadence (append-path, amortized). */
+        readonly checkIntervalAppends: 25;
+        /** Tail-bounded read window for readTrajectoryWithCoverage. */
+        readonly readMaxBytes: number;
+        /** Tail-bounded read window for getCurrentStep (newest lines carry max step). */
+        readonly stepReadMaxBytes: number;
+        /** Tail-bounded input window for compaction (legacy files may be huge). */
+        readonly compactMaxBytes: number;
+        /** A JSONL line longer than this is shed as oversize (append skips it). */
+        readonly maxLineBytes: number;
+        /** Estimated bytes per entry used to derive the per-session byte ceiling. */
+        readonly estimatedLineBytes: 512;
+        /** Floor for the derived per-session byte ceiling. */
+        readonly minSessionMaxBytes: number;
+        /** Per-file cross-process lock: bounded retries, then skip + warn. */
+        readonly lockRetries: 20;
+        readonly lockRetryDelayMs: 5;
+        /** A lock older than this is considered crashed and broken. */
+        readonly lockStaleMs: number;
+        /** Per-directory session-file count cap (age-sweep backstop). */
+        readonly maxFilesPerDir: 200;
+        /** Unlinks per cleanup invocation (converges across runs). */
+        readonly maxDeletionsPerRun: 256;
+        /** Default age sweep horizon for trajectories/ and replays/. */
+        readonly defaultMaxAgeDays: 7;
+        /** Debounce for the lazily scheduled cleanup pass. */
+        readonly cleanupDebounceMs: number;
+        /** Cooldown for append_skip health events (lock-exhaust observability). */
+        readonly appendSkipEventCooldownMs: 60000;
+    };
+    readonly sessionMaxBytesFor: typeof sessionMaxBytesFor;
+    readonly getCacheSize: () => number;
+    readonly getChainSize: () => number;
+    /** Test isolation: the cleanup debounce is module-global state. */
+    readonly resetCleanupDebounce: () => void;
+    /** Test isolation: lock-skip counters are module-global state. */
+    readonly resetLockSkipCounters: () => void;
+    readonly appendFileIsTorn: (filePath: string) => Promise<boolean>;
 };
 /**
  * Alias for readTrajectory - retrieves trajectory entries for a session.
@@ -44,17 +219,16 @@ export declare const _test_exports: {
  * @returns Array of trajectory entries
  */
 export declare function getTrajectoryForSession(sessionId: string, directory: string): Promise<TrajectoryEntry[]>;
-/**
- * Truncates the trajectory file to the newest half if lines exceed maxLines.
- *
- * @param sessionId - Session identifier
- * @param directory - Base directory (workspace root)
- * @param maxLines - Maximum number of lines to retain
- */
-export declare function truncateTrajectoryIfNeeded(sessionId: string, directory: string, maxLines: number): Promise<void>;
 /**
  * Returns the highest step number in the session's trajectory.
- * Used to determine the next step number when appending.
+ * Used to determine the next step number when appending — the production
+ * restart-seeding path in trajectory-logger.ts calls this before the first
+ * mint of a session so step numbers stay monotonic across process restarts.
+ *
+ * Bounded: reads at most TRAJECTORY_LIMITS.stepReadMaxBytes of the file
+ * (the newest lines carry the max step) and merges the atomically persisted
+ * checkpoint, so a restart never scans unbounded history — and the high-water
+ * mark survives even a fully-corrupt data file.
  *
  * @param sessionId - Session identifier
  * @param directory - Base directory (workspace root)
@@ -62,8 +236,24 @@ export declare function truncateTrajectoryIfNeeded(sessionId: string, directory:
  */
 export declare function getCurrentStep(sessionId: string, directory: string): Promise<number>;
 /**
- * Deletes trajectory and replay files older than maxAgeDays.
- * Runs against .swarm/trajectories/ and .swarm/replays/ directories.
- * Non-blocking: errors logged, not thrown.
+ * Debounced, fire-and-forget cleanup scheduling used by the PRM hook's
+ * once-per-session trigger. The plugin's post-resolution init pass calls
+ * `cleanupOldTrajectoryFiles` directly (the debounce must not suppress the
+ * startup sweep).
+ */
+export declare function scheduleTrajectoryCleanup(directory: string): void;
+/**
+ * Deletes aged trajectory and replay files, then enforces a per-directory
+ * session-file count cap (oldest-first) so a hostile or skewed mtime cannot
+ * grow `.swarm/trajectories/` or `.swarm/replays/` without bound. A session's
+ * `.meta.json` checkpoint is removed with its `.jsonl`; orphan checkpoints and
+ * stale atomic-write `*.tmp` leftovers age out on their own. Bounded to
+ * maxDeletionsPerRun unlinks per invocation (converges across runs); every
+ * failure is swallowed. Never touches `.swarm/evidence/` (task evidence is a
+ * different directory tree governed by its own contract).
+ *
+ * Replays and trajectories are independent artifacts sharing this sweep: no
+ * cross-linkage is enforced or implied.
  */
 export declare function cleanupOldTrajectoryFiles(directory: string, maxAgeDays?: number): Promise<void>;
+export {};

package/dist/state.d.ts

@@ -1411,10 +1411,12 @@ export declare function setCriticalShownIds(sessionID: string, value: {
  *  whether an entry was removed. */
 export declare function clearCriticalShownIds(sessionID: string): boolean;
 /** Build the directive-identity fingerprint used to key the gate denial
- *  counter — a sorted, joined snapshot of a critical-directive-id set. Two
- *  calls with the same id set (regardless of order) produce the same key,
- *  so re-injecting the identical directive on a later turn does not reset
- *  the counter, but swapping to a genuinely different directive set does. */
+ *  counter — a sorted, joined snapshot of a critical-directive ENTRY-id set.
+ *  Two calls with the same entry-id set (regardless of order, and regardless
+ *  of which trace ids re-displayed those entries — issue #2398) produce the
+ *  same key, so re-injecting the same directive on a later turn does not
+ *  reset the counter, but swapping to a genuinely different directive set
+ *  does. */
 export declare function buildGateDenialDirectiveKey(ids: string[]): string;
 /** Increment (or start) the per-session gate denial counter for the given
  *  directive identity, FIFO-evicting the oldest session entry if the cap is

package/dist/telemetry.d.ts

@@ -32,7 +32,7 @@ export type TelemetryEvent = 'session_started' | 'session_ended' | 'agent_activa
  * `prm_hard_stop` TRIGGER emitted by `src/prm/escalation.ts`. A trigger with
  * no matching delivery means the containment never reached the agent.
  */
- | 'prm_hard_stop_delivered' | 'agent_conflict_detected' | 'close_archive_result' | 'knowledge_receipt_transition' | 'knowledge_maintenance' | 'residue_health' | 'context_telemetry_health' | 'skill_usage_health' | 'core_events_health' | 'shell_audit_health';
+ | 'prm_hard_stop_delivered' | 'agent_conflict_detected' | 'close_archive_result' | 'knowledge_receipt_transition' | 'knowledge_maintenance' | 'residue_health' | 'context_telemetry_health' | 'skill_usage_health' | 'core_events_health' | 'shell_audit_health' | 'trajectory_health';
 /** Stable classification for how a reviewer-gate decision was established. */
 export type ReviewerGateEvidenceKind = 'genuine' | 'fallback' | 'data_quality' | 'block';
 /**
@@ -335,6 +335,26 @@ export declare const telemetry: {
         bytes: number;
         limit_bytes: number;
     }): void;
+    /**
+     * PRM session-trajectory store health (issue #2041): emitted on
+     * compaction, cleanup sweeps, and (cooldown-bounded) lock-skipped appends
+     * for the bounded `.swarm/trajectories/` store. Counts ONLY — no session
+     * identifiers, no filesystem paths, no trajectory content — matching the
+     * observability contract's no-content-in-metrics rule.
+     * `dropped_count` discloses entries folded by compaction (line budget or
+     * the sovereign byte ceiling) and files removed by cleanup; `skipped_lock_count`
+     * discloses appends skipped because the per-file cross-process lock stayed
+     * busy (best-effort store: telemetry loss is preferred over corruption).
+     */
+    trajectoryHealth(data: {
+        trigger: "compaction" | "cleanup" | "append_skip";
+        retained_count: number;
+        dropped_count: number;
+        corrupt_count: number;
+        skipped_lock_count: number;
+        bytes: number;
+        limit_bytes: number;
+    }): void;
     /**
      * Issue #2063 C2 — the PRM hard-stop DENIAL was actually delivered to the
      * agent (thrown by the guardrails `toolBefore` consumer). `prm_hard_stop`

package/dist/utils/atomic-write.d.ts

@@ -131,6 +131,8 @@ export declare const MAX_ATOMIC_WRITE_BYTES: number;
 export interface AtomicWriteOptions {
     /** Skip the pre-rename fsync (tests / truly ephemeral data). */
     readonly skipFsync?: boolean;
+    /** File mode for the per-write temporary file before rename. */
+    readonly mode?: number;
     /**
      * Override the bounded-write cap (default MAX_ATOMIC_WRITE_BYTES). Exposed
      * so the bound itself is testable without allocating 256 MiB.

package/dist/utils/canonical-root.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Canonical project-root keying for session-scoped module state (issue #2041).
+ *
+ * The trajectory cache (src/prm/trajectory-store.ts), the step counters
+ * (src/hooks/trajectory-step-state.ts), and the logger's restart-seed gate
+ * (src/hooks/trajectory-logger.ts) are all process-global maps that a
+ * multi-root host can share through one plugin module instance. They must key
+ * by canonical root + session id, and they must agree on what "canonical"
+ * means: realpath resolves junction/symlink aliases (linked worktrees on
+ * Windows are junctions), `path.resolve` is the fallback for a root that does
+ * not exist yet, and Windows roots are case-folded because the filesystem is.
+ * A symlinked `.swarm` directory itself is already rejected by
+ * `validateSwarmPath`, so the aliasing this resolves lives strictly ABOVE
+ * `.swarm`. One shared implementation so the three maps cannot drift.
+ */
+/**
+ * Separator between canonical root and session id in composite keys.
+ * `String.fromCharCode(0)` rather than an escape literal so the source stays
+ * clean text (a literal NUL byte in source makes tooling treat the file as
+ * binary); NUL cannot appear in a path on any supported platform.
+ */
+export declare const SESSION_KEY_SEPARATOR: string;
+export declare function canonicalRootKey(directory: string): string;
+/** Composite map key: canonical root + NUL + session id. */
+export declare function compositeSessionKey(directory: string, sessionId: string): string;
+/**
+ * Suffix every root's key for a session ends with. Suffix-scan clear paths
+ * that legitimately lack a directory (the `/swarm reset` entry points) match
+ * all roots with this.
+ */
+export declare function sessionKeySuffix(sessionId: string): string;

package/dist/workflow/coder-settlement.d.ts

@@ -1,5 +1,6 @@
 import type { BackgroundTaskChangeContext, BackgroundWorktreeDescriptor } from '../background/pending-delegations.js';
 import { type TaskEvidence } from '../gate-evidence.js';
+import { removeWorktreeProvisioningOwner } from '../hooks/delegation-gate/worktree-provisioning-owner.js';
 import type { MergeOperationProvenance } from '../worktree/merge.js';
 import type { CoderSettlementWal } from './workflow-wal-schema.js';
 export interface CoderSettlementResult {
@@ -161,6 +162,7 @@ export declare function recoverStaleCoderSettlements(directory: string, options?
 }>;
 export declare const _internals: {
     liveDispatches: Set<string>;
+    removeWorktreeProvisioningOwner: typeof removeWorktreeProvisioningOwner;
     /**
      * Test seam for the lane-branch existence probe. Production reads it here,
      * so the #2236 fail-closed invariants — never mark a WAL terminal while the

package/dist/worktree/index.d.ts

@@ -1,5 +1,5 @@
 export type { AutoCommitSkip, AutoCommitSuccess, CleanCheckFailure, CleanCheckSuccess, CleanFailure, CleanSuccess, ProvisionFailure, ProvisionSuccess, RemoveFailure, RemoveSuccess, } from './core';
 export { _internals as coreInternals, assertCleanWorkingTree, autoCommitDirty, checkPathBudget, cleanUntrackedFiles, isCleanWorktree, isPathUnderSwarmWorktreeBase, makeWorktreeBranchName, provisionWorktree, removeWorktree, resolveWorktreeBaseDir, shortenWorktreePath, } from './core';
-export type { CleanupFailure, CleanupSuccess, ConflictHandlingError, ConflictInfo, DirtyMergeFailure, DirtyMergePartial, DirtyMergeSuccess, MergeConflict, MergeFailure, MergeSuccess, OrphanCleanupResult, StartupRecoveryResult, } from './merge';
-export { _internals as mergeInternals, attemptMergeBackFromDirty, cleanupOrphanedBranches, getMergeStrategy, handleMergeConflict, mergeLaneBranch, postMergeCleanup, pruneStaleWorktreeMetadata, scanRegisteredWorktreeLiveness, startupOrphanRecovery, } from './merge';
+export type { CleanupFailure, CleanupSuccess, ConflictHandlingError, ConflictInfo, DirtyMergeFailure, DirtyMergePartial, DirtyMergeSuccess, ImmutableMergeRecoveryCoordinates, ImmutableMergeRecoveryResult, MergeConflict, MergeFailure, MergeSuccess, OrphanCleanupResult, StartupRecoveryResult, } from './merge';
+export { _internals as mergeInternals, attemptMergeBackFromDirty, cleanupOrphanedBranches, getMergeStrategy, handleMergeConflict, mergeLaneBranch, postMergeCleanup, pruneStaleWorktreeMetadata, recoverMergeBackFromImmutableCoordinates, scanRegisteredWorktreeLiveness, startupOrphanRecovery, } from './merge';
 export * from './types';

package/dist/worktree/merge.d.ts

@@ -30,6 +30,8 @@ export declare const _internals: {
     cleanupOrphanedBranches: typeof cleanupOrphanedBranches;
     /** Test seam for startupOrphanRecovery — allows tests to intercept the recovery call. */
     startupOrphanRecovery: typeof startupOrphanRecovery;
+    /** Test seam for the dirty merge overlap preflight. */
+    captureMergeOverlapSnapshot: typeof captureMergeOverlapSnapshot;
     /** FR-001b: exposes extractSessionId for lane ownership validation. */
     extractSessionId: typeof extractSessionId;
     /**
@@ -156,6 +158,26 @@ export type MergeReconciliationResult = {
     landed: false;
     error?: string;
 };
+/**
+ * Immutable preserved-lane coordinates captured by the #2105 recovery
+ * authority. This path deliberately consumes exact object ids rather than a
+ * mutable branch ref, so a redispatch can recover the preserved lane even if
+ * the lane branch later advances, rewinds, or is renamed.
+ */
+export interface ImmutableMergeRecoveryCoordinates {
+    sourceBaseOid: string;
+    sourceHeadOid: string;
+    targetHeadOid: string;
+    strategy: MergeStrategy;
+}
+export type ImmutableMergeRecoveryResult = (MergeSuccess & {
+    sourceCommitOrder?: string[];
+    rewrittenCommitOrder?: string[];
+}) | (MergeConflict & {
+    sourceCommitOrder?: string[];
+}) | (MergeFailure & {
+    sourceCommitOrder?: string[];
+});
 export interface DirtyMergeOptions {
     /** Stable identifier allocated before the merge-back begins. */
     operationId?: string;
@@ -167,6 +189,20 @@ export interface DirtyMergeOptions {
      */
     onBeforeMerge?: (provenance: MergeOperationProvenance) => Promise<void>;
 }
+interface MergeOverlapSnapshot {
+    targetHead: string;
+    laneHead: string;
+    mergeBase: string;
+    indexDigest: string;
+    statusDigest: string;
+    incomingDigest: string;
+    overlapPaths: string[];
+}
+declare function captureMergeOverlapSnapshot(primaryDir: string, branchName: string): Promise<{
+    snapshot: MergeOverlapSnapshot;
+} | {
+    error: string;
+}>;
 export interface OrphanCleanupResult {
     removed: string[];
     skipped: string[];
@@ -219,6 +255,17 @@ export declare function getMergeStrategy(config: {
  * @returns Discriminated union: success, conflict, or failure.
  */
 export declare function mergeLaneBranch(primaryDir: string, branchName: string, strategy: MergeStrategy): Promise<MergeSuccess | MergeConflict | MergeFailure>;
+/**
+ * Re-applies a preserved lane using exact immutable object ids captured by the
+ * #2105 recovery authority.
+ *
+ * This is the strategy-specific recovery primitive that `worktree-isolation`
+ * can call when a same-task redispatch claims a preserved lane. It refuses to
+ * operate on mutable branch refs, verifies that the captured lane ancestry is
+ * coherent, and fails closed if the current primary checkout no longer
+ * descends from the captured target head.
+ */
+export declare function recoverMergeBackFromImmutableCoordinates(primaryDir: string, coordinates: ImmutableMergeRecoveryCoordinates): Promise<ImmutableMergeRecoveryResult>;
 /**
  * Detect whether a previously-started merge-back already landed on the target.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-swarm",
-	"version": "7.153.0",
+	"version": "7.153.2",
 	"description": "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -111,7 +111,14 @@
 		"check:retention": "bun run scripts/check-retention-registry.ts",
 		"check:core-events": "bun run scripts/check-core-events-usage.ts",
 		"check:shell-audit": "bun run scripts/check-shell-audit-usage.ts",
+		"check:trajectory-store": "bun run scripts/check-trajectory-store-usage.ts",
+		"check:mock-cleanup": "bun run scripts/check-mock-cleanup.ts",
+		"check:invariants": "bun run scripts/check-invariants.ts",
+		"check:cross-contamination": "bun run scripts/check-cross-contamination.ts",
+		"check:test-clock": "bun run scripts/check-test-clock.ts",
 		"check:test-file-cap": "bun run scripts/check-test-file-cap.ts",
+		"check:test-tmpdir": "bun run scripts/check-test-tmpdir.ts",
+		"check:bash-portability": "bun run scripts/check-bash-portability.ts",
 		"check:pending-fragment": "bun run scripts/check-pending-fragment.ts",
 		"check:gate-portability": "bun run scripts/check-gate-portability.ts",
 		"check:bare-spawn": "bun run scripts/check-bare-executable-spawn.ts",