@crewx/cli 0.9.0-rc.16 → 0.9.0-rc.161

package/dist/commands/db.js

@@ -1,125 +1,59 @@
-"use strict";
-/**
- * crewx db push handler.
- *
- * Usage:
- *   crewx db push               Preview changes → confirm → apply
- *   crewx db push --force        Apply without confirmation + reset migration history
- *   crewx db push --dry-run      Show preview only, no changes
- */
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.handleDb = handleDb;
-const path_1 = __importDefault(require("path"));
-const os_1 = __importDefault(require("os"));
-const readline_1 = __importDefault(require("readline"));
-const repository_1 = require("@crewx/sdk/repository");
-const repository_2 = require("@crewx/sdk/repository");
-function defaultDbPath() {
-    return path_1.default.join(os_1.default.homedir(), '.crewx', 'crewx.db');
-}
-function formatPreview(result, dbPath) {
-    const lines = [];
-    lines.push(`[crewx] Database push — comparing schema vs ${dbPath}`);
-    lines.push('');
-    if (result.created.length > 0) {
-        lines.push(`  Tables to create:`);
-        for (const t of result.created) {
-            lines.push(`    → ${t}`);
-        }
-    }
-    else {
-        lines.push('  Tables to create: (none)');
-    }
-    if (result.altered.length > 0) {
-        lines.push('  Columns to add:');
-        for (const { table, column } of result.altered) {
-            lines.push(`    → ${table}.${column}`);
-        }
-    }
-    else {
-        lines.push('  Columns to add: (none)');
-    }
-    if (result.warnings.length > 0) {
-        lines.push('  Warnings:');
-        for (const w of result.warnings) {
-            lines.push(`    ⚠ ${w}`);
-        }
-    }
-    if (result.backupPath) {
-        lines.push('');
-        lines.push(`  Backup: ${result.backupPath}`);
-    }
-    return lines.join('\n');
-}
-function hasChanges(result) {
-    return result.created.length > 0 || result.altered.length > 0;
-}
-function prompt(question) {
-    const rl = readline_1.default.createInterface({ input: process.stdin, output: process.stdout });
-    return new Promise((resolve) => {
-        rl.question(question, (answer) => {
-            rl.close();
-            resolve(answer);
-        });
-    });
-}
-async function handleDb(args) {
-    const subcommand = args[0];
-    if (!subcommand || subcommand === 'push') {
-        await handleDbPush(args.slice(subcommand === 'push' ? 1 : 0));
-        return;
-    }
-    console.error(`Unknown db subcommand: ${subcommand}`);
-    console.error('Usage: crewx db push [--force] [--dry-run]');
-    process.exit(1);
-}
-async function handleDbPush(args) {
-    const force = args.includes('--force');
-    const dryRun = args.includes('--dry-run');
-    const dbPath = defaultDbPath();
-    const handle = (0, repository_1.openDrizzleDb)(dbPath);
-    try {
-        // 1. Compute preview (dry-run pass — no changes yet)
-        const preview = (0, repository_2.pushSchema)(handle.db, { force, dbPath, dryRun: true });
-        console.log(formatPreview(preview, dbPath));
-        console.log('');
-        if (dryRun) {
-            console.log('[crewx] Dry-run mode — no changes applied.');
-            return;
-        }
-        if (!hasChanges(preview)) {
-            console.log('[crewx] No changes needed. Database is up to date.');
-            return;
-        }
-        // 2. Confirm unless --force
-        if (!force) {
-            const answer = await prompt('Apply changes? (y/N): ');
-            if (answer.trim().toLowerCase() !== 'y') {
-                console.log('[crewx] Aborted.');
-                return;
-            }
-        }
-        // 3. Apply
-        const result = (0, repository_2.pushSchema)(handle.db, { force, dbPath });
-        console.log('');
-        console.log('[crewx] Push complete.');
-        if (result.created.length > 0) {
-            console.log(`  Tables created: ${result.created.join(', ')}`);
-        }
-        if (result.altered.length > 0) {
-            console.log(`  Columns added: ${result.altered.map((a) => `${a.table}.${a.column}`).join(', ')}`);
-        }
-        if (result.backupPath) {
-            console.log(`  Backup: ${result.backupPath}`);
-        }
-        if (result.created.length === 0 && result.altered.length === 0) {
-            console.log('  No changes applied.');
-        }
-    }
-    finally {
-        handle.close();
-    }
-}
+"use strict";var g=exports&&exports.__importDefault||function(e){return e&&e.__esModule?e:{"default":e}};Object.defineProperty(exports,"__esModule",{value:true});exports.USAGE_BACKFILL_HELP=exports.REQUEST_LOG_MIGRATION_HELP=exports.TASK_LOG_MIGRATION_HELP=void 0;exports.handleDb=P;const $=g(require("path"));const v=g(require("os"));const R=g(require("readline"));const T=require("@crewx/sdk/repository");const m=require("@crewx/sdk/repository");const x=require("@crewx/sdk/repository");const p=require("@crewx/sdk/repository");const _=require("@crewx/sdk/repository");exports.TASK_LOG_MIGRATION_HELP=`Usage:
+  crewx db migrate-task-logs --dry-run [--db PATH]
+  crewx db migrate-task-logs --apply [--db PATH] [--batch-tasks N]
+  crewx db migrate-task-logs --verify [--db PATH]
+
+Modes:
+  --dry-run  Read and validate legacy blobs without writing or creating a backup.
+  --apply    Create a consistent SQLite backup, then migrate one task per transaction.
+  --verify   Check source invariants, event sequences, counts, and orphan rows.
+
+Apply policy:
+  Only blob tasks with status success, failed, or completed are migrated.
+  pending, running, paused, and unknown statuses are deferred for a later run.
+  There is no --force or --include-active option. Apply requires the estimated
+  database/event growth plus a 10 GiB free-space reserve.
+
+Exit codes:
+  0  Completed with no malformed rows or invariant failures.
+  1  Safe tasks completed but a row/invariant failed, or apply was blocked.
+  2  Invalid command-line arguments.
+
+The command never runs automatically at server startup and never runs VACUUM.`;exports.REQUEST_LOG_MIGRATION_HELP=`Usage:
+  crewx db migrate-request-logs [--batch N] [--dry-run]
+
+Moves the request log rows still stored in crewx.db into logs.db, the file next
+to it. Each distinct request/response body is stored once in logs.db, keyed by
+its SHA-256; a row points to its bodies by hash, so nothing is dropped.
+
+Options:
+  --batch N   Rows per batch (default 250; a batch is also capped at about 8 MB).
+  --dry-run   Count rows and distinct bodies without writing anything (logs.db is not created).
+
+Safe while crewx is running: each batch is committed to logs.db, verified there,
+and only then deleted from crewx.db in one short transaction. Interrupt it and run
+it again at any time. The database is chosen like everywhere else (CREWX_DB, else
+~/.crewx/crewx.db). No VACUUM and no DROP: crewx.db keeps its size until a later compaction.
+
+Exit codes:
+  0  Every row is in logs.db and none is left in crewx.db (or the dry run finished).
+  1  Rows are still in crewx.db, or an error stopped the move (progress is kept).
+  2  Invalid command-line arguments.`;exports.USAGE_BACKFILL_HELP=`Usage:
+  crewx db backfill-usage [--dry-run|--apply|--verify] [--db PATH] [--backup PATH]
+  crewx db backfill-usage --restore SNAPSHOT [--db PATH]
+
+Modes:
+  --dry-run  Show provider/reason recovery plans without changing the database (default).
+  --apply    Create a row-level undo snapshot, then account one task per transaction.
+  --verify   Recheck remaining targets and usageAccounting markers without changing the database.
+  --restore  Restore rows from SNAPSHOT when their current values still match the snapshot after-state.
+
+Apply policy:
+  Only success, failed, and completed tasks with zero recorded usage are considered.
+  Workflow/MCP anchors and plugin/mock rows are excluded. Rows completed within 24 hours
+  are not marked unavailable when their logs do not contain usage.
+
+Exit codes:
+  0  Completed successfully.
+  1  Apply was blocked or one or more task updates failed.
+  2  Invalid command-line arguments.`;function E(){return $.default.join(v.default.homedir(),".crewx","crewx.db")}function S(e,o){const s=[];s.push(`[crewx] Database push \u2014 comparing schema vs ${o}`);s.push("");if(e.created.length>0){s.push(`  Tables to create:`);for(const n of e.created){s.push(`    \u2192 ${n}`)}}else{s.push("  Tables to create: (none)")}if(e.altered.length>0){s.push("  Columns to add:");for(const{table:n,column:r}of e.altered){s.push(`    \u2192 ${n}.${r}`)}}else{s.push("  Columns to add: (none)")}if(e.warnings.length>0){s.push("  Warnings:");for(const n of e.warnings){s.push(`    \u26A0 ${n}`)}}if(e.backupPath){s.push("");s.push(`  Backup: ${e.backupPath}`)}return s.join("\n")}function L(e){return e.created.length>0||e.altered.length>0}function y(e){const o=Object.entries(e??{});return o.length>0?o.map(([s,n])=>`${s}=${n}`).join(", "):"(none)"}function A(e){const o=R.default.createInterface({input:process.stdin,output:process.stdout});return new Promise(s=>{o.question(e,n=>{o.close();s(n)})})}async function P(e){const o=e[0];if(o==="migrate-task-logs"){await B(e.slice(1));return}if(o==="migrate-request-logs"){await G(e.slice(1));return}if(o==="backfill-usage"){await N(e.slice(1));return}if(o==="--help"||o==="-h"){console.log("Usage: crewx db push [--force] [--dry-run]");console.log(exports.TASK_LOG_MIGRATION_HELP);console.log(exports.REQUEST_LOG_MIGRATION_HELP);return}if(!o||o==="push"){await H(e.slice(o==="push"?1:0));return}console.error(`Unknown db subcommand: ${o}`);console.error("Usage: crewx db push [--force] [--dry-run]");console.error(exports.TASK_LOG_MIGRATION_HELP);process.exitCode=2}class d extends Error{}class u extends Error{}function M(e){let o;let s;let n;const r=a=>{if(o)throw new d("Choose exactly one of --dry-run, --apply, or --verify.");o=a};const t=(a,c,l)=>{const i=a[c+1];if(!i||i.startsWith("--"))throw new d(`${l} requires a value.`);return i};for(let a=0;a<e.length;a+=1){const c=e[a];if(c==="--help"||c==="-h"){throw new d(exports.TASK_LOG_MIGRATION_HELP)}if(c==="--dry-run"){r("dry-run");continue}if(c==="--apply"){r("apply");continue}if(c==="--verify"){r("verify");continue}if(c==="--db"){s=t(e,a,"--db");a+=1;continue}if(c.startsWith("--db=")){s=c.slice("--db=".length);if(!s)throw new d("--db requires a value.");continue}if(c==="--batch-tasks"){const l=t(e,a,"--batch-tasks");const i=Number(l);if(!Number.isSafeInteger(i)||i<1){throw new d("--batch-tasks must be a positive integer.")}n=i;a+=1;continue}if(c.startsWith("--batch-tasks=")){const l=c.slice("--batch-tasks=".length);const i=Number(l);if(!Number.isSafeInteger(i)||i<1){throw new d("--batch-tasks must be a positive integer.")}n=i;continue}throw new d(`Unknown option: ${c}`)}if(!o)throw new d("Choose one of --dry-run, --apply, or --verify.");if(n!==void 0&&o!=="apply"){throw new d("--batch-tasks is only valid with --apply.")}return{mode:o,dbPath:s,batchTasks:n}}function C(e){const o=e.mode==="dry-run"?"Dry-run":e.mode==="apply"?"Apply":"Verify";const s=[`[crewx] Task-log migration \u2014 ${o}`,`  Database: ${e.dbPath}`,`  Tasks scanned: ${e.taskCount}`,`  Blob candidates: ${e.candidateTaskCount}`,`  Eligible terminal blobs: ${e.eligibleTaskCount}`,`  Status counts: ${y(e.statusCounts)}`,`  Deferred blob tasks: ${e.deferredTaskCount}`,`  Deferred statuses: ${y(e.deferredStatusCounts)}`,`  Entries: ${e.entryCount}`,`  Source bytes: ${e.sourceBytes}`,`  Estimated free-space need: ${e.estimatedFreeSpaceBytes}`,`  Required free space (with reserve): ${e.requiredFreeSpaceBytes}`,`  Available free space: ${e.availableFreeSpaceBytes}`,`  Free-space gate: ${e.freeSpaceGatePassed?"PASS":"FAIL"}`,`  Migrated: ${e.migratedTasks} task(s), ${e.migratedEntries} entr${e.migratedEntries===1?"y":"ies"}`,`  Skipped event-source tasks: ${e.skippedTasks}`,`  Failed tasks: ${e.failedTasks}`,`  Logical source bytes removed: ${e.logicalSourceBytesRemoved}`];if(e.remainingTaskCount!==void 0)s.push(`  Remaining blob tasks: ${e.remainingTaskCount}`);if(e.backupPath){s.push(`  Backup: ${e.backupPath}`);if(e.backupMethod)s.push(`  Backup method: ${e.backupMethod}`)}if(e.verification){s.push(`  Event rows checked: ${e.verification.eventCount}`);s.push(`  Verification issues: ${e.verification.issues.length}`)}if(e.blockedReason)s.push(`  Blocked: ${e.blockedReason}`);for(const n of e.warnings??[])s.push(`  Warning: ${n}`);return s.join("\n")}async function B(e){let o;try{o=M(e)}catch(s){const n=s instanceof Error?s.message:String(s);if(n===exports.TASK_LOG_MIGRATION_HELP){console.log(n)}else{console.error(n);console.error(exports.TASK_LOG_MIGRATION_HELP);process.exitCode=2}return}try{const s=await(0,x.runTaskLogMigration)(o);console.log(C(s));if(!s.ok){if(s.blockedReason)console.error(s.blockedReason);const n=s.failures??s.malformedRows??[];for(const r of n){console.error(`  ${r.taskId}: ${r.reason}`)}process.exitCode=1}else{process.exitCode=0}}catch(s){console.error(s instanceof Error?s.message:String(s));process.exitCode=1}}class b extends Error{}function I(e){let o;let s=false;const n=r=>{const t=Number(r);if(!r||!Number.isSafeInteger(t)||t<1){throw new b("--batch must be a positive integer.")}return t};for(let r=0;r<e.length;r+=1){const t=e[r];if(t==="--help"||t==="-h")throw new b(exports.REQUEST_LOG_MIGRATION_HELP);if(t==="--dry-run"){s=true;continue}if(t==="--batch"){o=n(e[r+1]);r+=1;continue}if(t.startsWith("--batch=")){o=n(t.slice("--batch=".length));continue}throw new b(`Unknown option: ${t}`)}return{batchRows:o,dryRun:s}}function h(e){if(e<1024)return`${e} B`;const o=["KiB","MiB","GiB","TiB"];let s=e;let n=-1;while(s>=1024&&n<o.length-1){s/=1024;n+=1}return`${s.toFixed(s>=100?0:1)} ${o[n]} (${e} bytes)`}function k(e,o){const s=[...e].sort((n,r)=>n-r);return s[Math.min(s.length-1,Math.floor(o/100*s.length))]}function w(e){return`${(e/1e3).toFixed(1)}s`}const q=1e4;function O(e,o){if(e.dryRun){const s=e.scan;console.log("[crewx] Dry run finished \u2014 nothing was written.");console.log(`  Rows scanned: ${s?.rows??0}`);console.log(`  Bodies: ${s?.bodies??0} (${h(s?.bodyBytes??0)})`);console.log(`  Distinct bodies: ${s?.distinctBodies??0} (${h(s?.distinctBodyBytes??0)}) \u2014 what logs.db would store`);console.log(`  Elapsed: ${w(e.elapsedMs)}`);return}console.log("[crewx] Request-log move finished.");console.log(`  Moved rows: ${e.movedRows}`);console.log(`  Remaining rows in crewx.db: ${o.crewxRows}`);console.log(`  logs.db request_logs: ${o.logsRows??0}`);console.log(`  logs.db request_log_bodies: ${o.logsBodies??0}`);console.log(`  logs.db size: ${h(o.logsFileBytes)} (+ wal ${h(o.logsWalBytes)})`);console.log(`  crewx.db freelist pages: ${o.crewxFreelistPages}`);console.log(`  Batches: ${e.batches}, bodies added: ${e.bodiesAdded}`);if(e.deleteTxMs.length>0){console.log(`  crewx.db delete transaction per batch: p50 ${k(e.deleteTxMs,50).toFixed(1)} ms, p90 ${k(e.deleteTxMs,90).toFixed(1)} ms, max ${e.maxDeleteTxMs.toFixed(1)} ms`);console.log(`  Largest crewx.db -wal seen after a batch: ${h(e.maxWalBytes)}`)}console.log(`  Elapsed: ${w(e.elapsedMs)}`);if(o.crewxRows>0){console.log(`  ${o.crewxRows} row(s) are still in crewx.db (new rows arrived or the run stopped early). Run it again.`)}}async function G(e){let o;try{o=I(e)}catch(s){const n=s instanceof Error?s.message:String(s);if(n===exports.REQUEST_LOG_MIGRATION_HELP){console.log(n)}else{console.error(n);console.error(exports.REQUEST_LOG_MIGRATION_HELP);process.exitCode=2}return}try{const s=(0,p.inspectRequestLogsMove)();console.log(`[crewx] Request logs \u2192 logs.db${o.dryRun?" (dry run)":""}`);console.log(`  crewx.db: ${s.crewxDbPath}`);console.log(`  logs.db: ${s.logsDbPath}`);console.log(`  Rows to move: ${s.crewxRows}`);let n=Date.now();const r=a=>{const c=Date.now();if(c-n<q)return;n=c;const l=o.dryRun?a.scannedRows:a.movedRows;const i=Math.max(0,s.crewxRows-l);console.log(`  ${o.dryRun?"scanned":"moved"} ${l} | remaining ~${i} | elapsed ${w(a.elapsedMs)}`)};const t=(0,p.moveRequestLogsToLogsDb)({batchRows:o.batchRows,dryRun:o.dryRun,onProgress:r});O(t,(0,p.inspectRequestLogsMove)());process.exitCode=o.dryRun||t.remainingRows===0?0:1}catch(s){console.error(s instanceof Error?s.message:String(s));process.exitCode=1}}function U(e){let o;let s;let n;let r;const t=l=>{if(o)throw new u("Choose exactly one of --dry-run, --apply, --verify, or --restore.");o=l};const a=(l,i)=>{const f=e[l+1];if(!f||f.startsWith("--"))throw new u(`${i} requires a value.`);return f};for(let l=0;l<e.length;l+=1){const i=e[l];if(i==="--help"||i==="-h")throw new u(exports.USAGE_BACKFILL_HELP);if(i==="--dry-run"){t("dry-run");continue}if(i==="--apply"){t("apply");continue}if(i==="--verify"){t("verify");continue}if(i==="--restore"){t("restore");r=a(l,"--restore");l+=1;continue}if(i.startsWith("--restore=")){t("restore");r=i.slice("--restore=".length);if(!r)throw new u("--restore requires a value.");continue}if(i==="--db"){s=a(l,"--db");l+=1;continue}if(i.startsWith("--db=")){s=i.slice("--db=".length);if(!s)throw new u("--db requires a value.");continue}if(i==="--backup"){n=a(l,"--backup");l+=1;continue}if(i.startsWith("--backup=")){n=i.slice("--backup=".length);if(!n)throw new u("--backup requires a value.");continue}throw new u(`Unknown option: ${i}`)}const c=o??"dry-run";if(n&&c!=="apply"){throw new u("--backup is only valid with --apply.")}if(r&&c!=="restore"){throw new u("--restore is only valid with restore mode.")}return{mode:c,dbPath:s,backupPath:n,restorePath:r}}function D(e){const o=e.mode==="dry-run"?"Dry-run":e.mode==="apply"?"Apply":e.mode==="restore"?"Restore":"Verify";const s=[`[crewx] Usage backfill \u2014 ${o}`,`  Database: ${e.dbPath}`,`  Tasks scanned: ${e.scannedTasks}`,`  Terminal tasks: ${e.terminalTasks}`,`  Raw target tasks: ${e.rawTargetTasks}`,`  Candidate tasks: ${e.candidateTasks}`,`  Recovered: ${e.recoveredTasks}`,`  Unavailable: ${e.unavailableTasks}`,`  Deferred (within 24h): ${e.deferredTasks}`,`  Changed: ${e.changedTasks}`,`  Would change: ${e.wouldChangeTasks}`,`  Restored: ${e.restored}`,`  Skipped conflicts: ${e.skippedConflict}`,`  Remaining target tasks: ${e.remainingTargetTasks}`,`  Tasks with usageAccounting: ${e.accountingTasks}`,"  Provider distribution:"];const n=Object.entries(e.providerDistribution);if(n.length===0){s.push("    (none)")}else{for(const[t,a]of n){s.push(`    ${t}: candidates=${a.candidates}, recovered=${a.recovered}, unavailable=${a.unavailable}, deferred=${a.deferred}`)}}s.push("  Reason counts:");for(const[t,a]of Object.entries(e.reasonCounts))s.push(`    ${t}: ${a}`);s.push(`  Estimated free-space need: ${e.estimatedFreeSpaceBytes}`);s.push(`  Required free space (with reserve): ${e.requiredFreeSpaceBytes}`);s.push(`  Available free space: ${e.availableFreeSpaceBytes}`);s.push(`  Free-space gate: ${e.freeSpaceGatePassed?"PASS":"FAIL"}`);const r=e.snapshotPath??e.backupPath;if(r){s.push(`  Undo snapshot: ${r}`);if(e.backupMethod)s.push(`  Snapshot method: ${e.backupMethod}`)}if(e.blockedReason)s.push(`  Blocked: ${e.blockedReason}`);for(const t of e.conflictSamples){s.push(`  Conflict sample: ${t.taskId}: ${t.fields.join(", ")}`)}for(const t of e.failures)s.push(`  Failure: ${t.taskId}: ${t.reason}`);for(const t of e.warnings)s.push(`  Warning: ${t}`);return s.join("\n")}async function N(e){let o;try{o=U(e)}catch(s){const n=s instanceof Error?s.message:String(s);if(n===exports.USAGE_BACKFILL_HELP){console.log(n)}else{console.error(n);console.error(exports.USAGE_BACKFILL_HELP);process.exitCode=2}return}try{const s=await(0,_.runUsageBackfill)(o);console.log(D(s));process.exitCode=s.ok?0:1}catch(s){console.error(s instanceof Error?s.message:String(s));process.exitCode=1}}async function H(e){const o=e.includes("--force");const s=e.includes("--dry-run");const n=E();const r=(0,T.openDrizzleDb)(n);try{const t=(0,m.pushSchema)(r.db,{force:o,dbPath:n,dryRun:true});console.log(S(t,n));console.log("");if(s){console.log("[crewx] Dry-run mode \u2014 no changes applied.");return}if(!L(t)){console.log("[crewx] No changes needed. Database is up to date.");return}if(!o){const c=await A("Apply changes? (y/N): ");if(c.trim().toLowerCase()!=="y"){console.log("[crewx] Aborted.");return}}const a=(0,m.pushSchema)(r.db,{force:o,dbPath:n});console.log("");console.log("[crewx] Push complete.");if(a.created.length>0){console.log(`  Tables created: ${a.created.join(", ")}`)}if(a.altered.length>0){console.log(`  Columns added: ${a.altered.map(c=>`${c.table}.${c.column}`).join(", ")}`)}if(a.backupPath){console.log(`  Backup: ${a.backupPath}`)}if(a.created.length===0&&a.altered.length===0){console.log("  No changes applied.")}}finally{r.close()}}

package/dist/commands/detached.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Shared receipt-mode implementation for the query and execute commands.
+ *
+ * A receipt is persisted before a detached runner is started. The runner gets
+ * its own identity variables, while the trace variables remain the caller's
+ * trace context and are never repurposed as the runner assignment.
+ */
+import { TaskRepository } from '@crewx/sdk/repository';
+import type { DurableTaskAdmission, TaskActor } from '@crewx/sdk';
+export type ReceiptActorKind = 'human' | 'agent' | 'system' | 'unknown';
+export interface ReceiptActor {
+    kind: ReceiptActorKind;
+    id: string | null;
+}
+/** Resolve the CLI actor from metadata and the caller's current environment. */
+export declare function resolveCliTaskActor(metadata: Record<string, unknown>, agentId?: string | undefined): TaskActor;
+/**
+ * Resolve the actor at the receipt boundary while the caller's environment is
+ * still available. The receipt and synchronous paths share one predicate so
+ * cron runners cannot diverge after root context is stripped.
+ */
+export declare function resolveReceiptActor(metadata: Record<string, unknown>, agentId?: string | undefined): ReceiptActor;
+/**
+ * Report a blocked direct admission (WI-CTO-20260919-004 R2 finding #1) to
+ * the operator. Never called for an adopted (already pending) receipt — see
+ * admitDurableTask()'s own doc comment.
+ */
+export declare function reportAdmissionBlocked(admission: Extract<DurableTaskAdmission, {
+    ok: false;
+}>): void;
+/**
+ * Remove receipt-selection flags, respecting the `--` literal-args sentinel.
+ */
+export declare function extractReceiptFlags(args: string[]): {
+    detach: boolean;
+    wait: boolean;
+    rest: string[];
+};
+export type ReceiptModeReason = 'explicit-detach' | 'agent-context' | 'detached-runner' | 'wait' | 'default';
+export interface ReceiptModeDecision {
+    receipt: boolean;
+    reason: ReceiptModeReason;
+}
+/** Resolve the receipt/synchronous mode contract shared by q and x. */
+export declare function resolveReceiptMode(options: {
+    detach: boolean;
+    wait: boolean;
+    detachedRunner: boolean;
+    agentContext: boolean;
+}): ReceiptModeDecision;
+/**
+ * Rebuild runner argv from the parsed request. The resolved prompt is passed
+ * as one argv value after `--`, so stdin is never needed by the detached
+ * child and prompt text beginning with a dash remains positional text.
+ */
+export declare function buildDetachedRunnerArgs(filteredArgs: string[], agentRef: string, finalMessage: string): string[];
+export type AssignedTaskAdoption = {
+    kind: 'adopted';
+    taskId: string;
+} | {
+    kind: 'stale';
+} | {
+    kind: 'failed';
+};
+/**
+ * Claim a pre-issued receipt without overwriting an already-owned row.
+ * Assignment-only leakage is recoverable: discard the stale id and let the
+ * normal SDK path create a fresh task. A real detached runner must fail loud
+ * because its receipt would otherwise point at no execution row.
+ */
+export declare function adoptAssignedTask(taskRepo: Pick<TaskRepository, 'adoptPendingTask'>, taskId: string, detachedRunner: boolean): AssignedTaskAdoption;
+/** Read the actor persisted on the receipt after the runner adopts it. */
+export declare function readAssignedTaskActor(taskRepo: Pick<TaskRepository, 'getTask'>, taskId: string): TaskActor;
+export interface DetachedMiddleHop {
+    taskId: string;
+    logPath: string;
+    runnerArgs: string[];
+}
+/**
+ * Read the private Windows middle-hop contract. Invalid direct invocations
+ * are left untouched and therefore fail through the normal unknown-option
+ * path instead of becoming an undocumented public command.
+ */
+export declare function readDetachedMiddleHop(args: string[]): DetachedMiddleHop | undefined;
+/**
+ * Windows middle hop: transfer a transient log handle to the final runner,
+ * close the middle process's copy, and exit immediately. The parent treats a
+ * successful middle-hop exit as normal and makes adoption a database decision.
+ */
+export declare function runDetachedMiddle(command: string, hop: DetachedMiddleHop): Promise<void>;
+/**
+ * Persist a receipt and launch its detached runner. Unix uses one hop. Windows
+ * uses a short-lived middle hop so the final runner has no live parent link.
+ */
+export declare function runDetached(command: string, filteredArgs: string[], reason: ReceiptModeReason, invocationArgs?: string[]): Promise<void>;

package/dist/commands/detached.js

@@ -0,0 +1,15 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:true});exports.resolveCliTaskActor=V;exports.resolveReceiptActor=X;exports.reportAdmissionBlocked=B;exports.extractReceiptFlags=he;exports.resolveReceiptMode=_e;exports.buildDetachedRunnerArgs=Y;exports.adoptAssignedTask=we;exports.readAssignedTaskActor=me;exports.readDetachedMiddleHop=Ee;exports.runDetachedMiddle=xe;exports.runDetached=ve;const F=require("child_process");const l=require("fs");const A=require("path");const ne=require("os");const y=require("@crewx/sdk");const se=require("@crewx/sdk/node");const oe=require("@crewx/sdk/repository");const ie=require("./parse-agent-message");const j=require("./parse-common-flags");const ce=require("./resolve-recipient");const ae=require("./resolve-prompt");const de=require("../utils/version");const G=require("../utils/inherited-trace");const U=require("./cal");const ue=require("./emit-trailer");function q(e){return typeof e==="string"&&e.trim().length>0?e.trim():void 0}function V(e,t=process.env["CREWX_AGENT_ID"]){const r=q(e.schedule_id);if(r)return{actorKind:"system",actorId:`cron:${r}`};const n=e.workflow;const s=n!==null&&typeof n==="object"&&!Array.isArray(n)?n:void 0;const o=q(s?.exec_id);if(o)return{actorKind:"system",actorId:`workflow:${o}`};const i=q(t);if(i)return{actorKind:"agent",actorId:i};if(process.stdin.isTTY===true||process.stderr.isTTY===true){return{actorKind:"human",actorId:(0,se.getLocalActorId)()}}return{actorKind:"unknown",actorId:null}}function X(e,t=process.env["CREWX_AGENT_ID"]){const r=V(e,t);return{kind:r.actorKind,id:r.actorId}}function B(e){process.stderr.write(`${e.message}
+`)}const le=200;const z=3e4;const pe=["--to","--thread","--provider","--model","--metadata","--config","-c","--output-format","--effort","--prompt-file","-f","--out","-o"];const J="--__crewx-detached-middle";const C="--__crewx-detached-task";const L="--__crewx-detached-log";const M="--__crewx-detached-token";const b="CREWX_DETACHED_HOP_TOKEN";function fe(e){return pe.some(t=>e===t||e.startsWith(`${t}=`))}function ge(e){return e==="--prompt-file"||e==="-f"||e.startsWith("--prompt-file=")||e.startsWith("-f=")}function he(e){const t=[];let r=false;let n=false;let s=false;for(const o of e){if(!s&&o==="--"){s=true;t.push(o);continue}if(!s&&(o==="--detach"||o==="--async")){r=true;continue}if(!s&&(o==="--wait"||o.startsWith("--wait="))){n=true;continue}t.push(o)}return{detach:r,wait:n,rest:t}}function _e(e){if(e.wait)return{receipt:false,reason:"wait"};if(e.detachedRunner)return{receipt:false,reason:"detached-runner"};if(e.detach)return{receipt:true,reason:"explicit-detach"};if(e.agentContext)return{receipt:true,reason:"agent-context"};return{receipt:false,reason:"default"}}function h(e){return e instanceof Error?e.message:String(e)}function ke(e,t,r,n={}){return new Promise((s,o)=>{let i=false;let c;let _;const T=()=>{if(c!==void 0)clearInterval(c);if(_!==void 0)clearTimeout(_)};const E=a=>{if(i)return;i=true;T();s(a)};const k=(a,g=false)=>{try{const p=e.getTask(t);if(p&&p.status!=="pending"){E({kind:"adopted"});return}if(a!==void 0){E({kind:"exited",reason:a});return}if(g)E({kind:"timeout"})}catch(p){if(i)return;i=true;T();o(p)}};r.on("error",a=>{k(`Runner failed before adopting task: ${h(a)}`)});r.on("exit",(a,g)=>{if(n.ignoreSuccessfulExit&&a===0&&g===null)return;const p=g?`signal ${g}`:`exit ${a??"unknown"}`;k(`Runner exited before adopting task (${p})`)});c=setInterval(()=>k(),le);_=setTimeout(()=>k(void 0,true),z);k()})}function W(e,t,r){try{const n=e.failPendingTask(t,r);if(n){process.stderr.write(`Detached task ${t} failed: ${r}
+`);return false}const s=e.getTask(t);if(s&&s.status!=="pending")return true}catch(n){r+=`; could not persist failure: ${h(n)}`}process.stderr.write(`Detached task ${t} failed: ${r}
+`);return false}function R(e,t,r,n,s,o,i){let c="pending";try{const T=e.getTask(t);c=T?.status==="pending"?"pending":"running"}catch{}if(o==="json"){process.stdout.write(`${JSON.stringify({taskId:t,status:c,mode:"receipt",logPath:r})}
+`);return}if(s)process.stderr.write(`mode=receipt reason=${n}
+`);process.stdout.write(`${t}
+`);process.stderr.write(`Task ${t} accepted. This ID is the handle (not a PID).
+`);if(i&&s)process.stderr.write(`${i}
+`);const _=(0,U.suggestWaitSeconds)({startedAt:null});(0,U.writeCalFooter)({commandId:"crewx.receipt",params:{taskId:t,wait:String(_)}})}function Y(e,t,r){const n=[];for(let s=0;s<e.length;s+=1){const o=e[s];if(o==="--")break;if(o==="--verbose"||o==="--overdrive"){n.push(o);continue}if(o==="--var"){const i=e[s+1];if(i!==void 0){n.push(o,i);s+=1}continue}if(o.startsWith("--var=")){n.push(o);continue}if(o==="--to"){s+=1;continue}if(o.startsWith("--to="))continue;if(!fe(o))continue;if(ge(o)){if(!o.includes("="))s+=1;continue}n.push(o);if(!o.includes("=")){const i=e[s+1];if(i!==void 0){n.push(i);s+=1}}}return[...n,...t?[t]:[],"--",r]}function Q(e){if(e==="execute")return"x";if(e==="query")return"q";return e}function Z(e){const t={...process.env};delete t[b];if(process.versions.electron){t.ELECTRON_RUN_AS_NODE="1"}t.CREWX_DETACHED_RUNNER="1";t.CREWX_ASSIGNED_TASK_ID=e;return t}function we(e,t,r){if(e.adoptPendingTask(t)){return{kind:"adopted",taskId:t}}const n=`stale assigned id ${t}: expected pending task with pid NULL`;if(r){process.stderr.write(`Detached runner failed to adopt task ${t}: ${n}
+`);return{kind:"failed"}}process.stderr.write(`${n}
+`);return{kind:"stale"}}function me(e,t){const r=e.getTask(t);const n=r?.actor_kind;if(n===null||n===void 0){return{actorKind:"unknown",actorId:null}}if(n==="human"||n==="agent"||n==="system"||n==="unknown"){return{actorKind:n,actorId:r?.actor_id??null}}return{actorKind:"unknown",actorId:r?.actor_id??null}}function Te(e){const t={...process.env};if(process.versions.electron){t.ELECTRON_RUN_AS_NODE="1"}t[b]=e;return t}function Ee(e){let t=false;let r;let n;let s;let o=false;const i=[];for(const c of e){if(!o&&c==="--"){o=true;i.push(c);continue}if(!o&&c===J){t=true;continue}if(!o&&c.startsWith(`${C}=`)){r=c.slice(`${C}=`.length);continue}if(!o&&c.startsWith(`${L}=`)){n=c.slice(`${L}=`.length);continue}if(!o&&c.startsWith(`${M}=`)){s=c.slice(`${M}=`.length);continue}i.push(c)}if(!t||!r||!n||!s||s!==process.env[b]){return void 0}return{taskId:r,logPath:n,runnerArgs:i}}async function xe(e,t){let r;try{const n=(0,A.dirname)(t.logPath);if(!(0,l.existsSync)(n))(0,l.mkdirSync)(n,{recursive:true});r=(0,l.openSync)(t.logPath,"a");const s=process.argv[1];const o=(0,F.spawn)(process.execPath,[s,Q(e),...t.runnerArgs],{detached:true,windowsHide:true,stdio:["ignore",r,r],env:Z(t.taskId)});(0,l.closeSync)(r);r=void 0;o.unref()}catch(n){if(r!==void 0)(0,l.closeSync)(r);process.stderr.write(`Runner failed before adopting task: ${h(n)}
+`);process.exit(1);return}process.exit(0)}async function ve(e,t,r,n=t){const s=(0,j.parseCommonFlags)(t);const{thread:o,metadata:i,promptFile:c,rest:_,to:T}=s;const{agentRef:E,message:k}=(0,ie.parseAgentMessage)(_);const a=await(0,ae.resolvePrompt)(k,c);let g;try{({agentRef:g}=(0,ce.resolveRecipient)({positionalRef:E,toFlag:T,agentContext:Boolean(process.env["CREWX_AGENT_ID"]),bodyForHint:a,command:e,invocationArgs:n}))}catch(u){const v=h(u);process.stderr.write(`Error: ${v}
+`);(0,ue.emitDelegationResult)({command:e,trace:(0,G.readInheritedTrace)(),isError:true});process.exit(2);return}if(!a){console.error("Usage: crewx q|x --to <agent> <message> [options]");console.error("  @agent is a positional shorthand for selecting a recipient.");console.error("  Task body can also be supplied via stdin pipe or --prompt-file.");process.exit(1);return}let p;try{p=(0,j.parseMetadata)(i)}catch(u){process.stderr.write(`Error: ${h(u)}
+`);process.exit(2);return}const x=(0,y.admitDurableTask)(`direct-cli:${e}`);if(!x.ok){B(x);process.exit(1);return}const d=x.taskId;const ee=new Date().toISOString();const I=process.cwd();const te=(0,l.existsSync)((0,A.join)(I,"crewx.yaml"))||(0,l.existsSync)((0,A.join)(I,"crewx.yml"));const N=(0,G.readInheritedTrace)();const re=N?.rootTraceId||d;const f=new oe.TaskRepository;const O=X(p);try{f.startTask({id:d,agentId:g.replace(/^@/,""),actorKind:O.kind,actorId:O.id,prompt:a,mode:e==="q"||e==="query"?"query":"execute",status:"pending",startedAt:ee,pid:null,parentTaskId:N?.parentTaskId??null,callerAgentId:N?.callerAgentId??null,traceId:re,command:process.argv.join(" "),metadata:Object.keys(p).length>0?JSON.stringify(p):null,workspaceId:te?(0,y.hashWorkspaceId)((0,y.resolveWorkspaceOwnerPath)(I)):null,cwd:(0,y.normalizeWorkspacePath)(I),projectId:null,platform:"cli",crewxVersion:de.CLI_VERSION,threadId:o??null})}catch(u){x.release();process.stderr.write(`Failed to create detached task receipt: ${h(u)}
+`);process.exit(1);return}x.release();const P=Y(t,g,a);const K=Q(e);const S=(0,A.join)((0,ne.homedir)(),".crewx","logs");const w=(0,A.join)(S,`${d}.log`);let m;let D;let H=false;try{if(!(0,l.existsSync)(S))(0,l.mkdirSync)(S,{recursive:true});if(process.platform==="win32"){H=true;const u=(0,y.generateId)("req");D=(0,F.spawn)(process.execPath,[process.argv[1],K,J,`${C}=${d}`,`${L}=${w}`,`${M}=${u}`,...P],{detached:true,windowsHide:true,stdio:"ignore",env:Te(u)})}else{m=(0,l.openSync)(w,"a");D=(0,F.spawn)(process.execPath,[process.argv[1],K,...P],{detached:true,windowsHide:true,stdio:["ignore",m,m],env:Z(d)});(0,l.closeSync)(m);m=void 0}D.unref()}catch(u){if(m!==void 0)(0,l.closeSync)(m);const v=`Runner failed before adopting task: ${h(u)}`;if(!W(f,d,v))process.exit(1);else{R(f,d,w,r,s.verbose,s.outputFormat);process.exit(0)}return}let $;try{$=await ke(f,d,D,{ignoreSuccessfulExit:H})}catch(u){const v=`Runner adoption check failed: ${h(u)}`;if(!W(f,d,v))process.exit(1);else{R(f,d,w,r,s.verbose,s.outputFormat);process.exit(0)}return}if($.kind==="adopted"){R(f,d,w,r,s.verbose,s.outputFormat);process.exit(0);return}if($.kind==="timeout"){R(f,d,w,r,s.verbose,s.outputFormat,`Warning: runner alive, row not yet adopted after ${z/1e3}s.`);process.exit(0);return}if(!W(f,d,$.reason))process.exit(1);else{R(f,d,w,r,s.verbose,s.outputFormat);process.exit(0)}}

package/dist/commands/doctor.d.ts

@@ -6,7 +6,84 @@
  *   crewx doctor                  Run full diagnosis
  *   crewx doctor --config <path>  Use specific config file
  */
+import type { CrewxExecutableResolution, CrewxExecutableStage } from '@crewx/sdk';
+interface DiagnosticResult {
+    name: string;
+    status: 'success' | 'warning' | 'error';
+    message: string;
+    details?: string;
+}
+export interface CliProviderInfo {
+    cmd: string;
+    install: string;
+}
+export interface DoctorArtifact {
+    directory: string;
+    sizeBytes: number;
+    details: string[];
+}
+export interface NpxCacheReport {
+    cacheRoot: string;
+    zeroByteLockfileDirectories: DoctorArtifact[];
+    staleFileCacheDirectories: DoctorArtifact[];
+    cleanableDirectories: DoctorArtifact[];
+}
+export interface HookCommandIssue {
+    provider: 'claude' | 'codex';
+    settingsPath: string;
+    command: string;
+    reason: 'launcher' | 'non-absolute';
+}
+export interface HookCommandReport {
+    inspectedFiles: string[];
+    issues: HookCommandIssue[];
+}
+export interface CrewxShimReport {
+    shimRoot: string;
+    currentFingerprint?: string;
+    staleDirectories: Array<DoctorArtifact & {
+        fingerprint: string;
+    }>;
+}
+export interface CrewxExecutableReport {
+    platform: NodeJS.Platform;
+    pathCandidates: string[];
+    stage?: CrewxExecutableStage;
+    argv?: string[];
+    electron: boolean;
+    requiredEnvKeys: string[];
+    binResolution: 'global_first' | 'local_first';
+    adoptedPath?: string;
+    resolutionError?: string;
+}
+export interface CrewxExecutableInspectionOptions {
+    platform?: NodeJS.Platform;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    binResolution?: 'global_first' | 'local_first';
+    pathCandidates?: readonly string[];
+    resolution?: CrewxExecutableResolution;
+}
+/** CLI diagnostics keyed by the bare provider name used in PROVIDER_ORDER. */
+export declare const CLI_PROVIDER_INFO: Record<string, CliProviderInfo>;
+/** Format a byte count for diagnostic output. */
+export declare function formatBytes(bytes: number): string;
+/** Inspect npm's persistent `_npx` cache without modifying it. */
+export declare function inspectNpxCache(cacheRoot?: string): NpxCacheReport;
+/** Inspect installed CrewX hooks without rewriting provider settings. */
+export declare function inspectHookCommands(projectRoot: string): HookCommandReport;
+/** Inspect the SDK-selected CrewX executable without printing environment values. */
+export declare function inspectCrewxExecutable(options?: CrewxExecutableInspectionOptions & {
+    configPath?: string;
+}): CrewxExecutableReport;
+/** Inspect orphaned CrewX PATH shim directories without modifying them. */
+export declare function inspectCrewxShims(crewxHome?: string, resolvedFingerprint?: string | undefined): CrewxShimReport;
+/**
+ * Check CLI provider availability in the canonical PROVIDER_ORDER.
+ */
+export declare function checkCliProviders(): DiagnosticResult[];
 /**
  * Handle `crewx doctor` command.
  */
 export declare function handleDoctor(args: string[]): Promise<void>;
+export {};