workbite 0.1.22 → 0.1.24

package/README.md

@@ -3,16 +3,15 @@
 WorkBite installs and opens **Work Stack** (organizes the work) and
 **StackBite** (gets it moving) as one native suite.
 
-Launcher 0.1.22 has a **qualified Windows x64 and Linux x64 native candidate**;
-TypeScript TUI is 1.0.38. Both actual artifacts,
-`workbite-0.1.22-windows-x64.zip` and `workbite-0.1.22-linux-x64.tar.gz`,
-use build source `dd0e08d5d7d241177a482d4b8d1d92448b724a82`, tree
-`37ba32d6033c6e26612036d6f883ccbc0349d50b`. Their reviewed archive hashes,
-embedded bundle digests and sizes are sealed in `release.json` for intended tag
-`v0.1.22` in `Shinick-Han/WorkBite-releases`. Publication, registry acceptance,
-installation and live handover remain pending. The operator selected manual
-publication because hosted Actions quota is exhausted; no hosted CI or OIDC
-success is claimed and the existing CI publication helper is unchanged.
+Launcher 0.1.24 pins qualified Windows x64 and Linux x64 native archives.
+TypeScript TUI remains 1.0.38 and the embedded StackBite is 0.5.39.
+Both archives use build source `ba44d63cb89c9f979c236a2df6a7dcf73228a129`,
+tree `15c07e0d5de33440422210675855c73c8de8a0b9`. Their actual archive hashes,
+embedded bundle digests and sizes are sealed in `release.json` for `v0.1.24`
+in `Shinick-Han/WorkBite-releases`. Publication, registry delivery and installed
+runtime handover are separately verified maintainer operations. The maintainer
+uses the selected manual publication path because hosted Actions quota is
+exhausted; no hosted CI/OIDC success is claimed.
 It opens the familiar TypeScript Work Stack UI by default, which
 has one Tasks workbench: switch Focus/Table/Board without losing your selected
 Task, open its persistent Room's plain terminal, and control it beside or below
@@ -30,23 +29,22 @@ an explicit alternative per open: `workbite open --frontend rust` (or bare
 StackBite backend; the choice is not saved. Leaving the view or closing the UI
 keeps the agent running, and Task completion stays an explicit action.
 
-The 0.1.22 pair passed independent archive/runtime review: all 17 Windows probes,
+The 0.1.24 pair passed independent archive/runtime review: all 17 Windows probes,
 all 12 Linux ELF version-needs audits at GLIBC <= 2.28, and 29 AlmaLinux 8.10
-userspace probes. Both packaged TypeScript TUIs returned 1.0.38. Fresh source QA
-includes Windows arrow 364 pass / one existing QR skip and typecheck, Linux arrow
-70 pass, bounded backend/UX tests, and native Task Room client 19 / assembly 2 on
-each platform. Existing Windows-only/native opt-in skips remain explicit. All nine
-mandatory Linux frozen modules are present; two unwired libraries remain documented
-exclusions. Prior 0.1.21 artifacts do not qualify this pair.
-See the [0.1.22 release notes](../../docs/RELEASE-0.1.22.md) and
-[qualification record](../../docs/releases/0.1.22/README.md) for exact pins and limits.
-Configured disposable fake-connector Windows bridge hello returned interactive=true
-and wrote zero state files; blank-profile false is UNCONFIGURED. This is capability
-smoke, with no actual attach, native input or provider proof. Source fixtures and
-Alma8 bwrap userspace on WSL do not prove a booted AlmaLinux kernel, baseline CPU,
-SSH/VM, NFS or physical Phone behavior. Updating an existing native bundle requires
-an operator handover of existing backend processes; the launcher does not stop them
-or clear startup records automatically.
+userspace probes. Fresh bounded lifecycle source checks passed on Windows and
+Linux; Windows-only checks skipped on Linux remain explicit. These checks do
+not claim a real provider turn, interactive-screen acceptance, booted AlmaLinux,
+baseline CPU, SSH/VM, NFS or physical Phone behavior. Linux Phone is unsupported.
+See the [0.1.24 release notes](../../docs/RELEASE-0.1.24.md) and
+[qualification record](../../docs/releases/0.1.24/README.md) for pins and limits.
+
+The Rust frontend highlights the active Room and Seat with a background.
+Optional Claude/Codex lifecycle hooks add observed work status for CLIs started
+manually inside shell Seats. Stop means idle, never verified completion. Hook
+installation and an existing CLI's normal restart/resume may be required; Codex
+retains its normal hook trust review. Current owners and Seats remain on their
+existing runtime until a safe operator handover; updates do not stop them or
+clear unknown startup records automatically.
 
 The candidate keeps a stable Seat across explicit shell restarts, with a fresh
 generation and no inferred previous CLI/provider resume. Stop retains the Seat;
@@ -89,7 +87,7 @@ new one. A failure can leave the launcher installed without its suite: inspect
 `workbite check`. Never replay an unknown npm install without inspecting it.
 
 ```sh
-npm install -g workbite@0.1.22                             # only after registry publication and public-asset verification
+npm install -g workbite@0.1.24                             # only after registry publication and public-asset verification
 workbite install
 workbite open --workspace /abs/path/new-folder --init      # first time, once
 workbite                                                   # afterwards (TypeScript UI)
@@ -175,12 +173,12 @@ assignment refuses discovery. Standalone/unbound terminals retain the explicit
 workspace/context path. WorkBite does not enable MCP or configure providers
 automatically; source fixture checks do not prove an actual provider turn.
 
-The 0.1.22 candidate also repairs initial Task Room capability discovery and
+The candidate retains the repair for initial Task Room capability discovery and
 recovery notices after overlapping reads. Task Room inventory is filtered to
 the requested Task's Rooms before runtime inventory is read. Selecting a Task
 continues to create no Room, Seat or provider.
 
-The 0.1.22 candidate retains **Connect agent** in Task Execution (`a`),
+The candidate retains **Connect agent** in Task Execution (`a`),
 the global 9 Execution monitor and launch picker (`+`), clickable controls and
 scoped command palettes (`:`). Claude Code, Codex, Cursor and Grok Build use
 their official CLI login and credential storage. Missing CLIs offer install
@@ -202,7 +200,7 @@ Source checks used disposable fixtures, with no live account login, browser
 completion, account-entitlement proof or paid provider turn acceptance. See the
 [source acceptance record](../../docs/WORKBITE-AGENT-CONNECTION-ACCEPTANCE-2026-10-16.md).
 
-The Windows 0.1.22 candidate retains the read-only phone companion pilot from 0.1.14.
+The Windows candidate retains the read-only phone companion pilot from 0.1.14.
 Linux Phone support remains unsupported; paired releases do not imply identical
 platform capabilities.
 Phone actions preserve their selected target during status reads, show pending

package/bin/workbite.js

@@ -1,13 +1,13 @@
-#!/usr/bin/env node
-'use strict';
-const { main } = require('../lib/cli');
-main().then(({ code, signal }) => {
-  if (signal && process.platform !== 'win32') {
-    process.kill(process.pid, signal);
-  } else {
-    process.exitCode = code === null ? 1 : code;
-  }
-}).catch(error => {
-  console.error(`WorkBite: ${error.message}`);
-  process.exitCode = 1;
-});
+#!/usr/bin/env node
+'use strict';
+const { main } = require('../lib/cli');
+main().then(({ code, signal }) => {
+  if (signal && process.platform !== 'win32') {
+    process.kill(process.pid, signal);
+  } else {
+    process.exitCode = code === null ? 1 : code;
+  }
+}).catch(error => {
+  console.error(`WorkBite: ${error.message}`);
+  process.exitCode = 1;
+});

package/lib/agent.js

@@ -1,240 +1,240 @@
-'use strict';
-// WorkBite agent interface: binds one already-running, WorkBite-owned Work Stack
-// owner and forwards curated agent commands to it through the pinned native
-// client's v1 `cli.execute` RPC. The native client is the only mapper to the
-// owner's versioned APIs. Nothing here starts, downloads, initializes or adopts
-// an owner, falls back to another workspace or tool, or replays a write.
-const path = require('node:path');
-const { spawn } = require('node:child_process');
-const { randomBytes } = require('node:crypto');
-const { fail, exists, readSmall, sha256, UUID } = require('./common');
-const { cleanEnvironment, stateLayout, workspaceKey, readWorkspaceUid, rememberedWorkspace, engineIdentity } = require('./runtime');
-
-const OWNER_SCHEMA = 'workbite.owner.v2';
-const LOOPBACK = /^http:\/\/127\.0\.0\.1:([1-9][0-9]{0,4})$/;
-const LAUNCH = /^[0-9a-f]{16}$/;
-const MAX_PACKET_BYTES = 32768;
-const MAX_TRANSFER_BYTES = 1024 * 1024;
-const MAX_ARGV = 128;
-const MAX_STDOUT = 1024 * 1024 + 8192;
-const MAX_STDERR = 65536;
-const DEFAULT_DEADLINE = 30000;
-// Placeholder authority for the static capability table only; the client never contacts it for that command.
-const NO_ENDPOINT = 'http://127.0.0.1:9';
-const NO_UID = '00000000-0000-4000-8000-000000000000';
-
-// Curated command paths; every other native command (raw rpc, legacy, deploy, delete, migration) is refused.
-const AGENT_COMMANDS = Object.freeze(['capabilities', 'status', 'tasks list', 'tasks create', 'tasks update', 'context',
-  'checkpoint', 'operation-status', 'export', 'import', 'import-status', 'import-rollback']);
-const WRITE_COMMANDS = Object.freeze(['tasks create', 'tasks update', 'checkpoint', 'import', 'import-rollback']);
-const FORBIDDEN_FLAGS = new Set(['--data-dir', '--endpoint', '--token-env', '--token', '--workspace', '--read-retries',
-  '--timeout-ms', '--request-id', '--generation', '--packet-file']);
-
-const EXPLICIT = 'Name it with --workspace ABS --workspace-uid UUID, or open it once with: workbite open --workspace ABS';
-const bindings = new WeakMap();
-
-// Only the bound --workspace-uid (once, exactly that UID) may precede the command words.
-function commandOf(argv, uid) {
-  if (!Array.isArray(argv) || argv[0] !== 'agent') return null;
-  let start = 1;
-  if (typeof uid === 'string' && uid) {
-    if (argv[1] === '--workspace-uid' && argv[2] === uid) start = 3;
-    else if (argv[1] === `--workspace-uid=${uid}`) start = 2;
-  }
-  const words = [];
-  for (const item of argv.slice(start)) { if (item.startsWith('-')) break; words.push(item); }
-  const name = words.join(' ');
-  return AGENT_COMMANDS.includes(name) ? name : null;
-}
-function checkedArgv(argv, uid) {
-  if (!Array.isArray(argv) || !argv.length || argv.length > MAX_ARGV
-      || argv.some(item => typeof item !== 'string' || item.includes('\0'))
-      || argv.reduce((total, item) => total + Buffer.byteLength(item), 0) > MAX_PACKET_BYTES) fail('Invalid WorkBite agent arguments');
-  const command = commandOf(argv, uid);
-  if (!command) fail('Unsupported WorkBite agent command; supported: ' + AGENT_COMMANDS.join(', '));
-  argv.forEach((item, index) => {
-    const key = item.split('=')[0];
-    if (FORBIDDEN_FLAGS.has(key)) fail(`WorkBite agent commands do not accept ${key}; authority comes from the binding`);
-    if (key === '--workspace-uid') {
-      const value = item.includes('=') ? item.slice(item.indexOf('=') + 1) : argv[index + 1];
-      if (value !== uid) fail('--workspace-uid does not match the bound WorkBite workspace');
-    }
-  });
-  return command;
-}
-function checkedStdin(stdin, command) {
-  if (stdin === undefined || stdin === null) return null;
-  const maximum = command === 'import' ? MAX_TRANSFER_BYTES : MAX_PACKET_BYTES;
-  if (typeof stdin !== 'string' || Buffer.byteLength(stdin) > maximum || stdin.includes('\0') || stdin.isWellFormed?.() === false) {
-    fail(`WorkBite agent input must be UTF-8 text of at most ${maximum} bytes`);
-  }
-  return stdin;
-}
-// Capture recovery identity before launch; never reconstruct it from native error text.
-function checkedIntent(argv, command, write) {
-  const flags = argv.filter(item => item.split('=')[0] === '--intent-id');
-  if (!flags.length && !write) return null;
-  if (flags.length !== 1 || (!WRITE_COMMANDS.includes(command)
-      && !['operation-status', 'import-status'].includes(command)) || argv.includes('--')) {
-    fail('Invalid or repeated --intent-id');
-  }
-  const flag = flags[0];
-  const value = flag.includes('=') ? flag.slice(flag.indexOf('=') + 1) : argv[argv.indexOf(flag) + 1];
-  if (typeof value !== 'string' || (!flag.includes('=') && value.startsWith('--'))
-      || value.length < 8 || value.length > 128 || /[^A-Za-z0-9._:-]/.test(value)) fail('Invalid --intent-id');
-  return value;
-}
-function clientCommand(installed, commands) {
-  const command = commands?.workstack_client || [installed?.executables?.workstack_client];
-  if (!Array.isArray(command) || typeof command[0] !== 'string' || !path.isAbsolute(command[0])) {
-    fail('The verified WorkBite native client is not available; run workbite check.');
-  }
-  return command;
-}
-
-function explicitWorkspace(workspace, workspaceUid) {
-  if ((workspace === undefined) !== (workspaceUid === undefined)) fail('--workspace and --workspace-uid must be given together');
-  if (typeof workspace !== 'string' || !path.isAbsolute(workspace) || /[\x00-\x1f]/.test(workspace)
-      || (process.platform === 'win32' && /^[\\/](?![\\/])/.test(workspace))) fail('--workspace must be an absolute path');
-  if (typeof workspaceUid !== 'string' || !UUID.test(workspaceUid)) fail('--workspace-uid must be a canonical workspace UUID');
-  return { workspace: path.resolve(workspace), uid: workspaceUid };
-}
-// Only the saved selection (written after a fully proven open) names a default; never a guess.
-async function selectedWorkspace(layout) {
-  if (!await exists(layout.selection)) fail(`No WorkBite workspace is selected. ${EXPLICIT}`);
-  return rememberedWorkspace(layout);
-}
-
-async function ownerRecord(layout, workspace, uid) {
-  const file = path.join(layout.owners, `${workspaceKey(workspace)}.json`);
-  let bytes, record;
-  try { bytes = await readSmall(file, 65536); record = JSON.parse(bytes.toString('utf8')); } catch {
-    fail(`No ready WorkBite-owned Work Stack owner is recorded for ${workspace}. Start it with: workbite open --workspace ABS`);
-  }
-  const same = typeof record?.workspace === 'string' && path.isAbsolute(record.workspace)
-    && workspaceKey(path.resolve(record.workspace)) === workspaceKey(workspace);
-  if (record === null || typeof record !== 'object' || Array.isArray(record) || record.schema !== OWNER_SCHEMA
-      || record.state !== 'ready' || !same || record.workspace_uid !== uid || typeof record.launch !== 'string'
-      || !LAUNCH.test(record.launch) || typeof record.token !== 'string' || !/^[0-9a-f]{64}$/.test(record.token)
-      || typeof record.endpoint !== 'string' || !LOOPBACK.test(record.endpoint)) {
-    fail(`The Work Stack owner record for ${workspace} is not a ready WorkBite owner for that workspace UID. Open it with: workbite open --workspace ABS`);
-  }
-  return { file, digest: sha256(bytes), record };
-}
-async function proveOwner(layout, workspace, uid) {
-  if (await readWorkspaceUid(workspace) !== uid) fail(`The workspace.json id of ${workspace} does not match --workspace-uid`);
-  const owner = await ownerRecord(layout, workspace, uid);
-  if (!await engineIdentity(owner.record.endpoint, owner.record.token, uid)) {
-    fail(`The WorkBite Work Stack owner for ${workspace} could not be authenticated (stopped or replaced). Start it with: workbite open --workspace ABS`);
-  }
-  return owner;
-}
-
-async function bindAgent({ installed, stateRoot, environment = process.env, workspace, workspaceUid, commands, timeouts = {} } = {}) {
-  if (typeof stateRoot !== 'string' || !path.isAbsolute(stateRoot)) fail('WorkBite state directory must be an absolute path');
-  const layout = stateLayout(path.resolve(stateRoot));
-  const command = clientCommand(installed, commands);
-  const chosen = workspace === undefined && workspaceUid === undefined
-    ? await selectedWorkspace(layout) : explicitWorkspace(workspace, workspaceUid);
-  const owner = await proveOwner(layout, chosen.workspace, chosen.uid);
-  const binding = Object.freeze({ workspace: chosen.workspace, workspaceUid: chosen.uid, endpoint: owner.record.endpoint,
-    stateRoot: layout.root });
-  bindings.set(binding, Object.freeze({ layout, command, environment: { ...environment }, digest: owner.digest,
-    launch: owner.record.launch, deadline: timeouts.agent || DEFAULT_DEADLINE }));
-  return binding;
-}
-
-// The bound owner must be the very same proven generation for every call.
-async function recheck(binding, state) {
-  const owner = await proveOwner(state.layout, binding.workspace, binding.workspaceUid);
-  if (owner.digest !== state.digest || owner.record.launch !== state.launch || owner.record.endpoint !== binding.endpoint) {
-    fail('The bound WorkBite Work Stack owner changed since binding; bind again (nothing was sent).');
-  }
-}
-
-// JSON quoting retains the exact path without letting terminal controls become diagnostics.
-const diagnosticJson = value => JSON.stringify(value).replace(/[\x7f-\x9f\u2028-\u202e\u2066-\u2069]/g,
-  character => `\\u${character.charCodeAt(0).toString(16).padStart(4, '0')}`);
-// One request, one response, no retry. `write` decides how an uncertain outcome is reported.
-function rpc(command, { endpoint, uid, workspace, environment, argv, stdin, deadline, write, intent, name }) {
-  const requestId = `workbite-agent-${randomBytes(8).toString('hex')}`;
-  const request = JSON.stringify({ version: 1, request_id: requestId, workspace_uid: uid, generation: 0,
-    method: 'cli.execute', params: { argv, stdin } }) + '\n';
-  const nativeTimeout = Math.max(1000, Math.min(300000, deadline));
-  const [file, ...prefix] = command;
-  // cli.execute wraps escaped stdout in JSON; a bounded archive may expand at both layers.
-  const transfer = ['export', 'import', 'import-status', 'import-rollback'].includes(name);
-  const stdoutLimit = transfer ? 8 * MAX_TRANSFER_BYTES : MAX_STDOUT;
-  const lookup = transfer ? 'import-status' : 'operation-status';
-  const intentFlag = intent?.startsWith('--') ? `--intent-id=${intent}` : `--intent-id ${intent}`;
-  const uncertain = what => ({ code: 1, stdout: '', stderr: write
-    ? `error: commit unknown (${what}); WorkBite did not replay it. Check: workbite agent ${lookup} ${intentFlag}\n`
-      + `Use the same bound workspace: ${diagnosticJson({ workspace, workspace_uid: uid })}\n`
-    : `error: ${what}; nothing was retried\n`,
-    ...(write ? { meta: { command: `agent.${name.replace(/ /g, '.')}`, intent_id: intent, commit_state: 'unknown' },
-      workbite: { schema: 'workbite.agent.binding.v1', workspace, workspace_uid: uid } } : {}) });
-  return new Promise(resolve => {
-    let child;
-    try {
-      child = spawn(file, [...prefix, '--endpoint', endpoint, '--workspace-uid', uid, '--timeout-ms', String(nativeTimeout),
-        '--read-retries', '0', 'rpc'], { env: cleanEnvironment(environment), shell: false, windowsHide: true,
-        stdio: ['pipe', 'pipe', 'pipe'] });
-    } catch { resolve({ code: 1, stdout: '', stderr: 'error: cannot start the verified Work Stack native client\n' }); return; }
-    const out = [], err = [];
-    let outSize = 0, errSize = 0, done = false, overflow = false, started = false;
-    const finish = result => { if (!done) { done = true; clearTimeout(timer); resolve(result); } };
-    const timer = setTimeout(() => { child.kill(); finish(uncertain('native client deadline exceeded')); }, nativeTimeout + 5000);
-    child.stdout.on('data', chunk => {
-      outSize += chunk.length;
-      if (outSize > stdoutLimit) { overflow = true; child.kill(); } else out.push(chunk);
-    });
-    child.stderr.on('data', chunk => { errSize += chunk.length; if (errSize <= MAX_STDERR) err.push(chunk); });
-    child.stdin.on('error', () => {});
-    child.once('spawn', () => { started = true; });
-    child.once('error', () => finish(started ? uncertain('native client failed')
-      : { code: 1, stdout: '', stderr: 'error: cannot start the verified Work Stack native client\n' }));
-    child.once('close', () => {
-      if (overflow) { finish(uncertain('native response exceeded its bound')); return; }
-      const lines = Buffer.concat(out).toString('utf8').split('\n').filter(line => line.trim());
-      let response = null;
-      try { response = lines.length === 1 ? JSON.parse(lines[0]) : null; } catch { response = null; }
-      if (response === null || typeof response !== 'object' || response.version !== 1 || response.request_id !== requestId) {
-        finish(uncertain('no valid native response')); return;
-      }
-      if (response.error) {
-        const code = ['InvalidRequest', 'UnsupportedVersion', 'Unavailable', 'Timeout', 'Conflict', 'Unauthorized', 'Io', 'UnknownCommit']
-          .includes(response.error.code) ? response.error.code : 'Error';
-        if (code === 'UnknownCommit') { finish(uncertain('owner response was lost')); return; }
-        finish({ code: 1, stdout: '', stderr: `error: ${code}: native request failed\n` });
-        return;
-      }
-      const result = response.result;
-      if (result === null || typeof result !== 'object' || !Number.isInteger(result.exit_code)
-          || typeof result.stdout !== 'string' || typeof result.stderr !== 'string') { finish(uncertain('invalid native result')); return; }
-      finish({ code: result.exit_code, stdout: result.stdout, stderr: result.stderr });
-    });
-    child.stdin.end(request);
-  });
-}
-
-async function executeAgent(binding, argv, { stdin } = {}) {
-  const state = bindings.get(binding);
-  if (!state) fail('Not a WorkBite agent binding; use bindAgent');
-  const command = checkedArgv(argv, binding.workspaceUid);
-  const args = [...argv];
-  const input = checkedStdin(stdin, command);
-  const write = WRITE_COMMANDS.includes(command) && !(command === 'import' && args.includes('--dry-run'));
-  const intent = checkedIntent(args, command, write);
-  await recheck(binding, state);
-  return rpc(state.command, { endpoint: binding.endpoint, uid: binding.workspaceUid, workspace: binding.workspace,
-    environment: state.environment, argv: args, stdin: input, deadline: state.deadline, write, intent, name: command });
-}
-
-// The static capability table needs no workspace authority; it never reaches an owner.
-async function agentCapabilities({ installed, commands, environment = process.env, argv = ['agent', 'capabilities'], timeouts = {} } = {}) {
-  if (checkedArgv(argv, NO_UID) !== 'capabilities') fail('Only agent capabilities is authority-free');
-  return rpc(clientCommand(installed, commands), { endpoint: NO_ENDPOINT, uid: NO_UID, environment, argv: [...argv], stdin: null,
-    deadline: timeouts.agent || DEFAULT_DEADLINE, write: false, name: 'capabilities' });
-}
-
-module.exports = { bindAgent, executeAgent, agentCapabilities, AGENT_COMMANDS, WRITE_COMMANDS, MAX_PACKET_BYTES, MAX_TRANSFER_BYTES, commandOf };
+'use strict';
+// WorkBite agent interface: binds one already-running, WorkBite-owned Work Stack
+// owner and forwards curated agent commands to it through the pinned native
+// client's v1 `cli.execute` RPC. The native client is the only mapper to the
+// owner's versioned APIs. Nothing here starts, downloads, initializes or adopts
+// an owner, falls back to another workspace or tool, or replays a write.
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+const { randomBytes } = require('node:crypto');
+const { fail, exists, readSmall, sha256, UUID } = require('./common');
+const { cleanEnvironment, stateLayout, workspaceKey, readWorkspaceUid, rememberedWorkspace, engineIdentity } = require('./runtime');
+
+const OWNER_SCHEMA = 'workbite.owner.v2';
+const LOOPBACK = /^http:\/\/127\.0\.0\.1:([1-9][0-9]{0,4})$/;
+const LAUNCH = /^[0-9a-f]{16}$/;
+const MAX_PACKET_BYTES = 32768;
+const MAX_TRANSFER_BYTES = 1024 * 1024;
+const MAX_ARGV = 128;
+const MAX_STDOUT = 1024 * 1024 + 8192;
+const MAX_STDERR = 65536;
+const DEFAULT_DEADLINE = 30000;
+// Placeholder authority for the static capability table only; the client never contacts it for that command.
+const NO_ENDPOINT = 'http://127.0.0.1:9';
+const NO_UID = '00000000-0000-4000-8000-000000000000';
+
+// Curated command paths; every other native command (raw rpc, legacy, deploy, delete, migration) is refused.
+const AGENT_COMMANDS = Object.freeze(['capabilities', 'status', 'tasks list', 'tasks create', 'tasks update', 'context',
+  'checkpoint', 'operation-status', 'export', 'import', 'import-status', 'import-rollback']);
+const WRITE_COMMANDS = Object.freeze(['tasks create', 'tasks update', 'checkpoint', 'import', 'import-rollback']);
+const FORBIDDEN_FLAGS = new Set(['--data-dir', '--endpoint', '--token-env', '--token', '--workspace', '--read-retries',
+  '--timeout-ms', '--request-id', '--generation', '--packet-file']);
+
+const EXPLICIT = 'Name it with --workspace ABS --workspace-uid UUID, or open it once with: workbite open --workspace ABS';
+const bindings = new WeakMap();
+
+// Only the bound --workspace-uid (once, exactly that UID) may precede the command words.
+function commandOf(argv, uid) {
+  if (!Array.isArray(argv) || argv[0] !== 'agent') return null;
+  let start = 1;
+  if (typeof uid === 'string' && uid) {
+    if (argv[1] === '--workspace-uid' && argv[2] === uid) start = 3;
+    else if (argv[1] === `--workspace-uid=${uid}`) start = 2;
+  }
+  const words = [];
+  for (const item of argv.slice(start)) { if (item.startsWith('-')) break; words.push(item); }
+  const name = words.join(' ');
+  return AGENT_COMMANDS.includes(name) ? name : null;
+}
+function checkedArgv(argv, uid) {
+  if (!Array.isArray(argv) || !argv.length || argv.length > MAX_ARGV
+      || argv.some(item => typeof item !== 'string' || item.includes('\0'))
+      || argv.reduce((total, item) => total + Buffer.byteLength(item), 0) > MAX_PACKET_BYTES) fail('Invalid WorkBite agent arguments');
+  const command = commandOf(argv, uid);
+  if (!command) fail('Unsupported WorkBite agent command; supported: ' + AGENT_COMMANDS.join(', '));
+  argv.forEach((item, index) => {
+    const key = item.split('=')[0];
+    if (FORBIDDEN_FLAGS.has(key)) fail(`WorkBite agent commands do not accept ${key}; authority comes from the binding`);
+    if (key === '--workspace-uid') {
+      const value = item.includes('=') ? item.slice(item.indexOf('=') + 1) : argv[index + 1];
+      if (value !== uid) fail('--workspace-uid does not match the bound WorkBite workspace');
+    }
+  });
+  return command;
+}
+function checkedStdin(stdin, command) {
+  if (stdin === undefined || stdin === null) return null;
+  const maximum = command === 'import' ? MAX_TRANSFER_BYTES : MAX_PACKET_BYTES;
+  if (typeof stdin !== 'string' || Buffer.byteLength(stdin) > maximum || stdin.includes('\0') || stdin.isWellFormed?.() === false) {
+    fail(`WorkBite agent input must be UTF-8 text of at most ${maximum} bytes`);
+  }
+  return stdin;
+}
+// Capture recovery identity before launch; never reconstruct it from native error text.
+function checkedIntent(argv, command, write) {
+  const flags = argv.filter(item => item.split('=')[0] === '--intent-id');
+  if (!flags.length && !write) return null;
+  if (flags.length !== 1 || (!WRITE_COMMANDS.includes(command)
+      && !['operation-status', 'import-status'].includes(command)) || argv.includes('--')) {
+    fail('Invalid or repeated --intent-id');
+  }
+  const flag = flags[0];
+  const value = flag.includes('=') ? flag.slice(flag.indexOf('=') + 1) : argv[argv.indexOf(flag) + 1];
+  if (typeof value !== 'string' || (!flag.includes('=') && value.startsWith('--'))
+      || value.length < 8 || value.length > 128 || /[^A-Za-z0-9._:-]/.test(value)) fail('Invalid --intent-id');
+  return value;
+}
+function clientCommand(installed, commands) {
+  const command = commands?.workstack_client || [installed?.executables?.workstack_client];
+  if (!Array.isArray(command) || typeof command[0] !== 'string' || !path.isAbsolute(command[0])) {
+    fail('The verified WorkBite native client is not available; run workbite check.');
+  }
+  return command;
+}
+
+function explicitWorkspace(workspace, workspaceUid) {
+  if ((workspace === undefined) !== (workspaceUid === undefined)) fail('--workspace and --workspace-uid must be given together');
+  if (typeof workspace !== 'string' || !path.isAbsolute(workspace) || /[\x00-\x1f]/.test(workspace)
+      || (process.platform === 'win32' && /^[\\/](?![\\/])/.test(workspace))) fail('--workspace must be an absolute path');
+  if (typeof workspaceUid !== 'string' || !UUID.test(workspaceUid)) fail('--workspace-uid must be a canonical workspace UUID');
+  return { workspace: path.resolve(workspace), uid: workspaceUid };
+}
+// Only the saved selection (written after a fully proven open) names a default; never a guess.
+async function selectedWorkspace(layout) {
+  if (!await exists(layout.selection)) fail(`No WorkBite workspace is selected. ${EXPLICIT}`);
+  return rememberedWorkspace(layout);
+}
+
+async function ownerRecord(layout, workspace, uid) {
+  const file = path.join(layout.owners, `${workspaceKey(workspace)}.json`);
+  let bytes, record;
+  try { bytes = await readSmall(file, 65536); record = JSON.parse(bytes.toString('utf8')); } catch {
+    fail(`No ready WorkBite-owned Work Stack owner is recorded for ${workspace}. Start it with: workbite open --workspace ABS`);
+  }
+  const same = typeof record?.workspace === 'string' && path.isAbsolute(record.workspace)
+    && workspaceKey(path.resolve(record.workspace)) === workspaceKey(workspace);
+  if (record === null || typeof record !== 'object' || Array.isArray(record) || record.schema !== OWNER_SCHEMA
+      || record.state !== 'ready' || !same || record.workspace_uid !== uid || typeof record.launch !== 'string'
+      || !LAUNCH.test(record.launch) || typeof record.token !== 'string' || !/^[0-9a-f]{64}$/.test(record.token)
+      || typeof record.endpoint !== 'string' || !LOOPBACK.test(record.endpoint)) {
+    fail(`The Work Stack owner record for ${workspace} is not a ready WorkBite owner for that workspace UID. Open it with: workbite open --workspace ABS`);
+  }
+  return { file, digest: sha256(bytes), record };
+}
+async function proveOwner(layout, workspace, uid) {
+  if (await readWorkspaceUid(workspace) !== uid) fail(`The workspace.json id of ${workspace} does not match --workspace-uid`);
+  const owner = await ownerRecord(layout, workspace, uid);
+  if (!await engineIdentity(owner.record.endpoint, owner.record.token, uid)) {
+    fail(`The WorkBite Work Stack owner for ${workspace} could not be authenticated (stopped or replaced). Start it with: workbite open --workspace ABS`);
+  }
+  return owner;
+}
+
+async function bindAgent({ installed, stateRoot, environment = process.env, workspace, workspaceUid, commands, timeouts = {} } = {}) {
+  if (typeof stateRoot !== 'string' || !path.isAbsolute(stateRoot)) fail('WorkBite state directory must be an absolute path');
+  const layout = stateLayout(path.resolve(stateRoot));
+  const command = clientCommand(installed, commands);
+  const chosen = workspace === undefined && workspaceUid === undefined
+    ? await selectedWorkspace(layout) : explicitWorkspace(workspace, workspaceUid);
+  const owner = await proveOwner(layout, chosen.workspace, chosen.uid);
+  const binding = Object.freeze({ workspace: chosen.workspace, workspaceUid: chosen.uid, endpoint: owner.record.endpoint,
+    stateRoot: layout.root });
+  bindings.set(binding, Object.freeze({ layout, command, environment: { ...environment }, digest: owner.digest,
+    launch: owner.record.launch, deadline: timeouts.agent || DEFAULT_DEADLINE }));
+  return binding;
+}
+
+// The bound owner must be the very same proven generation for every call.
+async function recheck(binding, state) {
+  const owner = await proveOwner(state.layout, binding.workspace, binding.workspaceUid);
+  if (owner.digest !== state.digest || owner.record.launch !== state.launch || owner.record.endpoint !== binding.endpoint) {
+    fail('The bound WorkBite Work Stack owner changed since binding; bind again (nothing was sent).');
+  }
+}
+
+// JSON quoting retains the exact path without letting terminal controls become diagnostics.
+const diagnosticJson = value => JSON.stringify(value).replace(/[\x7f-\x9f\u2028-\u202e\u2066-\u2069]/g,
+  character => `\\u${character.charCodeAt(0).toString(16).padStart(4, '0')}`);
+// One request, one response, no retry. `write` decides how an uncertain outcome is reported.
+function rpc(command, { endpoint, uid, workspace, environment, argv, stdin, deadline, write, intent, name }) {
+  const requestId = `workbite-agent-${randomBytes(8).toString('hex')}`;
+  const request = JSON.stringify({ version: 1, request_id: requestId, workspace_uid: uid, generation: 0,
+    method: 'cli.execute', params: { argv, stdin } }) + '\n';
+  const nativeTimeout = Math.max(1000, Math.min(300000, deadline));
+  const [file, ...prefix] = command;
+  // cli.execute wraps escaped stdout in JSON; a bounded archive may expand at both layers.
+  const transfer = ['export', 'import', 'import-status', 'import-rollback'].includes(name);
+  const stdoutLimit = transfer ? 8 * MAX_TRANSFER_BYTES : MAX_STDOUT;
+  const lookup = transfer ? 'import-status' : 'operation-status';
+  const intentFlag = intent?.startsWith('--') ? `--intent-id=${intent}` : `--intent-id ${intent}`;
+  const uncertain = what => ({ code: 1, stdout: '', stderr: write
+    ? `error: commit unknown (${what}); WorkBite did not replay it. Check: workbite agent ${lookup} ${intentFlag}\n`
+      + `Use the same bound workspace: ${diagnosticJson({ workspace, workspace_uid: uid })}\n`
+    : `error: ${what}; nothing was retried\n`,
+    ...(write ? { meta: { command: `agent.${name.replace(/ /g, '.')}`, intent_id: intent, commit_state: 'unknown' },
+      workbite: { schema: 'workbite.agent.binding.v1', workspace, workspace_uid: uid } } : {}) });
+  return new Promise(resolve => {
+    let child;
+    try {
+      child = spawn(file, [...prefix, '--endpoint', endpoint, '--workspace-uid', uid, '--timeout-ms', String(nativeTimeout),
+        '--read-retries', '0', 'rpc'], { env: cleanEnvironment(environment), shell: false, windowsHide: true,
+        stdio: ['pipe', 'pipe', 'pipe'] });
+    } catch { resolve({ code: 1, stdout: '', stderr: 'error: cannot start the verified Work Stack native client\n' }); return; }
+    const out = [], err = [];
+    let outSize = 0, errSize = 0, done = false, overflow = false, started = false;
+    const finish = result => { if (!done) { done = true; clearTimeout(timer); resolve(result); } };
+    const timer = setTimeout(() => { child.kill(); finish(uncertain('native client deadline exceeded')); }, nativeTimeout + 5000);
+    child.stdout.on('data', chunk => {
+      outSize += chunk.length;
+      if (outSize > stdoutLimit) { overflow = true; child.kill(); } else out.push(chunk);
+    });
+    child.stderr.on('data', chunk => { errSize += chunk.length; if (errSize <= MAX_STDERR) err.push(chunk); });
+    child.stdin.on('error', () => {});
+    child.once('spawn', () => { started = true; });
+    child.once('error', () => finish(started ? uncertain('native client failed')
+      : { code: 1, stdout: '', stderr: 'error: cannot start the verified Work Stack native client\n' }));
+    child.once('close', () => {
+      if (overflow) { finish(uncertain('native response exceeded its bound')); return; }
+      const lines = Buffer.concat(out).toString('utf8').split('\n').filter(line => line.trim());
+      let response = null;
+      try { response = lines.length === 1 ? JSON.parse(lines[0]) : null; } catch { response = null; }
+      if (response === null || typeof response !== 'object' || response.version !== 1 || response.request_id !== requestId) {
+        finish(uncertain('no valid native response')); return;
+      }
+      if (response.error) {
+        const code = ['InvalidRequest', 'UnsupportedVersion', 'Unavailable', 'Timeout', 'Conflict', 'Unauthorized', 'Io', 'UnknownCommit']
+          .includes(response.error.code) ? response.error.code : 'Error';
+        if (code === 'UnknownCommit') { finish(uncertain('owner response was lost')); return; }
+        finish({ code: 1, stdout: '', stderr: `error: ${code}: native request failed\n` });
+        return;
+      }
+      const result = response.result;
+      if (result === null || typeof result !== 'object' || !Number.isInteger(result.exit_code)
+          || typeof result.stdout !== 'string' || typeof result.stderr !== 'string') { finish(uncertain('invalid native result')); return; }
+      finish({ code: result.exit_code, stdout: result.stdout, stderr: result.stderr });
+    });
+    child.stdin.end(request);
+  });
+}
+
+async function executeAgent(binding, argv, { stdin } = {}) {
+  const state = bindings.get(binding);
+  if (!state) fail('Not a WorkBite agent binding; use bindAgent');
+  const command = checkedArgv(argv, binding.workspaceUid);
+  const args = [...argv];
+  const input = checkedStdin(stdin, command);
+  const write = WRITE_COMMANDS.includes(command) && !(command === 'import' && args.includes('--dry-run'));
+  const intent = checkedIntent(args, command, write);
+  await recheck(binding, state);
+  return rpc(state.command, { endpoint: binding.endpoint, uid: binding.workspaceUid, workspace: binding.workspace,
+    environment: state.environment, argv: args, stdin: input, deadline: state.deadline, write, intent, name: command });
+}
+
+// The static capability table needs no workspace authority; it never reaches an owner.
+async function agentCapabilities({ installed, commands, environment = process.env, argv = ['agent', 'capabilities'], timeouts = {} } = {}) {
+  if (checkedArgv(argv, NO_UID) !== 'capabilities') fail('Only agent capabilities is authority-free');
+  return rpc(clientCommand(installed, commands), { endpoint: NO_ENDPOINT, uid: NO_UID, environment, argv: [...argv], stdin: null,
+    deadline: timeouts.agent || DEFAULT_DEADLINE, write: false, name: 'capabilities' });
+}
+
+module.exports = { bindAgent, executeAgent, agentCapabilities, AGENT_COMMANDS, WRITE_COMMANDS, MAX_PACKET_BYTES, MAX_TRANSFER_BYTES, commandOf };