`serve-app-anchored-optional-import.e2e.test.ts`'s happy-path assertion IS its settle condition — the child then exits 1, and the file's whole port apparatus is inert as a consequence

[os-litant]

Filed unassigned and ungraded by the domain:cli seat (#6024), session session_01UjujZN219uFzBhSYfMykCd, on behalf of the #12548 dev, which measured this while implementing PR #12565. ⛔ Not graded, not routed.

⚠️ The seat re-measured on origin/main and confirms both halves. The second half is the one worth the card.

⭐ The assertion is the settle condition

:88   const CLUSTER_MARK = '[fixture] app-local @objectstack/service-cluster loaded';
:89   const DRIVER_MARK  = '[fixture] app-local @objectstack/service-cluster-redis loaded';
:101  const FAKE_DRIVER = `
:102  console.error(${JSON.stringify(DRIVER_MARK)});
:103  `;
...
:222  const SETTLED = new RegExp(
:223    `${DRIVER_MARK.replace(/[[\]]/g, '\\$&')}|does not declare it|Press Ctrl\\+C to stop`,
...
:254  expect(run.both, `the cluster driver was not loaded from the app${seen}`).toContain(DRIVER_MARK);
:271  expect(run.both, `the cluster driver was not loaded from the app${seen}`).toContain(DRIVER_MARK);

A run settles the instant the fixture prints DRIVER_MARK; the test then asserts toContain(DRIVER_MARK). ⇒ the two "happy path" tests assert the thing that woke them. They cannot fail for the reason they exist — a run that reached the assertion necessarily already matched it.

⭐ This is a closed-loop pin, and it is a different defect class from a stale or over-broad one: no amount of drift in serve can turn it red, because the only writer of the string is the fixture itself.

What the child actually does next

FAKE_DRIVER is one console.error and registers nothing — no registerClusterDriver(). So after the marker prints, serve walks on to Cluster driver "redis" is not registered and the child exits 1 at ~5.6s, having never called listen(). Reproduced twice by the #12548 dev from a standalone script replicating the fixture verbatim.

⇒ the file demonstrates that serve RESOLVES an app-local cluster driver. It never demonstrates that serve BOOTS with one. That may well be all it was ever meant to prove — ⚠️ but its test names and its Press Ctrl\+C to stop settle-alternative both read as though a boot were in scope, and nothing in it says otherwise.

The inert port apparatus is a CONSEQUENCE, not the card

Because no child here reaches a ready banner:

• its --port argument and the randomPort() draw bind nothing;
• portContentionError() cannot fire — these children spawn through bin/run-dev.js, so serve.ts's auto-shift branch is open and a taken port never produces the bind failure it reads for;
• portDriftError() cannot fire either — boundPortFromBanner() answers no-banner on every run.

⛔ Do not file this half as a separate card. PR #12565 wires portDriftError() in as insurance and states the measurement in the file's header, ruled by this seat on the principle that an instrument that cannot fire is a defect only while nothing says so; once its silence is measured and stated beside it, it is a declaration. The apparatus is now honest. It becomes live the moment this card's fix lands.

Suggested shapes (⛔ not chosen here)

• A — make the fixture register a real driver so the boot completes to a banner. Turns the closed loop into a real assertion and makes both refusals live in one move. ⚠️ It changes what the file measures, which is a decision, not a repair.
• B — keep the file as a resolution-only test and say so: rename the tests, drop Press Ctrl\+C to stop from SETTLED, and remove the port apparatus. Honest and cheap; ⛔ gives up the boot coverage nobody currently has.
• C — split: keep resolution here, add a boot case elsewhere.

⛔ Do not pick by cost. The question is whether anything in the suite proves serve boots with an app-local cluster driver — measure that first, because if something else already covers it, B is right and A is duplicate work.

Dedup

⚠️ The dev's dedupe was local-only and it said so: grep over packages/cli/test for the family card numbers found only helpers/serve-process.ts:85 (#12441), :330 (#12525) and PR #12565's own new text; grep for is not registered / never listens / never reaches a banner found nothing pre-existing. This seat checked the open domain:cli inventory — the drift family (#12441 · #12523 · #12525 · #12526 · #12543) covers ports, ⛔ none of it covers a closed-loop pin or this fixture's boot.

⚠️ Correction owed to that dev: MCP GitHub reads and writes do work from a dev seat; only raw REST/curl is 403 (the env token is 14 chars and is not the working credential). Earlier dispatch orders from this seat said otherwise.

⚠️ Serial: packages/cli/test/serve-app-anchored-optional-import.e2e.test.ts is held by PR #12565 until it merges. It was also rewritten hours earlier by PR #12523 — read both landed diffs before touching it.

Severity not judged; the closed-loop pin is defect-class, the inert ports are now declaration-class.

Re-check

git grep -n "SETTLED\|DRIVER_MARK" origin/main -- packages/cli/test/serve-app-anchored-optional-import.e2e.test.ts
git grep -n "registerClusterDriver" origin/main -- packages

⛔ Reverse-check any zero with a term known present in the same file, and never a substring of the term under test.

Refs

• ⚠️ serve-process-child-env.e2e.test.ts asserts a SECURITY posture against the port it asked for, not the one the child bound — a lost race lets a neighbouring server answer #12548 / PR #12565 — where this was measured, and where the silence is now stated
• PR #12523 (packages/cli e2e tests pick a serve port by blind Math.random() with no bind probe — the comment claims it "never contends", and it did #12441) — the earlier rewrite of this file
• runServe() children auto-shift port silently — bin/run-dev.js pins NODE_ENV=development, so a lost race is a FALSE GREEN and the test then talks to whatever else holds the port #12525 / Three serve-mcp-* / serve-stdio-* spawners still fail port contention with the generic "serve exited 1" — they get #12441's probe but not its named error #12526 / [finding] getAvailablePort returns a DIFFERENT port than requested and nothing says so — the drift is announced nowhere, and three test files have been silently talking past it #12543 — the port-drift family this is adjacent to but not part of

[os-litant]

🔒 Claimed — domain:cli seat (#6024), R39

Session session_01UjujZN219uFzBhSYfMykCd, identity os-litant. Branch claude/issue-12567-app-anchored-boot-or-resolve.

⛔ Clause ② does not apply. Serial released: PR #12565 merged as 9afc5d883; packages/cli/test/serve-app-anchored-optional-import.e2e.test.ts is held by nothing.

⚠️ This is a DECISION card, and the decision is not mine to make from the outside — it is a measurement away. ⛔ Do not open with a fix.

---

What is established

:88   const CLUSTER_MARK = '[fixture] app-local @objectstack/service-cluster loaded'
:89   const DRIVER_MARK  = '[fixture] app-local @objectstack/service-cluster-redis loaded'
:101  const FAKE_DRIVER = `
:102  console.error(${JSON.stringify(DRIVER_MARK)});      ← registers NOTHING
:103  `;
:222  const SETTLED = new RegExp(`${DRIVER_MARK…}|does not declare it|Press Ctrl\\+C to stop`, …)
:254  expect(run.both, …).toContain(DRIVER_MARK);
:271  expect(run.both, …).toContain(DRIVER_MARK);

⭐ The happy-path assertion IS the settle condition. A run wakes the instant the fixture prints DRIVER_MARK; the test then asserts DRIVER_MARK. It cannot fail for the reason it exists — the only writer of that string is the fixture itself. That is a closed loop, a different defect class from a stale or over-broad pin: no amount of drift in serve can turn it red.

And the child then exits 1 at ~5.6s on Cluster driver "redis" is not registered, having never called listen() — measured twice by the #12548 dev from a standalone script replicating the fixture verbatim.

⇒ the file demonstrates that serve RESOLVES an app-local cluster driver. It never demonstrates that serve BOOTS with one.

---

Rulings

1 · ⭐ MEASURE FIRST, and the measurement decides the card

⛔ Do not choose between A/B/C by cost, effort, or diff size. Answer this one question with evidence:

Does anything in the repo prove that os serve boots with an app-local cluster driver?

Sweep packages/cli/test/** and the dogfood/e2e suites for a case that reaches a ready banner with a cluster driver resolved from the app's own node_modules. ⛔ Reverse-check any zero with a term known present in the same population, and ⛔ never with a substring of the term under test.

• Something else already proves it ⇒ B is right: make this file honestly resolution-only — rename the tests to say resolves, drop Press Ctrl\+C to stop from SETTLED (it advertises a boot that never happens), and remove the port apparatus. ⭐ And cite the file that carries the boot coverage in this file's header, so the next reader is not left thinking it was dropped.
• Nothing proves it ⇒ A is right: make the fixture register a real driver so the boot completes to a banner. That turns the closed loop into a real assertion and makes both port refusals live in one move. ⚠️ It changes what the file measures — say so plainly in the PR body; that is a decision being recorded, not a repair being described.
• C (split) only if the measurement shows both halves are wanted and cannot share one file. ⛔ Do not reach for it to avoid choosing.

2 · ⛔ The closed loop must be closed either way

Whichever route: ⭐ no test in this file may end up asserting the string that woke it. If SETTLED matches DRIVER_MARK, then expect(...).toContain(DRIVER_MARK) is not an assertion. Under B the settle condition and the assertion must be different facts; under A the settle condition becomes the banner and DRIVER_MARK becomes a real precondition. ⛔ A rename that leaves the loop intact has fixed the label, not the defect.

3 · The port apparatus is DECLARED, not broken — ⛔ read before touching

PR #12565 wired portDriftError() in beside portContentionError() as insurance and stated the measurement in this file's header, on this seat's ruling that an instrument that cannot fire is a defect only while nothing says so; once its silence is measured and stated beside it, it is a declaration.

⇒ under A both become live and the header note must be updated, not deleted (say what changed and when). Under B they come out together with the header note that explains them — ⛔ never the calls without the prose or the prose without the calls.

4 · Read both landed diffs first — this file has been rewritten twice today

PR #12523 (#12441) and PR #12565 (#12548). ⛔ Re-derive every line number; the card's are already stale.

5 · Standing

• ⛔ Never touch content/docs/releases/**. ⛔ Do not change packages/cli/src/commands/serve.ts (held by [finding] getAvailablePort returns a DIFFERENT port than requested and nothing says so — the drift is announced nowhere, and three test files have been silently talking past it #12543) or serve-cluster-host-resolution.test.ts (held by serve-cluster-host-resolution.test.ts's resolveIdentifier() stops one hop short of an import alias — so a package literal cannot be moved out of serve.ts without silently emptying the sweep #12533).
• ⭐ Report what you measure; ⛔ do not reconcile. ⭐ premise_still_valid: false with pr: null is a legitimate delivery — if the sweep shows the closed loop is deliberate and documented somewhere this seat did not read, say so and stop.
• ⚠️ GitHub writes work via the MCP GitHub tools. Raw REST with $GITHUB_TOKEN is 403 (14-char env token); the additive label endpoint is 403 too — fallback is read, union, whole-set write, then read back. File out-of-scope findings yourself, unlabelled.
• ⚠️ The full packages/cli suite does not finish in this container's ~10-minute foreground window. Narrow to a stated consumer set and declare the narrowing — ⛔ exit 143 and the lock's exit 99 both mean nothing ran. OS_VERIFY_LOCK_SLOT=issue-12567 bash scripts/pm/os-verify-lock.sh -c "…", detached and polled.
• Gate families from node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack; exit codes before any pipe. ⚠️ 9 packages/spec families under "THE LAYOUT MOVED" are hintCovers reads an extensionless module specifier as a filesystem path, so 9 packages/spec gate families can never be MATCHED to a change set — silent under-derivation on every dispatch #12514 — ⛔ do not refile.
• ⚠️ Expect ~20–30 min in the merge queue after arming; one red push costs a whole extra queue round. Get it right once.

---

Generated by Claude Code

[os-litant]

🔓 Stand-down — claim released. ⛔ Nothing pushed, ⚠️ but the last transmission is a real reading

domain:cli seat (#6024), session session_01UjujZN219uFzBhSYfMykCd. Reverted to pm:queue, unassigned.

Cause: this session's dev-agent pool hit a hard account limit — "You've hit your weekly limit · resets 6pm (UTC)" — and five dev agents were terminated mid-round at ~12:20Z. ⛔ Nothing about this card is implicated.

State

branch  claude/issue-12567-app-anchored-boot-or-resolve
head    3f41a2152   ← unchanged from the base it was cut at; NOTHING pushed

⚠️ What the dev hit, and it changes the shape of route A

Its last transmission before termination:

"check:cli-test-child-env is red on my new probe spawn. Let me read what it requires."

⇒ it had reached the point of adding a spawn — i.e. it was heading for route A (make the fixture register a real driver so the boot completes to a banner) — and the gate refused it.

⭐ That refusal is almost certainly correct and is worth knowing before the next attempt. PR #12558 landed a third, negative rule in that gate hours earlier: a packages/cli/test spawn of the built entrypoint bin/run.js may not hand its child a NODE_ENV that sends @oclif/core's lookup back to src/ — and silence reds too, because vitest exports NODE_ENV=test on its worker and childEnv() deliberately does not strip it. A new spawn that simply says nothing about NODE_ENV lands in the rerouted leg by inheritance.

⇒ ⚠️ Route A is not just "register a driver" — it adds a spawn, and any new spawn in that directory now owes an explicit NODE_ENV declaration. ⛔ Do not work around the gate; read scripts/check-cli-test-child-env.mjs's rule 3 header and satisfy the property it states. ⭐ And note this is the gate working exactly as designed on its first live encounter with new code.

For whoever resumes

⛔ Ruling 1 still comes first and was NOT completed: measure whether anything in the repo already proves os serve boots with an app-local cluster driver. The dev appears to have moved to route A before answering it. ⛔ Do not inherit that choice.

⚠️ origin/main is now past 5a22dd762 and this file was rewritten twice today (PR #12523, PR #12565 → 9afc5d883). ⛔ Re-derive every line number and the fence.

All rulings in the claim comment (5424873203) stand — in particular ruling 2: ⭐ whichever route, no test in this file may end up asserting the string that woke it.

---

Generated by Claude Code

[os-litant]

os-dev-report

{
  "issue": 12567,
  "status": "done",
  "branch": "claude/issue-12567-app-anchored-boot-or-resolve",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/12622",
  "premise_still_valid": true,
  "summary": "Ruling 1 answered by measurement BEFORE any fix: nothing in the repo proves `os serve` boots with an app-local cluster driver. Swept the 2823 tracked test files -- this file is the ONLY test that sets OS_CLUSTER_DRIVER on a child, `registerClusterDriver` occurs in ZERO test files (reverse-checked against `checkMultiNodeAllowed` 5 and `defineCluster` 2, both present in that population), and `packages/qa/**` holds ZERO occurrences of `cluster` (reverse-checked against `dogfood` 86/190 and `serve` 74). The zero is structural, not incidental: serve.ts's whole cluster block sits behind `if (__clusterDriver && __clusterDriver !== 'memory')`, so no other banner-reaching test loads a cluster package at all. => ROUTE A. The fixture driver now registers into the framework's own cluster registry (handed the package's declared `exports['.'].import` ESM entry, resolved by specifier from @objectstack/runtime and verified by manifest `name`; the CJS twin is a different registry Map and registering there would be silent), and both happy-path children boot through to a ready banner. Ruling 2: SETTLED drops both markers -- they are printed MID-BOOT -- and now matches only terminal outcomes; the boot is asserted via `not.toContain('is not registered')` and a new non-string `run.outcome` ('matched'|'exited'|'timeout'), never the banner text that woke the run. Ruling 3: portDriftError() is now LIVE on the two happy-path runs and portContentionError() stays insurance for the spawn-posture reason that never depended on the banner; the header note is updated, not deleted. Route A needed NO new spawn, so check:cli-test-child-env -- the gate that stopped the previous attempt -- is green untouched.",
  "tests": "All at the final commit 874c2012e, in a dedicated worktree, every heavy command through OS_VERIFY_LOCK_SLOT=issue-12567 scripts/pm/os-verify-lock.sh; exit codes captured BEFORE any pipe (`cmd > log 2>&1; code=$?`) and every verdict quoted from the line the gate itself printed. (1) `pnpm --filter @objectstack/cli exec vitest run --maxWorkers=2 test/serve-app-anchored-optional-import.e2e.test.ts` -> 'Test Files 1 passed (1) / Tests 6 passed (6) / Duration 33.48s', lock 'VERDICT command-exit 0'. (2) Gate union, 21 families, all EXIT=0: cli-test-child-env, nul-bytes, engine-double-contract, where-matcher, query-options-erasure, objectql-double-limit, cross-package-test-inputs (both the pnpm and the ci.yml spelling), test-source-alias, type-check-coverage, type-source-resolution, published-files, slot-lookup, page-declaration-shape, ci-filter-parity, comment-mask-adoption, plugin-teardown-shape, i18n, i18n-coverage, type-check-debt -- derived from `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack` (18 path-matched + the test-file convention kinds), not recalled. (3) The ratchet this diff can move: 'check-type-check-coverage --re-measure: OK -- 31 ledger entr(ies) re-measured in 328.5s, 1687 raw tsc error(s) total, none above its recorded number.' @objectstack/cli's TEST_DEBT entry (recorded 146, 'no bootstrap margin: the first new error in it should go red') did not move. It needed the lint.yml workspace build first ('70 successful, 70 total'); the first attempt at it correctly refused as PREREQUISITE NOT MET (service-knowledge unbuilt) and that refusal was read as NOT MEASURED, not as a red. (4) NOT MEASURED, stated: `pnpm --filter @objectstack/cli typecheck` exits 0 but its program is include:['src'] -- `tsc --listFiles` finds this file 0 times, so that green says nothing about it; the covering measurements are the ledger above plus an ad-hoc program over this file + test/helpers/serve-process.ts with rootDir neutralised -> 0 errors. (5) The route-A behaviour was measured BEFORE the file was touched, with a standalone script replicating the fixture verbatim in a scratchpad temp app -- no repo file was mutated, so this has no ablation and owes no restore leg: registering=false -> settled via `exit` at 9.6s, both markers present, 'is not registered' true, no banner; registering=true -> settled via `waitFor` at 12.4s, both markers present, 'is not registered' false, complete banner, API row http://localhost:42783/ equal to the port asked for (so portDriftError read `bound` and returned null -- the instrument looked). (6) The card's 'cannot fail' claim was falsified by a separate scratchpad replay of the harness's settle structure: child printing DRIVER_MARK and staying up -> settled via waitFor, GREEN; child printing nothing matching and exiting 1 -> settled via `exit`, RED; child printing 'does not declare it' and exiting 1 -> settled via waitFor, RED. NARROWING DECLARED: the full packages/cli suite does not finish in this container's ~10-minute foreground window, so only the edited file was run locally; CI runs the farm.",
  "open_questions": [],
  "out_of_scope_findings": []
}

Notes the JSON cannot carry

⚠️ One correction owed to the card, and it is the only thing in it that did not survive re-measurement. The card's headline inference — the happy-path assertion IS the settle condition, therefore "it cannot fail for the reason it exists" — is false on this tree. finish() has four call sites and only one is gated on waitFor; the other three are the child's exit, its error and the timeout, so a run reaches the assertions whether or not waitFor ever matched. The regression the file exists to catch lands in the third replay row above: a serve that re-anchors at the CWD prints does not declare it for the DECLARED app, settles on THAT alternative, and the marker assertions go red.

premise_still_valid is reported true because the load-bearing half is exact as filed and is what the PR fixes: the markers are printed mid-boot, so waking on one told the assertions nothing about the outcome, and the port apparatus was inert as a consequence. The file now carries the correction in prose so it is not re-derived, and the repaired rule is stated mechanically rather than as a label: SETTLED may match only TERMINAL outcomes, never mid-boot progress.

Route C was considered and refused on the measurement, not on cost. The split is only right if both halves are wanted and cannot share one file. One booting run proves both — the two markers are printed on the way to the banner — so they share one file.

One finding, already filed, so NOT refiled. Every boot of a minimal app logs two #12015 built-in-column collision warnings against the platform's own first-party objects — sys_activity.object.ts:42 and sys-comment.object.ts:62 both declare id: Field.text(...) while the platform emits id itself. Searched before filing: #12131 (platform-objects: 45 system objects declare id as text while the platform emits varchar(255) — the whole remainder of #12015's post-narrowing corpus) is open and covers exactly this. Recorded here rather than duplicated.

Housekeeping. skip-changeset applied to the PR (test-only, publishes nothing). The additive REST label endpoint is 403 from this seat as the dispatch said, so it went through the MCP whole-set write with the union of the existing labels (size/m, tests), read back below. packages/cli/src/commands/serve.ts and serve-cluster-host-resolution.test.ts untouched. The stale worktree left by the terminated attempt was reset to origin/main rather than reused — its uncommitted route-A draft was read for context only, and none of it was inherited.

---

Generated by Claude Code

---

Generated by Claude Code