@gotcos/glasses-server 6.81.0 → 6.82.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 6.82.0 - Routines: any COS skill on a schedule, each with its own cap, off switch and breaker
+
+Miles, 2026-10-20 (plan Decision Q4): "Any COS skill on a schedule. Pick a skill, a time and days; each routine has its own cap and off switch." Until now the server had one routine, the morning brief.
+
+- **Client matrix.** Server only in this release. Companion 6.10.650 lists, adds, edits, pauses and runs routines from the phone; older companions and COS Control keep using `/api/morning-brief`, which is unchanged. Nothing runs that a user did not create: a fresh server has the morning brief and no skill routines.
+- **The morning brief is routine #1, unchanged.** Its config file, scheduler, prompt, scheduled submission, `/api/morning-brief` envelope, a rejected PUT and Run now while it runs are pinned by `morning-brief-golden.test.ts`, recorded on the unmodified 6.81.0 base (6b2e70b) before any routine code existed and passing byte for byte after. The only change it sees: its run is counted in the token audit as `routine:morning-brief` instead of `full_query`.
+- **`/api/routines`.** `GET` lists the brief first, then skill routines, each with schedule, next run, gate (why it will not run), breaker state, today's runs against its cap, and its last run. `GET /routines/skills` lists this workspace's skills (`.agents/skills`, `.claude/skills`; labels only, never paths). `POST` creates; `PATCH` (or `PUT`) edits, and `resetBreaker: true` closes an open breaker; `POST /:id/pause` and `/:id/resume`; `DELETE` (the brief can only be turned off: 409 `cannot_delete_brief`); `POST /:id/run` is Run now (202; 409 running, off or skill missing; 423 breaker open, with `openUntil`; 429 capped); `GET /:id/runs` and `/routines/runs` are history. A brief edit through `/api/routines/morning-brief` takes only the brief's own fields and refuses any other (400 `not_a_brief_field`).
+- **A skill routine.** A workspace skill, an optional extra instruction, a time and days in a zone (default the Mac's, weekdays at 08:00), runs a day (default 2, at most 10), a model (default `sonnet`, never left to the user default, never a key lane), and its breaker (default 3 failures, 6 hours). Stored in `data/routines/routines.json`, runs in `data/routines/runs.json` (0600, atomic; a damaged file keeps its good routines and drops the rest). It runs as an ordinary durable job with `origin: { kind: 'routine', id }`, so it survives the phone sleeping and lands in the inbox with a message number. Its prompt says nobody is watching: read and summarise freely, write only the skill's own files, never send, publish, deploy, push, delete or spend; if a source is missing, say so in one line.
+- **How it stops.** Its own switch, and `COS_ROUTINES=0` turns every skill routine off (the brief keeps its own switch). Its daily cap counts scheduled and Run now runs together; a failed submit never ran and is not counted. Every skill routine together is capped at 40 runs a day. The breaker opens after N consecutive failed runs (a failed or interrupted job, or a failed submit) and nothing fires until the cooldown ends; then one trial run is allowed, a success closes it and a failure opens it again. A canceled run counts neither way, and each finished run is counted once however many ticks read it. One scheduled slot per selected day, three submit attempts two minutes apart, crash-resumed by a fixed client id. Inert while Background jobs are off or maintenance is closed, as the brief.
+- **Token audit by caller.** A routine's run is logged as `routine:<id>` (Claude, Codex, Cursor and direct bridges; the runtime passes `auditCaller` only for routine origins, so every other caller is byte for byte what it was).
+- **Checks.** Canary C7 (`server/scripts/routines-canary.ts`, not packaged): on a scratch data dir, a scratch HOME and workspace, an ephemeral port, and a stub `claude` on PATH, two routines fired at their slot on the production 30 s tick; the one whose skill fails exited 1, the breaker counted it, a second failure opened it, Run now answered 423 and the next tick skipped it, the other routine stayed ready, and the token audit row read `routine:<id>` on `sonnet`. Mutation gate `server/scripts/routines-mutation-gate.mjs` (not packaged): green baseline (55 tests in 6 files), 42 of 42 mutants killed, each by a named test. Full suite 8,503 passed, 0 failed, 3 skipped (562 files); `tsc --noEmit` clean. The key-lanes census classifies the three new model sites as Reject.
+
 ## 6.81.0 - The Mac saves a stopped meeting on its own once it holds every chunk
 
 Miles, 2026-10-20: "if the application isn't in the foreground, it can fail to save the meetings". Both G2 meetings that day saved only once the phone came back on screen: the phone's Stop needs IndexedDB, and iOS suspends IndexedDB while the companion is hidden (11:19 qbbgyq: Stop 12:43, `stop_blocked`, "Load failed", saved 12:47 by a new WebView; 14:07 mip9qb: Stop 15:13:50, saved 15:14:37 only after the phone was visible). The full map is `docs/meeting-autonomous-save.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.81.0",
+  "version": "6.82.0",
   "description": "COS Glasses: self-hosted AI heads-up-display server for Even G2 smart glasses, powered by Claude Code, Codex, Cursor Agent CLI, or local Ollama",
   "type": "module",
   "bin": {
@@ -55,6 +55,8 @@
     "!server/scripts/fact-check-mutation-gate.mjs",
     "!server/scripts/stale-session-mutation-gate.mjs",
     "!server/scripts/autonomous-save-mutation-gate.mjs",
+    "!server/scripts/routines-mutation-gate.mjs",
+    "!server/scripts/routines-canary.ts",
     "!server/scripts/stt-mutation-gate.mjs",
     "!server/scripts/dictation-stt-mutation-gate.mjs",
     "!server/scripts/pairing-mutation-gate.mjs",

package/server/index.ts

@@ -170,6 +170,8 @@ import { listBoard } from './lib/task-store.js'
 import { createDefaultWorkReviewRuntime } from './lib/work-review-backend.js'
 import { createMorningBriefRouter } from './routes/morning-brief.js'
 import { getMorningBriefScheduler, startMorningBriefScheduler, stopMorningBriefScheduler } from './lib/morning-brief-runtime.js'
+import { createRoutinesRouter } from './routes/routines.js'
+import { getRoutineRegistry, routineSkillCatalog, startRoutineScheduler, stopRoutineScheduler } from './lib/routines-runtime.js'
 import {
   initQueryJobRuntime,
   preparePublicDurableQueryAdmission,
@@ -838,6 +840,8 @@ app.use('/api', queryRouter)
 // The scheduled start-of-day brief: settings, status, run-now. Same auth as
 // every other settings route; the brief itself is an ordinary durable job.
 app.use('/api', createMorningBriefRouter(getMorningBriefScheduler))
+// 6.82.0: every routine (the brief first, then skill routines), each with its own cap, switch and breaker.
+app.use('/api', createRoutinesRouter(getRoutineRegistry, routineSkillCatalog))
 app.use('/api', providerProofRouter)
 app.use('/api', transcribeRouter)
 // Ported from cos-glasses-app in 6.24.0. The companion's Sessions tab has been
@@ -1257,6 +1261,7 @@ async function gracefulShutdown(): Promise<void> {
   forceExit.unref?.()
   await meetingAskRuntime.shutdown()
   stopMorningBriefScheduler()
+  stopRoutineScheduler()
   await workReviewRuntime?.close()
   workIntakeStore?.close()
   workHandoffRequestStore?.close()
@@ -1534,6 +1539,8 @@ listenRequiredServers(listeners).then(() => {
       // that store is ready. Its own tick checks the durable-jobs switch and the
       // maintenance gate, so starting it here is safe when either is off.
       startMorningBriefScheduler()
+      // 6.82.0: skill routines ride the same coordinator and the same gates.
+      startRoutineScheduler()
       void workReviewRuntime?.start().catch(error => console.error('[work-reviews] reconciliation unavailable:', error))
     }).catch(error => {
       // The store remains degraded and rejects admission. Legacy /api/query is

package/server/lib/claude-bridge.ts

@@ -436,6 +436,11 @@ export interface CallOptions {
   dispatch?: { restricted: true; tools: readonly string[] }
   /** 6.58.2: `claude --name` for a session this COS session starts fresh (QueryJobRequest.sessionName). */
   sessionName?: string
+  /**
+   * 6.82.0: the token-audit `caller` for this run, so a server-started job is counted by who started
+   * it (`routine:morning-brief`, `routine:routine-<id>`). Absent, every bridge writes the caller it always did.
+   */
+  auditCaller?: string
   /**
    * 6.78.0 Messages steer: the job's steer port. Present only when the coordinator decided the
    * run is steerable (lib/claude-steer.ts). Absent, every argument and every stdin byte is the
@@ -927,7 +932,7 @@ export async function callClaudeStreaming(
       inputChars: inputEstimate,
       outputChars: text.length,
       durationMs: totalMs,
-      caller: options?.lightweight ? 'voice_query' : 'full_query',
+      caller: options?.auditCaller ?? (options?.lightweight ? 'voice_query' : 'full_query'),
       ...keyAuditFields,
       ...keyUsdFields,
     })

package/server/lib/codex-bridge.ts

@@ -817,7 +817,7 @@ export async function callCodexStreaming(
       inputChars: systemPrompt.length + fullQuery.length + contextPrompt.length,
       outputChars: text.length,
       durationMs: totalMs,
-      caller: options?.lightweight ? 'voice_query' : 'full_query',
+      caller: options?.auditCaller ?? (options?.lightweight ? 'voice_query' : 'full_query'),
       ...keyAuditFields,
       ...keyUsdFields,
     })

package/server/lib/cursor-bridge.ts

@@ -528,7 +528,7 @@ export async function callCursorStreaming(
       inputChars: systemPrompt.length + fullQuery.length + contextPrompt.length,
       outputChars: text.length,
       durationMs: totalMs,
-      caller: options?.lightweight ? 'voice_query' : 'full_query',
+      caller: options?.auditCaller ?? (options?.lightweight ? 'voice_query' : 'full_query'),
       turnId: options?.turnId,
       runId: run.runId,
       sessionId: sid,

package/server/lib/direct-bridge.ts

@@ -564,7 +564,7 @@ export async function callDirectStreaming(
       inputChars: messages.reduce((n, m) => n + (typeof m.content === 'string' ? m.content.length : 0), 0),
       outputChars: text.length,
       durationMs: Date.now() - startTime,
-      caller: 'direct_query',
+      caller: options?.auditCaller ?? 'direct_query',
       ...(options?.turnId ? { turnId: options.turnId } : {}),
       runId: run.runId,
       sessionId: sid,

package/server/lib/morning-brief-schedule.ts

@@ -113,9 +113,15 @@ function daysBetween(fromDay: string, toDay: string): number {
   return Math.round((Date.UTC(ty, tm - 1, td) - Date.UTC(fy, fm - 1, fd)) / 86_400_000)
 }
 
+/** The schedule fields the arithmetic reads. The morning brief config and a
+ * 6.82.0 skill routine both carry them, so both share one decision table. */
+export type ScheduleShape = Pick<MorningBriefConfig, 'enabled' | 'time' | 'timezone' | 'days' | 'catchUpMinutes'>
+/** The ledger fields the fire decision reads (a brief run and a routine run both have them). */
+export type ScheduledRunShape = Pick<MorningBriefRun, 'day' | 'trigger' | 'attempt' | 'firedAt' | 'jobId' | 'submitError'>
+
 /** ISO instant of the next scheduled fire at or after `nowMs`, or null when
  * the brief is disabled or no weekday is selected. */
-export function nextScheduledFire(config: MorningBriefConfig, nowMs: number): string | null {
+export function nextScheduledFire(config: Pick<ScheduleShape, 'enabled' | 'time' | 'timezone' | 'days'>, nowMs: number): string | null {
   if (!config.enabled || config.days.length === 0) return null
   const target = parseTime(config.time)
   const clock = localClock(nowMs, config.timezone)
@@ -129,8 +135,8 @@ export function nextScheduledFire(config: MorningBriefConfig, nowMs: number): st
   return null
 }
 
-export type FireDecision =
-  | { fire: true; day: string; attempt: number; resume?: MorningBriefRun }
+export type FireDecision<R extends ScheduledRunShape = MorningBriefRun> =
+  | { fire: true; day: string; attempt: number; resume?: R }
   | { fire: false; reason: 'disabled' | 'not_a_brief_day' | 'before_slot' | 'window_closed' | 'already_fired' | 'in_flight' | 'attempts_exhausted' | 'backoff' }
 
 /**
@@ -140,11 +146,11 @@ export type FireDecision =
  * job id and no error is a crash between ledger write and admission — resumed
  * by client identity rather than re-run.
  */
-export function decideScheduledFire(
-  config: MorningBriefConfig,
-  runs: readonly MorningBriefRun[],
+export function decideScheduledFire<R extends ScheduledRunShape = MorningBriefRun>(
+  config: ScheduleShape,
+  runs: readonly R[],
   nowMs: number,
-): FireDecision {
+): FireDecision<R> {
   if (!config.enabled) return { fire: false, reason: 'disabled' }
   const clock = localClock(nowMs, config.timezone)
   if (!config.days.includes(clock.weekday)) return { fire: false, reason: 'not_a_brief_day' }

package/server/lib/query-job-runtime.ts

@@ -1,3 +1,4 @@
+import { routineAuditCaller } from './routines-config.js'
 import { carriesBoundTo } from './agent-session-binding-store.js'
 import { randomUUID } from 'node:crypto'
 import { resolve } from 'node:path'
@@ -420,6 +421,8 @@ const runner: QueryJobRunner = async ({ jobId, turnId, request, signal, callback
       sessionLockHeld: true,
       ...(request.dispatch ? { dispatch: request.dispatch } : {}),
       ...(request.sessionName ? { sessionName: request.sessionName } : {}),
+      // 6.82.0: a routine's run is counted in the token audit under the routine that started it.
+      ...(routineAuditCaller(request) ? { auditCaller: routineAuditCaller(request) } : {}),
       ...(request.keyTurnOnly ? { keyTurnOnly: true } : {}),
       // 6.78.0: only on a run the coordinator decided is steerable.
       ...(steer ? { steer } : {}),

package/server/lib/routines-config.ts

@@ -0,0 +1,421 @@
+// 6.82.0 Routines: any COS skill on a schedule (Miles, 2026-10-20, Q4: "Pick a skill, a time
+// and days; each routine has its own cap and off switch").
+//
+// The morning brief stays exactly what it was (its own config file, scheduler and golden) and is
+// listed as routine #1 by the registry. Everything here is the SECOND kind: a skill routine.
+//
+// HOW A SKILL ROUTINE STOPS (every new provider caller answers this):
+//  - its own off switch (`enabled`), and the master switch COS_ROUTINES=0 for all of them;
+//  - its own daily cap: admitted runs per local day, scheduled and Run now together;
+//  - a server-wide ceiling across every skill routine per day (ROUTINE_LIMITS.globalRunsPerDay);
+//  - a breaker: N consecutive failed runs open it for a cooldown, and nothing fires while it is open;
+//  - one scheduled slot per selected day, at most `scheduledAttemptsPerDay` submit attempts;
+//  - inert while durable jobs are off or maintenance admissions are closed (as the brief).
+// It runs on a cheap model (sonnet) unless the routine names another, and never on a key lane.
+
+import { createHash, randomBytes } from 'node:crypto'
+import { durableAtomicWriteFileSync, loadJsonOrQuarantine } from './atomic-fs.js'
+import { dataPath } from './data-dir.js'
+import { ensurePrivateDir, isValidTimezone, serverTimezone } from './morning-brief-config.js'
+import { KEY_PROFILE_REJECT_CODE, KEY_PROFILE_SCHEDULED_REJECT, keyProfileRejectApplies } from './key-profile-rejects.js'
+import {
+  normalizeEffortPreference,
+  normalizeModelPreference,
+  type EffortPreference,
+  type ModelPreference,
+} from '../../shared/model-preference.js'
+
+export const ROUTINES_PROTOCOL_VERSION = 1 as const
+
+export const ROUTINE_LIMITS = Object.freeze({
+  /** Skill routines one server holds (the morning brief is not counted). */
+  maxRoutines: 12,
+  nameChars: 60,
+  instructionChars: 1_000,
+  skillNameChars: 64,
+  dailyCapDefault: 2,
+  dailyCapMin: 1,
+  dailyCapMax: 10,
+  /** Every skill routine together, per local day of the server zone. */
+  globalRunsPerDay: 40,
+  breakerFailuresDefault: 3,
+  breakerFailuresMin: 1,
+  breakerFailuresMax: 10,
+  cooldownMinutesDefault: 6 * 60,
+  cooldownMinutesMin: 15,
+  cooldownMinutesMax: 7 * 24 * 60,
+  catchUpMinutesDefault: 3 * 60,
+  catchUpMinutesMax: 12 * 60,
+  /** Submit attempts for one scheduled slot before the day is given up (as the brief). */
+  scheduledAttemptsPerDay: 3,
+  attemptSpacingMs: 2 * 60_000,
+  retainedRuns: 240,
+})
+
+/** Unless a routine names another model, it runs here: the server's fast default, never Opus. */
+export const ROUTINE_DEFAULT_MODEL: ModelPreference = 'sonnet'
+
+const TIME_RE = /^([01]\d|2[0-3]):([0-5]\d)$/
+const CONTROL_RE = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g
+/** A skill's loader identity (`good-morning`, `customer-marketing:intel`). No slash, no path. */
+export const ROUTINE_SKILL_RE = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$/
+/** Routine ids double as the job origin id (QUERY_JOB_ORIGIN_ID_RE) and never equal `morning-brief`. */
+export const ROUTINE_ID_RE = /^routine-[0-9a-f]{10}$/
+
+export class RoutineConfigError extends Error {
+  constructor(readonly code: string, message = code, readonly status = 400) {
+    super(message)
+    this.name = 'RoutineConfigError'
+  }
+}
+
+export interface RoutineBreakerSettings {
+  /** Consecutive failed runs that open the breaker. */
+  failures: number
+  /** How long it stays open. */
+  cooldownMinutes: number
+}
+
+export interface SkillRoutine {
+  id: string
+  kind: 'skill'
+  name: string
+  /** Skill loader identity, without the slash. */
+  skill: string
+  /** Optional words added after the skill call. */
+  instruction: string
+  enabled: boolean
+  time: string
+  timezone: string
+  days: number[]
+  catchUpMinutes: number
+  /** Admitted runs per local day, scheduled and Run now together. */
+  dailyCap: number
+  model: ModelPreference
+  effort?: EffortPreference
+  breaker: RoutineBreakerSettings
+  createdAt: string
+  updatedAt: string
+}
+
+export interface RoutineBreakerState {
+  consecutiveFailures: number
+  /** Set while the breaker is open. Nothing fires before this instant. */
+  openUntil?: string
+  openedAt?: string
+  lastFailure?: { code: string; message: string; at: string }
+}
+
+export type RoutineTrigger = 'scheduled' | 'manual'
+
+export interface RoutineRun {
+  id: string
+  routineId: string
+  day: string
+  trigger: RoutineTrigger
+  attempt: number
+  firedAt: string
+  clientJobId: string
+  generation: 1
+  sessionId: string
+  messageEra?: string
+  globalMsgNum?: number
+  jobId?: string
+  submitError?: { code: string; message: string }
+  lastKnownStatus?: string
+  /** Set once the run's result has been counted by the breaker (exactly once per run). */
+  outcome?: 'completed' | 'failed' | 'canceled'
+}
+
+export interface RoutinesFile {
+  v: 1
+  routines: SkillRoutine[]
+  breakers: Record<string, RoutineBreakerState>
+}
+
+export interface RoutinesLedger {
+  v: 1
+  runs: RoutineRun[]
+}
+
+export interface RoutineStorePaths {
+  routines: string
+  runs: string
+}
+
+export function routinePaths(root?: string): RoutineStorePaths {
+  const configured = root ?? process.env.COS_ROUTINES_DIR?.trim()
+  const base = configured ? configured : dataPath('routines')
+  return { routines: `${base}/routines.json`, runs: `${base}/runs.json` }
+}
+
+/** Master switch. Only an explicit `0`, `false`, `off` or `no` turns every skill routine off. */
+export function routinesEnabledByEnv(env: NodeJS.ProcessEnv = process.env): boolean {
+  const raw = env.COS_ROUTINES?.trim().toLowerCase()
+  return !(raw === '0' || raw === 'false' || raw === 'off' || raw === 'no')
+}
+
+export function newRoutineId(): string {
+  return `routine-${randomBytes(5).toString('hex')}`
+}
+
+/** Deterministic client id for one routine's scheduled slot, so a retry after a crashed submit
+ * admits as the SAME job (the brief's rule, keyed by routine as well). */
+export function routineScheduledClientJobId(routineId: string, day: string, timezone: string): string {
+  const digest = createHash('sha256').update(`routine|${routineId}|${timezone}|${day}`).digest()
+  const bytes = Buffer.from(digest.subarray(0, 16))
+  bytes[6] = (bytes[6] & 0x0f) | 0x40
+  bytes[8] = (bytes[8] & 0x3f) | 0x80
+  const hex = bytes.toString('hex')
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
+}
+
+function cleanText(value: unknown, maxChars: number): string {
+  if (typeof value !== 'string') return ''
+  return value.replace(CONTROL_RE, '').replace(/\r\n?/g, '\n').trim().slice(0, maxChars)
+}
+
+function intIn(raw: unknown, min: number, max: number, code: string, label: string): number {
+  const n = typeof raw === 'number' ? raw : Number(raw)
+  if (!Number.isSafeInteger(n) || n < min || n > max) throw new RoutineConfigError(code, `${label} must be ${min} to ${max}.`)
+  return n
+}
+
+function normalizeDays(raw: unknown): number[] {
+  if (!Array.isArray(raw)) throw new RoutineConfigError('invalid_days', 'days must be a list of weekday numbers, 0 (Sunday) to 6.')
+  return [...new Set(raw
+    .map(value => (typeof value === 'number' ? value : Number(value)))
+    .filter(value => Number.isInteger(value) && value >= 0 && value <= 6))]
+    .sort((a, b) => a - b)
+}
+
+export function normalizeSkillName(raw: unknown): string {
+  const name = typeof raw === 'string' ? raw.trim().replace(/^\//, '') : ''
+  if (!ROUTINE_SKILL_RE.test(name)) throw new RoutineConfigError('invalid_skill', 'Pick a skill from this COS workspace.')
+  return name
+}
+
+export interface RoutinePatchContext {
+  now: Date
+  /** True when the skill is in this workspace's catalog. A routine can only name one that is. */
+  skillExists: (name: string) => boolean
+}
+
+/**
+ * Create or edit a skill routine from an untrusted body. Every field is validated and an invalid
+ * one throws (a settings screen that shows Saved over a rejected time is the failure this guards).
+ * `current` absent means create: `skill` is required and everything else takes its default.
+ */
+export function applyRoutinePatch(current: SkillRoutine | null, raw: unknown, ctx: RoutinePatchContext): SkillRoutine {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new RoutineConfigError('invalid_patch', 'Expected a JSON object.')
+  const patch = raw as Record<string, unknown>
+  const at = ctx.now.toISOString()
+  const base: SkillRoutine = current
+    ? { ...current, days: [...current.days], breaker: { ...current.breaker } }
+    : {
+        id: newRoutineId(),
+        kind: 'skill',
+        name: '',
+        skill: '',
+        instruction: '',
+        enabled: true,
+        time: '08:00',
+        timezone: serverTimezone(),
+        days: [1, 2, 3, 4, 5],
+        catchUpMinutes: ROUTINE_LIMITS.catchUpMinutesDefault,
+        dailyCap: ROUTINE_LIMITS.dailyCapDefault,
+        model: ROUTINE_DEFAULT_MODEL,
+        breaker: { failures: ROUTINE_LIMITS.breakerFailuresDefault, cooldownMinutes: ROUTINE_LIMITS.cooldownMinutesDefault },
+        createdAt: at,
+        updatedAt: at,
+      }
+  if (!current && !('skill' in patch)) throw new RoutineConfigError('invalid_skill', 'Pick a skill from this COS workspace.')
+  if ('skill' in patch) {
+    const skill = normalizeSkillName(patch.skill)
+    if (!ctx.skillExists(skill)) throw new RoutineConfigError('unknown_skill', `/${skill} is not a skill in this COS workspace.`)
+    base.skill = skill
+  }
+  if ('name' in patch) {
+    if (patch.name != null && typeof patch.name !== 'string') throw new RoutineConfigError('invalid_name', 'name must be text.')
+    base.name = cleanText(patch.name, ROUTINE_LIMITS.nameChars)
+  }
+  if (!base.name) base.name = `/${base.skill}`
+  if ('instruction' in patch) {
+    if (patch.instruction != null && typeof patch.instruction !== 'string') throw new RoutineConfigError('invalid_instruction', 'instruction must be text.')
+    base.instruction = cleanText(patch.instruction, ROUTINE_LIMITS.instructionChars)
+  }
+  if ('enabled' in patch) {
+    if (typeof patch.enabled !== 'boolean') throw new RoutineConfigError('invalid_enabled', 'enabled must be true or false.')
+    base.enabled = patch.enabled
+  }
+  if ('time' in patch) {
+    const time = typeof patch.time === 'string' ? patch.time.trim() : ''
+    if (!TIME_RE.test(time)) throw new RoutineConfigError('invalid_time', 'time must be HH:MM in 24-hour form, e.g. 08:00.')
+    base.time = time
+  }
+  if ('timezone' in patch) {
+    if (!isValidTimezone(patch.timezone)) throw new RoutineConfigError('invalid_timezone', 'timezone must be an IANA zone such as America/Chicago.')
+    base.timezone = patch.timezone
+  }
+  if ('days' in patch) base.days = normalizeDays(patch.days)
+  if ('catchUpMinutes' in patch) {
+    base.catchUpMinutes = intIn(patch.catchUpMinutes, 0, ROUTINE_LIMITS.catchUpMinutesMax, 'invalid_catch_up', 'catchUpMinutes')
+  }
+  if ('dailyCap' in patch) {
+    base.dailyCap = intIn(patch.dailyCap, ROUTINE_LIMITS.dailyCapMin, ROUTINE_LIMITS.dailyCapMax, 'invalid_daily_cap', 'dailyCap')
+  }
+  if ('model' in patch) {
+    if (patch.model == null || patch.model === '') {
+      base.model = ROUTINE_DEFAULT_MODEL
+    } else {
+      const model = normalizeModelPreference(patch.model)
+      // A scheduled routine always runs on the subscription, never a key lane (Decision Q2).
+      if (!model && keyProfileRejectApplies(patch.model)) throw new RoutineConfigError(KEY_PROFILE_REJECT_CODE, KEY_PROFILE_SCHEDULED_REJECT)
+      if (!model) throw new RoutineConfigError('invalid_model', 'Unknown model preference.')
+      base.model = model
+    }
+  }
+  if ('effort' in patch) {
+    if (patch.effort == null || patch.effort === '') {
+      delete base.effort
+    } else {
+      const effort = normalizeEffortPreference(patch.effort)
+      if (!effort) throw new RoutineConfigError('invalid_effort', 'Unknown effort preference.')
+      base.effort = effort
+    }
+  }
+  if ('breaker' in patch) {
+    const b = patch.breaker
+    if (!b || typeof b !== 'object' || Array.isArray(b)) throw new RoutineConfigError('invalid_breaker', 'breaker must be an object.')
+    const rec = b as Record<string, unknown>
+    if ('failures' in rec) base.breaker.failures = intIn(rec.failures, ROUTINE_LIMITS.breakerFailuresMin, ROUTINE_LIMITS.breakerFailuresMax, 'invalid_breaker_failures', 'breaker.failures')
+    if ('cooldownMinutes' in rec) base.breaker.cooldownMinutes = intIn(rec.cooldownMinutes, ROUTINE_LIMITS.cooldownMinutesMin, ROUTINE_LIMITS.cooldownMinutesMax, 'invalid_breaker_cooldown', 'breaker.cooldownMinutes')
+  }
+  base.updatedAt = at
+  return base
+}
+
+/** Coerce a stored routine. A damaged field takes its default; a routine with no usable id or skill is dropped. */
+export function coerceRoutine(raw: unknown): SkillRoutine | null {
+  if (!raw || typeof raw !== 'object') return null
+  const r = raw as Record<string, unknown>
+  if (typeof r.id !== 'string' || !ROUTINE_ID_RE.test(r.id)) return null
+  if (typeof r.skill !== 'string' || !ROUTINE_SKILL_RE.test(r.skill)) return null
+  const num = (value: unknown, min: number, max: number, fallback: number) => {
+    const n = Number(value)
+    return Number.isSafeInteger(n) && n >= min && n <= max ? n : fallback
+  }
+  const breaker = (r.breaker && typeof r.breaker === 'object' ? r.breaker : {}) as Record<string, unknown>
+  const model = normalizeModelPreference(r.model)
+  const effort = normalizeEffortPreference(r.effort)
+  const now = new Date().toISOString()
+  let days: number[]
+  try { days = normalizeDays(r.days) } catch { days = [1, 2, 3, 4, 5] }
+  return {
+    id: r.id,
+    kind: 'skill',
+    name: cleanText(r.name, ROUTINE_LIMITS.nameChars) || `/${r.skill}`,
+    skill: r.skill,
+    instruction: cleanText(r.instruction, ROUTINE_LIMITS.instructionChars),
+    enabled: typeof r.enabled === 'boolean' ? r.enabled : false,
+    time: typeof r.time === 'string' && TIME_RE.test(r.time) ? r.time : '08:00',
+    timezone: isValidTimezone(r.timezone) ? r.timezone : serverTimezone(),
+    days,
+    catchUpMinutes: num(r.catchUpMinutes, 0, ROUTINE_LIMITS.catchUpMinutesMax, ROUTINE_LIMITS.catchUpMinutesDefault),
+    dailyCap: num(r.dailyCap, ROUTINE_LIMITS.dailyCapMin, ROUTINE_LIMITS.dailyCapMax, ROUTINE_LIMITS.dailyCapDefault),
+    model: model ?? ROUTINE_DEFAULT_MODEL,
+    ...(effort ? { effort } : {}),
+    breaker: {
+      failures: num(breaker.failures, ROUTINE_LIMITS.breakerFailuresMin, ROUTINE_LIMITS.breakerFailuresMax, ROUTINE_LIMITS.breakerFailuresDefault),
+      cooldownMinutes: num(breaker.cooldownMinutes, ROUTINE_LIMITS.cooldownMinutesMin, ROUTINE_LIMITS.cooldownMinutesMax, ROUTINE_LIMITS.cooldownMinutesDefault),
+    },
+    createdAt: typeof r.createdAt === 'string' ? r.createdAt : now,
+    updatedAt: typeof r.updatedAt === 'string' ? r.updatedAt : now,
+  }
+}
+
+function coerceBreaker(raw: unknown): RoutineBreakerState {
+  const r = (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>
+  const failures = Number(r.consecutiveFailures)
+  const state: RoutineBreakerState = { consecutiveFailures: Number.isSafeInteger(failures) && failures > 0 ? failures : 0 }
+  if (typeof r.openUntil === 'string' && Number.isFinite(Date.parse(r.openUntil))) state.openUntil = r.openUntil
+  if (typeof r.openedAt === 'string') state.openedAt = r.openedAt
+  const last = r.lastFailure as Record<string, unknown> | undefined
+  if (last && typeof last.code === 'string' && typeof last.at === 'string') {
+    state.lastFailure = { code: last.code.slice(0, 64), message: String(last.message ?? '').slice(0, 300), at: last.at }
+  }
+  return state
+}
+
+export function loadRoutinesFile(paths: RoutineStorePaths): { file: RoutinesFile; quarantinedAs?: string } {
+  const loaded = loadJsonOrQuarantine<unknown>(paths.routines)
+  if (loaded.status !== 'ok' || !loaded.data || typeof loaded.data !== 'object') {
+    return { file: { v: 1, routines: [], breakers: {} }, ...(loaded.status === 'corrupt' ? { quarantinedAs: loaded.quarantinedAs } : {}) }
+  }
+  const data = loaded.data as { routines?: unknown; breakers?: unknown }
+  const seen = new Set<string>()
+  const routines: SkillRoutine[] = []
+  for (const entry of Array.isArray(data.routines) ? data.routines : []) {
+    const routine = coerceRoutine(entry)
+    if (!routine || seen.has(routine.id)) continue
+    seen.add(routine.id)
+    routines.push(routine)
+  }
+  const breakers: Record<string, RoutineBreakerState> = {}
+  const rawBreakers = data.breakers && typeof data.breakers === 'object' ? data.breakers as Record<string, unknown> : {}
+  for (const id of seen) if (rawBreakers[id]) breakers[id] = coerceBreaker(rawBreakers[id])
+  return { file: { v: 1, routines: routines.slice(0, ROUTINE_LIMITS.maxRoutines), breakers } }
+}
+
+export function saveRoutinesFile(paths: RoutineStorePaths, file: RoutinesFile): void {
+  ensurePrivateDir(paths.routines)
+  durableAtomicWriteFileSync(paths.routines, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 })
+}
+
+function isRoutineRun(value: unknown): value is RoutineRun {
+  if (!value || typeof value !== 'object') return false
+  const run = value as Record<string, unknown>
+  return typeof run.id === 'string'
+    && typeof run.routineId === 'string'
+    && typeof run.day === 'string'
+    && (run.trigger === 'scheduled' || run.trigger === 'manual')
+    && typeof run.firedAt === 'string'
+    && typeof run.clientJobId === 'string'
+    && typeof run.sessionId === 'string'
+}
+
+export function loadRoutinesLedger(paths: RoutineStorePaths): RoutinesLedger {
+  const loaded = loadJsonOrQuarantine<unknown>(paths.runs)
+  if (loaded.status !== 'ok' || !loaded.data || typeof loaded.data !== 'object') return { v: 1, runs: [] }
+  const raw = (loaded.data as { runs?: unknown }).runs
+  return { v: 1, runs: (Array.isArray(raw) ? raw : []).filter(isRoutineRun) }
+}
+
+export function saveRoutinesLedger(paths: RoutineStorePaths, ledger: RoutinesLedger): void {
+  ensurePrivateDir(paths.runs)
+  const runs = ledger.runs.slice(-ROUTINE_LIMITS.retainedRuns)
+  durableAtomicWriteFileSync(paths.runs, `${JSON.stringify({ v: 1, runs }, null, 2)}\n`, { mode: 0o600 })
+}
+
+/** The prompt a skill routine's durable job carries. Deterministic for (routine, day) so a crash
+ * resume re-admits the same job. Unattended: it never sends, publishes or deletes. */
+export function composeSkillRoutinePrompt(routine: Pick<SkillRoutine, 'name' | 'skill' | 'instruction'>, day: string, ownerName: string, trigger: RoutineTrigger): string {
+  const who = ownerName.trim() || 'the owner'
+  const lines = [
+    `Scheduled COS routine "${routine.name}" for ${day} (${trigger === 'manual' ? 'Run now' : 'on schedule'}).`,
+    `Run the /${routine.skill} skill from this COS workspace and give ${who} its result.`,
+    ...(routine.instruction ? ['', `Also: ${routine.instruction}`] : []),
+    '',
+    'Nobody is watching this run. Read and summarise freely, and write only the files this skill keeps on this Mac.',
+    'Do not send email, Slack or any message, publish, deploy, push, delete data, or spend money. If the skill needs one of those, stop and say what it would do.',
+    'If the skill is missing or a source it needs is unavailable, say so in one plain line instead of guessing.',
+    'Answer in plain text with short lines, so it reads on the glasses.',
+  ]
+  return lines.join('\n')
+}
+
+/** 6.82.0: the token-audit caller for a job a routine started (`routine:<id>`), '' for every other
+ * job, whose callers stay exactly what they were. */
+export function routineAuditCaller(request: { origin?: { kind: string; id: string } }): string {
+  return request.origin?.kind === 'routine' ? `routine:${request.origin.id}` : ''
+}