akm-cli 0.6.1 → 0.7.0

package/dist/src/commands/history.js

@@ -0,0 +1,191 @@
+/**
+ * `akm history` — surfaces internal mutation/usage events for a single asset
+ * (`--ref`) or stash-wide.
+ *
+ * Event sources:
+ *   - `usage_events` SQLite table: search, show, and feedback events recorded
+ *     by the local indexer during normal CLI use.
+ *   - `events.jsonl` append-only stream (opt-in via `--include-proposals`):
+ *     proposal lifecycle events (`promoted`, `rejected`) emitted by
+ *     `akm proposal accept` / `akm proposal reject`. Use this flag to see
+ *     the full proposal review trail alongside usage events.
+ *
+ * The two sources are merged and sorted chronologically (oldest first) so
+ * consumers see a coherent lifecycle trail in a single output.
+ */
+import { parseAssetRef } from "../core/asset-ref";
+import { UsageError } from "../core/errors";
+import { readEvents } from "../core/events";
+import { closeDatabase, openDatabase } from "../indexer/db";
+import { ensureUsageEventsSchema } from "../indexer/usage-events";
+// Proposal lifecycle event types emitted by the proposal substrate (#225).
+const PROPOSAL_EVENT_TYPES = new Set(["promoted", "rejected"]);
+// ── Helpers ──────────────────────────────────────────────────────────────────
+function normalizeSince(since) {
+    // Accept "YYYY-MM-DD", "YYYY-MM-DDTHH:MM:SSZ", epoch ms, or anything Date can parse.
+    const trimmed = since.trim();
+    if (!trimmed) {
+        throw new UsageError("--since cannot be empty.", "INVALID_FLAG_VALUE");
+    }
+    // Pure-digit input → epoch milliseconds
+    if (/^\d+$/.test(trimmed)) {
+        const ms = Number.parseInt(trimmed, 10);
+        const d = new Date(ms);
+        if (Number.isNaN(d.getTime())) {
+            throw new UsageError(`Invalid --since value: ${since}`, "INVALID_FLAG_VALUE");
+        }
+        return d
+            .toISOString()
+            .replace("T", " ")
+            .replace(/\.\d+Z$/, "");
+    }
+    const parsed = new Date(trimmed);
+    if (Number.isNaN(parsed.getTime())) {
+        throw new UsageError(`Invalid --since value: ${since}. Expected ISO timestamp (e.g. 2026-04-01T00:00:00Z) or epoch ms.`, "INVALID_FLAG_VALUE");
+    }
+    // Match the "YYYY-MM-DD HH:MM:SS" format SQLite's datetime('now') stores.
+    return parsed
+        .toISOString()
+        .replace("T", " ")
+        .replace(/\.\d+Z$/, "");
+}
+function parseMetadata(raw) {
+    if (!raw)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return raw;
+    }
+}
+function toEntry(row) {
+    return {
+        id: row.id,
+        eventType: row.event_type,
+        ref: row.entry_ref,
+        entryId: row.entry_id,
+        query: row.query,
+        signal: row.signal,
+        metadata: parseMetadata(row.metadata),
+        createdAt: row.created_at,
+    };
+}
+/**
+ * Convert an ISO timestamp from events.jsonl ("2026-04-01T12:00:00.000Z")
+ * to the SQLite-style format used in HistoryEntry.createdAt
+ * ("2026-04-01 12:00:00") so entries sort consistently.
+ */
+function isoToSqliteTimestamp(ts) {
+    // Normalise to the "YYYY-MM-DD HH:MM:SS" format used by usage_events rows.
+    return ts
+        .replace("T", " ")
+        .replace(/\.\d+Z$/, "")
+        .replace("Z", "");
+}
+// ── Main ─────────────────────────────────────────────────────────────────────
+/**
+ * Read mutation/usage history. When `ref` is provided, results are filtered to
+ * that asset (validated via `parseAssetRef`). Always returns chronological
+ * order (oldest first) so consumers can display a lifecycle trail.
+ *
+ * When `includeProposals` is true, proposal lifecycle events (`promoted`,
+ * `rejected`) from events.jsonl are merged into the result set. This provides
+ * one coherent view of both usage signals and proposal review decisions.
+ */
+export async function akmHistory(options = {}) {
+    let normalizedRef;
+    if (options.ref !== undefined) {
+        const trimmed = options.ref.trim();
+        if (!trimmed) {
+            throw new UsageError("--ref cannot be empty.", "INVALID_FLAG_VALUE");
+        }
+        // Validate the ref grammar; we still query by exact entry_ref string so
+        // the user gets back exactly what they asked for.
+        parseAssetRef(trimmed);
+        normalizedRef = trimmed;
+    }
+    const sinceNormalized = options.since !== undefined ? normalizeSince(options.since) : undefined;
+    const db = options.db ?? openDatabase();
+    const ownsDb = options.db === undefined;
+    try {
+        // The schema is normally created during `akm index`; ensure it exists so
+        // `akm history` works on a freshly-initialised stash that has never been
+        // indexed (and just returns an empty list rather than an error).
+        ensureUsageEventsSchema(db);
+        const conditions = [];
+        const params = [];
+        if (normalizedRef !== undefined) {
+            conditions.push("entry_ref = ?");
+            params.push(normalizedRef);
+        }
+        if (sinceNormalized !== undefined) {
+            conditions.push("created_at >= ?");
+            params.push(sinceNormalized);
+        }
+        const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+        const sql = `SELECT id, event_type, query, entry_id, entry_ref, signal, metadata, created_at
+                 FROM usage_events ${where}
+                 ORDER BY id ASC`;
+        const rows = db.prepare(sql).all(...params);
+        const usageEntries = rows.map(toEntry);
+        // ── Proposal lifecycle events (opt-in) ────────────────────────────────
+        const sources = ["usage_events"];
+        const proposalEntries = [];
+        if (options.includeProposals === true) {
+            sources.push("events.jsonl");
+            // Convert sinceNormalized ("YYYY-MM-DD HH:MM:SS") to ISO for readEvents
+            // which uses `ts >= since` where `ts` is ISO-8601.
+            const sinceIso = sinceNormalized !== undefined ? `${sinceNormalized.replace(" ", "T")}Z` : undefined;
+            const { events } = readEvents({
+                since: sinceIso,
+                ref: normalizedRef,
+            }, options.eventsCtx);
+            // Keep only proposal lifecycle event types.
+            let counter = -1_000_000; // negative ids mark proposal-stream entries
+            for (const event of events) {
+                if (!PROPOSAL_EVENT_TYPES.has(event.eventType))
+                    continue;
+                const createdAt = event.ts ? isoToSqliteTimestamp(event.ts) : "";
+                // Skip if before `since` (readEvents already filters by ts >= since,
+                // but the isoToSqliteTimestamp conversion may introduce drift so we
+                // guard again with the normalised form).
+                if (sinceNormalized !== undefined && createdAt < sinceNormalized)
+                    continue;
+                proposalEntries.push({
+                    id: counter--,
+                    eventType: event.eventType,
+                    ref: event.ref ?? null,
+                    entryId: null,
+                    query: null,
+                    signal: null,
+                    metadata: event.metadata ?? null,
+                    createdAt,
+                });
+            }
+        }
+        // ── Merge and sort ────────────────────────────────────────────────────
+        const entries = [...usageEntries, ...proposalEntries].sort((a, b) => {
+            // Primary sort: chronological by createdAt (string compare is safe for
+            // "YYYY-MM-DD HH:MM:SS" format). Secondary sort: id ascending for ties.
+            if (a.createdAt < b.createdAt)
+                return -1;
+            if (a.createdAt > b.createdAt)
+                return 1;
+            return a.id - b.id;
+        });
+        const response = {
+            schemaVersion: 1,
+            ...(normalizedRef !== undefined ? { ref: normalizedRef } : {}),
+            ...(sinceNormalized !== undefined ? { since: sinceNormalized } : {}),
+            totalCount: entries.length,
+            entries,
+            sources,
+        };
+        return response;
+    }
+    finally {
+        if (ownsDb)
+            closeDatabase(db);
+    }
+}

package/dist/{commands → src/commands}/installed-stashes.js

@@ -333,7 +333,7 @@ function selectTargets(installed, target, all) {
         }
         throw new UsageError(`"${target}" is a local directory — it reflects your files in place. To refresh the search index, run: akm index`, "TARGET_NOT_UPDATABLE");
     }
-    throw new NotFoundError(`No matching source for target: ${target}`);
+    throw new NotFoundError(`No matching source for target: ${target}`, "SOURCE_NOT_FOUND");
 }
 function tryResolveInstalledTarget(installed, target) {
     const byId = installed.find((entry) => entry.id === target);

package/dist/src/commands/proposal.js

@@ -0,0 +1,119 @@
+/**
+ * `akm proposal {list,show,accept,reject,diff}` — review surface for the
+ * proposal substrate (#225).
+ *
+ * Each function returns a plain JSON envelope; the CLI dispatcher in
+ * `src/cli.ts` flows the result through the standard
+ * `shapeForCommand` + `formatPlain` pipeline. There is no `JSON.stringify`
+ * fallback in the output layer — every shape is registered explicitly in
+ * `src/output/shapes.ts` and `src/output/text.ts`.
+ */
+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";
+// ── Shared helpers ──────────────────────────────────────────────────────────
+function resolveStash(stashDir) {
+    if (stashDir)
+        return stashDir;
+    return resolveStashDir();
+}
+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";
+    const proposals = listProposals(stash, {
+        includeArchive,
+        status: options.status,
+        ref: options.ref,
+    });
+    return { schemaVersion: 1, totalCount: proposals.length, proposals };
+}
+export function akmProposalShow(options) {
+    const stash = resolveStash(options.stashDir);
+    const proposal = getProposal(stash, options.id);
+    return {
+        schemaVersion: 1,
+        proposal,
+        validation: validateProposal(proposal),
+    };
+}
+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);
+    // 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,
+        },
+    });
+    return {
+        schemaVersion: 1,
+        ok: true,
+        id: result.proposal.id,
+        ref: result.ref,
+        assetPath: result.assetPath,
+        proposal: result.proposal,
+    };
+}
+export function akmProposalReject(options) {
+    const stash = resolveStash(options.stashDir);
+    const existing = getProposal(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");
+    }
+    const updated = archiveProposal(stash, options.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 } : {}),
+            ...(options.reason !== undefined ? { reason: options.reason } : {}),
+        },
+    });
+    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 proposal = getProposal(stash, options.id);
+    const diff = diffProposal(stash, config, options.id, { target: options.target });
+    return {
+        schemaVersion: 1,
+        id: proposal.id,
+        ref: proposal.ref,
+        isNew: diff.isNew,
+        unified: diff.unified,
+        ...(diff.targetPath ? { targetPath: diff.targetPath } : {}),
+    };
+}
+export function akmProposalCreate(options) {
+    const stash = resolveStash(options.stashDir);
+    const proposal = createProposal(stash, {
+        ref: options.ref,
+        source: options.source,
+        ...(options.sourceRun !== undefined ? { sourceRun: options.sourceRun } : {}),
+        payload: options.payload,
+    }, options.ctx);
+    return { schemaVersion: 1, ok: true, proposal };
+}

package/dist/src/commands/propose.js

@@ -0,0 +1,171 @@
+/**
+ * `akm propose <type> <name> --task ...` — proposal-producing agent
+ * command (#226).
+ *
+ * Mirrors {@link akmReflect} but for fresh authoring. The agent receives a
+ * task description plus per-asset-type schema hints and is asked to author
+ * a brand-new asset payload. The output lands ONLY in the proposal queue.
+ *
+ * Failures use the same {@link AgentFailureReason} discriminants as
+ * `akm reflect`. `propose_invoked` is emitted at command entry.
+ */
+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 { 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);
+}
+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})`,
+        type,
+        name,
+        exitCode: result.exitCode,
+        ...(result.stdout ? { stdout: result.stdout } : {}),
+        ...(result.stderr ? { stderr: result.stderr } : {}),
+    };
+}
+export async function akmPropose(options) {
+    if (!options.type?.trim()) {
+        throw new UsageError("propose: <type> is required.", "MISSING_REQUIRED_ARGUMENT");
+    }
+    if (!options.name?.trim()) {
+        throw new UsageError("propose: <name> is required.", "MISSING_REQUIRED_ARGUMENT");
+    }
+    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");
+    }
+    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.
+    let profile;
+    try {
+        profile = resolveProfile(options);
+    }
+    catch (err) {
+        if (err instanceof ConfigError || err instanceof UsageError)
+            throw err;
+        throw err;
+    }
+    // 3. Build prompt.
+    const prompt = buildProposePrompt({
+        type: options.type,
+        name: options.name,
+        task: options.task,
+    });
+    // 4. Spawn the agent.
+    const runOptions = {
+        stdio: "captured",
+        parseOutput: "text",
+        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+        ...(options.runAgentOptions ?? {}),
+    };
+    const result = await runAgent(profile, prompt, runOptions);
+    if (!result.ok) {
+        return failureEnvelope(result, options.type, options.name);
+    }
+    // 5. Parse the structured response.
+    let payload;
+    try {
+        payload = parseAgentProposalPayload(result.stdout);
+    }
+    catch (err) {
+        return {
+            schemaVersion: 1,
+            ok: false,
+            reason: "parse_error",
+            error: err instanceof Error ? err.message : String(err),
+            type: options.type,
+            name: options.name,
+            exitCode: result.exitCode,
+            stdout: result.stdout,
+            ...(result.stderr ? { stderr: result.stderr } : {}),
+        };
+    }
+    // 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}`;
+    let ref = expectedRef;
+    if (payload.ref) {
+        let parsedRef;
+        try {
+            parsedRef = parseAssetRef(payload.ref);
+        }
+        catch (err) {
+            return {
+                schemaVersion: 1,
+                ok: false,
+                reason: "parse_error",
+                error: err instanceof Error ? err.message : String(err),
+                type: options.type,
+                name: options.name,
+                exitCode: result.exitCode,
+                stdout: result.stdout,
+                ...(result.stderr ? { stderr: result.stderr } : {}),
+            };
+        }
+        if (parsedRef.type !== options.type) {
+            return {
+                schemaVersion: 1,
+                ok: false,
+                reason: "parse_error",
+                error: `Agent returned ref type ${parsedRef.type} but expected ${options.type}`,
+                type: options.type,
+                name: options.name,
+                exitCode: result.exitCode,
+                stdout: result.stdout,
+                ...(result.stderr ? { stderr: result.stderr } : {}),
+            };
+        }
+        ref = `${parsedRef.type}:${parsedRef.name}`;
+    }
+    const createInput = {
+        ref,
+        source: "propose",
+        sourceRun: `propose-${Date.now()}`,
+        payload: {
+            content: payload.content,
+            ...(payload.frontmatter ? { frontmatter: payload.frontmatter } : {}),
+        },
+    };
+    const proposal = createProposal(stash, createInput, options.ctx);
+    return {
+        schemaVersion: 1,
+        ok: true,
+        proposal,
+        ref: proposal.ref,
+        agentProfile: profile.name,
+        durationMs: result.durationMs,
+    };
+}

package/dist/src/commands/reflect.js

@@ -0,0 +1,193 @@
+/**
+ * `akm reflect [ref]` — proposal-producing agent command (#226).
+ *
+ * Pipeline:
+ *
+ *   1. Emit `reflect_invoked` event at command entry (always, even on failure).
+ *   2. If `ref` is provided, look the asset up via the FTS index and read its
+ *      content. Pull recent feedback (`feedback` events for that ref) and
+ *      lesson-lint findings to surface as schema hints.
+ *   3. Build the prompt via {@link buildReflectPrompt}.
+ *   4. Spawn the configured agent profile via {@link runAgent}.
+ *   5. Parse the agent's stdout into a {@link AgentProposalPayload}.
+ *   6. Insert into the proposal queue via {@link createProposal} with
+ *      `source: "reflect"`.
+ *
+ * Failures are surfaced as structured envelopes carrying an
+ * {@link AgentFailureReason} discriminant. Reflect NEVER calls
+ * `writeAssetToSource` directly — the proposal queue is the only path to
+ * a committed asset, and the `accept` flow is the bridge.
+ */
+import fs from "node:fs";
+import { parseAssetRef } from "../core/asset-ref";
+import { resolveStashDir } from "../core/common";
+import { loadConfig } from "../core/config";
+import { ConfigError, UsageError } from "../core/errors";
+import { appendEvent, readEvents } from "../core/events";
+import { lintLessonContent } from "../core/lesson-lint";
+import { createProposal } from "../core/proposals";
+import { lookup } from "../indexer/indexer";
+import { parseAgentConfig, requireAgentProfile, runAgent, } from "../integrations/agent";
+import { buildReflectPrompt, parseAgentProposalPayload } from "../integrations/agent/prompts";
+const MAX_FEEDBACK_LINES = 10;
+const MAX_GLOBAL_FEEDBACK_LINES = 20;
+/**
+ * Pull recent `feedback` events from events.jsonl. When `ref` is present we
+ * scope to that asset; otherwise we surface the most recent feedback across
+ * all assets so `akm reflect` can operate in a general "review recent
+ * signals" mode. Best-effort — a missing or empty events stream returns `[]`.
+ */
+function readRecentFeedback(ref) {
+    try {
+        const result = readEvents({ type: "feedback", ...(ref ? { ref } : {}) });
+        const lines = [];
+        const limit = ref ? MAX_FEEDBACK_LINES : MAX_GLOBAL_FEEDBACK_LINES;
+        for (const event of result.events.slice(-limit)) {
+            const md = (event.metadata ?? {});
+            const signal = typeof md.signal === "string" ? md.signal : "?";
+            const note = typeof md.note === "string" ? md.note : typeof md.reason === "string" ? md.reason : "";
+            const details = note ? `[${signal}] ${note}` : `[${signal}]`;
+            lines.push(!ref && event.ref ? `${event.ref} ${details}` : details);
+        }
+        return lines;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Build schema/lint hints for the prompt. For lesson refs, run the lesson
+ * lint over the current content and surface any findings — they are a
+ * concrete starting point for the agent's revision.
+ */
+function buildSchemaHints(type, content) {
+    if (!content)
+        return [];
+    if (type !== "lesson")
+        return [];
+    const report = lintLessonContent(content, "reflect");
+    return report.findings.map((f) => `[${f.kind}] ${f.message}`);
+}
+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);
+}
+function failureEnvelope(result, ref, fallbackReason = "non_zero_exit") {
+    const reason = result.reason ?? fallbackReason;
+    return {
+        schemaVersion: 1,
+        ok: false,
+        reason,
+        error: result.error ?? `agent failure (${reason})`,
+        ...(ref ? { ref } : {}),
+        exitCode: result.exitCode,
+        ...(result.stdout ? { stdout: result.stdout } : {}),
+        ...(result.stderr ? { stderr: result.stderr } : {}),
+    };
+}
+export async function akmReflect(options = {}) {
+    const stash = options.stashDir ?? resolveStashDir();
+    // 1. Always emit `reflect_invoked` at command entry — observers see the
+    // attempt regardless of downstream success/failure.
+    appendEvent({
+        eventType: "reflect_invoked",
+        ...(options.ref ? { ref: options.ref } : {}),
+        metadata: {
+            ...(options.task ? { task: options.task } : {}),
+            ...(options.profile ? { profile: options.profile } : {}),
+        },
+    });
+    // 2. Resolve target asset content (if a ref is supplied).
+    let assetContent;
+    let parsedRef;
+    if (options.ref) {
+        parsedRef = parseAssetRef(options.ref);
+        try {
+            const entry = await lookup(parsedRef);
+            if (entry?.filePath && fs.existsSync(entry.filePath)) {
+                assetContent = fs.readFileSync(entry.filePath, "utf8");
+            }
+        }
+        catch {
+            // Index miss is non-fatal — the agent can still propose a fresh asset.
+        }
+    }
+    // 3. Resolve agent profile. ConfigError surfaces as a thrown error so the
+    // CLI dispatcher renders the standard envelope.
+    let profile;
+    try {
+        profile = resolveProfile(options);
+    }
+    catch (err) {
+        if (err instanceof ConfigError || err instanceof UsageError)
+            throw err;
+        throw err;
+    }
+    // 4. Build the prompt.
+    const feedback = readRecentFeedback(options.ref);
+    const schemaHints = buildSchemaHints(parsedRef?.type ?? "", assetContent);
+    const prompt = buildReflectPrompt({
+        ...(options.ref ? { ref: options.ref } : {}),
+        ...(parsedRef?.type ? { type: parsedRef.type } : {}),
+        ...(parsedRef?.name ? { name: parsedRef.name } : {}),
+        ...(assetContent !== undefined ? { assetContent } : {}),
+        ...(feedback.length > 0 ? { feedback } : {}),
+        ...(schemaHints.length > 0 ? { schemaHints } : {}),
+        ...(options.task ? { task: options.task } : {}),
+    });
+    // 5. Spawn the agent. Force captured stdio + JSON parse so we can extract
+    // the structured payload without confusing terminal control codes.
+    const runOptions = {
+        stdio: "captured",
+        parseOutput: "text",
+        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+        ...(options.runAgentOptions ?? {}),
+    };
+    const result = await runAgent(profile, prompt, runOptions);
+    if (!result.ok) {
+        return failureEnvelope(result, options.ref);
+    }
+    // 6. Parse stdout into a proposal payload.
+    let payload;
+    try {
+        payload = parseAgentProposalPayload(result.stdout);
+    }
+    catch (err) {
+        return {
+            schemaVersion: 1,
+            ok: false,
+            reason: "parse_error",
+            error: err instanceof Error ? err.message : String(err),
+            ...(options.ref ? { ref: options.ref } : {}),
+            exitCode: result.exitCode,
+            stdout: result.stdout,
+            ...(result.stderr ? { stderr: result.stderr } : {}),
+        };
+    }
+    // 7. Create the proposal. The proposal queue is the ONLY thing reflect
+    // writes — promotion to a real asset is gated by `akm proposal accept`.
+    const createInput = {
+        ref: payload.ref,
+        source: "reflect",
+        sourceRun: `reflect-${Date.now()}`,
+        payload: {
+            content: payload.content,
+            ...(payload.frontmatter ? { frontmatter: payload.frontmatter } : {}),
+        },
+    };
+    const proposal = createProposal(stash, createInput, options.ctx);
+    return {
+        schemaVersion: 1,
+        ok: true,
+        proposal,
+        ref: proposal.ref,
+        agentProfile: profile.name,
+        durationMs: result.durationMs,
+    };
+}