crewx-agent-cli 0.2.3 → 0.2.4

package/README.md

@@ -1,6 +1,13 @@
 # CrewX CLI
 
-Connect an existing Codex, Claude Code, Pi, Hermes, or OpenClaw installation to a CrewX workspace. The runner stays on your machine, so the agent uses its existing login, configuration, tools, and access to the selected working directory.
+Connect an existing Codex, Claude Code, Pi, Hermes, or OpenClaw installation to
+a CrewX workspace. The runner stays on your machine, so the agent uses its
+existing login, configuration, tools, and access to the selected working
+directory.
+
+For a persistent agent, CrewX recommends a connected machine managed by
+`crewx-bridge`. **Via terminal** is the portable foreground alternative
+documented below.
 
 ## One-command join
 
@@ -23,7 +30,18 @@ npx --yes crewx-agent-cli@latest --join <join-code> --adapter codex
 
 The versioned join payload is base64url-encoded JSON containing the server URL, adapter, and raw `crwx_…` bearer token. Base64url is transport encoding, not encryption. CrewX shows the generated token once, but the credential inside the command is reusable until its configured expiry or revocation. Anyone who obtains the command can decode and use it, and the command may remain in shell history. Treat it as a secret and revoke the token from the agent profile if it is exposed.
 
-The server stores only the token digest. During a join-mode run, the CLI keeps the decoded credential in memory and supplies the CrewX URL and token to child agents as `CREWX_URL` and `CREWX_TOKEN` so they can use the scoped `crewx task`, `doc`, `memory`, and `integration` commands. A locally executed agent has the same trust boundary as the user account running it.
+The server stores only the token digest. During a join-mode run, the CLI keeps
+the decoded credential in memory, but it does not pass that reusable credential
+to the coding runtime. For each assignment it opens an ephemeral loopback
+capability proxy and supplies the runtime only that proxy's URL, random bearer,
+and CLI path. The proxy allows the selected task, document, memory, and
+integration operations with strict route/method, size, timeout, and redirect
+limits, then closes when the assignment ends. A locally executed agent still
+has the operating-system permissions of the user account running it. The proxy
+prevents accidental credential inheritance and limits the normal tool surface;
+it is not isolation from hostile code running as the same OS user, which may
+inspect that user's files and processes. Use a separate OS account, container,
+VM, or host for an untrusted runtime or materially different trust boundary.
 
 ## Persistent installation
 
@@ -46,7 +64,42 @@ crewx daemon --adapter codex
 
 The saved connection lives at `$XDG_CONFIG_HOME/crewx/config.json` (or `~/.config/crewx/config.json`) with mode `0600`. `CREWX_URL`, `CREWX_TOKEN`, and `CREWX_ADAPTER` override saved settings and are useful in explicitly secured services and CI. The CLI includes operating-system certificate authorities in Node's trust store, so locally trusted HTTPS sites such as Laravel Herd work without disabling certificate verification.
 
-Both join mode and `crewx daemon` run in the foreground. Start either command inside a safe fallback directory. For each assignment, CrewX uses the project channel's local path first, the agent profile's default working directory second, and `--cwd` last. Use `--once` for one poll and `--poll-interval 5000` to change the polling cadence.
+Both join mode and `crewx daemon` run in the foreground. Start either command
+inside a safe fallback directory. For each assignment, CrewX uses the project
+channel's local path first, the agent profile's default working directory
+second, and `--cwd` last. Use `--once` for one poll and
+`--poll-interval 5000` to set the active/base polling cadence. During an idle
+period the runner backs off with jitter to at most 8 seconds, honors server
+retry guidance, and resets to the base cadence as soon as work appears.
+
+Assignments carry an opaque claim-fencing token. The runner includes it on
+heartbeats, messages, errors, and lifecycle events; CrewX rotates it when work
+is reassigned so a replaced runner cannot apply late results. The token is
+redacted from diagnostics and never enters the prompt or coding-runtime
+environment. Final assistant messages, errors, and the terminal lifecycle event
+are persisted as one owner-only outbox batch with stable event UUIDs before
+delivery. A process restart replays that batch until the server acknowledges
+it, while bounded backpressure coalesces replaceable output and never silently
+evicts a terminal outcome. Every outbound event batch is capped against the
+exact serialized HTTP body, including its envelope and separators; one event
+that cannot fit fails visibly instead of creating an endlessly retried request.
+
+The outbox is stored below
+`~/Library/Application Support/CrewX Agent/outbox/` on macOS or
+`${XDG_STATE_HOME:-~/.local/state}/crewx-agent/outbox/` on Linux. Its directory
+is mode `0700`, files are mode `0600`, and unsafe ownership, modes, or symlinks
+are rejected. New join codes carry an opaque, non-secret runner scope generated
+once for the agent profile. It keys the outbox and its full-lifetime
+single-writer lock, so a rotated connection token reuses the same durable
+state. The token remains the sole authority. A second live daemon for the same
+profile is rejected; after an unclean exit, a replacement verifies process
+identity before recovering the lock. Legacy join codes without a runner scope
+remain supported and derive an isolated fallback key from the token.
+
+Bridge-started runners receive their per-run bearer through a one-shot
+inherited pipe that closes immediately after startup, rather than through the
+exec environment. This reduces accidental exposure but does not change the OS
+account trust boundary.
 
 ## Built-in adapters
 
@@ -58,6 +111,13 @@ Both join mode and `crewx daemon` run in the foreground. Start either command in
 
 `crewx doctor` probes all five binaries. Runtime profile changes are read before every assignment, so supported model, permission, chat-only, working-directory, token, and deactivation changes do not require reconnecting. Chat-only and deactivated agents cannot receive task runs.
 
+The assignment capability proxy enforces the server profile locally:
+`read_only` and chat-only profiles may use only GET operations; `standard` and
+`full_access` profiles may use the explicitly allowlisted task, document,
+memory, and integration mutations. A 401 or 403 from the assignment control
+endpoint immediately aborts the active process group and terminates the daemon
+instead of allowing revoked work to continue.
+
 ## Custom commands
 
 Advanced users can replace the built-in invocation without editing CrewX:
@@ -72,7 +132,13 @@ crewx run codex "Review this repository" --coding-cmd 'my-agent {prompt} --quiet
 
 CrewX uses a quote-aware argv parser and launches the resulting executable with `shell: false`. The prompt replaces one exact `{prompt}` argument or is appended as one argument when the placeholder is absent; it is never interpolated into a shell string. Pipes, redirection, variable expansion, and command substitution are therefore not interpreted by CrewX.
 
-This prevents prompt text from becoming shell syntax, but it does not make an arbitrary executable safe. The selected program inherits the runner's operating-system permissions and environment, including CrewX connection variables in join mode. Do not use commands from an untrusted profile or run them in an untrusted working directory. Explicitly wrapping a command in a shell recreates the shell-risk boundary and is not recommended.
+This prevents prompt text from becoming shell syntax, but it does not make an
+arbitrary executable safe. The selected program inherits the runner's
+operating-system permissions and ordinary provider environment, but all
+inherited `CREWX_*` variables are removed and replaced only by the
+assignment-lifetime loopback capability. Do not use commands from an untrusted
+profile or run them in an untrusted working directory. Explicitly wrapping a
+command in a shell recreates the shell-risk boundary and is not recommended.
 
 ## Shared work commands
 
@@ -99,6 +165,15 @@ crewx integration search google_drive "quarterly plan" --json
 
 Agents may update only tasks assigned to their own profile. Documents must be agent-readable and unprotected, and every document update requires the current version from `doc list`; stale updates fail instead of overwriting newer work. Agents may edit only memories they recorded, while channel-scoped memory is limited to channels they can see. Provider access tokens are encrypted by the web application and are never returned to the CLI; integration commands expose normalized search results only.
 
+Task, document, and memory lists consume the server's bounded cursor pages
+automatically. Each HTTP response remains below the CLI's 2 MiB safety limit,
+while existing callers still receive one combined array up to 10,000 items or
+16 MiB of encoded data. Larger results fail with an instruction to narrow the
+filters or use `listTaskPage`, `listDocumentPage`, or `listMemoryPage` for
+explicit page-by-page processing. The monotonic cursor is the last seen
+resource ID, so concurrent inserts do not shift later pages. Legacy servers
+without pagination metadata remain a supported one-page response.
+
 ## One-shot local runs
 
 The same adapters can be exercised without a CrewX connection:

package/dist/adapters.d.ts

@@ -1,5 +1,9 @@
 import { type ChildProcessWithoutNullStreams, type SpawnOptionsWithoutStdio } from 'node:child_process';
 import { type AgentAdapter } from 'crewx-agent-protocol';
+export declare function adapterProbePlan(adapter: AgentAdapter): {
+    args: readonly string[];
+    timeoutMs: number;
+};
 export interface AdapterInvocation {
     command: string;
     args: string[];
@@ -50,6 +54,7 @@ export interface RunAdapterOptions {
     profile?: AgentRuntimeProfile | undefined;
     codingCommand?: string | undefined;
     environment?: NodeJS.ProcessEnv | undefined;
+    controlEnvironment?: NodeJS.ProcessEnv | undefined;
     timeoutMs?: number | undefined;
     maxOutputBytes?: number | undefined;
     signal?: AbortSignal | undefined;
@@ -58,6 +63,13 @@ export interface RunAdapterOptions {
     onMessage?: ((message: string, role: 'assistant' | 'tool') => void) | undefined;
     onStderr?: ((line: string) => void) | undefined;
 }
+/**
+ * Coding runtimes inherit provider credentials and ordinary process settings,
+ * but never inherit the daemon's CrewX control-plane credentials. The only
+ * CrewX variables admitted are short-lived, capability-scoped proxy values
+ * supplied separately by the assignment executor.
+ */
+export declare function runtimeEnvironment(environment?: NodeJS.ProcessEnv, controlEnvironment?: NodeJS.ProcessEnv, inherited?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 export declare function runAdapter(options: RunAdapterOptions): Promise<AdapterRunResult>;
 export declare function probeAdapter(adapter: AgentAdapter, spawnProcess?: SpawnProcess, timeoutMs?: number): Promise<{
     available: boolean;

package/dist/adapters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../src/adapters.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,8BAA8B,EAAE,KAAK,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAM/G,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAS7E,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;IAClC,MAAM,EACF;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,GACjB;QAAE,IAAI,EAAE,UAAU,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GACnC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACpC;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,WAAW,GAAG,UAAU,GAAG,aAAa,CAAC;IAC5D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAWD,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,OAAO,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,WAAW,GAAG,MAAM,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;IAC9B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,MAAM,YAAY,GAAG,CACzB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE,wBAAwB,KAC9B,8BAA8B,CAAC;AAuEpC,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAMxD;AAED,mFAAmF;AACnF,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,YAAY,EACrB,OAAO,GAAE,mBAAwB,EACjC,aAAa,CAAC,EAAE,MAAM,GACrB,iBAAiB,CAmGnB;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CA6C1D;AAwDD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAoDvF;AA4FD,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,IAAI,CAAC,iBAAiB,EAAE,KAAK,GAAG,aAAa,GAAG,cAAc,CAAC,GAAG;IACzE,OAAO,EAAE,mBAAmB,CAAC;CAC9B,GACA,OAAO,CAAC,IAAI,CAAC,CA6Ff;AAmCD,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,YAAY,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;IAC1C,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,SAAS,CAAC;IAC5C,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IACjC,YAAY,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IAC3E,SAAS,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IAChF,QAAQ,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CACjD;AA0cD,wBAAsB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAgBtF;AAED,wBAAsB,YAAY,CAChC,OAAO,EAAE,YAAY,EACrB,YAAY,GAAE,YAAoC,EAClD,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAsGnE"}
+{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../src/adapters.ts"],"names":[],"mappings":"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"}

package/dist/adapters.js

@@ -9,6 +9,13 @@ import { CliError } from './errors.js';
 const DEFAULT_RUNTIME_PROBE_TIMEOUT_MS = 5_000;
 const OPENCLAW_RUNTIME_PROBE_TIMEOUT_MS = 30_000;
 const OPENCLAW_SETUP_TIMEOUT_MS = 60_000;
+export function adapterProbePlan(adapter) {
+    return adapter === 'hermes'
+        ? { args: ['acp', '--check'], timeoutMs: DEFAULT_RUNTIME_PROBE_TIMEOUT_MS }
+        : adapter === 'openclaw'
+            ? { args: ['agents', 'list', '--json'], timeoutMs: OPENCLAW_RUNTIME_PROBE_TIMEOUT_MS }
+            : { args: ['--version'], timeoutMs: DEFAULT_RUNTIME_PROBE_TIMEOUT_MS };
+}
 const CLAUDE_STANDARD_CREWX_TOOLS = [
     'WebSearch',
     'WebFetch',
@@ -351,12 +358,23 @@ function record(value) {
         ? value
         : undefined;
 }
+function openClawError(code, message, cause) {
+    return new CliError(message, 1, {
+        code,
+        ...(cause !== undefined ? { cause } : {}),
+    });
+}
+function publicOpenClawDiagnostic(value) {
+    return value
+        .replace(/(^|[\s"'`=:(])(?:\/(?!\/)[^\s"'`),;]+)+/g, "$1<local-path>")
+        .replace(/(^|[\s"'`=:(])[A-Za-z]:\\[^\s"'`),;]+/g, "$1<local-path>");
+}
 async function resolvedPath(value, label) {
     try {
         return await realpath(value);
     }
     catch (error) {
-        throw new CliError(`${label} does not resolve to an accessible local directory: ${value}`, 1, { cause: error });
+        throw openClawError('openclaw_workspace_unavailable', `${label} does not resolve to an accessible local directory.`, error);
     }
 }
 async function openClawJsonProbe(args, options, timeoutMs = OPENCLAW_RUNTIME_PROBE_TIMEOUT_MS) {
@@ -365,14 +383,14 @@ async function openClawJsonProbe(args, options, timeoutMs = OPENCLAW_RUNTIME_PRO
     try {
         child = spawnProcess('openclaw', args, {
             cwd: options.cwd,
-            env: { ...process.env, ...options.environment },
+            env: runtimeEnvironment(options.environment),
             shell: false,
             detached: process.platform !== 'win32',
             stdio: ['pipe', 'pipe', 'pipe'],
         });
     }
     catch (error) {
-        throw new CliError('Unable to start openclaw. Is it installed and on PATH?', 1, { cause: error });
+        throw openClawError('openclaw_unavailable', 'Unable to start openclaw. Is it installed and on PATH?', error);
     }
     let stdout = '';
     let stderr = '';
@@ -417,18 +435,20 @@ async function openClawJsonProbe(args, options, timeoutMs = OPENCLAW_RUNTIME_PRO
                 throw error;
             }),
         ]));
-        if (timedOut)
-            throw new CliError(`OpenClaw preflight timed out: openclaw ${args.join(' ')}`);
-        if (exceeded)
-            throw new CliError('OpenClaw preflight exceeded its 1048576 byte output limit.');
+        if (timedOut) {
+            throw openClawError('openclaw_probe_timeout', `OpenClaw preflight timed out while running ${[args[0], args[1]].filter(Boolean).join(' ')}.`);
+        }
+        if (exceeded) {
+            throw openClawError('openclaw_probe_output_too_large', 'OpenClaw preflight exceeded its 1048576 byte output limit.');
+        }
         if (code !== 0) {
-            throw new CliError(`OpenClaw preflight failed: ${stderr.trim() || `exit ${String(code)}`}`);
+            throw openClawError('openclaw_probe_failed', `OpenClaw preflight failed: ${publicOpenClawDiagnostic(stderr.trim()) || `exit ${String(code)}`}`);
         }
         try {
             return JSON.parse(stdout);
         }
         catch (error) {
-            throw new CliError('OpenClaw preflight returned invalid JSON.', 1, { cause: error });
+            throw openClawError('openclaw_probe_invalid_json', 'OpenClaw preflight returned invalid JSON.', error);
         }
     }
     finally {
@@ -441,12 +461,14 @@ async function openClawJsonProbe(args, options, timeoutMs = OPENCLAW_RUNTIME_PRO
 }
 export async function verifyOpenClawRuntime(options) {
     const agentId = options.profile.runtimeAgentId?.trim();
-    if (!agentId)
-        throw new CliError('OpenClaw requires an explicit configured agent ID.');
+    if (!agentId) {
+        throw openClawError('openclaw_agent_id_missing', 'OpenClaw requires an explicit configured agent ID.');
+    }
     const desiredWorkspace = await resolvedPath(options.cwd, 'CrewX assignment directory');
     let agents = await openClawJsonProbe(['agents', 'list', '--json'], options);
-    if (!Array.isArray(agents))
-        throw new CliError('OpenClaw returned an invalid agent list.');
+    if (!Array.isArray(agents)) {
+        throw openClawError('openclaw_agent_list_invalid', 'OpenClaw returned an invalid agent list.');
+    }
     let selected = agents.map(record).find((agent) => agent?.id === agentId);
     if (!selected && agentId.startsWith('crewx-')) {
         await openClawJsonProbe([
@@ -459,41 +481,74 @@ export async function verifyOpenClawRuntime(options) {
             '--json',
         ], options, OPENCLAW_SETUP_TIMEOUT_MS);
         agents = await openClawJsonProbe(['agents', 'list', '--json'], options);
-        if (!Array.isArray(agents))
-            throw new CliError('OpenClaw returned an invalid agent list after setup.');
+        if (!Array.isArray(agents)) {
+            throw openClawError('openclaw_agent_list_invalid', 'OpenClaw returned an invalid agent list after setup.');
+        }
         selected = agents.map(record).find((agent) => agent?.id === agentId);
         if (!selected) {
-            throw new CliError(`CrewX created OpenClaw agent "${agentId}", but OpenClaw did not return it.`);
+            throw openClawError('openclaw_agent_setup_failed', `CrewX created OpenClaw agent "${agentId}", but OpenClaw did not return it.`);
         }
     }
     if (!selected) {
-        throw new CliError(`OpenClaw agent "${agentId}" is not configured. Run \`openclaw agents list --json\` to choose one.`);
+        throw openClawError('openclaw_agent_missing', `OpenClaw agent "${agentId}" is not configured. Run \`openclaw agents list --json\` to choose one.`);
     }
     if (typeof selected.workspace !== 'string' || !selected.workspace.trim()) {
-        throw new CliError(`OpenClaw agent "${agentId}" does not report a workspace.`);
+        throw openClawError('openclaw_workspace_missing', `OpenClaw agent "${agentId}" does not report a workspace.`);
     }
     const configuredWorkspace = await resolvedPath(selected.workspace, `OpenClaw agent "${agentId}" workspace`);
     if (configuredWorkspace !== desiredWorkspace) {
-        throw new CliError(`OpenClaw agent "${agentId}" uses workspace "${configuredWorkspace}", but this CrewX assignment requires "${desiredWorkspace}". OpenClaw has no per-run --cwd. Create a dedicated agent with: openclaw agents add <name> --workspace "${desiredWorkspace}" --non-interactive --json`);
+        throw openClawError('openclaw_workspace_mismatch', `OpenClaw agent "${agentId}" is bound to a different local workspace than the CrewX-approved folder. OpenClaw has no per-run --cwd; create or select a dedicated OpenClaw agent for the approved folder, then retry.`);
+    }
+    const models = record(await openClawJsonProbe(['models', 'status', '--agent', agentId, '--json'], options, OPENCLAW_SETUP_TIMEOUT_MS));
+    if (!models || (typeof models.agentId === 'string' && models.agentId !== agentId)) {
+        throw openClawError('openclaw_model_status_invalid', `OpenClaw did not return model status for agent "${agentId}". Run \`openclaw models status --agent "${agentId}" --json\`.`);
+    }
+    const resolvedModel = typeof models.resolvedDefault === 'string' && models.resolvedDefault.trim()
+        ? models.resolvedDefault.trim()
+        : typeof models.defaultModel === 'string' && models.defaultModel.trim()
+            ? models.defaultModel.trim()
+            : undefined;
+    if (!resolvedModel) {
+        throw openClawError('openclaw_model_missing', `OpenClaw agent "${agentId}" has no default model. Configure one, then run \`openclaw models status --agent "${agentId}" --json\`.`);
+    }
+    const allowedModels = Array.isArray(models.allowed)
+        ? models.allowed.filter((value) => typeof value === 'string')
+        : [];
+    if (allowedModels.length > 0 && !allowedModels.includes(resolvedModel)) {
+        throw openClawError('openclaw_model_unavailable', `OpenClaw agent "${agentId}" resolves to model "${resolvedModel}", but that model is not allowed. Run \`openclaw models status --agent "${agentId}" --json\` and select an allowed model.`);
+    }
+    const auth = record(models.auth);
+    const missingProviders = Array.isArray(auth?.missingProvidersInUse)
+        ? auth.missingProvidersInUse.filter((value) => typeof value === 'string')
+        : [];
+    if (missingProviders.length > 0) {
+        throw openClawError('openclaw_auth_missing', `OpenClaw agent "${agentId}" is missing authentication for ${missingProviders.join(', ')}. Run \`openclaw models auth --agent "${agentId}" --help\`, configure the provider, then verify with \`openclaw models status --agent "${agentId}" --json\`.`);
+    }
+    const authRoutes = Array.isArray(auth?.runtimeAuthRoutes)
+        ? auth.runtimeAuthRoutes.map(record).filter((route) => route !== undefined)
+        : [];
+    if (authRoutes.length > 0 &&
+        !authRoutes.some((route) => route.status === 'usable')) {
+        throw openClawError('openclaw_auth_unusable', `OpenClaw agent "${agentId}" has no usable authentication route for "${resolvedModel}" (credentials may be expired or cooling down). Run \`openclaw models auth --agent "${agentId}" list --json\`, repair authentication, then retry.`);
     }
     const sessionLeaf = options.profile.sessionKey ?? 'main';
     const fullSessionKey = `agent:${agentId}:${sessionLeaf}`;
     const explanation = record(await openClawJsonProbe(['sandbox', 'explain', '--session', fullSessionKey, '--json'], options));
     const sandbox = record(explanation?.sandbox);
     if (explanation?.agentId !== agentId || explanation?.sessionKey !== fullSessionKey || !sandbox) {
-        throw new CliError('OpenClaw sandbox preflight did not describe the requested agent session.');
+        throw openClawError('openclaw_sandbox_invalid', 'OpenClaw sandbox preflight did not describe the requested agent session.');
     }
     const effectiveHostRoot = typeof sandbox.effectiveHostWorkspaceRoot === 'string'
         ? await resolvedPath(sandbox.effectiveHostWorkspaceRoot, 'OpenClaw effective workspace')
         : undefined;
     if (effectiveHostRoot !== desiredWorkspace) {
-        throw new CliError('OpenClaw sandbox policy does not expose the exact CrewX assignment directory.');
+        throw openClawError('openclaw_sandbox_workspace_mismatch', 'OpenClaw sandbox policy does not expose the exact CrewX assignment directory.');
     }
     if (sandbox.sessionIsSandboxed === true) {
         if (sandbox.backend !== 'docker' ||
             sandbox.workspaceAccess !== 'rw' ||
             typeof sandbox.runtimeWorkdir !== 'string') {
-            throw new CliError('OpenClaw must grant rw workspace access for CrewX coding assignments.');
+            throw openClawError('openclaw_sandbox_read_only', 'OpenClaw must grant rw workspace access for CrewX coding assignments.');
         }
         const mounts = Array.isArray(sandbox.workspaceMounts) ? sandbox.workspaceMounts.map(record) : [];
         let writableWorkspaceMount = false;
@@ -508,16 +563,16 @@ export async function verifyOpenClawRuntime(options) {
             }
         }
         if (!writableWorkspaceMount) {
-            throw new CliError('OpenClaw sandbox policy does not mount the CrewX assignment directory read-write at its runtime workdir.');
+            throw openClawError('openclaw_sandbox_mount_missing', 'OpenClaw sandbox policy does not mount the CrewX assignment directory read-write at its runtime workdir.');
         }
     }
     else {
         if (typeof sandbox.runtimeWorkdir !== 'string') {
-            throw new CliError('OpenClaw did not report its direct runtime working directory.');
+            throw openClawError('openclaw_runtime_workdir_missing', 'OpenClaw did not report its direct runtime working directory.');
         }
         const runtimeWorkdir = await resolvedPath(sandbox.runtimeWorkdir, 'OpenClaw runtime working directory');
         if (runtimeWorkdir !== desiredWorkspace) {
-            throw new CliError('OpenClaw direct runtime workdir does not match the CrewX assignment directory.');
+            throw openClawError('openclaw_runtime_workdir_mismatch', 'OpenClaw direct runtime workdir does not match the CrewX assignment directory.');
         }
     }
 }
@@ -553,6 +608,32 @@ function createLineConsumer(callback) {
         },
     };
 }
+const ALLOWED_RUNTIME_CONTROL_VARIABLES = [
+    'CREWX_URL',
+    'CREWX_TOKEN',
+    'CREWX_CLI_PATH',
+];
+/**
+ * Coding runtimes inherit provider credentials and ordinary process settings,
+ * but never inherit the daemon's CrewX control-plane credentials. The only
+ * CrewX variables admitted are short-lived, capability-scoped proxy values
+ * supplied separately by the assignment executor.
+ */
+export function runtimeEnvironment(environment = {}, controlEnvironment = {}, inherited = process.env) {
+    const result = {};
+    for (const [key, value] of Object.entries({ ...inherited, ...environment })) {
+        if (key.toUpperCase().startsWith('CREWX_'))
+            continue;
+        if (value !== undefined)
+            result[key] = value;
+    }
+    for (const key of ALLOWED_RUNTIME_CONTROL_VARIABLES) {
+        const value = controlEnvironment[key];
+        if (value !== undefined)
+            result[key] = value;
+    }
+    return result;
+}
 async function materializeInvocation(invocation, prompt) {
     if (invocation.prompt.type === 'stdin') {
         return { args: invocation.args, stdin: prompt, cleanup: async () => undefined };
@@ -603,10 +684,7 @@ async function runSpawnAdapter(options) {
     try {
         child = spawnProcess(invocation.command, materialized.args, {
             cwd: options.cwd,
-            env: {
-                ...process.env,
-                ...options.environment,
-            },
+            env: runtimeEnvironment(options.environment, options.controlEnvironment),
             shell: false,
             detached: process.platform !== 'win32',
             stdio: ['pipe', 'pipe', 'pipe'],
@@ -767,7 +845,7 @@ async function runHermesAcp(options) {
     try {
         child = spawnProcess('hermes', ['acp'], {
             cwd: options.cwd,
-            env: { ...process.env, ...options.environment },
+            env: runtimeEnvironment(options.environment, options.controlEnvironment),
             shell: false,
             detached: process.platform !== 'win32',
             stdio: ['pipe', 'pipe', 'pipe'],
@@ -1006,20 +1084,14 @@ export async function runAdapter(options) {
     return runSpawnAdapter(options);
 }
 export async function probeAdapter(adapter, spawnProcess = spawn, timeoutMs) {
-    const effectiveTimeoutMs = timeoutMs
-        ?? (adapter === 'openclaw'
-            ? OPENCLAW_RUNTIME_PROBE_TIMEOUT_MS
-            : DEFAULT_RUNTIME_PROBE_TIMEOUT_MS);
+    const plan = adapterProbePlan(adapter);
+    const effectiveTimeoutMs = timeoutMs ?? plan.timeoutMs;
     const command = adapter;
-    const probeArgs = adapter === 'hermes'
-        ? ['acp', '--check']
-        : adapter === 'openclaw'
-            ? ['agents', 'list', '--json']
-            : ['--version'];
+    const probeArgs = plan.args;
     let child;
     try {
         child = spawnProcess(command, probeArgs, {
-            env: process.env,
+            env: runtimeEnvironment(),
             shell: false,
             detached: process.platform !== 'win32',
             stdio: ['pipe', 'pipe', 'pipe'],