docs: attribute the polling, and state what confirmation trusts

Two corrections to what the notes claim.

The release note described bin/castle install polling running/1, which
is Forecastle's behaviour and not Castle's integrated state: mix.lock
pins Forecastle at 7eb5acc, whose bin/castle installs with a single rpc
and never calls running/1. Castle supplies the answer; the asking
belongs to Forecastle, from its own 1.0.0. Said that way round in both
RELEASE.md and AGENTS.md, without claiming the pair's behaviour is
already in effect here.

The boot-completion check trusts the selected boot script to emit
{progress, started} where it means what it says, and that is worth
saying out loud. A RELEASE_BOOT_SCRIPT naming a hand-written script that
never reaches the marker is never confirmed - install waits, then fails,
and the refusal names the progress the node did reach, so it is
diagnosable and never a false success - and one that emits the marker
before its applications start defeats the check. Neither is validated:
Mix generates these scripts and offers no rel/ template for them, so
reaching either state takes deliberate work.

That also corrects something I wrote in the previous commit.
systools_make:add_apply_upgrade/2's hard match on the trailing marker
does not rule this out: it builds the hybrid script for an emulator
upgrade and says nothing about a script an operator supplies.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01C4oaMvbR1cbxrZBj8qwkqN

Author: ausimian

AGENTS.md

@@ -25,8 +25,12 @@ Castle's job is configuration and release management on a running node.
   the system is running. `install_release/1`'s reply says only that the upgrade
   was accepted: a transition that restarts the emulator is replied to and then
   rebooted, and an emulator upgrade finishes on the way back up, where it can
-  still roll back. `bin/castle install` therefore polls this rather than
-  trusting the reply. Two conditions. The version is the running release: the
+  still roll back. So Castle answers the question and leaves the asking to
+  Forecastle: `bin/castle install` repeats it rather than trusting the reply,
+  from Forecastle 1.0.0 — the revision pinned in this project's `mix.lock`
+  installs with a single rpc and never calls this, so do not describe the
+  polling as something Castle's own integrated state does. Two conditions. The
+  version is the running release: the
   `current` one, or the `permanent` one when none is current — `install` leaves
   its target `current` and `commit` promotes it, so both count; `unpacked` (a
   rolled-back continuation) and `tmp_current` (written before the reboot) do
@@ -41,6 +45,18 @@ Castle's job is configuration and release management on a running node.
   that commits straight after installing would make a version that cannot boot
   the permanent one.
 
+  The marker is the whole of the evidence, so it inherits whatever the selected
+  boot script does with it. `RELEASE_BOOT_SCRIPT` naming a hand-written script
+  that never reaches `{progress, started}` will never be confirmed — `install`
+  waits and then fails, and the refusal names the progress the node did reach,
+  so it is diagnosable and never a false success — and one that emits the marker
+  before its applications start defeats the check. Both are documented rather
+  than validated: Mix generates the boot scripts and offers no `rel/` template
+  for them, so reaching either state takes deliberate work. (An earlier note
+  here claimed `systools_make:add_apply_upgrade/2`'s hard match on the trailing
+  marker ruled this out. It does not: that builds the hybrid script for an
+  emulator upgrade and says nothing about a script an operator supplies.)
+
 Every one of them is a command entry point, so `Castle` is the command
 boundary: an operation that fails raises `Castle.Error` there, which is what
 leaves a non-zero exit status behind for the shell that asked for it. Raising,

RELEASE.md

@@ -8,8 +8,14 @@
   accepted: a transition that restarts the emulator is replied to and *then*
   rebooted, and for an emulator upgrade the instructions run on the way back
   up, where they can still fail and roll back. Completion therefore has to be
-  observed, and `bin/castle install` polls this to observe it. Confirmation
-  needs two things: the version is the release the system is running - the one
+  observed rather than inferred, and this is what makes it observable: a caller
+  that repeats the question until it is answered - which is what Forecastle's
+  `bin/castle install` does, from its own 1.0.0 - can tell an upgrade that took
+  effect from one that did not. Castle supplies the answer; it does not do the
+  asking, and the Forecastle this release is built against does not yet ask.
+
+  Confirmation needs two things: the version is the release the system is
+  running - the one
   whose status is `current`, or the `permanent` one if none is current, so a
   version is confirmed both before and after `commit` - *and* its boot has
   finished. The second is not redundant. A node that restarted into the new
@@ -18,6 +24,16 @@
   from `kernel` onwards, so an application started after `sasl` can still fail
   and take the system back to the version that was permanent. Confirming
   earlier than that would let automation `commit` a release that cannot boot.
+
+  "Finished booting" means the boot script reached its `{progress, started}`
+  instruction, which is the last thing every boot script Mix generates does.
+  A release booted with a `RELEASE_BOOT_SCRIPT` that names a hand-written
+  script without that marker will therefore never be confirmed: `install` waits
+  and then fails, and the refusal names the progress the node did reach, so it
+  says what is wrong rather than failing silently - but it will not succeed. A
+  script that emits the marker before its applications are started defeats the
+  check instead, since the marker is all there is to go on.
+
   Nothing can build a relup that restarts the emulator until
   [forecastle#4](https://github.com/ausimian/forecastle/issues/4), so the
   restart transitions this addresses cannot be exercised end to end yet. The

lib/castle/commands.ex

@@ -199,6 +199,13 @@ defmodule Castle.Commands do
   # before that same marker (systools_make.erl:336). So a provided status of
   # `:started` means the script ran to the end: applications up, and any
   # continuation of the upgrade finished.
+  #
+  # The marker is the whole of the evidence, so this trusts whichever boot
+  # script was selected to emit it where it means what it says. One that never
+  # reaches it is never confirmed - `install` waits, then fails, and the message
+  # below names the progress the node did reach - and one that emits it early
+  # defeats the check. Mix generates these scripts; both states take an operator
+  # writing their own and pointing RELEASE_BOOT_SCRIPT at it.
   defp booted(vsn, init) do
     case init.get_status() do
       {_internal, :started} ->