docs(cli): document the two ipc messages and the parent-spawn pattern

Adds a `Waiting for the boot from a parent process` section to the `os dev`
page: what each message means, the spawn-with-ipc snippet, the asymmetry
(`os dev` consumes `objectstack:listening` and relays only the settle
message), and what `objectstack:seed-settled` promises — including why it is
sent on suppressed boots with a reason rather than withheld.

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

Author: claude

.changeset/17329-seed-settled-ipc-message.md

@@ -0,0 +1,17 @@
+---
+"@objectstack/cli": minor
+---
+
+`os serve` now announces **`objectstack:seed-settled`** on its existing ipc channel when this boot's seeding has come to rest, and `os dev` forwards it to its own parent process when one holds the channel. A script that spawns a dev server can finally wait for the boot to finish without reading the child's output.
+
+`✓ Server is ready` is true about the HTTP server and says nothing about the app. Seeding races a soft budget (`OS_INLINE_SEED_BUDGET_MS`, default 8s) and past it finishes in the background, so the banner can be a minute ahead of the seed's own result — measured downstream at **82 seconds of silence after the banner, then 120 `ERROR` lines**. The same command on the same corpus settles before the banner on a machine where the seed fits its budget, so the defect is invisible on exactly the boxes that would have caught it. Everything that distinguishes the two cases arrives on the child's inherited stdio, and reading that costs the boot its TTY.
+
+- **The producer is not new.** `@objectstack/runtime` already declares every seed source and settles it at the moment its boot-time write is done, publishing the tally under `@objectstack/spec`'s `seed-settlement` contract. This is the hop outward: the CLI subscribes to two hooks the kernel already fires and reads a snapshot it already publishes. No service is registered and no tally is mutated — the contract is read-only by design.
+- **Sent once, and never before `objectstack:listening`.** Seeding that settles during `runtime.start()` is latched and released after the bound port is published, so a parent that waits for the listening message and only then listens for the settle cannot miss it.
+- ⛔ **Keyed on `inFlight`, not `pending`.** Multi-tenant replay and `skipSeedData` register a seed source and deliberately never run it, keeping `pending` above zero for the life of the process. A `pending`-keyed message would never be sent on those boots, and its absence would be indistinguishable from a boot still writing — the same ambiguity this closes, one level up. Those boots get the message with `suppressed` reasons attached instead, so a consumer can say *why* no rows landed.
+- **Failure settles too.** A seed that failed has still come to rest; withholding there would recreate the hang. `ok` is a verdict on the per-source counts the boot recorded, and the message carries those counts.
+- **The over-budget banner no longer omits seeding.** `Seeds:` is fed by outcomes recorded when a load *finishes*, so past the budget the row was ABSENT and the transcript was byte-identical to an app that declares no seeds — which is how the defect hid. It now reads `pending — N sources still writing`, with a line saying seeding continues in the background; suppressed sources are named rather than reported as pending.
+
+⛔ An ipc channel is **not** made a requirement of either command: `process.send` is undefined under an ordinary terminal boot, both sends are no-ops there, and no byte of that transcript changes. Nothing in the existing `objectstack:listening` publication moves.
+
+Note that `os dev` consumes `objectstack:listening` itself (it is how the bound-port readout and the MCP connect hint learn the real port) and relays only `objectstack:seed-settled`. Spawn `os serve` directly to receive both in one place.

content/docs/deployment/cli.mdx

@@ -234,6 +234,67 @@ audit) lands there instead of the business DB (ADR-0057). Opt out with
 `OS_TELEMETRY_DB=0`, or point it elsewhere (any mode, including `serve`)
 with `OS_TELEMETRY_DB=<path>`.
 
+##### Waiting for the boot from a parent process
+
+`✓ Server is ready` is true about the **HTTP server**, and deliberately says
+nothing about the app's data. Seeding races a soft budget
+(`OS_INLINE_SEED_BUDGET_MS`, default `8000`); when it runs long the kernel
+starts anyway and the rest of the seed finishes **in the background** — so the
+banner, and anything that waits for it, can be a minute ahead of the seed's own
+result. On a machine where the seed fits its budget the same command settles
+before the banner. Both are normal, and which one you get depends on the box.
+
+So a script that spawns a dev server and wants to act **after the boot has come
+to rest** should not wait on the banner, and should not need to read the child's
+output at all. Spawn with an `ipc` channel and wait for a message:
+
+| Message | Sent by | Means |
+|---|---|---|
+| `objectstack:listening` | `os serve` | The HTTP server is bound. Carries `{ port, url }` — the port actually bound, which in dev may differ from the one requested. |
+| `objectstack:seed-settled` | `os serve` | Nothing is still seeding. Carries `{ ok, suppressed, sources }`. Sent once per boot, always **after** `objectstack:listening`. |
+
+```js
+import { spawn } from 'node:child_process';
+
+const child = spawn('os', ['dev'], { stdio: ['inherit', 'inherit', 'inherit', 'ipc'] });
+
+child.on('message', (msg) => {
+  if (msg?.type !== 'objectstack:seed-settled') return;
+  if (msg.suppressed.length > 0) {
+    console.log(`boot complete — seeds not run this boot (${msg.suppressed.join(', ')})`);
+  } else if (!msg.ok) {
+    console.log('boot complete — but some seed records did not land; see the log above');
+  } else {
+    console.log('boot complete — the app is ready to use');
+  }
+});
+```
+
+**`os dev` spawns `os serve`, and the two channels are not symmetric.** `os dev`
+consumes `objectstack:listening` itself — it is how the `↪ server bound to port`
+line and the MCP connect hint learn the real port — and does **not** relay it.
+It forwards `objectstack:seed-settled` to its own parent verbatim. Spawn
+`os serve` directly if you need both messages in one place.
+
+An `ipc` channel is optional: without one, both sends are no-ops and nothing
+about the command changes. There is no polling to do — if you did not open the
+channel, the messages simply are not sent.
+
+<Callout type="info" title="What `objectstack:seed-settled` promises, and what it does not">
+It is sent when **nothing is still writing** — on success *and* on failure, since
+a seed that failed has still come to rest. Read `ok` together with `sources`
+rather than alone: `ok` is a verdict on the per-source counts the boot recorded,
+and a source that finished by throwing may record no counts at all.
+
+`suppressed` is non-empty when this boot registered a seed source and
+deliberately never ran it — `multi-tenant-replay` (rows are written per
+organization on `sys_organization` insert) or `skip-seed-data` (a planning boot
+that writes nothing). Those sources never settle and no further signal is
+coming for them, which is exactly why the message is sent anyway with the reason
+attached: a consumer that waited for *every* source to finish would wait
+forever.
+</Callout>
+
 #### `os serve`
 
 Starts the ObjectStack server with automatic plugin discovery: