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.

follow-ups ôlish

Louis Choquel8668c2d6b0f4
diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.toml
index ca638ab96..c2889fe0e 100644
--- a/.drift/acks/cli-docs.toml
+++ b/.drift/acks/cli-docs.toml
@@ -1,8 +1,8 @@
contract = "cli-docs"
-digest = "sha256:e0ae9abafd983c542d19e338a7b7f6cefa720d8c668872efa08d324ff417b13b"
+digest = "sha256:ef75f1a9eff0100feb5e38e6e522fd22e4363680c3bd9487734f38bd6acb7c39"
reviewed_by = "Louis Choquel"
-reviewed_at = "2026-08-17T13:45:26Z"
-rationale = "Reviewed docs/tools/cli/ and the agent-CLI contract doc against the two CLI changes in this commit. One target was genuinely stale and is now false rather than merely incomplete: migrate.md said the command does not descend into subdirectories and that inference backends are never rewritten by it, which stopped being true when the walk learned to enter a directory a surface owns. Rewritten to say what it now does and, just as importantly, what it still does not - one level, only into a directory some configuration family owns, so inference/deck/ and the inference/backends.toml beside the directory stay out, and the model deck keeps its own update command. The other change is the wording of one rendered operation, which turns a literal wildcard segment into English: it renders ledger material only, so the agent-CLI doc's standing claim that paths, operation kinds and ledger-supplied values are all that appear is unaffected, and no flag, stream, format, structured field or exit code moved. docs/tools/cli/index.md still has no doctor page."
+reviewed_at = "2026-08-17T19:54:27Z"
+rationale = "Reviewed docs/tools/cli/ and the agent-CLI contract doc against a docstring-only correction in migrate_cmd.py. No surface moved - no flag, format, stream, structured field or exit code - so nothing in either target went stale by omission. Checked them for the specific claim the correction removes: the module docstring had said the transaction refuses where the rehearsal and the write pass disagree, which conflated two windows of very different widths. The agent CLI cannot be affected at all, since it is single-pass (dry_run = not yes) and has no confirmation window to edit a file during, and its contract doc makes no two-pass claim. migrate.md is likewise not falsified: it documents the backup and the atomic replace, both accurate, and never promises that the previewed report is what gets applied. What migrate.md could gain is a new sentence telling the user the files are re-read after they answer, and that is deliberately held rather than written now: whether the rehearsal should bind the write is an open design question recorded in wip/migrator-pr-1117-review-followups.md, and documenting behavior that may change is how a doc goes stale on purpose."
[trigger_files]
"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"
@@ -105,7 +105,7 @@ rationale = "Reviewed docs/tools/cli/ and the agent-CLI contract doc against the
"pipelex/cli/commands/init/ui/types.py" = "blob:1361f29ca95bacc90bca90ea6c0e39f44b6734ab"
"pipelex/cli/commands/login/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/commands/login/command.py" = "blob:ace1db9879626cc1722adaac12761aadaa6b24ed"
-"pipelex/cli/commands/migrate_cmd.py" = "blob:fa352e722f238b4785e83e37e413d8728a820c0c"
+"pipelex/cli/commands/migrate_cmd.py" = "blob:ffd3b0ff4fb8448bd03204b4381fb4f214a88271"
"pipelex/cli/commands/plugins_cmd.py" = "blob:9657b713c3650ff4a929e92ae68af453d896393e"
"pipelex/cli/commands/resolve_cmd.py" = "blob:2928a0e26eab7983367a59a78533f6618817feba"
"pipelex/cli/commands/run/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
diff --git a/pipelex/cli/commands/migrate_cmd.py b/pipelex/cli/commands/migrate_cmd.py
index fa352e722..ffd3b0ff4 100644
--- a/pipelex/cli/commands/migrate_cmd.py
+++ b/pipelex/cli/commands/migrate_cmd.py
@@ -11,10 +11,16 @@ deck, no credentials, no network. That is a property to preserve, not an acciden
a test that hands the command a configuration that cannot load.
Two passes, and they are not the same pass twice for the sake of it. The first is a dry run whose
-report is what the user is shown and asked about; the second is the one that writes. Under
-always-replay the two agree, and where they do not — because the user edited a file in between, or
-another process did — the second is the authoritative one and the transaction refuses rather than
-writing over work it never saw.
+report is what the user is shown and asked about; the second is the one that writes, and it reads
+each file again rather than carrying the rehearsal's reading forward. Under always-replay the two
+agree. Where they do not — because the user edited a file while the question was on screen, or
+another process did — the second is the authoritative one: what lands is a correct migration of the
+file as it now stands, the copy taken beside it holds the exact bytes replaced, and the report
+printed afterwards is that pass's rather than the rehearsal's.
+
+What the per-file transaction refuses over is narrower than that, and worth not reading as more: it
+compares against the reading *that pass* took, so what it catches is a writer landing between this
+run's own read and its replace, and not an edit made while the confirmation was pending.
See `docs/migration-ledger.md`.
"""
diff --git a/wip/migrator-pr-1117-review-followups.md b/wip/migrator-pr-1117-review-followups.md
new file mode 100644
index 000000000..efe7183d7
--- /dev/null
+++ b/wip/migrator-pr-1117-review-followups.md
@@ -0,0 +1,53 @@
+# The release PR — items deferred from the PR #1117 review
+
+What the review-bot pass on [PR #1117](https://github.com/Pipelex/pipelex/pull/1117) surfaced and this branch did **not** fix, with why.
+
+**Read the pass itself before reading its findings.** Two of the three bots never reviewed this PR at all: Greptile refused on file count (517 files against a 200-file limit) and Cubic on size (51,431 reviewable changed lines against a 50,000 limit, most of it `.test_durations` and the three `[email protected]` goldens). Neither posted a single comment. So the near-silence on this PR is evidence of a diff too large to review, **not** evidence of a clean one — and the reflex it should provoke is about the release PR's shape rather than about the code: a release branch that carries a whole phase of migrator work in one diff is a branch no automated reviewer will read. The per-feature PRs that fed it (#1111, #1114, #1115, #1116) were each reviewed in full, which is where the coverage actually came from.
+
+That left one thread, from Codex, and it is confirmed. Its documentation half was fixed on the branch: the `migrate_cmd` module docstring claimed that where the rehearsal and the write pass disagree "the transaction refuses rather than writing over work it never saw", which conflates two windows of very different widths and leaves a reader believing an edit made at the prompt is refused. It is not. The docstring now separates them — what the second pass is authoritative over, and the much narrower thing the per-file transaction actually guards. The behavior half is item 1 below.
+
+Item 2 came from running the suite rather than from a bot, and it is the more interesting of the two.
+
+## 1. The rehearsal a user answered is not binding on the write
+
+**Reporter:** Codex, P2 (`pipelex/cli/commands/migrate_cmd.py`) — [thread](https://github.com/Pipelex/pipelex/pull/1117#discussion_r3798218312).
+
+The mechanism is real and worth stating precisely, because the two file-reads involved sit close enough together to be mistaken for one. `migrate_cmd` rehearses, prints, and asks; on a yes it calls `apply_pending_migrations`, which starts a **completely fresh** pass. That pass re-reads every file from disk (`read_file_snapshot(file_path.resolve())` in `migration/runner.py`) and replays the ledger over whatever it now finds. The conflict guard, `assert_snapshot_unchanged` in `pipeline/fixes/file_transaction.py`, compares against the snapshot taken *inside that second pass* — so its window is pass-2-read → replace, a matter of milliseconds. A file edited while `Confirm.ask` was on screen is outside it entirely: the edit is adopted as the new basis for the migration, and operations the user never previewed are applied on a yes that answered a different report.
+
+**Why deferred — and the reason is that the consequence is much milder than the promise the docstring made.** Nothing is lost: `_write_migrated_file` backs up the exact bytes it is about to replace, taken from that same second-pass snapshot, so the user's just-edited content is what lands in the `.bak.` copy. Nothing is misreported either: the summary printed afterwards is the second pass's own report, so the user is told what actually happened rather than what was rehearsed. And what lands is correct — the second pass is byte-for-byte what a fresh `pipelex migrate` would do to that file, which is what always-replay means. The gap is a consent gap, not a data-integrity one.
+
+Set against that, the stricter behavior is a genuine tradeoff rather than an obvious win. Refusing on any change-since-rehearsal means a user who fixes a typo at the prompt has their *repair* command refuse them and has to run it again — on a command whose entire reason to exist is repairing a machine that will not boot. Nor is it a small change: making the promise true means carrying a digest of each rehearsed file forward on `MigrationPlan`, threading an expected-digest parameter down `migrate_config_directories` → `migrate_directories` → `migrate_file`, and deciding what the *other* caller does. That caller is `doctor --fix`, which reaches the same write pass with its own row as the dry run, and whose confirm window is wider still — several rows and possibly several other prompts separate the two. A release branch is the wrong place to add plumbing to the write path of a command that rewrites user configuration files.
+
+**Recommendation:** decide the question before building for it, because the two answers want different code.
+
+If the answer is *the rehearsal binds*, the shape is the one above — a `source_digest` on `MigrationPlan`, an optional `expected_digests: dict[Path, str] | None` on `migrate_directories` that `migrate_file` checks before replaying, and a mismatch returning a blocked plan under `FileBlockedReason.CHANGED_DURING_RUN`, whose existing docstring ("between the read and the write") would need widening to match. `doctor --fix` then has to pass the digests its row measured, or explicitly opt out and say why.
+
+If the answer is *the write pass binds* — which is what ships today, and is defensible — then nothing is owed in code and the remaining work is a sentence in `docs/tools/cli/migrate.md` telling the user plainly that the file is re-read after they answer, so that the guarantee is stated where a user reads it rather than only where a maintainer does.
+
+The one option to rule out is leaving the prose ahead of the code again. That is what this thread caught.
+
+## 2. The kernel boot contract holds only while no configuration file is stale
+
+**Reporter:** none — found by running `make agent-test` on this branch, on a machine whose configuration had not been migrated.
+
+Three tests fail here and pass in CI, and the gap between those two facts is the finding. `tests/unit/pipelex/kernel/test_kernel_boot_contract.py::test_every_kernel_call_runs_on_a_kernel_only_boot_with_no_library`, `tests/unit/pipelex/test_runtime_boot_closure.py::test_booting_the_kernel_layer_loads_no_interpreter_module_and_installs_no_interpreter_hub`, and `tests/integration/pipelex/system/test_load_config.py::test_load_config` all fail on one condition: this checkout's `.pipelex/pipelex_override.toml` still carries the pre-reshape `[pipelex.*]` root that `#1111` removed. That file is **gitignored** — a personal, machine-local override — so CI checks out a tree without it and never meets the condition.
+
+The first two do not fail *because* the configuration is stale. They fail because of what tolerating it costs. The boot handles the stale file exactly as designed: it reads it as if migrated, warns, writes nothing, and names `pipelex migrate`. But the retry that does the tolerating reaches the migration engine, and `pipelex/migration/engine.py` imports `apply_fix_ops` from `pipelex.pipeline.fixes.applier` — an interpreter package. So the kernel-only boot ends up having loaded `pipelex.pipeline`, `pipelex.pipeline.fixes` and `pipelex.pipeline.fixes.applier`, and the contract test reports precisely that: `the kernel call loaded 3 interpreter module(s)`.
+
+**The hazard was known, and half of it is already mitigated — which is the part worth reading before reaching for a fix.** The retry's import of the engine is function-local, and the comment above it at `pipelex/system/configuration/config_surface.py` says why in as many words: the engine's applier lives under `pipelex.pipeline`, an interpreter package, while that module sits in `runtime_hub`'s import closure. Deferring the import buys a real and deliberate guarantee — *a boot whose configuration validates never imports the migration engine at all*. That guarantee holds. What it does not cover, and what the comment does not claim, is the stale path: there the import fires, and the closure is no longer clean. So the accurate statement is not "the kernel contract is broken" but **"the kernel contract is conditional on the healthy path, and the test asserts it unconditionally"** — the two disagree only where a configuration is stale.
+
+**Severity is narrow, and worth stating so nobody fixes this in a panic.** Three modules get imported. No interpreter hub is installed — the boot-closure test checks both and only the import half trips — so no ambient interpreter state is created, nothing changes behavior, and nothing crashes. The cost is import-closure purity in a slim or kernel-only deployment, which matters for the distributed-activity wrapping the kernel doctrine is designed to keep cheap, and not much before then.
+
+The causal chain was checked rather than assumed. Running the contract test's own subprocess script from a working directory with no stale override returns `0` and prints `kernel boot contract OK`; running it from this repository returns `1` and names the three modules. Nothing else differs between the two runs.
+
+**Why deferred:** it is pre-existing, it is not what this PR is about, and the sharing underneath it is deliberate — the migration engine and the `.mthds` fix loop want one applier and one set of transaction primitives, and duplicating them to satisfy a layer boundary would be the worse trade. With the mitigation already in place and the severity as narrow as it is, there is nothing here urgent enough to change on a release branch.
+
+**Recommendation:** treat it as a hub-layering question, not a migration one, and pick one of three.
+
+The narrow structural move is to lift the op-application core out of `pipelex/pipeline/fixes/` into a layer both callers may import. `applier.py` and `file_transaction.py` hold no fix-loop or pipeline concepts — op application, snapshot, stage, atomic replace, rollback — so their present address under `pipelex.pipeline` is historical rather than structural, and moving them would make the contract unconditional instead of healthy-path-only.
+
+The cheap honest move is to leave the code alone and teach the two tests the condition the code already documents: assert the contract on a healthy configuration, and assert separately that the stale path is the *only* thing that breaches it. That converts a test which fails on developer machines for an understood reason into one that pins the reason.
+
+The move to rule out is widening the comment and doing nothing else. The comment is already accurate about what it claims; the gap is between what it claims and what the test asserts.
+
+One thing to fix regardless of which is chosen: `check-hub-layering` cannot see this. It chases `interpreter_hub` installation, and this offender installs no hub — it only imports modules. So the sole detector today is a full `make agent-test` on a machine that happens to be stale, which is the opposite of a reliable signal, and it is why this went unnoticed until a dogfooding run turned it up.