@gotcos/glasses-server 7.0.18 → 7.0.29

package/server/lib/session-organizer.ts

@@ -0,0 +1,305 @@
+/**
+ * The session organizer (Sessions chat-style layout, step 2a; contract
+ * operations/personal/wk46_2026/sessions_chat_layout/S1_CONTRACT_step2a.md).
+ *
+ * COS's own folders, COS pins and renamed titles for agent sessions, shared by Control Web and the Mac app. It only
+ * ADDS: nothing an agent wrote is changed (a COS pin is not a Claude star), and a list without this store is today's.
+ *
+ * - One file, data/session-organizer.json, 0600, written durably (temp file, fsync, rename) on every change.
+ * - Keyed `<provider>:<canonical id>`, lowercase. The caller canonicalizes (Claude Desktop ids map to their CLI id)
+ *   BEFORE it reaches this module, so this module never guesses identity.
+ * - One change per call, applied in memory and written at once; `rev` rises by one per change. Nothing takes a whole
+ *   store, so two devices editing different things never overwrite each other.
+ * - Folder names and titles never reach a log line: logs carry counts and reason codes only.
+ * - A file that exists but cannot be READ makes the store unavailable (no writes), so a transient read error can
+ *   never be followed by a write that replaces real data with an empty store. A file that reads but does not parse,
+ *   or has the wrong shape, is moved aside as `.corrupt-<time>` and the store starts empty.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync } from 'node:fs'
+import { randomBytes } from 'node:crypto'
+import { dirname } from 'node:path'
+import { durableAtomicWriteFileSync } from './atomic-fs.js'
+import { dataPath } from './data-dir.js'
+
+export const ORGANIZER_FILE = 'session-organizer.json'
+export const ORGANIZER_LIMITS = { folders: 200, entries: 5_000, folderName: 60, title: 120 } as const
+export type OrganizerProvider = 'claude' | 'codex' | 'cursor'
+const PROVIDERS: ReadonlySet<string> = new Set(['claude', 'codex', 'cursor'])
+const FOLDER_ID_RE = /^f_[0-9a-f]{16}$/
+
+export interface OrganizerFolder { name: string; created_at: string }
+/** `desktop_id`: for a Claude session, the Claude Desktop id it was written under when one is known (Q1 FIX 2). A row
+ *  matches an entry by its key OR by this id, so an entry survives the Desktop alias appearing or changing. */
+export interface OrganizerEntry { folder_id?: string; cos_pinned?: true; title?: string; desktop_id?: string; updated_at: string }
+interface OrganizerFile {
+  version: 1
+  rev: number
+  folders: Record<string, OrganizerFolder>
+  sessions: Record<string, OrganizerEntry>
+}
+
+export class OrganizerError extends Error {
+  constructor(readonly status: number, readonly reason: string) { super(reason) }
+}
+
+/** What a list row or search hit carries from the store (each omitted when absent). */
+export interface OrganizerRowFields { folder_id?: string; cos_pinned?: true; title_override?: string }
+
+/** Trim, drop control characters and line breaks, collapse inner whitespace. Empty means refused. */
+export function cleanOrganizerText(value: unknown, max: number): string | null {
+  if (typeof value !== 'string') return null
+  // eslint-disable-next-line no-control-regex
+  const cleaned = value.replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g, ' ').replace(/\s+/g, ' ').trim()
+  if (!cleaned || [...cleaned].length > max) return null
+  return cleaned
+}
+
+export function organizerKey(provider: string, sessionId: string): string {
+  return `${provider}:${sessionId.trim().toLowerCase()}`
+}
+
+function emptyFile(): OrganizerFile { return { version: 1, rev: 0, folders: {}, sessions: {} } }
+
+function validShape(value: unknown): value is OrganizerFile {
+  if (!value || typeof value !== 'object') return false
+  const v = value as Partial<OrganizerFile>
+  if (v.version !== 1 || typeof v.rev !== 'number' || !Number.isInteger(v.rev) || v.rev < 0) return false
+  if (!v.folders || typeof v.folders !== 'object' || Array.isArray(v.folders)) return false
+  if (!v.sessions || typeof v.sessions !== 'object' || Array.isArray(v.sessions)) return false
+  for (const [id, folder] of Object.entries(v.folders)) {
+    if (!FOLDER_ID_RE.test(id) || !folder || typeof folder.name !== 'string' || typeof folder.created_at !== 'string') return false
+  }
+  for (const [key, entry] of Object.entries(v.sessions)) {
+    const provider = key.split(':', 1)[0]
+    if (!PROVIDERS.has(provider) || key.length <= provider.length + 1 || !entry || typeof entry.updated_at !== 'string') return false
+    if (entry.folder_id !== undefined && (typeof entry.folder_id !== 'string' || !v.folders[entry.folder_id])) return false
+    if (entry.cos_pinned !== undefined && entry.cos_pinned !== true) return false
+    if (entry.title !== undefined && typeof entry.title !== 'string') return false
+    if (entry.desktop_id !== undefined && typeof entry.desktop_id !== 'string') return false
+  }
+  return true
+}
+
+export type OrganizerLog = (line: string) => void
+
+export class SessionOrganizer {
+  private state: OrganizerFile = emptyFile()
+  private available = true
+
+  constructor(private readonly path: string = dataPath(ORGANIZER_FILE), private readonly log: OrganizerLog = line => console.warn(line),
+    private readonly now: () => Date = () => new Date()) {
+    this.load()
+  }
+
+  private load(): void {
+    if (!existsSync(this.path)) return
+    let raw: string
+    try {
+      raw = readFileSync(this.path, 'utf8')
+    } catch (error) {
+      // Exists but unreadable (permission, I/O): never write over it.
+      this.available = false
+      this.log(`[session-organizer] unavailable: the store exists but could not be read (${(error as NodeJS.ErrnoException)?.code ?? 'error'})`)
+      return
+    }
+    let parsed: unknown
+    try { parsed = JSON.parse(raw) } catch { parsed = undefined }
+    if (validShape(parsed)) { this.state = parsed; return }
+    const aside = `${this.path}.corrupt-${Date.now()}`
+    try {
+      renameSync(this.path, aside)
+      this.log('[session-organizer] the store did not parse; moved aside and started empty (reason=corrupt_store)')
+    } catch {
+      this.available = false
+      this.log('[session-organizer] unavailable: the store did not parse and could not be moved aside (reason=corrupt_store)')
+    }
+  }
+
+  isAvailable(): boolean { return this.available }
+  rev(): number { return this.state.rev }
+  isEmpty(): boolean { return Object.keys(this.state.folders).length === 0 && Object.keys(this.state.sessions).length === 0 }
+
+  private requireAvailable(): void {
+    if (!this.available) throw new OrganizerError(503, 'organizer_unavailable')
+  }
+
+  private commit(next: OrganizerFile): void {
+    next.rev = this.state.rev + 1
+    mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 })
+    durableAtomicWriteFileSync(this.path, JSON.stringify(next), { mode: 0o600 })
+    this.state = next
+  }
+
+  private clone(): OrganizerFile { return structuredClone(this.state) }
+
+  private counts(): Map<string, number> {
+    const counts = new Map<string, number>()
+    for (const entry of Object.values(this.state.sessions)) {
+      if (entry.folder_id) counts.set(entry.folder_id, (counts.get(entry.folder_id) ?? 0) + 1)
+    }
+    return counts
+  }
+
+  listFolders(): Array<{ id: string; name: string; created_at: string; count: number }> {
+    const counts = this.counts()
+    return Object.entries(this.state.folders)
+      .map(([id, f]) => ({ id, name: f.name, created_at: f.created_at, count: counts.get(id) ?? 0 }))
+      .sort((a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: 'base' }) || a.id.localeCompare(b.id))
+  }
+
+  private nameTaken(name: string, except?: string): boolean {
+    const lower = name.toLocaleLowerCase()
+    return Object.entries(this.state.folders).some(([id, f]) => id !== except && f.name.toLocaleLowerCase() === lower)
+  }
+
+  createFolder(rawName: unknown): { id: string; name: string; created_at: string; count: number } {
+    this.requireAvailable()
+    const name = cleanOrganizerText(rawName, ORGANIZER_LIMITS.folderName)
+    if (!name) throw new OrganizerError(400, 'invalid_name')
+    if (Object.keys(this.state.folders).length >= ORGANIZER_LIMITS.folders) throw new OrganizerError(409, 'too_many_folders')
+    if (this.nameTaken(name)) throw new OrganizerError(409, 'folder_name_taken')
+    let id = ''
+    do { id = `f_${randomBytes(8).toString('hex')}` } while (this.state.folders[id])
+    const next = this.clone()
+    const created_at = this.now().toISOString()
+    next.folders[id] = { name, created_at }
+    this.commit(next)
+    return { id, name, created_at, count: 0 }
+  }
+
+  renameFolder(id: string, rawName: unknown): { id: string; name: string; created_at: string; count: number } {
+    this.requireAvailable()
+    const folder = this.state.folders[id]
+    if (!folder) throw new OrganizerError(404, 'folder_not_found')
+    const name = cleanOrganizerText(rawName, ORGANIZER_LIMITS.folderName)
+    if (!name) throw new OrganizerError(400, 'invalid_name')
+    if (this.nameTaken(name, id)) throw new OrganizerError(409, 'folder_name_taken')
+    const next = this.clone()
+    next.folders[id] = { ...folder, name }
+    this.commit(next)
+    return { id, name, created_at: folder.created_at, count: this.counts().get(id) ?? 0 }
+  }
+
+  /** Removes the folder. Its sessions leave it; no session is ever deleted. Returns how many left. */
+  deleteFolder(id: string): number {
+    this.requireAvailable()
+    if (!this.state.folders[id]) throw new OrganizerError(404, 'folder_not_found')
+    const next = this.clone()
+    delete next.folders[id]
+    let released = 0
+    const stamp = this.now().toISOString()
+    for (const [key, entry] of Object.entries(next.sessions)) {
+      if (entry.folder_id !== id) continue
+      released++
+      delete entry.folder_id
+      entry.updated_at = stamp
+      if (!entry.cos_pinned && entry.title === undefined) delete next.sessions[key]
+    }
+    this.commit(next)
+    return released
+  }
+
+  /**
+   * One session's change. `key` must already be canonical (organizerKey on the canonical id). Keys left out of
+   * `change` are untouched; `null` clears. An entry left with nothing in it is removed.
+   */
+  updateSession(key: string, change: { folder_id?: unknown; cos_pinned?: unknown; title?: unknown }, ids: { desktopId?: string } = {}): OrganizerRowFields {
+    this.requireAvailable()
+    const touchesFolder = Object.prototype.hasOwnProperty.call(change, 'folder_id')
+    const touchesPin = Object.prototype.hasOwnProperty.call(change, 'cos_pinned')
+    const touchesTitle = Object.prototype.hasOwnProperty.call(change, 'title')
+    if (!touchesFolder && !touchesPin && !touchesTitle) throw new OrganizerError(400, 'empty_change')
+    let folderId: string | null | undefined
+    if (touchesFolder) {
+      if (change.folder_id === null) folderId = null
+      else if (typeof change.folder_id === 'string' && this.state.folders[change.folder_id]) folderId = change.folder_id
+      else throw new OrganizerError(404, 'folder_not_found')
+    }
+    if (touchesPin && typeof change.cos_pinned !== 'boolean') throw new OrganizerError(400, 'invalid_pin')
+    let title: string | null | undefined
+    if (touchesTitle) {
+      if (change.title === null) title = null
+      else {
+        title = cleanOrganizerText(change.title, ORGANIZER_LIMITS.title)
+        if (!title) throw new OrganizerError(400, 'invalid_title')
+      }
+    }
+    const desktopId = ids.desktopId?.trim().toLowerCase() || undefined
+    // Q1 FIX 2: an entry written under the same Desktop id but another key (its CLI alias appeared or changed since)
+    // moves to this key, so one session never has two entries.
+    const movedFrom = !this.state.sessions[key] && desktopId
+      ? Object.keys(this.state.sessions).find(k => k.startsWith('claude:') && this.state.sessions[k].desktop_id === desktopId)
+      : undefined
+    const existing = this.state.sessions[key] ?? (movedFrom ? this.state.sessions[movedFrom] : undefined)
+    if (!existing && Object.keys(this.state.sessions).length >= ORGANIZER_LIMITS.entries) throw new OrganizerError(409, 'too_many_entries')
+    const next = this.clone()
+    const entry: OrganizerEntry = { ...(existing ? structuredClone(existing) : {}), updated_at: this.now().toISOString() }
+    if (movedFrom) delete next.sessions[movedFrom]
+    if (desktopId) entry.desktop_id = desktopId
+    if (folderId === null) delete entry.folder_id; else if (folderId) entry.folder_id = folderId
+    if (touchesPin) { if (change.cos_pinned === true) entry.cos_pinned = true; else delete entry.cos_pinned }
+    if (title === null) delete entry.title; else if (title) entry.title = title
+    if (!entry.folder_id && !entry.cos_pinned && entry.title === undefined) delete next.sessions[key]
+    else next.sessions[key] = entry
+    this.commit(next)
+    return this.fieldsFor(key)
+  }
+
+  /** The fields for the first of these keys that has an entry, or for an entry written under one of `desktopIds`. */
+  fieldsForAny(keys: readonly string[], desktopIds: readonly string[] = []): OrganizerRowFields {
+    for (const key of keys) if (this.state.sessions[key]) return this.fieldsFor(key)
+    if (desktopIds.length) {
+      const wanted = new Set(desktopIds.map(id => id.toLowerCase()))
+      for (const [key, entry] of Object.entries(this.state.sessions)) {
+        if (entry.desktop_id && key.startsWith('claude:') && wanted.has(entry.desktop_id)) return this.fieldsFor(key)
+      }
+    }
+    return {}
+  }
+
+  /** The fields a row for this canonical key carries (empty when none). */
+  fieldsFor(key: string): OrganizerRowFields {
+    const entry = this.state.sessions[key]
+    if (!entry) return {}
+    return {
+      ...(entry.folder_id ? { folder_id: entry.folder_id } : {}),
+      ...(entry.cos_pinned ? { cos_pinned: true as const } : {}),
+      ...(entry.title !== undefined ? { title_override: entry.title } : {}),
+    }
+  }
+
+  /** Canonical ids per provider that the list keeps at any age and outside its caps: COS pins and folder members. */
+  keptIds(): Record<OrganizerProvider, Set<string>> {
+    const kept: Record<OrganizerProvider, Set<string>> = { claude: new Set(), codex: new Set(), cursor: new Set() }
+    for (const [key, entry] of Object.entries(this.state.sessions)) {
+      if (!entry.cos_pinned && !entry.folder_id) continue
+      const at = key.indexOf(':')
+      kept[key.slice(0, at) as OrganizerProvider].add(key.slice(at + 1))
+      // The list maps a Desktop id to its current CLI id, so an entry follows its session when the alias changes.
+      if (entry.desktop_id) kept.claude.add(entry.desktop_id)
+    }
+    return kept
+  }
+
+  /** Keys whose renamed title contains `query` (case-insensitive), for search. */
+  titleMatches(query: string): Array<{ provider: OrganizerProvider; session_id: string }> {
+    const needle = query.trim().toLocaleLowerCase()
+    if (!needle) return []
+    const out: Array<{ provider: OrganizerProvider; session_id: string }> = []
+    for (const [key, entry] of Object.entries(this.state.sessions)) {
+      if (entry.title === undefined || !entry.title.toLocaleLowerCase().includes(needle)) continue
+      const at = key.indexOf(':')
+      out.push({ provider: key.slice(0, at) as OrganizerProvider, session_id: key.slice(at + 1) })
+    }
+    return out
+  }
+}
+
+let shared: SessionOrganizer | null = null
+/** The server's one organizer, loaded on first use. */
+export function sessionOrganizer(): SessionOrganizer {
+  if (!shared) shared = new SessionOrganizer()
+  return shared
+}
+/** Tests only. */
+export function __resetSessionOrganizerForTests(next: SessionOrganizer | null = null): void { shared = next }

package/server/lib/session-stream-events.ts

@@ -1354,6 +1354,16 @@ export function draftsFromLine(provider: SessionStreamProvider, line: string): S
  *
  * Skipped: `isMeta` and `isCompactSummary` rows (injected context, not a prompt), tool
  * results, and the bookkeeping rows (`system`, `last-prompt`, `attachment`, `mode`...).
+ *
+ * ONLY `type: 'user'` AND `type: 'assistant'` ROWS ARE THE CONVERSATION (2026-11-11). Every
+ * other row type is skipped, whatever its `message.role`. Claude Code 2.1.300 (first seen
+ * 2026-10-14) writes `api-request-blob` rows: no timestamp, `message.role` user or assistant,
+ * copies of earlier blocks, written AFTER the tool results they repeat. Read as a reply, a
+ * copied `tool_use` re-opened a tool that had already answered, the tail read `tool_pending`,
+ * and the queue held a turn parked for an idle Desktop session until 30 minutes of quiet
+ * (S1, lanes/S1_queue_hold_diagnosis.md: 15 of 56 ended transcripts read open). An UNKNOWN
+ * row type therefore never opens a turn: it fails toward "ended", and the hooks, the registry
+ * and the gate still decide whether anything is sent.
  * Codex keeps its event rule (task_complete / turn_complete end, task_started opens).
  *
  * PURE, like everything else here. The queue store reads the tail; this decides.
@@ -1400,7 +1410,9 @@ export function turnFromTail(provider: SessionStreamProvider, lines: readonly st
     const content = Array.isArray(message.content) ? message.content : typeof message.content === 'string' ? [{ type: 'text', text: message.content }] : []
     const blocks = content.map(asRecord).filter((b): b is Record<string, unknown> => b !== null)
 
-    if (type === 'user' || message.role === 'user') {
+    // The conversation is `user` and `assistant` rows only, by row TYPE, never by `message.role` (see the header:
+    // an api-request-blob carries a role, and any row type this build does not know falls through both branches).
+    if (type === 'user') {
       const results = blocks.filter(b => b.type === 'tool_result')
       if (results.length > 0) {
         for (const b of results) if (typeof b.tool_use_id === 'string') pendingToolUses.delete(b.tool_use_id)
@@ -1413,7 +1425,7 @@ export function turnFromTail(provider: SessionStreamProvider, lines: readonly st
       continue
     }
 
-    if (type === 'assistant' || message.role === 'assistant') {
+    if (type === 'assistant') {
       for (const b of blocks) if (b.type === 'tool_use' && typeof b.id === 'string') pendingToolUses.add(b.id)
       const stop = typeof message.stop_reason === 'string' ? message.stop_reason : ''
       if (TERMINAL_STOP_REASONS.has(stop)) {

package/server/lib/tailnet-self-name.ts

@@ -1,8 +1,9 @@
 // This Mac's own Tailscale MagicDNS name, for COS Control Web's origin checks.
 //
 // WHY NOT THE TAILSCALE CLI. Under the server's LaunchAgent the `tailscale status --json` call
-// the nudger makes does not answer (server.log: "trigger=boot dropped: Tailscale did not answer
-// for 120s"), so the nudger never learns Self.DNSName and a phone at
+// the nudger makes fails: node passes its child no SHLVL, and the macOS CLI then answers "The
+// Tailscale GUI failed to start" instead of the JSON (probe 2026-11-10; server.log's "Tailscale did
+// not answer for 120s" is the event's age, not a hang). So the nudger never learns Self.DNSName and a phone at
 // http://<mac>.<tailnet>.ts.net:3141/control was refused by CORS on every write (6.99.1).
 // MagicDNS itself answers a reverse lookup of this Mac's own 100.x address at 100.100.100.100
 // in about a millisecond, with no CLI involved. The nudger's answer still wins when it has one.
@@ -10,6 +11,13 @@
 // EXACT NAME ONLY. The answer is normalised by normalizeTailscaleDnsName (lowercase, one
 // trailing dot dropped, must end in .ts.net) and compared for equality; never a suffix match.
 // No answer means no name: the tailnet NAME is refused and the tailnet IP URL keeps working.
+//
+// A MISS IS NOT FINAL (7.0.14). The boot lookup can miss (a startup race), and readers that only
+// call currentSelfDnsName() then saw null forever: /api/web-key/status answered `origin: null` (COS
+// Control hid Phone approvals) and the 3144 signer refused every phone write `origin_refused`, until
+// some other route happened to call refresh(). refreshIfMissing() is for exactly those readers: with
+// a name known it returns it and looks nothing up; with none it joins the lookup in flight or starts
+// ONE, at most once per TAILNET_NAME_ON_DEMAND_MIN_MS, and waits at most a bounded time.
 
 import { Resolver } from 'node:dns/promises'
 import { networkInterfaces } from 'node:os'
@@ -18,6 +26,10 @@ import { normalizeTailscaleDnsName, reachableIpv4Addresses } from './network-pol
 export const TAILNET_NAME_HIT_TTL_MS = 10 * 60_000
 export const TAILNET_NAME_MISS_TTL_MS = 60_000
 export const TAILNET_REVERSE_TIMEOUT_MS = 1_500
+/** refreshIfMissing(): while the name is unknown, at most one lookup it starts per this window. */
+export const TAILNET_NAME_ON_DEMAND_MIN_MS = 30_000
+/** refreshIfMissing(): the longest a request waits for that lookup (the lookup itself is bounded by the resolver timeout). */
+export const TAILNET_NAME_ON_DEMAND_WAIT_MS = 2_000
 const MAGIC_DNS_RESOLVER = '100.100.100.100'
 
 export interface TailnetSelfNameDeps {
@@ -37,6 +49,13 @@ export interface TailnetSelfName {
   refresh(): Promise<string | null>
   /** `SelfDnsSource` for isAllowedCorsOrigin: same as refresh(). */
   queryStatus(): Promise<string | null>
+  /**
+   * For a request that must not act on a stale miss (7.0.14). A name known now: that name, no lookup.
+   * None: joins the lookup in flight, or starts one unless this method started one in the last
+   * TAILNET_NAME_ON_DEMAND_MIN_MS (then null at once). Waits at most `waitMs`; a slower lookup keeps
+   * running and caches its answer for the next reader. Never throws.
+   */
+  refreshIfMissing(waitMs?: number): Promise<string | null>
 }
 
 function defaultTailscaleIpv4(): string | null {
@@ -62,13 +81,8 @@ export function createTailnetSelfName(deps: TailnetSelfNameDeps = {}): TailnetSe
 
   const currentSelfDnsName = (): string | null => fromNudger() ?? cached?.name ?? null
 
-  const refresh = (): Promise<string | null> => {
-    const known = fromNudger()
-    if (known) return Promise.resolve(known)
-    const at = now()
-    if (cached && at - cached.at < (cached.name ? TAILNET_NAME_HIT_TTL_MS : TAILNET_NAME_MISS_TTL_MS)) {
-      return Promise.resolve(cached.name)
-    }
+  // The one lookup (single-flight): every caller below shares the promise in flight.
+  const lookup = (): Promise<string | null> => {
     if (inflight) return inflight
     inflight = (async () => {
       let name: string | null = null
@@ -88,7 +102,40 @@ export function createTailnetSelfName(deps: TailnetSelfNameDeps = {}): TailnetSe
     return inflight
   }
 
-  return { currentSelfDnsName, refresh, queryStatus: refresh }
+  const refresh = (): Promise<string | null> => {
+    const known = fromNudger()
+    if (known) return Promise.resolve(known)
+    const at = now()
+    if (cached && at - cached.at < (cached.name ? TAILNET_NAME_HIT_TTL_MS : TAILNET_NAME_MISS_TTL_MS)) {
+      return Promise.resolve(cached.name)
+    }
+    return lookup()
+  }
+
+  // When refreshIfMissing() last STARTED a lookup. Its own clock: the boot lookup and refresh()'s TTL
+  // do not count, so the first reader after a boot miss looks again at once.
+  let onDemandAt: number | null = null
+  const refreshIfMissing = (waitMs: number = TAILNET_NAME_ON_DEMAND_WAIT_MS): Promise<string | null> => {
+    const known = currentSelfDnsName()
+    if (known) return Promise.resolve(known)
+    let pending: Promise<string | null>
+    if (inflight) {
+      pending = inflight
+    } else {
+      const at = now()
+      if (onDemandAt !== null && at - onDemandAt < TAILNET_NAME_ON_DEMAND_MIN_MS) return Promise.resolve(null)
+      onDemandAt = at
+      pending = lookup()
+    }
+    const wait = Math.max(0, waitMs)
+    return new Promise<string | null>(resolve => {
+      const timer = setTimeout(() => resolve(null), wait)
+      timer.unref?.()
+      pending.then(name => { clearTimeout(timer); resolve(name) }, () => { clearTimeout(timer); resolve(null) })
+    })
+  }
+
+  return { currentSelfDnsName, refresh, queryStatus: refresh, refreshIfMissing }
 }
 
 let singleton: TailnetSelfName | null = null

package/server/lib/thread-turn-queue.ts

@@ -122,6 +122,14 @@ export interface QueuedThreadTurn {
    * the words alone, so the pending row and its preview never show a path. Absent on a turn without files.
    */
   attachmentIds?: string[]
+  /**
+   * 2026-11-11 (S1, Miles's note held 08:01): WHY a `waiting` row is held, as a short code the drain decided, and
+   * since when that code has held (epoch ms). Written only when the code CHANGES, never per sweep, so a held row
+   * costs no extra writes. Additive: an older server or client ignores both. Codes only, never text
+   * (`holdReasonFor`, `HOLD_REASON_CODE`).
+   */
+  holdReason?: string
+  holdSince?: number
 }
 
 // ------------------------------------------------------------------- 6.78.0 flags
@@ -376,6 +384,22 @@ export function drainDecision(
   return seen.activity === 'idle' ? 'deliver' : 'hold'
 }
 
+/** A hold reason is a short code: lowercase letters, digits and underscores. Anything else reads `gate_closed`. */
+export const HOLD_REASON_CODE = /^[a-z0-9_]{1,48}$/
+
+/**
+ * Why `drainDecision` held this row, as a code (2026-11-11). Same order as the decision, so the code names the
+ * branch that held: a cancel hold, then the gate (its own reason), then an open turn, then a turn not yet ended.
+ * Only meaningful for a row the decision held; `files_wait_for_turn_end` is set by the drain itself, when the
+ * row's files are the only thing that kept it from going into the running turn.
+ */
+export function holdReasonFor(seen: DrainObservation, now: number): string {
+  if (typeof seen.cancelHoldUntil === 'number' && Number.isFinite(seen.cancelHoldUntil) && now < seen.cancelHoldUntil) return 'cancel_hold'
+  if (!seen.attachable) return typeof seen.reason === 'string' && HOLD_REASON_CODE.test(seen.reason) ? seen.reason : 'gate_closed'
+  if (seen.turnOpen === true) return 'turn_open'
+  return 'turn_not_ended'
+}
+
 /**
  * Admit a turn to the queue, or say why not.
  *

package/server/lib/web-key-signer-app.ts

@@ -92,6 +92,13 @@ export interface WebKeySignerDeps {
   api: (req: IncomingMessage, res: ServerResponse) => void
   /** `https://<MagicDNS name>:3144` (lib/web-key-origin.ts), or null when unknown. */
   origin: () => string | null
+  /**
+   * 7.0.14: called (and awaited) only when origin() is null on an /api request, before the origin
+   * check, so a boot-time miss of the tailnet name does not refuse the phone `origin_refused` until
+   * something else refreshes it (lib/tailnet-self-name.ts refreshIfMissing: bounded, single-flight,
+   * rate-limited). Absent: the null origin stands, as before.
+   */
+  refreshOrigin?: () => Promise<unknown>
   /** How often the signer's files are re-checked. 0: never on a timer (tests call integrity.check()). */
   recheckMs?: number
 }
@@ -128,13 +135,25 @@ export function createWebKeySignerHandler(deps: WebKeySignerDeps): ((req: Incomi
     const method = String(req.method ?? 'GET').toUpperCase()
 
     if (pathname === '/api' || pathname.startsWith('/api/')) {
+      const decide = (expected: string | null): void => {
+        const origin = typeof req.headers.origin === 'string' ? req.headers.origin : undefined
+        // Another origin's page never drives this one. A write must name this origin outright.
+        if (origin !== undefined && origin !== expected) { json(res, 403, { ok: false, error: 'origin_refused' }); return }
+        if (method !== 'GET' && method !== 'HEAD' && (expected === null || origin !== expected)) { json(res, 403, { ok: false, error: 'origin_refused' }); return }
+        if (!signerApiAllowed(method === 'HEAD' ? 'GET' : method, pathname)) { json(res, 404, { ok: false, error: 'not_found' }); return }
+        deps.api(req, res)
+      }
       const expected = deps.origin()
-      const origin = typeof req.headers.origin === 'string' ? req.headers.origin : undefined
-      // Another origin's page never drives this one. A write must name this origin outright.
-      if (origin !== undefined && origin !== expected) { json(res, 403, { ok: false, error: 'origin_refused' }); return }
-      if (method !== 'GET' && method !== 'HEAD' && (expected === null || origin !== expected)) { json(res, 403, { ok: false, error: 'origin_refused' }); return }
-      if (!signerApiAllowed(method === 'HEAD' ? 'GET' : method, pathname)) { json(res, 404, { ok: false, error: 'not_found' }); return }
-      deps.api(req, res)
+      if (expected !== null || !deps.refreshOrigin) { decide(expected); return }
+      // Name unknown: one bounded lookup, then the same checks against whatever it found (null still refuses).
+      let refreshing: Promise<unknown>
+      try { refreshing = Promise.resolve(deps.refreshOrigin()) } catch { refreshing = Promise.resolve() }
+      const after = (): void => {
+        let found: string | null = null
+        try { found = deps.origin() } catch { found = null }
+        decide(found)
+      }
+      void refreshing.then(after, after)
       return
     }