akm-cli 0.10.261012-beta → 0.10.261013-beta

package/dist/commands/tasks/tasks.js

@@ -23,18 +23,21 @@ import { makeBundleRef, parseBundleRef } from "../../core/asset/asset-ref.js";
 import { conceptIdFromTypeName, isFullRefInput } from "../../core/asset/resolve-ref.js";
 import { isWithin, resolveStashDir } from "../../core/common.js";
 import { loadConfig, mutateConfig, resetConfigCache } from "../../core/config/config.js";
-import { bundleKeyForContentRoot, resolveActiveConfiguredSources, resolveConfiguredSources, } from "../../core/config/config-sources.js";
+import { bundleKeyForContentRoot, resolveConfiguredSources } from "../../core/config/config-sources.js";
 import { IMPROVE_AUTONOMY_CONFIG_KEY, isImproveAutonomyEnabled } from "../../core/config/experimental.js";
 import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
 import { getTaskHistoryDir, getTaskLogDir } from "../../core/paths.js";
 import { warn } from "../../core/warn.js";
-import { commitWriteTargetBoundary, isWriteCapableSourceKind, prepareWriteTargetForMutation, resolveWorkingStashTarget, resolveWriteTarget, writeAssetToSource, } from "../../core/write-source.js";
+import { assertBundleNotDisabled, commitWriteTargetBoundary, isWriteCapableSourceKind, prepareWriteTargetForMutation, resolveWorkingStashTarget, resolveWriteTarget, writeAssetToSource, } from "../../core/write-source.js";
+import { deriveInstallations } from "../../indexer/installations.js";
 import { withEngineFallback } from "../../integrations/agent/engine-fallback.js";
+import { resolveSourcesForOrigin } from "../../registry/origin-resolve.js";
 import { resolveAssetPath } from "../../sources/resolve.js";
 import { enabledRefsFromInstalled, schedulerEnabledRefs, setSchedulerRefEnabled } from "../../tasks/activation-config.js";
 import { backendNameForPlatform, selectBackend } from "../../tasks/backends/index.js";
 import { prepareTaskV3Execution } from "../../tasks/prepare/prepare.js";
 import { isCheckoutInvocation, resolveAkmInvocation } from "../../tasks/resolve-akm-bin.js";
+import { activeTaskSources, resolveBundleAsset } from "../../tasks/run/load-task.js";
 import { createExecutionProvenanceContext } from "../../tasks/run/provenance.js";
 import { runTask } from "../../tasks/run/run-task.js";
 import { readTaskHistory } from "../../tasks/run/task-history.js";
@@ -78,7 +81,7 @@ export async function akmTasksAdd(input, deps = {}) {
         when_to_use: input.when_to_use,
         tags: input.tags,
     });
-    const parsedTask = parseTaskSource({ yaml, filePath: assetPath, workspaceRoot: stashDir });
+    const parsedTask = parseTaskSource({ yaml, filePath: assetPath });
     const task = projectTaskSourceV4(parsedTask.v4);
     const qualifiedRef = makeBundleRef(bundle.bundleName, `tasks/${id}`);
     await prepareTaskV3Execution(task, {
@@ -234,7 +237,6 @@ function resolveTaskActivation(ref, target, requireSchedulable) {
         const parsedSource = parseTaskSource({
             yaml: fs.readFileSync(sourcePath, "utf8"),
             filePath: sourcePath,
-            workspaceRoot: bundle.source.path,
         });
         if (parsedSource.v4.schedule.length === 0) {
             throw new UsageError(`Task ${JSON.stringify(ref)} has no schedule to enable.`, "INVALID_FLAG_VALUE");
@@ -361,24 +363,26 @@ async function buildSchedulerSyncPlan(deps, bundleTarget, options) {
         if (options.dryRun !== true)
             config = loadConfig();
     }
-    const activeSources = resolveActiveConfiguredSources(config);
+    // The one active-bundle set search, show and workflows walk, working stash included.
+    // A working stash that is a disabled configured bundle is left out: an
+    // unscoped sync still removes that bundle's rows (below) and syncs the others,
+    // and a scoped sync reports it as disabled only when it is the selected one.
+    const sources = activeTaskSources(config);
+    const ids = deriveInstallations(sources).map((installation) => installation.id);
+    const kinds = sources.map((source) => source.type);
+    const configuredSources = resolveConfiguredSources(config);
     if (bundleTarget) {
         // Only filesystem and git bundles can carry scheduler state.
-        const targetSource = activeSources.find((source) => source.name === bundleTarget);
-        if (targetSource && !isWriteCapableSourceKind(targetSource.type)) {
-            throw new UsageError(`Bundle "${bundleTarget}" has kind "${targetSource.type}"; task scheduling is only supported for filesystem and git bundles.`, "INVALID_FLAG_VALUE");
+        const targetType = kinds[ids.indexOf(bundleTarget)];
+        if (targetType !== undefined && !isWriteCapableSourceKind(targetType)) {
+            throw new UsageError(`Bundle "${bundleTarget}" has kind "${targetType}"; task scheduling is only supported for filesystem and git bundles.`, "INVALID_FLAG_VALUE");
         }
     }
-    const configuredSources = resolveConfiguredSources(config);
-    const schedulable = activeSources
-        .filter((source) => isWriteCapableSourceKind(source.type))
-        .map((source) => source.name);
-    // No configured bundle at all: the working stash (e.g. `AKM_BUNDLE_DIR`).
-    const selected = bundleTarget
-        ? [bundleTarget]
-        : schedulable.length > 0 || configuredSources.length > 0
-            ? schedulable
-            : [undefined];
+    const schedulable = ids.filter((_, index) => {
+        const type = kinds[index];
+        return type !== undefined && isWriteCapableSourceKind(type);
+    });
+    const selected = bundleTarget ? [bundleTarget] : schedulable;
     const enabledRefSet = new Set(enabledRefs);
     const desired = [];
     const failures = [];
@@ -696,12 +700,7 @@ function taskProjectionAssetResolver(config, bundleName, bundleRoot) {
         if (bundle === bundleName) {
             return { file: await resolveAssetPath(bundleRoot, type, name), bundleRoot };
         }
-        // `bundle` is the qualifier of an asset ref in the task, not a flag.
-        const target = resolveWriteTarget(config, bundle, { requireWritable: false, flag: "The asset ref's bundle" });
-        return {
-            file: await resolveAssetPath(target.source.path, type, name),
-            bundleRoot: target.source.path,
-        };
+        return resolveBundleAsset(config, { bundle, type, name });
     };
 }
 /**
@@ -722,44 +721,27 @@ export function resolveTaskReadBundle(refBundle, flagBundle) {
         resolved = resolveWorkingStashTarget(config, { requireWritable: false });
     }
     else {
-        const configured = resolveActiveConfiguredSources(config).some((source) => source.name === selector);
-        const implicit = configured ? undefined : resolveImplicitScheduledBundleTarget(config, selector);
-        resolved =
-            implicit ??
-                resolveWriteTarget(config, selector, {
-                    requireWritable: false,
-                    // The selector is `--bundle` when given, else the task ref's own bundle qualifier.
-                    flag: flagBundle !== undefined ? "--bundle" : "The task ref's bundle",
-                });
+        // Reading needs no write target: any bundle of the active set resolves.
+        const sources = activeTaskSources(config);
+        const source = resolveSourcesForOrigin(selector, sources)[0];
+        if (!source) {
+            assertBundleNotDisabled(config, selector);
+            throw new UsageError(`${flagBundle !== undefined ? "--bundle" : "The task ref's bundle"} must reference a source name from your config. No source named "${selector}" is configured. Run \`akm bundle list\` to see available sources.`, "INVALID_FLAG_VALUE");
+        }
+        resolved = {
+            source: {
+                kind: source.type ?? "filesystem",
+                name: selector,
+                path: source.path,
+                adapterId: source.adapterId ?? detectAdapterId(source.path),
+            },
+        };
     }
     if (refBundle && resolved.source.name !== refBundle) {
         throw new UsageError(`Task ref bundle ${JSON.stringify(refBundle)} does not match the resolved source.`, "INVALID_FLAG_VALUE");
     }
     return resolved;
 }
-/**
- * New scheduler bindings always carry a canonical `--bundle <owner>` token,
- * including an env-selected working stash. That stash need not be persisted in
- * config (CI, one-shot tools, and fresh installs commonly use only
- * AKM_BUNDLE_DIR), so its scheduled child — every row sets AKM_BUNDLE_DIR to
- * the working stash it was synced from — must accept precisely its derived
- * owner name.
- *
- * This is intentionally narrower than an unknown-bundle fallback: a configured
- * source always wins, and an unconfigured selector is accepted only when it is
- * exactly the current env-selected working stash identity.
- */
-function resolveImplicitScheduledBundleTarget(config, selector) {
-    if (!process.env.AKM_BUNDLE_DIR?.trim())
-        return undefined;
-    try {
-        const working = resolveWorkingStashTarget(config, { requireWritable: false });
-        return working.source.name === selector ? working : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
 /** True when `candidate` resolves to the same directory as the primary stash. */
 function isPrimaryStashPath(candidate) {
     let primary;

package/dist/commands/ui/redact.js

@@ -7,15 +7,15 @@
  * anything secret-like by key name, because the UI shows config the CLI's
  * `config list` never had to defend against a browser leaking.
  *
- * Symbolic references (`$VAR`, `${VAR}`, `secret://name`) are kept: they say
+ * Symbolic references (`$VAR`, `${VAR}`, `${secrets/name}`) are kept: they say
  * where a credential comes from without being one.
  */
+import { isApiKeyReference } from "../../core/config/schema/primitives.js";
 const REDACTED = "[redacted]";
 /** Key names whose string values are credentials, or sit in a bag of them. */
 const SECRET_KEY = /(api[-_]?key|token|password|passwd|secret|credential|authorization|bearer|private[-_]?key)/i;
 /** A whole subtree of values (`env`, `secrets`) that is data, not settings. */
 const SECRET_BAG_KEY = /^(env|secrets?)$/i;
-const SYMBOLIC_REFERENCE = /^(\$[A-Za-z_][A-Za-z0-9_]*|\$\{[A-Za-z_][A-Za-z0-9_]*\}|secret:\/\/.+)$/;
 /** Query parameters that carry a credential in a URL. */
 const SECRET_QUERY_PARAM = /^(api[-_]?key|key|token|access[-_]?token|auth|password|secret|sig|signature)$/i;
 /** `scheme://user:pass@host/?token=x` with the credentials masked. Anything that is not a URL is returned as is. */
@@ -65,7 +65,7 @@ export function redactForUi(value, inSecretBag = false) {
     if (Array.isArray(value))
         return value.map((child) => redactForUi(child, inSecretBag));
     if (typeof value === "string") {
-        if (SYMBOLIC_REFERENCE.test(value))
+        if (isApiKeyReference(value))
             return value;
         return inSecretBag ? REDACTED : redactUrlCredentials(value);
     }
@@ -73,7 +73,7 @@ export function redactForUi(value, inSecretBag = false) {
         return inSecretBag && value !== null ? REDACTED : value;
     const result = {};
     for (const [key, child] of Object.entries(value)) {
-        if (typeof child === "string" && SECRET_KEY.test(key) && !SYMBOLIC_REFERENCE.test(child)) {
+        if (typeof child === "string" && SECRET_KEY.test(key) && !isApiKeyReference(child)) {
             result[key] = REDACTED;
         }
         else {

package/dist/commands/ui/workspace-actions.js

@@ -44,7 +44,7 @@ function positional(body, key) {
 }
 function preserveUnrelatedConfig(config = loadConfig()) {
     if (!isDeepStrictEqual(sanitizeConfigForWrite(config, { quiet: true }), config)) {
-        throw new UsageError("AKM's config sanitizer would remove unrelated credentials. Move literal API keys to $VAR or secret:// references and remove registry URL credentials using the CLI before changing bundle configuration in the UI.");
+        throw new UsageError("AKM's config sanitizer would remove unrelated credentials. Move literal API keys to $VAR or ${secrets/name} references and remove registry URL credentials using the CLI before changing bundle configuration in the UI.");
     }
 }
 /** The error kind behind each exit code of the CLI contract (`EXIT_CODES`, `src/cli/shared.ts`). */

package/dist/commands/workflow/plan.js

@@ -8,18 +8,22 @@
  * (`loadWorkflowAsset`, `freezeWorkflow`) and NOTHING else — never
  * `publishWorkflowRunV4`, `startWorkflowRun`, `appendEvent`, or `akmIndex`.
  *
- * SECRET-FREE, by construction (§4.6's closed print list): a resolved
- * reference VALUE is never printed (references resolve at pre-attempt, not
+ * SECRET-FREE, by construction (§4.6's closed print list): a step's
+ * `orchestration` is the authored argv, cwd and env names plus the
+ * bundle-qualified refs they resolve to (the projection `akm show` prints,
+ * never a value or a path); a resolved reference VALUE is never printed (references resolve at pre-attempt, not
  * here); a `literal` **environment** binding's value is never printed (only
- * `environment[].kind`/`.name`, and an `env-ref`'s `.ref`/`.keys`/
- * `.secretNames` — all NAMES); `request.command.content`,
+ * `environment[].kind`/`.name`, and an `env-ref`'s `.ref` — all NAMES);
+ * `request.command.content`,
  * `request.persona`, `request.conversation`, `request.runtime.environment`,
  * and a script target's `bytesBase64` are never read at all.
  */
 import { loadConfig } from "../../core/config/config.js";
+import { NotFoundError } from "../../core/errors.js";
 import { buildExecutionFromWire } from "../../integrations/agent/execution.js";
 import { freezeWorkflow } from "../../workflows/freeze/freeze.js";
 import { computePlanHash } from "../../workflows/ir/plan-hash.js";
+import { resolveOrchestrationRefs, summarizeStepOrchestration } from "../../workflows/renderer.js";
 import { loadWorkflowAsset } from "../../workflows/runtime/workflow-asset-loader.js";
 /** The step's dispatch unit — the map template for a fan-out, else the root unit. Undefined for a step not yet frozen. */
 function stepUnit(step) {
@@ -30,7 +34,7 @@ function stepUnit(step) {
 }
 function projectEnvironmentBinding(binding) {
     if (binding.kind === "env-ref") {
-        return { kind: binding.kind, ref: binding.ref, keys: binding.keys, secretNames: binding.secretNames };
+        return { kind: binding.kind, ref: binding.ref };
     }
     // literal / pass-through: kind + name only — a literal's VALUE is never printed.
     return { kind: binding.kind, name: binding.name };
@@ -46,14 +50,23 @@ function childExpansion(target) {
         via: "child",
         childRef: target.ref,
         childPlanHash: target.planHash,
-        steps: target.frozenPlan.steps.map((step, index) => projectStep(step, index)),
+        steps: target.frozenPlan.steps.map((step, index) => projectStep(step, index, stepOrchestration(step, target.frozenPlan))),
     };
 }
 /** The child expansion boundary for one step (§4.6). */
 function stepExpansion(frozenTarget) {
     return frozenTarget?.kind === "child-workflow" ? childExpansion(frozenTarget) : { via: "direct" };
 }
-function projectStep(step, sequenceIndex) {
+/**
+ * The step's `show` orchestration projection plus the refs it resolves to.
+ * `authored` is the compiled step (it keeps the spelling the author wrote);
+ * a child plan's steps have only their frozen form.
+ */
+function stepOrchestration(step, plan) {
+    const summary = summarizeStepOrchestration(step, plan.defaults);
+    return summary && resolveOrchestrationRefs(summary);
+}
+function projectStep(step, sequenceIndex, orchestration) {
     const unit = stepUnit(step);
     const frozenTarget = unit?.frozenTarget;
     const kind = step.root?.kind === "map" ? "map" : "unit";
@@ -65,6 +78,7 @@ function projectStep(step, sequenceIndex) {
         targetKind: frozenTarget?.kind ?? null,
         ...(step.root?.kind === "map" ? { concurrency: step.root.concurrency } : {}),
         inputs: unit?.inputs ?? [],
+        ...(orchestration ? { orchestration } : {}),
         environment: (unit?.environment ?? []).map(projectEnvironmentBinding),
         ...(inputBindings && inputBindings.length > 0 ? { inputBindings: inputBindings.map(projectInputBinding) } : {}),
         gate: {
@@ -102,15 +116,40 @@ function collectLoweringNotices(plan, config) {
     }
     return notices;
 }
+/** Every ref the steps' orchestration names that no bundle owns, as `ref (where of step "id")`. */
+function unresolvedRefs(steps, orchestrations) {
+    return orchestrations.flatMap((orchestration, index) => (orchestration?.unresolved ?? []).map((missing) => `${missing.ref} (${missing.in} of step "${steps[index]?.stepId}")`));
+}
+/** The unresolved refs of every embedded child plan, recursively, each prefixed with the child workflow it is in. */
+function unresolvedInChildren(plan) {
+    return plan.steps.flatMap((step) => {
+        const target = stepUnit(step)?.frozenTarget;
+        if (target?.kind !== "child-workflow")
+            return [];
+        const child = target.frozenPlan;
+        const own = unresolvedRefs(child.steps, child.steps.map((childStep) => stepOrchestration(childStep, child)));
+        return [...own.map((entry) => `${entry} in child ${target.ref}`), ...unresolvedInChildren(child)];
+    });
+}
+function failOnUnresolved(ref, unresolved) {
+    if (unresolved.length === 0)
+        return;
+    throw new NotFoundError(`Workflow ${ref} names asset(s) that no bundle owns: ${unresolved.join(", ")}.`, "FILE_NOT_FOUND");
+}
 /**
  * Compile + freeze `ref` and project the frozen plan into the read-only
  * `akm workflow plan` envelope. Never publishes, never writes, never warns.
  */
 export async function akmWorkflowPlan(ref) {
     const asset = await loadWorkflowAsset(ref);
+    // Resolve what the authored steps name before freezing: a `${ref}`, env ref or child workflow no bundle owns fails the plan.
+    const orchestrations = asset.plan.steps.map((step) => stepOrchestration(step, asset.plan));
+    failOnUnresolved(asset.ref, unresolvedRefs(asset.plan.steps, orchestrations));
     const config = loadConfig();
     const frozen = await freezeWorkflow(asset, config);
     const plan = frozen.plan;
+    // A child workflow's steps exist only once frozen; they fail the plan exactly as the top level's do.
+    failOnUnresolved(asset.ref, unresolvedInChildren(plan));
     return {
         ok: true,
         ref: asset.ref,
@@ -123,7 +162,7 @@ export async function akmWorkflowPlan(ref) {
         execution: plan.execution,
         ...(plan.budget ? { budget: plan.budget } : {}),
         ...(plan.params ? { params: plan.params } : {}),
-        steps: plan.steps.map((step, index) => projectStep(step, index)),
+        steps: plan.steps.map((step, index) => projectStep(step, index, orchestrations[index])),
         notices: collectLoweringNotices(plan, config),
         warnings: frozen.warnings.map((warning) => warning.message),
     };

package/dist/commands/workflow-cli.js

@@ -2,8 +2,9 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
- * `akm workflow` command family. `run` is the canonical start/resume/execute
- * surface; the former public `start`, `next`, and `complete` lifecycle is gone.
+ * `akm workflow` command family. `run` is the canonical start/execute surface
+ * (a ref starts a new run, a run id drives that run) and `resume` reopens a
+ * run; the former public `start`, `next`, and `complete` lifecycle is gone.
  * `create --print` emits Markdown, the only workflow source format. Validate
  * with `akm lint --type workflows`.
  */
@@ -13,7 +14,6 @@ import { armAbortDeadline } from "../core/abort-deadline.js";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../core/asset/asset-create.js";
 import { NotFoundError, TransientError, UsageError } from "../core/errors.js";
 import { warn } from "../core/warn.js";
-import { akmIndex } from "../indexer/indexer.js";
 import { assertWorkflowMarkdownName, createWorkflowAsset, getWorkflowTemplate } from "../workflows/authoring/authoring.js";
 import { WORKFLOW_MAX_TIMEOUT_MS } from "../workflows/resource-limits.js";
 import { abandonWorkflowRun, getWorkflowStatus, listWorkflowRuns, resolveWorkflowRunTarget, resumeWorkflowRun, } from "../workflows/runtime/runs.js";
@@ -21,7 +21,7 @@ import { akmWorkflowPlan } from "./workflow/plan.js";
 const workflowStatusCommand = defineJsonCommand({
     meta: {
         name: "status",
-        description: "Show full workflow run state for review or resume; workflow refs resolve within the current scope",
+        description: "Show full workflow run state for review or resume; a workflow ref shows its most recent run",
     },
     args: {
         target: { type: "positional", description: "Workflow run id or workflow ref (workflows/<name>)", required: true },
@@ -31,16 +31,17 @@ const workflowStatusCommand = defineJsonCommand({
                 "diagnostic text). Diagnostics only — step evidence stays deterministic and is unaffected.",
             default: false,
         },
+        // Deprecated no-op, accepted through 0.10 so scripts that pass it do not
+        // fail with UNKNOWN_FLAG. Runs are no longer scoped to a directory.
         "all-scopes": {
             type: "boolean",
-            description: "When resolving a workflow ref (not a run id), search every scope instead of only the current one (#942).",
+            description: "Deprecated, no effect: runs are host-wide, not scoped to a directory. Accepted through 0.10 for existing scripts.",
             default: false,
         },
     },
     async run({ args }) {
         const target = args.target;
         const includeUnits = args.units === true;
-        const allScopes = args["all-scopes"] === true;
         const resolvedRunId = await resolveWorkflowRunTarget(target);
         if (resolvedRunId !== undefined) {
             const result = await getWorkflowStatus(resolvedRunId, { includeUnits });
@@ -48,9 +49,8 @@ const workflowStatusCommand = defineJsonCommand({
             return;
         }
         let runs;
-        let scopeKey;
         try {
-            ({ runs, scopeKey } = await listWorkflowRuns({ workflowRef: target, allScopes }));
+            ({ runs } = await listWorkflowRuns({ workflowRef: target }));
         }
         catch (error) {
             if (!target.includes(":") && !target.includes("/")) {
@@ -60,14 +60,6 @@ const workflowStatusCommand = defineJsonCommand({
         }
         const mostRecent = runs[0];
         if (!mostRecent) {
-            // #942: name the scope actually searched and point at `--all-scopes`
-            // rather than a bare "not found" — the ref-fallthrough lookup is
-            // scope-local by default, so "no runs" here means "none in THIS
-            // scope", not "none anywhere". Already searching every scope (or no
-            // real scope was filtered on) has nothing more specific to suggest.
-            if (!allScopes && scopeKey !== null) {
-                throw new NotFoundError(`No workflow runs found for ${target} in scope ${scopeKey}.`, "WORKFLOW_NOT_FOUND", `Run 'akm workflow status ${target} --all-scopes' to search every scope.`);
-            }
             throw new NotFoundError(`No workflow runs found for ${target}`, "WORKFLOW_NOT_FOUND");
         }
         const result = await getWorkflowStatus(mostRecent.id, { includeUnits });
@@ -77,9 +69,7 @@ const workflowStatusCommand = defineJsonCommand({
 const workflowListCommand = defineJsonCommand({
     meta: {
         name: "list",
-        description: "List workflow runs in the current working scope. A scheduled task runs from the scheduler's cwd, so its runs " +
-            "sit in another scope: get the run id from `akm task history <task-id> --limit 1` (detail.runId) and pass it " +
-            "to `akm workflow status <run-id>`, which works from any directory, or pass --all-scopes.",
+        description: "List workflow runs on this host, most recently updated first",
     },
     args: {
         ref: { type: "string", description: "Filter to one workflow ref" },
@@ -89,11 +79,11 @@ const workflowListCommand = defineJsonCommand({
             description: "Also include child workflow runs (hidden by default, P3b)",
             default: false,
         },
+        // Deprecated no-op, accepted through 0.10 so scripts that pass it do not
+        // fail with UNKNOWN_FLAG. Runs are no longer scoped to a directory.
         "all-scopes": {
             type: "boolean",
-            description: "Search every scope instead of only the current one (#942). The envelope's top-level `scopeKey` is " +
-                "`null` with this flag, otherwise the scope that was searched — so an empty `runs: []` is never " +
-                'indistinguishable from "nothing anywhere".',
+            description: "Deprecated, no effect: runs are host-wide, not scoped to a directory. Accepted through 0.10 for existing scripts.",
             default: false,
         },
     },
@@ -102,7 +92,6 @@ const workflowListCommand = defineJsonCommand({
             workflowRef: args.ref,
             activeOnly: args.active,
             includeChildren: args.children,
-            allScopes: args["all-scopes"],
         });
         output("workflow-list", result);
     },
@@ -158,12 +147,6 @@ const workflowCreateCommand = defineJsonCommand({
             from: args.from,
             force: args.force,
         });
-        // Index the newly-written workflow so `akm workflow run` can resolve
-        // a workflowEntryId without requiring an explicit `akm index` call
-        // first. Uses the same incremental index path that `akm add` uses.
-        // `result.bundleDir` — the indexer's own `IndexOptions.stashDir` field
-        // name is unchanged (indexer vocabulary is out of scope, P4 row B-50).
-        await akmIndex({ stashDir: result.bundleDir });
         output("workflow-create", { ok: true, ...result });
     },
 });
@@ -184,29 +167,34 @@ const WORKFLOW_RUN_SKIP_REASONS = {
 const workflowRunCommand = defineJsonCommand({
     meta: {
         name: "run",
-        description: "Start or resume a workflow and execute it through completion, failure, a verification gate, or an explicit limit",
+        description: "Start a new run of a workflow ref, or drive an existing run by id, through completion, failure, a verification gate, or an explicit limit",
     },
     args: {
-        target: { type: "positional", description: "Workflow run id or workflow ref (auto-starts a run)", required: true },
+        target: {
+            type: "positional",
+            description: "Workflow ref (starts a new run) or workflow run id (drives that run)",
+            required: true,
+        },
         "max-steps": { type: "string", description: "Stop after executing this many steps" },
         "max-retries": { type: "string", description: "Retry a failed workflow step this many additional times" },
         timeout: { type: "string", description: "Whole-run timeout: N, Nms, Ns, or Nm (bare N is milliseconds)" },
+        // Deprecated no-op, accepted through 0.10 so scripts that pass it do not
+        // fail with UNKNOWN_FLAG. A workflow ref always starts a new run now.
         new: {
             type: "boolean",
-            description: "Start a fresh run even if one is already active for this ref, leaving the existing run untouched " +
-                "(never abandons it). A workflow ref only — passing a run id with --new is a usage error.",
+            description: "Deprecated, no effect: a workflow ref always starts a new run. Accepted through 0.10 for existing scripts.",
             default: false,
         },
         "skip-if-locked": {
             type: "boolean",
-            description: "If another akm process is already driving this run, or state.db is busy with another " +
-                "writer, skip gracefully (exit 0) instead of failing (exit 75). Use for high-frequency scheduled runs " +
-                "so they don't pile up failures while a longer-running invocation is in progress.",
+            description: "If another akm process is already driving this run (or, for a workflow ref, an active run of it), or " +
+                "state.db is busy with another writer, skip gracefully (exit 0) instead of failing (exit 75). Use for " +
+                "high-frequency scheduled runs so they don't pile up failures while a longer-running invocation is in progress.",
             default: false,
         },
     },
     async run({ args, rawArgs }) {
-        const { runWorkflowSteps } = await import("../workflows/exec/run-workflow.js");
+        const { findLiveLockedRunOfRef, runWorkflowSteps } = await import("../workflows/exec/run-workflow.js");
         const parameterFlags = parseWorkflowParameterFlags(rawArgs, args.target);
         const maxSteps = parseIntegerFlag(getStringArg(args, "max-steps"), "--max-steps", 1);
         const maxRetries = parseIntegerFlag(getStringArg(args, "max-retries"), "--max-retries", 0);
@@ -228,15 +216,25 @@ const workflowRunCommand = defineJsonCommand({
             timeoutMs,
             reason: `Workflow run timed out after ${timeoutMs}ms.`,
         });
+        const skip = (reason, message) => {
+            warn(`[workflow] ${message} skipping (--skip-if-locked)`);
+            output("workflow-run", { ok: true, target: args.target, skipped: { reason, message } });
+        };
         try {
             let result;
             try {
+                // #1239: a ref start never conflicts with another run of the ref, so
+                // the one extra condition is an active run of it a live process is driving.
+                const held = skipIfLocked ? await findLiveLockedRunOfRef(args.target) : undefined;
+                if (held) {
+                    skip("lock-held", `Workflow run ${held.runId} of ${args.target} is already being driven by another akm process (pid ${held.holder}).`);
+                    return;
+                }
                 result = await runWorkflowSteps({
                     target: args.target,
                     parameterFlags,
                     ...(maxSteps !== undefined ? { maxSteps } : {}),
                     ...(maxRetries !== undefined ? { maxRetries } : {}),
-                    newRun: args.new,
                     signal: controller.signal,
                 });
             }
@@ -247,9 +245,7 @@ const workflowRunCommand = defineJsonCommand({
                 // off UsageError) — a bad flag or malformed input still fails loudly
                 // even with the flag set.
                 if (skipIfLocked && err instanceof TransientError && WORKFLOW_RUN_SKIP_REASONS[err.code]) {
-                    const reason = WORKFLOW_RUN_SKIP_REASONS[err.code];
-                    warn(`[workflow] ${err.message} skipping (--skip-if-locked)`);
-                    output("workflow-run", { ok: true, target: args.target, skipped: { reason, message: err.message } });
+                    skip(WORKFLOW_RUN_SKIP_REASONS[err.code], err.message);
                     return;
                 }
                 throw err;

package/dist/core/adapter/adapters/akm-adapter.js

@@ -83,6 +83,7 @@ import path from "node:path";
 import { applyPostContributorFields, applyPreContributorFields, extractPackageMetadata, getMarkdownFragmentContent, hasMarkdownFragmentContent, setMarkdownFragmentContent, } from "../../../indexer/passes/metadata.js";
 import { assetPathCandidatesForName, deriveCanonicalAssetNameFromStashRoot, placementTypes, stashDirFor, stashDirNames, } from "../../asset/asset-placement.js";
 import { parseFrontmatter } from "../../asset/frontmatter.js";
+import { sensitiveMarkerPath } from "../../sensitive-marker-path.js";
 import { executionDefaultsFromFrontmatter, renderMarkdownExecutionSource } from "../execution-source.js";
 import { recognizeMatch } from "../recognize-match.js";
 import { perTypeValidateChecks, skillDirectoryDiagnostics } from "./akm-lint.js";
@@ -136,7 +137,7 @@ function akmStashAbstains(root, absPath) {
         return true;
     // Skip env `.env` files that have a sibling `.sensitive` marker file.
     if (segments[0] === "env" && (absPath.endsWith(".env") || path.basename(absPath) === ".env")) {
-        if (fs.existsSync(absPath.replace(/\.env$/, ".sensitive")))
+        if (fs.existsSync(sensitiveMarkerPath(absPath, "env")))
             return true;
     }
     // Skip secret files that are themselves a `.sensitive` marker, or that have a
@@ -145,7 +146,7 @@ function akmStashAbstains(root, absPath) {
     if (segments[0] === "secrets") {
         if (absPath.endsWith(".sensitive") || absPath.endsWith(".lock"))
             return true;
-        if (fs.existsSync(`${absPath}.sensitive`))
+        if (fs.existsSync(sensitiveMarkerPath(absPath, "secret")))
             return true;
     }
     // Inside a `wikis/<name>/` directory, the root-level infrastructure files
@@ -439,7 +440,6 @@ async function validate(c, changes, ctx) {
             body: parsed.content,
             ext: overlay.ext,
             ctx,
-            workspaceRoot: c.root,
         })));
         diagnostics.push(...(await skillDirectoryDiagnostics(change.path, seenSkillDirs, ctx)));
     }

package/dist/core/adapter/adapters/akm-lint.js

@@ -207,7 +207,7 @@ export async function skillDirectoryDiagnostics(relPath, seen, ctx, skillDirs =
  * routes through `ctx`.
  */
 export async function perTypeValidateChecks(args) {
-    const { type, relPath, raw, data, frontmatter, body, ext, ctx, workspaceRoot } = args;
+    const { type, relPath, raw, data, frontmatter, body, ext, ctx } = args;
     switch (type) {
         case "command":
             return nameOrTypeDiagnostics(relPath, data, frontmatter, ["command"]);
@@ -216,7 +216,7 @@ export async function perTypeValidateChecks(args) {
         case "fact":
             return factDiagnostics(relPath, data);
         case "task":
-            return taskDiagnostics(relPath, raw, workspaceRoot);
+            return taskDiagnostics(relPath, raw);
         case "workflow":
             return ext === ".md" ? workflowDiagnostics(relPath, raw, body) : [];
         case "memory":
@@ -266,12 +266,11 @@ export function factDiagnostics(relPath, data) {
  * contract; the cron suits the local scheduler backend), so `akm lint --type
  * tasks` never reports clean a task that sync would refuse.
  */
-export function taskDiagnostics(relPath, raw, workspaceRoot) {
+export function taskDiagnostics(relPath, raw) {
     try {
         const parsed = parseTaskSource({
             filePath: relPath,
             yaml: raw,
-            ...(workspaceRoot ? { workspaceRoot } : {}),
         });
         assertTaskScheduleInputsSatisfyContract(parsed.v4, relPath);
         assertTaskScheduleCronValid(parsed.v4, backendNameForPlatform());

package/dist/core/adapter/adapters/akm-metadata.js

@@ -170,7 +170,7 @@ export function foldRecognizedMetadata(rendererName, file) {
         case "task-yaml": {
             out.tags = Array.from(new Set([...(out.tags ?? []), "task", "scheduled"]));
             try {
-                const parsed = parseTaskSource({ yaml: file.content(), filePath: file.absPath, workspaceRoot: file.stashRoot });
+                const parsed = parseTaskSource({ yaml: file.content(), filePath: file.absPath });
                 const v4 = parsed.v4;
                 const target = v4.target;
                 const hints = new Set();
@@ -261,7 +261,7 @@ export function foldRecognizedMetadata(rendererName, file) {
         // ── workflow-document-metadata (historical renderer id `workflow-md`, peer sources) ──
         case "workflow-md": {
             try {
-                const result = compileWorkflowSource(file.content(), { path: file.relPath, workspaceRoot: file.stashRoot });
+                const result = compileWorkflowSource(file.content(), { path: file.relPath });
                 if (!result.ok)
                     return out;
                 const plan = result.plan;