opencode-swarm 7.135.4 → 7.136.0

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

@@ -14,7 +14,7 @@ import { extractFileSymbols } from '../../lang/symbol-graph';
 import { extractGoSymbols, extractPythonSymbols, extractRustSymbols, extractTSSymbols } from '../symbols';
 import { extractFileOntology } from './ontology';
 import { safeRealpathSync } from './safe-realpath';
-import type { BuildWorkspaceGraphOptions, GraphEdge, GraphNode, RepoGraph, RepoGraphDiagnostics, SymbolEdge } from './types';
+import type { BuildWorkspaceGraphOptions, GraphEdge, GraphExtractorInputWitness, GraphNode, RepoGraph, RepoGraphDiagnostics, SymbolEdge } from './types';
 /**
  * _internals DI seam for the walk clock and graph helpers.
  * Defaults to the real implementations. Tests can override these to inject
@@ -52,6 +52,8 @@ export declare function isScannableSourcePath(p: string): boolean;
  * queries.
  */
 export declare function isAssetEdge(edge: GraphEdge): boolean;
+/** Correctness witnesses are not display diagnostics and must cover the full walk. */
+export declare const MAX_EXTRACTOR_INPUT_WITNESSES = 100256;
 /**
  * Add or update a node in the graph.
  * @param graph - The graph to modify
@@ -144,6 +146,56 @@ declare function parseFileImports(rawContent: string, sourceFile?: string, works
  * @returns the *exported* names (binding.imported) judged to be used.
  */
 declare function computeUsedSymbols(strippedContent: string, bindings: readonly ImportBinding[]): string[];
+/**
+ * Return whether a path is a graph-wide extractor input. Changes to these
+ * manifests can alter package-boundary ontology for many nodes, so consumers
+ * must rebuild rather than treating them as an ordinary one-file refresh.
+ */
+export declare function isGraphWideInputPath(filePath: string): boolean;
+/**
+ * Async, chunked, cycle-safe equivalent of `findSourceFiles`.
+ *
+ * Yields to the event loop every `ASYNC_WALK_YIELD_INTERVAL` entries so the
+ * Node/Bun macrotask queue continues to drain while the walk runs. This is
+ * the variant called from the plugin init path; the sync variant remains
+ * available for non-init callers (tools, tests) for compatibility.
+ */
+export interface RepoGraphInputMetadata {
+    absolutePath: string;
+    kind: 'source' | 'manifest';
+    sizeBytes: number;
+    mtimeMs: number;
+}
+export interface RepoGraphInputWalkResult {
+    sourceFiles: string[];
+    manifestFiles: string[];
+    metadata: RepoGraphInputMetadata[];
+    manifestDirs: Set<string>;
+    truncated: boolean;
+    truncationReason?: 'budget' | 'cap';
+    incomplete: boolean;
+    unreadableDirectories: string[];
+    unreadableFiles: string[];
+    probedFiles: number;
+    elapsedMs: number;
+}
+export interface RepoGraphInputWalkOptions {
+    walkBudgetMs?: number;
+    maxFiles?: number;
+    followSymlinks?: boolean;
+    excludeDirs?: readonly string[];
+    /** Capture size/mtime for every source and manifest during this same walk. */
+    captureMetadata?: boolean;
+    /** Capture only graph-wide manifest metadata (used by the graph builder). */
+    captureManifestMetadata?: boolean;
+}
+/**
+ * Enumerate every input used by repository-graph extraction with the same
+ * bounded, deterministic, cycle-safe traversal as the async graph builder.
+ * Directory and metadata I/O failures are surfaced through `incomplete` so a
+ * caller can refuse removals/certification instead of guessing.
+ */
+export declare function walkRepoGraphInputs(dir: string, options?: RepoGraphInputWalkOptions): Promise<RepoGraphInputWalkResult>;
 /**
  * Result of scanning a single file for graph updates.
  */
@@ -164,6 +216,8 @@ export interface AsyncScanResult {
     symbolEdges: SymbolEdge[];
     /** Optional file-level diagnostics collected during async scanning. */
     diagnostics?: RepoGraphDiagnostics;
+    /** Build-time witness for a deterministic non-node skip. */
+    inputWitness?: GraphExtractorInputWitness;
 }
 /**
  * Scan a single file and extract its graph node and edges.

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

@@ -1,48 +1,24 @@
 /**
- * In-memory cache for loaded repo graphs.
+ * Bounded in-memory cache for loaded repo graphs.
  *
- * Three maps keyed by normalized workspace path:
- * - graphCache  — the last loaded/saved RepoGraph for each workspace
- * - dirtyFlags  — whether the cached graph has been modified since the last save
- * - mtimeCache  — the file mtime at the time the graph was last loaded/saved,
- *                 used by the optimistic concurrency check in incremental.ts
- *
- * All public functions normalize the workspace path before use so callers
- * are not required to pre-normalize.
+ * Graph, dirty, and mtime state intentionally share one entry so eviction can
+ * never leave one piece of workspace state behind. Entries are keyed by an
+ * absolute normalized workspace path and maintained as a true LRU: every read
+ * moves the entry to the newest position and insertion evicts the oldest.
  */
 import type { RepoGraph } from './types';
-/**
- * Get the cached graph for a workspace.
- * @param workspace - The workspace directory (absolute or relative path)
- * @returns The cached graph or undefined if not cached
- */
+/** Return the cached graph for a workspace, if present. */
 export declare function getCachedGraph(workspace: string): RepoGraph | undefined;
 /**
- * Set the cached graph for a workspace.
- * @param workspace - The workspace directory (absolute or relative path)
- * @param graph - The graph to cache
- * @param mtime - Optional file mtime to track for cache invalidation
+ * Cache a graph and mark it clean. Omitting mtime clears any previous mtime so
+ * an old optimistic-concurrency witness cannot survive a new graph value.
  */
 export declare function setCachedGraph(workspace: string, graph: RepoGraph, mtime?: number): void;
-/**
- * Mark a workspace's cache as dirty (modified since last save).
- * @param workspace - The workspace directory (absolute or relative path)
- */
+/** Mark a workspace's cached state dirty, preserving its graph and mtime. */
 export declare function markDirty(workspace: string): void;
-/**
- * Check if a workspace's cache is dirty.
- * @param workspace - The workspace directory (absolute or relative path)
- * @returns True if the cache has been modified since last save
- */
+/** Return whether the workspace's cached state is dirty. */
 export declare function isDirty(workspace: string): boolean;
-/**
- * Clear the cache for a workspace.
- * @param workspace - The workspace directory (absolute or relative path)
- */
+/** Remove all cached state for one workspace. */
 export declare function clearCache(workspace: string): void;
-/**
- * Get the cached file mtime for a workspace (used for optimistic concurrency).
- * @param workspace - The workspace directory (absolute or relative path)
- * @returns The cached mtime in milliseconds, or undefined if not cached
- */
+/** Return the graph-file mtime captured with the cached graph, if present. */
 export declare function getCachedMtime(workspace: string): number | undefined;

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

@@ -0,0 +1,54 @@
+/**
+ * Bounded content-freshness certification for repository graphs.
+ *
+ * A probe is one bounded readdir+stat directory walk, not a stat pass over
+ * already-known graph nodes. It reads no source contents and performs no
+ * parsing, so it is much cheaper than graph construction while still finding
+ * additions and removals. The sidecar deliberately fingerprints metadata
+ * (byte size + numeric mtime), not file bytes, so a tool that preserves both
+ * values can evade detection. Results may also be cached for up to 30 seconds.
+ * Callers must therefore treat `inconclusive` as unknown and may mutate/delete
+ * only after a complete `drifted` probe.
+ */
+import * as fsPromises from 'node:fs/promises';
+import { bunWrite } from '../../utils/bun-compat';
+import { walkRepoGraphInputs } from './builder';
+import type { FreshnessProbeState, RepoGraph } from './types';
+export declare const REPO_GRAPH_FINGERPRINT_FILENAME = "repo-graph.fingerprint.json";
+export declare const FINGERPRINT_SCHEMA_VERSION = 1;
+export declare const EXTRACTOR_STAMP: string;
+export interface FreshnessOptions {
+    walkBudgetMs?: number;
+    maxFiles?: number;
+    followSymlinks?: boolean;
+    excludeDirs?: readonly string[];
+}
+export interface FreshnessProbe {
+    state: FreshnessProbeState;
+    /** Absolute paths positively observed as new or metadata-changed. */
+    changed: string[];
+    /** Absolute paths absent from a complete walk. Empty when inconclusive. */
+    removed: string[];
+    truncated: boolean;
+    probedFiles: number;
+    elapsedMs: number;
+}
+export declare const _internals: {
+    now: () => number;
+    walkRepoGraphInputs: typeof walkRepoGraphInputs;
+    open: typeof fsPromises.open;
+    bunWrite: typeof bunWrite;
+    fsRename: typeof fsPromises.rename;
+    fsUnlink: typeof fsPromises.unlink;
+    retryDelayMs: number;
+};
+/** Invalidate one project's probe cache, or every entry when root is omitted. */
+export declare function invalidateFreshnessCache(root?: string): void;
+/** Probe workspace metadata using a bounded per-directory 16-entry LRU cache. */
+export declare function probeFreshness(root: string, options?: FreshnessOptions): Promise<FreshnessProbe>;
+/**
+ * Atomically persist a sidecar only when a complete walk certifies that the
+ * graph and every intentional stable skip match current metadata. Never
+ * throws; `false` means the graph remains deliberately uncertified.
+ */
+export declare function writeFingerprint(root: string, graph: RepoGraph, options?: FreshnessOptions): Promise<boolean>;

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

@@ -15,16 +15,27 @@
  * rebuild on every incremental update.
  */
 import { type Stats } from 'node:fs';
+import { buildWorkspaceGraphAsync, scanFileAsync } from './builder';
+import { writeFingerprint } from './freshness';
+import { saveGraph } from './storage';
+import type { BuildWorkspaceGraphOptions, RepoGraph } from './types';
+/** Public options shared by hook, read-repair, and direct callers. */
+export interface IncrementalUpdateOptions {
+    forceRebuild?: boolean;
+    /** Bounds and exclusions used by both direct and fallback full builds. */
+    buildOptions?: BuildWorkspaceGraphOptions;
+}
 /**
- * DI seam for the optimistic-concurrency stat check (defect A4). Tests override
- * `stat` to inject deterministic mtime shifts between load and the pre-save
- * re-check, exercising the reload-and-replay branch without races. Defaults to
- * the real `fsPromises.stat`. Restore in afterEach.
+ * DI seam for concurrency, scan-failure, and paired-persistence tests. Tests
+ * must restore every replaced entry in afterEach.
  */
 export declare const _internals: {
     stat: (path: string) => Promise<Stats>;
+    scanFileAsync: typeof scanFileAsync;
+    buildWorkspaceGraphAsync: typeof buildWorkspaceGraphAsync;
+    saveGraph: typeof saveGraph;
+    writeFingerprint: typeof writeFingerprint;
 };
-import type { RepoGraph } from './types';
 /**
  * Incrementally update the graph for a set of changed files.
  * Re-scans only the specified files, updates their nodes and edges,
@@ -36,6 +47,4 @@ import type { RepoGraph } from './types';
  * @param options.forceRebuild - Force a full rebuild instead of incremental
  * @returns Updated RepoGraph
  */
-export declare function updateGraphForFiles(workspaceRoot: string, filePaths: string[], options?: {
-    forceRebuild?: boolean;
-}): Promise<RepoGraph>;
+export declare function updateGraphForFiles(workspaceRoot: string, filePaths: string[], options?: IncrementalUpdateOptions): Promise<RepoGraph>;

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

@@ -1,8 +1,14 @@
+import type { FreshnessProbe } from './freshness';
 import type { BlastRadiusResult, CallerReference, ContextPackResult, DeadExportsResult, FileOntology, FileReference, GraphHealthResult, GraphNode, LocalizationBlock, PackageBoundarySummary, RepoGraph, SymbolReference } from './types';
 export declare function getGraphNode(graph: RepoGraph, input: string): GraphNode | undefined;
 export declare function resetQueryCache(): void;
+/**
+ * @deprecated Graph age is not a content-freshness signal. Internal consumers
+ * use {@link probeFreshness}; this compatibility helper intentionally retains
+ * its historical five-minute TTL semantics for external callers.
+ */
 export declare function isGraphFresh(graph: RepoGraph | null, maxAgeMs?: number): boolean;
-export declare function getGraphHealth(graph: RepoGraph | null, workspaceRoot?: string): GraphHealthResult;
+export declare function getGraphHealth(graph: RepoGraph | null, workspaceRoot?: string, probe?: FreshnessProbe): GraphHealthResult;
 export declare function getImporters(graph: RepoGraph, filePath: string): FileReference[];
 export declare function getDependencies(graph: RepoGraph, filePath: string): FileReference[];
 export declare function getSymbolConsumers(graph: RepoGraph, filePath: string, symbolName: string): SymbolReference[];

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

@@ -6,6 +6,7 @@
  * cache. Symlink resolution guards against workspace-escape attacks.
  */
 import * as fsPromises from 'node:fs/promises';
+import { type FreshnessOptions, writeFingerprint } from './freshness';
 import { safeRealpathSync } from './safe-realpath';
 import type { RepoGraph } from './types';
 /**
@@ -20,6 +21,7 @@ export declare const _internals: {
     safeRealpathSync: typeof safeRealpathSync;
     fsRename: typeof fsPromises.rename;
     retryDelayMs: number;
+    writeFingerprint: typeof writeFingerprint;
 };
 /**
  * Get the validated path for the repo-graph.json file.
@@ -75,4 +77,4 @@ export declare function loadOrCreateGraph(workspace: string): Promise<RepoGraph>
  * @throws Error if workspace is dirty but cache is missing (inconsistent state)
  * @throws Error if save fails
  */
-export declare function saveIfDirty(workspace: string): Promise<void>;
+export declare function saveIfDirty(workspace: string, freshnessOptions?: FreshnessOptions): Promise<void>;

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

@@ -35,8 +35,14 @@ export declare const REPO_GRAPH_FILENAME = "repo-graph.json";
  * Diagnostics are additive and optional on all schema versions. Old graphs
  * without diagnostics remain readable; graph-health queries surface empty
  * diagnostics with an explicit rebuild note.
+ *
+ * 1.4.0 adds optional numeric `sizeBytes` and `mtimeMs` witnesses to each
+ * node. Builders capture them from the same stat used immediately before the
+ * source read. The content-freshness sidecar requires both witnesses before
+ * it will certify a graph; older graphs remain readable but are intentionally
+ * treated as needing a rebuild before certification.
  */
-export declare const GRAPH_SCHEMA_VERSION = "1.3.0";
+export declare const GRAPH_SCHEMA_VERSION = "1.4.0";
 /**
  * Compare dotted numeric version strings (e.g. '1.1.0' >= '1.1.0').
  * Missing/non-numeric segments are treated as 0. Returns true when `version`
@@ -132,6 +138,10 @@ export interface GraphNode {
     language: string;
     /** Last modified timestamp */
     mtime: string;
+    /** Exact byte size captured by the stat that preceded the source read. */
+    sizeBytes?: number;
+    /** Numeric mtime captured with `sizeBytes`; avoids ISO precision loss. */
+    mtimeMs?: number;
     /** Optional code ontology facts for agent context/preflight packets */
     ontology?: FileOntology;
 }
@@ -280,6 +290,14 @@ export interface GraphUnresolvedImport {
     file: string;
     specifier: string;
 }
+/** Build-time metadata witness for a non-node extractor input. */
+export interface GraphExtractorInputWitness {
+    /** Normalized workspace-relative path. */
+    file: string;
+    kind: 'manifest' | 'stable-skip';
+    sizeBytes: number;
+    mtimeMs: number;
+}
 export interface RepoGraphDiagnostics {
     extractionFailures?: GraphExtractionFailure[];
     unresolvedImports?: GraphUnresolvedImport[];
@@ -287,6 +305,14 @@ export interface RepoGraphDiagnostics {
     unsupportedFiles?: string[];
     binaryFiles?: string[];
     unreadableFiles?: string[];
+    /** Source files intentionally skipped because their extracted node failed validation. */
+    validationSkippedFiles?: string[];
+    /**
+     * Build-time witnesses for manifests and deterministic non-node skips.
+     * Persistence compares them against its live walk so an edit between graph
+     * extraction and sidecar persistence cannot be blessed as clean.
+     */
+    extractorInputWitnesses?: GraphExtractorInputWitness[];
     lowConfidenceEdgeCount?: number;
     /**
      * True when the last workspace walk was truncated by the file cap or wall-
@@ -306,6 +332,7 @@ export interface RepoGraphDiagnostics {
 export interface GraphHealthResult {
     schemaVersion: string | null;
     fresh: boolean;
+    probeState: FreshnessProbeState;
     staleFiles: string[];
     extractionFailures: GraphExtractionFailure[];
     unresolvedImports: GraphUnresolvedImport[];
@@ -313,12 +340,15 @@ export interface GraphHealthResult {
     unsupportedFiles: string[];
     binaryFiles: string[];
     unreadableFiles: string[];
+    validationSkippedFiles: string[];
     lowConfidenceEdgeCount: number;
     walkTruncated: boolean;
     walkTruncationReason: 'budget' | 'cap' | null;
     incrementalFallbacks: number;
     notes: string[];
 }
+/** Authoritative states returned by the bounded repository freshness probe. */
+export type FreshnessProbeState = 'clean' | 'drifted' | 'no-fingerprint' | 'inconclusive';
 export interface BlastRadiusResult {
     target: string[];
     directDependents: string[];

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

@@ -14,15 +14,17 @@
  *
  * All existing imports of this module continue to work unchanged.
  */
-export type { ScanResult } from './repo-graph/builder';
-export { addEdge, buildWorkspaceGraph, buildWorkspaceGraphAsync, isScannableSourcePath, resolveModuleSpecifier, upsertNode, } from './repo-graph/builder';
+export type { RepoGraphInputMetadata, RepoGraphInputWalkOptions, RepoGraphInputWalkResult, ScanResult, } from './repo-graph/builder';
+export { addEdge, buildWorkspaceGraph, buildWorkspaceGraphAsync, isGraphWideInputPath, isScannableSourcePath, resolveModuleSpecifier, upsertNode, walkRepoGraphInputs, } from './repo-graph/builder';
 export { clearCache, getCachedGraph, getCachedMtime, isDirty, markDirty, setCachedGraph, } from './repo-graph/cache';
+export type { FreshnessOptions, FreshnessProbe, } from './repo-graph/freshness';
+export { EXTRACTOR_STAMP, FINGERPRINT_SCHEMA_VERSION, invalidateFreshnessCache, probeFreshness, REPO_GRAPH_FINGERPRINT_FILENAME, writeFingerprint, } from './repo-graph/freshness';
 export { updateGraphForFiles } from './repo-graph/incremental';
 export type { ExtractFileOntologyInput } from './repo-graph/ontology';
 export { extractFileOntology } from './repo-graph/ontology';
 export type { DeadExportsOptions } from './repo-graph/query';
 export { buildOntologyPreflightPacket, getBlastRadius, getCallers, getContextPack, getDeadExports, getDependencies, getFileOntology, getGraphHealth, getGraphNode, getImporters, getKeyFiles, getLocalizationContext, getPackageBoundaries, getSymbolConsumers, isGraphFresh, resetQueryCache, } from './repo-graph/query';
 export { getGraphPath, loadGraph, loadGraphSync, loadOrCreateGraph, saveGraph, saveIfDirty, } from './repo-graph/storage';
-export type { BlastRadiusResult, BuildWorkspaceGraphOptions, CallerReference, ContextPackResult, ContextPackSpan, ConventionFact, DataOperationFact, DeadExportCandidate, DeadExportsResult, FileOntology, FileReference, FileRole, GraphEdge, GraphExtractionFailure, GraphHealthResult, GraphNode, GraphUnresolvedImport, LocalizationBlock, OntologyFinding, PackageBoundarySummary, RepoGraph, RepoGraphDiagnostics, RouteFact, RouteMethod, SecurityFact, SymbolEdge, SymbolReference, } from './repo-graph/types';
+export type { BlastRadiusResult, BuildWorkspaceGraphOptions, CallerReference, ContextPackResult, ContextPackSpan, ConventionFact, DataOperationFact, DeadExportCandidate, DeadExportsResult, FileOntology, FileReference, FileRole, FreshnessProbeState, GraphEdge, GraphExtractionFailure, GraphExtractorInputWitness, GraphHealthResult, GraphNode, GraphUnresolvedImport, LocalizationBlock, OntologyFinding, PackageBoundarySummary, RepoGraph, RepoGraphDiagnostics, RouteFact, RouteMethod, SecurityFact, SymbolEdge, SymbolReference, } from './repo-graph/types';
 export { createEmptyGraph, GRAPH_SCHEMA_VERSION, isSchemaVersionAtLeast, normalizeGraphPath, REPO_GRAPH_FILENAME, updateGraphMetadata, } from './repo-graph/types';
 export { validateGraphEdge, validateGraphNode, validateWorkspace, } from './repo-graph/validation';

package/dist/tools/repo-map.d.ts

@@ -1,2 +1,10 @@
+import { loadPluginConfigWithMeta } from '../config/loader';
 import { createSwarmTool } from './create-tool';
+import { probeFreshness, updateGraphForFiles, writeFingerprint } from './repo-graph';
+export declare const _internals: {
+    loadPluginConfigWithMeta: typeof loadPluginConfigWithMeta;
+    probeFreshness: typeof probeFreshness;
+    updateGraphForFiles: typeof updateGraphForFiles;
+    writeFingerprint: typeof writeFingerprint;
+};
 export declare const repo_map: ReturnType<typeof createSwarmTool>;

package/dist/utils/path-security.d.ts

@@ -43,6 +43,28 @@ export declare function validateDirectory(directory: string): void;
  * both fallback branches keeps the comparison basis consistent whether
  * realpathSync succeeds or not, independent of incidental filesystem state.
  *
+ * Not-yet-existing targets (e.g. a file about to be created by an atomic
+ * write) are handled the same way: realpathSync on the full target throws
+ * ENOENT, so resolution falls back to `resolveNearestExistingCanonical`,
+ * which walks up to the nearest existing ancestor, resolves symlinks on
+ * that ancestor (and everything above it), and rejoins the not-yet-existing
+ * tail. Without this, a target under a workspace root that itself sits
+ * behind a symlink (e.g. macOS `/tmp` and `/var`, which are symlinks to
+ * `/private/tmp` and `/private/var`) would resolve to its unresolved literal
+ * path while the (already-existing) root resolves to its `/private/...`
+ * form, producing a spurious boundary-escape error even though the target
+ * is genuinely inside the root. See issue #1986.
+ *
+ * This also TIGHTENS containment versus the pre-#1986-fix behavior in one
+ * case: if `.swarm/` or any other ancestor between the target and the
+ * workspace root is itself a symlink/junction pointing outside the
+ * workspace, the old fallback (unresolved `path.resolve`) could let a
+ * not-yet-existing target through on its first write; the ancestor walk now
+ * resolves that symlinked ancestor and correctly throws. If a deployment
+ * relies on a symlinked `.swarm/` (or similar) pointing outside the
+ * workspace root, that setup will now be rejected — this is the intended,
+ * correct behavior, not a regression.
+ *
  * @param targetPath - The path to validate (absolute)
  * @param rootPath - The root directory boundary (absolute)
  * @throws Error if the resolved target escapes the root boundary

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-swarm",
-	"version": "7.135.4",
+	"version": "7.136.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",