akm-cli 0.9.14 → 0.9.15-beta.2

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

@@ -30,8 +30,14 @@ import { akmShowUnified } from "./show.js";
  * rejected — the command then runs against the DEFAULT `--from` value
  * (local) instead of the source the caller named, with exit 0 and no error.
  * Reject it explicitly instead.
+ *
+ * Exported so `akm task list` (`../tasks/tasks-cli.ts`, #951) — a pure
+ * delegating alias for `akm search --type task` — applies the identical
+ * guard rather than a second copy of it; a task-list-scoped `--source` must
+ * fail exactly like `search`'s does, not fall through to citty's silent
+ * unknown-flag absorption.
  */
-function rejectRetiredSourceFlag() {
+export function rejectRetiredSourceFlag() {
     if (!getParsedInvocation().hasFlag("--source"))
         return;
     throw new UsageError("`--source` was renamed to `--from` in 0.9. Use `--from local|registry|all` instead.", "INVALID_FLAG_VALUE");
@@ -141,7 +147,7 @@ export const searchCommand = defineJsonCommand({
 export const curateCommand = defineJsonCommand({
     meta: {
         name: "curate",
-        description: "Pick the assets worth loading for a task. Unlike `akm search`, this reranks by intent, attaches a preview and run details per hit, adds related support refs, and summarizes the set — the usual starting point for an agent.",
+        description: "Pick the assets worth loading for a task. Unlike `akm search`, this attaches a preview and run details per hit, adds related support refs, and summarizes the set — the usual starting point for an agent.",
     },
     args: {
         // Optional in citty so run() is invoked when omitted; we re-validate
@@ -283,6 +289,18 @@ export const showCommand = defineJsonCommand({
             type: "string",
             description: "Scope filter (repeatable): --filter user=<id> --filter agent=<id> --filter run=<id> --filter channel=<name>. Narrows resolution to assets whose frontmatter scope matches. Same axis as `akm search --filter`.",
         },
+        context: {
+            type: "string",
+            description: "Fragment presentation: exact (default) returns only the selected section; lead returns bounded indexed-safe document lead plus the explicitly labelled selected match.",
+        },
+        "max-tokens": {
+            type: "string",
+            description: "Approximate context budget in tokens (four characters per token). Requires --context lead; mutually exclusive with --max-chars.",
+        },
+        "max-chars": {
+            type: "string",
+            description: "Exact context budget in characters. Requires --context lead; mutually exclusive with --max-tokens.",
+        },
         // Declared as the POSITIVE name with `default: true` — see the
         // `project-context` comment on `searchCommand` above for why a flag NAME
         // must never start with `no-`.
@@ -331,10 +349,22 @@ export const showCommand = defineJsonCommand({
         // commands share one spelling for the scope-narrowing axis).
         const scopeTokens = parseAllFlagValues("--filter");
         const scope = parseScopeFilterFlags(scopeTokens, "--filter");
+        const contextMode = parseFragmentContextMode(typeof args.context === "string" ? args.context : undefined);
+        const maxTokens = parsePositiveIntFlag(args["max-tokens"] ?? undefined, "--max-tokens");
+        const maxChars = parsePositiveIntFlag(args["max-chars"] ?? undefined, "--max-chars");
+        if (maxTokens !== undefined && maxChars !== undefined) {
+            throw new UsageError("--max-tokens and --max-chars are mutually exclusive.", "INVALID_FLAG_VALUE");
+        }
+        const maxContextChars = maxChars ?? (maxTokens !== undefined ? maxTokens * 4 : undefined);
+        if (maxContextChars !== undefined && !Number.isSafeInteger(maxContextChars)) {
+            throw new UsageError("Fragment context budget is too large.", "INVALID_FLAG_VALUE");
+        }
         const skipLogging = args["track-usage"] === false;
         const result = await akmShowUnified({
             ref: args.ref,
             detail: showDetail,
+            contextMode,
+            maxContextChars,
             scope,
             skipLogging,
             eventSource: resolveUsageEventSource(),
@@ -342,3 +372,9 @@ export const showCommand = defineJsonCommand({
         output("show", result);
     },
 });
+export function parseFragmentContextMode(raw) {
+    const normalized = raw?.trim().toLowerCase() || "exact";
+    if (normalized === "exact" || normalized === "lead")
+        return normalized;
+    throw new UsageError(`Invalid --context value: "${raw}". Expected exact or lead.`, "INVALID_FLAG_VALUE");
+}

package/dist/commands/read/show.js

@@ -23,7 +23,7 @@ import { assetPathForName, stashDirFor } from "../../core/asset/asset-placement.
 import { makeBundleRef, parseBundleRef } from "../../core/asset/asset-ref.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { extractSection, markdownFragmentSlugs } from "../../core/asset/markdown.js";
-import { fragmentForSelector } from "../../core/asset/markdown-fragments.js";
+import { buildMarkdownLeadContext, fragmentForSelector, MARKDOWN_FRAGMENT_CONTEXT_DEFAULT_MAX_CHARS, } from "../../core/asset/markdown-fragments.js";
 import { displayRef, typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
 import { META_DIR, parseMetaRef, readMetaFile } from "../../core/asset/stash-meta.js";
 import { asNonEmptyString, isWithin } from "../../core/common.js";
@@ -65,6 +65,7 @@ import { getActiveWorkflowRun } from "../../workflows/runtime/runs.js";
  */
 export async function akmShowUnified(input) {
     const ref = input.ref.trim();
+    validateFragmentContextRequest(input);
     // 0a. Stash `.meta/` convention: `[origin//]meta[:name]` direct-reads a
     //     human-authored orientation doc from the stash's `.meta/` directory.
     //     These files are not indexed (the walker skips dot-dirs), so they are
@@ -148,6 +149,32 @@ async function showStashMeta(metaRef) {
 function hasAnyScopeKey(scope) {
     return Boolean(scope.user || scope.agent || scope.run || scope.channel);
 }
+function validateFragmentContextRequest(input) {
+    const mode = input.contextMode ?? "exact";
+    if (mode !== "exact" && mode !== "lead") {
+        throw new UsageError(`Invalid --context value: "${String(mode)}". Expected exact or lead.`, "INVALID_FLAG_VALUE");
+    }
+    if (input.maxContextChars !== undefined &&
+        (!Number.isSafeInteger(input.maxContextChars) || input.maxContextChars <= 0)) {
+        throw new UsageError("Fragment context budget must be a positive safe integer.", "INVALID_FLAG_VALUE");
+    }
+    if (mode !== "lead" && input.maxContextChars !== undefined) {
+        throw new UsageError("--max-chars and --max-tokens require --context lead.", "INVALID_FLAG_VALUE");
+    }
+    if (mode !== "lead")
+        return;
+    if (parseMetaRef(input.ref)) {
+        throw new UsageError("--context lead requires an indexed Markdown asset fragment.", "INVALID_FLAG_VALUE");
+    }
+    const parsed = parseBundleRef(input.ref);
+    if (!parsed.fragment) {
+        throw new UsageError("--context lead requires a fragment-qualified ref.", "INVALID_FLAG_VALUE");
+    }
+    const type = typeNameFromConceptId(parsed.conceptId)?.type;
+    if (type === "env" || type === "secret") {
+        throw new UsageError(`--context lead is unavailable for sensitive ${type} assets.`, "INVALID_FLAG_VALUE");
+    }
+}
 /**
  * Read the asset file's frontmatter and verify its `scope_*` keys satisfy
  * every supplied filter. Throws a {@link NotFoundError} on mismatch so the
@@ -184,6 +211,7 @@ function enforceScopeOrThrow(filePath, ref, scope) {
 }
 /** @internal Use akmShowUnified() for all external callers. */
 export async function showLocal(input) {
+    validateFragmentContextRequest(input);
     const parsed = parseBundleRef(input.ref);
     warnSensitiveFragmentUnsupported(parsed);
     const assetParts = typeNameFromConceptId(parsed.conceptId);
@@ -235,14 +263,19 @@ export async function showLocal(input) {
     }
     const fileCtx = buildFileContext(sourceStashDir, assetPath);
     const presentedName = indexedEntry.name;
-    const indexedFragment = parsed.fragment?.startsWith("akm-fragment-")
+    const opaqueFragmentSelector = parsed.fragment?.startsWith("akm-fragment-") === true;
+    // Friendly heading selectors retain the source-live exact response contract.
+    // Only resolve the indexed-safe revision when the selector itself is opaque,
+    // or when the caller explicitly opts into indexed-safe contextual output.
+    const indexedFragment = parsed.fragment && (opaqueFragmentSelector || input.contextMode === "lead")
         ? withIndexDb((db) => getIndexedMarkdownFragment(db, indexedEntry.itemRef, parsed.fragment))
         : undefined;
+    const indexedFragmentContent = opaqueFragmentSelector ? indexedFragment?.content : undefined;
     const indexedRenderer = rendererForIndexedEntry(indexedEntry, fileCtx);
     let response;
     try {
         if (indexedRenderer === null) {
-            response = buildIndexedProjectionResponse(indexedEntry, assetPath, parsed.fragment, indexedFragment?.content);
+            response = buildIndexedProjectionResponse(indexedEntry, assetPath, parsed.fragment, indexedFragmentContent);
         }
         else {
             const match = typeof indexedRenderer === "string" ? indexedMatch(indexedEntry, indexedRenderer) : recognizeMatch(fileCtx);
@@ -263,7 +296,7 @@ export async function showLocal(input) {
                     warn(`Fragment "#${parsed.fragment}" was ignored: ${makeBundleRef(parsed.bundle, parsed.conceptId)} is not a Markdown document, so heading fragments do not apply. Showing the whole asset.`);
                 }
                 else {
-                    applyMarkdownFragment(response, fileCtx.content(), parsed.fragment, presentedName, indexedFragment?.content);
+                    applyMarkdownFragment(response, fileCtx.content(), parsed.fragment, presentedName, indexedFragmentContent);
                 }
             }
         }
@@ -280,6 +313,41 @@ export async function showLocal(input) {
         conceptId: indexedEntry.conceptId,
         bundleId: indexedEntry.bundleId,
     }, config.defaultBundle ?? (isPrimaryStash ? indexedEntry.bundleId : undefined));
+    if (parsed.fragment && indexedFragment) {
+        const selectedFragmentId = indexedFragment.fragments[indexedFragment.ordinal].fragmentId;
+        const selectedRef = `${canonicalRef}#${selectedFragmentId}`;
+        const parentEstimatedTokens = typeof indexedEntry.document?.fileSize === "number"
+            ? Math.round(indexedEntry.document.fileSize / 4)
+            : Math.round(indexedFragment.parentChars / 4);
+        Object.assign(response, {
+            selectedRef,
+            parentRef: canonicalRef,
+            fragmentOrdinal: indexedFragment.ordinal + 1,
+            fragmentCount: indexedFragment.count,
+            startLine: indexedFragment.startLine,
+            endLine: indexedFragment.endLine,
+            ...(indexedFragment.previousFragmentId
+                ? { previousRef: `${canonicalRef}#${indexedFragment.previousFragmentId}` }
+                : {}),
+            ...(indexedFragment.nextFragmentId ? { nextRef: `${canonicalRef}#${indexedFragment.nextFragmentId}` } : {}),
+            fragmentChars: indexedFragment.fragmentChars,
+            fragmentEstimatedTokens: Math.round(indexedFragment.fragmentChars / 4),
+            parentChars: indexedFragment.parentChars,
+            parentEstimatedTokens,
+            contextMode: input.contextMode ?? "exact",
+            contextTruncated: false,
+        });
+        if (input.contextMode === "lead") {
+            const contextMaxChars = input.maxContextChars ?? MARKDOWN_FRAGMENT_CONTEXT_DEFAULT_MAX_CHARS;
+            const contextual = buildMarkdownLeadContext(indexedFragment.fragments, indexedFragment.ordinal, contextMaxChars);
+            applyMarkdownResponsePayload(response, contextual.content);
+            response.contextMaxChars = contextMaxChars;
+            response.contextTruncated = contextual.truncated;
+        }
+    }
+    else if (input.contextMode === "lead") {
+        throw new NotFoundError(`Indexed-safe fragment context is unavailable for ${input.ref}.`);
+    }
     if (response.type === "workflow")
         response.action = buildWorkflowAction(canonicalRef);
     // 07 P1-D: provenance-aware toolPolicy CEILING. An agent's self-declared
@@ -541,6 +609,14 @@ function applyMarkdownFragment(response, raw, fragment, name, indexedFragmentCon
     else
         response.content = section;
 }
+function applyMarkdownResponsePayload(response, content) {
+    if (response.template !== undefined)
+        response.template = content;
+    else if (response.prompt !== undefined)
+        response.prompt = content;
+    else
+        response.content = content;
+}
 function requireMarkdownSection(content, fragment, name) {
     const section = extractSection(content, fragment);
     if (section)
@@ -572,6 +648,7 @@ function buildBriefResponse(full, assetPath) {
         ...(summary.origin !== undefined ? { origin: summary.origin } : {}),
         ...(full.editable !== undefined ? { editable: full.editable } : {}),
         ...(full.editHint ? { editHint: full.editHint } : {}),
+        ...fragmentResponseProjection(full),
     };
 }
 /**
@@ -607,6 +684,28 @@ function buildSummaryResponse(full, assetPath) {
         ...(full.origin !== undefined ? { origin: full.origin } : {}),
         ...(full.editable !== undefined ? { editable: full.editable } : {}),
         ...(full.editHint ? { editHint: full.editHint } : {}),
+        ...fragmentResponseProjection(full),
     };
     return summary;
 }
+function fragmentResponseProjection(full) {
+    if (!full.selectedRef)
+        return {};
+    return {
+        selectedRef: full.selectedRef,
+        parentRef: full.parentRef,
+        fragmentOrdinal: full.fragmentOrdinal,
+        fragmentCount: full.fragmentCount,
+        startLine: full.startLine,
+        endLine: full.endLine,
+        previousRef: full.previousRef,
+        nextRef: full.nextRef,
+        fragmentChars: full.fragmentChars,
+        fragmentEstimatedTokens: full.fragmentEstimatedTokens,
+        parentChars: full.parentChars,
+        parentEstimatedTokens: full.parentEstimatedTokens,
+        contextMode: full.contextMode,
+        contextMaxChars: full.contextMaxChars,
+        contextTruncated: full.contextTruncated,
+    };
+}

package/dist/commands/sources/info.js

@@ -5,7 +5,7 @@ import { placementTypes } from "../../core/asset/asset-placement.js";
 import { resolveStashDir } from "../../core/common.js";
 import { getSources, loadConfig } from "../../core/config/config.js";
 import { classifyPathAccess, describeInaccessiblePath } from "../../core/path-access.js";
-import { getDbPath } from "../../core/paths.js";
+import { getCacheDir, getConfigDir, getDataDir, getDbPath, getStateDir } from "../../core/paths.js";
 import { formatRegistryUrl } from "../../core/registry-url.js";
 import { error } from "../../core/warn.js";
 import { closeDatabase, openExistingDatabase } from "../../storage/repositories/index-connection.js";
@@ -69,6 +69,10 @@ export function assembleInfo(options) {
         version: pkgVersion,
         bundleDir: stashDir,
         defaultBundle,
+        dataDir: getDataDir(),
+        configDir: getConfigDir(),
+        cacheDir: getCacheDir(),
+        stateDir: getStateDir(),
         assetTypes,
         searchModes,
         semanticSearch: {

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

@@ -26,7 +26,7 @@ import { beginImmediateTransaction, getStateDbPath, openStateDatabase } from "..
 import { warn } from "../../core/warn.js";
 import { resolveGitContentRoot } from "../../core/write-source.js";
 import { withAssetMutationLease } from "../../indexer/index-writer-lock.js";
-import { akmIndex } from "../../indexer/indexer.js";
+import { akmIndex, runEmbeddingPass } from "../../indexer/indexer.js";
 import { compareAndSwapLockfileSnapshot, publishLockfileUpdate, readLockfile, readLockfileForUpdate, } from "../../integrations/lockfile.js";
 import { parseRegistryRef } from "../../registry/resolve.js";
 import { sha256Hex } from "../../runtime.js";
@@ -350,11 +350,19 @@ export async function akmRemove(input) {
         },
     };
 }
-/** Read the current index generation without creating or hydrating anything. */
+/**
+ * Read the current index generation without creating or hydrating anything.
+ * This path never ran an embedding pass (#954, field-report follow-up), so it has no
+ * `verification` to report — {@link buildUpdateResponse} falls back to the
+ * two facts it can actually know (whether semantic search is configured on
+ * at all) rather than fabricating verification numbers (`entryCount: 0`,
+ * `ok: true`) for a run that never verified anything.
+ */
 function readCurrentIndexSummary() {
     const db = openReadonlyExistingDatabase(getDbPath());
-    if (!db)
+    if (!db) {
         return { mode: "incremental", totalEntries: 0, directoriesScanned: 0, directoriesSkipped: 0 };
+    }
     try {
         return {
             mode: "incremental",
@@ -388,6 +396,12 @@ function buildUpdateResponse(stashDir, target, all, processed, opts) {
             directoriesScanned: index.directoriesScanned,
             directoriesSkipped: index.directoriesSkipped,
             ...(index.scanComplete !== undefined ? { scanComplete: index.scanComplete } : {}),
+            // A real embedding pass (`akmIndex`/`runEmbeddingPass`) reports its own
+            // verified `semanticStatus`. When no pass ran this update (the
+            // no-op/nothing-configured fallback) the only two facts known without
+            // fabricating a verification are whether semantic search is off at all
+            // or, if not, that its state is simply unverified this run.
+            semanticStatus: index.verification?.semanticStatus ?? (finalConfig.semanticSearchMode === "off" ? "disabled" : "pending"),
         },
     };
 }
@@ -499,6 +513,45 @@ function closeUnifiedUpdateTransaction(transaction, committed) {
             : `[akm bundle update] rolled back, but closing its database handles failed: ${String(closeError)}`);
     }
 }
+/**
+ * Run the embedding phase AFTER the coordinator's atomic commit, on its own
+ * fresh connection (#954). Before this, `akmUpdate` called
+ * `akmIndex()` for its embedding phase too, INSIDE this same unified
+ * `BEGIN IMMEDIATE` — so every per-batch commit the materializer opened
+ * nested as an unobservable SAVEPOINT, and a SIGKILL mid-run lost every
+ * embedding of the run rather than just the one in flight. The
+ * ambient-transaction drift guard (#954) now rejects that outright, so
+ * `akmIndex`'s own embedding phase is skipped for a deferred update
+ * transaction and this runs instead, once content/lock/index/state are
+ * already durably committed.
+ *
+ * A failing pass (provider down, timeout) does NOT fail the update: the
+ * bundle content and index are already committed successfully, exactly like
+ * a plain `akm index` whose embedding phase fails — only the reported
+ * `verification` reflects the shortfall (`semanticStatus: "blocked"`).
+ */
+async function runPostCommitEmbeddingPass(index) {
+    const config = loadConfig();
+    let db;
+    try {
+        const embeddingDim = config.embedding?.dimension;
+        db = openIndexDatabase(getDbPath(), embeddingDim ? { embeddingDim } : undefined);
+        const { verification } = await runEmbeddingPass({ db, config, onProgress: () => { } });
+        return { ...index, verification };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        warn(`[akm bundle update] post-commit embedding pass failed: ${message}`);
+        return {
+            ...index,
+            verification: { ...index.verification, ok: false, semanticStatus: "blocked", message },
+        };
+    }
+    finally {
+        if (db)
+            closeDatabase(db);
+    }
+}
 function pathAtOrBelow(candidate, root) {
     const relative = path.relative(path.resolve(root), path.resolve(candidate));
     return relative === "" || (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
@@ -779,14 +832,8 @@ async function publishPreparedPlainUpdate(id, ref, prepared, stashDir, allowInse
                 updateTransactionHook("before-commit", id, { db: transaction.db });
                 commitUnifiedUpdateTransaction(transaction);
                 committed = true;
-                try {
-                    transaction.deferred.afterCommit?.();
-                }
-                catch (error) {
-                    warn(`[akm bundle update] committed, but semantic status refresh failed: ${String(error)}`);
-                }
                 prepared.publication?.commit();
-                return index;
+                return await runPostCommitEmbeddingPass(index);
             }
             catch (error) {
                 let recoveryError = transaction ? rollbackUnifiedUpdateTransaction(transaction) : undefined;
@@ -1093,12 +1140,6 @@ async function updateManagedInstall(managed, force, yes, stashDir, allowInsecure
                 updateTransactionHook("before-commit", managed.installId, { db: transaction.db });
                 commitUnifiedUpdateTransaction(transaction);
                 committed = true;
-                try {
-                    transaction.deferred.afterCommit?.();
-                }
-                catch (error) {
-                    warn(`[akm bundle update] committed, but semantic status refresh failed: ${String(error)}`);
-                }
             }
             catch (error) {
                 let recoveryError = transaction ? rollbackUnifiedUpdateTransaction(transaction) : undefined;
@@ -1146,6 +1187,7 @@ async function updateManagedInstall(managed, force, yes, stashDir, allowInsecure
                 }
             }
             prepared.publication?.commit();
+            index = await runPostCommitEmbeddingPass(index);
             if (movedRoot) {
                 const currentConfig = loadConfig();
                 const currentLocks = readLockfile();

package/dist/commands/sources/self-update.js

@@ -174,10 +174,10 @@ export function getAkmBinaryName() {
         return "akm-windows-x64.exe";
     throw new ConfigError(`Unsupported platform for binary upgrade: ${platform}/${arch}`, "UNSUPPORTED_PLATFORM");
 }
-export async function checkForUpdate(currentVersion) {
+export async function checkForUpdate(currentVersion, fetchOptions) {
     const installMethod = detectInstallMethod();
     const url = `https://api.github.com/repos/${REPO}/releases/latest`;
-    const response = await fetchWithRetry(url, { headers: githubHeaders() });
+    const response = await fetchWithRetry(url, { headers: githubHeaders() }, fetchOptions);
     if (!response.ok) {
         throw new Error(`Failed to check for updates: ${response.status} ${response.statusText}`);
     }

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

@@ -42,10 +42,13 @@ import { resolveBundleWriteTarget } from "../../core/mutation-target.js";
 import { getCacheDir } from "../../core/paths.js";
 import { clearLogFile, info, isVerbose, setLogFile } from "../../core/warn.js";
 import { resolveWriteTarget } from "../../core/write-source.js";
+import { releaseIndexRebuildLock, tryAcquireIndexRebuildLock } from "../../indexer/index-rebuild-lock.js";
 import { akmIndex } from "../../indexer/indexer.js";
 import { getHyphenatedBoolean, getOutputMode } from "../../output/context.js";
 import { inferAssetName, mergeXrefsIntoContent, readKnowledgeInput, resolveSupersedesForWrite, resolveSupersedesWriteTarget, resolveXrefsForWrite, writeMarkdownAsset, } from "../read/knowledge.js";
 import { assembleInfo } from "./info.js";
+/** Matches the high-frequency per-committed-batch progress line (#954), excluded from non-verbose JSON-mode stderr. */
+const EMBEDDED_BATCH_PROGRESS_PATTERN = /^Embedded \d+\/\d+ entries\.$/;
 export const indexCommand = defineCommand({
     meta: { name: "index", description: "Build search index (incremental by default; --full forces full reindex)" },
     args: {
@@ -66,6 +69,16 @@ export const indexCommand = defineCommand({
             description: "When combined with --clean, report stale entries without deleting them.",
             default: false,
         },
+        reembed: {
+            type: "boolean",
+            description: "Force re-embedding of every entry, bypassing the embedding-model-rename compatibility check.",
+            default: false,
+        },
+        "skip-if-locked": {
+            type: "boolean",
+            description: "If another `akm index` run already holds the rebuild lock, skip gracefully (exit 0) instead of contending with it. Use for scheduled/opportunistic index runs so they don't pile up against a longer run in progress.",
+            default: false,
+        },
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
@@ -75,6 +88,27 @@ export const indexCommand = defineCommand({
             if (getHyphenatedBoolean(args, "re-enrich") || getParsedInvocation().getFlagValue("--re-enrich") !== undefined) {
                 throw new UsageError("`akm index --re-enrich` has been removed. Re-enrichment of index-time LLM passes is not exposed in this slice.");
             }
+            // #956: opt-in, non-blocking rebuild lock — never gates a human-typed
+            // `akm index` (it only warns and contends), but a scheduled/opportunistic
+            // caller can pass --skip-if-locked to step aside instead of piling up
+            // behind a run already in progress. Acquired before any other side
+            // effect (log file, spinner) so a skip does neither.
+            const lockAcquisition = tryAcquireIndexRebuildLock(args["skip-if-locked"]);
+            if (lockAcquisition.state === "skipped") {
+                output("index", {
+                    ok: true,
+                    skipped: {
+                        reason: "lock-held",
+                        pid: lockAcquisition.holder.pid,
+                        // #956: the launcher pid (when known) alongside the pid that
+                        // actually holds the lock — every process listing and task log
+                        // shows the launcher pid, not the bun/node child's.
+                        launcherPid: lockAcquisition.holder.launcherPid,
+                        startedAt: lockAcquisition.holder.startedAt,
+                    },
+                });
+                return;
+            }
             const outputMode = getOutputMode();
             const controller = new AbortController();
             const abort = () => controller.abort(new Error("index interrupted"));
@@ -98,6 +132,7 @@ export const indexCommand = defineCommand({
                     full: args.full,
                     clean: args.clean,
                     dryRun: args["dry-run"],
+                    reembed: args.reembed,
                     onProgress: ({ phase, message, processed, total }) => {
                         latestMessage = message;
                         const progressPrefix = processed !== undefined && total !== undefined ? `[${processed}/${total}] ` : "";
@@ -108,6 +143,17 @@ export const indexCommand = defineCommand({
                             spin.stop(`${progressPrefix}${message}`);
                             spin.start(`${progressPrefix}${message}`);
                         }
+                        else if (!EMBEDDED_BATCH_PROGRESS_PATTERN.test(message)) {
+                            // Non-verbose, non-text (JSON/yaml/etc) mode: silence used to be
+                            // total until the run finished (#954) — a stalled
+                            // run looked identical to "nothing written". Phase-start
+                            // messages and the embedding heartbeat now reach stderr here
+                            // too; the high-frequency per-batch `Embedded N/M entries.`
+                            // line (emitted after every committed batch)
+                            // is deliberately excluded — that would be spam, not a
+                            // heartbeat.
+                            info(`[index:${phase}] ${progressPrefix}${message}`);
+                        }
                     },
                     signal: controller.signal,
                 });
@@ -126,6 +172,8 @@ export const indexCommand = defineCommand({
                 clearLogFile();
                 process.off("SIGINT", abort);
                 process.off("SIGTERM", abort);
+                if (lockAcquisition.state === "acquired")
+                    releaseIndexRebuildLock(lockAcquisition.ownership);
             }
         });
     },

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

@@ -29,7 +29,11 @@ import { getParsedInvocation } from "../../cli/invocation.js";
 import { parsePositiveIntFlag } from "../../cli/parse-args.js";
 import { defineGroupCommand, defineJsonCommand, EXIT_CODES, GLOBAL_OUTPUT_ARGS, output, outputWithExitCode, runWithJsonErrors, } from "../../cli/shared.js";
 import { UsageError } from "../../core/errors.js";
+import { resolveUsageEventSource } from "../../indexer/usage/usage-events.js";
+import { getOutputMode } from "../../output/context.js";
 import { TASK_RUN_BOOLEAN_FLAGS, TASK_RUN_VALUE_FLAGS } from "../../tasks/task-run-reserved-flags.js";
+import { akmSearch, parseSearchSource } from "../read/search.js";
+import { rejectRetiredSourceFlag } from "../read/search-cli.js";
 import { akmTaskExplain } from "./explain.js";
 import { akmTasksAdd, akmTasksDoctor, akmTasksHistory, akmTasksPrune, akmTasksRun, akmTasksSync, akmTasksSyncPlan, } from "./tasks.js";
 import { akmTaskValidate } from "./validate.js";
@@ -480,6 +484,47 @@ const tasksPruneCommand = defineJsonCommand({
         outputWithExitCode("task-prune", result, taskPruneExitCode(result));
     },
 });
+/**
+ * #951: `akm task list` — a pure, zero-logic delegating alias for
+ * `akm search --type task`. 0.9.0 removed `task list` because it was a
+ * second, redundant IMPLEMENTATION of task listing, not because the
+ * spelling itself was off-limits; this reuses `search`'s exact envelope
+ * (its `results` alias comes along for free) instead of adding a second one.
+ * `query`/`--limit`/`--from` are handled identically to `searchCommand.run()`
+ * for the same inputs, including the retired `--source` guard (`../read/
+ * search-cli.ts`'s `rejectRetiredSourceFlag`, reused rather than copied) so
+ * `akm task list --source x` fails with the same actionable rename message
+ * as `akm search --type task --source x` instead of citty's silent absorb.
+ */
+const tasksListCommand = defineJsonCommand({
+    meta: { name: "list", description: "List task assets (alias for `akm search --type task`)" },
+    args: {
+        query: {
+            type: "positional",
+            description: "Search query (omit to list all tasks)",
+            required: false,
+            default: "",
+        },
+        limit: { type: "string", description: "Maximum number of results" },
+        from: { type: "string", description: "Search source (local|registry|all)", default: "local" },
+    },
+    async run({ args }) {
+        rejectRetiredSourceFlag();
+        const query = (args.query ?? "").trim();
+        const limit = parsePositiveIntFlag(args.limit ?? undefined);
+        const source = parseSearchSource(args.from);
+        const outputMode = getOutputMode();
+        const result = await akmSearch({
+            query,
+            type: "task",
+            limit,
+            source,
+            eventSource: resolveUsageEventSource(),
+            attributionProjection: outputMode.shape === "agent" ? "agent" : outputMode.detail,
+        });
+        output("search", result);
+    },
+});
 export const taskCommand = defineGroupCommand({
     meta: {
         name: "task",
@@ -491,12 +536,14 @@ export const taskCommand = defineGroupCommand({
         explain: tasksExplainCommand,
         validate: tasksValidateCommand,
         history: tasksHistoryCommand,
+        list: tasksListCommand,
         sync: tasksSyncCommand,
         prune: tasksPruneCommand,
         doctor: tasksDoctorCommand,
     },
-    // Bare `akm task` reports scheduler diagnostics. Inspection of individual
-    // tasks moved to the generic `akm search` / `akm show <bundle//tasks/id>`.
+    // Bare `akm task` reports scheduler diagnostics. Deeper inspection of
+    // individual tasks is the generic `akm show <bundle//tasks/id>`; `list`
+    // above is a delegating alias for `akm search --type task` (#951).
     // No `defaultRun`: bare `akm task` is a usage error (exit 2), the canonical
     // bare-group behavior — owner ruling 12. Run `akm task doctor` for what the
     // bare form used to run.