@gotcos/glasses-server 6.3.1 → 6.5.0

package/.env.example

@@ -19,18 +19,29 @@ BIND_HOST=0.0.0.0
 # here for a stable token across restarts.
 # COS_API_TOKEN=pick-any-long-random-string
 
+# Optional durable image-store location. Defaults to
+# ~/.cos-glasses/data/media alongside the standalone conversation/archive data.
+# COS_MEDIA_ROOT=/path/on-a-local-volume/media
+
 # ── THE LLM (chat) ──────────────────────────────────────────────────────
 # Chat runs through your LOCAL agent CLI — NOT an API key:
-#   Opus / Sonnet / Haiku  ->  Claude Code CLI  (https://claude.ai/download, then `claude login`)
-#   Codex High             ->  Codex CLI        (https://developers.openai.com/codex/, then `codex login`)
+#   Opus / Fable / Sonnet  ->  Claude Code CLI  (https://claude.ai/download, then `claude login`)
+#   GPT Frontier/Balanced  ->  Codex CLI        (https://developers.openai.com/codex/, then `codex login`)
 # Install at least one. Pick the default model the glasses use:
-# COS_G2_DEFAULT_MODEL=sonnet     # opus | sonnet | haiku | codex-high
+# COS_G2_DEFAULT_MODEL=sonnet     # opus | fable | sonnet | codex-frontier | codex-balanced
+#
+# GPT slots refresh from the Codex model catalog every 15 minutes and retain
+# their last-known-good resolution if discovery is temporarily unavailable.
+# COS_CODEX_MODEL_REFRESH_TTL_MS=900000
+# COS_CODEX_MODEL_REFRESH_TIMEOUT_MS=7000
 #
-# Codex options (only used for the codex-high model):
-#   COS_CODEX_MODEL pins a specific codex model id; blank = use your codex CLI default.
-#   COS_CODEX_REASONING_EFFORT is low | medium | high (default high).
+# Legacy explicit overrides remain supported for migrated codex-high/frontier
+# installs. Leave blank for auto-latest; Balanced always stays auto-catalog.
 # COS_CODEX_MODEL=
-# COS_CODEX_REASONING_EFFORT=high
+# COS_CODEX_REASONING_EFFORT=high   # low | medium | high | xhigh | max | ultra
+#
+# Codex remains read-only by default. This is the only broader trust opt-in:
+# COS_CODEX_SANDBOX=workspace-write
 
 # ── VOICE (optional) ────────────────────────────────────────────────────
 # Local transcription is FREE via whisper.cpp (brew install whisper-cpp; the

package/CHANGELOG.md

@@ -1,5 +1,88 @@
 # Changelog
 
+## 6.5.0
+
+Durable phone photos and assistant-selected output images for COS Glasses
+build 179, while preserving the public server's sandbox and privacy boundary.
+
+- **One media contract.** Authenticated phone uploads become opaque attachment
+  refs, survive queues/restarts/archives/numbered-message recall, and resolve to
+  normalized server-owned files for Claude/Codex. Bytes and storage paths never
+  enter SSE, run ledgers, or archives.
+- **Answer images.** Claude or Codex can publish an already-local generated,
+  researched, or explicitly used email image through a private run-scoped
+  capability. The server accepts JPEG/PNG/WebP/HEIC/HEIF/AVIF up to 16 MiB and
+  16 megapixels, strips metadata, re-encodes through the existing media store,
+  and appends refs to the completed answer.
+- **No mailbox or URL crawler.** The publisher rejects URLs, data URIs, base64,
+  unrelated discovery, symlinks, directory replacement, content-id tampering,
+  over-capacity output, and manifest fields that could carry private paths.
+- **Codex remains read-only.** Output publishing adds only the random private
+  run directory via `codex exec --add-dir`; global sandbox flags precede
+  `resume`. Older CLIs without `--add-dir` keep chat working and simply disable
+  Codex output-image publishing. There is no full-access fallback.
+- **Durable finalization.** Assistant text is persisted before image
+  normalization, request media associates even if SSE disconnects, partial
+  image failures do not discard successful refs, and completion emits one
+  canonical `attachments` list with safe aggregate stats.
+- **Lens contract.** `/api/health` advertises `mediaProcessingReady` and
+  `g2LensVariant=png-288x144-v1`; the media endpoint serves the validated phone,
+  thumbnail, and exact 288×144 G2 variants expected by build 179.
+- **Fresh-install diagnostics.** The npm launcher now reports whether ffmpeg is
+  ready for phone/output/lens images, gives a non-blocking install command when
+  absent, and sends setup questions directly to `gotcos.com/wizard/`.
+- **One server owner.** The public runner now claims the same atomic
+  machine-wide lock as the installed LaunchAgent before mutable modules load.
+  A duplicate exits with code 75, and HTTP/HTTPS listeners bind as one required
+  set: if either port is occupied, any earlier listener closes and the process
+  exits instead of surviving half-bound with separate SSE and media state.
+
+Release evidence: TypeScript, 130/130 tests across 23 files, package dry-run
+including the executable publisher and startup hardening, and a live duplicate
+start against the installed LaunchAgent rejected before server initialization.
+
+## 6.4.0
+
+Fresh-install parity for COS Glasses builds 170–173, without weakening the
+public server's sandbox defaults.
+
+- **Auto-updating GPT Frontier + Balanced.** Stable client slots resolve to the
+  top two capable models in the newest visible GPT generation through Codex's
+  official `model/list` catalog. The server refreshes at boot and every 15
+  minutes, and each Codex run awaits the same TTL-cached/coalesced refresh
+  before resolving its slot. It preserves the last-known-good catalog on
+  failures and falls back to the CLI default only before any discovery succeeds.
+- **Fable + effort controls.** Fable joins Opus and Sonnet as a first-class
+  Claude tier alias, and High / Extra High / Max / Ultracode now propagate from
+  `/api/query` to both Claude and Codex. Claude aliases remain versionless and
+  1M-context capable; Codex effort is clamped to each live model's advertised
+  support. Per-run ledgers record the concrete resolved model and effort.
+- **Safe live job activity.** `activityToolMode` supports off, status-only, or
+  bounded observable tool input/output previews. ANSI/control data, credential
+  assignments, auth headers, provider tokens, JWTs, URL credentials, and opaque
+  blobs are redacted, including 40–72-character PEM/private-key body chunks.
+  Hidden reasoning is never surfaced.
+- **Same-session run safety.** Turns for one conversation now serialize until
+  the active bridge sends a terminal callback, while different sessions remain
+  concurrent. Failed or cancelled Claude/Codex runs remove the exact pending
+  user exchange by object identity, preventing phantom prompts, duplicate-text
+  deletion, and resume-history contamination.
+- **Authenticated transport boundary.** Activity lines are returned only on the
+  authenticated `/api/query` SSE stream. They are deliberately excluded from
+  the unauthenticated global display bus and its replay buffer.
+- **Public trust model retained.** Codex remains read-only by default with only
+  the existing `workspace-write` opt-in. Existing archive traversal, local-day,
+  malformed-file, starter-kit launch-directory, and conversation behavior are
+  unchanged. Legacy `codex-high` state migrates to the frontier slot without
+  changing saved thread trust mode.
+- **Diagnostics and compatibility.** `/api/models`, health data, and `/v1/models`
+  expose stable slots plus concrete live models. `cos-codex-high` remains an
+  accepted alias for older clients. Existing `COS_CODEX_MODEL` and
+  `COS_CODEX_REASONING_EFFORT` overrides continue to apply to the migrated
+  legacy/frontier slot; leave them unset for auto-latest. A new regression suite covers catalog
+  selection/fallback/refresh, sandbox arguments, migrations, effort mappings,
+  activity redaction, and the display-bus security boundary.
+
 ## 6.3.1
 
 Security + robustness hardening on the 6.3.0 archive routes, from a 3-agent QA pass. (6.3.0 was never published; 6.3.1 is the first release of the expanded route set.)

package/README.md

@@ -1,7 +1,7 @@
 # COS Glasses Server
 
 Self-hosted AI heads-up display for **Even G2 smart glasses**. Runs on your Mac,
-talks to your local **Claude Code** CLI, and pushes answers, voice
+talks to your local **Claude Code or Codex** CLI, and pushes answers, voice
 transcription, and notes to the lens. Your data never leaves your machine, and no
 API key is pasted into the phone for chat.
 
@@ -11,22 +11,31 @@ API key is pasted into the phone for chat.
 npx @gotcos/glasses-server
 ```
 
-The launcher checks Node, finds your CLI, downloads the local voice model, writes
-`~/.cos-glasses/.env`, and starts the server on `0.0.0.0:3141`. On boot it prints
-an **API token** — paste that into the COS Glasses app.
+The launcher checks Node, finds your CLI, checks voice and image processing,
+downloads the local voice model when needed, writes `~/.cos-glasses/.env`, and
+starts the server on `0.0.0.0:3141`. On boot it prints
+an **API token** — paste that into the COS Glasses app. Only one COS Glasses
+server may run on a Mac at a time; a second `npx` or source runner exits before
+opening ports or touching shared conversation/media state.
 
 ## Requirements
 
 - **Node.js 20.11+** — https://nodejs.org
-- **Claude Code CLI** (Opus/Sonnet/Haiku) — https://claude.ai/download, then `claude login`
-  _or_ **Codex CLI** (Codex High) — https://developers.openai.com/codex/, then `codex login`
+- **Claude Code CLI** (Opus/Fable/Sonnet) — https://claude.ai/download, then `claude login`
+  _or_ **Codex CLI** (GPT Frontier/Balanced) — https://developers.openai.com/codex/, then `codex login`
 - **Even G2 glasses** + the **COS Glasses** app from the Even Hub
 - _Optional:_ `brew install whisper-cpp` for free local voice (otherwise OpenAI API)
+- _Optional:_ `brew install ffmpeg` for phone/output image attachments (text chat remains available without it)
 - _Optional:_ **Tailscale** so your phone reaches your Mac from anywhere
 
 > No `ANTHROPIC_API_KEY` is needed — chat runs through your installed CLI, billed
 > to your existing Claude or Codex subscription. Pick either per query, or set a
-> default with `COS_G2_DEFAULT_MODEL` (`opus`|`sonnet`|`haiku`|`codex-high`).
+> default with `COS_G2_DEFAULT_MODEL` (`opus`|`fable`|`sonnet`|`codex-frontier`|`codex-balanced`).
+> Claude tier aliases and the two GPT slots resolve dynamically, so new model
+> releases do not require a new glasses package. GPT discovery refreshes every
+> 15 minutes and retains its last-known-good catalog through transient failures.
+> Existing `COS_CODEX_MODEL` / `COS_CODEX_REASONING_EFFORT` settings remain
+> supported on the migrated Frontier slot; leave them blank for auto-latest.
 > Codex runs **sandboxed read-only** by default (`COS_CODEX_SANDBOX` to adjust).
 
 ## Connect your phone (the one gotcha)
@@ -44,8 +53,13 @@ The built-in IP allowlist blocks public-internet traffic regardless.
 ## What it does
 
 - Ask anything, get a streamed answer on the lens (`/api/query`, `/v1/chat/completions`)
+- Choose Opus, Fable, Sonnet, GPT Frontier, or GPT Balanced plus High, Extra
+  High, Max, or Ultracode effort; optional redacted tool activity streams only
+  to the authenticated query that requested it
 - Message History + cross-day "reference message N" — your chats are archived by day
   and every message keeps a permanent number you can recall (`/api/archive`, `/api/message/:num`)
+- Send phone photos with queued prompts, and review assistant-selected generated,
+  research, or explicitly used email images in Messages and on the G2 lens
 - Live voice capture + transcription during meetings
 - Local whisper.cpp transcription (free) with OpenAI fallback (optional)
 - Tasks / calendar / people context **if** you run the
@@ -57,7 +71,8 @@ The built-in IP allowlist blocks public-internet traffic regardless.
 Config lives at `~/.cos-glasses/.env` (created on first run). Every key is
 optional except an installed CLI. Highlights: `BIND_HOST`, `PORT`,
 `COS_API_TOKEN` (auto if unset), `OPENAI_API_KEY` (cloud voice fallback),
-`COS_SCRIPTS_DIR` (full pipeline). Your name + transcription vocabulary live in
+`COS_SCRIPTS_DIR` (full pipeline), and `COS_MEDIA_ROOT` (optional image-store
+location; default `~/.cos-glasses/data/media`). Your name + transcription vocabulary live in
 `~/.cos-glasses/.cos-profile.json` (see `.cos-profile.example.json`).
 
 ## Run from source
@@ -74,6 +89,7 @@ BIND_HOST=0.0.0.0 npm run start:server
 - *Phone can't connect* — check `BIND_HOST=0.0.0.0`, the same Tailscale account on both devices, and the correct `100.x` IP + token.
 - *AI queries fail* — run `claude --version` / `codex --version`, then `claude login` / `codex login`.
 - *Voice getting billed?* — install `whisper-cpp` for free local transcription.
+- *Photos unavailable?* — install `ffmpeg`, restart the server, and confirm `/api/health` reports `features.mediaProcessingReady: true`.
 
 ## License
 

package/bin/cli.cjs

@@ -34,13 +34,13 @@ if (process.argv.includes('--help') || process.argv.includes('-h')) {
   console.log('')
   console.log('  Requirements:')
   console.log('    - Node.js 20.11+')
-  console.log('    - Claude Code CLI (Opus / Sonnet / Haiku) or Codex CLI (Codex High)')
+  console.log('    - Claude Code CLI (Opus / Fable / Sonnet) or Codex CLI (GPT Frontier / Balanced)')
   console.log('    - Even G2 smart glasses + the COS Glasses app (Even Hub)')
   console.log('')
   console.log('  No API key is needed for chat — it runs through your installed CLI.')
   console.log('  Config persists at ~/.cos-glasses/.env')
   console.log('')
-  console.log('  Setup guide: https://www.gotcos.com')
+  console.log('  Setup guide: https://www.gotcos.com/wizard/')
   console.log('')
   process.exit(0)
 }
@@ -60,9 +60,9 @@ if (nodeMajor < 20 || (nodeMajor === 20 && nodeMinor < 11)) {
 console.log(green('  ✓') + ` Node.js ${process.versions.node}`)
 
 // Step 2: agent CLI detection — at least one of Claude Code / Codex is required
-function getCliVersion(command) {
+function getCliVersion(command, versionArg = '--version') {
   try {
-    return execSync(`${command} --version 2>&1`, { shell: '/bin/sh', stdio: 'pipe', timeout: 5000 }).toString().trim()
+    return execSync(`${command} ${versionArg} 2>&1`, { shell: '/bin/sh', stdio: 'pipe', timeout: 5000 }).toString().trim()
   } catch {
     return null
   }
@@ -75,15 +75,15 @@ function normalizeCodexVersion(raw) {
 const claudeVersion = getCliVersion('claude')
 const codexVersion = getCliVersion('codex')
 if (claudeVersion) {
-  console.log(green('  ✓') + ` Claude Code ${claudeVersion} ` + dim('(Opus / Sonnet / Haiku)'))
+  console.log(green('  ✓') + ` Claude Code ${claudeVersion} ` + dim('(Opus / Fable / Sonnet)'))
 } else {
-  console.log(yellow('  ⚠') + ' Claude Code CLI not found ' + dim('— Opus/Sonnet/Haiku unavailable'))
+  console.log(yellow('  ⚠') + ' Claude Code CLI not found ' + dim('— Opus/Fable/Sonnet unavailable'))
   console.log('    Install: ' + bold('https://claude.ai/download'))
 }
 if (codexVersion) {
-  console.log(green('  ✓') + ` Codex CLI ${normalizeCodexVersion(codexVersion)} ` + dim('(Codex High)'))
+  console.log(green('  ✓') + ` Codex CLI ${normalizeCodexVersion(codexVersion)} ` + dim('(GPT Frontier / Balanced)'))
 } else {
-  console.log(yellow('  ⚠') + ' Codex CLI not found ' + dim('— Codex High unavailable'))
+  console.log(yellow('  ⚠') + ' Codex CLI not found ' + dim('— GPT Frontier/Balanced unavailable'))
 }
 if (!claudeVersion && !codexVersion) {
   console.log('')
@@ -184,13 +184,25 @@ if (whisperCliPath && hasValidModel) {
   console.log('    Free local voice: ' + bold('brew install whisper-cpp') + dim('  (no Homebrew? https://brew.sh)'))
 }
 
-// Step 6: phone reachability — the glasses' phone app must reach this server.
+// Step 6: image capability — ffmpeg validates, strips metadata, normalizes,
+// and builds the exact 288x144 G2 variant. It is optional so text/voice remain
+// useful on a minimal install, but the launcher should make the gap visible.
+const ffmpegVersion = getCliVersion('ffmpeg', '-version')
+if (ffmpegVersion) {
+  const firstLine = ffmpegVersion.split('\n')[0].trim()
+  console.log(green('  ✓') + ` ${firstLine} ` + dim('— phone + lens images ready'))
+} else {
+  console.log(yellow('  ⚠') + ' ffmpeg not installed ' + dim('— phone and answer images disabled'))
+  console.log('    Enable photos: ' + bold('brew install ffmpeg') + dim('  (text + voice still work)'))
+}
+
+// Step 7: phone reachability — the glasses' phone app must reach this server.
 if (!process.env.BIND_HOST) {
   process.env.BIND_HOST = '0.0.0.0'
   console.log(yellow('  ⚠') + ' BIND_HOST not set — defaulting to 0.0.0.0 so your phone can reach the server')
 }
 
-// Step 7: start the bundled server
+// Step 8: start the bundled server
 try {
   const ld = process.env.COS_LAUNCH_DIR
   if (ld && (existsSync(join(ld, '.cos', 'manifest.json')) || existsSync(join(ld, 'AGENTS.md')) || existsSync(join(ld, 'CLAUDE.md')))) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.3.1",
+  "version": "6.5.0",
   "description": "COS Glasses — self-hosted AI heads-up-display server for Even G2 smart glasses, powered by your local Claude Code or Codex CLI",
   "type": "module",
   "bin": {
@@ -9,14 +9,25 @@
   "scripts": {
     "start": "node bin/cli.cjs",
     "start:server": "node --import tsx/esm server/index.ts",
+    "test": "vitest run",
     "typecheck": "tsc --noEmit"
   },
-  "keywords": ["even-g2", "smart-glasses", "claude-code", "codex", "ai", "cos", "heads-up-display", "whisper"],
+  "keywords": [
+    "even-g2",
+    "smart-glasses",
+    "claude-code",
+    "codex",
+    "ai",
+    "cos",
+    "heads-up-display",
+    "whisper"
+  ],
   "files": [
     "bin/cli.cjs",
-    "server/**/*.ts",
-    "server/**/*.js",
-    "shared/**/*.ts",
+    "server",
+    "shared",
+    "!server/**/*.test.ts",
+    "!shared/**/*.test.ts",
     ".env.example",
     ".cos-profile.example.json",
     "README.md",
@@ -48,6 +59,7 @@
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.6",
     "@types/node": "^22.10.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.7"
   }
 }

package/server/bin/cos-output-image-publisher.mjs

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+
+// Capability-scoped image publisher used by a single COS Glasses model run.
+// It copies one already-local supported image artifact into the run's private inbox and
+// appends only an opaque content id + generic provenance to the manifest.
+// Source paths, URLs, and bytes never enter the manifest or stdout.
+
+import { createHash, timingSafeEqual } from 'node:crypto'
+import {
+  chmodSync,
+  closeSync,
+  constants,
+  existsSync,
+  fstatSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+  writeSync,
+} from 'node:fs'
+import { basename, isAbsolute, join, sep } from 'node:path'
+
+const RUN_DIR_PREFIX = 'cos-glasses-output-images-'
+const ABSOLUTE_MAX_IMAGES = 5
+const MAX_IMAGE_BYTES = 16 * 1024 * 1024
+const MANIFEST_MAX_BYTES = 64 * 1024
+const PROVENANCE = new Set(['generated', 'research', 'email'])
+const OUTPUT_ID_RE = /^o_[a-f0-9]{32}$/
+const WAIT_ARRAY = new Int32Array(new SharedArrayBuffer(4))
+
+function configuredMaxImages() {
+  const parsed = Number(process.env.COS_OUTPUT_IMAGE_MAX)
+  if (!Number.isInteger(parsed)) return ABSOLUTE_MAX_IMAGES
+  return Math.max(0, Math.min(ABSOLUTE_MAX_IMAGES, parsed))
+}
+
+function fail(message) {
+  throw new Error(message)
+}
+
+function sleep(ms) {
+  Atomics.wait(WAIT_ARRAY, 0, 0, ms)
+}
+
+function isSupportedMagic(bytes) {
+  const jpeg = bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff
+  const png = bytes.length >= 8 &&
+    bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47 &&
+    bytes[4] === 0x0d && bytes[5] === 0x0a && bytes[6] === 0x1a && bytes[7] === 0x0a
+  const webp = bytes.length >= 12 &&
+    bytes.toString('ascii', 0, 4) === 'RIFF' && bytes.toString('ascii', 8, 12) === 'WEBP'
+  let isoImage = false
+  if (bytes.length >= 12 && bytes.toString('ascii', 4, 8) === 'ftyp') {
+    const declaredBoxSize = bytes.readUInt32BE(0)
+    const boxEnd = Math.min(bytes.length, declaredBoxSize >= 16 ? declaredBoxSize : 16, 256)
+    const brands = [bytes.toString('ascii', 8, 12)]
+    for (let offset = 16; offset + 4 <= boxEnd; offset += 4) brands.push(bytes.toString('ascii', offset, offset + 4))
+    isoImage = brands.some((brand) => [
+      'avif', 'avis',
+      'heic', 'heix', 'hevc', 'hevx', 'heim', 'heis',
+      'mif1', 'msf1',
+    ].includes(brand))
+  }
+  return jpeg || png || webp || isoImage
+}
+
+function outputId(bytes) {
+  // Provenance is presentation metadata, not identity. The first publication
+  // of identical bytes wins regardless of how that image was later reused.
+  const digest = createHash('sha256').update(bytes).digest('hex')
+  return `o_${digest.slice(0, 32)}`
+}
+
+function validateItemsDir(runDir, expected) {
+  const itemsDir = join(runDir, 'items')
+  let fd = -1
+  try {
+    const before = lstatSync(itemsDir)
+    if (!before.isDirectory() || before.isSymbolicLink() || (before.mode & 0o777) !== 0o700) {
+      fail('Publisher items directory is unavailable.')
+    }
+    if (typeof process.getuid === 'function' && before.uid !== process.getuid()) {
+      fail('Publisher items directory is unavailable.')
+    }
+    const real = realpathSync(itemsDir)
+    if (real !== itemsDir || !real.startsWith(`${runDir}${sep}`)) {
+      fail('Publisher items directory is unavailable.')
+    }
+    fd = openSync(itemsDir, constants.O_RDONLY | (constants.O_DIRECTORY ?? 0) | (constants.O_NOFOLLOW ?? 0))
+    const opened = fstatSync(fd)
+    const after = lstatSync(itemsDir)
+    if (!opened.isDirectory() || opened.dev !== before.dev || opened.ino !== before.ino ||
+        after.isSymbolicLink() || after.dev !== opened.dev || after.ino !== opened.ino ||
+        (opened.mode & 0o777) !== 0o700 ||
+        (typeof process.getuid === 'function' && opened.uid !== process.getuid())) {
+      fail('Publisher items directory is unavailable.')
+    }
+    if (expected && (opened.dev !== expected.dev || opened.ino !== expected.ino)) {
+      fail('Publisher items directory is unavailable.')
+    }
+    return { path: itemsDir, dev: opened.dev, ino: opened.ino }
+  } catch (err) {
+    if (err instanceof Error && err.message === 'Publisher items directory is unavailable.') throw err
+    fail('Publisher items directory is unavailable.')
+  } finally {
+    if (fd >= 0) {
+      try { closeSync(fd) } catch { /* best effort */ }
+    }
+  }
+}
+
+function readManifestIds(path) {
+  if (!existsSync(path)) return new Set()
+  let contents = ''
+  let fd = -1
+  try {
+    const stat = lstatSync(path)
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MANIFEST_MAX_BYTES) {
+      fail('Publisher manifest is unavailable.')
+    }
+    fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0))
+    contents = readFileSync(fd, 'utf8')
+  } catch {
+    fail('Publisher manifest is unavailable.')
+  } finally {
+    if (fd >= 0) {
+      try { closeSync(fd) } catch { /* best effort */ }
+    }
+  }
+  const ids = new Set()
+  for (const line of contents.split('\n')) {
+    if (!line || line.length > 512) continue
+    try {
+      const item = JSON.parse(line)
+      if (item?.v === 1 && item?.type === 'publish' && OUTPUT_ID_RE.test(item.id) && PROVENANCE.has(item.provenance)) {
+        ids.add(item.id)
+      }
+    } catch {
+      // A process can die between append bytes. A malformed tail never makes
+      // a valid earlier publication disappear.
+    }
+  }
+  return ids
+}
+
+function acquireLock(runDir) {
+  const lockDir = join(runDir, '.publish.lock')
+  const deadline = Date.now() + 5_000
+  while (Date.now() < deadline) {
+    try {
+      mkdirSync(lockDir, { mode: 0o700 })
+      return lockDir
+    } catch (err) {
+      if (err?.code !== 'EEXIST') fail('Publisher lock is unavailable.')
+      try {
+        if (Date.now() - statSync(lockDir).mtimeMs > 30_000) {
+          rmSync(lockDir, { recursive: true, force: true })
+          continue
+        }
+      } catch {
+        // The owner may have released it between the failed mkdir and stat.
+      }
+      sleep(25)
+    }
+  }
+  fail('Publisher is busy; try once more.')
+}
+
+function readCapability(runDir, supplied) {
+  if (!supplied || Buffer.byteLength(supplied) > 256) fail('Publisher capability is unavailable.')
+  let expected = ''
+  try {
+    expected = readFileSync(join(runDir, '.capability'), 'utf8').trim()
+  } catch {
+    fail('Publisher capability is unavailable.')
+  }
+  const a = Buffer.from(supplied)
+  const b = Buffer.from(expected)
+  if (a.length !== b.length || !timingSafeEqual(a, b)) fail('Publisher capability is unavailable.')
+}
+
+function validateRunDir(rawDir) {
+  if (!rawDir || !isAbsolute(rawDir)) fail('Publisher directory is unavailable.')
+  let runDir
+  let tmpRoot
+  try {
+    runDir = realpathSync(rawDir)
+    tmpRoot = realpathSync('/tmp')
+    const stat = lstatSync(runDir)
+    if (!stat.isDirectory() || stat.isSymbolicLink()) fail('Publisher directory is unavailable.')
+    if ((stat.mode & 0o777) !== 0o700) fail('Publisher directory is not private.')
+    if (typeof process.getuid === 'function' && stat.uid !== process.getuid()) fail('Publisher directory is unavailable.')
+  } catch {
+    fail('Publisher directory is unavailable.')
+  }
+  if (!runDir.startsWith(`${tmpRoot}${sep}`) || !basename(runDir).startsWith(RUN_DIR_PREFIX)) {
+    fail('Publisher directory is unavailable.')
+  }
+  return runDir
+}
+
+function readLocalImage(source) {
+  if (!source || !isAbsolute(source) || /^[a-z][a-z0-9+.-]*:/i.test(source) || source.startsWith('//')) {
+    fail('Publisher accepts an absolute local file, never a URL.')
+  }
+  let fd = -1
+  try {
+    const before = lstatSync(source)
+    if (!before.isFile() || before.isSymbolicLink() || before.size <= 0 || before.size > MAX_IMAGE_BYTES) {
+      fail('Source must be a supported local image no larger than 16 MiB.')
+    }
+    fd = openSync(source, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0))
+    const opened = fstatSync(fd)
+    if (!opened.isFile() || opened.size !== before.size || opened.ino !== before.ino || opened.dev !== before.dev) {
+      fail('Source image changed while publishing.')
+    }
+    const bytes = readFileSync(fd)
+    const after = fstatSync(fd)
+    if (after.size !== opened.size || after.ino !== opened.ino || after.dev !== opened.dev) {
+      fail('Source image changed while publishing.')
+    }
+    if (!isSupportedMagic(bytes)) fail('Only JPEG, PNG, WebP, HEIC, HEIF, or AVIF images can be published.')
+    return bytes
+  } catch (err) {
+    if (typeof err?.message === 'string' && err.message.startsWith('Source ')) throw err
+    fail('Source image is unavailable.')
+  } finally {
+    if (fd >= 0) {
+      try { closeSync(fd) } catch { /* best effort */ }
+    }
+  }
+}
+
+function main() {
+  const [provenance, source, ...extra] = process.argv.slice(2)
+  if (!PROVENANCE.has(provenance) || !source || extra.length > 0) {
+    fail('Usage: publisher <generated|research|email> <absolute-local-image>')
+  }
+
+  const runDir = validateRunDir(process.env.COS_OUTPUT_IMAGE_DIR)
+  readCapability(runDir, process.env.COS_OUTPUT_IMAGE_TOKEN)
+  const bytes = readLocalImage(source)
+  const id = outputId(bytes)
+  const maxImages = configuredMaxImages()
+  const manifestPath = join(runDir, 'manifest.jsonl')
+  const items = validateItemsDir(runDir)
+  const itemsDir = items.path
+  const lockDir = acquireLock(runDir)
+
+  try {
+    const published = readManifestIds(manifestPath)
+    if (!published.has(id) && published.size >= maxImages) {
+      fail(maxImages === 0 ? 'This response cannot accept output images.' : `This response already has ${maxImages} published images.`)
+    }
+
+    const target = join(itemsDir, `${id}.img`)
+    if (!existsSync(target)) {
+      const tmp = join(itemsDir, `.${id}-${process.pid}.tmp`)
+      let fd = -1
+      try {
+        validateItemsDir(runDir, items)
+        fd = openSync(
+          tmp,
+          constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0),
+          0o600,
+        )
+        const opened = fstatSync(fd)
+        if (!opened.isFile() || opened.nlink !== 1 || (opened.mode & 0o777) !== 0o600) {
+          fail('Publisher items directory is unavailable.')
+        }
+        // If the path was swapped between validation and open, detect that
+        // before writing any source bytes to the selected directory.
+        validateItemsDir(runDir, items)
+        writeSync(fd, bytes)
+        fsyncSync(fd)
+        closeSync(fd)
+        fd = -1
+        validateItemsDir(runDir, items)
+        renameSync(tmp, target)
+        validateItemsDir(runDir, items)
+      } finally {
+        if (fd >= 0) {
+          try { closeSync(fd) } catch { /* best effort */ }
+        }
+        try { rmSync(tmp, { force: true }) } catch { /* best effort */ }
+      }
+    }
+
+    if (!published.has(id)) {
+      const line = `${JSON.stringify({ v: 1, type: 'publish', id, provenance })}\n`
+      const fd = openSync(
+        manifestPath,
+        constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | (constants.O_NOFOLLOW ?? 0),
+        0o600,
+      )
+      try {
+        const stat = fstatSync(fd)
+        if (!stat.isFile()) fail('Publisher manifest is unavailable.')
+        writeSync(fd, line)
+        fsyncSync(fd)
+      } finally {
+        closeSync(fd)
+      }
+      chmodSync(manifestPath, 0o600)
+    }
+    process.stdout.write(`Published ${provenance} image.\n`)
+  } finally {
+    rmSync(lockDir, { recursive: true, force: true })
+  }
+}
+
+try {
+  main()
+} catch (err) {
+  const message = err instanceof Error ? err.message : 'Image publication failed.'
+  process.stderr.write(`${message}\n`)
+  process.exitCode = 1
+}

package/server/bootstrap.ts

@@ -0,0 +1,16 @@
+// Must remain the first import in server/index.ts. Claim the same machine-wide
+// slot used by the installed LaunchAgent before mutable routes or stores load.
+import './env.js'
+import { acquireServerInstanceLock, ServerInstanceActiveError } from './lib/server-instance-lock.js'
+
+try {
+  const instanceLock = acquireServerInstanceLock()
+  process.once('exit', instanceLock.release)
+} catch (error) {
+  if (error instanceof ServerInstanceActiveError) {
+    console.error(`[COS API] Startup refused: ${error.message}`)
+    process.exit(75)
+  }
+  console.error('[COS API] Startup refused: single-instance lock failed.', error)
+  process.exit(74)
+}