gowalk-cicd 1.0.190 → 1.0.191

package/README.md

@@ -1363,3 +1363,12 @@ Its `result.json` contains the validated envelope on success and classified fail
 headers, environment values, provider exceptions or identities. Normal GitHub artifact integrity checks
 apply. The console copy is supplementary: secret masking can replace JSON punctuation in logs.
 Each invocation uses a fresh local directory so a failed reader cannot publish a prior result.
+
+### Applied backend runtime diagnostics
+
+The backend action's `operation: runtime-diagnostics` reads the exact app project and expected deployed SHA,
+returning actual service count, effective limits, two bounded resource samples and private database-binding
+provenance. Call it from the app's read-only diagnostic workflow with `diagnostic-service` and
+`expected-build-sha`, using its existing host/key/pin inputs. It requires the released host forced command as well
+as the updated action. See [the scoped runtime contract and host installer](docs/BACKEND_SSH_GATE.md#applied-runtime-readback).
+Identity failure logs and source Compose files do not establish this applied state.

package/backend-action/action.yml

@@ -7,11 +7,11 @@ description: >
 
 inputs:
   operation:
-    description: deploy (default) or identity-diagnostics.
+    description: deploy (default), identity-diagnostics or runtime-diagnostics.
     required: false
     default: deploy
   diagnostic-service:
-    description: Exact Compose service to inspect; used only for identity-diagnostics.
+    description: Exact Compose service for identity logs or runtime build/database binding proof.
     required: false
     default: api
   diagnostic-since:
@@ -106,7 +106,7 @@ runs:
         API_DOMAIN: ${{ inputs.api-domain }}
         DEPLOY_HOST: ${{ inputs.host }}
       run: |
-        case "$OPERATION" in deploy|identity-diagnostics) ;; *) exit 1;; esac
+        case "$OPERATION" in deploy|identity-diagnostics|runtime-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"
@@ -279,6 +279,33 @@ runs:
         path: ${{ steps.identity_diagnostics.outputs.result }}
         if-no-files-found: error
 
+    - name: Read scoped backend runtime
+      id: runtime_diagnostics
+      if: inputs.operation == 'runtime-diagnostics'
+      shell: bash
+      env:
+        DIAGNOSTIC_APP: ${{ inputs.app-name }}
+        DIAGNOSTIC_SERVICE: ${{ inputs.diagnostic-service }}
+        DIAGNOSTIC_HOST: ${{ inputs.host }}
+        DIAGNOSTIC_USER: ${{ inputs.ssh-user }}
+        DIAGNOSTIC_BUILD: ${{ inputs.expected-build-sha }}
+      run: |
+        RESULT_DIR="$(mktemp -d "$RUNNER_TEMP/backend-runtime-diagnostics.XXXXXX")"
+        echo "result=$RESULT_DIR/result.json" >> "$GITHUB_OUTPUT"
+        python3 "${{ github.action_path }}/runtime_diagnostics.py" \
+          --app "$DIAGNOSTIC_APP" --service "$DIAGNOSTIC_SERVICE" --expected-build-sha "$DIAGNOSTIC_BUILD" \
+          --host "$DIAGNOSTIC_HOST" --user "$DIAGNOSTIC_USER" --output "$RESULT_DIR/result.json"
+
+    - name: Retain scoped backend runtime result
+      if: always() && inputs.operation == 'runtime-diagnostics'
+      uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
+      env:
+        NODE_OPTIONS: --require "${{ github.action_path }}/scripts/artifact_env.cjs"
+      with:
+        name: backend-runtime-diagnostics-${{ github.job }}-${{ github.run_attempt }}
+        path: ${{ steps.runtime_diagnostics.outputs.result }}
+        if-no-files-found: error
+
     - name: Cleanup key
       if: always()
       shell: bash

package/backend-action/install_runtime.py

@@ -0,0 +1,159 @@
+"""Install an integrity-verified published runtime and retarget only named panel forced commands."""
+import argparse
+import base64
+import hashlib
+import io
+import json
+import os
+import re
+import shutil
+import stat
+import tarfile
+import tempfile
+from pathlib import Path
+
+ROOT = Path('/opt/gowalk-cicd-runtime')
+AUTHORIZED_KEYS = Path('/root/.ssh/authorized_keys')
+ROOT_UID = 0
+REQUIRED = (
+    'ssh_gate.py', 'native_profile.py', 'native_deploy.py', 'runtime_host.py', 'runtime_launch.py',
+    'runtime_model.py', 'runtime_readback.py', 'runtime_projection.py', 'identity_diagnostics.py',
+    'runtime_env.py', 'runtime_env_parse.py', 'edge_inputs.py', 'edge_vhost.py', 'edge_health.py',
+    'configure_vhost.py', 'vhost_diagnostics.py', 'remote_deploy.sh', 'deploy_evidence.sh',
+    'ensure_certificate.sh', 'select_certbot_account.sh',
+)
+
+
+def archive_files(archive, integrity, version):
+    if not re.fullmatch(r'\d+\.\d+\.\d+', version) or not re.fullmatch(r'sha512-[A-Za-z0-9+/]+=*', integrity):
+        raise ValueError('release_identity_invalid')
+    if archive.stat().st_size > 20 * 1024 * 1024:
+        raise ValueError('release_archive_too_large')
+    raw = archive.read_bytes()
+    actual = 'sha512-' + base64.b64encode(hashlib.sha512(raw).digest()).decode()
+    if actual != integrity:
+        raise ValueError('release_integrity_mismatch')
+    with tarfile.open(fileobj=io.BytesIO(raw), mode='r:gz') as source:
+        metadata = json.load(source.extractfile('package/package.json'))
+        if metadata.get('name') != 'gowalk-cicd' or metadata.get('version') != version:
+            raise ValueError('release_identity_mismatch')
+        result = {}
+        for member in source.getmembers():
+            if not member.name.startswith('package/backend-action/'):
+                continue
+            path = Path(member.name).relative_to('package')
+            if member.isdir():
+                continue
+            if not member.isfile() or '..' in path.parts or member.size > 1024 * 1024 or str(path) in result:
+                raise ValueError('release_archive_invalid')
+            result[str(path)] = source.extractfile(member).read()
+            if len(result) > 256 or sum(len(content) for content in result.values()) > 8 * 1024 * 1024:
+                raise ValueError('release_archive_too_large')
+    if not all('backend-action/' + name in result for name in REQUIRED):
+        raise ValueError('release_reader_missing')
+    for name, content in result.items():
+        if name.endswith('.py'):
+            compile(content, name, 'exec')
+    return result
+
+
+def trusted(path, *, directory=False):
+    info = path.lstat()
+    expected = stat.S_ISDIR if directory else stat.S_ISREG
+    if not expected(info.st_mode) or info.st_uid != ROOT_UID or info.st_mode & 0o022:
+        raise ValueError('release_path_untrusted')
+    return info
+
+
+def install_files(version, files):
+    ROOT.mkdir(mode=0o755, parents=True, exist_ok=True)
+    trusted(ROOT, directory=True)
+    target = ROOT / version
+    if target.exists():
+        trusted(target, directory=True)
+        for name, content in files.items():
+            trusted(target / name)
+            if (target / name).read_bytes() != content:
+                raise ValueError('release_existing_mismatch')
+        return target
+    staging = Path(tempfile.mkdtemp(prefix='.runtime-', dir=str(ROOT)))
+    try:
+        for name, content in files.items():
+            path = staging / name
+            path.parent.mkdir(mode=0o755, parents=True, exist_ok=True)
+            path.write_bytes(content)
+            path.chmod(0o644)
+        staging.chmod(0o755)
+        staging.rename(target)
+    finally:
+        if staging.exists():
+            shutil.rmtree(staging)
+    return target
+
+
+def update_commands(content, target, owners):
+    lines = content.splitlines(keepends=True)
+    for owner in owners:
+        if not re.fullmatch(r'[a-z0-9-]{1,40}', owner):
+            raise ValueError('release_owner_invalid')
+        pattern = re.compile(r'command="/usr/bin/python3 /opt/gowalk-cicd-runtime/\d+\.\d+\.\d+'
+                             r'/backend-action/ssh_gate\.py ' + re.escape(owner) + r'"')
+        matches = [index for index, line in enumerate(lines) if pattern.search(line)]
+        if len(matches) != 1 or 'restrict' not in lines[matches[0]].split(' ')[0].split(','):
+            raise ValueError('release_owner_command_ambiguous')
+        replacement = 'command="/usr/bin/python3 ' + str(target / 'backend-action/ssh_gate.py') + ' ' + owner + '"'
+        lines[matches[0]] = pattern.sub(lambda _match: replacement, lines[matches[0]])
+    return ''.join(lines)
+
+
+def atomic_keys(content):
+    descriptor, filename = tempfile.mkstemp(prefix='.runtime-keys-', dir=str(AUTHORIZED_KEYS.parent))
+    try:
+        with os.fdopen(descriptor, 'w') as stream:
+            stream.write(content)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(filename, str(AUTHORIZED_KEYS))
+    finally:
+        if Path(filename).exists():
+            Path(filename).unlink()
+
+
+def install(archive, integrity, version, owners):
+    if not owners or len(set(owners)) != len(owners):
+        raise ValueError('release_owners_invalid')
+    files = archive_files(archive, integrity, version)
+    trusted(AUTHORIZED_KEYS)
+    original = AUTHORIZED_KEYS.read_text()
+    target = ROOT / version
+    updated = update_commands(original, target, owners)
+    install_files(version, files)
+    if AUTHORIZED_KEYS.read_text() != original:
+        raise ValueError('release_keys_changed')
+    if updated != original:
+        atomic_keys(updated)
+    if AUTHORIZED_KEYS.read_text() != updated:
+        raise ValueError('release_keys_unconfirmed')
+    return {'schema': 'gowalk-cicd/backend-runtime-install.v1', 'version': version,
+            'owners': owners, 'changed': updated != original, 'verified': True}
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--archive', type=Path, required=True)
+    parser.add_argument('--integrity', required=True)
+    parser.add_argument('--version', required=True)
+    parser.add_argument('--owner', action='append', required=True)
+    args = parser.parse_args()
+    try:
+        result = install(args.archive, args.integrity, args.version, args.owner)
+    except Exception as error:
+        code = str(error) if isinstance(error, ValueError) and re.fullmatch('[a-z_]+', str(error)) else 'unclassified'
+        print('backend_runtime_install_refused code=' + code)
+        return 1
+    print(json.dumps(result, separators=(',', ':')))
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

package/backend-action/runtime_diagnostics.py

@@ -0,0 +1,63 @@
+"""Call the released host runtime reader through the existing restricted CI identity."""
+import argparse
+import json
+import re
+import shlex
+from pathlib import Path
+
+from identity_diagnostics import ReaderFailure, bounded, retain_result
+from runtime_projection import RuntimeFailure, envelope, scope, validate
+
+
+def local(args):
+    scope(args.app, args.service, args.expected_build_sha)
+    if (not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9.-]{0,252}', args.host or '')
+            or not re.fullmatch(r'[a-z_][a-z0-9_-]{0,31}', args.user)):
+        raise RuntimeFailure('invalid_scope')
+    command = shlex.join(['gowalk-backend', 'runtime-diagnostics', args.app, args.service, args.expected_build_sha])
+    try:
+        status, raw = bounded(['ssh', '-T', '-i', str(Path.home() / '.ssh/backend_deploy'),
+            '-o', 'IdentitiesOnly=yes', '-o', 'BatchMode=yes', '-o', 'StrictHostKeyChecking=yes',
+            '-o', 'ConnectTimeout=10', '-o', 'ServerAliveInterval=5', '-o', 'ServerAliveCountMax=2',
+            '-o', 'ClearAllForwardings=yes', args.user + '@' + args.host, command], seconds=75, with_status=True)
+    except ReaderFailure as error:
+        raise RuntimeFailure(error.code) from None
+    except OSError:
+        raise RuntimeFailure('transport_failure') from None
+    if status not in (0, 1):
+        raise RuntimeFailure('transport_failure')
+    if status == 1 and not raw.strip():
+        raise RuntimeFailure('runtime_reader_unavailable')
+    try:
+        result = validate(json.loads(raw), args.app, args.service, args.expected_build_sha)
+    except (ValueError, TypeError, KeyError):
+        raise RuntimeFailure('remote_invalid') from None
+    if result['ok'] != (status == 0):
+        raise RuntimeFailure('remote_invalid')
+    return result
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--app', required=True)
+    parser.add_argument('--service', default='api')
+    parser.add_argument('--expected-build-sha', required=True)
+    parser.add_argument('--host', required=True)
+    parser.add_argument('--user', default='root')
+    parser.add_argument('--output', required=True)
+    args = parser.parse_args()
+    try:
+        result = local(args)
+    except Exception as error:
+        result = envelope(args.app, args.service, args.expected_build_sha,
+                          error.code if isinstance(error, RuntimeFailure) else 'unclassified', reader_version=None)
+    try:
+        retain_result(args.output, result)
+    except ReaderFailure:
+        result = envelope(args.app, args.service, args.expected_build_sha, 'artifact_write_failed', reader_version=None)
+    print(json.dumps(result, separators=(',', ':')))
+    return 0 if result['ok'] else 1
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

package/backend-action/runtime_projection.py

@@ -0,0 +1,118 @@
+"""Closed, credential-free envelope for one app's deployed runtime observations."""
+import math
+import re
+
+SCHEMA = 'gowalk-cicd/backend-runtime-diagnostics.v1'
+READER_VERSION = '1.0.191'
+PROJECT = r'[a-z0-9][a-z0-9-]{0,79}'
+SERVICE = r'[a-z0-9][a-z0-9_-]{0,63}'
+SHA = r'[a-f0-9]{40}'
+CID = r'[a-f0-9]{64}'
+FAILURES = frozenset({
+    'invalid_scope', 'runtime_absent', 'runtime_ambiguous', 'runtime_scope_mismatch', 'runtime_changed',
+    'runtime_invalid', 'build_mismatch', 'profile_invalid', 'profile_changed', 'binding_mismatch',
+    'command_timeout', 'output_limit', 'command_failed', 'transport_failure', 'remote_invalid',
+    'artifact_write_failed', 'runtime_reader_unavailable', 'unclassified',
+})
+
+
+class RuntimeFailure(Exception):
+    def __init__(self, code):
+        self.code = code if isinstance(code, str) and code in FAILURES else 'unclassified'
+        super().__init__(self.code)
+
+
+def scope(app, service, expected):
+    if not all(isinstance(value, str) and re.fullmatch(pattern, value)
+               for value, pattern in ((app, PROJECT), (service, SERVICE), (expected, SHA))):
+        raise RuntimeFailure('invalid_scope')
+
+
+def number(value, *, integer=False, positive=False):
+    if (isinstance(value, bool) or not isinstance(value, int if integer else (int, float))
+            or not math.isfinite(value) or value < 0 or (positive and value == 0)):
+        raise RuntimeFailure('remote_invalid')
+
+
+def service_record(row):
+    fields = {'service', 'container_id', 'image_id', 'running', 'limits', 'samples'}
+    if not isinstance(row, dict) or set(row) != fields:
+        raise RuntimeFailure('remote_invalid')
+    for name, pattern in (('service', SERVICE), ('container_id', CID), ('image_id', 'sha256:' + CID)):
+        if not isinstance(row[name], str) or not re.fullmatch(pattern, row[name]):
+            raise RuntimeFailure('remote_invalid')
+    if type(row['running']) is not bool or set(row['limits']) != {
+            'memory_bytes', 'reservation_bytes', 'cpu_limit', 'pids_limit'}:
+        raise RuntimeFailure('remote_invalid')
+    for name, value in row['limits'].items():
+        number(value, integer=name != 'cpu_limit', positive=name != 'reservation_bytes')
+    if row['limits']['reservation_bytes'] > row['limits']['memory_bytes']:
+        raise RuntimeFailure('remote_invalid')
+    samples = row['samples']
+    if samples == [] and not row['running']:
+        return
+    if not isinstance(samples, list) or len(samples) != 2:
+        raise RuntimeFailure('remote_invalid')
+    for usage in samples:
+        if not isinstance(usage, dict) or set(usage) != {'memory_bytes', 'cpu_percent', 'pids', 'observed_at'}:
+            raise RuntimeFailure('remote_invalid')
+        if not isinstance(usage['observed_at'], str) or not re.fullmatch(r'\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ',
+                                                                      usage['observed_at']):
+            raise RuntimeFailure('remote_invalid')
+        for name in ('memory_bytes', 'cpu_percent', 'pids'):
+            number(usage[name], integer=name != 'cpu_percent')
+
+
+def database_record(row):
+    if not isinstance(row, dict) or set(row) != {
+            'mode', 'profile_present', 'binding_matches_profile', 'removed_services', 'database_services'}:
+        raise RuntimeFailure('remote_invalid')
+    if row['mode'] not in {'host_profile', 'app_service', 'external_unverified', 'unconfigured'}:
+        raise RuntimeFailure('remote_invalid')
+    if (type(row['profile_present']) is not bool
+            or row['binding_matches_profile'] is not None and type(row['binding_matches_profile']) is not bool):
+        raise RuntimeFailure('remote_invalid')
+    for key in ('removed_services', 'database_services'):
+        if (not isinstance(row[key], list) or len(row[key]) > 32
+                or any(not isinstance(value, str) or not re.fullmatch(SERVICE, value) for value in row[key])):
+            raise RuntimeFailure('remote_invalid')
+    if row['mode'] == 'host_profile' and (not row['profile_present'] or row['binding_matches_profile'] is not True):
+        raise RuntimeFailure('remote_invalid')
+
+
+def validate(result, app, service, expected):
+    scope(app, service, expected)
+    base = {'schema', 'reader_version', 'ok', 'failure', 'project', 'build_service', 'expected_build_sha'}
+    if (not isinstance(result, dict) or result.get('schema') != SCHEMA or type(result.get('ok')) is not bool
+            or result.get('project') != app or result.get('build_service') != service
+            or result.get('expected_build_sha') != expected
+            or result.get('reader_version') != READER_VERSION):
+        raise RuntimeFailure('remote_invalid')
+    if not result['ok']:
+        if set(result) != base or result['failure'] not in FAILURES:
+            raise RuntimeFailure('remote_invalid')
+        return result
+    if (set(result) != base | {'observed_build_sha', 'services', 'container_count', 'database', 'observed_at'}
+            or result['failure'] != '' or result['observed_build_sha'] != expected
+            or not isinstance(result['observed_at'], str)
+            or not re.fullmatch(r'\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ', result['observed_at'])):
+        raise RuntimeFailure('remote_invalid')
+    rows = result['services']
+    if not isinstance(rows, list) or not 1 <= len(rows) <= 32:
+        raise RuntimeFailure('remote_invalid')
+    number(result['container_count'], integer=True)
+    if result['container_count'] != len(rows):
+        raise RuntimeFailure('remote_invalid')
+    for row in rows:
+        service_record(row)
+    if len({row['container_id'] for row in rows}) != len(rows) or len({row['service'] for row in rows}) != len(rows):
+        raise RuntimeFailure('remote_invalid')
+    if not any(row['service'] == service and row['running'] for row in rows):
+        raise RuntimeFailure('remote_invalid')
+    database_record(result['database'])
+    return result
+
+
+def envelope(app, service, expected, failure='', *, reader_version=READER_VERSION):
+    return {'schema': SCHEMA, 'reader_version': reader_version, 'ok': not failure, 'failure': failure, 'project': app,
+            'build_service': service, 'expected_build_sha': expected}

package/backend-action/runtime_readback.py

@@ -0,0 +1,163 @@
+"""Observe one authorized Compose project; private bindings never leave the host."""
+import datetime
+import json
+import re
+import stat
+import sys
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from identity_diagnostics import ReaderFailure, bounded
+from runtime_projection import CID, SERVICE, RuntimeFailure, envelope, scope, validate
+
+APPS = Path('/opt/gowalk-backends')
+PROFILES = Path('/opt/gowalk-backend-runtime')
+ROOT_UID = 0
+INSPECT = ('{"id":{{json .Id}},"image":{{json .Image}},"running":{{json .State.Running}},'
+           '"project":{{json (index .Config.Labels "com.docker.compose.project")}},'
+           '"service":{{json (index .Config.Labels "com.docker.compose.service")}},'
+           '"directory":{{json (index .Config.Labels "com.docker.compose.project.working_dir")}},'
+           '"memory":{{.HostConfig.Memory}},"reservation":{{.HostConfig.MemoryReservation}},'
+           '"nano_cpus":{{.HostConfig.NanoCpus}},"quota":{{.HostConfig.CpuQuota}},'
+           '"period":{{.HostConfig.CpuPeriod}},"pids":{{json .HostConfig.PidsLimit}},'
+           '"binding":[""{{range .Config.Env}}{{$key := index (split . "=") 0}}'
+           '{{if or (eq $key "BUILD_SHA") (eq $key "DATABASE_URL")}},{{json .}}{{end}}{{end}}]}')
+
+
+def run(arguments):
+    try:
+        return bounded(arguments, seconds=10)
+    except ReaderFailure as error:
+        raise RuntimeFailure(error.code) from None
+
+
+def containers(app):
+    raw = run(['docker', 'ps', '--all', '--no-trunc', '--filter',
+               'label=com.docker.compose.project=' + app, '--format', '{{.ID}}']).decode().splitlines()
+    if not raw:
+        raise RuntimeFailure('runtime_absent')
+    if len(raw) > 32 or len(set(raw)) != len(raw) or any(not re.fullmatch(CID, value) for value in raw):
+        raise RuntimeFailure('runtime_ambiguous')
+    return sorted(raw)
+
+
+def inspect(app, identifiers):
+    rows = [json.loads(line) for line in run(['docker', 'inspect', '--format', INSPECT, *identifiers]).splitlines()]
+    if sorted(row['id'] for row in rows) != identifiers:
+        raise RuntimeFailure('runtime_changed')
+    services = set()
+    for row in rows:
+        if (row['project'] != app or row['directory'] != str(APPS / app)
+                or not isinstance(row['service'], str) or not re.fullmatch(SERVICE, row['service'])):
+            raise RuntimeFailure('runtime_scope_mismatch')
+        if row['service'] in services:
+            raise RuntimeFailure('runtime_ambiguous')
+        services.add(row['service'])
+        values = [item.split('=', 1) for item in row['binding'] if item]
+        if len({item[0] for item in values}) != len(values):
+            raise RuntimeFailure('runtime_invalid')
+        row['binding'] = dict(values)
+    return sorted(rows, key=lambda row: row['service'])
+
+
+def profile(app):
+    path = PROFILES / (app + '.json')
+    try:
+        info = path.lstat()
+    except FileNotFoundError:
+        return None
+    if not stat.S_ISREG(info.st_mode) or info.st_uid != ROOT_UID or info.st_mode & 0o022 or info.st_size > 65536:
+        raise RuntimeFailure('profile_invalid')
+    raw = path.read_bytes()
+    value = json.loads(raw)
+    if (not isinstance(value, dict) or value.get('schema') != 'gowalk-cicd/backend-runtime.v1'
+            or set(value) - {'schema', 'disabled', 'remove_services', 'services'}):
+        raise RuntimeFailure('profile_invalid')
+    return raw
+
+
+def database(raw_profile, selected, rows):
+    document = json.loads(raw_profile) if raw_profile is not None else {}
+    removed = document.get('remove_services', [])
+    service = document.get('services', {}).get(selected['service'], {})
+    declared = service.get('environment', {}).get('DATABASE_URL')
+    actual = selected['binding'].get('DATABASE_URL')
+    if not isinstance(removed, list) or any(not isinstance(x, str) or not re.fullmatch(SERVICE, x) for x in removed):
+        raise RuntimeFailure('profile_invalid')
+    if set(removed) & {row['service'] for row in rows}:
+        raise RuntimeFailure('binding_mismatch')
+    matched = None if declared is None else isinstance(declared, str) and bool(declared) and actual == declared
+    if matched is False:
+        raise RuntimeFailure('binding_mismatch')
+    hostname = urlsplit(actual).hostname if actual else None
+    owned = [row['service'] for row in rows if row['service'] == hostname]
+    mode = 'host_profile' if matched else 'app_service' if owned else (
+        'external_unverified' if actual else 'unconfigured')
+    return {'mode': mode, 'profile_present': raw_profile is not None, 'binding_matches_profile': matched,
+            'removed_services': sorted(removed), 'database_services': owned}
+
+
+def usage(rows):
+    identifiers = [row['id'] for row in rows if row['running']]
+    if not identifiers:
+        raise RuntimeFailure('runtime_absent')
+    samples = [json.loads(line) for line in run(['docker', 'stats', '--no-stream', '--no-trunc',
+               '--format', '{{json .}}', *identifiers]).splitlines()]
+    if sorted(row['ID'] for row in samples) != sorted(identifiers):
+        raise RuntimeFailure('runtime_changed')
+    units = {'B': 1, 'kB': 1000, 'KiB': 1024, 'MB': 1000 ** 2, 'MiB': 1024 ** 2,
+             'GB': 1000 ** 3, 'GiB': 1024 ** 3}
+    result = {}
+    observed = datetime.datetime.now(datetime.timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')
+    for row in samples:
+        memory = re.fullmatch(r'([0-9.]+)([A-Za-z]+)', row['MemUsage'].split(' / ')[0].strip())
+        if not memory or memory[2] not in units or not re.fullmatch(r'[0-9.]+%', row['CPUPerc']):
+            raise RuntimeFailure('runtime_invalid')
+        result[row['ID']] = {'memory_bytes': int(float(memory[1]) * units[memory[2]]),
+                            'cpu_percent': float(row['CPUPerc'][:-1]), 'pids': int(row['PIDs']),
+                            'observed_at': observed}
+    return result
+
+
+def public_row(row, samples):
+    cpus = row['nano_cpus'] / 1e9 if row['nano_cpus'] else (
+        row['quota'] / row['period'] if row['quota'] > 0 and row['period'] > 0 else 0)
+    return {'service': row['service'], 'container_id': row['id'], 'image_id': row['image'],
+            'running': row['running'], 'limits': {'memory_bytes': row['memory'],
+            'reservation_bytes': row['reservation'], 'cpu_limit': cpus, 'pids_limit': row['pids']},
+            'samples': [sample[row['id']] for sample in samples] if row['running'] else []}
+
+
+def collect(app, service, expected):
+    scope(app, service, expected)
+    original_profile = profile(app)
+    identifiers = containers(app)
+    rows = inspect(app, identifiers)
+    selected = next((row for row in rows if row['service'] == service), None)
+    if not selected or not selected['running'] or selected['binding'].get('BUILD_SHA') != expected:
+        raise RuntimeFailure('build_mismatch')
+    binding = database(original_profile, selected, rows)
+    samples = [usage(rows), usage(rows)]
+    if containers(app) != identifiers or inspect(app, identifiers) != rows:
+        raise RuntimeFailure('runtime_changed')
+    if profile(app) != original_profile:
+        raise RuntimeFailure('profile_changed')
+    result = dict(envelope(app, service, expected), observed_build_sha=expected,
+                  services=[public_row(row, samples) for row in rows], container_count=len(rows),
+                  database=binding,
+                  observed_at=datetime.datetime.now(datetime.timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ'))
+    return validate(result, app, service, expected)
+
+
+def main():
+    app, service, expected = (sys.argv[1:] + ['', '', ''])[:3]
+    try:
+        result = collect(app, service, expected)
+    except Exception as error:
+        result = envelope(app, service, expected, error.code if isinstance(error, RuntimeFailure) else 'unclassified')
+    print(json.dumps(result, separators=(',', ':')))
+    return 0 if result['ok'] else 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/backend-action/ssh_gate.py

@@ -80,6 +80,13 @@ def authorize(owner, project, policy, may_claim):
 
 
 def helper_command(words):
+    if len(words) == 5 and words[:2] == ['gowalk-backend', 'runtime-diagnostics']:
+        from runtime_projection import RuntimeFailure, scope
+        try:
+            scope(*words[2:])
+        except RuntimeFailure:
+            raise ValueError('ssh_arguments_refused') from None
+        return words[2], False, [sys.executable, str(HELPERS / 'runtime_readback.py'), *words[2:]]
     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')

package/docs/BACKEND_SSH_GATE.md

@@ -56,3 +56,55 @@ mutations refuse; after the gate opens, the key can transfer only its own app'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.
+
+## Applied runtime readback
+
+The released backend action accepts `operation: runtime-diagnostics`, `diagnostic-service` (default `api`) and
+`expected-build-sha`. Its existing pinned CI SSH identity issues only
+`gowalk-backend runtime-diagnostics <project> <service> <40-character-SHA>`. The forced command checks the same
+panel/project ownership and global freeze, then executes its own released `runtime_readback.py`. It never runs
+consumer code or an uploaded script. An older/refusing gate has no reader receipt and the client returns
+`runtime_reader_unavailable`; locally synthesized failures carry `reader_version: null`, never host-adoption proof.
+A collector refusal carries its actual `reader_version` and fixed failure code.
+
+The `backend-runtime-diagnostics-<job>-<attempt>` artifact contains only `result.json`, schema
+`gowalk-cicd/backend-runtime-diagnostics.v1`. Success binds the expected/observed build to the running API's
+`BUILD_SHA`, enumerates at most 32 exact-project containers (including stopped ones), and rechecks their exact
+project/service/working-directory labels. It returns container and image IDs, effective memory/reservation/CPU/PID
+limits and two timestamped `docker stats --no-stream` samples for running app containers. Memory samples retain
+Docker's display precision. CPU samples are Docker's bounded observations, not a whole-load benchmark. The
+collector never launches workload, reads logs, executes in containers or inspects a shared database's cgroup.
+Both container identity/configuration and the private profile are rechecked before returning success.
+
+`database.mode: host_profile` with `binding_matches_profile: true` proves this app's root-owned profile supplied
+the API's current private `DATABASE_URL`. `removed_services` describes that profile's applied removals; a remaining
+removed service refuses. `app_service` means the runtime connection names another reported service.
+`external_unverified` and `unconfigured` establish no managed database ownership. No DSN, username, password,
+other environment variable or raw host output leaves the host. This is connection provenance, not proof of SQL
+grants, migrated data or application behavior: still verify the app's authenticated data path through its public API.
+
+The complete inventory is scoped to this app before inspect/stats; no unfiltered Docker inventory is used.
+A missing/ambiguous API, stale build, changed container/profile, binding mismatch, unbounded service limits or
+malformed result refuses proof. A replay is another read and makes no mutation. Empty identity-diagnostic log
+records never establish database ownership or resources, and an absent source `db` container alone proves no
+shared-database substitution.
+
+## Install a published host runtime
+
+Use the published package's `backend-action/install_runtime.py` with its npm archive, the registry's exact
+`dist.integrity`, version and existing panel owners. Verify the archive's sha512 before extracting the installer.
+For example, after transferring those verified public files to task-owned host scratch:
+
+```sh
+python3 install_runtime.py --archive gowalk-cicd-1.0.191.tgz --integrity "$PACKAGE_INTEGRITY" \
+  --version 1.0.191 --owner robot --owner vpnrobot
+```
+
+The root-only installer verifies integrity/name/version again, installs only package-owned backend helpers under
+`/opt/gowalk-cicd-runtime/<version>`, and atomically retargets each named owner's exact existing forced command in
+`/root/.ssh/authorized_keys`. It refuses missing/duplicate owners, nonrestricted entries, untrusted paths and
+changed existing release bytes; it never provisions keys or changes another entry. Exact replay verifies the
+release and leaves keys unchanged. A fixed receipt confirms the version and owners without key contents.
+It changes no app source, runtime profile, container, database, service timer or deployment freeze. Preserve the
+previous release directory; this is ordinary released-helper installation, not app-state recovery.
+Verify a fresh scoped readback through each owner and keep that receipt with the exact npm integrity and release.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gowalk-cicd",
-  "version": "1.0.190",
+  "version": "1.0.191",
   "description": "Zero-config GitHub Actions delivery for iOS TestFlight and Android Google Play.",
   "type": "module",
   "bin": {