[qingyun-wu]

Summary

Phase 2a of the multi-core agent pool. Ships the two foundation pieces that are safe to land before the pool-aware skill:

• src/claim_task.py + 7 unit tests including a 2-process race test (forked subprocesses, verifies exactly one wins via POSIX-atomic rename).
• scripts/install-core-pool.sh N (default N=3) and scripts/uninstall-core-pool.sh.

Stacked on #881 (the multi-core-pool design doc). Once #881 merges, rebase the base to main and this lands cleanly.

Regression-prevention posture

1. Opt-in by default. Default behavior unchanged — pool only activates when install-core-pool.sh runs.
2. Pre-flight refuse: install REFUSES to create plists when the /proactive-loop-pool skill (Phase 2b) doesn't exist on disk — unless --force is passed — so today's install can't quietly create broken pool members that loop-restart on missing skill and burn quota.
3. Narrow glob: both scripts use com.sutando.core-[0-9]*.plist, NOT the wider com.sutando.core-*.plist. Critical — see "Regression caught during self-test" below.
4. Idempotent install: re-running with smaller N removes excess plists; re-running with same N updates in place.
5. Logs preserved on uninstall: $SUTANDO_WORKSPACE/logs/core-*.log kept for post-mortem.
6. Input sanitization: claim_task.py rejects .., /, dot-prefixed task_id / core_id (CodeQL py/path-injection class).

Regression caught + fixed during self-test

Original uninstall glob com.sutando.core-*.plist engulfed com.sutando.core-agent.plist — the pre-existing Sutando.app production launchd agent, NOT a pool member. Self-test removed it; recovered via cp .plist.bak .plist && launchctl bootstrap. Both scripts now use com.sutando.core-[0-9]*.plist (numeric-suffix-only) with a prominent comment citing this regression at each glob site. Saved as durable memory (feedback_specific_globs_system_paths.md) so the lesson outlives this PR.

What's NOT in this PR (Phase 2b, separate)

• /proactive-loop-pool skill that wedges the claim call before task pickup.
• Side-effect helper done-flag gate (~10 helpers across Python+TS bridges).
• Boot-time orphan-scan watchdog (release stale claims when sessions crash).
• Per-session state/cores/core-<n>/ heartbeat generalization.

Without Phase 2b, installing the pool at N>1 would result in 3× duplicate processing of every task. The install script's pre-flight refuse blocks this — owner can --force if they understand the risk and want to test the launchd shape.

Eval (per the always-propose-eval rule)

• Synthetic — correctness (CI gating): 7 unit tests in tests/claim-task.test.py:
  • happy path: single claim renames file
  • missing task: returns None
  • double claim: second returns None
  • race: 2 forked subprocesses both call claim() on the same task; exactly one wins, other loses, kernel decides
  • different core IDs: claim files distinguish properly
  • path-traversal validation: rejects .., /, dot-prefix
  • realistic task_id (e.g. 1779170589673): accepted
• Synthetic — throughput: deferred to Phase 2b once the skill wedge exists; the burst-load benchmark needs the full claim wiring to measure speedup.
• Real-user — shadow-mode: deferred to Phase 2b; needs the full pool to replay bridge logs against.

Test plan

• python3 tests/claim-task.test.py — 7/7 pass
• bash -n scripts/install-core-pool.sh syntax check pass
• bash -n scripts/uninstall-core-pool.sh syntax check pass
• Install script pre-flight refuse verified (without --force, errors out cleanly with usage message)
• Install script --force path verified on temp workspace
• Narrow glob verified — confirmed com.sutando.core-[0-9]*.plist does NOT match com.sutando.core-agent.plist
• Owner local install test (Phase 2b ready)

Tracks #880. Phase 2b lands as a separate PR once the wedge + done-flag gate are designed.

🤖 Generated with Claude Code