akm-cli 0.10.261008-beta → 0.10.261010-beta

package/dist/commands/read/knowledge.js

@@ -8,10 +8,12 @@
  * (knowledge and memory) from the CLI. Extracted to keep the CLI entry point
  * focused on command definitions and routing.
  */
+import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { parse as yamlParse } from "yaml";
 import { detectAdapterId } from "../../core/adapter/detect-adapter.js";
+import { normalizeAkmMarkdown } from "../../core/asset/akm-markdown.js";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../../core/asset/asset-create.js";
 import { assetPathForName, stashDirFor } from "../../core/asset/asset-placement.js";
 import { assembleAsset } from "../../core/asset/asset-serialize.js";
@@ -24,6 +26,7 @@ import { resolveBundleWriteTarget, resolveMutationTarget } from "../../core/muta
 import { resolveStashStandards } from "../../core/standards/resolve-stash-standards.js";
 import { warn } from "../../core/warn.js";
 import { commitWriteTargetBoundary, formatRefForMessage, recordWriteTargetPath, resolveWriteTarget, writeAssetToSource, } from "../../core/write-source.js";
+import { withAssetMutationLease } from "../../indexer/index-writer-lock.js";
 import { indexWrittenAssets } from "../../indexer/index-written-assets.js";
 import { deriveInstallations, slugForPath } from "../../indexer/installations.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
@@ -502,16 +505,10 @@ export function resolveSupersedesForWrite(rawRefs, target, targetFlag) {
     }
     return plan;
 }
-// ── Asset writing ────────────────────────────────────────────────────────────
-/**
- * Write a markdown asset (knowledge or memory) to the resolved write target.
- *
- * Resolves the write target via the v1 precedence chain (`--bundle` →
- * `defaultWriteTarget` → working stash), validates the path is within the
- * type root, enforces `--force` semantics, and delegates the actual write
- * to `writeAssetToSource`.
- */
 export async function writeMarkdownAsset(options) {
+    if (options.expectedContentHash !== undefined && !/^[0-9a-f]{64}$/.test(options.expectedContentHash)) {
+        throw new UsageError("The expected content hash must be a lowercase hex SHA-256 digest (64 characters).", "INVALID_FLAG_VALUE");
+    }
     const cfg = loadConfig();
     // `--name` is the flat asset name; `--path` is the subdirectory under the
     // type root. Combine them into the nested name the path resolver expects.
@@ -524,16 +521,10 @@ export async function writeMarkdownAsset(options) {
     const { target } = resolved;
     const { source, config } = target;
     const typeRoot = path.join(source.path, options.type === "knowledge" ? "knowledge" : "memories");
-    // Pre-flight: existence + force semantics. The helper itself overwrites
-    // unconditionally; the CLI surfaces a friendlier UsageError before any
-    // disk activity when --force is absent.
     const assetPath = assetPathForName(options.type, typeRoot, normalizedName);
     if (!isWithin(assetPath, typeRoot)) {
         throw new UsageError(`Resolved ${options.type} path escapes the stash: "${normalizedName}"`);
     }
-    if (fs.existsSync(assetPath) && !options.force) {
-        throw new UsageError(`${options.type === "knowledge" ? "Knowledge" : "Memory"} "${normalizedName}" already exists. Re-run with --force to overwrite it.`, "RESOURCE_ALREADY_EXISTS");
-    }
     // A correction cannot supersede ITSELF. Under `--force` the ref resolves to
     // the very file this command is about to overwrite, and the demotion would
     // immediately mark the fresh correction superseded (plus a self-xref) —
@@ -544,72 +535,113 @@ export async function writeMarkdownAsset(options) {
             throw new UsageError(`--supersedes ${item.ref} resolves to the asset being written ("${resolved.displayRef}") — a correction cannot supersede itself.`, "INVALID_FLAG_VALUE", "Write the correction under a different --name, or drop --supersedes when overwriting an asset in place with --force.");
         }
     }
-    const result = await writeAssetToSource(source, config, resolved.ref, options.content);
-    const durableRef = result.ref;
-    result.ref = resolved.displayRef;
-    // SPEC-5 (--supersedes): demote each superseded asset by mutating its
-    // frontmatter (`beliefState: superseded` + sorted-set-append `supersededBy`;
-    // every other key and the body are preserved). Ordered BEFORE
-    // commitWriteTargetBoundary so a git target batches the correction and the
-    // demoted incumbent into the single boundary commit instead of leaving the
-    // metadata edit as dirty residue after it.
-    const superseded = [];
-    const demotedByRoot = new Map();
-    for (const item of options.supersedes ?? []) {
-        if (!item.writable) {
-            const reason = item.reason ?? "target is not writable";
-            warn(`Warning: superseded asset ${item.ref} was NOT demoted (${reason}). ` +
-                "The correction was written and cites it in xrefs; demote the old asset where it is writable.");
-            superseded.push({ ref: item.ref, applied: false, reason });
-            continue;
-        }
-        // The demotion round-trips the old file's frontmatter through the YAML
-        // parser. A malformed block would silently fall back to the lossy lenient
-        // scanner and re-serializing that result destroys list/nested values —
-        // skip instead of rewriting, mirroring mergeXrefsIntoContent's
-        // abort-on-malformed policy (the correction itself still writes).
-        let oldFrontmatter = null;
-        try {
-            oldFrontmatter = parseFrontmatter(fs.readFileSync(item.filePath, "utf8")).frontmatter;
-        }
-        catch {
-            // Unreadable file — let writeSupersededEdge surface the real fs error.
-        }
-        if (oldFrontmatter?.trim() && !isParseableYamlMapping(oldFrontmatter)) {
-            const reason = "its existing frontmatter is not a parseable YAML mapping — rewriting it would drop the values the parser could not read";
-            warn(`Warning: superseded asset ${item.ref} was NOT demoted (${reason}). ` +
-                "The correction was written and cites it in xrefs; fix the old asset's frontmatter and re-run the correction with --force.");
-            superseded.push({ ref: item.ref, applied: false, reason });
-            continue;
+    // The lease covers only what reads or changes authored files: the existence
+    // and revision checks, the write, the demotions and the boundary commit. The
+    // commit pushes inside the lease on purpose: a push from a writer that has
+    // released it would race the next writer's commit on the same branch (the
+    // conflicting-commit hazard the lease exists for), and the sync write path
+    // (`withWriteTargetMutation`) draws the same boundary. Indexing is a
+    // regenerable cache and runs after release.
+    const written = await withAssetMutationLease("markdown-write", async () => {
+        // Pre-flight: existence + force semantics. The helper itself overwrites
+        // unconditionally; the CLI surfaces a friendlier UsageError before any
+        // disk activity when --force is absent.
+        if (fs.existsSync(assetPath) && !options.force) {
+            throw new UsageError(`${options.type === "knowledge" ? "Knowledge" : "Memory"} "${normalizedName}" already exists. Re-run with --force to overwrite it.`, "RESOURCE_ALREADY_EXISTS");
         }
-        // A demotion failure (fs error, concurrent delete, malformed YAML the
-        // pre-check missed) must NOT abort the correction: the new asset is
-        // already on disk, and bailing out here would skip the boundary commit and
-        // the write-path indexing below — leaving the correction unindexed and,
-        // on a git target, uncommitted (and a re-run hits RESOURCE_ALREADY_EXISTS).
-        // Degrade to the same applied:false report the non-writable path uses.
-        try {
-            const sameSource = path.resolve(item.stashRoot) === path.resolve(source.path);
-            writeSupersededEdge(item.filePath, durableRef);
-            if (sameSource) {
-                recordWriteTargetPath(source, item.filePath);
+        if (options.expectedContentHash !== undefined) {
+            let existing;
+            try {
+                existing = fs.readFileSync(assetPath);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+            if (!existing || createHash("sha256").update(existing).digest("hex") !== options.expectedContentHash) {
+                throw new UsageError("The document changed or was removed after it was loaded. Reload its source before saving.", "ASSET_CONTENT_CHANGED");
+            }
+            // Unchanged when the live bytes are the submission itself (an untouched
+            // document keeps its bytes, missing metadata included) or exactly what
+            // the writer would write for it (e.g. the submission only lacks the
+            // final line break the writer adds).
+            const unchanged = existing.equals(Buffer.from(options.content, "utf8")) ||
+                existing.equals(Buffer.from(normalizeAkmMarkdown(options.content, resolved.ref.type), "utf8"));
+            if (unchanged && !options.supersedes?.length) {
+                return { ref: resolved.displayRef, path: assetPath, stashDir: source.path, unchanged: true };
             }
         }
-        catch (error) {
-            const reason = `demotion failed: ${error instanceof Error ? error.message : String(error)}`;
-            warn(`Warning: superseded asset ${item.ref} was NOT demoted (${reason}). ` +
-                "The correction was written and cites it in xrefs; demote the old asset manually or re-run the correction with --force.");
-            superseded.push({ ref: item.ref, applied: false, reason });
-            continue;
+        const result = await writeAssetToSource(source, config, resolved.ref, options.content);
+        const durableRef = result.ref;
+        result.ref = resolved.displayRef;
+        // SPEC-5 (--supersedes): demote each superseded asset by mutating its
+        // frontmatter (`beliefState: superseded` + sorted-set-append `supersededBy`;
+        // every other key and the body are preserved). Ordered BEFORE
+        // commitWriteTargetBoundary so a git target batches the correction and the
+        // demoted incumbent into the single boundary commit instead of leaving the
+        // metadata edit as dirty residue after it.
+        const superseded = [];
+        const demotedByRoot = new Map();
+        for (const item of options.supersedes ?? []) {
+            if (!item.writable) {
+                const reason = item.reason ?? "target is not writable";
+                warn(`Warning: superseded asset ${item.ref} was NOT demoted (${reason}). ` +
+                    "The correction was written and cites it in xrefs; demote the old asset where it is writable.");
+                superseded.push({ ref: item.ref, applied: false, reason });
+                continue;
+            }
+            // The demotion round-trips the old file's frontmatter through the YAML
+            // parser. A malformed block would silently fall back to the lossy lenient
+            // scanner and re-serializing that result destroys list/nested values —
+            // skip instead of rewriting, mirroring mergeXrefsIntoContent's
+            // abort-on-malformed policy (the correction itself still writes).
+            let oldFrontmatter = null;
+            try {
+                oldFrontmatter = parseFrontmatter(fs.readFileSync(item.filePath, "utf8")).frontmatter;
+            }
+            catch {
+                // Unreadable file — let writeSupersededEdge surface the real fs error.
+            }
+            if (oldFrontmatter?.trim() && !isParseableYamlMapping(oldFrontmatter)) {
+                const reason = "its existing frontmatter is not a parseable YAML mapping — rewriting it would drop the values the parser could not read";
+                warn(`Warning: superseded asset ${item.ref} was NOT demoted (${reason}). ` +
+                    "The correction was written and cites it in xrefs; fix the old asset's frontmatter and re-run the correction with --force.");
+                superseded.push({ ref: item.ref, applied: false, reason });
+                continue;
+            }
+            // A demotion failure (fs error, concurrent delete, malformed YAML the
+            // pre-check missed) must NOT abort the correction: the new asset is
+            // already on disk, and bailing out here would skip the boundary commit and
+            // the write-path indexing below — leaving the correction unindexed and,
+            // on a git target, uncommitted (and a re-run hits RESOURCE_ALREADY_EXISTS).
+            // Degrade to the same applied:false report the non-writable path uses.
+            try {
+                const sameSource = path.resolve(item.stashRoot) === path.resolve(source.path);
+                writeSupersededEdge(item.filePath, durableRef);
+                if (sameSource) {
+                    recordWriteTargetPath(source, item.filePath);
+                }
+            }
+            catch (error) {
+                const reason = `demotion failed: ${error instanceof Error ? error.message : String(error)}`;
+                warn(`Warning: superseded asset ${item.ref} was NOT demoted (${reason}). ` +
+                    "The correction was written and cites it in xrefs; demote the old asset manually or re-run the correction with --force.");
+                superseded.push({ ref: item.ref, applied: false, reason });
+                continue;
+            }
+            superseded.push({ ref: item.ref, applied: true });
+            const files = demotedByRoot.get(item.stashRoot) ?? [];
+            files.push(item.filePath);
+            demotedByRoot.set(item.stashRoot, files);
         }
-        superseded.push({ ref: item.ref, applied: true });
-        const files = demotedByRoot.get(item.stashRoot) ?? [];
-        files.push(item.filePath);
-        demotedByRoot.set(item.stashRoot, files);
-    }
-    // 0.9.0 (issue #507): single batch commit at the write boundary for git
-    // targets. No-op for filesystem/primary-stash targets.
-    commitWriteTargetBoundary(target, `Update ${formatRefForMessage(resolved.ref)}`);
+        // 0.9.0 (issue #507): single batch commit at the write boundary for git
+        // targets. No-op for filesystem/primary-stash targets.
+        commitWriteTargetBoundary(target, `Update ${formatRefForMessage(resolved.ref)}`);
+        return { result, superseded, demotedByRoot };
+    });
+    if (written.unchanged)
+        return written;
+    const { result, superseded, demotedByRoot } = written;
     // Write-path indexing: the asset is searchable immediately. Fail-open; reads
     // no longer trigger reindexes, so keeping the index current is the writer's
     // job. Demoted files reindex under their own containing root (usually the

package/dist/commands/read/search-cli.js

@@ -24,6 +24,14 @@ import { deliverRendered } from "../../output/html-render.js";
 import { akmCurate, packCuratedHits } from "./curate.js";
 import { akmSearch, parseBeliefFilterMode, parseScopeFilterFlags, parseSearchSource } from "./search.js";
 import { akmShowUnified } from "./show.js";
+const scopeFilterArg = {
+    type: "string",
+    description: "Scope filter (repeatable): --filter user=<id> --filter agent=<id> --filter run=<id> --filter channel=<name>. Narrows results without changing ranking.",
+};
+const beliefArg = {
+    type: "string",
+    description: "Belief filter on any asset: all|current|historical. current keeps active/asserted and unflagged assets; historical keeps deprecated/contradicted/superseded/archived assets. Labels do not establish factual truth.",
+};
 export const searchCommand = defineJsonCommand({
     meta: { name: "search", description: "Search the bundle" },
     args: {
@@ -44,20 +52,13 @@ export const searchCommand = defineJsonCommand({
             description: "Include asset-level search results (only meaningful with --from registry|all)",
             default: false,
         },
-        filter: {
-            type: "string",
-            description: "Scope filter (repeatable): --filter user=<id> --filter agent=<id> --filter run=<id> --filter channel=<name>. Narrows results without changing ranking.",
-        },
+        filter: scopeFilterArg,
         "include-proposed": {
             type: "boolean",
             description: 'Include entries with quality:"proposed" in the result set. Excluded by default.',
             default: false,
         },
-        belief: {
-            type: "string",
-            description: "Memory belief filter: all|current|historical. current keeps active memory beliefs; historical keeps contradicted/superseded/archived memory beliefs.",
-            default: "all",
-        },
+        belief: { ...beliefArg, default: "current" },
         "include-sessions": {
             type: "boolean",
             description: "Include session assets (excluded from default search results via config.search.defaultExcludeTypes).",
@@ -110,6 +111,8 @@ export const curateCommand = defineJsonCommand({
         },
         limit: { type: "string", description: "Maximum number of curated results", default: "4" },
         from: { type: "string", description: "Search source (local|registry|all)", default: "local" },
+        filter: scopeFilterArg,
+        belief: { ...beliefArg, default: "current" },
         pack: {
             type: "string",
             description: "Pack the ranked stash hits' full content into a single token-budgeted blob instead of returning refs " +
@@ -123,7 +126,14 @@ export const curateCommand = defineJsonCommand({
     async run({ args }) {
         const packBudget = parsePositiveIntFlag(args.pack ?? undefined, "--pack");
         const outputMode = getOutputMode();
-        const curated = await runCurate({ query: args.query, type: args.type, limit: args.limit, from: args.from }, outputMode);
+        const curated = await runCurate({
+            query: args.query,
+            type: args.type,
+            limit: args.limit,
+            from: args.from,
+            filters: parseAllFlagValues("--filter"),
+            belief: args.belief,
+        }, outputMode);
         if (packBudget !== undefined) {
             const packed = await packCuratedHits(curated, packBudget);
             deliverRendered(outputMode.format === "text" ? formatCuratePackText(packed) : JSON.stringify(packed.items, null, 2), outputMode.outputPath);
@@ -149,6 +159,8 @@ export async function runCurate(args, outputMode) {
         type: args.type,
         limit: limitParsed && limitParsed > 0 ? limitParsed : 4,
         source: parseSearchSource(args.from ?? "local"),
+        filters: parseScopeFilterFlags(args.filters ?? [], "--filter"),
+        belief: parseBeliefFilterMode(args.belief ?? "current"),
         eventSource: resolveUsageEventSource(),
         attributionProjection: outputMode.shape === "agent" ? "agent" : outputMode.detail,
     });
@@ -158,7 +170,9 @@ function formatCuratePackText(packed) {
     if (packed.items.length === 0) {
         return `No packed content for "${packed.query}" (budget ${packed.budget} tokens).`;
     }
-    return packed.items.map((item) => `## ${item.ref}\n\n${item.content}`).join("\n\n");
+    return packed.items
+        .map((item) => `## ${item.ref}\n\n${item.reason ? `${item.reason}\n\n` : ""}${item.content}`)
+        .join("\n\n");
 }
 /**
  * Reject any positional after the ref: `akm show` takes one ref, and a stray

package/dist/commands/read/search.js

@@ -103,7 +103,7 @@ export async function akmSearch(input) {
     const sources = allSources;
     const filters = normalizeScopeFilters(input.filters);
     const includeProposed = input.includeProposed === true;
-    const belief = input.belief ?? "all";
+    const belief = parseBeliefFilterMode(input.belief ?? "current");
     const localResult = source === "registry"
         ? undefined
         : await searchLocal({
@@ -118,7 +118,7 @@ export async function akmSearch(input) {
             beliefFilter: belief,
             // When `--from <name>` narrowed the source list above, propagate
             // that intent down to the database layer so FTS/vector hits from
-            // sources outside the narrowed set are filtered out post-ranking.
+            // sources outside the narrowed set cannot consume candidate budgets.
             // Without this, the index (which spans every configured source)
             // would leak hits from sources the caller did not request.
             restrictToSources: namedSourceName !== undefined,
@@ -384,7 +384,7 @@ export function parseBeliefFilterMode(value) {
  * `undefined` when nothing meaningful remains, so callers don't pay for an
  * empty-filter post-walk in `searchLocal`.
  */
-function normalizeScopeFilters(raw) {
+export function normalizeScopeFilters(raw) {
     if (!raw)
         return undefined;
     const out = {};

package/dist/commands/read/show.js

@@ -34,13 +34,15 @@ import { SCRIPT_EXTENSIONS } from "../../core/recognition-util.js";
 import { presentationFor } from "../../core/type-presentation.js";
 import { warn, warnOnce } from "../../core/warn.js";
 import { lookupBundleRef, lookupBundleRefWithResolution, lookupBundleRefWithResolutionReadonly, } from "../../indexer/indexer.js";
-import { projectMarkdownFragmentContent } from "../../indexer/passes/metadata.js";
+import { applyCuratedFrontmatter, applyProvenanceFrontmatter, projectMarkdownFragmentContent, } from "../../indexer/passes/metadata.js";
 import { ensurePrimaryIndexForRead, resolveReadSources } from "../../indexer/read-preflight.js";
+import { applyEntryFilters } from "../../indexer/search/db-search.js";
 import { buildEditHint, findSourceForPath, isEditable, resolveSourceEntries, } from "../../indexer/search/search-source.js";
 import { recentShowCount, recordShowUsage } from "../../indexer/usage/show-usage.js";
 import { buildFileContext, buildRenderContext, getRenderer, } from "../../indexer/walk/file-context.js";
 import { resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
 import { withIndexDb } from "../../storage/repositories/index-db.js";
+import { getEntryById, getEntryIdByFilePath } from "../../storage/repositories/index-entries-repository.js";
 import { getIndexedMarkdownFragment } from "../../storage/repositories/index-fts-repository.js";
 import { readEntryLinks } from "../../storage/repositories/index-links-repository.js";
 import { getCurrentWorkflowScopeKey } from "../../workflows/authoring/scope-key.js";
@@ -258,6 +260,34 @@ export async function showLocal(input) {
             "Run `akm bundle create` to create the stash directory, or check `akm bundle list` for configured paths.");
     }
     const fileCtx = buildFileContext(sourceStashDir, assetPath);
+    let beliefState;
+    if (input.recall) {
+        const policy = input.recall;
+        const sources = policy.source && !["local", "all"].includes(policy.source)
+            ? resolveSourcesForOrigin(policy.source, allSources)
+            : allSources;
+        const eligible = withIndexDb((db) => {
+            const id = getEntryIdByFilePath(db, assetPath);
+            const row = id === undefined ? undefined : getEntryById(db, id);
+            if (!row || id === undefined)
+                return false;
+            // Source-live show must not restore a belief/scope changed after indexing.
+            const entry = { ...row.entry, scope: undefined };
+            applyCuratedFrontmatter(entry, parseFrontmatter(fileCtx.content()).data);
+            const allowed = applyEntryFilters([{ ...row, id, entry }], {
+                db,
+                sources,
+                restrictToSources: true,
+                filters: policy.filters,
+                includeProposed: false,
+                beliefFilter: policy.belief ?? "current",
+            });
+            beliefState = entry.beliefState;
+            return allowed.length > 0 && (!policy.type || policy.type === "any" || entry.type === policy.type);
+        }, { readOnly: input.readOnly === true });
+        if (!eligible)
+            throw new NotFoundError(`Asset not found for recall filters: ${input.ref}`);
+    }
     const presentedName = indexedEntry.name;
     const opaqueFragmentSelector = parsed.fragment?.startsWith("akm-fragment-") === true;
     // Friendly heading selectors retain the source-live exact response contract.
@@ -302,6 +332,8 @@ export async function showLocal(input) {
     catch (error) {
         throwIndexedPathNotFound(error, input.ref);
     }
+    if (beliefState)
+        response.beliefState = beliefState;
     response.type = indexedEntry.type;
     response.name = indexedEntry.name;
     const isPrimaryStash = source?.isDefault === true;
@@ -364,8 +396,22 @@ export async function showLocal(input) {
         delete response.toolPolicy;
     }
     const editable = isEditable(assetPath, config, allSources);
+    // Evidence must describe the same revision as the rendered claim: ordinary
+    // Markdown show is source-live, while indexed fragment show is a snapshot.
+    let evidenceMetadata;
+    if (["memory", "lesson", "knowledge"].includes(response.type)) {
+        evidenceMetadata = indexedFragment ? indexedEntry.document : { name: presentedName, type: response.type };
+        if (!indexedFragment && evidenceMetadata) {
+            const frontmatter = parseFrontmatter(fileCtx.content()).data;
+            applyCuratedFrontmatter(evidenceMetadata, frontmatter);
+            applyProvenanceFrontmatter(evidenceMetadata, frontmatter);
+        }
+    }
     const fullResponse = {
         ...response,
+        ...(evidenceMetadata?.evidence ? { evidence: evidenceMetadata.evidence } : {}),
+        ...(evidenceMetadata?.evidenceSources ? { evidenceSources: evidenceMetadata.evidenceSources } : {}),
+        ...(evidenceMetadata?.evidence && evidenceMetadata.provenance ? { provenance: evidenceMetadata.provenance } : {}),
         ref: canonicalRef,
         origin: source?.registryId ?? null,
         editable,

package/dist/commands/sources/bundle-cli.js

@@ -139,14 +139,13 @@ const updateCommand = defineJsonCommand({
             description: "Allow an update containing dangerous env keys (e.g. LD_PRELOAD, PATH). Use only after explicitly reviewing the staged bundle.",
             default: false,
         },
-        // F1/R-058: gates ONLY the rare branch where the resolved content
-        // directory moves and the previous `localRoot` is deleted — a normal
-        // refresh (the overwhelming majority of updates) deletes nothing and
-        // never consults this flag. Mirrors `remove`'s `-y/--yes`.
+        // Deprecated no-op, accepted through 0.10 so scripts that pass it do not
+        // fail with UNKNOWN_FLAG. Deleting the previous directory of a read-only
+        // install whose content moved no longer asks: it is a re-fetchable cache.
         yes: {
             type: "boolean",
             alias: "y",
-            description: "Skip the confirmation prompt when an update needs to delete a previous install directory (because the resolved content location moved). No effect on a normal refresh, which deletes nothing.",
+            description: "Deprecated, no effect: update no longer asks before deleting a moved read-only install directory. Accepted through 0.10 for existing scripts.",
             default: false,
         },
     },
@@ -157,7 +156,6 @@ const updateCommand = defineJsonCommand({
                 target: args.target,
                 all: args.all,
                 force: args.force,
-                yes: args.yes,
                 allowDangerousEnvKeys: args["allow-dangerous-env-keys"],
             });
         }

package/dist/commands/sources/installed-stashes.js

@@ -611,15 +611,13 @@ function managedInstallViewOfPlainNpm(config, npmSource) {
  * Sync a single registry-managed install and return the processed record:
  * fetch into staging, audit, publish, write its lock entry, reindex.
  *
- * `yes` gates ONLY the destructive branch below (deleting a previous
- * `localRoot` whose content moved) — it has no effect on the sync itself. A
- * normal refresh that resolves the SAME content directory (the overwhelming
- * majority of updates) never reaches that branch, so it never prompts and
- * never requires `--yes` (F1/R-058: `update` must stay usable bare in
- * scripts; only the branch that can `rm -rf` needs a gate, not the whole
- * command).
+ * Read-only installs are keyed by resolved revision, so every upstream change
+ * resolves a new content directory, and the previous one is deleted once the
+ * new one is published. That directory is a re-fetchable cache: local and
+ * writable installs never take this path, and a directory another bundle or
+ * lock entry still references is kept. So deleting it never asks for confirmation.
  */
-async function updateManagedInstall(managed, force, yes, stashDir, allowDangerousEnvKeys) {
+async function updateManagedInstall(managed, force, stashDir, allowDangerousEnvKeys) {
     const { synced, staged } = await stageManagedUpdate(managed, force);
     try {
         await auditStagedUpdate(staged.auditRoot, managed.ref, allowDangerousEnvKeys);
@@ -642,12 +640,6 @@ async function updateManagedInstall(managed, force, yes, stashDir, allowDangerou
             path.resolve(managed.localRoot) !== path.resolve(synced.contentDir) &&
             managed.source !== "local" &&
             !managed.writable;
-        if (movedRoot) {
-            const { confirmDestructive } = await import("../../cli/confirm.js");
-            const confirmed = await confirmDestructive(`Update resolved a new content directory for "${managed.installId}" (${synced.contentDir}) and would delete the previous install directory at ${managed.localRoot}. This cannot be undone.`, { yes });
-            if (!confirmed)
-                throw new UsageError(`Update cancelled for "${managed.installId}"; no configuration was changed.`);
-        }
         const index = await publishAndIndex(stashDir, async () => {
             staged.publish();
             await upsertLockEntry({
@@ -724,7 +716,6 @@ export async function akmUpdate(input) {
     const target = input?.target?.trim();
     const all = input?.all === true;
     const force = input?.force === true;
-    const yes = input?.yes === true;
     const allowDangerousEnvKeys = input?.allowDangerousEnvKeys === true;
     const config = loadConfig();
     const managedInstalls = listManagedInstalls(config);
@@ -732,7 +723,7 @@ export async function akmUpdate(input) {
         // Registry-managed install (lock-backed) — re-download from its locator.
         const managed = resolveManagedTarget(config, target);
         if (managed) {
-            const updated = await updateManagedInstall(managed, force, yes, stashDir, allowDangerousEnvKeys);
+            const updated = await updateManagedInstall(managed, force, stashDir, allowDangerousEnvKeys);
             return buildUpdateResponse(stashDir, target, all, [updated.item], { index: updated.index });
         }
         // Plain git / website source (bundles without a lock) — provider re-sync.
@@ -789,7 +780,7 @@ export async function akmUpdate(input) {
             return false;
         });
         if (npmMatch) {
-            const updated = await updateManagedInstall(managedInstallViewOfPlainNpm(config, npmMatch), force, yes, stashDir, allowDangerousEnvKeys);
+            const updated = await updateManagedInstall(managedInstallViewOfPlainNpm(config, npmMatch), force, stashDir, allowDangerousEnvKeys);
             return buildUpdateResponse(stashDir, target, all, [updated.item], { index: updated.index });
         }
         const filesystemMatch = stashes.find((source) => {
@@ -812,7 +803,7 @@ export async function akmUpdate(input) {
     let latestIndex;
     for (const managed of selected) {
         try {
-            const updated = await updateManagedInstall(managed, force, yes, stashDir, allowDangerousEnvKeys);
+            const updated = await updateManagedInstall(managed, force, stashDir, allowDangerousEnvKeys);
             processed.push(updated.item);
             latestIndex = updated.index;
         }
@@ -842,7 +833,7 @@ export async function akmUpdate(input) {
                     latestIndex = updated.index;
                 }
                 else if (plain.type === "npm") {
-                    const updated = await updateManagedInstall(managedInstallViewOfPlainNpm(config, plain), force, yes, stashDir, allowDangerousEnvKeys);
+                    const updated = await updateManagedInstall(managedInstallViewOfPlainNpm(config, plain), force, stashDir, allowDangerousEnvKeys);
                     processed.push(updated.item);
                     latestIndex = updated.index;
                 }