akm-cli 0.10.261012-beta → 0.10.261014-beta

package/dist/commands/command/command-cli.js

@@ -2,6 +2,7 @@
 // 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/.
 import { getStringArg, parsePositiveIntFlag } from "../../cli/parse-args.js";
+import { RETIRED_ENGINE_ARG, SELECTION_ARGS, selectionFromArgs } from "../../cli/selection.js";
 import { defineGroupCommand, defineJsonCommand, EXIT_CODES, output } from "../../cli/shared.js";
 import { loadConfig } from "../../core/config/config.js";
 import { isVerbose, setVerbose, warn, warnVerbose } from "../../core/warn.js";
@@ -30,8 +31,8 @@ export const commandRunCommand = defineJsonCommand({
             type: "string",
             description: "Override the command's agent selector with a portable agent ref or native harness selector",
         },
-        engine: { type: "string", description: "Override the selected execution engine" },
-        model: { type: "string", description: "Override the selected model alias or exact model identifier" },
+        ...SELECTION_ARGS,
+        ...RETIRED_ENGINE_ARG,
         "timeout-ms": { type: "string", description: "Override the execution timeout in milliseconds" },
         cwd: { type: "string", description: "Override the execution workspace/current working directory" },
         "dry-run": {
@@ -46,15 +47,10 @@ export const commandRunCommand = defineJsonCommand({
         const timeoutMs = parsePositiveIntFlag(exactStringArg(args, "timeout-ms"), "--timeout-ms");
         const current = {};
         const agent = getStringArg(args, "agent");
-        const engine = getStringArg(args, "engine");
-        const model = getStringArg(args, "model");
         const workspace = getStringArg(args, "cwd");
         if (agent !== undefined)
             current.agent = agent;
-        if (engine !== undefined)
-            current.engine = engine;
-        if (model !== undefined)
-            current.model = model;
+        Object.assign(current, selectionFromArgs(args));
         if (timeoutMs !== undefined)
             current.timeout = timeoutMs;
         if (workspace !== undefined)

package/dist/commands/command/command-execution.js

@@ -1,13 +1,14 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // 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/.
+import { SHIPPED_ALIAS } from "../../core/config/model-aliases.js";
 import { UsageError } from "../../core/errors.js";
+import { mergeNotices } from "../../execution/notices.js";
 import { createInlineResolvedCommand, createResolvedCommand, createResolvedPersona, } from "../../execution/resolved-request.js";
 import { isPortableExecutionAgentSelector, } from "../../execution/source.js";
 import { recordIndexedShowUsage } from "../../indexer/usage/show-usage.js";
 import { resolveUsageEventSource } from "../../indexer/usage/usage-events.js";
-import { fallbackAnnouncement } from "../../integrations/agent/engine-fallback.js";
-import { buildExecution, resolveExecution, } from "../../integrations/agent/execution.js";
+import { buildExecution, currentLayer, resolveExecution, shippedAlias, } from "../../integrations/agent/execution.js";
 import { runExecution } from "../../integrations/agent/runner-dispatch.js";
 import { parseBuiltinCommandAction } from "./builtin-action.js";
 import { loadAdapterExecutionSource, } from "./execution-source-loader.js";
@@ -106,18 +107,22 @@ export async function prepareCommandInvocation(options) {
         renderedPersona = rendered;
     }
     const persona = renderedPersona ? createResolvedPersona(renderedPersona) : selectedAgent.present ? null : undefined;
+    const layers = [
+        shippedAlias(SHIPPED_ALIAS.agent),
+        ...(renderedPersona
+            ? [{ id: renderedPersona.identity.ref, kind: "agent", values: renderedPersona.defaults }]
+            : []),
+        { id: renderedCommand?.identity.ref ?? "inline-command", kind: "command", values: commandDefaults },
+        ...(options.invocationDefaults
+            ? [{ id: "invocation-defaults", kind: "invocation-defaults", values: options.invocationDefaults }]
+            : []),
+        ...(options.current ? [currentLayer(options.current)] : []),
+    ];
     return resolveExecution({
         command,
         config: options.config,
         ...(persona !== undefined ? { persona } : {}),
-        ...(renderedPersona ? { agentLayer: { id: renderedPersona.identity.ref, values: renderedPersona.defaults } } : {}),
-        commandLayer: {
-            id: renderedCommand?.identity.ref ?? "inline-command",
-            values: commandDefaults,
-        },
-        ...(options.invocationDefaults ? { invocationDefaults: options.invocationDefaults } : {}),
-        ...(options.current ? { current: options.current } : {}),
-        ...(options.modelMap ? { modelMap: options.modelMap } : {}),
+        layers,
     });
 }
 function compareText(left, right) {
@@ -126,38 +131,27 @@ function compareText(left, right) {
 const DIAGNOSTIC_PROVENANCE_FIELDS = new Set([
     "/inference",
     "agent",
-    "authorization",
     "command",
-    "engine",
-    "engine.requested",
     "model",
     "outputSchema",
     "persona",
     "runtime.environment",
-    "runtime.settings",
     "runtime.timeoutMs",
     "runtime.workspace",
-    "tools",
+    "target",
 ]);
 const DIAGNOSTIC_NOTICE_FIELDS = new Set([
     "agent",
     "command.content",
-    "command.extensions",
     "conversation",
-    "engine",
-    "engine.extensions",
-    "extensions",
     "inference",
     "model",
     "outputSchema",
     "persona",
-    "persona.extensions",
     "runtime.environment",
-    "runtime.extensions",
-    "runtime.settings",
     "runtime.timeoutMs",
     "runtime.workspace",
-    "tools",
+    "target",
 ]);
 function canonicalDiagnosticProvenanceField(field) {
     if (field.startsWith("/inference/"))
@@ -219,20 +213,15 @@ function safeDiagnosticNotice(notice) {
                 severity: "info",
                 adapter: notice.adapter,
                 field: "persona",
-                message: "The selected engine has no native persona channel; AKM composed the persona into the prompt.",
+                message: "The selected harness has no native persona channel; AKM composed the persona into the prompt.",
             });
         default:
             return undefined;
     }
 }
 function diagnosticNotices(notices) {
-    const canonical = new Map();
-    for (const notice of notices) {
-        const safe = safeDiagnosticNotice(notice);
-        if (safe)
-            canonical.set(JSON.stringify(safe), safe);
-    }
-    return Object.freeze([...canonical.values()].sort((left, right) => compareText(JSON.stringify(left), JSON.stringify(right))));
+    const safe = notices.flatMap((notice) => safeDiagnosticNotice(notice) ?? []);
+    return Object.freeze([...(mergeNotices(safe) ?? [])].sort((left, right) => compareText(JSON.stringify(left), JSON.stringify(right))));
 }
 /**
  * Build a prepared invocation and project only safe structural diagnostics.
@@ -245,7 +234,7 @@ export function inspectPreparedCommandInvocation(prepared) {
         shape: "command-dry-run",
         ok: true,
         dryRun: true,
-        engine: prepared.request.engine.name,
+        engine: prepared.request.target.name,
         provenance: diagnosticProvenance(prepared.provenance),
         notices: diagnosticNotices(built.notices),
     };
@@ -270,22 +259,19 @@ function resultEnvelope(result, engine, warnings, notices) {
 export async function dispatchPreparedCommandInvocation(prepared, options = {}) {
     const { request } = prepared;
     const built = buildExecution(request, prepared.runner);
-    const selectedEngine = request.engine.name;
+    const selectedEngine = request.target.name;
     const result = await runExecution(built, runOptionsFor(options));
     const consumedRefs = new Set();
     if (request.command.source)
         consumedRefs.add(request.command.source.ref);
     if (request.persona)
         consumedRefs.add(request.persona.source.ref);
-    // F-1 (spec §5.2 point 3): options.eventSource is only a FALLBACK — an
-    // ambient AKM_EVENT_SOURCE still wins (D5 clause d). Absent, this is
-    // byte-identical to the pre-P1b bare resolveUsageEventSource() call (P-07's
-    // own default is "user").
+    // options.eventSource is only a FALLBACK — an ambient AKM_EVENT_SOURCE still
+    // wins. Absent, the default is "user".
     const eventSource = resolveUsageEventSource(process.env, options.eventSource ?? "user");
     for (const ref of consumedRefs)
         recordIndexedShowUsage(ref, eventSource);
-    const announcement = fallbackAnnouncement(prepared.fallbackEngineName, selectedEngine);
-    return resultEnvelope(result, selectedEngine, announcement ? [announcement] : [], built.notices);
+    return resultEnvelope(result, selectedEngine, [], built.notices);
 }
 export async function executeCommandInvocation(options, dispatchOptions = {}) {
     return dispatchPreparedCommandInvocation(await prepareCommandInvocation(options), dispatchOptions);

package/dist/commands/command/execution-source-loader.js

@@ -6,7 +6,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { adapterForId } from "../../core/adapter/registry.js";
 import { parseBundleRef } from "../../core/asset/asset-ref.js";
-import { isWithin } from "../../core/common.js";
+import { isContainedResolvedPath, isWithin } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
 import { bundleComponentConfig, bundlesToSourceEntries } from "../../core/config/config-sources.js";
 import { ConfigError, NotFoundError, UsageError } from "../../core/errors.js";
@@ -55,7 +55,7 @@ function isLexicallyWithin(candidate, root) {
     const relative = path.relative(path.resolve(root), path.resolve(candidate));
     return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
 }
-function implicitComponentForEntry(entry, config, realRoot) {
+function implicitComponentForEntry(entry, config) {
     const sources = resolveSourceEntries(undefined, config);
     const installations = deriveInstallations(sources);
     for (const [index, installation] of installations.entries()) {
@@ -66,9 +66,6 @@ function implicitComponentForEntry(entry, config, realRoot) {
         if (!source || !component)
             continue;
         const canonicalRoot = realDirectory(component.root, `Canonical implicit source root for ${entry.bundleId}`);
-        if (canonicalRoot !== realRoot) {
-            warnOnce(`execution-source-root-drift:${entry.itemRef}`, `[command] Indexed root for ${JSON.stringify(entry.itemRef)} no longer matches the working bundle source; re-resolving from live config. Run \`akm index --full\` to refresh it.`);
-        }
         if (component.adapter !== entry.adapterId) {
             warnOnce(`execution-source-adapter-drift:${entry.itemRef}`, `[command] Indexed adapter ${JSON.stringify(entry.adapterId)} for ${JSON.stringify(entry.itemRef)} no longer matches the working source's adapter ${JSON.stringify(component.adapter)}; re-resolving from live config. Run \`akm index --full\` to refresh it.`);
         }
@@ -84,7 +81,7 @@ function implicitComponentForEntry(entry, config, realRoot) {
 function componentForEntry(entry, config, realRoot) {
     const configured = config.bundles?.[entry.bundleId];
     if (!configured) {
-        const implicit = implicitComponentForEntry(entry, config, realRoot);
+        const implicit = implicitComponentForEntry(entry, config);
         if (implicit)
             return implicit;
         throw new ConfigError(`Indexed execution source ${JSON.stringify(entry.itemRef)} belongs to unconfigured bundle ${JSON.stringify(entry.bundleId)}.`, "INVALID_CONFIG_FILE", "Refresh the bundle configuration and rebuild the index before dispatching this asset.");
@@ -116,9 +113,6 @@ function componentForEntry(entry, config, realRoot) {
         if (!isWithin(configuredRoot, configuredSourceRoot)) {
             throw new ConfigError(`Configured component root for ${JSON.stringify(entry.itemRef)} resolves outside its materialized bundle source.`, "INVALID_CONFIG_FILE", "Remove the escaping symlink or component path, then run `akm index --full`.");
         }
-        if (configuredRoot !== realRoot) {
-            warnOnce(`execution-source-root-drift:${entry.itemRef}`, `[command] Indexed root for ${JSON.stringify(entry.itemRef)} no longer matches the ${JSON.stringify(configuredSource.type)} bundle source; re-resolving from live config. Run \`akm index --full\` to refresh it.`);
-        }
     }
     const writable = component?.writable ?? configured.writable ?? configured.path !== undefined;
     return Object.freeze({
@@ -131,8 +125,8 @@ function componentForEntry(entry, config, realRoot) {
 function expectedIndexedType(kind) {
     return kind === "command" ? "command" : "agent";
 }
-function assertRenderedIdentity(source, entry, realRoot, realFile, content) {
-    const expectedFile = path.relative(realRoot, realFile).replace(/\\/g, "/");
+function assertRenderedIdentity(source, entry, content) {
+    const expectedFile = path.relative(path.resolve(entry.stashDir), path.resolve(entry.filePath)).replace(/\\/g, "/");
     const expectedHash = createHash("sha256").update(content, "utf8").digest("hex");
     if (source.identity.ref !== entry.itemRef ||
         source.identity.bundle !== entry.bundleId ||
@@ -157,8 +151,10 @@ export async function loadAdapterExecutionSource(refInput, expectedKind, options
     }
     const config = await effectiveConfig(options.config);
     const realRoot = realDirectory(entry.stashDir, `Indexed component root for ${entry.itemRef}`);
-    const realFile = realRegularFile(entry.filePath, `Indexed execution source ${entry.itemRef}`);
-    if (!isWithin(realFile, realRoot) || realFile === realRoot) {
+    realRegularFile(entry.filePath, `Indexed execution source ${entry.itemRef}`);
+    // An index row must name a file inside its own component root. Checked on the
+    // authored path, so a file that is a symlink to one elsewhere still loads.
+    if (!isContainedResolvedPath(path.resolve(entry.filePath), path.resolve(entry.stashDir))) {
         throw new ConfigError(`Indexed execution source ${JSON.stringify(entry.itemRef)} resolves outside its component root.`, "INVALID_CONFIG_FILE", "Remove the escaping path and rebuild the index.");
     }
     const component = componentForEntry(entry, config, realRoot);
@@ -174,6 +170,6 @@ export async function loadAdapterExecutionSource(refInput, expectedKind, options
     if (!rendered || rendered.kind !== expectedKind) {
         throw new ConfigError(`Bundle adapter ${JSON.stringify(entry.adapterId)} did not render ${JSON.stringify(entry.itemRef)} as a ${expectedKind}.`, "INVALID_CONFIG_FILE", "Rebuild the index; if the mismatch remains, repair the source file or owning adapter.");
     }
-    assertRenderedIdentity(rendered, entry, realRoot, realFile, fileContext.content());
+    assertRenderedIdentity(rendered, entry, fileContext.content());
     return rendered;
 }

package/dist/commands/completions.js

@@ -58,7 +58,7 @@ function walkCommandTree(cmd, parentPath = "") {
     const valueFlags = [];
     if (cmd.args) {
         for (const [flagName, arg] of Object.entries(cmd.args)) {
-            if (arg.type === "positional")
+            if (arg.type === "positional" || arg.hidden === true)
                 continue;
             flags.push(`--${flagName}`);
             if (arg.type === "boolean" && arg.default === true)

package/dist/commands/config-cli.js

@@ -9,14 +9,15 @@
  * zero lines here — the walker handles get/set/unset/coercion uniformly.
  *
  * `configVersion` is controlled by the config lifecycle. All execution
- * settings use their canonical engine/strategy paths; retired aliases are not
+ * settings use their canonical connection, harness and strategy paths; retired aliases are not
  * rewritten at this boundary.
  */
 import { isDeepStrictEqual } from "node:util";
 import { defineGroupCommand, defineJsonCommand, output } from "../cli/shared.js";
 import { isRecord } from "../core/common.js";
-import { DEFAULT_CONFIG, getConfigValueSource, loadConfig, mutateConfig, parseAndValidateConfigText, resolveConfigRefSource, } from "../core/config/config.js";
+import { DEFAULT_CONFIG, getConfigValueSource, loadConfig, mutateConfig, parseAndValidateConfigText, resolveConfigRefSource, unusableEntryAt, } from "../core/config/config.js";
 import { configGet, configSet, configUnset, unknownKeyHint } from "../core/config/config-walker.js";
+import { isEnvReference } from "../core/config/schema/primitives.js";
 import { UsageError } from "../core/errors.js";
 import { getConfigPath } from "../core/paths.js";
 import { formatRegistryUrl } from "../core/registry-url.js";
@@ -31,11 +32,13 @@ export function unsetConfigValue(config, key) {
     return configUnset(config, key);
 }
 export function listConfig(config) {
-    // 0.9.0 (spec §10.1): sources live in `bundles` (spread from config); the
+    // Sources live in `bundles` (spread from config); the
     // retired top-level `sources[]` array is no longer surfaced.
     return redactConfigValue({ ...DEFAULT_CONFIG, ...config });
 }
 function redactConfigValue(value, path = []) {
+    if (path.at(-1) === "apiKey" && typeof value === "string" && !isEnvReference(value))
+        return undefined;
     if (typeof value === "string" && isRegistryUrlPath(path))
         return formatRegistryUrl(value);
     if (Array.isArray(value))
@@ -44,8 +47,7 @@ function redactConfigValue(value, path = []) {
         return value;
     const result = {};
     for (const [key, child] of Object.entries(value)) {
-        if (key !== "apiKey" ||
-            (typeof child === "string" && /^\$(?:[A-Za-z_][A-Za-z0-9_]*|\{[A-Za-z_][A-Za-z0-9_]*\})$/.test(child))) {
+        if (key !== "apiKey" || (typeof child === "string" && isEnvReference(child))) {
             result[key] = redactConfigValue(child, [...path, key]);
         }
     }
@@ -195,6 +197,13 @@ export const configCommand = defineGroupCommand({
                 if (source.startsWith("extends:")) {
                     throw new UsageError(`Config key "${args.key}" is inherited from ${source} and cannot be unset here.`, "TARGET_NOT_UPDATABLE", `Override it locally with "akm config set ${args.key} <value>", or edit the base file directly.`);
                 }
+                // An entry the reader drops is not in the config `unsetConfigValue` sees, so it would no-op and say ok.
+                const ignored = unusableEntryAt(args.key);
+                if (ignored) {
+                    throw new UsageError(`Config key "${args.key}" is inside ${ignored.kind} "${ignored.name}", which akm ignores (${ignored.why}), so \`akm config\` cannot edit it.`, "TARGET_NOT_UPDATABLE", ignored.inFile
+                        ? `Remove or fix the ${ignored.group}.${ignored.name} entry in ${getConfigPath()} by hand.`
+                        : `${getConfigPath()} is still in the retired engines form: run \`akm migrate apply\` first, then fix or remove the entry.`);
+                }
                 const result = mutateConfig((current) => unsetConfigValue(current, args.key), { absentNoop: true });
                 const updated = result.config;
                 if (!args.silent) {

package/dist/commands/env/child-env.js

@@ -1,7 +1,10 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // 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/.
-import { WIN32_SPAWN_ENV_FLOOR } from "../../core/spawn-env.js";
+/**
+ * What `env run --clean` / `secret run --clean` keeps of the parent environment. The user typed
+ * the flag to get a minimal one; without the last eight names Windows cannot create the process.
+ */
 const CLEAN_ENV_ALLOWLIST = [
     "HOME",
     "PATH",
@@ -31,6 +34,14 @@ const CLEAN_ENV_ALLOWLIST = [
     "TZ",
     "NO_COLOR",
     "COLORTERM",
+    "SystemRoot",
+    "SystemDrive",
+    "WINDIR",
+    "COMSPEC",
+    "PATHEXT",
+    "USERPROFILE",
+    "HOMEDRIVE",
+    "HOMEPATH",
 ];
 export function buildChildEnv(parentEnv, options) {
     const base = options.clean ? {} : { ...parentEnv };
@@ -39,19 +50,6 @@ export function buildChildEnv(parentEnv, options) {
             if (parentEnv[key] !== undefined)
                 base[key] = parentEnv[key];
         }
-        // The allowlist above is POSIX-shaped. On Windows a child started without
-        // SystemRoot/COMSPEC/PATHEXT and friends frequently cannot start at all —
-        // which is why every other spawn path in the codebase applies this floor
-        // (see spawnEnvNamesFor). `env run --clean` / `secret run --clean` did not,
-        // so clean-mode injection was unusable there. The floor is names the OS
-        // requires of any child, not user configuration, so it does not weaken what
-        // "clean" means about inherited secrets.
-        if (process.platform === "win32") {
-            for (const key of WIN32_SPAWN_ENV_FLOOR) {
-                if (parentEnv[key] !== undefined)
-                    base[key] = parentEnv[key];
-            }
-        }
     }
     for (const key of options.inherit) {
         if (parentEnv[key] !== undefined)

package/dist/commands/env/env-binding.js

@@ -9,37 +9,43 @@
  * REUSES the exact same machinery instead of forking it. Every safety
  * invariant carries over unchanged:
  *
- *   - `${secret:NAME}` tokens resolve against the env's own stash; a missing
- *     secret is a hard error and NOTHING is injected (no partial injection).
- *   - Known process-hijacking keys (LD_PRELOAD, PATH, …) are blocked for
- *     third-party-sourced stashes and warned about for first-party ones.
+ *   - `${ref}` tokens resolve through the one ref walk (a `secrets/` ref to the
+ *     secret's trimmed value, any other asset ref to its absolute path); a
+ *     missing ref is a hard error and NOTHING is injected (no partial injection).
  *   - An `env_access` audit event records key NAMES only, never values.
  *   - Resolved values must never be written to stdout or logs by callers.
  */
-import fs from "node:fs";
-import path from "node:path";
-import { decideDangerousEnvInjection } from "../../core/activation-policy.js";
-import { assetPathForName } from "../../core/asset/asset-placement.js";
-import { isWithin } from "../../core/common.js";
-import { makeEnvRef, makeSecretRef, resolveEnvPath } from "../../core/env-secret-ref.js";
+import { isInstalledBundle, makeEnvRef, resolveEnvPath, resolveRefOwner } from "../../core/env-secret-ref.js";
 import { NotFoundError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
-import { isDangerousEnvKey } from "../lint/env-key-rules.js";
-import { loadEnv, resolveSecretTokens } from "./env.js";
-import { readValue } from "./secret.js";
+import { substituteRefTokens } from "../../core/ref-token.js";
+import { readValue } from "../../core/secret-value.js";
+import { warnOnce } from "../../core/warn.js";
+import { loadEnv } from "./env.js";
+/** The retired `${secret:NAME}` env-value token (see `resolveEnvBinding`). */
+const LEGACY_SECRET_TOKEN_RE = /\$\{secret:([^}\s]+)\}/g;
+/**
+ * What a `${ref}` token stands for: a `secrets/` ref yields the secret's
+ * trimmed value, any other asset ref its absolute path, a ref no bundle owns
+ * `undefined`. The one resolver behind env values and exec argv.
+ */
+export function resolveRefToken(ref) {
+    const owner = resolveRefOwner(ref);
+    if (owner === undefined)
+        return undefined;
+    return owner.type === "secret"
+        ? { kind: "secret", value: readValue(owner.absPath) }
+        : { kind: "path", path: owner.absPath };
+}
 /**
  * Resolve an env ref to its injectable values: load the file, apply key
- * filtering, substitute `${secret:NAME}` tokens from the sibling secrets
- * directory, enforce the dangerous-key policy, and append the keys-only
+ * filtering, substitute `${ref}` tokens, and append the keys-only
  * `env_access` audit event.
  */
 export function resolveEnvBinding(target, options = {}) {
     const warn = options.warn ?? ((message) => process.stderr.write(`warning: ${message}\n`));
-    const { name, absPath, source } = resolveEnvPath(target);
+    const { name, absPath, source, bundleId } = resolveEnvPath(target);
     const envRef = makeEnvRef(name, source);
-    if (!fs.existsSync(absPath)) {
-        throw new NotFoundError(`Env not found: ${envRef}`);
-    }
     const allValues = loadEnv(absPath);
     // Value-safe key filtering (--only / --except operate on key NAMES only).
     let envValues = allValues;
@@ -58,49 +64,32 @@ export function resolveEnvBinding(target, options = {}) {
         const excluded = new Set(options.except);
         envValues = Object.fromEntries(Object.entries(allValues).filter(([k]) => !excluded.has(k)));
     }
-    // Substitute `${secret:NAME}` tokens with the sibling secret asset in the
-    // SAME stash. A missing secret is a hard error — inject NOTHING.
-    const secretsRoot = path.join(source.path, "secrets");
-    const resolveSecret = (secretName) => {
-        const secretPath = assetPathForName("secret", secretsRoot, secretName);
-        // Defense-in-depth: ensure the resolved path stays inside the secrets dir.
-        if (!isWithin(secretPath, secretsRoot)) {
-            throw new UsageError(`Secret name "${secretName}" escapes the secrets directory.`);
-        }
-        if (!fs.existsSync(secretPath))
-            return undefined;
-        // Match `secret run`: read utf8, do not trim (stay consistent with that path).
-        return readValue(secretPath).toString("utf8");
-    };
-    const { values: substituted, missing } = resolveSecretTokens(envValues, resolveSecret);
+    // Read-compat: env files written for 0.9 / early 0.10 spell a secret
+    // `${secret:NAME}`, meaning `secrets/NAME` in this env asset's own bundle.
+    // Read it as the `${ref}` it stands for; the file is bundle content and is
+    // never rewritten.
+    let firstLegacy;
+    envValues = Object.fromEntries(Object.entries(envValues).map(([key, value]) => [
+        key,
+        value.replace(LEGACY_SECRET_TOKEN_RE, (_token, secretName) => {
+            const spelling = `\${${bundleId}//secrets/${secretName}}`;
+            firstLegacy ??= spelling;
+            return spelling;
+        }),
+    ]));
+    if (firstLegacy !== undefined) {
+        warnOnce(`legacy-secret-token:${envRef}`, `Env "${envRef}" uses the retired \${secret:NAME} spelling; reading it as ${firstLegacy}. Write the full ref in the env file.`);
+    }
+    // Substitute `${ref}` tokens. A missing ref is a hard error — inject NOTHING.
+    const { values: substituted, missing, secretValues, } = substituteRefTokens(envValues, resolveRefToken, isInstalledBundle);
     if (missing.length > 0) {
-        throw new NotFoundError(`Env "${envRef}" references secret(s) not found in its stash: ${missing.map((n) => makeSecretRef(n)).join(", ")}. Nothing was injected.`, "FILE_NOT_FOUND", `Create the missing secret, e.g. \`akm secret set ${makeSecretRef(missing[0])}\`.`);
+        throw new NotFoundError(`Env "${envRef}" references asset(s) that no bundle owns: ${missing.join(", ")}. Nothing was injected.`, "FILE_NOT_FOUND", 
+        // biome-ignore lint/suspicious/noTemplateCurlyInString: literal `${ref}` token syntax documented for users, not interpolation
+        "Write each `${ref}` as a full akm ref that exists, e.g. `${secrets/name}` or `${team//scripts/run.sh}`.");
     }
     envValues = substituted;
     const keys = Object.keys(envValues);
-    // Scan injected keys for known process-hijacking variables. The workspace
-    // activation policy decides block (third-party, registryId set) vs. warn
-    // (first-party stash, where the operator owns the file).
-    const dangerous = keys.filter(isDangerousEnvKey);
-    if (dangerous.length > 0) {
-        const detail = `Env "${envRef}" injects process-hijacking variable(s): ${dangerous.join(", ")}.`;
-        const decision = decideDangerousEnvInjection({
-            dangerousKeys: dangerous,
-            thirdParty: Boolean(source.registryId),
-            allowDangerousEnvKeys: options.allowDangerousEnvKeys,
-        });
-        if (decision === "block") {
-            throw new UsageError(`Refusing to inject env from a third-party stash. ${detail}\n` +
-                `       Review the file, then copy the values into a first-party env if you trust them, ` +
-                `or pass --allow-dangerous-env-keys once you have.`, "INVALID_FLAG_VALUE");
-        }
-        if (decision === "warn") {
-            warn(options.allowDangerousEnvKeys && source.registryId
-                ? `${detail} Injecting anyway (--allow-dangerous-env-keys).`
-                : `${detail} Injecting anyway (first-party stash).`);
-        }
-    }
     // Audit trail: keys only, never values.
     appendEvent({ eventType: "env_access", ref: envRef, metadata: { keys } });
-    return { ref: envRef, values: envValues, keys };
+    return { ref: envRef, values: envValues, keys, secretValues };
 }