@crewx/cli 0.9.0-rc.10 → 0.9.0-rc.101

package/dist/bootstrap/codex-writable-roots.d.ts

@@ -33,6 +33,19 @@ export declare function escapeTomlBasicString(value: string): string;
  * Works for both `codex exec` and `codex exec resume` (config-override form).
  */
 export declare function buildCodexWritableRootArgs(crewxHome: string): string[];
+/**
+ * Create an `AdditionalArgsProvider` that skips Codex's git repository trust
+ * check for a resolved workspace.
+ *
+ * The workspace is resolved by the product layer, so an unavailable workspace
+ * must not fall back to the host cwd. The flag is independent of execution
+ * mode because it controls repository trust rather than filesystem access.
+ */
+export declare function createCodexSkipGitRepoCheckProvider(workspaceRoot: string | undefined): AdditionalArgsProvider;
+/**
+ * Compose product-layer argument providers while preserving their order.
+ */
+export declare function composeAdditionalArgsProviders(...providers: AdditionalArgsProvider[]): AdditionalArgsProvider;
 /**
  * Create an `AdditionalArgsProvider` (SDK extension point, WI-20260703-001)
  * that injects CrewX home as a Codex writable root for `workspace-write`

package/dist/bootstrap/codex-writable-roots.js

@@ -20,6 +20,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveCrewxHome = resolveCrewxHome;
 exports.escapeTomlBasicString = escapeTomlBasicString;
 exports.buildCodexWritableRootArgs = buildCodexWritableRootArgs;
+exports.createCodexSkipGitRepoCheckProvider = createCodexSkipGitRepoCheckProvider;
+exports.composeAdditionalArgsProviders = composeAdditionalArgsProviders;
 exports.createCodexWritableRootsProvider = createCodexWritableRootsProvider;
 const os_1 = require("os");
 const path_1 = require("path");
@@ -68,6 +70,29 @@ function buildCodexWritableRootArgs(crewxHome) {
 function isCodexProvider(ctx) {
     return ctx.providerId === 'codex' || ctx.providerStr === 'cli/codex';
 }
+/**
+ * Create an `AdditionalArgsProvider` that skips Codex's git repository trust
+ * check for a resolved workspace.
+ *
+ * The workspace is resolved by the product layer, so an unavailable workspace
+ * must not fall back to the host cwd. The flag is independent of execution
+ * mode because it controls repository trust rather than filesystem access.
+ */
+function createCodexSkipGitRepoCheckProvider(workspaceRoot) {
+    return (ctx) => {
+        if (!isCodexProvider(ctx))
+            return [];
+        if (!workspaceRoot)
+            return [];
+        return ['--skip-git-repo-check'];
+    };
+}
+/**
+ * Compose product-layer argument providers while preserving their order.
+ */
+function composeAdditionalArgsProviders(...providers) {
+    return (ctx) => providers.flatMap((provider) => provider(ctx));
+}
 /**
  * Create an `AdditionalArgsProvider` (SDK extension point, WI-20260703-001)
  * that injects CrewX home as a Codex writable root for `workspace-write`

package/dist/bootstrap/crewx-cli.js

@@ -9,6 +9,7 @@ const plugins_1 = require("@crewx/sdk/plugins");
 const repository_1 = require("@crewx/sdk/repository");
 const register_builtin_tools_1 = require("../register-builtin-tools");
 const version_1 = require("../utils/version");
+const inherited_trace_1 = require("../utils/inherited-trace");
 const codex_writable_roots_1 = require("./codex-writable-roots");
 /**
  * Build a Crewx instance with CLI-standard plugins (FileLogger + SqliteTracing)
@@ -40,6 +41,7 @@ async function createCliCrewx(configPath = process.env.CREWX_CONFIG ?? 'crewx.ya
     else {
         yamlPath = undefined;
     }
+    const skipRoot = yamlPath !== undefined ? (0, path_1.dirname)(absConfigPath) : undefined;
     // Run drizzle migrations once at bootstrap — plugin relies on this guarantee.
     const dbDir = (0, path_1.join)((0, os_1.homedir)(), '.crewx');
     (0, fs_1.mkdirSync)(dbDir, { recursive: true });
@@ -53,11 +55,14 @@ async function createCliCrewx(configPath = process.env.CREWX_CONFIG ?? 'crewx.ya
     }
     const crewx = await sdk_1.Crewx.loadYaml(yamlPath, {
         remoteFactory: createCliCrewx,
-        additionalArgsProvider: (0, codex_writable_roots_1.createCodexWritableRootsProvider)(),
+        additionalArgsProvider: (0, codex_writable_roots_1.composeAdditionalArgsProviders)((0, codex_writable_roots_1.createCodexWritableRootsProvider)(), (0, codex_writable_roots_1.createCodexSkipGitRepoCheckProvider)(skipRoot)),
     });
     (0, register_builtin_tools_1.registerBuiltinToolsIfNeeded)(crewx);
     await crewx.use(new plugins_1.ConversationPlugin());
     await crewx.use(new plugins_1.FileLoggerPlugin({ version: version_1.CLI_VERSION, workspaceRoot }));
-    await crewx.use(new plugins_1.SqliteTracingPlugin({ version: version_1.CLI_VERSION }));
+    await crewx.use(new plugins_1.SqliteTracingPlugin({
+        version: version_1.CLI_VERSION,
+        runnerIdentity: (0, inherited_trace_1.consumeInheritedRunnerIdentity)(),
+    }));
     return crewx;
 }

package/dist/builtin.js

@@ -55,6 +55,7 @@ const BUILTIN_MAP = {
     dreaming: () => Promise.resolve().then(() => __importStar(require('@crewx/dreaming/cli'))),
     wi: () => Promise.resolve().then(() => __importStar(require('@crewx/wi/cli'))),
     chromex: () => Promise.resolve().then(() => __importStar(require('@crewx/chromex/cli'))),
+    notify: () => Promise.resolve().then(() => __importStar(require('@crewx/notify/cli'))),
 };
 exports.BUILTIN_COMMANDS = new Set(Object.keys(BUILTIN_MAP));
 // Load skill-tracer for observability (graceful degradation if unavailable)

package/dist/commands/agent.js

@@ -3,46 +3,11 @@
  * crewx agent handler.
  * Dispatches `crewx agent ls` and `crewx agent prompt` subcommands.
  */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleAgent = handleAgent;
-const path = __importStar(require("path"));
 const fs_1 = require("fs");
 const crewx_cli_1 = require("../bootstrap/crewx-cli");
 const sdk_1 = require("@crewx/sdk");
-const skill_1 = require("@crewx/skill");
 /**
  * Parse a flag from args array.
  * Supports both `--flag=value` and `--flag value` forms.
@@ -135,11 +100,9 @@ async function handleAgentPrompt(crewx, args) {
         process.exit(1);
     }
     try {
-        const skills = loadAgentSkills();
         const rendered = await crewx.renderAgentPromptFull(agentIdRaw, {
             env: process.env,
             session: { mode: 'query', platform: 'cli' },
-            skills,
         });
         const displayId = agentIdRaw.startsWith('@') ? agentIdRaw.slice(1) : agentIdRaw;
         console.log(`\n🤖 **Rendered Prompt for Agent: ${displayId}**\n`);
@@ -197,27 +160,6 @@ async function handleAgent(args) {
             process.exit(1);
     }
 }
-/**
- * Discover available skills and convert to SkillEntry format for template rendering.
- * Searches skills/ and node_modules/@crewx directories.
- */
-function loadAgentSkills() {
-    try {
-        const engine = new skill_1.SkillEngine(process.cwd());
-        const discovered = engine.discover();
-        return discovered.map(s => ({
-            metadata: {
-                name: s.name,
-                version: s.version ?? '0.0.0',
-                description: s.description ?? '',
-            },
-            filePath: s.skillMdPath ?? path.join(s.dir, 'SKILL.md'),
-        }));
-    }
-    catch {
-        return [];
-    }
-}
 function printAgentHelp() {
     console.log(`
 CrewX Agent Management

package/dist/commands/cal.d.ts

@@ -0,0 +1,15 @@
+import type { ActionContext } from '@crewx/knowledge-core';
+/** Suggested wait rungs in seconds. 540 is the safe caller-harness cap. */
+export declare const WAIT_LADDER_SECONDS: readonly [60, 300, 540];
+export interface SuggestWaitSecondsOptions {
+    startedAt?: string | number | Date | null;
+    lastWaitSeconds?: number;
+    now?: number;
+}
+/**
+ * Select the next safe result wait based on task runtime without stepping
+ * down from the wait value the caller just used.
+ */
+export declare function suggestWaitSeconds(options: SuggestWaitSecondsOptions): number;
+/** Write a human-only CAL footer without contaminating command stdout. */
+export declare function writeCalFooter(context: ActionContext): void;

package/dist/commands/cal.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WAIT_LADDER_SECONDS = void 0;
+exports.suggestWaitSeconds = suggestWaitSeconds;
+exports.writeCalFooter = writeCalFooter;
+const knowledge_core_1 = require("@crewx/knowledge-core");
+/** Suggested wait rungs in seconds. 540 is the safe caller-harness cap. */
+exports.WAIT_LADDER_SECONDS = [60, 300, 540];
+function toTimestamp(value) {
+    if (value instanceof Date) {
+        return Number.isFinite(value.getTime()) ? value.getTime() : undefined;
+    }
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? value : undefined;
+    }
+    if (typeof value === 'string') {
+        const timestamp = Date.parse(value);
+        return Number.isFinite(timestamp) ? timestamp : undefined;
+    }
+    return undefined;
+}
+/**
+ * Select the next safe result wait based on task runtime without stepping
+ * down from the wait value the caller just used.
+ */
+function suggestWaitSeconds(options) {
+    const now = Number.isFinite(options.now) ? options.now : Date.now();
+    const startedAt = toTimestamp(options.startedAt);
+    const elapsedSeconds = startedAt === undefined
+        ? 0
+        : Math.max(0, (now - startedAt) / 1000);
+    const rung = exports.WAIT_LADDER_SECONDS.find(seconds => seconds > elapsedSeconds)
+        ?? exports.WAIT_LADDER_SECONDS[exports.WAIT_LADDER_SECONDS.length - 1];
+    const lastWaitSeconds = Number.isFinite(options.lastWaitSeconds)
+        ? Math.max(0, options.lastWaitSeconds)
+        : 0;
+    return Math.min(exports.WAIT_LADDER_SECONDS[exports.WAIT_LADDER_SECONDS.length - 1], Math.max(rung, lastWaitSeconds));
+}
+/** Write a human-only CAL footer without contaminating command stdout. */
+function writeCalFooter(context) {
+    const block = (0, knowledge_core_1.formatActions)((0, knowledge_core_1.generateNextActions)(context));
+    if (block)
+        process.stderr.write(`${block}\n`);
+}

package/dist/commands/db.d.ts

@@ -6,4 +6,6 @@
  *   crewx db push --force        Apply without confirmation + reset migration history
  *   crewx db push --dry-run      Show preview only, no changes
  */
+export declare const TASK_LOG_MIGRATION_HELP = "Usage:\n  crewx db migrate-task-logs --dry-run [--db PATH]\n  crewx db migrate-task-logs --apply [--db PATH] [--batch-tasks N]\n  crewx db migrate-task-logs --verify [--db PATH]\n\nModes:\n  --dry-run  Read and validate legacy blobs without writing or creating a backup.\n  --apply    Create a consistent SQLite backup, then migrate one task per transaction.\n  --verify   Check source invariants, event sequences, counts, and orphan rows.\n\nApply policy:\n  Only blob tasks with status success, failed, or completed are migrated.\n  pending, running, paused, and unknown statuses are deferred for a later run.\n  There is no --force or --include-active option. Apply requires the estimated\n  database/event growth plus a 10 GiB free-space reserve.\n\nExit codes:\n  0  Completed with no malformed rows or invariant failures.\n  1  Safe tasks completed but a row/invariant failed, or apply was blocked.\n  2  Invalid command-line arguments.\n\nThe command never runs automatically at server startup and never runs VACUUM.";
+export declare const USAGE_BACKFILL_HELP = "Usage:\n  crewx db backfill-usage [--dry-run|--apply|--verify] [--db PATH] [--backup PATH]\n  crewx db backfill-usage --restore SNAPSHOT [--db PATH]\n\nModes:\n  --dry-run  Show provider/reason recovery plans without changing the database (default).\n  --apply    Create a row-level undo snapshot, then account one task per transaction.\n  --verify   Recheck remaining targets and usageAccounting markers without changing the database.\n  --restore  Restore rows from SNAPSHOT when their current values still match the snapshot after-state.\n\nApply policy:\n  Only success, failed, and completed tasks with zero recorded usage are considered.\n  Workflow/MCP anchors and plugin/mock rows are excluded. Rows completed within 24 hours\n  are not marked unavailable when their logs do not contain usage.\n\nExit codes:\n  0  Completed successfully.\n  1  Apply was blocked or one or more task updates failed.\n  2  Invalid command-line arguments.";
 export declare function handleDb(args: string[]): Promise<void>;

package/dist/commands/db.js

@@ -11,12 +11,56 @@ 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.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");
+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.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 +101,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 +118,343 @@ function prompt(question) {
 }
 async function handleDb(args) {
     const subcommand = args[0];
+    if (subcommand === 'migrate-task-logs') {
+        await handleTaskLogMigration(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);
+        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;
+    }
+}
+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_4.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');