@byokit/herdr 0.7.0 → 0.7.2

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## Unreleased
 
+## 0.7.2 (2026-10-09)
+
+- Dependency update: pins @byokit/relay 0.6.0.
+- Dependency update: pins @byokit/link 0.8.0.
+- FIX: (from @byokit/pair 0.9.0) a phone killed while the person at the computer decides now resumes against the pinned computer, for compact and version 1 QRs alike. `pairWithOffer` takes `onPending(grant)`, which hands over the pending grant to keep before the computer can approve this device, and `pendingGrant` accepts a compact QR given the authenticated `host` key, and `parseOffer` reads a compact QR for inspection (expiry, addresses, name, role) without one. Before, `pendingGrant` refused compact QRs, and even a version 1 pending grant never came online after a real kill. A socket that drops once the computer has taken the code now ends pairing with `unreachable` instead of trying the next address, where the spent code or ticket could only be refused as `wrong-code` or `expired`. A socket that closes while `onPending` is still saving ends pairing at once with that close; a version 1 `onPending` that never settles times out. The compact QR is unchanged: 109 characters for one relay address and the name Umer.
+- SECURITY: (from @byokit/pair 0.9.0) pinning and approval semantics. A compact QR's pending grant pins the key the code handshake authenticated, kept after Noise message 2 and before the device's identity goes out in message 3; if saving it fails, pairing stops before the computer learns the device. A device using `onPending` says so inside the handshake, and only then does the computer keep a yes given after its socket dropped, granting only the device key that handshake authenticated; any other device that leaves still gets no grant. A computer with another key at the same address is still refused, and a version 1 `pendingGrant` refuses a `host` that differs from its QR.
+- FIX: (from @byokit/pair 0.9.0) the pairing picture's words match what the host now prints: scan the code, or type the shown code where the phone page asks for it, with no raw address to type.
+- FIX: (from @byokit/pair 0.9.0) the browser pairing test closes only the Chromium processes it spawned — over that browser's own private CDP pipe — instead of signalling a whole process group, so a killed or timed-out test can no longer take out or leave behind the wrong process tree. `BYOKIT_CHROME` is the single documented key that selects the test browser.
+
+- The herdr-kit example's agent rows lead with the workspace folder and name the agent second (`shop · Pi`), question cards name folder and agent without repeating the computer, and state badges read without the sentence's full stop (`Ready for you`).
+
+## 0.7.1 (2026-10-07)
+
+- Dependency update: pins @byokit/relay 0.5.3.
+- Dependency update: pins @byokit/link 0.7.1.
+
+- `move` and `moveToAccount` no longer type env prep into the new pane: the split placement env is verified silently through `pane.get` (set vars exact, unset vars absent, fail closed), so no `unset` lines, echo probes or account folder values stay in the scrollback after a move.
+- The replacement agent keeps the conversation's name: it starts unique while the source is still live, then takes the source's session name through `agent.rename` once the source pane closes (best-effort; a refused rename never fails the move). New panes no longer show `move-<hex>` names.
+- The quickstart now says what to read next (the kit spec's decisions and work packages, then the two ways in
+  and agent readiness). Docs only; no typed surface changed.
+- The `relay` option takes anything with `RelayClient`'s `notify`, so a host can hand the kit a relay it opens after `Host.open` (the client needs the open host). A `RelayClient` still fits; behaviour is unchanged.
+- Unreleased source dependency metadata: pin @byokit/seal 0.3.0 and @byokit/relay 0.5.2; this package's existing version is not republished. Previously published consumer metadata remains unchanged.
+- `startAgent` with a record `env` that sets `HOME` now also places the pane's XDG config, data, state and cache directories under that home (unless set), so a sign-in inside the pane stays in the task-owned home instead of the server's.
+
 ## 0.7.0 (2026-10-02)
 
 - Includes the Muse installation, managed-kind discovery and isolated readiness FIX/SECURITY changes recorded in the unpublished 0.6.0 preparation below; none add native login qualification.

package/README.md

@@ -145,6 +145,10 @@ for (const q of await hd.blocked()) {
 The [herdr-kit example](../../examples/herdr-kit) is the full version: pairing with a QR code and typed code, a
 persistent grant store, and the phone page above.
 
+Read next: [docs/runtime-kits.md](../../docs/runtime-kits.md) §11 for the decisions and the work packages this
+kit does not have yet, and [Two ways in](#two-ways-in) plus
+[Agent readiness](#agent-readiness) for the parts a new app picks first.
+
 ## API at a glance
 
 | Export | What it does |
@@ -154,7 +158,7 @@ persistent grant store, and the phone page above.
 | `HERDR_VERSION`, `HERDR_PROTOCOL` | The pinned Herdr release (`0.9.1`) and the protocol the kit speaks (`22`) |
 | `words`, `agentWords`, `stateWords`, `WORDS` | Plain sentences for agent statuses and kit states |
 | `herdrLink` (`@byokit/herdr/link`) | The host side of the `hd.*` link ops, spread into `Host.open`; scopes each grant to its workspaces and can push sealed approval notices through a relay |
-| `serve` (`@byokit/herdr/link`) | Finds the address with `@byokit/reach` and serves the link (and an optional page) on one port |
+| `serve` (`@byokit/herdr/link`) | Finds the address with `@byokit/discover` and serves the link (and an optional page) on one port |
 | `herdrDevice` (`@byokit/herdr/device`) | The phone and browser side: typed calls over a `DeviceLink` (`tree`, `startAgent`, `prompt`, `read`, `blocked`, `answer`, `events`, `terminal`, notices); no Node import |
 | `openNotice` (`@byokit/herdr/device`) | Opens a sealed approval notice with the device's own seed |
 | `startFakeHerdr`, `writeBinShim`, `herdrContract` (`@byokit/herdr/testing`) | The kit's stand-in Herdr, a bin shim that runs it, and the contract suite the kit passes |
@@ -220,6 +224,9 @@ and are re-read before staging. Timeout returns `busy`, approval returns `blocke
 and missing sequence or invalid bounds returns `unsupported`. The person may stop the step themselves in the pane.
 `busy: 'interrupt'` (confirmed session/terminal/seq) returns `interrupt_unsupported`, never keys or lifecycle calls.
 Offline fixtures do not qualify real working-step handoff or native Pi moves. `StartAgent.env` applies to newly created placements; existing shells cannot receive a new env.
+A record env with `HOME` gives the pane a task-owned home: unless the env sets them, `XDG_CONFIG_HOME`,
+`XDG_DATA_HOME`, `XDG_STATE_HOME` and `XDG_CACHE_HOME` move under it too, so a sign-in inside the pane stays
+there. Other server variables still reach the pane; pass `{ env, unset }` for a fully replaced environment.
 Tokens stay on the device and are never logged. Each provider's own terms apply to how you use your plan.
 
 For managed-folder stores that supply resume arguments and credential shedding, use `move`:

package/dist/accounts.js

@@ -17,52 +17,46 @@ export function createAccountPanes(ctx) {
             return false;
         }
     }
-    // A shell rc can override placement env. Verify what the shell actually resolves, rather
-    // than pane.get's launch env. The variable name is fixed by the provider, never caller text.
-    async function checkEnv(paneId, variable, folder, timeout, absent = false) {
-        const marker = `BYOKIT_ACCOUNT_${randomBytes(8).toString('hex')}`;
-        const deadline = Date.now() + timeout;
-        const expansion = absent ? '${' + variable + '+x}' : '$' + variable;
-        try {
-            await call('pane.send_text', { pane_id: paneId, text: `echo ${marker}="${expansion}"\n` }, timeout);
-            for (;;) {
-                const result = await call('pane.read', { pane_id: paneId, source: 'recent_unwrapped', lines: 40,
-                    format: 'text', strip_ansi: true }, Math.max(1, deadline - Date.now()));
-                const readings = String(result?.read?.text ?? '').split('\n').map((line) => line.trim())
-                    .filter((line) => line.startsWith(`${marker}=`)).map((line) => line.slice(marker.length + 1));
-                if (readings.length > 0)
-                    return readings.includes(folder);
-                if (Date.now() >= deadline)
-                    return false;
-                await sleep(Math.min(100, Math.max(1, deadline - Date.now())));
-            }
-        }
-        catch {
-            return false;
-        }
-    }
-    // agent.start has no env/unset/command field in the pinned protocol. Clear credentials in
-    // the shell that launches it, then verify absence (never echo credential values).
-    async function prepareEnv(paneId, set, unset, variable, timeout) {
+    // Env verification types nothing into the pane: every prep keystroke (unset lines,
+    // echo probes) stays in the new pane's scrollback where users see it after a move. The
+    // placement env rides `pane.split`, applied by the server before the shell is shown,
+    // so `pane.get` proves the new shell's launch env: every set var exact, every unset
+    // var absent. Fail closed: the split call cannot express removals, so a leaked
+    // credential in the launch env refuses the move instead of running on it.
+    // Limitation: a shell rc overriding placement env after launch is not visible here;
+    // no pinned RPC reads shell-effective env without typing into the pane.
+    async function verifyPaneEnv(paneId, set, unset, timeout) {
         const entries = Object.entries(set);
         if ([...entries.map(([key]) => key), ...unset].some((key) => !/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
             || entries.some(([, value]) => typeof value !== 'string' || /[\r\n\0]/.test(value))
             || unset.some((key) => key in set))
             return false;
         try {
-            if (unset.length > 0)
-                await call('pane.send_text', { pane_id: paneId, text: `unset ${unset.join(' ')}\n` }, timeout);
-            if (!await checkEnv(paneId, variable, set[variable], timeout))
+            const pane = (await call('pane.get', { pane_id: paneId }, timeout))?.pane;
+            const env = pane?.env;
+            if (!pane || typeof env !== 'object' || env === null || Array.isArray(env))
                 return false;
-            for (const key of unset)
-                if (!await checkEnv(paneId, key, '', timeout, true))
-                    return false;
-            return true;
+            if (unset.some((key) => Object.hasOwn(env, key)))
+                return false;
+            return entries.every(([key, value]) => env[key] === value);
         }
         catch {
             return false;
         }
     }
+    // The replacement keeps the conversation's user-visible name. The server rejects
+    // duplicate agent names, so it starts unique while the source is still live, then
+    // takes the source's name once that pane is closed. A failed rename keeps the
+    // unique start name and never fails the move.
+    function moveNames(sourceName, kind) {
+        const clean = (value) => {
+            const slug = String(value ?? '').toLowerCase().replace(/[^a-z0-9_-]+/g, '-')
+                .replace(/^[-_0-9]+/, '').slice(0, 32);
+            return /^[a-z][a-z0-9_-]{0,31}$/.test(slug) ? slug : undefined;
+        };
+        const want = clean(sourceName) ?? clean(kind) ?? 'agent';
+        return { start: `${want.slice(0, 25)}-${randomBytes(3).toString('hex')}`, want };
+    }
     async function openSignInTab(o) {
         const { workspaceId, label, folder, ...start } = o;
         try {
@@ -188,16 +182,17 @@ export function createAccountPanes(ctx) {
             catch {
                 return rollback('start_failed');
             }
-            if (request !== undefined && !await prepareEnv(paneId, request.set, request.unset ?? [], variable, timeout)) {
-                return rollback('env_mismatch');
+            if (request !== undefined) {
+                if (!await verifyPaneEnv(paneId, request.set, request.unset ?? [], timeout))
+                    return rollback('env_mismatch');
             }
-            if (request === undefined && !await checkEnv(paneId, variable, o.folder, timeout)) {
+            else if (!await verifyPaneEnv(paneId, { ...o.env, [variable]: o.folder }, [], timeout)) {
                 return rollback('env_mismatch');
             }
+            const names = moveNames(agent?.name, kind);
             try {
-                // Unique names avoid colliding with the still-live source agent.
                 await ctx.startAgent({ kind, cwd: agent.foreground_cwd ?? agent.cwd ?? '.',
-                    name: `move-${randomBytes(8).toString('hex')}`, place: { pane: paneId }, args, timeoutMs: timeout });
+                    name: names.start, place: { pane: paneId }, args, timeoutMs: timeout });
                 await call('agent.wait', { target: paneId, until: ['idle', 'done'], timeout_ms: timeout }, timeout + 5000);
                 const deadline = Date.now() + timeout;
                 for (;;) {
@@ -267,6 +262,15 @@ export function createAccountPanes(ctx) {
                 return failed('close_failed', live);
             }
             // The source is closed: a notification failure cannot undo a successful move.
+            // Take the conversation's name now that it is free; the unique start name stays
+            // when the rename is refused, and a rename failure never undoes the move.
+            if (names.want !== names.start) {
+                try {
+                    await call('agent.rename', { target: paneId, name: names.want }, timeout);
+                    replacement.name = names.want;
+                }
+                catch { /* the unique start name stays; the move already succeeded */ }
+            }
             try {
                 request?.onReplaced?.(paneId);
             }

package/dist/agents.js

@@ -116,7 +116,12 @@ export function createAgents(ctx) {
             throw fail('env_mismatch', 'This pane needs to be opened again to use that sign-in.');
         }
         const timeout = o.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-        const env = o.env === undefined || launch ? {} : { env: o.env };
+        // A pane HOME alone keeps the server's XDG dirs, so a sign-in would land outside it: confine them too.
+        const home = launch ? undefined : o.env?.HOME;
+        const env = o.env === undefined || launch ? {} : { env: home === undefined ? o.env : {
+                XDG_CONFIG_HOME: join(home, '.config'), XDG_DATA_HOME: join(home, '.local', 'share'),
+                XDG_STATE_HOME: join(home, '.local', 'state'), XDG_CACHE_HOME: join(home, '.cache'), ...o.env
+            } };
         let paneId;
         let created = false;
         if (o.worktree !== undefined) {

package/dist/link.d.ts

@@ -1,6 +1,6 @@
 import { type IncomingMessage, type ServerResponse } from 'node:http';
 import { type Grant, type Host, type HostOptions } from '@byokit/link';
-import { type ServeIngress, type Via } from '@byokit/reach';
+import { type ServeIngress, type Via } from '@byokit/discover';
 import type { RelayClient } from '@byokit/relay';
 import type { HerdrKit } from './kit.ts';
 export type HerdrScope = {
@@ -9,7 +9,7 @@ export type HerdrScope = {
 export declare function herdrLink(kit: HerdrKit, o: {
     scopeOf: (grant: Grant) => HerdrScope;
     passThrough?: (method: string, grant: Grant) => boolean;
-    relay?: RelayClient;
+    relay?: Pick<RelayClient, 'notify'>;
 }): Pick<HostOptions, 'handle' | 'stream' | 'allow'>;
 export declare function serve(o: {
     host: Host;

package/dist/link.js

@@ -7,7 +7,7 @@
 import { createServer } from 'node:http';
 import { WebSocketServer } from 'ws';
 import { PublicLinkError, } from '@byokit/link';
-import { reach } from '@byokit/reach';
+import { reach } from '@byokit/discover';
 import { stateWords, words } from "./words.js";
 import { decodeB64Url, sealNotice } from "./notices.js";
 // Ops a view-role grant may open; every other op needs the control role (7.1, *view* marks).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/herdr",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Drive the Herdr on this computer — workspaces, tabs, panes, agents and blocked-approval answers — from an app, or hand it to a phone over @byokit/link.",
   "license": "Apache-2.0",
   "type": "module",
@@ -52,11 +52,11 @@
     "prepack": "tsc -b && node ../../scripts/fix-words-dts.cjs"
   },
   "dependencies": {
-    "@byokit/link": "0.7.0",
-    "@byokit/relay": "0.5.1",
-    "@byokit/reach": "0.6.0",
-    "@byokit/seal": "0.2.0",
-    "ws": "8.21.3"
+    "@byokit/link": "0.8.0",
+    "@byokit/relay": "0.6.0",
+    "@byokit/discover": "0.6.0",
+    "@byokit/seal": "0.3.0",
+    "ws": "8.22.0"
   },
   "publishConfig": {
     "access": "public"