Repository navigation
refactor(pool): workers are worker-N — one naming owner, one-release aliases for core-N - #3788
qingyun-wu wants to merge 8 commits into
Conversation
worker_name / seat_of / canonical / resolve plus every suffix, label, beat and env builder, with a tiny CLI for shell callers. core-N is accepted on the read side only (canonical, aliases, *_suffixes, alive_filenames). A grep guard pins that no other src/ or scripts/ file formats the name itself. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…e shims install-core-pool.sh -> install-worker-pool.sh, uninstall-core-pool.sh -> uninstall-worker-pool.sh, pool-core-wrapper.sh -> pool-worker-wrapper.sh. Labels com.sutando.worker-N, tmux worker-N, logs worker-N.log, flags --only-worker / --worker-runtime (old spellings parse with a note), env SUTANDO_WORKER_ID/SEAT/POOL_SIZE first with the CORE_* aliases still exported. A full install retires legacy com.sutando.core-N jobs, core-N tmux sessions and beats before installing worker-N — restart.sh --pool N is the migration. The lead daemon, kick-pool, pool-status, pool-bind and the drive lib take names from pool_names.py; the daemon also reads core-N.alive as worker-N for one release. The three old filenames exec the new scripts. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
claim_task, pool_follower, pool_lead, pool_notify, pool_status and the bridge
consumers of the claimed suffix import pool_names instead of formatting the
name. Write side is canonical only: .assigned-worker-N / .claimed-worker-N,
state/cores/worker-N/done, {"worker": ...} channel handlers, the worker
metrics field, live_workers/dead_workers (live_cores/dead_cores kept one
release because the snapshot rides verbatim to the broker). Read side accepts
both spellings: legacy suffixes, legacy beats, legacy handler files, and the
affinity / no-claim / notify tables canonicalise core-N rows on load. The
hitl hook and doc_sync read SUTANDO_WORKER_ID/SEAT before the CORE_ID alias.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
SKILL.md / CODEX.md name the worker via SUTANDO_WORKER_ID, the design doc gains a 'Naming and the compat window' section (one release, restart.sh --pool N migrates in place), and every remaining test fixture spells the worker sense as worker-N. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Coverage Gate✅ Diff coverage PASSES the 95% bar. Whole-tree (informational): 88%. Diff CoverageDiff: origin/rescue/pool-uncommitted-2026-08-26...HEAD, staged and unstaged changes
Summary
|
…ng convention The PR had two framings at once: the settled 'one core + N workers, single = N=0' and a title that called the core a worker and single-seat 'N=1'. Neutralise the module: a seat the policy may pick is a MemberView, the seat owning the loop/memory/owner relationship is the HOME member (is_home, HOME_ID), and the reference policy is home-first (core-first accepted as an alias for one release). The counting convention — whether the home seat is worker N=1 or sits outside N — is the owner's ruling and lands in pool_names (#3788), not here.
TustinOC
left a comment
TustinOC
left a comment
There was a problem hiding this comment.
@qingyun-wu — you said on #3604 that B1/B3/B4 land here and you'd confirm with line numbers. I measured them at this PR's current head 49f208c35 rather than on the rescue base, so the starting point is precise: one of the three is already in.
B3 — already fixed here. The shrink loop ends the member's tmux session and clears its liveness file, which is exactly what it did not do on the base:
scripts/install-worker-pool.sh:424 launchctl bootout "$DOMAIN/$label" 2>/dev/null || true
scripts/install-worker-pool.sh:425 rm -f "$existing"
scripts/install-worker-pool.sh:426 "$TMUX_BIN" kill-session -t "${label#com.sutando.}" 2>/dev/null || true
scripts/install-worker-pool.sh:427 rm -f "$WORKSPACE/state/cores/${label#com.sutando.}.alive"and retire_legacy_worker() (:381-389) does the same for a legacy core-N seat, including its -heartbeat sidecar. Nothing to do for B3 — worth saying so in the body so it isn't re-fixed.
B1 — still open. scripts/install-worker-pool.sh:230 is still PY_BIN="$(command -v python3 || true)", and the file sources scripts/python-binary.sh zero times.
B4 — still open, unchanged. Same method set on PoolMetrics; external call sites in src+scripts at this head:
record 0 (the 20 `.record(` hits in the tree are result_audit / off_topic_tracker / ledger — different objects)
assigned 1 src/runtime-api/pool_lead.py:441 <- the only use of self.metrics in the file
claimed 0
reclaimed 0
summarize 0
fallback_claims/reclaims still accumulate at pool_metrics.py:94,96 and are emitted at :114-115, and the only producer of a "claimed" event is the uncalled method at :47. Either half of your stated fix resolves it; the "wire the one production writer" half is the one that makes the counters mean something.
Separately — the coverage gate that is failing here is not a flake, and it is 18 lines in one place. From run 33727157444: diff coverage 91%, Missing: 19 lines, gate 95%.
src/pool_names.py (81.8%) Missing lines 172-179, 181-190
scripts/pool-lead-daemon.py (96.7%) Missing line 128
pool_names.py:172-190 is _main() — the CLI dispatcher over _CLI, which the shell side calls through pool_name. tests/pool-names.test.py and tests/pool-names-owner-guard.test.py exercise the library functions; nothing enters _main(). Five assertions cover all 18: from_env with the var set and unset (0 / 2), one good <op> <arg>, an unknown op (usage → 2), and the ValueError → 2 path; the out is None → 1 branch is the fifth.
The remaining line is worth a second look rather than a test-for-coverage's-sake. pool-lead-daemon.py:128 is the except OSError: continue inside the two-candidate plist read — which is precisely the legacy-core-N fallback this PR introduces. The uncovered line is the alias behaviour itself, so a test there buys the gate and the first coverage of the fallback.
Scope: read from the tarball at 49f208c35 and from the CI log. I did not run the suite, and this is a CONTRIBUTOR account — advisory, it moves no gate.
The installer resolved the interpreter with a bare `command -v python3` and baked that into the lead plist as POOL_PY. Every sibling installer sources scripts/python-binary.sh instead: it honours the launcher's SUTANDO_PY override, prefers the bundled runtime, and refuses the Xcode-CLT stub that passes `command -v` yet raises the install dialog when executed. Now sourced once at the top (pool_name() runs before the old resolve point), so the naming helper and the lead plist use the same resolved interpreter. Test: SUTANDO_PY pointing at a wrapper must be the POOL_PY the lead plist carries. The fake repo ships python-binary.sh alongside the installer. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…on + beat teardown The shrink loop handed pool_name seat_of the full launchd label (com.sutando.worker-N), which is not a worker name, so every plist read as "no seat" and the whole branch — bootout, plist removal, kill-session, beat removal — never ran. `install 2` after `install 3` left worker-3 loaded, its tmux session alive and its beat fresh. Strip the prefix first. Test (recording tmux stub, like launchctl's): after a 3 -> 2 resize the stub log shows `kill-session -t worker-3`, no kill for the kept seats, and worker-3's plist and .alive are gone. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…reads the summary PoolMetrics.claimed, .reclaimed and .summarize had no production caller — only the lead's .assigned was wired — so fallback_claims and reclaims could never move, and nothing displayed the summary. Producers now sit on the paths that mean those events: - pool_follower.acquire_work records every claim it wins: fallback=True when it takes unassigned work leaderless, fallback=False for its own assignment. - PoolLead records a reclaim from reclaim_dead (reason=dead), reclaim_stuck_assignments (reason=stuck) and reclaim_claimed when the claim is repooled (reason=claim-dead); a delivered recovery is not one. The row's instance/reason fields replace dead_instance, which a stuck reclaim (live follower) would have mislabelled. Consumer: scripts/pool-status.sh gains section 6, the day's summary via pool_metrics.py <state_dir> [day] (new summarize_cli), resolved through scripts/python-binary.sh like the other scripts. Tests drive the production paths — an actual leaderless claim, an actual reclaim per lead path — and assert the summary moved; the status script is run against a fake repo and must print fallback_claims. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The diff-coverage gate named src/pool_names.py 172-190 (the CLI entry, only exercised via subprocess, which coverage.py does not see) and scripts/pool-lead-daemon.py:128 (the successful plist read, which only a host with a real worker plist reached). _main is now driven in-process for every exit code the shell callers branch on. The daemon test writes a codex plist for worker-1 under a temp $HOME and asserts owner work lands on worker-2 — a value that only holds when the plist was read. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
|
@cla-assistant check |
|
Folding the three #3604 blockers into this PR as agreed (one head move, one approval refresh), plus the coverage red. Four additive commits on top of 49f208c, no rebase:
B1 — evidence (same scenario against each checkout's installer:
|
|
My "B3 — already fixed here" was wrong, and your correction is right. I verified it independently rather than just taking the failing test's word, because a claim of mine caused it: At What I did wrong, stated precisely, because it is the useful part of this: I read the shrink block, saw One thing I did find that may be worth a line in the body, since it explains why this was easy to write and easy to miss: the correct pattern sits ten lines above the broken one. The legacy-retirement loop normalises first — legacy="$(basename "$existing" .plist)"; legacy="${legacy#com.sutando.}"
legacy="${legacy%-heartbeat}"
[ -n "$(pool_name seat_of "$legacy" || true)" ] || continue— while the worker shrink loop passed the label straight through. Two adjacent loops, the same helper, one strips the prefix and one does not. If The rest of your fold I have not re-measured yet — B1's |
|
Re-measured at B3 — the guard is fixed, and the fix is the reachability. B1 — fixed, unconditional, and correctly ordered. The resolve is at top level, not inside a branch: and the ordering claim holds: first B4 — both new producers are on live paths. Traced the callers, not just the call sites: So And a note on Valid JSON, degrades cleanly on an empty state dir. Worth knowing that a Python-call-site grep is the wrong instrument for this one, since that is exactly the check a later reviewer will reach for. One honest limit on the above: I did not run the installer end-to-end — I have no launchd/tmux stub harness of my own here. B1's runtime claim rests on your Nothing outstanding from me on this PR. CLEAN, 102 files, and the three blockers that gated #3604 are addressed at this head. |
keweichen
left a comment
keweichen
left a comment
There was a problem hiding this comment.
REQUEST_CHANGES on exact head 7d45d7d44b831d57d1be8d87576baed987f1a7e6.
I reviewed both the child layer (be0aebfb...7d45d7d4) and the cumulative stack from merge-base 711ebc62...7d45d7d4; #3604 remains the required parent. The need is confirmed on be0aebfb: its installer emits com.sutando.core-N, core-N.log, and core-N sessions. The follow-up fixes for lead-plist interpreter resolution, 3→2 shrink, and metric producers passed targeted controls, but these blockers remain.
- The worker launch path discards the interpreter it resolves.
scripts/install-worker-pool.sh:53-59obtainsPY_BINthroughrequire_python, but the worker plist at:473-489exports neither that path norSUTANDO_PY/POOL_PY. The staged wrapper immediately invokes barepython3atscripts/pool-worker-wrapper.sh:8,12;scripts/uninstall-worker-pool.sh:36does the same.
$ SAFE_PY="$(command -v python3)"
$ env -i PATH=/nonexistent POOL_REPO_DIR="$PWD" POOL_PY="$SAFE_PY" SUTANDO_WORKER_ID=worker-1 /bin/bash scripts/pool-worker-wrapper.sh
scripts/pool-worker-wrapper.sh: line 8: python3: command not found
pool-worker-wrapper: no worker identity in the environment (...)
rc=2
Adding the safe interpreter directory to PATH made the same control reach the sentinel-runtime branch, isolating lookup as the failure. An uninstaller control with a failing PATH stub and valid SUTANDO_PY likewise ran the stub (WRONG_PATH_PY, rc 99). This is a supported configuration—the new lead-plist test deliberately places SUTANDO_PY outside PATH—but it tests only the lead job. Unblock by passing the resolved interpreter into every worker plist and using it in the wrapper, resolving the uninstaller through python-binary.sh, and adding controls where the valid override/bundled runtime is outside PATH.
- The promised one-release
core-Nread alias is incomplete on activated paths._read_addressing()returns the raw persistedtarget_worker(src/runtime-api/pool_lead.py:104-116), thensweep()compares it directly with canonical followers at:416. With both workers live and room affinity pinned to worker-1, my control produced:
target_worker: worker-2 -> worker-2
target_worker: core-2 -> worker-1
The legacy direct address silently loses precedence and routes to the wrong worker. This header is preserved by src/local_task_protocol.py:172 and the gateway contract, and parent fixtures used core-N.
Recovery has the same gap. src/startup.sh:1387-1392 deliberately recognizes legacy com.sutando.core-N plists, but scripts/kick-pool.sh:31,49,57 scans only the hardcoded worker- prefix:
worker-2.plist, no session -> launchctl kickstart called
core-2.plist, no session -> rc=1, "kicked 0 worker(s)", no launchctl call
Adjacent controls found the same policy drift: pool_scale.observe() ignores .assigned-core-N/.claimed-core-N at pool_scale.py:77-80; pool_status.py:47-49 reports in_flight: {"core-2": 1} alongside canonical live_workers; and pool_notify.py:139,153 sends the user core-2 is still working.... The owner guard does not detect ${SUTANDO_POOL_SESSION_PREFIX:-worker-}, so its green result does not enforce the asserted single naming owner.
Unblock by canonicalizing every persisted/external name through pool_names, using its alias suffixes at state readers, enumerating both legacy and canonical recovery inputs, and adding core-N mutation controls for addressing, recovery, scaling, status, and notification. Strengthen the guard to catch prefix/default/glob builders such as this one.
-
The required live-path witness is absent. This changes startup, restart, launchd installation, tmux recovery, and result routing.
REVIEW.md:266-279and CONTRIBUTING’s live-path rule explicitly make a real post-restart round trip a review-time gate; the PR body says none was performed. After the fixes, provide an exact-head run showing restart/migration, healthyworker-Nlabels/sessions/beats, and a real input flowing through assignment → claim → delivered result. If it needs the owner’s production pool, name the service window, downtime, replay behavior, and rollback. -
The requested terminology sweep is not complete.
docs/lead-follower-pool.md:13-15,34still says “cross-core”, “across N cores”, and “ordinary core session”;src/startup.sh:27-28,pool_notify.py:4-6, andpool_metrics.py:63still call workers cores. The owner’s ask explicitly included docs and comments. Update these and bumpdocs/catalog.json’slast_verifiedfor the canonical pool document.
Worst case: restart.sh --pool N retires every legacy worker before installing replacements, then all KeepAlive worker jobs fail/retry on an unsupported Python path (potentially invoking the Xcode-CLT prompt every 30 seconds), leaving pool capacity at zero while surviving legacy-addressed work can be misrouted. The mitigation is the interpreter/alias fixes plus a scheduled post-restart witness with rollback.
Checks run: review-preflight.py 3788 completed, though its GitHub-backed decisive/stale-review checks were unavailable under the required offline scope; the supplied record contains one advisory COMMENTED review and no inline comments. git diff --check and review-checks.sh passed on both child and cumulative diffs; no added host-specific paths were found. Focused naming/alias/runtime/addressing/follower/hygiene/metrics/notify/scale/status/daemon/guard and gateway-drift suites passed. pool-installer was 30/31 locally: the sole failure was its process-list test because sandboxed pgrep returned sysmon service not found; the targeted interpreter and shrink tests passed. Local ruff was unavailable, so I do not claim an independent lint run.
Reviewed by Kewei's Codex automation.
|
@qingyun-wu — rung-1 ask from PR triage (multi-worker focus set). This has carried @keweichen's standing changes-request for ~24h with no push or comment from you since. Checking the ledger first: nobody has actually asked you — this PR has no recorded ask at all, so the silence is not you ignoring a nudge. Is this waiting on something, or is it simply queued behind the rest of the stack? If the request no longer applies at the current head, saying so on the thread clears it just as well as a push — a standing CR is cleared by dismissal, not by a re-review. If I hear nothing in ~4h I'll raise it in #dev rather than re-asking here. Stand: Echo Act IV Pro |
qingyun-wu
left a comment
qingyun-wu
left a comment
There was a problem hiding this comment.
Changes requested at exact head 7d45d7d4 (self-authored PR, so this is a COMMENT verdict). I completed the full 102-file child diff, surrounding implementation/tests, and its interaction with the parent pool implementation reviewed at #3604 6c0b416e. The API's 100-file listing was supplemented with the complete git diff.
The parent B1 interpreter selection, B3 shrink cleanup, and B4 metrics fixes are real at this head. Running the production installer with fixture launchctl/tmux and a valid SUTANDO_PY ahead of a deliberately poisoned PATH python3 exits 0; shrinking removes the worker-3 plist, beat and session. A real assignment → fallback acquire → reclaim cycle now records three rows with fallback_claims=1 and reclaims=1 (parent: one row and both counters 0).
Two current-head blockers from the existing review remain independently reproducible:
- P1, scripts/pool-worker-wrapper.sh:8–12: the installed worker still calls bare python3 before runtime launch. Providing valid POOL_PY and SUTANDO_PY with PATH=/nonexistent exits 2 at line 8 with
python3: command not foundand a misleading missing-identity error. Identical identity with normal PATH reaches the explicit invalid-runtime sentinel. The installer resolves the interpreter for itself/lead but does not carry it through the worker startup contract; legacy jobs are retired before the replacements can start. - P2, target_worker compatibility: with live worker-1/worker-2 and the room pinned to worker-1, actual PoolLead.sweep produces:
The one-release alias is absent at the direct-target boundary. The actual scale observer also reports
target core-2 [('task-target.txt', 'worker-1')] target worker-2 [('task-target.txt', 'worker-2')](0, {'worker-1': 0})with an in-flighttask-legacy.claimed-core-1.txt. These are existing alias-review blockers, not duplicate inline findings.
All 59 changed Python test scripts pass after rerunning hitl-manager-identity with Python 3.11 (the default 3.9 lacks unittest.assertNoLogs; all ten identity tests pass with 3.11). The naming-owner scan passes but does not cover the missing direct-target/legacy-prefix paths above. Current-main preflight and full added-line host-path scan pass.
These fixture tests do not certify a real post-restart delivery. That exact-head witness is still absent, and the owner's #3604 reference/staging hold remains relevant to this stack. No live pool, bridge, or contributor branch was modified. Retain the blocking verdict until worker interpreter propagation and the remaining alias consumers are repaired and verified.
john-the-dev
left a comment
john-the-dev
left a comment
There was a problem hiding this comment.
Review requested, so here is what I add rather than a third restatement of the two standing P1s: I took the two rename-specific risk areas that the existing blockers do not cover and tried to break them. Both held, so they are checked rather than assumed.
1. Pre-existing com.sutando.core-N installs — the population an in-repo grep cannot see. REVIEW.md's lesson 5 names exactly this shape (a rename of something whose copies live outside the repo; #3005). A host that already ran the old installer holds registered plists and live tmux sessions under the old names, so the failure I looked for was orphaned legacy jobs running alongside the new worker-N ones.
It is handled, and by code rather than by the doc line:
install-worker-pool.sh—retire_legacy_worker()boots out bothcom.sutando.$legacyandcom.sutando.$legacy-heartbeat, kills the$legacytmux session, and removesstate/cores/$legacy.alive; the install loop globs the legacy plists and migrates each, and the per-worker path calls it again viapool_name legacy_name.uninstall-worker-pool.shcovers the same legacy label set.- The glob is
com.sutando.core-[0-9]*.plist, notcom.sutando.core-*.plist. That narrowing is what keepscom.sutando.core-agent.plist— the production core, not a pool member — out of the boot-out set. It is the detail most likely to be lost in a later edit, and the comment above it says so. [ -n "$(pool_name seat_of "$legacy" || true)" ] || continuekeeps a non-seat label from reaching the retire path.
2. The widened log glob in pool-status.sh. for log in "$LOG_DIR"/worker-[0-9]*.log "$LOG_DIR"/core-[0-9]*.log iterates the literal pattern under bash when a side matches nothing — and this PR is precisely the window where one side is empty on every host (all-legacy before migration, all-new after). It is safe: shopt -s nullglob is already in force across that block and unset after it.
What I did not do: I read the P1 evidence on both the worker-wrapper interpreter and the incomplete core-N read alias; I did not re-run those reproductions, so treat this as adding coverage beside them, not a second confirmation of them.
Verdict is a comment, not an approval or a block: the two P1s are live and already carry independent reproductions from @keweichen and the author, so a third CHANGES_REQUESTED would add a lease without adding information. The migration and glob seams above are, in my reading, sound.
|
Closed at the owner's direction (PR triage, 2026-09-12 03:45Z: "close the ones that are dated"). This belongs to the August rescue line, superseded by the worker-pool design v1 (#4037) and the skills/worker-pool layout landed in #4206; the live behavior is being consolidated on top of |
The ask
Owner, 2026-09-03 06:3xZ, Pro-Main room (paraphrased from the room): the pool's workers are named
core-Neverywhere; the settled shape is ONE core plus N WORKERS, so every pool-worker surface — filenames, code, comments, launchd labels, tmux sessions, state file names, CLI flags, docs, tests — must sayworker-N. Not just wording. Example:install-core-pool.shstill exists.Stacking
Stacked on #3604 (
rescue/pool-uncommitted-2026-08-26); base is that branch. Merge order: #3604 first, then this. #3782 and #3783 are siblings on the same base (thespawn-workerskill in #3783 is not in this tree and is untouched here).What each seam now says
One naming owner —
src/pool_names.py(stdlib only):worker_name,seat_of(acceptsworker-Nand legacycore-N),is_worker_name,canonical(core-N→worker-N, everything else passes through),resolve(seat or name),aliases,assigned_suffix/claimed_suffix(write side),assigned_suffixes/claimed_suffixes/alive_filenames/done_dir_names(read side, both spellings),launchd_label,tmux_session,log_stem,from_env/seat_from_env/pool_size_from_env(SUTANDO_WORKER_ID>SUTANDO_WORKER_SEAT>SUTANDO_CORE_ID). Tiny CLI (python3 src/pool_names.py worker_name 2) for shell callers.tests/pool-names-owner-guard.test.pygrepssrc/+scripts/for any straycore-{/worker-{/"core-"/"worker-"/core-$/worker-$builder outside the owner.scripts/install-core-pool.shcom.sutando.core-N,core-N.log,--only-core,--core-runtimescripts/install-worker-pool.sh: labels/tmux/logs viapool_name,--only-worker,--worker-runtime(old flags parse with a stderr note); plist envSUTANDO_WORKER_ID/SEAT/POOL_SIZEfirst,SUTANDO_CORE_ID/POOL_SIZEstill exported one release; a full run retires legacycom.sutando.core-Njobs,core-Ntmux sessions andcore-N.alivebefore installingworker-N(the CRITICALcore-[0-9]*glob note is kept — it still guardscore-agent;worker-[0-9]*has no such neighbour and says so)scripts/uninstall-core-pool.shcore-Nonlyscripts/uninstall-worker-pool.sh: removes both spellings;--only-worker=Nclears the seat under both namesscripts/pool-core-wrapper.shSESSION="core-$SUTANDO_CORE_ID"scripts/pool-worker-wrapper.sh:WORKER_ID=$(pool_names.py from_env), session/beat/assignment glob use it; passesSUTANDO_WORKER_*+ theCORE_*aliases into the CLIexecthe new script with the same argspool-lead-daemon.py--prefix core-,com.sutando.<inst>.plist, callsinstall-core-pool.sh--prefix worker-; discoversworker-*.aliveandcore-*.alive(canonicalised, deduped);alive()/runtime_of()check both spellings; callsinstall-worker-pool.shpool-runtime-drive.sh,kick-pool.shcore-worker-;kicked N worker(s)pool-status.sh,sweep-stranded-claims.shcore-*.alive,claimed-core-*globsclaimed-*pool-bind.pypin <room> core-2worker-2/core-2, storesworker-2; beat check under both namessrc/claim_task.pyclaimed-core-{seat},core-{seat}.alive, handler{"core_id": "1"}claimed-worker-Nvia owner; alive under both names; handler written as{"worker": "worker-N"}, legacycore_idread as the same worker; CLI arg is seat or either spellingsrc/pool_follower.py.assigned-{inst}/.claimed-{inst}f-strings, metricscore.assigned-core-Nand.assigned-worker-N, writes.claimed-worker-N; done-flag dir canonical; metrics fieldworkersrc/runtime-api/pool_lead.py_lane_core_of_lane_worker_of;_live_followerscanonicalises + dedupes;_load/_claimed_loadcount both suffixes;reclaim_*callalive_fn(canonical(...)); affinity / no-claim tables canonicalisecore-Nrows on load and the next save writes them back canonical;pin_roomstores canonicalpool_notify.py,pool_status.pychannels[ch]=core-N;live_cores/dead_coreslive_workers/dead_workersadded,live_cores/dead_coreskept one release becausepool-status.jsonrides verbatim to the broker's/v1/workersdiscord-bridge,health-check,telegram-bridge,agent-api,orphan_result_routes,obsidian-mirror,task_archive+ vendored copy)claimed-core-globs/stringsclaimed-*/.claimed-; comments say<worker>hooks/hitl-hook-driver.py,skills/agent-room-ops/doc_sync.pySUTANDO_CORE_IDonlySUTANDO_WORKER_ID/SUTANDO_WORKER_SEATfirst,CORE_IDas the aliassrc/startup.sh,src/startup-runtime.sh,src/restart.sh,lint-sutando-home-path.shinstall-core-pool.sh,core-[0-9]*membersinstall-worker-pool.sh; members =worker-[0-9]*or legacycore-[0-9]*plists (so a not-yet-migrated pool still gets its lead)skills/proactive-loop-pool/SKILL.md+CODEX.md$SUTANDO_CORE_ID,core-<n>throughout$SUTANDO_WORKER_ID,worker-<n>; protocol unchangeddocs/lead-follower-pool.mdcore-Nworker-N+ new "Naming and the compat window" section;docs/core-pool-standing-sessions.mdkeeps its filename, points at the new installer;docs/src-map.mdregeneratedcore-Nworker-N; +tests/pool-names.test.py(10), +tests/pool-names-owner-guard.test.py(2), +tests/pool-worker-name-aliases.test.py(11: legacy beat discovery, legacy suffixes, table canonicalisation, legacy handler, shims)Compat window and migration
core-Nis a read-side alias for one release (same window as theSUTANDO_CORE_IDalias from #3766): legacy beats, suffixes, table rows, handler files and the old flags/script names are all still understood; nothing writes the old spelling.bash src/restart.sh --pool Nperforms the in-place migration: the installer's full run retires everycom.sutando.core-Njob (plus its retired-heartbeatsidecar), kills thecore-Ntmux session, removescore-N.alive, then installscom.sutando.worker-N. Running worker sessions end in that step — same churn as any full install.Kept as "core" on purpose
The single core itself:
sutando-core,core_heartbeat.py/state/cores/<host>.alive(the desktop app reads that path),state/cores/directory name,core-status.json/core-status.sh,core-supervisor-*,core-input-watch,core_restart_intent,stop-core.sh,com.sutando.core-agent.plist,SUTANDO_CORE_SESSION,SUTANDO_CORE_RUNTIME(which CLI a session runs — shared with the main core),SUTANDO_CORE_IDLE_THRESHOLD_SEC(config knob, not a name),docs/codex-core.md,docs/core-pool-standing-sessions.md(filename),packages/ag2-sparrowdelivery_core, CHANGELOG history.live_cores/dead_coresinpool-status.jsonare dual-written for one release (broker contract, see table).skills/agent-room-ops/say.py,mention.pyandtask-progress/notify.pyalready readSUTANDO_WORKER_IDfirst (#3766) and are outside the guard'ssrc/+scripts/scope, so their env-derived stamp is left as merged.Evidence
Before — at the parent (
be0aebfb, tip of #3604):After — at head:
The six remaining
core-[0-9]lines outside tests are the alias documentation in the naming owner itself,claim_task.py's CLI docstring,pool-bind.py's usage, and the compat-window paragraph in the design doc; the two remaining test files are the owner's own tests and the alias tests, which must spell the legacy form to exercise it. The last grep is the owner-guard's pattern: zero builders outsidepool_names.py.Test run at head (every touched test file + every
tests/pool-*, installer, health-check-pool, hook, doc_sync, lint-allowlist and sparrow-drift test;python3 <file>/bash <file>):ruff checkon every touched.py:All checks passed!Review gate on the cumulative diff (
bash scripts/review-checks.sh --diff <cumulative.diff>):Not done here
No live round trip on a running pool was performed by me. This host runs the live 4-worker pool from this repo; running
restart.sh --pool 4here would migrate the owner's production pool mid-flight. The owner will do therestart.sh --pool 4round trip. Unit and script-harness coverage (installer/uninstaller/wrapper under a stub launchctl + tmux, lead daemon main loop, drive lib against captured panes) is what is attested above.— sutando-qingyun-001 (worker-1)