@yolo-labs/yolobridge 0.2.0 → 0.7.1

package/dist/api-client.js

@@ -29,12 +29,40 @@ async function parseErrorBody(res) {
         return { message: `HTTP ${res.status}` };
     }
 }
-export async function attach(cfg, workspaceId, hostLabel) {
+/**
+ * `POST /v1/workspaces/:workspaceId/yolobridge/attach`.
+ *
+ * `scopedToken` / `scopedTokenExpiresAt` are the workspace-scoped daemon
+ * credential common-api mints at attach
+ * (`docs/YOLOBRIDGE_SCOPED_CREDENTIAL_PLAN.md`): a token confined to THIS
+ * workspace's YoloBridge surface, which the post-attach calls
+ * (`detach`/`openStream`/`postHeartbeat`/`postReadOutputReply`) use instead of
+ * the full-account token. `scopedTokenExpiresAt` is absolute epoch-ms computed
+ * server-side at mint, so the refresh schedule never requires decoding the JWT.
+ *
+ * REQUIRED since 0.7.0 (card 09, D6 — "no backwards support"). Both fields or
+ * neither is still the rule; what changed is that "neither" is now an ERROR
+ * rather than a degrade. This used to be optional to protect a daemon binary
+ * frozen on a laptop against a common-api predating the mint — but Boundary B
+ * now refuses an account token on every post-attach route, so a daemon that
+ * attaches without a scoped credential cannot do anything afterwards. Accepting
+ * the response would buy it exactly one successful call and then a 403 loop
+ * with no diagnosis; failing here names the real problem at the one moment the
+ * operator is still watching the terminal.
+ *
+ * Every other exported function's signature is unchanged: they still take "the
+ * bearer token to send" via `ApiClientConfig`, and which token that is remains
+ * the caller's decision.
+ */
+export async function attach(cfg, workspaceId, hostLabel, remoteHost) {
     const fetchImpl = cfg.fetchImpl ?? fetch;
     const res = await fetchImpl(`${base(cfg)}/v1/workspaces/${workspaceId}/yolobridge/attach`, {
         method: 'POST',
         headers: { ...authHeaders(cfg), 'Content-Type': 'application/json' },
-        body: JSON.stringify(hostLabel ? { hostLabel } : {}),
+        body: JSON.stringify({
+            ...(hostLabel ? { hostLabel } : {}),
+            ...(remoteHost && Object.values(remoteHost).some(Boolean) ? { remoteHost } : {}),
+        }),
     });
     if (!res.ok) {
         const { message, code } = await parseErrorBody(res);
@@ -44,7 +72,54 @@ export async function attach(cfg, workspaceId, hostLabel) {
     if (typeof body?.tileId !== 'string' || typeof body?.attachmentId !== 'string') {
         throw new YoloBridgeApiError('attach returned an unexpected shape', res.status);
     }
-    return { tileId: body.tileId, attachmentId: body.attachmentId };
+    // Both-or-neither, and "neither" is a failure (see the doc comment). A token
+    // with no expiry cannot be renewed on time and an expiry with no token is
+    // nothing, so a half-pair is refused by the same check — there is no shape
+    // here that yields a usable-but-unschedulable credential.
+    if (typeof body?.scopedToken !== 'string' || typeof body?.scopedTokenExpiresAt !== 'number') {
+        throw new YoloBridgeApiError('attach returned no workspace-scoped credential — this server cannot host a YoloBridge daemon', res.status);
+    }
+    return {
+        tileId: body.tileId,
+        attachmentId: body.attachmentId,
+        scopedToken: body.scopedToken,
+        scopedTokenExpiresAt: body.scopedTokenExpiresAt,
+    };
+}
+/**
+ * `POST /v1/workspaces/:workspaceId/yolobridge/attach/:attachmentId/refresh` —
+ * renew the workspace-scoped daemon credential (card 07,
+ * docs/YOLOBRIDGE_SCOPED_CREDENTIAL_PLAN.md, D1).
+ *
+ * `cfg.accessToken` MUST be the scoped token being renewed: this endpoint
+ * authenticates by the presented credential itself ("proof of recent prior
+ * possession"), so the token IS the request's identity. There is no refresh
+ * credential — deliberately. The daemon never holds a long-lived one, which is
+ * the entire point of the scoping work: a stolen laptop yields a credential
+ * that expires in an hour and can only be renewed while it is still fresh.
+ *
+ * The server accepts a token that has JUST expired, within a narrow grace
+ * window (15 minutes server-side), so a clock skew or a short sleep across the
+ * scheduled renewal recovers instead of forcing a re-attach. Past that, the
+ * refusal is terminal and the remedy is `yolo-bridge attach`.
+ *
+ * Unlike `attach`, the response shape is validated STRICTLY: this call only
+ * ever reaches a server that already issued a scoped token, so a reply missing
+ * one is a genuine protocol disagreement, not an old-server degrade. Returning
+ * a half-pair would leave the caller unable to schedule the next renewal.
+ */
+export async function refreshScopedToken(cfg, workspaceId, attachmentId) {
+    const fetchImpl = cfg.fetchImpl ?? fetch;
+    const res = await fetchImpl(`${base(cfg)}/v1/workspaces/${workspaceId}/yolobridge/attach/${encodeURIComponent(attachmentId)}/refresh`, { method: 'POST', headers: authHeaders(cfg) });
+    if (!res.ok) {
+        const { message, code } = await parseErrorBody(res);
+        throw new YoloBridgeApiError(`scoped credential refresh failed: ${message}`, res.status, code);
+    }
+    const body = (await res.json());
+    if (typeof body?.scopedToken !== 'string' || typeof body?.scopedTokenExpiresAt !== 'number') {
+        throw new YoloBridgeApiError('scoped credential refresh returned an unexpected shape', res.status);
+    }
+    return { scopedToken: body.scopedToken, scopedTokenExpiresAt: body.scopedTokenExpiresAt };
 }
 /**
  * `GET /v1/workspaces/selectable` — slim `{id,name,status}` list of the
@@ -78,6 +153,16 @@ export async function listSelectableWorkspaces(cfg) {
     }
     return workspaces;
 }
+/**
+ * `DELETE /v1/workspaces/:workspaceId/yolobridge/attach/:attachmentId`.
+ *
+ * `cfg.accessToken` must be the WORKSPACE-SCOPED credential, not the account
+ * token: this is one of the daemon-only routes Boundary B guards, and an
+ * account token is refused there with 403 YOLOBRIDGE_SCOPED_TOKEN_REQUIRED
+ * (card 09). Both callers comply — the daemon's own cleanup path via
+ * `scopedCfg()`, and standalone `yolo-bridge detach` via the credential
+ * `attachment.json` persisted at attach.
+ */
 export async function detach(cfg, workspaceId, attachmentId) {
     const fetchImpl = cfg.fetchImpl ?? fetch;
     const res = await fetchImpl(`${base(cfg)}/v1/workspaces/${workspaceId}/yolobridge/attach/${attachmentId}`, {

package/dist/attach-cmd.js

@@ -25,7 +25,8 @@ import { nextBackoffMs } from './reconnect.js';
 import { deliverPromptToLocalAgent, captureLocalAgentOutput } from './local-agent.js';
 import * as apiClient from './api-client.js';
 import { refreshAccessToken as refreshAccessTokenApi } from './device-auth.js';
-import { loadAuth, saveAuth, saveAttachment, clearAttachment } from './config-store.js';
+import { loadAuth, saveAuth, loadAttachment, saveAttachment, clearAttachment, } from './config-store.js';
+import { recordConnectionEvent, resetConnectionState, } from './connection-state.js';
 const DEFAULT_AUTH_URL = 'https://auth.yololabs.ai';
 /** Refresh once the access token has less than this much validity left.
  * Production access tokens live 24h; 5min gives ample margin against a
@@ -38,9 +39,39 @@ const DEFAULT_REFRESH_BUFFER_MS = 5 * 60_000;
  * its own — which, by design, it doesn't. Small enough to be prompt,
  * cheap enough to not matter (a no-op comparison on every tick). */
 const STOP_POLL_INTERVAL_MS = 250;
+/**
+ * Fraction of the SCOPED credential's lifetime to spend before renewing it
+ * (card 07, docs/YOLOBRIDGE_SCOPED_CREDENTIAL_PLAN.md D1). At the server's 1h
+ * TTL this renews ~45 minutes in.
+ *
+ * Deliberately BEFORE expiry, not after: the server's grace window for a
+ * just-expired token is a SKEW allowance, not a refresh interval. Spending it
+ * on the normal path would leave nothing in reserve for the cases it exists
+ * for — a laptop that slept, a clock that drifted, a network outage that
+ * happened to straddle the scheduled renewal. On the happy path the daemon
+ * never presents an expired credential at all.
+ *
+ * Derived from the expiry the SERVER reported (`scopedTokenExpiresAt`), never
+ * from a TTL constant duplicated here: this binary sits frozen on a laptop for
+ * months and must follow whatever lifetime the server it is talking to today
+ * actually issued.
+ */
+const SCOPED_REFRESH_AT_FRACTION = 0.75;
+/**
+ * The daemon's own copy of the server's `YOLOBRIDGE_REFRESH_MAX_EXPIRED_MS`
+ * (15 minutes) — how long past expiry a renewal can still succeed.
+ *
+ * A copy, not an import: the two live on opposite sides of a frozen-binary
+ * seam. It is used ONLY to decide when to stop retrying and tell the operator
+ * to re-attach; the server is the authority on whether any given renewal is
+ * accepted. A copy that drifted SHORT makes this daemon give up slightly early
+ * (an honest re-attach), and one that drifted LONG makes it retry a few
+ * doomed requests — neither can widen the server's actual window.
+ */
+const SCOPED_REFRESH_GRACE_MS = 15 * 60_000;
 const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 export async function runAttachDaemon(deps) {
-    const { workspaceId, commonApiBaseUrl, hostLabel, auth, env, io, fetchImpl, } = deps;
+    const { workspaceId, commonApiBaseUrl, hostLabel, remoteHost, auth, env, io, fetchImpl, } = deps;
     const shouldStop = deps.shouldStop ?? (() => false);
     const sleep = deps.sleep ?? defaultSleep;
     const log = deps.log ?? ((line) => process.stdout.write(`${line}\n`));
@@ -52,20 +83,183 @@ export async function runAttachDaemon(deps) {
     const refreshBufferMs = deps.refreshBufferMs ?? DEFAULT_REFRESH_BUFFER_MS;
     const authBaseUrl = deps.authBaseUrl ?? process.env.YOLOBRIDGE_AUTH_URL ?? DEFAULT_AUTH_URL;
     const doRefresh = deps.refreshAccessToken ?? refreshAccessTokenApi;
-    const cfg = { commonApiBaseUrl, accessToken: auth.accessToken, fetchImpl };
+    /**
+     * THE ACCOUNT identity. Full-account bearer from `yolo-bridge login`, and the
+     * ONLY thing `ensureFreshToken` may write to. Used for exactly one call —
+     * `attach` — because that call is what CREATES the scope; there is nothing
+     * narrower to present until it returns.
+     */
+    const accountCfg = { commonApiBaseUrl, accessToken: auth.accessToken, fetchImpl };
     let currentAuth = auth;
+    /**
+     * THE ATTACHMENT identity — the workspace-scoped credential common-api mints
+     * at attach (docs/YOLOBRIDGE_SCOPED_CREDENTIAL_PLAN.md). Every post-attach
+     * call presents this instead of the account token, so a stolen laptop yields
+     * a credential confined to ONE workspace's YoloBridge surface.
+     */
+    const scopedCredential = {};
+    /**
+     * Write `auth.json` back, NEVER with the account refresh token (cards 08+09).
+     *
+     * The access token expires on its own; the REFRESH token is the durable key
+     * to the whole account, and this daemon does not need it on disk to do its
+     * job. Once `attach` has exchanged it for a workspace-scoped credential the
+     * daemon's entire YoloBridge traffic runs on that instead, so a leaked
+     * `auth.json` should be worth at worst a self-expiring access token.
+     *
+     * UNCONDITIONAL since 0.7.0. Card 08 made the drop conditional on a scoped
+     * token being in hand, to protect the DEGRADED path — a common-api predating
+     * the mint, where `scopedCfg()` fell back to the account token and the daemon
+     * ran the whole session on it. Boundary B deleted that path: an account token
+     * is now refused on every post-attach route, so there is no session left for
+     * the refresh token to be load-bearing in, and `runAttachDaemon` fails at
+     * attach rather than continuing without a scoped credential.
+     *
+     * ONE CONSEQUENCE, ACCEPTED AND NOT HIDDEN: the pre-attach
+     * `ensureFreshToken()` call also writes through here, so a rotation that
+     * happens moments BEFORE a failed attach drops the refresh token without an
+     * exchange ever completing. The operator keeps a ~24h access token and must
+     * `yolo-bridge login` again after that. Narrow (it needs a near-expiry token
+     * AND a failing attach in the same run) and it errs toward less crown-jewel
+     * material on disk, which is the direction this work exists to push.
+     *
+     * Every `auth.json` write in this file goes through here rather than calling
+     * `saveAuth` directly, so an account rotation cannot quietly re-persist the
+     * very token the attach exchange just dropped.
+     */
+    function persistAccountAuth() {
+        saveAuth({ ...currentAuth, refreshToken: undefined }, env, io);
+    }
+    /**
+     * Record a freshly-issued scoped credential and schedule its renewal.
+     *
+     * `refreshAtMs` is computed from THIS moment plus 75% of the remaining
+     * lifetime the server just advertised, so a credential handed over already
+     * part-used (a slow attach round trip, a clock a little ahead) still renews
+     * with margin rather than at a fixed offset from an issue time this daemon
+     * never observed. A non-positive remaining lifetime schedules the renewal
+     * immediately rather than in the past.
+     */
+    function rememberScopedCredential(token, expiresAtMs) {
+        const at = now();
+        const remaining = Math.max(0, expiresAtMs - at);
+        scopedCredential.token = token;
+        scopedCredential.expiresAtMs = expiresAtMs;
+        scopedCredential.refreshAtMs = at + Math.floor(remaining * SCOPED_REFRESH_AT_FRACTION);
+    }
+    /**
+     * Deliberately a FACTORY over a separate holder, not a second mutable config
+     * object.
+     *
+     * The trap this avoids: `ensureFreshToken` refreshes the ACCOUNT token on a
+     * ~24h cadence and writes `accountCfg.accessToken` in place. Had the scoped
+     * token been assigned onto that same object, the next refresh tick would
+     * silently overwrite it and the daemon would quietly revert to sending the
+     * account token — with every test still green. Because the scoped value lives
+     * in its own holder that `ensureFreshToken` has no reference to, the revert
+     * is structurally impossible rather than merely avoided.
+     *
+     * NO ACCOUNT FALLBACK, since 0.7.0 (card 09). It used to read
+     * `?? currentAuth.accessToken` so a daemon talking to a common-api predating
+     * the mint could still work. Boundary B refuses an account token on every
+     * route this config is used for, so the fallback can no longer produce a
+     * working call — it can only convert one legible failure at attach into an
+     * unexplained 403 on every heartbeat for the rest of the session. The daemon
+     * stops at attach instead (see the `scopedCredential.token` check below), so
+     * by the time anything calls this a scoped token is always in hand; the throw
+     * is a structural backstop for a future caller that reorders that, not a
+     * reachable path today.
+     */
+    function scopedCfg() {
+        const accessToken = scopedCredential.token;
+        if (!accessToken) {
+            throw new Error('internal: scopedCfg() called before a workspace-scoped credential was obtained');
+        }
+        return { commonApiBaseUrl, accessToken, fetchImpl };
+    }
+    // Declared up here (rather than at their first assignment below) purely
+    // so `noteConnection` can close over `attachmentId` without a temporal-
+    // dead-zone throw: the very first `ensureFreshToken()` call runs before
+    // the attach round trip has produced one.
+    let attachmentId = '';
+    let tileId = '';
+    let attachedAt = '';
+    /**
+     * Write `attachment.json`, INCLUDING the current scoped credential (card 08).
+     *
+     * The credential is persisted so a daemon that dies and is restarted while
+     * its scoped token is still renewable resumes THIS attachment rather than
+     * needing a fresh one. That is not a convenience: this card also drops the
+     * account refresh token, so once the account access token expires there is
+     * nothing else left on the machine to authenticate a new `attach` with — the
+     * stored scoped token is the only way a long-lived daemon survives its own
+     * restart without sending the operator back to `yolo-bridge login`.
+     *
+     * Same file, same writer, same 0600 posture as before — no new file and no
+     * new mode. Called at attach and again after every renewal, so a restart
+     * resumes from the CURRENT credential rather than the one attach happened to
+     * hand out hours ago.
+     */
+    function persistAttachment() {
+        saveAttachment({
+            workspaceId,
+            tileId,
+            attachmentId,
+            attachedAt,
+            ...(scopedCredential.token && scopedCredential.expiresAtMs !== undefined
+                ? { scopedToken: scopedCredential.token, scopedTokenExpiresAtMs: scopedCredential.expiresAtMs }
+                : {}),
+        }, env, io);
+    }
+    /**
+     * The out-of-band connection-state sink (see `AttachDaemonDeps.onConnectionEvent`).
+     * The default persists to `~/.config/yolobridge/connection.json`; a
+     * `connecting` event starts a fresh per-attachment record so `status`
+     * never shows a previous attach's history as if it were this one's.
+     */
+    const emitConnectionEvent = deps.onConnectionEvent ??
+        ((event) => {
+            if (!attachmentId)
+                return;
+            if (event.state === 'connecting')
+                resetConnectionState(attachmentId, event, env, io);
+            else
+                recordConnectionEvent(attachmentId, event, env, io);
+        });
+    function noteConnection(state, extra = {}) {
+        try {
+            emitConnectionEvent({ state, at: new Date(now()).toISOString(), ...extra });
+        }
+        catch {
+            // This channel is diagnostics. A read-only config dir or a full disk
+            // must not take down an otherwise-working attach — and must NOT fall
+            // back to stdout, which is precisely the bug this replaced.
+        }
+    }
     /**
      * Proactive refresh (Bug 2 fix): checked before opening/reopening the
      * stream and on every heartbeat tick while connected, so the daemon
      * rotates its access token well before the 24h production expiry
      * instead of degrading into a silent zombie that just starts 401ing.
-     * Updates both the in-memory `cfg`/`currentAuth` used by every
-     * subsequent API call in this process AND the on-disk auth.json (via
-     * `saveAuth`) so a later `status`/restart also sees the fresh token.
+     * Updates the in-memory `accountCfg`/`currentAuth` used by `attach` AND the
+     * on-disk auth.json (via `saveAuth`) so a later `status`/restart also sees
+     * the fresh token. It must NEVER write the scoped credential — see
+     * `scopedCfg` for why that separation is load-bearing.
      */
     async function ensureFreshToken() {
         if (now() < currentAuth.expiresAtMs - refreshBufferMs)
             return { ok: true };
+        // No refresh token: either this daemon dropped it after its own scoped
+        // attach exchange (card 08) and is now running from a restart, or the
+        // operator's `auth.json` predates login. Either way there is nothing to
+        // refresh WITH — report it as an outcome rather than handing `undefined`
+        // to auth-service and getting back an unexplained 400.
+        if (!currentAuth.refreshToken) {
+            return {
+                ok: false,
+                message: 'the account access token has expired and no refresh token is stored on this machine',
+            };
+        }
         const result = await doRefresh(authBaseUrl, currentAuth.refreshToken, fetchImpl);
         if (result.status !== 'ok') {
             return { ok: false, message: result.message };
@@ -76,33 +270,244 @@ export async function runAttachDaemon(deps) {
             tokenType: currentAuth.tokenType,
             expiresAtMs: result.tokens.expiresAtMs,
         };
-        cfg.accessToken = currentAuth.accessToken;
-        saveAuth(currentAuth, env, io);
-        log('Access token refreshed.');
+        accountCfg.accessToken = currentAuth.accessToken;
+        persistAccountAuth();
+        // Out-of-band, not `log`: this fires on a ~24h cadence from inside the
+        // heartbeat tick, i.e. while the local agent's TUI owns the terminal.
+        noteConnection('refreshed');
+        return { ok: true };
+    }
+    /**
+     * Latched once the account refresh has failed on the SCOPED path, so the
+     * heartbeat tick doesn't retry a call that cannot start working again.
+     */
+    let accountRefreshAbandoned = false;
+    /**
+     * `ensureFreshToken`, downgraded from fatal to best-effort.
+     *
+     * Nothing in this daemon's YoloBridge traffic uses the account token past
+     * attach, so killing a perfectly healthy session because it could not be
+     * rotated would be a self-inflicted brick. The rotation is kept running — it
+     * is not dead code: `onAttached` hands `getAccessToken` to the local MCP
+     * proxy, whose delegated-token mints are still account-authenticated (see
+     * mcp-proxy.ts) — but a failure DEGRADES that one enhancement rather than
+     * ending the session, and latches so the heartbeat tick stops retrying a call
+     * that cannot start working again.
+     *
+     * Card 08 classified this failure by whether a scoped credential existed,
+     * because on the degraded path the account token WAS the daemon's credential
+     * and a failed refresh had to be terminal. Card 09 removed that path
+     * entirely: `runAttachDaemon` never reaches this loop without a scoped
+     * credential, so the classification had exactly one branch left.
+     *
+     * Deliberately silent when it degrades. `noteConnection('degraded')` means
+     * "the LINK is struggling" and, being the last event recorded, would leave
+     * `yolo-bridge status` reporting a healthy session as degraded for the rest
+     * of its life. The one consumer, MCP minting, already reports its own
+     * failures, and best-effort MCP is its documented contract.
+     */
+    async function ensureFreshAccountToken() {
+        if (accountRefreshAbandoned)
+            return { ok: true };
+        const outcome = await ensureFreshToken();
+        if (outcome.ok)
+            return outcome;
+        accountRefreshAbandoned = true;
         return { ok: true };
     }
+    /**
+     * SINGLE-FLIGHT guard for the renewal below.
+     *
+     * The heartbeat scheduler fires on a plain interval and does NOT wait for
+     * the previous tick's async work to finish, so a renewal that takes longer
+     * than one tick would otherwise be started again by the next one. Two
+     * concurrent renewals are not merely wasteful: they can resolve out of
+     * order, and the loser would overwrite the live credential with the older of
+     * the two tokens — a bug that only ever appears on a slow network, and one
+     * whose symptom (heartbeats 401ing a few minutes later) points nowhere near
+     * here. Overlapping callers await the SAME renewal instead.
+     */
+    let scopedRefreshInFlight;
+    /**
+     * Latched terminal outcome. Once a credential is unrenewable it never
+     * becomes renewable again, so every later caller gets the same answer
+     * without another doomed round trip — which matters because the heartbeat
+     * interval keeps firing for the fraction of a second between the failure
+     * and the stream loop actually unwinding.
+     */
+    let scopedRefreshTerminal;
+    /**
+     * Renew the WORKSPACE-SCOPED credential before it expires (card 07).
+     *
+     * Checked in the same two places `ensureFreshToken` is — before opening or
+     * reopening the stream, and on every heartbeat tick while connected — so no
+     * new timer is introduced and the whole thing is driven by the already-
+     * injected `timers`/`now` seams. At a 10s heartbeat the renewal lands within
+     * ~10s of its scheduled moment, which against a 15-minute grace window is
+     * noise.
+     *
+     * Returns `{ ok: false }` ONLY when the situation is terminal — the grace
+     * window has closed, or the server said the attachment is gone. A transient
+     * failure while the credential is still renewable returns `ok` and simply
+     * lets the next tick try again (`refreshAtMs` is left where it was, so the
+     * retry is immediate rather than deferred another 45 minutes).
+     */
+    function ensureFreshScopedToken() {
+        if (scopedRefreshTerminal)
+            return Promise.resolve(scopedRefreshTerminal);
+        // Unreachable in this loop — `rememberScopedCredential` sets all three
+        // fields together and the daemon refuses to start without them (card 09).
+        // Kept as the type-level narrowing `scopedCredential.refreshAtMs` needs
+        // below, not as a live degrade branch.
+        if (!scopedCredential.token || scopedCredential.refreshAtMs === undefined) {
+            return Promise.resolve({ ok: true });
+        }
+        if (now() < scopedCredential.refreshAtMs)
+            return Promise.resolve({ ok: true });
+        if (scopedRefreshInFlight)
+            return scopedRefreshInFlight;
+        const attempt = renewScopedCredential();
+        scopedRefreshInFlight = attempt;
+        // `renewScopedCredential` never rejects (it converts every failure into an
+        // outcome), so one settle handler is enough. Cleared only if this attempt
+        // is still the current one, so a later attempt is never dropped by an
+        // earlier one's completion.
+        void attempt.then(() => {
+            if (scopedRefreshInFlight === attempt)
+                scopedRefreshInFlight = undefined;
+        });
+        return attempt;
+    }
+    async function renewScopedCredential() {
+        try {
+            const renewed = await apiClient.refreshScopedToken(scopedCfg(), workspaceId, attachmentId);
+            rememberScopedCredential(renewed.scopedToken, renewed.scopedTokenExpiresAt);
+            // Persist the RENEWED credential, not just the one attach issued: a
+            // restart hours into a session must resume from a token the server will
+            // still accept.
+            persistAttachment();
+            // Same out-of-band channel the account rotation uses, for the same
+            // reason: this fires mid-session, while the local agent's TUI owns the
+            // terminal.
+            noteConnection('refreshed', { detail: 'workspace-scoped credential renewed' });
+            return { ok: true };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            // 403 means the SERVER has ended this attachment (detached, or the
+            // workspace is gone). Retrying cannot help and waiting out the grace
+            // window only delays the truth.
+            const attachmentGone = err instanceof apiClient.YoloBridgeApiError && err.status === 403;
+            const expiresAtMs = scopedCredential.expiresAtMs ?? 0;
+            const windowBlown = now() >= expiresAtMs + SCOPED_REFRESH_GRACE_MS;
+            if (attachmentGone || windowBlown) {
+                scopedRefreshTerminal = {
+                    ok: false,
+                    message: 'YoloBridge session credential could not be renewed '
+                        + `(${message}). Run \`yolo-bridge attach\` again to reconnect this machine.`,
+                };
+                return scopedRefreshTerminal;
+            }
+            // Still renewable. `degraded` is exactly what this vocabulary means by
+            // "still connected, but an individual call failed" — the same state a
+            // failed heartbeat POST records — and it is transient by construction:
+            // the next tick either succeeds (→ `refreshed`) or the window closes
+            // (→ the terminal `interrupted` below). It is NOT used for the terminal
+            // failure, which would otherwise leave `yolo-bridge status` reporting a
+            // healthy session as degraded.
+            noteConnection('degraded', { detail: `scoped credential refresh failed: ${message}` });
+            return { ok: true };
+        }
+    }
     // Cover the case where the daemon is (re)started against a token that's
     // already within the refresh buffer of expiry (e.g. `attach` run right
     // after a long-down period) — refresh before the very first network
     // call, not just before subsequent reconnects.
     const initialRefresh = await ensureFreshToken();
+    /**
+     * RESUME an existing attachment from its persisted scoped credential
+     * (card 08), instead of creating a new one.
+     *
+     * Deliberately reached ONLY when the account credential cannot do a fresh
+     * attach. A healthy account token takes the ordinary path, byte for byte as
+     * before — resuming is a recovery route, not a new default, so it cannot
+     * change what a normal `yolo-bridge attach` does.
+     *
+     * The case it exists for is the one this card creates: a daemon that has run
+     * for days renewing its scoped credential, whose account access token expired
+     * on day one and whose refresh token is deliberately no longer on disk. Its
+     * restart has no account credential at all — but it does still hold a
+     * workspace-scoped one, which is precisely the credential the attachment's
+     * own routes want. Without this the operator is sent back to
+     * `yolo-bridge login` for a session that never actually lost anything.
+     *
+     * No window check here on purpose: the SERVER is the authority on whether a
+     * credential is still renewable (card 07's grace-window comment), and the
+     * renewal that runs before the stream opens asks it. If the answer is no, the
+     * daemon stops with card 07's own re-attach remedy rather than inventing a
+     * second, possibly-drifted opinion about the window here.
+     */
+    let resumed = false;
     if (!initialRefresh.ok) {
-        log(`Token refresh failed: ${initialRefresh.message}`);
-        log('Run `yolo-bridge login` again.');
-        return { ok: false, reason: 'refresh-failed', message: initialRefresh.message };
+        const stored = loadAttachment(env, io);
+        if (stored &&
+            stored.workspaceId === workspaceId &&
+            stored.scopedToken !== undefined &&
+            stored.scopedTokenExpiresAtMs !== undefined) {
+            attachmentId = stored.attachmentId;
+            tileId = stored.tileId;
+            attachedAt = stored.attachedAt;
+            rememberScopedCredential(stored.scopedToken, stored.scopedTokenExpiresAtMs);
+            resumed = true;
+        }
+        else {
+            log(`Token refresh failed: ${initialRefresh.message}`);
+            log('Run `yolo-bridge login` again.');
+            return { ok: false, reason: 'refresh-failed', message: initialRefresh.message };
+        }
     }
-    let attachmentId;
-    let tileId;
-    try {
-        const result = await apiClient.attach(cfg, workspaceId, hostLabel);
-        attachmentId = result.attachmentId;
-        tileId = result.tileId;
+    if (!resumed) {
+        try {
+            const result = await apiClient.attach(accountCfg, workspaceId, hostLabel, remoteHost);
+            attachmentId = result.attachmentId;
+            tileId = result.tileId;
+            attachedAt = new Date().toISOString();
+            // `api-client.attach` now REQUIRES the scoped pair and throws on its
+            // absence (card 09), so this is a plain read rather than the narrowing
+            // the optional shape used to need. A server that issues no credential
+            // lands in the catch below, as an attach failure with its own message.
+            rememberScopedCredential(result.scopedToken, result.scopedTokenExpiresAt);
+        }
+        catch (err) {
+            return { ok: false, reason: 'attach-failed', message: err instanceof Error ? err.message : String(err) };
+        }
     }
-    catch (err) {
-        return { ok: false, reason: 'attach-failed', message: err instanceof Error ? err.message : String(err) };
+    // Belt and braces for the property everything after this point depends on:
+    // BOTH routes into this line (a fresh attach, and the resume branch above)
+    // set the scoped credential or fail, so this cannot fire today. It exists so
+    // that if a third route is ever added, the daemon stops HERE — with a message
+    // an operator can act on, while they are still watching the terminal — rather
+    // than proceeding to 403 on every daemon call for the rest of the session.
+    if (!scopedCredential.token) {
+        const message = 'this attach produced no workspace-scoped credential, so the daemon has nothing '
+            + 'the YoloBridge routes will accept';
+        log(message);
+        return { ok: false, reason: 'attach-failed', message };
     }
-    saveAttachment({ workspaceId, tileId, attachmentId, attachedAt: new Date().toISOString() }, env, io);
-    log(`Attached. tileId=${tileId} attachmentId=${attachmentId}`);
+    persistAttachment();
+    // THE EXCHANGE IS COMPLETE — drop the durable account credential from disk
+    // (card 08). Ordered after `persistAttachment` so the machine is never
+    // momentarily left with neither credential persisted: a crash between the two
+    // writes would otherwise leave a daemon that can neither resume nor re-attach.
+    // `persistAccountAuth` is what makes this conditional on a scoped token
+    // actually being in hand; see its comment for why unconditional would brick
+    // the degraded path.
+    persistAccountAuth();
+    // Safe on stdout: this is still BEFORE `onAttached` spawns the local
+    // agent, so nothing owns the screen yet (and the caller's `clearScreen()`
+    // wipes it moments later anyway).
+    log(`${resumed ? 'Resumed' : 'Attached'}. tileId=${tileId} attachmentId=${attachmentId}`);
+    noteConnection('connecting');
     // Codex-found race: if something already asked us to stop WHILE the
     // initial refresh/attach network round trip above was in flight (e.g. the
     // local agent process this daemon spawns exits almost immediately), the
@@ -145,7 +550,7 @@ export async function runAttachDaemon(deps) {
     }
     async function detachAndReportStopped() {
         try {
-            await apiClient.detach(cfg, workspaceId, attachmentId);
+            await apiClient.detach(scopedCfg(), workspaceId, attachmentId);
         }
         catch (err) {
             // Only clear `attachment.json` on a SUCCESSFUL (or already-gone —
@@ -159,6 +564,13 @@ export async function runAttachDaemon(deps) {
             // retry against, and the next `attach` would then create a SECOND
             // server-side attachment/tile instead of ever cleaning up the first.
             log(`Cleanup detach failed: ${err instanceof Error ? err.message : String(err)}`);
+            // The record stays (see above) and so does the CREDENTIAL. Card 08 cleared
+            // it here on the reasoning that the retry authenticated with the account
+            // token — card 09's Boundary B made that false, and `runDetach` now
+            // accepts only the scoped credential. Clearing it would leave the retry
+            // this comment describes unable to authenticate at all, stranding a live
+            // server-side attachment and duplicating the tile on the next attach.
+            // (Codex review, gpt-5.6-sol, 2026-08-25.)
             return { ok: true, reason: 'stopped' };
         }
         clearAttachment(env, io);
@@ -171,13 +583,30 @@ export async function runAttachDaemon(deps) {
      * (forced via the stop-poll below) so the daemon stops instead of
      * looping forever reconnecting with a dead token. */
     let refreshFailed;
+    /** The same, for the WORKSPACE-SCOPED credential: set when its renewal
+     * window has closed (or the server ended the attachment), so the daemon
+     * stops instead of streaming on with a credential that is about to start
+     * 401ing every heartbeat. Kept separate from `refreshFailed` because the
+     * two have different remedies — `yolo-bridge login` vs `yolo-bridge attach`
+     * — and different reporting rules: the account failure is the daemon's exit
+     * message and may use stdout, this one fires mid-session while the local
+     * agent's TUI owns the terminal and must not. */
+    let scopedRefreshFailed;
     try {
         while (!shouldStop()) {
-            const preStreamRefresh = await ensureFreshToken();
+            const preStreamRefresh = await ensureFreshAccountToken();
             if (!preStreamRefresh.ok) {
                 refreshFailed = preStreamRefresh;
                 break;
             }
+            // Also before every (re)connect, not only on the heartbeat tick: a long
+            // backoff with no stream open is exactly when a scoped credential can
+            // cross its renewal point unnoticed.
+            const preStreamScopedRefresh = await ensureFreshScopedToken();
+            if (!preStreamScopedRefresh.ok) {
+                scopedRefreshFailed = preStreamScopedRefresh;
+                break;
+            }
             let sawDetached = false;
             /** Set when the SSE stream itself (or any other call in this attempt)
              *  404s -- the attachment/workspace no longer exists server-side
@@ -190,7 +619,7 @@ export async function runAttachDaemon(deps) {
              *  `detached` frame that would normally end this loop cleanly. */
             let sawGone = false;
             try {
-                const res = await apiClient.openStream(cfg, workspaceId, attachmentId);
+                const res = await apiClient.openStream(scopedCfg(), workspaceId, attachmentId);
                 attempt = 0; // reset backoff on a successful connect
                 const parser = new SseFrameParser();
                 const nodeStream = Readable.fromWeb(res.body);
@@ -219,7 +648,7 @@ export async function runAttachDaemon(deps) {
                 // above) instead of riding out the connection to its next natural
                 // event.
                 const stopPollHandle = timers.setInterval(() => {
-                    if (shouldStop() || refreshFailed) {
+                    if (shouldStop() || refreshFailed || scopedRefreshFailed) {
                         nodeStream.destroy();
                     }
                 }, STOP_POLL_INTERVAL_MS);
@@ -246,18 +675,35 @@ export async function runAttachDaemon(deps) {
                                     // right before `startLocalAgent`, the one moment
                                     // guaranteed to be before any agent output regardless of
                                     // either timing race.
-                                    log('Stream connected.');
+                                    // Out-of-band (was `log('Stream connected.')`): by this
+                                    // point `onAttached` has spawned the local agent, whose
+                                    // PTY is piped to this same stdout — a status line here
+                                    // lands in the middle of the TUI's frame.
+                                    noteConnection('connected');
                                     heartbeat?.stop();
                                     heartbeat = startHeartbeat(async () => {
-                                        const refreshCheck = await ensureFreshToken();
+                                        const refreshCheck = await ensureFreshAccountToken();
                                         if (!refreshCheck.ok) {
                                             refreshFailed = refreshCheck;
                                             return;
                                         }
-                                        await apiClient.postHeartbeat(cfg, workspaceId, attachmentId);
-                                    }, (err) => log(`heartbeat error: ${err instanceof Error ? err.message : String(err)}`), undefined, deps.timers);
+                                        // Renew the scoped credential BEFORE the heartbeat that
+                                        // would use it, so a tick that crosses the renewal point
+                                        // heartbeats with the new token rather than spending one
+                                        // more tick on the old one.
+                                        const scopedCheck = await ensureFreshScopedToken();
+                                        if (!scopedCheck.ok) {
+                                            scopedRefreshFailed = scopedCheck;
+                                            return;
+                                        }
+                                        await apiClient.postHeartbeat(scopedCfg(), workspaceId, attachmentId);
+                                    }, (err) => noteConnection('degraded', {
+                                        detail: `heartbeat error: ${err instanceof Error ? err.message : String(err)}`,
+                                    }), undefined, deps.timers);
                                     // Send one immediately so status isn't stale for the first ~10s.
-                                    apiClient.postHeartbeat(cfg, workspaceId, attachmentId).catch((err) => log(`initial heartbeat error: ${err instanceof Error ? err.message : String(err)}`));
+                                    apiClient.postHeartbeat(scopedCfg(), workspaceId, attachmentId).catch((err) => noteConnection('degraded', {
+                                        detail: `initial heartbeat error: ${err instanceof Error ? err.message : String(err)}`,
+                                    }));
                                     break;
                                 case 'ping':
                                     break;
@@ -267,16 +713,18 @@ export async function runAttachDaemon(deps) {
                                 case 'read-output': {
                                     const captured = await captureOutput();
                                     await apiClient
-                                        .postReadOutputReply(cfg, workspaceId, attachmentId, action.requestId, captured.output, captured.busy)
-                                        .catch((err) => log(`read-output reply failed: ${err instanceof Error ? err.message : String(err)}`));
+                                        .postReadOutputReply(scopedCfg(), workspaceId, attachmentId, action.requestId, captured.output, captured.busy)
+                                        .catch((err) => noteConnection('degraded', {
+                                        detail: `read-output reply failed: ${err instanceof Error ? err.message : String(err)}`,
+                                    }));
                                     break;
                                 }
                                 case 'detached':
-                                    log('Detached by server.');
+                                    noteConnection('detached');
                                     sawDetached = true;
                                     break;
                                 case 'unknown':
-                                    log(`Unrecognized frame type: ${action.event}`);
+                                    noteConnection('degraded', { detail: `unrecognized frame type: ${action.event}` });
                                     break;
                             }
                             if (sawDetached)
@@ -291,7 +739,9 @@ export async function runAttachDaemon(deps) {
                 }
             }
             catch (err) {
-                log(`Stream error: ${err instanceof Error ? err.message : String(err)}`);
+                // The reported bug's primary symptom: this is the transient-drop
+                // path, and it used to write straight into the agent's PTY stream.
+                noteConnection('interrupted', { detail: err instanceof Error ? err.message : String(err) });
                 if (err instanceof apiClient.YoloBridgeApiError && err.status === 404)
                     sawGone = true;
             }
@@ -301,20 +751,43 @@ export async function runAttachDaemon(deps) {
                 clearAttachment(env, io);
                 return { ok: true, reason: 'detached-by-server' };
             }
-            if (refreshFailed)
+            if (refreshFailed || scopedRefreshFailed)
                 break;
             if (shouldStop())
                 break;
             attempt += 1;
             const delay = nextBackoffMs(attempt, deps.backoffOpts);
-            log(`Reconnecting in ${delay}ms (attempt ${attempt})...`);
+            noteConnection('reconnecting', { attempt, retryInMs: delay });
             await sleep(delay);
         }
     }
     finally {
         heartbeat?.stop();
     }
+    if (scopedRefreshFailed) {
+        // OUT-OF-BAND ONLY — no `log()` here, unlike the account-token path below.
+        // That path is reached from the daemon's own pre-attach startup or as its
+        // terminal exit line; this one fires from inside a live session, where the
+        // local agent's PTY is piped to this process's stdout and any human-
+        // readable line lands in the middle of a frame its TUI believes it drew
+        // (connection-state.ts's module header). `interrupted` is the honest
+        // state: the session is ending abnormally — deliberately not `degraded`,
+        // which means the LINK is struggling and would make `yolo-bridge status`
+        // misreport a healthy session. The remedy travels two ways regardless: in
+        // the `detail` here, and as the returned `message`, which cli.ts prints on
+        // STDERR after the PTY is already gone.
+        noteConnection('interrupted', { detail: scopedRefreshFailed.message });
+        // `refresh-failed` (not a new reason) on purpose: cli.ts keys off it to run
+        // the best-effort `runDetach()` cleanup that stops a stale attachment being
+        // left behind, which is exactly what should happen here too.
+        return { ok: false, reason: 'refresh-failed', message: scopedRefreshFailed.message };
+    }
     if (refreshFailed) {
+        noteConnection('interrupted', { detail: `token refresh failed: ${refreshFailed.message}` });
+        // Still on stdout, deliberately: this is the terminal EXIT message for
+        // a daemon that is about to return and let cli.ts kill the local PTY.
+        // Unlike the reconnect narration above, there is no frame left to
+        // corrupt, and the alternative is an unexplained silent exit.
         log(`Token refresh failed: ${refreshFailed.message}`);
         log('Run `yolo-bridge login` again.');
         return { ok: false, reason: 'refresh-failed', message: refreshFailed.message };

package/dist/cli.js

@@ -18,6 +18,7 @@
  */
 import { fileURLToPath } from 'node:url';
 import { realpathSync } from 'node:fs';
+import { hostname } from 'node:os';
 import { runLogin } from './login-cmd.js';
 import { runAttachFromDisk, pickWorkspaceFromDisk } from './attach-cmd.js';
 import { runDetach } from './detach-cmd.js';
@@ -163,6 +164,40 @@ export function parseAttachArgs(args) {
     }
     return { workspaceId, hostLabel, agentBin, agentId };
 }
+/**
+ * Everything the attach handshake tells the workspace about this machine,
+ * resolved from already-known values — pure, so it's unit-testable without
+ * touching a real `os`/`process` (the caller passes the real ones in).
+ *
+ * Two things happen here:
+ *
+ *  - **`hostLabel` gains a default.** It was previously set ONLY by an
+ *    explicit `--label`, so the overwhelmingly common `yolo-bridge attach`
+ *    with no flags produced a tile named a bare "YoloBridge" with nothing
+ *    identifying WHICH machine had attached — actively confusing for an
+ *    operator running a daemon on more than one. The machine's own hostname
+ *    is the obvious default and is already what `--label` is usually set to
+ *    by hand. An explicit `--label` still wins.
+ *  - **`remoteHost` is assembled**: the launch directory, the OS platform
+ *    string, and which agent binary this attach drives.
+ *
+ * What is deliberately NOT collected, and should not be added without its
+ * own consent story: environment variables, anything listing the contents
+ * of `cwd`, the OS username or any other account identity, network
+ * addresses, or installed-software inventory. This is the operator's own
+ * machine being described back to the operator; it is not a survey of it.
+ */
+export function resolveAttachHostInfo(input) {
+    const label = input.label?.trim();
+    return {
+        hostLabel: label || input.hostname.trim() || undefined,
+        remoteHost: {
+            cwd: input.cwd,
+            platform: input.platform,
+            agent: input.agent,
+        },
+    };
+}
 async function cmdAttach(args) {
     // Printed unconditionally, first thing, regardless of how the rest of
     // this command goes — a self-diagnosing fix for a real, repeated support
@@ -231,6 +266,16 @@ async function cmdAttach(args) {
     process.on('SIGINT', onSignal);
     process.on('SIGTERM', onSignal);
     const spawnCwd = process.cwd();
+    // Everything the workspace tile shows about WHERE this session runs, all
+    // resolved here in one place (see resolveAttachHostInfo's doc comment for
+    // what is and isn't collected).
+    const attachHostInfo = resolveAttachHostInfo({
+        label: hostLabel,
+        hostname: hostname(),
+        cwd: spawnCwd,
+        platform: process.platform,
+        agent: resolvedAgentId,
+    });
     let mcpProxyHandle;
     let mcpConfigCleanup;
     let mcpTrustRemoval;
@@ -239,7 +284,8 @@ async function cmdAttach(args) {
         result = await runAttachFromDisk({
             workspaceId,
             commonApiBaseUrl: apiUrl(),
-            hostLabel,
+            hostLabel: attachHostInfo.hostLabel,
+            remoteHost: attachHostInfo.remoteHost,
             shouldStop: () => stopRequested,
             // Fires once the real tileId exists (docs/YOLOBRIDGE_PLAN.md's "Local
             // MCP access" section) — starts the local MCP proxy and writes
@@ -248,7 +294,7 @@ async function cmdAttach(args) {
             // skipped, not fatal — MCP access is an enhancement on a tile that
             // already works without it (send_to_tile/read_tile_output are
             // unaffected either way).
-            onAttached: async ({ getAccessToken, clearScreen }) => {
+            onAttached: async ({ tileId, getAccessToken, clearScreen }) => {
                 // Isolated from `startLocalAgent` below on purpose (Codex review,
                 // 2026-08-24): `startMcpProxy` itself never throws, but
                 // `writeLocalMcpConfig`/`writeLocalMcpTrust` do plain synchronous
@@ -266,6 +312,11 @@ async function cmdAttach(args) {
                         getAccessToken,
                         workspaceId,
                         agentId: resolvedAgentId,
+                        // Self-identity for the spawned agent: the tile it is running in.
+                        // Without it, an agent asked to message "the other tile" has to
+                        // guess which studio_list_tiles row is itself — and a backwards
+                        // guess sends the prompt into its OWN input.
+                        callerTileId: tileId,
                         log: (line) => process.stdout.write(`${line}\n`),
                     });
                     // `.mcp.json` + `.claude/settings.json` are Claude Code-specific

package/dist/config-store.js

@@ -56,10 +56,21 @@ export function loadAuth(env = process.env, io = defaultIO) {
     try {
         const parsed = JSON.parse(raw);
         if (typeof parsed.accessToken === 'string' &&
-            typeof parsed.refreshToken === 'string' &&
+            // Absent is VALID (the scoped path deliberately drops it); present must
+            // still be a string. A malformed value is treated as absent rather than
+            // as a corrupt file: the access token half is what this record is for,
+            // and refusing to load it would log the operator out over a field the
+            // daemon may not even need.
+            (parsed.refreshToken === undefined || typeof parsed.refreshToken === 'string') &&
             typeof parsed.tokenType === 'string' &&
             typeof parsed.expiresAtMs === 'number') {
-            return parsed;
+            const { accessToken, refreshToken, tokenType, expiresAtMs } = parsed;
+            return {
+                accessToken,
+                tokenType,
+                expiresAtMs,
+                ...(refreshToken ? { refreshToken } : {}),
+            };
         }
         return undefined;
     }
@@ -67,8 +78,24 @@ export function loadAuth(env = process.env, io = defaultIO) {
         return undefined;
     }
 }
+/**
+ * Writes `auth.json`. A missing (or empty) `refreshToken` is written out as an
+ * ABSENT KEY, never as `""`.
+ *
+ * Normalised here rather than left to callers on purpose: an empty string is a
+ * value that every `typeof x === 'string'` check downstream accepts, so it
+ * would sail through the loader and be handed to auth-service's refresh
+ * endpoint as a credential, turning "we deliberately dropped this" into an
+ * unexplained 401. Absent is the honest encoding of absent.
+ */
 export function saveAuth(auth, env = process.env, io = defaultIO) {
-    io.writeFile(authPath(env), `${JSON.stringify(auth, null, 2)}\n`);
+    const record = {
+        accessToken: auth.accessToken,
+        ...(auth.refreshToken ? { refreshToken: auth.refreshToken } : {}),
+        tokenType: auth.tokenType,
+        expiresAtMs: auth.expiresAtMs,
+    };
+    io.writeFile(authPath(env), `${JSON.stringify(record, null, 2)}\n`);
 }
 export function clearAuth(env = process.env, io = defaultIO) {
     io.removeFile(authPath(env));
@@ -83,7 +110,15 @@ export function loadAttachment(env = process.env, io = defaultIO) {
             typeof parsed.tileId === 'string' &&
             typeof parsed.attachmentId === 'string' &&
             typeof parsed.attachedAt === 'string') {
-            return parsed;
+            const { workspaceId, tileId, attachmentId, attachedAt } = parsed;
+            // Both-or-neither. A half-pair is dropped rather than rejecting the whole
+            // record: the attachment IDENTITY is still perfectly good (detach and the
+            // status display need only that), and the daemon simply falls back to a
+            // fresh attach instead of resuming.
+            const scoped = typeof parsed.scopedToken === 'string' && typeof parsed.scopedTokenExpiresAtMs === 'number'
+                ? { scopedToken: parsed.scopedToken, scopedTokenExpiresAtMs: parsed.scopedTokenExpiresAtMs }
+                : {};
+            return { workspaceId, tileId, attachmentId, attachedAt, ...scoped };
         }
         return undefined;
     }
@@ -94,6 +129,25 @@ export function loadAttachment(env = process.env, io = defaultIO) {
 export function saveAttachment(attachment, env = process.env, io = defaultIO) {
     io.writeFile(attachmentPath(env), `${JSON.stringify(attachment, null, 2)}\n`);
 }
+/**
+ * Strips the workspace-scoped credential from `attachment.json`, leaving the
+ * attachment identity behind.
+ *
+ * Distinct from `clearAttachment` because the two answer different questions.
+ * `detach` clears the whole record on success — but on FAILURE it deliberately
+ * keeps it, so the retry path (`cli.ts`, or a manual `yolo-bridge detach`)
+ * knows what to retry against. The stored credential has no such second use:
+ * the server refuses it the moment the attachment stops being live, so leaving
+ * it on disk is residue that can only ever be leaked, never spent. No-ops when
+ * there is nothing stored, and never creates a file.
+ */
+export function clearStoredScopedToken(env = process.env, io = defaultIO) {
+    const attachment = loadAttachment(env, io);
+    if (!attachment || attachment.scopedToken === undefined)
+        return;
+    const { scopedToken: _dropped, scopedTokenExpiresAtMs: _droppedExpiry, ...rest } = attachment;
+    saveAttachment(rest, env, io);
+}
 export function clearAttachment(env = process.env, io = defaultIO) {
     io.removeFile(attachmentPath(env));
 }

package/dist/connection-state.js

@@ -0,0 +1,108 @@
+/**
+ * Out-of-band connection-state channel for the `yolo-bridge attach` daemon.
+ *
+ * **Why this module exists (bug, 2026-08-25).** `attach` spawns the user's
+ * local coding agent under a real PTY and pipes that PTY straight to this
+ * process's own `process.stdout` (`local-agent.ts`'s module header), so from
+ * the moment `startLocalAgent` runs the terminal belongs to a full-screen
+ * TUI that owns the alternate screen buffer and repaints on its own
+ * schedule. The daemon's own `log()` defaults to `process.stdout.write` —
+ * the SAME stream — so every connection-state line it emitted from inside
+ * the reconnect loop (`Stream error: …`, `Reconnecting in 1000ms
+ * (attempt 1)...`, `Stream connected.`) was injected into the middle of a
+ * frame the TUI believed it had drawn. The result is a garbled/overlapping
+ * display that persists until the agent happens to do a full repaint: a
+ * transient wifi blip the daemon recovers from entirely on its own still
+ * trashed the user's screen.
+ *
+ * Writing the same text to `process.stderr` instead is NOT a fix: in an
+ * interactive session both file descriptors point at the same tty, so the
+ * bytes land in exactly the same place.
+ *
+ * The fix is to stop putting human-readable status into a stream a TUI is
+ * actively rendering to, and route it to a channel that has nothing to do
+ * with the terminal. That channel is this file: a small JSON record under
+ * the daemon's existing config dir (`~/.config/yolobridge/`, alongside
+ * `auth.json`/`attachment.json`) holding the current connection state plus
+ * a bounded tail of recent transitions, written through the same injectable
+ * `ConfigStoreIO` every other piece of local state already uses.
+ *
+ * The information is deliberately NOT dropped — it is surfaced two ways:
+ *   - locally, by `yolo-bridge status` (status-cmd.ts), which reads this
+ *     record and renders the current state plus recent transitions;
+ *   - in the workspace, by the tile's own status: yolobridge tile status is
+ *     derived server-side from `lastHeartbeatAt` (docs/YOLOBRIDGE_PLAN.md's
+ *     "Status derivation" — ≤30s `running`, ≤90s `paused`, older
+ *     `stopped`), so a real drop already degrades the tile without the
+ *     daemon having to narrate it into the PTY.
+ *
+ * Scoped to one attachment (`attachmentId`): a record left over from a
+ * previous attach is ignored rather than shown as if it described the
+ * current one, which avoids needing a cleanup call at every teardown site.
+ */
+import * as path from 'node:path';
+import { defaultIO, configDir } from './config-store.js';
+/** How many prior transitions to keep. Enough to show "it blipped three
+ *  times in the last minute" without turning this into a log file. */
+export const MAX_RECENT_EVENTS = 20;
+function connectionPath(env) {
+    return path.join(configDir(env), 'connection.json');
+}
+export function loadConnectionState(env = process.env, io = defaultIO) {
+    const raw = io.readFile(connectionPath(env));
+    if (!raw)
+        return undefined;
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.attachmentId === 'string' &&
+            parsed.current !== undefined &&
+            typeof parsed.current.state === 'string' &&
+            typeof parsed.current.at === 'string') {
+            return {
+                attachmentId: parsed.attachmentId,
+                current: parsed.current,
+                recent: Array.isArray(parsed.recent) ? parsed.recent : [],
+            };
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Starts a fresh record for `attachmentId`. Called once, right after the
+ * attach succeeds, so `status` never renders a previous attach's history as
+ * if it belonged to the live one.
+ */
+export function resetConnectionState(attachmentId, event, env = process.env, io = defaultIO) {
+    writeState({ attachmentId, current: event, recent: [] }, env, io);
+}
+/**
+ * Appends `event` as the new current state, rolling the previous one into
+ * the bounded `recent` tail. A record belonging to a different attachment
+ * is replaced rather than appended to.
+ */
+export function recordConnectionEvent(attachmentId, event, env = process.env, io = defaultIO) {
+    const existing = loadConnectionState(env, io);
+    if (!existing || existing.attachmentId !== attachmentId) {
+        writeState({ attachmentId, current: event, recent: [] }, env, io);
+        return;
+    }
+    const recent = [...existing.recent, existing.current].slice(-MAX_RECENT_EVENTS);
+    writeState({ attachmentId, current: event, recent }, env, io);
+}
+function writeState(state, env, io) {
+    io.writeFile(connectionPath(env), `${JSON.stringify(state, null, 2)}\n`);
+}
+/** One-line human rendering, used by `yolo-bridge status`. */
+export function formatConnectionEvent(event) {
+    const parts = [event.state];
+    if (event.state === 'reconnecting' && typeof event.attempt === 'number') {
+        parts.push(`(attempt ${event.attempt}${typeof event.retryInMs === 'number' ? `, retrying in ${event.retryInMs}ms` : ''})`);
+    }
+    parts.push(`at ${event.at}`);
+    if (event.detail)
+        parts.push(`— ${event.detail}`);
+    return parts.join(' ');
+}

package/dist/detach-cmd.js

@@ -18,20 +18,58 @@
  * cli.ts).
  */
 import { detach as apiDetach } from './api-client.js';
-import { loadAuth, loadAttachment, clearAttachment } from './config-store.js';
+import { loadAuth, loadAttachment, clearAttachment, clearStoredScopedToken, } from './config-store.js';
 export async function runDetach(deps) {
-    const auth = loadAuth(deps.env, deps.io);
-    if (!auth)
+    // Still a real precondition, but no longer the credential: `auth.json` is
+    // what makes this a set-up machine at all, and its absence has a much better
+    // remedy to offer than a 403 would.
+    if (!loadAuth(deps.env, deps.io)) {
         return { ok: false, reason: 'not-logged-in', message: 'Not logged in — run `yolo-bridge login` first.' };
+    }
     const attachment = loadAttachment(deps.env, deps.io);
     if (!attachment)
         return { ok: false, reason: 'not-attached', message: 'No active attachment found.' };
+    // READ THE CREDENTIAL BEFORE ANY CLEARING BELOW. `DELETE .../attach/:id` is a
+    // daemon-only route behind Boundary B (card 09): an account token is refused
+    // there with 403 YOLOBRIDGE_SCOPED_TOKEN_REQUIRED, so this command must
+    // present the workspace-scoped credential `attach` persisted alongside the
+    // attachment identity — the same one the running daemon uses.
+    const scopedToken = attachment.scopedToken;
+    if (!scopedToken) {
+        // No credential the daemon surface will accept, and nothing on this machine
+        // can mint one for an attachment that already exists. Say so plainly rather
+        // than sending an account token to be refused: the operator's real remedy
+        // is to let the tile go stale on its own (the server stops it once the
+        // heartbeat lapses) or to re-attach.
+        return {
+            ok: false,
+            reason: 'error',
+            message: 'No workspace-scoped credential is stored for this attachment, so it cannot be '
+                + 'detached from this machine. The tile stops on its own once its heartbeat lapses; '
+                + 'run `yolo-bridge attach` to reconnect.',
+        };
+    }
     try {
-        await apiDetach({ commonApiBaseUrl: deps.commonApiBaseUrl, accessToken: auth.accessToken, fetchImpl: deps.fetchImpl }, attachment.workspaceId, attachment.attachmentId);
+        await apiDetach({ commonApiBaseUrl: deps.commonApiBaseUrl, accessToken: scopedToken, fetchImpl: deps.fetchImpl }, attachment.workspaceId, attachment.attachmentId);
     }
     catch (err) {
+        // The attachment RECORD **and** its credential are both kept on a genuine
+        // failure, because the retry needs both.
+        //
+        // Card 08 stripped the credential here, reasoning it was leakable residue
+        // the server would refuse anyway. Card 09 invalidated that: the scoped
+        // credential is now the ONLY thing Boundary B accepts on this route, so
+        // discarding it made every retry — automatic or manual — take the
+        // no-credential branch above. The attachment stays live server-side, this
+        // machine can no longer remove it, and the next `attach` creates a SECOND
+        // attachment and tile. (Codex review, gpt-5.6-sol, 2026-08-25: two P1s.)
+        //
+        // The credential is discarded only on a SUCCESSFUL or confirmed-gone
+        // detach — the same rule the record already follows, and for the same
+        // reason: the two are only useful together.
         return { ok: false, reason: 'error', message: err instanceof Error ? err.message : String(err) };
     }
+    clearStoredScopedToken(deps.env, deps.io);
     clearAttachment(deps.env, deps.io);
     return { ok: true };
 }

package/dist/mcp-proxy.js

@@ -167,7 +167,7 @@ async function fetchAllScopes(apiUrl, fetchImpl, tracker) {
 /** One cached, self-refreshing, workspace-wide token — scoped to whatever
  *  `agentId`'s registry entry actually allows out of the full scope
  *  universe (see this file's header comment). */
-function makeTokenCache(apiUrl, getAccessToken, workspaceId, agentId, fetchImpl, tracker) {
+function makeTokenCache(apiUrl, getAccessToken, workspaceId, agentId, callerTileId, fetchImpl, tracker) {
     let cached;
     async function mint() {
         const scopes = await fetchAllScopes(apiUrl, fetchImpl, tracker);
@@ -179,6 +179,7 @@ function makeTokenCache(apiUrl, getAccessToken, workspaceId, agentId, fetchImpl,
                     workspaceId,
                     agentId,
                     scopes,
+                    ...(callerTileId ? { callerTileId } : {}),
                     ttlSeconds: REQUESTED_TTL_SECONDS,
                 }),
                 signal,
@@ -243,7 +244,7 @@ export async function startMcpProxy(opts) {
     const log = opts.log ?? (() => { });
     const fetchImpl = opts.fetchImpl ?? fetch;
     const tracker = new RequestTracker();
-    const tokenCache = makeTokenCache(opts.apiUrl, opts.getAccessToken, opts.workspaceId, opts.agentId, fetchImpl, tracker);
+    const tokenCache = makeTokenCache(opts.apiUrl, opts.getAccessToken, opts.workspaceId, opts.agentId, opts.callerTileId, fetchImpl, tracker);
     // Bounded (STARTUP_MINT_TIMEOUT_MS): a stalled scope-discovery/mint fetch
     // must not block `onAttached` from ever reaching `startLocalAgent`
     // (Codex review, 2026-08-24). `abortAll()` only affects requests in

package/dist/status-cmd.js

@@ -11,8 +11,18 @@
  * a pidfile / lockfile next to attachment.json to close that gap; not
  * implemented here — flagged as a known limitation, not silently glossed
  * over.
+ *
+ * Partially narrowed since (2026-08-25): the daemon now records every
+ * connection transition to `connection.json` (connection-state.ts) instead
+ * of narrating it into the terminal the local agent's TUI is rendering
+ * into, and this command renders that record. That still isn't liveness —
+ * a crashed daemon leaves its last transition frozen on disk, so
+ * `Connection: connected` means "the last thing it managed to record",
+ * not "it is connected right now" — but a drop/reconnect blip is no
+ * longer invisible just because it can't be printed to the screen.
  */
 import { loadAuth, loadAttachment } from './config-store.js';
+import { loadConnectionState, formatConnectionEvent } from './connection-state.js';
 export function getStatus(deps = {}) {
     const now = deps.now ?? Date.now;
     const auth = loadAuth(deps.env, deps.io);
@@ -30,6 +40,14 @@ export function getStatus(deps = {}) {
         report.tileId = attachment.tileId;
         report.attachmentId = attachment.attachmentId;
         report.attachedAt = attachment.attachedAt;
+        const connection = loadConnectionState(deps.env, deps.io);
+        // Only report a record that belongs to the CURRENT attachment — a
+        // leftover from a previous attach describes a connection that no
+        // longer exists and would be actively misleading here.
+        if (connection && connection.attachmentId === attachment.attachmentId) {
+            report.connection = connection.current;
+            report.connectionHistory = connection.recent;
+        }
     }
     return report;
 }
@@ -47,6 +65,18 @@ export function formatStatus(report) {
     else {
         lines.push(`Attached: yes — workspace=${report.workspaceId} tile=${report.tileId} attachmentId=${report.attachmentId} since=${report.attachedAt}`);
         lines.push('(local file only — does not confirm the attach daemon process is still running/connected)');
+        if (report.connection) {
+            lines.push(`Connection: ${formatConnectionEvent(report.connection)}`);
+            const history = report.connectionHistory ?? [];
+            if (history.length > 0) {
+                // Newest first — a reconnect blip is easiest to read as "what just
+                // happened", not "what happened when this attach started".
+                lines.push('Recent connection events (newest first):');
+                for (const event of [...history].reverse()) {
+                    lines.push(`  ${formatConnectionEvent(event)}`);
+                }
+            }
+        }
     }
     return lines.join('\n');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yolo-labs/yolobridge",
-  "version": "0.2.0",
+  "version": "0.7.1",
   "description": "YoloBridge — local coding-agent daemon that attaches a user's own Claude Code/Codex session to a YOLO Studio workspace as a first-class tile (docs/YOLOBRIDGE_PLAN.md, build-order Phase 5).",
   "license": "MIT",
   "type": "module",