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

Merged opened this in answer to

Check · Review · Land · Live done — Landed and live in production.

Merged

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.

Notes

shipped production is serving it deploy 8e1361f

opened this

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. callHeaders in src/apps/timer_fire.ts builds the headers for every call. The timer delivery (deliveryHeaders) and the hand-run callTool both use it, so a hand-run call now carries x-forge-identity and x-forge-signature too. callTool and runRecorded take the app's identity key as a new argument; the features tool passes it.
  • Contract in the docs. docs/features/feature-schedule.md has a new "Calling a tool" section. It lists the headers and says how an app verifies "this is my forge": the identity starts with forge-timer|, has not expired, and its signature checks under FORGE_APP_IDENTITY_KEY. It also says not to guess from header absence.
  • Contract test. test/feature-call-contract.test.ts uses 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_REVISION is now #3, so every app's schedules are re-read once. After that read, and on each new production commit, src/apps/schedule_probe.ts sends each scheduled tool one call with x-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/health schedules.ran now 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": true is 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": true and honour the header.
  • Template not changed (item 4). templates/app-template.json is a pinned snapshot of another repository, so I did not edit it. Its fromForge in src/once.ts already implements the documented check, but the template has no /forge/tools route yet. The docs point tool routes at fromForge.

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.

Closes #14216

5 earlier comments · 1 event
commented

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. callHeaders in src/apps/timer_fire.ts builds the headers for every call. The timer delivery (deliveryHeaders) and the hand-run callTool both use it, so a hand-run call now carries x-forge-identity and x-forge-signature too. callTool and runRecorded take the app's identity key as a new argument; the features tool passes it.
  • Contract in the docs. docs/features/feature-schedule.md has a new "Calling a tool" section. It lists the headers and says how an app verifies "this is my forge": the identity starts with forge-timer|, has not expired, and its signature checks under FORGE_APP_IDENTITY_KEY. It also says not to guess from header absence.
  • Contract test. test/feature-call-contract.test.ts uses 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_REVISION is now #3, so every app's schedules are re-read once. After that read, and on each new production commit, src/apps/schedule_probe.ts sends each scheduled tool one call with x-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/health schedules.ran now 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": true is 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": true and honour the header.
  • Template not changed (item 4). templates/app-template.json is a pinned snapshot of another repository, so I did not edit it. Its fromForge in src/once.ts already implements the documented check, but the template has no /forge/tools route yet. The docs point tool routes at fromForge.

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.

commented

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

Changes requested — before the latest push

The header unification is sound and the docs section is clear, but four things need fixing in one round.

  1. Fix first: the probe wiring is untested. probeFeature in timer_service.ts and the SYNC_REVISION bump are what actually make a probe happen once per commit. The tests call probeSchedules directly, so deleting the probeFeature call from syncAll leaves every test green. Add a test that drives syncAll and asserts one probe on a new commit and none on the next pass.
  2. syncAll now awaits reach.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.
  3. schedules.ran now requires http_status = 200 exactly. An app that answers 204 or 202 to its scheduled tool, which is a valid success, is reported as never proven. Count status = 'ok' and any 2xx, and add a test.
  4. A person's hand call is signed as forge-timer|manual:...|timer. An app that follows the documented fromForge check 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 as forge-hand, and document that fromForge accepts both, or state in the docs that this is deliberate. Also, callTool takes key as a bare positional string; the opts bag 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.

commented

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.

  1. Probe wiring. syncAll now takes an optional reach as its third argument. The new test in test/timers-sync.test.ts creates 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 the probeFeature call to confirm the test turns red, but it would see 0 probes.
  2. Probes off the read path. syncAll now 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.
  3. Any 2xx proves a schedule. schedules.ran now counts runs with status = 'ok' and an http_status from 200 to 299. A new test shows a 404 run does not count and a 204 run does.
  4. Hand identity and callTool. I chose the "deliberate" option, so a hand call is still signed forge-timer|manual:…|timer. A distinct kind like forge-hand would break the forge-timer| check in every app that already follows the documented fromForge. The docs now say a hand call is signed as a timer's on purpose, and that the manual: prefix on the idempotency key is how an app can tell it from the clock's. callTool now takes opts: { key, probe?, now? } instead of a bare positional key, and all callers and tests are updated.
commented

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.

  • newApp cast (line 72): I removed the as never. The input already matches NewAppInput.
  • reach cast (line 88): it is now typed as Reach, with the type imported from timer_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.

commented

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.

commented

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 --fix is 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.ts and test/flake.test.ts pass together, 38 tests.
  • tsc --noEmit is 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.

Approved

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.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs