@rubytech/create-maxy-code 0.1.51 → 0.1.58

package/dist/__tests__/platform-port-stamp.test.js

@@ -0,0 +1,24 @@
+// Task 142 — manager systemd unit must stamp PLATFORM_PORT equal to
+// MAXY_UI_INTERNAL_PORT so admin and whatsapp MCP servers inherit the
+// internal-loopback port. The producer-side gap closed in Task 142
+// after Task 139 removed every consumer-side fallback.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { buildClaudeSessionManagerUnitFile } from "../port-resolution.js";
+test("PLATFORM_PORT stamped on manager unit equal to MAXY_UI_INTERNAL_PORT", () => {
+    const unit = buildClaudeSessionManagerUnitFile({
+        productName: "Maxy",
+        brandHostname: "maxy",
+        installDir: "/opt/maxy",
+        persistDir: "/home/admin/.maxy",
+        claudeSessionManagerPort: 11200,
+        brandPort: 19200,
+        maxyUiInternalPort: 19201,
+        accountId: "00000000-0000-0000-0000-000000000000",
+    });
+    assert.match(unit, /^Environment=PLATFORM_PORT=19201$/m);
+    assert.match(unit, /^Environment=MAXY_UI_INTERNAL_PORT=19201$/m);
+    assert.match(unit, /^Environment=MAXY_BRAND_PORT=19200$/m);
+    // Order is not asserted; coexistence with the existing brand-port and
+    // internal-port lines is what producers and consumers contract on.
+});

package/dist/index.js

@@ -1815,7 +1815,9 @@ function deployPayload() {
     // future divergence between the two should be caught by the test suite.
     runInstallInvariantCheck(persistentUsersFile, join(INSTALL_DIR, "data", "accounts"));
     // Write version marker so the running platform knows which create-maxy produced this deployment
-    writeFileSync(join(configDir, `.${BRAND.hostname}-version`), PKG_VERSION, "utf-8");
+    const versionMarkerPath = join(configDir, `.${BRAND.hostname}-version`);
+    writeFileSync(versionMarkerPath, PKG_VERSION, "utf-8");
+    console.log(`  [install] version-marker written path=${versionMarkerPath} version=${PKG_VERSION}`);
     console.log(`  Deployed to ${INSTALL_DIR}`);
 }
 // register the local + external Claude Code plugins after the
@@ -2989,10 +2991,11 @@ function installService() {
         persistDir,
         claudeSessionManagerPort: CLAUDE_SESSION_MANAGER_PORT_BRAND,
         brandPort: PORT,
+        maxyUiInternalPort: MAXY_UI_INTERNAL_PORT,
         accountId: installAccountId,
     });
     writeFileSync(join(serviceDir, claudeSessionManagerUnitName), claudeSessionManagerUnit);
-    logFile(`  ${claudeSessionManagerUnitName}: CLAUDE_SESSION_MANAGER_PORT=${CLAUDE_SESSION_MANAGER_PORT_BRAND}`);
+    logFile(`  ${claudeSessionManagerUnitName}: CLAUDE_SESSION_MANAGER_PORT=${CLAUDE_SESSION_MANAGER_PORT_BRAND} MAXY_UI_INTERNAL_PORT=${MAXY_UI_INTERNAL_PORT}`);
     // the edge service: always-on front door that owns the public
     // port (PORT) and the VNC stack (Xtigervnc + websockify). Its lifecycle is
     // independent of the main brand service, so an in-place upgrade triggered

package/dist/port-resolution.js

@@ -146,6 +146,8 @@ Environment=CLAUDE_SESSION_MANAGER_PERSIST_DIR=${o.persistDir}
 Environment=CLAUDE_CONFIG_DIR=${o.persistDir}/.claude
 Environment=PLATFORM_ROOT=${o.installDir}/platform
 Environment=MAXY_BRAND_PORT=${o.brandPort}
+Environment=MAXY_UI_INTERNAL_PORT=${o.maxyUiInternalPort}
+Environment=PLATFORM_PORT=${o.maxyUiInternalPort}
 EnvironmentFile=-${o.persistDir}/.env
 StandardOutput=append:${o.persistDir}/logs/server.log
 StandardError=append:${o.persistDir}/logs/server.log

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy-code",
-  "version": "0.1.51",
+  "version": "0.1.58",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy-code": "./dist/index.js"

package/payload/platform/lib/require-port-env/dist/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Loud-fail port-env resolver. Single doctrine surface for every runtime
+ * site that reads a network port from the environment.
+ *
+ * Per Task 139: no hardcoded numeric fallbacks. If the env var is missing
+ * or doesn't parse as an integer in the valid TCP port range, throw with
+ * a one-line diagnostic in the canonical shape
+ *
+ *   [<tag>] <fail-line> reason=missing-env env=<NAME>
+ *
+ * matching the Task 134 hook diagnostic so one grep
+ * (`reason=missing-env env=`) lists every misconfigured device in the field.
+ *
+ * Callers in server entry points should let the throw propagate; systemd's
+ * Restart=on-failure cycles visibly. Callers in long-lived processes should
+ * surface the same line on stderr before exit.
+ */
+export interface RequirePortEnvOptions {
+    /** Diagnostic tag prefixed to the fail line. Defaults to "port-env". */
+    tag?: string;
+    /** Fail line written after the tag. Defaults to "missing-port-env". */
+    failLine?: string;
+}
+export declare class MissingPortEnvError extends Error {
+    readonly envName: string;
+    readonly tag: string;
+    readonly failLine: string;
+    constructor(envName: string, tag: string, failLine: string, message: string);
+}
+export declare function requirePortEnv(envName: string, options?: RequirePortEnvOptions): number;
+//# sourceMappingURL=index.d.ts.map

package/payload/platform/lib/require-port-env/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,qBAAqB;IACpC,wEAAwE;IACxE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBACd,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAO5E;AAKD,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,MAAM,CAc3F"}

package/payload/platform/lib/require-port-env/dist/index.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * Loud-fail port-env resolver. Single doctrine surface for every runtime
+ * site that reads a network port from the environment.
+ *
+ * Per Task 139: no hardcoded numeric fallbacks. If the env var is missing
+ * or doesn't parse as an integer in the valid TCP port range, throw with
+ * a one-line diagnostic in the canonical shape
+ *
+ *   [<tag>] <fail-line> reason=missing-env env=<NAME>
+ *
+ * matching the Task 134 hook diagnostic so one grep
+ * (`reason=missing-env env=`) lists every misconfigured device in the field.
+ *
+ * Callers in server entry points should let the throw propagate; systemd's
+ * Restart=on-failure cycles visibly. Callers in long-lived processes should
+ * surface the same line on stderr before exit.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MissingPortEnvError = void 0;
+exports.requirePortEnv = requirePortEnv;
+class MissingPortEnvError extends Error {
+    envName;
+    tag;
+    failLine;
+    constructor(envName, tag, failLine, message) {
+        super(message);
+        this.name = "MissingPortEnvError";
+        this.envName = envName;
+        this.tag = tag;
+        this.failLine = failLine;
+    }
+}
+exports.MissingPortEnvError = MissingPortEnvError;
+const VALID_PORT_MIN = 1;
+const VALID_PORT_MAX = 65535;
+function requirePortEnv(envName, options = {}) {
+    const tag = options.tag ?? "port-env";
+    const failLine = options.failLine ?? "missing-port-env";
+    const raw = process.env[envName];
+    if (raw === undefined || raw === "") {
+        const msg = `[${tag}] ${failLine} reason=missing-env env=${envName}`;
+        throw new MissingPortEnvError(envName, tag, failLine, msg);
+    }
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isInteger(parsed) || parsed < VALID_PORT_MIN || parsed > VALID_PORT_MAX || String(parsed) !== raw.trim()) {
+        const msg = `[${tag}] ${failLine} reason=invalid-port-env env=${envName} value=${JSON.stringify(raw)}`;
+        throw new MissingPortEnvError(envName, tag, failLine, msg);
+    }
+    return parsed;
+}
+//# sourceMappingURL=index.js.map

package/payload/platform/lib/require-port-env/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;;AAyBH,wCAcC;AA9BD,MAAa,mBAAoB,SAAQ,KAAK;IACnC,OAAO,CAAS;IAChB,GAAG,CAAS;IACZ,QAAQ,CAAS;IAC1B,YAAY,OAAe,EAAE,GAAW,EAAE,QAAgB,EAAE,OAAe;QACzE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAXD,kDAWC;AAED,MAAM,cAAc,GAAG,CAAC,CAAC;AACzB,MAAM,cAAc,GAAG,KAAK,CAAC;AAE7B,SAAgB,cAAc,CAAC,OAAe,EAAE,UAAiC,EAAE;IACjF,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,UAAU,CAAC;IACtC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,kBAAkB,CAAC;IACxD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACjC,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE,EAAE,CAAC;QACpC,MAAM,GAAG,GAAG,IAAI,GAAG,KAAK,QAAQ,2BAA2B,OAAO,EAAE,CAAC;QACrE,MAAM,IAAI,mBAAmB,CAAC,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC;IAC7D,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACxC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,cAAc,IAAI,MAAM,GAAG,cAAc,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC;QACrH,MAAM,GAAG,GAAG,IAAI,GAAG,KAAK,QAAQ,gCAAgC,OAAO,UAAU,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC;QACvG,MAAM,IAAI,mBAAmB,CAAC,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/payload/platform/lib/require-port-env/src/index.ts

@@ -0,0 +1,56 @@
+/**
+ * Loud-fail port-env resolver. Single doctrine surface for every runtime
+ * site that reads a network port from the environment.
+ *
+ * Per Task 139: no hardcoded numeric fallbacks. If the env var is missing
+ * or doesn't parse as an integer in the valid TCP port range, throw with
+ * a one-line diagnostic in the canonical shape
+ *
+ *   [<tag>] <fail-line> reason=missing-env env=<NAME>
+ *
+ * matching the Task 134 hook diagnostic so one grep
+ * (`reason=missing-env env=`) lists every misconfigured device in the field.
+ *
+ * Callers in server entry points should let the throw propagate; systemd's
+ * Restart=on-failure cycles visibly. Callers in long-lived processes should
+ * surface the same line on stderr before exit.
+ */
+
+export interface RequirePortEnvOptions {
+  /** Diagnostic tag prefixed to the fail line. Defaults to "port-env". */
+  tag?: string;
+  /** Fail line written after the tag. Defaults to "missing-port-env". */
+  failLine?: string;
+}
+
+export class MissingPortEnvError extends Error {
+  readonly envName: string;
+  readonly tag: string;
+  readonly failLine: string;
+  constructor(envName: string, tag: string, failLine: string, message: string) {
+    super(message);
+    this.name = "MissingPortEnvError";
+    this.envName = envName;
+    this.tag = tag;
+    this.failLine = failLine;
+  }
+}
+
+const VALID_PORT_MIN = 1;
+const VALID_PORT_MAX = 65535;
+
+export function requirePortEnv(envName: string, options: RequirePortEnvOptions = {}): number {
+  const tag = options.tag ?? "port-env";
+  const failLine = options.failLine ?? "missing-port-env";
+  const raw = process.env[envName];
+  if (raw === undefined || raw === "") {
+    const msg = `[${tag}] ${failLine} reason=missing-env env=${envName}`;
+    throw new MissingPortEnvError(envName, tag, failLine, msg);
+  }
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isInteger(parsed) || parsed < VALID_PORT_MIN || parsed > VALID_PORT_MAX || String(parsed) !== raw.trim()) {
+    const msg = `[${tag}] ${failLine} reason=invalid-port-env env=${envName} value=${JSON.stringify(raw)}`;
+    throw new MissingPortEnvError(envName, tag, failLine, msg);
+  }
+  return parsed;
+}

package/payload/platform/lib/require-port-env/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}

package/payload/platform/package-lock.json

@@ -6,7 +6,6 @@
   "packages": {
     "": {
       "name": "maxy-platform",
-      "version": "0.1.0",
       "workspaces": [
         "plugins/*/mcp",
         "services/*"

package/payload/platform/package.json

@@ -1,14 +1,13 @@
 {
   "name": "maxy-platform",
-  "version": "0.1.0",
   "private": true,
   "workspaces": [
     "plugins/*/mcp",
     "services/*"
   ],
   "scripts": {
-    "build": "tsc -p lib/models/tsconfig.json && tsc -p lib/oauth-llm/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/mcp-eager/tsconfig.json && tsc -p lib/account-enumeration/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json && tsc -p lib/persistent-components/tsconfig.json && tsc -p services/claude-session-manager/tsconfig.json && NODE_OPTIONS='--max-old-space-size=8192' tsc -b plugins/*/mcp/tsconfig.json",
-    "build:lib": "tsc -p lib/models/tsconfig.json && tsc -p lib/oauth-llm/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/mcp-eager/tsconfig.json && tsc -p lib/account-enumeration/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json && tsc -p lib/persistent-components/tsconfig.json",
+    "build": "tsc -p lib/models/tsconfig.json && tsc -p lib/oauth-llm/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/mcp-eager/tsconfig.json && tsc -p lib/account-enumeration/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json && tsc -p lib/persistent-components/tsconfig.json && tsc -p lib/require-port-env/tsconfig.json && tsc -p services/claude-session-manager/tsconfig.json && NODE_OPTIONS='--max-old-space-size=8192' tsc -b plugins/*/mcp/tsconfig.json",
+    "build:lib": "tsc -p lib/models/tsconfig.json && tsc -p lib/oauth-llm/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/mcp-eager/tsconfig.json && tsc -p lib/account-enumeration/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/screening-patterns/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json && tsc -p lib/persistent-components/tsconfig.json && tsc -p lib/require-port-env/tsconfig.json",
     "build:memory": "tsc -p plugins/memory/mcp/tsconfig.json",
     "build:contacts": "tsc -p plugins/contacts/mcp/tsconfig.json",
     "build:telegram": "tsc -p plugins/telegram/mcp/tsconfig.json",

package/payload/platform/plugins/admin/PLUGIN.md

@@ -64,6 +64,8 @@ mcp:
     PLATFORM_ROOT: ${PLATFORM_ROOT}
     ACCOUNT_ID: ${ACCOUNT_ID}
     SESSION_ID: ${SESSION_ID}
+    PLATFORM_PORT: ${PLATFORM_PORT}
+    MAXY_BRAND_PORT: ${MAXY_BRAND_PORT}
 ---
 
 # Admin
@@ -105,8 +107,19 @@ Tools are available via the `admin` MCP server.
 - `hooks/pre-tool-use.sh` — enforces admin agent write boundaries
 - `hooks/playwright-file-guard.sh` — rewrites file:// URLs to a backgrounded loopback http.server before Playwright sees them
 - `hooks/webfetch-preflight.mjs` — short-circuits WebFetch on JS-SPA shells with a structured `WEBFETCH_CANNOT_READ_JS_SPA` error so the agent surfaces a loud failure to the owner instead of paying the 60s extraction timeout. Fail-open on any internal error.
-- `hooks/turn-completed-graph-write.sh` — Stop hook fired once per completed admin-agent turn. Gates on `MAXY_SESSION_ROLE=admin` + `MAXY_HIDDEN_SPAWN=0` so it never recurses into the hidden recorder PTY or fires on public sessions. Task 122 redesign: the hook makes ONE HTTP call to `POST /api/admin/claude-sessions/recorder-spawn` (loopback-only, `senderId='turn-recorder'`, bypasses admin-session auth on 127.0.0.1). The wrapper owns the spawn-with-initial-message sequence for every caller — Sidebar single-line stimulus and recorder multi-line instruction both flow through one function, so the multi-line submit path lives in one place instead of being re-implemented in bash. The manager's `POST /:id/input` wraps multi-line `text` in DEC bracketed-paste markers (`\e[200~ ... \e[201~\r`) so the TUI submits it as one turn; single-line text keeps the typed-keystroke path. The recorder-auto-archive subscriber stops the recorder PTY as soon as its JSONL contains an assistant message with `stop_reason === "end_turn"`. Hidden rows do not surface in `/list` by default.
+- `hooks/turn-completed-graph-write.sh` — Stop hook fired once per completed admin-agent turn. Gates on `MAXY_SESSION_ROLE=admin` + `MAXY_IS_RECORDER!=1` so it never recurses into the recorder PTY or fires on public sessions. **Task 134 redesign** — the recorder is spawned via the same route Sidebar uses. ONE POST to `POST /api/admin/claude-sessions`, body carries `{specialist:'database-operator', initialMessage:'<instruction>\n\n<last-turn-text>', originatingSessionId:<op>}` — no synthetic `senderId: 'turn-recorder'` marker. The Hono wrapper bypasses cookie auth on this exact method+path when the request originates from `127.0.0.1` (same trust boundary the claude-session-manager itself relies on), looks up the operator's senderId from the manager's `/<originatingSessionId>/meta`, and forwards a Sidebar-shape spawn body. The `/recorder-spawn` sibling route is gone. The hook reads its UI port from `MAXY_UI_INTERNAL_PORT` (stamped on the manager systemd unit) — no fallback; absence emits `[turn-recorder] spawn-failed reason=missing-env env=MAXY_UI_INTERNAL_PORT` to stderr instead of silently 19199-ing. The manager's `POST /:id/input` wraps multi-line `text` in DEC bracketed-paste markers (`\e[200~ ... \e[201~\r`) so the TUI submits it as one turn — both Sidebar's multi-line first messages and the recorder's multi-line instruction depend on that branch. The recorder-auto-archive subscriber stops the recorder PTY as soon as its JSONL contains an assistant message with `stop_reason === "end_turn"`. **Task 129** — every emit goes through `POST /api/admin/log-ingest` so the lines land in `server.log` keyed by the operator session id. The chain is `trigger` → `spawn-request` → `spawn-success` → `input-delivered` → `tool-call` × N → `tool-result` × N → `write-complete` → `auto-archive`; each gated-off path emits one `trigger-skipped reason=<role-not-admin|is-recorder|empty-stdin|missing-transcript|last-turn-empty>` line. The spawn body carries `originatingSessionId` as a structural top-level field so downstream loggers read the operator id without parsing prose. Failure modes — `spawn-failed`, `tool-surface-missing`, `input-failed`, `write-empty`, `auto-archive reason=stale-recorder` — each emit one named line; absence is itself a defect.
 
-## Failure-report breadcrumbs
+## Session identifiers (Task 135)
 
-`POST /api/admin/sse-telemetry` and `POST /api/admin/failure-report` write `[sse-client]` and `[failure-report]` lines to `claude-agent-stream-<sessionKey>.log` so one grep against that file reconstructs the failing turn. The admin agent reads these via `logs-read`; the operator surfaces them by clicking "Report this turn" in the chat menu.
+The metadata pane and admin logs use these three identifier names, matching what Claude Code surfaces:
+
+| Operator label | What it is | Manager wire field | Log key |
+|---|---|---|---|
+| `sessionId` | Claude's session — one identity with two phases the manager resolver maps to the same row: bridge suffix (`session_xxx` from `claude.ai/code/<session_xxx>`) and JSONL basename UUID on disk. The manager emits whichever phase is current (bridge preferred). | `sessionId` (collapsed from the earlier three-field surface (see Task 141)) | `sessionId=` |
+| `accountId` | Account / workspace UUID. | `senderId` (channel-agnostic — same wire field carries phone/email/chat-id on non-admin channels, so its log key stays `senderId=` outside admin flow) | `accountId=` (admin flow) |
+
+Full contract lives in [admin-session.md § Session identifiers](../docs/references/admin-session.md).
+
+## SSE telemetry breadcrumbs
+
+`POST /api/admin/sse-telemetry` writes `[sse-client]` lines to `claude-agent-stream-<sessionKey>.log` so one grep against that file reconstructs a failing turn. The admin agent reads these via `logs-read`.