[codex] Backport machine-fit and local AI trial tooling

AGENTS.md

@@ -33,15 +33,19 @@ Use this order:
 - prefer clarity and explicit boundaries over magical automation
 - preserve `/srv/abyss-stack` as the canonical deployed runtime root unless explicitly redesigned
 - preserve the split between normative platform docs, public-safe host facts, and private host facts
+- treat current-machine fit as a first-class runtime concern before latency-sensitive or accelerator-sensitive work
 
 ## Host-facts rule
 
 - `docs/REFERENCE_PLATFORM.md` owns the intended host posture.
 - `docs/REFERENCE_PLATFORM_SPEC.md` owns the machine-readable contract and capture destinations.
+- `docs/MACHINE_FIT_POLICY.md` owns the current-machine adaptation policy and capture destinations.
 - `scripts/aoa-doctor` answers readiness, not durable inventory.
 - `scripts/aoa-host-facts` captures durable host facts.
+- `scripts/aoa-machine-fit` captures the bounded current-machine runtime posture.
 - public-safe artifacts may live under `docs/reference-platform/`
 - private captures belong under `${AOA_STACK_ROOT}/Logs/host-facts/`
+- private machine-fit captures belong under `${AOA_STACK_ROOT}/Logs/machine-fit/`
 
 ## Repository reading order
 

README.md

@@ -18,6 +18,7 @@ This repository is the right home for:
 - runtime-facing return and bounded context-rebuild policy for agent-facing routes
 - security, runbook, backup, and restore posture
 - normative host posture and machine-readable host-facts contracts
+- current-machine fit policy, driver freshness posture, and bounded machine-local tuning guidance
 - platform-adaptation policy and public-safe/private tuning record contracts
 - infra helper services that support AoA and ToS
 
@@ -59,22 +60,23 @@ This repository should not absorb:
 15. Read [docs/STORAGE_LAYOUT](docs/STORAGE_LAYOUT.md).
 16. Read [docs/REFERENCE_PLATFORM](docs/REFERENCE_PLATFORM.md).
 17. Read [docs/REFERENCE_PLATFORM_SPEC](docs/REFERENCE_PLATFORM_SPEC.md).
-18. Read [docs/PLATFORM_ADAPTATION_POLICY](docs/PLATFORM_ADAPTATION_POLICY.md).
-19. Read [docs/BRANCH_POLICY](docs/BRANCH_POLICY.md).
-20. Read [docs/MEMO_RUNTIME_SEAM](docs/MEMO_RUNTIME_SEAM.md).
-21. Read [docs/EVAL_RUNTIME_SEAM](docs/EVAL_RUNTIME_SEAM.md).
-22. Read [docs/PLAYBOOK_RUNTIME_SEAM](docs/PLAYBOOK_RUNTIME_SEAM.md).
-23. Read [docs/MODEL_PROFILES](docs/MODEL_PROFILES.md).
-24. Read [docs/CONTEXT_BUDGET_POLICY](docs/CONTEXT_BUDGET_POLICY.md).
-25. Read [docs/RECURRENCE_RUNTIME_POLICY](docs/RECURRENCE_RUNTIME_POLICY.md).
-26. Read [docs/DEPLOYMENT](docs/DEPLOYMENT.md).
-27. Read [docs/FIRST_RUN](docs/FIRST_RUN.md).
-28. Read [docs/DOCTOR](docs/DOCTOR.md).
-29. Read [docs/SECRETS_BOOTSTRAP](docs/SECRETS_BOOTSTRAP.md).
-30. Read [docs/LIFECYCLE](docs/LIFECYCLE.md).
-31. Read [docs/RUNBOOK](docs/RUNBOOK.md).
-32. Read [docs/SECURITY](docs/SECURITY.md).
-33. Read [docs/MIGRATION_FROM_OLD](docs/MIGRATION_FROM_OLD.md).
+18. Read [docs/MACHINE_FIT_POLICY](docs/MACHINE_FIT_POLICY.md).
+19. Read [docs/PLATFORM_ADAPTATION_POLICY](docs/PLATFORM_ADAPTATION_POLICY.md).
+20. Read [docs/BRANCH_POLICY](docs/BRANCH_POLICY.md).
+21. Read [docs/MEMO_RUNTIME_SEAM](docs/MEMO_RUNTIME_SEAM.md).
+22. Read [docs/EVAL_RUNTIME_SEAM](docs/EVAL_RUNTIME_SEAM.md).
+23. Read [docs/PLAYBOOK_RUNTIME_SEAM](docs/PLAYBOOK_RUNTIME_SEAM.md).
+24. Read [docs/MODEL_PROFILES](docs/MODEL_PROFILES.md).
+25. Read [docs/CONTEXT_BUDGET_POLICY](docs/CONTEXT_BUDGET_POLICY.md).
+26. Read [docs/RECURRENCE_RUNTIME_POLICY](docs/RECURRENCE_RUNTIME_POLICY.md).
+27. Read [docs/DEPLOYMENT](docs/DEPLOYMENT.md).
+28. Read [docs/FIRST_RUN](docs/FIRST_RUN.md).
+29. Read [docs/DOCTOR](docs/DOCTOR.md).
+30. Read [docs/SECRETS_BOOTSTRAP](docs/SECRETS_BOOTSTRAP.md).
+31. Read [docs/LIFECYCLE](docs/LIFECYCLE.md).
+32. Read [docs/RUNBOOK](docs/RUNBOOK.md).
+33. Read [docs/SECURITY](docs/SECURITY.md).
+34. Read [docs/MIGRATION_FROM_OLD](docs/MIGRATION_FROM_OLD.md).
 
 For the shortest next route by intent:
 - if you need the ecosystem center, layer map, or federation rules, go to [`Agents-of-Abyss`](https://github.com/8Dionysus/Agents-of-Abyss)
@@ -88,6 +90,7 @@ For the shortest next route by intent:
 - if you need the Windows host and WSL bridge workflow, read [docs/WINDOWS_BRIDGE](docs/WINDOWS_BRIDGE.md), [docs/WINDOWS_SETUP](docs/WINDOWS_SETUP.md), and [docs/WINDOWS_PERFORMANCE](docs/WINDOWS_PERFORMANCE.md)
 - if you need runtime benchmark ownership, storage, and manifest rules, read [docs/RUNTIME_BENCH_POLICY](docs/RUNTIME_BENCH_POLICY.md)
 - if you need normative host posture or machine-readable host-facts capture, read [docs/REFERENCE_PLATFORM](docs/REFERENCE_PLATFORM.md) and [docs/REFERENCE_PLATFORM_SPEC](docs/REFERENCE_PLATFORM_SPEC.md)
+- if you need to tune the runtime to the current machine, confirm driver freshness, or decide which preset the host should prefer, read [docs/MACHINE_FIT_POLICY](docs/MACHINE_FIT_POLICY.md)
 - if you need a compact record of platform-specific quirks, adaptations, and portability notes, read [docs/PLATFORM_ADAPTATION_POLICY](docs/PLATFORM_ADAPTATION_POLICY.md)
 - if you need the repo merge and branch discipline, read [docs/BRANCH_POLICY](docs/BRANCH_POLICY.md)
 - if you need the runtime-side memo mirror, recall seam, or export candidates, read [docs/MEMO_RUNTIME_SEAM](docs/MEMO_RUNTIME_SEAM.md)
@@ -164,6 +167,7 @@ The repository now includes:
 - render-truth helpers for actual composed runtime output
 - runtime benchmark policy, schema, and example artifacts
 - reference-platform schema and host-facts capture support
+- machine-fit schema and current-host adaptation capture support
 - platform-adaptation schema, example artifacts, and capture support
 - preset-aware composition helpers and preset introspection
 - Windows host bridge scripts and WSL guidance docs
@@ -174,9 +178,9 @@ The repository now includes:
 
 ## Current status
 
-`abyss-stack` is now a live multi-service runtime with stateful storage, local and Intel-aware inference paths, monitoring, host-facts capture, platform-adaptation logging, and landed federation advisory seams for sibling AoA repositories.
+`abyss-stack` is now a live multi-service runtime with stateful storage, local and Intel-aware inference paths, monitoring, host-facts capture, machine-fit capture, platform-adaptation logging, and landed federation advisory seams for sibling AoA repositories.
 The first live consumer step has now landed in `langchain-api` through opt-in `POST /run/federated`, which can consume advisory playbook and memo seams without changing the default `POST /run` path.
-The next large step is no longer whether the live runtime should consume those seams at all, but how broadly and how deeply the runtime loop should rely on them.
+The next large step is no longer bootstrap or mirror landing, or whether the live runtime should consume those seams at all; it is deciding how broadly and how deeply the runtime loop should rely on those already-landed seams.
 
 ## License
 

docs/DEPLOYMENT.md

@@ -23,6 +23,7 @@ If you want the least-friction path, use:
 ```bash
 scripts/aoa-doctor
 scripts/aoa-first-run --strict
+scripts/aoa-machine-fit --mode private --write "${AOA_STACK_ROOT}/Logs/machine-fit/latest/latest.private.json"
 ```
 
 `aoa-first-run --strict` is strict about layout and bootstrapped config presence, but still ignores missing secrets on that first pass by design.
@@ -102,6 +103,15 @@ Use `--strict` if warnings should fail the command.
 
 From a Windows host, use `pwsh -File scripts/aoa.ps1 host-doctor` for the Windows+WSL readiness pass before invoking the Linux doctor.
 
+### `scripts/aoa-machine-fit`
+
+Captures the bounded current-machine runtime posture after the layout exists.
+Use it to record:
+- which preset this host should currently prefer
+- whether the relevant host packages are current in configured repos
+- what validated local tuning should be reused
+- whether the current host envelope is too noisy for latency-sensitive work
+
 ### `scripts/aoa-install-layout`
 
 Creates the non-destructive runtime directory skeleton under `${AOA_STACK_ROOT}`.
@@ -204,6 +214,7 @@ scripts/aoa-install-layout
 scripts/aoa-sync-configs
 scripts/aoa-bootstrap-configs
 scripts/aoa-check-layout --ignore-secrets --strict
+scripts/aoa-machine-fit --mode private --write "${AOA_STACK_ROOT}/Logs/machine-fit/latest/latest.private.json"
 scripts/aoa-sync-federation-surfaces --layer aoa-agents   # optional
 scripts/aoa-sync-federation-surfaces --layer aoa-routing  # optional
 scripts/aoa-sync-federation-surfaces --layer aoa-memo     # optional

docs/DOCTOR.md

@@ -18,6 +18,8 @@ The current doctor pass looks at things like:
 - whether the optional vault path appears mounted
 - whether the stack root is the canonical `/srv/abyss-stack`
 - whether the selected runtime includes internal-only layers that should later be checked with `aoa-smoke --with-internal`
+- whether a current machine-fit record is missing for the deployed runtime root
+- whether the current host envelope looks noisy for latency-sensitive work
 
 ## Preset-aware and profile-aware behavior
 
@@ -39,6 +41,8 @@ Use `aoa-doctor` to decide whether a selected runtime is ready to start.
 
 Use `scripts/aoa-host-facts` to capture durable machine-readable host facts.
 
+Use `scripts/aoa-machine-fit` to capture the bounded current-machine runtime posture after host facts exist.
+
 The two surfaces complement each other and should not absorb each other's job.
 
 ## Usage
@@ -72,6 +76,7 @@ Durable host-facts capture:
 ```bash
 scripts/aoa-host-facts --mode public --write /tmp/reference-host.public.review.json
 scripts/aoa-host-facts --mode private --write "${AOA_STACK_ROOT}/Logs/host-facts/latest.private.json"
+scripts/aoa-machine-fit --mode private --write "${AOA_STACK_ROOT}/Logs/machine-fit/latest/latest.private.json"
 ```
 
 Keep `docs/reference-platform/reference-host.public.json` for later canonical-host refreshes, not routine local captures.
@@ -110,6 +115,7 @@ For a generic full bundle:
 scripts/aoa-doctor --preset agent-full
 scripts/aoa-first-run --strict
 scripts/aoa-check-layout --strict
+scripts/aoa-machine-fit --mode private --write "${AOA_STACK_ROOT}/Logs/machine-fit/latest/latest.private.json"
 scripts/aoa-smoke --with-internal --preset agent-full
 ```
 
@@ -119,5 +125,6 @@ For an Intel-aware full bundle:
 scripts/aoa-doctor --preset intel-full
 scripts/aoa-first-run --strict
 scripts/aoa-check-layout --strict
+scripts/aoa-machine-fit --mode private --write "${AOA_STACK_ROOT}/Logs/machine-fit/latest/latest.private.json"
 scripts/aoa-smoke --with-internal --preset intel-full
 ```

docs/FIRST_RUN.md

@@ -51,18 +51,20 @@ Then validate the fully bootstrapped layout:
 scripts/aoa-check-layout --strict
 ```
 
-## Optional but recommended: capture host facts
+## Optional but recommended: capture host facts and machine fit
 
-Once the runtime roots exist, record both the public-safe and local-private host posture:
+Once the runtime roots exist, record both the public-safe and local-private host posture, then capture the bounded current-machine fit:
 
 ```bash
 scripts/aoa-host-facts --mode public --write /tmp/reference-host.public.review.json
 scripts/aoa-host-facts --mode private --write "${AOA_STACK_ROOT}/Logs/host-facts/latest.private.json"
+scripts/aoa-machine-fit --mode private --write "${AOA_STACK_ROOT}/Logs/machine-fit/latest/latest.private.json"
 ```
 
 Review the public artifact before commit.
 Do not commit the private artifact.
 Only refresh `docs/reference-platform/reference-host.public.json` when you are intentionally updating the reviewed canonical Linux reference host snapshot.
+Refresh the private machine-fit record when kernel, firmware, container runtime, or validated local tuning changes.
 
 ## Inspect the profile before launch
 
@@ -107,6 +109,8 @@ scripts/aoa-profile-modules --profile agentic --paths
 scripts/aoa-profile-endpoints --profile agentic
 scripts/aoa-render-services --profile agentic
 scripts/aoa-up --profile agentic
+scripts/aoa-smoke --profile agentic
+scripts/aoa-qwen-check --case exact-reply
 ```
 
 ### Intel-aware runtime
@@ -118,6 +122,8 @@ scripts/aoa-profile-modules --profile intel --paths
 scripts/aoa-profile-endpoints --profile intel
 scripts/aoa-render-services --profile intel
 scripts/aoa-up --profile intel
+scripts/aoa-smoke --profile intel
+scripts/aoa-qwen-check --case exact-reply
 ```
 
 ## Use a preset instead of spelling the whole composition
@@ -128,8 +134,21 @@ scripts/aoa-profile-endpoints --preset agent-full
 scripts/aoa-render-services --preset agent-full
 scripts/aoa-up --preset agent-full
 scripts/aoa-smoke --with-internal --preset agent-full
+scripts/aoa-qwen-bench --preset agent-full
 ```
 
+## Optional supervised local AI qualification
+
+Once the intended Qwen path is healthy, materialize the bounded local pilot and run the runtime wave:
+
+```bash
+scripts/aoa-local-ai-trials materialize
+scripts/aoa-local-ai-trials run-wave W0
+```
+
+That flow keeps machine-readable trial truth under `Logs/local-ai-trials/` and writes Markdown mirrors to `Dionysus/reports/local-ai-trials/`.
+Use [LOCAL_AI_TRIALS](LOCAL_AI_TRIALS.md) for the full contract.
+
 ## Compose optional layers manually
 
 ### Agent runtime plus tools
@@ -168,6 +187,7 @@ Then read:
 - [DEPLOYMENT](DEPLOYMENT.md)
 - [DOCTOR](DOCTOR.md)
 - [REFERENCE_PLATFORM_SPEC](REFERENCE_PLATFORM_SPEC.md)
+- [MACHINE_FIT_POLICY](MACHINE_FIT_POLICY.md)
 - [PRESETS](PRESETS.md)
 - [PROFILE_RECIPES](PROFILE_RECIPES.md)
 - [RENDER_TRUTH](RENDER_TRUTH.md)