@gotcos/glasses-server 6.58.1 → 6.59.0

package/CHANGELOG.md

@@ -1,3 +1,43 @@
+## 6.59.0
+
+### Work on the glasses: progress, everything open, and a request inbox COS Control works through
+
+- Miles, 2026-09-30: "Can we make sure that our EHPK work tab has the core updates that make these so useful." His decisions the same morning: the glasses get progress and start work; evidence text may come back to the glasses, up to 280 characters, never the prompt, detail or result. The contract all three builds share is `PLAN_work_on_glasses_6_9_561_2026-09-30.md` (v1 S1 to S4, then v2 items 1 to 11 and v3 items 13 to 21 from QA round 1). Glasses 6.9.561 and COS Control 0.5.252 build on it.
+- Before this the glasses could see one status word per handoff and nothing else: the server projected only id, status, provider and session from COS Control's journal, and there was no way for the glasses to start tracked Work. Control's journal, its one-active-handoff fence and its COS-WORK tracker live on the Mac, so starting Work from the glasses has to go through Control.
+- **Progress on an item.** `GET /api/work-board/activity` now answers `capabilities`, the task's own `taskRevision`, a `savedDestination` when Control saved one, and per handoff `mode`, `model` (a New session's; Control's `existing-session` placeholder on a Continue or Fork is left out), `channel`, `createdAt`, `updatedAt` (the newest progress event Control recorded, else `createdAt`), `progress` (`reported` done, needs input, blocked or null; `reportedBy` session or Jev; `evidence`; `receivedAt`; `lastMove { from, to, at, undone }`; `paused`), `acknowledged`, `appOpened`, `serverHold`, `waitingInApp`, `sending` (a send in flight: preparing or sending, made in the last 10 minutes), `requestedFrom` and `requestId`. Each field maps from Control's own `WorkProgress` and receipt rules, read from Control 0.5.250's source, never guessed.
+  - `appOpened`, `serverHold` and `waitingInApp` belong to the session, across every receipt that names it, with Control's `sameSession` rule: a Continue into a session another handoff opened in its app is the app's, as Control treats it. A handoff with no session owns nothing.
+  - Evidence is cleaned as a 6.58.2 session name is (the shared `flattenDisplayText`) and kept to 280 whole characters and 1,200 UTF-16 units; it appears only with a report.
+  - Lenient for everything new: a malformed `progress` block reads `{ unreadable: true }` on its own, a malformed `appOpen` or `acknowledgedAt` reads as absent, a time no date can hold is left out. The journal is never made unavailable by them. Every existing check (O_NOFOLLOW, symlinked folders, owner, size, the isolated-runtime refusal, the strict receipt, session and draft checks) is unchanged.
+  - A 0.5.248 tab that never reached a session reads as `canceled`, as Control reads it on load.
+  - The board row behind `taskRevision` and `savedDestination` is read within 3 s; past that the activity answers without them. The glasses routes share one board read, kept for 10 s after it finished and dropped at once by a Work stage or meeting write.
+- **Everything open.** New `GET /api/work-board/activity/open` with `total` and `truncated`: every board task whose newest handoff in the last 14 days needs input or is blocked, needs attention (failed, refused, unknown, completed with no report), is running (queued, running, delivered, or a send in flight: `preparing` or `sending` made in the last 10 minutes), or reports done, and is not acknowledged. Items carry `group`, `taskRevision` and the board's title, ordered by group and then by the newest progress, cut to 50 after sorting. A report counts only on a receipt that did not fail and was not refused or canceled (Control's `WorkTracking.latest`), and a checked task shows only while its handoff is queued or running (Control's board). Read-only: no provider call, no Jev.
+- **Task revision.** `taskRevision` (on the activity, each open item and every `GET /api/work-board` task) is Control's own `WorkSource.taskSnapshot` revision of that one task, so a request is refused only when that task changed, not when another card in the domain file did. It is pinned to Control's Swift by `server/lib/__fixtures__/control-task-snapshot` (Control's code from 0.5.250, 12 rows, `generate.sh`), outside the package.
+- **Saved destination.** `savedDestination { mode, provider, model?, sessionId? }` from Control's draft for the task's current revision, only when Control's `sendPlan` would send exactly that and a request with it would pass: a non-empty prompt within Control's draft limit, Continue on claude, codex or cursor, a native Fork of claude or codex (whatever provider the draft still holds), a Fork to the other of the two with one of its model slots, a New session whose slot matches its provider. Never the prompt.
+- **The handoff request inbox.** The glasses `POST /api/work-board/handoff-requests` `{ clientRequestId, domain, workIdentity, expectedTaskRevision, intent, mode, sessionId?, model?, note?, destinationSource, replyTo? }` and poll `GET .../:clientRequestId`. COS Control, on the Mac only (403 `local_only` otherwise), lists `?state=pending`, claims (`POST .../:id/claim`: 200 with a `claimToken`, 409, 410) and reports under that token (`POST .../:id/result`: `sent` with its receipt, `refused` with a reason, `unresolved` with its receipt). The server never runs a provider for a request.
+  - Idempotent by `clientRequestId` (the same request again is 200, answered before the board is read; a different one is 409 `request_id_conflict`); one pending or claimed request per item (409 `request_pending`); 409 `revision_changed` when this task changed; 409 `task_complete` for a checked task or one at stage Complete (Control refuses both); 40 a day by the Mac's local day (429 `daily_cap` with `resetsAt` and `Retry-After`; the message names no time). The board read is bounded at 5 s (503 `work_board_unavailable` with its `cause`; nothing is created).
+  - Reply by voice and Not done yet are `intent: reply | notDone` with `replyTo`: the item's newest receipt, continuing the session it went to, with a note (409 `reply_target_invalid` otherwise).
+  - Time: a pending request expires 10 minutes after it was made and can never be claimed after; a claim carries `claimExpiresAt` (10 minutes on) and with no result by then reads `unconfirmed`, which still takes one late result; a time more than 5 minutes ahead of the clock ends the wait at once (pending reads expired, claimed reads unconfirmed, never expired). All follow from stored times, so a read never writes, and each transition is logged once.
+  - `capabilities.requests` is 1 only while Control listed pending requests in the last 120 s (in memory); `requestsInbox` and `requestsConsumerSeenAt` say the rest, so the glasses can tell Control 0.5.250 (which never consumes it) from a live inbox.
+  - Validation: UUID v4, safe domain, 12-hex identity, 64-hex task revision, the intent and mode enums, a full `provider:native` session UUID (native-thread-id rule, no nested provider) for claude, codex or cursor on Continue and claude or codex on Fork, a Fork model only of the other platform, no model on Continue, a model slot this server knows (a New session without one takes `COS_G2_DEFAULT_MODEL`, else sonnet), and a note of at most 2,000 characters in which control characters (except newline and tab), U+2028 and U+2029, invisible format characters (except the joiners) and `COS-WORK` (read as Control reads a status line, so `COS**-WORK` too) are refused, not cleaned.
+  - Stored in `work-handoff-requests/requests.json` with one writer lock and durable atomic writes, like work intake; a bad record (a New session without its model among them) is quarantined on its own and ages out with the requests after 7 days; Control's list reports the count. A locked or unreadable file disables the inbox without stopping the server. Writes take the usual `/api` maintenance lease, and nothing here holds a restart.
+  - Control's claim and result refusals, every 5xx and the board failures on the activity routes are logged with codes, never a note.
+- Also: `package.json` describes the server without an em dash.
+- QA round 1 (Completionist, User, Skeptic and Ghost Hunter): no blocker for the glasses; the Skeptic's one blocker (a late true "sent" refused after the claim timeout) is the `unconfirmed` state. Everything above marked v2 or v3 in the contract came from it, with the Ghost Hunter's independent check of the gate and of the Swift hashes.
+- QA round 2 (one verifier, on 98b8298): shippable. Its last items are in: four guards pinned with tests (the domain in both row lookups, the 10 s glance age, the newer-read-wins rule), a long reason that survives a restart, the placeholder model left out, a claim ahead of the clock reading unconfirmed, the board read dropped after a stage or meeting write and aged from its end, the normalized `COS-WORK` check, sends in flight shown as running, and the zone-independent daily-cap test.
+- Docs: new `docs/work-handoff-requests.md` (in the package); `docs/work-task-runtime.md` says what the projection now carries and names its two pieces of session text (the session title, and the evidence Miles approved on 2026-09-30); `docs/work-intake.md` points to it.
+- Tests: the projection over fixture journals (each field, per-session ownership with short ids and other providers, an unreadable block beside a readable one, the evidence rules and both caps, times out of range, the strict checks unchanged, no private text in any serialized answer); the open list (groups, the 14-day edge, acknowledgement, failed reports, checked tasks, newest receipt, progress order before the cut, total and truncated); the task revision against the Swift harness; the saved destination against each `sendPlan` case; the bounded, shared board read; both routes over HTTP with the real API token (loopback only for Control, claim race, claim tokens, late results, daily cap, timeouts with causes, replies); the store (validation table, idempotency, conflict, one per item, revision, local-day cap, expiry at exactly 10 minutes, skew, claim timeout, persistence across a reload, a crash in the middle of a write, 7-day retention and quarantine). `node server/scripts/work-progress-mutation-gate.mjs` runs its mutants from a green baseline; each must fail the test named for it.
+
+## 6.58.2
+
+### A New session from Work is named after its task, and visible while it runs
+
+- Miles, 2026-09-29 at 20:40, on the first COS Control 0.5.249 New session (job c3878966, 20:36:49 to 20:39:11): Control opened it in Claude 31 s after the run ended, and it sat at the top of the MU-Chief-Staff sidebar as "General coding session". "This is super generic. It should be based off of the same name of the task that we're sending in." And while it ran: "I don't see anything in the sidebar ... We should probably show the session behind this." The card said "session live status unavailable" and Sessions listed the run as a COS server job.
+- **A new Claude session is named.** A query job may carry `sessionName`. The server cleans it: control characters, zero-width spaces and direction marks and overrides become spaces (the joiners U+200C and U+200D stay), whitespace collapses, and a name over 100 characters is cut at 100, back to its last space when that space is in the second half; the cut counts whole characters, so it never splits an emoji. When the job starts a Claude session of its own, the server runs `claude --name=<name>`, which writes the session's title; the Claude app shows it in the sidebar. Never on a Continue into a session the COS session already has, never on a read-only dispatch, and a named session never takes the session the server warmed at boot (that one opens with "ready" under the glasses prompt); it starts clean. The server asks `claude --help` once whether the installed CLI takes `--name`; one that does not runs the session unnamed, as before. The name is outside the request fingerprint, so a retry that renames the same job is the same job, and an older server drops the field.
+- **The job names its Claude session while it runs.** Claude announces its session id in its first stream event (a hook or init line, before any answer text); before this the server recorded it only with the final result, so a New session from Work could not be linked, shown or opened while it ran. The server now records it on the run and on the job (`cliSessionId`, through the same link update as the provider process) from that first event, only while the job is running; a job that already ended keeps what it had. At completion the result's id is recorded as before. Claude only: Codex, Cursor and Ollama jobs are unchanged.
+- **Session titles in long transcripts.** The session list reads a Claude session's custom title from the end of its transcript; a transcript longer than the 256 KB window whose only title sits near the top now falls back to the top.
+- Proven on this Mac first (claude 2.1.285): `claude -p --name` writes `{"type":"custom-title",...}` into the transcript (and again as the session goes on), the same line the Claude app shows as a session's name; `--resume <id> --name` renames; a name that starts with a dash, in the `--name=` form, is taken as the name; and every stream event, from the first hook line, carries the session id.
+- Tests: the name's cleaning, joiners kept, the cut (at the last space, exactly at the limit, a run of emoji and of joined family emoji cut in whole characters), the request carrying it outside the fingerprint; `--name=` only for a session the COS session starts (not a Continue, not a dispatch, not the warmed session, not on a CLI without the option, a dash-leading name kept as one argument); the help probe (asked once, a CLI or help failure is a no); the first event with an id linking once (not an event without one, not a dispatch); the job showing the session while still running and keeping it at completion; a link after the job ended changing nothing; the runtime passing the name down and the early id up; a title at either end of a long transcript.
+
 ## 6.58.1
 
 ### A copy that lost its audio no longer holds the ring

package/docs/work-handoff-requests.md

@@ -0,0 +1,181 @@
+# Work progress and handoff requests (6.59.0)
+
+The glasses see how Work handoffs are going, and can ask COS Control to start one. The server only reads COS Control's handoff journal and keeps a small inbox of requests. It never runs a provider for a request and never asks Jev on these routes. Every route here uses the existing `/api` authentication; COS Control's own inbox routes also answer only on the Mac itself.
+
+## Capabilities
+
+The activity and open-work answers carry `capabilities`:
+
+| Field | Meaning |
+| --- | --- |
+| `progress: 1` | This server projects progress (below). An older server sends no `capabilities`. |
+| `requests` | 1 only while COS Control is taking glasses requests: it listed pending requests in the last 120 s. Kept in memory, so after a restart it reads 0 until Control polls again. Offer Start work only on 1. |
+| `requestsInbox` | 1 when the request inbox opened on this server. 1 with `requests: 0` means COS Control (0.5.252 or newer) is not running or not polling. |
+| `requestsConsumerSeenAt` | When COS Control last listed pending requests (ISO), or null. |
+
+Any future change to the request schema moves `requests` to 2.
+
+## Progress on an item: `GET /api/work-board/activity?domain=<domain>&workIdentity=<12hex>`
+
+Unchanged fields stay as they were (`id`, `workId`, `domain`, `status`, `provider`, `sessionId`, `sessionTitle`, `error`). The result gains `capabilities`, `taskRevision` (the task's own revision, below) and, when Control saved one, `savedDestination`, both at the top level. Each activity may also carry:
+
+| Field | Meaning | From COS Control's journal |
+| --- | --- | --- |
+| `mode` | `continueSession`, `fork` or `newSession` | `mode` |
+| `model` | The model slot a New session was sent with. Never on a Continue or a Fork (Control records the placeholder `existing-session` there) | `modelID` |
+| `createdAt` | ISO time the handoff was sent | `createdAt` (seconds since 1970) |
+| `updatedAt` | The newest progress event, never earlier than `createdAt` | `progress.events[].at` |
+| `progress.reported` | `done`, `needsInput`, `blocked` or `null` | `progress.reported` (an unknown kind reads as `null`, as Control reads it) |
+| `progress.reportedBy` | `session` (its own status line) or `jev` (Jev read the reply) | `progress.reportedBy` |
+| `progress.evidence` | At most 280 characters and 1,200 UTF-16 units | `progress.evidence` |
+| `progress.receivedAt` | When the session was seen to have the work | `progress.receivedAt` |
+| `progress.lastMove` | `{ from, to, at, undone }`: the newest move COS made | the newest `moved` event and its `undoneAt` |
+| `progress.paused` | A manual move back (or an Undo) paused automatic moves | `progress.paused` |
+| `progress: { unreadable: true }` | The progress block is there but the server cannot read it: there may be a report it cannot show | a malformed `progress` |
+| `acknowledged` | You reviewed or acknowledged it | `acknowledgedAt` set, or status `reviewed` |
+| `appOpened` | Its SESSION is owned by its app | any receipt naming the same session (Control's `sameSession`) was opened in its app (`appOpen.openedAt`), came from a 0.5.248 tab, or went to the app (channel `app`) |
+| `serverHold` | The COS server is still running a Work New session on its SESSION | any receipt on the same session with channel `job`, mode `newSession`, not terminal |
+| `waitingInApp` | A note for its SESSION is queued in its app; nothing reached the session yet | any receipt on the same session with channel `app` and status `queued` |
+| `channel` | How Control delivered it: `job`, `fork`, `app`, `turn`, `queue` or `tab` | `channel` |
+| `sending: true` | A send in flight. Its `status` still reads `unknown` (as for older clients); with this flag say "Sending", not an unresolved delivery. Absent otherwise | status `preparing` or `sending`, made in the last 10 minutes (an older one was interrupted) |
+| `requestedFrom` | `glasses` when Control sent it from a glasses request | `requestedFrom` |
+| `requestId` | The handoff request it answered | `requestId` (Control 0.5.252) |
+
+`appOpened`, `serverHold` and `waitingInApp` look at every receipt in the journal that names the session, as Control's `appOwner` and `serverHold` do, and are false for a handoff with no session. `reportedBy` and `evidence` appear only with a report; show Jev's evidence as a reading, not as the session's words. Evidence is cleaned as a session name is (control characters, zero-width space, direction marks and overrides as spaces; joiners kept; whitespace, U+2028 and U+2029 included, collapsed).
+
+Parsing is lenient for everything new. A malformed `progress` block reads `{ unreadable: true }` on its own (its `updatedAt` is then its `createdAt`); a malformed `appOpen` or `acknowledgedAt` reads as absent; a time no date can hold is left out. None of them makes the journal unavailable. Every check the server already made on the rest of the journal is unchanged, and so are the file protections (no symlinked file or folder, owner only, under 10 MB, never read in an isolated runtime).
+
+A handoff COS Control 0.5.248 opened as a tab and never linked to a session (channel `tab`, `queued`, no session) reads as `canceled`, as Control reads it.
+
+The board row behind `taskRevision` and `savedDestination` is read within 3 s. One read is shared with the other glasses routes and kept for 10 s after it finished; a Work stage or meeting write through this server drops it at once. Past the 3 s, or with no board, the activity still answers, without those two fields: treat a missing `taskRevision` as "refresh, no Start".
+
+## Everything open: `GET /api/work-board/activity/open`
+
+`{ version: 1, available, reason?, capabilities, items, total, truncated }`. Each item is an activity (as above) plus `workIdentity`, `domain`, `title` (the board row's; the receipt's work title is never returned), `taskRevision`, `group` and, when saved, `savedDestination`. It takes no parameters (400 `invalid_open_activity_request`).
+
+An item is a board task (`task:<domain>:<12 hex>` with a row on the board) whose newest receipt (by time, then id; any revision) was sent in the last 14 days and falls in a group:
+
+| `group` | When |
+| --- | --- |
+| `needsInput` | It reports needs input or blocked, and is not acknowledged |
+| `attention` | It failed, was refused, is unknown (delivery unresolved), or completed with no report (an unreadable one included), and is not acknowledged |
+| `running` | It is queued, running or delivered, or a send in flight (`sending: true`; its `status` still reads `unknown`, so label these by `group` or the flag). An older one was interrupted and is `attention` |
+| `done` | It reports done, and is not acknowledged |
+
+- A report counts only on a receipt that did not fail and was not refused or canceled, as Control's `WorkTracking.latest` reads it; such a receipt goes to `attention` (or nowhere, when canceled).
+- A checked task shows only while its newest receipt is `queued` or `running`, as Control's board does. A task whose stage is Complete but that is not checked still shows.
+- Order: the groups in the order above; within each, the newest `updatedAt` first, then the newest send. The list is cut to 50 after sorting; `total` counts every item and `truncated` says whether any were cut.
+- The board is read within 5 s. Past that, or when the journal or board cannot be read, `available: false` with a reason.
+- Read-only: no provider call, no Jev, no write.
+
+`GET /api/work-board` also carries `taskRevision` on every task.
+
+## Task revision
+
+`taskRevision` is COS Control's own revision of the task: the SHA-256 of the context `WorkSource.taskSnapshot` builds from the row (its words, domain, Done when, source and meeting links). It changes only when that task changes, never when another card in the same domain file does. The server's computation is pinned to Control's Swift by `server/lib/__fixtures__/control-task-snapshot` (its `generate.sh` rebuilds the goldens).
+
+## Saved destination
+
+`savedDestination: { mode, provider, model?, sessionId? }` comes from COS Control's draft for the task's current revision; a draft saved before the task changed does not count, as in Control. It is present only when Control's `sendPlan` would send exactly that and a handoff request with it would pass the rules below:
+
+- the draft's prompt is not empty and within Control's draft limit (31,520 UTF-16 units);
+- Continue: a claude, codex or cursor session;
+- a native Fork: a claude or codex session, whatever other provider the draft still holds;
+- a Fork to the other platform: a claude or codex source, the other of the two as target, and a model slot of that target;
+- New: a model slot whose provider is the draft's provider.
+
+`provider` is always set. The draft's prompt is never returned.
+
+## Handoff requests
+
+The glasses leave a request, COS Control claims it and runs its own send with every guard it has (the journal fence, one active handoff per item, the status line, the session name, the server hold, the app owner, open in app). The requests live in `work-handoff-requests/requests.json` in the server data directory.
+
+### Glasses: `POST /api/work-board/handoff-requests`
+
+```
+{ clientRequestId, domain, workIdentity, expectedTaskRevision, intent, mode, sessionId?, model?, note?, destinationSource, replyTo? }
+```
+
+- `clientRequestId`: a UUID v4 (either case; stored in lowercase). `domain`: a safe domain name. `workIdentity`: 12 hex. `expectedTaskRevision`: the task's `taskRevision`.
+- `intent`: `start`, `reply` (Reply by voice) or `notDone` (Not done yet). Reply and Not done yet name `replyTo`, the item's newest receipt, continue the session that receipt went to, and carry a note; Start names no `replyTo`.
+- `mode`: `continueSession`, `fork` or `newSession`. `sessionId` is exactly `provider:native`, with provider claude, codex or cursor and native a full lowercase session UUID (never a short id, a path, or another `provider:` inside). A live Claude session listed by its 8-character id cannot be named, so do not offer it. Continue works with claude, codex and cursor sessions and takes no model. Fork works from claude and codex sessions only; a model on a Fork is a Fork to the other platform and must be a slot of that platform. A New session names no session; without a model it takes the server's default (`COS_G2_DEFAULT_MODEL`, else `sonnet`), and the stored request names it. A model is a slot this server knows (`opus`, `fable`, `sonnet`, `haiku`, `codex-frontier`, `codex-balanced`, `cursor-grok`, `cursor-composer`, `ollama`).
+- `note`: at most 2,000 characters after trimming. Newlines, tabs and the joiners U+200C and U+200D are kept. Refused (400, never cleaned): any other control character, U+2028 and U+2029, any other invisible format character (direction marks and overrides, zero-width space, soft hyphen, byte-order mark), a broken surrogate, and the text `COS-WORK` in any case (an agent quoting it back could move the card). `COS-WORK` is looked for as COS Control reads a status line, with `*`, `_`, backticks and joiners taken out first, so `COS**-WORK` is refused too.
+- `destinationSource`: `saved`, `jev` or `user`. A hint for COS Control's copy; Control never trusts it.
+- An empty string or `null` counts as not given for `sessionId`, `model`, `note` and `replyTo`. Any other field, or a body over 16 KB, is refused.
+
+Answers:
+
+| Status | Code | When |
+| --- | --- | --- |
+| 201 | | Recorded as `pending`: `{ request }` |
+| 200 | | The same `clientRequestId` and the same request again: the stored request, in whatever state it is now. Answered before the board is read |
+| 400 | `invalid_handoff_request` | Anything malformed |
+| 404 | `task_not_found` | No board row for that domain and work identity |
+| 409 | `task_complete` | The task is checked, or at stage Complete (COS Control refuses both) |
+| 409 | `request_id_conflict` | The same `clientRequestId` with a different request |
+| 409 | `revision_changed` | This task changed since `expectedTaskRevision` |
+| 409 | `reply_target_invalid` | `replyTo` is not this task's newest receipt, or the request continues a different session |
+| 409 | `request_pending` | The item already has a pending or claimed request |
+| 429 | `daily_cap` | 40 requests already made today, counted by the Mac's local day whatever became of them. The error carries `resetsAt` (the Mac's next local midnight as an ISO instant, for the client to format; the message names no time) and the answer a `Retry-After` |
+| 503 | `work_board_unavailable` | The board did not answer within 5 s or failed; `cause` says why (`work_board_timeout`, `cos_pipeline_not_configured`, ...). Nothing was created |
+| 503 | `work_history_unavailable` | A reply's receipt cannot be checked: COS Control's journal cannot be read here |
+| 503 | `handoff_requests_unavailable` | The inbox did not open on this server |
+| 503 | `handoff_store_closed` | The server is shutting down |
+| 503 | `maintenance_drain_active` | COS Control is draining the server for an update (the usual `/api` maintenance lease). This body is the maintenance shape, `{ error: "maintenance_drain_active", message, retryable: true, retryAfterSeconds? }`, with `Retry-After` when known; try again after it. Nothing was created |
+
+After a transport failure or a timeout, GET the same `clientRequestId` before telling anyone anything: 404 means nothing was recorded.
+
+### Glasses: `GET /api/work-board/handoff-requests/:clientRequestId`
+
+`{ request: { clientRequestId, state, receiptId?, reason?, createdAt, expiresAt, claimedAt?, claimExpiresAt?, resultAt? } }`, never the note. `expiresAt` is `createdAt` plus 10 minutes, the last moment it can be claimed; `claimExpiresAt` is `claimedAt` plus 10 minutes, the last moment COS Control may send it. 404 `request_not_found` means the server no longer has the request (it keeps requests for 7 days).
+
+| `state` | Meaning |
+| --- | --- |
+| `pending` | Waiting for COS Control on the Mac |
+| `claimed` | COS Control took it and is sending |
+| `sent` | Control sent it; `receiptId` names the handoff |
+| `refused` | Control did not send it; `reason` says why |
+| `unresolved` | Control sent it but cannot confirm delivery; `receiptId` names the handoff. "Delivery is unresolved. Check Work on the Mac." |
+| `unconfirmed` | Control claimed it and did not report back within 10 minutes: it may or may not have been sent. "COS Control did not confirm. Check Work on the Mac before trying again." Never "Not sent" |
+| `expired` | Nobody claimed it within 10 minutes. Nothing was sent |
+
+### COS Control (on the Mac only: any other caller gets 403 `local_only`)
+
+- `GET /api/work-board/handoff-requests?state=pending` returns `{ version: 1, requests, quarantined }`: the requests in full (intent, mode, session, model, note, reply target, destination source, claim deadline), oldest first, and how many unreadable records are set aside. `state` may be any state or left out; listing `pending` is what tells the glasses Control is taking requests.
+- `POST /api/work-board/handoff-requests/:id/claim` (no body) is atomic: 200 `{ request, claimToken }` with the request now `claimed`; the same `{ claimToken }` again is 200 while the claim holds; 409 `already_claimed` otherwise; 410 `request_expired`; 404 `request_not_found`. Check `claimExpiresAt` immediately before sending, and never send after it.
+- `POST /api/work-board/handoff-requests/:id/result` `{ state, receiptId?, reason?, claimToken }`:
+  - `sent` needs `receiptId`; `refused` needs `reason` (and a `receiptId` when there is one); `unresolved` needs `receiptId`.
+  - Taken for a claimed request, and once for an `unconfirmed` one (a result that arrives late).
+  - The same result again is 200 with no change; any other is 409 `request_not_claimed`; a wrong token is 409 `claim_token_mismatch`; 410 `request_expired`.
+  - The reason is cleaned (control characters as spaces) and kept to 500 characters.
+  - Control should retry a result until the server accepts it.
+
+### Time
+
+- A pending request expires 10 minutes after `createdAt` and can never be claimed after that, so a Control that starts tomorrow never fires yesterday's tap.
+- A claimed request with no result 10 minutes after the claim becomes `unconfirmed` and still takes one late result.
+- A time more than 5 minutes ahead of the server's clock (a clock that jumped) ends the wait at once: a pending request is `expired`; a claimed one is `unconfirmed`, never expired, and still takes its one late result.
+- These follow from the stored times on every read; the next write stores them. A read never writes. Each transition is logged once, with the request id and never the note.
+- A request survives a restart and stays claimable until `createdAt` plus 10 minutes, whatever happened in between.
+
+### Storage and recovery
+
+One server process owns the file (`writer.lock`); writes are durable and atomic (a private temp file, fsync, rename). Requests and set-aside records older than 7 days are dropped on the next write; at 40 a day that is at most a few hundred. An unreadable record is set aside on its own (`quarantined`) and logged at start. An unreadable or unsafe file disables the inbox (503, `capabilities.requestsInbox: 0`) without stopping the server: keep the file for diagnosis, then move it aside to start empty.
+
+Writes take the same maintenance lease as every short `/api` write, so they are refused while COS Control drains the server for an update. Nothing here holds a restart: a request that waits through one simply expires if it is not claimed in time.
+
+Rolling back to a server before 6.59.0 leaves the file unread and these routes answer 404 there; COS Control and the glasses should read that 404 as a server without the inbox.
+
+### Logs
+
+Every refusal of a claim or a result, every 5xx (with the board's `cause`), each expiry and each claim that went unconfirmed are logged as `[work-handoff-requests] ...` with the request id and code, and the activity routes log `[work-board] ...: answered without the board (<cause>)`. A note is never logged.
+
+## Privacy
+
+Responses never carry a receipt's `prompt`, `detail`, `result` or work title, a progress event's text, or a draft's prompt. Two projected fields are session text: `sessionTitle` (projected since 6.56.0) and `evidence`, up to 280 characters of the session's status line or Jev's reading (Miles approved this on 2026-09-30). A request's note goes back only to COS Control's list and claim, and to the glasses that sent it (in the create answer), never in the status view.
+
+A Continue into a busy session queues on the Mac and may reach the session later; `claimExpiresAt` bounds when Control sends, not when a queued turn runs.
+
+## Verification
+
+`npx vitest run server/lib/work-activity.test.ts server/routes/work-board.test.ts server/lib/work-handoff-requests.test.ts server/routes/work-handoff-requests.test.ts` covers the projection, the open list, the task revision (against Control's own Swift output), the saved destination, the inbox and its routes. `node server/scripts/work-progress-mutation-gate.mjs` runs its mutations in a private copy, refuses to start on a red baseline, and requires each mutant to fail the test named for it.

package/docs/work-intake.md

@@ -34,3 +34,7 @@ The journal is `work-intake/intake.json` in the server data directory, owned by
 Since 6.57.1 `POST /api/work-board/session-recommendation` also takes exactly `{ reviewId, sessions }` for a meeting review (`reviewId` = `wr_` + 32 hex). The server reads the review's meeting title and reviewed follow-up from its own store; the client never sends work text. Errors: 400 `invalid_review_request` (bad id or session list), 404 `review_not_found`, 404 `reviews_unavailable` (reviews off), 503 `review_store_unavailable` (defensive; the stock lookup reads memory).
 
 Since 6.58.0 `POST /api/work-board/completion-check` takes exactly `{ domain, id, provider, sessionId }` plus an optional `after` (ISO time). It asks Jev whether the session's replies since `after` (or its newest reply) show the task finished, judged against its Done when or, without one, its own text. The server reads the task from the board and the replies from its own transcripts; the client sends names and a time only. It answers `{ provider: "jev", verdict: "done" | "not_done" | "unclear", confidence, basis: "done_when" | "task", model, cached }` or `{ provider: "none", reason }` (`no_reply`, `no_task_text`, a Jev condition, `completion_unavailable`). Errors: 400 `invalid_completion_request`, 404 `task_not_found`, 404 `session_not_found`. COS Control 0.5.247 asks only while the session is idle and its newest reply since the handoff has no `COS-WORK` status line, at most twice per handoff, and moves a card to QA only on done at 0.8 (0.85 without a Done when).
+
+Since 6.58.2 `POST /api/query-jobs` also takes an optional `sessionName` (a string; the server cleans it as the 6.58.2 changelog says and keeps at most 100 characters; anything else is no name, never an error). It names only a Claude session the job starts itself (`claude --name=<name>`, when the installed CLI lists `--name`); a Continue, a dispatch, a Codex, Cursor or Ollama job, and an older server ignore it, and it is not part of the request fingerprint. A Claude job's snapshot carries `cliSessionId` from Claude's first stream event while the job is still `running`, not only at completion. COS Control 0.5.250 sends the Work item's title for New session, Start work and Fork to Claude, and links its receipt as soon as the running job names the session.
+
+Since 6.59.0 `GET /api/work-board/activity` also projects each handoff's progress (the report, its evidence of at most 280 characters, the newest move), the task's own revision and a saved destination, `GET /api/work-board/activity/open` lists every open handoff across the board, and `POST /api/work-board/handoff-requests` lets the glasses ask COS Control to start Work, reply, or say it is not done yet, which Control claims on this Mac and sends with its own guards. The server runs no provider and no Jev for any of it. See `docs/work-handoff-requests.md`.

package/docs/work-task-runtime.md

@@ -62,12 +62,22 @@ platforms, isolated runtimes, missing/unsafe/malformed journals report
 `available:false`, not a successful empty history. Custom data roots are treated
 as isolated for native-journal reading. There is no request-supplied file path.
 
-Only receipt identity/status/provider/session fields are projected. Prompt, detail,
-result, draft and source text are never returned. Error text is generic. Session
-ownership is never inferred from titles. `sending`/`preparing` project as unknown;
-queued/delivered receipts are not task completion. The journal has no per-receipt
-update timestamp, so no fabricated `updatedAt` is emitted. This endpoint does not
-poll providers, resend work or mutate the native journal.
+Receipt identity/status/provider/session fields are projected, and since 6.59.0
+also mode, model slot, channel, times, acknowledgement, the session's app and server
+ownership (per session, across every receipt that names it), the request a receipt
+answered, and COS Control's own progress record: the report (done, needs input,
+blocked), who made it, its evidence, when the session received the work, the newest
+automatic move and whether moves are paused (`docs/work-handoff-requests.md`). Two
+projected fields are session-derived text: the session title (since 6.56.0) and the
+evidence, which Miles approved returning on 2026-09-30, at most 280 characters and
+1,200 UTF-16 units, cleaned as a session name is. Prompt, detail, result, work title,
+draft and source text and progress event text are never returned. Error text is
+generic. Session ownership is never inferred from titles. `sending`/`preparing`
+project as unknown; queued/delivered receipts are not task completion. `updatedAt` is
+the newest progress event Control recorded, else the receipt's `createdAt`; nothing
+is fabricated. A malformed progress block reads `{ unreadable: true }` on its own and
+never makes the journal unavailable. This endpoint does not poll providers, resend work or mutate
+the native journal.
 
 ## Qualification
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.58.1",
-  "description": "COS Glasses \u2014 self-hosted AI heads-up-display server for Even G2 smart glasses, powered by Claude Code, Codex, Cursor Agent CLI, or local Ollama",
+  "version": "6.59.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": {
     "glasses-server": "bin/cli.cjs",
@@ -44,6 +44,7 @@
     "!server/scripts/work-review-candidate.ts",
     "!server/scripts/work-review-mutation-gate.mjs",
     "!server/scripts/work-intake-mutation-gate.mjs",
+    "!server/scripts/work-progress-mutation-gate.mjs",
     "!server/scripts/mutation-gate.mjs",
     "!server/lib/meeting-engine/__fixtures__/**",
     "!server/lib/__fixtures__/**",
@@ -64,6 +65,7 @@
     "docs/control2-task-runtime.md",
     "docs/work-reviews.md",
     "docs/work-intake.md",
+    "docs/work-handoff-requests.md",
     "work-task-runtime",
     "docs/work-task-runtime.md",
     "!server/scripts/build-work-task-runtime.py"

package/server/index.ts

@@ -125,9 +125,13 @@ import { createQueryJobsRouter } from './routes/query-jobs.js'
 import { createWorkReviewsRouter } from './routes/work-reviews.js'
 import { createWorkBoardRouter } from './routes/work-board.js'
 import { createWorkIntakeRouter } from './routes/work-intake.js'
+import { createWorkHandoffRequestsRouter } from './routes/work-handoff-requests.js'
 import { createJevRouter } from './routes/jev.js'
 import { dataPath } from './lib/data-dir.js'
 import { WorkIntakeStore, createOptionalWorkIntakeStore } from './lib/work-intake-store.js'
+import { WorkHandoffRequestStore, createOptionalWorkHandoffRequestStore, handoffRequestCapabilities } from './lib/work-handoff-requests.js'
+import { createWorkBoardReader } from './lib/work-board-reader.js'
+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'
@@ -625,7 +629,13 @@ app.use('/api', createQueryJobsRouter(queryJobCoordinator, {
 }))
 const workReviewRuntime = createDefaultWorkReviewRuntime()
 app.use('/api', createWorkReviewsRouter(workReviewRuntime))
-app.use('/api', createWorkBoardRouter())
+// Work handoff requests (6.59.0): the glasses ask for Work to start and COS Control claims them. Optional: a bad
+// journal answers 503 and `capabilities.requests: 0`, never blocks boot. The server runs no provider for a request.
+const workHandoffRequestStore = createOptionalWorkHandoffRequestStore(() => new WorkHandoffRequestStore(dataPath('work-handoff-requests')))
+// One bounded board read (5 s) shared by the glasses' Work glances and the request inbox; GET /api/work-board primes it.
+const workBoardReader = createWorkBoardReader(() => listBoard())
+app.use('/api', createWorkBoardRouter({ readBoard: workBoardReader, requests: () => handoffRequestCapabilities(workHandoffRequestStore, Date.now()) }))
+app.use('/api', createWorkHandoffRequestsRouter({ store: workHandoffRequestStore, readBoard: workBoardReader }))
 // Work intake (6.57.0): meeting-derived suggestions, asks and review items. Optional: a bad journal never blocks boot.
 const workIntakeStore = createOptionalWorkIntakeStore(() => new WorkIntakeStore(dataPath('work-intake')))
 app.use('/api', createWorkIntakeRouter({ store: workIntakeStore }))
@@ -948,6 +958,7 @@ async function gracefulShutdown(): Promise<void> {
   stopMorningBriefScheduler()
   await workReviewRuntime?.close()
   workIntakeStore?.close()
+  workHandoffRequestStore?.close()
   stopMeetingImportScheduler()
   stopMeetingMergeScheduler()
   sessionHooksRuntime.stop()

package/server/lib/agent-session-store.ts

@@ -580,7 +580,17 @@ export function parseJsonLine(line: string): Record<string, unknown> | null {
 }
 
 export async function lastCustomTitle(path: string): Promise<string | null> {
-  const text = await readWindow(path, true)
+  // The CLI re-writes its custom-title line as a session goes on, so the tail normally holds the
+  // newest. 6.58.2: a transcript longer than the window whose only title sits near the top (a
+  // `claude -p --name` run that wrote a long answer) falls back to the head.
+  const tail = customTitleIn(await readWindow(path, true))
+  if (tail) return tail
+  const st = await fileStat(path)
+  if (!st?.isFile || st.size <= HEAD_BYTES) return null
+  return customTitleIn(await readWindow(path, false))
+}
+
+function customTitleIn(text: string): string | null {
   let found: string | null = null
   for (const line of text.split('\n')) {
     if (!line.includes('custom-title')) continue

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 { claudeSupportsSessionName } from './claude-cli-support.js'
 
 // Inactivity = no stdout data for this long → kill (catches stalls)
 const INACTIVITY_BY_MODEL: Record<ClaudeModelPreference, number> = {
@@ -340,6 +341,12 @@ export interface StreamCallbacks {
   /** 6.52.0: readable steps of a durable Messages job (lib/job-trail.ts). Optional, and
    * absent on every path that is not a durable job with the trail on. */
   onTrail?: (draft: JobTrailDraft) => void
+  /**
+   * 6.58.2: the provider named its own session, at the start of the run. Claude announces
+   * its session id in the first stream event; before this the id reached the job only with
+   * the result, so COS Control could not show a New session from Work while it ran.
+   */
+  onNativeSession?: (linkage: { cliSessionId: string }) => void
 }
 
 /** Claude CLI can emit `subtype: success` with `is_error: true`; the boolean
@@ -395,6 +402,8 @@ export interface CallOptions {
   sessionLockHeld?: boolean
   /** Read-only scheduled-task dispatch. Same shape as QueryJobRequest.dispatch. */
   dispatch?: { restricted: true; tools: readonly string[] }
+  /** 6.58.2: `claude --name` for a session this COS session starts fresh (QueryJobRequest.sessionName). */
+  sessionName?: string
 }
 
 export async function callClaudeStreaming(
@@ -426,6 +435,9 @@ export async function callClaudeStreaming(
   // Pass existing CLI session ID if resuming (new sessions get it after first result)
   const resolvedCliKey = cliSessionKey(sid, resolvedModel)
   let existingCliSession = options?.dispatch ? undefined : cliSessionMap.get(resolvedCliKey)
+  // 6.58.2: decided before the pre-warmed session below stands in: a COS session that has no
+  // Claude session of its own yet starts one here, and only that one may be named.
+  const startsOwnCliSession = !existingCliSession
   callbacks.onStart?.(resolvedModel, sid, existingCliSession, {
     clientJobId: options?.clientJobId,
     generation: options?.generation,
@@ -531,7 +543,10 @@ export async function callClaudeStreaming(
   // Check if we have a prior CLI session for this COS session.
   // If not, use the pre-warmed session (eliminates 2-15s cold start on first query).
   // Restricted dispatch never steals the pre-warmed unrestricted session.
-  if (!options?.dispatch && !existingCliSession && preWarmedCliSessionId && resolvedModel === DEFAULT_MODEL) {
+  // 6.58.2: nor does a named New session (COS Control Work). The warmed session opens with the
+  // boot prompt "ready" under the glasses prompt; a session someone will open in the Claude app
+  // under its task's name starts clean.
+  if (!options?.dispatch && !options?.sessionName && !existingCliSession && preWarmedCliSessionId && resolvedModel === DEFAULT_MODEL) {
     // Only the default model consumes the pre-warmed session.
     // Hey Even (Haiku) cold-starts its own session to avoid model contamination.
     existingCliSession = preWarmedCliSessionId
@@ -576,6 +591,11 @@ export async function callClaudeStreaming(
     // Resume prior CLI session — reuses cached context, avoids cold start
     args.push('--resume', existingCliSession)
   }
+  // 6.58.2: name the session this COS session starts (never a Continue, never a dispatch), when
+  // the installed CLI takes --name. The `=` form keeps a name that starts with a dash a value.
+  if (startsOwnCliSession && !options?.dispatch && options?.sessionName && await claudeSupportsSessionName()) {
+    args.push(`--name=${options.sessionName}`)
+  }
 
   // Strip CLAUDECODE env var so claude -p doesn't think it's nested
   const env = { ...process.env }
@@ -856,6 +876,8 @@ export async function callClaudeStreaming(
 
   // ─── Process stdout ───
 
+  // 6.58.2: onNativeSession fires once per run.
+  let nativeSessionAnnounced = false
   proc.stdout.on('data', (chunk: Buffer) => {
     resetInactivity()
     buffer += chunk.toString()
@@ -871,6 +893,15 @@ export async function callClaudeStreaming(
       try {
         const event = JSON.parse(trimmed)
 
+        // 6.58.2: the first event that carries the session id (a hook or init line, before any
+        // answer text) links the run and the job to it. At completion the result's id is
+        // recorded as before, so the finished job names the session the result names.
+        if (!nativeSessionAnnounced && !options?.dispatch && typeof event.session_id === 'string' && event.session_id) {
+          nativeSessionAnnounced = true
+          updateClaudeRun(run.runId, { cliSessionId: event.session_id })
+          callbacks.onNativeSession?.({ cliSessionId: event.session_id })
+        }
+
         if (event.type === 'system' && event.subtype === 'init' && typeof event.model === 'string') {
           updateClaudeRun(run.runId, { resolvedModelId: event.model })
         } else if (event.type === 'stream_event') {

package/server/lib/claude-cli-support.ts

@@ -0,0 +1,37 @@
+import { execFile } from 'node:child_process'
+
+/**
+ * 6.58.2: does the installed Claude CLI take `--name`? A CLI that predates the option rejects
+ * it as unknown and the whole run fails, so the server asks `claude --help` once, in the
+ * background (it answers in about 50 ms on this Mac), and names a session only when the help
+ * lists the option. Any failure to ask is a no: the session then runs unnamed, as before 6.58.2.
+ */
+let sessionNameSupport: Promise<boolean> | null = null
+
+const HELP_TIMEOUT_MS = 5_000
+
+export function claudeSupportsSessionName(): Promise<boolean> {
+  if (!sessionNameSupport) {
+    sessionNameSupport = new Promise<boolean>(resolve => {
+      try {
+        execFile('claude', ['--help'], { timeout: HELP_TIMEOUT_MS, maxBuffer: 1024 * 1024 }, (error, stdout, stderr) => {
+          const supported = !error && helpListsNameOption(`${stdout}\n${stderr}`)
+          if (!supported) console.warn('[claude-bridge] this Claude CLI does not list --name; new sessions stay unnamed')
+          resolve(supported)
+        })
+      } catch {
+        resolve(false)
+      }
+    })
+  }
+  return sessionNameSupport
+}
+
+/** The help line reads `-n, --name <name>` on Claude Code 2.1.285. */
+export function helpListsNameOption(help: string): boolean {
+  return /(^|[\s,])--name[\s=<[]/m.test(help)
+}
+
+export function resetClaudeCliSupportForTests(): void {
+  sessionNameSupport = null
+}

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

@@ -39,6 +39,10 @@ export interface QueryJobRunnerCallbacks {
   /** True only when provider ownership was durably fsynced for this active
    * generation. False means cancel/shutdown won; no prompt may be written. */
   onProviderProcess: (linkage: QueryJobProviderLinkage) => boolean | Promise<boolean>
+  /** 6.58.2: a link the provider names mid-run (the Claude session id). Persisted only while
+   * the job runs (like every link update it restamps providerOwnershipConfirmedAt); unlike
+   * onProviderProcess it gates nothing, and a job that already ended keeps what it had. */
+  onLinkage?: (linkage: QueryJobProviderLinkage) => Promise<void>
   onChunk: (text: string) => void
   onToolStatus: (text: string) => void
   onActivityLine: (line: { kind: 'input' | 'output'; text: string }) => void
@@ -340,6 +344,9 @@ export class QueryJobCoordinator {
         })
       },
       onProviderProcess: linkage => this.providerProcessReady(active, linkage),
+      onLinkage: linkage => this.enqueueCallback(active, async () => {
+        await this.store.updateLinkage(active.jobId, linkage)
+      }),
       onChunk: (text) => { this.queuePartial(active, text) },
       onToolStatus: (text) => {
         if (active.request.activityToolMode === 'off') text = 'Processing...'

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

@@ -234,6 +234,8 @@ const runner: QueryJobRunner = async ({ jobId, turnId, request, signal, callback
               ? { ollamaRunId: metadata.runId }
               : { codexRunId: metadata.runId }),
       }),
+      // 6.58.2: the provider's own session id, as soon as it names it (Claude: first stream event).
+      onNativeSession: linkage => { void callbacks.onLinkage?.({ provider: 'claude', cliSessionId: linkage.cliSessionId }) },
       onChunk: text => { callbacks.onChunk(text) },
       onToolStatus: toolName => {
         const message = request.activityToolMode === 'off'
@@ -349,6 +351,7 @@ const runner: QueryJobRunner = async ({ jobId, turnId, request, signal, callback
       attachmentPromptBlock: resolvedAttachments.promptBlock,
       sessionLockHeld: true,
       ...(request.dispatch ? { dispatch: request.dispatch } : {}),
+      ...(request.sessionName ? { sessionName: request.sessionName } : {}),
     },
   )
 }