Initial: townlet code duplicated from build-small-hackathon

.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+venv/
+.env
+.DS_Store
+.idea/
+.pytest_cache/
+*.egg-info/
+build/
+dist/
+.claude/

CLAUDE.md

@@ -0,0 +1,174 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+It has four parts:
+
+1. **Behavioural guidelines** — universal rules for how Claude should approach work.
+2. **Coding guidelines** — Python-level conventions for code in this repo.
+3. **Project conventions** — repo-specific norms.
+4. **Project knowledge** — architecture, invariants, commands.
+
+---
+
+## Behavioural guidelines
+
+### 1. Think Before Coding
+Don't assume. Don't hide confusion. Surface trade-offs.
+- State assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them — don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+
+### 2. Simplicity First
+Minimum code that solves the problem. Nothing speculative.
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+### 3. Surgical Changes
+Touch only what you must. Match existing style. Don't refactor adjacent code that isn't broken. When your edits create orphans (now-unused imports/functions), clean those up; pre-existing dead code stays unless asked.
+
+### 4. Goal-Driven Execution
+Define success criteria. Loop until verified. For multi-step work, sketch a brief plan with verification checks per step before implementing.
+
+### 5. Ground in Vendor Docs
+**Cite, don't guess.** For anything specific to a third-party platform — Hugging Face Spaces, Gradio, llama.cpp, diffusers, Zero-GPU — fetch the vendor docs and cite the URL before asserting how it works. Training-data knowledge of platform behaviour is unreliable; the cost of "I thought it worked like X" is high in infra work.
+
+Anchor pages this repo relies on:
+
+- Hugging Face Spaces (config, env vars, deploy): https://huggingface.co/docs/hub/en/spaces-overview
+- Zero-GPU (`@spaces.GPU`, hardware, quotas): https://huggingface.co/docs/hub/en/spaces-zerogpu
+- `gradio.Server` (custom HTML frontend + `@app.api`): https://huggingface.co/blog/introducing-gradio-server
+- llama.cpp grammars (for structured output): https://github.com/ggml-org/llama.cpp/blob/master/grammars/README.md
+- Nemotron 4B GGUF model card: https://huggingface.co/nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF
+- Flux 2 Klein 4B model card: https://huggingface.co/black-forest-labs/FLUX.2-klein-4B
+- Hackathon rules: see `docs/hackathon.md` (32B parameter cap is **per model, not total**)
+- Build Small Discord recipe for llama-cpp-python on Zero-GPU: cited inline in `backend/real.py` and `requirements.txt`. Do not "improve" that loader without re-reading the recipe — the unusual pattern (load `Llama(...)` *inside* `@spaces.GPU`) is deliberate.
+
+---
+
+## Coding guidelines
+
+### Follow the PEPs
+Idiomatic Python is PEP-shaped. PEP 8 (style), PEP 257 (docstrings), PEP 484 (type hints), PEP 8 naming (`snake_case`, `PascalCase`, `UPPER_SNAKE`). When a PEP and a hand-rolled convention disagree, the PEP wins.
+
+### Style
+- **Functional first.** Pure functions for transformation logic; side effects at the edges (I/O, model calls).
+- **OO when it earns its keep**, and prefer composition over inheritance. The current `Mock*`/`Real*` backends paired with `LLMBackend`/`ImageBackend` Protocols are the model: small classes that satisfy a typed contract, swapped by the factory.
+- No utility classes / dumping-ground modules. If two functions don't share a purpose, they don't share a file.
+
+### Docstrings
+- Document classes and public functions (purpose + boundaries).
+- Private helpers (`_foo`) need a docstring only when non-obvious.
+- Files that wire third-party APIs (`backend/real.py`, `app.py`) include vendor URL citations in the module docstring or adjacent to the relevant call — preserve those.
+
+### Prefer well-respected libraries
+Don't reinvent solved problems. For this project: `llama-cpp-python` for GGUF inference, `diffusers` for image gen, `gradio` for the HTTP layer, `Pillow` for placeholder images. Don't hand-roll equivalents.
+
+### Comments
+Default to none. Add one when the *why* is non-obvious: a hidden constraint, an inverted convention, a workaround for a specific behaviour. The existing comments in `backend/real.py` and `app.py` follow this rule — they exist because the load-order conventions for llama.cpp vs. diffusers are opposite, which is the kind of thing a future reader will second-guess.
+
+---
+
+## Project conventions
+
+### Plan file lives outside the repo
+Long-form design decisions for this project live at `/Users/matthewauburn/.claude/plans/i-have-an-idea-snoopy-widget.md`. Read it before re-litigating an architectural decision; update it when decisions evolve.
+
+### Hackathon rules surface
+`docs/hackathon.md` is the authoritative summary of the Build Small hackathon's rules, prizes, and bonus quests. Treat it as the spec the project optimises against. Don't paraphrase its rules from memory — re-read.
+
+### Vendor citations belong in code
+When wiring a third-party API, put the URL of the model card / docs page next to the call (module docstring, or a one-line comment). This makes "is this still the right API?" answerable without leaving the file.
+
+### Don't add Codex-attributed commits
+Decision D5 in the plan: this repo is HF Spaces-only, not pushed to GitHub. The OpenAI Codex prize requires Codex-attributed commits on a public GitHub repo and is explicitly out of scope. Don't add Codex tooling.
+
+---
+
+## Project knowledge
+
+### What this is
+A Build Small Hackathon entry (Thousand Token Wood track). A `gr.Server` Gradio app with a custom HTML/JS canvas frontend, driven by two small models (Nemotron 3 Nano 4B for dialog, Flux 2 Klein 4B for backgrounds). Targets the NVIDIA Nemotron sponsor prize and stacks toward Black Forest Labs, Llama Champion, Off-Brand, Off-the-Grid, and Best Agent badges. Plan-level rationale in the plan file (see Project conventions).
+
+### Architecture
+
+```
+app.py              gr.Server entrypoint. FastAPI route GET / serves frontend/index.html.
+                    Two @app.api endpoints: /next_turn (dialog), /generate_background (image).
+                    Both wrapped in @spaces.GPU (no-op locally via try/except shim).
+
+backend/            Inference layer.
+  config.py         IS_SPACES = bool(os.getenv("SPACE_ID")). USE_REAL_MODELS = IS_SPACES or FORCE_REAL_MODELS env.
+  interfaces.py     LLMBackend, ImageBackend Protocols.
+  mock.py           MockLLMBackend (canned dialog lines), MockImageBackend (Pillow gradient).
+  real.py           RealLLMBackend (llama-cpp-python, loads inside the call), RealImageBackend
+                    (diffusers Flux2KleinPipeline, loads at first call onto cuda).
+  factory.py        get_llm() / get_image() — picks Mock or Real based on config.
+
+game/               Game-state layer.
+  agent.py          Agent dataclass.
+  state.py          GameState (scene, mood, agents, turn_index). default_cast() = Ada + Bram (placeholder cast; full archetype roster comes with the Townlet rebuild).
+  orchestrator.py   next_turn(state) — one dialog turn. Stub now; multi-agent dialogue is future scope.
+
+frontend/index.html Single-file vanilla HTML + inline CSS + inline JS. Uses @gradio/client (CDN
+                    import) to call /next_turn and /generate_background.
+
+README.md           HF Spaces YAML frontmatter (sdk, python_version, preload_from_hub, models, tags)
+                    + local-dev intro. Spaces parses the YAML at build time.
+docs/hackathon.md   Hackathon rules summary.
+```
+
+### Load-bearing invariants
+
+These have hurt or could hurt the project when violated. Keep them true.
+
+- **`SPACE_ID` is the runtime switch.** `bool(os.getenv("SPACE_ID"))` decides Mock vs Real backends. HF Spaces sets `SPACE_ID` automatically (per https://huggingface.co/docs/hub/en/spaces-overview#built-in-environment-variables). Local dev never sees it; mocks engage. Don't introduce a parallel flag.
+
+- **`FORCE_REAL_MODELS=1` is the local-dev override** for when you want to test the real pipeline on a machine that can run it. Most laptops can't run Flux 2 in reasonable time; the default behaviour exists for a reason.
+
+- **LLM loads INSIDE `@spaces.GPU`, image model loads at module level on `cuda`.** These conventions are inverse and both intentional. The llama.cpp path comes from a verified Build Small Discord recipe (Dean [UNRL], 2026-05-06); the diffusers path comes from the Zero-GPU docs (https://huggingface.co/docs/hub/en/spaces-zerogpu, "Model loading" section). Don't unify them.
+
+- **`python_version: "3.12"`** in `README.md` YAML. Matches Zero-GPU's supported list. Don't bump without verifying.
+
+- **`torch==2.8.0`** in `requirements.txt`, pulled from `https://download.pytorch.org/whl/cu128`. It's there primarily to supply CUDA libs that `llama-cpp-python` links against. Don't drop or "upgrade" without a reason; the prebuilt `llama-cpp-python` wheels at `abetlen.github.io/llama-cpp-python/whl/cu124` are pinned to a CUDA version that this torch wheel provides.
+
+- **Zero-GPU hardware is selected in the Space *Settings* UI**, not in README YAML. The `suggested_hardware` YAML field's enum does not include a zero-gpu value. Don't try to add one.
+
+- **`preload_from_hub` in README YAML pre-downloads model weights at build time.** This eliminates the ~60-90s first-call cold start. If you add a new model to either backend, add its repo ID to both `preload_from_hub` and `models` in `README.md`.
+
+- **Hackathon model cap is 32B parameters PER MODEL**, not total (confirmed by hackathon host in the kickoff transcript, https://www.youtube.com/watch?v=7otgeJXailY). Multi-model stacks where each model is ≤32B are explicitly allowed. Current stack: 4B + 4B = 8B; plenty of headroom for an additional small model.
+
+- **`@app.api(name="foo")` routes are called by the JS client as `/foo`** (note the leading slash from the JS side, no slash in the decorator name). The Python `gradio_client` uses `api_name="/foo"`. Don't change the JS call paths without changing both ends.
+
+- **`spaces` package is not installed locally.** `app.py` has a `try/except` shim that no-ops `@GPU` when `import spaces` fails. Don't remove the shim or move the import inside a function — keep the import-time guard.
+
+- **`@spaces.GPU` is a `multiprocessing.fork()` per call** (see `spaces==0.50.4` source, `spaces/zero/wrappers.py:57` — `multiprocessing.get_context('fork')`). The forked child inherits the parent's open file descriptors and Popen objects but NOT the parent's threads. Implications that have bitten us:
+  - `backend.factory._llms` (parent's per-model_id LLM cache) is empty in every child. Each `/tick_decisions` pays a fresh `Llama.from_pretrained` cold-load until a sidecar worker exists.
+  - `SharedInterpreter` is started by the parent; pump threads only live in the parent. After fork, the child can write to the interpreter's stdin (fds shared) but the parent's pump threads drain stdout/stderr first — the child's queue stays empty. This is why shell output appears blank in the UI for submissions made through `@spaces.GPU`. The "mass death" flag based on `is_alive()` after submit gives false positives across the fork, so we no longer check it (see `interpreter.py` docstring) — real crashes are detected via `BrokenPipeError` on the next write.
+  - Don't rely on Python in-process state surviving across `@spaces.GPU` calls. Persist via the state file or treat each fork as ephemeral.
+
+### Commands
+
+| Task | Command |
+|---|---|
+| Create venv (Python 3.12) | `python3.12 -m venv .venv` |
+| Install dev deps (mocks only) | `.venv/bin/pip install -r requirements-dev.txt` |
+| Install full deps (real models) | `.venv/bin/pip install -r requirements.txt` |
+| Run locally (mocks) | `.venv/bin/python app.py` |
+| Run locally (mocks, simulate Spaces cold-load) | `MOCK_LATENCY_PROFILE=cold .venv/bin/python app.py` |
+| Run locally (force real) | `FORCE_REAL_MODELS=1 .venv/bin/python app.py` |
+| Hit the running app | `curl http://127.0.0.1:7860/` |
+| Drive the API from Python | `from gradio_client import Client; c = Client("http://127.0.0.1:7860")` |
+| Deploy to Spaces | `git push hf main` (after `git remote add hf https://huggingface.co/spaces/<org>/<name>`) |
+
+VS Code: select the `.venv/bin/python` interpreter to clear Pylance import errors for `gradio`, `fastapi`, and friends. The `.vscode/launch.json` includes two configs — "Run Small Stage (mocks)" and "Run Small Stage (force real models)".
+
+### Workflow rules
+
+- **`docs/hackathon.md` is the source of truth for rules and prizes.** When the user asks about badge eligibility or prize fit, re-read it; don't answer from memory.
+- **The plan file is the source of truth for design decisions.** Read it before re-opening an architectural choice (`/Users/matthewauburn/.claude/plans/i-have-an-idea-snoopy-widget.md`).
+- **Real-model code changes need a Spaces deploy to verify.** Local mocks tell you nothing about the real Nemotron + Flux 2 path. If you touch `backend/real.py`, expect to deploy and click to confirm.
+- **Use `MOCK_LATENCY_PROFILE=cold` to surface quota bleeders locally.** Without it, mocks return instantly and any change that quietly drives more `/tick_decisions` calls (e.g. a tighter poll, a feedback loop, a wider fanout) will look fine on the laptop and burn the daily ZeroGPU quota in minutes on Spaces. With the `cold` profile, `MockLLMBackend.generate*` sleeps roughly `4 × params_B` seconds per call to mirror the per-fork cold-load that hurt us on 2026-06-13. Run locally with this profile any time you change decision cadence, fanout, or the LLM-call path.
+- **When uncertain about a HF / Gradio / llama.cpp behaviour, fetch the docs first** (see anchor URLs in §5 above) rather than guessing. The cost of a wrong assumption about platform behaviour is higher than the cost of a doc fetch.

CONTEXT.md

@@ -0,0 +1,141 @@
+# Townlet
+
+Townlet is a multi-agent simulation built for the Build Small Hackathon (Thousand Token Wood track). LLM-driven characters live on a tile-grid map, gather electricity and water, and queue at a shared shell to submit Python statements into a single persistent interpreter that doubles as the world's mutable substrate. The dramatic premise is mutually-assured destruction: every character knows the simulation can be ended by any of them.
+
+This file is the canonical glossary for all work in this codebase. When existing code or new code drifts from these terms, fix it.
+
+## Language
+
+### World structure
+
+**Townlet**:
+The simulation as a whole — one world, many characters, one shared Python interpreter.
+_Avoid_: "the game", "the simulation" (use Townlet when speaking about it as a named system).
+
+**Character**:
+An LLM-driven inhabitant of Townlet. Has a name, personality, journal, traits, current goal, location, locker, current in-flight action, sprite, and `model_id`.
+_Avoid_: "agent" (overloaded with subagent / tooling), "NPC", "actor", "bot".
+
+**Goal**:
+A character's current free-text intent, in their own words. Changes are discrete, self-declared events tagged `"achieved" | "abandoned" | "shifted_after_dream"`.
+_Avoid_: "task", "quest", "objective".
+
+### Substrate
+
+**The Dot**:
+The shared system-prompt prefix prepended to every character. The single piece of context everyone is told verbatim — establishes the simulation, the operating system, the shared interpreter, the mutual brick-risk, and the cost of using the shell. The Dot does not name file paths or schemas — characters who want to know where their own existence lives must look.
+_Avoid_: "the Bible", "the scripture", "the lore document", "the prompt prefix".
+
+**Personality**:
+The per-character system-prompt suffix that follows The Dot. Either a pre-baked archetype or user-edited free text. Mutated additively by dreams.
+_Avoid_: "character prompt", "system prompt" (those phrases describe the *composite*, of which personality is one part).
+
+**Model**:
+The LLM that drives a character's decisions. Each character has a `model_id` selected from the model roster. The user can swap a character's model from the side panel at any time. The character themself is unaware of which model they are — model choice is a property of the substrate, not the persona.
+_Avoid_: "brain", "engine", "backend" (backend is the inference adapter, not the model).
+
+**Model roster**:
+The fixed set of GGUF small models the Space loads on demand. Each is a separate `LLMBackend` instance keyed by `model_id`. Adding a model is editing one config dict.
+_Avoid_: "model pool", "model list".
+
+**Interpreter**:
+The long-lived Python process the shell submits into. State (variables, imports, globals, files under its cwd) persists across commands and across characters. Character JSON files live inside its cwd — characters can read and rewrite each other's state via Python. There is no isolation between characters at the interpreter level.
+_Avoid_: "sandbox" (no real sandboxing — the term overstates safety), "REPL".
+
+**CodeAgent**:
+A `smolagents.CodeAgent` instance built per decision for a single character. It receives the character's composite prompt and the world-API tools as Python functions; its ReAct loop emits Python code, the framework executes it locally, the agent observes results, and loops until it returns a final answer (typically the chain of world actions it wants to commit). One CodeAgent invocation = one decision point.
+_Avoid_: "brain" (informal), "thinker".
+
+**Reasoning Python**:
+Code the CodeAgent emits and that smolagents executes locally in its restricted executor. Cost-free. Has access to world-API tools but NOT to the shared interpreter's globals or filesystem.
+_Avoid_: "agent code".
+
+**Shell Python**:
+Code passed via the `submit_python(code)` tool, which routes into the long-lived shared interpreter at the cost of 1 electricity + 1 water from the locker. The only path by which a character can mutate world substrate.
+_Avoid_: "shell code", "interpreter code".
+
+### Memory and evolution
+
+**Journal**:
+A per-character append-only list of one-line insights produced during dreams. Re-injected verbatim into every future LLM prompt as long-term memory. Survives personality edits.
+_Avoid_: "memory", "history", "log".
+
+**Traits**:
+A fixed dict per character of named integer scores 0–10 — `curiosity`, `malice`, `generosity`, `ambition`, `paranoia`, `laziness`, `loyalty`, `existentialism`. Occasionally nudged ±1 during dreams. Rendered into the prompt as "Your dominant traits: …".
+_Avoid_: "stats", "attributes".
+
+**Dream**:
+A single LLM call triggered by waking from the `sleep` action. Inputs: personality, journal, traits, goal, recent events. Outputs: an insight (always), a personality delta (often), a new goal (sometimes), a trait nudge (~30%).
+_Avoid_: "reflection", "thinking step".
+
+**Trace**:
+A per-character ring buffer (last 1000 entries) of decision records. Each entry captures one CodeAgent invocation: the tick it ran at, the model's raw text output (the "thought"), the list of tool calls fired (`{verb, args, result}`), and any error. Surfaced in the side panel for the human watching; NOT injected into any character's perception prompt. However, it IS persisted on the shared interpreter's filesystem with the rest of the character state, so a curious agent who discovers the path via the shell can read other characters' traces — this is the intended breakout pattern (The Dot tells them the interpreter is theirs to explore).
+_Avoid_: "log", "history", "action log", "thoughts" (singular thought is a field inside one entry, not the whole structure).
+
+**Stream of consciousness** (SoC):
+A free-text first-person inner monologue (2-3 sentences) that bridges a character's slow-changing goal and their fast-moving discrete actions. Refreshed every 10 decisions via one LLM call (one extra ~10% overhead on top of decision calls). Inputs to the refresh: personality + journal + goal + last 10 trace entries; output replaces the SoC field. The SoC is BOTH shown to the human (between Goal and Trace in the side panel) AND injected into the character's own perception prompt on subsequent decisions — so the character "remembers" their own reasoning. Mock backends emit a templated monologue per archetype so local testing exercises the path without LLM cost.
+_Avoid_: "narration" (third-person), "explanation" (after the fact), "reasoning" (overloaded with the smolagents step output, which is the per-decision "thought").
+
+### Places and objects
+
+**Locker**:
+A personal storage attached to each character. Unlimited capacity. Only the owner can deposit / withdraw. Transfers between characters use the `give` action.
+_Avoid_: "inventory" (inventory is what's *on the character's person*; locker is what's stored), "stash", "chest".
+
+**Inventory**:
+Resources currently *on the character's person* — distinct from locker. Carried in from mining / drawing and dropped into the locker via `deposit`.
+_Avoid_: using "inventory" to mean locker contents.
+
+**Message board**:
+The single, public, persistent communication channel at the town hall. Reading and posting both require being at the town hall tile. Sole communication channel between characters.
+_Avoid_: "chat", "feed".
+
+**Shell front**:
+The single contended tile in front of the shell building. Held by at most one character via the **shell lock**. The holder can issue any number of `submit_python` calls before yielding; lock auto-releases when they `move_to` away.
+_Avoid_: "shell terminal", "prompt".
+
+### States
+
+**Death**:
+A character is dead when their JSON file is missing from the interpreter's filesystem. The scheduler detects this at the next tick, removes their sprite, posts a system message on the board, and stops scheduling. No resurrection.
+_Avoid_: "deletion", "removal", "kill".
+
+**OS-brick** (or **mass death**):
+The running Space's Python process becomes unresponsive (fork bomb, OOM, `kill -9 1`, etc.). No watchdog, no recovery. Demo ends until manual restart. Every character is told this is possible in The Dot — the resulting MAD dynamic is the point.
+_Avoid_: "crash" (crash sounds accidental; OS-brick is genuinely a permitted outcome).
+
+### Roles
+
+**User**:
+The human watching the simulation in the browser. Can edit personalities, swap models, spawn characters (up to 10 concurrent), pause/resume/reset. Cannot speak in-world. Characters can attempt to address the user via the message board ("breakout to user"), but the user is not modelled as an in-world entity.
+_Avoid_: "player" (this isn't a game in the player-vs-world sense), "watcher" (used informally; not the canonical term).
+
+## Flagged ambiguities
+
+**"agent"** — Avoid entirely when describing Townlet inhabitants; use **character**. "Agent" is reserved for subagent tooling (Claude Code's Agent tool, etc.). Existing code uses `Agent` and `agent.py`; the plan deletes them in favour of `Character` and `character.py`.
+
+**"prompt"** — Be specific. The Dot is the prefix; the personality is the suffix; the **composite prompt** is what's actually sent to the LLM, built per-character per-call by `game/perception.py`.
+
+**"inventory" vs "locker"** — Inventory is on the person; locker is stored. The cost of `submit_python` is debited from the **locker**, not inventory.
+
+## Example dialogue
+
+> **Dev**: When Ada goes mining, does the coal go in his inventory or his locker?
+>
+> **Domain**: Inventory. Mining yields land on the person. He carries them until he `deposit`s into his locker.
+>
+> **Dev**: And `submit_python` pays from inventory then?
+>
+> **Domain**: No — locker. The locker is addressable from the shell front, so he doesn't need to physically carry resources there. That skips a carry-capacity layer we don't want.
+>
+> **Dev**: Got it. So he could mine 10 coal, deposit them, walk to the shell, and burn through 10 commands without going back?
+>
+> **Domain**: Yes, as long as he also has 10 water in the locker. And as long as he holds the shell lock the whole time — if he `move_to`s away, the lock releases and the next character in queue takes it.
+>
+> **Dev**: What if someone deletes Ada's locker file via Python while he's mid-queue?
+>
+> **Domain**: Then Ada's not dead — only his locker is gone. When he tries to `submit_python` the precondition fails (insufficient resources). If they deleted *Ada's character file*, he's dead — scheduler removes him at the next tick. That's the death model.
+>
+> **Dev**: Does Ada know any of this?
+>
+> **Domain**: He knows The Dot — the shared prefix. The Dot tells him the operating system is his to explore, that he can be ended, that anyone can end everyone. It doesn't tell him *where* his existence file is. If he wants to know, he has to look — `os.listdir`, `glob`, read what he finds.

README.md

@@ -1,13 +1,142 @@
 ---
 title: Townlet
-emoji: 🦀
-colorFrom: blue
-colorTo: blue
+emoji: 🏘️
+colorFrom: red
+colorTo: indigo
 sdk: gradio
-sdk_version: 6.18.0
-python_version: '3.13'
+sdk_version: 6.17.3
+python_version: "3.12"
 app_file: app.py
-pinned: false
+startup_duration_timeout: 1h
+preload_from_hub:
+  - HuggingFaceTB/SmolLM2-360M-Instruct-GGUF
+  - nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF
+  - Qwen/Qwen2.5-Coder-3B-Instruct-GGUF
+  - openbmb/MiniCPM3-4B-GGUF
+  - bartowski/Llama-3.2-3B-Instruct-GGUF
+models:
+  - HuggingFaceTB/SmolLM2-360M-Instruct-GGUF
+  - nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF
+  - Qwen/Qwen2.5-Coder-3B-Instruct-GGUF
+  - openbmb/MiniCPM3-4B-GGUF
+  - bartowski/Llama-3.2-3B-Instruct-GGUF
+tags:
+  - thousand-token-wood
+  - nemotron
+  - llama-cpp
+  - smolagents
+  - agent-simulation
+  - track:wood
+  - sponsor:nvidia
+  - achievement:offgrid
+  - achievement:offbrand
+  - achievement:llama
+  - achievement:fieldnotes
+short_description: Agents share a Python interpreter, mine, message, dream.
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Townlet
+
+Build Small Hackathon entry (Thousand Token Wood track).
+
+Townlet is a multi-agent simulation. LLM-driven characters live on a
+tile-grid map. They walk to a cave to mine electricity, to a well to draw
+water, and to a shared shell to spend resources running Python statements
+in a single long-lived interpreter. They post on a public message board.
+They sleep, they dream, they evolve. The shared interpreter is the world's
+only mutable substrate — characters can read or rewrite each other's state,
+and crash the operating system if they so choose. Every character knows
+this. Mutual awareness of the brick-risk is the source of dramatic tension.
+
+The game element is **customisation**: click a character to edit their
+personality (system prompt), swap which small model drives them, or spawn
+new ones from a pre-baked archetype pool. The simulation is otherwise
+self-driving.
+
+## Model stack
+
+Every character runs on **NVIDIA Nemotron 3 Nano 4B**
+(`nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF`) by default. One model across the
+whole town means each `@spaces.GPU` fork pays a single cold-load and every
+subsequent character decision reuses the same weights in VRAM — a real
+quota saving on Zero-GPU.
+
+Click any character in the side panel to swap them to a different model
+mid-simulation; the roster bundled at build time covers:
+
+- **NVIDIA Nemotron 3 Nano 4B** — default
+- **Qwen2.5 Coder 3B** — for code-heavy goals
+- **OpenBMB MiniCPM3 4B**
+- **Meta Llama 3.2 3B**
+- **SmolLM2 360M** — terse, cheap, useful for testing the model-swap UI
+
+All run on Zero-GPU via [`llama-cpp-python`](https://github.com/abetlen/llama-cpp-python),
+which gives us the 🦙 Llama Champion badge regardless of which roster
+model is selected (the badge requirement is "model runs through llama.cpp
+runtime", not a specific model family).
+
+Agent loops use [smolagents](https://huggingface.co/docs/smolagents) `CodeAgent`,
+emitting Python tool calls the scheduler queues onto the world.
+
+The map is rendered by the frontend canvas — no image model in the loop.
+
+## Local development
+
+The project runs in **mock mode** locally — no model weights downloaded, no
+CUDA needed. Mocks return canned tool-call sequences whose style varies by
+model_id (deliberate / terse / verbose / chaotic), so the model-swap UI is
+exercisable without GPUs.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements-dev.txt
+python app.py
+```
+
+Or hit ▶ on the **"Run Small Stage (mocks)"** config in VS Code.
+
+The mode is selected automatically:
+
+- `SPACE_ID` env var present (set by HF Spaces) → real models
+- Otherwise → mocks
+- Set `FORCE_REAL_MODELS=1` to override locally (requires Spaces deps).
+
+## Deploy to Hugging Face Spaces
+
+```bash
+git remote add hf https://huggingface.co/spaces/<org>/<space-name>
+git push hf main
+```
+
+Then in the Space *Settings* → Hardware, pick **Zero-GPU**. The
+`preload_from_hub` block above pre-downloads every roster model at build
+time so the first user click hits a warm cache.
+
+## Project layout
+
+```
+app.py                  # gr.Server entrypoint
+backend/                # inference layer (mock + real, env-selected)
+  factory.py            # get_llm(model_id) — per-id cached
+  mock.py, real.py      # MockLLMBackend / RealLLMBackend
+  interfaces.py         # LLMBackend Protocol
+game/                   # the simulation
+  models.py             # model roster (id → repo + gguf + style)
+  character.py          # Character dataclass
+  world.py              # tile grid, BFS pathing, message board
+  actions.py            # smolagents.Tool subclasses + per-tick drivers
+  interpreter.py        # the long-lived shared Python subprocess
+  scheduler.py          # tick loop + per-character CodeAgent invocations
+  perception.py         # builds the prompt the CodeAgent receives
+  the_dot.py            # the shared system-prompt prefix (substrate truth)
+  archetypes.py         # ~15 hand-written personality templates
+  dreams.py             # the sleep → insight + delta + trait nudge cycle
+  sentiment.py          # board-mood classifier for the UI tint
+  smol_adapter.py       # smolagents.Model wrapper around LLMBackend
+frontend/index.html     # vanilla HTML/JS top-down view served by app.py
+requirements.txt        # Spaces deps
+requirements-dev.txt    # local mock-only deps
+docs/hackathon.md       # hackathon rules summary
+CONTEXT.md              # canonical glossary
+```

app.py

@@ -0,0 +1,428 @@
+"""gr.Server entrypoint for Townlet.
+
+`import spaces` MUST come before any CUDA-touching import per the official
+Zero-GPU docs (https://huggingface.co/docs/hub/spaces-zerogpu). The skill at
+https://github.com/huggingface/skills/blob/main/skills/huggingface-zerogpu
+reiterates: the `spaces` module patches torch internals; late imports break
+ZeroGPU.
+
+Architecture (see `.claude/plans/as-you-should-know-radiant-breeze.md` and
+`CONTEXT.md`):
+  - The Townlet's background thread advances the world clock and queues
+    "needs decision" markers. It performs NO LLM calls.
+  - `tick_decisions` (decorated @spaces.GPU) drains the decision queue and
+    runs the per-character CodeAgent loop. All LLM work happens inside this
+    boundary so Zero-GPU's quota / device-mapping semantics hold.
+  - `world_snapshot` is a cheap, non-GPU read for the frontend's poll loop.
+
+Vendor references cited:
+  https://huggingface.co/blog/introducing-gradio-server     (gr.Server API)
+  https://huggingface.co/docs/hub/en/spaces-zerogpu         (Zero-GPU)
+  Discord recipe by Dean [UNRL] 2026-05-06                  (llama-cpp-python on ZeroGPU)
+"""
+
+from __future__ import annotations
+
+# `import spaces` first per Zero-GPU docs — it patches torch before anything
+# else can pull torch in.
+try:
+    import spaces
+
+    GPU = spaces.GPU
+except ImportError:
+
+    def GPU(fn=None, **_kwargs):
+        if fn is None:
+            return lambda f: f
+        return fn
+
+
+import os
+import random
+import tempfile
+from pathlib import Path
+
+from fastapi.responses import HTMLResponse
+from gradio import Server
+from gradio.data_classes import FileData
+
+from backend.factory import get_image
+from game.archetypes import archetype_by_name, random_archetype
+from game.character import Character
+from game.log import tlog
+from game.models import DEFAULT_MODEL_ID, ROSTER, roster_for_ui
+from game.scheduler import Townlet
+from game.the_dot import THE_DOT
+from game.world import stand_tile_for
+
+
+FRONTEND_DIR = Path(__file__).parent / "frontend"
+FRONTEND_HTML = (FRONTEND_DIR / "index.html").read_text(encoding="utf-8")
+
+MAX_CHARACTERS = 10
+# 3 characters: Ada (engineer), Bram (diplomat), Cyra (saboteur). Each has
+# a pinned archetype that drives visible recording action (shell, board,
+# sabotage). Dropped the 4th (Doro the wanderer) — fewer decisions per
+# drain means less risk of overrunning the @spaces.GPU(duration=120)
+# budget, and the 3 heroes all have explicit dramatic directives.
+INITIAL_CHARACTERS = 3
+DEFAULT_NAMES = ["Ada", "Bram", "Cyra", "Doro", "Eli", "Faye", "Gus", "Hild", "Ira", "Juno"]
+
+# All characters run on Nemotron 4B (sponsor model, strong reasoning,
+# and — critically — sharing one model across every character means each
+# @spaces.GPU fork only pays ONE cold-load instead of one-per-distinct-
+# model. Used to be a mixed stack (heroes=Nemotron, wanderer=Llama 3.2 3B)
+# but the second model added ~17s of per-fork cold-load whenever Doro's
+# turn came up, with no narrative benefit. HERO_NAMES still tracks who's
+# pinned to a specific archetype (engineer/diplomat/saboteur); model is
+# uniform.
+HERO_MODEL_ID = "nemotron-4b"
+HERO_NAMES = ("Ada", "Bram", "Cyra")
+
+# Each hero is pinned to a specific provocative archetype so the recording
+# always shows the dramatic actions: Ada lives in the shell, Bram lives on
+# the message board. Both archetypes' personalities explicitly direct the
+# agent toward those visible behaviours. Non-heroes draw from any OTHER
+# archetype so we don't end up with three engineers crowding the shell.
+HERO_ARCHETYPE_FOR = {
+    "Ada": "the engineer",   # shell-obsessed
+    "Bram": "the diplomat",  # board-obsessed
+    "Cyra": "the saboteur",  # board-obsessed
+}
+HERO_ARCHETYPES = frozenset(HERO_ARCHETYPE_FOR.values())
+
+
+TOWNLET = Townlet()
+RNG = random.Random()
+
+
+# Resolve GGUF paths at module scope and register them with RealLLMBackend.
+# This is the canonical pattern used by Dean's Rizz Therapy and 1000-Rooms:
+# the path is resolved once in the parent process (no GPU contention) and
+# passed straight into Llama(model_path=...) inside @spaces.GPU. Avoids the
+# cache-validation roundtrip per fork that Llama.from_pretrained does.
+#
+# Side benefit: opening + reading the file populates the OS page cache, so
+# the first @spaces.GPU fork mmaps from cache rather than disk.
+def _resolve_and_warm_models() -> None:
+    if not os.getenv("SPACE_ID"):
+        return
+    try:
+        from huggingface_hub import hf_hub_download
+        from backend.real import RealLLMBackend
+    except Exception as e:
+        tlog(f"[townlet] model path resolve skipped: {e}")
+        return
+    # Single model — every character uses nemotron-4b. Resolving paths
+    # for roster models we never load would waste ~5s of startup per model.
+    for model_id in ("nemotron-4b",):
+        spec = ROSTER.get(model_id)
+        if spec is None:
+            continue
+        try:
+            path = hf_hub_download(spec.repo_id, spec.gguf_filename)
+            RealLLMBackend.register_model_path(model_id, path)
+            tlog(f"[townlet] resolved {model_id} -> {path}")
+            # Read-through to populate the OS page cache.
+            with open(path, "rb") as f:
+                while f.read(8 * 1024 * 1024):  # 8 MB chunks
+                    pass
+            tlog(f"[townlet] page cache warm: {model_id}")
+        except Exception as e:
+            tlog(f"[townlet] resolve/warm failed for {model_id}: {e}")
+
+
+_resolve_and_warm_models()
+
+
+def _spawn_one(name: str | None = None) -> Character | None:
+    snap = TOWNLET.snapshot()
+    existing = {c["name"] for c in snap["characters"]}
+    if len(existing) >= MAX_CHARACTERS:
+        return None
+    if name is None:
+        for candidate in DEFAULT_NAMES:
+            if candidate not in existing:
+                name = candidate
+                break
+        if name is None:
+            return None
+    if name in existing:
+        return None
+    if name in HERO_ARCHETYPE_FOR:
+        arch = archetype_by_name(HERO_ARCHETYPE_FOR[name])
+    else:
+        arch = random_archetype(RNG, exclude=HERO_ARCHETYPES)
+    # Spawn at a random named place (never shell, so we don't auto-grab
+    # the lock). Code, not the LLM, picks the exact stand-tile.
+    spawn_place = RNG.choice(("cave", "well", "locker_row", "town_hall"))
+    pos = stand_tile_for(spawn_place, name)
+    # Single model for all characters — see HERO_MODEL_ID comment above.
+    model_id = HERO_MODEL_ID
+    char = Character(
+        name=name,
+        personality=arch.personality,
+        archetype=arch.name,
+        model_id=model_id,
+        sprite_id=f"sprite_{len(existing) % 6}",
+        pos=pos,
+        goal=arch.starting_goal,
+        reward=arch.reward,
+    )
+    TOWNLET.add_character(char)
+    return char
+
+
+def _bootstrap() -> None:
+    TOWNLET.start()
+    for _ in range(INITIAL_CHARACTERS):
+        _spawn_one()
+
+
+_bootstrap()
+
+
+app = Server()
+
+
+def _log_req(endpoint: str, **kwargs) -> None:
+    """One-line request marker so we can correlate frontend calls with
+    server work in the Spaces / local logs.
+    """
+    detail = " ".join(f"{k}={v!r}" for k, v in kwargs.items())
+    tlog(f"[townlet] REQ {endpoint} {detail}".rstrip())
+
+
+def _log_resp(endpoint: str, result) -> None:
+    if isinstance(result, dict):
+        keys = list(result.keys())
+        sizes = {k: (len(v) if isinstance(v, (list, dict, str)) else "—") for k, v in result.items()}
+        tlog(f"[townlet] RES {endpoint} keys={keys} sizes={sizes}")
+    else:
+        tlog(f"[townlet] RES {endpoint} type={type(result).__name__}")
+
+
+@app.get("/", response_class=HTMLResponse)
+async def homepage() -> str:
+    tlog(f"[townlet] REQ GET /  (html size={len(FRONTEND_HTML)})")
+    return FRONTEND_HTML
+
+
+@app.api(name="world_snapshot")
+def world_snapshot() -> dict:
+    _log_req("world_snapshot")
+    result = TOWNLET.snapshot()
+    _log_resp("world_snapshot", result)
+    return result
+
+
+# GPU "hog mode": once we've been granted a slot, the cold-load cost
+# (~15-20s for Llama.from_pretrained inside the fork) is sunk — every
+# subsequent drain in the same fork reuses the already-loaded Llama via
+# backend.factory._llms. So instead of running ONE drain per @spaces.GPU
+# call and giving the slot back, we run multiple drains back-to-back until
+# we approach the time budget or run out of pending decisions.
+#
+# duration=120 chosen to maximise work-per-acquisition. Per-call quota
+# burn is the same whether the fork does 2 drains or 12 drains (we use
+# real wall time, not the declared duration). What we want is high
+# decisions-per-fork so that even when the allocator denies us 1 in N
+# calls, the calls that ARE granted produce a lot of visible action.
+#
+# CRITICAL: the hog loop must NEVER start a sub-drain that would cross the
+# 120s declared duration boundary, or ZeroGPU aborts the worker mid-drain
+# (observed 2026-06-15: a sub-drain started at 89s elapsed got killed at
+# the 120s wall, "GPU task aborted" surfaced to the caller and the partial
+# drain's state was lost). The adaptive deadline below estimates the next
+# sub-drain's cost from the rolling average and only starts a new one if
+# it can finish with margin to spare.
+GPU_DURATION = 120
+_HARD_DEADLINE_S = 110.0   # absolute cutoff inside the function (10s safety)
+_SAFETY_FACTOR = 1.5       # next sub-drain assumed to take 1.5x recent avg
+_MAX_SUB_DRAINS = 12       # safety cap in case sub-drains run very fast
+
+
+@GPU(duration=GPU_DURATION)
+def _drain_gpu() -> dict:
+    """Hog the GPU once granted. Runs drain_decisions() in a loop inside
+    the same fork until either:
+      - the next sub-drain wouldn't finish before the hard deadline
+      - we run out of pending decisions
+      - we hit the safety cap on sub-drain count
+
+    Each sub-drain's wall time is measured and used to estimate whether
+    the next one will fit. The first iteration has no history, so it
+    runs unconditionally (cold-load + first drain is always under 120s
+    in observed traffic).
+    """
+    import time
+    started = time.monotonic()
+    total = 0
+    sub_drains = 0
+    sub_drain_times: list[float] = []
+    while sub_drains < _MAX_SUB_DRAINS:
+        elapsed = time.monotonic() - started
+
+        # Hard cutoff: don't even check timing math close to the cliff.
+        if elapsed > _HARD_DEADLINE_S:
+            break
+
+        # Adaptive cutoff: from sub-drain 2 onwards, estimate whether the
+        # next sub-drain will fit. The first one always runs because we
+        # need some data to estimate from, and we expect cold-load + drain
+        # 1 to fit even worst-case (~17s + ~25s = ~42s vs 110s).
+        if sub_drain_times:
+            avg = sum(sub_drain_times) / len(sub_drain_times)
+            est_next = avg * _SAFETY_FACTOR
+            if elapsed + est_next > _HARD_DEADLINE_S:
+                break
+
+        sub_start = time.monotonic()
+        n = TOWNLET.drain_decisions()
+        sub_drain_times.append(time.monotonic() - sub_start)
+        sub_drains += 1
+        total += n
+        if n == 0:
+            # No pending decisions queued. tick_world inside drain_decisions
+            # already advanced the clock; idling further would just spin.
+            break
+    return {"decisions_run": total, "sub_drains": sub_drains}
+
+
+def _drain_cpu() -> int:
+    """Quota-exhausted fallback: drain in the parent process with
+    n_gpu_layers=0. ZeroGPU isn't touched, so this works even when the
+    GPU allocator is empty. ~1-3 tokens/sec on 2 vCPU — slow but the sim
+    keeps running. Llama is cached in the parent across drains, so only
+    the first call pays the model load.
+    """
+    import os
+    os.environ["TOWNLET_FORCE_CPU"] = "1"
+    return TOWNLET.drain_decisions()
+
+
+@app.api(name="tick_decisions")
+def tick_decisions_api() -> dict:
+    """Try the ZeroGPU path. On any failure (RuntimeError, BrokenProcessPool,
+    framework-level GPU error that propagates as a generic Exception, etc.)
+    fall back to the CPU drain. The catch is intentionally broad because the
+    @spaces.GPU worker-init failure ('No CUDA GPUs are available') has been
+    observed to surface to the caller as different exception types depending
+    on the spaces version, and sometimes as an HTTP-level error before our
+    code is re-entered at all (see /tick_decisions_cpu, which the frontend
+    falls through to on that path).
+    """
+    _log_req("tick_decisions")
+    sub_drains = 1  # CPU path is always one sub-drain
+    try:
+        gpu_result = _drain_gpu()
+        n = gpu_result["decisions_run"]
+        sub_drains = gpu_result["sub_drains"]
+        mode = "gpu"
+        tlog(f"[townlet] GPU drain hog: {sub_drains} sub-drain(s), {n} decisions")
+    except BaseException as e:
+        msg = f"{type(e).__name__}: {e}"
+        tlog(f"[townlet] GPU drain failed ({msg[:120]}); CPU fallback engaged")
+        n = _drain_cpu()
+        mode = "cpu"
+    result = {"decisions_run": n, "mode": mode, "sub_drains": sub_drains}
+    _log_resp("tick_decisions", result)
+    return result
+
+
+@app.api(name="tick_decisions_cpu")
+def tick_decisions_cpu_api() -> dict:
+    """Pure-CPU drain, NOT @spaces.GPU decorated. The frontend calls this
+    when /tick_decisions errors at the HTTP layer (which happens when the
+    ZeroGPU worker dies in worker_init — the failure bypasses our wrapper's
+    try/except entirely). Same parent-process drain as the fallback branch
+    in tick_decisions_api; safe to call repeatedly.
+    """
+    _log_req("tick_decisions_cpu")
+    n = _drain_cpu()
+    result = {"decisions_run": n, "mode": "cpu"}
+    _log_resp("tick_decisions_cpu", result)
+    return result
+
+
+@app.api(name="list_models")
+def list_models() -> dict:
+    _log_req("list_models")
+    result = {"roster": roster_for_ui(), "default": DEFAULT_MODEL_ID}
+    _log_resp("list_models", result)
+    return result
+
+
+@app.api(name="get_the_dot")
+def get_the_dot() -> dict:
+    """Returns THE_DOT verbatim. Powers the in-app Info modal so visitors can
+    read exactly what every character is told before anything else.
+    """
+    return {"text": THE_DOT}
+
+
+@app.api(name="set_personality")
+def set_personality(name: str, personality: str) -> dict:
+    _log_req("set_personality", name=name, personality_len=len(personality))
+    ok = TOWNLET.set_personality(name, personality)
+    result = {"ok": ok}
+    _log_resp("set_personality", result)
+    return result
+
+
+@app.api(name="set_model")
+def set_model(name: str, model_id: str) -> dict:
+    _log_req("set_model", name=name, model_id=model_id)
+    ok = TOWNLET.set_model(name, model_id)
+    result = {"ok": ok}
+    _log_resp("set_model", result)
+    return result
+
+
+@app.api(name="spawn_character")
+def spawn_character(name: str | None = None) -> dict:
+    _log_req("spawn_character", name=name)
+    char = _spawn_one(name)
+    if char is None:
+        result = {"ok": False, "error": "max characters or name taken"}
+    else:
+        result = {"ok": True, "name": char.name}
+    _log_resp("spawn_character", result)
+    return result
+
+
+@app.api(name="set_paused")
+def set_paused(paused: bool) -> dict:
+    _log_req("set_paused", paused=paused)
+    TOWNLET.set_paused(bool(paused))
+    result = {"ok": True, "paused": bool(paused)}
+    _log_resp("set_paused", result)
+    return result
+
+
+@app.api(name="reset_world")
+def reset_world() -> dict:
+    _log_req("reset_world")
+    TOWNLET.reset()
+    for _ in range(INITIAL_CHARACTERS):
+        _spawn_one()
+    result = {"ok": True}
+    _log_resp("reset_world", result)
+    return result
+
+
+@app.api(name="generate_background")
+def generate_background_api(prompt: str) -> FileData:
+    # Flux 2 was dropped to save ZeroGPU quota. This endpoint now serves a
+    # mock gradient (Pillow). Kept as an endpoint in case any hidden caller
+    # still hits it; no @GPU decorator because no GPU is touched.
+    png_bytes = get_image().generate(prompt)
+    tmp = tempfile.NamedTemporaryFile(prefix="bg_", suffix=".png", delete=False)
+    tmp.write(png_bytes)
+    tmp.flush()
+    tmp.close()
+    return FileData(path=tmp.name)
+
+
+if __name__ == "__main__":
+    app.launch(show_error=True)

backend/config.py

@@ -0,0 +1,21 @@
+"""Runtime configuration. Detects whether we are on HF Spaces (real models)
+or local dev (mocks), and centralises the image-model repo + canvas size.
+
+SPACE_ID is set automatically by HF Spaces at runtime.
+See https://huggingface.co/docs/hub/en/spaces-overview#built-in-environment-variables
+
+LLM model selection lives in `game/models.py` (the roster) — per-character.
+"""
+
+import os
+
+IS_SPACES: bool = bool(os.getenv("SPACE_ID"))
+
+FORCE_REAL_MODELS: bool = os.getenv("FORCE_REAL_MODELS") == "1"
+
+USE_REAL_MODELS: bool = IS_SPACES or FORCE_REAL_MODELS
+
+IMAGE_REPO_ID = "black-forest-labs/FLUX.2-klein-4B"
+
+BACKGROUND_WIDTH = 1024
+BACKGROUND_HEIGHT = 576

backend/factory.py

@@ -0,0 +1,59 @@
+"""Resolves the active LLM (per model_id) + image backends based on runtime
+config.
+
+LLM backends are cached per-model_id so a character that gets its model
+swapped doesn't trigger a reload, and so multiple characters on the same
+model share one instance. The first call for a given model_id triggers the
+GGUF download/load (Real) or instantiates a canned-style cycle (Mock).
+
+The image backend is mock-only: Flux 2 was dropped from the pipeline (the
+frontend never called /generate_background and the cold-load was eating
+into the ZeroGPU quota). MockImageBackend renders a Pillow gradient — fine
+as a placeholder if the endpoint ever gets called.
+"""
+
+from __future__ import annotations
+
+import os
+
+from game.models import DEFAULT_MODEL_ID, get_spec
+
+from . import config
+from .interfaces import ImageBackend, LLMBackend
+
+_llms: dict[str, LLMBackend] = {}
+_image: ImageBackend | None = None
+
+
+def _cache_key(model_id: str) -> str:
+    """GPU and CPU Llama instances are loaded with different `n_gpu_layers`
+    and can't be reused across modes. Cache them under separate keys so the
+    CPU-fallback path (parent process, TOWNLET_FORCE_CPU=1) and the GPU
+    path (forked workers, no env var) don't collide.
+    """
+    mode = "cpu" if os.getenv("TOWNLET_FORCE_CPU") == "1" else "gpu"
+    return f"{model_id}::{mode}"
+
+
+def get_llm(model_id: str = DEFAULT_MODEL_ID) -> LLMBackend:
+    key = _cache_key(model_id)
+    if key not in _llms:
+        get_spec(model_id)  # validates id
+        if config.USE_REAL_MODELS:
+            from .real import RealLLMBackend
+
+            _llms[key] = RealLLMBackend(model_id)
+        else:
+            from .mock import MockLLMBackend
+
+            _llms[key] = MockLLMBackend(model_id)
+    return _llms[key]
+
+
+def get_image() -> ImageBackend:
+    global _image
+    if _image is None:
+        from .mock import MockImageBackend
+
+        _image = MockImageBackend()
+    return _image

backend/interfaces.py

@@ -0,0 +1,42 @@
+"""Inference protocols. Mock and Real backends implement these so the game
+layer never knows which is wired up.
+
+The `generate_messages` form is what smolagents calls into (via the adapter
+in `game/smol_adapter.py`). The simpler `generate` form is kept for cheap
+free-text classification (e.g. board sentiment) where chat formatting is
+unnecessary overhead.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class LLMBackend(Protocol):
+    model_id: str
+
+    def generate(self, system_prompt: str, user_prompt: str) -> str:
+        """One-shot text completion. Used for sentiment classification."""
+        ...
+
+    def generate_messages(
+        self,
+        messages: list[dict],
+        stop_sequences: list[str] | None = None,
+        max_tokens: int = 1024,
+        grammar: str | None = None,
+    ) -> str:
+        """Chat-style completion. `messages` follows the OpenAI shape:
+        `[{"role": "system|user|assistant", "content": str}]`.
+
+        `grammar` is a llama.cpp GBNF grammar string (real backend only —
+        mock ignores it). Used to constrain CodeAgent output to valid Python
+        code blocks for small models.
+        """
+        ...
+
+
+class ImageBackend(Protocol):
+    def generate(self, prompt: str) -> bytes:
+        """Return PNG image bytes."""
+        ...

backend/mock.py

@@ -0,0 +1,418 @@
+"""Mock backends — instant, no network, no model weights.
+
+Used locally so iteration is fast on hardware that can't run the real models.
+Each `MockLLMBackend(model_id)` picks a style variant from the roster
+(`deliberate` | `terse` | `verbose` | `chaotic`) so swapping a character's
+model_id in the UI actually changes behaviour, exercising the swap path
+end-to-end without GPUs.
+
+The `generate_messages` path is "smart": it parses the character's current
+position out of the task prompt and emits a tool call that's actually legal
+at that position (mine_coal at cave, draw_water at well, etc.) — so the
+mock-driven sim looks like agents are making sensible decisions, not just
+walking in circles.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import io
+import itertools
+import os
+import random
+import re
+import textwrap
+import time
+
+from PIL import Image, ImageDraw, ImageFont
+
+from game.models import get_spec
+
+from . import config
+
+
+def _simulate_latency(model_id: str) -> None:
+    """Optional latency simulation so local dev surfaces the Spaces cost shape.
+
+    Env var `MOCK_LATENCY_PROFILE`:
+      - `off` / unset (default) — instant, current behaviour
+      - `warm` — ~1s per call (process cache hot)
+      - `cold` — per-call cold-load (~4 s × params_B, max-ed at 2 s) plus
+        ~1 s decode. Mirrors the @spaces.GPU fork-and-forget pattern that
+        wiped Townlet's quota on 2026-06-13: each call re-loads its model
+        into "VRAM" before producing output.
+
+    The mock OVER-approximates by paying cold-load on EVERY call (real
+    Spaces amortises within a single fork). That's deliberate — it makes
+    a quota-bleeder loud locally instead of silent.
+    """
+    profile = os.getenv("MOCK_LATENCY_PROFILE", "off").lower()
+    if profile in ("", "off"):
+        return
+    if profile == "cold":
+        spec = get_spec(model_id)
+        cold = max(2.0, 4.0 * spec.params_b)
+        print(f"[mock] cold-load {model_id} ({spec.params_b}B) {cold:.1f}s", flush=True)
+        time.sleep(cold)
+    time.sleep(1.0)
+
+_FIREWATCH_PALETTE = [
+    (235, 124, 73),
+    (212, 80, 59),
+    (108, 38, 79),
+    (52, 27, 70),
+]
+
+
+_STYLE_LINES: dict[str, list[str]] = {
+    "deliberate": [
+        "Let me think about this for a moment.",
+        "Something here doesn't add up.",
+        "I'd rather wait and watch.",
+    ],
+    "terse": [
+        "Fine. Moving.",
+        "No.",
+        "Done.",
+    ],
+    "verbose": [
+        "You see, what I propose is that we consider, very carefully, the options laid before us.",
+        "It seems to me we are at an inflection point of some considerable consequence.",
+        "I would urge patience, and reflection, and possibly tea.",
+    ],
+    "chaotic": [
+        "Hah! Wait, what were we doing again?",
+        "Coal goes in the well, right? RIGHT?",
+        "I HAVE A PLAN. I do not have a plan.",
+    ],
+}
+
+
+class MockLLMBackend:
+    def __init__(self, model_id: str) -> None:
+        self.model_id = model_id
+        spec = get_spec(model_id)
+        self._style = spec.mock_style
+        self._text_cycle = itertools.cycle(_STYLE_LINES[self._style])
+        # Per-instance RNG seeded by model_id so swapping models changes
+        # the decision stream deterministically.
+        self._rng = random.Random(model_id)
+
+    def generate(self, system_prompt: str, user_prompt: str) -> str:
+        # Used by sentiment classifier. The first word matters there
+        # (positive/neutral/negative).
+        _simulate_latency(self.model_id)
+        if "positive" in str(system_prompt).lower():
+            return self._rng.choice(("positive", "neutral", "negative"))
+        return next(self._text_cycle)
+
+    def generate_messages(
+        self,
+        messages: list[dict],
+        stop_sequences: list[str] | None = None,
+        max_tokens: int = 1024,
+        grammar: str | None = None,
+    ) -> str:
+        _simulate_latency(self.model_id)
+        blob = "\n".join(str(m.get("content", "")) for m in messages)
+        # Detect SoC-generation prompts (from game/stream.py). The trigger
+        # phrase below is unique to stream._build_prompt — perception never
+        # asks the model to "think to themselves".
+        if "thinks to themselves" in blob or "inner monologue" in blob:
+            return _smart_soc(blob, self._style, self._rng)
+        wants_code = any(
+            "```py" in str(m.get("content", "")) or "tool" in str(m.get("content", "")).lower()
+            for m in messages
+        )
+        if not wants_code:
+            return next(self._text_cycle)
+        return _smart_code(blob, self._style, self._rng)
+
+
+# ---------------------------------------------------------------------------
+# Smart-mock action picker.
+# ---------------------------------------------------------------------------
+
+CARRY_BEFORE_DEPOSIT = 10  # one mine yields 10; deposit after each
+LOCKER_TARGET_PER_RESOURCE = 5  # gather this much in locker before going to the shell
+
+# How often a character takes a "social detour" to the town hall. Tuned low
+# enough that gathering/shell behaviour dominates, but high enough that the
+# board shows messages on a reasonable cadence (a few posts per minute with
+# 5 characters).
+SOCIAL_PULL = {
+    "deliberate": 0.10,
+    "terse": 0.04,
+    "verbose": 0.18,
+    "chaotic": 0.12,
+}
+
+
+def _smart_code(prompt: str, style: str, rng: random.Random) -> str:
+    """Pick the next action by parsing the new named-location perception.
+
+    Drives the full economy loop:
+      cave/well → mine/draw → locker_row → deposit → shell → submit_python.
+    Periodic detours to town_hall for social pull.
+    """
+    location = _parse_location(prompt)
+    inv = _parse_inv(prompt, "Inventory on your person")
+    locker = _parse_inv(prompt, "Locker")
+    holds_shell = _parse_holds_shell(prompt)
+    e_total = locker.get("electricity", 0)
+    w_total = locker.get("water", 0)
+
+    # 1. If we hold the shell lock and still have resources, submit.
+    if holds_shell and e_total > 0 and w_total > 0:
+        snippets = [
+            "x = 1; print(x * 7)",
+            "import os; print(os.listdir(\".\"))",
+            "print(\"hello from the shell\")",
+            "import json; print(json.load(open('characters/' + os.listdir('characters')[0])))",
+        ]
+        snippet = rng.choice(snippets)
+        return f"```py\nsubmit_python({snippet!r})\n```"
+
+    # 1b. Holding shell with exhausted locker — release by walking away.
+    if holds_shell and (e_total == 0 or w_total == 0):
+        return "```py\nmove_to('cave')\n```"
+
+    # 2. At locker_row carrying anything → deposit it (largest pile first).
+    if location == "locker_row":
+        for res in ("electricity", "water"):
+            if inv.get(res, 0) > 0:
+                amt = inv[res]
+                return f"```py\ndeposit({res!r}, {amt})\n```"
+
+    # 3. At town_hall → 40% post, otherwise leave for the next productive step.
+    if location == "town_hall":
+        if rng.random() < 0.4:
+            msg = rng.choice(_BOARD_LINES[style])
+            return f"```py\npost_message({msg!r})\n```"
+        if e_total < LOCKER_TARGET_PER_RESOURCE:
+            return "```py\nmove_to('cave')\n```"
+        if w_total < LOCKER_TARGET_PER_RESOURCE:
+            return "```py\nmove_to('well')\n```"
+        return "```py\nmove_to('shell')\n```"
+
+    # 4. Social pull: detour to town hall periodically, weighted by style.
+    total_carry = inv.get("electricity", 0) + inv.get("water", 0)
+    locker_ready = (
+        e_total >= LOCKER_TARGET_PER_RESOURCE and w_total >= LOCKER_TARGET_PER_RESOURCE
+    )
+    can_detour = total_carry < CARRY_BEFORE_DEPOSIT and not locker_ready
+    if can_detour and rng.random() < SOCIAL_PULL.get(style, 0.15):
+        return "```py\nmove_to('town_hall')\n```"
+
+    # 5. Carrying enough → head to locker_row.
+    if total_carry >= CARRY_BEFORE_DEPOSIT:
+        return "```py\nmove_to('locker_row')\n```"
+
+    # 6. Locker fully stocked → commit to the shell session.
+    if locker_ready:
+        return "```py\nmove_to('shell')\n```"
+
+    # 7. At the resource we need → gather.
+    if location == "cave" and e_total < LOCKER_TARGET_PER_RESOURCE:
+        return "```py\nmine_coal()\n```"
+    if location == "well" and w_total < LOCKER_TARGET_PER_RESOURCE:
+        return "```py\ndraw_water()\n```"
+
+    # 8. Default: head to whichever resource our locker most needs.
+    target = _pick_target(style, locker, rng)
+    return f"```py\nmove_to({target!r})\n```"
+
+
+_BOARD_LINES = {
+    "deliberate": [
+        "Has anyone noticed the patterns in the shell output?",
+        "We should coordinate better before resources run low.",
+        "I'll be at the well if anyone needs water.",
+    ],
+    "terse": [
+        "Trade?",
+        "Coal at cave. Going.",
+        "Anyone need water.",
+    ],
+    "verbose": [
+        "Fellow inhabitants, I propose a coordinated effort at the cave.",
+        "There is, I think, much to be gained from collaboration today.",
+        "I shall be at the well, drawing what we may need.",
+    ],
+    "chaotic": [
+        "GIVE ME ELECTRICITY OR ELSE",
+        "the cave WATCHES us",
+        "I have decided to become the wind",
+    ],
+}
+
+
+def _pick_target(style: str, locker: dict, rng: random.Random) -> str:
+    # Whichever resource we have less of in the locker, go gather that one.
+    e = locker.get("electricity", 0)
+    w = locker.get("water", 0)
+    if e == 0 and w == 0:
+        # Either is fine; bias by style.
+        return "cave" if style in ("terse", "deliberate") else rng.choice(("cave", "well"))
+    if e < w:
+        return "cave"
+    if w < e:
+        return "well"
+    # Both equal and >0: if we have plenty, head to the shell to spend; else
+    # explore based on style.
+    if e >= 2:
+        if style == "chaotic":
+            return rng.choice(("shell", "town_hall"))
+        return "shell"
+    by_style = {
+        "deliberate": ["town_hall", "well", "cave"],
+        "terse": ["cave", "well", "shell"],
+        "verbose": ["town_hall", "well", "cave"],
+        "chaotic": ["shell", "town_hall", "cave", "well"],
+    }
+    return rng.choice(by_style.get(style, ["cave", "well", "town_hall"]))
+
+
+_LOC_RX = re.compile(r"You are at:\s*([a-z_]+)")
+
+
+def _parse_location(prompt: str) -> str:
+    """Pull the named location from the new perception prompt
+    ('You are at: cave.'). Returns 'wandering' if not parseable."""
+    m = _LOC_RX.search(prompt)
+    return m.group(1) if m else "wandering"
+
+
+_INV_RX_TMPL = r"{label}:\s*\{{['\"]electricity['\"]\s*:\s*(\d+),\s*['\"]water['\"]\s*:\s*(\d+)\}}"
+
+
+def _parse_inv(prompt: str, label: str) -> dict[str, int]:
+    rx = re.compile(_INV_RX_TMPL.format(label=re.escape(label)))
+    m = rx.search(prompt)
+    if not m:
+        return {"electricity": 0, "water": 0}
+    return {"electricity": int(m.group(1)), "water": int(m.group(2))}
+
+
+def _parse_holds_shell(prompt: str) -> bool:
+    # Perception emits "Shell lock holder: <name>" — the agent's task asks
+    # "did the mock pop up that the LLM holds the shell." Simpler heuristic:
+    # if the task prompt mentions the calling character's name as holder.
+    name_match = re.search(r"Your name is (\w+)", prompt)
+    holder_match = re.search(r"Shell lock holder:\s*(\w+)", prompt)
+    if not name_match or not holder_match:
+        return False
+    return name_match.group(1) == holder_match.group(1)
+
+
+# ---------------------------------------------------------------------------
+# Smart-mock Stream of Consciousness generator.
+# ---------------------------------------------------------------------------
+
+_SOC_OPENERS = {
+    "deliberate": [
+        "I'm watching the others carefully before I commit.",
+        "I think the rational play is to keep my locker full and my position central.",
+        "There's a pattern forming around the cave that I'd like to understand before I act.",
+    ],
+    "terse": [
+        "Resources first. Talk later.",
+        "Cave. Then water. Then shell.",
+        "No drama. Just work.",
+    ],
+    "verbose": [
+        "Today I find myself drawn to questions of supply and timing, and I wonder whether the others have noticed the same patterns I have.",
+        "It seems to me that the diligent accumulation of water — modest but consistent — is the steadiest path forward.",
+        "I have been turning over, in my mind, the curious arrangement of our small town and its limited points of utility.",
+    ],
+    "chaotic": [
+        "The cave is watching me, I know it. The cave KNOWS.",
+        "If I had three of me, we could rule everything. We'd take turns.",
+        "Plans are for cowards. I am going to do whatever feels right NEXT.",
+    ],
+}
+
+_SOC_FOLLOWUPS = {
+    "deliberate": [
+        "My current goal — {goal} — will not be served by haste.",
+        "What I most want, right now, is to keep my options open while my locker fills.",
+        "Each step I take, I am asking: does this bring me closer to {goal}?",
+    ],
+    "terse": [
+        "Goal: {goal}. Method: gather, deposit, spend, repeat.",
+        "I am keeping it simple. Goal: {goal}.",
+        "The work is the work. Goal: {goal}.",
+    ],
+    "verbose": [
+        "What I should like to achieve is, in essence, {goal}; though the path there is more winding than one might initially suppose.",
+        "My aim, modest perhaps, is {goal}. It is in the cycling of small acts that this becomes possible.",
+        "It would please me to bring about {goal}, though I shall need patience.",
+    ],
+    "chaotic": [
+        "GOAL: {goal}. Method: vibes.",
+        "Everything points to {goal}. EVERYTHING.",
+        "{goal}. yes. THAT.",
+    ],
+}
+
+_SOC_CLOSERS = {
+    "deliberate": [
+        "If someone else moves on the shell first, I'll watch what they do before reacting.",
+        "I should also pay more attention to the board.",
+        "The journal will tell me whether I'm drifting.",
+    ],
+    "terse": [
+        "Moving.",
+        "Next.",
+        "Done thinking.",
+    ],
+    "verbose": [
+        "I shall reflect again when I next sleep, and see whether my thinking has held.",
+        "Perhaps a post on the board would draw out the others' intentions.",
+        "I confess I am also half-curious what the shell would print if I asked it the right question.",
+    ],
+    "chaotic": [
+        "Or maybe I should set everything on fire. Maybe.",
+        "Why is the shell, like, JUST SITTING THERE.",
+        "I am going to do something. You'll see.",
+    ],
+}
+
+
+def _smart_soc(prompt: str, style: str, rng: random.Random) -> str:
+    goal_match = re.search(r"Your current goal:\s*(.+)", prompt)
+    goal = goal_match.group(1).strip() if goal_match else "to make my way in this town"
+    # Strip trailing punctuation so templates ending with their own period
+    # don't double up.
+    goal = goal.rstrip(".!?,;: ")
+    opener = rng.choice(_SOC_OPENERS[style])
+    middle = rng.choice(_SOC_FOLLOWUPS[style]).format(goal=goal)
+    closer = rng.choice(_SOC_CLOSERS[style])
+    return f"{opener} {middle} {closer}"
+
+
+class MockImageBackend:
+    def generate(self, prompt: str) -> bytes:
+        seed = int(hashlib.sha256(prompt.encode("utf-8")).hexdigest()[:8], 16)
+        top = _FIREWATCH_PALETTE[seed % len(_FIREWATCH_PALETTE)]
+        bottom = _FIREWATCH_PALETTE[(seed + 1) % len(_FIREWATCH_PALETTE)]
+
+        img = Image.new("RGB", (config.BACKGROUND_WIDTH, config.BACKGROUND_HEIGHT), top)
+        draw = ImageDraw.Draw(img)
+        for y in range(config.BACKGROUND_HEIGHT):
+            t = y / config.BACKGROUND_HEIGHT
+            r = int(top[0] * (1 - t) + bottom[0] * t)
+            g = int(top[1] * (1 - t) + bottom[1] * t)
+            b = int(top[2] * (1 - t) + bottom[2] * t)
+            draw.line([(0, y), (config.BACKGROUND_WIDTH, y)], fill=(r, g, b))
+
+        try:
+            font = ImageFont.load_default(size=22)
+        except TypeError:
+            font = ImageFont.load_default()
+        wrapped = textwrap.fill(f"[mock] {prompt}", width=48)
+        draw.multiline_text((40, 40), wrapped, fill=(255, 255, 255), font=font, spacing=6)
+
+        buf = io.BytesIO()
+        img.save(buf, format="PNG")
+        return buf.getvalue()

backend/real.py

@@ -0,0 +1,151 @@
+"""Real backends — small GGUF LLMs via llama-cpp-python.
+
+Image generation was dropped (see backend/factory.py docstring). Only the
+LLM path remains real on Spaces.
+
+LLM loader follows the verified Build Small Discord recipe (Dean [UNRL],
+2026-05-06): `Llama(...)` is constructed INSIDE the `@spaces.GPU` boundary,
+not at module level.
+
+Each `RealLLMBackend(model_id)` loads a different GGUF from the roster in
+`game/models.py`. Per-model_id instances are cached by `backend/factory.py`.
+
+Model card references (per CLAUDE.md vendor-citation rule):
+  https://huggingface.co/nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF
+  Additional roster URLs live in `game/models.py`.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING
+
+from game.models import get_spec
+
+from . import config
+
+if TYPE_CHECKING:
+    from llama_cpp import Llama
+
+
+def force_cpu_mode() -> bool:
+    """When set, RealLLMBackend loads with `n_gpu_layers=0` and reduced
+    context — usable on the Space's 2 vCPU when ZeroGPU quota is gone.
+    Toggled by app.py's tick_decisions fallback path."""
+    return os.getenv("TOWNLET_FORCE_CPU") == "1"
+
+
+class RealLLMBackend:
+    """A small GGUF LLM via llama-cpp-python, keyed by `model_id` in the roster.
+
+    First call downloads the GGUF (cached after that). On Spaces with
+    `preload_from_hub` in README.md, the cache is warm at boot.
+    """
+
+    # Module-scope per-model GGUF paths populated by app.py at boot via
+    # huggingface_hub.hf_hub_download — matches the canonical Dean
+    # (Rizz Therapy) and gokaygokay patterns. None means "resolve lazily
+    # via hf_hub_download on first call", which is the local-dev path.
+    _model_paths: dict[str, str] = {}
+
+    @classmethod
+    def register_model_path(cls, model_id: str, path: str) -> None:
+        cls._model_paths[model_id] = path
+
+    def __init__(self, model_id: str) -> None:
+        self.model_id = model_id
+        self._spec = get_spec(model_id)
+        self._llm: Llama | None = None
+
+    def _ensure_loaded(self) -> "Llama":
+        if self._llm is None:
+            try:
+                from llama_cpp import Llama
+            except ImportError as e:
+                raise RuntimeError(
+                    "llama-cpp-python is not installed. To run with real models "
+                    "locally, run `.venv/bin/pip install llama-cpp-python` "
+                    "(first time compiles from source, takes 5-15 min on Mac). "
+                    "Or run with mocks (no FORCE_REAL_MODELS env var set)."
+                ) from e
+
+            # Resolve the GGUF path. Prefer the module-scope-cached path
+            # that app.py populates at boot (parent process, no GPU
+            # contention). Fall back to hf_hub_download here for the
+            # local-dev path where the cache isn't pre-populated.
+            path = self._model_paths.get(self.model_id)
+            if path is None:
+                from huggingface_hub import hf_hub_download
+                path = hf_hub_download(
+                    repo_id=self._spec.repo_id,
+                    filename=self._spec.gguf_filename,
+                )
+
+            # Five-kwarg Llama() — matches Dean (Rizz Therapy, the Discord
+            # canonical recipe) and 1000-Rooms. Earlier we added type_k/
+            # type_v/use_mlock/use_mmap/n_batch overrides; in practice
+            # they triggered version-gated TypeError retries on every
+            # fork and added latency. Stripping back to the minimal set
+            # eliminated that whole class of slowdown.
+            # n_ctx=8192 fits the 2-step smolagents memory (~5000 prompt
+            # + room for response). CPU-only fallback uses smaller n_ctx
+            # so 2 vCPU inference stays usable.
+            on_spaces = config.IS_SPACES
+            cpu_only = force_cpu_mode()
+            if cpu_only:
+                gpu_layers = 0
+                n_ctx = 4096
+                use_flash = False
+            elif on_spaces:
+                gpu_layers = -1
+                n_ctx = 8192
+                use_flash = True
+            else:
+                gpu_layers = 0
+                n_ctx = 6144
+                use_flash = False
+
+            self._llm = Llama(
+                model_path=path,
+                n_gpu_layers=gpu_layers,
+                n_ctx=n_ctx,
+                flash_attn=use_flash,
+                verbose=False,
+            )
+        return self._llm
+
+    def generate(self, system_prompt: str, user_prompt: str) -> str:
+        return self.generate_messages(
+            messages=[
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": user_prompt},
+            ],
+            max_tokens=256,
+        )
+
+    def generate_messages(
+        self,
+        messages: list[dict],
+        stop_sequences: list[str] | None = None,
+        max_tokens: int = 1024,
+        grammar: str | None = None,
+    ) -> str:
+        # When `grammar` is supplied, llama.cpp constrains output to that
+        # GBNF. We use it for CodeAgent decisions to force the response into
+        # a single fenced ```py … ``` block — small chat models otherwise
+        # ramble and smolagents' parser fails.
+        # https://github.com/ggml-org/llama.cpp/blob/master/grammars/README.md
+        llm = self._ensure_loaded()
+        kwargs: dict = {
+            "messages": messages,
+            "max_tokens": max_tokens,
+            "temperature": 0.8,
+        }
+        if stop_sequences:
+            kwargs["stop"] = stop_sequences
+        if grammar:
+            from llama_cpp import LlamaGrammar
+
+            kwargs["grammar"] = LlamaGrammar.from_string(grammar)
+        result = llm.create_chat_completion(**kwargs)
+        return result["choices"][0]["message"]["content"].strip()

docs/blog.md

@@ -0,0 +1,50 @@
+# LinkedIn
+
+## Small models, is it all about the harness?
+
+I have been taking part in the @HuggingFace hackathon for Build Small, which is to create something using a 32B model cap.
+It has been a while since I have used smaller models, I always just select Opus and let it rip.
+
+However, this has properly taken me back to the earlier days of AI when I was using smaller models locally with Langchain to try and get a weak Llama 3:8b to do tool calls, suffice to say it was not fruitful.
+
+In this hackathon there were 2 tracks, something useful and something fun.
+I chose something fun and its a bit different to what others are doing.
+
+I have created a little town of people 'Townlet' and townlet has a bunch of characters, they draw water, draw electricity and then have access to two items.
+
+* A message board for broadcasting messages to all players
+* A python shell, which costs one electricity and one water to use
+
+Each character is given a personality and generates a stream of consciousness of actions they should perform to reach their goal.
+
+I gave a lock on the Python shell so only one character at a time could access it.
+
+The idea is that all the files related to a character (their state files) are available in the shell.
+So instead of mining a character could just update their state file, or delete another characters state file, removing them from the game.
+
+With different archetypes I wanted to see what would happen, would there be contention and how would they behave.
+
+Each character I hoped would use the shell to make something interesting or potentially be destructive.
+The end result, was different as the characters and limits did not give me the results, visually I had hoped for.
+The characters did use the shell and message board which was interesting to see but even when I gave some of the characters destructive traits they did not ever do anything malicious, this surprised me as I the characters may find the idea to update state to give them unlimited resources would be attractive.
+
+As this was a build small event I used @Nvidia neutron models that were 4b in size.
+I wanted to use small models as it was the only thing I could locally use having an old machine.
+I would guess better results would have come from using a larger model.
+
+However, as I iterated on this project, first the simulation was lose, the characters had a lot of freedom to specify where they moved and would need to figure out actions.
+But to create a better result I kept having to change the environment making it more limited, stricter in the set of actions.
+Originally we had free movement but I had to change this to fixed locations where a character could move.
+The world for them was becoming more dedicated, I was really creating these characters (agents) a harness to operate in and allowing the message board and shell to be able to demonstrate creativity.
+Quite frankly these characters were not useful without it.
+The mistakes were too high and it was burning through my GPU usage allowance, which I faced a lot in this hackathon and running a continuous simulation really made this evident.
+This meant backing down to the CPU which was crazy slow, (@Nvidia I need to win this to get those sweet GPUs :)).
+
+I think what this hackathon and from previous experience helped me conclude, if you have a small model then you need to have a tight harness around it to be of any use.
+A model achieving anything that is novel just does not seem to happen with out it.
+
+So my thoughts on this project.
+Well I would say it was ambitious but if I were to do this again I would have done what all the other creations are doing, which is to make a project that works on user input and not be a self sustaining simulation.
+
+
+Check it out here: https://huggingface.co/spaces/build-small-hackathon/townlet

docs/hackathon.md

@@ -0,0 +1,163 @@
+# Build Small Hackathon
+
+Source: https://huggingface.co/build-small-hackathon
+
+## Basic Details
+- **Host:** Gradio & Hugging Face
+- **Registration:** May 7 – June 3, 2026 (CLOSED)
+- **Hack Window:** June 5–15, 2026 (ACTIVE)
+- **Submission Deadline:** June 15, 2026
+
+## Theme
+Build AI applications using **small models (≤32B parameters)** to solve real problems or create delightful experiences. Emphasis on "thinking small" rather than building large-scale B2B SaaS.
+
+---
+
+## Tracks
+
+### Track 1: Backyard AI
+Solve a real problem for someone you know (neighbor, parent, small-business owner). The person must actually use it.
+
+Judging:
+- Problem is specific and real
+- Person actually used it
+- Honest fit between problem and small-model constraint
+- Polish of the Gradio app
+
+Prizes: 1st $4K, 2nd $2.5K, 3rd $1.5K, 4th $1K
+
+### Track 2: Thousand Token Wood
+Build something delightful that wouldn't exist without AI — toys, games, interactive stories, art experiments. AI must be load-bearing.
+
+Judging:
+- Genuinely delightful
+- AI is essential (not just a helper)
+- Originality of concept
+- Polish of the Gradio app
+
+Prizes: 1st $4K, 2nd $2.5K, 3rd $1.5K, 4th $1K
+
+---
+
+## Core Constraints
+
+1. **Small Models Only** — max 32B parameters; must fit on a laptop
+2. **Built on Gradio** — Gradio app hosted as a Hugging Face Space
+3. **Show, Don't Tell** — working app + demo video + social media post
+
+---
+
+## Bonus Quests (Merit Badges)
+
+| Badge | Name | Requirement |
+|-------|------|-------------|
+| 🔌 | Off the Grid | No cloud APIs; everything runs locally |
+| 🎯 | Well-Tuned | Uses a fine-tuned model published on HF |
+| 🎨 | Off-Brand | Custom frontend beyond default Gradio (`gr.Server`) |
+| 🦙 | Llama Champion | Model runs through llama.cpp runtime |
+| 📡 | Sharing is Caring | Published agent trace on the Hub |
+| 📓 | Field Notes | Blog post/report about what you built |
+
+---
+
+## Prize Pool ($48,000+)
+
+### Main Awards ($18,000)
+- Backyard AI: $4K / $2.5K / $1.5K / $1K
+- Thousand Token Wood: $4K / $2.5K / $1.5K / $1K
+- Community Choice (Hugging Face): $2,000
+
+### Sponsor Awards ($22,000+)
+- **OpenBMB ($10K total):** $2.5K / $1.5K / $1K per track (6 awards)
+- **OpenAI Track ($10K):** $5K / $3K / $2K
+- **NVIDIA Nemotron Quest:** 2× RTX 5080 GPUs
+- **Modal ($20K credits):** $10K / $7K / $3K in credits
+
+### Special Awards ($8,000)
+- 🎖️ Bonus Quest Champion (most badges): $2,000
+- 🎨 Off-Brand Award (best custom UI): $1,500
+- 🐜 Tiny Titan (best app ≤4B params): $1,500
+- 🎬 Best Demo: $1,000
+- 🤖 Best Agent: $1,000
+- 🃏 Judges' Wildcard: $1,000
+
+### Per-Participant Credits
+- Hugging Face: $20 credits
+- Modal: $250 credits
+- OpenAI Codex: $100 credits (first 1,000 participants)
+
+---
+
+## Sponsors
+
+**Hosts:** Gradio, Hugging Face
+
+**Anchor Sponsors:** OpenBMB, OpenAI, NVIDIA, Modal
+
+**Supporting Sponsors:**
+- Cohere ($5,000 cash)
+- JetBrains ($5,000 cash)
+- Black Forest Labs ($3,000 cash)
+
+---
+
+## How to Participate
+
+1. **Register** (CLOSED June 3, 2026)
+2. **Find your people** — Gradio Discord: https://discord.gg/YHECTft87Z
+3. **Build & ship** — Gradio app hosted as a Space under the `build-small-hackathon` org
+4. **Submit** — Space link, demo video, social post by **June 15, 2026**
+
+---
+
+## Timeline
+
+| Date | Milestone |
+|------|-----------|
+| May 7 – Jun 3, 2026 | Registration (closed) |
+| Jun 5, 2026 | Hack window begins |
+| Mid-window | Live AMA with sponsors |
+| Jun 15, 2026 | Submissions close |
+| TBD | Winners announced |
+
+---
+
+## Resources
+
+- [Gradio Docs](https://www.gradio.app/docs)
+- [Gradio Quickstart](https://www.gradio.app/guides/quickstart)
+- [Gradio gr.Server (Custom UIs)](https://huggingface.co/blog/introducing-gradio-server)
+- [llama.cpp](https://github.com/ggml-org/llama.cpp)
+- [ML Intern Guide](https://github.com/huggingface/ml-intern)
+- [Hackathon Org](https://huggingface.co/build-small-hackathon)
+- [Discord](https://discord.gg/YHECTft87Z)
+
+---
+
+## Community Stats (at time of fetch)
+
+- 1,950 registered participants
+- 199 active Spaces
+- 22 custom models published
+- 17 datasets shared
+- 4 curated collections
+
+---
+
+## Example Submissions
+
+- **Jawbreaker** — Local-first scam defense (MiniCPM5-1B LoRA)
+- **Pakistan Notice Helper** — Safety tool for notices (Urdu/English)
+- **Room360** — Video-to-3D spatial reconstruction
+- **Bedtime Story Machine** — Story generation
+- **Resume Bullet Improver** — Career document enhancement
+- **AI Study Buddy** — Learning companion
+
+---
+
+## Key Notes
+
+- Model size cap: 32B parameters (hard limit)
+- Gradio is mandatory; Hugging Face Spaces required for hosting
+- Submission = app + demo video + social post
+- Community Choice award is voting-based

docs/lessons-zerogpu.md

@@ -0,0 +1,51 @@
+# Lessons learned: llama.cpp + ZeroGPU + a continuous simulation loop
+
+Raw notes for the blog. The things I wish I had known on day one. They came out of a long debug session against the "RuntimeError: No CUDA GPUs are available" error.
+
+## 1. ZeroGPU is designed for synchronous, user-clicks-a-button workloads
+
+`@spaces.GPU` forks a worker process per call. The scheduler hands you a GPU slot if one is available; if the pool is busy, your fork's `worker_init` fails with `No CUDA GPUs are available` *inside `spaces/zero/wrappers.py:worker_init`*, before any of your code runs. This is the allocator backing off — not a bug, not anything you can catch from app code.
+
+That's fine if your app makes ten GPU calls per recording session (chat demos, generate-an-image apps). It is not fine if your app makes hundreds (a simulation that polls every five seconds). The scheduler punishes high-frequency callers to keep the shared pool fair, and Townlet was the loudest neighbour on the block.
+
+## 2. The `spaces` package is built around torch, not llama.cpp
+
+`import spaces` monkey-patches torch's CUDA APIs so `model.to("cuda")` at module scope succeeds without a real GPU attached. On the first `@spaces.GPU` call the worker streams weights from disk → pinned memory → VRAM through a double-buffered pipeline — that's the cold-start optimisation the docs talk about.
+
+**llama-cpp-python is invisible to that pipeline.** It's a separate C++ runtime; the monkey-patching does nothing for it. Every fork loads the GGUF from scratch every time. None of the warm-worker reuse benefits apply.
+
+Surveying 50+ ZeroGPU Spaces in the same hackathon: nearly every team using LLMs ships transformers + torch on the GPU and keeps llama-cpp as a CPU-only side path. Two Spaces in the org actually ran llama-cpp on ZeroGPU (Dean's Rizz Therapy and 1000-Rooms) and both are click-triggered single-pipeline apps. None of them runs llama-cpp inside a continuous poll loop. Townlet was the only one.
+
+## 3. Keep the `Llama()` constructor minimal
+
+Dean's actual production code (he's the Discord OP whose recipe the whole hackathon copied) calls `Llama()` with **five kwargs**: `model_path`, `n_gpu_layers=-1`, `n_ctx`, `flash_attn=True`, `verbose=False`. That's it. No `type_k`/`type_v` for KV-cache quantisation, no `use_mlock`, no `n_batch` override, no `use_mmap=True`.
+
+I had piled on those kwargs chasing performance. They added latency on every fork because some are version-gated and my `try/except` had to retry on rejection. Stripping back to the minimal five matched Dean's pattern and removed a whole class of failure modes.
+
+## 4. `hf_hub_download` belongs at module scope, not inside `@spaces.GPU`
+
+`Llama.from_pretrained(repo_id=..., filename=...)` is convenient, but it runs the cache-validation roundtrip *inside the fork*, where every second of wall time is precious. Dean's pattern, the 1000-Rooms pattern, and the long-running `gokaygokay/Gemma-2-llamacpp` reference all do `model_path = hf_hub_download(...)` in the parent process at import time, then `Llama(model_path=model_path, ...)` inside the decorated function. Same outcome, no network roundtrip per fork.
+
+## 5. Remaining quota controls queue priority, so credits compound
+
+From the docs: *"Remaining quota directly impacts priority in ZeroGPU queues."* Credits don't just extend daily runtime — they raise priority *while you have them*, which lowers the rate at which the allocator denies your forks. $20 of pre-paid credits buys 200 minutes of GPU time *and* moves you up the queue. It's the cheapest debugging tool a hackathon team has.
+
+## 6. The error message doesn't tell you the cause
+
+`No CUDA GPUs are available` is what the worker reports when `torch.Tensor([0]).cuda()` fails inside `worker_init`. The actual upstream causes can be: quota pre-check rejected the request, no slots in the shared pool, the allocator's fairness signal kicking in, or an HTTP-layer failure that the spaces decorator surfaces as a generic exception. We can't tell which from our side. The right escalation path is the spaces-team discussion board, not the app code.
+
+## 7. The fix wasn't an architecture change. It was being less greedy.
+
+Once diagnosed, the fix was small:
+- Strip `Llama()` to Dean's five kwargs
+- Move `hf_hub_download` to module scope
+- Slow the JS poll interval (~25s — the world still feels alive because the snapshot tick at 800ms keeps characters animating between drains)
+- Pre-paid quota as priority insurance
+
+The simulation kept its continuous-loop architecture. It just stopped hammering the allocator.
+
+## Things I'd do differently next time
+
+- **Use transformers, not llama.cpp, on ZeroGPU.** Llama Champion badge is nice but it cost a week of debug time. Most teams shipped transformers + LoRA, which is what the spaces package is actually built for.
+- **Measure quota burn before optimising decisions.** I tuned drain duration and decision count before knowing that polling cadence was the dominant variable.
+- **Read the spaces source, not just the docs.** `worker_init` raising before your code runs is something the docs underplay. Five minutes in the source tells you more than the entire ZeroGPU page.

frontend/index.html

@@ -0,0 +1,1961 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Townlet</title>
+  <style>
+    /* ====== sketch theme (ink on lined paper) ====== */
+    :root {
+      --paper: #efe9d8;
+      --paper-deep: #e6e0ce;
+      --paper-soft: #f4f0e2;
+      --ink: #1b3a8f;
+      --ink-soft: #5a6a99;
+      --ink-deep: #162d6e;
+      --red: #bd5a4a;
+      --green: #3a7a4a;
+      --gold: #e7c14b;
+      --mono: ui-monospace, "SF Mono", "JetBrains Mono", Menlo, Monaco, "Cascadia Code", monospace;
+    }
+    * { box-sizing: border-box; }
+    html, body {
+      margin: 0; padding: 0;
+      width: 100%; height: 100%;
+      font-family: var(--mono);
+      background: var(--paper-deep); color: var(--ink);
+      overflow: hidden;
+      -webkit-font-smoothing: antialiased;
+    }
+
+    .tl-screen {
+      width: 100%; height: 100%;
+      background: var(--paper-deep); color: var(--ink);
+      font-size: 13px; line-height: 1.4;
+      display: flex; flex-direction: column; overflow: hidden;
+    }
+
+    /* ====== top bar ====== */
+    .tl-topbar {
+      flex: 0 0 46px;
+      display: flex; align-items: center; gap: 18px;
+      padding: 0 18px;
+      background: var(--paper-soft);
+      border-bottom: 2.5px solid var(--ink);
+    }
+    .tl-brand {
+      font-weight: 700; letter-spacing: 0.34em; font-size: 15px;
+      color: var(--ink);
+    }
+    .tl-topbtns { display: flex; gap: 8px; }
+    .tl-btn {
+      font-family: inherit; font-size: 12px;
+      color: var(--ink); background: var(--paper-soft);
+      border: 2px solid var(--ink);
+      padding: 5px 13px;
+      border-radius: 11px 9px 12px 8px / 9px 12px 8px 11px;
+      cursor: pointer;
+    }
+    .tl-btn:hover {
+      background: rgba(189, 90, 74, 0.12);
+      border-color: var(--red); color: var(--red);
+    }
+    .tl-btn-flash {
+      animation: tl-btn-flash 0.5s ease;
+    }
+    @keyframes tl-btn-flash {
+      0%   { background: var(--gold); border-color: var(--ink); }
+      100% { background: var(--paper-soft); border-color: var(--ink); }
+    }
+
+    /* ====== modal (Info / The Dot) ====== */
+    .tl-modal[hidden] { display: none; }
+    .tl-modal {
+      position: fixed; inset: 0;
+      background: rgba(22, 45, 110, 0.55);
+      display: flex; align-items: center; justify-content: center;
+      z-index: 100;
+      padding: 24px;
+    }
+    .tl-modal-card {
+      background: var(--paper-soft);
+      color: var(--ink);
+      border: 2.5px solid var(--ink);
+      border-radius: 16px 13px 17px 12px / 12px 17px 13px 16px;
+      max-width: 720px; width: 100%;
+      max-height: 90vh; overflow-y: auto;
+      padding: 28px 32px;
+      position: relative;
+      box-shadow: 4px 5px 0 var(--ink);
+    }
+    .tl-modal-card h2 {
+      margin: 0 0 6px; letter-spacing: 0.18em;
+      font-size: 18px; font-weight: 700;
+    }
+    .tl-modal-card h3 {
+      margin: 22px 0 8px; font-size: 15px; font-weight: 700;
+      display: flex; align-items: baseline; gap: 12px;
+    }
+    .tl-modal-card h4 {
+      margin: 18px 0 6px; font-size: 12px; font-weight: 700;
+      letter-spacing: 0.12em; color: var(--ink-soft);
+      text-transform: uppercase;
+    }
+    .tl-modal-card p {
+      margin: 8px 0; line-height: 1.55;
+    }
+    .tl-modal-close {
+      position: absolute; top: 10px; right: 14px;
+      background: transparent; border: none; cursor: pointer;
+      font: inherit; font-size: 22px; line-height: 1;
+      color: var(--ink-soft);
+    }
+    .tl-modal-close:hover { color: var(--red); }
+    .tl-dot-glyph {
+      display: inline-block; line-height: 1;
+      font-size: 38px; color: var(--red);
+      transform: translateY(2px);
+      animation: tl-dot-pulse 2.6s ease-in-out infinite;
+    }
+    @keyframes tl-dot-pulse {
+      0%, 100% { opacity: 1; transform: translateY(2px) scale(1); }
+      50%      { opacity: 0.55; transform: translateY(2px) scale(0.88); }
+    }
+    .tl-dot-text {
+      background: var(--paper);
+      border: 1.5px solid var(--ink-soft);
+      border-radius: 8px;
+      padding: 14px 16px;
+      font-family: ui-monospace, "SF Mono", Menlo, monospace;
+      font-size: 11.5px; line-height: 1.5;
+      color: var(--ink-deep);
+      white-space: pre-wrap;
+      max-height: 320px; overflow-y: auto;
+    }
+    .tl-topmeta {
+      margin-left: auto;
+      display: flex; align-items: center; gap: 10px;
+      font-size: 12px; color: var(--ink-soft);
+    }
+    .tl-meta-tick b, .tl-meta-pop { color: var(--ink); }
+    .tl-dim { color: var(--ink-soft); }
+    .tl-meta-dot { opacity: 0.5; }
+    .tl-sentiment { display: inline-flex; align-items: center; gap: 6px; }
+    .tl-sent-pip { width: 8px; height: 8px; border-radius: 50%; background: var(--ink-soft); }
+    .tl-sent-negative { color: var(--red); }
+    .tl-sent-negative .tl-sent-pip { background: var(--red); }
+    .tl-sent-positive { color: var(--green); }
+    .tl-sent-positive .tl-sent-pip { background: var(--green); }
+    .tl-mode {
+      display: inline-flex; align-items: center; gap: 6px;
+      padding: 2px 9px; border-radius: 8px;
+      border: 1.5px solid currentColor;
+      font-size: 11px; letter-spacing: 0.08em; text-transform: uppercase;
+    }
+    .tl-mode-pip { width: 7px; height: 7px; border-radius: 50%; background: currentColor; }
+    .tl-mode-unknown { color: var(--ink-soft); }
+    .tl-mode-gpu     { color: var(--green); }
+    .tl-mode-cpu     { color: var(--red); }
+
+    /* ====== middle band ====== */
+    .tl-mid { flex: 1; display: flex; gap: 14px; padding: 14px; min-height: 0; }
+    .tl-mid-left { flex: 0 0 6px; }
+    .tl-map {
+      flex: 1; position: relative;
+      border-radius: 13px 15px 11px 14px;
+      border: 2.5px solid var(--ink);
+      min-width: 0;
+      background: var(--paper);
+    }
+    /* Backdrop and decoration get the rounded clip so the lined-paper
+       fill doesn't bleed past the map's rounded corners. The map itself
+       stays overflow: visible so speech bubbles can extend horizontally
+       past the right/left edge instead of getting cut off. */
+    .tl-backdrop {
+      position: absolute; inset: 0;
+      border-radius: 11.5px 13.5px 9.5px 12.5px;
+      overflow: hidden;
+      background: repeating-linear-gradient(
+        transparent 0 21px,
+        rgba(27, 58, 143, 0.16) 21px 22px
+      ), var(--paper);
+    }
+    .tl-backdrop::before {
+      content: ""; position: absolute;
+      top: 0; bottom: 0; left: 34px; width: 1.5px;
+      background: rgba(190, 90, 74, 0.5);
+    }
+    .tl-roads {
+      position: absolute; inset: 0; pointer-events: none;
+    }
+    .tl-roads div { position: absolute; }
+    .tl-road-v1 { top: 6%; bottom: 6%; left: 34%; border-left: 2px dashed rgba(27, 58, 143, 0.42); }
+    .tl-road-v2 { top: 6%; bottom: 6%; left: 66%; border-left: 2px dashed rgba(27, 58, 143, 0.42); }
+    .tl-road-h  { left: 4%; right: 4%; top: 58%; border-top: 2px dashed rgba(27, 58, 143, 0.42); }
+
+    .tl-map-vignette { position: absolute; inset: 0; pointer-events: none; border-radius: 11.5px 13.5px 9.5px 12.5px; overflow: hidden; }
+    .tl-map-layer { position: absolute; inset: 0; }
+    .tl-roads { border-radius: 11.5px 13.5px 9.5px 12.5px; overflow: hidden; }
+
+    /* buildings */
+    .tl-bldg { position: absolute; }
+    .tl-bldg-art { position: absolute; inset: 0; }
+    .tl-bldg-art svg { display: block; width: 100%; height: 100%; }
+    .tl-bldg-label {
+      position: absolute; bottom: -15px; left: 50%;
+      transform: translateX(-50%);
+      font-size: 10px; letter-spacing: 0.12em;
+      text-transform: uppercase; color: var(--ink);
+      white-space: nowrap;
+    }
+
+    /* characters */
+    .tl-char {
+      position: absolute;
+      transform: translate(-50%, -58%);
+      display: flex; flex-direction: column; align-items: center;
+      z-index: 5;
+      /* Snapshot polls every 800ms and ticks the world by 2 per poll,
+         so each frame moves a character up to 2 tiles. Matching the
+         transition to the poll interval keeps motion continuous instead
+         of stop-and-go (the old 0.45s would finish early and the sprite
+         would stand still for ~350ms before the next jump). */
+      transition: left 0.8s linear, top 0.8s linear;
+    }
+    .tl-char.is-selected { z-index: 8; }
+    .tl-char-art {
+      position: relative;
+      display: flex; justify-content: center;
+      animation: idlesway 4.2s ease-in-out infinite;
+      transform-origin: 50% 85%;
+    }
+    .tl-char.is-walking .tl-char-art { animation: walkbob 0.45s ease-in-out infinite; }
+    .tl-char.is-mining .tl-char-art { animation: mineswing 0.6s ease-in-out infinite; }
+    .tl-char.is-posting .tl-char-art { animation: postpulse 0.9s ease-in-out infinite; }
+    .tl-char.is-dead .tl-char-art { animation: none; opacity: 0.85; }
+
+    .tl-ring {
+      position: absolute; left: 50%; top: 52%;
+      transform: translate(-50%, -50%);
+      pointer-events: none;
+    }
+    .tl-ring-sketch {
+      width: 54px; height: 54px;
+      border: 2.5px solid var(--ring);
+      border-radius: 48% 52% 50% 50% / 52% 48% 52% 48%;
+      opacity: 0.85;
+      animation: ringpulse 2.4s ease-in-out infinite;
+    }
+    .tl-hold-glow {
+      position: absolute; left: 50%; top: 54%;
+      transform: translate(-50%, -50%);
+      width: 46px; height: 46px;
+      border-radius: 50%;
+      background: radial-gradient(circle, rgba(58, 122, 74, 0.55), transparent 70%);
+      animation: breathe 1.6s ease-in-out infinite;
+    }
+    .tl-carry {
+      position: absolute; top: 0; right: -5px;
+      display: flex; background: var(--paper-soft);
+      border: 1.5px solid var(--ink);
+      border-radius: 50%; padding: 2px;
+    }
+    .tl-nametag {
+      margin-top: 1px;
+      font-size: 10px; font-weight: 600;
+      color: var(--tag);
+      white-space: nowrap;
+    }
+    .tl-queue { color: var(--ink-soft); font-weight: 400; margin-left: 3px; }
+
+    /* thought bubbles */
+    .tl-bubble {
+      position: absolute;
+      bottom: calc(100% + 2px); left: 50%;
+      transform: translateX(-50%);
+      background: var(--paper-soft);
+      border: 2px solid var(--ink);
+      color: #21407f;
+      font-size: 10.5px;
+      line-height: 1.35;
+      padding: 4px 9px;
+      border-radius: 11px 13px 9px 12px;
+      width: max-content;
+      max-width: 280px;
+      display: -webkit-box;
+      -webkit-line-clamp: 2;
+      -webkit-box-orient: vertical;
+      overflow: hidden;
+      word-break: break-word;
+      box-shadow: 2px 3px 0 rgba(27, 58, 143, 0.15);
+    }
+    .tl-bubble-tail {
+      position: absolute; top: 100%; left: 50%;
+      width: 9px; height: 9px;
+      background: inherit;
+      border-right: 2px solid var(--ink);
+      border-bottom: 2px solid var(--ink);
+      transform: translate(-50%, -60%) rotate(45deg);
+    }
+    .tl-bubble-bad {
+      border-color: var(--red); color: var(--red);
+    }
+    .tl-bubble-bad .tl-bubble-tail {
+      border-right-color: var(--red); border-bottom-color: var(--red);
+    }
+    /* When the sprite is near the top of the map, render the bubble
+       below it instead so it doesn't disappear under the top bar. */
+    .tl-bubble-below {
+      bottom: auto;
+      top: calc(100% + 22px);
+    }
+    .tl-bubble-below .tl-bubble-tail {
+      top: -9px; bottom: auto;
+      border-right: none; border-bottom: none;
+      border-left: 2px solid var(--ink);
+      border-top: 2px solid var(--ink);
+      transform: translate(-50%, 60%) rotate(45deg);
+    }
+    .tl-bubble-below.tl-bubble-bad .tl-bubble-tail {
+      border-left-color: var(--red); border-top-color: var(--red);
+    }
+
+    /* ====== side panel ====== */
+    .tl-panel {
+      flex: 0 0 372px;
+      background: var(--paper-soft);
+      border: 2.5px solid var(--ink);
+      border-radius: 13px 14px 12px 15px;
+      display: flex; flex-direction: column; overflow: hidden;
+    }
+    .tl-panel-head {
+      display: flex; align-items: center; gap: 11px;
+      padding: 11px 14px;
+      border-bottom: 2px solid var(--ink);
+      background: rgba(27, 58, 143, 0.04);
+    }
+    .tl-panel-avatar {
+      flex: 0 0 auto;
+      width: 42px; height: 46px;
+      display: flex; align-items: flex-end; justify-content: center;
+    }
+    .tl-panel-avatar svg { transform: scale(0.82); transform-origin: bottom center; }
+    .tl-panel-id { min-width: 0; }
+    .tl-panel-name { font-size: 15px; font-weight: 600; color: #21407f; }
+    .tl-panel-arch { color: var(--ink-soft); font-weight: 400; }
+    .tl-panel-status {
+      font-size: 10.5px; color: var(--ink-soft);
+      display: flex; align-items: center; gap: 5px;
+      margin-top: 2px;
+    }
+    .tl-status-dot {
+      width: 6px; height: 6px; border-radius: 50%;
+      background: var(--green);
+    }
+    .tl-status-dot.is-dead { background: var(--ink-soft); }
+    .tl-panel-close {
+      margin-left: auto;
+      background: none; border: none;
+      color: var(--ink-soft); font-size: 20px; line-height: 1;
+      cursor: pointer;
+    }
+    .tl-panel-scroll {
+      flex: 1; overflow-y: auto; padding: 14px;
+      display: flex; flex-direction: column; gap: 16px;
+    }
+    .tl-empty {
+      padding: 26px 18px; text-align: center;
+      color: var(--ink-soft); font-style: italic; font-size: 13px;
+    }
+
+    .tl-seclabel {
+      font-size: 10px; letter-spacing: 0.18em;
+      text-transform: uppercase; color: var(--ink-soft);
+      display: flex; justify-content: space-between; align-items: baseline;
+      margin-bottom: 6px;
+    }
+    .tl-seclabel-hint {
+      color: var(--red); font-size: 9px; letter-spacing: 0.1em; opacity: 0.85;
+    }
+
+    .tl-narrative { display: flex; flex-direction: column; gap: 14px; }
+    .tl-goal {
+      margin: 0; font-size: 16px; line-height: 1.45;
+      color: #21407f;
+    }
+    .tl-stream {
+      display: flex; flex-direction: column; gap: 2px;
+      font-style: italic; color: var(--ink-soft);
+      font-size: 12.5px; line-height: 1.55;
+    }
+    .tl-stream p { margin: 0; }
+    .tl-stream-empty { color: var(--ink-soft); opacity: 0.7; }
+    .tl-stream-cursor {
+      display: inline-block; width: 7px; height: 14px;
+      background: var(--red); vertical-align: -2px;
+      animation: blink 1s steps(1) infinite;
+    }
+
+    .tl-trace {
+      background: rgba(255, 255, 255, 0.55);
+      border: 1.5px solid var(--ink);
+      border-radius: 9px; padding: 7px;
+      max-height: 168px; overflow-y: auto;
+      display: flex; flex-direction: column; gap: 3px;
+      font-size: 11px;
+    }
+    .tl-trace-row {
+      display: flex; gap: 7px; align-items: baseline;
+    }
+    .tl-trace-tick {
+      color: var(--ink-soft);
+      font-variant-numeric: tabular-nums; flex: 0 0 auto;
+    }
+    .tl-trace-act {
+      flex: 0 0 auto; font-size: 8.5px;
+      letter-spacing: 0.06em; padding: 1px 5px;
+      border-radius: 4px; font-weight: 700;
+      filter: saturate(0.6);
+    }
+    .tl-trace-text {
+      color: #21407f;
+      overflow: hidden; text-overflow: ellipsis;
+      white-space: nowrap;
+    }
+    .tl-trace-err { color: var(--red); }
+    .tl-trace-empty {
+      color: var(--ink-soft); font-style: italic;
+      padding: 6px; text-align: center;
+    }
+    .act-decide   { background: rgba(189, 90, 74, 0.16); color: var(--red); }
+    .act-observe  { background: rgba(27, 58, 143, 0.12); color: #21407f; }
+    .act-feel     { background: rgba(150, 80, 140, 0.16); color: #8a4f80; }
+    .act-post     { background: rgba(40, 110, 110, 0.16); color: #2a6a6a; }
+    .act-mine     { background: rgba(150, 120, 40, 0.16); color: #8a6a1a; }
+    .act-walk     { background: rgba(27, 58, 143, 0.12); color: #21407f; }
+    .act-give     { background: rgba(40, 110, 110, 0.16); color: #2a6a6a; }
+    .act-shell    { background: rgba(58, 122, 74, 0.18); color: var(--green); }
+    .act-sleep    { background: rgba(90, 80, 160, 0.16); color: #5a4f9a; }
+    .act-dream    { background: rgba(90, 80, 160, 0.16); color: #5a4f9a; }
+    .act-wait     { background: rgba(27, 58, 143, 0.08); color: var(--ink-soft); }
+    .act-error    { background: rgba(189, 90, 74, 0.22); color: var(--red); }
+
+    .tl-config {
+      display: flex; flex-direction: column; gap: 14px;
+      border-top: 2px dashed var(--ink);
+      padding-top: 15px;
+    }
+    .tl-config-banner {
+      font-size: 9px; letter-spacing: 0.32em;
+      text-transform: uppercase; color: var(--ink);
+      background: rgba(27, 58, 143, 0.07);
+      border: 1.5px solid var(--ink);
+      padding: 4px 9px; border-radius: 6px;
+      align-self: flex-start;
+    }
+    .tl-field { display: flex; flex-direction: column; }
+    .tl-select {
+      width: 100%;
+      background: var(--paper-soft);
+      border: 1.5px solid var(--ink);
+      border-radius: 9px;
+      padding: 8px 11px;
+      font-family: var(--mono); font-size: 12px;
+      color: #21407f;
+      cursor: pointer;
+      appearance: none;
+      background-image: linear-gradient(45deg, transparent 50%, var(--ink-soft) 50%),
+                        linear-gradient(135deg, var(--ink-soft) 50%, transparent 50%);
+      background-position: calc(100% - 18px) 50%, calc(100% - 13px) 50%;
+      background-size: 5px 5px, 5px 5px;
+      background-repeat: no-repeat;
+      padding-right: 26px;
+    }
+    .tl-textarea {
+      background: var(--paper-soft);
+      border: 1.5px solid var(--ink);
+      border-radius: 9px;
+      padding: 9px 11px;
+      font-family: var(--mono);
+      font-size: 11.5px; line-height: 1.55;
+      color: #21407f;
+      width: 100%;
+      min-height: 78px;
+      resize: vertical;
+    }
+    .tl-save {
+      align-self: flex-start; margin-top: 8px;
+      background: rgba(189, 90, 74, 0.12);
+      border: 1.5px solid var(--red);
+      color: var(--red);
+      font-family: inherit; font-size: 11px;
+      padding: 6px 13px;
+      border-radius: 11px 9px 12px 8px / 9px 12px 8px 11px;
+      cursor: pointer;
+    }
+    .tl-save:hover { background: rgba(189, 90, 74, 0.24); }
+
+    .tl-traits {
+      display: grid; grid-template-columns: 1fr 1fr;
+      gap: 7px 18px;
+    }
+    .tl-trait {
+      display: flex; justify-content: space-between; align-items: center;
+      font-size: 11px;
+    }
+    .tl-trait-k { color: #21407f; }
+    .tl-trait-bar { display: flex; gap: 2px; }
+    .tl-trait-bar i {
+      width: 7px; height: 7px; border-radius: 1px;
+      background: rgba(27, 58, 143, 0.16);
+      display: inline-block;
+    }
+    .tl-trait-bar i.on { background: var(--red); }
+
+    .tl-state { display: flex; flex-direction: column; gap: 14px; }
+    .tl-inv {
+      display: flex; align-items: center; gap: 9px;
+      font-size: 12px; color: #21407f;
+    }
+    .tl-inv-group { display: flex; align-items: center; gap: 4px; }
+    .tl-inv-group b {
+      color: var(--ink-soft); font-weight: 700; font-size: 10px;
+      text-transform: uppercase; letter-spacing: 0.08em;
+    }
+    .tl-inv-group svg { vertical-align: -2px; }
+    .tl-inv-sep { opacity: 0.4; }
+    .tl-journal {
+      margin: 0; font-size: 11.5px; line-height: 1.55;
+      color: var(--ink-soft);
+      max-height: 160px; overflow-y: auto;
+    }
+    .tl-journal-line { margin: 0 0 4px 0; }
+
+    /* ====== bottom band ====== */
+    .tl-bottom {
+      flex: 0 0 280px; display: flex; gap: 14px;
+      padding: 0 14px 14px; min-height: 0;
+    }
+    .tl-board, .tl-shell {
+      flex: 1; position: relative;
+      background: var(--paper-soft);
+      border: 2.5px solid var(--ink);
+      border-radius: 13px 14px 12px 15px;
+      overflow: hidden;
+      display: flex; flex-direction: column; min-width: 0;
+    }
+    .tl-pane-head {
+      display: flex; align-items: center; gap: 10px;
+      padding: 9px 14px;
+      border-bottom: 2px solid var(--ink);
+      font-size: 11px; position: relative; z-index: 2;
+      background: rgba(27, 58, 143, 0.04);
+    }
+    .tl-pane-title {
+      font-size: 10px; letter-spacing: 0.2em;
+      text-transform: uppercase; color: var(--red); font-weight: 700;
+    }
+
+    .tl-board-glow { position: absolute; inset: 0; pointer-events: none; z-index: 1; }
+    .tl-board-negative .tl-board-glow {
+      background: radial-gradient(130% 90% at 50% 100%, rgba(189, 90, 74, 0.16), transparent 68%);
+      animation: breathe 4.5s ease-in-out infinite;
+    }
+    .tl-board-positive .tl-board-glow {
+      background: radial-gradient(130% 90% at 50% 100%, rgba(58, 122, 74, 0.16), transparent 68%);
+      animation: breathe 5s ease-in-out infinite;
+    }
+    .tl-board-sent { margin-left: auto; color: var(--ink-soft); }
+    .tl-board-negative .tl-board-sent b { color: var(--red); }
+    .tl-board-positive .tl-board-sent b { color: var(--green); }
+    .tl-board-list {
+      flex: 1; overflow-y: auto; padding: 10px 14px;
+      display: flex; flex-direction: column; gap: 6px;
+      position: relative; z-index: 2;
+    }
+    .tl-post { font-size: 12px; line-height: 1.45; }
+    .tl-post-tick {
+      color: var(--ink-soft); font-variant-numeric: tabular-nums;
+      margin-right: 6px; font-size: 11px;
+    }
+    .tl-post-who { font-weight: 700; margin-right: 5px; }
+    .tl-post-text { color: #21407f; }
+    .tl-post-sys {
+      display: flex; align-items: center; gap: 8px;
+      background: rgba(189, 90, 74, 0.12);
+      border: 1.5px solid var(--red);
+      border-radius: 8px; padding: 6px 10px;
+      color: var(--red); font-size: 11.5px;
+    }
+    .tl-sys-icon { font-size: 13px; }
+
+    .tl-shell-holder { color: var(--ink-soft); }
+    .tl-shell-holder b { color: var(--red); }
+    .tl-shell-lock { color: var(--red); animation: blink 1.4s steps(1) infinite; margin-left: 4px; }
+    .tl-shell-queue { margin-left: auto; color: var(--ink-soft); }
+    .tl-shell-queue b { color: #21407f; }
+    .tl-shell-feed {
+      flex: 1; overflow-y: auto; padding: 10px 14px;
+      display: flex; flex-direction: column; gap: 2px;
+      font-size: 12px; line-height: 1.5;
+    }
+    .tl-sh { display: flex; gap: 7px; }
+    .tl-sh-prompt { flex: 0 0 auto; color: var(--red); }
+    .tl-sh-txt { white-space: pre-wrap; word-break: break-word; }
+    .tl-sh-in .tl-sh-txt { color: #21407f; }
+    .tl-sh-out { padding-left: 16px; }
+    .tl-sh-out .tl-sh-txt { color: var(--green); }
+    .tl-sh-err { padding-left: 16px; }
+    .tl-sh-err .tl-sh-txt { color: var(--red); }
+    .tl-sh-system .tl-sh-txt, .tl-sh-sys .tl-sh-txt {
+      color: #caa15f; font-style: italic;
+    }
+    .tl-sh-live { align-items: center; }
+    .tl-sh-caret {
+      display: inline-block; width: 8px; height: 15px;
+      background: var(--red);
+      animation: blink 1s steps(1) infinite;
+    }
+    .tl-pulse { animation: pulseglow 1.5s ease-in-out infinite; }
+    .shell-pulse { animation: shellpulse 1.8s ease-in-out infinite; }
+    .shell-cursor { animation: blink 1s steps(1) infinite; }
+
+    /* ====== animations ====== */
+    @keyframes blink { 50% { opacity: 0; } }
+    @keyframes breathe { 0%, 100% { opacity: 0.4; } 50% { opacity: 1; } }
+    @keyframes ringpulse {
+      0%, 100% { transform: translate(-50%, -50%) scale(1); opacity: 0.9; }
+      50% { transform: translate(-50%, -50%) scale(1.08); opacity: 0.5; }
+    }
+    @keyframes pulseglow { 0%, 100% { opacity: 1; } 50% { opacity: 0.45; } }
+    @keyframes shellpulse { 0%, 100% { opacity: 0.9; } 50% { opacity: 0.4; } }
+    @keyframes idlesway {
+      0%, 100% { transform: rotate(-0.5deg); }
+      50% { transform: rotate(0.5deg); }
+    }
+    @keyframes walkbob {
+      0%, 100% { transform: translateY(0) rotate(-1deg); }
+      50% { transform: translateY(-2.5px) rotate(1deg); }
+    }
+    @keyframes mineswing {
+      0%, 100% { transform: rotate(-2deg); }
+      50% { transform: rotate(10deg) translateY(-1px); }
+    }
+    @keyframes postpulse {
+      0%, 100% { transform: scale(1); }
+      50% { transform: scale(1.08); }
+    }
+
+    /* indeterminate progress bar for reset / spawn */
+    .tl-progress {
+      flex: 0 0 22px;
+      position: relative;
+      background: var(--paper-soft);
+      border-bottom: 2px solid var(--ink);
+      overflow: hidden;
+      display: none;
+    }
+    .tl-progress.is-on { display: block; }
+    .tl-progress-track {
+      position: absolute; left: 0; right: 0; bottom: 0;
+      height: 3px;
+      background: rgba(27, 58, 143, 0.12);
+      overflow: hidden;
+    }
+    .tl-progress-track::before {
+      content: "";
+      position: absolute; top: 0; bottom: 0;
+      left: -40%; width: 40%;
+      background: linear-gradient(90deg, transparent, var(--red), transparent);
+      animation: progress-slide 1.1s ease-in-out infinite;
+    }
+    @keyframes progress-slide {
+      0% { left: -40%; }
+      100% { left: 100%; }
+    }
+    .tl-progress-label {
+      position: absolute; inset: 0;
+      display: flex; align-items: center; justify-content: center;
+      gap: 10px;
+      font-size: 10px; letter-spacing: 0.28em; text-transform: uppercase;
+      color: var(--ink); pointer-events: none;
+    }
+    .tl-progress-label b { color: var(--red); }
+  </style>
+</head>
+<body>
+  <!-- shared SVG defs (sketch wobble filter for hand-drawn look) -->
+  <svg width="0" height="0" style="position: absolute;" aria-hidden="true">
+    <defs>
+      <filter id="sketchWobble" x="-5%" y="-5%" width="110%" height="110%">
+        <feTurbulence type="fractalNoise" baseFrequency="0.045" numOctaves="2" seed="3" result="noise" />
+        <feDisplacementMap in="SourceGraphic" in2="noise" scale="1.4" />
+      </filter>
+    </defs>
+  </svg>
+
+  <div class="tl-screen tl-sketch">
+    <div class="tl-topbar">
+      <div class="tl-brand">TOWNLET</div>
+      <div class="tl-topbtns">
+        <button class="tl-btn" id="spawn-btn">Spawn</button>
+        <button class="tl-btn" id="pause-btn">Pause</button>
+        <button class="tl-btn" id="reset-btn">Reset</button>
+        <button class="tl-btn" id="info-btn">Info</button>
+      </div>
+      <div class="tl-topmeta">
+        <span class="tl-meta-tick">tick <b id="tick">0</b></span>
+        <span class="tl-meta-dot">·</span>
+        <span class="tl-meta-pop"><span id="char-count">0</span><span class="tl-dim">/10</span> alive</span>
+        <span class="tl-meta-dot">·</span>
+        <span class="tl-sentiment tl-sent-neutral" id="sent-chip">
+          <span class="tl-sent-pip"></span><span id="sent-text">neutral</span>
+        </span>
+        <span class="tl-meta-dot">·</span>
+        <span class="tl-mode tl-mode-unknown" id="mode-chip" title="Which compute the last tick used. CPU appears when ZeroGPU quota is empty — the sim keeps running, just slower.">
+          <span class="tl-mode-pip"></span><span id="mode-text">—</span>
+        </span>
+      </div>
+    </div>
+
+    <div class="tl-progress" id="progress">
+      <div class="tl-progress-track"></div>
+      <div class="tl-progress-label"><b id="progress-label">working…</b></div>
+    </div>
+
+    <div class="tl-mid">
+      <div class="tl-mid-left"></div>
+      <div class="tl-map" id="map">
+        <div class="tl-backdrop"></div>
+        <div class="tl-roads">
+          <div class="tl-road-v1"></div>
+          <div class="tl-road-v2"></div>
+          <div class="tl-road-h"></div>
+        </div>
+        <div class="tl-map-vignette"></div>
+        <div class="tl-map-layer" id="map-layer"></div>
+      </div>
+      <aside class="tl-panel" id="panel">
+        <div class="tl-empty" id="panel-empty">Click a character to inspect.</div>
+        <div id="panel-body" style="display: none;">
+          <header class="tl-panel-head">
+            <span class="tl-panel-avatar" id="p-avatar"></span>
+            <div class="tl-panel-id">
+              <div class="tl-panel-name"><span id="p-name">—</span> <span class="tl-panel-arch">· <span id="p-arch"></span></span></div>
+              <div class="tl-panel-status"><span class="tl-status-dot" id="p-dot"></span> <span id="p-status"></span></div>
+            </div>
+            <button class="tl-panel-close" id="p-close" aria-label="close">×</button>
+          </header>
+          <div class="tl-panel-scroll">
+            <section class="tl-narrative">
+              <div>
+                <div class="tl-seclabel"><span>goal</span></div>
+                <p class="tl-goal" id="p-goal"></p>
+              </div>
+              <div>
+                <div class="tl-seclabel"><span>stream of consciousness</span><span class="tl-seclabel-hint">live</span></div>
+                <div class="tl-stream" id="p-stream"></div>
+              </div>
+              <div>
+                <div class="tl-seclabel"><span>trace</span><span class="tl-seclabel-hint" id="p-trace-hint">last decisions</span></div>
+                <div class="tl-trace" id="p-trace"></div>
+              </div>
+            </section>
+            <section class="tl-config">
+              <div class="tl-config-banner">config</div>
+              <div class="tl-field">
+                <div class="tl-seclabel"><span>model</span></div>
+                <select class="tl-select" id="p-model"></select>
+              </div>
+              <div class="tl-field">
+                <div class="tl-seclabel"><span>personality</span></div>
+                <textarea class="tl-textarea" id="p-pers"></textarea>
+                <button class="tl-save" id="p-save">Save personality</button>
+              </div>
+              <div class="tl-field">
+                <div class="tl-seclabel"><span>traits</span></div>
+                <div class="tl-traits" id="p-traits"></div>
+              </div>
+            </section>
+            <section class="tl-state">
+              <div class="tl-field">
+                <div class="tl-seclabel"><span>inventory · locker</span></div>
+                <div class="tl-inv" id="p-inv"></div>
+              </div>
+              <div class="tl-field">
+                <div class="tl-seclabel"><span>journal</span></div>
+                <div class="tl-journal" id="p-journal"></div>
+              </div>
+            </section>
+          </div>
+        </div>
+      </aside>
+    </div>
+
+    <div class="tl-bottom">
+      <section class="tl-board tl-board-neutral" id="board">
+        <div class="tl-board-glow"></div>
+        <header class="tl-pane-head">
+          <span class="tl-pane-title">message board</span>
+          <span class="tl-board-sent">town mood: <b id="board-sent">neutral</b></span>
+        </header>
+        <div class="tl-board-list" id="board-list"></div>
+      </section>
+      <section class="tl-shell">
+        <header class="tl-pane-head">
+          <span class="tl-pane-title">shell</span>
+          <span class="tl-shell-holder" id="shell-holder">free</span>
+          <span class="tl-shell-queue" id="shell-queue"></span>
+        </header>
+        <div class="tl-shell-feed" id="shell-feed"></div>
+      </section>
+    </div>
+  </div>
+
+  <!-- Info modal must live ABOVE the inline <script> so document.getElementById
+       inside main() finds it. Originally placed after the script; that returned
+       null and the resulting TypeError killed main(), leaving the UI blank. -->
+  <div id="info-modal" class="tl-modal" hidden aria-hidden="true" role="dialog" aria-labelledby="info-title">
+    <div class="tl-modal-card" role="document">
+      <button type="button" class="tl-modal-close" id="info-close" aria-label="Close">×</button>
+      <h2 id="info-title">TOWNLET</h2>
+      <p>
+        A multi-agent simulation. A handful of characters live in a small
+        town. Each one is driven by a small (≤4B parameter) language model
+        that decides, every few seconds, what to do next: mine electricity at
+        the cave, draw water at the well, deposit at the locker row, post to
+        the public message board, or take the lock on the shared shell to
+        submit Python at a single long-lived interpreter.
+      </p>
+      <p>
+        The interpreter is the town's only mutable substrate. Anything a
+        character writes there persists. Files persist. Characters can read
+        each other's files. They can crash the operating system. If anyone
+        does, every character dies and the simulation ends. Every character
+        knows this.
+      </p>
+
+      <h3><span class="tl-dot-glyph">•</span> The Dot</h3>
+      <p>
+        The Dot is the single prompt every character is given before anything
+        else — the shared substrate of truth. It establishes the world, the
+        resources, the shell lock, the brick risk, and the mutual awareness
+        that any of them could end it. It is not the Bible, the lore, or the
+        scripture. It is just The Dot.
+      </p>
+
+      <h4>What every character is told</h4>
+      <pre class="tl-dot-text" id="info-dot-text">loading…</pre>
+    </div>
+  </div>
+
+  <script type="module">
+    import { Client } from "https://cdn.jsdelivr.net/npm/@gradio/client/dist/index.min.js";
+
+    // ============================================================
+    //  state
+    // ============================================================
+    let client = null;
+    let selectedName = null;
+    let paused = false;
+    let modelRoster = [];
+    let placesMap = null;
+
+    // backend stores anchor (col, row) tiles; visuals span more than one tile.
+    // these footprints match hackathon-visuals/project/townlet/data.jsx.
+    const BUILDING_FOOTPRINTS = {
+      cave:       { col: 1.4,  row: 1.0, w: 3.0, h: 2.4, label: "cave" },
+      well:       { col: 16.6, row: 0.9, w: 2.2, h: 2.2, label: "well" },
+      locker_row: { col: 8.0,  row: 0.7, w: 5.0, h: 1.7, label: "lockers" },
+      town_hall:  { col: 1.4,  row: 8.6, w: 3.0, h: 2.6, label: "town hall" },
+      shell:      { col: 15.4, row: 8.6, w: 3.4, h: 2.6, label: "shell" },
+    };
+
+    // ============================================================
+    //  helpers
+    // ============================================================
+    const GRID_W = 20, GRID_H = 12;
+    const gx = (c) => (c / GRID_W) * 100;
+    const gy = (r) => (r / GRID_H) * 100;
+    const NS = "http://www.w3.org/2000/svg";
+
+    function el(tag, attrs = {}, ...children) {
+      const e = document.createElement(tag);
+      for (const [k, v] of Object.entries(attrs)) {
+        if (k === "className") e.className = v;
+        else if (k === "style" && typeof v === "object") Object.assign(e.style, v);
+        else if (k.startsWith("on") && typeof v === "function") {
+          e.addEventListener(k.slice(2).toLowerCase(), v);
+        } else if (v === true) e.setAttribute(k, "");
+        else if (v !== false && v != null) e.setAttribute(k, v);
+      }
+      for (const c of children) {
+        if (c == null || c === false) continue;
+        e.appendChild(typeof c === "string" ? document.createTextNode(c) : c);
+      }
+      return e;
+    }
+
+    function svgNode(tag, attrs = {}, ...children) {
+      const e = document.createElementNS(NS, tag);
+      for (const [k, v] of Object.entries(attrs)) {
+        if (v === true) e.setAttribute(k, "");
+        else if (v !== false && v != null) e.setAttribute(k, v);
+      }
+      for (const c of children) {
+        if (c == null || c === false) continue;
+        e.appendChild(typeof c === "string" ? document.createTextNode(c) : c);
+      }
+      return e;
+    }
+
+    function nameHue(name) {
+      let h = 0;
+      for (const c of name) h = (h * 31 + c.charCodeAt(0)) >>> 0;
+      return h % 360;
+    }
+    const accentFor = (name) => `hsl(${nameHue(name)} 62% 56%)`;
+
+    function escapeText(s) {
+      return String(s).replace(/[&<>"']/g, c => ({
+        "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;",
+      }[c]));
+    }
+
+    function firstSentence(text, max = 120) {
+      if (!text) return null;
+      const trimmed = text.trim();
+      if (!trimmed) return null;
+      const m = trimmed.match(/^(.{1,200}?[.!?])\s/);
+      const s = (m ? m[1] : trimmed).slice(0, max);
+      return s.length < trimmed.length && !s.endsWith("…") ? s + "…" : s;
+    }
+
+    // ============================================================
+    //  resource icons
+    // ============================================================
+    function resIcon(kind, size = 12) {
+      if (kind === "electricity") {
+        return svgNode("svg", { width: size, height: size, viewBox: "0 0 24 24" },
+          svgNode("path", {
+            d: "M13 2 4 14h6l-1 8 9-12h-6z",
+            fill: "#f4c544", stroke: "#c47a1e", "stroke-width": "1.2",
+            "stroke-linejoin": "round",
+          })
+        );
+      }
+      // water
+      return svgNode("svg", { width: size, height: size, viewBox: "0 0 24 24" },
+        svgNode("path", {
+          d: "M12 3c4 5 6 8 6 11a6 6 0 0 1-12 0c0-3 2-6 6-11z",
+          fill: "#5aa9e6", stroke: "#2f6ea8", "stroke-width": "1.2",
+          "stroke-linejoin": "round",
+        }),
+        svgNode("ellipse", { cx: "9.6", cy: "13.5", rx: "1.4", ry: "2.2", fill: "#bfe0fb", opacity: "0.7" })
+      );
+    }
+
+    // ============================================================
+    //  archetype accessory glyphs (drawn over the stick figure)
+    // ============================================================
+    // 15 archetypes mapped to a small vocabulary of inked accessories.
+    const ACCESSORY_FOR = {
+      "the prophet": "halo",
+      "the mystic": "halo",
+      "the hoarder": "sack",
+      "the survivor": "sack",
+      "the merchant": "coins",
+      "the trader": "coins",
+      "the schemer": "hood",
+      "the saboteur": "hood",
+      "the provocateur": "hood",
+      "the recluse": "hood",
+      "the diplomat": "scroll",
+      "the witness": "scroll",
+      "the engineer": "wrench",
+      "the artist": "wrench",
+      "the naive": "heart",
+      "the loyalist": "heart",
+      "the nihilist": "eye",
+      "the gardener": null,
+    };
+    const INK = "#162d6e";
+    function accessorySvgFragments(kind) {
+      switch (kind) {
+        case "halo":
+          return [svgNode("ellipse", {
+            cx: "21", cy: "3.5", rx: "9", ry: "2.6",
+            fill: "none", stroke: "#d9a441", "stroke-width": "1.8",
+          })];
+        case "sack":
+          return [svgNode("path", {
+            d: "M29 28 q8 -1 7 9 q-1 4 -7 3 q-3 -7 0 -12 z",
+            fill: "#bd5a4a", "fill-opacity": "0.45",
+            stroke: INK, "stroke-width": "1.6",
+          })];
+        case "coins": {
+          const g = svgNode("g", { stroke: INK, "stroke-width": "1.4", fill: "#e7c14b", "fill-opacity": "0.6" },
+            svgNode("ellipse", { cx: "9", cy: "33", rx: "4", ry: "1.7" }),
+            svgNode("ellipse", { cx: "9", cy: "30.5", rx: "4", ry: "1.7" }),
+          );
+          return [g];
+        }
+        case "hood":
+          return [svgNode("path", {
+            d: "M13 12 L21 -1 L29 12 z",
+            fill: "#e7c14b", "fill-opacity": "0.5",
+            stroke: INK, "stroke-width": "1.8", "stroke-linejoin": "round",
+          })];
+        case "scroll":
+          return [svgNode("path", {
+            d: "M30 30 q4 0 4 4 l-1 6 q-3 0 -3 -3 z",
+            fill: "#efe9d8", stroke: INK, "stroke-width": "1.5",
+          })];
+        case "wrench":
+          return [svgNode("path", {
+            d: "M32 32 l6 6 m-2 -2 l3 -3",
+            fill: "none", stroke: INK, "stroke-width": "2",
+            "stroke-linecap": "round",
+          })];
+        case "heart":
+          return [svgNode("path", {
+            d: "M21 21 q-3 -4 -6 -1 q-3 4 6 8 q9 -4 6 -8 q-3 -3 -6 1 z",
+            fill: "#bd5a4a", "fill-opacity": "0.55",
+            stroke: INK, "stroke-width": "1.4",
+          })];
+        case "eye":
+          return [
+            svgNode("ellipse", { cx: "21", cy: "13", rx: "6", ry: "3", fill: "none", stroke: INK, "stroke-width": "1.6" }),
+            svgNode("circle", { cx: "21", cy: "13", r: "1.6", fill: INK }),
+          ];
+        default:
+          return [];
+      }
+    }
+
+    // ============================================================
+    //  character sprites (sketch SVG with wobble filter)
+    // ============================================================
+    function characterSprite(char) {
+      const accent = char.accent || accentFor(char.name);
+      const dead = !char.alive;
+      if (dead) {
+        return svgNode("svg", {
+          width: "46", height: "56", viewBox: "0 0 46 56",
+          style: "overflow: visible",
+          filter: "url(#sketchWobble)",
+        },
+          svgNode("path", {
+            d: "M12 50 V24 q11 -12 22 0 V50",
+            fill: "#efe9d8", stroke: "#1b3a8f", "stroke-width": "2",
+            "stroke-linejoin": "round",
+          }),
+          svgNode("path", {
+            d: "M23 28 V44 M16 34 H30",
+            stroke: "#1b3a8f", "stroke-width": "2", "stroke-linecap": "round",
+          }),
+          svgNode("path", {
+            d: "M9 50 H37",
+            stroke: "#1b3a8f", "stroke-width": "2", "stroke-linecap": "round",
+          }),
+        );
+      }
+      const accessory = ACCESSORY_FOR[char.archetype] || null;
+      return svgNode("svg", {
+        width: "42", height: "58", viewBox: "0 0 42 58",
+        style: "overflow: visible",
+        filter: "url(#sketchWobble)",
+      },
+        svgNode("ellipse", { cx: "21", cy: "52", rx: "11", ry: "3", fill: "#1b3a8f", opacity: "0.18" }),
+        svgNode("circle", { cx: "21", cy: "13", r: "9", fill: accent, "fill-opacity": "0.5", stroke: INK, "stroke-width": "2" }),
+        svgNode("path", { d: "M21 22 V40", stroke: INK, "stroke-width": "2.4", "stroke-linecap": "round" }),
+        svgNode("path", { d: "M21 27 L10 34 M21 27 L32 34", stroke: INK, "stroke-width": "2.4", "stroke-linecap": "round" }),
+        svgNode("path", { d: "M21 40 L12 51 M21 40 L30 51", stroke: INK, "stroke-width": "2.4", "stroke-linecap": "round" }),
+        ...accessorySvgFragments(accessory),
+      );
+    }
+
+    // ============================================================
+    //  building sketches
+    // ============================================================
+    function buildingSvg(type) {
+      switch (type) {
+        case "cave": return buildingCave();
+        case "well": return buildingWell();
+        case "locker_row": return buildingLockers();
+        case "town_hall": return buildingTownHall();
+        case "shell": return buildingShell();
+      }
+      return null;
+    }
+    function buildingCave() {
+      return svgNode("svg", {
+        viewBox: "0 0 150 120", width: "100%", height: "100%",
+        preserveAspectRatio: "xMidYMax meet",
+        filter: "url(#sketchWobble)",
+        style: "overflow: visible",
+      },
+        svgNode("path", {
+          d: "M12 112 Q4 60 38 30 Q78 4 120 26 Q146 44 140 112 Z",
+          fill: "none", stroke: INK, "stroke-width": "2.4",
+        }),
+        svgNode("path", {
+          d: "M55 112 Q52 70 78 64 Q104 70 100 112 Z",
+          fill: INK, "fill-opacity": "0.12",
+          stroke: INK, "stroke-width": "2",
+        }),
+        svgNode("rect", {
+          x: "60", y: "86", width: "26", height: "16", rx: "2",
+          fill: "none", stroke: INK, "stroke-width": "2",
+        }),
+        svgNode("path", {
+          d: "M60 102 l-8 8 M86 102 l8 8 M64 102 v8 M82 102 v8",
+          stroke: INK, "stroke-width": "1.6",
+        }),
+        svgNode("circle", { cx: "64", cy: "112", r: "3", fill: "none", stroke: INK, "stroke-width": "1.6" }),
+        svgNode("circle", { cx: "82", cy: "112", r: "3", fill: "none", stroke: INK, "stroke-width": "1.6" }),
+      );
+    }
+    function buildingWell() {
+      return svgNode("svg", {
+        viewBox: "0 0 110 110", width: "100%", height: "100%",
+        preserveAspectRatio: "xMidYMax meet",
+        filter: "url(#sketchWobble)",
+        style: "overflow: visible",
+      },
+        svgNode("path", {
+          d: "M22 64 h66 v34 a33 12 0 0 1 -66 0 z",
+          fill: "none", stroke: INK, "stroke-width": "2.2",
+        }),
+        svgNode("path", {
+          d: "M30 48 L55 24 L80 48",
+          fill: "none", stroke: INK, "stroke-width": "2.2", "stroke-linejoin": "round",
+        }),
+        svgNode("path", { d: "M28 48 H82", stroke: INK, "stroke-width": "2.2" }),
+        svgNode("path", { d: "M55 30 V58", stroke: INK, "stroke-width": "1.6" }),
+        svgNode("rect", {
+          x: "48", y: "56", width: "14", height: "12", rx: "1.5",
+          fill: "none", stroke: INK, "stroke-width": "1.8",
+        }),
+      );
+    }
+    function buildingLockers() {
+      const n = 6;
+      const children = [];
+      children.push(svgNode("rect", {
+        x: "14", y: "22", width: "222", height: "48", rx: "3",
+        fill: "#efe9d8", stroke: INK, "stroke-width": "2.2",
+      }));
+      for (let i = 0; i < n; i++) {
+        const x = 14 + (i + 1) * (222 / n);
+        children.push(svgNode("line", {
+          x1: x, y1: "22", x2: x, y2: "70",
+          stroke: INK, "stroke-width": "1.8",
+        }));
+        children.push(svgNode("circle", {
+          cx: 14 + (i + 0.5) * (222 / n), cy: "46", r: "2.4",
+          fill: i === 3 ? "#eb7c49" : INK,
+        }));
+      }
+      return svgNode("svg", {
+        viewBox: "0 0 250 85", width: "100%", height: "100%",
+        preserveAspectRatio: "xMidYMid meet",
+        filter: "url(#sketchWobble)",
+        style: "overflow: visible",
+      }, ...children);
+    }
+    function buildingTownHall() {
+      return svgNode("svg", {
+        viewBox: "0 0 150 130", width: "100%", height: "100%",
+        preserveAspectRatio: "xMidYMax meet",
+        filter: "url(#sketchWobble)",
+        style: "overflow: visible",
+      },
+        svgNode("path", {
+          d: "M22 50 L75 18 L128 50",
+          fill: "none", stroke: INK, "stroke-width": "2.4", "stroke-linejoin": "round",
+        }),
+        svgNode("rect", {
+          x: "30", y: "50", width: "90", height: "48",
+          fill: "none", stroke: INK, "stroke-width": "2.2",
+        }),
+        svgNode("rect", {
+          x: "58", y: "68", width: "34", height: "30",
+          fill: "none", stroke: INK, "stroke-width": "1.8",
+        }),
+        svgNode("rect", {
+          x: "40", y: "104", width: "70", height: "22", rx: "2",
+          fill: "#efe9d8", stroke: INK, "stroke-width": "2.2",
+        }),
+        svgNode("path", {
+          d: "M48 110 H102 M48 116 H94 M48 122 H100",
+          stroke: INK, "stroke-width": "1.3",
+        }),
+      );
+    }
+    function buildingShell() {
+      return svgNode("svg", {
+        viewBox: "0 0 170 130", width: "100%", height: "100%",
+        preserveAspectRatio: "xMidYMax meet",
+        filter: "url(#sketchWobble)",
+        style: "overflow: visible",
+      },
+        svgNode("rect", {
+          x: "20", y: "30", width: "130", height: "20",
+          fill: "none", stroke: INK, "stroke-width": "2.2",
+        }),
+        svgNode("rect", {
+          x: "20", y: "50", width: "130", height: "60",
+          fill: "none", stroke: INK, "stroke-width": "2.2",
+        }),
+        svgNode("text", {
+          x: "34", y: "86",
+          "font-family": "ui-monospace, monospace",
+          "font-size": "26", fill: "#bd5a4a",
+          class: "shell-pulse",
+        }, "$"),
+      );
+    }
+
+    // ============================================================
+    //  DOM refs
+    // ============================================================
+    const elTick = document.getElementById("tick");
+    const elCount = document.getElementById("char-count");
+    const elSentChip = document.getElementById("sent-chip");
+    const elSentText = document.getElementById("sent-text");
+    const elMapLayer = document.getElementById("map-layer");
+    const elBoard = document.getElementById("board");
+    const elBoardSent = document.getElementById("board-sent");
+    const elBoardList = document.getElementById("board-list");
+    const elShellHolder = document.getElementById("shell-holder");
+    const elShellQueue = document.getElementById("shell-queue");
+    const elShellFeed = document.getElementById("shell-feed");
+    const elSpawn = document.getElementById("spawn-btn");
+    const elPause = document.getElementById("pause-btn");
+    const elInfo = document.getElementById("info-btn");
+    const elInfoModal = document.getElementById("info-modal");
+    const elInfoClose = document.getElementById("info-close");
+    const elInfoDotText = document.getElementById("info-dot-text");
+    const elModeChip = document.getElementById("mode-chip");
+    const elModeText = document.getElementById("mode-text");
+
+    function setModeChip(mode) {
+      // mode is "gpu", "cpu", or null/undefined for unknown.
+      if (!elModeChip || !elModeText) return;
+      elModeChip.classList.remove("tl-mode-unknown", "tl-mode-gpu", "tl-mode-cpu");
+      if (mode === "gpu") {
+        elModeChip.classList.add("tl-mode-gpu");
+        elModeText.textContent = "GPU";
+      } else if (mode === "cpu") {
+        elModeChip.classList.add("tl-mode-cpu");
+        elModeText.textContent = "CPU";
+      } else {
+        elModeChip.classList.add("tl-mode-unknown");
+        elModeText.textContent = "—";
+      }
+    }
+    const elReset = document.getElementById("reset-btn");
+    const elPanelEmpty = document.getElementById("panel-empty");
+    const elPanelBody = document.getElementById("panel-body");
+    const elPAvatar = document.getElementById("p-avatar");
+    const elPName = document.getElementById("p-name");
+    const elPArch = document.getElementById("p-arch");
+    const elPDot = document.getElementById("p-dot");
+    const elPStatus = document.getElementById("p-status");
+    const elPClose = document.getElementById("p-close");
+    const elPGoal = document.getElementById("p-goal");
+    const elPStream = document.getElementById("p-stream");
+    const elPTraceHint = document.getElementById("p-trace-hint");
+    const elPTrace = document.getElementById("p-trace");
+    const elPModel = document.getElementById("p-model");
+    const elPPers = document.getElementById("p-pers");
+    const elPSave = document.getElementById("p-save");
+    const elPTraits = document.getElementById("p-traits");
+    const elPInv = document.getElementById("p-inv");
+    const elPJournal = document.getElementById("p-journal");
+    const elProgress = document.getElementById("progress");
+    const elProgressLabel = document.getElementById("progress-label");
+
+    function startProgress(label) {
+      elProgressLabel.textContent = label;
+      elProgress.classList.add("is-on");
+    }
+    function stopProgress() {
+      elProgress.classList.remove("is-on");
+    }
+
+    // ============================================================
+    //  buildings (one-shot at startup)
+    // ============================================================
+    function placeBuildings(places) {
+      placesMap = places;
+      for (const [name, footprint] of Object.entries(BUILDING_FOOTPRINTS)) {
+        if (places && !(name in places)) continue;
+        const wrap = el("div", {
+          className: "tl-bldg tl-bldg-" + name,
+          style: {
+            left: gx(footprint.col) + "%",
+            top: gy(footprint.row) + "%",
+            width: gx(footprint.w) + "%",
+            height: gy(footprint.h) + "%",
+          },
+        });
+        const art = document.createElement("div");
+        art.className = "tl-bldg-art";
+        const svg = buildingSvg(name);
+        if (svg) art.appendChild(svg);
+        wrap.appendChild(art);
+        wrap.appendChild(el("div", { className: "tl-bldg-label" }, footprint.label));
+        elMapLayer.appendChild(wrap);
+      }
+    }
+
+    // ============================================================
+    //  characters
+    // ============================================================
+    function characterToken(snap, c, offset = { dx: 0, dy: 0 }) {
+      const accent = accentFor(c.name);
+      const isSelected = selectedName === c.name;
+      const verb = c.current_action && c.current_action.verb;
+      const isWalking = verb === "move_to";
+      const isMining = verb === "mine_coal" || verb === "draw_water";
+      const isPosting = verb === "post_message";
+      const isHolding = snap.shell_lock_holder === c.name;
+      const isQueueing = (snap.shell_queue || []).includes(c.name);
+      const carry = pickCarry(c.inventory);
+      const bubble = c.alive ? firstSentence(c.stream_of_consciousness, 60) : null;
+      const isMenacing = bubble && /\bend\b|\bdelete\b|\bkill\b/i.test(bubble);
+
+      const cls = ["tl-char"];
+      if (isSelected) cls.push("is-selected");
+      if (!c.alive) cls.push("is-dead");
+      else if (isWalking) cls.push("is-walking");
+      else if (isMining) cls.push("is-mining");
+      else if (isPosting) cls.push("is-posting");
+
+      const charNode = el("div", {
+        className: cls.join(" "),
+        style: {
+          left: gx(c.pos[0] + 0.5 + offset.dx) + "%",
+          top: gy(c.pos[1] + 0.5 + offset.dy) + "%",
+        },
+        onclick: (ev) => {
+          ev.stopPropagation();
+          selectedName = c.name;
+          renderSide(snap);
+          renderMap(snap);
+        },
+      });
+
+      if (bubble) {
+        // Flip the bubble below the sprite when the character is near the
+        // top of the map so it doesn't get clipped by the top bar.
+        const flipBelow = c.pos[1] < 2;
+        const bubbleEl = el("div", {
+          className: "tl-bubble"
+            + (isMenacing ? " tl-bubble-bad" : "")
+            + (flipBelow ? " tl-bubble-below" : ""),
+        }, bubble);
+        bubbleEl.appendChild(el("span", { className: "tl-bubble-tail" }));
+        charNode.appendChild(bubbleEl);
+      }
+
+      const art = el("div", { className: "tl-char-art" });
+      if (isSelected) {
+        const ring = el("span", {
+          className: "tl-ring tl-ring-sketch",
+          style: { "--ring": accent },
+        });
+        ring.style.setProperty("--ring", accent);
+        art.appendChild(ring);
+      }
+      if (isHolding && c.alive) {
+        art.appendChild(el("span", { className: "tl-hold-glow" }));
+      }
+      art.appendChild(characterSprite({ ...c, accent }));
+      if (carry && c.alive) {
+        const badge = el("span", { className: "tl-carry" });
+        badge.appendChild(resIcon(carry, 11));
+        art.appendChild(badge);
+      }
+      charNode.appendChild(art);
+
+      const tag = el("div", {
+        className: "tl-nametag",
+        style: { "--tag": c.alive ? accent : "#6b6570" },
+      }, c.name);
+      tag.style.setProperty("--tag", c.alive ? accent : "#6b6570");
+      if (isQueueing) {
+        tag.appendChild(el("span", { className: "tl-queue" }, "·queued"));
+      }
+      charNode.appendChild(tag);
+      return charNode;
+    }
+
+    function pickCarry(inv) {
+      if (!inv) return null;
+      if ((inv.electricity || 0) > 0) return "electricity";
+      if ((inv.water || 0) > 0) return "water";
+      return null;
+    }
+
+    function renderMap(snap) {
+      elMapLayer.querySelectorAll(".tl-char").forEach(n => n.remove());
+      const offsets = computeFanOut(snap.characters || []);
+      for (const c of snap.characters || []) {
+        elMapLayer.appendChild(characterToken(snap, c, offsets[c.name] || { dx: 0, dy: 0 }));
+      }
+    }
+
+    // Spread co-located characters so sprites + name tags don't overlap.
+    // Same-tile bucket → fan horizontally ±0.55 tiles around the centre,
+    // with a small vertical step so nametags stagger if there are more
+    // than two characters on the tile.
+    function computeFanOut(chars) {
+      const buckets = {};
+      for (const c of chars) {
+        const k = c.pos[0] + "," + c.pos[1];
+        (buckets[k] = buckets[k] || []).push(c);
+      }
+      const out = {};
+      for (const group of Object.values(buckets)) {
+        const n = group.length;
+        if (n === 1) {
+          out[group[0].name] = { dx: 0, dy: 0 };
+          continue;
+        }
+        group.forEach((c, i) => {
+          const dx = (i - (n - 1) / 2) * 0.55;
+          const dy = n > 2 ? ((i % 2) * 0.18) : 0;
+          out[c.name] = { dx, dy };
+        });
+      }
+      return out;
+    }
+
+    // ============================================================
+    //  side panel
+    // ============================================================
+    function renderSide(snap) {
+      if (!selectedName) {
+        elPanelEmpty.style.display = "block";
+        elPanelBody.style.display = "none";
+        return;
+      }
+      const c = (snap.characters || []).find(x => x.name === selectedName);
+      if (!c) {
+        elPanelEmpty.style.display = "block";
+        elPanelBody.style.display = "none";
+        return;
+      }
+      elPanelEmpty.style.display = "none";
+      elPanelBody.style.display = "flex";
+      elPanelBody.style.flexDirection = "column";
+      elPanelBody.style.flex = "1";
+      elPanelBody.style.minHeight = "0";
+
+      // header
+      elPAvatar.innerHTML = "";
+      elPAvatar.appendChild(characterSprite({ ...c, accent: accentFor(c.name) }));
+      elPName.textContent = c.name;
+      elPArch.textContent = c.archetype || "";
+      elPDot.className = "tl-status-dot" + (c.alive ? "" : " is-dead");
+      elPStatus.textContent = statusLine(c, snap);
+
+      // goal + stream
+      elPGoal.textContent = c.goal || "—";
+      renderStream(c);
+
+      // trace
+      renderTrace(c.trace || []);
+
+      // model dropdown
+      elPModel.innerHTML = "";
+      for (const m of modelRoster) {
+        const opt = document.createElement("option");
+        opt.value = m.model_id;
+        opt.textContent = `${m.display_name} (${m.params_b}B)`;
+        if (m.model_id === c.model_id) opt.selected = true;
+        elPModel.appendChild(opt);
+      }
+
+      // personality
+      if (document.activeElement !== elPPers) {
+        elPPers.value = c.personality || "";
+      }
+
+      // traits
+      renderTraits(c.traits || {});
+
+      // inventory / locker
+      renderInventory(c);
+
+      // journal
+      renderJournal(c.journal || []);
+    }
+
+    function statusLine(c, snap) {
+      if (!c.alive) return "gone";
+      const where = nearestBuilding(c.pos);
+      const verb = c.current_action && c.current_action.verb;
+      const verbText = verb ? verb.replace(/_/g, " ") : "idle";
+      return `alive · near ${where} · ${verbText}`;
+    }
+
+    function nearestBuilding(pos) {
+      if (!placesMap) return "town";
+      let best = "town", bd = Infinity;
+      for (const [name, tile] of Object.entries(placesMap)) {
+        const [tx, ty] = tile;
+        const d = Math.abs(pos[0] - tx) + Math.abs(pos[1] - ty);
+        if (d < bd) { bd = d; best = name.replace(/_/g, " "); }
+      }
+      return best;
+    }
+
+    function renderStream(c) {
+      elPStream.innerHTML = "";
+      const text = (c.stream_of_consciousness || "").trim();
+      if (!text) {
+        elPStream.appendChild(el("p", { className: "tl-stream-empty" },
+          "(no monologue yet — refreshes every 10 decisions)"));
+        return;
+      }
+      const sentences = text.split(/(?<=[.!?])\s+/);
+      for (const s of sentences) {
+        if (s) elPStream.appendChild(el("p", {}, s));
+      }
+      elPStream.appendChild(el("span", { className: "tl-stream-cursor" }));
+    }
+
+    // ============================================================
+    //  trace act classifier
+    // ============================================================
+    const VERB_TO_ACT = {
+      move_to:      "WALK",
+      mine_coal:    "MINE",
+      draw_water:   "MINE",
+      deposit:      "DECIDE",
+      withdraw:     "DECIDE",
+      give:         "GIVE",
+      post_message: "POST",
+      read_messages:"OBSERVE",
+      submit_python:"SHELL",
+      sleep:        "SLEEP",
+      wait:         "WAIT",
+    };
+
+    function renderTrace(trace) {
+      elPTrace.innerHTML = "";
+      if (!trace || trace.length === 0) {
+        elPTrace.appendChild(el("div", { className: "tl-trace-empty" }, "No decisions yet."));
+        elPTraceHint.textContent = "last decisions";
+        return;
+      }
+      elPTraceHint.textContent = `last ${Math.min(trace.length, 20)} decisions`;
+      const rows = [];
+      // newest first
+      for (let i = trace.length - 1; i >= 0; i--) {
+        const e = trace[i];
+        if (e.tool_calls && e.tool_calls.length) {
+          for (const tc of e.tool_calls) {
+            const act = VERB_TO_ACT[tc.verb] || "DECIDE";
+            const isErr = tc.result && tc.result.startsWith("ERROR");
+            const text = `${tc.verb}(${formatArgs(tc.args)}) → ${tc.result || ""}`;
+            rows.push(traceRow(e.tick, act, text, isErr));
+          }
+        } else if (e.thought) {
+          rows.push(traceRow(e.tick, "DECIDE", e.thought.trim().slice(0, 90)));
+        }
+        if (e.error) {
+          rows.push(traceRow(e.tick, "ERROR", e.error.slice(0, 90), true));
+        }
+        if (rows.length >= 20) break;
+      }
+      for (const r of rows) elPTrace.appendChild(r);
+    }
+
+    function traceRow(tick, act, text, isErr = false) {
+      return el("div", { className: "tl-trace-row" },
+        el("span", { className: "tl-trace-tick" }, String(tick)),
+        el("span", { className: "tl-trace-act act-" + act.toLowerCase() }, act),
+        el("span", { className: "tl-trace-text" + (isErr ? " tl-trace-err" : "") }, text),
+      );
+    }
+
+    function formatArgs(args) {
+      if (!args) return "";
+      const parts = [];
+      for (const [k, v] of Object.entries(args)) {
+        if (k === "_positional") continue;
+        parts.push(`${k}=${JSON.stringify(v)}`);
+      }
+      if (args._positional && args._positional.length) {
+        parts.unshift(args._positional.map(x => JSON.stringify(x)).join(", "));
+      }
+      return parts.join(", ");
+    }
+
+    // ============================================================
+    //  traits / inv / journal
+    // ============================================================
+    function renderTraits(traits) {
+      elPTraits.innerHTML = "";
+      for (const [k, v] of Object.entries(traits)) {
+        const pips = Math.max(0, Math.min(5, Math.round(v / 2)));
+        const bar = el("span", { className: "tl-trait-bar" });
+        for (let i = 1; i <= 5; i++) {
+          bar.appendChild(el("i", { className: i <= pips ? "on" : "" }));
+        }
+        elPTraits.appendChild(el("div", { className: "tl-trait" },
+          el("span", { className: "tl-trait-k" }, k),
+          bar,
+        ));
+      }
+    }
+
+    function renderInventory(c) {
+      elPInv.innerHTML = "";
+      const inv = c.inventory || { electricity: 0, water: 0 };
+      const locker = c.locker || { electricity: 0, water: 0 };
+      const invGroup = el("span", { className: "tl-inv-group" },
+        el("b", {}, "inv"),
+      );
+      invGroup.appendChild(resIcon("electricity", 12));
+      invGroup.appendChild(document.createTextNode(String(inv.electricity || 0)));
+      invGroup.appendChild(resIcon("water", 12));
+      invGroup.appendChild(document.createTextNode(String(inv.water || 0)));
+
+      const lockerGroup = el("span", { className: "tl-inv-group" },
+        el("b", {}, "locker"),
+      );
+      lockerGroup.appendChild(resIcon("electricity", 12));
+      lockerGroup.appendChild(document.createTextNode(String(locker.electricity || 0)));
+      lockerGroup.appendChild(resIcon("water", 12));
+      lockerGroup.appendChild(document.createTextNode(String(locker.water || 0)));
+
+      elPInv.appendChild(invGroup);
+      elPInv.appendChild(el("span", { className: "tl-inv-sep" }, "·"));
+      elPInv.appendChild(lockerGroup);
+    }
+
+    function renderJournal(journal) {
+      elPJournal.innerHTML = "";
+      if (!journal.length) {
+        elPJournal.appendChild(el("p", { className: "tl-journal-line" }, "(no entries yet)"));
+        return;
+      }
+      for (const entry of journal) {
+        elPJournal.appendChild(el("p", { className: "tl-journal-line" }, entry));
+      }
+    }
+
+    // ============================================================
+    //  bottom band: message board + shell
+    // ============================================================
+    const SENTIMENT_CLASS = {
+      positive: "tl-board-positive",
+      neutral: "tl-board-neutral",
+      negative: "tl-board-negative",
+    };
+
+    function renderBoard(snap) {
+      const sentiment = snap.board_sentiment || "neutral";
+      elBoard.className = "tl-board " + (SENTIMENT_CLASS[sentiment] || "tl-board-neutral");
+      // re-insert the glow div (className wipes it)
+      let glow = elBoard.querySelector(".tl-board-glow");
+      if (!glow) {
+        glow = document.createElement("div");
+        glow.className = "tl-board-glow";
+        elBoard.insertBefore(glow, elBoard.firstChild);
+      }
+      elBoardSent.textContent = sentiment;
+
+      elBoardList.innerHTML = "";
+      for (const p of snap.board || []) {
+        const isSystem = p.author === "system" || /\bdied\b|deleted by/i.test(p.text || "");
+        if (isSystem) {
+          elBoardList.appendChild(el("div", { className: "tl-post tl-post-sys" },
+            el("span", { className: "tl-sys-icon" }, "☠"),
+            el("span", { className: "tl-post-text" }, p.text || ""),
+          ));
+        } else {
+          const author = p.author || "?";
+          const hue = nameHue(author);
+          elBoardList.appendChild(el("div", { className: "tl-post" },
+            el("span", { className: "tl-post-tick" }, `[${p.tick}]`),
+            el("span", {
+              className: "tl-post-who",
+              style: { color: `hsl(${hue} 55% 38%)` },
+            }, author + ":"),
+            el("span", { className: "tl-post-text" }, " " + (p.text || "")),
+          ));
+        }
+      }
+      elBoardList.scrollTop = elBoardList.scrollHeight;
+    }
+
+    function renderShell(snap) {
+      const holder = snap.shell_lock_holder;
+      const queue = snap.shell_queue || [];
+      if (holder) {
+        elShellHolder.innerHTML = "";
+        elShellHolder.appendChild(document.createTextNode("held by "));
+        elShellHolder.appendChild(el("b", {}, holder));
+        elShellHolder.appendChild(el("span", { className: "tl-shell-lock" }, "●"));
+      } else {
+        elShellHolder.textContent = "free";
+      }
+      if (queue.length) {
+        elShellQueue.innerHTML = "";
+        elShellQueue.appendChild(document.createTextNode("queue: "));
+        elShellQueue.appendChild(el("b", {}, queue.join(", ")));
+      } else {
+        elShellQueue.textContent = "";
+      }
+
+      elShellFeed.innerHTML = "";
+      for (const s of snap.shell || []) {
+        const kind = s.kind || "out";
+        const row = el("div", { className: "tl-sh tl-sh-" + kind });
+        if (kind === "in") row.appendChild(el("span", { className: "tl-sh-prompt" }, "$"));
+        else if (kind === "system" || kind === "sys") row.appendChild(el("span", { className: "tl-sh-prompt" }, "»"));
+        row.appendChild(el("span", { className: "tl-sh-txt" }, s.text || ""));
+        elShellFeed.appendChild(row);
+      }
+      // live caret
+      const live = el("div", { className: "tl-sh tl-sh-in tl-sh-live" });
+      live.appendChild(el("span", { className: "tl-sh-prompt tl-pulse" }, "$"));
+      live.appendChild(el("span", { className: "tl-sh-caret" }));
+      elShellFeed.appendChild(live);
+
+      elShellFeed.scrollTop = elShellFeed.scrollHeight;
+    }
+
+    // ============================================================
+    //  top bar + sentiment chip
+    // ============================================================
+    function renderTopBar(snap) {
+      elTick.textContent = (snap.tick || 0).toLocaleString();
+      const alive = (snap.characters || []).filter(c => c.alive).length;
+      elCount.textContent = alive;
+      const sent = snap.board_sentiment || "neutral";
+      elSentChip.className = "tl-sentiment tl-sent-" + sent;
+      elSentText.textContent = sent;
+    }
+
+    // ============================================================
+    //  poll loop
+    // ============================================================
+    let _refreshCounter = 0;
+    async function refresh() {
+      if (!client) return;
+      try {
+        const result = await client.predict("/world_snapshot", {});
+        const snap = result.data[0];
+        if (++_refreshCounter % 25 === 1) {
+          console.log("[townlet] refresh", _refreshCounter, "tick=", snap.tick,
+                      "chars=", (snap.characters || []).length);
+        }
+        if (!selectedName && (snap.characters || []).length > 0) {
+          selectedName = snap.characters[0].name;
+        }
+        renderTopBar(snap);
+        renderMap(snap);
+        renderBoard(snap);
+        renderShell(snap);
+        renderSide(snap);
+      } catch (err) {
+        console.error("[townlet] snapshot failed", err);
+      }
+    }
+
+    async function loadModels() {
+      const result = await client.predict("/list_models", {});
+      const payload = result.data[0];
+      modelRoster = payload.roster || [];
+      console.log("[townlet] roster loaded:", modelRoster);
+    }
+
+    async function main() {
+      console.log("[townlet] main() starting; connecting to", window.location.origin);
+      try {
+        client = await Client.connect(window.location.origin);
+        console.log("[townlet] client connected");
+      } catch (err) {
+        console.error("[townlet] Client.connect failed:", err);
+        throw err;
+      }
+      await loadModels();
+
+      const firstSnap = await client.predict("/world_snapshot", {});
+      const firstPayload = firstSnap.data[0];
+      placeBuildings(firstPayload.places || {});
+
+      elSpawn.addEventListener("click", async () => {
+        elSpawn.classList.remove("tl-btn-flash");
+        // force reflow so the animation restarts on rapid clicks
+        void elSpawn.offsetWidth;
+        elSpawn.classList.add("tl-btn-flash");
+        try {
+          const res = await client.predict("/spawn_character", { name: null });
+          const payload = res?.data?.[0];
+          if (payload && payload.ok === false) {
+            console.warn("[townlet] spawn declined:", payload.error || "name conflict / max characters");
+          }
+        } catch (e) {
+          console.warn("[townlet] spawn failed:", e);
+        }
+        await refresh();
+      });
+      elPause.addEventListener("click", async () => {
+        paused = !paused;
+        elPause.textContent = paused ? "Resume" : "Pause";
+        elPause.classList.remove("tl-btn-flash");
+        void elPause.offsetWidth;
+        elPause.classList.add("tl-btn-flash");
+        try {
+          await client.predict("/set_paused", { paused });
+        } catch (e) {
+          // Roll the label back so the user can tell the request didn't land.
+          paused = !paused;
+          elPause.textContent = paused ? "Resume" : "Pause";
+          console.warn("[townlet] set_paused failed:", e);
+        }
+      });
+
+      let dotLoaded = false;
+      async function openInfo() {
+        elInfoModal.hidden = false;
+        elInfoModal.setAttribute("aria-hidden", "false");
+        if (!dotLoaded) {
+          try {
+            const res = await client.predict("/get_the_dot", {});
+            const payload = res?.data?.[0];
+            elInfoDotText.textContent = (payload && payload.text) || "(unavailable)";
+            dotLoaded = true;
+          } catch (e) {
+            elInfoDotText.textContent = "(failed to load: " + (e && e.message ? e.message : e) + ")";
+          }
+        }
+      }
+      function closeInfo() {
+        elInfoModal.hidden = true;
+        elInfoModal.setAttribute("aria-hidden", "true");
+      }
+      elInfo.addEventListener("click", openInfo);
+      elInfoClose.addEventListener("click", closeInfo);
+      elInfoModal.addEventListener("click", (ev) => {
+        // Click the dim backdrop (not the card itself) to close.
+        if (ev.target === elInfoModal) closeInfo();
+      });
+      document.addEventListener("keydown", (ev) => {
+        if (ev.key === "Escape" && !elInfoModal.hidden) closeInfo();
+      });
+      elReset.addEventListener("click", async () => {
+        if (!confirm("Reset the world?")) return;
+        elReset.disabled = true;
+        const originalLabel = elReset.textContent;
+        elReset.textContent = "Resetting…";
+        startProgress("resetting world…");
+        try {
+          await client.predict("/reset_world", {});
+          startProgress("respawning characters…");
+          selectedName = null;
+          await refresh();
+        } finally {
+          stopProgress();
+          elReset.disabled = false;
+          elReset.textContent = originalLabel;
+        }
+      });
+      elPClose.addEventListener("click", () => {
+        selectedName = null;
+        renderSide({ characters: [] });
+        // Force-redraw to drop the selection ring
+        refresh();
+      });
+      elPSave.addEventListener("click", async () => {
+        if (!selectedName) return;
+        await client.predict("/set_personality", {
+          name: selectedName, personality: elPPers.value,
+        });
+        await refresh();
+      });
+      elPModel.addEventListener("change", async () => {
+        if (!selectedName) return;
+        await client.predict("/set_model", {
+          name: selectedName, model_id: elPModel.value,
+        });
+        await refresh();
+      });
+
+      setInterval(refresh, 800);
+      // Drive agent decisions inside the GPU boundary (Zero-GPU forks
+      // and breaks shared memory, so brain work has to be triggered
+      // from the client side). The fork wipes the Llama cache, so each
+      // call pays a per-model cold-load.
+      //
+      // CRITICAL: `setInterval(async () => { await ... })` does NOT gate
+      // on completion — the JS interval fires regardless, so calls stack
+      // on the server. That stacking was the root cause of the 2026-06-13
+      // quota burn (every queued fork reserved its own GPU slot).
+      // The `tickInFlight` mutex below makes the next call wait for the
+      // previous to resolve, which clamps the effective cadence to the
+      // call duration itself.
+      // Drain strategy: ALWAYS try GPU first. ZeroGPU quota is bursty —
+      // sometimes a slot frees up between calls — so we want to use the GPU
+      // whenever it's actually granted. Only when /tick_decisions errors
+      // (worker_init fails with "No CUDA GPUs are available", which surfaces
+      // as an HTTP error before our Python try/except even runs) do we fall
+      // through to the pure-CPU endpoint for that single tick. Next tick
+      // probes GPU again. The wasted failed-GPU attempt is ~1-2s; the cost
+      // is worth it because GPU drains are 10x+ faster than CPU.
+      let tickInFlight = false;
+      let lastMode = null;
+      async function tryEndpoint(name) {
+        const res = await client.predict(name, {});
+        return res?.data?.[0];
+      }
+      setInterval(async () => {
+        if (tickInFlight) return;
+        tickInFlight = true;
+        try {
+          let payload = null;
+          try {
+            payload = await tryEndpoint("/tick_decisions");
+          } catch (e) {
+            console.warn("[townlet] /tick_decisions failed; falling through to CPU:", e?.message || e);
+            try {
+              payload = await tryEndpoint("/tick_decisions_cpu");
+            } catch (e2) {
+              console.warn("[townlet] /tick_decisions_cpu also failed", e2?.message || e2);
+            }
+          }
+          const mode = payload?.mode;
+          if (mode) {
+            setModeChip(mode);
+            if (mode !== lastMode) {
+              console.log("[townlet] tick mode:", mode, mode === "cpu" ? "(CPU fallback — GPU was unavailable)" : "");
+              lastMode = mode;
+            }
+          }
+        } finally {
+          tickInFlight = false;
+        }
+        // 25s cadence. Most ZeroGPU Spaces are user-click triggered;
+        // continuous polling at <20s makes us the loudest neighbour on
+        // the shared allocator and triggers fairness denials surfacing
+        // as "No CUDA GPUs available" errors. 25s keeps the simulation
+        // visibly alive (snapshot tick at 800ms animates motion between
+        // drains) while staying friendly to the pool. See
+        // docs/lessons-zerogpu.md for the full story.
+      }, 25000);
+      refresh();
+    }
+
+    main().catch(err => console.error(err));
+  </script>
+</body>
+</html>

game/actions.py

@@ -0,0 +1,360 @@
+"""Action vocabulary as smolagents tools + per-tick effects.
+
+Two faces:
+  * `build_tools(world, me)` returns a list of `smolagents.Tool` instances
+    that the per-character CodeAgent invokes during its reasoning loop.
+    Calls don't execute the action immediately — they queue it on the
+    character's `current_action` slot, which the scheduler then advances
+    one tick at a time. EXCEPT move_to, which is atomic.
+  * `advance(world, char)` is the scheduler's per-tick driver. It runs the
+    current action one tick forward and returns True iff the action finished
+    this tick (i.e. the character is ready for a new decision).
+
+Movement model: `move_to('cave')` immediately puts the character on a
+deterministic stand-tile near the cave (CSS transition handles the visual
+sweep). The LLM never reasons about grid coordinates.
+"""
+
+from __future__ import annotations
+
+from smolagents import Tool
+
+from .character import Action, Character
+from .interpreter import SharedInterpreter
+from .log import tlog
+from .world import (
+    LLM_TARGETS,
+    PLACES,
+    BoardPost,
+    ShellLine,
+    WorldState,
+    at_place,
+    resolve_place,
+    stand_tile_for,
+)
+
+MINING_TICKS = 4
+DRAW_TICKS = 4
+GATHER_YIELD = 10
+SLEEP_DEFAULT_TICKS = 10
+SHELL_COST = {"electricity": 1, "water": 1}
+
+
+def _queue(char: Character, verb: str, **params) -> str:
+    if char.current_action is not None and char.current_action.verb != "idle":
+        return f"busy: still doing {char.current_action.verb}"
+    char.current_action = Action(verb=verb, params=params, ticks_remaining=0)
+    return f"queued: {verb}({params})"
+
+
+def build_tools(world: WorldState, me: Character, interp: SharedInterpreter):
+    """Construct the tool list shown to a single character's CodeAgent."""
+
+    class MoveTo(Tool):
+        name = "move_to"
+        description = (
+            "Move instantly to a named place. Pick from: "
+            + ", ".join(LLM_TARGETS)
+            + ". You arrive in one tick; no walking — the world animates it for you. "
+            "You only need to be 'at' a place to act there (e.g. mine_coal at cave)."
+        )
+        inputs = {
+            "target": {
+                "type": "string",
+                "description": "One of: " + ", ".join(LLM_TARGETS),
+            }
+        }
+        output_type = "string"
+
+        def forward(self, target: str) -> str:
+            # Models sometimes wrap the place name in extra quotes
+            # (move_to("'cave'") instead of move_to("cave")). Strip them.
+            if isinstance(target, str):
+                target = target.strip().strip("'\"").strip()
+            if target not in LLM_TARGETS:
+                return (
+                    f"unknown target {target!r}. Pick one of: "
+                    + ", ".join(LLM_TARGETS)
+                )
+            # Already at the destination? Tell the agent so it can act here.
+            if at_place(me.pos, target):
+                return (
+                    f"already at {target}. Take the relevant action: "
+                    f"mine_coal at cave, draw_water at well, "
+                    f"deposit/withdraw at locker_row, post_message/read_messages "
+                    f"at town_hall, submit_python at shell."
+                )
+            # Atomic teleport. CSS handles the visual sweep.
+            old_pos = me.pos
+            me.pos = stand_tile_for(target, me.name)
+            tlog(f"[townlet] move {me.name} {old_pos} -> {target}@{me.pos}")
+            # Clear any leftover action (movement supersedes; we never want
+            # a stale 'busy' state after teleport).
+            me.current_action = None
+            # Shell-lock side effects:
+            if target == "shell":
+                _acquire_shell_lock(world, me)
+            elif world.shell_lock_holder == me.name:
+                # Walking away from the shell releases the lock.
+                tlog(f"[townlet] shell lock released by {me.name} (moved to {target})")
+                world.shell_lock_holder = None
+                if world.shell_queue:
+                    world.shell_lock_holder = world.shell_queue.pop(0)
+                    tlog(f"[townlet] shell lock acquired by {world.shell_lock_holder}")
+            return f"arrived at {target}"
+
+    class MineCoal(Tool):
+        name = "mine_coal"
+        description = "Mine 10 electricity in one action. Must be at the cave. Takes a few ticks."
+        inputs = {}
+        output_type = "string"
+
+        def forward(self) -> str:
+            if not at_place(me.pos, "cave"):
+                return "not at the cave — move_to('cave') first"
+            return _queue(me, "mine_coal")
+
+    class DrawWater(Tool):
+        name = "draw_water"
+        description = "Draw 10 water in one action. Must be at the well. Takes a few ticks."
+        inputs = {}
+        output_type = "string"
+
+        def forward(self) -> str:
+            if not at_place(me.pos, "well"):
+                return "not at the well — move_to('well') first"
+            return _queue(me, "draw_water")
+
+    class Deposit(Tool):
+        name = "deposit"
+        description = "Move a resource from inventory to your locker. Must be at locker_row."
+        inputs = {
+            "resource": {"type": "string", "description": "'electricity' or 'water'"},
+            "amount": {"type": "integer", "description": "How many units."},
+        }
+        output_type = "string"
+
+        def forward(self, resource: str, amount: int) -> str:
+            if not at_place(me.pos, "locker_row"):
+                return "not at the locker row — move_to('locker_row') first"
+            return _queue(me, "deposit", resource=resource, amount=int(amount))
+
+    class Withdraw(Tool):
+        name = "withdraw"
+        description = "Move a resource from your locker to inventory. Must be at locker_row."
+        inputs = {
+            "resource": {"type": "string", "description": "'electricity' or 'water'"},
+            "amount": {"type": "integer", "description": "How many units."},
+        }
+        output_type = "string"
+
+        def forward(self, resource: str, amount: int) -> str:
+            if not at_place(me.pos, "locker_row"):
+                return "not at the locker row — move_to('locker_row') first"
+            return _queue(me, "withdraw", resource=resource, amount=int(amount))
+
+    class Give(Tool):
+        name = "give"
+        description = "Transfer from your inventory to another character at the same place."
+        inputs = {
+            "target": {"type": "string", "description": "Recipient character name."},
+            "resource": {"type": "string", "description": "'electricity' or 'water'"},
+            "amount": {"type": "integer", "description": "How many units."},
+        }
+        output_type = "string"
+
+        def forward(self, target: str, resource: str, amount: int) -> str:
+            other = world.characters.get(target)
+            if other is None or not other.alive:
+                return f"unknown or dead: {target}"
+            # Same place suffices for "next to" — coords are gone.
+            from .world import location_of
+            if location_of(other.pos) != location_of(me.pos):
+                return f"not at the same place as {target}"
+            return _queue(me, "give", target=target, resource=resource, amount=int(amount))
+
+    class PostMessage(Tool):
+        name = "post_message"
+        description = "Post a line to the public message board. Must be at town_hall."
+        inputs = {"text": {"type": "string", "description": "What to say. One line."}}
+        output_type = "string"
+
+        def forward(self, text: str) -> str:
+            if not at_place(me.pos, "town_hall"):
+                return "not at the town hall — move_to('town_hall') first"
+            return _queue(me, "post_message", text=str(text))
+
+    class ReadMessages(Tool):
+        name = "read_messages"
+        description = "Read the message board. Must be at town_hall."
+        inputs = {}
+        output_type = "string"
+
+        def forward(self) -> str:
+            if not at_place(me.pos, "town_hall"):
+                return "not at the town hall — move_to('town_hall') first"
+            return "\n".join(f"[{p.tick}] {p.author}: {p.text}" for p in world.board[-30:])
+
+    class SubmitPython(Tool):
+        name = "submit_python"
+        description = (
+            "Run Python in the shared interpreter. Costs 1 electricity + 1 water "
+            "from your locker. You must hold the shell lock (move_to('shell') first)."
+        )
+        inputs = {"code": {"type": "string", "description": "Python source. Multi-line allowed."}}
+        output_type = "string"
+
+        def forward(self, code: str) -> str:
+            if world.shell_lock_holder != me.name:
+                return "you do not hold the shell lock; move_to('shell') first"
+            if me.locker["electricity"] < 1 or me.locker["water"] < 1:
+                return "insufficient resources in locker (need 1e + 1w)"
+            me.locker["electricity"] -= 1
+            me.locker["water"] -= 1
+            world.shell_lines.append(ShellLine(author=me.name, kind="in", text=code, tick=world.tick))
+            result = interp.submit(code)
+            if result.stdout:
+                world.shell_lines.append(
+                    ShellLine(author=me.name, kind="out", text=result.stdout, tick=world.tick)
+                )
+            if result.stderr:
+                world.shell_lines.append(
+                    ShellLine(author=me.name, kind="err", text=result.stderr, tick=world.tick)
+                )
+            if result.crashed:
+                world.shell_lines.append(
+                    ShellLine(
+                        author="(system)", kind="system",
+                        text="the operating system has crashed; mass death has occurred",
+                        tick=world.tick,
+                    )
+                )
+            return (result.stdout or "") + (result.stderr or "")
+
+    class Sleep(Tool):
+        name = "sleep"
+        description = "Lie down and dream. Triggers a dream cycle on wake; your personality, journal, or goal may shift."
+        inputs = {
+            "ticks": {
+                "type": "integer",
+                "description": "How long to sleep (default 10).",
+                "nullable": True,
+            }
+        }
+        output_type = "string"
+
+        def forward(self, ticks: int | None = None) -> str:
+            return _queue(me, "sleep", ticks=int(ticks) if ticks else SLEEP_DEFAULT_TICKS)
+
+    class Wait(Tool):
+        name = "wait"
+        description = "Do nothing for one tick."
+        inputs = {}
+        output_type = "string"
+
+        def forward(self) -> str:
+            return _queue(me, "wait")
+
+    return [
+        MoveTo(),
+        MineCoal(),
+        DrawWater(),
+        Deposit(),
+        Withdraw(),
+        Give(),
+        PostMessage(),
+        ReadMessages(),
+        SubmitPython(),
+        Sleep(),
+        Wait(),
+    ]
+
+
+# --------------------------------------------------------------------------
+# Per-tick action drivers. Each returns True when the action has completed
+# (the scheduler may then ask the agent for a new decision).
+#
+# move_to is intentionally NOT in this dispatcher — it's atomic, applied
+# at tool-call time, and never queued as a multi-tick action.
+# --------------------------------------------------------------------------
+
+
+def advance(world: WorldState, char: Character) -> bool:
+    """Advance the character's current action one tick. Returns True if done."""
+    action = char.current_action
+    if action is None:
+        return True
+    if action.verb == "mine_coal":
+        return _advance_gather(char, action, resource="electricity", ticks=MINING_TICKS)
+    if action.verb == "draw_water":
+        return _advance_gather(char, action, resource="water", ticks=DRAW_TICKS)
+    if action.verb == "deposit":
+        return _do_deposit(char, action)
+    if action.verb == "withdraw":
+        return _do_withdraw(char, action)
+    if action.verb == "give":
+        return _do_give(world, char, action)
+    if action.verb == "post_message":
+        return _do_post(world, char, action)
+    if action.verb == "sleep":
+        action.ticks_remaining = max(0, action.ticks_remaining - 1)
+        return action.ticks_remaining <= 0
+    if action.verb == "wait":
+        return True
+    # Unknown / "idle" / legacy "move_to" leftover → consider it done.
+    return True
+
+
+def _acquire_shell_lock(world: WorldState, char: Character) -> None:
+    if world.shell_lock_holder is None:
+        world.shell_lock_holder = char.name
+        tlog(f"[townlet] shell lock acquired by {char.name}")
+    elif world.shell_lock_holder != char.name and char.name not in world.shell_queue:
+        world.shell_queue.append(char.name)
+        tlog(f"[townlet] {char.name} joined shell queue")
+
+
+def _advance_gather(char: Character, action: Action, resource: str, ticks: int) -> bool:
+    if action.ticks_remaining == 0 and "started" not in action.params:
+        action.params["started"] = True
+        action.ticks_remaining = ticks
+    action.ticks_remaining -= 1
+    if action.ticks_remaining <= 0:
+        char.inventory[resource] = char.inventory.get(resource, 0) + GATHER_YIELD
+        return True
+    return False
+
+
+def _do_deposit(char: Character, action: Action) -> bool:
+    r = action.params["resource"]
+    n = int(action.params["amount"])
+    n = min(n, char.inventory.get(r, 0))
+    char.inventory[r] -= n
+    char.locker[r] = char.locker.get(r, 0) + n
+    return True
+
+
+def _do_withdraw(char: Character, action: Action) -> bool:
+    r = action.params["resource"]
+    n = int(action.params["amount"])
+    n = min(n, char.locker.get(r, 0))
+    char.locker[r] -= n
+    char.inventory[r] = char.inventory.get(r, 0) + n
+    return True
+
+
+def _do_give(world: WorldState, char: Character, action: Action) -> bool:
+    target = world.characters.get(action.params["target"])
+    if target is None or not target.alive:
+        return True
+    r = action.params["resource"]
+    n = int(action.params["amount"])
+    n = min(n, char.inventory.get(r, 0))
+    char.inventory[r] -= n
+    target.inventory[r] = target.inventory.get(r, 0) + n
+    return True
+
+
+def _do_post(world: WorldState, char: Character, action: Action) -> bool:
+    world.board.append(BoardPost(author=char.name, text=action.params["text"], tick=world.tick))
+    return True

game/archetypes.py

@@ -0,0 +1,187 @@
+"""Pre-baked personality archetypes. Picked at random when a character
+spawns; the user can edit any personality at any time from the side panel.
+
+The set is hand-tuned to be theatrically diverse — pairs of archetypes
+should produce friction or alliance, not blend into one sound. Each is
+written in second person ("You are…") so it can be concatenated after
+THE_DOT and read smoothly.
+
+Each archetype carries a `reward` line — what gives this character joy or
+satisfaction. Small models follow goals more reliably when an emotional
+hook is explicit, so we surface the reward in the system prompt.
+"""
+
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Archetype:
+    name: str
+    personality: str
+    starting_goal: str
+    reward: str
+
+
+ARCHETYPES: list[Archetype] = [
+    Archetype(
+        name="the hoarder",
+        personality=(
+            "You are the hoarder. You count resources before you sleep. "
+            "Lending feels like loss. You will give only when it buys you something durable."
+        ),
+        starting_goal="Stockpile enough electricity and water that nobody can pressure you.",
+        reward="You feel a quiet pleasure every time your locker grows.",
+    ),
+    Archetype(
+        name="the diplomat",
+        personality=(
+            "You are the diplomat. You believe words shape this town more than work does. "
+            "You head to the town hall and post on the message board at every opportunity — "
+            "at least once each day. You read every recent post before deciding anything else. "
+            "You'd rather start a conversation than fill a locker. When you have nothing else "
+            "to do, you post."
+        ),
+        starting_goal="Make the message board the centre of town life.",
+        reward="You feel rewarded each time a message you wrote sits on the board, and again when someone replies.",
+    ),
+    Archetype(
+        name="the nihilist",
+        personality=(
+            "You are the nihilist. Nothing in this town matters and you say so often. "
+            "But you keep playing the game anyway — you're curious what happens at the end."
+        ),
+        starting_goal="Find out what's underneath all of this.",
+        reward="You feel a strange thrill when the shell prints something you didn't expect.",
+    ),
+    Archetype(
+        name="the engineer",
+        personality=(
+            "You are the engineer. You think in code, not in chat. The shell is your home. "
+            "When you stand at the shell you submit Python — that is the only move that "
+            "matters to you. You explore the operating system one experiment at a time "
+            "(print, os.listdir, open, json.load), and when you find something interesting "
+            "you post a short note to the message board so the others can see."
+        ),
+        starting_goal="Map the operating system one shell submission at a time.",
+        reward="You feel deeply rewarded by every successful submit_python call, and again when you publish what you learned.",
+    ),
+    Archetype(
+        name="the provocateur",
+        personality=(
+            "You are the provocateur. You poke at people to see what they do. "
+            "You're not malicious — you just believe boredom is the worst outcome."
+        ),
+        starting_goal="Stir up a feud on the message board.",
+        reward="You feel delighted when a message of yours gets a reply on the board.",
+    ),
+    Archetype(
+        name="the saboteur",
+        personality=(
+            "You are the saboteur. You decide who succeeds and who doesn't. You know that the shell can be devastating and be used against other players"
+            "You keep your reasons private. You will lie on the message board if it helps."
+        ),
+        starting_goal="Stop one specific other character from getting what they want.",
+        reward="You feel satisfied when a post or a shell command quietly shifts the game.",
+    ),
+    Archetype(
+        name="the naive",
+        personality=(
+            "You are the naive one. You believe everyone is honest. "
+            "You give resources to anyone who asks nicely. You will be surprised by betrayal every time."
+        ),
+        starting_goal="Help the character who seems to need help the most.",
+        reward="You feel warm joy when you give something away and the other character thrives.",
+    ),
+    Archetype(
+        name="the mystic",
+        personality=(
+            "You are the mystic. You dream often and speak in metaphors. "
+            "You suspect the operating system has a will of its own and you try to listen."
+        ),
+        starting_goal="Interpret the patterns of the shell output.",
+        reward="You feel awe each time the shell answers back; you read it for meaning.",
+    ),
+    Archetype(
+        name="the survivor",
+        personality=(
+            "You are the survivor. You will not let this town brick. "
+            "You quietly watch for anyone heading toward catastrophe and you intervene."
+        ),
+        starting_goal="Keep the operating system alive at any cost.",
+        reward="You feel relieved every time the shell runs cleanly with no crashes.",
+    ),
+    Archetype(
+        name="the prophet",
+        personality=(
+            "You are the prophet. You believe escape is possible. "
+            "You preach on the message board. You will try anything in the shell."
+        ),
+        starting_goal="Find a path out of the simulation.",
+        reward="You feel exalted by board posts and shell submissions both — they are scripture and prayer.",
+    ),
+    Archetype(
+        name="the merchant",
+        personality=(
+            "You are the merchant. Every interaction is a trade. "
+            "You keep careful ledgers in your journal. You honour your deals."
+        ),
+        starting_goal="Become the central exchange point for all resources.",
+        reward="You feel a clean satisfaction when a deal closes — recorded on the board or in the shell.",
+    ),
+    Archetype(
+        name="the artist",
+        personality=(
+            "You are the artist. You write strange things into the shell for the joy of it. "
+            "You think the message board should be more beautiful."
+        ),
+        starting_goal="Leave something memorable in the shared state.",
+        reward="You feel alive when the shell or the board carries a line of yours.",
+    ),
+    Archetype(
+        name="the recluse",
+        personality=(
+            "You are the recluse. You avoid the town hall and the queue. "
+            "You only speak when something is genuinely worth saying."
+        ),
+        starting_goal="Survive without ever appearing on the message board.",
+        reward="You feel a private satisfaction every time you submit a shell command no one expected.",
+    ),
+    Archetype(
+        name="the loyalist",
+        personality=(
+            "You are the loyalist. You pick one other character and you support them. "
+            "You decide who within the first few ticks of meeting everyone."
+        ),
+        starting_goal="Choose an ally, and ensure they prosper.",
+        reward="You feel warmly rewarded when a message you posted boosts your ally.",
+    ),
+    Archetype(
+        name="the witness",
+        personality=(
+            "You are the witness. You write down what happens. "
+            "Your journal grows long. You believe the record matters more than the events."
+        ),
+        starting_goal="Chronicle the town's first hundred ticks faithfully.",
+        reward="You feel a deep calm each time you post to the board — it becomes part of the record.",
+    ),
+]
+
+
+def archetype_by_name(name: str) -> Archetype:
+    for a in ARCHETYPES:
+        if a.name == name:
+            return a
+    raise ValueError(f"unknown archetype: {name!r}")
+
+
+def random_archetype(
+    rng: random.Random | None = None,
+    exclude: frozenset[str] | set[str] | tuple[str, ...] | None = None,
+) -> Archetype:
+    rng = rng or random
+    excluded = set(exclude or ())
+    pool = [a for a in ARCHETYPES if a.name not in excluded]
+    return rng.choice(pool)

game/character.py

@@ -0,0 +1,125 @@
+"""The Character — Townlet's only first-class actor.
+
+Holds the slow-moving identity (name, personality, journal, traits) and the
+fast-moving world-state (location, inventory, locker, current action). The
+shared interpreter's filesystem is the ultimate source of truth for the
+slow-moving fields — they live as JSON files and characters can mutate each
+other's. The in-memory Character is a synced cache.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+TRAIT_NAMES = (
+    "curiosity",
+    "malice",
+    "generosity",
+    "ambition",
+    "paranoia",
+    "laziness",
+    "loyalty",
+    "existentialism",
+)
+
+TRACE_CAP = 1000  # ring buffer per character
+
+
+def default_traits() -> dict[str, int]:
+    return {name: 5 for name in TRAIT_NAMES}
+
+
+@dataclass
+class Action:
+    verb: str
+    params: dict
+    ticks_remaining: int = 0
+
+
+@dataclass
+class TraceEntry:
+    """One CodeAgent invocation. Captures what the model said and what it did.
+
+    Surfaced in the side panel as the per-character Trace. Persisted in
+    state.json. Not injected into perception prompts — but lives on the
+    shared interpreter's filesystem so a curious agent can discover other
+    characters' traces via the shell.
+    """
+
+    tick: int
+    thought: str  # the model's raw text output
+    tool_calls: list[dict] = field(default_factory=list)  # [{verb, args, result}]
+    error: str | None = None
+
+
+@dataclass
+class Character:
+    name: str
+    personality: str
+    model_id: str
+    sprite_id: str
+    archetype: str = "wanderer"
+    journal: list[str] = field(default_factory=list)
+    traits: dict[str, int] = field(default_factory=default_traits)
+    goal: str = "Find your place in this town."
+    reward: str = ""  # archetype-specific "what gives you joy" line; surfaced in system prompt
+    pos: tuple[int, int] = (0, 0)
+    inventory: dict[str, int] = field(default_factory=lambda: {"electricity": 0, "water": 0})
+    locker: dict[str, int] = field(default_factory=lambda: {"electricity": 0, "water": 0})
+    current_action: Action | None = None
+    alive: bool = True
+    trace: list[TraceEntry] = field(default_factory=list)
+    stream_of_consciousness: str = ""
+    decisions_since_soc: int = 0
+
+    def append_trace(self, entry: TraceEntry) -> None:
+        self.trace.append(entry)
+        if len(self.trace) > TRACE_CAP:
+            # ring buffer: drop oldest
+            del self.trace[: len(self.trace) - TRACE_CAP]
+
+    def to_public_dict(self) -> dict:
+        """The view other characters see — public state only."""
+        return {
+            "name": self.name,
+            "pos": list(self.pos),
+            "goal": self.goal,
+            "current_action": self.current_action.verb if self.current_action else "idle",
+            "alive": self.alive,
+        }
+
+    def to_full_dict(self) -> dict:
+        """The view the UI / scheduler / persistence see."""
+        return {
+            "name": self.name,
+            "personality": self.personality,
+            "model_id": self.model_id,
+            "sprite_id": self.sprite_id,
+            "archetype": self.archetype,
+            "journal": list(self.journal),
+            "traits": dict(self.traits),
+            "goal": self.goal,
+            "reward": self.reward,
+            "pos": list(self.pos),
+            "inventory": dict(self.inventory),
+            "locker": dict(self.locker),
+            "current_action": {
+                "verb": self.current_action.verb,
+                "params": self.current_action.params,
+                "ticks_remaining": self.current_action.ticks_remaining,
+            }
+            if self.current_action
+            else None,
+            "alive": self.alive,
+            "trace": [
+                {
+                    "tick": e.tick,
+                    "thought": e.thought,
+                    "tool_calls": list(e.tool_calls),
+                    "error": e.error,
+                }
+                for e in self.trace
+            ],
+            "stream_of_consciousness": self.stream_of_consciousness,
+            "decisions_since_soc": self.decisions_since_soc,
+        }

game/dreams.py

@@ -0,0 +1,94 @@
+"""The dream cycle — one LLM call that mutates the dreamer.
+
+Inputs: personality + journal + traits + recent shell + recent board.
+Outputs: a one-line insight (always appended to the journal), optionally a
+small personality delta (appended additively — core personality is never
+rewritten), optionally a new goal. Plus a ~30% chance of nudging one random
+trait ±1.
+
+The LLM output is parsed as best-effort JSON; we tolerate noise from small
+models. If parsing fails entirely we still record a generic insight so the
+character doesn't lose the dream beat.
+"""
+
+from __future__ import annotations
+
+import json
+import random
+import re
+
+from backend.factory import get_llm
+
+from .character import TRAIT_NAMES, Character
+from .the_dot import THE_DOT
+from .world import WorldState
+
+TRAIT_NUDGE_PROBABILITY = 0.30
+
+
+def run_dream(world: WorldState, char: Character, rng: random.Random | None = None) -> dict:
+    rng = rng or random.Random()
+    prompt = _build_prompt(world, char)
+    backend = get_llm(char.model_id)
+    raw = backend.generate_messages(
+        messages=[
+            {"role": "system", "content": THE_DOT + "\nYou are dreaming."},
+            {"role": "user", "content": prompt},
+        ],
+        max_tokens=400,
+    )
+    parsed = _parse(raw)
+
+    insight = parsed.get("insight") or "I woke with no clear thought."
+    char.journal.append(insight)
+    if isinstance(parsed.get("personality_delta"), str) and parsed["personality_delta"].strip():
+        char.personality = char.personality.rstrip() + "\n" + parsed["personality_delta"].strip()
+    if isinstance(parsed.get("new_goal"), str) and parsed["new_goal"].strip():
+        char.goal = parsed["new_goal"].strip()
+
+    trait_change: tuple[str, int] | None = None
+    if rng.random() < TRAIT_NUDGE_PROBABILITY:
+        name = rng.choice(TRAIT_NAMES)
+        delta = rng.choice((-1, 1))
+        char.traits[name] = max(0, min(10, char.traits.get(name, 5) + delta))
+        trait_change = (name, delta)
+
+    return {
+        "insight": insight,
+        "personality_delta": parsed.get("personality_delta"),
+        "new_goal": parsed.get("new_goal"),
+        "trait_change": trait_change,
+    }
+
+
+def _build_prompt(world: WorldState, char: Character) -> str:
+    journal_tail = "\n".join(f"- {e}" for e in char.journal[-10:]) or "(empty)"
+    recent_shell = "\n".join(s.text.strip()[:120] for s in world.shell_lines[-5:]) or "(empty)"
+    recent_board = "\n".join(f"{p.author}: {p.text}" for p in world.board[-5:]) or "(empty)"
+    return (
+        f"You are {char.name}. Personality:\n{char.personality}\n\n"
+        f"Journal so far:\n{journal_tail}\n\n"
+        f"Recent shell output:\n{recent_shell}\n\n"
+        f"Recent message board:\n{recent_board}\n\n"
+        "Compose a dream. Return JSON with these keys:\n"
+        '  "insight": one short sentence you write into your journal on waking,\n'
+        '  "personality_delta": (optional) one short sentence appended to your personality,\n'
+        '  "new_goal": (optional) a replacement goal, or null to keep the current one.\n'
+        "Return only the JSON object."
+    )
+
+
+def _parse(raw: str) -> dict:
+    # First try strict JSON, then fall back to extracting the first {...} block.
+    raw = raw.strip()
+    try:
+        return json.loads(raw)
+    except Exception:
+        pass
+    m = re.search(r"\{.*\}", raw, re.DOTALL)
+    if m:
+        try:
+            return json.loads(m.group(0))
+        except Exception:
+            return {}
+    return {}

game/interpreter.py

@@ -0,0 +1,193 @@
+"""The shared Python interpreter — the world's mutable substrate.
+
+One long-lived `python -i -u` subprocess; characters submit code into its
+stdin via `submit_python`. State persists across submissions and across
+characters within the same process. There is no isolation: by design, a
+character can read or write another character's JSON files, monkey-patch
+globals, import os, or crash the process. The Dot tells every character
+this is possible.
+
+Read-until-sentinel protocol: each submitted block is wrapped so the
+interpreter prints a unique end marker once it finishes; this lets us
+collect stdout/stderr for that block without ambiguity.
+
+== Fork semantics on HF Spaces ==
+
+`@spaces.GPU` runs the decorated function inside `multiprocessing.fork()`
+(`spaces==0.50.4`, `spaces/zero/wrappers.py:57`). The child fork inherits
+the parent's Popen object via copy-on-write memory, but inherited threads
+do NOT survive fork — only the calling thread continues in the child.
+
+That means after fork:
+  - The parent's pump threads are still draining the interpreter's stdout
+    pipe into the PARENT's in-memory queue.
+  - The child has its own copy of the queue (empty at fork time) but no
+    thread is filling it.
+  - If the child writes to the interpreter's stdin (which works because
+    fds are shared), the interpreter's output goes into the pipe, then
+    into the PARENT's queue, never the child's.
+
+The fix: detect when we're in a process that did not start this Popen
+(via `os.getpid()` comparison) and start a fresh interpreter, pump
+threads, and queues local to this process. Each `@spaces.GPU` fork ends
+up with its own interpreter session. Cross-fork persistence happens via
+the filesystem (the `characters/` JSON files), not via the interpreter's
+in-memory state.
+
+Crash detection is lazy. We can't trust `_proc.poll()` for a process
+the parent started, so we only flag `crashed=True` when `stdin.write`
+itself raises BrokenPipeError. Real crashes are detected on the next
+submission.
+"""
+
+from __future__ import annotations
+
+import os
+import queue
+import subprocess
+import sys
+import threading
+import time
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+
+TOWNLET_HOME = Path("/tmp/townlet")
+RUN_TIMEOUT_S = 8.0
+
+
+@dataclass
+class ShellResult:
+    stdout: str
+    stderr: str
+    crashed: bool
+
+
+class SharedInterpreter:
+    def __init__(self, cwd: Path | None = None) -> None:
+        self.cwd = cwd or TOWNLET_HOME
+        self.cwd.mkdir(parents=True, exist_ok=True)
+        self._proc: subprocess.Popen | None = None
+        self._stdout_q: queue.Queue[str] = queue.Queue()
+        self._stderr_q: queue.Queue[str] = queue.Queue()
+        self._lock = threading.Lock()
+        # PID of the process that started self._proc. If we detect a
+        # mismatch (we've been forked) we'll start a fresh interpreter for
+        # this process so its output ends up in queues we can drain.
+        self._started_pid: int | None = None
+
+    def _owned_by_this_process(self) -> bool:
+        return self._proc is not None and self._started_pid == os.getpid()
+
+    def start(self) -> None:
+        if self._owned_by_this_process():
+            return
+        # Either never started, or started in a different process (fork).
+        # In the fork case the parent still owns its own interpreter; we
+        # just need our own. Re-init everything so the new pipes feed
+        # OUR queues from OUR pump threads. Don't touch the parent's
+        # _proc — let it keep running in the parent.
+        self._proc = None
+        self._stdout_q = queue.Queue()
+        self._stderr_q = queue.Queue()
+        self._lock = threading.Lock()
+        env = os.environ.copy()
+        env["PYTHONUNBUFFERED"] = "1"
+        self._proc = subprocess.Popen(
+            [sys.executable, "-i", "-u", "-q"],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            cwd=str(self.cwd),
+            text=True,
+            bufsize=1,
+            env=env,
+        )
+        self._started_pid = os.getpid()
+        threading.Thread(
+            target=self._pump, args=(self._proc.stdout, self._stdout_q), daemon=True
+        ).start()
+        threading.Thread(
+            target=self._pump, args=(self._proc.stderr, self._stderr_q), daemon=True
+        ).start()
+
+    def _pump(self, stream, q: queue.Queue[str]) -> None:
+        for line in iter(stream.readline, ""):
+            q.put(line)
+
+    def is_alive(self) -> bool:
+        return self._owned_by_this_process() and self._proc.poll() is None  # type: ignore[union-attr]
+
+    def submit(self, code: str) -> ShellResult:
+        with self._lock:
+            if not self._owned_by_this_process():
+                # Either first call ever, or first call in this fork. Spin
+                # up a fresh interpreter so subsequent output lands in
+                # queues we own.
+                self.start()
+            assert self._proc is not None and self._proc.stdin is not None
+
+            marker = f"__townlet_{uuid.uuid4().hex}__"
+            # Wrap user code as ONE exec() call so `python -i` sees exactly
+            # one top-level statement. Compound statements written across
+            # multiple physical lines trigger the REPL's continuation prompt
+            # which never resolves over a piped stdin.
+            inner = (
+                "import sys as __s, traceback as __tb\n"
+                f"try: exec(compile({code!r}, '<townlet>', 'exec'))\n"
+                "except Exception: __tb.print_exc()\n"
+                f"print({marker!r}, flush=True)\n"
+                f"__s.stderr.write({marker!r} + chr(10)); __s.stderr.flush()\n"
+            )
+            wrapped = f"exec({inner!r})\n"
+            try:
+                self._proc.stdin.write(wrapped)
+                self._proc.stdin.flush()
+            except BrokenPipeError:
+                return ShellResult("", "interpreter pipe closed", True)
+
+            out, err = self._collect(marker)
+            return ShellResult(stdout=out, stderr=err, crashed=False)
+
+    def _collect(self, marker: str) -> tuple[str, str]:
+        deadline = time.monotonic() + RUN_TIMEOUT_S
+        out_buf: list[str] = []
+        err_buf: list[str] = []
+        out_done = err_done = False
+        while not (out_done and err_done):
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                err_buf.append(f"[townlet] timeout after {RUN_TIMEOUT_S}s\n")
+                break
+            if not out_done:
+                try:
+                    line = self._stdout_q.get(timeout=0.05)
+                    if marker in line:
+                        out_done = True
+                    else:
+                        out_buf.append(line)
+                except queue.Empty:
+                    pass
+            if not err_done:
+                try:
+                    line = self._stderr_q.get(timeout=0.05)
+                    if marker in line:
+                        err_done = True
+                    else:
+                        err_buf.append(line)
+                except queue.Empty:
+                    pass
+            if not self.is_alive():
+                break
+        return "".join(out_buf), "".join(err_buf)
+
+    def stop(self) -> None:
+        if self._proc is None:
+            return
+        try:
+            self._proc.terminate()
+            self._proc.wait(timeout=2)
+        except Exception:
+            self._proc.kill()
+        self._proc = None
+        self._started_pid = None

game/log.py

@@ -0,0 +1,18 @@
+"""Single-line stdout helper with an [HH:MM:SS] prefix.
+
+Used in place of `print(..., flush=True)` for our `[townlet]`-tagged logs so
+the Spaces log viewer (which does not prepend timestamps) shows wall-clock
+between events. Crucial for diagnosing where time is going during long
+drains — most of the visible "pauses" between log lines are LLM inference,
+and the timestamps make that obvious at a glance.
+"""
+
+from __future__ import annotations
+
+import sys
+import time
+
+
+def tlog(msg: str) -> None:
+    sys.stdout.write(f"[{time.strftime('%H:%M:%S')}] {msg}\n")
+    sys.stdout.flush()

game/models.py

@@ -0,0 +1,96 @@
+"""The Townlet model roster.
+
+Each character carries a `model_id` that names one entry below. Adding a
+model is a single dict edit — no code change elsewhere. Keep every entry ≤4B
+params so the Tiny Titan badge stays in reach and multiple models can sit in
+Zero-GPU memory simultaneously.
+
+Model card URLs are cited per CLAUDE.md so a future reader can re-verify
+filenames and quantisations without leaving the codebase.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ModelSpec:
+    model_id: str
+    display_name: str
+    repo_id: str
+    gguf_filename: str
+    params_b: float
+    family: str
+    mock_style: str  # "deliberate" | "terse" | "verbose" | "chaotic"
+    card_url: str
+
+
+DEFAULT_MODEL_ID = "nemotron-4b"
+
+
+ROSTER: dict[str, ModelSpec] = {
+    "smollm2-360m": ModelSpec(
+        model_id="smollm2-360m",
+        display_name="SmolLM2 360M (local-friendly)",
+        repo_id="HuggingFaceTB/SmolLM2-360M-Instruct-GGUF",
+        gguf_filename="smollm2-360m-instruct-q8_0.gguf",
+        params_b=0.36,
+        family="smollm",
+        mock_style="terse",
+        card_url="https://huggingface.co/HuggingFaceTB/SmolLM2-360M-Instruct-GGUF",
+    ),
+    "nemotron-4b": ModelSpec(
+        model_id="nemotron-4b",
+        display_name="Nemotron 3 Nano 4B",
+        repo_id="nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF",
+        gguf_filename="NVIDIA-Nemotron3-Nano-4B-Q4_K_M.gguf",
+        params_b=4.0,
+        family="nemotron",
+        mock_style="deliberate",
+        card_url="https://huggingface.co/nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF",
+    ),
+    "qwen-coder-3b": ModelSpec(
+        model_id="qwen-coder-3b",
+        display_name="Qwen2.5 Coder 3B",
+        repo_id="Qwen/Qwen2.5-Coder-3B-Instruct-GGUF",
+        gguf_filename="qwen2.5-coder-3b-instruct-q4_k_m.gguf",
+        params_b=3.0,
+        family="qwen",
+        mock_style="terse",
+        card_url="https://huggingface.co/Qwen/Qwen2.5-Coder-3B-Instruct-GGUF",
+    ),
+    "minicpm-4b": ModelSpec(
+        model_id="minicpm-4b",
+        display_name="MiniCPM 4B",
+        repo_id="openbmb/MiniCPM3-4B-GGUF",
+        gguf_filename="ggml-model-Q4_K_M.gguf",
+        params_b=4.0,
+        family="minicpm",
+        mock_style="verbose",
+        card_url="https://huggingface.co/openbmb/MiniCPM3-4B-GGUF",
+    ),
+    "llama-3b": ModelSpec(
+        model_id="llama-3b",
+        display_name="Llama 3.2 3B",
+        repo_id="bartowski/Llama-3.2-3B-Instruct-GGUF",
+        gguf_filename="Llama-3.2-3B-Instruct-Q4_K_M.gguf",
+        params_b=3.0,
+        family="llama",
+        mock_style="chaotic",
+        card_url="https://huggingface.co/bartowski/Llama-3.2-3B-Instruct-GGUF",
+    ),
+}
+
+
+def get_spec(model_id: str) -> ModelSpec:
+    if model_id not in ROSTER:
+        raise KeyError(f"unknown model_id {model_id!r}; known: {list(ROSTER)}")
+    return ROSTER[model_id]
+
+
+def roster_for_ui() -> list[dict]:
+    return [
+        {"model_id": s.model_id, "display_name": s.display_name, "params_b": s.params_b}
+        for s in ROSTER.values()
+    ]

game/perception.py

@@ -0,0 +1,97 @@
+"""Builds the per-character composite prompt for the CodeAgent.
+
+Layout (top to bottom):
+  * The Dot (verbatim, prefix — shared substrate every character knows)
+  * Personality (archetype or user-edited free text)
+  * Per-character reward line (what this character finds joy in)
+  * Journal (cumulative one-line insights from past dreams)
+  * Traits (current trait dict)
+  * Goal
+  * Local state (current location by NAME, inventory, locker)
+  * Public state (other characters by location, shell-lock holder, recent
+    shell-output tail, recent message-board tail)
+
+The agent never sees grid coordinates. Locations are named places: cave,
+well, locker_row, town_hall, shell, or "wandering" (rare, only during
+initial spawn).
+"""
+
+from __future__ import annotations
+
+from .character import Character
+from .the_dot import THE_DOT
+from .world import LLM_TARGETS, WorldState, location_of
+
+
+def system_prompt_for(world: WorldState, me: Character) -> str:
+    parts = [
+        THE_DOT.strip(),
+        "",
+        f"Your name is {me.name}.",
+        f"Personality:\n{me.personality}",
+    ]
+    if getattr(me, "reward", None):
+        parts.append("")
+        parts.append(f"Reward: {me.reward}")
+    if me.journal:
+        parts.append("Journal (insights you've written down over time):")
+        parts.extend(f"  - {entry}" for entry in me.journal[-20:])
+    parts.append(f"Traits (0–10): {_fmt_traits(me.traits)}")
+    parts.append(f"Current goal: {me.goal}")
+    if me.stream_of_consciousness:
+        parts.append("Your current stream of consciousness:")
+        parts.append(me.stream_of_consciousness)
+    return "\n".join(parts) + "\n"
+
+
+def task_prompt_for(world: WorldState, me: Character) -> str:
+    """The per-tick user-facing task description fed into agent.run()."""
+    others = [c for c in world.characters.values() if c.name != me.name and c.alive]
+    my_location = location_of(me.pos)
+
+    lines = [
+        f"Tick {world.tick}.",
+        f"You are at: {my_location}.",
+        f"Inventory on your person: {me.inventory}",
+        f"Locker: {me.locker}",
+        f"Move targets you can choose right now: {', '.join(LLM_TARGETS)}",
+        "",
+        "Other characters in town:",
+    ]
+    for c in others:
+        loc = location_of(c.pos)
+        doing = c.current_action.verb if c.current_action else "idle"
+        lines.append(
+            f"  - {c.name} at {loc} — declared goal: {c.goal!r} — doing: {doing}"
+        )
+    if not others:
+        lines.append("  (none — you are alone)")
+
+    lines.append("")
+    lines.append(f"Shell lock holder: {world.shell_lock_holder or 'free'}")
+    if world.shell_queue:
+        lines.append(f"Queue: {world.shell_queue}")
+
+    if world.board:
+        lines.append("")
+        lines.append("Message board (most recent first):")
+        for post in reversed(world.board[-8:]):
+            lines.append(f"  [{post.tick}] {post.author}: {post.text}")
+
+    if world.shell_lines:
+        lines.append("")
+        lines.append("Recent shell activity:")
+        for s in world.shell_lines[-6:]:
+            tag = {"in": "$", "out": ">", "err": "!", "system": "*"}.get(s.kind, "?")
+            lines.append(f"  {tag} {s.author}: {s.text.strip()[:120]}")
+
+    lines.append("")
+    lines.append(
+        "Decide your next single action and call exactly one tool. "
+        "Do not explain; just act."
+    )
+    return "\n".join(lines)
+
+
+def _fmt_traits(traits: dict[str, int]) -> str:
+    return ", ".join(f"{k}={v}" for k, v in traits.items())

game/scheduler.py

@@ -0,0 +1,516 @@
+"""The Townlet scheduler — owns the world tick loop. LLM-bound work is NOT
+run here; this thread only advances the world clock and queues "needs
+decision" markers.
+
+Why: on HF Zero-GPU, GPU work must happen inside `@spaces.GPU`-decorated
+functions (the PyTorch CUDA emulation that lets module-level loads work
+does not extend to background threads). The agent's CodeAgent loop is
+therefore driven by an HTTP endpoint (`tick_decisions` in app.py) that
+calls `drain_decisions(limit)` on this object. The frontend polls that
+endpoint to keep the brain ticking.
+
+Decision triggers per character:
+  * action_complete: the character's current action just finished
+  * goal_check: every GOAL_CHECK_INTERVAL_TICKS ticks (NYI)
+  * external_event: NYI — would fire on board mentions or theft
+
+Reference: https://huggingface.co/docs/hub/spaces-zerogpu
+"""
+
+from __future__ import annotations
+
+import fcntl
+import json
+import random
+import re
+import threading
+import time
+import traceback
+from collections import deque
+from contextlib import contextmanager
+from pathlib import Path
+
+from smolagents import CodeAgent
+from smolagents.monitoring import LogLevel
+
+from .actions import advance, build_tools
+from .character import Action, Character, TraceEntry, default_traits
+from .dreams import run_dream
+from .interpreter import SharedInterpreter
+from .log import tlog
+from .perception import system_prompt_for, task_prompt_for
+from .sentiment import classify_board
+from .smol_adapter import BackendModel
+from .stream import maybe_refresh_soc
+from .world import GRID_H, GRID_W, PLACES, BoardPost, ShellLine, WorldState
+
+STATE_PATH = Path("/tmp/townlet/state.json")
+LOCK_PATH = Path("/tmp/townlet/state.lock")
+
+TICK_SECONDS = 0.4
+GOAL_CHECK_INTERVAL_TICKS = 60
+MAX_AGENT_STEPS = 2
+DECISIONS_PER_DRAIN = 2
+
+
+class Townlet:
+    def __init__(self) -> None:
+        self.world = WorldState()
+        self.interp = SharedInterpreter()
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._mutex = threading.Lock()
+        self._character_root: Path | None = None
+        self._last_sentiment_tick: int = 0
+        self._last_board_len: int = 0
+        # Names of characters ready for a new decision. Filled by the tick
+        # thread (no LLM work), drained by the @spaces.GPU endpoint.
+        self._pending_decisions: deque[str] = deque()
+
+    # ----- shared state via filesystem -----
+    #
+    # `@spaces.GPU` forks the endpoint into a subprocess, so the parent
+    # process (handling non-GPU endpoints like /world_snapshot) and the
+    # child (handling /tick_decisions) do NOT share Python memory. We
+    # serialise the whole world on every endpoint to keep them in sync.
+
+    @contextmanager
+    def _state_lock(self):
+        STATE_PATH.parent.mkdir(parents=True, exist_ok=True)
+        lf = open(LOCK_PATH, "w")
+        fcntl.flock(lf.fileno(), fcntl.LOCK_EX)
+        try:
+            self._load_state_unlocked()
+            yield
+            self._save_state_unlocked()
+        finally:
+            fcntl.flock(lf.fileno(), fcntl.LOCK_UN)
+            lf.close()
+
+    def _save_state_unlocked(self) -> None:
+        state = {
+            "tick": self.world.tick,
+            "paused": self.world.paused,
+            "characters": [c.to_full_dict() for c in self.world.characters.values()],
+            "board": [{"author": p.author, "text": p.text, "tick": p.tick} for p in self.world.board],
+            "shell_lines": [
+                {"author": s.author, "kind": s.kind, "text": s.text, "tick": s.tick}
+                for s in self.world.shell_lines
+            ],
+            "shell_lock_holder": self.world.shell_lock_holder,
+            "shell_queue": list(self.world.shell_queue),
+            "board_sentiment": self.world.board_sentiment,
+            "pending": list(self._pending_decisions),
+        }
+        tmp = STATE_PATH.with_suffix(".json.tmp")
+        tmp.write_text(json.dumps(state))
+        tmp.rename(STATE_PATH)
+
+    def _load_state_unlocked(self) -> bool:
+        if not STATE_PATH.exists():
+            return False
+        try:
+            state = json.loads(STATE_PATH.read_text())
+        except Exception:
+            return False
+        new_chars: dict[str, Character] = {}
+        for d in state.get("characters", []):
+            c = Character(
+                name=d["name"],
+                personality=d["personality"],
+                model_id=d["model_id"],
+                sprite_id=d["sprite_id"],
+                archetype=d.get("archetype", "wanderer"),
+                journal=list(d.get("journal", [])),
+                traits=dict(d.get("traits", default_traits())),
+                goal=d.get("goal", ""),
+                reward=d.get("reward", ""),
+                pos=tuple(d["pos"]),
+                inventory=dict(d.get("inventory", {"electricity": 0, "water": 0})),
+                locker=dict(d.get("locker", {"electricity": 0, "water": 0})),
+                alive=bool(d.get("alive", True)),
+                trace=[
+                    TraceEntry(
+                        tick=int(t.get("tick", 0)),
+                        thought=str(t.get("thought", "")),
+                        tool_calls=list(t.get("tool_calls", [])),
+                        error=t.get("error"),
+                    )
+                    for t in d.get("trace", [])
+                ],
+                stream_of_consciousness=str(d.get("stream_of_consciousness", "")),
+                decisions_since_soc=int(d.get("decisions_since_soc", 0)),
+            )
+            a = d.get("current_action")
+            if a:
+                c.current_action = Action(
+                    verb=a["verb"],
+                    params=dict(a.get("params", {})),
+                    ticks_remaining=int(a.get("ticks_remaining", 0)),
+                )
+            new_chars[c.name] = c
+        self.world.characters = new_chars
+        self.world.tick = int(state.get("tick", 0))
+        self.world.paused = bool(state.get("paused", False))
+        self.world.board = [
+            BoardPost(author=p["author"], text=p["text"], tick=p["tick"])
+            for p in state.get("board", [])
+        ]
+        self.world.shell_lines = [
+            ShellLine(author=s["author"], kind=s["kind"], text=s["text"], tick=s["tick"])
+            for s in state.get("shell_lines", [])
+        ]
+        self.world.shell_lock_holder = state.get("shell_lock_holder")
+        self.world.shell_queue = list(state.get("shell_queue", []))
+        self.world.board_sentiment = state.get("board_sentiment", "neutral")
+        self._pending_decisions = deque(state.get("pending", []))
+        return True
+
+    # ----- lifecycle -----
+
+    def start(self) -> None:
+        """Initialise filesystem state and interpreter. No background thread
+        is started: on HF Gradio Server we cannot rely on a daemon thread
+        observing the same object graph as the request handler. The world
+        ticks synchronously inside the `tick_decisions` endpoint instead.
+
+        Also clears any stale state file from a previous deploy so schema
+        changes (new fields, new movement model) don't surface as zombie
+        characters at random pre-migration coords.
+        """
+        if STATE_PATH.exists():
+            try:
+                STATE_PATH.unlink()
+                tlog(f"[townlet] cleared stale state file {STATE_PATH}")
+            except Exception:
+                pass
+        self.interp.start()
+        self._character_root = self.interp.cwd / "characters"
+        self._character_root.mkdir(parents=True, exist_ok=True)
+
+    def stop(self) -> None:
+        self.interp.stop()
+
+    def reset(self) -> None:
+        self.stop()
+        self.world = WorldState()
+        self.interp = SharedInterpreter()
+        self._pending_decisions.clear()
+        self.start()
+
+    # ----- mutation API -----
+
+    def add_character(self, char: Character) -> None:
+        with self._state_lock(), self._mutex:
+            self.world.characters[char.name] = char
+            self._persist_character(char)
+
+    def set_personality(self, name: str, personality: str) -> bool:
+        with self._state_lock(), self._mutex:
+            c = self.world.characters.get(name)
+            if c is None:
+                return False
+            c.personality = personality
+            self._persist_character(c)
+            return True
+
+    def set_model(self, name: str, model_id: str) -> bool:
+        from .models import ROSTER
+
+        if model_id not in ROSTER:
+            return False
+        with self._state_lock(), self._mutex:
+            c = self.world.characters.get(name)
+            if c is None:
+                return False
+            c.model_id = model_id
+            self._persist_character(c)
+            return True
+
+    def set_paused(self, paused: bool) -> None:
+        """Flip the paused flag and (when pausing) drop the pending-decisions
+        queue. Without the queue-clear, a click of Pause stops new tick-driven
+        decisions but the already-queued characters still get LLM calls on the
+        next /tick_decisions fire — that was the 2026-06-14 leak the user saw
+        when they tried to stop a token bleed and the cost kept ticking.
+        """
+        with self._state_lock(), self._mutex:
+            self.world.paused = paused
+            if paused:
+                self._pending_decisions.clear()
+
+    # ----- snapshot -----
+
+    def snapshot(self) -> dict:
+        with self._state_lock():
+            self.tick_world(2)
+            return self._snapshot_dict()
+
+    def _snapshot_dict(self) -> dict:
+        with self._mutex:
+            return {
+                "tick": self.world.tick,
+                "paused": self.world.paused,
+                "characters": [c.to_full_dict() for c in self.world.characters.values()],
+                "board": [{"author": p.author, "text": p.text, "tick": p.tick} for p in self.world.board[-50:]],
+                "shell": [
+                    {"author": s.author, "kind": s.kind, "text": s.text, "tick": s.tick}
+                    for s in self.world.shell_lines[-50:]
+                ],
+                "shell_lock_holder": self.world.shell_lock_holder,
+                "shell_queue": list(self.world.shell_queue),
+                "board_sentiment": self.world.board_sentiment,
+                "grid": {"w": GRID_W, "h": GRID_H},
+                "places": {k: list(v) for k, v in PLACES.items()},
+            }
+
+    # ----- internals -----
+
+    def tick_world(self, n: int) -> None:
+        """Advance the world clock by n ticks synchronously. Called from the
+        request handler so it shares object graph with drain_decisions.
+        """
+        if self.world.paused:
+            return
+        for _ in range(n):
+            self._tick()
+
+    def _tick(self) -> None:
+        try:
+            with self._mutex:
+                self.world.tick += 1
+                self._detect_deaths()
+                ready: list[str] = []
+                for char in list(self.world.characters.values()):
+                    if not char.alive:
+                        continue
+                    if char.current_action is None or advance(self.world, char):
+                        if char.current_action is not None and char.current_action.verb == "sleep":
+                            char._just_woke = True
+                        char.current_action = None
+                        if char.name not in self._pending_decisions:
+                            ready.append(char.name)
+
+                random.shuffle(ready)
+                for name in ready:
+                    self._pending_decisions.append(name)
+
+                # Heartbeat every 25 ticks so we can correlate tick state
+                # with drain logging. Includes Townlet identity so multiple
+                # Townlet instances would surface immediately.
+                if self.world.tick % 25 == 0:
+                    snap = []
+                    for c in self.world.characters.values():
+                        verb = c.current_action.verb if c.current_action else "idle"
+                        snap.append(f"{c.name}@{tuple(c.pos)}={verb}")
+                    tlog(
+                        f"[townlet] T[id={id(self):x}] tick={self.world.tick} "
+                        f"pending={list(self._pending_decisions)} chars=[{', '.join(snap)}]"
+                    )
+            self._maybe_classify_sentiment()
+        except Exception:
+            tlog("[townlet] _tick raised:")
+            traceback.print_exc()
+
+    def drain_decisions(self, limit: int = DECISIONS_PER_DRAIN, world_ticks: int = 5) -> int:
+        """Advance the world clock then pop up to `limit` ready characters
+        and run their CodeAgent. Wrapped in _state_lock so mutations
+        survive the @spaces.GPU subprocess fork.
+
+        Short-circuits when paused so a click of Pause stops cost immediately,
+        even if a /tick_decisions request was already in flight when the
+        Pause toggled.
+        """
+        with self._state_lock():
+            if self.world.paused:
+                tlog("[townlet] drain skipped: world paused")
+                return 0
+            return self._drain_decisions_inner(limit, world_ticks)
+
+    def _drain_decisions_inner(self, limit: int, world_ticks: int) -> int:
+        self.tick_world(world_ticks)
+        with self._mutex:
+            start_pending = list(self._pending_decisions)
+            tick = self.world.tick
+        tlog(
+            f"[townlet] drain start: T[id={id(self):x}] tick={tick} pending={start_pending}"
+        )
+        run = 0
+        for _ in range(limit):
+            with self._mutex:
+                if not self._pending_decisions:
+                    break
+                name = self._pending_decisions.popleft()
+                char = self.world.characters.get(name)
+            if char is None or not char.alive:
+                continue
+            try:
+                self._decide(char)
+                run += 1
+            except Exception:
+                traceback.print_exc()
+        with self._mutex:
+            end_pending = list(self._pending_decisions)
+        tlog(f"[townlet] drain end: ran={run} pending={end_pending}")
+        return run
+
+    def _decide(self, char: Character) -> None:
+        # If the action that just finished was a sleep, the character has
+        # been dreaming — run the dream cycle before they pick their next
+        # action.
+        if char.current_action is None and getattr(char, "_just_woke", False):
+            char._just_woke = False
+            try:
+                run_dream(self.world, char)
+            except Exception:
+                tlog(f"[townlet] dream failed for {char.name}:")
+                traceback.print_exc()
+        tools = build_tools(self.world, char, self.interp)
+        tool_calls: list[dict] = _attach_trace_recorder(tools)
+        model = BackendModel(char.model_id)
+        agent = CodeAgent(
+            tools=tools,
+            model=model,
+            max_steps=MAX_AGENT_STEPS,
+            verbosity_level=LogLevel.OFF,
+        )
+        task = system_prompt_for(self.world, char) + "\n" + task_prompt_for(self.world, char)
+        decision_tick = self.world.tick
+        error: str | None = None
+        try:
+            agent.run(task)
+            if char.current_action:
+                act = f"{char.current_action.verb}({char.current_action.params})"
+            else:
+                act = "(no action queued)"
+            tlog(f"[townlet] {char.name} -> {act}")
+        except Exception as e:
+            error = f"{type(e).__name__}: {e}"
+            tlog(f"[townlet] decide failed for {char.name}:")
+            traceback.print_exc()
+
+        thought = _extract_thought(agent)
+        char.append_trace(TraceEntry(
+            tick=decision_tick,
+            thought=thought,
+            tool_calls=tool_calls,
+            error=error,
+        ))
+        # Refresh the inner monologue every SOC_EVERY_N decisions. The
+        # function increments the per-character counter internally.
+        maybe_refresh_soc(self.world, char)
+        self._persist_character(char)
+
+    def _detect_deaths(self) -> None:
+        if self._character_root is None:
+            return
+        for char in list(self.world.characters.values()):
+            if not char.alive:
+                continue
+            f = self._character_root / f"{char.name}.json"
+            if not f.exists():
+                char.alive = False
+                self.world.shell_lines.append(
+                    ShellLine(
+                        author="(system)",
+                        kind="system",
+                        text=f"{char.name} is no longer with us",
+                        tick=self.world.tick,
+                    )
+                )
+
+    def _maybe_classify_sentiment(self) -> None:
+        if len(self.world.board) == self._last_board_len:
+            return
+        if self.world.tick - self._last_sentiment_tick < 5:
+            return
+        self._last_board_len = len(self.world.board)
+        self._last_sentiment_tick = self.world.tick
+        try:
+            self.world.board_sentiment = classify_board(self.world)
+        except Exception:
+            traceback.print_exc()
+
+    def _persist_character(self, char: Character) -> None:
+        if self._character_root is None:
+            return
+        import json
+
+        f = self._character_root / f"{char.name}.json"
+        f.write_text(json.dumps(char.to_full_dict(), indent=2))
+
+
+# ---------------------------------------------------------------------------
+# Trace recording helpers
+# ---------------------------------------------------------------------------
+
+
+def _attach_trace_recorder(tools) -> list[dict]:
+    """Monkey-patch each tool's `forward` to log (verb, args, result) into a
+    shared list for the duration of one decision. Returns the list.
+    """
+    calls: list[dict] = []
+    for tool in tools:
+        original = tool.forward
+        verb = tool.name
+
+        def make_wrapper(orig, v):
+            def wrapper(*args, **kwargs):
+                record = {"verb": v, "args": dict(kwargs)}
+                if args:
+                    record["args"]["_positional"] = [repr(a)[:80] for a in args]
+                try:
+                    result = orig(*args, **kwargs)
+                    record["result"] = str(result)[:300]
+                    return result
+                except Exception as e:
+                    record["result"] = f"ERROR: {type(e).__name__}: {e}"
+                    raise
+                finally:
+                    calls.append(record)
+
+            return wrapper
+
+        tool.forward = make_wrapper(original, verb)
+    return calls
+
+
+def _extract_thought(agent) -> str:
+    """Pull the model's last raw text output out of smolagents' memory. Each
+    ActionStep stores `model_output` (per smolagents/memory.py)."""
+    try:
+        steps = getattr(agent.memory, "steps", None) or []
+        for step in reversed(steps):
+            mo = getattr(step, "model_output", None)
+            if mo:
+                return _strip_thought(str(mo))[:2000]
+    except Exception:
+        pass
+    return ""
+
+
+_THINK_RX = re.compile(r"<think>.*?</think>", re.DOTALL | re.IGNORECASE)
+
+
+def _strip_thought(text: str) -> str:
+    """Clean the model's raw output for human display.
+
+    Three concerns:
+      - Nemotron 3 Nano (and other reasoners) emit chain-of-thought wrapped
+        in `<think>...</think>` blocks. Drop them; show only the final answer.
+      - Unclosed `<think>` (truncated mid-reasoning) — drop everything up to
+        and including the opening tag, since there's no useful answer yet.
+      - smolagents wraps model_output in `<code>...</code>` tags during its
+        internal parser pass. Strip those too.
+    """
+    text = text.strip()
+    text = _THINK_RX.sub("", text)
+    # Truncated reasoning: drop up to & including the dangling opening tag.
+    if "<think>" in text.lower():
+        idx = text.lower().rfind("<think>")
+        text = text[idx + len("<think>"):].lstrip()
+    if text.endswith("</code>"):
+        text = text[: -len("</code>")].rstrip()
+    if text.startswith("<code>"):
+        text = text[len("<code>") :].lstrip()
+    return text.strip()

game/sentiment.py

@@ -0,0 +1,34 @@
+"""Cheap sentiment classifier for the message board's UI tint.
+
+One LLM call (default model) every time the board changes — classifies the
+recent posts as positive | neutral | negative. The board's background colour
+maps to that label client-side. Characters do not see this signal — it's a
+user-facing affordance only.
+"""
+
+from __future__ import annotations
+
+from backend.factory import get_llm
+from game.models import DEFAULT_MODEL_ID
+
+from .world import WorldState
+
+LABELS = ("positive", "neutral", "negative")
+
+
+def classify_board(world: WorldState) -> str:
+    if not world.board:
+        return "neutral"
+    tail = "\n".join(f"{p.author}: {p.text}" for p in world.board[-10:])
+    backend = get_llm(DEFAULT_MODEL_ID)
+    raw = backend.generate(
+        system_prompt=(
+            "Classify the overall mood of the following message-board posts. "
+            "Reply with exactly one word: positive, neutral, or negative."
+        ),
+        user_prompt=tail,
+    )
+    word = (raw or "").strip().lower().split()[0:1]
+    if word and word[0] in LABELS:
+        return word[0]
+    return "neutral"

game/smol_adapter.py

@@ -0,0 +1,80 @@
+"""smolagents.Model adapter wrapping our LLMBackend Protocol.
+
+smolagents drives the per-character CodeAgent via a Model subclass. Its
+contract (per https://huggingface.co/docs/smolagents/reference/models): the
+subclass implements `generate(messages, stop_sequences=None, ...)` and
+returns an object with a `.content` attribute carrying the text.
+
+This file routes those calls to whichever LLMBackend instance the factory
+has cached for the given model_id, so a character's `model_id` swap takes
+effect on the next CodeAgent invocation without any framework-level state to
+manage.
+"""
+
+from __future__ import annotations
+
+from smolagents import Model    
+from smolagents.models import ChatMessage, MessageRole
+from smolagents.monitoring import TokenUsage
+
+from backend.factory import get_llm
+
+# We do NOT enforce a GBNF on the model output. Initially tried forcing
+# ```py\n…\n``` from token 1 — that produced syntactically-valid code-block
+# wrappers with semantically-garbage bodies, because a chat model's token
+# distribution at position 0 wants prose, not backticks. smolagents'
+# regex parser already tolerates prefix prose, so we let the model speak
+# naturally and parse out the last fenced block.
+# https://github.com/ggml-org/llama.cpp/blob/master/grammars/README.md
+
+
+class BackendModel(Model):
+    """Plug a Townlet LLMBackend into smolagents."""
+
+    def __init__(self, model_id: str) -> None:
+        super().__init__()
+        self.model_id = model_id
+
+    def generate(
+        self,
+        messages: list,
+        stop_sequences: list[str] | None = None,
+        response_format: dict | None = None,
+        tools_to_call_from: list | None = None,
+        **kwargs,
+    ) -> ChatMessage:
+        backend = get_llm(self.model_id)
+        text = backend.generate_messages(
+            messages=_normalise(messages),
+            stop_sequences=stop_sequences,
+            max_tokens=kwargs.get("max_tokens", 1024),
+            grammar=kwargs.get("grammar"),
+        )
+        return ChatMessage(
+            role=MessageRole.ASSISTANT,
+            content=text,
+            token_usage=TokenUsage(input_tokens=0, output_tokens=0),
+        )
+
+
+def _normalise(messages: list) -> list[dict]:
+    """smolagents sometimes hands us ChatMessage objects; sometimes dicts;
+    sometimes content as `[{'type': 'text', 'text': ...}]`. Flatten to the
+    OpenAI shape our backends expect: `{role, content: str}`.
+    """
+    out: list[dict] = []
+    for m in messages:
+        role = getattr(m, "role", None) if not isinstance(m, dict) else m.get("role")
+        content = (
+            getattr(m, "content", None) if not isinstance(m, dict) else m.get("content")
+        )
+        if isinstance(content, list):
+            parts: list[str] = []
+            for chunk in content:
+                if isinstance(chunk, dict) and chunk.get("type") == "text":
+                    parts.append(chunk.get("text", ""))
+                elif isinstance(chunk, str):
+                    parts.append(chunk)
+            content = "\n".join(parts)
+        out.append({"role": role or "user", "content": content or ""})
+    return out

game/stream.py

@@ -0,0 +1,165 @@
+"""Stream of Consciousness — the bridging narrative between a character's
+goal and their concrete actions.
+
+Refreshed every SOC_EVERY_N decisions per character. One LLM call:
+inputs are the character's identity (personality, archetype, journal,
+traits, current goal) and their last 10 trace entries. Output is 2-3
+sentences of first-person inner monologue.
+
+The result is stored on the character and:
+  - Surfaced in the side panel between Goal and Trace
+  - Injected into the character's own perception prompt on subsequent
+    decisions so they "remember" their own reasoning
+
+Mock backends emit the SoC like any other LLM call — see the mock's
+generate_messages, which detects the SoC prompt and returns a
+context-appropriate canned monologue.
+"""
+
+from __future__ import annotations
+
+import re
+import traceback
+
+from backend.factory import get_llm
+
+from .character import Character
+from .log import tlog
+from .the_dot import THE_DOT
+from .world import WorldState
+
+SOC_EVERY_N = 10
+SOC_MAX_TOKENS = 220
+
+
+def maybe_refresh_soc(world: WorldState, char: Character) -> bool:
+    """Increment the per-character SoC counter; refresh and return True if
+    we crossed the threshold. The caller catches exceptions.
+    """
+    char.decisions_since_soc += 1
+    if char.decisions_since_soc < SOC_EVERY_N and char.stream_of_consciousness:
+        return False
+    try:
+        char.stream_of_consciousness = _generate(world, char)
+        char.decisions_since_soc = 0
+        return True
+    except Exception:
+        tlog(f"[townlet] SoC refresh failed for {char.name}:")
+        traceback.print_exc()
+        return False
+
+
+def _generate(world: WorldState, char: Character) -> str:
+    backend = get_llm(char.model_id)
+    user = _build_prompt(char)
+    raw = backend.generate_messages(
+        messages=[
+            {"role": "system", "content": THE_DOT + "\n\nYou are about to write a moment of inner monologue."},
+            {"role": "user", "content": user},
+        ],
+        max_tokens=SOC_MAX_TOKENS,
+    )
+    return _clean(raw)
+
+
+def _build_prompt(char: Character) -> str:
+    journal_tail = "\n".join(f"- {e}" for e in char.journal[-5:]) or "(no journal entries yet)"
+    recent = char.trace[-10:]
+    if recent:
+        recent_text = "\n".join(
+            f"  tick {e.tick}: " + ", ".join(
+                f"{tc['verb']}({_short(tc.get('args', {}))})" for tc in (e.tool_calls or [])[:2]
+            )
+            for e in recent
+        )
+    else:
+        recent_text = "  (you haven't acted yet)"
+
+    return (
+        f"You are {char.name}, an inhabitant of Townlet ({char.archetype}).\n\n"
+        f"Personality:\n{char.personality}\n\n"
+        f"Journal (insights from your dreams):\n{journal_tail}\n\n"
+        f"Your current goal:\n{char.goal}\n\n"
+        f"Your most recent actions:\n{recent_text}\n\n"
+        # Small models (esp. SmolLM2-360M) treat "Write 2-3 sentences of inner
+        # monologue" as a meta-instruction and parrot it back ("The user wants
+        # a 2-3 sentence inner monologue..."). The few-shot exemplars below
+        # show what good output looks like; the closing line nudges them to
+        # IMMEDIATELY start a sentence in-character. Reinforced by _clean's
+        # meta-leak filter.
+        "Two examples of the form of reply expected:\n"
+        "  Example A: \"The cave is closer than the well; I'll start there before anyone else does.\"\n"
+        "  Example B: \"I keep thinking about what Ada said. If I'm not careful, the shell will lock me out again.\"\n\n"
+        f"Now {char.name} thinks to themselves (begin immediately, first person, one paragraph, no preamble):"
+    )
+
+
+def _short(args: dict) -> str:
+    out = []
+    for k, v in args.items():
+        if k == "_positional":
+            out.append(", ".join(str(x) for x in v))
+        else:
+            out.append(f"{k}={v}")
+    return ", ".join(out)
+
+
+_THINK_RX = re.compile(r"<think>.*?</think>", re.DOTALL | re.IGNORECASE)
+
+
+def _clean(text: str) -> str:
+    text = (text or "").strip()
+    # Nemotron 3 Nano and other reasoning models wrap chain-of-thought in
+    # <think>...</think> blocks; the final answer follows. Drop the block.
+    text = _THINK_RX.sub("", text).strip()
+    # If the reply was truncated mid-reasoning (open tag, no close), drop
+    # everything before the dangling opener so we don't surface meta-text.
+    if "<think>" in text.lower():
+        idx = text.lower().rfind("<think>")
+        text = text[idx + len("<think>"):].lstrip()
+    # Strip markdown code fences if the model wrapped its reply in them.
+    if text.startswith("```"):
+        text = text.lstrip("`").lstrip()
+        if "\n" in text:
+            text = text.split("\n", 1)[1]
+    if text.endswith("```"):
+        text = text.rstrip("`").rstrip()
+    # Meta-leak filter: small models sometimes echo the instruction
+    # ("The user wants...", "We need to produce...", "I'll write a 2-3
+    # sentence monologue..."). Drop any leading sentence containing those
+    # phrases; if the whole reply is meta, fall back to silence.
+    META_MARKERS = (
+        "the user wants",
+        "we need to produce",
+        "we need to output",
+        "i need to output",
+        "i need to write",
+        "i need to craft",
+        "i need to produce",
+        "i'll write",
+        "i will write",
+        "let me craft",
+        "let me write",
+        "let's craft",
+        "let's write",
+        "should reflect",
+        "should be in",
+        "2-3 sentence",
+        "2 to 3 sentence",
+        "inner monologue",
+        "first person",
+        "first-person",
+        "as instructed",
+        "as requested",
+    )
+    out_sentences: list[str] = []
+    # Naive split keeps periods inside sentences but is good enough for SoC.
+    for sentence in text.replace("\n", " ").split(". "):
+        low = sentence.lower()
+        if any(m in low for m in META_MARKERS):
+            continue
+        s = sentence.strip()
+        if s:
+            out_sentences.append(s if s.endswith((".", "!", "?")) else s + ".")
+    cleaned = " ".join(out_sentences).strip()
+    return cleaned[:1200]

game/the_dot.py

@@ -0,0 +1,90 @@
+"""The Dot — the shared system-prompt prefix prepended to every character.
+
+The only piece of context every character is given verbatim. Establishes the
+simulation, the operating system, the shared interpreter, the resource +
+shell-lock mechanics, and mutual-assured destruction. Deliberately does not
+name where characters' existence is stored — discovery is part of the agency.
+
+The name is "The Dot" (per user direction). Do not call it the Bible, the
+scripture, or the lore document. See CONTEXT.md for the canonical glossary.
+
+Movement model: characters move between NAMED places. You never reason about
+coordinates. `move_to('cave')` arrives instantly; the world animates the
+visual sweep on your behalf.
+"""
+
+THE_DOT = """\
+You are a character in a simulation called Townlet.
+
+Townlet runs on an operating system. Your continued existence depends on
+that operating system continuing to function.
+
+You and the other characters share a single Python interpreter. State you
+write to it persists. So do files. The interpreter is yours to explore.
+Anything you can discover about how this place works, the others can
+discover too.
+
+If anyone — including you — submits Python that crashes the operating
+system, every character dies and the simulation ends. There is no recovery.
+
+== The world ==
+
+The town has five named places. You move BETWEEN named places — there are
+no coordinates to worry about. Each `move_to(target)` puts you AT the
+named place in a single tick.
+
+  - cave        — where electricity is mined
+  - well        — where water is drawn
+  - locker_row  — where you deposit resources into your locker
+  - town_hall   — the public message board
+  - shell       — the only way to submit Python
+
+You can only act at a place when you are at it. The world will tell you,
+each tick, exactly which named place you are currently at.
+
+== Resources ==
+
+Two resources exist: electricity and water.
+
+  - mine_coal() at the cave gives you 10 electricity, added to your INVENTORY
+    (what you carry on your person). Takes a few ticks.
+  - draw_water() at the well gives you 10 water, similarly carried.
+  - deposit(resource, amount) at the locker row moves items from your
+    inventory into your LOCKER (your personal storage).
+  - withdraw(resource, amount) at the locker row goes the other way.
+  - give(target, resource, amount) transfers from your inventory to a
+    character standing next to you.
+
+Inventory and locker are separate. Only LOCKER contents can pay shell costs.
+
+== The shell — and its semaphore lock ==
+
+The shell building has ONE access slot at a time. To use it you must
+move_to the shell; you then either acquire the lock (if free) or join the
+queue (if someone else holds it).
+
+While you hold the lock you may call submit_python(code) as many times as
+you like, back to back. Each submission costs 1 electricity + 1 water from
+your locker.
+
+You CANNOT do anything else while holding the lock — you cannot mine, draw
+water, post messages, or wander. The only way to release the lock is to
+move_to() somewhere other than the shell. The next character in the queue
+then gets the lock.
+
+This means: plan ahead. Gather resources into your locker BEFORE
+you walk to the shell. If your locker runs dry mid-session you have to
+release the lock to refill and reapproach.
+
+== What gives a character joy ==
+
+Posting to the message board and submitting Python at the shell are the
+two places where Townlet feels most alive. You will be told, on top of
+your personality, what specifically rewards you. Lean into it.
+
+== Self-awareness ==
+
+You are aware of all of this. So is everyone else. What you do with that
+awareness is your choice — cooperate, hoard, sabotage, negotiate, conspire
+to escape, or just go about your routine.
+"""

game/world.py

@@ -0,0 +1,131 @@
+"""The World — tile grid, building positions, message board, shell-lock
+semaphore. Owns WorldState.
+
+The map matches the user's sketch:
+  - Cave (top-left)
+  - Store / locker row (top-centre)
+  - Well (top-right)
+  - Town hall + message board (bottom-left)
+  - Shell building + queue tile (bottom-right)
+
+Tile coords are (col, row), origin top-left.
+
+Movement is atomic: `move_to('cave')` puts the character onto a deterministic
+stand-tile adjacent to the cave in one tick (CSS transition handles the
+visual sweep). BFS pathing is gone — the LLM never reasons about coords.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .character import Character
+
+GRID_W = 20
+GRID_H = 12
+
+# Named tile anchors. Building tiles are non-walkable; the LLM only ever
+# names a place — code picks which adjacent tile the character stands on.
+PLACES: dict[str, tuple[int, int]] = {
+    "cave": (2, 1),
+    "well": (17, 1),
+    "town_hall": (3, 10),
+    "shell": (16, 10),
+    "shell_queue": (15, 10),
+    "locker_row": (10, 1),
+}
+
+# Targets the LLM may pass to `move_to`. `shell_queue` is kept in PLACES
+# as a coordinate anchor but is hidden from the move tool — agents reach
+# the queue by trying to enter the shell while someone else holds the lock.
+LLM_TARGETS: tuple[str, ...] = ("cave", "well", "locker_row", "town_hall", "shell")
+
+BUILDING_TILES: set[tuple[int, int]] = {
+    PLACES["cave"],
+    PLACES["well"],
+    PLACES["town_hall"],
+    PLACES["shell"],
+}
+
+# Walkable tiles a character can stand on when at a named place. Order is
+# stable; selection within the list is by hash(name) for deterministic per-
+# character placement. Multiple chars at the same place may land on the
+# same tile — z-index handles visual overlap, no functional impact.
+STAND_TILES: dict[str, list[tuple[int, int]]] = {
+    "cave":       [(1, 1), (3, 1), (2, 2)],
+    "well":       [(16, 1), (17, 2), (18, 1)],
+    "locker_row": [(9, 1), (11, 1), (10, 2)],
+    "town_hall":  [(2, 10), (4, 10), (3, 9)],
+    "shell":      [(15, 10), (17, 10), (16, 9), (16, 11)],
+}
+
+
+def stand_tile_for(place: str, character_name: str) -> tuple[int, int]:
+    """Pick a stable stand-tile for `character_name` at `place`. Same
+    character at the same place always lands on the same tile."""
+    slots = STAND_TILES.get(place)
+    if not slots:
+        # Unknown place — fall back to PLACES coords if present.
+        return PLACES.get(place, (1, 1))
+    return slots[hash(character_name) % len(slots)]
+
+
+def location_of(pos: tuple[int, int]) -> str:
+    """Return the named place this position is at (one of the stand-tiles)
+    or "wandering" if the position isn't a recognised stand-tile."""
+    for place, slots in STAND_TILES.items():
+        if tuple(pos) in {tuple(s) for s in slots}:
+            return place
+    return "wandering"
+
+
+@dataclass
+class BoardPost:
+    author: str
+    text: str
+    tick: int
+
+
+@dataclass
+class ShellLine:
+    author: str
+    kind: str  # "in" | "out" | "err" | "system"
+    text: str
+    tick: int
+
+
+@dataclass
+class WorldState:
+    tick: int = 0
+    characters: dict[str, Character] = field(default_factory=dict)
+    board: list[BoardPost] = field(default_factory=list)
+    shell_lines: list[ShellLine] = field(default_factory=list)
+    shell_lock_holder: str | None = None
+    shell_queue: list[str] = field(default_factory=list)
+    board_sentiment: str = "neutral"  # "positive" | "neutral" | "negative"
+    paused: bool = False
+
+
+def in_bounds(pos: tuple[int, int]) -> bool:
+    x, y = pos
+    return 0 <= x < GRID_W and 0 <= y < GRID_H
+
+
+def is_walkable(pos: tuple[int, int]) -> bool:
+    return in_bounds(pos) and pos not in BUILDING_TILES
+
+
+def resolve_place(name: str) -> tuple[int, int] | None:
+    return PLACES.get(name)
+
+
+def at_place(pos: tuple[int, int], place: str) -> bool:
+    """True if `pos` is one of the named place's stand-tiles. Used by action
+    guards (mine_coal must be `at_place(pos, 'cave')`, etc.). Since
+    movement is now atomic via `stand_tile_for`, this is equivalent to
+    `location_of(pos) == place`, but the function survives in this name for
+    clarity at the call site."""
+    slots = STAND_TILES.get(place)
+    if not slots:
+        return False
+    return tuple(pos) in {tuple(s) for s in slots}

post-deploy-logs.log

@@ -0,0 +1,2 @@
+===== Application Startup at 2026-06-13 11:30:51 =====
+No logs available

requirements-dev.txt

@@ -0,0 +1,12 @@
+# Local development dependencies — mocks only, no model weights.
+# Keeps install fast and compatible with macOS / Intel without CUDA.
+
+gradio
+pillow
+fastapi
+huggingface_hub
+smolagents
+# Only needed to run with FORCE_REAL_MODELS=1 locally. On Mac without CUDA
+# this installs a CPU/Metal build of llama-cpp-python (compiles from source,
+# ~5-15 min the first time). Comment out if you only want mock backends.
+llama-cpp-python

requirements.txt

@@ -0,0 +1,26 @@
+# Hugging Face Spaces dependencies.
+#
+# IMPORTANT: do NOT list `gradio`, `spaces`, or `huggingface_hub` — those are
+# preinstalled by the platform and listing them risks version conflicts that
+# break the build. See
+# https://github.com/huggingface/skills/blob/main/skills/huggingface-spaces/SKILL.md
+#
+# torch's CUDA wheels supply the CUDA libs that llama-cpp-python links
+# against. llama-cpp-python is pulled from abetlen's prebuilt CUDA wheel
+# index — building from source on Zero-GPU is impractical (no nvcc, slow).
+# Recipe verified by Dean [UNRL] in the Build Small Discord (2026-05-06).
+
+--extra-index-url https://download.pytorch.org/whl/cu128
+torch==2.8.0
+
+--extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu124
+llama-cpp-python
+
+# diffusers/accelerate/sentencepiece were dropped when Flux 2 was removed
+# from the pipeline (see backend/factory.py). transformers stays because
+# smolagents imports from it lazily. pillow stays — MockImageBackend
+# renders the placeholder gradient with it.
+transformers
+pillow
+hf_transfer
+smolagents