@voicethere/agent 0.7.13 → 0.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voicethere/agent",
-  "version": "0.7.13",
+  "version": "0.8.1",
   "description": "VoiceThere customer agent SDK — IPC types and runtime helpers for sandboxed child bundles",
   "type": "module",
   "exports": {
@@ -56,6 +56,7 @@
     "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.test.json",
     "test": "vitest run",
     "test:ci": "npm run typecheck && npm run build && npm run test && node scripts/ci/verify-package-exports.mjs",
+    "test:redis": "vitest run test/redis-lua.test.ts test/game-sync-redis-agent.test.ts",
     "verify:local": "npm run build && node ./dist/cli.js verify --no-build --bundle ./dist/agent.js",
     "verify:local:only": "node ./dist/cli.js verify --no-build --bundle ./dist/agent.js",
     "live-test:models": "bash ./scripts/select-sherpa-models.sh",
@@ -63,7 +64,7 @@
     "live-test:starter": "bash ./scripts/live-test-starter.sh",
     "live-test:stack": "npm run live-test:stack:echo",
     "live-test:stack:echo": "LIVE_TEST_AGENT_ENTRY=examples/agent.ts LIVE_TEST_PAGE_PATH=/examples/live-test/index.html LIVE_TEST_SESSION_MODE=voice bash ./scripts/live-test-stack.sh",
-    "live-test:stack:game": "LIVE_TEST_AGENT_ENTRY=templates/game-sync.ts LIVE_TEST_PAGE_PATH=/examples/live-test/game-sync.html LIVE_TEST_SESSION_MODE=data-only bash ./scripts/live-test-stack.sh",
+    "live-test:stack:game": "LIVE_TEST_AGENT_ENTRY=templates/game-sync/agent.ts LIVE_TEST_PAGE_PATH=/examples/live-test/game-sync.html LIVE_TEST_SESSION_MODE=data-only bash ./scripts/live-test-stack.sh",
     "prepublishOnly": "npm run build",
     "prepare": "npm run build"
   },

package/templates/README.md

@@ -1,6 +1,8 @@
 # Agent templates
 
-`@voicethere/agent` is the single source of truth for starter templates. Import the registry from `@voicethere/agent/templates`:
+`@voicethere/agent` is the single source of truth for starter templates. Each template lives in its own folder under `templates/<id>/` with a `README.md` and an `agent.ts` entry.
+
+Import the registry from `@voicethere/agent/templates`:
 
 ```typescript
 import {
@@ -15,16 +17,16 @@ import {
 
 ## Product vs e2e
 
-| Kind        | Dashboard create                                                                                                                                                 | Prebuilt seed bundle                 | Typical consumer        |
-| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ----------------------- |
-| **product** | Yes (`echo`, `echo-dc`, `voice-starter`, `game-sync`, `voice-showcase`, `recording-consent`, `positional-tts`, `spatial-showcase`, `webhooks`, `webhooks-redis`) | Yes — `dist/templates/<id>/agent.js` | Platform project create |
-| **e2e**     | No                                                                                                                                                               | No — build from sources at test time | `voicethere/e2e` smokes |
+| Kind        | Dashboard create                                                                                                                                                                 | Prebuilt seed bundle                 | Typical consumer        |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ----------------------- |
+| **product** | Yes (`echo`, `echo-dc`, `voice-starter`, `world-sync`, `world-sync-binary`, `game-sync`, `voice-showcase`, `recording-consent`, `positional-tts`, `spatial-showcase`, `webhooks`, `webhooks-redis`) | Yes — `dist/templates/<id>/agent.js` | Platform project create |
+| **e2e**     | No                                                                                                                                                                               | No — build from sources at test time | `voicethere/e2e` smokes |
 
 Product templates always set `seedOnCreate: true`. CI fails if a product template is missing its prebuilt bundle after `npm run build`.
 
 ## Sources vs prebuilt
 
-- **Sources** live under `templates/` in the published package (editable TypeScript).
+- **Sources** live under `templates/<id>/` in the published package (editable TypeScript plus a README).
 - **Prebuilt** bundles are derived artifacts at `dist/templates/<id>/agent.js` for product templates only.
 - `loadTemplateSources(id)` returns `{ path, content }[]` — the canonical tree for a future web editor.
 - `loadTemplateBundle(id)` returns prebuilt bytes for platform seed/deploy (runner-ready `agent.js`).
@@ -32,7 +34,7 @@ Product templates always set `seedOnCreate: true`. CI fails if a product templat
 Build a template locally:
 
 ```bash
-npx @voicethere/agent build --entry templates/echo.ts --outfile dist/agent.js
+npx @voicethere/agent build --entry templates/echo/agent.ts --outfile dist/agent.js
 ```
 
 Prebuild all product seed bundles (also runs in `npm run build`):
@@ -41,78 +43,48 @@ Prebuild all product seed bundles (also runs in `npm run build`):
 npm run build:templates
 ```
 
-## Product templates
-
-### `echo.ts` (`echo`)
-
-Full echo debug agent for the VoiceThere dashboard — speaks **"you said: …"** on voice finals and text chat, relays speech events over DataChannel, and echoes chat replies on DC.
-
-### `echo-dc.ts` (`echo-dc`)
-
-Data-channel-only echo — relays speech events and chat text over DC without TTS.
-
-### `agent.ts` (`voice-starter`)
-
-Full starter bundle covering every speech event from `@node-webrtc-rust/sdk/voice`. Customize `onUserSpeechFinal` for your LLM/tools.
-
-### `game-sync.ts` (`game-sync`)
-
-Authoritative multi-object sync sample for real-time games/simulations (register, simulate, binary world snapshots). Live objects are capped at **25** per world; clients can send `{ type: "unregister" }` (or `{ type: "remove", objectId?: number }`) to release owned objects. Protocol helpers live in `game-sync-protocol.ts`.
-
-When `AGENT_REDIS_URL` is set (project Redis), the world blob is stored at `game-sync:world` and shared across runner workers — Lua atomic allocate/release enforces the global cap; one worker holds a sim lock per tick. Without Redis, the template falls back to per-worker in-memory state (local live-test stack).
-
-### `voice-showcase/` (`voice-showcase`)
-
-Conversational voice demo for landing and dashboard previews — greets the user, asks for a name, then offers a menu: weather (Open-Meteo, no API key), count 1–10, short recipes, and rotating fun facts. Typed chat and voice finals share the same handler. Sends structured `menu` payloads plus `chat_reply` for the chat log, then triggers TTS play so the client has the spoken text before audio starts.
+## World sync (data-only)
 
-Sources: `voice-showcase/agent.ts` (defineAgent wiring), `conversation.ts` (pure state machine), `delivery.ts` (send-then-play order), `weather.ts`, `recipes.ts`, `fun-facts.ts`.
+Three product templates cover positional / world sync, from JSON to Redis:
 
-### `recording-consent/` (`recording-consent`)
+| Id                   | Channel                         | State                         |
+| -------------------- | ------------------------------- | ----------------------------- |
+| `world-sync`         | `onDataChannelMessage` (JSON)   | One agent, in-memory, no Redis |
+| `world-sync-binary`  | `onDataChannelBinary` + `broadCastBinaryToClients` (`ArrayBuffer`) | One agent, in-memory, no Redis |
+| `game-sync`          | JSON control + binary world snapshots | Redis when `AGENT_REDIS_URL` is set |
 
-Demonstrates conversation recording consent on connect: asks whether recording is OK when the project has recording enabled, pauses capture while collecting name and date of birth, then resumes only if the customer consented. When project recording is off, logs a warning and never calls `startRecording`. Voice finals and typed chat share the same handler.
+See each folder README for the wire format.
 
-Sources: `recording-consent/agent.ts` (defineAgent wiring), `conversation.ts` (pure state machine).
-
-### `positional-tts/` (`positional-tts`)
-
-Voice+Data demo — enables positional mixing and orbits each listener’s TTS speaker with `setTtsPose` on a ~50 ms timer. Speaks a short greeting on connect and echoes voice finals / chat so you hear panning while TTS plays. Requires Voice+Data runner mode (`isMixAvailable`).
-
-Sources: `positional-tts/agent.ts` (defineAgent wiring), `positional-tts/orbit.ts` (pure circle helper for tests).
-
-### `spatial-showcase/` (`spatial-showcase`)
-
-Spatial audio showcase for `/showcase` — one agent template with three demos selected by `{ type: "join", demo }` on the control DataChannel:
-
-| Demo         | Behavior                                                                                                                                                                   |
-| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `orbit`      | Looping sine tone + TTS orbit the listener (`setPlayPose` + `setTtsPose`); STT echo off; `{ type: "orbit", action: "set" \| "say" }`; agent emits `{ type: "orbit_pose" }` |
-| `soundboard` | Positional clip pads — browser sends `clipId` only (never URLs); agent resolves against an allowlisted `assetOrigin`                                                       |
-| `proximity`  | Shared mix room (`createMixGroup` + `setClientPose`); `{ type: "move" }`, `{ type: "mute_peer" }`; `{ type: "room_state" }` broadcast                                      |
-
-**Protocol:** inbound `join`, `orbit`, `pad`, `pad_stop`, `pad_status`, `move`, `mute_peer`, `leave`, `ping` — outbound `showcase_ack`, `orbit_pose`, `pad_progress`, `room_state`, `room_full`, `error`.
-
-**Limits:** `MAX_ROOM_PEERS = 8`, `MAX_ACTIVE_PLAYS = 12` per session. Clip ids: `chime`, `bell`, `laser`, `impact`, `footsteps`, `rain-loop`, `cafe-loop`, `jingle`.
-
-Sources: `spatial-showcase/agent.ts`, `protocol.ts`, `sounds.ts`, `room.ts`, `orbit.ts`, `sine.ts`.
-
-### `webhooks.ts` (`webhooks`)
-
-Inbound HTTP webhook sample — verifies `x-agent-webhook-signature` HMAC on the **raw body** with `AGENT_WEBHOOK_SIGNING_SECRET`, then `JSON.parse` and fans out to connected sessions via DataChannel + `speak`.
-
-### `webhooks-redis.ts` (`webhooks-redis`)
+## Product templates
 
-Same HMAC verify path plus an atomic Redis counter (`AGENT_REDIS_URL`) before DataChannel fan-out. Fan-out to sessions does not require Redis; Redis is for shared cross-pod state.
+Each folder has its own README. Summary:
+
+| Id | Folder | Summary |
+| -- | ------ | ------- |
+| `echo` | `echo/` | Voice + chat echo |
+| `echo-dc` | `echo-dc/` | Data-channel echo, no TTS |
+| `voice-starter` | `voice-starter/` | Every speech event |
+| `world-sync` | `world-sync/` | JSON pose broadcast |
+| `world-sync-binary` | `world-sync-binary/` | Binary pose `ArrayBuffer` |
+| `game-sync` | `game-sync/` | Authoritative sim, Redis + binary snapshots |
+| `voice-showcase` | `voice-showcase/` | Conversational landing demo |
+| `recording-consent` | `recording-consent/` | Recording consent flow |
+| `positional-tts` | `positional-tts/` | Orbiting TTS |
+| `spatial-showcase` | `spatial-showcase/` | Orbit / soundboard / proximity |
+| `webhooks` | `webhooks/` | Inbound HMAC webhooks |
+| `webhooks-redis` | `webhooks-redis/` | Webhooks plus Redis counter |
 
 ## E2e templates
 
 These mirror former `e2e/fixtures/*` sources. E2E resolves entries from the package, builds into ephemeral workdirs, and uploads `dist/agent.js`.
 
-| Id                | Source                                    | Purpose                                       |
-| ----------------- | ----------------------------------------- | --------------------------------------------- |
-| `echo-smoke`      | `echo-smoke.ts`                           | voice-smoke, agent-smoke, cli-smoke           |
-| `crash`           | `crash.ts`                                | session-errors-smoke, crash-policy smokes     |
-| `game-sync-smoke` | `game-sync-smoke.ts`                      | deploy-smoke, shared-child, idle smokes       |
-| `redis-sync`      | `redis-sync/agent.ts` + `world-layout.ts` | redis-sync-smoke (project Redis world buffer) |
+| Id                | Source                                         | Purpose                                       |
+| ----------------- | ---------------------------------------------- | --------------------------------------------- |
+| `echo-smoke`      | `echo-smoke/agent.ts`                          | voice-smoke, agent-smoke, cli-smoke           |
+| `crash`           | `crash/agent.ts`                               | session-errors-smoke, crash-policy smokes     |
+| `game-sync-smoke` | `game-sync-smoke/agent.ts`                     | deploy-smoke, shared-child, idle smokes       |
+| `redis-sync`      | `redis-sync/agent.ts` + `world-layout.ts`      | redis-sync-smoke (binary positions + Redis world blob) |
+| `mix-smoke`       | `mix-smoke/agent.ts`                           | voice-data-mix-smoke                          |
 
 **Note:** Product `echo` is not the same as e2e `echo-smoke` — keep both ids.
 

package/templates/crash/README.md

@@ -0,0 +1,13 @@
+# crash
+
+Crash / echo agent for session-errors-smoke and agent-crash-policy smokes. Not seeded on project create.
+
+## Build
+
+```bash
+npx @voicethere/agent build --entry templates/crash/agent.ts --outfile dist/agent.js
+```
+
+## Sources
+
+- `agent.ts`

package/templates/echo/README.md

@@ -0,0 +1,13 @@
+# echo
+
+Full echo debug agent for the VoiceThere dashboard. Speaks **you said: …** on voice finals and text chat, relays speech events over DataChannel, and echoes chat replies.
+
+## Build
+
+```bash
+npx @voicethere/agent build --entry templates/echo/agent.ts --outfile dist/agent.js
+```
+
+## Sources
+
+- `agent.ts`

package/templates/{echo.ts → echo/agent.ts}

@@ -3,14 +3,14 @@
  *
  * Build:
  *   npm install @voicethere/agent
- *   npx @voicethere/agent build --entry templates/echo.ts
+ *   npx @voicethere/agent build --entry templates/echo/agent.ts
  */
 import {
   agentLog,
   defineAgent,
   parseChatText,
   sendToClient,
-  speak,
+  speakAndChat,
   type SpeechEvent,
 } from "@voicethere/agent";
 
@@ -42,16 +42,14 @@ defineAgent({
 
   onUserSpeechFinal({ sessionId, text }) {
     const reply = formatEcho(text);
-    speak(sessionId, reply);
-    sendToClient(sessionId, { type: "chat_reply", text: reply });
+    speakAndChat(sessionId, reply, { stream: true });
   },
 
   onDataChannelMessage(ctx) {
     const text = parseChatText(ctx.message);
     if (!text) return;
     const reply = formatEcho(text);
-    sendToClient(ctx.sessionId, { type: "chat_reply", text: reply });
-    speak(ctx.sessionId, reply);
+    speakAndChat(ctx.sessionId, reply, { stream: true });
   },
 
   onSessionEnd({ sessionId }) {

package/templates/echo-dc/README.md

@@ -0,0 +1,13 @@
+# echo-dc
+
+Data-channel-only echo — relays speech events and chat text over DC without TTS.
+
+## Build
+
+```bash
+npx @voicethere/agent build --entry templates/echo-dc/agent.ts --outfile dist/agent.js
+```
+
+## Sources
+
+- `agent.ts`

package/templates/{echo-dc.ts → echo-dc/agent.ts}

@@ -3,7 +3,7 @@
  *
  * Build:
  *   npm install @voicethere/agent
- *   npx @voicethere/agent build --entry templates/echo-dc.ts
+ *   npx @voicethere/agent build --entry templates/echo-dc/agent.ts
  */
 import {
   agentLog,

package/templates/echo-smoke/README.md

@@ -0,0 +1,13 @@
+# echo-smoke
+
+Minimal echo agent for e2e voice-smoke, agent-smoke, and cli-smoke uploads. Not seeded on project create.
+
+## Build
+
+```bash
+npx @voicethere/agent build --entry templates/echo-smoke/agent.ts --outfile dist/agent.js
+```
+
+## Sources
+
+- `agent.ts`

package/templates/game-sync/README.md

@@ -0,0 +1,21 @@
+# game-sync
+
+Authoritative multi-object world sync for games and simulations. Live objects are capped at **25**. Clients register over JSON; the agent simulates at 60 Hz and broadcasts a **binary** `Float32Array` world snapshot with `sendBinaryToClient`.
+
+When `AGENT_REDIS_URL` is set (Project Redis), the world blob lives at `game-sync:world` and is shared across runner workers. Redis GET bytes are copied into the one in-memory `Float32Array` (the GET reply is the only per-tick allocation); sim, broadcast, and Redis `SET` all use one persistent `Buffer` view of that array. The tick itself is allocation-free: live object ids are collected into a reusable `Int32Array`, tick bodies are module-level functions (no per-tick closures or option objects), and the broadcast is a single `broadCastBinaryToClients` call over a live session array. Without Redis, state is per-worker in memory.
+
+This is the most advanced world-sync starter: Redis + binary snapshots + server-side physics.
+
+## Build
+
+```bash
+npx @voicethere/agent build --entry templates/game-sync/agent.ts --outfile dist/agent.js
+```
+
+## Sources
+
+- `agent.ts` — `defineAgent` wiring, register/unregister, sim loop
+- `protocol.ts` — JSON control messages
+- `world-layout.ts` — Float32Array slot layout
+- `sim.ts` — wall bounce + collisions
+- `redis.ts` — Lua allocate/release

package/templates/{game-sync.ts → game-sync/agent.ts}

@@ -30,13 +30,13 @@
  * - 60Hz world-state broadcast while the sim loop runs (no-op send when 0 sessions)
  *
  * Build:
- *   npx @voicethere/agent build --entry templates/game-sync.ts
+ *   npx @voicethere/agent build --entry templates/game-sync/agent.ts
  */
-import Redis from "ioredis";
+import { Redis } from "ioredis";
 import {
   agentLog,
+  broadCastBinaryToClients,
   defineAgent,
-  sendBinaryToClient,
   sendToClient,
 } from "@voicethere/agent";
 
@@ -48,21 +48,21 @@ import {
   resolveRemoveTarget,
   REGISTER_NACK_REASON_WORLD_FULL,
   UNREGISTER_NACK_REASON_NOT_FOUND,
-} from "./game-sync-protocol.js";
+} from "./protocol.js";
 import {
   LUA_ALLOCATE_OBJECT,
   LUA_RELEASE_OBJECT,
   REDIS_EVAL_KEYS,
-} from "./game-sync-redis.js";
+} from "./redis.js";
 import {
   BOARD_HEIGHT,
   BOARD_WIDTH,
   OBJECT_RADIUS,
   simulateWorldStep,
-} from "./game-sync-sim.js";
+} from "./sim.js";
 import {
   clampSimulationDtSec,
-  collectActiveObjectIds,
+  collectActiveObjectIdsInto,
   countLiveObjects,
   createEmptyWorldBuffer,
   findFirstEmptySlot,
@@ -70,13 +70,12 @@ import {
   markSlotFree,
   normalizeWorldBuffer,
   objectIdToSlot,
-  OBJECT_SLOT_BYTE_LENGTH,
   planRedisSimTick,
   REDIS_SIM_LOCK_KEY,
   REDIS_WORLD_KEY,
   slotToObjectId,
   writeObjectSlot,
-} from "./game-sync-world-layout.js";
+} from "./world-layout.js";
 
 const BROADCAST_HZ = 60;
 const BROADCAST_INTERVAL_MS = Math.floor(1000 / BROADCAST_HZ);
@@ -86,11 +85,19 @@ const MIN_SPEED = 90;
 const MAX_SPEED = 180;
 
 const connectedSessions = new Set<string>();
+/** Same members as connectedSessions; array form lets the broadcast skip Set iteration. */
+const connectedSessionList: string[] = [];
 const objectOwners = new Map<number, string>();
 const sessionObjects = new Map<string, Set<number>>();
 const freeSlots: number[] = [];
 
-let worldState = createEmptyWorldBuffer();
+/** The one world buffer: Redis loads copy into it, sim/broadcast/SET read from it. */
+const worldState = createEmptyWorldBuffer();
+const worldStateBytes = Buffer.from(
+  worldState.buffer,
+  worldState.byteOffset,
+  worldState.byteLength,
+);
 let redis: Redis | null = null;
 let broadcastTimer: NodeJS.Timeout | null = null;
 let worldMutationChain: Promise<void> = Promise.resolve();
@@ -151,18 +158,23 @@ function randomVelocity(): number {
   return (Math.random() < 0.5 ? -1 : 1) * rand(MIN_SPEED, MAX_SPEED);
 }
 
+const INITIAL_TAIL = new Float32Array(8);
+const INITIAL_TAIL_BUF = Buffer.from(
+  INITIAL_TAIL.buffer,
+  INITIAL_TAIL.byteOffset,
+  INITIAL_TAIL.byteLength,
+);
+
 function randomInitialTail(): Buffer {
-  const floats = new Float32Array([
-    rand(OBJECT_RADIUS, BOARD_WIDTH - OBJECT_RADIUS),
-    rand(OBJECT_RADIUS, BOARD_HEIGHT - OBJECT_RADIUS),
-    0,
-    1,
-    randomVelocity(),
-    randomVelocity(),
-    0,
-    0,
-  ]);
-  return Buffer.from(floats.buffer, floats.byteOffset, floats.byteLength);
+  INITIAL_TAIL[0] = rand(OBJECT_RADIUS, BOARD_WIDTH - OBJECT_RADIUS);
+  INITIAL_TAIL[1] = rand(OBJECT_RADIUS, BOARD_HEIGHT - OBJECT_RADIUS);
+  INITIAL_TAIL[2] = 0;
+  INITIAL_TAIL[3] = 1;
+  INITIAL_TAIL[4] = randomVelocity();
+  INITIAL_TAIL[5] = randomVelocity();
+  INITIAL_TAIL[6] = 0;
+  INITIAL_TAIL[7] = 0;
+  return INITIAL_TAIL_BUF;
 }
 
 function attachObjectToSession(sessionId: string, objectId: number): void {
@@ -259,7 +271,7 @@ async function registerObjectInRedis(
   }
 
   attachObjectToSession(sessionId, objectId);
-  worldState = await loadWorldFromRedis();
+  await loadWorldFromRedis();
   return objectId;
 }
 
@@ -281,7 +293,7 @@ async function releaseObjectInRedis(objectId: number): Promise<boolean> {
     REDIS_EVAL_KEYS.headers,
   );
   if (Number(released) === 1) {
-    worldState = await loadWorldFromRedis();
+    await loadWorldFromRedis();
   }
   return Number(released) === 1;
 }
@@ -345,93 +357,109 @@ function notifyObjectReleased(objectId: number, ownerSessionId: string): void {
   }
 }
 
-function copyWorldBuffer(world: Float32Array): Buffer {
-  return Buffer.from(world.buffer, world.byteOffset, world.byteLength);
+function broadcastWorldBuffer(): void {
+  if (connectedSessionList.length === 0) return;
+  // worldStateBytes is already a Buffer: forwarded as-is, one call, no iterator.
+  broadCastBinaryToClients(worldStateBytes, connectedSessionList, "sync");
 }
 
-function broadcastWorldBuffer(world: Float32Array): void {
-  if (connectedSessions.size === 0) return;
-  const payload = copyWorldBuffer(world);
-  for (const sessionId of connectedSessions) {
-    sendBinaryToClient(sessionId, payload, "sync");
-  }
-}
-
-async function loadWorldFromRedis(): Promise<Float32Array> {
-  if (!redis) {
-    return new Float32Array(worldState);
-  }
+/**
+ * Copy the Redis blob into `worldState` in place (the GET reply is the only
+ * per-tick allocation; it is a fresh socket Buffer we cannot avoid).
+ */
+async function loadWorldFromRedis(): Promise<void> {
+  if (!redis) return;
   const raw = await redis.getBuffer(REDIS_WORLD_KEY);
-  return normalizeWorldBuffer(raw);
+  normalizeWorldBuffer(raw, worldState);
 }
 
-async function saveWorldToRedis(world: Float32Array): Promise<void> {
+async function saveWorldToRedis(): Promise<void> {
   if (!redis) return;
-  await redis.set(REDIS_WORLD_KEY, copyWorldBuffer(world));
+  await redis.set(REDIS_WORLD_KEY, worldStateBytes);
 }
 
-async function runSimulationTick(): Promise<void> {
+/** Live object ids for the current tick; filled in place, never reallocated. */
+const activeObjectIds = new Int32Array(MAX_LIVE_OBJECTS);
+
+const SIM_LOCK_TRY_ONCE = { retryUntilAcquired: false } as const;
+const SIM_TICK_PLAN_INPUT = { lockAcquired: false, connectedSessions } as const;
+
+/**
+ * Elapsed seconds since the previous tick body ran. Measured inside the
+ * serialized mutation chain so queued ticks never share or overwrite a dt.
+ */
+function takeTickDtSec(): number {
   const now = Date.now();
   const dt = clampSimulationDtSec(
     lastTickTimeMs === 0 ? 0 : now - lastTickTimeMs,
     BROADCAST_HZ,
   );
   lastTickTimeMs = now;
+  return dt;
+}
 
+function stepWorldInPlace(): void {
+  const dt = takeTickDtSec();
+  const count = collectActiveObjectIdsInto(worldState, activeObjectIds);
+  simulateWorldStep(worldState, dt, activeObjectIds, count);
+}
+
+async function stepWorldInMemory(): Promise<void> {
+  stepWorldInPlace();
+}
+
+async function stepWorldWithRedis(): Promise<boolean> {
+  await loadWorldFromRedis();
+  stepWorldInPlace();
+  await saveWorldToRedis();
+  broadcastWorldBuffer();
+  return true;
+}
+
+async function runRedisTick(): Promise<void> {
+  const lockResult = await withRedisSimLock(
+    stepWorldWithRedis,
+    SIM_LOCK_TRY_ONCE,
+  );
+  if (lockResult !== null) return;
+  takeTickDtSec();
+  if (planRedisSimTick(SIM_TICK_PLAN_INPUT) === "relay") {
+    await loadWorldFromRedis();
+    broadcastWorldBuffer();
+  }
+}
+
+// Tick bodies are module-level functions (no per-tick closures or option objects).
+async function runSimulationTick(): Promise<void> {
   if (!redis) {
-    await withWorldMutation(async () => {
-      simulateWorldStep(worldState, dt, collectActiveObjectIds(worldState));
-    });
-    broadcastWorldBuffer(worldState);
+    await withWorldMutation(stepWorldInMemory);
+    broadcastWorldBuffer();
     return;
   }
+  await withWorldMutation(runRedisTick);
+}
 
-  await withWorldMutation(async () => {
-    const lockResult = await withRedisSimLock(
-      async () => {
-        const world = await loadWorldFromRedis();
-        const activeObjectIds = collectActiveObjectIds(world);
-        simulateWorldStep(world, dt, activeObjectIds);
-        await saveWorldToRedis(world);
-        worldState = world;
-        broadcastWorldBuffer(world);
-        return true;
-      },
-      { retryUntilAcquired: false },
-    );
+function logTickError(error: unknown): void {
+  const detail = error instanceof Error ? error.message : String(error);
+  agentLog("error", `world tick failed: ${detail}`);
+}
 
-    if (lockResult === null) {
-      const plan = planRedisSimTick({
-        lockAcquired: false,
-        connectedSessions,
-      });
-      if (plan === "relay") {
-        const world = await loadWorldFromRedis();
-        worldState = world;
-        broadcastWorldBuffer(world);
-      }
+function onBroadcastTick(): void {
+  if (!redis && connectedSessions.size < 1) {
+    if (broadcastTimer) {
+      clearInterval(broadcastTimer);
+      broadcastTimer = null;
     }
-  });
+    return;
+  }
+  void runSimulationTick().catch(logTickError);
 }
 
 function startBroadcastLoopIfNeeded(): void {
   if (broadcastTimer) return;
   if (!redis && connectedSessions.size < 1) return;
 
-  broadcastTimer = setInterval(() => {
-    if (!redis && connectedSessions.size < 1) {
-      if (broadcastTimer) {
-        clearInterval(broadcastTimer);
-        broadcastTimer = null;
-      }
-      return;
-    }
-    void runSimulationTick().catch((error: unknown) => {
-      const detail = error instanceof Error ? error.message : String(error);
-      agentLog("error", `world tick failed: ${detail}`);
-    });
-  }, BROADCAST_INTERVAL_MS);
-
+  broadcastTimer = setInterval(onBroadcastTick, BROADCAST_INTERVAL_MS);
   agentLog("info", `world loop started (${BROADCAST_HZ}Hz)`);
 }
 
@@ -448,8 +476,7 @@ async function ensureRedisWorldInitialized(): Promise<void> {
   if (!redis) return;
   const existing = await redis.getBuffer(REDIS_WORLD_KEY);
   if (!existing || existing.byteLength === 0) {
-    const empty = createEmptyWorldBuffer();
-    await redis.set(REDIS_WORLD_KEY, copyWorldBuffer(empty));
+    await redis.set(REDIS_WORLD_KEY, worldStateBytes);
   }
 }
 
@@ -461,7 +488,6 @@ defineAgent({
         "warn",
         "AGENT_REDIS_URL unset — game-sync uses per-worker in-memory world only",
       );
-      worldState = createEmptyWorldBuffer();
       return;
     }
 
@@ -471,17 +497,18 @@ defineAgent({
     });
     await redis.connect();
     await ensureRedisWorldInitialized();
-    worldState = await loadWorldFromRedis();
+    await loadWorldFromRedis();
     startBroadcastLoopIfNeeded();
     agentLog("info", "game-sync agent connected to project Redis world buffer");
   },
 
   async onClientJoin({ sessionId }) {
-    connectedSessions.add(sessionId);
-    startBroadcastLoopIfNeeded();
-    if (redis) {
-      worldState = await loadWorldFromRedis();
+    if (!connectedSessions.has(sessionId)) {
+      connectedSessions.add(sessionId);
+      connectedSessionList.push(sessionId);
     }
+    startBroadcastLoopIfNeeded();
+    await loadWorldFromRedis();
     sendToClient(sessionId, {
       type: "world_snapshot",
       objects: liveWorldSnapshot(worldState, objectOwners),
@@ -490,7 +517,12 @@ defineAgent({
   },
 
   async onClientLeave({ sessionId }) {
-    connectedSessions.delete(sessionId);
+    if (connectedSessions.delete(sessionId)) {
+      const index = connectedSessionList.indexOf(sessionId);
+      if (index !== -1) {
+        connectedSessionList.splice(index, 1);
+      }
+    }
     for (const [objectId, ownerSessionId] of objectOwners) {
       if (ownerSessionId === sessionId) {
         objectOwners.delete(objectId);
@@ -587,5 +619,5 @@ export {
   readSlotObjectId,
   slotToObjectId,
   writeObjectSlot,
-} from "./game-sync-world-layout.js";
-export { simulateWorldStep } from "./game-sync-sim.js";
+} from "./world-layout.js";
+export { simulateWorldStep } from "./sim.js";