@crewx/cli 0.9.0-rc.14 → 0.9.0-rc.140

package/dist/commands/doctor.js

@@ -8,12 +8,30 @@
  *   crewx doctor --config <path>  Use specific config file
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLI_PROVIDER_INFO = void 0;
+exports.formatBytes = formatBytes;
+exports.inspectNpxCache = inspectNpxCache;
+exports.inspectHookCommands = inspectHookCommands;
+exports.inspectCrewxExecutable = inspectCrewxExecutable;
+exports.inspectCrewxShims = inspectCrewxShims;
+exports.checkCliProviders = checkCliProviders;
 exports.handleDoctor = handleDoctor;
-const fs_1 = require("fs");
-const path_1 = require("path");
-const child_process_1 = require("child_process");
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
 const sdk_1 = require("@crewx/sdk");
 const parse_common_flags_1 = require("./parse-common-flags");
+const command_marker_1 = require("./hook/command-marker");
+/** CLI diagnostics keyed by the bare provider name used in PROVIDER_ORDER. */
+exports.CLI_PROVIDER_INFO = {
+    codex: { cmd: 'codex', install: 'npm install -g @openai/codex' },
+    claude: { cmd: 'claude', install: 'npm install -g @anthropic-ai/claude-code' },
+    grok: { cmd: 'grok', install: 'curl -fsSL https://x.ai/cli/install.sh | bash' },
+    opencode: { cmd: 'opencode', install: 'npm install -g opencode' },
+    antigravity: { cmd: 'antigravity', install: 'npm install -g antigravity' },
+    copilot: { cmd: 'gh', install: 'brew install gh  # or visit cli.github.com' },
+};
 function statusIcon(status) {
     switch (status) {
         case 'success': return '✅';
@@ -26,18 +44,438 @@ function statusIcon(status) {
  */
 function isCommandAvailable(cmd) {
     try {
-        (0, child_process_1.execSync)(`which ${cmd}`, { stdio: 'ignore' });
+        (0, node_child_process_1.execSync)(`which ${cmd}`, { stdio: 'ignore' });
         return true;
     }
     catch {
         return false;
     }
 }
+/** Format a byte count for diagnostic output. */
+function formatBytes(bytes) {
+    if (!Number.isFinite(bytes) || bytes <= 0)
+        return '0 B';
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    let value = bytes;
+    let unitIndex = 0;
+    while (value >= 1024 && unitIndex < units.length - 1) {
+        value /= 1024;
+        unitIndex += 1;
+    }
+    const rounded = unitIndex === 0 || value >= 10 ? Math.round(value) : value.toFixed(1);
+    return `${rounded} ${units[unitIndex]}`;
+}
+function directorySize(path) {
+    try {
+        const stats = (0, node_fs_1.lstatSync)(path);
+        if (!stats.isDirectory())
+            return stats.size;
+        return (0, node_fs_1.readdirSync)(path, { withFileTypes: true }).reduce((total, entry) => {
+            return total + directorySize((0, node_path_1.join)(path, entry.name));
+        }, 0);
+    }
+    catch {
+        return 0;
+    }
+}
+function immediateDirectories(root) {
+    try {
+        return (0, node_fs_1.readdirSync)(root, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => (0, node_path_1.join)(root, entry.name))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+function readJsonObject(filePath) {
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(filePath, 'utf8'));
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+function getNpxCacheRoot(env = process.env) {
+    const configuredCache = env.NPM_CONFIG_CACHE ?? env.npm_config_cache;
+    const npmCache = configuredCache?.trim() || (0, node_path_1.join)((0, node_os_1.homedir)(), '.npm');
+    const resolvedCache = (0, node_path_1.resolve)(npmCache);
+    return (0, node_path_1.basename)(resolvedCache) === '_npx'
+        ? resolvedCache
+        : (0, node_path_1.join)(resolvedCache, '_npx');
+}
+const DEPENDENCY_SECTIONS = [
+    'dependencies',
+    'devDependencies',
+    'optionalDependencies',
+    'peerDependencies',
+];
+function staleFileDependencies(cacheDirectory) {
+    const packageJson = readJsonObject((0, node_path_1.join)(cacheDirectory, 'package.json'));
+    if (!packageJson)
+        return [];
+    const missing = [];
+    for (const section of DEPENDENCY_SECTIONS) {
+        const dependencies = packageJson[section];
+        if (typeof dependencies !== 'object' || dependencies === null || Array.isArray(dependencies))
+            continue;
+        for (const [name, specifier] of Object.entries(dependencies)) {
+            if (typeof specifier !== 'string' || !specifier.startsWith('file:'))
+                continue;
+            const target = (0, node_path_1.resolve)(cacheDirectory, specifier.slice('file:'.length));
+            if (!(0, node_fs_1.existsSync)(target)) {
+                missing.push(`${section}.${name}=${specifier} (missing ${target})`);
+            }
+        }
+    }
+    return missing;
+}
+function addArtifact(artifacts, directory, details) {
+    const existing = artifacts.get(directory);
+    if (existing) {
+        existing.details.push(...details);
+        return existing;
+    }
+    const artifact = {
+        directory,
+        sizeBytes: directorySize(directory),
+        details: [...details],
+    };
+    artifacts.set(directory, artifact);
+    return artifact;
+}
+/** Inspect npm's persistent `_npx` cache without modifying it. */
+function inspectNpxCache(cacheRoot = getNpxCacheRoot()) {
+    const resolvedRoot = (0, node_path_1.resolve)(cacheRoot);
+    const zeroByteLockfileDirectories = [];
+    const staleFileCacheDirectories = [];
+    const cleanable = new Map();
+    for (const directory of immediateDirectories(resolvedRoot)) {
+        const lockfile = (0, node_path_1.join)(directory, 'package-lock.json');
+        try {
+            const lockfileStats = (0, node_fs_1.statSync)(lockfile);
+            if (lockfileStats.isFile() && lockfileStats.size === 0) {
+                const entry = addArtifact(cleanable, directory, [`0-byte lockfile: ${lockfile}`]);
+                zeroByteLockfileDirectories.push(entry);
+            }
+        }
+        catch {
+            // A cache entry can disappear while doctor is inspecting it.
+        }
+        const missing = staleFileDependencies(directory);
+        if (missing.length > 0) {
+            const entry = addArtifact(cleanable, directory, missing);
+            staleFileCacheDirectories.push(entry);
+        }
+    }
+    return {
+        cacheRoot: resolvedRoot,
+        zeroByteLockfileDirectories,
+        staleFileCacheDirectories,
+        cleanableDirectories: [...cleanable.values()],
+    };
+}
+function asRecord(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return undefined;
+    return value;
+}
+function hookCommandsFromSettings(settings) {
+    const hookContainer = asRecord(settings.hooks) ?? settings;
+    const preToolUse = hookContainer.PreToolUse;
+    if (!Array.isArray(preToolUse))
+        return [];
+    const commands = [];
+    for (const entry of preToolUse) {
+        const entryRecord = asRecord(entry);
+        const hooks = entryRecord?.hooks;
+        if (!Array.isArray(hooks))
+            continue;
+        for (const hook of hooks) {
+            const command = asRecord(hook)?.command;
+            if (typeof command === 'string' && command_marker_1.CREWX_HOOK_COMMAND_RE.test(command)) {
+                commands.push(command);
+            }
+        }
+    }
+    return commands;
+}
+function firstShellToken(command) {
+    const value = command.trim();
+    if (!value)
+        return '';
+    if (value.startsWith("'") || value.startsWith('"')) {
+        const quote = value[0];
+        const closing = value.indexOf(quote, 1);
+        return closing === -1 ? value.slice(1) : value.slice(1, closing);
+    }
+    return value.split(/\s+/, 1)[0];
+}
+function isAbsoluteExecutableToken(token) {
+    return (0, node_path_1.isAbsolute)(token) || /^[A-Za-z]:[\\/]/.test(token) || token.startsWith('\\\\');
+}
+function hookCommandIssue(command) {
+    const executable = firstShellToken(command);
+    if (/^(?:npx|pnpm|yarn)$/i.test(executable))
+        return 'launcher';
+    if (!isAbsoluteExecutableToken(executable))
+        return 'non-absolute';
+    return undefined;
+}
+/** Inspect installed CrewX hooks without rewriting provider settings. */
+function inspectHookCommands(projectRoot) {
+    const candidates = [
+        { provider: 'claude', settingsPath: (0, node_path_1.join)((0, node_path_1.resolve)(projectRoot), '.claude', 'settings.json') },
+        { provider: 'codex', settingsPath: (0, node_path_1.join)((0, node_path_1.resolve)(projectRoot), '.codex', 'hooks.json') },
+    ];
+    const inspectedFiles = [];
+    const issues = [];
+    for (const candidate of candidates) {
+        if (!(0, node_fs_1.existsSync)(candidate.settingsPath))
+            continue;
+        inspectedFiles.push(candidate.settingsPath);
+        const settings = readJsonObject(candidate.settingsPath);
+        if (!settings)
+            continue;
+        for (const command of hookCommandsFromSettings(settings)) {
+            const reason = hookCommandIssue(command);
+            if (reason) {
+                issues.push({
+                    provider: candidate.provider,
+                    settingsPath: candidate.settingsPath,
+                    command,
+                    reason,
+                });
+            }
+        }
+    }
+    return { inspectedFiles, issues };
+}
+function configuredBinResolution(configPath, fallback = 'global_first') {
+    try {
+        const config = (0, sdk_1.loadYamlFile)(configPath);
+        const value = config.settings?.bin_resolution;
+        return value === 'local_first' || value === 'global_first' ? value : fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+function readWindowsCrewxPathCandidates(cwd, env, platform) {
+    if (platform !== 'win32')
+        return [];
+    try {
+        (0, sdk_1.primeWindowsConsoleCodePage)();
+        const output = (0, node_child_process_1.execFileSync)('where.exe', ['crewx'], {
+            cwd,
+            env,
+            encoding: null,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        return (0, sdk_1.decodeConsoleBuffer)(output, { platform })
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0);
+    }
+    catch {
+        return [];
+    }
+}
+/** Inspect the SDK-selected CrewX executable without printing environment values. */
+function inspectCrewxExecutable(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const cwd = (0, node_path_1.resolve)(options.cwd ?? process.cwd());
+    const env = options.env ?? process.env;
+    const configPath = options.configPath ?? (0, node_path_1.join)(cwd, 'crewx.yaml');
+    const resolution = options.resolution ?? (0, sdk_1.resolveCrewxExecutable)({ env, cwd, platform });
+    const pathCandidates = options.pathCandidates
+        ? [...options.pathCandidates]
+        : readWindowsCrewxPathCandidates(cwd, env, platform);
+    const requiredEnvKeys = resolution.ok
+        ? Object.keys(resolution.requiredEnv ?? {})
+            .filter((key) => key === 'ELECTRON_RUN_AS_NODE')
+        : [];
+    return {
+        platform,
+        pathCandidates,
+        ...(resolution.ok
+            ? {
+                stage: resolution.stage,
+                argv: [...resolution.argv],
+                adoptedPath: resolution.argv[0],
+            }
+            : { resolutionError: resolution.reason }),
+        electron: requiredEnvKeys.includes('ELECTRON_RUN_AS_NODE'),
+        requiredEnvKeys,
+        binResolution: options.binResolution ?? configuredBinResolution(configPath),
+    };
+}
+function checkCrewxExecutable(report) {
+    const details = [
+        `platform: ${report.platform}`,
+        `stage: ${report.stage ?? '(unresolved)'}`,
+        `argv: ${report.argv ? (0, sdk_1.formatCrewxExecutableArgv)(report.argv) : '(unresolved)'}`,
+        `adopted path: ${report.adoptedPath ?? '(none)'}`,
+        `Electron runtime: ${report.electron ? 'yes' : 'no'}`,
+        `required environment keys: ${report.requiredEnvKeys.length > 0 ? report.requiredEnvKeys.join(', ') : '(none)'}`,
+        `bin_resolution setting: ${report.binResolution}`,
+        ...(report.platform === 'win32'
+            ? [`where.exe crewx candidates: ${report.pathCandidates.length > 0 ? report.pathCandidates.join(', ') : '(none)'}`]
+            : []),
+    ];
+    if (report.resolutionError) {
+        return {
+            name: 'CrewX Executable',
+            status: 'warning',
+            message: 'Could not resolve the CrewX executable',
+            details: `${details.join('\n')}\nResolution failed; no environment values were printed.`,
+        };
+    }
+    return {
+        name: 'CrewX Executable',
+        status: 'success',
+        message: 'SDK child executable contract is available',
+        details: details.join('\n'),
+    };
+}
+/** Inspect orphaned CrewX PATH shim directories without modifying them. */
+function inspectCrewxShims(crewxHome = (0, sdk_1.getCrewxHome)(), resolvedFingerprint = (() => {
+    const resolution = (0, sdk_1.resolveCrewxExecutable)();
+    return resolution.ok ? (0, sdk_1.crewxCliShimFingerprint)(resolution) : undefined;
+})()) {
+    const shimRoot = (0, node_path_1.join)((0, node_path_1.resolve)(crewxHome), 'bin-shim');
+    const staleDirectories = [];
+    if (resolvedFingerprint) {
+        for (const directory of immediateDirectories(shimRoot)) {
+            const fingerprint = directory.slice(shimRoot.length + 1);
+            if (fingerprint === resolvedFingerprint)
+                continue;
+            staleDirectories.push({
+                fingerprint,
+                directory,
+                sizeBytes: directorySize(directory),
+                details: [`not current fingerprint (${resolvedFingerprint})`],
+            });
+        }
+    }
+    return { shimRoot, currentFingerprint: resolvedFingerprint, staleDirectories };
+}
+function checkNpxCache(report) {
+    const corrupt = report.zeroByteLockfileDirectories.length;
+    const stale = report.staleFileCacheDirectories.length;
+    const cleanable = report.cleanableDirectories.length;
+    if (corrupt === 0 && stale === 0) {
+        return {
+            name: 'npx Cache',
+            status: 'success',
+            message: `No stale entries found in ${report.cacheRoot}`,
+        };
+    }
+    const details = [];
+    if (corrupt > 0) {
+        details.push(`0-byte package-lock.json: ${report.zeroByteLockfileDirectories.map((entry) => entry.directory).join(', ')}`);
+    }
+    if (stale > 0) {
+        details.push(`stale file: cache: ${report.staleFileCacheDirectories.map((entry) => entry.directory).join(', ')}`);
+    }
+    details.push('Run `crewx doctor --clean-npx-cache` to remove these cache directories explicitly.');
+    return {
+        name: 'npx Cache',
+        status: 'warning',
+        message: `Found ${cleanable} problematic npx cache director${cleanable === 1 ? 'y' : 'ies'}`,
+        details: details.join('\n'),
+    };
+}
+function checkHookCommands(report) {
+    if (report.issues.length === 0) {
+        return {
+            name: 'CrewX Hooks',
+            status: 'success',
+            message: report.inspectedFiles.length > 0
+                ? 'Installed CrewX hook commands use absolute entrypoints'
+                : 'No installed CrewX hooks found',
+        };
+    }
+    const details = report.issues
+        .map((issue) => `${issue.settingsPath}: ${issue.command} (${issue.reason})`)
+        .join('\n');
+    return {
+        name: 'CrewX Hooks',
+        status: 'warning',
+        message: `Found ${report.issues.length} hook command(s) that need an absolute CrewX entrypoint`,
+        details: `${details}\nRun \`crewx hook install\` to refresh the hook after reviewing the change.`,
+    };
+}
+function checkCrewxShims(report) {
+    if (!report.currentFingerprint) {
+        return {
+            name: 'CrewX PATH Shims',
+            status: 'warning',
+            message: 'Could not resolve the current CrewX executable; skipped orphan shim cleanup',
+            details: `Shim root: ${report.shimRoot}`,
+        };
+    }
+    if (report.staleDirectories.length === 0) {
+        return {
+            name: 'CrewX PATH Shims',
+            status: 'success',
+            message: 'No orphaned CrewX PATH shims found',
+        };
+    }
+    return {
+        name: 'CrewX PATH Shims',
+        status: 'warning',
+        message: `Found ${report.staleDirectories.length} orphaned CrewX PATH shim director${report.staleDirectories.length === 1 ? 'y' : 'ies'}`,
+        details: `${report.staleDirectories.map((entry) => entry.directory).join(', ')}\nRun \`crewx doctor --clean-npx-cache\` to remove stale shims explicitly.`,
+    };
+}
+function safelyRemoveDirectories(directories, parent) {
+    const expectedParent = (0, node_path_1.resolve)(parent);
+    let removed = 0;
+    const failed = [];
+    for (const entry of directories) {
+        const directory = (0, node_path_1.resolve)(entry.directory);
+        if ((0, node_path_1.dirname)(directory) !== expectedParent) {
+            failed.push(`${directory} (unexpected parent)`);
+            continue;
+        }
+        try {
+            (0, node_fs_1.rmSync)(directory, { recursive: true, force: true });
+            if (!(0, node_fs_1.existsSync)(directory))
+                removed += 1;
+            else
+                failed.push(directory);
+        }
+        catch {
+            failed.push(directory);
+        }
+    }
+    return { removed, failed };
+}
+function cleanDoctorArtifacts(npxCache, shims) {
+    const npxTargets = npxCache.cleanableDirectories;
+    const shimTargets = shims.staleDirectories;
+    const allTargets = [...npxTargets, ...shimTargets];
+    const totalBytes = allTargets.reduce((sum, entry) => sum + entry.sizeBytes, 0);
+    console.log(`⚠️  --clean-npx-cache: before cleanup, ${npxTargets.length} npx cache director${npxTargets.length === 1 ? 'y' : 'ies'} ` +
+        `and ${shimTargets.length} orphan shim director${shimTargets.length === 1 ? 'y' : 'ies'} (${formatBytes(totalBytes)}).`);
+    const npxResult = safelyRemoveDirectories(npxTargets, npxCache.cacheRoot);
+    const shimResult = safelyRemoveDirectories(shimTargets, shims.shimRoot);
+    const failures = [...npxResult.failed, ...shimResult.failed];
+    console.log(`   Removed ${npxResult.removed + shimResult.removed} director${npxResult.removed + shimResult.removed === 1 ? 'y' : 'ies'}.`);
+    if (failures.length > 0) {
+        console.log(`   Could not remove: ${failures.join(', ')}`);
+    }
+}
 /**
  * Check crewx.yaml configuration file.
  */
 function checkConfig(configPath) {
-    if (!(0, fs_1.existsSync)(configPath)) {
+    if (!(0, node_fs_1.existsSync)(configPath)) {
         return {
             name: 'Configuration File',
             status: 'error',
@@ -83,8 +521,8 @@ function checkConfig(configPath) {
  * Check .crewx/logs directory.
  */
 function checkLogsDir() {
-    const logsDir = (0, path_1.join)(process.cwd(), '.crewx', 'logs');
-    if (!(0, fs_1.existsSync)(logsDir)) {
+    const logsDir = (0, node_path_1.join)(process.cwd(), '.crewx', 'logs');
+    if (!(0, node_fs_1.existsSync)(logsDir)) {
         return {
             name: 'Logs Directory',
             status: 'warning',
@@ -99,20 +537,19 @@ function checkLogsDir() {
     };
 }
 /**
- * Check CLI provider availability.
- * Providers are checked in PROVIDER_ORDER: codex → claude → opencode → antigravity → copilot.
+ * Check CLI provider availability in the canonical PROVIDER_ORDER.
  */
 function checkCliProviders() {
-    // Map each provider (in PROVIDER_ORDER) to its CLI command and install hint.
-    const providerInfo = {
-        codex: { cmd: 'codex', install: 'npm install -g @openai/codex' },
-        claude: { cmd: 'claude', install: 'npm install -g @anthropic-ai/claude-code' },
-        opencode: { cmd: 'opencode', install: 'npm install -g opencode' },
-        antigravity: { cmd: 'antigravity', install: 'npm install -g antigravity' },
-        copilot: { cmd: 'gh', install: 'brew install gh  # or visit cli.github.com' },
-    };
     return sdk_1.PROVIDER_ORDER.map(provider => {
-        const info = providerInfo[provider];
+        const info = exports.CLI_PROVIDER_INFO[provider];
+        if (!info) {
+            return {
+                name: `${provider.toUpperCase()} CLI`,
+                status: 'error',
+                message: 'Diagnostic metadata is missing',
+                details: `Add ${provider} to CLI_PROVIDER_INFO.`,
+            };
+        }
         const displayName = provider === 'copilot' ? 'copilot (gh)' : provider;
         const available = isCommandAvailable(info.cmd);
         return {
@@ -138,7 +575,7 @@ function checkEnvVars() {
     return {
         name: 'CREWX_CLI',
         status: 'warning',
-        message: 'Not set — defaulting to "npx crewx"',
+        message: 'Not set — defaulting to "crewx"',
         details: 'This is auto-set at CLI startup; no action needed.',
     };
 }
@@ -161,14 +598,30 @@ function assessHealth(diagnostics) {
  * Handle `crewx doctor` command.
  */
 async function handleDoctor(args) {
-    const { config } = (0, parse_common_flags_1.parseCommonFlags)(args);
-    const configPath = config ?? process.env.CREWX_CONFIG ?? (0, path_1.join)(process.cwd(), 'crewx.yaml');
+    const cleanNpxCache = args.includes('--clean-npx-cache');
+    const commonArgs = args.filter((arg) => arg !== '--clean-npx-cache');
+    const { config } = (0, parse_common_flags_1.parseCommonFlags)(commonArgs);
+    const configPath = config ?? process.env.CREWX_CONFIG ?? (0, node_path_1.join)(process.cwd(), 'crewx.yaml');
     console.log('🩺 Starting CrewX system diagnosis...\n');
+    let npxCache = inspectNpxCache();
+    let shims = inspectCrewxShims();
+    const projectRoot = (0, node_path_1.dirname)((0, node_path_1.resolve)(configPath));
+    const hooks = inspectHookCommands(projectRoot);
+    const executable = inspectCrewxExecutable({ configPath, cwd: process.cwd() });
+    if (cleanNpxCache) {
+        cleanDoctorArtifacts(npxCache, shims);
+        npxCache = inspectNpxCache();
+        shims = inspectCrewxShims();
+    }
     const diagnostics = [
         checkConfig(configPath),
         checkLogsDir(),
         checkEnvVars(),
+        checkCrewxExecutable(executable),
         ...checkCliProviders(),
+        checkNpxCache(npxCache),
+        checkHookCommands(hooks),
+        checkCrewxShims(shims),
     ];
     // Print diagnostics
     diagnostics.forEach(d => {
@@ -185,7 +638,7 @@ async function handleDoctor(args) {
     console.log(`${healthIcon} Overall: ${health.message}`);
     if (health.status === 'success') {
         console.log('\nNext steps:');
-        console.log('  crewx query "@claude hello"');
+        console.log('  crewx q --to crewx "hello"');
     }
     else {
         console.log('\nAddress the issues above, then run `crewx doctor` again.');

package/dist/commands/emit-trailer.d.ts

@@ -0,0 +1,25 @@
+import type { TraceContext } from '@crewx/sdk';
+/** Mutable per-process guard shared by a handler and main()'s error boundary. */
+export interface DelegationEmitState {
+    emitted: boolean;
+}
+/** The result fields needed to produce a delegation control line. */
+export interface DelegationEmitOptions {
+    command?: string;
+    trace?: TraceContext;
+    taskId?: string;
+    agentId?: string;
+    isError: boolean;
+    state?: DelegationEmitState;
+}
+export declare function createDelegationEmitState(): DelegationEmitState;
+/**
+ * Return true only for an inherited child invocation of q/query/x/execute.
+ * Root CLI calls and unrelated built-in commands must remain byte-compatible.
+ */
+export declare function shouldEmitDelegationResult(command: string | undefined, trace?: TraceContext | undefined): boolean;
+/**
+ * Write one machine-readable result line to stdout when this is a delegated call.
+ * The shared SDK formatter owns the wire syntax and validation rules.
+ */
+export declare function emitDelegationResult(options: DelegationEmitOptions): boolean;

package/dist/commands/emit-trailer.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDelegationEmitState = createDelegationEmitState;
+exports.shouldEmitDelegationResult = shouldEmitDelegationResult;
+exports.emitDelegationResult = emitDelegationResult;
+const sdk_1 = require("@crewx/sdk");
+const inherited_trace_1 = require("../utils/inherited-trace");
+const DELEGATION_COMMANDS = new Set(['q', 'query', 'x', 'execute']);
+function createDelegationEmitState() {
+    return { emitted: false };
+}
+/**
+ * Return true only for an inherited child invocation of q/query/x/execute.
+ * Root CLI calls and unrelated built-in commands must remain byte-compatible.
+ */
+function shouldEmitDelegationResult(command, trace = (0, inherited_trace_1.readInheritedTrace)()) {
+    return DELEGATION_COMMANDS.has(command ?? '') && Boolean(trace?.parentTaskId);
+}
+/**
+ * Write one machine-readable result line to stdout when this is a delegated call.
+ * The shared SDK formatter owns the wire syntax and validation rules.
+ */
+function emitDelegationResult(options) {
+    const { command, trace, state, taskId, agentId, isError } = options;
+    if (state?.emitted || !shouldEmitDelegationResult(command, trace))
+        return false;
+    const line = (0, sdk_1.formatDelegationResult)({ taskId, agentId, isError });
+    // Mark before writing so an EPIPE/error boundary cannot accidentally retry.
+    if (state)
+        state.emitted = true;
+    process.stdout.write(`${line}\n`);
+    return true;
+}

package/dist/commands/execute.d.ts

@@ -3,25 +3,29 @@
  * Parses args, loads config via Crewx SDK, and executes the task.
  *
  * Flags:
+ *   --to <agent>             Explicit recipient (the positional @agent form is shorthand)
  *   --thread <name>          Conversation thread name
  *   --provider <cli/xxx>     Provider override
+ *   --model <name>           Model override (e.g. claude-sonnet-5)
  *   --metadata <json>        Extra metadata JSON (double-quoted object). Propagated to events/hooks/tracing.
- *                           e.g. --metadata='{"workflow_id":"wf-1"}'
  *   --verbose                Debug output mode (default: raw agent response only)
  *   --config/-c <path>       Config file path override
  *   --output-format <fmt>    Output format (json|text|stream-json)
  *   --effort <level>         Model effort (high|medium|low)
- *   -f/--prompt-file <path>  Read task body from file (bypasses cmd.exe argv truncation)
+ *   -f/--prompt-file <path>  Read task body from file
+ *   --detach/--async         Persist a receipt and launch a detached runner
+ *   --wait                   Force synchronous execution
  *
  * Stdin support:
  *   Pipe or redirect content into crewx x to supply the task body via stdin.
- *   e.g. cat task.md | crewx x "@agent label"
  *   Stdin is ignored when running in an interactive TTY.
  */
+import { type DelegationEmitState } from './emit-trailer';
+export { runDetachedMiddle } from './detached';
 /**
  * Handle `crewx execute <agentRef> <message>` command.
  *
  * Default output: raw agent response only (stdout).
  * --verbose: debug info written to stderr, response to stdout.
  */
-export declare function handleExecute(args: string[]): Promise<void>;
+export declare function handleExecute(args: string[], command?: string, emitState?: DelegationEmitState): Promise<void>;