@miroshnik/elves 0.0.0 → 2026.1018.0

package/skills/task-env/scripts/task-env.ts

@@ -0,0 +1,1017 @@
+#!/usr/bin/env bun
+/**
+ * task-env — a task's environment (the task-env skill): the task's stack is the Docker Compose project `<project>-<N>`;
+ * the machine's proxy — one Traefik per machine — gives containers of task stacks the addresses
+ * `http://<service>.<N>.<project>.localhost` by their labels, without ports on the host (tests/capabilities/task-env).
+ *
+ * `up` brings the task's stack up: the number from the branch `<type>/<N>-slug`, the Compose project `<project>-<N>`
+ * (without a number — `<project>`), the project's compose files plus the task's override on Compose's stdin — the
+ * proxy's labels and network for the HTTP services of `env.http` in `.agents/elves.json`; their addresses go to Compose's
+ * interpolation in `TASK_ENV_<SERVICE>_URL` (the compose file gives the app its own address); it prints the addresses.
+ * `e2e` brings `<project>-<N>-e2e` up anew with clean volumes and runs the command on the host with the e2e addresses
+ * in `TASK_ENV_*` variables; `down` takes both stacks of a task down with their volumes — `task close` calls it; `prune`
+ * takes down the stacks of the project's closed tasks left on the machine — orphans, the task's state by GitHub. A stack
+ * that didn't come up — each failed service with its state and the end of its log.
+ *
+ * `check` holds the project's compose file to the isolation rules: Compose keeps two stacks of one project apart by the
+ * project name — containers, volumes and networks get its prefix — and four entries bypass the prefix and break
+ * isolation silently: `container_name`, a fixed host port, a volume or a network with `name:` or `external`, an
+ * absolute path to code in `volumes` and `build`. It reads not the YAML but `docker compose config --format json`:
+ * Compose has already brought the forms of writing (short and long syntax, the override file, variables, `extends`) to
+ * one. Without path resolution — otherwise Compose makes relative paths absolute itself; with all profiles — otherwise
+ * heavy services in `profiles` aren't shown. `config` needs no Docker daemon, it works in the sandbox too. `check` of
+ * the Elves installer calls it for a project with a compose file.
+ *
+ * The proxy is the Compose project of `proxy/compose.yaml` next to this directory: the Docker provider with
+ * `exposedByDefault: false` (a container without labels isn't published), its own network, the `web` entry point on
+ * port 80 of 127.0.0.1, `restart: unless-stopped` (it comes back with Docker). A container leaves the routes when it
+ * stops: Traefik follows Docker events. A task stack joins the proxy network as `external` — the proxy creates it, so
+ * it goes up before the stack.
+ *
+ * The name (Compose project and network) and the port come from ELVES_PROXY and ELVES_PROXY_PORT, by default
+ * `elves-proxy` and 80: a test runs its own proxy next to the machine's one, a machine with port 80 busy takes
+ * another. The defaults live only here: the script passes both to the compose file explicitly (`composeEnv`), the file
+ * has none (`${…:?}`); `check -g` of the installer imports `proxyName`.
+ *
+ * The rename of the flow to Elves renamed the proxy: `FORMER_PROXY` → `PROXY`. For one release `proxy up` takes the
+ * former proxy's place: removes its container — it holds the port — and joins its network, where stacks brought up
+ * before the rename stay, so their addresses keep working; `check` names the former network in a project's compose
+ * file. Which network the proxy reaches a container through is deterministic: a task
+ * stack's service names it by a label, the provider's default is the former network while the proxy is in it
+ * (`proxyLabels`, `up`).
+ *
+ * The proxy's API (Traefik `/api/http/routers`) answers on its port by the host `<name>.localhost`: `proxyHosts` reads
+ * the hosts of its routes, `taskAddress` tells a task's address among them — the dashboard shows a task's services by
+ * them over the loopback, without the Docker socket.
+ *
+ * Docker runs outside the Claude Code sandbox (the sandbox denies its socket): the agent runs this script as an
+ * unsandboxed call — an `excludedCommands` entry for it doesn't take it out (SKILL.md, «Docker and the sandbox»).
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Help — `--help` or `-h` before `--` (after it — the e2e command's arguments; tests/standards/cli-help): a command's
+ * synopsis (the first paragraph), what it does and examples; `task-env --help` — the synopses of all. The dispatcher takes
+ * only the commands from here: a command without help can't be called.
+ */
+const HELP: Record<string, string> = {
+  up: `task-env up [--profile <p>]...
+
+Brings the task's stack up — the Compose project <project>-<N> by the branch <type>/<N>-slug, <project> without a
+number — and prints its addresses: env.http services of .agents/elves.json through the proxy, published ports on
+127.0.0.1; the HTTP addresses go to the compose file's interpolation in TASK_ENV_<SERVICE>_URL; --profile — Compose
+profiles. Code 0 — up, 1 — a service failed (its state and log), 2 — not tried.
+
+Examples:
+  task-env up
+  task-env up --profile worker`,
+  e2e: `task-env e2e [--profile <p>]... [-- <command>...]
+
+The e2e stack <project>-<N>-e2e anew with clean volumes (its own addresses in the interpolation), then the command with
+its addresses in TASK_ENV_PROJECT, TASK_ENV_<SERVICE>_URL, TASK_ENV_<SERVICE>_<PORT>; the exit code is the command's; the
+stack stays until the next run.
+
+Examples:
+  task-env e2e -- npx playwright test
+  task-env e2e --profile worker -- bun test e2e`,
+  down: `task-env down [<N>]
+
+Takes the stacks of task N (default — the branch's) down with their volumes: dev and e2e; a line per stack: + down,
+○ none, ! not removed (code 2); no compose file in the checkout — nothing to take down, Docker isn't called; task close of
+the github skill calls it.
+
+Examples:
+  task-env down
+  task-env down 42`,
+  prune: `task-env prune
+
+Takes down the stacks of the project's closed tasks left on the machine (orphans) with their volumes: the task's state —
+by GitHub (gh); stacks of open tasks, of the main checkout, of numbers that aren't tasks and of another repository with
+the same name — left.
+
+Examples:
+  task-env prune`,
+  check: `task-env check [<dir>]
+
+Holds the compose file in <dir> (default — the current directory) to the task isolation rules: no container_name, no
+fixed host port, volumes and networks without name and external, code by paths relative to the compose file; one ❌ line
+per violation; the network of the proxy's former name ai-dev-proxy — remove it, task-env up adds the proxy's network
+itself. Code 0 — the rules hold or there is no compose file, 1 — violations, 2 — not checked (no docker compose, the
+config doesn't parse).
+
+Examples:
+  task-env check
+  task-env check services/api`,
+  "proxy up": `task-env proxy up
+
+Starts the machine's proxy (Traefik) or brings it to the skill's compose file and waits until it is healthy; port 80 busy
+— another one in ELVES_PROXY_PORT. The proxy before the rename (ai-dev-proxy) — its container removed, its network
+joined: stacks brought up before the rename keep their addresses.
+
+Examples:
+  task-env proxy up`,
+  "proxy down": `task-env proxy down
+
+Stops and removes the proxy and its network.
+
+Examples:
+  task-env proxy down`,
+  "proxy status": `task-env proxy status
+
+Running — code 0, not running — 1 with the start command, Docker unavailable — 2.
+
+Examples:
+  task-env proxy status`,
+};
+
+/** `task-env --help`: what the script is and the synopsis of each command. */
+const OVERVIEW = [
+  "task-env — a task's environment: its Docker Compose stack and the machine's proxy of *.localhost addresses",
+  "",
+  ...Object.values(HELP).map((h) => h.split("\n\n")[0]!.replace(/^/gm, "  ")),
+  "",
+  "task-env <command> --help — the command's details and examples",
+].join("\n");
+
+/** The command the arguments start with: `proxy up`, `down`; none — undefined. */
+const commandOf = (argv: string[]) => Object.keys(HELP).find((c) => `${argv.join(" ")} `.startsWith(`${c} `));
+
+/** The help the arguments before `--` ask for (`--help`, `-h`): of their command, otherwise the overview; none — undefined. */
+function helpOf(argv: string[]): string | undefined {
+  const own = argv.includes("--") ? argv.slice(0, argv.indexOf("--")) : argv;
+  if (!own.some((a) => a === "--help" || a === "-h")) return undefined;
+  const cmd = commandOf(own);
+  return cmd ? HELP[cmd] : OVERVIEW;
+}
+
+/** The proxy's compose file: the skill directory's `proxy/compose.yaml`. */
+export const PROXY_FILE = fileURLToPath(new URL("../proxy/compose.yaml", import.meta.url));
+/** The proxy's Compose service — the Traefik container. */
+const SERVICE = "traefik";
+/** The entry point routers of task stacks attach to: HTTP on the proxy's port. */
+export const ENTRY_POINT = "web";
+
+/** The proxy's default name: the installer and other scripts import it; the compose file has no default of its own. */
+export const PROXY = "elves-proxy";
+
+/**
+ * The proxy's default name before the rename of the flow (ai-dev → Elves), read for the transition — one release
+ * (#545): `proxy up` takes its place, `check` names its network in a project's compose file, `check -g` of the
+ * installer names a proxy left under this name.
+ */
+export const FORMER_PROXY = "ai-dev-proxy";
+
+/** The proxy's name — its Compose project and network; `check -g` of the installer looks for it by this function. */
+export const proxyName = (env: NodeJS.ProcessEnv = process.env) => env.ELVES_PROXY || PROXY;
+
+/**
+ * The former proxy `proxy up` replaces: of the default proxy — `FORMER_PROXY`, of a proxy with another name (a test's
+ * one) — `<name>-former`, so a test's proxy never touches the machine's former proxy.
+ */
+export const formerProxyName = (env: NodeJS.ProcessEnv = process.env) => {
+  const name = proxyName(env);
+  return name === PROXY ? FORMER_PROXY : `${name}-former`;
+};
+
+/**
+ * The proxy's port on 127.0.0.1. AI_DEV_PROXY_PORT — the variable before the rename (#545): a profile set it when port
+ * 80 was busy, and the proxy keeps that port until the profile is edited.
+ */
+export const proxyPort = (env: NodeJS.ProcessEnv = process.env) => env.ELVES_PROXY_PORT || env.AI_DEV_PROXY_PORT || "80";
+
+/**
+ * The environment of the proxy's compose file: the name, the port and the provider's default network are passed
+ * explicitly — the file has no defaults of its own (`${…:?}`), they live only here (#396, question 1). The default
+ * network is the proxy's own unless `up` joins the former proxy's network (`up`); not a setting — the script sets it.
+ */
+export const composeEnv = (env: NodeJS.ProcessEnv = process.env, network = proxyName(env)): NodeJS.ProcessEnv => ({
+  ...env,
+  ELVES_PROXY: proxyName(env),
+  ELVES_PROXY_PORT: proxyPort(env),
+  ELVES_PROXY_DEFAULT_NETWORK: network,
+});
+
+/** The host of the proxy's API: a router of the proxy's own labels on the `web` entry point (proxy/compose.yaml). */
+export const apiHost = (env: NodeJS.ProcessEnv = process.env) => `${proxyName(env)}.localhost`;
+
+/** A service's address through the machine's proxy: its port is in the address when it isn't 80. */
+export const addressUrl = (host: string, port = proxyPort()) => `http://${host}${port === "80" ? "" : `:${port}`}`;
+
+/** The command that starts the proxy — as the output names it. */
+const START = `bun --no-env-file ${fileURLToPath(import.meta.url)} proxy up`;
+
+// ----------------------------------------------------------------------------
+// Addresses
+// ----------------------------------------------------------------------------
+
+/** A task's address `<service>.<N>.<project>.localhost`, e2e — `<service>.e2e.<N>.<project>.localhost`. */
+export interface TaskAddress {
+  service: string;
+  task: number;
+  e2e: boolean;
+  project: string;
+}
+
+/** A DNS label and a Compose project name at once: lowercase letters, digits and `-`. */
+const dnsLabel = (s: string) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+
+/**
+ * `<project>` of stacks and addresses by the repository name (#393, question 6): `projectName` takes it from `origin`,
+ * the dashboard — from the task's repository.
+ */
+export const hostProject = (repo: string) => dnsLabel(repo) || "project";
+
+// the service is lazy: `web.e2e.42.shop` is e2e of web, not the service `web.e2e`; `web.1.42.shop` is the service web.1
+const TASK_HOST = /^(.+?)\.(?:(e2e)\.)?(\d+)\.([a-z0-9-]+)\.localhost$/;
+
+/** A task's address by its host; another host (the main checkout's stack, the proxy's API, a foreign one) — null. */
+export function taskAddress(host: string): TaskAddress | null {
+  const m = TASK_HOST.exec(host.toLowerCase());
+  return m ? { service: m[1]!, task: Number(m[3]), e2e: !!m[2], project: m[4]! } : null;
+}
+
+/** The API answers locally: longer than this is a hang, not work. */
+const API_TIMEOUT = 3_000;
+/** Routers per API page — Traefik's default; the next page is in `X-Next-Page`, the last page names page 1. */
+const PER_PAGE = 100;
+const HOST_RULE = /Host\(\s*[`"]([^`"]+)[`"]\s*\)/g;
+
+/** The part of a Traefik router (`/api/http/routers`) the hosts are read from. */
+interface Router {
+  rule?: string;
+  status?: string;
+  entryPoints?: string[];
+}
+
+/**
+ * Hosts of the proxy's routes — from its API (Traefik `GET /api/http/routers`, page by page): `Host(…)` of the
+ * enabled routers of the `web` entry point; a router appears when its container starts and leaves when it stops. The
+ * proxy isn't running (the connection is refused) — null: without the proxy there are no addresses either; another
+ * failure — an exception with the reason.
+ */
+export async function proxyHosts(env: NodeJS.ProcessEnv = process.env): Promise<string[] | null> {
+  const fail = (why: string) => new Error(`proxy ${proxyName(env)}: routes not read — ${why}`);
+  const hosts = new Set<string>();
+  for (let page = 1; ; ) {
+    const url = `http://127.0.0.1:${proxyPort(env)}/api/http/routers?per_page=${PER_PAGE}&page=${page}`;
+    let r: Response;
+    try {
+      r = await fetch(url, { headers: { Host: apiHost(env) }, signal: AbortSignal.timeout(API_TIMEOUT) });
+    } catch (e) {
+      const err = e as NodeJS.ErrnoException & { cause?: { code?: string } };
+      const code = err.code ?? err.cause?.code;
+      if (code === "ECONNREFUSED") return null;
+      if (err.name === "TimeoutError") throw fail(`127.0.0.1:${proxyPort(env)} didn't answer in ${API_TIMEOUT / 1000} s`);
+      if (code === "EPERM") throw fail(`connecting to 127.0.0.1:${proxyPort(env)} is denied here (an agent's sandbox?)`);
+      throw fail(`${code ? `${code}: ` : ""}${err.message}`);
+    }
+    // the proxy before its API (#396) or something else on the port: Traefik answers an unknown host with 404
+    if (!r.ok) throw fail(`127.0.0.1:${proxyPort(env)} answered ${apiHost(env)} with HTTP ${r.status} — a proxy without the API? task-env proxy up brings it to the compose file`);
+    let routers: Router[];
+    try {
+      routers = (await r.json()) as Router[];
+    } catch {
+      throw fail("the API answered not with JSON");
+    }
+    if (!Array.isArray(routers)) throw fail("the API answered not with a list of routers");
+    for (const x of routers) {
+      if (x.status !== "enabled" || !x.entryPoints?.includes(ENTRY_POINT)) continue;
+      for (const m of String(x.rule ?? "").matchAll(HOST_RULE)) hosts.add(m[1]!);
+    }
+    const next = Number(r.headers.get("X-Next-Page"));
+    if (!(next > page)) break;
+    page = next;
+  }
+  return [...hosts];
+}
+
+export interface ProxyRoute {
+  /** The Compose project of the stack: `<project>-<N>`, `<project>-<N>-e2e`, `<project>` without a task. */
+  stack: string;
+  /** The Compose service. */
+  service: string;
+  /** The address host: `<service>.<N>.<project>.localhost`. */
+  host: string;
+  /** The service's HTTP port inside the container. */
+  port: number;
+  /** The proxy's network — the one the proxy reaches the container through. */
+  network: string;
+}
+
+/**
+ * Traefik labels for an HTTP service of a task stack: a router by host on the `web` entry point and a service to the
+ * container's port. The router and the service are named `<stack>-<service>`: unique on the machine, and replicas of
+ * one service (`--scale`) carry the same labels — Traefik balances between them. The network for reaching the
+ * container — by a label (#545): without it Traefik takes the provider's default network, and when the container isn't
+ * in that one — the first of its networks in Go's map order, a random one per configuration, and a stack in its
+ * `default` and the proxy's network would answer or not by chance; the default is the former proxy's network while
+ * the proxy is in it (`up`).
+ */
+export function proxyLabels(r: ProxyRoute): Record<string, string> {
+  const id = `${r.stack}-${r.service}`;
+  return {
+    "traefik.enable": "true",
+    "traefik.docker.network": r.network,
+    [`traefik.http.routers.${id}.rule`]: `Host(\`${r.host}\`)`,
+    [`traefik.http.routers.${id}.entrypoints`]: ENTRY_POINT,
+    [`traefik.http.routers.${id}.service`]: id,
+    [`traefik.http.services.${id}.loadbalancer.server.port`]: String(r.port),
+  };
+}
+
+interface Result {
+  code: number;
+  out: string;
+}
+
+/** The first line of a failed docker's output, or the launch error. */
+function why(r: ReturnType<typeof spawnSync>) {
+  if (r.error) return (r.error as NodeJS.ErrnoException).code === "ENOENT" ? "docker not found — task-env needs Docker (Docker Desktop on macOS)" : r.error.message;
+  const text = `${r.stderr ?? ""}`.trim() || `${r.stdout ?? ""}`.trim();
+  const lines = text.split("\n").filter((l) => /error|cannot|denied|failed|not permitted/i.test(l));
+  return (lines.at(-1) ?? text.split("\n").at(-1) ?? `docker: code ${r.status}`).trim();
+}
+
+/** A hint for a docker failure: what to do about it. */
+function hint(reason: string, env: NodeJS.ProcessEnv) {
+  if (/already allocated|address already in use|bind/i.test(reason)) return ` — port 127.0.0.1:${proxyPort(env)} is busy: free it or set ELVES_PROXY_PORT (the addresses then carry the port)`;
+  if (/cannot connect to the docker daemon|is the docker daemon running/i.test(reason)) return " — Docker isn't running: start it (Docker Desktop on macOS)";
+  if (/docker\.sock|not permitted|permission denied/i.test(reason)) return " — an agent's sandbox? Docker doesn't work in it: run this command outside the sandbox (SKILL.md, «Docker and the sandbox»)";
+  if (/address pools/i.test(reason)) return " — Docker is out of network subnets: take down stacks nobody needs or widen default-address-pools (SKILL.md, «Network subnets»)";
+  return "";
+}
+
+/**
+ * `docker compose` of the proxy. `former` — the former proxy's network to join: an override on Compose's stdin (the
+ * network isn't always on the machine, so it isn't in the file), and it becomes the provider's default network.
+ */
+function compose(args: string[], env: NodeJS.ProcessEnv, former?: string) {
+  const override = former ? { services: { [SERVICE]: { networks: { proxy: null, former: null } } }, networks: { former: { name: former, external: true } } } : undefined;
+  return spawnSync("docker", ["compose", "-f", PROXY_FILE, ...(override ? ["-f", "-"] : []), ...args], {
+    encoding: "utf8",
+    input: override ? JSON.stringify(override) : undefined,
+    env: composeEnv(env, former),
+  });
+}
+
+/** The proxy containers of a Compose project in any state — a `format` line each; Docker unavailable — the reason. */
+function proxyContainers(project: string, format: string, env: NodeJS.ProcessEnv): string[] | string {
+  const filters = ["--filter", `label=com.docker.compose.project=${project}`, "--filter", `label=com.docker.compose.service=${SERVICE}`];
+  const r = spawnSync("docker", ["ps", "--all", ...filters, "--format", format], { encoding: "utf8", env, timeout: 10_000 });
+  if (r.error || r.status !== 0) return why(r);
+  return r.stdout.split("\n").filter(Boolean);
+}
+
+/** Whether the proxy container runs: true / false; Docker unavailable — the reason. */
+export function proxyRunning(env: NodeJS.ProcessEnv = process.env): boolean | string {
+  const states = proxyContainers(proxyName(env), "{{.State}}", env);
+  return typeof states === "string" ? states : states.includes("running");
+}
+
+/** Whether a network is on the machine; Docker unavailable — the reason. */
+function networkExists(name: string, env: NodeJS.ProcessEnv): boolean | string {
+  const r = spawnSync("docker", ["network", "ls", "--filter", `name=^${name}$`, "--format", "{{.Name}}"], { encoding: "utf8", env, timeout: 10_000 });
+  if (r.error || r.status !== 0) return why(r);
+  return r.stdout.split("\n").includes(name);
+}
+
+function status(env: NodeJS.ProcessEnv): Result {
+  const name = proxyName(env);
+  const found = proxyContainers(name, "{{.State}}\t{{.Networks}}", env);
+  if (typeof found === "string") return { code: 2, out: `proxy ${name}: Docker unavailable — ${found}${hint(found, env)}` };
+  const running = found.map((l) => l.split("\t")).find(([state]) => state === "running");
+  if (!running) return { code: 1, out: `proxy ${name}: not running — start: ${START}` };
+  const former = formerProxyName(env);
+  const also = running[1]?.split(",").includes(former) ? `; and ${former} — of the proxy before the rename, with the stacks brought up before it` : "";
+  return { code: 0, out: `proxy ${name}: running — ${addressUrl("<service>.<N>.<project>.localhost", proxyPort(env))} on 127.0.0.1, routes by container labels (network ${name}${also})` };
+}
+
+/**
+ * `proxy up`: the proxy brought to the compose file and healthy. The transition from the proxy before the rename
+ * (#545, one release): its container holds the port — removed once the new one is created (a failed pull leaves the
+ * former proxy serving); its network stays — stacks brought up before the rename are in it — and the proxy joins it as
+ * the provider's default network: their services carry no network label, and a container outside the default network
+ * gets a random one of its networks (`proxyLabels`). No former network on the machine — the proxy is in its own only,
+ * the former one isn't created.
+ */
+function up(env: NodeJS.ProcessEnv): Result {
+  const name = proxyName(env);
+  const former = formerProxyName(env);
+  const out: string[] = [];
+  const fail = (reason: string) => ({ code: 2, out: [...out, `proxy ${name}: not started — ${reason}${hint(reason, env)}`].join("\n") });
+  const old = proxyContainers(former, "{{.ID}}", env);
+  if (typeof old === "string") return fail(old);
+  const joined = networkExists(former, env);
+  if (typeof joined === "string") return fail(joined);
+  const network = joined ? former : undefined;
+  if (old.length) {
+    const created = compose(["up", "--no-start", "--quiet-pull"], env, network);
+    if (created.error || created.status !== 0) return fail(why(created));
+    const rm = spawnSync("docker", ["rm", "--force", ...old], { encoding: "utf8", env });
+    if (rm.error || rm.status !== 0) return fail(`the proxy before the rename, ${former}, not removed: ${why(rm)}`);
+    out.push(`proxy ${former}: removed — the proxy before the rename; ${name} takes its port${joined ? `, its network ${former} stays` : ""}`);
+  }
+  const r = compose(["up", "--detach", "--wait", "--quiet-pull"], env, network);
+  if (r.error || r.status !== 0) return fail(why(r));
+  const s = status(env);
+  return { code: s.code, out: [...out, s.out].join("\n") };
+}
+
+function down(env: NodeJS.ProcessEnv): Result {
+  const r = compose(["down"], env);
+  if (r.error || r.status !== 0) {
+    const reason = why(r);
+    const attached = /active endpoints/i.test(reason) ? " — task stacks are still in its network: take them down first" : hint(reason, env);
+    return { code: 2, out: `proxy ${proxyName(env)}: not removed — ${reason}${attached}` };
+  }
+  return { code: 0, out: `proxy ${proxyName(env)}: removed` };
+}
+
+// ----------------------------------------------------------------------------
+// check — the compose file isolation rules
+// ----------------------------------------------------------------------------
+
+/**
+ * Compose files Docker Compose looks for, in its order. The installer imports the list — its `check` doesn't start this
+ * script in a project without a compose file.
+ */
+export const COMPOSE_FILES = ["compose.yaml", "compose.yml", "docker-compose.yaml", "docker-compose.yml"];
+
+/**
+ * Sources of a bind mount that are the machine's resources, not code — the Docker socket, `/etc/localtime`, devices:
+ * they don't tie a stack to a checkout (#398, question 3).
+ */
+const MACHINE = /^\/(?:var\/run|run|etc|dev|proc|sys)(?:\/|$)/;
+/** `docker compose config` reads a few files — longer than this is a hang, not work. */
+const CONFIG_TIMEOUT = 20_000;
+
+interface Port {
+  target: number;
+  published?: string;
+  host_ip?: string;
+  protocol?: string;
+}
+interface Mount {
+  type: string;
+  source?: string;
+}
+interface Service {
+  container_name?: string;
+  ports?: Port[];
+  volumes?: Mount[];
+  build?: { context?: string; dockerfile?: string };
+  networks?: Record<string, unknown>;
+}
+interface Resource {
+  name?: string;
+  external?: boolean;
+}
+/** The part of the normalized `docker compose config --format json` the rules read. */
+interface Config {
+  name: string;
+  services?: Record<string, Service>;
+  volumes?: Record<string, Resource>;
+  networks?: Record<string, Resource>;
+}
+
+const absolute = (p: string) => p.startsWith("/") || p === "~" || p.startsWith("~/");
+const list = (names: string[]) => `${names.length === 1 ? "service" : "services"} ${names.join(", ")}`;
+
+/** Violations of the isolation rules, one line each: services, then volumes, then networks; Compose sorts the keys. */
+function violations(config: Config, file: string): string[] {
+  const out: string[] = [];
+  const line = (subject: string, what: string) => out.push(`❌ ${file}: ${subject} — ${what}`);
+  const services = Object.entries(config.services ?? {});
+  for (const [name, s] of services) {
+    const subject = `service ${name}`;
+    if (s.container_name) line(subject, `container_name ${s.container_name}: a second task stack can't start; remove it, Compose names containers by the project`);
+    for (const p of s.ports ?? []) {
+      if (!p.published) continue;
+      const proto = p.protocol && p.protocol !== "tcp" ? `/${p.protocol}` : "";
+      const host = p.host_ip ? `${p.host_ip}:` : "";
+      line(subject, `fixed host port ${host}${p.published}:${p.target}${proto}: two task stacks contend for it; publish 127.0.0.1::${p.target}${proto} or drop ports`);
+    }
+    // a URL context (a git repository) isn't absolute either: it starts neither with / nor with ~
+    for (const [field, p] of [["context", s.build?.context], ["dockerfile", s.build?.dockerfile]] as const) {
+      if (p && absolute(p)) line(subject, `build ${field}: absolute path ${p}: builds code outside the task's worktree; use a path relative to the compose file`);
+    }
+    for (const v of s.volumes ?? []) {
+      if (v.type === "bind" && v.source && absolute(v.source) && !MACHINE.test(v.source)) {
+        line(subject, `volumes: absolute path ${v.source}: mounts code outside the task's worktree; use a path relative to the compose file`);
+      }
+    }
+  }
+  const shared = (kind: "volume" | "network", key: string, r: Resource, users: string[], why: string) => {
+    const subject = `${kind} ${key} (${list(users)})`;
+    if (r.external) line(subject, `external: ${why}; drop external`);
+    else if (r.name && r.name !== `${config.name}_${key}`) line(subject, `name ${r.name}: ${why}; remove name, Compose prefixes it by the project`);
+  };
+  for (const [key, r] of Object.entries(config.volumes ?? {})) {
+    const users = services.filter(([, s]) => (s.volumes ?? []).some((v) => v.type === "volume" && v.source === key)).map(([n]) => n);
+    shared("volume", key, r, users, "task stacks share it, down -v of one wipes another's data");
+  }
+  for (const [key, r] of Object.entries(config.networks ?? {})) {
+    const users = services.filter(([, s]) => Object.hasOwn(s.networks ?? {}, key)).map(([n]) => n);
+    // the proxy's network under its name before the rename (#545): a compose file wrote it by hand, as the example of
+    // reference.md did; the proxy stays in that network one release (`up`), and a machine without it fails the stack
+    if (r.name === FORMER_PROXY) {
+      line(`network ${key} (${list(users)})`, `${FORMER_PROXY} is the machine's proxy before the rename, now ${PROXY}: remove the network from the compose file and its services; task-env up adds the proxy's network to the HTTP services of env.http itself`);
+      continue;
+    }
+    shared("network", key, r, users, "task stacks share it and reach each other's services");
+  }
+  return out;
+}
+
+/** `check`: the exit code; all lines go to stdout — `check` of the installer reads them from there. */
+function check(dir: string): number {
+  const file = COMPOSE_FILES.find((f) => existsSync(path.join(dir, f)));
+  if (!file) return console.log(`no compose file in ${dir} — nothing to check`), 0;
+  const notChecked = (why: string) => (console.log(`○ ${file}: not checked — ${why}`), 2);
+  const r = spawnSync("docker", ["compose", "--profile", "*", "config", "--no-path-resolution", "--format", "json"], { cwd: dir, encoding: "utf8", timeout: CONFIG_TIMEOUT });
+  const error = r.error as NodeJS.ErrnoException | undefined;
+  if (error?.code === "ENOENT") return notChecked("docker not found");
+  if (error) return notChecked(`docker compose config: ${error.message}`);
+  if (r.status !== 0) return notChecked(`docker compose config: ${r.stderr.trim().split("\n")[0] || `exit code ${r.status}`}`);
+  let config: Config;
+  try {
+    config = JSON.parse(r.stdout) as Config;
+  } catch {
+    return notChecked("docker compose config printed no JSON");
+  }
+  const lines = violations(config, file);
+  if (!lines.length) return console.log(`${file}: the task isolation rules hold`), 0;
+  console.log(lines.join("\n"));
+  return 1;
+}
+
+// ----------------------------------------------------------------------------
+// The task's stack — up, e2e, down
+// ----------------------------------------------------------------------------
+
+// canon task types — a copy of EST_TYPES and BRANCH_CONV_RE from skills/est/scripts/est.ts (and in skills/github/scripts/github.ts):
+// no shared module: task-env imports no other skill (tests/standards/skill-imports); the tests/standards/task-branch
+// standard keeps the parsing identical
+const TASK_TYPES = ["feat", "fix", "docs", "refactor", "perf", "test", "chore", "ci", "build", "research"];
+const TASK_BRANCH_RE = new RegExp("^(?:[\\p{L}\\p{N}_.-]+/)?(" + TASK_TYPES.join("|") + ")/(\\d{1,6})-", "iu");
+
+/** A task branch by the canon — `[<area>/]<type>/<N>-<slug>`: the type (lowercased) and the number, otherwise null. */
+export function taskBranch(branch: string): { type: string; issue: number } | null {
+  const m = TASK_BRANCH_RE.exec(branch);
+  return m ? { type: m[1]!.toLowerCase(), issue: parseInt(m[2]!, 10) } : null;
+}
+
+/**
+ * Override files Compose takes next to the compose file by itself, in its order (checked on Compose 5.6). With
+ * explicit `-f` it takes none — the script passes the project's one along with the task's override.
+ */
+const OVERRIDE_FILES = ["compose.override.yml", "compose.override.yaml", "docker-compose.override.yml", "docker-compose.override.yaml"];
+/** `docker compose up` output with an image build can be long; the default buffer would cut the run. */
+const MAX_BUFFER = 64 * 1024 * 1024;
+/** How long `up --wait` waits for healthchecks: a service that isn't healthy by then failed. */
+const WAIT_TIMEOUT = "300";
+/** Log lines of a failed service the report shows. */
+const LOG_TAIL = "20";
+
+const git = (dir: string, ...args: string[]) => {
+  const r = spawnSync("git", ["-C", dir, ...args], { encoding: "utf8" });
+  return r.status === 0 ? r.stdout.trim() : "";
+};
+
+/**
+ * `<project>` of stacks and addresses: the repository of `origin` (the last part of its URL without `.git`), without a
+ * remote — the main checkout's directory. Not the directory Compose takes by default: a worktree's is random
+ * (`session-379-…`), and stacks of one project would get different names (#393, question 6).
+ */
+export function projectName(root: string): string {
+  const url = git(root, "remote", "get-url", "origin").replace(/\/+$/, "");
+  const common = git(root, "rev-parse", "--path-format=absolute", "--git-common-dir");
+  const name = url ? url.split(/[/:]/).at(-1)!.replace(/\.git$/, "") : common ? path.basename(path.dirname(common)) : path.basename(root);
+  return hostProject(name);
+}
+
+export interface Stack {
+  /** The Compose project: `<project>-<N>`, `<project>-<N>-e2e`, `<project>` without a task. */
+  name: string;
+  /** A service's address host: `<service>.<N>.<project>.localhost`, e2e — `<service>.e2e.<N>.<project>.localhost`. */
+  host: (service: string) => string;
+}
+
+/** The stack of task `task` of `project`; without a task — the main checkout's. */
+export function stackOf(project: string, task: number | undefined, e2e = false): Stack {
+  const n = task === undefined ? [] : [String(task)];
+  const kind = e2e ? ["e2e"] : [];
+  return { name: [project, ...n, ...kind].join("-"), host: (service) => [dnsLabel(service), ...kind, ...n, project, "localhost"].join(".") };
+}
+
+
+/** The variable of a service for the e2e command: `TASK_ENV_<SERVICE>_<suffix>` (#393, question 7). */
+const varOf = (service: string, suffix: string | number) => `TASK_ENV_${service.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_${suffix}`;
+
+/**
+ * The project's settings file: `.agents/elves.json`; an install from before the rename has `.agents/ai-dev.json` until
+ * `update` moves it — read then (#545).
+ */
+const MANIFESTS = [".agents/elves.json", ".agents/ai-dev.json"];
+
+/**
+ * HTTP services of the project's stack and their ports inside the container — `env.http` of the project's settings
+ * (`MANIFESTS`, #393, question 4): in a compose file a database's port doesn't differ from an app's. No file or no
+ * field — none; a broken one — the reason, with the file read.
+ */
+export function httpServices(root: string): Record<string, number> | string {
+  const name = MANIFESTS.find((f) => existsSync(path.join(root, f)));
+  if (!name) return {};
+  let http: unknown;
+  try {
+    http = (JSON.parse(readFileSync(path.join(root, name), "utf8")) as { env?: { http?: unknown } }).env?.http ?? {};
+  } catch (e) {
+    return `${name}: ${(e as Error).message}`;
+  }
+  const bad = `env.http of ${name}: a service → its HTTP port in the container expected, like {"web": 3000}`;
+  if (typeof http !== "object" || !http || Array.isArray(http)) return bad;
+  const ports = http as Record<string, unknown>;
+  return Object.values(ports).every((p) => Number.isInteger(p) && (p as number) > 0 && (p as number) < 65536) ? (ports as Record<string, number>) : bad;
+}
+
+/** Where the task's stack lives: the worktree's root, its compose files, the project's name, the task and HTTP services. */
+interface Project {
+  root: string;
+  /** `-f` of the compose file and of the project's override file, if there is one. */
+  files: string[];
+  name: string;
+  task: number | undefined;
+  http: Record<string, number>;
+}
+
+function projectOf(cwd: string): Project | string {
+  const root = git(cwd, "rev-parse", "--show-toplevel") || cwd;
+  const file = COMPOSE_FILES.find((f) => existsSync(path.join(root, f)));
+  if (!file) return `no compose file in ${root} (${COMPOSE_FILES.join(", ")}) — the task's stack is the project's Compose`;
+  const extra = OVERRIDE_FILES.find((f) => existsSync(path.join(root, f)));
+  const http = httpServices(root);
+  if (typeof http === "string") return http;
+  const files = [file, ...(extra ? [extra] : [])].flatMap((f) => ["-f", f]);
+  return { root, files, name: projectName(root), task: taskBranch(git(root, "branch", "--show-current"))?.issue, http };
+}
+
+/** `docker compose` in cwd; vars — over the script's environment: Compose takes them into interpolation. */
+const dc = (args: string[], cwd: string, input?: string, vars: Record<string, string> = {}) =>
+  spawnSync("docker", ["compose", ...args], { cwd, input, encoding: "utf8", maxBuffer: MAX_BUFFER, env: { ...process.env, ...vars } });
+
+/**
+ * The stack's addresses for Compose's interpolation (#413): `TASK_ENV_<SERVICE>_URL` of each `env.http` service — the
+ * names the e2e command gets — so the compose file gives the app its own address (`APP_URL:
+ * ${TASK_ENV_WEB_URL:-http://localhost:3000}`). Known before `up`: the host is the stack's, the port is the proxy's. Only
+ * the environment of the script's Compose process — no file: `docker compose` by hand and CI get the compose file's
+ * default.
+ */
+const urlVars = (project: Project, stack: Stack, env: NodeJS.ProcessEnv) =>
+  Object.fromEntries(Object.keys(project.http).map((service) => [varOf(service, "URL"), addressUrl(stack.host(service), proxyPort(env))]));
+
+/**
+ * The task stack's override — the only thing the script adds to the project's Compose: the proxy's labels and network
+ * for HTTP services of the settings, nothing to the others (a database isn't published). A service's networks are its
+ * own as Compose normalized them (one without `networks` is in `default`) plus the proxy's: listed networks replace
+ * the implicit `default`, and a key with null merges with the project's keeping its aliases. The override goes to
+ * Compose's stdin (`-f -`), not into a file: a `compose.override.yaml` would be the project's, and `check` would name
+ * its external network. No HTTP service in the compose file — no override.
+ */
+function overrideOf(config: Config, http: Record<string, number>, stack: Stack, proxy: string): object | undefined {
+  const services: Record<string, object> = {};
+  for (const [service, port] of Object.entries(http)) {
+    const s = config.services?.[service];
+    if (!s) continue;
+    const networks = Object.fromEntries([...Object.keys(s.networks ?? { default: null }), proxy].map((n) => [n, null]));
+    services[service] = { networks, labels: proxyLabels({ stack: stack.name, service: dnsLabel(service), host: stack.host(service), port, network: proxy }) };
+  }
+  if (!Object.keys(services).length) return undefined;
+  return { services, networks: { [proxy]: { external: true } } };
+}
+
+/** A container of `docker compose ps --format json`. */
+interface Container {
+  Name: string;
+  Service: string;
+  State: string;
+  Health?: string;
+  ExitCode?: number;
+  Publishers?: { URL?: string; TargetPort: number; PublishedPort: number; Protocol?: string }[] | null;
+}
+
+/** Containers of a stack by its Compose project, from any directory — Compose finds them by labels; all — stopped too. */
+function containers(stack: string, all = false): Container[] {
+  const r = dc(["-p", stack, "ps", ...(all ? ["--all"] : []), "--format", "json"], "/");
+  const out = r.status === 0 ? r.stdout.trim() : "";
+  if (!out) return [];
+  // Compose prints a container per line; before 2.21 — one JSON array
+  return out.startsWith("[") ? (JSON.parse(out) as Container[]) : out.split("\n").map((l) => JSON.parse(l) as Container);
+}
+
+/** Did a container fail: not running, not healthy; a one-shot that exited with 0 did its job. */
+const failed = (c: Container) => (c.State !== "running" && !(c.State === "exited" && c.ExitCode === 0)) || c.Health === "unhealthy" || c.Health === "starting";
+
+/** The last healthcheck's output of a container: why it isn't healthy. */
+function healthOf(container: string): string {
+  const r = spawnSync("docker", ["inspect", "--format", "{{json .State.Health}}", container], { encoding: "utf8" });
+  try {
+    const last = (JSON.parse(r.stdout) as { Log?: { ExitCode: number; Output: string }[] }).Log?.at(-1);
+    return last ? `exit ${last.ExitCode}${last.Output.trim() ? ` — ${last.Output.trim().split("\n").slice(-3).join(" ")}` : ""}` : "no result yet";
+  } catch {
+    return why(r);
+  }
+}
+
+/**
+ * A stack that didn't come up: each failed service — its state and the last lines of its log (#393, question 5); no
+ * container failed (an image isn't pulled, a build broke) — Compose's own answer.
+ */
+function report(stack: string, r: ReturnType<typeof spawnSync>, env: NodeJS.ProcessEnv): string[] {
+  const out = [`stack ${stack}: not up — ${why(r)}${hint(why(r), env)}`];
+  for (const c of containers(stack, true).filter(failed)) {
+    const state = [c.State === "exited" ? `exited (exit ${c.ExitCode})` : c.State, c.Health].filter(Boolean).join(", ");
+    out.push(`✗ ${c.Service}: ${state}`);
+    if (c.Health === "unhealthy") out.push(`    healthcheck: ${healthOf(c.Name)}`);
+    const logs = dc(["-p", stack, "logs", "--no-color", "--no-log-prefix", "--tail", LOG_TAIL, c.Service], "/");
+    for (const l of `${logs.stdout}${logs.stderr}`.trimEnd().split("\n").filter(Boolean)) out.push(`    | ${l}`);
+  }
+  // Compose's progress lines (a resource and its step) say nothing about the failure
+  const progress = /^\s*(?:Network|Volume|Container|Image)\s+\S+\s+(?:Creat|Start|Wait|Pull|Build|Healthy|Running|Recreat)\w*\s*$/;
+  if (out.length === 1) for (const l of `${r.stderr ?? ""}`.trimEnd().split("\n").filter((l) => l.trim() && !progress.test(l)).slice(-15)) out.push(`    | ${l}`);
+  return out;
+}
+
+/** An address of a stack's service: a URL through the proxy or a published port on the loopback, with its variable. */
+interface Address {
+  service: string;
+  value: string;
+  name: string;
+  note?: string;
+}
+
+/** Addresses of the running services: HTTP ones of the settings through the proxy, every published port on 127.0.0.1. */
+function addressesOf(project: Project, stack: Stack, env: NodeJS.ProcessEnv): Address[] {
+  const out: Address[] = [];
+  const running = containers(stack.name).filter((c) => c.State === "running");
+  for (const service of [...new Set(running.map((c) => c.Service))].sort()) {
+    if (project.http[service]) out.push({ service, value: addressUrl(stack.host(service), proxyPort(env)), name: varOf(service, "URL") });
+    const seen = new Set<string>();
+    for (const p of running.find((c) => c.Service === service)!.Publishers ?? []) {
+      const proto = p.Protocol && p.Protocol !== "tcp" ? `/${p.Protocol}` : "";
+      if (!p.PublishedPort || seen.has(`${p.TargetPort}${proto}`)) continue;
+      seen.add(`${p.TargetPort}${proto}`);
+      const ip = !p.URL || p.URL === "0.0.0.0" || p.URL === "::" ? "127.0.0.1" : p.URL;
+      out.push({ service, value: `${ip}:${p.PublishedPort}`, name: varOf(service, `${p.TargetPort}${proto ? `_${p.Protocol!.toUpperCase()}` : ""}`), note: `→ ${p.TargetPort}${proto}` });
+    }
+  }
+  return out;
+}
+
+/**
+ * Brings the stack up: the project's compose files plus the override, `up --wait` with a build — the stack runs the
+ * worktree's code, not an image from another task's run. The proxy goes up first when the override joins its network
+ * and it isn't running (#393, question 8); a running one isn't touched. Both Compose calls get the stack's addresses
+ * for interpolation — `config` too: a required `${TASK_ENV_WEB_URL:?…}` would fail it.
+ */
+function upStack(project: Project, stack: Stack, profiles: string[], env: NodeJS.ProcessEnv): { code: number; lines: string[] } {
+  const vars = urlVars(project, stack, env);
+  const config = dc([...project.files, "--profile", "*", "config", "--format", "json"], project.root, undefined, vars);
+  if (config.error || config.status !== 0) return { code: 2, lines: [`stack ${stack.name}: not started — docker compose config: ${why(config)}${hint(why(config), env)}`] };
+  const parsed = JSON.parse(config.stdout) as Config;
+  const lines = Object.keys(project.http)
+    .filter((s) => !parsed.services?.[s])
+    .map((s) => `! env.http: service ${s} isn't in the compose file — no address for it`);
+  const override = overrideOf(parsed, project.http, stack, proxyName(env));
+  if (override) {
+    const running = proxyRunning(env);
+    if (typeof running === "string") return { code: 2, lines: [...lines, `stack ${stack.name}: not started — Docker unavailable: ${running}${hint(running, env)}`] };
+    if (!running) {
+      const p = up(env);
+      if (p.code) return { code: 2, lines: [...lines, p.out] };
+    }
+  }
+  const args = ["-p", stack.name, ...project.files, ...(override ? ["-f", "-"] : []), ...profiles.flatMap((p) => ["--profile", p])];
+  const r = dc([...args, "--progress", "plain", "up", "--detach", "--wait", "--wait-timeout", WAIT_TIMEOUT, "--build", "--remove-orphans", "--quiet-pull"], project.root, override ? JSON.stringify(override) : undefined, vars);
+  if (r.error || r.status !== 0) return { code: r.error ? 2 : 1, lines: [...lines, ...report(stack.name, r, env)] };
+  return { code: 0, lines };
+}
+
+/**
+ * Takes a stack down with its volumes — by the Compose project from `/`, without the compose file: it may be gone
+ * already (`task close` after the worktree), and a compose file found by Compose would hide services of other profiles.
+ * Compose finds the stack's containers, networks and volumes by their labels — a stack left with volumes only too.
+ */
+function downStack(stack: string, env: NodeJS.ProcessEnv): { ok: boolean; line: string } {
+  const r = dc(["-p", stack, "down", "--volumes", "--remove-orphans"], "/");
+  const ok = !r.error && r.status === 0;
+  return { ok, line: ok ? `+ stack ${stack}: down, with its volumes` : `! stack ${stack}: not removed — ${why(r)}${hint(why(r), env)}` };
+}
+
+/** The label Compose marks a stack's containers, volumes and networks with: the Compose project. */
+const PROJECT_LABEL = "com.docker.compose.project";
+/** Compose projects on the machine → the directories of their containers; no docker — missing, Docker unavailable — the reason. */
+type Machine = Map<string, Set<string>> | { missing: true } | string;
+
+/**
+ * Stacks on the machine — by the label of containers, volumes and networks, not `docker compose ls`: a stack whose
+ * containers are gone but volumes stay (`down` without `-v`, containers removed by hand) isn't in its list (#395,
+ * question 2). A container's directory (`working_dir` — where Compose ran) tells a stack of another repository with the
+ * same name (`prune`).
+ */
+function machineStacks(env: NodeJS.ProcessEnv): Machine {
+  const stacks = new Map<string, Set<string>>();
+  for (const list of [["ps", "--all"], ["volume", "ls"], ["network", "ls"]]) {
+    const format = list[0] === "ps" ? `{{.Label "${PROJECT_LABEL}"}}\t{{.Label "${PROJECT_LABEL}.working_dir"}}` : `{{.Label "${PROJECT_LABEL}"}}`;
+    const r = spawnSync("docker", [...list, "--filter", `label=${PROJECT_LABEL}`, "--format", format], { encoding: "utf8", env, timeout: CONFIG_TIMEOUT });
+    if ((r.error as NodeJS.ErrnoException | undefined)?.code === "ENOENT") return { missing: true };
+    if (r.error || r.status !== 0) return why(r);
+    for (const line of r.stdout.split("\n")) {
+      const [name, dir] = line.split("\t");
+      if (!name?.trim()) continue;
+      const dirs = stacks.get(name.trim()) ?? new Set<string>();
+      if (dir?.trim()) dirs.add(dir.trim());
+      stacks.set(name.trim(), dirs);
+    }
+  }
+  return stacks;
+}
+
+/** Address lines: the service column aligned; withVar — the variable the e2e command gets it in. */
+function shown(addresses: Address[], withVar: boolean): string[] {
+  const width = Math.max(0, ...addresses.map((a) => a.service.length));
+  return addresses.map((a) => `  ${a.service.padEnd(width)}  ${a.value}${a.note ? ` ${a.note}` : ""}${withVar ? `  ${a.name}` : ""}`);
+}
+
+/** `up`: the dev stack of the branch's task (without one — the main checkout's) and its addresses. */
+function stackUp(project: Project, profiles: string[], env: NodeJS.ProcessEnv): number {
+  const stack = stackOf(project.name, project.task);
+  const r = upStack(project, stack, profiles, env);
+  if (r.code) return console.log(r.lines.join("\n")), r.code;
+  const addresses = addressesOf(project, stack, env);
+  console.log([...r.lines, `stack ${stack.name}: up${addresses.length ? "" : " — no HTTP service in env.http and no published port"}`, ...shown(addresses, false)].join("\n"));
+  console.log(`logs: docker compose -p ${stack.name} logs <service>; down: bun --no-env-file ${fileURLToPath(import.meta.url)} down${project.task === undefined ? "" : ` ${project.task}`}`);
+  return 0;
+}
+
+/**
+ * `e2e`: the task's e2e stack anew — with clean volumes, apart from the dev stack — then the run command on the host
+ * with the e2e addresses in variables; the exit code is the command's. The stack stays until the next run: a failed
+ * run is examined on it.
+ */
+function stackE2e(project: Project, profiles: string[], command: string[], env: NodeJS.ProcessEnv): number {
+  const stack = stackOf(project.name, project.task, true);
+  const clean = downStack(stack.name, env);
+  if (!clean.ok) return console.log(clean.line), 2;
+  const r = upStack(project, stack, profiles, env);
+  if (r.code) return console.log(r.lines.join("\n")), r.code;
+  const addresses = addressesOf(project, stack, env);
+  console.log([...r.lines, `stack ${stack.name}: up, clean volumes — TASK_ENV_PROJECT=${stack.name}`, ...shown(addresses, true)].join("\n"));
+  if (!command.length) return 0;
+  const vars = Object.fromEntries([["TASK_ENV_PROJECT", stack.name], ...addresses.map((a) => [a.name, a.value])]);
+  const run = spawnSync(command[0]!, command.slice(1), { stdio: "inherit", env: { ...env, ...vars } });
+  if (run.error) return console.log(`e2e: ${command[0]} not started — ${run.error.message}`), 2;
+  return run.status ?? 1;
+}
+
+/**
+ * `down`: the task's stacks — dev and e2e — with their volumes, those that are on the machine; stacks of other tasks
+ * aren't touched. A checkout without a compose file has no task stacks: Docker isn't called — `task close` of every
+ * project calls `down`, and with Docker stopped a project without Compose would get a `!` line (#395, question 4).
+ */
+function stackDown(root: string, task: number | undefined, env: NodeJS.ProcessEnv): number {
+  if (!COMPOSE_FILES.some((f) => existsSync(path.join(root, f)))) return console.log(`○ no compose file in ${root} — the project has no task stacks`), 0;
+  const name = projectName(root);
+  const stacks = [stackOf(name, task), stackOf(name, task, true)].map((s) => s.name);
+  const machine = machineStacks(env);
+  if (typeof machine === "string") return console.log(`! stacks ${stacks.join(", ")}: not removed — Docker unavailable: ${machine}${hint(machine, env)}`), 2;
+  if (!(machine instanceof Map)) return console.log("○ no Docker on the machine — no task stacks"), 0;
+  const present = stacks.filter((s) => machine.has(s));
+  if (!present.length) return console.log(`○ stacks ${stacks.join(", ")}: none on the machine`), 0;
+  const done = present.map((s) => downStack(s, env));
+  console.log(done.map((d) => d.line).join("\n"));
+  return done.every((d) => d.ok) ? 0 : 2;
+}
+
+// The checkout's GitHub repository by its origin — a copy of originRepo from skills/est/scripts/est.ts and skills/github/scripts/github.ts:
+// no shared module: task-env imports no other skill (tests/standards/skill-imports); the tests/standards/origin-repo
+// standard keeps the parsing identical
+const ORIGIN_RE = /^(?:[a-z][a-z\d+.-]*:\/\/(?:[^@/\s]+@)?(?:ssh\.)?github\.com(?::\d+)?\/|(?:[^@/\s:]+@)?(?:ssh\.)?github\.com:)([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/i;
+
+/** `owner/repo` of a GitHub origin URL (host github.com or ssh.github.com, any case, with a port), otherwise null. */
+export function originRepo(url: string): string | null {
+  const m = ORIGIN_RE.exec(url.trim());
+  return m ? `${m[1]}/${m[2]}` : null;
+}
+
+/** A task's state on GitHub (`gh api`): open, closed, missing — no such issue (a PR isn't a task); otherwise why not known. */
+function taskState(repo: string, n: number, env: NodeJS.ProcessEnv): "open" | "closed" | "missing" | { error: string } {
+  const r = spawnSync("gh", ["api", `repos/${repo}/issues/${n}`], { encoding: "utf8", env, timeout: 30_000 });
+  if ((r.error as NodeJS.ErrnoException | undefined)?.code === "ENOENT") return { error: "gh not found — prune checks tasks on GitHub with the gh CLI" };
+  if (r.error) return { error: r.error.message };
+  if (r.status !== 0) return /HTTP 404|Not Found/i.test(r.stderr) ? "missing" : { error: r.stderr.trim().split("\n").at(-1) || `gh: code ${r.status}` };
+  try {
+    const issue = JSON.parse(r.stdout) as { state?: string; pull_request?: unknown };
+    if (issue.pull_request) return "missing";
+    return issue.state === "closed" ? "closed" : issue.state === "open" ? "open" : { error: `gh: state ${issue.state}` };
+  } catch {
+    return { error: "gh printed no JSON" };
+  }
+}
+
+/**
+ * `prune`: stacks of the project's closed tasks left on the machine — orphans: a task closed without `task close`, a
+ * close that couldn't reach Docker, a task that removed the compose file. The stacks `<project>-<N>` and
+ * `<project>-<N>-e2e` of the machine (containers, volumes and networks, #395, question 2); the task's state — by GitHub:
+ * closed — the stacks go with their volumes; open, not an issue, not checked — left. A stack whose containers ran in an
+ * existing directory of another project — another repository with the same name (`shop-2` at the project `shop`) —
+ * left (#395, question 3). Without confirmation: a closed task's stack is nobody's (#395, question 1).
+ */
+function prune(root: string, env: NodeJS.ProcessEnv): number {
+  const name = projectName(root);
+  const machine = machineStacks(env);
+  if (typeof machine === "string") return console.log(`! prune: Docker unavailable — ${machine}${hint(machine, env)}`), 2;
+  if (!(machine instanceof Map)) return console.log("○ no Docker on the machine — no task stacks"), 0;
+  const re = new RegExp(`^${name}-(\\d+)(-e2e)?$`);
+  const found = [...machine.keys()]
+    .map((stack) => ({ stack, m: re.exec(stack) }))
+    .filter((x) => x.m)
+    .map(({ stack, m }) => ({ stack, task: Number(m![1]), e2e: !!m![2] }))
+    .sort((a, b) => a.task - b.task || Number(a.e2e) - Number(b.e2e));
+  if (!found.length) return console.log(`○ no stacks of ${name} tasks on the machine`), 0;
+  const repo = originRepo(git(root, "remote", "get-url", "origin"));
+  if (!repo) return console.log(`! prune: the origin of ${root} isn't a GitHub repository — task states can't be checked; left: ${found.map((f) => f.stack).join(", ")}`), 2;
+  const states = new Map<number, ReturnType<typeof taskState>>();
+  let ok = true;
+  for (const { stack, task } of found) {
+    const other = [...machine.get(stack)!].find((dir) => existsSync(dir) && projectName(dir) !== name);
+    if (other) {
+      console.log(`○ stack ${stack}: its containers are from ${other} — another project, left`);
+      continue;
+    }
+    if (!states.has(task)) states.set(task, taskState(repo, task, env));
+    const state = states.get(task)!;
+    if (state === "closed") {
+      const d = downStack(stack, env);
+      console.log(d.ok ? `${d.line} — task #${task} is closed` : d.line);
+      ok &&= d.ok;
+    } else if (state === "open") console.log(`○ stack ${stack}: task #${task} is open — left`);
+    else if (state === "missing") console.log(`○ stack ${stack}: no task #${task} in ${repo} — left`);
+    else {
+      console.log(`! stack ${stack}: task #${task} not checked — ${state.error}; left`);
+      ok = false;
+    }
+  }
+  return ok ? 0 : 2;
+}
+
+/** `--profile <name>` options of `up` and `e2e` before the command: the profiles and what follows them. */
+function profilesOf(args: string[]): { profiles: string[]; rest: string[] } | undefined {
+  const profiles: string[] = [];
+  let i = 0;
+  for (; i < args.length && args[i] !== "--"; i++) {
+    if (args[i] !== "--profile" || !args[i + 1]) return undefined;
+    profiles.push(args[++i]!);
+  }
+  return { profiles, rest: args.slice(i + 1) };
+}
+
+/** The stack commands: undefined — not one of them or wrong arguments. */
+function stackCommand(group: string, args: string[], env: NodeJS.ProcessEnv): number | undefined {
+  if (group !== "up" && group !== "e2e" && group !== "down" && group !== "prune") return undefined;
+  if (group === "down" || group === "prune") {
+    if (group === "prune" ? args.length : args.length > 1 || (args[0] && !/^\d+$/.test(args[0]))) return undefined;
+    // the stacks are found by the Compose project: the task's worktree may be gone already
+    const root = git(process.cwd(), "rev-parse", "--show-toplevel") || process.cwd();
+    if (group === "prune") return prune(root, env);
+    return stackDown(root, args[0] ? Number(args[0]) : taskBranch(git(root, "branch", "--show-current"))?.issue, env);
+  }
+  const opts = profilesOf(args);
+  if (!opts || (group === "up" && opts.rest.length)) return undefined;
+  const project = projectOf(process.cwd());
+  if (typeof project === "string") return console.log(`task-env ${group}: ${project}`), 2;
+  return group === "up" ? stackUp(project, opts.profiles, env) : stackE2e(project, opts.profiles, opts.rest, env);
+}
+
+const COMMANDS: Record<string, (env: NodeJS.ProcessEnv) => Result> = { up, down, status };
+
+function main(argv: string[]): number {
+  const help = helpOf(argv);
+  if (help) return process.stdout.write(help + "\n"), 0;
+  const command = commandOf(argv);
+  const usage = () => (process.stderr.write(`${command ? HELP[command] : OVERVIEW}\n`), 2);
+  if (!command) return usage();
+  const [group, cmd = "", ...rest] = argv;
+  if (group === "check" && !rest.length && !cmd.startsWith("-")) return check(path.resolve(cmd || "."));
+  const stack = stackCommand(group!, argv.slice(1), process.env);
+  if (stack !== undefined) return stack;
+  const fn = group === "proxy" && !rest.length ? COMMANDS[cmd] : undefined;
+  if (!fn) return usage();
+  const r = fn(process.env);
+  (r.code === 2 ? process.stderr : process.stdout).write(r.out + "\n");
+  return r.code;
+}
+
+if (import.meta.main) process.exitCode = main(process.argv.slice(2));