4.1Registration

Tasks are registered via the tasks API, which is available from the public API. During config file loading, calls to tasks.register() delegate to the active Nadle instance via an AsyncLocalStorage context. Each Nadle instance owns its own task registry, ensuring full isolation between instances. A registration associates a name with an optional task body and a set of configuration fields. There are three registration forms:

For the typed-task form, the options resolver is optional when the options type has no required fields (an empty object satisfies it); in that case the options default to an empty object ({}). When the options type has at least one required field, both the body and the resolver are mandatory.

A task’s configuration (group, dependsOn, inputs, outputs, env, etc.) is provided as part of the registration alongside the body and options — it is not a separate, later step. See 02-task-configuration.md. Configuration may also be supplied lazily, deferring its resolution until the configuration is first needed (see 02-task-configuration.md).

4.2Naming Rules

Task names must match the pattern: ^[a-z]([a-z0-9-]*[a-z0-9])?$ (case-insensitive).

If a task name is invalid, registration fails with an error.

4.3Duplicate Detection

Task names must be unique within a workspace. The same name may appear in different workspaces. If a duplicate name is registered in the same workspace, registration fails with an error.

4.4Task Identity

A task is uniquely identified by a task identifier string:

The separator is a colon (:). The last segment is always the task name; preceding segments form the workspace ID.

4.5Status Lifecycle

A task moves through the following statuses:

                                    +-> Finished
                                    |
Registered -> Scheduled -> Running -+-> Failed
                  |                 |
                  |                 +-> Canceled
                  |
                  +-> UpToDate
                  |
                  +-> FromCache

4.6Reusable Task Types

The defineTask() function creates a reusable task type with a typed options contract. It is an identity function that enables type inference for the run function’s options parameter.

A reusable task type is then registered by providing it as the task body together with an options resolver that supplies the concrete options for this instance.

---

5.1Configuration Fields

All fields are optional.

5.2Supplying Configuration

Configuration is supplied as a set of fields at registration time. The configuration provided at registration is the task’s complete configuration; there is no separate merge step.

A task’s configuration may instead be supplied lazily — deferred rather than determined eagerly at registration. A lazily-supplied configuration is resolved at most once per task: it is not evaluated at registration, only when the configuration is first needed (scheduling, execution, or reporting), and the result is memoized so the deferred resolution never runs more than once for a task in a given invocation (configuration avoidance). A lazy configuration must therefore be pure with respect to that single evaluation; do not rely on a side effect running on every read.

5.3dependsOn Resolution

Dependency strings are resolved as follows:

1. No colon (e.g., "build") — resolved within the current workspace.
2. With colon (e.g., "packages:foo:build") — the last segment is the task name; preceding segments form the workspace ID. Resolved by workspace ID or label.
3. Root workspace — use "root:taskName" (root workspace ID is always "root").

A dependency is resolved only within its target workspace (the current workspace for a colon-less name, or the explicit workspace for a qualified name) — there is no implicit fallback to the root workspace. If the task is not found there, an error is raised with suggestions. To depend on a root task, qualify it explicitly with "root:taskName".

Excluded tasks (via --exclude) are filtered out of the resolved dependency set.

5.4Declarations DSL

Declarations describe file patterns for inputs and outputs. There are two types:

Outputs.files and Outputs.dirs are aliases for Inputs.files and Inputs.dirs respectively — there is no functional difference.

5.5Environment Variables

The env field accepts a map of key-value pairs where values may be strings, numbers, or booleans. Non-string values are converted to strings (via String(val)) before being applied to the worker process environment.

Environment variables are applied before the task function runs and restored to their original values afterward.

5.6Working Directory

The workingDir field is resolved relative to the project root workspace’s absolute path. If omitted, it defaults to the project root. The resolved absolute path is provided to the task function via the runner context.

5.7Timeouts and Retries

timeout (milliseconds, positive integer) bounds each execution attempt of the task function; an attempt that does not settle in time fails with a timeout error. retries (non-negative integer, default 0) is the number of additional attempts after the first failure. Together a task runs up to 1 + retries attempts and fails only if all attempts fail. Both apply only to the task function, not to cache restore. See 04-execution.md.

---

6.1DAG Construction

The scheduler maintains three internal graphs:

Additionally, an indegree map tracks the number of unresolved dependencies for each task.

6.2Cycle Detection

After analysis, cycles are detected using depth-first traversal. For each task, the scheduler walks its dependency chain. If a task is encountered that already exists in the current path, a cycle is detected.

• If a cycle is found, Nadle raises an error that includes the full cycle path (e.g., a -> b -> c -> a).
• Cycle detection runs before any task execution begins.

6.3Workspace Task Expansion

When a task is specified at the root workspace level and child workspaces have tasks with the same name, Nadle automatically expands the request to include the matching child workspace tasks. This only applies to tasks registered in the root workspace.

6.4Implicit Workspace Dependencies

When implicitDependencies is enabled (the default), Nadle automatically creates task dependency edges based on workspace dependency relationships declared in package.json.

6.5Execution Modes

6.6Exclusion

Tasks specified via --exclude are removed from consideration during analysis. They are filtered out of dependency sets, so they and their exclusive subtrees are not scheduled.

6.7Execution Plan

The execution plan is the ordered list of tasks produced by simulating Kahn’s algorithm to completion. This plan is used by dry-run mode to display the intended execution order.

---

7.1Worker Pool

The pool is configured with:

Worker count values are clamped to [1, availableParallelism]. Percentage strings (e.g., "50%") are multiplied by availableParallelism and rounded.

7.2Worker Parameters

Each task dispatch sends these parameters to the worker:

7.3Message Protocol

Workers communicate back to the pool via MessagePort. There are exactly three message types:

7.4Worker Execution Flow

1. Initialize Nadle in the worker thread on the first task dispatch using a lightweight path: the worker receives the fully resolved options (including the project structure) from the main thread, loads config files to populate task function closures and the task registry, but skips project resolution, option merging, and task input resolution. The instance is cached at module scope and reused for subsequent dispatches within the same thread, so config files are loaded at most once per worker thread lifetime.
2. Look up the task by ID in the registry.
3. Resolve the task’s configuration and options.
4. Resolve the working directory (relative to project root).
5. Run cache validation (see 05-caching.md).
6. Based on validation result:
   • not-cacheable or cache-disabled: send "start", apply env, execute, restore env.
   • up-to-date: send "up-to-date", return.
   • restore-from-cache: restore outputs, update cache pointer, send "from-cache".
   • cache-miss: log reasons, send "start", apply env, execute, restore env, save outputs and metadata.

7.5Timeouts and Retries

A task may declare a timeout (milliseconds) and/or a retries count (see 02-task-configuration.md). They apply only to the execution of the task function — never to cache restore, which is not retried or timed.

• Attempt — one invocation of the task function. A task runs up to 1 + retries attempts (default retries is 0, i.e. a single attempt).
• Timeout — if timeout is set, each attempt is bounded. An attempt that does not settle within timeout milliseconds fails with a timeout error. The task function is not forcibly interrupted (its asynchronous work may continue); the attempt is treated as failed for scheduling and retry purposes.
• Retry — when an attempt fails (including by timeout), the task is retried until it succeeds or the attempts are exhausted. The final failure (the last attempt’s error) is the task’s error. A succeeding attempt makes the task succeed regardless of earlier failures.
• Environment injection is applied and restored around the attempts, not around each individual attempt.

timeout must be a positive integer and retries a non-negative integer; otherwise a configuration error is raised.

7.6Environment Injection

Before executing the task function:

1. The original process environment is merged with the task’s env field.
2. After execution, injected keys are removed and original values restored.

Non-string env values are converted to strings before application.

7.7Cancellation

If a task fails and other tasks are still running:

1. The pool is destroyed, which terminates all worker threads.
2. A terminated worker throws a “Terminating worker thread” error.
3. The pool detects this error and checks if the task’s status is Running.
4. If Running, the task is marked as Canceled (not Failed).

7.8Cleanup

The pool is always destroyed in a finally block after execution, whether it succeeds or fails. This ensures all worker threads are terminated.

7.9Task Chaining

After a task completes successfully, the pool queries the scheduler for newly ready tasks (those whose indegree has reached zero). Each ready task is dispatched to the pool, enabling concurrent execution of independent tasks.

---

8.1Precondition

A task is cacheable only if both inputs and outputs are declared in its configuration. If either is missing, the task is always executed.

8.2Validation Outcomes

Cache validation produces exactly one of five results:

8.3Validation Flow

1. Check if task is cacheable (inputs AND outputs defined). If not, return not-cacheable.
2. Check if caching is enabled (cache flag). If not, return cache-disabled.
3. Compute input fingerprints from config files and declared input patterns.
4. Compute cache key from {taskId, inputsFingerprints, env, options, dependencyFingerprints}.
5. Check if a cache entry exists for this key.
6. If no cache entry exists, return cache-miss with reasons.
7. Read the latest run metadata.
8. Compute current output fingerprints.
9. If the latest run’s cache key matches AND output fingerprints match, return up-to-date. 10. Otherwise, return restore-from-cache.

8.4Input Fingerprinting

Each input file is hashed with SHA-256 to produce a hex-encoded fingerprint. The result is a map from absolute file path to fingerprint string.

8.5Cache Key Computation

The cache key is computed by hashing an object containing:

The hash is SHA-256 with unordered object and array comparison, producing a 64-character hex string.

8.6Up-to-date vs Restore-from-cache

| | Up-to-date | Restore-from-cache | | ---------------------------- | ------------------------- | ----------------------------------------------- | | Cache key matches latest run | Yes | Not necessarily (may match a non-latest run) | | Output files exist on disk | Yes, with correct content | May be missing or modified | | Action | Skip entirely | Copy cached outputs back, update latest pointer |

8.7Cache Miss Reasons

When a cache miss occurs, reasons are computed by comparing the previous run’s input fingerprints with the current ones:

Multiple reasons may be reported for a single cache miss.

8.8Storage Layout

Cache data is stored under the cache directory (default: node_modules/.cache/nadle/):

{cacheDir}/
  tasks/
    {encodedTaskId}/
      metadata.json                     # Latest run pointer
      runs/
        {cacheKey}/                     # 64-char hex hash
          metadata.json                 # Run metadata
          outputs/                      # Snapshot of output files
            {relative-paths}...

8.9Output Snapshot

8.10Cache Update Flow

After validation, the cache is updated based on the result:

8.11Cache Eviction

Each task has a maximum number of cache entries (maxCacheEntries, default: 5). After a cache-miss save, entries beyond this limit are evicted:

1. List all run directories for the task.
2. If the count is within the limit, do nothing.
3. Sort runs by timestamp (newest first).
4. Delete the oldest runs that exceed the limit, never deleting the current latest.

The maxCacheEntries can be set globally via configure() or per-task in the task configuration. The per-task value takes precedence over the global value.

8.12Corruption Recovery

Cache metadata files are written atomically (write to .tmp, then rename) to minimize corruption risk. If corruption does occur:

• Corrupted JSON (SyntaxError during parse): Treated as missing cache. The task re-executes and overwrites the corrupted entry.
• Failed cache restore (missing or partial output files): Falls back to re-executing the task, then saves fresh outputs.

No explicit cleanup of corrupted entries is performed. The eviction mechanism naturally prunes old entries over time.

8.13File I/O Concurrency

Cache save and restore operations use a concurrency limiter (default: 64 concurrent file operations) to prevent “too many open files” errors when tasks have large output sets.

---

9.1Project Structure

9.2Root Detection

The project root is found by searching upward from the current directory:

1. Look for a package.json marked with nadle.root: true. If found, that directory is the root (and is further inspected for a monorepo layout).
2. Otherwise, detect a monorepo root via package manager tooling (lock files, workspace config).
3. Otherwise, fall back to the closest ancestor directory that contains a package.json, treated as a single-package project.

If no package.json is found in any ancestor directory, Nadle raises an error.

9.3Package Manager Detection

The package manager is detected automatically from lock files and workspace configuration — it is not manually configured. Detection uses the @manypkg/tools library.

9.4Workspace Discovery

Child workspaces are discovered via the package manager’s workspace configuration:

• pnpm: pnpm-workspace.yaml
• npm/yarn: workspaces field in root package.json

Each discovered package directory becomes a workspace (see 07-workspace.md), except the project root itself: a workspace pattern that matches the root directory (for example a pattern of .) does not create a second workspace, because the root is already represented by the root workspace. Such a match is ignored rather than treated as an error.

Workspaces are sorted by their relative path for deterministic ordering.

9.5Project Resolution Flow

1. Find the project root (config file or monorepo root).
2. Detect the package manager.
3. Discover all workspaces.
4. Create the root workspace with its config file path.
5. Create child workspaces with their package metadata.
6. Resolve workspace dependencies from package.json.
7. Apply alias configuration (if any).
8. Validate workspace labels for uniqueness.

9.6Current Workspace

The current workspace is determined by the directory where Nadle is invoked. It defaults to the root workspace. The current workspace ID affects which workspace receives task registrations when loading config files.

---

10.1Workspace Fields

10.2Identity

Workspace IDs are derived from the relative path by replacing path separators with colons:

The root workspace always has the ID "root" and the relative path ".".

Backslashes (Windows paths) are normalized to forward slashes before conversion.

10.3Config Files

Each workspace may have its own nadle.config.{js,mjs,ts,mts} file:

• The root workspace’s config file is required.
• Child workspace config files are optional.
• Workspace config files are loaded after the root config file.
• Config files register tasks scoped to their workspace.

10.4Workspace Dependencies

Workspace dependencies are populated from the package.json dependency fields:

• dependencies
• devDependencies

peerDependencies and optionalDependencies are intentionally excluded: they rarely imply a build-ordering relationship and including them risks spurious edges (or cycles) in the task graph.

If a dependency references another workspace in the project (e.g., via workspace:* protocol), it is recorded as a workspace dependency.

When implicitDependencies is enabled (the default), these workspace dependencies are used to automatically create task dependency edges between workspaces. See 03-scheduling.md for details on implicit dependency resolution and root task aggregation.

10.5Aliases

Aliases provide human-readable labels for workspaces. They are configured via the configure() function in the root config file:

• Object map: { "shared/api": "api" } — maps workspace paths to labels.
• Function: (workspacePath) => label | undefined — returns a label or undefined.

10.6Task Scoping

• Tasks are scoped to the workspace whose config file registered them.
• The same task name may exist in different workspaces.
• When resolving a task reference without a workspace prefix, Nadle looks in the current workspace first.
• If the task is not found in the current workspace, Nadle falls back to the root workspace.

---

11.1Supported Formats

Config files may use any of these extensions:

11.2Default Config File

The default config file name is nadle.config.ts. Nadle searches for config files in this precedence order:

1. nadle.config.js
2. nadle.config.ts
3. nadle.config.mjs
4. nadle.config.mts

If multiple exist, the first match wins (JS before TS, TS before MTS).

The --config flag overrides this search and specifies an explicit path.

11.3Runtime Transpilation

Config files are loaded using jiti, which provides:

• ESM support regardless of the project’s module format.
• TypeScript transpilation without a separate build step.
• Interop for default exports.

11.4Loading Flow

Config files are loaded within an AsyncLocalStorage context bound to the active Nadle instance. This enables tasks.register() and configure() to route registrations to the correct instance without requiring explicit parameters.

1. CLI parse: yargs parses command-line arguments.
2. Config file resolution: find and load the root config file.
3. Root config execution: the config file runs within the instance context, calling tasks.register() and optionally configure().
4. Workspace config loading: for each workspace with a config file, set the workspace context and load the file (still within the same instance context).
5. Project resolution: resolve project structure, workspaces, and dependencies.
6. Task finalization: flush the task registry buffer into the final registry.
7. Options merge: combine defaults, file options, and CLI options.

11.5The `configure()` Function

The configure() function may be called from the root config file only. It sets file-level options that are merged between defaults and CLI options.

Accepted options:

If configure() is called from a non-root workspace config file, it raises an error.

11.6Option Precedence

Options are merged in this order (later wins):

Built-in defaults < File options (configure()) < CLI flags

11.7Built-in Defaults

11.8Worker Count Resolution

Worker count values can be:

• An integer: used directly.
• A percentage string (e.g., "50%"): multiplied by availableParallelism and rounded.

The result is always clamped to [1, availableParallelism]. The minWorkers value is additionally capped at maxWorkers.

11.9Supported Log Levels

The following log levels are supported, in increasing verbosity:

1. "error" — errors only
2. "log" — standard output (default)
3. "info" — informational messages
4. "debug" — debug-level output

---

12.1Command Structure

nadle [tasks...] [options]

• tasks — zero or more task names or task identifiers to execute.
• If no tasks are specified and stdin is a TTY, Nadle enters interactive task selection.

nadle <tasks...> [options] -- <args...>

12.2Flags

12.3Shell Completion

The completion command prints a shell completion script to standard output for the detected shell (bash, zsh, or fish). The user installs it by sourcing the output (e.g. nadle completion >> ~/.zshrc).

Once installed, pressing TAB completes:

• task names — the labels of all tasks registered by the live configuration (discovered by loading the config, exactly as --list does), and
• option flags — the known CLI flags.

When the active shell can render a description alongside each candidate (such shells accept a value:description pairing), task completions carry the task’s description so the menu shows the same context as --list. Tasks without a description, and shells that cannot display descriptions, complete to the bare task name. The description is the only annotation; no other metadata is attached.

Completion discovers task names dynamically from the current project, so it always reflects the tasks actually defined. The completion command and the completion callback produce no other output (no banner, footer, or logs).

12.4JSON Output

The --json flag switches the read-only inspection commands from human-oriented text to a single machine-readable JSON document on standard output. It is intended for tooling and automation that need to parse Nadle’s introspection output reliably.

When --json is set:

• The selected read command prints exactly one JSON document and nothing else: no banner, no progress footer, no colors, and no trailing run summary.
• The live progress footer is forced off regardless of its own default.

--json applies to these commands; any other command ignores it:

--show-config and --config-key already emit JSON and are unaffected by --json.

A task’s dependsOn, inputs, and outputs reflect its declared configuration. inputs and outputs are rendered as <type>: <pattern> entries (one per declared pattern).

12.5Handler Chain

After options are resolved, Nadle selects a handler using a first-match-wins chain:

Each handler is instantiated and its canHandle() method is checked. The first handler that returns true has its handle() method invoked. Only one handler runs per invocation.

The Execute handler additionally honors --since <ref>: before scheduling, it filters the requested (expanded) task set to those affected by files changed since the git ref. A task is affected when a changed file lies within its workspace directory; the dependencies of an affected task are included so its inputs are produced. If no task is affected, Execute reports it and runs nothing. Cross-workspace dependent propagation is out of scope for this version.

12.6Exit Codes

When an error is caught during execution:

• If the error is a NadleError, exit with its errorCode.
• Otherwise, exit with code 1.

In a machine-readable error mode (see Error Handling — Structured Error Output), the same failure also emits a one-line structured error record to the error stream before exiting.

12.7Interactive Task Selection

When no tasks are specified on the command line and stdin is a TTY, Nadle enters an interactive mode where the user can select tasks from a list. This state is tracked internally and affects footer rendering.

---

13.1Argument Normalization

All exec-based tasks (ExecTask, NodeTask, NpmTask, NpxTask, PnpmTask, PnpxTask) share one semantic for the args option: a string is split into arguments on spaces, with backslash-escaped spaces preserved (a\ b stays one argument); an array is taken as-is, each element one argument.

13.2ExecTask

Executes an arbitrary external command.

13.3PnpmTask

Executes a pnpm command. Specialized variant of ExecTask with pnpm as the command.

13.4NodeTask

Executes a Node.js script. Specialized variant of ExecTask with node as the command.

13.5NpmTask

Executes an npm command. Specialized variant of ExecTask with npm as the command.

13.6PnpxTask

Executes a locally-installed package binary via pnpm exec. Specialized variant of ExecTask for running binaries from node_modules/.bin through pnpm.

13.7NpxTask

Executes a locally-installed package binary via npx. Specialized variant of ExecTask for running binaries from node_modules/.bin through npx.

13.8File Selections

File-operation tasks share one source vocabulary. A file selection is either:

• a string — a path (relative to the working directory) to a file or a directory, or
• a selector object — { dir, include?, exclude? }, where include/exclude are glob patterns matched against files inside dir (include defaults to all files).

A string selection pointing to a file yields that file. One pointing to a directory selects the files inside it (applying the task-level default include/exclude patterns, if any). A missing source logs a warning and yields nothing — unless the task’s strict option is set, in which case it is an error.

13.9CopyTask

Copies files into a destination directory.

13.10MoveTask

Moves files into a destination directory. Identical options and destination-mapping behavior to CopyTask (including flatten, rename, overwrite, strict), with one difference: each source file is removed after it reaches its destination.

• A filesystem rename is used when possible; cross-device moves fall back to copy-then-delete.
• Files skipped by the overwrite policy keep their source.
• Emptied source directories are not removed.

13.11SyncTask

Mirrors sources into a destination directory. Identical selection and destination-mapping behavior to CopyTask (including flatten, rename, strict), without an overwrite option — existing destination files are always replaced.

13.12ZipTask

Creates a zip archive from selected files.

13.13UnzipTask

Extracts a zip archive into a directory.

13.14DownloadTask

Downloads a file over HTTP(S).

13.15DeleteTask

Deletes files and directories using glob patterns.

13.16Common Properties

All built-in tasks share these characteristics:

• They all respect the workingDir from the runner context.
• ExecTask, NodeTask, NpmTask, NpxTask, PnpmTask, and PnpxTask force color output via FORCE_COLOR=1 environment variable.
• ExecTask, NodeTask, NpmTask, NpxTask, PnpmTask, and PnpxTask append the runner context’s passthrough arguments (CLI args after --, see spec 09) after their configured arguments. CopyTask and DeleteTask ignore passthrough arguments.
• All tasks stream output through the task logger.

13.17Custom Task Types

Users create custom reusable task types using defineTask():

defineTask({
  run: ({ options, context }) => { ... }
})

The run function receives typed options and a runner context. The returned task object is then registered by providing it as the task body together with an options resolver (see 01-task.md).

---

14.1Listener Interface

A listener is an object with optional methods for each lifecycle event. All event methods are optional — a listener may implement any subset.

14.2Events

Events are listed in typical emission order:

14.3Emission Order

Events are emitted sequentially through all registered listeners, in registration order. For each event:

1. Iterate through all listeners.
2. For each listener that implements the event method, call it and await the result.
3. Move to the next listener.

This means listeners are called in order and each listener’s handler completes before the next is invoked.

14.4Built-in Listeners

Nadle registers two built-in listeners in this order:

The ExecutionTracker runs first so that statistics are up-to-date when the DefaultReporter renders output.

14.5ExecutionTracker Details

The execution tracker maintains:

• Task stats: count of tasks in each status (Scheduled, Running, Finished, UpToDate, FromCache, Failed, Canceled).
• Duration: total execution time, updated every 100ms via an interval timer.
• Per-task state: status, duration, start time, and thread ID for each task.

The duration timer is unreferenced so it does not prevent the process from exiting.

14.6Custom Listeners

The core registers a fixed set of listeners (ExecutionTracker and the active reporter). User-facing extension is through the plugin system (specified in full in 14-plugins.md): a plugin applied with use() contributes lifecycle hooks that the core dispatches on the main thread via an internal listener. The hooks map to events as follows:

Hooks run in plugin order, grouped by the optional enforce (pre → normal → post). Because beforeTask is skipped for cache hits while afterTask always fires, the two are not a guaranteed pair. Plugins may also contribute task types and reporters.

---

15.1NadleError

NadleError is a specialized error class with a numeric exit code.

15.2NadleError Subclasses

NadleError has a hierarchy of subclasses so consumers can catch specific error categories programmatically. Each subclass fixes a distinct errorCode.

Invariant violations (states that should be impossible — unset working directory, project not yet configured, exhaustiveness fallbacks) remain plain Error, not NadleError subclasses.

15.3Error Propagation

Errors flow through the system in this chain:

Task function throws
  -> Worker promise rejects
    -> Pool catches the error
      -> onTaskFailed event emitted
        -> Error re-thrown to handler
          -> onExecutionFailed event emitted
            -> Process exits with error code

15.4Exit Code Determination

if error is NadleError:
  exit with error.errorCode
else:
  exit with 1

15.5Known Error Types

15.6Structured Error Output

By default, a failure prints a human-readable message (and an optional repro hint). In a machine-readable error mode — active whenever the selected reporter is the agent reporter, and intended to extend to any future explicit machine-output flag — a failure additionally emits a single structured error record to the error stream.

The record is a one-line, machine-parseable object with these fields:

15.7Stacktrace Display

By default, only the error message is shown. When --stacktrace is passed:

• The full error stack trace is printed.
• Without --stacktrace, a hint is shown suggesting the user re-run with the flag.

---

16.1Reporters

The output style is selected by the reporter option (--reporter):

The reporter name space is open: in addition to the two built-ins, a plugin may contribute a named reporter (a listener factory), selected by the same --reporter <name> option. Exactly one reporter is active per run (a plugin reporter replaces the default). A plugin reporter may not shadow a built-in name, and an unknown reporter name is a configuration error listing the available reporters. See 14-plugins.md for how reporters are contributed.

The remaining sections of this document describe the default reporter. The agent reporter is specified below.

SUCCESS in {duration} (done {N}[ up-to-date {N}][ cached {N}][ failed {N}])
FAILED in {duration} (done {N}[ ... ] failed {N})

16.2Footer

The footer is a live-updating display at the bottom of the terminal showing execution progress.

16.3Task Status Messages

During execution, each task event produces a status message:

16.4Execution Result

RUN SUCCESSFUL in {duration}
{N} tasks executed[, {N} tasks up-to-date][, {N} tasks restored from cache]

RUN FAILED in {duration} ({N} tasks executed, {N} tasks failed)

For more details, re-run the command with the --stacktrace option...

16.5Summary (`—summary`)

When --summary is passed, an end-of-run profiling table is printed showing each finished task with its execution duration. This is rendered after the success message and before the final status line.

Only tasks with status Finished are included in the summary (not up-to-date or from-cache tasks).

16.6Welcome Banner

At execution start (unless --show-config is active), Nadle prints:

▶ Welcome to Nadle v{version}!
Using Nadle from {path}
Loaded configuration from {configFile}[ and {N} other(s) files]

16.7Task Resolution Display

If any task names were auto-corrected during resolution (e.g., fuzzy matching), the corrected mappings are displayed:

Resolved tasks:
    {original}  → {corrected}