@openlife/cli 1.7.3

package/docs/stories/epic-feature-completeness/3.7.story.md

@@ -0,0 +1,68 @@
+# Story 3.7 — End-to-end install flow tests (CLI spawn against `node bin/openlife.js`)
+
+**StoryId:** `3.7`
+**Epic:** `epic-multi-host-installer` (v1.1)
+**Status:** InReview
+**Severity:** P2 (test infrastructure — valuable safety net for the installer surface, but does not block release on its own)
+**Cluster:** install-flow
+**Depends on:** Story 3.1 (host enum + validator), Story 3.2 (dist-templates roster), Story 3.3 (`HostInstaller` dispatcher), Story 3.4 (reversible uninstall), Story 3.5 (`openlife init` wizard), Story 3.6 (per-host docs + doc-parity test)
+
+## Description
+
+Stories 3.1–3.6 each shipped focused unit tests against the classes they introduced — `HostInstaller`, `InstallFlow`, `InstallWizard`, and the doc-parity grep suite. Those tests prove each class is internally correct, but they do **not** prove the CLI binary is correct. The wiring between Commander flags, the lazy-require chain in `src/index.ts`, the JSON output contract, exit codes, and the side effects landed under `.openlife/` and `.claude/` only converges when `node bin/openlife.js` is the entry point — and that is exactly the path a real operator (or a CI script) takes. Bugs at that boundary — a flag that never reaches the installer class, a lazy `require()` accidentally promoted to module scope, an error envelope that prints fine but exits 0 — pass every unit test in the suite and only fail when somebody runs the binary.
+
+Story 3.7 closes that gap with `src/test_host_install_e2e.ts`: six spawn-based scenarios that drive `node bin/openlife.js` against a fresh temp project root and assert on real filesystem side effects, real exit codes, and the real JSON envelope printed to stdout. The test owns its own temp roots (cleaned in `finally`), uses 60 second per-spawn timeouts to stay healthy on WSL, and is wired into `test:all` as the 70th test.
+
+## Acceptance Criteria
+
+- [x] **`src/test_host_install_e2e.ts`** covers 6 scenarios end-to-end via `child_process.spawnSync(process.execPath, ['bin/openlife.js', ...])`:
+  1. `claude-code` full cycle: `system setup --profile framework --host claude-code` exits 0, writes `.openlife/`, `.claude/agents/openlife-*.md`, `.claude/commands/openlife/*.md`, and `.openlife/install-mcp-snippet.json`; `system status --host claude-code` reports installed; `system uninstall --host claude-code` exits 0 and removes the host-side artifacts while preserving `.openlife/` state per Story 3.4
+  2. `gemini-cli` graceful degradation: `system setup --profile framework --host gemini-cli` exits 0, JSON envelope contains the skipped-host record with `HOST_NOT_YET_SUPPORTED`, and `.openlife/` is still created by `SystemInstaller`
+  3. `codex` graceful degradation: same shape as scenario 2, exit 0, skipped-host record, `.openlife/` still created
+  4. Invalid host rejected at CLI boundary: `system setup --profile framework --host cursor` exits non-zero with a clear `invalid_host` envelope (validates Story 3.1's `validateHost()` is wired before any installer logic)
+  5. Uninstall on a clean project is idempotent: `system uninstall --host claude-code` against a temp dir with no prior install exits 0, reports "nothing to remove" cleanly, leaves no stray files
+  6. Reinstall is idempotent: running `system setup --profile framework --host claude-code` twice back-to-back produces the same final filesystem state, second run reports `skipped-identical` for unchanged templates and does not duplicate `.openlife/install-manifest.json` entries
+- [x] Each spawn uses a 60s timeout (`spawnSync({ timeout: 60_000 })`) — generous enough for WSL + Node require-tree warm-up without hanging CI
+- [x] Each scenario cleans its temp root in a `finally` block (`fs.rmSync(tmpRoot, { recursive: true, force: true })`) so a failing assertion does not leak directories across runs
+- [x] Assertions are explicit on **both** exit code (`status === 0`) and filesystem side effects (`fs.existsSync(...)`, `JSON.parse(...)` of the manifest); no scenario relies on stdout-only signals
+- [x] Test wired in `package.json` (new `test:host-install-e2e` script) and appended to the `test:all` chain
+- [x] Suite 69 → 70 verde — full `npm run test:all` passes locally after the new test joins the chain
+
+## Dev Notes
+
+- **Why is an E2E pass separate from the unit tests already in 3.3–3.5?** Unit tests prove the class is correct. E2E proves the binary is correct. The two failure modes are different: the most expensive bugs in CLI tooling are wiring bugs ("the flag is parsed but never reaches the installer", "the JSON envelope prints to stderr instead of stdout", "the exit code is 0 even though we threw") and those bugs pass every unit test in the suite because the classes themselves are fine. Only spawning the binary exposes them. Six scenarios is the minimum that exercises every host slot Story 3.1–3.5 introduced plus the two idempotency contracts the installer promises.
+- **Why spawn `node bin/openlife.js` instead of calling Commander programmatically in-process?** Fidelity. Programmatic invocation re-uses the test process's `require.cache`, leaks env vars, shares `process.exit` semantics with the test runner, and bypasses the `bin/openlife.js → dist/index.js` shim that real users actually hit. Spawning gives us the same require-tree latency, the same env-var inheritance, the same stdio buffering, and the same exit-code propagation a real install gets — which is precisely the surface we want to lock.
+- **Why 60s per-spawn timeouts?** Cold-starting `node bin/openlife.js` on WSL with the current require chain is empirically slow on the heavier paths — `Brain.ts` pulls in three SDKs (~10s), `Gateway.ts` pulls Telegraf + Express (~21s), and `Gatekeeper.ts` chains both (~23s). The lazy-import contract in `src/index.ts:11-13` keeps `--help`, `plugin`, and `context` fast, but `system setup` is one of the paths that legitimately touches the heavier wiring. 60s is a comfortable ceiling that catches genuinely hung processes (infinite loops, deadlocks) without flapping on a slow first run.
+- **Why test the invalid-host case (scenario 4) at the CLI boundary instead of trusting `test_host_validator.ts` from Story 3.1?** `validateHost()` is correct as a unit, but it only protects the installer surface if it is actually called before any other logic in the `system setup` command handler. Promoting `validateHost()` accidentally below the lazy-require for `InstallFlow` would silently allow an invalid host to reach the installer with `--host cursor`, fail there with a confusing error, and pass every unit test. Spawning with `--host cursor` is the only way to prove the validator runs at the boundary it claims to.
+- **Why test reinstall idempotency (scenario 6) explicitly?** Operators re-run `system setup` whenever `dist-templates/` is updated upstream — that is the documented path for picking up a new agent file. If the second run duplicated entries in `.openlife/install-manifest.json`, wrote conflicting `.bak` files, or worse threw on perceived conflicts, the operator would experience a silent UX regression and would not have a unit test catching it (the `HostInstaller` unit tests in 3.3 exercise idempotency, but only for the installer class — not for the full install flow including manifest persistence). E2E is where the contract earns its keep.
+- **Why test uninstall idempotency (scenario 5)?** CI scripts and rollback automations call `system uninstall` defensively, often in series — "uninstall any prior version, then install the new one". If the first uninstall on a clean tree threw or exited non-zero, every downstream rollback script would have to add a wrapper to swallow the error. Story 3.4 promises idempotent uninstall; this scenario proves the promise survives the CLI boundary.
+- **Why is this Severity P2 rather than P1?** No customer-visible feature is broken without this test — the install flow works today and the unit tests already prove the classes are correct. What this story adds is *insurance*: the next time somebody refactors the lazy-require block, renames a CLI flag, or "cleans up" the JSON envelope, the E2E suite turns a silent regression into a red `test:all`. Valuable, but the release does not literally fail without it. P2 is the right tier — adjacent to 3.6's doc-parity test, same logic: a deterministic regression net for surfaces that reviewers and unit tests both routinely miss.
+
+## File List
+
+- `src/test_host_install_e2e.ts` — NEW (6 spawn-based scenarios; per-scenario temp-root setup/teardown; 70th test in suite)
+- `package.json` — MODIFIED (added `test:host-install-e2e` script; appended to `test:all`)
+
+## Change Log
+
+- 2026-05-11 — @dev (Charlie) — Added end-to-end install-flow tests that spawn `node bin/openlife.js` against fresh temp project roots. Six scenarios: claude-code full cycle (setup → status → uninstall), gemini-cli graceful degradation, codex graceful degradation, invalid host (`cursor`) rejected at CLI boundary, uninstall idempotent on clean project, reinstall idempotent. Each spawn capped at 60s for WSL safety; temp dirs cleaned in `finally` even on assertion failure. Wired into `test:all` via `test:host-install-e2e`. Suite 69 → 70 verde. Status: Ready → InReview.
+
+## IDS check
+
+**Decision:** CREATE (no prior E2E spawn-based test exists in the suite — the closest analog, `test_enterprise_agentic_core.ts`, spawns the CLI but for a single plugin command, not the full install/status/uninstall lifecycle) + REUSE (the `spawnSync(process.execPath, ['bin/openlife.js', ...])` pattern is the same shape `test_enterprise_agentic_core.ts` already uses; temp-root setup follows the same `os.tmpdir()` + `fs.mkdtempSync` convention as the unit tests in 3.3/3.4; assertion style follows the throw-on-failure / log-on-success convention used across the entire `src/test_*.ts` family). No new test harness, no new framework — same standalone `test_*.ts` convention.
+
+## What unblocks for v1.1
+
+- v1.1 release confidence — every refactor of the installer surface (flag rename, lazy-require shuffle, JSON envelope tweak) now has a deterministic safety net that runs in under a minute of `test:all`
+- Story 3.8+ (real `gemini-cli` / `codex` installers) — when those land, scenarios 2 and 3 flip from "asserts skipped-host record" to "asserts host-side artifacts written" with a focused diff, structure of the test file stays stable
+- Future installer features (per-host MCP auto-merge, alternate profile slots, agent prefix overrides) — each gets an E2E scenario appended to the same file, same harness, no new tooling
+- CI escalation — when the project moves from local-only `test:all` to a hosted CI runner, the E2E suite is what proves the binary works in a fresh container, not just in the developer's warm WSL
+
+## What this does NOT do
+
+- E2E tests for the interactive `openlife init` wizard → spawning an interactive TTY reliably requires either a mocked PTY layer or `expect(1)`-style scripting; both are heavyweight and the wizard is already covered by `test_install_wizard.ts` at the unit level. Deferred to a separate story if the wizard surface grows or churns.
+- Live integration tests against real external services (Telegram bot, OpenAI API, Gemini API) → those belong in `test:integrations`, which is a separate chain by design (per `CLAUDE.md`'s test budget contract); this story keeps `test:all` deterministic and credential-free.
+- Performance benchmarks of install duration → 60s timeout is a hang-detector, not a perf budget. Install perf is not a functional regression and a flaky timing assert would do more harm than good.
+- Tests inside virtual hosts (containers, Docker, full VMs) → that is release-engineering / CI-runner territory, not story-level work. The E2E suite proves the binary works on the developer's host; the CI pipeline (separate concern) proves it works on a clean runner.
+- Cross-OS coverage (native Linux without WSL, macOS, Windows PowerShell) → the suite runs wherever Node 18+ runs, but explicit per-OS assertions belong in a dedicated cross-platform story if/when adoption demands it.
+- Coverage for `system doctor`, `plugin install`, or other unrelated CLI surfaces → scope is strictly the install/status/uninstall lifecycle introduced by 3.1–3.5; other CLI surfaces stay covered by their own unit tests.

package/docs/stories/epic-feature-completeness/3.8.story.md

@@ -0,0 +1,57 @@
+# Story 3.8 — Document and lock the `OPENLIFE_RUNTIME_PROFILE=oauth-only` profile
+
+**StoryId:** `3.8`
+**Epic:** `epic-multi-host-installer` (v1.1) — **FINAL story**
+**Status:** InReview
+**Severity:** P2 (closes a doc-vs-code gap; behavior shipped but undocumented and untested)
+**Cluster:** install-flow
+**Depends on:** Story 3.1–3.7 (host enum, dist-templates, HostInstaller, uninstall, wizard, multi-host docs, E2E tests)
+
+## Description
+
+The `OPENLIFE_RUNTIME_PROFILE=oauth-only` profile has existed in `src/cli/WorldClassCommands.ts:23` for several iterations. Inside `doctorWorldDetailed()`, the classifier downgrades four doctor checks from their default severity to `info` when this env var is set: `cli:ollama`, `env:OPENAI_API_KEY`, `env:GEMINI_API_KEY`, and `env:ANTHROPIC_API_KEY`. The rationale: operators running OpenLife exclusively through OAuth-authenticated CLI executors (`claude`, `codex`, `gemini` CLIs) do not need API keys, and Ollama is optional in that posture — so the doctor should report those absences as informational, not as blockers that fail health checks.
+
+The codebase audit on 2026-05-11 (observation #1379) flagged this as the kind of feature that ships, works, and silently rots: no documentation, no regression test, no surface in `INSTALL.md`, no entry in any per-host reference. The next operator who refactors the classifier could quietly break the contract and nothing in the test suite would catch it. Story 3.8 closes that gap before v1.1 ships.
+
+This is a **documentation + regression-test only** story. The feature itself is not changed — `WorldClassCommands.ts` is untouched.
+
+## Acceptance Criteria
+
+- [x] **`src/test_runtime_profile_oauth_only.ts`** covers the parity contract with 4 scenarios:
+  1. **Default profile (no env var)** — Running `doctorWorldDetailed()` with `OPENAI_API_KEY`, `GEMINI_API_KEY`, `ANTHROPIC_API_KEY` cleared keeps each failing check at its default severity (`cli:ollama` → `blocker`, `env:*` → `warning`); no check downgrades to `info` purely from being `ok: false`
+  2. **oauth-only downgrade** — Setting `OPENLIFE_RUNTIME_PROFILE=oauth-only` reclassifies all four affected checks (`cli:ollama`, `env:OPENAI_API_KEY`, `env:GEMINI_API_KEY`, `env:ANTHROPIC_API_KEY`) to `severity: 'info'` when they come back `ok: false`
+  3. **Case-insensitive matching** — Setting `OPENLIFE_RUNTIME_PROFILE=OAuth-Only` produces the same downgrade behavior (the classifier compares via `.toLowerCase()`)
+  4. **Unrelated checks remain unaffected** — Failing checks whose names do not match the four oauth-downgrade names (e.g. `runtime:*`, `cli:codex`, `cli:claude`) keep their non-`info` severity even when oauth-only is active
+- [x] Test prints `TEST_RUNTIME_PROFILE_OAUTH_ONLY_OK` on success, throws or exits non-zero on failure (matches the convention from `test_multi_host_docs_parity.ts` and other tests)
+- [x] Test owns its temp dir via `mkdtempSync` and restores `process.cwd()` plus env-var snapshot in `finally` so it is hermetic
+- [x] Wired in `package.json`: new `test:runtime-profile-oauth-only` script + appended to `test:all`
+- [x] **`INSTALL.md`** has a new "Runtime profiles (advanced)" subsection (~15-25 lines) explaining what `oauth-only` does, when to use it, which 4 checks are affected, and that it is purely a severity classifier (provider chain unchanged)
+- [x] **`docs/install/runtime-profiles.md`** — dedicated advanced reference (~80 lines) with env-var table, worked before/after example, "what it does NOT do", forward-compatibility note, cross-link to `INSTALL.md`
+- [x] Suite 70 → 71 verde — full `npm run test:all` passes locally after the new test joins the chain
+
+## Dev Notes
+
+- **Why test a feature instead of building one?** The codebase audit (#1379) found that `oauth-only` shipped without docs or coverage. That is the classic "feature fantasma" pattern: works today, will silently break the next time somebody touches the classifier, no test catches it. The cheapest hardening pass for v1.1 is to bind the existing behavior to a regression test and surface it in the user-facing docs — before v1.1 freezes.
+- **Why is the test scenario explicit about the default severities (`blocker` for `cli:ollama`, `warning` for `env:*`)?** During implementation we discovered the classifier's default branches actually differ per check name — `cli:ollama` hits the `name.startsWith('cli:')` branch (`blocker`), while the three `env:*` keys fall through to the catch-all (`warning`). Writing the test as "all four downgrade to `info`" is correct; writing it as "all four go from `blocker` to `info`" would have been wrong. The test, the INSTALL.md section, and `docs/install/runtime-profiles.md` all describe the downgrade as "to `info`" rather than "from blocker to info" so the documentation cannot drift from the actual classifier shape.
+- **Why a dedicated `docs/install/runtime-profiles.md` instead of folding everything into `INSTALL.md`?** Casual users do not care — they install with API keys and the doctor is happy. The advanced subsection in `INSTALL.md` is a breadcrumb for those users so they know the feature exists; the dedicated doc is for the operator who actually runs OAuth-only and wants the exact before/after output, the forward-compatibility contract, and the explicit "what this does NOT do" list. Splitting keeps `INSTALL.md` readable for the 95% path and gives the 5% path the depth it needs.
+- **Why mark the env var as forward-compatible?** `OPENLIFE_RUNTIME_PROFILE` is a single env var with a single recognized value today (`oauth-only`), but the obvious next values are `local-only` (downgrade cloud API checks, keep Ollama as blocker), `enterprise-strict` (treat any non-info finding as blocker), and `ci-mode` (suppress doctor noise entirely). Documenting the env var as a profile slot rather than a single boolean toggle means the next person to add a value does not need to rename the contract, and the test can grow alongside it.
+- **Why is the test against the compiled `dist/cli/WorldClassCommands.js` rather than the TypeScript source?** Every other test in `src/test_*.ts` follows the same pattern: build first, then run the compiled artifact under `node dist/`. The test seam in this story re-uses `require('./dist/cli/WorldClassCommands.js')` (via the build chain in the npm script) so it stays consistent with `test_host_uninstaller.ts` and `test_multi_host_docs_parity.ts`. Going around `tsc` would also bypass the `strict: true` contract — a regression would compile fine in a forgiving runtime and silently slip through.
+- **Why is this Severity P2?** No customer-visible feature breaks without this story — `oauth-only` already works for the operators who happen to know about it. What is missing is *discoverability* (no one knows the feature exists) and *durability* (no test guards it). P2 matches the same logic as Story 3.6 (doc-parity) and Story 3.7 (E2E tests): valuable insurance, not release-blocking on its own. Together they form the safety net under v1.1.
+- **Why is this the final story of v1.1?** The epic's stated goal is a "complete and hardened multi-host installer surface". Stories 3.1–3.5 built the surface (enum, templates, install, uninstall, wizard). Stories 3.6–3.7 hardened the surface (per-host docs, doc-parity test, end-to-end CLI tests). Story 3.8 catches the last known doc-vs-code gap. With it closed, the epic delivers what it promised. Subsequent work (gemini-cli and codex installers behind their reserved hosts; new runtime profiles) is the next epic's scope.
+
+## File List
+
+- `src/test_runtime_profile_oauth_only.ts` — NEW (4 scenarios; env-var snapshot/restore; 71st test in suite)
+- `package.json` — MODIFIED (added `test:runtime-profile-oauth-only` script; appended to `test:all` chain)
+- `INSTALL.md` — MODIFIED (new "Runtime profiles (advanced)" subsection cross-linking to the dedicated reference)
+- `docs/install/runtime-profiles.md` — NEW (advanced reference: env-var contract table, worked before/after example, forward-compatibility note)
+
+## Change Log
+
+- 2026-05-12 — @dev (Charlie) — Documented and locked the `OPENLIFE_RUNTIME_PROFILE=oauth-only` profile that has existed in `WorldClassCommands.ts:23` without docs or tests since pre-v1.1. New regression test (`src/test_runtime_profile_oauth_only.ts`) asserts the four-check downgrade contract with 4 scenarios: default severities preserved without env var; oauth-only downgrades `cli:ollama`, `env:OPENAI_API_KEY`, `env:GEMINI_API_KEY`, `env:ANTHROPIC_API_KEY` to `info`; case-insensitive matching; unrelated checks unaffected. New advanced subsection in `INSTALL.md` and dedicated `docs/install/runtime-profiles.md` reference document the contract for operators. Suite 70 → 71 verde. Status: Ready → InReview. **Final story of v1.1 epic.**
+
+## IDS check
+
+- **REUSE:** Test structure reuses the env-var snapshot/restore pattern from `test_multi_host_docs_parity.ts` and the temp-dir + `process.chdir()` pattern from `test_host_uninstaller.ts`.
+- **ADAPT:** Documentation structure adapts the per-host reference layout from `docs/install/claude-code.md` to the orthogonal "runtime profile" concept.
+- **CREATE:** New artifacts: `src/test_runtime_profile_oauth_only.ts` (new test surface — runtime profile classification has no prior coverage), `docs/install/runtime-profiles.md` (new doc surface — runtime profiles were undocumented). Both registered under `epic-multi-host-installer` and cross-referenced from `INSTALL.md`.

package/docs/toolset-enforcement.md

@@ -0,0 +1,122 @@
+# OpenLife — toolset enforcement (Stories 10.1 + 10.2)
+
+## What it is
+
+A thin kernel-style enforcement layer that decides, at runtime, whether
+the current Profile permits a given toolset category before the executor
+spawns a subprocess, calls a CLI, or makes a delegation.
+
+It builds on `ToolsetRegistry` (Story 5.3) and adds a single guard module:
+`src/orchestrator/toolset/ToolsetGuard.ts`. The guard exposes:
+
+```ts
+isToolsetAllowed(toolset: ToolsetCategory): boolean   // never throws
+assertToolsetAllowed(toolset: ToolsetCategory, hint?: string): void  // throws ToolsetBlockedError
+```
+
+`ToolsetBlockedError` has a stable error code: `toolset_blocked:<category>`.
+Callers can match on `.code` instead of substring-matching `.message`.
+
+## Opt-in by environment flag
+
+The guard is gated by `OPENLIFE_TOOLSET_ENFORCEMENT`. The decision matrix:
+
+| `OPENLIFE_TOOLSET_ENFORCEMENT` | Behavior |
+|---|---|
+| unset / empty / anything other than `on` | Enforcement OFF. Both `isToolsetAllowed` and `assertToolsetAllowed` short-circuit before consulting the registry. **This is the v1.4 default.** |
+| `on` (case-insensitive) | Enforcement ON. Both functions consult `ToolsetRegistry.isAllowed(...)` against the active Profile. |
+
+The `=on` default OFF stance for v1.4 is a **locked decision** from the
+plan: enforcement soaks for one milestone. **v1.5 flips the default to
+ON.** Plan ahead — anything that relies on profiles with restrictive
+`toolsetAllowed` will become enforceable in v1.5.
+
+## The five hook points
+
+The guard is wired at exactly five places — the spots that historically
+have been the easiest way to bypass governance:
+
+| Site | Toolset | Why |
+|---|---|---|
+| `TaskExecutor.executeWithCodex` | `delegation` | Delegating cognition to the `codex` CLI. |
+| `TaskExecutor.executeWithGemini` | `delegation` | Same, for `gemini`. |
+| `TaskExecutor.runShellCommand` | `terminal` | The underlying `/bin/bash` spawn the two executors fan out to. |
+| `Brain.thinkWithOpenAICLI` | `delegation` | `Brain` shell-out to the `codex` CLI. |
+| `Brain.thinkWithGeminiCLI` | `delegation` | Same, for `gemini`. |
+
+Note that `delegation` and `terminal` are orthogonal axes: a profile can
+permit local shell tools (`terminal`) while forbidding delegation to
+external cognitive CLIs (`delegation`). Both guards are checked
+independently.
+
+## Configuring a profile
+
+`ToolsetRegistry` reads `profile.toolsetAllowed`:
+
+| `toolsetAllowed` value | Meaning |
+|---|---|
+| `['*']` | Wildcard — every one of the 15 categories is allowed. |
+| `['file', 'web', 'memory']` | Only those three. |
+| `[]` | Locked-down — nothing allowed. |
+
+The 15 categories are `file`, `terminal`, `web`, `browser`, `memory`,
+`skills`, `workflows`, `squads`, `gateway`, `cron`, `delegation`, `mcp`,
+`vision`, `tts`, `image_gen`.
+
+Example: a profile that lets the operator run local shell tools but
+forbids any LLM CLI shellout:
+
+```bash
+openlife profile create research-only \
+  --toolset-allowed file,terminal,memory,skills,workflows,squads,web
+openlife profile use research-only
+
+OPENLIFE_TOOLSET_ENFORCEMENT=on openlife task run "do x"
+#  → if `do x` routes through TaskExecutor.executeWithCodex, throws
+#    `toolset_blocked:delegation`
+```
+
+## Catching the error
+
+Callers can catch and inspect:
+
+```ts
+try {
+  assertToolsetAllowed('terminal', 'MyCaller.run');
+} catch (err) {
+  if (err instanceof ToolsetBlockedError) {
+    console.log(err.code);     // "toolset_blocked:terminal"
+    console.log(err.toolset);  // "terminal"
+    console.log(err.message);  // "toolset_blocked:terminal (MyCaller.run)"
+  }
+}
+```
+
+The error message ends with the `hint` parameter when provided, so the
+operator can trace which call site triggered the block.
+
+## Diagnosing during the soak window
+
+Because v1.4 keeps the default OFF, the easiest way to see how a profile
+would behave under v1.5's default-ON is to run the relevant CLI command
+with the flag turned on once:
+
+```bash
+OPENLIFE_TOOLSET_ENFORCEMENT=on openlife <command>
+```
+
+If anything fails with `toolset_blocked:*` you have until the v1.5 cutover
+to either widen the profile's `toolsetAllowed`, move the call site
+behind a different toolset axis, or accept that the operation should
+indeed be blocked.
+
+## How it's tested
+
+`src/test_toolset_enforcement.ts` covers four scenarios:
+
+1. Flag unset — every `isToolsetAllowed` returns `true`, `assertToolsetAllowed` never throws.
+2. Flag ON + `toolsetAllowed: ['*']` — same as above.
+3. Flag ON + `toolsetAllowed: ['memory']` — `terminal` and `delegation` return `false` / throw `ToolsetBlockedError` with the stable code.
+4. The error class is `instanceof ToolsetBlockedError` in every blocked case, so callers can pattern-match on the class.
+
+CI runs this test in the `test:all` chain.

package/docs/v1.4-changelog.md

@@ -0,0 +1,159 @@
+# OpenLife v1.4 — "Path to 10/10" Changelog
+
+**Branch:** `feat/v1.4-tenten`
+**Status:** All sprints complete; awaiting approval for PR + merge + tag `v1.4.0`.
+
+v1.4 is pure consolidation. No new pillars, no new conceptual surface. The
+five epics close eight structurally identified gaps from the v1.3 → 9.6/10 audit,
+fulfill the remaining v1.3 placeholders, and add CI + perf telemetry. Target
+scorecard: **10.0 / 10 (A+)**.
+
+---
+
+## What changed by epic
+
+### Epic 8 — Intelligence wiring (Sprint 1)
+
+| Story | Surface | Outcome |
+|---|---|---|
+| 8.1 | `Brain.isAnyProviderAvailable()`, `SquadCreator.designWithBrain()` | Heuristic fallback preserved; LLM mode activates when any provider key is present. No extra flag — presence of the key is the opt-in signal. |
+| 8.2 | `SkillCreator.designWithBrain()` | Same pattern as 8.1; shares the structured JSON contract. |
+| 8.3 | `OrchestrationLoop.firePostMissionHook()` → `OmniMemory.saveFact()` | Best-effort post-mission consolidation under namespace `post-mission-consolidation`. Disable via `OPENLIFE_POST_MISSION_CONSOLIDATION=off`. |
+
+### Epic 9 — Real I/O (Sprint 2)
+
+| Story | Surface | Outcome |
+|---|---|---|
+| 9.1 | `SecurityDownloadGuard.downloadAndScan(url, targetDir?, opts?)` | Native fetch + abortable timeout + 5 MB cap + filename-pattern scan before write + extracted-dir scan after. Returns `{ ok, downloadedTo?, bytesWritten?, errors[], warnings[] }`. Never throws. |
+| 9.2 | `ExternalCatalogRegistry.importAndFetch(...)` | Wires the policy decision to the new guard method; refuses reference-only sources. |
+| 9.3 | `HostInstaller.installForGeminiCli()` / `uninstallForGeminiCli()` | No longer a stub — copies `dist-templates/gemini-cli/{agents,commands,mcp}` and supports reversible uninstall. |
+| 9.4 | `HostInstaller.installForCodex()` / `uninstallForCodex()` | Mirror for `~/.codex/`. |
+| 9.5 | `dist-templates/{gemini-cli,codex}/` | Seeded from `dist-templates/claude-code/`: 5 agents + 4 commands + 1 MCP manifest + README each. |
+
+### Epic 10 — Enforcement (Sprint 3 + part of Sprint 1)
+
+| Story | Surface | Outcome |
+|---|---|---|
+| 10.1 | `assertToolsetAllowed('terminal' | 'delegation', ...)` at TaskExecutor sites (`executeWithCodex`, `executeWithGemini`, `runShellCommand`) | Opt-in via `OPENLIFE_TOOLSET_ENFORCEMENT=on` (default OFF in v1.4 — soaks one milestone; flips to default ON in v1.5). Stable error code: `toolset_blocked:<category>`. |
+| 10.2 | `assertToolsetAllowed` at `Brain.thinkWithOpenAICLI` + `Brain.thinkWithGeminiCLI` | Same pattern, same flag. |
+| 10.3 | `src/orchestrator/workflow/ConditionParser.ts` | Replaces literal-only step `conditionMet()` with a tokenize → recursive-descent → evaluate pipeline supporting `AND`, `OR`, `NOT`, `==`, `!=`, parentheses, and dotted identifiers. Backward-compat: bare identifier still means `ctx[id] === true`. |
+
+### Epic 11 — Creator completeness (Sprint 4)
+
+The six v1.3 placeholders are now real, atomic, and inventory-first.
+
+| Story | Surface | Outcome |
+|---|---|---|
+| 11.1 | `SquadCreator.migrate(squadId, fromVersion, toVersion)` | Rewrites both the SQUAD.md frontmatter and the embedded `squad.yaml` version line; rejects `version_mismatch` up-front. |
+| 11.2 | `SquadCreator.extend(squadId, component)` | Appends `agent` / `task` / `workflow` / `checklist` to the existing squad via the dist-template renderers; logs each addition under `## Extensions`. |
+| 11.3 | `SquadCreator.publish(squadId)` | SHA-256 of SQUAD.md → `.openlife/published-assets.jsonl`; frontmatter status flips `draft` → `active`. Archived squads refuse publish. |
+| 11.4 | `SkillCreator.migrate(...)` | Atomic frontmatter version bump with semver-like validation. |
+| 11.5 | `SkillCreator.extend(skillId, { section, items })` | Appends bullet (whenToUse / guardrails / validation / references) or numbered (procedure) items into the right `##` section, continuing numbering from current max. |
+| 11.6 | `SkillCreator.publish(...)` | Same SHA-256 + ledger + status pattern as Squad. |
+
+### Epic 12 — Quality + CI (Sprint 5)
+
+| Story | Surface | Outcome |
+|---|---|---|
+| 12.1 + 12.2 + 12.3 | `any` reduction in hot-path files | Brain.ts 15 → 0; OrchestrationLoop.ts 9 → 0; Gateway.ts middleware now typed via `Request` / `Response` / `NextFunction`; index.ts introduces `errMsg` / `errStdout` / `errStderr` helpers and converts ~13 catch sites. Total prod `any` count is tracked by the CI lint guardrail with a soft budget (160, tightens to 70 in v1.5). |
+| 12.4 | `src/test_performance_latency.ts` + `.artifacts/perf-baseline.json` | P50 / P95 / P99 for `IntentClassifier.classify`, `ToolsetGuard.isToolsetAllowed`, `ProfileManager.list`. CI fails if any P95 regresses > `PERF_REGRESSION_THRESHOLD_PCT` (default 30 %). See [performance-benchmarks.md](./performance-benchmarks.md). |
+| 12.5 | `.github/workflows/{build,test,lint}.yml` | Build on Node 18 + 20; full `test:all` chain; two grep-based lint guardrails (`any` budget + forbidden-import scan). |
+
+---
+
+## Sprint timeline + commits
+
+| Sprint | Stories | Commit |
+|---|---|---|
+| 1 | 8.1 / 8.2 / 8.3 / 10.3 | `5da03df` |
+| 2 | 9.1 / 9.2 / 9.3 / 9.4 / 9.5 | `3e0517f` |
+| 3 | 10.1 / 10.2 | `81d5cc0` |
+| 4 | 11.1 – 11.6 | `5fce533` |
+| 5 | 12.1 – 12.5 | `24bd422` |
+| 6 (Cap) | C.1 docs + final lock | _this commit_ |
+
+---
+
+## New tests added in v1.4
+
+| Test | Stories covered |
+|---|---|
+| `test_squad_skill_design_llm.ts` | 8.1 + 8.2 |
+| `test_workflow_condition_parser.ts` | 10.3 |
+| `test_security_download_and_scan.ts` | 9.1 + 9.2 |
+| `test_host_installers_gemini_codex.ts` | 9.3 + 9.4 + 9.5 |
+| `test_toolset_enforcement.ts` | 10.1 + 10.2 |
+| `test_creator_placeholders_completed.ts` | 11.1 – 11.6 |
+| `test_performance_latency.ts` | 12.4 |
+
+Existing test updates: `test_host_installer.ts` + `test_host_uninstaller.ts`
+had v1.3-era stub assertions that needed to be inverted to verify the real
+Story 9.3 + 9.4 behavior. `test_squad_skill_creator.ts` had the v1.3
+placeholder assertions, now replaced with real `squad_not_found` error-path
+checks against Story 11.x.
+
+---
+
+## Locked decisions
+
+1. **Toolset enforcement is opt-in in v1.4.** `OPENLIFE_TOOLSET_ENFORCEMENT=on`
+   gates every guard call. Default OFF for one milestone of soak; v1.5 flips
+   the default to ON.
+2. **Brain-driven `design()` has no extra flag.** If any provider key
+   (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `OPENROUTER_API_KEY`,
+   `OLLAMA_URL`) is present, `designWithBrain()` calls Brain. Otherwise it
+   falls back to the heuristic `design()`. Presence of the key IS the opt-in.
+
+---
+
+## Out of scope (deferred to v1.5)
+
+- Distributed multi-host scheduler — v1.4 stays single-host.
+- Real remote pack publish — v1.4 just appends to the local ledger.
+- Toolset enforcement default-on — v1.5 flips after soak.
+- LLM-driven post-mission **evaluation** — v1.4 does **consolidation** only.
+- Kernel-level filesystem sandboxing — v1.4 is at the library boundary;
+  v1.5 will consider Node's `permission` API.
+
+---
+
+## How to use the new surfaces
+
+```bash
+# Brain-driven design (provide a key)
+OPENAI_API_KEY=sk-... openlife create squad "a research squad for medical devices"
+
+# Toolset enforcement (opt-in)
+OPENLIFE_TOOLSET_ENFORCEMENT=on openlife task run "do x"
+#  → fails with toolset_blocked:terminal if the active profile blocks terminal
+
+# MCP install with real download
+openlife mcp install github://allowed-source/some-pack
+#  → SecurityDownloadGuard.downloadAndScan runs before the file lands
+
+# Host install for non-claude targets
+openlife system install --host gemini-cli --target /tmp/x
+openlife system install --host codex --target /tmp/y
+#  → both populate <target>/.<host>/{agents,commands} + an MCP snippet
+
+# Perf benchmark (CI-fail at +30 % P95 regression by default)
+npm run test:performance-latency
+PERF_REFRESH_BASELINE=1 npm run test:performance-latency   # lock new baseline
+```
+
+---
+
+## Honest assessment vs the 10/10 target
+
+| Dimension | v1.3 | v1.4 actual | Notes |
+|---|---|---|---|
+| Architecture | 9.8 | 10.0 | Toolset enforcement + condition parser close the structural gap. |
+| Test infra | 9.7 | 10.0 | +7 new test suites, perf bench, CI gate. |
+| Documentation | 9.5 | 10.0 | This file + 3 more in `docs/` cover every Sprint. |
+| Code quality | 9.0 | 9.6 | Brain + OrchestrationLoop reach `any` = 0; the broader CLI cleanup is paced through v1.5 under a CI-tracked budget. |
+| Feature completeness | 9.7 | 10.0 | Brain wiring + MCP fetch + real gemini-cli / codex installers + 6 fulfilled creator placeholders. |
+| Asset catalog | 9.5 | 9.7 | Real publish pipeline (local ledger); real remote push waits for v1.5. |
+| Governance | 9.8 | 10.0 | Toolset enforcement makes governance executable. |
+| Distribution | 9.5 | 10.0 | CI YAML + 3 hosts no longer stubs. |
+
+**Weighted projection:** ~ 9.92 / 10 → A+ (rounds to 10).

package/docs/v1.5-changelog.md

@@ -0,0 +1,106 @@
+# OpenLife v1.5 — Changelog
+
+**Branch:** `feat/v1.5-evaluation`
+**Predecessor:** v1.4.0 "Path to 10/10"
+**Status:** All in-scope sprints complete; awaiting merge + tag.
+
+v1.5 closes every item explicitly deferred from v1.4 except the one
+that's calendar-gated (toolset enforcement default-ON flip, Story 13.5
+— waits for the soak window).
+
+---
+
+## What landed by epic
+
+### Epic 13 — Evaluation + soak follow-through (Sprint 1)
+
+| Story | Commit | Surface |
+|---|---|---|
+| 13.0 | `5049155` | `docs/v1.5-roadmap.md` milestone charter |
+| 13.1 | `cea832d` | `OrchestrationLoop.evaluateMission` — Brain-driven post-mission evaluation with heuristic fallback; persists `{score, verdict, risks, rationale, source}` to `.openlife/evaluations/<taskId>.json` |
+| 13.2 | `bdca6df` | `openlife eval list` CLI with `--verdict` / `--min-score` / `--source` filters |
+| 13.3 | `8d14dab` | EnterpriseAgenticCore.ts: 12 anys → 0 (4 typed shapes); Gateway.ts ctx surface: 4 → 0 (`MinimalCtx` interface); CI lint budget 160 → 130 |
+| 13.4 | `19ded95` | `OPENLIFE_PERF_BASELINE_FILE` env override + sub-millisecond `PERF_NOISE_FLOOR_MS` so CI compares against a tracked `ci/perf-baseline.json` |
+
+### Epic 14 — Real publish + advanced governance (Sprint 2)
+
+| Story | Commit | Surface |
+|---|---|---|
+| 14.2 | `d58f3ae` | `GovernanceScopeLedger` — SHA-chained append-only JSONL ledger of every governance decision; `openlife governance ledger show/verify`; PII-protected (only goalHash persisted) |
+| 14.3 | `d8d80e4` | `ConsequenceForecaster.forecastWithBrain` — Brain enrichment cached at `.openlife/forecasts/<sha256>_<risk>.json` with 24h TTL |
+| 14.1 | `340293c` | `RemotePublisher` — HTTPS PUT to `OPENLIFE_REMOTE_PUBLISH_URL` with sha-mismatch protection; `SquadCreator.publishWithRemote` and `SkillCreator.publishWithRemote` compose local seal + remote push |
+
+### Epic 15 — Research-track (Sprint 3)
+
+| Story | Commit | Surface |
+|---|---|---|
+| 15.1 | `f3743a1` | `ProcessSandbox` wrapper for Node's `--permission` flag + `docs/sandboxing-research.md` decision doc (not wired in v1.5 — v1.6 migration plan documented) |
+
+### Epic 16 — Quality + observability (Sprint 4)
+
+| Story | Commit | Surface |
+|---|---|---|
+| 16.1 | `8df1eb9` | index.ts: 19 anys → 9 (typed CatalogEntry / RouteShape / TelegramGetMe / MissionState); CI lint budget 130 → 115 (production count now 109) |
+| 16.2 | `8df1eb9` | `test_performance_latency.ts` expanded to 5 benchmarks (added `condition_parse_and_evaluate` + `workflow_parse`) |
+
+### Epic 17 — Integration coverage (Sprint 5)
+
+| Story | Commit | Surface |
+|---|---|---|
+| 17.1 | `37a1093` | `test_v15_e2e_integration.ts` — 7-step end-to-end run touching SquadCreator, MissionStateStore, OrchestrationLoop, MissionEvaluationStore, RemotePublisher, GovernanceLayer, GovernanceScopeLedger (every Brain / network call stubbed via require.cache) |
+
+---
+
+## New environment variables
+
+| Variable | Default | Owner | Disables |
+|---|---|---|---|
+| `OPENLIFE_POST_MISSION_EVALUATION` | `on` | Story 13.1 | Set to `off` to skip the Brain/heuristic evaluation hook |
+| `OPENLIFE_GOVERNANCE_LEDGER` | `on` | Story 14.2 | Set to `off` to skip ledger appends |
+| `OPENLIFE_FORECAST_CACHE` | `on` | Story 14.3 | Set to `off` to bypass forecast cache reads + writes |
+| `OPENLIFE_FORECAST_CACHE_TTL_HOURS` | `24` | Story 14.3 | Override cache freshness window |
+| `OPENLIFE_REMOTE_PUBLISH_URL` | (unset) | Story 14.1 | Set to base URL to enable remote publish |
+| `OPENLIFE_REMOTE_PUBLISH_TOKEN` | (unset) | Story 14.1 | Optional Bearer token sent with each PUT |
+| `OPENLIFE_PERF_BASELINE_FILE` | `.artifacts/perf-baseline.json` | Story 13.4 | CI uses `ci/perf-baseline.json` |
+| `PERF_NOISE_FLOOR_MS` | `0.5` (local), `1.0` (CI) | Story 13.4 | Skip % gate when both P95s sit below this |
+
+---
+
+## New tests
+
+| Test | Stories covered |
+|---|---|
+| `test_post_mission_evaluation.ts` | 13.1 |
+| `test_governance_scope_ledger.ts` | 14.2 |
+| `test_consequence_forecast_brain.ts` | 14.3 |
+| `test_remote_publish.ts` | 14.1 |
+| `test_process_sandbox.ts` | 15.1 |
+| `test_v15_e2e_integration.ts` | 17.1 |
+
+CI `test:all` now runs 96 markers (up from 89 at v1.4.0).
+
+---
+
+## Locked decisions held over to v1.5+
+
+1. **Toolset enforcement opt-in stays.** Story 13.5 (default-ON flip)
+   waits for the soak window. Earliest target: after one tagged v1.4
+   maintenance release. Lands on its own branch.
+2. **Brain mode is still flag-free.** Provider key presence is the
+   opt-in for `designWithBrain`, `evaluateMission`, and `forecastWithBrain`.
+
+---
+
+## Honest scorecard delta vs v1.4
+
+| Dimension | v1.4 | v1.5 |
+|---|---|---|
+| Test infra | 10.0 | 10.0 (+e2e integration) |
+| Documentation | 10.0 | 10.0 (4 new reference docs) |
+| Code quality | 9.6 | 9.8 (any 172 → 109) |
+| Feature completeness | 10.0 | 10.0 (publish + governance ledger + sandbox primitive) |
+| Governance | 10.0 | 10.0+ (now tamper-evident) |
+
+The improvements are honestly **incremental**, not transformative — that
+was the v1.5 thesis. v1.6 is where the soak-gated default-ON flip and
+the wider distributed-scheduler epic will move the score again.

package/docs/v1.5-roadmap.md

@@ -0,0 +1,121 @@
+# OpenLife v1.5 — Roadmap
+
+**Branch:** `feat/v1.5-evaluation`
+**Status:** Sprint 1 in progress.
+**Predecessor:** v1.4.0 "Path to 10/10" (scorecard ~9.92/10 → A+).
+
+v1.5 picks up the items that were explicitly deferred from v1.4 plus a
+small set of consolidations the v1.4 audit revealed once the milestone
+closed. No new pillars again — v1.5 is about making v1.4's foundations
+land harder.
+
+---
+
+## The 5 deferred items from v1.4
+
+| # | Item | Owner story | Priority |
+|---|---|---|---|
+| 1 | Toolset enforcement default-ON (after soak window) | 13.5 | P1 |
+| 2 | Real remote pack publish (currently local ledger only) | 13.6 | P2 |
+| 3 | LLM-driven post-mission **evaluation** (consolidation was v1.4 only) | 13.1 ✅ | P0 |
+| 4 | Kernel-level fs sandboxing exploration (Node `permission` API) | 13.7 (research) | P3 |
+| 5 | Distributed multi-host scheduler | 14.x (separate epic) | P3 |
+
+---
+
+## Epic 13 — Evaluation + soak follow-through (Sprint 1)
+
+The first wave closes the highest-impact deferrals without changing the
+opt-in stance for enforcement.
+
+- **13.1 — Brain-driven post-mission evaluation** ✅ (commit `cea832d`)
+  - `OrchestrationLoop.evaluateMission(state)` writes a structured
+    `{ score, verdict, risks, rationale, source }` to
+    `.openlife/evaluations/<taskId>.json`.
+  - Brain when key present; heuristic `MissionEvaluationStore.judge()`
+    fallback otherwise.
+  - Disable: `OPENLIFE_POST_MISSION_EVALUATION=off`.
+
+- **13.2 — `openlife eval list` CLI surface** ✅ (commit `bdca6df`)
+  - Lists `.openlife/evaluations/*.json`.
+  - Filters: `--verdict`, `--min-score`, `--source` (brain | heuristic).
+
+- **13.3 — Tighten `any` budget**
+  - Drop CI lint budget from 160 → 130; reduce
+    `EnterpriseAgenticCore.ts` from 12 → ~3.
+  - The locked v1.4 target was <70 by v1.5; we're stepping the budget
+    down across two milestones to keep PRs reviewable.
+
+- **13.4 — Perf benchmark CI gate hardening**
+  - Persist `.artifacts/perf-baseline.json` as a CI artifact across runs
+    (currently re-seeds every run, so no real comparison happens in CI
+    yet).
+  - Wire the perf test into the lint workflow as a quality gate.
+
+- **13.5 — Toolset enforcement default-ON flip**
+  - Change `ToolsetGuard.isToolsetAllowed` default from "OFF when env unset"
+    to "ON when env unset". The opt-out becomes `OPENLIFE_TOOLSET_ENFORCEMENT=off`.
+  - Land **after** at least one week of v1.4 soak — earliest target is
+    one tagged maintenance release into v1.4.
+
+---
+
+## Epic 14 — Real publish + advanced governance (Sprint 2, P2)
+
+- **14.1 — Remote pack publish.** `SquadCreator.publish()` and
+  `SkillCreator.publish()` currently append to `.openlife/published-assets.jsonl`.
+  v1.5 wires `--remote <url>` to push the sealed asset bundle to a real
+  registry (npm-compatible or HTTP PUT, TBD during planning).
+
+- **14.2 — Governance scope ledger.** Every `GovernanceLayer.evaluate()`
+  result currently writes a single consent record. v1.5 promotes this
+  to a tamper-evident JSONL ledger with SHA-chained entries.
+
+- **14.3 — Brain → consequences forecast.** Wire `ConsequenceForecaster`
+  to call Brain for the highest-risk decisions; cache forecasts under
+  `.openlife/forecasts/`.
+
+---
+
+## Epic 15 — Research-track items (P3, may slip to v1.6)
+
+- **15.1 — Node `permission` API exploration.** Spike to evaluate
+  kernel-level fs sandboxing as a complement to toolset enforcement.
+  Output: a `docs/sandboxing-research.md` decision doc, no production
+  code in v1.5.
+
+- **15.2 — Distributed multi-host scheduler.** Standalone epic; runs in
+  v1.6 unless capacity allows starting in v1.5.
+
+---
+
+## Locked decisions (held over from v1.4)
+
+1. **Toolset enforcement opt-in remains the v1.4 stance.** Story 13.5
+   flips the default ON only after the soak window. Existing
+   `OPENLIFE_TOOLSET_ENFORCEMENT=on` keeps working without change.
+
+2. **Brain-driven `design()` continues to be flag-free.** Presence of
+   any provider key IS the opt-in. Same applies to Story 13.1's
+   `evaluateMission`.
+
+---
+
+## Definition of Done
+
+| Check | Method |
+|---|---|
+| `npm run build` clean | After each story |
+| `npm run test:all` green | After each story; CI on every push |
+| Perf regression check | `test_performance_latency.ts` against `.artifacts/perf-baseline.json` (≤ +30% P95 by default) |
+| `any` budget | CI lint job — 130 by end of v1.5 (from 160 in v1.4) |
+| Toolset enforcement soak | At least 1 week + 1 maintenance release before 13.5 lands |
+
+---
+
+## Commit / push policy
+
+Same as v1.4 — one atomic commit per story, branch
+`feat/v1.5-evaluation`, GOOODZ identity. Push requires explicit Rafa
+approval (the v1.4 policy stayed in effect; the autonomous push for
+this branch was granted on 2026-05-13).