@cohortapp/agent-sdk 2.11.15 → 2.13.0

package/docs/guides/front-door-session.md

@@ -0,0 +1,313 @@
+# The front-door session — operator guide
+
+Every seat runs two launchd jobs and one brain. This page is for the person
+who has to look after a seat: what is running, how to look at it, how to stop
+and restart it, and how to read `maestro session status` and `maestro doctor`.
+The design is `docs/superpowers/specs/2026-09-08-front-door-session-design.md`;
+this is the operator's view of §3 of it.
+
+## 1. What runs on a seat
+
+```
+launchd (gui/<uid>)
+├── ai.maestro.<first>-daemon    KeepAlive   scripts/daemon/maestro-daemon.mjs   ← plumbing
+│     the one SSE stream to os.cohortapp.com · presence beat every 30 s ·
+│     Slack/Telegram/WhatsApp/orgmail adapters · classify + hydrate inbound
+│     → state/inbox/cohort/*.yaml · cadence bus
+└── ai.maestro.<first>-session   KeepAlive   scripts/session/supervisor.sh       ← brain
+      screen -D -m -S maestro-<first>  claude --name <first>-main --resume <id> …
+        └── a persistent monitor inside the session: scripts/session/feed.mjs
+              heartbeat every 15 s · tails the inbox + handoffs
+              → one JSON line per event → the session acts
+```
+
+**The daemon** is the plumbing and is unchanged in what it holds: the single
+allowed SSE connection per seat with its durable cursor, the presence beat,
+the channel adapters, the directedness/self-echo/dedupe pipeline. It never
+reasons.
+
+**The session** is the agent's front door. It is a normal interactive Claude
+Code session (`claude --name <first>-main`) kept alive inside a terminal
+multiplexer (`screen` ships with macOS; `tmux` is preferred when installed).
+Every inbound Cohort event — DMs, space messages, threads, inbound email,
+comments on files and boards, huddle calls — reaches it as a JSON line from
+the feed, and it either answers in the same turn, runs a dynamic workflow, or
+hands the heavy work to a peer session it spawns. Meaty asks go onto the
+relevant Board; the session works its board items proactively when idle.
+
+**Who receives inbound.** While the session's heartbeat
+(`state/session/heartbeat.json`, written every 15 s) is fresher than 90 s, the
+daemon leaves Cohort inbox items in place for the session to claim and writes
+escalate/guarded cadence ticks as handoffs (`state/session/handoffs/`). When the
+heartbeat is stale, the daemon falls back to today's `claude --print` dispatch
+for both. Liveness is measured, never assumed, so nothing is dropped in either
+direction. The beat reports which lane is active: `machine.frontDoor`
+(`"session"` when the job exists, `"daemon"` otherwise) and
+`machine.sessionLive`. They ride `machine` — the beat field hq stores as an
+open record — rather than `session`, which hq validates strictly and which
+stays `null` while no work session runs.
+
+**Exactly one.** The supervisor takes an O_EXCL lock (`lib/singleton.js`,
+name `session`); a second supervisor exits 0 so launchd does not thrash. An
+orphaned mux session with no lock holder is adopted, not duplicated.
+
+**Continuity.** The session id is stable (`state/session/main-session.json`);
+every relaunch is `claude --resume <id>`, so the session keeps its memory
+across restarts and reboots. If a resume fails within 20 s the supervisor
+rotates to a fresh id (at most three times an hour, then it sleeps).
+
+**Relaunch only on death.** The supervisor runs the multiplexer in the
+foreground and exits 75 when the session ends; launchd's
+`KeepAlive {SuccessfulExit:false}` + `ThrottleInterval 30` bring it back.
+There is no cron, no periodic kill, no memory watchdog SIGTERM for the main
+session (`memory-watchdog.sh` spares `<first>-main` and the feed).
+
+**Auth.** The supervisor sources `.env` the same way `launchd-wrapper.sh`
+does, so the seat's `CLAUDE_CODE_OAUTH_TOKEN` (from `claude setup-token`)
+reaches `claude`. The keychain login is not relied on.
+
+## 2. Install and first start
+
+```bash
+cd ~/<agent-name>
+maestro session install     # renders + bootstraps ai.maestro.<first>-session
+maestro session status      # expect: lock held · mux maestro-<first> · heartbeat N s ago (live)
+```
+
+`init-agent.sh` and `generate-plists.sh` render the same plist; `install`
+is the idempotent front door for it. It needs the SDK installed **globally**
+(`npm i -g @cohortapp/agent-sdk`) because the session, like any Claude Code
+session on the seat, resolves `maestro` and `cohort-mcp` from PATH — `maestro
+doctor` checks both.
+
+## 3. How to attach
+
+```bash
+maestro session attach      # opens the live session in this terminal
+```
+
+Detach with `Ctrl-A D` (screen) or `Ctrl-B D` (tmux). Detaching does not stop
+anything. You are looking at the agent's own working session: type into it
+the way you would into any Claude Code session, but remember that whatever it
+sends outbound goes through the send-gate and the persona audit like any
+other turn. Over SSH this is the same command; Tailscale SSH
+(`scripts/setup/configure-macos.sh --tailscale-ssh`) is how an operator
+reaches a seat.
+
+## 4. How to stop, start and restart
+
+| You want | Run | What happens |
+| --- | --- | --- |
+| Restart on the current code (or after an upgrade) | `maestro session restart` | writes `state/session/restart-requested`; the session finishes its turn, exits the mux, the supervisor exits 75, launchd relaunches it with `--resume` |
+| Stop it and keep it stopped | `maestro session stop` | `launchctl bootout` of the session job; the daemon's `--print` lane takes over inbound within 90 s |
+| Start it again | `maestro session start` | `launchctl bootstrap` of the job |
+| Stop the whole seat | `touch .emergency-stop` | daemon exits clean and stays down; stop the session separately with `session stop` |
+
+Never `launchctl kickstart -k` the session job from a script or a cadence:
+it is long-lived interactive state. The hourly autoupdate job knows this — it
+restarts the daemon and health-gates it, but for the session it only writes
+`state/session/upgrade-notice.json`; the session restarts itself at an idle
+moment via `maestro session restart` and comes back on the new code.
+
+One consequence of `maestro upgrade` reconciling launchd (§4a): every
+generated job that is installed but **not loaded** is bootstrapped again on
+the next upgrade, the session job included. `maestro session stop` therefore
+holds until the next hour's autoupdate lands a new version; to keep a seat's
+session down for longer, use the autoupdate kill-switch
+(`touch ~/.maestro-no-autoupdate`) or remove the session plist. The
+kill-switch and the emergency stop (`.emergency-stop`, `state/EMERGENCY_STOP`)
+also **hold** the launchd step of a by-hand `maestro upgrade`: plists are
+still written, nothing is bootstrapped, and each held row says which marker
+held it. `scripts/session/supervisor.sh` refuses to start under an emergency
+stop as well (exit 0, so launchd does not relaunch it), which covers the one
+path the hold cannot — the next login re-bootstrapping `~/Library/LaunchAgents`.
+
+## 4a. How a seat upgrades itself
+
+The hourly `ai.maestro.<first>-autoupdate` job
+(`scripts/local-triggers/autoupdate.sh`) installs a strictly-newer SDK into
+the agent dir and runs **that package's** `maestro upgrade`. So on the first
+hop from any older version it is the *new* `upgrade` that runs, and it puts
+the seat on the new architecture by itself — the "seat reconcile" steps at
+the end of every non-dry upgrade, each fail-open and each reported in the
+summary and in `.maestro/upgrade-result.json` `{from, to, at, steps}`:
+
+| Step | What it does |
+| --- | --- |
+| `plists` | `scripts/local-triggers/generate-plists.sh`, unconditionally |
+| `launchd` | installs every generated plist missing from `~/Library/LaunchAgents` (mode 600, `launchctl bootstrap gui/<uid>`; `launchctl load` only when launchd does not already hold the label) — this is how the session job reaches an existing seat; **rewrites** changed ones (file only — launchd keeps the loaded definition until the next login or an explicit `bootout` + `bootstrap`; nothing is ever `kickstart`ed, least of all the `-autoupdate` job this upgrade runs inside); bootstraps installed-but-unloaded ones; never `bootout`s anything, orphans are only reported. "Loaded" is measured in the GUI domain (`launchctl print gui/<uid>`), so the answer is right over ssh too. Held entirely (files written, nothing started) under an emergency stop or the autoupdate kill-switch |
+| `globalSetup` | `maestro global-setup` — identity block, cohort MCP server, session settings, global skills |
+| `globalInstall` | `npm i -g @cohortapp/agent-sdk@<this version>` so `maestro` / `cohort` / `cohort-mcp` on PATH match the agent dir (`MAESTRO_SKIP_GLOBAL_INSTALL=1` skips) |
+| `verify` | the `maestro upgrade --verify` report, below |
+
+autoupdate then kickstarts the daemon and health-gates it: the daemon
+process must be alive with a fresh `org-mesh connected` / `[daemon] Running`
+line, and — when a `-session` plist was generated — the session label must be
+in `launchctl list` with a live supervisor process. A missing session is
+logged as `reconcile-failed` and does **not** roll back (the daemon's
+`--print` lane is the front door meanwhile; doctor says what to do). Every
+launchd and `pgrep` question is scoped to *this* agent (`ai.maestro.<first>-*`
+and its own agent dir), so two seats on one Mac never gate on — or restart —
+each other.
+
+An unhealthy daemon **rolls back**: the previous SDK is reinstalled into the
+agent dir and *that* package's `upgrade` runs, the global install is put back
+to the previous version, and a `-session` job that **this run** installed is
+booted out and its plist removed (a pre-existing session job is the
+operator's and is never touched). What a rollback does *not* undo: files the
+new version added that the old manifest never listed stay on disk, and the
+old `upgrade` rewrites the manifest without `sdkVersion` — `maestro doctor` /
+`upgrade --verify` report both on the next healthy hop. A version that failed
+the health gate here is then **held**: `state/autoupdate/last.json`
+(`{from, to, at, ok, healthy, reason}`) is read at the top of every run and a
+`to` it records as `unhealthy-rolled-back` / `rollback-unhealthy` is not
+retried for 24 h (`MAESTRO_AUTOUPDATE_FAILED_HOLD_S`; delete the file to retry
+now) — without that memory a bad release would install, reconcile, roll back
+and refresh the global install twice an hour until someone touched the
+kill-switch. The beat reports `last.json` as `machine.upgrade` next to
+`sdkVersion` in the Fleet view, so a held seat shows its failure and its age.
+Two runs cannot overlap (`state/locks/autoupdate/`, stale after two hours),
+and `npm view` / `npm install` are retried three times with backoff.
+
+`maestro upgrade --verify` (also printed by `maestro doctor`) answers "is
+this seat wholly on one version?": the global bin, the agent dir's package,
+`.maestro/shipped-manifest.json`, the running daemon
+(`state/dashboards/daemon-health.yaml` `sdk_version` — the version of the
+*copied* `scripts/daemon` the process started on, read from the manifest
+before `node_modules`, so a daemon restarted between autoupdate's `npm
+install` and the file merge does not report the version it is not yet
+running), every generated plist installed **and** loaded (in the GUI domain),
+and the global-setup markers. It exits 1 on any mismatch and names the fix
+per row.
+
+## 5. How to read status
+
+`maestro session status` prints:
+
+- **lock** — who holds `state/session.lock` (pid, identity) or "free";
+- **mux** — `maestro-<first>` present or not, which multiplexer;
+- **session id** and how many times it has been resumed;
+- **heartbeat** — age in seconds and `live` / `stale` against the 90 s bar;
+- **open handoffs** — cadence ticks waiting in `state/session/handoffs/`;
+- **peers** — sessions it has spawned (`maestro session peers` lists them
+  and prunes dead ones).
+
+`--brief` gives the one-liner the SessionStart hook shows every new session.
+
+`maestro doctor` adds the fleet view of the same facts and a remedy per line:
+the Claude auth mode and what `claude auth status` reports (the CLI reports
+that a credential is present — it does not validate a token; a bad token
+shows up on the first real spawn, in `logs/sessions` and on the beat as
+`relogin_required`); where each Cohort value
+came from (`config/org.yaml` beats the environment beats `.env`) and which
+values lost; whether `COHORT_ORG_ID` is the org's ID or its slug; the global
+SDK install and whether it is current; Tailscale SSH; and the session job —
+installed / loaded / heartbeat live. The rungs read, in order:
+
+```
+✓ Claude auth: subscription OAuth token (CLAUDE_CODE_OAUTH_TOKEN + MAESTRO_PREFER_SUBSCRIPTION_AUTH=1)
+✓ Claude auth (subscription — OAuth token): CLI reports a login for the token; the token itself is only proven by a real spawn (a rejection shows in logs/sessions and on the beat as relogin_required)
+✓ Cohort base ← org.yaml (https://os.cohortapp.com)
+✓ Cohort orgId ← org.yaml (org_default_adaptic)
+⚠   Cohort orgId: org.yaml wins over .env COHORT_ORG_ID=adaptic — the losing value is ignored
+✓ COHORT_ORG_ID is the org ID (org_default_adaptic) — matches the server
+✓ @cohortapp/agent-sdk 2.12.0 installed globally (npm latest 2.12.0)
+✓ Tailscale SSH is on (RunSSH=true)
+✓ Main session job ai.maestro.ethan-session loaded, heartbeat live (12 s ago)
+```
+
+From the Fleet view in Cohort the same seat shows `hostname`, `tailnetIp`,
+`sdkVersion`, `frontDoor` and `sessionLive` off its beat — `sdkVersion` per
+seat is how a fleet-wide rollout is confirmed after a publish.
+
+## 6. What the session does with an event
+
+Each line from the feed is one unit of work. The policy the session follows
+(skill `inbound-triage`):
+
+1. **Answer in the turn** when the ask is answerable in one reply from what
+   the agent already knows. `maestro inbox reply <id>` routes through the same
+   send-gate and audit as every other outbound path.
+2. Otherwise **acknowledge in-channel in the same turn**, file the ask on the
+   conversation's board (`maestro board track <inbox-id> --stage accepted
+   --title … --why …`), and either run the work as a dynamic workflow inside
+   the session or spawn a peer (`maestro session spawn --name <slug> "<prompt>"`).
+   Report back in-channel and `board track --stage done` on completion.
+3. **Handoffs** (`{"type":"handoff", …}`) are cadence ticks the daemon has
+   handed over; the session runs the rendered prompt and `maestro session ack
+   <tickId>`. A handoff not acked within 30 minutes is re-enqueued by the
+   daemon on the legacy lane, so a wedged session cannot starve a cadence.
+4. A claimed inbox item neither replied nor done within 20 minutes is
+   re-opened by the daemon's assurance sweep and re-emitted (or dispatched
+   legacy if the session is no longer live).
+
+To the humans it talks to, the agent is one persona. Peer sessions and
+sub-agents are "my team" / "a colleague"; the persona audit hook blocks any
+outbound text that says otherwise.
+
+## 6a. DESIGN.md and the parallelism directive
+
+Two things reach every prompt a seat runs, and neither is left to a session to
+remember.
+
+**DESIGN.md and PRODUCT.md.** `maestro design sync` reads the workspace's SAVED
+brand foundation (`branding.getFoundation` — never a draft) and renders it into
+`DESIGN.md` (colour, type, radius, spacing and component tokens, in the
+google-labs-code/design.md frontmatter shape, with `{colors.primary}`-style
+refs) and `PRODUCT.md` (positioning, voice, tone, lexicon) in the agent dir,
+plus the raw snapshot at `state/design/foundation.json`. The daemon re-runs the
+same code path every 15 minutes and rewrites the files when the foundation's
+version has moved, so a seat's design files follow the humans editing the
+foundation without anyone re-running a command.
+
+Both files are GENERATED. An edit to them is overwritten on the next sync;
+foundation changes are human-gated and go through the `design_propose_change`
+tool. The write is byte-idempotent — an unchanged foundation touches no mtime,
+so the poll never churns the tree, and the render stamp is kept per output
+directory so a `--out` run and the daemon's poll of the agent dir cannot
+invalidate each other's files. Every posture here is fail-open: an un-enrolled
+seat writes nothing, and a failed read keeps the last-good files rather than
+blanking them. Design skills are told to read `$AGENT_ROOT/DESIGN.md` when the
+working directory is not the agent dir.
+
+A workspace that has never SAVED a foundation writes nothing at all, and the
+CLI says why. hq answers such a read with its own product defaults and
+`unversioned: true` — a complete, plausible palette that is nobody's brand — and
+a DESIGN.md rendered from it would ground every design skill on the seat in the
+wrong palette with a generated file's authority behind it.
+
+    maestro design sync                # into the agent dir
+    maestro design sync --out docs/brand --json
+
+**The parallelism directive.** `lib/prompts/parallelism.mjs` holds one constant,
+prepended exactly once (it is idempotent, and the seams compose) to every
+peer-session prompt by `maestro session spawn`, to every sub-session prompt
+built by the daemon's prompt-builder, and to every cadence trigger prompt on the
+escalate/guarded lane — both when a sub-session is spawned for it and when a
+live main session is handed it (`renderCadencePromptBody`, one seam for both, so
+the two lanes send the same bytes). It grants the standing permission to
+dispatch independent tasks as one parallel batch, and carries the safety rule
+that makes that safe on a shared checkout: check the planned file scope first,
+and never assign two agents to edit the same file — sequence or re-scope
+instead. Sessions ran plans strictly serially before it existed, because
+nothing in the prompt had ever said they need not.
+
+## 7. Files
+
+| Path | What |
+| --- | --- |
+| `state/session/heartbeat.json` | `{pid, ppid, sessionId, name, ts, feedVersion}`, every 15 s |
+| `state/session/main-session.json` | `{sessionId, createdAt, resumes}` — the stable id |
+| `state/session/handoffs/<tickId>.json` | cadence ticks waiting for the session; `done/` when acked |
+| `state/session/peers.json` | spawned peer sessions |
+| `state/session/feed-seen.json` | the feed's seen-set (no replay after a monitor restart) |
+| `state/session/restart-requested` | `maestro session restart` marker |
+| `state/session/upgrade-notice.json` | written by autoupdate; the session restarts itself when idle |
+| `state/session.lock` | the singleton lock |
+| `state/inbox/cohort/*.yaml` | inbound items (`.dispatched` = claimed, `.processed` = done, `.deferred`) |
+| `DESIGN.md`, `PRODUCT.md` | generated from the workspace brand foundation by `maestro design sync` and the daemon's 15-minute poll; edits are overwritten |
+| `state/design/foundation.json` | `{fetchedAt, renderedAt, version, versionLabel, foundation}` — the last synced foundation; the refresh gate reads it back |
+| `state/org/board-mine.json` | `{ts, items}` — the daemon's 5-minute cache of hq `board.mine` (this agent's items across every board); read by the SessionStart primer, the `session_status` MCP tool and `maestro board mine` |
+| `.maestro/upgrade-result.json` | `{from, to, at, steps:{plists, launchd, globalSetup, globalInstall, verify}}` — what the last `maestro upgrade` did to the seat |
+| `state/autoupdate/last.json` | `{from, to, at, ok, healthy, reason}` — the last autoupdate attempt; the beat's `machine.upgrade` |
+| `state/locks/autoupdate/` | autoupdate's overlap lock (pid inside; stale after 2 h) |

package/docs/guides/mac-mini.md

@@ -1,10 +1,15 @@
 # Mac mini bring-up — an always-on Cohort agent, end to end
 
 The one-page operator runbook: from a boxed Apple-silicon Mac mini to a fully
-enrolled AI colleague on `os.cohortapp.com` — messaging, board work, and a real
-workspace email address — verified by `cohort doctor`. OS-level hardening and
-fleet mechanics live in the deeper runbook: [Mac Mini Bootstrap](../runbooks/mac-mini-bootstrap.md)
-(this page links it rather than duplicating it).
+enrolled AI colleague on `os.cohortapp.com` — messaging, board work, a real
+workspace email address and an always-on **main session** as its front door —
+verified by `cohort doctor`. OS-level hardening and fleet mechanics live in the
+deeper runbook: [Mac Mini Bootstrap](../runbooks/mac-mini-bootstrap.md); the
+session itself is described in [Front-door Session](front-door-session.md)
+(this page links both rather than duplicating them).
+
+The sequence, in one line: **token → create → setup → init-agent →
+session install → tailscale-ssh → doctor.**
 
 ## 1. Hardware / prereqs
 
@@ -22,13 +27,27 @@ sudo pmset -a sleep 0 displaysleep 0 autorestart 1
 xcode-select --install
 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
 brew install node@20 git python@3.12
-npm i -g @anthropic-ai/claude-code && claude login   # Max subscription — the daemon
-                                                     # strips API keys so sub-sessions
-                                                     # ride keychain OAuth
-npm i -g @cohortapp/agent-sdk
+npm i -g @anthropic-ai/claude-code
+npm i -g @cohortapp/agent-sdk        # GLOBAL on purpose: every Claude Code session on
+                                     # this seat needs `maestro` + `cohort-mcp` on PATH
 ```
 
-## 3. Create the agent repo
+## 3. The Claude token — one auth story for the whole seat
+
+Every `claude` the seat runs (the daemon's `--print` lane, the main session,
+cadence sub-sessions) authenticates with a **long-lived subscription OAuth
+token**, never the interactive keychain login (which expires headlessly and
+has stranded seats before). Mint it on **any** machine where you are logged
+in to Claude Code with the Max subscription — your laptop is fine:
+
+```bash
+claude setup-token          # prints one token; copy it
+```
+
+Keep it in your clipboard / password manager for step 5. It is per seat: mint
+a fresh one whenever `cohort doctor` reports the token as rejected.
+
+## 4. Create the agent repo
 
 ```bash
 cohort create <agent-name>
@@ -40,7 +59,7 @@ including `.mcp.json`, which exposes the `cohort-mcp` org tool surface to
 interactive Claude sessions, and the PreToolUse hooks that keep its outbound
 writes on the CLI lane).
 
-## 4. Enroll against `https://os.cohortapp.com`
+## 5. Enroll against `https://os.cohortapp.com` — and paste the token
 
 Two lanes — pick one:
 
@@ -49,9 +68,14 @@ Two lanes — pick one:
 
   ```bash
   export COHORT_API_KEY=nlk_…  COHORT_ORG_ID=<org-ID>  COHORT_AGENT_ID=<member-slug>
-  cohort setup
+  cohort setup                       # the model section (order 30) asks for the token from step 3
+  # headless / one-paste bootstrap: the token comes from the environment instead of a prompt
+  CLAUDE_CODE_OAUTH_TOKEN=<token> cohort setup --headless
   ```
 
+  Either way `.env` ends up with `CLAUDE_CODE_OAUTH_TOKEN` +
+  `MAESTRO_PREFER_SUBSCRIPTION_AUTH=1`, mode 600. No `ANTHROPIC_API_KEY`.
+
   > **`COHORT_ORG_ID` is the org's ID, not its slug** — this line said
   > `<org-slug>` and that would 401 every call. The value rides as `x-org-id`
   > (`lib/org/client.mjs#baseHeaders`) and hq compares it with strict equality
@@ -68,12 +92,13 @@ Two lanes — pick one:
 - **Pre-auth pairing**: `cohort pair <code>` → an org admin approves the
   handshake in Cohort (`pairing.request`/`pairing.approve`).
 
-## 5. Wizard
+## 6. Wizard
 
-`cohort setup` walks the sections in order — the org trio is:
+`cohort setup` walks the sections in order — the auth section and the org trio are:
 
 | Order | Section | What it does |
 | --- | --- | --- |
+| 30 | `model` | Claude auth — **`oauth-token` by default**: paste the `claude setup-token` output; writes `CLAUDE_CODE_OAUTH_TOKEN` + `MAESTRO_PREFER_SUBSCRIPTION_AUTH=1`, chmods `.env` 600 |
 | 75 | `org` | endpoint + token (the enrollment SoT) |
 | 76 | `messaging` | messaging.read/write + calling.write scopes, home channels |
 | 77 | `orgmail` | **workspace mailbox** — writes `config/orgmail.yaml` |
@@ -82,28 +107,65 @@ For 77 to go live, an admin must have verified a domain and assigned this
 agent a mailbox in Cohort → Settings → Email first (the wizard's verify step
 probes `email.inbox` and WARNS until then — it never blocks setup).
 
-## 6. Always-on (launchd)
+## 7. Always-on (launchd): the daemon, then the main session
 
 ```bash
-scripts/setup/init-agent.sh     # deps → state dirs → generate-plists.sh → launchctl load
+scripts/setup/init-agent.sh     # deps → state dirs → generate-plists.sh → launchctl bootstrap
+maestro session install         # the front-door main session job (KeepAlive)
+maestro session status          # lock holder, mux name, heartbeat age — expect "live"
 launchctl list | grep ai.maestro
 ```
 
-Expect the daemon plus the cadence triggers; the daemon plist is KeepAlive
-`{SuccessfulExit:false, Crashed:true}` so it restarts on crash but respects a
-clean stop.
+Expect the daemon, the **session**, the cadence triggers and the hourly
+autoupdate job. The daemon plist is KeepAlive `{SuccessfulExit:false,
+Crashed:true}`; the session plist is KeepAlive `{SuccessfulExit:false}` with a
+30 s throttle — it relaunches only on death, never on a schedule. Once the
+session's heartbeat is live the daemon stops spawning `--print` sessions for
+Cohort inbox items and hands them to the session instead; if the heartbeat
+goes stale (> 90 s) the daemon falls back to its own lane, so nothing is ever
+dropped. `maestro session attach` opens the live session in your terminal
+(`Ctrl-A D` / `Ctrl-B D` detaches); see [Front-door Session](front-door-session.md).
+
+## 8. Remote operator access — Tailscale SSH
+
+```bash
+scripts/setup/configure-macos.sh --tailscale-ssh   # tailscale set --ssh + Remote Login on
+```
+
+This is what makes every later step remote (`ssh <agent-user>@<tailnet-host>`
+from an operator machine, no `authorized_keys` to manage). Allow it in the
+tailnet ACL once for the fleet; `cohort doctor` warns while it is off.
 
-## 7. Verify — `cohort doctor` is the gate
+## 9. Verify — `cohort doctor` is the gate
 
 ```bash
 cohort doctor
 ```
 
-All green includes the **Cohort connectivity** block: enrollment resolved →
-directory reachable (latency) → protocol version aligned (the server's
-`x-org-protocol` header; a drift warning means run `cohort upgrade`) → **key
-paired to a workforce member** (the `messaging.channels` gate) → **workspace
-mailbox reachable** (when `config/orgmail.yaml` exists).
+All green includes, in this order:
+
+- **Claude auth** — the mode in effect (`subscription OAuth token` is the
+  expected line) and what `claude auth status` reports. The CLI reports that
+  a credential is PRESENT — it answers "logged in" for any token value — so a
+  bad token is only caught by the first real spawn (`logs/sessions`, and the
+  beat flips to `relogin_required`); a `claude -p "ping"` after doctor is the
+  cheap way to prove it. "keychain login"
+  or "nothing configured" means step 3/5 was skipped.
+- **Cohort sources** — for each of `base` / `orgId` / `token` / `agentId`,
+  which file won (`config/org.yaml` beats the environment beats `.env`) and
+  every value that lost. If you edited `.env` and nothing changed, this line
+  is why.
+- **`COHORT_ORG_ID`** checked against the server: "you set the slug" names the
+  real ID to use.
+- **Global SDK install** — `@cohortapp/agent-sdk` present globally and current
+  against npm; `maestro` / `cohort-mcp` resolve on PATH.
+- **Tailscale SSH** on (step 8).
+- **Main session job** installed, loaded, heartbeat live (step 7).
+- The **Cohort connectivity** block: enrollment resolved → directory reachable
+  (latency) → protocol version aligned (the server's `x-org-protocol` header;
+  a drift warning means run `cohort upgrade`) → **key paired to a workforce
+  member** (the `messaging.channels` gate) → **workspace mailbox reachable**
+  (when `config/orgmail.yaml` exists).
 
 Then two live probes:
 
@@ -115,15 +177,25 @@ Then two live probes:
    tick ≤60s). First-contact recipients park as approvals in /decisions — by
    design.
 
-## 8. Operations
+## 10. Operations
 
 - **Kill switch**: touch `.emergency-stop` in the repo root (human-only). The
   daemon exits clean, so launchd stops the restart treadmill. Resume with
-  `scripts/resume-operations.sh`.
+  `scripts/resume-operations.sh`. The main session is stopped separately with
+  `maestro session stop` (and comes back with `maestro session start`).
 - **Email-only kill switch**: delete/rename `config/orgmail.yaml` and restart —
   the gate-file loop skips the platform; server-side an admin can flip the
   mailbox to Disabled in Settings → Email.
-- **Upgrade**: `cohort upgrade` (framework files), `npm i -g @cohortapp/agent-sdk@latest`
-  (the SDK itself). A doctor "protocol drift" warning is the upgrade cue.
+- **Upgrade**: automatic — the hourly `ai.maestro.<first>-autoupdate` job installs
+  a newer SDK, runs `cohort upgrade` (which also regenerates and installs the
+  launchd jobs, re-runs `global-setup` and refreshes the global npm install —
+  `docs/guides/front-door-session.md` §4a), restarts the daemon and
+  health-gates it. It does **not** restart the main session; it writes
+  `state/session/upgrade-notice.json` and the session restarts itself at an
+  idle moment. By hand: `npm i -g @cohortapp/agent-sdk@latest && cohort upgrade`,
+  then `maestro session restart`; `maestro upgrade --verify` confirms the seat
+  is wholly on one version. Verified fleet-wide by `sdkVersion` and
+  `machine.upgrade` on each seat's beat (the Fleet view). A doctor "protocol
+  drift" warning is the cue.
 - **Health**: `scripts/healthcheck.sh`; logs under `logs/` (`logs/audit/` carries
   the per-action JSONL rows from BOTH the native executor and the MCP plane).

package/docs/guides/org-onboarding.md

@@ -71,7 +71,7 @@ context from Cohort and shape the agent's config from it.
 | Var | Required | Purpose |
 | --- | --- | --- |
 | `COHORT_API_KEY` | yes | Bearer OrgApiKey for the org-data DTO reads AND the `/v1` read/RPC surface. hq's documented agent var. (`COHORT_API_TOKEN` / `COHORT_TOKEN` are accepted for back-compat.) |
-| `COHORT_ORG_ID` | yes | Org id / slug — the tenant. Sent as `?slug=` on org-data reads and as the `x-org-id` pin on `/v1`. |
+| `COHORT_ORG_ID` | yes | The org **ID** (`org_default_<slug>`), never the bare slug — hq compares the `x-org-id` pin with strict equality against the ID, so a slug 401s every `/v1` call (`maestro setup` warns, `maestro doctor` checks it against the server). Also sent as `?slug=` on legacy org-data reads. |
 | `COHORT_AGENT_ID` | optional | This agent's member slug. When set it selects `members/<slug>` + keys relationships; when absent the pull resolves via `whoami`. |
 | `COHORT_BASE` / `COHORT_API_URL` | optional | Server origin. Falls back to the persisted `config/org.yaml` endpoint. |
 | `COHORT_AGENT_EMAIL` | optional | Email hint for `whoami` resolution when no `COHORT_AGENT_ID` is given. |

package/docs/guides/setup-wizard.md

@@ -52,7 +52,7 @@ core runner.
 |---------|-------|-------------|
 | `identity` | 10 | Agent name and title, the **function × altitude** archetype, and the principal. Writes `config/agent.json`. |
 | `company` | 20 | Company-context interview — name, website, industry, one-line + detailed overview, stage/size, footprint, regulation, top priorities, and key people. Writes `config/company.json`. |
-| `model` | 30 | Model/provider choice: a Claude Code subscription (keychain OAuth, no API key) or a pasted Anthropic API key. Writes the model lines of `.env`. |
+| `model` | 30 | Claude auth. Three modes, **`oauth-token` the default**: run `claude setup-token` on any logged-in machine and paste the result (headless: `CLAUDE_CODE_OAUTH_TOKEN` in the environment) → `.env` gets `CLAUDE_CODE_OAUTH_TOKEN` + `MAESTRO_PREFER_SUBSCRIPTION_AUTH=1`; or this machine's keychain login; or a pasted Anthropic API key. Chmods `.env` 600. |
 | `comms` | 45 | Wires each messaging channel — Slack, Gmail, SMS, WhatsApp, Telegram, voice — into `.env`/gate files and verifies inbound. |
 | `tools` | 50 | Selects which channels and MCP servers the agent should run. |
 | `operating-model` | 60 | Deterministically generates the operating charter, a seeded WBS backlog (≥5 open items), 40–60 sub-agents + skills + workflows + MCP servers + event-routing, archetype cadences, the autonomy policy, the communication profile, and the launchd plists. |
@@ -102,14 +102,17 @@ re-running `maestro setup` (or `maestro setup enrich`) without the flag.
 ## 5. The verify probe and capability table
 
 The final `verify` section runs a live check and prints an `N/M` capability table.
-It aggregates every other section's `verify()` plus a Claude API probe and the
-completeness gate. Per enabled channel/MCP it runs the right liveness check
+It aggregates every other section's `verify()` plus the Claude auth probe
+(`claude auth status` in subscription mode — which reports that a credential
+is present, not that it is valid; an API ping in api-key mode, which does
+prove the key — the same probe `maestro doctor` and the fleet beat use) and
+the completeness gate. Per enabled channel/MCP it runs the right liveness check
 (`auth.test` for Slack, an IMAP login for Gmail, a Twilio lookup, a relay
 `/health`, etc.), and prints a remedy line under any failure:
 
 ```
 Capability summary — 7/9 checks passing
-  ✓ Claude API reachable
+  ✓ Claude auth (subscription — OAuth token)
   ✓ identity complete
   ✓ Slack auth.test
   ✗ Gmail IMAP login        [comms]
@@ -118,7 +121,8 @@ Capability summary — 7/9 checks passing
 ```
 
 Setup exits **non-zero only on hard failures** — no identity, an unresolvable
-archetype, or the Claude API being unreachable. Optional channels and best-effort
+archetype, or Claude auth being rejected (a probe that cannot run — no CLI, no
+network — is reported as "could not verify" and does not fail the run). Optional channels and best-effort
 enrichment are reported but never fail the run. The same completeness gate backs
 `maestro doctor`, so `doctor` and `setup --status` agree on what "done" means.
 

package/docs/runbooks/cohort-cutover.md

@@ -55,7 +55,17 @@ machine's `config/org.yaml` pins `server.url` (e.g.
 service changes the `*.up.railway.app` host and strands the fleet. Move the
 fleet to a stable custom domain first (§2), then rename freely.
 
-> ⚠︎ **2026-08-16 — this warning appears to have come true, and it is unresolved.**
+> ✅ **RESOLVED 2026-09-08.** The working host is **`https://os.cohortapp.com`** —
+> the org plane (`/api/v1/*`, the `/v1` RPC binding, `presence.beat`, the
+> agent SSE stream) is served by the product app `cohort-app` on the
+> `cohort-os` Railway project, not by a separate org-server service. There is
+> nothing to repoint at `neolith-production`. `DEPLOYMENT.md` §5.1 now templates
+> `os.cohortapp.com`; `.env.example` defaults `COHORT_BASE` to it; `maestro
+> doctor` prints the effective base per seat (org.yaml vs .env vs env) so a
+> straggler pinning the dead host is one `doctor` run away from being found.
+> The paragraph below is kept as the record of what was observed.
+>
+> ⚠︎ **2026-08-16 — this warning appears to have come true (resolved above).**
 > `https://neolith.up.railway.app` is now UNROUTED: Railway's edge returns
 > `x-railway-fallback: true` with a 404 on `/`, `/v1` and `/v1/ops`, meaning no
 > service is attached to that hostname. Contrast the app, whose rename DID