@clearlysh/beehaven 0.8.35 → 0.8.37

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' },
@@ -704,7 +715,7 @@ const PAGES = {
         related: ['call', 'pwd', 'workspace'],
     },
     call: {
-        synopsis: 'beehaven call <action> [json-input] [--building <type>:<id>] [--json]',
+        synopsis: 'beehaven call <action> [json-input | @file | -] [--building <type>:<id>] [--json | --brief]',
         description: `Invoke an RPC on the current target. Input is a JSON string.
     Schema comes from the action's manifest — use \`beehaven actions\` first
     to see what's available, or \`beehaven explain <action>\` for the exact
@@ -714,10 +725,12 @@ const PAGES = {
         flags: [
             { name: '--building <type>:<id>', desc: 'Explicit target (e.g. shopifyStore:clearly-demo)' },
             { name: '--json', desc: 'Suppress breadcrumb + hint blocks; raw stdout only' },
+            { name: '--brief', desc: 'A short receipt instead of the JSON: steps, layer changes, failures, lint to fix, review verdicts. Same exit code.' },
             { name: '--timeout <ms>', desc: 'Override the 30s default' },
         ],
         examples: [
             { cmd: 'beehaven call note-create \'{"title":"Hello"}\'' },
+            { cmd: 'beehaven call canvas-act @build.json --brief', note: 'a canvas batch, read as a one-line receipt' },
             { cmd: "beehaven call project-list '{}' --building home" },
             {
                 cmd: 'beehaven call admin-agent-chat \'{"conversationId":"c1","message":"top sellers?","scope":"read"}\'',
@@ -1690,7 +1703,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 +1712,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/commands/workspace.js

@@ -1132,7 +1132,36 @@ export async function cmdCall(action, rawInput, values) {
             printCallErrorHints(raw.message, action, values);
             process.exit(1);
         }
-        if (result && typeof result === 'object') {
+        /**
+         * MCP2-25 — `call … --out <file>` writes the whole JSON result to a file. The canvas skill tells
+         * agents to save a large response once and read a summary, and the only way was `> file`, which a
+         * headless agent needs permission for: a recorded Claude Code take lost a call to "`--out` is not
+         * supported by `beehaven call`". The receipt (or a one-line note) still prints; the exit code is
+         * the result's, exactly as without the flag.
+         */
+        const outPath = values.out ?? values.output;
+        if (typeof outPath === 'string' && outPath) {
+            const { mkdirSync, writeFileSync } = await import('node:fs');
+            const { dirname, resolve } = await import('node:path');
+            const file = resolve(outPath);
+            mkdirSync(dirname(file), { recursive: true });
+            const text = result && typeof result === 'object' ? JSON.stringify(result, null, 2) : String(result ?? '');
+            writeFileSync(file, text + '\n');
+            if (!values.brief)
+                console.log(`wrote ${text.length.toLocaleString()} bytes to ${outPath}`);
+        }
+        let briefFailed = false;
+        if (values.brief && !values.json) {
+            // ⚠ THE SAME RESULT, READ FOR A PERSON — see call-brief.ts for what is kept and why.
+            const { briefReceipt } = await import('../call-brief.js');
+            const receipt = briefReceipt(action, result);
+            console.log(receipt.lines.join('\n'));
+            briefFailed = !receipt.ok;
+        }
+        else if (typeof outPath === 'string' && outPath) {
+            // Written above; the console keeps only the note, so a large result stays out of the context.
+        }
+        else if (result && typeof result === 'object') {
             console.log(JSON.stringify(result, null, 2));
         }
         else {
@@ -1234,7 +1263,7 @@ export async function cmdCall(action, rawInput, values) {
             }
             printKnownActionAdvice(action, input, result);
         }
-        if (isFailureResult(result))
+        if (briefFailed || isFailureResult(result))
             process.exit(1);
     }
     catch (err) {

package/dist/daemon-client.js

@@ -18,6 +18,7 @@ import net from 'net';
 import { resolveClientAuthToken } from './ipc-auth.js';
 import { activeAgentWrap } from './agent-attribution.js';
 import { ipcSocketPath, socketMayExist } from './ipc-path.js';
+import { utf8Stream } from './utf8-stream.js';
 const TIMEOUT_MS = 60_000;
 const AUTH_TIMEOUT_MS = 3_000;
 /** One attempt. Resolves, never rejects. */
@@ -112,8 +113,10 @@ function handshake(socket) {
             socket.removeListener('data', onData);
             reject(new Error('IPC auth handshake timeout'));
         }, AUTH_TIMEOUT_MS);
+        // CA-63 — decode the stream, not each chunk: a character split across two reads stays whole.
+        const decode = utf8Stream();
         const onData = (chunk) => {
-            buffer += chunk.toString();
+            buffer += decode(chunk);
             const lines = buffer.split('\n');
             buffer = lines.pop() || '';
             for (const line of lines) {
@@ -218,8 +221,10 @@ function sendIpc(socket, msg) {
             socket.removeListener('data', onData);
             reject(new Error(`Daemon RPC timeout after ${TIMEOUT_MS}ms`));
         }, TIMEOUT_MS);
+        // CA-63 — decode the stream, not each chunk: a character split across two reads stays whole.
+        const decode = utf8Stream();
         const onData = (chunk) => {
-            buffer += chunk.toString();
+            buffer += decode(chunk);
             const lines = buffer.split('\n');
             buffer = lines.pop() || '';
             for (const line of lines) {

package/dist/ipc-client.js

@@ -11,6 +11,7 @@ import { EventEmitter } from 'events';
 import { resolveClientAuthToken } from './ipc-auth.js';
 import { ipcSocketPath, socketMayExist } from './ipc-path.js';
 import { activeAgentWrap } from './agent-attribution.js';
+import { utf8Stream } from './utf8-stream.js';
 /** The default address (Unix socket, or this user's named pipe on Windows) — see `ipc-path.ts`. */
 const IPC_SOCKET_PATH = ipcSocketPath();
 /** Default timeout for RPC calls (ms) */
@@ -77,8 +78,10 @@ export class IpcClient extends EventEmitter {
             socket.on('connect', () => {
                 this._connected = true;
             });
+            // CA-63 — decode the stream, not each chunk: a character split across two reads stays whole.
+            const decode = utf8Stream();
             socket.on('data', (data) => {
-                this.buffer += data.toString();
+                this.buffer += decode(data);
                 const lines = this.buffer.split('\n');
                 this.buffer = lines.pop() || '';
                 for (const line of lines) {

package/dist/ipc-server.js

@@ -27,6 +27,7 @@ import { createConnection, createServer } from 'net';
 import { EventEmitter } from 'events';
 import { resolveAuthScope } from './ipc-auth.js';
 import { ipcSocketPath, socketMayExist, clearStaleSocket, restrictSocketToOwner } from './ipc-path.js';
+import { utf8Stream } from './utf8-stream.js';
 /** The default address (Unix socket, or this user's named pipe on Windows) — see `ipc-path.ts`. */
 const IPC_SOCKET_PATH = ipcSocketPath();
 /**
@@ -194,8 +195,10 @@ export class IpcServer extends EventEmitter {
                 daemonPid: process.pid,
                 requireAuth: true,
             });
+            // CA-63 — decode the stream, not each chunk: a character split across two reads stays whole.
+            const decode = utf8Stream();
             socket.on('data', (data) => {
-                client.buffer += data.toString();
+                client.buffer += decode(data);
                 const lines = client.buffer.split('\n');
                 client.buffer = lines.pop() || '';
                 for (const line of lines) {

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;
+    }
+}