From 4988ede4d4b53f2cca64a962731de22c188a23f7 Mon Sep 17 00:00:00 2001
From: Ali Mohammad <freelancealimohammad@gmail.com>
Date: Thu, 29 Oct 2026 00:14:01 +0300
Subject: [PATCH 1/2] feat(observe): close idle sessions

The sweep ends an active session (status 'ended', ended_at = its last
activity) once none of its observations is open and nothing in it started
or finished within the idle window (`observe start --session-idle-minutes N`,
default 30, 0 = off). New activity past ended_at reopens an ended or
interrupted session on ingest; stale or reordered events do not. Retention
then prunes ended sessions like any other finished one. Studio's Threads
status facet offers 'ended'.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/screens/threads/ThreadsScreen.tsx     |   8 +-
 .../threads/__tests__/threads.test.tsx        |   9 ++
 docs/cli.md                                   |  11 +-
 docs/observability.md                         |  28 +++-
 llms-full.txt                                 |  39 +++++-
 src/cli/observe.test.ts                       |   4 +
 src/cli/observe.ts                            |  37 ++++--
 src/observe/daemon.ts                         |  17 ++-
 src/observe/store.test.ts                     |  61 +++++++++
 src/observe/store.ts                          |  39 +++++-
 src/observe/sweep.test.ts                     | 125 ++++++++++++++++++
 src/observe/sweep.ts                          |  34 +++++
 12 files changed, 393 insertions(+), 19 deletions(-)

diff --git a/apps/agent-forge/src/screens/threads/ThreadsScreen.tsx b/apps/agent-forge/src/screens/threads/ThreadsScreen.tsx
index 7f8d39a64..27e229945 100644
--- a/apps/agent-forge/src/screens/threads/ThreadsScreen.tsx
+++ b/apps/agent-forge/src/screens/threads/ThreadsScreen.tsx
@@ -34,8 +34,12 @@ import {
   type ThreadsUrlState,
 } from './threadsUrl';
 
-/** Session statuses the daemon writes: `active`, then `interrupted` when the agent's crash sweep closes it. */
-const STATUSES = ['active', 'interrupted'];
+/**
+ * Session statuses the daemon writes: `active`; `ended` once its idle sweep sees
+ * nothing run for the idle window; `interrupted` when the agent's crash sweep
+ * closes it. New activity makes an ended or interrupted session `active` again.
+ */
+const STATUSES = ['active', 'ended', 'interrupted'];
 
 /** The session's span, start to its latest finished observation; `-` while nothing has finished. */
 const span = (s: ObserveSessionRow): number | null => (s.ended_at === null ? null : s.ended_at - s.started_at);
diff --git a/apps/agent-forge/src/screens/threads/__tests__/threads.test.tsx b/apps/agent-forge/src/screens/threads/__tests__/threads.test.tsx
index 2e17d4ba0..bdf80bcfa 100644
--- a/apps/agent-forge/src/screens/threads/__tests__/threads.test.tsx
+++ b/apps/agent-forge/src/screens/threads/__tests__/threads.test.tsx
@@ -147,6 +147,15 @@ describe('ThreadsScreen list', () => {
     expect(custom?.getAttribute('aria-pressed')).toBe('true');
   });
 
+  it('offers the ended status the idle sweep writes', async () => {
+    const container = await mountAt('#/threads?status=ended');
+    expect(listRequests().at(-1)!.get('status')).toBe('ended');
+    const statusBtn = [...container.querySelectorAll<HTMLButtonElement>('.facet-btn')].find((b) => b.textContent?.startsWith('Status'))!;
+    act(() => statusBtn.click());
+    const options = [...container.querySelectorAll('.facet-pop .facet-opt')].map((o) => o.textContent);
+    expect(options).toEqual(['active', 'ended', 'interrupted']);
+  });
+
   it('opening a row navigates to #/threads/:sessionId', async () => {
     const container = await mountAt('#/threads?status=active');
     const row = container.querySelector<HTMLTableRowElement>('tbody tr[data-row-index="0"]')!;
diff --git a/docs/cli.md b/docs/cli.md
index 591d8752c..ba051535b 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -36,7 +36,7 @@ lousho mcp <agent.yaml|json|agent-dir|agent.ts> [--http --port N --host H]
 lousho doctor [agent.yaml|json|agent-dir|agent.ts] [--json] [--ping]
 lousho eval [globs...] [--tag t] [--junit path] [--json path] [--strict] [--judge] [--record | --replay | --drift [--drift-usage]] [--url <base> [--token <bearer>]] [--config vitest.config.ts] [--timeout <ms>]
 lousho traces [traceId|prefix] [--dir D] [--limit N] [--json] [--content]
-lousho observe <start|status|stop|rebuild-rollups|prune|export|token> [--port N] [--db path] [--host H] [--require-token] [--project X] [--webhook URL] [--retention-days N] [--older-than <N>d] [--since <N>d|<N>h|<N>m] [--agent X] [--out file]
+lousho observe <start|status|stop|rebuild-rollups|prune|export|token> [--port N] [--db path] [--host H] [--require-token] [--project X] [--webhook URL] [--retention-days N] [--session-idle-minutes N] [--older-than <N>d] [--since <N>d|<N>h|<N>m] [--agent X] [--out file]
 lousho prompt <push <file|->|list|get <name[@version|@label]>|label <name> <label> <version>> [--url U] [--port N] [--token T] [--json] [--name N]
 lousho --version
 ```
@@ -306,6 +306,15 @@ prune stays committed, the error goes to stderr and the exit code is 0. It is
 safe to run while the daemon is up. A bad N is a usage
 error (exit 2). See [Retention](./observability.md#retention).
 
+`start --session-idle-minutes N` sets when a conversation counts as finished
+(default 30; `0` turns it off, so a session stays `active` until its agent goes
+down). The daemon's sweep marks a session `ended` once none of its runs is
+still open and nothing in it has started or finished for N minutes; its
+`ended_at` is the time of that last activity. A new run in an `ended` (or
+`interrupted`) session makes it `active` again. Ended sessions are then pruned
+by `--retention-days` like any other finished session. A bad N is a usage
+error (exit 2). See [Idle sessions](./observability.md#idle-sessions).
+
 `export` writes traces as JSONL: one line per trace, `{ trace, observations,
 scores }` (the same rows the trace API returns), oldest first, with no cap on
 how many. `--since <N>d` (or `<N>h`, `<N>m`) keeps traces that started within
diff --git a/docs/observability.md b/docs/observability.md
index f45676d79..d8971ae57 100644
--- a/docs/observability.md
+++ b/docs/observability.md
@@ -628,7 +628,8 @@ however old. With a trace go its scores and its prompt-use links; scores older
 than the window whose trace has no observations left go too. A session is
 deleted only when it is not `active`, ended (or, with no end, started) before
 the window, and no remaining observation references it, so an old thread
-that is still active is never pruned.
+that is still active is never pruned. Idle sessions end on their own (see
+[Idle sessions](#idle-sessions)), so finished conversations do age out.
 
 Pruning never touches the Insights rollups (charts for pruned days stay),
 the prompt registry, hub entries, the agent registry or tokens. The daily
@@ -693,12 +694,35 @@ session row is `{ session_id, agent_id, agent_name, status, started_at,
 ended_at, traces, input_tokens, output_tokens, cost_usd, last_input_preview }`:
 `traces` counts distinct trace ids, tokens and cost sum the session's
 observations, and `last_input_preview` is the first 200 characters of the root
-input of its latest trace.
+input of its latest trace. `status` is `active`, `ended` (idle, see below) or
+`interrupted` (its agent went down).
 
 `GET /api/v1/sessions/:id` returns `{ session, traces }` with the traces
 (same rows as the trace list) ordered by start ascending, capped at 500; an
 unknown id is a 404 with code `LOUSHO_REQUEST_INVALID`.
 
+### Idle sessions
+
+The SDK sends no "session closed" event: a session row exists because its
+runs carry its id, so the daemon decides when a conversation is over. Each
+sweep (every 30 s) marks a session `ended` when none of its runs is still open
+(a run in progress keeps it `active` however long it takes) and nothing in it
+has started or finished for `--session-idle-minutes` (default 30; `0` turns
+this off). Its `ended_at` is the time of that last activity, not the time of
+the sweep. A session no run references falls back to when the daemon last
+updated it. Sessions in a db written by an older daemon close on the first
+sweep that finds them idle.
+
+A new run in an `ended` session makes it `active` again (`ended_at` follows
+its runs again), and so does new activity in an `interrupted` one. A
+re-sent or reordered event for activity at or before the session's
+`ended_at` does not reopen it. The idle pass never touches `interrupted`
+sessions. Once ended, a session is pruned by [retention](#retention) like
+any other finished session, so Threads shows only live conversations as
+`active`. The idle window is judged against the timestamps your agents
+report, so an agent clock far behind the daemon's can end a session early;
+its next run reopens it.
+
 ## The built server
 
 The server `lousho build --target=node-server` or `--target=docker` generates
diff --git a/llms-full.txt b/llms-full.txt
index 15c18fba1..835a28515 100644
--- a/llms-full.txt
+++ b/llms-full.txt
@@ -4991,7 +4991,7 @@ lousho mcp <agent.yaml|json|agent-dir|agent.ts> [--http --port N --host H]
 lousho doctor [agent.yaml|json|agent-dir|agent.ts] [--json] [--ping]
 lousho eval [globs...] [--tag t] [--junit path] [--json path] [--strict] [--judge] [--record | --replay | --drift [--drift-usage]] [--url <base> [--token <bearer>]] [--config vitest.config.ts] [--timeout <ms>]
 lousho traces [traceId|prefix] [--dir D] [--limit N] [--json] [--content]
-lousho observe <start|status|stop|rebuild-rollups|prune|export|token> [--port N] [--db path] [--host H] [--require-token] [--project X] [--webhook URL] [--retention-days N] [--older-than <N>d] [--since <N>d|<N>h|<N>m] [--agent X] [--out file]
+lousho observe <start|status|stop|rebuild-rollups|prune|export|token> [--port N] [--db path] [--host H] [--require-token] [--project X] [--webhook URL] [--retention-days N] [--session-idle-minutes N] [--older-than <N>d] [--since <N>d|<N>h|<N>m] [--agent X] [--out file]
 lousho prompt <push <file|->|list|get <name[@version|@label]>|label <name> <label> <version>> [--url U] [--port N] [--token T] [--json] [--name N]
 lousho --version
 ```
@@ -5261,6 +5261,15 @@ prune stays committed, the error goes to stderr and the exit code is 0. It is
 safe to run while the daemon is up. A bad N is a usage
 error (exit 2). See [Retention](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/observability.md#retention).
 
+`start --session-idle-minutes N` sets when a conversation counts as finished
+(default 30; `0` turns it off, so a session stays `active` until its agent goes
+down). The daemon's sweep marks a session `ended` once none of its runs is
+still open and nothing in it has started or finished for N minutes; its
+`ended_at` is the time of that last activity. A new run in an `ended` (or
+`interrupted`) session makes it `active` again. Ended sessions are then pruned
+by `--retention-days` like any other finished session. A bad N is a usage
+error (exit 2). See [Idle sessions](https://github.com/LinuxDevil/agent-sdk/blob/main/docs/observability.md#idle-sessions).
+
 `export` writes traces as JSONL: one line per trace, `{ trace, observations,
 scores }` (the same rows the trace API returns), oldest first, with no cap on
 how many. `--since <N>d` (or `<N>h`, `<N>m`) keeps traces that started within
@@ -14494,7 +14503,8 @@ however old. With a trace go its scores and its prompt-use links; scores older
 than the window whose trace has no observations left go too. A session is
 deleted only when it is not `active`, ended (or, with no end, started) before
 the window, and no remaining observation references it, so an old thread
-that is still active is never pruned.
+that is still active is never pruned. Idle sessions end on their own (see
+[Idle sessions](#idle-sessions)), so finished conversations do age out.
 
 Pruning never touches the Insights rollups (charts for pruned days stay),
 the prompt registry, hub entries, the agent registry or tokens. The daily
@@ -14559,12 +14569,35 @@ session row is `{ session_id, agent_id, agent_name, status, started_at,
 ended_at, traces, input_tokens, output_tokens, cost_usd, last_input_preview }`:
 `traces` counts distinct trace ids, tokens and cost sum the session's
 observations, and `last_input_preview` is the first 200 characters of the root
-input of its latest trace.
+input of its latest trace. `status` is `active`, `ended` (idle, see below) or
+`interrupted` (its agent went down).
 
 `GET /api/v1/sessions/:id` returns `{ session, traces }` with the traces
 (same rows as the trace list) ordered by start ascending, capped at 500; an
 unknown id is a 404 with code `LOUSHO_REQUEST_INVALID`.
 
+### Idle sessions
+
+The SDK sends no "session closed" event: a session row exists because its
+runs carry its id, so the daemon decides when a conversation is over. Each
+sweep (every 30 s) marks a session `ended` when none of its runs is still open
+(a run in progress keeps it `active` however long it takes) and nothing in it
+has started or finished for `--session-idle-minutes` (default 30; `0` turns
+this off). Its `ended_at` is the time of that last activity, not the time of
+the sweep. A session no run references falls back to when the daemon last
+updated it. Sessions in a db written by an older daemon close on the first
+sweep that finds them idle.
+
+A new run in an `ended` session makes it `active` again (`ended_at` follows
+its runs again), and so does new activity in an `interrupted` one. A
+re-sent or reordered event for activity at or before the session's
+`ended_at` does not reopen it. The idle pass never touches `interrupted`
+sessions. Once ended, a session is pruned by [retention](#retention) like
+any other finished session, so Threads shows only live conversations as
+`active`. The idle window is judged against the timestamps your agents
+report, so an agent clock far behind the daemon's can end a session early;
+its next run reopens it.
+
 ## The built server
 
 The server `lousho build --target=node-server` or `--target=docker` generates
diff --git a/src/cli/observe.test.ts b/src/cli/observe.test.ts
index ee10688ef..1681c93c3 100644
--- a/src/cli/observe.test.ts
+++ b/src/cli/observe.test.ts
@@ -228,6 +228,10 @@ describe('lousho observe', () => {
       expect(await runObserve(['start', `--retention-days=${bad}`, '--db', file, '--port', '0'])).toBe(2);
     }
     expect(errors.at(-1)).toContain('--retention-days');
+    for (const bad of ['-1', '1.5', 'x', '', '30m']) {
+      expect(await runObserve(['start', `--session-idle-minutes=${bad}`, '--db', file, '--port', '0'])).toBe(2);
+    }
+    expect(errors.at(-1)).toContain('--session-idle-minutes');
   });
 
   describe('export', () => {
diff --git a/src/cli/observe.ts b/src/cli/observe.ts
index c86d44f04..7cf880e44 100644
--- a/src/cli/observe.ts
+++ b/src/cli/observe.ts
@@ -2,7 +2,7 @@
  * `lousho observe` - the collector daemon command. It owns the single writer
  * to `~/.lousho/observe.db` and serves the ingest + Studio read API.
  *
- *   lousho observe start [--port N] [--db path] [--host H] [--require-token] [--retention-days N]
+ *   lousho observe start [--port N] [--db path] [--host H] [--require-token] [--retention-days N] [--session-idle-minutes N]
  *   lousho observe status [--port N | --url U]
  *   lousho observe stop [--db path]
  *   lousho observe rebuild-rollups [--db path]
@@ -25,6 +25,7 @@ import {
   defaultPidPath,
   isObserveDaemon,
   OBSERVE_RETENTION_DAYS_DEFAULT,
+  OBSERVE_SESSION_IDLE_MINUTES_DEFAULT,
   sameDbPath,
   probeHealth,
   startObserveDaemon,
@@ -38,7 +39,7 @@ import { VERSION } from '../version';
 import { exitCodeFor, parseCommand, portValue, stringValue, usageError, type CommandSpec } from './args';
 
 const USAGE = `Usage: lousho observe <command> [options]
-  observe start [--port N] [--db path] [--host H] [--require-token] [--webhook URL] [--retention-days N]
+  observe start [--port N] [--db path] [--host H] [--require-token] [--webhook URL] [--retention-days N] [--session-idle-minutes N]
   observe status [--port N] [--url U]
   observe stop [--db path]
   observe rebuild-rollups [--db path]
@@ -63,6 +64,10 @@ Options:
                     'start': once a day, delete finished traces older than N days (default
                     ${OBSERVE_RETENTION_DAYS_DEFAULT}; 0 keeps everything). Open runs, active sessions,
                     rollups, prompts and hub entries are never pruned.
+  --session-idle-minutes N
+                    'start': end a session once nothing in it has run for N minutes (default
+                    ${OBSERVE_SESSION_IDLE_MINUTES_DEFAULT}; 0 keeps sessions active until their agent goes down).
+                    New activity reopens it; retention then prunes ended sessions.
   --older-than <N>d 'prune': delete finished traces older than N days now, then VACUUM the db
   --since <N>d      'export': only traces that started within the last N days (or <N>h / <N>m)
   --agent X         'export': only this agent (its agent_id, or its name when that names one agent)
@@ -76,10 +81,11 @@ type ObserveSubcommand = 'start' | 'status' | 'stop' | 'rebuild-rollups' | 'prun
 const SUB_SPECS: Record<ObserveSubcommand, CommandSpec> = {
   start: {
     command: 'observe start',
-    usage: 'Usage: lousho observe start [--port N] [--db path] [--host H] [--require-token] [--webhook URL] [--retention-days N]',
+    usage: 'Usage: lousho observe start [--port N] [--db path] [--host H] [--require-token] [--webhook URL] [--retention-days N] [--session-idle-minutes N]',
     options: {
       port: { type: 'string' },
       'retention-days': { type: 'string' },
+      'session-idle-minutes': { type: 'string' },
       db: { type: 'string' },
       host: { type: 'string' },
       'require-token': { type: 'boolean' },
@@ -135,11 +141,17 @@ function stringListValue(value: string | boolean | (string | boolean)[] | undefi
 
 const DAY_MS = 86_400_000;
 
-/** `--retention-days N`: a non-negative integer (0 disables the daily prune), or the default when absent. */
-function retentionDaysValue(spec: CommandSpec, value: string | boolean | (string | boolean)[] | undefined): number {
+/** A non-negative integer flag (`--retention-days N`, `--session-idle-minutes N`; 0 disables), or `fallback` when absent. */
+function wholeNumberValue(
+  spec: CommandSpec,
+  flag: string,
+  meaning: string,
+  value: string | boolean | (string | boolean)[] | undefined,
+  fallback: number
+): number {
   const given = stringValue(value);
-  if (given === undefined) return OBSERVE_RETENTION_DAYS_DEFAULT;
-  if (!/^\d+$/.test(given)) throw usageError(spec, `--retention-days must be a non-negative integer (days; 0 disables pruning), got '${given}'.`);
+  if (given === undefined) return fallback;
+  if (!/^\d+$/.test(given)) throw usageError(spec, `${flag} must be a non-negative integer (${meaning}), got '${given}'.`);
   return Number(given);
 }
 
@@ -210,12 +222,19 @@ async function runStart(args: string[]): Promise<number> {
   const host = stringValue(values.host) ?? '127.0.0.1';
   const requireToken = values['require-token'] === true;
   const webhooks = stringListValue(values.webhook);
-  const retentionDays = retentionDaysValue(spec, values['retention-days']);
+  const retentionDays = wholeNumberValue(spec, '--retention-days', 'days; 0 disables pruning', values['retention-days'], OBSERVE_RETENTION_DAYS_DEFAULT);
+  const sessionIdleMinutes = wholeNumberValue(
+    spec,
+    '--session-idle-minutes',
+    'minutes; 0 never ends idle sessions',
+    values['session-idle-minutes'],
+    OBSERVE_SESSION_IDLE_MINUTES_DEFAULT
+  );
   const pidPath = defaultPidPath(dbPath);
 
   let daemon;
   try {
-    daemon = await startObserveDaemon({ dbPath, port, host, requireToken, pidPath, webhooks, retentionDays });
+    daemon = await startObserveDaemon({ dbPath, port, host, requireToken, pidPath, webhooks, retentionDays, sessionIdleMinutes });
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === 'EADDRINUSE') return reportPortInUse(port, host, dbPath);
     throw error;
diff --git a/src/observe/daemon.ts b/src/observe/daemon.ts
index 8985344c2..2f0647fec 100644
--- a/src/observe/daemon.ts
+++ b/src/observe/daemon.ts
@@ -84,11 +84,24 @@ export interface ObserveDaemonOptions {
    * it; `0`, a negative value or `NaN` disables pruning.
    */
   retentionDays?: number;
+  /**
+   * Idle window in minutes after which the sweep ends an `active` session
+   * with no open observation (default {@link OBSERVE_SESSION_IDLE_MINUTES_DEFAULT}).
+   * Only a finite number `> 0` enables it; `0` keeps sessions active until
+   * their agent goes down.
+   */
+  sessionIdleMinutes?: number;
 }
 
 /** `lousho observe start`'s default retention window: finished traces older than 30 days are pruned daily. */
 export const OBSERVE_RETENTION_DAYS_DEFAULT = 30;
 
+/** `lousho observe start`'s default idle window: a session quiet for 30 minutes with nothing running is ended. */
+export const OBSERVE_SESSION_IDLE_MINUTES_DEFAULT = 30;
+
+/** The sweep's idle window in ms from {@link ObserveDaemonOptions.sessionIdleMinutes} (absent = the default). */
+const minutesToMs = (minutes: number = OBSERVE_SESSION_IDLE_MINUTES_DEFAULT): number => minutes * 60_000;
+
 export interface ObserveDaemon {
   port: number;
   host: string;
@@ -236,7 +249,8 @@ export async function startObserveDaemon(options: ObserveDaemonOptions = {}): Pr
   // The monitoring sweep: rewrites agents.status from heartbeat freshness,
   // interrupts a crashed agent's open work, and posts alerts to webhooks
   // (fire-and-forget; delivery lives in alerts.ts). It also runs the daily
-  // retention prune (sweep.ts) - never a VACUUM, which would stall ingest.
+  // retention prune (sweep.ts) - never a VACUUM, which would stall ingest -
+  // and ends idle sessions.
   const alerter = createAlerter(alertConfig, options.fetchFn ?? fetch);
   const sweep = startStatusSweep(db, {
     intervalMs: options.sweepIntervalMs,
@@ -244,6 +258,7 @@ export async function startObserveDaemon(options: ObserveDaemonOptions = {}): Pr
     errorRateThreshold: alertConfig.errorRateThreshold,
     onAlerts: (alerts) => alerter.post(alerts),
     retentionDays: options.retentionDays ?? OBSERVE_RETENTION_DAYS_DEFAULT,
+    sessionIdleMs: minutesToMs(options.sessionIdleMinutes),
   });
 
   return {
diff --git a/src/observe/store.test.ts b/src/observe/store.test.ts
index e03b02c89..6cad4b2e4 100644
--- a/src/observe/store.test.ts
+++ b/src/observe/store.test.ts
@@ -914,3 +914,64 @@ describe('trace list prompt filter', () => {
     }
   });
 });
+
+describe('session reopen on ingest', () => {
+  const session = (database: SqlDatabase) =>
+    database.prepare("SELECT status, ended_at FROM sessions WHERE session_id = 's1'").get();
+  const closed = (status: 'ended' | 'interrupted'): SqlDatabase => {
+    const database = db();
+    ingestBatch(database, [obs({ session_id: 's1', start: T0, end: T0 + 100 })], T0 + 100);
+    database.prepare("UPDATE sessions SET status = ?, ended_at = ? WHERE session_id = 's1'").run(status, T0 + 100);
+    return database;
+  };
+
+  for (const status of ['ended', 'interrupted'] as const) {
+    it(`a new open trace in an ${status} session reopens it`, () => {
+      const database = closed(status);
+      try {
+        ingestBatch(database, [obs({ obs_id: 'o2', trace_id: 't2', session_id: 's1', start: T0 + 5000, end: undefined, status: undefined })]);
+        expect(session(database)).toMatchObject({ status: 'active', ended_at: null });
+      } finally {
+        database.close();
+      }
+    });
+  }
+
+  it('a new finished trace in an ended session reopens it, ending at that trace', () => {
+    const database = closed('ended');
+    try {
+      ingestBatch(database, [obs({ obs_id: 'o2', trace_id: 't2', session_id: 's1', start: T0 + 5000, end: T0 + 6000 })]);
+      expect(session(database)).toMatchObject({ status: 'active', ended_at: T0 + 6000 });
+    } finally {
+      database.close();
+    }
+  });
+
+  it('a stale or reordered event for activity at or before ended_at does not reopen it', () => {
+    const database = closed('ended');
+    try {
+      ingestBatch(database, [
+        // the same finished root re-sent
+        obs({ session_id: 's1', start: T0, end: T0 + 100 }),
+        // a requeued start event for that root
+        obs({ session_id: 's1', start: T0, end: undefined, status: undefined }),
+        // an older child arriving late
+        obs({ obs_id: 'late', parent_obs_id: 'o1', session_id: 's1', start: T0 + 10, end: T0 + 90 }),
+      ]);
+      expect(session(database)).toMatchObject({ status: 'ended', ended_at: T0 + 100 });
+    } finally {
+      database.close();
+    }
+  });
+
+  it('an active session keeps tracking its latest finished observation', () => {
+    const database = db();
+    try {
+      ingestBatch(database, [obs({ session_id: 's1', start: T0, end: T0 + 100 })]);
+      ingestBatch(database, [obs({ obs_id: 'o2', session_id: 's1', start: T0 + 200, end: undefined, status: undefined })]);
+      expect(session(database)).toMatchObject({ status: 'active', ended_at: T0 + 100 });
+    } finally {
+      database.close();
+    }
+  });
+});
diff --git a/src/observe/store.ts b/src/observe/store.ts
index 072ee16c1..28d686795 100644
--- a/src/observe/store.ts
+++ b/src/observe/store.ts
@@ -124,14 +124,28 @@ const OBS_UPSERT = `
   WHERE excluded."end" IS NOT NULL OR observations."end" IS NULL
 `;
 
-/** A session row is derived from whatever observations carry its id; there is no session event in the envelope. */
+/**
+ * New activity in a closed (`ended`/`interrupted`) session: the observation's
+ * latest moment (its end, else its start) is past the session's `ended_at`.
+ * A re-sent or reordered event for activity at or before it is not new.
+ */
+const SESSION_REOPENS = `(sessions.status != 'active'
+  AND (sessions.ended_at IS NULL OR COALESCE(excluded.ended_at, excluded.started_at) > sessions.ended_at))`;
+
+/**
+ * A session row is derived from whatever observations carry its id; there is
+ * no session event in the envelope. New activity reopens a closed session as
+ * if it were inserted fresh: `active`, `ended_at` = this observation's end.
+ */
 const SESSION_UPSERT = `
   INSERT INTO sessions (session_id, agent_id, started_at, ended_at, status, updated_at)
   VALUES (?, ?, ?, ?, 'active', ?)
   ON CONFLICT(session_id) DO UPDATE SET
     agent_id = COALESCE(excluded.agent_id, sessions.agent_id),
     started_at = MIN(sessions.started_at, excluded.started_at),
+    status = CASE WHEN ${SESSION_REOPENS} THEN 'active' ELSE sessions.status END,
     ended_at = CASE
+      WHEN ${SESSION_REOPENS} THEN excluded.ended_at
       WHEN excluded.ended_at IS NULL THEN sessions.ended_at
       WHEN sessions.ended_at IS NULL THEN excluded.ended_at
       ELSE MAX(sessions.ended_at, excluded.ended_at)
@@ -491,6 +505,29 @@ export function interruptAgentWork(db: SqlDatabase, agentId: string, now: number
   return { sessions: Number(sessions.changes), observations: interruptOpenObservations(db, agentId, now) };
 }
 
+/** A session's last activity: its observations' latest end (or start), else the row's own `updated_at`. */
+const SESSION_LAST_ACTIVITY = `COALESCE(
+  (SELECT MAX(COALESCE(o."end", o.start)) FROM observations o WHERE o.session_id = sessions.session_id),
+  sessions.updated_at)`;
+
+/**
+ * The idle close: every `active` session with no open observation (`end IS
+ * NULL`) whose last activity is older than `idleMs` becomes `ended`, with
+ * `ended_at` = that last activity (not `now`). `interrupted` sessions are left
+ * alone; new activity reopens an ended one on ingest. Returns how many ended.
+ */
+export function endIdleSessions(db: SqlDatabase, now: number, idleMs: number): number {
+  const result = db
+    .prepare(
+      `UPDATE sessions SET status = 'ended', ended_at = ${SESSION_LAST_ACTIVITY}, updated_at = ?
+       WHERE status = 'active'
+         AND NOT EXISTS (SELECT 1 FROM observations o WHERE o.session_id = sessions.session_id AND o."end" IS NULL)
+         AND ${SESSION_LAST_ACTIVITY} < ?`
+    )
+    .run(now, now - idleMs);
+  return Number(result.changes);
+}
+
 /** Flip one instance's open observations to 'interrupted' and forget the instance. */
 export function interruptInstance(db: SqlDatabase, agentId: string, instanceId: string, now: number): number {
   const result = db
diff --git a/src/observe/sweep.test.ts b/src/observe/sweep.test.ts
index 947875b0d..a2d543cfe 100644
--- a/src/observe/sweep.test.ts
+++ b/src/observe/sweep.test.ts
@@ -471,3 +471,128 @@ describe('retention: the sweep prune pass', () => {
     expect(error.mock.calls.some((args) => String(args[0]).includes('prune'))).toBe(true);
   });
 });
+
+describe('idle sessions: the sweep session pass', () => {
+  const MIN = 60_000;
+  const IDLE = 30 * MIN;
+  const session = (database: SqlDatabase, id: string) =>
+    database.prepare('SELECT status, ended_at, updated_at FROM sessions WHERE session_id = ?').get(id);
+  const sweepAt = (database: SqlDatabase, at: number, sessionIdleMs = IDLE) => {
+    const sweep = startStatusSweep(database, { intervalMs: 0, now: () => at, sessionIdleMs });
+    sweeps.push(sweep);
+    return sweep;
+  };
+
+  it('ends a session whose traces all closed longer ago than the window, at its last activity', () => {
+    const database = db();
+    ingestBatch(
+      database,
+      [
+        obs({ obs_id: 'r1', trace_id: 't1', start: T0, end: T0 + 100 }),
+        obs({ obs_id: 'r2', trace_id: 't2', start: T0 + 1000, end: T0 + 5000 }),
+        obs({ obs_id: 'c2', trace_id: 't2', parent_obs_id: 'r2', start: T0 + 2000, end: T0 + 3000 }),
+      ],
+      T0 + 5000
+    );
+    // still inside the window: stays active
+    sweepAt(database, T0 + 5000 + IDLE - 1);
+    expect(session(database, 's1')?.status).toBe('active');
+    const at = T0 + 5000 + IDLE + 1;
+    sweepAt(database, at);
+    expect(session(database, 's1')).toMatchObject({ status: 'ended', ended_at: T0 + 5000, updated_at: at });
+  });
+
+  it('keeps a session with an open root active however old it is', () => {
+    const database = db();
+    ingestBatch(
+      database,
+      [
+        obs({ obs_id: 'done', trace_id: 't1', start: T0, end: T0 + 100 }),
+        obs({ obs_id: 'open', trace_id: 't2', start: T0 + 200, end: undefined, status: undefined }),
+      ],
+      T0
+    );
+    sweepAt(database, T0 + 100 * IDLE);
+    expect(session(database, 's1')?.status).toBe('active');
+  });
+
+  it('falls back to updated_at for a session no observation references', () => {
+    const database = db();
+    database
+      .prepare("INSERT INTO sessions (session_id, agent_id, started_at, ended_at, status, updated_at) VALUES ('bare', 'a1', ?, NULL, 'active', ?)")
+      .run(T0, T0 + 10);
+    sweepAt(database, T0 + 10 + IDLE + 1);
+    expect(session(database, 'bare')).toMatchObject({ status: 'ended', ended_at: T0 + 10 });
+  });
+
+  it('a window of 0 (or unset) never ends a session', () => {
+    for (const sessionIdleMs of [0, undefined]) {
+      const database = db();
+      ingestBatch(database, [obs()], T0);
+      const sweep = startStatusSweep(database, { intervalMs: 0, now: () => T0 + 1000 * IDLE, ...(sessionIdleMs !== undefined ? { sessionIdleMs } : {}) });
+      sweeps.push(sweep);
+      expect(session(database, 's1')?.status).toBe('active');
+    }
+  });
+
+  it('leaves interrupted sessions alone', () => {
+    const database = db();
+    ingestBatch(database, [obs()], T0);
+    database.prepare("UPDATE sessions SET status = 'interrupted', ended_at = ? WHERE session_id = 's1'").run(T0 + 7);
+    sweepAt(database, T0 + 100 * IDLE);
+    expect(session(database, 's1')).toMatchObject({ status: 'interrupted', ended_at: T0 + 7 });
+  });
+
+  it('a failing session pass does not break the status sweep', () => {
+    const database = db();
+    ingestBatch(database, [heartbeat('a1', T0)], T0);
+    const error = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    const realPrepare = database.prepare.bind(database);
+    vi.spyOn(database, 'prepare').mockImplementation((sql: string) => {
+      if (sql.includes("status = 'ended'")) throw new Error('disk on fire');
+      return realPrepare(sql);
+    });
+    const sweep = sweepAt(database, T0);
+    const result = sweep.run(T0 + 310_000);
+    expect(result.transitions).toEqual([expect.objectContaining({ agent_id: 'a1', to: 'down' })]);
+    expect(error.mock.calls.some((args) => String(args[0]).includes('session'))).toBe(true);
+  });
+
+  it('an ended session past the retention cutoff is pruned with its traces', () => {
+    const database = db();
+    const DAY = 86_400_000;
+    const OLD = T0 - 40 * DAY;
+    ingestBatch(database, [obs({ start: OLD, end: OLD + 100 })], OLD);
+    sweepAt(database, OLD + 100 + IDLE + 1);
+    expect(session(database, 's1')?.status).toBe('ended');
+    expect(pruneBefore(database, T0 - 30 * DAY)).toMatchObject({ observations: 1, sessions: 1 });
+    expect(session(database, 's1')).toBeUndefined();
+  });
+});
+
+describe('idle sessions: the daemon window', () => {
+  const MIN = 60_000;
+  const seeded = (): SqlDatabase => {
+    const database = db();
+    ingestBatch(database, [obs()], T0);
+    return database;
+  };
+  const status = (database: SqlDatabase) => database.prepare("SELECT status FROM sessions WHERE session_id = 's1'").get()?.status;
+
+  it('defaults to 30 minutes', async () => {
+    const database = seeded();
+    const daemon = await start({ db: database, sweepIntervalMs: 0, nowFn: () => T0 + 100 + 30 * MIN - 1, retentionDays: 0 });
+    expect(status(database)).toBe('active');
+    daemon.sweep.run(T0 + 100 + 30 * MIN + 1);
+    expect(status(database)).toBe('ended');
+  });
+
+  it('takes sessionIdleMinutes, and 0 turns the pass off', async () => {
+    const custom = seeded();
+    await start({ db: custom, sweepIntervalMs: 0, nowFn: () => T0 + 100 + 5 * MIN + 1, retentionDays: 0, sessionIdleMinutes: 5 });
+    expect(status(custom)).toBe('ended');
+    const off = seeded();
+    await start({ db: off, sweepIntervalMs: 0, nowFn: () => T0 + 1000 * MIN, retentionDays: 0, sessionIdleMinutes: 0 });
+    expect(status(off)).toBe('active');
+  });
+});
diff --git a/src/observe/sweep.ts b/src/observe/sweep.ts
index 19fd16497..5f754177c 100644
--- a/src/observe/sweep.ts
+++ b/src/observe/sweep.ts
@@ -26,12 +26,19 @@
  * then at most one pass per 24h prune finished traces older than the window
  * (`pruneBefore`; open runs and active sessions are kept). The sweep never
  * VACUUMs - `lousho observe prune` does that on demand.
+ *
+ * Idle sessions close on the same loop: with `sessionIdleMs` > 0, every pass
+ * ends the `active` sessions with no open observation whose last activity is
+ * older than the window (`endIdleSessions`), so retention can prune them and
+ * Threads stops showing finished conversations as live. New activity reopens
+ * one on ingest (store.ts).
  */
 
 import type { SqlDatabase } from '../storage/sqlite/driver';
 import type { AlertEvent } from './alerts';
 import {
   HEARTBEAT_INTERVAL_DEFAULT_MS,
+  endIdleSessions,
   freshnessStatus,
   heartbeatIntervalFromMeta,
   interruptAgentWork,
@@ -217,6 +224,12 @@ export interface StatusSweepOptions {
    * enables it: unset, `0`, a negative value or `NaN` never prunes.
    */
   retentionDays?: number;
+  /**
+   * Idle window in ms: each pass ends `active` sessions with no open
+   * observation and no activity for this long. Only a finite number `> 0`
+   * enables it: unset, `0`, a negative value or `NaN` never ends a session.
+   */
+  sessionIdleMs?: number;
 }
 
 export interface StatusSweep {
@@ -225,6 +238,25 @@ export interface StatusSweep {
   stop(): void;
 }
 
+/**
+ * The session pass {@link startStatusSweep} runs first each tick: before the
+ * prune (a session idle past the retention window goes in the same pass) and
+ * before the status pass, so a session that finished cleanly ends as `ended`
+ * rather than `interrupted` when its agent goes down in this pass. Kept apart
+ * like the prune: a failure is logged and never costs the pass its alerts.
+ */
+function idleSessionPass(db: SqlDatabase, idleMs: number | undefined): (at: number) => void {
+  // Anything but a finite positive number (unset, 0, negative, NaN) disables it.
+  if (idleMs === undefined || !Number.isFinite(idleMs) || idleMs <= 0) return () => undefined;
+  return (at) => {
+    try {
+      endIdleSessions(db, at, idleMs);
+    } catch (error) {
+      console.error('[lousho observe] idle session pass failed:', error);
+    }
+  };
+}
+
 /**
  * The daemon's sweep loop. The first pass runs immediately: agents that died
  * while the daemon was down are marked (and reported) at boot, not one
@@ -250,7 +282,9 @@ export function startStatusSweep(db: SqlDatabase, options: StatusSweepOptions =
       console.error('[lousho observe] retention prune failed:', error);
     }
   };
+  const endIdle = idleSessionPass(db, options.sessionIdleMs);
   const run = (at: number = now()): SweepResult => {
+    endIdle(at);
     prune(at);
     const result = sweepAgents(db, at, {
       ...(options.errorRateThreshold !== undefined ? { errorRateThreshold: options.errorRateThreshold } : {}),

From 41591989e20788dab64fcc2b5166ffed3ee6f472 Mon Sep 17 00:00:00 2001
From: Ali Mohammad <freelancealimohammad@gmail.com>
Date: Thu, 29 Oct 2026 00:18:32 +0300
Subject: [PATCH 2/2] fix(observe): interrupted runs do not keep a session open

The idle pass treated a run the sweep marked 'interrupted' (end still
NULL) as open, so a session whose process died while its agent stayed
healthy never ended. Such a run now no longer blocks the close, and it
counts as activity at its interrupt time (its updated_at), so the idle
window starts there instead of at the dead run's old start.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/cli.md               |  2 +-
 docs/observability.md     |  4 +++-
 llms-full.txt             |  6 ++++--
 src/observe/store.ts      | 26 +++++++++++++++++++------
 src/observe/sweep.test.ts | 41 +++++++++++++++++++++++++++++++++++++++
 5 files changed, 69 insertions(+), 10 deletions(-)

diff --git a/docs/cli.md b/docs/cli.md
index ba051535b..f2c14ee16 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -309,7 +309,7 @@ error (exit 2). See [Retention](./observability.md#retention).
 `start --session-idle-minutes N` sets when a conversation counts as finished
 (default 30; `0` turns it off, so a session stays `active` until its agent goes
 down). The daemon's sweep marks a session `ended` once none of its runs is
-still open and nothing in it has started or finished for N minutes; its
+still open (a run marked `interrupted` does not count) and nothing in it has started or finished for N minutes; its
 `ended_at` is the time of that last activity. A new run in an `ended` (or
 `interrupted`) session makes it `active` again. Ended sessions are then pruned
 by `--retention-days` like any other finished session. A bad N is a usage
diff --git a/docs/observability.md b/docs/observability.md
index d8971ae57..d7dc3e538 100644
--- a/docs/observability.md
+++ b/docs/observability.md
@@ -708,7 +708,9 @@ runs carry its id, so the daemon decides when a conversation is over. Each
 sweep (every 30 s) marks a session `ended` when none of its runs is still open
 (a run in progress keeps it `active` however long it takes) and nothing in it
 has started or finished for `--session-idle-minutes` (default 30; `0` turns
-this off). Its `ended_at` is the time of that last activity, not the time of
+this off). A run marked `interrupted` (its process died while the agent kept
+running) no longer counts as in progress; it counts as activity at the moment
+it was interrupted. Its `ended_at` is the time of that last activity, not the time of
 the sweep. A session no run references falls back to when the daemon last
 updated it. Sessions in a db written by an older daemon close on the first
 sweep that finds them idle.
diff --git a/llms-full.txt b/llms-full.txt
index 835a28515..0e58e1429 100644
--- a/llms-full.txt
+++ b/llms-full.txt
@@ -5264,7 +5264,7 @@ error (exit 2). See [Retention](https://github.com/LinuxDevil/agent-sdk/blob/mai
 `start --session-idle-minutes N` sets when a conversation counts as finished
 (default 30; `0` turns it off, so a session stays `active` until its agent goes
 down). The daemon's sweep marks a session `ended` once none of its runs is
-still open and nothing in it has started or finished for N minutes; its
+still open (a run marked `interrupted` does not count) and nothing in it has started or finished for N minutes; its
 `ended_at` is the time of that last activity. A new run in an `ended` (or
 `interrupted`) session makes it `active` again. Ended sessions are then pruned
 by `--retention-days` like any other finished session. A bad N is a usage
@@ -14583,7 +14583,9 @@ runs carry its id, so the daemon decides when a conversation is over. Each
 sweep (every 30 s) marks a session `ended` when none of its runs is still open
 (a run in progress keeps it `active` however long it takes) and nothing in it
 has started or finished for `--session-idle-minutes` (default 30; `0` turns
-this off). Its `ended_at` is the time of that last activity, not the time of
+this off). A run marked `interrupted` (its process died while the agent kept
+running) no longer counts as in progress; it counts as activity at the moment
+it was interrupted. Its `ended_at` is the time of that last activity, not the time of
 the sweep. A session no run references falls back to when the daemon last
 updated it. Sessions in a db written by an older daemon close on the first
 sweep that finds them idle.
diff --git a/src/observe/store.ts b/src/observe/store.ts
index 28d686795..89f6f6f32 100644
--- a/src/observe/store.ts
+++ b/src/observe/store.ts
@@ -505,23 +505,37 @@ export function interruptAgentWork(db: SqlDatabase, agentId: string, now: number
   return { sessions: Number(sessions.changes), observations: interruptOpenObservations(db, agentId, now) };
 }
 
-/** A session's last activity: its observations' latest end (or start), else the row's own `updated_at`. */
+/**
+ * A run the sweep gave up on: `end` still unset, but marked `interrupted`
+ * (its process died). It no longer holds a session open. `IS`, not `=`: an
+ * open run's status is NULL, and `NOT (... = ...)` on NULL would hide it.
+ */
+const DEAD_RUN = `(o."end" IS NULL AND o.status IS 'interrupted')`;
+
+/**
+ * A session's last activity: its observations' latest end (or start), else
+ * the row's own `updated_at`. An interrupted run counts from when it was
+ * interrupted (its `updated_at`, which the interrupt writes), so the idle
+ * window starts there rather than at the dead run's old start.
+ */
 const SESSION_LAST_ACTIVITY = `COALESCE(
-  (SELECT MAX(COALESCE(o."end", o.start)) FROM observations o WHERE o.session_id = sessions.session_id),
+  (SELECT MAX(CASE WHEN ${DEAD_RUN} THEN MAX(o.start, o.updated_at) ELSE COALESCE(o."end", o.start) END)
+     FROM observations o WHERE o.session_id = sessions.session_id),
   sessions.updated_at)`;
 
 /**
  * The idle close: every `active` session with no open observation (`end IS
- * NULL`) whose last activity is older than `idleMs` becomes `ended`, with
- * `ended_at` = that last activity (not `now`). `interrupted` sessions are left
- * alone; new activity reopens an ended one on ingest. Returns how many ended.
+ * NULL` and not `interrupted`) whose last activity is older than `idleMs`
+ * becomes `ended`, with `ended_at` = that last activity (not `now`).
+ * `interrupted` sessions are left alone; new activity reopens an ended one on
+ * ingest. Returns how many ended.
  */
 export function endIdleSessions(db: SqlDatabase, now: number, idleMs: number): number {
   const result = db
     .prepare(
       `UPDATE sessions SET status = 'ended', ended_at = ${SESSION_LAST_ACTIVITY}, updated_at = ?
        WHERE status = 'active'
-         AND NOT EXISTS (SELECT 1 FROM observations o WHERE o.session_id = sessions.session_id AND o."end" IS NULL)
+         AND NOT EXISTS (SELECT 1 FROM observations o WHERE o.session_id = sessions.session_id AND o."end" IS NULL AND NOT ${DEAD_RUN})
          AND ${SESSION_LAST_ACTIVITY} < ?`
     )
     .run(now, now - idleMs);
diff --git a/src/observe/sweep.test.ts b/src/observe/sweep.test.ts
index a2d543cfe..6e0cbf4b9 100644
--- a/src/observe/sweep.test.ts
+++ b/src/observe/sweep.test.ts
@@ -525,6 +525,47 @@ describe('idle sessions: the sweep session pass', () => {
     expect(session(database, 'bare')).toMatchObject({ status: 'ended', ended_at: T0 + 10 });
   });
 
+  it('an instance interrupted while its sibling stays healthy no longer holds the session open', () => {
+    const database = db();
+    const beat = (instance: string, ts: number, pid: number): IngestEvent => ({
+      type: 'agent.heartbeat',
+      data: { agent_id: 'a1', project: 'proj', name: 'a', ts, heartbeat_interval_ms: 60_000, instance_id: instance, hostname: 'h1', pid },
+    });
+    ingestBatch(database, [beat('A', T0, 100), beat('B', T0, 200)], T0);
+    ingestBatch(database, [obs({ obs_id: 'runA', end: undefined, status: undefined, attrs: { 'lousho.instance_id': 'A' } })], T0);
+    const sweep = sweepAt(database, T0);
+    // only B keeps heartbeating, so the sweep interrupts A's open run
+    const tick = (t: number) => {
+      ingestBatch(database, [beat('B', t, 200)], t);
+      sweep.run(t);
+    };
+    for (let t = T0 + 60_000; t <= T0 + 600_000; t += 60_000) tick(t);
+    const runA = database.prepare("SELECT status, updated_at FROM observations WHERE obs_id = 'runA'").get();
+    expect(runA?.status).toBe('interrupted');
+    const interruptedAt = Number(runA?.updated_at);
+    expect(interruptedAt).toBeGreaterThan(T0);
+    // the idle window counts from the interrupt, not from the run's old start
+    tick(interruptedAt + IDLE - 1);
+    expect(session(database, 's1')?.status).toBe('active');
+    tick(interruptedAt + IDLE + 1);
+    expect(session(database, 's1')).toMatchObject({ status: 'ended', ended_at: interruptedAt });
+  });
+
+  it('an interrupted run beside a genuinely open one keeps the session active', () => {
+    const database = db();
+    ingestBatch(
+      database,
+      [
+        obs({ obs_id: 'dead', trace_id: 't1', end: undefined, status: undefined }),
+        obs({ obs_id: 'live', trace_id: 't2', end: undefined, status: undefined }),
+      ],
+      T0
+    );
+    database.prepare("UPDATE observations SET status = 'interrupted', updated_at = ? WHERE obs_id = 'dead'").run(T0 + 1);
+    sweepAt(database, T0 + 100 * IDLE);
+    expect(session(database, 's1')?.status).toBe('active');
+  });
+
   it('a window of 0 (or unset) never ends a session', () => {
     for (const sessionIdleMs of [0, undefined]) {
       const database = db();