recodeee · NagyVikt · Apr 23, 2026 · Apr 23, 2026 · Apr 23, 2026 · Apr 23, 2026
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-23
@@ -0,0 +1,17 @@
+## Why
+
+- The raw Active Agents tree still surfaces machine worktree folder names and full `agent/...` refs, which slows scan time when many sandboxes are open.
+- Operators need dense `3 files`-style summaries and branch labels that read like task rows, not filesystem internals.
+
+## What Changes
+
+- Prefer task-first labels for raw worktree groups when the worktree maps to a single active session.
+- Compact raw branch rows from full `agent/<owner>/<task>` refs to a shorter owner/task label while keeping the full ref in tooltips.
+- Normalize raw session summaries to `Working · 3 files · ...` wording and mirror the update into the template extension source.
+- Bump the live/template Active Agents manifest versions for the shipped UI tweak.
+
+## Impact
+
+- Scope stays inside the VS Code Active Agents extension tree presentation.
+- Full worktree paths and full branch refs remain available in tooltips and commands.
+- Focused regression coverage stays in `test/vscode-active-agents-session-state.test.js`.
@@ -0,0 +1,23 @@
+## ADDED Requirements
+
+### Requirement: raw Active Agents worktree rows stay task-first
+
+The VS Code Active Agents raw tree SHALL prefer a readable task label and compact worktree summary instead of the managed worktree folder basename when a worktree represents a single active session.
+
+#### Scenario: single-session worktree group
+
+- **WHEN** the raw Active Agents tree renders a managed worktree that contains one tracked session
+- **THEN** the worktree row uses the session task name as its label
+- **AND** the description shows compact agent/file/lock summary text
+- **AND** the tooltip still exposes the full worktree path and full branch ref.
+
+### Requirement: raw Active Agents branch rows stay compact but identifiable
+
+The VS Code Active Agents raw tree SHALL render readable branch rows that preserve operator context without repeating the full `agent/...` ref in the visible label.
+
+#### Scenario: raw branch row
+
+- **WHEN** the raw Active Agents tree renders a session row under a worktree group
+- **THEN** the row label uses a compact owner/task branch label
+- **AND** the row description starts with a capitalized session status and compact file summary wording like `Working · 3 files`
+- **AND** the tooltip still includes the full branch ref.
@@ -0,0 +1,35 @@
+## Definition of Done
+
+This change is complete only when **all** of the following are true:
+
+- Every checkbox below is checked.
+- The agent branch reaches `MERGED` state on `origin` and the PR URL + state are recorded in the completion handoff.
+- If any step blocks (test failure, conflict, ambiguous result), append a `BLOCKED:` line under section 4 explaining the blocker and **STOP**. Do not tick remaining cleanup boxes; do not silently skip the cleanup pipeline.
+
+## Handoff
+
+- Handoff: change=`agent-codex-codex-task-2026-04-23-13-25`; branch=`agent/codex/codex-task-2026-04-23-13-25`; scope=`Active Agents raw worktree labels, compact branch rows, mirrored template, focused tests`; action=`improve the screenshoted tree design inside the existing sandbox and finish normally`.
+
+## 1. Specification
+
+- [x] 1.1 Finalize proposal scope and acceptance criteria for `agent-codex-codex-task-2026-04-23-13-25`.
+- [x] 1.2 Define normative requirements in `specs/agent-codex-codex-task-2026-04-23-13-25/spec.md`.
+
+## 2. Implementation
+
+- [x] 2.1 Tighten raw Active Agents worktree labels/descriptions to read task-first instead of machine-folder-first.
+- [x] 2.2 Tighten raw branch row labels/descriptions to show compact owner/task labels and cleaner `3 files` wording.
+- [x] 2.3 Mirror the tree update into the template extension source and bump the live/template manifest versions.
+- [x] 2.4 Extend focused regression coverage for the raw tree presentation.
+
+## 3. Verification
+
+- [x] 3.1 Run `node --test test/vscode-active-agents-session-state.test.js`.
+- [x] 3.2 Run `openspec validate agent-codex-codex-task-2026-04-23-13-25 --type change --strict`.
+- [x] 3.3 Run `openspec validate --specs`.
+
+## 4. Cleanup (mandatory; run before claiming completion)
+
+- [ ] 4.1 Run the cleanup pipeline: `gx branch finish --branch agent/codex/codex-task-2026-04-23-13-25 --base main --via-pr --wait-for-merge --cleanup`. This handles commit -> push -> PR create -> merge wait -> worktree prune in one invocation.
+- [ ] 4.2 Record the PR URL and final merge state (`MERGED`) in the completion handoff.
+- [ ] 4.3 Confirm the sandbox worktree is gone (`git worktree list` no longer shows the agent path; `git branch -a` shows no surviving local/remote refs for the branch).
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-23
@@ -0,0 +1,16 @@
+## Why
+
+- Active Agents already shows state, file churn, and freshness, but it does not surface the per-session health score operators already scan in Cave Monitor.
+- When several sandboxes are live, the user has to leave the VS Code tree and cross-check another surface to see which session is drifting hardest.
+
+## What Changes
+
+- Accept an optional `sessionHealth` payload from active-session JSON records and `AGENT.lock` snapshot telemetry.
+- Show the compact score (`45/100`) in each session row, with the labeled summary in the tooltip and session detail list.
+- Mirror the schema/rendering patch into the extension template and lock it with focused Active Agents tests.
+
+## Impact
+
+- Backward compatible: sessions without `sessionHealth` keep the current description and tooltip format.
+- Affected surface: `vscode/guardex-active-agents/*`, `templates/vscode/guardex-active-agents/*`, focused extension tests, and this change workspace.
+- This change only renders cave-monitor telemetry when a producer includes it; it does not change how the score is calculated.
@@ -0,0 +1,17 @@
+## ADDED Requirements
+
+### Requirement: Active Agents rows surface optional session health
+The VS Code Active Agents extension SHALL show the compact session-health score when an active-session record or `AGENT.lock` telemetry payload includes Cave Monitor health data for that session.
+
+#### Scenario: Active-session record includes session health
+- **GIVEN** `.omx/state/active-sessions/<branch>.json` contains `sessionHealth.score=45` and `sessionHealth.label="Inefficient"`
+- **WHEN** the extension renders that session in `Working now` or `Idle / thinking`
+- **THEN** the row description includes `45/100`
+- **AND** the tooltip or session detail list includes `45/100 · Inefficient`
+
+#### Scenario: Worktree lock fallback includes session health
+- **GIVEN** no active-session JSON exists for a managed worktree
+- **AND** the worktree `AGENT.lock` snapshot telemetry includes session health for the latest session preview
+- **WHEN** the extension falls back to the `AGENT.lock` session
+- **THEN** the rendered session row includes the compact `score/100`
+- **AND** sessions without `sessionHealth` keep the current description format.
@@ -0,0 +1,40 @@
+## Definition of Done
+
+This change is complete only when **all** of the following are true:
+
+- Every checkbox below is checked.
+- The agent branch reaches `MERGED` state on `origin` and the PR URL + state are recorded in the completion handoff.
+- If any step blocks (test failure, conflict, ambiguous result), append a `BLOCKED:` line under section 4 explaining the blocker and **STOP**. Do not tick remaining cleanup boxes; do not silently skip the cleanup pipeline.
+
+## Handoff
+
+- Handoff: change=`agent-codex-show-session-health-in-active-agents-2026-04-23`; branch=`agent/codex/codex-task-2026-04-23-13-25`; scope=`vscode/guardex-active-agents/*`, `templates/vscode/guardex-active-agents/*`, `test/vscode-active-agents-session-state.test.js`, and this change workspace; action=`render optional Cave Monitor session-health scores in Active Agents rows without changing no-payload sessions`.
+- Copy prompt: Continue `agent-codex-show-session-health-in-active-agents-2026-04-23` on branch `agent/codex/codex-task-2026-04-23-13-25`. Work inside the existing sandbox, review `openspec/changes/agent-codex-show-session-health-in-active-agents-2026-04-23/tasks.md`, continue from the current state instead of creating a new sandbox, and when the work is done run `gx branch finish --branch agent/codex/codex-task-2026-04-23-13-25 --base main --via-pr --wait-for-merge --cleanup`.
+
+## 1. Specification
+
+- [x] 1.1 Finalize proposal scope and acceptance criteria for `agent-codex-show-session-health-in-active-agents-2026-04-23`.
+- [x] 1.2 Define normative requirements in `specs/vscode-active-agents-session-health/spec.md`.
+
+## 2. Implementation
+
+- [x] 2.1 Normalize optional `sessionHealth` payloads from active-session JSON records and `AGENT.lock` snapshot telemetry.
+- [x] 2.2 Render compact session-health scores in Active Agents rows, tooltips, and detail items without changing sessions that lack health data.
+- [x] 2.3 Mirror the source/template patch and add focused regression coverage.
+
+## 3. Verification
+
+- [x] 3.1 Run targeted project verification commands.
+- [x] 3.2 Run `openspec validate agent-codex-show-session-health-in-active-agents-2026-04-23 --type change --strict`.
+- [x] 3.3 Run `openspec validate --specs`.
+
+Verification evidence:
+- `node --test test/vscode-active-agents-session-state.test.js` (pass, 42 tests)
+- `openspec validate agent-codex-show-session-health-in-active-agents-2026-04-23 --type change --strict` (pass)
+- `openspec validate --specs` (`No items found to validate.` in this worktree)
+
+## 4. Cleanup (mandatory; run before claiming completion)
+
+- [ ] 4.1 Run the cleanup pipeline: `gx branch finish --branch agent/codex/codex-task-2026-04-23-13-25 --base main --via-pr --wait-for-merge --cleanup`. This handles commit -> push -> PR create -> merge wait -> worktree prune in one invocation.
+- [ ] 4.2 Record the PR URL and final merge state (`MERGED`) in the completion handoff.
+- [ ] 4.3 Confirm the sandbox worktree is gone (`git worktree list` no longer shows the agent path; `git branch -a` shows no surviving local/remote refs for the branch).