feat(scheduler-core): implement REPL execution control (task 12.1)

Adds the interactive simulation REPL's execution-control slice (Req 5 AC 22): a single-threaded input loop (readline-based) supporting step [N], continue, quit, and help, pausing before the first replay event and blocking the driver loop while active. Review round 1 raised two findings, both resolved here: - GNU readline (GPL) was linked directly into xce_scheduler, a shipped production daemon. Switched the whole project to libedit (BSD) for line editing -- scheduler and controller (xce_test) both now use editline/readline.h, API-compatible (readline()/add_history()). - Getting a clean regression run after the libedit swap required a full clean rebuild, which exposed a genuine pre-existing SIGSEGV (bug-1504): SnapshotData.internalState was a capnp Data field, and this codebase's capnpc-c backend silently no-ops Data-field encoding without zero-initializing the caller's stack struct, leaving an uninitialized capn_ptr written onto the wire. Fixed by switching internalState to List(UInt8) (with a new internalStateLen wire field), matching the working FetchFileReply.content/bytesRead precedent -- no hand-written accessor code needed. A second, unrelated instance of the same bug class was found in the controller's WAL-catchup path (WalCatchupEntry.payload) and deliberately left unfixed as bug-1505, out of scheduler-core's boundary; needs its own project-wide Data-field audit. Scheduler suite: 34/34 clean. RED-phase reproduction recorded in tasks.md (repl_should_pause() step-budget check disabled -> 2/4 tests fail as expected -> reverted -> 34/34 green). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JPPXeKSUXUqcqvzNXY1rzJ
2026-08-07 08:17:35 +00:00 · 2026-08-07 08:17:35 +00:00 · 02f7f48ff9
commit 02f7f48ff9
parent de00ccff37
17 changed files with 1491 additions and 81 deletions
--- a/.kiro/specs/scheduler-core/tasks.md
+++ b/.kiro/specs/scheduler-core/tasks.md
@ -354,12 +354,13 @@
 - [ ] 12. Core: Interactive REPL
- [ ] 12.1 Implement REPL execution control
+- [x] 12.1 Implement REPL execution control
  - Implement a single input-loop REPL (not a separate thread) that pauses before the first event and blocks the simulation loop while active, supporting step-N-sessions, continue-to-next-breakpoint-or-EOF, and quit
  - Observable: starting simulation with the REPL enabled pauses before any event is processed; issuing a step command advances exactly the requested number of sessions and returns control to the prompt
  - _Requirements: 5.22_
-  - _Note: use readline() for the input loop's line editing (history, arrow keys) — xce_test's REPL already sets this precedent (src/controller/testsuite/test.c:3827) and readline is already a linked project dependency, zero new cost. Confirm readline's GPL licensing is acceptable for this build target before committing to it (vs. libedit/linenoise) if that hasn't already been settled elsewhere in the codebase._
+  - _Note: use readline() for the input loop's line editing (history, arrow keys) — xce_test's REPL already sets this precedent (src/controller/testsuite/test.c:3827) and readline is already a linked project dependency, zero new cost. Confirm readline's GPL licensing is acceptable for this build target before committing to it (vs. libedit/linenoise) if that hasn't already been settled elsewhere in the codebase._ **Resolved: switched project-wide to libedit (BSD) instead — see Implementation Notes.**
  - _Depends: 11.2_
  - _Verified: RED-phase reproduction performed during review round 2 — temporarily changed `repl_should_pause()` (repl.c) from `return (rs->step_budget <= 0);` to `return false;`, rebuilt, ran `sched_repl_execution_control_test`: 2/4 tests failed exactly as expected (`test_should_pause_fires_on_exactly_the_nth_session`, `test_step_1_processes_exactly_one_session_then_quit_exits`), the 2 unrelated tests (`test_should_pause_never_fires_in_continue_mode`, `test_pre_replay_pause_blocks_before_any_event_is_processed`) stayed green. Reverted; rebuilt; full scheduler suite 34/34 GREEN._
 - [ ] 12.2 Implement REPL breakpoints and state inspection
  - Support setting/listing/deleting breakpoints on event type with optional field filters, and inspection commands reporting current simulation position, and job/queue/worker/resource/summary state
@ -402,3 +403,5 @@
 - Task 9.3's review found a genuine task-breakdown gap, not fixable within 9.3's own boundary: `record_snapshot_interval` (the field task 9.3's periodic-checkpoint mechanism reads) has no CLI or admin-request wiring anywhere in the codebase — `--record-snapshot-interval` appears in AC 11's own normative text but in zero task's actual scope. Neither task 9.4 (admin request handler — dispatches `SchedAdminRequest` actions, which don't carry an interval field either, per controller.capnp's `SchedAdminRequest{action, recordFile}`) nor group 10 (controller-side dispatch) owns scheduler startup CLI flags; only `main.c`'s argp table does, following task 9.1's own `--record-dir` precedent. As currently scoped, AC 11's mechanism is fully implemented and tested (via the struct field directly) but has no path to ever be configured non-zero in a real deployment. Needs a small follow-up task before this spec is considered complete: add a `--record-snapshot-interval N` CLI flag to `main.c`, wired to `sched.record_snapshot_interval`, mirroring `--record-dir`'s exact pattern (task 9.1).
 - Task 9.3's review also flagged `test_record_lifecycle.c`'s size (826→1232 lines across tasks 9.2+9.3) as past this suite's established over-800 precedent (prior max `test_driver_translate.c`≈867) — the content itself is genuine, non-duplicative coverage (not padding), and a natural split point exists along the AC10 (lifecycle/TOCTOU)/AC11 (periodic-checkpoint/error-handling) seam by extracting shared fixture helpers into a common header. Non-blocking; worth a future cleanup pass, not urgent.
 - Cross-task interaction, flagged before task 9.4 exists — resolution decided (not a fail/retry, a deferral): task 9.2's `sched_record_start()` calls `xce_sched_core_save_snapshot()` as its first action (AC 10 step 1) — the same function task 8.2 gated to return `-EBUSY` whenever `session_active != 0`. `main.c`'s driver loop is single-threaded (`while(1) { xce_sched_driver_run_normal_mode_round(&sched); ...; sleep(1); }`); incoming requests (including the future `SchedAdminRequest`) arrive asynchronously via `scheduler_req_handler` (handler.c) on the I/O side, same as job/queue/worker updates. **Decision**: task 9.4 must NOT call `sched_record_start()` directly from the request-handling thread (that both risks racing `session_active` and violates this codebase's async-I/O rule against blocking/file-I/O in a request-handler callback). Instead, `recordStart` must be enqueued the same way job/queue/worker updates already are (`pend_updates` dataq or an equivalent dedicated pending-admin-request slot) and picked up by `xce_sched_driver_translate_pending_events()` — which already runs at the top of every round, strictly before `begin_session()`, so it is guaranteed between-sessions by the same construction argument design.md uses for `core_push_events()`. This means recording "takes effect" at the next scheduling round, not synchronously on request arrival. Consequence for task 9.4: since AC 10 specifies a synchronous request-reply carrying the resolved filename, the actual `SchedAdminReply` send must be deferred until the driver thread performs the queued start (not sent eagerly from the handler thread) — needs a completion signal back to the waiting request context (e.g. a condition variable, or replying once `xce_sched_driver_translate_pending_events()` reports the deferred start applied). Given this deferral makes the direct `-EBUSY` race effectively unreachable from the admin path, the AC 10 error-codes table doesn't need a new "busy" entry for this case — `sched_record_start()` keeps its `-EBUSY` return as a defensive/fail-loud contract check (task 9.2's job, no torn state), it just should no longer be a path task 9.4's dispatch can actually trigger by construction.
 - Task 12.1's review found a licensing gap (fixed): the readline()-based REPL input loop originally linked GNU readline (GPL) directly into `xce_scheduler`, a shipped production daemon (unlike `xce_test`, a debug-only binary controller's own readline use was already confined to). Switched project-wide to libedit (BSD) — `nixSupport/xce.nix`, both `meson.build`s, `repl.c`, and `src/controller/testsuite/test.c` now use `editline/readline.h` (API-compatible: `readline()`/`add_history()`), no hand-written accessor changes needed anywhere.
 - Task 12.1's review also surfaced bug-1504 (fixed) and bug-1505 (deferred, out of boundary) — see `.wolf/buglog.json`. Verifying the licensing fix required a full clean rebuild (new nix dependency), which exposed a genuine, pre-existing, deterministic SIGSEGV in `write_SnapshotData` unrelated to task 12.1's own repl.c: `SnapshotData.internalState` was a capnp `Data` field, and this codebase's capnpc-c backend silently no-ops Data-field encoding in generated `encode_XXX()` helpers without zero-initializing the caller's stack struct first — a real, reproducible UB crash, not a flaky test. Fixed (bug-1504) by switching `internalState` to `List(UInt8)` (controller.capnp, typemap.h, test_e2e_capnp.c) — this same capnpc-c backend DOES correctly auto-generate real encode/decode for `List(UInt8)` (proven precedent: `FetchFileReply.content`/`bytesRead`), eliminating the whole no-op class for this field with no hand-written accessor code. Re-verified with a full clean rebuild: scheduler suite 34/34, no regressions. While chasing this, also hit a **second, unrelated instance of the same bug class** in the controller's HA/WAL-catchup subsystem (`WalCatchupEntry.payload`, bug-847's own territory) — confirmed systemic (affects any `:Data` field in `controller.capnp` fed through the generic codec, not a one-off) but deliberately **left unfixed** (bug-1505) as out of scheduler-core's boundary; needs its own project-wide `:Data`-field audit as a separate task.
--- a/.wolf/buglog.json
+++ b/.wolf/buglog.json
@ -14667,5 +14667,178 @@
    "related_bugs": [],
    "occurrences": 1,
    "last_seen": "2026-08-04T00:00:00Z"
  },
  {
    "id": "bug-1498",
    "timestamp": "2026-08-05T00:00:00Z",
    "error_message": "test_toctou_hardlink_planted_after_validation_rejected FAILED: Expected Non-NULL -- fgets() on the outside 'victim' file returned NULL (file was 0 bytes) after the TOCTOU regression test ran, even though sched_record_start()/the reproduced open-hardening sequence both correctly REJECTED the hard-link swap and returned an error.",
    "file": "src/scheduler/src/recording.c",
    "root_cause": "sched_record_start()'s TOCTOU-hardened open used O_WRONLY|O_CREAT|O_TRUNC|O_NOFOLLOW. O_TRUNC truncates the target atomically as PART OF the open(2) syscall itself, before any userspace code -- including the fstat()+st_nlink==1 safety check right after open() -- ever runs. Against a hard-linked victim (same inode as the outside file, no symlink involved so O_NOFOLLOW never triggers), open() succeeds and O_TRUNC immediately zeroes the shared inode's content; the subsequent st_nlink>1 check then correctly rejects and closes the fd, but the outside victim file was already corrupted by that point. The check ran too late to matter -- classic 'check-after-side-effect' TOCTOU-adjacent bug, caught by the test's own outside-file-content assertion (added specifically to prove containment, not just that the return code was negative).",
    "fix": "Removed O_TRUNC from the initial open() flags (now O_WRONLY|O_CREAT|O_NOFOLLOW). After fstat()+st_nlink==1 passes, explicitly call ftruncate(fd, 0) to get the same truncate-on-legitimate-overwrite behavior, but only once safety is verified. Same fix applied to the test's own toctou_hardened_open() helper (a verbatim reproduction of the production sequence, used because a literal multi-threaded race against sched_record_start()'s few-instruction internal window would be flaky).",
    "tags": [
      "scheduler-core",
      "task-9.2",
      "recording.c",
      "toctou",
      "hardlink",
      "O_TRUNC",
      "check-after-side-effect",
      "sched_record_start"
    ],
    "related_bugs": [],
    "occurrences": 1,
    "last_seen": "2026-08-05T00:00:00Z"
  },
  {
    "id": "bug-1499",
    "timestamp": "2026-08-05T00:00:00Z",
    "error_message": "sched_driver_session_ordering_test TIMEOUT (30s, killed by SIGTERM) after adding task 9.2's recording-write hooks to xce_sched_driver_run_normal_mode_round() -- picker thread, allocator thread, and the main round all blocked forever.",
    "file": "src/scheduler/src/driver.c",
    "root_cause": "While inserting the new 'if (sched->recording) { rec_ctx = sched_record_session_begin(...); }' block between plugin_begin_session()/sched_account_jobs() and the decision-drain loop, the pre-existing `xce_core_signal_go(&(sched->core));` call was accidentally dropped from the Edit's old_string/new_string pair -- it was the last line of the block being replaced but was not included in the replacement text. Without xce_core_signal_go(), the picker thread's cbuf_get(&core->wbuf) rendezvous never unblocks, which cascades: the stand-in allocator thread never receives a jobid from cbuf_get(&core->jbuf), so it never pushes the end-of-session NULL decision, so the main thread's own cbuf_get(&core->decisions) drain loop blocks forever -- a 3-way deadlock across all three threads.",
    "fix": "Restored `xce_core_signal_go(&(sched->core));` immediately after the new recording session-begin block (matching requirements.md's own annotated pseudocode order: build ReplaySession{beginRound} THEN sched_go()). Caught by re-running the full scheduler test suite after the recording hooks were added -- test_driver_session_ordering.c is the ONLY test in the suite that drives a real picker/allocator thread pair through this exact function, so it was the only test capable of catching a signal_go() regression.",
    "tags": [
      "scheduler-core",
      "task-9.2",
      "driver.c",
      "deadlock",
      "xce_core_signal_go",
      "accidental-deletion-in-edit",
      "xce_sched_driver_run_normal_mode_round"
    ],
    "related_bugs": [],
    "occurrences": 1,
    "last_seen": "2026-08-05T00:00:00Z"
  },
  {
    "id": "bug-1500",
    "timestamp": "2026-08-06T00:00:00Z",
    "error_message": "test_run_processes_multiple_sessions_in_order_and_no_longer_returns_enosys FAIL: Expected 5000 Was 743938186628040 (a raw-looking CLOCK_MONOTONIC nanosecond value, not the fixture's own beginRound).",
    "file": "src/scheduler/testsuite/test_sim_event_loop.c",
    "root_cause": "The test's fixture-building helper called the real sched_record_start() THEN sched_record_stop() to produce a valid header+snapshot prefix (matching test_sim_startup.c's own write_valid_fixture() precedent), then re-opened the same path in append mode ('a') to hand-write additional ReplayEvent/ReplaySession messages after it. But sched_record_stop() (recording.c) unconditionally writes its OWN ReplayEvent{endSession} marker immediately after the snapshot as part of every completed recording (Req 5 AC 20) -- so the fixture already contained a premature end-of-stream marker BEFORE any of the test's own appended events/sessions. sched_sim_driver_run()'s event loop (sim_loop.c, task 11.2) correctly treats ReplayEvent{endSession} as the whole-stream termination signal and stopped reading right there, leaving sim->core's clock at its xce_sched_core_init() default (virtual_clock_base=0, speed_num=1, speed_den=1 -- AC 3's normal-mode row), so xce_core_now() returned an unfrozen, elapsed-wall-clock-driven value instead of the intended frozen 5000.",
    "fix": "Changed the fixture helper to call ONLY sched_record_start() (never sched_record_stop()), and return the STILL-OPEN FILE* (sched.record_file) so the test appends its own hand-built events/sessions directly onto the same open stream, ending with its own append_end_of_stream_marker() call, then fclose()s it directly -- bypassing sched_record_stop()'s real event/session-recording API entirely for this hand-built-fixture use case.",
    "tags": [
      "scheduler-core",
      "task-11.2",
      "sim_loop.c",
      "test-fixture",
      "sched_record_stop",
      "ReplayEvent_body_endSession",
      "premature-termination-marker"
    ],
    "related_bugs": [],
    "occurrences": 1,
    "last_seen": "2026-08-06T00:00:00Z"
  },
  {
    "id": "bug-1501",
    "timestamp": "2026-08-07T00:00:00Z",
    "error_message": "gcc: 'expected =, ,, ;, asm or __attribute__ before is' / 'unknown type name is' / 'missing terminating character' cascade starting at sim_verify.c:59, plus 'implicit declaration of function sim_verify_str_eq' further down.",
    "file": "src/scheduler/src/sim_verify.c",
    "root_cause": "File header doc comment's Comparison-strategy paragraph wrote the literal text 'xce_job_alloc_t*/xce_pendreason_t*' to mean 'an xce_job_alloc_t pointer or an xce_pendreason_t pointer' -- the '*/' substring is C's block-comment CLOSE token, so the /* ... */ doc comment terminated early, right in the middle of prose. Everything from that point until the next real */ (the following function's own closing delimiter) was parsed as C code, producing a cascade of nonsense syntax errors and, once the compiler resynced, an implicit-declaration warning/error for a function whose real prototype/definition had been swallowed into the truncated comment. Exact recurrence of the bug-1493 pattern already logged for typemap.h (same 'accidental */ in a C block comment' root cause).",
    "fix": "Reworded to 'xce_job_alloc_t* or xce_pendreason_t*' (space before 'or' instead of a bare slash-star-slash-adjacent sequence), eliminating the literal '*/' substring. Ran a repo grep for the same '[A-Za-z_]*/[A-Za-z_]' pattern across both new/modified files (sim_verify.c, sim_loop.c) before rebuilding to rule out a second occurrence.",
    "tags": [
      "scheduler-core",
      "task-11.4",
      "sim_verify.c",
      "block-comment",
      "accidental-comment-close",
      "bug-1493-recurrence",
      "build-failure"
    ],
    "related_bugs": [
      "bug-1493"
    ],
    "occurrences": 1,
    "last_seen": "2026-08-07T00:00:00Z"
  },
  {
    "id": "bug-1502",
    "timestamp": "2026-08-07T00:00:00Z",
    "error_message": "Task 11.5 review round 1 REJECTED: previous implementer's self-reported RED-phase evidence (git stash of 4 'behavioral production files' -> 3 tests failing under meson test) did not reproduce -- reviewer got a hard ninja build failure instead (test_sim_event_loop.c:467 calling sim_process_replay_event_message with 5 args against a stashed-back 4-arg sim_loop.c declaration).",
    "file": "src/scheduler/src/sim_loop.c",
    "root_cause": "git stash scoped to only 4 production files silently desyncs test files (which already call the NEW post-task-11.5 signatures/behavior) against the stashed-back OLD production code -- a stash-based RED probe is not a valid methodology whenever tests and production code changed together in the same commit-to-be. The previous implementer's reported failure counts were therefore not reproducible as described.",
    "fix": "Replaced the stash approach with a direct, targeted, in-place temporary edit of ONLY the behavioral logic inside sim_loop.c (never touching test files, sim_record.c, sim.c/sim.h, recording_session.c/recording.h, or either meson.build): hardcoded event_src to sim->replay_file (defeats AC16 what-if branching) and wrapped the 3 --sim-output write gates (header/snapshot, event pass-through, session-write via record_ctx) in 'if (0 && ...)' no-ops (defeats AC19). Rebuilt+ran `meson test -C xce.build --suite scheduler`: real RED = 30/32, sched_sim_alt_events_test and sched_sim_record_output_test FAIL with concrete assertion messages. Reverted all 4 edits using the exact original text; confirmed via `git diff src/scheduler/src/sim_loop.c` that only the original (pre-probe) task-11.5 diff remained, no probe residue (grep for 'TEMP RED-PHASE PROBE' and 'if (0 &&' both zero matches). Rebuilt+reran: 32/32 green again.",
    "tags": [
      "scheduler-core",
      "task-11.5",
      "sim_loop.c",
      "red-phase-evidence",
      "review-rejection",
      "git-stash-pitfall",
      "methodology"
    ],
    "related_bugs": [],
    "occurrences": 1,
    "last_seen": "2026-08-07T00:00:00Z"
  },
  {
    "id": "bug-1503",
    "timestamp": "2026-08-07T03:11:00Z",
    "error_message": "AddressSanitizer: attempting free on address which was not malloc()-ed, inside free_QueueConf() <- free_QueueConf_ptr() <- release_translated_payload() (driver.c) <- xce_sched_driver_translate_pending_events(). Crashing pointer was 56 bytes inside a 61-byte region allocated by makeString()->makeInstance().",
    "file": "src/scheduler/testsuite/test_sim_equivalence.c",
    "root_cause": "makeString() (lib/xstring.c) is backed by the vendored rtti library makeInstance() allocator, which does NOT return a plain malloc()-compatible pointer at offset 0 of its allocation (it returns a pointer into a larger rtti-managed block). Elsewhere in the codebase makeString()-allocated strings are safe because they are only ever released by the SAME rtti-aware teardown path that created them (e.g. kill_sched_* killers, or never freed at all in white-box test fixtures). This new test constructed xce_queue_t/xce_job_t fixtures with q->queue/submit->queue/user/project_name/resreq set via makeString(), then drove them through the REAL production cleanup path release_translated_payload() (driver.c), whose free_QueueConf_ptr()/free_Job_ptr() (controller.capnp.c, capnp-generated) call plain free() on those fields directly -- exactly the mismatch: an rtti-backed allocation freed via plain free().",
    "fix": "Replaced every makeString() call used to populate xce_queue_t.queue / xce_job_t.submit->{queue,user,project_name,resreq} in test_sim_equivalence.c with strdup(), which returns a plain malloc()-compatible buffer safe for free_QueueConf_ptr()/free_Job_ptr() to free directly. Confirmed clean (no ASan bad-free) after the fix, full scheduler suite (33/33) green.",
    "tags": [
      "scheduler-core",
      "makeString",
      "strdup",
      "asan",
      "bad-free",
      "driver.c",
      "task-11.6"
    ],
    "related_bugs": [],
    "occurrences": 1,
    "last_seen": "2026-08-07T03:11:00Z"
  },
  {
    "id": "bug-1504",
    "timestamp": "2026-08-07T08:00:00Z",
    "error_message": "sched_sim_startup_test SIGSEGV in write_SnapshotData (lib/controller.capnp.c) -- deterministic crash inside libCapnC_Runtime's read_ptr/capn_setp, discovered during scheduler-core task 12.1 review remediation (full clean rebuild needed for a libedit dependency swap).",
    "file": "src/schema/controller.capnp",
    "root_cause": "SnapshotData.internalState was declared `:Data` in the capnp schema. This codebase's capnpc-c backend silently no-ops Data-field encoding inside generated encode_XXX() composite helpers (documented, deliberate limitation -- see controller.capnp's own prior comment citing ReplayHeader.configHash). But encode_SnapshotData_ptr()'s local `struct SnapshotData d;` is never zero-initialized before the (partially no-op) encode_SnapshotData() populates it, so the skipped Data field's capn_ptr is left as UNINITIALIZED STACK GARBAGE. write_SnapshotData() then unconditionally capn_setp()'s that garbage onto the wire. This is genuine UB: whether it crashes depends entirely on what garbage bytes land in that stack slot at each call site -- ReplayHeader.configHash has the identical gap but never crashed (lucky garbage); SnapshotData.internalState's stack layout in this one test's call chain was unlucky. A prior 'rm -rf xce.build' full rebuild (needed to pick up a new nix dependency) perturbed the whole binary's layout enough to flip this from dormant to a deterministic, reproducible SIGSEGV.",
    "fix": "Changed SnapshotData.internalState from `Data` to `List(UInt8)` in controller.capnp, with a new companion internalStateLen (@11, UInt32) wire field for the maplistcount -- following the exact working precedent of FetchFileReply.content/bytesRead, which this same capnpc-c backend DOES correctly auto-generate real (non-no-op) encode/decode for (capn_new_list8/capn_set8 loop, not a placeholder comment). Updated typemap.h's sched_snapshot_data_t.internal_state_len from size_t to uint32_t to match the wire type, and updated test_e2e_capnp.c's test_snapshot_data_round_trip (which previously worked around the Data no-op with a manual low-level SnapshotData_get/set_internalState accessor) to rely on the now-working ordinary codec bridge instead. No hand-written low-level accessor code needed any more for this field.",
    "tags": [
      "scheduler-core",
      "task-12.1",
      "capnp-schema",
      "codegen-limitation",
      "sigsegv",
      "uninitialized-memory",
      "controller.capnp",
      "snapshot"
    ],
    "related_bugs": [
      "bug-1493",
      "bug-1505"
    ],
    "occurrences": 1,
    "last_seen": "2026-08-07T08:00:00Z"
  },
  {
    "id": "bug-1505",
    "timestamp": "2026-08-07T08:10:00Z",
    "error_message": "controller_unit_test SIGSEGV in write_WalCatchupEntry (lib/controller.capnp.c), test_wal_catchup_append_term_fields_round_trip -- discovered incidentally while chasing bug-1504; NOT fixed, logged for its own follow-up.",
    "file": "src/schema/controller.capnp",
    "root_cause": "Same root cause as bug-1504 (Data-field codegen no-op leaves an uninitialized stack capn_ptr in the generated encode_XXX_ptr()'s local struct), a DIFFERENT field: WalCatchupEntry.payload (@2: Data), in the controller's HA/WAL-catchup subsystem (bug-847's own territory -- see controller.capnp's comment there), entirely unrelated to scheduler-core. Confirms this is a systemic, project-wide bug class affecting every `:Data` field in controller.capnp whose bytes are populated via the generic encode_XXX()/write_XXX() composite pipeline rather than fully hand-written low-level accessor code -- not a one-off. Known/suspected other Data fields with the same latent gap: ReplayHeader.configHash (dormant so far, no real consumer), CtrlHelloRequest.key, and possibly others not yet audited.",
    "fix": "NOT FIXED. Deliberately deferred -- out of scheduler-core task 12.1's boundary (this is the controller's HA/WAL-replication subsystem), and a proper fix requires a project-wide audit of every `:Data` field in controller.capnp to decide case-by-case: convert to List(UInt8) (bug-1504's fix, when the field is genuinely a flat byte blob with no cross-segment/per-element concerns) vs. keep Data with real hand-written low-level accessor code at every encode/decode call site (matching the batchPayloads precedent, when List(UInt8) risks bug-847's per-element far-pointer loss for repeated/batch structures). Needs its own scoped task, not a one-off patch.",
    "tags": [
      "controller",
      "ha",
      "wal-catchup",
      "capnp-schema",
      "codegen-limitation",
      "sigsegv",
      "uninitialized-memory",
      "controller.capnp",
      "deferred",
      "systemic"
    ],
    "related_bugs": [
      "bug-1504",
      "bug-847"
    ],
    "occurrences": 1,
    "last_seen": "2026-08-07T08:10:00Z"
  }
-]
+]
--- a/src/controller/meson.build
+++ b/src/controller/meson.build
@ -56,9 +56,12 @@ controller = executable('xce_controller',
 xce_test_src = [ 'testsuite/test.c', 'testsuite/waldump.c', 'testsuite/walcompare.c', 'testsuite/snapverify.c', 'testsuite/snapdiff.c', 'testsuite/configcompare.c']
-readline_dep = dependency('readline')
+# BSD-licensed readline replacement (scheduler-core spec, task 12.1 review
-ncurses_dep = dependency('ncurses')
+# finding): GNU readline is GPL; xce_test's REPL only needs readline()/
-history_dep = dependency('history')
+# add_history(), both provided by libedit's editline/readline.h emulation
 # header under a permissive license. Single dependency, no separate
 # ncurses/history split (libedit's own .pc pulls ncurses in privately).
 libedit_dep = dependency('libedit')
 ssl_dep = dependency('openssl') # also needed by configcompare.c (SHA256());
                                 # controller_unit_test_deps below re-assigns
                                 # the same dependency() result, harmless
@ -67,9 +70,7 @@ xce_test_deps = [
  libxce_dep,
  librtti_dep,
  struct2json_dep,
-  readline_dep,
+  libedit_dep,
  history_dep,
  ncurses_dep,
  tinylog_dep,
  zlib_dep,        # waldump: crc32 WAL validation
  c_capnproto_dep, # waldump: decode JOB_SUBMIT jobid
--- a/src/controller/testsuite/test.c
+++ b/src/controller/testsuite/test.c
@ -10,8 +10,9 @@
 #include <time.h>
 #include <unistd.h>
-#include <readline/history.h>
+#include <editline/readline.h> /* libedit (BSD) -- provides readline()/
-#include <readline/readline.h>
+                                 * add_history(), same as GNU readline's
                                 * split readline.h/history.h pair */
 #include <cjson/cJSON.h>
 #include <cjson/s2j.h>
--- a/src/controller/testsuite/test_e2e_capnp.c
+++ b/src/controller/testsuite/test_e2e_capnp.c
@ -1080,14 +1080,16 @@ static void test_replay_decision_dispatch_union_round_trip(void)
 /* non-trivial data (including >=1 entry in each of the top-level       */
 /* List(...) fields: queues/users/projects) and round-trips them        */
 /* field-for-field through encode_SnapshotData_ptr/decode_SnapshotData  */
-/* -- EXCEPT internalState (a Data field), whose generated codec is a   */
+/* -- INCLUDING internalState, which is List(UInt8) (task 12.1 review   */
-/* documented no-op (same limitation as every other Data field in this  */
+/* finding: was Data, whose generated codec is a silent no-op in this   */
-/* schema, e.g. ReplayHeader.configHash in Test 7) -- verified instead  */
+/* codebase's capnpc-c setup and left write_SnapshotData() writing an   */
-/* via the low-level SnapshotData_get/set_internalState accessor on the */
+/* uninitialized stack capn_ptr onto the wire -- a real, reproducible   */
-/* SAME struct pointer the codec bridge already populated, same hybrid  */
+/* crash; see controller.capnp's SnapshotData comment for the full      */
-/* technique used nowhere else in this file but safe because encode_/   */
+/* story). List(UInt8) gets a real generated encode_/decode_ (same      */
-/* set_ operate on independent field slots of one already-allocated     */
+/* precedent as FetchFileReply.content/bytesRead), so internal_state/   */
-/* capnp struct.                                                        */
+/* internal_state_len round-trip through the ordinary codec bridge      */
 /* like every other field here -- no low-level accessor workaround      */
 /* needed any more.                                                     */
 /*                                                                       */
 /* Also demonstrates this task's internalVersion Observable: "a         */
 /* snapshot encoded with one internal-state version and decoded         */
@ -1228,14 +1230,6 @@ static void test_snapshot_data_round_trip(void)
    SnapshotData_ptr p;
    encode_SnapshotData_ptr(cs, &p, &src);
    /* internalState (Data field): codec no-op, set via low-level accessor
     * on the same already-allocated struct pointer (see comment above). */
    capn_list8 state_list = capn_new_list8(cs, (int)sizeof(internal_bytes));
    capn_setv8(state_list, 0, internal_bytes, sizeof(internal_bytes));
    capn_data state_data;
    state_data.p = state_list.p;
    SnapshotData_set_internalState(p, state_data);
    capn_setp(capn_root(&c), 0, p.p);
    int64_t sz = capn_size(&c);
    TEST_ASSERT_TRUE(sz > 0);
@ -1316,16 +1310,13 @@ static void test_snapshot_data_round_trip(void)
    TEST_ASSERT_EQUAL_UINT64(123456789ULL, dst.prng_seed);
    TEST_ASSERT_EQUAL_UINT32(2u, dst.internal_version);
-    /* internalState -- low-level accessor read-back (Data field, codec
+    /* internalState -- ordinary codec-bridge read-back (List(UInt8), real
-     * no-op; see comment above). */
+     * generated decode; see comment above). */
-    capn_data out_state = SnapshotData_get_internalState(dp);
+    TEST_ASSERT_EQUAL_UINT32((uint32_t)sizeof(internal_bytes),
-    TEST_ASSERT_EQUAL_INT((int)sizeof(internal_bytes),
+                             dst.internal_state_len);
-                           capn_len((capn_list8){ out_state.p }));
+    TEST_ASSERT_NOT_NULL(dst.internal_state);
-    uint8_t out_state_bytes[sizeof(internal_bytes)];
+    TEST_ASSERT_EQUAL_MEMORY(internal_bytes, dst.internal_state,
-    TEST_ASSERT_EQUAL_INT((int)sizeof(internal_bytes),
+                             sizeof(internal_bytes));
                           capn_getv8((capn_list8){ out_state.p }, 0,
                                      out_state_bytes, sizeof(internal_bytes)));
    TEST_ASSERT_EQUAL_MEMORY(internal_bytes, out_state_bytes, sizeof(internal_bytes));
    /* Observable: version-mismatch rejection. A reader that expects the
     * SAME internal_version accepts; a reader that expects a DIFFERENT
--- a/src/include/typemap.h
+++ b/src/include/typemap.h
@ -623,13 +623,19 @@ typedef struct {
 * placeholder wholesale. Every domain-object pointer reuses a pre-existing
 * native type (already used natively throughout the scheduler/controller)
 * except users/projects (sched_snapshot_user_t/sched_snapshot_project_t
- * above) and the two scheduler-internal-only opaque fields. internal_state
+ * above) and the two scheduler-internal-only opaque fields. internal_version
- * follows the same raw uint8_t-pointer + size_t pattern as every other Data
+ * is a format tag for internal_state so an incompatible future internal
- * field in this file (e.g. replay_header_t.config_hash above) -- the generated
+ * layout is rejected rather than misinterpreted (this task's Observable).
- * encode_SnapshotData/decode_SnapshotData codec is a documented no-op for
+ *
- * it; real extraction is task 9+ hand-written code. internal_version is a
+ * internal_state/internal_state_len map controller.capnp's internalState,
- * format tag for internal_state so an incompatible future internal layout
+ * a List(UInt8) (task 12.1 review finding, fixed -- was Data, whose
- * is rejected rather than misinterpreted (this task's Observable). */
+ * generated codec is a silent no-op in this codebase's capnpc-c setup and
 * left a genuinely uninitialized capn_ptr on the wire, a real reproducible
 * crash; see controller.capnp's SnapshotData comment for the full story).
 * List(UInt8)'s generated encode_/decode_ actually runs (proven precedent:
 * xce_fetchfile_reply_t.content/bytes_read below), so internal_state_len
 * must be uint32_t to match internalStateLen's UInt32 wire type -- same
 * maplistcount convention as content/bytes_read. */
 typedef struct {
    xce_conf4sched_t          *config;
    xce_jobs_data_t           *jobs;
@ -644,7 +650,7 @@ typedef struct {
    int                         n_projects;
    uint64_t                    prng_seed;
    uint8_t                    *internal_state;
-    size_t                      internal_state_len;
+    uint32_t                    internal_state_len;
    uint32_t                    internal_version;
 } sched_snapshot_data_t;
--- a/src/nixSupport/xce.nix
+++ b/src/nixSupport/xce.nix
@ -30,8 +30,12 @@ stdenv.mkDerivation {
      separateDebugInfo = true;
    }))
    libtirpc
-    readline
+    # BSD-licensed readline replacement (task 12.1, scheduler-core spec):
-    ncurses
+    # GNU readline is GPL and would encumber xce_scheduler/xce_test's own
    # licensing once linked into a production/shipped binary; libedit's
    # editline/readline.h header is API-compatible (readline()/add_history())
    # so callers change only their #include, not their calls.
    libedit
    struct2json
    (capnpc.overrideAttrs (oldAttrs: {
      separateDebugInfo = true;
--- a/src/scheduler/include/repl.h
+++ b/src/scheduler/include/repl.h
@ -0,0 +1,82 @@
 #if !defined(_REPL_H_)
 #define _REPL_H_ 1
 #include "sim.h"
 /*
 * repl.h - interactive simulation REPL, execution-control slice (scheduler-
 * core spec, task 12.1, Req 5 AC 22). New file per design.md's File
 * Structure Plan ("repl.c -- NEW (Phase 3): interactive REPL command loop
 * (Req 5 AC 22)"), Phase 3, sibling to sim.h/sim.c/sim_loop.c.
 *
 * This header declares repl.c's two driver-facing entry points, plus two
 * `static inline` wrappers that fold the `sim->interactive` gate INTO the
 * header itself. That inline-wrapper indirection is a deliberate, judgment-
 * based deviation from this file family's usual "extern declared where
 * consumed, no dedicated header" convention (sim_verify.c/sim_record.c/
 * recording_session.c's entry points are all extern-declared directly
 * inside sim_loop.c -- see that file's own header comment): sim_loop.c was
 * already at 796/800 lines (this project's per-file cap, CLAUDE.md) before
 * this task, leaving no room for even one bare `if (sim->interactive) { ...
 * }` block at each of the two call sites design.md's REPL integration
 * pseudocode requires (pre-replay pause, post-session pause), let alone two.
 * Moving the gate into these inline wrappers keeps sim_loop.c's own diff to
 * two single-line, brace-free call expressions -- this task's own text
 * anticipates exactly this fallback ("move the hook logic into a tiny
 * static inline helper in repl.h, or extract something unrelated out of
 * sim_loop.c"). The two real functions (`xce_repl_start`/
 * `xce_repl_post_session_check`) still carry the actual logic; a `static
 * inline` here costs nothing at link time (each including TU gets its own
 * copy, trivially small, no ODR risk -- sim_loop.c is the only production
 * consumer).
 *
 * Boundary (Req 5 AC 17, "Simulation isolation", same as sim.h): this header
 * only depends on sim.h (itself core.h + stdbool/stdint/stdio) -- no
 * scheduler.h, no client.h, no capnp types. repl.c's own file header
 * comment documents the same boundary for its implementation.
 */
 /*
 * xce_repl_start - the pre-replay pause (Req 5 AC 22's interaction model:
 * "blocks on stdin at startup"). Prints the load banner ("[sim] loaded: ...
 * snapshot @ ts=...", "[sim] ready. type 'help' for commands.") then enters
 * the REPL command loop, blocking on stdin until the operator issues a
 * command that hands control back (`step [N]`/`continue`) or terminates the
 * process (`quit`, which never returns). Called once, by
 * sched_sim_driver_run() (sim_loop.c), strictly before its event loop's
 * `for(;;)` begins -- see xce_repl_pre_replay_pause() below for the actual
 * production call site.
 */
 extern void xce_repl_start(xce_sched_sim_driver_t* sim);
 /*
 * xce_repl_post_session_check - the per-session pause-decision point (Req 5
 * AC 22's interaction model: "blocks on stdin ... at each breakpoint hit";
 * task 12.1's own narrower scope: only a `step N` budget reaching zero, no
 * breakpoints yet). Called once per completed ReplaySession, immediately
 * after xce_core_end_session() (sim_loop.c), when sim->interactive is set.
 * Internally decides whether to pause (a `step` budget hit zero; `continue`
 * mode never pauses here in 12.1's scope) and, if so, re-enters the same
 * blocking command loop xce_repl_start() uses. Task 12.2's own seam: it
 * extends the INTERNAL pause decision (repl.c) to also check a breakpoint
 * list -- this function's signature and sim_loop.c's own call site are not
 * expected to change.
 */
 extern void xce_repl_post_session_check(xce_sched_sim_driver_t* sim);
 static inline void xce_repl_pre_replay_pause(xce_sched_sim_driver_t* sim)
 {
    if (sim->interactive) {
        xce_repl_start(sim);
    }
 }
 static inline void xce_repl_post_session_pause(xce_sched_sim_driver_t* sim)
 {
    if (sim->interactive) {
        xce_repl_post_session_check(sim);
    }
 }
 #endif
--- a/src/scheduler/include/sim.h
+++ b/src/scheduler/include/sim.h
@ -65,17 +65,34 @@
 * write the output header/snapshot, so a re-derived value would drift from
 * "the same SnapshotEntry that was loaded" (AC 19's own wording -- same ts,
 * not merely a same-shaped one taken moments later).
 *
 * `repl_state` below is a SECOND field beyond design.md's literal sketch
 * (scheduler-core spec, task 12.1, Req 5 AC 22) -- the interactive REPL's
 * own execution-control state (current step-N/continue mode, remaining step
 * budget; task 12.2/12.3 grow the same struct with breakpoints/param
 * overrides). Declared here only as an opaque forward-declared pointer
 * (xce_sched_repl_state_t, just below) -- the full struct body lives in
 * repl.c, never in this header, matching plugin.h's own
 * `xce_sched_core_t` forward-declare precedent for the identical "opaque
 * pointer, defined in the consuming file" reason. NULL until
 * xce_repl_start() lazily allocates it (repl.c) -- guaranteed NULL after a
 * successful sched_sim_driver_start() the same way every other field here
 * is, via that function's own `memset(sim, 0, sizeof(*sim))` (sim.c); no
 * sim.c change was needed for this task.
 */
 typedef struct xce_sched_repl_state_s xce_sched_repl_state_t;
 typedef struct {
-    xce_sched_core_t core;
+    xce_sched_core_t        core;
-    FILE*            replay_file;
+    FILE*                   replay_file;
-    FILE*            alt_events_file;
+    FILE*                   alt_events_file;
-    FILE*            record_file;
+    FILE*                   record_file;
-    uint64_t         sim_speed_num;
+    uint64_t                sim_speed_num;
-    uint64_t         sim_speed_den;
+    uint64_t                sim_speed_den;
-    bool             verify;
+    bool                    verify;
-    bool             interactive;
+    bool                    interactive;
-    uint64_t         snapshot_ts;
+    uint64_t                snapshot_ts;
    xce_sched_repl_state_t* repl_state;
 } xce_sched_sim_driver_t;
 /*
--- a/src/scheduler/meson.build
+++ b/src/scheduler/meson.build
@ -18,6 +18,7 @@ scheduler_srcs = [
  'src/sim_loop.c',
  'src/sim_verify.c',
  'src/sim_record.c',
  'src/repl.c',
  'src/schedobj.c',
  'src/plugin.c',
  'src/resource.c',
@ -33,12 +34,23 @@ incdir = include_directories('src',
                             '../include',
                             '../lib')
 # Task 12.1 (scheduler-core spec, Req 5 AC 22): the interactive REPL's
 # line-editing input loop (src/repl.c) needs readline()/add_history().
 # Uses libedit (BSD), not GNU readline (GPL) -- xce_scheduler is a shipped
 # production daemon (unlike xce_test, a debug tool), so a GPL dependency
 # would encumber the whole linked binary. libedit's editline/readline.h
 # emulation header provides the same two calls under a permissive license;
 # src/controller/meson.build (xce_test's own REPL) uses the identical dep
 # for the same reason, kept consistent project-wide.
 libedit_dep = dependency('libedit')
 scheduler_deps = [
  libxce_dep,
  librtti_dep,
  math_dep,
  tinylog_dep,
-  thread_dep
+  thread_dep,
  libedit_dep,
 ]
 scheduler = executable('xce_scheduler',
@ -66,17 +78,18 @@ sched_core_isolation_lib = static_library(
 # Task 11.3 (scheduler-core spec, Req 5 AC 17): isolated compile target for
 # the simulation driver's own files, consumed by
 # testsuite/test_sim_isolation.c to prove at build time that
-# sim.c/sim_loop.c/sim_record.c reference zero controller-facing symbols
+# sim.c/sim_loop.c/sim_record.c/repl.c reference zero controller-facing
-# (client/netio/xceapi/delay/idgen). All files are compiled together into ONE
+# symbols (client/netio/xceapi/delay/idgen). All files are compiled together
-# archive -- task 11.2 added sim_loop.c as a sibling file to task 11.1's
+# into ONE archive -- task 11.2 added sim_loop.c as a sibling file to task
-# sim.c, and task 11.5 adds sim_record.c as a third; covering only a subset
+# 11.1's sim.c, task 11.5 added sim_record.c as a third, and task 12.1 adds
-# of them would repeat core.c's own siblings' (core_events.c/core_session.c/
+# repl.c as a fourth; covering only a subset of them would repeat core.c's
-# core_clock.c) never-mechanically-covered gap for the sim driver. Same
+# own siblings' (core_events.c/core_session.c/core_clock.c)
-# "compiling to an object is enough, no real linking needed" rationale as
+# never-mechanically-covered gap for the sim driver. Same "compiling to an
 # object is enough, no real linking needed" rationale as
 # sched_core_isolation_lib above.
 sched_sim_isolation_lib = static_library(
    'sched_sim_isolation',
-    ['src/sim.c', 'src/sim_loop.c', 'src/sim_record.c'],
+    ['src/sim.c', 'src/sim_loop.c', 'src/sim_record.c', 'src/repl.c'],
    include_directories: incdir,
    dependencies: scheduler_deps,
    install: false)
--- a/src/scheduler/src/repl.c
+++ b/src/scheduler/src/repl.c
@ -0,0 +1,370 @@
 #include <ctype.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
 #include <editline/readline.h> /* libedit (BSD) -- readline()/add_history() */
 #include "repl.h"
 #include "utils.h"
 /*
 * repl.c - interactive simulation REPL, execution-control slice (scheduler-
 * core spec, task 12.1, Req 5 AC 22). Implements a single input-loop REPL
 * (NOT a separate thread, per this file family's own established
 * single-threaded-driver discipline and design.md line 482/510) that pauses
 * before the first event is processed and blocks the simulation loop while
 * active. This task's own scope: `step [N]`/`continue`/`quit`/`help`, the
 * pre-replay pause, and the blocking interaction model. Breakpoints, state
 * inspection (`info job`/`info queue`/etc.), snapshot capture, and `set`/
 * `info config` are tasks 12.2/12.3's own jobs -- see repl_should_pause()
 * below for the single seam left for 12.2 to extend without restructuring
 * sim_loop.c's call sites (repl.h's own header comment).
 *
 * Sanctioned deviation from requirements.md's literal text (Req 5 AC 22,
 * "Implementation note": "The REPL is a single `fgets` loop"): this task's
 * OWN text explicitly directs using readline() instead, for line editing
 * and history. The "single loop in the driver thread, not a separate
 * thread" invariant -- the part of the Implementation note that actually
 * matters for correctness (design.md line 510: "REPL blocks the driver loop
 * intentionally") -- is fully preserved regardless of which line-editing
 * library backs readline()/add_history(); only the input loop's ergonomics
 * change. Matches this spec's own established pattern of documenting
 * deliberate, task-sanctioned deviations from design.md's literal prose
 * (see sim.c/sim_loop.c's own file header comments for the same style
 * across tasks 11.1-11.6).
 *
 * Licensing (task 12.1 review finding): GNU readline is GPL-licensed.
 * xce_scheduler is a shipped production daemon -- linking it in directly
 * (unlike xce_test, a separate debug/tooling binary) would GPL-encumber
 * the whole linked binary. Uses libedit (BSD/NetBSD license) instead, via
 * its editline/readline.h emulation header, which provides the identical
 * readline()/add_history() surface this file calls -- zero behavioral
 * difference, no GPL exposure. src/controller/testsuite/test.c's own REPL
 * was switched to the same libedit dependency for project-wide consistency
 * (see src/controller/meson.build's `libedit_dep`), even though xce_test's
 * standalone-binary status meant it was never GPL-exposed the way
 * xce_scheduler would have been.
 *
 * Boundary (Req 5 AC 17, "Simulation isolation", same as sim.h/sim.c/
 * sim_loop.c/sim_record.c): this file touches only xce_sched_sim_driver_t/
 * xce_sched_core_t (via repl.h -> sim.h -> core.h) plus stdio/libedit --
 * no xcecli_ctx_t, no xce_cluster_config_t, no capnp socket, no controller
 * RPC. test_sim_isolation.c (task 11.3) is extended by this task to cover
 * repl.c/repl.h too, matching the 3-file (now 5-file) precedent it already
 * established for sim.c/sim_loop.c/sim_record.c.
 */
 #define XCE_REPL_PROMPT "(sim) "
 typedef enum {
    XCE_REPL_MODE_STEP = 0, /* pause once `step_budget` sessions complete */
    XCE_REPL_MODE_CONTINUE  /* task 12.1 scope: run unattended until EOF --
                              * no breakpoint mechanism exists yet */
 } xce_repl_run_mode_t;
 /*
 * xce_sched_repl_state_s - the full definition of sim.h's opaque forward
 * declaration. Deliberately private to this file (not exposed even in
 * repl.h) -- sim_loop.c and every other production consumer touch it only
 * through the pointer, never its fields, matching core.h's own
 * xce_sched_core_t precedent for "opaque outside the owning module."
 * White-box test files (this test suite's established convention -- see
 * test_sim_isolation.c's own header comment on the genre) get full field
 * access anyway via `#include "../src/repl.c"`.
 */
 struct xce_sched_repl_state_s {
    xce_repl_run_mode_t mode;
    long                step_budget;
 };
 /*
 * repl_state_ensure - lazily allocates sim->repl_state on first use
 * (xce_repl_start() is always the first caller in the real driver flow, but
 * this stays defensive rather than assuming it). Returns the (possibly
 * newly-allocated) state, or NULL on allocation failure -- callers must
 * treat NULL as "REPL unavailable, do not block" rather than crash: the REPL
 * is a debugging aid, never load-bearing for the simulation's own
 * correctness (design.md's "Deterministic replay is preserved" invariant --
 * the REPL only ever controls WHEN execution pauses, never WHAT is
 * processed, so degrading to "never pauses" on OOM is safe, just less
 * useful).
 */
 static xce_sched_repl_state_t* repl_state_ensure(xce_sched_sim_driver_t* sim)
 {
    if (sim->repl_state != NULL) {
        return sim->repl_state;
    }
    sim->repl_state
        = (xce_sched_repl_state_t*)calloc(1, sizeof(*(sim->repl_state)));
    return sim->repl_state;
 }
 /*
 * repl_count_jobs - counts `core->jobs` via the SAME iter_make()/iter_next()
 * walk core_session.c's core_gc_select_nodes()/scheduler.c's own job-listing
 * code already establish as this codebase's idiom for enumerating a
 * kvmgr-backed `var` container -- not a new tracking mechanism (no new
 * state field, no persistent counter; a one-off read-only walk computed on
 * demand at banner-print time). Used for the load banner's "N" below.
 *
 * Deviation note: requirements.md's own AC 22 pseudocode banner text reads
 * "loaded: N events, snapshot @ ts=...". No field anywhere in
 * xce_sched_sim_driver_t/xce_sched_core_t tracks a total replay-event count
 * without a full file pre-scan -- and sched_sim_driver_start()'s own doc
 * comment (sim.h) is explicit that `sim->replay_file`'s read position must
 * land EXACTLY after the chosen SnapshotEntry, ready for sim_loop.c's
 * sequential resume; scanning ahead to count events would disturb that
 * position (or require a seek-back the file's own stream-based framing does
 * not cheaply support). This task's own text is explicit on the same point
 * ("pull from whatever sim/core state already has this, don't invent new
 * tracking"). Reports the count of job records already restored into the
 * loaded snapshot instead -- real, already-loaded state, zero new tracking,
 * zero file re-scan -- and is labeled honestly below ("N jobs"), not
 * mislabeled as an event count.
 */
 static int repl_count_jobs(xce_sched_core_t* core)
 {
    iterator_t       it;
    xce_sched_job_t* job   = NULL;
    int              count = 0;
    int              rc;
    rc = iter_make(&it, core->jobs);
    if (rc < 0) {
        return 0;
    }
    for (;;) {
        rc = iter_next(&it, (void**)&job);
        if ((rc < 0) || (rc == RTTI_ITER_NO_DATA)) {
            break;
        }
        count++;
    }
    return count;
 }
 static void repl_print_banner(const xce_sched_sim_driver_t* sim)
 {
    int njobs = repl_count_jobs((xce_sched_core_t*)&(sim->core));
    printf("[sim] loaded: %d jobs, snapshot @ ts=%llu\n", njobs,
           (unsigned long long)sim->snapshot_ts);
    printf("[sim] ready. type 'help' for commands.\n");
 }
 /*
 * repl_print_help - Req 5 AC 22's "help" command: "Print available commands
 * with one-line descriptions." Deliberately covers ONLY the commands this
 * task implements (step/continue/quit/help) -- AC 22's full table also
 * lists breakpoints, state inspection, snapshot, and `set`/`info config`
 * commands that do not exist yet; listing them here would document
 * commands repl_dispatch() below would then reject as unrecognized. Tasks
 * 12.2/12.3 extend this listing as they add those commands, matching this
 * task's own text ("Don't over-build entries for commands that don't exist
 * yet").
 */
 static void repl_print_help(void)
 {
    printf("[sim] available commands:\n");
    printf("  step [N]   Advance N sessions (default 1), pause after.\n");
    printf("  continue   Run until next breakpoint hit or EOF.\n");
    printf("  quit       Exit the scheduler immediately.\n");
    printf("  help       Print this help listing.\n");
 }
 /*
 * repl_cmd_quit - Req 5 AC 22's "quit": "Exit the scheduler immediately. No
 * cleanup guarantees beyond `fclose` on open files." That fclose is the ONE
 * guarantee the spec makes, not merely a floor -- honored explicitly here
 * rather than left to implicit process-exit fd release. Mirrors
 * sched_sim_driver_run()'s own clean-completion flush+close for
 * sim->record_file (sim_loop.c) so a `quit` mid-session leaves any partial
 * --sim-output write as durable as a normal completion would. Never
 * returns.
 */
 static void repl_cmd_quit(xce_sched_sim_driver_t* sim)
 {
    if (sim->record_file != NULL) {
        fflush(sim->record_file);
        fclose(sim->record_file);
        sim->record_file = NULL;
    }
    if (sim->replay_file != NULL) {
        fclose(sim->replay_file);
        sim->replay_file = NULL;
    }
    if (sim->alt_events_file != NULL) {
        fclose(sim->alt_events_file);
        sim->alt_events_file = NULL;
    }
    exit(0);
 }
 /*
 * repl_cmd_step - Req 5 AC 22's "step [N]": "Advance N sessions (default
 * 1), pause after." `line` is the FULL command line (including the "step"
 * token itself) -- skips it, then parses the remainder as an optional
 * positive integer via strtol() with explicit trailing-garbage/non-numeric
 * rejection (NOT a bare sscanf("%ld") on the whole remainder, which would
 * silently accept "step abc" as N=<unchanged> by failing to convert without
 * signalling an error the caller could see -- this codebase's own "fail
 * loud" preference, project CLAUDE.md). Sets `sim->repl_state`'s mode/budget
 * and returns true (control returns to the driver loop) only on a
 * successfully parsed, positive N; prints an error and returns false
 * (re-prompt) otherwise.
 */
 static bool repl_cmd_step(xce_sched_sim_driver_t* sim, const char* line)
 {
    const char* rest = line;
    long        n;
    char*       endptr;
    while ((*rest != '\0') && !isspace((unsigned char)*rest)) {
        rest++;
    }
    while (isspace((unsigned char)*rest)) {
        rest++;
    }
    if (*rest == '\0') {
        n = 1; /* "step" with no argument -- Req 5 AC 22's documented
                * default */
    } else {
        n = strtol(rest, &endptr, 10);
        while (isspace((unsigned char)*endptr)) {
            endptr++;
        }
        if ((endptr == rest) || (*endptr != '\0') || (n <= 0)) {
            printf("[sim] step: N must be a positive integer -- usage: "
                   "step [N]\n");
            return false;
        }
    }
    sim->repl_state->mode        = XCE_REPL_MODE_STEP;
    sim->repl_state->step_budget = n;
    return true;
 }
 /*
 * repl_dispatch - parses one readline()-returned command line (already
 * known non-blank by the caller) and executes it. Returns true if control
 * should return to the driver's event loop (`step`/`continue`), false if
 * the REPL should re-prompt (`help`, an unrecognized command, or a `step`
 * parse error). `quit` never returns from repl_cmd_quit() -- its own return
 * value below is unreachable, kept only so every branch has a well-typed
 * value.
 */
 static bool repl_dispatch(xce_sched_sim_driver_t* sim, const char* line)
 {
    char cmd[32];
    if (sscanf(line, " %31s", cmd) != 1) {
        return false; /* whitespace-only -- silently re-prompt */
    }
    if (strcmp(cmd, "step") == 0) {
        return repl_cmd_step(sim, line);
    }
    if (strcmp(cmd, "continue") == 0) {
        sim->repl_state->mode = XCE_REPL_MODE_CONTINUE;
        return true;
    }
    if (strcmp(cmd, "quit") == 0) {
        repl_cmd_quit(sim);
        return true; /* unreachable */
    }
    if (strcmp(cmd, "help") == 0) {
        repl_print_help();
        return false;
    }
    printf("[sim] unknown command: '%s' (type 'help' for a list)\n", cmd);
    return false;
 }
 /*
 * repl_command_loop - the blocking prompt loop itself: readline() the
 * `(sim) ` prompt, add_history() on non-blank input (same convention
 * src/controller/testsuite/test.c's own REPL establishes at its readline()
 * call site), dispatch, repeat until a command hands control back. NULL
 * from readline() (Ctrl-D / stdin EOF) is treated exactly like an explicit
 * `quit` -- the same convention test.c's own loop follows
 * (`execute_line("quit")` on a NULL readline() return) -- never returns in
 * that case either.
 */
 static void repl_command_loop(xce_sched_sim_driver_t* sim)
 {
    for (;;) {
        char* line = readline(XCE_REPL_PROMPT);
        if (line == NULL) {
            repl_cmd_quit(sim); /* never returns */
        }
        if (line[0] != '\0') {
            add_history(line);
        }
        if (repl_dispatch(sim, line)) {
            free(line);
            return;
        }
        free(line);
    }
 }
 void xce_repl_start(xce_sched_sim_driver_t* sim)
 {
    if (repl_state_ensure(sim) == NULL) {
        ERROR("%s failed to allocate REPL state -- continuing unattended "
              "(--interactive pre-replay pause skipped)",
              __func__);
        return;
    }
    repl_print_banner(sim);
    repl_command_loop(sim);
 }
 /*
 * repl_should_pause - Req 5 AC 22's per-session pause decision, task 12.1's
 * own scope: pause only when a `step N` budget reaches zero. `continue`
 * mode (AC 22: "Run until next breakpoint hit or EOF") always returns false
 * here today -- no breakpoint mechanism exists yet (task 12.2's job). This
 * is the single seam task 12.2 extends (adding a breakpoint-list check
 * alongside the step-budget check below) without touching
 * xce_repl_post_session_check() or sim_loop.c's call site at all.
 */
 static bool repl_should_pause(xce_sched_sim_driver_t* sim)
 {
    xce_sched_repl_state_t* rs = sim->repl_state;
    if (rs == NULL) {
        return false; /* defensive: xce_repl_start() always allocates this
                       * first in the real driver flow */
    }
    if (rs->mode == XCE_REPL_MODE_STEP) {
        rs->step_budget--;
        return (rs->step_budget <= 0);
    }
    return false;
 }
 void xce_repl_post_session_check(xce_sched_sim_driver_t* sim)
 {
    if (repl_should_pause(sim)) {
        repl_command_loop(sim);
    }
 }
--- a/src/scheduler/src/sim_loop.c
+++ b/src/scheduler/src/sim_loop.c
@ -8,6 +8,7 @@
 #include "controller.capnp.h"
 #include "plugin.h"
 #include "preason.h"
 #include "repl.h"
 #include "sim.h"
 #include "utils.h"
 #include "xstring.h"
@ -522,6 +523,7 @@ int sched_sim_driver_run(xce_sched_sim_driver_t* sim,
        return rc;
    }
    xce_repl_pre_replay_pause(sim);
    sim_register_default_picker(sim);
    /* Req 5 AC 19 (task 11.5): the first two --sim-output messages, written
@ -735,6 +737,7 @@ int sched_sim_driver_run(xce_sched_sim_driver_t* sim,
            free_ReplaySession_ptr(&decoded_session);
            xce_core_end_session(&(sim->core));
            xce_repl_post_session_pause(sim);
            /* Req 5 AC 19: "On core_end_session(): finalize the
             * ReplaySession ... write the complete message" -- mirrors
--- a/src/scheduler/src/snapshot_load.c
+++ b/src/scheduler/src/snapshot_load.c
@ -324,7 +324,7 @@ int xce_sched_core_load_snapshot(xce_sched_core_t*            core,
            core->session_duration_ns = blob[1];
        } else {
            WARN("%s internal_state version mismatch (got %u, expected %u) "
-                 "or undersized (%zu bytes) -- skipping, session "
+                 "or undersized (%u bytes) -- skipping, session "
                 "diagnostics left at defaults",
                 __func__, in->internal_version,
                 SCHED_SNAPSHOT_INTERNAL_VERSION, in->internal_state_len);
--- a/src/scheduler/testsuite/meson.build
+++ b/src/scheduler/testsuite/meson.build
@ -2,7 +2,17 @@ scheduler_test_src = [
  'test.c',
 ]
-scheduler_test_deps = [libxce_deps, librtti_dep, unity_dep, libxce_dep]
+# libedit_dep (defined in the parent meson.build, task 12.1, Req 5 AC 22):
 # every white-box test TU that #includes ../src/sim_loop.c now transitively
 # pulls in repl.h's inline wrappers, which reference repl.c's real
 # readline()/add_history() calls the moment ANY such TU also #includes
 # ../src/repl.c (already required at link time regardless -- sim_loop.c's
 # own repl.h wrappers reference xce_repl_start()/xce_repl_post_session_check()
 # unconditionally). Added to the shared deps list rather than per-test so
 # every current and future sim-family white-box test picks it up
 # automatically.
 scheduler_test_deps = [libxce_deps, librtti_dep, unity_dep, libxce_dep,
                       libedit_dep]
 incdir = include_directories('../include', '../../include', '.', '../src', '../../lib')
@ -535,6 +545,12 @@ sched_sim_isolation_test = executable(
             '-DXCE_SIM_RECORD_C_PATH="'
             + (meson.current_source_dir() / '..' / 'src' / 'sim_record.c')
             + '"',
             '-DXCE_SIM_REPL_C_PATH="'
             + (meson.current_source_dir() / '..' / 'src' / 'repl.c')
             + '"',
             '-DXCE_SIM_REPL_H_PATH="'
             + (meson.current_source_dir() / '..' / 'include' / 'repl.h')
             + '"',
             '-DXCE_SIM_LIB_PATH="'
             + sched_sim_isolation_lib.full_path()
             + '"'],
@ -636,6 +652,24 @@ sched_sim_equivalence_test = executable(
    dependencies: [scheduler_test_deps],
    install: false)
 # Contract test for the interactive simulation REPL's execution-control slice
 # (scheduler-core spec, task 12.1, Req 5 AC 22): starting simulation with
 # --interactive pauses before any event is processed, and a `step N` command
 # advances exactly N sessions before returning control to the prompt. Same
 # white-box #include pattern as sched_sim_alt_events_test/sched_sim_verify_test
 # (core.c, core_clock.c, core_events.c, core_session.c, decision.c, plugin.c,
 # plugins/builtin_fcfs.c, recording.c, recording_session.c, sim.c, sim_loop.c,
 # sim_record.c, sim_verify.c, snapshot.c/snapshot_wire.c/snapshot_load.c) PLUS
 # the new ../src/repl.c under test. Needs libedit_dep (parent meson.build)
 # at link time -- repl.c's real readline()/add_history() calls are pulled
 # into this TU by the white-box #include.
 sched_repl_execution_control_test = executable(
    'sched_repl_execution_control_test',
    ['test_repl_execution_control.c'],
    include_directories:[incdir],
    dependencies: [scheduler_test_deps, libedit_dep],
    install: false)
 # Register as meson tests so `meson test --suite scheduler` runs them all.
 # detect_leaks=0 matches the suite convention (fixtures are not torn down).
 test('scheduler test', scheduler_test, suite: 'scheduler',
@ -726,3 +760,6 @@ test('scheduler sim record output test',
 test('scheduler sim equivalence test',
     sched_sim_equivalence_test, suite: 'scheduler',
     env: ['ASAN_OPTIONS=detect_leaks=0'])
 test('scheduler repl execution control test',
     sched_repl_execution_control_test, suite: 'scheduler',
     env: ['ASAN_OPTIONS=detect_leaks=0'])
--- a/src/scheduler/testsuite/test_repl_execution_control.c
+++ b/src/scheduler/testsuite/test_repl_execution_control.c
@ -0,0 +1,643 @@
 /*
 * test_repl_execution_control.c - contract test for the interactive
 * simulation REPL's execution-control slice (scheduler-core spec, task
 * 12.1, Req 5 AC 22).
 *
 * Observable under test (task 12.1's own text):
 *   (a) starting simulation with the REPL enabled pauses before any event
 *       is processed;
 *   (b) issuing a step command advances exactly the requested number of
 *       sessions and returns control to the prompt.
 *
 * Three tests, at three different granularities (same "unit-level precision
 * PLUS integration-level end-to-end proof" split test_sim_event_loop.c's own
 * header comment establishes):
 *
 *   Test 1 (unit-level, white-box): drives repl_should_pause() -- the exact
 *   internal predicate sim_loop.c's post-session hook relies on -- directly,
 *   asserting it returns false for the first N-1 completed sessions and true
 *   on exactly the Nth. This is the precise "not N-1, not N+1" proof
 *   Observable (b) requires; it cannot be obtained by driving the full
 *   blocking driver (a real REPL prompt loop cannot be sampled mid-flight
 *   from a single-threaded test without either forking or instrumenting
 *   production code for tests, neither of which would be as precise as
 *   calling the exact decision function directly).
 *
 *   Test 2 (integration-level, single-process, stdin freopen()'d from a
 *   script file): drives a REAL sched_sim_driver_run() with sim->interactive
 *   set against a real one-session `.replay` fixture whose session produces
 *   a real PEND decision, scripted with a single "continue\n" line. Proves
 *   Observable (a) by capturing stdout (dup()/dup2() around the run, same
 *   technique test_sim_verify.c's own capture_stdout_around() establishes)
 *   and asserting the pre-replay-pause banner text appears STRICTLY BEFORE
 *   the decision's own output line -- ordering, not just presence, is the
 *   proof that nothing was processed before the pause.
 *
 *   Test 3 (integration-level, forked child process): drives a REAL
 *   sched_sim_driver_run() against a real THREE-session fixture (distinct
 *   jobid pushed just before each session boundary), scripted with "step
 *   1\nquit\n". A child process is required because the CORRECT behavior is
 *   for `quit` to call exit(0) directly -- this is the genuinely falsifiable
 *   proof the task's own RED-phase guidance asks for: a broken
 *   implementation where `step` is a no-op (always runs to EOF, the exact
 *   probe this task's own text suggests) would run all three sessions to
 *   completion and return normally instead of ever reading "quit", which
 *   the parent detects both by exit status (0 only via quit's real exit(0),
 *   not by falling off the end of the child helper) AND by captured
 *   content (only the FIRST session's jobid may appear).
 *
 * Fixture strategy: the SAME real QUEUE_UPDATE+JOBS_PUSH-driving-the-real-
 * builtin_fcfs-picker technique test_sim_alt_events.c/test_sim_verify.c's
 * own integration-level fixtures establish (build_fixture_scheduler()
 * records schedPolicy="builtin_fcfs" so sim_register_default_picker()
 * resolves the real plugin; sched_job_is_ready()/sched_queue_is_ready() are
 * unconditional `return 1` stubs, task 2.4's own documented, still-live
 * scope note, so any queue/job pair immediately becomes a next_job()
 * candidate).
 *
 * White-box #include of the same TU set test_sim_alt_events.c uses (see
 * that file's own header comment) -- core.c/core_clock.c/core_events.c/
 * core_session.c/decision.c/plugin.c/plugins/builtin_fcfs.c/recording.c/
 * recording_session.c/sim.c/sim_loop.c/sim_record.c/sim_verify.c/
 * snapshot.c/snapshot_load.c/snapshot_wire.c PLUS the new ../src/repl.c
 * under test (task 12.1's own file, pulling readline()/add_history() calls
 * into this TU -- see testsuite/meson.build's own comment on this
 * executable's readline_dep/history_dep/ncurses_dep link requirement).
 */
 #include <errno.h>
 #include <limits.h>
 #include <stdatomic.h>
 #include <stdbool.h>
 #include <stdint.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
 #include <sys/wait.h>
 #include <unistd.h>
 #include <unity/unity.h>
 #include "controller.capnp.h"
 #include "kvmgr.h"
 #include "scheduler.h"
 #include "xstring.h"
 /* Pull in the real functions under test into this TU (white-box #include,
 * same convention as test_sim_alt_events.c/test_sim_verify.c). */
 #include "../src/core.c"
 #include "../src/core_clock.c"
 #include "../src/core_events.c"
 #include "../src/core_session.c"
 #include "../src/decision.c"
 #include "../src/plugin.c"
 #include "../src/plugins/builtin_fcfs.c"
 #include "../src/recording.c"
 #include "../src/recording_session.c"
 #include "../src/repl.c"
 #include "../src/sim.c"
 #include "../src/sim_loop.c"
 #include "../src/sim_record.c"
 #include "../src/sim_verify.c"
 #include "../src/snapshot.c"
 #include "../src/snapshot_load.c"
 #include "../src/snapshot_wire.c"
 void kill_sched_job(void* arg) { (void)arg; }
 void kill_sched_queue(void* arg) { (void)arg; }
 void kill_sched_worker(void* arg) { (void)arg; }
 void kill_sched_user(void* arg) { (void)arg; }
 void kill_sched_project(void* arg) { (void)arg; }
 void kill_sched_resval(xce_val_t* val) { (void)val; }
 void sched_worker_release_host_ctx(xce_sched_worker_t* w) { (void)w; }
 int sched_fill_limit_requests(xce_scheduler_t* sched, xvec_idval_t* vec,
                              xlist_t* limits)
 {
    (void)sched;
    (void)vec;
    (void)limits;
    return 0;
 }
 /* Real reimplementation of schedobj.c's sched_resolve_job_picker -- same
 * copy test_sim_alt_events.c/test_sim_verify.c/test_sim_event_loop.c each
 * carry (schedobj.c is not linked here: it would need plugin_register(),
 * which requires a genuine xce_scheduler_t* neither this file's fixtures
 * nor sim_loop.c's own core-scoped registration path have, Req 5 AC 17). */
 int sched_resolve_job_picker(xce_sched_core_t* core, xce_sched_plugin_t** out)
 {
    xce_sched_plugin_t* plugin = NULL;
    int                 rc     = 0;
    if ((core == NULL) || (out == NULL)) {
        return -EINVAL;
    }
    *out = NULL;
    if (core->job_pick_plugin == NULL) {
        return -EINVAL;
    }
    lock(core->plugins, RTTI_LOCK_READ);
    rc = key_find(core->plugins, core->job_pick_plugin, (void**)&plugin);
    unlock(core->plugins);
    if (rc <= 0) {
        return (rc < 0) ? rc : -ENOENT;
    }
    if ((plugin == NULL) || (plugin->picker_iface == NULL)
        || (plugin->picker_iface->next_job == NULL)
        || (plugin->picker_iface->begin_session == NULL)
        || (plugin->picker_iface->end_session == NULL)
        || (plugin->picker_iface->on_dispatch == NULL)
        || (plugin->picker_iface->on_pend == NULL)) {
        return -EINVAL;
    }
    *out = plugin;
    return 0;
 }
 void setUp(void) { return; }
 void tearDown(void) { return; }
 /* ---------------------------------------------------------------------- */
 /* Fixture helpers -- same techniques test_sim_alt_events.c/test_sim_verify.c */
 /* already establish.                                                      */
 /* ---------------------------------------------------------------------- */
 static void make_tmp_dir(char* out, size_t out_len, const char* suffix)
 {
    char tmpl[PATH_MAX];
    snprintf(tmpl, sizeof(tmpl), "/tmp/sched_replexec%s_XXXXXX", suffix);
    TEST_ASSERT_NOT_NULL(mkdtemp(tmpl));
    TEST_ASSERT_TRUE(strlen(tmpl) < out_len);
    strcpy(out, tmpl);
 }
 static void build_fixture_scheduler(xce_scheduler_t* sched, char* record_dir)
 {
    int rc;
    memset(sched, 0, sizeof(*sched));
    mylock_init(&(sched->record_lock));
    rc = xce_sched_core_init(&(sched->core));
    TEST_ASSERT_EQUAL_INT(0, rc);
    sched->core.job_pick_plugin = (char*)"builtin_fcfs";
    sched->record_dir           = record_dir;
 }
 static FILE* write_header_and_snapshot(char* out_path, size_t out_path_len,
                                       const char* suffix)
 {
    char            record_dir[PATH_MAX];
    xce_scheduler_t sched;
    int             rc;
    make_tmp_dir(record_dir, sizeof(record_dir), suffix);
    build_fixture_scheduler(&sched, record_dir);
    rc = sched_record_start(&sched, "fixture.replay");
    TEST_ASSERT_EQUAL_INT(0, rc);
    TEST_ASSERT_TRUE(strlen(sched.record_file_path) < out_path_len);
    strcpy(out_path, sched.record_file_path);
    return sched.record_file;
 }
 static void append_queue_update_event(FILE* f, uint64_t ts,
                                      const char* queue_name)
 {
    xce_queue_t          queue;
    replay_event_t       src;
    struct capn          c;
    struct capn_segment* cs;
    ReplayEvent_ptr      p;
    memset(&queue, 0, sizeof(queue));
    queue.queue    = (char*)queue_name;
    queue.status   = QUEUE_STAT_OPEN;
    queue.priority = 1;
    memset(&src, 0, sizeof(src));
    src.ts                = ts;
    src.body_which        = ReplayEvent_body_queueUpdate;
    src.body.queue_update = &queue;
    capn_init_malloc(&c);
    cs = capn_root(&c).seg;
    encode_ReplayEvent_ptr(cs, &p, &src);
    capn_setp(capn_root(&c), 0, p.p);
    TEST_ASSERT_EQUAL_INT(0, write_capnp_message(f, &c));
    capn_free(&c);
 }
 static void append_jobs_push_event(FILE* f, uint64_t ts, uint64_t jobid,
                                   const char* queue_name)
 {
    job_submit_data_t    submit;
    xce_job_t            job;
    xce_job_t*           jobs[1];
    xce_jobs_data_t      jobs_data;
    replay_event_t       src;
    struct capn          c;
    struct capn_segment* cs;
    ReplayEvent_ptr      p;
    memset(&submit, 0, sizeof(submit));
    submit.queue    = (char*)queue_name;
    submit.user     = (char*)"alice";
    submit.mintasks = 1;
    submit.maxtasks = 1;
    memset(&job, 0, sizeof(job));
    job.jobid  = jobid;
    job.state  = JOB_STAT_PEND;
    job.submit = &submit;
    jobs[0] = &job;
    memset(&jobs_data, 0, sizeof(jobs_data));
    jobs_data.n_total = 1;
    jobs_data.count   = 1;
    jobs_data.jobs    = jobs;
    memset(&src, 0, sizeof(src));
    src.ts             = ts;
    src.body_which     = ReplayEvent_body_jobsPush;
    src.body.jobs_push = &jobs_data;
    capn_init_malloc(&c);
    cs = capn_root(&c).seg;
    encode_ReplayEvent_ptr(cs, &p, &src);
    capn_setp(capn_root(&c), 0, p.p);
    TEST_ASSERT_EQUAL_INT(0, write_capnp_message(f, &c));
    capn_free(&c);
 }
 static void append_replay_session(FILE* f, uint64_t begin_round)
 {
    struct capn          c;
    struct capn_segment* cs;
    ReplaySession_ptr    sp;
    capn_init_malloc(&c);
    cs = capn_root(&c).seg;
    sp = new_ReplaySession(cs);
    ReplaySession_set_beginRound(sp, begin_round);
    capn_setp(capn_root(&c), 0, sp.p);
    TEST_ASSERT_EQUAL_INT(0, write_capnp_message(f, &c));
    capn_free(&c);
 }
 static void append_end_of_stream_marker(FILE* f)
 {
    replay_event_t       src;
    struct capn          c;
    struct capn_segment* cs;
    ReplayEvent_ptr      p;
    memset(&src, 0, sizeof(src));
    src.body_which = ReplayEvent_body_endSession;
    capn_init_malloc(&c);
    cs = capn_root(&c).seg;
    encode_ReplayEvent_ptr(cs, &p, &src);
    capn_setp(capn_root(&c), 0, p.p);
    TEST_ASSERT_EQUAL_INT(0, write_capnp_message(f, &c));
    capn_free(&c);
 }
 static void write_text_file(const char* path, const char* content)
 {
    FILE* f = fopen(path, "w");
    TEST_ASSERT_NOT_NULL(f);
    TEST_ASSERT_TRUE(fputs(content, f) >= 0);
    fclose(f);
 }
 static char* read_whole_file(const char* path)
 {
    FILE* f = fopen(path, "rb");
    long  len;
    char* buf;
    TEST_ASSERT_NOT_NULL(f);
    TEST_ASSERT_EQUAL_INT(0, fseek(f, 0, SEEK_END));
    len = ftell(f);
    TEST_ASSERT_TRUE(len >= 0);
    rewind(f);
    buf = (char*)malloc((size_t)len + 1);
    TEST_ASSERT_NOT_NULL(buf);
    if (len > 0) {
        TEST_ASSERT_EQUAL_INT((int)len, (int)fread(buf, 1, (size_t)len, f));
    }
    buf[len] = '\0';
    fclose(f);
    return buf;
 }
 /* Same dup()/dup2()-around-STDOUT_FILENO capture technique
 * test_sim_verify.c's own capture_stdout_around() establishes. */
 static char* capture_stdout_around(void (*fn)(void))
 {
    char  tmp[] = "/tmp/xce_replexec_stdoutcap_XXXXXX";
    int   fd    = mkstemp(tmp);
    int   saved_stdout;
    off_t len;
    char* buf;
    TEST_ASSERT_TRUE_MESSAGE(fd >= 0, "mkstemp for stdout capture must "
                                      "succeed");
    fflush(stdout);
    saved_stdout = dup(STDOUT_FILENO);
    TEST_ASSERT_TRUE_MESSAGE(saved_stdout >= 0, "dup(STDOUT_FILENO) must "
                                                "succeed");
    TEST_ASSERT_TRUE_MESSAGE(dup2(fd, STDOUT_FILENO) >= 0,
                             "dup2 redirect of STDOUT_FILENO must succeed");
    fn();
    fflush(stdout);
    dup2(saved_stdout, STDOUT_FILENO);
    close(saved_stdout);
    len = lseek(fd, 0, SEEK_CUR);
    TEST_ASSERT_TRUE(len >= 0);
    buf = (char*)calloc(1, (size_t)len + 1);
    TEST_ASSERT_NOT_NULL(buf);
    TEST_ASSERT_TRUE(lseek(fd, 0, SEEK_SET) == 0);
    if (len > 0) {
        ssize_t nread = read(fd, buf, (size_t)len);
        TEST_ASSERT_TRUE(nread == len);
    }
    close(fd);
    unlink(tmp);
    return buf;
 }
 /* ---------------------------------------------------------------------- */
 /* Test 1: repl_should_pause() pauses on exactly the Nth completed        */
 /* session -- the precise unit-level proof of Observable (b).             */
 /* ---------------------------------------------------------------------- */
 static void test_should_pause_fires_on_exactly_the_nth_session(void)
 {
    xce_sched_sim_driver_t sim;
    memset(&sim, 0, sizeof(sim));
    sim.interactive = true;
    sim.repl_state  = repl_state_ensure(&sim);
    TEST_ASSERT_NOT_NULL(sim.repl_state);
    sim.repl_state->mode        = XCE_REPL_MODE_STEP;
    sim.repl_state->step_budget = 3;
    TEST_ASSERT_FALSE_MESSAGE(repl_should_pause(&sim),
                              "must not pause after session 1 of 3");
    TEST_ASSERT_FALSE_MESSAGE(repl_should_pause(&sim),
                              "must not pause after session 2 of 3");
    TEST_ASSERT_TRUE_MESSAGE(repl_should_pause(&sim),
                             "must pause after exactly session 3 of 3");
    free(sim.repl_state);
    printf("test_should_pause_fires_on_exactly_the_nth_session: PASS\n");
 }
 static void test_should_pause_never_fires_in_continue_mode(void)
 {
    xce_sched_sim_driver_t sim;
    int                    i;
    memset(&sim, 0, sizeof(sim));
    sim.interactive = true;
    sim.repl_state  = repl_state_ensure(&sim);
    TEST_ASSERT_NOT_NULL(sim.repl_state);
    sim.repl_state->mode = XCE_REPL_MODE_CONTINUE;
    /* Req 5 AC 22, task 12.1's own scope: "continue" runs to EOF -- no
     * breakpoint mechanism exists yet, so this must never pause no matter
     * how many sessions complete. */
    for (i = 0; i < 5; i++) {
        TEST_ASSERT_FALSE(repl_should_pause(&sim));
    }
    free(sim.repl_state);
    printf("test_should_pause_never_fires_in_continue_mode: PASS\n");
 }
 /* ---------------------------------------------------------------------- */
 /* Test 2: the pre-replay pause happens BEFORE any decision is produced   */
 /* -- Observable (a), proved by output ORDER, not merely presence.        */
 /* ---------------------------------------------------------------------- */
 static xce_sched_sim_driver_t g_t2_sim;
 static sched_sim_args_t       g_t2_args;
 static int                    g_t2_rc;
 static void run_driver_for_t2_capture(void)
 {
    g_t2_rc = sched_sim_driver_run(&g_t2_sim, &g_t2_args);
 }
 static void test_pre_replay_pause_blocks_before_any_event_is_processed(void)
 {
    char  replay_path[PATH_MAX];
    char  script_dir[PATH_MAX];
    char  script_path[PATH_MAX];
    FILE* f;
    char* captured;
    char* ready_pos;
    char* pend_pos;
    FILE* saved_stdin_check;
    f = write_header_and_snapshot(replay_path, sizeof(replay_path),
                                  "_prepause");
    TEST_ASSERT_NOT_NULL(f);
    append_queue_update_event(f, 1000ULL, "normal");
    append_jobs_push_event(f, 1500ULL, 4242ULL, "normal");
    append_replay_session(f, 2000ULL); /* the only session boundary */
    append_end_of_stream_marker(f);
    fclose(f);
    make_tmp_dir(script_dir, sizeof(script_dir), "_prepausescript");
    snprintf(script_path, sizeof(script_path), "%s/script.txt", script_dir);
    /* A single "continue" -- 12.1's own scope means continue never
     * re-pauses, so the run reaches EOF cleanly without reading stdin
     * again. */
    write_text_file(script_path, "continue\n");
    saved_stdin_check = freopen(script_path, "r", stdin);
    TEST_ASSERT_NOT_NULL_MESSAGE(saved_stdin_check,
                                 "freopen of scripted stdin must succeed");
    memset(&g_t2_sim, 0, sizeof(g_t2_sim));
    memset(&g_t2_args, 0, sizeof(g_t2_args));
    g_t2_args.replay_path  = replay_path;
    g_t2_args.sim_start_ts = SCHED_SIM_START_TS_LATEST;
    g_t2_args.sim_speed    = 0;
    g_t2_args.interactive  = true;
    captured = capture_stdout_around(run_driver_for_t2_capture);
    TEST_ASSERT_EQUAL_INT(0, g_t2_rc);
    ready_pos = strstr(captured, "[sim] ready. type 'help' for commands.");
    pend_pos  = strstr(captured, "PEND jobid=4242");
    TEST_ASSERT_NOT_NULL_MESSAGE(ready_pos,
                                 "pre-replay pause banner must be printed");
    TEST_ASSERT_NOT_NULL_MESSAGE(pend_pos,
                                 "the fixture's one session must have "
                                 "produced a live PEND decision");
    TEST_ASSERT_TRUE_MESSAGE(ready_pos < pend_pos,
                             "the pre-replay pause banner must appear "
                             "BEFORE any decision output -- proves no "
                             "event was processed before the pause");
    free(captured);
    printf("test_pre_replay_pause_blocks_before_any_event_is_processed: "
          "PASS\n");
 }
 /* ---------------------------------------------------------------------- */
 /* Test 3: "step 1" against a three-session fixture processes EXACTLY one */
 /* session before re-pausing -- proved end to end via a forked child that */
 /* then issues "quit" (real exit(0)), so a broken "step ignores N, always */
 /* runs to EOF" implementation is genuinely distinguishable: it would     */
 /* never read "quit" at all and would exit via a different path/status.  */
 /* ---------------------------------------------------------------------- */
 static void child_step_then_quit(const char* replay_path,
                                 const char* script_path,
                                 const char* capture_path)
 {
    xce_sched_sim_driver_t sim;
    sched_sim_args_t       args;
    if (freopen(script_path, "r", stdin) == NULL) {
        _exit(120);
    }
    if (freopen(capture_path, "w", stdout) == NULL) {
        _exit(121);
    }
    memset(&sim, 0, sizeof(sim));
    memset(&args, 0, sizeof(args));
    args.replay_path  = replay_path;
    args.sim_start_ts = SCHED_SIM_START_TS_LATEST;
    args.sim_speed    = 0;
    args.interactive  = true;
    (void)sched_sim_driver_run(&sim, &args);
    /* Unreachable in a correct implementation: "quit" (the script's second
     * line) must have called exit(0) from inside the post-session pause
     * that follows session 1. Falling through here means either the
     * pre-replay pause or the post-session pause never blocked on stdin at
     * all. */
    fflush(stdout);
    _exit(111);
 }
 static void test_step_1_processes_exactly_one_session_then_quit_exits(void)
 {
    char  replay_path[PATH_MAX];
    char  aux_dir[PATH_MAX];
    char  script_path[PATH_MAX];
    char  capture_path[PATH_MAX];
    FILE* f;
    pid_t pid;
    int   status;
    char* captured;
    f = write_header_and_snapshot(replay_path, sizeof(replay_path),
                                  "_step1quit");
    TEST_ASSERT_NOT_NULL(f);
    append_queue_update_event(f, 1000ULL, "normal");
    append_jobs_push_event(f, 1500ULL, 111ULL, "normal");
    append_replay_session(f, 2000ULL); /* session boundary #1 */
    append_jobs_push_event(f, 2500ULL, 222ULL, "normal");
    append_replay_session(f, 3000ULL); /* session boundary #2 -- must NEVER
                                        * be reached */
    append_jobs_push_event(f, 3500ULL, 333ULL, "normal");
    append_replay_session(f, 4000ULL); /* session boundary #3 -- must NEVER
                                        * be reached */
    append_end_of_stream_marker(f);
    fclose(f);
    make_tmp_dir(aux_dir, sizeof(aux_dir), "_step1quitaux");
    snprintf(script_path, sizeof(script_path), "%s/script.txt", aux_dir);
    snprintf(capture_path, sizeof(capture_path), "%s/capture.out", aux_dir);
    write_text_file(script_path, "step 1\nquit\n");
    pid = fork();
    TEST_ASSERT_TRUE_MESSAGE(pid >= 0, "fork() must succeed");
    if (pid == 0) {
        child_step_then_quit(replay_path, script_path, capture_path);
        _exit(112); /* unreachable -- child_step_then_quit never returns */
    }
    TEST_ASSERT_EQUAL_INT_MESSAGE(pid, waitpid(pid, &status, 0),
                                  "waitpid must reap the REPL child");
    TEST_ASSERT_TRUE_MESSAGE(WIFEXITED(status),
                             "the REPL child must exit normally via quit's "
                             "exit(0), not crash/signal");
    TEST_ASSERT_EQUAL_INT_MESSAGE(0, WEXITSTATUS(status),
                                  "quit's exit(0) is the only correct exit "
                                  "path -- a nonzero/111 status means "
                                  "'step 1' never paused (ran to EOF "
                                  "instead), the RED-phase probe this "
                                  "task's own text describes");
    captured = read_whole_file(capture_path);
    TEST_ASSERT_NOT_NULL_MESSAGE(strstr(captured, "PEND jobid=111"),
                                 "session 1's decision must have run");
    TEST_ASSERT_NULL_MESSAGE(strstr(captured, "PEND jobid=222"),
                             "session 2 must NEVER have run -- step 1 "
                             "must pause strictly after session 1");
    TEST_ASSERT_NULL_MESSAGE(strstr(captured, "PEND jobid=333"),
                             "session 3 must NEVER have run either");
    free(captured);
    printf("test_step_1_processes_exactly_one_session_then_quit_exits: "
          "PASS\n");
 }
 int main(void)
 {
    UNITY_BEGIN();
    RUN_TEST(test_should_pause_fires_on_exactly_the_nth_session);
    RUN_TEST(test_should_pause_never_fires_in_continue_mode);
    RUN_TEST(test_pre_replay_pause_blocks_before_any_event_is_processed);
    RUN_TEST(test_step_1_processes_exactly_one_session_then_quit_exits);
    return UNITY_END();
 }
--- a/src/scheduler/testsuite/test_sim_isolation.c
+++ b/src/scheduler/testsuite/test_sim_isolation.c
@ -4,21 +4,27 @@
 * or structural check confirms no controller-facing symbol is reachable
 * from the simulation driver's compiled object" -- plus the AC's own
 * "confirmed by the struct definition itself, not runtime checks alone"
- * clause. Scope: sim.h + sim.c + sim_loop.c + sim_record.c together (task
+ * clause. Scope: sim.h + sim.c + sim_loop.c + sim_record.c + repl.c/repl.h
- * 11.1 + task 11.2's sibling file + task 11.5's sibling file, the
+ * together (task 11.1 + task 11.2's sibling file + task 11.5's sibling
- * --sim-output writer) -- NOT a re-audit of core.c (task 4.1's own
+ * file, the --sim-output writer + task 12.1's sibling files, the
- * territory, test_core_isolation.c) and NOT plugin.c/builtin_fcfs.c (shared
+ * interactive REPL) -- NOT a re-audit of core.c (task 4.1's own territory,
 * test_core_isolation.c) and NOT plugin.c/builtin_fcfs.c (shared
 * normal-mode infra, out of this task's boundary). sim_verify.c (task 11.4)
 * is likewise out of scope here -- it is never compiled into
 * sched_sim_isolation_lib below and carries no isolation-sensitive logic of
 * its own (pure struct comparison, no I/O); extending this guard to it was
- * not part of task 11.4's own text and is left as-is.
+ * not part of task 11.4's own text and is left as-is. repl.c/repl.h are
 * added here per task 12.1's own text (extending this exact 3-file
 * precedent to a 5-file one) -- the REPL reads/writes stdin/stdout and
 * touches xce_sched_sim_driver_t directly, the same category of
 * driver-level code this guard already covers.
 *
 * Three layers, extending test_core_isolation.c's two-layer pattern (same
 * genre: source-text scans of the real, current on-disk files, not a frozen
 * snapshot):
 *
- *   1. Source-text scan of sim.h/sim.c/sim_loop.c: no #include of
+ *   1. Source-text scan of sim.h/sim.c/sim_loop.c/sim_record.c/repl.c/
 *      repl.h: no #include of
 *      client.h/netio.h/xceapi.h/delay.h/idgen.h/xce/cluster.h; no call-site
 *      substring matching a symbol exported only by those libraries (the
 *      exact FORBIDDEN_SYMBOLS list test_core_isolation.c already
@ -83,9 +89,17 @@
 #error                                                                         \
    "XCE_SIM_RECORD_C_PATH must be defined by meson.build to sim_record.c's absolute path"
 #endif
 #ifndef XCE_SIM_REPL_C_PATH
 #error                                                                         \
    "XCE_SIM_REPL_C_PATH must be defined by meson.build to repl.c's absolute path"
 #endif
 #ifndef XCE_SIM_REPL_H_PATH
 #error                                                                         \
    "XCE_SIM_REPL_H_PATH must be defined by meson.build to repl.h's absolute path"
 #endif
 #ifndef XCE_SIM_LIB_PATH
 #error                                                                         \
-    "XCE_SIM_LIB_PATH must be defined by meson.build to the absolute path of sim.c+sim_loop.c+sim_record.c's isolated static_library() archive"
+    "XCE_SIM_LIB_PATH must be defined by meson.build to the absolute path of sim.c+sim_loop.c+sim_record.c+repl.c's isolated static_library() archive"
 #endif
 /* Forbidden headers (design.md "Allowed Dependencies", same list
@ -359,16 +373,22 @@ static void test_sim_source_paths_are_readable(void)
    char* c      = read_whole_file(XCE_SIM_C_PATH);
    char* loop   = read_whole_file(XCE_SIM_LOOP_C_PATH);
    char* record = read_whole_file(XCE_SIM_RECORD_C_PATH);
    char* repl_c = read_whole_file(XCE_SIM_REPL_C_PATH);
    char* repl_h = read_whole_file(XCE_SIM_REPL_H_PATH);
    TEST_ASSERT_NOT_NULL_MESSAGE(h, XCE_SIM_H_PATH);
    TEST_ASSERT_NOT_NULL_MESSAGE(c, XCE_SIM_C_PATH);
    TEST_ASSERT_NOT_NULL_MESSAGE(loop, XCE_SIM_LOOP_C_PATH);
    TEST_ASSERT_NOT_NULL_MESSAGE(record, XCE_SIM_RECORD_C_PATH);
    TEST_ASSERT_NOT_NULL_MESSAGE(repl_c, XCE_SIM_REPL_C_PATH);
    TEST_ASSERT_NOT_NULL_MESSAGE(repl_h, XCE_SIM_REPL_H_PATH);
    free(h);
    free(c);
    free(loop);
    free(record);
    free(repl_c);
    free(repl_h);
 }
 static void test_sim_never_includes_forbidden_headers(void)
@ -377,38 +397,54 @@ static void test_sim_never_includes_forbidden_headers(void)
    char* c_raw      = read_whole_file(XCE_SIM_C_PATH);
    char* loop_raw   = read_whole_file(XCE_SIM_LOOP_C_PATH);
    char* record_raw = read_whole_file(XCE_SIM_RECORD_C_PATH);
    char* repl_c_raw = read_whole_file(XCE_SIM_REPL_C_PATH);
    char* repl_h_raw = read_whole_file(XCE_SIM_REPL_H_PATH);
    char* h;
    char* c;
    char* loop;
    char* record;
    char* repl_c;
    char* repl_h;
    TEST_ASSERT_NOT_NULL(h_raw);
    TEST_ASSERT_NOT_NULL(c_raw);
    TEST_ASSERT_NOT_NULL(loop_raw);
    TEST_ASSERT_NOT_NULL(record_raw);
    TEST_ASSERT_NOT_NULL(repl_c_raw);
    TEST_ASSERT_NOT_NULL(repl_h_raw);
    h      = strip_c_comments(h_raw);
    c      = strip_c_comments(c_raw);
    loop   = strip_c_comments(loop_raw);
    record = strip_c_comments(record_raw);
    repl_c = strip_c_comments(repl_c_raw);
    repl_h = strip_c_comments(repl_h_raw);
    TEST_ASSERT_NOT_NULL(h);
    TEST_ASSERT_NOT_NULL(c);
    TEST_ASSERT_NOT_NULL(loop);
    TEST_ASSERT_NOT_NULL(record);
    TEST_ASSERT_NOT_NULL(repl_c);
    TEST_ASSERT_NOT_NULL(repl_h);
    assert_no_forbidden_includes(h, "sim.h");
    assert_no_forbidden_includes(c, "sim.c");
    assert_no_forbidden_includes(loop, "sim_loop.c");
    assert_no_forbidden_includes(record, "sim_record.c");
    assert_no_forbidden_includes(repl_c, "repl.c");
    assert_no_forbidden_includes(repl_h, "repl.h");
    free(h_raw);
    free(c_raw);
    free(loop_raw);
    free(record_raw);
    free(repl_c_raw);
    free(repl_h_raw);
    free(h);
    free(c);
    free(loop);
    free(record);
    free(repl_c);
    free(repl_h);
 }
 static void test_sim_never_calls_forbidden_symbols(void)
@ -417,38 +453,54 @@ static void test_sim_never_calls_forbidden_symbols(void)
    char* c_raw      = read_whole_file(XCE_SIM_C_PATH);
    char* loop_raw   = read_whole_file(XCE_SIM_LOOP_C_PATH);
    char* record_raw = read_whole_file(XCE_SIM_RECORD_C_PATH);
    char* repl_c_raw = read_whole_file(XCE_SIM_REPL_C_PATH);
    char* repl_h_raw = read_whole_file(XCE_SIM_REPL_H_PATH);
    char* h;
    char* c;
    char* loop;
    char* record;
    char* repl_c;
    char* repl_h;
    TEST_ASSERT_NOT_NULL(h_raw);
    TEST_ASSERT_NOT_NULL(c_raw);
    TEST_ASSERT_NOT_NULL(loop_raw);
    TEST_ASSERT_NOT_NULL(record_raw);
    TEST_ASSERT_NOT_NULL(repl_c_raw);
    TEST_ASSERT_NOT_NULL(repl_h_raw);
    h      = strip_c_comments(h_raw);
    c      = strip_c_comments(c_raw);
    loop   = strip_c_comments(loop_raw);
    record = strip_c_comments(record_raw);
    repl_c = strip_c_comments(repl_c_raw);
    repl_h = strip_c_comments(repl_h_raw);
    TEST_ASSERT_NOT_NULL(h);
    TEST_ASSERT_NOT_NULL(c);
    TEST_ASSERT_NOT_NULL(loop);
    TEST_ASSERT_NOT_NULL(record);
    TEST_ASSERT_NOT_NULL(repl_c);
    TEST_ASSERT_NOT_NULL(repl_h);
    assert_no_forbidden_symbols(h, "sim.h");
    assert_no_forbidden_symbols(c, "sim.c");
    assert_no_forbidden_symbols(loop, "sim_loop.c");
    assert_no_forbidden_symbols(record, "sim_record.c");
    assert_no_forbidden_symbols(repl_c, "repl.c");
    assert_no_forbidden_symbols(repl_h, "repl.h");
    free(h_raw);
    free(c_raw);
    free(loop_raw);
    free(record_raw);
    free(repl_c_raw);
    free(repl_h_raw);
    free(h);
    free(c);
    free(loop);
    free(record);
    free(repl_c);
    free(repl_h);
 }
 /*
@ -523,8 +575,8 @@ static void test_sim_object_has_no_forbidden_undefined_symbols(void)
        /* posix format for an undefined symbol: "<name> U" (no
         * value/size columns). Skip anything that doesn't parse as
         * exactly that -- e.g. a blank line, or an archive member header
-         * some nm versions print (this archive has three member objects,
+         * some nm versions print (this archive has four member objects,
-         * sim.c.o, sim_loop.c.o, and sim_record.c.o). */
+         * sim.c.o, sim_loop.c.o, sim_record.c.o, and repl.c.o). */
        if (sscanf(line, "%511s %c", symbol, &type) != 2) {
            continue;
        }
--- a/src/schema/controller.capnp
+++ b/src/schema/controller.capnp
@ -1109,10 +1109,23 @@ struct SchedProject $C.mapname("sched_snapshot_project_t") {
 # session/iterator state) with no capnp-visible structure -- the core owns
 # its byte layout; internalVersion is a format tag so a future incompatible
 # internal layout is rejected rather than misinterpreted (this task's
-# Observable). Like every other Data field in this schema (see
+# Observable).
-# ReplayHeader.configHash above), internalState's generated encode_/decode_
+#
-# codec is a documented no-op -- real extraction is hand-written
+# internalState is List(UInt8), NOT Data (task 12.1 review finding, fixed):
-# low-level-accessor code, task 9+'s job, same pattern.
+# every OTHER Data field in this schema (e.g. ReplayHeader.configHash) has
 # its generated encode_/decode_ codec silently no-op'd by this codebase's
 # capnpc-c setup -- the generated encode_SnapshotData_ptr()'s local `struct
 # SnapshotData d;` is never zero-initialized, so a no-op'd Data field left
 # capn_setp() writing an UNINITIALIZED stack capn_ptr onto the wire (real,
 # reproducible SIGSEGV in write_SnapshotData, deterministic per call site's
 # stack layout -- configHash happened to get lucky garbage, internalState
 # did not). List(UInt8) sidesteps the whole no-op class: this same capnpc-c
 # backend DOES correctly auto-generate real encode/decode for List(UInt8)
 # (proven precedent: FetchFileReply.content/bytesRead above -- a genuine
 # capn_new_list8()/capn_set8() loop, not a comment placeholder), so no
 # hand-written low-level accessor code is needed here at all. Same
 # maplistcount convention as content/bytesRead: internalStateLen (@11,
 # below) carries the byte count as its own real wire scalar.
 struct SnapshotData $C.mapname("sched_snapshot_data_t") {
  config          @0: Conf4Sched;
  jobs            @1: SchedJobData;
@ -1123,8 +1136,9 @@ struct SnapshotData $C.mapname("sched_snapshot_data_t") {
  users           @6: List(SchedUser) $C.maplistcount("n_users");
  projects        @7: List(SchedProject) $C.maplistcount("n_projects");
  prngSeed        @8: UInt64 $C.mapname("prng_seed");
-  internalState   @9: Data $C.mapname("internal_state");
+  internalState   @9: List(UInt8) $C.mapname("internal_state") $C.maplistcount("internal_state_len");
  internalVersion @10: UInt32 $C.mapname("internal_version");
  internalStateLen @11: UInt32 $C.mapname("internal_state_len");
 }
 struct SnapshotEntry $C.mapname("replay_snapshot_entry_t") {