@gotcos/glasses-server 6.99.33 → 7.0.18

package/server/lib/session-files-setting.ts

@@ -0,0 +1,88 @@
+/**
+ * "Show files and images your sessions make" (6.99.35). Miles asked where a person opts in to the images (6.99.28) and
+ * files (SendUserFile) Control Web shows from a session's project folder. This is that switch, stored the way the
+ * Today summary switch is (lib/today-brief.ts): a small private JSON file in the data folder, written atomically.
+ *
+ * - DEFAULT ON, as both features shipped.
+ * - The Settings toggle (Control Web, Settings, Privacy) saves { schema: 1, enabled } to web-session-files-settings.json.
+ * - COS_WEB_SESSION_FILES=0 (or false, off) on the Mac forces it OFF, whatever was saved. No value forces it on: an
+ *   environment that wants previews leaves the variable unset.
+ * - Read on every request, so a change applies at once and a restart is never needed.
+ * - QA 7.0.0: only a file that is not there (first use) gets the default. A saved file that is damaged, unreadable or
+ *   not this schema fails CLOSED (source 'damaged', off): it may have said off, and a privacy switch never turns itself
+ *   back on. The Settings row says so, and saving from it writes a good file again.
+ *
+ * Preview engine phase 1: link cards (outputLinks) and GET /api/preview/... ride the same switch, default on.
+ *
+ * Off means: GET .../output-images/:id/content, .../output-files/:id/content and .../tool-images/:id/content answer 403 previews_off before any
+ * transcript or file is read, and the session detail's turns carry `previewsOff: true` instead of image and file
+ * descriptors (withoutPreviews), so not even a name reaches the browser.
+ */
+import { readFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { durableAtomicWriteFileSync } from './atomic-fs.js'
+import { dataPath } from './data-dir.js'
+import { readSwitch } from './env-switch.js'
+import { securePrivateDirectory } from './secure-user-config.js'
+import type { SessionTurn } from './agent-session-turns.js'
+import { withoutLinkCards } from './session-links.js'
+
+export const SESSION_FILES_SETTINGS_FILE = 'web-session-files-settings.json'
+export type SessionFilesSource = 'env' | 'settings' | 'default' | 'damaged'
+export interface SessionFilesSetting { enabled: boolean; source: SessionFilesSource; saved: boolean | null }
+export interface SessionFilesSettingStore {
+  read(): SessionFilesSetting
+  set(enabled: boolean): SessionFilesSetting
+}
+
+export function createSessionFilesSetting(deps: { file: () => string; env?: () => Record<string, string | undefined> }): SessionFilesSettingStore {
+  const env = deps.env ?? (() => process.env)
+  // 'absent' only for ENOENT (first use). Any other read error, bad JSON or a foreign shape is 'damaged'.
+  type Saved = { kind: 'absent' } | { kind: 'damaged' } | { kind: 'saved'; enabled: boolean }
+  const saved = (): Saved => {
+    let text: string
+    try { text = readFileSync(deps.file(), 'utf8') } catch (e) {
+      return (e as NodeJS.ErrnoException | null)?.code === 'ENOENT' ? { kind: 'absent' } : { kind: 'damaged' }
+    }
+    try {
+      const raw = JSON.parse(text) as unknown
+      if (raw && typeof raw === 'object' && (raw as { schema?: unknown }).schema === 1 && typeof (raw as { enabled?: unknown }).enabled === 'boolean') {
+        return { kind: 'saved', enabled: (raw as { enabled: boolean }).enabled }
+      }
+    } catch { /* damaged */ }
+    return { kind: 'damaged' }
+  }
+  const store: SessionFilesSettingStore = {
+    read() {
+      const s = saved()
+      const value = s.kind === 'saved' ? s.enabled : null
+      // Only an off value forces anything; readSwitch with an ON fallback is false exactly for 0, false and off.
+      if (!readSwitch(env().COS_WEB_SESSION_FILES, true)) return { enabled: false, source: 'env', saved: value }
+      if (s.kind === 'saved') return { enabled: s.enabled, source: 'settings', saved: s.enabled }
+      if (s.kind === 'damaged') return { enabled: false, source: 'damaged', saved: null }
+      return { enabled: true, source: 'default', saved: null }
+    },
+    set(enabled) {
+      const file = deps.file()
+      securePrivateDirectory(dirname(file))
+      durableAtomicWriteFileSync(file, JSON.stringify({ schema: 1, enabled }) + '\n', { mode: 0o600 })
+      return store.read()
+    },
+  }
+  return store
+}
+
+/** The server's switch, in the data folder. */
+export const sessionFilesSetting = createSessionFilesSetting({ file: () => dataPath(SESSION_FILES_SETTINGS_FILE) })
+
+/** Turns with every image and file descriptor (tool-result and prompt images too) removed and `previewsOff` marked where there were any. Pure. */
+export function withoutPreviews(turns: SessionTurn[]): SessionTurn[] {
+  return turns.map(t => {
+    if (!t.outputImages?.length && !t.outputFiles?.length && !t.toolImages?.length && !t.toolImagesMore && !t.outputLinks?.length) return t
+    const { outputImages: _i, outputFiles: _f, toolImages: _t, toolImagesMore: _m, outputLinks: _l, ...rest } = t
+    // Preview engine phase 1: link cards ride this switch. Off, a card marker turns back into the link's words and the
+    // "N more linked files" sentence goes (QA 7.0.5), so not even a count reaches the browser. The Mac path was already
+    // gone from the text (session-links.ts).
+    return { ...rest, ...(_l?.length ? { text: withoutLinkCards(rest.text) } : {}), previewsOff: true as const }
+  })
+}

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

@@ -13,6 +13,8 @@
 // interactive-only events (Notification, StopFailure, sub-agents, compaction, model switch)
 // whose shapes are still the documented ones until a Desktop recording lands.
 
+import { questionRowText, waitingQuestionWordsEnabled } from './full-hold.js'
+import { captureTurnAsk, turnEndAsksEnabled, WRAP_UP_TOOL } from './turn-end-ask.js'
 import { createHash } from 'node:crypto'
 import { profileIdForCodexPath } from './codex-homes.js'
 import { isKeyProfileId } from '../../shared/key-preference.js'
@@ -208,12 +210,31 @@ function canonicalJson(value: unknown): string {
 export function toolTarget(toolInput: unknown, max = 80): string {
   if (!toolInput || typeof toolInput !== 'object') return ''
   const i = toolInput as Record<string, unknown>
-  const candidate = [i.command, i.file_path, i.path, i.url, i.pattern, i.query, i.prompt, i.description]
+  // X1: an AskUserQuestion carries only `questions`. With COS_WAITING_QUESTION_WORDS on (default ON, Miles
+  // 22:10) its target is its first question's text, control and format characters out, cut at `max` (80)
+  // below, so a row waiting on a question says what it asks. Never an option, a description or an answer.
+  // `0`: a question's target is '' exactly as in 7.0.13, and the words reach neither the ledger nor a row.
+  const firstQuestion = waitingQuestionWordsEnabled(process.env) && Array.isArray(i.questions) && i.questions.length > 0 && i.questions[0] && typeof i.questions[0] === 'object'
+    ? questionRowText((i.questions[0] as Record<string, unknown>).question)
+    : undefined
+  const candidate = [i.command, i.file_path, i.path, i.url, i.pattern, i.query, i.prompt, i.description, firstQuestion]
     .find(v => typeof v === 'string' && v.trim().length > 0)
   const text = typeof candidate === 'string' ? candidate.replace(/\s+/g, ' ').trim() : ''
   return text.length > max ? text.slice(0, max - 1) + '…' : text
 }
 
+/**
+ * 7.0.18 (X1): a turn-end ask (lib/turn-end-ask.ts) kept in the ledger so a restart replays it. Only on a
+ * PostToolUse of `mcp__ccd_turn__wrap_up`, only with COS_TURN_END_ASKS on, and only the bounded capture:
+ * the ask (80), at most 2 reply labels (40) and `blocked`. Never `recap`, never `tool_response`. An
+ * additive key, so 7.0.17 replays the row and ignores it. `tool_target` stays as 7.0.17 computes it.
+ */
+function turnAskProjection(event: HookEventName, toolName: string, toolInput: unknown): Record<string, unknown> {
+  if (event !== 'PostToolUse' || toolName !== WRAP_UP_TOOL || !turnEndAsksEnabled()) return {}
+  const capture = captureTurnAsk(toolInput, waitingQuestionWordsEnabled(process.env))
+  return capture ? { turn_ask: capture } : {}
+}
+
 /** Text fields kept from a payload. Everything else is dropped before the ledger sees it. */
 export const HOOK_TEXT_MAX = 400
 
@@ -272,6 +293,7 @@ export function projectHookPayload(event: HookEventName, payload: Record<string,
         ...(event === 'PermissionRequest' && Array.isArray(payload.permission_suggestions)
           ? { permission_suggestions: payload.permission_suggestions.slice(0, 4) }
           : {}),
+        ...turnAskProjection(event, toolName, payload.tool_input),
       }
     }
     case 'Notification':

package/server/lib/session-hooks-runtime.ts

@@ -21,6 +21,9 @@ import { HALT_MARKER_TTL_MS, HALT_REARM_UNVERIFIED_MS, clearHaltMarkerOnSessionE
 import { cancelVoidsOpenTurn, threadCancel } from './session-cancel.js'
 import { ensureHookRuntimeFiles, ensureStableHookScript, hookSpoolDir, hookStatus, type HookStatus } from './claude-hooks-installer.js'
 import { codexHooksHealthField, cursorObserverHealthField, type CodexHooksHealth, type CursorObserverHealth } from './provider-observe.js'
+import { readHidIdleSeconds } from './permission-broker.js'
+import { waitingQuestionWordsEnabled } from './full-hold.js'
+import { TurnEndAskTracker, turnEndAsksEnabled, type TurnEndAskCounters } from './turn-end-ask.js'
 
 export function sessionHooksEnabled(): boolean {
   const raw = process.env.COS_SESSION_HOOKS
@@ -256,6 +259,8 @@ export function haltHandedOffTurn(sessionId: string, marker: HaltMarker, turn: {
 let ledger: SessionHookLedger | null = null
 let ingester: SpoolIngester | null = null
 let replayed: { rows: number; applied: number } | null = null
+/** 7.0.18 (X1): the turn-end ask tracker, only while COS_TURN_END_ASKS is on (read once at startup). */
+let turnEndAskTracker: TurnEndAskTracker | null = null
 /** The two-scan memory: consecutive dead observations and when the first one was. */
 const deadById = new Map<string, { scans: number; since: number | null; at: number }>()
 const DEAD_MEMORY_MS = 60 * 60_000
@@ -271,6 +276,18 @@ export function startSessionHooksRuntime(options: { port: number }): SessionHook
   ledger = new SessionHookLedger(dataPath('session-hook-events.jsonl'))
   const enabled = sessionHooksEnabled()
   const since = Date.now() - LEDGER_REPLAY_WINDOW_MS
+  // 7.0.18 (X1): subscribed BEFORE the replay, so an ask asked before a restart is still known after it.
+  // Off (COS_TURN_END_ASKS=0): no tracker, no subscription, no desk reads, every row 7.0.17's.
+  turnEndAskTracker?.stop()
+  turnEndAskTracker = enabled && turnEndAsksEnabled() ? new TurnEndAskTracker({
+    now: () => Date.now(),
+    enabled: () => true,
+    words: () => waitingQuestionWordsEnabled(process.env),
+    readDeskIdleSeconds: readHidIdleSeconds,
+    deskIdleSeconds,
+  }) : null
+  const tracker = turnEndAskTracker
+  const unsubscribeTurnAsk = tracker ? sessionSignalStore.subscribe((signal, env, child) => tracker.observe(env, child, signal)) : () => {}
   const replay = ledger.replay(since, (env, _key, child, entrypoint) => {
     if (!enabled) return
     sessionSignalStore.apply(env, child)
@@ -321,6 +338,8 @@ export function startSessionHooksRuntime(options: { port: number }): SessionHook
     stop() {
       clearInterval(pruneTimer)
       unsubscribeHalt()
+      unsubscribeTurnAsk()
+      tracker?.stop()
       ingester?.stop()
     },
   }
@@ -472,8 +491,10 @@ export function deriveForRow(input: { sessionId: string; registry?: RegistryFact
     prevDeadScans: prev?.scans ?? 0,
     prevDeadSince: prev?.since ?? null,
     attachedTurn: input.attachedTurn === true,
+    ...(turnEndAskTracker ? { turnEndAsk: turnEndAskTracker.visibleAsk(key, now) } : {}),
   })
   if (derived.agent_state === 'ended') {
+    turnEndAskTracker?.sessionRowEnded(key)
     for (const listener of rowEndedListeners) {
       try { listener(key) } catch { /* a listener never breaks a row */ }
     }
@@ -489,7 +510,20 @@ export function deriveForRow(input: { sessionId: string; registry?: RegistryFact
   return derived
 }
 
+/** 7.0.18 (X1): the turn-end ask counters for the authenticated stats, or null with the switch off. */
+export function turnEndAskStats(): (TurnEndAskCounters & { tracked: number }) | null {
+  return turnEndAskTracker ? turnEndAskTracker.stats() : null
+}
+
+/** Tests only: the tracker the runtime would build, installed directly. */
+export function __setTurnEndAskTrackerForTests(tracker: TurnEndAskTracker | null): void {
+  turnEndAskTracker?.stop()
+  turnEndAskTracker = tracker
+}
+
 export function __resetSessionHooksForTests(): void {
+  turnEndAskTracker?.stop()
+  turnEndAskTracker = null
   rowEndedListeners.clear()
   sessionSignalStore.__resetForTests()
   deadById.clear()

package/server/lib/session-links.ts

@@ -0,0 +1,280 @@
+/**
+ * Link cards (preview engine phase 1, PLAN_preview_engine_2026-11-08 4f). A Markdown link in a reply to a local file
+ * becomes a card where it sits. 40% of sessions link a local file; 3,389 links in 14 days, none of which worked.
+ *
+ * This module is pure apart from filesystem reads in `resolveLinkTarget`:
+ *   - `linkTokens`: the same bounded scanner as the inline-image tokens, for `[label](target)`. Code fences, inline
+ *     code, indented blocks and comments stay inert. Web URLs and #anchors are not local and stay as written.
+ *   - `splitLineAnchor`: `file.ts:42`, `:42:7`, `:42-50` and `#L42` become `line`, never part of the name.
+ *   - `resolveLinkTarget`: the row's cwd first, then the workspace root (21% of relative links need the root), then
+ *     authorized only inside the workspace or a Settings extra folder, and never a denied secret name.
+ *   - `previewKind`: what the viewer does with a name.
+ *
+ * Paths never leave the server: a card carries a base name, the link's words and an opaque id.
+ */
+import { realpathSync, statSync } from 'node:fs'
+import { isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { isDeniedSecretPath } from './secret-path-guard.js'
+
+export const LINK_CARDS_PER_TURN = 20
+export const SESSION_OUTPUT_LINK_ID = /^al_[a-f0-9]{64}$/
+/** The marker a card leaves in the projected text: `[label](cos-file:N)`, N the index into the turn's outputLinks. */
+export const LINK_MARKER = /\[([^\]\n]*)\]\(cos-file:(\d{1,2})\)/g
+
+export type PreviewKind = 'image' | 'pdf' | 'html' | 'markdown' | 'text' | 'code' | 'table' | 'document' | 'slides' | 'sheet'
+  | 'audio' | 'video' | 'archive' | 'folder' | 'file'
+/** `secret_file`: the 7.0.4 shared deny list (secret-path-guard.ts) refused the name, as written or canonically. */
+export type LinkReason = 'outside_workspace' | 'missing' | 'unavailable' | 'secret_file'
+
+/** A link card. Only a base name, the link's words and an opaque id travel; never a Mac path. */
+export interface SessionOutputLink {
+  id: string
+  label: string
+  name: string
+  kind: PreviewKind
+  type: string
+  size?: number
+  line?: number
+  state: 'available' | 'unavailable'
+  reason?: LinkReason
+  /** The words the card shows instead (SECRET_FILE_NOTICE), set only with `secret_file`. */
+  notice?: string
+}
+
+export interface LinkToken { label: string; target: string; start: number; end: number }
+
+const KINDS: Array<[RegExp, PreviewKind, string]> = [
+  [/\.(png|jpe?g|webp|hei[cf]|avif)$/i, 'image', 'Image'],
+  [/\.gif$/i, 'image', 'GIF image'],
+  [/\.pdf$/i, 'pdf', 'PDF'],
+  [/\.html?$/i, 'html', 'HTML page'],
+  [/\.(md|markdown|mdx)$/i, 'markdown', 'Markdown'],
+  [/\.csv$/i, 'table', 'CSV'],
+  [/\.tsv$/i, 'table', 'TSV'],
+  [/\.(txt|log|text)$/i, 'text', 'Text'],
+  [/\.json$/i, 'code', 'JSON'],
+  [/\.jsonl$/i, 'code', 'JSON lines'],
+  [/\.ya?ml$/i, 'code', 'YAML'],
+  [/\.toml$/i, 'code', 'TOML'],
+  [/\.xml$/i, 'code', 'XML'],
+  // An SVG can carry script, so it is shown as its source, never as a picture.
+  [/\.svg$/i, 'code', 'SVG source'],
+  [/\.(ts|tsx|mts|cts)$/i, 'code', 'TypeScript'],
+  [/\.(js|jsx|mjs|cjs)$/i, 'code', 'JavaScript'],
+  [/\.py$/i, 'code', 'Python'],
+  [/\.swift$/i, 'code', 'Swift'],
+  [/\.(sh|zsh|bash)$/i, 'code', 'Shell script'],
+  [/\.(css|scss)$/i, 'code', 'CSS'],
+  [/\.(rb|go|rs|java|kt|c|h|cc|cpp|hpp|m|mm|sql|lua|php)$/i, 'code', 'Source code'],
+  [/\.(plist|ini|conf|cfg|properties)$/i, 'code', 'Settings file'],
+  [/\.docx?$/i, 'document', 'Word document'],
+  [/\.(pages|rtf)$/i, 'document', 'Document'],
+  [/\.xlsx?$/i, 'sheet', 'Excel workbook'],
+  [/\.numbers$/i, 'sheet', 'Spreadsheet'],
+  [/\.pptx?$/i, 'slides', 'PowerPoint deck'],
+  [/\.key$/i, 'slides', 'Keynote deck'],
+  [/\.(wav|mp3|m4a|aac|flac|aiff?)$/i, 'audio', 'Audio'],
+  [/\.(mp4|mov|webm|m4v)$/i, 'video', 'Video'],
+  [/\.(zip|tar|gz|tgz|bz2|xz|7z)$/i, 'archive', 'Archive'],
+  [/\.ehpk$/i, 'archive', 'EHPK package'],
+]
+export function previewKind(name: string): { kind: PreviewKind; type: string } {
+  for (const [re, kind, type] of KINDS) if (re.test(name)) return { kind, type }
+  const ext = /\.([a-z0-9]{1,8})$/i.exec(name)
+  return { kind: 'file', type: ext ? ext[1].toUpperCase() + ' file' : 'File' }
+}
+
+/** The base name a person sees: no directories, no control characters, at most 120 characters. */
+export function baseName(source: string): string {
+  const base = source.split(/[\\/]/).filter(Boolean).pop() || ''
+  const clean = base.replace(/[\u0000-\u001f\u007f]/g, '').trim()
+  return (clean || 'File').slice(0, 120)
+}
+
+/**
+ * A link's words, made safe to show: a label that is itself an absolute or home path becomes its base name, so
+ * `[/Users/x/plan.md](/Users/x/plan.md)` never puts the path in front of anyone. Anything else is kept (120 chars).
+ */
+export function linkLabel(label: string, name: string): string {
+  const clean = label.replace(/[\u0000-\u001f\u007f]/g, ' ').trim()
+  if (!clean) return name
+  if (/^(?:file:\/\/|~\/|\/)/.test(clean) || /(?:^|[\s(`'"])(?:\/Users\/|\/private\/|\/Volumes\/|\/var\/folders\/)/.test(clean)) return baseName(clean.replace(/^file:\/\//, ''))
+  return clean.slice(0, 120)
+}
+
+/**
+ * The words a link card shows in the reply. A label that is the file's own name keeps the line the link points at,
+ * so `[app.ts](/Users/x/app.ts#L42)` reads `app.ts:42`, as the 7.0.4 redactor wrote it. Prose labels stay as written.
+ */
+export function linkCardWords(label: string, name: string, target: string): string {
+  const words = linkLabel(label, name)
+  const { path, line } = splitLineAnchor(target)
+  if (!line) return words
+  const own = baseName(path.replace(/^file:\/\//i, ''))
+  return words === own || words === name ? words + ':' + line : words
+}
+
+export const LINK_SCAN_CHARS = 128 * 1024
+
+/**
+ * `[label](target)` tokens in reply text, never `![..](..)` (images have their own scanner). Bounded like the image
+ * scanner: inert inside fences, inline code, indented blocks and comments; the label has no brackets or newline; the
+ * target is angle-wrapped (spaces allowed) or balanced parentheses on one line. A trailing ` "title"` is dropped.
+ */
+export function linkTokens(raw: string, scanChars = LINK_SCAN_CHARS): LinkToken[] {
+  const text = raw.slice(0, scanChars)
+  const out: LinkToken[] = []
+  let fence = '', inline = 0
+  for (let i = 0; i < text.length; i++) {
+    if (i === 0 || text[i - 1] === '\n') {
+      if (!fence && /^(?: {4}| {0,3}\t)/.test(text.slice(i, i + 4))) { i = text.indexOf('\n', i); if (i < 0) break; continue }
+      const m = /^( {0,3})(`{3,}|~{3,})/.exec(text.slice(i, i + 80))
+      if (m) { if (!fence) fence = m[2]; else if (m[2][0] === fence[0] && m[2].length >= fence.length) fence = ''; i = text.indexOf('\n', i); if (i < 0) break; continue }
+    }
+    if (fence) continue
+    if (text[i] === '\\') { i++; continue }
+    if (text[i] === '`') { let n = 1; while (text[i + n] === '`') n++; if (!inline) inline = n; else if (inline === n) inline = 0; i += n - 1; continue }
+    if (inline) continue
+    if (text.startsWith('<!--', i)) { const end = text.indexOf('-->', i + 4); if (end < 0) break; i = end + 2; continue }
+    if (text[i] !== '[' || text[i - 1] === '!') continue
+    const close = text.indexOf(']', i + 1)
+    if (close < 0 || close - i > 250 || text[close + 1] !== '(') continue
+    const label = text.slice(i + 1, close)
+    if (label.includes('[') || label.includes('\n')) continue
+    let j = close + 2, target = '', valid = false
+    if (text[j] === '<') {
+      const end = text.indexOf('>', j + 1)
+      if (end >= 0 && text[end + 1] === ')' && !text.slice(j + 1, end).includes('\n')) { target = text.slice(j + 1, end); j = end + 2; valid = true }
+    } else {
+      const start = j; let depth = 1
+      while (j < text.length && j - start <= 4096) {
+        if (text[j] === '\n') break
+        if (text[j] === '(') depth++
+        if (text[j] === ')' && --depth === 0) { target = text.slice(start, j); j++; valid = true; break }
+        j++
+      }
+    }
+    if (!valid || !target || target.length > 4096 || /[\u0000-\u001f\u007f]/.test(target)) continue
+    const titled = /^(\S+)\s+"[^"]*"$/.exec(target)
+    if (titled) target = titled[1]
+    out.push({ label, target, start: i, end: j }); i = j - 1
+  }
+  return out
+}
+
+/** A target that names a local file: a path, `~/...` or `file://`. Web URLs, mail, anchors and network paths are not. */
+export function isLocalTarget(target: string): boolean {
+  if (!target || target.startsWith('#') || target.startsWith('//') || target.includes('\\')) return false
+  if (/^file:\/\//i.test(target)) return true
+  // `server.ts:42` is a path with a line, not a scheme.
+  return !/^[a-z][a-z0-9+.-]*:/i.test(splitLineAnchor(target).path)
+}
+
+/** `x.ts:42`, `x.ts:42:7`, `x.ts:42-50`, `x.ts#L42`, `x.ts#L42-L50` → the path and line 42. */
+export function splitLineAnchor(target: string): { path: string; line?: number } {
+  let m = /^(.*?)#L(\d{1,7})(?:C\d+)?(?:-L?\d{1,7})?$/.exec(target)
+  if (m && m[1]) return { path: m[1], line: Number(m[2]) || undefined }
+  m = /^(.*?):(\d{1,7})(?::\d{1,5}|-\d{1,7})?$/.exec(target)
+  if (m && m[1] && !/:$/.test(m[1])) return { path: m[1], line: Number(m[2]) || undefined }
+  const hash = target.indexOf('#')
+  return { path: hash > 0 ? target.slice(0, hash) : target }
+}
+
+export interface LinkRoots {
+  /** The session's canonical workspace, or null (broad or unknown). */
+  workspace: string | null
+  /** Canonical Settings extra folders. */
+  extra: readonly string[]
+  home: string
+}
+export type Resolved =
+  | { state: 'available'; path: string; root: string; name: string; isDir: boolean; size?: number }
+  | { state: 'unavailable'; reason: LinkReason; name: string }
+
+export function insideRoot(root: string, path: string): boolean {
+  const rel = relative(root, path)
+  return rel !== '' && rel !== '..' && !rel.startsWith('..' + sep) && !isAbsolute(rel)
+}
+/** The allowed root holding a canonical path, or null. */
+export function authorizedRoot(path: string, roots: LinkRoots): string | null {
+  if (roots.workspace && insideRoot(roots.workspace, path)) return roots.workspace
+  for (const r of roots.extra) if (insideRoot(r, path)) return r
+  return null
+}
+
+function expandTarget(target: string, home: string): string | null {
+  if (/^file:\/\//i.test(target)) { try { return fileURLToPath(target) } catch { return null } }
+  if (target === '~') return home
+  if (target.startsWith('~/')) return join(home, target.slice(2))
+  return target
+}
+
+/**
+ * Where a link points, and whether COS may show it. Bases: the row's cwd, then the workspace root. A relative link
+ * that exists under neither is missing (when it would sit inside an allowed root) or outside. The canonical file
+ * decides containment, so a link out of the root is outside. A denied secret name is refused before any read, by its
+ * written name and by its canonical name.
+ */
+export function resolveLinkTarget(rawTarget: string, bases: readonly (string | null | undefined)[], roots: LinkRoots): Resolved {
+  const { path: written } = splitLineAnchor(rawTarget)
+  const variants = [written]
+  if (/%[0-9a-f]{2}/i.test(written)) { try { const d = decodeURIComponent(written); if (d !== written) variants.push(d) } catch { /* keep as written */ } }
+  // A percent-encoded name reads as its words ("Q3 plan.md", not "Q3%20plan.md").
+  const name = baseName(variants[variants.length - 1])
+  const lexicals: string[] = []
+  for (const v of variants) {
+    const expanded = expandTarget(v, roots.home)
+    if (!expanded) continue
+    if (isAbsolute(expanded)) lexicals.push(resolve(expanded))
+    else for (const b of bases) if (b && isAbsolute(b)) lexicals.push(resolve(b, expanded))
+  }
+  if (!lexicals.length) return { state: 'unavailable', reason: 'outside_workspace', name }
+  if (lexicals.some(p => isDeniedSecretPath(p))) return { state: 'unavailable', reason: 'secret_file', name }
+  for (const lexical of lexicals) {
+    let canonical: string
+    try { canonical = realpathSync(lexical) } catch { continue }
+    const root = authorizedRoot(canonical, roots)
+    if (!root) return { state: 'unavailable', reason: 'outside_workspace', name }
+    if (isDeniedSecretPath(canonical)) return { state: 'unavailable', reason: 'secret_file', name }
+    try {
+      const st = statSync(canonical)
+      if (st.isDirectory()) return { state: 'available', path: canonical, root, name, isDir: true }
+      if (!st.isFile()) return { state: 'unavailable', reason: 'missing', name }
+      // 7.0.4 QA's sent-file rule: a file with another hard link may be a secret under this name. Pictures are exempt
+      // (they are normalised to a JPEG, never served as they are).
+      if (st.nlink > 1 && !/\.(png|jpe?g|webp|hei[cf]|avif)$/i.test(canonical)) return { state: 'unavailable', reason: 'secret_file', name }
+      return { state: 'available', path: canonical, root, name, isDir: false, size: st.size }
+    } catch { return { state: 'unavailable', reason: 'missing', name } }
+  }
+  // Nothing there. Say missing only for a path that would be inside an allowed root (by its real parent folder).
+  const wouldBeInside = lexicals.some(p => {
+    if (authorizedRoot(p, roots)) return true
+    try { return authorizedRoot(join(realpathSync(resolve(p, '..')), baseName(p)), roots) !== null } catch { return false }
+  })
+  return { state: 'unavailable', reason: wouldBeInside ? 'missing' : 'outside_workspace', name }
+}
+
+/** Text with every card marker turned back into its words. Used when previews are off. Pure. */
+export function withoutLinkMarkers(text: string): string {
+  return text.replace(LINK_MARKER, '$1')
+}
+
+/** The sentence a reply ends with when it links more files than LINK_CARDS_PER_TURN (added after its last word). */
+export function linkOverflowSentence(extra: number): string {
+  return extra + (extra === 1 ? ' more linked file is not shown as a card.' : ' more linked files are not shown as cards.')
+}
+const LINK_OVERFLOW = /\n\n\d{1,6} more linked files? (?:is|are) not shown as (?:a )?cards?\./g
+/** The reply cap can cut the sentence: `\n\n23 more linked fi…`, at the end or just before the scan-limit line. */
+const LINK_OVERFLOW_CUT = /\n\n(\d{1,6})([^\n…]*)…(?=\n\[Reply shortened at the image preview scan limit\.\]$|$)/
+
+/**
+ * QA 7.0.5 (agent 4 C-N1): previews off sends no count, so the overflow sentence goes as well as the markers. A cut
+ * sentence goes only when what is left is exactly the start of that sentence, so a reply's own words stay. Pure.
+ */
+export function withoutLinkCards(text: string): string {
+  const out = withoutLinkMarkers(text).replace(LINK_OVERFLOW, '')
+  const cut = LINK_OVERFLOW_CUT.exec(out)
+  if (!cut || !linkOverflowSentence(Number(cut[1])).startsWith(cut[1] + cut[2])) return out
+  return out.slice(0, cut.index) + out.slice(cut.index + cut[0].length)
+}