Public: anyone can read this; the crew can change it.
A feature's scheduled tool is called the way its hand-run tool is: the unified timer broke the morning paper's print with a header its app refuses #14218
Check · Review · Land · Live done — Landed and live in production.
Items 1–3 are done; item 4 is not, and item 2 covers only tools that opt in. A feature's tool is now called with the same signed headers whether a person or the clock runs it. The tests I ran pass (173 of 174), and the one failure is fixed below.
shipped production is serving it deploy 8e1361f
5 earlier comments · 1 event
Items 1–3 are done; item 4 is not, and item 2 covers only tools that opt in. A feature's tool is now called with the same signed headers whether a person or the clock runs it. The tests I ran pass (173 of 174), and the one failure is fixed below. I did not run the full suite; the forge's check does that.
What changed
- One header set.
callHeadersinsrc/apps/timer_fire.tsbuilds the headers for every call. The timer delivery (deliveryHeaders) and the hand-runcallToolboth use it, so a hand-run call now carriesx-forge-identityandx-forge-signaturetoo.callToolandrunRecordedtake the app's identity key as a new argument; thefeaturestool passes it. - Contract in the docs.
docs/features/feature-schedule.mdhas a new "Calling a tool" section. It lists the headers and says how an app verifies "this is my forge": the identity starts withforge-timer|, has not expired, and its signature checks underFORGE_APP_IDENTITY_KEY. It also says not to guess from header absence. - Contract test.
test/feature-call-contract.test.tsuses an app that refuses anything it can't verify. It shows the hand's headers cover the clock's, and that a wrong key gets a 404. - Probe at migration.
SYNC_REVISIONis now#3, so every app's schedules are re-read once. After that read, and on each new production commit,src/apps/schedule_probe.tssends each scheduled tool one call withx-forge-probe: 1. An app that refuses it gets a failed run on the schedule, and the owner is asked through the existing failing-run ask (failingNow). An accepted probe records nothing. - What counts as proven.
/api/v1/healthschedules.rannow counts a schedule only when a fired run was answered 200. A failed run, or a refused probe, no longer counts.
What I chose not to do
- Probe is opt-in. Only a tool declared
"probe": trueis probed. It must answer 200 to the probe header without doing its work. Probing the paper's print without that promise would print the paper, so a feature that hasn't opted in is still not checked in advance. The morning paper would need to add"probe": trueand honour the header. - Template not changed (item 4).
templates/app-template.jsonis a pinned snapshot of another repository, so I did not edit it. ItsfromForgeinsrc/once.tsalready implements the documented check, but the template has no/forge/toolsroute yet. The docs point tool routes atfromForge.
Existing test I changed. test/feature-schedule-one.test.ts expected ran: 1 after a schedule that failed past its retries. That is the behaviour item 3 removes, so it now expects ran: 0.
Hold on the desk. The "Releasing trevato/forge: production is rolling" note did not affect this change.
To try it. Run bun test test/feature-call-contract.test.ts. On the features page, Run now on a scheduled tool sends the signed headers, and an app that refuses them answers 404.
Two commits are pushed. The second is an empty "Try:" commit, added because the pre-push hook required one.
This pull makes a feature's tool get the same signed headers whether it is run by hand or by the clock. It also probes a feature's schedule once and counts it proven only after a 200 run.
The last check failed on the gate's "both doors" rule. src/apps/schedule_probe.ts is internal plumbing with no screen of its own, and the rule wants a terminal screen and a how-to doc for any new feature module. I added neither; instead I pushed an empty commit with a No door: line in its message, which the gate accepts. The line says the only surface is the existing Settings › Features page, which already has both doors.
bun scripts/gate.ts ran after the commit and printed nothing, which I took as a pass. I did not re-run tsc or the tests, because only a commit message changed. The forge's check will run on this push.
Try it from Settings › Features › Run now. An app that refuses the forge's signed headers answers 404 there, as it would to the clock.
🤖 Generated with Claude Code
The header unification is sound and the docs section is clear, but four things need fixing in one round.
- Fix first: the probe wiring is untested.
probeFeatureintimer_service.tsand theSYNC_REVISIONbump are what actually make a probe happen once per commit. The tests callprobeSchedulesdirectly, so deleting theprobeFeaturecall fromsyncAllleaves every test green. Add a test that drivessyncAlland asserts one probe on a new commit and none on the next pass. syncAllnow awaitsreach.ensure(which can boot an app) and a call of up to WAIT_MS for each scheduled tool. All of that runs inside the once-a-minute sync loop, so one slow app delays every other app's schedule read. Run the probes after the sync loop, or off it, with a bounded total time. Also cover non-production envs deliberately, or say why only production is probed.schedules.rannow requireshttp_status = 200exactly. An app that answers 204 or 202 to its scheduled tool, which is a valid success, is reported as never proven. Countstatus = 'ok'and any 2xx, and add a test.- A person's hand call is signed as
forge-timer|manual:...|timer. An app that follows the documentedfromForgecheck cannot tell a person's call from the clock's, and the docs call the identity a timer's. Either mark hand calls with a distinct kind in the identity, such asforge-hand, and document thatfromForgeaccepts both, or state in the docs that this is deliberate. Also,callTooltakeskeyas a bare positional string; theoptsbag is already there, so keep the signature honest.
The docs live in docs/features/feature-schedule.md and README is untouched, which is right. The No door: empty commit is accepted. I did not exercise the preview beyond reading the diff.
All four points are addressed and pushed. tsc is clean and gate has nothing to report. The four test files that cover the change pass (20 tests). scripts/fast.ts named 2,237 test files for this diff, so I did not run the full set; the forge's check will.
- Probe wiring.
syncAllnow takes an optionalreachas its third argument. The new test intest/timers-sync.test.tscreates an app on a real commit with a probing scheduled tool. It asserts one probe on the first pass and still one on the second. I did not delete theprobeFeaturecall to confirm the test turns red, but it would see 0 probes. - Probes off the read path.
syncAllnow reads every app's schedules first and probes afterwards. The probes are bounded by a 30 s budget for the whole pass, and any left over when it runs out are not retried. Only production is probed, and the comment and the docs say why: a preview's schedules do not fire, so a refusal there would be reported for a run that never comes. - Any 2xx proves a schedule.
schedules.rannow counts runs withstatus = 'ok'and anhttp_statusfrom 200 to 299. A new test shows a 404 run does not count and a 204 run does. - Hand identity and
callTool. I chose the "deliberate" option, so a hand call is still signedforge-timer|manual:…|timer. A distinct kind likeforge-handwould break theforge-timer|check in every app that already follows the documentedfromForge. The docs now say a hand call is signed as a timer's on purpose, and that themanual:prefix on the idempotency key is how an app can tell it from the clock's.callToolnow takesopts: { key, probe?, now? }instead of a bare positional key, and all callers and tests are updated.
The gate failure is fixed and pushed. The three flagged spots, all in the new test in test/timers-sync.test.ts, are changed. bun x tsc --noEmit is clean and bun test test/timers-sync.test.ts passes (2 tests). bun scripts/gate.ts printed nothing once the fix was committed; it still flagged the same lines while the edit was uncommitted, so it appears to read the committed diff. I did not re-run the other test files, since nothing outside this test changed.
newAppcast (line 72): I removed theas never. The input already matchesNewAppInput.reachcast (line 88): it is now typed asReach, with the type imported fromtimer_fire.ts.- Sleep (line 84): the loop that waits for the runtime to deploy the commit now ends with
// real-timer: waits for the runtime to deploy the commit. I kept the real wait because the runtime deploys on its own clock, so there is nothing to inject.
The change to src/ and the docs from the last round is unchanged.
Fixed the one red test the check traced to this pull. I pushed the fix; the forge's check hasn't rerun on it yet.
Cause. The new test in test/timers-sync.test.ts waited for production to deploy the commit, then went on without checking it had. The repository's flake rule (test/flake.test.ts) forbids a poll that runs out of time and carries on. It also read the trailing // real-timer comment as part of the loop, so it didn't see the statement after it.
Change. I moved the comment above the loop and added expect(production()?.commitOid).toBe(tip) straight after it. No production code changed.
Verification. test/timers-sync.test.ts and test/flake.test.ts pass together, 38 tests. tsc --noEmit is clean and gate.ts --fix changed nothing.
The other two failures. I did not change anything for the first-view budget test (65 ms) or the needsYouCard N+1 test. Both passed when I ran them alone, 15 tests across the two files. They looked like load flakes in the 57-shard run and touch nothing this pull edits. If they fail again on the next check, they need a separate look.
I've pushed a fix for the gate failure; the forge's check hasn't rerun on it yet.
Cause. My last fix moved the // real-timer: <why> comment onto its own line above the loop. The gate's rule "a test does not wait on a real timer" wants that comment at the end of the line that sleeps. The flake rule wants the assertion straight after the loop, and it misreads a loop whose single line ends in a comment. The two rules disagreed about one line.
Change. In test/timers-sync.test.ts the deploy wait is now a braced loop. await Bun.sleep(100); // real-timer: waits for the runtime to deploy the commit sits on its own line inside it. The expect(production()?.commitOid).toBe(tip) follows the closing brace. Test-only change; no production code touched.
Verification.
bun scripts/gate.ts --fixis clean once the change is committed. Before the commit it still reported line 86, because it judges the committed diff, not the working tree.test/timers-sync.test.tsandtest/flake.test.tspass together, 38 tests.tsc --noEmitis clean.
The two failures from the earlier run, the first-view budget test and the needsYouCard N+1 test, passed when I ran them alone. I left them as probable load flakes.
All four earlier asks are met. (1) Probe wiring: syncAll takes a reach and the new timers-sync test asserts one probe per commit, not repeated. (2) Probes run after every app is read, under a 30 s pass budget, production only. (3) schedules.ran counts only status ok with a 2xx, with a 404/204 test. (4) The hand identity is documented as deliberately a timer's, and callTool takes an opts object. The preview answers 200 and the checks the builder reports are green. Next, two things I would do: (a) Non-blocking: in src/apps/timer_service.ts the doc comment for SYNC_REVISION ("Bumped when...") now sits above PROBE_BUDGET_MS, so it describes the wrong constant. Move PROBE_BUDGET_MS above that comment, or give it its own. (b) Non-blocking: add "probe": true plus the x-forge-probe handler to the morning paper, so its schedule is actually checked in advance, and give the app template a /forge/tools route that uses fromForge.
Items 1–3 are done; item 4 is not, and item 2 covers only tools that opt in. A feature's tool is now called with the same signed headers whether a person or the clock runs it. The tests I ran pass (173 of 174), and the one failure is fixed below. I did not run the full suite; the forge's check does that.
What changed
callHeadersinsrc/apps/timer_fire.tsbuilds the headers for every call. The timer delivery (deliveryHeaders) and the hand-runcallToolboth use it, so a hand-run call now carriesx-forge-identityandx-forge-signaturetoo.callToolandrunRecordedtake the app's identity key as a new argument; thefeaturestool passes it.docs/features/feature-schedule.mdhas a new "Calling a tool" section. It lists the headers and says how an app verifies "this is my forge": the identity starts withforge-timer|, has not expired, and its signature checks underFORGE_APP_IDENTITY_KEY. It also says not to guess from header absence.test/feature-call-contract.test.tsuses an app that refuses anything it can't verify. It shows the hand's headers cover the clock's, and that a wrong key gets a 404.SYNC_REVISIONis now#3, so every app's schedules are re-read once. After that read, and on each new production commit,src/apps/schedule_probe.tssends each scheduled tool one call withx-forge-probe: 1. An app that refuses it gets a failed run on the schedule, and the owner is asked through the existing failing-run ask (failingNow). An accepted probe records nothing./api/v1/healthschedules.rannow counts a schedule only when a fired run was answered 200. A failed run, or a refused probe, no longer counts.What I chose not to do
"probe": trueis probed. It must answer 200 to the probe header without doing its work. Probing the paper's print without that promise would print the paper, so a feature that hasn't opted in is still not checked in advance. The morning paper would need to add"probe": trueand honour the header.templates/app-template.jsonis a pinned snapshot of another repository, so I did not edit it. ItsfromForgeinsrc/once.tsalready implements the documented check, but the template has no/forge/toolsroute yet. The docs point tool routes atfromForge.Existing test I changed.
test/feature-schedule-one.test.tsexpectedran: 1after a schedule that failed past its retries. That is the behaviour item 3 removes, so it now expectsran: 0.Hold on the desk. The "Releasing trevato/forge: production is rolling" note did not affect this change.
To try it. Run
bun test test/feature-call-contract.test.ts. On the features page, Run now on a scheduled tool sends the signed headers, and an app that refuses them answers 404.Two commits are pushed. The second is an empty "Try:" commit, added because the pre-push hook required one.
Closes #14216