Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.
Agent Session Activity Signal Investigation
Investigation into deriving a live session activity signal (working, idle, waiting) from existing MSO session records.
Decision: Case B (Cannot Be Distinguished Without Server Changes)
A live session activity signal cannot be derived reliably from existing MSO session records or APIs. Deriving working from updatedAt is not merely a weak heuristic; it is actively misleading for long turns.
Evidence and Audited Code Paths
1. Session Row Fields in List Handler
- Location:
app/api/v1/agent-sessions/handler-get.ts:87callsownerSessionSummaries(limit). - Mapping:
lib/agent/session-record.ts:10-38transforms records viasummary(record)intoAgentSessionSummary(lib/agent/session-types.ts:80-102). - Fields returned:
id,source,name,label,title,titleSource,createdAt,updatedAt,resumedFrom,cwd,parentSessionId,estimatedTokens,lifetimeEstimatedTokens,compactThresholdTokens,compactionCount,archiveCount,lastCompactedAt,lastArchivedAt,eventCount,historyTurns,artifacts. - Finding: No
status,presence,state, or turn-in-progress indicator exists on the session row.
2. CLI-Side Session State Heuristic
- Location:
scripts/mso-agent-session-list.mjs:14-51(stateOf). - Behavior: Checks for explicit
row.status(working,busy,running,waiting,idle), falling back todiff = now - updatedAt <= ACTIVITY_THRESHOLD_MS (60_000)to guessworkingvsidle. - Finding:
GET /api/v1/agent-sessions(scripts/mso-agent-api.mjs:100) never populatesrow.status. Every row falls through to the timestamp comparison.
3. Existing Runtime Signals
- Subagent jobs:
lib/agent/subagent-jobs.ts:12-22andscripts/mso-agent-jobs.mjs:35-53track background jobs in a volatile process Map (const jobs = new Map<string, SubagentJob>()), scoped to capability tool invocations (subagent_job_list), not interactive sessions. - Lock files: Ephemeral file locks (
lib/agent/session-mutations.ts:25,withSecurityStoreLock) exist only during atomic disk writes, lasting milliseconds. No persistent lock indicates an active turn. - Turn progress: Neither token stream chunks nor tool executions emit observable disk writes, turn counters, or inter-process IPC signals for the session.
4. Turn Persistence Path
- Persistence driver:
scripts/mso-agent-session-ui.mjs:15(persistSession) saves the session viasaveCliSession(POST /api/v1/agent-sessions). - Timestamp mutation:
lib/agent/session-mutations.ts:47(andlib/agent/session-store.ts:133) setsrecord.updatedAt = new Date().toISOString()when the record is saved. - Invocation timing: In
scripts/mso-agent-turn.mjs:198,await persistSession(session)is called only afteragentRoundcompletely finishes. Line 207 calls it in the catch block on failure. - Finding:
persistSessionis called strictly at turn completion, never per streamed chunk or during tool execution.
Why updatedAt Inverts the Real State
Because updatedAt records when the last completed turn was written:
- False Idle: While a turn is actively executing (for example, LLM generation streaming for 90 seconds or a long-running tool command),
updatedAtremains the completion timestamp of the previous turn. A caller inspectingupdatedAtperceives an active session as idle. - False Working: Immediately after a turn finishes,
updatedAtis brand new (now - updatedAt < 1s). The agent is completely idle waiting for user input, yet the timestamp heuristic marks it asworkingfor the entire 60-second threshold.
Minimal Server Change to Enable Case A
To make a truthful activity signal possible without guessing:
- Schema additions (
lib/agent/session-types.ts):- Add optional field
turnActive?: boolean(orturnStartedAt?: string | null) to bothAgentSessionandAgentSessionSummary.
- Add optional field
- Turn lifecycle markers (
scripts/mso-agent-turn.mjsandapp/api/v1/agent-sessions):- At turn start (inside
runInteractiveRound, beforeagentRound), send a lightweight action (e.g.action: "turn-start", id: session.id) or updateturnStartedAt = new Date().toISOString(). - At turn end (inside the
finallyblock ofrunInteractiveRound), clear the marker (turnStartedAt = null).
- At turn start (inside
- List handler exposure (
lib/agent/session-record.ts:summary):- Include
turnActive: Boolean(record.turnStartedAt)inAgentSessionSummarysoGET /api/v1/agent-sessionsreturns the live state directly in the session list.
- Include
Resolution: Fixed (Turn Lifecycle Activity Signal Landed)
The minimal server change and lifecycle markers have landed:
Schema (
lib/agent/session-types.ts):- Added
turnStartedAt?: string | nulltoAgentSession. - Added
turnActive: booleantoAgentSessionSummary.
- Added
Summary mapping (
lib/agent/session-record.ts):summary(record)derivesturnActive: Boolean(record.turnStartedAt), returning a truthful boolean without client-side timestamp arithmetic.
Session store helper (
lib/agent/session-store.ts):- Added
updateAgentSessionTurnActive(principal, id, turnStartedAt)to writerecord.turnStartedAt(or delete it when cleared) and updaterecord.updatedAtwhile holding the session lock.
- Added
API route allow-list (
app/api/v1/agent-sessions/handler-post.ts):- Added
turnStartedAt?: string | nullto the POST body type and wiredaction: "update"to invokeupdateAgentSessionTurnActivewhenturnStartedAtis defined.
- Added
CLI turn lifecycle markers (
scripts/mso-agent-turn.mjs):- Write point 1 (turn start): inside
runInteractiveRound, beforeagentRoundbegins, persists the session withturnStartedAt = new Date().toISOString(). - Write point 2 (turn end): inside the
finallyblock ofrunInteractiveRound, clearsturnStartedAttonullso interrupted or crashed turns never stick in the active state. - All bookkeeping writes catch and suppress errors so network or storage issues during bookkeeping never abort the agent round.
- Write point 1 (turn start): inside
TUI consumption and loop closure (
scripts/mso-agent-session-list.mjs):- Wired
turnActiveintostateOf:turnActive: truederivesworking(eliminating false idle during active turns), andturnActive: falsederivesidle(eliminating false working immediately post-turn). - Added
turnActive === truetoneedsAttentionand identified it inattentionReasonasturnActive: working, enabling/tabs nextand/tabs prevto navigate truthfully to active sessions. - Connected
turnActivethrough/tabstable and tab row indicators, completing the loop across all TUI views without client-side timestamp arithmetic.
- Wired