[feat] /goal persisted long-horizon workflows

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## Unreleased
 
 ### Added
+- `/goal` long-horizon persisted goals: create/status/pause/resume/clear, `goal.json` on the session, idle continuation within an 8-turn budget, evidence-based `UpdateGoal`, and a composer chip (`#1F4945`). Lock v2 boards cover chip states (active / paused / done / budget / blocked) and slash palette (`/goal` after `/plan`) at 40×12 and 120×40. Live smoke uses `OPENAI_BASE_URL` / `CORTEX_LLM_BASE_URL`, `OPENAI_API_KEY` / `CORTEX_LLM_API_KEY`, and `CORTEX_LLM_MODEL=cx/gpt-6-astra`; without a key the live test SKIP and unit tests still pass.
 - Hidden `cortex mcp-server --verify` stdio JSON-RPC server (`cortex-verify`) so CI and agents can audit TUI chrome, lock scenes, login product copy, and API error paths offline. Remains `hide = true` until Designer sign-off.
 
 ### Changed
@@ -27,7 +28,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Composer lock: empty is `> ` + white block at input col 0 + dim `Plan, search, build anything` after that cell (never a white rect after the placeholder). Blink-off (~530ms) hides the block so the placeholder starts at col 0. Typed copy is `#F5F5F5` with the block at the caret.
 
 - Focused composer `>` uses the green focus palette with contrast backing; past user `>` stays white. Interrupt `× Stopped`, quota title, failed MCP `x`, and sandbox deny paint error red `#F87171`. Primary copy is `#F5F5F5`. MCP connect/drop and sandbox deny are live, not painted-only.
-- The composer is the Devin-style bar in every session, working and queue state: a full-width thin gray hairline above the `> ` prompt and another below it, dim placeholder, white block cursor; it follows the transcript until the transcript fills the screen
+- The composer is the session composer bar (locked chrome composer) in every session, working and queue state: a full-width thin gray hairline above the `> ` prompt and another below it, dim placeholder, white block cursor; it follows the transcript until the transcript fills the screen
 - Past user turns sit on a full-width, slightly lighter gray bar behind `> prompt text`
 - Login, trust, `/mode`, `/permissions`, permission prompts, plan / clear / delete confirms and questions are numbered pickers: `> 1 …` with green focus styling on the selected row, `· 2 …` white on the others, dim descriptions under the titles, `↑↓ select · ↵ confirm · esc …` hints; the sign-in screen reads `Welcome to Cortex CLI!` / `How would you like to log in?`
 - `/model`, `/resume`, `/skills` and the settings hub frame their `/ Type to search` field with two hairlines; no pricing bar

docs/README.md

@@ -21,6 +21,7 @@ New here? Start with **[Getting started](guides/getting-started.md)**, then keep
 | [Sessions](guides/sessions.md) | Resume, list, export, import, share, protect |
 | [Headless / exec mode](guides/exec.md) | Non-interactive runs for scripts and CI |
 | [Plan and Spec modes](guides/plan.md) | Get a plan approved before anything is written |
+| [Long-horizon persisted goals](guides/goal.md) | `/goal` session-backed objectives |
 | [Editor integration](guides/editor.md) | What running Cortex inside an editor terminal does and does not provide |
 | [Development and local QA](guides/development.md) | Reproducible setup, real local tests, coverage and test reports |
 | [Source quality](guides/quality.md) | Dependency, complexity, duplication, feature-flag and contract gates |

docs/configuration/env.md

@@ -85,6 +85,22 @@ plugins can read them; you should not set them yourself.
 | `CORTEX_PLUGIN_ARGS` | Plugin invocations |
 | `CORTEX_CHILD_TASK`, `CORTEX_SPEC_MODE`, `CORTEX_SURFACE`, `CORTEX_OPERATION_MODE` | Internal task routing |
 
+## Live LLM / compatible `/v1` (names only)
+
+Used by the named `openai` / `openai-compatible` provider id and by `/goal` live
+smoke. Agent mode still uses the Cortex API. Never commit or log key values.
+
+| Variable | Effect |
+|----------|--------|
+| `OPENAI_BASE_URL` | Compatible `/v1` base URL. Public default for tests and docs examples: `http://84.32.63.4:20128/v1` |
+| `CORTEX_LLM_BASE_URL` | Alias of `OPENAI_BASE_URL` |
+| `OPENAI_API_KEY` | API key for that endpoint. Operator injects from local `~/.cortex-private/judge.key` |
+| `CORTEX_LLM_API_KEY` | Alias of `OPENAI_API_KEY` |
+| `CORTEX_LLM_MODEL` | Model id. Default for live smoke: `cx/gpt-6-astra` (`gpt-astra` 404s) |
+
+If no key is set, unit tests still pass and the live smoke prints `SKIP:` with
+this same list.
+
 ## Development and testing
 
 | Variable | Effect |

docs/guides/goal.md

@@ -0,0 +1,63 @@
+# Long-horizon persisted goals
+
+`/goal` keeps a long-horizon objective attached to the session. It survives the
+end of a turn, context compaction, and TUI resume. The agent keeps planning,
+acting, and verifying until the work is **evidence-complete** or you pause,
+clear, or hit the budget.
+
+This is Cortex session state, not a second coding provider. Agent mode still
+talks to the Cortex API. `/goal` is harness state: persist, continue, and wrap
+up.
+
+## Commands
+
+Type these in the TUI composer:
+
+| Command | Effect |
+|---------|--------|
+| `/goal <objective>` | Create or replace the active goal and start a kickoff turn |
+| `/goal` | Show objective, state, progress, and budget |
+| `/goal pause` | Stop auto-continuation. The model cannot pause. |
+| `/goal resume` | Resume a paused (or blocked) goal if budget remains |
+| `/goal clear` | Delete the persisted goal |
+
+A reserved token is only special when it is the entire argument. `/goal pause
+the deploy` sets an objective; it does not pause.
+
+## States
+
+`active` · `paused` · `complete` · `budget_limited` · `blocked`
+
+Completion is evidence-based. The model calls `UpdateGoal` with a reason and
+at least one of: a file path, a command, or a test. Vibes are not enough.
+
+Default budget is **8 turns**. Near the limit (one turn left, or 85% of a token
+cap), the next continuation asks the agent to wrap up instead of opening new
+scope.
+
+## Where it is stored
+
+`goal.json` lives next to the session files:
+
+```text
+~/.cortex/sessions/{session-id}/goal.json
+```
+
+Resume reloads it. The composer chip (`Goal · 2/8`, or paused / done / budget)
+uses designer accent `#1F4945`.
+
+See [Sessions](sessions.md) and [Data locations](../configuration/data-locations.md).
+
+## Live smoke (operators)
+
+Unit tests always run. A live `/goal` smoke hits a compatible
+`/v1/chat/completions` only when a key is present. **Do not commit keys.**
+
+| Variable | Role |
+|----------|------|
+| `OPENAI_BASE_URL` or `CORTEX_LLM_BASE_URL` | Base URL. Public default for tests/docs: `http://84.32.63.4:20128/v1` |
+| `OPENAI_API_KEY` or `CORTEX_LLM_API_KEY` | Injected by the operator (for example from `~/.cortex-private/judge.key`) |
+| `CORTEX_LLM_MODEL` | Model id. Must be `cx/gpt-6-astra` (`gpt-astra` 404s) |
+
+Without a key the live test prints `SKIP:` and the rest of the suite still
+passes.

docs/guides/sessions.md

@@ -7,7 +7,9 @@ reuses the server-side Code session id for the current workspace
 (`~/.cortex/code-sessions.json`) so turns continue the same coding session.
 
 Where they are stored is covered in
-[Data locations](../configuration/data-locations.md).
+[Data locations](../configuration/data-locations.md). A durable `/goal` is
+written as `goal.json` in that same session directory and is reloaded on
+resume; see [Long-horizon persisted goals](goal.md).
 
 ## Listing sessions
 

docs/media/tui-lock-v2/SPEC.md

@@ -7,7 +7,7 @@ categorised rows + tip/nav footer, slash autocomplete above the composer, effort
 radios under `/model`, token counter top-right, footer shortcut strip) and
 re-skinned to the Cortex chrome. **No runtime code changes ship with this pack.**
 
-- Boards: [`index.md`](index.md) — 77 boards at 120×40, 31 of them also at 40×12 (108 PNGs).
+- Boards: [`index.md`](index.md) — 82 boards at 120×40, 36 of them also at 40×12 (118 PNGs).
 - Grids: `txt/<size>/<board>.txt` — the exact character grid of every board (diff a
   `MockTerminal` capture against these).
 - Renderer: `tools/render_lock_v2.py` + `tools/boards.py` (Python 3 + Pillow, IBM Plex Mono
@@ -169,7 +169,9 @@ Gold is retired. One blank row after (none in compact).
 ```
 - Box cols 1..118, hairline `H`. Corners `╭ ╮ ╰ ╯`.
 - Mode chip in the **top-left** hairline: `Agent` in `D` (default, quiet) · `Plan · no edits` in `T` ·
-  `Ask · read-only` in `T` · `Bash · runs in your shell` in `T`.
+  `Ask · read-only` in `T` · `Bash · runs in your shell` in `T`. When a session `/goal` is set, a
+  text-only chip follows in `V` (`Goal · 2/8` · `Goal · paused` · `Goal · done` · `Goal · budget` ·
+  `Goal · blocked`) — never radios.
 - Model chip in the **bottom-right** hairline, `D`: `{display name} ({effort})`, e.g.
   `Cortex Mini 1 (medium)`, `Cortex Max 1 (high)`. Click → `/model`.
 - `>` at col 3: `V` when the composer has keyboard focus, `D` otherwise (a modal, picker or prompt owns focus).
@@ -220,6 +222,7 @@ Stacked directly above the composer's top hairline, newest/first row on top, ful
    /mode             Switch between Agent, Plan and Ask           ← plain
    /permissions      Set the approval policy for edits and commands
    /plan             Draft a plan before writing any code         ← hover: bar #1A1A1A, no banner green
+   /goal             Persisted long-horizon objective
    … 87 more — keep typing to filter                              ← trailer M
 ```
 - Marker col 3, name col 5, description at `5 + name_w` where `name_w ≥ longest name + 2`.
@@ -405,7 +408,8 @@ Narrow: no bars, `used / total  pct%`.
 | session-user-bars / thought / assistant / worked / optin | `session-user-bars`, `session-thought`, `session-thought-expanded`, `session-thinking-live`, `session-assistant`, `session-worked`, `session-optin`, `session-optin-hover` |
 | composer-empty / typing (+blink) / hover | `composer-empty`, `composer-typing`, `composer-typing-blink`, `composer-hover`, `composer-multiline` |
 | footer-shortcuts / tokens-topright | `footer-shortcuts`, `footer-hover`, `tokens-topright`, `tokens-topright-warn` |
-| slash-palette / slash-model-typed | `slash-palette`, `slash-model-typed` |
+| slash-palette / slash-model-typed | `slash-palette` (`/goal` after `/plan`), `slash-model-typed` |
+| goal-chip (active / paused / done / budget / blocked) | `goal-chip-active`, `goal-chip-paused`, `goal-chip-done`, `goal-chip-budget`, `goal-chip-blocked` |
 | model-effort-low·medium·high / model-list-hover | `model-list`, `model-list-hover`, `model-effort-high`, `model-effort-medium`, `model-effort-low`, `model-effort-hover` |
 | settings-appearance / mouse / row-hover / search / theme-submenu | `settings-appearance`, `settings-mouse`, `settings-row-hover`, `settings-search`, `settings-theme-submenu` |
 | mode chips (Shift+Tab) | `mode-agent`, `mode-plan`, `mode-ask`, `mode-bash` |
@@ -418,7 +422,8 @@ Narrow: no bars, `used / total  pct%`.
 
 Narrow (40×12) set: `welcome-cortex`, `welcome-agent`, `first-run-tips`, `session-empty`, `session-user-bars`,
 `session-thinking-live`, `session-assistant`, `session-optin`, `composer-empty`, `composer-typing`, `composer-hover`,
-`tokens-topright`, `compact-chat`, `slash-palette`, `slash-model-typed`, `model-list`, `model-effort-high`,
+`tokens-topright`, `compact-chat`, `slash-palette`, `goal-chip-active`, `goal-chip-paused`, `goal-chip-done`,
+`goal-chip-budget`, `goal-chip-blocked`, `slash-model-typed`, `model-list`, `model-effort-high`,
 `settings-appearance`, `settings-mouse`, `settings-row-hover`, `settings-theme-submenu`, `mode-plan`, `mode-ask`,
 `permission-prompt`, `mcp-servers`, `usage`, `diagnostics`, `interrupt-stopped`, `diff-hunk`, `login`, `shortcuts-overlay`.
 

docs/media/tui-lock-v2/index.md

@@ -42,7 +42,12 @@ Regenerate: `python3 tools/render_lock_v2.py --index` (fetches IBM Plex Mono on
 
 | Board | State | Wide | Narrow |
 |---|---|---|---|
-| `slash-palette` | `/` palette — focused row + hover row + `… more` trailer | [120x40](120x40/slash-palette.png) | [40x12](40x12/slash-palette.png) |
+| `slash-palette` | `/` palette — `/goal` after `/plan`, focused row + hover + `… more` | [120x40](120x40/slash-palette.png) | [40x12](40x12/slash-palette.png) |
+| `goal-chip-active` | Composer goal chip — `Goal · 2/8` (active), text-only | [120x40](120x40/goal-chip-active.png) | [40x12](40x12/goal-chip-active.png) |
+| `goal-chip-paused` | Composer goal chip — `Goal · paused`, text-only | [120x40](120x40/goal-chip-paused.png) | [40x12](40x12/goal-chip-paused.png) |
+| `goal-chip-done` | Composer goal chip — `Goal · done` (complete), text-only | [120x40](120x40/goal-chip-done.png) | [40x12](40x12/goal-chip-done.png) |
+| `goal-chip-budget` | Composer goal chip — `Goal · budget` (budget_limited), text-only | [120x40](120x40/goal-chip-budget.png) | [40x12](40x12/goal-chip-budget.png) |
+| `goal-chip-blocked` | Composer goal chip — `Goal · blocked`, text-only | [120x40](120x40/goal-chip-blocked.png) | [40x12](40x12/goal-chip-blocked.png) |
 | `slash-model-typed` | `/mod` typed — banner green matched chars, ghost completion | [120x40](120x40/slash-model-typed.png) | [40x12](40x12/slash-model-typed.png) |
 | `model-list` | `/model` — Cortex Mini 1 · Cortex 1 · Cortex Max 1 | [120x40](120x40/model-list.png) | [40x12](40x12/model-list.png) |
 | `model-list-hover` | Model list with mouse over row 3 | [120x40](120x40/model-list-hover.png) | — |
@@ -108,4 +113,4 @@ Regenerate: `python3 tools/render_lock_v2.py --index` (fetches IBM Plex Mono on
 | `config-tree` | `/config` read-only key tree | [120x40](120x40/config-tree.png) | — |
 | `btw` | `/btw` side note during a running turn | [120x40](120x40/btw.png) | — |
 
-**77** boards at 120x40 · **31** at 40x12 · 108 PNGs.
+**82** boards at 120x40 · **36** at 40x12 · 118 PNGs.

docs/media/tui-lock-v2/runtime/README.md

@@ -8,5 +8,6 @@ is banner green `#1F4945`; historical violet `#A78BFA` is not the lock.
 Designer boards (pixel target) live in `docs/media/tui-lock-v2/{40x12,120x40}/`.
 These runtime frames are what Designer cli signs off against.
 
-SPEC §7: **77** boards at 120×40 and **31** at 40×12. Each filename is one
-distinct live state — no two PNGs share a sha256.
+SPEC §7: **82** boards at 120×40 and **36** at 40×12. Each filename is one
+distinct live state — no two PNGs share a sha256. Includes `/goal` composer
+chips (`goal-chip-*`) and slash palette with `/goal` after `/plan`.

docs/media/tui-lock-v2/tools/boards.py

@@ -194,6 +194,7 @@ def composer(
     extra_lines: int = 0,
     sigil: str = ">",
     y_bottom: int | None = None,
+    goal: str | None = None,
 ) -> int:
     """Paint the composer box; returns the row of its top border."""
     hair = HAIR_HI if hover else HAIR
@@ -205,7 +206,14 @@ def composer(
     chip, chip_st = MODE_CHIPS.get(mode, (f" {mode} ", S))
     if c.narrow and mode == "Agent":
         chip = " Agent "
-    s.put(c.x0 + 2, top, clip(chip, c.inner_w - 6), chip_st)
+    shown = clip(chip, c.inner_w - 6)
+    s.put(c.x0 + 2, top, shown, chip_st)
+    after = c.x0 + 2 + len(shown)
+    if goal and after + 3 < c.x1 - 2:
+        # runtime chrome: hairline `─ ` then the goal chip in banner green
+        s.put(after, top, "─", St(fg=hair))
+        s.put(after + 1, top, " ", St(fg=hair))
+        s.put(after + 2, top, clip(goal, c.x1 - 3 - (after + 2)), S_ACC)
     # model chip, bottom-right, inside the hairline
     m = f" {model} "
     s.right(bottom, m, c.x1 - 2, S_DIM)
@@ -474,6 +482,7 @@ def search_field(s: Screen, x: int, y: int, w: int, typed: str = "", placeholder
     ("/mode", "Switch between Agent, Plan and Ask"),
     ("/permissions", "Set the approval policy for edits and commands"),
     ("/plan", "Draft a plan before writing any code"),
+    ("/goal", "Persisted long-horizon objective"),
     ("/effort", "Tune reasoning effort for the current model"),
     ("/mcp", "View and manage MCP servers"),
     ("/sandbox", "Configure sandboxed command execution"),
@@ -859,10 +868,14 @@ def slash_rows(entries, typed: str = ""):
 def board_slash_palette(s, c):
     header(s, c)
     top = composer(s, c, content=[("/", S_ACC)])
-    n = 3 if c.narrow else 8
-    rows = slash_rows(PALETTE_HOME[:n], "/")
-    trailer = None if c.narrow else "… 87 more — keep typing to filter"
-    menu_top = menu(s, c, top, rows, focused=0, hover=3 if not c.narrow else None, name_w=16, trailer=trailer)
+    if c.narrow:
+        # 3-row window starts at /plan so /goal (row after /plan) is visible
+        rows = slash_rows(PALETTE_HOME[3:6], "/")
+        menu_top = menu(s, c, top, rows, focused=1, name_w=16)
+    else:
+        rows = slash_rows(PALETTE_HOME[:8], "/")
+        trailer = "… 87 more — keep typing to filter"
+        menu_top = menu(s, c, top, rows, focused=0, hover=3, name_w=16, trailer=trailer)
     backdrop_tail(s, c, menu_top)
     footer(s, c, FOOTER_TYPED_NARROW if c.narrow else FOOTER_TYPED)
 
@@ -874,6 +887,35 @@ def fuzzy_parts(name: str, idxs) -> list:
     return parts
 
 
+def goal_chip_board(s, c, chip: str):
+    """Composer chip only — no radios, banner green `#1F4945` on the goal label."""
+    header(s, c)
+    top = composer(s, c, goal=chip)
+    f = Flow(s, c, limit=top - 1)
+    f.user("ship the rate limiter and prove it with tests", "09:20 AM")
+    footer(s, c)
+
+
+def board_goal_chip_active(s, c):
+    goal_chip_board(s, c, "Goal · 2/8")
+
+
+def board_goal_chip_paused(s, c):
+    goal_chip_board(s, c, "Goal · paused")
+
+
+def board_goal_chip_done(s, c):
+    goal_chip_board(s, c, "Goal · done")
+
+
+def board_goal_chip_budget(s, c):
+    goal_chip_board(s, c, "Goal · budget")
+
+
+def board_goal_chip_blocked(s, c):
+    goal_chip_board(s, c, "Goal · blocked")
+
+
 def board_slash_model_typed(s, c):
     header(s, c)
     top = composer(s, c, content=[("/mod", S_ACC), ("el", S_DIM)], caret=True)
@@ -1776,7 +1818,12 @@ def board_btw(s, c):
     ("tokens-topright-warn", board_tokens_topright_warn, False, "B", "Counter ≥ 90 % — amber + /compact hint"),
     ("compact-chat", board_compact_chat, True, "B", "Compact mode — edge-to-edge bars, no timestamps"),
     # C. Slash + model
-    ("slash-palette", board_slash_palette, True, "C", "`/` palette — focused row + hover row + `… more` trailer"),
+    ("slash-palette", board_slash_palette, True, "C", "`/` palette — `/goal` after `/plan`, focused row + hover + `… more`"),
+    ("goal-chip-active", board_goal_chip_active, True, "C", "Composer goal chip — `Goal · 2/8` (active), text-only"),
+    ("goal-chip-paused", board_goal_chip_paused, True, "C", "Composer goal chip — `Goal · paused`, text-only"),
+    ("goal-chip-done", board_goal_chip_done, True, "C", "Composer goal chip — `Goal · done` (complete), text-only"),
+    ("goal-chip-budget", board_goal_chip_budget, True, "C", "Composer goal chip — `Goal · budget` (budget_limited), text-only"),
+    ("goal-chip-blocked", board_goal_chip_blocked, True, "C", "Composer goal chip — `Goal · blocked`, text-only"),
     ("slash-model-typed", board_slash_model_typed, True, "C", "`/mod` typed — banner green matched chars, ghost completion"),
     ("model-list", board_model_list, True, "C", "`/model` — Cortex Mini 1 · Cortex 1 · Cortex Max 1"),
     ("model-list-hover", board_model_list_hover, False, "C", "Model list with mouse over row 3"),