Skip to content

ci(timed-run): a core plan gives the world, the launcher and the load drivers their own cores (#2507) - #2573

Merged
genekogan merged 1 commit into
mainfrom
agent/2507-timed-run-cores
Nov 16, 2026
Merged

genekogan merged 1 commit into
mainfrom
agent/2507-timed-run-cores

Conversation

@genekogan

Copy link
Copy Markdown
Member

Problem

On the three-core timed runners, timed-run.mjs gives the world 2 physical cores and puts the launcher and the load driver together on the third. A scaling run therefore cannot tell "the world is at its limit" from "the bench is". Step 0 (on the issue) read 0.077 to 0.095 cores for the launcher and driver together at 200 viewers, which scales to about 1.9 to 2.4 cores at 5,000, so the shared core would become the limit. Closes #2507.

Acceptance

  • A1 cores is accepted, validated and recorded; a plan that does not fit is refused at the start gate (unit test in timed-run.test.mjs) — evidence: the test core plan (#2507): cores is accepted ... in node --test .github/scripts/timed-run.test.mjs -> 17 pass, 0 fail. On a real runner, run https://github.com/soulsimulation/souls/actions/runs/43823296471 (cores=world=2,launcher=1, viewers 50) was refused at its Start load step, before any load sampling, with the core plan world=2,launcher=1 needs 4 physical cores (at least one for the load drivers); this runner has 3 of its own. The plan is recorded in the receipt as inputs.cores and cpuSplit.plan.
  • A2 One viewers --viewers 50 run with cores: world=2,launcher=1 shows the launcher pinned apart from the driver in the receipt — evidence: run https://github.com/soulsimulation/souls/actions/runs/43823299362, receipt timed-run.json runs[0].cpuSplit: plan world=1,launcher=1, layout 1+1+1, world 0,24, launcher 1,25, load 2,26, launcherProcesses 1 with launcherAllowed ["1,25"] read back, worldAllowed ["0,24"]. Busy share (mean / busiest 5 s): world 0.348 / 0.772, launcher 0.031 / 0.054, load 0.029 / 0.142. Start load: own cores 0.013. The runners have 3 physical cores, so this ran the smaller plan the issue's Risks section allows (see Deviations).
  • A3 Default behaviour (no cores input) is unchanged: the same split as today in the receipt — evidence: run https://github.com/soulsimulation/souls/actions/runs/43823302599, no cores: receipt cpuSplit layout 2+1, physicalCores 3, world 9,33,10,34 (the first two physical cores), load 11,35, worldAllowed ["9-10,33-34"]. This is the same shape as the pre-change receipt of run 43781046865 (2+1, world the first two cores, load the third). The only addition is busy: world 0.233 / 0.446, load 0.052 / 0.151. No plan or launcher key, and inputs has no cores key. The default path of splitCores is unchanged, which the unit test asserts (splitCores(x, smt, null) deep-equals splitCores(x, smt)).

Proof

Tier: T0

  • proof.json: none needed at T0. The evidence is the unit test and the run receipts linked above.
  • clips: none (no UI)
  • images: none

What changed

  • timed-run.yml: a new cores input, world=N or world=N,launcher=M physical cores. It is passed on as INPUT_CORES.
  • timed-run.mjs:
    • parseInputs accepts a plan for the split commands only and validates it (parseCorePlan).
    • splitCores(own, siblingsOf, plan) gives the world the first N cores, the launcher the next M and the load drivers the rest (at least one). A plan that does not fit is refused with a plain message. Without a plan the split is exactly as before.
    • The Start load step checks the plan before it samples load, so a plan that does not fit is refused at the start gate.
    • pinWorlds also pins each launcher process (isLauncher: tools/world-launcher/launcher.mjs) onto the launcher's cores. A world the launcher starts is still moved on to the world's cores.
    • Every 5 s it samples each group's busy share from /proc/stat. cpuSplit.busy.<group> records { mean, peak5s }.
    • A run with a launcher in its plan fails if no launcher process was seen.

Deviations from the design

  • A2 names cores: world=2,launcher=1. Every souls-timed runner gives a job 3 physical cores, and that plan needs 4 (one is left for the load drivers), so the gate refuses it there (run 43823296471, the A1 evidence). A2 ran world=1,launcher=1, the smaller plan the issue's Risks section names, until a wide runner exists. The amended declaration was posted on the issue before any run.
  • The design's "each group's processor share" is recorded as each group's busy fraction of its own logical CPUs: the mean over the repeat and the busiest 5 s. Per-process CPU time is lost when processes exit, and the groups' cores are the job's own, so core busy is the share that counts.
  • Touches names docs/testing.md (the timed-run section). The timed-run section is in fact docs/testing/playtests.md ("Timed runs"), which the workflow's header names. The docs change went there (5 lines).

Self-audit

  • Checks run:
    • node --test .github/scripts/timed-run.test.mjs -> 17 pass, 0 fail
    • node tools/proof/tier.mjs -> T0
    • node .github/scripts/guards.mjs scrub --base origin/main -> 0 problems
    • the workflow YAML parses
  • Failed attempts: none.
  • Long tail / externalities:
    • Every split run (default too) now reads /proc/stat every 5 s in the control process. That is negligible, and it runs on the job's control process, not in the measured groups' pinned processes.
    • The receipt gains cpuSplit.busy. No consumer parses cpuSplit strictly.
  • Known limits:
    • A launcher's non-world children inherit the launcher's cores (the intended reading of "the launcher").
    • A world the launcher starts runs on the launcher's cores for up to 250 ms before it is re-pinned.
    • The busy shares are per core group, not per process. Two processes in the same group can't be told apart.
  • Docs: docs/testing/playtests.md "Timed runs": the cores input, the refusal and the recorded shares.

Changelog

Label no-changelog: CI tooling only.

Outside Touches

  • docs/testing/playtests.md (5 lines; it holds the timed-run section that Touches means, see Deviations)

Time

Started 07:18 UTC. Took about 32 min wall clock (07:18 to 07:50 UTC), of which about 25 min was waiting on the runners, so about 7 min of work against a ceiling of 2 h (runner waits not counted).

Risk

The only path that changes without a plan is the extra /proc/stat sampling and the busy field. If it misbehaves, a timed run fails at its Run step and someone dispatching would see it at once. To roll back, revert this PR.

🤖 Generated with Claude Code

… drivers their own cores (#2507)

The cores input (world=N or world=N,launcher=M) splits the runner's physical
cores; the launcher is pinned apart as the world is, a plan that does not fit
is refused at the start gate, and each run records each group's busy share.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@genekogan
genekogan marked this pull request as ready for review November 16, 2026 07:50
@genekogan genekogan added ci:run Open the CI window: run this ready PR's heavy CI jobs (docs/testing.md#ci-window) no-changelog Nothing user-facing; no changes/ fragment needed labels Nov 16, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Proof check: proof-ok passes

Tier T0 from .github/scripts/timed-run.mjs, .github/scripts/timed-run.test.mjs, .github/workflows/timed-run.yml, docs/testing/playtests.md (node tools/proof/tier.mjs).
Required at T0 (docs/process/PROOF-POLICY.yml): lint.

Check Status Detail
problem statement ok present
linked issue ok #2507
Acceptance criteria
Criterion Status Evidence
[x] A1 cores is accepted, validated and recorded; a plan that does not fit met the test core plan (#2507): cores is accepted ... in node --test .github/scripts/timed-run.test.mjs -> 17 pass, 0 fa
[x] A2 One viewers --viewers 50 run with cores: world=2,launcher=1 shows met run
[x] A3 Default behaviour (no cores input) is unchanged: the same split as t met run

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 genekogan added 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 08:31
@genekogan
genekogan added this pull request to the merge queue Nov 16, 2026
@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
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to failed status checks Nov 16, 2026
@genekogan genekogan removed the merge:ready Hand the PR to the merge train (.github/workflows/merge-train.yml) label Nov 16, 2026
@genekogan

Copy link
Copy Markdown
Member Author

Merge queue: this PR left the queue without merging (reason: CI_FAILURE), so it left the train. The failing run is on the gh-readonly-queue commit in the Actions tab.

Fix it and add merge:ready again.

@genekogan genekogan added 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 11:42
@genekogan
genekogan added this pull request to the merge queue Nov 16, 2026
Merged via the queue into main with commit 495752e Nov 16, 2026
145 of 164 checks passed
@genekogan
genekogan deleted the agent/2507-timed-run-cores branch November 16, 2026 12:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

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) no-changelog Nothing user-facing; no changes/ fragment needed

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Scaling M1 · Timed runs for the scaling gates give the world, the launcher and the load drivers their own cores

1 participant