carlos / platform Public

The build probe an existing app could never get, and a deploy that says

what it is watching

Discussion #13: `carlos deploy` printed "live" and exited 0 while the
previous binary was still serving. Every platform-side signal agreed,
because they all describe the ADOPTED release rather than the running
process — the edge stamps X-Carlos-Version from the route row the moment
adoption moves a symlink, whether or not anything restarted. The
instance had also silently missed an earlier adoption hours before, so
the box had been two releases stale with nothing reporting a problem.

The platform already had the answer. An app may declare a BUILD PROBE —
a path whose body names the build actually running — and the deploy
watch polls the app's own process instead of the header. That closes
exactly this gap, and #13's first suggestion is a description of it.

It could only be set at CLAIM time. SetAppBuildProbe had precisely one
caller, handleAPICreateApp, so an app created before the flag existed —
or one whose author did not think to pass it, which is most of them —
could never acquire a probe. The fix was unreachable by exactly the apps
that had the bug. That is the actual defect, and it is what this closes:

    carlos apps build-probe --app docs /api/version
    carlos apps build-probe --app docs -            # back to the header

- POST /api/cli/apps/{account}/{app}/build-probe, registered with an
  EMPTY role set and added to closedDoors AND policyDoors with the
  reason: the probe is what the deploy watch trusts INSTEAD of the
  header, so a credential able to rewrite it is a credential able to
  make its own deploys report success over a process that never cycled —
  the precise failure the probe exists to prevent, handed to the wrong
  caller. A person sets it once.
- The stored value is read back and echoed, and the CLI compares it, the
  same discipline `apps create` already applies to this field. Its whole
  job is to be trusted.
- "-" clears, the sentinel `--unit` and `--environment` use, because ""
  is a LEGAL value here (it means header-watching) and an empty argument
  must not be mistaken for one nobody meant to pass.
- The shape is validated at the write door too, not only where deploy
  reads it: the watch concatenates probe onto an origin, so
  "@evil.example/x" would poll a machine of someone else's choosing and
  report ITS build as this deploy's.

And the silence that made the bug survivable is gone. A deploy with no
probe now says, while it waits, that the header reports the release
adopted rather than the build running, and names the one command that
fixes it for that app. It already exits non-zero on a watch timeout;
what it could not do was tell you that a SUCCESS meant less than it
looked.

Also `carlos deploy --label/--notes`, filed in the same discussion: a
deploy is a ship plus a promote, the ship half has carried both since it
existed, and deploy passed "" — so `--label` failed with "flag provided
but not defined" and dumped usage. runShipAPI already took both
arguments; nothing below the flag had to change.

Not fixed here, and worth its own decision: the fire-and-forget restart
arms. adoptHost stamps Version after a restart callback returns nil, and
arms 2 and 3 (carlos-app@ unit tenants, exec children) swallow their
errors deliberately, so one tenant's failed cycle cannot poison a
release for the rest of the pass. That is the right trade for the pass
and the wrong one for the stamp, and the activator's 90s convergence
sweep is the only backstop — with two silent failure modes of its own
(a persistent symlink read error, or a backend with no LiveVersion,
both of which return "do not cycle" forever without a log line).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QVvK41AUKXndpcy5KkUZRS