@3minapi/cli 0.0.0-stage → 0.22.1

package/dist/commands/start.js

@@ -0,0 +1,443 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { ApiClient, userAgent } from "../core/api.js";
+import { APP_LOG_DIR, BIN, CliError, PROJECT_CONFIG_FILE, DEFAULT_LOCAL_SERVER_PORT, DETACH_READY_MS, ENV, ExitCode, ConfigError, RECEIVE_MODES, isTrustedLiveUrl, LOCAL_SERVER_TOKEN_FILE, MONTH_MS, RUNNER_OUT_FILE, STOP_CHECK_INTERVAL_MS, StopError, UsageError } from "../core/domain/index.js";
+import { outputTail, spawnDetached } from "../core/host/detach.js";
+import { LIVE_META } from "../core/control-db.js";
+import { LiveReceiver } from "../core/host/live-receiver.js";
+import { Poller } from "../core/host/poller.js";
+import { acquireRunnerLock, readRunner } from "../core/host/runner-lock.js";
+import { openSession, recordEnd, recordStop, rememberQuota, stopHint } from "../core/host/session.js";
+import { formatCount } from "../core/text.js";
+import { formatInterval, formatLocal, formatThroughput, maxTasksPerMinute, sleep } from "../core/time.js";
+import { startWorkers } from "../modules/workers/start.js";
+import { noticeUpdate, requireProject, requireToken, requireWorkersDir } from "./common.js";
+import { LatestWatch, readLatest, updateInfo } from "../core/update-notice.js";
+export const start = {
+    name: 'start',
+    summary: 'Run this machine as a 3Min API host: fetch tasks and run the worker files until stopped',
+    usage: '[--detach] [--mode live|poll] [--serve [--port <port>] [--public]]',
+    description: 'Runs this machine as a 3Min API host. It registers the worker files in the workers\n' +
+        'folder with 3Min API as local workers (one API call), then fetches their tasks and\n' +
+        'runs them on this machine.\n' +
+        '\n' +
+        'When to fetch (--mode): live (default) keeps a connection open and fetches when 3Min API\n' +
+        'signals a new or cancelled task — idle costs no calls; each connect or reconnect is one\n' +
+        'call and each fetch is one. poll fetches every interval instead (pollIntervalMs), and every\n' +
+        'poll counts as one call even when nothing is waiting — use it where WebSockets are blocked\n' +
+        "(a company proxy or firewall; '3minapi doctor' checks). There is no automatic switch.\n" +
+        '\n' +
+        'Adding or renaming a worker file, or changing its description, takes effect on\n' +
+        "'3minapi reload' (no restart; running tasks keep going) — 'worker new' reloads by itself.\n" +
+        'Handler code and .env changes apply to the next task. A worker deleted on the server is\n' +
+        'turned off for the run, and start ends when no worker is left.\n' +
+        '\n' +
+        'The server holds the queue: each fetch takes only as many tasks as can start now (up to the\n' +
+        'concurrency setting, default 4). In poll mode at most concurrency x polls per minute run — about\n' +
+        '8 a minute at 4 every 30s. A fetched task is run to the end; if this machine stops before it finishes, the\n' +
+        'next start reports it failed (host_restarted) instead of running it again.\n' +
+        'Stops all calls immediately when the quota runs out or the token is revoked, and does not\n' +
+        'start again on its own — run start again after fixing the cause.\n' +
+        '\n' +
+        'Runs in the foreground by default (Ctrl+C to stop). With --detach it keeps running\n' +
+        "after the terminal is closed — stop it with '3minapi stop'. Only one can run per host.\n" +
+        'It does not start again after a reboot.\n' +
+        '\n' +
+        '--serve also opens an HTTP server: POST /task/<worker> on 127.0.0.1, with the token\n' +
+        `in ${LOCAL_SERVER_TOKEN_FILE} (Authorization: Bearer <token>). --public listens on all\n` +
+        'interfaces instead and serves worker files as public workers: 3Min API POSTs signed tasks\n' +
+        'to this machine. Use it for names registered as public workers on the dashboard, with\n' +
+        'THREEMINAPI_WORKER_<NAME>_SECRET and THREEMINAPI_WORKER_<NAME>_KEY set; those files are\n' +
+        'not registered as local workers. Long-running servers only — serverless platforms are\n' +
+        'not supported.',
+    options: {
+        detach: {
+            type: 'boolean',
+            short: 'd',
+            description: "Run in the background (stop with '3minapi stop')"
+        },
+        mode: {
+            type: 'string',
+            valueName: RECEIVE_MODES.join('|'),
+            description: 'When to fetch tasks: live (default — when 3Min API signals) or poll (every interval)'
+        },
+        serve: {
+            type: 'boolean',
+            description: 'Also open an HTTP server (127.0.0.1; all interfaces with --public)'
+        },
+        port: {
+            type: 'string',
+            valueName: 'port',
+            description: `HTTP server port (default ${DEFAULT_LOCAL_SERVER_PORT}, with --serve)`
+        },
+        public: {
+            type: 'boolean',
+            description: 'Serve worker files as public workers on all interfaces (with --serve)'
+        }
+    },
+    args: { min: 0, max: 0 },
+    async run(ctx) {
+        if ((ctx.values.port !== undefined || ctx.values.public) && !ctx.values.serve) {
+            throw new UsageError('--port and --public need --serve');
+        }
+        if (ctx.values.detach && ctx.env[ENV.detached] !== '1')
+            return startDetached(ctx);
+        return startForeground(ctx);
+    }
+};
+async function startForeground(ctx) {
+    const { out } = ctx;
+    const token = requireToken(ctx);
+    const detachedChild = ctx.env[ENV.detached] === '1';
+    const session = openSession(ctx);
+    try {
+        const { values: cfg } = session.config;
+        const { root, dir: workersDir } = requireWorkersDir(session.config);
+        const serve = Boolean(ctx.values.serve);
+        const isPublic = Boolean(ctx.values.public);
+        const lock = acquireRunnerLock(ctx.dirs.data, {
+            detached: detachedChild,
+            port: serve ? cfg.localServerPort : null,
+            public: serve && isPublic,
+            intervalMs: cfg.receiveMode === 'live' ? null : cfg.pollIntervalMs,
+            mode: cfg.receiveMode,
+            concurrency: cfg.concurrency,
+            apiUrl: cfg.apiUrl,
+            outFile: detachedChild ? outFilePath(ctx) : null,
+            workersDir,
+            reload: true,
+            localDelete: true
+        }, ctx.now());
+        ctx.chdir(root);
+        ctx.claimInterrupt();
+        const shutdown = new AbortController();
+        const onAbort = () => shutdown.abort();
+        ctx.signal.addEventListener('abort', onAbort, { once: true });
+        let polling = null;
+        const projectFile = session.config.projectFile ?? path.join(root, PROJECT_CONFIG_FILE);
+        let projectGone = false;
+        let fileMisses = 0;
+        const stopWatch = setInterval(() => {
+            lock.heartbeat();
+            if (!projectGone) {
+                fileMisses = existsSync(projectFile) ? 0 : fileMisses + 1;
+                if (!existsSync(root) || fileMisses >= PROJECT_GONE_MISSES) {
+                    projectGone = true;
+                    session.logger.warn('project folder gone', { root });
+                    shutdown.abort();
+                }
+            }
+            if (lock.stopRequested())
+                shutdown.abort();
+            else if (polling?.resyncIdle) {
+                const deleted = lock.takeDeleted();
+                if (deleted.length > 0)
+                    polling.requestDrop(deleted);
+                if (lock.takeReload())
+                    polling.requestResync();
+            }
+        }, STOP_CHECK_INTERVAL_MS);
+        let workers = null;
+        try {
+            const debug = (m, a) => session.logger.debug(m, a);
+            const updates = new LatestWatch({
+                db: session.db,
+                now: ctx.now,
+                log: debug,
+                announce: () => {
+                    if (!detachedChild) {
+                        noticeUpdate(ctx, session, true);
+                        return;
+                    }
+                    const info = updateInfo(ctx.version, readLatest(session.db, debug), true);
+                    if (info.available) {
+                        session.logger.info('update available', { current: info.current, latest: info.latest });
+                    }
+                }
+            });
+            const agent = userAgent(ctx.version, ctx.platform);
+            const api = new ApiClient({
+                apiUrl: cfg.apiUrl,
+                token: token.token,
+                userAgent: agent,
+                onServerCli: (cli) => updates.observe(cli)
+            });
+            let receiver;
+            resetLiveState(session);
+            workers = await startWorkers({
+                ctx,
+                session,
+                api,
+                token: token.token,
+                userAgent: agent,
+                lock,
+                root,
+                workersDir,
+                serve,
+                isPublic,
+                signal: shutdown.signal,
+                onStop: (err) => receiver.stop(err),
+                onLive: (live) => {
+                    if (receiver instanceof LiveReceiver)
+                        receiver.setUrl(live.url);
+                    else
+                        rememberLiveUrl(session, live.url, cfg.apiUrl, ctx.now());
+                }
+            });
+            if (projectGone)
+                throw projectGoneError(root);
+            if (!workers) {
+                out.info('Stopped.');
+                return ctx.signal.aborted ? ExitCode.Interrupted : ExitCode.Ok;
+            }
+            const onPull = pullReporter(ctx, cfg.receiveMode, (quota) => rememberQuota(session, quota, ctx.now()));
+            const onError = (err) => out.warn(err.message);
+            if (workers.live)
+                rememberLiveUrl(session, workers.live.url, cfg.apiUrl, ctx.now());
+            if (cfg.receiveMode === 'live') {
+                const url = liveUrl(workers.live?.url ?? null, cfg.apiUrl);
+                receiver = new LiveReceiver({
+                    api,
+                    logger: session.logger,
+                    module: workers.module,
+                    quota: workers.quota,
+                    signal: shutdown.signal,
+                    url,
+                    token: token.token,
+                    apiUrl: cfg.apiUrl,
+                    onPull,
+                    onError,
+                    onState: liveStateReporter(ctx, session),
+                    onLiveUrl: (next) => saveMeta(session, LIVE_META.url, next, ctx.now())
+                });
+            }
+            else {
+                receiver = new Poller({
+                    api,
+                    logger: session.logger,
+                    intervalMs: cfg.pollIntervalMs,
+                    module: workers.module,
+                    quota: workers.quota,
+                    signal: shutdown.signal,
+                    onPull,
+                    onError
+                });
+            }
+            const closed = await workers.recover();
+            if (closed > 0) {
+                out.info(`closed ${closed} task(s) the previous run left unfinished — see '${BIN} tasks'`);
+            }
+            await workers.serve();
+            out.info(banner(ctx, session.config, workers));
+            updates.arm();
+            session.logger.info('runner started', {
+                pid: process.pid,
+                detached: detachedChild,
+                mode: cfg.receiveMode,
+                interval_ms: cfg.receiveMode === 'live' ? null : cfg.pollIntervalMs,
+                port: workers.serverPort(),
+                public: isPublic
+            });
+            polling = receiver;
+            const stopped = await receiver.run();
+            polling = null;
+            if (stopped && !(stopped instanceof StopError)) {
+                recordEnd(session, stopped.ended, stopped.deletedWorkers, ctx.now());
+                throw new CliError(workers.endMessage(stopped));
+            }
+            if (stopped) {
+                recordStop(session, stopped, ctx.now());
+                throw new StopError(stopped.reason, `${stopped.message}\n${stopHint(stopped.reason)}`, stopped.resetAt);
+            }
+            if (projectGone)
+                throw projectGoneError(root);
+            session.logger.info('runner stopped', { pid: process.pid });
+            out.info('Stopped.');
+            return ctx.signal.aborted ? ExitCode.Interrupted : ExitCode.Ok;
+        }
+        finally {
+            clearInterval(stopWatch);
+            ctx.signal.removeEventListener('abort', onAbort);
+            await workers?.close();
+            lock.release();
+        }
+    }
+    finally {
+        session.close();
+    }
+}
+function liveUrl(url, apiUrl) {
+    if (url === null) {
+        throw new ConfigError(`this server (${apiUrl}) does not support live mode. Run '${BIN} start --mode poll' to fetch tasks at an interval instead.`);
+    }
+    if (!isTrustedLiveUrl(url, apiUrl)) {
+        throw new ConfigError(`the server gave a live address that is not on ${apiUrl} — not connecting, so your host token is not sent elsewhere. ` +
+            `Run '${BIN} start --mode poll' instead, and check the API URL.`);
+    }
+    return url;
+}
+function resetLiveState(session) {
+    try {
+        session.db.deleteMeta(LIVE_META.state);
+    }
+    catch (e) {
+        session.logger.warn('could not clear the live state', { message: e.message });
+    }
+}
+function rememberLiveUrl(session, url, apiUrl, now) {
+    if (isTrustedLiveUrl(url, apiUrl))
+        saveMeta(session, LIVE_META.url, url, now);
+}
+function saveMeta(session, key, value, now) {
+    try {
+        session.db.setMeta(key, value, now);
+    }
+    catch (e) {
+        session.logger.warn('could not record live info', { key, message: e.message });
+    }
+}
+function liveStateReporter(ctx, session) {
+    let warned = false;
+    return (state) => {
+        try {
+            session.db.setLiveState(state, ctx.now());
+        }
+        catch (e) {
+            session.logger.warn('could not record the live state', { message: e.message });
+        }
+        if (state.connected && warned) {
+            warned = false;
+            ctx.out.info(`${ctx.out.err.dim(formatLocal(ctx.now()))}  live connection open`);
+        }
+        else if (!state.connected && !state.everConnected && state.lastError && !warned) {
+            warned = true;
+            ctx.out.warn(`could not open the live connection (${state.lastError}) — retrying in the background; no tasks are fetched until it connects.
+` +
+                `On a network that blocks WebSockets (a company proxy or firewall), run '${BIN} doctor' or start with '--mode poll'.`);
+        }
+    };
+}
+const PROJECT_GONE_MISSES = 2;
+function projectGoneError(root) {
+    return new CliError(`the project folder ${root} is gone (moved or deleted). Stopped. ` +
+        `If you moved it, run '${BIN} start' inside the new folder.`);
+}
+function pullReporter(ctx, mode, remember) {
+    let warnedLow = false;
+    return (res) => {
+        remember(res.quota);
+        const { remaining, limit } = res.quota;
+        const left = `${formatCount(remaining)} of ${formatCount(limit)} calls left`;
+        if (res.tasks.length > 0) {
+            ctx.out.info(`${ctx.out.err.dim(formatLocal(ctx.now()))}  received ${res.tasks.length} task(s) · ${left}`);
+        }
+        if (!warnedLow && limit > 0 && remaining < limit * 0.1) {
+            warnedLow = true;
+            ctx.out.warn(`only ${left}. ${mode === 'live'
+                ? 'Each fetch and each reconnect uses one call'
+                : 'Every poll uses one call'}; all calls stop when the quota runs out.`);
+        }
+    };
+}
+function banner(ctx, config, workers) {
+    const lines = [
+        `${ctx.out.err.green('started')}  ${workers.bannerSubject()} · pid ${process.pid}`,
+        modeLine(config.values),
+        ...workers.bannerLines()
+    ];
+    lines.push(ctx.env[ENV.detached] === '1' ? `stop with '${BIN} stop'` : `Ctrl+C or '${BIN} stop' to stop`);
+    return lines.join('\n');
+}
+async function startDetached(ctx) {
+    const { out } = ctx;
+    requireToken(ctx);
+    const config = ctx.loadConfig();
+    const root = requireProject(config);
+    const current = readRunner(ctx.dirs.data);
+    if (current.state === 'running') {
+        throw new CliError(`3minapi is already running (pid ${current.info.pid}). Only one can run per host.\n` +
+            `Stop it with '${BIN} stop' first.`);
+    }
+    const outFile = outFilePath(ctx);
+    const startedAt = Date.now();
+    const child = spawnDetached({
+        args: ['start', ...forwardArgs(ctx)],
+        cwd: root,
+        env: ctx.env,
+        outFile
+    });
+    let exited = null;
+    child.once('exit', (code) => (exited = code ?? 1));
+    let info = null;
+    while (Date.now() - startedAt < DETACH_READY_MS && exited === null) {
+        const state = readRunner(ctx.dirs.data);
+        if (state.state === 'running' && state.info.pid === child.pid) {
+            info = state.info;
+            break;
+        }
+        await sleep(100);
+    }
+    child.unref();
+    if (!info) {
+        if (exited === null) {
+            try {
+                child.kill();
+            }
+            catch {
+            }
+        }
+        throw new CliError(`the background runner did not start${exited !== null ? ` (exit code ${exited})` : ''}.\n` +
+            outputTail(outFile));
+    }
+    const { pollIntervalMs, concurrency, receiveMode } = config.values;
+    const poll = receiveMode === 'poll';
+    out.result({
+        running: true,
+        pid: info.pid,
+        outFile,
+        mode: receiveMode,
+        intervalMs: poll ? pollIntervalMs : null,
+        monthlyCalls: poll ? Math.round(MONTH_MS / pollIntervalMs) : null,
+        concurrency,
+        maxTasksPerMinute: poll ? maxTasksPerMinute(concurrency, pollIntervalMs) : null
+    }, [
+        `${out.out.green('started in the background')}  pid ${info.pid}`,
+        modeLine(config.values),
+        `output: ${outFile}`,
+        `stop with '${BIN} stop' · check with '${BIN} status'`
+    ].join('\n'));
+    return ExitCode.Ok;
+}
+function forwardArgs(ctx) {
+    const { values } = ctx;
+    const args = [];
+    if (values.serve)
+        args.push('--serve');
+    if (values.public)
+        args.push('--public');
+    if (typeof values.port === 'string')
+        args.push('--port', values.port);
+    if (typeof values.mode === 'string')
+        args.push('--mode', values.mode);
+    if (typeof values['api-url'] === 'string')
+        args.push('--api-url', values['api-url']);
+    if (typeof values.config === 'string')
+        args.push('--config', path.resolve(ctx.cwd, values.config));
+    return args;
+}
+function outFilePath(ctx) {
+    return path.join(ctx.dirs.logs, APP_LOG_DIR, RUNNER_OUT_FILE);
+}
+function monthlyCalls(intervalMs) {
+    return formatCount(Math.round(MONTH_MS / intervalMs));
+}
+function modeLine(cfg) {
+    if (cfg.receiveMode === 'poll')
+        return pollingLine(cfg.pollIntervalMs, cfg.concurrency);
+    return (`live — fetches when 3Min API signals, up to ${cfg.concurrency} at a time. ` +
+        'Idle ≈ 0 calls · 1 call per connect or reconnect · about 3 calls per task');
+}
+function pollingLine(intervalMs, concurrency) {
+    return (`polling every ${formatInterval(intervalMs)}, ${formatThroughput(concurrency, intervalMs)} — ` +
+        `about ${monthlyCalls(intervalMs)} calls per month even when idle`);
+}

package/dist/commands/stop.js

@@ -0,0 +1,68 @@
+import { existsSync, rmSync } from 'node:fs';
+import { CliError, ExitCode, STOP_WAIT_MS } from "../core/domain/index.js";
+import { isAlive, lockPath, readRunner, readRunnerSettled, heartbeatStopped, requestStop } from "../core/host/runner-lock.js";
+import { sleep } from "../core/time.js";
+export const stop = {
+    name: 'stop',
+    summary: "Stop this host's running 'start' (background or another terminal)",
+    usage: '',
+    description: 'Asks the running start to finish — the whole host process, whatever it runs: running\n' +
+        'tasks are cancelled and reported as failed.\n' +
+        `If it has not exited after ${STOP_WAIT_MS / 1000}s it is killed.`,
+    options: {},
+    args: { min: 0, max: 0 },
+    run(ctx) {
+        return stopLocked(ctx, {
+            read: () => readRunner(ctx.dirs.data),
+            readSettled: () => readRunnerSettled(ctx.dirs.data),
+            requestStop: (info) => requestStop(ctx.dirs.data, info),
+            lockFile: lockPath(ctx.dirs.data)
+        });
+    }
+};
+export async function stopLocked(ctx, target) {
+    const { out } = ctx;
+    const current = await target.readSettled();
+    if (current.state !== 'running') {
+        out.result({ stopped: false, running: false }, 'Not running.');
+        return ExitCode.Ok;
+    }
+    const { info } = current;
+    target.requestStop(info);
+    out.info(`stopping pid ${info.pid}...`);
+    const deadline = Date.now() + STOP_WAIT_MS;
+    while (Date.now() < deadline && isAlive(info.pid) && existsSync(target.lockFile)) {
+        await sleep(200);
+    }
+    let forced = false;
+    if (isAlive(info.pid) &&
+        target.read().state === 'running' &&
+        heartbeatStopped(target.lockFile, info)) {
+        rmSync(target.lockFile, { force: true });
+        out.result({ stopped: true, pid: info.pid, forced: false, killed: false }, `pid ${info.pid} has not updated this lock for a while — it may be another program that reused the pid. ` +
+            'It was not killed; the stale lock was removed.');
+        return ExitCode.Ok;
+    }
+    if (isAlive(info.pid) && target.read().state === 'running') {
+        forced = true;
+        if (!(await forceKill(info.pid))) {
+            throw new CliError(`pid ${info.pid} did not stop and could not be killed. Stop it from the OS (Activity Monitor / Task Manager / kill -9).`);
+        }
+        rmSync(target.lockFile, { force: true });
+    }
+    out.result({ stopped: true, pid: info.pid, forced }, forced ? `Killed pid ${info.pid} (it did not stop in time).` : `Stopped pid ${info.pid}.`);
+    return ExitCode.Ok;
+}
+export async function forceKill(pid) {
+    try {
+        process.kill(pid, process.platform === 'win32' ? undefined : 'SIGKILL');
+    }
+    catch (err) {
+        if (err.code === 'ESRCH')
+            return true;
+        return false;
+    }
+    for (let i = 0; i < 20 && isAlive(pid); i++)
+        await sleep(100);
+    return !isAlive(pid);
+}

package/dist/commands/tasks.js

@@ -0,0 +1,93 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { ControlDb } from "../core/control-db.js";
+import { BIN, CONTROL_DB_FILE, CliError, ExitCode, TASKS_PRUNE_MIN_AGE_MS, UsageError } from "../core/domain/index.js";
+import { assertWorkerName } from "../core/names.js";
+import { confirm } from "../core/prompt.js";
+import { formatBytes, formatCount } from "../core/text.js";
+import { formatLocal, parseDateArg } from "../core/time.js";
+export const tasksPrune = {
+    name: 'tasks prune',
+    summary: 'Delete the run history of tasks that finished before a date',
+    usage: '--before <date> [--worker <name>] [--yes]',
+    description: "Deletes this host's task records — when each task ran, retries, cancellations and why it\n" +
+        'failed. Nothing is deleted automatically otherwise. Tasks still waiting or running, and tasks\n' +
+        'that finished in the last 24 hours, are kept: those records stop a task from running twice\n' +
+        'when it is delivered again. Saved results in data.db are not touched (worker results prune).\n' +
+        'Shows how many first and asks to confirm. The file does not shrink; new records reuse the space.',
+    options: {
+        before: {
+            type: 'string',
+            valueName: 'date',
+            description: 'Delete tasks that finished before this time — YYYY-MM-DD (local midnight) or ISO 8601'
+        },
+        worker: { type: 'string', valueName: 'name', description: 'Only this worker' },
+        yes: { type: 'boolean', description: 'Delete without asking for confirmation' }
+    },
+    args: { min: 0, max: 0 },
+    async run(ctx) {
+        const { out, values } = ctx;
+        if (typeof values.before !== 'string') {
+            throw new UsageError(`--before is required.\nusage: ${BIN} tasks prune --before <date>`);
+        }
+        const before = parseDateArg(values.before);
+        if (before === null) {
+            throw new UsageError(`--before "${values.before}" is not a date. Use YYYY-MM-DD (local midnight) or ISO 8601 like 2026-10-01T09:00.`);
+        }
+        const filter = { before };
+        if (typeof values.worker === 'string') {
+            assertWorkerName(values.worker);
+            filter.worker = values.worker;
+        }
+        if (!existsSync(path.join(ctx.dirs.data, CONTROL_DB_FILE))) {
+            out.result({ deleted: 0, bytes: 0, kept: 0 }, 'Nothing to delete.');
+            return ExitCode.Ok;
+        }
+        const db = ControlDb.open(ctx.dirs.data);
+        try {
+            const now = ctx.now();
+            const target = db.pruneUsage(filter, now);
+            const keptNote = target.recent > 0
+                ? `${formatCount(target.recent)} task(s) that finished in the last 24 hours are kept.`
+                : null;
+            if (target.count === 0) {
+                out.result({ deleted: 0, bytes: 0, kept: target.recent }, ['Nothing to delete.', ...(keptNote ? [keptNote] : [])].join('\n'));
+                return ExitCode.Ok;
+            }
+            const what = `the run history of ${formatCount(target.count)} finished task(s) (about ${formatBytes(target.bytes)})${filter.worker ? ` of ${filter.worker}` : ''} from before ${formatLocal(Math.min(before, now - TASKS_PRUNE_MIN_AGE_MS))}`;
+            if (!values.yes) {
+                if (out.json || !ctx.stdin.isTTY) {
+                    throw new UsageError(`this deletes ${what} and cannot be undone.${keptNote ? ` ${keptNote}` : ''} ` +
+                        'Nothing was deleted. Once the user has agreed, run it again with --yes.');
+                }
+                if (keptNote)
+                    out.info(keptNote);
+                if (!(await confirm(ctx.stdin, out, `Delete ${what}? This cannot be undone.`))) {
+                    throw new CliError('cancelled — nothing was deleted.');
+                }
+            }
+            const deleted = db.prune(filter, now);
+            out.result({ deleted, bytes: target.bytes, kept: target.recent }, [
+                `Deleted the run history of ${formatCount(deleted)} task(s). ${CONTROL_DB_FILE} keeps its size; new records reuse the space.`,
+                ...(keptNote && values.yes ? [keptNote] : [])
+            ].join('\n'));
+            return ExitCode.Ok;
+        }
+        finally {
+            db.close();
+        }
+    }
+};
+export const tasks = {
+    name: 'tasks',
+    summary: "Manage this host's task run history",
+    usage: '<command>',
+    description: "This host keeps a record of every task it ran (control.db, '3minapi paths'): when it ran,\n" +
+        "retries, cancellations and why it failed. Nothing deletes it automatically — use 'tasks prune'.",
+    options: {},
+    args: { min: 0, max: 0 },
+    subcommands: [tasksPrune],
+    async run() {
+        return ExitCode.Usage;
+    }
+};