@byokit/herdr 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## 0.5.0 (2026-10-01)
+
+- SECURITY: StartAgent and openSignInTab accept a clean launch environment with explicit unsets, verified before launch in idle shells on new or existing panes; credential values stay out of terminal commands, argv and errors, preventing inherited API key (billed per use) variables from overriding subscription sign-in.
+
 ## 0.4.1 (2026-10-01)
 
 - Dependency update: pins @byokit/relay 0.5.1.

package/README.md

@@ -391,3 +391,10 @@ package, never touches a person's other AI tools. Its tests run against a fake H
 ## License
 
 Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](../../NOTICE).
+
+`startAgent` and `openSignInTab` accept the accounts `launchEnv()` result as `env: launch`.
+The host and Herdr must share a filesystem. New panes and existing idle POSIX shells apply
+the settings and unsets through a private temporary file before launch; only the file path
+is sent to the terminal. Busy panes and unsupported shells fail closed. Legacy record env
+still travels on new-pane placement, and remains refused on existing panes. Credential
+values must never be supplied in agent args.

package/dist/agents.js

@@ -7,6 +7,7 @@ import { accessSync, constants as fsConstants, openSync, readSync, closeSync } f
 import { homedir } from 'node:os';
 import { delimiter, join } from 'node:path';
 import { words } from "./words.js";
+import { prepareLaunchEnv } from "./launch-env.js";
 const PROMPTABLE = ['idle', 'working', 'blocked', 'done'];
 const DEFAULT_TIMEOUT_MS = 60_000;
 // `agent.start` lands while the fresh pane is still at its shell prompt: the server answers
@@ -81,15 +82,19 @@ export function createAgents(ctx) {
         catch (error) {
             const reason = classifyStartFailure(error, { installExpected, stage });
             emit({ phase: 'launchFailed', kind: o.kind, reason, message: launchFailureWords(reason, o.kind) });
+            if (o.env && typeof o.env.env === 'object')
+                throw fail(codeOf(error) === 'env_mismatch' ? 'env_mismatch' : 'start_failed', words('agent.notReady'));
             throw error;
         }
     }
     async function startAgentInner(o, onStartPhase) {
-        if ('pane' in o.place && Object.keys(o.env ?? {}).length > 0) {
+        const launch = o.env && typeof o.env.env === 'object' && Array.isArray(o.env.unset)
+            ? o.env : undefined;
+        if (!launch && 'pane' in o.place && Object.keys(o.env ?? {}).length > 0) {
             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 ? {} : { env: o.env };
+        const env = o.env === undefined || launch ? {} : { env: o.env };
         let paneId;
         let created = false;
         if (o.worktree !== undefined) {
@@ -127,6 +132,20 @@ export function createAgents(ctx) {
         }
         if (paneId === undefined)
             throw new Error('herdr: the placement answered no pane id');
+        if (launch) {
+            try {
+                await prepareLaunchEnv(call, paneId, launch, timeout);
+            }
+            catch (error) {
+                if (created) {
+                    try {
+                        await call('pane.close', { pane_id: paneId });
+                    }
+                    catch { /* best effort */ }
+                }
+                throw error;
+            }
+        }
         onStartPhase?.();
         const name = agentName(o);
         const params = { pane_id: paneId, kind: o.kind, name,
@@ -148,6 +167,8 @@ export function createAgents(ctx) {
                     }
                     catch { /* rollback is best-effort */ }
                 }
+                if (launch)
+                    throw fail('start_failed', words('agent.notReady'));
                 throw error;
             }
         }

package/dist/launch-env.d.ts

@@ -0,0 +1,6 @@
+import type { Call } from './agents.ts';
+export type LaunchEnvironment = {
+    env: Record<string, string>;
+    unset: string[];
+};
+export declare function prepareLaunchEnv(call: Call, paneId: string, launch: LaunchEnvironment, timeout: number): Promise<void>;

package/dist/launch-env.js

@@ -0,0 +1,71 @@
+// The pinned agent.start launches through the pane shell. Values stay in a private host file,
+// never terminal text or argv. Only an idle POSIX shell may source it; preparation fails closed.
+import { randomBytes } from 'node:crypto';
+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+const quote = (v) => `'${v.replaceAll("'", "'\\''")}'`;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export async function prepareLaunchEnv(call, paneId, launch, timeout) {
+    let dir;
+    try {
+        if (!Number.isFinite(timeout) || timeout <= 0)
+            throw new Error();
+        const entries = Object.entries(launch.env);
+        const unset = [...launch.unset];
+        const names = [...entries.map(([key]) => key), ...unset];
+        if (names.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) => Object.hasOwn(launch.env, key)))
+            throw new Error();
+        const deadline = Date.now() + timeout;
+        // Do not send shell input to an agent or another foreground program.
+        for (;;) {
+            const result = await call('pane.process_info', { pane_id: paneId }, Math.max(1, deadline - Date.now()));
+            const info = result?.process_info;
+            if (info?.shell_pid && info.foreground_processes?.length === 1
+                && info.foreground_processes[0]?.pid === info.shell_pid
+                && /^(?:-)?(?:ba|z|da|k)?sh$/.test(info.foreground_processes[0].name))
+                break;
+            if (Date.now() >= deadline)
+                throw new Error();
+            await sleep(Math.min(100, Math.max(1, deadline - Date.now())));
+        }
+        const marker = `BYOKIT_ENV_${randomBytes(16).toString('hex')}`;
+        dir = mkdtempSync(join(tmpdir(), 'byokit-env-'));
+        const file = join(dir, 'prepare.sh');
+        const steps = [
+            'set +x +v',
+            // Remove exports absent from the clean result too: a pane may inherit more than the host.
+            // The pipeline is private; neither values nor variable listings reach the terminal.
+            `for BYOKIT_ENV_KEY in $(/usr/bin/env | /usr/bin/cut -d= -f1); do
+case "$BYOKIT_ENV_KEY" in ''|[!A-Za-z_]*|*[!A-Za-z0-9_]*) continue ;; esac
+case "$BYOKIT_ENV_KEY" in ${entries.length ? entries.map(([key]) => key).join('|') : 'BYOKIT_ENV_KEY'}) ;; *) unset "$BYOKIT_ENV_KEY" 2>/dev/null || return 1 ;; esac
+done`,
+            'unset BYOKIT_ENV_KEY',
+            ...unset.map((key) => `unset ${key}`),
+            ...entries.map(([key, value]) => `export ${key}=${quote(value)}`),
+            ...unset.map((key) => `test "\${${key}+present}" = ''`),
+            ...entries.map(([key, value]) => `test "\${${key}+present}" = present && test "$${key}" = ${quote(value)}`),
+            `printf '%s\\n' ${quote(marker)}`,
+        ];
+        writeFileSync(file, steps.join(' &&\n') + '\n', { mode: 0o600, flag: 'wx' });
+        await call('pane.send_text', { pane_id: paneId, text: `set +x +v; . ${quote(file)}\n` }, Math.max(1, deadline - Date.now()));
+        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()));
+            if (result?.read?.text?.split(/\r?\n/).some((line) => line.trim() === marker))
+                return;
+            if (Date.now() >= deadline)
+                throw new Error();
+            await sleep(Math.min(100, Math.max(1, deadline - Date.now())));
+        }
+    }
+    catch {
+        throw Object.assign(new Error('This pane could not use that sign-in.'), { code: 'env_mismatch' });
+    }
+    finally {
+        if (dir !== undefined)
+            rmSync(dir, { recursive: true, force: true });
+    }
+}

package/dist/testing/fake-herdr/server.js

@@ -2,6 +2,7 @@
 // request per connection — the server closes after answering; only `events.subscribe` is held open.
 // Ported from muxr `perf/fake-herdr/server.mjs` with the UI plugins, title churn, graphics and perf
 // byte rates removed.
+import { spawnSync } from 'node:child_process';
 import { mkdirSync, unlinkSync } from 'node:fs';
 import { createServer } from 'node:net';
 import { join } from 'node:path';
@@ -235,6 +236,28 @@ export async function startFakeHerdr(options) {
             emitEvent('tab.renamed', { tab_id: tab.tab_id, workspace_id: tab.workspace_id, label: tab.label });
             return { type: 'tab_info', tab: tabView(tab) };
         },
+        'pane.process_info': (p) => {
+            const pane = paneOf(p.pane_id);
+            const busy = live.agents.some((a) => a.pane_id === pane.pane_id);
+            return { process_info: { shell_pid: 1, foreground_processes: [{ pid: busy ? 2 : 1, name: busy ? 'agent' : 'sh' }] } };
+        },
+        'pane.send_text': (p) => {
+            const pane = paneOf(p.pane_id);
+            const text = String(p.text ?? '');
+            // A real offline shell exercises the private launch file, never a real agent CLI.
+            if (!/^set \+x \+v; \. '/.test(text))
+                throw fail('unsupported', 'unsupported fake shell command');
+            const r = spawnSync('/bin/sh', ['-c', text + "printf '\\0'; /usr/bin/env -0"], {
+                env: pane.env ?? { PATH: '/usr/bin:/bin', HOME: dir }, encoding: 'utf8', timeout: 5000,
+            });
+            const [output, ...environment] = r.stdout.split('\0');
+            pane.text.push(output);
+            pane.env = Object.fromEntries(environment.filter(Boolean).map((entry) => {
+                const i = entry.indexOf('=');
+                return [entry.slice(0, i), entry.slice(i + 1)];
+            }));
+            return {};
+        },
         'pane.get': (p) => ({ pane: paneView(paneOf(p.pane_id)) }),
         'pane.close': (p) => {
             const pane = paneOf(p.pane_id);

package/dist/types.d.ts

@@ -116,7 +116,10 @@ export type StartAgent = {
         base?: string;
     };
     args?: string[];
-    env?: Record<string, string>;
+    env?: Record<string, string> | {
+        env: Record<string, string>;
+        unset: string[];
+    };
     timeoutMs?: number;
     onEvent?: (e: AgentStartEvent) => void;
     installProbe?: AgentInstallProbe;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/herdr",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "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",