feat: manage Codex native user-wide statusline

MAINTAINER.md

@@ -25,7 +25,7 @@ release this kit. User-facing docs live in [README.md](README.md); this file is
 ### CLI shape (`bin/agentic-kit.mjs`)
 
 - **Porcelain** (daily): `setup`, `status`, `sync`, `dashboard`, `admin`, `dual`, `uninstall`. Bare `ak` → `status --hint`. (`dashboard` and `admin` are also reachable as `ak x dashboard` / `ak x admin`.)
-- **Plumbing** (power users): `ak x daemon-gc | mcp | reference | verify | improvement-eval`.
+- **Plumbing** (power users): `ak x daemon-gc | mcp | reference | statusline | verify | improvement-eval`.
 - Each command module exports `options` (a `parseArgs` config) and `run({ flags, positionals, pkgRoot })`.
 - A best-effort drift nudge runs after non-`sync`, non-`--json` commands.
 
@@ -39,7 +39,7 @@ src/
   commands/              # porcelain verbs
     setup.mjs  status.mjs  sync.mjs  dual.mjs  uninstall.mjs
     x/                   # plumbing verbs
-      admin.mjs  daemon-gc.mjs  dashboard.mjs  harvest.mjs  mcp.mjs  provider.mjs  reference.mjs  verify.mjs
+      admin.mjs  daemon-gc.mjs  dashboard.mjs  harvest.mjs  mcp.mjs  provider.mjs  reference.mjs  statusline.mjs  verify.mjs
   lib/                   # the engine — each file is one concern
     heal.mjs             # the mutations sync/setup apply (idempotent, {ok,detail})
     natives.mjs          # better-sqlite3 / agentdb native detection
@@ -48,6 +48,7 @@ src/
     ruvnet-brain.mjs     # RuvNet Brain: on-disk detection + GitHub-release drift (NOT an npm pkg)
     blocks.mjs           # managed-block registry + syncBlocks + guidanceTargets (3 targets: ~/.claude/CLAUDE.md, project AGENTS.md, ~/.codex/AGENTS.md)
     hosts.mjs            # host-adapter core: drivingHost() + HOST_ADAPTERS (guidance file, auth, statusline)
+    codex-statusline.mjs # owned presets + narrow ~/.codex/config.toml projection
     providers.mjs        # frontier-host + LLM-provider detect/wire (hosts, auth, MCP bridges, aqe router)
     routing.mjs          # pure dual-host routing policy: defaults, projections, primary-host swap
     qeCourt.mjs          # qe-court vendor-diversity panel helpers
@@ -92,6 +93,17 @@ wiring, both MCP-bridge directions, aqe router file). Seeded/healed by `setup` +
 `sync` + `x provider pick`, surfaced by `status` + `dashboard`. Design records:
 ADRs [0001–0006](docs/adr/); user guide: `docs/PROVIDERS.md`.
 
+**Status-line capability is host-specific.** Claude owns a project-scoped,
+command-backed renderer; Codex offers a user-scoped, built-in field list.
+`ak x statusline codex native|extended` explicitly opts the user into management
+of only `tui.status_line` and `tui.status_line_use_colors`; `sync` must not touch
+those keys without that ownership record. The textual TOML merge is
+backup-first and must preserve unknown keys, comments, ordering, and newline
+style. `off` and uninstall remove each key only if its managed value is
+unchanged. See
+[the Codex status-line guide](docs/CODEX-STATUSLINE.md) and
+[ADR-0015](docs/adr/0015-managed-codex-native-statusline.md).
+
 > The consistency contract all managed tools share — install/update/version/display
 > invariants, the per-tool table, and the add-a-tool checklist — lives in
 > [docs/MANAGED-TOOLS.md](docs/MANAGED-TOOLS.md). The notes below are the

README.md

@@ -52,6 +52,7 @@ ak sync         converge to good: upgrade + heal + verify          [--dry-run] [
 ak dashboard    open the local web dashboard (auto-opens your browser)
                 [--port N] [--no-open] [--live-source 'surface=path']
 ak dual         run a Claude+Codex collaboration swarm (dual-host)   run <template> "<task>"  [--dry-run] [--escalate] [--route ...]
+ak x statusline manage Codex's native user-wide status line          status | codex native|extended|off
 ak uninstall    leave cleanly                [--dry-run] [--this-project] [--remove-ruflo] [--remove-aqe] [--purge] [--yes]
 ```
 
@@ -77,6 +78,7 @@ What the verbs cover:
 
 Power-user mechanisms live under `ak x …` (`daemon-gc`, `harvest`,
 `mcp pick|off`, `provider status|pick|off`, `reference diff|sync`,
+`statusline status|codex native|extended|off`,
 `verify learning|security|aqe|providers|harvest`, `improvement-eval`) — see `ak --help --all`.
 
 One of those is worth calling out:
@@ -94,6 +96,14 @@ each segment shown **only when genuinely active**: 🧠 SONA patterns/trajectori
 live micro-LoRA Δ‖W‖), 📈 route-RL metrics, 🛡 aidefence, 🧿 RuvNet Brain KB,
 ⚙ machine-wide daemon count, and 🎓 Agentic-QE stats.
 
+That rich, command-backed footer is a Claude Code surface. Codex supports a
+single native line made from built-in fields instead. Opt into a compact
+machine-wide preset with `ak x statusline codex native` (or use `extended` on
+a wide terminal); `ak sync` then keeps the selected preset converged without
+rewriting unrelated `~/.codex/config.toml` settings. See
+[Managed Codex status line](docs/CODEX-STATUSLINE.md) for fields, ownership,
+rollback, and the current parity boundary.
+
 ## Requirements
 
 Node ≥ 22, npm, and the `claude` CLI (Claude Code). That's the whole list —

bin/agentic-kit.mjs

@@ -33,6 +33,7 @@ const PLUMBING = Object.assign(Object.create(null), {
   'mcp': () => import('../src/commands/x/mcp.mjs'),
   'provider': () => import('../src/commands/x/provider.mjs'),
   'reference': () => import('../src/commands/x/reference.mjs'),
+  'statusline': () => import('../src/commands/x/statusline.mjs'),
   'verify': () => import('../src/commands/x/verify.mjs'),
 });
 
@@ -68,6 +69,7 @@ Plumbing (power users) — each takes --help:
   ak x mcp [status|pick|off]   MCP registration + tool-family deny rules
   ak x provider [status|pick|off]   detect claude/codex CLIs; wire ruflo + aqe hosts/providers
   ak x reference [diff|sync]   CLAUDE.md managed-block inspection/reconcile
+  ak x statusline [status|codex native|codex extended|codex off]   manage Codex's native user status line
   ak x verify [learning|security|aqe|providers|harvest|all]   deep proofs (slow, spawns real CLIs)
   ak x improvement-eval [...]  causal self-improvement eval (route Q-learner)`;
 

docs/CODEX-STATUSLINE.md

@@ -0,0 +1,106 @@
+# Managed Codex status line
+
+Codex has a native, user-wide status line. Agentic-kit can manage a useful
+preset for every newly started Codex session while preserving the rest of
+`~/.codex/config.toml`.
+
+This is intentionally different from the rich Claude Code footer. Codex's
+native line is single-line and accepts only Codex's built-in fields. Ruflo,
+SONA, route-RL, daemon, RuvNet Brain, and Agentic QE segments cannot appear
+inside it until Codex provides a command or plugin-backed extension point.
+
+## Choose a preset
+
+```bash
+# Inspect agentic-kit's ownership and the current Codex configuration.
+ak x statusline status
+
+# Recommended: compact enough for an ordinary terminal.
+ak x statusline codex native
+
+# Add operational fields for a wide terminal.
+ak x statusline codex extended
+
+# Stop managing the Codex status line.
+ak x statusline codex off
+```
+
+`native` selects:
+
+```text
+model-with-reasoning, project-name, git-branch, run-state,
+context-remaining, five-hour-limit, weekly-limit, task-progress
+```
+
+`extended` adds:
+
+```text
+permissions, approval-mode, used-tokens, fast-mode, thread-id, codex-version
+```
+
+The setting is machine/user scoped rather than repository scoped. Start a new
+Codex session after changing it; an already-running TUI may not reload the
+configuration.
+
+## Ownership and sync
+
+Selecting `native` or `extended` records explicit ownership in agentic-kit's
+machine configuration. From then on, `ak status` reports drift and `ak sync`
+reconciles the selected preset.
+
+Agentic-kit narrowly updates only these keys under `[tui]`:
+
+```toml
+[tui]
+status_line_use_colors = true
+status_line = [
+  "model-with-reasoning",
+  "project-name",
+  "git-branch",
+  "run-state",
+  "context-remaining",
+  "five-hour-limit",
+  "weekly-limit",
+  "task-progress",
+]
+```
+
+Other tables, keys, comments, ordering, and newline style in
+`~/.codex/config.toml` are preserved. A backup is made before a managed write.
+If no preset is owned, `ak status` may describe a native configuration but
+`ak sync` leaves it alone.
+
+The narrow writer fails closed on TOML-equivalent quoted table/key syntax or
+dotted `tui.status_line` keys instead of risking a duplicate semantic key.
+Normalize those forms to the conventional `[tui]` table before opting in.
+
+`off` relinquishes ownership. Each managed key is removed only when its value
+still matches the last managed projection; an edited key is preserved as user
+state. Uninstall follows the same rule.
+
+## What each host can display
+
+| Capability | Claude Code | Codex |
+|---|---:|---:|
+| Configuration scope | Project | User/machine |
+| Native single-line fields | Host-dependent | Yes |
+| Command-backed renderer | Yes | No |
+| Multiple rich telemetry lines | Yes | No |
+| Managed by `ak sync` | Yes | After explicit preset selection |
+
+For Claude Code, agentic-kit continues to inject its rich renderer into the
+project's ruflo status-line helper. The Codex preset complements that renderer;
+it does not attempt to claim visual or telemetry parity.
+
+## Troubleshooting
+
+- **The line did not change:** exit and start a new Codex session.
+- **The right side is missing:** use `native`, or widen the terminal. Codex
+  renders one width-constrained line.
+- **`ak status` reports drift:** run `ak sync` to restore the owned preset, or
+  run `ak x statusline codex off` before maintaining the keys yourself.
+- **You need the rich subsystem display:** use Claude Code's project footer for
+  now. Hooks and notifications are event messages, not a persistent Codex UI.
+
+The design and safety constraints are recorded in
+[ADR-0015](adr/0015-managed-codex-native-statusline.md).

docs/TROUBLESHOOTING.md

@@ -22,6 +22,9 @@ ak sync             # apply it
 | `status` shows `aidefence missing` | ruflo ≥3.28 stopped shipping `@claude-flow/aidefence` but `ruflo security defend` still imports it — injection defense is silently non-functional ([ruvnet/ruflo#2670](https://github.com/ruvnet/ruflo/issues/2670)) | `ak sync` reinstalls it; `ak x verify security` proves defend works (exit 1=threat / 0=clean) |
 | `status` shows oversized RVF store(s) | A runaway append after a hard exit grew a `.rvf` past the 2 GB cap (seen at ~277 GB once) | `ak sync` quarantines the oversized store; agentic-qe rebuilds it |
 | Statusline footer (🧠/🛡/🎓 lines) disappeared | `@claude-flow/cli`'s version-stamped helper auto-refresh pristine-copies `statusline.cjs` on the **first ruflo command after an upgrade** — including the statusline render itself | `ak sync` — it now triggers that refresh *first*, then re-injects, so the footer survives; `ak status` flags an armed wipe before it fires |
+| Codex's native status line did not change | Codex reads the user-wide setting when a session starts; an existing TUI may not hot-reload it | Exit and start a new Codex session; inspect ownership with `ak x statusline status` and drift with `ak status` |
+| The right side of Codex's status line is missing | Codex has one width-constrained native line | Widen the terminal or choose the compact preset with `ak x statusline codex native` |
+| Want the rich Ruflo/SONA/AQE display inside Codex | Codex currently accepts built-in status-line fields only, not a command-backed renderer | Keep the rich footer in Claude Code; see [Managed Codex status line](CODEX-STATUSLINE.md) for the current boundary |
 | Too many `⚙` daemons / stale daemons | One daemon per active project is normal (local-only workers, $0). Stale = workspace deleted or past the 12h TTL | `ak x daemon-gc --kill`; `sync` also reaps (and verifies the pid really is a ruflo daemon before killing) |
 | Want to change which MCP tool families are callable | Exclusions are `permissions.deny` rules, persisted in kit.json | `ak x mcp pick` (re-runnable); `x mcp status` shows the inventory; `x mcp off` unregisters |
 | `ruflo memory store` says OK but reads return nothing | Absolute-DB-path pin missing, or WAL not checkpointed, or the WASM fallback above | `ak setup` in the project re-pins + verifies a real write lands on disk |

docs/UPGRADING.md

@@ -23,12 +23,19 @@ family on your behalf.
 | -------------------- | ----------------------------------------------- | -------------------------------- |
 | `ak sync`            | update the binary + heal to your recorded state | **no** — converges, never decides |
 | `ak x provider pick` | opt into / retune hosts & LLM providers         | **yes** — this is the switch     |
+| `ak x statusline codex native\|extended` | opt into a user-wide Codex status-line preset | **yes** — records the preset |
 | `ak setup`           | first-time bootstrap of absent tooling          | only via explicit flags (`--codex`, `--primary-host`) |
 
 If you already have `ak` working, you almost never need `ak setup` again — it's the
 installer. Enabling a shipped-but-opt-in feature is a `provider pick` (or an `x mcp pick`,
 etc.), not a re-`setup`.
 
+Codex status-line management is deliberately not enabled merely because an
+upgrade adds support for it. Run `ak x statusline codex native` once to opt in;
+later `ak sync` runs converge that recorded choice. Use
+`ak x statusline codex off` to relinquish ownership. See
+[Managed Codex status line](CODEX-STATUSLINE.md).
+
 ## Worked example: adopting ambidextrous dual-host
 
 You have an older `ak` and both the `claude` and `codex` CLIs installed, and you want the

docs/adr/0015-managed-codex-native-statusline.md

@@ -0,0 +1,139 @@
+# ADR-0015 — Manage Codex's native user-wide status line without claiming rich-renderer parity
+
+- **Status:** Accepted
+- **Date:** 2026-07-28
+- **Deciders:** agentic-kit maintainers
+- **Related:** [ADR-0001](0001-one-routing-policy-many-projections.md),
+  [ADR-0006](0006-primary-host-and-ambidextrous-mirroring.md),
+  [ADR-0008](0008-guidance-target-scope-split.md),
+  [ADR-0010](0010-provider-mediated-quota-reads.md)
+
+## Context
+
+Agentic-kit gives Claude Code a rich, project-scoped status display by repairing ruflo's
+`.claude/helpers/statusline.cjs`, injecting `src/templates/statusline-footer.cjs`, and pointing
+Claude Code's command-backed `statusLine` setting at that renderer. The footer can read local
+ruflo, SONA, reinforcement-learning, daemon, RuvNet Brain, and agentic-qe state and render several
+ANSI-styled lines.
+
+Codex CLI has a different extension boundary. Codex 0.145.0 exposes `/statusline` and the
+user-scoped `tui.status_line` array in `~/.codex/config.toml`. The array selects from native item
+identifiers such as model, project, Git branch, run state, context remaining, five-hour and weekly
+limits, token totals, and task progress. It is a single native line. Codex does not accept a
+command-backed item, arbitrary text, custom ANSI output, or multiple renderer-owned lines.
+OpenAI tracks command/plugin-backed status-line support as an upstream feature request.
+
+The repository currently reduces this distinction to `statuslineSupported: false` for Codex and
+reports that the statusline is Claude-only. That is accurate for the rich command-backed renderer
+but no longer accurate for Codex's native declarative status line. It also leaves every Codex user
+to configure the same useful baseline by hand.
+
+`~/.codex/config.toml` is shared user state. It contains project trust, MCP registrations, user
+preferences, and possibly fields introduced by newer Codex releases. Agentic-kit must not parse and
+rewrite the whole document with an incomplete TOML model or silently seize a list the user already
+curated.
+
+## Decision
+
+### 1. Model status-line capability, not a boolean
+
+Host adapters distinguish three properties:
+
+- whether the host has a status line;
+- whether it accepts a command-backed custom renderer;
+- whether its configuration is project- or user-scoped.
+
+Claude remains `command` plus project scope. Codex becomes `builtin` plus user scope. User-facing
+status output says that Codex supports a managed native line while rich ruflo/SONA/AQE segments
+remain unavailable inside the Codex TUI.
+
+### 2. Add explicit managed Codex presets
+
+Agentic-kit provides an `ak x statusline` command with:
+
+```text
+ak x statusline status
+ak x statusline codex native
+ak x statusline codex extended
+ak x statusline codex off
+```
+
+`native` is the recommended compact preset:
+
+```text
+model-with-reasoning, project-name, git-branch, run-state,
+context-remaining, five-hour-limit, weekly-limit, task-progress
+```
+
+`extended` adds operational fields that are useful on wide terminals:
+
+```text
+permissions, approval-mode, used-tokens, fast-mode, thread-id, codex-version
+```
+
+The command is user/machine scoped because Codex reads `~/.codex/config.toml` for all sessions.
+Changes apply to newly started Codex sessions; a running TUI need not hot-reload them.
+
+### 3. Ownership is explicit and reversible
+
+Selecting `native` or `extended` records the chosen preset in `kit.json`. Only then may `ak sync`
+reconcile `tui.status_line` and `tui.status_line_use_colors`. `off` removes agentic-kit's ownership
+and removes only the two managed keys when their values still equal the last managed projection.
+It does not delete the `[tui]` table or unrelated user settings.
+
+If Codex or the user changes the managed values, `ak status` reports drift and `ak sync` restores the
+selected preset. If no preset is owned, status may describe the detected native configuration but
+must not propose a mutating fix.
+
+Uninstall follows the same ownership rule and never removes an unowned status line.
+
+### 4. Patch only the owned TOML keys
+
+The writer performs a narrow, backup-first, atomic textual merge of the two keys inside `[tui]`.
+It preserves comments, ordering, newline style, every other table, and every unknown key. It must
+recognize multiline arrays because `/statusline` may write one. It validates the resulting file
+before replacement using Codex's own configuration loader when a safe non-interactive validation
+path is available; otherwise structural tests and a rollback-on-write-failure boundary are
+mandatory.
+
+Agentic-kit remains zero-runtime-dependency. Adding a general TOML dependency solely for these two
+keys is rejected.
+
+### 5. Keep rich telemetry host-neutral, but outside this change
+
+The existing ruflo/SONA/RL/daemon/Brain/AQE footer remains Claude-backed. A later change may extract
+its filesystem probes into:
+
+```text
+ak statusline render --host codex --format ansi|json
+```
+
+for tmux, Zellij, shell prompts, an adjacent pane, or a future Codex command-backed item. This ADR
+does not add a terminal wrapper, patch the Codex binary, claim hooks are persistent UI, or maintain
+a private Codex fork.
+
+## Consequences
+
+- Codex users get a consistent, colored, machine-wide native status line through the same
+  status/sync drift model as the rest of agentic-kit.
+- The UI immediately exposes model, repository, execution state, context headroom, plan headroom,
+  and task progress without an external process.
+- Ruflo, SONA, RL, daemon, Brain, and agentic-qe telemetry cannot appear in Codex's native line until
+  Codex adds an extension point. Documentation states that boundary directly.
+- The implementation needs focused tests for absent `[tui]`, existing `[tui]`, multiline arrays,
+  CRLF, comments, duplicate/invalid structures, ownership, drift, sync, off, and uninstall.
+- Preset identifiers are version-sensitive. The compact preset uses fields verified in Codex
+  0.145.0; future incompatible Codex changes surface as drift/validation failures rather than
+  destructive fallback rewrites.
+
+## Rejected alternatives
+
+- **Reuse Claude's `statusline.cjs` directly.** Codex has no command-backed status-line item.
+- **Configure every available native item.** Codex renders one width-constrained line; later fields
+  become invisible on ordinary terminals.
+- **Always overwrite `~/.codex/config.toml` during setup or sync.** That would convert a convenience
+  into ownership of unrelated user state.
+- **Use hooks or `notify` as the renderer.** They produce event notifications, not a persistent
+  status surface.
+- **Rewrite the entire TOML document.** It risks losing comments and newer Codex fields and violates
+  the repository's merge-not-clobber rule.