workbite 0.1.19 → 0.1.21

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 };