akm-cli 0.9.17 → 0.9.19-alpha.1

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;
         }

package/dist/commands/proposal/repository.js

@@ -21,7 +21,7 @@ import { assembleAsset, serializeFrontmatter } from "../../core/asset/asset-seri
 import { carryForwardBookkeepingFrontmatter, parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { conceptIdFromTypeName, parseRefInput } from "../../core/asset/resolve-ref.js";
 import { loadConfig } from "../../core/config/config.js";
-import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
+import { ConfigError, NotFoundError, rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { proposalContent } from "../../core/file-change.js";
 import { canonicalBundleIdForTarget, resolveBundleWriteTarget } from "../../core/mutation-target.js";
@@ -34,7 +34,7 @@ import { indexWrittenAssets } from "../../indexer/index-written-assets.js";
 import { deriveInstallations } from "../../indexer/installations.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { insertEventOnce } from "../../storage/repositories/events-repository.js";
-import { recordImproveLedger, recordImproveLedgerDecision, } from "../../storage/repositories/improve-ledger-repository.js";
+import { CONSOLIDATE_LEDGER_SOURCE, forgetImproveLedgerDecision, recordImproveLedger, recordImproveLedgerDecision, reopenImproveLedgerDecision, } from "../../storage/repositories/improve-ledger-repository.js";
 import { getStateProposal, listStateProposalIdsByPrefix, listStateProposals, upsertProposal, } from "../../storage/repositories/proposals-repository.js";
 import { openSqliteReadSnapshot } from "../../storage/sqlite-read-snapshot.js";
 import { pkgVersion } from "../../version.js";
@@ -42,8 +42,8 @@ import { contentHash } from "../improve/content-hash.js";
 import { writeSupersededEdge } from "../improve/memory/memory-belief.js";
 import { archiveCleanupCandidate, derivedTwinPath } from "../improve/memory/memory-improve.js";
 import { runBaseChecks } from "../lint/base-linter.js";
-import { formatNewAssetDiff, formatUnifiedDiff } from "./diff-format.js";
-import { ASSET_MISSING_GATE_REASON, EXPIRED_GATE_REASON, isAutomatedProposalSource, isRetireProposal, isValidProposalSource, PROPOSAL_SOURCES, STALE_TARGET_GATE_REASON, } from "./proposal-types.js";
+import { formatNewAssetDiff, formatRetireDiff, formatUnifiedDiff } from "./diff-format.js";
+import { ASSET_MISSING_GATE_REASON, EXPIRED_GATE_REASON, isAutomatedProposalSource, isRetireProposal, isValidProposalSource, PROPOSAL_SOURCES, proposalWaitingSince, STALE_TARGET_GATE_REASON, } from "./proposal-types.js";
 import { canonicalOnlyProposalValidators, hasCanonicalProposalValidator, runProposalValidators, } from "./validators/proposal-validators.js";
 import { repairProposalContent, validateProposal } from "./validators/proposals.js";
 export { AUTOMATED_PROPOSAL_SOURCES, isAutomatedProposalSource, isValidProposalSource, PROPOSAL_SOURCES, } from "./proposal-types.js";
@@ -141,6 +141,28 @@ export function resolveProposalQueueTarget(stashDir, config = loadConfig()) {
     }
     return { source: bundleId, root };
 }
+/**
+ * The configured bundle that owns the asset `itemRef` names when it is not the
+ * bundle rooted at `target`; otherwise `undefined`. A differing name is
+ * confirmed by the owner's root, so one bundle known by two spellings is never
+ * taken for two, and an owner that cannot be resolved is never refused on.
+ */
+function otherOwningBundle(itemRef, target) {
+    try {
+        const owner = parseBundleRef(itemRef).bundle;
+        if (owner === undefined || owner === target.source)
+            return undefined;
+        const sources = resolveSourceEntries(target.root, loadConfig());
+        const ownerSource = sources[deriveInstallations(sources).findIndex((installation) => installation.id === owner)];
+        return ownerSource !== undefined && path.resolve(ownerSource.path) !== path.resolve(target.root)
+            ? owner
+            : undefined;
+    }
+    catch (err) {
+        rethrowIfTestIsolationError(err);
+        return undefined;
+    }
+}
 /**
  * Create a pending proposal (a random UUID id). Obviously invalid input is
  * refused with a typed `proposal_creation_rejected` event. The mint and its
@@ -190,9 +212,13 @@ export function createProposal(stashDir, input, ctx) {
             return rejectProposal("missing_description", `Proposal for "${input.ref}" (source=consolidate) has empty or missing frontmatter description.`);
         }
     }
+    const proposalTarget = resolveCreateProposalTarget(stashDir, input.target, parsedRef.origin);
+    const owner = input.itemRef ? otherOwningBundle(input.itemRef, proposalTarget) : undefined;
+    if (owner) {
+        return rejectProposal("cross_bundle", `Proposal for "${input.ref}" rewrites ${input.itemRef}, which bundle "${owner}" owns, but its queue target is bundle "${proposalTarget.source}". Filing it there would fork the asset out of "${owner}" or overwrite this bundle's copy with content taken from the other. Improve it in its own bundle instead (\`akm improve --bundle ${owner}\`).`);
+    }
     // The FileChange envelope, and the target's before-hashes as of mint (the
     // freshness check at accept compares against them).
-    const proposalTarget = resolveCreateProposalTarget(stashDir, input.target, parsedRef.origin);
     const normalizedRef = proposalDurableRef(parsedRef, proposalTarget);
     const targetRoot = path.resolve(proposalTarget.root);
     let targetRelPath;
@@ -373,9 +399,13 @@ export function listProposals(stashDir, options = {}, ctx) {
 /**
  * {@link listProposals} on a read snapshot that never creates or migrates
  * state.db: prompt building runs before the first dispatch has validated its
- * credentials, and a missing store is simply empty.
+ * credentials, and a missing store is simply empty. A caller that already
+ * holds a live connection (`ctx.db`) reads through it: a snapshot would copy
+ * the whole database for nothing.
  */
 export function listProposalsReadOnly(stashDir, options = {}, ctx) {
+    if (ctx?.db)
+        return queryProposals(ctx.db, stashDir, options);
     const dbPath = ctx?.dbPath ?? getStateDbPath();
     if (!fs.existsSync(dbPath))
         return [];
@@ -450,6 +480,25 @@ function ledgerOutcomeForDecision(status, gateDecision) {
     }
     return "rejected";
 }
+/**
+ * What a decision's ledger row is about. A promotion's row is keyed by its
+ * source memory, so a decision on it names that memory, together with the body
+ * hash the promotion was queued against — this is what holds the memory back
+ * until it changes (`isContentDrivenDecision`). Any other proposal, and a
+ * promotion minted before the hash was recorded, is keyed by its own ref.
+ * Every decision that can create a row when none carries the proposal id — a
+ * reject, an accept and a drain deferral alike — must key it this way: a stray
+ * row under the knowledge ref carries the proposal id, so a later verdict
+ * updates that one and never reaches the memory's own row.
+ */
+function decisionLedgerSubject(proposal) {
+    if (proposal.source === CONSOLIDATE_LEDGER_SOURCE &&
+        proposal.promotionSource !== undefined &&
+        proposal.promotionSourceHash !== undefined) {
+        return { ref: proposal.promotionSource, contentHash: proposal.promotionSourceHash };
+    }
+    return { ref: proposal.ref };
+}
 /** Archive a pending proposal as accepted/rejected, recording the decision in the ledger in the same transaction. */
 export function archiveProposal(stashDir, id, status, reason, ctx, gateDecision) {
     return withProposalsDb(ctx, (db) => withImmediateTransaction(db, () => {
@@ -469,7 +518,7 @@ export function archiveProposal(stashDir, id, status, reason, ctx, gateDecision)
         recordImproveLedgerDecision(db, {
             proposalId: updated.id,
             stashDir,
-            ref: updated.ref,
+            ...decisionLedgerSubject(updated),
             source: updated.source,
             outcome: ledgerOutcomeForDecision(status, gateDecision),
             at: decidedAt,
@@ -496,7 +545,7 @@ export function recordGateDecision(stashDir, id, decision, ctx) {
             recordImproveLedgerDecision(db, {
                 proposalId: updated.id,
                 stashDir,
-                ref: updated.ref,
+                ...decisionLedgerSubject(updated),
                 source: updated.source,
                 outcome: "review_needed",
                 at: decidedAt,
@@ -547,9 +596,10 @@ export function purgeOrphanProposals(stashDir, sourceDirs, ctx) {
 }
 /**
  * Archive pending proposals older than `archiveRetentionDays` (default 90;
- * 0 disables) as rejected with an `expired` gate decision and a
- * `proposal_expired` event. The ledger records `expired` — a short grace, not
- * the rejection window, since nobody judged the content.
+ * 0 disables; counted from the last reopen, if any) as rejected with an
+ * `expired` gate decision and a `proposal_expired` event. The ledger records
+ * `expired` — a short grace, not the rejection window, since nobody judged the
+ * content.
  */
 export function expireStaleProposals(stashDir, config, ctx) {
     const t0 = Date.now();
@@ -568,7 +618,9 @@ export function expireStaleProposals(stashDir, config, ctx) {
         // way back short of the pair pass finding it again from scratch.
         if (isRetireProposal(p))
             continue;
-        const createdMs = new Date(p.createdAt).getTime();
+        // A reopened proposal's wait starts over at the reopen (#997): expiring it
+        // on its original age would undo the reopen at the next sweep.
+        const createdMs = new Date(proposalWaitingSince(p)).getTime();
         if (!Number.isFinite(createdMs) || nowMs - createdMs < retentionDays * MS_PER_DAY)
             continue;
         try {
@@ -686,7 +738,7 @@ function persistProposalDecision(stashDir, proposal, decision, ctx) {
         recordImproveLedgerDecision(db, {
             proposalId: next.id,
             stashDir,
-            ref: next.ref,
+            ...decisionLedgerSubject(next),
             source: next.source,
             outcome: ledgerOutcomeForDecision(accept ? "accepted" : "reverted"),
             at: decision.decidedAt,
@@ -1587,17 +1639,197 @@ async function revertProposalWithLease(stashDir, config, id, options, ctx) {
     await indexWrittenProposalAsset(target, assetPath);
     return { proposal: reverted, assetPath, ref: proposal.ref };
 }
+/** The message of the stale-target refusal `check` raises, else `undefined`. */
+function staleRefusal(check) {
+    try {
+        check();
+        return undefined;
+    }
+    catch (error) {
+        if (error instanceof UsageError)
+            return error.message;
+        throw error;
+    }
+}
+/**
+ * Why `proposal` cannot be reopened, or `undefined` when it can. Only a
+ * rejected proposal comes back, and only one accept would not refuse as stale:
+ * a retire proposal needs its successor and both recorded body hashes to still
+ * match (B2), any other its target to be what it was minted against
+ * (STALE, R20) — so a reopened proposal is never one the next accept refuses.
+ */
+function reopenRefusal(config, proposal, queueTarget) {
+    if (proposal.status !== "rejected") {
+        return `it is not rejected (current status: ${proposal.status}); only a rejected proposal can be reopened.`;
+    }
+    if (proposal.changes.length === 0 || proposal.proposedTarget === undefined) {
+        // A pending row must carry both (proposalToRowValues), which a row from
+        // before the change envelope existed cannot.
+        return "it was recorded before proposals carried their change envelope, so it cannot go back in the queue.";
+    }
+    const target = resolveProposalWriteTarget(config, proposal, undefined, queueTarget);
+    const assetPath = resolveAssetFilePathSafe(target.source, parseRefInput(proposal.ref));
+    if (!assetPath)
+        return "its target cannot be resolved.";
+    if (!isRetireProposal(proposal)) {
+        return staleRefusal(() => void readFreshProposalTarget(proposal, assetPath, proposalContent(proposal)));
+    }
+    if (!proposal.retirement)
+        return "it has no retirement metadata.";
+    if (!fs.existsSync(assetPath)) {
+        return "its retired file no longer exists (already retired, or removed by something else).";
+    }
+    const { retirement } = proposal;
+    return staleRefusal(() => assertRetirementStillFresh(proposal.id, proposal.ref, retirement, target.source, fs.readFileSync(assetPath)));
+}
+/** The assets a retire proposal speaks for — the one it retires and its successor — as bundle-less concept ids, the way the pair pass keys them. */
+function retireHeldRefs(proposal) {
+    return [proposal.ref, proposal.retirement?.successorRef].flatMap((ref) => {
+        const conceptId = ref === undefined ? undefined : proposalRefIdentity(ref)?.conceptId;
+        return conceptId === undefined ? [] : [conceptId];
+    });
+}
+const REOPEN_REFUSED_HINT = "Only a rejected proposal whose target is unchanged can be reopened; `akm proposal list --status rejected` lists the candidates.";
+const REOPEN_RETIRE_CONFLICT_HINT = "Only one pending retire proposal can involve a document: accept or reject the pending one (or reopen just one of a clashing pair), then reopen the other.";
+/**
+ * The pair pass never has two pending retire proposals speak for one asset
+ * (`pendingRetireRefs`): accepting one would strand the other. Reopening must
+ * not break that either — a rejected pair can meanwhile have been re-paired
+ * with something else. `held` maps each asset to the pending retire proposal
+ * that has it; a proposal that clears this claims its assets, so two in one
+ * batch that clash refuse the later.
+ */
+function retireConflict(proposal, held) {
+    if (!isRetireProposal(proposal))
+        return undefined;
+    const refs = retireHeldRefs(proposal);
+    for (const ref of refs) {
+        const holder = held.get(ref);
+        if (holder !== undefined) {
+            return `${ref} is already part of retire proposal ${holder}, which is pending or being reopened with this one; only one pending retire proposal may involve an asset.`;
+        }
+    }
+    for (const ref of refs)
+        held.set(ref, proposal.id);
+    return undefined;
+}
+/**
+ * Put rejected proposals back in the queue (`akm proposal reopen`, #997): a
+ * rejection is otherwise final, and it also suppresses the pair pass from ever
+ * re-proposing a retirement (its record keys the pair), so a mistaken one
+ * could not be undone. Each proposal returns to `pending` with the rejection —
+ * and the gate verdict that came with it — kept in `reviewHistory` (the verdict
+ * itself is cleared, unless it is a `deferred` hand-off to a person), its
+ * ledger row reset (the pair pass keys off proposal status, so the pair is no
+ * longer suppressed and, while pending, cannot be minted twice), and a
+ * `proposal_reopened` event recorded, all in one transaction.
+ *
+ * All-or-nothing: every id is checked (see {@link reopenRefusal} and
+ * {@link retireConflict}) before any is reopened, and one refusal leaves the
+ * whole batch untouched.
+ */
+export function reopenProposals(stashDir, config, ids, options = {}, ctx) {
+    return withProposalsDb(ctx, (db) => withImmediateTransaction(db, () => {
+        const proposals = [...new Set(ids)].map((id) => requireProposal(db, stashDir, id));
+        const held = new Map();
+        for (const pending of listStateProposals(db, { stashDir, status: "pending" })) {
+            if (isRetireProposal(pending))
+                for (const ref of retireHeldRefs(pending))
+                    held.set(ref, pending.id);
+        }
+        const refusals = proposals.flatMap((proposal) => {
+            const refusal = reopenRefusal(config, proposal, options.queueTarget);
+            const conflict = refusal === undefined ? retireConflict(proposal, held) : undefined;
+            const reason = refusal ?? conflict;
+            return reason === undefined
+                ? []
+                : [{ proposal: `${proposal.id} (${proposal.ref})`, reason, isConflict: conflict !== undefined }];
+        });
+        if (refusals.length > 0) {
+            // A retire conflict is not about the target changing, so it gets its own hint.
+            const hints = [
+                ...(refusals.some((refusal) => !refusal.isConflict) ? [REOPEN_REFUSED_HINT] : []),
+                ...(refusals.some((refusal) => refusal.isConflict) ? [REOPEN_RETIRE_CONFLICT_HINT] : []),
+            ];
+            throw new UsageError(proposals.length === 1
+                ? `Proposal ${refusals[0]?.proposal} cannot be reopened: ${refusals[0]?.reason}`
+                : `Cannot reopen ${refusals.length} of ${proposals.length} proposals; none were reopened:\n${refusals
+                    .map((refusal) => `  - ${refusal.proposal}: ${refusal.reason}`)
+                    .join("\n")}`, "INVALID_FLAG_VALUE", hints.join(" "));
+        }
+        const decidedAt = nowIso(ctx);
+        return proposals.map((existing) => {
+            const reopened = {
+                ...existing,
+                status: "pending",
+                updatedAt: decidedAt,
+                review: undefined,
+                // A reopened proposal is adjudicated afresh: a `staged` verdict would
+                // let the drain accept it unseen, and another gate's `auto-rejected`
+                // would have the drain skip it. A `deferred` one is the quality
+                // gate's hand-off to a person, which the drain must keep honouring
+                // (drainProposals leaves it alone), so it stays.
+                gateDecision: existing.gateDecision?.outcome === "deferred" ? existing.gateDecision : undefined,
+                reviewHistory: [
+                    ...(existing.reviewHistory ?? []),
+                    {
+                        ...(existing.review !== undefined ? { review: existing.review } : {}),
+                        ...(existing.gateDecision !== undefined ? { gateDecision: existing.gateDecision } : {}),
+                        reopenedAt: decidedAt,
+                        ...(options.reason !== undefined ? { reopenReason: options.reason } : {}),
+                    },
+                ],
+            };
+            upsertProposal(db, reopened, stashDir);
+            if (isRetireProposal(existing)) {
+                // A retire mint writes no ledger row, so the one its rejection wrote goes.
+                forgetImproveLedgerDecision(db, stashDir, existing.id);
+            }
+            else {
+                reopenImproveLedgerDecision(db, {
+                    proposalId: existing.id,
+                    stashDir,
+                    source: existing.source,
+                    at: decidedAt,
+                    detail: options.reason !== undefined ? `reopened: ${options.reason}` : "reopened",
+                });
+            }
+            insertEventOnce(db, {
+                eventType: "proposal_reopened",
+                ts: decidedAt,
+                ref: reopened.ref,
+                metadata: {
+                    proposalId: reopened.id,
+                    source: reopened.source,
+                    ...(reopened.sourceRun !== undefined ? { sourceRun: reopened.sourceRun } : {}),
+                    ...(options.reason !== undefined ? { reason: options.reason } : {}),
+                },
+                idempotencyKey: `${reopened.id}:reopened:${decidedAt}`,
+            });
+            return reopened;
+        });
+    }));
+}
 /** The proposal against the asset its accept would overwrite (same target resolution as accept). */
 export function diffProposal(stashDir, config, id, options = {}, ctx) {
     const proposal = getProposal(stashDir, id, ctx);
     const target = resolveProposalWriteTarget(config, proposal, options.target, options.queueTarget);
     const targetPath = resolveAssetFilePathSafe(target.source, parseRefInput(proposal.ref));
     const existing = targetPath && fs.existsSync(targetPath) ? fs.readFileSync(targetPath, "utf8") : null;
-    // A retire proposal's primary change deletes its target rather than
-    // writing content: "proposed" is empty and the diff shows the whole body
-    // being removed, reusing the ordinary unified-diff formatter instead of
-    // proposalContent() (which has nothing to read for a delete).
-    const proposed = isRetireProposal(proposal) ? "" : proposalContent(proposal);
+    if (isRetireProposal(proposal)) {
+        // A retire proposal's primary change deletes its target rather than
+        // writing content (proposalContent() has nothing to read for a delete):
+        // accept archives the file, it never replaces it with a blank one, so the
+        // diff shows the file leaving — not a "proposed" side (#997).
+        return {
+            existing,
+            proposed: "",
+            unified: formatRetireDiff(proposal.ref, existing, proposal.retirement?.successorRef),
+            isNew: false,
+            ...(targetPath ? { targetPath } : {}),
+        };
+    }
+    const proposed = proposalContent(proposal);
     return {
         existing,
         proposed,