epic: Cortex v0.9.0 — stable local tool for coding agents

Goal

Ship Cortex v0.9.0 by 2026-09-30 as a tool our own team runs every day alongside their
coding agent. This is an internal release: the bar is stability and daily usability, not
market positioning.

Our current product priority is observability — token usage, cost, latency, and what the
agent actually sent. Cost reduction (tool-definition pruning) ships and stays supported, but
the release is judged on whether the numbers Cortex shows are correct, complete, and still
there tomorrow.

Exit bar

The release ships when all five hold:

1. Install works cold. curl | sh → abctl observe → claude succeeds from a clean
   machine on macOS arm64, macOS amd64, Linux amd64, Linux arm64. macOS is the primary
   workstation target — the others must work, but macOS is what most of the team runs.
2. Cortex is invisible to everything else. With the service running and the CA trusted,
   git, gh, ssh, curl and ordinary shell scripts behave exactly as they do without it.
3. The numbers are right and they persist. A full session shows correct token counts
   (input / cache-read / cache-write / output), cost, and latency; the data survives
   abctl service restart.
4. No known P0 bugs. #926 and #912 are closed with regression tests.
5. A new user can self-serve. Someone who has not used Cortex before installs it on a stock
   macOS workstation following the docs alone — no tribal knowledge, nobody to ask — and can
   then say what Cortex is for, what the numbers mean, and why it is worth leaving running. The
   install is easy to follow, not merely possible. Documentation covers installing, using it
   day to day, interpreting the results, and the value the tool brings. Verified by at least one
   person outside the team who has not installed it before.

Non-goals

Tracked separately, deliberately out of this release:

• Runtime-extensible / no-PR plugin model (#721)
• Enterprise dashboard (#872)
• Identity, authz and platform work (#905, #758, #506, #508, #647, #658, #683, #681, #398, #341)
• Multi-user session correlation through Envoy/ext-proc (#182) — a Kubernetes concern, not
  the laptop tool. Local session differentiation is #949
• Kubernetes-mode feature work: the sidecar / SPIRE / Keycloak paths keep working, they are
  just not where the release effort goes

Release mechanics

Superseded 2026-10-02. The plan said binaries would jump from v0.7.0-alpha.N straight to
v0.9.0 with no v0.8.0. That is not what happened: v0.7.0 shipped non-prerelease on 2026-09-24,
then v0.8.0 and v0.8.1 on 2026-10-01, with v0.8.1 marked latest. v0.9.0 is now planned for
end of October. Docs verification that was gated on a v0.9.0 binary has been retargeted at
v0.8.1 — see #959 and #960.

• Confirm a non-prerelease / latest build publishes — done for v0.8.1
• Confirm what install.sh with no --ref resolves to. Note the premise above is wrong:
  scripts/install.sh deliberately does not use releases/latest (it excludes
  prereleases, and this project ships them) — it lists releases newest-first including
  prereleases. So marking a release non-prerelease is not what makes the installer pick it up,
  and main-latest is still present. Worth settling before v0.9.0.

Owners

Area	Owner
macOS install, proxy bugs, metrics backend, persistence, refactor	@huang195
Agent integrations, abctl / TUI, unattended workloads	@esnible
Session differentiation	@galmasi
Linux install, release smoke tests, reboot verification, CI	@Alan-Cha
Docs	@mrsabath

Release-blocking — P0 (27)

Agent support

• #939 Agent integration contract — reusable detection, settings patching, revert
• #940 Claude Code — verify and harden the reference integration
• #941 OpenCode support
• #943 Bob support

Install & service lifecycle

• #944 Verified macOS install and launchd service lifecycle
• #945 Verified Linux install and systemd service lifecycle
• #964 Verify the installed service survives reboot on macOS and Linux
• #966 Minimize the desktop release artifact — fixed plugin set for desktop use

Not breaking the rest of the machine

• #946 git, gh and ssh keep working with Cortex running
• #947 Language toolchains and scripted HTTPS clients keep working

Session differentiation

• #949 Differentiate concurrent coding-agent sessions in abctl

Observability

• #950 Per-session and per-model token and cost aggregation
• #951 Latency metrics — time to first token, total response time, session percentiles
• #953 Metrics view in the abctl TUI
• #900 No token showing for requests in abctl

Persistence & configuration

• #901 Persist sessions — sqlite backend
• #954 Persistent user configuration for abctl

Unattended operation

• #955 Support unattended agent workloads — headless agent runs with no human present

TUI stabilization

• #870 Better user help for disappearing events
• #865 Sort events other than chronologically

Bugs

• #926 Early flush of leading thinking block → client stream-idle timeout
• #912 TLS bridge auto-skip → 10-minute intermittent CA failures

Release testing

• #956 Release smoke test on macOS CI runners
• #957 Release smoke test on Linux CI runners

Docs

• #959 First-run path — install to first useful reading (closed 2026-10-02; verified against v0.8.1 in rossoctl/rossoctl#2615)

• #960 Troubleshooting guide for the laptop install (closed 2026-10-02; verified against v0.8.1 in rossoctl/rossoctl#2615)

• #963 Explain what Cortex shows and why it is worth running — interpreting the metrics
  and the value case. Prose complete and verified against v0.8.1; blocked only on #951
  (v0.8.1 has no time-to-first-token and no percentiles, so the latency content and the
  worked-example capture cannot be finished) plus the outside-reader pass.

• #1236 Document agentop configure claude-code — enable, disable, status (new 2026-10-02)

• #1237 Document agentop configure bob and agentop configure bobshell (new 2026-10-02)

  Both ship in v0.8.1 and have no user-facing page; split out of #959 rather than widening it.

Stretch — P1 (13)

• #942 Codex support
• #1002 Cortex being down can break the harness — routing stays configured when the service
  is not listening (unowned; adopted into the plan 2026-09-22, see the status note below)
• #952 Attribute tool-pruning savings — tokens and cost saved
• #961 Separate laptop docs from Kubernetes and platform docs (shipped in rossoctl/rossoctl#2551)
• #958 CI coverage gate for abctl and authbridge-proxy
• #898 Report statistics to a central collector
• #906 Better information for non-LLM/A2A/MCP traffic
• #724 Surfacing outbound pipeline denials
• #914 make targets for building abctl and authbridge-proxy
• #867 Explanation of / (filter) function
• #868 Slow down y (yank) screen clearing
• #844 Help Context Guru end users understand what it does
• #913 abctl exec — verify and close, appears already implemented

Adopted after the plan was written (3, all closed)

Attached to this epic as sub-issues after the P0/P1 lists were drawn, so they were never priced
into either count. Recorded here rather than folded into P0, which would make the "N of 27" series
above incomparable with itself.

• #1018 Session titles instead of bare UUIDs in abctl (#1052, #1056, #1085)
• #984 Give plugins the same per-session identity that recording gets (#989)
• #971 abctl event-picker highlight lost when new events arrive (#981)

Not in this release

• #682 Refactor: separate proxy data-planes. Missed its hard merge cutoff of 2026-09-19 with
  nothing merged, so by the rule the epic set for it, it has left the release. It is a native
  sub-issue of #2244 (epic: Cortex Phase 1) and stays tracked there — it was never a sub-issue of
  this epic, only a reference in the stretch list. Its scope is also stale: the shared-shim-layer
  approach was rejected in favour of in-process policy plus a thin interception front, so it needs
  rescoping or superseding before anyone picks it up.

Post-v0.9.0 — brainstorm backlog (4)

From a team brainstorming session, September 2026. None of these are in scope for v0.9.0 and
none affect the exit bar — they are parked here so the ideas stay attached to the product rather
than getting lost, and they can be reparented once a routing epic exists. Each carries the
open questions the idea has not yet answered.

• #1022 URL-level egress visibility — show every external destination the agent reaches
  (@maia-iyer). Builds on #906; enforcement counterpart is #724
• #1019 Transparent model and provider switching across a limit, price or policy boundary
  (@rubambiza). The largest of the four; needs a provider wire-format abstraction
• #1020 Route by task class — cheaper model when the prompt does not need an expensive one
  (@galmasi)
• #1021 Shadow a request against a second model to measure where the cheap model suffices —
  and possibly a Cortex-native benchmark built from captured traffic (@aslom, @galmasi)

#1020 and #1021 both depend on the switching mechanism in #1019; #1021 is what would
supply the evidence for #1020's default routing table, and #1019/#1021 both need per-model
cost attribution from #950. #1021's captured-traffic benchmark also depends on #901 and needs a
redaction and consent story scoped before any corpus exists.

Critical paths

Two dependency chains, both spanning more than one owner. Neither parallelizes.

#939 agent contract  ──┬── #940 Claude Code (reimplemented on it)
                       ├── #941 OpenCode
                       ├── #943 Bob
                       └── #942 Codex (P1)

#949 session identity ──┬── #950 token/cost aggregation ── #953 TUI metrics view
                        └── #955 unattended workloads

#949 is owned by @galmasi, #950 by @huang195, #953 and #955 by @esnible. The
session-identity schema needs agreeing in week one, not discovering in week three.

Risks

• 27 P0 items, three weeks, five people. Every P0 has an owner. Several are small, but
  #939/#941/#943, #950/#951/#953, #944/#945 and #949 are not.
• Exit criterion 5 lands last by construction. #963 explains what the metrics mean, so it
  cannot be finished before #950/#951/#952 do, and the outside-reader verification cannot start
  before #963. Whoever is going to read the docs cold should be lined up in advance, or the
  criterion becomes a rubber stamp in the final days.
• @esnible holds 10 of the 24 P0 items, spanning agent integrations and TUI stabilization —
  two workstreams that do not interleave. The heaviest load in the plan.
• #682 landing late. Retired 2026-09-22 — the cutoff passed with nothing merged, so the
  refactor left the release rather than landing in the final week. See Not in this release.
• All 5 remaining unowned issues are P1 (#898, #724, #867, #844, #1002), so nothing unowned
  gates the release. #1002 is the one to revisit if that stops being acceptable: it is a bug a user
  hits by leaving Cortex installed, and it is unowned only because nothing unowned may be P0.

Open questions

• Owners for #898, #724, #867, #844, #1002 (all P1). #906, #914 and #868 are closed and have
  dropped off this list
• Confirm v0.9.0 publishes as non-prerelease so install.sh defaults to it
• #943: Bob's wire format and settings location need capturing before implementation

Status — 2026-09-16 (progress reconciliation)

Checkbox state above reconciled against actual issue state. P0: 6 of 27 closed. The P0 and P1
counts are unchanged by the new Post-v0.9.0 — brainstorm backlog section (#1022, #1019, #1020,
#1021), which is deliberately outside the release scope and the exit bar.

• Closed since the epic was written: #966, #949, #900, #870 (P0); #906, #868, #914 (P1).
• Docs (#959, #960, #963, #961): the prose is written and merged in
  rossoctl/rossoctl#2551, but the issues stay
  open here. #959, #960 and #961 are drafted and checked in the list above; #963 stays open because the value
  case still carries 5 VERIFY v0.9.0 markers and placeholder worked-example figures that depend
  on the metrics work (#950/#951/#952) landing, and the outside-reader verification (exit
  criterion 5) has not run. Additional docs shipped: the RossoCortex value rewrite
  (rossoctl/rossoctl#2564) and three feedback
  surfaces (cortex #975 abctl footer, #977 issue form + docs prompt).
• Still open and load-bearing for the release: the metrics chain #950 → #951/#953 (plus #952
  for pruning savings), install/lifecycle #944/#945/#946/#947, and the P0 bugs #926/#912.

Status — 2026-09-22 (closure pass)

Every issue in the lists above re-checked against issue state, cross-referenced PRs, and the tree at
84e16ef3, and the body reconciled against this epic's 47 native sub-issues so the two now agree.

17 closed, 30 open. P0 8 of 27 — #966, #949, #900, #870, #865, #954, #950, #953. P1 6 of 13
— #906, #868, #914, #913, #952, #961. Adopted-after-the-plan 3 of 3. Post-v0.9.0 backlog 0 of 4,
by design. Excluding that backlog, 26 open issues stand between here and the exit bar.

• Stale boxes, now ticked. #865 closed 2026-09-16 via #1025 and #954 closed 2026-09-17 via
  #969/#1039 — both landed after the previous status pass, so the lists above were understating
  progress by two.

• Four sub-issues were in no list at all, and so in no count: #1018, #984, #971 (all closed, now
  in Adopted after the plan was written) and #1002, open and unowned, now P1. Walking the checklists
  rather than the sub-issue list is what hid them; the two agree as of this pass.

• Closed in this pass. #950 — the aggregation chain #1011 → #1015 plus the per-tier split
  #1064-#1067/#1072/#1097; its "one documented field-name schema" bullet moved to #898, where the
  second consumer lives. #953 — the last box, honouring persisted configuration, landed in #1048.
  #952 — #1050 aggregates avoided cost beside spend and never in it, per agent included. #961 — the
  structural split shipped, and unlike #959/#960/#963 it does not depend on the v0.9.0 numbers, so it
  is not held by the verification gate.

• #682 missed its 2026-09-19 cutoff with nothing merged, so it has left the release and moved out
  of the stretch list into Not in this release. It was never a sub-issue of this epic — its parent
  is #2244 — so it is the one item here that GitHub never counted either way.

• #1002 is the open question this pass raises. abctl service install writes proxy settings into
  the environment, so with the service down the routing stays configured and the harness gets
  connection-refused behind a generic "network error". It is filed P1 only because the epic holds that
  nothing unowned may be P0; give it an owner and it has a claim on exit criterion 2.

• Partly done, correctly still open. #912 has the backoff and the pinned-versus-transient split
  (SkipSet.backoffFor, Fail / FailTransient) and #1041 names the CA to the client, but there is
  still no list of currently-skipped hosts and the connection is still dead post-forge. #901's
  user-visible complaint is fixed by #904/#933/#999 and cost survives restart via the ledger, but the
  scoped sqlite Store does not exist — worth rescoping. #951 measures mean response time with
  whiskers, but no time-to-first-token and no percentiles.

• Untouched, with eight days to the target. #926 — no stream-idle handling anywhere in the tree.
  Install and lifecycle #944/#945/#946/#947/#956/#957/#964 — PRs #1076 and #1080 are still open and
  five of those hang on them. Agent contract #939 — abctl configure exists (#1028) but
  bob/codex/opencode answer "not yet persistent", and cmd_claudecode.go is still the bespoke
  original, so #941/#942/#943 stay blocked behind it.