Merge pull request #507 from irisitymichaelgrundberg/feat/select-session-from-url

feat(web): select a dashboard session from a #session=<id> link

docs/architecture-invariants.md

@@ -580,7 +580,7 @@ Either way the actual launch (`runCustomModelEntry`) routes through `run()` itse
 
 ⚠️ **Viewing a session ACKNOWLEDGES its idle item, it does not resolve it** (`POST /api/approvals/session/:sessionId/viewed` → `acknowledgedAt` → `approval:updated`): the item stays pending (still answerable, still Read My Mind context) and only stops arming the yellow tab alert. That flag is what makes the clear durable, since the view-clears-idle rule used to live in one browser's memory and `seedApprovals()` re-armed the alert on the next reload while other devices never heard about it at all; the local half is `markIdleAlertSeen()` (app.js), called from BOTH `selectSession` paths, including the already-active early return, where a click could otherwise never clear the alert.
 
-⚠️ **Only a HUMAN opening a session acknowledges**: `selectSession(id, { auto: true })` marks the three selections the APP makes (boot restore, a solo window opening its target, the fallback after the active session is closed) and skips the acknowledgement, so a page load cannot silently spend an alert the user never saw. The flag defaults to user-initiated, so an untagged call site fails toward acknowledging rather than toward an alert nothing can clear; `test/session-select-ack-gate.test.ts` pins both the gate and the tagged call sites. Idle-only by construction (`acknowledge()` defaults to `['idle']`): looking at a permission/question dialog does not answer it.
+⚠️ **Only a HUMAN opening a session acknowledges**: `selectSession(id, { auto: true })` marks the four selections the APP makes (boot restore, a solo window opening its target, a `#session=<id>` link from another page, the fallback after the active session is closed) and skips the acknowledgement, so a page load cannot silently spend an alert the user never saw. The flag defaults to user-initiated, so an untagged call site fails toward acknowledging rather than toward an alert nothing can clear; `test/session-select-ack-gate.test.ts` pins both the gate and the tagged call sites. Idle-only by construction (`acknowledge()` defaults to `['idle']`): looking at a permission/question dialog does not answer it.
 
 ⚠️ Same rule on the input path: `_ackDelivery` (app.js) spends the IDLE alert only, via that same `markIdleAlertSeen()`. It used to `clearPendingHooks(sessionId)` with no kind, so one keystroke wiped a RED alert on that device while the dialog was still up, the other devices stayed red, and a reload re-seeded it.
 

docs/extending-codeman.md

@@ -338,6 +338,33 @@ codeman ralph start|stop|status|reset    codeman users add|passwd|list
 codeman status | list | attach <path>    codeman doctor
 ```
 
+### Opening a session from your own page
+
+To send someone from your page to one session, link to the dashboard with the
+session id in the fragment, as in `http://127.0.0.1:3000/#session=<id>`. The
+dashboard selects that tab when it loads. It also removes the fragment from its
+own URL, so a later link to the same session still counts as a change.
+
+Keep reusing one named window to make later links fast:
+
+```js
+window.open(`${codeman}/#session=${encodeURIComponent(id)}`, 'codeman');
+```
+
+When that window already shows the dashboard, only the fragment differs. The
+browser therefore keeps the page loaded, and the dashboard switches tabs without
+reloading it. A session the window has shown before appears at once. A session
+your page has only just created may not be listed yet, so the dashboard waits
+for its `session:created` event and selects it then.
+
+Following a link does not count as someone looking at the session, so it
+leaves the session's idle alert in place. The alert clears when the person
+clicks the tab or types into the session. A link to a session that is popped
+out into its own window asks that window to come forward, as clicking its tab does.
+
+A link to `/session/<id>` opens a page showing that session alone, and that
+page loads from scratch for every link.
+
 ## Seam 4: Hooks
 
 Claude Code hooks post to `POST /api/v1/hook-event` from inside an agent session.