workbite 0.1.19 → 0.1.20

package/lib/cli.js

@@ -1,324 +1,334 @@
-'use strict';
-const path = require('node:path');
-const { fail, readSmall } = require('./common');
-const { locations, releaseSpec, ensureInstalled, stageReporter, packageVersion } = require('./install');
-const { openSuite, FRONTENDS } = require('./runtime');
-const { bindAgent, executeAgent, agentCapabilities, WRITE_COMMANDS, MAX_PACKET_BYTES } = require('./agent');
-const transfer = require('./transfer');
-
-const HELP = `WorkBite ${packageVersion} - Work Stack organizes the work. StackBite gets it moving.
-
-Usage:
-  workbite install                       download, verify and install the pinned native suite
-  workbite check                         verify the installed suite (no download, no processes)
-  workbite status [--json]               inspect startup records without starting anything
-  workbite doctor [--json]               explain startup evidence and its limits (read-only)
-  workbite recover --dry-run [--json]    print a recovery plan only; never changes state
-  workbite open --workspace ABS [--init] [--no-ui] [--frontend typescript|rust]
-                                         start or reuse this workspace's Work Stack owner and the
-                                         StackBite backend, then run the Work Stack terminal UI
-  workbite [open] [--no-ui] [--frontend typescript|rust]
-                                         reopen the last workspace WorkBite opened successfully
-  workbite agent [--workspace ABS --workspace-uid UUID] COMMAND [--input-file FILE | --stdin] [flags]
-                                         curated Work Stack agent commands against the running,
-                                         WorkBite-owned owner (never starts one): capabilities, status,
-                                         tasks list|create|update, context, checkpoint, operation-status,
-                                         export, import, import-status, import-rollback
-  workbite mcp [--workspace ABS --workspace-uid UUID]
-                                         WorkBite MCP server on stdio for the same agent commands
-  workbite --version | --help
-
-agent:
-  Reads use the last workspace WorkBite opened unless --workspace and --workspace-uid name one.
-  Writes (tasks create, tasks update, checkpoint) always need --workspace ABS --workspace-uid UUID
-  and a packet from --input-file FILE or --stdin (UTF-8, at most 32768 bytes). An uncertain write
-  is never replayed; check it with agent operation-status --intent-id ID.
-
-  Task transfer (archive at most 1 MiB; uses the running owner, never starts one):
-    workbite agent export --output tasks.json [--include-history] [--redact]
-    workbite agent import --input-file tasks.json --mode new --dry-run
-    workbite agent --workspace ABS --workspace-uid UUID import --input-file tasks.json --mode new
-      --intent-id ID --plan-digest sha256:HEX --expected-snapshot-digest sha256:HEX [--id-map map.json]
-    workbite agent import-status --intent-id ID
-    workbite agent --workspace ABS --workspace-uid UUID import-rollback --intent-id ID --import-id ID
-      --expected-snapshot-digest sha256:HEX
-  merge is also supported. --preserve-ids is explicit. Output files must be new local files.
-  Import unknowns require import-status with the SAME intent; no automatic replay or Task status changes.
-  Full workspace relocation uses official backup/restore.
-
-open:
-  --workspace ABS  absolute workspace folder; always wins over the remembered one
-  --init           create a new Work Stack workspace in a new or empty folder (needs --workspace)
-  --no-ui          start or reuse the backends, print one JSON summary and exit; does not prove UI works
-  --frontend NAME  typescript (default): the familiar Work Stack UI, with same-window 9 Execution
-                   on execution bundles; rust: the explicit alternative unified UI (execution
-                   bundles only). Chosen per open, never saved.
-
-First time, name the workspace once:
-  workbite open --workspace /abs/path/new-folder --init
-  workbite open --workspace /abs/path/existing-workspace
-Afterwards just run:
-  workbite
-
-The Work Stack owner and StackBite backend keep running after the UI exits, so
-agents continue. WorkBite never auto-updates, installs dependencies, approves
-provider trust or stops processes it cannot prove are its own.
-
-Locations (override with absolute WORKBITE_HOME / WORKBITE_STATE_DIR):
-  Windows  %LOCALAPPDATA%\\WorkBite\\app\\<version>   %LOCALAPPDATA%\\WorkBite\\state
-  Linux    $XDG_DATA_HOME/workbite/app/<version>  $XDG_STATE_HOME/workbite
-`;
-
-// Native flags each curated agent command accepts (value-taking unless listed in FLAGS_WITHOUT_VALUE).
-const AGENT_FLAGS = Object.freeze({
-  capabilities: ['--command', '--section'],
-  status: ['--workspace-revision'],
-  'tasks list': ['--status', '--limit', '--offset'],
-  'tasks create': ['--intent-id'],
-  'tasks update': ['--intent-id', '--task', '--expected-revision'],
-  context: ['--task', '--view', '--format', '--source', '--fingerprint', '--if-fingerprint'],
-  checkpoint: ['--intent-id'],
-  'operation-status': ['--intent-id'],
-  export: ['--include-history', '--redact'],
-  import: ['--mode', '--dry-run', '--preserve-ids', '--intent-id', '--plan-digest', '--expected-snapshot-digest'],
-  'import-status': ['--intent-id'],
-  'import-rollback': ['--intent-id', '--import-id', '--expected-snapshot-digest'],
-});
-const FLAGS_WITHOUT_VALUE = new Set(['--workspace-revision', '--fingerprint', '--include-history', '--redact', '--dry-run', '--preserve-ids']);
-const REPEATABLE = new Set(['--source']);
-const PACKET_COMMANDS = new Set(['tasks create', 'tasks update', 'checkpoint', 'import']);
-
-function parseBinding(options, argument, next) {
-  if (argument === '--workspace' && options.workspace === undefined && next !== undefined && !next.startsWith('--')) {
-    if (!path.isAbsolute(next)) fail('--workspace must be an absolute path');
-    options.workspace = next; return true;
-  }
-  if (argument === '--workspace-uid' && options.workspaceUid === undefined && next !== undefined && !next.startsWith('--')) {
-    options.workspaceUid = next; return true;
-  }
-  return false;
-}
-function pairedBinding(options) {
-  if ((options.workspace === undefined) !== (options.workspaceUid === undefined)) {
-    fail('--workspace and --workspace-uid must be given together');
-  }
-}
-
-function parseAgent(rest) {
-  // The binding pair may come before the command words, after them, or split around them;
-  // each flag is still accepted once, with its value, and nothing else may precede the words.
-  const options = { command: 'agent' };
-  while (rest.length && parseBinding(options, rest[0], rest[1])) rest.splice(0, 2);
-  if (rest.length && rest[0].startsWith('-')) {
-    fail(`Unknown or repeated agent option before the command: ${String(rest[0]).slice(0, 64)}. See workbite --help.`);
-  }
-  const words = [];
-  while (rest.length && !rest[0].startsWith('-')) words.push(rest.shift());
-  const name = words.join(' ');
-  if (!Object.hasOwn(AGENT_FLAGS, name)) {
-    fail(`Unknown agent command: ${name.slice(0, 64) || '(none)'}. Supported: ${Object.keys(AGENT_FLAGS).join(', ')}.`);
-  }
-  Object.assign(options, { name, native: ['agent', ...words] });
-  for (let index = 0; index < rest.length; index++) {
-    const argument = rest[index], next = rest[index + 1];
-    if (parseBinding(options, argument, next)) { index++; continue; }
-    if (((argument === '--output' && name === 'export' && options.output === undefined)
-        || (argument === '--id-map' && name === 'import' && options.idMap === undefined))
-        && next !== undefined && !next.startsWith('--')) {
-      options[argument === '--output' ? 'output' : 'idMap'] = next; index++; continue;
-    }
-    if (argument === '--input-file' && options.inputFile === undefined && !options.stdin && next !== undefined
-        && !next.startsWith('--')) { options.inputFile = next; index++; continue; }
-    if (argument === '--stdin' && !options.stdin && options.inputFile === undefined) { options.stdin = true; continue; }
-    if (!AGENT_FLAGS[name].includes(argument) || (!REPEATABLE.has(argument) && options.native.includes(argument))) {
-      fail(`Unknown or repeated agent ${name} option: ${String(argument).slice(0, 64)}. See workbite --help.`);
-    }
-    options.native.push(argument);
-    if (FLAGS_WITHOUT_VALUE.has(argument)) continue;
-    if (next === undefined || next.startsWith('--')) fail(`${argument} needs a value`);
-    options.native.push(next); index++;
-  }
-  pairedBinding(options);
-  const packet = options.stdin || options.inputFile !== undefined;
-  if (PACKET_COMMANDS.has(name) !== packet) {
-    fail(PACKET_COMMANDS.has(name) ? `agent ${name} needs a packet from --input-file FILE or --stdin`
-      : `agent ${name} does not take --input-file or --stdin`);
-  }
-  const value = flag => options.native[options.native.indexOf(flag) + 1];
-  const has = flag => options.native.includes(flag);
-  const dryRun = name === 'import' && has('--dry-run');
-  if (name === 'import') {
-    if (options.inputFile === undefined) fail('agent import requires --input-file FILE');
-    if (!has('--mode') || !['new', 'merge'].includes(value('--mode'))) fail('--mode must be new or merge');
-    const proofs = ['--intent-id', '--plan-digest', '--expected-snapshot-digest'];
-    if (dryRun && (proofs.some(has) || options.idMap !== undefined)) fail('Import preview does not accept write identity, proofs or --id-map');
-    if (!dryRun && proofs.some(flag => !has(flag))) fail('Import apply requires --intent-id, --plan-digest and --expected-snapshot-digest from preview');
-  }
-  if (['import-status', 'import-rollback'].includes(name) && !has('--intent-id')) fail(`agent ${name} requires --intent-id`);
-  if (name === 'import-rollback' && (!has('--import-id') || !has('--expected-snapshot-digest'))) fail('Import rollback requires --import-id and --expected-snapshot-digest');
-  for (const proof of ['--plan-digest', '--expected-snapshot-digest']) {
-    if (has(proof) && !transfer.DIGEST.test(value(proof))) fail(`${proof} must be sha256: followed by 64 lowercase hex digits`);
-  }
-  if (has('--intent-id') && name.startsWith('import') && !/^[A-Za-z0-9._:-]{8,128}$/.test(value('--intent-id'))) fail('Invalid transfer --intent-id');
-  if (WRITE_COMMANDS.includes(name) && !dryRun && options.workspace === undefined) {
-    fail(`agent ${name} changes Work Stack; name the workspace with --workspace ABS --workspace-uid UUID`);
-  }
-  if (packet) options.native.push('--stdin');
-  return options;
-}
-function parseMcp(rest) {
-  const options = { command: 'mcp' };
-  for (let index = 0; index < rest.length; index++) {
-    if (!parseBinding(options, rest[index], rest[index + 1])) {
-      fail(`Unknown or repeated mcp option: ${String(rest[index]).slice(0, 64)}. See workbite --help.`);
-    }
-    index++;
-  }
-  pairedBinding(options);
-  return options;
-}
-
-function parseArguments(argv) {
-  if (argv.length === 1 && ['--help', '-h', 'help'].includes(argv[0])) return { command: 'help' };
-  if (argv.length === 1 && ['--version', '-v', 'version'].includes(argv[0])) return { command: 'version' };
-  // Bare `workbite` (or only open options) means `workbite open`.
-  const [command, ...rest] = argv.length && !argv[0].startsWith('--') ? argv : ['open', ...argv];
-  if ((command === 'install' || command === 'check') && !rest.length) return { command };
-  if (['status', 'doctor', 'recover'].includes(command)) {
-    const options = { command, json: false, dryRun: false };
-    for (const argument of rest) {
-      if (argument === '--json' && !options.json) options.json = true;
-      else if (command === 'recover' && argument === '--dry-run' && !options.dryRun) options.dryRun = true;
-      else fail(`Unsupported or repeated ${command} option. See workbite --help.`);
-    }
-    if (command === 'recover' && !options.dryRun) fail('recover requires --dry-run; automatic repair is not supported.');
-    return options;
-  }
-  if (command === 'agent') return parseAgent([...rest]);
-  if (command === 'mcp') return parseMcp(rest);
-  if (command === 'open') {
-    const options = { command, init: false, ui: true };
-    for (let index = 0; index < rest.length; index++) {
-      const argument = rest[index];
-      if (argument === '--init' && !options.init) options.init = true;
-      else if (argument === '--no-ui' && options.ui) options.ui = false;
-      else if (argument === '--workspace' && options.workspace === undefined && rest[index + 1] !== undefined
-          && !rest[index + 1].startsWith('--')) options.workspace = rest[++index];
-      else if (argument === '--frontend' && options.frontend === undefined) {
-        const name = rest[++index];
-        if (!FRONTENDS.includes(name)) fail(`--frontend must be one of: ${FRONTENDS.join(', ')}`);
-        options.frontend = name;
-      }
-      else fail(`Unknown or repeated open option: ${String(argument).slice(0, 64)}. See workbite --help.`);
-    }
-    // Without --workspace the remembered workspace is reopened; --init never picks a folder by itself.
-    if (options.workspace === undefined) {
-      if (options.init) fail('--init needs --workspace ABS naming the new or empty folder');
-      return options;
-    }
-    if (!path.isAbsolute(options.workspace)) fail('--workspace must be an absolute path');
-    return options;
-  }
-  fail(`Unknown command: ${String(command).slice(0, 64)}. See workbite --help.`);
-}
-
-// A packet is bounded UTF-8 text handed to the native client as stdin; it never enters argv.
-function packetText(bytes) {
-  if (bytes.length > MAX_PACKET_BYTES) fail(`The agent packet exceeds ${MAX_PACKET_BYTES} bytes`);
-  try { return new TextDecoder('utf-8', { fatal: true }).decode(bytes); } catch { fail('The agent packet is not valid UTF-8'); }
-}
-async function readPacket(parsed, stdin) {
-  if (parsed.inputFile !== undefined) {
-    let bytes;
-    try { bytes = await readSmall(path.resolve(parsed.inputFile), MAX_PACKET_BYTES); } catch (error) {
-      fail(/oversized/.test(error.message) ? `The agent packet file is not a regular file of at most ${MAX_PACKET_BYTES} bytes`
-        : 'The agent packet file could not be read');
-    }
-    return packetText(bytes);
-  }
-  if (!parsed.stdin) return null;
-  const chunks = [];
-  let size = 0;
-  for await (const chunk of stdin) {
-    size += chunk.length;
-    if (size > MAX_PACKET_BYTES) fail(`The agent packet exceeds ${MAX_PACKET_BYTES} bytes`);
-    chunks.push(Buffer.from(chunk));
-  }
-  return packetText(Buffer.concat(chunks));
-}
-
-async function runAgent(parsed, { installed, stateRoot, environment, commands, timeouts, stdout, stderr, stdin }) {
-  let result, binding = null;
-  if (parsed.name === 'capabilities' && parsed.workspace === undefined) {
-    result = await agentCapabilities({ installed, commands, environment, argv: parsed.native, timeouts });
-  } else {
-    binding = await bindAgent({ installed, stateRoot, environment, workspace: parsed.workspace,
-      workspaceUid: parsed.workspaceUid, commands, timeouts });
-    if (parsed.output !== undefined) await transfer.outputPath(parsed.output);
-    if (parsed.idMap !== undefined) await transfer.outputPath(parsed.idMap);
-    const packet = parsed.name === 'import' ? await transfer.readArchive(parsed.inputFile) : await readPacket(parsed, stdin || process.stdin);
-    result = await executeAgent(binding, parsed.native, { stdin: packet });
-  }
-  let output = result.stdout;
-  if (result.code === 0 && (parsed.output !== undefined || parsed.idMap !== undefined)) {
-    try {
-      const intentIndex = parsed.native.indexOf('--intent-id');
-      const data = transfer.resultData(result, parsed.name, binding.workspaceUid,
-        intentIndex === -1 ? undefined : parsed.native[intentIndex + 1]);
-      if (parsed.output !== undefined) await transfer.writePrivate(parsed.output, transfer.archive(data, binding.workspaceUid));
-      if (parsed.idMap !== undefined) await transfer.writePrivate(parsed.idMap, transfer.idMap(data.id_map));
-    } catch (error) {
-      // Apply may already be committed: preserve its receipt and never replay for a local file failure.
-      if (output) stdout.write(output);
-      stderr.write(`error: transfer file output failed: ${error.message}. Native operation was not replayed; retain this response and use import-status for any write.\n`);
-      return { code: 1, signal: null };
-    }
-  }
-  if (parsed.name === 'status' && result.code === 0) {
-    try {
-      const document = JSON.parse(output);
-      if (document !== null && typeof document === 'object' && !Array.isArray(document)) {
-        document.workbite = { schema: 'workbite.agent.binding.v1', workspace: binding.workspace,
-          workspace_uid: binding.workspaceUid, endpoint: binding.endpoint, state: binding.stateRoot };
-        output = JSON.stringify(document) + '\n';
-      }
-    } catch { /* not JSON: passed through unchanged */ }
-  }
-  if (output) stdout.write(output);
-  if (result.stderr) stderr.write(result.stderr);
-  return { code: result.code, signal: null };
-}
-
-async function main(argv = process.argv.slice(2), options = {}) {
-  const stdout = options.stdout || process.stdout, stderr = options.stderr || process.stderr;
-  const parsed = parseArguments(argv);
-  if (parsed.command === 'help') { stdout.write(HELP); return { code: 0, signal: null }; }
-  if (parsed.command === 'version') { stdout.write(`workbite ${packageVersion}\n`); return { code: 0, signal: null }; }
-  const environment = options.environment || process.env;
-  const platform = options.platform || process.platform;
-  if (['status', 'doctor', 'recover'].includes(parsed.command)) {
-    return require('./diagnostics').runDiagnostics(parsed, { ...options, environment, platform, stdout });
-  }
-  const spec = releaseSpec(options.manifest || require('../release.json'), platform, options.arch || process.arch, options);
-  const where = locations(environment, platform);
-  // agent and mcp only use an already installed, verified suite: nothing is downloaded or started.
-  const installed = await ensureInstalled(spec, { ...options, apps: options.apps || where.apps,
-    checkOnly: ['check', 'agent', 'mcp'].includes(parsed.command), progress: options.progress || stageReporter(stderr) });
-  const stateRoot = options.stateRoot || where.state;
-  if (parsed.command === 'agent') return runAgent(parsed, { ...options, installed, stateRoot, environment, stdout, stderr });
-  if (parsed.command === 'mcp') {
-    return require('./mcp').runMcp({ installed, stateRoot, environment, workspace: parsed.workspace,
-      workspaceUid: parsed.workspaceUid, commands: options.commands, timeouts: options.timeouts,
-      stdin: options.stdin || process.stdin, stdout, stderr });
-  }
-  if (parsed.command === 'install' || parsed.command === 'check') {
-    stdout.write(JSON.stringify({ schema: 'workbite.install.v1', version: spec.version, target: spec.target,
-      home: installed.home, state: stateRoot }) + '\n');
-    return { code: 0, signal: null };
-  }
-  return openSuite({ installed, commands: options.commands, workspace: parsed.workspace, init: parsed.init, ui: parsed.ui,
-    frontend: parsed.frontend, stateRoot, environment, spawnImpl: options.spawnImpl, execImpl: options.execImpl, stdout, stderr, timeouts: options.timeouts,
-    mobileBootstrap: options.mobileBootstrap });
-}
-
-module.exports = { main, parseArguments, HELP };
+'use strict';
+const path = require('node:path');
+const { fail, readSmall } = require('./common');
+const { locations, releaseSpec, ensureInstalled, stageReporter, packageVersion } = require('./install');
+const { openSuite, FRONTENDS } = require('./runtime');
+const { bindAgent, executeAgent, agentCapabilities, WRITE_COMMANDS, MAX_PACKET_BYTES } = require('./agent');
+const transfer = require('./transfer');
+
+const HELP = `WorkBite ${packageVersion} - Work Stack organizes the work. StackBite gets it moving.
+
+Usage:
+  workbite install                       download, verify and install the pinned native suite
+  workbite update                        update the global npm launcher and stage its verified suite
+  workbite check                         verify the installed suite (no download, no processes)
+  workbite status [--json]               inspect startup records without starting anything
+  workbite doctor [--json]               explain startup evidence and its limits (read-only)
+  workbite recover --dry-run [--json]    print a recovery plan only; never changes state
+  workbite open --workspace ABS [--init] [--no-ui] [--frontend typescript|rust]
+                                         start or reuse this workspace's Work Stack owner and the
+                                         StackBite backend, then run the Work Stack terminal UI
+  workbite [open] [--no-ui] [--frontend typescript|rust]
+                                         reopen the last workspace WorkBite opened successfully
+  workbite agent [--workspace ABS --workspace-uid UUID] COMMAND [--input-file FILE | --stdin] [flags]
+                                         curated Work Stack agent commands against the running,
+                                         WorkBite-owned owner (never starts one): capabilities, status,
+                                         tasks list|create|update, context, checkpoint, operation-status,
+                                         export, import, import-status, import-rollback
+  workbite mcp [--workspace ABS --workspace-uid UUID]
+                                         WorkBite MCP server on stdio for the same agent commands
+  workbite --version | --help
+
+agent:
+  Reads use the last workspace WorkBite opened unless --workspace and --workspace-uid name one.
+  Writes (tasks create, tasks update, checkpoint) always need --workspace ABS --workspace-uid UUID
+  and a packet from --input-file FILE or --stdin (UTF-8, at most 32768 bytes). An uncertain write
+  is never replayed; check it with agent operation-status --intent-id ID.
+
+  Task transfer (archive at most 1 MiB; uses the running owner, never starts one):
+    workbite agent export --output tasks.json [--include-history] [--redact]
+    workbite agent import --input-file tasks.json --mode new --dry-run
+    workbite agent --workspace ABS --workspace-uid UUID import --input-file tasks.json --mode new
+      --intent-id ID --plan-digest sha256:HEX --expected-snapshot-digest sha256:HEX [--id-map map.json]
+    workbite agent import-status --intent-id ID
+    workbite agent --workspace ABS --workspace-uid UUID import-rollback --intent-id ID --import-id ID
+      --expected-snapshot-digest sha256:HEX
+  merge is also supported. --preserve-ids is explicit. Output files must be new local files.
+  Import unknowns require import-status with the SAME intent; no automatic replay or Task status changes.
+  Full workspace relocation uses official backup/restore.
+
+open:
+  --workspace ABS  absolute workspace folder; always wins over the remembered one
+  --init           create a new Work Stack workspace in a new or empty folder (needs --workspace)
+  --no-ui          start or reuse the backends, print one JSON summary and exit; does not prove UI works
+  --frontend NAME  typescript (default): the familiar Work Stack UI, with same-window 9 Execution
+                   on execution bundles; rust: the explicit alternative unified UI (execution
+                   bundles only). Chosen per open, never saved.
+
+update:
+  Uses official npm latest; global installs only (local/npx copies are never replaced).
+  Does not switch or stop running owners, Seats or Phone. Inspect workbite status
+  --json and workbite doctor --json; ask your operator for handover before opening
+  the new runtime. Closing the UI leaves backends and agents running.
+
+First time, name the workspace once:
+  workbite open --workspace /abs/path/new-folder --init
+  workbite open --workspace /abs/path/existing-workspace
+Afterwards just run:
+  workbite
+
+The Work Stack owner and StackBite backend keep running after the UI exits, so
+agents continue. WorkBite never auto-updates, installs dependencies, approves
+provider trust or stops processes it cannot prove are its own.
+
+Locations (override with absolute WORKBITE_HOME / WORKBITE_STATE_DIR):
+  Windows  %LOCALAPPDATA%\\WorkBite\\app\\<version>   %LOCALAPPDATA%\\WorkBite\\state
+  Linux    $XDG_DATA_HOME/workbite/app/<version>  $XDG_STATE_HOME/workbite
+`;
+
+// Native flags each curated agent command accepts (value-taking unless listed in FLAGS_WITHOUT_VALUE).
+const AGENT_FLAGS = Object.freeze({
+  capabilities: ['--command', '--section'],
+  status: ['--workspace-revision'],
+  'tasks list': ['--status', '--limit', '--offset'],
+  'tasks create': ['--intent-id'],
+  'tasks update': ['--intent-id', '--task', '--expected-revision'],
+  context: ['--task', '--view', '--format', '--source', '--fingerprint', '--if-fingerprint'],
+  checkpoint: ['--intent-id'],
+  'operation-status': ['--intent-id'],
+  export: ['--include-history', '--redact'],
+  import: ['--mode', '--dry-run', '--preserve-ids', '--intent-id', '--plan-digest', '--expected-snapshot-digest'],
+  'import-status': ['--intent-id'],
+  'import-rollback': ['--intent-id', '--import-id', '--expected-snapshot-digest'],
+});
+const FLAGS_WITHOUT_VALUE = new Set(['--workspace-revision', '--fingerprint', '--include-history', '--redact', '--dry-run', '--preserve-ids']);
+const REPEATABLE = new Set(['--source']);
+const PACKET_COMMANDS = new Set(['tasks create', 'tasks update', 'checkpoint', 'import']);
+
+function parseBinding(options, argument, next) {
+  if (argument === '--workspace' && options.workspace === undefined && next !== undefined && !next.startsWith('--')) {
+    if (!path.isAbsolute(next)) fail('--workspace must be an absolute path');
+    options.workspace = next; return true;
+  }
+  if (argument === '--workspace-uid' && options.workspaceUid === undefined && next !== undefined && !next.startsWith('--')) {
+    options.workspaceUid = next; return true;
+  }
+  return false;
+}
+function pairedBinding(options) {
+  if ((options.workspace === undefined) !== (options.workspaceUid === undefined)) {
+    fail('--workspace and --workspace-uid must be given together');
+  }
+}
+
+function parseAgent(rest) {
+  // The binding pair may come before the command words, after them, or split around them;
+  // each flag is still accepted once, with its value, and nothing else may precede the words.
+  const options = { command: 'agent' };
+  while (rest.length && parseBinding(options, rest[0], rest[1])) rest.splice(0, 2);
+  if (rest.length && rest[0].startsWith('-')) {
+    fail(`Unknown or repeated agent option before the command: ${String(rest[0]).slice(0, 64)}. See workbite --help.`);
+  }
+  const words = [];
+  while (rest.length && !rest[0].startsWith('-')) words.push(rest.shift());
+  const name = words.join(' ');
+  if (!Object.hasOwn(AGENT_FLAGS, name)) {
+    fail(`Unknown agent command: ${name.slice(0, 64) || '(none)'}. Supported: ${Object.keys(AGENT_FLAGS).join(', ')}.`);
+  }
+  Object.assign(options, { name, native: ['agent', ...words] });
+  for (let index = 0; index < rest.length; index++) {
+    const argument = rest[index], next = rest[index + 1];
+    if (parseBinding(options, argument, next)) { index++; continue; }
+    if (((argument === '--output' && name === 'export' && options.output === undefined)
+        || (argument === '--id-map' && name === 'import' && options.idMap === undefined))
+        && next !== undefined && !next.startsWith('--')) {
+      options[argument === '--output' ? 'output' : 'idMap'] = next; index++; continue;
+    }
+    if (argument === '--input-file' && options.inputFile === undefined && !options.stdin && next !== undefined
+        && !next.startsWith('--')) { options.inputFile = next; index++; continue; }
+    if (argument === '--stdin' && !options.stdin && options.inputFile === undefined) { options.stdin = true; continue; }
+    if (!AGENT_FLAGS[name].includes(argument) || (!REPEATABLE.has(argument) && options.native.includes(argument))) {
+      fail(`Unknown or repeated agent ${name} option: ${String(argument).slice(0, 64)}. See workbite --help.`);
+    }
+    options.native.push(argument);
+    if (FLAGS_WITHOUT_VALUE.has(argument)) continue;
+    if (next === undefined || next.startsWith('--')) fail(`${argument} needs a value`);
+    options.native.push(next); index++;
+  }
+  pairedBinding(options);
+  const packet = options.stdin || options.inputFile !== undefined;
+  if (PACKET_COMMANDS.has(name) !== packet) {
+    fail(PACKET_COMMANDS.has(name) ? `agent ${name} needs a packet from --input-file FILE or --stdin`
+      : `agent ${name} does not take --input-file or --stdin`);
+  }
+  const value = flag => options.native[options.native.indexOf(flag) + 1];
+  const has = flag => options.native.includes(flag);
+  const dryRun = name === 'import' && has('--dry-run');
+  if (name === 'import') {
+    if (options.inputFile === undefined) fail('agent import requires --input-file FILE');
+    if (!has('--mode') || !['new', 'merge'].includes(value('--mode'))) fail('--mode must be new or merge');
+    const proofs = ['--intent-id', '--plan-digest', '--expected-snapshot-digest'];
+    if (dryRun && (proofs.some(has) || options.idMap !== undefined)) fail('Import preview does not accept write identity, proofs or --id-map');
+    if (!dryRun && proofs.some(flag => !has(flag))) fail('Import apply requires --intent-id, --plan-digest and --expected-snapshot-digest from preview');
+  }
+  if (['import-status', 'import-rollback'].includes(name) && !has('--intent-id')) fail(`agent ${name} requires --intent-id`);
+  if (name === 'import-rollback' && (!has('--import-id') || !has('--expected-snapshot-digest'))) fail('Import rollback requires --import-id and --expected-snapshot-digest');
+  for (const proof of ['--plan-digest', '--expected-snapshot-digest']) {
+    if (has(proof) && !transfer.DIGEST.test(value(proof))) fail(`${proof} must be sha256: followed by 64 lowercase hex digits`);
+  }
+  if (has('--intent-id') && name.startsWith('import') && !/^[A-Za-z0-9._:-]{8,128}$/.test(value('--intent-id'))) fail('Invalid transfer --intent-id');
+  if (WRITE_COMMANDS.includes(name) && !dryRun && options.workspace === undefined) {
+    fail(`agent ${name} changes Work Stack; name the workspace with --workspace ABS --workspace-uid UUID`);
+  }
+  if (packet) options.native.push('--stdin');
+  return options;
+}
+function parseMcp(rest) {
+  const options = { command: 'mcp' };
+  for (let index = 0; index < rest.length; index++) {
+    if (!parseBinding(options, rest[index], rest[index + 1])) {
+      fail(`Unknown or repeated mcp option: ${String(rest[index]).slice(0, 64)}. See workbite --help.`);
+    }
+    index++;
+  }
+  pairedBinding(options);
+  return options;
+}
+
+function parseArguments(argv) {
+  if (argv.length === 1 && ['--help', '-h', 'help'].includes(argv[0])) return { command: 'help' };
+  if (argv.length === 1 && ['--version', '-v', 'version'].includes(argv[0])) return { command: 'version' };
+  // Bare `workbite` (or only open options) means `workbite open`.
+  const [command, ...rest] = argv.length && !argv[0].startsWith('--') ? argv : ['open', ...argv];
+  if (['install', 'check', 'update'].includes(command) && !rest.length) return { command };
+  if (['status', 'doctor', 'recover'].includes(command)) {
+    const options = { command, json: false, dryRun: false };
+    for (const argument of rest) {
+      if (argument === '--json' && !options.json) options.json = true;
+      else if (command === 'recover' && argument === '--dry-run' && !options.dryRun) options.dryRun = true;
+      else fail(`Unsupported or repeated ${command} option. See workbite --help.`);
+    }
+    if (command === 'recover' && !options.dryRun) fail('recover requires --dry-run; automatic repair is not supported.');
+    return options;
+  }
+  if (command === 'agent') return parseAgent([...rest]);
+  if (command === 'mcp') return parseMcp(rest);
+  if (command === 'open') {
+    const options = { command, init: false, ui: true };
+    for (let index = 0; index < rest.length; index++) {
+      const argument = rest[index];
+      if (argument === '--init' && !options.init) options.init = true;
+      else if (argument === '--no-ui' && options.ui) options.ui = false;
+      else if (argument === '--workspace' && options.workspace === undefined && rest[index + 1] !== undefined
+          && !rest[index + 1].startsWith('--')) options.workspace = rest[++index];
+      else if (argument === '--frontend' && options.frontend === undefined) {
+        const name = rest[++index];
+        if (!FRONTENDS.includes(name)) fail(`--frontend must be one of: ${FRONTENDS.join(', ')}`);
+        options.frontend = name;
+      }
+      else fail(`Unknown or repeated open option: ${String(argument).slice(0, 64)}. See workbite --help.`);
+    }
+    // Without --workspace the remembered workspace is reopened; --init never picks a folder by itself.
+    if (options.workspace === undefined) {
+      if (options.init) fail('--init needs --workspace ABS naming the new or empty folder');
+      return options;
+    }
+    if (!path.isAbsolute(options.workspace)) fail('--workspace must be an absolute path');
+    return options;
+  }
+  fail(`Unknown command: ${String(command).slice(0, 64)}. See workbite --help.`);
+}
+
+// A packet is bounded UTF-8 text handed to the native client as stdin; it never enters argv.
+function packetText(bytes) {
+  if (bytes.length > MAX_PACKET_BYTES) fail(`The agent packet exceeds ${MAX_PACKET_BYTES} bytes`);
+  try { return new TextDecoder('utf-8', { fatal: true }).decode(bytes); } catch { fail('The agent packet is not valid UTF-8'); }
+}
+async function readPacket(parsed, stdin) {
+  if (parsed.inputFile !== undefined) {
+    let bytes;
+    try { bytes = await readSmall(path.resolve(parsed.inputFile), MAX_PACKET_BYTES); } catch (error) {
+      fail(/oversized/.test(error.message) ? `The agent packet file is not a regular file of at most ${MAX_PACKET_BYTES} bytes`
+        : 'The agent packet file could not be read');
+    }
+    return packetText(bytes);
+  }
+  if (!parsed.stdin) return null;
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of stdin) {
+    size += chunk.length;
+    if (size > MAX_PACKET_BYTES) fail(`The agent packet exceeds ${MAX_PACKET_BYTES} bytes`);
+    chunks.push(Buffer.from(chunk));
+  }
+  return packetText(Buffer.concat(chunks));
+}
+
+async function runAgent(parsed, { installed, stateRoot, environment, commands, timeouts, stdout, stderr, stdin }) {
+  let result, binding = null;
+  if (parsed.name === 'capabilities' && parsed.workspace === undefined) {
+    result = await agentCapabilities({ installed, commands, environment, argv: parsed.native, timeouts });
+  } else {
+    binding = await bindAgent({ installed, stateRoot, environment, workspace: parsed.workspace,
+      workspaceUid: parsed.workspaceUid, commands, timeouts });
+    if (parsed.output !== undefined) await transfer.outputPath(parsed.output);
+    if (parsed.idMap !== undefined) await transfer.outputPath(parsed.idMap);
+    const packet = parsed.name === 'import' ? await transfer.readArchive(parsed.inputFile) : await readPacket(parsed, stdin || process.stdin);
+    result = await executeAgent(binding, parsed.native, { stdin: packet });
+  }
+  let output = result.stdout;
+  if (result.code === 0 && (parsed.output !== undefined || parsed.idMap !== undefined)) {
+    try {
+      const intentIndex = parsed.native.indexOf('--intent-id');
+      const data = transfer.resultData(result, parsed.name, binding.workspaceUid,
+        intentIndex === -1 ? undefined : parsed.native[intentIndex + 1]);
+      if (parsed.output !== undefined) await transfer.writePrivate(parsed.output, transfer.archive(data, binding.workspaceUid));
+      if (parsed.idMap !== undefined) await transfer.writePrivate(parsed.idMap, transfer.idMap(data.id_map));
+    } catch (error) {
+      // Apply may already be committed: preserve its receipt and never replay for a local file failure.
+      if (output) stdout.write(output);
+      stderr.write(`error: transfer file output failed: ${error.message}. Native operation was not replayed; retain this response and use import-status for any write.\n`);
+      return { code: 1, signal: null };
+    }
+  }
+  if (parsed.name === 'status' && result.code === 0) {
+    try {
+      const document = JSON.parse(output);
+      if (document !== null && typeof document === 'object' && !Array.isArray(document)) {
+        document.workbite = { schema: 'workbite.agent.binding.v1', workspace: binding.workspace,
+          workspace_uid: binding.workspaceUid, endpoint: binding.endpoint, state: binding.stateRoot };
+        output = JSON.stringify(document) + '\n';
+      }
+    } catch { /* not JSON: passed through unchanged */ }
+  }
+  if (output) stdout.write(output);
+  if (result.stderr) stderr.write(result.stderr);
+  return { code: result.code, signal: null };
+}
+
+async function main(argv = process.argv.slice(2), options = {}) {
+  const stdout = options.stdout || process.stdout, stderr = options.stderr || process.stderr;
+  const parsed = parseArguments(argv);
+  if (parsed.command === 'help') { stdout.write(HELP); return { code: 0, signal: null }; }
+  if (parsed.command === 'version') { stdout.write(`workbite ${packageVersion}\n`); return { code: 0, signal: null }; }
+  const environment = options.environment || process.env;
+  const platform = options.platform || process.platform;
+  if (parsed.command === 'update') {
+    return require('./update').runUpdate({ ...options, environment, platform, stdout, stderr });
+  }
+  if (['status', 'doctor', 'recover'].includes(parsed.command)) {
+    return require('./diagnostics').runDiagnostics(parsed, { ...options, environment, platform, stdout });
+  }
+  const spec = releaseSpec(options.manifest || require('../release.json'), platform, options.arch || process.arch, options);
+  const where = locations(environment, platform);
+  // agent and mcp only use an already installed, verified suite: nothing is downloaded or started.
+  const installed = await ensureInstalled(spec, { ...options, apps: options.apps || where.apps,
+    checkOnly: ['check', 'agent', 'mcp'].includes(parsed.command), progress: options.progress || stageReporter(stderr) });
+  const stateRoot = options.stateRoot || where.state;
+  if (parsed.command === 'agent') return runAgent(parsed, { ...options, installed, stateRoot, environment, stdout, stderr });
+  if (parsed.command === 'mcp') {
+    return require('./mcp').runMcp({ installed, stateRoot, environment, workspace: parsed.workspace,
+      workspaceUid: parsed.workspaceUid, commands: options.commands, timeouts: options.timeouts,
+      stdin: options.stdin || process.stdin, stdout, stderr });
+  }
+  if (parsed.command === 'install' || parsed.command === 'check') {
+    stdout.write(JSON.stringify({ schema: 'workbite.install.v1', version: spec.version, target: spec.target,
+      home: installed.home, state: stateRoot }) + '\n');
+    return { code: 0, signal: null };
+  }
+  return openSuite({ installed, commands: options.commands, workspace: parsed.workspace, init: parsed.init, ui: parsed.ui,
+    frontend: parsed.frontend, stateRoot, environment, spawnImpl: options.spawnImpl, execImpl: options.execImpl, stdout, stderr, timeouts: options.timeouts,
+    mobileBootstrap: options.mobileBootstrap });
+}
+
+module.exports = { main, parseArguments, HELP };