gowalk-cicd 1.0.177 → 1.0.179

package/README.md

@@ -242,7 +242,7 @@ contents, contact a provider or deploy. Preserve app-owned configuration and gen
 in the same validated candidate. A layout receipt proves selection, not production readiness.
 
 The backend workflow runs on a GitHub-hosted runner and, on a push touching
-`backend/**`, deploys to the gowalk host (`138.197.36.107`, publicly reachable):
+`backend/**`, deploys to the explicitly bound, publicly reachable `BACKEND_DEPLOY_HOST`:
 it rsyncs the backend dir to `/opt/gowalk-backends/<app>/`, runs
 `docker compose up -d --build`, auto-detects the published `127.0.0.1:<port>`,
 wires an nginx vhost + Let's Encrypt cert for the API domain, and health-checks.
@@ -304,9 +304,10 @@ Requirements on the consumer repo:
   **Backend Deploy runs only when it is set**: a repository with no bound backend
   origin holds no deploy key, so `deploy-backend.yml` is skipped and the feature-branch
   `backend-preview` deploy ends with a `backend_origin_unbound` notice.
+- Repo **variable** `BACKEND_DEPLOY_HOST`: the bound SSH destination (DNS name or IPv4 address),
+  required for a bound backend; no panel host or historical address is used as a fallback.
 - Repo **variables** (optional): `BACKEND_APP_NAME` (defaults to the repo name),
-  `BACKEND_HEALTH_PATH` (default `/health`), `BACKEND_DEPLOY_HOST` (default
-  `138.197.36.107`). The action refuses an `api-domain` that is not a lowercase DNS
+  `BACKEND_HEALTH_PATH` (default `/health`). The action refuses an `api-domain` that is not a lowercase DNS
   name, a `health-path` outside `/[A-Za-z0-9_./-]*` and a malformed `cert-email`.
 
 The action directory is canonical here (like the iOS/Android actions): edit it in
@@ -319,6 +320,36 @@ only; normal default-branch backend deploys remain in `deploy-backend.yml`.
 
 For optional app-owned Cloudflare ingress, follow [backend edge delivery](docs/BACKEND_EDGE.md).
 
+Backend starts use the resolved Compose model with effective CPU, memory and PID limits. Missing limits
+default to 0.5 CPU, 256 MiB memory, a 64 MiB memory reservation (or the smaller hard limit), and 128 PIDs.
+Explicit workload limits remain authoritative. Both Compose resource syntaxes agree in the generated
+model; JSON/local logs default to 10 MiB with three files. Health probes run at least 60 seconds apart
+in steady state, retaining fast startup with a 5-second start interval and at least 30 seconds of grace.
+The app owns a cheap probe and effective worker/pool limits; this helper never rewrites application code.
+Docker Engine 25+ and Compose 2.20.2+ support the startup interval.
+
+Before building and again immediately before starting, deployment checks live host memory and pressure.
+Other factory containers plus the proposed stack may reserve at most 70% of physical RAM; at least
+10% (and 512 MiB) stays available after additional reservations. One-minute load above twice the CPU
+count or full memory pressure of 1% refuses a start. Starts share a host lock (120-second acquisition
+limit); image builds stay parallel. A failed admission emits `backend_runtime_refused` with a fixed
+`gowalk-cicd/backend-runtime-refused.v1 code=…` and leaves existing containers running.
+
+An operator-managed `/opt/gowalk-backend-runtime/<app>.json`, outside the application mirror, may set
+`schema: "gowalk-cicd/backend-runtime.v1"`, `disabled: true`, `remove_services: ["db"]`, and per-service
+`services` overrides for `environment`, `command`, `entrypoint`, `mem_limit`, `mem_reservation`, `cpus`
+and `pids_limit`. A disabled binding refuses builds/starts. After a verified database migration, this
+file can remove the retired database service and override the app's connection environment on every
+redeploy. Only dependencies on explicitly removed services are removed; volumes are preserved. Keep
+the file private (0600), use distinct scoped database roles, and complete compatibility, restore and
+isolation checks before removing a database. This helper provisions no shared database and deletes no
+database volume. Resolved credentials stay in a private temporary file removed on success or failure;
+literal dollars survive the second Compose parse.
+
+For a shared host, use the [host-owned SSH deployment entry](docs/BACKEND_SSH_GATE.md). It scopes each panel's
+key, keeps new project claims autonomous, and redirects older action invocations to the released host helpers.
+Its global disabled gate permits readiness while refusing mutations during a migration.
+
 ## Android credentials
 
 Place these files under `creds/`:
@@ -524,6 +555,10 @@ remain readable by the panel. Masked fields are never reconstructed and credenti
 Protected vhost failures add `backend_vhost_failed` (`gowalk-cicd/backend-vhost-failed.v1`) with fixed
 brace-free `operation`, `stage`, `reason`, `child_exit` and `signals`; see `docs/BACKEND_EDGE.md`.
 It preserves the existing refusal and records only bounded observed facts, never private child output.
+Edge health failures add `backend_health_failed` (`gowalk-cicd/backend-health-failed.v1`) with fixed
+brace-free `probe`, `reason`, `curl_exit`, `http_status` and `attempt`; see `docs/BACKEND_EDGE.md`.
+Only the final failed probe's bounded observations appear, with no URLs, bodies, headers or credentials.
+Ingress refusal, strict TLS, exact-build acceptance, retry bounds and the original failed result remain.
 An interrupted locked Pod fetch can retry once within the existing 900-second install budget.
 `native_pods_retry` (`gowalk-cicd/native-pods-retry.v1`) reports `attempt:2` and `reason:partial_transfer`;
 successful preparation reports `pod_attempts`. Dependency locks, relay and TLS checks remain enforced.

package/backend-action/action.yml

@@ -1,7 +1,7 @@
 name: gowalk-cicd backend deploy
 description: >
   Build and deploy a Dockerized Python+Postgres backend to the gowalk deploy
-  host (138.197.36.107) — rsync the backend dir, `docker compose up -d --build`,
+  configured host — rsync the backend dir, enforce resources, build/start the stack,
   wire an nginx vhost + Let's Encrypt cert for the API domain, and health-check.
   The deploy host is publicly reachable, so this runs on a GitHub-hosted runner.
 
@@ -23,9 +23,9 @@ inputs:
     required: false
     default: none
   host:
-    description: SSH host of the deploy server.
-    required: false
-    default: "138.197.36.107"
+    description: Explicit SSH host from the backend binding; no infrastructure fallback.
+    required: true
+    default: ""
   ssh-user:
     description: SSH user on the deploy server.
     required: false
@@ -104,12 +104,16 @@ runs:
       env:
         OPERATION: ${{ inputs.operation }}
         API_DOMAIN: ${{ inputs.api-domain }}
+        DEPLOY_HOST: ${{ inputs.host }}
       run: |
         case "$OPERATION" in deploy|identity-diagnostics) ;; *) exit 1;; esac
         # Only a repository with a bound origin holds the deploy key; the panel sets the domain when it binds one.
         if [ "$OPERATION" = deploy ] && [ -z "$API_DOMAIN" ]; then
           echo "::notice title=backend_origin_unbound::No api-domain: the backend origin is not bound yet, nothing deployed"
           echo "skip=true" >> "$GITHUB_OUTPUT"
+        elif [[ ! "$DEPLOY_HOST" =~ ^[A-Za-z0-9][A-Za-z0-9.-]*$ ]]; then
+          echo "::error title=backend_host_required::Configure the backend binding's SSH host before deployment"
+          exit 1
         fi
 
     - name: Validate inputs
@@ -206,6 +210,10 @@ runs:
           "${{ github.action_path }}/edge_inputs.py" \
           "${{ github.action_path }}/runtime_env.py" \
           "${{ github.action_path }}/runtime_env_parse.py" \
+          "${{ github.action_path }}/runtime_model.py" \
+          "${{ github.action_path }}/runtime_host.py" \
+          "${{ github.action_path }}/native_profile.py" \
+          "${{ github.action_path }}/runtime_launch.py" \
           "${{ github.action_path }}/edge_vhost.py" \
           "${{ github.action_path }}/vhost_diagnostics.py" \
           "${{ github.action_path }}/edge_health.py" \

package/backend-action/edge_health.py

@@ -9,6 +9,25 @@ import time
 from edge_inputs import load, TOKEN_HEADER
 from edge_vhost import NGINX_DIR, paths, recorded_domain
 
+PROBES = frozenset({"configuration", "origin_missing_token", "origin_invalid_token", "origin_authorized",
+                    "legacy_identity", "legacy", "public"})
+REASONS = frozenset({"unclassified", "path_invalid", "request_failed", "http_refused", "json_invalid",
+                     "body_shape", "build_missing", "build_mismatch"})
+
+
+def report(probe, reason, *, curl_exit=None, http_status=None, attempt=None):
+    probe = probe if type(probe) is str and probe in PROBES else "unclassified"
+    reason = reason if type(reason) is str and reason in REASONS else "unclassified"
+    code = str(curl_exit) if type(curl_exit) is int and -255 <= curl_exit <= 255 else "none"
+    status = str(http_status) if type(http_status) is int and 100 <= http_status <= 599 else "none"
+    count = str(attempt) if type(attempt) is int and 1 <= attempt <= 15 else "none"
+    message = ("::error title=backend_health_failed::gowalk-cicd/backend-health-failed.v1 "
+               "probe={} reason={} curl_exit={} http_status={} attempt={}\n")
+    try:
+        sys.stderr.write(message.format(probe, reason, code, status, count))
+    except (OSError, ValueError):
+        pass  # Diagnostic delivery must not replace the original refusal.
+
 
 def request(url, *, headers=None, run=subprocess.run):
     # curl retains its strict TLS/time bounds. Private headers and bounded response
@@ -27,46 +46,89 @@ def request(url, *, headers=None, run=subprocess.run):
         return result.returncode, int(status) if status.isdigit() else 0, data
 
 
-def healthy(url, sha="", *, headers=None, fetch=request, sleep=time.sleep):
+def response_reason(code, status, body, sha):
+    if code != 0:
+        return "request_failed"
+    if not 200 <= status < 300:
+        return "http_refused"
+    if sha:
+        try:
+            value = json.loads(body)
+        except ValueError:
+            return "json_invalid"
+        if not isinstance(value, dict):
+            return "body_shape"
+        if "build_sha" not in value:
+            return "build_missing"
+        if value.get("build_sha") != sha:
+            return "build_mismatch"
+    return None
+
+
+def healthy(url, sha="", *, headers=None, fetch=request, sleep=time.sleep, probe="public"):
     for attempt in range(15):
+        code = status = None
+        reason = "unclassified"
         try:
             code, status, body = fetch(url, headers=headers)
-            valid = code == 0 and 200 <= status < 300
-            if valid and sha:
-                value = json.loads(body)
-                valid = isinstance(value, dict) and value.get("build_sha") == sha
-            if valid:
+            reason = response_reason(code, status, body, sha)
+            if reason is None:
                 return
         except (OSError, ValueError, subprocess.SubprocessError):
-            pass
+            reason = "request_failed" if code is None else "unclassified"
         if attempt != 14:
             sleep(2)
+    report(probe, reason, curl_exit=code, http_status=status, attempt=15)
     raise ValueError("backend_public_health_failed")
 
 
+def origin_refusal(url, headers, probe, fetch):
+    try:
+        code, status, _body = fetch(url, headers=headers)
+    except (OSError, ValueError, subprocess.SubprocessError):
+        report(probe, "request_failed", attempt=1)
+        raise
+    if code != 0 or status != 403:
+        report(probe, "request_failed" if code != 0 else "http_refused",
+               curl_exit=code, http_status=status, attempt=1)
+        raise ValueError("backend_origin_ingress_unverified")
+
+
 def verify(config, app, domain, health, *, nginx_dir=NGINX_DIR, fetch=request, sleep=time.sleep):
-    value = load(config)
+    try:
+        value = load(config)
+    except (OSError, ValueError, subprocess.SubprocessError):
+        report("configuration", "unclassified")
+        raise
     if not health.startswith("/") or any(character in health for character in "\r\n?#"):
+        report("configuration", "path_invalid")
         raise ValueError("backend_health_path_invalid")
     origin_url = f"https://{domain}{health}"
     if value["ingress_required"] == "true":
-        for headers in (None, {TOKEN_HEADER: "invalid-backend-ingress-token"}):
-            code, status, _body = fetch(origin_url, headers=headers)
-            if code != 0 or status != 403:
-                raise ValueError("backend_origin_ingress_unverified")
+        for probe, headers in (("origin_missing_token", None),
+                               ("origin_invalid_token", {TOKEN_HEADER: "invalid-backend-ingress-token"})):
+            origin_refusal(origin_url, headers, probe, fetch)
         healthy(origin_url, value["expected_build_sha"], headers={TOKEN_HEADER: value["ingress_token"]},
-                fetch=fetch, sleep=sleep)
-        legacy = recorded_domain(paths(config, app, nginx_dir)[0])
+                fetch=fetch, sleep=sleep, probe="origin_authorized")
+        try:
+            legacy = recorded_domain(paths(config, app, nginx_dir)[0])
+        except (OSError, ValueError, subprocess.SubprocessError):
+            report("legacy_identity", "unclassified")
+            raise
         if legacy:
-            healthy(f"https://{legacy}{health}", fetch=fetch, sleep=sleep)
+            healthy(f"https://{legacy}{health}", fetch=fetch, sleep=sleep, probe="legacy")
     public = value["public_health_url"] or origin_url
     healthy(public, value["expected_build_sha"], fetch=fetch, sleep=sleep)
     return {"ok": True, "public_health_verified": True, "build_sha": value["expected_build_sha"],
             "ingress_verified": value["ingress_required"] == "true"}
 
 
-if __name__ == "__main__":
+def main():
     try:
         print(json.dumps(verify(*sys.argv[1:5])))
     except (OSError, ValueError, subprocess.SubprocessError):
         sys.exit("backend_edge_health_failed")
+
+
+if __name__ == "__main__":
+    main()

package/backend-action/native_deploy.py

@@ -0,0 +1,143 @@
+"""Run only an operator-declared native deploy under shared host admission and resource limits."""
+import http.client
+import json
+import os
+import re
+import subprocess
+import sys
+import time
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from native_profile import APPS, load_profile, model, unit_properties
+from runtime_host import admit, host_facts, running_containers, start_lock
+from runtime_launch import START_LOCK
+from runtime_model import duration
+
+
+def run(arguments, timeout=60):
+    return subprocess.run(arguments, capture_output=True, text=True, timeout=timeout, check=True)
+
+
+def install(app, profile, phase='install'):
+    deadline = time.monotonic() + (600 if phase == 'install' else 60)
+    for index, arguments in enumerate(profile[phase]):
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            raise ValueError('native_install_timeout')
+        unit = 'gowalk-native-%s-%s-%s-%s' % (phase, app, os.getpid(), index)
+        try:
+            run(['systemd-run', '--quiet', '--wait', '--pipe', '--collect', '--unit=' + unit,
+                 '--property=MemoryMax=512M', '--property=CPUQuota=100%', '--property=TasksMax=128',
+                 '--property=RuntimeMaxSec=%g' % remaining, '--property=User=' + profile['install_user'],
+                 '--property=WorkingDirectory=' + profile['directory'], '--', *arguments], timeout=remaining + 5)
+        except subprocess.SubprocessError:
+            run(['systemctl', 'stop', unit])
+            raise
+
+
+def sync_source(app, profile):
+    source = APPS / app
+    if source.is_symlink() or not source.is_dir():
+        raise ValueError('native_source_invalid')
+    if str(source) == profile['directory']:
+        return
+    exclusions = sorted(set(['.env', '.runtime.env', '.git', 'env/', '.venv/', *profile['preserve']]))
+    run(['rsync', '-ac', '--delete', '--safe-links', *['--exclude=' + path for path in exclusions],
+         str(source) + '/', profile['directory'] + '/'], timeout=120)
+
+
+def source_revision(directory):
+    with (Path(directory) / '.backend-source-sha').open() as stream:
+        revision = stream.read(42).strip()
+    if not re.fullmatch('[0-9a-f]{40}', revision):
+        raise ValueError('native_source_identity_invalid')
+    return revision
+
+
+def held_state(profile):
+    units = sorted(set(profile['units']) - set(profile['restart_units']))
+    return unit_properties(units, ['ActiveState', 'UnitFileState', 'MainPID']) if units else {}
+
+
+def apply_limits(document):
+    for unit, limits in document['services'].items():
+        run(['systemctl', 'set-property', unit, 'MemoryMax=' + str(limits['mem_limit']),
+             'MemoryLow=' + str(limits['mem_reservation']), 'CPUQuota=%g%%' % (limits['cpus'] * 100),
+             'TasksMax=' + str(limits['pids_limit'])])
+    states = unit_properties(list(document['services']), ['MemoryMax', 'MemoryLow', 'CPUQuotaPerSecUSec', 'TasksMax'])
+    for unit, limits in document['services'].items():
+        state = states[unit]
+        expected = (limits['mem_limit'], limits['mem_reservation'], limits['pids_limit'])
+        actual = tuple(int(state[name]) for name in ('MemoryMax', 'MemoryLow', 'TasksMax'))
+        if actual != expected or abs(duration(state['CPUQuotaPerSecUSec']) - limits['cpus']) > 0.000001:
+            raise ValueError('native_limits_unapplied')
+
+
+def health(profile):
+    url = urlsplit(profile['health_url'])
+    deadline = time.monotonic() + 60
+    while time.monotonic() < deadline:
+        connection = http.client.HTTPConnection(url.hostname, url.port or 80, timeout=5)
+        try:
+            connection.request('GET', (url.path or '/') + ('?' + url.query if url.query else ''))
+            response = connection.getresponse()
+            payload = json.loads(response.read(65537)) if profile['health_json'] else {}
+            matches = isinstance(payload, dict) and all(payload.get(k) == v for k, v in profile['health_json'].items())
+            states = unit_properties(profile['restart_units'], ['ActiveState'])
+            active = all(item['ActiveState'] == 'active' for item in states.values())
+            if matches and 200 <= response.status < 300 and active:
+                return
+        except (OSError, ValueError, http.client.HTTPException):
+            pass
+        finally:
+            connection.close()
+        time.sleep(2)
+    raise ValueError('native_health_failed')
+
+
+def deploy(app):
+    profile = load_profile(app)
+    if profile['disabled']:
+        raise ValueError('native_disabled')
+    revision = source_revision(APPS / app)
+    document = model(profile)
+    admit(app, document, host_facts(), running_containers())
+    preserved_state = held_state(profile)
+    sync_source(app, profile)
+    install(app, profile)
+    with start_lock(START_LOCK):
+        # Re-read the host's freeze after preparation and immediately before start.
+        if load_profile(app) != profile:
+            raise ValueError('native_profile_changed')
+        if held_state(profile) != preserved_state:
+            raise ValueError('native_held_unit_changed')
+        admit(app, document, host_facts(), running_containers())
+        apply_limits(document)
+        try:
+            run(['systemctl', 'restart', *profile['restart_units']])
+            health(profile)
+            install(app, profile, 'verify')
+            if source_revision(profile['directory']) != revision:
+                raise ValueError('native_source_changed')
+            if held_state(profile) != preserved_state:
+                raise ValueError('native_held_unit_changed')
+        except (ValueError, OSError, subprocess.SubprocessError):
+            run(['systemctl', 'stop', *profile['restart_units']])
+            raise
+    print(json.dumps({'schema': 'gowalk-cicd/backend-native-result.v1', 'project': app,
+                      'units': profile['restart_units'], 'health': 'passed', 'resources': 'verified',
+                      'verification': 'passed', 'source_sha': revision}))
+
+
+def main():
+    try:
+        deploy(sys.argv[1])
+    except (ValueError, OSError, KeyError, IndexError, TypeError, subprocess.SubprocessError):
+        print('backend_native_refused', file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/backend-action/native_profile.py

@@ -0,0 +1,105 @@
+"""Root-owned native deployment declarations and reservations shared with Compose admission."""
+import json
+import re
+import subprocess
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from runtime_model import configure
+
+PROFILES = Path('/opt/gowalk-backend-native')
+APPS = Path('/opt/gowalk-backends')
+ROOT_UID = 0
+FIELDS = {'schema', 'disabled', 'directory', 'units', 'restart_units', 'install', 'install_user',
+          'health_url', 'health_json', 'resources', 'preserve', 'verify'}
+
+
+def load_profile(app):
+    if not re.fullmatch('[a-z0-9-]+', app):
+        raise ValueError('native_project_invalid')
+    path = PROFILES / (app + '.json')
+    info = path.stat()
+    if path.is_symlink() or info.st_uid != ROOT_UID or info.st_mode & 0o022:
+        raise ValueError('native_profile_permissions')
+    profile = json.loads(path.read_text())
+    if not isinstance(profile, dict) or set(profile) != FIELDS:
+        raise ValueError('native_profile_invalid')
+    if profile['schema'] != 'gowalk-cicd/backend-native.v1' or not isinstance(profile['disabled'], bool):
+        raise ValueError('native_profile_invalid')
+    directory = Path(profile['directory'])
+    if directory not in (APPS / app, Path('/opt') / app) or directory.is_symlink():
+        raise ValueError('native_directory_invalid')
+    units = profile['units']
+    if not isinstance(units, list) or not units or len(set(units)) != len(units):
+        raise ValueError('native_units_invalid')
+    if any(not re.fullmatch('[a-zA-Z0-9_-]+[.]service', unit) for unit in units):
+        raise ValueError('native_units_invalid')
+    restarting = profile['restart_units']
+    if not isinstance(restarting, list) or not restarting or set(restarting) - set(units):
+        raise ValueError('native_units_invalid')
+    validate_deployment(profile)
+    model(profile)
+    return profile
+
+
+def validate_deployment(profile):
+    for field in ['install', 'verify']:
+        commands = profile[field]
+        if not isinstance(commands, list) or len(commands) > 8:
+            raise ValueError('native_install_invalid')
+        for command in commands:
+            if not isinstance(command, list) or not command or not all(isinstance(word, str) for word in command):
+                raise ValueError('native_install_invalid')
+            if not command[0].startswith('/') or any('\x00' in word for word in command):
+                raise ValueError('native_install_invalid')
+    if not isinstance(profile['install_user'], str) or not re.fullmatch('[a-z_][a-z0-9_-]*', profile['install_user']):
+        raise ValueError('native_install_user_invalid')
+    url = urlsplit(profile['health_url'])
+    if url.scheme != 'http' or url.hostname not in ('127.0.0.1', 'localhost', '::1') or url.username or url.password:
+        raise ValueError('native_health_invalid')
+    if not isinstance(profile['health_json'], dict):
+        raise ValueError('native_health_invalid')
+    preserve = profile['preserve']
+    if not isinstance(preserve, list) or any(not re.fullmatch('[a-zA-Z0-9_.-]+/?', item) for item in preserve):
+        raise ValueError('native_preserve_invalid')
+    if any(item in ('.', '..', './', '../') for item in preserve):
+        raise ValueError('native_preserve_invalid')
+
+
+def model(profile):
+    resources = profile['resources']
+    if not isinstance(resources, dict) or set(resources) - set(profile['units']):
+        raise ValueError('native_resources_invalid')
+    services = {}
+    for unit in profile['units']:
+        values = resources.get(unit, {})
+        if not isinstance(values, dict) or set(values) - {'mem_limit', 'mem_reservation', 'cpus', 'pids_limit'}:
+            raise ValueError('native_resources_invalid')
+        services[unit] = values
+    return configure({'services': services})
+
+
+def unit_properties(units, properties):
+    result = subprocess.run(['systemctl', 'show', '--property=' + ','.join(['Id', *properties]), *units],
+                            capture_output=True, text=True, timeout=30, check=True)
+    records = [dict(line.split('=', 1) for line in block.splitlines() if '=' in line)
+               for block in result.stdout.strip().split('\n\n')]
+    mapped = {record['Id']: record for record in records if record.get('Id')}
+    if set(mapped) != set(units):
+        raise ValueError('native_unit_missing')
+    return mapped
+
+
+def running_native():
+    containers = []
+    for path in sorted(PROFILES.glob('*.json')):
+        profile = load_profile(path.stem)
+        states = unit_properties(profile['units'], ['ActiveState', 'MemoryLow'])
+        for unit, limits in model(profile)['services'].items():
+            if states[unit]['ActiveState'] not in ('active', 'activating', 'reloading'):
+                continue
+            reservation = max(int(states[unit]['MemoryLow']), limits['mem_reservation'])
+            containers.append({'Config': {'Labels': {'com.docker.compose.project': path.stem,
+                               'com.docker.compose.project.working_dir': str(APPS / path.stem)}},
+                               'HostConfig': {'MemoryReservation': reservation}})
+    return containers

package/backend-action/remote_deploy.sh

@@ -9,7 +9,8 @@ DOMAIN="${2:-}"    # api.<app-domain>, or empty to skip nginx/cert
 HEALTH="${3:-/health}"
 CERT_EMAIL="${4:-admin@gowalk.com}"
 DIR="/opt/gowalk-backends/$APP"
-source "$(dirname "${BASH_SOURCE[0]}")/deploy_evidence.sh"
+HELPERS="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$HELPERS/deploy_evidence.sh"
 BACKEND_DEPLOY_PHASE=remote_setup
 cd "$DIR"
 export COMPOSE_FILE="${5:-docker-compose.yml}"
@@ -18,8 +19,8 @@ case "$COMPOSE_FILE" in
   *) echo "::error::unsupported backend compose filename"; exit 1;;
 esac
 test -f "$COMPOSE_FILE" || { echo "::error::selected backend compose file is missing"; exit 1; }
-source "$DIR/select_certbot_account.sh"
-source "$DIR/ensure_certificate.sh"
+source "$HELPERS/select_certbot_account.sh"
+source "$HELPERS/ensure_certificate.sh"
 
 log() { echo "[deploy $APP] $*"; }
 log "host $(python3 --version)"
@@ -38,9 +39,9 @@ EDGE_CONFIG="/opt/gowalk-backend-ingress/$APP/.backend-edge.json"
 EDGE_VHOST="/etc/nginx/conf.d/backend-$APP-edge.conf"
 EDGE_MODE=legacy
 if [ -f "$EDGE_CONFIG" ] || [ -e "$EDGE_VHOST" ]; then
-  python3 "$DIR/edge_vhost.py" validate "$EDGE_CONFIG" "$APP" "$DOMAIN"
-  EDGE_MODE="$(python3 "$DIR/edge_inputs.py" mode "$EDGE_CONFIG")"
-  python3 "$DIR/edge_inputs.py" runtime "$EDGE_CONFIG"
+  python3 "$HELPERS/edge_vhost.py" validate "$EDGE_CONFIG" "$APP" "$DOMAIN"
+  EDGE_MODE="$(python3 "$HELPERS/edge_inputs.py" mode "$EDGE_CONFIG")"
+  python3 "$HELPERS/edge_inputs.py" runtime "$EDGE_CONFIG"
 fi
 
 # ── secrets: generate a per-app .env once, then preserve it (rsync excludes it)
@@ -83,8 +84,7 @@ fi
 # ── bring the stack up
 BACKEND_DEPLOY_PHASE=compose_up
 log "docker compose up -d --build"
-docker compose "${COMPOSE_ENV[@]}" --project-name "$APP" \
-  up -d --build --remove-orphans
+python3 "$HELPERS/runtime_launch.py" "$APP" "${COMPOSE_ENV[@]}"
 
 # ── discover the host port the service published on 127.0.0.1.
 # The text `ps` PORTS column reliably shows `127.0.0.1:<port>-><target>/tcp`.
@@ -136,9 +136,9 @@ CERT_VHOST="$VHOST"
 write_vhost() {
   local state
   if [ "${EDGE_MODE:-legacy}" = edge ]; then
-    state="$(nginx_locked python3 "$DIR/edge_vhost.py" configure "$EDGE_CONFIG" "$APP" "$DOMAIN" "$PORT" "$1")"
+    state="$(nginx_locked python3 "$HELPERS/edge_vhost.py" configure "$EDGE_CONFIG" "$APP" "$DOMAIN" "$PORT" "$1")"
   else
-    state="$(nginx_locked python3 "$DIR/configure_vhost.py" "$VHOST" "$DOMAIN" "$PORT" "$1")"
+    state="$(nginx_locked python3 "$HELPERS/configure_vhost.py" "$VHOST" "$DOMAIN" "$PORT" "$1")"
   fi
   [ "$state" != changed ] || log "nginx vhost for $DOMAIN ($1) → 127.0.0.1:$PORT"
 }
@@ -162,7 +162,7 @@ fi
 # and the application together; a green deploy must mean the public API works.
 BACKEND_DEPLOY_PHASE=public_health
 if [ "$EDGE_MODE" != legacy ]; then
-  python3 "$DIR/edge_health.py" "$EDGE_CONFIG" "$APP" "$DOMAIN" "$HEALTH"
+  python3 "$HELPERS/edge_health.py" "$EDGE_CONFIG" "$APP" "$DOMAIN" "$HEALTH"
   log "done"
   exit 0
 fi

package/backend-action/runtime_host.py

@@ -0,0 +1,95 @@
+"""Admit backend starts against live host headroom and existing container reservations."""
+import json
+import os
+import subprocess
+import time
+import fcntl
+from contextlib import contextmanager
+from pathlib import Path
+
+from runtime_model import MIB
+from native_profile import running_native
+
+HOST_POLICY = Path('/etc/gowalk-backend-ssh.json')
+ROOT_UID = 0
+
+
+def host_enabled():
+    if not HOST_POLICY.exists():
+        return
+    info = HOST_POLICY.stat()
+    policy = json.loads(HOST_POLICY.read_text())
+    if info.st_uid != ROOT_UID or info.st_mode & 0o022:
+        raise ValueError('host_policy_permissions')
+    if not isinstance(policy, dict) or policy.get('schema') != 'gowalk-cicd/backend-ssh.v1':
+        raise ValueError('host_backend_disabled')
+    if policy.get('disabled') is not False:
+        raise ValueError('host_backend_disabled')
+
+
+@contextmanager
+def start_lock(path):
+    with path.open("a") as lock:
+        deadline = time.monotonic() + 120
+        while True:
+            try:
+                fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                break
+            except BlockingIOError:
+                if time.monotonic() >= deadline:
+                    raise ValueError("host_start_busy")
+                time.sleep(0.1)
+        yield
+
+
+def host_facts(root=Path("/proc")):
+    memory = {}
+    for line in (root / "meminfo").read_text().splitlines():
+        key, value = line.split(":", 1)
+        memory[key] = int(value.strip().split()[0]) * 1024
+    pressure = 0.0
+    path = root / "pressure/memory"
+    if path.exists():
+        for line in path.read_text().splitlines():
+            if line.startswith("full "):
+                pressure = float(dict(part.split("=") for part in line.split()[1:])["avg10"])
+    return {"total": memory["MemTotal"], "available": memory["MemAvailable"],
+            "load": float((root / "loadavg").read_text().split()[0]),
+            "cpus": os.cpu_count() or 1, "memory_pressure": pressure}
+
+
+def running_containers():
+    result = subprocess.run(["docker", "ps", "-q"], capture_output=True, text=True, timeout=30, check=True)
+    ids = result.stdout.split()
+    if not ids:
+        return running_native()
+    template = ('{"Config":{"Labels":{"com.docker.compose.project":'
+                '{{json (index .Config.Labels "com.docker.compose.project")}},'
+                '"com.docker.compose.project.working_dir":'
+                '{{json (index .Config.Labels "com.docker.compose.project.working_dir")}}}},'
+                '"HostConfig":{"MemoryReservation":{{.HostConfig.MemoryReservation}}}}')
+    result = subprocess.run(["docker", "inspect", "--format", template, *ids],
+                            capture_output=True, text=True, timeout=30, check=True)
+    return [json.loads(line) for line in result.stdout.splitlines()] + running_native()
+
+
+def admit(app, model, facts, containers):
+    host_enabled()
+    required = sum(service["mem_reservation"] for service in model["services"].values())
+    reserved, current = 0, 0
+    for container in containers:
+        labels = container.get("Config", {}).get("Labels") or {}
+        if not labels.get("com.docker.compose.project.working_dir", "").startswith("/opt/gowalk-backends/"):
+            continue
+        amount = container["HostConfig"].get("MemoryReservation") or 64 * MIB
+        if labels.get("com.docker.compose.project") == app:
+            current += amount
+        else:
+            reserved += amount
+    if reserved + required > facts["total"] * 0.7:
+        raise ValueError("host_reservations_exhausted")
+    if facts["available"] - max(0, required - current) < max(512 * MIB, facts["total"] * 0.1):
+        raise ValueError("host_memory_exhausted")
+    if facts["load"] > facts["cpus"] * 2 or facts["memory_pressure"] >= 1:
+        raise ValueError("host_pressure_high")
+    return required

package/backend-action/runtime_launch.py

@@ -0,0 +1,71 @@
+"""Resolve private Compose inputs, enforce limits and serialize only admitted container starts."""
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from runtime_host import admit, host_facts, running_containers, start_lock
+from runtime_model import configure
+
+PROFILE_ROOT = Path("/opt/gowalk-backend-runtime")
+START_LOCK = Path("/run/lock/gowalk-backend-start.lock")
+
+
+def profile_snapshot(app):
+    if not re.fullmatch(r"[a-z0-9-]+", app):
+        raise ValueError("runtime_app_invalid")
+    profile = PROFILE_ROOT / (app + '.json')
+    return profile.read_bytes() if profile.exists() else None
+
+
+def compose_model(app, arguments):
+    raw_profile = profile_snapshot(app)
+    result = subprocess.run(["docker", "compose", *arguments, "--project-name", app, "config", "--format", "json"],
+                            capture_output=True, text=True, timeout=60, check=True)
+    return configure(json.loads(result.stdout), json.loads(raw_profile) if raw_profile is not None else None)
+
+
+def launch(app, arguments):
+    original_profile = profile_snapshot(app)
+    model = compose_model(app, arguments)
+    admit(app, model, host_facts(), running_containers())
+    descriptor, filename = tempfile.mkstemp(prefix=".runtime-compose-", suffix=".json", dir=".")
+    try:
+        with os.fdopen(descriptor, "w") as stream:
+            json.dump(model, stream)
+        command = ["docker", "compose", "--file", filename, "--project-name", app]
+        if any(service.get("build") for service in model["services"].values()):
+            subprocess.run(command + ["build"], check=True)
+        with start_lock(START_LOCK):
+            if profile_snapshot(app) != original_profile:
+                raise ValueError('runtime_profile_changed')
+            admit(app, model, host_facts(), running_containers())
+            subprocess.run(command + ["up", "-d", "--no-build", "--remove-orphans"], check=True)
+    finally:
+        Path(filename).unlink()
+
+
+def main():
+    try:
+        launch(sys.argv[1], sys.argv[2:])
+    except ValueError as error:
+        code = str(error) if str(error).replace("_", "").isalnum() else "runtime_invalid"
+        print("::error title=backend_runtime_refused::gowalk-cicd/backend-runtime-refused.v1 code=" + code,
+              file=sys.stderr)
+        return 1
+    except subprocess.CalledProcessError as error:
+        print("::error title=backend_runtime_refused::gowalk-cicd/backend-runtime-refused.v1 code=runtime_failed",
+              file=sys.stderr)
+        return error.returncode if 0 < error.returncode < 256 else 1
+    except (OSError, subprocess.SubprocessError, KeyError, TypeError):
+        print("::error title=backend_runtime_refused::gowalk-cicd/backend-runtime-refused.v1 code=runtime_failed",
+              file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/backend-action/runtime_model.py

@@ -0,0 +1,111 @@
+"""Bound a resolved Compose model while preserving app code and host-owned DB bindings."""
+import copy
+import math
+import re
+
+MIB = 1024 * 1024
+SCHEMA = "gowalk-cicd/backend-runtime.v1"
+SERVICE_FIELDS = {"environment", "command", "entrypoint", "mem_limit", "mem_reservation", "cpus", "pids_limit"}
+
+
+def quantity(value, units):
+    match = re.fullmatch(r"([0-9]+(?:\.[0-9]+)?)\s*([a-z]*)", str(value).strip().lower())
+    if not match or match[2] not in units:
+        raise ValueError("resource_value_invalid")
+    result = float(match[1]) * units[match[2]]
+    if not math.isfinite(result) or result <= 0:
+        raise ValueError("resource_value_invalid")
+    return int(result)
+
+
+def memory(value):
+    return quantity(value, {"": 1, "b": 1, "k": 1024, "kb": 1024, "m": MIB, "mb": MIB,
+                            "g": 1024 * MIB, "gb": 1024 * MIB})
+
+
+def duration(value):
+    parts = re.findall(r"([0-9]+(?:\.[0-9]+)?)(ns|us|ms|s|m|h)", str(value))
+    if not parts or "".join(number + unit for number, unit in parts) != str(value):
+        raise ValueError("health_duration_invalid")
+    units = {"ns": 1e-9, "us": 1e-6, "ms": 1e-3, "s": 1, "m": 60, "h": 3600}
+    return sum(float(number) * units[unit] for number, unit in parts)
+
+
+def bind_profile(model, profile):
+    if not profile:
+        return
+    if not isinstance(profile, dict) or profile.get("schema") != SCHEMA:
+        raise ValueError("runtime_profile_invalid")
+    if set(profile) - {"schema", "disabled", "remove_services", "services"}:
+        raise ValueError("runtime_profile_invalid")
+    if profile.get("disabled"):
+        raise ValueError("runtime_disabled")
+    removed = profile.get("remove_services", [])
+    if not isinstance(removed, list) or any(not isinstance(name, str) for name in removed):
+        raise ValueError("runtime_profile_invalid")
+    for name in removed:
+        model["services"].pop(name, None)
+    for service in model["services"].values():
+        dependencies = service.get("depends_on", {})
+        service["depends_on"] = {key: value for key, value in dependencies.items() if key not in removed}
+    for name, values in profile.get("services", {}).items():
+        if name not in model["services"] or not isinstance(values, dict) or set(values) - SERVICE_FIELDS:
+            raise ValueError("runtime_service_invalid")
+        service = model["services"][name]
+        for key, value in values.items():
+            if key == "environment":
+                if not isinstance(value, dict):
+                    raise ValueError("runtime_environment_invalid")
+                service.setdefault(key, {}).update(escape_interpolation(value))
+            else:
+                service[key] = escape_interpolation(value)
+
+
+def bound_service(service):
+    resources = service.setdefault("deploy", {}).setdefault("resources", {})
+    limits, reservations = resources.setdefault("limits", {}), resources.setdefault("reservations", {})
+    cap = memory(service.get("mem_limit") or limits.get("memory") or 256 * MIB)
+    reserve = memory(service.get("mem_reservation") or reservations.get("memory") or min(64 * MIB, cap))
+    cpu = float(service.get("cpus") or limits.get("cpus") or 0.5)
+    pids = int(service.get("pids_limit") or limits.get("pids") or 128)
+    if reserve > cap or not math.isfinite(cpu) or cpu <= 0 or pids <= 0:
+        raise ValueError("resource_limits_invalid")
+    service.update(mem_limit=cap, mem_reservation=reserve, cpus=cpu, pids_limit=pids)
+    limits.update(memory=str(cap), cpus=str(cpu), pids=pids)
+    reservations["memory"] = str(reserve)
+    health = service.setdefault("healthcheck", {})
+    if not health.get("disable") and health.get("test") != ["NONE"]:
+        if duration(health.get("interval", "30s")) < 60:
+            health["interval"] = "60s"
+        if duration(health.get("start_period", "0s")) < 30:
+            health["start_period"] = "30s"
+        if duration(health.get("start_interval", "5s")) > 5 or "start_interval" not in health:
+            health["start_interval"] = "5s"
+    logging = service.setdefault("logging", {"driver": "json-file"})
+    if logging.get("driver") in ("json-file", "local"):
+        options = logging.setdefault("options", {})
+        options.setdefault("max-size", "10m")
+        options.setdefault("max-file", "3")
+    return reserve
+
+
+def configure(document, profile=None):
+    model = copy.deepcopy(document)
+    if not isinstance(model.get("services"), dict) or not model["services"]:
+        raise ValueError("compose_services_required")
+    bind_profile(model, profile)
+    if not model["services"]:
+        raise ValueError("compose_services_required")
+    for service in model["services"].values():
+        bound_service(service)
+    return model
+
+
+def escape_interpolation(value):
+    if isinstance(value, str):
+        return value.replace("$", "$$")
+    if isinstance(value, dict):
+        return {key: escape_interpolation(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [escape_interpolation(item) for item in value]
+    return value

package/backend-action/ssh_gate.py

@@ -0,0 +1,171 @@
+"""Forced-command entry for panel deploy keys; never execute helper code from app mirrors."""
+import json
+import os
+import re
+import shlex
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from native_profile import PROFILES as NATIVE_PROFILES
+
+HELPERS = Path(__file__).resolve().parent
+POLICY = Path('/etc/gowalk-backend-ssh.json')
+OWNERS = Path('/var/lib/gowalk-backend-ownership')
+APPS = Path('/opt/gowalk-backends')
+INGRESS = Path('/opt/gowalk-backend-ingress')
+ROOT_UID = 0
+READY = ('command -v docker >/dev/null && docker info >/dev/null 2>&1 '
+         '&& docker compose version >/dev/null 2>&1')
+
+
+def load_policy(owner):
+    info = POLICY.stat()
+    if info.st_uid != ROOT_UID or info.st_mode & 0o022:
+        raise ValueError('ssh_policy_permissions')
+    policy = json.loads(POLICY.read_text())
+    if not isinstance(policy, dict) or policy.get('schema') != 'gowalk-cicd/backend-ssh.v1':
+        raise ValueError('ssh_policy_invalid')
+    if not isinstance(policy.get('owners'), list) or not isinstance(policy.get('allow_new_projects'), bool):
+        raise ValueError('ssh_policy_invalid')
+    if not isinstance(policy.get('disabled'), bool) or owner not in policy['owners']:
+        raise ValueError('ssh_owner_refused')
+    return policy
+
+
+def scoped_path(value, base=None):
+    base = base or APPS
+    path = Path(value)
+    if not path.is_absolute() or '..' in path.parts:
+        raise ValueError('ssh_path_refused')
+    try:
+        relative = path.relative_to(base)
+    except ValueError:
+        raise ValueError('ssh_path_refused') from None
+    if not relative.parts or not re.fullmatch('[a-z0-9-]+', relative.parts[0]):
+        raise ValueError('ssh_project_refused')
+    project = relative.parts[0]
+    root = base / project
+    resolved_root = base.resolve() / project
+    resolved = path.resolve()
+    if root.is_symlink() or (resolved != resolved_root and resolved_root not in resolved.parents):
+        raise ValueError('ssh_path_refused')
+    return project, path
+
+
+def authorize(owner, project, policy, may_claim):
+    path = OWNERS / (project + '.json')
+    if not path.exists():
+        if not may_claim or not policy.get('allow_new_projects') or (APPS / project).exists():
+            raise ValueError('ssh_project_unregistered')
+        OWNERS.mkdir(mode=0o700, parents=True, exist_ok=True)
+        descriptor, staging = tempfile.mkstemp(prefix='.claim-', dir=str(OWNERS))
+        try:
+            with os.fdopen(descriptor, 'w') as stream:
+                json.dump({'project': project, 'owner': owner}, stream)
+            try:
+                os.link(staging, str(path))
+            except FileExistsError:
+                pass
+        finally:
+            Path(staging).unlink()
+    info = path.stat()
+    if info.st_uid != ROOT_UID or info.st_mode & 0o022:
+        raise ValueError('ssh_owner_permissions')
+    binding = json.loads(path.read_text())
+    if binding != {'project': project, 'owner': owner}:
+        raise ValueError('ssh_project_owned_elsewhere')
+
+
+def helper_command(words):
+    if len(words) == 3 and words[:2] == ['gowalk-backend', 'native-deploy']:
+        if not re.fullmatch('[a-z0-9-]+', words[2]):
+            raise ValueError('ssh_project_refused')
+        return words[2], False, [sys.executable, str(HELPERS / 'native_deploy.py'), words[2]]
+    if len(words) in (4, 5, 6, 7) and words[0] == 'bash':
+        project, script = scoped_path(words[1])
+        if script != APPS / project / 'remote_deploy.sh' or words[2] != project:
+            raise ValueError('ssh_helper_refused')
+        patterns = [r'[a-z0-9.-]*', r'/[A-Za-z0-9_./-]*', r'[A-Za-z0-9._%+@-]+']
+        if any(not re.fullmatch(pattern, value) for pattern, value in zip(patterns, words[3:6])):
+            raise ValueError('ssh_arguments_refused')
+        compose_names = ('compose.yaml', 'compose.yml', 'docker-compose.yaml', 'docker-compose.yml')
+        if len(words) == 7 and words[6] not in compose_names:
+            raise ValueError('ssh_arguments_refused')
+        return project, False, ['/bin/bash', str(HELPERS / 'remote_deploy.sh'), *words[2:]]
+    if len(words) == 4 and words[0] == 'python3' and words[2] == 'receive':
+        project, script = scoped_path(words[1])
+        if script != APPS / project / 'runtime_env.py' or words[3] != str(APPS / project / '.runtime.env'):
+            raise ValueError('ssh_helper_refused')
+        return project, False, [sys.executable, str(HELPERS / 'runtime_env.py'), 'receive', words[3]]
+    if len(words) == 9 and words[:3] == ['python3', '-', '--remote']:
+        if words[3::2] != ['--app', '--service', '--since'] or not re.fullmatch('[a-z0-9-]+', words[4]):
+            raise ValueError('ssh_helper_refused')
+        return words[4], False, [sys.executable, str(HELPERS / 'identity_diagnostics.py'), *words[2:]]
+    raise ValueError('ssh_operation_refused')
+
+
+def transfer_command(words):
+    if len(words) == 3 and words[:2] == ['mkdir', '-p']:
+        project, path = scoped_path(words[2])
+        return project, path == APPS / project, ['/usr/bin/mkdir', '-p', str(path)]
+    if len(words) >= 5 and words[:2] == ['rsync', '--server'] and words[-2] == '.':
+        project, path = scoped_path(words[-1])
+        for option in words[2:-2]:
+            if option not in ('--delete', '--delete-after', '--delete-during', '--delete-delay'):
+                if not re.fullmatch(r'-[vlogDtprz]+(?:e[.a-zA-Z]+)?', option):
+                    raise ValueError('ssh_rsync_refused')
+        return project, False, ['/usr/bin/rsync', *words[1:-1], str(path)]
+    if len(words) == 11 and words[:5] == ['umask', '077', ';', 'mkdir', '-p']:
+        project, destination = scoped_path(words[5], INGRESS)
+        expected = [';', 'python3', str(APPS / project / 'edge_inputs.py'), 'receive',
+                    str(INGRESS / project / '.backend-edge.json')]
+        if words[6:] != expected or destination != INGRESS / project:
+            raise ValueError('ssh_helper_refused')
+        return project, False, [sys.executable, str(HELPERS / 'edge_inputs.py'), 'receive', expected[-1]]
+    return helper_command(words)
+
+
+def plan(command):
+    lexer = shlex.shlex(command, posix=True, punctuation_chars=';&|<>')
+    lexer.whitespace_split = True
+    lexer.commenters = ''
+    words = list(lexer)
+    if not words or len(command) > 8192:
+        raise ValueError('ssh_operation_refused')
+    return transfer_command(words)
+
+
+def readiness():
+    for command in [['docker', 'info'], ['docker', 'compose', 'version']]:
+        subprocess.run(command, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=15, check=True)
+    return 0
+
+
+def main():
+    try:
+        os.umask(0o077)
+        owner = sys.argv[1]
+        policy = load_policy(owner)
+        command = os.environ.get('SSH_ORIGINAL_COMMAND', '')
+        if ' '.join(command.split()) in (READY, 'gowalk-backend readiness'):
+            return readiness()
+        if policy.get('disabled', True):
+            raise ValueError('ssh_backend_disabled')
+        project, may_claim, arguments = plan(command)
+        authorize(owner, project, policy, may_claim)
+        if arguments[:2] == ['/bin/bash', str(HELPERS / 'remote_deploy.sh')]:
+            if (NATIVE_PROFILES / (project + '.json')).exists():
+                raise ValueError('ssh_native_project_required')
+        if arguments[1:3] == [str(HELPERS / 'edge_inputs.py'), 'receive']:
+            Path(arguments[3]).parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+        os.execve(arguments[0], arguments, {'PATH': '/usr/sbin:/usr/bin:/sbin:/bin', 'LANG': 'C.UTF-8'})
+    except (OSError, ValueError, KeyError, IndexError, subprocess.SubprocessError):
+        print('backend_ssh_refused', file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/docs/BACKEND_EDGE.md

@@ -57,3 +57,19 @@ They are observed patterns, not a unique cause or retry permission. No raw error
 token or child output is included. A failed restoration adds a separate rollback refusal while keeping
 the original failure visible; absence of that extra line alone does not prove successful restoration.
 The generic `backend_edge_vhost_refused`, changed/unchanged stdout, ingress, TLS and deploy gates remain.
+
+Health refusals add the fixed stderr annotation `backend_health_failed` with schema
+`gowalk-cicd/backend-health-failed.v1`. Its brace-free fields are `probe`, `reason`, `curl_exit`,
+`http_status` and `attempt`. Probes are configuration, origin_missing_token, origin_invalid_token,
+origin_authorized, legacy_identity, legacy and public; unknown metadata becomes unclassified.
+Reasons are unclassified, path_invalid, request_failed, http_refused, json_invalid, body_shape,
+build_missing and build_mismatch. No URL, response body, build identity, header, credential, path,
+exception text or subprocess output enters the annotation. Curl exit is an observed integer from
+-255 to 255, HTTP status from 100 to 599 and attempt from 1 to 15; other values become `none`.
+An exhausted health check emits only its final attempt's facts, clearing any previous observations.
+These facts identify the failed probe, not a unique cause or permission to retry or bypass it.
+Missing-token and invalid-token checks remain single requests requiring completed 403 responses.
+Healthy-origin, retained-legacy and public checks retain 15 attempts with two seconds between them,
+strict TLS, existing curl time/body bounds and exact build checks. A successful check emits no
+failure annotation and returns the existing result. Original exceptions and the generic CLI refusal
+`backend_edge_health_failed` with exit 1 remain unchanged, including when diagnostic delivery fails.

package/docs/BACKEND_NATIVE.md

@@ -0,0 +1,60 @@
+# Profiled native backend compatibility
+
+Existing native services can retain their interpreters, private environment, database and systemd units.
+The same forced SSH entry accepts exactly `gowalk-backend native-deploy <project>` and dispatches the
+release-owned `native_deploy.py`; callers cannot supply commands, units or resource overrides. The host
+must already have the compatible interpreter, dependencies, root-owned units and ownership registration.
+A native profile prevents that project from falling back to the Compose deploy entry.
+
+Upload source to `/opt/gowalk-backends/<project>` through the scoped receiver. Include `.backend-source-sha`
+containing the exact 40-character lowercase commit SHA. Create a root-owned, non-writable-by-others
+`/opt/gowalk-backend-native/<project>.json` outside that mirror:
+
+```json
+{
+  "schema": "gowalk-cicd/backend-native.v1",
+  "disabled": true,
+  "directory": "/opt/example",
+  "units": ["example.service", "example-worker.service"],
+  "restart_units": ["example.service"],
+  "install_user": "root",
+  "install": [
+    ["/opt/example/env/bin/python", "-m", "pip", "install", "-r", "requirements.txt"],
+    ["/opt/example/env/bin/python", "scripts/apply_migrations.py"]
+  ],
+  "verify": [],
+  "health_url": "http://127.0.0.1:6061/health",
+  "health_json": {"status": "ok"},
+  "preserve": ["static/", "logs/"],
+  "resources": {}
+}
+```
+
+The profile's directory must be the project's standard mirror or exact legacy `/opt/<project>` path.
+The helper synchronizes legacy checkouts with content checksums, preserving `.env`, `.runtime.env`, `.git`,
+`env/`, `.venv/` and the explicit production-state paths. Declare every persistent app-owned path before
+activation; external state is never synchronized. Source deletion applies only outside those exclusions.
+Private runtime rotations can use the existing runtime-env envelope into the mirror's `.runtime.env`.
+Provision an optional systemd `EnvironmentFile=-/opt/gowalk-backends/<project>/.runtime.env` for apps whose
+settings honor process-environment precedence. Do not replace their original private `.env` file.
+
+`units` declares every managed unit; `restart_units` declares only the units this deployment starts.
+All managed units receive persistent limits, but an inactive worker remains inactive and an active worker
+is not restarted unless listed. ActiveState, UnitFileState and MainPID of held units must remain unchanged
+from before preparation through final verification. Resource fields per unit are `mem_limit`, `mem_reservation`, `cpus` and
+`pids_limit`, with the same defaults as Compose. The helper reads back MemoryMax, MemoryLow, CPUQuota and
+TasksMax and refuses if they differ. Every active native unit contributes its reservation to admission
+for both native and Compose deployments.
+
+Install and post-health verification commands are fixed argument arrays from the trusted profile,
+including an app's established idempotent migration entry. They run in the legacy checkout under the
+specified existing user, inside transient units bounded to 512 MiB, one CPU and 128 PIDs. Installation
+shares a ten-minute budget and verification a one-minute budget; a failed transient unit is stopped.
+Captured output stays private. Verification programs must return nonzero when their contract fails.
+
+Both global and per-project disabled gates must open before deployment. Admission runs before preparation
+and again under the shared start lock, rereading the global freeze both times. A changed profile refuses start. Local health has a 60-second bound,
+requires 2xx plus the declared JSON fields, and requires only the restarted units to be active. A failed
+restart, health or verification stops exactly those units and fails CI; subsequent corrected deployments
+use the same bounded path. No worker is enabled, no notification is sent and no source rollback is claimed.
+A successful receipt reports the exact transferred source SHA, verified resources, health and verification.

package/docs/BACKEND_SSH_GATE.md

@@ -0,0 +1,57 @@
+# Host-owned backend deployment entry
+
+Install `backend-action/` from an integrity-verified published package in a root-owned release directory,
+outside `/opt/gowalk-backends/`. Deployment transport must not be able to replace that directory.
+The forced-command entry runs every supported helper from its own release directory, including when an
+older action uploaded an older `remote_deploy.sh` into an app mirror. No consumer repository update is
+needed for the transport protocol below.
+
+Each panel gets its own dedicated SSH key. Its `authorized_keys` entry uses `restrict` and a fixed owner:
+
+```text
+restrict,command="/usr/bin/python3 /opt/gowalk-cicd-runtime/1.0.179/backend-action/ssh_gate.py robot" ssh-ed25519 <key>
+```
+
+Keep operator and release credentials separate. Never install an unrestricted backend key as a fallback.
+Create root-owned mode-0600 `/etc/gowalk-backend-ssh.json`:
+
+```json
+{
+  "schema": "gowalk-cicd/backend-ssh.v1",
+  "disabled": true,
+  "owners": ["robot", "vpnrobot"],
+  "allow_new_projects": true
+}
+```
+
+`disabled: true` refuses every mutation while permitting the read-only readiness probe. Keep it set
+through migration and validation. Existing per-app runtime `disabled` profiles remain an independent
+start fence when the global transport gate opens.
+
+Register each existing app as `/var/lib/gowalk-backend-ownership/<project>.json`, root-owned and mode0600,
+with exactly `{"project":"<project>","owner":"robot"}` (or its actual panel owner). Do not infer ownership
+from an SSH caller. Existing app directories without registration refuse first claims. After activation,
+the action's first `mkdir -p /opt/gowalk-backends/<new-project>` atomically claims an unused safe project
+name for that panel. A competing panel cannot replace the binding. This permits ordinary new backend
+provisioning without a manual allowlist update; existing ownership and private directories remain fenced.
+
+The entry permits only:
+
+- the panel's exact existing Docker/Compose readiness probe, or `gowalk-backend readiness`;
+- scoped app-directory creation and the action's rsync **receiver** protocol inside that app;
+- the standard private runtime environment and edge-input receive envelopes;
+- the standard backend deploy invocation, redirected to the host-owned released helper;
+- the standard bounded identity-diagnostic invocation, also redirected to the released helper;
+- `gowalk-backend native-deploy <project>` for an existing [root-profiled native service](BACKEND_NATIVE.md).
+
+It refuses arbitrary shell commands, interactive shells, rsync sender/download operations, traversal,
+directory symlinks escaping an app and any attempt to execute an app-mirror helper. App code still owns
+its container build and product implementation; the released launcher owns runtime limits and admission.
+Custom native deployment workflows use their fixed host-owned profile before enabling their key;
+they cannot use this key to run arbitrary systemd commands.
+
+Verify with a fresh connection under each real panel key: readiness succeeds during a global freeze;
+mutations refuse; after the gate opens, the key can transfer only its own app's source and another panel's
+project refuses. A disabled runtime profile must still refuse a legacy deploy invocation. Verify a new
+task-owned project can be claimed and replayed, then remove only that verification project and binding.
+Failures emit only `backend_ssh_refused`, never the original command or private stdin.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gowalk-cicd",
-  "version": "1.0.177",
+  "version": "1.0.179",
   "description": "Zero-config GitHub Actions delivery for iOS TestFlight and Android Google Play.",
   "type": "module",
   "bin": {
@@ -39,6 +39,8 @@
     "docs/GRADLE_CACHE.md",
     "docs/CANDIDATE_ARTIFACTS.md",
     "docs/BACKEND_EDGE.md",
+    "docs/BACKEND_SSH_GATE.md",
+    "docs/BACKEND_NATIVE.md",
     "docs/CONFIGURATION.md",
     "docs/CI_PERFORMANCE.md"
   ],

package/templates/deploy-backend.yml

@@ -60,7 +60,7 @@ jobs:
           diagnostic-since: ${{ inputs.diagnostic-since }}
           ssh-key: ${{ secrets.BACKEND_DEPLOY_SSH_KEY }}
           known-hosts: ${{ vars.BACKEND_DEPLOY_KNOWN_HOSTS }}
-          host: ${{ vars.BACKEND_DEPLOY_HOST || '138.197.36.107' }}
+          host: ${{ vars.BACKEND_DEPLOY_HOST }}
           app-name: ${{ vars.BACKEND_APP_NAME || github.event.repository.name }}
           api-domain: ${{ vars.BACKEND_API_DOMAIN }}
           backend-dir: ${{ steps.dir.outputs.path }}

package/templates/deploy.yml

@@ -839,7 +839,7 @@ jobs:
         with:
           ssh-key: ${{ secrets.BACKEND_DEPLOY_SSH_KEY }}
           known-hosts: ${{ vars.BACKEND_DEPLOY_KNOWN_HOSTS }}
-          host: ${{ vars.BACKEND_DEPLOY_HOST || '138.197.36.107' }}
+          host: ${{ vars.BACKEND_DEPLOY_HOST }}
           app-name: ${{ vars.BACKEND_APP_NAME || github.event.repository.name }}
           api-domain: ${{ vars.BACKEND_API_DOMAIN }}
           backend-dir: ${{ steps.dir.outputs.path }}