@codyswann/lisa 2.337.2 → 2.338.0

package/package.json

@@ -112,10 +112,13 @@
     "postcss": ">=8.5.18",
     "undici": "^6.27.0",
     "form-data": ">=4.0.6",
-    "brace-expansion": ">=5.0.9"
+    "brace-expansion": ">=5.0.9",
+    "@istanbuljs/load-nyc-config": {
+      "js-yaml": "^3.15.1"
+    }
   },
   "name": "@codyswann/lisa",
-  "version": "2.337.2",
+  "version": "2.338.0",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {
@@ -221,7 +224,7 @@
     "husky": "^8.0.0",
     "jest": "^30.0.0",
     "jiti": "^2.4.0",
-    "js-yaml": "^4.3.0",
+    "js-yaml": "^4.3.1",
     "jscodeshift": "0.15.2",
     "jsonc-parser": "^3.3.1",
     "knip": "^5.0.0",

package/plugins/lisa/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.337.2",
+  "version": "2.338.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.337.2",
+  "version": "2.338.0",
   "description": "Universal governance: agents, skills, commands, hooks, and rules for all projects.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/skills/lisa-secrets-access/SKILL.md

@@ -129,6 +129,22 @@ ci: yes - injected by <mechanism>
 docs: <path>
 ```
 
+### `tool:` — the CLI a secret implies
+
+One key is read by more than a human. A credential and the CLI that consumes it belong together — `SONARQUBE_CLI_TOKEN` is only useful with `sonar` — so a `tool:` (or `tools: a, b`) line declares that pairing where it cannot drift from the secret:
+
+```text
+SonarCloud token, in the variable name the SonarQube CLI reads.
+owner: <name>
+tool: sonar
+```
+
+`lisa remote-env --print-tools` reads these from the materialized notes and prints the names, which is how a **repo-less** session decides what to install: with no checkout there is no `remoteEnv.tools`, and installing the whole catalogue can exhaust a cloud surface's setup-script time budget — a blown budget is a session that never starts. The machine account's grant then scopes the credentials and the CLIs together, instead of leaving a second list to maintain.
+
+Annotating **narrows**; annotating nothing changes nothing. A vault where no note carries the key yields an empty list, and an empty list means the full catalogue.
+
+Names are matched against Lisa's catalogue and **never executed**. A note is remote-influenced input — anyone who can edit a secret can edit its note — so the worst a hostile one can ask for is a CLI Lisa already ships a pinned, checksummed entry for. A name Lisa cannot install is ignored rather than treated as an error: it is a request from a future version, not a broken environment.
+
 `describe` returns this. When a note is empty, **infer purpose from the name, mark it inferred, and report the gap** — infer *and* warn, never instead of. A silent fallback that works well enough guarantees the notes stay empty forever.
 
 **An inferred mapping must never authorise a write.** It orients a reader; it does not pick which credential calls a production API. `ATTIO_API_KEY` versus `ATTIO_API_KEY_STAGING` is exactly the guess that silently writes to the wrong system.

package/plugins/lisa/.codex-plugin/skills/lisa-secrets-access/scripts/tools-from-notes.mjs

@@ -0,0 +1,59 @@
+/**
+ * Read which CLIs a secret set implies, from the notes stored beside it.
+ *
+ * A session with no checkout has no `remoteEnv.tools` to consult, so the
+ * toolchain fell back to "install the whole catalogue" — which spends a
+ * setup-script time budget on CLIs the container may never use, and on a
+ * five-minute budget that is the difference between a session and no session.
+ *
+ * The vault already knows. A credential and the CLI that consumes it belong
+ * together: `SONARQUBE_CLI_TOKEN` is only useful with `sonar`, and a machine
+ * account that cannot see the token has no business installing the CLI. Using
+ * the notes makes the provider grant the single boundary for both, instead of a
+ * second list to keep in step.
+ *
+ * Notes are free text with a loose `key: value` convention already in use
+ * (`scope:`, `owner:`, `consumers:`), so this reads a `tool:` or `tools:` line
+ * in the same shape rather than inventing a format.
+ *
+ * **Names are matched against a catalogue, never executed.** A note is
+ * remote-influenced input: anyone who can edit a secret in the vault can edit
+ * its note. Selecting from a known set means the worst a hostile note can do is
+ * ask for a CLI Lisa already ships a pinned, checksummed entry for — it can
+ * never introduce a URL, a version, or a command.
+ * @module tools-from-notes
+ */
+
+/** Matches `tool: name` or `tools: a, b`, case-insensitively, one per line. */
+const TOOL_LINE = /^[ \t]*tools?[ \t]*:[ \t]*(.+)$/gim;
+
+/**
+ * Collect the tool names a set of notes asks for.
+ *
+ * Unknown names are dropped rather than reported as an error: a note naming a
+ * CLI this version of Lisa does not ship is a request from the future, not a
+ * broken environment, and failing setup over it would be a poor trade.
+ * @param {Record<string, string>} notes Note text by secret name.
+ * @param {string[]} known Tool names Lisa can install.
+ * @returns {string[]} Known tool names, deduplicated, in catalogue order.
+ */
+export function toolsFromNotes(notes, known) {
+  const allowed = new Set(known);
+  const wanted = new Set();
+
+  for (const note of Object.values(notes ?? {})) {
+    if (typeof note !== "string") continue;
+    // `matchAll` rather than `exec` in a loop: the regex is global, and a shared
+    // lastIndex across secrets would skip matches in every note but the first.
+    for (const [, list] of note.matchAll(TOOL_LINE)) {
+      for (const raw of list.split(",")) {
+        const name = raw.trim().toLowerCase();
+        if (allowed.has(name)) wanted.add(name);
+      }
+    }
+  }
+
+  // Catalogue order, not note order, so the plan reads the same however the
+  // vault happens to be arranged.
+  return known.filter(name => wanted.has(name));
+}

package/plugins/lisa/.codex-plugin/skills/lisa-setup-remote-env/SKILL.md

@@ -13,7 +13,7 @@ Prepare a remote surface so a host project can execute there. Today that means *
 The remote environment's own configuration fields stay **one line into the repository**. Nothing else is pasted into a vendor UI.
 
 ```text
-setup:       n=0; rc=0; seen=""; for f in scripts/lisa-remote-env/setup.sh */scripts/lisa-remote-env/setup.sh "$HOME"/scripts/lisa-remote-env/setup.sh "$HOME"/*/scripts/lisa-remote-env/setup.sh /workspace/scripts/lisa-remote-env/setup.sh /workspace/*/scripts/lisa-remote-env/setup.sh; do [ -f "$f" ] || continue; d=$(cd "$(dirname "$f")" && pwd -P); case " $seen " in *" $d "*) continue;; esac; seen="$seen $d"; n=$((n+1)); bash "$f" || rc=$?; done; [ "$n" -gt 0 ] && exit "$rc"; g=0; for c in ./.git ./*/.git "$HOME"/*/.git /workspace/*/.git; do [ -e "$c" ] && g=1; done; if [ "$g" -eq 1 ]; then echo "lisa-remote-env entrypoint not found, but a checkout is present. PWD=$PWD HOME=$HOME" >&2; ls -1 . "$HOME" /workspace 2>&1 | head -40 >&2; exit 1; fi; ten="${LISA_TENANT:-${LISA_SECRETS_NAMESPACE:-}}"; if [ -n "$ten" ]; then echo "No checkout; preparing tools and credentials for $ten."; tw=0; ts=0; npx -y @codyswann/lisa@2.337.1 workstation --install --agents=none --provider="${LISA_PROVIDER:-${LISA_SECRETS_PROVIDER:-bitwarden}}" || tw=$?; export PATH="$HOME/.local/bin:$PATH"; npx -y @codyswann/lisa@2.337.1 remote-env --phase=secrets || ts=$?; [ "$tw" -eq 0 ] || echo "SETUP INCOMPLETE: tool install failed (exit $tw). The session will start WITHOUT the pinned tools." >&2; [ "$ts" -eq 0 ] || echo "SETUP INCOMPLETE: secrets did not materialize (exit $ts). The session will start WITHOUT credentials." >&2; else echo "No checkout and no tenant configured; nothing to prepare."; fi; exit 0
+setup:       n=0; rc=0; seen=""; for f in scripts/lisa-remote-env/setup.sh */scripts/lisa-remote-env/setup.sh "$HOME"/scripts/lisa-remote-env/setup.sh "$HOME"/*/scripts/lisa-remote-env/setup.sh /workspace/scripts/lisa-remote-env/setup.sh /workspace/*/scripts/lisa-remote-env/setup.sh; do [ -f "$f" ] || continue; d=$(cd "$(dirname "$f")" && pwd -P); case " $seen " in *" $d "*) continue;; esac; seen="$seen $d"; n=$((n+1)); bash "$f" || rc=$?; done; [ "$n" -gt 0 ] && exit "$rc"; g=0; for c in ./.git ./*/.git "$HOME"/*/.git /workspace/*/.git; do [ -e "$c" ] && g=1; done; if [ "$g" -eq 1 ]; then echo "lisa-remote-env entrypoint not found, but a checkout is present. PWD=$PWD HOME=$HOME" >&2; ls -1 . "$HOME" /workspace 2>&1 | head -40 >&2; exit 1; fi; ten="${LISA_TENANT:-${LISA_SECRETS_NAMESPACE:-}}"; if [ -n "$ten" ]; then echo "No checkout; preparing tools and credentials for $ten."; tw=0; tt=0; ts=0; tp=0; npx -y @codyswann/lisa@2.337.3 workstation --install --agents=none --tools=none --provider="${LISA_PROVIDER:-${LISA_SECRETS_PROVIDER:-bitwarden}}" || tw=$?; export PATH="$HOME/.local/bin:$PATH"; npx -y @codyswann/lisa@2.337.3 remote-env --phase=secrets || ts=$?; w=$(npx -y @codyswann/lisa@2.337.3 remote-env --print-tools 2>/dev/null) || tp=$?; w=$(printf "%s\n" "$w" | tail -1); [ "$tp" -eq 0 ] || echo "SETUP INCOMPLETE: could not read the tool list from the vault (exit $tp). Installing the full catalogue." >&2; npx -y @codyswann/lisa@2.337.3 workstation --install --agents=none --tools="$w" --provider="${LISA_PROVIDER:-${LISA_SECRETS_PROVIDER:-bitwarden}}" || tt=$?; [ "$tw" -eq 0 ] && [ "$tt" -eq 0 ] || echo "SETUP INCOMPLETE: tool install failed (exit $tw/$tt). The session will start WITHOUT the pinned tools." >&2; [ "$ts" -eq 0 ] || echo "SETUP INCOMPLETE: secrets did not materialize (exit $ts). The session will start WITHOUT credentials." >&2; else echo "No checkout and no tenant configured; nothing to prepare."; fi; exit 0
 maintenance: n=0; rc=0; seen=""; for f in scripts/lisa-remote-env/setup.sh */scripts/lisa-remote-env/setup.sh "$HOME"/scripts/lisa-remote-env/setup.sh "$HOME"/*/scripts/lisa-remote-env/setup.sh /workspace/scripts/lisa-remote-env/setup.sh /workspace/*/scripts/lisa-remote-env/setup.sh; do [ -f "$f" ] || continue; d=$(cd "$(dirname "$f")" && pwd -P); case " $seen " in *" $d "*) continue;; esac; seen="$seen $d"; n=$((n+1)); bash "$f" || rc=$?; done; [ "$n" -gt 0 ] || { echo "lisa-remote-env entrypoint not found. PWD=$PWD HOME=$HOME" >&2; ls -1 . "$HOME" /workspace 2>&1 | head -40 >&2; exit 1; }; exit "$rc"
 ```
 

package/plugins/lisa/.codex-plugin/skills/lisa-setup-remote-env/scripts/setup-remote-env.mjs

@@ -644,7 +644,7 @@ export const SETUP_FIELD =
   'ten="${LISA_TENANT:-${LISA_SECRETS_NAMESPACE:-}}"; ' +
   'if [ -n "$ten" ]; then ' +
   'echo "No checkout; preparing tools and credentials for $ten."; ' +
-  "tw=0; ts=0; " +
+  "tw=0; tt=0; ts=0; tp=0; " +
   // `--agents=none` is load-bearing, not tidiness.
   //
   // The bootstrap's default is every coding agent it knows: claude, codex,
@@ -657,15 +657,39 @@ export const SETUP_FIELD =
   // A remote container needs the provider CLI and the tools; it does not need
   // agents, because it IS one. No AGENTS entry is named "none", so the filter
   // selects nothing — pinned by a test, since it reads like a magic word.
-  `npx -y ${SELF_SPEC} workstation --install --agents=none ` +
+  // Two passes, credentials in between, because the vault is what knows which
+  // CLIs this container needs — and it cannot be asked until it has been read.
+  //
+  // The first pass installs only the provider CLI (`--tools=none`, the same
+  // idiom as `--agents=none`), because that is all materialization requires.
+  `npx -y ${SELF_SPEC} workstation --install --agents=none --tools=none ` +
   '--provider="${LISA_PROVIDER:-${LISA_SECRETS_PROVIDER:-bitwarden}}" || tw=$?; ' +
   // Exported BEFORE the secrets phase, not after: the toolchain installs into
   // ~/.local/bin, and materialization spawns the provider CLI by name. Ordered
   // the other way it gets ENOENT on a binary that is sitting right there.
   'export PATH="$HOME/.local/bin:$PATH"; ' +
   `npx -y ${SELF_SPEC} remote-env --phase=secrets || ts=$?; ` +
-  '[ "$tw" -eq 0 ] || echo "SETUP INCOMPLETE: tool install failed ' +
-  '(exit $tw). The session will start WITHOUT the pinned tools." >&2; ' +
+  // Now the notes can answer it. A vault that names nothing yields an empty
+  // string, and `--tools=` with an empty value selects the whole catalogue —
+  // so annotating the notes NARROWS what gets installed, and not annotating
+  // them leaves this field behaving exactly as it did before.
+  //
+  // stderr is dropped and only the last line kept: npx narrates to stderr, and
+  // this is a command substitution whose output becomes a flag value.
+  //
+  // The status is captured BEFORE the pipe, because `tail` exits 0 whatever
+  // happened upstream. A failed lookup still falls through to the whole
+  // catalogue — installing too much is the safe direction, and it is what this
+  // field did before the vault had any say — but it says so, rather than being
+  // indistinguishable from a vault that simply names nothing.
+  `w=$(npx -y ${SELF_SPEC} remote-env --print-tools 2>/dev/null) || tp=$?; ` +
+  'w=$(printf "%s\\n" "$w" | tail -1); ' +
+  '[ "$tp" -eq 0 ] || echo "SETUP INCOMPLETE: could not read the tool list ' +
+  'from the vault (exit $tp). Installing the full catalogue." >&2; ' +
+  `npx -y ${SELF_SPEC} workstation --install --agents=none --tools="$w" ` +
+  '--provider="${LISA_PROVIDER:-${LISA_SECRETS_PROVIDER:-bitwarden}}" || tt=$?; ' +
+  '[ "$tw" -eq 0 ] && [ "$tt" -eq 0 ] || echo "SETUP INCOMPLETE: tool install ' +
+  'failed (exit $tw/$tt). The session will start WITHOUT the pinned tools." >&2; ' +
   '[ "$ts" -eq 0 ] || echo "SETUP INCOMPLETE: secrets did not materialize ' +
   '(exit $ts). The session will start WITHOUT credentials." >&2; ' +
   'else echo "No checkout and no tenant configured; nothing to prepare."; fi; ' +
@@ -1023,6 +1047,43 @@ function readBootstrapKey(cwd = process.cwd()) {
 }
 
 async function main() {
+  // `--print-tools` answers "which CLIs does this secret set imply", reading
+  // the notes materialized alongside the values.
+  //
+  // It exists so a repo-less setup can install what the container actually
+  // needs. Without a checkout there is no `remoteEnv.tools`, and the fallback
+  // was the whole catalogue — which spends a five-minute setup budget on CLIs
+  // that may never be used, and a blown budget is a session that never starts.
+  //
+  // Printing rather than installing keeps the two skills decoupled: the secrets
+  // side knows what the vault says, the workstation side knows how to install,
+  // and neither grows a dependency on the other.
+  if (process.argv.includes("--print-tools")) {
+    const { readConfig, materializedPaths } = await import(
+      pathToFileURL(siblingScript("lisa-secrets-access", "surfaces.mjs")).href
+    );
+    const { toolsFromNotes } = await import(
+      pathToFileURL(
+        siblingScript("lisa-secrets-access", "tools-from-notes.mjs")
+      ).href
+    );
+    const { TOOLS } = await import(
+      pathToFileURL(siblingScript("lisa-setup-workstation", "catalogue.mjs"))
+        .href
+    );
+
+    const { notesFile } = materializedPaths(readConfig().namespace);
+    // Silence rather than failure when nothing has been materialized: the
+    // caller is a shell substitution in a setup script, and an error there
+    // would abort provisioning over a question that simply has no answer yet.
+    if (!existsSync(notesFile)) return;
+
+    const notes = JSON.parse(readFileSync(notesFile, "utf8")).secrets ?? {};
+    const known = TOOLS.filter(t => t.kind !== "required").map(t => t.name);
+    console.log(toolsFromNotes(notes, known).join(","));
+    return;
+  }
+
   const dryRun = process.argv.includes("--dry-run");
   const emit = process.argv
     .find(arg => arg.startsWith("--emit="))

package/plugins/lisa/.codex-plugin/skills/lisa-setup-workstation/scripts/cli.mjs

@@ -10,6 +10,9 @@
  *   cli.mjs                                report present vs missing
  *   cli.mjs --install                      provision what is missing
  *   cli.mjs --install --agents=claude,codex   only these agents
+ *   cli.mjs --install --tools=aws,sonar    only these OPTIONAL tools; required
+ *                                          ones are always kept, and an empty
+ *                                          value selects the whole catalogue
  *   cli.mjs --provider=bitwarden           credential manager (asked if a TTY)
  *   cli.mjs --json                         machine-readable plan
  *   cli.mjs --print-dockerfile             an image that runs this same script
@@ -177,6 +180,21 @@ export async function run(argv, io = {}) {
         .filter(Boolean)
     : null;
 
+  // `--tools=` with nothing after it selects everything, deliberately.
+  //
+  // Its caller is a shell substitution — a repo-less setup script asking the
+  // vault which CLIs its secrets imply — and a vault that names none must leave
+  // the container exactly as it was before this flag existed. Reading an empty
+  // value as "install nothing" would make adopting the convention a silent
+  // regression for every environment that has not annotated its notes yet.
+  const requested = value("tools");
+  const tools = requested
+    ? requested
+        .split(",")
+        .map(s => s.trim())
+        .filter(Boolean)
+    : null;
+
   const provider = chooseProvider(value("provider"), io);
 
   if (flag("print-dockerfile")) {
@@ -186,7 +204,7 @@ export async function run(argv, io = {}) {
 
   let plan;
   try {
-    plan = planWorkstation({ agents, provider, ...(io.probes ?? {}) });
+    plan = planWorkstation({ agents, tools, provider, ...(io.probes ?? {}) });
   } catch (error) {
     // A misspelled provider stops here rather than silently provisioning the
     // wrong credential manager.

package/plugins/lisa/.codex-plugin/skills/lisa-setup-workstation/scripts/workstation.mjs

@@ -168,7 +168,17 @@ export function planWorkstation(options = {}) {
       group: "agent",
     })
   );
-  const tools = TOOLS.map(t => ({ ...planEntry(t, options), group: "tool" }));
+  // Tools are selectable for the same reason agents are, and it matters more
+  // here: a remote container has a setup-script time budget, and installing a
+  // CLI nothing in that container uses spends it for nothing.
+  //
+  // A `required` tool is never filtered out. Those are not installs — they are
+  // assertions about the machine (git, node), and hiding them would turn a
+  // missing prerequisite into a silent one.
+  const wantedTools = options.tools ?? null;
+  const tools = TOOLS.filter(
+    t => t.kind === "required" || !wantedTools || wantedTools.includes(t.name)
+  ).map(t => ({ ...planEntry(t, options), group: "tool" }));
 
   // Only the SELECTED provider is planned. Installing every credential CLI
   // would leave four unused ones on the machine, each needing patching for no

package/plugins/lisa/skills/lisa-secrets-access/SKILL.md

@@ -129,6 +129,22 @@ ci: yes - injected by <mechanism>
 docs: <path>
 ```
 
+### `tool:` — the CLI a secret implies
+
+One key is read by more than a human. A credential and the CLI that consumes it belong together — `SONARQUBE_CLI_TOKEN` is only useful with `sonar` — so a `tool:` (or `tools: a, b`) line declares that pairing where it cannot drift from the secret:
+
+```text
+SonarCloud token, in the variable name the SonarQube CLI reads.
+owner: <name>
+tool: sonar
+```
+
+`lisa remote-env --print-tools` reads these from the materialized notes and prints the names, which is how a **repo-less** session decides what to install: with no checkout there is no `remoteEnv.tools`, and installing the whole catalogue can exhaust a cloud surface's setup-script time budget — a blown budget is a session that never starts. The machine account's grant then scopes the credentials and the CLIs together, instead of leaving a second list to maintain.
+
+Annotating **narrows**; annotating nothing changes nothing. A vault where no note carries the key yields an empty list, and an empty list means the full catalogue.
+
+Names are matched against Lisa's catalogue and **never executed**. A note is remote-influenced input — anyone who can edit a secret can edit its note — so the worst a hostile one can ask for is a CLI Lisa already ships a pinned, checksummed entry for. A name Lisa cannot install is ignored rather than treated as an error: it is a request from a future version, not a broken environment.
+
 `describe` returns this. When a note is empty, **infer purpose from the name, mark it inferred, and report the gap** — infer *and* warn, never instead of. A silent fallback that works well enough guarantees the notes stay empty forever.
 
 **An inferred mapping must never authorise a write.** It orients a reader; it does not pick which credential calls a production API. `ATTIO_API_KEY` versus `ATTIO_API_KEY_STAGING` is exactly the guess that silently writes to the wrong system.

package/plugins/lisa/skills/lisa-secrets-access/scripts/tools-from-notes.mjs

@@ -0,0 +1,59 @@
+/**
+ * Read which CLIs a secret set implies, from the notes stored beside it.
+ *
+ * A session with no checkout has no `remoteEnv.tools` to consult, so the
+ * toolchain fell back to "install the whole catalogue" — which spends a
+ * setup-script time budget on CLIs the container may never use, and on a
+ * five-minute budget that is the difference between a session and no session.
+ *
+ * The vault already knows. A credential and the CLI that consumes it belong
+ * together: `SONARQUBE_CLI_TOKEN` is only useful with `sonar`, and a machine
+ * account that cannot see the token has no business installing the CLI. Using
+ * the notes makes the provider grant the single boundary for both, instead of a
+ * second list to keep in step.
+ *
+ * Notes are free text with a loose `key: value` convention already in use
+ * (`scope:`, `owner:`, `consumers:`), so this reads a `tool:` or `tools:` line
+ * in the same shape rather than inventing a format.
+ *
+ * **Names are matched against a catalogue, never executed.** A note is
+ * remote-influenced input: anyone who can edit a secret in the vault can edit
+ * its note. Selecting from a known set means the worst a hostile note can do is
+ * ask for a CLI Lisa already ships a pinned, checksummed entry for — it can
+ * never introduce a URL, a version, or a command.
+ * @module tools-from-notes
+ */
+
+/** Matches `tool: name` or `tools: a, b`, case-insensitively, one per line. */
+const TOOL_LINE = /^[ \t]*tools?[ \t]*:[ \t]*(.+)$/gim;
+
+/**
+ * Collect the tool names a set of notes asks for.
+ *
+ * Unknown names are dropped rather than reported as an error: a note naming a
+ * CLI this version of Lisa does not ship is a request from the future, not a
+ * broken environment, and failing setup over it would be a poor trade.
+ * @param {Record<string, string>} notes Note text by secret name.
+ * @param {string[]} known Tool names Lisa can install.
+ * @returns {string[]} Known tool names, deduplicated, in catalogue order.
+ */
+export function toolsFromNotes(notes, known) {
+  const allowed = new Set(known);
+  const wanted = new Set();
+
+  for (const note of Object.values(notes ?? {})) {
+    if (typeof note !== "string") continue;
+    // `matchAll` rather than `exec` in a loop: the regex is global, and a shared
+    // lastIndex across secrets would skip matches in every note but the first.
+    for (const [, list] of note.matchAll(TOOL_LINE)) {
+      for (const raw of list.split(",")) {
+        const name = raw.trim().toLowerCase();
+        if (allowed.has(name)) wanted.add(name);
+      }
+    }
+  }
+
+  // Catalogue order, not note order, so the plan reads the same however the
+  // vault happens to be arranged.
+  return known.filter(name => wanted.has(name));
+}

package/plugins/lisa/skills/lisa-setup-remote-env/SKILL.md

@@ -13,7 +13,7 @@ Prepare a remote surface so a host project can execute there. Today that means *
 The remote environment's own configuration fields stay **one line into the repository**. Nothing else is pasted into a vendor UI.
 
 ```text
-setup:       n=0; rc=0; seen=""; for f in scripts/lisa-remote-env/setup.sh */scripts/lisa-remote-env/setup.sh "$HOME"/scripts/lisa-remote-env/setup.sh "$HOME"/*/scripts/lisa-remote-env/setup.sh /workspace/scripts/lisa-remote-env/setup.sh /workspace/*/scripts/lisa-remote-env/setup.sh; do [ -f "$f" ] || continue; d=$(cd "$(dirname "$f")" && pwd -P); case " $seen " in *" $d "*) continue;; esac; seen="$seen $d"; n=$((n+1)); bash "$f" || rc=$?; done; [ "$n" -gt 0 ] && exit "$rc"; g=0; for c in ./.git ./*/.git "$HOME"/*/.git /workspace/*/.git; do [ -e "$c" ] && g=1; done; if [ "$g" -eq 1 ]; then echo "lisa-remote-env entrypoint not found, but a checkout is present. PWD=$PWD HOME=$HOME" >&2; ls -1 . "$HOME" /workspace 2>&1 | head -40 >&2; exit 1; fi; ten="${LISA_TENANT:-${LISA_SECRETS_NAMESPACE:-}}"; if [ -n "$ten" ]; then echo "No checkout; preparing tools and credentials for $ten."; tw=0; ts=0; npx -y @codyswann/lisa@2.337.1 workstation --install --agents=none --provider="${LISA_PROVIDER:-${LISA_SECRETS_PROVIDER:-bitwarden}}" || tw=$?; export PATH="$HOME/.local/bin:$PATH"; npx -y @codyswann/lisa@2.337.1 remote-env --phase=secrets || ts=$?; [ "$tw" -eq 0 ] || echo "SETUP INCOMPLETE: tool install failed (exit $tw). The session will start WITHOUT the pinned tools." >&2; [ "$ts" -eq 0 ] || echo "SETUP INCOMPLETE: secrets did not materialize (exit $ts). The session will start WITHOUT credentials." >&2; else echo "No checkout and no tenant configured; nothing to prepare."; fi; exit 0
+setup:       n=0; rc=0; seen=""; for f in scripts/lisa-remote-env/setup.sh */scripts/lisa-remote-env/setup.sh "$HOME"/scripts/lisa-remote-env/setup.sh "$HOME"/*/scripts/lisa-remote-env/setup.sh /workspace/scripts/lisa-remote-env/setup.sh /workspace/*/scripts/lisa-remote-env/setup.sh; do [ -f "$f" ] || continue; d=$(cd "$(dirname "$f")" && pwd -P); case " $seen " in *" $d "*) continue;; esac; seen="$seen $d"; n=$((n+1)); bash "$f" || rc=$?; done; [ "$n" -gt 0 ] && exit "$rc"; g=0; for c in ./.git ./*/.git "$HOME"/*/.git /workspace/*/.git; do [ -e "$c" ] && g=1; done; if [ "$g" -eq 1 ]; then echo "lisa-remote-env entrypoint not found, but a checkout is present. PWD=$PWD HOME=$HOME" >&2; ls -1 . "$HOME" /workspace 2>&1 | head -40 >&2; exit 1; fi; ten="${LISA_TENANT:-${LISA_SECRETS_NAMESPACE:-}}"; if [ -n "$ten" ]; then echo "No checkout; preparing tools and credentials for $ten."; tw=0; tt=0; ts=0; tp=0; npx -y @codyswann/lisa@2.337.3 workstation --install --agents=none --tools=none --provider="${LISA_PROVIDER:-${LISA_SECRETS_PROVIDER:-bitwarden}}" || tw=$?; export PATH="$HOME/.local/bin:$PATH"; npx -y @codyswann/lisa@2.337.3 remote-env --phase=secrets || ts=$?; w=$(npx -y @codyswann/lisa@2.337.3 remote-env --print-tools 2>/dev/null) || tp=$?; w=$(printf "%s\n" "$w" | tail -1); [ "$tp" -eq 0 ] || echo "SETUP INCOMPLETE: could not read the tool list from the vault (exit $tp). Installing the full catalogue." >&2; npx -y @codyswann/lisa@2.337.3 workstation --install --agents=none --tools="$w" --provider="${LISA_PROVIDER:-${LISA_SECRETS_PROVIDER:-bitwarden}}" || tt=$?; [ "$tw" -eq 0 ] && [ "$tt" -eq 0 ] || echo "SETUP INCOMPLETE: tool install failed (exit $tw/$tt). The session will start WITHOUT the pinned tools." >&2; [ "$ts" -eq 0 ] || echo "SETUP INCOMPLETE: secrets did not materialize (exit $ts). The session will start WITHOUT credentials." >&2; else echo "No checkout and no tenant configured; nothing to prepare."; fi; exit 0
 maintenance: n=0; rc=0; seen=""; for f in scripts/lisa-remote-env/setup.sh */scripts/lisa-remote-env/setup.sh "$HOME"/scripts/lisa-remote-env/setup.sh "$HOME"/*/scripts/lisa-remote-env/setup.sh /workspace/scripts/lisa-remote-env/setup.sh /workspace/*/scripts/lisa-remote-env/setup.sh; do [ -f "$f" ] || continue; d=$(cd "$(dirname "$f")" && pwd -P); case " $seen " in *" $d "*) continue;; esac; seen="$seen $d"; n=$((n+1)); bash "$f" || rc=$?; done; [ "$n" -gt 0 ] || { echo "lisa-remote-env entrypoint not found. PWD=$PWD HOME=$HOME" >&2; ls -1 . "$HOME" /workspace 2>&1 | head -40 >&2; exit 1; }; exit "$rc"
 ```
 

package/plugins/lisa/skills/lisa-setup-remote-env/scripts/setup-remote-env.mjs

@@ -644,7 +644,7 @@ export const SETUP_FIELD =
   'ten="${LISA_TENANT:-${LISA_SECRETS_NAMESPACE:-}}"; ' +
   'if [ -n "$ten" ]; then ' +
   'echo "No checkout; preparing tools and credentials for $ten."; ' +
-  "tw=0; ts=0; " +
+  "tw=0; tt=0; ts=0; tp=0; " +
   // `--agents=none` is load-bearing, not tidiness.
   //
   // The bootstrap's default is every coding agent it knows: claude, codex,
@@ -657,15 +657,39 @@ export const SETUP_FIELD =
   // A remote container needs the provider CLI and the tools; it does not need
   // agents, because it IS one. No AGENTS entry is named "none", so the filter
   // selects nothing — pinned by a test, since it reads like a magic word.
-  `npx -y ${SELF_SPEC} workstation --install --agents=none ` +
+  // Two passes, credentials in between, because the vault is what knows which
+  // CLIs this container needs — and it cannot be asked until it has been read.
+  //
+  // The first pass installs only the provider CLI (`--tools=none`, the same
+  // idiom as `--agents=none`), because that is all materialization requires.
+  `npx -y ${SELF_SPEC} workstation --install --agents=none --tools=none ` +
   '--provider="${LISA_PROVIDER:-${LISA_SECRETS_PROVIDER:-bitwarden}}" || tw=$?; ' +
   // Exported BEFORE the secrets phase, not after: the toolchain installs into
   // ~/.local/bin, and materialization spawns the provider CLI by name. Ordered
   // the other way it gets ENOENT on a binary that is sitting right there.
   'export PATH="$HOME/.local/bin:$PATH"; ' +
   `npx -y ${SELF_SPEC} remote-env --phase=secrets || ts=$?; ` +
-  '[ "$tw" -eq 0 ] || echo "SETUP INCOMPLETE: tool install failed ' +
-  '(exit $tw). The session will start WITHOUT the pinned tools." >&2; ' +
+  // Now the notes can answer it. A vault that names nothing yields an empty
+  // string, and `--tools=` with an empty value selects the whole catalogue —
+  // so annotating the notes NARROWS what gets installed, and not annotating
+  // them leaves this field behaving exactly as it did before.
+  //
+  // stderr is dropped and only the last line kept: npx narrates to stderr, and
+  // this is a command substitution whose output becomes a flag value.
+  //
+  // The status is captured BEFORE the pipe, because `tail` exits 0 whatever
+  // happened upstream. A failed lookup still falls through to the whole
+  // catalogue — installing too much is the safe direction, and it is what this
+  // field did before the vault had any say — but it says so, rather than being
+  // indistinguishable from a vault that simply names nothing.
+  `w=$(npx -y ${SELF_SPEC} remote-env --print-tools 2>/dev/null) || tp=$?; ` +
+  'w=$(printf "%s\\n" "$w" | tail -1); ' +
+  '[ "$tp" -eq 0 ] || echo "SETUP INCOMPLETE: could not read the tool list ' +
+  'from the vault (exit $tp). Installing the full catalogue." >&2; ' +
+  `npx -y ${SELF_SPEC} workstation --install --agents=none --tools="$w" ` +
+  '--provider="${LISA_PROVIDER:-${LISA_SECRETS_PROVIDER:-bitwarden}}" || tt=$?; ' +
+  '[ "$tw" -eq 0 ] && [ "$tt" -eq 0 ] || echo "SETUP INCOMPLETE: tool install ' +
+  'failed (exit $tw/$tt). The session will start WITHOUT the pinned tools." >&2; ' +
   '[ "$ts" -eq 0 ] || echo "SETUP INCOMPLETE: secrets did not materialize ' +
   '(exit $ts). The session will start WITHOUT credentials." >&2; ' +
   'else echo "No checkout and no tenant configured; nothing to prepare."; fi; ' +
@@ -1023,6 +1047,43 @@ function readBootstrapKey(cwd = process.cwd()) {
 }
 
 async function main() {
+  // `--print-tools` answers "which CLIs does this secret set imply", reading
+  // the notes materialized alongside the values.
+  //
+  // It exists so a repo-less setup can install what the container actually
+  // needs. Without a checkout there is no `remoteEnv.tools`, and the fallback
+  // was the whole catalogue — which spends a five-minute setup budget on CLIs
+  // that may never be used, and a blown budget is a session that never starts.
+  //
+  // Printing rather than installing keeps the two skills decoupled: the secrets
+  // side knows what the vault says, the workstation side knows how to install,
+  // and neither grows a dependency on the other.
+  if (process.argv.includes("--print-tools")) {
+    const { readConfig, materializedPaths } = await import(
+      pathToFileURL(siblingScript("lisa-secrets-access", "surfaces.mjs")).href
+    );
+    const { toolsFromNotes } = await import(
+      pathToFileURL(
+        siblingScript("lisa-secrets-access", "tools-from-notes.mjs")
+      ).href
+    );
+    const { TOOLS } = await import(
+      pathToFileURL(siblingScript("lisa-setup-workstation", "catalogue.mjs"))
+        .href
+    );
+
+    const { notesFile } = materializedPaths(readConfig().namespace);
+    // Silence rather than failure when nothing has been materialized: the
+    // caller is a shell substitution in a setup script, and an error there
+    // would abort provisioning over a question that simply has no answer yet.
+    if (!existsSync(notesFile)) return;
+
+    const notes = JSON.parse(readFileSync(notesFile, "utf8")).secrets ?? {};
+    const known = TOOLS.filter(t => t.kind !== "required").map(t => t.name);
+    console.log(toolsFromNotes(notes, known).join(","));
+    return;
+  }
+
   const dryRun = process.argv.includes("--dry-run");
   const emit = process.argv
     .find(arg => arg.startsWith("--emit="))

package/plugins/lisa/skills/lisa-setup-workstation/scripts/cli.mjs

@@ -10,6 +10,9 @@
  *   cli.mjs                                report present vs missing
  *   cli.mjs --install                      provision what is missing
  *   cli.mjs --install --agents=claude,codex   only these agents
+ *   cli.mjs --install --tools=aws,sonar    only these OPTIONAL tools; required
+ *                                          ones are always kept, and an empty
+ *                                          value selects the whole catalogue
  *   cli.mjs --provider=bitwarden           credential manager (asked if a TTY)
  *   cli.mjs --json                         machine-readable plan
  *   cli.mjs --print-dockerfile             an image that runs this same script
@@ -177,6 +180,21 @@ export async function run(argv, io = {}) {
         .filter(Boolean)
     : null;
 
+  // `--tools=` with nothing after it selects everything, deliberately.
+  //
+  // Its caller is a shell substitution — a repo-less setup script asking the
+  // vault which CLIs its secrets imply — and a vault that names none must leave
+  // the container exactly as it was before this flag existed. Reading an empty
+  // value as "install nothing" would make adopting the convention a silent
+  // regression for every environment that has not annotated its notes yet.
+  const requested = value("tools");
+  const tools = requested
+    ? requested
+        .split(",")
+        .map(s => s.trim())
+        .filter(Boolean)
+    : null;
+
   const provider = chooseProvider(value("provider"), io);
 
   if (flag("print-dockerfile")) {
@@ -186,7 +204,7 @@ export async function run(argv, io = {}) {
 
   let plan;
   try {
-    plan = planWorkstation({ agents, provider, ...(io.probes ?? {}) });
+    plan = planWorkstation({ agents, tools, provider, ...(io.probes ?? {}) });
   } catch (error) {
     // A misspelled provider stops here rather than silently provisioning the
     // wrong credential manager.

package/plugins/lisa/skills/lisa-setup-workstation/scripts/workstation.mjs

@@ -168,7 +168,17 @@ export function planWorkstation(options = {}) {
       group: "agent",
     })
   );
-  const tools = TOOLS.map(t => ({ ...planEntry(t, options), group: "tool" }));
+  // Tools are selectable for the same reason agents are, and it matters more
+  // here: a remote container has a setup-script time budget, and installing a
+  // CLI nothing in that container uses spends it for nothing.
+  //
+  // A `required` tool is never filtered out. Those are not installs — they are
+  // assertions about the machine (git, node), and hiding them would turn a
+  // missing prerequisite into a silent one.
+  const wantedTools = options.tools ?? null;
+  const tools = TOOLS.filter(
+    t => t.kind === "required" || !wantedTools || wantedTools.includes(t.name)
+  ).map(t => ({ ...planEntry(t, options), group: "tool" }));
 
   // Only the SELECTED provider is planned. Installing every credential CLI
   // would leave four unused ones on the machine, each needing patching for no

package/plugins/lisa-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.337.2",
+  "version": "2.338.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-agy/skills/lisa-secrets-access/SKILL.md

@@ -129,6 +129,22 @@ ci: yes - injected by <mechanism>
 docs: <path>
 ```
 
+### `tool:` — the CLI a secret implies
+
+One key is read by more than a human. A credential and the CLI that consumes it belong together — `SONARQUBE_CLI_TOKEN` is only useful with `sonar` — so a `tool:` (or `tools: a, b`) line declares that pairing where it cannot drift from the secret:
+
+```text
+SonarCloud token, in the variable name the SonarQube CLI reads.
+owner: <name>
+tool: sonar
+```
+
+`lisa remote-env --print-tools` reads these from the materialized notes and prints the names, which is how a **repo-less** session decides what to install: with no checkout there is no `remoteEnv.tools`, and installing the whole catalogue can exhaust a cloud surface's setup-script time budget — a blown budget is a session that never starts. The machine account's grant then scopes the credentials and the CLIs together, instead of leaving a second list to maintain.
+
+Annotating **narrows**; annotating nothing changes nothing. A vault where no note carries the key yields an empty list, and an empty list means the full catalogue.
+
+Names are matched against Lisa's catalogue and **never executed**. A note is remote-influenced input — anyone who can edit a secret can edit its note — so the worst a hostile one can ask for is a CLI Lisa already ships a pinned, checksummed entry for. A name Lisa cannot install is ignored rather than treated as an error: it is a request from a future version, not a broken environment.
+
 `describe` returns this. When a note is empty, **infer purpose from the name, mark it inferred, and report the gap** — infer *and* warn, never instead of. A silent fallback that works well enough guarantees the notes stay empty forever.
 
 **An inferred mapping must never authorise a write.** It orients a reader; it does not pick which credential calls a production API. `ATTIO_API_KEY` versus `ATTIO_API_KEY_STAGING` is exactly the guess that silently writes to the wrong system.