docs: scheduled jobs are hex workers, not LaunchAgents#16
Merged
Conversation
The AGENTS.md 'Automation' section instructed agents to write a launchd plist for new scheduled jobs — stale guidance that contradicts the no-LaunchAgents decision (persistent-processes-via-iii-exec-not-launchagents-2026-06-11) and caused a launchd reminder to be (wrongly) created for the reading-digest system. Rewrite the guidance to match the code: - Scheduled/recurring jobs = typed-Rust hex workers in the foundation registry (hex_modules::module_registry(), Worker::new().on_cron_named); authoring one is a foundation change, not a config edit. - Persistent processes ride the engine via iii-exec in the instance .hex/iii/engine-workers.yaml (which hosts daemons/factories, NOT cron jobs). - New per-job LaunchAgents are forbidden; the one sanctioned LaunchAgent is the harness bootstrap (com.hex.harness) that hosts the engine. Also: capability-table row, a hex-ops.md note clarifying its LaunchAgents section is the sanctioned-services exception (not a pattern to copy), and a code-intel.md forward-note (new daemons → iii-exec). Existing prohibitions (no runtime cron primitives / polling / sleep loops) preserved. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The worker section documented a 'hex worker run <config>' CLI and a
{worker_name, jobs:[{command, cron}]} YAML host. Neither exists: there is no
'hex worker' subcommand (verified vs the binary and develop main.rs), no
iii_worker.rs, and no worker_name parsing anywhere in the harness. The doc even
hedged 'verify once shipped' — it was written ahead of code and never reconciled.
Correct it to the real, code-verified model: workers are typed Rust (Worker::new
().on_cron_named/.on_event) registered in hex_modules::module_registry() and run
by 'hex harness serve'; lifecycle is 'hex module list|status|enable|disable'.
This is the doc the AGENTS.md Automation rule points to, so the citation is now
accurate instead of pointing at a nonexistent CLI.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
mrap
added a commit
that referenced
this pull request
Jun 13, 2026
…rker/LaunchAgent (PR #16) PR #16 (3659a06, 'scheduled jobs are hex workers, not LaunchAgents') deliberately removed the lowercase 'launchd' wording from AGENTS.md's Automation section (now 'hex workers' + 'LaunchAgents'), but test-agents-md-complete.sh still asserted grep -i 'launchd' — a stale check on deliberately-deleted content that blocked the release battery's codex-parity gate. Updated the assertion to 'hex worker\|LaunchAgent' (present in both AGENTS.md and CLAUDE.md → parity holds). Verified: 16/16 pass. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
mrap
added a commit
that referenced
this pull request
Jun 13, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The AGENTS.md Automation section instructed agents to "write a launchd plist" for new scheduled jobs. That guidance is stale — it contradicts the no-LaunchAgents decision (
persistent-processes-via-iii-exec-not-launchagents-2026-06-11) and directly caused a launchd LaunchAgent to be wrongly created for a new reading-digest reminder this session. Doc drift → wrong action. This fixes the guidance at the source.What
Rewrite the scheduling guidance to match the code (verified against
system/harness/src/worker/,workers/mod.rs,worker/runtime.rs):hex_modules::module_registry(),Worker::new().on_cron_named(...)), run in-process by the harness engine. Authoring one is a foundation change, not a config edit.iii-execentry in the instance.hex/iii/engine-workers.yaml— which hosts daemons/factories, not new cron schedules.com.hex.harness) that hosts the engine.Touched:
templates/AGENTS.md+AGENTS.md— Automation section + capability-table row.docs/hex-ops.md— note clarifying its LaunchAgents section documents the sanctioned services, not a pattern to copy.docs/code-intel.md— forward-note: new daemons → iii-exec (scipd documented as the existing exception).Existing prohibitions preserved (no runtime cron primitives, no polling/
sleeploops). Earlier drafts of this fix referenced a non-existenthex worker run <yaml>CLI and claimed the instance file hosts cron jobs — both corrected to match the code before commit.Scope
Docs only. Not touched: the harness/scipd LaunchAgents themselves (legitimate), CHANGELOG history. The instance reading-digest reminder is handled by a calendar-event popup (no launchd, no worker) — there is no instance-level cron mechanism today; a future headless digest generator would be a foundation registry worker.
🤖 Generated with Claude Code