feat(tuval): cron wakes on a timer, starts a job program and reports the run on its tile

[cansirin]

Tuval had no scheduler. cron is a program on defineProgram that wakes on a timer, starts a job
program it knows only by its ports, and says on its board tile how the run went. It is the first
consumer written on the authoring layer from outside the kernel, and it is the program that
surfaced #8762, #8887, #8898/#8858 and #9220 on the way.

cron({everyMs, prompt, job}) returns the row. job is Program.shape over the AI-agent payloads
out of ai-agent/ports/index.ts — the interface module, the same import the pr-review example
makes — so the config hands it claudeSession({…}) itself and cron imports no session. A tick
spawns the job with on: {result}, sends a well-formed PromptPayload, records the run when the
answer lands and stops the child; a tick while a job runs spawns nothing and the tile says
running since. The stopped cell handles the answer to cron's own stop; its other branch — a
job that died before answering — is written for the day #9227 delivers that event and is
unreachable under today's kernel, stated in the module header and the cell and under Deviations. A restored cron whose
checkpointed child is no longer live records that run as interrupted, so a restart cannot wedge
every later tick. History is bounded at ten. :cron run is a commands cell answering
send("run"), the shape ADR 0372 takes since #9221.

The cron flag is declared on TuvalFeatures/featuresDefault (src/features.ts) the way
prReviewExample is — off there, flipped on by this repo's own layer, so the key reaches the
Features service and the generated browser module and not the row alone. That registration was
missing on the first head and is the second repair in this round; round-2 criterion #8 on #9225.

The first job, in .tuval/tuval.config.ts behind features.cron, is a read-only phoenix brief
through gh: merged PRs, new issues, anything ready-for:human, five lines, every ten minutes.

Gates at this head: pnpm typecheck 0 errors; npx biome check src/cron src/features.ts .tuval src/boot.unit.test.ts src/config.unit.test.ts src/page/dev-server.unit.test.ts clean; pnpm vitest run --project unit 321 passed / 1 failed, the one pre-existing failure named below. Boot with the
flag on: 9 program(s), process cron program=cron … state=running@0, no HandlerFailed.

One earlier run was verified by hand on the first head (20s cadence, ~4 min): .tuval/processes/ cron.json ended with ticks: 11 and seven runs, all ok: true, each a real gh readout off a
live Claude session. That is a manual proof, not an input this gate reads — no checked-in artifact
or test carries it, so read the "one real tick lands ok: true" half of criterion 6 as unverified
by the gate rather than as evidence.

Reviewer's first stop: the result and resume cells in apps/tuval/src/cron/cron.ts.

Fixes #9225

Deviations

• Known gap left unfixed — Said: :cron run fires a tick on demand. Did: declared the
  command and the run cell; live, the spell refuses with UnknownProcess for the cron the boot
  graph launched. Why: resolution through own-process.ts finds the planned cron off
  ProcessTable, but delivery goes through SpawnedProcesses.send, whose live map holds only
  processes it spawned — process send cannot reach a graph-launched process: only ad-hoc spawns are addressable #8944, filed before this PR and now with a second caller. Working around
  it here would mean cron spawning itself ad hoc, which is not what a planned process is.
  Disposition: documented in the module docblock citing process send cannot reach a graph-launched process: only ad-hoc spawns are addressable #8944; the spell starts working the
  day that lands, with no change to this file.
• Pre-existing failure left red — Said: the unit project is green. Did: shipped with
  src/page/attached-desk.unit.test.tsx › "closes on Escape from inside the overlay" failing.
  Why: it fails identically on clean origin/main (bc890986), reproduced 2/2, and touches
  nothing cron does. Disposition: not this PR's to fix; named here so the gate reads it as
  known rather than introduced.
• Branch written for an event the kernel does not deliver — Said: a job that ends before
  answering is recorded as a failed run. Did: the stopped cell has that branch, and live it
  is unreachable — stopped is only ever the answer to a program's own stop effect
  (stopHandler in authoring/define-program.ts); nothing dispatches an unsolicited child exit
  into a spawner's inbox, so a job that crashes before result leaves child set and later ticks
  dropped until a restart, which resume reconciles. Why: delivering it is a kernel change to
  on routing at the child's end, which is a program's to consume and not a program's to make —
  filed as An authored spawner never hears an unsolicited child exit: stopped is only ever the answer to its own stop effect #9227. Disposition: the cell and its testProgram case stay, renamed to say they
  prove the cell and not live behaviour; the module header and the cell's docblock cite An authored spawner never hears an unsolicited child exit: stopped is only ever the answer to its own stop effect #9227 the
  way process send cannot reach a graph-launched process: only ad-hoc spawns are addressable #8944 is cited; the branch needs no change to this file the day An authored spawner never hears an unsolicited child exit: stopped is only ever the answer to its own stop effect #9227 lands.
• Durability leak observed, not addressed — Said: cron stops each child on result.
  Did: it does, and the stopped children still accumulate in .tuval/manifest.json and are
  restored on the next boot. Why: the manifest has no forget path; that is A child ended by the authored stop effect is still restored on the next boot: the manifest never forgets a stopped process #9220, whose
  stop-versus-forget question A Tuval process cannot be killed from the desk, so a stray process is restored on every boot #8332 reserves for the founder. Disposition: cron's resume
  reconciliation keeps a restart from wedging; the restore of dead children is A child ended by the authored stop effect is still restored on the next boot: the manifest never forgets a stopped process #9220's.

Base is main.

🤖 Generated with Claude Code

[github-actions]

🚀 Preview deployed

• web — Stage pr-9226 torn down.

[cansirin]

review-code: FAIL @ 0e6b575 content:265d2661134e — repair round

review-code — FAIL

Graded against #9225's seven acceptance criteria, read at head 0e6b5750. Conjunctive: one FAIL row fails the class.

Per-criterion

• [PASS] 1. cron(options) on defineProgram, job filled through fill, no session package imported — apps/tuval/src/cron/cron.ts L300–314 (defineProgram({...cronProgram(fill), fill: {job: fill.job}, ...})); imports are ../ai-agent/ports/index.ts (the interface module, same import authoring/example/pr-review.ts makes) and ../authoring/* only. cron.unit.test.ts "puts the job on the row's fill" drives the compiled spawn handler and sees claude-session resolved off the fill.
• [FAIL] 2. A tick spawns, sends a well-formed PromptPayload, records on result and stops the child; a child that ends before answering is recorded as a failed run; a tick mid-run spawns nothing — the first and third clauses hold (startIfIdle, spawned → send({process, port: "prompt"}, {text, key, timestamp}), result → recorded + stop(state.child); tests "sends the configured prompt…", "stops the job it started…", "drops a tick…"). The middle clause does not hold at runtime. The authoring layer produces a stopped event in exactly one place: apps/tuval/src/authoring/define-program.ts L333–336, stopHandler, as the answer to the program's own stop effect. A child that exits on its own publishes {kind: "stopped"} to the ProcessTable stream (apps/tuval/src/process/Processes.ts L289) and its live finalizer in apps/tuval/src/commands/core/process.ts L326–334 deletes the entry; nothing subscribes and dispatches a stopped into the parent's inbox (git grep of stopped( / "stopped" across apps/tuval/src at head finds no other producer). So the stopped cell's "the job died before it answered" branch (cron.ts L217–231) is unreachable under the live kernel: a job that crashes before result leaves child set and every later tick dropped until a restart. cron.unit.test.ts "records a failed run when the job dies before it answers" feeds the event by hand, so it proves the cell, not the behaviour the criterion names. The cell's docblock states the behaviour as delivered ("without it a crashed job would leave … child set forever") — that claim is not grounded in the code read. Repair: either deliver an unsolicited child exit to the spawner (the ProcessTable stopped change for a child spawned with on → the parent's stopped event), with a test that drives it through the compiled handlers rather than testProgram; or, if that is a kernel issue of its own, file it, cite it in the stopped cell and the module header the way process send cannot reach a graph-launched process: only ad-hoc spawns are addressable #8944 is cited, and disclose it under ## Deviations.
• [PASS] 3. A restored cron whose checkpointed child is not live records the run as interrupted and the next tick spawns — resume (L262) emits restored only when child !== null; the restored cell (L253–261) records INTERRUPTED and clears child; tests "records the half-finished run as failed…", "spawns on the very next tick…", "reconciles once…". Note: the cell records interrupted whether or not the child is live — a superset of the criterion — and L234–252 states why (restore spawns with no on record and unwired ports, verified at apps/tuval/src/durability/restore.ts L26/L55, so a live restored child cannot answer; a blind stop fails ProcessNotFound out of resume). Accepted as documented.
• [PASS] 4. title/status on the kernel's title@1/status@1 — title/status derived lines (L281–291) compile onto TITLE_PORT/STATUS_PORT (define-program.ts L194–199; self-report.ts L17–18). Tests assert emit(STATUS_PORT, "last run 07:00 · ok") etc.; boot.unit.test.ts pins the booted row's title@1:out(tuval/title/v1),status@1:out(tuval/status/v1) ports.
• [PASS] 5. :cron run as a commands cell answering send("run"); run cell behaves as a tick; refusal documented as process send cannot reach a graph-launched process: only ad-hoc spawns are addressable #8944 — commands.run (L266–279) returns send("run", request); the run port cell (L184–187) calls the same startIfIdle; the module header and the command docblock name process send cannot reach a graph-launched process: only ad-hoc spawns are addressable #8944 and work nothing around it. resolveOwnProcess (authoring/own-process.ts) and SpawnedProcesses.send's live-only map (commands/core/process.ts L242–250) confirm the header's account of the refusal. Tests under "cron's run command".
• [FAIL] 6. Config registers cron behind a feature toggle with claudeSession(...); pnpm dev boots with it on; one real tick lands ok: true in .tuval/processes/cron.json — the row is gated on a local features.cron and the job is claudeSession({cwd, scope}) (apps/tuval/.tuval/tuval.config.ts L73–96, L120–123, L129–136), and boot.unit.test.ts boots the box config with cron live. Two misses. (a) cron is not declared on TuvalFeatures / featuresDefault in apps/tuval/src/features.ts. DeclaredFeatures derives its keys from featuresDefault (config.ts L70–76) and its own comment records that an undeclared key "was dropped by the decode" — so the config's cron: true reaches the row (ADR 0375 §1) and nothing else: not the Features service, not the generated browser module. ADR 0375 §3 and features.ts's header ("A flag added here is one edit…") require the flag declared there; prReviewExample, the one precedent, is in both places. Filed as round-2 criterion effect-migration: port resolver-down code to Effect Context.Service #8 on Tuval has no scheduler: a cron program on defineProgram that starts a job program on a timer and reports each run on its tile #9225. (b) The "one real tick lands a run with ok: true" half is evidenced by nothing this gate reads — it lives in PR-body prose, which is not an input; no checked-in artifact or test carries it. Not weighed as a defect, named as unverified.
• [PASS] 7. cron.unit.test.ts on testProgram; boot.unit.test.ts updated — 25 cases across the tick, result, stopped, restored, run-command and shape seams; boot test moves 8→9 programs, 3→4 processes, +1 spell, and pins the cron process line. The pre-existing assertion changes are the ones the criterion asks for.

Standing checks

• Test honesty: no pre-existing assertion weakened; the boot-count moves are the criterion's own.
• Release containment: default-ON, stated with rationale in the config comment. Containment is stated; the toggle itself is unregistered (row 6a).
• Comment discipline: the cron.ts docblocks are dense but nearly all state kernel constraints the code cannot show (restore wiring, SpawnedProcesses delivery, ADR 0372). One of them (the stopped cell) states a behaviour the kernel does not deliver — row 2.
• Staleness traps: none. Timer Sub is dep-keyed on everyMs; child is cleared on result, not on the answering stopped.

Fan-out

• Silent failure: row 2 — an unsolicited child exit is silently absorbed (no event, child stays set).
• Type design (out of scope, not filed): CronState.child and startedAt are two nullables that must move together; a single running: {child, startedAt} | null would make the half-set state unrepresentable. Nit.
• Test gap: row 2 — nothing drives a child exit through the compiled handlers.

Deviations

Disclosed	Substance	Matched against findings
:cron run refuses for a graph-launched cron	#8944, documented, not worked around	Matches row 5; PASS
attached-desk.unit.test.tsx › closes on Escape red on base	pre-existing on bc890986	Not cron's; CI-at-head is the gate's answer
Stopped children accumulate in the manifest	#9220	Matches; out of this diff
— undisclosed —	stopped cell unreachable for an unsolicited child exit (row 2)	Not in the section
— undisclosed —	cron flag stated in config but not registered in features.ts (row 6a)	Not in the section

deviation-disclosure: FAIL — two findings this gate could see are not in the section.

CI at head

settle settled · ci 0e6b5750 green — 45 check runs, 39 success, 6 skipped; 28 of 40 repo-authored workflows ran at head. Execution evidence is green; the FAIL above is judgement CI cannot make.

Verdict

FAIL on rows 2 and 6. Repair round: deliver (or honestly scope and disclose) the child-exit path, register the cron flag in features.ts, and re-post over the new head.

Verdict-written: 2026-09-15T10:36:18Z

[cansirin]

review-code: PASS @ 268e017 content:531c21a57266 — merge-ready

review-code — PASS (repair round 2)

Graded against #9225's eight acceptance criteria (seven original, #8 appended at round 1), read at head 268e017a. Conjunctive.

Per-criterion

• [PASS] 1. cron(options) on defineProgram, job filled through fill, no session package imported — apps/tuval/src/cron/cron.ts L318–333; imports are ../ai-agent/ports/index.ts (the interface module) and ../authoring/* only. Unchanged from round 1.
• [PASS] 2. Tick spawns, sends a well-formed PromptPayload, records on result and stops the child; a child that ends before answering is recorded as a failed run; a tick mid-run spawns nothing — first and third clauses as before (startIfIdle, spawned → send({process, port: "prompt"}, {text, key, timestamp}), result → recorded + stop). The middle clause took the repair path the round-1 verdict named: the kernel gap is filed as An authored spawner never hears an unsolicited child exit: stopped is only ever the answer to its own stop effect #9227 (open, describes exactly the single-producer stopHandler at authoring/define-program.ts L331–336 — re-verified at this head, no other stopped producer into a spawner's inbox), cited in the module header and the stopped cell's docblock the way process send cannot reach a graph-launched process: only ad-hoc spawns are addressable #8944 is, the test renamed to say it proves the cell and not live behaviour ("cell, unreachable until An authored spawner never hears an unsolicited child exit: stopped is only ever the answer to its own stop effect #9227…"), and the gap disclosed under ## Deviations. The round-1 misstatement ("without it a crashed job would leave child set forever") is gone; the docblock now states the live consequence honestly. Nothing worked around.
• [PASS] 3. Restored cron with a checkpointed child records interrupted, next tick spawns — resume L258, restored cell L245–257; tests under "cron, restarted mid-run". Unchanged.
• [PASS] 4. title/status on title@1/status@1 — L277–287; boot.unit.test.ts pins title@1:out(tuval/title/v1),status@1:out(tuval/status/v1) on the booted row. Unchanged.
• [PASS] 5. :cron run as a commands cell answering send("run"); run cell is a tick; refusal documented as process send cannot reach a graph-launched process: only ad-hoc spawns are addressable #8944 — commands.run L266–275, run port cell L183–186, header cites process send cannot reach a graph-launched process: only ad-hoc spawns are addressable #8944 (open). Unchanged.
• [PASS] 6. Config registers cron behind a feature toggle with claudeSession(...); pnpm dev boots with it on; one real tick lands ok: true — .tuval/tuval.config.ts L74–95, L122–123, L129–136; boot.unit.test.ts boots the box config with cron live (9 program(s), 4 process(es), process cron … state=running@0). Round-1 miss (a) is closed by criterion 8 below. The "one real tick lands ok: true" half is still evidenced by nothing this gate reads — PR-body prose says as much itself — so it is named as unverified, not weighed as a defect, the same reading round 1 gave it.
• [PASS] 7. cron.unit.test.ts on testProgram; boot.unit.test.ts updated — 26 cases; boot test moves 8→9 programs, 3→4 processes, CRON_SPELLS = 1. Unchanged in substance; one test renamed for An authored spawner never hears an unsolicited child exit: stopped is only ever the answer to its own stop effect #9227.
• [PASS] 8. cron declared on TuvalFeatures and featuresDefault with the ADR 0375 row-flag docblock — apps/tuval/src/features.ts L63–77 and L94: the docblock mirrors prReviewExample's (row stated one layer lower, A Tuval feature flag stated in a config layer never reaches the node side #8595, global layer reaches the Features service and not the row, ADR 0375). DeclaredFeatures derives its fields from featuresDefault (config.ts L76), so cron: true in the config now survives decode. config.unit.test.ts (7 expectation records) and page/dev-server.unit.test.ts (3 generated-module strings) carry cron: false at default.

Standing checks

• Test honesty: no pre-existing assertion weakened; the boot-count and feature-record moves are criterion 7/8's own.
• Release containment: default-off in featuresDefault, flipped on by this repo's own layer with the rationale stated in both the config comment and the features.ts docblock. Matches the diff.
• Comment discipline: dense but load-bearing — restore wiring, SpawnedProcesses delivery, ADR 0372, An authored spawner never hears an unsolicited child exit: stopped is only ever the answer to its own stop effect #9227's unreachable branch are all constraints the code cannot show. No narration of obvious flow.
• Staleness traps: none. Timer Sub dep-keyed on everyMs; child cleared on result, not on the answering stopped.

Fan-out

• Silent failure: the crashed-child hang is now disclosed and tracked (An authored spawner never hears an unsolicited child exit: stopped is only ever the answer to its own stop effect #9227); nothing else silent.
• Type design (out of scope, not filed, nit carried from round 1): child + startedAt as two nullables that move together; a single running: {child, startedAt} | null would make the half-set state unrepresentable.
• Test gap: none in scope beyond what An authored spawner never hears an unsolicited child exit: stopped is only ever the answer to its own stop effect #9227 owns.

Deviations

Disclosed	Substance	Matched against findings
:cron run refuses for a graph-launched cron	#8944, documented, not worked around	Row 5; PASS
attached-desk.unit.test.tsx › closes on Escape red on base	pre-existing on bc890986	Not cron's; CI-at-head green is the gate's answer
stopped branch unreachable for an unsolicited child exit	#9227, cell kept and honestly named	Row 2; PASS
Stopped children accumulate in the manifest	#9220	Out of this diff

deviation-disclosure: PASS — nothing undisclosed that this gate could see.

CI at head

settle settled · ci 268e017a green — 45 check runs, 39 success, 6 skipped; 28 of 40 repo-authored workflows ran at head.

Verdict

PASS. Both round-1 FAIL rows (2, 6a) are repaired on this head; no new finding routes to an acceptance criterion.

Verdict-written: 2026-09-15T10:55:59Z

[cansirin]

routed-elsewhere: review-ui @ 268e017 — cron program row + flag default; no rendered surface, component, or style changes

LAW-SOURCE: manifest-prose (ui law exit 13 — untyped registry).

Seven files change, all under apps/tuval; the ui class fired off the apps/tuval/src/ prefix test alone.

• apps/tuval/src/cron/cron.ts (new): a process program — timer tick, spawn a job program, record the run. Imports are @demlik/tea, effect, authoring/ports/process modules; no JSX, no stylesheet, no page. Its only UI contact is the title/label strings it hands the existing board-tile chrome, which this PR does not modify.
• apps/tuval/src/features.ts: adds the cron: boolean flag, default false.
• apps/tuval/.tuval/tuval.config.ts: registers the row and flips the flag on for this repo's own desk.
• apps/tuval/src/page/dev-server.unit.test.ts: the generated features-module string grows one key.
• boot.unit.test.ts, config.unit.test.ts, cron.unit.test.ts: tests.

No composition, page, screen, state or style a user sees is added or changed; the existing tile paints one more row of the shape it already paints. Tuval is a local app (no alchemy.run.ts), so there is also no preview deployment to capture. Text judgment belongs to review, which stands PASS at this head.