@codyswann/lisa 2.319.0 → 2.320.0

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 "$@"

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

@@ -5,15 +5,26 @@
  * This is the script a remote environment's setup **and** maintenance fields
  * call. They are the same script on purpose. A container may be built fresh or
  * resumed from cache, and every step here is idempotent and version-aware, so
- * running it twice is correct and running it on resume is what picks up a
- * rotated value, an edited note, or a changed version pin.
+ * running it twice is correct.
  *
  * Order matters. The toolchain comes first because the secrets step needs the
  * provider CLI that the toolchain installs. The project hook comes last because
  * it is the only part that may assume everything else is ready.
  *
+ * **Which phases run depends on the surface, and the reason is not cosmetic.**
+ * On a surface that re-runs this script when a container resumes, materializing
+ * here is what picks up a rotated value. On a surface that *skips* it whenever a
+ * filesystem cache exists, materializing here would write the value once and
+ * then never refresh it — a rotated credential would stay stale until the cache
+ * expired. Those surfaces materialize from a session-start hook instead, which
+ * runs every session including resumed ones, and `--phase=secrets` is how that
+ * hook re-enters this file.
+ *
+ * The selection comes from the surface's `materializeAt` capability rather than
+ * from its name, so adding a surface does not mean editing a branch here.
+ *
  * Usage:
- *   setup-remote-env.mjs [--dry-run]
+ *   setup-remote-env.mjs [--dry-run] [--phase=toolchain|secrets|hook]
  * @module setup-remote-env
  */
 
@@ -26,7 +37,7 @@ import {
   rmSync,
 } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { assertPinned, extractVersion, planToolchain } from "./toolchain.mjs";
 
@@ -197,31 +208,252 @@ function runHook(hook, dryRun) {
   execFileSync("bash", [path], { stdio: "inherit" });
 }
 
-function main() {
+/** Phases this runner can execute, in the order they must happen. */
+const PHASES = ["toolchain", "secrets", "hook"];
+
+/**
+ * The settings block that wires the session-start hook into a repository.
+ *
+ * Emitted rather than written, because `.claude/settings.json` belongs to the
+ * project: it may already carry hooks, and merging someone else's file from
+ * here is how a careless tool destroys a configuration it did not understand.
+ */
+const SESSION_START_BLOCK = `{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \\"$CLAUDE_PROJECT_DIR\\"/scripts/lisa-remote-env/session-start.sh"
+          }
+        ]
+      }
+    ]
+  }
+}`;
+
+/**
+ * Produce the configuration a human pastes to provision a Claude cloud surface.
+ *
+ * This surface has no API tier and no console tier to fall back to: a Claude
+ * cloud environment is configured only in the environment dialog, which has no
+ * settings page, no direct URL, and no endpoint. Emit is not a degraded option
+ * here, it is the only one — so the read-back in `verify-remote-env.mjs` is
+ * what makes the result trustworthy, exactly as it would be at any other tier.
+ * @param {{bootstrapKey: string|null, install: string}} options Project details.
+ * @returns {string} Text to show the operator.
+ */
+export function emitClaudeWeb({ bootstrapKey, install }) {
+  const key = bootstrapKey ?? "<secrets.bootstrap.key is not configured>";
+  return [
+    "Provisioning tier: EMIT — and for this surface that is the only tier.",
+    "  A Claude cloud environment is account-scoped configuration edited in the",
+    "  environment selector at claude.ai/code. There is no settings page, no",
+    "  direct URL and no API, so nothing here can provision it for you.",
+    "",
+    "Paste into the environment dialog",
+    "---------------------------------",
+    "  Network access:  Trusted, or Custom plus any host your project needs",
+    "",
+    "  Environment variables:",
+    `    ${key}=<read this from your credential manager>`,
+    "",
+    "    Only the bootstrap belongs in this box. Values here 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 org. Every",
+    "    other credential is materialized by the session-start hook below, which",
+    "    is why exactly one value needs to live here.",
+    "",
+    "  Setup script:",
+    `    ${install} && bash scripts/lisa-remote-env/setup.sh`,
+    "",
+    "    The install must come first. On a fresh container node_modules is the",
+    "    only copy of the Lisa skills present, because Claude receives them as",
+    "    an installed plugin rather than as part of the clone.",
+    "",
+    "Commit to the repository",
+    "------------------------",
+    "  scripts/lisa-remote-env/session-start.sh   (from this skill's assets)",
+    "",
+    "  .claude/settings.json — merge this into any hooks already there:",
+    SESSION_START_BLOCK.split("\n")
+      .map(line => `    ${line}`)
+      .join("\n"),
+    "",
+    "    The setup script is skipped whenever a cached environment exists, so",
+    "    secrets are materialized from this hook instead. It runs every session,",
+    "    including a resumed one, which is what keeps a rotated value current.",
+    "",
+    "Worth knowing about this base image",
+    "-----------------------------------",
+    "  The GitHub CLI is not pre-installed. If this project's flows shell out to",
+    "  `gh`, add it to remoteEnv.tools.install with a pinned version and",
+    "  checksum, the same as any other tool.",
+    "",
+    "  A credential handled by the GitHub proxy reads as the literal string",
+    '  "proxy-injected" inside the session. Tools that authenticate through the',
+    "  proxy work; a script that reads the variable itself gets the placeholder.",
+    "",
+    "Then prove it",
+    "-------------",
+    "  Start a session and run the read-back. Whatever provisioned an",
+    "  environment, the same verify is what makes it trustworthy:",
+    "    node node_modules/@codyswann/lisa/plugins/lisa/skills/lisa-setup-remote-env/scripts/verify-remote-env.mjs",
+  ].join("\n");
+}
+
+/**
+ * Decide which phases this invocation runs.
+ *
+ * An explicit `--phase` always wins, because that is how a session-start hook
+ * asks for the one phase it owns. Otherwise every phase runs except a secrets
+ * step that belongs to a different moment on this surface — running it here
+ * would produce a copy that the surface never refreshes.
+ * @param {string|undefined} requested Value of `--phase`, when given.
+ * @param {string|null} materializeAt When this surface materializes.
+ * @returns {string[]} Phases to run, in order.
+ */
+export function selectPhases(requested, materializeAt) {
+  if (requested) {
+    if (!PHASES.includes(requested)) {
+      throw new Error(
+        `unknown --phase "${requested}". Known: ${PHASES.join(", ")}.`
+      );
+    }
+    if (requested === "secrets" && materializeAt !== "session-start") {
+      // Not an error: the hook is committed to the repository and runs on every
+      // surface the project is ever checked out on. Refusing loudly would make
+      // a correct local session look broken every time it started.
+      return [];
+    }
+    return [requested];
+  }
+  return PHASES.filter(
+    phase => phase !== "secrets" || materializeAt === "setup"
+  );
+}
+
+/**
+ * Read the surface the resolver detects, without duplicating its rules.
+ *
+ * Imported rather than shelled out to, because the answer is a pure function of
+ * the environment and a subprocess would buy nothing. The path is converted to
+ * a file URL first: a bare absolute path is not a portable module specifier.
+ * @returns {Promise<{surface: string, materializeAt: string|null}>} Detected surface.
+ */
+async function detectSurface() {
+  const script = siblingScript("lisa-secrets-access", "surfaces.mjs");
+  const mod = await import(pathToFileURL(script).href);
+  const surface = mod.detectSurface();
+  return { surface, materializeAt: mod.SURFACES[surface].materializeAt };
+}
+
+/**
+ * Name the project's own install command rather than inventing one.
+ *
+ * The emitted setup line must begin with whatever this project already uses; a
+ * guessed package manager produces a container that fails on its first command.
+ * @param {string} [cwd] Repository root.
+ * @returns {string} The install command to place before the setup script.
+ */
+export function detectInstallCommand(cwd = process.cwd()) {
+  const lockfiles = [
+    ["bun.lockb", "bun install"],
+    ["bun.lock", "bun install"],
+    ["pnpm-lock.yaml", "pnpm install --frozen-lockfile"],
+    ["yarn.lock", "yarn install --immutable"],
+    ["package-lock.json", "npm ci"],
+  ];
+  for (const [file, command] of lockfiles) {
+    if (existsSync(join(cwd, file))) return command;
+  }
+  return "<your install command>";
+}
+
+/**
+ * Read the bootstrap key name, which is the one value the operator must paste.
+ * @param {string} [cwd] Repository root.
+ * @returns {string|null} The configured key name, when there is one.
+ */
+function readBootstrapKey(cwd = process.cwd()) {
+  const path = join(cwd, ".lisa.config.json");
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, "utf8")).secrets?.bootstrap?.key ?? null;
+}
+
+async function main() {
   const dryRun = process.argv.includes("--dry-run");
+  const emit = process.argv
+    .find(arg => arg.startsWith("--emit="))
+    ?.slice("--emit=".length);
+
+  if (emit) {
+    if (emit !== "claude-web") {
+      throw new Error(
+        `no emit template for surface "${emit}".\n` +
+          `Emitting is implemented for claude-web, which has no other tier.`
+      );
+    }
+    console.log(
+      emitClaudeWeb({
+        bootstrapKey: readBootstrapKey(),
+        install: detectInstallCommand(),
+      })
+    );
+    return;
+  }
+
+  const requested = process.argv
+    .find(arg => arg.startsWith("--phase="))
+    ?.slice("--phase=".length);
   const cfg = readRemoteEnvConfig();
+  const { surface, materializeAt } = await detectSurface();
+  const phases = selectPhases(requested, materializeAt);
 
-  console.log("Toolchain:");
-  applyToolchain(cfg.tools, dryRun);
+  if (!phases.length) {
+    console.log(
+      `Nothing to do: surface "${surface}" does not materialize from a ` +
+        `session-start hook.`
+    );
+    return;
+  }
 
-  console.log("\nSecrets:");
-  const materialize = siblingScript(
-    "lisa-secrets-access",
-    "materialize-secrets.mjs"
-  );
-  execFileSync("node", dryRun ? [materialize, "--dry-run"] : [materialize], {
-    stdio: "inherit",
-  });
+  if (phases.includes("toolchain")) {
+    console.log("Toolchain:");
+    applyToolchain(cfg.tools, dryRun);
+  }
+
+  if (phases.includes("secrets")) {
+    console.log("\nSecrets:");
+    const materialize = siblingScript(
+      "lisa-secrets-access",
+      "materialize-secrets.mjs"
+    );
+    execFileSync("node", dryRun ? [materialize, "--dry-run"] : [materialize], {
+      stdio: "inherit",
+    });
+  } else if (!requested) {
+    console.log(
+      `\nSecrets: materialized from a session-start hook on "${surface}", ` +
+        `not here.\n` +
+        `  This script is skipped whenever a cached environment exists, so a ` +
+        `value written\n  here would go stale the moment it was rotated. The ` +
+        `hook runs every session.`
+    );
+  }
 
-  runHook(cfg.hook, dryRun);
+  if (phases.includes("hook")) runHook(cfg.hook, dryRun);
   console.log(`\nRemote environment ${dryRun ? "plan complete" : "ready"}.`);
 }
 
 if (import.meta.url === `file://${process.argv[1]}`) {
-  try {
-    main();
-  } catch (err) {
+  // Awaited rather than called bare: main is async, so a synchronous try/catch
+  // would let a rejected promise escape as an unhandled rejection and exit 0 —
+  // reporting a prepared environment that was never prepared.
+  main().catch(err => {
     console.error(err.message);
     process.exit(1);
-  }
+  });
 }

package/plugins/lisa/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-agy/plugin.json

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

package/plugins/lisa-agy/skills/lisa-secrets-access/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-agy/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-agy/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 "$@"