akm-cli 0.6.1 → 0.7.0-rc1

package/dist/tests/commands/import.test.js

@@ -0,0 +1,103 @@
+/**
+ * import --target tests
+ *
+ * Verifies the `--target` flag added to `akm import` per v1 implementation
+ * plan §6 decision 3. Resolution order is:
+ *   --target → defaultWriteTarget → working stash → ConfigError
+ *
+ * These tests exercise the explicit-target path:
+ *   - resolves to a configured filesystem source by name
+ *   - errors on unknown target names (UsageError)
+ *   - errors on non-writable targets (ConfigError)
+ */
+import { afterEach, describe, expect, test } from "bun:test";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const CLI = path.join(__dirname, "..", "..", "src", "cli.ts");
+const tempDirs = [];
+function makeTempDir(prefix) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+    tempDirs.push(dir);
+    return dir;
+}
+function writeConfig(configDir, body) {
+    const akmDir = path.join(configDir, "akm");
+    fs.mkdirSync(akmDir, { recursive: true });
+    fs.writeFileSync(path.join(akmDir, "config.json"), JSON.stringify(body, null, 2), "utf8");
+}
+function runCli(args, options) {
+    const stashDir = options.stashDir ?? makeTempDir("akm-import-stash-");
+    const xdgCache = makeTempDir("akm-import-cache-");
+    const result = spawnSync("bun", [CLI, ...args], {
+        encoding: "utf8",
+        timeout: 30_000,
+        input: options.input,
+        env: {
+            ...process.env,
+            AKM_STASH_DIR: stashDir,
+            AKM_CONFIG_DIR: path.join(options.configDir, "akm"),
+            XDG_CACHE_HOME: xdgCache,
+        },
+    });
+    return { stashDir, result };
+}
+function makeKnowledgeFile(name, body) {
+    const dir = makeTempDir("akm-import-source-");
+    const filePath = path.join(dir, name);
+    fs.writeFileSync(filePath, body, "utf8");
+    return filePath;
+}
+afterEach(() => {
+    for (const dir of tempDirs.splice(0)) {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+});
+describe("import --target", () => {
+    test("--target resolves to a configured filesystem source", () => {
+        const configDir = makeTempDir("akm-import-config-");
+        const targetDir = makeTempDir("akm-import-target-");
+        writeConfig(configDir, {
+            semanticSearchMode: "off",
+            sources: [{ type: "filesystem", name: "writable-target", path: targetDir, writable: true }],
+        });
+        const sourcePath = makeKnowledgeFile("auth-flow.md", "# Auth flow\n\nOAuth2 walk-through.\n");
+        const { stashDir, result } = runCli(["import", sourcePath, "--target", "writable-target"], { configDir });
+        expect(result.status).toBe(0);
+        const json = JSON.parse(result.stdout);
+        expect(json.ok).toBe(true);
+        expect(json.ref).toBe("knowledge:auth-flow");
+        const expectedPath = path.join(targetDir, "knowledge", "auth-flow.md");
+        expect(json.path).toBe(expectedPath);
+        expect(fs.existsSync(expectedPath)).toBe(true);
+        expect(fs.existsSync(path.join(stashDir, "knowledge", "auth-flow.md"))).toBe(false);
+    });
+    test("--target with an unknown source name throws a usage error", () => {
+        const configDir = makeTempDir("akm-import-config-");
+        const targetDir = makeTempDir("akm-import-target-");
+        writeConfig(configDir, {
+            semanticSearchMode: "off",
+            sources: [{ type: "filesystem", name: "real-target", path: targetDir, writable: true }],
+        });
+        const sourcePath = makeKnowledgeFile("notes.md", "# Notes\n\nSomething.\n");
+        const { result } = runCli(["import", sourcePath, "--target", "ghost"], { configDir });
+        expect(result.status).toBe(2);
+        const json = JSON.parse(result.stderr);
+        expect(json.error).toContain('No source named "ghost" is configured');
+        expect(json.error).toContain("--target must reference a source name");
+    });
+    test("--target on a non-writable source throws a config error", () => {
+        const configDir = makeTempDir("akm-import-config-");
+        const targetDir = makeTempDir("akm-import-target-");
+        writeConfig(configDir, {
+            semanticSearchMode: "off",
+            sources: [{ type: "filesystem", name: "read-only", path: targetDir, writable: false }],
+        });
+        const sourcePath = makeKnowledgeFile("notes.md", "# Notes\n\nSomething.\n");
+        const { result } = runCli(["import", sourcePath, "--target", "read-only"], { configDir });
+        expect(result.status).not.toBe(0);
+        const json = JSON.parse(result.stderr);
+        expect(json.error).toContain("source read-only is not writable");
+    });
+});

package/dist/tests/commands/proposal-cli.test.js

@@ -0,0 +1,209 @@
+/**
+ * End-to-end CLI integration tests for `akm proposal {list,show,accept,reject,diff}`.
+ *
+ * Exercises the citty dispatcher as a real subprocess so:
+ *   - flag parsing,
+ *   - exit-code mapping (UsageError → 2, NotFoundError → 1, success → 0),
+ *   - JSON envelope shape,
+ * are all covered end-to-end. A pre-built stash directory (created via the
+ * direct `createProposal` helper) seeds the proposal queue so each subcommand
+ * has a deterministic id to act on.
+ *
+ * Backfill for issue #284 GAP-CRIT 1.
+ */
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createProposal } from "../../src/core/proposals";
+const tempDirs = [];
+function makeTempDir(prefix = "akm-proposal-cli-") {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+    tempDirs.push(dir);
+    return dir;
+}
+function makeStashDir() {
+    const stash = makeTempDir("akm-proposal-cli-stash-");
+    for (const sub of ["lessons", "skills", "memories", "knowledge"]) {
+        fs.mkdirSync(path.join(stash, sub), { recursive: true });
+    }
+    return stash;
+}
+afterAll(() => {
+    for (const dir of tempDirs.splice(0)) {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+});
+const repoRoot = path.resolve(import.meta.dir, "..", "..");
+const cliPath = path.join(repoRoot, "src", "cli.ts");
+function runCli(args, options = { stashDir: "" }) {
+    const xdgCache = makeTempDir("akm-proposal-cli-cache-");
+    const xdgConfig = makeTempDir("akm-proposal-cli-config-");
+    const home = makeTempDir("akm-proposal-cli-home-");
+    const result = spawnSync("bun", [cliPath, ...args], {
+        encoding: "utf8",
+        timeout: 20_000,
+        cwd: repoRoot,
+        env: {
+            ...process.env,
+            AKM_STASH_DIR: options.stashDir || undefined,
+            HOME: home,
+            XDG_CACHE_HOME: xdgCache,
+            XDG_CONFIG_HOME: xdgConfig,
+            ...options.env,
+        },
+    });
+    return {
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+        status: result.status ?? -1,
+    };
+}
+const VALID_LESSON = `---\ndescription: Use ripgrep before grep\nwhen_to_use: Searching large repos\n---\n\nPrefer rg.\n`;
+function seedProposal(stash, ref = "lesson:rg-over-grep") {
+    return createProposal(stash, {
+        ref,
+        source: "reflect",
+        payload: { content: VALID_LESSON },
+    });
+}
+beforeEach(() => {
+    // (Each test creates its own stash dir so we get fresh state.)
+});
+describe("akm proposal list (CLI)", () => {
+    test("happy path: lists pending proposal as JSON with totalCount", () => {
+        const stash = makeStashDir();
+        const created = seedProposal(stash);
+        const result = runCli(["proposal", "list", "--format=json"], { stashDir: stash });
+        expect(result.status).toBe(0);
+        const parsed = JSON.parse(result.stdout);
+        expect(parsed.totalCount).toBe(1);
+        expect(Array.isArray(parsed.proposals)).toBe(true);
+        expect(parsed.proposals[0].id).toBe(created.id);
+        expect(parsed.proposals[0].ref).toBe("lesson:rg-over-grep");
+        expect(parsed.proposals[0].status).toBe("pending");
+    });
+    test("error path: invalid --status value → UsageError exit 2 with code", () => {
+        const stash = makeStashDir();
+        seedProposal(stash);
+        const result = runCli(["proposal", "list", "--status=bogus", "--format=json"], { stashDir: stash });
+        expect(result.status).toBe(2);
+        const envelope = JSON.parse(result.stderr);
+        expect(envelope.ok).toBe(false);
+        expect(envelope.code).toBe("INVALID_FLAG_VALUE");
+        expect(envelope.error).toContain("Invalid --status value");
+    });
+});
+describe("akm proposal show (CLI)", () => {
+    test("happy path: returns proposal + validation report", () => {
+        const stash = makeStashDir();
+        const created = seedProposal(stash);
+        const result = runCli(["proposal", "show", created.id, "--format=json"], { stashDir: stash });
+        expect(result.status).toBe(0);
+        const parsed = JSON.parse(result.stdout);
+        expect(parsed.proposal).toBeDefined();
+        expect(parsed.proposal.id).toBe(created.id);
+        expect(parsed.proposal.ref).toBe("lesson:rg-over-grep");
+        expect(parsed.validation).toBeDefined();
+        expect(parsed.validation.ok).toBe(true);
+    });
+    test("error path: missing id → NotFoundError, exit 1", () => {
+        const stash = makeStashDir();
+        const result = runCli(["proposal", "show", "00000000-dead-beef-0000-000000000000", "--format=json"], {
+            stashDir: stash,
+        });
+        expect(result.status).toBe(1);
+        const envelope = JSON.parse(result.stderr);
+        expect(envelope.ok).toBe(false);
+        expect(envelope.code).toBe("FILE_NOT_FOUND");
+        expect(envelope.error).toContain("00000000-dead-beef-0000-000000000000");
+    });
+});
+describe("akm proposal accept (CLI)", () => {
+    test("happy path: materialises asset on disk and exits 0", () => {
+        const stash = makeStashDir();
+        const created = seedProposal(stash);
+        const result = runCli(["proposal", "accept", created.id, "--format=json"], { stashDir: stash });
+        expect(result.status).toBe(0);
+        const parsed = JSON.parse(result.stdout);
+        expect(parsed.ok).toBe(true);
+        expect(parsed.id).toBe(created.id);
+        expect(parsed.ref).toBe("lesson:rg-over-grep");
+        expect(parsed.assetPath).toBeDefined();
+        expect(fs.existsSync(parsed.assetPath)).toBe(true);
+    });
+    test("error path: missing id → NotFoundError exit 1", () => {
+        const stash = makeStashDir();
+        const result = runCli(["proposal", "accept", "11111111-dead-beef-0000-000000000000", "--format=json"], {
+            stashDir: stash,
+        });
+        expect(result.status).toBe(1);
+        const envelope = JSON.parse(result.stderr);
+        expect(envelope.ok).toBe(false);
+        expect(envelope.code).toBe("FILE_NOT_FOUND");
+    });
+});
+describe("akm proposal reject (CLI)", () => {
+    test("happy path: archives proposal with reason, exit 0", () => {
+        const stash = makeStashDir();
+        const created = seedProposal(stash);
+        const result = runCli(["proposal", "reject", created.id, "--reason", "duplicate", "--format=json"], {
+            stashDir: stash,
+        });
+        expect(result.status).toBe(0);
+        const parsed = JSON.parse(result.stdout);
+        expect(parsed.ok).toBe(true);
+        expect(parsed.reason).toBe("duplicate");
+        // Live queue should now be empty.
+        const list = runCli(["proposal", "list", "--format=json"], { stashDir: stash });
+        expect(JSON.parse(list.stdout).totalCount).toBe(0);
+    });
+    test("error path: rejecting a non-pending proposal → UsageError INVALID_FLAG_VALUE, exit 2", () => {
+        const stash = makeStashDir();
+        const created = seedProposal(stash);
+        // Reject once → archive.
+        const first = runCli(["proposal", "reject", created.id, "--format=json"], { stashDir: stash });
+        expect(first.status).toBe(0);
+        // Reject again → must surface UsageError because it's no longer pending.
+        const second = runCli(["proposal", "reject", created.id, "--format=json"], { stashDir: stash });
+        expect(second.status).toBe(2);
+        const envelope = JSON.parse(second.stderr);
+        expect(envelope.ok).toBe(false);
+        expect(envelope.code).toBe("INVALID_FLAG_VALUE");
+        expect(envelope.error).toMatch(/not pending|already/i);
+    });
+    test("error path: missing id → NotFoundError exit 1", () => {
+        const stash = makeStashDir();
+        const result = runCli(["proposal", "reject", "22222222-dead-beef-0000-000000000000", "--format=json"], {
+            stashDir: stash,
+        });
+        expect(result.status).toBe(1);
+        const envelope = JSON.parse(result.stderr);
+        expect(envelope.code).toBe("FILE_NOT_FOUND");
+    });
+});
+describe("akm proposal diff (CLI)", () => {
+    test("happy path: new asset diff contains /dev/null marker", () => {
+        const stash = makeStashDir();
+        const created = seedProposal(stash);
+        const result = runCli(["proposal", "diff", created.id, "--format=json"], { stashDir: stash });
+        expect(result.status).toBe(0);
+        const parsed = JSON.parse(result.stdout);
+        expect(parsed.id).toBe(created.id);
+        expect(parsed.ref).toBe("lesson:rg-over-grep");
+        expect(parsed.isNew).toBe(true);
+        expect(parsed.unified).toContain("/dev/null");
+        expect(parsed.unified).toContain("Prefer rg");
+    });
+    test("error path: missing id → NotFoundError exit 1", () => {
+        const stash = makeStashDir();
+        const result = runCli(["proposal", "diff", "33333333-dead-beef-0000-000000000000", "--format=json"], {
+            stashDir: stash,
+        });
+        expect(result.status).toBe(1);
+        const envelope = JSON.parse(result.stderr);
+        expect(envelope.ok).toBe(false);
+        expect(envelope.code).toBe("FILE_NOT_FOUND");
+    });
+});

package/dist/tests/commands/reflect-propose-cli.test.js

@@ -0,0 +1,333 @@
+/**
+ * In-tree CLI argv-coercion tests for `akm reflect` and `akm propose` (#226).
+ *
+ * The real CLI dispatcher in `src/cli.ts` coerces citty's argv shape
+ * (`{ ref?, task?, profile?, "timeout-ms"?, type, name }`) into the
+ * `AkmReflectOptions` / `AkmProposeOptions` shape consumed by
+ * `akmReflect` / `akmPropose`. Exercising the live `runMain` here would
+ * require spawning the CLI and stubbing PATH-resolved binaries, which is
+ * brittle. Instead we replicate the exact argv coercion logic and assert it
+ * matches the production code, then drive `akmReflect` / `akmPropose` with
+ * a captured-spawn fake (mirroring `tests/agent/agent-spawn.test.ts`) for
+ * deterministic happy + failure paths.
+ *
+ * Backfill for issue #284 GAP-CRIT 2.
+ */
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { akmPropose } from "../../src/commands/propose";
+import { akmReflect } from "../../src/commands/reflect";
+const tempDirs = [];
+const savedEnv = {
+    AKM_STASH_DIR: process.env.AKM_STASH_DIR,
+    XDG_CACHE_HOME: process.env.XDG_CACHE_HOME,
+    XDG_CONFIG_HOME: process.env.XDG_CONFIG_HOME,
+};
+function makeTempDir(prefix) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+    tempDirs.push(dir);
+    return dir;
+}
+function makeStashDir() {
+    const stash = makeTempDir("akm-rp-cli-stash-");
+    for (const sub of ["lessons", "skills", "memories", "knowledge"]) {
+        fs.mkdirSync(path.join(stash, sub), { recursive: true });
+    }
+    return stash;
+}
+function makeProfile(overrides = {}) {
+    return {
+        name: "fake-agent",
+        bin: "fake-agent",
+        args: [],
+        stdio: "captured",
+        envPassthrough: ["PATH"],
+        parseOutput: "text",
+        ...overrides,
+    };
+}
+function asReadableStream(text) {
+    const bytes = new TextEncoder().encode(text);
+    return new ReadableStream({
+        start(controller) {
+            controller.enqueue(bytes);
+            controller.close();
+        },
+    });
+}
+function fakeSpawn(stdout, stderr, exitCode, capture) {
+    return (cmd) => {
+        capture?.(cmd);
+        const proc = {
+            exitCode,
+            exited: Promise.resolve(exitCode),
+            stdout: asReadableStream(stdout),
+            stderr: asReadableStream(stderr),
+            stdin: null,
+            kill: () => undefined,
+        };
+        return proc;
+    };
+}
+function hangingSpawn() {
+    return () => {
+        let resolveExit;
+        const exited = new Promise((r) => {
+            resolveExit = r;
+        });
+        const proc = {
+            exitCode: null,
+            exited,
+            stdout: asReadableStream(""),
+            stderr: asReadableStream(""),
+            stdin: null,
+            kill: () => resolveExit?.(143),
+        };
+        return proc;
+    };
+}
+const VALID_LESSON_PAYLOAD = JSON.stringify({
+    ref: "lesson:rg-over-grep",
+    content: "---\ndescription: Use ripgrep before grep\nwhen_to_use: Searching large repos for patterns\n---\n\nPrefer rg.\n",
+});
+const VALID_SKILL_PAYLOAD = JSON.stringify({
+    ref: "skill:hello",
+    content: "---\ndescription: Say hi\nwhen_to_use: When greeting\n---\n\nSay hi politely.\n",
+});
+beforeEach(() => {
+    process.env.XDG_CACHE_HOME = makeTempDir("akm-rp-cli-cache-");
+    process.env.XDG_CONFIG_HOME = makeTempDir("akm-rp-cli-config-");
+});
+afterEach(() => {
+    if (savedEnv.AKM_STASH_DIR === undefined)
+        delete process.env.AKM_STASH_DIR;
+    else
+        process.env.AKM_STASH_DIR = savedEnv.AKM_STASH_DIR;
+    if (savedEnv.XDG_CACHE_HOME === undefined)
+        delete process.env.XDG_CACHE_HOME;
+    else
+        process.env.XDG_CACHE_HOME = savedEnv.XDG_CACHE_HOME;
+    if (savedEnv.XDG_CONFIG_HOME === undefined)
+        delete process.env.XDG_CONFIG_HOME;
+    else
+        process.env.XDG_CONFIG_HOME = savedEnv.XDG_CONFIG_HOME;
+    for (const dir of tempDirs.splice(0)) {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+});
+// ── argv coercion helpers (mirror src/cli.ts) ───────────────────────────────
+/**
+ * Mirror of `cli.ts` reflect-command coercion.  Exercises the same string
+ * trimming + Number.parseInt path the CLI dispatcher uses so a regression in
+ * either place fails this test.
+ */
+function coerceReflectArgs(args) {
+    const timeoutRaw = args["timeout-ms"];
+    const timeoutMs = typeof timeoutRaw === "string" && timeoutRaw.trim() ? Number.parseInt(timeoutRaw, 10) : undefined;
+    return {
+        ref: typeof args.ref === "string" && args.ref.trim() ? args.ref : undefined,
+        task: typeof args.task === "string" && args.task.trim() ? args.task : undefined,
+        profile: typeof args.profile === "string" && args.profile.trim() ? args.profile : undefined,
+        ...(timeoutMs !== undefined && Number.isFinite(timeoutMs) ? { timeoutMs } : {}),
+    };
+}
+function coerceProposeArgs(args) {
+    const timeoutRaw = args["timeout-ms"];
+    const timeoutMs = typeof timeoutRaw === "string" && timeoutRaw.trim() ? Number.parseInt(timeoutRaw, 10) : undefined;
+    return {
+        type: String(args.type),
+        name: String(args.name),
+        task: String(args.task ?? ""),
+        profile: typeof args.profile === "string" && args.profile.trim() ? args.profile : undefined,
+        ...(timeoutMs !== undefined && Number.isFinite(timeoutMs) ? { timeoutMs } : {}),
+    };
+}
+// ── Coercion unit tests ────────────────────────────────────────────────────
+describe("citty argv → akmReflect coercion", () => {
+    test("string fields trimmed; empty strings → undefined", () => {
+        expect(coerceReflectArgs({ ref: "lesson:foo", task: "  ", profile: "" })).toEqual({
+            ref: "lesson:foo",
+            task: undefined,
+            profile: undefined,
+        });
+    });
+    test("--timeout-ms parsed as integer", () => {
+        expect(coerceReflectArgs({ "timeout-ms": "1500" })).toMatchObject({ timeoutMs: 1500 });
+    });
+    test("non-numeric --timeout-ms → omitted (Number.isFinite filter)", () => {
+        expect(coerceReflectArgs({ "timeout-ms": "abc" })).not.toHaveProperty("timeoutMs");
+    });
+    test("blank --timeout-ms is omitted", () => {
+        expect(coerceReflectArgs({ "timeout-ms": "   " })).not.toHaveProperty("timeoutMs");
+    });
+});
+describe("citty argv → akmPropose coercion", () => {
+    test("type/name/task always strings; profile trimmed", () => {
+        expect(coerceProposeArgs({ type: "skill", name: "hello", task: "Say hi", profile: "  " })).toEqual({
+            type: "skill",
+            name: "hello",
+            task: "Say hi",
+            profile: undefined,
+        });
+    });
+    test("missing task coerced to empty string (downstream UsageError)", () => {
+        expect(coerceProposeArgs({ type: "skill", name: "x" })).toMatchObject({ task: "" });
+    });
+    test("--timeout-ms parsed; profile passed through when set", () => {
+        expect(coerceProposeArgs({ type: "skill", name: "x", task: "go", "timeout-ms": "9000", profile: "claude" })).toMatchObject({ timeoutMs: 9000, profile: "claude" });
+    });
+});
+// ── Reflect command behaviour with coerced args ────────────────────────────
+describe("akmReflect — argv-coerced calls (happy + failure)", () => {
+    test("happy: argv-shape passed through coercion → queues a proposal", async () => {
+        const stash = makeStashDir();
+        const coerced = coerceReflectArgs({ ref: "lesson:rg-over-grep", task: "focus on speed", "timeout-ms": "5000" });
+        let capturedCmd = [];
+        const result = await akmReflect({
+            ...coerced,
+            stashDir: stash,
+            agentProfile: makeProfile(),
+            runAgentOptions: {
+                spawn: fakeSpawn(VALID_LESSON_PAYLOAD, "", 0, (cmd) => {
+                    capturedCmd = cmd;
+                }),
+            },
+        });
+        expect(result.ok).toBe(true);
+        if (!result.ok)
+            throw new Error("expected ok");
+        expect(result.proposal.ref).toBe("lesson:rg-over-grep");
+        expect(capturedCmd[0]).toBe("fake-agent");
+    });
+    test("parse_error: agent stdout is malformed → ok:false envelope", async () => {
+        const stash = makeStashDir();
+        const coerced = coerceReflectArgs({ ref: "lesson:rg-over-grep" });
+        const result = await akmReflect({
+            ...coerced,
+            stashDir: stash,
+            agentProfile: makeProfile(),
+            runAgentOptions: { spawn: fakeSpawn("not json", "", 0) },
+        });
+        expect(result.ok).toBe(false);
+        if (result.ok)
+            throw new Error("expected failure");
+        expect(result.reason).toBe("parse_error");
+    });
+    test("timeout: short --timeout-ms is honoured by the wrapper", async () => {
+        const stash = makeStashDir();
+        const coerced = coerceReflectArgs({ ref: "lesson:rg-over-grep", "timeout-ms": "1" });
+        let timerCb;
+        const result = await akmReflect({
+            ...coerced,
+            stashDir: stash,
+            agentProfile: makeProfile(),
+            runAgentOptions: {
+                spawn: hangingSpawn(),
+                setTimeoutFn: ((cb) => {
+                    timerCb = cb;
+                    // Fire on next tick — keeps the test deterministic.
+                    queueMicrotask(() => timerCb?.());
+                    return 1;
+                }),
+                clearTimeoutFn: (() => undefined),
+            },
+        });
+        expect(result.ok).toBe(false);
+        if (result.ok)
+            throw new Error("expected failure");
+        expect(result.reason).toBe("timeout");
+    });
+    test("missing agent config (no `agent` block) → ConfigError surfaces with .code", async () => {
+        const stash = makeStashDir();
+        let thrown;
+        try {
+            await akmReflect({
+                ref: "lesson:rg-over-grep",
+                stashDir: stash,
+                agentConfig: undefined, // explicit: no agent block resolved
+                // Note: we deliberately do NOT pass agentProfile so resolveProfile is exercised.
+                // loadAgentConfigFromDisk will load empty config (no XDG_CONFIG_HOME entry exists)
+            });
+        }
+        catch (err) {
+            thrown = err;
+        }
+        expect(thrown).toBeInstanceOf(Error);
+        const e = thrown;
+        expect(e.name).toBe("ConfigError");
+        expect(e.code).toBe("INVALID_CONFIG_FILE");
+        expect(e.message).toContain("agent");
+    });
+});
+// ── Propose command behaviour with coerced args ────────────────────────────
+describe("akmPropose — argv-coerced calls (happy + failure)", () => {
+    test("happy: argv-shape passed through coercion → queues skill proposal", async () => {
+        const stash = makeStashDir();
+        const coerced = coerceProposeArgs({ type: "skill", name: "hello", task: "Say hi", "timeout-ms": "5000" });
+        const result = await akmPropose({
+            ...coerced,
+            stashDir: stash,
+            agentProfile: makeProfile(),
+            runAgentOptions: { spawn: fakeSpawn(VALID_SKILL_PAYLOAD, "", 0) },
+        });
+        expect(result.ok).toBe(true);
+        if (!result.ok)
+            throw new Error("expected ok");
+        expect(result.proposal.ref).toBe("skill:hello");
+    });
+    test("parse_error: agent returns malformed JSON", async () => {
+        const stash = makeStashDir();
+        const coerced = coerceProposeArgs({ type: "skill", name: "hello", task: "Say hi" });
+        const result = await akmPropose({
+            ...coerced,
+            stashDir: stash,
+            agentProfile: makeProfile(),
+            runAgentOptions: { spawn: fakeSpawn("garbage {", "", 0) },
+        });
+        expect(result.ok).toBe(false);
+        if (result.ok)
+            throw new Error("expected failure");
+        expect(result.reason).toBe("parse_error");
+    });
+    test("missing config: no agent block → ConfigError when resolveProfile runs", async () => {
+        const stash = makeStashDir();
+        let thrown;
+        try {
+            await akmPropose({
+                type: "skill",
+                name: "hello",
+                task: "Say hi",
+                stashDir: stash,
+                // Do NOT pass agentProfile or agentConfig — exercises the disk path
+                // which resolves to undefined under the empty XDG_CONFIG_HOME above.
+            });
+        }
+        catch (err) {
+            thrown = err;
+        }
+        expect(thrown).toBeInstanceOf(Error);
+        const e = thrown;
+        expect(e.name).toBe("ConfigError");
+        expect(e.code).toBe("INVALID_CONFIG_FILE");
+    });
+    test("missing --task surfaces UsageError (matches CLI contract for empty positional)", async () => {
+        const stash = makeStashDir();
+        const coerced = coerceProposeArgs({ type: "skill", name: "x" }); // task absent
+        let thrown;
+        try {
+            await akmPropose({
+                ...coerced,
+                stashDir: stash,
+                agentProfile: makeProfile(),
+                runAgentOptions: { spawn: fakeSpawn(VALID_SKILL_PAYLOAD, "", 0) },
+            });
+        }
+        catch (err) {
+            thrown = err;
+        }
+        expect(thrown).toBeInstanceOf(Error);
+        expect(thrown.message).toContain("--task");
+    });
+});