stacklok / stacklok/mecatl

mecatui: distinguish saved session state from confirmed running activity

Open
#1,621 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Go
Stars
152
Forks
16
Avg merge
14h 48m
Merged PRs (30d)
536

Description

Problem

The /sessions browser represents running with a triangle and completed with a checkmark. The selected row also has a triangle cursor. These glyphs do not adequately explain session state, and a saved running state is not evidence that a process is still executing.

An operator's computer crashed during a session. After restarting, that session appeared with a triangle and opened only for read-only inspection. The operator did not know the triangle meant running or why continuation was unavailable. They subsequently resumed the same session successfully using mecatui --resume <exact-session-id>.

This is a confirmed user-reported crash and successful recovery, not a runtime ownership trace. The browser should communicate what the server actually knows rather than presenting persisted state as verified liveness.

Expected behavior

Explicit status wording distinguishes current, confirmed activity from the last persisted execution state. A glyph or color may supplement the wording, but must not be the only explanation.

Illustrative wording when ownership is unknown: Last saved while running · activity unconfirmed. Do not label every uncertain session crashed or recoverable.

Acceptance criteria

  • Session rows or an immediately discoverable detail surface provide explicit textual status, including the meaning of the running badge; the selection cursor is visually distinguishable from the status indicator.
  • The UI distinguishes persisted running state from server-confirmed activity. Unknown/unavailable activity evidence remains explicitly uncertain, not falsely active or crashed.
  • Confirmed activity means evidence from the server's applicable ownership/liveness mechanisms, not merely state == running or absence from this client's local registry.
  • When continuation is unavailable, the UI explains why and provides an appropriate next action. Recovery, when available, points to the separately tracked Recover and continue workflow.
  • Status refresh reflects updated server evidence; merely viewing status does not start, cancel, or recover a session.
  • Status remains understandable without color and in narrow terminal layouts.
  • Offline tests cover active, saved-running/activity-unknown, and completed sessions, including a selected running row.
  • Update the owning user documentation with the status meanings and uncertainty semantics.

Source context

  • cmd/mecatui/ui/sessions_surface.go:1244-1257: state badges.
  • cmd/mecatui/ui/sessions_surface.go:1540-1555: selected-row cursor alongside the state badge.
  • internal/adapter/server/service.go:8016-8049: inventory capabilities currently classify persisted running or locally live sessions as active elsewhere.

Line references describe the source inspected when filing and may move.

Scope and relationships

This issue owns explaining state, not changing the recovery policy. The Recover and continue action is tracked separately. Read-only transcript selection/copy is #1620.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in cmd/mecatui/ui/sessions_surface.go:1244-1257 and 1540-1555 to trace state badges and the selected-row cursor, then inspect internal/adapter/server/service.go:8016-8049 for the activity evidence currently exposed. Locate the existing offline session tests and cover active, saved-running/unknown, completed, and selected-running states. Done includes explicit uncertainty and continuation messaging, refreshed status behavior, narrow-layout accessibility, and updated user documentation.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
backend, cli, documentation, testing
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
66/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.