@codyswann/lisa 2.319.0 → 2.321.0

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

@@ -22,7 +22,8 @@
  */
 
 import { execFileSync } from "node:child_process";
-import { existsSync, statSync } from "node:fs";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
 
 import { readRemoteEnvConfig } from "./setup-remote-env.mjs";
 import { extractVersion } from "./toolchain.mjs";
@@ -119,6 +120,43 @@ function verifyToolchain(tools) {
   }
 }
 
+/**
+ * Assert that a declared credential is genuinely readable, not a proxy stand-in.
+ *
+ * A surface may keep a credential outside the sandbox entirely and substitute
+ * the real value at egress. The variable is then present and non-empty, so a
+ * presence check passes — and a script that reads the variable and puts it in a
+ * header sends the placeholder and fails somewhere far from here, with an error
+ * that points at the service rather than at the environment.
+ *
+ * Reported without printing any value: the placeholder is compared, and a real
+ * credential is only ever reported as present.
+ *
+ * Takes its reporter as an argument rather than writing to this module's
+ * results array, so the rule can be exercised against a synthetic environment
+ * without a container and without leaking findings between runs.
+ * @param {string[]} required Declared credential names.
+ * @param {Record<string, string|undefined>} env Environment to inspect.
+ * @param {(ok: boolean, label: string, detail: string) => void} report Collector.
+ */
+export function verifyNotProxied(required, env, report) {
+  for (const name of required) {
+    const value = (env[name] ?? "").trim();
+    if (!value) {
+      report(false, `credential ${name}`, "declared but not present");
+      continue;
+    }
+    report(
+      value !== "proxy-injected",
+      `credential ${name}`,
+      value === "proxy-injected"
+        ? 'reads as "proxy-injected" — substituted at egress, so anything ' +
+            "reading this variable directly receives the placeholder"
+        : "present"
+    );
+  }
+}
+
 /**
  * Assert the working tree is clean.
  *
@@ -142,11 +180,28 @@ function verifyCleanCheckout() {
   }
 }
 
+/**
+ * Read the credential names the project declares it needs.
+ * @param {string} [cwd] Repository root.
+ * @returns {string[]} Declared names, or none when unconfigured.
+ */
+function readRequired(cwd = process.cwd()) {
+  const path = join(cwd, ".lisa.config.json");
+  if (!existsSync(path)) return [];
+  const required = JSON.parse(readFileSync(path, "utf8")).secrets?.require;
+  if (required == null) return [];
+  if (!Array.isArray(required)) {
+    throw new Error("secrets.require must be an array when present");
+  }
+  return required;
+}
+
 function main() {
   const cfg = readRemoteEnvConfig();
   const secretsDir = process.argv[2];
 
   verifyToolchain(cfg.tools);
+  verifyNotProxied(readRequired(), process.env, check);
 
   const surface = node([
     new URL(

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

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

package/plugins/lisa-cursor/skills/lisa-secrets-access/scripts/surfaces.mjs

@@ -29,18 +29,35 @@ import { join } from "node:path";
  * consuming process exists and which therefore have no other channel; a remote
  * agent container prepares itself during setup, long before any task starts.
  *
- * The two remote surfaces share the capability but not the timing, and a reader
- * adding a third should not assume otherwise. `codex-cloud` re-runs its setup
- * script when a container resumes, so materializing there picks up a rotated
- * value. `claude-web` *skips* its setup script whenever a filesystem cache
- * exists, so materializing there would strand a rotated value until the cache
- * expired — its materialize step runs from a session-start hook instead.
+ * `materializeAt` — *when* the write happens, for surfaces that do one. The two
+ * remote surfaces share the capability but not the timing, and a reader adding a
+ * third should not assume otherwise. `codex-cloud` re-runs its setup script when
+ * a container resumes, so materializing during setup picks up a rotated value.
+ * `claude-web` *skips* its setup script whenever a filesystem cache exists, so
+ * materializing there would strand a rotated value until the cache expired —
+ * it materializes from a session-start hook instead, which runs every session.
+ *
+ * Stated as a capability rather than inferred from the surface name, so the
+ * setup runner selects its phases from the table instead of branching on which
+ * vendor it happens to be talking to.
  */
 export const SURFACES = {
-  local: { materialized: false, mayWriteValues: false },
-  "github-actions": { materialized: false, mayWriteValues: false },
-  "codex-cloud": { materialized: true, mayWriteValues: true },
-  "claude-web": { materialized: true, mayWriteValues: true },
+  local: { materialized: false, mayWriteValues: false, materializeAt: null },
+  "github-actions": {
+    materialized: false,
+    mayWriteValues: false,
+    materializeAt: null,
+  },
+  "codex-cloud": {
+    materialized: true,
+    mayWriteValues: true,
+    materializeAt: "setup",
+  },
+  "claude-web": {
+    materialized: true,
+    mayWriteValues: true,
+    materializeAt: "session-start",
+  },
 };
 
 /** Config defaults when `.lisa.config.json` carries no `secrets` block. */

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

@@ -39,6 +39,20 @@ Omitting the install does not degrade gracefully. The entrypoint exits before th
 
 Order matters. The toolchain comes first because the secrets step needs the provider CLI it installs. The hook comes last because it is the only part that may assume everything else is ready.
 
+### Which phases run depends on the surface
+
+Not every surface runs all three here, and the reason is worth understanding before changing it.
+
+A surface that **re-runs this script when a container resumes** — Codex Cloud — should materialize during setup. Re-running is exactly what picks up a rotated value, an edited note, or a changed version pin.
+
+A surface that **skips this script whenever a filesystem cache exists** — Claude Code web — must not. Materializing here would write the values once and then never refresh them, so a credential rotated on Tuesday would still be serving Monday's value until the cache expired days later. Those surfaces materialize from a session-start hook instead, which runs every session including a resumed one:
+
+```sh
+bash scripts/lisa-remote-env/session-start.sh   # guard; delegates to --phase=secrets
+```
+
+The selection comes from the surface's `materializeAt` capability in `lisa-secrets-access`, not from its name, so adding a surface does not mean editing a branch. The hook is committed to the repository, so it also fires on a developer's machine — it exits `0` immediately there rather than failing, because a correct local session must not look broken.
+
 ## Toolchain manifest — two entry kinds
 
 ```json
@@ -131,6 +145,37 @@ Environment vars:  LISA_SECRETS_SURFACE=codex-cloud
                    maintenance both run before task secrets exist>
 ```
 
+### Claude Code web is emit-only, and that is not a fallback
+
+**For Claude Code web there is no tier 1 or tier 2 to fall back from.** A cloud environment is account-scoped configuration — network access level, environment variables, setup script — edited only in the environment selector at claude.ai/code, which has no settings page, no direct URL, and no API. `/remote-env` selects an environment; it cannot create or edit one.
+
+Note what this surface's environment is *not*: it carries no repository. The repository arrives per session, so an environment is reusable across every project, and there is nothing to bind. Its durable handle is the routine that dispatch fires, which is why `remoteEnv.surfaces["claude-web"]` records `routineId` and `fireUrl` rather than a repository.
+
+Generate the exact text to paste:
+
+```sh
+node scripts/setup-remote-env.mjs --emit=claude-web
+```
+
+It reads the project's own install command from its lockfile and the bootstrap name from `secrets.bootstrap.key`, then emits the environment fields, the `.claude/settings.json` hook block, and the two base-image surprises worth knowing before they cost an afternoon:
+
+- **`gh` is not pre-installed.** If the project's flows shell out to it, add it to `remoteEnv.tools.install`, pinned and checksummed like anything else.
+- **A proxied credential reads as the literal string `proxy-injected`.** Tools that authenticate through the GitHub proxy work; a script that reads the variable directly gets the placeholder. The read-back asserts this rather than leaving it to be discovered against a live service.
+
+### One environment per project, pinned locally
+
+An environment is **not** bound to a repository — the repository arrives per session, and one environment is technically reusable across all of them. Give each project its own anyway, because an environment's *contents* are project-shaped: its setup script is a repository-relative path and its bootstrap is scoped to that project's secrets. Pointing one project's session at another's environment runs a setup script that may not exist there, and a setup script that exits non-zero means the session never starts.
+
+`/remote-env` writes `remote.defaultEnvironmentId` into **user** settings, which is one value for the whole machine — wrong as soon as a developer has two projects. Pin it per project instead:
+
+```sh
+node scripts/setup-remote-env.mjs --install --pin-env=<environment-id>
+```
+
+That writes `.claude/settings.local.json`, which outranks user settings and is gitignored — correct on both counts, since an environment belongs to one developer's account and is meaningless in someone else's checkout. Existing keys in that file are merged, not replaced; it commonly holds permission grants worth keeping.
+
+**Only the bootstrap belongs in the environment-variable box.** Values there are stored as plain text and are readable by anyone who uses the environment — on an organization-shared environment, that is every member of the organization. Everything else is materialized by the session-start hook. There is no dedicated secrets store on this surface, and personal versus shared environments cannot be told apart programmatically, so this one is a rule the operator upholds rather than something the tooling can enforce.
+
 ## Verification is tier-independent
 
 **Whatever tier provisioned it, the same read-back proves it.** Trust comes from the verify, not the mechanism — which is what makes emit-tier as trustworthy as API-tier.
@@ -139,7 +184,9 @@ Environment vars:  LISA_SECRETS_SURFACE=codex-cloud
 scripts/verify-remote-env.mjs [SECRETS_DIR]
 ```
 
-Asserts, without printing a value: each declared tool at its pinned or minimum version, the detected surface, the secrets directory at mode `0700`, both files at mode `0600`, and a clean checkout.
+Asserts, without printing a value: each declared tool at its pinned or minimum version, the detected surface, the secrets directory at mode `0700`, both files at mode `0600`, a clean checkout, and that every name in `secrets.require` resolves to a real credential rather than a proxy placeholder.
+
+That last one exists because presence is a weaker claim than usability. A credential the surface keeps outside the sandbox and substitutes at egress is present and non-empty, so a presence check passes — and a script that reads the variable and puts it in a header sends the placeholder and fails against the service, with an error pointing anywhere but at the environment.
 
 **Never verify against vendor UI state.** On 2026-08-01 a Codex environments table reported zero tasks for an environment that had demonstrably completed one, because the task records carried a null environment identifier and the `--env` filter was correspondingly unreliable. Reconcile through durable identifiers only.
 
@@ -147,7 +194,7 @@ Asserts, without printing a value: each declared tool at its pinned or minimum v
 
 Checked when setup runs, not at 3am:
 
-- the environment exists and is bound to **this** repository as its default checkout;
+- the environment exists, and on a surface that binds one, is bound to **this** repository as its default checkout — Claude cloud environments bind no repository at all, so there is nothing to check there;
 - the bootstrap credential resolves;
 - either a checkout-local Lisa skill is present, or the project dependency install has made the pinned `@codyswann/lisa` package available under `node_modules`.
 
@@ -157,6 +204,8 @@ Fail with a message naming what is missing. Never provision-and-hope.
 
 On Codex Cloud the bootstrap must be an **environment variable, not a task secret**: setup runs on a new container and maintenance runs on cache resume, both before task secrets exist. The tradeoff is that the variable remains visible during the task, so compensate by keeping the machine account narrowly scoped and instructing the task never to inspect or use it.
 
+On Claude Code web the same placement applies for the same reason, with the exposure widened rather than narrowed: there is no secrets store, values are stored as plain text, and anyone who uses the environment can read them. On an organization-shared environment that is every member. Keep the bootstrap in a **personal** environment, scope the machine account to the minimum, and treat every other credential as something the session-start hook materializes rather than something a human pastes.
+
 ## Related
 
 - `lisa-secrets-access` — owns every part of the secrets contract this skill composes with.

package/plugins/lisa-cursor/skills/lisa-setup-remote-env/assets/session-start.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+#
+# Session-start entrypoint for surfaces that materialize secrets per session
+# rather than during environment setup.
+#
+# Wired into the repository's `.claude/settings.json` as a SessionStart hook,
+# so it is part of the clone and runs on every session — including a session
+# resumed onto a cached environment, which is the case that matters.
+#
+# Why this exists at all: a cloud environment's setup script is skipped whenever
+# a filesystem cache exists. Materializing there would write the values once and
+# never refresh them, so a rotated credential would stay stale until the cache
+# expired days later. This hook runs every session, so the copy on disk is
+# always the provider's current view.
+#
+# It is deliberately a guard and a delegation, not a second implementation. The
+# skill-resolution ladder is subtle enough that two copies would drift, so the
+# real work stays in setup.sh and this file only decides whether to call it.
+set -euo pipefail
+
+# Exit before doing anything on a machine that is not a remote session. The hook
+# is committed to the repository, so it also fires on every local session; the
+# materialize step would correctly refuse there, but failing on a developer's
+# laptop every time they start a session is noise, not a signal.
+if [ "${CLAUDE_CODE_REMOTE:-}" != "true" ]; then
+  exit 0
+fi
+
+here="$(CDPATH='' cd -- "$(dirname -- "$0")" && pwd)"
+exec bash "${here}/setup.sh" --phase=secrets "$@"