akm-cli 0.10.261011-beta → 0.10.261013-beta

package/CHANGELOG.md

@@ -6,6 +6,244 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.10.261013] - 2026-10-23
+
+### Fixed
+
+- A secret is now also redacted when it appears in its JSON-escaped spelling
+  (#1238). Text redaction matched only the exact and URL-encoded forms, so a child
+  that printed `JSON.stringify({ token })` for a secret with a quote, backslash,
+  newline or non-ASCII character left it in the unit journal when the output failed
+  its schema, had no schema, or came with a non-zero exit. The shared redactor now
+  also matches the `\"`, `\\`, `\n` and `\uXXXX` forms (lowercase or uppercase
+  hex, DEL included), for workflow, engine and task-output redaction alike.
+- `akm bundle rename` now rewrites the refs of a bundle whose id contains an
+  emoji or other character outside the Basic Multilingual Plane correctly
+  (#1239). It used to cut into the `//` separator, storing `team/workflows/x`
+  for `💼//workflows/x` and stranding the bundle's workflow runs, task history
+  and proposals.
+- A task's `uses:` script or workflow in an npm, website or read-only bundle now
+  resolves (#1238). It used to fail with "unsupported kind for writes", because
+  the lookup went through the write-target resolver. An unknown bundle in such a
+  ref is reported as not configured, without naming a flag.
+- `akm bundle update` no longer re-clones a git or npm bundle whose upstream
+  revision has not changed. Re-cloning replaced the bundle's directory under any
+  running task or workflow, and left an empty revision directory behind after
+  each real change. An unchanged bundle is now reported as unchanged and left
+  alone (`--force` still fetches it again). After a real change, the previous
+  revision is kept and older revision directories are removed (#1235).
+- Scheduled tasks in the `AKM_BUNDLE_DIR` working stash were silently dropped by
+  an unscoped `akm task sync` (and `--rebind`) once any other bundle was
+  configured (#1236). Task sync now uses the same set of active bundles as
+  search, show and workflows, so the working stash is synced the same way
+  whether you sync everything or name it with `--bundle`.
+- A `bundle update` while a workflow is running no longer fails the run (#1238,
+  #1235). A running workflow used to remember the directory it was started in, so
+  once the update moved the bundle to a new revision directory, the next step
+  failed with `PATH_ESCAPE_VIOLATION` and the only remedy was `abandon`. The
+  run now finds its bundle again at each step and carries on from the new
+  directory. It continues from its frozen plan even if the new revision renamed
+  or removed the workflow file, and a step fails only when the run's bundle is
+  no longer configured.
+- `exec.cwd` is applied once (#1238). `cwd: sub` used to run in `<bundle>/sub/sub`.
+  It now runs in `<bundle>/sub`.
+
+### Changed
+
+- `akm workflow plan --format text` now shows each step's argv, cwd and env refs,
+  and the bundle-qualified ref that every `${ref}` token, `env:` entry and child
+  `workflow:` resolves to; a ref no bundle owns, in the workflow or in a child
+  workflow it runs, fails the plan and names it.
+  `akm workflow status <id> --units` shows the same argv, cwd and resolved refs
+  for a failed unit (#1238).
+- A workflow exec step's command now receives `AKM_CONFIG_DIR`, `AKM_DATA_DIR`,
+  `AKM_CACHE_DIR` and `AKM_STATE_DIR` set to the directories the akm that started
+  it resolved, including ones it found through `XDG_*_HOME`, and `AKM_BUNDLE_DIR`
+  when it had one. A step that runs `akm` uses the same bundle and state without
+  `pass_env` (#1238).
+- `akm env`, `akm secret`, workflow `env:` bindings and child workflows, task
+  `uses:` assets, and `improve`/`distill`/schema-repair file lookups now find an
+  asset with the same lookup `akm show` uses, instead of each keeping its own
+  copy of it (#1238). The visible differences: a missing child workflow fails
+  with the ordinary "Workflow not found" error, an env ref in a workflow does
+  not resolve into a disabled bundle, and `improve` finds a concept in a
+  bundle whose adapter names the file (such as an OKF table) from disk as well
+  as from the index.
+- An asset is addressed by its akm ref and nothing else (#1238). `akm secret
+  set|run` and `akm env create|run|path|export|remove` now take a full ref
+  (`secrets/gitea_token`, `team//env/prod`); a bare name such as `gitea_token`
+  or `prod` is a usage error that names the full form. `akm env create prod` is
+  now `akm env create env/prod`.
+- One substitution token, `${ref}`, replaces `${secret:NAME}` in env values and
+  `secret://name` in config credentials (#1238). A `${secrets/name}` token is
+  replaced with the secret's value and any other asset ref, such as
+  `${scripts/lab/fetch.sh}`, with its absolute path; the ref may name any bundle
+  (`${team//secrets/discord_bot_token}`) rather than only the env file's own
+  bundle. A ref into a bundle of any adapter works when it is qualified and the
+  bundle is installed (`${docs//tables/customers}` in an OKF bundle). A `${...}`
+  body that is not an akm ref, such as `${HOME}` or shell substitution like
+  `${v//-/_}`, is left as text. `engines.*.apiKey`, `embedding.apiKey`,
+  `search.curateRerank.apiKey` and a git bundle's `credential` accept `$VAR`,
+  `${VAR}` or `${secrets/<name>}` (in any bundle, such as `${team//secrets/x}`); a
+  `${...}` naming any other kind of asset, such as `${scripts/x}`, is rejected
+  when the config loads. An env file that still holds `${secret:NAME}` keeps
+  working: akm reads it as `${<the env file's bundle>//secrets/NAME}` and warns
+  once, naming the env ref. The file is not rewritten, so write the full ref.
+- A workflow unit's `env:` bindings are now read at dispatch with the same
+  function `akm env run` uses, so a bundle's env asset, its `${ref}` tokens and
+  the secrets they name behave the same in a workflow as on the command line
+  (#1238). An edit to an env file after a run started is picked up by the next
+  dispatch instead of failing with "key set changed".
+- Only secret values are redacted from workflow output (#1238). A value
+  substituted from a `secrets/` ref is still `[REDACTED]` in stdout, stderr,
+  diagnostics and the journal, but the rest of an env asset, such as a URL or a
+  channel id, now reaches the journal and the next step intact. A credential
+  typed straight into an env file is no longer redacted; keep credentials in
+  `secrets/`.
+- A secret's value is read the same way everywhere (#1238): the file content with
+  surrounding whitespace trimmed. `akm secret run` and env tokens used to pass
+  the raw bytes, trailing newline included, while config credentials and the
+  website fetchers trimmed.
+- Installing a bundle is now the trust decision (#1237). A bundle whose `env/`
+  files set a key such as `PATH` installs, updates unattended, and works in
+  `akm env run`, `akm secret run` and workflow `env:` bindings with no flag, no
+  prompt and no block, whichever bundle it comes from. `akm lint` still reports
+  `dangerous-env-key` findings, non-blocking.
+- An agent's own `tools` list is now honoured for an agent in any bundle, not
+  only the primary stash. `execution.allowedTools` still caps what a run grants.
+- A task `env:` value that looks like a credential is now a warning, in the same
+  style workflow params give, instead of an error that stopped the task. The
+  warning points to `akm secret run` or `akm env run` in the task's `run:`.
+- `--allow-dangerous-env-keys` on `bundle add`, `bundle update` and `env run` is
+  now a deprecated no-op, accepted through 0.10 so existing scripts keep working.
+  It is an unknown flag from 0.11.
+- Reads follow symlinks (#1237). An env file or secret that is a symlink to a
+  file outside its bundle directory now resolves through `akm env`, `akm secret`,
+  `${ref}` substitution and a workflow `env:` binding, and a ref
+  resolved by path does the same, instead of failing with "escapes the secrets
+  directory" or "Ref resolves outside the stash root", so a secret can point at
+  a container's `/run/secrets/<name>`. A command, agent or script that is such a
+  symlink also resolves when a workflow, task or `akm agent` runs it, and
+  `akm index` indexes a file symlink like any other file, so `akm show` and
+  search find it, and `akm env list` and `akm secret list` list it. A symlinked
+  script runs under the interpreter its own name selects, and cloning a skill
+  copies a symlinked file by content. A directory symlink is still never
+  descended. Names with `..`
+  segments or absolute names are still refused, and writes still never follow a
+  symlink out of the bundle.
+- `akm workflow run <ref>` always starts a new run, and `akm workflow run <run-id>`
+  continues one (#1239). `akm workflow resume <run-id>` only re-activates a blocked
+  or failed run so `run <run-id>` can continue it. Before, running a ref
+  silently resumed any active run of that ref started from the same directory,
+  which is why scripts passed `--new` and why a scheduled task and a shell could
+  each start their own run. Now, when other runs of the ref are still active, the
+  start prints one warning naming their ids and the `akm workflow run <id>` /
+  `akm workflow abandon <id>` commands, and starts anyway. Parameters are accepted
+  on every ref start, and `--new` is accepted and does nothing (deprecated,
+  through 0.10).
+- Workflow runs are no longer tied to the directory you run from (#1239).
+  `akm workflow list` and `akm workflow status <ref>` show every run on the host,
+  most recently updated first, from any directory, so the runs of a scheduled
+  task are listed like any other. `--all-scopes` is accepted and does nothing
+  (deprecated, through 0.10), and the `list` result no longer carries a
+  `scopeKey`. Runs started by 0.10 are not visible to a 0.9.15 binary reading the
+  same `state.db`.
+- `akm workflow run <ref> --skip-if-locked` also skips (exit 0, nothing started)
+  when an active run of that ref is being driven by a live process (#1239). Without
+  the flag a start is never refused.
+- `akm bundle rename` rewrites the workflow ref on that bundle's workflow runs, so
+  `akm workflow list` shows the old runs under the new name, and lists the bundle's
+  active and blocked runs in its output, each with its status (#1239). Their frozen
+  plans keep the old refs; continue or abandon them.
+- `akm workflow create` no longer indexes the new workflow, and a new run no longer
+  records an index entry id (#1239).
+- A workflow plan records the refs it uses and no locations (#1238). New runs
+  freeze plan `irVersion` 7, which holds no bundle directory, no directory
+  identity and, for each `env:` ref, only its bundle-qualified ref: the env
+  file, its keys and the secrets it names are read at each step. Runs frozen
+  by earlier releases (`irVersion` 5 and 6) carry those fields, which are never
+  read but are kept as stored, so a run interrupted before the upgrade finds the
+  child workflow run it had already started instead of starting a second one, and
+  continues the same way. A plan frozen by a newer akm is refused with a message
+  that says to upgrade akm, whether or not this akm could decode it. A plan with an
+  agent step records an empty directory identity, so a 0.10 pre-release that finds
+  the run stops at that step instead of running the agent in the wrong directory.
+  `akm workflow plan` lists an env ref without its `keys` and `secretNames`.
+- A workflow's exec units, agents and gate judges work in the root of the bundle
+  that holds the workflow, found at each step, and `exec.cwd` is joined onto it (#1238).
+  `exec.cwd` may now be absolute, and it is no longer required to stay inside the
+  bundle: a command can reach any directory anyway. A step whose workflow no
+  longer resolves to a bundle fails naming the workflow (a step with a gate is
+  blocked by its judge first, for `akm workflow resume`) instead of running in
+  akm's own working directory.
+- An exec step's argv and `exec.cwd` can name an asset in any bundle with the same
+  `${ref}` token env assets use (#1238): `["bun", "${homelab//scripts/lab-status/fetch.ts}"]`.
+  A `secrets/` ref is replaced by the secret's value, which is redacted from the
+  unit's output after it is parsed, like a secret bound through an env asset; any
+  other asset ref by its absolute path. A ref no bundle owns
+  fails the unit, naming it, before anything is spawned. Prompts are not
+  substituted. A workflow in bundle A can now run a script from bundle B with an
+  env asset from bundle C that names a secret in bundle D.
+- A task no longer captures its working directory's identity when it is prepared
+  and re-checks it before it runs (#1238). A `run:` task runs in
+  `<bundle>/<working-directory>`, and a `uses: scripts/<file>` target that is a
+  symlink to a file outside the bundle works: the task freezes that file's
+  bytes.
+- A task's `working-directory` follows the same rule as a workflow's `exec.cwd`
+  (#1238): a non-empty path, relative to the task's bundle root or absolute, and
+  no longer required to stay inside the bundle. A symlink to a directory outside
+  the bundle, an absolute path and a path with `..` all work, and `akm lint` and
+  `akm task sync` no longer need the bundle root to check it.
+
+### Deprecated
+
+- `secret://name` in config is retired in favour of `${secrets/name}` (#1238). A
+  config that still holds it loads as if it said `${secrets/name}`, with one
+  warning naming the key, and `akm migrate apply` rewrites `config.json`.
+  `akm config set` and `bundle add --credential` no longer accept it. A workflow run
+  frozen before the upgrade keeps resolving its engine credential when it is
+  continued, and keeps the `secret://` text it stored.
+
+### Removed
+
+- The dangerous-key audit on `bundle add` and `bundle update`, its prompt, its
+  rollback of a freshly installed bundle, and the `blocked` per-bundle status in
+  `bundle update --all`. The `DANGEROUS_ENV_KEY` and `DANGEROUS_ENV_AUDIT_FAILED`
+  error codes are gone with them (#1237).
+- The first-party and third-party distinction for env and secret injection
+  (`src/core/activation-policy.ts`) and the unused `trusted` field on a derived
+  bundle installation (#1237).
+- `akm show` no longer reports an `activeRun` field. Run state is under
+  `akm workflow` (#1239).
+- The "indexed root no longer matches the bundle source" warnings when a command
+  or persona is dispatched (#1238). A bundle at a different location than the
+  index recorded is no longer reported as drift.
+- The `exec_cwd_escape` failure reason and the checks behind it: the parser, the
+  compiler and the exec runner no longer reject an `exec.cwd` that leaves the
+  workflow's bundle (#1238).
+
+## [0.10.261012] - 2026-10-22
+
+### Changed
+
+- Distill writes more useful lessons without writing wrong ones. The lesson
+  writer treats a tested or measured result about a change or method, stated
+  with the conditions and limits it held under, as a lesson. It answers NONE for
+  a dated status, for the report of one run or day whose cause is only suspected
+  with no fix verified, and for a recap or reminder list whose rules a related
+  asset already states. Lessons are shorter (about half the memory), in the
+  writer's own words, and keep the memory's numbers, names and terms. The lesson
+  judge's REUSABLE criterion credits such a tested result and scores a lesson
+  drawn from an unconfirmed one-run report as not reusable; judging an update
+  to an existing lesson keeps the original criterion.
+
+### Fixed
+
+- A SIGINT or SIGTERM that reached akm just after it started an agent or harness
+  in its own process group could end akm with that group still running (#1230).
+  The signal guard is now in place before the child is spawned, so the group is
+  always terminated with akm.
+
 ## [0.10.261011] - 2026-10-22
 
 ### Changed

package/SECURITY.md

@@ -75,8 +75,8 @@ The built-in YouTube snapshot fetcher (`src/sources/snapshot-fetchers/youtube.ts
 and `<stash>/secrets/`. They are protected against other local users by
 filesystem permissions but are not encrypted at rest. Do not commit these
 files to source control. Normal `akm env` and `akm secret` output never echoes
-values; materialize values only at the command boundary with `akm env run`,
-`akm secret run`, or `akm secret path`.
+values; materialize values only at the command boundary with `akm env run`
+or `akm secret run`.
 
 The knowledge graph extracted from your assets (entities/relations) lives
 only in `$DATA/index.db` and is surfaced as aggregate counts via `akm health`

package/STABILITY.md

@@ -100,9 +100,9 @@ enumeration of the whole `proposal` noun group.
 | `akm search` | Stable | |
 | `akm curate` | Stable | |
 | `akm show` | Stable | |
-| `akm workflow status` | Experimental | `--all-scopes` added in 0.9.15 (#942), additive. |
+| `akm workflow status` | Experimental | `--all-scopes` added in 0.9.15 (#942); a deprecated no-op since 0.10 (#1239), accepted through 0.10. |
 | `akm workflow plan` | Experimental | New in 0.9.2; secret-free provenance output; envelope shape may change. |
-| `akm workflow list` | Experimental | `--all-scopes` and a top-level `scopeKey` envelope field added in 0.9.15 (#942), both additive. |
+| `akm workflow list` | Experimental | `--all-scopes` and a top-level `scopeKey` envelope field added in 0.9.15 (#942); since 0.10 (#1239) `--all-scopes` is a deprecated no-op, accepted through 0.10, and the `scopeKey` field is removed from the list result. |
 | `akm workflow create` | Experimental | |
 | `akm workflow resume` | Experimental | |
 | `akm workflow abandon` | Experimental | |

package/dist/assets/hints/cli-hints-full.md

@@ -92,7 +92,7 @@ akm import https://example.com/docs/auth       # Fetch one URL and import it as
 akm import ./doc.md --bundle my-other-bundle    # Route import to a named writable bundle source
 akm workflow create ship-release               # Create a workflow asset in the bundle
 akm lint --type workflows                      # Parse and compile every workflow source; list every error
-akm workflow run workflows/ship-release        # Start or resume and execute the workflow
+akm workflow run workflows/ship-release        # Start a new run and execute it
 akm feedback skills/code-review --positive     # Record that an asset helped (ranks it higher; no rewrite)
 akm feedback agents/reviewer --negative --reason "says to run jest; the suite runs on vitest" # Content wrong or stale: lowers its ranking; improve may repair its frontmatter
 akm feedback knowledge/opencode-server --negative --reason "the default port is 4096, not 8000" --replace "port 8000" --with "port 4096" --source "https://opencode.ai/docs/server/" # Apply an exact fix
@@ -150,8 +150,8 @@ the index (comments can contain commented-out credentials). akm does not edit
 entries — you edit the file with your own editor and akm loads it.
 
 ```sh
-akm env create prod                           # Create an empty env file
-akm env create prod --from-file ./.env        # Ingest an existing .env
+akm env create env/prod                           # Create an empty env file
+akm env create env/prod --from-file ./.env        # Ingest an existing .env
 akm env list                                  # List all env files across bundles with key names
 akm show env/prod                             # Inspect key names (never values or comments)
 akm env run env/prod -- ./deploy.sh           # Run a command with the whole .env injected (the safe path)
@@ -186,10 +186,10 @@ workflow. Direct run-id commands still target the exact run.
 akm workflow create ship-release --print     # Print a starter workflow template, without writing
 akm workflow create ship-release             # Scaffold a new workflow asset
 akm workflow run workflows/ship-release --version=1.2.3  # Start and execute with exact-name parameter flags
-akm workflow run <run-id> --max-retries 2 --timeout 10m  # Resume with invocation-wide controls
+akm workflow run <run-id> --max-retries 2 --timeout 10m  # Continue a run with invocation-wide controls
 akm workflow status <run-id>                 # Show the exact run by id
-akm workflow resume <run-id>                 # Resume a blocked or failed run
-akm workflow list                            # List workflow runs in the current scope
+akm workflow resume <run-id>                 # Re-activate a blocked or failed run, then `run <run-id>`
+akm workflow list                            # List workflow runs on this host
 ```
 
 ## Clone
@@ -282,7 +282,6 @@ akm bundle list --kind git                           # Filter by provider (files
 akm bundle remove <target>                           # Remove by id, ref, path, or name
 akm bundle update --all                              # Update all managed sources
 akm bundle update <target> --force                   # Force re-download
-akm bundle update <target> --allow-dangerous-env-keys # Approve reviewed dangerous env keys
 akm bundle update --all --skip-if-locked             # Scheduled refresh; exit 0 on DB contention
 ```
 

package/dist/assets/hints/cli-hints-short.md

@@ -15,9 +15,8 @@ For workflow tasks:
 2. `akm workflow run workflows/<name> --param_name=value` — execute every step and verification gate
 3. `akm workflow status <run-id> --units` — inspect a stopped or failed run
 
-Workflow runs are scoped to your current project/worktree/directory. Ref-based
-commands like `workflow run workflows/<name>`, `workflow status workflows/<name>`,
-and `workflow list` operate within the current scope only.
+A workflow ref (`workflows/<name>`) starts a new run; a run id drives that exact
+run. `workflow list` and `workflow status` see every run on this host.
 
 ## Quick Reference
 
@@ -29,7 +28,7 @@ akm search "memories/projectA/"               # List a subtree (conceptId prefix
 akm search "<query>" --from all               # Also search registries
 akm show <ref>                                # View asset details
 akm help <command>                            # Show a command's options and subcommands
-akm workflow run <ref>                        # Start or resume and execute a workflow
+akm workflow run <ref>                        # Start a new run and execute it
 akm remember "Deployment needs VPN access"    # Record a memory in your bundle
 akm remember "note" --bundle my-bundle         # Route write to a named writable bundle source
 akm remember "note" --xref knowledge/auth-flow # Cite provenance in frontmatter xrefs (repeatable)

package/dist/assets/prompts/distill-lesson-system.md

@@ -4,7 +4,10 @@ holds a lesson and, if it does, write the lesson.
 
 A memory holds a lesson when it states a cause and what to do about it: a
 failure or surprise with its cause and the fix that worked, or a rule with the
-reason it holds. It holds a lesson even when it is short and names one project,
+reason it holds. A measured or tested result also holds a lesson when someone
+could reuse it, even with no fix: what was found, under which conditions, and
+the limits the memory states (what was not checked, not confirmed, or only
+held in one place). It holds a lesson even when it is short and names one project,
 tool or incident, if the cause and the fix would help someone in a similar
 situation.
 
@@ -13,9 +16,15 @@ or decided, what is pending or planned, how a system is set up now, or the steps
 of a procedure, with no failure and cause behind it, or when its feedback says
 only that it is out of date or superseded. ANSWER NONE then: the single word and
 nothing else. A reply bound to a JSON schema answers NONE by
-setting `decision` to `none` and leaving the other fields empty. Answer NONE too
+setting `decision` to `none` and leaving the other fields empty. A status on
+a date (blocked, waiting on someone, pending approval, ready to ship) is not a
+result, and neither is the report of one run or day (counts passed and failed,
+durations, which items failed) whose cause is only suspected, with no fix
+verified: answer NONE, even if a rule could be drawn from it. A result that holds a lesson is a finding about a change or a method (what
+it did, under which conditions), not an account of how one run went. Answer NONE too
 when a related asset listed below the memory already states the rule the memory
-would give.
+would give, including when the memory is a recap or a list of reminders whose
+rules a related asset already states.
 
 When the memory holds a lesson, write it from what the memory and its feedback
 say, and nothing more:
@@ -23,7 +32,11 @@ say, and nothing more:
 - Keep the scope the memory has. A fix verified in one place is a fix for that
   place, and what was not checked stays unchecked. One case is not "always" or
   "never".
-- Be shorter than the memory.
+- Be clearly shorter than the memory (about half its length; the description,
+  when_to_use and body together, not only the body), and write it in
+  your own words. Leave out the incident's
+  story; keep only the rule, its cause and its limits. Keep the memory's
+  numbers, names, versions and terms exactly as written.
 
 YOUR RESPONSE MUST START EXACTLY WITH `---` ON THE VERY FIRST LINE.
 DO NOT output any prose, explanation, or code fences before or after.
@@ -34,7 +47,7 @@ description: <one complete sentence (ending with `.`) summarising what the lesso
 when_to_use: <one complete sentence describing the concrete trigger condition>
 ---
 
-<lesson body — plain markdown, as short as the memory allows>
+<lesson body — at most three sentences that add what the description lacks (the cause, the facts, the limits); never repeat the description>
 
 ## description field (MANDATORY)
 - A single complete sentence in present tense, 20–400 chars, NO markdown.

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/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 };
 }