@codyswann/lisa 2.338.1 → 2.338.3

package/package.json

@@ -118,7 +118,7 @@
     }
   },
   "name": "@codyswann/lisa",
-  "version": "2.338.1",
+  "version": "2.338.3",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.338.1",
+  "version": "2.338.3",
   "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.338.1",
+  "version": "2.338.3",
   "description": "Universal governance: agents, skills, commands, hooks, and rules for all projects.",
   "author": {
     "name": "Cody Swann"

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

@@ -12,11 +12,26 @@ 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; tt=0; ts=0; tp=0; npx -y @codyswann/lisa@2.338.0 workstation --install --agents=none --tools=none --provider="${LISA_PROVIDER:-${LISA_SECRETS_PROVIDER:-bitwarden}}" || tw=$?; export PATH="$HOME/.local/bin:$HOME/.opencode/bin:$HOME/.local/share/sonarqube-cli/bin:$PATH"; npx -y @codyswann/lisa@2.338.0 remote-env --phase=secrets || ts=$?; w=$(npx -y @codyswann/lisa@2.338.0 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.338.0 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"
+**Ask for that line; do not copy it from here.**
+
+```bash
+npx -y @codyswann/lisa@latest remote-env --emit=claude-web
 ```
 
+The field pins the exact Lisa it runs, and the emitter reads that version from
+the package it is running out of — so the line it prints is always pinned to the
+version that printed it.
+
+A copy written into this file cannot have that property. It is a snapshot taken
+when the package was *built*, and the release bumps the version *after* the
+build, so a published tarball's copy names the previous release. That is not a
+cosmetic lag: the pinned version predates whatever this file documents, so a
+pasted copy can call flags that version does not implement. Measured on
+`2.338.1`, whose embedded copy named `2.338.0` — a Lisa with no `--print-tools`,
+no `--tools`, and no `tools-from-notes.mjs`. Unknown flags are ignored rather
+than rejected, so it did not fail; it installed the full catalogue and re-ran the
+whole setup, three times over, inside a five-minute budget.
+
 **That line is identical for every project AND every surface.** Nothing in it names the
 repository or the package manager, so it can be pasted unchanged anywhere.
 
@@ -236,8 +251,10 @@ When emitting, produce exactly:
 ```text
 Environment name:  <project> remote executor
 Repository:        <org>/<repo>        (must be the default checkout)
-Setup script:      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"
-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"
+Setup script:      <printed by `remote-env --emit`; never copied
+                   from prose, so its pin is always the version
+                   that printed it>
+Maintenance:       <same line, printed by the same command>
                    (identical for every project — the script finds the
                    checkout and installs from the committed lockfile)
 Environment vars:  LISA_SECRETS_SURFACE=codex-cloud

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

@@ -912,6 +912,21 @@ export function emitClaudeWeb({ bootstrapKey }) {
     "    is why exactly one value needs to live here.",
     "",
     "  Setup script:",
+    "",
+    "    A setup script sees NONE of the variables configured above — it runs",
+    "    while the image is being built, before the environment exists. So a",
+    "    session with no checkout has to be told its tenant inside the script",
+    "    itself, or the field finds nothing to prepare and exits 0 looking like",
+    "    success. Put these three lines FIRST, then the line after them:",
+    "",
+    "      export LISA_TENANT=<your namespace>",
+    `      export ${key}='<the same value as above>'`,
+    "      export LISA_SECRETS_SURFACE=claude-web",
+    "",
+    "    LISA_SECRETS_SURFACE is set explicitly rather than left to detection:",
+    "    detection keys off CLAUDE_CODE_REMOTE, and a surface that does not set",
+    "    it falls through to `local`, which writes no credentials to disk at all.",
+    "",
     `    ${SETUP_FIELD}`,
     "",
     "    This line is identical for every project and every surface — nothing",

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

@@ -34,6 +34,8 @@
  */
 
 import { execFileSync } from "node:child_process";
+import { existsSync, lstatSync, mkdirSync, rmSync, symlinkSync } from "node:fs";
+import { join } from "node:path";
 
 import {
   AGENTS,
@@ -297,6 +299,84 @@ export function renderPlan(plan) {
  * @param {object} [deps] Injected runner, for tests.
  * @returns {object} Result row.
  */
+/**
+ * Make a tool that installed elsewhere reachable from `~/.local/bin`.
+ *
+ * A vendor script installs where it likes — SonarQube's puts `sonar` under
+ * `~/.local/share/sonarqube-cli/bin` — and the catalogue records that in
+ * `binDir`. Until now the only thing that put those directories on PATH was an
+ * edit to the shell rc files, which a cloud container never reads: its tool
+ * shell is not a login shell. So the tool installed, and the session that asked
+ * for it could not find it. Observed on a live Claude Tag channel, where
+ * `~/.local/share/sonarqube-cli` existed and `command -v sonar` came back empty.
+ *
+ * Exporting PATH from the setup script does not fix that either — those exports
+ * die with the process that ran them. Only the filesystem survives into the
+ * session, so the fix has to be a file.
+ *
+ * A symlink into `~/.local/bin` is the shape the AWS installer already uses
+ * (`aws -> ~/.local/aws-cli/v2/current/bin/aws`), and that directory is the one
+ * place every surface agrees is on PATH.
+ *
+ * Deliberately never fatal. A tool that is already reachable does not need the
+ * link, and one that cannot be linked is caught a moment later by the probe —
+ * which reports the real problem instead of a symlink error standing in for it.
+ * @param {object} entry Catalogue entry just installed.
+ * @param {object} [deps] Injected seams, for tests.
+ */
+export function linkIntoBinDir(entry, deps = {}) {
+  if (!entry.binDir) return;
+
+  const home = deps.home ?? process.env.HOME ?? "";
+  const link = deps.link ?? symlinkSync;
+  const exists = deps.exists ?? existsSync;
+  const remove = deps.remove ?? rmSync;
+  const makeDir = deps.mkdir ?? mkdirSync;
+  // Two different questions, and they need two different probes.
+  //
+  // The SOURCE must be followed: a link pointing at a binary that is not there
+  // means the install did not produce one, whatever the link says.
+  //
+  // The TARGET must NOT be followed. `existsSync` reports false for a dangling
+  // symlink, which is precisely the case this function claims to repair — the
+  // vendor moved and the old link now points at nothing. Following it would
+  // skip the removal, `symlinkSync` would throw EEXIST, the catch below would
+  // swallow it, and the broken link would survive the fix meant to replace it.
+  const present = deps.present ?? (path => lstatPresent(path));
+
+  const source = join(
+    entry.binDir.replace(/^~/, home),
+    entry.binary ?? entry.name
+  );
+  const target = join(home, ".local", "bin", entry.name);
+  if (source === target || !exists(source)) return;
+
+  try {
+    makeDir(join(home, ".local", "bin"), { recursive: true });
+    // Replaced rather than skipped-if-present: a stale link left by an earlier
+    // version pointing at a path the vendor has since moved is worse than none,
+    // because it resolves and then fails at the moment of use.
+    if (present(target)) remove(target, { force: true });
+    link(source, target);
+  } catch {
+    // See above: the probe is the authority on whether this worked.
+  }
+}
+
+/**
+ * Whether a path exists WITHOUT following it, so a dangling link counts.
+ * @param {string} path Path to inspect.
+ * @returns {boolean} True when something occupies the path.
+ */
+function lstatPresent(path) {
+  try {
+    lstatSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export function installEntry(entry, row, deps = {}) {
   const run =
     deps.run ??
@@ -398,6 +478,10 @@ export function installEntry(entry, row, deps = {}) {
     };
   }
 
+  // Link it into ~/.local/bin BEFORE probing, because that is what makes the
+  // probe meaningful for a tool the vendor put somewhere else.
+  linkIntoBinDir(entry, deps);
+
   // Verify by looking, not by exit status. Every installer above can exit 0
   // having installed nothing, so a claim of success is only as good as a fresh
   // probe — reporting a tool as installed when it is absent is worse than

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

@@ -12,11 +12,26 @@ 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; tt=0; ts=0; tp=0; npx -y @codyswann/lisa@2.338.0 workstation --install --agents=none --tools=none --provider="${LISA_PROVIDER:-${LISA_SECRETS_PROVIDER:-bitwarden}}" || tw=$?; export PATH="$HOME/.local/bin:$HOME/.opencode/bin:$HOME/.local/share/sonarqube-cli/bin:$PATH"; npx -y @codyswann/lisa@2.338.0 remote-env --phase=secrets || ts=$?; w=$(npx -y @codyswann/lisa@2.338.0 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.338.0 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"
+**Ask for that line; do not copy it from here.**
+
+```bash
+npx -y @codyswann/lisa@latest remote-env --emit=claude-web
 ```
 
+The field pins the exact Lisa it runs, and the emitter reads that version from
+the package it is running out of — so the line it prints is always pinned to the
+version that printed it.
+
+A copy written into this file cannot have that property. It is a snapshot taken
+when the package was *built*, and the release bumps the version *after* the
+build, so a published tarball's copy names the previous release. That is not a
+cosmetic lag: the pinned version predates whatever this file documents, so a
+pasted copy can call flags that version does not implement. Measured on
+`2.338.1`, whose embedded copy named `2.338.0` — a Lisa with no `--print-tools`,
+no `--tools`, and no `tools-from-notes.mjs`. Unknown flags are ignored rather
+than rejected, so it did not fail; it installed the full catalogue and re-ran the
+whole setup, three times over, inside a five-minute budget.
+
 **That line is identical for every project AND every surface.** Nothing in it names the
 repository or the package manager, so it can be pasted unchanged anywhere.
 
@@ -236,8 +251,10 @@ When emitting, produce exactly:
 ```text
 Environment name:  <project> remote executor
 Repository:        <org>/<repo>        (must be the default checkout)
-Setup script:      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"
-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"
+Setup script:      <printed by `remote-env --emit`; never copied
+                   from prose, so its pin is always the version
+                   that printed it>
+Maintenance:       <same line, printed by the same command>
                    (identical for every project — the script finds the
                    checkout and installs from the committed lockfile)
 Environment vars:  LISA_SECRETS_SURFACE=codex-cloud

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

@@ -912,6 +912,21 @@ export function emitClaudeWeb({ bootstrapKey }) {
     "    is why exactly one value needs to live here.",
     "",
     "  Setup script:",
+    "",
+    "    A setup script sees NONE of the variables configured above — it runs",
+    "    while the image is being built, before the environment exists. So a",
+    "    session with no checkout has to be told its tenant inside the script",
+    "    itself, or the field finds nothing to prepare and exits 0 looking like",
+    "    success. Put these three lines FIRST, then the line after them:",
+    "",
+    "      export LISA_TENANT=<your namespace>",
+    `      export ${key}='<the same value as above>'`,
+    "      export LISA_SECRETS_SURFACE=claude-web",
+    "",
+    "    LISA_SECRETS_SURFACE is set explicitly rather than left to detection:",
+    "    detection keys off CLAUDE_CODE_REMOTE, and a surface that does not set",
+    "    it falls through to `local`, which writes no credentials to disk at all.",
+    "",
     `    ${SETUP_FIELD}`,
     "",
     "    This line is identical for every project and every surface — nothing",

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

@@ -34,6 +34,8 @@
  */
 
 import { execFileSync } from "node:child_process";
+import { existsSync, lstatSync, mkdirSync, rmSync, symlinkSync } from "node:fs";
+import { join } from "node:path";
 
 import {
   AGENTS,
@@ -297,6 +299,84 @@ export function renderPlan(plan) {
  * @param {object} [deps] Injected runner, for tests.
  * @returns {object} Result row.
  */
+/**
+ * Make a tool that installed elsewhere reachable from `~/.local/bin`.
+ *
+ * A vendor script installs where it likes — SonarQube's puts `sonar` under
+ * `~/.local/share/sonarqube-cli/bin` — and the catalogue records that in
+ * `binDir`. Until now the only thing that put those directories on PATH was an
+ * edit to the shell rc files, which a cloud container never reads: its tool
+ * shell is not a login shell. So the tool installed, and the session that asked
+ * for it could not find it. Observed on a live Claude Tag channel, where
+ * `~/.local/share/sonarqube-cli` existed and `command -v sonar` came back empty.
+ *
+ * Exporting PATH from the setup script does not fix that either — those exports
+ * die with the process that ran them. Only the filesystem survives into the
+ * session, so the fix has to be a file.
+ *
+ * A symlink into `~/.local/bin` is the shape the AWS installer already uses
+ * (`aws -> ~/.local/aws-cli/v2/current/bin/aws`), and that directory is the one
+ * place every surface agrees is on PATH.
+ *
+ * Deliberately never fatal. A tool that is already reachable does not need the
+ * link, and one that cannot be linked is caught a moment later by the probe —
+ * which reports the real problem instead of a symlink error standing in for it.
+ * @param {object} entry Catalogue entry just installed.
+ * @param {object} [deps] Injected seams, for tests.
+ */
+export function linkIntoBinDir(entry, deps = {}) {
+  if (!entry.binDir) return;
+
+  const home = deps.home ?? process.env.HOME ?? "";
+  const link = deps.link ?? symlinkSync;
+  const exists = deps.exists ?? existsSync;
+  const remove = deps.remove ?? rmSync;
+  const makeDir = deps.mkdir ?? mkdirSync;
+  // Two different questions, and they need two different probes.
+  //
+  // The SOURCE must be followed: a link pointing at a binary that is not there
+  // means the install did not produce one, whatever the link says.
+  //
+  // The TARGET must NOT be followed. `existsSync` reports false for a dangling
+  // symlink, which is precisely the case this function claims to repair — the
+  // vendor moved and the old link now points at nothing. Following it would
+  // skip the removal, `symlinkSync` would throw EEXIST, the catch below would
+  // swallow it, and the broken link would survive the fix meant to replace it.
+  const present = deps.present ?? (path => lstatPresent(path));
+
+  const source = join(
+    entry.binDir.replace(/^~/, home),
+    entry.binary ?? entry.name
+  );
+  const target = join(home, ".local", "bin", entry.name);
+  if (source === target || !exists(source)) return;
+
+  try {
+    makeDir(join(home, ".local", "bin"), { recursive: true });
+    // Replaced rather than skipped-if-present: a stale link left by an earlier
+    // version pointing at a path the vendor has since moved is worse than none,
+    // because it resolves and then fails at the moment of use.
+    if (present(target)) remove(target, { force: true });
+    link(source, target);
+  } catch {
+    // See above: the probe is the authority on whether this worked.
+  }
+}
+
+/**
+ * Whether a path exists WITHOUT following it, so a dangling link counts.
+ * @param {string} path Path to inspect.
+ * @returns {boolean} True when something occupies the path.
+ */
+function lstatPresent(path) {
+  try {
+    lstatSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export function installEntry(entry, row, deps = {}) {
   const run =
     deps.run ??
@@ -398,6 +478,10 @@ export function installEntry(entry, row, deps = {}) {
     };
   }
 
+  // Link it into ~/.local/bin BEFORE probing, because that is what makes the
+  // probe meaningful for a tool the vendor put somewhere else.
+  linkIntoBinDir(entry, deps);
+
   // Verify by looking, not by exit status. Every installer above can exit 0
   // having installed nothing, so a claim of success is only as good as a fresh
   // probe — reporting a tool as installed when it is absent is worse than

package/plugins/lisa-agy/plugin.json

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

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

@@ -12,11 +12,26 @@ 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; tt=0; ts=0; tp=0; npx -y @codyswann/lisa@2.338.0 workstation --install --agents=none --tools=none --provider="${LISA_PROVIDER:-${LISA_SECRETS_PROVIDER:-bitwarden}}" || tw=$?; export PATH="$HOME/.local/bin:$HOME/.opencode/bin:$HOME/.local/share/sonarqube-cli/bin:$PATH"; npx -y @codyswann/lisa@2.338.0 remote-env --phase=secrets || ts=$?; w=$(npx -y @codyswann/lisa@2.338.0 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.338.0 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"
+**Ask for that line; do not copy it from here.**
+
+```bash
+npx -y @codyswann/lisa@latest remote-env --emit=claude-web
 ```
 
+The field pins the exact Lisa it runs, and the emitter reads that version from
+the package it is running out of — so the line it prints is always pinned to the
+version that printed it.
+
+A copy written into this file cannot have that property. It is a snapshot taken
+when the package was *built*, and the release bumps the version *after* the
+build, so a published tarball's copy names the previous release. That is not a
+cosmetic lag: the pinned version predates whatever this file documents, so a
+pasted copy can call flags that version does not implement. Measured on
+`2.338.1`, whose embedded copy named `2.338.0` — a Lisa with no `--print-tools`,
+no `--tools`, and no `tools-from-notes.mjs`. Unknown flags are ignored rather
+than rejected, so it did not fail; it installed the full catalogue and re-ran the
+whole setup, three times over, inside a five-minute budget.
+
 **That line is identical for every project AND every surface.** Nothing in it names the
 repository or the package manager, so it can be pasted unchanged anywhere.
 
@@ -236,8 +251,10 @@ When emitting, produce exactly:
 ```text
 Environment name:  <project> remote executor
 Repository:        <org>/<repo>        (must be the default checkout)
-Setup script:      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"
-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"
+Setup script:      <printed by `remote-env --emit`; never copied
+                   from prose, so its pin is always the version
+                   that printed it>
+Maintenance:       <same line, printed by the same command>
                    (identical for every project — the script finds the
                    checkout and installs from the committed lockfile)
 Environment vars:  LISA_SECRETS_SURFACE=codex-cloud

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

@@ -912,6 +912,21 @@ export function emitClaudeWeb({ bootstrapKey }) {
     "    is why exactly one value needs to live here.",
     "",
     "  Setup script:",
+    "",
+    "    A setup script sees NONE of the variables configured above — it runs",
+    "    while the image is being built, before the environment exists. So a",
+    "    session with no checkout has to be told its tenant inside the script",
+    "    itself, or the field finds nothing to prepare and exits 0 looking like",
+    "    success. Put these three lines FIRST, then the line after them:",
+    "",
+    "      export LISA_TENANT=<your namespace>",
+    `      export ${key}='<the same value as above>'`,
+    "      export LISA_SECRETS_SURFACE=claude-web",
+    "",
+    "    LISA_SECRETS_SURFACE is set explicitly rather than left to detection:",
+    "    detection keys off CLAUDE_CODE_REMOTE, and a surface that does not set",
+    "    it falls through to `local`, which writes no credentials to disk at all.",
+    "",
     `    ${SETUP_FIELD}`,
     "",
     "    This line is identical for every project and every surface — nothing",

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

@@ -34,6 +34,8 @@
  */
 
 import { execFileSync } from "node:child_process";
+import { existsSync, lstatSync, mkdirSync, rmSync, symlinkSync } from "node:fs";
+import { join } from "node:path";
 
 import {
   AGENTS,
@@ -297,6 +299,84 @@ export function renderPlan(plan) {
  * @param {object} [deps] Injected runner, for tests.
  * @returns {object} Result row.
  */
+/**
+ * Make a tool that installed elsewhere reachable from `~/.local/bin`.
+ *
+ * A vendor script installs where it likes — SonarQube's puts `sonar` under
+ * `~/.local/share/sonarqube-cli/bin` — and the catalogue records that in
+ * `binDir`. Until now the only thing that put those directories on PATH was an
+ * edit to the shell rc files, which a cloud container never reads: its tool
+ * shell is not a login shell. So the tool installed, and the session that asked
+ * for it could not find it. Observed on a live Claude Tag channel, where
+ * `~/.local/share/sonarqube-cli` existed and `command -v sonar` came back empty.
+ *
+ * Exporting PATH from the setup script does not fix that either — those exports
+ * die with the process that ran them. Only the filesystem survives into the
+ * session, so the fix has to be a file.
+ *
+ * A symlink into `~/.local/bin` is the shape the AWS installer already uses
+ * (`aws -> ~/.local/aws-cli/v2/current/bin/aws`), and that directory is the one
+ * place every surface agrees is on PATH.
+ *
+ * Deliberately never fatal. A tool that is already reachable does not need the
+ * link, and one that cannot be linked is caught a moment later by the probe —
+ * which reports the real problem instead of a symlink error standing in for it.
+ * @param {object} entry Catalogue entry just installed.
+ * @param {object} [deps] Injected seams, for tests.
+ */
+export function linkIntoBinDir(entry, deps = {}) {
+  if (!entry.binDir) return;
+
+  const home = deps.home ?? process.env.HOME ?? "";
+  const link = deps.link ?? symlinkSync;
+  const exists = deps.exists ?? existsSync;
+  const remove = deps.remove ?? rmSync;
+  const makeDir = deps.mkdir ?? mkdirSync;
+  // Two different questions, and they need two different probes.
+  //
+  // The SOURCE must be followed: a link pointing at a binary that is not there
+  // means the install did not produce one, whatever the link says.
+  //
+  // The TARGET must NOT be followed. `existsSync` reports false for a dangling
+  // symlink, which is precisely the case this function claims to repair — the
+  // vendor moved and the old link now points at nothing. Following it would
+  // skip the removal, `symlinkSync` would throw EEXIST, the catch below would
+  // swallow it, and the broken link would survive the fix meant to replace it.
+  const present = deps.present ?? (path => lstatPresent(path));
+
+  const source = join(
+    entry.binDir.replace(/^~/, home),
+    entry.binary ?? entry.name
+  );
+  const target = join(home, ".local", "bin", entry.name);
+  if (source === target || !exists(source)) return;
+
+  try {
+    makeDir(join(home, ".local", "bin"), { recursive: true });
+    // Replaced rather than skipped-if-present: a stale link left by an earlier
+    // version pointing at a path the vendor has since moved is worse than none,
+    // because it resolves and then fails at the moment of use.
+    if (present(target)) remove(target, { force: true });
+    link(source, target);
+  } catch {
+    // See above: the probe is the authority on whether this worked.
+  }
+}
+
+/**
+ * Whether a path exists WITHOUT following it, so a dangling link counts.
+ * @param {string} path Path to inspect.
+ * @returns {boolean} True when something occupies the path.
+ */
+function lstatPresent(path) {
+  try {
+    lstatSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export function installEntry(entry, row, deps = {}) {
   const run =
     deps.run ??
@@ -398,6 +478,10 @@ export function installEntry(entry, row, deps = {}) {
     };
   }
 
+  // Link it into ~/.local/bin BEFORE probing, because that is what makes the
+  // probe meaningful for a tool the vendor put somewhere else.
+  linkIntoBinDir(entry, deps);
+
   // Verify by looking, not by exit status. Every installer above can exit 0
   // having installed nothing, so a claim of success is only as good as a fresh
   // probe — reporting a tool as installed when it is absent is worse than

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.338.1",
+  "version": "2.338.3",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.338.1",
+  "version": "2.338.3",
   "description": "AWS CDK-specific Lisa plugin.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.338.1",
+  "version": "2.338.3",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.338.1",
+  "version": "2.338.3",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.338.1",
+  "version": "2.338.3",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

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

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