opencode-swarm 7.166.1 → 7.166.3

package/dist/cli/{worktree-collision-ownership-pmpnftkd.js → worktree-collision-ownership-1g1qz8wc.js}

@@ -6,40 +6,41 @@ import {
   WORKTREE_PROVISIONING_OWNER_LEASE_MS,
   removeWorktreeProvisioningOwner,
   scanWorktreeProvisioningOwnersForRecovery
-} from "./index-1zqf2pny.js";
+} from "./index-9wv6a3jx.js";
 import {
   scanDelegationFallbacksForRecovery,
   scanDelegationsForRecovery
-} from "./index-w11whwn3.js";
-import"./index-bfr392e7.js";
-import"./index-ee6ydtfe.js";
+} from "./index-2c7eabkr.js";
+import"./index-sahf5yz3.js";
 import {
   bunSpawn
 } from "./index-p612v1mv.js";
-import"./index-79sr3fd1.js";
-import"./index-jx9f4ke1.js";
-import"./index-aftapk6j.js";
+import"./index-75f9jj3h.js";
+import"./index-6d4dc99f.js";
+import"./index-rk10x4zr.js";
 import"./index-ry16d01s.js";
 import"./index-n4fzmqz8.js";
-import"./index-axf65x87.js";
-import"./index-bkd3450m.js";
+import"./index-qd726agw.js";
+import"./index-8cky7ksv.js";
+import"./index-vzm6zre7.js";
 import"./index-ae75rja9.js";
-import"./index-a7rw4g4s.js";
+import"./index-t8tw1bhs.js";
+import"./index-2w0beg3s.js";
+import"./index-m21x1bkx.js";
+import"./index-f6zgz02s.js";
 import {
   canonicalRootKeyFresh
 } from "./index-7qefgq4j.js";
-import"./index-edm41q4j.js";
-import"./index-gy0nyfbw.js";
-import"./index-hwj25q9r.js";
+import"./index-ee6ydtfe.js";
 import"./index-7g4c7s5r.js";
 import {
   init_git_executable,
   resolveGitExecutable
 } from "./index-9e6fdz2h.js";
 import"./index-4rhhvd1a.js";
-import"./index-zpsr8rpc.js";
 import"./index-bk5tah7q.js";
 import"./index-bpmtbmy9.js";
+import"./index-zpsr8rpc.js";
 import"./index-zgwm4ryv.js";
 import"./index-a76rekgs.js";
 

package/dist/cli/{worktree-isolation-4053n0px.js → worktree-isolation-jwxtrh3z.js}

@@ -21,68 +21,69 @@ import {
   sanitizeWorktreeTaskId,
   standardWorktreeByCallID,
   standardWorktreeSerializationSessions
-} from "./index-399nq780.js";
-import"./index-2sqgbmtq.js";
-import"./index-hvk3zs62.js";
-import"./index-gr8ppbq3.js";
-import"./index-8fr2wn18.js";
-import"./index-0g5v4s0x.js";
-import"./index-17yszqs5.js";
+} from "./index-dvhecfa9.js";
+import"./index-d5qf7hvh.js";
+import"./index-m3tx1q9v.js";
+import"./index-4c50tm9j.js";
+import"./index-gk1w1h9k.js";
+import"./index-t9kjxzdr.js";
+import"./index-5bd84nxc.js";
 import"./index-txdagbh7.js";
 import"./index-cw912re7.js";
-import"./index-066xxa4q.js";
-import"./index-13egyjgv.js";
-import"./index-ybcxvv17.js";
+import"./index-qa7t42e7.js";
+import"./index-h92cqbqa.js";
+import"./index-87wqes24.js";
 import"./index-70ha9e09.js";
-import"./index-8hqkrd2j.js";
+import"./index-1aex5zd9.js";
 import"./index-9ss2m4rs.js";
-import"./index-xezfx7ge.js";
+import"./index-3nm1b3t2.js";
 import"./index-zsrtt42s.js";
-import"./index-k5w284js.js";
-import"./index-6chhqq2n.js";
-import"./index-1zqf2pny.js";
+import"./index-hfrb77tj.js";
+import"./index-251vrmge.js";
+import"./index-9wv6a3jx.js";
 import"./index-b43rt5ph.js";
 import"./index-q7sjgr1y.js";
-import"./index-yt25kpvz.js";
-import"./index-fc1dqzjp.js";
-import"./index-w11whwn3.js";
-import"./index-zha9bdj9.js";
-import"./index-bfr392e7.js";
-import"./index-ee6ydtfe.js";
+import"./index-xn16akay.js";
+import"./index-b7ra4hwj.js";
+import"./index-2c7eabkr.js";
+import"./index-tzq6t9wc.js";
+import"./index-sahf5yz3.js";
 import"./index-p612v1mv.js";
-import"./index-6rff2h8x.js";
-import"./index-c20gf089.js";
+import"./index-bwvbj3fp.js";
+import"./index-qww0h314.js";
 import"./index-rtry5xyf.js";
 import {
   resolveWorktreeIsolationConfig
-} from "./index-nph5g4em.js";
+} from "./index-3a2xznmd.js";
 import"./index-3qf1vxtb.js";
 import"./index-n832052r.js";
-import"./index-xwkn5hse.js";
-import"./index-2y4kargd.js";
-import"./index-2v17wb75.js";
-import"./index-79sr3fd1.js";
-import"./index-jx9f4ke1.js";
-import"./index-aftapk6j.js";
+import"./index-ms16gaa4.js";
+import"./index-3f1tr4ha.js";
+import"./index-qd619x3r.js";
+import"./index-75f9jj3h.js";
+import"./index-6d4dc99f.js";
+import"./index-rk10x4zr.js";
 import"./index-ry16d01s.js";
 import"./index-n4fzmqz8.js";
-import"./index-axf65x87.js";
-import"./index-bkd3450m.js";
+import"./index-qd726agw.js";
+import"./index-8cky7ksv.js";
+import"./index-vzm6zre7.js";
 import"./index-ae75rja9.js";
-import"./index-a7rw4g4s.js";
+import"./index-t8tw1bhs.js";
+import"./index-2w0beg3s.js";
+import"./index-m21x1bkx.js";
+import"./index-f6zgz02s.js";
 import"./index-7qefgq4j.js";
-import"./index-edm41q4j.js";
-import"./index-gy0nyfbw.js";
-import"./index-hwj25q9r.js";
+import"./index-ee6ydtfe.js";
 import"./index-7g4c7s5r.js";
-import"./index-52xdezsh.js";
+import"./index-0jpv5z94.js";
 import"./index-9e6fdz2h.js";
 import"./index-4rhhvd1a.js";
-import"./index-wf12wckd.js";
+import"./index-4mgggb8x.js";
 import"./index-0tc0pcmh.js";
-import"./index-zpsr8rpc.js";
 import"./index-bk5tah7q.js";
 import"./index-bpmtbmy9.js";
+import"./index-zpsr8rpc.js";
 import"./index-q1r1cfww.js";
 import"./index-yzjaj53h.js";
 import"./index-zgwm4ryv.js";

package/dist/commands/close.d.ts

@@ -157,6 +157,77 @@ declare function countSessionKnowledgeEntries(entries: CloseKnowledgeEntry[], se
  * Use copyDirRecursiveWithFailures when per-file failure tracking is needed.
  */
 declare function copyDirRecursive(src: string, dest: string): Promise<number>;
+/**
+ * Flat-file artifacts to include in the archive bundle.
+ * Each entry is a relative path under .swarm/.
+ *
+ * plan-ledger.jsonl is included so the archive bundle is a self-contained
+ * forensic snapshot of the session: the ledger holds the full audit trail of
+ * task state transitions and snapshot events that plan.json/plan.md don't
+ * preserve.
+ */
+export declare const ARCHIVE_ARTIFACTS: string[];
+/**
+ * Active-state flat files to clean after archiving so future swarms start clean.
+ *
+ * plan.json, plan.md, and plan-ledger.jsonl are all removed so the next /swarm
+ * session starts with a clean slate. The user's original ask for /swarm close
+ * was to "archive plan files so future swarms aren't confused" — leaving a
+ * terminal-state plan.json in place violates that invariant because the next
+ * session's loadPlan() would pick it up as if it were still active.
+ *
+ * CRITICAL: the ledger must also be removed. Without this, loadPlan()'s Step 4
+ * would see no plan.json but a surviving ledger, call replayFromLedger(), and
+ * materialize the CLOSED plan back into plan.json on the next session. The
+ * ledger is a second backing store for the same "terminal-state plan" and
+ * leaving it behind re-enables the exact bug this cleanup is meant to fix.
+ * The archive-first guard below ensures we only delete files we successfully
+ * copied to the archive bundle, so the audit trail is preserved in the bundle.
+ *
+ * knowledge-rejected.jsonl, repo-graph.json, doc-manifest.json,
+ * dark-matter.md, telemetry.jsonl, and swarm.db are
+ * session-generated artifacts that do not persist meaningfully across sessions —
+ * they are recreated on next session init and must be removed to avoid stale-state
+ * interference.
+ *
+ * The SQLite WAL sidecars swarm.db-shm and swarm.db-wal are deliberately NOT in
+ * either list (the archive-first guard would preserve them anyway): since #2483
+ * they are removed immediately AFTER the swarm.db unlink by
+ * removeSqliteSidecarsAfterClose, deliberately reversing #1692. Post-unlink the
+ * sidecar paths are meaningless for future opens (no new opener can attach),
+ * live processes keep their already-open fds so deleting the PATH cannot
+ * corrupt them, and a Windows open-handle collision yields EBUSY which the
+ * helper skips fail-open.
+ *
+ * Note: knowledge.jsonl is intentionally NOT cleaned because it contains cumulative
+ * project knowledge (lessons learned) that should persist across sessions and finalize
+ * cycles. The archive step still creates a backup for safety.
+ * close-summary.md is NOT cleaned because it is written as the final close output
+ * AFTER the clean stage runs. spec.md IS cleaned: it is single-session state coupled
+ * to the plan lifecycle (the plan it produced is removed above), so leaving it behind
+ * makes the next session pick up a stale spec via readEffectiveSpecSync and mis-route
+ * the architect into CLARIFY-SPEC/overwrite prompts. It is archived first (archive-first
+ * guard), so the forensic copy is preserved in the bundle. The earlier "spec.md may not
+ * exist" rationale was wrong — handoff.md is equally optional and is cleaned the same way.
+ * session-reflection.md is a single-session snapshot (not cumulative like
+ * knowledge.jsonl) so it IS cleaned to maintain the clean-slate invariant.
+ * spec-staleness.json and spec-snapshot.md are the same class of single-session
+ * spec-drift state as spec.md. spec-staleness.json is an existence-only gate
+ * checked unconditionally by enforceSpecDriftGate, which hard-blocks the core
+ * write tools (save_plan, update_task_status, phase_complete,
+ * lean_turbo_run_phase, lean_turbo_acquire_locks) with SPEC_DRIFT_BLOCK — a
+ * survivor would block the NEXT session against drift that no longer applies.
+ * spec-snapshot.md is its companion diff source, feeding the mismatch shown in
+ * the SPEC_DRIFT_BLOCK message. Both are archived first (archive-first guard),
+ * then cleaned so the next session starts drift-free.
+ */
+export declare const ACTIVE_STATE_TO_CLEAN: string[];
+/**
+ * Active-state directories to archive and clean after archiving.
+ * These contain session-generated data that must be removed so future
+ * swarms start clean. Each entry is a relative path under .swarm/.
+ */
+export declare const ACTIVE_STATE_DIRS_TO_CLEAN: string[];
 /**
  * Guarantee all phases and tasks in a plan are marked complete/closed.
  * Mutates planData in place. Returns actual IDs of newly closed phases and
@@ -226,6 +297,16 @@ export declare function runArchiveEvidenceRetention(ctx: ArchiveStageContext): P
  * 375 ms so `/swarm close` remains responsive.
  */
 declare function unlinkActiveStateFileWithRetry(filePath: string): Promise<void>;
+/**
+ * Remove the SQLite WAL sidecars (swarm.db-wal / swarm.db-shm) immediately
+ * after the clean stage unlinks swarm.db (#2483, deliberately reversing the
+ * #1692 preserve decision): once the main db is unlinked the sidecar paths
+ * are meaningless for future opens — no new opener can attach — and live
+ * processes keep their already-open fds, so deleting the PATH cannot corrupt
+ * them. Best-effort and per-file fail-open: ENOENT (already gone) and EBUSY
+ * (Windows open-handle collision) are skipped silently.
+ */
+export declare function removeSqliteSidecarsAfterClose(swarmDir: string): void;
 export declare function runCleanStage(ctx: CloseStageContext): Promise<CleanStageResult>;
 /**
  * STAGE 4: ALIGN
@@ -282,6 +363,7 @@ export declare const _internals: {
     closeRepoMemory: typeof closeRepoMemory;
     unlinkActiveStateFileWithRetry: typeof unlinkActiveStateFileWithRetry;
     unlink: typeof fsSync.promises.unlink;
+    unlinkSidecarSync: typeof fsSync.unlinkSync;
     sleep: typeof sleep;
     collectGarbageBestEffort: typeof collectGarbageBestEffort;
     ACTIVE_STATE_DIRS_TO_CLEAN: string[];

package/dist/config/schema.d.ts

@@ -445,6 +445,11 @@ export declare const SummaryConfigSchema: z.ZodObject<{
     exempt_tools: z.ZodDefault<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 export type SummaryConfig = z.infer<typeof SummaryConfigSchema>;
+export declare const RetentionConfigSchema: z.ZodPrefault<z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    dry_run: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>>;
+export type RetentionConfig = z.infer<typeof RetentionConfigSchema>;
 export declare const ReviewPassesConfigSchema: z.ZodObject<{
     always_security_review: z.ZodDefault<z.ZodBoolean>;
     security_globs: z.ZodDefault<z.ZodArray<z.ZodString>>;
@@ -2218,6 +2223,10 @@ export declare const PluginConfigSchema: z.ZodObject<{
         retention_days: z.ZodDefault<z.ZodNumber>;
         exempt_tools: z.ZodDefault<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
+    retention: z.ZodPrefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        dry_run: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
     review_passes: z.ZodOptional<z.ZodObject<{
         always_security_review: z.ZodDefault<z.ZodBoolean>;
         security_globs: z.ZodDefault<z.ZodArray<z.ZodString>>;

package/dist/context-map/capsule-persistence.d.ts

@@ -29,6 +29,7 @@ export declare const _internals: {
     readonly existsSync: typeof fs.existsSync;
     readonly mkdirSync: typeof fs.mkdirSync;
     readonly readdirSync: typeof fs.readdirSync;
+    readonly statSync: fs.StatSyncFn;
     readonly unlinkSync: typeof fs.unlinkSync;
     readonly renameSync: typeof fs.renameSync;
 };
@@ -50,17 +51,21 @@ export declare function saveCapsule(capsule: ContextCapsule, directory: string):
  */
 export declare function loadCapsule(taskId: string, directory: string): ContextCapsule | null;
 /**
- * Delete a capsule from `.swarm/capsules/{task_id}.json`.
- *
- * Returns `true` if the file was deleted, `false` if it didn't exist.
- * Never throws.
+ * Listing cap for `.swarm/capsules/` enumeration (issue #2483 §2, R12): the
+ * 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 capsule history). The effective value resolves
+ * through `resolveRetentionCap` so the #2483 acceptance checks can shrink it.
  */
-export declare function deleteCapsule(taskId: string, directory: string): boolean;
+export declare const MAX_CAPSULES_LISTED = 500;
 /**
- * List all saved capsule task IDs in `.swarm/capsules/`.
+ * List saved capsule task IDs in `.swarm/capsules/`, newest-first.
  *
  * Returns an array of task IDs derived from filenames (stripping the
- * `.json` extension). Returns an empty array if the directory doesn't
- * exist. Never throws.
+ * `.json` extension), ordered by capsule file mtime descending (code-unit
+ * filename tie-break) and capped at {@link MAX_CAPSULES_LISTED} entries.
+ * A capsule whose file cannot be `stat`-ed sorts oldest (fail-open per
+ * entry). Returns an empty array if the directory doesn't exist. Never
+ * throws.
  */
 export declare function listCapsules(directory: string): string[];

package/dist/evidence/phase-participation.d.ts

@@ -40,5 +40,5 @@ export declare function completeBackgroundPhaseParticipation(input: {
     record: BackgroundDelegationRecord;
     resultText: string;
 }): Promise<boolean>;
-export declare function readPhaseParticipation(directory: string, plan: Plan, phase: number, role: string): ParticipationReadResult;
+export declare function readPhaseParticipation(directory: string, plan: Plan, phase: number, role: string): Promise<ParticipationReadResult>;
 export declare function resetPhaseParticipationForTests(): void;

package/dist/hooks/delegate-ack-collector.d.ts

@@ -39,6 +39,13 @@ export interface DelegateAckOutput {
 }
 /** Best-effort extraction of a task id from a delegation prompt envelope. */
 export declare function resolveDelegateAckTaskId(args: Record<string, unknown>, knownPlanTaskIds?: ReadonlySet<string>, planContextOverLimit?: boolean): string | undefined;
+/**
+ * Global FIFO cap on the unacknowledged-criticals 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_UNACKNOWLEDGED_CRITICALS = 500;
 export interface CollectDelegateAcksResult {
     emitted: Array<{
         id: string;

package/dist/hooks/guardrails/execution-stall.d.ts

@@ -92,7 +92,7 @@
  * escalates to the STOP directive.
  */
 import type { BackgroundWorkspaceSnapshot } from '../../background/pending-delegations.js';
-import { captureWorkspaceSnapshot, changedFilesSinceSnapshot } from '../../background/workspace-snapshot.js';
+import { captureWorkspaceSnapshotAsync, changedFilesSinceSnapshotAsync } from '../../background/workspace-snapshot.js';
 /** Default advisory rung (mirrors `guardrails.execution_stall_warn_calls`). */
 export declare const DEFAULT_EXECUTION_STALL_WARN_CALLS = 30;
 /** Default hard rung (mirrors `guardrails.execution_stall_stop_calls`). */
@@ -251,6 +251,9 @@ export declare function enforceExecutionStallDenial(params: {
  * `tool.execute.after`. Records progress events, arms on a successful
  * `update_task_status(in_progress)`, and runs the periodic workspace probe.
  * NEVER throws.
+ *
+ * Async (issue #2472 W7): the workspace captures route through the async
+ * snapshot twin, so callers (guardrails' `toolAfter`) must await it.
  */
 export declare function recordExecutionStallToolAfter(params: {
     sessionID: string;
@@ -260,18 +263,20 @@ export declare function recordExecutionStallToolAfter(params: {
     output: unknown;
     directory: string;
     options?: ExecutionStallOptions;
-}): void;
+}): Promise<void>;
 /**
  * Test/DI seam (AGENTS.md invariant 7). `now` is the fake-clock seam the
  * idleness-lapse tests drive; the two workspace functions are indirected so a
  * test never spawns git, and `readPlanOpenTaskState` so a test can drive the
  * disarm edge without a plan fixture (the disarm tests exercise the REAL reader
- * against a real `.swarm/plan.json` as well).
+ * against a real `.swarm/plan.json` as well). The capture seam carries the
+ * ASYNC twin (issue #2472 W7) — hook paths must never reach the sync
+ * spawn-based capture.
  */
 export declare const _internals: {
     now: () => number;
-    captureWorkspaceSnapshot: typeof captureWorkspaceSnapshot;
-    changedFilesSinceSnapshot: typeof changedFilesSinceSnapshot;
+    captureWorkspaceSnapshotAsync: typeof captureWorkspaceSnapshotAsync;
+    changedFilesSinceSnapshotAsync: typeof changedFilesSinceSnapshotAsync;
     ensureArchitectSession: typeof ensureArchitectSession;
     readPlanOpenTaskState: typeof readPlanOpenTaskState;
 };

package/dist/hooks/hive-promoter.d.ts

@@ -21,7 +21,7 @@
  * This module is NOT imported on the plugin-init path (invariant 1): promotion
  * runs only on the lazy `/swarm promote`, close, curate, and postmortem paths.
  */
-import { resolveCohortId } from '../knowledge/cohort-identity.js';
+import type { CohortIdentity } from '../knowledge/cohort-identity.js';
 import { authorizeCuration } from '../knowledge/curation-policy.js';
 import { appendCuratorRecommendation, readCuratorSummary } from './curator.js';
 import { transactHiveStore } from './hive-transaction.js';
@@ -65,19 +65,21 @@ export declare function countDistinctProjects(confirmedBy: ProjectConfirmationRe
  * new canonical-cohort confirmations. Returns a summary for curator state.
  *
  * `directory` is required (#1847) to resolve the canonical cohort identity
- * (#1846) for cross-project distinctness.
+ * (#1846) for cross-project distinctness. `sessionID` (#2472 W2) is optional:
+ * when present, cohort resolution reuses the session's cached cohort id (see
+ * the `_internals.resolveCohortId` default).
  *
  * @note The 'hive-fast-track' tag is privileged — it bypasses the 3-phase
  *   confirmation requirement inside the eligibility_route gate. It should only
  *   be set by authorized tooling (inferTags() never produces it automatically).
  */
-export declare function checkHivePromotions(swarmEntries: SwarmKnowledgeEntry[], config: KnowledgeConfig, directory: string): Promise<HivePromotionSummary>;
+export declare function checkHivePromotions(swarmEntries: SwarmKnowledgeEntry[], config: KnowledgeConfig, directory: string, sessionID?: string): Promise<HivePromotionSummary>;
 export declare const _internals: {
     readSwarmEntries: (directory: string) => Promise<SwarmKnowledgeEntry[]>;
     checkHivePromotions: typeof checkHivePromotions;
     readCuratorSummary: typeof readCuratorSummary;
     appendCuratorRecommendation: typeof appendCuratorRecommendation;
-    resolveCohortId: typeof resolveCohortId;
+    resolveCohortId: (directory: string, sessionID?: string) => Promise<CohortIdentity>;
     transactHiveStore: typeof transactHiveStore;
     validateLesson: typeof validateLesson;
     authorizeCuration: typeof authorizeCuration;
@@ -146,10 +148,31 @@ export declare const _internals: {
             synonym_map_max_pairs: number;
         } | undefined;
     };
+    /** #2472 W2 cadence clock (PRR-021 DI seam, invariant 7): the promotion
+     *  cadence floor reads time through this seam so tests can advance the
+     *  60s floor deterministically without real sleeping or raw wall-clock
+     *  polling. Everything else (entry timestamps, audit timestamps) stays on
+     *  `new Date().toISOString()` — only the cadence decision is time-driven
+     *  control flow. */
+    now: () => number;
+    /** Test-only: clears the #2472 W2 hook-gating state (per-directory cadence
+     *  map + curator-migration guard). Production code never calls this; it
+     *  exists so test files sharing one Bun process start from a clean slate. */
+    resetPromoterGatingState: () => void;
 };
 /**
  * Create a hook that promotes swarm entries to the hive.
- * The hook fires unconditionally - the caller decides when to invoke it.
+ *
+ * #2472 W2 gating — the hook self-gates instead of running unconditionally:
+ *  1. Write-class tools only (`PROMOTER_WRITE_TOOL_NAMES`): a read-only tool
+ *     call returns before even the swarm-store read.
+ *  2. Empty-candidates gate: when no swarm entry has ACTIVE status the hook
+ *     returns BEFORE cohort resolution, evidence loading, the hive
+ *     transaction, and the curator-summary read. The one-time legacy
+ *     curator-summary migration read stays reachable — at most once per
+ *     directory per process (critic Round 2 item 1).
+ *  3. Cadence floor: a second qualifying invocation inside
+ *     `PROMOTION_CADENCE_FLOOR_MS` returns before the promotion body.
  */
 export declare function createHivePromoterHook(directory: string, config: KnowledgeConfig): (input: unknown, output: unknown) => Promise<void>;
 /** Options for manual promotion (override semantics, #1847 §4). */

package/dist/hooks/knowledge-store.d.ts

@@ -29,6 +29,13 @@ export interface KnowledgeRetractionRecord {
     matched_swarm_ids: string[];
     matched_hive_ids: string[];
 }
+/**
+ * Global FIFO cap on the retraction audit stream (issue #2483 §2). Enforcement
+ * resolves the effective value through {@link resolveRetentionCap} so the
+ * #2483 acceptance checks can shrink the cap below this default and prove the
+ * writer clamps.
+ */
+export declare const MAX_RETRACTION_RECORDS = 500;
 export declare function readRetractionRecords(directory: string): Promise<KnowledgeRetractionRecord[]>;
 export declare function appendRetractionRecord(directory: string, record: KnowledgeRetractionRecord): Promise<void>;
 /**

package/dist/hooks/repo-graph-builder.d.ts

@@ -14,6 +14,14 @@
  * the async builder, yields to the event loop before doing any work, and
  * exposes the init promise so `toolAfter` can serialize incremental
  * updates after the initial scan completes.
+ *
+ * Issue #2472 (REPOGRAPH-1): `toolAfter` runs its entire cheap synchronous
+ * filter chain (enabled flag, write-tool membership, path extraction and
+ * validation, exclude-dir scoping) BEFORE awaiting the init promise, so a
+ * non-write tool call settles immediately even while the startup scan is
+ * pending — only write tools that will actually mutate the graph wait for
+ * the scan. The startup scan itself is bounded by an overall wall-clock
+ * budget (STARTUP_SCAN_BUDGET_MS) that resolves fail-open on timeout.
  */
 import { type BuildWorkspaceGraphOptions, type RepoGraph } from '../tools/repo-graph';
 import { type FreshnessOptions, type FreshnessProbe } from '../tools/repo-graph/freshness';
@@ -51,6 +59,12 @@ export interface RepoGraphBuilderOptions {
     maxFiles?: number;
     walkBudgetMs?: number;
     excludeDirs?: readonly string[];
+    /**
+     * Overall wall-clock budget (ms) for the startup scan (issue #2472).
+     * Defaults to STARTUP_SCAN_BUDGET_MS. Additive DI/test knob so the
+     * fail-open timeout path can be exercised without waiting 30 s.
+     */
+    scanBudgetMs?: number;
 }
 /**
  * Rebase a realpath'd file onto the lexical workspace root so the incremental

package/dist/hooks/review-receipt.d.ts

@@ -224,6 +224,25 @@ export declare function persistReviewReceipt(directory: string, receipt: ReviewR
  * orphan file, never a dangling index entry that points at missing evidence.
  */
 export declare function removeReviewReceipt(directory: string, receiptPath: string, receiptId: string): Promise<void>;
+export interface PruneDanglingReceiptIndexEntriesOptions {
+    /** Count dangling entries without rewriting the index (sweep dry-run). */
+    dryRun?: boolean;
+}
+/**
+ * Drop index entries whose receipt file no longer exists (issue #2483).
+ *
+ * The retention sweep prunes receipt FILES by age/count; without this pass
+ * the manifest keeps naming pruned evidence forever. Entries whose
+ * `filename` is not a bare basename (the poisoned-entry class the read path
+ * already refuses) count as dangling and are dropped with the rest.
+ *
+ * The rewrite is atomic (temp+rename via {@link writeReceiptIndex}) under
+ * the same `_indexLockChain` as appends, so an interleaved append is never
+ * lost. Returns the number of entries dropped (or, with `dryRun`, the
+ * number that WOULD be dropped). A missing/unparseable index, or a receipts
+ * directory that does not exist, is a 0 — this helper never creates state.
+ */
+export declare function pruneDanglingReceiptIndexEntries(directory: string, options?: PruneDanglingReceiptIndexEntriesOptions): Promise<number>;
 /**
  * Atomically attach independent finding-validation results to an existing
  * receipt. The receipt identity and index entry remain unchanged.
@@ -238,9 +257,18 @@ export declare function readReceiptById(directory: string, receiptId: string): P
  * Useful for drift verification to find prior reviews of the same scope.
  */
 export declare function readReceiptsByScopeHash(directory: string, scopeHash: string): Promise<ReviewReceipt[]>;
+/**
+ * Read cap for the receipts index reader (issue #2483 §2, R12): the index is
+ * append-ordered (newest last), so bounding the read to the LAST
+ * {@link MAX_RECEIPTS_READ} entries keeps every read O(cap) while still
+ * returning the newest receipts. The effective value resolves through
+ * `resolveRetentionCap` so the #2483 acceptance checks can shrink it.
+ */
+export declare const MAX_RECEIPTS_READ = 1000;
 /**
  * Read all receipts from the index (all verdicts, latest first).
- * Useful for drift verification context.
+ * Useful for drift verification context. Bounded to the newest
+ * {@link MAX_RECEIPTS_READ} index entries (see the constant's docblock).
  */
 export declare function readAllReceipts(directory: string): Promise<ReviewReceipt[]>;
 /**

package/dist/hooks/system-enhancer.d.ts

@@ -40,6 +40,27 @@ declare function maybeAppendSpecDriftAdvisory(output: {
  * Returns null if no valid retrospective found.
  */
 export declare function buildRetroInjection(directory: string, currentPhaseNumber: number, currentPlanTitle?: string): Promise<string | null>;
+/**
+ * #2472 W4 (PR #2588 bot finding 7): dispose fence for a project root's
+ * deferred maintenance scans. Called best-effort from the plugin's
+ * `dispose` so a scheduled-but-not-yet-fired (or in-flight) doc-index /
+ * dark-matter background task cannot fire into — or keep writing `.swarm`
+ * artifacts for — a project whose plugin instance is being torn down.
+ *
+ *  (i)  Future scheduling for `directory` is suppressed: the resolved root
+ *       is added to `cancelledDeferredScanDirs`, and
+ *       `scheduleDeferredMaintenanceScans` is a no-op for cancelled roots.
+ *  (ii) Any already-scheduled or in-flight task for `directory` aborts:
+ *       the root's deferred-scan generation is bumped, and every task
+ *       captured the pre-bump value and re-checks it before its first
+ *       statement and before each major scan step, so even a long-running
+ *       dark-matter git scan stops before its next write.
+ *
+ * A NEW system-enhancer instance created for the same directory (plugin
+ * re-init — the restart-safe lifecycle of issue #2472) removes the
+ * cancellation marker, so fresh instances schedule scans normally again.
+ */
+export declare function cancelDeferredMaintenanceScans(directory: string): void;
 /**
  * Creates the experimental.chat.system.transform hook for system enhancement.
  */