feat(bin): add fleet admission control stages 0 and 1

[sbracewell64]

Intent

Implement fleet admission control Stages 0 and 1 exactly as designed by an accepted, captain-authorized scout study. The design was reviewed and approved before this work started; the task was explicitly to implement it as written, not to redesign it, so departures from the study are out of scope rather than improvements.

Admission control is a third layer above routing (who is capable) and scheduling (when accepted work runs): it decides whether the fleet should accept another task at all right now. Its defining constraint, and the reason the layer exists separately at all, is task independence - it reads ONLY fleet-snapshot properties and never the incoming task, so the same snapshot returns the same band for every task. bin/fm-admission.sh therefore refuses a task argument on purpose; that refusal is the invariant made structural, not missing argument handling.

DELIBERATE NON-ENFORCEMENT, the single most likely thing to look like an omission. The study found no measured evidence that any numeric signal predicts fleet coordination failure: eleven active workers ran on a lightly loaded host, and coordinator attention cost is not collectable until a wake-outcome ledger lands. Shipping a cap would manufacture policy from one point sample, and the repo already has a standing contract that isolated work dispatches immediately with NO concurrency cap. So every numeric threshold ships null with enforce:false, and enforcement_mode accepts exactly one value ('safety-only') which forbids enforce:true on any signal. Numeric enforcement is structurally unreachable until Stage 2 adds a mode value and the comparison path together as one reviewed change. Only deterministic safety conditions - admission authority, census integrity, snapshot freshness - can set a band. Threshold-comparison code being absent is the requirement, not an unfinished feature.

INERT BY DEFAULT. A home with no _scheduling.admission_control policy, or one carrying only underscore-prefixed operator notes, sees zero behavior change and pays one cheap config read. All three consuming seams (bootstrap, teardown, session start) are gated on an active policy. The live captain config today holds only a note, so this lands as a no-op for the fleet.

SIGNAL-SPECIFIC VALIDITY. The study observed a real production case where the broad snapshot validity bit was false (a historical backlog row had no child metadata) while task metadata gave a perfectly coherent eleven-worker census. Collapsing those into one aggregate health bit would close the fleet for an unrelated bookkeeping error. So backlog_consistency is its own signal, separate from census_integrity, reported and repairable but never contributing a capacity band. It is a seventh signal not present in the study's section 4 schema block, added because the study's own section 1.3 and 9.3 findings mandate the separation; the brief listed it as in scope.

NO NEW MACHINERY. The existing per-home session lock is the single-primary admission authority - no new process, daemon, reservation store, or second queue. Deferred and refused requests stay in the owning backlog under a 'load' hold, and capacity is re-examined at exactly two seams that already exist: successful cleanup and session start. The known already-empty-fleet gap (a fleet that empties while a request is held waits until session start) is deliberately left named and instrumented rather than cured with a timer; that restraint is the study's explicit recommendation.

DORMANT, NOT MISSING. Reservations, a distributed registry, remote nodes, host-resource metrics, and an admission daemon are all deliberately unimplemented. The schema validates their config placeholders and REFUSES to let them be enabled, so the distributed contract is settled in advance as validated policy rather than running code, and activating it later cannot change admission semantics. A task-weighted admission score, provider quota inside the admission band, and an admission daemon are permanently rejected designs.

LEDGER SEAM ONLY. The wake-outcome ledger is being built in parallel and exposes no extension seam yet (verified: nothing in tracked material). The decision record from --json is the named unit of admission telemetry, but nothing is persisted and no competing evidence store is opened - integration is explicitly the ledger's Phase 2, not this task's.

OTHER DELIBERATE CHOICES a reviewer may question: exit status encodes the band (0 preferred, 3 soft, 4 hard, 2 malformed policy) so a caller that ignores stdout still stops safely. Unknown config fields are REFUSED rather than ignored, because the study's central complaint was that bootstrap silently ignored unknown scheduling keys; a typo must not silently disable a safety condition. unknown_band accepts only soft or hard because the study's invariant says missing evidence must never resolve to 'probably fine'. Signals with no collector are recorded as unmeasured rather than assumed zero, and admission wait age stays explicitly uncollected because backlog age is task age, not load-wait age.

This repo is firstmate's own shared tracked material, so knowledge was routed by its documented placement rules: AGENTS.md got only a three-line intake stub plus a skill trigger (its token cost is paid by every session of every fleet member), the per-band procedure went to a new agent-only skill, the schema to docs/configuration.md as its single owner, and rationale to docs/architecture.md. Captain-private config values were deliberately kept out of tracked material - only the schema, its validation, and an all-null example ship.

tests/fm-gotmp.test.sh gains two lines because teardown now sources a new lib and that suite's fake root must mirror teardown's real dependency set, exactly as its other sourced libs are already linked. That is a required fixture completeness fix, not unrelated scope.

Verified before submitting: shellcheck lint clean, doc-audience check clean, 14 new behavior cases green, and the pr-forge, session-bootstrap, pure-contract-unit and backend-dispatch families run. Three failures remain that this change did not cause - fm-session-start, fm-calm-pi-extension (node ESM), and fm-backend-tmux-smoke - each confirmed to fail identically on a stashed baseline and environmental to this machine.

What Changed

• Add bin/fm-admission.sh and bin/fm-admission-lib.sh: a task-independent admission layer that reads only fleet-snapshot properties and resolves a preferred/soft/hard band (exit codes 0/3/4, with 2 for malformed policy). All numeric thresholds ship null under a safety-only enforcement mode that structurally refuses enforce:true; only deterministic safety conditions (admission authority, census integrity, snapshot freshness) can set a band, unknown config keys are refused rather than ignored, and a --json decision record serves as the telemetry unit. Per review feedback, an unmeasurable snapshot age now fails closed to the configured unknown_band instead of resolving preferred, and band/trigger validation was tightened (bands.preferred refuses hold_kind/auto_reconsider; queue.release_triggers is pinned to exactly its two seams).
• Wire the three consuming seams — bin/fm-bootstrap.sh, bin/fm-teardown.sh, and bin/fm-session-start.sh — all gated on an active _scheduling.admission_control policy, so a home with no policy (or only underscore-prefixed operator notes) sees zero behavior change.
• Add the policy schema to docs/configuration.md, rationale to docs/architecture.md, a per-band fleet-admission agent skill plus a three-line AGENTS.md intake stub, an all-null example in docs/examples/crew-dispatch.json, and tests/fm-admission.test.sh with 15 behavior cases (all green in the pipeline, alongside the bootstrap and gotmp regression suites).

Risk Assessment

✅ Low: The feature remains additive and inert-by-default, all four review fixes were applied exactly as instructed and verified empirically against the shipped example and live script, and the fix diff introduces no new behavior beyond tightening validation and failing closed on unmeasurable freshness evidence.

Testing

Ran the new fm-admission behavior suite plus the gotmp and bootstrap suites that cover the consuming seams (all pass), then manually drove bin/fm-admission.sh through 11 end-user scenarios in a fixture home covering every intent constraint — inertness, task independence, band exit codes, authority, staleness fail-closed, signal separation, and safety-only schema refusals — captured as a CLI transcript; no visual evidence applies since the surface is a CLI.

Evidence: fm-admission.sh end-to-end CLI transcript (11 scenarios)

===== 1. no admission policy configured (inert by default) =====
$ /home/shane/.no-mistakes/worktrees/5f306883d81c/01KYQW2H0KH7GVAEH92SVKKWSJ/bin/fm-admission.sh
admission: not configured (absent) - dispatch is unchanged
[exit 0]

===== 2. note-only policy (still inert) =====
$ /home/shane/.no-mistakes/worktrees/5f306883d81c/01KYQW2H0KH7GVAEH92SVKKWSJ/bin/fm-admission.sh
admission: not configured (inert) - dispatch is unchanged
[exit 0]

===== 3. active policy, authority held, fresh census -> human explanation =====
$ owned /home/shane/.no-mistakes/worktrees/5f306883d81c/01KYQW2H0KH7GVAEH92SVKKWSJ/bin/fm-admission.sh --snapshot /tmp/fm-admission-demo/snapshot.json
admission: preferred -> admit   fleet=test-fleet authority=test-authority config=sha256:c9df407eb7ec21ca
snapshot: sha256:c6097f35fb2d2cc6 generated=2026-07-29T00:00:00Z age=0s  mode=safety-only combine=most_restrictive

  authority.single_primary: observed=held state  source=per-home-session-lock/age=0s valid=true  /_scheduling/admission_control/authority/unreachable_band authority-held hard  -> preferred
  census_integrity.inventory: observed=true boolean  source=fresh-authority-census/age=0s valid=true  /_scheduling/admission_control/signals/census_integrity/unknown_band readable hard  -> preferred
  census_integrity.duplicate_identities: observed=0 count  source=fresh-authority-census/age=0s valid=true  /_scheduling/admission_control/signals/census_integrity/unknown_band ==0 hard  -> preferred
  census_integrity.snapshot_age: observed=0 seconds  source=fresh-authority-census/age=0s valid=true  /_scheduling/admission_control/signals/census_integrity/max_snapshot_age_seconds > null  -> preferred
  backlog_consistency.main_inventory: observed=false boolean  source=main-inventory/age=0s valid=true  /_scheduling/admission_control/signals/backlog_consistency/enforce observe false  -> preferred
  admission_queue_pressure.load_hold_depth: observed=2 count  source=tasks-axi-load-holds-plus-ledger/age=0s valid=true  /_scheduling/admission_control/signals/admission_queue_pressure/enforce observe false  -> preferred
  admission_queue_pressure.oldest_wait: observed=null seconds  source=tasks-axi-load-holds-plus-ledger/age=unknown valid=false  /_scheduling/admission_control/signals/admission_queue_pressure/oldest_wait_soft_seconds observe null  -> preferred
  active_workers.count: observed=3 count  source=fresh-authority-census/age=0s valid=true  /_scheduling/admission_control/signals/active_workers/enforce observe false  -> preferred
  coordination_debt.unavailable: observed=null  source=wake-outcome-ledger/age=unknown valid=false  /_scheduling/admission_control/signals/coordination_debt/enabled observe false  -> preferred
  host_resources.unavailable: observed=null  source=node-summaries/age=unknown valid=false  /_scheduling/admission_control/signals/host_resources/enabled observe false  -> preferred
  reservation_pressure.unavailable: observed=null  source=admission-registry/age=unknown valid=false  /_scheduling/admission_control/signals/reservation_pressure/enabled observe false  -> preferred

notification: silent
[exit 0]

===== 4. --json decision record (key fields) =====
$ fm-admission.sh --json --snapshot snapshot.json | jq ...
{
  "schema": "fm-admission.v1",
  "decision_band": "preferred",
  "action": "admit",
  "task_id": null,
  "task_independent": true,
  "enforcement_mode": "safety-only",
  "authority_held": true,
  "active_worker_count": 3,
  "load_queue_depth": 2,
  "backlog_rule": {
    "observed": false,
    "detail": "in-flight backlog item has no child metadata",
    "result": "preferred"
  },
  "telemetry": {
    "sink": "wake-outcome-ledger",
    "integrated": false,
    "reason": "wake-outcome ledger extension seam is not available yet; this record is the unit to append when it lands"
  }
}
[exit 0]

===== 5. --brief summary line =====
$ owned /home/shane/.no-mistakes/worktrees/5f306883d81c/01KYQW2H0KH7GVAEH92SVKKWSJ/bin/fm-admission.sh --brief --snapshot /tmp/fm-admission-demo/snapshot.json
admission: preferred (admit; 3 worker(s), 2 load-held; authority held; config sha256:c9df407eb7ec21ca)
[exit 0]

===== 6. caller does not hold the session lock -> hard refuse =====
$ /home/shane/.no-mistakes/worktrees/5f306883d81c/01KYQW2H0KH7GVAEH92SVKKWSJ/bin/fm-admission.sh --brief --snapshot /tmp/fm-admission-demo/snapshot.json
admission: hard (refuse; 3 worker(s), 2 load-held; authority not held; config sha256:c9df407eb7ec21ca)
  controlling: authority.single_primary
[exit 4]

===== 7. snapshot older than configured freshness limit -> soft defer =====
$ owned /home/shane/.no-mistakes/worktrees/5f306883d81c/01KYQW2H0KH7GVAEH92SVKKWSJ/bin/fm-admission.sh --brief --snapshot /tmp/fm-admission-demo/snapshot.json
admission: soft (queue; 3 worker(s), 2 load-held; authority held; config sha256:8349afbcb9d99c80)
  controlling: census_integrity.snapshot_age
[exit 3]

===== 8. task argument refused (task independence is structural) =====
$ owned /home/shane/.no-mistakes/worktrees/5f306883d81c/01KYQW2H0KH7GVAEH92SVKKWSJ/bin/fm-admission.sh my-task-123
error: fm-admission.sh takes no task argument: admission inspects fleet state only, never the incoming task
[exit 2]

===== 9. numeric enforcement (enforce:true) refused under safety-only mode =====
$ /home/shane/.no-mistakes/worktrees/5f306883d81c/01KYQW2H0KH7GVAEH92SVKKWSJ/bin/fm-admission.sh validate
admission policy invalid: config/crew-dispatch.json - enforcement_mode safety-only forbids enforce on active_workers; numeric enforcement is evidence-gated and not implemented yet
[exit 2]

===== 10. typo'd config key refused rather than silently ignored =====
$ /home/shane/.no-mistakes/worktrees/5f306883d81c/01KYQW2H0KH7GVAEH92SVKKWSJ/bin/fm-admission.sh validate
admission policy invalid: config/crew-dispatch.json - unknown signals.census_integrity field: max_snapshot_age_secnods
[exit 2]

===== 11. unknown_band=preferred refused =====
$ /home/shane/.no-mistakes/worktrees/5f306883d81c/01KYQW2H0KH7GVAEH92SVKKWSJ/bin/fm-admission.sh validate
admission policy invalid: config/crew-dispatch.json - unknown_band must be soft or hard
[exit 2]

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

⚠️ **Review** - 1 info

• ⚠️ bin/fm-admission.sh:262 - Unmeasurable snapshot age bypasses a configured freshness limit. $stale (bin/fm-admission.sh:198) requires $snapshot_age != null, so a readable snapshot whose generated field is missing or unparseable (reachable via the public --snapshot flag, or on a host where both date -j -f and date -d parsing fail) yields age null and the census_integrity.snapshot_age rule resolves preferred even when max_snapshot_age_seconds is configured (verified empirically: rule records valid:false, configured_value:10, result:"preferred"). Snapshot freshness is one of the three deterministic safety conditions the intent says may set a band, and the intent states "missing evidence must never resolve to 'probably fine'"; a null age with a configured non-null limit should arguably map to the census unknown_band instead of preferred. No shipped default is affected (the limit ships null), but once an operator configures a limit, this silently disables the freshness safety condition on exactly the inputs where it matters.
• ℹ️ bin/fm-admission-lib.sh:108 - Validation accepts an arbitrary hold_kind (and auto_reconsider) on the preferred band: the hold_kind must be "load" check is skipped for preferred while hold_kind remains an allowed key, so bands.preferred.hold_kind: "captain" validates (verified against the shipped example). Runtime impact is nil since preferred admits, but the change's own rationale is that misleading configuration must be refused rather than accepted; tightening band_error to refuse hold_kind/auto_reconsider on preferred (or require hold_kind absent there) closes the gap.
• ℹ️ bin/fm-admission-lib.sh:217 - queue.release_triggers is validated as a configurable non-empty subset of ["teardown","session-start"] but no consuming seam reads it: bin/fm-teardown.sh's admission_release_reminder and bin/fm-session-start.sh's Fleet admission subsection both fire unconditionally for any active policy, and the value is only echoed into the decision record. An operator who configures ["session-start"] only still gets the teardown reminder. Either pin validation to exactly the two triggers (matching docs/configuration.md's "pins ... the two release triggers" wording) or honor the configured subset at the seams.
• ℹ️ docs/architecture.md:160 - docs/architecture.md describes combining signals "into a preferred, soft, hard, or unknown band", but no unknown band exists anywhere in the implementation: severity_order is exactly ["preferred","soft","hard"], unknown evidence maps to soft/hard via unknown_band, and the exit-code contract has no fourth band. The doc sentence contradicts the schema it points to.
• ℹ️ bin/fm-admission-lib.sh:310 - Missing-jq semantics are asymmetric: fm_admission_state reports absent when jq is missing (bin/fm-admission-lib.sh:310-313), so an ACTIVE policy's session-start and teardown seams silently skip, while fm-admission.sh fails closed with exit 2 and the message "admission policy invalid ... jq is required" even for a dispatch-only crew-dispatch.json that carries no admission block at all. Both directions are defensible - a policy's presence cannot be determined without a JSON parser, and bootstrap's existing MISSING: jq diagnostic surfaces the root cause - so this is a noted tradeoff, not a requested change.

🔧 Fix: fail closed on unmeasurable snapshot age; tighten band and trigger validation
1 info still open:

• ℹ️ bin/fm-admission.sh:263 - All four accepted round-1 findings are correctly fixed in fad40be and verified empirically: the freshness rule fails closed to the configured unknown_band when max_snapshot_age_seconds is set and the snapshot age is unmeasurable (valid:false preserved, controlling rule named, both directions plus the configured-band variant pinned by the new test); queue.release_triggers is validated as exactly ["teardown","session-start"] with the seams left unconditional and the doc updated; bands.preferred refuses hold_kind and auto_reconsider while still allowing underscore operator notes, with the shipped example still validating; and docs/architecture.md now describes the three-band set with unknown evidence mapping through unknown_band. No new defects introduced by the fix diff.

✅ **Test** - passed

✅ No issues found.

• bin/fm-test-run.sh tests/fm-admission.test.sh tests/fm-gotmp.test.sh — 15 admission behavior cases + 4 gotmp cases, all green
• bin/fm-test-run.sh tests/fm-bootstrap.test.sh — bootstrap seam regression, green
• Manual end-to-end CLI walkthrough of bin/fm-admission.sh in a fixture home: absent policy (exit 0, unchanged), note-only policy (inert), active policy with held lock and fresh census (human explanation, preferred/exit 0), --json decision record (task_id null, safety-only mode, backlog contradiction observed but band preferred, ledger seam integrated:false), --brief one-liner, lock not held (hard/exit 4), stale snapshot with unknown_band=soft (soft/exit 3), task argument refused (exit 2), validate refusing enforce:true, a typo'd config key, and unknown_band=preferred (each exit 2 with actionable reason)

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.