akm-cli 0.10.261012-beta → 0.10.261013-beta

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

@@ -21,9 +21,8 @@
  * document fails closed with `TASK_SCHEMA_VERSION_UNSUPPORTED`, naming
  * `akm migrate apply`, which converts it). That parser owns the closed key sets,
  * the executable-selector XOR, hostile YAML policy, the `akm/command`
- * builtin, bounds, and physical `working-directory` containment. The
- * adapter only translates a parser failure into the format-family
- * diagnostic shape.
+ * builtin, and bounds. The adapter only translates a parser failure into
+ * the format-family diagnostic shape.
  *
  * Conformance oracle (authored, DO NOT modify): fixture
  * `tests/fixtures/bundles/akm-task/` + goldens
@@ -59,7 +58,7 @@ function recognize(c, file) {
         content: raw,
     };
 }
-async function validate(c, changes, ctx) {
+async function validate(_c, changes, ctx) {
     const diagnostics = [];
     for (const change of changes) {
         if (change.op === "delete")
@@ -84,7 +83,7 @@ async function validate(c, changes, ctx) {
             continue;
         }
         try {
-            parseTaskSource({ yaml: raw, filePath: relPath, workspaceRoot: c.root });
+            parseTaskSource({ yaml: raw, filePath: relPath });
         }
         catch (cause) {
             diagnostics.push({
@@ -145,7 +144,7 @@ export const akmTaskAdapter = {
                 continue;
             }
             try {
-                parseTaskSource({ yaml: raw, filePath: entry.name, workspaceRoot: root });
+                parseTaskSource({ yaml: raw, filePath: entry.name });
                 return true;
             }
             catch {

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

@@ -31,6 +31,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { assetPathCandidatesForName, typeForStashDir } from "../../asset/asset-placement.js";
 import { scanEnvKeyNames, toPosix } from "../../common.js";
+import { sensitiveMarkerPath } from "../../sensitive-marker-path.js";
 import { dangerousEnvKeyDiagnostics } from "./akm-lint.js";
 import { hashContent } from "./shared.js";
 /** A dotenv bundle is single-component; its one component is `main`. */
@@ -73,7 +74,7 @@ function classify(relPath) {
  * disagreed about a documented promise.
  */
 function hasSensitiveMarker(absPath, type) {
-    const marker = type === "env" ? absPath.replace(/\.env$/i, ".sensitive") : `${absPath}.sensitive`;
+    const marker = sensitiveMarkerPath(absPath, type === "env" ? "env" : "secret");
     return marker !== absPath && fs.existsSync(marker);
 }
 function conceptIdForPath(type, relativePath) {
@@ -167,8 +168,8 @@ export const dotenvAdapter = {
             return [];
         const primaries = assetPathCandidatesForName(type, path.join(c.root, head), rest);
         const expanded = primaries.flatMap((primary) => type === "env"
-            ? [primary, primary.replace(/\.env$/i, ".sensitive")]
-            : [primary, `${primary}.sensitive`, `${primary}.lock`]);
+            ? [primary, sensitiveMarkerPath(primary, "env")]
+            : [primary, sensitiveMarkerPath(primary, "secret"), `${primary}.lock`]);
         return expanded.map((candidatePath) => ({ path: candidatePath, conceptId: posix }));
     },
     /** The dotenv bundle owns its `env/` + `secrets/` dirs. */

package/dist/core/asset/resolve-ref.js

@@ -12,6 +12,11 @@
  *                 against an injected {@link RefContext}. This is the "the short
  *                 form is input sugar" rule (§11.1) made structural: only a
  *                 `ResolvedRef` ever crosses a storage boundary.
+ *                 It answers "which bundle" against an injected index snapshot;
+ *                 it does not find files. "Where is the file for this ref right
+ *                 now" has one answer, `resolveConceptOwner`
+ *                 (`src/indexer/lookup/adapter-concept-owner.ts`), which
+ *                 every resolver that needs a path calls.
  *   - serialize — `bundleRefToString` (`asset-ref.ts`); serializing a
  *                 `ResolvedRef` always emits the fully-qualified form.
  *

package/dist/core/bundle-rename.js

@@ -6,7 +6,7 @@
  * bundle's key. A bundle id is a mass identity prefix: every durable ref this
  * tool minted (`entries.item_ref`/`bundle_id`, `proposals.ref`, a pending
  * proposal's `proposedTarget.source`, a workflow task_history row's
- * `target_ref`, `scheduler.enabled[].ref`) carries it, and a hand-edited
+ * `target_ref`, a `workflow_runs.workflow_ref`, `scheduler.enabled[].ref`) carries it, and a hand-edited
  * `bundles` key strands all of it (see `src/indexer/bundle-identity-guard.ts`
  * §11.5). This module is the rekey transaction that guard's docstring points
  * to.
@@ -32,6 +32,7 @@ import { closeDatabase, openIndexDatabase, openReadonlyExistingDatabase, } from
 import { getFilePathsByBundle, renameEntriesBundleId } from "../storage/repositories/index-entries-repository.js";
 import { countProposalsForBundleRename, renameProposalsBundleRef } from "../storage/repositories/proposals-repository.js";
 import { countTaskHistoryTargetRefs, renameTaskHistoryTargetRefs, } from "../storage/repositories/task-history-repository.js";
+import { countWorkflowRunRefsForRename, renameWorkflowRunRefs } from "../storage/repositories/workflow-runs-repository.js";
 import { selectBackend } from "../tasks/backends/index.js";
 import { bundleRefToString, parseBundleRef } from "./asset/asset-ref.js";
 import { validateExplicitBundleName } from "./bundle-id.js";
@@ -152,12 +153,17 @@ async function buildPlan(config, oldId, newId, sched) {
     let proposalRefs = 0;
     let proposalTargets = 0;
     let taskHistoryRefs = 0;
+    let workflowRunRefs = 0;
+    let activeWorkflowRuns = [];
     if (fs.existsSync(getStateDbPath())) {
         withStateDb((db) => {
             const counts = countProposalsForBundleRename(db, oldId);
             proposalRefs = counts.refs;
             proposalTargets = counts.targets;
             taskHistoryRefs = countTaskHistoryTargetRefs(db, oldId);
+            const runs = countWorkflowRunRefsForRename(db, oldId);
+            workflowRunRefs = runs.refs;
+            activeWorkflowRuns = runs.active;
         });
     }
     return {
@@ -170,7 +176,8 @@ async function buildPlan(config, oldId, newId, sched) {
         },
         lock: { present: lockPresent },
         index: { entries: indexEntries },
-        state: { proposalRefs, proposalTargets, taskHistoryRefs },
+        state: { proposalRefs, proposalTargets, taskHistoryRefs, workflowRunRefs },
+        activeWorkflowRuns,
         contentRefs,
         nativeSchedulerRows,
     };
@@ -254,12 +261,13 @@ export async function renameBundle(oldId, newId, options = {}, deps) {
             closeDatabase(writeIndexDb);
         }
     }
-    // State: proposals.ref, a pending proposal's proposedTarget.source, and
-    // workflow task_history.target_ref.
+    // State: proposals.ref, a pending proposal's proposedTarget.source,
+    // workflow task_history.target_ref, and workflow_runs.workflow_ref.
     if (fs.existsSync(getStateDbPath())) {
         withStateDb((db) => {
             renameProposalsBundleRef(db, oldId, newId);
             renameTaskHistoryTargetRefs(db, oldId, newId);
+            renameWorkflowRunRefs(db, oldId, newId);
         });
     }
     // Scheduler: remove native rows still naming `<old>//` (see

package/dist/core/common.js

@@ -376,25 +376,6 @@ export function hasErrnoCode(error, code) {
 export function isChmodUnsupported(error) {
     return hasErrnoCode(error, "EPERM") || hasErrnoCode(error, "ENOTSUP") || hasErrnoCode(error, "EINVAL");
 }
-/**
- * True when `value` is a RELATIVE path that cannot leave its base directory:
- * no absolute form (POSIX `/`, Windows `\` or a `C:` drive prefix), no `~`
- * home expansion, and no `..` segment under either separator.
- *
- * This is the SYNTACTIC half of containment — cheap, string-only, usable at
- * authoring time before any directory exists. It is deliberately paired with
- * (never a substitute for) {@link isWithin}, which resolves symlinks against a
- * real base at use time. Workflow `exec` units run both: the parser and the
- * frozen-plan decoder reject uncontained spellings, and the executor re-checks
- * the resolved path before spawning.
- */
-export function isContainedRelativePath(value) {
-    if (value === "" || value.startsWith("/") || value.startsWith("\\") || value.startsWith("~"))
-        return false;
-    if (/^[A-Za-z]:/.test(value))
-        return false;
-    return !value.split(/[/\\]+/).includes("..");
-}
 export function isWithin(candidate, root) {
     return isContainedResolvedPath(safeRealpath(candidate), safeRealpath(root));
 }
@@ -419,16 +400,11 @@ export function isAkmRegistryCachePath(filePath) {
     return isWithin(filePath, getRegistryCacheDir()) || isWithin(filePath, getRegistryIndexCacheDir());
 }
 /**
- * {@link isWithin} for callers that must not block the event loop (e.g. the
- * workflow exec dispatch path, which runs once per fan-out unit). Same
- * comparison, same normalization, same nearest-existing-ancestor fallback —
- * only the realpath syscalls are awaited.
+ * The containment comparison behind {@link isWithin}.
+ * Called directly with `path.resolve`d arguments it is a lexical check: it
+ * refuses `..` and absolute names without following symlinks.
  */
-export async function isWithinAsync(candidate, root) {
-    return isContainedResolvedPath(await safeRealpathAsync(candidate), await safeRealpathAsync(root));
-}
-/** The containment comparison shared by {@link isWithin} and {@link isWithinAsync}. */
-function isContainedResolvedPath(resolvedCandidate, resolvedRoot) {
+export function isContainedResolvedPath(resolvedCandidate, resolvedRoot) {
     const rel = path.relative(normalizeFsPathForComparison(resolvedRoot), normalizeFsPathForComparison(resolvedCandidate));
     if (rel === "")
         return true;
@@ -475,30 +451,6 @@ export function safeRealpath(p) {
         }
     }
 }
-/** {@link safeRealpath}'s async twin — awaited syscalls, identical walk-up. */
-export async function safeRealpathAsync(p) {
-    const resolved = path.resolve(p);
-    try {
-        return await fs.promises.realpath(resolved);
-    }
-    catch {
-        const suffix = [];
-        let current = resolved;
-        for (;;) {
-            const parent = path.dirname(current);
-            if (parent === current)
-                return resolved;
-            suffix.unshift(path.basename(current));
-            current = parent;
-            try {
-                return path.join(await fs.promises.realpath(current), ...suffix);
-            }
-            catch {
-                // parent also doesn't exist; keep walking up
-            }
-        }
-    }
-}
 function normalizeFsPathForComparison(value) {
     return process.platform === "win32" ? value.toLowerCase() : value;
 }

package/dist/core/config/config-walker.js

@@ -219,7 +219,7 @@ export function configSet(config, dotted, raw) {
                 ? { success: true, data: value }
                 : {
                     success: false,
-                    error: { issues: [{ path: [], message: "apiKey must be $VAR, ${VAR}, or secret://<name>" }] },
+                    error: { issues: [{ path: [], message: "apiKey must be $VAR, ${VAR}, or ${secrets/<name>}" }] },
                 }
             : isUnknownKey
                 ? { success: true, data: value }

package/dist/core/config/config.js

@@ -9,13 +9,14 @@ import { isBundleSlug } from "../asset/asset-ref.js";
 import { deriveBundleId } from "../bundle-id.js";
 import { isRecord, resolveStashDir } from "../common.js";
 import { ConfigError } from "../errors.js";
+import { isRefToken, substituteRefTokens } from "../ref-token.js";
 import { formatRegistryLabel, hasRegistryUrlCredentials } from "../registry-url.js";
 import { acquireConfigLock, backupExistingConfig, parseConfigText, readConfigText, withConfigLock, writeConfigAtomic, } from "./config-io.js";
 import { AkmConfigSchema, CURRENT_CONFIG_VERSION } from "./config-schema.js";
 import { bundleComponentConfig, bundleContentRoot, bundleContentRoots, bundleSourceId, bundlesToSourceEntries, filesystemBundleSourceId, isBundleEnabled, } from "./config-sources.js";
 import { resolveSchemaAt } from "./config-walker.js";
 import { deepMergeConfig, isPlainObject } from "./deep-merge.js";
-import { isApiKeyReference, SECRET_STORE_REFERENCE_PATTERN } from "./schema/primitives.js";
+import { isApiKeyReference } from "./schema/primitives.js";
 export { stripJsonComments } from "./config-io.js";
 import { getConfigPath } from "../paths.js";
 import { warn, warnOnce } from "../warn.js";
@@ -102,7 +103,43 @@ export function loadUserConfig() {
  * the file that extends it.
  */
 function runConfigFilePipeline(text, sourcePath) {
-    return readConfigVersion(parseConfigText(text, sourcePath), sourcePath);
+    const raw = parseConfigText(text, sourcePath);
+    return readConfigVersion(readRetiredSecretRefs(raw, [], sourcePath), sourcePath);
+}
+/** The retired `secret://<name>` credential form; it survives only in {@link readRetiredSecretRefs}. */
+const SECRET_STORE_REFERENCE_PATTERN = /^secret:\/\/(.+)$/;
+/**
+ * The `${ref}` a retired `secret://<x>` value reads as: `${<x>}` when `<x>` is
+ * already a full ref, else `${secrets/<x>}`. `undefined` for any other string.
+ * Shared by the config reader and the frozen workflow runner decoder.
+ */
+export function liftRetiredSecretRef(value) {
+    const name = SECRET_STORE_REFERENCE_PATTERN.exec(value)?.[1];
+    if (name === undefined)
+        return undefined;
+    return isRefToken(`\${${name}}`) ? `\${${name}}` : `\${secrets/${name}}`;
+}
+/**
+ * `secret://<x>` is retired in favour of `${ref}`. A value in that form is read
+ * as its {@link liftRetiredSecretRef} with one warning naming the key; every
+ * ordinary config write and `akm migrate apply`'s `configFile` step then
+ * persist the new form.
+ */
+function readRetiredSecretRefs(node, keyPath, sourcePath) {
+    if (typeof node === "string") {
+        const lifted = liftRetiredSecretRef(node);
+        if (lifted === undefined)
+            return node;
+        const dotted = keyPath.join(".");
+        warnOnce(`config:secret-scheme:${sourcePath ?? "inline"}:${dotted}`, `${dotted}${sourcePath ? ` at ${sourcePath}` : ""} uses the retired ${JSON.stringify(node)} form; reading it as ${JSON.stringify(lifted)}. \`akm migrate apply\` rewrites config.json.`);
+        return lifted;
+    }
+    if (Array.isArray(node))
+        return node.map((child, i) => readRetiredSecretRefs(child, [...keyPath, String(i)], sourcePath));
+    if (isPlainConfigObject(node)) {
+        return Object.fromEntries(Object.entries(node).map(([key, child]) => [key, readRetiredSecretRefs(child, [...keyPath, key], sourcePath)]));
+    }
+    return node;
 }
 /**
  * `configVersion` is read, never gated on. `"0.9.0"` is the only value akm
@@ -812,10 +849,10 @@ export function updateConfig(partial) {
 }
 /**
  * Resolve a single secret value: expand `${VAR}` / `$VAR` against
- * `process.env`, or look up `secret://<name>` via `resolveFromStore`. Use this
- * at apiKey / authorization-header consumption sites (LLM client, embedder,
- * agent SDK runner) — NOT on the load path. Non-string inputs pass through
- * unchanged.
+ * `process.env`, then substitute `${ref}` tokens (`${secrets/name}`) through
+ * `resolveFromStore`. Use this at apiKey / authorization-header consumption
+ * sites (LLM client, embedder, agent SDK runner) — NOT on the load path.
+ * Non-string inputs pass through unchanged.
  *
  * Returns the input unchanged when no substitution markers are present, so
  * literal API key strings (already-resolved secrets) are zero-cost.
@@ -824,26 +861,18 @@ export function updateConfig(partial) {
  * preserved verbatim on read — only fields explicitly routed through this
  * helper are expanded.
  *
- * A `secret://<name>` value that fails to resolve throws `ConfigError`
- * (naming the ref, never the secret) rather than silently sending an unusable
- * credential.
+ * A `${ref}` that fails to resolve throws `ConfigError` (naming the ref, never
+ * the secret) rather than silently sending an unusable credential.
  */
 export function resolveSecret(value, resolveFromStore) {
     if (value === undefined)
         return undefined;
     if (typeof value !== "string")
         return value;
-    const storeRef = SECRET_STORE_REFERENCE_PATTERN.exec(value)?.[1];
-    if (storeRef !== undefined) {
-        const resolved = resolveFromStore?.(storeRef) ?? null;
-        if (resolved === null) {
-            throw new ConfigError(`Secret store reference "${value}" did not resolve to a stored value.`, "SECRET_REFERENCE_UNRESOLVED");
-        }
-        return resolved;
-    }
     if (!value.includes("$"))
         return value;
-    return value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (_match, braced, bare) => {
+    // Env expansion runs first so a secret value containing `$` is never re-expanded.
+    const expanded = value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (_match, braced, bare) => {
         const name = (braced ?? bare);
         const resolved = process.env[name];
         if (!resolved) {
@@ -854,6 +883,14 @@ export function resolveSecret(value, resolveFromStore) {
         }
         return resolved ?? "";
     });
+    const { values, missing } = substituteRefTokens({ value: expanded }, (ref) => {
+        const stored = resolveFromStore?.(ref) ?? null;
+        return stored === null ? undefined : { kind: "secret", value: stored };
+    });
+    if (missing.length > 0) {
+        throw new ConfigError(`Secret store reference "\${${missing[0]}}" did not resolve to a stored value.`, "SECRET_REFERENCE_UNRESOLVED");
+    }
+    return values.value;
 }
 // Re-export source runtime helpers — implementation lives in config-sources.ts.
 export { bundleComponentConfig, bundleContentRoot, bundleContentRoots, bundleEntryToSourceEntry, bundleKeyForContentRoot, bundlePhysicalContentRoot, bundleSourceId, bundlesToSourceEntries, installedSourceDescriptor, isBundleEnabled, parseSourceSpec, primaryBundlePath, resolveActiveConfiguredSources, resolveConfiguredSources, } from "./config-sources.js";

package/dist/core/config/schema/primitives.js

@@ -8,6 +8,7 @@
  */
 import { z } from "zod";
 import { validateExtraParams } from "../../extra-params.js";
+import { isRefToken, isSecretRefToken } from "../../ref-token.js";
 import { warnOnce } from "../../warn.js";
 import { ENGINE_NAME_PATTERN_SOURCE } from "../engine-semantics.js";
 /** Persisted config schema version. Package prerelease/patch versions do not change this value. */
@@ -28,21 +29,26 @@ export const httpUrl = z.string().refine((v) => v.startsWith("http://") || v.sta
 });
 const ENGINE_NAME_PATTERN = new RegExp(ENGINE_NAME_PATTERN_SOURCE);
 export const ENV_REFERENCE_PATTERN = /^\$[A-Za-z_][A-Za-z0-9_]*$|^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/;
-/** `secret://<name>` — an apiKey reference into the akm secret store, resolved via `resolveSecretFromStore`. */
-export const SECRET_STORE_REFERENCE_PATTERN = /^secret:\/\/(.+)$/;
 export const engineName = z
     .string()
     .max(63)
     .regex(ENGINE_NAME_PATTERN, "names must be lowercase kebab-case and must not begin with reserved akm-");
-/** The two symbolic apiKey forms akm accepts: an env-var reference or a secret-store reference. Never matches a literal key. */
+/** The two symbolic credential forms akm accepts in config: an env-var reference (`$VAR`, `${VAR}`) or a `secrets/` ref (`${secrets/name}`). Never matches a literal key. */
 export function isApiKeyReference(value) {
-    return ENV_REFERENCE_PATTERN.test(value) || SECRET_STORE_REFERENCE_PATTERN.test(value);
+    return ENV_REFERENCE_PATTERN.test(value) || isSecretRefToken(value);
 }
 export function symbolicOrWarnApiKey(label) {
-    return z.string().superRefine((value) => {
+    return z.string().superRefine((value, ctx) => {
         if (isApiKeyReference(value))
             return;
-        warnOnce(`config:literal-api-key:${label}`, `A ${label} in config.json is a literal API key, not a $VAR/\${VAR}/secret:// reference; using it as configured. Prefer \`akm config set ...apiKey '$VAR'\` (with the corresponding env var set) or \`secret://<name>\` (with \`akm secret set <name> ...\`) — see docs/reference/data-and-telemetry.md.`);
+        if (isRefToken(value)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `a ${label} accepts only a \${secrets/<name>} ref (or a $VAR reference); "${value}" names another kind of asset`,
+            });
+            return;
+        }
+        warnOnce(`config:literal-api-key:${label}`, `A ${label} in config.json is a literal API key, not a $VAR/\${VAR} or \${secrets/<name>} reference; using it as configured. Prefer \`akm config set ...apiKey '$VAR'\` (with the corresponding env var set) or \`'\${secrets/<name>}'\` (with \`akm secret set secrets/<name> ...\`) — see docs/reference/data-and-telemetry.md.`);
     });
 }
 export const chatCompletionsEndpoint = z.string().superRefine((value, ctx) => {

package/dist/core/config/schema/sources-bundles.js

@@ -64,7 +64,7 @@ export const SourceConfigEntrySchema = z
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
             path: ["credential"],
-            message: "git credential must be a $VAR or secret://<name> reference",
+            message: "git credential must be a $VAR, ${VAR} or ${secrets/<name>} reference",
         });
     }
 });
@@ -178,7 +178,7 @@ export const BundleConfigEntrySchema = z
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
             path: ["credential"],
-            message: "git credential must be a $VAR or secret://<name> reference",
+            message: "git credential must be a $VAR, ${VAR} or ${secrets/<name>} reference",
         });
     }
     const componentEntries = entry.components ? Object.entries(entry.components) : [];

package/dist/core/env-secret-ref.js

@@ -13,11 +13,14 @@
  */
 import fs from "node:fs";
 import path from "node:path";
+import { resolveConceptOwner } from "../indexer/lookup/adapter-concept-owner.js";
 import { resolveSourceEntries } from "../indexer/search/search-source.js";
+import { isFileOrFileSymlink } from "../indexer/walk/walker.js";
 import { resolveSourcesForOrigin } from "../registry/origin-resolve.js";
 import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "./asset/asset-create.js";
 import { assetPathForName, deriveCanonicalAssetName } from "./asset/asset-placement.js";
-import { displayRef, isFullRefInput, parseRefInput } from "./asset/resolve-ref.js";
+import { makeBundleRef, parseBundleRef } from "./asset/asset-ref.js";
+import { conceptIdFromTypeName, displayRef, parseRefInput, typeNameFromConceptId } from "./asset/resolve-ref.js";
 import { isWithin } from "./common.js";
 import { loadConfig } from "./config/config.js";
 import { NotFoundError, UsageError } from "./errors.js";
@@ -51,7 +54,7 @@ export function listEnvsRecursive(listKeysFn, config = loadConfig()) {
                     walk(full);
                     continue;
                 }
-                if (!entry.isFile())
+                if (!entry.isFile() && !(entry.isSymbolicLink() && isFileOrFileSymlink(full)))
                     continue;
                 if (entry.name !== ".env" && !entry.name.endsWith(".env"))
                     continue;
@@ -71,33 +74,64 @@ export function listEnvsRecursive(listKeysFn, config = loadConfig()) {
     return result;
 }
 export function parseEnvRef(ref) {
-    // Accept a bare env name (`prod`, `sub/prod`) or the new-grammar
-    // `[bundle//]env/name` conceptId. A bare name's leading segment maps to no
-    // asset type, so it is qualified with the `env/` conceptId prefix; anything
-    // already a full new-grammar ref is parsed as-is.
-    return parseRefInput(isFullRefInput(ref) ? ref : `env/${ref}`);
+    return parseTypedRef(ref, "env", "env/<name>");
 }
-export function findEnvSource(origin, type, name) {
-    const sources = resolveSourceEntries(undefined, loadConfig());
-    if (sources.length === 0) {
-        throw new UsageError("No bundles configured. Run `akm bundle create` to create your working bundle.");
+/**
+ * Parse `ref` as a `[bundle//]conceptId` of the given asset type. There is no
+ * bare-name form: `prod` is a usage error that also names the ref it probably
+ * meant (`env/prod`), as text only — the suggestion is never resolved or accepted.
+ */
+function parseTypedRef(ref, type, form) {
+    let parsed;
+    try {
+        parsed = parseRefInput(ref);
     }
-    const candidates = origin ? resolveSourcesForOrigin(origin, sources) : sources;
-    const typeDir = type === "env" ? "env" : "secrets";
-    const member = candidates.find((source) => fs.existsSync(assetPathForName(type, path.join(source.path, typeDir), name)));
-    if (member)
-        return member;
-    if (!origin) {
-        const fallback = candidates[0];
-        if (fallback)
-            return fallback;
-        throw new UsageError("No bundles configured. Run `akm bundle create` to create your working bundle.");
+    catch (error) {
+        if (!(error instanceof NotFoundError))
+            throw error;
     }
-    const named = candidates[0];
-    if (!named) {
-        throw new NotFoundError(`Source not found for origin: ${origin}`);
+    if (parsed?.type !== type) {
+        const bare = parseBundleRef(ref);
+        const hint = typeNameFromConceptId(bare.conceptId) === undefined
+            ? ` Did you mean "${makeBundleRef(bare.bundle, conceptIdFromTypeName(type, bare.conceptId))}"?`
+            : "";
+        throw new UsageError(`Expected ${type === "env" ? "an" : "a"} ${type} ref (${form} or <bundle>//${form}); got "${ref}". Write the full ref.${hint}`, "INVALID_FLAG_VALUE");
+    }
+    return parsed;
+}
+/** The bundle and file that own an env or secret ref right now, or undefined. Sensitive files resolve too. */
+function findEnvSecretOwner(origin, conceptId) {
+    return resolveConceptOwner({ bundle: origin, conceptId }, resolveSourceEntries(undefined, loadConfig()), {
+        includeSensitive: true,
+    });
+}
+/**
+ * The file that owns any asset ref right now (the asset type its conceptId
+ * names, and the bundle-qualified spelling of the ref), or undefined when no
+ * bundle owns it. The lookup behind `${ref}` tokens.
+ */
+export function resolveRefOwner(ref) {
+    const { bundle, conceptId } = parseBundleRef(ref);
+    const match = findEnvSecretOwner(bundle, conceptId);
+    return (match && {
+        absPath: match.owner.path,
+        type: typeNameFromConceptId(conceptId)?.type,
+        ref: makeBundleRef(match.bundleId, conceptId),
+    });
+}
+/**
+ * Is `bundle` the id of an installed bundle in the active source set? The predicate `${ref}` substitution uses to
+ * tell a qualified ref from shell text. A source set that cannot be read (for example `AKM_BUNDLE_DIR` naming a
+ * disabled bundle) answers "not installed", so shell text never raises a config error; a real ref then fails where
+ * it is resolved, with that error.
+ */
+export function isInstalledBundle(bundle) {
+    try {
+        return resolveSourcesForOrigin(bundle, resolveSourceEntries(undefined, loadConfig())).length > 0;
+    }
+    catch {
+        return false;
     }
-    return named;
 }
 /**
  * `config` defaults to the real `loadConfig()`, same as {@link displayDefaultBundle}.
@@ -112,31 +146,28 @@ export function makeEnvRef(name, source, config = loadConfig()) {
     return displayRef({ type: "env", name, bundleId: source?.registryId }, displayDefaultBundle(source, config));
 }
 /**
- * Resolve an env ref to an absolute `.env` path. Accepts the `env/<name>`
- * conceptId (or a bare name, auto-qualified into it). The path is returned
- * even when the file does not yet exist (so `create` writes under `env/`).
+ * Resolve an env ref to the absolute `.env` path that owns it right now.
+ * Accepts a full `[bundle//]env/<name>` ref.
+ * Throws `NotFoundError` when no bundle owns it; creating one goes through
+ * {@link resolveEnvWriteTarget}.
  */
 export function resolveEnvPath(ref) {
     const parsed = parseEnvRef(ref);
-    if (parsed.type !== "env") {
-        throw new UsageError(`Expected an env ref (env/<name>); got "${ref}".`);
-    }
-    const source = findEnvSource(parsed.origin, "env", parsed.name);
-    const envRoot = path.join(source.path, "env");
-    const envPath = assetPathForName("env", envRoot, parsed.name);
-    // Defense-in-depth: ensure the resolved path stays inside the env directory.
-    // validateName already rejects traversal patterns like "../../foo", but an
-    // absolute-path override or symlink-based attack could still escape without
-    // this second check.
-    if (!isWithin(envPath, envRoot)) {
-        throw new UsageError(`Env name "${parsed.name}" escapes the env directory.`);
-    }
-    return { name: parsed.name, absPath: envPath, source, parsedRef: parsed, dir: "env" };
+    const conceptId = conceptIdFromTypeName("env", parsed.name);
+    const match = findEnvSecretOwner(parsed.origin, conceptId);
+    if (!match)
+        throw new NotFoundError(`Env not found: ${makeBundleRef(parsed.origin, conceptId)}`);
+    return {
+        name: parsed.name,
+        absPath: match.owner.path,
+        source: match.source,
+        bundleId: match.bundleId,
+        parsedRef: parsed,
+        dir: "env",
+    };
 }
 export function parseSecretRef(ref) {
-    // Same bare-name-vs-full-ref rule as parseEnvRef; a bare name is qualified
-    // with the `secrets/` conceptId prefix (secret's stash subdir).
-    return parseRefInput(isFullRefInput(ref) ? ref : `secrets/${ref}`);
+    return parseTypedRef(ref, "secret", "secrets/<name>");
 }
 export function makeSecretRef(name, source) {
     // F4b output-spelling flip: `secrets/name` in the primary stash,
@@ -149,39 +180,22 @@ function displayDefaultBundle(source, config = loadConfig()) {
     const primary = resolveSourceEntries(undefined, config)[0];
     return primary && path.resolve(primary.path) === path.resolve(source.path) ? source.registryId : undefined;
 }
-export function resolveSecretPath(ref, 
-// Create-only (`secret set`): enforce a flat ref name and apply `--path` as
-// the subdirectory. Lookup callers omit this so nested refs keep resolving.
-create) {
+export function resolveSecretPath(ref) {
     const parsed = parseSecretRef(ref);
-    if (parsed.type !== "secret") {
-        throw new UsageError(`Expected a secret ref (secrets/<name>); got "${ref}".`);
-    }
-    if (create) {
-        assertFlatAssetName(parsed.name);
-        parsed.name = combineCreatePath(normalizeCreateSubPath(create.subPath), parsed.name);
-    }
-    // Source resolution is identical for every asset type; reuse the env helper.
-    const source = findEnvSource(parsed.origin, "secret", parsed.name);
-    const typeRoot = path.join(source.path, "secrets");
-    const absPath = assetPathForName("secret", typeRoot, parsed.name);
-    // Defense-in-depth: ensure the resolved path stays inside the secrets dir.
-    if (!isWithin(absPath, typeRoot)) {
-        throw new UsageError(`Secret name "${parsed.name}" escapes the secrets directory.`);
-    }
-    return { name: parsed.name, absPath, source };
+    const conceptId = conceptIdFromTypeName("secret", parsed.name);
+    const match = findEnvSecretOwner(parsed.origin, conceptId);
+    if (!match)
+        throw new NotFoundError(`Secret not found: ${makeBundleRef(parsed.origin, conceptId)}`);
+    return { name: parsed.name, absPath: match.owner.path, source: match.source };
 }
 /**
  * Resolve the destination for an env mutation. Mirrors {@link resolveEnvPath}
  * but selects the source via {@link resolveWriteTarget} (writability-checked)
- * instead of the read-side {@link findEnvSource}. `create` enforces a flat ref
+ * instead of the read-side {@link resolveEnvPath}. `create` enforces a flat ref
  * name and applies `--path` as the subdirectory (matching `env create`).
  */
 export function resolveEnvWriteTarget(ref, writeTarget, create) {
     const parsed = parseEnvRef(ref);
-    if (parsed.type !== "env") {
-        throw new UsageError(`Expected an env ref (env/<name>); got "${ref}".`);
-    }
     if (create) {
         assertFlatAssetName(parsed.name);
         parsed.name = combineCreatePath(normalizeCreateSubPath(create.subPath), parsed.name);
@@ -199,13 +213,10 @@ export function resolveEnvWriteTarget(ref, writeTarget, create) {
  * Resolve the destination for a secret mutation. Mirrors
  * {@link resolveSecretPath} but selects the source via
  * {@link resolveWriteTarget} (writability-checked) instead of the read-side
- * {@link findEnvSource}.
+ * {@link resolveSecretPath}.
  */
 export function resolveSecretWriteTarget(ref, writeTarget, create) {
     const parsed = parseSecretRef(ref);
-    if (parsed.type !== "secret") {
-        throw new UsageError(`Expected a secret ref (secrets/<name>); got "${ref}".`);
-    }
     if (create) {
         assertFlatAssetName(parsed.name);
         parsed.name = combineCreatePath(normalizeCreateSubPath(create.subPath), parsed.name);

package/dist/core/errors.js

@@ -17,7 +17,7 @@ const CONFIG_HINTS = {
     UNSAFE_STASH_DIR: "Choose a path inside your home directory (e.g. ~/akm) or another empty workspace. The bundle directory cannot be the filesystem root, your home directory itself, or a sensitive system path like /etc, /var, ~/.config, or ~/.ssh.",
     UNKNOWN_IMPROVE_STRATEGY: "Pass one of the listed strategy names to `--strategy`, or define it under `improve.strategies`. Names are case-sensitive.",
     EXECUTION_NOT_AUTHORIZED: "Change the selected tools or update the machine/user execution policy, then retry.",
-    SECRET_REFERENCE_UNRESOLVED: "Check the secret exists (`akm secret list`) and the name after `secret://` matches, or run `akm secret set <name> <value>` to store it.",
+    SECRET_REFERENCE_UNRESOLVED: "Check the secret exists (`akm secret list`) and the ref inside `${…}` matches it, or run `akm secret set secrets/<name>` to store it.",
     REGISTRY_URL_INVALID: "Registry URLs must be credential-free http(s) URLs. Fix the entry with `akm registry list` / `akm registry add`, or the AKM_REGISTRY_URL / AKM_NPM_REGISTRY variable that supplied it.",
 };
 // Code-review finding: COMPOSITION_INVALID covers several unrelated causes