workbite 0.1.12 → 0.1.13

package/README.md

@@ -37,7 +37,8 @@ Node.js 20+ on Windows x64 or Linux x64 (glibc 2.28+).
   `github.com/Shinick-Han/WorkBite-releases`, verifies its size and SHA-256 and
   every file listed in its `bundle.json`, and installs it into an immutable
   per-user version folder. No auto-update, no install scripts, no dependencies.
-- `workbite check` re-verifies the installed bundle without downloading.
+- `workbite check` re-verifies installed bundle integrity without downloading;
+  it does not test backend health, workspace admission or UI behavior.
 - `workbite open --workspace ABS [--init] [--no-ui] [--frontend typescript|rust]`
   starts or reuses the workspace's Work Stack owner and a StackBite backend
   (only processes it can prove it started), then runs the TypeScript Work Stack
@@ -52,10 +53,13 @@ Node.js 20+ on Windows x64 or Linux x64 (glibc 2.28+).
 - Each backend's startup record (private token, launch id, port) is saved in
   the state folder *before* the process is started. A later `open` reuses
   that same attempt once it authenticates (also after a slow start), and
-  otherwise refuses: an unreadable, invalid or unreachable record is never
-  cleared, replaced or followed by a second backend, and nothing is stopped.
-  If a refusal names a record and you have confirmed no WorkBite process for
-  that state is running, move that record aside and open again.
+  otherwise refuses. Unreadable/invalid records remain untouched; an
+  unreachable process is not assumed stopped. The unreleased source's narrow
+  archival path requires trusted same-host previous-boot evidence for eligible
+  owner/backend records. It does not resolve foreign hosts or native intents.
+  Diagnose the exact host/boot, workspace, backend and native intent before
+  operator handover. Age or a missing local PID cannot establish that a process
+  on another NFS client has stopped; preserve uncertain records.
 
 WorkBite keeps its own state (`%LOCALAPPDATA%\WorkBite` on Windows,
 `~/.local/share/workbite` and `~/.local/state/workbite` on Linux; override
@@ -63,6 +67,26 @@ with absolute `WORKBITE_HOME` / `WORKBITE_STATE_DIR`) and never touches
 separately installed Work Stack or StackBite apps, their state or ports. It
 never approves provider trust or starts paid agents by itself.
 
+Startup diagnostics in the **unreleased source** add `workbite status [--json]`,
+`workbite doctor [--json]` and `workbite recover --dry-run [--json]`. Check your
+installed launcher's `--help` before using them. They inspect evidence and plan
+only: no process starts/stops, record reset, native intent repair or migration.
+`open --no-ui` does start/reuse the backend stack (including native selection for
+v2) and prints JSON, but never launches or validates the foreground UI. Startup
+stage messages distinguish that UI launch from backend readiness; the launcher
+continues waiting while the UI runs. Full installed-file hashing still occurs
+on reuse, so these changes do not promise faster opens.
+
+For NFS shared homes, configure the existing absolute `WORKBITE_STATE_DIR`
+override to a distinct host-local runtime directory per host after coordinating
+any existing owners and active Seats. This does not move old state or permit
+parallel writers to one shared workspace. `WORKBITE_HOME` separately overrides
+the installation root (`app/` beneath it); changing it is not a universal tar
+fix. See the source repository's
+[startup troubleshooting guide](../../docs/STARTUP-TROUBLESHOOTING.md) for tcsh
+`setenv` examples, failure diagnosis, bounded tar stderr and safe handover
+requirements. Keep workspace locks and unknown native intents intact.
+
 Coding agents read and record Tasks of a workspace whose owner `workbite open`
 already runs; nothing is started for them:
 

package/lib/agent.js

@@ -14,6 +14,7 @@ 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;
@@ -24,8 +25,8 @@ 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']);
-const WRITE_COMMANDS = Object.freeze(['tasks create', 'tasks update', 'checkpoint']);
+  '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']);
 
@@ -61,13 +62,28 @@ function checkedArgv(argv, uid) {
   });
   return command;
 }
-function checkedStdin(stdin) {
+function checkedStdin(stdin, command) {
   if (stdin === undefined || stdin === null) return null;
-  if (typeof stdin !== 'string' || Buffer.byteLength(stdin) > MAX_PACKET_BYTES || stdin.includes('\0')) {
-    fail(`WorkBite agent input must be UTF-8 text of at most ${MAX_PACKET_BYTES} bytes`);
+  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])) {
@@ -136,17 +152,27 @@ async function recheck(binding, state) {
   }
 }
 
-const boundedLine = text => String(text).replace(/[\x00-\x1f\x7f]/g, ' ').trim().slice(0, 300);
+// 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, environment, argv, stdin, deadline, write }) {
+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 operation-status --intent-id ID\n`
-    : `error: ${what}; nothing was retried\n` });
+    ? `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 {
@@ -160,7 +186,7 @@ function rpc(command, { endpoint, uid, environment, argv, stdin, deadline, write
     const timer = setTimeout(() => { child.kill(); finish(uncertain('native client deadline exceeded')); }, nativeTimeout + 5000);
     child.stdout.on('data', chunk => {
       outSize += chunk.length;
-      if (outSize > MAX_STDOUT) { overflow = true; child.kill(); } else out.push(chunk);
+      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', () => {});
@@ -176,9 +202,10 @@ function rpc(command, { endpoint, uid, environment, argv, stdin, deadline, write
         finish(uncertain('no valid native response')); return;
       }
       if (response.error) {
-        const code = typeof response.error.code === 'string' ? response.error.code.replace(/[^A-Za-z]/g, '').slice(0, 32) : '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}: ${boundedLine(response.error.message || 'native request failed')}\n` });
+        finish({ code: 1, stdout: '', stderr: `error: ${code}: native request failed\n` });
         return;
       }
       const result = response.result;
@@ -194,17 +221,20 @@ 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 input = checkedStdin(stdin);
+  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, environment: state.environment,
-    argv: [...argv], stdin: input, deadline: state.deadline, write: WRITE_COMMANDS.includes(command) });
+  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 });
+    deadline: timeouts.agent || DEFAULT_DEADLINE, write: false, name: 'capabilities' });
 }
 
-module.exports = { bindAgent, executeAgent, agentCapabilities, AGENT_COMMANDS, WRITE_COMMANDS, MAX_PACKET_BYTES, commandOf };
+module.exports = { bindAgent, executeAgent, agentCapabilities, AGENT_COMMANDS, WRITE_COMMANDS, MAX_PACKET_BYTES, MAX_TRANSFER_BYTES, commandOf };

package/lib/archive.js

@@ -9,6 +9,7 @@ const { Transform, Writable } = require('node:stream');
 const { pipeline } = require('node:stream/promises');
 const { spawn } = require('node:child_process');
 const path = require('node:path');
+const { stripVTControlCharacters } = require('node:util');
 const { LIMITS, fail, memberPath } = require('./common');
 const utf8 = new TextDecoder('utf-8', { fatal: true });
 const crcTable = Uint32Array.from({ length: 256 }, (_, value) => {
@@ -213,21 +214,121 @@ async function boundedGunzip(archive, destination) {
 function nativeTar() {
   return process.platform === 'win32' ? path.join(process.env.SystemRoot || 'C:\\Windows', 'System32', 'tar.exe') : '/usr/bin/tar';
 }
-async function extractArchive(archive, destination, spec, { spawnImpl = spawn } = {}) {
+// Diagnostics are untrusted subprocess output or paths. Never echo URLs, auth
+// headers, credential assignments or terminal control sequences back to a terminal.
+function diagnosticText(value, maximum = 4096) {
+  return stripVTControlCharacters(String(value))
+    .replace(/[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/g, ' ')
+    .replace(/\b[a-z][a-z0-9+.-]*:\/\/[^\s]+/gi, '[redacted URL]')
+    .replace(/\b(?:authorization|proxy-authorization|cookie|set-cookie)\s*[:=].*/gi, '[redacted credentials]')
+    .replace(/\b(?:bearer|basic)\s+\S+/gi, '[redacted credentials]')
+    .replace(/\b([\w.-]*(?:token|password|passwd|secret|credential|api[_-]?key)[\w.-]*)\s*[:=]\s*(?:"[^"]*(?:"|$)|'[^']*(?:'|$)|[^\s]*)/gi, '$1=[redacted]')
+    .slice(0, maximum);
+}
+function extractionError(reason, destination, { code = null, signal = null, stderr = '', truncated = false, spawnCode } = {}) {
+  const detail = diagnosticText(stderr);
+  const permission = /permission denied|operation not permitted|read-only file system|access is denied/i.test(detail)
+    || ['EACCES', 'EPERM', 'EROFS'].includes(spawnCode);
+  const storage = /no space left|disk (?:is )?full|quota exceeded|stale file handle|input\/output error/i.test(detail)
+    || ['ENOSPC', 'EDQUOT', 'ESTALE', 'EIO'].includes(spawnCode);
+  const hint = permission ? ' Check destination permissions, mount options and NFS access.'
+    : storage ? ' Check free space, quota and filesystem/NFS health.' : '';
+  const error = new Error(`${reason} (exit code: ${code ?? 'none'}, signal: ${diagnosticText(signal ?? 'none', 64)}${spawnCode ? `, spawn: ${diagnosticText(spawnCode, 64)}` : ''}); destination: ${diagnosticText(path.resolve(destination))}.${hint}${detail ? ` stderr: ${detail}${truncated ? ' [truncated]' : ''}` : ''}`);
+  error.exitCode = code;
+  error.signal = signal;
+  if (spawnCode) error.code = spawnCode;
+  return error;
+}
+async function extractArchive(archive, destination, spec, { spawnImpl = spawn, timeout = LIMITS.timeout } = {}) {
   let input = archive;
   const windows = spec.asset.endsWith('.zip');
   if (!windows) { input = archive + '.tar'; await boundedGunzip(archive, input); }
   const entries = windows ? await zipEntries(input) : await tarEntries(input);
   validateEntries(entries, windows);
   await new Promise((resolve, reject) => {
-    const child = spawnImpl(nativeTar(), ['-xf', input, '-C', destination, '--no-same-owner', '--no-same-permissions'],
-      { shell: false, stdio: ['ignore', 'ignore', 'pipe'], windowsHide: true });
-    let errorBytes = 0;
-    const timer = setTimeout(() => { child.kill(); reject(new Error('Native tar extraction timed out')); }, LIMITS.timeout);
-    child.stderr.on('data', chunk => { errorBytes += chunk.length; if (errorBytes > 65536) { child.kill(); } });
-    child.once('error', () => { clearTimeout(timer); reject(new Error('Native tar is unavailable; install the operating system tar command')); });
-    child.once('close', code => { clearTimeout(timer); code === 0 ? resolve() : reject(new Error('Native tar rejected the release archive')); });
+    let child, timer, closeTimer, errorBytes = 0, captured = 0, stopped, processCode;
+    let started = false, settled = false;
+    const chunks = [];
+    const details = (code, signal, spawnCode) => ({ code, signal, spawnCode,
+      stderr: Buffer.concat(chunks).toString('utf8'), truncated: errorBytes > 4096 });
+    const finish = (error, unknown = false) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      clearTimeout(closeTimer);
+      if (child) {
+        child.removeListener('spawn', onSpawn);
+        child.removeListener('error', onError);
+        child.removeListener('close', onClose);
+        child.stderr.removeListener('data', onData);
+        // A late kill error must remain handled without retaining this attempt's
+        // callbacks or changing its already settled cleanup authority.
+        child.on('error', () => {});
+        if (unknown) { child.unref?.(); child.stderr.destroy(); }
+        child = undefined;
+      }
+      chunks.length = 0;
+      if (error) reject(error);
+      else resolve();
+    };
+    const spawnFailure = error => {
+      const failure = extractionError(error.code === 'ENOENT'
+        ? 'Native tar is unavailable; install the operating system tar command'
+        : 'Native tar could not start', destination, details(null, null, error.code));
+      finish(failure);
+    };
+    const stop = reason => {
+      if (settled || stopped) return;
+      stopped = reason;
+      // A process blocked in filesystem I/O may not close even after SIGKILL.
+      // Arm the grace before kill: it can throw, return false, or emit events
+      // synchronously. Only close proves the destination can be cleaned up.
+      closeTimer = setTimeout(() => {
+        const error = extractionError(`${stopped}; tar did not close after termination; staging retained for safety`,
+          destination, details(null, null, processCode));
+        error.extractionMayBeRunning = true;
+        finish(error, true);
+      }, 1000);
+      try { child.kill('SIGKILL'); }
+      catch (error) { if (!settled) processCode ||= error.code; }
+    };
+    const onSpawn = () => { if (!settled) started = true; };
+    const onError = error => {
+      if (settled) return;
+      // Node leaves pid undefined when spawn is refused. A pid, a spawn event,
+      // or an attempted kill makes an error insufficient proof of termination.
+      if (!started && child.pid === undefined && !stopped) { spawnFailure(error); return; }
+      processCode ||= error.code;
+      stop('Native tar process failed');
+    };
+    const onData = chunk => {
+      if (settled) return;
+      started = true;
+      const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      errorBytes += bytes.length;
+      if (captured < 65536) {
+        const part = Buffer.from(bytes.subarray(0, 65536 - captured));
+        chunks.push(part); captured += part.length;
+      }
+      if (errorBytes > 65536) stop('Native tar stderr exceeded its diagnostic limit');
+    };
+    // Wait for close after killing tar so staging cleanup cannot race extraction.
+    const onClose = (code, signal) => {
+      if (settled) return;
+      if (!stopped && code === 0 && !signal) finish();
+      else finish(extractionError(stopped || 'Native tar rejected the release archive', destination, details(code, signal, processCode)));
+    };
+    try {
+      child = spawnImpl(nativeTar(), ['-xf', input, '-C', destination, '--no-same-owner', '--no-same-permissions'],
+        { shell: false, stdio: ['ignore', 'ignore', 'pipe'], windowsHide: true });
+    } catch (error) { spawnFailure(error); return; }
+    started = child.pid !== undefined && child.pid !== null;
+    timer = setTimeout(() => stop('Native tar extraction timed out'), Math.min(timeout, LIMITS.timeout));
+    child.once('spawn', onSpawn);
+    child.on('error', onError);
+    child.once('close', onClose);
+    child.stderr.on('data', onData);
   });
   return entries;
 }
-module.exports = { validateEntries, zipEntries, tarEntries, extractArchive, nativeTar, TOP_DIRECTORIES, BUNDLE };
+module.exports = { validateEntries, zipEntries, tarEntries, extractArchive, nativeTar, diagnosticText, TOP_DIRECTORIES, BUNDLE };

package/lib/cli.js

@@ -4,12 +4,16 @@ 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
@@ -18,7 +22,8 @@ Usage:
   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
+                                         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
@@ -29,10 +34,22 @@ agent:
   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
+  --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.
@@ -62,10 +79,14 @@ const AGENT_FLAGS = Object.freeze({
   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']);
+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']);
+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('--')) {
@@ -101,6 +122,11 @@ function parseAgent(rest) {
   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; }
@@ -118,7 +144,23 @@ function parseAgent(rest) {
     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`);
   }
-  if (WRITE_COMMANDS.includes(name) && options.workspace === undefined) {
+  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');
@@ -142,6 +184,16 @@ function parseArguments(argv) {
   // 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') {
@@ -202,10 +254,26 @@ async function runAgent(parsed, { installed, stateRoot, environment, commands, t
   } else {
     binding = await bindAgent({ installed, stateRoot, environment, workspace: parsed.workspace,
       workspaceUid: parsed.workspaceUid, commands, timeouts });
-    const packet = await readPacket(parsed, stdin || process.stdin);
+    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);
@@ -228,6 +296,9 @@ async function main(argv = process.argv.slice(2), options = {}) {
   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.
@@ -246,7 +317,7 @@ async function main(argv = process.argv.slice(2), options = {}) {
     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, timeouts: options.timeouts });
+    frontend: parsed.frontend, stateRoot, environment, spawnImpl: options.spawnImpl, execImpl: options.execImpl, stdout, stderr, timeouts: options.timeouts });
 }
 
 module.exports = { main, parseArguments, HELP };