feat(loop): add second-resolution session wakeup engine - #5182

✅ Maintainer verification — wakeup engine driven end-to-end in a real TUI

This is an engine + tool PR (Step 1; /loop skill wiring is out of scope per #5184), so I verified it where it actually runs: I drove the loop_wakeup tool through the real interactive TUI under tmux, watched a scheduled wakeup actually fire ~60s later and re-invoke the model, and confirmed the clamp/exit-summary behavior — plus the full changed-file test suite and a typecheck.

Setup

• Source: PR head 8dd6268, fresh npm ci + npm run bundle → dist/cli.js (v0.18.1).
• Env: Linux, Node v22. Config isolated via QWEN_HOME.
• Driving the agent: invoking loop_wakeup needs the model to emit a tool call, so I pointed the OpenAI-compatible provider at a local mock that emits one loop_wakeup({delaySeconds: 5, prompt: "<continuation>", reason: ...}) and then, when the fired continuation prompt comes back as a fresh user turn, replies with text (without re-arming, to end the loop). Only the tool call is scripted — the scheduler, the onFire delivery, the notification queue, and the re-invocation are all the PR's real code. loop_wakeup is registered by default (cronEnabled defaults true) and, despite being a deferred tool, a direct model call executes fine.

1. Schedule + clamp report (delaySeconds: 5 → clamped to 60s)

The tool surfaces as an ask-gated confirmation (same as CronCreate), and the requested 5s is reported as clamped to the floor:

?  LoopWakeup 60s (requested 5s): WAKEUP_FIRED continue the self-paced loop
   60s (requested 5s): WAKEUP_FIRED continue the self-paced loop
Do you want to proceed?
 › 1. Yes, allow once
   2. Always allow loop_wakeup in this project
   3. Always allow loop_wakeup for this user
   4. No, suggest changes (esc)

Approved → the scheduler returns an exact, second-resolution ISO fire time and echoes the reason:

✓  LoopWakeup 60s (requested 5s): WAKEUP_FIRED continue the self-paced loop
   Loop wakeup cxusm81j scheduled for 2026-06-16T23:34:05.712Z — demo: polling fast-changing state
✦ Scheduled a wakeup; I will resume automatically when it fires.

2. The wakeup actually fires and re-invokes the model (the headline)

~60s later the tick fires it through the existing onFire channel → it lands on the interactive notification queue as a Cron: item → auto-submits as its own turn → the model is re-invoked with the verbatim continuation prompt:

✦ Scheduled a wakeup; I will resume automatically when it fires.
● Cron: WAKEUP_FIRED continue the self-paced loo          ← fire delivered via onFire
✦ ✅ Woke up via loop_wakeup and resumed the loop. Ending now.   ← model re-invoked with the prompt

Because the woken-up turn did not schedule another wakeup, the loop ended — matching CC's "call again to keep alive / omit to end." (Re-arming instead would continue it; the engine clears the prior wakeup on each scheduleWakeup, so only one is ever pending.) This confirms "no CLI delivery-path changes" — it rides the same path cron fires already use.

3. Pending wakeup is tracked (exit summary)

Scheduling another wakeup and quitting before it fires prints the session exit summary, listing the pending wakeup with id, local fire time, and prompt:

Session ending. 1 active loop cancelled:
  - [l959l7kt] wakeup at 6/17/2026, 7:36:36 AM: WAKEUP_FIRED continue the self-paced loop

(cron_list / cron_delete exposure of wakeups is covered by the unit tests below.)

4. Focused tests + typecheck (on PR head)

663 tests pass. (No CLI source changed, so the cron-delivery suites the PR lists are unaffected.)

Notes

• Clamp boundaries match the spec end-to-end: [60, 3600], 1200 default for non-finite, wasClamped reported in both the confirmation description and the tool result.
• Firing is exact second-resolution (it fired right at the 60s mark, not minute-rounded) — distinct from cron jobs, exactly as designed.
• The wakeup map is separate from cron jobs: never durable, not counted against MAX_JOBS, and scheduleWakeup clears any prior pending wakeup (single in-flight wakeup) — consistent with the observed behavior and the unit tests.

Verdict: The session wakeup engine and loop_wakeup tool work end-to-end through the real interactive delivery path — schedule, clamp, exact fire, re-invoke, and exit tracking all behave as described. Solid Step-1 foundation for #5156. LGTM. 👍

?  LoopWakeup 60s (requested 5s): WAKEUP_FIRED continue the self-paced loop
   60s (requested 5s): WAKEUP_FIRED continue the self-paced loop
Do you want to proceed?
 › 1. Yes, allow once
   2. Always allow loop_wakeup in this project
   3. Always allow loop_wakeup for this user
   4. No, suggest changes (esc)

✓  LoopWakeup 60s (requested 5s): WAKEUP_FIRED continue the self-paced loop
   Loop wakeup cxusm81j scheduled for 2026-06-16T23:34:05.712Z — demo: polling fast-changing state
✦ Scheduled a wakeup; I will resume automatically when it fires.

✦ Scheduled a wakeup; I will resume automatically when it fires.
● Cron: WAKEUP_FIRED continue the self-paced loo          ← 通过 onFire 投递的触发
✦ ✅ Woke up via loop_wakeup and resumed the loop. Ending now.   ← 模型被该 prompt 重新唤起

Session ending. 1 active loop cancelled:
  - [l959l7kt] wakeup at 6/17/2026, 7:36:36 AM: WAKEUP_FIRED continue the self-paced loop

_{Verified locally in an isolated environment; the model's tool call was stubbed via a local mock — the scheduler, onFire delivery, fire, and re-invocation are the PR's real code.}

✅ Maintainer re-verification — new commit f9fb3e6c driven end-to-end (delta on my prior 8dd6268 check)

My earlier verification covered head 8dd6268. The branch has since advanced by exactly one commit — f9fb3e6c "fix(loop): align wakeup delay reporting" — and that commit changes user-visible reporting, so I rebuilt the new head and re-drove it through the real interactive TUI under tmux, focused on what this commit changes, plus a full regression of the core schedule → fire → re-invoke path and the changed-file test suite.

What f9fb3e6c actually changes (4 things)

1. Exports WAKEUP_MIN_SECONDS / WAKEUP_MAX_SECONDS and interpolates them into the clamp message + the delaySeconds schema description (single source of truth; same [60, 3600]).
2. Exit-summary fire time .toLocaleString() → .toISOString().
3. getDescription() now rounds delaySeconds before the clamp comparison → a sub-second input that rounds into range no longer shows a (requested …) suffix, aligning the preview with the wasClamped flag.
4. toAutoClassifierInput projects the clamped delay (5 → 60) into the AUTO classifier.

Setup

• Source: PR head f9fb3e6c, fresh npm run bundle → dist/cli.js (v0.18.1). The bundled chunk literally carries the new code (wakeup at ${new Date(wakeup.fireAtMs).toISOString()}, the roundedDelaySeconds logic, the clamped classifier projection).
• Env: Linux, Node v22. Config isolated via a throwaway HOME; OpenAI-compatible provider pointed at a local mock that emits one loop_wakeup(...) tool call and then, when the fired continuation comes back as a fresh user turn, replies with plain text (no re-arm, to end the loop). Only the tool call is scripted — the scheduler, the onFire delivery, the notification queue and the re-invocation are all the PR's real code.
• Aside: the only npm run build failure on this box is the unrelated web-shell package (missing katex asset in this environment) — this PR touches packages/core only; core compiles clean and the bundle is built directly from source.

1. Clamp report still correct — 5 → 60s (requested 5s), now via the exported constants

delaySeconds: 5 rounds to 5, which is below the floor → genuinely clamped → the (requested 5s) suffix shows, and an exact ISO fire time is returned:

?  LoopWakeup 60s (requested 5s): WAKEUP_FIRED continue the self-paced loop
 › 1. Yes, allow once  …
✓  LoopWakeup 60s (requested 5s): WAKEUP_FIRED continue the self-paced loop
   Loop wakeup wos8ljqu scheduled for 2026-06-18T01:04:17.862Z — demo: polling fast-changing state

2. NEW alignment — 59.6 → 60s with no (requested …) suffix

delaySeconds: 59.6 rounds to 60, which is in range → it is not a meaningful clamp, so the preview drops the suffix (matching wasClamped=false). Direct contrast with §1:

?  LoopWakeup 60s: WAKEUP_FIRED continue the self-paced loop          ← no "(requested 59.6s)"
✓  LoopWakeup 60s: WAKEUP_FIRED continue the self-paced loop
   Loop wakeup 70ffg3d4 scheduled for 2026-06-18T01:06:41.484Z — demo: sub-second rounding alignment

This is exactly the inconsistency the commit fixes: before, the description said 60s (requested 59.6s) while the schedule path reported no clamp — now both agree.

3. NEW exit-summary is ISO (.toISOString())

Scheduling a wakeup and quitting before it fires now prints the pending wakeup with an ISO fire time (my prior report on 8dd6268 showed the locale form 6/17/2026, 7:36:36 AM):

Session ending. 1 active loop cancelled:
  - [70ffg3d4] wakeup at 2026-06-18T01:06:41.484Z: WAKEUP_FIRED continue the self-paced loop

The id 70ffg3d4 matches the scheduled wakeup, and /quit cancelled the single pending one — pending-wakeup tracking intact.

4. Core path — exact fire + re-invoke, no regression

The headline behavior from the prior check still holds on the new head. The wakeup fired through the existing onFire channel → landed on the notification queue → auto-submitted as its own turn → re-invoked the model with the verbatim continuation, then ended (no re-arm):

✦ Scheduled. I will resume automatically when the wakeup fires.
● Cron: WAKEUP_FIRED continue the self-paced loo          ← fire delivered via onFire
✦ ✅ Woke up via loop_wakeup and resumed the loop. Ending now.   ← model re-invoked with the prompt

Fired at 01:04:17.971Z vs scheduled 01:04:17.862Z — ~110 ms, exact second-resolution, not minute-rounded.

5. AUTO-classifier clamp projection (5 → 60)

Change #4 feeds the clamped delay to the AUTO classifier; that projection is internal input (not surfaced in interactive ask mode, which is what I drove), and is covered by the new unit test projects the clamped delay into AUTO classifier input (green, by name below).

6. Focused tests + typecheck (on PR head f9fb3e6c)

665 tests pass.

Verdict

f9fb3e6c does exactly what it says: it aligns the three reporting surfaces (description preview, schedule/wasClamped flag, classifier input) so sub-second rounding is no longer mislabeled as "clamped", and switches the exit summary to ISO — all with no regression to the core schedule → exact fire → re-invoke path. My prior LGTM stands for the updated head. 👍

?  LoopWakeup 60s (requested 5s): WAKEUP_FIRED continue the self-paced loop
✓  LoopWakeup 60s (requested 5s): WAKEUP_FIRED continue the self-paced loop
   Loop wakeup wos8ljqu scheduled for 2026-06-18T01:04:17.862Z — demo: polling fast-changing state

?  LoopWakeup 60s: WAKEUP_FIRED continue the self-paced loop          ← 没有 "(requested 59.6s)"
✓  LoopWakeup 60s: WAKEUP_FIRED continue the self-paced loop
   Loop wakeup 70ffg3d4 scheduled for 2026-06-18T01:06:41.484Z — demo: sub-second rounding alignment

Session ending. 1 active loop cancelled:
  - [70ffg3d4] wakeup at 2026-06-18T01:06:41.484Z: WAKEUP_FIRED continue the self-paced loop

✦ Scheduled. I will resume automatically when the wakeup fires.
● Cron: WAKEUP_FIRED continue the self-paced loo          ← 通过 onFire 投递的触发
✦ ✅ Woke up via loop_wakeup and resumed the loop. Ending now.   ← 模型被该 prompt 重新唤起

_{Re-verified locally in an isolated environment at head f9fb3e6c; the model's tool call was stubbed via a local mock — the scheduler, onFire delivery, fire, and re-invocation are the PR's real code.}

@qwen-code /triage

@qwen-code /triage