@gotcos/glasses-server 6.12.7 → 6.13.0

package/CHANGELOG.md

@@ -500,3 +500,10 @@ it directly, with no second repository to clone.
   can reach the server over your mesh/LAN. The IP allowlist blocks public traffic.
 - **Persistent config** at `~/.cos-glasses/.env`.
 - Requires Node.js 20.11+.
+# 6.13.0
+
+- Added a non-interactive managed-server entrypoint for the COS Control macOS app.
+- Added authenticated maintenance status and guarded local Whisper restart contracts.
+- Added `--prepare-only` to the existing guided launcher so first-run dependencies can be prepared without leaving a second server process running.
+- Added a provider-neutral managed work-folder setting while preserving the existing interactive launch-directory behavior.
+- Kept the existing `npx @gotcos/glasses-server` foreground workflow fully compatible.

package/README.md

@@ -11,6 +11,16 @@ API key is pasted into the phone for chat.
 npx --yes @gotcos/glasses-server@latest
 ```
 
+For the optional COS Control macOS menu bar app, prepare dependencies without
+leaving a foreground server running:
+
+```bash
+npx --yes @gotcos/glasses-server@latest --prepare-only
+```
+
+COS Control then installs the same npm package as a launchd-managed runtime.
+The original foreground command remains supported and unchanged.
+
 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

package/bin/cli.cjs

@@ -41,6 +41,7 @@ if (process.argv.includes('--help') || process.argv.includes('-h')) {
   console.log('')
   console.log('  Usage:')
   console.log('    npx --yes @gotcos/glasses-server@latest')
+  console.log('    npx --yes @gotcos/glasses-server@latest --prepare-only')
   console.log('')
   console.log('  Requirements:')
   console.log('    - Node.js 20.11+')
@@ -174,6 +175,17 @@ try {
   process.exit(1)
 }
 
+// Controller probes are deliberately read-only. They verify Node, agent auth,
+// and the packaged runtime without creating config, downloading models,
+// changing permissions, or starting a listener.
+if (process.argv.includes('--prepare-only')) {
+  console.log('')
+  console.log(green('  ✓ Non-mutating readiness check complete'))
+  console.log('    COS Control can perform guided installation without hidden setup side effects.')
+  console.log('')
+  process.exit(0)
+}
+
 // Step 4: persistent config at ~/.cos-glasses/ (survives npx cache churn)
 function securePrivateDirectory(dir) {
   mkdirSync(dir, { recursive: true, mode: 0o700 })

package/bin/managed-server.cjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+// Non-interactive entrypoint for trusted local service managers such as
+// COS Control. The existing glasses-server CLI remains the interactive setup
+// path; this launcher assumes ~/.cos-glasses/.env is already configured.
+
+const { resolve } = require('node:path')
+const packageJson = require('../package.json')
+
+const PKG_ROOT = resolve(__dirname, '..')
+
+try {
+  require('tsx/cjs')
+} catch {
+  console.error('[cos-managed] Package dependencies are incomplete; reinstall @gotcos/glasses-server.')
+  process.exit(1)
+}
+
+const workDir = process.env.COS_WORKDIR?.trim()
+process.env.COS_MANAGED = '1'
+process.env.COS_ENTRYPOINT = 'managed-server'
+process.env.COS_SERVER_VERSION = packageJson.version
+if (workDir) process.env.COS_LAUNCH_DIR = workDir
+
+// The launchd-owned PID is the listener owner. Keeping the listener in this
+// process removes the supervisor/child ambiguity that made lifecycle proof and
+// crash receipts unreliable.
+require(resolve(PKG_ROOT, 'server/index.ts'))

package/managed-runtime-contract.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": 1,
+  "contractVersion": 2,
+  "entrypoint": "bin/managed-server.cjs",
+  "listenerOwnership": "entrypoint-process",
+  "requiredEnvironment": [
+    "COS_API_TOKEN",
+    "COS_SERVER_GENERATION_ID",
+    "COS_MAINTENANCE_GATE_PATH"
+  ],
+  "optionalEnvironment": [
+    "COS_WORKDIR",
+    "PORT",
+    "HTTPS_PORT",
+    "BIND_HOST",
+    "COS_DURABLE_QUERY_JOBS"
+  ],
+  "maintenance": {
+    "scope": "cross_boot",
+    "adoptionRequired": true,
+    "networkRestartEndpoint": false
+  }
+}

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.12.7",
+  "version": "6.13.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": {
-    "glasses-server": "bin/cli.cjs"
+    "glasses-server": "bin/cli.cjs",
+    "glasses-server-managed": "bin/managed-server.cjs"
   },
   "scripts": {
     "start": "node bin/cli.cjs",
@@ -24,6 +25,8 @@
   ],
   "files": [
     "bin/cli.cjs",
+    "bin/managed-server.cjs",
+    "managed-runtime-contract.json",
     "server",
     "shared",
     "!server/**/*.test.ts",

package/server/index.ts

@@ -28,6 +28,7 @@ import { sessionsRouter } from './routes/sessions.js'
 import { mediaRouter, mediaBodyParser } from './routes/media.js'
 import { promptDraftsRouter } from './routes/prompt-drafts.js'
 import { cliDebugRouter } from './routes/cli-debug.js'
+import { maintenanceRouter } from './routes/maintenance.js'
 import { prewarmContext } from './lib/context-builder.js'
 import { preWarmCLI } from './lib/claude-bridge.js'
 import { getCodexRunConfig } from './lib/codex-run-ledger.js'
@@ -58,6 +59,13 @@ import {
   isTailscaleIpv4,
 } from './lib/network-policy.js'
 import { timingSafeTokenEqual } from './lib/token-auth.js'
+import { isManagedRuntime } from './lib/managed-runtime.js'
+import {
+  acquireMaintenanceWork,
+  MaintenanceLifecycleError,
+  maintenanceAdmissionsOpen,
+  maintenanceErrorPayload,
+} from './lib/maintenance-lifecycle.js'
 
 const app = express()
 const PORT = parseInt(process.env.PORT ?? '3141', 10)
@@ -74,6 +82,9 @@ const BIND_HOST = process.env.BIND_HOST ?? '0.0.0.0'
 
 // API token — auto-generate if not set so every session is authenticated.
 const API_TOKEN_AUTO = !process.env.COS_API_TOKEN
+if (isManagedRuntime() && API_TOKEN_AUTO) {
+  throw new Error('Managed COS startup requires a pre-provisioned COS_API_TOKEN.')
+}
 const API_TOKEN = process.env.COS_API_TOKEN ?? `_${randomBytes(32).toString('base64url')}`
 process.env.COS_API_TOKEN = API_TOKEN  // make available to routes that check it
 // Persist an auto-generated token to ~/.cos-glasses/.env so it SURVIVES restarts.
@@ -135,6 +146,42 @@ app.use('/api', (req, res, next) => {
   next()
 })
 
+// Fail-closed catch-all for mutation routes that do not own a more specific
+// lifecycle lease below. This closes the admission/drain race for secondary
+// state-changing APIs (media, sessions, settings, diagnostics) without
+// double-owning provider and recording continuations whose routes retain work
+// through their true terminal boundary.
+app.use('/api', (req, res, next) => {
+  if (req.method === 'GET' || req.method === 'HEAD' || req.method === 'OPTIONS') return next()
+  const lifecycleOwned = (req.path === '/query-jobs' && req.method === 'POST')
+    || req.path === '/query'
+    || req.path === '/transcribe'
+    || req.path.startsWith('/transcribe-stream')
+    || req.path === '/meeting/save'
+    || req.path.startsWith('/prompt-drafts')
+    || req.path.startsWith('/maintenance/drain')
+  if (lifecycleOwned) return next()
+
+  try {
+    const lease = acquireMaintenanceWork('api_mutation')
+    let released = false
+    const release = () => {
+      if (released) return
+      released = true
+      lease.release()
+    }
+    res.once('finish', release)
+    res.once('close', release)
+    next()
+  } catch (error) {
+    if (error instanceof MaintenanceLifecycleError) {
+      if (error.retryAfterSeconds != null) res.setHeader('Retry-After', String(error.retryAfterSeconds))
+      return res.status(error.status).json(maintenanceErrorPayload(error))
+    }
+    return res.status(500).json({ error: 'maintenance_internal_error', retryable: false })
+  }
+})
+
 // Authenticate before parsing large upload bodies. The 16 MB allowance stays
 // scoped to /api/media; every other route retains the 10 MB ceiling.
 app.use('/api/media', mediaBodyParser)
@@ -167,6 +214,7 @@ app.use('/api', sessionsRouter)
 app.use('/api', mediaRouter)
 app.use('/api', promptDraftsRouter)
 app.use('/api', cliDebugRouter)
+app.use('/api', maintenanceRouter)
 
 // OpenAI-compatible endpoint for the G2 Agent (ER "Add Agent")
 // Mounted at root — routes are /v1/chat/completions and /v1/models
@@ -242,6 +290,7 @@ listeners.push({ server: httpServer, port: PORT, host: BIND_HOST, label: 'HTTP'
 
 listenRequiredServers(listeners).then(() => {
   const serverInstanceId = initializeServerInstanceId()
+  const startupAdmissionsOpen = maintenanceAdmissionsOpen()
   if (listeners.some(listener => listener.label === 'HTTPS')) {
     console.log(`[COS API] HTTPS server running on https://${BIND_HOST}:${HTTPS_PORT}`)
   }
@@ -249,17 +298,21 @@ listenRequiredServers(listeners).then(() => {
   console.log(`[COS API] Server instance: ${serverInstanceId}`)
   console.log(`[COS API] Mode: ${COS_MODE ? 'COS pipeline' : 'standalone'}`)
 
-  void initQueryJobRuntime().then(health => {
-    if (process.env.COS_DURABLE_QUERY_JOBS === '1') {
-      console.log(`[COS API] Durable query jobs: ${health.store.state} · ${health.store.retainedIdentities} retained`)
-    } else {
-      console.log('[COS API] Durable query jobs: disabled (set COS_DURABLE_QUERY_JOBS=1 to enable)')
-    }
-  }).catch(error => {
-    // The store remains degraded and rejects admission. Legacy /api/query is
-    // still mounted, so disabling the feature flag is an immediate rollback.
-    console.error('[COS API] Durable query-job store unavailable:', error)
-  })
+  if (startupAdmissionsOpen) {
+    void initQueryJobRuntime().then(health => {
+      if (process.env.COS_DURABLE_QUERY_JOBS === '1') {
+        console.log(`[COS API] Durable query jobs: ${health.store.state} · ${health.store.retainedIdentities} retained`)
+      } else {
+        console.log('[COS API] Durable query jobs: disabled (set COS_DURABLE_QUERY_JOBS=1 to enable)')
+      }
+    }).catch(error => {
+      // The store remains degraded and rejects admission. Legacy /api/query is
+      // still mounted, so disabling the feature flag is an immediate rollback.
+      console.error('[COS API] Durable query-job store unavailable:', error)
+    })
+  } else {
+    console.log('[COS API] Startup maintenance gate is closed — durable recovery waits for controller adoption')
+  }
 
   // Print ADDRESSES THE PHONE CAN ACTUALLY REACH. The bind address (0.0.0.0) is
   // not paste-able — enumerate real interfaces and label the Tailscale one.
@@ -281,8 +334,10 @@ listenRequiredServers(listeners).then(() => {
     }
   } catch { /* interface enumeration is best-effort */ }
 
-  // Print the full API token when auto-generated — the user pastes it into the app.
-  if (API_TOKEN_AUTO) {
+  // Interactive standalone startup may print a newly generated pairing token.
+  // Managed startup never generates or logs credentials; COS Control copies the
+  // pre-provisioned token through the local pasteboard flow instead.
+  if (API_TOKEN_AUTO && !isManagedRuntime()) {
     console.log('')
     console.log(`[COS API] API Token: ${API_TOKEN}`)
     console.log('[COS API]   ^ paste this into the COS Glasses app' + (API_TOKEN_PERSISTED ? ' — saved to ~/.cos-glasses/.env so it stays the same across restarts' : ' (set COS_API_TOKEN in .env for a fixed token)'))
@@ -306,32 +361,34 @@ listenRequiredServers(listeners).then(() => {
   console.log(`[COS API] Codex workdir: ${codexConfig.cwd}`)
   // Refresh immediately and then periodically. The catalog module retains the
   // last-known-good snapshot if Codex is temporarily unavailable.
-  startCodexModelCatalogRefresh()
+  if (startupAdmissionsOpen) {
+    startCodexModelCatalogRefresh()
 
-  if (COS_MODE) {
-    initSessionCache()
-    // Pre-warm context cache so first query doesn't wait for the pipeline
-    prewarmContext()
-  }
-  // Start local whisper-server (model stays in RAM for ~50ms transcription)
-  startWhisperServer().catch(err => console.error('[startup] Whisper server error:', err))
-  // Initialize speaker embeddings (voiceprint-based diarization) — fails soft if model absent
-  const embeddingOk = initSpeakerEmbeddings()
-  console.log(`[startup] Speaker embeddings: ${embeddingOk ? 'active' : 'disabled (model not found)'}`)
-  // Initialize Silero VAD (silence trimming before Whisper) — fails soft if model absent
-  const vadOk = initSileroVAD()
-  console.log(`[startup] Silero VAD: ${vadOk ? 'active' : 'disabled (model not found)'}`)
+    if (COS_MODE) {
+      initSessionCache()
+      // Pre-warm context cache so first query doesn't wait for the pipeline
+      prewarmContext()
+    }
+    // Start local whisper-server (model stays in RAM for ~50ms transcription)
+    startWhisperServer().catch(err => console.error('[startup] Whisper server error:', err))
+    // Initialize speaker embeddings (voiceprint-based diarization) — fails soft if model absent
+    const embeddingOk = initSpeakerEmbeddings()
+    console.log(`[startup] Speaker embeddings: ${embeddingOk ? 'active' : 'disabled (model not found)'}`)
+    // Initialize Silero VAD (silence trimming before Whisper) — fails soft if model absent
+    const vadOk = initSileroVAD()
+    console.log(`[startup] Silero VAD: ${vadOk ? 'active' : 'disabled (model not found)'}`)
 
-  // Pre-warm Claude only when installed so Codex-only startup stays quiet.
-  if (claudeAvailable) {
-    preWarmCLI().catch(err => console.error('[startup] CLI pre-warm error:', err))
-  }
+    // Pre-warm Claude only when installed so Codex-only startup stays quiet.
+    if (claudeAvailable) {
+      preWarmCLI().catch(err => console.error('[startup] CLI pre-warm error:', err))
+    }
 
-  // Auto-snapshot active sessions every 5 min (survives restarts)
-  startAutoSnapshot(5 * 60_000)
+    // Auto-snapshot active sessions every 5 min (survives restarts)
+    startAutoSnapshot(5 * 60_000)
 
-  // Durable media GC (staged/reserved expiry + generated-image content TTL).
-  getMediaStore().startGC()
+    // Durable media GC (staged/reserved expiry + generated-image content TTL).
+    getMediaStore().startGC()
+  }
 }).catch((error: NodeJS.ErrnoException) => {
   console.error(`[COS API] Fatal listener startup: ${error.message}`)
   process.exit(error.code === 'EADDRINUSE' ? 75 : 74)

package/server/lib/launch-dir.ts

@@ -14,16 +14,22 @@ import { join, resolve } from 'node:path'
 
 let cached: string | null | undefined
 
-/** The user's launch directory IF it contains a COS brain; otherwise null. */
-export function cosBrainDir(): string | null {
-  if (cached !== undefined) return cached
-  const raw = process.env.COS_LAUNCH_DIR?.trim()
-  if (!raw) { cached = null; return cached }
-  const dir = resolve(raw)
+export function resolveCosBrainDir(raw: string | undefined): string | null {
+  const candidate = raw?.trim()
+  if (!candidate) return null
+  const dir = resolve(candidate)
   const hasBrain =
     existsSync(join(dir, '.cos', 'manifest.json')) ||
     existsSync(join(dir, 'AGENTS.md')) ||
     existsSync(join(dir, 'CLAUDE.md'))
-  cached = hasBrain ? dir : null
+  return hasBrain ? dir : null
+}
+
+/** The user's launch directory IF it contains a COS brain; otherwise null. */
+export function cosBrainDir(): string | null {
+  if (cached !== undefined) return cached
+  // COS_WORKDIR is the provider-neutral managed setting. COS_LAUNCH_DIR stays
+  // as the interactive npx compatibility path.
+  cached = resolveCosBrainDir(process.env.COS_WORKDIR ?? process.env.COS_LAUNCH_DIR)
   return cached
 }