v3.1.7 Jacobean Released

[amrmelsayed]

v3.1.7 Jacobean

Released: 2026-06-03

Another Jacobean-line patch focused on the VS Code extension. The biggest story is the Builders tree's reframe — grouping by lifecycle stage (SPECIFY → PLAN → IMPLEMENT → REVIEW → PR → VERIFIED) by default, with area/* grouping still one click away via a toggle, so triage answers "what's blocking me right now?" without giving up the "what domain am I in?" view. Alongside it: area-header roll-up status icons, a Codev CLI preflight on startup with a guided walkthrough, a new editor-tab Search Backlog webview, and a click-to-reconnect affordance on terminal give-up. The cycle's biggest bug-fix wins close two long-standing annoyances — the terminal no longer spams "Connection lost" indefinitely, and the sidebar no longer blanks empty during transient connection blips — plus a fresh bug born in v3.0.6: dev-server menu / keybindings / palette no longer offer options for missing config.

Codev CLI preflight on extension activation (#791, PR #955)

The extension now verifies, on every startup, that the codev CLI is installed on PATH and at a version at least as new as itself. The probe is fire-and-forget and bounded to 400ms so activation isn't blocked; the result caches for the session. Until #791 this dependency was implicit — a missing or out-of-date CLI surfaced only as a confusing "not connected to Tower" error from deep in the activation path, with no actionable guidance.

Three outcomes branch the UX:

• OK — no toast, no walkthrough. A new Codev CLI row in the sidebar's Status view shows the detected version with a green check.
• Missing — the new Get started with Codev walkthrough opens automatically (once per workspace), with three steps: detect (codev --version), install (npm install -g @cluesmith/codev, with Node ≥20 prereq surfaced), and verify.
• Outdated — a warning notification offers Update via npm (one-click install in an integrated terminal, with a re-verify that fires only when that specific terminal closes with a success exit code), Open Install Docs, or dismiss.

The Status row carries a recheck button on missing/outdated states (intentionally not on the ≤400ms pending probe window — a recheck button there is meaningless and would risk a second concurrent codev --version). A new Codev: Recheck CLI command exposes the same recovery path from the palette. Dismissing the prompt leaves Codev commands registered but no-op'ing with a single "run setup" toast rather than crashing — guarded commands fall through cleanly until the CLI is sorted out.

The walkthrough's Verify step completion keys off onContext:codev.cliReady, so a failed recheck doesn't falsely tick the step — only a genuinely successful preflight does.

Preview

Builders tree group-by-stage (action axis) with stage/area toggle (#952, PR #970)

The Builders sidebar tree used to group only by area/* label — the same axis the Backlog tree uses. That's the right grouping for Backlog ("what should I pick up next?" → domain) but the wrong default for Builders, where the real question is "what's blocking me right now?" → action. With area-only grouping you had to expand every group and scan each row's [<phase>] prefix to find the builders needing your attention.

This release makes lifecycle stage the new default for Builders specifically (area grouping is still supported — see the toggle below): the group rows are the builder's lifecycle stage (SPECIFY → PLAN → IMPLEMENT → REVIEW → PR → VERIFIED, in lifecycle order, empty stages hidden), and each row reads [<area>] #<id> <title>. "Show me everything blocked at plan-approval" is now one group expand instead of an N-row scan.

The grouping is toggleable for reviewers who prefer the domain view, from either of two places:

• a title-bar button ($(tag) shows when in stage mode, $(milestone) shows when in area mode), or
• a control on the group header itself — flip the axis without moving your cursor away from the row you were scanning.

Either control flips both the group axis and the row prefix together. The choice persists per workspace via the new codev.buildersGroupBy setting ("stage" default, or "area"). Per-mode collapse state is independent and persists across reloads — collapsing the IMPLEMENT group in stage mode doesn't collapse area/vscode in area mode.

Group by Area

Group by Phase

Backlog grouping is unaffected by all of this — it remains area-grouped because "domain" really is the right axis for "what should I pick up?".

Terminal reconnect overhaul + click-to-recover affordance (#936, #939, PR #962)

A Codev terminal whose WebSocket dies — Tower restart, a forgotten session id, a transient network blip — used to fill the pane with [Codev: Connection lost, reconnecting...] lines in a tight loop. No backoff, no give-up, no actual reconnect — and the comment in the code claimed the terminal-manager handled reconnection while in fact nothing subscribed. The architect's real output kept flowing into a live Tower-side PTY, buried under the spam.

This release rewires the terminal adapter to own its reconnect loop:

• Exponential backoff (1s → 2s → 4s → 8s → 16s → 30s) instead of fire-as-fast-as-possible. The pane now shows one [Codev: retrying in Ns (attempt n/6)] line per interval, not several per second.
• Bounded retry: after 6 attempts (~63s total under the backoff curve), the adapter stops and prints a red failure line. No more terminals stuck in an unbounded loop.
• Fast-give-up on stale-session: when Tower's WebSocket close-frame indicates the session id is unknown (i.e. Tower restarted, the PTY is gone), the adapter recognises the case from the upgrade-error string and surfaces the red give-up immediately — no waiting through 6 retries for a hopeless retry chain.
• Stream-state isolation across reconnects: the terminal's ANSI decoder and escape-sequence buffer are reset before each scheduled reconnect, so a half-received escape sequence from the dead socket can't corrupt the new one's output. An identity guard on the close handler also prevents the old socket's late-arriving close from scheduling a stray retry against a healthy reconnected socket — a class of bug that bit a prior attempt at this fix.

On top of that give-up state, #939 ships a recovery affordance: the red failure line carries a clickable Reconnect token (via a terminal link provider). One click starts a fresh retry chain from the same terminal — repeatable, so a "click → retry → fail again → click" cycle works every time. The user no longer needs to close the terminal tab and re-open via the sidebar / command palette to recover.

Targeting works correctly across multiple terminals: the click reconnects the terminal whose line was clicked, not whichever terminal happens to be active.

A follow-up (#961) tracks consolidating the four duplicated copies of the exponential-backoff curve (this adapter, the SSE connection-manager, the dashboard's web terminal, the tunnel client) into a single @cluesmith/codev-core policy — including the design call on whether the dashboard's web terminal should adopt the same 6-attempt give-up and stale-session fast-path it currently lacks.

Area-header roll-up icons (#926, PR #959)

The area/* group headers in the Backlog and Builders sidebar trees now carry a status glyph that summarises what's inside, so you can triage areas at a glance without expanding each group.

The two views answer different questions and the rollup vocabularies reflect that:

• Backlog is binary — filled grey dot if the area has any builder working it, outline grey if it's purely open work waiting to be spawned. The Backlog asks "is anyone working this area?", and grey reads as a calm "where can I spawn?" surface rather than overloading the green that builder rows reserve for live agents.
• Builders is a worst-of-three — yellow bell if any builder in the group is blocked at a gate, blue comment-discussion if any are idle, green circle-filled only if all are active. Reuses the per-row glyph vocabulary so the header is a literal summary of what's below it. The full {b blocked · i waiting · a active} breakdown lives in the tooltip.

A consequence worth a conscious nod: the same area can show a filled-grey Backlog header (has a builder) while its Builders header reads yellow bell (that builder is blocked). That's intended — the two views are different questions, and the headers answer each in its own register.

One known limitation, tracked as a follow-up: an area whose only open issue is being built has the issue filtered out of the Backlog today, so the area renders no Backlog header at all. #948 explores keeping in-progress issues in the Backlog with the builder's state icon, which would close that gap.

Search Backlog editor-tab webview (#920, PR #957)

The Backlog view's title bar gains a 🔍 icon that opens a new Search Backlog editor-tab panel — a full editor-area webview built for exploratory triage where the always-on sidebar tree and the Quick Pick both fall short.

Filter the open backlog by Area, Assignee, and Author (three native-styled dropdowns that AND together); substring-search title and body with a debounced live query; sort any column; row click opens the issue and the ↪ inline action references it in the architect chat with #<id> "<title>". A match-count footer reads N matches found · by-area breakdown.

Three modes: Open (default, mirrors the sidebar's PR-excluded backlog), Closed (lifts the PR exclusion since closed issues usually have a merged PR), All. The panel is a singleton — re-invoking the command focuses the existing tab instead of stacking duplicates. Themed via CSS variables only, so dark / light / high-contrast all render cleanly without per-theme code.

This panel coexists with the sidebar Backlog tree and the Codev: Search Backlog… Quick Pick (#918) rather than replacing either. The sidebar is at-a-glance "what's on my plate"; Quick Pick is muscle-memory "I know it exists, find it, dismiss"; this panel is "scan, filter, sort, refine". Supersedes the closed #906.

Preview

Sidebar stops flickering empty during transient connection blips (#916, PR #976)

The Codev sidebar's four data-bearing views (Builders, Backlog, Pull Requests, Recently Closed) used to all blank simultaneously — while the Workspace view stayed populated — then recover on their own after some unknown interval. The bug was intermittent, hard to reproduce on demand, and rendered the architect's daily-driver surface untrustworthy at exactly the moments (network blip, Tower restart, SSE reconnect) when the user most wanted to see what was actually happening.

Root cause: the shared overview cache that backs those four views was overwriting populated data with null on a transient read — when the extension wasn't currently connected or when a /api/overview fetch failed. Every provider treats a falsy cache read as an empty list, so a single null commit blanked all four views at once. The Workspace view stayed populated because it reads from different sources (it doesn't depend on /api/overview), which was the discriminating signal that ruled out the obvious-but-wrong theory ("Tower must be sending empty data").

The fix is straightforward once the diagnosis lands: the cache now holds last-known-good data. Transient reads no longer clobber the cache; only a successful fetch commits a new value; and a dedicated reconnect refresh re-syncs the moment the connection is re-established. The no-flicker invariant is pinned at the event level too — onDidChange only fires on a successful commit, never on a transient/failed read, so providers aren't even asked to re-render mid-blip.

Trade-off by design: a long Tower outage now shows stale fleet data rather than blanking. The issue's acceptance explicitly chose stale-over-blank — a distinct "disconnected" visual treatment for the data-views is a separate concern, deliberately out of scope here. The cache continues to hold the last value it saw until either a successful fetch commits a fresher one or the user explicitly refreshes.

Polish

• Run / Stop Dev Server entries hide when worktree.devCommand isn't configured (vscode: Run/Stop Dev Server context-menu entries on builder rows ignore worktree.devCommand presence #975, PR vscode: gate builder-row Run/Stop Dev Server menu on worktree.devCommand (#975) #978). The Workspace view's Start row has always honoured this gating, but the builder-row context menu, dev keybindings (Cmd/Ctrl+Alt+R/S), and command palette didn't — they would surface on every blocked builder regardless, then fail with a missing-command error on click. All four surfaces now share a single codev.hasDevCommand context key, refreshed by the same global signals (onStateChange + worktree-config-updated SSE) that already drive the Workspace view's gate, so add / remove / edit worktree.devCommand in .codev/config.json and every gated surface updates live without a window reload. Also fixes a latent Workspace-view bug: "devCommand": "" (empty string) used to render a Start row that errored on click; now treated as absent.
• Neutral inline gate-action icon on builder rows (VSCode Builders tree: inline gate-action button uses checkmark icon even when the action isn't 'approve' #933, PR VSCode Builders tree: neutral inline gate-action icon (#933) #963). The inline action button on a blocked builder row used to show a ✓ checkmark regardless of which gate the builder was at — implying "approve" even when the underlying action might be View Plan or Run Dev. It's now a neutral → arrow. Behaviour is unchanged (same click flow); per-gate triage continues to live on the row's leading icon (the gate-specific glyph from the same icon vocabulary shipped earlier this cycle).
• [new] prefix on freshly-created backlog rows (vscode: mark recently-created backlog rows (created within last 24h) #930, PR vscode: mark recently-created backlog rows with [new] (<24h) #949). Backlog items whose createdAt is within the last 24 hours now lead with a [new] prefix right after the issue number — e.g. #930 [new] vscode: mark recently-created.... The threshold is re-evaluated on every tree render so items naturally lose the prefix as they age past 24h, no per-user state, no manual dismissal. The OverviewBacklogItem.createdAt field was already on the wire from earlier work, so this was a pure UI-layer change in packages/vscode/src/views/backlog.ts plus a new backlog-recency.ts pure helper with vitest coverage. Architect made an in-flight placement call at dev-approval (commit 5ff73ac4) to lead the row with [new] rather than trail it; commit 16cb365c reconciled the plan and review docs to match the shipped order.
• Open Builder Terminal and Send Message Quick Picks show #<id> <title> (vscode: 'Open Builder Terminal' and 'Send Message' Quick Picks show internal builder id instead of issue # + title #925, PR vscode: show issue # + title in Open Builder Terminal & Send Message pickers #951). The two outlier builder pickers (palette commands Codev: Open Builder Terminal and Codev: Send Message to Builder) previously labelled rows with the internal builder name (e.g. pir-1333), while the seven other builder pickers in the extension already used the #<id> <title> format. This fix brings the two outliers into line. Mechanical .map() change in each picker's source; data was already on the wire via the same getWorkspaceState endpoint the canonical pickers consume. Surfaced a follow-up: there's no Send-Message-to-Architect Quick Pick at all — filed as vscode: add Send Message to Architect Quick Pick (or fold architects into Send Message) #950.

Other fixes (dashboard, porch, infrastructure)

• Web dashboard terminal now gives up after 6 reconnect attempts (was 50), and the refresh button truly reconnects from the dead-socket state (core: extract transport-agnostic reconnect policy; adopt in vscode + dashboard terminals + tunnel client #961, PR core: extract transport-agnostic reconnect policy; adopt in vscode + dashboard terminals + tunnel client #972). The web terminal used to retry a failed WebSocket up to 50 times before stopping, and its refresh button only resized a live socket — clicking it after the terminal had given up did nothing useful. Both surfaces now share the same bounded reconnect curve used by the VS Code terminal (1s → 2s → 4s → 8s → 16s → 30s, give-up after 6 attempts, fresh retry chain on a true reconnect), so dashboard users get the same actionable give-up state VS Code users got in terminal-adapter: WebSocket close-handler spams 'Connection lost' in a tight loop with no backoff, no give-up, no actual reconnect #936 and the refresh button is now the recovery affordance it always looked like. A follow-up (web terminal: adopt session-unknown fast-path once Tower emits a browser-visible WS close code #971) tracks adopting the stale-session fast-path on the web side too once Tower emits a browser-visible close code.
• SPIR/ASPIR review iteration ceiling lowered from 8 to 3 (PR Lower SPIR/ASPIR review iteration ceiling (max_iterations) from 8 to 3 #964). The max_iterations safety ceiling on every SPIR and ASPIR phase (and the defaults block) is now 3, not 8. This is the runaway-loop backstop, not a target — a phase normally advances the moment its 3-way consult APPROVEs (typically 1–2 rounds), and the ceiling fires only when REQUEST_CHANGES persists, at which point porch force-advances and escalates to the human. Lowering 8 → 3 means a deadlocked phase escalates after 3 stuck rounds instead of 8 — saves consult tokens, faster escalation, no behavior change when the phase is actually making progress. Configuration-only change in codev-skeleton/protocols/{spir,aspir}/protocol.json.
• Directory entries in worktree.symlinks via trailing-slash opt-in (Allow directory entries in worktree.symlinks via trailing-slash opt-in #805, PR Allow directory entries in worktree.symlinks via trailing-slash opt-in #947). worktree.symlinks previously dropped directory matches silently — the nodir: true glob flag intentionally kept a footgun guard against a pattern like "apps/auth" symlinking the worktree's source over the parent's. A new trailing-slash form (".local-user-data/") is treated as a literal-path directory symlink; entries without a trailing slash keep their existing file-only behavior (footgun guard intact). Use case: sharing per-worktree runtime state directories (gitignored, intentionally not branch-isolated) so builders boot against the parent's existing state instead of bootstrapping from scratch. Windows handled via symlinkSync(src, dest, 'dir'); glob metacharacters inside a trailing-slash entry emit a warning rather than silently mis-expanding.

Preview

Breaking changes

None.

Install

npm install -g @cluesmith/codev@X.Y.Z
afx tower stop && afx tower start

The VS Code extension ships separately via the Marketplace — Codev extension by cluesmith.codev, version X.Y.Z.

Contributors

• Amr Elsayed (@amrmelsayed) — VS Code extension surface area: spec, plan, and integration across the Builders tree group-by-stage reframe (vscode: Builders tree should group by phase (action axis), not area (domain axis); area becomes the row prefix #952), the terminal reconnect overhaul + recovery affordance (terminal-adapter: WebSocket close-handler spams 'Connection lost' in a tight loop with no backoff, no give-up, no actual reconnect #936, vscode: add manual-reconnect affordance to terminal give-up state #939), area-header roll-up icons (VSCode: area-header roll-up icons in backlog & builders views #926), CLI preflight + walkthrough (vscode: startup preflight — verify codev CLI installed and version ≥ extension version; guide install/upgrade otherwise #791), Search Backlog editor-tab webview (vscode: editor-tab webview for rich backlog search #920), the sidebar last-known-good fix (vscode: sidebar data (builders, backlog, PRs, etc.) intermittently disappears, then recovers on its own #916), and the dev-server menu gating (vscode: Run/Stop Dev Server context-menu entries on builder rows ignore worktree.devCommand presence #975). Also the Overview-types consolidation (Collapse duplicate Overview*/*Overview types (single source of truth in @cluesmith/codev-types) #875) and the transport-agnostic reconnect-policy extraction to @cluesmith/codev-core (core: extract transport-agnostic reconnect policy; adopt in vscode + dashboard terminals + tunnel client #961). Reviewed every PR in the v3.1.7 set.
• M Waleed Kadous (@waleedkadous) — SPIR/ASPIR consultation cost: lowered the runaway-loop max_iterations ceiling from 8 to 3 (PR Lower SPIR/ASPIR review iteration ceiling (max_iterations) from 8 to 3 #964). Deadlocked phases now escalate to the human after 3 stuck consult rounds instead of 8 — saves consult tokens, faster escalation, no behavior change when the phase is actually making progress.
• Builders working under AIR / BUGFIX / PIR / SPIR protocols across the PRs in this release.