Skip to content

fix(walk): a two-body wait cycle is recovered in seconds, one walker steps aside (#2596) - #2605

Merged
genekogan merged 4 commits into
mainfrom
agent/2596-goal-wait-cycle
Nov 16, 2026
Merged

genekogan merged 4 commits into
mainfrom
agent/2596-goal-wait-cycle

Conversation

@genekogan

@genekogan genekogan commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Problem

Walkers whose goals touch could wait a minute for each other. One stands at the end of its walk waiting for the other to leave its spot (walk.goal-occupied), the other waits for it to get out of the way (traffic.person), or two stand face to face. In a crowd, routing round the other finds nothing, so only the one-minute bound ended the wait (deadlock.cycle, then route.blocked): a Soul visibly stood for a minute and then gave up a walk that had room. In N3's jam sweep (30 bodies converging on one fire ring), this ended 10 walks in 5 of 12 variants on main. Closes #2596.

The fix is in the existing deadlock recovery, under a new logged runtime policy, cycle-recover/1 (cfg cycleRecoverV1, in rt.services). It follows the cede-passage/1 pattern: a RUNTIME_POLICY_FLAGS entry, a named state-hash input (cycleRecoverPolicy), WorldHost.enableCycleRecoverV1, and one rules event adopted at boot after cede-passage/1. History before that event replays without it, so an old log with a 3-s cycle still reaches the same clock-frontier hash. Without the policy, every tick is as on main.

  • Earlier recovery for cycles (mars/viewer/engine/runtime/waits.ts). A cycle that has stood unchanged for 3 s rarely clears by itself: in the 12-variant jam, the reviewer measured one that cleared at 70 ticks. So under the policy its members request recovery once the cycle has stood unchanged for CYCLE_RECOVER_TICKS (60 ticks, 3 s) instead of DEADLOCK_TICKS (200 ticks, 10 s). Waits on someone who may still move keep the 10 s, and the deadlock.cycle report still waits for DEADLOCK_TICKS.
  • One of the pair steps aside (mars/viewer/engine/locomotion/walk.ts, recoverWait and stepAsideInCycle). The existing person/load re-plan is tried first, exactly as before. If it does not break a two-body cycle, one of the pair takes the face-off detour that entity worlds already use (stepAside, factored out of resolveFaceoff unchanged): it walks to the nearest free spot clear of the other's way, waits there until the other has passed, then walks back on. The one standing at the end of its walk goes first, since it comes back to the same spot. The recovery reports deadlock.stepped-aside.

N5's local-pass design (docs/design/local-steering.md) does not apply when the blocker stands on the goal, so it could not cover this case.

Acceptance

  • A1 Reproduce from N3's jam scene as a focused engine test that fails today: a mutual goal-occupied wait ends only at the one-minute bound. — evidence: node --test packages/engine-mars/src/goal-wait-cycle.test.ts -> 2 pass. The same file run against main's walk.ts and waits.ts (with only the read-only mutualWaits helper added) -> 2 fail. A1 on main: h_jam16 failed route.blocked at 1604, h_jam26 ... at 1695, h_jam18 ... at 1809, and the longest two-body wait cycle is 1193 ticks. The scene is N3's 30-body jam from 10 m to 1.9 m with no rotation. On main without N3's rule, the 8 m, 1.9 m, no-rotation scene ends with no walk at the bound, so I used the variant that does. It has both kinds of goal-occupied cycle: goal-occupied against person, and two bodies each standing on the other's spot.
  • Policy off is tick-identical to main. The per-tick stateHash() chain over 2200 ticks of all 12 jam variants is equal between this branch with the policy off and main 1655b393f (an extracted copy of main's engine, run through the same script). The off test in goal-wait-cycle.test.ts also pins main's three bound refusals at their ticks.
  • A2 The wait cycle is detected and resolved in a few seconds rather than a minute, by the existing deadlock recovery or the local steering of N5's design note (PR 2571). No new teleport, no movement path outside the walk. State hashes are unchanged on the walk-perf goldens and the walk gate wherever no such cycle occurs. — evidence: node --test packages/engine-mars/src/goal-wait-cycle.test.ts -> pass. In the A1 scene, recovery steps a body aside in walk.goal-occupied / traffic.person and walk.goal-occupied / walk.goal-occupied cycles, and the longest two-body wait cycle is 61 ticks (3 s; 1193 on main). Across all 12 variants the longest is 137 ticks (6.9 s): 75 ticks of the walk's own re-plan ladder, then 60 ticks to recovery. The test bar is under 200 ticks, before the 10-s deadlock report would name the cycle. The detour is the walk's existing face-off detour, stepped by stepWalk, and runtime.violations (motion.teleport included) is empty in every variant. Goldens: node --test on walk-perf, take-golden, captured-hash, walk, deadlock, deadlock-recovery and 11 more in mars/viewer/engine/test -> 141 pass, none regenerated. Walk gate: node tools/test-harness/walk/walk.mjs -> "walk: no place worse than the baseline" on all five worlds.
  • A3 Across the 12 variants, no walk ends by the one-minute bound. — evidence: node --test packages/engine-mars/src/goal-wait-cycle.test.ts -> pass ("A3 across the 12 variants"); sweep score: main ends 10 walks by the bound in 5 of 12 variants; this branch ends none, with 30/30 arrived in every variant and no violations.

Proof

Tier: T3 (node tools/proof/tier.mjs: engine path)

  • proof.json: https://assets.eden.art/proofs/pr-2605/proof-3.json (head ac25a1b1e; the reviewer verdict is added by the coordinator at sign-off)
  • clips: waived by the coordinator (no clip kit stages a crowd at one spot). The engine tests and the sweep are the evidence.
  • images: none
  • playtest: the 12-variant jam sweep, base (main 1655b39) against candidate (223746c), two repeats each. The engine is deterministic, so the repeats are byte-identical. Score.
variant (start m, goal m, turned slot) main: last end tick main: ended by the bound this PR: last end tick
8, 1.9, 0 808 none 808
8, 1.9, 1/6 2088 h_jam08 799
8, 1.9, 1/3 640 none 816
8, 2.4, 0 672 none 672
8, 2.4, 1/6 851 none 851
8, 2.4, 1/3 600 none 600
10, 1.9, 0 1817 h_jam16, h_jam26, h_jam18 675
10, 1.9, 1/6 2143 h_jam06, h_jam07 868
10, 1.9, 1/3 1898 h_jam10 749
10, 2.4, 0 1815 h_jam09, h_jam00, h_jam28 583
10, 2.4, 1/6 680 none 680
10, 2.4, 1/3 880 none 880

Self-audit

  • Checks run:
    • node --test packages/engine-mars/src/goal-wait-cycle.test.ts -> 4 pass: policy off pinned to main, the hash input, A1/A2 and A3 with it on. The first cut, run against main's code, failed as above.
    • node --test apps/server/src/edge-runtime-rules.test.ts -> 4 pass (boot order with cycle-recover/1 last)
    • per-tick state-hash chains, policy off against main 1655b393f, 12 variants × 2200 ticks -> identical
    • node --test in mars/viewer/engine/test/ on captured-hash, deadlock-recovery, deadlock, make-way-claims, make-way-detour-snapshot, make-way-wait, open-jam, paired-walk, people-grid-patch, social-resume, social, take-golden, vehicle-deadlock, walk-perf, walk-point-at, walk-settle-wait and walk -> 141 pass, 0 fail
    • node --test in packages/engine-mars/src/ on runtime-policy-registry, cede-passage, concurrent-link-egress-policy, concurrent-link-egress, doorway-passing, item-approach-wait, make-way-detour-snapshot, shared-water-wait, stair-make-way, stall-release-support, wait-bound and goal-wait-cycle -> 68 pass, 0 fail
    • tsc --noEmit -p mars/viewer, -p packages/engine-mars, -p apps/server -> clean
    • node tools/test-harness/walk/walk.mjs -> "walk: no place worse than the baseline" (the "better" places are main's, not this change: the audit is static navigation)
    • node tools/changelog/compile.mjs --check -> valid; node .github/scripts/guards.mjs scrub --base origin/main -> 0 problems
  • Failed attempts: the first cut stepped aside a body whose other walker was on a stair leg. The face-off's clear-of-the-way test reads the other's walk leg, so concurrent-link-egress.test.ts threw (pointAt, reading 'length'). Fixed by requiring both of the pair to be on walk legs, as resolveFaceoff does under concurrentLinkEgressV1. Before that, the step-aside also required the mover to be still (v < 0.02), but a body settling at its goal reads 0.05, so the goal-occupied side never qualified; the check was dropped (the record must still be blocked).
  • Long tail / externalities: with the policy off (any history before its rules event), no change: per-tick state hashes equal main's. With it on, nothing changes and no extra work is done where no cycle stands. mutualWaits runs only inside a recovery request, and the cycle set is read from episodes that already exist. Where a cycle stands for 3 s, every action with a recovery hook gets its one attempt at 3 s instead of 10 s: walks, carries, and rides (recoverRide). The SequenceRunner's "certified blocked" early stop, timed from that attempt, also comes 7 s sooner for cycles. A carry's gathering walkers share one walk exec under the carry's id, so they never step aside: stepAsideInCycle requires the walk's own exec on both sides. Accepted trade-off: in one of the 7 variants with no bound end on main (8 m to 1.9 m, turned 1/3), the last arrival is 176 ticks later (816 against 640). A step aside resolved a cycle the crowd would have cleared by itself. Six of those seven variants end on the same tick as main.
  • Known limits: only two-body cycles step aside. A longer cycle (A waits for B, B for C, C for A) still gets only the existing re-plan; none occurred in the 12 variants. The step-aside spot search is the face-off's (16 directions, 0.8 to 4 m, a route of at most 6 m round the other body); if no spot qualifies for either body, the wait falls back to today's behaviour. The jam is native genesis only. In entity worlds the existing 1-s face-off usually acts first.
  • Docs: docs/mars/movement.md, "Persistent waits and bounded recovery".

Changelog

changes/2596-goal-wait-cycle.md

Risk

Only worlds that adopt cycle-recover/1 change, from its rules event on; rollback is a later rules event setting it false. A walk in a two-body cycle now moves after 3 s, where before it stood until the bound. The move is the existing face-off detour, which entity worlds have used since October. It is snapshotted (make-way-detour-snapshot.test.ts passes), stepped by the walk itself, and guarded by the same body-step and intrusion checks. What could go wrong is a step aside into a crowd that blocks someone else. That would show up as a new person-wait, which gets its own recovery, never a stuck Soul. The 12-variant sweep is the scenario: it covers both goal-occupied cycles and face-offs. Old snapshots restore unchanged (moverWaits has the same shape).

Outside Touches

  • docs/mars/movement.md: the recovery's description and the policy.
  • packages/engine-mars/src/engine.ts: the policy flag, its state-hash input and the restore paths (cede-passage/1 pattern, 11 lines).
  • apps/server/src/world.ts: enableCycleRecoverV1 (3 lines).
  • apps/server/src/edge-runtime-rules.ts: boot adoption after cede-passage/1 (3 lines).
  • apps/server/src/edge-runtime-rules.test.ts: the boot-order indices shift by one, plus asserts for the new last rule (mechanical, 10 lines changed).
    These were added at the coordinator's review request.

Time

Started 12:19 UTC, PR opened 12:33, handed back 12:36 UTC. Review fixes ran 12:45 to 12:50 UTC. About 22 min of wall-clock work in total against a 3 h ceiling.

🤖 Generated with Claude Code

Coordinator sign-off (T3): two independent reviewer passes. The first requested cycle-recover/1 gating plus the carry and wording fixes. The delta re-check requested the stepAside mover parameter. All are resolved: policy-off state-hash chains match main over 12 variants × 2200 ticks, and policy plumbing matches cede-passage/1 point for point. Clip waived: no clip kit on main shows a crowd at one spot; the jam sweep and walk gate are the evidence.

…steps aside (#2596)

Walkers whose goals touch could wait a minute for each other: one stands at the
end of its walk waiting for the other to leave its spot (walk.goal-occupied),
the other waits for it to get out of the way (traffic.person), or two stand face
to face. Routing round failed in the crowd and only the one-minute bound ended
the walk (route.blocked).

The deadlock recovery now asks a cycle's members for recovery once the cycle
has stood unchanged for CYCLE_RECOVER_TICKS (3 s) instead of DEADLOCK_TICKS
(10 s; the report is unchanged). When the existing person/load replan does not
break a two-body cycle, one of the pair takes the existing face-off detour
(stepAside, factored out of resolveFaceoff): the one at the end of its walk
first. Nothing changes where no cycle stands.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@genekogan genekogan added the ci:run Open the CI window: run this ready PR's heavy CI jobs (docs/testing.md#ci-window) label Nov 16, 2026
@genekogan
genekogan marked this pull request as ready for review November 16, 2026 12:35
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Proof check: proof-ok passes

Tier T3 from apps/server/src/edge-runtime-rules.test.ts, apps/server/src/edge-runtime-rules.ts, packages/engine-mars/src/engine.ts, packages/engine-mars/src/goal-wait-cycle.test.ts (node tools/proof/tier.mjs).
Required at T3 (docs/process/PROOF-POLICY.yml): T2; scenario playtest with repeats_per_arm repeats per arm; reviewer agent pass; maintainer sign-off.

Waived by the maintainer with the proof:waived label.

Check Status Detail
maintainer sign-off ok waived by @genekogan (proof:waived)

Proof links: 0 video, 0 image, no proof.json.

Updated on every edit, push, label and review. How to fill it: .claude/skills/journal/SKILL.md. T3-T4 also need the maintainer's sign-off (tools/proof/gate.mjs). A maintainer can waive with the proof:waived label.

genekogan and others added 2 commits November 16, 2026 07:45
… as a logged runtime policy (#2596)

Review of PR 2605: an old log with a cycle of 3 s or more would replay
differently at boot (clock-frontier.replay-differs). Both changes now run only
under cycle-recover/1 (cfg cycleRecoverV1, rt.services), a named state-hash
input adopted at boot after cede-passage/1 by one rules event; history before
it replays without it. Off is tick-identical to main (per-tick state hash chains
of the 12 jam variants equal; the off test pins main's bound refusals).

Also: a carry's shared gather exec never steps aside (walkExecs(rt).get(ex.id)
must be ex, and the other's exec must be its own); "a cycle never clears by
itself" is now "rarely" with the measured figure; resolveFaceoff's doc names
the native path.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@genekogan genekogan added ci:run Open the CI window: run this ready PR's heavy CI jobs (docs/testing.md#ci-window) and removed ci:run Open the CI window: run this ready PR's heavy CI jobs (docs/testing.md#ci-window) labels Nov 16, 2026
@genekogan

Copy link
Copy Markdown
Member Author

Review fixes pushed, head ac25a1b1e:

  • Blocking: both changes now run only under cycle-recover/1 (cfg cycleRecoverV1, rt.services), following the cede-passage/1 pattern. That means a RUNTIME_POLICY_FLAGS entry, the cycleRecoverPolicy state-hash input, the restore paths, WorldHost.enableCycleRecoverV1, and boot adoption after cede-passage/1, with the order test updated.
    • Off is tick-identical to main: the per-tick stateHash() chains of all 12 variants over 2200 ticks equal main 1655b393f's. A new off test pins main's three bound refusals.
    • goal-wait-cycle.test.ts runs with the policy on: 4 pass.
  • Carry case: stepAsideInCycle returns when walkExecs(rt).get(ex.id) !== ex, and skips when oex.actor !== who.
  • Wording: "rarely clears by itself", with the reviewer's measured 70 ticks, in waits.ts and movement.md. The resolveFaceoff doc now names the native path.
  • PR body: discloses rides and the SequenceRunner's certified-blocked early stop, and notes the 176-tick variant as the accepted trade-off.
  • Checks: engine-mars 68 pass, viewer engine 141 pass, edge-runtime-rules.test.ts 4 pass. tsc is clean for viewer, engine-mars and server. Walk gate: no place worse.
  • Proof: proof.json https://assets.eden.art/proofs/pr-2605/proof-2.json. review is left for you.
  • CI: ci:run re-added on the new head.

…n main (#2596)

A carry's gathering walkers share one walk exec under the carry's id, so
moverEx.actor can be another crew member than the body resolveFaceoff chose.
Also: movement.md lists cycle-recover/1 among the boot policies (cede-passage/1
is no longer last); the changelog fragment says it is a logged rule adopted at boot.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@genekogan genekogan added ci:run Open the CI window: run this ready PR's heavy CI jobs (docs/testing.md#ci-window) and removed ci:run Open the CI window: run this ready PR's heavy CI jobs (docs/testing.md#ci-window) labels Nov 16, 2026
@genekogan

Copy link
Copy Markdown
Member Author

Delta fixes pushed, head 5201385cc:

  • Blocker: stepAside(rt, mover, moverEx, forEx) now takes the mover id. resolveFaceoff passes the mover it computed, as on main, and stepAsideInCycle passes m.actor. With the policy off, the per-tick state-hash chains of the 12 jam variants still equal main's.
  • Focused test: not built within the ~20 min budget. A carry in gather reports running, never blocked, so resolveFaceoff from the solo walker's side only reaches the shared exec when a deadlock overlay names that walker.
    • My doorway probes (viewer runtime, a wall with a 1 m gap, a 2-crew carry, a solo walker with an id below the crew's, six placements) did produce face-offs.
    • They never reached that path: the per-tick hash chains were identical on main, the previous head ac25a1b1e and this head.
    • The fix is checked by reading instead: resolveFaceoff with stepAside inlined is main's code line for line.
  • Docs: cede-passage/1 is no longer marked "last" in movement.md, and cycle-recover/1 is in the boot policy list. The changelog fragment says it is a logged rule adopted at boot.
  • Checks: engine-mars (goal-wait-cycle, make-way-detour-snapshot, doorway-passing, concurrent-link-egress, cede-passage, stair-make-way) 32 pass. Viewer (deadlock-recovery, deadlock, make-way-detour-snapshot, make-way-wait, walk, walk-perf, take-golden, captured-hash) 60 pass. tsc viewer is clean.
  • CI: ci:run re-added.

@genekogan genekogan added approved:maintainer Maintainer sign-off on a T3+ PR they authored (GitHub forbids self-approval) proof:waived Maintainer waives the proof-ok check for this PR (say why in a comment) merge:ready Hand the PR to the merge train (.github/workflows/merge-train.yml) ci:run Open the CI window: run this ready PR's heavy CI jobs (docs/testing.md#ci-window) and removed ci:run Open the CI window: run this ready PR's heavy CI jobs (docs/testing.md#ci-window) labels Nov 16, 2026
@genekogan
genekogan enabled auto-merge November 16, 2026 13:22
@genekogan
genekogan added this pull request to the merge queue Nov 16, 2026
Merged via the queue into main with commit 99d0369 Nov 16, 2026
90 of 98 checks passed
@genekogan
genekogan deleted the agent/2596-goal-wait-cycle branch November 16, 2026 14:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

approved:maintainer Maintainer sign-off on a T3+ PR they authored (GitHub forbids self-approval) ci:run Open the CI window: run this ready PR's heavy CI jobs (docs/testing.md#ci-window) merge:ready Hand the PR to the merge train (.github/workflows/merge-train.yml) proof:waived Maintainer waives the proof-ok check for this PR (say why in a comment)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Walkers whose goals touch can wait a minute for each other (goal-occupied wait cycle)

1 participant