chore: docs update

Author: maxy-shpfy

docs/express-best-practices.md

@@ -198,21 +198,25 @@ router.post(
 
 ### Reusable cross-cutting middleware
 
-Factor recurring concerns (auth, token checks, request logging) into small middleware functions. The token guard is the model to follow:
+Factor recurring concerns (auth, token checks, request logging) into small middleware functions. The token guard is the model to follow — a factory parameterized by the connector credential, so the byte comparison lives in the credential and a route only says which far end it is for (`apps/server/src/middleware/requireCredential.ts`):
 
 ```ts
-// ✅ GOOD: a focused, reusable guard (apps/server/src/routes/internalMemory.ts)
-function requireInternalToken(
-  req: Request,
-  res: Response,
-  next: NextFunction,
-): void {
-  if (req.get("authorization") !== `Bearer ${INTERNAL_TOKEN}`) {
-    res.status(401).json({ error: "Unauthorized" });
-    return;
-  }
-  next();
+// ✅ GOOD: a focused, reusable guard parameterized by a credential
+export function requireCredential(
+  credential: ConnectorCredential,
+): RequestHandler {
+  return function guard(req: Request, res: Response, next: NextFunction): void {
+    if (!credential.verify({ authorization: req.get("authorization") })) {
+      res.status(401).json({ error: "Unauthorized" });
+      return;
+    }
+    next();
+  };
 }
+
+// The internal API's guard is that factory bound to the Pi connector's credential
+// (apps/server/src/middleware/requireInternalToken.ts):
+export const requireInternalToken = requireCredential(piCredential);
 ```
 
 ### Centralize error handling

docs/server/agent-communication.md

@@ -126,15 +126,30 @@ A2A participant when the registry resolves one:
 **How Prime reads a sub-agent's room:** "the room" is the shared session
 transcript persisted in the `SessionStore`. When Prime (or any agent) calls
 `read_room`, the tool hits `GET /internal/agents/room?sessionId=...`, and
-`handleRoom` returns the tail of `store.getMessages(sessionId)`:
+`handleRoom` returns the tail of `store.getMessages(sessionId)` — unless the
+caller names both `conversationId` and `participantId`, in which case it returns
+that Conversation projected through the reader's context policy (verbatim tail
+plus any digests; see [conversations.md](./conversations.md)):
 
-```138:151:apps/server/src/routes/internalAgents.ts
+```327:347:apps/server/src/routes/internalAgents.ts
 async function handleRoom(
   store: SessionStore,
   query: RoomQuery,
   res: Response,
+  context: ContextEngine | undefined,
+  memberships: MembershipRegistry | undefined,
 ): Promise<void> {
-  ...
+  const limit = roomLimit(query.limit);
+  if (context && memberships && query.conversationId && query.participantId) {
+    const projected = await projectRoom(context, store, memberships, {
+      sessionId: query.sessionId,
+      conversationId: query.conversationId,
+      participantId: query.participantId,
+      limit,
+    });
+    res.json(projected);
+    return;
+  }
   const all = await store.getMessages(query.sessionId);
   res.json({ messages: all.slice(-limit) });
 }
@@ -268,7 +283,7 @@ Pi-RPC stdin; the reply is Pi-RPC stdout → manager handler → WS out.
 > `autoRelayToPrime: false`, so they react in isolation and only reach Prime when
 > they explicitly call `message_prime`.
 
-## 5. Remote sub-agents (an alternative host)
+## 5. Remote sub-agents (an alternative connector)
 
 A sub-agent does not have to be a local `pi` child. A **remote environment**
 can connect over a dedicated Socket.IO namespace (`/remote-env`) and host
@@ -302,6 +317,8 @@ rather than mis-routed. See [connectors.md](./connectors.md).
   another agent SDK.
 
 The wire shapes live in `@tangent/shared/remoteSubagent.ts`, shared by both
-sides so the protocol cannot drift. Remote sub-agents are **not** revived after
-a server restart (`reviveSubagents` skips `host: "remote"` rows); they
-re-establish when their environment reconnects.
+sides so the protocol cannot drift. On a server restart, `ConnectorRegistry.revive`
+routes every non-terminal persisted row to its connector by recorded kind. The
+remote connector does not re-spawn a process it does not own: it restores the row
+as a `detached` tab, which becomes reachable again only when the environment
+reconnects and streams a turn.

docs/server/egress-and-security.md

@@ -19,8 +19,11 @@ extensions present that token as `Authorization: Bearer <token>` on every call
 to the server's internal API.
 
 `INTERNAL_TOKEN` ([config.ts](../../server/src/config.ts)) is a per-start
-`randomUUID()` unless pinned via env. Every internal router installs a middleware
-that rejects any request whose bearer does not match:
+`randomUUID()` unless pinned via env. Every internal router installs
+`requireInternalToken` — `requireCredential(piCredential)`
+([requireInternalToken.ts](../../server/src/middleware/requireInternalToken.ts)) —
+which rejects any request the Pi connector's credential does not verify. The byte
+comparison lives in the credential facet, not the route:
 
 - `/internal/agents` ([internalAgents.ts](../../server/src/routes/internalAgents.ts))
 - `/internal/memory` ([internalMemory.ts](../../server/src/routes/internalMemory.ts))

docs/server/index.md

@@ -228,11 +228,12 @@ Every `pi` child is spawned with `TANGENT_INTERNAL_URL` and
 `TANGENT_INTERNAL_TOKEN` in its environment
 ([apps/server/src/pi/piAgentManager.ts](../../apps/server/src/pi/piAgentManager.ts)).
 The extensions present that token as `Authorization: Bearer <token>` on every
-call to `/internal/*`. Each internal router rejects requests whose bearer does not
-match `INTERNAL_TOKEN`, which is a per-start `randomUUID()` unless pinned via env
-([apps/server/src/config.ts](../../apps/server/src/config.ts)). This keeps
-arbitrary local processes from driving a session's agents, memory, triggers, or
-resources. Details in [egress-and-security.md](./egress-and-security.md).
+call to `/internal/*`. Each internal router installs `requireInternalToken`
+(`requireCredential(piCredential)`), which rejects any request the Pi connector's
+credential does not verify against `INTERNAL_TOKEN` — a per-start `randomUUID()`
+unless pinned via env ([apps/server/src/config.ts](../../apps/server/src/config.ts)).
+This keeps arbitrary local processes from driving a session's agents, memory,
+triggers, or resources. Details in [egress-and-security.md](./egress-and-security.md).
 
 ## Configuration / environment surface
 

docs/server/sessions-and-storage.md

@@ -29,9 +29,9 @@ interface; the routes and socket handlers depend only on it. The production
 implementation is
 [`SqliteSessionStore`](../../apps/server/src/store/sqliteSessionStore.ts), backed by
 the shared `tangent.db` connection (`openDb()` applies pending drizzle migrations
-on startup). It composes the participant and resource stores so a roster write
-mirrors into the `participants` table and a pinned artifact into the resource
-catalog. `InMemorySessionStore` still exists but is a test fake, not the
+on startup). It reads and writes the roster on the `participants` table directly
+and composes the resource store so a pinned artifact is mirrored into the
+resource catalog. `InMemorySessionStore` still exists but is a test fake, not the
 production backend.
 
 `createSession` allocates a `randomUUID()`, derives `rootPath =
@@ -56,24 +56,24 @@ The relational state lives in [db/schema.ts](../../apps/server/src/store/db/sche
 Chat history is deliberately **not** a table — it stays as JSONL on disk. Schema
 changes go exclusively through drizzle migrations; never alter tables ad-hoc.
 
-| Table                 | Holds                                                                                          |
-| --------------------- | ---------------------------------------------------------------------------------------------- |
-| `sessions`            | one row per session (mirrors the `Session` wire contract, plus `archived`, `user_identity`).   |
-| `session_assets`      | pinned artifacts, scoped to a session, oldest-first.                                           |
-| `session_agents`      | the agent roster (Prime + sub-agents) with connector facets; still the write authority today.  |
-| `participants`        | session-scoped actor identities (`human` / `agent` / `automation`), capabilities, presence.    |
-| `conversations`       | per-Conversation `seq` counter and its owning agent; maps a Conversation id to its transcript. |
-| `memberships`         | a `(participant, conversation)` attachment: reaction spec, ingress, transcript visibility.     |
-| `runs`                | one unit of work by one participant: status, ingress, home conversation, external id, cursor.  |
-| `resources`           | the catalog: `file` / `memory` / `attachment` / `artifact`, pointing at bytes by `uri`.        |
-| `resource_references` | a resource surfaced into a Conversation (surfacing + citation, not a filesystem gate).         |
-| `resource_grants`     | per-Membership refinement of a reference; default-permissive (an empty table changes nothing). |
-| `session_views`       | when each user last opened a session.                                                          |
-
-`session_agents` remains the write authority for the roster; `participants` is
-mirrored from it (and derived read-through for a session the backfill never
-touched). The deprecated `host` column survives beside the connector facets. A
-later cleanup folds these away.
+| Table                 | Holds                                                                                                                                                        |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `sessions`            | one row per session (mirrors the `Session` wire contract, plus `archived`, `user_identity`).                                                                 |
+| `session_assets`      | pinned artifacts, scoped to a session, oldest-first.                                                                                                         |
+| `participants`        | the roster: session-scoped actor identities (`human` / `agent` / `automation`), capabilities, presence, and each agent's connector facets + `agent_payload`. |
+| `conversations`       | per-Conversation `seq` counter and its owning agent; maps a Conversation id to its transcript.                                                               |
+| `memberships`         | a `(participant, conversation)` attachment: reaction spec, ingress, transcript visibility.                                                                   |
+| `runs`                | one unit of work by one participant: status, ingress, home conversation, external id, cursor.                                                                |
+| `resources`           | the catalog: `file` / `memory` / `attachment` / `artifact`, pointing at bytes by `uri`.                                                                      |
+| `resource_references` | a resource surfaced into a Conversation (surfacing + citation, not a filesystem gate).                                                                       |
+| `resource_grants`     | per-Membership refinement of a reference; default-permissive (an empty table changes nothing).                                                               |
+| `session_views`       | when each user last opened a session.                                                                                                                        |
+
+`participants` is the roster's only store. The old `session_agents` table (and
+its deprecated `host` column) is gone; `SessionStore.listAgents` /
+`recordAgent` / `setAgentStatus` now read and write `participants` directly,
+mapping an agent's `agent_payload` back to a `SessionAgent`. Connector kind is a
+facet column, defaulting to `pi-stdio` when unset.
 
 ---