agents-city 0.1.0

package/demo/units.yml

@@ -0,0 +1,33 @@
+# Business units — the districts of your city.
+#
+# This is yours to define at install time. The map reads it, so the districts,
+# their names, their colours and their order come from here and not from the
+# code. The demo ships a game studio; replace it with your own units and the map
+# redraws itself.
+#
+# id      what you write in `unidad` inside parcels.yml
+# name    what shows on the banner
+# color   hex, without the #
+# order   left to right; the shared district usually goes last
+units:
+  - id: mobile   ; name: Mobile Games      ; color: 3fb8a0 ; order: 1
+  - id: console  ; name: Console Games     ; color: 8f7ae6 ; order: 2
+  - id: arcade   ; name: Arcade Cabinets   ; color: e08a3c ; order: 3
+  - id: school   ; name: School Editions   ; color: 4a9ede ; order: 4
+  - id: platform ; name: Platform          ; color: 6f8fbf ; order: 5
+    note: "store, launcher, live ops — every unit ships through it"
+  - id: data     ; name: Player Data       ; color: e2604f ; order: 6
+    note: "telemetry, experiments, the numbers everyone argues with"
+
+# Two districts every city has, whatever the business.
+#
+# The lab does not ship yet, and it is needed. It gets its own district instead
+# of falling into the shared bucket on purpose: a lab repo among the orphans
+# reads as waste, and it is the opposite. Its houses are drawn with permanent
+# scaffolding, and its growth is not compared against the shipping units — a lab
+# house with few floors is not behind, it is early.
+special:
+  - id: lab      ; name: Lab               ; color: 8fb8c9 ; order: 90
+    note: "doesn't ship yet, and it's needed"
+  - id: none     ; name: No unit           ; color: c8b48a ; order: 99
+    note: "serves several units, or none"

package/docs/agents-first.md

@@ -0,0 +1,106 @@
+# Agents come first
+
+The original model was "a repo is an agent": every window was a git checkout,
+and anyone whose work was a folder of documents — no git at all — had nowhere
+to live. The model is now inverted. The primary unit is the **agent**; a repo
+is just one thing an agent can mount.
+
+The inversion is total but loses nothing, because the old model is a special
+case of the new one — so **existing cities keep working untouched**.
+
+## The model
+
+An agent has a **workspace folder** (`<city>/agents/<slug>/`) as its working
+directory, and inside it a `mounts/` folder of **symlinks** to wherever the
+real work lives: a git repo, a linked worktree, or a plain folder of documents.
+
+```
+<city>/agents/writer/
+├── mounts/
+│   ├── handbook   -> ~/Documents/handbook      # a document folder, no git
+│   └── spec       -> ~/code/product/spec        # a subtree of a repo
+└── (the agent's own notes live directly here)
+```
+
+An agent also has a **kind** — `code`, `knowledge`, or `coordinator` — which is
+what makes the map polymorphic instead of assuming everyone ships pull requests.
+
+## Two card shapes, one internal model
+
+`plugin/scripts/workspace.py` normalises **both** card shapes into one list of
+`Agente`, so the launcher, the cage and the map read one model regardless of how
+the card was written.
+
+**Read forever, written never.** The legacy shape below is still parsed by
+every door, so a city written a year ago opens today exactly as it did. Nothing
+writes it any more: the wizard and the Hall both produce the agent-first shape
+through `workspace.claves_de_roster`, because two writers of one fact is how the
+terminal and the web ended up able to produce different cities for the same
+city. Re-running `./bin/seat --agents` over an old card upgrades it in place.
+
+Legacy (still read — every repo is an agent whose single mount is that repo):
+
+```yaml
+repos: [nova, store-service]
+role.nova: po
+```
+
+Agent-first (adds `kind.<agent>` and `mounts.<agent>`):
+
+```yaml
+agents: [writer, chair]
+kind.writer: knowledge
+mounts.writer: [~/Documents/handbook, ~/code/product/spec]
+kind.chair: coordinator
+runs.chair: claude
+```
+
+## How the cage follows a mount
+
+The cage seals by path, so an agent's workspace is exactly what it makes
+writable — plus the **resolved targets** of its mounts. Because seatbelt
+resolves symlinks at the kernel, `mount_targets()` follows each symlink to its
+real destination and the launcher passes those to `cage.py --mounts`. A mount
+that resolves inside a sealed root (`~/.ssh`, the broker store, …) is refused,
+never honoured: the security invariant holds under the new model, and
+`bin/test-cage.py` proves the writable-mount / sealed-secret split against the
+live kernel.
+
+## Managing mounts
+
+```bash
+agents-city agents list    --data <city> --card <card>       # list normalised agents
+agents-city agents mount   --data <city> --agent writer --src ~/Documents/handbook
+agents-city agents mounts  --data <city> --agent writer      # what is mounted
+agents-city agents unmount --data <city> --agent writer --name handbook
+```
+
+At session start the launcher runs `workspace.py sync` for each agent, which
+creates the workspace and materialises every declared mount (skipping a missing
+source with a warning rather than aborting the city).
+
+## Growth without git — `crecimiento.py`
+
+A house grows by what its agent actually does, not by pull requests alone:
+
+- **code** — floors = merged PRs, bricks = commits (an injected git counter).
+- **knowledge** — floors = documents in the workspace, bricks = recent edits.
+- **coordinator** — floors = recorded decisions, bricks = notices.
+
+Every counter returns the same `{floors, bricks, activity30, signal}` shape, so
+a person with no git at all now has a house that grows as their knowledge does.
+
+## Avatars — `avatar.py`
+
+Each agent gets a deterministic, self-contained SVG identicon from its name
+(same name → same face), with the border tinted by kind. No network, no
+library, no external asset, so it drops into the Hall under its strict CSP —
+`avatar.data_uri(name, kind)` is ready for an `<img src>`.
+
+## Presence and "thinking"
+
+The activity pipeline already emits on `UserPromptSubmit` (a turn begins) and
+`Stop` (it ends), so "active since the last prompt without a stop" is derivable
+from the existing feed — the Hall renders it. This document's generators
+(avatars, growth) provide the data; wiring them into the Hall view is the
+rendering layer's job.

package/docs/glossary.md

@@ -0,0 +1,55 @@
+# Glossary
+
+The code keeps a small Spanish domain vocabulary. These are the canonical v2
+meanings.
+
+| Term | Meaning |
+|---|---|
+| city / `ciudad` | One autonomous work domain with one owner seat |
+| owner / `usuario` | The local person who may own several cities |
+| seat / `asiento` | The city's only road-facing agent; owns its role and goal |
+| chair / `presidente` | The seat while selecting agents, controlling turns and integrating a decision |
+| committee / `comité` | A bounded evidence process among the chair and selected repo agents |
+| floor / `palabra` | One evidence-backed reply requested by a member and granted or denied by the chair |
+| live feed | Read-only browser view of submitted committee artifacts and protocol actions over the local WebSocket bus; never model chain-of-thought |
+| act / `acta` | Durable human-readable decision, verification and closure record |
+| local bus | Per-city loopback WebSocket hub carrying typed internal and road envelopes |
+| native gateway | Provider-specific last mile that accepts a bus envelope through an official runtime protocol, never terminal paste |
+| Claude stream gateway | Default Agents City transport: one persistent official Claude Code process receiving acknowledged JSONL turns over stdin/stdout |
+| Claude Channel | Optional upstream preview path for injecting an event into an opted-in interactive session; not required by Agents City |
+| terminal fallback | Explicit `terminal:<command>` compatibility mode for an unknown CLI; the only mode allowed to inject into tmux |
+| address / `direccion` | Stable `owner/city` identity used on roads |
+| road / `carretera` | Explicit connection from one city seat to another |
+| support agent | A local agent window working inside one repo, with its own operating role; never road-facing |
+| operating role | The professional perspective assigned to one repo agent; separate from chair/member authority |
+| skill | A capability installed and owned by a repo/runtime, only recognised by Agents City |
+| card / `ficha` | The one owner file containing chair role, repos, per-repo roles, goal and window engines |
+| blank role | An explicit role with no built-in role knowledge or inferred responsibility |
+| round / `ronda` | Evidence exchange by a seat across its explicit roads |
+| notice / `carta` | A concrete change one city tells another city may affect its domain |
+| house / `casa` | One parcel drawn on the visual map |
+| parcel / `parcela` | A slice of a repo serving one unit; not necessarily a whole repo |
+| district / `barrio` | The visual area belonging to one business unit |
+| unit / `unidad` | A business unit represented by a district |
+| worker / `obrero` | A currently active agent window drawn on a parcel |
+| foreman / `perito` | Visual representation of the city seat near its support work |
+| architect / `arquitecto` | Legacy map name for the goal-owning seat |
+| trade / `oficio` | A role's name in the city metaphor |
+| square / `plaza` | The map's live-presence area and its Durable Object |
+| scaffold / `andamio` | An open pull request; visually stale after two weeks |
+| floors / `pisos` | Landed work; a house grows when work lands |
+| bricks / `ladrillos` | Commits not yet represented by a pull request |
+| crack / `grieta` | Failing CI |
+| milestone / `hito` | One day's landed work for one parcel |
+| oven / `horno` | Pipeline that bakes 3D models into isometric sprites |
+| step / `paso` | Distance between map plots, in tiles |
+
+Two special visual districts remain:
+
+- `lab`: research work that has not shipped;
+- `none`: work shared by several units or assigned to none.
+
+Some storage and API fields still use names such as `personas` for compatibility
+with existing map data. They do not change the v2 ownership rule: a personal city
+has exactly one owner seat; repo support agents and connected cities are separate
+entities.

package/docs/map-live-layers.md

@@ -0,0 +1,73 @@
+# The map's live layers
+
+The map used to describe last month: floors from merged PRs, windows lit by
+thirty days of activity. Three layers now describe **right now**, and all three
+are derived from data the product already emits — nothing on the map is
+invented at render time.
+
+## Presence: lights are turns
+
+A house whose agent is mid-turn glows and breathes, with three thinking dots
+over its worker (or over its roof when no worker figure is on site). A house
+whose agent just stopped cools down over about two minutes. A house with no
+session shows only its historical windows.
+
+Derived entirely from the activity feed the hooks already publish:
+
+| Event | Effect |
+| --- | --- |
+| `conversation.user` | the actor's house enters "in turn": pulsing glow + dots |
+| `conversation.agent` | the turn ended: the glow cools instead of cutting out |
+| `runtime.session.ended` | lights out, no afterglow |
+
+Code: `city/web/src/presencia.ts`. The Hall relays these lifecycle events to
+the embedded map (`isPresenceEvent` in `city/web/src/activity.ts`); they never
+become speech bubbles.
+
+## The town hall: the committee, staged
+
+A civic building stands past the square. When a deliberation opens it lights
+up and the badge over its door tracks the state machine — the same kinds
+`isSpeechEvent` already lists:
+
+- `committee.position.submitted` — the member's position flies in from their
+  house **face down**: isolated positions are the committee's one hard rule,
+  and the map shows the rule, not just the traffic.
+- `committee.position(s).revealed` — cards turn over.
+- `committee.floor.requested` — a "✋ palabra?" chip hangs over the house of
+  whoever asked; `granted`/`denied` answer it in colour.
+- `committee.verification.passed/failed` — the verifier's stamp over the door.
+- `committee.closed` — the act rises from the hall, signed; the cards leave
+  with it. `committee.cancelled` clears the stage with no act.
+
+One session on stage at a time; the Hall's right rail remains the transcript.
+Code: `city/web/src/ayuntamiento.ts`.
+
+## Gates: roads made visible
+
+One arch per road, at the city's entrance, with the road's name and its
+`owner/city` address on the plate. A notice whose recipient is not in this
+city flies out through the right gate and fades at the edge; one arriving from
+another city comes in the same way. The map never draws the far city — a road
+grants reachability, and the gate is exactly that much.
+
+The gates come from the Hall, which is the only thing that knows the roads: on
+loading the map iframe it sends a `map.config` message with them. The
+standalone team map never receives one and draws no gates rather than invent
+connections. Code: `city/web/src/puertas.ts`.
+
+## Rehearsing without a city
+
+Every layer can be driven from the browser console on any running map:
+
+```js
+__city.presence('conversation.user', 'nova');          // the house breathes
+__city.committee('committee.opened', 'seat', 'why');   // the hall lights up
+__city.committee('committee.position.submitted', 'nova');
+__city.roads([{ name: 'home', address: 'you/home' }]); // gates appear
+__city.letter('ada', 'you/home', 'security');          // out through the arch
+```
+
+`prefers-reduced-motion` is honoured the way the rest of the map honours it:
+every state is still shown — steady instead of breathing, placed instead of
+flown.

package/docs/security.md

@@ -0,0 +1,265 @@
+# The cage and the broker
+
+Yolo is non-negotiable here: a committee dies the moment every bus command
+needs a human. So the security model never touches the approval axis. It
+narrows the other one — what a window can *reach* — at the kernel and at the
+credential store, where a language model cannot talk its way past it.
+
+The threat this is built for is the one nobody has solved: prompt injection.
+A repo window reads text that ultimately came from outside — an issue, a log,
+a committee assignment quoting a road message — and no instruction to "treat
+it as untrusted" is a security control. The goal is therefore not to prevent
+the injection but to make a successful one worthless: nothing to steal, no
+credential to hold, and a signed trail of everything it tried.
+
+## Layer 1 — the cage (`plugin/scripts/cage.py`)
+
+Claude, OpenCode and Kimi agent windows launch confined by the kernel. Two
+mechanisms, one meaning — and the meaning is what `cage.py` owns, so the
+launcher asks for a prefix and never learns which kernel it is on:
+
+```
+macOS   sandbox-exec -f ~/.agents-city/.runtime/cage/<window>.sb <runtime …>
+Linux   bwrap --ro-bind / / … --tmpfs ~/.ssh … <runtime …>
+```
+
+On macOS the profile reads top to bottom: allow everything, deny all writes,
+re-allow the working set, then seal the secrets — reads and writes both. The
+semantics (last matching rule wins; children and grandchildren inherit) were
+verified on a real machine before a line of it was written.
+
+On Linux the same shape is expressed as mounts, applied in the same order and
+with the same last-one-wins rule: the whole filesystem read-only, the working
+set re-bound writable, each sealed directory replaced by an empty tmpfs, each
+sealed file replaced by `/dev/null`, and finally this window's own broker token
+re-admitted read-only. A sealed path is not refused — it is *not there*.
+
+Availability is checked by doing, not by looking: `bwrap_sirve()` builds a real
+namespace once and remembers the answer, because Ubuntu 24's AppArmor policy and
+hardened kernels can refuse unprivileged user namespaces even with bubblewrap
+installed. Where the cage cannot run, the launcher says so and starts uncaged —
+the behaviour the product always had. `bin/test-cage.py` re-proves both cages
+live: seatbelt on every macOS run, bubblewrap on every Linux run.
+
+Inside the cage a window **can**: work freely in its own repo, run builds,
+reach the network, keep its runtime state (`~/.claude`, `~/.codex`,
+`~/.agents-city`, build caches). It is never asked a question — yolo intact.
+
+Inside the cage a window **cannot**: read or write `~/.ssh`, `~/.aws`,
+`~/.kube`, `~/.gnupg`, `~/.docker`, `~/.config/gcloud`, `~/.config/gh`,
+`~/.git-credentials`, `~/.netrc`, `~/.pgpass`, cargo credentials,
+`~/.claude/.credentials.json`, any remote road `.env` under
+`~/.claude/channels/`, or the broker's state; nor write anywhere outside its
+repo and the allowed runtime/cache set — other repos on the machine included.
+
+`~/.claude/.credentials.json` earns its own line because it is the one this
+product created: `~/.claude` stays writable for runtime state, and outside
+macOS there is no Keychain, so Claude Code writes its OAuth tokens there as
+plain JSON. Every third-party credential store was sealed while ours was not,
+which is the sort of hole that only a review looking for it finds.
+
+### Where the two cages differ, exactly
+
+They seal the same set, and both are re-proved live on every CI run — seatbelt
+on macOS, bubblewrap on Linux. One difference is real and worth knowing:
+
+macOS states the road-token rule as a **pattern** (`channels/*/.env`), so a
+road created after the window started is sealed too. Linux states it as one
+**mount per file**, and a mount needs a path that exists — so a road opened
+mid-session is not sealed inside windows that were already running. It is
+sealed for every window started afterwards, and closing and reopening the city
+closes the gap. The alternative — hiding the whole `channels` directory — would
+also hide what the in-window hooks legitimately read, so this stays a known,
+bounded difference rather than a silent one.
+
+Dials, all environment variables read at launch:
+
+| Variable | Effect |
+| --- | --- |
+| `CITY_CAGE=0` | launch every window uncaged — exactly the old behaviour |
+| `CITY_CAGE_DENY=a:b` | extra paths to seal (e.g. `~/.npmrc`, see below) |
+| `CITY_CAGE_ALLOW_WRITE=a:b` | extra writable roots for unusual toolchains |
+
+On Linux or any machine without `sandbox-exec`, the prefix is empty and
+nothing changes. The seat is deliberately never caged: it is the permissioned,
+non-yolo side that holds the road token and asks the owner.
+
+Codex uses exactly one confinement layer: its native `workspace-write` sandbox
+(network enabled only in auto mode). It is deliberately not wrapped in the
+outer seatbelt profile because Codex MCPs such as `node_repl` create their own
+sandboxed worker; macOS rejects that second `sandbox_apply` when the entire
+gateway already runs under seatbelt. `CITY_CAGE=0` deliberately changes Codex
+to `dangerFullAccess` and launches the other providers without their outer
+cage.
+
+At startup, the Codex gateway also reads the effective MCP registry through the
+Codex CLI. An enabled stdio MCP whose executable is provably absent is disabled
+only through a process-local `-c mcp_servers.<name>.enabled=false` override for
+app-server and its TUI. The owner's `~/.codex/config.toml` is never rewritten;
+healthy, URL-based and uncertain integrations are left alone. Each scoped
+disable is recorded as `codex.mcp.unavailable.disabled` without MCP environment
+values.
+
+## Layer 2 — the credential broker (`plugin/scripts/broker.py`)
+
+A caged window cannot read the `gh` token — that is the cage working. But
+opening a pull request is legitimate work, so the window asks a small process
+the owner runs outside every cage, and that process acts with the real
+credentials after validating the request:
+
+```bash
+CITY_BROKER=1 agents-city seat            # start the session with a broker
+python3 plugin/scripts/broker.py call pr --title "Add X" --body "why"
+python3 plugin/scripts/broker.py call push
+```
+
+- One token per window, minted at session start, **bound to one repo**: a
+  stolen token cannot choose a different target.
+- Only the SHA-256 of a token is stored; the token itself travels as a file
+  path whose read is the single exception the window's cage re-allows.
+- The broker refuses any action on the default branch, always. Pushes are
+  `git push origin HEAD` — no force, no refspec.
+- The broker is opt-in (`CITY_BROKER=1`) while it covers only `pr` and `push`;
+  stop it with `broker.py stop --data <city-dir>`.
+
+## Layer 3 — the audit chain, with an evidence vocabulary
+
+Every broker request — served or refused — appends one line to
+`~/.agents-city/.runtime/broker/<id>/audit.log`, and each line carries the
+SHA-256 of the previous one. The cage denies repo windows the whole directory,
+so an agent cannot rewrite its own history, and `broker.py verify` catches a
+single flipped byte. `bin/test-broker.py` proves both directions.
+
+A hash chain proves a line was not altered; it says nothing about what the line
+proves. So every line also carries an evidence state (`plugin/scripts/evidencia.py`):
+`enforced` (a control decided the outcome), `attribution-only`, `unattributed`,
+`unknown`, `ambiguous`, `unsupported`. Two rules hold wherever it is read —
+`unknown` never means allowed, and `ambiguous` is never resolved by picking a
+candidate. A missing binding is `unknown`, which authorises nothing; only
+`enforced` is proof a control fired.
+
+## Layer 4 — path containment, resolved twice
+
+The cage's write-allow set and the broker's repo binding both trust paths, and
+`plugin/scripts/rutas.py` answers the same question for both: it resolves a path
+through the deepest ancestor that exists — so a missing leaf under a symlinked
+parent still lands on the real target — and refuses a path both when it sits
+inside a sealed root and when it *covers* one. The cage's own guarantee is the
+ordering (the secret-deny block is emitted last and wins), so a covering
+writable root is safe; what containment adds is refusing a repo rooted on the
+credential store and dropping an owner `CITY_CAGE_ALLOW_WRITE` that lands inside
+a seal. `bin/test-rutas.py` drives the primitive directly.
+
+## Layer 5 — road admission as a gate graph
+
+An inbound road message is admitted by an ordered gate graph
+(`plugin/scripts/admision.py`), not a boolean: address → road → sender →
+payload, first blocker decisive. It returns a stable reason code
+(`road_missing`, `sender_not_paired`, …) and, per gate, a redacted diagnostic —
+counts and opaque ids, never a raw allowlist entry — so a refusal is
+explainable without leaking who is allowed. A road that matches but whose sender
+does not is an explicit block; an unknown sender under pairing yields
+`pairing-required` rather than a silent drop.
+
+## Layer 6 — road pairing
+
+An unknown city earns the right to write to a seat through a short code
+(`plugin/scripts/pairing.py`): eight characters from an unambiguous alphabet, a
+one-hour TTL, at most three pending per city, and an opaque approval id so
+tooling never echoes the human code. The code is revealed once per sender per
+window, so re-messaging cannot re-spam it. Approving grants exactly one thing —
+permission for that address to write to this seat — never road membership, never
+chair authority. The store is consulted only under the pairing policy; it can
+never widen an existing allowlist.
+
+## Layer 7 — untrusted road text
+
+Text arriving over a road is wrapped once, on arrival, in an unforgeable
+boundary (`plugin/channel/untrusted.ts`): the opening marker carries a fresh
+random id per wrap, so a message that pastes its own closing marker cannot guess
+the id and cannot smuggle the rest as trusted text. Chat-template role tokens
+(`<|im_start|>`, `[INST]`, `<start_of_turn>`, …) are defanged first, so text
+cannot forge a synthetic system or assistant turn on a self-hosted backend. It
+is defence in depth for the seat, not a promise the model obeys the boundary.
+
+## Host-bound secrets — the broker without handing over the key
+
+A caged window cannot read an API token, and the broker does not hand it one.
+The owner binds a secret to an exact host set (`broker.py secret-set OPENAI
+--value … --allow-host api.openai.com`; no wildcards, no ports), and a window
+asks the broker to make the call carrying the secret by *name*
+(`broker.py call fetch --secret OPENAI --host api.openai.com --path /v1/…`). The
+broker injects the value only when the target host matches a bound one, and
+never returns it. A leaked transcript or `ps` line holds the request, never the
+credential.
+
+## The Hall protocol — writing to the seat from a page
+
+When the local web Hall is built, it talks to the bus that serves it over one
+same-origin socket, on the contract in `plugin/scripts/hall_protocol.py`: three
+frames (`req`/`res`/`event`), a per-connection monotonic sequence, and the rule
+that events are never replayed — on a gap the client re-fetches a snapshot. The
+method set is closed (`os.system` is not a method); writing to the seat is one
+call with a queue mode (`start`/`steer`/`queue`/`note`) so an idle and a busy
+seat are the same call. Loopback is a pairing convenience, never a substitute
+for the seat's own admission.
+
+## Config migrations — `doctor`
+
+The runtime reads one config schema. Every change that can invalidate an
+existing config ships a migration in `plugin/scripts/doctor.py` that detects the
+old shape, explains it in one line, writes a timestamped backup, and rewrites to
+canonical form. Migrations are idempotent and ordered, so a file needing several
+converges in one pass and a canonical file is left untouched. `--fix` writes;
+the default is a dry-run report.
+
+## The ratchet
+
+`bin/test-security.py` is not a unit suite but a firewall of cross-cutting
+invariants: the secret set always contains `~/.ssh`/`~/.git-credentials`/gh, the
+seal block is always emitted after the write-allow block, `unknown` evidence
+never authorises, an admission decision never carries a raw allowlist entry, the
+Hall method set stays closed, and the launcher never wraps the seat window in
+the cage. Each past sharp edge becomes a line here, and the line stays.
+
+## Scope — the conscience stays inside the city
+
+Installing the plugin does not enrol every Claude session on the machine.
+Every hook sources `plugin/hooks/solo-en-ciudad.sh` first: outside a city
+runtime — no `CITY_BUS_ACTOR`, the identity only `city-session.sh` sets — the
+hook answers `{}` and leaves. No review passes, no digging notes, no notice
+judgements, no token counters in plain conversations. The MCP server already
+declared itself inactive without an actor identity; this extends the same rule
+to the hooks, which were the remaining machine-wide surface.
+
+The machine-wide conscience still exists as an explicit choice:
+`CITY_HOOKS=everywhere`, in the environment or in
+`~/.claude/channels/city-bus/.env`. Second-order effects are opted into, never
+discovered. `bin/test-contracts.py` holds both sides: every hook is mute
+outside a city, and both opt-in paths open the gate.
+
+## What this does NOT do, in writing
+
+- **Prompt injection still exists.** The cage bounds what it is worth.
+- **Keychain credentials travel over IPC, not file reads.** A jailed `git
+  push` still works when GitHub credentials live in the macOS keychain; the
+  broker and forge-side protected branches are the guard there. If you keep
+  `~/.git-credentials` in plain text, move it: `git config --global
+  credential.helper osxkeychain`.
+- **Outbound network stays open** — that is what keeps yolo useful. A window
+  can still exfiltrate what it can already see: its own repo.
+- **Everything runs as your OS user.** The cage narrows file reach; it is not
+  hostile-process isolation. Untrusted code still belongs in a separate user,
+  VM or container.
+- `~/.npmrc` stays readable by default because denying it breaks `npm install`
+  for owners with a registry config. If yours holds tokens, add it to
+  `CITY_CAGE_DENY`.
+
+## Where this lands against an exposed-gateway agent
+
+The criticisms that stuck to OpenClaw-class setups were: reachable from the
+network, broad host access, credentials in reach of the model. Here: nothing
+listens beyond `127.0.0.1`, writes are kernel-bounded per repo, and the
+credentials a hijacked window would want are either unreadable (cage) or never
+held (broker). The fourth problem — the model reads untrusted text — remains
+everyone's, and the three layers above exist to make it survivable.