@gotcos/glasses-server 6.36.12 → 6.36.14

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 ## Unreleased
 
+## 6.36.14
+- **The session LIST now reports what its caps hid.** The 7-day age gate, the
+  20-per-provider cap, and the Cursor 32 MB skip used to drop rows with no
+  signal, so a 60-row list looked complete. `GET /api/agent-sessions` now carries
+  `dropped: { age, limit, oversized }`. Additive: an older client ignores the
+  key. Zero means the walk found nothing to hide, not that the caps are off.
+  Keep-warm titles and Codex files over 32 MB are not counted — Codex is listed
+  oversize on purpose; Cursor is the one that skips. Measured on this machine
+  before publish: 62 listed, **2,144** older than 7 days, **91** over the
+  per-provider cap, **0** oversized. The visible first/last ids match running
+  6.36.13, so the list membership did not change — only the silence did.
+
+## 6.36.13
+- **Codex was spawned by bare name in four places, and it only worked here by accident.**
+  `codex` on PATH is a shell alias to `/Applications/Codex.app`, which does not exist; the real
+  binary lives in ChatGPT.app. Every bare `spawn('codex', …)` resolved through a PATH that COS
+  Control injects into the managed plist — so it worked on this machine and was ENOENT for every
+  public npx user, and for anything launchd- or Finder-spawned. The sites: the model catalog, the
+  `--add-dir` capability probe, the health probe, and `callCodexStreaming`, which is the **live
+  turn-execution path**. Each now resolves first, and each refuses in the way that suits it: the
+  live turn throws with the reason, the catalog rejects to its existing `cli-default` degradation,
+  the capability probe reports unsupported, and the health probe reports `unresolved (…)` instead
+  of collapsing "cannot find it" and "found it and it errored" into one `error`.
+- **Binary resolution moved to its own leaf module.** `provider-binary.ts` imports nothing from the
+  repo, deliberately: reaching the resolver through `attached-provider-adapter.ts` would close the
+  cycle adapter → codex-run-ledger → codex-model-catalog → adapter. The adapter re-exports it, so
+  no existing importer changed.
+- **Three source-text assertions replaced with fixtures.** Two tests asserted on this repo's own
+  characters — `not.toMatch('AGENT_SESSION_MAX_FILE_BYTES')` and `toMatch('end = HEAD_BYTES - 1')`
+  — which go stale on any refactor and cannot observe the property they name. A Codex rollout is
+  now made genuinely larger than the 32 MB gate (sparse, via `truncateSync`) and asserted to still
+  be listed. Verified by mutation: adding that gate to `listCodexSessions` fails the new test.
+
 ## 6.36.12
 - **Claude and Codex now rank candidates by recency before spending the budget.** Both
   walked in raw `readdir` order, so which sessions were reachable came down to filesystem

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.36.12",
+  "version": "6.36.14",
   "description": "COS Glasses — self-hosted AI heads-up-display server for Even G2 smart glasses, powered by Claude Code, Codex, or Cursor Agent CLI",
   "type": "module",
   "bin": {

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

@@ -27,6 +27,17 @@ const CODEX_ROLLOUT_STAMP = /^rollout-(\d{4}-\d{2}-\d{2})T(\d{2})-(\d{2})-(\d{2}
 export type AgentProvider = 'claude' | 'codex' | 'cursor'
 export type AgentSessionSort = 'updated' | 'opened'
 
+/** Caps that drop LIST rows with no other signal. Search has its own budget. */
+export interface AgentSessionListDropped {
+  age: number
+  limit: number
+  oversized: number
+}
+
+export function emptySessionListDropped(): AgentSessionListDropped {
+  return { age: 0, limit: 0, oversized: 0 }
+}
+
 export interface AgentSessionRow {
   session_id: string
   provider: AgentProvider
@@ -836,6 +847,7 @@ export async function listClaudeSessions(
   cap = AGENT_SESSION_PER_PROVIDER_LIMIT,
   starredIds: ReadonlySet<string> = new Set(),
   desktopSessionsRoot = '',
+  dropped: AgentSessionListDropped = emptySessionListDropped(),
 ): Promise<AgentSessionRow[]> {
   const seen = new Set<string>()
   const pinnedCandidates: Array<{ file: string; native: string; project: string; mtimeMs: number; birthtimeMs: number; desktop?: string }> = []
@@ -854,7 +866,10 @@ export async function listClaudeSessions(
       if (!st?.isFile) continue
       const pinned = starredIds.has(native.toLowerCase())
       const fresh = now.getTime() - st.mtimeMs <= AGENT_SESSION_MAX_AGE_MS
-      if (!pinned && !fresh) continue
+      if (!pinned && !fresh) {
+        dropped.age += 1
+        continue
+      }
       const candidate = {
         file,
         native,
@@ -888,8 +903,12 @@ export async function listClaudeSessions(
 
   const toRows = async (candidates: typeof recentCandidates, limit: number): Promise<AgentSessionRow[]> => {
     const rows: AgentSessionRow[] = []
-    for (const candidate of candidates) {
-      if (rows.length >= Math.max(0, limit)) break
+    for (let i = 0; i < candidates.length; i++) {
+      if (rows.length >= Math.max(0, limit)) {
+        dropped.limit += candidates.length - i
+        break
+      }
+      const candidate = candidates[i]
       let title = ''
       let project = candidate.project
       let firstPrompt = ''
@@ -935,6 +954,7 @@ export async function listCodexSessions(
   sessionsRoot: string,
   now: Date,
   cap = AGENT_SESSION_PER_PROVIDER_LIMIT,
+  dropped: AgentSessionListDropped = emptySessionListDropped(),
 ): Promise<AgentSessionRow[]> {
   const names = await loadCodexThreadNames(sessionsRoot)
   const pinnedIds = await loadCodexPinnedIds(sessionsRoot)
@@ -947,7 +967,10 @@ export async function listCodexSessions(
     const fileId = idFromCodexFilename(name)
     const pinned = fileId ? pinnedIds.has(fileId) : false
     const fresh = now.getTime() - st.mtimeMs <= AGENT_SESSION_MAX_AGE_MS
-    if (!pinned && !fresh) continue
+    if (!pinned && !fresh) {
+      dropped.age += 1
+      continue
+    }
     const candidate = { file, name, mtimeMs: st.mtimeMs, birthtimeMs: st.birthtimeMs }
     if (pinned) pinnedCandidates.push(candidate)
     else recentCandidates.push(candidate)
@@ -957,8 +980,12 @@ export async function listCodexSessions(
 
   const toRows = async (candidates: typeof recentCandidates, limit: number): Promise<AgentSessionRow[]> => {
     const rows: AgentSessionRow[] = []
-    for (const candidate of candidates) {
-      if (rows.length >= Math.max(0, limit)) break
+    for (let i = 0; i < candidates.length; i++) {
+      if (rows.length >= Math.max(0, limit)) {
+        dropped.limit += candidates.length - i
+        break
+      }
+      const candidate = candidates[i]
       const meta = await peekCodexMeta(candidate.file)
       if (!meta || meta.subagent) continue
       // THE FILENAME WINS WHEN THEY DISAGREE.
@@ -1011,6 +1038,7 @@ export async function listCursorSessions(
   cap = AGENT_SESSION_PER_PROVIDER_LIMIT,
   composerDb = '',
   pinnedIds: ReadonlySet<string> = new Set(),
+  dropped: AgentSessionListDropped = emptySessionListDropped(),
 ): Promise<AgentSessionRow[]> {
   const composerNames = composerDb ? await loadCursorComposerNames(composerDb) : new Map<string, string>()
   const byId = new Map<string, { file: string; sessionDir: string; project: string; mtimeMs: number; birthtimeMs: number }>()
@@ -1024,9 +1052,15 @@ export async function listCursorSessions(
       const file = join(transcripts, sessionDir, `${sessionDir}.jsonl`)
       const st = await fileStat(file)
       if (!st?.isFile) continue
-      if (!pinned && st.size > AGENT_SESSION_MAX_FILE_BYTES) continue
+      if (!pinned && st.size > AGENT_SESSION_MAX_FILE_BYTES) {
+        dropped.oversized += 1
+        continue
+      }
       const fresh = now.getTime() - st.mtimeMs <= AGENT_SESSION_MAX_AGE_MS
-      if (!pinned && !fresh) continue
+      if (!pinned && !fresh) {
+        dropped.age += 1
+        continue
+      }
       const next = {
         file,
         sessionDir,
@@ -1045,8 +1079,12 @@ export async function listCursorSessions(
 
   const toRows = async (candidates: typeof recentCandidates, limit: number): Promise<AgentSessionRow[]> => {
     const rows: AgentSessionRow[] = []
-    for (const candidate of candidates) {
-      if (rows.length >= Math.max(0, limit)) break
+    for (let i = 0; i < candidates.length; i++) {
+      if (rows.length >= Math.max(0, limit)) {
+        dropped.limit += candidates.length - i
+        break
+      }
+      const candidate = candidates[i]
       const peek = await peekCursorDiscussion(candidate.file)
       const firstPrompt = await firstCursorUserTitle(candidate.file) ?? peek.lastUser ?? ''
       const title = composerNames.get(candidate.sessionDir)
@@ -1141,6 +1179,7 @@ export async function listAgentSessions(
   live: AgentSessionRow[] = [],
   limit = AGENT_SESSION_LIST_LIMIT,
   sort: AgentSessionSort = 'updated',
+  dropped: AgentSessionListDropped = emptySessionListDropped(),
 ): Promise<AgentSessionRow[]> {
   const starredIds = await loadClaudeStarredIds(roots.claudeDesktopConfig)
   const cursorPinned = await loadCursorPinnedIds(roots.cursorWorkspaceStorage)
@@ -1159,9 +1198,9 @@ export async function listAgentSessions(
   const cap = AGENT_SESSION_PER_PROVIDER_LIMIT
   let rows = dedupeSessions([
     ...enrichedLive,
-    ...await listClaudeSessions(roots.claudeProjects, now, liveIds, cap, starredIds, roots.claudeCodeSessions),
-    ...await listCodexSessions(roots.codexSessions, now, cap),
-    ...await listCursorSessions(roots.cursorProjects, now, cap, roots.cursorComposerDb, cursorPinned),
+    ...await listClaudeSessions(roots.claudeProjects, now, liveIds, cap, starredIds, roots.claudeCodeSessions, dropped),
+    ...await listCodexSessions(roots.codexSessions, now, cap, dropped),
+    ...await listCursorSessions(roots.cursorProjects, now, cap, roots.cursorComposerDb, cursorPinned, dropped),
   ])
   if (sort === 'opened') {
     rows = rows.filter(entry => {
@@ -1178,6 +1217,8 @@ 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)
 }
 

package/server/lib/attached-provider-adapter.ts

@@ -227,173 +227,28 @@ export function attachedDeliveryAmbiguous(result: AttachedTurnResult): boolean {
 // ---------------------------------------------------------------------------
 // Binary resolution
 // ---------------------------------------------------------------------------
+//
+// MOVED to ./provider-binary.js so codex-bridge, codex-model-catalog and
+// health-static-probes can resolve without importing this module -- doing so would close
+// the cycle adapter -> codex-run-ledger -> codex-model-catalog -> adapter.
+// Re-exported here so existing importers and tests are unaffected.
+
+import {
+  resolveProviderBinary,
+  type BinaryResolution,
+} from './provider-binary.js'
+
+export {
+  STALE_SHIM_PREFIXES,
+  isKnownStaleShimPath,
+  providerBinarySpec,
+  resolveProviderBinary,
+  resolveBinaryFromSpec,
+  type BinaryResolution,
+  type BinaryResolutionFailure,
+  type BinarySpec,
+} from './provider-binary.js'
 
-export type BinaryResolutionFailure = 'env_override_unusable' | 'not_found'
-
-export type BinaryResolution =
-  | { ok: true; path: string; source: 'env' | 'absolute' | 'path' }
-  | { ok: false; binary: string; detail: BinaryResolutionFailure }
-
-/**
- * Path prefixes that can never be a usable provider binary.
- *
- * `codex` resolved through PATH (or a shell alias) points at
- * `/Applications/Codex.app/Contents/Resources/codex` on this machine, and that
- * app no longer exists. Today the shim is dangling, so an existence check
- * already rejects it — but a reinstalled or partially-removed Codex.app puts a
- * real, executable file back on that path, and then only this list stands
- * between an attached turn and a binary that cannot serve it.
- */
-export const STALE_SHIM_PREFIXES: readonly string[] = ['/Applications/Codex.app/']
-
-export function isKnownStaleShimPath(
-  candidate: string,
-  prefixes: readonly string[] = STALE_SHIM_PREFIXES,
-): boolean {
-  // A non-array argument falls back to the known list rather than to "exclude
-  // nothing" — the classic version of this bug is `list.some(isKnownStaleShimPath)`,
-  // where `.some` passes the INDEX as the second argument and every exclusion
-  // silently disappears.
-  const list = Array.isArray(prefixes) ? prefixes : STALE_SHIM_PREFIXES
-  return list.some(prefix => typeof prefix === 'string' && prefix.length > 0 && candidate.startsWith(prefix))
-}
-
-function isUsableExecutable(
-  candidate: string,
-  excludePrefixes: readonly string[] = STALE_SHIM_PREFIXES,
-): boolean {
-  try {
-    if (!isAbsolute(candidate) || candidate.includes('\0')) return false
-    if (isKnownStaleShimPath(candidate, excludePrefixes)) return false
-    if (!statSync(candidate).isFile()) return false
-    accessSync(candidate, fsConstants.X_OK)
-    return true
-  } catch {
-    return false
-  }
-}
-
-export interface BinarySpec {
-  name: string
-  envKeys: readonly string[]
-  /** Tried in order, BEFORE any PATH scan. */
-  absolutes: readonly string[]
-  /**
-   * Paths that must never be selected, from any source. Defaults to
-   * `STALE_SHIM_PREFIXES`.
-   *
-   * On the spec rather than hardcoded because the exclusion is the only guard
-   * standing between resolution and a known-bad binary, and a guard whose input
-   * cannot be constructed is a guard nobody can prove works: the real prefix
-   * lives under `/Applications`, which no fixture can write to.
-   */
-  excludePrefixes?: readonly string[]
-}
-
-/**
- * Where each provider's binary is looked for, in precedence order.
- *
- * Exported as data rather than kept private so the precedence itself is
- * testable: on a machine where a stale shim sits on PATH, "ChatGPT.app is tried
- * before PATH" is the property that decides whether an attached Codex turn
- * launches the real binary or a dangling one.
- */
-export function providerBinarySpec(provider: AttachedProvider): BinarySpec {
-  const home = (() => {
-    try {
-      return homedir()
-    } catch {
-      return ''
-    }
-  })()
-  if (provider === 'claude') {
-    return {
-      name: 'claude',
-      envKeys: ['COS_ATTACHED_CLAUDE_BIN', 'COS_CLAUDE_BIN'],
-      absolutes: [
-        '/opt/homebrew/bin/claude',
-        '/usr/local/bin/claude',
-        home ? join(home, '.local', 'bin', 'claude') : '',
-      ].filter(Boolean),
-    }
-  }
-  return {
-    name: 'codex',
-    envKeys: ['COS_ATTACHED_CODEX_BIN', 'COS_CODEX_BIN'],
-    absolutes: [
-      // Verified 2026-08-15: codex-cli 0.148.0-alpha.9 lives here, and there is
-      // no `codex` on PATH at all on this machine.
-      '/Applications/ChatGPT.app/Contents/Resources/codex',
-      home ? join(home, '.codex', 'bin', 'codex') : '',
-      '/opt/homebrew/bin/codex',
-      '/usr/local/bin/codex',
-    ].filter(Boolean),
-  }
-}
-
-/**
- * Resolve a provider binary to a verified absolute path, or refuse.
- *
- * Never returns a bare name. A bare name is a silent PATH lookup, and the two
- * environments this server runs in disagree about PATH: a login shell finds the
- * CLI, a Finder- or launchd-spawned process gets a minimal PATH and does not
- * (hit twice in COS Control). The PATH scan below is done by us, entry by
- * entry, and still yields an absolute path we have stat'ed — so a failure names
- * the missing binary instead of surfacing as ENOENT from inside a spawn.
- *
- * An unusable env override REFUSES rather than falling through to the
- * candidates: an operator who set it wrongly needs to be told, not overridden.
- */
-export function resolveProviderBinary(
-  provider: AttachedProvider,
-  env: NodeJS.ProcessEnv = process.env,
-): BinaryResolution {
-  return resolveBinaryFromSpec(providerBinarySpec(provider), env)
-}
-
-/**
- * The resolution algorithm itself, separated from the provider tables.
- *
- * Not a testing seam bolted on: on any developer machine at least one real
- * absolute candidate exists, so the PATH-scan and not-found branches of
- * `resolveProviderBinary` are unreachable from a test and would ship
- * unexercised — which is exactly how a launchd-only failure hides. Driving the
- * REAL algorithm with a fixture spec exercises them for real.
- */
-export function resolveBinaryFromSpec(spec: BinarySpec, env: NodeJS.ProcessEnv): BinaryResolution {
-  const excluded = spec.excludePrefixes ?? STALE_SHIM_PREFIXES
-
-  for (const key of spec.envKeys) {
-    const raw = env[key]
-    if (typeof raw !== 'string' || raw.trim().length === 0) continue
-    const candidate = raw.trim()
-    if (!isUsableExecutable(candidate, excluded)) {
-      return { ok: false, binary: spec.name, detail: 'env_override_unusable' }
-    }
-    return { ok: true, path: candidate, source: 'env' }
-  }
-
-  for (const candidate of spec.absolutes) {
-    if (isUsableExecutable(candidate, excluded)) return { ok: true, path: candidate, source: 'absolute' }
-  }
-
-  const pathValue = typeof env.PATH === 'string' ? env.PATH : ''
-  for (const dir of pathValue.split(delimiter)) {
-    // A relative PATH entry resolves against the server's cwd, which is not a
-    // location we control. Skipped rather than resolved.
-    //
-    // Redundant with the `isAbsolute` inside `isUsableExecutable` — verified by
-    // mutation: removing EITHER one alone changes no outcome, and only removing
-    // BOTH lets a relative entry through. Kept because two independent guards
-    // on "never resolve against the server cwd" is the correct amount for a
-    // path that ends up as a spawned executable.
-    if (!dir || !isAbsolute(dir)) continue
-    const candidate = join(dir, spec.name)
-    if (isUsableExecutable(candidate, excluded)) return { ok: true, path: candidate, source: 'path' }
-  }
-
-  return { ok: false, binary: spec.name, detail: 'not_found' }
-}
 
 // ---------------------------------------------------------------------------
 // Injected surface

package/server/lib/codex-bridge.ts

@@ -2,6 +2,11 @@
 // Concrete GPT ids resolve from Codex's live model catalog at run time.
 
 import { spawn, spawnSync } from 'node:child_process'
+// Resolved, never bare. `codex` on PATH is a shell alias to /Applications/Codex.app,
+// which does not exist; the real binary is in ChatGPT.app. A bare argv works here only
+// because COS Control injects that directory into the managed plist PATH -- it is ENOENT
+// for every public npx user, and for anything launchd- or Finder-spawned.
+import { resolveProviderBinary } from './provider-binary.js'
 import { logTokenAudit } from './token-audit.js'
 import { cleanupModelImageInputs, type ModelImageInput } from './model-image-input.js'
 import { buildSystemPrompt, buildLightweightSystemPrompt } from './context-builder.js'
@@ -137,7 +142,14 @@ let addDirSupported: boolean | undefined
 export function codexSupportsAdditionalDir(): boolean {
   if (addDirSupported !== undefined) return addDirSupported
   try {
-    const result = spawnSync('codex', ['exec', '--help'], {
+    const resolved = resolveProviderBinary('codex')
+    if (!resolved.ok) {
+      // Cannot probe what cannot be found. Report unsupported rather than throwing:
+      // this gate only disables output publishing, and chat stays functional.
+      addDirSupported = false
+      return addDirSupported
+    }
+    const result = spawnSync(resolved.path, ['exec', '--help'], {
       encoding: 'utf8',
       timeout: 5_000,
       stdio: ['ignore', 'pipe', 'pipe'],
@@ -413,7 +425,18 @@ export async function callCodexStreaming(
   delete env.CLAUDECODE
   if (outputImagePublisher) Object.assign(env, outputImagePublisher.env)
 
-  const proc = spawn('codex', args, {
+  // The live turn path. This one REFUSES loudly rather than degrading -- a turn that
+  // cannot reach the binary must say so, not fail later as an opaque ENOENT from inside
+  // a spawn whose argv the caller never sees.
+  const resolvedCodex = resolveProviderBinary('codex')
+  if (!resolvedCodex.ok) {
+    throw new Error(
+      `codex binary unresolved (${resolvedCodex.detail}). Checked the env override, `
+      + 'then ChatGPT.app, then PATH; /Applications/Codex.app is excluded as a stale shim.',
+    )
+  }
+
+  const proc = spawn(resolvedCodex.path, args, {
     stdio: ['pipe', 'pipe', 'pipe'],
     env,
     cwd: codexCwd,

package/server/lib/codex-model-catalog.ts

@@ -6,6 +6,10 @@
 // the CLI default is used only when no discovered catalog exists yet.
 
 import { spawn } from 'node:child_process'
+// Resolved, never bare -- see provider-binary.ts. This module is a leaf, and the resolver
+// was extracted precisely so importing it here cannot close the cycle
+// catalog -> adapter -> codex-run-ledger -> catalog.
+import { resolveProviderBinary } from './provider-binary.js'
 import { existsSync, readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { resolve } from 'node:path'
@@ -248,7 +252,15 @@ async function fetchAppServerModels(): Promise<CodexCatalogModel[]> {
   return new Promise((resolveModels, reject) => {
     const env = { ...process.env }
     delete env.CLAUDECODE
-    const child = spawn('codex', ['app-server', '--stdio'], {
+    const resolved = resolveProviderBinary('codex')
+    if (!resolved.ok) {
+      // Degrade, do not throw: this module already models exactly this outcome as
+      // `CodexCatalogSource = 'cli-default'`. A catalog refresh that cannot find the
+      // binary is a stale catalog, not a broken server.
+      reject(new Error(`codex binary unresolved (${resolved.detail})`))
+      return
+    }
+    const child = spawn(resolved.path, ['app-server', '--stdio'], {
       stdio: ['pipe', 'pipe', 'pipe'],
       env,
     })

package/server/lib/health-static-probes.ts

@@ -1,4 +1,5 @@
 import { execFile } from 'node:child_process'
+import { resolveProviderBinary } from './provider-binary.js'
 import { PYTHON_BIN } from './python-bridge.js'
 import {
   getCursorModelCatalog,
@@ -116,7 +117,12 @@ async function probeClaude(): Promise<{ value: string; available: boolean }> {
 
 async function probeCodex(): Promise<{ value: string; available: boolean }> {
   try {
-    const result = await execute('codex', ['--version'])
+    // Distinguish "cannot find the binary" from "found it and it errored" -- collapsing
+    // both to 'error' told every public npx user their Codex was broken when the real
+    // problem was a bare argv resolving through a PATH they do not have.
+    const resolved = resolveProviderBinary('codex')
+    if (!resolved.ok) return { value: `unresolved (${resolved.detail})`, available: false }
+    const result = await execute(resolved.path, ['--version'])
     const combined = `${result.stdout}\n${result.stderr}`.trim()
     const versionLine = combined.split(/\r?\n/).map(line => line.trim())
       .find(line => /^codex(?:-cli)?\s+/i.test(line))

package/server/lib/provider-binary.ts

@@ -0,0 +1,192 @@
+/**
+ * Where a provider's executable actually is.
+ *
+ * Extracted from `attached-provider-adapter.ts` 2026-08-19, unchanged. It moved because
+ * three other modules spawn providers by BARE NAME and need this resolution, and importing
+ * the adapter to get it closes a cycle: adapter -> codex-run-ledger -> codex-model-catalog
+ * -> adapter. This module imports nothing from the repo, so it can never be in one.
+ *
+ * Bare `'codex'` in argv resolves through PATH, and a Finder- or launchd-spawned process
+ * gets a minimal one. On this machine the bare sites work ONLY because COS Control injects
+ * ChatGPT.app onto the managed plist PATH -- they are broken for every public npx user.
+ */
+
+import { accessSync, constants as fsConstants, statSync } from 'node:fs'
+import { delimiter, isAbsolute, join } from 'node:path'
+import { homedir } from 'node:os'
+
+// ---------------------------------------------------------------------------
+// Binary resolution
+// ---------------------------------------------------------------------------
+
+export type BinaryResolutionFailure = 'env_override_unusable' | 'not_found'
+
+export type BinaryResolution =
+  | { ok: true; path: string; source: 'env' | 'absolute' | 'path' }
+  | { ok: false; binary: string; detail: BinaryResolutionFailure }
+
+/**
+ * Path prefixes that can never be a usable provider binary.
+ *
+ * `codex` resolved through PATH (or a shell alias) points at
+ * `/Applications/Codex.app/Contents/Resources/codex` on this machine, and that
+ * app no longer exists. Today the shim is dangling, so an existence check
+ * already rejects it — but a reinstalled or partially-removed Codex.app puts a
+ * real, executable file back on that path, and then only this list stands
+ * between an attached turn and a binary that cannot serve it.
+ */
+export const STALE_SHIM_PREFIXES: readonly string[] = ['/Applications/Codex.app/']
+
+export function isKnownStaleShimPath(
+  candidate: string,
+  prefixes: readonly string[] = STALE_SHIM_PREFIXES,
+): boolean {
+  // A non-array argument falls back to the known list rather than to "exclude
+  // nothing" — the classic version of this bug is `list.some(isKnownStaleShimPath)`,
+  // where `.some` passes the INDEX as the second argument and every exclusion
+  // silently disappears.
+  const list = Array.isArray(prefixes) ? prefixes : STALE_SHIM_PREFIXES
+  return list.some(prefix => typeof prefix === 'string' && prefix.length > 0 && candidate.startsWith(prefix))
+}
+
+function isUsableExecutable(
+  candidate: string,
+  excludePrefixes: readonly string[] = STALE_SHIM_PREFIXES,
+): boolean {
+  try {
+    if (!isAbsolute(candidate) || candidate.includes('\0')) return false
+    if (isKnownStaleShimPath(candidate, excludePrefixes)) return false
+    if (!statSync(candidate).isFile()) return false
+    accessSync(candidate, fsConstants.X_OK)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export interface BinarySpec {
+  name: string
+  envKeys: readonly string[]
+  /** Tried in order, BEFORE any PATH scan. */
+  absolutes: readonly string[]
+  /**
+   * Paths that must never be selected, from any source. Defaults to
+   * `STALE_SHIM_PREFIXES`.
+   *
+   * On the spec rather than hardcoded because the exclusion is the only guard
+   * standing between resolution and a known-bad binary, and a guard whose input
+   * cannot be constructed is a guard nobody can prove works: the real prefix
+   * lives under `/Applications`, which no fixture can write to.
+   */
+  excludePrefixes?: readonly string[]
+}
+
+/**
+ * Where each provider's binary is looked for, in precedence order.
+ *
+ * Exported as data rather than kept private so the precedence itself is
+ * testable: on a machine where a stale shim sits on PATH, "ChatGPT.app is tried
+ * before PATH" is the property that decides whether an attached Codex turn
+ * launches the real binary or a dangling one.
+ */
+/**
+ * Takes a plain string, not `AttachedProvider`, deliberately. That type is declared in
+ * `attached-provider-adapter.ts`, and importing it back would recreate exactly the cycle
+ * this extraction exists to break. Callers pass a string-union value, which is assignable.
+ */
+export function providerBinarySpec(provider: string): BinarySpec {
+  const home = (() => {
+    try {
+      return homedir()
+    } catch {
+      return ''
+    }
+  })()
+  if (provider === 'claude') {
+    return {
+      name: 'claude',
+      envKeys: ['COS_ATTACHED_CLAUDE_BIN', 'COS_CLAUDE_BIN'],
+      absolutes: [
+        '/opt/homebrew/bin/claude',
+        '/usr/local/bin/claude',
+        home ? join(home, '.local', 'bin', 'claude') : '',
+      ].filter(Boolean),
+    }
+  }
+  return {
+    name: 'codex',
+    envKeys: ['COS_ATTACHED_CODEX_BIN', 'COS_CODEX_BIN'],
+    absolutes: [
+      // Verified 2026-08-15: codex-cli 0.148.0-alpha.9 lives here, and there is
+      // no `codex` on PATH at all on this machine.
+      '/Applications/ChatGPT.app/Contents/Resources/codex',
+      home ? join(home, '.codex', 'bin', 'codex') : '',
+      '/opt/homebrew/bin/codex',
+      '/usr/local/bin/codex',
+    ].filter(Boolean),
+  }
+}
+
+/**
+ * Resolve a provider binary to a verified absolute path, or refuse.
+ *
+ * Never returns a bare name. A bare name is a silent PATH lookup, and the two
+ * environments this server runs in disagree about PATH: a login shell finds the
+ * CLI, a Finder- or launchd-spawned process gets a minimal PATH and does not
+ * (hit twice in COS Control). The PATH scan below is done by us, entry by
+ * entry, and still yields an absolute path we have stat'ed — so a failure names
+ * the missing binary instead of surfacing as ENOENT from inside a spawn.
+ *
+ * An unusable env override REFUSES rather than falling through to the
+ * candidates: an operator who set it wrongly needs to be told, not overridden.
+ */
+export function resolveProviderBinary(
+  provider: string,
+  env: NodeJS.ProcessEnv = process.env,
+): BinaryResolution {
+  return resolveBinaryFromSpec(providerBinarySpec(provider), env)
+}
+
+/**
+ * The resolution algorithm itself, separated from the provider tables.
+ *
+ * Not a testing seam bolted on: on any developer machine at least one real
+ * absolute candidate exists, so the PATH-scan and not-found branches of
+ * `resolveProviderBinary` are unreachable from a test and would ship
+ * unexercised — which is exactly how a launchd-only failure hides. Driving the
+ * REAL algorithm with a fixture spec exercises them for real.
+ */
+export function resolveBinaryFromSpec(spec: BinarySpec, env: NodeJS.ProcessEnv): BinaryResolution {
+  const excluded = spec.excludePrefixes ?? STALE_SHIM_PREFIXES
+
+  for (const key of spec.envKeys) {
+    const raw = env[key]
+    if (typeof raw !== 'string' || raw.trim().length === 0) continue
+    const candidate = raw.trim()
+    if (!isUsableExecutable(candidate, excluded)) {
+      return { ok: false, binary: spec.name, detail: 'env_override_unusable' }
+    }
+    return { ok: true, path: candidate, source: 'env' }
+  }
+
+  for (const candidate of spec.absolutes) {
+    if (isUsableExecutable(candidate, excluded)) return { ok: true, path: candidate, source: 'absolute' }
+  }
+
+  const pathValue = typeof env.PATH === 'string' ? env.PATH : ''
+  for (const dir of pathValue.split(delimiter)) {
+    // A relative PATH entry resolves against the server's cwd, which is not a
+    // location we control. Skipped rather than resolved.
+    //
+    // Redundant with the `isAbsolute` inside `isUsableExecutable` — verified by
+    // mutation: removing EITHER one alone changes no outcome, and only removing
+    // BOTH lets a relative entry through. Kept because two independent guards
+    // on "never resolve against the server cwd" is the correct amount for a
+    // path that ends up as a spawned executable.
+    if (!dir || !isAbsolute(dir)) continue
+    const candidate = join(dir, spec.name)
+    if (isUsableExecutable(candidate, excluded)) return { ok: true, path: candidate, source: 'path' }
+  }
+
+  return { ok: false, binary: spec.name, detail: 'not_found' }
+}

package/server/routes/agent-sessions.ts

@@ -11,8 +11,10 @@
 // `?sort=opened` keeps the same window on session start instead.
 // Search scans titles, sidebar names, first prompts, and transcript heads
 // without the 7-day list window. Literal /search is registered first.
-// Does not need COS_SCRIPTS_DIR. Codex subagents stay out. Files over 32 MB
-// still appear in the list; detail remains capped.
+// Does not need COS_SCRIPTS_DIR. Codex subagents stay out.
+// Codex files over 32 MB still appear in the list. Cursor files over 32 MB
+// are skipped and counted on `dropped.oversized`. The list payload now says
+// what each cap hid.
 
 import { Router } from 'express'
 import { stat } from 'node:fs/promises'
@@ -23,6 +25,7 @@ import {
   agentSessionRoots,
   findAgentSessionFile,
   listAgentSessions,
+  emptySessionListDropped,
   loadCursorComposerNames,
   parseAgentSession,
   type AgentProvider,
@@ -268,7 +271,8 @@ agentSessionsRouter.get('/agent-sessions', async (req, res) => {
     const limit = boundedInteger(req.query.limit, AGENT_SESSION_LIST_LIMIT, 1, AGENT_SESSION_LIST_MAX)
     const sort = asSort(req.query.sort)
     const live = await liveClaudeRows()
-    const sessions = await listAgentSessions(agentSessionRoots(), new Date(), live, limit, sort)
+    const dropped = emptySessionListDropped()
+    const sessions = await listAgentSessions(agentSessionRoots(), new Date(), live, limit, sort, dropped)
     const scan = runningThreads(sessions)
     // Freshness is layered on AFTER occupancy, and only over what occupancy
     // found. `Date.now()` is read once so every row in a payload is judged
@@ -283,6 +287,10 @@ agentSessionsRouter.get('/agent-sessions', async (req, res) => {
       // True when a probe could not see clearly. The client must render "unknown"
       // rather than treating a quiet scan as "nothing is running".
       runningDegraded: running.degraded,
+      // LIST caps that previously dropped rows with no signal. Additive: an older
+      // client ignores this key. Zero means the walk found nothing to hide, not
+      // that the caps are off.
+      dropped,
     })
   } catch (error) {
     console.error(`[agent-sessions] list failed: ${error instanceof Error ? error.message : error}`)