opencode-swarm 7.168.1 → 7.169.0

package/dist/memory/embeddings/reranker.d.ts

@@ -3,6 +3,16 @@ export interface RerankCandidate {
     text: string;
     score?: number;
 }
+/**
+ * The narrow reranking contract used by the SQLite retrieval pipeline.
+ * Keeping this structural makes deterministic, offline evaluation possible
+ * without making the optional transformers dependency part of the evaluator.
+ */
+export interface MemoryReranker {
+    readonly available: boolean;
+    readonly modelVersion?: string;
+    rerank<T extends RerankCandidate>(candidates: T[], query?: string, topN?: number): Promise<T[]>;
+}
 /**
  * Latency gate: skip reranking when the previous recall step already
  * exceeded the caller's latency budget.
@@ -18,8 +28,9 @@ export declare function shouldRerank(previousRecallElapsedMs: number, latencyBud
  * Graceful degradation: if the package is missing or the model fails to
  * load, `available` is false and rerank() returns candidates unchanged.
  */
-export declare class CrossEncoderReranker {
+export declare class CrossEncoderReranker implements MemoryReranker {
     private readonly options;
+    readonly modelVersion: string;
     private loadFailed;
     private _available;
     private pipeline;
@@ -38,5 +49,5 @@ export declare class CrossEncoderReranker {
      * Returns the top `topN` candidates sorted descending by cross-encoder
      * score. If the model is unavailable, returns candidates unchanged.
      */
-    rerank(candidates: RerankCandidate[], query: string, topN?: number): Promise<RerankCandidate[]>;
+    rerank<T extends RerankCandidate>(candidates: T[], query?: string, topN?: number): Promise<T[]>;
 }

package/dist/memory/evaluation.d.ts

@@ -1,10 +1,88 @@
+import { type SQLiteRetrievalDependencies } from './sqlite-provider';
 import type { MemoryKind, MemoryRecord, MemoryScopeRef, MemorySource, RecallMode } from './types';
 export type RecallEvaluationProviderName = 'local-jsonl' | 'sqlite';
 export type RecallEvaluationMode = Extract<RecallMode, 'manual' | 'injection' | 'curator'>;
+export type RecallEvaluationProfile = 'lexical' | 'hybrid' | 'hybrid+rerank';
+export interface RecallEvaluationResourceCaps {
+    candidate_count: number;
+    token_budget: number;
+}
+export interface RecallEvaluationResourceUsage {
+    lexical_candidate_count: number;
+    dense_candidate_count: number;
+    rerank_candidate_count: number;
+    returned_count: number;
+    query_embedding_invocation_count: number;
+    /** Text-only estimate over actual returned records; prompt consumption is not measured here. */
+    returned_token_estimate: number;
+}
+export interface RecallEvaluationManifest {
+    version: '1.0.0';
+    source_id: string;
+    model_id: string;
+    provider_id: string;
+    config_hash: string;
+    corpus_hash: string;
+    profile_thresholds: Record<string, number>;
+    sample_counts: Record<string, number>;
+    metric_definitions: Record<string, string>;
+    uncertainty: {
+        method: string;
+        confidence: number;
+        sample_count: number;
+    };
+    variants?: Record<string, RecallEvaluationIdentity>;
+}
+export interface RecallEvaluationIdentity {
+    source_id: string;
+    model_id: string;
+    provider_id: string;
+    config_hash: string;
+}
+export interface RecallEvaluationScenario {
+    id: string;
+    language: string;
+    analyzer_id?: string;
+    source_provenance: 'direct-source';
+    /** Graph extraction/index querying is deliberately not claimed by memory recall. */
+    index_state: 'not-measured';
+    graph_measurement: {
+        status: 'unmeasured';
+        reason: string;
+    };
+    expected_symbols: string[];
+    expected_edges: Array<string | {
+        from: string;
+        to: string;
+    }>;
+    known_misses: string[];
+    spurious_edges: Array<string | {
+        from: string;
+        to: string;
+    }>;
+}
+export interface RecallEvaluationComparison {
+    fixture: string;
+    provider: RecallEvaluationProviderName;
+    mode: RecallEvaluationMode;
+    baseline_profile: RecallEvaluationProfile;
+    variant_profile: RecallEvaluationProfile;
+    precision_at_k_delta: number;
+    recall_at_k_delta: number;
+    latency_ms_delta: number;
+    cost_delta: null;
+    cost_comparison: 'unavailable';
+}
 export interface RecallEvaluationOptions {
     fixtureDirectory: string;
     providers?: RecallEvaluationProviderName[];
     modes?: RecallEvaluationMode[];
+    /** Omitted preserves the legacy provider × mode report. */
+    profiles?: RecallEvaluationProfile[];
+    /** Instance-owned offline dependencies; never used by normal agent recall. */
+    dependencies?: SQLiteRetrievalDependencies;
+    resourceCaps?: Partial<RecallEvaluationResourceCaps>;
+    heldoutCorpusDirectory?: string;
     keepTempRoots?: boolean;
 }
 export interface RecallEvaluationMetrics {
@@ -28,6 +106,20 @@ export interface RecallEvaluationRun {
     retrieved_ids: string[];
     metrics: RecallEvaluationMetrics;
     passed: boolean;
+    profile?: RecallEvaluationProfile;
+    status?: 'complete' | 'degraded' | 'skipped';
+    degradation_reason?: string;
+    provenance?: string;
+    resource_cap?: RecallEvaluationResourceCaps;
+    resource_usage?: RecallEvaluationResourceUsage;
+    latency_ms?: number;
+    cost_provenance?: string;
+    cost?: {
+        provenance: string;
+        amount: null;
+    };
+    identity?: RecallEvaluationIdentity;
+    scenario?: RecallEvaluationScenario;
 }
 export interface RecallEvaluationReport {
     schema_version: 1;
@@ -41,6 +133,9 @@ export interface RecallEvaluationReport {
         passed_run_count: number;
     };
     runs: RecallEvaluationRun[];
+    comparisons: RecallEvaluationComparison[];
+    /** Additive contract metadata; schema_version stays v1 for legacy callers. */
+    manifest: RecallEvaluationManifest;
 }
 type FixtureRecordState = {
     deleted?: boolean;
@@ -71,7 +166,11 @@ interface RecallEvaluationFixture {
     k?: number;
     expectedLabels: string[];
     records: FixtureRecord[];
+    scenario?: RecallEvaluationScenario;
+    sourceHash?: string;
 }
 export declare function evaluateMemoryRecallFixtures(options: RecallEvaluationOptions): Promise<RecallEvaluationReport>;
 export declare function loadRecallEvaluationFixtures(fixtureDirectory: string): Promise<RecallEvaluationFixture[]>;
+/** Strict, filesystem-independent report metadata validation. */
+export declare function validateRecallEvaluationManifest(value: unknown): asserts value is RecallEvaluationManifest;
 export {};

package/dist/memory/heldout-evaluation-corpus.d.ts

@@ -0,0 +1,51 @@
+export declare const MAX_HELDOUT_MANIFEST_BYTES: number;
+export interface HeldoutRecallCorpusCase {
+    id?: string;
+    language: string;
+    expected_symbols: string[];
+    expected_edges: Array<string | {
+        from: string;
+        to: string;
+    }>;
+    known_misses: string[];
+    spurious_edges: Array<string | {
+        from: string;
+        to: string;
+    }>;
+    paraphrase: string;
+    source_path?: string;
+    content_hash?: string;
+    analyzer_id?: string;
+}
+export interface HeldoutRecallCorpusManifest {
+    corpus_id: string;
+    split: 'heldout';
+    version?: string;
+    thresholds?: Record<string, number>;
+    cases: HeldoutRecallCorpusCase[];
+}
+export interface LoadedHeldoutRecallScenario extends HeldoutRecallCorpusCase {
+    id: string;
+    source_text: string;
+    source_hash: string;
+    source_provenance: 'direct-source';
+}
+/**
+ * Validate the data contract only. Filesystem membership, safe paths, byte
+ * caps, and source hashes are intentionally enforced by the loader below.
+ */
+export declare function validateHeldoutRecallCorpusManifest(value: unknown): asserts value is HeldoutRecallCorpusManifest;
+/**
+ * Bounded filesystem boundary for held-out corpora. It does not recurse, and
+ * every optional source file must remain inside the supplied corpus root.
+ */
+export declare function loadHeldoutRecallEvaluationCorpus(corpusDirectory: string): Promise<HeldoutRecallCorpusManifest>;
+/**
+ * Bounded direct-source scenarios for production retrieval evaluation. This
+ * loader validates corpus membership and content hashes; it never scores or
+ * manufactures analyzer results.
+ */
+export declare function loadHeldoutRecallEvaluationScenarios(corpusDirectory: string): Promise<{
+    manifest: HeldoutRecallCorpusManifest;
+    scenarios: LoadedHeldoutRecallScenario[];
+}>;

package/dist/memory/index.d.ts

@@ -1,9 +1,11 @@
 export type { MemoryConfig } from './config';
 export { DEFAULT_MEMORY_CONFIG, resolveMemoryConfig } from './config';
+export type { MemoryReranker, RerankCandidate } from './embeddings/reranker';
 export { MemoryDisabledError, MemoryPiiDetectorError, MemoryValidationError, } from './errors';
-export { evaluateMemoryRecallFixtures, loadRecallEvaluationFixtures, type RecallEvaluationMetrics, type RecallEvaluationMode, type RecallEvaluationOptions, type RecallEvaluationProviderName, type RecallEvaluationReport, type RecallEvaluationRun, } from './evaluation';
+export { evaluateMemoryRecallFixtures, loadRecallEvaluationFixtures, type RecallEvaluationComparison, type RecallEvaluationIdentity, type RecallEvaluationManifest, type RecallEvaluationMetrics, type RecallEvaluationMode, type RecallEvaluationOptions, type RecallEvaluationProfile, type RecallEvaluationProviderName, type RecallEvaluationReport, type RecallEvaluationResourceCaps, type RecallEvaluationResourceUsage, type RecallEvaluationRun, type RecallEvaluationScenario, validateRecallEvaluationManifest, } from './evaluation';
 export type { MemoryGatewayOptions, ProposeMemoryInput, RecallMemoryInput, RecordMemoryOutcomeInput, } from './gateway';
 export { createConfiguredMemoryProvider, createConfiguredMemoryProviderForRoot, createMemoryGateway, MemoryGateway, } from './gateway';
+export { type HeldoutRecallCorpusCase, type HeldoutRecallCorpusManifest, type LoadedHeldoutRecallScenario, loadHeldoutRecallEvaluationCorpus, loadHeldoutRecallEvaluationScenarios, validateHeldoutRecallCorpusManifest, } from './heldout-evaluation-corpus';
 export { createMemoryLifecycleHooks, type MemoryLifecycleHookOptions, type MemoryLifecycleHooks, } from './injector';
 export { backupLegacyJsonl, getLegacyJsonlFileStatus, getLegacyOutcomeJsonlSignature, type JsonlBackupResult, type JsonlImportPayload, type JsonlInvalidRow, type JsonlMigrationReport, LEGACY_JSONL_MIGRATION_NAME, LEGACY_JSONL_MIGRATION_VERSION, LEGACY_JSONL_OUTCOME_META_KEY, readLegacyJsonl, readMigrationReport, resolveMemoryStorageDir, resolveSqliteDatabasePath, writeJsonlExport, writeMigrationReport, } from './jsonl-migration';
 export { LocalJsonlMemoryProvider } from './local-jsonl-provider';
@@ -19,6 +21,7 @@ export { readDeadAnchorMemoryIds, readReflectionDigest, recordOutcomeWithReflect
 export { MEMORY_RECALL_PROFILES, type MemoryRecallProfile, normalizeMemoryAgentRole, resolveMemoryRecallProfile, } from './role-profiles';
 export { appendMemoryRunLog, sanitizeRunId } from './run-log';
 export { computeMemoryContentHash, createBundleId, createMemoryId, createProposalId, isExpired, MemoryAnchorSchema, normalizeMemoryAnchorFile, normalizeMemoryText, validateCuratorMemoryDecision, validateMemoryProposal, validateMemoryRecordRules, } from './schema';
+export type { MemoryRecallQualityTrace, SQLiteRetrievalDependencies, } from './sqlite-provider';
 export { EVENT_CHAIN_GENESIS, MEMORY_EVENTS_CHAIN_HEAD_KEY, type MemoryAuditVerificationReport, type MemoryEventRow, memoryEventRowHash, SQLiteMemoryProvider, verifyMemoryEventChainRows, } from './sqlite-provider';
 export { isCohortRoot, isLocalRoot, resolveVettedMemoryRoot, rootStoragePath, type VettedMemoryRoot, wrapLocalRoot, } from './storage-root';
-export type { AppliedMemoryChange, CuratorMemoryDecision, MemoryAnchor, MemoryContext, MemoryKind, MemoryListFilter, MemoryOutcome, MemoryPatch, MemoryProposal, MemoryRecord, MemoryRelation, MemoryScopeRef, MemoryScopeType, NewMemoryRecord, RecallBundle, RecallInjectionSkipReason, RecallMode, RecallRequest, RecallResultItem, ResolvedCuratorMemoryDecision, } from './types';
+export type { AppliedMemoryChange, CuratorMemoryDecision, MemoryAnchor, MemoryContext, MemoryKind, MemoryListFilter, MemoryOutcome, MemoryPatch, MemoryProposal, MemoryRecord, MemoryRelation, MemoryScopeRef, MemoryScopeType, NewMemoryRecord, RecallBundle, RecallInjectionSkipReason, RecallMode, RecallQualityProfile, RecallRequest, RecallResultItem, ResolvedCuratorMemoryDecision, } from './types';

package/dist/memory/sqlite-provider.d.ts

@@ -1,4 +1,6 @@
 import { type MemoryConfig } from './config';
+import { type MemoryReranker } from './embeddings/reranker';
+import type { EmbeddingProvider } from './embeddings/types';
 import { type JsonlMigrationReport } from './jsonl-migration';
 import { type MemoryOutcomeEvent } from './outcome-events';
 import type { MemoryCompactOptions, MemoryCompactResult, MemoryProposalStore, MemoryProvider, MemoryRecallUsageEvent, MemoryRecallUsageFilter, MemoryRewardEvent, MemoryRewardEventFilter, MemoryTransaction } from './provider';
@@ -55,6 +57,7 @@ interface Migration {
     name: string;
     sql: string;
 }
+declare function capQualityRecallItemsByTokenBudget(items: readonly RecallResultItem[], tokenBudget: number): RecallResultItem[];
 export declare const MIGRATIONS: Migration[];
 export interface SQLiteJsonlImportResult {
     importedMemories: number;
@@ -63,6 +66,33 @@ export interface SQLiteJsonlImportResult {
     invalidRows: JsonlMigrationReport['invalidRows'];
     totalRows: number;
 }
+export interface SQLiteRetrievalDependencies {
+    /** Optional deterministic override used by quality evaluation and focused tests. */
+    embeddingProvider?: EmbeddingProvider;
+    /** Selects dense candidates without claiming sqlite-vec availability. */
+    denseSelector?: (request: RecallRequest, queryEmbedding: Float32Array, records: readonly MemoryRecord[]) => Promise<MemoryRecord[]>;
+    reranker?: MemoryReranker;
+    /** Monotonic clock seam; default is Date.now. */
+    now?: () => number;
+}
+export interface MemoryRecallQualityTrace {
+    profile: 'lexical' | 'hybrid' | 'hybrid+rerank';
+    status: 'complete' | 'degraded' | 'skipped';
+    degradationReason?: string;
+    provenance: 'lexical' | 'sqlite-vec' | 'injected-dense';
+    usedEmbedding: boolean;
+    usedReranker: boolean;
+    latencyMs: number;
+    resourceUsage: {
+        lexical_candidate_count: number;
+        dense_candidate_count: number;
+        rerank_candidate_count: number;
+        returned_count: number;
+        query_embedding_invocation_count: number;
+        /** Deterministic estimate over the text actually returned, not a budget echo. */
+        returned_token_estimate: number;
+    };
+}
 export declare class SQLiteMemoryProvider implements MemoryProvider, MemoryProposalStore {
     readonly name = "sqlite";
     private readonly rootDirectory;
@@ -83,6 +113,7 @@ export declare class SQLiteMemoryProvider implements MemoryProvider, MemoryPropo
     private embeddingProvider;
     private embeddingCache;
     private reranker;
+    private readonly retrievalDependencies;
     private memories;
     private proposals;
     private lastAutomaticJsonlMigration;
@@ -97,7 +128,7 @@ export declare class SQLiteMemoryProvider implements MemoryProvider, MemoryPropo
      * `.swarm` path with full `validateSwarmPath` enforcement (today's
      * behavior).
      */
-    vettedCohortRoot?: string | null);
+    vettedCohortRoot?: string | null, retrievalDependencies?: SQLiteRetrievalDependencies);
     /**
      * #1850 (critic GAP-5): explicit cohort-root path branch.
      * - cohort root → `<cohortRoot>/memory.db` (NO validateSwarmPath — the
@@ -122,6 +153,7 @@ export declare class SQLiteMemoryProvider implements MemoryProvider, MemoryPropo
     recallWithDiagnostics(request: RecallRequest): Promise<{
         items: RecallResultItem[];
         diagnostics: RecallScoringDiagnostics;
+        qualityTrace?: MemoryRecallQualityTrace;
     }>;
     private expandRelated;
     recordRecallUsage(event: MemoryRecallUsageEvent): Promise<void>;
@@ -179,6 +211,7 @@ export declare class SQLiteMemoryProvider implements MemoryProvider, MemoryPropo
     private selectRecallCandidates;
     private getStoredModelVersion;
     private selectDenseCandidates;
+    private now;
     private runMigrations;
     private backfillScopeKeys;
     private backfillRecallRunIds;
@@ -292,5 +325,6 @@ export declare const _test_exports: {
     extractFtsTerms: typeof extractFtsTerms;
     FTS_SCHEMA_MIGRATION_NAME: string;
     FTS_SCHEMA_MIGRATION_VERSION: number;
+    capQualityRecallItemsByTokenBudget: typeof capQualityRecallItemsByTokenBudget;
 };
 export {};

package/dist/memory/types.d.ts

@@ -195,6 +195,8 @@ export interface AppliedMemoryChange {
 }
 export type RecallMode = 'manual' | 'injection' | 'curator' | 'evaluation';
 export type RecallInjectionSkipReason = 'disabled' | 'no_signal' | 'below_threshold' | 'no_results';
+/** Explicit, evaluator-only opt-in. Normal agent recall never requests it. */
+export type RecallQualityProfile = 'lexical' | 'hybrid' | 'hybrid+rerank';
 export interface RecallRequest {
     query: string;
     task?: string;
@@ -214,6 +216,18 @@ export interface RecallRequest {
      * suppression never deletes or tombstones the underlying record.
      */
     includeLowQ?: boolean;
+    /**
+     * Produces bounded retrieval-quality telemetry on `recallWithDiagnostics`.
+     * This is intentionally opt-in so agent-facing recall output stays unchanged.
+     */
+    quality?: {
+        profile: RecallQualityProfile;
+        /**
+         * Bounded evaluator-only retrieval work cap. Omitted for normal agent
+         * recall, which preserves the established provider candidate behavior.
+         */
+        candidateCap?: number;
+    };
 }
 export interface RecallResultItem {
     record: MemoryRecord;

package/dist/observability/otel-mapping.d.ts

@@ -1,11 +1,11 @@
 /**
  * External-convention attribute mappings (issue #2029 item 6).
  *
- * These are INERT LOOKUP TABLES. There is no OpenTelemetry SDK dependency, no
- * exporter, and no runtime consumer in this change: the tables are consumed as
- * data by the static contract check (which asserts every catalog entry records a
- * mapping decision) and by `docs/observability-event-contract.md`. The runtime
- * consumer lands in #2049.
+ * These tables are DATA consumed by the static contract check (which asserts
+ * every catalog entry records a mapping decision), by
+ * `docs/observability-event-contract.md`, and — since issue #2485 — by the
+ * opt-in runtime exporter (`src/observability/otlp-exporter.ts`), the runtime
+ * consumer originally deferred here to #2049.
  *
  * Import rules: no filesystem, network, subprocess, or OTel SDK.
  */

package/dist/observability/otlp-exporter.d.ts

@@ -0,0 +1,80 @@
+import type { ObservabilityEvent } from './envelope.js';
+/** Spool home, relative to the project root (retention-registry row `otlp-export-spool`). */
+export declare const OTLP_EXPORT_SPOOL_DIR = ".swarm/otlp-export";
+/** Bounded iteration ceiling for one flush cycle (drain-all semantics). */
+export declare const MAX_FLUSH_ITERATIONS = 100;
+export interface OtlpExportConfig {
+    enabled: boolean;
+    endpoint: string;
+    convention: 'genai' | 'openinference';
+    headers?: Record<string, string>;
+    batchSize: number;
+    flushIntervalMs: number;
+    requestTimeoutMs: number;
+    spoolMaxBytes: number;
+    spoolMaxAgeMs: number;
+    maxRetries: number;
+    backoffBaseMs: number;
+    backoffMaxMs: number;
+    circuitThreshold: number;
+    circuitCooldownMs: number;
+}
+export type OtlpExporterState = 'disabled' | 'active' | 'cooldown';
+export interface OtlpExporterHealth {
+    state: OtlpExporterState;
+    convention: 'genai' | 'openinference' | null;
+    mappingVersion: string | null;
+    spoolRecords: number;
+    spoolBytes: number;
+    accepted: number;
+    exported: number;
+    retried: number;
+    dropped: Record<string, number>;
+    lastErrorCategory: string | null;
+    lastErrorAt: string | null;
+    lastSuccessAt: string | null;
+    circuitOpen: boolean;
+}
+/**
+ * Project a canonical event onto the pinned attribute table for `convention`
+ * plus the closed `swarm.*` extension set. PURE: no I/O, no clock, no throw.
+ * `legacy.raw` is read ONLY at the exact mapped keys with typeof guards —
+ * never traversed or serialized (it may be circular; envelope.ts documents
+ * the alias contract).
+ */
+export declare function projectOtlpAttributes(event: ObservabilityEvent, convention: 'genai' | 'openinference'): Record<string, string | number | boolean>;
+/**
+ * Build one OTLP/HTTP-JSON span for the event, or `null` when the event must
+ * not be exported at all (`content` privacy class).
+ */
+export declare function buildOtlpSpan(event: ObservabilityEvent, convention: 'genai' | 'openinference'): Record<string, unknown> | null;
+/** Minimal fetch shape used by the transport (Bun's fetch adds `preconnect`). */
+export type OtlpFetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+/** DI seam (repo convention): tests inject a stub collector fetch. */
+export declare const _internals: {
+    fetch: OtlpFetch;
+    sleep: (ms: number) => Promise<void>;
+    now: () => number;
+};
+/** Drain ALL pending batches now (bounded by MAX_FLUSH_ITERATIONS). */
+export declare function flushOtlpExporterForTesting(directory: string): Promise<void>;
+/**
+ * Register the OTLP exporter for this project root. O(1), idempotent, never
+ * throws — safe on the plugin init path (invariant 1). All flush/listener
+ * I/O is post-resolution; the ONE init-path exception is a small
+ * (state.json-sized) synchronous read performed only when the exporter is
+ * enabled — fail-open and far inside the invariant's latency budget. When
+ * disabled (default), the kill switch is set, or the endpoint violates
+ * policy, NOTHING is registered and no `.swarm/otlp-export/` directory is
+ * created.
+ */
+export declare function registerOtlpExporter(directory: string, config: OtlpExportConfig): void;
+export declare function isOtlpExporterActive(): boolean;
+/**
+ * Drop the listener and forget in-memory state. Records already appended to
+ * the spool are ON DISK (appends are synchronous), so nothing in-flight is
+ * lost; counters are persisted before clearing so health survives rebind.
+ */
+export declare function resetOtlpExporterForTesting(): void;
+/** Merged health for `/swarm report`. Null when the exporter never ran here. */
+export declare function readOtlpExporterHealth(directory: string): OtlpExporterHealth | null;

package/dist/parallel/lane-owners.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Issue #2527 (PARALLEL-3): durable live-lane owner records.
+ *
+ * Every cross-process liveness signal that existed before this module
+ * expired after five minutes regardless of the lane's actual state: lane
+ * lock metas are stamped once (`file-locks.ts` LOCK_TIMEOUT_MS) with no
+ * renewal path, and provisioning owners are leased for five minutes and
+ * then dropped by init orphan recovery. A lane that legitimately ran longer
+ * became invisible to a second process and was reclaimed as an "orphan".
+ *
+ * This store gives a lane a durable owner signal whose lifetime is the
+ * LANE's, not a lock TTL:
+ *
+ *  - recorded at lane provisioning (lean runner AND standard worktree
+ *    isolation — one primitive for both lane types, F3/A3);
+ *  - cleared when the worktree is removed (`removeWorktree` in
+ *    `src/worktree/core.ts`, both success returns) and by GC-on-read for
+ *    any record whose lane path no longer exists (crashes, manual removal,
+ *    every non-git deletion path);
+ *  - liveness = owning PID exists AND the record's `startedAt` is within a
+ *    24-hour claim window. The window bounds PID-reuse blindness: a record
+ *    older than 24h is stale regardless of what now lives at that PID
+ *    (dispatch deadlines are minutes, so a genuinely-running lane never
+ *    approaches it; a >24h CLEAN lane being reclaimed is the low-harm case
+ *    — a >24h DIRTY lane still survives via git's own refusal, F2).
+ *    `process.kill(pid, 0)` EPERM ⇒ alive (fail-closed on Windows ACLs).
+ *
+ * Store pattern mirrors `dead-lane-reclaim.ts`: a bounded JSON file under
+ * `.swarm/`, written via `atomicWriteSwarmFileSync`, never grown past the
+ * entry/byte caps.
+ */
+import * as fs from 'node:fs';
+import { atomicWriteSwarmFileSync } from '../utils/atomic-write';
+/** Plan-critic round-1 item 5: PID-recency witness bound (24h). */
+export declare const LIVE_LANE_OWNER_CLAIM_WINDOW_MS: number;
+export interface LiveLaneOwnerEntry {
+    lanePath: string;
+    branchName: string;
+    sessionId: string;
+    taskId: string;
+    ownerPid: number;
+    startedAt: number;
+}
+export interface LiveLaneOwnersView {
+    /** Records whose owner process is alive within the claim window. */
+    live: LiveLaneOwnerEntry[];
+    /** Records dropped this read: path gone, or past the claim window. */
+    reaped: LiveLaneOwnerEntry[];
+}
+export declare const _internals: {
+    readFileSync: (p: string, enc: BufferEncoding) => string;
+    rmSync: typeof fs.rmSync;
+    statSync: (p: string) => unknown;
+    atomicWriteSwarmFileSync: typeof atomicWriteSwarmFileSync;
+    now: () => number;
+    kill: (pid: number, signal: 0) => true;
+    process: {
+        pid: number;
+    };
+};
+/** Record (or refresh) the durable owner of a live lane. Never throws. */
+export declare function recordLiveLaneOwner(directory: string, entry: {
+    lanePath: string;
+    branchName: string;
+    sessionId: string;
+    taskId: string;
+}): void;
+/** Clear the durable owner record for one lane path. Never throws. */
+export declare function clearLiveLaneOwner(directory: string, lanePath: string): void;
+/**
+ * Read the live-lane-owner view, GC-ing records whose lane path no longer
+ * exists (universal clear fallback: every removal path that bypassed
+ * `removeWorktree` — manual rm, /swarm close sweeps, future tooling — is
+ * healed on the next read) and records past the 24h claim window.
+ */
+export declare function listLiveLaneOwners(directory: string): LiveLaneOwnersView;

package/dist/tools/repo-graph/query.d.ts

@@ -1,6 +1,11 @@
 import type { FreshnessProbe } from './freshness';
-import type { BlastRadiusResult, CallerReference, ContextPackResult, ContextPackSourceMode, DeadExportsResult, FileOntology, FileReference, GraphHealthResult, GraphNode, LocalizationBlock, PackageBoundarySummary, RepoGraph, SymbolReference } from './types';
+import type { BlastRadiusResult, CallerReference, ContextPackResult, ContextPackSourceMode, DeadExportsResult, FileOntology, FileReference, GraphHealthResult, GraphNode, LocalizationBlock, PackageBoundarySummary, RepoGraph, SymbolEdge, SymbolReference } from './types';
+export interface SymbolEdgeIndexes {
+    forward: Map<string, SymbolEdge[]>;
+    reverse: Map<string, SymbolEdge[]>;
+}
 export declare function getGraphNode(graph: RepoGraph, input: string): GraphNode | undefined;
+export declare function getSymbolEdgeIndexes(graph: RepoGraph): SymbolEdgeIndexes;
 /**
  * Drop every cached query index. Required after any in-place mutation of a
  * graph's `nodes` or `edges` (see the {@link queryIndexCache} contract note),

package/dist/tools/repo-graph/types.d.ts

@@ -14,8 +14,7 @@ export declare const REPO_GRAPH_FILENAME = "repo-graph.json";
  * the importing file) and per-node `exportLines`, enabling the `callers` and
  * `dead_exports` queries. Both fields are optional, so graphs written by older
  * versions (1.0.0) still load — but `dead_exports` requires >= 1.1.0 data and
- * self-gates via {@link isSchemaVersionAtLeast} rather than relying on the
- * loader (which only checks that a version string is present, not its value).
+ * self-gates via {@link isSchemaVersionAtLeast}.
  *
  * 1.2.0 adds per-node `exportRanges` (1-based inclusive line spans keyed by
  * symbol name — exported symbols for every grammar, plus non-exported member
@@ -29,8 +28,8 @@ export declare const REPO_GRAPH_FILENAME = "repo-graph.json";
  * that distinguishes edges whose resolved target is a scannable source file
  * (a graph node) from edges whose target is an asset (JSON/CSS/etc. — a real
  * file that never becomes a node). The field is optional, so 1.0.0–1.2.0
- * graphs still load; `storage.ts` only checks that a version string is
- * present, and feature gating is per-query via {@link isSchemaVersionAtLeast}.
+ * graphs still load; feature gating is per-query via
+ * {@link isSchemaVersionAtLeast}.
  * For pre-1.3.0 graphs the loader/queries fall back to an extension check
  * (`isScannableSourcePath`) to classify an untagged edge's target kind.
  *
@@ -65,6 +64,8 @@ export declare const REPO_GRAPH_FILENAME = "repo-graph.json";
  * notes instead of failing (issue #1536).
  */
 export declare const GRAPH_SCHEMA_VERSION = "1.7.0";
+/** The oldest graph schema whose persisted shape this build can interpret. */
+export declare const MIN_SUPPORTED_GRAPH_SCHEMA_VERSION = "1.0.0";
 /**
  * Default per-file source-size ceiling shared by graph construction and
  * query-time source reads. The builder treats this as the default value of
@@ -80,6 +81,14 @@ export declare const DEFAULT_MAX_SOURCE_BYTES: number;
  * is greater than or equal to `minimum`.
  */
 export declare function isSchemaVersionAtLeast(version: string | undefined, minimum: string): boolean;
+/**
+ * Return whether a persisted graph schema is a canonical numeric semver in
+ * the supported compatibility window. This is deliberately stricter than
+ * {@link isSchemaVersionAtLeast}: feature gates may tolerate malformed input
+ * by treating missing components as zero, but a persistence boundary must
+ * never trust an unknown or future graph shape.
+ */
+export declare function isGraphSchemaVersionCompatible(version: unknown): version is string;
 export declare const FILE_ROLE_VALUES: readonly ["api_route", "middleware", "service_module", "data_module", "swarm_tool", "agent", "hook", "config", "schema", "test_file", "cli_command", "documentation", "source_module"];
 export type FileRole = (typeof FILE_ROLE_VALUES)[number];
 export declare const ROUTE_METHOD_VALUES: readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD", "ALL"];

package/dist/utils/bun-compat.d.ts

@@ -98,6 +98,14 @@ export interface BunCompatSpawnOptions {
     stdout?: 'inherit' | 'ignore' | 'pipe';
     stderr?: 'inherit' | 'ignore' | 'pipe';
     timeout?: number;
+    /**
+     * Maximum bytes retained for each buffered stdout/stderr stream. Invalid
+     * values fall back to `DEFAULT_BUN_SPAWN_MAX_BUFFER_BYTES` so asynchronous
+     * `bunSpawn` keeps its no-throw compatibility contract. Synchronous
+     * `bunSpawnSync` delegates to the host synchronous API and does not apply
+     * this asynchronous stream-capture option.
+     */
+    maxBuffer?: number;
     /** Preserve the caller's exact Windows argv quoting (required for cmd.exe /c). */
     windowsVerbatimArguments?: boolean;
     /**
@@ -111,6 +119,18 @@ export interface BunCompatSpawnOptions {
      */
     killProcessTree?: boolean;
 }
+/**
+ * Default bounded capture for unclaimed subprocess pipes. Five MiB matches
+ * the established Git subprocess limit while remaining finite by default.
+ */
+export declare const DEFAULT_BUN_SPAWN_MAX_BUFFER_BYTES: number;
+/** Raised when either buffered pipe exceeds its configured output limit. */
+export declare class BunCompatOutputLimitError extends Error {
+    readonly limit: number;
+    readonly captured: number;
+    readonly total: number;
+    constructor(limit: number, captured: number, total: number);
+}
 export interface BunCompatStream {
     text(): Promise<string>;
     bytes(): Promise<Uint8Array>;

package/dist/utils/gitignore-warning.d.ts

@@ -87,8 +87,11 @@ export declare const ENSURE_SWARM_GIT_EXCLUDED_PER_CALL_TIMEOUT_MS = 1500;
  * Steps:
  * 1. Resolve git root via `git rev-parse --show-toplevel`
  * 2. Resolve local exclude path via `git rev-parse --git-path info/exclude`
- * 3. Check if `.swarm/` is already ignored via `git check-ignore -q`
- * 4. If not ignored: append `.swarm/` to the local exclude file (idempotent)
+ * 3. Check if `.swarm/` AND `.swarm-worktrees/` are already ignored via two
+ *    independent `git check-ignore -q` probes (they are distinct patterns —
+ *    `.swarm/` does not cover `.swarm-worktrees/`, #2527)
+ * 4. For whichever pattern is not ignored: append it to the local exclude
+ *    file (idempotent, per-pattern)
  * 5. Detect tracked `.swarm/` files via `git ls-files -- .swarm`
  * 6. If tracked: emit an unsuppressed remediation warning
  *