beehaven 0.8.34 → 0.8.36

package/dist/commands/agents-md.js

@@ -8,17 +8,81 @@
  * is its own command the person (or their agent, asked first) runs, not a side effect of install.
  *
  * ⚠ THE MARKERS ARE THE UPDATE MECHANISM, as on every other surface (lib/connections/agentsMd.ts):
- * re-running replaces only what lies between our markers and leaves the rest byte for byte. The
- * CLI and MCP blocks have their own markers, so a repo used both ways keeps both.
+ * re-running replaces only what lies between our markers and leaves the rest byte for byte.
+ *
+ * ⚠ ONE TRACKED BLOCK FOR BOTH ROUTES (AWO-401). The block names the MCP tool and the CLI command
+ * for each step, so `--mcp` is kept only so older instructions still work; it writes the same block.
+ * Writing it removes the per-route blocks earlier versions wrote (`LEGACY_BLOCK_MARKERS`), so a repo
+ * that had both converges on one.
  *
  * ⚠ AGENTS.md IS THE FILE; CLAUDE.md POINTS AT IT with one `@AGENTS.md` line — one copy to keep
  * current. An existing CLAUDE.md gains the line only if it lacks it; nothing else in it is touched.
+ * The project's `.claude/settings.json` gains `CLAUDE_BASH_RULE` the same way (AWO-401).
  */
-import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
 import { join, resolve } from 'path';
 import { execFileSync } from 'child_process';
 import { color } from '../spinner.js';
-import { CLI_BLOCK_START, CLI_BLOCK_END, MCP_BLOCK_START, MCP_BLOCK_END, CLAUDE_MD_IMPORT, agentsMdCliBlock, agentsMdMcpBlock, } 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
+ * off. Written to the PROJECT's `.claude/settings.json` (committed with AGENTS.md, so it is the
+ * team's rule, not a change to anyone's user-wide settings). Claude Code matches each part of a
+ * chained command separately, so the rule never approves `beehaven … && something-else`.
+ */
+export const CLAUDE_BASH_RULE = 'Bash(beehaven:*)';
+/**
+ * Settings text with the rule added (or removed). `null` text means no file. A file that is not a
+ * JSON object is left alone (`skipped`) — never rewritten from a guess.
+ */
+export function editClaudeSettings(text, remove = false) {
+    if (text === null) {
+        if (remove)
+            return { next: null, change: 'absent' };
+        return { next: JSON.stringify({ permissions: { allow: [CLAUDE_BASH_RULE] } }, null, 2) + '\n', change: 'created' };
+    }
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        return { next: text, change: 'skipped' };
+    }
+    if (!data || typeof data !== 'object' || Array.isArray(data))
+        return { next: text, change: 'skipped' };
+    const perms = data.permissions && typeof data.permissions === 'object' && !Array.isArray(data.permissions) ? data.permissions : null;
+    const allow = perms && Array.isArray(perms.allow) ? perms.allow : [];
+    if (remove) {
+        if (!allow.includes(CLAUDE_BASH_RULE))
+            return { next: text, change: 'absent' };
+        perms.allow = allow.filter((r) => r !== CLAUDE_BASH_RULE);
+        if (!perms.allow.length)
+            delete perms.allow;
+        if (!Object.keys(perms).length)
+            delete data.permissions;
+        return { next: Object.keys(data).length ? JSON.stringify(data, null, 2) + '\n' : null, change: 'removed' };
+    }
+    if (allow.includes(CLAUDE_BASH_RULE))
+        return { next: text, change: 'current' };
+    if (perms && perms.allow !== undefined && !Array.isArray(perms.allow))
+        return { next: text, change: 'skipped' };
+    data.permissions = { ...(perms ?? {}), allow: [...allow, CLAUDE_BASH_RULE] };
+    return { next: JSON.stringify(data, null, 2) + '\n', change: 'updated' };
+}
+/** Apply `editClaudeSettings` to `<root>/.claude/settings.json`. */
+function writeClaudeSettings(root, remove) {
+    const path = join(root, '.claude', 'settings.json');
+    const before = existsSync(path) ? readFileSync(path, 'utf8') : null;
+    const { next, change } = editClaudeSettings(before, remove);
+    if (next === null && before !== null)
+        rmSync(path);
+    else if (next !== null && next !== before) {
+        mkdirSync(join(root, '.claude'), { recursive: true });
+        writeFileSync(path, next);
+    }
+    return { path, change };
+}
 /** Our block replaced between its markers, or appended after one blank line. Keeps CRLF files CRLF. */
 export function spliceBlock(text, block, start, end) {
     const eol = text.includes('\r\n') ? '\r\n' : '\n';
@@ -57,22 +121,47 @@ export function projectRoot(dir) {
     }
 }
 /** Write (or remove) the block in `<root>/AGENTS.md` and make CLAUDE.md import it. */
+/** The text with every per-route block from before AWO-401 taken out. */
+export function removeLegacyBlocks(text) {
+    return LEGACY_BLOCK_MARKERS.reduce((t, [start, end]) => removeBlock(t, start, end), text);
+}
+/**
+ * The block written into `text`: in place of our current block, else in place of the first legacy
+ * block (so a migrated repo keeps its layout), else appended. Any other legacy block is removed.
+ */
+export function upsertAgentsMdBlock(text, block) {
+    if (text.includes(AGENTS_MD_START))
+        return spliceBlock(removeLegacyBlocks(text), block, AGENTS_MD_START, AGENTS_MD_END);
+    const legacy = LEGACY_BLOCK_MARKERS.find(([start, end]) => {
+        const i = text.indexOf(start);
+        return i >= 0 && text.indexOf(end, i) >= 0;
+    });
+    if (legacy)
+        return removeLegacyBlocks(spliceBlock(text, block, legacy[0], legacy[1]));
+    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 [start, end] = opts.mcp ? [MCP_BLOCK_START, MCP_BLOCK_END] : [CLI_BLOCK_START, CLI_BLOCK_END];
     const agentsPath = join(root, 'AGENTS.md');
     const claudePath = join(root, 'CLAUDE.md');
     const files = [];
     const had = existsSync(agentsPath);
     const before = had ? readFileSync(agentsPath, 'utf8') : '';
     if (opts.remove) {
-        const next = removeBlock(before, start, end);
+        const next = removeLegacyBlocks(removeBlock(before, AGENTS_MD_START, AGENTS_MD_END));
         if (next !== before)
             writeFileSync(agentsPath, next);
         files.push({ path: agentsPath, change: next !== before ? 'removed' : 'absent' });
+        files.push(writeClaudeSettings(root, true));
         return { root, files };
     }
-    const next = spliceBlock(before, opts.mcp ? agentsMdMcpBlock() : agentsMdCliBlock(), start, end);
+    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' });
@@ -89,16 +178,18 @@ export function writeProjectAgentsMd(opts) {
     else {
         files.push({ path: claudePath, change: 'current' });
     }
+    if (!opts.notTracked)
+        files.push(writeClaudeSettings(root, false));
     return { root, files };
 }
 export function cmdAgentsMd(dir, opts) {
     if (opts.print) {
-        process.stdout.write((opts.mcp ? agentsMdMcpBlock() : agentsMdCliBlock()) + '\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}`);
@@ -106,10 +197,11 @@ export function cmdAgentsMd(dir, opts) {
     }
     console.log('');
     for (const f of r.files) {
-        const mark = f.change === 'current' || f.change === 'absent' ? color.dim('·') : color.green('✓');
-        console.log(`  ${mark} ${f.path}  ${color.dim(f.change)}`);
+        const mark = f.change === 'current' || f.change === 'absent' ? color.dim('·') : f.change === 'skipped' ? color.yellow('!') : color.green('✓');
+        const note = f.change === 'skipped' ? ` — not valid JSON, so left unchanged; add "${CLAUDE_BASH_RULE}" to permissions.allow yourself` : '';
+        console.log(`  ${mark} ${f.path}  ${color.dim(f.change)}${note}`);
     }
-    const changed = r.files.some((f) => f.change !== 'current' && f.change !== 'absent');
+    const changed = r.files.some((f) => f.change !== 'current' && f.change !== 'absent' && f.change !== 'skipped');
     if (changed && !opts.remove) {
         console.log(color.dim(`\n  Commit ${r.files.map((f) => f.path.slice(r.root.length + 1)).join(' and ')} so every agent that opens this project knows the workspace.`));
     }

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,23 +424,27 @@ const PAGES = {
         related: ['login', 'guide'],
     },
     'agents-md': {
-        synopsis: 'beehaven agents-md [dir] [--mcp] [--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 — knows the workspace and how
-    to reach it. Writes at the git root (or the directory given), and makes CLAUDE.md import it with
-    one \`@AGENTS.md\` line. Needs no login.
-
-    The block sits between Clearly's markers: run it again to update the block, and everything
-    else in the file stays as it was. \`beehaven login\` already teaches the agents on THIS machine
-    (their global instruction files); this is the shared, committed copy for everyone else.`,
+    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
+    the CLI and over MCP. Writes at the git root (or the directory given), and makes CLAUDE.md
+    import it with one \`@AGENTS.md\` line, and lets Claude Code run \`beehaven\` without a prompt per
+    call (\`Bash(beehaven:*)\` in the project's .claude/settings.json). Needs no login.
+
+    The block sits between Clearly's markers: run it again to update it, and everything else in
+    the file stays as it was. Older per-route Clearly blocks are replaced. \`beehaven login\`
+    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: '--mcp', desc: 'Write the block for agents connected over MCP instead of the CLI' },
+            { 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' },
         ],
         examples: [
-            { cmd: 'beehaven agents-md', note: 'AGENTS.md + CLAUDE.md at the repository root' },
-            { cmd: 'beehaven agents-md --mcp', note: 'for a team that connects over MCP' },
+            { cmd: 'beehaven agents-md', note: 'AGENTS.md, CLAUDE.md and .claude/settings.json at the repository root' },
+            { cmd: 'beehaven agents-md --print', note: 'see the block without writing it' },
         ],
         related: ['skills', 'login'],
     },
@@ -1687,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.
 
@@ -1696,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": "beehaven",
-  "version": "0.8.34",
+  "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;