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

package/dist/commands/registry.js

@@ -13,17 +13,19 @@ exports.KNOWN_COMMANDS = new Set([
     'q', 'query',
     'x', 'execute',
     'agent',
-    'ps', 'kill', 'result', 'log', 'restart',
+    'ps', 'stop', 'kill', 'result', 'log', 'restart',
     'doctor', 'init',
     'db',
     'help',
+    'shortcut',
+    'publish',
     'slack', 'slack:files',
     'hook', 'hook-dispatch',
 ]);
 /** Built-in tool commands routed via handleBuiltin(). */
 exports.BUILTIN_COMMAND_NAMES = new Set([
     'memory', 'search', 'doc', 'wbs', 'cron', 'workflow', 'skill', 'dreaming',
-    'wi', 'chromex',
+    'wi', 'chromex', 'notify', 'app',
 ]);
 /** Commands not yet migrated from cli-bak — show a migration message. */
 exports.NOT_YET_MIGRATED = new Set([

package/dist/commands/resolve-prompt.js

@@ -14,6 +14,28 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.readStdin = readStdin;
 exports.resolvePrompt = resolvePrompt;
 const fs_1 = require("fs");
+function decodePromptFile(promptFile) {
+    const contents = (0, fs_1.readFileSync)(promptFile);
+    if (contents.length >= 3
+        && contents[0] === 0xef
+        && contents[1] === 0xbb
+        && contents[2] === 0xbf) {
+        return contents.subarray(3).toString('utf8');
+    }
+    if (contents.length >= 2 && contents[0] === 0xff && contents[1] === 0xfe) {
+        return contents.subarray(2).toString('utf16le');
+    }
+    if (contents.length >= 2 && contents[0] === 0xfe && contents[1] === 0xff) {
+        const payload = contents.subarray(2);
+        for (let index = 0; index + 1 < payload.length; index += 2) {
+            const first = payload[index];
+            payload[index] = payload[index + 1];
+            payload[index + 1] = first;
+        }
+        return payload.toString('utf16le');
+    }
+    return contents.toString('utf8');
+}
 /**
  * Read all bytes from stdin (pipe or redirect).
  * Returns empty string when stdin is a TTY (interactive terminal).
@@ -43,7 +65,7 @@ async function readStdin() {
 async function resolvePrompt(argvPrompt, promptFile, _readStdin = readStdin) {
     let external = '';
     if (promptFile) {
-        external = (0, fs_1.readFileSync)(promptFile, 'utf8').trimEnd();
+        external = decodePromptFile(promptFile).trimEnd();
     }
     else if (!argvPrompt) {
         external = (await _readStdin()).trimEnd();

package/dist/commands/resolve-recipient.d.ts

@@ -0,0 +1,14 @@
+export interface ResolveRecipientOptions {
+    positionalRef?: string;
+    toFlag?: string;
+    agentContext: boolean;
+    bodyForHint?: string;
+    command?: string;
+    invocationArgs?: string[];
+}
+export declare class RecipientResolutionError extends Error {
+    constructor(message: string);
+}
+export declare function resolveRecipient(options: ResolveRecipientOptions): {
+    agentRef: string;
+};

package/dist/commands/resolve-recipient.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RecipientResolutionError = void 0;
+exports.resolveRecipient = resolveRecipient;
+class RecipientResolutionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RecipientResolutionError';
+    }
+}
+exports.RecipientResolutionError = RecipientResolutionError;
+function resolveRecipient(options) {
+    const toRef = normalizeRecipient(options.toFlag, true);
+    const positionalRef = normalizeRecipient(options.positionalRef, false);
+    if (toRef && positionalRef && toRef !== positionalRef) {
+        throw new RecipientResolutionError(`Recipient was specified twice: --to ${toRef.slice(1)} conflicts with positional ${positionalRef}.`);
+    }
+    const agentRef = toRef ?? positionalRef;
+    if (agentRef)
+        return { agentRef };
+    if (!options.agentContext)
+        return { agentRef: '@crewx' };
+    const hintedId = options.bodyForHint?.match(/^@(\S+)/u)?.[1];
+    const retryId = hintedId ?? '<agent-id>';
+    const command = options.command ?? 'query';
+    const retryArgs = (options.invocationArgs ?? []).map(formatRetryArgument).join(' ');
+    const retryCommand = `crewx ${command} --to ${retryId}${retryArgs ? ` ${retryArgs}` : ''}`;
+    throw new RecipientResolutionError('No recipient was specified. Agent calls must set one explicitly; nothing was run.\n' +
+        `Retry command: ${retryCommand}\n` +
+        'To ask the built-in assistant on purpose, use --to crewx.');
+}
+function normalizeRecipient(value, required) {
+    if (value === undefined)
+        return undefined;
+    const id = value.trim().replace(/^@/u, '');
+    if (!id) {
+        if (required)
+            throw new RecipientResolutionError('--to requires an agent id.');
+        return undefined;
+    }
+    return `@${id}`;
+}
+function formatRetryArgument(value) {
+    if (!/\s/u.test(value))
+        return value;
+    return `"${value.replaceAll('"', '\\"')}"`;
+}

package/dist/commands/restart.d.ts

@@ -14,7 +14,9 @@
  *   crewx restart <task-id>
  *
  * Behavior:
- *   - Only tasks with status='failed' can be restarted.
+ *   - Only tasks with status='failed' can be restarted, except a run whose end was not
+ *     observed (`terminalReason: 'runner_lost'`): it may still be running, so it is refused
+ *     by default (same decision as the SDK's `isTaskRetryableByDefault`).
  *   - A new taskId is generated; the original task row is never mutated.
  *   - metadata.restartedFromTaskId (+ retriedFromTaskId for compat) is recorded.
  *   - The Web UI `TSK.RETRY` system-message prefix is reused verbatim.

package/dist/commands/restart.js

@@ -15,7 +15,9 @@
  *   crewx restart <task-id>
  *
  * Behavior:
- *   - Only tasks with status='failed' can be restarted.
+ *   - Only tasks with status='failed' can be restarted, except a run whose end was not
+ *     observed (`terminalReason: 'runner_lost'`): it may still be running, so it is refused
+ *     by default (same decision as the SDK's `isTaskRetryableByDefault`).
  *   - A new taskId is generated; the original task row is never mutated.
  *   - metadata.restartedFromTaskId (+ retriedFromTaskId for compat) is recorded.
  *   - The Web UI `TSK.RETRY` system-message prefix is reused verbatim.
@@ -75,9 +77,17 @@ async function handleRestart(args) {
         process.exit(1);
         return;
     }
-    if (original.status !== 'failed') {
-        process.stderr.write(`Error: Task ${taskId} is not in failed state (current: ${original.status ?? 'unknown'}). ` +
-            `Only failed tasks can be restarted.\n`);
+    if (!(0, sdk_1.isTaskRetryableByDefault)(original)) {
+        if ((0, sdk_1.normalizeTaskStatus)(original) === 'failed') {
+            // failed + runner_lost: the run was marked failed without anyone seeing it end.
+            process.stderr.write(`Error: Task ${taskId} was not restarted: the end of the run was not observed (runner lost), ` +
+                `so it may have done part of the work or may still be running. ` +
+                `Check it with \`crewx log ${taskId}\` or \`crewx ps\` before running it again.\n`);
+        }
+        else {
+            process.stderr.write(`Error: Task ${taskId} is not in failed state (current: ${original.status ?? 'unknown'}). ` +
+                `Only failed tasks can be restarted.\n`);
+        }
         process.exit(1);
         return;
     }

package/dist/commands/result.d.ts

@@ -3,8 +3,13 @@
  * Retrieves the result of a completed task by its ID.
  *
  * Usage:
- *   crewx result <task-id>         Print raw result
- *   crewx result <task-id> --json  Print full task record as JSON
- *   crewx result                   List recent tasks (latest 10)
+ *   crewx result <task-id>            Print raw result
+ *   crewx result <task-id> --json     Print full task record as JSON
+ *   crewx result <task-id> --wait=<seconds> Poll (1s interval) up to the given
+ *                                    number of seconds for
+ *                                    the task to leave 'pending'/'running'. Exit 124 on
+ *                                    timeout. --wait=0 behaves like no --wait
+ *                                    (single immediate check).
+ *   crewx result                      List recent tasks (latest 10)
  */
 export declare function handleResult(args: string[]): Promise<void>;

package/dist/commands/result.js

@@ -4,25 +4,102 @@
  * Retrieves the result of a completed task by its ID.
  *
  * Usage:
- *   crewx result <task-id>         Print raw result
- *   crewx result <task-id> --json  Print full task record as JSON
- *   crewx result                   List recent tasks (latest 10)
+ *   crewx result <task-id>            Print raw result
+ *   crewx result <task-id> --json     Print full task record as JSON
+ *   crewx result <task-id> --wait=<seconds> Poll (1s interval) up to the given
+ *                                    number of seconds for
+ *                                    the task to leave 'pending'/'running'. Exit 124 on
+ *                                    timeout. --wait=0 behaves like no --wait
+ *                                    (single immediate check).
+ *   crewx result                      List recent tasks (latest 10)
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleResult = handleResult;
+const sdk_1 = require("@crewx/sdk");
 const repository_1 = require("@crewx/sdk/repository");
-function statusIcon(status) {
-    switch (status) {
+const cal_1 = require("./cal");
+const POLL_INTERVAL_MS = 1000;
+const REAP_INTERVAL_MS = 10_000;
+/**
+ * A run whose end was not observed is `failed` with the structured reason `runner_lost`, not a
+ * status of its own: it may have done part of the work or may still be running.
+ */
+function isRunnerLost(task) {
+    return task.status === 'failed' && (0, repository_1.readTaskTerminalReason)(task) === 'runner_lost';
+}
+function statusIcon(task) {
+    if (isRunnerLost(task))
+        return '⚠️';
+    switch (task.status) {
+        case 'pending': return '🕓';
         case 'running': return '⏳';
         case 'success': return '✅';
         case 'failed': return '❌';
+        case 'stopped': return '⏹';
         default: return '❓';
     }
 }
+function isActiveStatus(status) {
+    return status === 'pending' || status === 'running';
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function resultCommandId(status) {
+    switch (status) {
+        case 'pending': return 'crewx.result-pending';
+        case 'running': return 'crewx.result-running';
+        case 'success': return 'crewx.result-done';
+        case 'failed':
+        case 'stopped':
+            return 'crewx.result-terminal-abnormal';
+        default: return 'crewx.result';
+    }
+}
+function writeResultCalFooter(task, lastWaitSeconds) {
+    const params = { taskId: task.id };
+    if (task.agent_id)
+        params.agent = task.agent_id;
+    if (task.thread_id)
+        params.thread = task.thread_id;
+    if (isActiveStatus(task.status)) {
+        params.wait = String((0, cal_1.suggestWaitSeconds)({
+            startedAt: task.started_at,
+            lastWaitSeconds,
+        }));
+    }
+    (0, cal_1.writeCalFooter)({ commandId: resultCommandId(task.status), params });
+}
+function formatRuntimeDuration(startedAt, now = Date.now()) {
+    const startedAtMs = Date.parse(startedAt);
+    const elapsedSeconds = Number.isFinite(startedAtMs)
+        ? Math.max(0, Math.floor((now - startedAtMs) / 1000))
+        : 0;
+    const hours = Math.floor(elapsedSeconds / 3600);
+    const minutes = Math.floor((elapsedSeconds % 3600) / 60);
+    const seconds = elapsedSeconds % 60;
+    if (hours > 0)
+        return `${hours}h ${minutes}m ${seconds}s`;
+    if (minutes > 0)
+        return `${minutes}m ${seconds}s`;
+    return `${seconds}s`;
+}
+/** Parses `--wait=<seconds>`. Returns undefined when the flag is absent. */
+function parseWaitSeconds(args) {
+    const arg = args.find(a => a.startsWith('--wait='));
+    if (arg === undefined)
+        return undefined;
+    const n = Number(arg.slice('--wait='.length));
+    return Number.isFinite(n) && n >= 0 ? n : 0;
+}
 async function handleResult(args) {
     const jsonMode = args.includes('--json');
+    const waitSeconds = parseWaitSeconds(args);
     const taskId = args.find(a => !a.startsWith('--'));
     const repo = new repository_1.TaskRepository();
+    const initialReaped = repo.reapOrphanedTasks({ tickIntervalMs: REAP_INTERVAL_MS });
+    if (initialReaped > 0)
+        console.error(`Reaped ${initialReaped} orphaned task(s)`);
     if (!taskId) {
         const all = repo.getAllTasks();
         const recent = all.slice(0, 10);
@@ -33,38 +110,100 @@ async function handleResult(args) {
         }
         console.log('Recent Tasks (latest 10)\n');
         recent.forEach((task, idx) => {
-            const icon = statusIcon(task.status);
+            const icon = statusIcon(task);
             console.log(`${idx + 1}. ${icon} ${task.id}`);
             console.log(`   Agent: ${task.agent_id ?? '—'}  Mode: ${task.mode ?? '—'}`);
-            console.log(`   Started: ${new Date(task.started_at).toLocaleString()}`);
+            console.log(`   Started: ${(0, sdk_1.formatDisplayTimestamp)(new Date(task.started_at))}`);
             if (task.completed_at) {
-                console.log(`   Completed: ${new Date(task.completed_at).toLocaleString()}`);
+                console.log(`   Completed: ${(0, sdk_1.formatDisplayTimestamp)(new Date(task.completed_at))}`);
             }
             console.log('');
         });
         console.log('Tip: Run `crewx result <task-id>` to see full output.');
+        if (!jsonMode)
+            writeResultCalFooter(recent[0]);
         return;
     }
-    const task = repo.getTask(taskId);
+    let task = repo.getTask(taskId);
     if (!task) {
         console.error(`Error: Task not found: ${taskId}`);
         process.exit(1);
         return;
     }
+    if (waitSeconds !== undefined && waitSeconds > 0 && isActiveStatus(task.status)) {
+        const deadline = Date.now() + waitSeconds * 1000;
+        let lastReapAt = Date.now();
+        while (task && isActiveStatus(task.status)) {
+            if (Date.now() >= deadline) {
+                console.error(`Task ${taskId} is still ${task.status} (waited ${waitSeconds}s; ` +
+                    `running for ${formatRuntimeDuration(task.started_at)}). ` +
+                    'Not stalled — check again with a longer wait.');
+                writeResultCalFooter(task, waitSeconds);
+                process.exit(124);
+                return;
+            }
+            await sleep(Math.min(POLL_INTERVAL_MS, Math.max(0, deadline - Date.now())));
+            if (Date.now() - lastReapAt >= REAP_INTERVAL_MS) {
+                const reaped = repo.reapOrphanedTasks({ tickIntervalMs: REAP_INTERVAL_MS });
+                if (reaped > 0)
+                    console.error(`Reaped ${reaped} orphaned task(s)`);
+                lastReapAt = Date.now();
+            }
+            task = repo.getTask(taskId);
+            if (!task) {
+                console.error(`Error: Task not found: ${taskId}`);
+                process.exit(1);
+                return;
+            }
+        }
+    }
     if (jsonMode) {
         console.log(JSON.stringify(task, null, 2));
         return;
     }
+    if (task.status === 'pending') {
+        console.error(`🕓 Task ${taskId} is pending (waiting to start — runner has not adopted the task yet).`);
+        const nextWaitSeconds = (0, cal_1.suggestWaitSeconds)({
+            startedAt: task.started_at,
+            lastWaitSeconds: waitSeconds,
+        });
+        console.error(`Use \`crewx result ${taskId} --wait=${nextWaitSeconds}\` to wait for completion.`);
+        writeResultCalFooter(task, waitSeconds);
+        process.exit(1);
+        return;
+    }
     if (task.status === 'running') {
         console.error(`Task ${taskId} is still running.`);
-        console.error(`Use \`crewx kill ${taskId}\` to stop it.`);
+        const nextWaitSeconds = (0, cal_1.suggestWaitSeconds)({
+            startedAt: task.started_at,
+            lastWaitSeconds: waitSeconds,
+        });
+        console.error(`Use \`crewx result ${taskId} --wait=${nextWaitSeconds}\` to wait longer or \`crewx log ${taskId}\` to inspect progress.`);
+        writeResultCalFooter(task, waitSeconds);
+        process.exit(1);
+        return;
+    }
+    if (task.status === 'stopped') {
+        if (task.result !== null && task.result !== undefined) {
+            console.log(task.result);
+        }
+        console.error(`⏹ Task ${taskId} was stopped by user: ${task.error ?? 'no further details'}.`);
+        writeResultCalFooter(task);
+        process.exit(1);
+        return;
+    }
+    if (isRunnerLost(task)) {
+        console.error(`⚠️ Task ${taskId} runner lost before completion: ${task.error ?? 'no further details'}.`);
+        writeResultCalFooter(task);
         process.exit(1);
         return;
     }
     if (task.status === 'failed') {
         console.error(`Task ${taskId} failed: ${task.error ?? 'unknown error'}`);
+        writeResultCalFooter(task);
         process.exit(1);
         return;
     }
     console.log(task.result ?? '');
+    writeResultCalFooter(task);
 }

package/dist/commands/shortcut.d.ts

@@ -0,0 +1 @@
+export declare function handleShortcut(args: string[]): Promise<void>;

package/dist/commands/shortcut.js

@@ -0,0 +1,267 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleShortcut = handleShortcut;
+/**
+ * crewx shortcut handler — thin CLI wrapper over @crewx/sdk/desktop.
+ *
+ * Usage:
+ *   crewx shortcut status [--json]
+ *   crewx shortcut install [--force] [--json]
+ *   crewx shortcut uninstall [--json]
+ *
+ * All win32/foreign/superseded/force judgment lives in @crewx/sdk/desktop.
+ * This module only parses argv, forwards options, and renders the result.
+ */
+const desktop_1 = require("@crewx/sdk/desktop");
+const parse_common_flags_1 = require("./parse-common-flags");
+const NOT_WINDOWS_MESSAGE = 'NOT_WINDOWS: Desktop shortcuts are only supported on Windows.';
+function parseShortcutFlags(args, allowForce) {
+    let json = false;
+    let force = false;
+    for (const arg of args) {
+        if (arg === '--json') {
+            json = true;
+            continue;
+        }
+        if (arg === '--force' && allowForce) {
+            force = true;
+            continue;
+        }
+        throw new parse_common_flags_1.UnknownOptionError(`Unknown option: ${arg}`);
+    }
+    return { json, force };
+}
+/** Forwarded verbatim to stderr as each SDK phase starts — never buffered. */
+function onProgress(event) {
+    process.stderr.write(`[shortcut] ${event.message}\n`);
+}
+function printJson(payload) {
+    console.log(JSON.stringify(payload));
+}
+/** Prints the error and exits 1. Never returns (matches `process.exit`'s `never` type). */
+function failWithError(err, json) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (json) {
+        printJson({ success: false, error: message });
+    }
+    else {
+        console.error(`✗ ${message}`);
+    }
+    process.exit(1);
+}
+/** The SDK returns `supported:false` (no throw) for install/uninstall on non-Windows. */
+function failNotWindows(json) {
+    if (json) {
+        printJson({ success: false, supported: false, state: 'unsupported', error: NOT_WINDOWS_MESSAGE });
+    }
+    else {
+        console.error(`✗ ${NOT_WINDOWS_MESSAGE}`);
+    }
+    process.exit(1);
+}
+/**
+ * Detects the two ways a resolved (non-thrown) install result must NOT be
+ * read as success: a `superseded` shortcut (checked via both `state` and the
+ * `errors[]` entry, since either alone could otherwise be missed) and an
+ * unconfirmed global install (`installedGlobal:false` with
+ * `GLOBAL_INSTALL_UNCONFIRMED` in errors — npm exited 0 but re-detection
+ * could not confirm it).
+ */
+function installFailureReason(result) {
+    const supersededError = result.errors.find((e) => e.startsWith('SUPERSEDED:'));
+    if (result.state === 'superseded' || supersededError) {
+        return supersededError ?? 'Installed shortcut belongs to a newer CrewX version; refusing to modify it.';
+    }
+    const unconfirmedError = result.errors.find((e) => e.startsWith('GLOBAL_INSTALL_UNCONFIRMED:'));
+    if (!result.installedGlobal && unconfirmedError) {
+        return unconfirmedError;
+    }
+    if (result.errors.length > 0) {
+        return result.errors[0];
+    }
+    return null;
+}
+/**
+ * Only these two re-detected states mean the Desktop truly has no CrewX
+ * shortcut left. Everything else — `foreign`/`superseded` (SDK refused to
+ * touch it) and `installed`/`stale` (the `.lnk` unlink threw and was
+ * swallowed as "already gone" — install.ts `uninstallShortcut`) — means the
+ * file is still on disk. A success ALLOWLIST is used instead of enumerating
+ * failure states so an unlink failure (EPERM/EBUSY/locked/AV hook) that
+ * re-detects back to `installed` fails closed by construction, rather than
+ * requiring every new failure path to be added to an exclusion list.
+ */
+const UNINSTALL_SUCCESS_STATES = new Set(['declined', 'not-installed']);
+function uninstallFailureReason(result) {
+    if (UNINSTALL_SUCCESS_STATES.has(result.state)) {
+        return null;
+    }
+    const supersededError = result.errors.find((e) => e.startsWith('SUPERSEDED:'));
+    if (result.state === 'superseded' || supersededError) {
+        return supersededError ?? 'Installed shortcut belongs to a newer CrewX version; nothing was removed.';
+    }
+    if (result.state === 'foreign') {
+        const nsisError = result.errors.find((e) => e.startsWith('NSIS_PRESENT:'));
+        return nsisError ?? 'Existing Desktop shortcut is not managed by CrewX; nothing was removed.';
+    }
+    if (result.errors.length > 0) {
+        return result.errors[0];
+    }
+    return `CrewX desktop shortcut could not be removed (state: ${result.state}).`;
+}
+function printStatusHuman(status) {
+    switch (status.state) {
+        case 'unsupported':
+            console.log('Desktop shortcuts are only supported on Windows.');
+            break;
+        case 'not-installed':
+            console.log('No CrewX desktop shortcut installed yet.');
+            console.log('Run `crewx shortcut install` to create one.');
+            break;
+        case 'declined':
+            console.log('CrewX desktop shortcut setup was previously dismissed.');
+            console.log('Run `crewx shortcut install` to create one.');
+            break;
+        case 'installed':
+            console.log('✓ CrewX desktop shortcut is installed and up to date.');
+            if (status.shortcutPath)
+                console.log(`  Shortcut: ${status.shortcutPath}`);
+            break;
+        case 'stale':
+            console.log('⚠ CrewX desktop shortcut needs an update.');
+            console.log('Run `crewx shortcut install` to refresh it.');
+            break;
+        case 'foreign':
+            console.log('⚠ A Desktop shortcut exists that CrewX does not manage.');
+            console.log('Run `crewx shortcut install --force` to replace it.');
+            break;
+        case 'superseded':
+            console.log('⚠ The installed shortcut belongs to a newer CrewX version than the one running.');
+            console.log('Update CrewX before touching the shortcut.');
+            break;
+    }
+    for (const e of status.errors) {
+        console.log(`  note: ${e}`);
+    }
+}
+async function runStatus(args) {
+    const { json } = parseShortcutFlags(args, false);
+    let status;
+    try {
+        status = await (0, desktop_1.getShortcutStatus)();
+    }
+    catch (err) {
+        failWithError(err, json);
+    }
+    if (json) {
+        printJson(status);
+        return;
+    }
+    printStatusHuman(status);
+}
+async function runInstall(args) {
+    const { json, force } = parseShortcutFlags(args, true);
+    let result;
+    try {
+        result = await (0, desktop_1.installShortcut)({ force, onProgress });
+    }
+    catch (err) {
+        failWithError(err, json);
+    }
+    if (!result.supported) {
+        failNotWindows(json);
+    }
+    const failure = installFailureReason(result);
+    if (failure) {
+        if (json) {
+            printJson({ ...result, success: false });
+        }
+        else {
+            console.error(`✗ ${failure}`);
+        }
+        process.exit(1);
+    }
+    if (json) {
+        printJson({ ...result, success: true });
+        return;
+    }
+    if (result.changed) {
+        console.log('✓ CrewX desktop shortcut installed. Double-click "CrewX" on your Desktop to launch it.');
+    }
+    else {
+        console.log('✓ CrewX desktop shortcut is already up to date. Double-click "CrewX" on your Desktop to launch it.');
+    }
+    if (result.shortcutPath)
+        console.log(`  Shortcut: ${result.shortcutPath}`);
+}
+async function runUninstall(args) {
+    const { json } = parseShortcutFlags(args, false);
+    let result;
+    try {
+        result = await (0, desktop_1.uninstallShortcut)();
+    }
+    catch (err) {
+        failWithError(err, json);
+    }
+    if (!result.supported) {
+        failNotWindows(json);
+    }
+    const failure = uninstallFailureReason(result);
+    if (failure) {
+        if (json) {
+            printJson({ ...result, success: false });
+        }
+        else {
+            console.error(`✗ ${failure}`);
+            for (const e of result.errors) {
+                if (e !== failure)
+                    console.error(`  note: ${e}`);
+            }
+        }
+        process.exit(1);
+    }
+    if (json) {
+        printJson({ ...result, success: true });
+        return;
+    }
+    console.log('✓ CrewX desktop shortcut removed.');
+}
+function printHelp() {
+    console.log(`
+crewx shortcut — manage the Windows Desktop shortcut for CrewX
+
+Usage:
+  crewx shortcut status [--json]
+  crewx shortcut install [--force] [--json]
+  crewx shortcut uninstall [--json]
+
+Options:
+  --json     Print machine-readable JSON to stdout (progress/log always go to stderr)
+  --force    (install only) Overwrite a Desktop shortcut CrewX does not manage.
+             Never overwrites a shortcut created by a newer CrewX version.
+
+Notes:
+  Windows only. On macOS/Linux, \`status\` reports state "unsupported" (exit 0);
+  \`install\`/\`uninstall\` exit 1 with no changes made.
+`.trim());
+}
+async function handleShortcut(args) {
+    const subcommand = args[0];
+    if (!subcommand || subcommand === 'help' || subcommand === '--help' || subcommand === '-h') {
+        printHelp();
+        return;
+    }
+    const rest = args.slice(1);
+    switch (subcommand) {
+        case 'status':
+            return runStatus(rest);
+        case 'install':
+            return runInstall(rest);
+        case 'uninstall':
+            return runUninstall(rest);
+        default:
+            console.error(`Unknown shortcut subcommand: ${subcommand}`);
+            console.error('Run `crewx shortcut help` for usage.');
+            process.exit(1);
+    }
+}