opencode-swarm 7.166.1 → 7.166.3

package/dist/knowledge/curation-policy.d.ts

@@ -85,6 +85,13 @@ export interface CohortQuorumConfig {
     /** Minimum distinct cohort events (e.g. violations) required to authorize. */
     minCohortEvidence: number;
 }
+/**
+ * Global FIFO cap on the curation-proposals audit stream (issue #2483 §2).
+ * Enforcement resolves the effective value through `resolveRetentionCap` so
+ * the #2483 acceptance checks can shrink the cap below this default and prove
+ * the writer clamps.
+ */
+export declare const MAX_CURATION_PROPOSALS = 200;
 /**
  * Authorize a destructive curation action against a single entry.
  *

package/dist/memory/consolidation-log.d.ts

@@ -31,5 +31,14 @@ export interface ConsolidationLogRecord {
     errored: number;
     processedProposalIds: string[];
 }
+/**
+ * Global FIFO cap on the consolidation log (issue #2483 §2). Enforcement and
+ * the bounded read both resolve the effective value through
+ * `resolveRetentionCap` so the #2483 acceptance checks can shrink the cap
+ * below this default and prove the writer clamps. The cap keeps last-N
+ * semantics: records are returned oldest-to-newest, so callers that
+ * `slice(-limit)` for the CLI's last-N view keep working.
+ */
+export declare const MAX_CONSOLIDATION_LOG_ENTRIES = 500;
 export declare function readConsolidationLog(target: string | VettedMemoryRoot): Promise<ConsolidationLogRecord[]>;
 export declare function appendConsolidationLog(target: string | VettedMemoryRoot, record: ConsolidationLogRecord): Promise<void>;

package/dist/memory/injector.d.ts

@@ -33,6 +33,13 @@ export interface MemoryLifecycleHooks {
     toolAfter(input: unknown, output: unknown): Promise<void>;
 }
 export declare function createMemoryLifecycleHooks(options: MemoryLifecycleHookOptions): MemoryLifecycleHooks;
+/**
+ * Global FIFO cap on the (env-gated) unitid-probe audit stream (issue #2483
+ * §2). Enforcement resolves the effective value through
+ * `resolveRetentionCap` so the #2483 acceptance checks can shrink the cap
+ * below this default and prove the writer clamps.
+ */
+export declare const MAX_UNITID_PROBE_ENTRIES = 2000;
 declare function messagesContainRecall(messages: unknown[]): boolean;
 declare function recallMessageInsertIndex(messages: unknown[]): number;
 declare function compactText(text: string): string;

package/dist/memory/run-log.d.ts

@@ -20,5 +20,13 @@ export interface MemoryRunLogEvent {
     memoriesDecayed?: number;
     metadata?: Record<string, unknown>;
 }
+/**
+ * Global FIFO cap on each run's `memory.jsonl` run log (issue #2483 §2).
+ * Enforcement resolves the effective value through `resolveRetentionCap` so
+ * the #2483 acceptance checks can shrink the cap below this default and
+ * prove the writer clamps. Keyspace (run directories) is handled by the
+ * retention sweep and close lifecycle.
+ */
+export declare const MAX_RUN_LOG_ENTRIES = 2000;
 export declare function appendMemoryRunLog(directory: string, runId: string | undefined, event: MemoryRunLogEvent): Promise<void>;
 export declare function sanitizeRunId(runId: string | undefined): string;

package/dist/observability/catalog.d.ts

@@ -2,7 +2,7 @@
  * The event catalog (issue #2029).
  *
  * Exactly 61 entries, matching the `TelemetryEvent` union at
- * `src/telemetry.ts:16-172`. Thirty-eight predate the #2029 contract; the 39th is
+ * `src/telemetry.ts:20-172`. 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
  * structured close/archive result event), the 41st is the bounded diagnostic

package/dist/retention/caps.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Test-visible cap seam for every #2483 retention bound (issue #2483 §0).
+ *
+ * Writers keep their cap constants exported on their own modules (registry
+ * citations point there), but ENFORCEMENT must resolve the effective value
+ * through {@link resolveRetentionCap} so tests and acceptance checks can
+ * shrink a cap below its production default and prove the writer actually
+ * clamps. A writer that reads only its own constant is unfalsifiable at cap+1
+ * test widths that are impractical to write (10 000 entries / 8 MiB).
+ *
+ * Pure module: no filesystem, no imports — safe on the init path and under
+ * both the Bun and Node hosts (AGENTS.md invariant 2).
+ */
+/** Canonical cap names (frozen by the #2483 acceptance checks). */
+export type RetentionCapName = 'MAX_RETRACTION_RECORDS' | 'MAX_UNACKNOWLEDGED_CRITICALS' | 'MAX_CURATION_PROPOSALS' | 'MAX_CONSOLIDATION_LOG_ENTRIES' | 'MAX_CONTEXT_SNAPSHOT_BYTES' | 'MAX_CONTEXT_SNAPSHOT_ENTRIES' | 'MAX_CALIBRATION_MODULES' | 'MAX_DIVERGENCE_BYTES' | 'MAX_TEST_HISTORY_ENTRIES' | 'MAX_TEST_HISTORY_KEYS' | 'MAX_SKILL_CHANGELOG_ENTRIES_PER_SKILL' | 'MAX_SKILL_CHANGELOG_GLOBAL_ENTRIES' | 'MAX_RECEIPTS_READ' | 'MAX_CAPSULES_LISTED' | 'MAX_SUMMARIES_LISTED' | 'MAX_RUN_LOG_ENTRIES' | 'MAX_UNITID_PROBE_ENTRIES';
+/**
+ * Install test cap overrides (partial). Production code never calls this;
+ * tests and the #2483 acceptance checks do. Values are validated to be
+ * positive finite numbers so a bad fixture fails loudly at install time.
+ */
+export declare function setRetentionCapOverrides(partial: Partial<Record<RetentionCapName, number>>): void;
+/** Clear every override (test teardown). */
+export declare function clearRetentionCapOverrides(): void;
+/**
+ * Resolve the effective cap for {@link name}: the installed override when
+ * present, otherwise {@link defaultValue}. Every capped writer routes its
+ * enforcement through this function.
+ */
+export declare function resolveRetentionCap(name: RetentionCapName, defaultValue: number): number;
+/** Test/inspection seam. */
+export declare const _internals: {
+    overrides: Map<string, number>;
+};

package/dist/retention/dir-prune.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Age/count directory pruner (issue #2483 §1).
+ *
+ * Deletes the OLDEST entries (mtime ascending, deterministic code-unit name
+ * tie-break — never localeCompare) until the directory is within its caps.
+ *
+ * A DIRECTORY entry is aged by its CONTENT, not by the directory node's own
+ * mtime: the effective mtime is the newest regular-file mtime anywhere in the
+ * subtree (bounded, symlink-refusing). A directory's own mtime only reflects
+ * metadata churn (entry creates/deletes/renames — e.g. another pruner
+ * deleting a sibling refreshes the parent), so content age is the honest
+ * "last write activity" signal. An empty subtree falls back to the
+ * directory's own mtime; an unreadable or scan-budget-exhausted subtree is
+ * treated as unprunable (effective mtime +Infinity — never a victim).
+ *
+ * Containment properties (issue #2483 edge cases):
+ *  - symlink/junction entries are NEVER traversed or deleted (lstat check —
+ *    the #2127 marker-symlink precedent), including inside subtrees;
+ *  - entries with future mtimes (clock skew) are NEVER pruned;
+ *  - enumeration is bounded (`maxScan`, per directory level AND per subtree
+ *    walk) so a huge directory cannot turn the pruner into an unbounded scan
+ *    on a cold Windows filesystem;
+ *  - per-entry failures are swallowed (fail-open): one unreadable entry
+ *    never aborts the family.
+ */
+export interface PruneDirectoryOptions {
+    /** Keep at most this many entries (newest by mtime). */
+    maxEntries?: number;
+    /** Delete entries strictly older than this (ms before `now`). */
+    maxAgeMs?: number;
+    /** Clock injection point for tests/checks. */
+    now?: number;
+    /**
+     * Enumeration bound (default 100000 — review FB-12: 20000 stat ops could
+     * exhaust before a legitimately large keyspace finished enumerating,
+     * silently skipping stale tail entries; the budget is stats, not
+     * deletions, so the higher ceiling stays bounded).
+     */
+    maxScan?: number;
+    /** Count victims without deleting (blast-radius rehearsal / dry_run). */
+    dryRun?: boolean;
+}
+export interface PruneCandidate {
+    name: string;
+    mtimeMs: number;
+}
+/**
+ * Effective mtime of a subtree: the newest regular-file mtime found inside
+ * (never traversing symlinks), or `null` when the subtree contains no files.
+ * `POSITIVE_INFINITY` signals "could not verify within budget" — callers must
+ * treat that as unprunable. The walk is bounded by `maxScan` stat operations
+ * total, so a pathological subtree degrades to keep, never to an unbounded
+ * scan.
+ */
+export declare function subtreeNewestFileMtime(root: string, maxScan: number): number | null;
+/**
+ * Per-subtree walk budget. Deliberately NOT the caller's `maxScan`: the
+ * top-level enumeration bound must not multiply into every child subtree.
+ * Run/batch/candidate directories hold a handful of files each; 2000 stat
+ * operations per subtree is generous, and exhausting it degrades to keep.
+ */
+export declare const SUBTREE_SCAN_CAP = 2000;
+/** List bounded entries with effective mtimes; symlinked entries are collected separately and refused. */
+export declare function listPruneCandidates(dir: string, maxScan: number): {
+    candidates: PruneCandidate[];
+    refusedSymlinks: string[];
+};
+/**
+ * Prune `dir` down to its caps. Returns the number of entries deleted. A
+ * missing directory is a no-op (0). `dryRun` counts without deleting.
+ */
+export declare function pruneDirectory(dir: string, opts: PruneDirectoryOptions): Promise<number>;

package/dist/retention/jsonl-cap.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Capped JSONL append + bounded tail read (issue #2483 §1).
+ *
+ * `appendCappedJsonl` enforces the entry/byte caps on EVERY completed state:
+ * when an append would push the file past its caps, the compacted prefix
+ * (newest whole records that fit, minus the incoming record) is first
+ * swapped in crash-atomically (temp file + rename with a Windows
+ * transient-error retry), then the new record is appended — so an
+ * interleaved reader never observes more than the caps. Compaction has a
+ * whole-record floor: a non-empty stream is never emptied by compaction —
+ * at least the newest single record always survives, whatever the effective
+ * cap (the #2483 acceptance contract).
+ *
+ * Concurrency: all calls for the same `filePath` serialize through a
+ * per-file async mutex, so in-process concurrent appenders can never lose a
+ * line to the compaction rename (review finding FB-4). Cross-process
+ * writers remain best-effort by the documented fail-open contract (audit
+ * streams; the one lockfile-guarded writer predates this module).
+ *
+ * `readTailJsonl` reads only the last `maxBytes` bytes (newline-aligned) and
+ * parses at most `maxEntries` records from the end, so every reader that
+ * routes through it is O(cap), not O(history). `readTailJsonlDetailed`
+ * additionally reports whether a torn trailing line was skipped, for
+ * callers whose conservative decisions depend on tail completeness.
+ *
+ * Plumbing module: callers own their streams (retention-registry exemption;
+ * callers' rows carry the citations).
+ */
+export interface CappedJsonlOptions {
+    maxEntries: number;
+    /** Optional byte cap for the compacted file. */
+    maxBytes?: number;
+    /**
+     * Invoked when compaction drops `droppedCount` oldest records to enforce
+     * the caps. Lets stream owners surface truncation (review finding FB-5)
+     * instead of failing silently; failures thrown here are swallowed.
+     */
+    onPrune?: (droppedCount: number) => void;
+}
+declare function withFileLock<T>(filePath: string, task: () => Promise<T>): Promise<T>;
+/**
+ * Test/inspection seam (review round 2): exposes the mutex so the
+ * concurrent-append test can assert the chain fully drains instead of
+ * reasoning about the self-deletion logic.
+ */
+export declare const _internals: {
+    appendChains: Map<string, Promise<void>>;
+    withFileLock: typeof withFileLock;
+};
+/**
+ * Append `line` (a bare JSON record without the trailing newline) to
+ * `filePath`, enforcing the caps with a crash-atomic compaction when
+ * exceeded. Calls for the same file serialize through a per-file async
+ * mutex (in-process writers never lose lines to the compaction rename);
+ * the compaction rewrite is temp+rename, so a crash mid-compaction leaves
+ * either the old complete file or the new complete file — never a torn one.
+ */
+export declare function appendCappedJsonl(filePath: string, line: string, opts: CappedJsonlOptions): Promise<void>;
+export interface TailJsonlOptions {
+    maxEntries?: number;
+    maxBytes?: number;
+}
+export interface TailJsonlResult<T> {
+    records: T[];
+    /**
+     * True when a torn (unterminated) trailing line was skipped by the
+     * newline-alignment or whole-line filter. Conservative callers (e.g.
+     * evolution terminal detection) treat this as "state uncertain".
+     */
+    tailTruncated: boolean;
+}
+/**
+ * Bounded tail read: returns at most `maxEntries` records parsed from the
+ * end of the file, reading no more than `maxBytes` bytes. Malformed lines
+ * are skipped (they can be a torn final write); a missing file is `[]`.
+ */
+export declare function readTailJsonl<T>(filePath: string, opts: TailJsonlOptions): Promise<T[]>;
+/**
+ * Bounded tail read that also reports whether a torn trailing line was
+ * skipped, so conservative callers can distinguish "no record" from
+ * "state uncertain" (review FB-11).
+ */
+export declare function readTailJsonlDetailed<T>(filePath: string, opts: TailJsonlOptions): Promise<TailJsonlResult<T>>;
+export {};

package/dist/retention/sweep.d.ts

@@ -0,0 +1,67 @@
+/**
+ * One bounded, fail-open retention sweep over the residual keyspace families
+ * under `<projectRoot>/.swarm/` (issue #2483 §3).
+ *
+ * Production triggers: the wrapper-owned post-resolution task registered in
+ * `src/index.ts` (withTimeout-bounded, off the `server()`-resolution path —
+ * AGENTS.md invariant 1) and one pass before the `/swarm close` clean stage.
+ *
+ * Safety properties (tested in tests/unit/retention/sweep-2483.test.ts and
+ * edge-cases-2483.test.ts):
+ *  - only ever touches paths under `<projectRoot>/.swarm/`; nothing outside
+ *    survives-or-dies by accident (containment asserted by test);
+ *  - fail-open per family — one family's error never aborts the others and
+ *    never throws to the caller;
+ *  - future-mtime entries are never pruned; symlinked entries are never
+ *    traversed (dir-prune guards);
+ *  - `dryRun` reports what WOULD be pruned without deleting (the blast-
+ *    radius rehearsal mode; also the `retention.dry_run` config surface);
+ *  - the summaries family honors `summaries.retention_days` (default 7) by
+ *    delegating to `cleanupSummaries` (content-timestamp with mtime
+ *    fallback), which this sweep is the first production caller of — the
+ *    previously-dead `retention_days` setting becomes live.
+ *  - authoritative streams (plan ledger, knowledge store, council, evidence,
+ *    scopes, swarm.db, telemetry) are NOT in any family and are never
+ *    touched (negative test).
+ */
+/** Default age horizon for keyspace families (30 days). */
+export declare const DEFAULT_FAMILY_AGE_DAYS = 30;
+/** Summaries horizon comes from summaries.retention_days (default 7). */
+export declare const DEFAULT_SUMMARIES_RETENTION_DAYS = 7;
+/** Age-only backstop for evolution candidates whose state is unreadable. */
+export declare const EVOLUTION_BACKSTOP_AGE_DAYS = 90;
+/** Keep-newest caps layered on top of age for high-churn run/batch dirs. */
+export declare const PR_REVIEW_KEEP_NEWEST_RUNS = 50;
+export declare const LANE_RESULTS_KEEP_NEWEST_BATCHES = 100;
+export declare const REVIEW_RECEIPTS_KEEP_NEWEST = 1000;
+export interface RetentionSweepOptions {
+    /** Clock injection point for tests/checks. */
+    now?: number;
+    /** Count-and-report without deleting (blast-radius rehearsal / config). */
+    dryRun?: boolean;
+    /** Honored from `retention.enabled`; when false the sweep is a no-op. */
+    enabled?: boolean;
+    /** Honored from `summaries.retention_days`. */
+    summariesRetentionDays?: number;
+    /**
+     * Cooperative stop token, polled between families/passes (review FB-10).
+     * The post-init scheduler flips it when the outer `withTimeout` budget
+     * expires so an in-flight sweep abandons the remaining families instead
+     * of finishing its full pass after the awaiter already moved on.
+     */
+    shouldContinue?: () => boolean;
+}
+export interface RetentionSweepResult {
+    pruned: Record<string, number>;
+    disabled?: boolean;
+    dryRun?: boolean;
+    errors: Record<string, string>;
+}
+/**
+ * Prune stale keyspace families under `.swarm/`, age-delete the rebuildable
+ * epic diagnostics, expire legacy `.imported` doc-drift cold archives, run
+ * the summaries retention pass, and prune evolution candidates that reached
+ * a terminal lifecycle state (with an age-only backstop). Every family is
+ * individually fail-open; the function itself never throws.
+ */
+export declare function runRetentionSweep(projectRoot: string, options?: RetentionSweepOptions): Promise<RetentionSweepResult>;

package/dist/services/compaction-service.d.ts

@@ -20,6 +20,20 @@
 import type { CompactionConfig } from '../config/schema';
 export type { CompactionConfig };
 export declare const MAX_TRACKED_COMPACTION_SESSIONS = 500;
+/**
+ * Global byte cap on `.swarm/context-snapshot.md` (issue #2483 §2). Enforced
+ * via `appendCappedJsonl` with a high entry count so only the byte budget
+ * binds; compaction keeps the newest whole records that fit and never empties
+ * a non-empty snapshot (whole-record floor ≥ 1 entry).
+ */
+export declare const MAX_CONTEXT_SNAPSHOT_BYTES = 65536;
+/**
+ * Whole-record ceiling for the snapshot file (review FB-8). Only the byte
+ * budget binds in practice; this entry cap is a pure defense-in-depth bound
+ * and resolves through the seam like every other #2483 cap so tests can
+ * shrink it.
+ */
+export declare const MAX_CONTEXT_SNAPSHOT_ENTRIES = 100000;
 export interface CompactionServiceHook {
     toolAfter: (input: {
         tool: string;

package/dist/services/skill-changelog.d.ts

@@ -1,4 +1,24 @@
+/**
+ * Per-skill FIFO cap (issue #2483 §2). Enforcement routes the append through
+ * `appendCappedJsonl`, so the trim is crash-atomic (temp + rename), and
+ * resolves the effective value through `resolveRetentionCap` so the #2483
+ * acceptance checks can shrink the cap below this default and prove the
+ * writer clamps.
+ */
+export declare const MAX_SKILL_CHANGELOG_ENTRIES_PER_SKILL = 200;
+/**
+ * Legacy alias for {@link MAX_SKILL_CHANGELOG_ENTRIES_PER_SKILL} — retained
+ * for existing citations (`scripts/retention-registry.data.ts`) and tests.
+ */
 export declare const MAX_CHANGELOG_ENTRIES_PER_SKILL = 200;
+/**
+ * Global ceiling on TOTAL changelog entries across every per-skill file
+ * (issue #2483 §2). Enforced on EVERY append (critic N3 — deliberately no
+ * cadence) by scanning the changelog directory; the scan is bounded by the
+ * ceiling itself (one entry per slug ⇒ at most `cap` files / `cap` entries
+ * to enumerate). Appends are rare, so the per-append scan cost is accepted.
+ */
+export declare const MAX_SKILL_CHANGELOG_GLOBAL_ENTRIES = 10000;
 export interface SkillChangelogEntry {
     version: number;
     timestamp: string;

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

@@ -104,6 +104,48 @@ export interface SerializedAgentSession {
     /** Provider id paired with lastObservedModel (#1896). Omitted when undefined. */
     lastObservedProviderID?: string;
 }
+/**
+ * Compile-time snapshot-field parity map (issue #2472 W6 / AC-7; frozen check C7).
+ *
+ * WHY THIS MAP EXISTS — the serializer reads FROM `AgentSessionState` and
+ * writes TO `SerializedAgentSession`, so the drift-prone direction is a field
+ * that exists on the live state but silently never reaches the snapshot:
+ * nothing fails, the field is just lost on every restart. The
+ * `Record<Exclude<keyof AgentSessionState, keyof SerializedAgentSession>, string>`
+ * key type makes that direction exhaustive at compile time — EVERY state field
+ * that is not a serialized field MUST appear here with a one-line rationale,
+ * and a key that is NOT such a field is an excess-property type error. Adding
+ * a field to either interface without reconciling this map fails
+ * `bun run typecheck` (CI gate).
+ *
+ * The serialized-only direction (a `SerializedAgentSession` field with no
+ * `AgentSessionState` counterpart) is guarded separately by the
+ * `_serializedFieldsExistOnState` assertion below. The asymmetry is
+ * deliberate: the serializer can only *drop* state fields, while the reader
+ * could otherwise *invent* fields the live state does not have.
+ *
+ * This is NOT the same list as `TRANSIENT_SESSION_FIELDS` in
+ * `src/session/snapshot-reader.ts` (fields RESET on rehydration — a subset of
+ * the *serialized* fields). This map lists fields that are NEVER serialized.
+ * Most are genuinely process-local; `workspaceDirectory` is deliberately
+ * unserializable for trust reasons (see its TRUST BOUNDARY comment in
+ * `src/state.ts`), which is exactly why it must carry an entry here rather
+ * than fall out of the type silently.
+ *
+ * The runtime mirror of this guard lives at
+ * `tests/unit/session/snapshot-field-parity-guard.test.ts` (what frozen
+ * check C7 runs).
+ */
+export declare const SESSION_TRANSIENT_FIELDS: Readonly<Record<Exclude<keyof AgentSessionState, keyof SerializedAgentSession>, string>>;
+/**
+ * Reverse-direction parity guard: every `SerializedAgentSession` field must
+ * exist on `AgentSessionState`. The const assignment is what makes tsc
+ * actually enforce the conditional type — when a serialized field has no
+ * state counterpart, the type degrades to the error tuple below and assigning
+ * `true` fails `bun run typecheck` with that message.
+ */
+export type SerializedFieldsAllExistOnState = Exclude<keyof SerializedAgentSession, keyof AgentSessionState> extends never ? true : ['SerializedAgentSession field missing from AgentSessionState'];
+export declare const _serializedFieldsExistOnState: SerializedFieldsAllExistOnState;
 /**
  * Minimal interface for serialized InvocationWindow
  */

package/dist/summaries/manager.d.ts

@@ -17,13 +17,50 @@ export declare function storeSummary(directory: string, id: string, fullOutput:
  */
 export declare function loadFullOutput(directory: string, id: string): Promise<string | null>;
 /**
- * List all summary IDs that have summary entries.
- * Returns sorted array of valid summary IDs.
- * Returns empty array if summaries directory doesn't exist.
+ * Listing cap for `.swarm/summaries/` enumeration (issue #2483 §2, R12): the
+ * public list returns NEWEST-first (mtime descending, code-unit filename
+ * tie-break — never localeCompare) and is capped, so every listing read is
+ * O(cap), not O(unbounded summary history). The effective value resolves
+ * through `resolveRetentionCap` so the #2483 acceptance checks can shrink it.
+ * Retention cleanup does NOT go through this capped view — it enumerates the
+ * directory directly so stale files beyond the newest N are still pruned.
+ */
+export declare const MAX_SUMMARIES_LISTED = 500;
+/**
+ * List summary IDs that have summary entries, newest-first (mtime
+ * descending, code-unit filename tie-break), capped at
+ * {@link MAX_SUMMARIES_LISTED} entries. Returns an empty array if the
+ * summaries directory doesn't exist.
  */
 export declare function listSummaries(directory: string): Promise<string[]>;
+/**
+ * List summary IDs past the retention horizon WITHOUT deleting them (review
+ * FB-9: the single detection predicate shared by `cleanupSummaries` and the
+ * sweep's dry-run counter, so rehearsal and deletion can never diverge).
+ *
+ * Retention cleanup enumerates the directory DIRECTLY (uncapped): the
+ * public listSummaries is capped to the newest MAX_SUMMARIES_LISTED, and
+ * routing cleanup through it would skip stale files beyond that window
+ * (issue #2483).
+ *
+ * Retention also enumerates LENIENTLY: `enumerateSummaryIds` applies the
+ * strict write-side `^S\d+$` id grammar, but retention's job is to bound
+ * the keyspace — ANY `S*.json` occupant past the horizon is stale
+ * regardless of whether its id would pass write validation (legacy or
+ * foreign producers included).
+ *
+ * Detection is content-timestamp-first: a numeric `timestamp` older than the
+ * cutoff marks the entry stale; a missing/unparsable timestamp falls back to
+ * the file mtime (issue #2483); unreadable content or a parse failure is
+ * never stale (a `warn` is emitted for the latter, as deletion does).
+ */
+export declare function listStaleSummaryIds(directory: string, retentionDays: number, options?: {
+    now?: number;
+}): Promise<string[]>;
 /**
  * Delete summaries older than retentionDays.
  * Returns array of deleted summary IDs.
  */
-export declare function cleanupSummaries(directory: string, retentionDays: number): Promise<string[]>;
+export declare function cleanupSummaries(directory: string, retentionDays: number, options?: {
+    now?: number;
+}): Promise<string[]>;

package/dist/telemetry.d.ts

@@ -66,7 +66,37 @@ export declare function resetTelemetryForTesting(): void;
 /**
  * Initialize telemetry with the project directory.
  * Creates `.swarm/` if it doesn't exist and opens `telemetry.jsonl` for appending.
- * Idempotent — calling multiple times has no effect after the first successful call.
+ * Idempotent — calling multiple times with the SAME directory has no effect
+ * after the first successful call.
+ *
+ * Re-home (issue #2472 W9): when called with a projectDirectory DIFFERENT
+ * from the latched `_projectDirectory` while a stream exists (a second
+ * server() instance initializing in this process for another project root),
+ * telemetry re-initializes for the new directory exactly as a fresh init
+ * does — the previous behavior latched the first directory forever, so the
+ * second project's `.swarm/telemetry.jsonl` was never created. A disabled
+ * telemetry state stays disabled.
+ *
+ * No-drop ordering + fail-open ownership retention (PR #2588, review finding
+ * 6 / PRR-019): the NEW stream is created and published FIRST, and only then
+ * is the old stream flushed/closed best-effort. The previous
+ * close-then-create order nulled `_writeStream` before the replacement
+ * existed, so any emit racing the re-home was dropped by the
+ * `_writeStream === null` guard, and a new-stream creation FAILURE took the
+ * whole process's telemetry down (`_disabled = true`) after the old stream
+ * was already gone. On creation failure the OLD stream is now retained
+ * (logged non-fatally, no re-home) — events keep flowing to the previous
+ * directory until a later successful init.
+ *
+ * OWNERSHIP CONTRACT (last-init-wins): the newest successful initTelemetry
+ * call owns THE single live stream for the whole process. In a
+ * multi-project process, a project initialized earlier SHARES the latest
+ * stream until it re-initializes; per-event project routing is out of scope
+ * — the issue #2472 obligation is directory-CHANGE detection, not per-event
+ * fan-out. Same-directory detection uses canonical project-root identity
+ * (`sameProjectRoot`), so Windows case differences and symlink/junction
+ * spellings of one root do not churn the stream.
+ *
  * @param projectDirectory - Absolute path to the project root
  */
 export declare function initTelemetry(projectDirectory: string): void;

package/dist/test-impact/history-store.d.ts

@@ -11,6 +11,22 @@ export interface TestRunRecord {
     stackPrefix?: string;
     changedFiles: string[];
 }
+/**
+ * Global cap on TOTAL entries in `.swarm/cache/test-history.jsonl` (issue
+ * #2483 §2). Enforced inside the existing read-prune-write pass on EVERY
+ * append — deliberately no amortized cadence (critic N3): a cadence like
+ * every-512-appends would never fire inside a shrunken test override width
+ * and silently fail the #2483 acceptance check. The effective value resolves
+ * through `resolveRetentionCap`.
+ */
+export declare const MAX_TEST_HISTORY_ENTRIES = 5000;
+/**
+ * Global cap on DISTINCT (testFile, testName) keys in the history file
+ * (issue #2483 §2): when distinct keys exceed the cap, the oldest-key records
+ * are dropped entirely (keyspace prune). Enforced on every append alongside
+ * {@link MAX_TEST_HISTORY_ENTRIES}.
+ */
+export declare const MAX_TEST_HISTORY_KEYS = 1000;
 export declare function batchAppendTestRuns(records: TestRunRecord[], workingDir?: string): void;
 export declare function appendTestRun(record: TestRunRecord, workingDir?: string): void;
 export declare function getTestHistory(testFile: string, workingDir?: string): TestRunRecord[];

package/dist/turbo/epic/calibration.d.ts

@@ -27,7 +27,11 @@ export interface CalibrationState {
      * Modules promoted to the hot-module list by observed divergence.
      * Monotonically grows — never auto-shrinks (loosening the hot-module
      * list requires manual intervention; the calibration loop only adds).
-     * Sorted lexicographically for stable diffs.
+     * Sorted lexicographically for stable diffs. Bounded at
+     * {@link MAX_CALIBRATION_MODULES} on every save and load (issue #2483):
+     * once the cap binds, late-alphabet module paths are PERMANENTLY
+     * excluded from the list and — because additions are monotonic — can
+     * never re-enter (critic N5).
      */
     hotModuleAdditions: string[];
     /**
@@ -42,6 +46,17 @@ export interface CalibrationState {
     /** Number of divergence records processed by the engine so far. */
     processedRecords: number;
 }
+/**
+ * Global cap on the persisted `hotModuleAdditions` list (issue #2483 §2).
+ * Enforcement (save AND load) keeps the lexicographically SMALLEST prefix of
+ * the sorted list — deterministic and order-respecting, with no invented
+ * score. N5 bias, stated plainly: once the cap binds, late-alphabet module
+ * paths are permanently excluded from the list and — because additions are
+ * monotonic — can never re-enter. The effective value resolves through
+ * `resolveRetentionCap` so the #2483 acceptance checks can shrink the cap
+ * below this default and prove the truncation clamps.
+ */
+export declare const MAX_CALIBRATION_MODULES = 500;
 export declare function emptyCalibrationState(): CalibrationState;
 export declare function isCalibrationStateUnreadable(directory: string): boolean;
 export declare function repairCalibrationUnreadable(directory: string): void;

package/dist/turbo/epic/divergence-recorder.d.ts

@@ -40,6 +40,17 @@ export interface DivergenceRecord {
     /** True when divergenceRatio === 0 (no undeclared writes). */
     isClean: boolean;
 }
+/**
+ * Global byte cap on `.swarm/epic/divergence.jsonl` (issue #2483 §2).
+ * Byte-cap contract (critic N2): compaction retains the newest WHOLE records
+ * that fit within the effective cap, with a floor of at least one record — a
+ * non-empty stream is never emptied by compaction (one record ≈ 320 B; under
+ * any smaller effective cap the file keeps the newest single record). The
+ * effective value resolves through `resolveRetentionCap` so the #2483
+ * acceptance checks can shrink the cap below this default and prove the
+ * writer clamps.
+ */
+export declare const MAX_DIVERGENCE_BYTES: number;
 /**
  * Compute the divergence between a declared scope and the files actually
  * modified. Pure — no I/O, no side effects. Returns the diff sets plus the

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

@@ -128,6 +128,38 @@ export declare function assertWellFormedTargetPath(targetPath: string): void;
 export declare function assertSwarmContainedTarget(targetPath: string): SwarmContainment;
 /** Hard bound on a single atomic write (bounded-write requirement). */
 export declare const MAX_ATOMIC_WRITE_BYTES: number;
+/**
+ * Default window within which an ENOENT read of a target this process wrote
+ * (or is writing) is treated as plausibly mid-rename rather than never-existed
+ * — see `wasRecentlyWrittenByThisProcess` and the three-way ENOENT policy in
+ * `readSwarmFileAsync` (src/hooks/utils.ts).
+ */
+export declare const RECENT_WRITE_WINDOW_MS = 500;
+/**
+ * Remove the recent-write marker for `targetPath` (PRR-008). Called from the
+ * canonical writer's failure path: a write that throws before its rename
+ * completes must not leave a stale INTENT stamp behind, or a subsequent ENOENT
+ * read of the target would be misclassified as a rename race and retried
+ * against a file this process is no longer producing. Successful writes are
+ * unaffected — they reach the WRITE COMPLETION refresh, which re-stamps the
+ * marker for the post-rename visibility window. Returns true when a stamp was
+ * present and removed.
+ */
+export declare function clearRecentWriteActivity(targetPath: string): boolean;
+/**
+ * Whether this process recorded a write INTENT or write COMPLETION for
+ * `targetPath` within the last `withinMs` milliseconds (default
+ * {@link RECENT_WRITE_WINDOW_MS}).
+ *
+ * Consumers: the ENOENT retry ladders (`readSwarmFileAsync`,
+ * `readFileOrEmpty` in src/services/context-budget-service.ts) use this as
+ * the "evidenced rename-race" arm — an ENOENT on a file THIS process just
+ * wrote (or is mid-write on: intent is recorded before the temp file write
+ * begins) retries, while an ENOENT with no evidence the file ever existed
+ * returns immediately (issue #2472 PERF-1: 4×10ms of sleeps per missing-file
+ * read, ~1.9s/turn on plan-less projects).
+ */
+export declare function wasRecentlyWrittenByThisProcess(targetPath: string, withinMs?: number): boolean;
 export interface AtomicWriteOptions {
     /** Skip the pre-rename fsync (tests / truly ephemeral data). */
     readonly skipFsync?: boolean;

package/dist/utils/swarm-artifact-cache.d.ts

@@ -15,6 +15,12 @@ export interface SwarmArtifactCacheStats {
     textEntryCount: number;
     parsedEntryCount: number;
 }
+/**
+ * Whether a previous successful stat/read inside this module observed
+ * `filePath` to exist (resolved the same way the cache keys are). Cheap Set
+ * lookup — safe on hot paths.
+ */
+export declare function wasObservedToExist(filePath: string): boolean;
 /**
  * Dependency-injection seam for testing. Tests can temporarily replace these
  * to force a specific (e.g. colliding) stat stamp without relying on