opencode-swarm 7.154.2 → 7.155.0

package/dist/memory/reflection-service.d.ts

@@ -1,7 +1,9 @@
+import { queryNodeByFile, resolveGraphStorageMode } from '../tools/repo-graph/indexed-storage';
+import type { RepoGraph } from '../tools/repo-graph/types';
 import { type MemoryConfig } from './config';
 import { type MemoryGateway, type RecordMemoryOutcomeInput } from './gateway';
-import { type ReflectionDigest } from './reflection';
-import type { MemoryOutcome, MemoryRecord } from './types';
+import { type ReflectionAnchorStatus, type ReflectionDigest } from './reflection';
+import type { MemoryAnchor, MemoryOutcome, MemoryRecord } from './types';
 interface OutcomeWriteThroughBase {
     record: MemoryRecord;
     eventId: string;
@@ -49,12 +51,16 @@ export declare const _test_exports: {
     isReflectionEligible: typeof isReflectionEligible;
     prepareWriteThroughEntry: typeof prepareWriteThroughEntry;
     sanitizeReflectionRecord: typeof sanitizeReflectionRecord;
+    createAnchorResolver: typeof createAnchorResolver;
 };
 export declare const _internals: {
     withReflectionLock: typeof withReflectionLock;
     serializeDigestArtifacts: typeof serializeDigestArtifacts;
     boundDigest: typeof boundDigest;
+    resolveGraphStorageMode: typeof resolveGraphStorageMode;
+    queryNodeByFile: typeof queryNodeByFile;
 };
+declare function createAnchorResolver(directory: string, graph: RepoGraph | null): (anchor: MemoryAnchor) => ReflectionAnchorStatus;
 declare function withReflectionLock<T>(directory: string, fn: () => Promise<T>): Promise<T>;
 interface ReflectionArtifactPair {
     markdown: string;

package/dist/memory/schema.d.ts

@@ -10,8 +10,8 @@ export declare const MemoryScopeTypeSchema: z.ZodEnum<{
     project: "project";
     workspace: "workspace";
     run: "run";
-    global_user: "global_user";
     repository: "repository";
+    global_user: "global_user";
     cohort: "cohort";
 }>;
 export declare const MemoryScopeRefSchema: z.ZodObject<{
@@ -20,8 +20,8 @@ export declare const MemoryScopeRefSchema: z.ZodObject<{
         project: "project";
         workspace: "workspace";
         run: "run";
-        global_user: "global_user";
         repository: "repository";
+        global_user: "global_user";
         cohort: "cohort";
     }>;
     userId: z.ZodOptional<z.ZodString>;
@@ -77,8 +77,8 @@ export declare const MemoryRecordSchema: z.ZodObject<{
             project: "project";
             workspace: "workspace";
             run: "run";
-            global_user: "global_user";
             repository: "repository";
+            global_user: "global_user";
             cohort: "cohort";
         }>;
         userId: z.ZodOptional<z.ZodString>;
@@ -171,8 +171,8 @@ export declare const MemoryProposalSchema: z.ZodObject<{
                 project: "project";
                 workspace: "workspace";
                 run: "run";
-                global_user: "global_user";
                 repository: "repository";
+                global_user: "global_user";
                 cohort: "cohort";
             }>;
             userId: z.ZodOptional<z.ZodString>;

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

@@ -7,9 +7,15 @@
  *  - Reflection  (default 60%): re-summarise into tighter format
  *  - Emergency   (default 80%): hard truncation to system + current task + last N turns
  *
- * Consumes the per-session budget pct recorded by system-enhancer.ts after
- * each budget calc (`getSessionBudgetPct`).
- * Never throws. Advisory system message injection via callback.
+ * Consumes the per-session FINAL PROMPT PRESSURE recorded by the final
+ * context-accounting step (#2107 §3) after every injector has run
+ * (`getFinalPromptPressure`); before that step has run for a session it falls
+ * back to the legacy injection-footprint pct (`getSessionBudgetPct`) so the
+ * tiers never go dark.
+ * Never throws. Advisory system message injection via callback. These tiers
+ * ADVISE the model to compact — they never compact anything themselves and
+ * never claim a compaction was performed (only the physical pruning in
+ * src/hooks/context-budget.ts actually removes content).
  */
 import type { CompactionConfig } from '../config/schema';
 export type { CompactionConfig };

package/dist/services/context-budget-service.d.ts

@@ -74,10 +74,14 @@ export interface BudgetState {
  */
 export declare const DEFAULT_CONTEXT_BUDGET_CONFIG: ContextBudgetConfig;
 /**
- * Estimate token count for text using character-based approximation
+ * Estimate token count for text using the canonical character-based heuristic.
  *
- * @param text - The text to estimate tokens for
- * @returns Estimated token count (ceiling of chars / 3.5)
+ * Delegates to `estimateTokens` in src/hooks/utils.ts (issue #1616/#2107). This
+ * used to be an independent ÷3.5 formula, which made the user-facing budget
+ * report disagree ~15% with the injection-admission path (0.33 tok/char) on
+ * the same text. The export is kept for existing importers (capsule-builder,
+ * the services barrel); it is a heuristic — provider-reported token usage is
+ * authoritative when available.
  */
 export declare function estimateTokens(text: string): number;
 /**

package/dist/services/injection-budget.d.ts

@@ -1,8 +1,10 @@
 /**
  * Unified Injection Budget Service (FR-002).
  *
- * Pure, side-effect-free allocation function for the combined
- * system-enhancer + knowledge-injector injection ceiling.
+ * Two responsibilities: (1) the pure, side-effect-free FR-002 allocation
+ * function for the combined system-enhancer + knowledge-injector injection
+ * ceiling, and (2) the per-session/per-turn producer ledger (#2107 §2) that
+ * every model-visible producer claims from or records emissions into.
  *
  * Allocation strategy: proportional share.
  * - When combined demand fits within the budget, each component receives its
@@ -20,8 +22,8 @@
  * Priority-based allocation would require an arbitrary component ranking
  * not specified by the acceptance criteria.
  *
- * Char-to-token conversion uses the project's existing 0.33 tok/char ratio
- * (matches `estimateTokens` in src/hooks/utils.ts:200).
+ * Char-to-token conversion goes through the canonical estimator
+ * (`estimateTokensFromCharCount` in src/hooks/utils.ts — issue #1616/#2107).
  */
 /**
  * Allocation result for a single turn's unified injection budget.
@@ -59,40 +61,115 @@ export interface InjectionBudgetConfig {
  */
 export declare function allocateInjectionBudget(systemEnhancerDemandTokens: number, knowledgeInjectorDemandChars: number, config: InjectionBudgetConfig): InjectionBudgetAllocation;
 /**
- * Reset the budget for a session to the full unified ceiling.
- * Called by the first component to run for a given turn.
+ * Producers that contribute to the model-visible request surface. The
+ * `surface` on each accounting entry records WHERE the producer's bytes live:
+ * `'system'` entries are pushed to `output.system` in the system.transform
+ * chain (invisible to the messages chain and to final accounting's direct
+ * measurement of `output.messages` — they MUST be added to the final total via
+ * this ledger); `'messages'` entries are spliced into `output.messages` and are
+ * therefore already inside the final measurement (attribution only — adding
+ * them again would double-count).
  */
-export declare function resetUnifiedBudget(sessionID: string, totalBudget: number): void;
+export type InjectionProducer = 'system-enhancer' | 'knowledge-injector' | 'context-capsule' | 'memory-recall' | 'advisory-queue' | 'swarm-command-banner' | 'linked-cohort-advisory' | 'spec-drift-advisory' | 'final-accounting-warning';
+export type InjectionSurface = 'system' | 'messages';
+export interface ProducerAccounting {
+    /** Tokens the producer asked the ledger for this turn (claims only). */
+    requested: number;
+    /** Tokens the ledger granted under the ceiling + local max (claims only). */
+    granted: number;
+    /** Tokens actually emitted to the model-visible surface. */
+    emitted: number;
+    /** Tokens the producer wanted but did not emit (its own pruning). */
+    truncated: number;
+    surface: InjectionSurface;
+}
+export interface TurnLedgerSummary {
+    generation: number;
+    totalBudget: number;
+    /** Ceiling enforcement is only active when `unified_injection_tokens` is configured. */
+    ceilingActive: boolean;
+    used: number;
+    producers: Array<{
+        producer: InjectionProducer;
+    } & ProducerAccounting>;
+}
+/**
+ * Begin a new turn ledger for a session: reset exactly once at the start of
+ * composing that request (the system-enhancer is the first producer and calls
+ * this). Mints a fresh generation, so any stale claim from a prior composition
+ * is discarded. `ceilingActive` is only true when
+ * `context_budget.unified_injection_tokens` is configured; when false the
+ * ledger records accounting but never denies a claim (default configs keep
+ * their pre-#2107 behavior).
+ */
+export declare function beginTurnLedger(sessionID: string, totalBudget: number, ceilingActive: boolean): number;
+/**
+ * Claim tokens from the turn ledger. The grant is bounded by the producer's
+ * own local maximum (`localMaxTokens`) and, only when the ceiling is active,
+ * by what remains of the unified ceiling. When NO ledger exists for the session
+ * (system-enhancer never ran this turn — native agent, first turn, or hook
+ * disabled), the claim fails open to the local maximum and is not recorded,
+ * preserving #1617's fail-open contract; the caller is expected to report that
+ * the hard ceiling was unavailable.
+ */
+export declare function claimTurnBudget(sessionID: string, producer: InjectionProducer, requestedTokens: number, opts?: {
+    localMaxTokens?: number;
+    surface?: InjectionSurface;
+}): {
+    granted: number;
+    ledgerPresent: boolean;
+    ceilingActive: boolean;
+};
+/**
+ * Record a producer's grant without claiming through `claimTurnBudget`.
+ *
+ * The system-enhancer and knowledge-injector enforce their split through the
+ * pure `allocateInjectionBudget` (FR-002 contract, pinned by tests) rather than
+ * sequential claims; this books their allocator-derived grants into the shared
+ * ceiling so later claimants (capsule, memory recall) draw from what actually
+ * remains. When the ceiling is inactive the grant is recorded but deducts
+ * nothing. The deduction is clamped to the remaining budget so `used` can never
+ * exceed `totalBudget`.
+ */
+export declare function recordProducerGrant(sessionID: string, producer: InjectionProducer, requestedTokens: number, grantedTokens: number, surface: InjectionSurface): void;
 /**
- * Return the remaining unified budget for a session.
+ * Record what a producer actually emitted (and pruned itself) this turn.
+ * Producers that never claim (fixed/base content: advisory queue, banners,
+ * the context-budget warning, the final-accounting warning) still record their
+ * emission here so the final accounting can include them.
  */
-export declare function getUnifiedBudgetRemaining(sessionID: string): number;
+export declare function recordProducerEmission(sessionID: string, producer: InjectionProducer, emittedTokens: number, truncatedTokens: number, surface: InjectionSurface): void;
 /**
- * Request a slice of the unified budget. Returns the granted token count.
- * If the requester's need exceeds the remaining budget, it gets the remainder
- * and the other source is implicitly blocked (remaining drops to 0).
+ * Snapshot of the session's current turn ledger (null when absent).
  */
-export declare function requestUnifiedBudget(sessionID: string, requestedTokens: number): number;
 /**
- * Return the total unified budget configured for a session (or 0 if unset).
+ * Deduct tokens from a producer's recorded emission (#2107 §3): downstream
+ * system-chain mutators (the role filter) REMOVE strings after the producer
+ * recorded them, and the final accounting must not count bytes the model
+ * never sees. Floors at zero; no-op without a ledger or producer entry.
  */
-export declare function getUnifiedBudgetTotal(sessionID: string): number;
+export declare function deductProducerEmission(sessionID: string, producer: InjectionProducer, removedTokens: number): void;
+export declare function getTurnLedgerSummary(sessionID: string): TurnLedgerSummary | null;
 /**
- * Remove a session's budget entry. Used for cleanup in tests.
+ * Emitted tokens recorded for one producer this turn (0 when no ledger or the
+ * producer has not run). Replaces the old `getSystemEnhancerDemand` relay: the
+ * knowledge-injector reads the system-enhancer's actual emission from here.
  */
-export declare function clearUnifiedBudget(sessionID: string): void;
+export declare function getProducerEmission(sessionID: string, producer: InjectionProducer): number;
 /**
- * Ensure a budget entry exists for the session. Creates one with the full
- * budget if none exists; leaves an existing entry untouched.
+ * Advance the turn generation for a session: the current ledger is discarded so
+ * the next request composition starts from a fresh generation. Called when
+ * compaction changes the message surface (`experimental.session.compacting`)
+ * and at session teardown.
  */
-export declare function ensureSessionBudget(sessionID: string, totalBudget: number): void;
+export declare function advanceTurnGeneration(sessionID: string): void;
 /**
- * Store the system-enhancer's actual per-turn token demand so that
- * knowledge-injector can read it and compute its proportional share.
+ * Test/maintenance hook: clear one session's ledger.
  */
-export declare function setSystemEnhancerDemand(sessionID: string, demand: number): void;
+export declare function clearTurnLedger(sessionID: string): void;
 /**
- * Return the system-enhancer's actual per-turn token demand for a session.
- * Returns 0 if no budget entry exists or demand was not set.
+ * Clear every session's ledger. Called from `resetSwarmState` so the
+ * plugin-wide reset also resets per-turn producer accounting (zaxbysauce
+ * review on PR #2415: the reset pattern must cover ALL module-scoped maps).
  */
-export declare function getSystemEnhancerDemand(sessionID: string): number;
+export declare function clearAllTurnLedgers(): void;

package/dist/state.d.ts

@@ -723,6 +723,34 @@ export declare const swarmState: {
         pct: number;
         tokens: number;
     }>;
+    /**
+     * Final model-visible prompt pressure per session (#2107 §3) — the ONE
+     * truthful measurement taken after every injector has run and the system
+     * messages have been consolidated. Unlike `lastBudgetBySession` (the swarm
+     * INJECTION FOOTPRINT pct measured from an intermediate file surface),
+     * this is estimated total prompt tokens vs the same model limit physical
+     * pruning uses. Written by the final-context-accounting step; read by the
+     * compaction tiers, the CONTEXT PRESSURE advisory, and `/swarm status`.
+     * Bounded via {@link setFinalPromptPressure} (AGENTS.md invariant 8).
+     */
+    finalPromptPressureBySession: Map<string, {
+        pct: number;
+        usedTokens: number;
+        limitTokens: number;
+        estimatorSource: string;
+        providerReported: boolean;
+    }>;
+    /**
+     * Per-session final-accounting warning-band latch (#2107 §3): one bounded
+     * advisory per session per band (warn / critical). Kept here — not in the
+     * hook module — so `resetSwarmState` covers it like every other
+     * session-keyed map (AGENTS.md invariant 8). Bounded via
+     * {@link setFinalAccountingWarningBand}.
+     */
+    finalAccountingWarningBandsBySession: Map<string, {
+        warn: boolean;
+        critical: boolean;
+    }>;
     /**
      * Live `model.limit.context` per session — keyed by sessionID and bound to
      * the reporting model/provider identity. Recorded by the
@@ -1382,6 +1410,34 @@ export declare function getLiveContextModelIdentity(sessionID: string | undefine
  *  written together so `/swarm status` can never pair a pct from one report
  *  with a denominator from another. */
 export declare function setSessionBudget(sessionID: string, pct: number, tokens: number): void;
+/**
+ * Record this session's final prompt pressure (#2107 §3), FIFO-evicting the
+ *  oldest entry past {@link MAX_TRACKED_BUDGET_SESSIONS}. Written once per request
+ *  composition by the final-context-accounting step.
+ */
+export declare function setFinalPromptPressure(sessionID: string, snapshot: {
+    pct: number;
+    usedTokens: number;
+    limitTokens: number;
+    estimatorSource: string;
+    providerReported: boolean;
+}): void;
+/** The session's final prompt pressure snapshot, or undefined when the final
+ *  accounting step has not run for it (e.g. native-agent sessions). */
+export declare function getFinalPromptPressure(sessionID: string | undefined): {
+    pct: number;
+    usedTokens: number;
+    limitTokens: number;
+    estimatorSource: string;
+    providerReported: boolean;
+} | undefined;
+/** Record that this session's #2107 §3 advisory already fired for a band
+ *  (one advisory per session per band), FIFO-evicting past the cap. */
+export declare function setFinalAccountingWarningBand(sessionID: string, band: 'warn' | 'critical'): void;
+/** Whether this session already received the band's advisory. */
+export declare function getFinalAccountingWarningBand(sessionID: string | undefined, band: 'warn' | 'critical'): boolean;
+/** Clear all band latches (used by resetSwarmState and tests). */
+export declare function clearFinalAccountingWarningBands(): void;
 /** This session's last budget percentage, or 0 if it has not been measured.
  *  Consumers that ACT on a session (compaction, the context-pressure advisory)
  *  MUST use this rather than any cross-session aggregate. */
@@ -1397,6 +1453,19 @@ export declare function getDisplayBudget(): {
     pct: number;
     tokens: number;
 } | null;
+/**
+ * The most-pressured session's FINAL prompt pressure snapshot, for
+ * process-wide DISPLAY only (`/swarm status` has no single session in scope).
+ * The snapshot is returned whole so the pct, used tokens, limit, and estimator
+ * source shown together always come from one measurement (#2107 §3).
+ */
+export declare function getDisplayFinalPromptPressure(): {
+    pct: number;
+    usedTokens: number;
+    limitTokens: number;
+    estimatorSource: string;
+    providerReported: boolean;
+} | null;
 /** Set the critical shown ids for a session, FIFO-evicting the oldest entry
  * if the cap is exceeded. Re-setting an existing key keeps insertion order
  * fresh for that key (delete-then-set). */

package/dist/summaries/summarizer.d.ts

@@ -44,11 +44,40 @@ declare function summarizeJsonArray(parsed: unknown[]): string;
  */
 declare function extractCodeSignatures(code: string): string[];
 /**
- * Build a preview for code output that includes declaration signatures.
+ * Codepoint-safe truncation to a UTF-8 byte budget (#2107 §5).
+ *
+ * Iterates code points (never UTF-16 units) so a multibyte CJK/emoji run can
+ * never be split mid-codepoint, and the result is deterministic across Bun and
+ * Node (which disagree on `Buffer.byteLength` for unpaired surrogates — per
+ * code point, both agree). Returns the kept text and the exact number of bytes
+ * omitted.
+ */
+export declare function truncateToBytes(text: string, maxBytes: number): {
+    text: string;
+    omittedBytes: number;
+};
+/**
+ * Deterministic bounded head/tail preview (#2107 §5).
+ *
+ * Head: the leading non-blank identity lines (ceil half of the line budget).
+ * Tail: the trailing RAW outcome lines (floor half) — compiler, test, lint,
+ * and security verdicts live at the END of tool output, so the old head-only
+ * preview discarded exactly the decision-relevant evidence. Lines are never
+ * reordered within either segment, no outcome is invented, and every dropped
+ * region is disclosed with an accurate omitted-line count. When everything
+ * fits, the original text is returned unchanged (modulo per-line caps).
+ */
+declare function headTailPreview(output: string, maxLines: number): string;
+/**
+ * Build a preview for code output that includes declaration signatures plus
+ * the bounded head/tail policy (failure output at the end of a code blob is
+ * preserved).
  */
 declare function summarizeCode(output: string): string;
 /**
- * Build a preview for plain text output (leading non-blank lines).
+ * Build a preview for plain text output using the bounded head/tail policy
+ * (see headTailPreview). Previously head-only: the first `maxLines` non-blank
+ * lines, which silently discarded trailing failure/exit evidence.
  */
 declare function summarizeText(output: string, maxLines: number): string;
 /**
@@ -56,7 +85,7 @@ declare function summarizeText(output: string, maxLines: number): string;
  * @param output - The full tool output string
  * @param toolName - The name of the tool that produced the output
  * @param summaryId - Unique identifier for this summary
- * @param maxSummaryChars - Maximum characters allowed for the preview
+ * @param maxSummaryChars - Maximum bytes allowed for the preview
  * @returns Formatted summary string
  */
 export declare function createSummary(output: string, toolName: string, summaryId: string, maxSummaryChars: number): string;
@@ -64,6 +93,8 @@ export declare function createSummary(output: string, toolName: string, summaryI
  * Internal helpers exposed for testability.
  */
 export declare const _internals: {
+    truncateToBytes: typeof truncateToBytes;
+    headTailPreview: typeof headTailPreview;
     jsonTypeSignature: typeof jsonTypeSignature;
     summarizeJsonObject: typeof summarizeJsonObject;
     summarizeJsonArray: typeof summarizeJsonArray;

package/dist/tools/repo-graph/indexed-storage.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Derived SQLite index for the repo dependency graph (issue #1534).
+ *
+ * `.swarm/repo-graph.json` stays the single authoritative document in BOTH
+ * storage modes. When `repo_graph.storage === 'indexed'`, `saveGraph` also
+ * maintains `.swarm/repo-memory.sqlite`, a *derived accelerator* whose only job
+ * is to answer "give me the neighbourhood of these files" without parsing the
+ * whole JSON document. It returns an ordinary `RepoGraph` value that is fed to
+ * the existing, unmodified `getGraphNode` / `getLocalizationContext` /
+ * `getBlastRadius`, so no query logic is duplicated here.
+ *
+ * Every read verifies, before returning anything:
+ *   (a) the persisted `graph_meta.workspace_root` realpath-matches the ACTIVE
+ *       workspace (same trust boundary as `bindGraphToWorkspace`,
+ *       `storage.ts:100-127`), and
+ *   (b) `graph_meta.source_size` / `source_mtime_ms` equal a live stat of
+ *       `repo-graph.json`.
+ * Any mismatch, absence, or error returns null and the caller uses its
+ * existing JSON path. The index is never a second source of truth.
+ *
+ * Runtime portability (AGENTS.md invariant 2): the SQLite driver is resolved
+ * ONLY through `src/db/sqlite-loader.ts`. The `import type` below is erased at
+ * build time, so this module contributes no `bun:` runtime resolution.
+ * `node:sqlite` is stricter than `bun:sqlite` about bound parameters, so every
+ * statement's placeholder count equals its argument count exactly and
+ * no-placeholder statements are issued as `db.run(sql)` with no array.
+ */
+import type { GraphNode, RepoGraph } from './types';
+/** Filename of the derived index inside `.swarm/`. */
+export declare const REPO_MEMORY_FILENAME = "repo-memory.sqlite";
+/**
+ * Validated absolute path to `.swarm/repo-memory.sqlite`.
+ * Mirrors `getGraphPath`: validateWorkspace → validateSwarmPath →
+ * validateSymlinkBoundary.
+ */
+export declare function getRepoMemoryPath(workspace: string): string;
+/**
+ * Close the cached connection for a workspace. Called by the `/swarm close`
+ * clean stage before unlinking the store (Windows holds a WAL-mode file open,
+ * so `unlink` would fail with EBUSY — same guard as
+ * `closeProjectDb`, `project-db.ts:232-234`) and from test teardown.
+ */
+export declare function closeRepoMemory(workspace: string): void;
+/**
+ * Close every cached connection. Test-teardown only: `/swarm close` uses the
+ * singular `closeRepoMemory` (src/commands/close.ts); this export has no
+ * other production caller.
+ */
+export declare function closeAllRepoMemory(): void;
+/**
+ * Delete the derived store and its WAL sidecars.
+ *
+ * The cached handle is closed FIRST on every delete path — a live WAL-mode
+ * connection keeps the file open and Windows `unlink` fails with EBUSY
+ * otherwise.
+ */
+export declare function deleteRepoMemory(workspace: string): void;
+/** Whether a SQLite driver is resolvable in this runtime. */
+export declare function isIndexedStorageAvailable(): boolean;
+/**
+ * Effective storage mode for a workspace.
+ *
+ * Config is the kill switch: flipping `repo_graph.storage` back to `'json'`
+ * stops every reader from consulting the index immediately, even while a valid
+ * store with a matching stamp is still on disk. Falls back to `'json'` on any
+ * config error and whenever no SQLite driver is available.
+ */
+export declare function resolveGraphStorageMode(workspace: string): 'json' | 'indexed';
+/**
+ * Test seam (invariant 7: DI over mock.module) so the driver-unavailable
+ * fallback of {@link resolveGraphStorageMode} is exercisable without patching
+ * the module graph. Tests swap and restore the property; production reads it
+ * unchanged.
+ */
+export declare const _internals: {
+    isIndexedStorageAvailable: typeof isIndexedStorageAvailable;
+};
+/**
+ * Replace the whole index from `graph` in one transaction.
+ *
+ * `stamp` MUST be a stat of the TEMP FILE, taken inside the save lock
+ * immediately BEFORE this writer's rename publishes it — not a stat of
+ * `repo-graph.json` at any point. `rename(2)` leaves the inode's mtime and size
+ * untouched, so the temp-file stat identifies THIS writer's own bytes. Any stat
+ * of the published path instead describes whatever is at that path by then: a
+ * concurrent writer that failed the lock renames unlocked (the JSON write is
+ * never lock-gated), so a post-rename stat would let ITS bytes validate an index
+ * holding THIS writer's superseded content. See `saveGraph`.
+ *
+ * Returns false — never throws — on every failure; the JSON write is the
+ * durability point and has already succeeded.
+ */
+export declare function syncIndexFromGraph(workspace: string, graph: RepoGraph, stamp: {
+    size: number;
+    mtimeMs: number;
+    ino: string;
+}): Promise<boolean>;
+/**
+ * Resolve a single file to its `GraphNode` using the index.
+ *
+ * Implements closure rule steps 1-2 in full, so an anchor whose `moduleName`
+ * diverges from `path.relative(root, filePath)` resolves exactly as it would
+ * through `getGraphNode` on the full graph. Returns null whenever the index is
+ * absent, stale, foreign, or unusable — the caller keeps its existing path.
+ */
+export declare function queryNodeByFile(workspace: string, file: string): GraphNode | null;
+/**
+ * Build a bounded subgraph covering `files` and their neighbourhood, suitable
+ * for feeding the unmodified `getLocalizationContext` / `getBlastRadius`.
+ *
+ * Closure rule (normative, from the approved plan):
+ *  1-2. resolve every requested file the way `getGraphNode` would;
+ *  3.   `T` = the union of resolved targets across ALL requested files in this
+ *       ONE call (`getBlastRadius` seeds `visited` with every target at once,
+ *       query.ts:623-625, so per-file subgraphs merged afterwards would produce
+ *       a different `totalDependents` and therefore a different `riskLevel`);
+ *       `N = T ∪ R_1..R_D ∪ F_1`, where `R` is the reverse closure to depth `D`
+ *       and `F_1` is the 1-hop forward set from the targets only
+ *       (`getDependencies`, query.ts:398-406);
+ *  4.   `E = { edge : source ∈ N AND target ∈ N }` — AND, not incidence. An OR
+ *       rule would admit frontier edges whose counterpart node is absent, and
+ *       `moduleNameForEdgePath` (query.ts:83-88) silently degrades to a
+ *       different string for those, changing `importers` / `dependencies` /
+ *       `directDependents`. No asset/kind filtering happens in SQL:
+ *       `buildReverseIndex` and `collectExternallyUsedSymbols` re-apply
+ *       `isAssetEdge` downstream, so over-inclusion is harmless while
+ *       under-inclusion is fatal;
+ *  5.   the returned `workspaceRoot` is the realpath-bound ACTIVE workspace,
+ *       never the persisted `graph_meta.workspace_root`.
+ *
+ * `depth` is clamped to at least 1: `getLocalizationContext` calls
+ * `getImporters` unconditionally, which needs `R_1` even when it passes
+ * `maxDepth = 0` to `getBlastRadius`. Over-inclusion of nodes is safe (a
+ * `maxDepth = 0` blast radius early-returns, query.ts:613-621).
+ */
+export declare function loadSubgraphForFiles(workspace: string, files: string[], depth: number): RepoGraph | null;

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

@@ -1,6 +1,13 @@
 import type { FreshnessProbe } from './freshness';
 import type { BlastRadiusResult, CallerReference, ContextPackResult, ContextPackSourceMode, DeadExportsResult, FileOntology, FileReference, GraphHealthResult, GraphNode, LocalizationBlock, PackageBoundarySummary, RepoGraph, SymbolReference } from './types';
 export declare function getGraphNode(graph: RepoGraph, input: string): GraphNode | undefined;
+/**
+ * Drop every cached query index. Required after any in-place mutation of a
+ * graph's `nodes` or `edges` (see the {@link queryIndexCache} contract note),
+ * and retained as the test seam for index-staleness assertions. Reassigns a
+ * fresh `WeakMap` rather than deleting keys, so it invalidates graphs this
+ * module can no longer enumerate.
+ */
 export declare function resetQueryCache(): void;
 /**
  * @deprecated Graph age is not a content-freshness signal. Internal consumers

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-swarm",
-	"version": "7.154.2",
+	"version": "7.155.0",
 	"description": "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -114,6 +114,7 @@
 		"check:trajectory-store": "bun run scripts/check-trajectory-store-usage.ts",
 		"check:mock-cleanup": "bun run scripts/check-mock-cleanup.ts",
 		"check:invariants": "bun run scripts/check-invariants.ts",
+		"check:token-formula": "bun run scripts/check-token-formula.ts",
 		"check:cross-contamination": "bun run scripts/check-cross-contamination.ts",
 		"check:test-clock": "bun run scripts/check-test-clock.ts",
 		"check:test-file-cap": "bun run scripts/check-test-file-cap.ts",
@@ -123,6 +124,7 @@
 		"check:gate-portability": "bun run scripts/check-gate-portability.ts",
 		"check:bare-spawn": "bun run scripts/check-bare-executable-spawn.ts",
 		"check:error-channel-discard": "bun run scripts/check-error-channel-discard.ts",
+		"check:registry-citations": "bun run scripts/check-registry-citations.ts",
 		"check:memory-recall": "bun run scripts/memory-recall-regression.ts"
 	},
 	"dependencies": {