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.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
docs(agent): the activity signal cannot be derived, and updatedAt inverts the truth
Abdurrahman Fakhrulb905dad7872a
diff --git a/docs/AGENT-ACTIVITY-SIGNAL.md b/docs/AGENT-ACTIVITY-SIGNAL.mdnew file mode 100644index 00000000..b8f912ad--- /dev/null+++ b/docs/AGENT-ACTIVITY-SIGNAL.md@@ -0,0 +1,49 @@+# 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:87` calls `ownerSessionSummaries(limit)`.+- **Mapping:** `lib/agent/session-record.ts:10-38` transforms records via `summary(record)` into `AgentSessionSummary` (`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 to `diff = now - updatedAt <= ACTIVITY_THRESHOLD_MS (60_000)` to guess `working` vs `idle`.+- **Finding:** `GET /api/v1/agent-sessions` (`scripts/mso-agent-api.mjs:100`) never populates `row.status`. Every row falls through to the timestamp comparison.++### 3. Existing Runtime Signals+- **Subagent jobs:** `lib/agent/subagent-jobs.ts:12-22` and `scripts/mso-agent-jobs.mjs:35-53` track 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 via `saveCliSession` (`POST /api/v1/agent-sessions`).+- **Timestamp mutation:** `lib/agent/session-mutations.ts:47` (and `lib/agent/session-store.ts:133`) sets `record.updatedAt = new Date().toISOString()` when the record is saved.+- **Invocation timing:** In `scripts/mso-agent-turn.mjs:198`, `await persistSession(session)` is called only after `agentRound` completely finishes. Line 207 calls it in the catch block on failure.+- **Finding:** `persistSession` is 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:+1. **False Idle:** While a turn is actively executing (for example, LLM generation streaming for 90 seconds or a long-running tool command), `updatedAt` remains the completion timestamp of the previous turn. A caller inspecting `updatedAt` perceives an active session as idle.+2. **False Working:** Immediately after a turn finishes, `updatedAt` is brand new (`now - updatedAt < 1s`). The agent is completely idle waiting for user input, yet the timestamp heuristic marks it as `working` for the entire 60-second threshold.++## Minimal Server Change to Enable Case A++To make a truthful activity signal possible without guessing:++1. **Schema additions (`lib/agent/session-types.ts`):**+ - Add optional field `turnActive?: boolean` (or `turnStartedAt?: string | null`) to both `AgentSession` and `AgentSessionSummary`.+2. **Turn lifecycle markers (`scripts/mso-agent-turn.mjs` and `app/api/v1/agent-sessions`):**+ - At turn start (inside `runInteractiveRound`, before `agentRound`), send a lightweight action (e.g. `action: "turn-start", id: session.id`) or update `turnStartedAt = new Date().toISOString()`.+ - At turn end (inside the `finally` block of `runInteractiveRound`), clear the marker (`turnStartedAt = null`).+3. **List handler exposure (`lib/agent/session-record.ts:summary`):**+ - Include `turnActive: Boolean(record.turnStartedAt)` in `AgentSessionSummary` so `GET /api/v1/agent-sessions` returns the live state directly in the session list.diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.mdindex 8b784124..d368f4be 100644--- a/docs/CHANGELOG.md+++ b/docs/CHANGELOG.md@@ -8,7 +8,7 @@ this is the *what*, and it is what Settings → Account → About shows as “Wh**Added**-- `tui` the opencode-inspired batch, nine branches in one change+- `tui` the opencode-inspired batch, nine branches in one change (#241)- `tui` pin a pane slot without losing the cycle (#229)- `tui` a preferences registry, and settings that survive a restart (#231)- `tui` a vertical tab rail, from the same layout the horizontal row uses (#230)@@ -18,6 +18,10 @@ this is the *what*, and it is what Settings → Account → About shows as “Wh- `convex` write env over HTTP with the deployment key, and fix the regional host+**Docs**++- `agent` the activity signal cannot be derived, and updatedAt inverts the truth+## 2026-11-01**Added**diff --git a/docs/README.md b/docs/README.mdindex b5dec0da..d068153b 100644--- a/docs/README.md+++ b/docs/README.md@@ -65,6 +65,7 @@ evidence and review freshness. The repository quality gate runs both automatical| [`TUI-RENDERER-PLAN.md`](./TUI-RENDERER-PLAN.md) | What the TUI is today, why a retained renderer is the only path to panels and tabs, and the M0 to M8 order that keeps every gate green || [`TUI-HANDOVER.md`](./TUI-HANDOVER.md) | Where the TUI panel track stands, the state of the one in-progress branch, and what must be true before the alternate screen becomes the default || [`REA-OPENCODE-TUI.md`](./REA-OPENCODE-TUI.md) | Reverse-engineered opencode TUI study: OpenTUI engine evidence, settings/command registries, sidebar slots, tabs status, and fit for MSO |+| [`AGENT-ACTIVITY-SIGNAL.md`](./AGENT-ACTIVITY-SIGNAL.md) | Why a live session activity signal cannot be derived today, the evidence per code path, and the smallest server change that would enable it || [`ORGANIZATION.md`](./ORGANIZATION.md) | Owner-private organization units, seats, reporting lines, live agent bindings, and workflow routing references || [`MCP-HOW-TO.md`](./MCP-HOW-TO.md) | Bahasa Indonesia onboarding: client connection, prompts, workflow, project MCP and troubleshooting || [`MCP.md`](./MCP.md) | MCP/OAuth internals and full external-tool security model |