@gotcos/glasses-server 6.81.0 → 6.83.0

package/CHANGELOG.md

@@ -1,3 +1,96 @@
+## 6.83.0 - Work orchestrator: every session on a card, where each left off, and plan usage, in the planner input
+
+Miles, 2026-10-20 21:47: the Work chat should act like an orchestrator, not a form: find a card's sessions itself,
+read a session's log to know where to pick up, and fork to whichever of Claude, Codex or Cursor has usage left.
+Decisions (21:55): Auto-send is a per-card switch in COS Control; plan usage only, never a silent key-lane fallback.
+This is M1 plus the planner-input parts of M2 and M3 (`docs/work-orchestrator.md`). The server plans; COS Control
+still owns every send.
+
+- **Client matrix.** COS Control 0.5.333 uses it. Older Controls never send `orchestrator: true` and get 6.81.0's
+  prompt, schema, parser and output budget byte for byte (`WORK_CHAT_SYSTEM` SHA-256 pinned). This release also
+  carries everything in 6.82.0 (routines): the two lines were built in parallel from 6.81.0 and merged here.
+- **Phase A: Control pushes, the server keeps.** `POST /api/work/orchestrator/input {workID, meetingWorkIDs, snapshot}`
+  stores Control's bounded Work snapshot (`data/work-orchestrator/control-snapshot.json`, 0600, atomic; ids, modes,
+  statuses, times only) and answers the card's planner rows. Nothing there sends, links or calls a model.
+- **Discovery** (canary C3 rules 1 to 8): links, newSession, fork child and continue receipts, the card's COS-WORK
+  handoff prompt in a user turn, a valid status line in the session's own reply, the tag in the live row, the card's
+  source meeting (a suggestion). Never: tool output, quoted handoffs, subagents, a sourceSessionID. Precision fixes:
+  Claude rows credited by their own sessionId, Codex guardian and other child threads skipped (thread_spawn folds into
+  its parent), placeholder tags inert, newest strong evidence decides which card a session works on now. The log
+  index is incremental (`data/work-orchestrator/tag-index.json`): 8.7 GB, 1,368 files scanned in 10.4 s on Miles's
+  Mac, then 112 ms. On the toadstone card it finds both sessions.
+- **Pick-up notes** (M2 input): deterministic, from the last 6 MB of the log (seek from the end), harness notices
+  skipped, the live busy flag on top, secrets and customer identifiers (emails, phones, URL paths, amounts, long ids)
+  redacted, at most 1,500 characters. No model call.
+- **Plan usage** (M3 input): Claude `get_usage` over stream-json (no turn), Codex `account/rateLimits/read` (never
+  `supportsLunaReserve`, never a reset-credit call), Cursor unknown (no Keychain read, no TUI launch). Read on
+  demand only: a plan input re-reads a provider whose reading is older than 2 min (the plan is where a fork or a new
+  session is chosen); `GET /api/work/orchestrator/usage` re-reads one older than 10 min (2 with `refresh=1`). No
+  timer reads usage by default; the 10-minute poll runs only when the owner sets `COS_WORK_USAGE_POLL=1` (Miles has
+  not approved a background poll for every user). `rate_limit_event` frames from plan-lane Claude jobs and
+  `provider_limit` failures from plan-lane jobs mark a provider exhausted until the stated reset (or 1 h), over any
+  cached percentage; a key-lane turn never counts. Three failed probes pause that provider for an hour. Read on this
+  Mac at 23:0x: Claude 43% weekly headroom, Codex 8%.
+- **Planner input and answer.** Rows add discoveredBy, linked, member, lastTouchedCard, lastActivity, live, busy,
+  pickup, available + reason (not_in_session_list, app_owned, cursor, plan_limit, on_another_card) and forkable; the
+  input adds now, usage, leftOut and newSessionProviders. `automatic` stays the only Continue gate. Answers may Fork a
+  forkable row or start a New session on an offered provider. `WORK_CHAT_ORCHESTRATOR_RULES` (appended only for an
+  orchestrator input): prefer headroom, never an exhausted provider, avoid stale owners, continue vs fork, and never
+  say a card has no sessions when rows or leftOut are present.
+- **Every plan logged**, from any client: `data/work-orchestrator/plans.jsonl` (2 MB, newest half kept) and one
+  `[work-orchestrator] plan` line: sessions sent and their availability, left out and why, usage age, assignments
+  (mode and target, never text), outcome, time.
+- **Lens plans (Miles 2026-10-21 09:11, "Add both").** A plan the lens made can be saved into the card's Work chat
+  history, and sent from the lens. `GET /api/work/chat` adds `lensPlans: 1` and `lensPlansControl {connected,
+  lastSeenSec, autoSend}` (connected: COS Control polled the lens inbox in the last 60 s). The lens records with
+  `POST /api/work/chat/lens-rounds` (201, a repeated `clientRoundId` 200 with the same body; 400 `invalid_lens_round`
+  with `field`, 404 `unknown_work`, 413), reads `GET .../lens-rounds/:roundId` (state and per-assignment results, never
+  the prompts), asks `POST .../:roundId/send` (202; 409 `already_sent`, `send_in_progress`, `plan_stale`; 423
+  `control_not_connected`; 428 `confirmation_required` without `confirm: "two-step"` unless the card's Auto-send is on)
+  and `POST .../:roundId/stop`. COS Control, loopback only, polls `GET /api/work/chat/lens-inbox`, marks
+  `POST .../:roundId/history` and reports `POST /api/work/chat/lens-send/:sendRequestId/result`. Nothing here sends:
+  COS Control performs every send through its own Send path. A send not picked up in 10 minutes is `expired`.
+  Storage `data/work-lens-rounds.json` (0600, atomic, 200 rounds, 14 days). Every route answers 503 `maintenance`
+  while admissions are closed. Existing routes are unchanged (pinned). Contract: `CONTRACT_lens_plans_6.83.0_2026-10-21.md`.
+  QA on 6.10.651 (additive): `POST /api/work/chat/lens-rounds/:roundId/mac-send` (COS Control reports its own Send of a
+  lens round on the Mac, so a later lens send never delivers twice; `already_sent` lists the ids, and held counts as
+  sent); round outcomes add `failed` and `stopped` (all failed, all stopped), `refused` only for an actual refusal.
+  Checks after QA: `work-lens-rounds.test.ts` 32 tests; gate green baseline (40 tests in 2 files), 64 of 64 killed;
+  full suite 8,583 passed, 0 failed, 3 skipped (569 files).
+  Checks before QA: `work-lens-rounds.test.ts` 25 tests; `server/scripts/work-lens-rounds-mutation-gate.mjs` (not packaged): green
+  baseline (33 tests in 2 files), 56 of 56 mutants killed by a named test. Full suite after: 8,576 passed, 0 failed,
+  3 skipped (569 files).
+- **Checks.** Full suite 8,506 passed, 0 failed, 3 skipped (563 files); `tsc --noEmit` clean. The first full run
+  failed (9 Claude bridge suites that mock `node:child_process` could not load the orchestrator runtime; the key-lanes
+  P6 census had an unclassified site): the bridges now report through a leaf module and the site is classified.
+  `server/scripts/work-orchestrator-mutation-gate.mjs` (not packaged): green baseline (62 tests in 8 files), 70 mutants,
+  68 killed by a named test, 2 documented survivors (a seek-cut row never parses; the key check refuses `mode` from an
+  older client first). The gate found 11 real gaps on its first pass, each closed by a test (and fixed its own `$&`
+  replacement bug). Journey: the toadstone card replay (fake logs in the 2026-10-20 shapes) finds both sessions, plans
+  with them, and never says "no sessions"; the 6.81.0 path on the same card saw none. Real probes on Miles's Mac read
+  Claude and Codex usage with no turn sent. Shadow replay C4 (10 cards, 10 Opus calls, nothing sent): see the hand-off.
+- **Release checks (merged 6.82.0 + 6.83.0, after the on-demand usage change).** `tsc --noEmit` clean. Full suite
+  8,550 passed, 1 failed, 3 skipped (568 files): the failure is ST-3 in `query-job-steer-coordinator.test.ts`, a
+  fixed 50 ms sleep before reading the steer snapshot; that file and `claude-steer.ts` are unchanged from 6.82.0, the
+  carried steer was in the prompt, and the file passed 18 of 18 five runs out of five in isolation. Routines gate:
+  green baseline (55 tests in 6 files), 42 of 42 killed. Orchestrator gate: green baseline (66 tests in 8 files), 79
+  mutants, 77 killed by a named test, the same 2 documented survivors; the 10 new mutants, which replace the old `usage-poll-switch` (the opt-in switch and its
+  gate, the on-demand read, its 10-minute cache and 2-minute refresh, the plan's 2-minute re-read, the input and route
+  wiring) are all killed. `npm pack --dry-run`: 536 files, every new routines and orchestrator source file present,
+  no tests, fixtures, gates or canary.
+
+## 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/docs/work-orchestrator.md

@@ -0,0 +1,184 @@
+# Work orchestrator (server 6.83.0, COS Control 0.5.333)
+
+Plan: `operations/personal/wk43_2026/PLAN_work_orchestrator_glasses_work_routines_2026-10-20.md` (MU repo), approved by
+Miles 2026-10-20 21:55. Canaries: `CANARY_C1_usage_2026-10-20.md`, `CANARY_C2_C4_orchestrator_2026-10-20.md`.
+This milestone is M1 plus the planner-input parts of M2 (pick-up notes) and M3 (plan usage).
+
+## Phase A: how Work state reaches the server (decided 2026-10-20)
+
+Work state lives in COS Control today: confirmed links in `work-handoffs/handoffs.session-cards.json`, the receipt
+journal in `handoffs.json` (flock'd, compare-and-swap writes, 10 MB cap), and Work chat rounds in `task-chat/*.json`.
+The planner runs in the server. Two ways to join them were on the table.
+
+| | A. Control pushes a snapshot through the helper | B. The server reads Control's files on this Mac |
+| --- | --- | --- |
+| Who owns the bytes | Control writes, under its own journal lock; the server keeps a copy | The server reads a journal Control may be writing (it would have to speak Control's lock and CAS protocol) |
+| Contract | A versioned, bounded snapshot with only what discovery needs | Control's private schema, which gains fields almost every release |
+| Paths | None hardcoded in the server | The server hardcodes `~/Library/Application Support/COS Control/...` (the "multi-user path" rule) |
+| Phone, lens, cloud workers | Read the server's copy | Cannot: a cloud worker never sees a Mac file |
+| Freshness | Pushed right before every plan, and after each recorded handoff | Always current on this Mac |
+| Privacy | Ids, modes, statuses, times. Never prompts, results or file names | Everything in the journal, prompts included |
+
+**Decision: A.** Control pushes a snapshot on change through the helper (`work-orchestrator-input`), and the server
+stores it atomically in `data/work-orchestrator/control-snapshot.json` (0600). Reasons, in order: Control stays the
+single writer and owner of sends (this milestone keeps its handoff path, receipts, fences and Stop); the snapshot is a
+contract we can version, where Control's journal is not; the server never learns Control's private paths; and the same
+copy serves the phone, the lens and later cloud workers, which B can never do. The one thing B does better, freshness,
+is closed by pushing immediately before each plan (the push and the input build are one helper call) and after each
+handoff Control records. The server reports the snapshot's age in every input it builds, so a stale copy is visible,
+never silent.
+
+Snapshot (protocol 1, bounded, refused whole when out of bounds):
+
+```
+{ version: 1, controlVersion, sentAt,
+  links:    [{ sessionID, workID, at }]                                         <= 4000
+  receipts: [{ id, workID, mode, provider, sessionID, sourceSessionID,
+               forkChildID, status, createdAt }]                                <= 4000, newest first
+  live:     { checkedAt, rows: [{ id, title, status, updatedAt, busy,
+               waitingOnUser, appOwned }] }                                     <= 400 }
+```
+
+`live` is the session list Control read with `--fresh` immediately before planning. Guardian review rows are left out
+by Control and dropped again by the server.
+
+## What the server builds (`POST /api/work/orchestrator/input`)
+
+For one card it returns the rows the planner sees, already ranked and bounded to 12, plus what it left out and why,
+plus the usage snapshot. It never sends anything and never changes a link or a receipt.
+
+### Discovery (canary C3 rules 1 to 8)
+
+| Rank | Evidence | Card session? |
+| --- | --- | --- |
+| 1 | Confirmed link | Yes |
+| 2 | `newSession` receipt on the card | Yes |
+| 3 | `fork` receipt with a child (journaled `forkChildID`, or a `sessionID` that differs from `sourceSessionID`) | Yes |
+| 4 | `continueSession` receipt on the card | Yes |
+| 5 | The handoff template for this card's tag in a user turn | Yes (the only way to find fork children) |
+| 6 | A valid `COS-WORK <tag>: done/needs input/blocked` line in the session's own reply | Yes with 1 to 5; alone a suggestion |
+| 7 | The tag in the live row's summary | Yes with 1 to 5; alone a suggestion |
+| 8 | The session worked the card's confirmed source meeting (meeting card `meeting:<recordId>`) | Suggestion, reason shown |
+| Never | Tag in tool output, pasted or quoted handoffs, subagent transcripts, or as `sourceSessionID` | Not a card session |
+
+Precision fixes from the canary: Claude rows are credited by their own `sessionId` (a resumed file replays older
+sessions' rows); Codex guardian threads are skipped; Codex `thread_spawn` children fold into their parent; a tag no
+handoff prompt or Control record ever used is ignored (placeholders such as `aaaaaaaaaaaa`); when one session is on
+several cards, its newest strong evidence decides which card it is working on, and the older cards keep it as history
+(`available: false, reason: on_another_card`).
+
+The log scan is an incremental index (`data/work-orchestrator/tag-index.json`): append-only logs are read from the last
+offset, so after the first pass only new bytes are scanned. Lines are parsed only when they contain `COS-WORK`.
+
+### Rows
+
+Each row adds to the existing `{id, title, summary, status, automatic, openWork}`:
+`discoveredBy` (evidence kinds), `linked`, `lastTouchedCard` (newest evidence for this card), `lastActivity`, `live`
+(in the session list Control just read), `pickup` (<= 1,500 characters), `available` and `reason`
+(`not_in_session_list`, `app_owned`, `cursor`, `plan_limit`, `on_another_card`, `busy`), and `forkable`.
+`automatic` stays the only gate for a Continue: Control sets it (Claude or Codex, not app owned, in the live list).
+
+### Pick-up notes (M2 input, deterministic)
+
+Seek from the end of the log (last 6 MB; Codex logs reach 1.4 GB), parse the last human ask, the last result, whether
+the turn ended, open todos, questions and any COS-WORK status line; harness notices are skipped; the live busy flag
+overrides the state line. Secrets (`redactSecrets`) and customer identifiers (emails, phone numbers, URL paths and
+query strings, money amounts, long numeric ids) are redacted before the note leaves the module. No model call in this
+milestone; the canary's optional Haiku polish stays undecided.
+
+### Usage (M3 input, plan usage only)
+
+| | Claude | Codex | Cursor |
+| --- | --- | --- | --- |
+| Probe | `claude -p` stream-json control request `get_usage` (`skip_behaviors`), no turn | `codex app-server` `account/rateLimits/read` (`excludeResetCreditDetails`) | none: marked unknown (no Keychain read, no TUI launch; not approved) |
+| Read | on demand: before a plan (POST input) when older than 2 min; GET usage when older than 10 min (2 with `refresh=1`) | same | never |
+| Timer | none by default; every 10 min only with `COS_WORK_USAGE_POLL=1` | same | never |
+| Passive | `rate_limit_event` frames from the server's own plan-lane Claude jobs | none yet | none |
+| Fallback | a `provider_limit` failure marks the provider exhausted until its stated reset, or 1 h | same | same |
+
+Never sent: `supportsLunaReserve`. Never called: `ConsumeAccountRateLimitResetCredit`. Codex is gated on
+`ordinaryUsageAllowed === false` first. Probes run in a fresh empty directory, hooks and MCP off, killed by exact PID
+after 15 s. Stops: no background poll unless the owner sets `COS_WORK_USAGE_POLL=1` (Miles has not approved a poll
+for every user; the 6.83.0 release reads usage only when a plan or a usage read asks); three failed probes in a row
+pause that provider's probe for an hour. A key-lane turn's rate-limit frames are never recorded as plan usage.
+
+### Planner input and answer
+
+The plan request (`POST /api/work/chat`) from an orchestrator client carries `orchestrator: true`, `now` (ISO time),
+`usage` (per provider: state, headroom, reset, age, source), `leftOut` (what discovery left out and why) and
+`newSessionProviders`. The answer may now hold three kinds of assignment:
+
+| `mode` | Target | Rule |
+| --- | --- | --- |
+| `continue` (default) | `sessionID` | the row is `automatic: true` (unchanged) |
+| `fork` | `sessionID` | the row is `forkable: true` |
+| `newSession` | `provider` | the provider is in `newSessionProviders` |
+
+A client that does not send `orchestrator: true` gets today's prompt, schema and parser, byte for byte.
+
+### Plan log
+
+Every plan, from any client, appends one line to `data/work-orchestrator/plans.jsonl` (rotated at 2 MB, keeping the
+newest half) and prints one `[work-orchestrator] plan` line: the sessions sent with their availability, what was left
+out and why, the usage snapshot's age per provider, the assignments (mode and target, never prompt text), the planner,
+the outcome and the time taken.
+
+## Control 0.5.333
+
+- Plans with the server's input when `GET /api/work/chat` advertises `orchestrator: 1`; otherwise exactly as 0.5.332.
+- Refreshes the session list right before planning. A plan from no sessions says why (none discovered; or N discovered
+  but none can take a Continue, each with its reason) and still lets the planner propose a new session.
+- Journals `forkChildID` on fork receipts. Leaves Guardian review rows out.
+- Auto-send: a per-card switch whose default is Settings › Work › Send plans without review (off by default). On: the
+  plan's assignments (Continue, Fork and New session) go through the existing handoff path without the review click,
+  each with a visible Stop and a log line. Off: today, unchanged.
+
+## Lens plans (server 6.83.0, COS Control 0.5.333)
+
+Contract: `operations/personal/wk43_2026/CONTRACT_lens_plans_6.83.0_2026-10-21.md` (MU repo), Miles 2026-10-21 09:11
+("Add both"). The lens plans with `POST /api/work/chat` as above, then may save that plan into the card's Work chat
+history and ask for it to be sent. COS Control stays the owner of every send and of its Work chat journal: the server
+holds lens rounds and requests (`server/lib/work-lens-rounds.ts`, `server/routes/work-lens-rounds.ts`); Control pulls
+them, writes the round into the card's record, sends through its own Send path and reports results.
+
+| Who | Route | What |
+| --- | --- | --- |
+| Lens | `POST /api/work/chat/lens-rounds` | Record a plan. 201 `{roundId, workID, state, control}`; a repeated `clientRoundId` 200, same body (answered from the store even if the card left the board). 400 `invalid_lens_round` + `field`, 404 `unknown_work`, 413 `lens_round_too_large`, 503 `work_board_unavailable` when neither Control's snapshot nor the board can say. |
+| Lens | `GET /api/work/chat/lens-rounds/:roundId` | State (`recorded`, `in_history`, `send_requested`, `sending`, `sent`, `partly_sent`, `failed`, `stopped`, `refused`, `expired`), `inHistory`, `autoSendCard`, per assignment `{id, state, sessionID, receiptId, detail}`. Never prompts. |
+| Lens | `POST /api/work/chat/lens-rounds/:roundId/send` | 202 `{sendRequestId, state: "send_requested"}`. Omitted ids: the whole plan minus what is already sent (or held by COS Control). 409 `send_in_progress`, `already_sent` (with `assignmentIds`: those already sent), `plan_stale`; 428 `confirmation_required` (no `confirm: "two-step"` and the card's Auto-send off); 423 `control_not_connected`. |
+| Lens | `POST /api/work/chat/lens-rounds/:roundId/stop` | 202 `{stopRequestId, state: "stop_requested"}`; 423 without Control. |
+| Control (loopback) | `GET /api/work/chat/lens-inbox?since=<cursor>&autoSend=0\|1` | Rounds not yet in history (after `since`, with their full plan), send requests (each with its round) and stop requests (with the send they belong to), 50 at most. Listing a send or stop is its pick-up: it is listed once. `autoSend` is Settings > Work > Send plans without review, the card-independent hint. |
+| Control (loopback) | `POST /api/work/chat/lens-rounds/:roundId/history` | `{state: "in_history", autoSendCard?}` after Control wrote the round into the card's record. `autoSendCard` is the card's switch; Control re-posts it when the switch changes. |
+| Control (loopback) | `POST /api/work/chat/lens-rounds/:roundId/mac-send` | The same `{assignments: [...]}` shape, when COS Control sent assignments of the round with its own Send on the Mac (after a 423 the wearer is told to send from the Mac). Those never go again from the lens. |
+| Control (loopback) | `POST /api/work/chat/lens-send/:sendRequestId/result` | `{assignments: [{id, state, receiptId?, detail?, sessionID?}]}`, as often as states change (`held` until earlier work resolves, then `sent`; `stopped` after a Stop). |
+
+Rules the server enforces:
+
+- **Connected** means a loopback inbox poll in the last 60 s (Control polls every 5 s while running). A phone request
+  never counts. Without it a send or stop is 423 and the plan stays recorded, so it can be sent from the Mac.
+- **Confirmation.** `confirm: "two-step"` (with `confirmedAt`) records the wearer's two-step tap. Without it the send is
+  refused 428 unless the card's Auto-send is on as Control last reported it; Control checks the switch again before it
+  sends and refuses an unconfirmed assignment if the switch has since gone off.
+- **Plan stale.** At record time the server keeps the card's sessions from Control's snapshot (links, receipt targets,
+  fork children). A send is 409 `plan_stale` when that set changed (a session added or gone). Sessions the round's own
+  sends reported are not a change, so a partly sent plan can send the rest. No snapshot on either side: never stale.
+- **Expiry.** A send request not picked up in 10 minutes is `expired` (and never handed to Control later); a new send
+  may be asked for. A picked-up assignment Control never reports is marked `failed` after 15 minutes so the lens can
+  stop polling. A round is kept 14 days; at most 200 are kept, oldest idle first.
+- **Outcome.** Every assignment terminal (`sent`, `delivered`, `failed`, `refused`, `stopped`): all sent or delivered
+  is `sent`, some is `partly_sent`. None: all stopped is `stopped`; all refused (or refused and stopped) is `refused`, an
+  actual refusal (confirmation, a stale plan, a COS Control check); otherwise `failed`. The lens stops polling at
+  `sent`, `partly_sent`, `failed`, `stopped`, `refused` or `expired`.
+- **Sent from the Mac.** An assignment COS Control reported through `mac-send` as `sent`, `delivered` or `held` (queued
+  behind earlier work) is already sent: naming it is 409 `already_sent` with its id, and an omitted list leaves it out.
+  The round reads as that Mac send's outcome (`partly_sent` while the rest of the plan was never sent).
+- **Recording never sends.** COS Control writes a recorded round into history and nothing else; only a lens send request
+  (two-step confirm, or the card's Auto-send plus an explicit request) or Miles's own Send on the Mac sends it.
+- **Maintenance.** Every route answers 503 `maintenance` while admissions are closed; writes hold the `api_mutation`
+  lease themselves (the global mutation lease skips `/work/chat/lens-*` so the code is the contract's).
+- **Storage.** `data/work-lens-rounds.json`, 0600, atomic; an unreadable file is moved aside, never overwritten. Inside a
+  test the store is in memory only.
+
+Checks: `server/routes/work-lens-rounds.test.ts` (record, idempotent repeat, send with and without confirm, Auto-send,
+423, `plan_stale`, expiry, stop, loopback-only, maintenance, the existing GET and POST unchanged) and
+`server/scripts/work-lens-rounds-mutation-gate.mjs` (not packaged).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.81.0",
+  "version": "6.83.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",
@@ -86,6 +88,9 @@
     "!server/scripts/dictation-polish-mutation-gate.mjs",
     "!server/lib/meeting-engine/__fixtures__/**",
     "!server/lib/__fixtures__/**",
+    "!server/lib/work-orchestrator/__fixtures__/**",
+    "!server/scripts/work-orchestrator-mutation-gate.mjs",
+    "docs/work-orchestrator.md",
     "!shared/**/*.test.ts",
     ".env.example",
     ".cos-profile.example.json",

package/server/index.ts

@@ -158,6 +158,9 @@ import { createSubqKeyRouter } from './routes/subq-key.js'
 import { createDecisionProviderRouter } from './routes/decision-provider.js'
 import { createJevRouter } from './routes/jev.js'
 import { createWorkChatRouter } from './routes/work-chat.js'
+import { createWorkOrchestratorRouter } from './routes/work-orchestrator.js'
+import { createWorkLensRoundsRouter } from './routes/work-lens-rounds.js'
+import { startWorkOrchestrator } from './lib/work-orchestrator/runtime.js'
 import { createWorkSearchRouter } from './routes/work-search.js'
 import { isReadOnlyApiPost } from './lib/work-search.js'
 import { dataPath } from './lib/data-dir.js'
@@ -170,6 +173,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,
@@ -417,6 +422,8 @@ app.use('/api', (req, res, next) => {
     || req.path === '/meeting-ask/requests'
     || /^\/meeting-ask\/requests\/[A-Za-z0-9_-]+\/cancel$/.test(req.path)
     || req.path.startsWith('/maintenance/drain')
+    // 6.83.0 lens plans: each write takes the api_mutation lease itself and answers the contract's 503 `maintenance`.
+    || req.path.startsWith('/work/chat/lens-')
   if (lifecycleOwned) return next()
 
   // COS Control must prove the candidate while a committed cross-boot gate is
@@ -834,10 +841,16 @@ app.use('/api', createDecisionProviderRouter())
 app.use('/api', createSubqKeyRouter())
 app.use('/api', createWorkSearchRouter())
 app.use('/api', createWorkChatRouter())
+// 6.83.0 Work orchestrator: Control's Work snapshot, the planner input and plan usage (docs/work-orchestrator.md).
+app.use('/api', createWorkOrchestratorRouter())
+// 6.83.0 lens plans: the lens records a plan and may ask for it to be sent; COS Control pulls, sends and reports.
+app.use('/api', createWorkLensRoundsRouter())
 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 +1270,7 @@ async function gracefulShutdown(): Promise<void> {
   forceExit.unref?.()
   await meetingAskRuntime.shutdown()
   stopMorningBriefScheduler()
+  stopRoutineScheduler()
   await workReviewRuntime?.close()
   workIntakeStore?.close()
   workHandoffRequestStore?.close()
@@ -1477,6 +1491,9 @@ listenRequiredServers(listeners).then(() => {
     resumeAutonomousMeetingSaves()
     // 6.77.0: transcript cleanup data whose meeting is gone, and screen text past retention.
     scheduleTranscriptCleanupSweep()
+    // 6.83.0: the usage-event sink and a first background log scan. Plan usage is read on demand; the 10-minute poll
+    // runs only with COS_WORK_USAGE_POLL=1.
+    startWorkOrchestrator()
 
     // Debris from an import killed mid-write: a temp file, or a sidecar whose
     // markdown never landed. Both are invisible to every reader, so nothing
@@ -1534,6 +1551,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

@@ -60,6 +60,7 @@ import { terminalProviderAuthFailure } from './provider-terminal-error.js'
 import { claudePermissionArgs, getClaudeTrustMode } from './claude-permissions.js'
 import { terminateProviderProcess } from './provider-process-lifecycle.js'
 import { teeJobTrail, type JobTrailDraft } from './job-trail.js'
+import { noteClaudeRateLimitFrame } from './work-orchestrator/usage-events.js'
 import { claudeSupportsSessionName } from './claude-cli-support.js'
 import { applyTurnRequestEnv, createTurnRequestBinding, spawnWithTurnRequest } from './turn-request.js'
 import { STEER_REAPER_MS, STEER_SETTLE_MS, SteerTracker, composeFirstContent, encodeUserLine, steerClock, type SteerPort } from './claude-steer.js'
@@ -436,6 +437,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 +933,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,
     })
@@ -1129,6 +1135,9 @@ export async function callClaudeStreaming(
 
         if (event.type === 'system' && event.subtype === 'init' && typeof event.model === 'string') {
           updateClaudeRun(run.runId, { resolvedModelId: event.model })
+        } else if (event.type === 'rate_limit_event') {
+          // 6.83.0: free passive plan-usage refresh (canary C1). A key-lane turn's limits are the key's, never the plan's.
+          if (!keyProfile) noteClaudeRateLimitFrame(event)
         } else if (event.type === 'stream_event') {
           // Real-time token streaming — fires every few tokens during generation
           receivedStreamEvents = true

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-coordinator.ts

@@ -37,6 +37,7 @@ import type { MaintenanceWorkLease } from './maintenance-lifecycle.js'
 import { applyTrailToolMode, type JobTrailDraft } from './job-trail.js'
 import { crashLoopParkedError, type BootResumeGate } from './boot-resume.js'
 import { restartNoticeEnabled } from './query-job-feature.js'
+import { noteJobProviderLimit } from './work-orchestrator/usage-events.js'
 
 const CLIENT_JOB_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
 
@@ -836,7 +837,10 @@ export class QueryJobCoordinator {
         this.finishActive(active)
         return false
       }
-      const result = await this.store.fail(active.jobId, normalizeQueryJobError(error))
+      const failure = normalizeQueryJobError(error)
+      // 6.83.0: a plan-lane provider limit marks that provider exhausted for the Work orchestrator (until its reset).
+      noteJobProviderLimit(snapshot.provider, failure.code, error instanceof Error ? error.message : String((error as any)?.message ?? ''), active.request.model, snapshot.lane)
+      const result = await this.store.fail(active.jobId, failure)
       const projected = isTerminalQueryJobStatus(result.job.status)
         ? await this.projectTerminal(result.job, active.request)
         : false

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 } : {}),