akm-cli 0.7.0-rc1 → 0.7.0

package/dist/src/output/text.js

@@ -120,6 +120,8 @@ export function formatPlain(command, result, detail) {
                 const flagText = flags.length > 0 ? ` [${flags.join(", ")}]` : "";
                 lines.push(`[${kind}] ${name}${ver}${prov}${flagText}`);
             }
+            lines.push("");
+            lines.push("To search: akm search '<query>'  |  To view an asset: akm show <ref>");
             return lines.join("\n");
         }
         case "add": {
@@ -597,6 +599,10 @@ export function formatHistoryPlain(r) {
         headerParts.push(`since: ${r.since}`);
     const totalCount = typeof r.totalCount === "number" ? r.totalCount : entries.length;
     headerParts.push(`${totalCount} event(s)`);
+    // Show active event sources so operators know which streams were consulted.
+    if (Array.isArray(r.sources) && r.sources.length > 0) {
+        headerParts.push(`sources: ${r.sources.join(", ")}`);
+    }
     const header = headerParts.join("  ");
     if (entries.length === 0) {
         const scope = typeof r.ref === "string" && r.ref ? ` for ${r.ref}` : "";
@@ -627,6 +633,9 @@ function formatShowPlain(r, detail) {
     if (r.type || r.name) {
         lines.push(`# ${String(r.type ?? "asset")}: ${String(r.name ?? "unknown")}`);
     }
+    if (r.path && r.editable !== false) {
+        lines.push(`file: ${String(r.path)}`);
+    }
     if (r.origin !== undefined)
         lines.push(`# origin: ${String(r.origin)}`);
     if (r.action)
@@ -677,7 +686,10 @@ function formatShowPlain(r, detail) {
             const id = typeof step.id === "string" ? step.id : "unknown";
             lines.push(`  ${index + 1}. ${title} [${id}]`);
             if (typeof step.instructions === "string" && step.instructions.trim()) {
-                lines.push(`     instructions: ${step.instructions.replace(/\n+/g, " ").trim()}`);
+                const instrLines = step.instructions.trim().split("\n");
+                lines.push(`     instructions: ${instrLines[0]}`);
+                for (const instrLine of instrLines.slice(1))
+                    lines.push(`       ${instrLine}`);
             }
             if (Array.isArray(step.completionCriteria) && step.completionCriteria.length > 0) {
                 lines.push("     completion:");
@@ -692,8 +704,94 @@ function formatShowPlain(r, detail) {
             lines.push("");
         lines.push(...payloads);
     }
+    // REC-01 / REC-09: Append a type-specific directive so agents apply the
+    // content rather than substituting training-data approximations.
+    const assetType = typeof r.type === "string" ? r.type : null;
+    const assetRef = typeof r.name === "string" && assetType ? `${assetType}:${r.name}` : null;
+    // Show-loop detection: if the agent has shown this asset 3+ times without
+    // writing anything, surface a warning so it stops cycling and acts.
+    const showLoopCount = typeof r.showLoopWarning === "number" ? r.showLoopWarning : 0;
+    if (showLoopCount >= 3) {
+        lines.push("");
+        lines.push(`WARNING: You have shown this asset ${showLoopCount} times without completing the task.`);
+        lines.push("Stop re-reading — you have the information you need. Act on it now:");
+        lines.push("  - Write your output file using the content above.");
+        lines.push(`  - If this asset does not contain what you need, run \`akm feedback '${assetRef ?? "<ref>"}' --negative\` and search for a different asset.`);
+    }
+    if (assetType === "skill" || assetType === "knowledge") {
+        const activeRun = r.activeRun;
+        if (activeRun) {
+            // Active workflow: redirect agent to workflow commands instead of direct apply
+            lines.unshift(`  akm workflow complete '${activeRun.runId}'${activeRun.stepId ? ` --step '${activeRun.stepId}'` : ""}`);
+            lines.unshift("Read this schema, then follow your workflow step's instructions to edit the workspace file. When done, mark the step complete:");
+            lines.unshift(`WORKFLOW ACTIVE — schema shown as reference (run: ${activeRun.runId})`);
+            lines.unshift("---");
+            lines.unshift("");
+            // Still show feedback line at the end but skip the APPLY directive
+            lines.push("");
+            lines.push(`Run \`akm feedback ${assetRef ? `'${assetRef}'` : "<ref>"} --positive\` if the step succeeds, or \`--negative\` if this schema did not help.`);
+        }
+        else {
+            // No active workflow: show the APPLY directive. Branch on whether this
+            // skill primarily teaches CLI commands (shell output) vs YAML schema.
+            const preApplyLines = [...lines];
+            lines.push("");
+            lines.push("---");
+            if (isCommandOutputSkill(preApplyLines)) {
+                lines.push("APPLY (only if no workflow step is required for this task):");
+                lines.push("  1. Identify the output file from README.md (typically commands.txt).");
+                lines.push("  2. Write the exact command syntax from the code blocks above — replace every placeholder (`<name>`, `<value>`) with a real, concrete value from your task context. Do not write placeholder text.");
+                lines.push("  3. Each command should be on a single line (no backslash line continuation unless the verifier expects it).");
+                lines.push(`Run \`akm feedback ${assetRef ? `'${assetRef}'` : "<ref>"} --positive\` after the task succeeds, or \`--negative\` if this reference did not contain the needed command syntax.`);
+            }
+            else {
+                lines.push("APPLY (only if no workflow step is required for this task):");
+                lines.push("  1. Identify the target file from README.md — write or edit it. If the file does not yet exist, CREATE it with the full structure from this schema.");
+                lines.push("  2. Add/edit the fields shown above using the exact field names from this schema.");
+                lines.push("  3. COPY the exact YAML structure and field names from the code blocks above — do not substitute synonyms or invent nesting. Replace every placeholder value with a real, concrete value from your task context. Do not leave any field as null, empty, or a placeholder.");
+                lines.push(`Run \`akm feedback ${assetRef ? `'${assetRef}'` : "<ref>"} --positive\` after the task succeeds, or \`--negative\` if the task fails after following this guidance.`);
+            }
+        }
+    }
+    else if (assetType === "workflow") {
+        const workflowName = typeof r.name === "string" ? r.name : null;
+        const workflowRef = workflowName ? `workflow:${workflowName}` : "<ref>";
+        // Insert action directive BEFORE the workflow content by prepending to lines at the
+        // separator position. We find where the header ends and insert after the first `---`.
+        // Since lines already contain the full content at this point, we locate the insertion
+        // index: right after the first `---` separator if present, otherwise after the header.
+        const separatorIdx = lines.indexOf("---");
+        const insertIdx = separatorIdx >= 0 ? separatorIdx + 1 : r.type || r.name ? 1 : 0;
+        const actionDirective = [
+            `ACTION REQUIRED: Do not execute steps manually from this output.`,
+            `Run \`akm workflow next '${workflowRef}'\` to get your current step with exact instructions.`,
+            "---",
+        ];
+        lines.splice(insertIdx, 0, "", ...actionDirective);
+        lines.push("");
+        lines.push("---");
+        lines.push(`NEXT STEP: Run \`akm workflow next '${workflowRef}'\` to see the current workflow step.`);
+        lines.push("Do not edit workspace files before completing each step with `akm workflow complete`.");
+    }
     return lines.length > 0 ? lines.join("\n") : null;
 }
+/**
+ * Detect whether a skill's rendered content primarily teaches CLI commands
+ * rather than YAML schema. Used to select the right APPLY directive variant.
+ *
+ * Heuristic: count code-block lines that start with known shell command
+ * prefixes vs lines that look like YAML key-value pairs. If CLI lines
+ * outnumber YAML lines (and there is at least one CLI line), treat the
+ * skill as command-output.
+ */
+function isCommandOutputSkill(lines) {
+    const codeLines = lines.filter((l) => l.startsWith("  ") || l.startsWith("\t") || /^`/.test(l));
+    const cliPattern = /^(az |kubectl |docker |git |helm |terraform |aws |gcloud )/;
+    const yamlPattern = /^\s+\w+:/;
+    const cliCount = codeLines.filter((l) => cliPattern.test(l.trim())).length;
+    const yamlCount = codeLines.filter((l) => yamlPattern.test(l)).length;
+    return cliCount > yamlCount && cliCount > 0;
+}
 export function formatWorkflowListPlain(result) {
     const runs = Array.isArray(result.runs) ? result.runs : [];
     if (runs.length === 0) {
@@ -747,7 +845,10 @@ export function formatWorkflowNextPlain(result) {
     const lines = base ? [base, "", "next:"] : ["next:"];
     lines.push(`  ${String(step.title ?? "Untitled step")} [${String(step.id ?? "unknown")}]`);
     if (typeof step.instructions === "string" && step.instructions.trim()) {
-        lines.push(`  instructions: ${step.instructions.replace(/\n+/g, " ").trim()}`);
+        const instrLines = step.instructions.trim().split("\n");
+        lines.push(`  instructions: ${instrLines[0]}`);
+        for (const instrLine of instrLines.slice(1))
+            lines.push(`    ${instrLine}`);
     }
     const completion = Array.isArray(step.completionCriteria) ? step.completionCriteria : [];
     if (completion.length > 0) {
@@ -756,6 +857,25 @@ export function formatWorkflowNextPlain(result) {
             lines.push(`    - ${String(criterion)}`);
         }
     }
+    // T2-3: surface run-id as labeled field
+    const run = typeof result.run === "object" && result.run !== null ? result.run : undefined;
+    const runId = typeof run?.id === "string" ? run.id : null;
+    const stepId = typeof step?.id === "string" ? step.id : null;
+    if (runId) {
+        lines.push("");
+        lines.push(`runId: ${runId}`);
+    }
+    // T1-6: complete command
+    if (runId && stepId) {
+        lines.push("");
+        lines.push("COMPLETE THIS STEP:");
+        lines.push(`  akm workflow complete '${runId}' --step '${stepId}'`);
+    }
+    else if (runId) {
+        lines.push("");
+        lines.push("COMPLETE THIS STEP:");
+        lines.push(`  akm workflow complete '${runId}' --step '<step-id>'`);
+    }
     return lines.join("\n");
 }
 export function formatSearchPlain(r, detail) {
@@ -763,7 +883,13 @@ export function formatSearchPlain(r, detail) {
     const registryHits = r.registryHits ?? [];
     const allHits = [...hits, ...registryHits];
     if (allHits.length === 0) {
-        return r.tip ? String(r.tip) : "No results found.";
+        const warnings = Array.isArray(r.warnings) ? r.warnings : [];
+        const hasSetupWarning = warnings.some((w) => String(w).toLowerCase().includes("no stash") || String(w).toLowerCase().includes("not configured"));
+        if (hasSetupWarning) {
+            return "No stash configured. Run `akm init` to create your working stash, then `akm index` to build the search index.";
+        }
+        const base = r.tip ? String(r.tip) : "No matches found.";
+        return `${base}\nTry:\n  akm search '<broader-term>'          # fewer keywords\n  akm list                             # see all configured sources\n  akm curate '<query>'                 # let akm select the best match`;
     }
     const lines = [];
     for (const hit of allHits) {
@@ -822,6 +948,27 @@ export function formatSearchPlain(r, detail) {
         if (parts.length > 0)
             lines.push(`timing: ${parts.join(", ")}`);
     }
+    // REC-02: When stash hits exist, tell the agent the next required step so it
+    // doesn't skip `akm show` and write from training memory instead.
+    if (hits.length >= 1) {
+        // Prefer skill/command/agent type hits for the "Next:" ref — knowledge docs are
+        // supplementary context, not the authoritative schema agents should load first.
+        const preferredHit = hits.find((h) => h.type === "skill" || h.type === "command" || h.type === "agent") ?? hits[0];
+        const topRef = typeof preferredHit.ref === "string" ? preferredHit.ref : null;
+        const hasWorkflowHit = hits.some((h) => h.type === "workflow");
+        if (topRef) {
+            if (hasWorkflowHit) {
+                const workflowRef = hits.find((h) => h.type === "workflow");
+                const wfRef = workflowRef && typeof workflowRef.ref === "string" ? workflowRef.ref : topRef;
+                lines.push(`Next: akm show '${topRef}'  |  To start a workflow: akm workflow next '${wfRef}'`);
+                lines.push("After running workflow next: follow each step and run `akm workflow complete <run-id> --step <step-id>` when done.");
+            }
+            else {
+                lines.push(`Next: akm show '${topRef}'`);
+                lines.push("After reading the asset: check whether a workflow applies before editing — if so, use `akm workflow next` instead.");
+            }
+        }
+    }
     return lines.join("\n").trimEnd();
 }
 export function formatWikiListPlain(r) {
@@ -959,5 +1106,11 @@ export function formatCuratePlain(r, detail) {
             lines.push(`- ${String(warning)}`);
         }
     }
+    lines.push("");
+    lines.push("Next steps:");
+    lines.push("  1. Run `akm show <ref>` for the best result above to read the full schema.");
+    lines.push("  2. Edit the workspace file using the schema field names and your task-specific values.");
+    lines.push("  3. Run `akm feedback <ref> --positive` when the task succeeds.");
+    lines.push("To search further: akm search '<query>'");
     return lines.join("\n");
 }

package/dist/src/registry/build-index.js

@@ -19,15 +19,16 @@ import { detectStashRoot } from "../sources/providers/provider-utils";
 import { extractTarGzSecure } from "../sources/providers/tar-utils";
 import { parseRegistryIndex } from "./providers/static-index";
 const DEFAULT_NPM_REGISTRY_BASE = "https://registry.npmjs.org";
-const DEFAULT_MANUAL_ENTRIES_PATH = path.resolve("manual-entries.json");
-const DEFAULT_OUTPUT_PATH = path.resolve("index.json");
 const REQUIRED_KEYWORDS = ["akm-stash"];
 const GITHUB_TOPICS = ["akm-stash"];
 const EXCLUDED_REPOS = new Set(["itlackey/akm"]);
 const EXCLUDED_NPM_PACKAGES = new Set(["akm-cli"]);
 const EMPTY_INSPECTION = {};
+function getDefaultRegistryBuildDir() {
+    return path.join(getCacheDir(), "registry-build");
+}
 export async function buildRegistryIndex(options) {
-    const manualEntriesPath = path.resolve(options?.manualEntriesPath ?? DEFAULT_MANUAL_ENTRIES_PATH);
+    const manualEntriesPath = path.resolve(options?.manualEntriesPath ?? path.join(getDefaultRegistryBuildDir(), "manual-entries.json"));
     const npmRegistryBase = trimTrailingSlash(options?.npmRegistryBase ?? DEFAULT_NPM_REGISTRY_BASE);
     const githubApiBase = trimTrailingSlash(options?.githubApiBase ?? GITHUB_API_BASE);
     const [manualKits, npmKits, githubKits] = await Promise.all([
@@ -55,7 +56,7 @@ export async function buildRegistryIndex(options) {
     };
 }
 export function writeRegistryIndex(index, outPath) {
-    const resolved = path.resolve(outPath ?? DEFAULT_OUTPUT_PATH);
+    const resolved = path.resolve(outPath ?? path.join(getDefaultRegistryBuildDir(), "index.json"));
     fs.mkdirSync(path.dirname(resolved), { recursive: true });
     fs.writeFileSync(resolved, `${JSON.stringify(index, null, 2)}\n`, "utf8");
     return resolved;

package/dist/src/registry/providers/static-index.js

@@ -190,7 +190,9 @@ export function parseRegistryIndex(data) {
     if (typeof data !== "object" || data === null || Array.isArray(data))
         return null;
     const obj = data;
-    if (typeof obj.version !== "number" || obj.version !== 3)
+    // Accept version 2 and 3 — both use the same stashes[] wire format.
+    // The live official registry currently publishes version 2.
+    if (typeof obj.version !== "number" || (obj.version !== 2 && obj.version !== 3))
         return null;
     if (typeof obj.updatedAt !== "string")
         return null;

package/dist/src/setup/setup.js

@@ -283,6 +283,7 @@ async function stepOllama(current) {
             mxbai: 1024,
             minilm: 384,
             bge: 384,
+            qwen3: 1024,
         };
         const guessedDim = Object.entries(knownDims).find(([k]) => embChoice.includes(k))?.[1] ?? 384;
         p.note("Embedding dimension must match the model. Common values: 384 (BGE small), 768 (BGE base), 1024 (BGE large). Press Enter to accept the detected default.", "Embedding dimension");
@@ -302,6 +303,14 @@ async function stepOllama(current) {
             model: embChoice,
             dimension: Number(dimChoice),
         };
+        p.note([
+            "Recommended Qwen embedding models (modern, high context support):",
+            "  • qwen3-embedding-0.6b  — fast and lightweight (ollama pull qwen3-embedding-0.6b)",
+            "  • qwen3-embedding-4b    — higher quality (ollama pull qwen3-embedding-4b)",
+            "",
+            "For long documents (wiki pages, large files), set context length to avoid 400 errors:",
+            "  akm config set embedding.contextLength 8192",
+        ].join("\n"), "Embedding tips");
     }
     // else: undefined → use built-in local
     // Surface Ollama details to the LLM step so it can offer Ollama as a preset.

package/dist/src/wiki/wiki.js

@@ -11,6 +11,32 @@
  * Principle: "akm surfaces. The agent writes." akm owns lifecycle, raw-slug
  * generation, structural lint, and `index.md` regeneration. The agent uses
  * its native file tools for every other page operation.
+ *
+ * ## Canonical wiki content contract
+ *
+ * The three "infrastructure" files at the wiki root — `schema.md`, `index.md`,
+ * and `log.md` — are excluded from all user-facing content surfaces:
+ *
+ *   | Surface              | schema/index/log | raw/<slug>.md | <page>.md |
+ *   | -------------------- | ---------------- | ------------- | --------- |
+ *   | `wiki pages`         | excluded         | included      | included  |
+ *   | scoped wiki search   | excluded         | included      | included  |
+ *   | stash-wide FTS index | excluded         | included      | included  |
+ *   | `wiki lint`          | excluded         | tracked       | tracked   |
+ *
+ * `raw/` files are first-class addressable content (`wiki:<n>/raw/<slug>`),
+ * searchable, and listed. They are NOT authored pages — they are source
+ * material the agent turns into pages. `lint` tracks whether each raw file
+ * has been cited by a page's `sources:` frontmatter field.
+ *
+ * ## Regeneration contract
+ *
+ * `regenerateWikiIndex` / `regenerateAllWikiIndexes` apply ONLY to
+ * stash-owned wikis (directories under `<stashDir>/wikis/`).  External wikis
+ * registered via `akm wiki register` are read-only caches; mutating their
+ * `index.md` would corrupt source-of-truth content that akm does not own.
+ * The indexer therefore calls `regenerateAllWikiIndexes(stashDir)` — which
+ * only iterates `<stashDir>/wikis/` — and never touches registered sources.
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -496,10 +522,15 @@ function readPageFrontmatter(absPath) {
     return out;
 }
 /**
- * List the addressable markdown entries in a wiki, excluding only the
- * infrastructure files `schema.md`, `index.md`, and `log.md`. This includes
- * both authored pages and `raw/` sources so `wiki pages` can inventory content
- * written via `akm wiki stash`.
+ * List all addressable wiki content entries.
+ *
+ * Per the canonical wiki contract: `schema.md`, `index.md`, and `log.md` at
+ * the wiki root are infrastructure files and are excluded. Everything else —
+ * authored pages AND `raw/<slug>.md` sources — is included and addressable as
+ * `wiki:<name>/<rel-path-without-.md>`.
+ *
+ * Callers that need to distinguish authored pages from raw sources should
+ * check whether the returned `name` starts with `"raw/"`.
  */
 export function listPages(stashDir, name) {
     const wikiDir = resolveWikiSource(stashDir, name).path;
@@ -521,6 +552,10 @@ export function listPages(stashDir, name) {
  * Uses `akmSearch({ type: "wiki" })` to reuse the full FTS5+boost pipeline,
  * then drops hits that aren't inside `wikis/<name>/`. No parallel scorer.
  *
+ * Per the canonical wiki contract: infrastructure files (`schema.md`,
+ * `index.md`, `log.md`) at the wiki root are excluded. `raw/<slug>.md`
+ * sources are included — they are first-class addressable content.
+ *
  * When the index is absent (e.g. fresh stash), `akmSearch` falls back to its
  * substring walker; hits still come through path-filtered here.
  */
@@ -795,7 +830,13 @@ export function lintWiki(stashDir, name) {
 }
 // ── Index regeneration ─────────────────────────────────────────────────────
 /**
- * Rebuild a wiki's `index.md` from its pages' frontmatter.
+ * Rebuild a stash-owned wiki's `index.md` from its pages' frontmatter.
+ *
+ * This function uses `resolveWikiDir` (not `resolveWikiSource`) so it only
+ * ever operates on the stash-owned path `<stashDir>/wikis/<name>/`. External
+ * wikis registered via `akm wiki register` are never regenerated here — they
+ * are read-only caches. See the canonical wiki contract at the top of this
+ * file for the full regeneration rule.
  *
  * Pages are grouped by `pageKind` (falling back to `uncategorised`) and
  * listed alphabetically inside each group. If the wiki directory doesn't
@@ -861,7 +902,14 @@ export function regenerateWikiIndex(stashDir, name) {
     }
 }
 /**
- * Regenerate `index.md` for every wiki found under `<stashDir>/wikis/`.
+ * Regenerate `index.md` for every stash-owned wiki under `<stashDir>/wikis/`.
+ *
+ * Per the canonical wiki contract: regeneration applies ONLY to stash-owned
+ * wikis. External wikis registered via `akm wiki register` are read-only
+ * caches whose source-of-truth lives outside this stash; mutating their
+ * `index.md` would corrupt content that akm does not own. Those wikis
+ * therefore appear only in the FTS index (read), never in regeneration
+ * (write).
  *
  * Called from `akmIndex()` as a side effect after the FTS rebuild. Never
  * throws; returns the list of wiki names that were regenerated.

package/dist/src/workflows/runs.js

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import { parseAssetRef } from "../core/asset-ref";
 import { loadConfig } from "../core/config";
 import { NotFoundError, UsageError } from "../core/errors";
+import { appendEvent } from "../core/events";
 import { getDbPath } from "../core/paths";
 import { closeDatabase, openDatabase } from "../indexer/db";
 import { resolveSourceEntries } from "../indexer/search-source";
@@ -32,7 +33,13 @@ export async function startWorkflowRun(ref, params = {}) {
                 insertStep.run(runId, step.id, step.title, step.instructions, step.completionCriteria ? JSON.stringify(step.completionCriteria) : null, step.sequenceIndex ?? 0);
             }
         })();
-        return getWorkflowStatus(runId);
+        const result = getWorkflowStatus(runId);
+        appendEvent({
+            eventType: "workflow_started",
+            ref: ref,
+            metadata: { runId: result.run.id, title: result.run.workflowTitle },
+        });
+        return result;
     }
     finally {
         closeWorkflowDatabase(workflowDb);
@@ -173,7 +180,16 @@ export function completeWorkflowStep(input) {
                 completed_at: state.completedAt,
             };
         })();
-        return buildWorkflowRunDetail(updatedRun, refreshedSteps);
+        const detail = buildWorkflowRunDetail(updatedRun, refreshedSteps);
+        appendEvent({
+            eventType: "workflow_step_completed",
+            ref: detail.run.workflowRef,
+            metadata: { runId: input.runId, stepId: input.stepId, notes: input.notes },
+        });
+        if (detail.run.status === "completed") {
+            appendEvent({ eventType: "workflow_finished", ref: detail.run.workflowRef, metadata: { runId: input.runId } });
+        }
+        return detail;
     }
     finally {
         closeWorkflowDatabase(workflowDb);
@@ -187,6 +203,9 @@ async function resolveRunSpecifier(db, specifier, params) {
         }
         return { run: explicitRun, autoStarted: false };
     }
+    if (!specifier.includes(":")) {
+        throw new NotFoundError(`Workflow run "${specifier}" not found.`, "WORKFLOW_NOT_FOUND");
+    }
     const parsed = parseAssetRef(specifier);
     if (parsed.type !== "workflow") {
         throw new UsageError(`Expected a workflow ref or workflow run id, got "${specifier}".`);
@@ -316,7 +335,7 @@ function resolveWorkflowEntryId(sourcePath, ref) {
 function readWorkflowRun(db, runId) {
     const run = db.prepare("SELECT * FROM workflow_runs WHERE id = ?").get(runId);
     if (!run) {
-        throw new NotFoundError(`Workflow run not found: ${runId}`);
+        throw new NotFoundError(`Workflow run "${runId}" not found.`, "WORKFLOW_NOT_FOUND");
     }
     return run;
 }
@@ -416,3 +435,18 @@ function parseJsonArray(value) {
     }
     return undefined;
 }
+export function getActiveWorkflowRun() {
+    try {
+        const workflowDb = openWorkflowDatabase();
+        const row = workflowDb
+            .query("SELECT id, current_step_id, workflow_ref FROM workflow_runs WHERE status IN ('active', 'blocked') ORDER BY updated_at DESC LIMIT 1")
+            .get();
+        closeWorkflowDatabase(workflowDb);
+        if (!row)
+            return null;
+        return { runId: row.id, stepId: row.current_step_id, workflowRef: row.workflow_ref };
+    }
+    catch {
+        return null; // fail-open: never crash show output due to DB error
+    }
+}

package/dist/tests/architecture/agent-no-llm-sdk-guard.test.js

@@ -81,7 +81,7 @@ function listAgentSourceFiles() {
  */
 function buildImportRegex(pkg) {
     const escaped = pkg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    return new RegExp(String.raw `(?:from|import\(|require\()\s*['"]` + escaped + `(?:/[^'"]*)?['"]`);
+    return new RegExp(`${String.raw `(?:from|import\(|require\()\s*['"]` + escaped}(?:/[^'"]*)?['"]`);
 }
 describe("regression guard: src/integrations/agent/** never imports LLM SDKs", () => {
     test("the agent integration tree exists", () => {

package/dist/tests/bench/attribution.test.js

@@ -43,13 +43,14 @@ function makeReport(akmRuns) {
         commit: "abc",
         model: "m",
         corpus: { domains: 1, tasks: 1, slice: "all", seedsPerArm: akmRuns.length },
-        aggregateNoakm: { passRate: 0, tokensPerPass: null, wallclockMs: 0 },
+        aggregateNoakm: { passRate: 0, tokensPerPass: null, tokensPerRun: null, wallclockMs: 0 },
         aggregateAkm: {
             passRate: akmRuns.filter((r) => r.outcome === "pass").length / Math.max(1, akmRuns.length),
             tokensPerPass: null,
+            tokensPerRun: null,
             wallclockMs: 0,
         },
-        aggregateDelta: { passRate: 0, tokensPerPass: null, wallclockMs: 0 },
+        aggregateDelta: { passRate: 0, tokensPerPass: null, tokensPerRun: null, wallclockMs: 0 },
         trajectoryAkm: { correctAssetLoaded: null, feedbackRecorded: 0 },
         failureModes: { byLabel: {}, byTask: {} },
         tasks: [],
@@ -251,7 +252,7 @@ describe("runMaskedCorpus", () => {
             const passRate = alphaMissing ? 0.25 : 0.6;
             return {
                 ...baseReport,
-                aggregateAkm: { passRate, tokensPerPass: null, wallclockMs: 0 },
+                aggregateAkm: { passRate, tokensPerPass: null, tokensPerRun: null, wallclockMs: 0 },
                 akmRuns: [],
             };
         };
@@ -334,7 +335,7 @@ describe("runMaskedCorpus", () => {
                 observedTaskStashUnchanged = task?.stash === "fixtureA";
                 return {
                     ...baseReport,
-                    aggregateAkm: { passRate: 0, tokensPerPass: null, wallclockMs: 0 },
+                    aggregateAkm: { passRate: 0, tokensPerPass: null, tokensPerRun: null, wallclockMs: 0 },
                     akmRuns: [],
                 };
             },
@@ -377,7 +378,7 @@ describe("runMaskedCorpus", () => {
             topN: 2,
             runUtility: async () => ({
                 ...baseReport,
-                aggregateAkm: { passRate: 0, tokensPerPass: null, wallclockMs: 0 },
+                aggregateAkm: { passRate: 0, tokensPerPass: null, tokensPerRun: null, wallclockMs: 0 },
                 akmRuns: [],
             }),
             baseOptions: { arms: ["akm"], model: "m", seedsPerArm: 1 },
@@ -414,7 +415,7 @@ describe("runMaskedCorpus", () => {
                     successDirs.push(dir);
                 return {
                     ...baseReport,
-                    aggregateAkm: { passRate: 0, tokensPerPass: null, wallclockMs: 0 },
+                    aggregateAkm: { passRate: 0, tokensPerPass: null, tokensPerRun: null, wallclockMs: 0 },
                     akmRuns: [],
                 };
             },
@@ -440,7 +441,7 @@ describe("runMaskedCorpus", () => {
                     throw new Error("simulated runner failure");
                 return {
                     ...baseReport,
-                    aggregateAkm: { passRate: 0, tokensPerPass: null, wallclockMs: 0 },
+                    aggregateAkm: { passRate: 0, tokensPerPass: null, tokensPerRun: null, wallclockMs: 0 },
                     akmRuns: [],
                 };
             },
@@ -480,7 +481,7 @@ describe("runMaskedCorpus", () => {
                 callCount += 1;
                 return {
                     ...baseReport,
-                    aggregateAkm: { passRate: 0, tokensPerPass: null, wallclockMs: 0 },
+                    aggregateAkm: { passRate: 0, tokensPerPass: null, tokensPerRun: null, wallclockMs: 0 },
                 };
             },
             baseOptions: { arms: ["akm"], model: "m", seedsPerArm: 1 },
@@ -521,7 +522,7 @@ describe("runMaskedCorpus", () => {
                 callCount += 1;
                 return {
                     ...baseReport,
-                    aggregateAkm: { passRate: 0, tokensPerPass: null, wallclockMs: 0 },
+                    aggregateAkm: { passRate: 0, tokensPerPass: null, tokensPerRun: null, wallclockMs: 0 },
                 };
             },
             baseOptions: { arms: ["akm"], model: "m", seedsPerArm: 1 },
@@ -551,7 +552,7 @@ describe("runMaskedCorpus", () => {
                 callCount += 1;
                 return {
                     ...baseReport,
-                    aggregateAkm: { passRate: 0, tokensPerPass: null, wallclockMs: 0 },
+                    aggregateAkm: { passRate: 0, tokensPerPass: null, tokensPerRun: null, wallclockMs: 0 },
                 };
             },
             baseOptions: { arms: ["akm"], model: "m", seedsPerArm: 1 },
@@ -626,9 +627,9 @@ describe("bench attribute --top clamping", () => {
                     commit: "abc",
                     model: "test-model",
                     corpus: { domains: 1, tasks: 0, slice: "all", seedsPerArm: 1 },
-                    aggregateNoakm: { passRate: 0, tokensPerPass: null, wallclockMs: 0 },
-                    aggregateAkm: { passRate: 0, tokensPerPass: null, wallclockMs: 0 },
-                    aggregateDelta: { passRate: 0, tokensPerPass: null, wallclockMs: 0 },
+                    aggregateNoakm: { passRate: 0, tokensPerPass: null, tokensPerRun: null, wallclockMs: 0 },
+                    aggregateAkm: { passRate: 0, tokensPerPass: null, tokensPerRun: null, wallclockMs: 0 },
+                    aggregateDelta: { passRate: 0, tokensPerPass: null, tokensPerRun: null, wallclockMs: 0 },
                     trajectoryAkm: { correctAssetLoaded: null, feedbackRecorded: 0 },
                     failureModes: { byLabel: {}, byTask: {} },
                     tasks: [],
@@ -686,11 +687,11 @@ describe("runMaskedCorpus marginal_contribution arithmetic", () => {
             commit: "abc",
             model: "m",
             corpus: { domains: 1, tasks: 1, slice: "all", seedsPerArm: baseRuns.length },
-            aggregateNoakm: { passRate: 0, tokensPerPass: null, wallclockMs: 0 },
+            aggregateNoakm: { passRate: 0, tokensPerPass: null, tokensPerRun: null, wallclockMs: 0 },
             // Engineered base pass rate distinct from the masked rates so the
             // arithmetic is observable.
-            aggregateAkm: { passRate: 0.8, tokensPerPass: null, wallclockMs: 0 },
-            aggregateDelta: { passRate: 0.8, tokensPerPass: null, wallclockMs: 0 },
+            aggregateAkm: { passRate: 0.8, tokensPerPass: null, tokensPerRun: null, wallclockMs: 0 },
+            aggregateDelta: { passRate: 0.8, tokensPerPass: null, tokensPerRun: null, wallclockMs: 0 },
             trajectoryAkm: { correctAssetLoaded: null, feedbackRecorded: 0 },
             failureModes: { byLabel: {}, byTask: {} },
             tasks: [],
@@ -730,7 +731,7 @@ describe("runMaskedCorpus marginal_contribution arithmetic", () => {
                 const passRate = maskedPassRates[masked] ?? 0;
                 return {
                     ...baseReport,
-                    aggregateAkm: { passRate, tokensPerPass: null, wallclockMs: 0 },
+                    aggregateAkm: { passRate, tokensPerPass: null, tokensPerRun: null, wallclockMs: 0 },
                     akmRuns: [],
                 };
             },
@@ -875,9 +876,9 @@ describe("bench attribute prefers persisted runs[] (#249)", () => {
                     commit: "abc",
                     model: "test-model",
                     corpus: { domains: 1, tasks: 1, slice: "all", seedsPerArm: 2 },
-                    aggregateNoakm: { passRate: 0, tokensPerPass: null, wallclockMs: 0 },
-                    aggregateAkm: { passRate: 0.25, tokensPerPass: null, wallclockMs: 0 },
-                    aggregateDelta: { passRate: 0.25, tokensPerPass: null, wallclockMs: 0 },
+                    aggregateNoakm: { passRate: 0, tokensPerPass: null, tokensPerRun: null, wallclockMs: 0 },
+                    aggregateAkm: { passRate: 0.25, tokensPerPass: null, tokensPerRun: null, wallclockMs: 0 },
+                    aggregateDelta: { passRate: 0.25, tokensPerPass: null, tokensPerRun: null, wallclockMs: 0 },
                     trajectoryAkm: { correctAssetLoaded: null, feedbackRecorded: 0 },
                     failureModes: { byLabel: {}, byTask: {} },
                     tasks: [],
@@ -948,9 +949,9 @@ describe("bench attribute prefers persisted runs[] (#249)", () => {
                     commit: "abc",
                     model: "test-model",
                     corpus: { domains: 1, tasks: 0, slice: "all", seedsPerArm: 1 },
-                    aggregateNoakm: { passRate: 0, tokensPerPass: null, wallclockMs: 0 },
-                    aggregateAkm: { passRate: 0, tokensPerPass: null, wallclockMs: 0 },
-                    aggregateDelta: { passRate: 0, tokensPerPass: null, wallclockMs: 0 },
+                    aggregateNoakm: { passRate: 0, tokensPerPass: null, tokensPerRun: null, wallclockMs: 0 },
+                    aggregateAkm: { passRate: 0, tokensPerPass: null, tokensPerRun: null, wallclockMs: 0 },
+                    aggregateDelta: { passRate: 0, tokensPerPass: null, tokensPerRun: null, wallclockMs: 0 },
                     trajectoryAkm: { correctAssetLoaded: null, feedbackRecorded: 0 },
                     failureModes: { byLabel: {}, byTask: {} },
                     tasks: [],