@gotcos/glasses-server 7.0.7 → 7.0.27

package/server/lib/agent-session-recent.ts

@@ -0,0 +1,321 @@
+/**
+ * "Recent activity first" for the Today summary (Miles, 2026-11-09): what was said INTO a session lately and where its
+ * latest reply left off, with when, so the summary describes what a session is doing now instead of its first prompt.
+ *
+ * Why: each session's list `line` (composeDiscussionSummary) is its FIRST prompt plus the latest reply, cut at 180
+ * characters. On 11/09 the Codex orchestrator's line led with an ask from 10/11, 29 days old, and the model wrote
+ * "following up a transcription bakeoff" about a session that had just confirmed a release was live.
+ *
+ * readRecentActivity(provider, file, now) answers the last few asks (each with when and how it arrived), the latest
+ * reply and when the session last moved. Read-only display evidence: never imported by an attach, queue or write gate.
+ *
+ * - Claude: the last 8 MB of the transcript, memoized on mtime and size like readClaudeSubagents. User turns follow
+ *   parseAgentSession's rules: sidechains, `isMeta` and `isCompactSummary` rows are not asks (a peer row is, unwrapped
+ *   by unwrapPeerMessage), the verify footer comes off (withoutTurnFooter), wrapper tags go (STRIPPABLE_TAG_RE) and a
+ *   pasted JSON block becomes "[pasted data]". A peer row, or a row that carried a COS verify footer, arrived from
+ *   another screen or session: `via: 'peer'`, never attributed to the person. A peer row that is agent-to-agent
+ *   protocol (a cross-session or agent-message envelope) is not an ask at all.
+ * - Codex: rollouts reach 32 GB with single lines of 44 MB (measured 11/09). An incremental forward scan keeps its byte
+ *   offset in memory; the first pass reads at most the last 256 MB; a line over 1 MB is skipped without being decoded
+ *   or parsed; reads are async, 4 MB at a time, and the scan yields between chunks. One scan per file at a time: a
+ *   second caller waits on the first, and a scan the Today route stopped waiting for still finishes and fills the memo.
+ *   Codex rows carry no sender marker, so only a COS verify footer marks one as sent in from another screen.
+ * - Cursor: the existing tail peek (the last user query and reply); its transcript has no timestamps, so every time is
+ *   the file's mtime.
+ *
+ * `startedAt` and `firstAsk` are set only for a session whose file was created within the last day, for the
+ * "started today as" note. Opens refuse symlinks and non-regular files. Never throws: null when unreadable.
+ */
+import { constants } from 'node:fs'
+import { open, stat } from 'node:fs/promises'
+import {
+  STRIPPABLE_TAG_RE, createdFromCodexFilename, firstClaudeUserTitle, firstCursorUserTitle, isWrapperPrompt, parseJsonLine,
+  payloadText, codexUserText, peekCodexMeta, peekCursorDiscussion, proseSnippet, type AgentProvider,
+} from './agent-session-store.js'
+import { unwrapPeerMessage } from './session-stream-events.js'
+import { stripG2TurnFooter } from './turn-footer.js'
+
+export type RecentVia = 'typed' | 'peer'
+export interface RecentAsk { at: number; text: string; via: RecentVia }
+export interface RecentReply { at: number; text: string }
+export interface RecentActivity {
+  /** The newest asks into the session, oldest first, at most RECENT_ASKS_KEPT. */
+  asks: RecentAsk[]
+  /** The newest assistant reply (Codex: its newest final answer, not commentary). */
+  reply: RecentReply | null
+  /** The newest record's time (ms), 0 when none was seen. */
+  movedAt: number
+  /** Only for a session created within the last day: when, and its first ask. */
+  startedAt?: number
+  firstAsk?: string
+}
+
+export const RECENT_ASKS_KEPT = 3
+export const CLAUDE_RECENT_TAIL_BYTES = 8 * 1024 * 1024
+export const CODEX_FIRST_PASS_BYTES = 256 * 1024 * 1024
+/** A line longer than this is skipped unparsed (a 44 MB Codex line holds tool output, never an ask). */
+export const RECENT_LINE_MAX_BYTES = 1024 * 1024
+export const RECENT_CHUNK_BYTES = 4 * 1024 * 1024
+const TEXT_KEEP = 1000
+const MEMO_MAX = 64
+const DAY_MS = 24 * 60 * 60 * 1000
+
+// ── text ───────────────────────────────────────────────────────────────────
+
+const PASTED = /<pasted_content\b[^>]*>([\s\S]*?)<\/pasted_content\b[^>]*>/gi
+const WRAPPER_BLOCKS = /<(task-notification|system-reminder|relevant-memories|cache-health|daily-bulletin|cos-alarms|device-handoff|now|memory-stored|local-command-stdout|local-command-stderr|command-name|command-message|command-args|user_query)\b[^>]*>[\s\S]*?<\/\1>/gi
+/** A peer row that is agent-to-agent protocol, not words for the session. */
+const AGENT_ENVELOPE = /^\s*(?:<(?:cross-session-message|agent-message)\b|Message Type:|Subagent hand-?back\b)/i
+/** A paragraph that is pasted data: it opens with { or [ and holds a "key": pair. */
+const JSON_PARAGRAPH = /^\s*[[{][\s\S]*"\s*:/
+
+/** One ask's words: pasted data replaced, wrapper blocks and tags out, one line, bounded. '' when nothing is left. */
+export function cleanAskText(raw: string): string {
+  // Whole wrapper blocks go first (a background task's notification, a reminder, a slash command's parts). What is left
+  // is then judged as parseAgentSession's collectTurn judges a turn: still a wrapper (it opens with a tag the block list
+  // does not know), it is not an ask, and no tag is taken off so that its insides could read as words.
+  let s = raw.replace(WRAPPER_BLOCKS, ' ').replace(PASTED, (_m, inner: string) => {
+    const t = String(inner).trim()
+    return t.startsWith('{') || t.startsWith('[') ? '\n\n[pasted data]\n\n' : ` ${t} `
+  })
+  if (!s.trim() || isWrapperPrompt(s)) return ''
+  s = s.split(/\n\s*\n/).map(p => (JSON_PARAGRAPH.test(p) ? '[pasted data]' : p)).join('\n\n')
+  s = s.replace(STRIPPABLE_TAG_RE, ' ').replace(/\s+/g, ' ').trim()
+  if (!s || isWrapperPrompt(s) || s.startsWith('[Request interrupted') || s.startsWith('[image: source')) return ''
+  return s.slice(0, TEXT_KEEP)
+}
+
+/** An ask's words and how it arrived: a footer means another screen (glasses, phone or web) sent it. */
+function footerVia(text: string, peer: boolean): { text: string; via: RecentVia } {
+  const f = stripG2TurnFooter(text)
+  return { text: f.text, via: peer || f.turnId ? 'peer' : 'typed' }
+}
+
+const tsOf = (v: unknown): number => (typeof v === 'string' ? Date.parse(v) || 0 : 0)
+
+interface Collector { asks: RecentAsk[]; reply: RecentReply | null; movedAt: number }
+const emptyCollector = (): Collector => ({ asks: [], reply: null, movedAt: 0 })
+function addAsk(c: Collector, ask: RecentAsk) {
+  c.asks.push(ask)
+  if (c.asks.length > RECENT_ASKS_KEPT) c.asks.shift()
+}
+const moved = (c: Collector, at: number) => { if (at > c.movedAt) c.movedAt = at }
+
+/** One Claude record into the collector (parseAgentSession's user-turn rules). */
+export function collectClaudeRecord(c: Collector, obj: Record<string, unknown>): void {
+  if (obj.isSidechain === true) return
+  const at = tsOf(obj.timestamp)
+  if (at && (obj.type === 'user' || obj.type === 'assistant' || obj.type === 'system')) moved(c, at)
+  if (obj.type !== 'user' && obj.type !== 'assistant') return
+  if (obj.type === 'user' && obj.toolUseResult) return
+  const message = obj.message && typeof obj.message === 'object' ? obj.message as Record<string, unknown> : null
+  const text = message ? payloadText(message) : null
+  if (!text) return
+  if (obj.type === 'assistant') {
+    const prose = proseSnippet(text, TEXT_KEEP)
+    if (prose) c.reply = { at, text: prose }
+    return
+  }
+  const isPeer = (obj.origin as { kind?: unknown } | undefined)?.kind === 'peer'
+  const peerWords = isPeer ? unwrapPeerMessage(text) : null
+  // Injected rows (a slash-command body, a compaction preamble) are not asks; a peer row is, once unwrapped.
+  if (peerWords === null && (obj.isMeta === true || obj.isCompactSummary === true)) return
+  if (peerWords !== null && AGENT_ENVELOPE.test(peerWords)) return
+  const { text: words, via } = footerVia(peerWords ?? text, peerWords !== null)
+  const clean = cleanAskText(words)
+  if (clean) addAsk(c, { at, text: clean, via })
+}
+
+/** One Codex rollout line into the collector. The caller has already checked its size. */
+export function collectCodexLine(c: Collector, line: Buffer): void {
+  const head = line.subarray(0, 512).toString('utf8')
+  const stamp = /"timestamp":"([^"]{10,40})"/.exec(head)
+  const at = stamp ? Date.parse(stamp[1]!) || 0 : 0
+  if (at) moved(c, at)
+  // Role and type sit before the content in a rollout line, so the head decides without decoding the rest.
+  if (!head.includes('"type":"message"') || !(head.includes('"role":"user"') || head.includes('"role":"assistant"'))) return
+  const obj = parseJsonLine(line.toString('utf8'))
+  if (!obj || obj.type !== 'response_item' || !obj.payload || typeof obj.payload !== 'object') return
+  const p = obj.payload as Record<string, unknown>
+  if (p.type !== 'message') return
+  if (p.role === 'assistant') {
+    if (p.phase === 'commentary') return
+    const text = payloadText(p)
+    const prose = text ? proseSnippet(text, TEXT_KEEP) : ''
+    if (prose) c.reply = { at, text: prose }
+    return
+  }
+  if (p.role !== 'user') return
+  const text = codexUserText(p)
+  if (!text || isWrapperPrompt(text)) return
+  const { text: words, via } = footerVia(text, false)
+  const clean = cleanAskText(words)
+  if (clean) addAsk(c, { at, text: clean, via })
+}
+
+// ── reads ──────────────────────────────────────────────────────────────────
+
+type Handle = Awaited<ReturnType<typeof open>>
+async function openRegular(file: string): Promise<{ handle: Handle; size: number; mtimeMs: number; birthtimeMs: number; ino: number } | null> {
+  let handle: Handle | null = null
+  try {
+    handle = await open(file, constants.O_RDONLY | (constants.O_NONBLOCK ?? 0) | (constants.O_NOFOLLOW ?? 0))
+    const st = await handle.stat()
+    if (!st.isFile()) { await handle.close().catch(() => {}); return null }
+    return { handle, size: st.size, mtimeMs: st.mtimeMs, birthtimeMs: st.birthtimeMs, ino: st.ino }
+  } catch {
+    await handle?.close().catch(() => {})
+    return null
+  }
+}
+const yieldLoop = () => new Promise<void>(resolve => setImmediate(resolve))
+
+const claudeMemo = new Map<string, { mtimeMs: number; size: number; value: Collector }>()
+const remember = <V>(memo: Map<string, V>, key: string, value: V) => {
+  if (!memo.has(key) && memo.size >= MEMO_MAX) memo.delete(memo.keys().next().value!)
+  memo.set(key, value)
+}
+
+/** A Claude transcript's tail (8 MB), memoized on mtime and size. */
+async function readClaude(file: string, tailBytes = CLAUDE_RECENT_TAIL_BYTES): Promise<{ c: Collector; birthtimeMs: number } | null> {
+  const opened = await openRegular(file)
+  if (!opened) return null
+  const { handle, size, mtimeMs, birthtimeMs } = opened
+  try {
+    const hit = claudeMemo.get(file)
+    if (hit && hit.mtimeMs === mtimeMs && hit.size === size) return { c: hit.value, birthtimeMs }
+    const length = Math.min(size, tailBytes), start = size - length
+    const buffer = Buffer.alloc(length)
+    const read = await handle.read(buffer, 0, length, start)
+    const data = buffer.subarray(0, read.bytesRead)
+    const c = emptyCollector()
+    let pos = 0, n = 0
+    // A tail that starts mid-file has a cut first line: it fails to parse and is skipped like any bad line.
+    while (pos < data.length) {
+      let end = data.indexOf(0x0a, pos)
+      if (end < 0) end = data.length
+      if (end - pos > 0 && end - pos <= RECENT_LINE_MAX_BYTES) {
+        const obj = parseJsonLine(data.subarray(pos, end).toString('utf8'))
+        if (obj) collectClaudeRecord(c, obj)
+      }
+      pos = end + 1
+      if (++n % 2000 === 0) await yieldLoop()
+    }
+    remember(claudeMemo, file, { mtimeMs, size, value: c })
+    return { c, birthtimeMs }
+  } catch {
+    return null
+  } finally {
+    await handle.close().catch(() => {})
+  }
+}
+
+interface CodexScan { offset: number; size: number; partial: Buffer | null; skipping: boolean; c: Collector; running: Promise<void> | null; ino: number }
+const codexMemo = new Map<string, CodexScan>()
+
+/** Test seam: forget every memo (a new server process starts with none). */
+export function resetRecentActivityMemo(): void { claudeMemo.clear(); codexMemo.clear() }
+/** Test seam: the bytes of an unfinished line a Codex scan holds for its next read (never more than the line bound). */
+export function codexScanHeldBytes(file: string): number { return codexMemo.get(file)?.partial?.length ?? 0 }
+
+/**
+ * Scan a Codex rollout forward from where the last scan stopped. A first pass, or a gap past `firstPassBytes`, starts
+ * that far from the end and drops the line it lands inside.
+ */
+async function scanCodex(file: string, firstPassBytes: number, chunkBytes: number): Promise<CodexScan | null> {
+  const opened = await openRegular(file)
+  if (!opened) return null
+  const { handle, size, ino } = opened
+  try {
+    let scan = codexMemo.get(file)
+    if (scan && (scan.ino !== ino || size < scan.offset)) scan = undefined   // replaced or truncated: start over
+    if (!scan) {
+      scan = { offset: 0, size: 0, partial: null, skipping: false, c: emptyCollector(), running: null, ino }
+      remember(codexMemo, file, scan)
+    }
+    if (scan.running) { await scan.running; return scan }
+    const s = scan
+    const run = (async () => {
+      if (size - s.offset > firstPassBytes) {
+        s.offset = size - firstPassBytes
+        s.partial = null
+        s.skipping = s.offset > 0   // landed mid-line: that line is not whole
+      }
+      while (s.offset < size) {
+        const length = Math.min(chunkBytes, size - s.offset)
+        const chunk = Buffer.alloc(length)
+        const { bytesRead } = await handle.read(chunk, 0, length, s.offset)
+        if (bytesRead <= 0) break
+        s.offset += bytesRead
+        let buf = chunk.subarray(0, bytesRead)
+        if (s.partial) { buf = Buffer.concat([s.partial, buf]); s.partial = null }
+        let pos = 0
+        for (let nl = buf.indexOf(0x0a, pos); nl >= 0; nl = buf.indexOf(0x0a, pos)) {
+          if (s.skipping) s.skipping = false
+          else if (nl - pos > 0 && nl - pos <= RECENT_LINE_MAX_BYTES) collectCodexLine(s.c, buf.subarray(pos, nl))
+          pos = nl + 1
+        }
+        const rest = buf.subarray(pos)
+        // An unfinished line past the bound is never kept: the rest of it is skipped up to its newline. While skipping
+        // (no newline in this chunk at all), nothing is kept either.
+        if (!s.skipping) {
+          if (rest.length > RECENT_LINE_MAX_BYTES) s.skipping = true
+          else if (rest.length) s.partial = Buffer.from(rest)
+        }
+        await yieldLoop()
+      }
+      s.size = size
+    })()
+    s.running = run
+    try { await run } finally { s.running = null }
+    return s
+  } catch {
+    return null
+  } finally {
+    await handle.close().catch(() => {})
+  }
+}
+
+export interface RecentReadOptions { claudeTailBytes?: number; codexFirstPassBytes?: number; chunkBytes?: number }
+
+/** What was said into one session lately, its latest reply and when it last moved, or null when it cannot be read. */
+export async function readRecentActivity(provider: AgentProvider, file: string, now = Date.now(), opts: RecentReadOptions = {}): Promise<RecentActivity | null> {
+  try {
+    let c: Collector, createdAt = 0, firstAsk = ''
+    if (provider === 'claude') {
+      const r = await readClaude(file, opts.claudeTailBytes)
+      if (!r) return null
+      c = r.c
+      createdAt = r.birthtimeMs
+      if (createdAt && now - createdAt < DAY_MS) firstAsk = (await firstClaudeUserTitle(file)) ?? ''
+    } else if (provider === 'codex') {
+      const s = await scanCodex(file, opts.codexFirstPassBytes ?? CODEX_FIRST_PASS_BYTES, opts.chunkBytes ?? RECENT_CHUNK_BYTES)
+      if (!s) return null
+      c = s.c
+      createdAt = Date.parse(createdFromCodexFilename(file.split('/').pop() ?? '') ?? '') || 0
+      if (createdAt && now - createdAt < DAY_MS) firstAsk = (await peekCodexMeta(file))?.title ?? ''
+    } else {
+      const st = await stat(file).catch(() => null)
+      if (!st?.isFile()) return null
+      const peek = await peekCursorDiscussion(file)
+      const at = st.mtimeMs
+      c = { asks: [], reply: null, movedAt: at }
+      const ask = peek.lastUser ? cleanAskText(peek.lastUser) : ''
+      if (ask) c.asks.push({ at, text: ask, via: 'typed' })
+      const reply = peek.latestAssistant ? proseSnippet(peek.latestAssistant, TEXT_KEEP) : ''
+      if (reply) c.reply = { at, text: reply }
+      createdAt = st.birthtimeMs
+      if (createdAt && now - createdAt < DAY_MS) firstAsk = (await firstCursorUserTitle(file)) ?? ''
+    }
+    // Copies, so a caller can never edit the memo.
+    const out: RecentActivity = {
+      asks: c.asks.filter(a => a.at <= now).map(a => ({ ...a })),
+      reply: c.reply && c.reply.at <= now ? { ...c.reply } : null,
+      movedAt: c.movedAt,
+    }
+    if (firstAsk && createdAt) { out.startedAt = createdAt; out.firstAsk = firstAsk }
+    return out
+  } catch {
+    return null
+  }
+}

package/server/lib/agent-session-store.ts

@@ -35,6 +35,16 @@ export interface AgentSessionListDropped {
   age: number
   limit: number
   oversized: number
+  /** Step 2a (Q1 FIX 1): kept rows (COS pins, folder members, COS-started sessions) past KEPT_LIST_MAX. Present only
+   *  when something was dropped, so an older reader of `dropped` sees the shape it knows. */
+  kept?: number
+}
+
+/** Step 2a (Q1 FIX 1): the most kept rows one list answer carries, on top of `limit`. Native pins are not counted
+ *  here; they stay inside `limit` as before. */
+export const KEPT_LIST_MAX = 40
+function countKeptOverflow(dropped: AgentSessionListDropped, n: number): void {
+  if (n > 0) dropped.kept = (dropped.kept ?? 0) + n
 }
 
 export function emptySessionListDropped(): AgentSessionListDropped {
@@ -250,7 +260,7 @@ const STRIPPABLE_TAGS = [
   'local-command-stdout', 'local-command-stderr', 'thinking',
 ]
 
-const STRIPPABLE_TAG_RE = new RegExp(`</?(?:${STRIPPABLE_TAGS.join('|')})(?:\\s[^>]*)?/?>`, 'gi')
+export const STRIPPABLE_TAG_RE = new RegExp(`</?(?:${STRIPPABLE_TAGS.join('|')})(?:\\s[^>]*)?/?>`, 'gi')
 
 /**
  * Fenced code and known tags out. Shared so `proseSnippet` and `latestAssistantReply`
@@ -995,7 +1005,7 @@ export async function peekCodexMeta(path: string): Promise<{ id: string; cwd: st
   return { id, cwd, title, subagent, created }
 }
 
-async function peekCursorDiscussion(path: string): Promise<{ lastUser: string | null; latestAssistant: string }> {
+export async function peekCursorDiscussion(path: string): Promise<{ lastUser: string | null; latestAssistant: string }> {
   const text = await readWindow(path, true)
   let lastUser: string | null = null
   for (const line of text.split('\n')) {
@@ -1010,7 +1020,7 @@ async function peekCursorDiscussion(path: string): Promise<{ lastUser: string |
   return { lastUser, latestAssistant: latestAssistantFromWindow(text) }
 }
 
-async function firstCursorUserTitle(path: string): Promise<string | null> {
+export async function firstCursorUserTitle(path: string): Promise<string | null> {
   const text = await readWindow(path, false)
   let fallback: string | null = null
   for (const line of text.split('\n')) {
@@ -1058,6 +1068,11 @@ export async function listClaudeSessions(
   desktopSessionsRoot = '',
   dropped: AgentSessionListDropped = emptySessionListDropped(),
   preloadedAliases?: ClaudeAliasMap,
+  /** Step 2a: canonical ids the COS organizer keeps (COS pins, folder members). Listed at any age and outside `cap`,
+   *  like a native pin, but `pinned` stays the native star only. */
+  keep: ReadonlySet<string> = new Set(),
+  /** Which kept ids win when KEPT_LIST_MAX must choose: lower first (0 COS pins and folders, 1 COS-started). */
+  keepRank: (id: string) => number = () => 0,
 ): Promise<AgentSessionRow[]> {
   const aliases = preloadedAliases ?? await loadClaudeDesktopAliases(desktopSessionsRoot)
   const canonical = (id: string) => { const cli = aliases.get(id)?.cliSessionId; return cli && CLAUDE_UUID_JSONL.test(cli + '.jsonl') ? cli : id }
@@ -1072,6 +1087,7 @@ export async function listClaudeSessions(
   const seen = new Set<string>()
   const pinnedCandidates: Array<{ file: string; native: string; project: string; mtimeMs: number; birthtimeMs: number; desktop?: string }> = []
   const recentCandidates: Array<{ file: string; native: string; project: string; mtimeMs: number; birthtimeMs: number; desktop?: string }> = []
+  const keptCandidates: typeof recentCandidates = []
   for (const folder of await dirents(projectsRoot)) {
     const dir = join(projectsRoot, folder)
     const dirSt = await fileStat(dir)
@@ -1084,7 +1100,9 @@ export async function listClaudeSessions(
       const file = join(dir, name)
       const st = await fileStat(file)
       if (!st?.isFile) continue
-      const pinned = canonicalStars.has(native.toLowerCase())
+      const starred = canonicalStars.has(native.toLowerCase())
+      const kept = !starred && keep.has(native.toLowerCase())
+      const pinned = starred || kept
       const fresh = now.getTime() - st.mtimeMs <= AGENT_SESSION_MAX_AGE_MS
       if (!pinned && !fresh) {
         dropped.age += 1
@@ -1099,17 +1117,18 @@ export async function listClaudeSessions(
         desktop: desktopByCli.get(native)?.file,
       }
       seen.add(native.toLowerCase())
-      if (pinned) pinnedCandidates.push(candidate)
+      if (starred) pinnedCandidates.push(candidate)
+      else if (kept) keptCandidates.push(candidate)
       else recentCandidates.push(candidate)
     }
   }
-  for (const starred of canonicalStars) {
+  for (const starred of new Set([...canonicalStars, ...keep])) {
     if (seen.has(starred) || canonicalLive.has(starred) || canonicalLive.has(starred.slice(0, 8))) continue
     const desktop = desktopByCli.get(starred)?.file
     if (!desktop) continue
     const st = await fileStat(desktop)
     if (!st?.isFile) continue
-    pinnedCandidates.push({
+    ;(canonicalStars.has(starred) ? pinnedCandidates : keptCandidates).push({
       file: '',
       native: starred,
       project: '',
@@ -1120,6 +1139,7 @@ export async function listClaudeSessions(
     seen.add(starred)
   }
   pinnedCandidates.sort((a, b) => b.mtimeMs - a.mtimeMs)
+  keptCandidates.sort((a, b) => (keepRank(a.native.toLowerCase()) - keepRank(b.native.toLowerCase())) || b.mtimeMs - a.mtimeMs)
   recentCandidates.sort((a, b) => b.mtimeMs - a.mtimeMs)
 
   const toRows = async (candidates: typeof recentCandidates, limit: number): Promise<AgentSessionRow[]> => {
@@ -1166,8 +1186,13 @@ export async function listClaudeSessions(
     return rows
   }
 
+  const keptLimitBefore = dropped.limit
+  const keptRows = await toRows(keptCandidates, KEPT_LIST_MAX)
+  countKeptOverflow(dropped, dropped.limit - keptLimitBefore)
+  dropped.limit = keptLimitBefore
   return [
     ...await toRows(pinnedCandidates, Math.max(pinnedCandidates.length, 0)),
+    ...keptRows,
     ...await toRows(recentCandidates, Math.max(0, cap)),
   ]
 }
@@ -1177,27 +1202,36 @@ export async function listCodexSessions(
   now: Date,
   cap = AGENT_SESSION_PER_PROVIDER_LIMIT,
   dropped: AgentSessionListDropped = emptySessionListDropped(),
+  /** Step 2a: thread ids the COS organizer keeps; see listClaudeSessions. */
+  keep: ReadonlySet<string> = new Set(),
+  keepRank: (id: string) => number = () => 0,
 ): Promise<AgentSessionRow[]> {
   const names = await loadCodexThreadNames(sessionsRoot)
   const pinnedIds = await loadCodexPinnedIds(sessionsRoot)
   const pinnedCandidates: Array<{ file: string; name: string; mtimeMs: number; birthtimeMs: number }> = []
   const recentCandidates: Array<{ file: string; name: string; mtimeMs: number; birthtimeMs: number }> = []
+  const keptCandidates: typeof recentCandidates = []
   for (const file of await listCodexJsonlFiles(sessionsRoot)) {
     const st = await fileStat(file)
     if (!st?.isFile) continue
     const name = file.split('/').pop() || file
     const fileId = idFromCodexFilename(name)
-    const pinned = fileId ? pinnedIds.has(fileId) : false
+    const nativePin = fileId ? pinnedIds.has(fileId) : false
+    const kept = !nativePin && (fileId ? keep.has(fileId) : false)
+    const pinned = nativePin || kept
     const fresh = now.getTime() - st.mtimeMs <= AGENT_SESSION_MAX_AGE_MS
     if (!pinned && !fresh) {
       dropped.age += 1
       continue
     }
     const candidate = { file, name, mtimeMs: st.mtimeMs, birthtimeMs: st.birthtimeMs }
-    if (pinned) pinnedCandidates.push(candidate)
+    if (nativePin) pinnedCandidates.push(candidate)
+    else if (kept) keptCandidates.push(candidate)
     else recentCandidates.push(candidate)
   }
   pinnedCandidates.sort((a, b) => b.mtimeMs - a.mtimeMs)
+  const codexRank = (c: { name: string }) => keepRank(idFromCodexFilename(c.name) ?? '')
+  keptCandidates.sort((a, b) => (codexRank(a) - codexRank(b)) || b.mtimeMs - a.mtimeMs)
   recentCandidates.sort((a, b) => b.mtimeMs - a.mtimeMs)
 
   const toRows = async (candidates: typeof recentCandidates, limit: number): Promise<AgentSessionRow[]> => {
@@ -1251,8 +1285,12 @@ export async function listCodexSessions(
   }
 
   const pinnedRows = await toRows(pinnedCandidates, Math.max(pinnedCandidates.length, 0))
+  const keptLimitBefore = dropped.limit
+  const keptRows = await toRows(keptCandidates, KEPT_LIST_MAX)
+  countKeptOverflow(dropped, dropped.limit - keptLimitBefore)
+  dropped.limit = keptLimitBefore
   const recentRows = await toRows(recentCandidates, Math.max(0, cap))
-  return [...pinnedRows, ...recentRows]
+  return [...pinnedRows, ...keptRows, ...recentRows]
 }
 
 export async function listCursorSessions(
@@ -1262,15 +1300,19 @@ export async function listCursorSessions(
   composerDb = '',
   pinnedIds: ReadonlySet<string> = new Set(),
   dropped: AgentSessionListDropped = emptySessionListDropped(),
+  /** Step 2a: composer ids the COS organizer keeps; see listClaudeSessions. */
+  keep: ReadonlySet<string> = new Set(),
+  keepRank: (id: string) => number = () => 0,
 ): Promise<AgentSessionRow[]> {
   const composerNames = composerDb ? await loadCursorComposerNames(composerDb) : new Map<string, string>()
+  const retained = (id: string) => pinnedIds.has(id.toLowerCase()) || keep.has(id.toLowerCase())
   const byId = new Map<string, { file: string; sessionDir: string; project: string; mtimeMs: number; birthtimeMs: number }>()
   for (const folder of await dirents(projectsRoot)) {
     if (folder.includes('var-folders') || folder.includes('private-var')) continue
     const transcripts = join(projectsRoot, folder, 'agent-transcripts')
     for (const sessionDir of await dirents(transcripts)) {
       if (sessionDir === 'subagents') continue
-      const pinned = pinnedIds.has(sessionDir.toLowerCase())
+      const pinned = retained(sessionDir)
       if (folder === 'empty-window' && !pinned) continue
       const file = join(transcripts, sessionDir, `${sessionDir}.jsonl`)
       const st = await fileStat(file)
@@ -1295,9 +1337,12 @@ export async function listCursorSessions(
       byId.set(sessionDir, existing ? preferCursorCopy(next, existing) : next)
     }
   }
-  const pinnedCandidates = [...byId.values()].filter(c => pinnedIds.has(c.sessionDir.toLowerCase()))
-  const recentCandidates = [...byId.values()].filter(c => !pinnedIds.has(c.sessionDir.toLowerCase()))
+  const nativePin = (id: string) => pinnedIds.has(id.toLowerCase())
+  const pinnedCandidates = [...byId.values()].filter(c => nativePin(c.sessionDir))
+  const keptCandidates = [...byId.values()].filter(c => !nativePin(c.sessionDir) && retained(c.sessionDir))
+  const recentCandidates = [...byId.values()].filter(c => !retained(c.sessionDir))
   pinnedCandidates.sort((a, b) => b.mtimeMs - a.mtimeMs)
+  keptCandidates.sort((a, b) => (keepRank(a.sessionDir.toLowerCase()) - keepRank(b.sessionDir.toLowerCase())) || b.mtimeMs - a.mtimeMs)
   recentCandidates.sort((a, b) => b.mtimeMs - a.mtimeMs)
 
   const toRows = async (candidates: typeof recentCandidates, limit: number): Promise<AgentSessionRow[]> => {
@@ -1334,8 +1379,13 @@ export async function listCursorSessions(
     return rows
   }
 
+  const keptLimitBefore = dropped.limit
+  const keptRows = await toRows(keptCandidates, KEPT_LIST_MAX)
+  countKeptOverflow(dropped, dropped.limit - keptLimitBefore)
+  dropped.limit = keptLimitBefore
   return [
     ...await toRows(pinnedCandidates, Math.max(pinnedCandidates.length, 0)),
+    ...keptRows,
     ...await toRows(recentCandidates, Math.max(0, cap)),
   ]
 }
@@ -1407,6 +1457,12 @@ export async function listAgentSessions(
   sort: AgentSessionSort = 'updated',
   dropped: AgentSessionListDropped = emptySessionListDropped(),
   preloadedAliases?: ClaudeAliasMap,
+  /** Step 2a: canonical ids per provider the COS organizer keeps (COS pins, folder members). Kept rows are listed at
+   *  any age, outside the per-provider cap AND outside `limit`. Absent: exactly today's list. */
+  keep: Partial<Record<AgentProvider, ReadonlySet<string>>> = {},
+  /** Step 2a (Miles, 2026-11-10): sessions a COS job started in the last 7 days. Kept like `keep`, ranked after it when
+   *  the KEPT_LIST_MAX ceiling has to choose. */
+  started: Partial<Record<AgentProvider, ReadonlySet<string>>> = {},
 ): Promise<AgentSessionRow[]> {
   const originalStars = await loadClaudeStarredIds(roots.claudeDesktopConfig)
   // ONE alias load for the whole walk. Before this the walk loaded it here AND
@@ -1429,15 +1485,26 @@ export async function listAgentSessions(
     })
   const liveIds = new Set(enrichedLive.flatMap(row => [row.session_id, row.session_id.slice(0, 8)]))
   const cap = AGENT_SESSION_PER_PROVIDER_LIMIT
+  // Kept Claude ids are canonical already (the organizer route canonicalizes on write); map again in case a Desktop
+  // id reached the store from an older path.
+  const keptClaude = new Set([...(keep.claude ?? [])].map(id => canonical(id).toLowerCase()))
+  const startedClaude = new Set([...(started.claude ?? [])].map(id => canonical(id).toLowerCase()))
+  const inSet = (row: AgentSessionRow, claude: Set<string>, other: Partial<Record<AgentProvider, ReadonlySet<string>>>) =>
+    row.provider === 'claude' ? claude.has(row.session_id.toLowerCase()) : (other[row.provider]?.has(row.session_id.toLowerCase()) ?? false)
+  /** 0: a COS pin or folder member; 1: COS-started; null: not kept. */
+  const keptTier = (row: AgentSessionRow): 0 | 1 | null => inSet(row, keptClaude, keep) ? 0 : inSet(row, startedClaude, started) ? 1 : null
+  const isKept = (row: AgentSessionRow) => keptTier(row) !== null
+  const union = (provider: Exclude<AgentProvider, 'claude'>) => new Set([...(keep[provider] ?? []), ...(started[provider] ?? [])])
+  const keptForWalk = { claude: new Set([...keptClaude, ...startedClaude]), codex: union('codex'), cursor: union('cursor') }
   let rows = dedupeSessions([
     ...enrichedLive,
-    ...await listClaudeSessions(roots.claudeProjects, now, liveIds, cap, starredIds, roots.claudeCodeSessions, dropped, aliases),
-    ...(await Promise.all(codexSessionRootsOf(roots).map(root => listCodexSessions(root, now, cap, dropped)))).flat(),
-    ...await listCursorSessions(roots.cursorProjects, now, cap, roots.cursorComposerDb, cursorPinned, dropped),
+    ...await listClaudeSessions(roots.claudeProjects, now, liveIds, cap, starredIds, roots.claudeCodeSessions, dropped, aliases, keptForWalk.claude, id => keptClaude.has(id) ? 0 : 1),
+    ...(await Promise.all(codexSessionRootsOf(roots).map(root => listCodexSessions(root, now, cap, dropped, keptForWalk.codex, id => keep.codex?.has(id) ? 0 : 1)))).flat(),
+    ...await listCursorSessions(roots.cursorProjects, now, cap, roots.cursorComposerDb, cursorPinned, dropped, keptForWalk.cursor, id => keep.cursor?.has(id) ? 0 : 1),
   ])
   if (sort === 'opened') {
     rows = rows.filter(entry => {
-      if (entry.alive) return true
+      if (entry.alive || isKept(entry)) return true
       const created = Date.parse(entry.created)
       return Number.isFinite(created) && now.getTime() - created <= AGENT_SESSION_MAX_AGE_MS
     })
@@ -1450,9 +1517,24 @@ export async function listAgentSessions(
     // pin-boosting here made the lens show July stars instead of today.
     rows.sort((a, b) => (b.modified || '').localeCompare(a.modified || ''))
   }
-  const extras = Math.max(0, rows.length - Math.max(0, limit))
-  if (extras) dropped.limit += extras
-  return rows.slice(0, limit)
+  // Step 2a: kept rows are not cut by `limit` but by their own ceiling, KEPT_LIST_MAX (Q1 FIX 1): COS pins and folder
+  // members first, then COS-started sessions, newest first in each. They keep their place in the sort order.
+  const max = Math.max(0, limit)
+  const keptRanked = rows.filter(isKept)
+    .sort((a, b) => (keptTier(a)! - keptTier(b)!) || (b.modified || '').localeCompare(a.modified || ''))
+  const keptAllowed = new Set(keptRanked.slice(0, KEPT_LIST_MAX))
+  countKeptOverflow(dropped, keptRanked.length - keptAllowed.size)
+  let taken = 0
+  let cut = 0
+  const out = rows.filter(entry => {
+    if (isKept(entry)) return keptAllowed.has(entry)
+    taken += 1
+    if (taken <= max) return true
+    cut += 1
+    return false
+  })
+  if (cut) dropped.limit += cut
+  return out
 }
 
 /**