/hermit-routines

name: hermit-routines
description: Schedules routines via one native plugin monitor (zero-token skips); CronCreate fallback where Monitor is unavailable. heartbeat-restart stays a CronCreate re-arm anchor.

Routines

Register and manage scheduled routines. Where the Monitor tool is available, all enabled routines except `heartbeat-restart` run from ONE native plugin monitor that decides eligibility outside the session — a skipped fire costs zero model tokens. `heartbeat-restart` stays a CronCreate **re-arm anchor**: its skill IS `load`, so its daily fire re-arms the monitor and the anchor CronCreate — and, unless `heartbeat.enabled` is explicitly false, restores the heartbeat monitor too. The watchdog re-arms a monitor whose liveness has gone stale as a second net, on a resting session too. Where Monitor is unavailable (Bedrock/Google Cloud Agent Platform/Foundry, `DISABLE_TELEMETRY`/`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`), `load` falls back to per-routine CronCreates.

Usage

/claude-code-hermit:hermit-routines load              register/reconcile: monitor mode if available, else CronCreate diff-register
/claude-code-hermit:hermit-routines load --reset      unconditional reset: tear down + recreate everything
/claude-code-hermit:hermit-routines run <ids>          [internal] ROUTINE_DUE handler — invoked by the monitor's notification
/claude-code-hermit:hermit-routines list               list configured routines from config.json
/claude-code-hermit:hermit-routines status              show monitor/anchor state (or CronCreate registrations in fallback mode)
/claude-code-hermit:hermit-routines stop [id]           stop the monitor (or a specific fallback-mode CronCreate)
/claude-code-hermit:hermit-routines stop --all          stop everything

`list`, `status`, `stop` and the notes live in `reference.md`, beside this file in the skill's **Base directory** — `Read` it for those. `load` and `run` stay here: every always-on launch pays for them.

Plan

load

Called automatically by `hermit-start.ts` on always-on launches. Can also be called manually to apply config changes mid-session.

1. Resolve the plugin root path: derive it from this skill's **Base directory**, which the harness injects into the invocation context as `<plugin_root>/skills/hermit-routines`. Strip the trailing `/skills/hermit-routines` to get `pluginRoot`. This works in both installed and `--plugin-dir` modes. (`$CLAUDE_PLUGIN_ROOT` is NOT a Bash env var at runtime — evaluating it in Bash always returns empty. The braced `${CLAUDE_PLUGIN_ROOT}` form is text-substituted in skill markdown only in installed mode. Neither is reliable here — always use the Base-directory derivation.) The resolved `pluginRoot` must be baked into any CronCreate-delivered prompt at registration — it is not available inside either subprocess or cron-delivered prompts.

**Validate `pluginRoot` before proceeding.** If `pluginRoot` is empty, or either of `<pluginRoot>/scripts/routines.ts` (the `log-event`/`precheck`/`cron-registry` verbs all live in it) or `<pluginRoot>/scripts/routine-monitor.sh` does not exist (`test -f` on each path), abort `load` immediately — do not register/delete anything — and log one line: `Routine load aborted: plugin scripts not found at "<pluginRoot>". No routines registered or reset.` 2. **Ask what needs arming:**

   bun <pluginRoot>/scripts/routines.ts arm begin .claude-code-hermit <pluginRoot> --session-id "${CLAUDE_SESSION_ID}"

It reads config, the runtime mirror and both liveness files, and returns the whole plan. Append ` --reset` for `load --reset` (below). Its first line decides the branch:

• **`HEALTHY|routines=<mode:n>|anchor_age=<d.d>d|heartbeat=<ok|disabled>`** — the monitor is registered, ticking, and current; the anchor and heartbeat legs are too. **Log that one line and stop.** Re-arming a healthy monitor is pure spend.
• **`GUEST|native-monitors-resident-only`**: log the line and stop.
• **`RESTART_REQUIRED|<reason>`**: report that the resident must be restarted to pick up the new plugin path. Stop without arming anything.
• **`ARM|<legs>|<reasons>`** — execute the plan block that follows, in order. Every subsequent line is optional and appears only when it applies.
• **`ARM|routines,heartbeat|check-error:<reason>`** — the verb could not read `config.json` or the mirror, so it emitted no plan. Abort `load`: register or delete nothing, and log `Routine load aborted: arm check failed — <reason>. No routines registered.`

3. **Execute the `ARM` plan block.** Fetch `select:CronCreate,CronList,CronDelete` in one `ToolSearch`. Follow the printed lines:

• `HB_FIRST_START:1` / `HB_INTERVAL:<s>`: the heartbeat leg needs registration; pass `--heartbeat native` at commit. No `HB_` lines means it is current or disabled; pass `--heartbeat none`.
• `FIRST_TRANSITION:1`: `CronList`, then delete every non-anchor `[hermit-routine:*]` entry before replacing them with the native poller.
• `MONITOR_SKIP:zero-scheduled`: no routine registration is needed; pass `none` as its commit argument.
• `ACTIVATE:/claude-code-hermit:monitor-activate`: invoke the named skill once via the `Skill` tool, even when both legs need registration. The host starts the two resident-guarded supervisors on dispatch.
• Execute `DELETE:` / `CREATE:` lines through the **CronCreate flow** below. Preserve `ANCHOR_PROMPT_BEGIN` through `ANCHOR_PROMPT_END` as the anchor prompt.

4. **Commit:**

   bun <pluginRoot>/scripts/routines.ts arm commit .claude-code-hermit <pluginRoot> <native|none> --created "<succeeded-csv>" --heartbeat <native|none>

Use `native` for the routine leg unless `MONITOR_SKIP` was printed. Append ` --reset` when `begin` got it. The verb accepts a live supervisor PID or waits up to 10 seconds for liveness, then writes runtime and the registry mirror.

• `OK|monitor|<n> scheduled|anchor <created|kept>`: log it.
• `FALLBACK|liveness-absent`: g