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

package/dist/commands/slack.js

@@ -44,6 +44,7 @@ exports.handleSlack = handleSlack;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const https = __importStar(require("https"));
+const sdk_1 = require("@crewx/sdk");
 const adapter_slack_1 = require("@crewx/adapter-slack");
 const crewx_cli_1 = require("../bootstrap/crewx-cli");
 const markdown_1 = require("../slack/markdown");
@@ -186,7 +187,7 @@ async function handleListFiles(threadId) {
             console.log(`  📎 ${file.fileName}`);
             console.log(`     Size: ${formatFileSize(file.fileSize)}`);
             console.log(`     Path: ${file.filePath}`);
-            console.log(`     Downloaded: ${file.downloadedAt.toLocaleString()}`);
+            console.log(`     Downloaded: ${(0, sdk_1.formatDisplayTimestamp)(file.downloadedAt)}`);
             console.log('');
         }
         console.log(`Total: ${files.length} file${files.length > 1 ? 's' : ''}\n`);

package/dist/commands/stop.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Stop a running task through the SDK's cooperative-stop pipeline.
+ *
+ * `kill` is kept as a compatibility alias; both entry points use this same
+ * handler so server, CLI, and future adapters share one stop contract.
+ */
+/** Handle `crewx stop` and the compatibility `crewx kill` alias. */
+export declare function handleStop(args: string[], invokedAs?: 'stop' | 'kill'): Promise<void>;

package/dist/commands/stop.js

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * Stop a running task through the SDK's cooperative-stop pipeline.
+ *
+ * `kill` is kept as a compatibility alias; both entry points use this same
+ * handler so server, CLI, and future adapters share one stop contract.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleStop = handleStop;
+const sdk_1 = require("@crewx/sdk");
+const repository_1 = require("@crewx/sdk/repository");
+const cal_1 = require("./cal");
+function parseGrace(args) {
+    const flag = args.find((arg) => arg === '--grace' || arg.startsWith('--grace='));
+    if (!flag)
+        return { graceMs: 5_000 };
+    const raw = flag === '--grace'
+        ? args[args.indexOf(flag) + 1]
+        : flag.slice('--grace='.length);
+    const value = Number(raw);
+    if (!raw || !Number.isFinite(value) || value < 0) {
+        return { graceMs: 5_000, error: `Invalid --grace value: ${raw ?? '(missing)'}` };
+    }
+    return { graceMs: Math.trunc(value) };
+}
+function taskIdFromArgs(args) {
+    return args.find((arg, index) => {
+        if (arg === '--grace')
+            return false;
+        if (index > 0 && args[index - 1] === '--grace')
+            return false;
+        return !arg.startsWith('--');
+    });
+}
+function writeUsage() {
+    process.stderr.write('Error: Please provide a task ID or use --all to stop all running tasks.\n');
+    process.stderr.write('\nUsage:\n');
+    process.stderr.write('  crewx stop <task-id>    Stop a running task\n');
+    process.stderr.write('  crewx stop --all        Stop all running tasks\n');
+    process.stderr.write('  crewx stop <task-id> --grace=<ms>\n');
+}
+function formatGrace(graceMs) {
+    return `${graceMs / 1000}s`;
+}
+function reportResult(taskId, result, elapsedMs, graceMs) {
+    if (result.status === 'stopped') {
+        if (result.method === 'forced') {
+            process.stdout.write(`Stopped ${taskId} (forced after ${formatGrace(graceMs)} grace)\n`);
+        }
+        else {
+            process.stdout.write(`Stopped ${taskId} (cooperative, ${(elapsedMs / 1000).toFixed(1)}s)\n`);
+        }
+        return 0;
+    }
+    if (result.status === 'not_running') {
+        process.stdout.write(`Task ${taskId} is not running (${result.finalStatus ?? 'unknown'})\n`);
+        return 0;
+    }
+    if (result.status === 'already_requested') {
+        process.stderr.write(`Task ${taskId} already has a stop request; it remains ${result.finalStatus ?? 'running'}.\n`);
+        return 2;
+    }
+    if (result.status === 'ownership_unverified') {
+        const pid = result.pid ? ` (pid ${result.pid})` : '';
+        process.stderr.write(`Could not verify the process owner of ${taskId}; not terminated${pid}. ` +
+            'Row stays running — the reaper will settle it.\n');
+        return 2;
+    }
+    process.stderr.write(`Could not stop ${taskId}: ${result.error ?? 'unknown error'}\n`);
+    return 1;
+}
+/** Handle `crewx stop` and the compatibility `crewx kill` alias. */
+async function handleStop(args, invokedAs = 'stop') {
+    if (invokedAs === 'kill')
+        process.stderr.write('kill is an alias of stop\n');
+    const stopAll = args.includes('--all');
+    const { graceMs, error } = parseGrace(args);
+    if (error) {
+        process.stderr.write(`Error: ${error}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const taskId = taskIdFromArgs(args);
+    if (!taskId && !stopAll) {
+        writeUsage();
+        process.exitCode = 1;
+        return;
+    }
+    const repo = new repository_1.TaskRepository();
+    const stopOne = async (id, withFooter) => {
+        const startedAt = Date.now();
+        const result = await (0, sdk_1.stopTask)(repo, id, { graceMs, origin: 'cli' });
+        const exitCode = reportResult(id, result, Date.now() - startedAt, graceMs);
+        if (withFooter && (result.status === 'stopped' || result.status === 'not_running')) {
+            (0, cal_1.writeCalFooter)({
+                commandId: 'crewx.stop.done',
+                params: { taskId: id },
+            });
+        }
+        return exitCode;
+    };
+    if (stopAll) {
+        const running = repo.getRunningTasks();
+        if (running.length === 0) {
+            process.stdout.write('No running tasks found.\n');
+            return;
+        }
+        let exitCode = 0;
+        for (const task of running) {
+            exitCode = Math.max(exitCode, await stopOne(task.id, false));
+        }
+        if (exitCode > 0)
+            process.exitCode = exitCode;
+        return;
+    }
+    const exitCode = await stopOne(taskId, true);
+    if (exitCode > 0)
+        process.exitCode = exitCode;
+}

package/dist/index.d.ts

@@ -1 +1 @@
-export { handleInit, type InitResult } from './commands/init';
+export { buildDefaultAgents, handleInit, parseInitProvider, resolveInitProvider, type InitProvider, type InitResult, } from './commands/init';

package/dist/index.js

@@ -1,5 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.handleInit = void 0;
+exports.resolveInitProvider = exports.parseInitProvider = exports.handleInit = exports.buildDefaultAgents = void 0;
 var init_1 = require("./commands/init");
+Object.defineProperty(exports, "buildDefaultAgents", { enumerable: true, get: function () { return init_1.buildDefaultAgents; } });
 Object.defineProperty(exports, "handleInit", { enumerable: true, get: function () { return init_1.handleInit; } });
+Object.defineProperty(exports, "parseInitProvider", { enumerable: true, get: function () { return init_1.parseInitProvider; } });
+Object.defineProperty(exports, "resolveInitProvider", { enumerable: true, get: function () { return init_1.resolveInitProvider; } });

package/dist/logging.d.ts

@@ -9,7 +9,7 @@
  *
  * Format mirrors cli-bak TaskManagementService for backward compatibility.
  */
-import type { Crewx } from '@crewx/sdk';
+import { type Crewx } from '@crewx/sdk';
 /**
  * Attach file-based logging to a Crewx instance.
  * Subscribes to task:start and task:end events and writes log files.

package/dist/logging.js

@@ -14,6 +14,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.attachFileLogger = attachFileLogger;
 const fs_1 = require("fs");
 const path_1 = require("path");
+const sdk_1 = require("@crewx/sdk");
 const CREWX_VERSION = '0.9.0-alpha.1';
 /** Format Date as YYYYMMDDTHHmmss (local time) */
 function formatTimestamp(date) {
@@ -52,7 +53,7 @@ function attachFileLogger(crewx, workspaceRoot) {
                 `CrewX Version: ${CREWX_VERSION}\n` +
                 `Mode: ${event.mode}\n` +
                 `Agent: ${event.agentRef}\n` +
-                `Started: ${event.timestamp.toLocaleString()}\n` +
+                `Started: ${(0, sdk_1.formatDisplayTimestamp)(event.timestamp)}\n` +
                 `Message: ${event.message}\n` +
                 `\n`;
             (0, fs_1.writeFileSync)(logFile, header, { encoding: 'utf8', mode: 0o600 });
@@ -66,7 +67,7 @@ function attachFileLogger(crewx, workspaceRoot) {
             const logFile = logFiles.get(event.traceId);
             if (!logFile)
                 return;
-            const ts = new Date().toLocaleString();
+            const ts = (0, sdk_1.formatDisplayTimestamp)(new Date());
             const status = event.error
                 ? `failed: ${event.error.message}`
                 : 'completed successfully';

package/dist/main.d.ts

@@ -5,7 +5,8 @@
  *
  * Boot sequence:
  *   1. Inject CREWX_CLI / CREWX_WORKSPACE env defaults (must be first)
- *   2. Parse command
- *   3. Dispatch to handler
+ *   2. Load workspace and ~/.crewx .env files (does not override process.env)
+ *   3. Parse command
+ *   4. Dispatch to handler
  */
 export {};

package/dist/main.js

@@ -6,8 +6,9 @@
  *
  * Boot sequence:
  *   1. Inject CREWX_CLI / CREWX_WORKSPACE env defaults (must be first)
- *   2. Parse command
- *   3. Dispatch to handler
+ *   2. Load workspace and ~/.crewx .env files (does not override process.env)
+ *   3. Parse command
+ *   4. Dispatch to handler
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -45,26 +46,36 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 // ─── P0-1: Env Bootstrap ─────────────────────────────────────────────────────
 // Must run before any other code that might use process.env.CREWX_CLI.
-const env_defaults_1 = require("./utils/env-defaults");
+const sdk_compat_1 = require("./utils/sdk-compat");
+const account_1 = require("@crewx/sdk/account");
 const sdk_1 = require("@crewx/sdk");
-process.env.CREWX_CLI ??= (0, env_defaults_1.resolveCrewxCli)();
-process.env.CREWX_WORKSPACE ??= (0, env_defaults_1.resolveCrewxWorkspace)();
+const inherited_trace_1 = require("./utils/inherited-trace");
+process.env.CREWX_CLI ??= sdk_compat_1.sdkCompat.resolveCrewxCli();
+process.env.CREWX_WORKSPACE ??= sdk_compat_1.sdkCompat.resolveCrewxWorkspace();
+// Load workspace .env before ~/.crewx/.env. The SDK-owned loader keeps CLI and
+// server bootstrap on the same process > workspace > home precedence contract.
+(0, account_1.loadCrewxEnvFiles)();
+// Receipt runner identity is a one-hop capability. Consume it before any
+// command/provider code can spawn a child process.
+(0, inherited_trace_1.consumeInheritedRunnerIdentity)();
 // ─── Pricing remote override (WI-20260701-002) ───────────────────────────────
 // Best-effort, non-blocking: fetch remote model registry so new models get
 // accurate pricing without a CLI republish. Falls back to bundled table on
 // failure / offline. Browser entry does not call this automatically.
-void (0, sdk_1.initPricingRemote)();
+sdk_compat_1.sdkCompat.initPricingRemote();
 // ─── Command Imports ──────────────────────────────────────────────────────────
 const query_1 = require("./commands/query");
 const execute_1 = require("./commands/execute");
 const agent_1 = require("./commands/agent");
 const ps_1 = require("./commands/ps");
-const kill_1 = require("./commands/kill");
+const stop_1 = require("./commands/stop");
 const result_1 = require("./commands/result");
 const restart_1 = require("./commands/restart");
 const log_1 = require("./commands/log");
 const doctor_1 = require("./commands/doctor");
 const init_1 = require("./commands/init");
+const shortcut_1 = require("./commands/shortcut");
+const publish_1 = require("./commands/publish");
 const builtin_1 = require("./builtin");
 const slack_1 = require("./commands/slack");
 const install_1 = require("./commands/hook/install");
@@ -75,6 +86,8 @@ const db_1 = require("./commands/db");
 const parse_common_flags_1 = require("./commands/parse-common-flags");
 const registry_1 = require("./commands/registry");
 const version_1 = require("./utils/version");
+const product_package_root_1 = require("./utils/product-package-root");
+const emit_trailer_1 = require("./commands/emit-trailer");
 /**
  * Dev-only SSOT assertion: bin/cli-commands.js must be the exact union of
  * KNOWN_COMMANDS ∪ BUILTIN_COMMAND_NAMES ∪ NOT_YET_MIGRATED from registry.ts.
@@ -99,7 +112,7 @@ async function assertSsotParity() {
             (extra.length ? `  CLI_SUBCOMMANDS has, registry missing: ${extra.join(', ')}` : ''));
     }
 }
-async function main() {
+async function main(emitState) {
     if (process.env['NODE_ENV'] === 'development') {
         await assertSsotParity();
     }
@@ -111,7 +124,10 @@ async function main() {
     }
     // Built-in tools: memory, search, doc, wbs, cron, workflow, skill
     if (builtin_1.BUILTIN_COMMANDS.has(command)) {
-        await (0, builtin_1.handleBuiltin)(command, args.slice(1));
+        const productPackageRoot = command === 'skill'
+            ? (0, product_package_root_1.resolveProductRootFromCliEntry)(process.argv[1])
+            : undefined;
+        await (0, builtin_1.handleBuiltin)(command, args.slice(1), productPackageRoot);
         return;
     }
     // Core commands
@@ -119,11 +135,11 @@ async function main() {
         // P0-2: q/x aliases
         case 'q':
         case 'query':
-            await (0, query_1.handleQuery)(args.slice(1));
+            await (0, query_1.handleQuery)(args.slice(1), command, emitState);
             return;
         case 'x':
         case 'execute':
-            await (0, execute_1.handleExecute)(args.slice(1));
+            await (0, execute_1.handleExecute)(args.slice(1), command, emitState);
             return;
         case 'agent':
             await (0, agent_1.handleAgent)(args.slice(1));
@@ -132,9 +148,12 @@ async function main() {
         case 'ps':
             await (0, ps_1.handlePs)(args.slice(1));
             return;
-        // P0-5: kill
+        // Task stop (kill is a compatibility alias)
+        case 'stop':
+            await (0, stop_1.handleStop)(args.slice(1), 'stop');
+            return;
         case 'kill':
-            await (0, kill_1.handleKill)(args.slice(1));
+            await (0, stop_1.handleStop)(args.slice(1), 'kill');
             return;
         // P0-6: result
         case 'result':
@@ -157,7 +176,8 @@ async function main() {
             const initArgs = args.slice(1);
             const force = initArgs.includes('--force') || initArgs.includes('-f');
             try {
-                const r = await (0, init_1.handleInit)({ path: process.cwd(), force });
+                const provider = (0, init_1.parseInitProvider)(initArgs);
+                const r = await (0, init_1.handleInit)({ path: process.cwd(), force, provider });
                 if (r.skippedReason === 'yaml-exists') {
                     console.log('✓ crewx.yaml already exists (use --force to overwrite)');
                 }
@@ -167,6 +187,10 @@ async function main() {
                     if (r.errors.length > 0)
                         console.warn('Warnings:', r.errors.join('; '));
                 }
+                const profile = (0, sdk_1.getDefaultAgentProfile)(r.provider);
+                if (profile) {
+                    console.log(`✓ default agents: ${r.provider} (${profile.planner.model} / ${profile.worker.model})`);
+                }
                 if (r.workspaceId)
                     console.log(`✓ workspace registered (id=${r.workspaceId}, slug=${r.slug})`);
                 console.log('✓ done');
@@ -181,6 +205,14 @@ async function main() {
         case 'db':
             await (0, db_1.handleDb)(args.slice(1));
             return;
+        // Windows Desktop shortcut: crewx shortcut status|install|uninstall
+        case 'shortcut':
+            await (0, shortcut_1.handleShortcut)(args.slice(1));
+            return;
+        // crewx publish [dir] [--dry-run] [--version <semver>] [--json] [--upload]
+        case 'publish':
+            await (0, publish_1.handlePublish)(args.slice(1));
+            return;
         // SDK-009: slack / slack:files
         case 'slack':
         case 'slack:files':
@@ -248,12 +280,14 @@ UI Modes:
   crewx electron [--overlay]     Launch Electron (desktop or overlay window)
 
 Query / Execute:
-  q|query "@agent <message>"     Query an agent (quoted single string)
-  x|execute "@agent <task>"      Execute a task with an agent (quoted single string)
+  q|query --to <agent> <message> Query an agent
+  x|execute --to <agent> <task>  Execute a task with an agent
 
-  @agent is optional — defaults to @crewx when omitted.
+  Positional @agent <message> is shorthand for selecting a recipient.
+  Agent calls require a recipient; human terminal and cron calls default to @crewx.
 
   Common flags:
+    --to <agent>                 Explicit agent recipient
     --thread <name>              Conversation thread
     --provider <cli/xxx>         Provider override
     --metadata <json>            Extra metadata (JSON object, double-quoted). Propagated to events/hooks/tracing.
@@ -262,11 +296,18 @@ Query / Execute:
     --verbose                    Debug output mode (default: raw response only)
     --config/-c <path>           Config file path (default: CREWX_CONFIG or crewx.yaml)
     --output-format <fmt>        Output format (json|text|stream-json)
+    --out/-o <path>              Save result to file (stdout suppressed)
     --effort <level>             Model effort (high|medium|low)
-    -f/--prompt-file <path>      Read task body from file (bypasses argv length limits)
+    -f/--prompt-file <path>      Read body only from file; set recipient with --to (bypasses argv length limits)
     --var key=value              Template variable (repeatable). Accessible as {{key}} in agent prompt.
     --                           End of flags; remaining tokens treated as message text
-                                 e.g. crewx q "@agent label" -- --flag-in-message
+                                 e.g. crewx q --to agent "label" -- --flag-in-message
+
+  q/query/x/execute:
+    --detach/--async              Persist a receipt, launch a detached runner, and print task-id
+                                 (automatic inside an agent process; q/x stay synchronous elsewhere).
+    --wait                        Force synchronous execution, including inside an agent process.
+                                 e.g. crewx x --to agent "label" --detach
 
 Agent Management:
   agent ls [options]             List configured agents
@@ -277,20 +318,42 @@ Agent Management:
 
 Task Management:
   ps                             List running tasks
-  kill <task-id>                 Kill a running task
-  kill --all                     Kill all running tasks
+  stop <task-id>                 Stop a running task (cooperative, then forced)
+  stop --all                     Stop all running tasks
+  kill <task-id>                 Alias for stop
   result [task-id]               Get task result (or list recent tasks)
+    --wait=N                     Poll (1s interval) up to N seconds for the task to
+                                 finish. Exit 124 on timeout. --wait=0 = single check.
   restart <task-id>              Restart a failed task as a new task
 
 Logs & Diagnostics:
   log [ls|<task-id>]             View task logs
   doctor [--config <path>]       Run system diagnosis
-  init [--force] [--config <p>]  Initialize crewx.yaml
+  init [--force] [--provider cli/claude|cli/codex]  Initialize crewx.yaml
 
 Database:
   db push                        Sync DB schema to current code (additive only)
     --force                      Reset migration history + skip confirmation
     --dry-run                    Preview changes without applying
+  db migrate-task-logs           Backfill legacy tasks.logs into task_log_events
+    --dry-run                    Validate and estimate without writing
+    --apply                      Consistent backup + resumable task-by-task apply
+    --verify                     Check event/source invariants and parity
+  db migrate-request-logs        Move request logs from crewx.db into logs.db (bodies stored once)
+    --batch N                    Rows per batch (default 250)
+    --dry-run                    Count rows and distinct bodies without writing
+
+Desktop Shortcut (Windows only):
+  shortcut status [--json]                Show current shortcut status
+  shortcut install [--force] [--json]     Install/repair the Desktop shortcut
+  shortcut uninstall [--json]             Remove the Desktop shortcut
+
+Publish:
+  publish [dir] [options]         Package a workspace as a distributable template archive
+    --dry-run                     Scan + build manifest only; do not write a .tgz
+    --version <ver>               Override manifest version (semver)
+    --json                        Print machine-readable JSON to stdout
+    --upload                      Submit + upload using the SDK account session
 
 Built-in Tools:
   memory <args>                  Memory tool
@@ -312,7 +375,19 @@ Global Options:
   --version, -v                  Show version
 `.trim());
 }
-main().catch((err) => {
+function getProcessExitCode(error) {
+    if (error instanceof parse_common_flags_1.UnknownOptionError)
+        return 2;
+    if (typeof error === 'object' && error !== null && 'exitCode' in error) {
+        const exitCode = error.exitCode;
+        if (typeof exitCode === 'number')
+            return exitCode;
+    }
+    return 1;
+}
+const emitState = (0, emit_trailer_1.createDelegationEmitState)();
+main(emitState).catch((err) => {
     console.error(err instanceof Error ? err.message : String(err));
-    process.exit(err instanceof parse_common_flags_1.UnknownOptionError ? 2 : 1);
+    (0, emit_trailer_1.emitDelegationResult)({ command: process.argv[2], isError: true, state: emitState });
+    process.exit(getProcessExitCode(err));
 });

package/dist/utils/env-defaults.d.ts

@@ -1,5 +1,2 @@
-/**
- * CREWX_* environment variable defaults for CLI bootstrap.
- * Re-exported from @crewx/sdk for convenience.
- */
-export { resolveCrewxCli, resolveCrewxWorkspace } from '@crewx/sdk';
+export declare function resolveCrewxCli(): string;
+export declare function resolveCrewxWorkspace(): string;

package/dist/utils/env-defaults.js

@@ -1,10 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveCrewxWorkspace = exports.resolveCrewxCli = void 0;
+exports.resolveCrewxCli = resolveCrewxCli;
+exports.resolveCrewxWorkspace = resolveCrewxWorkspace;
 /**
  * CREWX_* environment variable defaults for CLI bootstrap.
- * Re-exported from @crewx/sdk for convenience.
+ * Routed through the SDK compatibility accessor for older SDK installations.
  */
-var sdk_1 = require("@crewx/sdk");
-Object.defineProperty(exports, "resolveCrewxCli", { enumerable: true, get: function () { return sdk_1.resolveCrewxCli; } });
-Object.defineProperty(exports, "resolveCrewxWorkspace", { enumerable: true, get: function () { return sdk_1.resolveCrewxWorkspace; } });
+const sdk_compat_1 = require("./sdk-compat");
+function resolveCrewxCli() {
+    return sdk_compat_1.sdkCompat.resolveCrewxCli();
+}
+function resolveCrewxWorkspace() {
+    return sdk_compat_1.sdkCompat.resolveCrewxWorkspace();
+}

package/dist/utils/inherited-trace.d.ts

@@ -1,4 +1,19 @@
 import type { TraceContext } from '@crewx/sdk';
+export interface InheritedRunnerIdentity {
+    assignedTaskId?: string;
+    detachedRunner: boolean;
+}
+/**
+ * Consume the runner-only identity exactly once.
+ *
+ * These variables are a one-hop capability, not trace context. Keeping the
+ * values in this module lets the current CLI process use them while deleting
+ * them from process.env prevents later child processes from inheriting the
+ * receipt runner identity.
+ */
+export declare function consumeInheritedRunnerIdentity(): InheritedRunnerIdentity;
+/** Test-only reset for the module-level one-shot cache. */
+export declare function resetInheritedRunnerIdentityForTests(): void;
 /**
  * Read cross-process trace context from inherited environment variables.
  *
@@ -10,3 +25,12 @@ import type { TraceContext } from '@crewx/sdk';
  * Returns undefined when none of the three vars are set (root invocation).
  */
 export declare function readInheritedTrace(): TraceContext | undefined;
+/**
+ * Read the pre-assigned task id carried only by a detached runner.
+ *
+ * This is deliberately separate from readInheritedTrace(): trace variables
+ * describe the caller's chain and must not be used as this task's identity.
+ */
+export declare function readRunnerAssignment(): string | undefined;
+/** Return true only for the final detached runner process. */
+export declare function isDetachedRunner(): boolean;

package/dist/utils/inherited-trace.js

@@ -1,6 +1,33 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.consumeInheritedRunnerIdentity = consumeInheritedRunnerIdentity;
+exports.resetInheritedRunnerIdentityForTests = resetInheritedRunnerIdentityForTests;
 exports.readInheritedTrace = readInheritedTrace;
+exports.readRunnerAssignment = readRunnerAssignment;
+exports.isDetachedRunner = isDetachedRunner;
+let inheritedRunnerIdentity;
+/**
+ * Consume the runner-only identity exactly once.
+ *
+ * These variables are a one-hop capability, not trace context. Keeping the
+ * values in this module lets the current CLI process use them while deleting
+ * them from process.env prevents later child processes from inheriting the
+ * receipt runner identity.
+ */
+function consumeInheritedRunnerIdentity() {
+    if (inheritedRunnerIdentity !== undefined)
+        return inheritedRunnerIdentity;
+    const assignedTaskId = process.env['CREWX_ASSIGNED_TASK_ID']?.trim() || undefined;
+    const detachedRunner = process.env['CREWX_DETACHED_RUNNER'] === '1';
+    delete process.env['CREWX_ASSIGNED_TASK_ID'];
+    delete process.env['CREWX_DETACHED_RUNNER'];
+    inheritedRunnerIdentity = { assignedTaskId, detachedRunner };
+    return inheritedRunnerIdentity;
+}
+/** Test-only reset for the module-level one-shot cache. */
+function resetInheritedRunnerIdentityForTests() {
+    inheritedRunnerIdentity = undefined;
+}
 /**
  * Read cross-process trace context from inherited environment variables.
  *
@@ -23,3 +50,16 @@ function readInheritedTrace() {
         callerAgentId,
     };
 }
+/**
+ * Read the pre-assigned task id carried only by a detached runner.
+ *
+ * This is deliberately separate from readInheritedTrace(): trace variables
+ * describe the caller's chain and must not be used as this task's identity.
+ */
+function readRunnerAssignment() {
+    return consumeInheritedRunnerIdentity().assignedTaskId;
+}
+/** Return true only for the final detached runner process. */
+function isDetachedRunner() {
+    return consumeInheritedRunnerIdentity().detachedRunner;
+}

package/dist/utils/product-package-root.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Finds the installed product root from the CLI entry file that is running.
+ * The real CLI path is walked to the first package named `crewx`, which must
+ * contain the compiled bundle helper. cwd and environment are deliberately ignored.
+ */
+export declare function resolveProductRootFromCliEntry(cliEntryPath: string | undefined): string | undefined;

package/dist/utils/product-package-root.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveProductRootFromCliEntry = resolveProductRootFromCliEntry;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const PRODUCT_BUNDLE_HELPER = (0, node_path_1.join)('dist-server', 'common', 'product-app-bundle.js');
+/**
+ * Finds the installed product root from the CLI entry file that is running.
+ * The real CLI path is walked to the first package named `crewx`, which must
+ * contain the compiled bundle helper. cwd and environment are deliberately ignored.
+ */
+function resolveProductRootFromCliEntry(cliEntryPath) {
+    if (typeof cliEntryPath !== 'string' || cliEntryPath.trim().length === 0)
+        return undefined;
+    let realCliEntryPath;
+    try {
+        realCliEntryPath = (0, node_fs_1.realpathSync)(cliEntryPath);
+    }
+    catch {
+        return undefined;
+    }
+    let current = (0, node_path_1.dirname)(realCliEntryPath);
+    while (true) {
+        try {
+            const packageJson = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(current, 'package.json'), 'utf8'));
+            if (packageJson.name === 'crewx') {
+                return (0, node_fs_1.existsSync)((0, node_path_1.join)(current, PRODUCT_BUNDLE_HELPER)) ? current : undefined;
+            }
+        }
+        catch {
+            // Continue to the next ancestor when this directory has no valid package manifest.
+        }
+        const parent = (0, node_path_1.dirname)(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+    return undefined;
+}

package/dist/utils/sdk-compat.d.ts

@@ -0,0 +1,24 @@
+import type { CrewxExecutableResolution } from '@crewx/sdk';
+type PricingInitializer = () => Promise<unknown> | unknown;
+export interface SdkLike {
+    resolveCrewxCli?: () => string;
+    resolveCrewxCliArgv?: () => CrewxExecutableResolution;
+    resolveCrewxWorkspace?: () => string;
+    initPricingRemote?: PricingInitializer;
+}
+export interface SdkCompat {
+    resolveCrewxCli(): string;
+    resolveCrewxCliArgv(): CrewxExecutableResolution;
+    resolveCrewxWorkspace(): string;
+    initPricingRemote(): void;
+}
+/**
+ * Create the CLI bootstrap capability accessor for the installed SDK.
+ *
+ * SDK exports are additive across compatible majors, so an older SDK may not
+ * expose every capability that a newer CLI knows about. Optional capabilities
+ * are checked here rather than at each bootstrap call site.
+ */
+export declare function createSdkCompat(sdkLike?: SdkLike): SdkCompat;
+export declare const sdkCompat: SdkCompat;
+export {};