akm-cli 0.6.1 → 0.7.0

package/dist/{registry → src/registry}/build-index.js

@@ -8,9 +8,9 @@
  * updated together with this builder.
  */
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
 import { fetchWithRetry, jsonWithByteCap } from "../core/common";
+import { getCacheDir } from "../core/paths";
 import { generateMetadataFlat, loadStashFile } from "../indexer/metadata";
 import { walkStashFlat } from "../indexer/walker";
 import { asRecord, asString, GITHUB_API_BASE, githubHeaders } from "../integrations/github";
@@ -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;
@@ -173,7 +174,16 @@ async function scanGithub(githubApiBase) {
     return stashes;
 }
 async function inspectArchive(url, headers) {
-    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "akm-registry-build-"));
+    // Route registry-build scratch space under the akm cache dir instead of
+    // the system temp directory. Long-running registry builds that crash
+    // mid-flight previously left orphan dirs under `/tmp`, which can fill
+    // the OS partition. Pinning to `${getCacheDir()}/registry-build/` keeps
+    // a single `rm -rf` of that directory sufficient to reclaim the space
+    // and leaves the operator's `/tmp` untouched. See #276 for the
+    // bench-tmp precedent and #284 for this non-bench rollout.
+    const tmpRoot = path.join(getCacheDir(), "registry-build");
+    fs.mkdirSync(tmpRoot, { recursive: true });
+    const tempDir = fs.mkdtempSync(path.join(tmpRoot, "build-"));
     const archivePath = path.join(tempDir, "archive.tgz");
     const extractDir = path.join(tempDir, "extract");
     try {
@@ -283,7 +293,9 @@ async function loadManualEntries(manualEntriesPath) {
         const parsed = parseRegistryIndex({ version: 3, updatedAt: new Date().toISOString(), stashes: candidateKits });
         if (!parsed)
             return [];
-        return parsed.stashes.map((stash) => normalizeStash({ ...stash, curated: stash.curated ?? true }));
+        // Legacy `curated` flag on input entries is ignored (v1 spec §4.2). The
+        // builder no longer emits it on the resulting index.
+        return parsed.stashes.map((stash) => normalizeStash(stash));
     }
     catch {
         return [];
@@ -327,7 +339,6 @@ function mergeEntries(a, b) {
         author: a.author ?? b.author,
         license: a.license ?? b.license,
         latestVersion: a.latestVersion ?? b.latestVersion,
-        curated: a.curated || b.curated || undefined,
     });
 }
 function mergeAssets(a, b) {

package/dist/{registry → src/registry}/factory.js

@@ -23,11 +23,3 @@ export function registerProvider(type, factory) {
 export function resolveProviderFactory(type) {
     return registry.resolve(type);
 }
-/**
- * Iterate over all registered registry providers. Used by the orchestrator
- * (`src/commands/registry-search.ts`) to fan out queries through the same
- * `RegistryProvider` interface regardless of provider kind.
- */
-export function listProviderTypes() {
-    return registry.list();
-}

package/dist/{registry → 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;
@@ -213,6 +215,9 @@ function parseStashEntry(raw) {
     const source = asSource(obj.source);
     if (!id || !name || !ref || !source)
         return null;
+    // The legacy registry boolean `curated` is removed in v1. Legacy index JSON
+    // containing a `curated` key parses normally; the key is silently ignored
+    // (v1 spec §4.2, docs/migration/v1.md).
     return {
         id,
         name,
@@ -226,7 +231,6 @@ function parseStashEntry(raw) {
         author: asString(obj.author),
         license: asString(obj.license),
         latestVersion: asString(obj.latestVersion),
-        curated: obj.curated === true ? true : undefined,
     };
 }
 // ── Scoring ─────────────────────────────────────────────────────────────────
@@ -294,7 +298,6 @@ function toSearchHit(stash, score, registryName) {
         homepage: stash.homepage,
         score: Math.round(score * 1000) / 1000,
         metadata,
-        curated: stash.curated,
         registryName,
     };
 }

package/dist/{registry → src/registry}/resolve.js

@@ -4,7 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { fetchWithRetry, jsonWithByteCap } from "../core/common";
-import { UsageError } from "../core/errors";
+import { NotFoundError, UsageError } from "../core/errors";
 import { asRecord, asString, GITHUB_API_BASE, githubHeaders } from "../integrations/github";
 /**
  * Validate that a URL is safe to pass to git.
@@ -200,7 +200,7 @@ function tryParseLocalRef(rawRef, explicitPath) {
     catch {
         // Explicit paths (./foo, ../bar, /abs) should throw on missing
         if (explicitPath) {
-            throw new Error(`Local path not found: ${resolvedPath}`);
+            throw new NotFoundError(`Local path not found: ${resolvedPath}`, "FILE_NOT_FOUND", "Check the path exists and is readable.");
         }
         // Bare names that don't exist on disk — let caller fall through to npm/github
         return undefined;
@@ -231,6 +231,71 @@ function isPathLikeRef(ref) {
     }
     return ref.includes("/") || ref.includes("\\");
 }
+/** Default public npm registry host. */
+const DEFAULT_NPM_REGISTRY_HOST = "registry.npmjs.org";
+/**
+ * Typed error raised when the npm registry returns a tarball URL on a host
+ * that is not the public registry or the operator-configured mirror. Carries
+ * a stable `.code` so callers (and JSON envelope output) can branch on it
+ * without parsing the message string.
+ */
+export class UntrustedNpmTarballError extends Error {
+    code = "UNTRUSTED_NPM_TARBALL";
+    _hint;
+    constructor(msg, hint) {
+        super(msg);
+        this.name = "UntrustedNpmTarballError";
+        this._hint = hint;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+    hint() {
+        return (this._hint ??
+            "Set AKM_NPM_REGISTRY to your private npm mirror's base URL if you install from a non-default registry.");
+    }
+}
+/**
+ * Resolve the set of npm registry hosts whose tarballs are considered trusted.
+ * Always includes the public npm registry, plus the host of an operator-set
+ * `AKM_NPM_REGISTRY` environment variable (if it parses to a valid URL).
+ */
+export function trustedNpmTarballHosts() {
+    const hosts = new Set([DEFAULT_NPM_REGISTRY_HOST]);
+    const override = process.env.AKM_NPM_REGISTRY?.trim();
+    if (override) {
+        try {
+            const overrideHost = new URL(override).hostname.toLowerCase();
+            if (overrideHost)
+                hosts.add(overrideHost);
+        }
+        catch {
+            // Ignore unparseable overrides; the default host still applies.
+        }
+    }
+    return hosts;
+}
+/**
+ * Validate that an npm tarball URL points at a trusted registry host. A
+ * compromised mirror could otherwise return an attacker-controlled
+ * `dist.tarball` field, redirecting installs to a third-party host.
+ */
+export function validateNpmTarballUrl(tarballUrl, packageRef) {
+    let url;
+    try {
+        url = new URL(tarballUrl);
+    }
+    catch {
+        throw new UntrustedNpmTarballError(`npm package ${packageRef} returned an invalid tarball URL: ${tarballUrl}`);
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw new UntrustedNpmTarballError(`npm package ${packageRef} returned a tarball with disallowed scheme "${url.protocol}".`);
+    }
+    const trusted = trustedNpmTarballHosts();
+    const host = url.hostname.toLowerCase();
+    if (!trusted.has(host)) {
+        const allowed = Array.from(trusted).join(", ");
+        throw new UntrustedNpmTarballError(`npm package ${packageRef} returned a tarball URL on untrusted host "${host}" (allowed: ${allowed}).`);
+    }
+}
 async function resolveNpmArtifact(parsed) {
     const encodedName = encodeURIComponent(parsed.packageName);
     const metadata = await fetchJson(`https://registry.npmjs.org/${encodedName}`);
@@ -262,6 +327,7 @@ async function resolveNpmArtifact(parsed) {
     if (!tarballUrl) {
         throw new Error(`npm package ${parsed.packageName}@${resolvedVersion} does not expose a tarball URL.`);
     }
+    validateNpmTarballUrl(tarballUrl, `${parsed.packageName}@${resolvedVersion}`);
     const resolvedRevision = asString(dist.shasum) ?? asString(dist.integrity);
     return {
         id: parsed.id,

package/dist/{setup → src/setup}/setup.js

@@ -14,6 +14,7 @@ import { getDefaultStashDir } from "../core/paths";
 import { closeDatabase, isVecAvailable, openDatabase } from "../indexer/db";
 import { akmIndex } from "../indexer/indexer";
 import { clearSemanticStatus, deriveSemanticProviderFingerprint, writeSemanticStatus, } from "../indexer/semantic-status";
+import { detectAgentCliProfiles, pickDefaultAgentProfile, } from "../integrations/agent";
 import { probeLlmCapabilities } from "../llm/client";
 import { checkEmbeddingAvailability, DEFAULT_LOCAL_MODEL, isTransformersAvailable } from "../llm/embedder";
 import { detectAgentPlatforms, detectOllama } from "./detect";
@@ -282,8 +283,10 @@ 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");
         const dimChoice = await prompt(() => p.text({
             message: `Embedding dimension for ${embChoice}:`,
             placeholder: String(guessedDim),
@@ -300,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.
@@ -313,7 +324,6 @@ const LLM_PRESETS = [
         endpoint: "https://api.anthropic.com/v1/chat/completions",
         defaultModel: "claude-sonnet-4-5",
         hint: "beta OpenAI-compat layer; set AKM_LLM_API_KEY; override the model if the default is unavailable",
-        contextWindow: 200_000,
     },
     {
         value: "openai",
@@ -321,7 +331,6 @@ const LLM_PRESETS = [
         endpoint: "https://api.openai.com/v1/chat/completions",
         defaultModel: "gpt-4o-mini",
         hint: "AKM_LLM_API_KEY required",
-        contextWindow: 128_000,
     },
     {
         value: "google",
@@ -329,7 +338,6 @@ const LLM_PRESETS = [
         endpoint: "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions",
         defaultModel: "gemini-2.0-flash",
         hint: "OpenAI-compat endpoint, AKM_LLM_API_KEY required",
-        contextWindow: 1_000_000,
     },
 ];
 /**
@@ -431,7 +439,6 @@ export async function stepLlm(current, ollamaEndpoint, ollamaChatModels) {
             model: model.trim() || preset.defaultModel,
             temperature: 0.3,
             maxTokens: 1024,
-            contextWindow: preset.contextWindow,
         };
     }
     // Remind the user about API key placement. We do not offer a "store in config"
@@ -649,6 +656,29 @@ async function stepAgentPlatforms(current) {
     }
     return entries;
 }
+/**
+ * Detect installed agent CLIs and produce an updated `agent` config block
+ * with a sensible `default` (the first detected profile that the user has
+ * not already overridden).
+ *
+ * Pure-ish: file system / PATH probes are routed through `detectFn` so
+ * tests can drive the branches without touching the real PATH.
+ *
+ * @internal Exported for testing only.
+ */
+export function stepAgentCliDetection(current, detectFn = detectAgentCliProfiles) {
+    const detections = detectFn(current.agent);
+    const defaultName = pickDefaultAgentProfile(detections, current.agent?.default);
+    // No installed agents found and no existing config → leave block absent.
+    if (!defaultName && !current.agent) {
+        return { detections };
+    }
+    const agent = {
+        ...(current.agent ?? {}),
+        ...(defaultName ? { default: defaultName } : {}),
+    };
+    return { agent, detections };
+}
 // ── Main Wizard ─────────────────────────────────────────────────────────────
 /**
  * Build the canonical list of `SetupStep`s for the interactive wizard.
@@ -731,6 +761,23 @@ export function buildSetupSteps(options) {
                 ctx.apply({ sources: merged.length > 0 ? merged : undefined });
             },
         },
+        {
+            id: "agent-cli",
+            label: "Agent CLI",
+            nonInteractive: true,
+            async run(ctx) {
+                const result = stepAgentCliDetection(ctx.config);
+                const detected = result.detections.filter((d) => d.available);
+                if (detected.length > 0) {
+                    p.log.info(`Detected agent CLIs: ${detected.map((d) => d.name).join(", ")}.` +
+                        (result.agent?.default ? ` Default profile: ${result.agent.default}.` : ""));
+                }
+                else {
+                    p.log.info("No agent CLIs detected on PATH. Agent commands will be disabled until one is installed and `akm setup` is re-run.");
+                }
+                ctx.apply({ agent: result.agent });
+            },
+        },
     ];
     return { steps, outcome };
 }
@@ -771,7 +818,7 @@ export async function runSetupWizard() {
     const embedding = newConfig.embedding;
     const llm = newConfig.llm;
     const registries = newConfig.registries;
-    const allStashes = newConfig.stashes ?? [];
+    const allStashes = newConfig.sources ?? newConfig.stashes ?? [];
     // Confirm before saving
     const effectiveRegistries = registries ?? DEFAULT_CONFIG.registries ?? [];
     p.note([

package/dist/{sources → src/sources}/providers/git.js

@@ -6,6 +6,7 @@ import { resolveStashDir } from "../../core/common";
 import { loadConfig } from "../../core/config";
 import { ConfigError, UsageError } from "../../core/errors";
 import { getRegistryCacheDir, getRegistryIndexCacheDir } from "../../core/paths";
+import { sanitizeCommitMessage } from "../../core/write-source";
 import { parseRegistryRef, resolveRegistryArtifact, validateGitRef, validateGitUrl } from "../../registry/resolve";
 import { registerSourceProvider } from "../provider-factory";
 import { applyAkmIncludeConfig, buildInstallCacheDir, copyDirectoryContents, detectStashRoot, isDirectory, isExpired, sanitizeString, } from "./provider-utils";
@@ -77,20 +78,6 @@ function getCachePaths(repoUrl) {
     const key = createHash("sha256").update(repoUrl).digest("hex").slice(0, 16);
     const cacheRoot = getRegistryIndexCacheDir();
     const rootDir = path.join(cacheRoot, `git-${key}`);
-    // One-time silent migration: legacy `context-hub-${key}` directories were
-    // created for ALL git stashes (not just the andrewyng/context-hub repo). If
-    // the new path doesn't yet exist but the legacy one does, rename it in place
-    // so existing clones aren't silently invalidated. Failures are non-fatal —
-    // worst case the repo is re-cloned on the next refresh.
-    try {
-        const legacyRootDir = path.join(cacheRoot, `context-hub-${key}`);
-        if (!fs.existsSync(rootDir) && fs.existsSync(legacyRootDir)) {
-            fs.renameSync(legacyRootDir, rootDir);
-        }
-    }
-    catch {
-        /* migration is best-effort */
-    }
     return {
         rootDir,
         repoDir: path.join(rootDir, "repo"),
@@ -398,7 +385,12 @@ function parseGitRepoUrl(rawUrl) {
  */
 export function saveGitStash(name, message, writableOverride) {
     const timestamp = new Date().toISOString().replace("T", " ").slice(0, 19);
-    const commitMessage = message?.trim() || `akm save ${timestamp}`;
+    // Sanitize the user-supplied message: strip CR/LF/NUL, collapse whitespace,
+    // clamp length. An attacker can otherwise pass `--message "subject\n\n\
+    // Co-Authored-By: someone-else"` and forge trailers in the commit log.
+    // Empty result falls back to the timestamped default.
+    const sanitized = message ? sanitizeCommitMessage(message) : "";
+    const commitMessage = sanitized || `akm save ${timestamp}`;
     let repoDir;
     let writable = false;
     if (name) {

package/dist/{wiki → 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/{workflows → 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
+    }
+}