@codyswann/lisa 2.316.2 → 2.317.0

package/plugins/lisa-cursor/skills/lisa-setup-automations/SKILL.md

@@ -26,6 +26,75 @@ create them; invoke the runtime's automation tool with the spec below.
 - **Other runtimes** → use the runtime's native recurring-task mechanism. If the runtime has none,
   state that scheduling is unavailable and stop.
 
+## Unattended scheduling: `scheduler: "github-actions"`
+
+Every option above runs on the **workstation**. That is correct when the operator is present, and
+useless when the goal is "fire work off, close the laptop, go to sleep" — a native automation on a
+sleeping machine does not fire.
+
+When a loop declares `scheduler: "github-actions"`, generate a workflow instead of a local routine.
+This is the right shape only in combination with `executionEnv`: the scheduled job becomes a **thin
+dispatcher** that wakes, picks eligible work, submits it to a remote surface, records the identifier,
+and exits. The heavy lifting happens on the remote surface, so the clock needs availability rather
+than power.
+
+```json
+{
+  "automations": {
+    "intake": {
+      "scheduler": "github-actions",
+      "schedule": "17 * * * *",
+      "executionEnv": "codex-cloud",
+      "enabled": false
+    }
+  }
+}
+```
+
+`scheduler` is the pluggable seam. The same declaration generates a GitHub Actions workflow today and
+can register a different mechanism later without touching the loop itself. **Config is the source of
+truth; the workflow is generated from it** — regenerate rather than hand-edit.
+
+```sh
+scripts/generate-workflow.mjs intake --write
+```
+
+### Why GitHub Actions is the default unattended clock
+
+It is already present in every host project, already holds the bootstrap credential, and provides
+cron, concurrency groups, retries, manual dispatch, and an audit trail. Cost is negligible: billing is
+per minute rounded up, and a dispatch-only job finishes in well under one — a nightly loop runs a few
+dollars a year. Note the rounding is **per workflow run**, so batching N dispatches into one run is
+far cheaper than N triggers.
+
+The real cost is the remote task's own consumption, against which the clock is a rounding error.
+
+Rejected: workstation-native automation mechanisms for this purpose — they reintroduce exactly the
+sleeping-laptop problem this option exists to solve.
+
+### Registered disabled
+
+A recurring trigger goes live **only after the exact production path has been proven once for one
+real item.** Registration therefore writes a `workflow_dispatch`-only workflow; enabling adds the
+cron. The generator says so when it writes a disabled loop.
+
+**GitHub auto-disables scheduled workflows after 60 days of repository inactivity.** For an
+unattended factory that is a real trap — a quiet repository silently stops running its loops, and
+nothing announces it. `lisa-automation-status` must treat a stopped clock as a finding.
+
+### What the generated workflow guarantees
+
+- **Never cancels in progress.** Cancelling could kill a dispatch after the remote accepted a task
+  but before its identifier was recorded — irreversible work with nothing to reconcile against, where
+  a retry duplicates it.
+- **Asserts the bootstrap before installing anything**, so a misconfigured secret fails in seconds
+  rather than after a toolchain download.
+- **Persists credential rotation with `if: always()`.** The dispatcher authenticates with a
+  credential that rotates on use, so the replacement must be written back even when the dispatch
+  itself failed. That makes the very first artifact this produces an exercise of the rotating-credential
+  path in `lisa-secrets-access`, not a hypothetical one.
+- **Guards on the repository**, so a fork does not inherit a live clock.
+
 ## Parameters
 
 - `auto-start-prds` (default **true**) — passed as `prd_ready` to the **exploratory-prds**

package/plugins/lisa-cursor/skills/lisa-setup-automations/scripts/generate-workflow.mjs

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+/**
+ * Generate the GitHub Actions workflow that fires a registered automation loop.
+ *
+ * Once `executionEnv` exists, a scheduled loop is a thin dispatcher: it wakes,
+ * picks eligible work, submits it to a remote surface, records the identifier,
+ * and exits. The heavy lifting happens elsewhere. That makes the clock's job
+ * cheap and boring, and the requirements on it are availability rather than
+ * power.
+ *
+ * The workflow is generated from `.lisa.config.json` rather than hand-written,
+ * so config stays the source of truth and swapping the scheduler later is a
+ * config change instead of a rewrite.
+ *
+ * Usage:
+ *   generate-workflow.mjs <loop-name> [--write]
+ * @module generate-workflow
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/** Where a generated loop workflow lands. */
+export const workflowPath = name =>
+  join(".github", "workflows", `lisa-${name}.yml`);
+
+/**
+ * Read one automation's declaration.
+ * @param {string} name Loop name.
+ * @param {string} [cwd] Repository root.
+ * @returns {object} The loop's configuration.
+ */
+export function readAutomation(name, cwd = process.cwd()) {
+  const path = join(cwd, ".lisa.config.json");
+  if (!existsSync(path)) throw new Error(".lisa.config.json is missing");
+  const cfg = JSON.parse(readFileSync(path, "utf8"));
+  const loop = cfg.automations?.[name];
+  if (!loop) {
+    throw new Error(
+      `no automations["${name}"] in .lisa.config.json.\n` +
+        `Declare the loop before generating its workflow.`
+    );
+  }
+  return {
+    ...loop,
+    repository: cfg.remoteEnv?.surfaces?.[loop.executionEnv]?.repository,
+  };
+}
+
+/**
+ * Render the workflow YAML for one loop.
+ *
+ * Three choices here are load-bearing rather than stylistic.
+ *
+ * The `schedule` trigger is emitted **only when the loop is enabled**. A
+ * recurring trigger goes live after the exact production path has been proven
+ * once for one real item, so registration writes a manually-dispatchable
+ * workflow and enabling adds the clock.
+ *
+ * The concurrency group **never cancels in progress**. Cancelling could kill a
+ * dispatch after the remote accepted a task but before its identifier was
+ * recorded, which orphans irreversible work — nothing left to reconcile against,
+ * and a retry that duplicates it.
+ *
+ * The bootstrap credential is asserted **before** anything is installed, so a
+ * misconfigured secret fails in seconds rather than after a toolchain download.
+ * @param {string} name Loop name.
+ * @param {object} loop Loop configuration.
+ * @returns {string} Workflow YAML.
+ */
+export function renderWorkflow(name, loop) {
+  if (!loop.schedule) throw new Error(`automations["${name}"] has no schedule`);
+  if (!loop.repository) {
+    throw new Error(
+      `automations["${name}"] targets executionEnv "${loop.executionEnv}", ` +
+        `but no remoteEnv.surfaces["${loop.executionEnv}"].repository is set.\n` +
+        `Run /lisa:setup:remote-env ${loop.executionEnv} first.`
+    );
+  }
+
+  const trigger = loop.enabled
+    ? `  schedule:\n    - cron: '${loop.schedule}'\n  workflow_dispatch:`
+    : `  # schedule: disabled until the production path is proven once for one\n` +
+      `  # real item. Enabling adds:  - cron: '${loop.schedule}'\n  workflow_dispatch:`;
+
+  return `# Generated by lisa-setup-automations from .lisa.config.json.
+# Edit the config and regenerate; hand edits are overwritten.
+name: 🔁 Lisa ${name}
+
+on:
+${trigger}
+
+# Never cancel in progress. A cancelled dispatch can leave a remote task that
+# was accepted but whose identifier was never recorded — irreversible work with
+# nothing to reconcile against, where a retry duplicates it.
+concurrency:
+  group: lisa-${name}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  dispatch:
+    name: Dispatch one ${name} cycle
+    if: github.repository == '${loop.repository}'
+    runs-on: ubuntu-latest
+    timeout-minutes: ${loop.timeoutMinutes ?? 15}
+    env:
+      LISA_SECRETS_SURFACE: github-actions
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      # Assert first, install second: a misconfigured bootstrap should fail in
+      # seconds rather than after a toolchain download.
+      - name: Check the bootstrap credential is configured
+        env:
+          BWS_ACCESS_TOKEN: \${{ secrets.BWS_ACCESS_TOKEN }}
+        run: |
+          set -euo pipefail
+          test -n "\${BWS_ACCESS_TOKEN}" || {
+            echo "BWS_ACCESS_TOKEN is not configured for this repository" >&2
+            exit 1
+          }
+
+      - name: Prepare the toolchain and secrets
+        env:
+          BWS_ACCESS_TOKEN: \${{ secrets.BWS_ACCESS_TOKEN }}
+        run: bash scripts/lisa-remote-env/setup.sh
+
+      - name: Run one ${name} cycle
+        env:
+          BWS_ACCESS_TOKEN: \${{ secrets.BWS_ACCESS_TOKEN }}
+        run: |
+          set -euo pipefail
+          node .claude/skills/lisa-remote-dispatch/scripts/dispatch.mjs \\
+            'executionEnv=${loop.executionEnv} ${loop.payload ?? ""}' \\
+            --skill ${loop.skill ?? `lisa-${name}`}
+
+      # The dispatcher authenticates with a credential that rotates on use, so
+      # the replacement must be persisted even when the dispatch itself failed.
+      - name: Persist any credential rotation
+        if: \${{ always() }}
+        env:
+          BWS_ACCESS_TOKEN: \${{ secrets.BWS_ACCESS_TOKEN }}
+        run: |
+          set -euo pipefail
+          node .claude/skills/lisa-secrets-access/scripts/rotate-secret.mjs leases
+`;
+}
+
+function main() {
+  const [name, ...flags] = process.argv.slice(2);
+  if (!name)
+    throw new Error("usage: generate-workflow.mjs <loop-name> [--write]");
+  const loop = readAutomation(name);
+  const yaml = renderWorkflow(name, loop);
+
+  if (!flags.includes("--write")) {
+    process.stdout.write(yaml);
+    return;
+  }
+  const path = workflowPath(name);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, yaml);
+  console.log(`wrote ${path}`);
+  if (!loop.enabled) {
+    console.log(
+      "Registered DISABLED. Prove the exact production path once for one real " +
+        "item with a manual dispatch, then set enabled: true and regenerate."
+    );
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  try {
+    main();
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+}

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

@@ -0,0 +1,150 @@
+---
+name: lisa-setup-remote-env
+description: "Provision and verify a remote execution environment for a host project — Codex Cloud today, other remote surfaces as they are added. Generates a repository-owned setup script that installs the declared toolchain, materializes secrets through lisa-secrets-access, and runs the project's own hook. Provisions by API where one exists, by driving the vendor console where one does not, and by emitting exact config otherwise — then proves the result with the same read-back regardless of which tier did the work. Use before dispatching any work with executionEnv."
+allowed-tools: ["Bash", "Read", "Write", "Edit", "Skill"]
+---
+
+# Setup Remote Environment: $ARGUMENTS
+
+Prepare a remote surface so a host project can execute there. Today that means **Codex Cloud**; the shape is deliberately surface-agnostic so Claude Code web, Cursor remote, and others slot in without redesign.
+
+## What lives where
+
+The remote environment's own configuration fields stay **two one-line calls into the repository**. Nothing is pasted into a vendor UI.
+
+```text
+setup:       bash scripts/lisa-remote-env/setup.sh
+maintenance: bash scripts/lisa-remote-env/setup.sh
+```
+
+They are the same script. A container may be built fresh or resumed from cache; every step 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.
+
+The complete logic is repository-owned so it is reviewed, versioned, tested, and reusable. A large inline installer in a settings field is none of those things.
+
+## The three phases
+
+1. **Toolchain** — assert what must already be present, install what is not.
+2. **Secrets** — materialize through `lisa-secrets-access`. This skill never reimplements any part of that contract; the single chokepoint is what makes the one-store rule enforceable.
+3. **Project hook** — an optional `setup.local.sh` the project owns.
+
+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.
+
+## Toolchain manifest — two entry kinds
+
+```json
+{
+  "remoteEnv": {
+    "tools": {
+      "require": [
+        { "name": "python3" },
+        { "name": "node", "minVersion": "20" },
+        { "name": "curl" },
+        { "name": "unzip" }
+      ],
+      "install": [
+        {
+          "name": "bws",
+          "version": "2.1.0",
+          "install": "release-zip",
+          "url": "https://<vendor>/releases/download/bws-v2.1.0/bws-<platform>-2.1.0.zip",
+          "sha256": "<sha256 published with that exact release>"
+        },
+        {
+          "name": "codex",
+          "version": "0.144.6",
+          "install": "npm-global",
+          "package": "@openai/codex"
+        }
+      ]
+    },
+    "hook": "scripts/lisa-remote-env/setup.local.sh",
+    "surfaces": {
+      "codex-cloud": {
+        "environmentId": "<id>",
+        "repository": "<org>/<repo>",
+        "branch": "main"
+      }
+    }
+  }
+}
+```
+
+**`require`** — assert present, optionally at a minimum version. For everything the base image already provides.
+
+**`install`** — provision it, pinned and checksummed. Only for what genuinely is not there.
+
+Expected shape for most projects: a short `require` list, an empty or near-empty `install` list, and the provider CLI as the only thing always provisioned.
+
+### Rules
+
+- **The base image is not a contract.** A vendor can change it. A project quietly depending on a preinstalled `jq` should break loudly at setup when that happens, not mysteriously mid-task weeks later. `require` is what converts an implicit assumption into an explicit check.
+- **Detect first, install second.** Check the installed version, skip when it matches the pin, reinstall only when the pin changed. This is what makes setup and maintenance the same script, and it is the cheap path on cache resume.
+- **Version-assert, not just presence.** A base-image bump that moves off a supported Node or Python must be caught. Presence alone is not enough when a project depends on a specific version.
+- **Prefer what is there.** A second Node beside the image's creates PATH ambiguity and wastes container time.
+- **Pin and checksum together, in one reviewed commit.** A version bump that does not move the checksum fails before installation, not after. An archive is verified *before* it is unpacked, so unexpected contents never reach a directory on PATH.
+
+## Tooling is never derived from secret notes
+
+Deliberately rejected:
+
+- Most tooling has **no credential** — `jq`, ripgrep, browsers, a linter — so notes could only ever cover a subset, and a second mechanism would be needed anyway.
+- Most credentials **imply no tool**: a webhook is curl'd, a REST key needs no CLI.
+- The mapping is **guesswork** — which CLI, what version, pinned how — and is exactly the inference the secrets contract already forbids from authorising anything.
+- It makes **prose load-bearing**: a note lives provider-side, is editable outside review, and is unfixable by a read-only account.
+- It is a **supply-chain path** — provider write access would become arbitrary install access.
+
+**Notes are an assertion target instead.** At verify time, a tool that declares a credential which is not materialized is an **error**; a credential materialized with no declared consumer is a **warning**. The arrow points the safe way: the repository declares intent, and the provider is checked against it.
+
+## Provisioning tiers
+
+Preference order, falling back:
+
+1. **API** — provision programmatically.
+2. **Console** — drive the vendor's web console.
+3. **Emit** — generate exact config for a human to paste.
+
+**For Codex Cloud today, start at tier 2 or 3.** Verified on 2026-08-01: `codex cloud` exposes only `exec | status | list | apply | diff`. There is no environment-provisioning subcommand, so there is nothing to call. Do not claim tier 1 for this surface until the CLI grows one.
+
+When emitting, produce exactly:
+
+```text
+Environment name:  <project> remote executor
+Repository:        <org>/<repo>        (must be the default checkout)
+Setup script:      bash scripts/lisa-remote-env/setup.sh
+Maintenance:       bash scripts/lisa-remote-env/setup.sh
+Environment vars:  LISA_SECRETS_SURFACE=codex-cloud
+                   BWS_ACCESS_TOKEN=<from the provider; an environment
+                   variable, not a task secret — setup and cache-resume
+                   maintenance both run before task secrets exist>
+```
+
+## 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.
+
+```sh
+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.
+
+**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.
+
+## Preconditions
+
+Checked when setup runs, not at 3am:
+
+- the environment exists and is bound to **this** repository as its default checkout;
+- the bootstrap credential resolves;
+- Lisa has been applied to the repository, so its skills are present in that checkout.
+
+Fail with a message naming what is missing. Never provision-and-hope.
+
+## Bootstrap credential placement
+
+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.
+
+## Related
+
+- `lisa-secrets-access` — owns every part of the secrets contract this skill composes with.
+- `lisa-remote-dispatch` — dispatches work to an environment this skill prepared.

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

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+#
+# Remote environment entrypoint. Installed by /lisa:setup:remote-env; the remote
+# environment's setup AND maintenance fields both call this exact path.
+#
+# They are the same script on purpose. A container may be built fresh or resumed
+# from cache, and everything below 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.
+#
+# This file is deliberately thin. It resolves an interpreter and hands off; the
+# reviewed, tested, versioned logic lives in the Lisa skill rather than here,
+# and emphatically not in a vendor settings field.
+set -euo pipefail
+
+# Node is the one thing that cannot be installed by the installer, since the
+# installer is written in it. Fail with an actionable message rather than a
+# "command not found" forty lines deep.
+if ! command -v node >/dev/null 2>&1; then
+  echo "node is required to prepare this environment but is not present." >&2
+  echo "It cannot be installed by the toolchain step, because that step runs" >&2
+  echo "on node. Pin a base image that provides it." >&2
+  exit 1
+fi
+
+# The skill ships under whichever agent directory this project uses. Search
+# rather than hardcode, so one entrypoint serves every supported harness.
+runner=""
+for candidate in \
+  ".claude/skills/lisa-setup-remote-env/scripts/setup-remote-env.mjs" \
+  ".agents/skills/lisa-setup-remote-env/scripts/setup-remote-env.mjs" \
+  ".codex/skills/lisa-setup-remote-env/scripts/setup-remote-env.mjs"; do
+  if [ -f "$candidate" ]; then
+    runner="$candidate"
+    break
+  fi
+done
+
+if [ -z "$runner" ]; then
+  echo "Cannot find the lisa-setup-remote-env skill in this checkout." >&2
+  echo "Run 'lisa apply' so the skills are present, then re-run setup." >&2
+  exit 1
+fi
+
+exec node "$runner" "$@"

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

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+/**
+ * Prepare a remote environment: toolchain, then secrets, then the project hook.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * Usage:
+ *   setup-remote-env.mjs [--dry-run]
+ * @module setup-remote-env
+ */
+
+import { execFileSync } from "node:child_process";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+} from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { assertPinned, extractVersion, planToolchain } from "./toolchain.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Locate a sibling skill's script.
+ *
+ * Secrets belong to `lisa-secrets-access`, and this script must not reimplement
+ * any part of that contract — the single chokepoint is what makes the one-store
+ * rule enforceable. Resolving relative to this file works in every install
+ * layout, because skills are always siblings under one `skills/` directory.
+ * @param {string} skill Sibling skill slug.
+ * @param {string} script Script filename.
+ * @returns {string} Absolute path.
+ */
+function siblingScript(skill, script) {
+  const path = resolve(HERE, "..", "..", skill, "scripts", script);
+  if (!existsSync(path)) {
+    throw new Error(
+      `cannot find ${skill}/scripts/${script} beside this skill.\n` +
+        `Remote setup composes with that skill rather than reimplementing it.`
+    );
+  }
+  return path;
+}
+
+/**
+ * Read the `remoteEnv` block from `.lisa.config.json`.
+ * @param {string} [cwd] Directory to look in.
+ * @returns {{tools: object, hook: string|null, surfaces: object}} Configuration.
+ */
+export function readRemoteEnvConfig(cwd = process.cwd()) {
+  const path = join(cwd, ".lisa.config.json");
+  const defaults = {
+    tools: { require: [], install: [] },
+    hook: null,
+    surfaces: {},
+  };
+  if (!existsSync(path)) return defaults;
+  const cfg = JSON.parse(readFileSync(path, "utf8")).remoteEnv;
+  if (!cfg) return defaults;
+  return {
+    tools: { require: [], install: [], ...(cfg.tools ?? {}) },
+    hook: cfg.hook ?? null,
+    surfaces: cfg.surfaces ?? {},
+  };
+}
+
+/**
+ * Probe what a tool reports for its version, treating absence as not present.
+ * @param {string} name Executable name.
+ * @returns {{version: string|null, present: boolean}} Probe result.
+ */
+function probe(name) {
+  try {
+    const out = execFileSync(name, ["--version"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return { present: true, version: extractVersion(out) };
+  } catch {
+    return { present: false, version: null };
+  }
+}
+
+/**
+ * Install a pinned archive, refusing anything whose checksum does not match.
+ * @param {object} tool Manifest entry.
+ * @param {string} binDir Directory to install into.
+ */
+function installReleaseZip(tool, binDir) {
+  const temporary = join(binDir, `.${tool.name}-download`);
+  mkdirSync(temporary, { recursive: true });
+  try {
+    const archive = join(temporary, "download.zip");
+    execFileSync("curl", ["-fsSL", tool.url, "-o", archive], {
+      stdio: "inherit",
+    });
+    // Verify before unpacking, not after. An unexpected archive must fail
+    // before any of its contents reach a directory that is on PATH.
+    execFileSync("sha256sum", ["-c", "-"], {
+      input: `${tool.sha256}  ${archive}\n`,
+      stdio: ["pipe", "ignore", "inherit"],
+    });
+    execFileSync("unzip", ["-q", "-o", archive, "-d", temporary], {
+      stdio: "inherit",
+    });
+    const binary = join(temporary, tool.binary ?? tool.name);
+    execFileSync("install", ["-m", "0755", binary, join(binDir, tool.name)], {
+      stdio: "inherit",
+    });
+  } finally {
+    rmSync(temporary, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Install a pinned global npm package.
+ * @param {object} tool Manifest entry.
+ */
+function installNpmGlobal(tool) {
+  execFileSync(
+    "npm",
+    ["install", "--global", `${tool.package}@${tool.version}`],
+    {
+      stdio: "inherit",
+    }
+  );
+}
+
+/**
+ * Execute one install decision.
+ * @param {object} tool Manifest entry.
+ * @param {string} binDir Directory for downloaded binaries.
+ */
+function installTool(tool, binDir) {
+  assertPinned(tool);
+  if (tool.install === "release-zip") installReleaseZip(tool, binDir);
+  else installNpmGlobal(tool);
+}
+
+/**
+ * Apply the toolchain plan, reporting every decision.
+ * @param {object} tools Manifest.
+ * @param {boolean} dryRun Whether to plan only.
+ * @returns {Array<object>} The plan that was applied.
+ */
+function applyToolchain(tools, dryRun) {
+  const plan = planToolchain(tools, probe);
+  const blocked = plan.filter(
+    p => p.action === "missing" || p.action === "invalid"
+  );
+  if (blocked.length) {
+    throw new Error(blocked.map(p => p.reason).join("\n\n"));
+  }
+
+  const binDir = join(process.env.HOME ?? "", ".local", "bin");
+  mkdirSync(binDir, { recursive: true, mode: 0o755 });
+  const byName = new Map((tools.install ?? []).map(t => [t.name, t]));
+
+  for (const step of plan) {
+    console.log(`  ${step.action.padEnd(8)} ${step.reason}`);
+    if (step.action === "install" && !dryRun)
+      installTool(byName.get(step.name), binDir);
+  }
+  return plan;
+}
+
+/**
+ * Run the project's own setup hook when it has one.
+ *
+ * A declarative manifest will never cover everything, and without an escape
+ * hatch a project's only option is to fork Lisa's script — at which point it
+ * stops receiving any of the fixes.
+ * @param {string|null} hook Repository-relative path.
+ * @param {boolean} dryRun Whether to plan only.
+ */
+function runHook(hook, dryRun) {
+  if (!hook) return;
+  const path = resolve(process.cwd(), hook);
+  if (!existsSync(path)) {
+    throw new Error(`remoteEnv.hook points at ${hook}, which does not exist`);
+  }
+  console.log(`\nProject hook: ${hook}`);
+  if (dryRun) return;
+  chmodSync(path, 0o755);
+  execFileSync("bash", [path], { stdio: "inherit" });
+}
+
+function main() {
+  const dryRun = process.argv.includes("--dry-run");
+  const cfg = readRemoteEnvConfig();
+
+  console.log("Toolchain:");
+  applyToolchain(cfg.tools, dryRun);
+
+  console.log("\nSecrets:");
+  const materialize = siblingScript(
+    "lisa-secrets-access",
+    "materialize-secrets.mjs"
+  );
+  execFileSync("node", dryRun ? [materialize, "--dry-run"] : [materialize], {
+    stdio: "inherit",
+  });
+
+  runHook(cfg.hook, dryRun);
+  console.log(`\nRemote environment ${dryRun ? "plan complete" : "ready"}.`);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  try {
+    main();
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+}