beehaven 0.8.29 → 0.8.34

package/dist/cli.js

@@ -16,6 +16,7 @@
 if (!process.env.BEEHAVEN_IPC_SCOPE) {
     process.env.BEEHAVEN_IPC_SCOPE = 'developer';
 }
+import './windows-hide.js'; // FIRST: no console windows flashing on Windows (CAN2-56)
 import { parseArgs } from 'node:util';
 import { devModeAvailable, buildLabel, PUBLIC_BUILD } from './build-channel.js';
 import { readFileSync, existsSync, mkdirSync, writeFileSync, readdirSync, } from 'fs';
@@ -142,6 +143,7 @@ function printHelp() {
 
     beehaven guide                             Agent-first setup and signup handoff
     beehaven signup                            Create a free Clearly account
+    beehaven agents-md                         Add Clearly to this project's AGENTS.md
 
   Personal workspace:
     beehaven cd home
@@ -448,8 +450,9 @@ ${DEV_ONLY_HELP ? `
 
   Note: if you also run the Hive menu-bar app, the tray is the
   primary owner of the daemon. CLI start/stop only act when the tray
-  isn't running its own daemon. The same socket (/tmp/beehaven-ipc.sock)
-  is shared in both modes — never two daemons at once.
+  isn't running its own daemon. The same socket (/tmp/beehaven-ipc.sock;
+  a per-user named pipe on Windows) is shared in both modes — never two
+  daemons at once.
 
   ─────────────────────────────────────────────────────────────────────
   OPTIONS
@@ -846,48 +849,9 @@ async function printStatus() {
  * One function, because four hand-written copies is how one missing `else` became four.
  */
 async function resolveTargetBuilding(values) {
-    if (values.building)
-        return; // an explicit flag always wins
-    const { getTarget, isHomeAddress } = await import('./cli-state.js');
-    const t = getTarget();
-    if (t?.address?.includes('/')) {
-        const [bType, ...bIdParts] = t.address.split('/');
-        values.building = `${bType}:${bIdParts.join('/')}`;
-        return;
-    }
-    if (t && isHomeAddress(t.address)) {
-        /**
-         * ⚠ HOME IS A POSITIVE STATEMENT, NOT AN ABSENCE. The daemon's focus is a routing
-         * optimisation; the file is where the user said to be. If they disagree the daemon is
-         * stale — drop it, so the call lands where `pwd` says it will, and SAY so.
-         */
-        try {
-            const { daemonGetConnection, daemonDisconnect } = await import('./daemon-client.js');
-            const conn = await daemonGetConnection();
-            if (conn?.buildingId) {
-                await daemonDisconnect();
-                console.error(`\x1b[2m  (dropped a stale daemon focus on ${conn.buildingType}/${conn.buildingId}`
-                    + ` — your target is home)\x1b[0m`);
-            }
-        }
-        catch { /* no daemon, or it refused — home is the default route anyway */ }
-        return;
-    }
-    if (!t) {
-        /**
-         * ⚠ NO TARGET EVER SET — inherit the daemon's connection. The machine-global fallback
-         * `cli-state.ts` warns about: another room, the Mac app or a human's terminal can set
-         * it, so an agent that never runs `connect` inherits someone else's cursor. Kept for
-         * back-compat; `connect home` is what opts out, and this fix makes that opt-out real.
-         */
-        try {
-            const { daemonGetConnection } = await import('./daemon-client.js');
-            const conn = await daemonGetConnection();
-            if (conn)
-                values.building = `${conn.buildingType}:${conn.buildingId}`;
-        }
-        catch { /* fall through to home */ }
-    }
+    // ⚠ ONE resolver for every verb, typed or raw (AWO-393/394) — see session-target.ts.
+    const { resolveTargetBuilding: resolve } = await import('./session-target.js');
+    await resolve(values);
 }
 /**
  * ⚠⚠ AN IDENTIFIABLE AGENT MUST LOG IN BEFORE IT ACTS.
@@ -954,6 +918,11 @@ const AGENT_LOGIN_EXEMPT = new Set([
      * would refuse the one person it is for — the agent whose user has not signed up yet (SGS-73).
      */
     'handoff',
+    /**
+     * ⚠ `agents-md` WRITES A FILE IN THIS REPO AND NOTHING ELSE — it never opens a workspace, and it is
+     * part of setting a project up, which must not require the login it helps a teammate do (CAN2-66).
+     */
+    'agents-md',
 ]);
 /**
  * ⚠ ALIAS → CANONICAL VERB, for the activity log's `source` column only.
@@ -1095,8 +1064,10 @@ async function requireAgentSession(command, values) {
         cfg = {};
     }
     // ⚠ ONE DECISION, EXECUTED BY A GUARD (`principalKind`). This branch does nothing but act on it.
+    const { activeSessionBinding: sessionForGate } = await import('./agent-state.js');
     const who = principalKind({
-        agentSessionId: rec?.sessionId,
+        // This session's own work session first (AWO-394); the shared record's for sessions bound before it.
+        agentSessionId: sessionForGate(name)?.sessionId ?? rec?.sessionId,
         agentExpiresAt: rec?.expiresAt,
         agentRuntime: isAgentRuntime(),
         accountUserId: cfg.userId,
@@ -1369,6 +1340,9 @@ 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).
+            mcp: { type: 'boolean', default: false },
+            print: { type: 'boolean', default: false },
             /**
              * ⚠⚠ `beehaven sheet` / `beehaven slides` — AND AN UNDECLARED FLAG IS A FATAL, NOT A NO-OP.
              *
@@ -2226,6 +2200,14 @@ async function run() {
             // workspace via daemonRpc('shell:exec', …) — see
             // commands/shell.ts:resolveDefaultBuilding + execRemote.
             const { HOME_ADDRESSES: HOME_ADDRS, CANONICAL_HOME_ADDRESS } = await import('./cli-state.js');
+            /**
+             * ⚠⚠ A SIGNED-IN SESSION MOVES ONLY ITSELF (AWO-394). The daemon's focus is ONE variable for
+             * the machine, so `connect` used to re-point every other terminal that had no cursor of its
+             * own — agent A connecting to a Shopify store moved agent B. A session's own cursor file is
+             * the whole of its routing; the daemon is not told.
+             */
+            const { activeSessionBinding: sessionOf } = await import('./agent-state.js');
+            const ownSession = sessionOf();
             if (HOME_ADDRS.has(target)) {
                 const { setTarget } = await import('./cli-state.js');
                 // Canonical label is 'workspace' (no "home DO" — the daemon's relay is to the
@@ -2236,7 +2218,11 @@ async function run() {
                 setTarget(CANONICAL_HOME_ADDRESS, 'cloud');
                 // Best-effort daemon-side cleanup of any prior connect()
                 // focus — we want home to be the default routing target.
-                if (daemonUp) {
+                if (ownSession) {
+                    const { moveAgentSession } = await import('./commands/agent.js');
+                    await moveAgentSession(CANONICAL_HOME_ADDRESS);
+                }
+                else if (daemonUp) {
                     try {
                         await daemonDisconnect();
                     }
@@ -2279,6 +2265,15 @@ async function run() {
                 // where we meant to be, and we can retry without a re-`cd`.
                 const { setTarget } = await import('./cli-state.js');
                 setTarget(`${bType}/${bId}`, 'cloud');
+                if (ownSession) {
+                    const { moveAgentSession } = await import('./commands/agent.js');
+                    await moveAgentSession(`${bType}/${bId}`);
+                    if (bType === 'shopifyStore' || bType === 'store') {
+                        console.log(color.dim(`  Store DOs take operator calls through: beehaven admin do ${bType}/${bId} <action> '<json>'  (platform admins)`));
+                    }
+                    console.log(`  ${color.green('✓')} This session → ${color.green(`${bType}/${bId}`)}`);
+                    break;
+                }
                 try {
                     await daemonConnect(bType, bId);
                 }
@@ -2388,7 +2383,13 @@ async function run() {
             const { clearTarget: clearDisconn } = await import('./cli-state.js');
             clearDisconn();
             const { isDaemonRunning: isDaemonRunningDisc, daemonDisconnect: daemonDisconnectDisc } = await import('./daemon-client.js');
-            if (await isDaemonRunningDisc()) {
+            const { activeSessionBinding: sessionOfDisc } = await import('./agent-state.js');
+            if (sessionOfDisc()) {
+                // AWO-394 — a signed-in session goes home alone; the machine-wide focus is someone else's.
+                const { moveAgentSession } = await import('./commands/agent.js');
+                await moveAgentSession('workspace');
+            }
+            else if (await isDaemonRunningDisc()) {
                 try {
                     await daemonDisconnectDisc();
                 }
@@ -2446,7 +2447,22 @@ async function run() {
                     // ⚠ `values` HERE TOO — `beehaven status --agent alice` must report who that call would
                     //   run as, not who the shell happens to be bound to. See `requireAgentSession`.
                     const who = activeAgentName(values);
-                    if (who && eff === who) {
+                    const { activeSessionBinding } = await import('./agent-state.js');
+                    const { describeAddress, currentEnvName } = await import('./session-binding.js');
+                    const bound = activeSessionBinding(who);
+                    if (who && bound) {
+                        // AWO-394 — one session: identity + workspace + env, owned by this scope.
+                        const { loadAgent } = await import('./agent-state.js');
+                        const r = loadAgent(who);
+                        const gone = typeof r?.expiresAt === 'number' && r.expiresAt <= Date.now();
+                        const envNow = currentEnvName();
+                        console.log(gone
+                            ? `  Agent:  ${color.green(who)}  ${'\x1b[31m'}TOKEN EXPIRED\x1b[0m${color.dim(' — calls are refused until `beehaven agent login ' + who + '`')}`
+                            : `  Agent:  ${color.green(who)}${color.dim('  (this session — every call here runs as this agent)')}`);
+                        console.log(`  Session: ${color.green(bound.scope)}${color.dim(`  work session ${bound.sessionId ? bound.sessionId.slice(0, 8) : 'none'} · in ${describeAddress(bound.workspace)}`)}`);
+                        console.log(`  Env:    ${bound.env === envNow ? color.green(bound.env) : `\x1b[31m${bound.env} — daemon is on ${envNow}; calls are refused\x1b[0m`}`);
+                    }
+                    else if (who && eff === who) {
                         // Identity, workspace session and cursor are one handle.
                         const { loadAgent } = await import('./agent-state.js');
                         const r = loadAgent(who);
@@ -2461,6 +2477,11 @@ async function run() {
                             : `  Agent:  ${color.green(who)}${color.dim('  (logged in — calls run as this agent)')}`);
                         console.log(`  Scope:  ${color.green(eff)}${color.dim('  (cursor follows the agent, not the session)')}`);
                     }
+                    else if (raw.startsWith('term-')) {
+                        // AWO-394 — a tab nobody signed in from is the person, on the shared cursor.
+                        console.log(`  Scope:  ${color.green(raw)}${color.dim('  (this tab — `beehaven agent login <name>` here signs in THIS tab only)')}`);
+                        console.log(`  Agent:  ${color.dim('none — calls run as you, on the cursor your other terminals share')}`);
+                    }
                     else if (raw) {
                         console.log(`  Scope:  ${color.green(raw)}${color.dim('  (private cursor — concurrent agents cannot clobber it)')}`);
                         console.log(`  Agent:  ${color.dim('none — calls run as you. `beehaven agent login <name>` to act as an agent')}`);
@@ -3143,6 +3164,15 @@ async function run() {
             console.log('  (or quit and relaunch the Hive Mac app if it owns the daemon).');
             break;
         }
+        case 'agents-md': {
+            const { cmdAgentsMd } = await import('./commands/agents-md.js');
+            process.exitCode = cmdAgentsMd(positionals[1], {
+                mcp: !!values.mcp,
+                print: !!values.print,
+                remove: !!values.remove,
+            });
+            break;
+        }
         case 'handoff': {
             const { cmdHandoff } = await import('./commands/handoff.js');
             process.exitCode = await cmdHandoff(positionals[1], {
@@ -3171,11 +3201,10 @@ async function run() {
             console.log(`  Sign up at ${color.cyan(signupUrl)}.`);
             console.log('  Then run "beehaven login" to wire the CLI to your account.');
             console.log('');
-            try {
-                const { spawn } = await import('child_process');
-                spawn('open', [signupUrl], { stdio: 'ignore', detached: true }).unref();
-            }
-            catch { }
+            // The shared opener: per-platform (Windows has no `open`), and a spawn failure prints the
+            // URL instead of crashing on an unhandled child 'error' event.
+            const { openInBrowser } = await import('./browser-login.js');
+            openInBrowser(signupUrl);
             break;
         }
         case 'treehouse': {

package/dist/commands/agent-skills.js

@@ -236,14 +236,25 @@ export function installAgentSkills() {
                  * ⚠ NO STAMP ⇒ TREATED AS UNTOUCHED. Every skill installed before stamping existed has
                  * none, and assuming an edit there would freeze them permanently — updates would silently
                  * stop landing, which is the failure mode this whole change exists to remove.
+                 *
+                 * ⚠ IDENTICAL TO WHAT SHIPS ⇒ CURRENT, WHATEVER THE STAMP SAYS (PPO-476). The Mac app writes
+                 * these same files on every launch, and a copy can only equal the release by coming from
+                 * it. Asked first, a stale stamp called every skill "edited locally" and none was ever
+                 * re-stamped, so the next real update never landed either.
                  */
                 if (existing) {
+                    const local = localSha(destDir, skillFiles);
+                    if (entry?.sha && local === entry.sha) {
+                        stamp(destDir, skillFiles, warnings);
+                        steps.push(`${agent}/${name}=current`);
+                        continue;
+                    }
                     let stamped = '';
                     try {
                         stamped = JSON.parse(fs.readFileSync(path.join(destDir, STAMP), 'utf8')).sha ?? '';
                     }
                     catch { /* unstamped */ }
-                    if (stamped && localSha(destDir, skillFiles) !== stamped) {
+                    if (stamped && local !== stamped) {
                         warnings.push(`${agent}/${name}: edited locally — left alone (delete it to take the shipped copy)`);
                         steps.push(`${agent}/${name}=locally-modified`);
                         continue;

package/dist/commands/agent.js

@@ -91,6 +91,60 @@ async function endWorkspaceSession(record, summary) {
         return false;
     }
 }
+/** `team/<id>` → the `--building` form `resolveBuilding` takes; home → undefined. */
+function buildingFor(address) {
+    if (!address || !address.includes('/'))
+        return undefined;
+    const i = address.indexOf('/');
+    return `${address.slice(0, i)}:${address.slice(i + 1)}`;
+}
+/** Workspace DOs hold agent work sessions; a store or a local app does not. */
+function holdsWorkSessions(address) {
+    return !address.includes('/') || /^(team|workspace)\//.test(address);
+}
+/**
+ * Run an action in a given workspace (AWO-394) — the session lives in the workspace it works in,
+ * not in whichever one the daemon happens to dial. Home goes direct; others through the proxy.
+ */
+async function rpcIn(address, action, input, timeout) {
+    const { resolveBuilding } = await import('./workspace.js');
+    const routed = resolveBuilding(action, input, buildingFor(address));
+    return rpcOnce(routed.action, routed.input, timeout);
+}
+/**
+ * "hive2 (workspace/98bef9…)" rather than a bare id — what an agent reads to know where it is.
+ * Best-effort: the account roster (`workspace:list`), falling back to the address itself.
+ */
+async function workspaceLabel(address) {
+    const { describeAddress } = await import('../session-binding.js');
+    const plain = describeAddress(address);
+    if (address.includes('/') && !/^(team|workspace)\//.test(address))
+        return plain;
+    try {
+        const { daemonRpc } = await import('../daemon-client.js');
+        const res = await Promise.race([daemonRpc('workspace:list', {}), new Promise((r) => setTimeout(() => r(null), 4_000))]);
+        const inner = res?.result ?? res;
+        const id = address.includes('/') ? address.slice(address.indexOf('/') + 1) : String(inner?.current ?? '');
+        const hit = (inner?.workspaces ?? []).find((w) => String(w?.id ?? '') === id);
+        if (hit?.name)
+            return address.includes('/') ? `${hit.name}  (${plain})` : `${hit.name} — home (your default workspace)`;
+    }
+    catch { /* the roster is a nicety */ }
+    return plain;
+}
+/** End one work session where it lives. Best-effort, like `endWorkspaceSession`. */
+async function endSessionIn(address, sessionId, agentId, summary) {
+    try {
+        const r = await rpcIn(address, 'agent-session-end', {
+            id: sessionId, agentId, ...(summary?.trim() ? { summary: summary.trim() } : {}),
+        }, 5_000);
+        const result = r?.result ?? r;
+        return result?.ok !== false && !result?.error;
+    }
+    catch {
+        return false;
+    }
+}
 const dim = (s) => `\x1b[2m${s}\x1b[0m`;
 const green = (s) => `\x1b[32m${s}\x1b[0m`;
 const bold = (s) => `\x1b[1m${s}\x1b[0m`;
@@ -701,7 +755,38 @@ async function agentLogin(args, values) {
      * actually began. `existingRecord` is read before the write for exactly this.
      */
     const birthday = existingRecord?.birthday ?? new Date().toISOString();
-    const previousSessionEnded = await endWorkspaceSession(existingRecord);
+    /**
+     * ⚠⚠ ONE SESSION = THIS PROCESS SCOPE (AWO-394). A re-login replaces the session THIS scope had,
+     * and nothing else: it used to end `record.sessionId` — one field shared by every terminal using
+     * the name — so logging in from a second terminal closed the first terminal's session and both
+     * then wrote under the new one.
+     */
+    const { deriveAgentScope } = await import('../agent-scope.js');
+    const { readSessionBinding, writeSessionBinding, currentEnvName, normalizeWorkspaceAddress, describeAddress, } = await import('../session-binding.js');
+    const { writeTargetForScope, readTargetForKey } = await import('../cli-state.js');
+    const scope = deriveAgentScope();
+    const priorBinding = scope ? readSessionBinding(scope) : null;
+    if (priorBinding?.sessionId)
+        await endSessionIn(priorBinding.workspace, priorBinding.sessionId, minted.agentId);
+    /**
+     * WHERE THIS SESSION WORKS: `--workspace`, else where this identity last worked, else home. The
+     * identity's last workspace is what keeps a durable agent from losing its place each conversation
+     * — the reason the cursor used to be keyed on the agent name — without letting one live session
+     * move another.
+     */
+    const requestedWorkspace = typeof values.workspace === 'string' ? values.workspace.trim() : '';
+    const normalizedRequest = requestedWorkspace ? normalizeWorkspaceAddress(requestedWorkspace) : null;
+    if (requestedWorkspace && !normalizedRequest) {
+        console.error(`  Unrecognised workspace "${requestedWorkspace}".`);
+        console.error('  Use: home · team/<id> · workspace/<id> · a 64-character workspace id   (beehaven workspaces lists them)');
+        process.exit(1);
+    }
+    const legacyCursor = readTargetForKey(name)?.address;
+    const chosenWorkspace = normalizedRequest
+        || existingRecord?.lastWorkspace
+        || (legacyCursor ? normalizeWorkspaceAddress(legacyCursor) : null)
+        || 'workspace';
+    const sessionEnv = currentEnvName();
     /**
      * ⚠⚠ FILL THE LIFETIME FIELDS FROM THE TOKEN — the cloud mint path does not
      * return them and a record without `expiresAt` can never be seen as expired.
@@ -740,8 +825,9 @@ async function agentLogin(args, values) {
          * resuming is least recoverable.
          */
         ...(existingRecord?.boundScopes ? { boundScopes: existingRecord.boundScopes } : {}),
-        ...(!previousSessionEnded && existingRecord?.sessionId ? { sessionId: existingRecord.sessionId } : {}),
+        ...(existingRecord?.sessionId ? { sessionId: existingRecord.sessionId } : {}),
         ...(existingRecord?.lastLoginAt ? { lastLoginAt: existingRecord.lastLoginAt } : {}),
+        lastWorkspace: chosenWorkspace,
     };
     saveAgent(name, record);
     /**
@@ -754,10 +840,14 @@ async function agentLogin(args, values) {
      * instead of silently replaced. The family (what un-logged-in sessions inherit) is claimed
      * below, only once a session actually starts.
      */
-    const { deriveAgentScope } = await import('../agent-scope.js');
     const { bindAgentScope, agentForScope, loginSessionOutcome } = await import('../agent-state.js');
-    const scope = deriveAgentScope();
     bindAgentScope(name, scope, { family: false });
+    // The session record: identity + workspace + env, owned by this scope alone. Written before the
+    // workspace answers for the same reason the binding is — a refused login must still own its scope.
+    if (scope) {
+        writeSessionBinding({ scope, agent: name, workspace: chosenWorkspace, env: sessionEnv, boundAt: Date.now() });
+        writeTargetForScope(scope, chosenWorkspace, chosenWorkspace === 'workspace' ? 'cloud' : undefined);
+    }
     // Sync to Electron store if present
     try {
         const p = join(homedir(), 'Library', 'Application Support', 'clearly-desktop', 'config.json');
@@ -821,18 +911,36 @@ async function agentLogin(args, values) {
     // `loginSessionOutcome` — and is reported, never swallowed.
     let started;
     let thrown;
-    try {
-        started = await rpcOnce('agent-session-start', {
-            agentId: record.agentId,
-            client: String(values.client ?? 'cli').trim() || 'cli',
-            label: String(values.label ?? '').trim() || undefined,
-            expiresAt: record.expiresAt,
-        }, 15_000);
+    const sessionInput = {
+        agentId: record.agentId,
+        client: String(values.client ?? 'cli').trim() || 'cli',
+        label: String(values.label ?? '').trim() || undefined,
+        expiresAt: record.expiresAt,
+    };
+    if (holdsWorkSessions(chosenWorkspace)) {
+        try {
+            // ⚠ IN THE SESSION'S WORKSPACE (AWO-394) — it used to open in the daemon's default
+            // workspace whatever the cursor said, and that id then rode on calls to other workspaces.
+            started = await rpcIn(chosenWorkspace, 'agent-session-start', sessionInput, 15_000);
+            const first = loginSessionOutcome(started);
+            // An identity is the ACCOUNT's; each workspace admits it once. Same self-heal `call` does.
+            if (first.kind === 'refused' && chosenWorkspace !== 'workspace' && /unknown agent|not admitted|unknown-agent/i.test(`${first.scope} ${first.reason}`)) {
+                const admitted = await rpcIn(chosenWorkspace, 'agent-admit', { agentId: record.agentId }, 20_000).catch(() => null);
+                if ((admitted?.result ?? admitted)?.ok)
+                    started = await rpcIn(chosenWorkspace, 'agent-session-start', sessionInput, 15_000);
+            }
+        }
+        catch (err) {
+            thrown = err ?? new Error('agent-session-start failed');
+        }
     }
-    catch (err) {
-        thrown = err ?? new Error('agent-session-start failed');
+    const outcome = holdsWorkSessions(chosenWorkspace)
+        ? loginSessionOutcome(started, thrown)
+        : { kind: 'unreachable', reason: 'a store keeps no agent work sessions' };
+    if (outcome.kind === 'started' && scope) {
+        const { updateSessionBinding } = await import('../session-binding.js');
+        updateSessionBinding(scope, { sessionId: outcome.sessionId });
     }
-    const outcome = loginSessionOutcome(started, thrown);
     if (outcome.kind === 'started') {
         saveAgentSession(name, outcome.sessionId);
         /**
@@ -876,8 +984,11 @@ async function agentLogin(args, values) {
         if (scope) {
             const resolved = agentForScope(scope);
             if (resolved === name) {
-                console.log(`  ${green('✓')} Bound to this session (${cyan(scope)}) — every call here now runs as ${cyan(name)}.`);
-                console.log(dim('    Other terminals: export BEEHAVEN_AGENT=' + name));
+                console.log(`  This session  ${cyan(scope)}`);
+                console.log(`    Agent       ${cyan(name)}${dim('   every beehaven command here runs as this agent — nothing to pass per call')}`);
+                console.log(`    Workspace   ${cyan(await workspaceLabel(chosenWorkspace))}${dim('   switch: beehaven connect <workspace>')}`);
+                console.log(`    Env         ${cyan(sessionEnv)}${dim('   calls are refused if the daemon moves to another env')}`);
+                console.log(dim('  Other sessions and terminal tabs keep their own agent and workspace.'));
             }
             else {
                 console.error(`  ${yellow('⚠')} Could not bind this session (${scope}) to ${name}; calls resolve to ${resolved ?? 'nobody'}.`);
@@ -886,9 +997,10 @@ async function agentLogin(args, values) {
             }
         }
         else {
-            console.log('  Activate in THIS terminal:');
+            // No per-session handle: a terminal that does not say which tab it is.
+            console.log('  This terminal has no session id, so the sign-in is shared by every such terminal.');
+            console.log('  To keep it to THIS terminal:');
             console.log(`    ${cyan(`eval "$(beehaven agent use ${name})"`)}`);
-            console.log(dim(`  or: export BEEHAVEN_AGENT=${name}`));
         }
     }
     console.log('');
@@ -1159,6 +1271,14 @@ function agentWhoami(values) {
     console.log(`    birthday:    ${r.birthday ? formatBirthday(r.birthday) : 'unknown (created before birthdays)'}`);
     console.log(`    voice:       ${r.voice?.provider ? (r.voice.voiceId ? `${r.voice.provider}:${r.voice.voiceId}` : `${r.voice.provider} (base voice)`) : 'unbound — speak picks whatever is reachable'}`);
     console.log(`    expires:     ${formatRemaining(r.expiresAt)}`);
+    if (active.session) {
+        console.log(`    session:     ${active.session.scope}  (work session ${active.session.sessionId ? active.session.sessionId.slice(0, 8) : 'none'})`);
+        console.log(`    workspace:   ${active.session.workspace}`);
+        console.log(`    env:         ${active.session.env}`);
+    }
+    else {
+        console.log(dim('    session:     none bound here — `beehaven agent login ' + active.name + '` binds this session'));
+    }
     if (active.expired)
         console.log(dim(`    refresh: beehaven agent login ${active.name}`));
     console.log('');
@@ -1184,6 +1304,53 @@ async function agentStatus(args, values) {
     }
     console.log(`  ${green('✓')} ${cyan(name)} status: ${String(result.message ?? message)}`);
 }
+// ── connect, for a signed-in session ─────────────────
+/**
+ * `beehaven connect <address>` in a signed-in session (AWO-394): move THIS session — its cursor,
+ * its work session and its binding — and nothing else. The cursor file is already this session's;
+ * this moves the work session to the workspace it now works in (a session lives in one workspace's
+ * DO, and its id used to ride on calls to others), and remembers the workspace on the identity so
+ * the next login starts there.
+ */
+export async function moveAgentSession(address) {
+    const { activeSessionBinding } = await import('../agent-state.js');
+    const { updateSessionBinding, describeAddress } = await import('../session-binding.js');
+    const bound = activeSessionBinding();
+    if (!bound)
+        return;
+    const record = loadAgent(bound.agent);
+    if (!record)
+        return;
+    if (bound.workspace === address)
+        return;
+    if (bound.sessionId)
+        await endSessionIn(bound.workspace, bound.sessionId, record.agentId);
+    let sessionId;
+    if (holdsWorkSessions(address)) {
+        const input = { agentId: record.agentId, client: 'cli', expiresAt: record.expiresAt };
+        const { loginSessionOutcome } = await import('../agent-state.js');
+        try {
+            let r = await rpcIn(address, 'agent-session-start', input, 15_000);
+            let o = loginSessionOutcome(r);
+            if (o.kind === 'refused' && address !== 'workspace' && /unknown agent|not admitted|unknown-agent/i.test(`${o.scope} ${o.reason}`)) {
+                const admitted = await rpcIn(address, 'agent-admit', { agentId: record.agentId }, 20_000).catch(() => null);
+                if ((admitted?.result ?? admitted)?.ok) {
+                    console.error(dim(`  ${bound.agent} joined this workspace.`));
+                    r = await rpcIn(address, 'agent-session-start', input, 15_000);
+                    o = loginSessionOutcome(r);
+                }
+            }
+            if (o.kind === 'started')
+                sessionId = o.sessionId;
+            else if (o.kind === 'refused')
+                console.error(`  ${yellow('⚠')} ${bound.agent} has no work session here: ${o.reason}`);
+        }
+        catch { /* unreachable — calls still route; the next login opens a session */ }
+    }
+    updateSessionBinding(bound.scope, { workspace: address, sessionId });
+    saveAgent(bound.agent, { ...record, lastWorkspace: address });
+    console.log(dim(`  Session ${bound.scope} (${bound.agent}) now works in ${await workspaceLabel(address)}${sessionId ? ` · work session ${sessionId.slice(0, 8)}` : ''}. Other sessions are unaffected.`));
+}
 // ── handoff ──────────────────────────────────────────
 /**
  * End the current work session WITH a note — the one thing the next login (this agent's, or the
@@ -1203,6 +1370,22 @@ async function agentHandoff(args, values) {
         process.exit(1);
     }
     const record = loadAgent(name);
+    const { activeSessionBinding } = await import('../agent-state.js');
+    const bound = activeSessionBinding(name);
+    if (bound?.sessionId && record) {
+        // AWO-394 — hand off THIS session, where it lives; other sessions of the name are untouched.
+        if (!await endSessionIn(bound.workspace, bound.sessionId, record.agentId, summary)) {
+            console.error(`  ${yellow('⚠')} The workspace did not accept the handoff; the session is still open.`);
+            process.exitCode = 1;
+            return;
+        }
+        const { updateSessionBinding } = await import('../session-binding.js');
+        updateSessionBinding(bound.scope, { sessionId: undefined });
+        if (record.sessionId === bound.sessionId)
+            clearAgentSessionId(name);
+        console.log(`  ${green('✓')} Handed off session ${cyan(bound.sessionId.slice(0, 8))} — the next login for ${cyan(name)} reads this first.`);
+        return;
+    }
     if (!record?.sessionId) {
         console.error(`  ${yellow('⚠')} ${cyan(name)} has no open work session on this device.`);
         console.error(dim(`    Start one with: beehaven agent login ${name} --label "<work>" --client cli`));
@@ -1236,18 +1419,42 @@ async function agentLogout(args, values) {
     // it stays in the workspace (source of truth) AND on this device, so you can
     // log back in. To remove the current workspace projection use `agent delete <name>`;
     // to remove the portable account identity use `agent delete <name> --account --yes`.
-    await endWorkspaceSession(record);
-    try {
-        await rpcOnce('agent:disconnect', { agentId: record.agentId ?? name }, 5_000);
-    }
-    catch {
-        /* daemon down — nothing to close */
+    /**
+     * ⚠ AWO-394 — signing out ends THIS session (its binding, its work session, its cursor) and
+     * leaves every other session signed in as the same name running. It used to clear the shared
+     * record's session, which locked every other terminal using the name out at once.
+     */
+    const { activeSessionBinding, unbindAgentScope } = await import('../agent-state.js');
+    const { clearSessionBinding, listSessionBindings } = await import('../session-binding.js');
+    const bound = activeSessionBinding(name);
+    if (bound) {
+        if (bound.sessionId)
+            await endSessionIn(bound.workspace, bound.sessionId, record.agentId);
+        clearSessionBinding(bound.scope);
+        // …and this scope stops resolving to the name, or the next call here would still act as it.
+        unbindAgentScope(name, bound.scope);
+        if (record.sessionId && record.sessionId === bound.sessionId)
+            clearAgentSessionId(name);
+    }
+    else {
+        await endWorkspaceSession(record);
+        clearAgentSession(name);
+    }
+    const others = listSessionBindings().filter((b) => b.agent === name);
+    if (!others.length) {
+        try {
+            await rpcOnce('agent:disconnect', { agentId: record.agentId ?? name }, 5_000);
+        }
+        catch {
+            /* daemon down — nothing to close */
+        }
     }
-    clearAgentSession(name);
-    console.log(`  ${green('✓')} Signed out agent "${name}" — session ended, identity kept.`);
+    console.log(`  ${green('✓')} Signed out agent "${name}" ${bound ? 'in this session' : ''} — session ended, identity kept.`);
+    if (others.length)
+        console.log(dim(`  ${others.length} other session${others.length === 1 ? ' is' : 's are'} still signed in as ${name}.`));
     console.log(dim(`  Log back in: beehaven agent login ${name}   ·   workspace remove: beehaven agent delete ${name}`));
-    if (activeAgentName(values) === name && !values.agent) {
-        console.log(dim(`  This was your active agent — run: unset BEEHAVEN_AGENT`));
+    if (process.env.BEEHAVEN_AGENT === name && !values.agent) {
+        console.log(dim(`  BEEHAVEN_AGENT still names ${name} in this shell — run: unset BEEHAVEN_AGENT`));
     }
 }
 // ── delete (destructive — removes the identity from the workspace + device) ──