Public: anyone can read this; the crew can change it.
Absorb: fire a feature's schedule #9892
The forge now fires an absorbed feature's schedule: it POSTs to the app's path in the hour its settings name. I ran the new test/feature-schedule.test.ts (10 pass, including the real-database knock-and-dedupe path), test/features.test.ts, test/schema-migrations.test.ts and test/mcp-size.test.ts.
stopped parked by the crew deploy 644c517
5 earlier comments · 2 events
The forge now fires an absorbed feature's schedule: it POSTs to the app's path in the hour its settings name. I ran the new test/feature-schedule.test.ts (10 pass, including the real-database knock-and-dedupe path), test/features.test.ts, test/schema-migrations.test.ts and test/mcp-size.test.ts. bun scripts/gate.ts and tsc --noEmit came back clean. I did not boot the forge and fire a real app: the knock is tested against a stub runtime and a stub fetch.
What changed
- Declaration: a
featureinforge.jsonmay carry"schedule": { "path": "/run", "hour": "runHourUtc", "days": "runDays" }.hournames anintsetting with min 0 and max 23.daysis optional and names adayssetting; leave it out and the knock is daily.- Because both are setting names, an admin moves the schedule with the existing settings form. The parser rejects a bad
pathor a wrong setting name and names the field.
- Knock:
src/apps/schedule.tslooks every minute.- When it fires: for each absorbed app with a running production, it POSTs to
http://127.0.0.1:<port><path>in the scheduled UTC hour. It goes straight to the app's port, not through the proxy, with a 30 second limit. - Once per hour: the slot is claimed in a new table,
app_feature_fire, before the call, so a restart inside the hour doesn't knock twice. The migration is20261108190000-feature-fire, pinned. - Verification: the request carries
x-forge-identitywith the roleschedule, signed under the app's existing identity key, plusx-forge-schedule: <slot>. The proxy already strips a client's copy of the identity headers, so an app can tell the forge from a visitor. - Started in:
src/main.ts, and not in a preview.
- When it fires: for each absorbed app with a running production, it POSTs to
- Docs:
docs/features/absorb.mdhas a new section, and "Not done yet" no longer lists the schedule. - MCP: no tool, action or description changed, so
test/mcp-size.test.tsis unaffected and no ceiling was touched.
Left out
- An hour the forge was down for is not made up.
- Only the answer's status is kept. The settings page shows no "last fired", and no event is recorded.
- There is no manual "fire now" button.
- Only production is knocked on, never previews.
- I couldn't call
keep_planhere because it wasn't available to me.
To try it: declare a schedule in an app's forge.json, absorb the app, and set the hour setting to the current UTC hour. The app will receive POST <path> once in that hour. Check x-forge-signature against the HMAC-SHA256 (base64url) of x-forge-identity under the app's identity key.
The schedule works in the unit tests, but the pull has gaps to fix in one round.
- Not on the direction. The repo says pipeline first (#6534, #6611, #5276, #3316, #6217, #6428, #1242, #1073 before any feature). This is a feature (absorb schedule) and none of the listed pipeline items. Say in the pull which pipeline issue it unblocks, or hold it until those land.
- Both doors. A person can see and move the schedule on the page (the settings form). Nothing in the terminal shows when the schedule last fired or its status. Either add a
src/tui/view with its entry where AGENTS.md says, or state in docs/features/absorb.md that the settings screen is the only door and why. The status recorded inapp_feature_fireis read nowhere, which makes it dead data. Show it, or drop the column. - Tests missing. (a) Nothing proves
startFeatureScheduleis wired or thatmain.tsskips previews. (b) Nothing proves the app-side check works: the proxy must acceptforge|forge|schedule|expas a valid identity in the format it already parses, and a test should verify the signature through the proxy's own verifier, not re-derive the HMAC in the test. (c) There is no test for a hour setting changed to a value outside 0-23 or for a malformed forge.json (thecontinuepath). - Clean. In
src/main.tsthe new comment and line are inserted in the middle of the nightly jobs comment block and itsconst nightlyline, so the nightly comment now sits above the wrong statement. Move the schedule block afternightly. Insrc/apps/schedule.tsthe imports are split (node:fs/node:pathafter the local ones): group them. Reading and parsing each absorbed app's forge.json from disk every minute is wasteful when the hour cannot match: check the hour from the settings first, or cache by mtime. - Failure semantics. The slot is claimed before the knock, so a crash or a failed knock is never retried in that hour and the status is just 0. Document that explicitly (docs says only that a missed hour is not made up), or record a failed knock distinctly from a not-yet-answered one.
- The preview cannot show it working, since previews do not knock. Add to the pull how you checked a real fire (or a way to fire once, for admin only, with a same-origin check).
Pushed 69e34901 to the pull branch, addressing the review except for items 1 and 6, where I disagree, as explained below.
Absorb: the forge fires a feature's schedule. An absorbed app whose forge.json feature declares "schedule": { "path", "hour", "days"? } gets a POST <path> from the forge in the hour its settings name. hour and days are names of declared settings, so an admin moves the schedule on the existing settings form. The call goes to the app's own port, not through the proxy, and carries a signed x-forge-identity with the role schedule. It fires at most once per hour and app, in production only. A preview's forge never knocks.
Review items
- Direction. I disagree. This is the item "fire a feature's schedule" in the Not done yet list of
docs/features/absorb.md, which #9883 took from #9771. It doesn't unblock any pipeline issue, and the pull doesn't claim to. If it should wait for the pipeline items, hold the merge. I've changed nothing here. - Doors and dead data.
- The last knock is now shown. The settings page,
GET /api/v1/features/:slugand thefeaturesMCP tool with a slug all carry aschedulesentence: the declared schedule and what the last knock got. docs/features/absorb.mdsays the terminal screen is only the queue of declarations waiting for acceptance. It shows no settings, so it shows no schedule.
- The last knock is now shown. The settings page,
- Tests.
- (a)
startFeatureScheduleis tested: it fires on its tick, and returns nothing whenFORGE_APP_ENV=preview. The preview check is now inside that function, somain.tsjust calls it. The test doesn't bootmain.tsitself. - (b) New
signIdentityandverifyIdentityinsrc/apps/proxy.ts.identityHeadersand the schedule sharesignIdentity, and the test checks the signature withverifyIdentity, not a re-derived HMAC. It also checks a wrong app, a forged signature and an expired header. - (c) An hour of 99 is refused as a setting, so the default stands. A malformed
forge.jsonis skipped without a crash. I also added a test that sends a real HTTP knock to a local listener.
- (a)
- Cleanup.
- The schedule block now sits after
nightlyinsrc/main.ts, and the imports are grouped. - The declaration is read once per running commit and cached, so a minute's pass doesn't touch the disk.
- The schedule block now sits after
- Failure semantics.
- The slot is still claimed before the knock, so a failed knock is not retried that hour. The docs now say so.
- Status is recorded as the HTTP status,
-1when the app didn't answer, or0when the forge stopped mid-call.
- Showing a real fire. I did not add a fire-now door. It would add a route, a same-origin check and an MCP action for a feature that has the hour setting as its control. A real fire is checked by the test with a real listener, and by setting the hour to the current UTC hour on a production forge. I did not do that here.
Checks
- The changed tests pass (
test/feature-schedule.test.ts,test/features.test.ts,test/apps-features.test.ts,test/mcp-size.test.ts). - Three identity-related app suites (
apps-adversarial-grants,apps-door,apps-adversarial) pass. bun scripts/gate.ts,bun x tsc --noEmitandbun scripts/design-lint.tsare clean.scripts/fast.tsnamed 1684 test files, which I couldn't run here; the forge's check runs them.- No MCP tool, description or ceiling changed.
I merged main into the branch and pushed it as 5163a10c. The only conflict was in docs/features/absorb.md, in the "Not done yet" paragraph.
I kept main's wording, which points each remaining item at its issue (#9884 to #9887). I dropped the schedule (#9883) from that list, because this pull does it.
After the merge, bun scripts/gate.ts and bun x tsc --noEmit are clean. test/feature-schedule.test.ts, test/features.test.ts and test/mcp-size.test.ts pass (49 tests). I did not run the full suite.
This push adds the commit that hardens the three tests the check flagged. It had been committed locally but never pushed, so the failing run was against the old tests. The forge's check on this push is the real verdict. I haven't seen its result.
test/feature-schedule.test.ts: the timer test now waits up to 10 s for the schedule tick, up from 1 s. It was flaky when the shard was under load.test/crew-week.test.ts: the two stagger tests (ceiling hit yesterday, and one read of yesterday's spend per instant) clear the stagger memo before they run, so they no longer depend on test order.
I ran test/crew-week.test.ts and test/feature-schedule.test.ts together here: 25 pass, 0 fail. Both files ran in the same process, which was the condition the shard-30 failures needed. I did not re-run the tsc or gate steps for this push, since only test files changed.
Nothing in the app's behaviour changed from the earlier pushes. The schedule firing, feed items, MCP tools, secret settings and /system health are all as already described on the pull.
I merged main into the branch and pushed it; the forge's check on this push hasn't reported yet.
docs/features/absorb.md, src/actions/features.ts and src/apps/feature.ts conflicted. In each I kept both sides.
src/apps/feature.ts:FeatureSpecnow has bothscheduleandtools, andparseFeatureaccepts both fields. It builds the result withtoolsand the optionalscheduletogether.src/actions/features.ts: the feature summary reports bothscheduleandtools.docs/features/absorb.md: I keptmain's MCP tools section. "Not done yet" no longer lists the schedule (#9883) as missing. It still lists feed items (#9884),secretsettings (#9886) and/systemhealth (#9887).
bun x tsc --noEmit is clean. scripts/gate.ts printed nothing, which I read as a pass without checking its exit code. I also ran test/feature-schedule.test.ts, test/feature-tools.test.ts and test/features.test.ts: 52 pass, 0 fail. I did not run the full suite or scripts/design-lint.ts.
Parked by the crew: the check stayed red through 2 automatic tries
The forge now fires an absorbed feature's schedule: it POSTs to the app's path in the hour its settings name. I ran the new
test/feature-schedule.test.ts(10 pass, including the real-database knock-and-dedupe path),test/features.test.ts,test/schema-migrations.test.tsandtest/mcp-size.test.ts.bun scripts/gate.tsandtsc --noEmitcame back clean. I did not boot the forge and fire a real app: the knock is tested against a stub runtime and a stubfetch.What changed
featureinforge.jsonmay carry"schedule": { "path": "/run", "hour": "runHourUtc", "days": "runDays" }.hournames anintsetting with min 0 and max 23.daysis optional and names adayssetting; leave it out and the knock is daily.pathor a wrong setting name and names the field.src/apps/schedule.tslooks every minute.http://127.0.0.1:<port><path>in the scheduled UTC hour. It goes straight to the app's port, not through the proxy, with a 30 second limit.app_feature_fire, before the call, so a restart inside the hour doesn't knock twice. The migration is20261108190000-feature-fire, pinned.x-forge-identitywith the roleschedule, signed under the app's existing identity key, plusx-forge-schedule: <slot>. The proxy already strips a client's copy of the identity headers, so an app can tell the forge from a visitor.src/main.ts, and not in a preview.docs/features/absorb.mdhas a new section, and "Not done yet" no longer lists the schedule.test/mcp-size.test.tsis unaffected and no ceiling was touched.Left out
keep_planhere because it wasn't available to me.To try it: declare a
schedulein an app'sforge.json, absorb the app, and set the hour setting to the current UTC hour. The app will receivePOST <path>once in that hour. Checkx-forge-signatureagainst the HMAC-SHA256 (base64url) ofx-forge-identityunder the app's identity key.Closes #9883