@rubytech/create-maxy-code 0.1.228 → 0.1.230

package/payload/platform/plugins/admin/skills/platform-architecture/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: platform-architecture
 description: Use when grounding any documented-surface claim about what Maxy ships — plugins, skills, specialists, install/deploy flows, internals. This is the install catalogue, not evidence of what is enabled on the current account. For install state on this account, call `capabilities-here`; for documented surface, cite the `Source:` URL inline.
-content-hash: sha256:e41db861c3d27b7540a72b1d789ff9d6ea42625edb3e8d93a08e2baae46b27c0
+content-hash: sha256:7ccf57afeb67e23745bc86265d7a65790fd4fc6cba0a659a8fb6ee3f69027e6d
 brand: maxy-code
 product-name: Maxy
 ---
@@ -3563,6 +3563,38 @@ Source: https://docs.getmaxy.com/troubleshooting.md
 
 **Diagnose if it ever recurs:** run `bash platform/scripts/__tests__/first-token-creates-stream-log.test.sh` from the install. Pass = invariant holds; any other exit = the writer-side existence contract is broken and one `[log-tee] missing-on-resolve sessionKey=<8> surface=<…>` line on `server.log` is the operator-visible signal (P0). For the duplicate-file class specifically (the 2026-05-14 recurrence trigger), `bash platform/scripts/log-adherence-check.sh` returns non-zero whenever any sessionKey has more than one `claude-agent-stream-<sk>.log` across account dirs.
 
+## Retrieving evidence from an rc-spawn session
+
+rc-spawn sessions (those started via the sidebar or the `claude rc --spawn` daemon) do not write a per-account stream log under `data/accounts/<id>/logs/`. Their evidence is the Claude Code JSONL transcript in the configDir:
+
+```
+<CLAUDE_CONFIG_DIR>/projects/<slug>/<uuid>.jsonl                      # parent session
+<…>/projects/<slug>/<uuid>.meta.json                                  # bridgeIds persistent map
+<…>/projects/<slug>/<uuid>/subagents/agent-<hex>.jsonl               # each subagent
+<…>/projects/<slug>/<uuid>/subagents/agent-<hex>.meta.json           # {"agentType",…}
+```
+
+**Retrieve a session's merged timeline:** `logs-read.sh <key>` with a bare key (no second argument) maps the key to the local `<uuid>` and prints one timestamp-ordered timeline merging the parent transcript with every subagent transcript. The key is resolved in order: a matching `<uuid>.jsonl` on disk; a `sessions/<pid>.json` whose `bridgeSessionId` matches; a `<uuid>.meta.json` whose `bridgeIds` carries the suffix (persistent — survives PID-file cleanup on clean exit); and finally a content scan of the top-level transcripts as last resort. Any accepted key form works: the `claude.ai` `session_<id>`, its bare suffix, or the `<uuid>` (or a unique uuid prefix).
+
+Every subagent `is_error` tool_result is flagged inline as `‼ SUBAGENT ERROR` with the agent type, the failing tool, and the error text. The parent session's own tool errors appear as `‼ tool error`. The two are never conflated.
+
+**Audit all silently-failed subagents:** `logs-read.sh --scan-subagent-errors [N]` walks every `subagents/agent-*.jsonl` under the configDir and lists each one carrying an `is_error` result — agent type, parent session, failing tool, error text. Optional `N` limits the scan to the `N` most-recently-modified transcripts. Use this when a delivery failure was reported but no reproduction is available.
+
+**Quick recipes:**
+
+```bash
+# A session's merged parent+subagent timeline (subagent errors flagged inline)
+~/maxy-code/platform/scripts/logs-read.sh session_<id>
+
+# Standing audit: every subagent transcript that failed silently
+~/maxy-code/platform/scripts/logs-read.sh --scan-subagent-errors
+
+# Limit audit to the 50 most-recent transcripts
+~/maxy-code/platform/scripts/logs-read.sh --scan-subagent-errors 50
+```
+
+Note: passing an explicit second argument (e.g. `logs-read.sh <key> agent-stream`) still reads the legacy per-account stream log — the bare-key JSONL path is the default when no type is given.
+
 ## A JavaScript-rendered page comes back empty from WebFetch or `url-get`
 
 **Symptom:** A page that needs JavaScript to show its content returns empty or a shell document from `WebFetch` (summary) or `url-get` (verbatim, server-rendered).

package/payload/platform/plugins/admin/skills/qr-code/SKILL.md

@@ -2,13 +2,14 @@
 name: qr-code
 description: >
   Generate QR codes from URLs, Wi-Fi credentials, contacts (vCard), email/SMS links,
-  or plain text and deliver the image inline. Trigger phrases: "QR code", "generate a
-  QR", "create a QR", "make a QR code for", or any request to share data as a scannable code.
+  or plain text. Writes the PNG under output/qr/ and tells the operator its path.
+  Trigger phrases: "QR code", "generate a QR", "create a QR", "make a QR code for",
+  or any request to share data as a scannable code.
 ---
 
 # QR Code Generation
 
-Generate QR codes from user-provided data and deliver the resulting image inline in conversation.
+Generate QR codes from user-provided data and deliver by stating the file path.
 
 ## When to Activate
 
@@ -20,9 +21,9 @@ Generate QR codes from user-provided data and deliver the resulting image inline
 
 Infer the data type from the user's input. For structured types (Wi-Fi, vCard), collect any missing fields conversationally and confirm the structured data before encoding. For simple types (URL, plain text, email, SMS), encode directly.
 
-Generate the QR image by piping the encoded string to the `qrcode` CLI via stdin — never interpolate user data into the shell command. Save the output as PNG to `/tmp/` and present the file to the user.
+Generate the QR image by calling the `qr-generate` tool with the encoded data string as the `data` parameter. The tool writes the PNG under `output/qr/` and returns the path. Tell the operator the path so they can retrieve it from the Artefacts panel or file share.
 
-If the CLI exits with an error, report the error message to the user and suggest corrections (e.g., data too long, invalid format).
+If the tool returns an error, report the message to the user and suggest corrections (e.g., data too long, invalid format).
 
 ## Boundaries
 

package/payload/platform/plugins/admin/skills/qr-code/references/data-formats.md

@@ -5,7 +5,7 @@
 Always pipe data via stdin to avoid shell injection. Never interpolate user data into the command string.
 
 ```bash
-printf '%s' 'ENCODED_DATA' | npx -y qrcode -o /tmp/qr-$(date +%s).png
+printf '%s' 'ENCODED_DATA' | npx -y qrcode -o output/qr/qr-$(date +%s).png
 ```
 
 ### Options
@@ -14,7 +14,7 @@ printf '%s' 'ENCODED_DATA' | npx -y qrcode -o /tmp/qr-$(date +%s).png
 |--------|------|--------|
 | Size | `--width` | Small: 200, Medium: 400 (default), Large: 800 |
 | Error correction | `--error-correction-level` | L (7%), M (15%, default), Q (25%), H (30%) |
-| SVG output | `--type svg -o /tmp/qr-$(date +%s).svg` | Use instead of PNG when user requests SVG |
+| SVG output | `--type svg -o output/qr/qr-$(date +%s).svg` | Use instead of PNG when user requests SVG |
 
 Higher error correction allows the QR code to remain scannable even if partially damaged, but reduces data capacity.
 

package/payload/platform/plugins/admin/skills/unzip-attachment/SKILL.md

@@ -49,7 +49,7 @@ See [references/safety.md](references/safety.md) for the precise shell commands,
 6. **Emit the done log line** — `[skill:unzip] done attachmentId=<uuid> entries=<n> uncompressed=<bytes>`.
 7. **Inventory + propose.** Reply to the operator with: top-level entries (first-level subdirectories and top-level files, up to ~20), total file count, total uncompressed bytes. For each entry class, propose **one** concrete follow-up:
    - `.md`, `.txt` → "ingest into memory via `memory-ingest`?"
-   - `.png`, `.jpg`, `.pdf` → "re-attach via the `file-presentation` skill so the user sees the file?"
+   - `.png`, `.jpg`, `.pdf` → "state their location under `extracted/<attachmentId>/` — the operator retrieves them from the Artefacts panel or file share."
    - unknown / binary / source → list only. No proposal.
 
 On any refusal step the operator gets the refusal message verbatim, no re-try, no silent substitution — per the loud-failure protocol in IDENTITY.md.

package/payload/platform/plugins/cloudflare/references/dashboard-guide.md

@@ -140,6 +140,34 @@ opens an SSH prompt to the Pi.
 
 ---
 
+## Create a URL Rewrite Rule
+
+A URL Rewrite Rule silently rewrites the path the origin server receives without changing the URL the visitor sees in their browser. Use this when you want a custom domain root (e.g. `getmaxy.com/`) to serve a path that lives elsewhere on the origin (e.g. `/sites/getmaxy/`) without redirecting the visitor.
+
+This is **not** the same as a Page Rule redirect. Page Rules issue a visible 301/302 to the browser; a Rewrite Rule changes only what the origin receives, transparently.
+
+1. Click **Websites** in the sidebar, then click the zone.
+2. Click **Rules** in the left-hand sidebar, then **Overview**.
+3. Click **Create rule**, then select **URL Rewrite Rule**.
+   Alternatively, click **Create from template** and choose **"Rewrite path of moved section"** for a pre-filled starting point.
+4. Enter a descriptive **Rule name** (e.g. `getmaxy apex → marketing site`).
+5. Under **If incoming requests match**, select **Custom filter expression** and enter the expression. For a match on bare domain and www:
+   ```
+   (http.host eq "example.com") or (http.host eq "www.example.com")
+   ```
+6. Under **Then**, set **Path** → **Rewrite to** → **Dynamic** and enter the expression:
+   ```
+   concat("/sites/mysite", http.request.uri.path)
+   ```
+   Leave **Query string** on **Preserve** (unchanged).
+7. Click **Deploy**.
+
+No server restart is needed. Verify with `curl -s https://<domain>/ | head` — the response should be the site's HTML, not the agent SPA `<div id="root">`.
+
+**When the zone cert misroutes:** if `cloudflared tunnel route dns` is run for a hostname in a zone the cert was not authorised for at `tunnel login`, it silently creates a record in the wrong zone (appends the cert's zone as a suffix). Check the emitted record name in the command output; if it has an unexpected suffix, delete the stray record via `DNS → Records` and create the CNAME manually in the correct zone instead.
+
+---
+
 ## Where tunnels live in the dashboard (as of 2026-04)
 
 Tunnels are under **Zero Trust** → **Networks** → **Tunnels**. This is not in the top-level sidebar — it is under the Zero Trust sub-dashboard, which itself appears in the main sidebar. Cloudflare has moved this location in the past. If **Networks** → **Tunnels** is not visible under Zero Trust, the label has likely been renamed; look for "Tunnels" under Networks or Access.

package/payload/platform/plugins/cloudflare/references/serving-published-sites.md

@@ -0,0 +1,73 @@
+# Serving a published static site at a custom domain — recipe + known gaps
+
+Notes captured 2026-06-01 during the getmaxy.com apex setup. The existing runbook
+(`manual-setup.md`) covers getting a hostname to *reach* the server, but not the
+application-layer step of making that hostname *serve a published site at its root*.
+These are the gaps that cost time, and the recipe that works.
+
+---
+
+## Gap 1 — an alias hostname serves the PUBLIC-AGENT SPA at `/`, not a published site
+
+Adding a hostname to `alias-domains.json` (so `isPublicHost()` is true) makes the
+platform serve the **public chat-agent landing** (`brandedPublicHtml`) at `/`. It does
+**not** serve a published static site. Published sites live at `/sites/<slug>/` and are
+reachable under any alias host at that path, but the bare root always renders the agent SPA.
+
+There is **no per-domain → landing-site mapping** in the platform. `resolveDefaultSlug()`
+reads `account.defaultAgent` (a chat agent), never a site slug. Confirmed by reading
+`server/server.js` `app41.get("/")` and the `/sites` route.
+
+**Implication:** "point getmaxy.com at the getmaxy site" is two jobs, not one:
+1. Routing (DNS + tunnel ingress + alias-domains) — gets the host to the server.
+2. Root-serving (below) — makes `/` render the site instead of the agent SPA.
+
+State this split to the operator up front. Do not imply step 1 alone will show the site.
+
+---
+
+## Recipe — serve `/sites/<slug>/` at a custom domain root
+
+1. **Ingress** — add the hostname(s) to `${CFG_DIR}/config.yml` (per `manual-setup.md`
+   multi-ingress section), validate, reload the brand service.
+2. **alias-domains.json** — add the hostname(s) so the public path filter allows `/sites/`.
+3. **DNS** — apex via dashboard CNAME (`@` → `<UUID>.cfargotunnel.com`, proxied); `www` via
+   dashboard too if the cert is not authorised for the zone (see Gap 2).
+4. **URL Rewrite Rule** (Cloudflare dashboard) — rewrite every path on the host to the site
+   subtree, invisibly (visitor URL stays clean):
+   - **Rules → Overview → Create rule → URL Rewrite Rule** (or **Create from template →
+     "Rewrite path of moved section"**).
+   - If — Custom filter expression: `(http.host eq "<domain>") or (http.host eq "www.<domain>")`
+   - Then — Path → Rewrite to → **Dynamic**: `concat("/sites/<slug>", http.request.uri.path)`
+   - Leave query string unchanged. Deploy.
+   - Effect: `<domain>/` → origin `/sites/<slug>/` → `index.html`; `<domain>/foo.webp` →
+     `/sites/<slug>/foo.webp`. Works because `/sites/` is in `PUBLIC_ALLOWED_PREFIXES`.
+
+No server restart needed for step 4. Verify: `curl -s https://<domain>/ | head` shows the
+site markup, not the SPA `<div id="root">`.
+
+---
+
+## Gap 2 — `tunnel route dns` misroutes ANY hostname whose zone the cert isn't authorised for
+
+`manual-setup.md` Step 4 warns about apex misrouting. The same failure hits **non-apex**
+hostnames too: if the login cert is authorised for zone A (e.g. `maxy.bot`) but you route a
+host in zone B (e.g. `www.getmaxy.com`), `cloudflared` appends zone A and silently creates
+`www.getmaxy.com.maxy.bot` under the wrong zone — exit 0, looks successful.
+
+**Rule:** the CLI can only route hostnames in a zone the cert was authorised for at
+`tunnel login`. For a hostname in any other zone (apex OR subdomain), create the CNAME in
+the dashboard, or re-run `cloudflared tunnel login` and authorise the new zone first. Do not
+trust exit 0 — check the emitted record name in the output (`Added CNAME <name>`); if it has
+an extra zone suffix, it misrouted and the stray record needs dashboard deletion.
+
+---
+
+## Gap 3 — dashboard labels are stale in `dashboard-guide.md`
+
+- URL rewrites are **not** called "Transform Rules" in the current UI. They are under
+  **Rules → Overview → Create rule → URL Rewrite Rule**, with templates via **Create from
+  template** (the relevant one: **"Rewrite path of moved section"**).
+- **Page Rules is the wrong tool** for transparent rewrites — it only does forwarding
+  (HTTP 301/302 redirects) with a visible URL change. Do not suggest Page Rules when the
+  requirement is an invisible origin-path rewrite.

package/payload/platform/plugins/cloudflare/skills/setup-tunnel/SKILL.md

@@ -40,7 +40,7 @@ When local Cloudflare state is corrupt or the operator wants to start from a kno
 
 ## Dashboard guidance
 
-For operations only the Cloudflare dashboard can do (sign in, switch accounts, add a site, edit an apex CNAME, verify zone nameservers, delete stale CNAMEs), quote the relevant click-path from `references/dashboard-guide.md` verbatim. The operator follows it in their browser. The agent does not drive the dashboard programmatically.
+For operations only the Cloudflare dashboard can do (sign in, switch accounts, add a site, edit an apex CNAME, verify zone nameservers, delete stale CNAMEs, create URL Rewrite Rules), quote the relevant click-path from `references/dashboard-guide.md` verbatim. The operator follows it in their browser. The agent does not drive the dashboard programmatically.
 
 ## Tool discipline — binding
 

package/payload/platform/plugins/docs/references/troubleshooting.md

@@ -8,6 +8,38 @@
 
 **Diagnose if it ever recurs:** run `bash platform/scripts/__tests__/first-token-creates-stream-log.test.sh` from the install. Pass = invariant holds; any other exit = the writer-side existence contract is broken and one `[log-tee] missing-on-resolve sessionKey=<8> surface=<…>` line on `server.log` is the operator-visible signal (P0). For the duplicate-file class specifically (the 2026-05-14 recurrence trigger), `bash platform/scripts/log-adherence-check.sh` returns non-zero whenever any sessionKey has more than one `claude-agent-stream-<sk>.log` across account dirs.
 
+## Retrieving evidence from an rc-spawn session
+
+rc-spawn sessions (those started via the sidebar or the `claude rc --spawn` daemon) do not write a per-account stream log under `data/accounts/<id>/logs/`. Their evidence is the Claude Code JSONL transcript in the configDir:
+
+```
+<CLAUDE_CONFIG_DIR>/projects/<slug>/<uuid>.jsonl                      # parent session
+<…>/projects/<slug>/<uuid>.meta.json                                  # bridgeIds persistent map
+<…>/projects/<slug>/<uuid>/subagents/agent-<hex>.jsonl               # each subagent
+<…>/projects/<slug>/<uuid>/subagents/agent-<hex>.meta.json           # {"agentType",…}
+```
+
+**Retrieve a session's merged timeline:** `logs-read.sh <key>` with a bare key (no second argument) maps the key to the local `<uuid>` and prints one timestamp-ordered timeline merging the parent transcript with every subagent transcript. The key is resolved in order: a matching `<uuid>.jsonl` on disk; a `sessions/<pid>.json` whose `bridgeSessionId` matches; a `<uuid>.meta.json` whose `bridgeIds` carries the suffix (persistent — survives PID-file cleanup on clean exit); and finally a content scan of the top-level transcripts as last resort. Any accepted key form works: the `claude.ai` `session_<id>`, its bare suffix, or the `<uuid>` (or a unique uuid prefix).
+
+Every subagent `is_error` tool_result is flagged inline as `‼ SUBAGENT ERROR` with the agent type, the failing tool, and the error text. The parent session's own tool errors appear as `‼ tool error`. The two are never conflated.
+
+**Audit all silently-failed subagents:** `logs-read.sh --scan-subagent-errors [N]` walks every `subagents/agent-*.jsonl` under the configDir and lists each one carrying an `is_error` result — agent type, parent session, failing tool, error text. Optional `N` limits the scan to the `N` most-recently-modified transcripts. Use this when a delivery failure was reported but no reproduction is available.
+
+**Quick recipes:**
+
+```bash
+# A session's merged parent+subagent timeline (subagent errors flagged inline)
+~/maxy-code/platform/scripts/logs-read.sh session_<id>
+
+# Standing audit: every subagent transcript that failed silently
+~/maxy-code/platform/scripts/logs-read.sh --scan-subagent-errors
+
+# Limit audit to the 50 most-recent transcripts
+~/maxy-code/platform/scripts/logs-read.sh --scan-subagent-errors 50
+```
+
+Note: passing an explicit second argument (e.g. `logs-read.sh <key> agent-stream`) still reads the legacy per-account stream log — the bare-key JSONL path is the default when no type is given.
+
 ## A JavaScript-rendered page comes back empty from WebFetch or `url-get`
 
 **Symptom:** A page that needs JavaScript to show its content returns empty or a shell document from `WebFetch` (summary) or `url-get` (verbatim, server-rendered).

package/payload/platform/services/claude-session-manager/dist/http-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-server.d.ts","sourceRoot":"","sources":["../src/http-server.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAM3B,OAAO,EAgBL,KAAK,SAAS,EAEf,MAAM,kBAAkB,CAAA;AAezB,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,iBAAiB,CAAA;AAE5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAgF9E,eAAO,MAAM,kBAAkB,QAA2B,CAAA;AAI1D,MAAM,WAAW,QAAS,SAAQ,IAAI,CAAC,SAAS,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAC7E,OAAO,EAAE,SAAS,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,iBAAiB,EAAE,MAAM,CAAA;IACzB,kBAAkB,EAAE,WAAW,CAAA;IAC/B,eAAe,EAAE,aAAa,CAAA;IAC9B;kFAC8E;IAC9E,cAAc,EAAE,cAAc,CAAA;CAC/B;AA4LD;;;kEAGkE;AAClE,MAAM,MAAM,OAAO,GAAG,IAAI,GAAG;IAC3B,2BAA2B,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACpD;;;+CAG2C;IAC3C,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAChD,CAAA;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAs5CpD"}
+{"version":3,"file":"http-server.d.ts","sourceRoot":"","sources":["../src/http-server.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAM3B,OAAO,EAgBL,KAAK,SAAS,EAEf,MAAM,kBAAkB,CAAA;AAezB,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,iBAAiB,CAAA;AAE5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAgF9E,eAAO,MAAM,kBAAkB,QAA2B,CAAA;AAI1D,MAAM,WAAW,QAAS,SAAQ,IAAI,CAAC,SAAS,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAC7E,OAAO,EAAE,SAAS,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,iBAAiB,EAAE,MAAM,CAAA;IACzB,kBAAkB,EAAE,WAAW,CAAA;IAC/B,eAAe,EAAE,aAAa,CAAA;IAC9B;kFAC8E;IAC9E,cAAc,EAAE,cAAc,CAAA;CAC/B;AA4LD;;;kEAGkE;AAClE,MAAM,MAAM,OAAO,GAAG,IAAI,GAAG;IAC3B,2BAA2B,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACpD;;;+CAG2C;IAC3C,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAChD,CAAA;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAg7CpD"}

package/payload/platform/services/claude-session-manager/dist/http-server.js

@@ -1456,6 +1456,14 @@ export function buildHttpApp(deps) {
             argv.push(name);
         if (sessionId)
             argv.push(mode === 'resume' ? '--resume' : '--session-id', sessionId);
+        // Task 592 — per-spawn bypass-permissions waiver. The brand settings.json
+        // carries `defaultMode: bypassPermissions` (Task 583); without this flag
+        // the first-time "WARNING: … 1. No, exit  2. Yes, I accept" disclaimer
+        // hangs the spawn and times out waitForPid. Both documented skip keys are
+        // waived so the disclaimer is suppressed whatever mode the session resolves
+        // to. Per Task 574 doctrine the waiver is per-spawn (never written into
+        // settings.json / .claude.json, which would permanently waive it).
+        argv.push('--settings', JSON.stringify({ skipDangerousModePermissionPrompt: true, skipAutoPermissionPrompt: true }));
         const env = buildRcChildEnv({
             accountId: deps.accountId,
             uiPort: process.env.MAXY_UI_INTERNAL_PORT ?? '',
@@ -1587,8 +1595,13 @@ export function buildHttpApp(deps) {
         // — and the natural-exit path inside `pty.onExit →
         // handlePtyNaturalExit`. The tracker remains in `livePtys` for the
         // session's lifetime.
-        void deps.watcher
-            .waitForPid(pty.pid, deps.pidFileTimeoutMs)
+        //
+        // Task 592 — capture the promise once so the fire-and-forget logging
+        // and the bounded bridgeSessionId await share the same resolution.
+        const RC_SPAWN_URL_WAIT_MS = 12_000;
+        const waitPidPromise = deps.watcher.waitForPid(pty.pid, deps.pidFileTimeoutMs);
+        // Fire-and-forget: unchanged logging contract.
+        void waitPidPromise
             .then((row) => {
             pidFileSeen = true;
             const ageMs = Date.now() - start;
@@ -1609,12 +1622,24 @@ export function buildHttpApp(deps) {
                 err: JSON.stringify(err instanceof Error ? err.message : String(err)),
             });
         });
+        // Task 592 — bounded await: surface bridgeSessionId in the response
+        // so the client can open the exact session URL. The pid file appears
+        // ~2-3 s in production; the 12 s bound is well inside that window.
+        // On timeout (or waitForPid rejection) bridgeSessionId stays null and
+        // the client falls back to the bare claude.ai/code URL.
+        let bridgeSessionId = null;
+        const timedPidRow = await Promise.race([
+            waitPidPromise.then((r) => r).catch(() => null),
+            new Promise((resolve) => setTimeout(() => resolve(null), RC_SPAWN_URL_WAIT_MS)),
+        ]);
+        if (timedPidRow)
+            bridgeSessionId = timedPidRow.bridgeSessionId ?? null;
         // Every rc-spawn child runs inside a `systemd-run --user --scope`
         // unit driven by node-pty; the operator-visible spawnMethod marker
         // is kept stable so server.log greps survive the Task 573 cleanup.
-        deps.logger(`[sessions-rc-resume] mode=${mode} sessionId=${sessionId ?? 'none'} jsonlPath=${existingJsonlPath ?? 'none'} name=${name ?? 'none'} spawnedPid=${pty.pid} bridgeId=pending spawnMethod=systemd-scope env.CLAUDE_CONFIG_DIR=${deps.claudeConfigDir}`);
+        deps.logger(`[sessions-rc-resume] mode=${mode} sessionId=${sessionId ?? 'none'} jsonlPath=${existingJsonlPath ?? 'none'} name=${name ?? 'none'} spawnedPid=${pty.pid} bridgeId=${bridgeSessionId ?? 'pending'} spawnMethod=systemd-scope env.CLAUDE_CONFIG_DIR=${deps.claudeConfigDir}`);
         timed(deps.logger, 'POST', '/rc-spawn', 200, Date.now() - start);
-        return c.json({ spawnedPid: pty.pid, sessionId: sessionId ?? null });
+        return c.json({ spawnedPid: pty.pid, sessionId: sessionId ?? null, bridgeSessionId });
     });
     return app;
 }