beehaven 0.8.29 → 0.8.34

package/dist/agent-attribution.js

@@ -62,6 +62,21 @@ export const BOOTSTRAP_ACTIONS = new Set([
     // The workspace-scoped predecessors, kept so an older flow still bootstraps.
     'agent-mint-token', 'agent-create', 'agent-list',
 ]);
+/**
+ * ⚠⚠ SPT-13 — `agent-create` ESTABLISHES AN IDENTITY ONLY WHEN IT CREATES THE ONE SIGNED IN.
+ *
+ * Unwrapped, it runs as the account owner. That is right for the bootstrap it exists for — the
+ * signed-in agent creating ITSELF in a workspace that has no row for it yet. It was wrong for every
+ * other agent: a signed-in agent whose matrix says `agents.create = false` minted `ss41-probe`
+ * because the call left as its owner. Creating ANOTHER agent is ordinary work, so it is wrapped and
+ * the capability gate decides.
+ */
+function createsAnotherAgent(action, input, active) {
+    if (action !== 'agent-create' || !active || active.expired)
+        return false;
+    // Without an `id` the server mints a random one, so the new agent cannot be the signed-in one.
+    return String(input?.id ?? '').trim() !== active.agentId;
+}
 /**
  * ⚠⚠ ACTIONS THE DAEMON ANSWERS ITSELF — THEY NEVER REACH A WORKSPACE, SO THEY CANNOT BE WRAPPED.
  *
@@ -165,7 +180,7 @@ export function alreadyAttributed(action, input) {
 export function activeAgentWrap(action, input, values) {
     if (alreadyAttributed(action, input))
         return { action, input };
-    if (BOOTSTRAP_ACTIONS.has(action) || DAEMON_LOCAL_ACTIONS.has(action))
+    if (DAEMON_LOCAL_ACTIONS.has(action))
         return { action, input };
     let active = null;
     try {
@@ -174,6 +189,8 @@ export function activeAgentWrap(action, input, values) {
     catch {
         return { action, input };
     }
+    if (BOOTSTRAP_ACTIONS.has(action) && !createsAnotherAgent(action, input, active))
+        return { action, input };
     if (!active || active.expired)
         return { action, input };
     return {
@@ -182,7 +199,8 @@ export function activeAgentWrap(action, input, values) {
             agentId: active.agentId,
             action,
             input,
-            ...(active.record.sessionId ? { sessionId: active.record.sessionId } : {}),
+            // This session's own work session (AWO-394), not the record every terminal shares.
+            ...(active.sessionId ? { sessionId: active.sessionId } : {}),
             // ⚠ WHICH DOOR — `cli:call` vs `cli:ticket` vs … See `cliDoor()` and
             // `agent_activity.source`. Set here, at the ONE wrap every CLI path shares, so a new
             // verb is labelled without its author having to know this exists.

package/dist/agent-scope.js

@@ -29,9 +29,43 @@
  * `cd` is recorded.
  */
 export function deriveAgentScope(env = process.env) {
+    /**
+     * ⚠⚠ A HARNESS SESSION ID OUTRANKS `BEEHAVEN_AGENT` (AWO-394). The env var names WHO — and
+     * `activeAgentName` still reads it first for that — but it is not a per-session handle: the
+     * daemon spawns every desktop Claude session with `BEEHAVEN_AGENT=<desktop principal>`, so they
+     * all derived ONE scope and shared one cursor and one work session. The session id is what
+     * tells two conversations of one agent apart.
+     */
+    const harness = harnessScope(env);
+    if (harness && harness !== 'claude')
+        return harness;
     const explicit = (env.BEEHAVEN_AGENT || '').trim();
     if (explicit)
-        return explicit; // an explicit choice always wins
+        return explicit; // an explicit choice, absent a session id
+    if (harness)
+        return harness;
+    /**
+     * ⚠ NO MARKER AND NO TTY IS STILL NOT A PERSON. Key on the PARENT pid — stable for the
+     * life of one process tree, different for a concurrent one. Not perfect (pids are reused
+     * eventually), but the failure mode of a collision here is two runs of the SAME tool,
+     * which is far milder than the shared-file failure it replaces: two DIFFERENT agents.
+     */
+    if (!process.stdin.isTTY && !process.stdout.isTTY)
+        return `pid-${process.ppid}`;
+    /**
+     * ⚠ A TERMINAL TAB IS ITS OWN SCOPE WHEN THE TERMINAL SAYS WHICH TAB (AWO-394). Every human
+     * terminal used to derive `''`, so one `agent login` in any tab made EVERY tab that agent — and
+     * the login's own advice ("other terminals: export BEEHAVEN_AGENT") was moot. These ids are set
+     * per tab/pane by the terminal itself. Without one, `''` keeps the old shared behaviour.
+     *
+     * ⚠ A HUMAN WHO HAS NOT LOGGED IN AS AN AGENT STILL SHARES `target.json` — `cli-state`
+     * maps an unbound `term-*` scope back to the shared cursor, so nobody's `cd` moves.
+     */
+    const tab = terminalTabId(env);
+    return tab ? `term-${tab}` : ''; // a human at a terminal
+}
+/** The harness session scope (`claude-…`, `codex-…`, `gemini-…`), or '' — see `deriveAgentScope`. */
+function harnessScope(env) {
     // Claude Code — its own marker (`daemon-omni.ts` already relies on it: "the SDK refuses to
     // start when CLAUDECODE=1 is set … it's how it refuses to recurse"), plus a per-session id.
     if (env.CLAUDECODE || env.CLAUDE_CODE_ENTRYPOINT) {
@@ -45,15 +79,26 @@ export function deriveAgentScope(env = process.env) {
     if (env.GEMINI_CLI_SESSION_ID) {
         return `gemini-${String(env.GEMINI_CLI_SESSION_ID).replace(/[^A-Za-z0-9]/g, '').slice(0, 12)}`;
     }
-    /**
-     * ⚠ NO MARKER AND NO TTY IS STILL NOT A PERSON. Key on the PARENT pid — stable for the
-     * life of one process tree, different for a concurrent one. Not perfect (pids are reused
-     * eventually), but the failure mode of a collision here is two runs of the SAME tool,
-     * which is far milder than the shared-file failure it replaces: two DIFFERENT agents.
-     */
-    if (!process.stdin.isTTY && !process.stdout.isTTY)
-        return `pid-${process.ppid}`;
-    return ''; // a human at a terminal
+    return '';
+}
+/**
+ * Which terminal tab or pane this is, from the id the terminal itself exports — or ''.
+ * macOS Terminal / iTerm2 (`TERM_SESSION_ID`, `ITERM_SESSION_ID`), Windows Terminal, tmux, kitty,
+ * WezTerm. Hashed to a short token: some carry paths or GUIDs, and it lands in a filename.
+ */
+export function terminalTabId(env = process.env) {
+    const raw = env.TMUX_PANE && env.TMUX ? `tmux${env.TMUX}${env.TMUX_PANE}`
+        : env.ITERM_SESSION_ID || env.TERM_SESSION_ID || env.WT_SESSION
+            || (env.KITTY_WINDOW_ID ? `kitty${env.KITTY_WINDOW_ID}` : '')
+            || (env.WEZTERM_PANE ? `wezterm${env.WEZTERM_PANE}` : '');
+    if (!raw)
+        return '';
+    let h = 2166136261; // FNV-1a — stable, dependency-free
+    for (let i = 0; i < raw.length; i++) {
+        h ^= raw.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return (h >>> 0).toString(36);
 }
 export function principalKind(input) {
     const now = input.now ?? Date.now();

package/dist/agent-state.js

@@ -11,6 +11,7 @@
  * (`agent:mint`) and the CLI just stores the resulting record.
  */
 import { deriveAgentScope } from './agent-scope.js';
+import { readSessionBinding } from './session-binding.js';
 import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, unlinkSync, renameSync, chmodSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
@@ -230,6 +231,17 @@ export function bindAgentScope(name, scope, opts = {}) {
     }
     catch { /* binding is a convenience; a failed write must not fail the login */ }
 }
+/** Forget that `scope` was logged in as `name` — `agent logout` in that session (AWO-394). */
+export function unbindAgentScope(name, scope) {
+    try {
+        const rec = loadAgent(name);
+        const prev = Array.isArray(rec?.boundScopes) ? rec.boundScopes : [];
+        if (!rec || !prev.includes(scope))
+            return;
+        saveAgent(name, { ...rec, boundScopes: prev.filter((s) => s !== scope) });
+    }
+    catch { /* best-effort */ }
+}
 /**
  * The stable half of a process scope — the TOOL rather than the conversation.
  *
@@ -240,6 +252,9 @@ export function bindAgentScope(name, scope, opts = {}) {
 export function scopeFamilyKey(scope) {
     if (!scope)
         return 'family:terminal';
+    // A terminal TAB (AWO-394) inherits nothing: one tab's login must not become another tab's identity.
+    if (scope.startsWith('term-'))
+        return null;
     const m = /^(claude|codex|gemini)-/.exec(scope);
     if (m)
         return `family:${m[1]}`;
@@ -254,6 +269,14 @@ export function scopeFamilyKey(scope) {
  */
 export function agentForScope(scope = '') {
     try {
+        /**
+         * ⚠ THE SESSION BINDING WINS (AWO-394). `agent login` writes `sessions/<scope>.json`, and that
+         * exact record — not a list on a record shared by every terminal using the name — is what this
+         * session is. `boundScopes` below stays for sessions bound before it existed and for the family.
+         */
+        const session = scope ? readSessionBinding(scope) : null;
+        if (session && loadAgent(session.agent))
+            return session.agent;
         const all = listAgents();
         const boundTo = (key) => all
             .filter(({ record }) => Array.isArray(record.boundScopes)
@@ -369,6 +392,18 @@ export function activeAgentName(values) {
         return null;
     }
 }
+/** The session binding of THIS process, when it belongs to `name` (or to whoever is active). */
+export function activeSessionBinding(name) {
+    try {
+        const b = readSessionBinding(deriveAgentScope());
+        if (!b)
+            return null;
+        return !name || b.agent === name ? b : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Resolve the active agent identity for this invocation, or null when no
  * agent is selected. Used by the call path to attach the token + route the
@@ -381,6 +416,13 @@ export function resolveActiveAgent(values) {
     const record = loadAgent(name);
     if (!record)
         return null;
+    const session = activeSessionBinding(name);
+    /**
+     * ⚠ THE SESSION'S OWN WORK SESSION, NOT THE SHARED RECORD'S (AWO-394). `record.sessionId` is one
+     * field for every terminal using this name, so a second terminal's login replaced the first's and
+     * both then wrote under it. A session bound by `agent login` carries its own.
+     */
+    const sessionId = session ? session.sessionId : record.sessionId;
     return {
         name,
         token: record.token,
@@ -389,6 +431,8 @@ export function resolveActiveAgent(values) {
         avatarId: record.avatarId,
         record,
         expired: typeof record.expiresAt === 'number' && record.expiresAt <= Date.now(),
+        ...(sessionId ? { sessionId } : {}),
+        ...(session ? { session } : {}),
     };
 }
 /**

package/dist/agents-md-text.js

@@ -0,0 +1,64 @@
+/**
+ * agents-md-text — the Clearly block for a PROJECT's AGENTS.md, as `beehaven agents-md` writes it
+ * (CAN2-66).
+ *
+ * ⚠⚠ 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.
+ *
+ * ⚠ 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 -->';
+/** 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) {
+    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).';
+    return [
+        CLI_BLOCK_START,
+        '<!-- managed-by: clearly. Run `beehaven agents-md` to update; edit outside this block. -->',
+        '',
+        '## Clearly workspace',
+        '',
+        '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.',
+        '',
+        `- Sign in once per session: ${login}`,
+        '  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. -->',
+        '',
+        '## Clearly workspace (connected over MCP as `clearly`)',
+        '',
+        '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.',
+        '',
+        '- 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,
+    ].join('\n');
+}

package/dist/browser-login.js

@@ -93,10 +93,15 @@ async function warnIfLocalDevDown() {
  * Linux; start on Windows. Failure is SURFACED — silent failure was the bug — so the person can
  * paste the URL themselves.
  */
-function openInBrowser(url) {
+export function openInBrowser(url) {
     try {
-        const opener = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
-        const proc = spawn(opener, [url], { stdio: 'ignore', detached: true });
+        // ⚠ Windows: `start` is a cmd.exe BUILTIN, not a program, so spawning it always failed (ENOENT)
+        // and login fell back to "paste this URL". The URL protocol handler is a real executable, and
+        // passing the URL as an argv entry keeps cmd from splitting it at `&` (CAN2-56).
+        const [opener, args] = process.platform === 'darwin' ? ['open', [url]]
+            : process.platform === 'win32' ? ['rundll32.exe', ['url.dll,FileProtocolHandler', url]]
+                : ['xdg-open', [url]];
+        const proc = spawn(opener, args, { stdio: 'ignore', detached: true, windowsHide: true });
         proc.unref();
         proc.on('error', (err) => {
             console.log(`  ${color.yellow('!')} Couldn't auto-open browser: ${err.message}`);
@@ -260,7 +265,12 @@ export function persistBrowserLogin(captured) {
             userId: captured.userId,
             email: captured.email ?? null,
             displayName: captured.displayName ?? null,
-            tokenStorage: 'keychain',
+            /**
+             * ⚠ SAY WHERE THE TOKEN REALLY IS (CAN2-65). This was always 'keychain', so on Windows —
+             * which has no keychain here — `whoami` reported a keychain that did not exist, and
+             * `Relay.loadConfig` / the refresh path shelled out to macOS `security` on every load.
+             */
+            tokenStorage: keychain.available ? 'keychain' : 'file',
             refreshToken: captured.refreshToken,
             token: captured.idToken,
             endpoint: dialUrl,

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 = 'd733c0004e58-dirty';
+export const BUILD_SHA = '0fc3f190acdb';
 /** ISO-8601 minute precision, UTC. Rewritten in `dist/` by `scripts/stamp-build-channel.mjs`. */
-export const BUILD_TIME = '2026-10-10T21:21Z';
+export const BUILD_TIME = '2026-10-27T20:29Z';
 /**
  * The build identity as one short string, for `--version`.
  *

package/dist/claude-bridge.js

@@ -15,12 +15,13 @@
  *   await bridge.callApp('recorder', 'record', { source: 'mic' });
  */
 import { createConnection } from 'net';
+import { request as httpRequest } from 'http';
 import { existsSync, readFileSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 import { EventEmitter } from 'events';
 import { activeAgentWrap } from './agent-attribution.js';
-const IPC_SOCKET_PATH = '/tmp/beehaven-ipc.sock';
+import { ipcSocketPath, watcherSocketPath, socketMayExist } from './ipc-path.js';
 const CONFIG_DIR = join(homedir(), '.beehaven');
 export class ClaudeBridge extends EventEmitter {
     socket = null;
@@ -39,11 +40,12 @@ export class ClaudeBridge extends EventEmitter {
     async connect() {
         if (this.connected)
             return true;
-        if (!existsSync(IPC_SOCKET_PATH))
+        const ipcPath = ipcSocketPath();
+        if (!socketMayExist(ipcPath))
             return false;
         return new Promise((resolve) => {
             const timeout = setTimeout(() => resolve(false), 5_000);
-            const socket = createConnection({ path: IPC_SOCKET_PATH });
+            const socket = createConnection({ path: ipcPath });
             this.socket = socket;
             socket.on('connect', () => {
                 this.connected = true;
@@ -198,11 +200,12 @@ export class ClaudeBridge extends EventEmitter {
     }
     // ── Internal ───────────────────────────────────────────────────────
     sendEvent(hookEvent, extra = {}) {
-        // Send via the watcher socket (HTTP POST to /tmp/beehaven.sock)
-        // This is the same protocol mwah uses.
-        if (!existsSync('/tmp/beehaven.sock'))
+        // Send via the watcher socket (HTTP POST to /event) — the same protocol mwah uses.
+        // ⚠ `http` is IMPORTED: this was `require('http')`, which is undefined in this ESM package,
+        // so every event threw a ReferenceError once the socket existed (CAN2-56).
+        const watcherPath = watcherSocketPath();
+        if (!socketMayExist(watcherPath))
             return;
-        const http = require('http');
         const body = JSON.stringify({
             hook_event_name: hookEvent,
             session_id: this.sessionId,
@@ -211,8 +214,8 @@ export class ClaudeBridge extends EventEmitter {
             source: 'claude-code',
             ...extra,
         });
-        const req = http.request({
-            socketPath: '/tmp/beehaven.sock',
+        const req = httpRequest({
+            socketPath: watcherPath,
             path: '/event',
             method: 'POST',
             headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) },

package/dist/clearly.js

@@ -26,6 +26,7 @@
  * product promises. GitHub / Linear / Slack ingestion is a separate project; nothing here
  * pretends otherwise, and `status` says so out loud.
  */
+import './windows-hide.js'; // FIRST: no console windows flashing on Windows (CAN2-56)
 import { execFileSync, spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
@@ -47,12 +48,12 @@ const c = {
     red: (s) => `\x1b[31m${s}\x1b[0m`,
 };
 /**
- * ⚠ THE AGENT TURN IS THE SLOW PART. The server's `RESPOND_TIMEOUT_MS` is 300s (clearly CDS-90, was
- * 180s); this waits that plus the report's tail, so a turn that finishes on time is never abandoned
+ * ⚠ THE AGENT JOB IS THE SLOW PART. The server's `RESPOND_TIMEOUT_MS` is 900s (WDP3-62);
+ * this waits that plus the report's tail, so a turn that finishes on time is never abandoned
  * by its caller and a timeout here still means the turn itself ran out. The relay-forward window
  * follows the `_timeout` sent with the call.
  */
-export const TURN_MS = 330_000;
+export const TURN_MS = 930_000;
 /**
  * ⚠ STDERR IS CAPTURED, NOT INHERITED. A failing probe is normal here — `HEAD~30` does not exist in
  * a repo with two commits — and with inherited stderr git printed

package/dist/cli-state.js

@@ -41,7 +41,8 @@
  * target is what stops the inheritance. Pin it, or pass `--building` per call.
  */
 import { deriveAgentScope } from './agent-scope.js';
-import { agentForScope } from './agent-state.js';
+import { agentForScope, loadAgent } from './agent-state.js';
+import { readSessionBinding, scopeKey } from './session-binding.js';
 import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync, renameSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
@@ -92,14 +93,55 @@ export function effectiveScope() {
     const raw = deriveAgentScope();
     if (!raw)
         return ''; // a human — the shared file
+    /**
+     * ⚠⚠ A SESSION BOUND BY `agent login` HAS ITS OWN CURSOR (AWO-394) — keyed on the session, not
+     * the agent name. Keyed on the name, two terminals logged in as one agent shared a workspace:
+     * one `connect` moved both. The workspace a NEW session starts in is chosen at login (the
+     * identity's last workspace, or `--workspace`), which keeps what the name key was for.
+     */
+    if (readSessionBinding(raw))
+        return raw;
     try {
+        // A session bound before session bindings existed keeps its agent-keyed cursor until it logs in again.
         const bound = agentForScope(raw);
-        if (bound)
-            return bound;
+        if (bound && !raw.startsWith('term-')) {
+            // …but only an EXACT binding. A session that merely inherited the family's identity starts
+            // at home in its own cursor — it must not inherit someone else's workspace with the name.
+            const rec = loadAgent(bound);
+            if (Array.isArray(rec?.boundScopes) && rec.boundScopes.includes(raw))
+                return bound;
+        }
     }
     catch { /* no agents dir, or a bad record — fall back to the process scope */ }
+    // A terminal tab nobody logged in from is the human: the shared cursor, exactly as before.
+    if (raw.startsWith('term-'))
+        return '';
     return raw;
 }
+/** The cursor file of a given session scope — `agent login` seeds a NEW session's cursor here. */
+export function writeTargetForScope(scope, address, kind) {
+    const key = scopeKey(scope);
+    if (!key)
+        return;
+    ensureStateDir();
+    const file = join(STATE_DIR, `target-${key}.json`);
+    const tmp = `${file}.tmp-${process.pid}`;
+    writeFileSync(tmp, JSON.stringify({ address, connectedAt: Date.now(), kind: kind ?? inferKind(address) }, null, 2), { mode: 0o600 });
+    renameSync(tmp, file);
+}
+/** Read the cursor of a given scope without making it this process's (the legacy agent-keyed file). */
+export function readTargetForKey(key) {
+    try {
+        const safe = scopeKey(key);
+        if (!safe)
+            return null;
+        const parsed = JSON.parse(readFileSync(join(STATE_DIR, `target-${safe}.json`), 'utf-8'));
+        return typeof parsed?.address === 'string' && parsed.address ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
 function targetFileFor(agent = effectiveScope()) {
     const safe = (agent || '').trim().replace(/[^A-Za-z0-9_-]/g, '');
     return join(STATE_DIR, safe ? `target-${safe}.json` : 'target.json');