@clearlysh/beehaven 0.8.34 → 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

@@ -1,64 +1,100 @@
 /**
  * agents-md-text — the Clearly block for a PROJECT's AGENTS.md, as `beehaven agents-md` writes it
- * (CAN2-66).
+ * (CAN2-66, AWO-401).
  *
  * ⚠⚠ A COPY, PINNED. The source of truth is the monorepo's `lib/connections/agentsMd.ts`, which the
- * Integrations page, each agent's details and the MCP `clearly-agents-md` prompt render. This
- * package cannot import it (it ships on its own), so the text is repeated here and the monorepo's
- * `lib/__tests__/agentsMdCliParity.test.mjs` compares the two OUTPUTS, name argument included.
- * Change both or the test fails — a stale copy does not render wrong, it instructs wrong.
+ * Integrations page, each agent's details, the /cli and /mcp guides and the MCP `clearly-agents-md`
+ * prompt render. This package cannot import it (it ships on its own), so the text is repeated here
+ * and the monorepo's `lib/__tests__/agentsMdCliParity.test.mjs` compares the two OUTPUTS, name
+ * argument included. Change both or the test fails — a stale copy does not render wrong, it
+ * instructs wrong.
+ *
+ * ⚠ ONE TRACKED BLOCK FOR MCP AND THE CLI (founder 2026-10-28): every task is tracked in Clearly,
+ * and each step names the MCP tool and the CLI command. The per-route blocks before it are removed
+ * when this one is written (`LEGACY_BLOCK_MARKERS`).
  *
  * ⚠ NO IMPORTS, so that test can load this file directly.
  */
-export const CLI_BLOCK_START = '<!-- clearly:cli:start -->';
-export const CLI_BLOCK_END = '<!-- clearly:cli:end -->';
-export const MCP_BLOCK_START = '<!-- clearly:mcp:start -->';
-export const MCP_BLOCK_END = '<!-- clearly:mcp:end -->';
+export const AGENTS_MD_START = '<!-- clearly:start -->';
+export const AGENTS_MD_END = '<!-- clearly:end -->';
+/** The per-route markers used before AWO-401. Writers remove these blocks; nothing writes them. */
+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. */
 export const CLAUDE_MD_IMPORT = '@AGENTS.md';
-/** The block for agents that use the `beehaven` CLI. */
-export function agentsMdCliBlock(agentName) {
+/** Where the block goes, said once for every surface. */
+export const AGENTS_MD_HOW = 'Every agent that opens the repository reads AGENTS.md, so the block makes each session track its work in Clearly. Claude Code reads CLAUDE.md — give it one line.';
+/** The MCP tools the block names. Each must be on the server's `tools/list` (a Worker test pins it). */
+export const MCP_BLOCK_TOOLS = ['clearly_catalog', 'clearly_read', 'clearly_grep', 'clearly_create', 'clearly_edit', 'clearly_comment'];
+/**
+ * The block. `agentName` personalises the CLI sign-in line for one agent (its details view);
+ * without it the agent is told to use its own name.
+ */
+export function agentsMdBlock(agentName) {
     const name = (agentName ?? '').trim();
     const login = name
-        ? `\`beehaven agent login ${name} --label "<what you are doing>"\` — you are ${name} in this workspace.`
-        : '`beehaven agent login <name> --label "<what you are doing>"`, using your own name (claude, codex, gemini).';
+        ? `\`beehaven agent login ${name} --label "<the task>"\` — you are ${name} in this workspace —`
+        : '`beehaven agent login <your-name> --label "<the task>"` (claude, codex, gemini…)';
     return [
-        CLI_BLOCK_START,
-        '<!-- managed-by: clearly. Run `beehaven agents-md` to update; edit outside this block. -->',
+        AGENTS_MD_START,
+        '<!-- managed-by: clearly. Run `beehaven agents-md` or the `clearly-agents-md` MCP prompt to update; edit outside this block. -->',
+        '',
+        '## Clearly workspace: track every task',
         '',
-        '## Clearly workspace',
+        "This project's plans, tickets, documents and designs live in Clearly. Track every task there,",
+        'even when the person does not ask. Use whichever route this session has: the `clearly_*` MCP tools,',
+        "or the `beehaven` CLI (`beehaven actions` lists actions; `beehaven call <action> '<json>'` runs one).",
         '',
-        'This project keeps its documents, plans, boards and tickets in Clearly. Use the `beehaven` CLI',
-        'for anything the team should see, not files in this repo.',
+        '### Start of every session',
         '',
-        `- Sign in once per session: ${login}`,
+        `- CLI: sign in first with ${login} and read the brief it prints.`,
         '  If it says the daemon is not running: `beehaven start --headless`.',
-        '- Read the `clearly-agent` skill before anything else, and `clearly-canvas` before design work',
-        '  (`beehaven skills install` puts them in place).',
-        '- `beehaven actions` lists what you can call; `beehaven call <action> \'<json>\'` calls it.',
-        '- Search before you create, file work in the project it belongs to, and end the session with',
-        '  `beehaven agent handoff "what you did · what is next"` so the next one starts there.',
-        CLI_BLOCK_END,
-    ].join('\n');
-}
-/** The block for agents connected over MCP (the `clearly` server). */
-export function agentsMdMcpBlock() {
-    return [
-        MCP_BLOCK_START,
-        '<!-- managed-by: clearly-mcp. Re-run the `clearly-agents-md` prompt to update; edit outside this block. -->',
+        '  MCP: you are already signed in as the agent chosen when Clearly was connected.',
+        "- Read this project's open tickets and its latest handoff before starting (`clearly_grep` /",
+        '  `clearly_read`, or the brief).',
+        '',
+        '### Every task has a ticket',
+        '',
+        '1. Search first (`clearly_grep`, `clearly_catalog`, or `beehaven call ticket-list`). Reuse the project,',
+        '   board and ticket that already own the work; create a board only if the project has none.',
+        '2. Create the ticket before changing code or files (`clearly_create` with `type: "ticket"` and',
+        '   `fields.boardId`, or `beehaven call ticket-create`). Say in its body what done means.',
+        '3. Move it to in-progress when work begins (`clearly_edit`, or `beehaven call ticket-update`).',
+        '4. File what you make (documents, designs, notes) into the project and link it from the ticket.',
+        '   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.',
         '',
-        '## Clearly workspace (connected over MCP as `clearly`)',
+        '### End of every session',
         '',
-        'This project keeps its documents, plans, boards and tickets in Clearly. Use the `clearly_*`',
-        'tools, not files in this repo, for anything the team should see.',
+        '- Leave a handoff: what you did and what is next. CLI: `beehaven agent handoff "<done · next>"`.',
+        '  MCP: a comment on the work ticket.',
         '',
-        '- Start with `clearly_catalog` to see what exists; search with `clearly_grep` / `clearly_glob`.',
-        '- Read with `clearly_read`, make new work with `clearly_create`, change it with `clearly_edit`,',
-        '  and discuss it with `clearly_comment`. They take a `target`: a path (`~/Q1/Plan.md`), a key',
-        '  (`CLR-42`), an id or an exact title. The extension names the type (`.md` document, `.csv`',
-        '  sheet, `.board.json` board); a trailing slash means a project.',
-        '- Search before you write, and write decisions back so the next session inherits them.',
-        '- If a job is not covered by a listed tool, say so rather than guessing an action name.',
-        MCP_BLOCK_END,
+        '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. 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 = '0fc3f190acdb';
+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-27T20:29Z';
+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:
@@ -1340,7 +1341,7 @@ async function run() {
             state: { type: 'string' },
             goal: { type: 'string' },
             remove: { type: 'boolean', default: false },
-            // `agents-md`: the MCP block instead of the CLI one; print it instead of writing it (CAN2-66).
+            // `agents-md`: `--mcp` is accepted for older instructions (one block since AWO-401); `--print` prints it.
             mcp: { type: 'boolean', default: false },
             print: { type: 'boolean', default: false },
             /**
@@ -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');
 }