@clearlysh/beehaven 0.8.35 → 0.8.36

package/dist/agent-sessions.js

@@ -14,6 +14,7 @@ import { writeFileSync, readFileSync, renameSync, chmodSync, mkdirSync, existsSy
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
+import { ReconnectBackoff } from './reconnect-backoff.js';
 const CONFIG_DIR = join(homedir(), '.beehaven');
 function scopedPresenceFile(scope) {
     const digest = createHash('sha256').update(String(scope || 'local')).digest('hex').slice(0, 24);
@@ -31,8 +32,6 @@ export class AgentSessions {
     presenceBroadcast = null;
     /** A desktop identity is presence, not a permanent login badge. */
     static IDLE_TIMEOUT_MS = 30 * 60 * 1000;
-    static RECONNECT_MIN_MS = 1_000;
-    static RECONNECT_MAX_MS = 30_000;
     /** @param wsBase returns the relay ws base, e.g. wss://…/  (no trailing path) */
     constructor(wsBase, presenceScope = 'local') {
         this.wsBase = wsBase;
@@ -188,8 +187,7 @@ export class AgentSessions {
     scheduleReconnect(agentId, spec) {
         if (this.specs.get(agentId) !== spec || spec.reconnectTimer)
             return;
-        const delay = spec.reconnectDelay;
-        spec.reconnectDelay = Math.min(spec.reconnectDelay * 2, AgentSessions.RECONNECT_MAX_MS);
+        const delay = spec.backoff.next();
         spec.reconnectTimer = setTimeout(() => {
             spec.reconnectTimer = null;
             this.openSocket(agentId, spec);
@@ -213,6 +211,7 @@ export class AgentSessions {
         const url = `${base}/my/workspace/ws?token=${encodeURIComponent(spec.token)}&clientType=agent&client=agent&deviceId=agent-${encodeURIComponent(agentId)}`;
         let ws;
         let opened = false;
+        let openedAt = null;
         let settled = false;
         let timer = null;
         const settleFirst = (result) => {
@@ -253,7 +252,10 @@ export class AgentSessions {
             // Reconnecting transport is not agent activity. A new socket stays inactive until a
             // verified call touches the identity; a persisted interaction keeps its existing clock.
             this.scheduleIdleExpiry(agentId);
-            spec.reconnectDelay = AgentSessions.RECONNECT_MIN_MS;
+            // ⚠ PPO-532: opening is not recovering — this reset-on-open made a workspace that drops
+            // every new socket while hydrating (1006) see a reconnect every ~1 s, in step with the
+            // daemon's own socket. The backoff now resets only after the socket stays open 60 s.
+            openedAt = spec.backoff.opened();
             this.syncPersistedInteractions();
             this.syncActiveSessionsFile();
             settleFirst({ ok: true });
@@ -290,6 +292,7 @@ export class AgentSessions {
                 return;
             }
             this.syncActiveSessionsFile();
+            spec.backoff.closed(openedAt);
             this.scheduleReconnect(agentId, spec);
         };
     }
@@ -300,7 +303,7 @@ export class AgentSessions {
         const spec = {
             token,
             reconnectTimer: null,
-            reconnectDelay: AgentSessions.RECONNECT_MIN_MS,
+            backoff: new ReconnectBackoff(),
         };
         this.specs.set(agentId, spec);
         return new Promise((resolve) => this.openSocket(agentId, spec, resolve));

package/dist/agents-md-text.js

@@ -22,6 +22,22 @@ export const LEGACY_BLOCK_MARKERS = [
     ['<!-- clearly:cli:start -->', '<!-- clearly:cli:end -->'],
     ['<!-- clearly:mcp:start -->', '<!-- clearly:mcp:end -->'],
 ];
+/**
+ * The opt-out (AWO-403): a project whose AGENTS.md or CLAUDE.md carries this exact line is not tracked in Clearly.
+ * The global block (agentsGlobal.ts) and the MCP standing instructions name it, so the opt-out is a literal an agent
+ * matches, not a sentence it interprets. `beehaven agents-md --not-tracked` writes it between Clearly's markers.
+ */
+export const AGENTS_MD_OPT_OUT_LINE = 'Clearly: not tracked';
+/** The opted-out project's block: the line, inside the same markers, so re-running the setup turns tracking back on. */
+export function agentsMdOptOutBlock() {
+    return [
+        AGENTS_MD_START,
+        '<!-- managed-by: clearly. Run `beehaven agents-md` to track this project in Clearly again. -->',
+        '',
+        AGENTS_MD_OPT_OUT_LINE,
+        AGENTS_MD_END,
+    ].join('\n');
+}
 /** How Claude Code runs the MCP server's `clearly-agents-md` prompt, which writes the block. */
 export const MCP_AGENTS_MD_SLASH = '/mcp__clearly__clearly-agents-md';
 /** What goes in CLAUDE.md so Claude Code reads the AGENTS.md block too. */
@@ -68,13 +84,17 @@ export function agentsMdBlock(agentName) {
         '   Record decisions, open questions and progress as comments (`clearly_comment`).',
         '5. Mark it done only after verifying the result, with the resolution and any remaining risk.',
         '',
+        'Questions and reads need no ticket.',
+        '',
         '### End of every session',
         '',
         '- Leave a handoff: what you did and what is next. CLI: `beehaven agent handoff "<done · next>"`.',
         '  MCP: a comment on the work ticket.',
         '',
         'If this session has neither the `clearly_*` tools nor `beehaven`, stop and ask the person to connect',
-        'Clearly (clearly.sh/docs/mcp or clearly.sh/docs/cli). Do not skip the tracking.',
+        'Clearly (clearly.sh/docs/mcp or clearly.sh/docs/cli). Do not skip the tracking. In CI or a cloud',
+        'agent, where nobody can sign in, connect over MCP with an agent token from the agent\'s details in',
+        'Clearly, kept as a secret.',
         AGENTS_MD_END,
     ].join('\n');
 }

package/dist/browser-login.js

@@ -291,3 +291,97 @@ export async function browserLogin() {
     persistBrowserLogin(captured);
     return captured;
 }
+/** The relay's HTTPS origin for the configured env (prod when unconfigured). */
+export function relayHttpFromConfig(cfg = readConfig(), env = process.env) {
+    const override = env.BEEHAVEN_RELAY_HTTP_URL;
+    if (override)
+        return override.replace(/\/+$/, '');
+    return resolveRelaySelection(cfg).url.replace(/^wss:\/\//, 'https://').replace(/^ws:\/\//, 'http://').replace(/\/+$/, '');
+}
+/**
+ * True where a browser on this machine is unlikely: an SSH session, CI, or Linux with no display.
+ * `beehaven login --browser` overrides it; `--device-code` forces the device flow anywhere.
+ */
+export function preferDeviceLogin(env = process.env, platform = process.platform) {
+    if (env.SSH_CONNECTION || env.SSH_TTY || env.CI)
+        return true;
+    return platform === 'linux' && !env.DISPLAY && !env.WAYLAND_DISPLAY;
+}
+/** The approval page, optionally with the code filled in. */
+export function deviceAuthUrl(authOrigin, userCode) {
+    return withUtm(`${authOrigin}/cli/device${userCode ? `?code=${encodeURIComponent(userCode)}` : ''}`);
+}
+/** Email and name from the ID token's payload, for the "Signed in as" line. Display only. */
+function idTokenClaims(idToken) {
+    try {
+        const payload = JSON.parse(Buffer.from(idToken.split('.')[1] ?? '', 'base64url').toString('utf8'));
+        return { email: typeof payload.email === 'string' ? payload.email : undefined, name: typeof payload.name === 'string' ? payload.name : undefined };
+    }
+    catch {
+        return {};
+    }
+}
+export function captureDeviceLogin(opts) {
+    const { relayOrigin, authOrigin, client, fetchImpl = fetch, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), now = Date.now, log = (line) => console.log(line), } = opts;
+    const post = async (path, body) => {
+        const res = await fetchImpl(`${relayOrigin}${path}`, {
+            method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body),
+        });
+        const json = await res.json().catch(() => ({}));
+        return { res, json };
+    };
+    return (async () => {
+        let start;
+        try {
+            const { res, json } = await post('/cli/device/start', { client });
+            if (!res.ok || !json?.ok)
+                throw new Error(json?.error === 'slow_down' ? 'Too many sign-in attempts from here. Wait a while and try again.' : (json?.error || `relay answered ${res.status}`));
+            start = json;
+        }
+        catch (err) {
+            throw new Error(`Couldn't start a device sign-in: ${err?.message ?? err}`);
+        }
+        log('');
+        log(`  On any device with a browser, open  ${color.cyan(deviceAuthUrl(authOrigin))}`);
+        log(`  and enter this code:                 ${color.bold(start.userCode)}`);
+        log('');
+        log(color.dim(`  Direct link: ${deviceAuthUrl(authOrigin, start.userCode)}`));
+        log(color.dim(`  Waiting for approval (the code expires in ${Math.round(start.expiresIn / 60)} minutes)…`));
+        let interval = Math.max(1, start.interval) * 1000;
+        const deadline = now() + start.expiresIn * 1000;
+        while (now() < deadline) {
+            await sleep(interval);
+            let res;
+            let json;
+            try {
+                ({ res, json } = await post('/cli/device/token', { deviceCode: start.deviceCode }));
+            }
+            catch {
+                continue; // a dropped poll is retried at the next tick
+            }
+            if (res.ok && json?.ok && json.idToken && json.refreshToken && json.userId) {
+                const { email, name } = idTokenClaims(json.idToken);
+                return { idToken: json.idToken, refreshToken: json.refreshToken, userId: json.userId, email, displayName: name };
+            }
+            switch (json?.error) {
+                case 'authorization_pending': continue;
+                case 'slow_down':
+                    interval += 5000;
+                    continue;
+                case 'access_denied': throw new Error('The sign-in was denied in the browser.');
+                case 'expired_token': throw new Error('The code expired. Run `beehaven login --device-code` again.');
+                default:
+                    if (res.status >= 500)
+                        throw new Error(json?.error || `relay answered ${res.status}`);
+            }
+        }
+        throw new Error('The code expired. Run `beehaven login --device-code` again.');
+    })();
+}
+/** Device-code sign-in end to end: start, show the code, poll, persist like the browser flow. */
+export async function deviceLogin(opts = {}) {
+    const { authOrigin } = resolveAuthOrigin();
+    const captured = await captureDeviceLogin({ relayOrigin: relayHttpFromConfig(), authOrigin, client: opts.client });
+    persistBrowserLogin(captured);
+    return captured;
+}

package/dist/build-channel.js

@@ -53,9 +53,9 @@ export const PUBLIC_BUILD = true;
  * ⚠ REWRITTEN IN `dist/` AT BUILD TIME, like `PUBLIC_BUILD`. `unstamped` is what a source checkout
  * carries and what `tsx`/`vitest` see, and it is honest: nothing has stamped them.
  */
-export const BUILD_SHA = 'f866489dd2f1';
+export const BUILD_SHA = '31746b91dfbf';
 /** ISO-8601 minute precision, UTC. Rewritten in `dist/` by `scripts/stamp-build-channel.mjs`. */
-export const BUILD_TIME = '2026-10-28T16:02Z';
+export const BUILD_TIME = '2026-10-29T05:50Z';
 /**
  * The build identity as one short string, for `--version`.
  *

package/dist/cli.js

@@ -284,6 +284,7 @@ ${DEV_ONLY_HELP ? `  PROJECT — build your own Durable Object backend  (HIVE_DE
     mcp status                               Which clients are configured
     mcp remove                               Remove the entries + revoke the token
     mcp-config [--name N]                    Print the block instead of writing it
+    mcp-config --token-only --expires <days> Print ONLY the token, for a secret store
 
     Anywhere else — claude.ai, Claude Desktop, another machine — point the client
     at the endpoint and let it log you in; nothing to install and no token to paste:
@@ -1417,6 +1418,10 @@ async function run() {
             // (a live client) when none is connected; `--dev` → localhost.
             launch: { type: 'boolean', default: false },
             browser: { type: 'boolean', default: false },
+            // `beehaven login --device-code` — sign in by approving a code on another device (AWO-402).
+            'device-code': { type: 'boolean', default: false },
+            // `beehaven agents-md --not-tracked` — write the opt-out line instead of the tracked block (AWO-403).
+            'not-tracked': { type: 'boolean', default: false },
             dev: { type: 'boolean', default: false },
             // `beehaven canvas perceive --pixels --max 80`, `canvas verify --keep`
             pixels: { type: 'boolean', default: false },
@@ -1461,6 +1466,8 @@ async function run() {
             client: { type: 'string' },
             /** `beehaven mcp install --rotate` — mint a new token instead of reusing the installed one. */
             rotate: { type: 'boolean' },
+            /** `beehaven mcp-config --token-only --expires <days>` — the raw token alone on stdout, for piping. */
+            'token-only': { type: 'boolean' },
             password: { type: 'string' },
             email: { type: 'string' },
             expires: { type: 'string' },
@@ -3033,10 +3040,19 @@ async function run() {
             // own copy aimed at /auth/beehaven, a route the web app no longer serves.
             // What follows the sign-in — restarting the daemon, teaching the agents —
             // stays here, because the daemon fallback must not restart itself.
+            // AWO-402 — the device-code flow for a machine with no browser of its own: forced with
+            // `--device-code`, chosen automatically over SSH / CI / a display-less Linux, and never when
+            // the person asked for `--browser`.
             let captured;
             try {
-                const { browserLogin } = await import('./browser-login.js');
-                captured = await browserLogin();
+                const { browserLogin, deviceLogin, preferDeviceLogin } = await import('./browser-login.js');
+                const useDevice = Boolean(values['device-code']) || (!values.browser && preferDeviceLogin());
+                if (useDevice && !values['device-code']) {
+                    console.log(color.dim('  No browser on this machine, so signing in with a code (`beehaven login --browser` to open one here).'));
+                }
+                captured = useDevice
+                    ? await deviceLogin({ client: `beehaven ${getVersion()} (${process.platform})` })
+                    : await browserLogin();
             }
             catch (err) {
                 console.error(`  ${color.red('✗')} ${err?.message ?? err}`);
@@ -3170,6 +3186,7 @@ async function run() {
                 mcp: !!values.mcp,
                 print: !!values.print,
                 remove: !!values.remove,
+                notTracked: Boolean(values['not-tracked']),
             });
             break;
         }
@@ -4073,10 +4090,82 @@ complete -F _beehaven_completions beehaven`);
             const tgtAddress = tgt?.address ?? 'home';
             const mcpEntry = entryNameFor(tgtAddress);
             const wsId = isHomeAddress(tgtAddress) ? '' : tgtAddress.split('/').slice(1).join('/');
-            const label = values.name || `${mcpEntry} · ${new Date().toISOString().slice(0, 10)}`;
+            const defaultMcpLabel = `${mcpEntry} · ${new Date().toISOString().slice(0, 10)}`;
             const { rpcOnce: _rpc } = await import('./ipc-client.js');
             const { resolveActiveAgent } = await import('./agent-state.js');
+            const { mcpMintInput, runMcpTokenOnly } = await import('./commands/mcp-token.js');
             const activeMcpAgent = resolveActiveAgent(values);
+            /**
+             * ⚠⚠ DO NOT ECHO THE RAW ERROR — IT SENT PEOPLE TO THE WRONG FIX.
+             *
+             * Observed: this printed "Cannot connect to daemon. Run `beehaven start --headless`" in the
+             * same second that `beehaven status` reported "Daemon: running". The daemon was up and the
+             * RELAY had dropped. Following the advice runs into the single-instance guard, which
+             * refuses — so the message costs a cycle and teaches the wrong model of the failure.
+             *
+             * The CLI already distinguishes these three states carefully (see `status`), precisely
+             * because the fixes are mutually exclusive: a restart will NOT refresh an expired token,
+             * and a re-login will NOT revive a dropped socket. This path bypassed all of it by
+             * forwarding whatever string the transport happened to raise.
+             *
+             * Re-probe and say what is actually true. Stderr only, and it returns the exit code, so the
+             * `--token-only` path can use it without touching stdout.
+             */
+            const explainMintFailure = async (err) => {
+                const { isDaemonRunning } = await import('./daemon-client.js');
+                let up = false;
+                try {
+                    up = await isDaemonRunning();
+                }
+                catch {
+                    up = false;
+                }
+                let expired = false;
+                try {
+                    const cfg = JSON.parse(readFileSync(join(homedir(), '.beehaven', 'config.json'), 'utf8'));
+                    const payload = JSON.parse(Buffer.from(String(cfg.token).split('.')[1], 'base64').toString());
+                    expired = !payload.exp || Date.now() / 1000 > payload.exp - 60;
+                }
+                catch {
+                    expired = true;
+                }
+                console.error(`  ${color.red('✗')} Could not mint a token.`);
+                console.error(!up
+                    ? '    The daemon is not running — `beehaven start --headless`'
+                    : expired
+                        ? '    The daemon is up but your token has EXPIRED — `beehaven login` (a restart will not refresh it)'
+                        : '    The daemon is up and your token is valid; the relay socket dropped — `beehaven restart`');
+                console.error(color.dim(`    (${err?.message ?? err})`));
+                return 1;
+            };
+            /**
+             * ⚠⚠ `--token-only`: THE RAW TOKEN ON STDOUT AND NOTHING ELSE, for
+             * `… | gh secret set CLEARLY_MCP_TOKEN`. The rules (stderr for every message, `--expires`
+             * required, the caller's own agent) live in commands/mcp-token.ts, where the tests call them.
+             * It branches off HERE, before the reuse check (print never reuses) and before anything below
+             * writes to stdout.
+             */
+            if (values['token-only']) {
+                process.exitCode = await runMcpTokenOnly({
+                    sub: mcpSub,
+                    flags: values,
+                    defaultLabel: defaultMcpLabel,
+                    agentId: activeMcpAgent?.agentId,
+                    mint: (input) => _rpc('create-mcp-token', input, 30_000),
+                    out: (s) => { process.stdout.write(s); },
+                    err: (s) => { process.stderr.write(s); },
+                    stdoutIsTTY: Boolean(process.stdout.isTTY),
+                    onMintError: explainMintFailure,
+                });
+                break;
+            }
+            // `--label` (else `--name`), `--expires <days>` and the caller's agent, for every mint below.
+            const mintInput = mcpMintInput(values, { label: defaultMcpLabel, agentId: activeMcpAgent?.agentId });
+            if ('error' in mintInput) {
+                console.error(`  ${color.red('✗')} ${mintInput.error}`);
+                process.exit(2);
+            }
+            const label = mintInput.input.label;
             let res;
             /**
              * ⚠⚠ REUSE THE TOKEN ALREADY INSTALLED RATHER THAN MINTING ANOTHER. Minting
@@ -4121,54 +4210,11 @@ complete -F _beehaven_completions beehaven`);
                 }
             }
             try {
-                if (!res) {
-                    res = await _rpc('create-mcp-token', {
-                        label,
-                        ...(activeMcpAgent?.agentId ? { agentId: activeMcpAgent.agentId } : {}),
-                    }, 30_000);
-                }
+                if (!res)
+                    res = await _rpc('create-mcp-token', mintInput.input, 30_000);
             }
             catch (err) {
-                /**
-                 * ⚠⚠ DO NOT ECHO THE RAW ERROR — IT SENT PEOPLE TO THE WRONG FIX.
-                 *
-                 * Observed: this printed "Cannot connect to daemon. Run `beehaven start --headless`" in the
-                 * same second that `beehaven status` reported "Daemon: running". The daemon was up and the
-                 * RELAY had dropped. Following the advice runs into the single-instance guard, which
-                 * refuses — so the message costs a cycle and teaches the wrong model of the failure.
-                 *
-                 * The CLI already distinguishes these three states carefully (see `status`), precisely
-                 * because the fixes are mutually exclusive: a restart will NOT refresh an expired token,
-                 * and a re-login will NOT revive a dropped socket. This path bypassed all of it by
-                 * forwarding whatever string the transport happened to raise.
-                 *
-                 * Re-probe and say what is actually true.
-                 */
-                const { isDaemonRunning } = await import('./daemon-client.js');
-                let up = false;
-                try {
-                    up = await isDaemonRunning();
-                }
-                catch {
-                    up = false;
-                }
-                let expired = false;
-                try {
-                    const cfg = JSON.parse(readFileSync(join(homedir(), '.beehaven', 'config.json'), 'utf8'));
-                    const payload = JSON.parse(Buffer.from(String(cfg.token).split('.')[1], 'base64').toString());
-                    expired = !payload.exp || Date.now() / 1000 > payload.exp - 60;
-                }
-                catch {
-                    expired = true;
-                }
-                console.error(`  ${color.red('✗')} Could not mint a token.`);
-                console.error(!up
-                    ? '    The daemon is not running — `beehaven start --headless`'
-                    : expired
-                        ? '    The daemon is up but your token has EXPIRED — `beehaven login` (a restart will not refresh it)'
-                        : '    The daemon is up and your token is valid; the relay socket dropped — `beehaven restart`');
-                console.error(color.dim(`    (${err?.message ?? err})`));
-                process.exit(1);
+                process.exit(await explainMintFailure(err));
             }
             if (!res?.key) {
                 console.error(`  ${color.red('✗')} ${res?.error ?? 'No token returned.'}`);

package/dist/commands/agent-instructions.js

@@ -14,9 +14,12 @@
  * means both converge and either uninstaller removes it. `agentInstructionParity.test.mjs` in the
  * root repo pins the two copies together.
  *
- * ⚠ CLAUDE GETS THE SHORT POINTER — `~/.claude/CLAUDE.md` is prepended to every Claude Code
- * session in every repository, so it carries a pointer to the skills, not a manual. Same rule as
- * the Mac app; see its note on `AGENT_INSTRUCTION_FILES`.
+ * ⚠ ONE TRACKED BLOCK FOR EVERY AGENT, MCP OR CLI (founder 2026-10-28, AWO-401 follow-up: anyone
+ * using Clearly gets the mandatory block). It is short (~15 lines) because `~/.claude/CLAUDE.md` is
+ * prepended to every Claude Code session in every repository; the exact verbs stay in the skills.
+ * It has an escape hatch — a project's AGENTS.md or the person can say a project is not tracked —
+ * and a project's own Clearly block takes precedence. The web copy for pasting (Cursor's user
+ * rules) is the monorepo's lib/connections/agentsGlobal.ts, pinned to this one by a test.
  *
  * ⚠ ONLY OUR BLOCK IS EVER TOUCHED. Text around it is preserved byte for byte; a file with no
  * block gets one appended; removal deletes the block and nothing else.
@@ -41,34 +44,24 @@ export function instructionBlock() {
         BLOCK_START,
         `<!-- ${MANAGED_MARKER}. Edits inside this block are overwritten on app launch; edit outside it. -->`,
         '',
-        '## Clearly — drive it with the `beehaven` CLI',
+        '## Clearly workspace: track your work there',
         '',
-        'Clearly (clearly.sh) is a workspace — documents, projects, boards, tickets and a design',
-        'canvas. Reach it from the shell with the `beehaven` CLI, NOT an HTTP API you construct.',
+        'This person keeps their plans, tickets, documents and designs in Clearly (clearly.sh). Track every',
+        'task there, even unasked and in any project, unless the project\'s AGENTS.md or CLAUDE.md has the line',
+        '`Clearly: not tracked`, or the person says not to track it. A project\'s own Clearly block in AGENTS.md',
+        'takes precedence over this one.',
         '',
-        '⚠ SIGN IN FIRST. Every call is attributed to an agent identity, and without one the CLI',
-        'refuses. `login` MINTS the name if it does not exist yet, and binds this terminal:',
+        'Use whichever route this session has: the `clearly_*` MCP tools, or the `beehaven` CLI.',
         '',
-        '```sh',
-        'beehaven agent login <your-name>   # required — mints + binds, once per session',
-        'beehaven connect home              # target the personal workspace',
-        'beehaven actions                   # list every action available there',
-        'beehaven call <action> \'{...}\'',
-        '```',
+        '- Start. CLI: `beehaven agent login <your-name> --label "<the task>"` (claude, codex, gemini…), then',
+        '  read the brief it prints; if the daemon is not running, `beehaven start --headless`. MCP: you are',
+        '  already signed in.',
+        '- Each task: search first, then create a ticket before changing code or files and move it to',
+        '  in-progress. File what you make into the project, record decisions as comments, and mark it done',
+        '  only after verifying. Questions and reads need no ticket.',
+        '- End: a handoff, `beehaven agent handoff "<done · next>"` on the CLI or a comment on the work ticket.',
         '',
-        'Read the full skills before driving it — they carry the exact verbs and node shapes:',
-        '',
-        '- `~/.<agent>/skills/clearly-agent/SKILL.md` — **read this first**: identity, sessions, your brief',
-        '- `~/.<agent>/skills/beehaven-cli/SKILL.md` — connect / call / sql / logs, the daemon',
-        '- `~/.<agent>/skills/clearly-workspace/SKILL.md` — audit what a workspace holds and who made it',
-        '- `~/.<agent>/skills/clearly-canvas/SKILL.md` — build + perceive a canvas, comm blocks, code diffs',
-        '- `~/.<agent>/skills/design-craft/SKILL.md` — **load before any visual work**: grid, type, colour, the studio pass',
-        '- `~/.<agent>/skills/layout-systems/SKILL.md` — grids and systems across many artboards',
-        '- `~/.<agent>/skills/pair-on-canvas/SKILL.md` — drive a coding task from a spec on the canvas',
-        '- `~/.<agent>/skills/codebase-map/SKILL.md` — draw a repo’s architecture on the canvas',
-        '',
-        'If a command reports the daemon is unreachable, `beehaven login` re-auths and',
-        '`beehaven start --headless` starts a daemon when the Mac app is not running.',
+        'Detail is in the `clearly-agent` skill (`beehaven skills install` puts the skills in place).',
         BLOCK_END,
     ].join('\n');
 }
@@ -78,9 +71,24 @@ export function claudeBlock() {
         BLOCK_START,
         `<!-- ${MANAGED_MARKER}. Edits inside this block are overwritten on app launch; edit outside it. -->`,
         '',
-        '**Clearly workspace** — drive it from the shell with the `beehaven` CLI (documents, projects,',
-        'boards, tickets, canvas). Sign in once per session first: `beehaven agent login <name>` —',
-        'it mints the identity if new. Full detail is in the skills, `clearly-agent` first.',
+        '## Clearly workspace: track your work there',
+        '',
+        'This person keeps their plans, tickets, documents and designs in Clearly (clearly.sh). Track every',
+        'task there, even unasked and in any project, unless the project\'s AGENTS.md or CLAUDE.md has the line',
+        '`Clearly: not tracked`, or the person says not to track it. A project\'s own Clearly block in AGENTS.md',
+        'takes precedence over this one.',
+        '',
+        'Use whichever route this session has: the `clearly_*` MCP tools, or the `beehaven` CLI.',
+        '',
+        '- Start. CLI: `beehaven agent login <your-name> --label "<the task>"` (claude, codex, gemini…), then',
+        '  read the brief it prints; if the daemon is not running, `beehaven start --headless`. MCP: you are',
+        '  already signed in.',
+        '- Each task: search first, then create a ticket before changing code or files and move it to',
+        '  in-progress. File what you make into the project, record decisions as comments, and mark it done',
+        '  only after verifying. Questions and reads need no ticket.',
+        '- End: a handoff, `beehaven agent handoff "<done · next>"` on the CLI or a comment on the work ticket.',
+        '',
+        'Detail is in the `clearly-agent` skill (`beehaven skills install` puts the skills in place).',
         BLOCK_END,
     ].join('\n');
 }

package/dist/commands/agents-md.js

@@ -23,7 +23,7 @@ import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
 import { join, resolve } from 'path';
 import { execFileSync } from 'child_process';
 import { color } from '../spinner.js';
-import { AGENTS_MD_START, AGENTS_MD_END, LEGACY_BLOCK_MARKERS, CLAUDE_MD_IMPORT, agentsMdBlock } from '../agents-md-text.js';
+import { AGENTS_MD_START, AGENTS_MD_END, LEGACY_BLOCK_MARKERS, CLAUDE_MD_IMPORT, agentsMdBlock, agentsMdOptOutBlock } from '../agents-md-text.js';
 /**
  * The Claude Code permission that lets an agent run `beehaven` without a prompt per call (AWO-401).
  * The tracked block makes several calls a task; a prompt on each one pushes people to turn tracking
@@ -141,6 +141,11 @@ export function upsertAgentsMdBlock(text, block) {
     return spliceBlock(text, block, AGENTS_MD_START, AGENTS_MD_END);
 }
 /** `mcp` is accepted for older instructions and changes nothing: there is one block (AWO-401). */
+/**
+ * `notTracked` (AWO-403) writes the opt-out — the line `Clearly: not tracked` between the same markers — so the global
+ * block every agent carries leaves this project alone. It skips the `beehaven` permission rule (nothing here will call
+ * it); re-running without the flag puts the tracked block back.
+ */
 export function writeProjectAgentsMd(opts) {
     const root = projectRoot(resolve(opts.dir));
     const agentsPath = join(root, 'AGENTS.md');
@@ -156,7 +161,7 @@ export function writeProjectAgentsMd(opts) {
         files.push(writeClaudeSettings(root, true));
         return { root, files };
     }
-    const next = upsertAgentsMdBlock(before, agentsMdBlock());
+    const next = upsertAgentsMdBlock(before, opts.notTracked ? agentsMdOptOutBlock() : agentsMdBlock());
     if (next !== before)
         writeFileSync(agentsPath, next);
     files.push({ path: agentsPath, change: !had ? 'created' : next !== before ? 'updated' : 'current' });
@@ -173,17 +178,18 @@ export function writeProjectAgentsMd(opts) {
     else {
         files.push({ path: claudePath, change: 'current' });
     }
-    files.push(writeClaudeSettings(root, false));
+    if (!opts.notTracked)
+        files.push(writeClaudeSettings(root, false));
     return { root, files };
 }
 export function cmdAgentsMd(dir, opts) {
     if (opts.print) {
-        process.stdout.write(agentsMdBlock() + '\n');
+        process.stdout.write((opts.notTracked ? agentsMdOptOutBlock() : agentsMdBlock()) + '\n');
         return 0;
     }
     let r;
     try {
-        r = writeProjectAgentsMd({ dir: dir ?? process.cwd(), mcp: opts.mcp, remove: opts.remove });
+        r = writeProjectAgentsMd({ dir: dir ?? process.cwd(), mcp: opts.mcp, remove: opts.remove, notTracked: opts.notTracked });
     }
     catch (err) {
         console.error(`  ${color.red('✗')} ${err?.message ?? err}`);

package/dist/commands/help.js

@@ -390,13 +390,23 @@ const PAGES = {
      * where they have already found the verb.
      */
     login: {
-        synopsis: 'beehaven login',
+        synopsis: 'beehaven login [--device-code | --browser]',
         description: `Sign in. Opens your browser, then starts (or restarts) the daemon so the
     new tokens take effect — the daemon reads credentials at startup and has no hot-reload.
 
+    No browser on this machine (SSH, a container, a remote box)? \`--device-code\` prints a short
+    code; open the link it shows on any device, sign in and approve, and this machine is signed in.
+    It is chosen automatically over SSH, in CI and on Linux with no display; \`--browser\` opens
+    one here anyway.
+
     A restart alone will NOT refresh an expired token; \`login\` is the fix for that.`,
+        flags: [
+            { name: '--device-code', desc: 'Sign in by approving a code on another device' },
+            { name: '--browser', desc: 'Open a browser on this machine even over SSH' },
+        ],
         examples: [
             { cmd: 'beehaven login' },
+            { cmd: 'beehaven login --device-code', note: 'on a machine with no browser' },
             { cmd: 'beehaven status', note: 'confirms the relay actually connected' },
         ],
         related: ['logout', 'whoami', 'status', 'doctor'],
@@ -414,7 +424,7 @@ const PAGES = {
         related: ['login', 'guide'],
     },
     'agents-md': {
-        synopsis: 'beehaven agents-md [dir] [--print] [--remove]',
+        synopsis: 'beehaven agents-md [dir] [--not-tracked] [--print] [--remove]',
         description: `Add the Clearly block to this project's AGENTS.md, so every agent that opens the
     repository — a teammate's Codex or Claude Code, a cloud agent, CI — tracks its work in the
     workspace: sign in, a ticket for every task, a handoff at the end. One block serves agents on
@@ -427,6 +437,7 @@ const PAGES = {
     already points the agents on THIS machine at Clearly (their global instruction files); this is
     the shared, committed copy for everyone who opens the repository.`,
         flags: [
+            { name: '--not-tracked', desc: 'Write the line `Clearly: not tracked` instead, so agents leave this project out' },
             { name: '--print', desc: 'Print the block and write nothing' },
             { name: '--remove', desc: 'Take the block out again' },
             { name: '--mcp', desc: 'Accepted for older instructions; the block is the same for MCP and the CLI' },
@@ -1690,7 +1701,7 @@ const PAGES = {
         related: ['context', 'pwd', 'workspace'],
     },
     'mcp-config': {
-        synopsis: 'beehaven mcp-config [--name <server-name>]',
+        synopsis: 'beehaven mcp-config [--label <text>] [--expires <days>] [--token-only]',
         description: `Print the MCP server block instead of writing it — for a client
     \`mcp install\` does not know about, or a config you keep in version control.
 
@@ -1699,9 +1710,30 @@ const PAGES = {
     revoke with \`beehaven mcp remove\` rather than just deleting the text.
 
     ⚠ The block is minted for the workspace you are CONNECTED to — \`beehaven
-    pwd\` first.`,
+    pwd\` first.
+
+    \`--token-only\` is for CI: stdout gets the raw token and one newline,
+    nothing else; every other message goes to stderr, so it pipes straight
+    into a secret store. It needs \`--expires <days>\` (\`0\` = never),
+    because a CI secret is set once and rarely looked at again.
+
+    ⚠⚠ WITH --token-only, STDOUT IS A LIVE SECRET. Pipe it; do not let it
+    land in a terminal, a log or a file you commit. Use \`set -o pipefail\` so a
+    refused or failed mint fails the job instead of storing an empty secret.
+    The token is bound to YOUR agent identity (the one \`agent whoami\` shows),
+    like \`mcp install\`; revoke it with the \`revoke-mcp-token\` line the
+    command prints to stderr.`,
+        flags: [
+            { name: '--token-only', desc: 'Print only the ck_mcp_ token on stdout (messages on stderr). Needs --expires.' },
+            { name: '--expires <days>', desc: 'Token lifetime in whole days; 0 = never expires. Default without it: 365.' },
+            { name: '--label <text>', desc: 'The token\'s label in Settings and list-mcp-tokens. --name is the older spelling; it labels the token, not the server entry.' },
+        ],
         examples: [
             { cmd: 'beehaven mcp-config --name clearly' },
+            {
+                cmd: 'set -o pipefail; beehaven mcp-config --token-only --expires 90 --label ci-github | gh secret set CLEARLY_MCP_TOKEN',
+                note: 'CI secret: a 90-day token, never shown on screen',
+            },
             { cmd: 'beehaven mcp install', note: 'write it for detected clients instead' },
             { cmd: 'beehaven mcp remove', note: 'revoke the token' },
         ],

package/dist/commands/mcp-token.js

@@ -0,0 +1,113 @@
+/**
+ * `beehaven mcp-config --token-only` — the raw `ck_mcp_` token on stdout and nothing else, so it
+ * can be piped straight into a secret store (founder request, 2026-10-29):
+ *
+ *     set -o pipefail
+ *     beehaven mcp-config --token-only --expires 90 --label ci-github | gh secret set CLEARLY_MCP_TOKEN
+ *
+ * ⚠⚠ STDOUT IS THE SECRET, SO STDOUT CARRIES NOTHING ELSE. One stray byte on stdout (a ✓, a blank
+ * line, an update notice) becomes part of the stored secret, and the CI job then fails with an
+ * auth error that names nothing. Every message here, refusals included, goes to stderr, and on any
+ * failure stdout stays EMPTY, so the pipe stores nothing that looks like a working token.
+ *
+ * ⚠ AN EXPIRY IS REQUIRED. A token minted for CI goes into a secret store nobody re-reads; leaving
+ * `--expires` off would give it the server's 365-day default by omission, an unbounded secret in
+ * practice. `--expires 0` is the explicit "never expires" for a caller who means it.
+ *
+ * ⚠ THE TOKEN IS THE CALLER'S OWN. It is bound to the active agent identity exactly as
+ * `mcp install` binds it, and the server refuses a token for any other agent
+ * (`agentTokenRefusal`, apps/cloudflare/src/rpc/mcp-token-rpcs.ts).
+ *
+ * The decisions live here, not inline in cli.ts, so the tests can call them: a grep over cli.ts
+ * cannot tell "stdout holds exactly the token" from "the line moved".
+ */
+import { color } from '../spinner.js';
+/**
+ * `--expires <days>`: a whole number of days, `0` = no expiry. Absent means "not given".
+ * (Results are told apart with `'error' in r`: the CLI compiles without strictNullChecks, where
+ * an `ok: true | false` discriminant does not narrow.)
+ */
+export function parseExpiresDays(raw) {
+    if (raw === undefined || raw === null)
+        return {};
+    const s = String(raw).trim();
+    if (!/^\d+$/.test(s) || !Number.isSafeInteger(Number(s))) {
+        return { error: `--expires takes a whole number of days (0 = never expires), not "${s}".` };
+    }
+    return { days: Number(s) };
+}
+/**
+ * The `create-mcp-token` input for every mint in `mcp` / `mcp-config`: `--label` (else `--name`,
+ * else the dated default), `--expires` as `expiresInDays` when given, and the caller's own agent.
+ */
+export function mcpMintInput(flags, defaults) {
+    const expiry = parseExpiresDays(flags.expires);
+    if ('error' in expiry)
+        return expiry;
+    const text = (v) => (typeof v === 'string' ? v.trim() : '');
+    const input = { label: text(flags.label) || text(flags.name) || defaults.label };
+    if (expiry.days !== undefined)
+        input.expiresInDays = expiry.days;
+    if (defaults.agentId)
+        input.agentId = defaults.agentId;
+    return { input };
+}
+/** Why `--token-only` cannot run as asked, or null. */
+export function tokenOnlyRefusal(sub, flags) {
+    if (sub !== 'print') {
+        return '--token-only prints a token for you to store; it does not install one.'
+            + ' Use: beehaven mcp-config --token-only --expires <days>';
+    }
+    if (flags.expires === undefined || flags.expires === null) {
+        return '--token-only needs --expires <days>. The token is headed for a CI secret that nobody'
+            + ' re-reads, and without an expiry it would stay valid for a year by default.'
+            + ' Pass --expires 90, or --expires 0 if it should never expire.';
+    }
+    return null;
+}
+/** A `ck_mcp_` bearer and nothing else: no whitespace, no JSON, no error text. */
+const MCP_TOKEN = /^ck_mcp_[A-Za-z0-9_-]+$/;
+/** Runs `--token-only`; returns the exit code. Writes stdout only on success. */
+export async function runMcpTokenOnly(run) {
+    const refusal = tokenOnlyRefusal(run.sub, run.flags);
+    if (refusal) {
+        run.err(`  ${color.red('✗')} ${refusal}\n`);
+        return 2;
+    }
+    const built = mcpMintInput(run.flags, { label: run.defaultLabel, agentId: run.agentId });
+    if ('error' in built) {
+        run.err(`  ${color.red('✗')} ${built.error}\n`);
+        return 2;
+    }
+    let res;
+    try {
+        res = await run.mint(built.input);
+    }
+    catch (e) {
+        if (run.onMintError)
+            return run.onMintError(e);
+        run.err(`  ${color.red('✗')} Could not mint a token: ${e?.message ?? e}\n`);
+        return 1;
+    }
+    const key = typeof res?.key === 'string' ? res.key : '';
+    if (!MCP_TOKEN.test(key)) {
+        run.err(`  ${color.red('✗')} ${res?.error ?? 'No ck_mcp_ token returned.'}\n`);
+        return 1;
+    }
+    run.out(`${key}\n`);
+    const prefix = String(res.prefix ?? key.slice(0, 12));
+    const now = run.now?.() ?? Date.now();
+    const expires = typeof res.expiresAt === 'number'
+        ? `expires ${new Date(res.expiresAt).toISOString().slice(0, 10)}`
+        : built.input.expiresInDays === 0
+            ? 'never expires'
+            : `expires in ${built.input.expiresInDays} days (from ${new Date(now).toISOString().slice(0, 10)})`;
+    const agent = res.agentName || res.agentId || built.input.agentId;
+    run.err(`  ${color.green('✓')} Minted ${prefix}  ${color.dim([res.label ?? built.input.label, expires, agent ? `agent ${agent}` : ''].filter(Boolean).join(' · '))}\n`);
+    run.err(color.dim('  stdout carried a live workspace credential, shown this once and stored hashed.\n'));
+    if (run.stdoutIsTTY) {
+        run.err(`  ${color.yellow('⚠')} stdout is a terminal, so the token is on screen. Pipe it into a secret store instead.\n`);
+    }
+    run.err(color.dim(`  Revoke with:  beehaven call revoke-mcp-token '{"prefix":"${prefix}"}'\n`));
+    return 0;
+}

package/dist/reconnect-backoff.js

@@ -0,0 +1,78 @@
+/**
+ * ReconnectBackoff — when to redial a dropped socket, for the daemon's relay socket
+ * (`relay.ts`) and its agent sessions (`agent-sessions.ts`).
+ *
+ * ⚠ PPO-532. Both sockets reset their backoff the moment a socket OPENED. A workspace that
+ * runs out of memory while hydrating a new socket accepts it, then drops it (1006) seconds
+ * later — so every retry was "the first" and came back in ~1 s. On the staging Playground
+ * home that was a reconnect → hydrate → out-of-memory → reset loop, 46 reconnects an hour per
+ * socket, with the two sockets closing in pairs every ~13 s.
+ *
+ * Now a connection only counts as recovered once it has stayed open for `healthyMs` (60 s);
+ * until then the delay keeps doubling. Each delay is FULL JITTER — uniform over
+ * [0, min(cap, base·2^attempt)) — so the daemon socket and its agent sockets (which drop
+ * together) do not come back together. Same shape as HiveClient's PPO-249 backoff.
+ *
+ * No timers: the healthy check is a timestamp read when the socket closes (or when
+ * `attempts` is read), so there is nothing to clean up on shutdown.
+ */
+export const RECONNECT_BASE_MS = 1_000;
+export const RECONNECT_CAP_MS = 30_000;
+export const RECONNECT_HEALTHY_MS = 60_000;
+export class ReconnectBackoff {
+    attempt = 0;
+    openedAt = null;
+    baseMs;
+    capMs;
+    healthyMs;
+    random;
+    now;
+    constructor(opts = {}) {
+        this.baseMs = opts.baseMs ?? RECONNECT_BASE_MS;
+        this.capMs = opts.capMs ?? RECONNECT_CAP_MS;
+        this.healthyMs = opts.healthyMs ?? RECONNECT_HEALTHY_MS;
+        this.random = opts.random ?? Math.random;
+        this.now = opts.now ?? Date.now;
+    }
+    /** Reconnects since the last healthy connection. 0 = healthy (or never failed). */
+    get attempts() {
+        this.settle();
+        return this.attempt;
+    }
+    /**
+     * A socket opened. This does NOT reset the backoff — only staying open does. Returns the
+     * connection's stamp; pass it to `closed()` so a stale socket closing late cannot clear the
+     * clock of the socket that replaced it.
+     */
+    opened() {
+        const at = this.now();
+        this.openedAt = at;
+        return at;
+    }
+    /**
+     * A socket closed. If it had stayed open `healthyMs`, the next retry starts from the base.
+     * `openedAt` is the stamp `opened()` returned (null/omitted = never opened, or the current one).
+     */
+    closed(openedAt = this.openedAt) {
+        if (openedAt !== null && this.now() - openedAt >= this.healthyMs)
+            this.attempt = 0;
+        if (openedAt === this.openedAt)
+            this.openedAt = null;
+    }
+    /** Delay before the next reconnect attempt (ms), and count the attempt. */
+    next() {
+        this.settle();
+        const ceiling = Math.min(this.capMs, this.baseMs * 2 ** Math.min(this.attempt, 30));
+        this.attempt++;
+        return Math.round(this.random() * ceiling);
+    }
+    /** An explicit (re)start — user action, network back, watchdog: start over from the base. */
+    reset() {
+        this.attempt = 0;
+        this.openedAt = null;
+    }
+    settle() {
+        if (this.openedAt !== null && this.now() - this.openedAt >= this.healthyMs)
+            this.attempt = 0;
+    }
+}

package/dist/relay.js

@@ -10,6 +10,7 @@ import { join, dirname, resolve, sep } from 'path';
 import { execSync, execFileSync } from 'child_process';
 import WebSocket from 'ws';
 import { logger } from './logger.js';
+import { ReconnectBackoff } from './reconnect-backoff.js';
 import { TerminalBlockParser } from './terminal/block-parser.js';
 import { writeIntegration, cleanupIntegration } from './terminal/shell-integration.js';
 import { transformPath } from './daemon-path-transform.js';
@@ -73,11 +74,16 @@ export class Relay {
     // ── WebSocket ─────────────────────────────────────────────────────────
     ws = null;
     wsConnecting = false;
-    reconnectAttempts = 0;
+    /** ⚠ PPO-532: resets only after a connection stays open 60 s, not when one opens — see
+     *  reconnect-backoff.ts. `reconnectAttempts` (read by the daemon's status.json) reads it. */
+    backoff = new ReconnectBackoff();
+    get reconnectAttempts() {
+        return this.backoff.attempts;
+    }
     reconnectTimer = null;
     /** Watchdog timer + the moment we first noticed we were disconnected. If the
      *  relay stays down past the threshold, the watchdog forces a HARD reconnect
-     *  (terminate any zombie socket + reset backoff + redial). This is the
+     *  (terminate any zombie socket + redial now; PPO-532 keeps the backoff). This is the
      *  self-heal a HEADLESS / orphaned daemon needs — it has no Mac-app tray
      *  parent to restart it, so a wedged WS (e.g. a half-open socket after system
      *  sleep) would otherwise leave it "stuck reconnecting" forever. */
@@ -388,6 +394,8 @@ export class Relay {
             return;
         // Re-enable auto-reconnect in case a previous stop() set it.
         this.stopped = false;
+        // An explicit start (daemon boot, sign-in) is not a retry: no inherited backoff.
+        this.backoff.reset();
         // Validate endpoint against whitelist
         try {
             const endpointHost = new URL(this.config.endpoint.replace('wss://', 'https://').replace('ws://', 'http://')).hostname;
@@ -534,6 +542,8 @@ export class Relay {
             params.set('deviceId', String(this.deviceId).slice(0, 64));
         const url = `${this.wsBase()}/my/workspace/ws?${params.toString()}`;
         const ws = new WebSocket(url);
+        // This socket's healthy clock (PPO-532); null until it opens.
+        let openedAt = null;
         // Wait for open or first error/close before resolving
         await new Promise((resolve) => {
             const done = () => {
@@ -543,7 +553,10 @@ export class Relay {
                 this.ws = ws;
                 this.wsConnecting = false;
                 this.connected = true;
-                this.reconnectAttempts = 0;
+                // ⚠ PPO-532: opening is not recovering. A workspace that runs out of memory while
+                // hydrating accepts the socket and drops it seconds later; resetting here made every
+                // retry the first (~1 s), a reconnect loop. The backoff resets after 60 s open.
+                openedAt = this.backoff.opened();
                 console.log(`[relay] WebSocket connected to ${this.config.endpoint}`);
                 // Notify subscribers that the WebSocket is open so they
                 // can pull fresh state. Wrapped because the callback
@@ -770,6 +783,7 @@ export class Relay {
                 pending.reject(new Error('WebSocket closed'));
             }
             this.pendingRequests.clear();
+            this.backoff.closed(openedAt);
             // Always schedule reconnect while we're still configured and not
             // stopped. Previous guard `if (wasConnected)` broke the chain: if
             // a reconnect attempt failed to open, the new ws's close handler
@@ -1100,28 +1114,21 @@ export class Relay {
     }
     // ── Reconnection ──────────────────────────────────────────────────────
     /**
-     * Reconnect with exponential backoff + jitter.
+     * Reconnect with exponential backoff + FULL jitter (PPO-532, reconnect-backoff.ts).
      *
-     * Backoff: 1s → 2s → 4s → 8s → 16s → 32s → 60s (capped). Jitter adds
-     * 0-25% of the base delay so a fleet of clients reconnecting after a
-     * server outage doesn't synchronize into a thundering herd. The cap
-     * keeps idle daemons polling at most once a minute.
+     * Delay: uniform over [0, min(30s, 1s·2^attempt)). The ±25% jitter this replaced kept the
+     * daemon socket and its agent sockets — which drop together — reconnecting together. The
+     * attempt count resets only once a connection has stayed open 60 s, so a socket that opens
+     * and dies (an out-of-memory workspace) keeps backing off instead of retrying every second.
      *
-     * Single-flight: a reconnect already scheduled is a no-op. The timer
-     * is cleared on successful connect (reconnectAttempts → 0) and on
-     * stop().
+     * Single-flight: a reconnect already scheduled is a no-op. The timer is cleared by stop()
+     * and forceReconnect().
      */
     scheduleReconnect() {
         if (this.reconnectTimer)
             return;
-        const baseDelay = Math.min(1000 * Math.pow(2, this.reconnectAttempts), 60_000);
-        // Add 0-25% random jitter — `delay * (1 + 0..0.25)` keeps the
-        // floor at the exponential value so we never reconnect FASTER
-        // than the backoff intends, only slower.
-        const jitter = Math.random() * 0.25 * baseDelay;
-        const delay = Math.round(baseDelay + jitter);
-        this.reconnectAttempts++;
-        console.log(`[relay] Reconnecting in ${(delay / 1000).toFixed(1)}s (attempt ${this.reconnectAttempts})`);
+        const delay = this.backoff.next();
+        console.log(`[relay] Reconnecting in ${(delay / 1000).toFixed(1)}s (attempt ${this.backoff.attempts})`);
         this.reconnectTimer = setTimeout(() => {
             this.reconnectTimer = null;
             if (this.useWebSocket) {
@@ -1151,6 +1158,10 @@ export class Relay {
                 this.disconnectedSince = Date.now();
                 return;
             }
+            // ⚠ PPO-532: a scheduled retry means the backoff chain is alive (≤30 s away). Forcing
+            // past it turned a workspace that keeps dropping new sockets back into rapid redials.
+            if (this.reconnectTimer)
+                return;
             if (Date.now() - this.disconnectedSince > maxDownMs) {
                 console.warn(`[relay] Watchdog: relay down ${Math.round((Date.now() - this.disconnectedSince) / 1000)}s — forcing hard reconnect`);
                 this.disconnectedSince = Date.now();
@@ -1159,7 +1170,8 @@ export class Relay {
         }, 30_000);
     }
     /** Hard reconnect: drop any (possibly zombie) socket, clear pending reconnect
-     *  state, reset the backoff so the next dial is immediate, then redial. */
+     *  state, then redial at once. The attempt count is kept (PPO-532): if this dial
+     *  fails too, the next retry continues the backoff instead of restarting at 1 s. */
     forceReconnect() {
         try {
             this.ws?.terminate();
@@ -1172,7 +1184,6 @@ export class Relay {
             clearTimeout(this.reconnectTimer);
             this.reconnectTimer = null;
         }
-        this.reconnectAttempts = 0;
         if (this.useWebSocket)
             this.connectWs();
         else
@@ -1182,7 +1193,7 @@ export class Relay {
         const ok = await this.sendHeartbeatHttp();
         if (ok) {
             this.connected = true;
-            this.reconnectAttempts = 0;
+            this.backoff.reset(); // legacy HTTP has no socket to watch: a good heartbeat is recovery
             console.log(`[relay] Reconnected (tier: ${this.tier})`);
             if (this.heartbeatInterval)
                 clearInterval(this.heartbeatInterval);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clearlysh/beehaven",
-  "version": "0.8.35",
+  "version": "0.8.36",
   "description": "Beehaven CLI — command your Clearly workspace, agents, and canvas from the terminal",
   "private": false,
   "type": "module",

package/scripts/sync-skills.mjs

@@ -46,6 +46,7 @@ const SOURCES = {
   'clearly-docs':      'apps/mcp-server/plugin/skills/clearly-docs/SKILL.md',
   'clearly-init':      'apps/mcp-server/plugin/skills/clearly-init/SKILL.md',
   'clearly-workflows': 'apps/mcp-server/plugin/skills/clearly-workflows/SKILL.md',
+  'clearly-artifacts': 'apps/mcp-server/plugin/skills/clearly-artifacts/SKILL.md',
 };
 
 let missing = 0;

package/skills/clearly-artifacts/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: clearly-artifacts
+description: >-
+  Needs a terminal with the beehaven CLI (Claude Code, Codex, Gemini CLI); in a chat with only the Clearly connector, say so: the connector cannot make a running page.
+  Put a self-contained interactive HTML page into a Clearly workspace, the way a
+  Claude artifact works: an explainer, an animation, a small tool, a calculator, a
+  chart that runs. Covers which of the three HTML homes runs scripts (a SITE does,
+  a canvas ARTIFACT card does but cannot be clicked, a NOTE never does), the exact
+  CLI calls, the sandbox limits, updating, filing in a project, how a person opens
+  it, and QA. Use when asked to publish, host or add an HTML page, demo or animation
+  to the workspace. Triggers: "make an artifact", "publish this HTML", "add this page /
+  animation / explainer to the workspace", "host this demo", "interactive page",
+  "put this HTML on the canvas", "why doesn't my page's script run".
+---
+
+# Clearly artifacts — a running HTML page in the workspace
+
+Sign in first (`clearly-agent`). `beehaven env` must name the environment you mean; staging and
+production hold different workspaces.
+
+## 1. Pick the home — only two of the three run code
+
+| Home | Make it with | Scripts and CSS animation | Clickable | Search, history | Opens at |
+|---|---|---|---|---|---|
+| **Site** | `compose-upload-init` → `file-teleport-inline` → `compose-upload-finalize` | run | yes | not in `document-search`; no version history; a re-upload overwrites | Recents or project card → `/compositions/detail?id=<id>` |
+| **Canvas artifact** | `canvas-act` `canvas.add-artifact` | run | **no**: the card never takes pointer events, so it pans like a picture | no; it is part of the canvas and is deleted with it | the canvas, `/c/<compositionId>` |
+| **Note** | `document-create {html}`; `page-write` (in-app chat only) | **never**: it opens in the document editor, which drops `<script>`, `<style>` and inline `<svg>` | n/a | yes, both | `/documents/<id>` |
+
+- An interactive page someone opens, clicks through or comes back to is a **site**. This is the
+  Claude-artifact equivalent and the default.
+- A page that only needs to be **seen** beside other cards (a looping animation, a live chart in a
+  review board) is a **canvas artifact**. Buttons inside it cannot be pressed.
+- Prose the team will read, search and edit is a **note**. Never put a script in a note: it
+  is stored, and then nothing ever runs it. Editing the note in the app rewrites its body.
+
+No home gives a public link that runs. Every share link (`/r/…`) is served with
+`script-src 'none'`, and a shared composition renders as a static picture. Say so when someone asks to
+publish an interactive page outside the workspace.
+
+## 2. Write it self-contained
+
+Both running homes inject the page with `srcdoc` into `<iframe sandbox="allow-scripts">`, with no
+`allow-same-origin`. The page gets an opaque origin (`window.origin === "null"`).
+
+- **One file.** `<!doctype html>`, `<meta name="viewport" content="width=device-width, initial-scale=1">`,
+  CSS in `<style>`, JS in `<script>`, art as inline SVG, images and fonts as `data:` URIs,
+  system font stacks. Make no network requests and load no CDN scripts.
+- **The sandbox blocks:** `localStorage`, `sessionStorage`, cookies and IndexedDB (accessing them
+  throws), `alert`/`confirm`/`prompt`, form submission, popups, `window.open` and top-level
+  navigation. Keep state in memory, and wrap any storage access in `try`.
+- **A site's other files are rarely reached.** The preview rewrites only `src="…"`/`href="…"`
+  in the entry HTML that name a build file exactly (up to 60 files). It does not rewrite `url()`
+  inside CSS, `import`, or `fetch` of a sibling file. Inline them.
+- **Size:** a canvas artifact is at most 512 KB. A site file is at most 6 MB inline. Over the CLI
+  WebSocket, keep a single `beehaven call` under about 900 KB, or use `beehaven compose push`,
+  which switches to a presigned upload.
+- **Motion:** honour `@media (prefers-reduced-motion: reduce)`. A canvas card lays the page out
+  at `designWidth` (default 1280) and grows to the document's full height. A `100vh` layout
+  makes it grow again on every fit, so size sections in px or by content.
+
+## 3. Make it (CLI)
+
+Build JSON payloads with a script and pass them as `@file`. Do not hand-escape HTML into a shell
+argument.
+
+**Site, from one file** (one `file-teleport-inline` per file; `entryPoint` and each path are
+relative to `build/`):
+
+```sh
+beehaven call compose-upload-init '{"name":"MCP tokens explained","sourceType":"static","entryPoint":"index.html","projectId":"<projectId>"}'
+# → { "id": "cmp_…", "created": true }
+node -e 'const fs=require("fs"),b=fs.readFileSync("page.html");fs.writeFileSync("up.json",JSON.stringify({key:"compositions/<id>/build/index.html",composition:true,name:"index.html",mimeType:"text/html",size:b.length,data:b.toString("base64")}))'
+beehaven call file-teleport-inline @up.json
+beehaven call compose-upload-finalize '{"compositionId":"<id>","totalBytes":<bytes>,"entryPoint":"index.html"}'
+beehaven call composition-fs '{"compositionId":"<id>","action":"list"}'   # one row per file, sizes match
+```
+
+Both parts of the upload are load-bearing. A `key` outside `compositions/<id>/build/`, or a
+missing `composition:true`, still answers ok, and the site then renders nothing.
+
+**Site, from a folder** that holds only the page and its assets:
+`cd <folder> && beehaven compose create --name "<title>" && beehaven compose push`. Every file in
+the folder is uploaded. A Vite, Next, Astro or SvelteKit `package.json` there runs its build first.
+To push to an existing site, run `beehaven compose push --composition <id>` from the folder; there
+is no `--dir` flag. `compose create` cannot file the site, so file it afterwards (§4). Ignore the
+URL that `push` prints, because it does not open the site.
+
+**Canvas artifact** (create or reuse the canvas with `composition-create {title, projectId}`):
+
+```sh
+# payload: {"compositionId":"<canvasId>","action":"canvas.add-artifact",
+#           "args":{"html":"<!doctype html>…","title":"…","name":"explainer","x":0,"y":0,"w":1000,"designWidth":1000}}
+beehaven call canvas-act @artifact.json
+```
+
+`w` is the card's width on the board; `designWidth` is the viewport the page lays out at. Use 390
+for a phone design. `canvas.place {kind:"site", id}` puts an existing site on a canvas as an
+artifact card. It copies the entry HTML at that moment: later re-uploads do not reach the card,
+and the site's other files do not load.
+
+**Connector only (MCP):** no tool makes a site or an artifact. `clearly_file_upload` cannot choose
+a site path, and `clearly_create` stores a document body as markdown. `clearly_canvas_place
+{target, kind:"site", id}` can place a site that already exists. Otherwise, tell the person the
+running page needs the CLI.
+
+## 4. Update, file, link
+
+- **Update a site:** upload to the same `key`, then `compose-upload-finalize` again. Only someone
+  who may manage the site (its creator) can overwrite it. A file you stop shipping stays in the
+  build. Agents are refused `composition-fs … "action":"delete"`, so ask the person to remove it,
+  or stop referencing it. There is no history, so keep the source in the repository or a note.
+- **Update a canvas artifact:** there is no edit verb. Add the new version at the old card's
+  `x`/`y`/`w`, then remove the old card with `canvas.delete {ids:[…]}`.
+- **File:** `projectId` on `compose-upload-init` (to file later, call it again with
+  `{"compositionId","projectId"}`). For a canvas, `composition-create {projectId}`. For a note,
+  `document-create {projectId}` or `document-update {id, projectId}`. Unfiled agent work is
+  private to its author.
+- **Link it to the ticket:** `beehaven call work-link '{"ticketId":"…","kind":"design","refKind":"composition","refId":"<id>"}'`.
+
+## 5. Hand it over
+
+Give the person the place to click, not just an id.
+
+- A site: "Recents (or the project) → the card", which opens `/compositions/detail?id=<id>`.
+  Do not hand over `/c/<siteId>`. That is what `beehaven open`, ticket links and workspace-ref
+  chips build for a site, and it opens an empty canvas instead of the page.
+- A canvas artifact: `/c/<canvasId>`. Double-clicking the card opens its stored file in a new tab,
+  which shows source text or an access error, never the running page.
+
+## 6. QA — open it, read the console, check mobile
+
+1. **Render it in the real frame model** before uploading. Use Playwright: an
+   `<iframe sandbox="allow-scripts" srcdoc>` at 1280 and 390 wide. Confirm there are no console
+   errors and no requests from the frame, that `scrollWidth === clientWidth`, that the animation
+   advances by itself, and that its controls respond.
+2. **Read the stored copy back:** check that `composition-fs list` shows the size you sent.
+3. **See the server render it.** For a canvas artifact, run
+   `canvas-act {"compositionId":"<canvasId>","action":"canvas.review","args":{"ids":["<artifactId>"]}}`.
+   It returns a filmstrip of four frames across about 5.4 s; inspect the PNG. For a site, place it on a scratch canvas
+   (`canvas.place {kind:"site", id}`), review that card the same way, and then archive the scratch
+   canvas (`composition-set-archived {id, archived:true}`).
+4. Report what you checked and what you could not check. Opening the signed-in page itself needs a
+   person's session.

package/skills/index.json

@@ -118,5 +118,12 @@
       "SKILL.md"
     ],
     "sha": "b9622f21173bab0d"
+  },
+  {
+    "name": "clearly-artifacts",
+    "files": [
+      "SKILL.md"
+    ],
+    "sha": "14434d4904da91a3"
   }
 ]