akm-cli 0.10.261013-beta → 0.10.261014-beta

package/dist/setup/steps/embeddings.js

@@ -0,0 +1,151 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Setup step 4: embeddings. A model the connection serves, akm's built-in local
+ * embedder, another endpoint, or off (which is semantic search off).
+ */
+import * as p from "../../cli/clack.js";
+import { defaultConnection, } from "../../core/config/config.js";
+import { apiKeyReference, resolveApiKey, storedCredential } from "../../core/config/credentials.js";
+import { sameEndpoint } from "../../core/endpoint-url.js";
+import { UsageError } from "../../core/errors.js";
+import { redactUrlCredentials } from "../../core/redaction.js";
+import { isEmbeddingModel } from "../../llm/model-list.js";
+import { prompt } from "../prompt.js";
+import { describeSemanticSearchAssets, isRemoteEmbeddingConfig } from "../semantic-assets.js";
+import { applySetupAnswers } from "../setup-plan.js";
+import { listModels, pickModel, promptApiKey, promptEndpoint, promptModelName, warnUser } from "./connection-shared.js";
+/**
+ * The connection that will serve an embedding model once this run's answers are saved: the default connection
+ * of the config as it will be, which is not necessarily the one this run just answered (a further `--name`
+ * connection is not the default, and with several none of which is called `default` there is none).
+ */
+function servingConnection(input) {
+    const projected = input.connection
+        ? { ...input.current, ...applySetupAnswers(input.current, { connection: input.connection }).patch }
+        : input.current;
+    return defaultConnection(projected);
+}
+/** The embedding models the serving connection lists: this run's listing, when this run was about that connection. */
+function servedModels(input) {
+    const serving = servingConnection(input);
+    return serving !== undefined && input.connection?.name === serving.name ? input.listed.filter(isEmbeddingModel) : [];
+}
+/**
+ * A key belongs to the endpoint it was given for. When the embedding endpoint changes and no
+ * key comes with the new one, the current key is not carried over; say so.
+ */
+function warnOfDroppedKey(current, endpoint, keyGiven, interactive) {
+    if (keyGiven || current?.endpoint === undefined || sameEndpoint(current.endpoint, endpoint))
+        return;
+    if (apiKeyReference(current.apiKey) === undefined && storedCredential({ service: "embedding" }) === undefined)
+        return;
+    warnUser(`The embedding endpoint changed, so its current key is not used with ${redactUrlCredentials(endpoint)}. Give the new endpoint's key with --embedding-api-key-env (or at the prompt).`, interactive);
+}
+function fromFlags(input) {
+    const { flags } = input;
+    if (flags.embedding === "off" || flags.embedding === "local")
+        return { kind: flags.embedding };
+    const model = flags.embedding;
+    if (flags.embeddingEndpoint !== undefined) {
+        warnOfDroppedKey(input.current.embedding, flags.embeddingEndpoint, Boolean(flags.embeddingApiKeyEnv), false);
+        return {
+            kind: "endpoint",
+            endpoint: flags.embeddingEndpoint,
+            model,
+            ...(flags.embeddingApiKeyEnv ? { key: { env: flags.embeddingApiKeyEnv } } : {}),
+        };
+    }
+    if (servingConnection(input) === undefined) {
+        const several = Object.keys(input.connection
+            ? { ...input.current.connections, [input.connection.name]: 1 }
+            : (input.current.connections ?? {})).length > 1;
+        throw new UsageError(several
+            ? `--embedding ${model} is served by the default connection, and none of the connections is called "default". Name one default (akm setup --name default), or pass --embedding-endpoint.`
+            : `--embedding ${model} is served by the default connection, and none is configured. Pass --endpoint (or --embedding-endpoint).`, "MISSING_REQUIRED_ARGUMENT");
+    }
+    return { kind: "connection", model };
+}
+/** The embedding block this answer leaves the config with, for the note that says what setup downloads. */
+function embeddingAfter(input, answer) {
+    if (answer.kind === "endpoint")
+        return { endpoint: answer.endpoint, model: answer.model };
+    if (answer.kind === "connection")
+        return { endpoint: servingConnection(input)?.connection.endpoint, model: answer.model };
+    return answer.kind === "off" ? input.current.embedding : undefined;
+}
+async function askSource(input) {
+    const { current } = input;
+    const served = servedModels(input);
+    const hasServing = servingConnection(input) !== undefined;
+    const heldModel = hasServing && current.embedding?.endpoint === undefined ? current.embedding?.model : undefined;
+    const connectionModels = [...new Set([...(heldModel ? [heldModel] : []), ...served])];
+    const options = [
+        ...connectionModels.map((model) => ({ value: `model:${model}`, label: model, hint: "served by the connection" })),
+        { value: "local", label: "Built-in local embedder", hint: "no server needed" },
+        { value: "endpoint", label: "Another endpoint" },
+        { value: "off", label: "Off", hint: "keyword search only" },
+    ];
+    const initialValue = current.embedding?.endpoint
+        ? "endpoint"
+        : heldModel
+            ? `model:${heldModel}`
+            : served[0]
+                ? `model:${served[0]}`
+                : "local";
+    const choice = await prompt(() => p.select({ message: "Which embedding source should akm use?", options, initialValue }));
+    if (choice === "local" || choice === "off")
+        return { kind: choice };
+    if (choice !== "endpoint")
+        return { kind: "connection", model: choice.slice("model:".length) };
+    const endpoint = await promptEndpoint({
+        message: "Embedding endpoint URL:",
+        ...(current.embedding?.endpoint ? { initialValue: current.embedding.endpoint } : {}),
+    });
+    if (endpoint === undefined)
+        return { kind: "local" };
+    // A key belongs to the endpoint it was given for, so the current one is offered for that endpoint alone.
+    const unchangedEndpoint = current.embedding?.endpoint !== undefined && sameEndpoint(current.embedding.endpoint, endpoint);
+    const held = unchangedEndpoint
+        ? resolveApiKey(current.embedding?.apiKey, { service: "embedding" }, endpoint, process.env, true)
+        : undefined;
+    const typed = await promptApiKey(held !== undefined ? "Embedding API key (blank keeps the current one)" : "Embedding API key (blank for none)");
+    const key = typed ? { pasted: typed } : undefined;
+    warnOfDroppedKey(current.embedding, endpoint, key !== undefined, true);
+    const listed = input.probe ? await listModels(endpoint, typed ?? (unchangedEndpoint ? held : undefined), true) : [];
+    const embeddingModels = listed.filter(isEmbeddingModel);
+    const model = listed.length > 0
+        ? await pickModel("Embedding model:", embeddingModels.length > 0 ? embeddingModels : listed, current.embedding?.model)
+        : await promptModelName({ message: "Embedding model name:", initialValue: current.embedding?.model });
+    return { kind: "endpoint", endpoint, model, ...(key ? { key } : {}) };
+}
+export async function stepEmbeddings(input) {
+    const { current, flags, interactive } = input;
+    const unchanged = { mode: current.semanticSearchMode, prepareAssets: false };
+    if (flags.embedding !== undefined) {
+        const answer = fromFlags(input);
+        return { answer, semantic: { mode: answer.kind === "off" ? "off" : "auto", prepareAssets: false } };
+    }
+    if (!interactive) {
+        // The default: a model the new default connection serves. A rerun, another connection, or an embedding
+        // block the config already has is the user's earlier choice and stays.
+        const model = servedModels(input)[0];
+        if (model === undefined || current.embedding !== undefined || !input.addedDefaultConnection) {
+            return { semantic: unchanged };
+        }
+        return { answer: { kind: "connection", model }, semantic: { mode: "auto", prepareAssets: false } };
+    }
+    const answer = await askSource(input);
+    if (answer.kind === "off")
+        return { answer, semantic: { mode: "off", prepareAssets: false } };
+    const after = embeddingAfter(input, answer);
+    p.note(describeSemanticSearchAssets(after).join("\n"), "Semantic Search Assets");
+    const prepareAssets = await prompt(() => p.confirm({
+        message: isRemoteEmbeddingConfig(after)
+            ? "Check the embedding endpoint and verify semantic search now?"
+            : "Download and verify semantic-search assets now?",
+        initialValue: true,
+    }));
+    return { answer, semantic: { mode: "auto", prepareAssets } };
+}

package/dist/setup/steps/harnesses.js

@@ -0,0 +1,118 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Setup steps 1 and 2: which agent programs to enable as harnesses, which of
+ * them agent work runs on, and whether akm's own model calls (improve, judging,
+ * extraction) may run through it too.
+ */
+import * as p from "../../cli/clack.js";
+import { defaultConnection, defaultHarness } from "../../core/config/config.js";
+import { warn } from "../../core/warn.js";
+import { getHarness } from "../../integrations/harnesses/index.js";
+import { prompt } from "../prompt.js";
+import { harnessEntries } from "../setup-plan.js";
+import { runsReadOnly, unrestrictedModelWorkNote } from "../summary.js";
+function readOnlyNote(platform, bin) {
+    return runsReadOnly(platform, bin)
+        ? "model calls are limited to reading and searching"
+        : "model calls cannot be restricted to read-only";
+}
+function configuredPlatforms(current) {
+    return [...new Set(Object.entries(current.harnesses ?? {}).map(([name, harness]) => harness.platform ?? name))];
+}
+/** The platform agent work runs on in the config, if any. */
+function currentDefaultPlatform(current) {
+    const found = defaultHarness(current);
+    return found ? (found.harness.platform ?? found.name) : undefined;
+}
+/** The `bin` the config sets for the first entry of `platform`, if it sets one: the program setup will judge. */
+function configuredBin(current, platform) {
+    return Object.entries(current.harnesses ?? {}).find(([name, harness]) => (harness.platform ?? name) === platform)?.[1]
+        .bin;
+}
+/** The harness agent work runs on once `answer` is applied: the entry the config will hold, with its own `bin`. */
+function selectedHarness(current, answer) {
+    const harnesses = answer ? harnessEntries(current.harnesses, answer.platforms, answer.default) : current.harnesses;
+    return defaultHarness({ harnesses });
+}
+export async function stepHarnesses(input) {
+    const { current, installed, flags } = input;
+    const configured = configuredPlatforms(current);
+    const installedPlatforms = installed.map((harness) => harness.platform);
+    let answer;
+    if (flags.harness) {
+        for (const platform of flags.harness) {
+            if (!installedPlatforms.includes(platform)) {
+                warn(`[akm setup] ${platform} was not found on PATH; enabling it anyway.`);
+            }
+        }
+        answer = { platforms: [...new Set([...configured, ...flags.harness])], default: flags.harness[0] };
+    }
+    else if (!input.interactive) {
+        if (configured.length === 0 && installedPlatforms.length > 0) {
+            answer = { platforms: installedPlatforms, default: installedPlatforms[0] };
+        }
+    }
+    else {
+        answer = await askHarnesses(current, installed, configured);
+    }
+    // `modelWork` is whether the default harness may take akm's model calls, once that has been decided.
+    const result = (modelCallsOnHarness, modelWork) => ({
+        ...(answer ? { answer } : {}),
+        modelCallsOnHarness,
+        ...(modelWork !== undefined ? { modelWork } : {}),
+    });
+    // Model calls can go to a harness only when one is enabled and no connection exists or is being added.
+    const selected = selectedHarness(current, answer);
+    if (selected === undefined || defaultConnection(current) !== undefined || flags.endpoint !== undefined) {
+        return result(false);
+    }
+    const defaultPlatform = selected.harness.platform ?? selected.name;
+    const readOnly = runsReadOnly(defaultPlatform, selected.harness.bin);
+    // A saved `modelWork: false` is the user's choice: only the question's "yes" changes it, never a default.
+    const declined = selected.harness.modelWork === false;
+    if (!input.interactive)
+        return declined ? result(false, false) : result(readOnly, readOnly);
+    const yes = await prompt(() => p.confirm({
+        message: `Use ${defaultPlatform} for akm's own model calls too (improve, judging, extraction)? ${readOnly ? "Model calls are limited to reading and searching." : unrestrictedModelWorkNote(defaultPlatform)}`,
+        initialValue: !declined,
+    }));
+    // Said again once it is chosen, so it stays in the transcript beside the answer.
+    if (yes && !readOnly)
+        p.log.warn(unrestrictedModelWorkNote(defaultPlatform));
+    return result(yes, yes);
+}
+async function askHarnesses(current, installed, configured) {
+    const installedPlatforms = installed.map((harness) => harness.platform);
+    const candidates = [...new Set([...installedPlatforms, ...configured])];
+    if (candidates.length === 0) {
+        p.log.info("No agent programs found on PATH. Agent work runs on akm's own runtime over a connection (set one up next).");
+        return undefined;
+    }
+    const selected = await prompt(() => p.multiselect({
+        message: "Which agent programs should akm use? (agent work runs on them)",
+        options: candidates.map((platform) => ({
+            value: platform,
+            label: getHarness(platform)?.displayName ?? platform,
+            hint: `${installed.find((harness) => harness.platform === platform)?.path ?? "not found on PATH"}; ${readOnlyNote(platform, configuredBin(current, platform))}`,
+        })),
+        initialValues: configured.length > 0 ? [...configured] : installedPlatforms,
+        required: false,
+    }));
+    if (selected.length === 0)
+        return { platforms: [] };
+    const wanted = currentDefaultPlatform(current);
+    const initialValue = wanted && selected.includes(wanted) ? wanted : selected[0];
+    const chosen = selected.length === 1
+        ? selected[0]
+        : await prompt(() => p.select({
+            message: "Which one should agent work run on by default?",
+            options: selected.map((platform) => ({
+                value: platform,
+                label: getHarness(platform)?.displayName ?? platform,
+            })),
+            initialValue,
+        }));
+    return { platforms: selected, default: chosen };
+}

package/dist/setup/steps/platforms.js

@@ -2,13 +2,11 @@
 // 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/.
 /**
- * Setup wizard steps for agent platforms and agent-CLI selection: detect
- * agent platform config dirs as stash sources, and pick a default agent CLI.
+ * Setup wizard step for agent platforms: detect agent platform config dirs
+ * and offer them as bundle sources.
  */
 import * as p from "../../cli/clack.js";
-import { detectAgentCliProfiles, pickDefaultAgentProfile } from "../../integrations/agent/index.js";
 import { detectAgentPlatforms } from "../detect.js";
-import { readAgentEngineSelection } from "../engine-config.js";
 import { prompt } from "../prompt.js";
 // The just-computed source list is threaded through the private setup draft.
 export async function stepAgentPlatforms(current) {
@@ -46,80 +44,3 @@ export async function stepAgentPlatforms(current) {
     }
     return entries;
 }
-/**
- * Print a feature capability summary after both connection steps are complete.
- */
-export function printCapabilitySummary(smallModelSkipped, agentConfigured) {
-    const lines = ["Setup complete. Here's what's enabled:", ""];
-    lines.push("  ✓ akm search, akm curate, akm show, akm index, akm remember — always available");
-    if (!smallModelSkipped) {
-        lines.push("  ✓ akm improve, akm remember --enrich — small model configured");
-    }
-    else {
-        lines.push("  ✗ akm improve, akm remember --enrich — run `akm setup` to enable");
-    }
-    if (agentConfigured) {
-        lines.push("  ✓ akm proposal new, akm improve, akm task — agent configured");
-    }
-    else {
-        lines.push("  ✗ akm proposal new, akm improve, akm task — run `akm setup` to enable");
-    }
-    p.note(lines.join("\n"), "Feature Summary");
-}
-export async function stepAgentSelection(current, detections) {
-    const currentAgentBlock = readAgentEngineSelection(current);
-    const available = detections.filter((d) => d.available);
-    if (available.length === 0) {
-        return currentAgentBlock;
-    }
-    const initialValue = pickDefaultAgentProfile(detections, currentAgentBlock?.default) ?? available[0]?.name;
-    const selectedDefault = await prompt(() => p.select({
-        message: "Which detected agent CLI should be the default?",
-        options: [
-            ...available.map((d) => ({
-                value: d.name,
-                label: d.name,
-                hint: d.resolvedPath ?? d.bin,
-            })),
-            { value: "disabled", label: "Disabled", hint: "do not configure a default agent CLI" },
-        ],
-        initialValue,
-    }));
-    if (selectedDefault === "disabled") {
-        if (!currentAgentBlock?.engines) {
-            return undefined;
-        }
-        return {
-            ...(currentAgentBlock ?? {}),
-            default: undefined,
-        };
-    }
-    return {
-        ...(currentAgentBlock ?? {}),
-        default: selectedDefault,
-    };
-}
-/**
- * Detect installed agent CLIs and produce an updated `agent` config block
- * with a sensible `default` (the first detected profile that the user has
- * not already overridden).
- *
- * Pure-ish: file system / PATH probes are routed through `detectFn` so
- * tests can drive the branches without touching the real PATH.
- *
- * @internal Exported for testing only.
- */
-export function stepAgentCliDetection(current, detectFn = detectAgentCliProfiles) {
-    const detections = detectFn(current);
-    const currentAgentBlock = readAgentEngineSelection(current);
-    const defaultName = pickDefaultAgentProfile(detections, currentAgentBlock?.default);
-    // No installed agents found and no existing config → leave block absent.
-    if (!defaultName && !currentAgentBlock) {
-        return { detections };
-    }
-    const agent = {
-        ...(currentAgentBlock ?? {}),
-        ...(defaultName ? { default: defaultName } : {}),
-    };
-    return { agent, detections };
-}

package/dist/setup/steps.js

@@ -17,6 +17,16 @@ export function createSetupContext(initial, options) {
         apply(delta) {
             acc = deepMergeConfig(acc, delta);
         },
+        replace(keys) {
+            const next = { ...acc };
+            for (const [key, value] of Object.entries(keys)) {
+                if (value === undefined)
+                    delete next[key];
+                else
+                    next[key] = value;
+            }
+            acc = next;
+        },
     };
 }
 /**

package/dist/setup/summary.js

@@ -0,0 +1,67 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * What runs where, in words, once setup has chosen: model calls, agent work and
+ * embeddings. The words are read off the table `akm info` and `akm health`
+ * print (`../commands/targets.ts`), so the summary says what those say and what
+ * a call does.
+ */
+import { targetRows } from "../commands/targets.js";
+import { getHarness } from "../integrations/harnesses/index.js";
+/**
+ * Whether akm can run this platform's program with its tools limited to reading and searching for model calls:
+ * `bin` when the harness sets one, else the platform's own.
+ */
+export function runsReadOnly(platform, bin) {
+    const harness = getHarness(platform);
+    return harness !== undefined && (harness.confinableInstalled?.(bin ?? harness.profile.bin) ?? harness.confinable);
+}
+/** What setup says, wherever it names a harness that takes akm's model calls and cannot be restricted. */
+export function unrestrictedModelWorkNote(name) {
+    return `Model work on ${name} cannot be restricted: it can edit files and run commands.`;
+}
+function modelSuffix(row) {
+    return row.model ? ` (${row.model})` : "";
+}
+/** Model calls or agent work: where the row says it runs, or what is wrong with the config that stops it. */
+function describeWork(row, rows, modelWork) {
+    if (row.problem)
+        return row.problem;
+    if (row.kind === "connection") {
+        return `${modelWork ? "connection" : "akm's own runtime over connection"} "${row.target}"${modelSuffix(row)}`;
+    }
+    if (row.kind === "harness") {
+        const platform = rows.find((r) => r.type === "harness" && r.name === row.target);
+        const restriction = modelWork && platform?.type === "harness"
+            ? runsReadOnly(platform.platform, platform.bin)
+                ? ", limited to reading and searching"
+                : `. ${unrestrictedModelWorkNote(`"${row.target}"`)}`
+            : "";
+        return `harness "${row.target}"${modelSuffix(row)}${restriction}`;
+    }
+    const declined = modelWork
+        ? rows.find((r) => r.type === "harness" && r.modelWork === false)
+        : undefined;
+    return declined
+        ? `off: no connection is configured, and harness "${declined.name}" is set not to take model calls. Add a connection with \`akm setup --endpoint URL\`.`
+        : "off: no connection or harness is configured";
+}
+function describeEmbeddings(row) {
+    if (row.kind === "local")
+        return `akm's built-in local embedder${modelSuffix(row)}`;
+    if (row.kind === "connection")
+        return `${row.model ?? "a model"} on connection "${row.target}"`;
+    if (row.kind === "endpoint")
+        return `${row.model ?? "a model"} at ${row.target}`;
+    return "off";
+}
+export function describeRuns(config) {
+    const rows = targetRows({ config });
+    const work = (name) => rows.find((r) => r.type === "process" && r.process === name);
+    return {
+        modelCalls: describeWork(work("improve"), rows, true),
+        agentWork: describeWork(work("agents"), rows, false),
+        embeddings: describeEmbeddings(work("embedding")),
+    };
+}

package/dist/sources/freshness.js

@@ -2,38 +2,33 @@
 // 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/.
 /**
- * Shared freshness-window skeleton for mirror caches (git repos, website
- * snapshots). A marker file's mtime records the last successful refresh:
- * within `ttlMs` the cached copy is served without refreshing; on refresh
- * failure the cached copy is still served while the marker is younger than
- * `staleMs`, so search stays available through upstream outages.
+ * Shared materialization skeleton for mirror caches (git repos, website
+ * snapshots). A marker file records that the mirror was materialized on this
+ * host and its mtime records the last successful refresh. A usable
+ * materialized mirror is served as-is: age never triggers a refresh. Only a
+ * missing marker, an unusable mirror, or `force` (`akm bundle update`) does.
+ * A failed refresh is reported, never masked: the refresh implementations
+ * leave the previous copy on disk, so search keeps serving it, but the caller
+ * sees the error.
  */
 import fs from "node:fs";
-import { isExpired } from "./providers/provider-utils.js";
 /**
- * Run the fresh → refresh → stale-fallback ladder around `refresh()`.
- * Resolves when the cached copy is usable (fresh, refreshed, or stale-but-
- * within-window); rethrows the refresh error otherwise.
+ * Run the materialized → refresh ladder around `refresh()`. Resolves when the
+ * cached copy is usable as-is or has just been refreshed; a failed refresh
+ * rethrows its error.
  */
 export async function withFreshnessCache(options) {
     const usable = options.isUsable ?? (() => true);
-    let mtime = 0;
+    let materialized = false;
     try {
-        mtime = fs.statSync(options.markerPath).mtimeMs;
+        fs.statSync(options.markerPath);
+        materialized = true;
     }
     catch {
         /* no marker — never successfully refreshed */
     }
-    if (!options.force && mtime && !isExpired(mtime, options.ttlMs) && usable()) {
+    if (!options.force && materialized && usable()) {
         return;
     }
-    try {
-        await options.refresh();
-    }
-    catch (err) {
-        if (options.allowStaleOnRefreshFailure !== false && mtime && !isExpired(mtime, options.staleMs) && usable()) {
-            return;
-        }
-        throw err;
-    }
+    await options.refresh();
 }

package/dist/sources/providers/git-provider.js

@@ -13,10 +13,6 @@ import { validateGitUrl } from "../../registry/resolve.js";
 import { withFreshnessCache } from "../freshness.js";
 import { assertNoIgnoredPathOverwrite, cloneRepo, inspectGitUpstream, runGit } from "./git-install.js";
 import { sanitizeString } from "./provider-utils.js";
-/** Cache TTL before refreshing the mirrored repo (12 hours). */
-const CACHE_TTL_MS = 12 * 60 * 60 * 1000;
-/** Maximum stale age allowed when refresh fails (7 days). */
-const CACHE_STALE_MS = 7 * 24 * 60 * 60 * 1000;
 /**
  * Git source provider — clones (and re-pulls) a remote repo into a local
  * cache directory. Implements the {@link SourceProvider} interface.
@@ -75,10 +71,7 @@ export async function ensureGitMirror(repo, cachePaths, options) {
     const writable = options?.writable === true;
     await withFreshnessCache({
         markerPath: cachePaths.indexPath,
-        ttlMs: CACHE_TTL_MS,
-        staleMs: CACHE_STALE_MS,
         force: options?.force === true,
-        allowStaleOnRefreshFailure: !(options?.force === true && writable),
         isUsable: () => !requireRepoDir || hasExtractedRepo(cachePaths.repoDir),
         refresh: async () => {
             fs.mkdirSync(cachePaths.rootDir, { recursive: true });
@@ -96,8 +89,8 @@ export async function ensureGitMirror(repo, cachePaths, options) {
 }
 /**
  * Sync mode for a long-lived configured git stash. Mirrors the repo into the
- * shared registry-index cache (12h TTL) and exposes the working tree as the
- * stash content directory.
+ * shared registry-index cache and exposes the working tree as the stash
+ * content directory. A mirror that already exists is reused unless `force`.
  */
 export async function syncMirroredRepo(config, options) {
     if (!config.url) {

package/dist/sources/providers/provider-utils.js

@@ -17,13 +17,9 @@ export function sanitizeString(value, maxLength = 255) {
     // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional — strip control chars from untrusted remote data
     return value.replace(/[\u0000-\u001f\u007f]/g, "").slice(0, maxLength);
 }
-/** Check whether a cached timestamp has exceeded its TTL. */
-export function isExpired(mtimeMs, ttlMs) {
-    return Date.now() - mtimeMs > ttlMs;
-}
 /**
  * True when ANY built-in adapter's install-time `looksLikeRoot` probe claims
- * `root` — the spec §1.2 ordered probe reduced to "is this the root of a bundle
+ * `root` — the ordered probe reduced to "is this the root of a bundle
  * of some format family?". A probe that throws (unreadable dir, race) does not
  * claim the root.
  */

package/dist/sources/snapshot-fetchers/robots.js

@@ -4,8 +4,7 @@
 /**
  * robots.txt parsing, matching, and a crawl-scoped fetch/cache policy.
  *
- * Behavioral reference: docs/plans/specs/p1-robots.md (authoritative). This
- * module is a clean rewrite against akm's contracts, not a port of any
+ * This module is a clean rewrite against akm's contracts, not a port of any
  * upstream source file.
  *
  * Pure by design: no fetching happens here (see `RobotsTxtLoader`/
@@ -14,7 +13,7 @@
  * `createRobotsPolicy` returns so it dies with the crawl that created it —
  * a module-level `origin -> RobotsRuleSet` map would leak `disallowAll`
  * results across crawls and across the test suite's process-wide `bun test`
- * run (see spec §6.1). The module-level `WeakMap` below is a different
+ * run. The module-level `WeakMap` below is a different
  * category: it memoizes a pure function of an individual rule object's own
  * `pattern` field, keyed by that object's identity. It cannot leak meaning
  * between origins or tests — distinct `parseRobotsTxt` calls (even for
@@ -40,7 +39,7 @@ export const ROBOTS_USER_AGENT_HEADER = "akm-cli website provider";
 /**
  * Frozen so a stray mutation (e.g. an accidental `.rules.push(...)` somewhere
  * that borrows one of these as a starting point) can never poison every other
- * crawl sharing this instance (spec §10, Review log 2026-08-01 finding 1).
+ * crawl sharing this instance.
  */
 const EMPTY_ROBOTS_RULES = Object.freeze([]);
 export const ALLOW_ALL_RULES = Object.freeze({
@@ -128,8 +127,8 @@ export function parseRobotsTxt(text) {
                 pattern: value,
                 specificity: value.length,
             };
-            // Compile once, here, at parse time — not on every URL check (spec
-            // §6.4, review finding robots.ts:238). See `compiledPatternCache`.
+            // Compile once, here, at parse time — not on every URL check. See
+            // `compiledPatternCache`.
             compiledPatternCache.set(rule, compilePatternSegments(value));
             current.rules.push(rule);
             continue;
@@ -185,7 +184,7 @@ function isUnreservedByte(byte) {
  * fallback) and match targets (`isPathAllowedByRobots`), so a percent-encoded
  * alias of a disallowed path — e.g. a link written as `/%73ecret/` — cannot
  * bypass `Disallow: /secret/` simply because `URL.pathname` preserves
- * %-escapes verbatim. Reserved-octet patterns like spec §4.3 M-31's
+ * %-escapes verbatim. Reserved-octet patterns like
  * `/caf%C3%A9` are untouched on both sides (0xC3/0xA9 are not unreserved),
  * so they keep matching themselves exactly as before.
  */
@@ -211,10 +210,10 @@ function compilePatternSegments(pattern) {
 }
 /**
  * Per-rule-object cache of the compiled pattern (see the file-level doc
- * comment for why this is not "module-level state" in the sense spec §6.1
- * forbids). `parseRobotsTxt` populates this eagerly, once, when it creates
- * each `RobotsPathRule` — the compile-once requirement from spec §6.4 /
- * review finding robots.ts:238. `compiledPatternFor` below is a defensive
+ * comment for why this is not "module-level state" in the sense that comment
+ * rules out). `parseRobotsTxt` populates this eagerly, once, when it creates
+ * each `RobotsPathRule` — the compile-once requirement.
+ * `compiledPatternFor` below is a defensive
  * fallback for `RobotsRuleSet`s assembled by hand (e.g. test fixtures)
  * rather than via `parseRobotsTxt`; it still compiles at most once per rule
  * object, just lazily on first use instead of at parse time.
@@ -324,7 +323,7 @@ export function createRobotsPolicy(load) {
         const pending = load(robotsUrl).then(outcomeToRuleSet);
         // A rejected fetch must not poison the cache: the next lookup for this
         // origin should retry the loader rather than replaying the same failure
-        // forever (spec §4.4 L-04).
+        // forever.
         pending.catch(() => {
             if (cache.get(origin) === pending)
                 cache.delete(origin);