opencode-swarm 7.168.1 → 7.170.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/sandbox/macos/sandbox-exec-executor.d.ts

@@ -23,12 +23,18 @@ declare function resolveProbeTargetBinary(): string;
  *
  * F6a item 2 (issue #2236): this deliberately shares the same primitives and
  * ordering as buildSandboxProfile's production profile — a blanket
- * `(deny file-write*)` followed by a scoped `(allow file-write* (subpath …))`,
- * plus a `(setenv …)`/`(unsetenv …)` pair (F6b) — so that probe success
- * implies the production profile's primitives actually parse under this
- * host's sandbox-exec. A trivial `(allow default)`-only probe would pass
- * even when the production profile is unparseable, which is the exact
- * probe-passes/production-fails failure mode this guards against.
+ * `(deny file-write*)` followed by a scoped `(allow file-write* (subpath …))` —
+ * so that probe success implies the production profile's primitives actually
+ * parse under this host's sandbox-exec. A trivial `(allow default)`-only probe
+ * would pass even when the production profile is unparseable, which is the
+ * exact probe-passes/production-fails failure mode this guards against.
+ *
+ * NEVER add env directives here or to buildSandboxProfile: `setenv`/`unsetenv`
+ * are not SBPL operations — the profile parser treats them as unbound
+ * variables and rejects the whole profile (exit 65), which silently disabled
+ * this executor on every macOS host (issue #2590). SBPL cannot mutate the
+ * sandboxed process's environment at all; env overrides are applied inside the
+ * wrapped command instead (see buildEnvOverridePrefix / wrapCommand).
  */
 declare function buildProbeProfile(tempDir: string): string;
 /**
@@ -61,15 +67,41 @@ export declare const _internals: {
     resetProbeMemo: typeof resetProbeMemo;
     buildSandboxProfile: typeof buildSandboxProfile;
     buildProbeProfile: typeof buildProbeProfile;
+    buildEnvOverridePrefix: typeof buildEnvOverridePrefix;
     resolveSandboxExecBinary: typeof resolveSandboxExecBinary;
     resolveProbeTargetBinary: typeof resolveProbeTargetBinary;
     exists: typeof existsSync;
     spawnSync: typeof spawnSync;
 };
 /**
- * Build a sandbox-exec profile string for the given scope paths, temp dir, and optional env overrides.
+ * Build the shell prefix that applies env overrides inside the wrapped
+ * command's `bash -c` payload (issue #2590).
+ *
+ * SBPL cannot mutate the sandboxed process's environment, so the hardening
+ * declared by getEnvOverrides() (DYLD_* unsets, PATH pin) and any per-call
+ * overrides are applied by the inner shell itself, before the user command:
+ * null-valued keys are unset via a single `unset` builtin, string-valued keys
+ * are exported with the value single-quote-escaped via shellEscape. Keys
+ * failing isValidEnvKey are silently dropped — the same contract the (broken)
+ * SBPL emitter applied, and required for shell safety too: an invalid key is
+ * neither a safe shell word nor a safe SBPL token.
+ *
+ * Returns '' when there is nothing to apply, so the no-override payload is
+ * byte-identical to the pre-#2590 wrapped command. The trailing '; ' lets the
+ * prefix compose with arbitrary user payloads.
+ */
+declare function buildEnvOverridePrefix(envOverrides?: Record<string, string | null>): string;
+/**
+ * Build a sandbox-exec profile string for the given scope paths and temp dir.
+ *
+ * NOTE: there are deliberately NO environment directives in the profile.
+ * `setenv`/`unsetenv` are not SBPL operations — sandbox-exec rejects them as
+ * unbound variables (exit 65), which silently disabled this executor on every
+ * macOS host (issue #2590). SBPL cannot mutate the sandboxed process's
+ * environment at all; env overrides are applied by the inner shell instead
+ * (see buildEnvOverridePrefix / wrapCommand).
  */
-declare function buildSandboxProfile(scopePaths: string[], tempDir: string, envOverrides?: Record<string, string | null>): string;
+declare function buildSandboxProfile(scopePaths: string[], tempDir: string): string;
 /**
  * macOS sandbox-exec sandbox executor.
  */
@@ -100,6 +132,8 @@ export declare class MacOSSandboxExecutor implements SandboxExecutor {
      * @param scopePaths - Additional scope paths to bind (merged with constructor scope)
      * @param tempDir   - Optional temp directory override
      * @param envOverrides - Optional per-call env overrides: string sets the var, null unsets it.
+     *                      Applied by the inner shell BEFORE the user command runs — SBPL
+     *                      cannot mutate the sandboxed process's environment (issue #2590).
      *                      When omitted, no per-call env override is applied.
      * @returns A sandbox-exec wrapped command string ready for shell execution,
      *          or the raw command string when the sandbox is unavailable (passthrough mode)
@@ -110,9 +144,12 @@ export declare class MacOSSandboxExecutor implements SandboxExecutor {
     /**
      * Return environment variable overrides required for the macOS sandbox.
      *
-     * DYLD_INSERT_LIBRARIES, DYLD_LIBRARY_PATH, DYLD_FRAMEWORK_PATH, and
-     * DYLD_ROOT_PATH can be used to bypass sandbox restrictions by injecting
-     * dynamic libraries. Unsetting them improves sandbox enforcement (defense in depth).
+     * DYLD_INSERT_LIBRARIES, DYLD_LIBRARY_PATH, DYLD_FRAMEWORK_PATH,
+     * DYLD_ROOT_PATH, and DYLD_FORCE_FLAT_NAMESPACE can be used to bypass
+     * sandbox restrictions by injecting or redirecting dynamic-library
+     * loading. Unsetting them improves sandbox enforcement (defense in
+     * depth); DYLD_FORCE_FLAT_NAMESPACE matches the Windows executors'
+     * scrub lists (review PRR-006, PR #2630).
      */
     getEnvOverrides(): Record<string, string | null>;
 }

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),