Skip to content

fix: wait for ready log before reporting project readiness - #555

Draft
awjdean wants to merge 5 commits into
F1bonacc1:mainfrom
awjdean:fix/ready-log-line-readiness
Draft

awjdean wants to merge 5 commits into
F1bonacc1:mainfrom
awjdean:fix/ready-log-line-readiness

Conversation

@awjdean

@awjdean awjdean commented Oct 2, 2026 •

Copy link
Copy Markdown

project is-ready can exit successfully while a running process has not yet printed its ready_log_line. With this change, a process with a ready_log_line counts as ready only once that line appears, so the project stays not ready until then. The same applies to --detach-on-success.

This only applies when Process Compose can see the process's output. Some processes write straight to the terminal, so Process Compose never sees their output and could never find the line. Those processes are listed below and behave as before.

Fixes #557

Implementation

Each time a process starts, newIncarnationState (src/app/project_runner.go) builds its state. It now sets HasHealthProbe when both of these are true:

  • the process has a ready_log_line, and
  • Process Compose reads the process's output.

HasHealthProbe is the flag that readiness and liveness probes already set, so no new check is needed. The existing readiness checks already require a process with this flag to be healthy, and they report a process that is still waiting for its line with the existing health is Unknown reason.

Process Compose does not read the output of the processes below, so their ready_log_line does not affect readiness:

Process Why its output is not read
Interactive process (is_interactive) It owns its own terminal.
The process selected by process-compose run It uses Process Compose's own stdin, stdout and stderr.
Elevated process (is_elevated) when the TUI is disabled It also uses Process Compose's own stdin, stdout and stderr.
Foreground process (is_foreground) started from the TUI The TUI runs it directly in the terminal.

newIncarnationState checks the first three explicitly. The fourth needs no check: the TUI runs a foreground process itself, so newIncarnationState is never called for it.

Other notes:

  • The rule for "uses Process Compose's own stdin, stdout and stderr" used to be written inline in getProcessStarter (src/app/process.go). It is now a small helper, usesAttachedIO. The code that starts a process and the new readiness code both call it, so the two cannot drift apart.
  • src/types is unchanged. NewProcessState only sees the process config. It does not know whether the TUI is on or which process process-compose run selected, so it cannot tell whether the output is read.
  • One visible side effect: once such a process has started, has_ready_probe is true in its state JSON (for example in process list --output json).
  • Processes with neither a probe nor a ready_log_line behave as before.

Tests and documentation

  • TestProjectRunner_newIncarnationStateLogReadiness is a table test. It checks case by case whether a ready_log_line makes a process wait:
    • It does for normal (piped) output, for a foreground process started through the runner instead of the TUI, and for an elevated process when the TUI is on.
    • It does not for an interactive process, for the process selected by process-compose run, or for an elevated process when the TUI is off.
    • A process whose output is not read still waits for its own probe, if it has one.
  • TestProjectRunner_ForegroundLogReadiness checks that a foreground process that has not been started yet does not hold the project back.
  • TestSystem_TestReadyLineProjectReadiness starts a real process that prints its ready line after one second. It waits for the project to become ready, then checks that the process was already healthy at that moment. In other words, the project did not become ready before the line was printed. The test does not assert "not ready" at a fixed earlier time, because that would fail whenever the test happens to run slower than the process.
  • www/docs/launcher.md gains two notes:
    • A process with a ready_log_line is not ready until the line is printed, with project is-ready and --detach-on-success as examples. A process that exits without printing the line, or that is stopped, is not ready.
    • The line is only detected in output that Process Compose captures, followed by the four exceptions from the table above.

Validation

Run on macOS (arm64) with Go 1.26.8, at commit cfd78b9:

  • make build passed.

  • make lint passed with zero issues. This used golangci-lint 2.11.3, the version pinned in the Makefile.

  • make testrace passed for every package except src/app, where one test, TestWatch_ExitOnEndSurvivesRestart, was reported by the race detector. This failure is not caused by this PR:

    • The race is between starting and stopping the file watcher (src/app/project_watch.go), which this PR does not touch.

    • The same test fails the same way, intermittently, on main at 23b0aca (the commit this branch is based on).

    • With that one test skipped, src/app passes with the race detector:

      go test -race ./src/app -count=1 -skip TestWatch_ExitOnEndSurvivesRestart
  • The new tests fail without the fix:

    • With the new lines in newIncarnationState removed, TestProjectRunner_newIncarnationStateLogReadiness and TestSystem_TestReadyLineProjectReadiness fail.
    • With the flag set for every process that has a ready_log_line, whether or not its output is read, TestProjectRunner_newIncarnationStateLogReadiness and TestProjectRunner_ForegroundLogReadiness fail.
  • The reproduction script from project is-ready reports success before ready_log_line is emitted #557, run against the built binary:

    • Before the ready line is printed, project is-ready exits with 1 and reports app (health is Unknown).
    • After the line is printed, it exits with 0.

Nix package build

Built from a clean clone of commit cfd78b9 in Docker containers, with Nix 2.35.2 and Go 1.26.1 (the version pinned by the flake). Both targets passed:

Target Container
x86_64-linux (the target the Nix workflow builds) linux/amd64, emulated on an ARM64 host
aarch64-linux linux/arm64, native
# x86_64-linux
nix --extra-experimental-features "nix-command flakes" --option filter-syscalls false build \
  --no-link --print-out-paths -L .#packages.x86_64-linux.process-compose

# aarch64-linux
nix --extra-experimental-features "nix-command flakes" build \
  --no-link --print-out-paths -L .#packages.aarch64-linux.process-compose
  • In both runs, the build, package test (checkPhase), install, and fixup phases all passed (exit status 0).
  • The package tests passed for every Go package, including the new tests in src/app. They run without the race detector, so the watcher race described above is not reported here.
  • --option filter-syscalls false is only there because the x86_64-linux container runs under emulation. An earlier attempt without it failed before compilation with unable to load seccomp BPF program: Invalid argument. The option turns off Nix's system-call filter for the build sandbox. It does not change what is built or tested.

Guard the transition from actual ready-log output to project readiness,
and document when callers can consider the project ready.

Refs F1bonacc1#557
@awjdean
awjdean marked this pull request as ready for review October 11, 2026 04:07
@sonarqubecloud

Copy link
Copy Markdown

@awjdean

awjdean commented Oct 12, 2026

Copy link
Copy Markdown
Author

Please merge #562 before this PR, then update this branch from main.

#562 makes liveness probes stop gating project readiness and renames ProcessState.HasHealthProbe to HasReadyProbe. This PR adds references to the old field name. Landing #562 first gives this branch the final field name and liveness semantics before adapting its implementation and tests.

Keep ready_log_line gating in this PR's output-aware newIncarnationState logic. #562 is staying focused on liveness. A generic log gate in NewProcessState would bypass this PR's exceptions for interactive processes, the process selected by run, and elevated processes without the TUI; combining that approach with this PR reproduced failures in all three existing test cases. This PR already covers the deferred foreground/log-readiness case.

After #562 merges:

  • Update the added HasHealthProbe references to HasReadyProbe.
  • Change the “unscanned output keeps its probe” test fixture from a liveness probe to a readiness probe, since a liveness probe should no longer set the readiness flag.
  • Preserve the output-capture checks and rerun the log-readiness tests.

{name: "elevated without TUI", proc: types.ProcessConfig{ReadyLogLine: "ready", IsElevated: true}},
{
name: "unscanned output keeps its probe",
proc: types.ProcessConfig{ReadyLogLine: "ready", LivenessProbe: &health.Probe{}},

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

About the plan for after #562: switching this to a readiness probe would test a config the loader rejects (readiness_probe together with ready_log_line fails validateNoIncompatibleHealthChecks). Once liveness no longer gates readiness, I think this case should just be removed rather than converted.

Comment thread src/app/process.go

// usesAttachedIO reports whether the process inherits process-compose's own
// stdin, stdout and stderr instead of having its output piped through it.
func usesAttachedIO(proc *types.ProcessConfig, isMain, isTuiEnabled bool) bool {

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Small nit: the helper only covers half of the "do we read the output" rule. !IsInteractive is still checked separately below in getProcessStarter and again in newIncarnationState. Maybe something like:

// scansOutput reports whether process-compose reads the process output,
// and so can see its ready_log_line.
func scansOutput(proc *types.ProcessConfig, isMain, isTuiEnabled bool) bool {
	return !proc.IsInteractive && !usesAttachedIO(proc, isMain, isTuiEnabled)
}

used in both places, so they really can't drift.

@F1bonacc1

Copy link
Copy Markdown
Owner

Oh, and don't worry about the lint failing. It is already fixed in main.

@awjdean
awjdean marked this pull request as draft October 26, 2026 14:08

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

project is-ready reports success before ready_log_line is emitted

2 participants