[linyows]

Adds an `## Unreleased` section to CHANGELOG.md for the refactoring series, above v1.27.0, in the file's own style: what breaks for code that imports probe as a library, with a table of what to use instead for each, and a list of behaviour changes a workflow may notice, each with its PR.

The entries were checked against `apidiff` from v1.29.0 to this branch, so they describe the net change since the last release, including the main PRs since v1.29.0 that changed the Go API (#410–#422 and on), and leave out what was added and then renamed within the series. Two external actions outside this repository, probe-agent and probe-browser, import `mapping`; the section `If your action imports mapping` tells them the `actionrpc` functions to use instead.

🤖 Generated with Claude Code

https://claude.ai/code/session_01X6CYBxNCxQyo1rbdg9hQ42

[linyows]

Adversarial accuracy pass over the Unreleased section, against v1.29.0 vs origin/docs/changelog-refactor (834b1f9).

What I verified

• Ran apidiff -m from v1.29.0 to this head. Every incompatible change it reports is covered: the 10 removed packages, all root-package removals and signature changes (NewExecutor, NewPrinter, JobResult.Status, the JobContext fields, ActionRunner.Run), actionrpc (RunStep/RunExecutableStep/Run removed, RunExecutable/Client.RunStep changed, Server.Run/Cleanup now taking internal/pb types), every Serve/Keeps/Params of the action packages, embedded.ServeWithActions, the 16 imap Req methods, and all the smtp removals and changes. I found no incompatible change that is missing.
• I checked go doc on old and new for: actions.Configure (it sets exactly Actions and NeedsNoCheck), actions.CheckOptions (it fills every field except Manifest), DecodeParams/EncodeResult/ParamNames/ParseTimeout, RunBuiltin/RunExecutable, TermGrace/ExitWait, ReadJobFile, WithActionRunner/WithNeedsNoCheck, Executor.Run, RunOptions.Context, Workflow.Env (v1.29.0 Start merged Config.Env into w.env), smtp.Dial/Deliver/Bulk.DeliverWithResult, imap Request/NewReq/Req.Do, and Result.SetReporter, StepResult.Failure, Config.Baseline and Probe.ExitStatus as the replacements named. The old actionrpc.Run/RunStep/Client.Run signatures match the Before column.
• I read the code behind these behaviour claims and found each accurate: the JobResult.Status strings in v1.29.0 (Running/Completed/Failed/skipped). The code-built job ID that fell back to its name (old workflow.go:230). PROBE_TTY moving from probe.New to cmd/probe. Interval going through duration.Parse with the error invalid duration %v: %w. duration.Parse rounding to the nearest ns, where the old mapping.ParseTimeout truncated. The time.Duration field that now refuses numbers (the old code converted 30 to 30ns). Ints that are refused rather than truncated, and bools that take 0 and 1. The map[string]string path through StringMap. The shell, ssh, grpc, db and dns timeouts: ssh and grpc used bare time.ParseDuration, db and dns took integers only, and shell accepted 0. The http timeout, where 0 still means no limit and the too-long, sub-nanosecond and wrap cases are refused. The smtp bounds (maxSession=1000, maxLength=100<<20, maxTimeout=24h, defaultTimeout=1m). Old Res.FilePath always empty, because ProcessHttpBody got text/plain. Old wait integer-only parsing. The PR attributions for #475 and #485.

Findings (inline): one must-fix, that the hello paragraph is framed against an intermediate state rather than v1.29.0. Two should-fix: Behaviour Changes leaves out several user-visible changes merged to main after v1.29.0, and the "workflow files are not affected" scope sentence. Two nits on completeness.

Style nit, not inline: earlier ### Behaviour Changes sections (v1.18.0, v1.19.x) are prose paragraphs without PR numbers. This one is a bullet list with (#NNN). That is arguably better for a list this long, but it differs from the existing entries.

[linyows]

must-fix. This is framed against an intermediate state, not v1.29.0. v1.29.0's engine never knew hello by name: there is no "hello" in any non-test root file at the tag. The special case came in after v1.29.0, with d54472f ("Do not warn of a hello step that has no test") and 803cb78 ("Pass a hello step that has no test when it runs"), via #448. It was then moved out to NeedsNoCheck in this series. So against v1.29.0, the engine does not "no longer" know hello. What changed for library users is that Config.NeedsNoCheck/CheckOptions.NeedsNoCheck/WithNeedsNoCheck are new, and leaving them unset keeps v1.29.0's behaviour, which the last sentence already says correctly. Suggest dropping the first sentence, or rewording it to "The engine does not know the hello action by name: which actions' steps pass without a test is told to it ...".

The change is also user-visible and missing from Behaviour Changes: with the probe command, probe check no longer warns of a hello step without a test, and a run passes such a step instead of marking it untested (the triangle, and untested in the reports).

[linyows]

should-fix. This list covers the refactoring PRs and the main fixes #452–#472. It leaves out several user-visible changes that were also merged to main after v1.29.0 (2026-10-16) and so ship in this release. I checked that each PR's merge commit is not an ancestor of v1.29.0:

• Start a job as soon as the jobs it needs are done #412: a job starts as soon as the jobs it needs are done, rather than in waves that wait for unrelated slower jobs. This changes timing and output order. Line 245 mentions only its jobs ... cannot run error.
• Make Probe easier to use when things go wrong #433 (Merge the workflow files given as separate arguments #432): probe a.yml b.yml merges the files, where it used to drop b.yml silently. A non-YAML file named directly is an error. Also new: --job.
• Make Probe easier to use when things go wrong #433 (Report names an expression reads that are not there #437), Mask the secrets a URL holds, check the fields a step reads, and keep the docs checked #448 (Check the fields of res and req a step reads, and the keys its action needs #447) and Report type errors in expressions before a workflow runs #450: probe check now reports, as errors, names an expression reads that are not there, res/req fields the action never returns, missing required keys, and expression type errors. A workflow that passed check in v1.29.0 can fail it now, which matters for CI.
• Mask the secrets a URL holds, check the fields a step reads, and keep the docs checked #448 (Mask a short secret only where it is a whole value #443/Redact the credentials of a URL in any output, whatever their length #444): a secret shorter than 4 characters is masked only where it is a whole value, with a warning; before, it was masked everywhere. URL credentials are redacted whatever their length. This is security-relevant output behaviour.
• Start each run of a workflow afresh: no job failed, no outputs, every job and its own env #459: starting the same *Workflow twice gives a fresh run (failed flag, outputs, Config.Jobs selection). Line 133 covers only the env part.

Either add them, or say in one line that this list covers only part of the release and point to the release notes for the rest.

[linyows]

should-fix. "Workflow files are not affected, except as told under Behaviour Changes below" leaves out something that is told elsewhere: lines 143–145 say Load (and Start for a code-built workflow) now refuses a workflow whose expressions, templates, step IDs or written wait cannot run, before any job runs. That comes from #421, after v1.29.0. A workflow whose bad expression sits in a step that never ran, for example one skipped by skipif, ran in v1.29.0 and is now refused. That is a workflow-file change, so it belongs in Behaviour Changes as a bullet, or this sentence should point to it. The same goes for the stricter probe check (see the comment on line 230).

[linyows]

nit. apidiff lists further exported additions this paragraph does not name: actionrpc.Contract, actionrpc.ContractMatch, actionrpc.Violation and the type actionrpc.Processes (only Call.Processes and Process are listed). Also report.Selection (the type; Report.Selection is listed), (*shell.Action).RunStep, and cmd/probe Cmd.Jobs/Cmd.Trace. They are harmless additions, but the paragraph reads as exhaustive.

[linyows]

nit. "Keeps() and Params() of each package" overstates it. Per apidiff, Keeps existed only in db, dns, embedded, grpc, hello and http, and Params in every package except hello. Suggest "Keeps() and Params(), where a package had them".