@codyswann/lisa 2.332.1 → 2.332.3

package/package.json

@@ -115,7 +115,7 @@
     "brace-expansion": ">=5.0.9"
   },
   "name": "@codyswann/lisa",
-  "version": "2.332.1",
+  "version": "2.332.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.332.1",
+  "version": "2.332.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.332.1",
+  "version": "2.332.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/scripts/setup-remote-env.mjs

@@ -38,6 +38,7 @@ import {
   rmSync,
   writeFileSync,
 } from "node:fs";
+import { homedir } from "node:os";
 import { delimiter, dirname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
@@ -583,6 +584,101 @@ export const SETUP_FIELD =
   'PWD=$PWD HOME=$HOME" >&2; ls -1 . "$HOME" /workspace 2>&1 | head -40 >&2; exit 1; }; ' +
   'exit "$rc"';
 
+/**
+ * Register the session-start hook at USER scope, so it fires wherever the
+ * session opens.
+ *
+ * The committed `.claude/settings.json` hook is *project*-scoped: it loads only
+ * when Claude Code's project directory is that repository. A cloud session does
+ * not reliably start there. With several repositories it starts in the shared
+ * parent, which is not a git repository at all; even with one, the checkout sits
+ * at `$HOME/<repo>` while the session may open at `$HOME`. In those sessions no
+ * project settings load, the hook never registers, and nothing materializes —
+ * the failure that `materializeAt: "both"` was introduced to paper over, and
+ * which it could not fix, because the setup phase cannot see the bootstrap
+ * credential in the first place.
+ *
+ * A user-scoped hook has neither problem: `~/.claude/settings.json` is read for
+ * every session regardless of project directory, and it runs in-session where
+ * the vendor's configured variables ARE present.
+ *
+ * Only ever on a remote surface. This writes machine state in an ephemeral
+ * container, which is fine there and would be an intrusion on a developer's
+ * laptop, where the project hook already works and the user owns that file.
+ *
+ * Merged, never clobbered, and idempotent on the exact command — an existing
+ * user settings file may carry hooks this knows nothing about.
+ * @param {string} repoRoot Absolute path to the checkout.
+ * @param {object} options Home directory, dry-run flag, and file seams.
+ * @returns {{action: string, path: string, reason?: string}} What was done.
+ */
+export function installUserSessionHook(repoRoot, options = {}) {
+  const {
+    home = process.env.HOME || homedir(),
+    dryRun = false,
+    exists = existsSync,
+    read = readFileSync,
+    write = writeFileSync,
+    mkdir = mkdirSync,
+  } = options;
+
+  const script = join(repoRoot, "scripts/lisa-remote-env/session-start.sh");
+  if (!exists(script)) {
+    return { action: "skipped", path: script, reason: "no session-start.sh" };
+  }
+
+  const dir = join(home, ".claude");
+  const settingsPath = join(dir, "settings.json");
+  const command = `bash ${script}`;
+
+  let settings = {};
+  if (exists(settingsPath)) {
+    try {
+      settings = JSON.parse(String(read(settingsPath, "utf8"))) || {};
+    } catch {
+      // Refuse rather than overwrite. A settings file that does not parse is
+      // still someone's configuration, and replacing it would be the careless
+      // destruction this whole function is written to avoid.
+      return {
+        action: "failed",
+        path: settingsPath,
+        reason: "existing settings.json is not valid JSON; left untouched",
+      };
+    }
+  }
+
+  const hooks = settings.hooks ?? {};
+  const sessionStart = Array.isArray(hooks.SessionStart)
+    ? hooks.SessionStart
+    : [];
+  const already = sessionStart.some(entry =>
+    (entry?.hooks ?? []).some(hook => hook?.command === command)
+  );
+  if (already) {
+    return { action: "present", path: settingsPath };
+  }
+
+  const updated = {
+    ...settings,
+    hooks: {
+      ...hooks,
+      SessionStart: [
+        ...sessionStart,
+        {
+          matcher: "startup|resume",
+          hooks: [{ type: "command", command }],
+        },
+      ],
+    },
+  };
+
+  if (dryRun) return { action: "would-register", path: settingsPath };
+
+  mkdir(dir, { recursive: true });
+  write(settingsPath, `${JSON.stringify(updated, null, 2)}\n`);
+  return { action: "registered", path: settingsPath };
+}
+
 /**
  * The settings block that wires the session-start hook into a repository.
  *
@@ -914,9 +1010,58 @@ async function main() {
       "lisa-secrets-access",
       "materialize-secrets.mjs"
     );
-    execFileSync("node", dryRun ? [materialize, "--dry-run"] : [materialize], {
-      stdio: "inherit",
-    });
+    // A failure here is fatal only when nothing else will try again.
+    //
+    // On a surface that materializes at BOTH setup and session start, this run
+    // is the floor and the hook is the authority. The two run in different
+    // environments: a cloud vendor can expose its configured variables to the
+    // agent session while the setup phase — which runs earlier, during image
+    // construction — never sees them. That is not an error state, it is the
+    // normal shape of `materializeAt: "both"`, and the hook materializes
+    // correctly moments later.
+    //
+    // Treating it as fatal cost an entire environment: setup.sh `exec`s this
+    // script, so a non-zero exit fails the vendor's setup step and Claude Code
+    // never starts at all. Trading "secrets arrive one phase later" for "the
+    // container will not boot" is a bad trade, and it regressed a case that
+    // used to work — before this surface materialized at setup, setup simply
+    // never attempted it.
+    //
+    // Every other case keeps the hard failure: an explicit `--phase=secrets`
+    // (the hook's own authoritative run) and a setup-only surface such as
+    // codex-cloud both have no second chance, so a silent pass there would
+    // hand back a session with no credentials and call it ready.
+    const retried = !requested && materializesAtSessionStart(materializeAt);
+
+    // If the hook is what will retry, make sure the hook can actually fire.
+    // Registering it at user scope is what makes the retry real rather than
+    // assumed: the committed project hook does not load when the session opens
+    // above the checkout, which is the norm in a cloud container.
+    // `materializeAt` being set is what "remote surface" means here. The
+    // toolchain phase derives a local `remote` from it, but that binding is
+    // scoped to its own block and is not in scope in this one.
+    if (retried && Boolean(materializeAt)) {
+      const hook = installUserSessionHook(process.cwd(), { dryRun });
+      console.log(`  session-start hook: ${hook.action} (${hook.path})`);
+      if (hook.reason) console.log(`    ${hook.reason}`);
+    }
+    try {
+      execFileSync(
+        "node",
+        dryRun ? [materialize, "--dry-run"] : [materialize],
+        { stdio: "inherit" }
+      );
+    } catch (err) {
+      if (!retried) throw err;
+      console.log(
+        `\n  Secrets were not materialized during setup, and that is not fatal ` +
+          `here.\n  This surface also materializes at session start, which runs ` +
+          `with the\n  session's own environment — the usual reason setup cannot ` +
+          `see the\n  bootstrap credential. The session-start hook will retry.\n` +
+          `  If secrets are still missing INSIDE a session, that run is the one ` +
+          `to debug.`
+      );
+    }
   } else if (!requested) {
     console.log(
       `\nSecrets: materialized from a session-start hook on "${surface}", ` +

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

@@ -38,6 +38,7 @@ import {
   rmSync,
   writeFileSync,
 } from "node:fs";
+import { homedir } from "node:os";
 import { delimiter, dirname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
@@ -583,6 +584,101 @@ export const SETUP_FIELD =
   'PWD=$PWD HOME=$HOME" >&2; ls -1 . "$HOME" /workspace 2>&1 | head -40 >&2; exit 1; }; ' +
   'exit "$rc"';
 
+/**
+ * Register the session-start hook at USER scope, so it fires wherever the
+ * session opens.
+ *
+ * The committed `.claude/settings.json` hook is *project*-scoped: it loads only
+ * when Claude Code's project directory is that repository. A cloud session does
+ * not reliably start there. With several repositories it starts in the shared
+ * parent, which is not a git repository at all; even with one, the checkout sits
+ * at `$HOME/<repo>` while the session may open at `$HOME`. In those sessions no
+ * project settings load, the hook never registers, and nothing materializes —
+ * the failure that `materializeAt: "both"` was introduced to paper over, and
+ * which it could not fix, because the setup phase cannot see the bootstrap
+ * credential in the first place.
+ *
+ * A user-scoped hook has neither problem: `~/.claude/settings.json` is read for
+ * every session regardless of project directory, and it runs in-session where
+ * the vendor's configured variables ARE present.
+ *
+ * Only ever on a remote surface. This writes machine state in an ephemeral
+ * container, which is fine there and would be an intrusion on a developer's
+ * laptop, where the project hook already works and the user owns that file.
+ *
+ * Merged, never clobbered, and idempotent on the exact command — an existing
+ * user settings file may carry hooks this knows nothing about.
+ * @param {string} repoRoot Absolute path to the checkout.
+ * @param {object} options Home directory, dry-run flag, and file seams.
+ * @returns {{action: string, path: string, reason?: string}} What was done.
+ */
+export function installUserSessionHook(repoRoot, options = {}) {
+  const {
+    home = process.env.HOME || homedir(),
+    dryRun = false,
+    exists = existsSync,
+    read = readFileSync,
+    write = writeFileSync,
+    mkdir = mkdirSync,
+  } = options;
+
+  const script = join(repoRoot, "scripts/lisa-remote-env/session-start.sh");
+  if (!exists(script)) {
+    return { action: "skipped", path: script, reason: "no session-start.sh" };
+  }
+
+  const dir = join(home, ".claude");
+  const settingsPath = join(dir, "settings.json");
+  const command = `bash ${script}`;
+
+  let settings = {};
+  if (exists(settingsPath)) {
+    try {
+      settings = JSON.parse(String(read(settingsPath, "utf8"))) || {};
+    } catch {
+      // Refuse rather than overwrite. A settings file that does not parse is
+      // still someone's configuration, and replacing it would be the careless
+      // destruction this whole function is written to avoid.
+      return {
+        action: "failed",
+        path: settingsPath,
+        reason: "existing settings.json is not valid JSON; left untouched",
+      };
+    }
+  }
+
+  const hooks = settings.hooks ?? {};
+  const sessionStart = Array.isArray(hooks.SessionStart)
+    ? hooks.SessionStart
+    : [];
+  const already = sessionStart.some(entry =>
+    (entry?.hooks ?? []).some(hook => hook?.command === command)
+  );
+  if (already) {
+    return { action: "present", path: settingsPath };
+  }
+
+  const updated = {
+    ...settings,
+    hooks: {
+      ...hooks,
+      SessionStart: [
+        ...sessionStart,
+        {
+          matcher: "startup|resume",
+          hooks: [{ type: "command", command }],
+        },
+      ],
+    },
+  };
+
+  if (dryRun) return { action: "would-register", path: settingsPath };
+
+  mkdir(dir, { recursive: true });
+  write(settingsPath, `${JSON.stringify(updated, null, 2)}\n`);
+  return { action: "registered", path: settingsPath };
+}
+
 /**
  * The settings block that wires the session-start hook into a repository.
  *
@@ -914,9 +1010,58 @@ async function main() {
       "lisa-secrets-access",
       "materialize-secrets.mjs"
     );
-    execFileSync("node", dryRun ? [materialize, "--dry-run"] : [materialize], {
-      stdio: "inherit",
-    });
+    // A failure here is fatal only when nothing else will try again.
+    //
+    // On a surface that materializes at BOTH setup and session start, this run
+    // is the floor and the hook is the authority. The two run in different
+    // environments: a cloud vendor can expose its configured variables to the
+    // agent session while the setup phase — which runs earlier, during image
+    // construction — never sees them. That is not an error state, it is the
+    // normal shape of `materializeAt: "both"`, and the hook materializes
+    // correctly moments later.
+    //
+    // Treating it as fatal cost an entire environment: setup.sh `exec`s this
+    // script, so a non-zero exit fails the vendor's setup step and Claude Code
+    // never starts at all. Trading "secrets arrive one phase later" for "the
+    // container will not boot" is a bad trade, and it regressed a case that
+    // used to work — before this surface materialized at setup, setup simply
+    // never attempted it.
+    //
+    // Every other case keeps the hard failure: an explicit `--phase=secrets`
+    // (the hook's own authoritative run) and a setup-only surface such as
+    // codex-cloud both have no second chance, so a silent pass there would
+    // hand back a session with no credentials and call it ready.
+    const retried = !requested && materializesAtSessionStart(materializeAt);
+
+    // If the hook is what will retry, make sure the hook can actually fire.
+    // Registering it at user scope is what makes the retry real rather than
+    // assumed: the committed project hook does not load when the session opens
+    // above the checkout, which is the norm in a cloud container.
+    // `materializeAt` being set is what "remote surface" means here. The
+    // toolchain phase derives a local `remote` from it, but that binding is
+    // scoped to its own block and is not in scope in this one.
+    if (retried && Boolean(materializeAt)) {
+      const hook = installUserSessionHook(process.cwd(), { dryRun });
+      console.log(`  session-start hook: ${hook.action} (${hook.path})`);
+      if (hook.reason) console.log(`    ${hook.reason}`);
+    }
+    try {
+      execFileSync(
+        "node",
+        dryRun ? [materialize, "--dry-run"] : [materialize],
+        { stdio: "inherit" }
+      );
+    } catch (err) {
+      if (!retried) throw err;
+      console.log(
+        `\n  Secrets were not materialized during setup, and that is not fatal ` +
+          `here.\n  This surface also materializes at session start, which runs ` +
+          `with the\n  session's own environment — the usual reason setup cannot ` +
+          `see the\n  bootstrap credential. The session-start hook will retry.\n` +
+          `  If secrets are still missing INSIDE a session, that run is the one ` +
+          `to debug.`
+      );
+    }
   } else if (!requested) {
     console.log(
       `\nSecrets: materialized from a session-start hook on "${surface}", ` +

package/plugins/lisa-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.332.1",
+  "version": "2.332.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/scripts/setup-remote-env.mjs

@@ -38,6 +38,7 @@ import {
   rmSync,
   writeFileSync,
 } from "node:fs";
+import { homedir } from "node:os";
 import { delimiter, dirname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
@@ -583,6 +584,101 @@ export const SETUP_FIELD =
   'PWD=$PWD HOME=$HOME" >&2; ls -1 . "$HOME" /workspace 2>&1 | head -40 >&2; exit 1; }; ' +
   'exit "$rc"';
 
+/**
+ * Register the session-start hook at USER scope, so it fires wherever the
+ * session opens.
+ *
+ * The committed `.claude/settings.json` hook is *project*-scoped: it loads only
+ * when Claude Code's project directory is that repository. A cloud session does
+ * not reliably start there. With several repositories it starts in the shared
+ * parent, which is not a git repository at all; even with one, the checkout sits
+ * at `$HOME/<repo>` while the session may open at `$HOME`. In those sessions no
+ * project settings load, the hook never registers, and nothing materializes —
+ * the failure that `materializeAt: "both"` was introduced to paper over, and
+ * which it could not fix, because the setup phase cannot see the bootstrap
+ * credential in the first place.
+ *
+ * A user-scoped hook has neither problem: `~/.claude/settings.json` is read for
+ * every session regardless of project directory, and it runs in-session where
+ * the vendor's configured variables ARE present.
+ *
+ * Only ever on a remote surface. This writes machine state in an ephemeral
+ * container, which is fine there and would be an intrusion on a developer's
+ * laptop, where the project hook already works and the user owns that file.
+ *
+ * Merged, never clobbered, and idempotent on the exact command — an existing
+ * user settings file may carry hooks this knows nothing about.
+ * @param {string} repoRoot Absolute path to the checkout.
+ * @param {object} options Home directory, dry-run flag, and file seams.
+ * @returns {{action: string, path: string, reason?: string}} What was done.
+ */
+export function installUserSessionHook(repoRoot, options = {}) {
+  const {
+    home = process.env.HOME || homedir(),
+    dryRun = false,
+    exists = existsSync,
+    read = readFileSync,
+    write = writeFileSync,
+    mkdir = mkdirSync,
+  } = options;
+
+  const script = join(repoRoot, "scripts/lisa-remote-env/session-start.sh");
+  if (!exists(script)) {
+    return { action: "skipped", path: script, reason: "no session-start.sh" };
+  }
+
+  const dir = join(home, ".claude");
+  const settingsPath = join(dir, "settings.json");
+  const command = `bash ${script}`;
+
+  let settings = {};
+  if (exists(settingsPath)) {
+    try {
+      settings = JSON.parse(String(read(settingsPath, "utf8"))) || {};
+    } catch {
+      // Refuse rather than overwrite. A settings file that does not parse is
+      // still someone's configuration, and replacing it would be the careless
+      // destruction this whole function is written to avoid.
+      return {
+        action: "failed",
+        path: settingsPath,
+        reason: "existing settings.json is not valid JSON; left untouched",
+      };
+    }
+  }
+
+  const hooks = settings.hooks ?? {};
+  const sessionStart = Array.isArray(hooks.SessionStart)
+    ? hooks.SessionStart
+    : [];
+  const already = sessionStart.some(entry =>
+    (entry?.hooks ?? []).some(hook => hook?.command === command)
+  );
+  if (already) {
+    return { action: "present", path: settingsPath };
+  }
+
+  const updated = {
+    ...settings,
+    hooks: {
+      ...hooks,
+      SessionStart: [
+        ...sessionStart,
+        {
+          matcher: "startup|resume",
+          hooks: [{ type: "command", command }],
+        },
+      ],
+    },
+  };
+
+  if (dryRun) return { action: "would-register", path: settingsPath };
+
+  mkdir(dir, { recursive: true });
+  write(settingsPath, `${JSON.stringify(updated, null, 2)}\n`);
+  return { action: "registered", path: settingsPath };
+}
+
 /**
  * The settings block that wires the session-start hook into a repository.
  *
@@ -914,9 +1010,58 @@ async function main() {
       "lisa-secrets-access",
       "materialize-secrets.mjs"
     );
-    execFileSync("node", dryRun ? [materialize, "--dry-run"] : [materialize], {
-      stdio: "inherit",
-    });
+    // A failure here is fatal only when nothing else will try again.
+    //
+    // On a surface that materializes at BOTH setup and session start, this run
+    // is the floor and the hook is the authority. The two run in different
+    // environments: a cloud vendor can expose its configured variables to the
+    // agent session while the setup phase — which runs earlier, during image
+    // construction — never sees them. That is not an error state, it is the
+    // normal shape of `materializeAt: "both"`, and the hook materializes
+    // correctly moments later.
+    //
+    // Treating it as fatal cost an entire environment: setup.sh `exec`s this
+    // script, so a non-zero exit fails the vendor's setup step and Claude Code
+    // never starts at all. Trading "secrets arrive one phase later" for "the
+    // container will not boot" is a bad trade, and it regressed a case that
+    // used to work — before this surface materialized at setup, setup simply
+    // never attempted it.
+    //
+    // Every other case keeps the hard failure: an explicit `--phase=secrets`
+    // (the hook's own authoritative run) and a setup-only surface such as
+    // codex-cloud both have no second chance, so a silent pass there would
+    // hand back a session with no credentials and call it ready.
+    const retried = !requested && materializesAtSessionStart(materializeAt);
+
+    // If the hook is what will retry, make sure the hook can actually fire.
+    // Registering it at user scope is what makes the retry real rather than
+    // assumed: the committed project hook does not load when the session opens
+    // above the checkout, which is the norm in a cloud container.
+    // `materializeAt` being set is what "remote surface" means here. The
+    // toolchain phase derives a local `remote` from it, but that binding is
+    // scoped to its own block and is not in scope in this one.
+    if (retried && Boolean(materializeAt)) {
+      const hook = installUserSessionHook(process.cwd(), { dryRun });
+      console.log(`  session-start hook: ${hook.action} (${hook.path})`);
+      if (hook.reason) console.log(`    ${hook.reason}`);
+    }
+    try {
+      execFileSync(
+        "node",
+        dryRun ? [materialize, "--dry-run"] : [materialize],
+        { stdio: "inherit" }
+      );
+    } catch (err) {
+      if (!retried) throw err;
+      console.log(
+        `\n  Secrets were not materialized during setup, and that is not fatal ` +
+          `here.\n  This surface also materializes at session start, which runs ` +
+          `with the\n  session's own environment — the usual reason setup cannot ` +
+          `see the\n  bootstrap credential. The session-start hook will retry.\n` +
+          `  If secrets are still missing INSIDE a session, that run is the one ` +
+          `to debug.`
+      );
+    }
   } else if (!requested) {
     console.log(
       `\nSecrets: materialized from a session-start hook on "${surface}", ` +

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.332.1",
+  "version": "2.332.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.332.1",
+  "version": "2.332.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.332.1",
+  "version": "2.332.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.332.1",
+  "version": "2.332.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.332.1",
+  "version": "2.332.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.332.1",
+  "version": "2.332.3",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"