@yolo-labs/yolobridge 0.2.0 → 0.8.0

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,262 @@ 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 };
     }
-    // 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();
-    if (!initialRefresh.ok) {
-        log(`Token refresh failed: ${initialRefresh.message}`);
-        log('Run `yolo-bridge login` again.');
-        return { ok: false, reason: 'refresh-failed', message: initialRefresh.message };
+    /**
+     * 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 };
     }
-    let attachmentId;
-    let tileId;
-    try {
-        const result = await apiClient.attach(cfg, workspaceId, hostLabel);
-        attachmentId = result.attachmentId;
-        tileId = result.tileId;
+    /**
+     * 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;
     }
-    catch (err) {
-        return { ok: false, reason: 'attach-failed', message: err instanceof Error ? err.message : String(err) };
+    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 };
+        }
+    }
+    /**
+     * RESUME an existing attachment from its persisted scoped credential
+     * (card 08), instead of creating a second one.
+     *
+     * **LIVENESS decides, not the account token's health** (D7). Card 08 gated
+     * this on the account refresh having failed, which meant a daemon restarting
+     * with a healthy account token ignored a perfectly good stored attachment and
+     * called `attach` again — a SECOND server-side attachment and a second tile.
+     * The first stops heartbeating and is reaped, but the operator is left
+     * looking at a duplicate. Account-token health says nothing about whether the
+     * attachment is still alive, so it was never the right question.
+     *
+     * The probe is card 07's own renewal route
+     * (`POST .../yolobridge/attach/:attachmentId/refresh`). That route re-reads
+     * live attachment state on every call and 403s a detached one, so it is
+     * simultaneously the liveness check AND the source of a fresh credential —
+     * there is deliberately no second probe to drift out of agreement with it.
+     *
+     * A failure of ANY kind (403 detached, 401 past the renewal window, a
+     * network error) is not fatal here: it just means there is nothing to
+     * resume, and the ordinary attach path below runs. The server, not this
+     * binary's copy of the window, is the authority on which it was.
+     */
+    let resumed = false;
+    if (!deps.fresh) {
+        const stored = loadAttachment(env, io);
+        if (stored &&
+            stored.workspaceId === workspaceId &&
+            stored.scopedToken !== undefined &&
+            stored.scopedTokenExpiresAtMs !== undefined) {
+            try {
+                // A one-off config rather than `scopedCfg()`: the stored token is not
+                // adopted as THE credential until the server has confirmed it is
+                // still good, so a failed probe leaves the daemon's own state
+                // untouched and the fall-through is a clean ordinary attach.
+                const renewed = await apiClient.refreshScopedToken({ commonApiBaseUrl, accessToken: stored.scopedToken, fetchImpl }, workspaceId, stored.attachmentId);
+                attachmentId = stored.attachmentId;
+                tileId = stored.tileId;
+                attachedAt = stored.attachedAt;
+                rememberScopedCredential(renewed.scopedToken, renewed.scopedTokenExpiresAt);
+                resumed = true;
+            }
+            catch (err) {
+                // Pre-spawn, so `log` is safe here (nothing owns the terminal yet) —
+                // and worth saying out loud: the operator is about to get a NEW tile
+                // where they may have expected the old one back.
+                const message = err instanceof Error ? err.message : String(err);
+                log(`Stored attachment is no longer resumable (${message}) — attaching fresh.`);
+            }
+        }
     }
-    saveAttachment({ workspaceId, tileId, attachmentId, attachedAt: new Date().toISOString() }, env, io);
-    log(`Attached. tileId=${tileId} attachmentId=${attachmentId}`);
+    if (!resumed) {
+        // ONLY the attach path needs the account credential — attach is the call
+        // that creates the scope, and nothing after it presents an account token.
+        // Keeping this refresh inside the branch is the ordering win D7 exists
+        // for: a daemon whose account token expired days ago, but whose
+        // attachment is still live, resumes above and never reaches this line.
+        // (It also still covers the original reason it existed: an `attach` run
+        // right after a long-down period, against a token already inside the
+        // refresh buffer, rotates before the very first network call.)
+        const initialRefresh = await ensureFreshToken();
+        if (!initialRefresh.ok) {
+            log(`Token refresh failed: ${initialRefresh.message}`);
+            log('Run `yolo-bridge login` again.');
+            return { ok: false, reason: 'refresh-failed', message: initialRefresh.message };
+        }
+        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) };
+        }
+    }
+    // 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 };
+    }
+    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 +568,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 +582,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 +601,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 +637,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 +666,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 +693,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 +731,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 +757,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 +769,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 };