akm-cli 0.10.261012-beta → 0.10.261014-beta

package/dist/workflows/runtime/runs.js

@@ -9,25 +9,35 @@ import { appendEvent } from "../../core/events.js";
 import { warn } from "../../core/warn.js";
 import { insertEventOnce } from "../../storage/repositories/events-repository.js";
 import { withWorkflowRunsRepo, } from "../../storage/repositories/workflow-runs-repository.js";
-import { getCurrentWorkflowScopeKey } from "../authoring/scope-key.js";
-import { frozenSummaryJudge } from "../exec/frozen-judge.js";
+import { frozenSummaryJudge, resolveJudgeCwd } from "../exec/frozen-judge.js";
 import { detectSecretShapedParams } from "../exec/param-secrets.js";
 import { freezeWorkflow } from "../freeze/freeze.js";
 import { applyWorkflowParamDefaults, materializeWorkflowParameterFlags, validateWorkflowParams, } from "../ir/params.js";
 import { canonicalPlanJson, computePlanHash } from "../ir/plan-hash.js";
+import { resolveOrchestrationRefs, summarizeStepOrchestration } from "../renderer.js";
 import { clip, WORKFLOW_UNIT_DIAGNOSTIC_CLIP } from "../resource-limits.js";
 import { validateStepSummary } from "../validate-summary.js";
 import { resolveAgentIdentity } from "./agent-identity.js";
-import { frozenStepRows, readRunPlan } from "./run-plan.js";
-import { canonicalizeWorkflowRefInput, loadWorkflowAsset, resolveWorkflowEntryId } from "./workflow-asset-loader.js";
+import { decodeWorkflowPlan, frozenStepRows, readRunPlan } from "./run-plan.js";
+import { canonicalizeWorkflowRefInput, loadWorkflowAsset } from "./workflow-asset-loader.js";
 /**
  * Membership test for the journaled `runner` column, which is an untyped string.
  * The `Record<WorkflowRuntimeKind, …>` is exhaustiveness-checked, so a new runtime
  * kind cannot be added to the union without being accepted here too.
  */
-const IR_RUNTIME_KINDS = { llm: true, agent: true, sdk: true, exec: true };
+const IR_RUNTIME_KINDS = { connection: true, harness: true, exec: true };
+/** What a run of an earlier release journaled for the runner kinds that were renamed. */
+const EARLIER_RUNTIME_KINDS = {
+    llm: "connection",
+    agent: "harness",
+    sdk: "harness",
+};
 function runtimeKindOf(runner) {
-    return runner !== null && Object.hasOwn(IR_RUNTIME_KINDS, runner) ? runner : null;
+    if (runner === null)
+        return null;
+    if (Object.hasOwn(IR_RUNTIME_KINDS, runner))
+        return runner;
+    return EARLIER_RUNTIME_KINDS[runner] ?? null;
 }
 function toUnitDiagnostic(row) {
     let diagnostic = null;
@@ -98,38 +108,21 @@ export async function startWorkflowRun(ref, params = {}, options) {
     return withWorkflowRunsRepo(async (repo) => {
         const now = new Date().toISOString();
         const runId = randomUUID();
-        const scopeKey = getCurrentWorkflowScopeKey();
         const currentStepId = plan.steps[0]?.stepId ?? null;
-        const workflowEntryId = resolveWorkflowEntryId(asset.sourcePath, asset.ref, asset.adapterId);
         // Capture the invoking harness/session identity for this run. Explicit options
         // win; otherwise fall back to best-effort environment detection. This is
         // identity-only — no background thread or timer is started here.
         const detected = resolveAgentIdentity();
         const agentHarness = options?.agentHarness !== undefined ? options.agentHarness : detected.harness;
         const agentSessionId = options?.agentSessionId !== undefined ? options.agentSessionId : detected.sessionId;
-        // Concurrency guard (#485): if an active run already exists in this
-        // (workflow_ref, scope_key) pair, refuse to create a parallel run unless
-        // `force: true` is set. Previously every call inserted unconditionally,
-        // so two terminals starting the same workflow could leave two runs racing.
-        // The active-alias query and all inserts share one immediate transaction.
-        // #942: an active run of this ref in a different scope (e.g. a scheduled
-        // task's cwd vs. a shell) is warned about once; the uniqueness guard stays
-        // scope-local. The query excludes the caller's own scope in SQL.
-        const crossScopeActive = repo.findActiveRunOutsideScope(workflowRefs, scopeKey);
-        const crossScopeWarning = crossScopeActive
-            ? `Workflow ${asset.ref} already has an active run in another scope ` +
-                `(id ${crossScopeActive.id}, started ${crossScopeActive.created_at}, scope ${crossScopeActive.scope_key ?? "unknown"}); ` +
-                `starting a separate run here. Resume it from anywhere with "akm workflow run ${crossScopeActive.id}" ` +
-                `or free it with "akm workflow abandon ${crossScopeActive.id}".`
-            : undefined;
+        // Starting a ref always starts a run. Other active runs of the same ref
+        // are not an error: name them once, after the start succeeds, so the
+        // operator can continue or abandon the ones they no longer want.
+        const otherActive = repo.listRuns({ workflowRefs, activeOnly: true });
         repo.publishWorkflowRunV4({
-            workflowRefs,
-            ...(options?.force ? { force: true } : {}),
             run: {
                 id: runId,
                 workflowRef: asset.ref,
-                scopeKey,
-                workflowEntryId,
                 workflowTitle: asset.title,
                 paramsJson: JSON.stringify(effectiveParams),
                 currentStepId,
@@ -149,9 +142,12 @@ export async function startWorkflowRun(ref, params = {}, options) {
             planJson,
             planHash,
         });
+        if (otherActive.length > 0) {
+            const ids = otherActive.map((run) => run.id);
+            warn(`Workflow ${asset.ref} already has ${ids.length} active run(s) (${ids.join(", ")}); started another. ` +
+                `Continue one with "akm workflow run ${ids[0]}" or give up on it with "akm workflow abandon ${ids[0]}".`);
+        }
         const result = await getWorkflowStatus(runId);
-        if (crossScopeWarning)
-            result.warnings = [...(result.warnings ?? []), crossScopeWarning];
         // Params reach every unit prompt in clear (only the journal scrubs them).
         // Surface a loud, best-effort warning when a param LOOKS like a credential
         // so the author moves it to an env binding. Advisory only — never blocks
@@ -159,14 +155,19 @@ export async function startWorkflowRun(ref, params = {}, options) {
         const secretWarnings = detectSecretShapedParams(effectiveParams);
         if (secretWarnings.length > 0)
             result.warnings = [...(result.warnings ?? []), ...secretWarnings];
-        // The implicit engine fallback is announced ONCE, here at run creation —
-        // the frozen plan records the engine actually used, so a resume never
-        // re-announces a decision it did not make.
-        if (frozen.engineAnnouncement)
-            result.warnings = [...(result.warnings ?? []), frozen.engineAnnouncement];
         return result;
     });
 }
+function decodeStatusPlan(planJson) {
+    if (!planJson)
+        return undefined;
+    try {
+        return decodeWorkflowPlan(JSON.parse(planJson));
+    }
+    catch {
+        return undefined;
+    }
+}
 export async function getWorkflowStatus(runId, opts) {
     return withWorkflowRunsRepo((repo) => {
         const run = readWorkflowRun(repo, runId);
@@ -176,25 +177,32 @@ export async function getWorkflowStatus(runId, opts) {
             // The honest diagnostic surface (#22): read the unit journal straight and
             // project each row, INCLUDING failures whose diagnostic text the
             // deterministic evidence graph drops. Read-only; never mutates the run.
-            detail.units = repo.getUnitsForRun(run.id).map(toUnitDiagnostic);
+            const rows = repo.getUnitsForRun(run.id);
+            // The plan is decoded only to describe a failed unit, read-only: no run
+            // warning (`readRunPlan` says it is "running" an older plan) and no
+            // orchestration when the plan cannot be decoded.
+            const plan = rows.some((row) => row.status === "failed") ? decodeStatusPlan(run.plan_json) : undefined;
+            detail.units = rows.map((row) => {
+                const unit = toUnitDiagnostic(row);
+                const step = row.status === "failed" ? plan?.steps.find((candidate) => candidate.stepId === row.step_id) : undefined;
+                const summary = step ? summarizeStepOrchestration(step, undefined) : undefined;
+                return summary ? { ...unit, orchestration: resolveOrchestrationRefs(summary) } : unit;
+            });
         }
         return detail;
     });
 }
 export async function listWorkflowRuns(input) {
-    const scopeKey = input?.allScopes === true ? null : getCurrentWorkflowScopeKey();
     const activeOnly = input?.activeOnly === true;
     const includeChildren = input?.includeChildren === true;
     if (input?.workflowRef === undefined) {
         return withWorkflowRunsRepo((repo) => ({
             runs: repo
                 .listRuns({
-                scopeKey,
                 ...(activeOnly ? { activeOnly: true } : {}),
                 ...(includeChildren ? { includeChildren: true } : {}),
             })
                 .map(toWorkflowRunSummary),
-            scopeKey,
         }));
     }
     const exactRef = input.workflowRef.trim();
@@ -212,12 +220,11 @@ export async function listWorkflowRuns(input) {
     }
     catch (error) {
         if (parsedExactRef.bundle !== undefined) {
-            const exactRows = await withWorkflowRunsRepo((repo) => repo.listRuns({ scopeKey, workflowRef: exactRef, ...(includeChildren ? { includeChildren: true } : {}) }));
+            const exactRows = await withWorkflowRunsRepo((repo) => repo.listRuns({ workflowRef: exactRef, ...(includeChildren ? { includeChildren: true } : {}) }));
             if (exactRows.length === 0)
                 throw error;
             return {
                 runs: exactRows.filter((row) => !activeOnly || row.status === "active").map(toWorkflowRunSummary),
-                scopeKey,
             };
         }
         if (!(error instanceof NotFoundError))
@@ -226,23 +233,20 @@ export async function listWorkflowRuns(input) {
     return withWorkflowRunsRepo((repo) => ({
         runs: repo
             .listRuns({
-            scopeKey,
             workflowRefs,
             ...(activeOnly ? { activeOnly: true } : {}),
             ...(includeChildren ? { includeChildren: true } : {}),
         })
             .map(toWorkflowRunSummary),
-        scopeKey,
     }));
 }
 export async function getNextWorkflowStep(specifier, params, options) {
     return withWorkflowRunsRepo(async (repo) => {
-        const { run, autoStarted, resumed, startWarnings } = await resolveRunSpecifier(repo, specifier, params, options?.parameterFlags, options?.newRun);
+        const { run, autoStarted, startWarnings } = await resolveRunSpecifier(repo, specifier, params, options?.parameterFlags);
         const steps = readWorkflowRunSteps(repo, run.id);
         return {
             ...projectNextResult(run, steps),
             ...(autoStarted ? { autoStarted: true } : {}),
-            ...(resumed ? { resumed: true } : {}),
             ...(startWarnings?.length ? { startWarnings } : {}),
         };
     });
@@ -348,7 +352,7 @@ export async function completeWorkflowStep(input) {
         const stepPlan = storedPlan.steps.find((step) => step.stepId === input.stepId);
         if (!stepPlan)
             throw new NotFoundError(`Step "${input.stepId}" was not found in workflow run ${run.id}.`);
-        return { existing, plan: storedPlan, stepPlan };
+        return { existing, plan: storedPlan, stepPlan, workflowRef: run.workflow_ref };
     });
     const summary = input.summary?.trim();
     // #506: completing a step requires a summary of the work done.
@@ -365,14 +369,11 @@ export async function completeWorkflowStep(input) {
             ? // Manual completion journals no gate row, so there is no `<stepId>.gate:l<loop>`
                 // identity to agree with — but the dispatch still names the REAL run and
                 // step (frozen-judge falls back to the gate node id for the unit id).
-                frozenSummaryJudge(preflight.stepPlan.gate.frozenJudge, input.signal, undefined, {
-                    runId: input.runId,
-                    stepId: input.stepId,
-                })
+                frozenSummaryJudge(preflight.stepPlan.gate.frozenJudge, input.signal, undefined, { runId: input.runId, stepId: input.stepId }, undefined, resolveJudgeCwd(preflight.stepPlan.gate.frozenJudge, preflight.workflowRef))
             : input.summaryJudge;
         if (criteria.length > 0 && !judge) {
             throw new ConfigError(`Workflow run ${input.runId} has completion criteria for step "${input.stepId}" but its frozen plan has no judge. ` +
-                "Set workflow.judgeEngine, abandon this run, and create a new one with `akm workflow run <ref>`.", "INVALID_CONFIG_FILE");
+                "Run `akm setup` to add a connection or harness, abandon this run, and create a new one with `akm workflow run <ref>`.", "INVALID_CONFIG_FILE");
         }
         const verdict = await validateStepSummary({ stepTitle: preflight.stepPlan.title, completionCriteria: criteria, summary }, judge ?? undefined, input.signal);
         if (!verdict.complete) {
@@ -457,57 +458,27 @@ export async function completeWorkflowStep(input) {
         return detail;
     });
 }
-async function resolveRunSpecifier(repo, specifier, params, parameterFlags, forceNew) {
-    const hasParameters = (params && Object.keys(params).length > 0) || (parameterFlags?.length ?? 0) > 0;
+async function resolveRunSpecifier(repo, specifier, params, parameterFlags) {
     const explicitRun = findRunByIdOrPrefix(repo, specifier);
     if (explicitRun) {
-        // `--new` starts a fresh run FROM A REF; it never makes sense against a
-        // run id (or an id prefix), which already names the run to act on (#919).
-        if (forceNew) {
-            throw new UsageError(`--new starts a fresh run from a workflow ref; "${specifier}" already names a run id.`, "INVALID_FLAG_VALUE");
-        }
-        if (hasParameters) {
+        if ((params && Object.keys(params).length > 0) || (parameterFlags?.length ?? 0) > 0) {
             throw new UsageError(`Workflow parameter flags can only be used when starting a new run, not with existing run id "${specifier}".`);
         }
         return { run: explicitRun, autoStarted: false };
     }
-    const scopeKey = getCurrentWorkflowScopeKey();
-    const exactRef = specifier.trim();
-    const parsedExact = parseBundleRef(exactRef);
-    const qualifiedExact = parsedExact.bundle !== undefined && parsedExact.fragment === undefined;
-    const detached = qualifiedExact && !forceNew ? repo.getActiveRunRowForScope(exactRef, scopeKey) : undefined;
+    // A workflow ref always starts a new run; only a run id drives an existing one.
     let ref;
     try {
         ref = await canonicalizeWorkflowSpecifier(specifier);
     }
     catch (error) {
-        if (detached) {
-            if (hasParameters) {
-                throw new UsageError(`Workflow parameter flags can only be set on a new run; ${specifier} is already active ` +
-                    `(id ${detached.id}, scope ${scopeKey}).`, "INVALID_FLAG_VALUE", `Pass --new to start a separate run, or run "akm workflow abandon ${detached.id}" to free up ${specifier} first.`);
-            }
-            return { run: detached, autoStarted: false, resumed: true };
-        }
         if (error instanceof NotFoundError && !specifier.includes(":") && !specifier.includes("/")) {
             throw new NotFoundError(`Workflow run or workflow "${specifier}" not found.`, "WORKFLOW_NOT_FOUND");
         }
         throw error;
     }
-    const active = forceNew ? undefined : repo.getActiveRunRowForScope(await workflowRunRefSet(ref, exactRef), scopeKey);
-    if (active) {
-        if (hasParameters) {
-            throw new UsageError(`Workflow parameter flags can only be set on a new run; ${ref} is already active ` +
-                `(id ${active.id}, scope ${scopeKey}).`, "INVALID_FLAG_VALUE", `Pass --new to start a separate run, or run "akm workflow abandon ${active.id}" to free up ${ref} first.`);
-        }
-        return { run: active, autoStarted: false, resumed: true };
-    }
-    // `force` (#485's own escape hatch) is what lets `--new` create a second
-    // active run for this (ref, scope) pair instead of the concurrency guard
-    // refusing it — the caller explicitly asked for a fresh run, so the guard
-    // that exists to catch an ACCIDENTAL second run does not apply (#919).
     const started = await startWorkflowRun(ref, params ?? {}, {
         ...(parameterFlags !== undefined ? { parameterFlags } : {}),
-        ...(forceNew ? { force: true } : {}),
     });
     return {
         run: readWorkflowRun(repo, started.run.id),
@@ -636,7 +607,7 @@ function toChildRunNode(repo, rootRunId, row) {
             ? {
                 resume: {
                     command: `akm workflow resume ${row.id}`,
-                    // biome-ignore lint/suspicious/noThenProperty: mirrors spec §4.5's real WorkflowChildRunNode.resume.then field name
+                    // biome-ignore lint/suspicious/noThenProperty: mirrors the real WorkflowChildRunNode.resume.then field name
                     then: `akm workflow resume ${rootRunId} && akm workflow run ${rootRunId}`,
                 },
             }
@@ -648,7 +619,6 @@ function toWorkflowRunSummary(run) {
     return {
         id: run.id,
         workflowRef: run.workflow_ref,
-        scopeKey: run.scope_key,
         workflowEntryId: run.workflow_entry_id,
         workflowTitle: run.workflow_title,
         status: run.status,
@@ -733,11 +703,3 @@ function parseJsonArray(value) {
     }
     return undefined;
 }
-export async function getActiveWorkflowRun(scopeKey = getCurrentWorkflowScopeKey()) {
-    return withWorkflowRunsRepo((repo) => {
-        const row = repo.findActiveOrBlockedRunForScope(scopeKey);
-        if (!row)
-            return null;
-        return { runId: row.id, stepId: row.current_step_id, workflowRef: row.workflow_ref };
-    }).catch(() => null); // fail-open: never crash show output due to DB error
-}

package/dist/workflows/runtime/workflow-asset-loader.js

@@ -3,16 +3,13 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { createHash } from "node:crypto";
 import fs from "node:fs";
-import { detectAdapterId } from "../../core/adapter/detect-adapter.js";
 import { makeBundleRef, parseBundleRef } from "../../core/asset/asset-ref.js";
 import { loadConfig } from "../../core/config/config.js";
 import { COMPOSITION_INVALID_MULTI_JOB_HINT, NotFoundError, UsageError } from "../../core/errors.js";
-import { getDbPath } from "../../core/paths.js";
 import { canonicalizeWorkflowName } from "../../core/recognition-util.js";
-import { deriveInstallations } from "../../indexer/installations.js";
-import { resolveAdapterConceptOwner } from "../../indexer/lookup/adapter-concept-owner.js";
+import { resolveConceptOwner } from "../../indexer/lookup/adapter-concept-owner.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
-import { withIndexDb } from "../../storage/repositories/index-db.js";
+import { resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
 import { compileWorkflowSource } from "../compile.js";
 /**
  * Build the canonical `workflow_runs.workflow_ref` for an AKM workflow asset.
@@ -31,71 +28,70 @@ export function parseWorkflowRefInput(ref) {
     }
     return parsed;
 }
-/** Resolve input sugar to the workflow's canonical run identity. */
+/** Resolve input sugar to the workflow's canonical run identity, without compiling it. */
 export async function canonicalizeWorkflowRefInput(ref) {
-    return (await loadWorkflowAsset(ref)).ref;
+    return resolveWorkflowAsset(ref).fullRef;
 }
-/**
- * Resolve a workflow ref and compile its authored bytes into a plan.
- */
-export async function loadWorkflowAsset(ref) {
+/** Resolve a workflow ref to its authored file and canonical run ref. */
+function resolveWorkflowAsset(ref) {
     const bundleRef = parseWorkflowRefInput(ref);
-    const config = loadConfig();
-    const allSources = resolveSourceEntries(undefined, config);
-    const installations = deriveInstallations(allSources);
-    const searchSources = allSources.flatMap((source, index) => {
-        const bundleId = installations[index]?.id;
-        if (!bundleId || (bundleRef.bundle !== undefined && bundleRef.bundle !== bundleId))
-            return [];
-        return [{ source, bundleId }];
-    });
-    if (bundleRef.bundle && searchSources.length === 0) {
-        throw new UsageError(`Bundle "${bundleRef.bundle}" was not found among configured sources.`, "WORKFLOW_SOURCE_INVALID");
-    }
-    let assetPath;
-    let sourcePath;
-    let sourceBundleId;
-    let workflowName;
-    let workflowAdapterId;
-    let rejectedSource;
-    for (const candidateSource of searchSources) {
-        const { source, bundleId } = candidateSource;
-        const adapterId = source.adapterId ?? detectAdapterId(source.path);
-        const ownedSource = source.adapterId ? source : { ...source, adapterId };
-        const owner = resolveAdapterConceptOwner(source.path, adapterId, bundleRef.conceptId);
-        if (!owner)
-            continue;
-        if (!ownsNativeWorkflowRuntime(ownedSource) || !owner.workflowSource) {
-            rejectedSource ??= { source: ownedSource, bundleId };
-            break;
-        }
-        assetPath = owner.path;
-        sourcePath = source.path;
-        sourceBundleId = bundleId;
-        workflowName = owner.workflowSource.canonicalName;
-        workflowAdapterId = adapterId;
-        break;
-    }
-    if (!assetPath) {
-        if (rejectedSource) {
-            const sourceName = rejectedSource.bundleId;
-            const adapterId = rejectedSource.source.adapterId ?? "unassigned";
-            throw new UsageError(`Bundle "${sourceName}" uses adapter "${adapterId}", which does not support native workflow execution.`, "WORKFLOW_SOURCE_INVALID");
+    const sources = resolveSourceEntries(undefined, loadConfig());
+    const match = resolveConceptOwner(bundleRef, sources);
+    if (!match) {
+        if (bundleRef.bundle && resolveSourcesForOrigin(bundleRef.bundle, sources).length === 0) {
+            throw new UsageError(`Bundle "${bundleRef.bundle}" was not found among configured sources.`, "WORKFLOW_SOURCE_INVALID");
         }
         throw new NotFoundError(`Workflow not found for ref: ${ref}`);
     }
-    const resolvedSourcePath = sourcePath;
+    const { owner, source, bundleId, adapterId } = match;
+    if ((adapterId !== "akm" && adapterId !== "akm-workflow") || !owner.workflowSource) {
+        throw new UsageError(`Bundle "${bundleId}" uses adapter "${adapterId}", which does not support native workflow execution.`, "WORKFLOW_SOURCE_INVALID");
+    }
     // Canonicalize the stored ref: `workflows/foo.md` and `workflows/foo` resolve
     // to the same file, so they MUST share one run identity.
-    const canonicalName = canonicalizeWorkflowName(workflowName);
-    const fullRef = workflowAdapterId === "akm-workflow"
-        ? makeBundleRef(sourceBundleId, canonicalName)
-        : canonicalWorkflowRunRef(sourceBundleId, canonicalName);
+    const canonicalName = canonicalizeWorkflowName(owner.workflowSource.canonicalName);
+    const fullRef = adapterId === "akm-workflow"
+        ? makeBundleRef(bundleId, canonicalName)
+        : canonicalWorkflowRunRef(bundleId, canonicalName);
+    return { assetPath: owner.path, sourcePath: source.path, adapterId, canonicalName, fullRef };
+}
+/**
+ * The root of the bundle that owns a workflow ref right now: where the run's exec units and agents work.
+ * A bundle-qualified ref names its bundle, so the workflow file need not exist (a bundle update may have
+ * renamed or removed it; the frozen plan is the run's authority). An unqualified legacy ref finds its
+ * owner by the existing walk. When the bundle does not resolve, the error keeps its type (and exit code)
+ * and names the ref in its message.
+ */
+export function resolveRunBundleRoot(ref) {
+    const { bundle } = parseWorkflowRefInput(ref);
+    if (bundle === undefined) {
+        try {
+            return resolveWorkflowAsset(ref).sourcePath;
+        }
+        catch (err) {
+            // Only a miss means the bundle does not resolve; any other error (an
+            // unsupported adapter, a collision) is reported as itself.
+            if (err instanceof NotFoundError) {
+                throw new NotFoundError(`workflow ${ref} does not resolve to a bundle: ${err.message}`, err.code, err.hint());
+            }
+            throw err;
+        }
+    }
+    const source = resolveSourcesForOrigin(bundle, resolveSourceEntries(undefined, loadConfig()))[0];
+    if (!source) {
+        throw new UsageError(`workflow ${ref} does not resolve to a bundle: bundle "${bundle}" is not configured`, "WORKFLOW_SOURCE_INVALID");
+    }
+    return source.path;
+}
+/**
+ * Resolve a workflow ref and compile its authored bytes into a plan.
+ */
+export async function loadWorkflowAsset(ref) {
+    const { assetPath, adapterId, canonicalName, fullRef } = resolveWorkflowAsset(ref);
     const title = canonicalName.split("/").pop() || canonicalName;
     const bytes = fs.readFileSync(assetPath);
     const result = compileWorkflowSource(bytes.toString("utf8"), {
         path: assetPath,
-        workspaceRoot: resolvedSourcePath,
         title,
     });
     if (!result.ok) {
@@ -106,36 +102,9 @@ export async function loadWorkflowAsset(ref) {
     return {
         ref: fullRef,
         path: assetPath,
-        sourcePath: resolvedSourcePath,
-        adapterId: workflowAdapterId,
+        adapterId,
         title,
         plan: result.plan,
         sourceHash: createHash("sha256").update(bytes).digest("hex"),
     };
 }
-function ownsNativeWorkflowRuntime(source) {
-    return source.adapterId === "akm" || source.adapterId === "akm-workflow";
-}
-/**
- * Resolve the `entries.id` for an indexed workflow, or null when the index
- * database does not yet exist or has no matching entry.
- */
-export function resolveWorkflowEntryId(_sourcePath, ref, adapterId) {
-    if (!fs.existsSync(getDbPath()))
-        return null;
-    const parsed = parseBundleRef(ref);
-    if (!parsed.bundle)
-        throw new UsageError(`Expected a bundle-qualified workflow ref, got "${ref}".`);
-    const itemRef = makeBundleRef(parsed.bundle, parsed.conceptId);
-    return withIndexDb((db) => {
-        const row = db
-            .prepare(`SELECT id
-         FROM entries
-         WHERE type = 'workflow'
-           AND item_ref = ?
-           ${adapterId ? "AND adapter_id = ?" : ""}
-          LIMIT 1`)
-            .get(itemRef, ...(adapterId ? [adapterId] : []));
-        return row?.id ?? null;
-    });
-}

package/dist/workflows/source-files.js

@@ -66,15 +66,6 @@ export class WorkflowSourceLinkResolutionError extends WorkflowSourceRejectionEr
         Object.setPrototypeOf(this, new.target.prototype);
     }
 }
-export class WorkflowSourcePathIdentityError extends WorkflowSourceRejectionError {
-    constructor(sourcePath, targetPath) {
-        super(`Workflow source ${sourcePath} resolves outside the bundle root to ${targetPath}.`, "PATH_ESCAPE_VIOLATION", [
-            sourcePath,
-        ]);
-        this.name = "WorkflowSourcePathIdentityError";
-        Object.setPrototypeOf(this, new.target.prototype);
-    }
-}
 /** Convert an adapter-owned concept id into its extensionless workflow name. */
 export function workflowNameForConceptId(adapterId, conceptId) {
     if (adapterId === "akm-workflow")
@@ -270,21 +261,18 @@ function inspectWorkflowSourceCandidate(candidate, canonicalName, realRoot) {
         issues.push(new WorkflowSourceLinkResolutionError(candidate.relativePath));
         return { issues };
     }
+    // A symlink may point anywhere (installing a bundle is the trust decision),
+    // but it may not change the source's format.
     const targetPath = toPosix(path.relative(realRoot, realPath));
-    const contained = isWithinResolved(realPath, realRoot);
-    if (!contained)
-        issues.push(new WorkflowSourcePathIdentityError(candidate.relativePath, targetPath));
     if (isLink && path.extname(realPath).toLowerCase() !== candidate.lowerExtension) {
         issues.push(new WorkflowSourceLinkIdentityError(candidate.relativePath, targetPath));
     }
-    if (contained) {
-        try {
-            if (!fs.statSync(realPath).isFile())
-                issues.push(new WorkflowSourceLinkResolutionError(candidate.relativePath));
-        }
-        catch {
+    try {
+        if (!fs.statSync(realPath).isFile())
             issues.push(new WorkflowSourceLinkResolutionError(candidate.relativePath));
-        }
+    }
+    catch {
+        issues.push(new WorkflowSourceLinkResolutionError(candidate.relativePath));
     }
     if (issues.length > 0)
         return { issues };

package/docs/README.md

@@ -17,6 +17,7 @@ Full per-directory indexes: [Guides](guides/README.md),
 - [Getting Started](guides/getting-started.md) -- Install akm, connect a source, and pull a curated shortlist in five to seven minutes
 - [Concepts](guides/concepts.md) -- Capabilities, bundles, adapters, asset types, and refs -- the mental model in one page
 - [Agent Install Guide](agents/agent-install.md) -- Step-by-step automated (non-interactive) install for agents
+- [Upgrade from 0.9 to 0.10](migration/v0.9-to-v0.10.md) -- The current upgrade path: the order to follow, every removed CLI spelling, config key and workflow feature with its replacement, and what a scheduled `akm improve` now does
 - `akm hints` (complete guide by default; `akm hints --detail brief` for the short one) -- The CLI reference agents load to use akm; always the embedded corpus at `src/assets/hints/cli-hints-{full,short}.md`
 
 ## Use
@@ -32,7 +33,6 @@ the task needs, and capture what you learn along the way.
 - [Environment & Secrets](reference/env-and-secrets.md) -- `akm env` and `akm secret`: exact operations, file modes, and the security guarantee
 - [Run Workflows](guides/run-workflows.md) -- Start or continue a run, check on it, resume it, or abandon it
 - [Scheduling](guides/scheduling.md) -- Run akm tasks through the OS scheduler (cron / launchd / schtasks) safely
-- [Migrate to 0.9.2](migration/v0.9.1-to-v0.9.2.md) -- Convert task-v2 sources safely and understand workflow resume compatibility
 - [Improve the Library](guides/improve-the-library.md) -- Feedback, history, and proposals -- how evidence turns into reviewable changes
 - Recipes: [Turn a Website into a Searchable Bundle](guides/recipes/website-source.md), [Headless Install](guides/recipes/headless-install.md)
 
@@ -42,23 +42,21 @@ Package complete capabilities and turn knowledge into repeatable work.
 
 - [Bundle Author's Guide](guides/author-bundles.md) -- Build a bundle, make it discoverable, and share it so others can install it with `akm bundle add`
 - [Author's Guide: Writing Workflows](guides/author-workflows.md) -- Write and test a workflow definition, from a minimal example to gates and outputs
-- [Claude Code workflows vs. akm workflows](guides/claude-code-vs-akm-workflows.md) -- Short decision guide for choosing between a session-native workflow and an akm workflow ([full technical comparison](architecture/comparisons/claude-code-vs-akm-workflows-full.md))
 - [Bundling akm](integration/bundling-akm.md) -- Ship akm inside your own product: the pin/migrate/health boot contract, plan JSON shapes, and exit codes for bundlers
 
 ### Maintainers
 
 Working on akm itself, not just using it.
 
-- [Maintainer Docs](maintainers/README.md) -- Start here: local development, measuring improvement, and the curate contract
+- [Maintainer Docs](maintainers/README.md) -- Start here: local development, the release checklist, and measuring improvement
 - [Local Development](maintainers/local-development.md) -- Dogfooding akm while editing its own source
-- [Curate Workmap](maintainers/curate-workmap.md) -- The current `akm curate` contract and the highest-value next fixes
 
 ## Look up details
 
 - [CLI](reference/cli.md) -- All `akm` commands and flags
-- [Configuration](reference/configuration.md) -- Engines, strategies, bundles, and settings
+- [Configuration](reference/configuration.md) -- Connections, harnesses, strategies, bundles, and settings
 - [Supported Formats](reference/supported-formats.md) -- Every bundle format akm recognizes, its detection marker, and current read/write support
-- [Tasks](reference/tasks.md) -- Task-v3 files, targets, triggers, and fail-closed migration
+- [Tasks](reference/tasks.md) -- Task source v4 files, targets, triggers, and the explicit `akm migrate apply` conversion of v2 and v3 files
 - [Asset Types](reference/asset-types.md) -- The capability taxonomy, directory conventions, and per-type examples
 - [Refs](reference/refs.md) -- The ref grammar `akm search` emits and `akm show` consumes
 - [Memory](reference/memory.md) -- The `memory` asset type: capture, belief states, and derived memories
@@ -68,17 +66,14 @@ Working on akm itself, not just using it.
 - [Website Sources](reference/website-sources.md) -- The pluggable fetcher API for URL-based knowledge reads
 - [Data & Telemetry](reference/data-and-telemetry.md) -- Exactly what akm reads and writes on your machine (no remote telemetry)
 - [Architecture Overview](architecture/architecture.md) -- How akm's bundles, cache, index, and registries fit together
-- [Core Principles](architecture/akm-core-principles.md) -- Design principles and constraints
+- [Core Principles](architecture/akm-core-principles.md) -- How the code, tests and docs in this repo are built: the engineering rules and what enforces each
 - [Adapters](architecture/adapters.md) -- How akm picks an adapter, indexes, validates, and writes into a bundle
 - [The Workflow Engine](architecture/workflow-engine.md) -- How a frozen plan is stored, dispatched, and resumed without replaying completed units
 - [The Improvement Loop](architecture/improvement.md) -- How a feedback signal becomes a ranking change, and how evidence becomes a proposal
-- [Runtime Boundary Design](architecture/runtime-boundary-design.md) -- Isolating `bun:sqlite`/`Bun.*` from the core
-- [Architecture Decision History](architecture/akm-architecture-decision-history.md) -- ADR-style record of the major architecture rulings
-- [Specs](architecture/README.md#specs-specs) -- Normative specifications (bundle/adapter model, ref grammar, bundle conventions)
-- [Internals](architecture/README.md#internals-internals) -- Current-truth subsystem references (storage, search, indexing, improve, health)
-- [Testing](architecture/README.md#testing-testing) -- Testing workflow and pre-release checklist
-- [Migration](migration/README.md) -- Upgrade guides and per-release migration notes
-- [Roadmap](https://github.com/itlackey/akm/blob/main/ROADMAP.md) -- High-level focus for the releases from here through 1.0
+- [Specs](architecture/README.md#specs-specs) -- Normative specifications (ref grammar, OKF support)
+- [Internals](architecture/README.md#internals-internals) -- Current-truth subsystem references (storage, indexing, classification, improve, health)
+- [Testing](architecture/README.md#testing-testing) -- Testing workflow
+- [Migration](migration/README.md) -- The current 0.9 to 0.10 upgrade guide, then the historical guides and per-release notes of earlier releases
 
 ## Execution boundary
 
@@ -86,8 +81,7 @@ AKM retrieves every supported capability type. It directly orchestrates
 defined execution surfaces such as workflows, agent dispatch, tasks, and
 guarded subprocess injection. It does not blindly execute arbitrary indexed
 content merely because that content appears in search results. See
-[Core Principles](architecture/akm-core-principles.md) for the full boundary,
-and [The Improvement Loop](architecture/improvement.md) for how that boundary
+[The Improvement Loop](architecture/improvement.md) for how that boundary
 applies to akm's own self-generated changes.
 
 ## Posts