akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/commands/proposal/proposal.js

@@ -13,9 +13,9 @@
  */
 import { resolveStashDir } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
-import { UsageError } from "../../core/errors.js";
-import { appendEvent } from "../../core/events.js";
-import { archiveProposal, createProposal, diffProposal, getProposal, isProposalSkipped, listProposals, promoteProposal, resolveProposalId, revertProposal, } from "./repository.js";
+import { resolveWriteTarget } from "../../core/write-source.js";
+import { withAssetMutationLease } from "../../indexer/index-writer-lock.js";
+import { createProposal, diffProposal, isProposalSkipped, listProposals, promoteProposal, proposalContent, recoverProposalTransactionsForStash, rejectProposalDurably, resolveProposalId, resolveProposalIdForReject, revertProposal, } from "./repository.js";
 import { validateProposal } from "./validators/proposals.js";
 // ── Shared helpers ──────────────────────────────────────────────────────────
 function resolveStash(stashDir) {
@@ -23,6 +23,14 @@ function resolveStash(stashDir) {
         return stashDir;
     return resolveStashDir();
 }
+function resolveProposalQueue(stashDir, queue, config) {
+    if (stashDir)
+        return { stashDir };
+    if (!queue)
+        return { stashDir: resolveStash() };
+    const target = resolveWriteTarget(config ?? loadConfig(), queue);
+    return { stashDir: target.source.path, target };
+}
 /**
  * Thin in-process read of the pending proposal queue, used by the health HTML
  * report builder (#582) so it never shells out to `akm proposal list`.
@@ -35,7 +43,7 @@ export function listPendingProposals(stashDir) {
     return listProposals(resolveStash(stashDir), { status: "pending" });
 }
 export function akmProposalList(options = {}) {
-    const stash = resolveStash(options.stashDir);
+    const { stashDir: stash } = resolveProposalQueue(options.stashDir, options.queue, options.config);
     // `--status accepted|rejected|reverted` implies archive-inclusion since the
     // live queue only ever contains pending entries.
     const includeArchive = options.includeArchive === true ||
@@ -51,8 +59,8 @@ export function akmProposalList(options = {}) {
     return { schemaVersion: 1, totalCount: proposals.length, proposals };
 }
 export function akmProposalShow(options) {
-    const stash = resolveStash(options.stashDir);
-    const proposal = getProposal(stash, options.id);
+    const { stashDir: stash } = resolveProposalQueue(options.stashDir, options.queue, options.config);
+    const proposal = resolveProposalId(stash, options.id);
     return {
         schemaVersion: 1,
         proposal,
@@ -60,29 +68,11 @@ export function akmProposalShow(options) {
     };
 }
 export async function akmProposalAccept(options) {
-    const stash = resolveStash(options.stashDir);
     const config = options.config ?? loadConfig();
+    const queue = resolveProposalQueue(options.stashDir, options.queue, config);
+    const stash = queue.stashDir;
     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
-    // is committed.
-    appendEvent({
-        eventType: "promoted",
-        ref: result.ref,
-        metadata: {
-            proposalId: result.proposal.id,
-            source: result.proposal.source,
-            ...(result.proposal.sourceRun !== undefined ? { sourceRun: result.proposal.sourceRun } : {}),
-            assetPath: result.assetPath,
-            // Attribution tagging: carry the eligibility lane from the proposal record
-            // onto the promoted event so accept outcomes can be sliced by lane.
-            ...(result.proposal.eligibilitySource !== undefined
-                ? { eligibilitySource: result.proposal.eligibilitySource }
-                : {}),
-        },
-    });
+    const result = await promoteProposal(stash, config, resolvedId, { target: options.target, queueTarget: queue.target, gateDecision: options.gateDecision }, options.ctx);
     return {
         schemaVersion: 1,
         ok: true,
@@ -92,37 +82,32 @@ export async function akmProposalAccept(options) {
         proposal: result.proposal,
     };
 }
-export function akmProposalReject(options) {
-    const stash = resolveStash(options.stashDir);
-    const existing = resolveProposalId(stash, options.id);
-    if (existing.status !== "pending") {
-        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, existing.id, "rejected", options.reason, options.ctx);
-    appendEvent({
-        eventType: "rejected",
-        ref: updated.ref,
-        metadata: {
-            proposalId: updated.id,
-            source: updated.source,
-            ...(updated.sourceRun !== undefined ? { sourceRun: updated.sourceRun } : {}),
+export async function akmProposalReject(options) {
+    return withAssetMutationLease("proposal-reject", async () => {
+        const config = options.config ?? loadConfig();
+        const { stashDir: stash } = resolveProposalQueue(options.stashDir, options.queue, config);
+        // resolveProposalIdForReject tolerates a legacy row whose metadata fails
+        // strict decoding — resolveProposalId's exact-UUID match would otherwise
+        // throw here, before the terminal-status machinery even runs.
+        const proposalId = resolveProposalIdForReject(stash, options.id, options.ctx);
+        await recoverProposalTransactionsForStash(stash, config, options.ctx, proposalId);
+        const updated = rejectProposalDurably(stash, proposalId, options.reason, options.ctx, options.gateDecision);
+        return {
+            schemaVersion: 1,
+            ok: true,
+            id: updated.id,
+            ref: updated.ref,
             ...(options.reason !== undefined ? { reason: options.reason } : {}),
-        },
+            proposal: updated,
+        };
     });
-    return {
-        schemaVersion: 1,
-        ok: true,
-        id: updated.id,
-        ref: updated.ref,
-        ...(options.reason !== undefined ? { reason: options.reason } : {}),
-        proposal: updated,
-    };
 }
 export function akmProposalDiff(options) {
-    const stash = resolveStash(options.stashDir);
     const config = options.config ?? loadConfig();
+    const queue = resolveProposalQueue(options.stashDir, options.queue, config);
+    const stash = queue.stashDir;
     const proposal = resolveProposalId(stash, options.id);
-    const diff = diffProposal(stash, config, proposal.id, { target: options.target });
+    const diff = diffProposal(stash, config, proposal.id, { target: options.target, queueTarget: queue.target });
     return {
         schemaVersion: 1,
         id: proposal.id,
@@ -133,12 +118,15 @@ export function akmProposalDiff(options) {
     };
 }
 export function akmProposalCreate(options) {
-    const stash = resolveStash(options.stashDir);
+    const queue = resolveProposalQueue(options.stashDir, options.queue, options.config);
+    const stash = queue.stashDir;
+    const target = options.target ?? (queue.target ? { source: queue.target.source.name, root: queue.target.source.path } : undefined);
     // 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,
+        ...(target !== undefined ? { target } : {}),
         ...(options.sourceRun !== undefined ? { sourceRun: options.sourceRun } : {}),
         payload: options.payload,
         force: true,
@@ -166,20 +154,11 @@ export function akmProposalCreate(options) {
  * `rejected`.
  */
 export async function akmProposalRevert(options) {
-    const stash = resolveStash(options.stashDir);
     const config = options.config ?? loadConfig();
+    const queue = resolveProposalQueue(options.stashDir, options.queue, config);
+    const stash = queue.stashDir;
     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,
-        },
-    });
+    const result = await revertProposal(stash, config, resolvedId, { target: options.target, queueTarget: queue.target }, options.ctx);
     return {
         schemaVersion: 1,
         ok: true,
@@ -189,3 +168,42 @@ export async function akmProposalRevert(options) {
         proposal: result.proposal,
     };
 }
+/**
+ * Bulk accept/reject every pending proposal from one generator, applying the
+ * shared `--max-diff-lines` / `--older-than` filters. Consolidates the two
+ * near-identical loops that lived in `proposal-cli.ts` (Chunk 6 WI-6.6);
+ * behavior is verbatim — same filter order, same per-item envelopes, same
+ * dry-run record shape. The destructive-confirmation prompt stays CLI-side.
+ */
+export async function bulkAdjudicateProposals(options) {
+    const config = options.config ?? loadConfig();
+    const { stashDir } = resolveProposalQueue(options.stashDir, options.queue, config);
+    const pending = listProposals(stashDir, { status: "pending" }).filter((p) => {
+        if (p.source !== options.generator)
+            return false;
+        if (options.maxDiffLines !== undefined) {
+            const lines = proposalContent(p).split("\n").length;
+            if (lines > options.maxDiffLines)
+                return false;
+        }
+        if (options.olderThanMs !== undefined) {
+            const age = Date.now() - new Date(p.createdAt).getTime();
+            if (age < options.olderThanMs)
+                return false;
+        }
+        return true;
+    });
+    const results = [];
+    for (const proposal of pending) {
+        if (options.dryRun) {
+            results.push({ id: proposal.id, ref: proposal.ref, source: proposal.source, dryRun: true });
+        }
+        else if (options.action === "accept") {
+            results.push(await akmProposalAccept({ stashDir, id: proposal.id, queue: options.queue, target: options.target, config }));
+        }
+        else {
+            results.push(await akmProposalReject({ stashDir, id: proposal.id, queue: options.queue, reason: options.reason, config }));
+        }
+    }
+    return { count: results.length, results };
+}

package/dist/commands/proposal/propose-cli.js

@@ -0,0 +1,88 @@
+// 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 new` — the asset-authoring entry point (formerly the
+ * top-level `akm propose`, moved under the `proposal` group per the 0.9 CLI
+ * overhaul, S8). Shares no private helper with the proposal MANAGEMENT
+ * family (list/show/accept/reject/…, `./proposal-cli.ts`) — its path/name
+ * helpers come from the shared src/core/asset/asset-create.ts module.
+ *
+ * Keeps the inline `runWithJsonErrors` form (branches on the result and sets
+ * `process.exitCode` conditionally on a failed proposal) rather than
+ * migrating to `defineJsonCommand`, matching the original contribute-cli.ts
+ * rationale: `process.exitCode` (not `process.exit()`) so the process still
+ * exits via natural event-loop drain rather than skipping pending cleanup.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { defineCommand } from "citty";
+import { getStringArg, parsePositiveIntFlag } from "../../cli/parse-args.js";
+import { EXIT_CODES, GLOBAL_OUTPUT_ARGS, output, runWithJsonErrors } from "../../cli/shared.js";
+import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../../core/asset/asset-create.js";
+import { UsageError } from "../../core/errors.js";
+import { akmPropose } from "./propose.js";
+const EXIT_GENERAL = EXIT_CODES.GENERAL;
+export const proposeCommand = defineCommand({
+    meta: {
+        name: "new",
+        description: "Ask the configured agent CLI to author a brand-new asset and queue it as a proposal",
+    },
+    // Raw defineCommand: declare the global output flags so their space-separated
+    // values are consumed rather than shifting the `type` / `name` positionals.
+    args: {
+        ...GLOBAL_OUTPUT_ARGS,
+        // Optional in citty so run() is invoked when omitted; we re-validate
+        // below to surface a structured UsageError (exit 2) instead of citty's
+        // default help-banner exit-0.
+        type: { type: "positional", description: "Asset type (skill, command, knowledge, lesson, ...)", required: false },
+        name: {
+            type: "positional",
+            description: "Asset name (flat, no '/'; use --path for a subdirectory)",
+            required: false,
+        },
+        path: {
+            type: "string",
+            description: "Relative subdirectory under the type dir to place the proposed asset in (e.g. 'release'). The filename comes from the name.",
+        },
+        task: { type: "string", description: "Task description for the agent (what should the asset do?)" },
+        file: { type: "string", description: "Read the task or prompt text from a UTF-8 file" },
+        engine: { type: "string", description: "Engine to use (defaults to defaults.engine)" },
+        "timeout-ms": { type: "string", description: "Override the agent CLI timeout in milliseconds" },
+    },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            // citty silently shows help and exits 0 when required positionals are
+            // omitted. Re-validate explicitly so the exit code is 2 (USAGE) and a
+            // structured JSON error reaches scripted callers.
+            const taskFromFlag = typeof args.task === "string" ? args.task : undefined;
+            const fileFromFlag = typeof args.file === "string" ? args.file : undefined;
+            if (!args.type || !args.name || (!taskFromFlag && !fileFromFlag)) {
+                throw new UsageError("Usage: akm proposal new <type> <name> (--task '<task>' | --file <path>).", "MISSING_REQUIRED_ARGUMENT", "Provide the asset type, name, and exactly one of --task or --file.");
+            }
+            if (taskFromFlag && fileFromFlag) {
+                throw new UsageError("Pass exactly one of --task or --file.", "INVALID_FLAG_VALUE");
+            }
+            // `name` is flat; subdirectory placement is `--path`'s job.
+            assertFlatAssetName(String(args.name));
+            const proposedName = combineCreatePath(normalizeCreateSubPath(getStringArg(args, "path")), String(args.name));
+            const taskText = fileFromFlag ? fs.readFileSync(path.resolve(fileFromFlag), "utf8") : (taskFromFlag ?? "");
+            const timeoutMs = parsePositiveIntFlag(args["timeout-ms"], "--timeout-ms");
+            const result = await akmPropose({
+                type: String(args.type),
+                name: proposedName,
+                task: taskText,
+                engine: getStringArg(args, "engine"),
+                ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+            });
+            output("proposal-new", result);
+            if (result.ok === false) {
+                // Same reasoning as agentCommand in contribute-cli.ts: output() already
+                // ran, this is the last statement in the handler, so process.exitCode +
+                // return is equivalent without skipping any pending cleanup.
+                process.exitCode = EXIT_GENERAL;
+                return;
+            }
+        });
+    },
+});

package/dist/commands/proposal/propose.js

@@ -13,25 +13,57 @@
  * `akm reflect`. `propose_invoked` is emitted at command entry.
  */
 import fs from "node:fs";
-import { parseAssetRef } from "../../core/asset/asset-ref.js";
-import { TYPE_DIRS } from "../../core/asset/asset-spec.js";
+import { placementTypes, stashDirFor } from "../../core/asset/asset-placement.js";
+import { parseRefInput } from "../../core/asset/resolve-ref.js";
 import { resolveStashDir } from "../../core/common.js";
 import { ConfigError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
+import { redactSensitiveText } from "../../core/redaction.js";
 import { resolveStandardsContext } from "../../core/standards/resolve-standards-context.js";
-import { runAgent, } from "../../integrations/agent/index.js";
-import { resolveProcessAgentProfile } from "../../integrations/agent/config.js";
+import { deriveEntryProvenance } from "../../indexer/installations.js";
+import { resolveEngine } from "../../integrations/agent/engine-resolution.js";
 import { buildProposePrompt, parseAgentProposalPayload } from "../../integrations/agent/prompts.js";
-import { runOpencodeSdk } from "../../integrations/harnesses/opencode-sdk/index.js";
-import { baseFailureFields, enoentHintMessage, isEnoentFailure, loadAgentConfigFromDisk, resolveAgentProfile, } from "../agent/agent-support.js";
-import { createProposal, isProposalSkipped, } from "./repository.js";
-function failureEnvelope(result, type, name, fallbackReason = "non_zero_exit") {
+import { collectDispatchSensitiveValues, executeRunner } from "../../integrations/agent/runner-dispatch.js";
+import { baseFailureFields, enoentHintMessage, isEnoentFailure } from "../agent/agent-support.js";
+import { createProposal, isProposalSkipped, resolveProposalQueueTarget, } from "./repository.js";
+function failureEnvelope(result, type, name, engine, fallbackReason = "non_zero_exit") {
     return {
         ...baseFailureFields(result, fallbackReason),
+        schemaVersion: 2,
         type,
         name,
+        engine,
     };
 }
+/**
+ * WI-8.5a — the fully-qualified `bundle//conceptId` item_ref for a proposal
+ * target in `stashDir`. The conceptId is BUILT from the D-R2 static table
+ * (`deriveEntryProvenance`), never looked up, so a propose target that does not
+ * yet exist on disk still keys onto its final spelling; the bundle is the
+ * write-target stash's installation id (same derivation the index write path
+ * uses). Matches `createProposal`'s durable `proposals.ref` mint, so the entry
+ * event, the fallback ref, and the stored proposal all carry one spelling.
+ */
+function proposeItemRef(bundleId, type, name) {
+    return deriveEntryProvenance({ bundleId, componentId: bundleId, adapterId: "akm" }, type, name).itemRef;
+}
+/**
+ * The command-entry `propose_invoked` event. WI-8.5b: the ref carries the same
+ * fully-qualified item_ref the durable proposal is minted under
+ * (`proposeItemRef`), so the entry event and the stored proposal agree.
+ */
+function emitProposeInvoked(bundleId, options) {
+    appendEvent({
+        eventType: "propose_invoked",
+        ref: proposeItemRef(bundleId, options.type, options.name),
+        metadata: {
+            type: options.type,
+            name: options.name,
+            task: options.task,
+            ...(options.engine ? { engine: options.engine } : {}),
+        },
+    });
+}
 export async function akmPropose(options) {
     if (!options.type?.trim()) {
         throw new UsageError("propose: <type> is required.", "MISSING_REQUIRED_ARGUMENT");
@@ -42,53 +74,20 @@ export async function akmPropose(options) {
     if (!options.task?.trim()) {
         throw new UsageError("propose: --task is required.", "MISSING_REQUIRED_ARGUMENT");
     }
-    if (!TYPE_DIRS[options.type]) {
-        throw new UsageError(`propose: unknown asset type "${options.type}". Known types: ${Object.keys(TYPE_DIRS).sort().join(", ")}.`, "INVALID_FLAG_VALUE");
+    if (!stashDirFor(options.type)) {
+        throw new UsageError(`propose: unknown asset type "${options.type}". Known types: ${[...placementTypes()].sort().join(", ")}.`, "INVALID_FLAG_VALUE");
     }
     const stash = options.stashDir ?? resolveStashDir();
-    // 1. Always emit `propose_invoked` at entry so observers see the attempt.
-    appendEvent({
-        eventType: "propose_invoked",
-        ref: `${options.type}:${options.name}`,
-        metadata: {
-            type: options.type,
-            name: options.name,
-            task: options.task,
-            ...(options.profile ? { profile: options.profile } : {}),
-        },
-    });
-    // 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 {
-        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)
-            throw err;
-        throw err;
-    }
+    // 1. Resolve the selected engine and write target exactly once.
+    // the LLM arm uses the caller-specific plain-chat handler below.
+    const config = options.agentConfig ?? (await import("../../core/config/config.js")).loadConfig();
+    const target = resolveProposalQueueTarget(stash, config);
+    emitProposeInvoked(target.source, options);
+    const engineName = options.engine ?? config.defaults?.engine;
+    if (!engineName)
+        throw new ConfigError("propose requires --engine or defaults.engine.", "INVALID_CONFIG_FILE");
+    const runner = resolveEngine(engineName, config);
+    const profile = runner.kind === "llm" ? undefined : runner.profile;
     // 3. Build prompt.
     // Synthesize a temp draft path so opencode can write the asset content
     // directly using its file tools rather than returning JSON via stdout.
@@ -104,39 +103,51 @@ export async function akmPropose(options) {
         ...(standardsContext.trim() ? { standardsContext } : {}),
         draftFilePath: resolvedDraftPath,
     });
-    // 4. Spawn the agent.
+    // 4. Dispatch the selected engine.
     // Real agent runs use interactive mode so file tools can write the draft.
     // Injected/custom spawns still need captured stdout for JSON payload tests.
-    // Use callAi for the unified AI dispatch path (agent CLI preferred, LLM HTTP fallback).
+    // All kinds cross the unified RunnerSpec dispatch boundary.
     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 runOpencodeSdk(profile, prompt ?? "", runOptions)
-            : await runAgent(profile, prompt, runOptions);
-    }
+    const runOptions = {
+        stdio: useCustomSpawn ? "captured" : "interactive",
+        parseOutput: "text",
+        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+        ...(options.runAgentOptions ?? {}),
+    };
+    const sensitiveValues = collectDispatchSensitiveValues(runner, runOptions);
+    result = await executeRunner(runner, prompt, runOptions, {
+        llm: async (spec, llmPrompt, opts) => {
+            const { chatCompletion } = await import("../../llm/client.js");
+            const started = Date.now();
+            try {
+                const stdout = await chatCompletion(spec.connection, [{ role: "user", content: llmPrompt }], {
+                    ...(Object.hasOwn(opts, "timeoutMs") ? { timeoutMs: opts.timeoutMs } : {}),
+                });
+                return { ok: true, exitCode: 0, stdout, stderr: "", durationMs: Date.now() - started };
+            }
+            catch (error) {
+                return {
+                    ok: false,
+                    exitCode: null,
+                    stdout: "",
+                    stderr: "",
+                    durationMs: Date.now() - started,
+                    error: String(error),
+                    reason: "spawn_failed",
+                };
+            }
+        },
+    });
     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, engineName),
+                error: enoentHintMessage(profile?.bin ?? engineName),
+            };
         }
-        return failureEnvelope(result, options.type, options.name);
+        return failureEnvelope(result, options.type, options.name, engineName);
     }
     // 5. Resolve the proposal content.
     // Path A: opencode wrote the draft file — read it directly (no stdout parse).
@@ -146,7 +157,7 @@ export async function akmPropose(options) {
         const draftContent = fs.readFileSync(resolvedDraftPath, "utf8");
         fs.unlinkSync(resolvedDraftPath);
         payload = {
-            ref: `${options.type}:${options.name}`,
+            ref: proposeItemRef(target.source, options.type, options.name),
             content: draftContent,
         };
     }
@@ -156,12 +167,13 @@ export async function akmPropose(options) {
         const stdioWasInteractive = !useCustomSpawn;
         if (stdioWasInteractive && (result.stdout ?? "") === "") {
             return {
-                schemaVersion: 1,
+                schemaVersion: 2,
                 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,
+                engine: engineName,
                 exitCode: result.exitCode,
                 ...(result.stderr ? { stderr: result.stderr } : {}),
             };
@@ -171,36 +183,39 @@ export async function akmPropose(options) {
         }
         catch (err) {
             return {
-                schemaVersion: 1,
+                schemaVersion: 2,
                 ok: false,
                 reason: "parse_error",
                 error: err instanceof Error ? err.message : String(err),
                 type: options.type,
                 name: options.name,
+                engine: engineName,
                 exitCode: result.exitCode,
                 stdout: result.stdout,
                 ...(result.stderr ? { stderr: result.stderr } : {}),
             };
         }
     }
+    payload = { ...payload, content: redactSensitiveText(payload.content, sensitiveValues) };
     // 6. Insert the proposal. Note: we allow the agent's `ref` to normalise the
     // asset name (e.g. path-cleanup), but only after validating that the ref is
     // well-formed and the type still matches the requested type.
-    const expectedRef = `${options.type}:${options.name}`;
+    const expectedRef = proposeItemRef(target.source, options.type, options.name);
     let ref = expectedRef;
     if (payload.ref) {
         let parsedRef;
         try {
-            parsedRef = parseAssetRef(payload.ref);
+            parsedRef = parseRefInput(payload.ref);
         }
         catch (err) {
             return {
-                schemaVersion: 1,
+                schemaVersion: 2,
                 ok: false,
                 reason: "parse_error",
                 error: err instanceof Error ? err.message : String(err),
                 type: options.type,
                 name: options.name,
+                engine: engineName,
                 exitCode: result.exitCode,
                 stdout: result.stdout,
                 ...(result.stderr ? { stderr: result.stderr } : {}),
@@ -208,23 +223,25 @@ export async function akmPropose(options) {
         }
         if (parsedRef.type !== options.type) {
             return {
-                schemaVersion: 1,
+                schemaVersion: 2,
                 ok: false,
                 reason: "parse_error",
                 error: `Agent returned ref type ${parsedRef.type} but expected ${options.type}`,
                 type: options.type,
                 name: options.name,
+                engine: engineName,
                 exitCode: result.exitCode,
                 stdout: result.stdout,
                 ...(result.stderr ? { stderr: result.stderr } : {}),
             };
         }
-        ref = `${parsedRef.type}:${parsedRef.name}`;
+        ref = proposeItemRef(target.source, parsedRef.type, parsedRef.name);
     }
     const createInput = {
         ref,
         source: "propose",
         sourceRun: `propose-${Date.now()}`,
+        target,
         // User-initiated proposals always bypass dedup/cooldown guards — the
         // operator is explicitly asking for a new proposal.
         force: true,
@@ -241,11 +258,11 @@ export async function akmPropose(options) {
     }
     const proposal = proposalResult;
     return {
-        schemaVersion: 1,
+        schemaVersion: 2,
         ok: true,
         proposal,
         ref: proposal.ref,
-        agentProfile: profile.name,
+        engine: engineName,
         durationMs: result.durationMs,
     };
 }