@visulima/task-runner 1.0.0-alpha.8 → 1.0.0-alpha.9

package/dist/index.d.ts

@@ -1,5 +1,353 @@
 import { Readable, Writable } from 'node:stream';
 /**
+* Represents a file access recorded during task execution.
+*
+* Write-intent accesses (`"write"`) are emitted when a task opens a file
+* with `O_WRONLY`/`O_RDWR`/`O_CREAT`/`O_TRUNC` flags (strace) or calls
+* `writeFile`/`appendFile`/`unlink`/`rename` (preload script).
+* The orchestrator uses the overlap of reads and writes to the same
+* workspace path to detect self-modifying tasks and skip caching.
+*/
+interface FileAccess {
+  /** The absolute path of the file */
+  path: string;
+  /** The type of access */
+  type: "missing" | "read" | "readdir" | "stat" | "write";
+}
+/**
+* Result of tracking file accesses during a command execution.
+*/
+interface TrackingResult {
+  /** All file accesses recorded */
+  accesses: FileAccess[];
+  /** The command exit code */
+  code: number;
+  /** The command stdout + stderr output */
+  output: string;
+}
+/**
+* Tracks which files a child process accesses during execution.
+*
+* Uses `strace` on Linux to intercept syscalls (open, openat, stat, lstat, access, getdents).
+* Falls back to no tracking on unsupported platforms.
+*/
+declare class FileAccessTracker {
+  #private;
+  constructor(workspaceRoot: string, excludePatterns?: RegExp[]);
+  /**
+  * Returns true if file access tracking is supported on the current platform.
+  */
+  isSupported(): boolean;
+  /**
+  * Runs a command and tracks all file system accesses.
+  * On unsupported platforms, runs the command without tracking.
+  */
+  track(command: string, options?: {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+  }): Promise<TrackingResult>;
+  /**
+  * Kills all active child processes. Called on abort/signal to prevent orphans.
+  */
+  killAll(): void;
+}
+/**
+* Generates a preload script that can be used with NODE_OPTIONS to
+* track file accesses in Node.js child processes.
+*
+* This is an alternative to strace that works cross-platform for Node.js processes.
+*/
+declare const generatePreloadScript: (outputPath: string) => string;
+/**
+* Represents a stored fingerprint for a task execution.
+*/
+interface TaskFingerprint {
+  /** Hash of the command arguments */
+  commandHash: string;
+  /** Directory listings recorded during execution (path -> sorted entries) */
+  directoryListings: Record<string, string[]>;
+  /** Hashes of fingerprinted environment variables */
+  envHashes: Record<string, string>;
+  /** Content hashes of files that were read during execution */
+  fileHashes: Record<string, string>;
+  /** Paths of files that were probed but didn't exist (ENOENT) */
+  missingFiles: string[];
+  /**
+  * Workspace-relative paths that were both read **and** written
+  * during execution. Populated when the tracker emits
+  * {@link FileAccess} entries with `"write"` type. The orchestrator
+  * uses a non-empty value here to skip caching a self-modifying
+  * task, whose fingerprint would otherwise capture post-write state
+  * and trigger false cache hits.
+  */
+  modifiedInputs?: string[];
+}
+/**
+* Describes why a cache miss occurred.
+*/
+interface CacheMissReason {
+  currentHash?: string;
+  detail: string;
+  previousHash?: string;
+  type: "file-changed" | "file-created" | "file-deleted" | "directory-changed" | "env-changed" | "args-changed" | "no-fingerprint";
+}
+/**
+* Manages task fingerprints for auto-detection caching.
+*
+* Records which files a task accesses during execution, stores content
+* hashes, and on subsequent runs checks if any accessed file has changed.
+*/
+declare class FingerprintManager {
+  #private;
+  constructor(workspaceRoot: string);
+  createFingerprint(accesses: FileAccess[], command: string, args: Record<string, unknown>, envVariables: Record<string, string | undefined>, envPatterns?: string[], untrackedEnvVariables?: string[]): Promise<TaskFingerprint>;
+  /**
+  * Validates a stored fingerprint against the current state.
+  * Returns null if valid (cache hit), or an array of reasons (cache miss).
+  *
+  * Does NOT use the file hash cache — validation must see current disk state.
+  */
+  validate(fingerprint: TaskFingerprint): Promise<CacheMissReason[] | undefined>;
+  validateCommand(fingerprint: TaskFingerprint, command: string, args: Record<string, unknown>): CacheMissReason | undefined;
+  formatMissReasons(reasons: CacheMissReason[]): string;
+}
+/**
+* Content-Addressable Storage digest. Mirrors REAPI's `Digest` message:
+* a content hash and the size in bytes of the addressed blob.
+*
+* The hash is the lowercase hex sha256 of the blob's raw bytes. Size is
+* the byte length of those bytes. Together they uniquely identify a CAS
+* entry across HTTP and gRPC (REAPI) backends.
+*/
+interface CasDigest {
+  /** Lowercase hex sha256 of the blob bytes. */
+  hash: string;
+  /** Size of the blob bytes, in bytes. */
+  sizeBytes: number;
+}
+/**
+* Result of executing a single Action. Mirrors REAPI's `ActionResult`
+* shape, with a vis-specific `fingerprint` extension for auto-fingerprint
+* mode. Persisted as JSON locally; serialized as a protobuf over gRPC.
+*
+* Output paths are workspace-relative.
+*/
+interface ActionResult {
+  /** Process exit code from the cached run. */
+  exitCode: number;
+  /** Optional vis-specific fingerprint (auto-fingerprint mode). */
+  fingerprint?: TaskFingerprint;
+  /**
+  * Per-output-directory entries. The `treeDigest` points to a CAS
+  * blob that is itself a serialized REAPI `Tree` message describing
+  * the directory hierarchy and its file digests.
+  */
+  outputDirectories: ReadonlyArray<{
+    path: string;
+    treeDigest: CasDigest;
+  }>;
+  /** Per-output-file entries. Workspace-relative paths. */
+  outputFiles: ReadonlyArray<{
+    digest: CasDigest;
+    isExecutable: boolean;
+    path: string;
+  }>;
+  /**
+  * CAS digest of the captured stdout/stderr stream. Optional because
+  * tasks with no output emit nothing. Most tasks emit at least
+  * "Done in Xs", so dedup across tasks is real.
+  */
+  stdoutDigest?: CasDigest;
+}
+/**
+* Lazy handle for a CAS blob. Backends call `open()` only when they're
+* ready to stream the bytes — keeps memory flat for multi-hundred-MB
+* artifacts and avoids buffering blobs the server reports as already
+* present (REAPI `FindMissingBlobs`).
+*/
+interface BlobSource {
+  digest: CasDigest;
+  open: () => Promise<NodeJS.ReadableStream>;
+}
+/**
+* Canonical cache-mode enum, replacing the original `read` / `write`
+* boolean pair. One flag, three values, no implicit env-detection.
+*
+* - `"read"`: Pull cache hits, never push. Default for local dev when
+*   developers shouldn't poison the shared cache.
+* - `"write"`: Push results, never read. Useful for refill / warm-up
+*   jobs that should always re-execute and re-upload.
+* - `"readwrite"`: Both. Default for CI.
+*/
+type CacheMode = "read" | "readwrite" | "write";
+/**
+* Compression algorithm used for artifact tarballs on the wire.
+*
+* - `"gzip"` (default): tar+gzip, matches Turborepo's protocol format
+*   and stays interop-safe with existing remote cache servers.
+* - `"brotli"`: tar + Node brotli (BROTLI_MODE_TEXT, quality 4) — a
+*   solid ratio/speed trade-off for source-tree tarballs. Both upload
+*   and download sides must agree; switching invalidates existing
+*   remote entries (they will simply re-populate on next run).
+*
+* HTTP-only — REAPI servers negotiate compression via the
+* `Capabilities` RPC + `grpc-encoding` metadata on the wire.
+*/
+type RemoteCacheCompression = "brotli" | "gzip";
+/**
+* HMAC signing configuration for the HTTP backend.
+*
+* When set, every upload carries an `X-Artifact-Signature` header
+* containing the HMAC-SHA256 digest of `hash | body`. On download,
+* the client recomputes the HMAC and rejects any artifact whose
+* signature doesn't match (constant-time comparison). REAPI servers
+* do not consume this — REAPI integrity rides on sha256
+* content-addressing instead.
+*/
+interface RemoteCacheSigning {
+  /** Shared secret. Must be at least 16 characters. */
+  secret: string;
+  /**
+  * Reject downloads whose signature doesn't match or is missing.
+  * Set to `true` once every upload on your server is signed.
+  * @default false
+  */
+  verifyOnDownload?: boolean;
+}
+/**
+* Canonical remote-cache configuration consumed by
+* `createRemoteCacheBackend`. Both `HttpRemoteCache` and
+* `ReapiRemoteCache` accept this shape directly — backend-specific
+* fields (e.g. `signing`, `compression` for HTTP; `bearerToken`,
+* `instanceName` for REAPI) are read by the corresponding constructor
+* and ignored by the other.
+*
+* Living in `backends/types.ts` rather than each backend file keeps a
+* single source of truth for `TaskRunnerOptions.remoteCache` and the
+* `vis-config` typed surface.
+*/
+interface RemoteCacheOptions {
+  /**
+  * Opt out of the REAPI safety check that refuses to send a bearer
+  * token over cleartext gRPC. Required only when the connection
+  * terminates inside a trusted boundary (loopback dev cache, mesh
+  * mTLS sidecar that strips/re-encrypts on the next hop). Default
+  * `false` — production callers should reach for `grpcs://` first.
+  *
+  * REAPI-only.
+  */
+  allowInsecureBearer?: boolean;
+  /**
+  * Wire-protocol selector. `"http"` is the Turborepo-compatible
+  * single-tarball cache; `"reapi"` switches to the Bazel Remote
+  * Execution API gRPC client, unlocking `bazel-remote`,
+  * BuildBuddy, BuildBarn, EngFlow as drop-in backends.
+  * @default "http"
+  */
+  backend?: "http" | "reapi";
+  /**
+  * Bearer token sent in REAPI's `authorization: Bearer {token}`
+  * gRPC metadata header. REAPI-only — HTTP backend uses `token`.
+  */
+  bearerToken?: string;
+  /** HTTP-only: tarball compression on the wire. @default "gzip" */
+  compression?: RemoteCacheCompression;
+  /**
+  * REAPI-only `instance_name` for multi-tenant servers (a single
+  * gRPC endpoint can host multiple logical caches keyed on the
+  * `instance_name` prefix).
+  */
+  instanceName?: string;
+  /**
+  * Local CAS root used by the per-blob {@link RemoteCacheBackend}
+  * methods. The HTTP wire format is still single-tarball; on
+  * retrieve the bridge extracts blobs into this root so a follow-up
+  * `fetchBlob` is just a local read.
+  */
+  localCasRoot?: string;
+  /**
+  * Canonical cache mode flag.
+  *
+  * - `"read"`: Pull cache hits, never push. Sensible default for
+  *   local dev so a developer doesn't poison the shared cache while
+  *   their workspace is dirty.
+  * - `"write"`: Push results, never read. Useful for refill /
+  *   warm-up jobs that should always re-execute and re-upload.
+  * - `"readwrite"`: Both. Default for CI.
+  * @default "readwrite"
+  */
+  mode?: CacheMode;
+  /**
+  * Called when a fire-and-forget upload fails. Uploads are
+  * non-blocking, so without this hook errors are silently dropped.
+  * Provide it to log or report upload failures.
+  */
+  onUploadError?: (hash: string, error: unknown) => void;
+  /** HTTP-only: HMAC-SHA256 signing for upload integrity. */
+  signing?: RemoteCacheSigning;
+  /** Team / namespace for cache isolation. */
+  teamId?: string;
+  /** Per-call request timeout in milliseconds. @default 30000 */
+  timeout?: number;
+  /**
+  * HTTP authentication token sent as `Authorization: Bearer …`.
+  * For REAPI, use `bearerToken` instead — same wire mechanic, but
+  * a separate field so REAPI's cleartext-bearer guard can distinguish
+  * "user explicitly opted into a gRPC token" from "user set HTTP
+  * auth and accidentally selected the REAPI backend".
+  */
+  token?: string;
+  /**
+  * Cache server URL.
+  *
+  * - HTTP: `https://cache.example.com`
+  * - REAPI: `grpcs://host:port` (TLS, recommended) or `grpc://host:port`
+  *   (cleartext — bearer tokens are refused unless `allowInsecureBearer`).
+  */
+  url: string;
+}
+/**
+* Pluggable backend boundary for the remote cache. Implementations:
+* - `HttpRemoteCache`: Turborepo wire-protocol-compatible HTTP cache.
+*   Bridges the single-tarball protocol to per-blob semantics by
+*   synthesizing an `ActionResult` from the extracted tarball contents.
+* - `ReapiRemoteCache`: Bazel Remote Execution API gRPC client.
+*   Speaks `ActionCache` + `ContentAddressableStorage` services
+*   natively, unlocking bazel-remote / BuildBuddy / BuildBarn / EngFlow.
+*/
+interface RemoteCacheBackend {
+  /**
+  * Release any persistent resources held by the backend (gRPC
+  * channels, HTTP keep-alive agents). Safe to call multiple times
+  * and safe to call when no work has been issued. Implementations
+  * must not throw — close failures are best-effort.
+  */
+  close: () => Promise<void>;
+  /**
+  * HEAD-equivalent existence check. REAPI: `GetActionResult` with
+  * `inline_*` fields disabled. HTTP: `HEAD /v8/artifacts/{hash}`.
+  */
+  containsAction: (actionDigest: CasDigest) => Promise<boolean>;
+  /**
+  * Stream a single CAS blob to disk. Returns `true` on success.
+  * Used to materialize output files referenced by an `ActionResult`.
+  */
+  fetchBlob: (digest: CasDigest, destinationPath: string) => Promise<boolean>;
+  /**
+  * Look up an Action's cached result. Resolves to `null` on miss.
+  * Implementations are responsible for fetching any CAS blobs the
+  * caller needs to materialize the outputs (or returning enough
+  * metadata for the caller to fetch them via `fetchBlob`).
+  */
+  retrieveAction: (actionDigest: CasDigest) => Promise<ActionResult | null>;
+  /**
+  * Persist an `ActionResult` and any blobs it references. Backends
+  * must enforce blobs-before-AC ordering on the wire so a partial
+  * failure cannot leave a cached result pointing at missing bytes.
+  */
+  storeAction: (actionDigest: CasDigest, result: ActionResult, blobs: ReadonlyArray<BlobSource>) => Promise<boolean>;
+}
+/**
 * A predicate clause that can match a single value, a list of values
 * (any-of), or — for env vars only — a `{ name, equals?, exists? }`
 * triplet. `not.*` mirrors of every clause provide a negative form
@@ -145,6 +493,22 @@ interface Task {
   always?: boolean;
   /** Whether this task is eligible for caching */
   cache?: boolean;
+  /**
+  * When `false`, exit-0 runs whose output matched any
+  * {@link Task.warningPattern} are NOT written to the cache. Defaults
+  * to `true` — warnings are recorded on the result but don't suppress
+  * caching, matching the rushstack#1402 / Theme P expectation that a
+  * succeeded-with-warnings build is still incremental on the next run.
+  *
+  * Carried over from {@link TargetConfiguration.cacheOnWarning}.
+  */
+  cacheOnWarning?: boolean;
+  /**
+  * Per-task overrides for cache restore fidelity. Carried over
+  * from {@link TargetConfiguration.cacheRestore}. When absent, the
+  * runner uses faithful defaults (mtime + mode preserved).
+  */
+  cacheRestore?: CacheRestoreOptions;
   /** Hash of the task inputs for caching */
   hash?: string;
   /** Detailed hash information */
@@ -172,6 +536,16 @@ interface Task {
   /** The target this task executes */
   target: TaskTarget;
   /**
+  * Regex strings (JavaScript flavor, anchored as the user writes them)
+  * that classify a successful task's terminal output as "succeeded
+  * with warnings". When any pattern matches, {@link TaskResult.hadWarnings}
+  * is set on the result. Combined with {@link Task.cacheOnWarning} this
+  * controls whether the run still seeds the cache.
+  *
+  * Carried over from {@link TargetConfiguration.warningPattern}.
+  */
+  warningPattern?: string[];
+  /**
   * Predicate that gates execution. Evaluated by the orchestrator
   * just before the task is launched; tasks whose `when` returns
   * `false` are marked `"skipped"` without ever invoking the
@@ -224,6 +598,14 @@ interface TaskResult {
   /** The end time of the task */
   endTime?: number;
   /**
+  * Set when the task exited 0 and at least one configured
+  * {@link Task.warningPattern} matched the terminal output. Surfaced
+  * to lifecycle reporters and the run summary so users can see that
+  * a "green" build still emitted warnings, and gates the optional
+  * `cacheOnWarning: false` cache-suppression path.
+  */
+  hadWarnings?: boolean;
+  /**
   * Set when the task modified one or more of its own tracked input
   * files during execution. Caching is skipped in this case — the
   * fingerprint captured before the run would mismatch the post-run
@@ -268,6 +650,30 @@ interface ProjectConfiguration {
   targets?: Record<string, TargetConfiguration>;
 }
 /**
+* Per-target controls over how the cache rehydrates outputs.
+*
+* Both default to `true` — faithful restoration is the contract:
+* cached outputs come back with the same mtime and mode bits the
+* task originally produced. Override only when downstream tooling
+* needs the opposite (e.g. a bundler that uses "newer than source"
+* heuristics, or a CI step that compares mtimes against a deploy
+* artifact).
+*/
+interface CacheRestoreOptions {
+  /**
+  * Restore each file's modification time from the captured tar
+  * header (second precision). When `false`, restored files take
+  * the current wall-clock time, matching the legacy behaviour.
+  */
+  preserveMtime?: boolean;
+  /**
+  * Restore each file's POSIX mode bits (rwx triplets, low 12
+  * bits). When `false`, restored files take the process umask.
+  * Only meaningful on POSIX hosts; Windows ignores tar mode.
+  */
+  preservePerms?: boolean;
+}
+/**
 * Configuration for a target within a project.
 */
 interface TargetConfiguration {
@@ -281,6 +687,22 @@ interface TargetConfiguration {
   always?: boolean;
   /** Whether this target is cacheable */
   cache?: boolean;
+  /**
+  * When `false`, exit-0 runs whose terminal output matched any
+  * {@link TargetConfiguration.warningPattern} are not seeded into the
+  * cache. Defaults to `true` — warnings are surfaced on the result
+  * (`hadWarnings: true`) but caching still happens, matching the
+  * "succeeded with warnings is incremental" behaviour rush, lage and
+  * wireit users have repeatedly asked for.
+  */
+  cacheOnWarning?: boolean;
+  /**
+  * Fine-grained controls over how cached outputs are rehydrated.
+  * See {@link CacheRestoreOptions}. Both fields default to `true`
+  * (faithful restore); flip individually when downstream tooling
+  * needs the legacy "now"-stamped behaviour.
+  */
+  cacheRestore?: CacheRestoreOptions;
   /** The command to run (alternative to executor) */
   command?: string;
   /** Named configurations (e.g., "production", "development") */
@@ -298,6 +720,19 @@ interface TargetConfiguration {
   /** Whether this target supports parallel execution */
   parallelism?: boolean;
   /**
+  * Regex source string(s) that mark a successful task as having
+  * emitted warnings. The orchestrator scans the task's combined
+  * terminal output after a 0-exit and, on first match, sets
+  * `hadWarnings` on the result. Combine with `cacheOnWarning: false`
+  * to skip caching for warning-tainted runs. Both bare strings and
+  * arrays are accepted; arrays are tested in order.
+  *
+  *   ```ts
+  *   warningPattern: ["\\bwarning\\b", "TS\\d{4}"]
+  *   ```
+  */
+  warningPattern?: string | string[];
+  /**
   * Predicate that gates execution. When the condition evaluates
   * to `false` for the current environment, the task is skipped
   * (marked `"skipped"`, not failed). Combine with `os`, `env`,
@@ -617,27 +1052,11 @@ interface TaskRunnerOptions {
   parallel?: number | boolean;
   /**
   * Remote cache configuration.
-  * When configured, the task runner will check the remote cache
-  * after a local cache miss, and upload results after execution.
-  */
-  remoteCache?: {
-    /**
-    * Called when a fire-and-forget upload fails.
-    * Since uploads are non-blocking, errors are silently swallowed by default.
-    * Provide this callback to log or report upload failures.
-    */
-    onUploadError?: (hash: string, error: unknown) => void;
-    /** Enable remote reads (default: true) */
-    read?: boolean;
-    /** Team/namespace for cache isolation */
-    teamId?: string;
-    /** Authentication token */
-    token?: string;
-    /** Remote cache server URL */
-    url: string;
-    /** Enable remote writes (default: true) */
-    write?: boolean;
-  };
+  * When configured, the task runner checks the remote cache after a
+  * local miss and uploads results after execution. See
+  * {@link RemoteCacheOptions} for the full HTTP and REAPI surface.
+  */
+  remoteCache?: RemoteCacheOptions;
   /** Whether to skip cache reads */
   skipNxCache?: boolean;
   /**
@@ -974,116 +1393,174 @@ declare const getAffectedProjects: (options: AffectedOptions) => Promise<Affecte
 */
 declare const filterAffectedTasks: (taskIds: string[], affectedProjects: Set<string>) => string[];
 /**
-* Represents a file access recorded during task execution.
+* Resolves the canonical {@link CacheMode}. `mode` defaults to
+* `"readwrite"` when unset — the safe choice for CI and the most
+* common config in dev. Kept as a separate helper so vis-side code
+* (CLI flag merge, doctor probes) can reuse the resolution rule.
+*/
+declare const resolveCacheMode: (options: {
+  mode?: CacheMode;
+}) => CacheMode;
+/**
+* Construct the configured remote cache backend. Selects between the
+* Turborepo-compatible HTTP client and the Bazel REAPI gRPC client
+* via `options.backend`.
+*/
+declare const createRemoteCacheBackend: (options: RemoteCacheOptions) => RemoteCacheBackend;
+/**
+* Derive a stable {@link CasDigest} from the orchestrator's task hash
+* (xxh3-128, 32 hex chars). REAPI servers reject non-sha256 digests on
+* the wire, so we sha256 a namespaced key. The HTTP backend uses the
+* resulting digest as the artifact URL component.
 *
-* Write-intent accesses (`"write"`) are emitted when a task opens a file
-* with `O_WRONLY`/`O_RDWR`/`O_CREAT`/`O_TRUNC` flags (strace) or calls
-* `writeFile`/`appendFile`/`unlink`/`rename` (preload script).
-* The orchestrator uses the overlap of reads and writes to the same
-* workspace path to detect self-modifying tasks and skip caching.
+* `sizeBytes` is set to `0` because this digest identifies an *action*
+* (an `ActionResult` keyed in the AC), not a stored CAS blob. REAPI
+* `Digest` size_bytes only carries meaning for blobs in the CAS — for
+* action keys it's ignored by the server. Setting it to the byte
+* length of the prehash key would be semantically wrong: the server
+* would believe a blob of that exact length exists at this hash, and
+* a downstream `BatchReadBlobs` against this digest would mismatch.
 */
-interface FileAccess {
-  /** The absolute path of the file */
-  path: string;
-  /** The type of access */
-  type: "missing" | "read" | "readdir" | "stat" | "write";
-}
+declare const actionDigestForTaskHash: (taskHash: string) => CasDigest;
 /**
-* Result of tracking file accesses during a command execution.
+* Probe whether a cached entry exists on the remote backend, keyed by
+* the orchestrator's task hash. Resolves `false` on any wire failure —
+* the orchestrator treats existence checks as best-effort.
 */
-interface TrackingResult {
-  /** All file accesses recorded */
-  accesses: FileAccess[];
-  /** The command exit code */
-  code: number;
-  /** The command stdout + stderr output */
-  output: string;
-}
+declare const containsByTaskHash: (backend: RemoteCacheBackend, taskHash: string) => Promise<boolean>;
 /**
-* Tracks which files a child process accesses during execution.
+* Download the cached entry for `taskHash` and extract it into
+* `{localCacheDirectory}/{taskHash}/`. Returns `true` only when the
+* directory has been fully populated; partial-extract failures clean
+* up after themselves so the local cache never observes a half-populated
+* entry.
+*/
+declare const retrieveByTaskHash: (backend: RemoteCacheBackend, taskHash: string, localCacheDirectory: string) => Promise<boolean>;
+/**
+* Tar `{localCacheDirectory}/{taskHash}/` and upload as a single CAS
+* blob via {@link RemoteCacheBackend.storeAction}. Skips the upload
+* unless `.commit` is present so we never publish a half-written entry.
 *
-* Uses `strace` on Linux to intercept syscalls (open, openat, stat, lstat, access, getdents).
-* Falls back to no tracking on unsupported platforms.
+* The lazy {@link BlobSource.open} returns a fresh `createReadStream`
+* each call so REAPI's `FindMissingBlobs` → `BatchUpdateBlobs` →
+* fallback `Write` flow can re-read the file as many times as it needs
+* to without requiring the bridge to buffer the bytes in memory.
+*
+* Bridge-local failures (`createTarGz`, `digestFile`) are surfaced
+* through `onUploadError` when provided, then swallowed so the
+* fire-and-forget call site stays non-throwing. A missing `.commit`
+* marker is *not* an error — it's the normal "skip this upload" path.
 */
-declare class FileAccessTracker {
+declare const storeByTaskHash: (backend: RemoteCacheBackend, taskHash: string, localCacheDirectory: string, onUploadError?: (hash: string, error: unknown) => void) => Promise<boolean>;
+/**
+* HTTP-based remote cache compatible with the Turborepo remote cache protocol.
+*
+* Protocol:
+* - GET  /v8/artifacts/{hash}?teamId={team}  -> retrieve cached artifact (gzipped tar)
+* - PUT  /v8/artifacts/{hash}?teamId={team}  -> store artifact
+* - POST /v8/artifacts/events                -> analytics (optional)
+*
+* Authentication via `Authorization: Bearer {token}` header.
+*
+* The cache entry is a gzipped tarball containing the cache directory contents
+* (code, terminalOutput, fingerprint.json, outputs/, .commit).
+*/
+declare class HttpRemoteCache implements RemoteCacheBackend {
   #private;
-  constructor(workspaceRoot: string, excludePatterns?: RegExp[]);
+  constructor(options: RemoteCacheOptions);
   /**
-  * Returns true if file access tracking is supported on the current platform.
+  * No-op. The HTTP backend uses Node's global `fetch`, which has no
+  * persistent connection to release. Implemented to satisfy the
+  * {@link RemoteCacheBackend.close} contract uniformly.
   */
-  isSupported(): boolean;
+  close(): Promise<void>;
   /**
-  * Runs a command and tracks all file system accesses.
-  * On unsupported platforms, runs the command without tracking.
+  * {@link RemoteCacheBackend.containsAction}: HEAD on the artifact URL.
+  * Resolves `false` on any wire failure — existence checks are best
+  * effort and never block the caller.
   */
-  track(command: string, options?: {
-    cwd?: string;
-    env?: Record<string, string | undefined>;
-  }): Promise<TrackingResult>;
+  containsAction(actionDigest: CasDigest): Promise<boolean>;
   /**
-  * Kills all active child processes. Called on abort/signal to prevent orphans.
+  * {@link RemoteCacheBackend.fetchBlob}: streams a blob out of the
+  * local CAS that was hydrated by a previous {@link retrieveAction}
+  * call. The HTTP wire ships one tarball per action, so per-blob
+  * fetches are local-only — there's no remote endpoint to call.
   */
-  killAll(): void;
-}
-/**
-* Generates a preload script that can be used with NODE_OPTIONS to
-* track file accesses in Node.js child processes.
-*
-* This is an alternative to strace that works cross-platform for Node.js processes.
-*/
-declare const generatePreloadScript: (outputPath: string) => string;
-/**
-* Represents a stored fingerprint for a task execution.
-*/
-interface TaskFingerprint {
-  /** Hash of the command arguments */
-  commandHash: string;
-  /** Directory listings recorded during execution (path -> sorted entries) */
-  directoryListings: Record<string, string[]>;
-  /** Hashes of fingerprinted environment variables */
-  envHashes: Record<string, string>;
-  /** Content hashes of files that were read during execution */
-  fileHashes: Record<string, string>;
-  /** Paths of files that were probed but didn't exist (ENOENT) */
-  missingFiles: string[];
+  fetchBlob(digest: CasDigest, destinationPath: string): Promise<boolean>;
   /**
-  * Workspace-relative paths that were both read **and** written
-  * during execution. Populated when the tracker emits
-  * {@link FileAccess} entries with `"write"` type. The orchestrator
-  * uses a non-empty value here to skip caching a self-modifying
-  * task, whose fingerprint would otherwise capture post-write state
-  * and trigger false cache hits.
+  * {@link RemoteCacheBackend.retrieveAction}: GETs the artifact at
+  * `/v8/artifacts/{actionDigest.hash}`, ingests the response bytes
+  * as a single CAS blob in the local store, and synthesises an
+  * {@link ActionResult} that points at that blob. Resolves to `null`
+  * on a 404 / signature mismatch / missing local CAS root.
   */
-  modifiedInputs?: string[];
+  retrieveAction(actionDigest: CasDigest): Promise<ActionResult | null>;
+  /**
+  * {@link RemoteCacheBackend.storeAction}: takes the single blob
+  * referenced by `result.outputFiles[0]`, streams its bytes as the
+  * PUT body, and signs the body when a signing secret is configured.
+  * Per-digest in-flight dedup means parallel writers racing on the
+  * same action upload exactly once.
+  */
+  storeAction(actionDigest: CasDigest, result: ActionResult, blobs: ReadonlyArray<BlobSource>): Promise<boolean>;
 }
 /**
-* Describes why a cache miss occurred.
+* REAPI-specific options accepted by {@link ReapiRemoteCache}. A type
+* alias rather than its own interface so callers can hand the same
+* object to the backend factory or to the constructor directly without
+* rewriting field names. HTTP-only fields (`signing`, `compression`)
+* are silently ignored here.
 */
-interface CacheMissReason {
-  currentHash?: string;
-  detail: string;
-  previousHash?: string;
-  type: "file-changed" | "file-created" | "file-deleted" | "directory-changed" | "env-changed" | "args-changed" | "no-fingerprint";
-}
+type ReapiRemoteCacheOptions = RemoteCacheOptions;
 /**
-* Manages task fingerprints for auto-detection caching.
+* Bazel REAPI gRPC backend. Implements {@link RemoteCacheBackend} over
+* `ContentAddressableStorage` + `ActionCache` + `Capabilities` +
+* `google.bytestream.ByteStream`. Battle-tested REAPI servers
+* (`bazel-remote`, BuildBuddy, BuildBarn, EngFlow) become drop-in
+* backends with no per-server adapter.
 *
-* Records which files a task accesses during execution, stores content
-* hashes, and on subsequent runs checks if any accessed file has changed.
+* Wire flow:
+*   - retrieveAction → GetActionResult → fetchBlob (BatchReadBlobs|Read)
+*   - storeAction    → FindMissingBlobs → BatchUpdateBlobs|Write → UpdateActionResult
 */
-declare class FingerprintManager {
+declare class ReapiRemoteCache implements RemoteCacheBackend {
   #private;
-  constructor(workspaceRoot: string);
-  createFingerprint(accesses: FileAccess[], command: string, args: Record<string, unknown>, envVariables: Record<string, string | undefined>, envPatterns?: string[], untrackedEnvVariables?: string[]): Promise<TaskFingerprint>;
+  constructor(options: ReapiRemoteCacheOptions);
   /**
-  * Validates a stored fingerprint against the current state.
-  * Returns null if valid (cache hit), or an array of reasons (cache miss).
+  * Close all gRPC channels held by this backend. Idempotent — safe
+  * to call multiple times, and safe to call before any RPC was
+  * issued. If `#getClients` is currently in flight we await its
+  * resolution so the underlying channels are observable to close.
+  */
+  close(): Promise<void>;
+  /**
+  * Diagnostic probe — fetches the server's `Capabilities` RPC response
+  * (or the cached value, if a previous call already negotiated). Used
+  * by `vis cache doctor` to surface what the server advertises without
+  * forcing the operator to issue a real CAS RPC.
   *
-  * Does NOT use the file hash cache — validation must see current disk state.
+  * Bypasses the read/write mode gate intentionally: a probe must work
+  * even on a cache configured `mode: "write"` so the operator can
+  * verify the connection regardless of how the runner uses it.
   */
-  validate(fingerprint: TaskFingerprint): Promise<CacheMissReason[] | undefined>;
-  validateCommand(fingerprint: TaskFingerprint, command: string, args: Record<string, unknown>): CacheMissReason | undefined;
-  formatMissReasons(reasons: CacheMissReason[]): string;
+  probeCapabilities(): Promise<{
+    digestFunctions: ReadonlyArray<string>;
+    maxBatchTotalSizeBytes: number;
+  }>;
+  containsAction(actionDigest: CasDigest): Promise<boolean>;
+  fetchBlob(digest: CasDigest, destinationPath: string): Promise<boolean>;
+  retrieveAction(actionDigest: CasDigest): Promise<ActionResult | null>;
+  storeAction(actionDigest: CasDigest, result: ActionResult, blobs: ReadonlyArray<BlobSource>): Promise<boolean>;
+}
+/**
+* Per-call control over restore fidelity. Both default to `true` —
+* the cache's job is to recreate exactly what was captured, and any
+* deviation is opt-in. Callers (e.g. vis target config) can flip
+* either off when downstream tooling needs a "fresh" mtime/mode.
+*/
+interface ExtractOptions {
+  preserveMtime?: boolean;
+  preservePerms?: boolean;
 }
 /**
 * Represents a cached task result.
@@ -1166,6 +1643,40 @@ declare class Cache {
   */
   get cacheDirectory(): string;
   /**
+  * Root for v2 CAS-shaped reads/writes. Backend implementations
+  * (HTTP today, REAPI gRPC next) take this path so they can
+  * hydrate fetched blobs into the same CAS the local cache reads
+  * from. Equal to {@link cacheDirectory} — `v2/` lives under that.
+  */
+  get casRoot(): string;
+  /**
+  * Read a v2 {@link ActionResult} by action digest. Resolves to
+  * `null` on miss. The orchestrator is expected to follow up with
+  * {@link materializeOutputs} to place the referenced blobs into
+  * the workspace.
+  */
+  getActionResult(actionDigest: CasDigest): Promise<ActionResult | null>;
+  /**
+  * Look up an action digest by the legacy task hash. Returns
+  * `null` when the bridge file isn't present — caller falls
+  * through to the legacy `&lt;hash>/` layout (or executes the task).
+  */
+  resolveActionDigestForTaskHash(taskHash: string): Promise<string | null>;
+  /**
+  * Persist a v2 entry: writes the AC JSON, copies referenced
+  * blobs into the CAS via the lazy {@link BlobSource} handles,
+  * and binds the task hash → action digest redirect last so a
+  * partial failure can't surface a half-written entry.
+  */
+  putActionResult(taskHash: string, actionDigest: CasDigest, result: ActionResult, blobs: ReadonlyArray<BlobSource>): Promise<void>;
+  /**
+  * Materialize an action's outputs into the workspace. Streams
+  * each referenced blob from the local CAS to its workspace path.
+  * Returns `false` when any blob is missing — caller treats that
+  * as a cache miss and re-executes.
+  */
+  materializeOutputs(result: ActionResult, workspaceRoot: string): Promise<boolean>;
+  /**
   * Retrieves a cached result for the given task hash.
   * Returns undefined if no valid cache entry exists.
   */
@@ -1196,7 +1707,7 @@ declare class Cache {
   * extracted staging become the set of swap roots. Still accepted
   * for backward compat.
   */
-  restoreOutputs(hash: string, _outputs?: OutputSpec[]): Promise<boolean>;
+  restoreOutputs(hash: string, _outputs?: OutputSpec[], options?: ExtractOptions): Promise<boolean>;
   /**
   * Retrieves the most recent cached result for a task by its ID.
   * Used in auto-fingerprint mode where the hash is derived from
@@ -1220,6 +1731,91 @@ declare class Cache {
   clear(): Promise<void>;
 }
 /**
+* Compute the sha256 digest of a buffer's bytes. Lowercase hex, matching
+* REAPI's `Digest.hash` format. Used for synchronous payloads (small
+* AC metadata, action proto bytes) where streaming isn't worth it.
+*/
+declare const digestBuffer: (bytes: Buffer) => CasDigest;
+/**
+* Compute the sha256 digest of a file's contents by streaming. Avoids
+* loading multi-hundred-MB outputs into memory. Returns `undefined`
+* when the file can't be opened (caller decides whether that's fatal).
+*/
+declare const digestFile: (filePath: string) => Promise<CasDigest | undefined>;
+/**
+* v2 layout root inside the cache directory. Coexists with the legacy
+* `&lt;cacheDir>/&lt;hash>/` entries until the migration window closes.
+*/
+declare const V2_ROOT = "v2";
+/**
+* Sub-roots under `v2/`. CAS holds raw blob bytes, AC holds JSON
+* `ActionResult` entries, the task-hash index bridges xxh3 task hashes
+* to sha256 action digests, tmp stages atomic renames.
+*/
+declare const V2_CAS = "cas";
+declare const V2_AC = "ac";
+declare const V2_INDEX = "task-hash-index";
+declare const V2_TMP = "tmp";
+/**
+* Resolve the on-disk path for a CAS blob. `&lt;root>/v2/cas/&lt;aa>/&lt;hash>`.
+*/
+declare const casBlobPath: (root: string, hash: string) => string;
+/**
+* Resolve the on-disk path for an Action Cache entry. AC entries are
+* JSON, suffix kept off-disk to match REAPI semantics (the action
+* digest is the file name).
+*/
+declare const acEntryPath: (root: string, actionHash: string) => string;
+/**
+* Resolve the path for the task-hash → action-digest redirect. 64-byte
+* file containing the action digest hex; lets `Cache.get(taskHash)`
+* jump to the AC entry without recomputing the action proto.
+*/
+declare const taskHashIndexPath: (root: string, taskHash: string) => string;
+/**
+* Returns `true` if the CAS blob already exists on disk for the given
+* digest. Caller uses this for `FindMissingBlobs`-style elision and to
+* avoid re-uploading bytes the local cache already holds.
+*/
+declare const containsBlob: (root: string, digest: CasDigest) => Promise<boolean>;
+/**
+* Stream a CAS blob from a source path into the store. The blob is
+* staged under `v2/tmp/` and renamed into `v2/cas/&lt;aa>/&lt;digest>` after
+* the bytes land. Idempotent: a concurrent writer racing on the same
+* digest results in two POSIX renames over byte-identical content,
+* which is atomic per POSIX. On Windows we treat `EEXIST` as success.
+*
+* `digest.hash` is trusted — the caller is responsible for computing
+* the sha256 of the source file first. Re-hashing here would double
+* the IO on every put.
+*/
+declare const putBlobFromFile: (root: string, digest: CasDigest, sourcePath: string) => Promise<void>;
+/**
+* Same as {@link putBlobFromFile} but for in-memory bytes. Used for
+* tiny payloads (the AC entry's stdout digest, tree protos) where
+* streaming would be more code than it's worth.
+*/
+declare const putBlobFromBytes: (root: string, digest: CasDigest, bytes: Buffer) => Promise<void>;
+/**
+* Materialize a CAS blob to a destination path. Streams; safe for
+* large outputs. Returns `false` if the blob isn't in the local store.
+*/
+declare const fetchBlobToFile: (root: string, digest: CasDigest, destinationPath: string) => Promise<boolean>;
+/**
+* Verify a blob's bytes match its expected digest. Used during legacy
+* → v2 migration where we trust nothing — sha256 every staged file
+* before the rename so a bit-flipped legacy artifact doesn't poison
+* the new CAS.
+*/
+declare const verifyBlob: (filePath: string, expected: CasDigest) => Promise<boolean>;
+/**
+* Bump mtime/atime on a blob. Drives mark-and-sweep GC: the sweeper
+* evicts blobs whose mtime is older than `maxCacheAge` AND not
+* referenced by any AC entry. Touching on hit means LRU tracks real
+* usage rather than write-time.
+*/
+declare const touchBlob: (root: string, digest: CasDigest) => Promise<void>;
+/**
 * Summary of a single task execution.
 */
 interface TaskSummary {
@@ -2047,110 +2643,56 @@ declare const isNativeAvailable: () => boolean;
 */
 declare const resolveOutputs: (workspaceRoot: string, outputs: OutputSpec[] | undefined, autoWrites?: ReadonlyArray<string>) => Promise<string[]>;
 /**
-* Enforces project dependency constraints on a project graph.
-* @param projectGraph The workspace project graph to validate.
-* @param constraints The constraint rules to enforce.
-* @returns Array of violations found. Empty means all constraints pass.
-*/
-declare const enforceProjectConstraints: (projectGraph: ProjectGraph, constraints: ConstraintsConfig) => ConstraintViolation[];
-/**
-* Compression algorithm used for artifact tarballs on the wire.
-* - `"gzip"` (default): tar+gzip, matches Turborepo's protocol format
-*   and stays interop-safe with existing remote cache servers.
-* - `"brotli"`: tar + Node brotli (BROTLI_MODE_TEXT, quality 4) — a
-*   solid ratio/speed trade-off for source-tree tarballs. Both upload
-*   and download sides must agree; switching invalidates existing
-*   remote entries (they will simply re-populate on next run).
+* URI schemes recognized by {@link parseInputUri}. Each maps to one of the
+* existing structured `InputDefinition` shapes — the URI form is a sugar
+* over the object form so the same hash semantics apply unchanged.
+*
+* - `file://&lt;path>` and `glob://&lt;pattern>` → {@link FileSetInput}
+*   (both produce a fileset; the split is purely documentary so a reader
+*   can tell at a glance whether the author meant a single path or a glob).
+* - `env://&lt;NAME>` → {@link EnvironmentInput}.
+* - `func://&lt;command>` → {@link RuntimeInput} (runtime command output).
+* - `dep://&lt;a,b,c>` → {@link ExternalDependencyInput} (comma-separated names).
+*
+* `{projectRoot}` and `{workspaceRoot}` tokens are honored inside `file://`
+* and `glob://` bodies, matching the bare-string form. Negation works for
+* filesets only (`!file://...`, `!glob://...`); attempting to negate the
+* other schemes throws because there is no semantic for "not this env var".
 */
-type RemoteCacheCompression = "brotli" | "gzip";
+declare const INPUT_URI_SCHEMES: readonly ["file", "glob", "env", "func", "dep"];
+type InputUriScheme = (typeof INPUT_URI_SCHEMES)[number];
 /**
-* HMAC signing configuration for cache integrity.
+* Thrown when a string carries a URI-shaped prefix but the scheme is
+* unrecognized or the body violates a scheme-specific constraint
+* (e.g. negating a non-fileset scheme).
 *
-* When set, every upload carries an `X-Artifact-Signature` header
-* containing the HMAC-SHA256 digest of `hash | body`. On download,
-* the client recomputes the HMAC and rejects any artifact whose
-* signature doesn't match using a constant-time comparison.
-*
-* Prevents cache poisoning in shared team environments where a
-* compromised cache server (or a MITM) could inject malicious
-* artifacts. Unsigned entries (written before signing was enabled)
-* are accepted only when `verifyOnDownload === false` — the default.
+* Surfaces as a config-load error rather than degrading silently into a
+* fileset glob — silent fallback would let typos like `gob://**` mask
+* cache-correctness bugs that only show up at hash-divergence time.
 */
-interface RemoteCacheSigning {
-  /** Shared secret. Must be at least 16 characters. */
-  secret: string;
-  /**
-  * Reject downloads whose signature doesn't match or is missing.
-  * Set to `true` once every upload on your server is signed.
-  * @default false
-  */
-  verifyOnDownload?: boolean;
+declare class InvalidInputUriError extends Error {
+  constructor(message: string);
 }
 /**
-* Options for the remote cache.
+* Parses a URI-prefixed input string into its structured `InputDefinition`.
+* Returns `undefined` for strings that don't carry a URI scheme — callers
+* fall back to existing handling (named-input lookup, bare globs).
 */
-interface RemoteCacheOptions {
-  /**
-  * Compression format for artifact tarballs. Defaults to `"gzip"`
-  * for Turborepo protocol compatibility.
-  */
-  compression?: RemoteCacheCompression;
-  /**
-  * Called when a fire-and-forget upload fails.
-  * Since uploads are non-blocking, errors are silently swallowed by default.
-  * Provide this callback to log or report upload failures.
-  */
-  onUploadError?: (hash: string, error: unknown) => void;
-  /** Whether to enable remote cache reads */
-  read?: boolean;
-  /**
-  * HMAC-SHA256 signing for upload integrity. When set, every
-  * uploaded artifact carries an `X-Artifact-Signature` header;
-  * downloads with `verifyOnDownload: true` reject unsigned or
-  * tampered payloads.
-  */
-  signing?: RemoteCacheSigning;
-  /** Team ID or namespace for cache isolation */
-  teamId?: string;
-  /** Request timeout in milliseconds (default: 30000) */
-  timeout?: number;
-  /** Authentication token for the remote cache */
-  token?: string;
-  /** Remote cache server URL (e.g., "https://cache.example.com") */
-  url: string;
-  /** Whether to enable remote cache writes */
-  write?: boolean;
-}
+declare const parseInputUri: (input: string) => InputDefinition | undefined;
 /**
-* HTTP-based remote cache compatible with the Turborepo remote cache protocol.
-*
-* Protocol:
-* - GET  /v8/artifacts/{hash}?teamId={team}  -> retrieve cached artifact (gzipped tar)
-* - PUT  /v8/artifacts/{hash}?teamId={team}  -> store artifact
-* - POST /v8/artifacts/events                -> analytics (optional)
-*
-* Authentication via `Authorization: Bearer {token}` header.
-*
-* The cache entry is a gzipped tarball containing the cache directory contents
-* (code, terminalOutput, fingerprint.json, outputs/, .commit).
+* Cheap predicate used by callers that only need to know whether a string
+* looks like a URI — saves them re-parsing when they want to short-circuit
+* other handling (e.g. file-group lookup) before delegating to
+* {@link parseInputUri} downstream.
 */
-declare class RemoteCache {
-  #private;
-  constructor(options: RemoteCacheOptions);
-  /**
-  * Retrieves a cached artifact from the remote cache.
-  * Returns the local path to the extracted cache entry, or undefined if not found.
-  */
-  retrieve(hash: string, localCacheDirectory: string): Promise<boolean>;
-  /**
-  * Stores a cache entry in the remote cache.
-  */
-  store(hash: string, localCacheDirectory: string): Promise<boolean>;
-  /**
-  * Checks if an artifact exists in the remote cache without downloading it.
-  */
-  exists(hash: string): Promise<boolean>;
-}
+declare const looksLikeInputUri: (input: string) => boolean;
+/**
+* Enforces project dependency constraints on a project graph.
+* @param projectGraph The workspace project graph to validate.
+* @param constraints The constraint rules to enforce.
+* @returns Array of violations found. Empty means all constraints pass.
+*/
+declare const enforceProjectConstraints: (projectGraph: ProjectGraph, constraints: ConstraintsConfig) => ConstraintViolation[];
 interface CreateTaskGraphOptions {
   /** The project graph */
   projectGraph: ProjectGraph;
@@ -2368,7 +2910,14 @@ interface TaskOrchestratorOptions {
   dryRun?: boolean;
   fingerprintEnvPatterns?: string[];
   lifeCycle: LifeCycleInterface;
-  remoteCache?: RemoteCache;
+  /**
+  * Surfaces bridge-local upload pipeline failures (tar / digest)
+  * for fire-and-forget remote-cache writes. Wire-level errors are
+  * already reported by the backend's own `onUploadError`; this
+  * fills the gap for steps the backend never sees.
+  */
+  onRemoteUploadError?: (hash: string, error: unknown) => void;
+  remoteCache?: RemoteCacheBackend;
   resolveCommand?: (task: Task) => string | undefined;
   scheduler: TaskScheduler;
   skipCache?: boolean;
@@ -2500,8 +3049,45 @@ declare const readPackageDeps: (packageJsonPath: string, options?: {
   peer?: boolean;
 }) => Promise<Set<string> | undefined>;
 /**
-* Generates a unique ID for temporary files/directories.
-* Not cryptographically secure — for cache entry naming only.
+* Generates a unique ID for temporary files/directories using
+* `crypto.randomUUID()`. Used for staging-path names that briefly
+* coexist on disk during atomic writes — collisions would clobber a
+* concurrent writer's staging directory, so the extra entropy over
+* `Date.now() + Math.random()` is worth the cycles. UUID v4 from
+* Node's crypto module is itself uniformly random, making this
+* cheaper than the previous string concat.
 */
 declare const uniqueId: () => string;
-export { type AffectedOptions, type AffectedResult, type AffectedScope, Cache, type CacheMissReason, type CacheOptions, type CachedResult, type ChromeTraceEvent, CompositeLifeCycle, type ConcurrentCloseEvent, type ConcurrentCommandConfig, type ConcurrentCommandInput, type ConcurrentRunResult, type ConcurrentRunnerOptions, ConsoleLifeCycle, type ConstraintViolation, type ConstraintsConfig, DEFAULT_CACHE_DIRECTORY_NAME, type DependencyKindRules, type DependencyType, type DetectedFramework, EmptyLifeCycle, type EnvMatcher, type EnvironmentInput, type ExternalDependencyInput, type FileAccess, FileAccessTracker, type FileSetBase, type FileSetInput, type FileSetPattern, type FileSnapshot, FingerprintManager, type GraphFormat, type GraphJson, type GraphVisualizerOptions, InProcessTaskHasher, IncrementalFileHasher, type IncrementalHasherOptions, type InputDefinition, type InputHandlerOptions, type LifeCycleInterface, LockfileHasher, type LogMode, LogReporter, type NamedInputs, type NodePlatform, type OutputSpec, type PackageLockfileHash, type ParseCommandsOptions, type PartitionOptions, type ProcessEvent, type ProjectConfiguration, type ProjectGraph, type ProjectGraphDependency, type ProjectGraphProjectNode, RemoteCache, type RemoteCacheCompression, type RemoteCacheOptions, type RemoteCacheSigning, type ResolvedDependency, type RestartOptions, type RunSummary, type RuntimeInput, type TagRelationships, type TargetConfiguration, type TargetDependencyConfig, type Task, type TaskExecutionOptions, type TaskExecutor, type TaskFingerprint, type TaskGraph, type TaskHashDetails, type TaskHasher, type TaskHasherOptions, TaskOrchestrator, type TaskOrchestratorOptions, type TaskPriority, type TaskResult, type TaskResults, type TaskRunnerContext, type TaskRunnerOptions, TaskScheduler, type TaskStatus, type TaskSummary, type TaskTarget, type TasksRunner, type TeardownOptions, TerminalBuffer, type TokenContext, type TrackedExecutionResult, TrackedTaskExecutor, type TrackingResult, type TypeBoundaries, type WhenCondition, type WhenContext, type WorkspaceConfiguration, buildForwardDependencyMap, buildReverseDependencyMap, collectFiles, computeTaskHash, createFailureResult, createInputHandler, createLogReporter, createTaskGraph, defaultTaskRunner, detectFrameworks, detectScriptShell, enforceProjectConstraints, evaluateWhen, expandAffected, expandArguments, expandShortcut, expandTokens, expandTokensInString, expandWildcard, explainWhen, extractPackageName, filterAffectedTasks, findCycle, findCycles, formatCacheSize, formatTimingTable, generatePreloadScript, generateRunSummary, getAffectedProjects, getChangedFiles, getCurrentBranch, getDependentTasks, getFrameworkEnvVariables, getLastRunSummaryPath, getLeafTasks, getTaskId, getTransitiveDependencies, hashFile, hashStrings, inferFrameworkEnvPatterns, isNativeAvailable, loadNativeBindings, logTimings, makeAcyclic, parseCacheSize, parseCommands, parseNpmLockfile, parsePartition, parsePnpmLockfile, parseTaskId, parseYarnLockfile, projectGraphToDot, readLastRunSummary, readPackageDeps, resetBranchCache, resolveOutputs, resolveTaskCwd, reverseTaskGraph, runConcurrentFallback, runConcurrently, runTeardown, sortObjectKeys, stripQuotes, toChromeTrace, toGraphAscii, toGraphHtml, toGraphJson, toGraphvizDot, uniqueId, walkTaskGraph, withRestart, writeChromeTrace, writeLastRunSummary, writeRunSummary };
+/**
+* Returns the absolute path to the *main* git worktree root when
+* `workspaceRoot` is a linked worktree, or `undefined` for primary
+* checkouts and non-git directories.
+*
+* Result is memoized for the lifetime of the process — worktree topology
+* does not change at runtime, so the second call is a hash lookup.
+*
+* Detection logic:
+* 1. If `{workspaceRoot}/.git` is a *directory*, this is a primary checkout
+*    (or vanilla repo). Returns `undefined`.
+* 2. If `{workspaceRoot}/.git` is a *file* (gitlink), resolves to the parent
+*    of `git rev-parse --git-common-dir` — that is the main worktree root.
+* 3. On any error (missing git binary, shallow CI checkout, etc.), returns
+*    `undefined` so the caller falls back to the workspace-local cache.
+* @param workspaceRoot Absolute path to the candidate workspace root.
+* @returns The main worktree root, or `undefined` if not a linked worktree.
+*/
+declare const getMainWorktreeRoot: (workspaceRoot: string) => string | undefined;
+/**
+* Returns `true` when `{workspaceRoot}/.git` is a regular file (the gitlink
+* pointer used by `git worktree add`), `false` otherwise. Cheap pre-flight
+* before invoking `git rev-parse`.
+* @param workspaceRoot Absolute path to the candidate workspace root.
+*/
+declare const isLinkedWorktree: (workspaceRoot: string) => boolean;
+/**
+* Clears the in-process detection cache. Tests must call this between
+* scenarios because the cache key is the canonicalized workspace path —
+* recreating a fixture at the same path would otherwise leak stale results.
+*/
+declare const resetWorktreeCache: () => void;
+export { type ActionResult, type AffectedOptions, type AffectedResult, type AffectedScope, type BlobSource, Cache, type CacheMissReason, type CacheMode, type CacheOptions, type CacheRestoreOptions, type CachedResult, type CasDigest, type ChromeTraceEvent, CompositeLifeCycle, type ConcurrentCloseEvent, type ConcurrentCommandConfig, type ConcurrentCommandInput, type ConcurrentRunResult, type ConcurrentRunnerOptions, ConsoleLifeCycle, type ConstraintViolation, type ConstraintsConfig, DEFAULT_CACHE_DIRECTORY_NAME, type DependencyKindRules, type DependencyType, type DetectedFramework, EmptyLifeCycle, type EnvMatcher, type EnvironmentInput, type ExternalDependencyInput, type FileAccess, FileAccessTracker, type FileSetBase, type FileSetInput, type FileSetPattern, type FileSnapshot, FingerprintManager, type GraphFormat, type GraphJson, type GraphVisualizerOptions, HttpRemoteCache, INPUT_URI_SCHEMES, InProcessTaskHasher, IncrementalFileHasher, type IncrementalHasherOptions, type InputDefinition, type InputHandlerOptions, type InputUriScheme, InvalidInputUriError, type LifeCycleInterface, LockfileHasher, type LogMode, LogReporter, type NamedInputs, type NodePlatform, type OutputSpec, type PackageLockfileHash, type ParseCommandsOptions, type PartitionOptions, type ProcessEvent, type ProjectConfiguration, type ProjectGraph, type ProjectGraphDependency, type ProjectGraphProjectNode, ReapiRemoteCache, type ReapiRemoteCacheOptions, type RemoteCacheBackend, type RemoteCacheCompression, type RemoteCacheOptions, type RemoteCacheSigning, type ResolvedDependency, type RestartOptions, type RunSummary, type RuntimeInput, type TagRelationships, type TargetConfiguration, type TargetDependencyConfig, type Task, type TaskExecutionOptions, type TaskExecutor, type TaskFingerprint, type TaskGraph, type TaskHashDetails, type TaskHasher, type TaskHasherOptions, TaskOrchestrator, type TaskOrchestratorOptions, type TaskPriority, type TaskResult, type TaskResults, type TaskRunnerContext, type TaskRunnerOptions, TaskScheduler, type TaskStatus, type TaskSummary, type TaskTarget, type TasksRunner, type TeardownOptions, TerminalBuffer, type TokenContext, type TrackedExecutionResult, TrackedTaskExecutor, type TrackingResult, type TypeBoundaries, V2_AC, V2_CAS, V2_INDEX, V2_ROOT, V2_TMP, type WhenCondition, type WhenContext, type WorkspaceConfiguration, acEntryPath, actionDigestForTaskHash, buildForwardDependencyMap, buildReverseDependencyMap, casBlobPath, collectFiles, computeTaskHash, containsBlob, containsByTaskHash, createFailureResult, createInputHandler, createLogReporter, createRemoteCacheBackend, createTaskGraph, defaultTaskRunner, detectFrameworks, detectScriptShell, digestBuffer, digestFile, enforceProjectConstraints, evaluateWhen, expandAffected, expandArguments, expandShortcut, expandTokens, expandTokensInString, expandWildcard, explainWhen, extractPackageName, fetchBlobToFile, filterAffectedTasks, findCycle, findCycles, formatCacheSize, formatTimingTable, generatePreloadScript, generateRunSummary, getAffectedProjects, getChangedFiles, getCurrentBranch, getDependentTasks, getFrameworkEnvVariables, getLastRunSummaryPath, getLeafTasks, getMainWorktreeRoot, getTaskId, getTransitiveDependencies, hashFile, hashStrings, inferFrameworkEnvPatterns, isLinkedWorktree, isNativeAvailable, loadNativeBindings, logTimings, looksLikeInputUri, makeAcyclic, parseCacheSize, parseCommands, parseInputUri, parseNpmLockfile, parsePartition, parsePnpmLockfile, parseTaskId, parseYarnLockfile, projectGraphToDot, putBlobFromBytes, putBlobFromFile, readLastRunSummary, readPackageDeps, resetBranchCache, resetWorktreeCache, resolveCacheMode, resolveOutputs, resolveTaskCwd, retrieveByTaskHash, reverseTaskGraph, runConcurrentFallback, runConcurrently, runTeardown, sortObjectKeys, storeByTaskHash, stripQuotes, taskHashIndexPath, toChromeTrace, toGraphAscii, toGraphHtml, toGraphJson, toGraphvizDot, touchBlob, uniqueId, verifyBlob, walkTaskGraph, withRestart, writeChromeTrace, writeLastRunSummary, writeRunSummary };