@visulima/task-runner 1.0.0-alpha.2 → 1.0.0-alpha.20

package/dist/index.d.ts

@@ -1,34 +1,3795 @@
-export type { AffectedOptions, AffectedResult } from "./affected.d.ts";
-export { filterAffectedTasks, getAffectedProjects, getChangedFiles } from "./affected.d.ts";
-export type { CachedResult, CacheOptions } from "./cache.d.ts";
-export { Cache, formatCacheSize, parseCacheSize } from "./cache.d.ts";
-export { defaultTaskRunner } from "./default-task-runner.d.ts";
-export type { FileAccess, TrackingResult } from "./file-access-tracker.d.ts";
-export { FileAccessTracker, generatePreloadScript } from "./file-access-tracker.d.ts";
-export type { CacheMissReason, TaskFingerprint } from "./fingerprint.d.ts";
-export { FingerprintManager } from "./fingerprint.d.ts";
-export type { DetectedFramework } from "./framework-inference.d.ts";
-export { detectFrameworks, getFrameworkEnvVariables, inferFrameworkEnvPatterns } from "./framework-inference.d.ts";
-export type { GraphFormat, GraphJson, GraphVisualizerOptions } from "./graph-visualizer.d.ts";
-export { projectGraphToDot, toGraphAscii, toGraphHtml, toGraphJson, toGraphvizDot } from "./graph-visualizer.d.ts";
-export type { FileSnapshot, IncrementalHasherOptions } from "./incremental-hasher.d.ts";
-export { IncrementalFileHasher } from "./incremental-hasher.d.ts";
-export { CompositeLifeCycle, ConsoleLifeCycle, EmptyLifeCycle } from "./life-cycle.d.ts";
-export type { PackageLockfileHash, ResolvedDependency } from "./lockfile-hasher.d.ts";
-export { extractPackageName, LockfileHasher, parseNpmLockfile, parsePnpmLockfile, parseYarnLockfile } from "./lockfile-hasher.d.ts";
-export { isNativeAvailable, loadNativeBindings } from "./native-binding.d.ts";
-export type { RemoteCacheOptions } from "./remote-cache.d.ts";
-export { RemoteCache } from "./remote-cache.d.ts";
-export type { RunSummary, TaskSummary } from "./run-summary.d.ts";
-export { generateRunSummary, writeRunSummary } from "./run-summary.d.ts";
-export { createTaskGraph, getTaskId, parseTaskId } from "./task-graph.d.ts";
-export { findCycle, findCycles, getDependentTasks, getLeafTasks, getTransitiveDependencies, makeAcyclic, reverseTaskGraph, walkTaskGraph, } from "./task-graph-utils.d.ts";
-export type { TaskHasher, TaskHasherOptions } from "./task-hasher.d.ts";
-export { computeTaskHash, InProcessTaskHasher } from "./task-hasher.d.ts";
-export type { TaskOrchestratorOptions } from "./task-orchestrator.d.ts";
-export { TaskOrchestrator } from "./task-orchestrator.d.ts";
-export { TaskScheduler } from "./task-scheduler.d.ts";
-export type { TrackedExecutionResult } from "./tracked-executor.d.ts";
-export { TrackedTaskExecutor } from "./tracked-executor.d.ts";
-export type { EnvironmentInput, ExternalDependencyInput, FileSetInput, InputDefinition, LifeCycleInterface, NamedInputs, ProjectConfiguration, ProjectGraph, ProjectGraphDependency, ProjectGraphProjectNode, RuntimeInput, TargetConfiguration, TargetDependencyConfig, Task, TaskExecutionOptions, TaskExecutor, TaskGraph, TaskHashDetails, TaskResult, TaskResults, TaskRunnerContext, TaskRunnerOptions, TasksRunner, TaskStatus, TaskTarget, WorkspaceConfiguration, } from "./types.d.ts";
-export { collectFiles, createFailureResult, hashFile, hashStrings, readPackageDeps, resolveTaskCwd, sortObjectKeys, uniqueId } from "./utils.d.ts";
+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;
+  /**
+  * True when the macOS DYLD-interpose tracker is usable. Unlike
+  * {@link isSupported} (which gates the syscall-level Linux paths),
+  * interpose only covers *directly-exec'd* commands — the caller
+  * must additionally check {@link parseDirectExec} and fall back to
+  * the preload path for shell-syntax commands.
+  */
+  isInterposeSupported(): boolean;
+  /**
+  * Tracks a directly-exec'd `argv` via the macOS interpose dylib.
+  * `argv` MUST come from {@link parseDirectExec} (a single binary,
+  * no shell syntax) — it is exec'd directly, never through a shell,
+  * so `DYLD_INSERT_LIBRARIES` survives SIP. Degrades to the
+  * no-tracking path if the addon/dylib went missing since the
+  * availability check.
+  */
+  trackInterpose(argv: string[], options?: {
+    abortSignal?: AbortSignal;
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+  }): Promise<TrackingResult>;
+  /**
+  * True when the Windows IAT-hook tracker is usable. Like
+  * {@link isInterposeSupported}, only covers *directly-exec'd*
+  * commands (the DLL is injected into the spawned binary, with no
+  * child-process propagation) — the caller must gate on
+  * {@link parseDirectExec} and fall back to the preload path for
+  * shell-syntax commands.
+  */
+  isIatHookSupported(): boolean;
+  /**
+  * Tracks a directly-exec'd `argv` via the Windows `fspy_windows`
+  * DLL (IAT hooks). `argv` MUST come from {@link parseDirectExec}.
+  * Degrades to the no-tracking path if the addon/DLL went missing
+  * since the availability check.
+  */
+  trackIatHook(argv: string[], options?: {
+    abortSignal?: AbortSignal;
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+  }): Promise<TrackingResult>;
+  /**
+  * Runs a command and tracks all file system accesses.
+  *
+  * Dispatch order (highest fidelity first):
+  * 1. **seccomp_unotify** — kernel-level interception via the
+  *    bundled helper binary. Catches static binaries and musl
+  *    children that the strace + preload paths miss. Linux only.
+  * 2. **strace** — userspace fallback when seccomp isn't
+  *    available (no native addon, no helper bin, kernel < 5.0).
+  * 3. **no-op** — on every other platform, run the command and
+  *    return zero accesses so the orchestrator's empty-fingerprint
+  *    diagnostic fires.
+  */
+  track(command: string, options?: {
+    /** When fired, SIGTERMs the active spawn for this call. */
+    abortSignal?: AbortSignal;
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+  }): Promise<TrackingResult>;
+  /**
+  * Kills all active child processes. Called on abort/signal to
+  * prevent orphans. Works for both `ChildProcess` (strace path)
+  * and the seccomp helper PID stub via the shared `Killable`
+  * shape.
+  */
+  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;
+}
+/**
+* Keyless artifact attestation hooks for the HTTP backend.
+*
+* Layered *above* {@link RemoteCacheSigning}: HMAC proves the bytes
+* weren't tampered with by anyone lacking the shared secret (integrity);
+* an attestation proves *who* produced them (authenticity — a Sigstore
+* keyless bundle in practice). Both can be active at once.
+*
+* task-runner stays dependency-free: it never imports Sigstore. The
+* caller (vis) supplies these callbacks; task-runner only moves the
+* opaque bundle string through the `X-Artifact-Attestation` header and
+* decides accept/reject from the boolean the verifier returns. REAPI
+* does not consume these — REAPI integrity rides on CAS content-
+* addressing, and authenticity is a server/transport concern there.
+*/
+interface RemoteCacheAttestation {
+  /**
+  * Expected keyless signer identity. Serializable so it can live in
+  * `vis.config.ts`. task-runner does not consume this — it is config
+  * passthrough for the vis-side `verifyArtifact` hook, which must
+  * enforce it. Without an expected identity a valid bundle from *any*
+  * Fulcio identity over the same digest verifies (integrity, not
+  * authenticity), so the vis hook treats "verify requested without an
+  * expected identity" as a misconfiguration.
+  *
+  * Three forms (pick one):
+  * - `{ github }` — GitHub Actions preset. Expands to the Fulcio
+  *   issuer + an escaped, anchored SAN. The ergonomic default.
+  * - `{ oidcIssuer, san }` — a *literal* signer identity. vis escapes
+  *   and anchors it for you; pass the plain URI, not a regex.
+  * - `{ oidcIssuer, sanRegex }` — advanced: a raw, unescaped regex.
+  *   You own anchoring (sigstore-js matches via `String.match`).
+  */
+  expectedIdentity?: {
+    /**
+    * GitHub Actions preset. Expands to issuer
+    * `https://token.actions.githubusercontent.com` and the
+    * anchored SAN `https://github.com/{repo}/{workflow}@{ref}`.
+    */
+    github: {
+      /** Git ref the workflow ran on, e.g. `refs/heads/main` or `refs/tags/v1.2.3`. */
+      ref: string;
+      /** `owner/name`, e.g. `visulima/visulima`. */
+      repo: string;
+      /** Workflow path, e.g. `.github/workflows/release.yml`. */
+      workflow: string;
+    };
+  } | {
+    /** Fulcio cert issuer extension, matched exactly. */
+    oidcIssuer: string;
+    /**
+    * Literal signer identity (certificate SAN). vis
+    * regex-escapes and anchors this — pass the plain URI,
+    * e.g. `https://github.com/org/repo/.github/workflows/ci.yml@refs/heads/main`.
+    */
+    san: string;
+  } | {
+    /** Fulcio cert issuer extension, matched exactly. */
+    oidcIssuer: string;
+    /**
+    * Advanced: raw, unescaped SAN regex. You own anchoring
+    * (`^…$`); an unanchored value is substring-matched.
+    */
+    sanRegex: string;
+  };
+  /**
+  * Called when a download is rejected (or downgraded to a cache miss)
+  * because its attestation is missing or failed verification. Without
+  * this hook the rejection is silent. Mirrors `onUploadError`.
+  */
+  onReject?: (hash: string, reason: "invalid" | "missing") => void;
+  /**
+  * Reject downloads whose attestation is missing or fails
+  * verification. With `verifyArtifact` set but this `false`, a bad
+  * attestation is treated as a cache miss (re-execute) rather than a
+  * hard failure.
+  * @default false
+  */
+  requireOnDownload?: boolean;
+  /**
+  * Produce an opaque attestation bundle for the staged artifact,
+  * called after the body is staged and before the PUT. Return `null`
+  * to upload without an attestation (e.g. no ambient OIDC outside
+  * CI). Any returned string is sent verbatim in the
+  * `X-Artifact-Attestation` header.
+  */
+  signArtifact?: (input: {
+    archivePath: string;
+    hash: string;
+  }) => Promise<string | null>;
+  /**
+  * Verify a received attestation bundle against the staged artifact.
+  * Resolve `false` to reject the cached entry. Only called when the
+  * download carried an `X-Artifact-Attestation` header.
+  */
+  verifyArtifact?: (input: {
+    archivePath: string;
+    attestation: string;
+    hash: string;
+  }) => Promise<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;
+  /**
+  * HTTP-only: keyless artifact attestation hooks (Sigstore in
+  * practice). Layered above `signing` — integrity vs authenticity.
+  */
+  attestation?: RemoteCacheAttestation;
+  /**
+  * 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
+* without having to wrap the whole `when` in a compound expression.
+*
+* Examples:
+*   `os: "linux"`              — runs only on linux
+*   `os: ["linux", "darwin"]`  — runs on linux or macOS
+*   `not.os: "windows"`        — runs everywhere except windows
+*   `env: "CI"`                — runs only when `process.env.CI` is truthy
+*   `env: { name: "NODE_ENV", equals: "production" }`
+*   `branch: ["main", "alpha"]`
+*   `ci: true`                 — runs only inside CI
+*/
+interface WhenCondition {
+  /** Match against the current git branch (HEAD). */
+  branch?: string | string[];
+  /**
+  * Run only when invoked inside CI when `true`, only outside CI
+  * when `false`. Detects CI via the `CI` env var (the convention
+  * GitHub Actions, GitLab, CircleCI, Jenkins, etc. all share).
+  */
+  ci?: boolean;
+  /**
+  * Match against environment variables. A bare string asserts the
+  * variable is set and non-empty; the object form lets you match
+  * an exact value or just assert presence/absence.
+  */
+  env?: EnvMatcher | EnvMatcher[];
+  /** Negative mirrors. A task runs only when *all* `not.*` clauses fail. */
+  not?: {
+    branch?: string | string[];
+    ci?: boolean;
+    env?: EnvMatcher | EnvMatcher[];
+    os?: NodePlatform | NodePlatform[];
+  };
+  /**
+  * Match `process.platform` (`"linux" | "darwin" | "win32" | "freebsd"
+  * | "openbsd" | "sunos" | "aix"`). Pass `"windows"` as an alias for
+  * `"win32"` — easier to remember and matches what people type.
+  */
+  os?: NodePlatform | NodePlatform[];
+}
+/**
+* An environment-variable match. The string form is shorthand for
+* `{ name, exists: true }` (set + non-empty). The object form
+* supports either presence assertions or exact-value matching.
+*/
+type EnvMatcher = string | {
+  /** Match this exact value. Mutually exclusive with `exists`. */
+  equals?: string;
+  /** Assert the variable is set & non-empty (`true`) or unset/empty (`false`). */
+  exists?: boolean;
+  /** Variable name. */
+  name: string;
+};
+/** Aliased platform list — `"windows"` is sugar for Node's `"win32"`. */
+type NodePlatform = "aix" | "darwin" | "freebsd" | "linux" | "openbsd" | "sunos" | "windows" | "win32";
+/**
+* Inputs for {@link evaluateWhen}. Pulled into a struct so tests can
+* inject deterministic values and CLIs can reuse the same env/branch
+* lookup across many task evaluations.
+*/
+interface WhenContext {
+  /** Current git branch. Pass an empty string when not in a repo. */
+  branch?: string;
+  /** Whether we're inside CI. Defaults to `process.env.CI` truthy check. */
+  ci?: boolean;
+  /** Environment variables to match against. Defaults to `process.env`. */
+  env?: Record<string, string | undefined>;
+  /** Platform string. Defaults to `process.platform`. */
+  platform?: NodePlatform;
+}
+declare const getCurrentBranch: (cwd: string) => string;
+/** Test-only escape hatch — clears every cached branch result. */
+declare const resetBranchCache: () => void;
+/**
+* Evaluates a {@link WhenCondition} against the supplied context (or the
+* live process state when omitted). Returns `true` when the task should
+* run, `false` when every positive clause matches and every `not.*`
+* clause is also satisfied.
+*
+* Semantics:
+*   - All positive clauses must match (AND).
+*   - All `not.*` clauses must not match (AND).
+*   - Within a single clause, an array means any-of (OR).
+*   - An empty/undefined `when` always returns `true`.
+*/
+declare const evaluateWhen: (when: WhenCondition | undefined, context?: WhenContext) => boolean;
+/**
+* Returns a short human-readable explanation of why a `when` clause
+* skipped a task. Used by lifecycle handlers to print diagnostics.
+* Returns an empty string when the condition evaluates to true.
+*/
+declare const explainWhen: (when: WhenCondition | undefined, context?: WhenContext) => string;
+/**
+* Represents a target that a task executes against.
+*/
+interface TaskTarget {
+  /** Optional configuration name */
+  configuration?: string;
+  /** The project name */
+  project: string;
+  /** The target name (e.g., "build", "test", "lint") */
+  target: string;
+}
+/**
+* Represents a single task to be executed.
+*/
+/**
+* Scheduling priority hint. The scheduler picks higher-priority tasks
+* out of the ready-queue first; ties fall through to the graph-derived
+* signals (dependent count, project depth).
+*
+* Use `"high"` for long-running leaves you want to kick off early
+* (integration tests, e2e suites) so their wall-clock overlaps with
+* the main build phase. Use `"low"` for work you don't mind deferring
+* (linters, coverage uploads) when faster tasks contend for slots.
+*/
+type TaskPriority = "high" | "low" | "normal";
+/**
+* Workspace-level concurrency caps. Maps a group name to the maximum
+* number of in-flight tasks across every target that opts into the
+* group via {@link TargetConfiguration.concurrencyGroup}. Independent
+* of `--parallel`: the global cap still bounds total in-flight tasks,
+* and group caps further bound the named subset. Values `&lt;= 0` are
+* ignored.
+*/
+type ConcurrencyGroups = Record<string, number>;
+/**
+* A single entry in a task's `outputs` list.
+*
+* - `string` — a literal path *or* a glob pattern relative to the
+*   workspace root. Prefix with `!` to exclude files the positive
+*   patterns would otherwise include (e.g. `"!dist/cache/**"`).
+* - `{ auto: true }` — use whatever files the task actually wrote
+*   during execution (resolved from the file-access tracker). Lets
+*   authors who don't know their exact output layout cache results
+*   without listing every path. Silently behaves as "no outputs" when
+*   tracking isn't active for this task.
+*/
+type OutputSpec = string | {
+  auto: true;
+};
+interface Task {
+  /**
+  * When `true`, this task runs after the main task graph completes
+  * — even if upstream tasks failed or the run was interrupted.
+  * Used for cleanup, teardown, or notification tasks. Carried over
+  * from {@link TargetConfiguration.always} at task graph creation.
+  */
+  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;
+  /**
+  * Workspace-level concurrency group. Carried over from
+  * {@link TargetConfiguration.concurrencyGroup}; the scheduler maps
+  * the name to a numeric cap via
+  * {@link TaskRunnerOptions.concurrencyGroups}.
+  */
+  concurrencyGroup?: string;
+  /**
+  * Per-task slot weight against the global `parallel` cap. Defaults
+  * to `1` (one slot). Carried over from
+  * {@link TargetConfiguration.concurrencyWeight}; values `&lt;= 0`,
+  * non-finite, or non-integer are ignored (treated as `1` — matches
+  * `resolveWeight` in `task-scheduler.ts`).
+  */
+  concurrencyWeight?: number;
+  /** Hash of the task inputs for caching */
+  hash?: string;
+  /** Detailed hash information */
+  hashDetails?: TaskHashDetails;
+  /**
+  * How this task's cache key is derived. Carried over from
+  * {@link TargetConfiguration.hashMode} at task graph creation.
+  * `"trace"` routes the task through the file-access tracker so the
+  * key comes from the files it actually read — the per-target
+  * equivalent of the global {@link TaskRunnerOptions.autoFingerprint}.
+  * Absent / `"declared"` keeps the Nx-style upfront hash from
+  * explicit {@link Task.outputs} and declared inputs.
+  */
+  hashMode?: "declared" | "trace";
+  /** Unique identifier for the task, typically "project:target:configuration" */
+  id: string;
+  /**
+  * Maximum in-flight instances allowed for this task's target name.
+  * Carried over from {@link TargetConfiguration.maxConcurrent}.
+  */
+  maxConcurrent?: number;
+  /**
+  * Output patterns this task produces. Each entry is either a
+  * literal path, a glob (`"dist/**"`), a negative glob
+  * (`"!dist/cache/**"`), or `{ auto: true }` to pick up whatever
+  * files the task wrote during execution.
+  */
+  outputs: OutputSpec[];
+  /** Overrides/extra options passed to the task */
+  overrides: Record<string, unknown>;
+  /** Whether this task supports parallel execution */
+  parallelism?: boolean;
+  /**
+  * Explicit scheduling priority. Outranks the scheduler's
+  * graph-derived heuristics. Defaults to `"normal"` when absent.
+  */
+  priority?: TaskPriority;
+  /** The project root directory */
+  projectRoot?: string;
+  /**
+  * Per-task PTY override. When `true`, this task spawns inside a
+  * pseudo-terminal even if the workspace-level toggle is off (or
+  * vice versa when `false`). Carried over from
+  * {@link TargetConfiguration.pty}. Consumed by the runner that
+  * actually spawns the command — the task-runner library exposes
+  * the flag and leaves the spawn decision to the executor.
+  */
+  pty?: boolean;
+  /** 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
+  * executor. Carried over from {@link TargetConfiguration.when}.
+  */
+  when?: WhenCondition;
+}
+/**
+* Represents detailed hash information for a task.
+*/
+interface TaskHashDetails {
+  /** The command hash */
+  command: string;
+  /** Hash of implicit dependencies */
+  implicitDeps?: Record<string, string>;
+  /** Hashes of input files */
+  nodes: Record<string, string>;
+  /** Hash of runtime values */
+  runtime?: Record<string, string>;
+}
+/**
+* Represents a directed acyclic graph of tasks.
+*/
+interface TaskGraph {
+  /** Dependencies for each task */
+  dependencies: Record<string, string[]>;
+  /** Top-level tasks that no other task depends on (the final outputs to run) */
+  roots: string[];
+  /** All tasks in the graph, keyed by task ID */
+  tasks: Record<string, Task>;
+}
+/**
+* Possible states of a task after execution.
+*/
+type TaskStatus = "success" | "failure" | "skipped" | "local-cache" | "local-cache-kept-existing" | "remote-cache";
+/**
+* Result of executing a task.
+*/
+interface TaskResult {
+  /**
+  * Set when the task asked the runner not to cache this run by calling
+  * `disableCache()` from `@visulima/task-runner-client`. Unlike
+  * {@link TaskResult.emptyFingerprint}, the fingerprint may be perfectly
+  * valid — the task itself declared the run non-deterministic (network
+  * flake, debug mode, aborted watch). Surfaced to reporters and the run
+  * summary so the skip is explained rather than silent.
+  */
+  cacheDisabledByTask?: boolean;
+  /**
+  * Provenance of the cooperative cache hints a task emitted via
+  * `@visulima/task-runner-client` during this run. Present only when
+  * the task registered at least one hint, so the common (no-client)
+  * path leaves it `undefined`. Surfaced in `--summarize` output so a
+  * cache key can be explained: which reads/writes were ignored and
+  * which env vars/patterns were registered as dependencies.
+  */
+  cacheHints?: {
+    /** Absolute paths whose reads were dropped from inferred inputs. */
+    ignoredInputs: string[];
+    /** Absolute paths whose writes were dropped from inferred outputs. */
+    ignoredOutputs: string[];
+    /** Env var names registered as cache dependencies via `getEnv`. */
+    trackedEnv: string[];
+    /** Env glob patterns registered as cache dependencies via `getEnvs`. */
+    trackedEnvPatterns: string[];
+  };
+  /** The exit code, if applicable */
+  code?: number;
+  /**
+  * Set when auto-fingerprint tracking was attempted for this task but
+  * returned zero workspace accesses — usually a static binary on
+  * macOS/Windows, where the Node preload can't attach. Caching is
+  * skipped to avoid persisting an empty fingerprint that would
+  * produce false cache hits on every subsequent run.
+  */
+  emptyFingerprint?: boolean;
+  /** 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;
+  /**
+  * Number of times the task was restarted by the retry controller
+  * before producing this final result. `0` (or undefined) means the
+  * task succeeded or failed on its first attempt; `> 0` means the
+  * task eventually produced this status after N restarts. Surfaced
+  * to lifecycle reporters and the run summary so a "green" build
+  * that masked a flake via retries is still visible to the user.
+  */
+  retryAttempts?: number;
+  /**
+  * 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
+  * contents and produce false cache hits on subsequent runs.
+  */
+  selfModified?: boolean;
+  /** The start time of the task */
+  startTime?: number;
+  status: TaskStatus;
+  task: Task;
+  /** The terminal output produced during execution */
+  terminalOutput?: string;
+}
+/**
+* Map of task results, keyed by task ID.
+*/
+type TaskResults = Map<string, TaskResult>;
+/**
+* Configuration for a project in the workspace.
+*/
+interface ProjectConfiguration {
+  /** Implicit dependencies on other projects */
+  implicitDependencies?: string[];
+  /**
+  * Project layer in the dependency hierarchy. Used by
+  * `enforceLayerRelationships` to ensure projects only depend on
+  * projects at the same or lower layer.
+  *
+  * Hierarchy (lowest → highest):
+  * `configuration < library < scaffolding < tool < automation < application`
+  */
+  layer?: "application" | "automation" | "configuration" | "library" | "scaffolding" | "tool";
+  /** The project type */
+  projectType?: "application" | "library" | "service" | "tool";
+  /** The root directory of the project, relative to workspace root */
+  root: string;
+  /** The source root directory */
+  sourceRoot?: string;
+  /** Tags for filtering */
+  tags?: string[];
+  /** Named targets and their configurations */
+  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 {
+  /**
+  * When `true`, this target runs after the main task graph
+  * completes — even if upstream tasks failed. Useful for cleanup,
+  * teardown, notifications, or anything that should fire
+  * regardless of build outcome. Always-tasks are not part of the
+  * normal dependency graph and never block other tasks.
+  */
+  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;
+  /**
+  * Workspace-level concurrency group this target opts into. The
+  * scheduler caps the *combined* in-flight count of every task whose
+  * target carries the same group name to the value declared in
+  * {@link TaskRunnerOptions.concurrencyGroups}. Use this when several
+  * targets share an external resource (a single Postgres,
+  * a developer's Docker daemon, an account-wide deploy lock) so the
+  * cap follows the resource, not any single target name.
+  *
+  * Targets that name a group not declared in `concurrencyGroups` run
+  * uncapped — a typo shouldn't deadlock the graph. Caps don't apply
+  * to tasks marked `always: true`; those run in a separate
+  * finalisation phase outside the scheduler.
+  */
+  concurrencyGroup?: string;
+  /**
+  * Per-task slot weight against the global `parallel` cap. Defaults
+  * to `1`. A task with `concurrencyWeight: 2` consumes two slots; with
+  * `parallel: 4` only two such tasks can run concurrently (or one
+  * weight-2 plus two weight-1). Use for CPU-pinning tasks — bundlers,
+  * `tsc`, native compiles — where the runner shouldn't keep
+  * over-subscribing the box just because slots are nominally free.
+  *
+  * The scheduler always lets a single task run even if its weight
+  * exceeds the remaining budget; otherwise a heavy task on a
+  * `parallel: 1` pool would deadlock. Values `&lt;= 0`, non-finite, or
+  * non-integer are ignored (treated as `1`).
+  */
+  concurrencyWeight?: number;
+  /** Named configurations (e.g., "production", "development") */
+  configurations?: Record<string, Record<string, unknown>>;
+  /** Other targets this target depends on */
+  dependsOn?: (string | TargetDependencyConfig)[];
+  /** The executor/command to run */
+  executor?: string;
+  /**
+  * How this target's cache key is derived.
+  *
+  * - `"declared"` (default): the Nx-style path — the hash is built
+  *   up-front from explicitly declared `inputs` (plus named/global
+  *   inputs and the lockfile). Deterministic and portable across
+  *   machines: two runners with the same workspace state produce the
+  *   same key regardless of OS or syscall surface.
+  * - `"trace"`: the task is run under the file-access tracker
+  *   (strace on Linux, an fs preload shim elsewhere) and the cache
+  *   key is derived from the files it actually *read* during
+  *   execution — no `inputs` declaration required. Mirrors the
+  *   shipped `{ auto: true }` output capture, but for the input
+  *   side. Use for compound or opaque commands whose real input set
+  *   is impractical to enumerate.
+  *
+  * Opt-in per target precisely because trace mode trades
+  * reproducibility for convenience: the observed read set can differ
+  * across runners with different syscall surfaces (a static binary on
+  * a host without strace records nothing), so a trace key is **not**
+  * guaranteed portable between machines. Leave targets on
+  * `"declared"` whenever the input set can reasonably be listed.
+  *
+  * Equivalent to flipping {@link TaskRunnerOptions.autoFingerprint}
+  * on for this one target while every other target stays declared.
+  */
+  hashMode?: "declared" | "trace";
+  /** Input patterns for cache invalidation */
+  inputs?: (string | InputDefinition)[];
+  /**
+  * Maximum number of in-flight instances of this target across the
+  * whole graph. When set, the scheduler refuses to start an
+  * additional task whose `target.target` equals this target's name
+  * once the running count reaches `maxConcurrent`. Independent of
+  * `--parallel`: the global cap still bounds total in-flight tasks,
+  * and `maxConcurrent` further bounds the per-target subset.
+  *
+  * Use for tests/deploys that share an external resource (DB, port,
+  * mock server). Set to `1` to serialize. Values `&lt;= 0` are ignored.
+  *
+  * If multiple projects declare different values for the same
+  * target name, the runner uses the smallest declared cap. Caps
+  * don't apply to tasks marked `always: true`; those run in a
+  * separate finalisation phase outside the scheduler.
+  */
+  maxConcurrent?: number;
+  /** Options passed to the executor */
+  options?: Record<string, unknown>;
+  /**
+  * Output patterns produced by this target. Each entry is a literal
+  * path, a glob (`"dist/**"`), a negative glob (`"!dist/cache/**"`),
+  * or `{ auto: true }` to cache whatever files the task actually
+  * wrote during execution (resolved from the file-access tracker).
+  * `{ auto: true }` lets a build script cache zero-config without
+  * the author enumerating its output layout; it contributes nothing
+  * — and the runner declines to seed the cache — when write
+  * tracking isn't available for the task, so a hit can never restore
+  * a missing artifact.
+  */
+  outputs?: OutputSpec[];
+  /** Whether this target supports parallel execution */
+  parallelism?: boolean;
+  /**
+  * Per-target PTY override. When `true`, every task spawned from
+  * this target runs inside a pseudo-terminal (so `isatty()` returns
+  * true and the child preserves color / progress UI). When `false`,
+  * the workspace-level PTY toggle is suppressed for this target.
+  * Useful when most targets are happy with piped stdio but one
+  * tool (vitest, prettier, a colorising linter) needs a real TTY,
+  * or vice versa.
+  *
+  * Absent means "follow the workspace default" — the executor
+  * decides based on its own toggles.
+  */
+  pty?: 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`,
+  * `branch`, and `ci` clauses for granular control:
+  *
+  *   ```ts
+  *   when: { os: "linux", ci: true, env: "DEPLOY_TOKEN" }
+  *   ```
+  */
+  when?: WhenCondition;
+}
+/**
+* Defines a dependency on another target.
+*/
+interface TargetDependencyConfig {
+  /** Whether this is a dependency on the same project */
+  dependencies?: boolean;
+  /** Params to pass through */
+  params?: "forward" | "ignore";
+  /** The project name (if different from the current project) */
+  projects?: string | string[];
+  /** The target name */
+  target: string;
+}
+/**
+* Defines an input for cache invalidation.
+*/
+type InputDefinition = FileSetInput | RuntimeInput | EnvironmentInput | ExternalDependencyInput;
+/**
+* Controls how a glob pattern is anchored.
+* - "package" (default): pattern is resolved relative to the project root
+* - "workspace": pattern is resolved relative to the workspace root
+*/
+type FileSetBase = "package" | "workspace";
+/**
+* An input based on file patterns.
+*
+* `fileset` may be a bare glob string (package-root relative) or an object
+* form `{ pattern, base }` to anchor explicitly to the workspace root.
+* Negation (`!` prefix) works in both forms.
+*/
+interface FileSetInput {
+  fileset: FileSetPattern | string;
+}
+/**
+* Object form of a fileset pattern, for anchoring to the workspace root.
+*/
+interface FileSetPattern {
+  /** Anchor for the pattern. */
+  base: FileSetBase;
+  /** Glob pattern (may start with `!` for negation). */
+  pattern: string;
+}
+/**
+* An input based on a runtime command.
+*/
+interface RuntimeInput {
+  runtime: string;
+}
+/**
+* An input based on environment variables.
+*/
+interface EnvironmentInput {
+  env: string;
+}
+/**
+* An input based on external dependency versions.
+*/
+interface ExternalDependencyInput {
+  externalDependencies: string[];
+}
+/**
+* Defines tag-based dependency rules.
+* Each key is a tag name. The value is the list of tags that a dependency
+* must have at least one of, when the source project has that tag.
+*
+* Example: `{ "frontend": ["shared", "frontend"] }` means a project tagged
+* "frontend" can only depend on projects tagged "shared" or "frontend".
+*/
+type TagRelationships = Record<string, string[]>;
+/**
+* Defines project-type-based dependency rules.
+*/
+interface TypeBoundaries {
+  /**
+  * Custom rules mapping project types to allowed dependency types.
+  * Example: `{ "application": ["library"] }` means applications can only
+  * depend on libraries.
+  */
+  allowedDependencyTypes?: Record<string, string[]>;
+  /**
+  * When true, no project may depend on a deployment target — projects of
+  * type `application`, `service`, or `tool`. Deployment targets are
+  * standalone artefacts, not reusable libraries.
+  * @default true
+  */
+  enforceApplicationBoundary?: boolean;
+}
+/**
+* Rules based on the dependency kind (dependencies vs devDependencies vs peerDependencies).
+*/
+interface DependencyKindRules {
+  /**
+  * When true, a "library" project must not have workspace-internal devDependencies
+  * on other libraries that are also in its production dependencies.
+  * Prevents publishing libraries that silently rely on dev-only workspace packages.
+  * @default false
+  */
+  noDevDependencyOnProductionDep?: boolean;
+  /**
+  * When true, production `dependencies` must not point to deployment-target
+  * projects — `application`, `service`, or `tool`. devDependencies on those
+  * are allowed (e.g., for testing).
+  * @default false
+  */
+  noProductionDependencyOnApplication?: boolean;
+}
+/**
+* Configuration for project constraint enforcement.
+*/
+interface ConstraintsConfig {
+  /** Rules based on the dependency kind (static vs devDependency vs peerDependency) */
+  dependencyKindRules?: DependencyKindRules;
+  /**
+  * When true, projects can only depend on projects at the same or
+  * lower layer in the hierarchy:
+  *
+  *   configuration < library < scaffolding < tool < automation < application
+  *
+  * Projects without an explicit `layer` are unconstrained.
+  * @default false
+  */
+  enforceLayerRelationships?: boolean;
+  /** Tag-based dependency rules */
+  tagRelationships?: TagRelationships;
+  /** Project-type-based dependency rules */
+  typeBoundaries?: TypeBoundaries;
+}
+/**
+* A single constraint violation detected in the project graph.
+*/
+interface ConstraintViolation {
+  /** The project being depended on */
+  dependencyProject: string;
+  /** Human-readable description of the violation */
+  message: string;
+  /** The type of rule that was violated */
+  rule: "dependency-kind" | "layer-relationship" | "tag-relationship" | "type-boundary";
+  /** The project that has the invalid dependency */
+  sourceProject: string;
+}
+/**
+* Controls how far to traverse the dependency graph in a given direction.
+* - "none": Don't traverse — only directly changed projects are included.
+* - "direct": Include only immediate neighbors (one hop).
+* - "deep": Include all transitive neighbors (full chain).
+*/
+type AffectedScope = "deep" | "direct" | "none";
+/**
+* Workspace configuration containing all project configurations.
+*/
+interface WorkspaceConfiguration {
+  /** All projects in the workspace, keyed by project name */
+  projects: Record<string, ProjectConfiguration>;
+}
+/**
+* The kind of dependency relationship between projects.
+* - "static": Production dependency (from `dependencies` in package.json)
+* - "dynamic": Dynamically resolved dependency (e.g., lazy imports)
+* - "implicit": Declared via `implicitDependencies` in project config
+* - "devDependency": Development-only dependency (from `devDependencies`)
+* - "peerDependency": Peer dependency (from `peerDependencies`)
+*/
+type DependencyType = "devDependency" | "dynamic" | "implicit" | "peerDependency" | "static";
+/**
+* A dependency relationship in the project graph.
+*/
+interface ProjectGraphDependency {
+  /** The source project */
+  source: string;
+  /** The target project */
+  target: string;
+  /** The type of dependency */
+  type: DependencyType;
+}
+/**
+* A node in the project graph.
+*/
+interface ProjectGraphProjectNode {
+  /** The project configuration */
+  data: ProjectConfiguration;
+  /** The project name */
+  name: string;
+  /** The type of project */
+  type: "application" | "library" | "service" | "tool";
+}
+/**
+* The project graph represents the dependency relationships between projects.
+*/
+interface ProjectGraph {
+  /** All dependency relationships */
+  dependencies: Record<string, ProjectGraphDependency[]>;
+  /** All project nodes, keyed by project name */
+  nodes: Record<string, ProjectGraphProjectNode>;
+}
+/**
+* Named input definitions that can be referenced by name.
+*/
+interface NamedInputs {
+  [name: string]: (string | InputDefinition)[];
+}
+/**
+* Configuration for the task runner.
+*/
+interface TaskRunnerOptions {
+  /**
+  * Scan each task's resolved command text for `$VAR`/`${VAR}`
+  * references and automatically fingerprint those env vars. Catches
+  * tasks like `curl ${VERCEL_URL}/api` where the user forgot to
+  * declare the reference in `envVars`/`globalEnv`.
+  * @default false
+  */
+  autoEnvVars?: boolean;
+  /**
+  * Enable auto-fingerprinting mode (Vite Task-style).
+  * When enabled, the task runner automatically tracks which files
+  * a task accesses during execution and uses that for cache invalidation
+  * instead of requiring manual input configuration.
+  *
+  * Falls back to explicit inputs (Nx-style) when file tracking
+  * is not supported on the current platform.
+  *
+  * This is the workspace-wide switch. To opt a single target into
+  * traced hashing without flipping it for the whole graph, set
+  * {@link TargetConfiguration.hashMode} to `"trace"` on that target
+  * instead.
+  * @default false
+  */
+  autoFingerprint?: boolean;
+  /**
+  * Failure-propagation policy.
+  *
+  * - `false` (default) — when a task fails, its transitive
+  *   dependents are marked `skipped`. Tasks not downstream of the
+  *   failure still run. Prevents cascade failures from running a
+  *   dependent on a missing `dist/` produced by the failed dep.
+  * - `true` — fail-fast. On the first failure every not-yet-started
+  *   task is marked `skipped`; in-flight tasks finish naturally.
+  * @default false
+  */
+  bail?: boolean;
+  /**
+  * Whether to show cache miss diagnostics (why a cache miss occurred).
+  * @default false
+  */
+  cacheDiagnostics?: boolean;
+  /** Directory for storing cache */
+  cacheDirectory?: string;
+  /**
+  * Workspace-level concurrency group caps. Maps a group name to the
+  * maximum number of in-flight tasks across every target whose
+  * `concurrencyGroup` field equals the same name. Independent of
+  * `parallel`: the global cap still bounds total tasks, and group
+  * caps further bound the named subset.
+  *
+  * Common shape — one cap per shared resource:
+  *
+  *   ```ts
+  *   concurrencyGroups: {
+  *     "db-bound": 2,    // any target hitting the local Postgres
+  *     "deploy-lock": 1, // any deploy target
+  *   }
+  *   ```
+  *
+  * Targets opt in via {@link TargetConfiguration.concurrencyGroup}.
+  * Values `&lt;= 0` are ignored.
+  */
+  concurrencyGroups?: ConcurrencyGroups;
+  /**
+  * Directory used to persist run summaries (`runs/`),
+  * `last-summary.json`, and other run-scoped state. Defaults to
+  * `{workspaceRoot}/.task-runner` when omitted so standalone
+  * task-runner consumers keep their existing layout. Vis sets this
+  * to `{workspaceRoot}/.vis` so all per-workspace state lives under
+  * a single directory.
+  */
+  dataDirectory?: string;
+  /**
+  * Dry-run mode: compute hashes and check cache but don't execute tasks.
+  * Useful for debugging cache hits/misses.
+  * @default false
+  */
+  dryRun?: boolean;
+  /** Custom environment variables to include in hash */
+  envVars?: string[];
+  /**
+  * Environment variable patterns to include in auto-fingerprint.
+  * Supports wildcard patterns like "VITE_*".
+  * Only used when autoFingerprint is enabled.
+  */
+  fingerprintEnvPatterns?: string[];
+  /**
+  * Enable framework environment variable inference.
+  * When true, automatically detects common frontend frameworks and includes
+  * their public env var prefixes in the task hash:
+  * - Next.js: NEXT_PUBLIC_*
+  * - Vite: VITE_*
+  * - Create React App: REACT_APP_*
+  * - Gatsby: GATSBY_*
+  * - Nuxt: NUXT_PUBLIC_*
+  * - Expo: EXPO_PUBLIC_*
+  *
+  * Matches Turborepo's framework inference behavior.
+  * @default false
+  */
+  frameworkInference?: boolean;
+  /**
+  * Global environment variables that invalidate ALL task hashes.
+  * Matches Turborepo's `globalEnv`.
+  */
+  globalEnv?: string[];
+  /**
+  * Global input files that invalidate ALL task hashes when changed.
+  * These are workspace-root-relative paths.
+  *
+  * Default: ["package-lock.json", "pnpm-lock.yaml", "yarn.lock",
+  * "tsconfig.base.json", ".env"]
+  *
+  * When any global input changes, every task's hash changes,
+  * forcing a full rebuild. This matches Turborepo's `globalDependencies`.
+  */
+  globalInputs?: string[];
+  /**
+  * When `true`, file hashes are cached in a persistent mtime+size
+  * indexed snapshot under `node_modules/.cache/task-runner/`. On
+  * subsequent runs, unchanged files skip content re-reads — cuts
+  * cold-cache fingerprint time dramatically on large workspaces.
+  *
+  * Changed or new files still get full content hashing. Safe to
+  * leave on by default; overhead when nothing matches is a single
+  * `stat` call per file.
+  * @default false
+  */
+  incrementalFileHashing?: boolean;
+  /** Maximum age of cache entries in milliseconds */
+  maxCacheAge?: number;
+  /** Maximum cache size (e.g., "1GB") */
+  maxCacheSize?: string;
+  /** Named inputs for cache invalidation */
+  namedInputs?: NamedInputs;
+  /**
+  * When `true`, the cache directory is partitioned by a hash of
+  * the resolved `globalEnv` values. Changing a globalEnv var moves
+  * cache writes into a new namespace; rolling it back reuses the
+  * old namespace and its hits. Without this option, any globalEnv
+  * change silently busts every cached entry.
+  *
+  * Keep disabled when globalEnv is stable across runs — the extra
+  * path depth offers no value, and misconfigured namespaces can
+  * hide stale hits.
+  * @default false
+  */
+  namespaceByGlobalEnv?: boolean;
+  /**
+  * Plugin extension point invoked during task fingerprinting. Fires
+  * once per task after the built-in inputs (filesets, runtime, env)
+  * have been gathered and before the hash is sealed. Contributions
+  * made through the supplied {@link FingerprintContributor} are mixed
+  * deterministically into the final hash.
+  *
+  * Throwing aborts fingerprinting for that task — the task fails
+  * before any cache lookup runs, so a buggy plugin can't silently
+  * corrupt cache state.
+  *
+  * Wired by `vis` to bridge into the `task:fingerprint` hook;
+  * standalone task-runner consumers can pass a callback directly.
+  */
+  onFingerprint?: FingerprintHook;
+  /** Maximum number of parallel tasks */
+  parallel?: number | boolean;
+  /**
+  * Remote cache configuration.
+  * 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;
+  /**
+  * Enable smart lockfile hashing.
+  * Instead of hashing the entire lockfile (which busts ALL caches),
+  * only hash the resolved versions of each package's actual dependencies.
+  * This matches Turborepo's smart lockfile hashing behavior.
+  * @default false
+  */
+  smartLockfileHashing?: boolean;
+  /**
+  * Generate a detailed JSON run summary after execution.
+  * When true, writes a summary file to `.task-runner/runs/` containing
+  * all task inputs, outputs, hashes, timings, and cache status.
+  *
+  * Useful for debugging cache misses and comparing runs.
+  * Matches Turborepo's `--summarize` flag.
+  * @default false
+  */
+  summarize?: boolean;
+  /** Target-specific default configurations */
+  targetDefaults?: Record<string, Partial<TargetConfiguration>>;
+  /**
+  * Environment variables that should be passed to tasks but NOT
+  * included in the cache fingerprint. Useful for CI-specific vars.
+  * Only used when autoFingerprint is enabled.
+  */
+  untrackedEnvVars?: string[];
+}
+/**
+* Handle handed to plugin fingerprint hooks. Plugins call
+* `contribute(key, value)` to mix extra strings into the task hash —
+* the hasher merges contributions into a deterministic, sorted bucket
+* so registration order doesn't change the resulting hash.
+*
+* Re-contributing the same key overwrites the previous value (last
+* write wins). Plugins that need isolation should namespace their
+* keys (e.g. `my-plugin:setting`).
+*/
+interface FingerprintContributor {
+  /**
+  * Mix `value` into the task fingerprint under `key`. Both are
+  * arbitrary strings; the hasher runs them through xxh3 alongside
+  * the built-in inputs.
+  */
+  contribute: (key: string, value: string) => void;
+}
+/**
+* Plugin callback fired during fingerprint construction, after all
+* built-in inputs (filesets, runtime, env) have been gathered and
+* before the final hash is sealed. Contributions made via the supplied
+* {@link FingerprintContributor} are mixed into the hash.
+*
+* Throwing aborts hashing for that task — the task fails before any
+* cache lookup, so a buggy plugin doesn't quietly corrupt cache state.
+*/
+type FingerprintHook = (task: Task, contributor: FingerprintContributor) => Promise<void> | void;
+/**
+* Options for executing a task.
+*/
+interface TaskExecutionOptions {
+  /** Whether to capture output */
+  captureOutput?: boolean;
+  /** The working directory */
+  cwd?: string;
+  /** Environment variables */
+  env?: Record<string, string>;
+  /** Stream output as it arrives */
+  streamOutput?: boolean;
+}
+/**
+* A task executor function.
+*/
+type TaskExecutor = (task: Task, options: TaskExecutionOptions) => Promise<{
+  code: number;
+  retryAttempts?: number;
+  terminalOutput: string;
+}>;
+/**
+* The function type for a task runner.
+*/
+type TasksRunner = (tasks: Task[], options: TaskRunnerOptions, context: TaskRunnerContext) => Promise<TaskResults>;
+/**
+* Context provided to the task runner.
+*/
+interface TaskRunnerContext {
+  /** Lifecycle hooks */
+  lifeCycle: LifeCycleInterface;
+  /** The project graph */
+  projectGraph: ProjectGraph;
+  /** The task executor */
+  taskExecutor: TaskExecutor;
+  /** The task graph */
+  taskGraph: TaskGraph;
+  /** The workspace root directory */
+  workspaceRoot: string;
+}
+/**
+* Input for a concurrent command -- either a string or a config object.
+*/
+type ConcurrentCommandInput = string | {
+  command: string;
+  cwd?: string;
+  env?: Record<string, string>;
+  name?: string; /** Initial PTY dimensions (only used when stdin is "pty"). */
+  ptySize?: {
+    cols: number;
+    rows: number;
+  };
+  stdin?: "inherit" | "null" | "pipe" | "pty";
+};
+/**
+* Configuration for a single command to run concurrently.
+*/
+interface ConcurrentCommandConfig {
+  /** The command string to execute (passed to shell). */
+  command: string;
+  /** Working directory for the command. */
+  cwd?: string;
+  /** Additional environment variables merged with process env. */
+  env?: Record<string, string>;
+  /** Human-readable name for this command (used in prefixes/logs). */
+  name?: string;
+  /**
+  * Initial PTY dimensions. Only used when stdin is "pty".
+  * Defaults to 80x24 if not specified.
+  */
+  ptySize?: {
+    cols: number;
+    rows: number;
+  };
+  /** Whether to use shell execution (default: true). */
+  shell?: boolean;
+  /**
+  * Stdin mode for the child process.
+  * - "null" (default): stdin closed, child cannot read input
+  * - "pipe": stdin is piped, can be written to programmatically
+  * - "inherit": child inherits parent's stdin (for interactive commands like vite dev)
+  * - "pty": child runs inside a pseudo-terminal (isatty() returns true, enables interactive prompts)
+  */
+  stdin?: "inherit" | "null" | "pipe" | "pty";
+}
+/**
+* Options controlling the concurrent runner behavior.
+*/
+interface ConcurrentRunnerOptions {
+  /** Conditions under which to kill other processes: "success", "failure". */
+  killOthers?: ("failure" | "success")[];
+  /** Signal to send when killing processes (default: "SIGTERM"). */
+  killSignal?: string;
+  /** Milliseconds to wait after kill signal before sending SIGKILL (default: 5000). */
+  killTimeout?: number;
+  /** Maximum number of processes to run simultaneously. 0 = unlimited. */
+  maxProcesses?: number;
+  /** Callback for real-time process events. */
+  onEvent?: (event: ProcessEvent) => void;
+  /** Restart options for failed commands. */
+  restart?: {
+    /** Delay between restarts in ms. "exponential" for 2^attempt * 1000ms. */
+    delay?: number | "exponential";
+    /**
+    * Optional pre-restart callback. Fires once per scheduled retry,
+    * after the failed attempt is detected and before the restart
+    * delay sleeps. `attempt` is 1-indexed and counts the retry that's
+    * about to start. Throwing aborts the entire restart batch.
+    */
+    onRetry?: (attempt: number, commandIndex: number, prevExitCode: number) => Promise<void> | void;
+    /** Maximum restart attempts per command. 0 = no restarts. -1 = infinite. */
+    tries: number;
+  };
+  /**
+  * Custom shell path for command execution.
+  * Overrides the platform default (/bin/sh on Unix, cmd.exe on Windows).
+  * Automatically detected from npm's `script-shell` config if not set.
+  */
+  shellPath?: string;
+  /** Success condition: "first", "last", "all", or "command-&lt;name|index>". */
+  successCondition?: string;
+  /** Commands to run sequentially after all processes complete. */
+  teardown?: string[];
+  /** Working directory for teardown commands. */
+  teardownCwd?: string;
+  /** Print a timing summary table after completion. Default: false. */
+  timings?: boolean;
+}
+/**
+* An event emitted during concurrent execution.
+*/
+interface ProcessEvent {
+  /** Command name (for close events). */
+  commandName?: string;
+  /** Duration in milliseconds (for close events). */
+  durationMs?: number;
+  /** Exit code (for close events). */
+  exitCode?: number;
+  /** Index of the command that produced this event. */
+  index: number;
+  /** Kill the child process/PTY. Only present on "started" events. */
+  kill?: (signal?: string) => void;
+  /** Whether the process was killed (for close events). */
+  killed?: boolean;
+  /** Event type: "stdout", "stderr", "close", "error", "started". */
+  kind: "close" | "error" | "started" | "stderr" | "stdout";
+  /** Error message (for error events). */
+  message?: string;
+  /**
+  * OS pid of the freshly spawned child. Only present on "started"
+  * events; absent when the platform could not provide one.
+  */
+  pid?: number;
+  /** Resize the child's PTY. Only present on "started" events with stdin "pty". */
+  resize?: (cols: number, rows: number) => void;
+  /** Text content (for stdout/stderr events). */
+  text?: string;
+  /** Write data to the child's stdin (pipe) or PTY. Only present on "started" events. */
+  write?: (data: string) => void;
+}
+/**
+* Result of a close event for a single command.
+*/
+interface ConcurrentCloseEvent {
+  /** The command string that was executed. */
+  command: string;
+  /** Duration in milliseconds. */
+  durationMs: number;
+  /** Exit code. -1 if killed by signal. */
+  exitCode: number;
+  /** Index of the command. */
+  index: number;
+  /** Whether the process was forcefully killed. */
+  killed: boolean;
+  /** The command name (if provided). */
+  name?: string;
+}
+/**
+* Overall result of a concurrent run.
+*/
+interface ConcurrentRunResult {
+  /** Close events for all commands, in completion order. */
+  closeEvents: ConcurrentCloseEvent[];
+  /** Whether the run succeeded according to the success condition. */
+  success: boolean;
+}
+/**
+* Interface for lifecycle event handlers.
+*/
+interface LifeCycleInterface {
+  endCommand?: () => void;
+  endTasks?: (taskResults: TaskResult[]) => void;
+  /**
+  * Called when a running task emits data on stderr, in the order the
+  * data arrives. Executors that support streaming output (`vis run`'s
+  * concurrent executor) forward chunks here verbatim. Executors that
+  * only buffer full output (e.g. the simple test executor) skip this
+  * hook — rely on `printTaskTerminalOutput` for the final dump.
+  *
+  * Handlers should be non-blocking; the orchestrator doesn't await.
+  */
+  onTaskStderr?: (task: Task, chunk: string) => void;
+  /**
+  * Called when a running task emits data on stdout, in the order the
+  * data arrives. See {@link LifeCycleInterface.onTaskStderr} for
+  * semantics — same contract, different stream.
+  */
+  onTaskStdout?: (task: Task, chunk: string) => void;
+  /**
+  * Called when caching is skipped because the task itself requested it
+  * via `disableCache()` (`@visulima/task-runner-client`). Distinct from
+  * {@link LifeCycleInterface.printEmptyFingerprintWarning}: the
+  * fingerprint may be valid; the task declared the run non-cacheable.
+  */
+  printCacheDisabledByTask?: (task: Task) => void;
+  /** Called when a cache miss occurs with diagnostic information */
+  printCacheMiss?: (task: Task, reasons: string) => void;
+  /**
+  * Called when caching was skipped because auto-fingerprint tracking
+  * came back empty — a signal that the tracker (strace or Node
+  * preload) couldn't observe the task's file access, typically
+  * because it's a static binary on a platform without strace.
+  * `reason` is a short human-readable diagnostic.
+  */
+  printEmptyFingerprintWarning?: (task: Task, reason: string) => void;
+  /**
+  * Called when caching is skipped because the task modified one or
+  * more of its own tracked inputs. `modifiedFiles` lists the
+  * workspace-relative paths that changed between pre- and
+  * post-execution hashes.
+  */
+  printSelfModifyingSkip?: (task: Task, modifiedFiles: string[]) => void;
+  printTaskTerminalOutput?: (task: Task, status: TaskStatus, terminalOutput: string) => void;
+  /**
+  * Called when a task is skipped because its `when` clause did not
+  * match the current environment. `reason` is a short
+  * human-readable diagnostic produced by {@link import("./when-condition").explainWhen}.
+  *
+  * Co-fires with `printTaskTerminalOutput` (status `"skipped"`,
+  * output `"Skipped: [reason]"`). Pick one to render — implementing
+  * both will double-report the skip.
+  */
+  printWhenSkip?: (task: Task, reason: string) => void;
+  scheduleTask?: (task: Task) => void;
+  startCommand?: () => void;
+  startTasks?: (tasks: Task[]) => void;
+}
+/**
+* Options for determining affected projects.
+*/
+interface AffectedOptions {
+  /** The base ref to compare against (default: "main") */
+  base?: string;
+  /**
+  * Control how far downstream (dependents of changed projects) to include.
+  * @default "deep"
+  */
+  downstream?: AffectedScope;
+  /** The head ref to compare (default: "HEAD") */
+  head?: string;
+  /** Project graph for dependency resolution */
+  projectGraph: ProjectGraph;
+  /** All project configurations keyed by name */
+  projects: Record<string, ProjectConfiguration>;
+  /**
+  * Control how far upstream (dependencies of changed projects) to include.
+  * @default "none"
+  */
+  upstream?: AffectedScope;
+  /** The workspace root directory */
+  workspaceRoot: string;
+}
+/**
+* Result of affected detection.
+*/
+interface AffectedResult {
+  /** All affected projects (union of changed, downstream, and upstream) */
+  affectedProjects: string[];
+  /** Files that changed between base and head */
+  changedFiles: string[];
+  /** Projects that were directly changed */
+  changedProjects: string[];
+  /** Projects affected because they depend on changed projects */
+  downstreamProjects: string[];
+  /** Projects that changed projects depend on */
+  upstreamProjects: string[];
+}
+/**
+* Builds a map from each project to the set of projects that depend on it (reverse/downstream).
+*/
+declare const buildReverseDependencyMap: (projectGraph: ProjectGraph) => Map<string, Set<string>>;
+/**
+* Builds a map from each project to the set of projects it depends on (forward/upstream).
+*/
+declare const buildForwardDependencyMap: (projectGraph: ProjectGraph) => Map<string, Set<string>>;
+/**
+* Expands a set of changed projects based on upstream/downstream scope settings.
+* Returns a new set containing all affected projects.
+*/
+declare const expandAffected: (changedProjects: Set<string>, projectGraph: ProjectGraph, options: {
+  downstream: AffectedScope;
+  upstream: AffectedScope;
+}) => {
+  affected: Set<string>;
+  downstream: Set<string>;
+  upstream: Set<string>;
+};
+/**
+* Gets the list of files changed between two git refs.
+* Uses execFile with argument arrays to prevent command injection.
+*/
+declare const getChangedFiles: (workspaceRoot: string, base: string, head: string) => Promise<string[]>;
+/**
+* Determines which projects are affected by changes between two git refs.
+*
+* Uses `git diff` to find changed files, maps them to projects based on
+* project roots, then walks the project dependency graph to find all
+* transitively affected projects.
+*
+* This is the same strategy used by `nx affected` and `turbo run --filter=[base...]`.
+*/
+declare const getAffectedProjects: (options: AffectedOptions) => Promise<AffectedResult>;
+/**
+* Filters tasks to only include those that are affected by changes.
+*/
+declare const filterAffectedTasks: (taskIds: string[], affectedProjects: Set<string>) => string[];
+/**
+* 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;
+/**
+* Fill missing HTTP-backend fields from Turborepo's environment
+* variables so a workspace migrating from Turbo can keep its existing
+* CI secrets:
+*
+* - `TURBO_API`   → `url`
+* - `TURBO_TOKEN` → `token`
+* - `TURBO_TEAM`  → `teamId`
+*
+* Explicit values in `input` always win. Returns `undefined` when
+* neither config nor env supplies a URL, which is the signal callers
+* use to mean "no remote cache configured." REAPI users are unaffected
+* — the env vars are Turborepo-shaped and only resolve `http` fields.
+*/
+declare const resolveTurboEnvCompat: (input?: Partial<RemoteCacheOptions>, env?: NodeJS.ProcessEnv) => RemoteCacheOptions | undefined;
+/**
+* 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.
+*
+* `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.
+*/
+declare const actionDigestForTaskHash: (taskHash: string) => CasDigest;
+/**
+* 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.
+*/
+declare const containsByTaskHash: (backend: RemoteCacheBackend, taskHash: string) => Promise<boolean>;
+/**
+* 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.
+*
+* 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 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(options: RemoteCacheOptions);
+  /**
+  * 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.
+  */
+  close(): Promise<void>;
+  /**
+  * {@link RemoteCacheBackend.containsAction}: HEAD on the artifact URL.
+  * Resolves `false` on any wire failure — existence checks are best
+  * effort and never block the caller.
+  */
+  containsAction(actionDigest: CasDigest): Promise<boolean>;
+  /**
+  * {@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.
+  */
+  fetchBlob(digest: CasDigest, destinationPath: string): Promise<boolean>;
+  /**
+  * {@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.
+  */
+  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>;
+}
+/**
+* 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.
+*/
+type ReapiRemoteCacheOptions = RemoteCacheOptions;
+/**
+* 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.
+*
+* Wire flow:
+*   - retrieveAction → GetActionResult → fetchBlob (BatchReadBlobs|Read)
+*   - storeAction    → FindMissingBlobs → BatchUpdateBlobs|Write → UpdateActionResult
+*/
+declare class ReapiRemoteCache implements RemoteCacheBackend {
+  #private;
+  constructor(options: ReapiRemoteCacheOptions);
+  /**
+  * 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.
+  *
+  * 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.
+  */
+  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.
+*/
+interface CachedResult {
+  /** The exit code of the original task execution */
+  code: number;
+  /** The auto-fingerprint data, if auto-fingerprinting was used */
+  fingerprint?: TaskFingerprint;
+  /** The hash that was used as the cache key */
+  hash: string;
+  /** The terminal output of the original task execution */
+  terminalOutput: string;
+}
+/**
+* Options for creating a Cache instance.
+*/
+interface CacheOptions {
+  /** The cache directory (defaults to `{workspaceRoot}/.task-runner-cache`) */
+  cacheDirectory?: string;
+  /**
+  * Optional isolation namespace appended to the cache directory
+  * as `&lt;cacheDir>/ns/&lt;namespace>`. When the caller derives the
+  * namespace from the resolved global-env fingerprint, flipping an
+  * env var sends writes into a new namespace while keeping the old
+  * namespace intact — rolling the env back restores the old hits.
+  *
+  * Filesystem-safe segment; callers are responsible for sanitising
+  * (slashes/colons would break path resolution).
+  */
+  cacheNamespace?: string;
+  /** Maximum age of cache entries in milliseconds (default: 7 days) */
+  maxCacheAge?: number;
+  /** Maximum cache size (e.g., "500MB", "1GB") */
+  maxCacheSize?: string;
+  /** The workspace root directory */
+  workspaceRoot: string;
+}
+/**
+* Directory name (relative to `workspaceRoot`) where the task runner writes
+* its cache by default. Exported so callers that manage the cache from the
+* outside — e.g. a CLI `cache clean` command — can reach the same default
+* without hard-coding the literal.
+*/
+declare const DEFAULT_CACHE_DIRECTORY_NAME = ".task-runner-cache";
+/**
+* Parses a human-readable cache size string into bytes.
+* Delegates to @visulima/humanizer's parseBytes with base-2 (1024) multipliers.
+*/
+declare const parseCacheSize: (sizeString: string) => number;
+/**
+* Formats a byte count into a human-readable string.
+* Delegates to @visulima/humanizer's formatBytes with base-2 (1024) multipliers.
+*/
+declare const formatCacheSize: (bytes: number) => string;
+/**
+* Local file-based cache for task results.
+*
+* Cache structure:
+* ```
+* .task-runner-cache/
+*   &lt;hash&gt;/
+*     outputs/          (Archived build outputs)
+*     code              (Exit code)
+*     terminalOutput    (Captured terminal output)
+*     fingerprint.json  (Auto-fingerprint data, optional)
+*     .commit           (Marker indicating complete cache entry)
+*   .task-index.json    (Task ID -> hash mapping for auto-fingerprint)
+* ```
+*
+* Atomicity: Cache entries are written to a temporary directory first,
+* then renamed into place. The `.commit` marker ensures readers only
+* see complete entries.
+*/
+declare class Cache {
+  #private;
+  constructor(options: CacheOptions);
+  /**
+  * Gets the cache directory path.
+  */
+  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.
+  */
+  get(hash: string): Promise<CachedResult | undefined>;
+  /**
+  * Stores a task result in the cache.
+  *
+  * Uses atomic write: builds the entry in a temporary directory,
+  * then renames into place to avoid partial reads by concurrent processes.
+  *
+  * `outputs` accepts the richer `OutputSpec[]` shape — glob
+  * patterns, negative globs, and `{ auto: true }` entries. Pass
+  * `autoWrites` alongside `{ auto: true }` so the resolver knows
+  * which files the task actually wrote; otherwise auto entries
+  * contribute nothing.
+  */
+  put(hash: string, terminalOutput: string, outputs: OutputSpec[], code: number, fingerprint?: TaskFingerprint, autoWrites?: ReadonlyArray<string>): Promise<void>;
+  /**
+  * Restores cached outputs from the compressed `outputs.tar.br`
+  * archive. Returns `true` either when the archive was extracted
+  * successfully OR when the entry simply has no outputs to restore.
+  *
+  * The restore flow stages into a temp directory, then swaps each
+  * top-level entry into place (see {@link restoreOutputsCompressed})
+  * so a mid-restore failure never destroys the user's working tree.
+  * The `outputs` parameter is no longer consulted at restore time —
+  * the archive is authoritative, and top-level entries in the
+  * extracted staging become the set of swap roots. Still accepted
+  * for backward compat.
+  */
+  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
+  * tracked file accesses rather than computed upfront.
+  */
+  getByTaskId(taskId: string): Promise<CachedResult | undefined>;
+  /**
+  * Stores the mapping from task ID to cache hash.
+  * Uses a write queue to serialize concurrent writes and prevent lost updates.
+  * Each write is atomic (temp file + rename).
+  */
+  setTaskIndex(taskId: string, hash: string): Promise<void>;
+  /**
+  * Removes old cache entries that exceed the maximum age,
+  * and enforces the maximum cache size by evicting oldest entries.
+  *
+  * NOTE: `maxCacheSize` only bounds the *legacy* `&lt;hash>/` entry
+  * layout. The v2 CAS subtree (rooted at {@link V2_ROOT}) is skipped
+  * here — it manages its own lifetime via blob-level touch + reference
+  * accounting (see `cas/store.ts`) and is deliberately excluded from
+  * both age and size accounting below. Consequently a cache dominated
+  * by v2 blobs reports a small measured size and may exceed
+  * `maxCacheSize`; size-based eviction is not driven from the CAS GC.
+  */
+  removeOldEntries(): Promise<void>;
+  /**
+  * Clears the entire 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 {
+  /** Whether the task was cacheable */
+  cacheable: boolean;
+  /**
+  * Provenance of cooperative cache hints the task emitted via
+  * `@visulima/task-runner-client` ({@link TaskResult.cacheHints}).
+  * Omitted when the task used no client hints.
+  */
+  cacheHints?: TaskResult["cacheHints"];
+  /**
+  * Why a cacheable task that ran (exit 0) seeded no cache entry.
+  * Omitted for cache hits, failures, and ordinary cache writes.
+  * `disabled-by-task` — the task called `disableCache()`;
+  * `self-modified` — it rewrote one of its own tracked inputs;
+  * `empty-fingerprint` — tracking observed no workspace accesses.
+  */
+  cacheSkipReason?: "disabled-by-task" | "empty-fingerprint" | "self-modified";
+  /** Cache status */
+  cacheStatus: "HIT" | "MISS" | "REMOTE_HIT" | "SKIPPED";
+  /** Dependencies on other tasks */
+  dependencies: string[];
+  /** Duration in milliseconds */
+  duration: number | undefined;
+  /** End time (ISO 8601) */
+  endTime: string | undefined;
+  /** Exit code */
+  exitCode: number | undefined;
+  /** The computed cache hash */
+  hash: string | undefined;
+  /** Detailed hash information */
+  hashDetails: TaskHashDetails | undefined;
+  /** The task's declared outputs (glob patterns, literals, or `{ auto: true }`). */
+  outputs: OutputSpec[];
+  /**
+  * Number of times the task was restarted before producing this final
+  * exit code. Omitted when the task completed on its first attempt;
+  * `> 0` means the result is post-retry (a "succeeded after N retries"
+  * pass should still register as a flake observation).
+  */
+  retryAttempts: number | undefined;
+  /** Start time (ISO 8601) */
+  startTime: string | undefined;
+  /** The task target */
+  target: {
+    configuration?: string;
+    project: string;
+    target: string;
+  };
+  /** The task ID (e.g., "app:build") */
+  taskId: string;
+}
+/**
+* Complete summary of a task runner execution.
+*/
+interface RunSummary {
+  /** Total duration in milliseconds */
+  duration: number;
+  /** Run end time (ISO 8601) */
+  endTime: string;
+  /** Environment info */
+  environment: {
+    /** Architecture */
+    arch: string;
+    /** Node.js version */
+    nodeVersion: string;
+    /** Platform */
+    platform: string;
+  };
+  /** Unique run ID */
+  id: string;
+  /** Run start time (ISO 8601) */
+  startTime: string;
+  /** Overall execution statistics */
+  stats: {
+    /** Number of cached tasks (local + remote) */
+    cached: number;
+    /** Number of failed tasks */
+    failed: number;
+    /** Number of skipped tasks */
+    skipped: number;
+    /** Number of successful tasks */
+    succeeded: number;
+    /** Total number of tasks */
+    total: number;
+  };
+  /** The task graph used for this run */
+  taskGraph: {
+    dependencies: Record<string, string[]>;
+    roots: string[];
+  };
+  /** Summary of each task */
+  tasks: TaskSummary[];
+}
+/**
+* Generates a run summary from task results.
+*/
+declare const generateRunSummary: (results: TaskResults, taskGraph: TaskGraph, startTime: number) => RunSummary;
+interface RunSummaryPathOptions {
+  /**
+  * Absolute path to the directory that holds `runs/` and
+  * `last-summary.json`. When omitted, falls back to
+  * `{workspaceRoot}/.task-runner`.
+  */
+  dataDirectory?: string;
+}
+/**
+* Writes the run summary to a JSON file in the `runs/` subdirectory of the
+* resolved data directory (defaults to `.task-runner/runs/`).
+* @param summary The run summary to write
+* @param workspaceRoot The workspace root directory
+* @param options Optional overrides — pass `dataDirectory` to redirect away from `.task-runner/`
+* @returns The path to the written summary file
+*/
+declare const writeRunSummary: (summary: RunSummary, workspaceRoot: string, options?: RunSummaryPathOptions) => Promise<string>;
+/**
+* Path where the most-recent run summary is persisted.
+* Consumers (e.g. CLIs exposing `--last-details`) read this file
+* to replay or render the previous run without re-executing.
+*/
+declare const getLastRunSummaryPath: (workspaceRoot: string, options?: RunSummaryPathOptions) => string;
+/**
+* Persists `summary` as the most-recent run summary at
+* `{dataDirectory}/last-summary.json`, overwriting any previous entry.
+*
+* This is the companion to {@link readLastRunSummary} and powers
+* CLI surfaces that display "last run" details without re-running tasks.
+* @returns The path to the written summary file
+*/
+declare const writeLastRunSummary: (summary: RunSummary, workspaceRoot: string, options?: RunSummaryPathOptions) => Promise<string>;
+/**
+* Reads the most-recent run summary written by {@link writeLastRunSummary}.
+* Returns `undefined` when no previous run has been recorded or the file
+* cannot be parsed — callers should render an informational message
+* instead of treating this as an error.
+*/
+declare const readLastRunSummary: (workspaceRoot: string, options?: RunSummaryPathOptions) => Promise<RunSummary | undefined>;
+/**
+* A single event in the Chrome Tracing JSON format. Chrome's
+* chrome://tracing viewer and Perfetto both accept an array of these.
+*
+* Fields track the subset we actually emit:
+* - `ph: "X"` — "complete" span (has duration)
+* - `ph: "s"` / `ph: "f"` — flow start / finish (connects two spans)
+*
+* See the Chrome Trace Event Format spec on docs.google.com
+* (document id: 1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU)
+* for the full specification.
+*/
+interface ChromeTraceEvent {
+  args?: Record<string, unknown>;
+  /** Event category — grouped in the viewer's search/filter UI. */
+  cat: string;
+  /** Duration in microseconds — only set for `ph: "X"` events. */
+  dur?: number;
+  /** Flow ID — used to draw an arrow from flow-start to flow-finish. */
+  id?: number;
+  /** Human label shown on the timeline. */
+  name: string;
+  /**
+  * Event phase:
+  * - `"X"` — complete (span with duration)
+  * - `"s"` — flow start
+  * - `"f"` — flow finish
+  * - `"M"` — metadata
+  */
+  ph: "f" | "M" | "s" | "X";
+  pid: number;
+  tid: number;
+  /** Timestamp in microseconds. */
+  ts: number;
+}
+/**
+* Converts a {@link RunSummary} into a Chrome Tracing event list that
+* renders as a gantt chart in chrome://tracing or Perfetto.
+*
+* Each task becomes a `"X"` span; dependency edges become flow arrows
+* from the dependency's finish to the dependent task's start.
+* Parallel tasks are assigned synthetic `tid` values (lane 0, 1, 2, …)
+* based on the smallest free lane at the task's start time, so the
+* timeline clearly shows concurrency without requiring real thread IDs.
+*/
+declare const toChromeTrace: (summary: RunSummary) => ChromeTraceEvent[];
+/**
+* Writes a Chrome Tracing JSON file at `outputPath`. Consumers (e.g.
+* a CLI `--profile out.json` flag) call this after the run completes
+* with a RunSummary produced by the task orchestrator.
+*/
+declare const writeChromeTrace: (summary: RunSummary, outputPath: string) => Promise<void>;
+/**
+* Context for token interpolation.
+*
+* Currently the only first-class token group is `affected` (and its alias
+* `changed_files`). Pass `affected.files` (workspace-relative paths) and
+* the renderer will substitute it into command strings such as
+* `eslint ${affected.files}` or `prettier ${changed_files | flag '--file'}`.
+*
+* Optional `projectRoot` makes paths relative to a single project root,
+* stripping the leading prefix and the immediately following `/`. Files
+* outside the root are dropped — token interpolation only emits paths
+* the task can actually act on.
+*/
+interface TokenContext {
+  /** Affected/changed files, relative to workspace root. */
+  affectedFiles?: string[];
+  /**
+  * When set, paths are rewritten relative to this project root and
+  * files outside the root are filtered out.
+  */
+  projectRoot?: string;
+}
+/**
+* Expands token references in a single command string.
+*
+* Supported tokens:
+*   `${affected.files}`                       — space-joined, shell-quoted paths
+*   `${changed_files}`                        — alias of `affected.files`
+*   `${affected.files | flag '--file'}`       — `--file path1 --file path2 ...`
+*
+* Unknown tokens are left in place — they may be environment-variable
+* references the shell will expand at runtime, and silently dropping
+* them would mask bugs in user commands.
+*
+* Escape with a leading backslash (`\${affected.files}`) to emit the
+* literal token without expansion. Note: the regex consumes at most
+* one leading backslash, so `\\${...}` collapses to `\${...}` rather
+* than producing a literal backslash followed by the literal token.
+* Use a different surrounding quoting scheme if you need a real
+* backslash adjacent to a token.
+*/
+declare const expandTokensInString: (command: string, context: TokenContext) => string;
+/**
+* Pipeline-friendly variant of {@link expandTokensInString} that takes
+* and returns a `ConcurrentCommandConfig`. Plays the same role as
+* {@link import("./expand-arguments").expandArguments} so it can slot
+* into {@link import("./index").parseCommands} as a normal step.
+*/
+declare const expandTokens: (config: ConcurrentCommandConfig, context: TokenContext) => ConcurrentCommandConfig;
+/**
+* Expands argument placeholders in command strings.
+*
+* Placeholders:
+*   {1}, {2}, ...  -> specific positional argument
+*   {@}            -> all arguments, individually quoted
+*   {*}            -> all arguments as a single quoted string
+*   \{1}           -> literal {1} (escaped)
+*/
+declare const expandArguments: (config: ConcurrentCommandConfig, additionalArguments: string[]) => ConcurrentCommandConfig;
+/**
+* Expands package manager shortcuts into full commands.
+*
+* This parser transforms shorthand notation into proper package manager
+* invocations. No user input is involved -- command strings originate
+* from the calling code which reads package.json scripts.
+*
+* Examples:
+*   npm:build    -> npm run build
+*   pnpm:test    -> pnpm run test
+*   node:script  -> node --run script
+*   deno:task    -> deno task task
+*/
+declare const expandShortcut: (config: ConcurrentCommandConfig) => ConcurrentCommandConfig;
+/**
+* Expands wildcard patterns in package manager "run" commands.
+*
+* Reads scripts from package.json and matches against the wildcard pattern.
+* Returns one ConcurrentCommandConfig per matching script.
+*
+* Example: "npm run watch-*" with scripts { "watch-js": "...", "watch-css": "..." }
+*          -> ["npm run watch-js", "npm run watch-css"]
+*
+* No user input is involved -- patterns come from the calling code.
+*/
+declare const expandWildcard: (config: ConcurrentCommandConfig) => ConcurrentCommandConfig | ConcurrentCommandConfig[];
+/**
+* Removes surrounding quotes from a command string.
+* Handles both single and double quotes.
+*/
+declare const stripQuotes: (config: ConcurrentCommandConfig) => ConcurrentCommandConfig;
+interface ParseCommandsOptions {
+  /** Additional arguments for placeholder expansion ({1}, {@}, {*}). */
+  additionalArguments?: string[];
+  /**
+  * Token interpolation context. When supplied, `${affected.files}`
+  * and `${changed_files | flag '--file'}` references in command
+  * strings are expanded before argument placeholder substitution.
+  */
+  tokens?: TokenContext;
+}
+/**
+* Parse and expand command inputs through the full pipeline:
+* 1. Normalize string inputs to config objects
+* 2. Strip surrounding quotes
+* 3. Expand package manager shortcuts (npm:build -> npm run build)
+* 4. Expand wildcard patterns (npm run watch-* -> multiple commands)
+* 5. Expand token references (${affected.files}, ${changed_files | flag '...'})
+* 6. Expand argument placeholders ({1}, {@}, {*})
+*/
+declare const parseCommands: (inputs: ConcurrentCommandInput[], options?: ParseCommandsOptions) => ConcurrentCommandConfig[];
+/**
+* Run commands concurrently with output streaming and process management.
+*
+* Automatically uses the native Rust addon for performance when available,
+* falling back to a pure JavaScript implementation.
+*
+* Supports flow controllers:
+* - `restart`: retry failed commands with configurable delay/backoff
+* - `teardown`: run cleanup commands after all processes complete
+* - `timings`: print a timing summary table
+* @param commands Array of command strings or config objects
+* @param options Runner options (maxProcesses, killOthers, restart, teardown, etc.)
+* @returns Promise resolving to the run result with close events and success status
+*/
+declare const runConcurrently: (commands: ConcurrentCommandInput[], options?: ConcurrentRunnerOptions) => Promise<ConcurrentRunResult>;
+/**
+* Run commands concurrently using pure JavaScript (child_process.spawn).
+* This is the fallback when the native Rust addon is unavailable.
+*/
+declare const runConcurrentFallback: (commands: ConcurrentCommandConfig[], options: ConcurrentRunnerOptions) => Promise<ConcurrentRunResult>;
+/**
+* The default task runner implementation.
+*
+* Runs tasks with caching, scheduling, and lifecycle support.
+* Supports two caching modes:
+*
+* 1. **Nx-style** (default): Explicit input declarations with upfront hash computation.
+* 2. **Auto-fingerprint** (Vite Task-style): Set `autoFingerprint: true` to automatically
+* track file accesses and use them for cache invalidation.
+* @example
+* ```ts
+* import { defaultTaskRunner } from "@visulima/task-runner";
+*
+* // Nx-style (explicit inputs)
+* const results = await defaultTaskRunner(tasks, options, context);
+*
+* // Vite Task-style (auto-fingerprinting)
+* const results = await defaultTaskRunner(tasks, {
+*     ...options,
+*     autoFingerprint: true,
+*     fingerprintEnvPatterns: ["VITE_*", "NODE_ENV"],
+*     cacheDiagnostics: true,
+* }, context);
+*
+* // With remote cache
+* const results = await defaultTaskRunner(tasks, {
+*     ...options,
+*     remoteCache: {
+*         url: "https://cache.example.com",
+*         token: process.env.CACHE_TOKEN,
+*         teamId: "my-team",
+*     },
+* }, context);
+*
+* // Dry-run (inspect hashes without executing)
+* const results = await defaultTaskRunner(tasks, {
+*     ...options,
+*     dryRun: true,
+* }, context);
+* ```
+*/
+declare const defaultTaskRunner: (_tasks: Task[], options: TaskRunnerOptions, context: TaskRunnerContext) => Promise<TaskResults>;
+/**
+* Detect the npm script-shell configuration.
+*
+* Returns the shell path if configured, or undefined to use platform defaults.
+* The result is cached after the first call.
+*/
+declare const detectScriptShell: () => string | undefined;
+interface InputHandlerOptions {
+  /** Default command index to route unprefixed input to. Default: 0. */
+  defaultTarget?: number;
+  /** Stream to read input from. Default: process.stdin. */
+  inputStream?: Readable;
+  /** Whether to pause the input stream when all processes finish. Default: true. */
+  pauseOnFinish?: boolean;
+}
+interface CommandStdin {
+  index: number;
+  name?: string;
+  stdin: Writable;
+}
+/**
+* Creates an input handler that routes stdin to child processes.
+* @param commands Map of command index/name to their stdin streams
+* @param options Input handler configuration
+* @returns cleanup function to call when done
+*/
+declare const createInputHandler: (commands: CommandStdin[], options?: InputHandlerOptions) => (() => void);
+/**
+* Generate a timing summary table string from close events.
+* @param closeEvents Close events from the concurrent run (in completion order)
+* @returns Formatted table string
+*/
+declare const formatTimingTable: (closeEvents: ConcurrentCloseEvent[]) => string;
+/**
+* Print timing summary to a writable stream.
+* @param closeEvents Close events from the concurrent run
+* @param output Output stream (default: process.stdout)
+*/
+declare const logTimings: (closeEvents: ConcurrentCloseEvent[], output?: NodeJS.WritableStream) => void;
+interface RestartOptions {
+  /** Delay between restarts in milliseconds. "exponential" for 2^attempt * 1000ms. */
+  delay: number | "exponential";
+  /**
+  * Optional pre-restart callback. Fires once per scheduled retry,
+  * **after** the failed attempt is detected and **before** the restart
+  * delay sleeps — giving callers a chance to log, emit metrics, or
+  * abort the retry by throwing.
+  *
+  * `attempt` is 1-indexed and counts the retry that's about to start
+  * (the original failed run was attempt 0). `commandIndex` matches
+  * the position of the failing command in the input array.
+  *
+  * Throwing aborts the entire `withRestart` batch — the rejection
+  * surfaces from `runConcurrently` to the caller, mirroring the
+  * existing error path. Use this to gate retries on external state
+  * (budget exhaustion, circuit breakers).
+  */
+  onRetry?: (attempt: number, commandIndex: number, prevExitCode: number) => Promise<void> | void;
+  /** Maximum number of restart attempts per command. 0 = no restarts. -1 = infinite. */
+  tries: number;
+}
+/**
+* Wraps a runner function to add restart-on-failure behavior.
+* @param runFn The underlying runner function (runConcurrently or runConcurrentFallback)
+* @param commands The original command configs
+* @param options Runner options
+* @param restartOptions Restart-specific options
+*/
+declare const withRestart: (runFunction: (commands: ConcurrentCommandConfig[], options: ConcurrentRunnerOptions) => Promise<ConcurrentRunResult>, commands: ConcurrentCommandConfig[], options: ConcurrentRunnerOptions, restartOptions: RestartOptions) => Promise<ConcurrentRunResult>;
+interface TeardownOptions {
+  /** Commands to run in sequence after all processes complete. */
+  commands: string[];
+  /** Working directory for teardown commands. */
+  cwd?: string;
+}
+/**
+* Run teardown commands sequentially.
+* Each command runs in the shell with inherited stdio.
+* If a command fails, subsequent commands are still attempted.
+* @returns Array of exit codes for each teardown command
+*/
+declare const runTeardown: (options: TeardownOptions) => Promise<number[]>;
+/**
+* Detected framework information.
+*/
+interface DetectedFramework {
+  /** The env var prefix(es) that should be included in task hashes */
+  envPrefixes: string[];
+  /** The framework name */
+  name: string;
+}
+/**
+* Detects frameworks used in a project by inspecting its package.json dependencies.
+* @param packageJsonPath Absolute path to the package.json file
+* @returns Array of detected frameworks with their env prefixes
+*/
+declare const detectFrameworks: (packageJsonPath: string) => Promise<DetectedFramework[]>;
+/**
+* Detects frameworks across all projects in a workspace and returns
+* the env var patterns that should be included in task hashes.
+* @param workspaceRoot The workspace root directory
+* @param projects Map of project name to project configuration with root paths
+* @returns Array of env var wildcard patterns (e.g., ["NEXT_PUBLIC_*", "VITE_*"])
+*/
+declare const inferFrameworkEnvPatterns: (workspaceRoot: string, projects: Record<string, {
+  root: string;
+}>) => Promise<string[]>;
+/**
+* For a specific project, detects frameworks and returns the matching
+* env vars from the current environment.
+* @param packageJsonPath Absolute path to the project's package.json
+* @param env The current environment variables
+* @returns Map of env var name to value for matching framework env vars
+*/
+declare const getFrameworkEnvVariables: (packageJsonPath: string, env?: Record<string, string | undefined>) => Promise<Record<string, string>>;
+/**
+* Graph visualization output formats.
+*/
+type GraphFormat = "dot" | "json" | "html" | "ascii";
+/**
+* Options for graph visualization.
+*/
+interface GraphVisualizerOptions {
+  /** Show only affected/filtered tasks (highlight subset) */
+  focusedTasks?: string[];
+  /** Group tasks by project (default: true) */
+  groupByProject?: boolean;
+  /** Show task status colors (requires results) */
+  taskStatuses?: Map<string, "success" | "failure" | "skipped" | "local-cache" | "local-cache-kept-existing" | "remote-cache" | "running" | "pending">;
+}
+/**
+* Exports a task graph in DOT format for Graphviz rendering.
+* @example
+* ```ts
+* const dot = toGraphvizDot(taskGraph);
+* // Render: dot -Tsvg -o graph.svg <<< "$dot"
+* ```
+*/
+declare const toGraphvizDot: (taskGraph: TaskGraph, options?: GraphVisualizerOptions) => string;
+/**
+* Exports the task graph as a JSON object suitable for visualization tools.
+*/
+interface GraphJson {
+  edges: {
+    source: string;
+    target: string;
+  }[];
+  nodes: {
+    configuration?: string;
+    id: string;
+    project: string;
+    status?: string;
+    target: string;
+  }[];
+  roots: string[];
+}
+declare const toGraphJson: (taskGraph: TaskGraph, taskStatuses?: Map<string, string>) => {
+  edges: GraphJson["edges"];
+  nodes: GraphJson["nodes"];
+  roots: string[];
+};
+/**
+* Generates a self-contained HTML file with an interactive task graph visualization.
+* Uses a simple force-directed layout with SVG rendering (no external dependencies).
+*/
+declare const toGraphHtml: (taskGraph: TaskGraph, options?: GraphVisualizerOptions) => string;
+/**
+* Renders the task graph as ASCII art for terminal display.
+* @example
+* ```
+* Task Graph (6 tasks, 5 dependencies)
+*
+* app:build
+* ├── lib-a:build
+* │   └── lib-core:build
+* └── lib-b:build
+*     └── lib-core:build (*)
+*
+* (*) = already shown above
+* ```
+*/
+declare const toGraphAscii: (taskGraph: TaskGraph, options?: GraphVisualizerOptions) => string;
+/**
+* Exports a project graph in DOT format.
+*/
+declare const projectGraphToDot: (projectGraph: ProjectGraph) => string;
+/**
+* Incremental file hasher that only re-hashes files that have changed
+* since the last run, based on mtime comparison.
+*
+* This is the key performance optimization used by Nx's daemon and
+* Turborepo's daemon — on subsequent runs, only files whose mtime
+* changed need to be re-read and re-hashed.
+*
+* The snapshot (path → { mtime, hash }) is kept in memory and can
+* optionally be persisted to disk for cross-process reuse.
+*/
+interface FileSnapshot {
+  /** xxh3-128 hash of file contents */
+  hash: string;
+  /** Last modification time in milliseconds */
+  mtimeMs: number;
+  /** File size in bytes (fast pre-check) */
+  size: number;
+}
+interface IncrementalHasherOptions {
+  /** Directories to skip (default: node_modules, .git, dist, coverage, .cache) */
+  ignoredDirs?: Set<string>;
+  /** File to persist the snapshot to (for cross-run reuse) */
+  snapshotPath?: string;
+  workspaceRoot: string;
+}
+declare class IncrementalFileHasher {
+  #private;
+  constructor(options: IncrementalHasherOptions);
+  /**
+  * Loads the snapshot from disk if available.
+  * Called automatically on first use.
+  */
+  load(): Promise<void>;
+  /**
+  * Persists the current snapshot to disk for cross-run reuse.
+  */
+  save(): Promise<void>;
+  /**
+  * Incrementally hashes all files in a directory.
+  *
+  * Only files whose mtime or size changed since the last snapshot
+  * are re-read and re-hashed. Unchanged files reuse the cached hash.
+  *
+  * Returns a map of relative paths → hashes.
+  */
+  hashDirectory(directoryPath: string): Promise<Record<string, string>>;
+  /**
+  * Returns how many files are in the snapshot (for diagnostics).
+  */
+  get snapshotSize(): number;
+  /**
+  * Clears the in-memory snapshot.
+  */
+  clear(): void;
+  /**
+  * Looks up the cached hash for `absolutePath` when its mtime and
+  * size match the snapshot; returns `undefined` otherwise. Callers
+  * that already have a `stat` result (e.g. `InProcessTaskHasher`)
+  * skip an extra syscall by passing it through directly.
+  *
+  * The snapshot is considered loaded on first call — lazy-load is
+  * synchronous-friendly here because the caller already performed
+  * an async `stat` before calling this method.
+  */
+  getSnapshotHash(absolutePath: string, mtimeMs: number, size: number): string | undefined;
+  /**
+  * Writes a fresh snapshot entry after the caller has computed the
+  * hash. Pairs with {@link IncrementalFileHasher.getSnapshotHash}
+  * — after a miss, the caller hashes the file and records the
+  * result here so the next run can reuse it.
+  */
+  recordSnapshot(absolutePath: string, hash: string, mtimeMs: number, size: number): void;
+}
+/**
+* Combines multiple lifecycle handlers into one.
+* Each event is forwarded to all registered handlers.
+*/
+declare class CompositeLifeCycle implements LifeCycleInterface {
+  #private;
+  constructor(lifeCycles: LifeCycleInterface[]);
+  startCommand(): void;
+  endCommand(): void;
+  scheduleTask(task: Task): void;
+  startTasks(tasks: Task[]): void;
+  endTasks(taskResults: TaskResult[]): void;
+  printTaskTerminalOutput(task: Task, status: TaskStatus, terminalOutput: string): void;
+  printCacheMiss(task: Task, reasons: string): void;
+  printCacheDisabledByTask(task: Task): void;
+  printEmptyFingerprintWarning(task: Task, reason: string): void;
+  printSelfModifyingSkip(task: Task, modifiedFiles: string[]): void;
+  onTaskStdout(task: Task, chunk: string): void;
+  onTaskStderr(task: Task, chunk: string): void;
+}
+/**
+* A lifecycle handler that logs task progress to the console.
+*/
+declare class ConsoleLifeCycle implements LifeCycleInterface {
+  #private;
+  constructor(verbose?: boolean);
+  startCommand(): void;
+  endCommand(): void;
+  scheduleTask(task: Task): void;
+  startTasks(tasks: Task[]): void;
+  endTasks(taskResults: TaskResult[]): void;
+  printTaskTerminalOutput(_task: Task, _status: TaskStatus, terminalOutput: string): void;
+  printCacheMiss(task: Task, reasons: string): void;
+}
+/**
+* A no-op lifecycle handler. Useful as a default.
+*/
+declare class EmptyLifeCycle implements LifeCycleInterface {}
+/**
+* Resolved dependency entry from a lockfile.
+*/
+interface ResolvedDependency {
+  /** The package name */
+  name: string;
+  /** The resolved version */
+  version: string;
+}
+/**
+* Result of parsing a lockfile for a specific package.
+*/
+interface PackageLockfileHash {
+  /** The resolved dependencies that were included in the hash */
+  dependencies: ResolvedDependency[];
+  /** Hash of the resolved dependencies relevant to this package */
+  hash: string;
+}
+/**
+* Extracts a package name from a node_modules path.
+* E.g., "node_modules/@scope/name" -> "@scope/name",
+* "node_modules/name" -> "name",
+* "node_modules/.package-lock.json" -> undefined.
+*/
+declare const extractPackageName: (path: string) => string | undefined;
+/**
+* Parses package-lock.json (npm v2/v3 format) to extract resolved versions.
+* The v2/v3 format uses a flat "packages" map with paths like "node_modules/pkg-name".
+*/
+declare const parseNpmLockfile: (content: string) => Map<string, string>;
+/**
+* Parses pnpm-lock.yaml to extract resolved versions.
+* Uses a lightweight regex-based parser to avoid a YAML dependency.
+*/
+declare const parsePnpmLockfile: (content: string) => Map<string, string>;
+/**
+* Parses yarn.lock to extract resolved versions.
+* Works with both Yarn Classic (v1) and Berry (v2+) formats.
+*/
+declare const parseYarnLockfile: (content: string) => Map<string, string>;
+/**
+* Smart lockfile hasher that only hashes the resolved versions
+* of a package's actual dependencies, not the entire lockfile.
+*
+* This matches Turborepo's smart lockfile hashing behavior:
+* changing the lockfile only busts cache for affected packages.
+*
+* Supports:
+* - package-lock.json (npm v2/v3)
+* - pnpm-lock.yaml (pnpm)
+* - yarn.lock (Yarn Classic + Berry)
+*/
+declare class LockfileHasher {
+  #private;
+  constructor(workspaceRoot: string);
+  /**
+  * Computes a hash based only on the resolved dependency versions
+  * relevant to a specific package.
+  * @param packageJsonPath Path to the package.json (relative to workspace root)
+  * @returns Hash of the relevant lockfile entries, or undefined if no lockfile found
+  */
+  hashForPackage(packageJsonPath: string): Promise<PackageLockfileHash | undefined>;
+  /**
+  * Returns the type of lockfile detected, or undefined if none found.
+  */
+  get lockfileType(): "npm" | "pnpm" | "yarn" | undefined;
+  /**
+  * Clears the cached lockfile data.
+  */
+  clearCache(): void;
+}
+/**
+* Output formatting mode for task terminal output.
+*
+* - `interleaved` **(default)**: emit each task's buffered output as-is
+*   — lines from parallel tasks may intermix when streamed live.
+* - `labeled`: prefix every line with `[project#target]` so parallel
+*   tasks remain distinguishable.
+* - `grouped`: buffer each task's output and print it as a single block
+*   bracketed by `── project#target ──` header and blank-line footer.
+*
+* Matches the three modes exposed by vite-task's `--log` flag.
+*/
+type LogMode = "grouped" | "interleaved" | "labeled";
+/**
+* How the reporter handles ANSI escape sequences in the buffered output
+* it receives.
+*
+* - `auto` **(default)**: detect color capability of the write target;
+*   strip escapes when stdout isn't a TTY, `NO_COLOR` is set, or
+*   `TERM=dumb`. Matches what colorize libraries do for live output.
+* - `always`: keep escapes — useful when piping into another tool that
+*   understands ANSI.
+* - `never`: always strip — useful for log files / JSON-collecting CI.
+*
+* Live spawn output is captured with `FORCE_COLOR=1` so cache entries
+* always contain colored bytes; without this control, replaying a cache
+* hit into a non-color destination prints raw escape sequences. See
+* voidzero-dev/vite-task#358 / #378.
+*/
+type ColorMode = "always" | "auto" | "never";
+/**
+* A lifecycle handler that renders task terminal output per {@link LogMode}.
+*
+* Operates on the buffered `printTaskTerminalOutput` signal the orchestrator
+* emits at task-completion. Line-by-line streaming is the consumer's
+* responsibility — a streaming reporter can wrap this one and emit buffered
+* output at the end of each task regardless of streaming choices.
+*/
+declare class LogReporter implements LifeCycleInterface {
+  #private;
+  constructor(mode: LogMode, write?: (chunk: string) => void, color?: ColorMode);
+  printTaskTerminalOutput(task: Task, _status: TaskStatus, terminalOutput: string): void;
+  endTasks(_taskResults: TaskResult[]): void;
+}
+/**
+* Convenience factory matching vite-task's `createLogReporter(mode)` surface.
+* Consumers that already compose their own lifecycle handlers can instantiate
+* {@link LogReporter} directly.
+*/
+declare const createLogReporter: (mode: LogMode, write?: (chunk: string) => void, color?: ColorMode) => LogReporter;
+interface NativeFileHash {
+  hash: string;
+  path: string;
+}
+interface NativeTaskHashDetails {
+  command: string;
+  implicit_deps?: string[][];
+  nodes: string[][];
+  runtime?: string[][];
+}
+interface NativeTaskGraph {
+  edges: string[][];
+  task_ids: string[];
+}
+interface NativeCycleResult {
+  cycle: string[];
+  has_cycle: boolean;
+}
+interface NativeConcurrentCommandConfig {
+  command: string;
+  cwd?: string;
+  env?: Record<string, string>;
+  name?: string;
+  shell?: boolean;
+  stdin?: string;
+}
+interface NativeConcurrentRunnerOptions {
+  killOthers?: string[];
+  killSignal?: string;
+  killTimeout?: number;
+  maxProcesses?: number;
+  shellPath?: string;
+  successCondition?: string;
+}
+interface NativeProcessEvent {
+  commandName?: string;
+  durationMs?: number;
+  exitCode?: number;
+  index: number;
+  killed?: boolean;
+  kind: string;
+  message?: string;
+  pid?: number;
+  text?: string;
+}
+interface NativeConcurrentCloseEvent {
+  command: string;
+  durationMs: number;
+  exitCode: number;
+  index: number;
+  killed: boolean;
+  name?: string;
+}
+interface NativeConcurrentRunResult {
+  closeEvents: NativeConcurrentCloseEvent[];
+  success: boolean;
+}
+interface NativeBindings {
+  collectFiles: (directory: string) => string[];
+  computeTaskHash: (details: NativeTaskHashDetails) => string;
+  findAllCycles: (graph: NativeTaskGraph) => string[][];
+  findBackEdges: (graph: NativeTaskGraph) => string[][];
+  findCycle: (graph: NativeTaskGraph) => NativeCycleResult;
+  getDependentTasks: (graph: NativeTaskGraph, taskId: string) => string[];
+  getMainWorktreeRoot: (workspaceRoot: string) => string | undefined | null;
+  getTransitiveDeps: (graph: NativeTaskGraph, taskId: string) => string[];
+  hashCommand: (project: string, target: string, configuration: string | undefined, overridesJson: string) => string;
+  hashEnvVar: (name: string, value: string) => string;
+  hashFile: (filePath: string) => string;
+  hashFilesBatch: (filePaths: string[], workspaceRoot: string) => NativeFileHash[];
+  hashFilesInDirectory: (directory: string, workspaceRoot: string) => NativeFileHash[];
+  hashString: (input: string) => string;
+  hashStrings: (inputs: string[]) => string;
+  isLinkedWorktree: (workspaceRoot: string) => boolean;
+  resetWorktreeCache: () => void;
+  runConcurrent: (commands: NativeConcurrentCommandConfig[], options: NativeConcurrentRunnerOptions, onEvent: (event: NativeProcessEvent) => void) => Promise<NativeConcurrentRunResult>;
+  runConcurrentBatch: (commands: NativeConcurrentCommandConfig[], options: NativeConcurrentRunnerOptions, onLifecycle?: ((event: NativeProcessEvent) => void) | null) => Promise<NativeConcurrentRunResult>;
+  topologicalSort: (graph: NativeTaskGraph) => string[];
+  /**
+  * Windows-only: spawn the directly-exec'd `argv` suspended, inject
+  * the `fspy_windows` DLL (at `dllPath`) via
+  * `CreateRemoteThread(LoadLibraryW)`, and collect the IAT-hooked
+  * accesses streamed over a named pipe. Same result shape as
+  * `trackWithSeccomp`. Present only when the addon was built for a
+  * Windows target.
+  */
+  trackWithIatHook?: (argv: string[], dllPath: string, options?: NativeSeccompSpawnOptions, onStarted?: (pid: number) => void) => Promise<NativeSeccompTrackingResult>;
+  /**
+  * macOS-only: spawn the directly-exec'd `argv` with the
+  * `fspy_macos` interpose dylib (at `dylibPath`) injected via
+  * `DYLD_INSERT_LIBRARIES` and collect reported accesses. Same
+  * result shape as `trackWithSeccomp`. Present only when the
+  * addon was built for a macOS target.
+  */
+  trackWithInterpose?: (argv: string[], dylibPath: string, options?: NativeSeccompSpawnOptions, onStarted?: (pid: number) => void) => Promise<NativeSeccompTrackingResult>;
+  /**
+  * Linux-only: spawn `argv` under seccomp_unotify tracking via
+  * the helper binary at `helperPath`. Resolves once the child
+  * exits with the gathered file accesses.
+  *
+  * `onStarted` (when supplied) fires once with the helper PID
+  * as soon as the spawn succeeds. The PID survives the
+  * helper→target execve, so callers can SIGTERM it via
+  * `process.kill(pid)` to abort the traced command.
+  *
+  * Undefined when the addon was built on a non-Linux target.
+  */
+  trackWithSeccomp?: (argv: string[], helperPath: string, options?: NativeSeccompSpawnOptions, onStarted?: (pid: number) => void) => Promise<NativeSeccompTrackingResult>;
+}
+interface NativeSeccompSpawnOptions {
+  cwd?: string;
+  /** Extra env vars merged on top of the parent's. */
+  env?: Record<string, string>;
+}
+interface NativeSeccompFileAccess {
+  kind: "missing" | "read" | "readdir" | "stat" | "write";
+  path: string;
+}
+interface NativeSeccompTrackingResult {
+  accesses: NativeSeccompFileAccess[];
+  exitCode: number;
+  stderr: Buffer;
+  stdout: Buffer;
+}
+/**
+* Attempts to load the native addon. Returns undefined if unavailable.
+* The result is cached after the first attempt.
+*
+* napi v3 outputs the .node file to the package root as
+* `task-runner-native.&lt;platform>.node`. The napi-generated index.js
+* handles platform detection automatically.
+*
+* Uses createRequire because the napi-generated index.js is CJS.
+*/
+declare const loadNativeBindings: () => NativeBindings | undefined;
+/**
+* Returns true if the native addon is loaded and available.
+*/
+declare const isNativeAvailable: () => boolean;
+/**
+* Expands a task's `OutputSpec[]` into the concrete file list to
+* archive:
+*
+* - literal paths → kept as-is (the archiver recursively copies
+*   directories, so `"dist"` captures its whole tree);
+* - positive globs → expanded via `fs.glob`, filtered to files only;
+* - negatives (`!pattern`) → applied to the combined result;
+* - `{ auto: true }` → pulls in `autoWrites` entries that fall inside
+*   the workspace.
+*
+* Returns deduped, sorted workspace-relative paths so archives are
+* byte-reproducible across invocations.
+*
+* Silent degradation: missing literal paths, empty glob matches, and
+* `{ auto: true }` without tracked writes all contribute nothing
+* rather than throwing.
+*/
+declare const resolveOutputs: (workspaceRoot: string, outputs: OutputSpec[] | undefined, autoWrites?: ReadonlyArray<string>) => Promise<string[]>;
+/**
+* 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".
+*/
+declare const INPUT_URI_SCHEMES: readonly ["file", "glob", "env", "func", "dep"];
+type InputUriScheme = (typeof INPUT_URI_SCHEMES)[number];
+/**
+* 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).
+*
+* 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.
+*/
+declare class InvalidInputUriError extends Error {
+  constructor(message: string);
+}
+/**
+* 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).
+*/
+declare const parseInputUri: (input: string) => InputDefinition | undefined;
+/**
+* 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 const looksLikeInputUri: (input: string) => boolean;
+/**
+* Walks from `cwd` (resolved against `process.cwd()` when relative)
+* up to the filesystem root, returning every `&lt;dir>/node_modules/.bin`
+* path encountered. Ordered nearest-first so the cwd-local `.bin`
+* shadows ancestor `.bin` directories, matching npm/pnpm semantics.
+*
+* The returned paths are not stat-checked — missing directories cost
+* nothing on the PATH and avoiding the syscalls keeps task startup
+* cheap (this runs once per spawned task).
+*/
+declare const collectNodeModulesBinDirs: (cwd: string) => string[];
+/**
+* Returns the enhanced PATH string for a child process spawned in
+* `cwd`. The caller's PATH (from `callerEnv` or, when unset, the
+* current `process.env`) is preserved as the suffix so system binaries
+* still resolve; the workspace's `node_modules/.bin` chain is prepended.
+*
+* Use this when building the `env` you hand to `child_process.spawn`
+* / `exec` / `tinyexec` for commands that come from `package.json`
+* scripts or any other user-authored shell string.
+*/
+declare const buildEnhancedPath: (cwd: string, callerEnv?: NodeJS.ProcessEnv | Record<string, string | undefined>) => string;
+/**
+* Convenience helper that returns a shallow-cloned `env` with the
+* enhanced PATH applied. Leaves the original object untouched so it
+* remains safe to share across concurrent spawns. The Windows `Path`
+* alias is also rewritten when present to avoid mixed-case clashes
+* where two PATH-shaped keys would otherwise disagree.
+*/
+declare const withEnhancedPath: <T extends NodeJS.ProcessEnv | Record<string, string | undefined>>(env: T, cwd: string) => T;
+/**
+* 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 {
+  /**
+  * Invoked once per dependency cycle that {@link createTaskGraph}
+  * breaks because it runs *solely* through soft (devDependency)
+  * edges. The argument is the cycle as a closed path of task ids
+  * (`[a, b, …, a]`). Consumers can surface this as a warning; cycles
+  * that contain a hard (static) edge are left intact and never
+  * reported here.
+  */
+  onCycleBroken?: (cycle: string[]) => void;
+  /** The project graph */
+  projectGraph: ProjectGraph;
+  /** Target default configurations */
+  targetDefaults?: Record<string, Partial<TargetConfiguration>>;
+  /** The workspace configuration */
+  workspace: WorkspaceConfiguration;
+}
+/**
+* Creates a unique task ID from a target.
+*/
+declare const getTaskId: (target: TaskTarget) => string;
+/**
+* Parses a task ID into its component parts.
+*/
+declare const parseTaskId: (taskId: string) => TaskTarget;
+/**
+* Creates a task graph from a list of tasks, resolving all dependencies.
+*/
+declare const createTaskGraph: (initialTasks: Task[], options: CreateTaskGraphOptions) => TaskGraph;
+/**
+* Finds a single cycle in the task graph, if one exists.
+* Returns the cycle as an array of task IDs, or null if no cycle exists.
+*/
+declare const findCycle: (taskGraph: TaskGraph) => string[] | undefined;
+/**
+* Finds all cycles in the task graph.
+*/
+declare const findCycles: (taskGraph: TaskGraph) => string[][];
+/**
+* Walks the task graph in topological order (dependencies before dependents),
+* calling the callback for each task.
+*
+* Note: If the graph contains cycles, tasks involved in cycles will not be visited.
+* Use `findCycle` to detect cycles before walking if complete traversal is required.
+*/
+declare const walkTaskGraph: (taskGraph: TaskGraph, callback: (taskId: string) => void) => void;
+/**
+* Returns a reversed copy of the task graph (edges point in the opposite direction).
+*/
+declare const reverseTaskGraph: (taskGraph: TaskGraph) => TaskGraph;
+/**
+* Returns the leaf tasks (tasks with no dependencies of their own).
+*/
+declare const getLeafTasks: (taskGraph: TaskGraph) => string[];
+/**
+* Removes edges that form cycles, making the graph acyclic.
+* Returns a new task graph without the cycle-forming edges.
+*/
+declare const makeAcyclic: (taskGraph: TaskGraph) => TaskGraph;
+/**
+* Gets all tasks that depend on the given task (directly or transitively).
+*/
+declare const getDependentTasks: (taskGraph: TaskGraph, taskId: string) => string[];
+/**
+* Gets all tasks that the given task depends on (directly or transitively).
+*/
+declare const getTransitiveDependencies: (taskGraph: TaskGraph, taskId: string) => string[];
+/**
+* Interface for task hashers.
+*/
+interface TaskHasher {
+  hashTask: (task: Task) => Promise<TaskHashDetails>;
+  /**
+  * Rehashes a single file bypassing any in-memory cache. Optional to keep
+  * external/custom hashers backward compatible; the orchestrator skips
+  * self-modifying-task detection when the implementation is absent.
+  */
+  rehashFile?: (filePath: string) => Promise<string | undefined>;
+}
+/**
+* Options for creating an InProcessTaskHasher.
+*/
+interface TaskHasherOptions {
+  /**
+  * When true, scan each task's resolved command for `$VAR`/`${VAR}`
+  * references and auto-fingerprint them. Catches the common case of
+  * a script reading `$VERCEL_URL` or `${NEXT_PUBLIC_API}` without
+  * the user remembering to declare it in `envVars`/`globalEnv`.
+  * @default false
+  */
+  autoEnvVars?: boolean;
+  /** Additional environment variables to include in hash */
+  envVars?: string[];
+  /**
+  * Enable framework environment variable inference.
+  * When true, auto-detects frameworks and includes their public
+  * env var prefixes in the task hash.
+  * @default false
+  */
+  frameworkInference?: boolean;
+  /**
+  * Global environment variables that invalidate all task hashes.
+  */
+  globalEnv?: string[];
+  /**
+  * Global input files that invalidate all task hashes when changed.
+  * These are workspace-root-relative paths (e.g., "pnpm-lock.yaml").
+  */
+  globalInputs?: string[];
+  /**
+  * Optional persistent mtime/size-indexed file snapshot. When set,
+  * `#hashFile` consults the snapshot first and only re-reads file
+  * contents when the file's mtime or size has changed since the
+  * previous run. Cuts cold-cache fingerprint time dramatically on
+  * large workspaces where most source files don't change run-to-run.
+  *
+  * The caller is responsible for `load()`ing the snapshot before
+  * using the hasher and `save()`ing it after the run completes.
+  */
+  incrementalHasher?: IncrementalFileHasher;
+  /** Named input definitions */
+  namedInputs?: NamedInputs;
+  /**
+  * Plugin hook fired during fingerprint construction. See
+  * {@link FingerprintHook} for the contract — throwing aborts
+  * hashing for the offending task.
+  */
+  onFingerprint?: FingerprintHook;
+  /** Project configurations keyed by project name */
+  projects: Record<string, ProjectConfiguration>;
+  /**
+  * Enable smart lockfile hashing.
+  * When true, instead of hashing the entire lockfile, only the resolved
+  * versions of a package's actual dependencies are hashed.
+  * This means changing the lockfile only busts cache for affected packages.
+  *
+  * Matches Turborepo's smart lockfile hashing behavior.
+  * @default false
+  */
+  smartLockfileHashing?: boolean;
+  /** Target default configurations */
+  targetDefaults?: Record<string, Partial<TargetConfiguration>>;
+  /** The workspace root directory */
+  workspaceRoot: string;
+}
+/**
+* Computes hashes for tasks based on their inputs.
+* Used to determine if a cached result can be reused.
+*/
+declare class InProcessTaskHasher implements TaskHasher {
+  #private;
+  constructor(options: TaskHasherOptions);
+  hashTask(task: Task): Promise<TaskHashDetails>;
+  clearCache(): void;
+  /**
+  * Reads `filePath` fresh and returns its content hash, bypassing the
+  * in-memory cache used during the initial `hashTask` pass.
+  *
+  * Used to detect tasks that modify their own tracked inputs: compare
+  * a pre-execution hash (from `task.hashDetails.nodes`) against the
+  * post-execution result of this method.
+  * @param filePath Absolute path to the file.
+  * @returns The fresh xxh3 hash, or `undefined` if the file cannot be read.
+  */
+  rehashFile(filePath: string): Promise<string | undefined>;
+}
+/**
+* Computes the final hash for a task from its hash details.
+* Uses native Rust xxh3-128 when available, otherwise pure TS xxh3-ts.
+* Both produce identical xxh3-128 hashes, ensuring cache compatibility
+* regardless of whether the native addon is loaded.
+*/
+declare const computeTaskHash: (hashDetails: TaskHashDetails) => string;
+/**
+* Options for partitioning tasks across CI runners.
+*/
+interface PartitionOptions {
+  /** 1-based partition index (e.g., 1 for the first partition) */
+  index: number;
+  /** Total number of partitions */
+  total: number;
+}
+/**
+* Parses a partition string like "1/4" into PartitionOptions.
+* Also supports the VIS_PARTITION environment variable as fallback.
+*/
+declare const parsePartition: (value?: string) => PartitionOptions | undefined;
+/**
+* Manages the scheduling order of tasks based on dependencies,
+* parallelism constraints, and estimated execution times.
+*/
+declare class TaskScheduler {
+  #private;
+  /**
+  * Partitions a list of tasks for distributed CI execution.
+  * Tasks are sorted by ID for deterministic distribution, then split
+  * using ceiling division so partitions differ by at most one task.
+  * @param tasks The full list of tasks to partition
+  * @param partition The partition configuration (1-based index and total)
+  * @returns The subset of tasks assigned to this partition
+  */
+  static partitionTasks(tasks: Task[], partition: PartitionOptions): Task[];
+  constructor(taskGraph: TaskGraph, projectGraph: ProjectGraph, maxParallel?: number, concurrencyGroups?: ConcurrencyGroups);
+  /**
+  * Returns the next batch of tasks that are ready to execute.
+  *
+  * Slot accounting is weighted: a task's `concurrencyWeight` (default
+  * `1`) counts against the global `parallel` cap. A heavier task may
+  * still run alone — when nothing is in flight, the scheduler always
+  * admits at least one ready task even if its weight exceeds the cap,
+  * so a `parallel: 1` pool can't deadlock on a weight-3 task.
+  */
+  getNextBatch(): Task[];
+  startTask(taskId: string): void;
+  completeTask(taskId: string): void;
+  isComplete(): boolean;
+  get remainingCount(): number;
+  get runningCount(): number;
+  /**
+  * Returns dep-id refs the task graph carries that don't resolve to
+  * any task in `tasks`, keyed by the task that declared them. The
+  * scheduler treats these as already-completed so the run can
+  * proceed, but the orchestrator surfaces this map as a warning at
+  * run start so the underlying input bug (vis / config emitting
+  * dangling refs) doesn't go silently masked.
+  */
+  getOrphanDependencies(): Map<string, string[]>;
+  /**
+  * Returns task ids that are not in `completedTasks` and not in
+  * `runningTasks`, along with their unmet deps after orphan refs
+  * have been filtered out. The orchestrator's deadlock error reads
+  * this so the message can name the actual stranded tasks instead
+  * of a generic "may indicate a circular dependency" hint.
+  */
+  describeStrandedTasks(): {
+    id: string;
+    unmetDeps: string[];
+  }[];
+}
+/**
+* Options for the TaskOrchestrator.
+*/
+interface TaskOrchestratorOptions {
+  /**
+  * Tasks marked `always: true` to run after the main task graph
+  * completes. Run sequentially, in declaration order, even if the
+  * main run failed or was aborted (SIGINT skips them — that's an
+  * explicit user request to stop). Skipped if their `when` clause
+  * doesn't match.
+  */
+  alwaysTasks?: Task[];
+  autoFingerprint?: boolean;
+  /**
+  * Failure-propagation policy.
+  *
+  * - `false` (default) — when a task fails, its transitive
+  *   dependents are marked `skipped` with a "dependency failed"
+  *   note. Tasks not downstream of the failure still run. Prevents
+  *   the cascade failures that result from running a dependent on
+  *   a missing `dist/` produced by the failed dep.
+  * - `true` — fail-fast. On the first failure every task that
+  *   hasn't started is marked `skipped`; in-flight tasks are
+  *   allowed to finish.
+  */
+  bail?: boolean;
+  cache: Cache;
+  cacheDiagnostics?: boolean;
+  captureOutput?: boolean;
+  /**
+  * Directory used to persist run summaries. Forwarded to
+  * {@link writeRunSummary} / {@link writeLastRunSummary} so
+  * embedders (vis) can redirect run-scoped state away from the
+  * default `{workspaceRoot}/.task-runner`.
+  */
+  dataDirectory?: string;
+  dryRun?: boolean;
+  fingerprintEnvPatterns?: string[];
+  lifeCycle: LifeCycleInterface;
+  /**
+  * 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;
+  summarize?: boolean;
+  taskExecutor: TaskExecutor;
+  taskGraph?: TaskGraph;
+  taskHasher: TaskHasher;
+  untrackedEnvVars?: string[];
+  /**
+  * Context used to evaluate per-task `when` conditions. Defaults
+  * to the live process state — `process.env`, `process.platform`,
+  * git branch read from `workspaceRoot`. Override in tests.
+  */
+  whenContext?: WhenContext;
+  workspaceRoot: string;
+}
+/**
+* Orchestrates the execution of tasks, handling caching,
+* scheduling, and lifecycle events.
+*/
+declare class TaskOrchestrator {
+  #private;
+  constructor(options: TaskOrchestratorOptions);
+  run(): Promise<TaskResults>;
+}
+/**
+* Minimal virtual terminal buffer that processes ANSI escape sequences
+* for cursor movement and line erasure. This allows PTY output from
+* interactive tools (inquirer, etc.) to render correctly by updating
+* lines in place rather than always appending.
+*
+* Supported sequences:
+* - \r       carriage return (cursor to column 0)
+* - \n       line feed (new line)
+* - \x1b[nA  cursor up n lines
+* - \x1b[nB  cursor down n lines
+* - \x1b[nC  cursor forward n columns
+* - \x1b[nD  cursor back n columns
+* - \x1b[nG  cursor to column n
+* - \x1b[r;cH cursor position
+* - \x1b[K   erase from cursor to end of line (0K, 1K, 2K)
+* - \x1b[J   erase from cursor to end of display (0J, 1J, 2J)
+* - \x1b[...m SGR (colors/styles) — passed through into output
+*/
+declare class TerminalBuffer {
+  #private;
+  constructor(maxBytes?: number);
+  /**
+  * Process raw PTY output data.
+  */
+  write(data: string): void;
+  /** Get the current buffer content as a string. */
+  toString(): string;
+}
+/**
+* Hints aggregated from a task's NDJSON file, with paths resolved to
+* absolute form against the child's cwd. Consumed by the orchestrator
+* to refine the auto-fingerprint before it's sealed.
+*/
+interface CollectedHints {
+  /** The task asked not to cache this run (via `disableCache()`). */
+  cacheDisabled: boolean;
+  /** Absolute paths whose reads should be dropped from inferred inputs. */
+  ignoredInputs: string[];
+  /** Absolute paths whose writes should be dropped from inferred outputs. */
+  ignoredOutputs: string[];
+  /** Env var names registered as cache dependencies via `getEnv`. */
+  trackedEnv: string[];
+  /** Env glob patterns registered as cache dependencies via `getEnvs`. */
+  trackedEnvPatterns: string[];
+}
+/**
+* Result of a tracked task execution.
+*/
+interface TrackedExecutionResult {
+  /** File accesses recorded during execution */
+  accesses: FileAccess[];
+  /** The command exit code */
+  code: number;
+  /**
+  * Cooperative cache hints the task emitted via
+  * `@visulima/task-runner-client` ({@link CollectedHints}). Empty when
+  * the task didn't use the client.
+  */
+  hints: CollectedHints;
+  /** The command stdout + stderr output */
+  terminalOutput: string;
+}
+/**
+* A task executor that tracks file accesses during command execution.
+*
+* Tracking strategies (in priority order):
+* 1. **Linux**: strace-based syscall interception (most complete)
+* 2. **macOS/Windows**: Node.js preload script that patches `fs` module
+* (works for Node.js processes, not native binaries)
+* 3. **Fallback**: No tracking (accesses array will be empty)
+*/
+declare class TrackedTaskExecutor {
+  #private;
+  constructor(workspaceRoot: string);
+  /**
+  * Returns true if file access tracking is supported on the current platform.
+  * strace tracking (Linux) or preload script (any Node.js process).
+  */
+  get isTrackingSupported(): boolean;
+  /**
+  * Returns true if the platform supports full syscall-level tracking (strace).
+  */
+  get isStraceSupported(): boolean;
+  /**
+  * Executes a task command and tracks all file system accesses.
+  *
+  * On Linux, uses strace for comprehensive tracking.
+  * On other platforms, uses a Node.js preload script (for Node processes).
+  */
+  execute(task: Task, options: TaskExecutionOptions, command: string): Promise<TrackedExecutionResult>;
+  /**
+  * Kills all active child processes. Called on abort/signal to prevent orphans.
+  */
+  killAll(): void;
+}
+/**
+* Hashes a file's content using xxh3-128.
+* Returns undefined if the file cannot be read.
+*/
+declare const hashFile: (filePath: string) => Promise<string | undefined>;
+/**
+* Hashes one or more string values using xxh3-128.
+*/
+declare const hashStrings: (...values: string[]) => string;
+/**
+* Sorts an object's keys for deterministic serialization.
+*/
+declare const sortObjectKeys: (object: Record<string, unknown>) => Record<string, unknown>;
+/**
+* Recursively collects all file paths in a directory,
+* skipping directories in the ignored set.
+*
+* Tracks visited real paths to prevent infinite loops from symlink cycles.
+*/
+declare const collectFiles: (directory: string, ignoredDirectories: Set<string>, visitedRealPaths?: Set<string>) => Promise<string[]>;
+/**
+* Resolves the working directory for a task.
+*/
+declare const resolveTaskCwd: (workspaceRoot: string, task: Task) => string;
+/**
+* Creates a failure TaskResult from an error.
+*/
+declare const createFailureResult: (task: Task, error: unknown, startTime: number) => TaskResult;
+declare const readPackageDeps: (packageJsonPath: string, options?: {
+  optional?: boolean;
+  peer?: boolean;
+}) => Promise<Set<string> | undefined>;
+/**
+* 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;
+/**
+* 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 ConcurrencyGroups, 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, type FingerprintContributor, type FingerprintHook, 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 RemoteCacheAttestation, type RemoteCacheBackend, type RemoteCacheCompression, type RemoteCacheOptions, type RemoteCacheSigning, type ResolvedDependency, type RestartOptions, type RunSummary, type RunSummaryPathOptions, 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, buildEnhancedPath, buildForwardDependencyMap, buildReverseDependencyMap, casBlobPath, collectFiles, collectNodeModulesBinDirs, 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, resolveTurboEnvCompat, retrieveByTaskHash, reverseTaskGraph, runConcurrentFallback, runConcurrently, runTeardown, sortObjectKeys, storeByTaskHash, stripQuotes, taskHashIndexPath, toChromeTrace, toGraphAscii, toGraphHtml, toGraphJson, toGraphvizDot, touchBlob, uniqueId, verifyBlob, walkTaskGraph, withEnhancedPath, withRestart, writeChromeTrace, writeLastRunSummary, writeRunSummary };