akm-cli 0.9.14 → 0.9.15-beta.1

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/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,6 +42,7 @@ 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";
@@ -66,6 +67,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 +86,23 @@ 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,
+                        startedAt: lockAcquisition.holder.startedAt,
+                    },
+                });
+                return;
+            }
             const outputMode = getOutputMode();
             const controller = new AbortController();
             const abort = () => controller.abort(new Error("index interrupted"));
@@ -98,6 +126,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}] ` : "";
@@ -126,6 +155,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.

package/dist/commands/workflow-cli.js

@@ -11,7 +11,8 @@ import { getStringArg } from "../cli/parse-args.js";
 import { defineGroupCommand, defineJsonCommand, EXIT_CODES, output, outputWithExitCode } from "../cli/shared.js";
 import { armAbortDeadline } from "../core/abort-deadline.js";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../core/asset/asset-create.js";
-import { NotFoundError, UsageError } from "../core/errors.js";
+import { NotFoundError, TransientError, UsageError } from "../core/errors.js";
+import { warn } from "../core/warn.js";
 import { akmIndex } from "../indexer/indexer.js";
 import { assertWorkflowMarkdownName, createWorkflowAsset, getWorkflowTemplate } from "../workflows/authoring/authoring.js";
 import { WORKFLOW_MAX_TIMEOUT_MS } from "../workflows/ir/schema.js";
@@ -30,10 +31,16 @@ const workflowStatusCommand = defineJsonCommand({
                 "diagnostic text). Diagnostics only — step evidence stays deterministic and is unaffected.",
             default: false,
         },
+        "all-scopes": {
+            type: "boolean",
+            description: "When resolving a workflow ref (not a run id), search every scope instead of only the current one (#942).",
+            default: false,
+        },
     },
     async run({ args }) {
         const target = args.target;
         const includeUnits = args.units === true;
+        const allScopes = args["all-scopes"] === true;
         const resolvedRunId = await resolveWorkflowRunTarget(target);
         if (resolvedRunId !== undefined) {
             const result = await getWorkflowStatus(resolvedRunId, { includeUnits });
@@ -41,8 +48,9 @@ const workflowStatusCommand = defineJsonCommand({
             return;
         }
         let runs;
+        let scopeKey;
         try {
-            ({ runs } = await listWorkflowRuns({ workflowRef: target }));
+            ({ runs, scopeKey } = await listWorkflowRuns({ workflowRef: target, allScopes }));
         }
         catch (error) {
             if (!target.includes(":") && !target.includes("/")) {
@@ -51,8 +59,17 @@ const workflowStatusCommand = defineJsonCommand({
             throw error;
         }
         const mostRecent = runs[0];
-        if (!mostRecent)
+        if (!mostRecent) {
+            // #942: name the scope actually searched and point at `--all-scopes`
+            // rather than a bare "not found" — the ref-fallthrough lookup is
+            // scope-local by default, so "no runs" here means "none in THIS
+            // scope", not "none anywhere". Already searching every scope (or no
+            // real scope was filtered on) has nothing more specific to suggest.
+            if (!allScopes && scopeKey !== null) {
+                throw new NotFoundError(`No workflow runs found for ${target} in scope ${scopeKey}.`, "WORKFLOW_NOT_FOUND", `Run 'akm workflow status ${target} --all-scopes' to search every scope.`);
+            }
             throw new NotFoundError(`No workflow runs found for ${target}`, "WORKFLOW_NOT_FOUND");
+        }
         const result = await getWorkflowStatus(mostRecent.id, { includeUnits });
         output("workflow-status", result);
     },
@@ -70,12 +87,20 @@ const workflowListCommand = defineJsonCommand({
             description: "Also include child workflow runs (hidden by default, P3b)",
             default: false,
         },
+        "all-scopes": {
+            type: "boolean",
+            description: "Search every scope instead of only the current one (#942). The envelope's top-level `scopeKey` is " +
+                "`null` with this flag, otherwise the scope that was searched — so an empty `runs: []` is never " +
+                'indistinguishable from "nothing anywhere".',
+            default: false,
+        },
     },
     async run({ args }) {
         const result = await listWorkflowRuns({
             workflowRef: args.ref,
             activeOnly: args.active,
             includeChildren: args.children,
+            allScopes: args["all-scopes"],
         });
         output("workflow-list", result);
     },
@@ -145,6 +170,20 @@ const workflowCreateCommand = defineJsonCommand({
         output("workflow-create", { ok: true, ...result });
     },
 });
+/**
+ * `--skip-if-locked` (#948) eligibility: only these two named, retryable
+ * `TransientError` codes (#948 addendum — moved off UsageError, exit 75) turn
+ * a `workflow run` failure into a graceful skip — `RUN_LEASE_HELD` (another
+ * engine invocation is driving THIS run, `workflow-runs-repository.ts`'s
+ * single-driver lease) and `STATE_DB_CONTENDED` (an unrelated akm process is
+ * writing state.db right now, `core/state-db.ts`'s BEGIN IMMEDIATE retry
+ * exhaustion). Every other error — a bad flag, an unresolvable target —
+ * still fails loudly.
+ */
+const WORKFLOW_RUN_SKIP_REASONS = {
+    RUN_LEASE_HELD: "lock-held",
+    STATE_DB_CONTENDED: "state-db-contended",
+};
 const workflowRunCommand = defineJsonCommand({
     meta: {
         name: "run",
@@ -161,6 +200,13 @@ const workflowRunCommand = defineJsonCommand({
                 "(never abandons it). A workflow ref only — passing a run id with --new is a usage error.",
             default: false,
         },
+        "skip-if-locked": {
+            type: "boolean",
+            description: "If another akm process already holds this run's engine lease, or state.db is busy with another " +
+                "writer, skip gracefully (exit 0) instead of failing (exit 75). Use for high-frequency scheduled runs " +
+                "so they don't pile up failures while a longer-running invocation is in progress.",
+            default: false,
+        },
     },
     async run({ args, rawArgs }) {
         const { runWorkflowSteps } = await import("../workflows/exec/run-workflow.js");
@@ -168,6 +214,7 @@ const workflowRunCommand = defineJsonCommand({
         const maxSteps = parseIntegerFlag(getStringArg(args, "max-steps"), "--max-steps", 1);
         const maxRetries = parseIntegerFlag(getStringArg(args, "max-retries"), "--max-retries", 0);
         const timeoutMs = parseWorkflowTimeout(getStringArg(args, "timeout"));
+        const skipIfLocked = args["skip-if-locked"];
         const controller = new AbortController();
         let signalExitCode;
         const interrupt = (signal) => {
@@ -185,14 +232,31 @@ const workflowRunCommand = defineJsonCommand({
             reason: `Workflow run timed out after ${timeoutMs}ms.`,
         });
         try {
-            const result = await runWorkflowSteps({
-                target: args.target,
-                parameterFlags,
-                ...(maxSteps !== undefined ? { maxSteps } : {}),
-                ...(maxRetries !== undefined ? { maxRetries } : {}),
-                newRun: args.new,
-                signal: controller.signal,
-            });
+            let result;
+            try {
+                result = await runWorkflowSteps({
+                    target: args.target,
+                    parameterFlags,
+                    ...(maxSteps !== undefined ? { maxSteps } : {}),
+                    ...(maxRetries !== undefined ? { maxRetries } : {}),
+                    newRun: args.new,
+                    signal: controller.signal,
+                });
+            }
+            catch (err) {
+                // #948: `--skip-if-locked` extends improve's "another run already
+                // holds this" skip semantics to `workflow run`. Only these two named,
+                // retryable TransientError codes are eligible (#948 addendum — moved
+                // off UsageError) — a bad flag or malformed input still fails loudly
+                // even with the flag set.
+                if (skipIfLocked && err instanceof TransientError && WORKFLOW_RUN_SKIP_REASONS[err.code]) {
+                    const reason = WORKFLOW_RUN_SKIP_REASONS[err.code];
+                    warn(`[workflow] ${err.message} skipping (--skip-if-locked)`);
+                    output("workflow-run", { ok: true, target: args.target, skipped: { reason, message: err.message } });
+                    return;
+                }
+                throw err;
+            }
             // The abort is observed between steps, so a deadline landing in the run's
             // final bookkeeping fires on a run that then finishes. Reporting that as
             // timed out would send an operator to resume a run with nothing left to
@@ -222,7 +286,17 @@ const WORKFLOW_RUN_VALUE_FLAGS = new Set([
     "shape",
     "output",
 ]);
-const WORKFLOW_RUN_BOOLEAN_FLAGS = new Set(["quiet", "verbose", "help", "no-quiet", "no-verbose", "new", "no-new"]);
+const WORKFLOW_RUN_BOOLEAN_FLAGS = new Set([
+    "quiet",
+    "verbose",
+    "help",
+    "no-quiet",
+    "no-verbose",
+    "new",
+    "no-new",
+    "skip-if-locked",
+    "no-skip-if-locked",
+]);
 export function parseWorkflowParameterFlags(rawArgs, target) {
     const flags = [];
     let targetSeen = false;

package/dist/core/asset/markdown-fragments.js

@@ -12,6 +12,8 @@ import { createHash } from "node:crypto";
 import { markdownHeadingSlug, parseMarkdownToc } from "./markdown.js";
 export const MARKDOWN_FRAGMENT_MAX_CHARS = 1600;
 export const MARKDOWN_FRAGMENT_PREFIX = "akm-fragment-";
+export const MARKDOWN_FRAGMENT_CONTEXT_DEFAULT_MAX_CHARS = 3200;
+export const MARKDOWN_FRAGMENT_SELECTED_LABEL = "[Selected matching fragment]";
 function hash(text) {
     return createHash("sha256").update(text).digest("hex");
 }
@@ -144,3 +146,36 @@ export function splitMarkdownFragments(body, maxChars = MARKDOWN_FRAGMENT_MAX_CH
 export function fragmentForSelector(body, selector) {
     return splitMarkdownFragments(body).find((fragment) => fragment.fragmentId === selector || fragment.headingSlug === selector);
 }
+/**
+ * Assemble the document lead and selected fragment under one hard character
+ * budget. The selected match is always labelled and last. When both pieces do
+ * not fit, lead bytes are discarded before any selected-fragment bytes so the
+ * evidence that caused retrieval remains intact whenever the caller's budget
+ * can hold it.
+ */
+export function buildMarkdownLeadContext(fragments, selectedOrdinal, maxChars = MARKDOWN_FRAGMENT_CONTEXT_DEFAULT_MAX_CHARS) {
+    if (!Number.isSafeInteger(maxChars) || maxChars <= 0) {
+        throw new RangeError("Markdown fragment context maxChars must be a positive safe integer");
+    }
+    const selected = fragments[selectedOrdinal];
+    if (!selected)
+        throw new RangeError(`Markdown fragment ordinal ${selectedOrdinal} is out of range`);
+    const selectedBlock = `${MARKDOWN_FRAGMENT_SELECTED_LABEL}\n${selected.text}`;
+    if (selectedBlock.length > maxChars) {
+        return { content: selectedBlock.slice(0, maxChars), truncated: true };
+    }
+    const lead = fragments[0];
+    if (!lead || lead.ordinal === selected.ordinal)
+        return { content: selectedBlock, truncated: false };
+    const separator = "\n\n";
+    const availableLeadChars = maxChars - selectedBlock.length - separator.length;
+    if (availableLeadChars <= 0)
+        return { content: selectedBlock, truncated: true };
+    const leadText = lead.text.slice(0, availableLeadChars).trimEnd();
+    if (!leadText)
+        return { content: selectedBlock, truncated: true };
+    return {
+        content: `${leadText}${separator}${selectedBlock}`,
+        truncated: leadText.length < lead.text.length,
+    };
+}