@rubytech/create-maxy-code 0.1.468 → 0.1.470

package/payload/platform/plugins/docs/references/admin-ui.md

@@ -485,6 +485,38 @@ or mis-named icon asset shows `icons-present<3`, and a dropped head injection
 shows `manifest-linked<3`. The graph, data, and browser shells are intentionally
 non-installable.
 
+## WhatsApp socket resolution
+
+Every route that needs a live WhatsApp socket resolves it through
+`resolveSocket` in
+[`app/lib/whatsapp/manager.ts`](../../../ui/app/lib/whatsapp/manager.ts),
+never through the raw `getSocket` primitive it is built on. `getSocket` is
+an exact-key lookup, and a connection is keyed by its credential dirname
+(often a legacy `default`) while callers frequently hold the platform
+account UUID. A raw lookup therefore returns `null` for a socket that is
+alive under the other key.
+
+`resolveSocket` accepts either key and splits that `null` into the two
+failures that demand **opposite** operator advice:
+
+| Reason | What it means | Correct advice |
+|---|---|---|
+| `key-miss` | No connection is registered under this id. The socket is likely alive under a different key. | Fix the account keying. **Never advise re-pairing** — that would re-pair a healthy socket. |
+| `disconnected` | The connection exists and its transport is genuinely down. | Transport-down; reconnecting is appropriate. |
+
+The reason label, the `presentKeys` rendering, and both operator-facing
+messages have one definition, in
+[`app/lib/whatsapp/socket-resolution-error.ts`](../../../ui/app/lib/whatsapp/socket-resolution-error.ts).
+Callers keep their own log shape, HTTP status, and throw-vs-return
+handling, but never hand-write the message strings — a copied key-miss
+message is how the "do not advise re-pairing" instruction drifts out of
+one branch unnoticed.
+
+Two callers predate the shared formatter and still carry their own
+equivalent wording: the reader reply path and the `/send-admin` route.
+Consolidating them is tracked separately; do not copy their strings into
+new callers.
+
 ## Related references
 
 - [`platform.md`](platform.md) — UI layout, session reconcile model,

package/payload/platform/plugins/docs/references/google-guide.md

@@ -0,0 +1,68 @@
+# Google Calendar
+
+Live Google Calendar for one account: read the user's real events, and create,
+update, cancel, respond to and check availability against them. Eleven tools,
+admin agent only.
+
+There is deliberately no Gmail surface here. Mail runs on the `email` plugin's
+IMAP/SMTP path, and Gmail's read/modify scopes are *restricted*, which would
+force Google's annual third-party security assessment. Calendar is only a
+*sensitive* scope, so it needs the lighter brand verification.
+
+## Connecting an account
+
+`google-account-register` returns a consent URL. Relay it to the user: they open
+it on any device, sign in, and approve. Google redirects to this install's
+public host at `/api/google/oauth/callback`, which exchanges the code and stores
+encrypted tokens. `google-account-register-poll` then reports the outcome.
+
+The register tool does not block and does not wait. A second register while one
+is already live is refused rather than overwriting it; that refusal names how
+long the live one has been pending.
+
+One account can connect several Google accounts. Every operational tool takes an
+optional `account` (the email address). Omit it when there is one; with two or
+more, omitting it returns a refusal listing them.
+
+## Reading and controlling
+
+- `google-calendar-list` — events in the next `rangeDays` days (default 7).
+  Recurring series are expanded into instances, so this returns what the user
+  actually sees in their calendar.
+- `google-calendar-event` — one event by id.
+- `google-calendar-create` — times are RFC3339 (`2026-07-20T09:00:00Z`) unless
+  `allDay` is true, in which case they are plain dates (`2026-07-20`).
+- `google-calendar-update` — changes only the fields you name. Omitted fields
+  are left alone, so an update never blanks something by accident.
+- `google-calendar-cancel` — deletes the event and notifies attendees.
+- `google-calendar-respond` — accept, decline or tentatively accept an
+  invitation. Every other attendee's response is preserved.
+- `google-calendar-freebusy` — busy blocks between two times. Free time is the
+  complement, which you work out.
+
+## Checking health
+
+`google-account-list` answers "is anything connected?" from local stores with no
+network call. Read each entry's `status` — a count alone is not "connected", and
+an unreadable store still counts. `google-account-info` gives one account's auth
+state, including whether its access token is near expiry and which scopes were
+granted.
+
+## When something is wrong
+
+**"GOOGLE_CLIENT_ID is not configured"** — this brand has no Google vendor app
+yet. Nothing the operator does on the device fixes it; the brand needs its own
+Google Cloud OAuth client. See `platform/plugins/google/references/auth.md`.
+
+**A 403 naming insufficient scope** — the connected account approved something
+narrower than the full calendar scope. Re-run `google-account-register` so they
+re-consent.
+
+**The user re-consents every week** — the brand's Google app is still in
+Testing, where Google caps refresh tokens at seven days and limits the app to
+100 named test users. Completing brand verification removes both. This is a
+property of the vendor app, not a fault in the connection.
+
+**A registration never completes** — the consent URL was opened but not
+approved, or the callback could not be reached. `google-account-register-poll`
+reports `expired` once the pending entry outlives Google's code lifetime.

package/payload/platform/plugins/google/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "google",
+  "description": "Live Google Calendar for one account via the Google Calendar API v3 — read plus control. Per-account OAuth authorization-code + PKCE; the consent URL is minted by the plugin and the code is exchanged by platform/ui, which holds the house-only client secret. One account can connect several Google accounts; every operational tool takes an optional account selector (the email address) and refuses ambiguously when two or more are connected and none is named. There is deliberately no Gmail surface — mail runs on the `email` plugin's IMAP/SMTP path, and Gmail's restricted scopes would force Google's annual third-party security assessment, whereas Calendar is only a sensitive scope. Tools — google-account-register / google-account-register-poll: connect a Google Calendar (returns a consent URL, then reports the outcome from local state); google-calendar-list: events in the next rangeDays days, recurring series expanded; google-calendar-event: one event by id; google-calendar-create / google-calendar-update / google-calendar-cancel: control events, attendees notified, update changes only the fields named; google-calendar-respond: accept, decline or tentatively accept an invitation, leaving other attendees' responses untouched; google-calendar-freebusy: busy blocks for this or named calendars; google-account-info: auth state for one connected Google account; google-account-list: every connected Google account with its own status.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Rubytech LLC"
+  },
+  "mcpServers": {
+    "google": {
+      "type": "stdio",
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/lib/mcp-spawn-tee/index.js",
+        "${CLAUDE_PLUGIN_ROOT}/mcp/dist/index.js"
+      ],
+      "env": {
+        "MCP_SPAWN_TEE_NAME": "google"
+      }
+    }
+  }
+}

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

@@ -0,0 +1,104 @@
+---
+name: google
+description: Live Google Calendar for one account via the Google Calendar API v3 — read plus control. Per-account OAuth authorization-code + PKCE; the consent URL is minted by the plugin and the code is exchanged by platform/ui, which holds the house-only client secret. One account can connect several Google accounts; every operational tool takes an optional account selector (the email address) and refuses ambiguously when two or more are connected and none is named. There is deliberately no Gmail surface — mail runs on the `email` plugin's IMAP/SMTP path, and Gmail's restricted scopes would force Google's annual third-party security assessment, whereas Calendar is only a sensitive scope. Tools — google-account-register / google-account-register-poll: connect a Google Calendar (returns a consent URL, then reports the outcome from local state); google-calendar-list: events in the next rangeDays days, recurring series expanded; google-calendar-event: one event by id; google-calendar-create / google-calendar-update / google-calendar-cancel: control events, attendees notified, update changes only the fields named; google-calendar-respond: accept, decline or tentatively accept an invitation, leaving other attendees' responses untouched; google-calendar-freebusy: busy blocks for this or named calendars; google-account-info: auth state for one connected Google account; google-account-list: every connected Google account with its own status.
+tools:
+  - name: google-account-register
+    publicAllowlist: false
+    adminAllowlist: false
+  - name: google-account-register-poll
+    publicAllowlist: false
+    adminAllowlist: false
+  - name: google-calendar-list
+    publicAllowlist: false
+    adminAllowlist: false
+  - name: google-calendar-event
+    publicAllowlist: false
+    adminAllowlist: false
+  - name: google-calendar-create
+    publicAllowlist: false
+    adminAllowlist: false
+  - name: google-calendar-update
+    publicAllowlist: false
+    adminAllowlist: false
+  - name: google-calendar-cancel
+    publicAllowlist: false
+    adminAllowlist: false
+  - name: google-calendar-respond
+    publicAllowlist: false
+    adminAllowlist: false
+  - name: google-calendar-freebusy
+    publicAllowlist: false
+    adminAllowlist: false
+  - name: google-account-info
+    publicAllowlist: false
+    adminAllowlist: false
+  - name: google-account-list
+    publicAllowlist: false
+    adminAllowlist: false
+mcp:
+  command: node
+  args:
+    - ${PLATFORM_ROOT}/lib/mcp-spawn-tee/dist/index.js
+    - ${PLATFORM_ROOT}/plugins/google/mcp/dist/index.js
+  env:
+    MCP_SPAWN_TEE_NAME: google
+    LOG_DIR: ${LOG_DIR}
+    PLATFORM_ROOT: ${PLATFORM_ROOT}
+    ACCOUNT_ID: ${ACCOUNT_ID}
+    SESSION_ID: ${SESSION_ID}
+    GOOGLE_CLIENT_ID: ${GOOGLE_CLIENT_ID}
+    GOOGLE_PUBLIC_BASE: ${GOOGLE_PUBLIC_BASE}
+    MAXY_UI_INTERNAL_PORT: ${MAXY_UI_INTERNAL_PORT}
+mcp-manifest: auto
+---
+
+# Google Calendar
+
+Per-account live Google Calendar. Read the user's real events, and create,
+update, cancel, respond to and check availability against them.
+
+## Why this exists
+
+A client sub-account cannot hold a claude.ai connector: connectors are
+authorised per client and visible only to the admin/claude.ai session, and the
+install holds one house Google identity that cannot represent each client's
+separate calendar. Before this plugin the only live-calendar path was that
+house-admin-only connector, so a client asking "what is on my calendar?" was
+dead-ended. See `references/auth.md`.
+
+## Auth
+
+Authorization-code + PKCE, not device-code. Google's device flow serves a fixed
+scope allowlist that excludes Calendar, and the out-of-band paste-a-code flow
+has been blocked since 31 January 2023, so consent must land on a real redirect.
+
+`google-account-register` mints the PKCE pair and a `state` nonce, persists them
+single-slot per account, and returns a consent URL. The user opens it on any
+device and approves. Google redirects to `/api/google/oauth/callback` on this
+install's public host, which verifies `state`, exchanges the code, resolves the
+account's email from its primary calendar, and writes encrypted tokens.
+`google-account-register-poll` then reports the outcome from local state.
+
+The client secret never enters this MCP process. A Web-application client must
+present it to refresh, so refresh is delegated to `platform/ui`, which holds it
+at `${PLATFORM_ROOT}/config/google-house.env`.
+
+## Scope
+
+One scope: `https://www.googleapis.com/auth/calendar`. The account's email is
+read from `GET /calendars/primary` (whose id is the address) rather than by
+requesting `openid`/`email`/`profile`, so consent stays minimal.
+
+## Configuration
+
+| Variable | Source | Effect when unset |
+|---|---|---|
+| `GOOGLE_CLIENT_ID` | `brand.json#googleClientId` | Plugin inert; register refuses with an actionable message |
+| `GOOGLE_PUBLIC_BASE` | install's public host origin | Register refuses; the redirect cannot be built |
+| `MAXY_ADMIN_BASE` | loopback `platform/ui` base | Defaults to `http://127.0.0.1:19301` |
+
+## Out of scope
+
+Gmail (stays on IMAP/SMTP), Contacts, Drive/Docs, push notification channels,
+recurring-series per-occurrence editing, and auto-sync with the internal
+`scheduling` plugin.

package/payload/platform/plugins/google/lib/mcp-spawn-tee/index.js

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * MCP spawn-tee — in-process stderr capture + lifecycle observability.
+ *
+ * Claude Code spawns each MCP server itself; the platform never holds a
+ * ChildProcess handle. This shim sits between Claude Code and the real MCP
+ * server: Claude Code runs `node <this> <real-entry>`, and the shim runs the
+ * real entry IN ITS OWN PROCESS via dynamic import() — one node runtime, not
+ * two. Before importing, it replaces process.stderr.write with a tee so every
+ * stderr byte the server writes is mirrored to the log sinks; stdin and stdout
+ * (the JSON-RPC channel) are never touched.
+ *
+ *   Claude Code CLI → shim (this file) = node running <real-entry> in-process
+ *        stdin/stdout : untouched (JSON-RPC channel)
+ *        stderr       : process.stderr.write teed → raw sink + passthrough
+ *
+ * Destinations:
+ *   - `${LOG_DIR}/mcp-<name>-<SESSION_ID>.log`   — raw stderr + lifecycle lines.
+ *     The sole raw sink. Task 1721 retired the per-date twin: its date was
+ *     pinned at spawn, no reader ever parsed it, and a since-removed stderr
+ *     tee wrote the same file, so every line landed twice.
+ *   - `${LOG_DIR}/mcp-<name>-nosession.log`      — the same, for a spawn with
+ *     no SESSION_ID (enumeration). One fixed file per server.
+ *   - `server.log` via the loopback log-ingest route — best-effort mirror of
+ *     the [mcp-helper] lifecycle lines.
+ *
+ * Lifecycle lines, correlation key `session=<id8> server=<name>` — unchanged:
+ *   [mcp-helper] op=spawn ... pid= entry=
+ *   [mcp-helper] op=boot  ... head=<first stderr bytes>
+ *   [mcp-helper] op=exit  ... code= signal= lifetimeMs= stderr-tail=
+ *
+ * Process model (Task 989): the shim IS the server's process. op=exit fires
+ * from process.on("exit"), so it covers a normal exit, a non-zero exit, an
+ * uncaught throw (code 1), and a catchable-signal exit (SIGTERM/SIGINT/SIGHUP,
+ * whose handlers record the signal name). An external SIGKILL is uncatchable
+ * and leaves no op=exit line — the per-session stderr tail already on disk and
+ * Claude Code's own transport-drop are the evidence for that death mode.
+ *
+ * The shim never writes to fd 1 (stdout) — that is the JSON-RPC channel.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_url_1 = require("node:url");
+const SERVER_NAME = process.env.MCP_SPAWN_TEE_NAME ?? "unknown";
+const LOG_DIR = process.env.LOG_DIR;
+const SESSION_ID = process.env.SESSION_ID;
+const PLATFORM_PORT = process.env.PLATFORM_PORT;
+const ENTRY = process.argv[2];
+const SESSION_ID8 = SESSION_ID ? SESSION_ID.slice(0, 8) : "—";
+const spawnStamp = Date.now();
+// The one raw sink (Task 1721). A sessionless spawn (rc-daemon stamps
+// SESSION_ID='' — rc-daemon.ts:513 — while still stamping LOG_DIR) shares one
+// fixed file per server rather than a date-named one: the date was never read
+// by any reader and named a process lifetime, not a day. Interleaved spawns in
+// the nosession file are separated by the [mcp-helper] op=spawn pid= lines.
+const rawSinkPath = LOG_DIR
+    ? (0, node_path_1.resolve)(LOG_DIR, SESSION_ID ? `mcp-${SERVER_NAME}-${SESSION_ID}.log` : `mcp-${SERVER_NAME}-nosession.log`)
+    : undefined;
+// Rolling tail of entry stderr for op=exit. Capped so a chatty server cannot
+// grow the buffer without bound.
+const TAIL_CAP = 2048;
+let stderrTail = "";
+let bootEmitted = false;
+let exitEmitted = false;
+let exitSignal;
+// The real stderr writer, captured before the tee replaces it. Lifecycle lines
+// and stderr passthrough both go through this so they are never re-teed into
+// the raw sink nor recursed back into the patched writer.
+const rawStderrWrite = process.stderr.write.bind(process.stderr);
+// LOG_DIR is created once, lazily, on the first successful append — not per
+// chunk. teeWrite runs on the server's own stderr hot path now, so a per-call
+// mkdirSync would be two syscalls per log line for nothing.
+let logDirReady = false;
+function appendSafe(path, data) {
+    if (!path || !LOG_DIR)
+        return;
+    try {
+        if (!logDirReady) {
+            (0, node_fs_1.mkdirSync)(LOG_DIR, { recursive: true });
+            logDirReady = true;
+        }
+        (0, node_fs_1.appendFileSync)(path, data);
+    }
+    catch {
+        /* unwritable destination — never mask primary output */
+    }
+}
+// Best-effort mirror of a lifecycle line to server.log via the loopback
+// log-ingest route. Fire-and-forget: the per-session file is authoritative, so
+// a dropped POST loses nothing. On the "exit" event the loop is stopping, so
+// the op=exit mirror may not flush — the per-session line, written sync, holds.
+function postToServerLog(suffix, level) {
+    if (!PLATFORM_PORT)
+        return;
+    try {
+        const ctrl = new AbortController();
+        const t = setTimeout(() => ctrl.abort(), 500);
+        t.unref?.(); // never let the abort timer keep the shim's event loop alive
+        void fetch(`http://127.0.0.1:${PLATFORM_PORT}/api/admin/log-ingest`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ tag: "mcp-helper", level, line: suffix }),
+            signal: ctrl.signal,
+        }).then(() => clearTimeout(t)).catch(() => clearTimeout(t));
+    }
+    catch {
+        /* fetch threw synchronously — best-effort only */
+    }
+}
+// Emit one [mcp-helper] lifecycle line: authoritative per-session file (sync,
+// survives process.exit), the shim's own stderr via the RAW writer (journald /
+// Claude Code visibility, never re-teed), and a best-effort server.log mirror.
+// `suffix` is the line body after the tag and carries no newline (the
+// log-ingest route rejects newlines).
+function emitLifecycle(suffix, level) {
+    const line = `[mcp-helper] ${suffix}\n`;
+    appendSafe(rawSinkPath, line);
+    try {
+        rawStderrWrite(line);
+    }
+    catch { /* stderr closed */ }
+    postToServerLog(suffix, level);
+}
+if (!ENTRY) {
+    emitLifecycle(`op=error session=${SESSION_ID8} server=${SERVER_NAME} reason="no entry given (argv[2] missing)"`, "error");
+    process.exit(2);
+}
+// Replace process.stderr.write with a tee: mirror every server stderr byte to
+// the raw sink, keep a rolling tail for op=exit, emit
+// op=boot on the first bytes, then pass the write through to the real stderr.
+const teeWrite = ((...args) => {
+    const chunk = args[0];
+    appendSafe(rawSinkPath, chunk); // raw sink (Task 1721)
+    const text = typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+    stderrTail = (stderrTail + text).slice(-TAIL_CAP);
+    if (!bootEmitted) {
+        bootEmitted = true;
+        const head = text.split("\n")[0].slice(0, 200);
+        emitLifecycle(`op=boot session=${SESSION_ID8} server=${SERVER_NAME} head=${JSON.stringify(head)}`, "info");
+    }
+    return rawStderrWrite(...args); // passthrough
+});
+process.stderr.write = teeWrite;
+// Catchable-signal handling. The shim drives the exit ONLY when it is the sole
+// listener for the signal — i.e. the imported entry installed no handler of its
+// own. In that case it records the signal (so op=exit carries signal=<sig>) and
+// exits with 128+signum, mirroring the prior wrapper's exit-status convention.
+//
+// When the entry DID install a handler, the shim defers entirely and records
+// nothing: the entry's handler decides the exit code, and op=exit reflects that
+// exit verbatim. This matches the prior two-process model, where a child that
+// caught the signal and exited cleanly was observed as code=0 signal=— (a clean
+// self-exit), not as a signal death. Setting exitSignal here unconditionally
+// would mislabel every graceful signal-driven shutdown as a signal kill.
+function onSignal(sig, code) {
+    return () => {
+        if (process.listenerCount(sig) === 1) {
+            exitSignal = sig;
+            process.exit(code);
+        }
+    };
+}
+process.on("SIGTERM", onSignal("SIGTERM", 143));
+process.on("SIGINT", onSignal("SIGINT", 130));
+process.on("SIGHUP", onSignal("SIGHUP", 129));
+// op=exit, emitted once from the process "exit" event. Sync-only — the loop is
+// stopping. When a catchable signal caused the exit, report code=— signal=<sig>
+// to match the prior wrapper's format; otherwise code=<exit code> signal=—.
+process.on("exit", (code) => {
+    if (exitEmitted)
+        return;
+    exitEmitted = true;
+    const lifetimeMs = Date.now() - spawnStamp;
+    const tail = stderrTail.slice(-200);
+    const codeField = exitSignal ? "—" : String(code);
+    const level = exitSignal || code !== 0 ? "error" : "info";
+    emitLifecycle(`op=exit session=${SESSION_ID8} server=${SERVER_NAME} pid=${process.pid} ` +
+        `code=${codeField} signal=${exitSignal ?? "—"} lifetimeMs=${lifetimeMs} stderr-tail=${JSON.stringify(tail)}`, level);
+});
+emitLifecycle(`op=spawn session=${SESSION_ID8} server=${SERVER_NAME} pid=${process.pid} entry=${ENTRY}`, "info");
+// Run the real MCP server in THIS process. Dynamic import() (not top-level
+// await — this file compiles to CommonJS) loads the ESM entry; a load-time
+// failure mirrors the old child spawn-error path (op=error, exit 127). The
+// op=exit handler is suppressed on this path so op=error stays the sole record.
+import((0, node_url_1.pathToFileURL)(ENTRY).href).catch((err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    exitEmitted = true;
+    emitLifecycle(`op=error session=${SESSION_ID8} server=${SERVER_NAME} reason=${JSON.stringify(`import error: ${msg}`)}`, "error");
+    process.exit(127);
+});
+//# sourceMappingURL=index.js.map

package/payload/platform/plugins/google/lib/mcp-spawn-tee/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/payload/platform/plugins/google/mcp/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@maxy/google",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test dist/__tests__/*.test.js",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}

package/payload/platform/plugins/google/references/auth.md

@@ -16,8 +16,8 @@ outcome (values themselves deliberately not recorded):
 The 604799 figure is the concrete argument for completing brand verification: in Testing,
 every connected account silently re-consents weekly. Verification removes it.
 
-Phases 1–2 may now proceed against the flow below, with one caveat: the client-secret
-storage location is an **open Phase 1 decision** (see "Open Phase 1 decision" below).
+Phases 1–2 may now proceed against the flow below. Client-secret storage is decided:
+house-only at `${PLATFORM_ROOT}/config/google-house.env` (see below).
 
 ## Original spike verdict (documentation-backed, now confirmed)
 
@@ -203,32 +203,51 @@ on that brand, exactly as `outlookClientId` does. The client id ships as the bra
 `GOOGLE_CLIENT_ID` and inherited down the spawn chain (manager unit env → PTY → MCP child).
 
 Divergence from Outlook: the recommended Web-application flow (Option B) also needs a
-**client secret**, and where that secret lives is an **open Phase 1 decision**, not a
-settled one. A brand that ships `googleClientId` empty has the plugin inert with an
+**client secret**, which lives house-only at `${PLATFORM_ROOT}/config/google-house.env`
+(decided; see below). A brand that ships `googleClientId` empty has the plugin inert with an
 actionable signal (`clientIdConfigured=false`), register refuses, and no operator action
 makes it work until the vendor client exists — mirroring Outlook's inert behaviour.
 
-### Open Phase 1 decision: there is no brand-level secret store
+### Client-secret storage: house-only (decided 2026-07-18)
 
 An earlier draft of this file said the secret is "held in the brand's secret store, the same
-way Cloudflare tokens are held". That was wrong, and Phase 1 must resolve it before the
-register path is built. The two stores that actually exist are:
-
-- **`brands/<brand>/brand.json`** — ships inside the published npm package. It can carry the
-  client **id** (public, non-secret, exactly like `outlookClientId`) and must never carry a
-  secret.
-- **`~/<brand>-code/data/accounts/<accountId>/secrets`** — where the Cloudflare master token
-  lives (`platform/plugins/cloudflare/references/api.md`). This is **account-scoped**, one
-  per install.
-
-The mismatch: the Google client secret is **per-brand** (one vendor app serves every install
-of that brand), but the only real secret store is **per-account**. Outlook never hit this
-because its device-code flow is secret-less, so there is no precedent to copy. Phase 1 must
-choose and record one of: replicate the brand secret into each install's account-scoped
-secrets at provisioning time; introduce a genuine brand-scoped secret store; or drop to
-Option A (Desktop client), whose installed-app secret Google documents as non-confidential
-and which therefore needs no confidential store at all. Do not assume a brand secret store
-exists — nothing implements one today.
+way Cloudflare tokens are held". That was wrong — no brand-level secret store exists. The
+decision, mirroring the Cloudflare master token exactly:
+
+```
+${PLATFORM_ROOT}/config/google-house.env      # mode 600, parent 700
+GOOGLE_CLIENT_ID=…
+GOOGLE_CLIENT_SECRET=…
+```
+
+Written once per install by the operator, never echoed, never in a project tree.
+`platform/plugins/cloudflare/references/api.md` already establishes this pattern for
+multi-client installs and names SiteDesk as the case: an account-wide credential inside a
+sub-account's secrets file lets that sub-account reach every other client's resources, so
+the master lives house-only at `${PLATFORM_ROOT}/config/cloudflare-house.env`, "a location
+no sub-account spawn sources". `google-house.env` is that file's twin.
+
+Rejected, with reasons:
+
+- **`brands/<brand>/brand.json`** ships inside the published npm package. It carries
+  `googleClientId` (public, exactly like `outlookClientId`, and the value the inert check
+  reads) and never the secret.
+- **`~/<brand>-code/data/accounts/<accountId>/secrets`** is wrong-scoped twice: the secret is
+  per-brand not per-account, so replicating it multiplies exposure for no benefit, and on a
+  multi-tenant install it drops a brand-wide credential into a client sub-account's own
+  directory.
+- **A Desktop-type client** (installed-app secret, documented non-confidential) would remove
+  the storage question but forces the loopback redirect and its copy-the-code-off-a-404 flow
+  on a phone, and discards the already-provisioned, verified Web-application client.
+
+House-only is sufficient here rather than merely tidier, because the token exchange runs in
+the `/api/google/oauth/callback` route inside the always-running `platform/ui` server, which
+is house-scoped. The secret never needs to reach a per-account MCP spawn.
+
+**It is a boundary of intent, not of permission.** Every account's session runs as the same
+unix user and the house path is deterministic, so an agent holding `Bash` can read the file
+regardless; OS user separation was costed and declined. Never cite house-only placement as
+proof a sub-account cannot reach the secret.
 
 ---
 
@@ -258,7 +277,7 @@ follow-up once the plugin lands (mirroring Outlook 1479/1485).
      new one."). Capture it at creation into its final destination, or plan to rotate. It is
      never pasted into a chat transcript, a shell command that lands in history, or the repo.
      Rotation is free and has no downtime: **Add secret**, store the new one, delete the old.
-     Where it should finally live is an open Phase 1 decision — see above.
+     It lives house-only at `${PLATFORM_ROOT}/config/google-house.env` — see above.
    - **Option A (fallback):** application type **Desktop app**. Copy the **Client ID**.
 5. Set `googleClientId` in the brand's `brand.json` and re-bundle:
    ```jsonc

package/payload/platform/services/claude-session-manager/dist/account-title-stores.d.ts

@@ -1,5 +1,12 @@
 import type { Logger } from './types.js';
 import { UserTitleStore } from './user-title-store.js';
+/** The account evidence a session row carries. Structural rather than the full
+ *  `SessionRow` so the `/spawn` call site, which has a cwd and no row, can
+ *  satisfy it without synthesising one. */
+export interface TitleStoreRowRef {
+    cwd: string | null;
+    accountId: string | null;
+}
 export declare class AccountTitleStores {
     private readonly accountsRoot;
     private readonly bootAccountId;
@@ -11,10 +18,16 @@ export declare class AccountTitleStores {
     /** The per-account store for `accountId`, created and loaded from disk on
      *  first access and cached thereafter. A null `accountId` (unresolvable
      *  session account) falls back to the boot account and is logged. */
-    forAccount(accountId: string | null): UserTitleStore;
-    /** The per-account store for the account a session runs under, resolved
-     *  from its spawn `cwd`. Same resolution the delete/list paths use. */
-    forSessionCwd(cwd: string | null): UserTitleStore;
+    forAccount(accountId: string | null, source?: string): UserTitleStore;
+    /** The per-account store for the account a session runs under.
+     *
+     *  `cwd` is tried first: for a live row it is read from claude's own PID
+     *  file and is the standing spawn-directory invariant (Tasks 1315/1322).
+     *  Once the process exits there is no PID file and no cwd, so the sidecar's
+     *  `accountId` — which survives the process — is the evidence that remains.
+     *  Both absent means the sidecar predates Task 983's stamping, and the boot
+     *  fallback logs it. */
+    forSessionRow(row: TitleStoreRowRef | null | undefined): UserTitleStore;
     /** The boot account's store — used for the manager's boot-ready size log. */
     bootStore(): UserTitleStore;
 }

package/payload/platform/services/claude-session-manager/dist/account-title-stores.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"account-title-stores.d.ts","sourceRoot":"","sources":["../src/account-title-stores.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAEtD,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAQ;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoC;IAEhE;wEACoE;gBACxD,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAMlD;;yEAEqE;IACrE,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,cAAc;IAwBpD;2EACuE;IACvE,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,cAAc;IAIjD,6EAA6E;IAC7E,SAAS,IAAI,cAAc;CAG5B"}
+{"version":3,"file":"account-title-stores.d.ts","sourceRoot":"","sources":["../src/account-title-stores.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAEtD;;2CAE2C;AAC3C,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CACzB;AAWD,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAQ;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoC;IAEhE;wEACoE;gBACxD,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAMlD;;yEAEqE;IACrE,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,SAAW,GAAG,cAAc;IAwBvE;;;;;;;4BAOwB;IACxB,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,GAAG,cAAc;IAuBvE,6EAA6E;IAC7E,SAAS,IAAI,cAAc;CAG5B"}