akm-cli 0.8.1 → 0.9.0-beta.0

package/dist/commands/sources/stash-cli.js

@@ -0,0 +1,219 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Stash-lifecycle command cluster — the create/index/ingest/inspect verbs for
+ * the working stash and its index database: `akm init` (create the stash +
+ * persist stashDir), `akm index` (build/refresh the search index), `akm import`
+ * (ingest a knowledge doc/URL), `akm db` (+ nested `backups` — inspect the
+ * SQLite data dir), and `akm info` (system capabilities + index stats).
+ * Extracted verbatim from src/cli.ts (WS6) so the God Module shrinks; the
+ * `main.subCommands.{init,index,import,db,info}` keys and every subcommand's
+ * args/output shape stay byte-identical.
+ *
+ * These share no private helper with any command still inline in cli.ts — every
+ * dependency is already exported from a shared module (core/paths, core/warn,
+ * core/errors, core/events, output/context, cli/shared, cli/parse-args, plus the
+ * per-command implementations in ./init, ./indexer, ./info, ./db-cli, ./knowledge,
+ * ./core/asset-create, ./core/common), so the cluster moves with zero hoisting.
+ *
+ * The leaf handlers whose body is a plain `runWithJsonErrors(...) + output(...)`
+ * (`init`, `import`, `info`, `db`, `db backups`) are migrated onto
+ * `defineJsonCommand`, which emits the same JSON envelope (stdout/stderr/
+ * exit-code) as the inline form. `index` keeps a plain `defineCommand` wrapping
+ * `runWithJsonErrors` because its body owns a spinner, an AbortController, and
+ * SIGINT/SIGTERM handlers in a try/finally — left byte-for-byte untouched.
+ */
+import path from "node:path";
+import * as p from "@clack/prompts";
+import { defineCommand } from "citty";
+import { hasSubcommand } from "../../cli/parse-args.js";
+import { defineJsonCommand, output, runWithJsonErrors } from "../../cli/shared.js";
+import { assertFlatAssetName } from "../../core/asset/asset-create.js";
+import { isHttpUrl } from "../../core/common.js";
+import { UsageError } from "../../core/errors.js";
+import { appendEvent } from "../../core/events.js";
+import { getCacheDir } from "../../core/paths.js";
+import { clearLogFile, info, isVerbose, setLogFile } from "../../core/warn.js";
+import { akmIndex } from "../../indexer/indexer.js";
+import { getHyphenatedBoolean, getOutputMode, parseFlagValue } from "../../output/context.js";
+import { akmDbBackups } from "../db-cli.js";
+import { readKnowledgeInput, writeMarkdownAsset } from "../read/knowledge.js";
+import { assembleInfo } from "./info.js";
+import { akmInit } from "./init.js";
+export const initCommand = defineJsonCommand({
+    meta: {
+        name: "init",
+        description: "Initialize akm's working stash directory and persist stashDir in config",
+    },
+    args: {
+        dir: { type: "string", description: "Custom stash directory path (default: ~/akm)" },
+    },
+    async run({ args }) {
+        // Accept both historical spellings for backwards compatibility with
+        // older docs/scripts that used `--stashDir`.
+        const legacyDir = parseFlagValue(process.argv, "--stashDir") ?? parseFlagValue(process.argv, "--stash-dir");
+        const result = await akmInit({ dir: args.dir ?? legacyDir });
+        output("init", result);
+    },
+});
+export const indexCommand = defineCommand({
+    meta: { name: "index", description: "Build search index (incremental by default; --full forces full reindex)" },
+    args: {
+        full: { type: "boolean", description: "Force full reindex", default: false },
+        clean: {
+            type: "boolean",
+            description: "After indexing, remove any entries whose source file no longer exists on disk.",
+            default: false,
+        },
+        "dry-run": {
+            type: "boolean",
+            description: "When combined with --clean, report stale entries without deleting them.",
+            default: false,
+        },
+    },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            if (getHyphenatedBoolean(args, "enrich") || parseFlagValue(process.argv, "--enrich") !== undefined) {
+                throw new UsageError("`akm index --enrich` has been removed. Plain `akm index` now performs metadata enrichment by default.");
+            }
+            if (getHyphenatedBoolean(args, "re-enrich") || parseFlagValue(process.argv, "--re-enrich") !== undefined) {
+                throw new UsageError("`akm index --re-enrich` has been removed. Re-enrichment of index-time LLM passes is not exposed in this slice.");
+            }
+            const outputMode = getOutputMode();
+            const controller = new AbortController();
+            const abort = () => controller.abort(new Error("index interrupted"));
+            process.once("SIGINT", abort);
+            process.once("SIGTERM", abort);
+            const indexLogFile = path.join(getCacheDir(), "logs", "index", `${new Date().toISOString().replace(/[:.]/g, "-")}.log`);
+            setLogFile(indexLogFile);
+            const verbose = isVerbose();
+            const spin = !verbose && outputMode.format === "text" ? p.spinner() : null;
+            if (spin) {
+                spin.start(`Building search index${args.full ? " (full rebuild)" : ""}...`);
+            }
+            let latestMessage = "";
+            try {
+                const result = await akmIndex({
+                    full: args.full,
+                    clean: args.clean,
+                    dryRun: args["dry-run"],
+                    onProgress: ({ phase, message, processed, total }) => {
+                        latestMessage = message;
+                        const progressPrefix = processed !== undefined && total !== undefined ? `[${processed}/${total}] ` : "";
+                        if (verbose) {
+                            info(`[index:${phase}] ${progressPrefix}${message}`);
+                        }
+                        else if (spin) {
+                            spin.stop(`${progressPrefix}${message}`);
+                            spin.start(`${progressPrefix}${message}`);
+                        }
+                    },
+                    signal: controller.signal,
+                });
+                if (spin) {
+                    spin.stop(`Indexed ${result.totalEntries} assets.`);
+                }
+                output("index", result);
+            }
+            catch (error) {
+                if (spin) {
+                    spin.stop(latestMessage ? `Indexing failed after: ${latestMessage}` : "Indexing failed.");
+                }
+                throw error;
+            }
+            finally {
+                clearLogFile();
+                process.off("SIGINT", abort);
+                process.off("SIGTERM", abort);
+            }
+        });
+    },
+});
+export const infoCommand = defineJsonCommand({
+    meta: { name: "info", description: "Show system capabilities, configuration, and index stats" },
+    run() {
+        const result = assembleInfo();
+        output("info", result);
+    },
+});
+// MVP DB administration. Currently only `akm db backups`; restore is manual —
+// stop akm and run `scripts/migrations/restore-data-dir.sh <backup>`.
+// Single source of truth: the routing set is derived from the subCommands keys
+// (M10) so adding a subcommand can never silently desync from `hasSubcommand`.
+const dbSubCommands = {
+    backups: defineJsonCommand({
+        meta: {
+            name: "backups",
+            description: "List pre-upgrade snapshots of the data directory (newest first). Backups are created automatically before destructive DB version upgrades unless AKM_DB_BACKUP=0.",
+        },
+        run() {
+            output("db-backups", akmDbBackups());
+        },
+    }),
+};
+const DB_SUBCOMMAND_SET = new Set(Object.keys(dbSubCommands));
+export const dbCommand = defineJsonCommand({
+    meta: {
+        name: "db",
+        description: "Inspect the AKM SQLite data directory. Currently exposes `backups`; to restore from a snapshot, stop akm and run scripts/migrations/restore-data-dir.sh against the chosen backup.",
+    },
+    subCommands: dbSubCommands,
+    run({ args }) {
+        if (hasSubcommand(args, DB_SUBCOMMAND_SET))
+            return;
+        // Default action: list backups.
+        output("db-backups", akmDbBackups());
+    },
+});
+export const importKnowledgeCommand = defineJsonCommand({
+    meta: {
+        name: "import",
+        description: "Import a knowledge document or URL into the default stash",
+    },
+    args: {
+        source: {
+            type: "positional",
+            description: 'Source file path, URL, or "-" to read from stdin',
+            required: true,
+        },
+        name: {
+            type: "string",
+            description: "Knowledge name (flat, no '/'; defaults to the source filename or content slug). Use --path for a subdirectory.",
+        },
+        path: {
+            type: "string",
+            description: "Relative subdirectory under knowledge/ to place the document in (e.g. 'projects/example'). The filename still comes from --name or the source slug.",
+        },
+        force: {
+            type: "boolean",
+            description: "Overwrite an existing knowledge document with the same name",
+            default: false,
+        },
+        target: {
+            type: "string",
+            description: "Override the write destination. Accepts a source name from your config; falls back to defaultWriteTarget then the working stash.",
+        },
+    },
+    async run({ args }) {
+        // `--name` is a flat name; subdirectory placement is `--path`'s job.
+        assertFlatAssetName(args.name);
+        const { content, preferredName } = await readKnowledgeInput(args.source);
+        const result = await writeMarkdownAsset({
+            type: "knowledge",
+            content,
+            name: args.name ?? (isHttpUrl(args.source) ? preferredName : undefined),
+            fallbackPrefix: "knowledge",
+            preferredName,
+            force: args.force,
+            target: args.target,
+            path: args.path,
+        });
+        appendEvent({
+            eventType: "import",
+            ref: result.ref,
+            metadata: { source: args.source, path: result.path, force: args.force === true },
+        });
+        output("import", { ok: true, source: args.source, ...result });
+    },
+});

package/dist/commands/sources/stash-skeleton.js

@@ -0,0 +1,79 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import fs from "node:fs";
+import path from "node:path";
+import { getDirname } from "../../runtime.js";
+const SKELETON_DIR = path.join(getDirname(import.meta.url), "../../assets/stash-skeleton");
+/**
+ * Copy the default stash skeleton into a newly created stash directory.
+ *
+ * Each file in src/assets/stash-skeleton/ is written to the stash root only
+ * if the destination does not already exist — existing files are never
+ * overwritten. Non-fatal: if the skeleton directory is missing or a copy
+ * fails the caller continues normally.
+ */
+export function copyStashSkeleton(stashDir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(SKELETON_DIR);
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const src = path.join(SKELETON_DIR, entry);
+        const dest = path.join(stashDir, entry);
+        if (fs.existsSync(dest))
+            continue;
+        try {
+            fs.copyFileSync(src, dest);
+        }
+        catch {
+            // Non-fatal — stash is usable without skeleton files
+        }
+    }
+}
+/**
+ * Scaffold the optional `.meta/index.md` orientation doc for the stash
+ * `.meta/` convention. Written only when absent — an existing `.meta/index.md`
+ * is never overwritten. Non-fatal: a stash works fine without it.
+ *
+ * `.meta/` is a dot-directory, so the indexer skips it; the template is
+ * written here (rather than shipped under `src/assets/`) because the
+ * build-time asset glob excludes dotfiles.
+ */
+export function scaffoldStashMeta(stashDir) {
+    const metaDir = path.join(stashDir, ".meta");
+    const indexPath = path.join(metaDir, "index.md");
+    if (fs.existsSync(indexPath))
+        return;
+    try {
+        fs.mkdirSync(metaDir, { recursive: true });
+        fs.writeFileSync(indexPath, STASH_META_INDEX_TEMPLATE);
+    }
+    catch {
+        // Non-fatal — stash is usable without the .meta orientation doc
+    }
+}
+const STASH_META_INDEX_TEMPLATE = `---
+# Optional, human-authored orientation for this stash. Not indexed; surfaced
+# on demand via \`akm show meta\` (this file) or \`akm show <stash>//meta\`.
+# Every field is optional — delete what you don't need.
+purpose:
+  - Describe what this stash is for.
+entry_points:
+  # Refs an agent should start from, e.g. skill:code-review, workflow:ship-release
+conventions:
+  # House rules an agent should follow when working in this stash.
+maintainer:
+---
+# About this stash
+
+Replace this with a short orientation for agents and humans: what lives here,
+where to start, and the conventions to follow.
+
+Extend the \`.meta/\` directory with more docs as needed — \`.meta/about.md\`,
+\`.meta/conventions.md\`, \`.meta/license\` — and read any of them with
+\`akm show meta:<name>\` (or \`akm show <stash>//meta:<name>\`).
+`;

package/dist/commands/tasks/default-tasks.js

@@ -0,0 +1,173 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Default scheduled-task set for the improve pipeline (issue #552).
+ *
+ * Ships a well-tuned multi-cadence task set so a typical single-developer
+ * install is correct with zero manual config. Registration is **idempotent**:
+ * running `akm setup` / `akm tasks init` twice yields the same task set with no
+ * duplicates. Each default task is a shell-command task (`akm improve --profile
+ * <name>`), so the profile is overridable in `config.json` without editing the
+ * task definition.
+ *
+ * The OS-scheduler-touching primitives (`add` / `setEnabled` / `list`) are
+ * injected via {@link RegisterDefaultTasksDeps} so tests can supply fakes and
+ * never mutate the host scheduler or a real stash — mirroring the
+ * dependency-injection pattern used by `stepScheduledTasks` in setup.ts.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import { akmTasksAdd, akmTasksList } from "./tasks.js";
+/**
+ * The canonical default improve task set. `update-stashes` is deliberately NOT
+ * listed here — it ships as an embedded core template and is left unchanged.
+ */
+export const DEFAULT_IMPROVE_TASKS = [
+    {
+        id: "akm-improve-frequent",
+        profile: "frequent",
+        command: "akm improve --profile frequent --auto-accept safe",
+        schedule: "0 * * * *",
+        description: "Frequent extract + inference pass (every 60 min)",
+        enableMode: "always",
+    },
+    {
+        id: "akm-improve-consolidate",
+        profile: "consolidate",
+        command: "akm improve --profile consolidate --auto-accept safe",
+        schedule: "0 */4 * * *",
+        description: "Consolidation-only pass (every 4h)",
+        enableMode: "always",
+    },
+    {
+        id: "akm-improve-nightly",
+        profile: "thorough",
+        command: "akm improve --profile thorough --auto-accept safe",
+        schedule: "0 2 * * *",
+        description: "Full nightly quality sweep (daily 2am)",
+        enableMode: "server",
+    },
+    {
+        id: "akm-improve-catchup",
+        profile: "catchup",
+        command: "akm improve --profile catchup --auto-accept safe",
+        schedule: null,
+        description: "Manual recovery — consolidation + triage drain (run on demand)",
+        enableMode: "manual",
+    },
+    {
+        id: "akm-graph-refresh-weekly",
+        profile: "graph-refresh",
+        command: "akm improve --profile graph-refresh --auto-accept safe",
+        schedule: "0 3 * * 0",
+        description: "Full-corpus graph rebuild (weekly Sunday 3am)",
+        enableMode: "always",
+    },
+];
+/**
+ * A schedule for the manual catch-up task. The scheduler requires a valid
+ * cron expression even when the task is registered disabled, so we give the
+ * unscheduled task a nominal far-future-ish cadence and leave it disabled —
+ * the documented entry point is `akm tasks run akm-improve-catchup`.
+ */
+const MANUAL_TASK_NOMINAL_SCHEDULE = "0 4 1 1 *"; // 04:00 on Jan 1 — never effectively fires
+const DEFAULT_DEPS = {
+    list: akmTasksList,
+    add: akmTasksAdd,
+};
+/**
+ * Decide whether `akm setup` is running in a CI environment, where it must
+ * register NO scheduled tasks. Mirrors the common `CI=true` convention used by
+ * GitHub Actions, GitLab CI, CircleCI, etc.
+ */
+export function isCiEnvironment(env = process.env) {
+    const ci = env.CI;
+    if (ci === undefined || ci === null)
+        return false;
+    const v = String(ci).trim().toLowerCase();
+    return v !== "" && v !== "0" && v !== "false";
+}
+/**
+ * Platform-appropriate default for the "Is this a server install?" prompt:
+ *  - Linux without a battery → `true` (server).
+ *  - macOS / any host with a battery (laptop) → `false`.
+ * Used as the default when setup is non-interactive (no TTY / --yes / CI).
+ */
+export function detectServerDefault() {
+    if (os.platform() !== "linux")
+        return false;
+    // A laptop exposes a battery under /sys/class/power_supply/BAT*. Absence of
+    // any battery is our heuristic for "server / desktop".
+    try {
+        const entries = fs.readdirSync("/sys/class/power_supply");
+        const hasBattery = entries.some((e) => /^BAT/i.test(e));
+        return !hasBattery;
+    }
+    catch {
+        // If we cannot read power-supply info, prefer the safe server default on
+        // Linux (the nightly sweep is low-impact and re-runnable).
+        return true;
+    }
+}
+/**
+ * Idempotently register the default improve task set.
+ *
+ * - Skips entirely when `CI` is set (returns `{ skipped: true, reason: "ci" }`).
+ * - Creates any missing task; never duplicates an existing one.
+ * - Re-aligns the enabled-state of existing tasks to the desired default only
+ *   when the install is fresh-creating them (existing tasks the user may have
+ *   toggled are left untouched — we only toggle tasks we just created, plus we
+ *   never re-disable a user-enabled task).
+ */
+export async function registerDefaultTasks(options = {}) {
+    if (isCiEnvironment()) {
+        return { skipped: true, reason: "ci", created: [], existing: [], toggled: [] };
+    }
+    const deps = options.deps ?? DEFAULT_DEPS;
+    const serverInstall = options.serverInstall ?? detectServerDefault();
+    let installed = [];
+    try {
+        installed = (await deps.list()).tasks;
+    }
+    catch {
+        installed = [];
+    }
+    const existingIds = new Set(installed.map((t) => t.id));
+    const created = [];
+    const existing = [];
+    const toggled = [];
+    for (const spec of DEFAULT_IMPROVE_TASKS) {
+        const desiredEnabled = resolveDesiredEnabled(spec, serverInstall);
+        if (existingIds.has(spec.id)) {
+            // Idempotent: never re-create. Leave the existing task in place.
+            existing.push(spec.id);
+            continue;
+        }
+        const schedule = spec.schedule ?? MANUAL_TASK_NOMINAL_SCHEDULE;
+        const addInput = {
+            id: spec.id,
+            schedule,
+            command: spec.command,
+            description: spec.description,
+            // Manual + non-server-enabled tasks are written disabled so the
+            // scheduler entry is inert until the user opts in / runs it manually.
+            disabled: !desiredEnabled,
+        };
+        await deps.add(addInput);
+        created.push(spec.id);
+        if (desiredEnabled)
+            toggled.push(spec.id);
+    }
+    return { skipped: false, created, existing, toggled };
+}
+function resolveDesiredEnabled(spec, serverInstall) {
+    switch (spec.enableMode) {
+        case "always":
+            return true;
+        case "server":
+            return serverInstall;
+        case "manual":
+            return false;
+    }
+}

package/dist/commands/tasks/tasks-cli.js

@@ -0,0 +1,210 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * `akm tasks` command family. Extracted verbatim from src/cli.ts (WS6) so the
+ * God Module shrinks; the `main.subCommands.tasks` key and every subcommand's
+ * args/output shape are byte-identical. Handlers whose body is a plain
+ * `runWithJsonErrors(...) + output(...)` are migrated to `defineJsonCommand`,
+ * which emits the same JSON envelope (stdout/stderr/exit-code) as the inline
+ * form. `tasks run` keeps a plain `defineCommand` because it forwards the
+ * task's own exit code via `process.exit`. The private helper
+ * `makeTasksToggleCommand` and the `TASKS_SUBCOMMAND_SET` routing constant move
+ * with the family.
+ */
+import { defineCommand } from "citty";
+import { hasSubcommand, parsePositiveIntFlag } from "../../cli/parse-args.js";
+import { defineJsonCommand, output, runWithJsonErrors } from "../../cli/shared.js";
+import { getHyphenatedArg } from "../../output/context.js";
+import { detectServerDefault, registerDefaultTasks } from "./default-tasks.js";
+import { akmTasksAdd, akmTasksDoctor, akmTasksHistory, akmTasksList, akmTasksRemove, akmTasksRun, akmTasksSetEnabled, akmTasksShow, akmTasksSync, parseTaskRef, } from "./tasks.js";
+const tasksAddCommand = defineJsonCommand({
+    meta: { name: "add", description: "Register a new scheduled task and install it in the OS scheduler" },
+    args: {
+        id: { type: "positional", description: "Task id (used as filename and scheduler entry)", required: true },
+        schedule: { type: "string", description: 'Cron-style schedule, e.g. "0 9 * * *" or "@daily"', required: true },
+        workflow: { type: "string", description: "Workflow ref to invoke (e.g. workflow:my-flow)" },
+        prompt: {
+            type: "string",
+            description: "Prompt for the configured agent harness — inline text, an asset ref like agent:foo, or ./path.md",
+        },
+        command: {
+            type: "string",
+            description: 'Shell command to run on the schedule (no AI agent), e.g. "akm improve --auto-accept safe". Split on whitespace; quote the whole flag value.',
+        },
+        profile: { type: "string", description: "Agent profile to use for prompt targets (default: defaults.agent)" },
+        params: { type: "string", description: "Workflow params as a JSON object" },
+        name: { type: "string", description: "Human-readable name for the task" },
+        "when-to-use": { type: "string", description: "Guidance on when this task runs or should be used" },
+        description: { type: "string", description: "Human-readable description" },
+        tags: { type: "string", description: "Comma-separated tags" },
+        disabled: { type: "boolean", description: "Register but leave disabled in the OS scheduler", default: false },
+        force: { type: "boolean", description: "Overwrite an existing task with the same id", default: false },
+    },
+    async run({ args }) {
+        const result = await akmTasksAdd({
+            id: args.id,
+            schedule: args.schedule,
+            workflow: args.workflow,
+            prompt: args.prompt,
+            command: args.command,
+            profile: args.profile,
+            params: args.params,
+            name: args.name,
+            when_to_use: getHyphenatedArg(args, "when-to-use"),
+            description: args.description,
+            tags: args.tags
+                ? args.tags
+                    .split(/[\s,]+/)
+                    .map((s) => s.trim())
+                    .filter(Boolean)
+                : undefined,
+            disabled: args.disabled === true,
+            force: args.force === true,
+        });
+        output("tasks-add", result);
+    },
+});
+const tasksInitCommand = defineJsonCommand({
+    meta: {
+        name: "init",
+        description: "Idempotently register the default improve task set (skips when CI=true)",
+    },
+    args: {
+        server: {
+            type: "boolean",
+            description: "Treat this as a server install (enables the nightly sweep). Defaults to platform detection.",
+        },
+        laptop: {
+            type: "boolean",
+            description: "Treat this as a laptop install (leaves the nightly sweep disabled).",
+        },
+    },
+    async run({ args }) {
+        const serverInstall = args.server === true ? true : args.laptop === true ? false : detectServerDefault();
+        const result = await registerDefaultTasks({ serverInstall });
+        output("tasks-init", result);
+    },
+});
+const tasksListCommand = defineJsonCommand({
+    meta: { name: "list", description: "List scheduled tasks in the stash" },
+    async run() {
+        const result = await akmTasksList();
+        output("tasks-list", result);
+    },
+});
+const tasksShowCommand = defineJsonCommand({
+    meta: { name: "show", description: "Show a parsed task definition" },
+    args: { id: { type: "positional", description: "Task id or task:<id>", required: true } },
+    async run({ args }) {
+        const { id } = parseTaskRef(args.id);
+        const result = await akmTasksShow(id);
+        output("tasks-show", result);
+    },
+});
+const tasksRemoveCommand = defineJsonCommand({
+    meta: { name: "remove", description: "Delete a task file and uninstall it from the OS scheduler" },
+    args: { id: { type: "positional", description: "Task id", required: true } },
+    async run({ args }) {
+        const { id } = parseTaskRef(args.id);
+        const result = await akmTasksRemove(id);
+        output("tasks-remove", result);
+    },
+});
+function makeTasksToggleCommand(enabled) {
+    const verb = enabled ? "enable" : "disable";
+    const description = enabled
+        ? "Enable a previously-disabled task"
+        : "Disable a task in the OS scheduler without removing the file";
+    return defineJsonCommand({
+        meta: { name: verb, description },
+        args: { id: { type: "positional", description: "Task id", required: true } },
+        async run({ args }) {
+            const { id } = parseTaskRef(args.id);
+            const result = await akmTasksSetEnabled(id, enabled);
+            output(`tasks-${verb}`, result);
+        },
+    });
+}
+const tasksEnableCommand = makeTasksToggleCommand(true);
+const tasksDisableCommand = makeTasksToggleCommand(false);
+const tasksRunCommand = defineCommand({
+    meta: {
+        name: "run",
+        description: "Execute a task now (this is what cron / launchd / schtasks invoke at the scheduled time)",
+    },
+    args: { id: { type: "positional", description: "Task id", required: true } },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            const { id } = parseTaskRef(args.id);
+            const envelope = await akmTasksRun(id);
+            output("tasks-run", envelope);
+            if (envelope.exitCode !== 0)
+                process.exit(envelope.exitCode);
+        });
+    },
+});
+const tasksHistoryCommand = defineJsonCommand({
+    meta: { name: "history", description: "Show recent task run history" },
+    args: {
+        id: { type: "string", description: "Filter to one task id" },
+        limit: { type: "string", description: "Maximum rows to return (default 50)" },
+    },
+    async run({ args }) {
+        const limit = parsePositiveIntFlag(args.limit ?? undefined);
+        const result = await akmTasksHistory({ id: args.id, limit });
+        output("tasks-history", result);
+    },
+});
+const tasksSyncCommand = defineJsonCommand({
+    meta: {
+        name: "sync",
+        description: "Reconcile the on-disk task files with the OS scheduler",
+    },
+    async run() {
+        const result = await akmTasksSync();
+        output("tasks-sync", result);
+    },
+});
+const tasksDoctorCommand = defineJsonCommand({
+    meta: {
+        name: "doctor",
+        description: "Report the active scheduler backend, akm bin path, log dir, and supported schedule subset",
+    },
+    async run() {
+        const result = await akmTasksDoctor();
+        output("tasks-doctor", result);
+    },
+});
+// Single source of truth: the routing set is derived from the subCommands keys
+// (M10) so adding a subcommand can never silently desync from `hasSubcommand`.
+const tasksSubCommands = {
+    add: tasksAddCommand,
+    init: tasksInitCommand,
+    list: tasksListCommand,
+    show: tasksShowCommand,
+    remove: tasksRemoveCommand,
+    enable: tasksEnableCommand,
+    disable: tasksDisableCommand,
+    run: tasksRunCommand,
+    history: tasksHistoryCommand,
+    sync: tasksSyncCommand,
+    doctor: tasksDoctorCommand,
+};
+const TASKS_SUBCOMMAND_SET = new Set(Object.keys(tasksSubCommands));
+export const tasksCommand = defineCommand({
+    meta: {
+        name: "tasks",
+        alias: "task",
+        description: "Schedule workflows or prompts via the OS-native scheduler (cron / launchd / schtasks)",
+    },
+    subCommands: tasksSubCommands,
+    run({ args }) {
+        return runWithJsonErrors(async () => {
+            if (hasSubcommand(args, TASKS_SUBCOMMAND_SET))
+                return;
+            const result = await akmTasksList();
+            output("tasks-list", result);
+        });
+    },
+});