akm-cli 0.9.18 → 0.9.19-alpha.1

package/dist/commands/improve/eligibility.js

@@ -4,6 +4,7 @@
 /** The refs an improve run may consider, read from the index, and the small predicates over them. */
 import fs from "node:fs";
 import path from "node:path";
+import { parseBundleRef } from "../../core/asset/asset-ref.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { conceptIdFromTypeName, parseRefInput, resolveRef, typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
 import { loadConfig } from "../../core/config/config.js";
@@ -109,6 +110,18 @@ export function dedupeRefs(refs) {
         return true;
     });
 }
+/**
+ * The bundle an improve run reads candidates from and files proposals into: its
+ * write target, the source rooted at `stashDir` (else the working bundle).
+ * Reflect reads a candidate from its owning bundle but the proposal lands in
+ * the write target, so a candidate owned by any other bundle would be read from
+ * one bundle and filed in another (#1000).
+ */
+function runBundleIdOf(sources, installations, stashDir) {
+    const root = stashDir === undefined ? undefined : path.resolve(stashDir);
+    const index = sources.findIndex((source) => root === undefined ? source.isDefault === true : path.resolve(source.path) === root);
+    return installations[index]?.id;
+}
 export async function collectEligibleRefs(scope, stashDir, improveProfile, config) {
     return collectEligibleRefsFromIndex(scope, stashDir, improveProfile, false, config);
 }
@@ -135,6 +148,9 @@ async function collectEligibleRefsFromIndex(scope, stashDir, improveProfile, rea
         return empty();
     const installations = deriveInstallations(sources);
     const writableBundleIds = deriveWritableBundleIds(sources);
+    const runBundleId = runBundleIdOf(sources, installations, stashDir);
+    // Candidates come from the write target alone, and only while it is writable.
+    const isCandidateBundle = (bundleId) => bundleId !== undefined && bundleId === runBundleId && writableBundleIds.has(bundleId);
     const ready = {
         status: "ready",
         reason: readOnly ? "loaded a non-mutating point-in-time copy of the existing index" : "loaded the prepared index",
@@ -152,20 +168,34 @@ async function collectEligibleRefsFromIndex(scope, stashDir, improveProfile, rea
             return empty(missing);
         if (scope.mode === "ref" && scope.value) {
             const entriesByItemRef = new Map(getAllEntries(db).map((entry) => [entry.itemRef, entry]));
-            const resolved = resolveRef(scope.value, {
-                defaultBundle: config.defaultBundle,
-                bundles: installations.map((installation) => ({
-                    id: installation.id,
-                    hasConcept: (conceptId) => entriesByItemRef.has(`${installation.id}//${conceptId}`),
-                })),
-            });
+            let resolved;
+            try {
+                resolved = resolveRef(scope.value, {
+                    defaultBundle: config.defaultBundle,
+                    bundles: installations.map((installation) => ({
+                        id: installation.id,
+                        hasConcept: (conceptId) => entriesByItemRef.has(`${installation.id}//${conceptId}`),
+                    })),
+                    ...(runBundleId ? { only: runBundleId } : {}),
+                });
+            }
+            catch (error) {
+                if (!(error instanceof NotFoundError) || !runBundleId)
+                    throw error;
+                // Name the bundle that owns the ref; a typo or an unindexed ref keeps the default advice.
+                const { conceptId } = parseBundleRef(scope.value);
+                const owner = installations.find((installation) => installation.id !== runBundleId && entriesByItemRef.has(`${installation.id}//${conceptId}`))?.id;
+                if (!owner)
+                    throw error;
+                throw new NotFoundError(error.message, error.code, `"${conceptId}" is in bundle "${owner}"; this run improves bundle "${runBundleId}" only. Run \`akm improve ${owner}//${conceptId}\` (or pass \`--bundle ${owner}\`).`);
+            }
             const indexed = entriesByItemRef.get(`${resolved.bundle}//${resolved.conceptId}`);
             if (!indexed?.bundleId || !indexed.conceptId || !fs.existsSync(indexed.filePath)) {
                 if (await findAssetFilePath(scope.value, stashDir))
                     return empty(ready);
                 throw new NotFoundError(`Asset not found in the selected writable source: ${scope.value}`, "ASSET_NOT_FOUND");
             }
-            if (!writableBundleIds.has(indexed.bundleId))
+            if (!isCandidateBundle(indexed.bundleId))
                 return empty(ready);
             const isMemory = indexed.entry.type === "memory";
             return {
@@ -180,7 +210,7 @@ async function collectEligibleRefsFromIndex(scope, stashDir, improveProfile, rea
                 indexSnapshot: ready,
             };
         }
-        const entries = getAllEntries(db, scope.mode === "type" ? scope.value : undefined).filter((indexed) => writableBundleIds.has(indexed.bundleId));
+        const entries = getAllEntries(db, scope.mode === "type" ? scope.value : undefined).filter((indexed) => isCandidateBundle(indexed.bundleId));
         const planned = new Map();
         const strategyFiltered = new Map();
         let memoryEligible = 0;

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

@@ -19,7 +19,7 @@ import { collectEngineCredentialValues } from "../../integrations/agent/engine-r
 import { probeLlmReachable } from "../../llm/client.js";
 import { getOutputMode } from "../../output/context.js";
 import { deliverRendered } from "../../output/html-render.js";
-import { akmImprove, resolveImproveReadSource } from "./improve.js";
+import { akmImprove, IMPROVE_TARGET_FLAG, resolveImproveReadSource } from "./improve.js";
 import { runImproveReportQuery } from "./improve-report.js";
 import { buildImproveRunId, recordImproveRunResult, recordTerminatedImproveRun, } from "./improve-result-file.js";
 import { runImproveSession } from "./improve-session.js";
@@ -209,8 +209,11 @@ export const improveCommand = defineCommand({
             description: "Alias for --dry-run (#947). Sets the exact same internal flag; use it when previewing resolved process -> engine -> model routing (plan.processes) rather than checking what would write.",
             default: false,
         },
-        bundle: { type: "string", description: "Override the write target for accepted proposals" },
-        limit: { type: "string", description: "Maximum number of assets to process (highest utility first)" },
+        bundle: {
+            type: "string",
+            description: "Bundle to improve and write proposals to (default: defaultWriteTarget, else the working bundle); only its assets are planned",
+        },
+        limit: { type: "string", description: "Maximum number of assets to process (highest salience first)" },
         "timeout-ms": {
             type: "string",
             description: "Wall-clock budget for the entire run in milliseconds (default: 7200000 = 2 hours)",
@@ -227,7 +230,7 @@ export const improveCommand = defineCommand({
         },
         "skip-if-locked": {
             type: "boolean",
-            description: "If another improve run already holds the lock, skip gracefully (exit 0) instead of failing with 'already running' (exit 78). Use for high-frequency scheduled runs so they don't pile up failures while a longer run is in progress.",
+            description: "If another improve run already holds the lock, skip gracefully (exit 0) instead of failing with 'already running' (exit 75). Use for high-frequency scheduled runs so they don't pile up failures while a longer run is in progress.",
             default: false,
         },
         "require-engines": {
@@ -286,8 +289,8 @@ export const improveCommand = defineCommand({
             const writeTarget = dryRun
                 ? undefined
                 : scopeRef
-                    ? resolveMutationTarget(effectiveConfig, scopeRef, targetArg).target
-                    : resolveWriteTarget(effectiveConfig, targetArg);
+                    ? resolveMutationTarget(effectiveConfig, scopeRef, targetArg, { flag: IMPROVE_TARGET_FLAG }).target
+                    : resolveWriteTarget(effectiveConfig, targetArg, { flag: IMPROVE_TARGET_FLAG });
             // Every model-backed process resolves before any side effect; a dry run
             // never dispatches, so it tolerates every process being disabled.
             const resolvedPlan = resolveImprovePlan(strategyArg, effectiveConfig, { allowAllDisabled: Boolean(dryRun) });

package/dist/commands/improve/improve.js

@@ -19,7 +19,7 @@ import { redactSensitiveText } from "../../core/redaction.js";
 import { openStateDatabase } from "../../core/state-db.js";
 import { info, warn, warnVerbose } from "../../core/warn.js";
 import { beginWriteProvenance, relativeWrittenPath } from "../../core/write-provenance.js";
-import { resolveWritable, resolveWriteTarget } from "../../core/write-source.js";
+import { resolveWorkingStashTarget, resolveWritable, resolveWriteTarget } from "../../core/write-source.js";
 import { ensureIndex } from "../../indexer/ensure-index.js";
 import { indexWrittenAssets } from "../../indexer/index-written-assets.js";
 import { akmIndex } from "../../indexer/indexer.js";
@@ -268,17 +268,24 @@ function describeRunWrittenPaths(setup, writtenPaths) {
     }
     return [...described].sort();
 }
+/** How `akm improve` spells its destination flag: the shared target resolvers name it in their errors. */
+export const IMPROVE_TARGET_FLAG = "--bundle";
 /**
  * The source a dry run (or `--show-prompt`) inspects, without adapting it into
  * a write target.
  */
 export function resolveImproveReadSource(config, scopedRef, explicitTarget, fallbackStashDir) {
     if (scopedRef?.origin && explicitTarget && scopedRef.origin !== explicitTarget) {
-        throw new UsageError(`Qualified ref bundle "${scopedRef.origin}" conflicts with --target "${explicitTarget}".`, "INVALID_FLAG_VALUE", `Drop --target or use --target ${scopedRef.origin}.`);
+        throw new UsageError(`Qualified ref bundle "${scopedRef.origin}" conflicts with ${IMPROVE_TARGET_FLAG} "${explicitTarget}".`, "INVALID_FLAG_VALUE", `Drop ${IMPROVE_TARGET_FLAG} or use ${IMPROVE_TARGET_FLAG} ${scopedRef.origin}.`);
     }
     const selector = scopedRef?.origin ?? explicitTarget ?? config.defaultWriteTarget;
     if (!selector && fallbackStashDir)
         return { source: { name: "stash", path: fallbackStashDir } };
+    if (!selector && process.env.AKM_BUNDLE_DIR?.trim()) {
+        // A live run's working bundle starts from AKM_BUNDLE_DIR (`resolveWorkingStashTarget`), so its preview does too.
+        const { source } = resolveWorkingStashTarget(config, { requireWritable: false });
+        return { source: { name: source.name, path: source.path } };
+    }
     const configuredSelector = selector ?? config.defaultBundle;
     if (configuredSelector) {
         const entry = bundlesToSourceEntries(config)?.find((source) => source.name === configuredSelector);
@@ -339,10 +346,12 @@ function resolveImproveRunSetup(options) {
     const writeTarget = options.dryRun
         ? undefined
         : scopedRef?.origin
-            ? resolveMutationTarget(config, scopedRef, options.writeTarget?.source.name ?? options.target).target
+            ? resolveMutationTarget(config, scopedRef, options.writeTarget?.source.name ?? options.target, {
+                flag: IMPROVE_TARGET_FLAG,
+            }).target
             : (options.writeTarget ??
                 (options.target || config.defaultWriteTarget || !options.stashDir
-                    ? resolveWriteTarget(config, options.target)
+                    ? resolveWriteTarget(config, options.target, { flag: IMPROVE_TARGET_FLAG })
                     : {
                         source: { kind: "filesystem", name: "stash", path: options.stashDir },
                         config: { type: "filesystem", name: "stash", path: options.stashDir, writable: true },

package/dist/commands/improve/ledger.js

@@ -9,9 +9,9 @@
 import fs from "node:fs";
 import { getStateDbPath, withImmediateTransaction, withStateDb } from "../../core/state-db.js";
 import { warn } from "../../core/warn.js";
-import { isLedgerBlocked, listImproveLedgerRows, PAIR_PASS_LEDGER_SOURCE, recordImproveLedger, } from "../../storage/repositories/improve-ledger-repository.js";
+import { isContentDrivenRow, isLedgerBlocked, listImproveLedgerRows, PAIR_PASS_LEDGER_SOURCE, recordImproveLedger, } from "../../storage/repositories/improve-ledger-repository.js";
 import { openSqliteReadSnapshot } from "../../storage/sqlite-read-snapshot.js";
-export { isLedgerBlocked, PAIR_PASS_LEDGER_SOURCE };
+export { isContentDrivenRow, isLedgerBlocked, PAIR_PASS_LEDGER_SOURCE };
 /** An improve candidate's durable state key: its index item_ref, else its conceptId. */
 export function stateKey(ref, itemRef) {
     return itemRef ?? ref;

package/dist/commands/improve/loop-stages.js

@@ -136,6 +136,8 @@ async function runLoopReflectPass(planned, env, tally) {
     if (reflectErrors.length > 0)
         tally.reflectsWithErrorContext++;
     const budgetMs = env.remainingBudgetMs();
+    // `planned` was selected from the run's write target alone (eligibility.ts), so the
+    // `target` below is the bundle `planned.itemRef` is read from and the proposal is filed in.
     const reflectArgs = {
         ref: planned.ref,
         ...(planned.itemRef ? { itemRef: planned.itemRef } : {}),

package/dist/commands/improve/preparation.js

@@ -793,7 +793,7 @@ function fetchRetrievalSignals(options, signalFiltered, noFeedbackCandidates, ev
         // usage_events live in state.db, entries in index.db.
         withRunState(eventsCtx, persist, (stateDb) => {
             if (countUsageEventsByType(stateDb, "show") === 0) {
-                warn("Warning: show events not yet in usage_events — zero-feedback fallback will match only search-retrieved assets.");
+                warn("Warning: show events not yet in usage_events — the retrieval scope will match only search-retrieved assets.");
             }
             const refs = [...new Set([...signalFiltered, ...noFeedbackCandidates].map((r) => r.ref))];
             out.retrievalCounts = getRetrievalCounts(indexDb, stateDb, refs, { sourceName: options.sourceName });

package/dist/commands/improve/reflect.js

@@ -1036,7 +1036,7 @@ async function finalizeReflectProposal(args) {
         payload: { content: payload.content, ...(Object.keys(frontmatter).length > 0 ? { frontmatter } : {}) },
         ...(typeof payload.confidence === "number" ? { confidence: payload.confidence } : {}),
         ...(options.eligibilitySource ? { eligibilitySource: options.eligibilitySource } : {}),
-        ...(options.itemRef ? { attemptedRefs: [options.itemRef] } : {}),
+        ...(options.itemRef ? { itemRef: options.itemRef, attemptedRefs: [options.itemRef] } : {}),
     }, reviewReasons.length > 0
         ? {
             review: {

package/dist/commands/improve/stage.js

@@ -158,18 +158,20 @@ export function buildJudgePrompt(lessonContent, sourceContent, similarLessons) {
         "Score this lesson on each criterion from 1 (poor) to 5 (excellent):",
         "1. NOVELTY: Does the lesson add information not already present in the source asset?",
         "2. NON-REDUNDANCY: Is this lesson meaningfully different from what the source already says?",
+        "3. GROUNDING: Is the lesson about what the source asset is about? Score 1-2 only if it is about a different subject than the source; 3 if it is on the source's subject but goes beyond or corrects what the source says (it may draw on feedback you are not shown); 4-5 if the source supports it. A lesson may generalize the source's point.",
         "",
         "Source asset content:",
         "```",
-        sourceContent.slice(0, 2000),
+        // The window distill generates from (buildDistillPrompt): grounding can reject, so the judge reads all of it.
+        sourceContent.slice(0, 3000),
         "```",
     ];
     if (similarLessons && similarLessons.length > 0) {
-        lines.push("", "Existing similar lessons (top-3 by similarity). Rate lower if the proposed lesson is substantially similar to any of these:");
+        lines.push("", "Existing similar lessons (top-3 by similarity). Rate NOVELTY and NON-REDUNDANCY lower if the proposed lesson is substantially similar to any of these:");
         for (const sl of similarLessons)
             lines.push(`\nExisting lesson ref: ${sl.ref}`, "```", sl.content.slice(0, 500), "```");
     }
-    lines.push("", "Proposed lesson content:", "```", lessonContent.slice(0, 1000), "```", "", 'Return ONLY valid JSON, no prose: {"scores": {"novelty": <1-5 integer>, "nonRedundancy": <1-5 integer>}, "reason": "<one sentence>"}');
+    lines.push("", "Proposed lesson content:", "```", lessonContent.slice(0, 1000), "```", "", 'Return ONLY valid JSON, no prose: {"scores": {"novelty": <1-5 integer>, "nonRedundancy": <1-5 integer>, "grounding": <1-5 integer>}, "reason": "<one sentence>"}');
     return lines.join("\n");
 }
 function boundedDocument(content, maxChars = 6000) {
@@ -229,12 +231,26 @@ export function buildReflectJudgePrompt(candidateContent, sourceContent, feedbac
         'Return ONLY valid JSON, no prose: {"scores": {"feedbackAlignment": <1-5 integer>, "preservation": <1-5 integer>, "quality": <1-5 integer>}, "reason": "<one sentence>"}',
     ].join("\n");
 }
-const LESSON_JUDGE_CRITERIA = ["novelty", "nonRedundancy"];
+/**
+ * `grounding` is scored with the other lesson criteria but left out of their
+ * mean: a lesson about a different subject than its source reads as novel and
+ * non-redundant, so the mean would pass it (or, in the review band, mint it as
+ * a pending proposal). A score of {@link UNGROUNDED_MAX_SCORE} or less is a
+ * rejection whatever the mean says (#999). Only a different subject scores that
+ * low. A lesson that goes beyond or corrects its source is on its subject:
+ * distill folds feedback into the lesson, and the judge is never shown it. A
+ * contradiction of the source is the optional fidelity check's to send to a
+ * human (`judgeAndQueue` in distill.ts), so the rubric must not pre-empt it.
+ */
+const GROUNDING_CRITERION = "grounding";
+const UNGROUNDED_MAX_SCORE = 2;
+const LESSON_JUDGE_CRITERIA = ["novelty", "nonRedundancy", GROUNDING_CRITERION];
 const REFLECT_JUDGE_CRITERIA = ["feedbackAlignment", "preservation", "quality"];
 /**
- * Read a judge response: the per-criterion shape (averaged here) or the older
- * `{"score"}` shape. Only the expected criteria are read; any missing or
- * out-of-range (1..5) value is a parse failure, extra keys are ignored.
+ * Read a judge response: the per-criterion shape (averaged here, `grounding`
+ * aside) or the older `{"score"}` shape. Only the expected criteria are read;
+ * any missing or out-of-range (1..5) value is a parse failure, extra keys are
+ * ignored.
  */
 function parseJudgeResponse(raw, keys) {
     const parsed = parseEmbeddedJsonResponse(raw);
@@ -253,7 +269,10 @@ function parseJudgeResponse(raw, keys) {
                 return undefined;
             criteria[key] = value;
         }
-        return { score: Object.values(criteria).reduce((a, b) => a + b, 0) / keys.length, reason, criteria };
+        const averaged = Object.entries(criteria)
+            .filter(([key]) => key !== GROUNDING_CRITERION)
+            .map(([, value]) => value);
+        return { score: averaged.reduce((a, b) => a + b, 0) / averaged.length, reason, criteria };
     }
     return inRange(parsed.score) ? { score: parsed.score, reason } : undefined;
 }
@@ -276,7 +295,8 @@ function judgeResponseSchema(keys) {
 /**
  * The quality judge. Fails closed: no runner, an unparseable verdict or a
  * provider failure never passes content. Bands: >= 3.5 pass, 2.5-3.5 review,
- * < 2.5 reject. Temperature is pinned to 0 so verdicts do not flip.
+ * < 2.5 reject; a `grounding` score of {@link UNGROUNDED_MAX_SCORE} or less
+ * rejects whatever the mean is. Temperature is pinned to 0 so verdicts do not flip.
  */
 async function runQualityJudge(feature, config, prompt, keys, chat, options) {
     const resolved = !options.runnerSelectionFrozen && !options.llmRunner
@@ -309,6 +329,15 @@ async function runQualityJudge(feature, config, prompt, keys, chat, options) {
     if (!parsed)
         return { pass: false, score: -1, reason: "judge parse failed — routed to review", reviewNeeded: true };
     const { score, reason, criteria } = parsed;
+    const grounding = criteria?.[GROUNDING_CRITERION];
+    if (criteria && grounding !== undefined && grounding <= UNGROUNDED_MAX_SCORE) {
+        return {
+            pass: false,
+            score,
+            reason: `Off-subject for its source (grounding ${grounding}/5): ${reason}`,
+            criteria,
+        };
+    }
     const verdict = score >= 3.5 ? { pass: true } : score >= 2.5 ? { pass: false, reviewNeeded: true } : { pass: false };
     return { ...verdict, score, reason, ...(criteria ? { criteria } : {}) };
 }

package/dist/commands/proposal/diff-format.js

@@ -48,3 +48,24 @@ export function formatNewAssetDiff(ref, content) {
     }
     return lines.join("\n");
 }
+/**
+ * Render the all-removals diff for a retire proposal (#997): the file its
+ * accept archives, line by line, and nothing added. Padding the proposed side
+ * with an empty string, as {@link formatUnifiedDiff} does, reads as "the whole
+ * file replaced by one blank line" — a retirement reviewed as data loss.
+ * `existing` is `null` when the retired file is already gone.
+ */
+export function formatRetireDiff(ref, existing, successorRef) {
+    const destination = `+++ /dev/null (retired: archived${successorRef ? `; successor ${successorRef}` : ""})`;
+    if (existing === null)
+        return [`--- ${ref} (missing)`, destination].join("\n");
+    const removed = existing.split("\n");
+    if (removed[removed.length - 1] === "")
+        removed.pop(); // the newline ending the file is not a line of its own
+    return [
+        `--- ${ref} (existing)`,
+        destination,
+        `@@ 1,${removed.length} 0,0 @@`,
+        ...removed.map((line) => `-${line}`),
+    ].join("\n");
+}

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

@@ -25,7 +25,8 @@ import { resolveImproveExecution } from "../improve/execution.js";
 import { extractCommand } from "../improve/extract-cli.js";
 import { resolveImproveStrategy } from "../improve/improve-strategies.js";
 import { drainProposals } from "./drain.js";
-import { akmProposalAccept, akmProposalDiff, akmProposalList, akmProposalReject, akmProposalRevert, akmProposalShow, bulkAdjudicateProposals, } from "./proposal.js";
+import { akmProposalAccept, akmProposalDiff, akmProposalList, akmProposalReject, akmProposalReopen, akmProposalRevert, akmProposalShow, bulkAdjudicateProposals, } from "./proposal.js";
+import { proposalWaitingSince } from "./proposal-types.js";
 import { proposeCommand } from "./propose-cli.js";
 export function mergeProposalDrainNotices(resolutionNotices, dispatchNotices) {
     const byKey = new Map();
@@ -128,7 +129,7 @@ const proposalAcceptCommand = defineJsonCommand({
         },
         "older-than": {
             type: "string",
-            description: "When bulk-accepting, only accept proposals created more than this many days ago (e.g. '7' for 7 days).",
+            description: "When bulk-accepting, only accept proposals created (or last reopened) more than this many days ago (e.g. '7' for 7 days).",
         },
         "dry-run": {
             type: "boolean",
@@ -207,7 +208,7 @@ const proposalRejectCommand = defineJsonCommand({
         },
         "older-than": {
             type: "string",
-            description: "When bulk-rejecting, only reject proposals created more than this many days ago (e.g. '7' for 7 days).",
+            description: "When bulk-rejecting, only reject proposals created (or last reopened) more than this many days ago (e.g. '7' for 7 days).",
         },
         "dry-run": {
             type: "boolean",
@@ -230,7 +231,7 @@ const proposalRejectCommand = defineJsonCommand({
         // F-6 / #393: Bulk-reject when --generator is provided without a positional id.
         if (generator && !args.id) {
             const { confirmDestructive } = await import("../../cli/confirm.js");
-            const confirmed = await confirmDestructive(`Bulk-reject all matching proposals from generator "${generator}"? This cannot be undone.`, { yes: args.yes === true || args["dry-run"] === true });
+            const confirmed = await confirmDestructive(`Bulk-reject all matching proposals from generator "${generator}"? A rejection can be undone with akm proposal reopen.`, { yes: args.yes === true || args["dry-run"] === true });
             if (!confirmed) {
                 process.stderr.write("Aborted.\n");
                 return;
@@ -252,7 +253,7 @@ const proposalRejectCommand = defineJsonCommand({
             throw new UsageError("Usage: akm proposal reject <id> --reason '<reason>'  OR  akm proposal reject --generator <generator> --reason '<reason>'", "MISSING_REQUIRED_ARGUMENT");
         }
         const { confirmDestructive } = await import("../../cli/confirm.js");
-        const confirmed = await confirmDestructive(`Reject proposal "${args.id}"? This cannot be undone.`, {
+        const confirmed = await confirmDestructive(`Reject proposal "${args.id}"? A rejection can be undone with akm proposal reopen.`, {
             yes: args.yes === true,
         });
         if (!confirmed) {
@@ -267,6 +268,41 @@ const proposalRejectCommand = defineJsonCommand({
         output("proposal-reject", result);
     },
 });
+// `proposal reopen` (#997): the undo a rejection lacked. Unlike `reject` it is
+// reversible (reject again), so it asks no confirmation.
+const proposalReopenCommand = defineJsonCommand({
+    meta: {
+        name: "reopen",
+        description: "Reopen rejected proposals: move them back to pending, keeping the rejection in their history. " +
+            "Takes full proposal ids; refused (and none reopened) if any is not rejected or its target changed since it was created.",
+    },
+    args: {
+        id: {
+            type: "positional",
+            description: "Rejected proposal id (full uuid); repeat it to reopen several at once",
+            required: true,
+        },
+        reason: {
+            type: "string",
+            description: "Why the rejection is being undone (kept in the proposal's review history)",
+        },
+        queue: { type: "string", description: "Select the proposal queue by source name" },
+    },
+    async run({ args }) {
+        // citty keeps every positional token in `_`, though it declares only `id`.
+        const ids = (Array.isArray(args._) && args._.length > 0 ? args._ : [args.id]).map(String);
+        const reason = typeof args.reason === "string" && args.reason.trim() ? args.reason.trim() : undefined;
+        const results = await akmProposalReopen({
+            ids,
+            queue: args.queue,
+            ...(reason !== undefined ? { reason } : {}),
+        });
+        if (results.length === 1)
+            output("proposal-reopen", results[0]);
+        else
+            output("proposal-reopen-batch", { reopened: results.length, results });
+    },
+});
 const proposalDiffCommand = defineJsonCommand({
     meta: { name: "diff", description: "Show the diff for a proposal (accepts full UUID, UUID prefix, or asset ref)" },
     args: {
@@ -356,7 +392,7 @@ const proposalDrainCommand = defineJsonCommand({
         },
         "older-than": {
             type: "string",
-            description: "Only consider proposals created more than this many days ago.",
+            description: "Only consider proposals created (or last reopened) more than this many days ago.",
         },
         promote: {
             type: "boolean",
@@ -410,10 +446,11 @@ const proposalDrainCommand = defineJsonCommand({
             const now = Date.now();
             excludeIds = new Set(listProposals(stashDir, { status: "pending" })
                 // Fail SAFE: exclude a proposal when its age cannot be computed
-                // (NaN createdAt) OR it is too fresh. An unparseable createdAt must
-                // never be treated as old enough to drain/promote.
+                // (NaN date) OR it is too fresh. An unparseable date must never be
+                // treated as old enough to drain/promote. Age counts from creation,
+                // or from the last reopen (#997) — a proposal just reopened is fresh.
                 .filter((proposal) => {
-                const age = now - new Date(proposal.createdAt).getTime();
+                const age = now - new Date(proposalWaitingSince(proposal)).getTime();
                 return Number.isNaN(age) || age < olderThanMs;
             })
                 .map((proposal) => proposal.id));
@@ -480,7 +517,7 @@ const proposalDrainCommand = defineJsonCommand({
 export const proposalCommand = defineGroupCommand({
     meta: {
         name: "proposal",
-        description: "Manage the proposal queue: list, show, diff, accept, reject, revert, extract, new, drain",
+        description: "Manage the proposal queue: list, show, diff, accept, reject, reopen, revert, extract, new, drain",
     },
     // The group declared `--queue`/`--status`/`--ref`/`--type` only so the bare
     // form could act as `proposal list`. That form is gone (see below), and
@@ -493,6 +530,7 @@ export const proposalCommand = defineGroupCommand({
         diff: proposalDiffCommand,
         accept: proposalAcceptCommand,
         reject: proposalRejectCommand,
+        reopen: proposalReopenCommand,
         revert: proposalRevertCommand,
         drain: proposalDrainCommand,
         extract: extractCommand,

package/dist/commands/proposal/proposal-types.js

@@ -36,6 +36,17 @@ export function isValidProposalSource(source) {
 export function isAutomatedProposalSource(source) {
     return AUTOMATED_PROPOSAL_SOURCES.includes(source);
 }
+/**
+ * When a pending proposal's wait for review began: its last reopen (#997), else
+ * its creation. Every age-based sweep — retention expiry, and `--older-than` on
+ * bulk accept/reject and on `drain` — counts from here, so a proposal just put
+ * back in the queue is not swept as if it had been waiting since it was first
+ * created (a scheduled `drain --older-than 7 --promote` would otherwise take
+ * it at once).
+ */
+export function proposalWaitingSince(proposal) {
+    return proposal.reviewHistory?.at(-1)?.reopenedAt ?? proposal.createdAt;
+}
 /** A pending or accepted proposal whose primary change deletes its target (a consolidate retire proposal, alpha.9). */
 export function isRetireProposal(proposal) {
     return proposal.changes[0]?.op === "delete";

package/dist/commands/proposal/proposal.js

@@ -2,7 +2,7 @@
 // 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
+ * `akm proposal {list,show,accept,reject,reopen,diff}` — review surface for the
  * proposal substrate (#225).
  *
  * Each function returns a plain JSON envelope; the CLI dispatcher in
@@ -13,10 +13,11 @@
  */
 import { resolveStashDir } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
+import { NotFoundError } from "../../core/errors.js";
 import { resolveWriteTarget } from "../../core/write-source.js";
 import { withAssetMutationLease } from "../../indexer/index-writer-lock.js";
-import { isRetireProposal } from "./proposal-types.js";
-import { diffProposal, listProposals, preflightProposalPromotion, promoteProposal, proposalContent, rejectProposalDurably, resolveProposalId, revertProposal, } from "./repository.js";
+import { isRetireProposal, proposalWaitingSince } from "./proposal-types.js";
+import { diffProposal, listProposals, preflightProposalPromotion, promoteProposal, proposalContent, rejectProposalDurably, reopenProposals, resolveProposalId, revertProposal, } from "./repository.js";
 import { validateProposal } from "./validators/proposals.js";
 // ── Shared helpers ──────────────────────────────────────────────────────────
 function resolveStash(stashDir) {
@@ -29,7 +30,7 @@ function resolveProposalQueue(stashDir, queue, config) {
         return { stashDir };
     if (!queue)
         return { stashDir: resolveStash() };
-    const target = resolveWriteTarget(config ?? loadConfig(), queue);
+    const target = resolveWriteTarget(config ?? loadConfig(), queue, { flag: "--queue" });
     return { stashDir: target.source.path, target };
 }
 /**
@@ -120,6 +121,59 @@ export async function akmProposalReject(options) {
         };
     });
 }
+/**
+ * Put rejected proposals back in the queue as `pending` (#997) — the undo the
+ * proposal queue lacked. All-or-nothing: see {@link reopenProposals}. An
+ * archived proposal is found by its full id (a prefix only matches the pending
+ * queue), the same as `revert`.
+ */
+export async function akmProposalReopen(options) {
+    return withAssetMutationLease("proposal-reopen", async () => {
+        const config = options.config ?? loadConfig();
+        const queue = resolveProposalQueue(options.stashDir, options.queue, config);
+        const ids = options.ids.map((id) => {
+            try {
+                return resolveProposalId(queue.stashDir, id, options.ctx).id;
+            }
+            catch (error) {
+                if (!(error instanceof NotFoundError))
+                    throw error;
+                throw new NotFoundError(error.message, error.code, "A rejected proposal is addressed by its full id (a prefix only matches pending proposals): `akm proposal list --status rejected` lists them.");
+            }
+        });
+        const reopened = reopenProposals(queue.stashDir, config, ids, { queueTarget: queue.target, ...(options.reason !== undefined ? { reason: options.reason } : {}) }, options.ctx);
+        return reopened.map((proposal) => ({
+            schemaVersion: 1,
+            ok: true,
+            id: proposal.id,
+            ref: proposal.ref,
+            ...(options.reason !== undefined ? { reason: options.reason } : {}),
+            proposal,
+        }));
+    });
+}
+/** What a reviewer of a retire proposal needs to know that its diff (a file leaving) does not say. */
+const RETIRE_DIFF_NOTE = "Accepting archives the retired file under .akm/memory-cleanup/archive/ (nothing is deleted); " +
+    "`akm proposal revert` restores it byte-exactly.";
+/** The fields a retire proposal's diff result adds to an ordinary one (#997). */
+function retireDiffFields(retirement) {
+    return {
+        op: "delete",
+        ...(retirement
+            ? {
+                retirement: {
+                    retiredRef: retirement.retiredRef,
+                    successorRef: retirement.successorRef,
+                    judgeLabel: retirement.judgeLabel,
+                    judgeReason: retirement.judgeReason,
+                    cosine: retirement.cosine,
+                    ...(retirement.continuityRisk ? { continuityRisk: retirement.continuityRisk } : {}),
+                },
+            }
+            : {}),
+        note: RETIRE_DIFF_NOTE,
+    };
+}
 export function akmProposalDiff(options) {
     const config = options.config ?? loadConfig();
     const queue = resolveProposalQueue(options.stashDir, options.queue, config);
@@ -133,6 +187,7 @@ export function akmProposalDiff(options) {
         isNew: diff.isNew,
         unified: diff.unified,
         ...(diff.targetPath ? { targetPath: diff.targetPath } : {}),
+        ...(isRetireProposal(proposal) ? retireDiffFields(proposal.retirement) : {}),
     };
 }
 /**
@@ -204,7 +259,7 @@ export async function bulkAdjudicateProposals(options) {
                 return false;
         }
         if (options.olderThanMs !== undefined) {
-            const age = Date.now() - new Date(p.createdAt).getTime();
+            const age = Date.now() - new Date(proposalWaitingSince(p)).getTime();
             if (age < options.olderThanMs)
                 return false;
         }