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

package/dist/commands/db.js

@@ -11,12 +11,77 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.USAGE_BACKFILL_HELP = exports.REQUEST_LOG_MIGRATION_HELP = exports.TASK_LOG_MIGRATION_HELP = void 0;
 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");
+const repository_3 = require("@crewx/sdk/repository");
+const repository_4 = require("@crewx/sdk/repository");
+const repository_5 = 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 defaultDbPath() {
     return path_1.default.join(os_1.default.homedir(), '.crewx', 'crewx.db');
 }
@@ -57,6 +122,12 @@ function formatPreview(result, dbPath) {
 function hasChanges(result) {
     return result.created.length > 0 || result.altered.length > 0;
 }
+function formatStatusCounts(counts) {
+    const entries = Object.entries(counts ?? {});
+    return entries.length > 0
+        ? entries.map(([status, count]) => `${status}=${count}`).join(', ')
+        : '(none)';
+}
 function prompt(question) {
     const rl = readline_1.default.createInterface({ input: process.stdin, output: process.stdout });
     return new Promise((resolve) => {
@@ -68,13 +139,474 @@ function prompt(question) {
 }
 async function handleDb(args) {
     const subcommand = args[0];
+    if (subcommand === 'migrate-task-logs') {
+        await handleTaskLogMigration(args.slice(1));
+        return;
+    }
+    if (subcommand === 'migrate-request-logs') {
+        await handleRequestLogMigration(args.slice(1));
+        return;
+    }
+    if (subcommand === 'backfill-usage') {
+        await handleUsageBackfill(args.slice(1));
+        return;
+    }
+    if (subcommand === '--help' || subcommand === '-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 (!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);
+    console.error(exports.TASK_LOG_MIGRATION_HELP);
+    process.exitCode = 2;
+}
+class TaskLogMigrationUsageError extends Error {
+}
+class UsageBackfillUsageError extends Error {
+}
+function parseTaskLogMigrationArgs(args) {
+    let mode;
+    let dbPath;
+    let batchTasks;
+    const setMode = (next) => {
+        if (mode)
+            throw new TaskLogMigrationUsageError('Choose exactly one of --dry-run, --apply, or --verify.');
+        mode = next;
+    };
+    const requireValue = (args, index, flag) => {
+        const value = args[index + 1];
+        if (!value || value.startsWith('--'))
+            throw new TaskLogMigrationUsageError(`${flag} requires a value.`);
+        return value;
+    };
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--help' || arg === '-h') {
+            throw new TaskLogMigrationUsageError(exports.TASK_LOG_MIGRATION_HELP);
+        }
+        if (arg === '--dry-run') {
+            setMode('dry-run');
+            continue;
+        }
+        if (arg === '--apply') {
+            setMode('apply');
+            continue;
+        }
+        if (arg === '--verify') {
+            setMode('verify');
+            continue;
+        }
+        if (arg === '--db') {
+            dbPath = requireValue(args, index, '--db');
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--db=')) {
+            dbPath = arg.slice('--db='.length);
+            if (!dbPath)
+                throw new TaskLogMigrationUsageError('--db requires a value.');
+            continue;
+        }
+        if (arg === '--batch-tasks') {
+            const value = requireValue(args, index, '--batch-tasks');
+            const parsed = Number(value);
+            if (!Number.isSafeInteger(parsed) || parsed < 1) {
+                throw new TaskLogMigrationUsageError('--batch-tasks must be a positive integer.');
+            }
+            batchTasks = parsed;
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--batch-tasks=')) {
+            const value = arg.slice('--batch-tasks='.length);
+            const parsed = Number(value);
+            if (!Number.isSafeInteger(parsed) || parsed < 1) {
+                throw new TaskLogMigrationUsageError('--batch-tasks must be a positive integer.');
+            }
+            batchTasks = parsed;
+            continue;
+        }
+        throw new TaskLogMigrationUsageError(`Unknown option: ${arg}`);
+    }
+    if (!mode)
+        throw new TaskLogMigrationUsageError('Choose one of --dry-run, --apply, or --verify.');
+    if (batchTasks !== undefined && mode !== 'apply') {
+        throw new TaskLogMigrationUsageError('--batch-tasks is only valid with --apply.');
+    }
+    return { mode, dbPath, batchTasks };
+}
+function formatMigrationReport(report) {
+    const modeLabel = report.mode === 'dry-run' ? 'Dry-run' : report.mode === 'apply' ? 'Apply' : 'Verify';
+    const lines = [
+        `[crewx] Task-log migration — ${modeLabel}`,
+        `  Database: ${report.dbPath}`,
+        `  Tasks scanned: ${report.taskCount}`,
+        `  Blob candidates: ${report.candidateTaskCount}`,
+        `  Eligible terminal blobs: ${report.eligibleTaskCount}`,
+        `  Status counts: ${formatStatusCounts(report.statusCounts)}`,
+        `  Deferred blob tasks: ${report.deferredTaskCount}`,
+        `  Deferred statuses: ${formatStatusCounts(report.deferredStatusCounts)}`,
+        `  Entries: ${report.entryCount}`,
+        `  Source bytes: ${report.sourceBytes}`,
+        `  Estimated free-space need: ${report.estimatedFreeSpaceBytes}`,
+        `  Required free space (with reserve): ${report.requiredFreeSpaceBytes}`,
+        `  Available free space: ${report.availableFreeSpaceBytes}`,
+        `  Free-space gate: ${report.freeSpaceGatePassed ? 'PASS' : 'FAIL'}`,
+        `  Migrated: ${report.migratedTasks} task(s), ${report.migratedEntries} entr${report.migratedEntries === 1 ? 'y' : 'ies'}`,
+        `  Skipped event-source tasks: ${report.skippedTasks}`,
+        `  Failed tasks: ${report.failedTasks}`,
+        `  Logical source bytes removed: ${report.logicalSourceBytesRemoved}`,
+    ];
+    if (report.remainingTaskCount !== undefined)
+        lines.push(`  Remaining blob tasks: ${report.remainingTaskCount}`);
+    if (report.backupPath) {
+        lines.push(`  Backup: ${report.backupPath}`);
+        if (report.backupMethod)
+            lines.push(`  Backup method: ${report.backupMethod}`);
+    }
+    if (report.verification) {
+        lines.push(`  Event rows checked: ${report.verification.eventCount}`);
+        lines.push(`  Verification issues: ${report.verification.issues.length}`);
+    }
+    if (report.blockedReason)
+        lines.push(`  Blocked: ${report.blockedReason}`);
+    for (const warning of report.warnings ?? [])
+        lines.push(`  Warning: ${warning}`);
+    return lines.join('\n');
+}
+async function handleTaskLogMigration(args) {
+    let parsed;
+    try {
+        parsed = parseTaskLogMigrationArgs(args);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message === exports.TASK_LOG_MIGRATION_HELP) {
+            console.log(message);
+        }
+        else {
+            console.error(message);
+            console.error(exports.TASK_LOG_MIGRATION_HELP);
+            process.exitCode = 2;
+        }
+        return;
+    }
+    try {
+        const report = await (0, repository_3.runTaskLogMigration)(parsed);
+        console.log(formatMigrationReport(report));
+        if (!report.ok) {
+            if (report.blockedReason)
+                console.error(report.blockedReason);
+            const failures = report.failures ?? report.malformedRows ?? [];
+            for (const failure of failures) {
+                console.error(`  ${failure.taskId}: ${failure.reason}`);
+            }
+            process.exitCode = 1;
+        }
+        else {
+            process.exitCode = 0;
+        }
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}
+class RequestLogMigrationUsageError extends Error {
+}
+function parseRequestLogMigrationArgs(args) {
+    let batchRows;
+    let dryRun = false;
+    const parseBatch = (value) => {
+        const parsed = Number(value);
+        if (!value || !Number.isSafeInteger(parsed) || parsed < 1) {
+            throw new RequestLogMigrationUsageError('--batch must be a positive integer.');
+        }
+        return parsed;
+    };
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--help' || arg === '-h')
+            throw new RequestLogMigrationUsageError(exports.REQUEST_LOG_MIGRATION_HELP);
+        if (arg === '--dry-run') {
+            dryRun = true;
+            continue;
+        }
+        if (arg === '--batch') {
+            batchRows = parseBatch(args[index + 1]);
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--batch=')) {
+            batchRows = parseBatch(arg.slice('--batch='.length));
+            continue;
+        }
+        throw new RequestLogMigrationUsageError(`Unknown option: ${arg}`);
+    }
+    return { batchRows, dryRun };
+}
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    const units = ['KiB', 'MiB', 'GiB', 'TiB'];
+    let value = bytes;
+    let unit = -1;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit += 1;
+    }
+    return `${value.toFixed(value >= 100 ? 0 : 1)} ${units[unit]} (${bytes} bytes)`;
+}
+function percentile(values, p) {
+    const sorted = [...values].sort((a, b) => a - b);
+    return sorted[Math.min(sorted.length - 1, Math.floor((p / 100) * sorted.length))];
+}
+function formatSeconds(ms) {
+    return `${(ms / 1000).toFixed(1)}s`;
+}
+const REQUEST_LOG_PROGRESS_INTERVAL_MS = 10_000;
+function printRequestLogSummary(result, status) {
+    if (result.dryRun) {
+        const scan = result.scan;
+        console.log('[crewx] Dry run finished — nothing was written.');
+        console.log(`  Rows scanned: ${scan?.rows ?? 0}`);
+        console.log(`  Bodies: ${scan?.bodies ?? 0} (${formatBytes(scan?.bodyBytes ?? 0)})`);
+        console.log(`  Distinct bodies: ${scan?.distinctBodies ?? 0} (${formatBytes(scan?.distinctBodyBytes ?? 0)}) — what logs.db would store`);
+        console.log(`  Elapsed: ${formatSeconds(result.elapsedMs)}`);
+        return;
+    }
+    console.log('[crewx] Request-log move finished.');
+    console.log(`  Moved rows: ${result.movedRows}`);
+    console.log(`  Remaining rows in crewx.db: ${status.crewxRows}`);
+    console.log(`  logs.db request_logs: ${status.logsRows ?? 0}`);
+    console.log(`  logs.db request_log_bodies: ${status.logsBodies ?? 0}`);
+    console.log(`  logs.db size: ${formatBytes(status.logsFileBytes)} (+ wal ${formatBytes(status.logsWalBytes)})`);
+    console.log(`  crewx.db freelist pages: ${status.crewxFreelistPages}`);
+    console.log(`  Batches: ${result.batches}, bodies added: ${result.bodiesAdded}`);
+    if (result.deleteTxMs.length > 0) {
+        console.log(`  crewx.db delete transaction per batch: p50 ${percentile(result.deleteTxMs, 50).toFixed(1)} ms, p90 ${percentile(result.deleteTxMs, 90).toFixed(1)} ms, max ${result.maxDeleteTxMs.toFixed(1)} ms`);
+        console.log(`  Largest crewx.db -wal seen after a batch: ${formatBytes(result.maxWalBytes)}`);
+    }
+    console.log(`  Elapsed: ${formatSeconds(result.elapsedMs)}`);
+    if (status.crewxRows > 0) {
+        console.log(`  ${status.crewxRows} row(s) are still in crewx.db (new rows arrived or the run stopped early). Run it again.`);
+    }
+}
+async function handleRequestLogMigration(args) {
+    let parsed;
+    try {
+        parsed = parseRequestLogMigrationArgs(args);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message === exports.REQUEST_LOG_MIGRATION_HELP) {
+            console.log(message);
+        }
+        else {
+            console.error(message);
+            console.error(exports.REQUEST_LOG_MIGRATION_HELP);
+            process.exitCode = 2;
+        }
+        return;
+    }
+    try {
+        const before = (0, repository_4.inspectRequestLogsMove)();
+        console.log(`[crewx] Request logs → logs.db${parsed.dryRun ? ' (dry run)' : ''}`);
+        console.log(`  crewx.db: ${before.crewxDbPath}`);
+        console.log(`  logs.db: ${before.logsDbPath}`);
+        console.log(`  Rows to move: ${before.crewxRows}`);
+        let lastPrint = Date.now();
+        const onProgress = (progress) => {
+            const now = Date.now();
+            if (now - lastPrint < REQUEST_LOG_PROGRESS_INTERVAL_MS)
+                return;
+            lastPrint = now;
+            const done = parsed.dryRun ? progress.scannedRows : progress.movedRows;
+            const remaining = Math.max(0, before.crewxRows - done);
+            console.log(`  ${parsed.dryRun ? 'scanned' : 'moved'} ${done} | remaining ~${remaining} | elapsed ${formatSeconds(progress.elapsedMs)}`);
+        };
+        const result = (0, repository_4.moveRequestLogsToLogsDb)({
+            batchRows: parsed.batchRows,
+            dryRun: parsed.dryRun,
+            onProgress,
+        });
+        printRequestLogSummary(result, (0, repository_4.inspectRequestLogsMove)());
+        process.exitCode = parsed.dryRun || result.remainingRows === 0 ? 0 : 1;
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}
+function parseUsageBackfillArgs(args) {
+    let mode;
+    let dbPath;
+    let backupPath;
+    let restorePath;
+    const setMode = (next) => {
+        if (mode)
+            throw new UsageBackfillUsageError('Choose exactly one of --dry-run, --apply, --verify, or --restore.');
+        mode = next;
+    };
+    const requireValue = (index, flag) => {
+        const value = args[index + 1];
+        if (!value || value.startsWith('--'))
+            throw new UsageBackfillUsageError(`${flag} requires a value.`);
+        return value;
+    };
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--help' || arg === '-h')
+            throw new UsageBackfillUsageError(exports.USAGE_BACKFILL_HELP);
+        if (arg === '--dry-run') {
+            setMode('dry-run');
+            continue;
+        }
+        if (arg === '--apply') {
+            setMode('apply');
+            continue;
+        }
+        if (arg === '--verify') {
+            setMode('verify');
+            continue;
+        }
+        if (arg === '--restore') {
+            setMode('restore');
+            restorePath = requireValue(index, '--restore');
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--restore=')) {
+            setMode('restore');
+            restorePath = arg.slice('--restore='.length);
+            if (!restorePath)
+                throw new UsageBackfillUsageError('--restore requires a value.');
+            continue;
+        }
+        if (arg === '--db') {
+            dbPath = requireValue(index, '--db');
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--db=')) {
+            dbPath = arg.slice('--db='.length);
+            if (!dbPath)
+                throw new UsageBackfillUsageError('--db requires a value.');
+            continue;
+        }
+        if (arg === '--backup') {
+            backupPath = requireValue(index, '--backup');
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--backup=')) {
+            backupPath = arg.slice('--backup='.length);
+            if (!backupPath)
+                throw new UsageBackfillUsageError('--backup requires a value.');
+            continue;
+        }
+        throw new UsageBackfillUsageError(`Unknown option: ${arg}`);
+    }
+    const selectedMode = mode ?? 'dry-run';
+    if (backupPath && selectedMode !== 'apply') {
+        throw new UsageBackfillUsageError('--backup is only valid with --apply.');
+    }
+    if (restorePath && selectedMode !== 'restore') {
+        throw new UsageBackfillUsageError('--restore is only valid with restore mode.');
+    }
+    return { mode: selectedMode, dbPath, backupPath, restorePath };
+}
+function formatUsageBackfillReport(report) {
+    const modeLabel = report.mode === 'dry-run'
+        ? 'Dry-run'
+        : report.mode === 'apply'
+            ? 'Apply'
+            : report.mode === 'restore'
+                ? 'Restore'
+                : 'Verify';
+    const lines = [
+        `[crewx] Usage backfill — ${modeLabel}`,
+        `  Database: ${report.dbPath}`,
+        `  Tasks scanned: ${report.scannedTasks}`,
+        `  Terminal tasks: ${report.terminalTasks}`,
+        `  Raw target tasks: ${report.rawTargetTasks}`,
+        `  Candidate tasks: ${report.candidateTasks}`,
+        `  Recovered: ${report.recoveredTasks}`,
+        `  Unavailable: ${report.unavailableTasks}`,
+        `  Deferred (within 24h): ${report.deferredTasks}`,
+        `  Changed: ${report.changedTasks}`,
+        `  Would change: ${report.wouldChangeTasks}`,
+        `  Restored: ${report.restored}`,
+        `  Skipped conflicts: ${report.skippedConflict}`,
+        `  Remaining target tasks: ${report.remainingTargetTasks}`,
+        `  Tasks with usageAccounting: ${report.accountingTasks}`,
+        '  Provider distribution:',
+    ];
+    const providers = Object.entries(report.providerDistribution);
+    if (providers.length === 0) {
+        lines.push('    (none)');
+    }
+    else {
+        for (const [provider, stats] of providers) {
+            lines.push(`    ${provider}: candidates=${stats.candidates}, recovered=${stats.recovered}, unavailable=${stats.unavailable}, deferred=${stats.deferred}`);
+        }
+    }
+    lines.push('  Reason counts:');
+    for (const [reason, count] of Object.entries(report.reasonCounts))
+        lines.push(`    ${reason}: ${count}`);
+    lines.push(`  Estimated free-space need: ${report.estimatedFreeSpaceBytes}`);
+    lines.push(`  Required free space (with reserve): ${report.requiredFreeSpaceBytes}`);
+    lines.push(`  Available free space: ${report.availableFreeSpaceBytes}`);
+    lines.push(`  Free-space gate: ${report.freeSpaceGatePassed ? 'PASS' : 'FAIL'}`);
+    const snapshotPath = report.snapshotPath ?? report.backupPath;
+    if (snapshotPath) {
+        lines.push(`  Undo snapshot: ${snapshotPath}`);
+        if (report.backupMethod)
+            lines.push(`  Snapshot method: ${report.backupMethod}`);
+    }
+    if (report.blockedReason)
+        lines.push(`  Blocked: ${report.blockedReason}`);
+    for (const conflict of report.conflictSamples) {
+        lines.push(`  Conflict sample: ${conflict.taskId}: ${conflict.fields.join(', ')}`);
+    }
+    for (const failure of report.failures)
+        lines.push(`  Failure: ${failure.taskId}: ${failure.reason}`);
+    for (const warning of report.warnings)
+        lines.push(`  Warning: ${warning}`);
+    return lines.join('\n');
+}
+async function handleUsageBackfill(args) {
+    let parsed;
+    try {
+        parsed = parseUsageBackfillArgs(args);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message === exports.USAGE_BACKFILL_HELP) {
+            console.log(message);
+        }
+        else {
+            console.error(message);
+            console.error(exports.USAGE_BACKFILL_HELP);
+            process.exitCode = 2;
+        }
+        return;
+    }
+    try {
+        const report = await (0, repository_5.runUsageBackfill)(parsed);
+        console.log(formatUsageBackfillReport(report));
+        process.exitCode = report.ok ? 0 : 1;
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
 }
 async function handleDbPush(args) {
     const force = args.includes('--force');

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>;