@codyswann/lisa 2.318.0 → 2.320.0

package/plugins/lisa/.codex-plugin/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/skills/lisa-secrets-access/scripts/doctor-secrets.mjs

@@ -47,6 +47,16 @@ function fingerprint(value) {
   return createHash("sha256").update(value).digest("hex").slice(0, 12);
 }
 
+/**
+ * The value a proxied credential reads as instead of a usable token.
+ *
+ * Some surfaces keep a credential outside the sandbox entirely and substitute
+ * the real value at egress. The variable is then present and non-empty, which
+ * is exactly what makes it dangerous: a presence check passes, and only a
+ * consumer that reads the variable *itself* discovers it holds a placeholder.
+ */
+const PROXY_PLACEHOLDER = "proxy-injected";
+
 /**
  * Assert every declared name actually resolves.
  * @param {object} cfg Resolved configuration.
@@ -56,18 +66,36 @@ function fingerprint(value) {
  */
 export function checkRequired(cfg, provider, file, report) {
   for (const name of cfg.require ?? []) {
-    const resolves =
-      (process.env[name] ?? "").trim() ||
-      file.get(name) ||
-      provider.get(name)?.value;
-    if (resolves) report("ok", name, "resolves");
-    else
+    const fromEnv = (process.env[name] ?? "").trim();
+    const resolves = fromEnv || file.get(name) || provider.get(name)?.value;
+
+    if (!resolves) {
       report(
         "error",
         name,
         "declared in secrets.require but resolves nowhere — a startup error, " +
           "not a late surprise"
       );
+      continue;
+    }
+
+    // Reported separately from "resolves" because the two are not the same
+    // claim. A tool that authenticates through the proxy works; a script that
+    // reads this variable and puts it in an Authorization header sends the
+    // literal placeholder and gets a confusing auth failure far from here.
+    if (fromEnv === PROXY_PLACEHOLDER) {
+      report(
+        "warn",
+        name,
+        `reads as the literal string "${PROXY_PLACEHOLDER}" — the value is ` +
+          `substituted at egress and never enters this environment. Tools that ` +
+          `authenticate through the proxy work; anything reading this variable ` +
+          `directly gets the placeholder, not a credential`
+      );
+      continue;
+    }
+
+    report("ok", name, "resolves");
   }
 }
 

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

@@ -28,11 +28,36 @@ import { join } from "node:path";
  * drift and leak. It is *required* on surfaces whose bootstrap runs before the
  * consuming process exists and which therefore have no other channel; a remote
  * agent container prepares itself during setup, long before any task starts.
+ *
+ * `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 },
+  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. */
@@ -68,6 +93,10 @@ export function detectSurface(configured = null, env = process.env) {
     return explicit;
   }
   if ((env.GITHUB_ACTIONS ?? "") === "true") return "github-actions";
+  // Compared to the exact string rather than tested for presence: the variable
+  // is documented as carrying "true" in a cloud session and never being true
+  // locally, so a presence test would misread a shell that exports it empty.
+  if ((env.CLAUDE_CODE_REMOTE ?? "") === "true") return "claude-web";
   if ((env.CODEX_SANDBOX ?? env.CODEX_HOME ?? "") !== "") return "codex-cloud";
   return "local";
 }

package/plugins/lisa/skills/lisa-secrets-access/scripts/validate-config.mjs

@@ -19,14 +19,59 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
+import { SURFACES as SURFACE_CAPABILITIES } from "./surfaces.mjs";
+
 /** Providers with a read implementation today. */
 const IMPLEMENTED_PROVIDERS = new Set(["bitwarden", "doppler", "env"]);
 
 /** Providers named in the dispatch table but not yet implemented. */
 const DECLARED_PROVIDERS = new Set(["1password", "aws", "vault"]);
 
-/** Surfaces the resolver knows. */
-const SURFACES = new Set(["local", "github-actions", "codex-cloud"]);
+/**
+ * Surfaces the resolver knows.
+ *
+ * Derived from the resolver's own table rather than restated here. The two
+ * lists previously drifted apart by construction: adding a surface meant
+ * remembering to edit a second file, and forgetting produced a config that
+ * resolved correctly at runtime while `doctor` called it unknown.
+ */
+const SURFACES = new Set(Object.keys(SURFACE_CAPABILITIES));
+
+/**
+ * What a provisioned surface must record before anything dispatches to it.
+ *
+ * Deliberately not uniform, because these surfaces do not bind the same way. A
+ * Codex Cloud environment is bound to one repository, so naming the repository
+ * is part of proving the environment is the right one. A Claude cloud
+ * environment has no repository at all — it is account-scoped configuration
+ * (network policy, variables, setup script) and the repository arrives per
+ * session — so its durable handle is the routine that dispatch fires.
+ *
+ * Requiring `repository` of every surface, as this file used to, would demand
+ * a field that cannot be true of `claude-web` in any meaningful sense.
+ *
+ * `repository` stays the default so every existing surface keeps its current
+ * contract. This file checks structure only — whether a declaration *could* be
+ * correct — so it deliberately does not restate the fuller preconditions that
+ * `lisa-remote-dispatch` enforces at the moment it actually dispatches.
+ */
+const SURFACE_BINDINGS = {
+  "claude-web": ["routineId", "fireUrl"],
+};
+
+/**
+ * The fields a surface must record, with the default applied.
+ *
+ * Read through one helper rather than at each call site, because the two
+ * callers answer different questions — "could this declaration be correct" and
+ * "may an automation dispatch to it" — and a fallback that drifted between them
+ * would let those answers disagree about the very same config.
+ * @param {string} surface Surface name.
+ * @returns {string[]} Field names that must be present.
+ */
+function bindingsFor(surface) {
+  return SURFACE_BINDINGS[surface] ?? ["repository"];
+}
 
 /** Install methods the toolchain runner supports. */
 const INSTALL_METHODS = new Set(["release-zip", "npm-global"]);
@@ -139,15 +184,30 @@ export function validateRemoteEnv(remoteEnv) {
   for (const [surface, block] of Object.entries(remoteEnv.surfaces ?? {})) {
     if (!SURFACES.has(surface)) {
       problems.push(`remoteEnv.surfaces has unknown surface "${surface}"`);
+      continue;
     }
-    if (!block.repository) {
-      problems.push(`remoteEnv.surfaces["${surface}"] has no repository`);
+    for (const field of bindingsFor(surface)) {
+      if (!block[field]) {
+        problems.push(`remoteEnv.surfaces["${surface}"] has no ${field}`);
+      }
     }
   }
 
   return problems;
 }
 
+/**
+ * Report whether a surface has been provisioned far enough to dispatch to.
+ * @param {object|undefined} remoteEnv The remote-environment block.
+ * @param {string} surface Surface name.
+ * @returns {boolean} Whether every binding field is recorded.
+ */
+export function isProvisioned(remoteEnv, surface) {
+  const block = remoteEnv?.surfaces?.[surface];
+  if (!block) return false;
+  return bindingsFor(surface).every(field => Boolean(block[field]));
+}
+
 /**
  * Validate the `automations` block against declared surfaces.
  * @param {object|undefined} automations The block, if present.
@@ -173,7 +233,7 @@ export function validateAutomations(automations, remoteEnv) {
       );
       continue;
     }
-    if (!remoteEnv?.surfaces?.[loop.executionEnv]?.repository) {
+    if (!isProvisioned(remoteEnv, loop.executionEnv)) {
       problems.push(
         `automations["${name}"] dispatches to "${loop.executionEnv}", which is ` +
           `not provisioned. Run /lisa:setup:remote-env ${loop.executionEnv} first.`

package/plugins/lisa/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,25 @@ 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.
+
+**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 +172,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 +182,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 +192,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/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 "$@"