agents-city 0.3.0-beta.21

package/plugin/scripts/find-repos.sh

@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+# Index the git repos already cloned on this machine, wherever they are, and
+# cache it. One line each:  <name-on-the-remote><TAB><local-path>
+#
+#   find-repos.sh            uses the cache while it is less than a day old
+#   find-repos.sh --refresh  rebuilds it
+#   find-repos.sh <repo>     prints that repo's path, or nothing
+#
+# The name comes from the `origin` remote and not from the folder name, so it
+# finds the repo even when the folder is called something else — which is the
+# normal case for anybody with more than ten of them.
+#
+#   AGENTS_CITY_ORG     only index repos of this organisation. Unset = all of
+#                       them; the filter is for machines that also hold work
+#                       from somewhere else.
+#   CITY_SEARCH_IN      colon-separated roots to search instead of the defaults
+#   CITY_SEARCH_DEPTH   how deep to go under each root (default 4)
+
+set -uo pipefail
+
+ORG="${AGENTS_CITY_ORG:-}"
+CACHE_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/agents-city"
+CACHE="$CACHE_DIR/repos.tsv"
+RAICES_DEF="$HOME/codigo:$HOME/code:$HOME/dev:$HOME/src:$HOME/projects:$HOME/proyectos:$HOME/work:$HOME/trabajo:$HOME/repos:$HOME/git:$HOME/Documents:$HOME/Desktop:$HOME/Developer:$HOME"
+RAICES="${CITY_SEARCH_IN:-$RAICES_DEF}"
+PROFUNDIDAD="${CITY_SEARCH_DEPTH:-4}"
+
+construir() {
+  mkdir -p "$CACHE_DIR"
+  local tmp="$CACHE.tmp.$$"
+  : > "$tmp"
+  local vistos=""
+  local IFS=':'
+  for raiz in $RAICES; do
+    unset IFS
+    [ -d "$raiz" ] || continue
+    # Do not walk a root another one already covered.
+    case ":$vistos:" in *":$raiz:"*) continue ;; esac
+    vistos="$vistos:$raiz"
+
+    # `.git` is a directory in a normal clone and a FILE in a linked worktree —
+    # and a worktree is exactly the folder an isolated agent works in, so missing
+    # them missed the people using agents the most. Both are indexed; a worktree
+    # is named `repo@branch` so the two are distinct things to pick.
+    find "$raiz" -maxdepth "$PROFUNDIDAD" \( -type d -o -type f \) -name .git \
+      -not -path "*/node_modules/*" \
+      -not -path "*/Library/*" \
+      -not -path "*/.Trash/*" \
+      -not -path "*/vendor/*" \
+      -not -path "*/.cache/*" \
+      -not -path "*/plugins/cache/*" \
+      -not -path "*/.cargo/*" -not -path "*/.asdf/*" -not -path "*/miniconda3/*" \
+      -not -path "*/.rbenv/*" -not -path "*/.pyenv/*" -not -path "*/.nvm/*" \
+      2>/dev/null \
+    | while read -r g; do
+        repo="$(dirname "$g")"
+        url="$(git -C "$repo" remote get-url origin 2>/dev/null)" || continue
+        [ -z "$url" ] && continue
+        # git@host:org/name.git  |  https://host/org/name(.git)
+        # The version excluded by an organisation whose default was the literal
+        # "<your-org>", so the index came back empty for everybody who never set
+        # the variable. Unset now means: index what is there.
+        if [ -n "$ORG" ]; then
+          case "$url" in
+            *[:/]"$ORG"/*) ;;
+            *) continue ;;
+          esac
+        fi
+        nombre="$(basename "$url" .git)"
+        if [ -f "$g" ]; then
+          rama="$(git -C "$repo" branch --show-current 2>/dev/null)"
+          [ -z "$rama" ] && rama="$(basename "$repo")"
+          nombre="$nombre@$rama"
+        fi
+        [ -n "$nombre" ] && printf '%s\t%s\n' "$nombre" "$repo"
+      done >> "$tmp"
+    IFS=':'
+  done
+  unset IFS
+  # First one wins on a duplicate: the roots run from most specific to least.
+  sort -u -t$'\t' -k1,1 "$tmp" > "$CACHE"
+  rm -f "$tmp"
+}
+
+caduca() {
+  [ ! -f "$CACHE" ] && return 0
+  [ -n "$(find "$CACHE" -mtime +1 2>/dev/null)" ] && return 0   # older than a day
+  return 1
+}
+
+case "${1:-}" in
+  --refresh|--refrescar)
+    echo "Looking for cloned repos…" >&2
+    construir
+    echo "$(wc -l < "$CACHE" | tr -d ' ') repos indexed in $CACHE" >&2
+    ;;
+  "")
+    caduca && construir
+    cat "$CACHE"
+    ;;
+  *)
+    caduca && construir
+    ruta="$(awk -F'\t' -v n="$1" '$1==n {print $2; exit}' "$CACHE")"
+    # Not there? It may have been cloned a minute ago: rebuild once and retry.
+    if [ -z "$ruta" ]; then
+      construir
+      ruta="$(awk -F'\t' -v n="$1" '$1==n {print $2; exit}' "$CACHE")"
+    fi
+    [ -n "$ruta" ] && printf '%s\n' "$ruta"
+    ;;
+esac

package/plugin/scripts/gh.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+"""Who and what, according to GitHub and according to git.
+
+Used by both doors — `./bin/seat` and the wizard — so it sits in the folder that
+ships. Everything here is optional: nothing in this project requires an account, and
+every function returns empty rather than raising when `gh` is missing or logged out.
+"""
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import unicodedata
+from collections import Counter
+
+
+def sh(args, timeout=180):
+    """Run something and take its stdout, or '' if it failed in any way."""
+    try:
+        r = subprocess.run(args, capture_output=True, text=True, timeout=timeout)
+        return r.stdout if r.returncode == 0 else ""
+    except (OSError, subprocess.TimeoutExpired):
+        return ""
+
+
+def hay(programa):
+    return bool(shutil.which(programa))
+
+
+def conectado():
+    """`gh` present *and* logged in. Both, because an installed-but-anonymous gh
+    fails on the first list with a message about scopes that reads like a bug."""
+    if not hay("gh"):
+        return False
+    try:
+        r = subprocess.run(["gh", "auth", "status"], capture_output=True, text=True, timeout=20)
+        return r.returncode == 0
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+
+
+def autentica_web():
+    """Run GitHub CLI's browser/device OAuth conversation in the foreground."""
+    if not hay("gh"):
+        return False
+    try:
+        r = subprocess.run(["gh", "auth", "login", "--web", "--git-protocol", "https"])
+        return r.returncode == 0 and conectado()
+    except OSError:
+        return False
+
+
+def login():
+    """Your GitHub login, which is *not* the same string as your card's user.
+
+    A card's user comes from a git email's local part. Mine is `joseluiscases`; my
+    login is `jlcases`. Anything asking GitHub `author:<who>` needs this one — the
+    other gives a 422 that the caller swallows, so the number silently never arrives.
+    """
+    return sh(["gh", "api", "user", "--jq", ".login"]).strip()
+
+
+def orgs():
+    out = sh(["gh", "api", "user/orgs", "--jq", ".[].login"])
+    return [l.strip() for l in out.splitlines() if l.strip()]
+
+
+def repos(dueno):
+    """A user's or an organisation's repos: (name, description, last pushed)."""
+    out = sh(
+        [
+            "gh",
+            "repo",
+            "list",
+            dueno,
+            "--limit",
+            "400",
+            "--no-archived",
+            "--json",
+            "name,pushedAt,description",
+        ]
+    )
+    try:
+        return [
+            (r["name"], (r.get("description") or "")[:60], r.get("pushedAt", "")[:10])
+            for r in json.loads(out or "[]")
+        ]
+    except json.JSONDecodeError:
+        return []
+
+
+def miembros(org):
+    out = sh(["gh", "api", f"orgs/{org}/members", "--paginate", "--jq", ".[].login"])
+    return [l.strip() for l in out.splitlines() if l.strip()]
+
+
+# ── identity, from a git email ─────────────────────────────────────────────
+def usuario_de_correo(correo):
+    """The username inside an email. One rule, shared by every door.
+
+    A `+` means one of two opposite things and the digits tell you which:
+
+      12345678+alice@users.noreply.github.com  ->  alice
+          GitHub's private-email setting. The number is the account id, so the name
+          is after the plus. Taking the whole thing gives a card called
+          `12345678+alice.md` and an agent name nobody can type.
+
+      alice+work@example.com                   ->  alice
+          Ordinary plus-addressing. Here the account is before the plus.
+
+    Then down to something safe as a filename and as a name on the bus, but
+    transliterated rather than stripped: `josé` should be `jose`, not `jos`.
+    """
+    u = correo.split("@")[0].strip().lower()
+    if "+" in u:
+        izq, der = u.split("+", 1)
+        u = der if izq.isdigit() else izq
+    # NFKD splits an accented letter into letter + mark, and dropping the marks is
+    # what turns Máx into max instead of Mx.
+    u = unicodedata.normalize("NFKD", u).encode("ascii", "ignore").decode()
+    return re.sub(r"[^a-z0-9._-]", "", u)
+
+
+def es_maquina(usuario, nombre):
+    """Whether this author is a bot. `[bot]` is the GitHub App convention, but plenty
+    of CI identities just call themselves some flavour of bot, and a card for one of
+    those is a card nobody can ask anything."""
+    return any(
+        s in f"{usuario} {nombre}".lower()
+        for s in ("[bot]", "dependabot", "renovate", "github-actions", "noreply")
+    )
+
+
+def gente_de_repos(rutas):
+    """Whoever has commits in these folders. Works with no account at all.
+
+    Grouped by username alone, not by (username, name). One person writes their own
+    name three ways across a decade of commits — "Max Carrion", "Máx Carrión",
+    "maxc" — and counting those separately offered the same person three times and
+    then wrote their card three times over the top of itself. The name shown is
+    whichever spelling they used most.
+    """
+    porUsuario = {}
+    for r in rutas:
+        if not os.path.isdir(r):
+            continue
+        for l in sh(["git", "-C", r, "log", "--since=1.year", "--format=%ae|%an"]).splitlines():
+            if "|" not in l:
+                continue
+            correo, nombre = l.split("|", 1)
+            u = usuario_de_correo(correo)
+            if u and not es_maquina(u, nombre):
+                porUsuario.setdefault(u, Counter())[nombre.strip()] += 1
+    fuera = [
+        (u, nombres.most_common(1)[0][0], sum(nombres.values()))
+        for u, nombres in porUsuario.items()
+    ]
+    return sorted(fuera, key=lambda x: -x[2])[:40]

package/plugin/scripts/hall_protocol.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""The Hall protocol: three frames, a per-connection sequence, no replay.
+
+The Hall is the local web page that watches the cities and writes to the seat.
+It talks to the bus the page is served from — same origin, one socket — and
+this module is the transport-free contract both ends share: the frame shapes,
+the monotonic per-connection sequence, and the one rule that removes a whole
+class of bugs — events are never replayed, so on a sequence gap the client
+re-fetches a snapshot instead of the server keeping a durable per-client log.
+
+Writing to the seat is one method with a queue mode, not several: the same
+call reaches an idle seat (start a turn) or a busy one (steer into the running
+turn, or queue, or just leave a note), and the bus decides which. Loopback is
+a convenience for pairing, never a substitute for the seat's own admission.
+
+Pure Python so the Hall's server and its tests validate frames identically;
+the browser side reimplements the same shapes in TypeScript when it is built.
+"""
+
+import json
+from enum import Enum
+
+PROTOCOL = 'agents-city-hall/1'
+
+
+class Tipo(str, Enum):
+    REQ = 'req'      # client -> bus: a method call
+    RES = 'res'      # bus -> client: the paired reply
+    EVENT = 'event'  # bus -> client: an unsolicited push, carrying seq
+
+    def __str__(self):
+        return self.value
+
+
+class Modo(str, Enum):
+    """How a write to the seat meets the seat's current turn."""
+    INICIA = 'start'        # idle seat: begin a new turn
+    DIRIGE = 'steer'        # busy seat: inject into the running turn
+    ENCOLA = 'queue'        # busy seat: run after the current turn
+    NOTA = 'note'           # write to the transcript, do not wake the seat
+
+    def __str__(self):
+        return self.value
+
+
+#: Closed method set. A method outside it is refused at the edge, never routed.
+METODOS = frozenset({
+    'hall.hello',        # handshake: negotiate protocol + declare read scope
+    'cities.snapshot',   # subscribe-and-snapshot in one round trip
+    'seat.write',        # write to the seat (carries a Modo)
+    'seat.history',      # re-fetch a seat transcript after a gap
+    'pairing.pending',   # list opaque pending road pairings
+    'pairing.approve',   # approve one by opaque id
+})
+
+#: Structured error codes the client branches on (never prose-matching).
+ERRORES = frozenset({
+    'unknown_method', 'bad_frame', 'unauthorized', 'seat_busy',
+    'not_addressed', 'rate_limited', 'gap_detected',
+})
+
+MAX_TEXTO = 64_000
+
+
+def error(codigo, mensaje, reintentable=False):
+    if codigo not in ERRORES:
+        raise ValueError(f'unknown error code: {codigo}')
+    return {'code': codigo, 'message': mensaje, 'retryable': bool(reintentable)}
+
+
+def valida_req(frame):
+    """Validate an inbound request frame. Returns (ok, problema|None).
+
+    Fail-closed: an unknown method, a missing id, a non-object params, or a
+    steer/queue write without text is refused here rather than deeper in.
+    """
+    if not isinstance(frame, dict):
+        return False, error('bad_frame', 'frame must be an object')
+    if frame.get('type') != Tipo.REQ.value:
+        return False, error('bad_frame', 'not a req frame')
+    if not isinstance(frame.get('id'), str) or not frame['id']:
+        return False, error('bad_frame', 'req needs a string id')
+    metodo = frame.get('method')
+    if metodo not in METODOS:
+        return False, error('unknown_method', f'no such method: {metodo}')
+    params = frame.get('params', {})
+    if not isinstance(params, dict):
+        return False, error('bad_frame', 'params must be an object')
+    if metodo == 'seat.write':
+        modo = params.get('mode', Modo.INICIA.value)
+        if modo not in {m.value for m in Modo}:
+            return False, error('bad_frame', f'unknown write mode: {modo}')
+        texto = params.get('text', '')
+        # text must be an actual string — a dict/list/number silently stringified
+        # would be admitted and forwarded as 'None' or "{'x': 1}".
+        if not isinstance(texto, str):
+            return False, error('bad_frame', 'text must be a string')
+        if modo != Modo.NOTA.value and not texto.strip():
+            return False, error('bad_frame', 'a seat write needs non-empty text')
+        if len(texto) > MAX_TEXTO:
+            return False, error('bad_frame', f'text exceeds {MAX_TEXTO} characters')
+    return True, None
+
+
+def respuesta(id_, payload=None, err=None):
+    """Build a res frame paired to a req id. Exactly one of payload/err."""
+    if (payload is None) == (err is None):
+        raise ValueError('a response carries exactly one of payload or error')
+    frame = {'type': Tipo.RES.value, 'id': id_, 'ok': err is None}
+    if err is None:
+        frame['payload'] = payload
+    else:
+        frame['error'] = err
+    return frame
+
+
+class Secuencia:
+    """A per-connection monotonic sequence stamped on every event.
+
+    The client watches for gaps: a jump means frames were dropped (a slow
+    consumer is served by dropping, not by unbounded buffering), and the client
+    recovers by re-fetching a snapshot — the server keeps no durable replay log.
+    """
+
+    def __init__(self):
+        self._n = 0
+
+    def evento(self, nombre, payload):
+        self._n += 1
+        return {'type': Tipo.EVENT.value, 'event': nombre, 'seq': self._n, 'payload': payload}
+
+    @staticmethod
+    def hay_hueco(ultimo_visto, seq):
+        """True when `seq` is not exactly one past `ultimo_visto` — a gap."""
+        return seq != ultimo_visto + 1
+
+
+def codifica(frame):
+    return json.dumps(frame, separators=(',', ':'))
+
+
+def descodifica(crudo):
+    """Parse one wire frame, or (None, problema) on malformed input."""
+    try:
+        return json.loads(crudo), None
+    except (json.JSONDecodeError, TypeError):
+        return None, error('bad_frame', 'frame is not valid json')

package/plugin/scripts/hook_activity.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""Mirror Claude's visible prompts and final answers onto the city WebSocket."""
+import hashlib
+import json
+import os
+import subprocess
+import sys
+
+import runtime_log
+import runtime_processes
+
+
+def text(value, limit=4000):
+    return str(value or '').strip()[:limit]
+
+
+def source_id(event, payload, content):
+    session = text(payload.get('session_id'), 100) or 'session'
+    transcript = text(payload.get('transcript_path'), 1000)
+    try:
+        position = os.path.getsize(transcript) if transcript else 0
+    except OSError:
+        position = 0
+    digest = hashlib.sha256(content.encode('utf-8')).hexdigest()[:20]
+    return f'claude:{session}:{event}:{position}:{digest}'
+
+
+def marker_path(data, actor):
+    safe = ''.join(c if c.isalnum() or c in '_-' else '-' for c in actor)[:80] or 'seat'
+    return os.path.join(runtime_processes.ruta(data), 'claude-threads', safe + '.json')
+
+
+def marker(data, actor):
+    try:
+        with open(marker_path(data, actor), encoding='utf-8') as stream:
+            value = json.load(stream)
+        return text(value.get('thread'), 160) or None
+    except (OSError, ValueError, TypeError, json.JSONDecodeError):
+        return None
+
+
+def clear_marker(data, actor):
+    try:
+        os.unlink(marker_path(data, actor))
+    except OSError:
+        pass
+
+
+def internal_city_prompt(content):
+    prompt = content.lstrip()
+    return (prompt.startswith('[Agents City authenticated local bus]')
+            or (prompt.startswith('<channel')
+                and 'source="plugin:city:city-bus"' in prompt[:500]))
+
+
+def activity(event, payload, data='', actor='seat'):
+    session = text(payload.get('session_id'), 160) or None
+    if event == 'UserPromptSubmit':
+        content = text(payload.get('prompt'))
+        if not content:
+            return None
+        if internal_city_prompt(content):
+            # The committee state machine already emits a concise assignment.
+            # Mirroring the transport wrapper produces the unreadable <channel>
+            # wall that the Hall must never expose.
+            return None
+        clear_marker(data, actor)
+        return session, {
+            'sourceId': source_id(event, payload, content),
+            'kind': 'conversation.user', 'phase': 'asked', 'tone': 'question',
+            'title': f'{actor} asked', 'summary': content,
+        }
+    if event == 'Stop':
+        content = text(payload.get('last_assistant_message'))
+        if not content:
+            return None
+        return marker(data, actor) or session, {
+            'sourceId': source_id(event, payload, content),
+            'kind': 'conversation.agent', 'phase': 'answered', 'tone': 'evidence',
+            'title': f'{actor} answered', 'summary': content,
+        }
+    if event in ('SessionStart', 'SessionEnd'):
+        phase = 'started' if event == 'SessionStart' else 'ended'
+        return session, {
+            'sourceId': source_id(event, payload, phase),
+            'kind': f'runtime.session.{phase}', 'phase': phase, 'tone': 'system',
+            'title': f'{actor} session {phase}',
+            'summary': f'Claude session {phase}.',
+        }
+    return None
+
+
+def main():
+    event = sys.argv[1] if len(sys.argv) > 1 else ''
+    data = os.environ.get('AGENTS_CITY_DATA', '')
+    actor = text(os.environ.get('CITY_BUS_ACTOR'), 80) or 'seat'
+    try:
+        payload = json.load(sys.stdin)
+    except (ValueError, OSError):
+        payload = {}
+    # The native Claude stream gateway has the exact bus-envelope/thread
+    # correlation and publishes the visible answer itself. Mirroring the same
+    # turn from lifecycle hooks would show it twice in the Hall. Token/growth
+    # hooks remain enabled; only this activity mirror becomes a no-op.
+    if os.environ.get('CITY_CLAUDE_STREAM_GATEWAY') == '1':
+        print('{}')
+        return
+    chosen = activity(event, payload, data, actor)
+    if chosen and data:
+        thread, body = chosen
+        client = os.path.realpath(
+            os.path.join(os.path.dirname(__file__), '..', 'channel', 'client.js')
+        )
+        command = ['node', client, 'activity', 'publish']
+        if thread:
+            command.append(thread)
+        command += ['--input', '-']
+        try:
+            result = subprocess.run(
+                command, input=json.dumps(body), capture_output=True, text=True,
+                timeout=6, env=dict(os.environ, CITY_BUS_ACTOR=actor))
+            if result.returncode:
+                runtime_log.append(data, f'claude-hook:{actor}', 'activity.publish.failed',
+                                   actor=actor, outcome='failed', message=result.stderr)
+            else:
+                runtime_log.append(data, f'claude-hook:{actor}', 'activity.published',
+                                   actor=actor, outcome='ok', message=event)
+        except Exception as error:
+            runtime_log.append(data, f'claude-hook:{actor}', 'activity.publish.failed',
+                               actor=actor, outcome='failed', message=error)
+    if event in ('Stop', 'SessionEnd') and data:
+        clear_marker(data, actor)
+    # Claude hooks accept an empty JSON decision. Mirroring is deliberately
+    # fail-open so observability can never block the user's model session.
+    print('{}')
+
+
+if __name__ == '__main__':
+    main()

package/plugin/scripts/launch.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""Create a short, auditable launcher so tmux never has to paste long commands."""
+import argparse
+import base64
+import json
+import os
+import shlex
+import time
+
+import runtime_processes
+
+
+def safe(value):
+    cleaned = ''.join(c if c.isalnum() or c in '-_' else '-' for c in value.lower())
+    return cleaned.strip('-')[:80] or 'actor'
+
+
+def make(args):
+    directory = os.path.join(runtime_processes.ruta(args.data), 'launchers')
+    app_home = os.path.realpath(os.environ.get('AGENTS_CITY_HOME') or
+                                os.path.join(args.data, '..', '..'))
+    os.makedirs(directory, mode=0o700, exist_ok=True)
+    os.chmod(directory, 0o700)
+    path = os.path.join(directory, f'{safe(args.actor)}-{os.getpid()}-{time.time_ns()}.sh')
+    command = base64.b64encode(args.command.encode('utf-8')).decode('ascii')
+    failure = base64.b64encode(json.dumps({
+        'sourceId': f'launcher:{args.actor}:{time.time_ns()}:failed',
+        'kind': 'runtime.launch.failed',
+        'phase': 'failed',
+        'tone': 'error',
+        'title': f'{args.actor} failed to start',
+        'summary': 'The agent command exited before a usable session was ready.',
+    }).encode('utf-8')).decode('ascii')
+    log = os.path.realpath(os.path.join(os.path.dirname(__file__), 'runtime_log.py'))
+    client = os.path.realpath(args.client)
+    lines = [
+        '#!/usr/bin/env bash',
+        'set +e',
+        f'DATA={shlex.quote(os.path.realpath(args.data))}',
+        f'APP_HOME={shlex.quote(app_home)}',
+        f'ACTOR={shlex.quote(args.actor)}',
+        f'WORKDIR={shlex.quote(os.path.realpath(args.cwd))}',
+        f'RUNTIME_DIR={shlex.quote(os.path.dirname(directory))}',
+        f'CLIENT={shlex.quote(client)}',
+        f'RUNTIME_LOG={shlex.quote(log)}',
+        f'COMMAND_B64={shlex.quote(command)}',
+        f'FAILURE_B64={shlex.quote(failure)}',
+        'export AGENTS_CITY_HOME="$APP_HOME" AGENTS_CITY_DATA="$DATA" CITY_BUS_ACTOR="$ACTOR"',
+        'python3 "$RUNTIME_LOG" launch.started --data "$DATA" --component launcher '
+        '  --actor "$ACTOR" --outcome starting',
+        'cd "$WORKDIR"',
+        'cd_status=$?',
+        'if [ "$cd_status" -eq 0 ]; then',
+        '  command_text="$(printf %s "$COMMAND_B64" | base64 --decode)"',
+        '  eval "$command_text"',
+        '  status=$?',
+        'else',
+        '  status=$cd_status',
+        'fi',
+        'if [ "$status" -eq 0 ]; then',
+        '  python3 "$RUNTIME_LOG" launch.exited --data "$DATA" --component launcher '
+        '    --actor "$ACTOR" --outcome ok --message "exit 0"',
+        'else',
+        '  python3 "$RUNTIME_LOG" launch.failed --data "$DATA" --component launcher '
+        '    --actor "$ACTOR" --outcome failed --message "exit $status"',
+        '  printf %s "$FAILURE_B64" | base64 --decode | env AGENTS_CITY_DATA="$DATA" '
+        '    CITY_BUS_ACTOR="$ACTOR" node "$CLIENT" activity publish '
+        '    --input - >/dev/null 2>&1 || true',
+        '  printf "\\n  Agents City: %s failed to start (exit %s).\\n" "$ACTOR" "$status" >&2',
+        '  printf "  Diagnostics: %s/diagnostics.jsonl\\n\\n" "$RUNTIME_DIR" >&2',
+        'fi',
+        'exit "$status"',
+        '',
+    ]
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o700)
+    with os.fdopen(fd, 'w', encoding='utf-8') as stream:
+        stream.write('\n'.join(lines))
+    print(path)
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument('verb', choices=['create'])
+    parser.add_argument('--data', required=True)
+    parser.add_argument('--actor', required=True)
+    parser.add_argument('--cwd', required=True)
+    parser.add_argument('--client', required=True)
+    parser.add_argument('--command', required=True)
+    args = parser.parse_args()
+    make(args)
+
+
+if __name__ == '__main__':
+    main()