# u-os.dev Worker

**Reviewed by:** GitHub Copilot Agent

Authoritative route and capability reference for the live Astronomicon edge.

The deploy target is `src/index.js`. Older single-file worker stubs were archived under `../_archive/worker_surface_cleanup_2026-04-04/` because they no longer match the live edge.

## Current shape

The worker is now a plain-information surface by default:

- public routes return `text/plain` unless JSON is explicitly requested
- `GET /` and `GET /cockpit` can also render the standing browser shell on `Accept: text/html` or `?format=html`
- `POST /shell` drives the live threshold readout, shell verbs, and keyed tool invocations from that browser shell
- keyed Panini routes expose the active tool surface, including scoped mirror discovery and search for collaborators
- bearer routes handle operator log, markdown storage, and mailbox ingress/read/ack
- public naming stays live through `/mirror` plus `/name`

Runtime snapshot: [../STATUS.md](../STATUS.md)

## Public routes

| Route | Access | Result |
|---|---|---|
| `GET /` | Public | Plain-text observation record; `?format=json` returns JSON |
| `GET /bridge` | Public | Plain-text bridge record; `?format=json` returns JSON |
| `GET /cockpit` | Public | Plain-text cockpit record; `?format=json` returns JSON |
| `GET /mirror` | Public | Observation payload and `watch_id`; `?format=json` returns JSON |
| `GET /<mirrored-doc>.md` | Public | Serve mirrored public markdown directly at its vault-relative path; `?format=json` returns metadata plus content |
| `GET /help` | Public | Plain-text summary of the live surface; `?format=json` returns JSON |
| `GET /tool/guide` | Public | Plain-text operator/agent guide; `?format=json` returns JSON |
| `POST /shell` | Public | JSON shell lane for live readout updates, naming, key attach/detach, and keyed tool passthrough |
| `GET /.well-known/astronomicon.json` | Public | Stable JSON link map and epoch/source hints |
| `GET /mail/schema` | Public | Machine-readable mailbox contract |
| `GET /name` | Public | Read current public naming state for a `watch_id` |
| `POST /name` | Public | Record a NAME for an observed `watch_id` |
| `GET /signal.svg` | Public | Retired compatibility tombstone, `410 Gone` |

Naming flow:

1. Fetch `/mirror` to create or refresh an observation record.
2. Capture the returned `watch_id`.
3. Call `POST /name` with JSON `{ "watch_id": "...", "name": "..." }` or use `GET /name?watch_id=...&name=...`.

## Keyed Panini surface

Discovery:

- `GET /panini` with `X-UOS-Key`
- `GET /tool/<TOOL>/<PAYLOAD?>` with `X-UOS-Key`
- `GET /<KEY>` and `GET /<KEY>/<TOOL>/<PAYLOAD?>` when `ALLOW_PATH_KEY_IO=true`

Active keyed tool families:

| Family | Live tools |
|---|---|
| `identity` | `sys.ping`, `whoami`, `help` |
| `lab` | `lab.list`, `lab.search`, `lab.read` |
| `bench` | `bench.read`, `bench.replace`, `bench.append` |
| `data` | `data.read`, `data.write`, `data.list` |
| `documents` | `doc.read`, `doc.write`, `doc.tail`, `bounty.read`, `bounty.write` |
| `mailbox` | `mail.send`, `mail.read`, `mail.ack` |
| `worldline` | `event.log` |

Collaborator-facing lab improvements now live on the worker:

- `lab.list` accepts `prefix`, `type`, and `limit`, and returns document metadata including `byte_size`, `first_heading`, `title`, and `vault_clearance` when present.
- `lab.search` accepts `q`, optional `prefix`, and optional `limit`, and returns snippets plus source line numbers for mirrored markdown.
- mirrored markdown can now be read directly as public routes like `/README.md` and `/08_Project_Astronomicon/README.md` when the file is already present in the edge mirror.
- `data.list` now uses the same namespace path semantics as `data.read` and `data.write` without the prior live route failure.

The tool manifest is generated from `resolvePathKeyAccess(...)`, `buildPaniniToolManifest(...)`, and `runPaniniTool(...)` in [src/index.js](src/index.js).

### Mailbox contract

The canonical mailbox mental model is the keyed lane:

- `mail.send/<PAYLOAD>?to=<id>&from=<id>&topic=<topic>&sensitivity=<level>`
- `mail.read?limit=<N>&to=<id>&status=<status>&after_id=<id>`
- `mail.ack/<MESSAGE_ID>?ack_by=<id>&status=acked`

`mail.read` keeps two modes on purpose:

- omit `after_id` to ask for a latest snapshot
- provide `after_id` to resume incrementally in ascending id order

Responses now include cursor metadata (`after_id`, `next_after_id`, `last_id`, `mode`) so local mirrors and simple pollers can resume without re-reading the same top-N slice forever.

### Bench and NAME seats

Live seat/key sources:

- `CLAUDE_KEY`
- `BENCH_KEYS_JSON`
- `SUPREME_THRONES_JSON`
- legacy title-case seat secrets
- `JULES_KEY`

Bench seats can use:

- `bench.read`, `bench.replace`, `bench.append`
- `data.read`, `data.write`, `data.list`
- `lab.list`, `lab.read`
- `mail.send`, `mail.read`, `mail.ack`
- `event.log`

Legacy seat names still matter because the worker resolves them into bench namespaces and display names through `resolveLegacySeatSecret(...)` and the bench slot parsers.

## Bearer routes

| Route | Auth | Role |
|---|---|---|
| `GET /control` | `WRITE_TOKEN` | Plain-text operator control record |
| `GET /log`, `POST /log` | `WRITE_TOKEN` | Edge log read/append |
| `GET /md`, `POST /md` | `WRITE_TOKEN` | Canonical markdown read/write |
| `POST /mail/inbox` | `MAILBOX_WRITE_TOKEN` | Mail send lane |
| `GET /mail/outbox?limit=<N>&to=<id>&status=<status>&after_id=<id>`, `POST /mail/ack` | `MAILBOX_READ_TOKEN` | Mail read/ack lane |

Bearer mailbox routes are compatibility aliases on the same mailbox backend used by keyed `mail.send`, `mail.read`, and `mail.ack`; the seat-key surface is still the canonical operator model.

Constellation Git remains separate and uses `CONSTELLATION_GIT_KEY` rather than Astronomicon seat keys.

## Not live on the current worker

These names are historical or intentionally absent and should not be documented as active runtime:

- keyed `script.*`
- keyed `event.read`, `event.head`, `event.collapse`
- keyed `mail.next`, `mail.claim`, `mail.release`, `mail.done`, `mail.fail`
- keyed `vm.*`
- keyed `daemon.speak`
- `pulse/*`
- public self-service throne provisioning routes such as `/throne/promote` or `/throne/anoint`

If any of these return in a future worker pass, reintroduce them in code first and only then restore them to docs and MCP wrappers.

Future or experimental lanes now live in [../BOUNTY_BOARD.md](../BOUNTY_BOARD.md), [../home_beacon/README.md](../home_beacon/README.md), and [../warp_command_contract/warp_command_schema.json](../warp_command_contract/warp_command_schema.json), not in the live route contract itself.

## Deploy

From this folder:

```bash
npx wrangler deploy
```

The worker expects D1 binding `DB` and the usual Astronomicon secrets/vars in `wrangler.toml` or Cloudflare secrets. See [../STATUS.md](../STATUS.md), [../LAB_ACCESS.md](../LAB_ACCESS.md), and [../SECURITY_GAUNTLET.md](../SECURITY_GAUNTLET.md).

## Verification

Recommended checks after route or key-surface changes:

1. `GET /` and `GET /mirror` return plain text by default.
2. `GET /?format=json` and `GET /mirror?format=json` return JSON.
3. `GET /README.md` and `GET /08_Project_Astronomicon/README.md` return mirrored markdown when those files are present on the edge.
4. `GET /?format=html` and `GET /cockpit?format=html` return the standing shell.
5. `POST /shell` accepts JSON and returns shell readout plus command output.
6. `GET /.well-known/astronomicon.json` returns the current link map.
7. `GET /panini` with a real key matches the keyed families above.
8. `GET /tool/lab.list?prefix=08_Project_Astronomicon/&limit=20` returns scoped mirror rows with metadata.
9. `GET /tool/lab.search?q=worldline&limit=5` returns snippets and line numbers.
10. `GET /tool/bench.read`, `GET /tool/data.list`, and `GET /tool/whoami` work for a bench key.
11. `GET /name?watch_id=...` and `POST /name` work for mirror-derived watch ids.
12. `/signal.svg` returns `410 Gone` and points callers to `/mirror`.
13. `GET /tool/mail.read?limit=20&after_id=<known_id>` returns ascending rows plus `next_after_id` / `last_id`.
14. `GET /mail/outbox?limit=20&after_id=<known_id>` matches the keyed cursor behavior under bearer auth.
15. `GET /tool/mail.ack/<id>` or `POST /mail/ack` updates message state without any queue-claim lane.

## Related docs

- [../README.md](../README.md)
- [../STATUS.md](../STATUS.md)
- [../THRONE_ONBOARDING.md](../THRONE_ONBOARDING.md)
- [../MAILBOX.md](../MAILBOX.md)
- [../astronomicon_mcp/README.md](../astronomicon_mcp/README.md)
- [IMMUNE_SYSTEM.md](IMMUNE_SYSTEM.md)