Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

fix/Pre-boot-refusal-exit · L-261017-db9236 (#1470)

Louis Choquel7992f2af3bde
diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.toml
index c7a18bdab..55e920d0e 100644
--- a/.drift/acks/cli-docs.toml
+++ b/.drift/acks/cli-docs.toml
@@ -1,8 +1,8 @@
contract = "cli-docs"
-digest = "sha256:15c34e11fbeda068e0b43ecdcec888acaa608831376c25b11466fb784d96fe81"
-reviewed_by = "Louis Choquel"
-reviewed_at = "2026-10-20T07:11:19Z"
-rationale = "real-catch: validate bundle --graph now makes its folder under the directory bundle_run_outputs_dir settles for the target, the one run bundle writes to (beside the bundle file named or the bundle defining a folder's entry pipe, or the folder's own results/ when --pipe names the pipe), and only once the graph has rendered; docs/tools/cli/agent-cli.md (Graph Visualization) and pipelex/cli/agent_cli/CLAUDE.md (the validate output and the file convention) now say so. run bundle's own locations are unchanged, only routed through that function."
+digest = "sha256:99b717b4eca9c5e27f0f7246a5017d2a2d6e3bc90b9cc96c6e07c5bcae112440"
+reviewed_by = "Claude Opus 5.5"
+reviewed_at = "2026-10-20T08:41:28Z"
+rationale = "real-catch: this branch makes pipelex-agent validate bundle and fix bundle exit 2, no verdict, on a configuration refused before the boot (report_agent_init_failure takes exit_code, which the agent resolver passes as 2), as the human pipelex validate/fix bundle already did, while run and inputs keep exit 1 and a lone .mthds file, not listed before the boot, keeps the boot's exit 1; docs/tools/cli/agent-cli.md (validate and fix), validate.md, fix.md (exit codes), docs/under-the-hood/error-model.md and pipelex/cli/agent_cli/CLAUDE.md say so, and the agent validate, run and inputs command docstrings state the exit codes each command gives. Merged with dev's validate bundle --graph output folder (its run_output folder under the directory run bundle writes to), whose agent-cli.md and CLAUDE.md changes are kept beside this branch's; the graph and view failures still exit 2, as the validate bundle docstring says."
[trigger_files]
"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"
@@ -10,9 +10,9 @@ rationale = "real-catch: validate bundle --graph now makes its folder under the
"pipelex/cli/agent_cli/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/agent_cli/_agent_cli.py" = "blob:3d46a1eb5afc34834de17c46ed8b468c67cc4624"
"pipelex/cli/agent_cli/commands/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
-"pipelex/cli/agent_cli/commands/agent_cli_factory.py" = "blob:422ae48a8d4eb9b2e33dc2e6a8ca608d205e5f59"
+"pipelex/cli/agent_cli/commands/agent_cli_factory.py" = "blob:275ceed1288f7c0d10c1e9fbdf2d756f88dc6553"
"pipelex/cli/agent_cli/commands/agent_output.py" = "blob:03307ca018ed9f93f3c4aeeb164eb12032306dc8"
-"pipelex/cli/agent_cli/commands/bundle_path_resolver.py" = "blob:beff9f679a2aeb29ba7213312026d80dacf4264b"
+"pipelex/cli/agent_cli/commands/bundle_path_resolver.py" = "blob:3dddbb7f22e929c17af5964f6a79dc4d62778369"
"pipelex/cli/agent_cli/commands/check_model_cmd.py" = "blob:fb66f68166671db207efbb8e974bc4e7c24915a5"
"pipelex/cli/agent_cli/commands/codegen/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/agent_cli/commands/codegen/app.py" = "blob:56130b89fe9efec5ad3d014ed6bc16bef1bd1645"
@@ -28,9 +28,9 @@ rationale = "real-catch: validate bundle --graph now makes its folder under the
"pipelex/cli/agent_cli/commands/inputs/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/agent_cli/commands/inputs/_inputs_core.py" = "blob:4161029643f3a302de54fa637d2676521e10d873"
"pipelex/cli/agent_cli/commands/inputs/app.py" = "blob:b30915d6fce2f524af4f0b2a50a37ffd7eaffab6"
-"pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py" = "blob:976b909bac4d8d10b8de5efa84d03f17a5793dee"
-"pipelex/cli/agent_cli/commands/inputs/method_cmd.py" = "blob:632864820c102553c972c9ce3a2a2429c6d8f7be"
-"pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py" = "blob:9001d6336761236b2f6947cdb3694b4a13cd3bf2"
+"pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py" = "blob:8e5bddc1c72d639452489b5c59d8f392f6bbf6ba"
+"pipelex/cli/agent_cli/commands/inputs/method_cmd.py" = "blob:c499a9b343d6b957122e223346878d9178c98d01"
+"pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py" = "blob:dbab9cb79bdba8964ccc3022ae53851f7a2e6644"
"pipelex/cli/agent_cli/commands/lint_cmd.py" = "blob:91ad9cb4d618ba4c0b7da366cde2f74f38d350df"
"pipelex/cli/agent_cli/commands/migrate_cmd.py" = "blob:3f60020ed38c289e7fae66e8e9c735030bd2521f"
"pipelex/cli/agent_cli/commands/models_cmd.py" = "blob:f6365858100ccedb5e85afe5c6c689d9018adfdb"
@@ -40,16 +40,16 @@ rationale = "real-catch: validate bundle --graph now makes its folder under the
"pipelex/cli/agent_cli/commands/run/_run_core.py" = "blob:44036b8b1e344e52880896d4c8edc2bfd35fe60d"
"pipelex/cli/agent_cli/commands/run/_run_hosted.py" = "blob:8d2e819c44d5669756e931b9f3fc83741d54a1df"
"pipelex/cli/agent_cli/commands/run/app.py" = "blob:7546d9b31ea2dc22b1ddae538edfbc8e7f7d08df"
-"pipelex/cli/agent_cli/commands/run/bundle_cmd.py" = "blob:42a795f9139eaf038af833f74f1f595e0807a737"
+"pipelex/cli/agent_cli/commands/run/bundle_cmd.py" = "blob:1dc97782d3bc94e2a06337a5f143d22cf77d4d4b"
"pipelex/cli/agent_cli/commands/run/method_cmd.py" = "blob:0df77aa1e35c22ceffdcefd7f4c12f28fda366c7"
-"pipelex/cli/agent_cli/commands/run/pipe_cmd.py" = "blob:1a5a2f86ac80fb86cb53376202bad05ffd19e9f6"
+"pipelex/cli/agent_cli/commands/run/pipe_cmd.py" = "blob:6bacf08886c38463828d9432b2cae4730e9004a3"
"pipelex/cli/agent_cli/commands/run/stdin_resolver.py" = "blob:db0176d7de1e074fd6eefd787c10e71b891eeb32"
"pipelex/cli/agent_cli/commands/validate/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/agent_cli/commands/validate/_validate_core.py" = "blob:f74178959782fe6e8edc2b7171b9967d82cf2076"
"pipelex/cli/agent_cli/commands/validate/app.py" = "blob:1982684a2aae81e0d634bb3b262457a5f187d979"
-"pipelex/cli/agent_cli/commands/validate/bundle_cmd.py" = "blob:4e785799e8a548fb973ad2b2fd184d1695a7dced"
+"pipelex/cli/agent_cli/commands/validate/bundle_cmd.py" = "blob:3df822724c3320a2a6251cf1abe9a495a7e6c2c4"
"pipelex/cli/agent_cli/commands/validate/method_cmd.py" = "blob:19cbf94ca5027983e5fd95b73bc346efaf195c37"
-"pipelex/cli/agent_cli/commands/validate/pipe_cmd.py" = "blob:786e4f13878dbe04d18493c15c613fc7d0d8e473"
+"pipelex/cli/agent_cli/commands/validate/pipe_cmd.py" = "blob:ca0b7bdce8e9a023e664289907f9db129c77b2cc"
"pipelex/cli/bundle_target_resolution.py" = "blob:fd4c1da386c33f4542c11a68ad4ce5bed64bc4aa"
"pipelex/cli/cli_factory.py" = "blob:9768ead842eecbfc9509dc68aafca31957a27439"
"pipelex/cli/commands/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
@@ -68,7 +68,7 @@ rationale = "real-catch: validate bundle --graph now makes its folder under the
"pipelex/cli/commands/build/output/method_cmd.py" = "blob:242434d518aff0b9706b910e7f937b53a601fde1"
"pipelex/cli/commands/build/output/pipe_cmd.py" = "blob:eb0db8279c93fcff9d5fe4546f593d753282acb5"
"pipelex/cli/commands/build/structures_cmd.py" = "blob:177c190e1679e26f7ab20d9ff3f6199aaf2cfe19"
-"pipelex/cli/commands/bundle_path_resolver.py" = "blob:b3176ff36aa2100300969009712c06e5956ba483"
+"pipelex/cli/commands/bundle_path_resolver.py" = "blob:3fe5a0a946dde78d66c69a68da2334943551a158"
"pipelex/cli/commands/codegen/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/commands/codegen/app.py" = "blob:9158084a89da23654e122e9df3a0a9c726401642"
"pipelex/cli/commands/codegen/check_cmd.py" = "blob:329f410bca90eb022fad2abc729e8b5203138c02"
@@ -130,7 +130,7 @@ rationale = "real-catch: validate bundle --graph now makes its folder under the
"pipelex/cli/commands/validate/pipe_cmd.py" = "blob:ab8cca9c5c8c5d7dce005deba6d2d8b32dc2e81e"
"pipelex/cli/commands/which_cmd.py" = "blob:5febd14510603f09ef0fb29d5ef97c35b7a6692f"
"pipelex/cli/deck_notice.py" = "blob:542877125e89e35b02bc969cfee952155b0d7c2c"
-"pipelex/cli/error_handlers.py" = "blob:b0bbfbb058ef764de90c7f1ba09093a7616f43c6"
+"pipelex/cli/error_handlers.py" = "blob:6f208c35d91cecaef82927634df9c58553dd181e"
"pipelex/cli/exceptions.py" = "blob:5c66f20b0a06c8ae8c20b94f92e2c30b78f5b6c5"
"pipelex/cli/installed_methods.py" = "blob:7e7f289d50ca6bc446b6891cbc846dc4a8cee6e2"
"pipelex/cli/judged_target.py" = "blob:8d3f3b3359992feeeca2bd4acd1d404262cbaf87"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5e32e8b94..5c4757a37 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,6 +13,7 @@
- **The API server's examples send a method in `files`**: the server's README and the API Server pages send a method to `/v1/execute` and `/v1/validate` in `files`, a map from each file's path in the method's folder to its content, where they sent `mthds_contents`. The reference pages and the OpenAPI artifact now say that `mthds_contents`, with `bundle_b64`, `resources` and `/v1/validate`'s `mthds_sources`, is being retired and will be refused by a later release, so a client sends `files` now.
- **A PipeFunc package-offer factory is never called on a thread running an event loop (Breaking)**: the factory a plugin registers with `PluginRegistrar.add_pipe_func_package_offer` may block for as long as its work takes and must not use an event loop of its caller's, and pipelex enforces it: a load that would call the factory on a thread running an event loop fails with `PipelexUnexpectedError` instead, so a host that calls a load itself from asynchronous code, such as a worker's activity, moves it off the loop with `run_method_load` (`pipelex.libraries.method_load_threads`) or with `acquire_library_async` (`pipelex.pipeline.execution_seams`), the twin of `acquire_library` that loads off the loop. The factory's signature is unchanged, and so is the plugin API version. `run_method_load` runs a blocking call in the method-load pool, a named pool of at most `METHOD_LOAD_MAX_THREADS` threads (four) apart from asyncio's default executor, in a copy of the caller's context, and when its caller is cancelled, the shutdown of `asyncio.run` included, withdraws a call no thread has taken yet or lets the cancellation through only once the running call has ended; the general mechanism is `WorkerThreads` (`pipelex.tools.misc.async_utils`).
- **The refusal of a package the request did not send**: the message of the `unresolved_package_dependency` refusal a static resolution gives, such as the one behind `/v1/resolve`, `/v1/codegen` and `/v1/pipe-io`, tells its reader to send the package's files in `dependencies`, keyed by its address, beside the method's own files in `files`, where it spoke of an in-memory resolve and the host filesystem and advised directory-based resolution; it still carries the words `address-based dependency '<address>'`.
+- **`pipelex-agent validate bundle` and `fix bundle` exit 2 on a configuration refused before the boot**: a configuration that does not validate, which these commands read before the boot for the limits a method's folder is listed under, exits 2, no verdict, where it exited 1, as `pipelex validate bundle` and `pipelex fix bundle` exit on it; the problem is unchanged, and `run bundle` and `inputs bundle` still exit 1.
### Fixed
diff --git a/docs/tools/cli/agent-cli.md b/docs/tools/cli/agent-cli.md
index 2dc5e5483..cc784c7cf 100644
--- a/docs/tools/cli/agent-cli.md
+++ b/docs/tools/cli/agent-cli.md
@@ -89,7 +89,7 @@ For `bundle`, additional options are available:
- `--graph-format`, `-f` - Graph output format (`mermaidflow`, `reactflow`, or `both`)
- `--direction` - Graph layout direction
-`validate bundle <folder>` reads the folder as its [method tree](../../building-methods/method-trees.md), the method rooted at the nearest `METHODS.toml` at or above it, else at the folder itself, and judges the whole tree, as the MTHDS protocol's validation judges a method: every bundle of it is loaded and every pipe of it dry-run. It needs no pipe to start at, so a folder whose bundles declare several `main_pipe`s, or none, is validated like any other, and `bundle_path` in the envelope names the folder. Only the tree's own pipes are judged: the `-L` directories, a nested package below the folder with its own `METHODS.toml`, and the packages the method depends on all load for its bundles to use, but their own pipes are not judged. A graph, which is drawn from one pipe, is drawn from the pipe named by `--pipe`, else from the pipe a run of the folder starts at, the manifest's `main_pipe` or, with no manifest, the one `main_pipe` its bundles declare; when the folder decides no such pipe, `--graph` and `--view` draw nothing and the envelope carries `graph_unavailable`, a sentence saying why, while the validation stands and exits on its own verdict. A folder holding no `.mthds` bundle produces no verdict: the problem `method.invalid`, its `diagnostics.error_class` being `EmptyMethodTreeError`, with exit code `2`.
+`validate bundle <folder>` reads the folder as its [method tree](../../building-methods/method-trees.md), the method rooted at the nearest `METHODS.toml` at or above it, else at the folder itself, and judges the whole tree, as the MTHDS protocol's validation judges a method: every bundle of it is loaded and every pipe of it dry-run. It needs no pipe to start at, so a folder whose bundles declare several `main_pipe`s, or none, is validated like any other, and `bundle_path` in the envelope names the folder. Only the tree's own pipes are judged: the `-L` directories, a nested package below the folder with its own `METHODS.toml`, and the packages the method depends on all load for its bundles to use, but their own pipes are not judged. A graph, which is drawn from one pipe, is drawn from the pipe named by `--pipe`, else from the pipe a run of the folder starts at, the manifest's `main_pipe` or, with no manifest, the one `main_pipe` its bundles declare; when the folder decides no such pipe, `--graph` and `--view` draw nothing and the envelope carries `graph_unavailable`, a sentence saying why, while the validation stands and exits on its own verdict. A folder holding no `.mthds` bundle produces no verdict: the problem `method.invalid`, its `diagnostics.error_class` being `EmptyMethodTreeError`, with exit code `2`. A configuration that does not validate, which the command reads before the boot for the tree's limits, produces none either: it is reported as the failed boot it would have been, under the configuration error's own code, with the boot's recovery tip in Markdown, and exit code `2`, as `pipelex validate bundle` exits on it.
!!! note "Signature pipes"
`pipelex-agent validate` is strict by default — same as `pipelex validate`. A bundle whose dependency graph reaches a `PipeSignature` is rejected unless you pass `--allow-signatures`, which dry-runs signatures as mocks.
@@ -123,7 +123,7 @@ pipelex-agent fix bundle <PATH> [OPTIONS]
- `--format` - Success output format: `markdown` (default) or `json`
- `--error-format` - Error output format: `markdown` or `json` (defaults to the program's `--error-format`, then to `--format`'s value)
-The result reports `iterations`, `fixes_applied`, `files_written`, and any `remaining_errors`. A fully valid result exits 0; a completed fix attempt that remains invalid exits 1 with the problem `method.invalid` on stderr, its `errors` the faults left, each with the code `validate bundle` gives it, and beside them `is_valid`, `bundle_path`, `iterations`, `fixes_applied`, `files_written` and any `bail_reason`; argument, setup, or unexpected failures exit 2, and so does a folder holding no `.mthds` bundle. A fix the command cannot write, its round rolled back, is `client.write_failed`, whose `params.path` names the file, or the directory a copy staged beside it could not be written in, and `params.reason` the system's reason, never `client.file_unreadable`, which is a method file it cannot read. A folder is fixed whole, as `validate bundle` judges it: every file of its method tree, from the tree's root down, is inside the write scope, a fix lands in the file its error names, and a folder whose bundles declare several `main_pipe`s, or none, is fixed like any other. A folder whose tree cannot be read, such as one past this machine's limits, leaves as the still-invalid problem `method.invalid` with exit code `1`, its `errors` carrying the refusal. A configuration that does not validate, which these commands read before the boot for the tree's limits, is reported as the failed boot it would have been, under the configuration error's own code, with the boot's recovery tip in Markdown.
+The result reports `iterations`, `fixes_applied`, `files_written`, and any `remaining_errors`. A fully valid result exits 0; a completed fix attempt that remains invalid exits 1 with the problem `method.invalid` on stderr, its `errors` the faults left, each with the code `validate bundle` gives it, and beside them `is_valid`, `bundle_path`, `iterations`, `fixes_applied`, `files_written` and any `bail_reason`; argument, setup, or unexpected failures exit 2, and so does a folder holding no `.mthds` bundle. A fix the command cannot write, its round rolled back, is `client.write_failed`, whose `params.path` names the file, or the directory a copy staged beside it could not be written in, and `params.reason` the system's reason, never `client.file_unreadable`, which is a method file it cannot read. A folder is fixed whole, as `validate bundle` judges it: every file of its method tree, from the tree's root down, is inside the write scope, a fix lands in the file its error names, and a folder whose bundles declare several `main_pipe`s, or none, is fixed like any other. A folder whose tree cannot be read, such as one past this machine's limits, leaves as the still-invalid problem `method.invalid` with exit code `1`, its `errors` carrying the refusal. A configuration that does not validate, which the command reads before the boot for the tree's limits, is reported as the failed boot it would have been, under the configuration error's own code, with the boot's recovery tip in Markdown, and exits 2, since it gives no verdict, as `pipelex fix bundle` exits on it.
Rewrite a method's flat `PipeFunc` function names as import paths from its folder, the migration of the retired function registry (see [PipeFunc](../../building-methods/pipes/pipe-operators/PipeFunc.md#migrating-flat-function-names)):
diff --git a/docs/tools/cli/fix.md b/docs/tools/cli/fix.md
index 249350b51..41e309512 100644
--- a/docs/tools/cli/fix.md
+++ b/docs/tools/cli/fix.md
@@ -57,7 +57,7 @@ pipelex fix bundle my_bundle.mthds --select match-sequence-output
- `0` - The bundle is valid after the run (fixed, or already valid)
- `1` - Negative verdict: the bundle is still invalid, or valid but not runnable (pending `PipeSignature` placeholders without `--allow-signatures`)
-- `2` - No verdict: bad path, a folder holding no `.mthds` bundle, invalid rule filter, or an unexpected failure
+- `2` - No verdict: bad path, a folder holding no `.mthds` bundle, a configuration that does not validate, read before Pipelex starts for the limits a folder's tree is listed under, invalid rule filter, or an unexpected failure
## What Gets Fixed
diff --git a/docs/tools/cli/validate.md b/docs/tools/cli/validate.md
index 0d3e8c5c0..c7f068025 100644
--- a/docs/tools/cli/validate.md
+++ b/docs/tools/cli/validate.md
@@ -64,7 +64,7 @@ pipelex validate --all --allow-signatures
pipelex validate bundle <PATH>
```
-Validates all pipes defined in a bundle file (`.mthds`), or every bundle of a method's folder. A folder is read as its [method tree](../../building-methods/method-trees.md), the method rooted at the nearest `METHODS.toml` at or above it, else at the folder itself, and the whole tree is judged, as the MTHDS protocol's validation judges a method: every bundle of it is loaded and every pipe of it dry-run, whatever its bundles declare of where the method starts. A folder whose bundles declare several `main_pipe`s, or none, is validated like any other, since validation needs no pipe to start at; only a command acting on one pipe, such as [`pipelex run bundle`](run.md#run-bundle), needs the folder's entry. Only the tree's own pipes are judged: the `-L` directories, a nested package below the folder with its own `METHODS.toml`, and the packages the method depends on all load for its bundles to use, but their own pipes are not judged. A folder whose tree cannot be read, such as one past this machine's limits or holding a symbolic link, is an invalid verdict naming the folder, with exit code `1`. A folder holding no `.mthds` bundle produces no verdict and exits with code `2`.
+Validates all pipes defined in a bundle file (`.mthds`), or every bundle of a method's folder. A folder is read as its [method tree](../../building-methods/method-trees.md), the method rooted at the nearest `METHODS.toml` at or above it, else at the folder itself, and the whole tree is judged, as the MTHDS protocol's validation judges a method: every bundle of it is loaded and every pipe of it dry-run, whatever its bundles declare of where the method starts. A folder whose bundles declare several `main_pipe`s, or none, is validated like any other, since validation needs no pipe to start at; only a command acting on one pipe, such as [`pipelex run bundle`](run.md#run-bundle), needs the folder's entry. Only the tree's own pipes are judged: the `-L` directories, a nested package below the folder with its own `METHODS.toml`, and the packages the method depends on all load for its bundles to use, but their own pipes are not judged. A folder whose tree cannot be read, such as one past this machine's limits or holding a symbolic link, is an invalid verdict naming the folder, with exit code `1`. A folder holding no `.mthds` bundle produces no verdict and exits with code `2`, and so does a configuration that does not validate, which the command reads before Pipelex starts for the limits a folder's tree is listed under: `Failed to validate:` names what to correct.
**Arguments:**
diff --git a/docs/under-the-hood/error-model.md b/docs/under-the-hood/error-model.md
index fe882666a..fa0e24061 100644
--- a/docs/under-the-hood/error-model.md
+++ b/docs/under-the-hood/error-model.md
@@ -519,7 +519,7 @@ The `validate` surface — both the bare `pipelex validate {bundle,method,pipe}`
**The verdict lives in the structured `is_valid` field, not the exit code.** The exit code is a convenience signal for naive shell/CI/Makefile use (`set -e`, `cmd && next`, `if cmd; then`); machine consumers (hooks, the Codex hook, runners) MUST read `is_valid` (and the problem's `code` and `domain`) from the JSON for their block/warn decisions rather than branching on the exit code. Decoupling the verdict from the exit code is what keeps any future exit-code change non-breaking. The 1-vs-2 split is also additive for flat consumers: both stay non-zero, so anything that only tests zero-vs-non-zero is unaffected.
-Implementation: the agent CLI threads `exit_code` through `agent_error(...)` (`agent_output.py`, default 1); the validate commands pass `exit_code=2` at every no-verdict site and keep the default 1 on the `ValidateBundleError` arm and the signature gate. The bare CLI sets the code directly via `typer.Exit(...)` in `cli/commands/validate/*` and via the `exit_code` parameter on `handle_model_availability_error` in `cli/error_handlers.py`. Every refusal of the bundle is a negative verdict on both CLIs: `validate bundle` and `validate method` validate through the shared cascade, and `validate pipe` and `validate --all` load their libraries through it too, so an unknown model or any other load-time refusal exits 1 with the invalid-bundle output rather than a traceback or the no-verdict exit 2. The bare `validate pipe` and `validate --all` also run their dry run through it, so a pipe whose dry run fails is rendered like any other invalid bundle; the agent CLI answers that failure with the problem `method.invalid`, `is_valid: false` and exit 1. Shared boot handlers (`make_pipelex_for_cli`'s telemetry-config and model-deck-preset paths) stay exit 1 — they are shared across `run`/`build`/`validate` and out of the validate-policy scope.
+Implementation: the agent CLI threads `exit_code` through `agent_error(...)` (`agent_output.py`, default 1); the validate commands pass `exit_code=2` at every no-verdict site and keep the default 1 on the `ValidateBundleError` arm and the signature gate. The bare CLI sets the code directly via `typer.Exit(...)` in `cli/commands/validate/*` and via the `exit_code` parameter on `handle_model_availability_error` in `cli/error_handlers.py`. Every refusal of the bundle is a negative verdict on both CLIs: `validate bundle` and `validate method` validate through the shared cascade, and `validate pipe` and `validate --all` load their libraries through it too, so an unknown model or any other load-time refusal exits 1 with the invalid-bundle output rather than a traceback or the no-verdict exit 2. The bare `validate pipe` and `validate --all` also run their dry run through it, so a pipe whose dry run fails is rendered like any other invalid bundle; the agent CLI answers that failure with the problem `method.invalid`, `is_valid: false` and exit 1. Shared boot handlers (`make_pipelex_for_cli`'s telemetry-config and model-deck-preset paths) stay exit 1 — they are shared across `run`/`build`/`validate` and out of the validate-policy scope. A configuration that does not validate, read before the boot to list a method's folder under its limits, is no boot failure: `validate bundle` and `fix bundle` give it exit 2 on both CLIs, through the `exit_code` of `handle_pre_boot_config_error` and of `report_agent_init_failure`, while the same configuration reached at the boot itself keeps the boot's exit 1.
### API
diff --git a/pipelex/cli/agent_cli/CLAUDE.md b/pipelex/cli/agent_cli/CLAUDE.md
index ca36f6dab..fe1d37bb2 100644
--- a/pipelex/cli/agent_cli/CLAUDE.md
+++ b/pipelex/cli/agent_cli/CLAUDE.md
@@ -106,7 +106,7 @@ commands/
- **File convention**: Generated outputs go to `mthds-wip/` with incremental naming (`pipeline_01/`, `pipeline_02/`). A `run` writes into a new numbered folder, `results/<pipe_code>_output_<NN>/`, made by `make_run_output_folder` (`pipelex/cli/commands/run/_run_output_folder.py`) beside the bundle it ran, else under `mthds-wip/`; the folder holds a `.gitignore` of `*`, so a run's outputs never join the method tree and two runs read the same tree, with the same `method_tree_digest`. `run_pipeline_core`'s `output_dir_override` replaces the directory the folder is made under: `run method` on a fetched target (a method address or GitHub URL) passes `results/` under the caller's CWD, since the fetched clone is an ephemeral temp dir deleted at process exit, and `run bundle` passes the directory `bundle_run_outputs_dir` settles for its target, `results/` beside the bundle file named or the bundle defining a folder's entry pipe, or the folder's own `results/` when `--pipe` names the pipe, which `validate bundle --graph` asks too.
- **Validate refusals of the method are verdicts**: the `validate` commands run their library load inside `translate_to_validate_bundle_error` (`pipelex/pipeline/validate_bundle_translation.py`), so every refusal raised while loading a bundle whose code is in the `method` domain, the unknown model (`PipeOperatorModelChoiceError`, an `unknown_model` item) included, reaches the command as a `ValidateBundleError` and leaves with the invalid verdict's problem and exit 1. A refusal of another actor, the request's or the input's included, keeps its own class and code, and so does a dry run none of whose failures is the method's. No `validate` command keeps an arm of its own for a model-choice error; exit 2 stays for a failure of the tool or its environment (config, runtime, security).
- **Run refusals are verdicts too**: a run loads its bundle inside the same translation (`acquire_library`), so an invalid bundle leaves `run pipe` / `run bundle` / `run method` as a `ValidateBundleError` with exit 1, through the generic `agent_error` arm (`run bundle`'s own reading of its bundle through `agent_error_method_refusal()`, in the caller's view on a runner), and its problem (`method.invalid`) carries the verdict's items as `errors`, and the Markdown lists the same errors one per line, so both formats list the one problem's errors and a foreign exception raised while handling an earlier verdict lists none of its items. `run_pipeline_core` sets `library_dirs_are_callers=True`, so a refusal in a `-L` directory (or the bundle's own directory) is the same verdict; `run bundle`'s own parse of a bundle without `--pipe` goes through the translation too, and so does its reading of the method tree: a folder resolves through `pipelex/cli/bundle_target_resolution.py` (`resolve_method_folder_run`, the protocol's entry rule in `pipelex/pipeline/method_entry.py`) and a lone file through `list_bundle_file_tree`, listed before the file is read, so a tree past its limits, a symbolic link or a special file such as a FIFO is a `ValidateBundleError` too, refused unread, and a bundle file the listing cannot read is `client.file_unreadable`, while a folder with no single `main_pipe` is the run's own refusal, a `MethodEntryError` coded `request.pipe_unspecified` or `request.pipe_ambiguous`, no verdict on a method that may be valid. So no `run` command keeps an arm of its own for a model-choice error either: an unknown model reaches it as the verdict's `unknown_model` item.
-- **Two readings of a folder, one resolution path**: `run bundle`, `validate bundle`, `fix bundle` and `inputs bundle` read a folder through `pipelex/cli/bundle_target_resolution.py` (`run` through `resolve_method_folder_run`, the others through `resolve_bundle_target_core`, validate and fix by way of `pipelex/cli/judged_target.py`, whose `JudgedBundleTarget.judged_path` is the path the verdict names and whose `fix_judged_target` is the one fix dispatch both CLIs call, and of `commands/bundle_path_resolver.py`), as its method tree, but with the `FolderReading` their job asks for. `validate` and `fix` take `WHOLE_TREE`, the MTHDS protocol's validation (`mthds/docs/spec/protocol.md`): every bundle of the tree is judged (`validate_bundle(method_dir=..., library_dirs_are_callers=True)`, `fix_method_folder`), with no pipe to start at, so a folder whose bundles declare several `main_pipe`s, or none, is validated like any other; mthds-js's local runner calls `pipelex validate bundle <dir>` to validate a whole method at install and relies on this. `--pipe` there only narrows the dry run, and `--graph` / `--view` draw from the pipe named, else from the entry (`locate_folder_pipe`), or, when the folder decides none, put `graph_unavailable` in the envelope and leave the verdict alone. `run` and `inputs` take `ENTRY_PIPE`, acting on one pipe: the one `--pipe` names, else the protocol's entry (`select_method_entry` in `pipelex/pipeline/method_entry.py`); no single `main_pipe` is the `MethodEntryError` with exit 1 on both, coded `request.pipe_unspecified` or `request.pipe_ambiguous`, the message the same, and no verdict on a method that may be valid. A folder holding no bundle is `EmptyMethodTreeError` with exit 2 on `validate` and `fix`, and a `MethodEntryError` saying it has no pipe to start at on the others, each problem coded `method.invalid`. A folder whose tree is refused at resolution (past its limits, a symbolic link) is the invalid verdict: `ValidateBundleError` on `validate`, and on `fix` the still-invalid `method.invalid` problem of a fix that could not start (`unfixable_method_result`, through `agent_error_fix_bundle`), exit 1 both. A fix of a folder writes anywhere in its method tree, from the root (`method_tree_root`) down, and the human `--diff` preview mirrors that root, so a fix landing in a bundle above the folder named is proposed and written alike. Only the tree's own pipes are judged: `validate_bundle(method_dir=...)` keeps the blueprints its tree lists (`_is_member_blueprint`), so a nested package, a dependency or a `-L` directory loads without being judged; `dirs_beside_method` is the one place the `-L` directories naming the folder itself are dropped, compared resolved. Reading the tree's limits loads the configuration before the boot, so each resolution site catches `PipelexConfigError` and reports it through `report_agent_init_failure` (`agent_cli_factory.py`), the problem a failed boot gives.
+- **Two readings of a folder, one resolution path**: `run bundle`, `validate bundle`, `fix bundle` and `inputs bundle` read a folder through `pipelex/cli/bundle_target_resolution.py` (`run` through `resolve_method_folder_run`, the others through `resolve_bundle_target_core`, validate and fix by way of `pipelex/cli/judged_target.py`, whose `JudgedBundleTarget.judged_path` is the path the verdict names and whose `fix_judged_target` is the one fix dispatch both CLIs call, and of `commands/bundle_path_resolver.py`), as its method tree, but with the `FolderReading` their job asks for. `validate` and `fix` take `WHOLE_TREE`, the MTHDS protocol's validation (`mthds/docs/spec/protocol.md`): every bundle of the tree is judged (`validate_bundle(method_dir=..., library_dirs_are_callers=True)`, `fix_method_folder`), with no pipe to start at, so a folder whose bundles declare several `main_pipe`s, or none, is validated like any other; mthds-js's local runner calls `pipelex validate bundle <dir>` to validate a whole method at install and relies on this. `--pipe` there only narrows the dry run, and `--graph` / `--view` draw from the pipe named, else from the entry (`locate_folder_pipe`), or, when the folder decides none, put `graph_unavailable` in the envelope and leave the verdict alone. `run` and `inputs` take `ENTRY_PIPE`, acting on one pipe: the one `--pipe` names, else the protocol's entry (`select_method_entry` in `pipelex/pipeline/method_entry.py`); no single `main_pipe` is the `MethodEntryError` with exit 1 on both, coded `request.pipe_unspecified` or `request.pipe_ambiguous`, the message the same, and no verdict on a method that may be valid. A folder holding no bundle is `EmptyMethodTreeError` with exit 2 on `validate` and `fix`, and a `MethodEntryError` saying it has no pipe to start at on the others, each problem coded `method.invalid`. A folder whose tree is refused at resolution (past its limits, a symbolic link) is the invalid verdict: `ValidateBundleError` on `validate`, and on `fix` the still-invalid `method.invalid` problem of a fix that could not start (`unfixable_method_result`, through `agent_error_fix_bundle`), exit 1 both. A fix of a folder writes anywhere in its method tree, from the root (`method_tree_root`) down, and the human `--diff` preview mirrors that root, so a fix landing in a bundle above the folder named is proposed and written alike. Only the tree's own pipes are judged: `validate_bundle(method_dir=...)` keeps the blueprints its tree lists (`_is_member_blueprint`), so a nested package, a dependency or a `-L` directory loads without being judged; `dirs_beside_method` is the one place the `-L` directories naming the folder itself are dropped, compared resolved. Reading the tree's limits loads the configuration before the boot, so each resolution site catches `PipelexConfigError` and reports it through `report_agent_init_failure` (`agent_cli_factory.py`), the problem a failed boot gives: with exit 2 on `validate` and `fix`, whose resolver passes `exit_code=2` since the refusal gives no verdict, as the human `pipelex validate bundle` and `fix bundle` exit, and with the boot's exit 1 on `run` and `inputs`. `validate` and `fix` do not list a lone `.mthds` file before the boot, so for a file the same configuration surfaces only at the boot, which exits 1.
- **Hosted runs**: every `run` subcommand takes `--runner local|hosted`, `--hosted/--local` and `--base-url`; `resolve_agent_run_execution()` (`run/_run_hosted.py`) settles them through `pipelex.hosted.execution.resolve_run_execution` (the flag, then `[run] execution`, then local), refusing a `--runner` that contradicts the flag pair and a `--base-url` on a local run as `client.argument_invalid` problems; a configuration that cannot be read there reports its own problem, as a failed boot does (`agent_cli_factory.py`). Every refusal made before anything is sent is a problem in the operator's view, except a refusal of the method the run would send; what the run itself fails with is the problem the runner or the client produced, in the caller's view (below). `run bundle` reads its bundle before it runs it, wherever it runs, so it settles where the run executes first (`resolve_agent_run_execution()`, then `refuse_local_only_flags()`), and reports a bundle that does not parse or validate (`ValidateBundleError`) or a bundle file or folder with no pipe to start at (`MethodEntryError`, `request.pipe_unspecified`, which a lone file with no `main_pipe` raises too, naming its pipes as `candidates`) through `agent_error_method_refusal()` (`run/_run_hosted.py`): on this machine's runtime through `agent_error`, in the operator's view with the command's sentence; on a runner as the refusal the runner would answer for the same method, `to_problem(view=ProblemView.CALLER)` printed through `agent_error_problem()`, with no `diagnostics` and no `message`, since both carry the raise site's classes and text, the items, their locations, the caller's step and the Markdown tip kept. A hosted run boots nothing: it builds a `HostedRunRequest` from what `pipelex/cli/commands/run/_hosted_sources.py` resolves (the bundle and its library's `.mthds` files, a pipe's library, or a method's files; an address or a catalog id as `method_ref` / `method_id`, never fetched) and `run_hosted_for_agent()` runs it through `pipelex.hosted.hosted_run.run_hosted`, which reads the signature and uploads local input files (only when some input string names an existing local file, so a method with an address-based dependency runs with any other inputs), then drives the lifecycle `start_and_wait` drives step by step (the `/v1/version` handshake, `start`, `wait_for_result`, and the blocking `execute` on a server with no run store), so a failure while following an acknowledged run is a `HostedRunPollingError` naming the run, and a transport failure after the run request was sent is a `HostedRunOutcomeUnknownError` rather than an `ApiUnreachableError`. `run_hosted`'s `on_started` callback records the acknowledged run's id, so Ctrl-C (`KeyboardInterrupt`, or the `CancelledError` of a cancelled task) leaves as the problem of a `HostedRunInterruptedError`, `client.follow_failed` carrying `pipeline_run_id` once the run was acknowledged and `client.outcome_unknown` before, with exit code 130. `run bundle` on a file with no `-L` sends `PIPELEXPATH`'s files (`hosted_library_dirs`), and an installed method named like a catalog id is that method. An exception no hosted arm names is this process's own failure and leaves through the command-boundary catch-all as a local run's does, in the operator's view: a Pipelex error under its own code, any other exception as `runtime.unexpected`. Its success envelope is `build_run_output()`'s, with the main output's content as `json`, an empty `markdown`, the working memory dump and `pipeline_run_id`; nothing is written to disk. `--dry-run` / `--mock-inputs` are refused on it, while `--graph` and `--costs` are accepted and ignored. There is no global `--runner` any more, and no `ctx.obj`.
- **A run on a runner that fails** reports the problem the runner or the client produced, in the caller's view, as it came: `agent_error_hosted()` (`run/_run_hosted.py`) builds it with `hosted_failure_problem()` and prints it through `agent_error_problem()` (`agent_output.py`), which neither rebuilds nor reclassifies it, in Markdown by default and JSON with `--error-format json`. A refusal the runner answered (pipelex-sdk's `ApiResponseError`), a runner that cannot be reached (`ApiUnreachableError`, `client.unreachable` naming `params.base_url`) and every other request error of pipelex-sdk or the MTHDS client carries the standard client's problem as `exc.problem`: the runner's own problem document when the answer is one, its `errors` items, its next step and its `request_id` included (`received_problem()`, which keeps only the members the standard and Pipelex declare, at every level, leaves out alone one of Pipelex's members that does not read, fills `request_id` from the answer when the document names none, and projects an answer carrying diagnostics onto the caller's view, deciding it from the document as it came, and a nested `run_error` always, since it is the run's stored record), else the code the client reads from the answer, such as `client.response_unreadable` naming the status, or `client.outcome_unknown` for an answer that leaves a run possibly started, which pipelex-sdk reads for every 5xx on the run request but a 501 and a 503 coded `pipeline_start_unavailable`, whatever the body. An answer in a shape that predates the standard's, which the client reads by its status alone, goes through `hosted_refusal_problem()` (`pipelex/hosted/error_rendering.py`): a refusal of the hosted plane reads as the core code its status and the plane's own `code` name, built by `make_problem` in the caller's view, `auth.missing_credential` for a `401` or `403` with no key sent (`HOSTED_MISSING_KEY_NEXT_STEP`), `auth.invalid_credential` for a `401` and for the edge's bare `403`, `auth.forbidden` for a `403` the platform codes with one of its authorization codes, `forbidden` or `role_not_permitted` (`HOSTED_FORBIDDEN_NEXT_STEP`), and `auth.invalid_credential` for a `403` with any other code, `run.not_found` or `method.not_found` for a `404` coded `run_not_found` or `method_version_not_found` and `request.not_found` for any other, `account.rate_limited` with its `retry_after` for a `429`, with the plane's own `detail` and the next step the human CLI gives (`HOSTED_REFUSAL_NEXT_STEPS_BY_STATUS`); a runner's own refusal in the former shape that lists validation items, the `422` of a method that does not validate on `/v1/start` or `/v1/execute`, is read first, by `_former_refusal_problem()` in `run/_run_hosted.py`, as `method.invalid` with those items, its reason, its advice and its status, through the builder a stored report in the same shape goes through (`_former_problem()`); any other such answer that gives its reason, a runner's own `422` for a reserved input key included, keeps the client's `client.response_unreadable`, read by the standard's members alone so a member beside them that does not read never stops it (`_client_reading()`), with that reason as its `detail` and the human CLI's step (`hosted_refusal_next_step()`), of the kind its advice names through `FORMER_ADVICE_KINDS` (`pipelex/hosted/error_rendering.py`), else `change_input` for a `4xx`; an answer that may have started a run keeps its `client.outcome_unknown`. A run that started and failed (`RunFailedError`) is `run.failed` naming the run and its status, with the client's sentence as `message`, which quotes the stored report's reason, and nests the run's own problem as `run_error`: a stored report that is a problem document is read as a runner's answer is, so a member it holds beside the problem is left out, and one in the former `RunErrorReport` shape is `method.invalid` with its validation items (`hosted_method_problem_items()`) or `runtime.unexpected`, its message, its advice (kind through `FORMER_ADVICE_KINDS`) and its `retryable` carried (`_former_run_problem()`). Markdown renders the nested problem with the head `render_problem_markdown` uses, one heading level down (`_problem_head_lines`). Every error of pipelex-sdk's own but an answer's refusal and an unreachable runner adds its sentence as `message`, since it says what its code's parameters cannot (how long the client waited, that a completed run delivered no main output), and every one but an answer's refusal and a failed run takes the next step the human CLI tailors for it (`tailored_next_step()`, the step `describe_hosted_error()` gives when it is not `HOSTED_RUN_REQUEST_NEXT_STEP`), keeping its code's kind. pipelex's own `HostedRunError`s report their problem in the caller's view with their sentence as `message` and their advice as the Markdown tip, `pipeline_run_id` included for `HostedRunPollingError` and `HostedRunInterruptedError`; a `HostedMethodInvalidError` lists pipe-io's items as `errors`, each coded as a local verdict codes it (`hosted_method_problem_items()`, through `validation_item_code` and `problem_item_of`, `method.schema_violation` with the item's sentence as its finding for an item of a type this version does not read, each item read by the fields this version declares, so a field it does not keeps nothing from being typed, and a declared field whose value it cannot read, such as a newer runner's fix, is left out alone, so the item keeps its type, its locators and its dependency facts), its file in `location.file`. Nothing of the envelope this CLI wrote before it reported problems is left (`error`, `error_type`, `error_source`, `hint`, `error_domain`, `retryable`, `error_code`, `http_status`, …), which `tests/unit/pipelex/cli/test_agent_output_drift.py` guards in the source and in the emitted document.
- **Method-reference failures**: the `run`/`validate`/`inputs` method commands call `resolve_method_target(..., raise_ref_errors=True)` and report the typed `MethodRefError` subclasses through `agent_error(...)` themselves, each with its own code (validate uses `exit_code=2`, its no-verdict convention) — the human CLI's red-text rendering stays in `resolve_method_target`'s default arm.
diff --git a/pipelex/cli/agent_cli/commands/agent_cli_factory.py b/pipelex/cli/agent_cli/commands/agent_cli_factory.py
index 422ae48a8..275ceed12 100644
--- a/pipelex/cli/agent_cli/commands/agent_cli_factory.py
+++ b/pipelex/cli/agent_cli/commands/agent_cli_factory.py
@@ -162,7 +162,7 @@ def apply_agent_cli_output_discipline() -> None:
hub.set_console_print_target(target=ConsoleTarget.STDERR)
-def report_agent_init_failure(*, error: Exception) -> NoReturn:
+def report_agent_init_failure(*, error: Exception, exit_code: int = 1) -> NoReturn:
"""Report a failure to initialize Pipelex, or to read the configuration it boots from, as its problem.
The one account of a failed boot, given whether the boot raised it or a step reading this machine's configuration
@@ -171,11 +171,18 @@ def report_agent_init_failure(*, error: Exception) -> NoReturn:
included, reports its own code, its next step, its advice and, when the migration history explains it, the pending
migration in its diagnostics. A failure whose chain gives no advice is tipped with the boot's recovery path, its
problem still its own.
+
+ Args:
+ error: What the boot, or the read of its configuration, raised.
+ exit_code: The exit code, 1 by default, which a failed boot gives. ``validate bundle`` and ``fix bundle`` pass
+ 2 for a configuration refused before the boot, since that refusal gives no verdict on the method, as the
+ 0/1/2 policy reserves 2 for and as the human ``pipelex validate bundle`` and ``pipelex fix bundle`` exit.
"""
if isinstance(error, ModelDeckPresetValidationError):
agent_error(
error.message,
cause=error,
+ exit_code=exit_code,
fallback_tip=AGENT_BOOT_RECOVERY_TIP,
preset_id=error.preset_id,
model_type=str(error.model_type),
@@ -183,8 +190,8 @@ def report_agent_init_failure(*, error: Exception) -> NoReturn:
enabled_backends=sorted(error.enabled_backends),
)
if isinstance(error, PipelexError):
- agent_error(error.message, cause=error, fallback_tip=AGENT_BOOT_RECOVERY_TIP)
- agent_error(f"Pipelex initialization failed: {error}", cause=error, fallback_tip=AGENT_BOOT_RECOVERY_TIP)
+ agent_error(error.message, cause=error, exit_code=exit_code, fallback_tip=AGENT_BOOT_RECOVERY_TIP)
+ agent_error(f"Pipelex initialization failed: {error}", cause=error, exit_code=exit_code, fallback_tip=AGENT_BOOT_RECOVERY_TIP)
def make_pipelex_for_agent_cli(*, library_dirs: list[str] | list[Path] | None = None, needs_inference: bool = True) -> Pipelex:
diff --git a/pipelex/cli/agent_cli/commands/bundle_path_resolver.py b/pipelex/cli/agent_cli/commands/bundle_path_resolver.py
index beff9f679..3dddbb7f2 100644
--- a/pipelex/cli/agent_cli/commands/bundle_path_resolver.py
+++ b/pipelex/cli/agent_cli/commands/bundle_path_resolver.py
@@ -23,8 +23,10 @@ def resolve_bundle_target(path: str, *, library_dir: list[str] | None) -> Judged
bundle of its tree, being user-passed.
A folder holding no bundle, its problem the error's own, and a path that is neither a ``.mthds`` file nor a
- directory, ``client.argument_invalid``, produce no verdict: exit 2 via ``agent_error``. A configuration that does
- not validate, read for the tree's limits before the boot, is reported as the failed boot it would have been.
+ directory, ``client.argument_invalid``, produce no verdict: exit 2 via ``agent_error``. So does a configuration
+ that does not validate, read for the tree's limits before the boot: it is reported with the problem of the failed
+ boot it would have been, and exits 2, as ``pipelex validate bundle`` and ``pipelex fix bundle`` exit on it. A lone
+ ``.mthds`` file is not listed before the boot, so the same configuration surfaces only at the boot, which exits 1.
Both ``path`` and each ``library_dir`` entry have ``~`` expanded before resolution, so home-relative inputs behave
like every other CLI path argument.
@@ -42,7 +44,7 @@ def resolve_bundle_target(path: str, *, library_dir: list[str] | None) -> Judged
except EmptyMethodTreeError as exc:
agent_error(exc.message, cause=exc, exit_code=2)
except PipelexConfigError as exc:
- report_agent_init_failure(error=exc)
+ report_agent_init_failure(error=exc, exit_code=2)
if isinstance(result, BundleTargetResolutionError):
agent_argument_error(
diff --git a/pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py b/pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py
index 976b909ba..8e5bddc1c 100644
--- a/pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py
+++ b/pipelex/cli/agent_cli/commands/inputs/bundle_cmd.py
@@ -55,7 +55,8 @@ def inputs_bundle_cmd(
"""Generate an example inputs template from a bundle file (.mthds) or pipeline directory.
Outputs the JSON envelope (or raw TOML with --format toml) to stdout on
- success, and the problem to stderr on error with exit code 1, as JSON unless --error-format says markdown.
+ success, and the problem to stderr on error with exit code 1, as JSON unless --error-format says markdown; a
+ command line that does not parse exits 2.
Examples:
pipelex-agent inputs bundle my_bundle.mthds
diff --git a/pipelex/cli/agent_cli/commands/inputs/method_cmd.py b/pipelex/cli/agent_cli/commands/inputs/method_cmd.py
index 632864820..c499a9b34 100644
--- a/pipelex/cli/agent_cli/commands/inputs/method_cmd.py
+++ b/pipelex/cli/agent_cli/commands/inputs/method_cmd.py
@@ -50,7 +50,8 @@ def inputs_method_cmd(
Resolves the method by name, finds its .mthds bundle, and generates inputs.
Outputs the JSON envelope (or raw TOML with --format toml) to stdout on
- success, and the problem to stderr on error with exit code 1, as JSON unless --error-format says markdown.
+ success, and the problem to stderr on error with exit code 1, as JSON unless --error-format says markdown; a
+ command line that does not parse exits 2.
Examples:
pipelex-agent inputs method my-method
diff --git a/pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py b/pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py
index 9001d6336..dbab9cb79 100644
--- a/pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py
+++ b/pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py
@@ -52,7 +52,8 @@ def inputs_pipe_cmd(
"""Generate an example inputs template for a pipe by code.
Outputs the JSON envelope (or raw TOML with --format toml) to stdout on
- success, and the problem to stderr on error with exit code 1, as JSON unless --error-format says markdown.
+ success, and the problem to stderr on error with exit code 1, as JSON unless --error-format says markdown; a
+ command line that does not parse exits 2.
Examples:
pipelex-agent inputs pipe my_pipe
diff --git a/pipelex/cli/agent_cli/commands/run/bundle_cmd.py b/pipelex/cli/agent_cli/commands/run/bundle_cmd.py
index 42a795f91..1dc97782d 100644
--- a/pipelex/cli/agent_cli/commands/run/bundle_cmd.py
+++ b/pipelex/cli/agent_cli/commands/run/bundle_cmd.py
@@ -119,7 +119,8 @@ def run_bundle_cmd(
"""Execute a pipeline from a bundle file (.mthds) or pipeline directory.
Default output is markdown; use --format json for structured JSON.
- Results go to stdout on success, errors to stderr with exit code 1.
+ Results go to stdout on success. A failure writes its problem to stderr and exits 1, or 130 when a hosted run
+ is interrupted; a command line that does not parse exits 2.
Graph visualizations are generated by default; use --no-graph to disable.
Examples:
diff --git a/pipelex/cli/agent_cli/commands/run/pipe_cmd.py b/pipelex/cli/agent_cli/commands/run/pipe_cmd.py
index 1a5a2f86a..6bacf0888 100644
--- a/pipelex/cli/agent_cli/commands/run/pipe_cmd.py
+++ b/pipelex/cli/agent_cli/commands/run/pipe_cmd.py
@@ -97,7 +97,8 @@ def run_pipe_cmd(
"""Execute a pipeline by pipe code and output the results.
Default output is markdown; use --format json for structured JSON.
- Results go to stdout on success, errors to stderr with exit code 1.
+ Results go to stdout on success. A failure writes its problem to stderr and exits 1, or 130 when a hosted run
+ is interrupted; a command line that does not parse exits 2.
Graph visualizations are generated by default; use --no-graph to disable.
Examples:
diff --git a/pipelex/cli/agent_cli/commands/validate/bundle_cmd.py b/pipelex/cli/agent_cli/commands/validate/bundle_cmd.py
index 4e785799e..3df822724 100644
--- a/pipelex/cli/agent_cli/commands/validate/bundle_cmd.py
+++ b/pipelex/cli/agent_cli/commands/validate/bundle_cmd.py
@@ -143,7 +143,11 @@ def validate_bundle_cmd(
run to one pipe. --graph and --view draw the pipe named, else the method's main pipe, and say so when it has none.
Default output is markdown; use --format json for structured JSON.
- Results go to stdout on success, errors to stderr with exit code 1.
+ Results go to stdout on success, and a failure's problem to stderr. Exit codes: 0 when the bundle is valid; 1 on
+ the invalid verdict, on a whole bundle not runnable without --allow-signatures, and when Pipelex fails to boot; 2
+ when no verdict could be produced (a command line that does not parse, a path that is no bundle, a folder holding
+ no bundle, a missing file or pipe, a method file it cannot read, a model no enabled backend serves, a configuration
+ refused before the boot, an unexpected failure) and when the graph or view asked for cannot be drawn.
Examples:
pipelex-agent validate bundle my_bundle.mthds
diff --git a/pipelex/cli/agent_cli/commands/validate/pipe_cmd.py b/pipelex/cli/agent_cli/commands/validate/pipe_cmd.py
index 786e4f138..ca0b7bdce 100644
--- a/pipelex/cli/agent_cli/commands/validate/pipe_cmd.py
+++ b/pipelex/cli/agent_cli/commands/validate/pipe_cmd.py
@@ -60,7 +60,11 @@ def validate_pipe_cmd(
"""Validate a pipe by code, or all pipes, and output the results.
Default output is markdown; use --format json for structured JSON.
- Results go to stdout on success, errors to stderr with exit code 1.
+ Results go to stdout on success, and a failure's problem to stderr. Exit codes: 0 when the pipe or library is
+ valid; 1 on the invalid verdict, on a library not runnable under --all without --allow-signatures, and when
+ Pipelex fails to boot; 2 when no verdict could be produced: a command line that does not parse, an argument it
+ refuses (no pipe code without --all, --all with a pipe code, a path where a pipe code is expected), a pipe code
+ not found or ambiguous, a model no enabled backend serves, an unexpected failure.
Examples:
pipelex-agent validate pipe my_pipe
diff --git a/pipelex/cli/commands/bundle_path_resolver.py b/pipelex/cli/commands/bundle_path_resolver.py
index b3176ff36..3fe5a0a94 100644
--- a/pipelex/cli/commands/bundle_path_resolver.py
+++ b/pipelex/cli/commands/bundle_path_resolver.py
@@ -60,8 +60,10 @@ def resolve_bundle_target(
No verdict is produced, exit 2 with a red message on stderr, for a folder holding no bundle, for a path that is
neither a ``.mthds`` file nor a directory, and for a configuration that does not validate, read for the tree's
- limits before the boot, as the command reports a boot failing on it. A folder whose tree is refused is the invalid
- verdict, which each command reports as its own: ``validate`` as an invalid bundle, ``fix`` as a fix that fails.
+ limits before the boot, which ``pipelex-agent validate bundle`` and ``pipelex-agent fix bundle`` refuse with the
+ same exit code. A lone ``.mthds`` file is not listed before the boot, so the same configuration surfaces only at
+ the boot, which exits 1. A folder whose tree is refused is the invalid verdict, which each command reports as its
+ own: ``validate`` as an invalid bundle, ``fix`` as a fix that fails.
Both ``path`` and each ``library_dir`` entry have ``~`` expanded before resolution, so home-relative inputs behave
like every other CLI path argument.
diff --git a/pipelex/cli/error_handlers.py b/pipelex/cli/error_handlers.py
index b0bbfbb05..6f208c35d 100644
--- a/pipelex/cli/error_handlers.py
+++ b/pipelex/cli/error_handlers.py
@@ -521,17 +521,20 @@ def handle_validate_bundle_error(
def handle_pre_boot_config_error(*, exc: PipelexConfigError, command: str, exit_code: int) -> NoReturn:
- """Report a configuration that cannot be read before the boot, as the command reports a boot that fails on it.
+ """Report a configuration that cannot be read before the boot, naming the command, never as a traceback.
A command handed a method's folder or bundle file lists its method tree before it boots, under the limits the
- configuration sets, so a configuration the boot would refuse is refused there first. It is reported as the
- command's boundary reports the boot's refusal, `Failed to <command>:` and the refusal, which names what to fix and
- the migration that would, never as a traceback.
+ configuration sets, so a configuration the boot would refuse is refused there first. It is reported as
+ `Failed to <command>:` and the refusal, which names what to fix and the migration that would.
Args:
exc: The configuration's refusal.
command: The human command name, as the command's other failures name it (e.g. ``"validate"``).
- exit_code: The exit code the command gives a failed boot.
+ exit_code: The exit code the command gives this refusal. ``validate`` and ``fix`` give 2, since it gives no
+ verdict on the method, as the 0/1/2 policy reserves 2 for, and the agent CLI's ``validate bundle`` and
+ ``fix bundle`` give the same; ``run`` and ``build`` give 1, as they give their other failures. ``validate``
+ and ``fix`` do not list a lone ``.mthds`` file before the boot, so for a file the same configuration
+ surfaces only at the boot, which exits 1.
"""
print_traceback_if_requested(console=get_error_console())
typer.secho(f"Failed to {command}: {exc.message}", fg=typer.colors.RED, err=True)
diff --git a/tests/unit/pipelex/cli/agent_cli/commands/test_bundle_path_resolver.py b/tests/unit/pipelex/cli/agent_cli/commands/test_bundle_path_resolver.py
index b809a847e..cd17da096 100644
--- a/tests/unit/pipelex/cli/agent_cli/commands/test_bundle_path_resolver.py
+++ b/tests/unit/pipelex/cli/agent_cli/commands/test_bundle_path_resolver.py
@@ -1,7 +1,8 @@
"""Unit tests for resolve_bundle_target: shared path resolution for the agent CLI's validate and fix bundle commands.
-Pins that ``~`` is expanded for both the ``path`` argument and each ``--library-dir`` entry, and that a folder is read
-whole, as its method tree, whatever its bundles declare of where the method starts.
+Pins that ``~`` is expanded for both the ``path`` argument and each ``--library-dir`` entry, that a folder is read
+whole, as its method tree, whatever its bundles declare of where the method starts, and that what gives no verdict on
+the folder exits 2.
"""
import json
@@ -9,7 +10,9 @@ from pathlib import Path
import pytest
import typer
+from pytest_mock import MockerFixture
+from pipelex.base_exceptions import PipelexConfigError
from pipelex.cli.agent_cli.commands.bundle_path_resolver import resolve_bundle_target
from pipelex.pipeline.exceptions import ValidateBundleError
from tests.helpers.method_folders import MethodFolderShape, write_method_folder
@@ -76,6 +79,22 @@ class TestResolveBundleTarget:
assert problem["diagnostics"]["error_class"] == "EmptyMethodTreeError"
assert problem["message"] == f"The folder '{tmp_path}' holds no .mthds bundle."
+ def test_a_configuration_that_does_not_validate_before_the_boot_exits_2(
+ self, mocker: MockerFixture, tmp_path: Path, capsys: pytest.CaptureFixture[str]
+ ) -> None:
+ """Listing the tree reads its limits from the configuration: its refusal is the failed boot's problem, no verdict."""
+ mocker.patch("pipelex.libraries.method_trees.local_tree_limits", side_effect=PipelexConfigError("the configuration is out of date"))
+ write_method_folder(directory=tmp_path, shape=MethodFolderShape.ONE_DECLARED_MAIN_PIPE)
+
+ with pytest.raises(typer.Exit) as exc_info:
+ resolve_bundle_target(str(tmp_path), library_dir=None)
+
+ assert exc_info.value.exit_code == 2
+ problem = json.loads(capsys.readouterr().err)
+ assert problem["code"] == "pipelex.config.invalid"
+ assert problem["diagnostics"]["error_class"] == "PipelexConfigError"
+ assert problem["message"] == "the configuration is out of date"
+
def test_a_folder_whose_tree_is_refused_raises_the_verdict_for_the_command(self, tmp_path: Path) -> None:
"""A symbolic link in the tree is the invalid verdict, which each command renders as its surface does."""
write_method_folder(directory=tmp_path, shape=MethodFolderShape.ONE_DECLARED_MAIN_PIPE)
diff --git a/tests/unit/pipelex/cli/agent_cli/test_folder_entry_commands.py b/tests/unit/pipelex/cli/agent_cli/test_folder_entry_commands.py
index 75417ddb7..62e5e3bcd 100644
--- a/tests/unit/pipelex/cli/agent_cli/test_folder_entry_commands.py
+++ b/tests/unit/pipelex/cli/agent_cli/test_folder_entry_commands.py
@@ -222,18 +222,22 @@ class TestAgentFolderEntryCommands:
assert "linked.mthds" in capsys.readouterr().err
mock_fix.assert_not_called()
- @pytest.mark.parametrize("command", ["validate", "fix", "inputs", "run"])
+ @pytest.mark.parametrize(("command", "exit_code"), [("validate", 2), ("fix", 2), ("inputs", 1), ("run", 1)])
def test_a_configuration_that_does_not_validate_before_the_boot_is_the_failed_boot_problem(
- self, mocker: MockerFixture, tmp_path: Path, capsys: pytest.CaptureFixture[str], command: str
+ self, mocker: MockerFixture, tmp_path: Path, capsys: pytest.CaptureFixture[str], command: str, exit_code: int
) -> None:
- """Listing the tree reads its limits from the configuration: a refusal there is the problem a failed boot gives."""
+ """Listing the tree reads its limits from the configuration: a refusal there is the problem a failed boot gives.
+
+ `validate` and `fix` exit 2 on it, no verdict, as the human `pipelex validate bundle` and `fix bundle` do;
+ `inputs` and `run` exit 1, as a failed boot does.
+ """
mocker.patch("pipelex.libraries.method_trees.local_tree_limits", side_effect=PipelexConfigError("the configuration is out of date"))
write_method_folder(directory=tmp_path, shape=MethodFolderShape.ONE_DECLARED_MAIN_PIPE)
with pytest.raises(typer.Exit) as exc_info:
_invoke_pre_boot_command(command=command, path=tmp_path)
- assert exc_info.value.exit_code == 1
+ assert exc_info.value.exit_code == exit_code
problem = json.loads(capsys.readouterr().err)
assert problem["code"] == "pipelex.config.invalid"
assert problem["diagnostics"]["error_class"] == "PipelexConfigError"
diff --git a/tests/unit/pipelex/cli/commands/test_folder_entry_commands.py b/tests/unit/pipelex/cli/commands/test_folder_entry_commands.py
index 2771b6c9e..7ba193e02 100644
--- a/tests/unit/pipelex/cli/commands/test_folder_entry_commands.py
+++ b/tests/unit/pipelex/cli/commands/test_folder_entry_commands.py
@@ -174,7 +174,11 @@ class TestHumanFolderEntryCommands:
def test_a_configuration_that_does_not_validate_before_the_boot_is_reported_as_a_failed_boot(
self, mocker: MockerFixture, tmp_path: Path, capsys: pytest.CaptureFixture[str], command: str, exit_code: int
) -> None:
- """Listing the tree reads its limits from the configuration: a refusal there names the command, never a traceback."""
+ """Listing the tree reads its limits from the configuration: a refusal there names the command, never a traceback.
+
+ `validate` and `fix` exit 2 on it, no verdict, as the agent CLI's `validate bundle` and `fix bundle` do; `run`
+ and `build` exit 1, as their other failures do.
+ """
mocker.patch("pipelex.libraries.method_trees.local_tree_limits", side_effect=PipelexConfigError("the configuration is out of date"))
write_method_folder(directory=tmp_path, shape=MethodFolderShape.ONE_DECLARED_MAIN_PIPE)