@codions/portta 0.0.0-develop.147.sha-1859ad1

package/dist/runtime/docker/images/apply/Dockerfile

@@ -0,0 +1,45 @@
+# ============================================================================
+# Portta applier
+# ============================================================================
+# The one image that may drive Compose on the host, so that a settings change
+# saved in the panel can be applied without a terminal.
+#
+# It exists because Traefik reads its static configuration from the environment
+# its container was created with (docs/development/adr/0003-traefik-static-config-via-env.md):
+# a saved setting needs the containers *recreated*, and recreating them means
+# Compose, which the panel deliberately cannot reach
+# (docs/development/adr/0008-web-panel-socket-proxy.md).
+#
+# Built on demand and cached locally, like the toolbox; never published. Off
+# unless PORTTA_APPLY=true. See docs/development/adr/0026-applying-settings-from-the-panel.md.
+#
+# Node runs the packaged Portta CLI; Bash remains only for the closed project
+# runner command.
+#
+# buildx, because `up` passes --build on a repository checkout. Nothing is built
+# in here: the context is streamed over the mounted socket and the host daemon
+# does the work, with the host's network and layer cache. The plugin is only how
+# the compose CLI reaches that daemon, which is why --network none is no
+# obstacle -- and why this image needs no toolchain of its own.
+# ============================================================================
+FROM alpine:3.24.1
+
+ARG PORTTA_VERSION
+
+# Pinned base, unpinned packages: Alpine's repositories only carry the current
+# patch level for a release, so `apk add` inside 3.24.1 is already constrained.
+RUN apk add --no-cache \
+      bash \
+      nodejs \
+      docker-cli \
+      docker-cli-buildx \
+      docker-cli-compose
+
+LABEL org.opencontainers.image.title="portta-apply" \
+      org.opencontainers.image.description="Recreates Portta's own containers on the host" \
+      org.opencontainers.image.version="$PORTTA_VERSION" \
+      org.opencontainers.image.source="https://github.com/codions-labs/portta" \
+      org.opencontainers.image.licenses="MIT"
+
+ENTRYPOINT []
+CMD ["/bin/bash"]

package/dist/runtime/docker/images/sandbox/Dockerfile

@@ -0,0 +1,79 @@
+# syntax=docker/dockerfile:1.7
+
+FROM node:24-bookworm-slim
+
+ENV AWS_DEFAULT_REGION=auto \
+    DEBIAN_FRONTEND=noninteractive \
+    DISABLE_UPDATES=1 \
+    NPM_CONFIG_PREFIX=/usr/local \
+    PATH="/root/.local/bin:/usr/local/bin:/root/.bun/bin:/root/.cargo/bin:${PATH}" \
+    PLAYWRIGHT_BROWSERS_PATH=/ms-playwright \
+    PORTTA_FLOW_SANDBOX_MANIFEST=/etc/taskflow-sandbox/manifest.json
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        build-essential \
+        ca-certificates \
+        curl \
+        git \
+        gnupg \
+        groff \
+        jq \
+        less \
+        openssh-client \
+        ripgrep \
+        sudo \
+        unzip \
+    && rm -rf /var/lib/apt/lists/*
+
+ARG TARGETARCH
+ARG ASCIINEMA_VERSION=3.2.1
+ARG ASCIINEMA_SHA256_AMD64=1b405bbda565b33c3c4718de67fedc3535580603c0694b1ff3fb04f363430a20
+ARG ASCIINEMA_SHA256_ARM64=b516a6d896844c0ffbc96e0a55afe4cbcc79216abde0fc64fdda4e39bee421ea
+
+RUN case "${TARGETARCH}" in \
+        amd64) target=x86_64; sha256="${ASCIINEMA_SHA256_AMD64}" ;; \
+        arm64) target=aarch64; sha256="${ASCIINEMA_SHA256_ARM64}" ;; \
+        *) echo "Unsupported asciinema architecture: ${TARGETARCH}" >&2; exit 1 ;; \
+    esac \
+    && curl -fsSL -o /usr/local/bin/asciinema \
+        "https://github.com/asciinema/asciinema/releases/download/v${ASCIINEMA_VERSION}/asciinema-${target}-unknown-linux-gnu" \
+    && echo "${sha256}  /usr/local/bin/asciinema" | sha256sum -c - \
+    && chmod 0755 /usr/local/bin/asciinema
+
+COPY --chmod=0755 agents/ /usr/local/lib/taskflow-sandbox/agents/
+COPY --chmod=0755 scripts/ /usr/local/lib/taskflow-sandbox/scripts/
+
+ARG BUILD_DATE=unknown
+ARG BUILD_ID=local
+ARG SANDBOX_VERSION=dev
+ARG TOOLS_REFRESH=local
+ARG VCS_REF=unknown
+
+# TOOLS_REFRESH deliberately invalidates only the high-cadence tool layer.
+RUN echo "Refreshing volatile tools: ${TOOLS_REFRESH}" \
+    && TARGETARCH="${TARGETARCH}" /usr/local/lib/taskflow-sandbox/scripts/install-tools.sh \
+    && install -d -m 0755 /etc/taskflow-sandbox \
+    && SANDBOX_VERSION="${SANDBOX_VERSION}" \
+       BUILD_DATE="${BUILD_DATE}" \
+       BUILD_ID="${BUILD_ID}" \
+       VCS_REF="${VCS_REF}" \
+       node /usr/local/lib/taskflow-sandbox/scripts/generate-manifest.mjs "${PORTTA_FLOW_SANDBOX_MANIFEST}" \
+    && /usr/local/lib/taskflow-sandbox/scripts/verify-image.sh
+
+# Task Flow runs containers with the host UID/GID. Keep HOME traversable and
+# writable while tools remain installed read-only under /usr/local.
+RUN usermod -l agent -d /root -s /bin/bash node \
+    && echo "agent ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/agent \
+    && chmod 0440 /etc/sudoers.d/agent \
+    && chmod -R 0777 /root /ms-playwright \
+    && ln -sf /usr/local/lib/taskflow-sandbox/scripts/entrypoint.sh /usr/local/bin/entrypoint.sh
+
+LABEL org.opencontainers.image.created="${BUILD_DATE}" \
+      org.opencontainers.image.description="Universal Task Flow agent sandbox" \
+      org.opencontainers.image.revision="${VCS_REF}" \
+      org.opencontainers.image.source="https://github.com/codions-labs/task-flow" \
+      org.opencontainers.image.title="Task Flow Sandbox" \
+      org.opencontainers.image.version="${SANDBOX_VERSION}"
+
+CMD ["sleep", "infinity"]

package/dist/runtime/docker/images/sandbox/README.md

@@ -0,0 +1,109 @@
+# Task Flow Sandbox
+
+The official universal sandbox image is published as:
+
+```text
+ghcr.io/codions-labs/portta-sandbox
+```
+
+It contains the four agent providers supported by Task Flow workflows: Codex,
+Claude Code, OpenCode, and Pi. It also includes GitHub CLI, AWS CLI,
+Playwright/Chromium, Mermaid CLI, asciinema, Git, Node.js 24, and common build
+utilities.
+
+## Build locally
+
+The build context is this directory. `TOOLS_REFRESH` invalidates the volatile
+tool layer without invalidating the base OS/runtime layers.
+
+```bash
+docker buildx build \
+  --load \
+  --platform linux/arm64 \
+  --build-arg SANDBOX_VERSION="$(tr -d '[:space:]' < VERSION)" \
+  --build-arg TOOLS_REFRESH="$(date -u +%Y%m%dT%H%M%SZ)" \
+  --tag portta-sandbox:local \
+  .
+```
+
+Use `linux/amd64` on x86_64 hosts. Validate the result with:
+
+```bash
+docker run --rm --entrypoint /usr/local/lib/taskflow-sandbox/scripts/verify-image.sh portta-sandbox:local
+docker run --rm --entrypoint cat portta-sandbox:local /etc/taskflow-sandbox/manifest.json
+```
+
+## Versions and tags
+
+`VERSION` is the version of the sandbox architecture, not the versions of the
+agents. A rebuild can keep the same sandbox version while resolving newer
+stable agent releases.
+
+- `rolling`: latest main-branch, scheduled, or manually refreshed build.
+- `edge`: latest develop-branch build.
+- `build-YYYYMMDD-<run-id>-<attempt>`: immutable build identity.
+- `X.Y.Z`: immutable structural release.
+- `X.Y`, `X`, and `latest`: aliases advanced only by a new structural release.
+
+Publish a structural release by creating a GitHub Release whose tag is
+`sandbox-vX.Y.Z`. The tag version must match `VERSION`. Re-running ordinary or
+scheduled builds never overwrites `X.Y.Z` or `latest`; it advances `rolling`.
+
+The exact versions in each architecture are stored at
+`/etc/taskflow-sandbox/manifest.json`, uploaded as workflow artifacts, and
+printed in the workflow summary. For strict rollback or reproduction, use the
+image digest or an immutable `build-*` tag.
+
+## Refresh and cache policy
+
+The workflow supplies a unique `TOOLS_REFRESH` value for every run. Structural
+layers remain cacheable, while signed APT repositories and npm stable tags are
+resolved again for the volatile tools. No tool version edit or synthetic commit
+is required: dispatch the workflow on `main` to refresh `rolling`.
+
+A weekly Monday build refreshes the rolling image. Weekly, rather than daily,
+limits two-architecture build minutes and immutable build-tag storage growth;
+`workflow_dispatch` remains the fast path when an important agent release lands.
+
+Claude Code is installed from Anthropic's signed stable APT channel. GitHub CLI
+uses its signed stable APT repository. Codex, OpenCode, and Pi use the official
+npm packages and their stable `latest` tags. A deliberate upstream regression
+should be handled by temporarily pinning inside the affected agent installer,
+then removing the pin after compatibility is restored.
+
+## Image architecture
+
+The first release uses one universal image:
+
+| Strategy | Decision |
+| --- | --- |
+| Universal image | Selected. It gives local, CI, VPS, and ephemeral environments the same warm toolset with no provisioning delay. |
+| Base plus agent variants | Deferred until image size or an agent incompatibility is measured; combinations would otherwise multiply tags and builds. |
+| Minimal base plus dynamic installs | Rejected as the default because startup would depend on registry availability and would be harder to audit and cache. |
+| Runtime plugin layers | Kept as a possible future distribution mechanism if independent agent release/security policies become necessary. |
+
+Agent installers are isolated files even though the delivered image is universal,
+so a future variant can reuse the same scripts and BuildKit layers instead of
+forking Dockerfiles.
+
+## Sandbox version policy
+
+Tool-only refreshes do not change `VERSION`. Bump its patch component for a
+backward-compatible image/configuration fix, its minor component for a new
+sandbox capability or supported agent, and its major component for a breaking
+runtime contract. A future reproducible-build mode can consume a saved manifest;
+until then, the immutable image digest is the exact replay and rollback identity.
+
+## Adding an agent
+
+Add one installer under `agents/`, call it from `scripts/install-tools.sh`, and
+add its version command to `scripts/generate-manifest.mjs` and
+`scripts/verify-image.sh`. Keep a single universal image until an agent has a
+demonstrated incompatibility or size requirement that justifies a variant.
+
+## Registry setup
+
+The publish job uses `GITHUB_TOKEN` and grants `packages: write` only to that
+job. The organization must allow GitHub Actions to create packages. After the
+first publication, make the `portta-sandbox` package public in the GHCR
+package settings; package visibility cannot be changed by the build workflow.

package/dist/runtime/docker/images/sandbox/VERSION

@@ -0,0 +1 @@
+0.1.0

package/dist/runtime/docker/images/sandbox/agents/claude-code.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+set -euo pipefail
+
+key=/tmp/claude-code.asc
+keyring=/etc/apt/keyrings/claude-code.asc
+fingerprint=31DDDE24DDFAB679F42D7BD2BAA929FF1A7ECACE
+
+install -d -m 0755 /etc/apt/keyrings
+curl -fsSL https://downloads.claude.ai/keys/claude-code.asc -o "$key"
+actual_fingerprint="$(gpg --show-keys --with-colons "$key" | awk -F: '$1 == "fpr" { print $10; exit }')"
+test "$actual_fingerprint" = "$fingerprint"
+install -m 0644 "$key" "$keyring"
+echo "deb [signed-by=$keyring] https://downloads.claude.ai/claude-code/apt/stable stable main" \
+  > /etc/apt/sources.list.d/claude-code.list
+apt-get update
+apt-get install -y --no-install-recommends claude-code
+rm -f "$key"
+rm -rf /var/lib/apt/lists/*

package/dist/runtime/docker/images/sandbox/agents/codex.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+set -euo pipefail
+
+npm install --global --no-audit --no-fund @openai/codex@latest

package/dist/runtime/docker/images/sandbox/agents/opencode.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+set -euo pipefail
+
+npm install --global --allow-scripts=opencode-ai --no-audit --no-fund opencode-ai@latest

package/dist/runtime/docker/images/sandbox/agents/pi.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+set -euo pipefail
+
+npm install --global --ignore-scripts --no-audit --no-fund @earendil-works/pi-coding-agent@latest

package/dist/runtime/docker/images/sandbox/scripts/entrypoint.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+set -euo pipefail
+
+if [ -f "$PWD/package-lock.json" ]; then
+  npm ci 2>/dev/null || npm install
+fi
+
+exec "$@"

package/dist/runtime/docker/images/sandbox/scripts/generate-manifest.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+
+import { execFileSync, spawnSync } from 'node:child_process'
+import { readFileSync, writeFileSync } from 'node:fs'
+import { arch } from 'node:os'
+
+function output(command, args) {
+  const result = spawnSync(command, args, { encoding: 'utf8' })
+  if (result.status !== 0) {
+    throw new Error(`${command} ${args.join(' ')} failed: ${result.stderr.trim()}`)
+  }
+  const value = `${result.stdout}\n${result.stderr}`
+  return value
+    .split('\n')
+    .map((line) => line.trim())
+    .find(Boolean)
+}
+
+function osRelease() {
+  return Object.fromEntries(
+    readFileSync('/etc/os-release', 'utf8')
+      .split('\n')
+      .filter((line) => line.includes('='))
+      .map((line) => {
+        const index = line.indexOf('=')
+        return [line.slice(0, index), line.slice(index + 1).replace(/^"|"$/g, '')]
+      }),
+  )
+}
+
+const chromium = execFileSync(
+  'find',
+  [
+    process.env.PLAYWRIGHT_BROWSERS_PATH ?? '/ms-playwright',
+    '-type',
+    'f',
+    '(',
+    '-name',
+    'chrome-headless-shell',
+    '-o',
+    '-name',
+    'headless_shell',
+    ')',
+    '-executable',
+    '-print',
+    '-quit',
+  ],
+  { encoding: 'utf8' },
+).trim()
+
+if (!chromium) throw new Error('Playwright Chromium executable was not found')
+
+const os = osRelease()
+const manifest = {
+  schemaVersion: 1,
+  sandbox: {
+    version: process.env.SANDBOX_VERSION ?? 'unknown',
+    builtAt: process.env.BUILD_DATE ?? 'unknown',
+    buildId: process.env.BUILD_ID ?? 'local',
+    gitRevision: process.env.VCS_REF ?? 'unknown',
+    platform: `linux/${arch() === 'x64' ? 'amd64' : arch()}`,
+    base: `${os.PRETTY_NAME ?? os.ID ?? 'Linux'}`,
+  },
+  tools: {
+    node: output('node', ['--version']),
+    npm: output('npm', ['--version']),
+    git: output('git', ['--version']),
+    gh: output('gh', ['--version']),
+    aws: output('aws', ['--version']),
+    codex: output('codex', ['--version']),
+    claude: output('claude', ['--version']),
+    opencode: output('opencode', ['--version']),
+    pi: output('pi', ['--version']),
+    playwright: output('playwright', ['--version']),
+    chromium: output(chromium, ['--version', '--no-sandbox']),
+    mermaid: output('mmdc', ['--version']),
+    asciinema: output('asciinema', ['--version']),
+  },
+}
+
+writeFileSync(process.argv[2] ?? '/etc/taskflow-sandbox/manifest.json', `${JSON.stringify(manifest, null, 2)}\n`)

package/dist/runtime/docker/images/sandbox/scripts/install-tools.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+set -euo pipefail
+
+install_github_cli() {
+  install -d -m 0755 /etc/apt/keyrings
+  curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+    -o /etc/apt/keyrings/githubcli-archive-keyring.gpg
+  chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg
+  echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
+    > /etc/apt/sources.list.d/github-cli.list
+  apt-get update
+  apt-get install -y --no-install-recommends gh
+  rm -rf /var/lib/apt/lists/*
+}
+
+install_aws_cli() {
+  case "${TARGETARCH:?TARGETARCH is required}" in
+    amd64|arm64) ;;
+    *) echo "Unsupported AWS CLI architecture: ${TARGETARCH}" >&2; return 1 ;;
+  esac
+
+  curl -fsSL https://awscli.amazonaws.com/v2/install.sh -o /tmp/aws-cli-install.sh
+  chmod 0755 /tmp/aws-cli-install.sh
+  /tmp/aws-cli-install.sh --system
+  rm -f /tmp/aws-cli-install.sh
+}
+
+install_node_tools() {
+  PUPPETEER_SKIP_DOWNLOAD=true \
+    npm install --global --no-audit --no-fund @playwright/test@latest @mermaid-js/mermaid-cli@latest
+  playwright install chromium --with-deps --only-shell
+  npm cache clean --force
+
+  chromium="$(find "$PLAYWRIGHT_BROWSERS_PATH" -type f \( -name chrome-headless-shell -o -name headless_shell \) -executable | head -n 1)"
+  test -n "$chromium"
+  printf '{"args":["--no-sandbox","--disable-setuid-sandbox"],"executablePath":"%s"}\n' "$chromium" \
+    > /root/.puppeteerrc.json
+}
+
+install_github_cli
+install_aws_cli
+/usr/local/lib/taskflow-sandbox/agents/claude-code.sh
+/usr/local/lib/taskflow-sandbox/agents/codex.sh
+/usr/local/lib/taskflow-sandbox/agents/opencode.sh
+/usr/local/lib/taskflow-sandbox/agents/pi.sh
+install_node_tools

package/dist/runtime/docker/images/sandbox/scripts/verify-image.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+set -euo pipefail
+
+manifest="${PORTTA_FLOW_SANDBOX_MANIFEST:-/etc/taskflow-sandbox/manifest.json}"
+test -s "$manifest"
+
+for command in node npm git gh aws codex claude opencode pi playwright mmdc asciinema; do
+  command -v "$command" >/dev/null
+done
+
+jq -e '
+  . as $manifest |
+  $manifest.schemaVersion == 1 and
+  ($manifest.sandbox.version | length > 0) and
+  ($manifest.sandbox.platform | startswith("linux/")) and
+  (["node", "npm", "git", "gh", "aws", "codex", "claude", "opencode", "pi", "playwright", "chromium", "mermaid", "asciinema"] |
+    all(. as $tool | $manifest.tools[$tool] | type == "string" and length > 0))
+' "$manifest" >/dev/null

package/dist/runtime/docker/images/toolbox/Dockerfile

@@ -0,0 +1,38 @@
+# ============================================================================
+# Portta toolbox
+# ============================================================================
+# One small image holding the diagnostic and client tools the gateway needs, so
+# a host only ever has to provide Docker, Git and a shell.
+#
+# Built on demand and cached locally; see `portta toolbox build`.
+# ============================================================================
+FROM alpine:3.24.1
+
+ARG PORTTA_VERSION
+
+# Pinned base, unpinned packages: Alpine's repositories only carry the current
+# patch level for a release, so `apk add` inside 3.24.1 is already constrained.
+RUN apk add --no-cache \
+      bash \
+      ca-certificates \
+      curl \
+      jq \
+      bind-tools \
+      openssl \
+      socat \
+      netcat-openbsd \
+      openssh-client \
+      postgresql-client \
+      mysql-client \
+      redis \
+      iputils \
+  && update-ca-certificates
+
+LABEL org.opencontainers.image.title="portta-toolbox" \
+      org.opencontainers.image.description="Diagnostic and client tools for Portta" \
+      org.opencontainers.image.version="$PORTTA_VERSION" \
+      org.opencontainers.image.source="https://github.com/codions-labs/portta" \
+      org.opencontainers.image.licenses="MIT"
+
+ENTRYPOINT []
+CMD ["/bin/bash"]

package/dist/runtime/scripts/lib/runner-exec.sh

@@ -0,0 +1,189 @@
+#!/usr/bin/env bash
+# The command the project runner container is created with. Fixed at creation;
+# the panel supplies no argument. The request is { verb, project, flags } in
+# state/runner/request.json, plus { workingDir, configFiles } for an `up` of a
+# project that has no container left. See docs/development/adr/0030-the-panel-and-a-project-lifecycle.md.
+set -euo pipefail
+
+PORTTA_ROOT="${PORTTA_ROOT:?PORTTA_ROOT is required}"
+REQUEST="$PORTTA_ROOT/state/runner/request.json"
+HOST_ROOT=/host
+
+die() { printf 'error: %s\n' "$1" >&2; exit 1; }
+
+[ -f "$REQUEST" ] || die "no runner request at $REQUEST"
+
+# Closed fields, closed values. A full JSON parser is not needed and would be a
+# dependency this image does not have. The panel refuses a path carrying a
+# comma, a quote or a backslash before it writes the request, which is what
+# lets the list be read as text between the brackets.
+verb=$(sed -n 's/.*"verb"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$REQUEST" | head -n1)
+project=$(sed -n 's/.*"project"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$REQUEST" | head -n1)
+nocache=$(grep -q '"no-cache"' "$REQUEST" && printf '1' || printf '0')
+directory=$(grep -q '"directory"' "$REQUEST" && printf '1' || printf '0')
+request_working_dir=$(sed -n 's/.*"workingDir"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$REQUEST" | head -n1)
+request_config_files=$(sed -n 's/.*"configFiles"[[:space:]]*:[[:space:]]*\[\([^]]*\)\].*/\1/p' "$REQUEST" | head -n1 | tr -d '"')
+
+case "$verb" in
+  up|stop|restart|build|down|down-volumes) ;;
+  *) die "unknown runner verb '$verb'" ;;
+esac
+
+[[ "$project" =~ ^[A-Za-z0-9][A-Za-z0-9_.-]*$ ]] || die "refusing project name '$project'"
+
+# The bound a path from the request must satisfy, the same one
+# packages/core/src/runner.ts checks before writing it: absolute, no walk-up,
+# not `/`, not a top-level directory.
+assert_request_path() {
+  local path="$1" what="$2"
+  [[ "$path" == /* ]] || die "$what is not absolute"
+  [[ "$path" != *..* ]] || die "refusing $what that walks up"
+  [[ "$path" != "/" ]] || die "refusing / as $what"
+  case "${path#/}" in
+    */*) ;;
+    *) die "refusing a top-level directory as $what" ;;
+  esac
+}
+
+# With no container left there is no managed label to protect Portta itself.
+# Refuse both its root and descendants: a remembered request must never run a
+# consumer Compose file from the gateway checkout.
+assert_not_portta_path() {
+  local path="$1" what="$2"
+  case "$path" in
+    "$PORTTA_ROOT"|"$PORTTA_ROOT"/*) die "refusing Portta's own directory as $what" ;;
+  esac
+}
+
+id=$(docker ps -aq --filter "label=com.docker.compose.project=${project}" | head -n1)
+if [ -n "$id" ]; then
+  # A container exists: its labels are the truth, whatever the request says.
+  managed=$(docker inspect "$id" --format '{{ index .Config.Labels "portta.managed" }}' 2>/dev/null || true)
+  [ "$managed" != "true" ] || die "refusing to operate Portta's own project"
+  working_dir=$(docker inspect "$id" --format '{{ index .Config.Labels "com.docker.compose.project.working_dir" }}')
+  config_files=$(docker inspect "$id" --format '{{ index .Config.Labels "com.docker.compose.project.config_files" }}')
+else
+  # Nothing left to read labels from: only `up` makes sense, and only with the
+  # paths the panel remembered. Portta's own project is refused by name and by
+  # directory, since no label can say so here.
+  [ "$verb" = "up" ] || die "no container on this host belongs to project '$project'"
+  [ -n "$request_working_dir" ] || die "no container on this host belongs to project '$project', and the request names no working directory"
+  own_name=$(sed -n 's/^PORTTA_PROJECT_NAME=//p' "$PORTTA_ROOT/.env" 2>/dev/null | head -n1)
+  own_name="${own_name%\"}"; own_name="${own_name#\"}"; own_name="${own_name%\'}"; own_name="${own_name#\'}"
+  own_name="${own_name:-portta}"
+  [ "$project" != "$own_name" ] || die "refusing to operate Portta's own project"
+  assert_request_path "$request_working_dir" "working directory"
+  assert_not_portta_path "$request_working_dir" "a working directory"
+  working_dir="$request_working_dir"
+  config_files="$request_config_files"
+fi
+
+[ -n "$working_dir" ] || die "project '$project' has no Compose working directory label"
+[ -d "${HOST_ROOT}${working_dir}" ] || die "working directory ${working_dir} does not exist on this host"
+
+# Compose sees the host filesystem at the host's own paths, so `include:` and
+# every relative path in a Compose file resolve exactly as they do on the host.
+# The first ancestor of a path that does not exist in this container becomes a
+# symlink into /host; the repository root is already mounted at its own path.
+link_host_path() {
+  local target="$1" partial="" rest segment
+  case "$target" in
+    "$PORTTA_ROOT"|"$PORTTA_ROOT"/*) return 0 ;;
+  esac
+  rest="${target#/}"
+  while [ -n "$rest" ]; do
+    segment="${rest%%/*}"
+    if [ "$segment" = "$rest" ]; then rest=""; else rest="${rest#*/}"; fi
+    partial="$partial/$segment"
+    if [ -L "$partial" ]; then
+      [ "$(realpath "$partial")" = "$(realpath "${HOST_ROOT}${partial}")" ] || die "${partial} in the runner does not point at the host's ${partial}; recreate the runner with portta up"
+      return 0
+    fi
+    if [ ! -e "$partial" ]; then
+      ln -s "${HOST_ROOT}${partial}" "$partial"
+      return 0
+    fi
+  done
+  [ "$(realpath "$target")" = "$(realpath "${HOST_ROOT}${target}")" ] || die "${target} exists inside the runner image and is not the host's ${target}"
+}
+
+link_host_path "$working_dir"
+
+# Compose files as the daemon recorded them, or as the panel remembered them.
+# Readability is checked through /host; the path handed to Compose is the
+# host's, like --project-directory, so bind mounts resolve on the host.
+files=()
+if [ -n "$config_files" ]; then
+  IFS=',' read -r -a listed <<< "$config_files"
+  for file in "${listed[@]}"; do
+    file="${file#"${file%%[![:space:]]*}"}"
+    file="${file%"${file##*[![:space:]]}"}"
+    [ -n "$file" ] || continue
+    [ -z "$id" ] && assert_request_path "$file" "compose file"
+    [ -n "$id" ] || assert_not_portta_path "$file" "a compose file"
+    [ -f "${HOST_ROOT}${file}" ] || die "compose file ${file} is not readable"
+    case "$file" in
+      "$working_dir"/*) ;;
+      *) link_host_path "${file%/*}" ;;
+    esac
+    files+=(-f "$file")
+  done
+fi
+if [ ${#files[@]} -eq 0 ]; then
+  for name in compose.yaml compose.yml docker-compose.yaml docker-compose.yml; do
+    if [ -f "${HOST_ROOT}${working_dir}/${name}" ]; then
+      files+=(-f "${working_dir}/${name}")
+      break
+    fi
+  done
+fi
+[ ${#files[@]} -gt 0 ] || die "no compose file in ${working_dir}"
+
+compose() {
+  docker compose --project-name "$project" --project-directory "$working_dir" "${files[@]}" "$@"
+}
+
+# The working directory is Docker's label. Removal is the same bound as
+# packages/core/src/paths.ts: absolute, no walk-up, not `/`, not a top-level
+# directory. `realpath` is the last check so a symlink cannot leave /host.
+remove_working_dir() {
+  local dir="$1"
+  [[ "$dir" == /* ]] || die "working directory is not absolute"
+  [[ "$dir" != *..* ]] || die "refusing working directory that walks up"
+  [[ "$dir" != "/" ]] || die "refusing to remove /"
+  case "${dir#/}" in
+    */*) ;;
+    *) die "refusing to remove a top-level directory" ;;
+  esac
+  local target="${HOST_ROOT}${dir}"
+  [ -d "$target" ] || die "working directory ${dir} does not exist on this host"
+  local real
+  real=$(realpath "$target")
+  case "$real" in
+    /host/*) ;;
+    *) die "resolved path is outside /host" ;;
+  esac
+  [ "$real" != "/host" ] && [ "$real" != "/" ] || die "refusing to remove the host root"
+  rm -rf -- "$real"
+}
+
+case "$verb" in
+  up) compose up -d --remove-orphans ;;
+  stop) compose stop ;;
+  restart) compose stop && compose up -d --remove-orphans ;;
+  build)
+    if [ "$nocache" = "1" ]; then
+      compose build --no-cache
+    else
+      compose build
+    fi
+    compose up -d --remove-orphans
+    ;;
+  down) compose down ;;
+  down-volumes)
+    compose down --volumes
+    if [ "$directory" = "1" ]; then
+      remove_working_dir "$working_dir"
+    fi
+    ;;
+esac