akm-cli 0.7.5 → 0.8.0-rc.6

package/dist/commands/lint/task-linter.js

@@ -0,0 +1,50 @@
+// 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 { BaseLinter } from "./base-linter";
+/**
+ * Linter for `tasks/` assets.
+ *
+ * Tasks are pure YAML files at `<stash>/tasks/<id>.yml`. In addition to the
+ * base checks this linter validates the required task fields:
+ *
+ *   - `schedule`  (string, non-empty) — cron expression or `@`-alias
+ *   - `enabled`   (boolean)
+ *   - At least one of: `prompt`, `workflow`, or `command` field present
+ *
+ * All issues are reported as `invalid-task-yaml` and are **not** auto-fixable.
+ * Cron expression syntax validation is intentionally out of scope (that
+ * belongs to `parseSchedule()`).
+ */
+export class TaskLinter extends BaseLinter {
+    types = ["tasks"];
+    lint(ctx) {
+        const issues = this.runBaseChecks(ctx);
+        // Skip files that failed to parse — `data` will be empty.
+        if (ctx.data === null || Object.keys(ctx.data).length === 0)
+            return issues;
+        const missing = [];
+        // schedule: must be present and non-empty
+        if (!("schedule" in ctx.data) || typeof ctx.data.schedule !== "string" || ctx.data.schedule.trim() === "") {
+            missing.push("schedule");
+        }
+        // enabled: must be present (boolean — value of false is valid)
+        if (!("enabled" in ctx.data)) {
+            missing.push("enabled");
+        }
+        // At least one of: prompt, workflow, or command
+        const hasTarget = "prompt" in ctx.data || "workflow" in ctx.data || "command" in ctx.data;
+        if (!hasTarget) {
+            missing.push("prompt, workflow, or command");
+        }
+        if (missing.length > 0) {
+            issues.push({
+                file: ctx.relPath,
+                issue: "invalid-task-yaml",
+                detail: `missing required fields: ${missing.join(", ")}`,
+                fixed: false,
+            });
+        }
+        return issues;
+    }
+}

package/dist/commands/lint/types.js

@@ -0,0 +1,4 @@
+// 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/.
+export {};

package/dist/commands/lint/vault-key-rules.js

@@ -0,0 +1,139 @@
+// 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/.
+/**
+ * Vault security lint rules — flags known-dangerous environment variable names.
+ *
+ * These env var names, when present as vault keys, indicate the vault can be
+ * used to hijack process execution via loader injection, path override, or
+ * shell/runtime startup hooks.  The lint pass emits a warning-level finding;
+ * it does NOT block vault load or `akm vault setKey`.
+ *
+ * Enforcement scope:
+ *   - `akm lint` reports findings as `dangerous-vault-key` (non-blocking warn).
+ *   - `akm add` BLOCKS install unless `--allow-insecure` is set (or, on TTY,
+ *     the user explicitly confirms at the prompt).
+ *   - `akm vault setKey` does NOT consult this list — by design, the operator
+ *     owns their own vault and may legitimately store any key locally.  The
+ *     gate exists only for third-party stash installation.
+ *
+ * False-positive tradeoff:
+ *   A handful of keys (EDITOR, VISUAL, PAGER) are included because they are
+ *   invoked by many interactive tools and are a documented RCE vector when
+ *   sourced from untrusted vaults.  They will also flag on benign vaults
+ *   where the operator legitimately wants to set their editor — accept the
+ *   FP and bypass with `--allow-insecure` after review.
+ */
+import { listKeys } from "../vault";
+// ── Dangerous key set ─────────────────────────────────────────────────────────
+export const DANGEROUS_VAULT_KEYS = new Set([
+    // Dynamic linker hijacking (Linux glibc ld.so)
+    "LD_PRELOAD", // forces shared library injection
+    "LD_LIBRARY_PATH", // overrides library search path
+    "LD_AUDIT", // loads auditing libs (CVE-class injection vector)
+    "LD_DEBUG", // info disclosure / loader behaviour leak
+    "LD_BIND_NOW", // eager symbol resolution — can trigger malicious libs
+    "LD_PROFILE", // writes profile data — abusable for info disclosure
+    "LD_ASSUME_KERNEL", // kernel-version spoofing affecting loader behaviour
+    "LD_TRACE_LOADED_OBJECTS", // info disclosure (lists linked libs)
+    // Dynamic linker hijacking (macOS dyld)
+    "DYLD_INSERT_LIBRARIES", // macOS analogue of LD_PRELOAD
+    "DYLD_LIBRARY_PATH", // overrides dyld library search path
+    "DYLD_FRAMEWORK_PATH", // overrides framework search path
+    // Shell and command resolution
+    "PATH", // command lookup hijack
+    "BASH_ENV", // sourced on non-interactive bash startup (RCE)
+    "ENV", // sourced on POSIX sh startup (RCE)
+    "PROMPT_COMMAND", // command run before each bash prompt (RCE)
+    "PS1", // prompt — command substitution arbitrary code
+    "PS2", // continuation prompt — command substitution
+    "IFS", // Internal Field Separator — classic word-splitting attack
+    // Shell startup hijack
+    "ZDOTDIR", // zsh startup file lookup directory hijack
+    // Language runtime hijacking — Node.js
+    "NODE_OPTIONS", // injects flags incl. --require module-load RCE
+    "NODE_PATH", // module resolution hijack
+    "NODE_TLS_REJECT_UNAUTHORIZED", // silently disables TLS verification — MITM enabler
+    // Language runtime hijacking — Python
+    "PYTHONSTARTUP", // sourced by interactive python (RCE)
+    "PYTHONPATH", // module resolution hijack
+    "PYTHONINSPECT", // drops into REPL after script — sandbox escape vector
+    "PYTHONHOME", // python install prefix hijack
+    "PYTHONNOUSERSITE", // disables user-site isolation — sandbox weakening
+    // Language runtime hijacking — Ruby
+    "RUBYLIB", // ruby load path hijack
+    "RUBYOPT", // injects ruby command-line opts
+    // Language runtime hijacking — Perl
+    "PERL5LIB", // perl @INC hijack
+    "PERL5OPT", // injects perl command-line opts
+    // Language runtime hijacking — Java
+    "JAVA_TOOL_OPTIONS", // honoured by every JVM — flag injection / agent load
+    "JDK_JAVA_OPTIONS", // JDK launcher options injection
+    "_JAVA_OPTIONS", // legacy JVM options injection
+    // Git (RCE via git invocations)
+    "GIT_SSH_COMMAND", // replaces ssh with arbitrary command (RCE)
+    "GIT_EXTERNAL_DIFF", // runs arbitrary command during diff (RCE)
+    "GIT_PAGER", // runs arbitrary command for paging (RCE)
+    "GIT_EDITOR", // runs arbitrary command for editor (RCE)
+    // Interactive-tool invocation hijack — high FP rate but documented RCE vectors
+    "EDITOR", // invoked by git, crontab, sudoedit, etc. (RCE)
+    "VISUAL", // EDITOR fallback used by many tools (RCE)
+    "PAGER", // invoked by git, man, systemctl, etc. (RCE)
+]);
+/**
+ * Pattern-based dangerous key matchers.
+ *
+ * Some attack vectors target a family of variable names rather than a single
+ * literal — most famously Shellshock (CVE-2014-6271), which exploits keys
+ * prefixed with `BASH_FUNC_`.  Listing every concrete name is impossible; we
+ * test against this pattern set in addition to the literal `Set`.
+ */
+export const DANGEROUS_VAULT_KEY_PATTERNS = [
+    {
+        // CVE-2014-6271 (Shellshock) — bash imports exported functions named
+        // `BASH_FUNC_<name>%%` and parses their bodies, enabling RCE.
+        pattern: /^BASH_FUNC_/,
+        reason: "Shellshock-class bash function injection (CVE-2014-6271)",
+    },
+];
+/**
+ * Returns `true` if the given key name is dangerous — either by literal match
+ * against `DANGEROUS_VAULT_KEYS` or by matching any entry in
+ * `DANGEROUS_VAULT_KEY_PATTERNS`.
+ */
+export function isDangerousVaultKey(key) {
+    if (DANGEROUS_VAULT_KEYS.has(key))
+        return true;
+    for (const { pattern } of DANGEROUS_VAULT_KEY_PATTERNS) {
+        if (pattern.test(key))
+            return true;
+    }
+    return false;
+}
+// ── Checker ───────────────────────────────────────────────────────────────────
+/**
+ * Inspect a vault `.env` file and return a lint finding for every key whose
+ * name appears in `DANGEROUS_VAULT_KEYS` or matches a pattern in
+ * `DANGEROUS_VAULT_KEY_PATTERNS`.
+ *
+ * @param vaultPath  Absolute path to the `.env` file.
+ * @param relPath    Stash-relative path used as the `file` field in findings
+ *                   (e.g. `"vaults/prod.env"`).
+ * @param vaultRef   Human-readable vault ref (e.g. `"vault:prod"`) shown in
+ *                   the finding message.
+ */
+export function checkVaultForDangerousKeys(vaultPath, relPath, vaultRef) {
+    const { keys } = listKeys(vaultPath);
+    const issues = [];
+    for (const key of keys) {
+        if (!isDangerousVaultKey(key))
+            continue;
+        issues.push({
+            file: relPath,
+            issue: "dangerous-vault-key",
+            detail: `Vault key \`${key}\` can be used to hijack process execution when injected via \`akm vault run\`. Vault ref: ${vaultRef}. Review this vault file before running \`akm vault run\` commands against untrusted stashes.`,
+            fixed: false,
+        });
+    }
+    return issues;
+}

package/dist/commands/lint/workflow-linter.js

@@ -0,0 +1,56 @@
+// 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 { BaseLinter } from "./base-linter";
+const PLACEHOLDER_STRINGS = ["Describe what this workflow accomplishes", "Example Workflow"];
+/**
+ * Linter for `workflows/` assets.
+ *
+ * Extra check beyond base:
+ *   - `placeholder-stub`: body contains a known placeholder string.
+ *     Fix: delete the file.
+ */
+export class WorkflowLinter extends BaseLinter {
+    types = ["workflows"];
+    lint(ctx) {
+        const issues = this.runBaseChecks(ctx);
+        const placeholderMatch = this.#checkPlaceholderStub(ctx.body);
+        if (placeholderMatch) {
+            if (ctx.fix) {
+                try {
+                    fs.unlinkSync(ctx.filePath);
+                    issues.push({
+                        file: ctx.relPath,
+                        issue: "placeholder-stub",
+                        detail: `deleted: found "${placeholderMatch}"`,
+                        fixed: true,
+                    });
+                }
+                catch (e) {
+                    issues.push({
+                        file: ctx.relPath,
+                        issue: "placeholder-stub",
+                        detail: `could not delete: ${e instanceof Error ? e.message : String(e)}`,
+                        fixed: false,
+                    });
+                }
+                return issues;
+            }
+            issues.push({
+                file: ctx.relPath,
+                issue: "placeholder-stub",
+                detail: `placeholder text: "${placeholderMatch}"`,
+                fixed: false,
+            });
+        }
+        return issues;
+    }
+    #checkPlaceholderStub(body) {
+        for (const placeholder of PLACEHOLDER_STRINGS) {
+            if (body.includes(placeholder))
+                return placeholder;
+        }
+        return null;
+    }
+}

package/dist/commands/lint.js

@@ -0,0 +1,4 @@
+// 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/.
+export { akmLint } from "./lint/index";

package/dist/commands/migration-help.js

@@ -1,6 +1,9 @@
+// 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";
-const CHANGELOG_URL = "https://github.com/itlackey/akm/blob/main/.github/CHANGELOG.md";
+const CHANGELOG_URL = "https://github.com/itlackey/akm/blob/main/CHANGELOG.md";
 const MIGRATION_DOC_URL = "https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md";
 /**
  * Directory containing per-version release notes. Resolved relative to
@@ -14,7 +17,7 @@ function releaseNotesDir() {
 }
 function loadChangelog() {
     try {
-        const changelogPath = path.resolve(import.meta.dir, "../../.github/CHANGELOG.md");
+        const changelogPath = path.resolve(import.meta.dir, "../../CHANGELOG.md");
         if (fs.existsSync(changelogPath)) {
             return fs.readFileSync(changelogPath, "utf8");
         }

package/dist/commands/proposal.js

@@ -1,3 +1,6 @@
+// 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 proposal {list,show,accept,reject,diff}` — review surface for the
  * proposal substrate (#225).
@@ -12,7 +15,7 @@ import { resolveStashDir } from "../core/common";
 import { loadConfig } from "../core/config";
 import { UsageError } from "../core/errors";
 import { appendEvent } from "../core/events";
-import { archiveProposal, createProposal, diffProposal, getProposal, listProposals, promoteProposal, validateProposal, } from "../core/proposals";
+import { archiveProposal, createProposal, diffProposal, getProposal, isProposalSkipped, listProposals, promoteProposal, resolveProposalId, revertProposal, validateProposal, } from "../core/proposals";
 // ── Shared helpers ──────────────────────────────────────────────────────────
 function resolveStash(stashDir) {
     if (stashDir)
@@ -21,9 +24,12 @@ function resolveStash(stashDir) {
 }
 export function akmProposalList(options = {}) {
     const stash = resolveStash(options.stashDir);
-    // `--status accepted|rejected` implies archive-inclusion since the live
-    // queue only ever contains pending entries.
-    const includeArchive = options.includeArchive === true || options.status === "accepted" || options.status === "rejected";
+    // `--status accepted|rejected|reverted` implies archive-inclusion since the
+    // live queue only ever contains pending entries.
+    const includeArchive = options.includeArchive === true ||
+        options.status === "accepted" ||
+        options.status === "rejected" ||
+        options.status === "reverted";
     const proposals = listProposals(stash, {
         includeArchive,
         status: options.status,
@@ -43,7 +49,8 @@ export function akmProposalShow(options) {
 export async function akmProposalAccept(options) {
     const stash = resolveStash(options.stashDir);
     const config = options.config ?? loadConfig();
-    const result = await promoteProposal(stash, config, options.id, { target: options.target }, options.ctx);
+    const resolvedId = resolveProposalId(stash, options.id).id;
+    const result = await promoteProposal(stash, config, resolvedId, { target: options.target }, options.ctx);
     // Emit `promoted` to the events stream so observers (audit, dashboards,
     // sync) see the accept happen. Only emit on the happy path — promotion
     // throws on validation failure, so reaching this point means the asset
@@ -69,11 +76,11 @@ export async function akmProposalAccept(options) {
 }
 export function akmProposalReject(options) {
     const stash = resolveStash(options.stashDir);
-    const existing = getProposal(stash, options.id);
+    const existing = resolveProposalId(stash, options.id);
     if (existing.status !== "pending") {
-        throw new UsageError(`Proposal ${options.id} is not pending (current status: ${existing.status}). Only pending proposals can be rejected.`, "INVALID_FLAG_VALUE");
+        throw new UsageError(`Proposal ${existing.id} is not pending (current status: ${existing.status}). Only pending proposals can be rejected.`, "INVALID_FLAG_VALUE");
     }
-    const updated = archiveProposal(stash, options.id, "rejected", options.reason, options.ctx);
+    const updated = archiveProposal(stash, existing.id, "rejected", options.reason, options.ctx);
     appendEvent({
         eventType: "rejected",
         ref: updated.ref,
@@ -96,8 +103,8 @@ export function akmProposalReject(options) {
 export function akmProposalDiff(options) {
     const stash = resolveStash(options.stashDir);
     const config = options.config ?? loadConfig();
-    const proposal = getProposal(stash, options.id);
-    const diff = diffProposal(stash, config, options.id, { target: options.target });
+    const proposal = resolveProposalId(stash, options.id);
+    const diff = diffProposal(stash, config, proposal.id, { target: options.target });
     return {
         schemaVersion: 1,
         id: proposal.id,
@@ -109,11 +116,58 @@ export function akmProposalDiff(options) {
 }
 export function akmProposalCreate(options) {
     const stash = resolveStash(options.stashDir);
-    const proposal = createProposal(stash, {
+    // Manual proposal creation (via `akm proposal create`) always bypasses
+    // dedup/cooldown guards — the operator is explicitly requesting a proposal.
+    const result = createProposal(stash, {
         ref: options.ref,
         source: options.source,
         ...(options.sourceRun !== undefined ? { sourceRun: options.sourceRun } : {}),
         payload: options.payload,
+        force: true,
     }, options.ctx);
-    return { schemaVersion: 1, ok: true, proposal };
+    if (isProposalSkipped(result)) {
+        // Should never happen with force:true — defensive only.
+        throw new Error(`Unexpected proposal skip: ${result.message}`);
+    }
+    return { schemaVersion: 1, ok: true, proposal: result };
+}
+/**
+ * Restore an accepted proposal's prior content from the backup captured at
+ * promotion time (Advantage D6c / Phase 6C).
+ *
+ * Failure modes (all surface as typed errors so the CLI can map exit codes):
+ *   - Proposal id does not resolve → `NotFoundError("FILE_NOT_FOUND")`
+ *     (raised by `resolveProposalId` / `getProposal`).
+ *   - Proposal is not `status === "accepted"` → `UsageError("INVALID_FLAG_VALUE")`
+ *     with message `"only accepted proposals can be reverted ..."`.
+ *   - No `backup` field, or the backup file is missing on disk →
+ *     `UsageError` with message `"no backup available for this proposal ..."`.
+ *
+ * On success, emits a `proposal_reverted` event for observability, mirroring
+ * how `akmProposalAccept` emits `promoted` and `akmProposalReject` emits
+ * `rejected`.
+ */
+export async function akmProposalRevert(options) {
+    const stash = resolveStash(options.stashDir);
+    const config = options.config ?? loadConfig();
+    const resolvedId = resolveProposalId(stash, options.id).id;
+    const result = await revertProposal(stash, config, resolvedId, { target: options.target }, options.ctx);
+    appendEvent({
+        eventType: "proposal_reverted",
+        ref: result.ref,
+        metadata: {
+            proposalId: result.proposal.id,
+            source: result.proposal.source,
+            ...(result.proposal.sourceRun !== undefined ? { sourceRun: result.proposal.sourceRun } : {}),
+            assetPath: result.assetPath,
+        },
+    });
+    return {
+        schemaVersion: 1,
+        ok: true,
+        id: result.proposal.id,
+        ref: result.ref,
+        assetPath: result.assetPath,
+        proposal: result.proposal,
+    };
 }

package/dist/commands/propose.js

@@ -1,3 +1,6 @@
+// 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 propose <type> <name> --task ...` — proposal-producing agent
  * command (#226).
@@ -9,37 +12,23 @@
  * Failures use the same {@link AgentFailureReason} discriminants as
  * `akm reflect`. `propose_invoked` is emitted at command entry.
  */
+import fs from "node:fs";
 import { parseAssetRef } from "../core/asset-ref";
 import { TYPE_DIRS } from "../core/asset-spec";
 import { resolveStashDir } from "../core/common";
-import { loadConfig } from "../core/config";
 import { ConfigError, UsageError } from "../core/errors";
 import { appendEvent } from "../core/events";
-import { createProposal } from "../core/proposals";
-import { parseAgentConfig, requireAgentProfile, runAgent, } from "../integrations/agent";
+import { createProposal, isProposalSkipped, } from "../core/proposals";
+import { runAgent, } from "../integrations/agent";
+import { resolveProcessAgentProfile } from "../integrations/agent/config";
 import { buildProposePrompt, parseAgentProposalPayload } from "../integrations/agent/prompts";
-function loadAgentConfigFromDisk() {
-    const config = loadConfig();
-    return parseAgentConfig(config.agent);
-}
-function resolveProfile(options) {
-    if (options.agentProfile)
-        return options.agentProfile;
-    const agent = options.agentConfig ?? loadAgentConfigFromDisk();
-    return requireAgentProfile(agent, options.profile);
-}
+import { runAgentSdk } from "../integrations/agent/sdk-runner";
+import { baseFailureFields, enoentHintMessage, isEnoentFailure, loadAgentConfigFromDisk, resolveAgentProfile, } from "./agent-support";
 function failureEnvelope(result, type, name, fallbackReason = "non_zero_exit") {
-    const reason = result.reason ?? fallbackReason;
     return {
-        schemaVersion: 1,
-        ok: false,
-        reason,
-        error: result.error ?? `agent failure (${reason})`,
+        ...baseFailureFields(result, fallbackReason),
         type,
         name,
-        exitCode: result.exitCode,
-        ...(result.stdout ? { stdout: result.stdout } : {}),
-        ...(result.stderr ? { stderr: result.stderr } : {}),
     };
 }
 export async function akmPropose(options) {
@@ -68,9 +57,31 @@ export async function akmPropose(options) {
         },
     });
     // 2. Resolve profile.
+    // When an explicit --profile flag is given, honour it directly (existing
+    // behaviour). Otherwise use resolveProcessAgentProfile so that per-process
+    // agent config (agent.processes["propose"]) is picked up automatically.
     let profile;
+    let resolvedTimeoutMs = options.timeoutMs;
     try {
-        profile = resolveProfile(options);
+        if (options.agentProfile) {
+            // Test seam: injected profile bypasses all config.
+            profile = options.agentProfile;
+        }
+        else if (options.profile) {
+            // Explicit --profile flag wins over process config.
+            profile = resolveAgentProfile(options);
+        }
+        else {
+            // Use per-process config resolution (falls back to agent.default).
+            const agent = options.agentConfig ?? loadAgentConfigFromDisk();
+            const processName = options.agentProcess ?? "propose";
+            const resolved = resolveProcessAgentProfile(processName, agent);
+            profile = resolved.profile;
+            // Only apply process-resolved timeoutMs when caller didn't supply one.
+            if (resolvedTimeoutMs === undefined) {
+                resolvedTimeoutMs = resolved.timeoutMs;
+            }
+        }
     }
     catch (err) {
         if (err instanceof ConfigError || err instanceof UsageError)
@@ -91,20 +102,40 @@ export async function akmPropose(options) {
     // 4. Spawn the agent.
     // Real agent runs use interactive mode so file tools can write the draft.
     // Injected/custom spawns still need captured stdout for JSON payload tests.
-    const runOptions = {
-        stdio: options.runAgentOptions?.spawn ? "captured" : "interactive",
-        parseOutput: "text",
-        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
-        ...(options.runAgentOptions ?? {}),
-    };
-    const result = await runAgent(profile, prompt, runOptions);
+    // Use callAi for the unified AI dispatch path (agent CLI preferred, LLM HTTP fallback).
+    const useCustomSpawn = Boolean(options.runAgentOptions?.spawn);
+    let result;
+    if (useCustomSpawn) {
+        // Test seam: use raw runAgent with injected spawn so tests remain deterministic.
+        const runOptions = {
+            stdio: "captured",
+            parseOutput: "text",
+            ...(resolvedTimeoutMs !== undefined ? { timeoutMs: resolvedTimeoutMs } : {}),
+            ...(options.runAgentOptions ?? {}),
+        };
+        result = await runAgent(profile, prompt, runOptions);
+    }
+    else {
+        // Production path: dispatch directly to the appropriate runner.
+        const runOptions = {
+            stdio: resolvedDraftPath ? "interactive" : "captured",
+            parseOutput: "text",
+            ...(resolvedTimeoutMs !== undefined ? { timeoutMs: resolvedTimeoutMs } : {}),
+        };
+        result = profile.sdkMode
+            ? await runAgentSdk(profile, prompt ?? "", runOptions)
+            : await runAgent(profile, prompt, runOptions);
+    }
     if (!result.ok) {
+        // B3: ENOENT / not-found gives an actionable hint.
+        if (isEnoentFailure(result)) {
+            return { ...failureEnvelope(result, options.type, options.name), error: enoentHintMessage(profile.bin) };
+        }
         return failureEnvelope(result, options.type, options.name);
     }
     // 5. Resolve the proposal content.
     // Path A: opencode wrote the draft file — read it directly (no stdout parse).
     // Path B: fallback to stdout JSON parse for non-file-writing agents.
-    const fs = await import("node:fs");
     let payload;
     if (fs.existsSync(resolvedDraftPath)) {
         const draftContent = fs.readFileSync(resolvedDraftPath, "utf8");
@@ -115,6 +146,21 @@ export async function akmPropose(options) {
         };
     }
     else {
+        // B1: When interactive mode was used and stdout is empty, the agent did not
+        // write the draft file and stdout was not captured — surface an actionable error.
+        const stdioWasInteractive = !useCustomSpawn;
+        if (stdioWasInteractive && (result.stdout ?? "") === "") {
+            return {
+                schemaVersion: 1,
+                ok: false,
+                reason: "parse_error",
+                error: "Agent did not write draft file and stdout was not captured (interactive mode). Check that the agent CLI understood the file-write instruction, or configure a headless profile with stdio: 'captured'.",
+                type: options.type,
+                name: options.name,
+                exitCode: result.exitCode,
+                ...(result.stderr ? { stderr: result.stderr } : {}),
+            };
+        }
         try {
             payload = parseAgentProposalPayload(result.stdout ?? "");
         }
@@ -174,12 +220,21 @@ export async function akmPropose(options) {
         ref,
         source: "propose",
         sourceRun: `propose-${Date.now()}`,
+        // User-initiated proposals always bypass dedup/cooldown guards — the
+        // operator is explicitly asking for a new proposal.
+        force: true,
         payload: {
             content: payload.content,
             ...(payload.frontmatter ? { frontmatter: payload.frontmatter } : {}),
         },
     };
-    const proposal = createProposal(stash, createInput, options.ctx);
+    const proposalResult = createProposal(stash, createInput, options.ctx);
+    // With force:true, the result is always a Proposal (never skipped).
+    if (isProposalSkipped(proposalResult)) {
+        // Should never happen when force:true, but be defensive.
+        throw new Error(`Unexpected skip in propose command: ${proposalResult.message}`);
+    }
+    const proposal = proposalResult;
     return {
         schemaVersion: 1,
         ok: true,