/hermit-routines

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

Routines

Register and manage scheduled routines. Where the Monitor tool is available, all enabled routines except `hermitd:heartbeat-restart` run from ONE native plugin monitor that decides eligibility outside the session — a skipped fire costs zero model tokens. `hermitd: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

/hermitd:hermit-routines load              register/reconcile: monitor mode if available, else CronCreate diff-register
/hermitd:hermit-routines load --reset      unconditional reset: tear down + recreate everything
/hermitd:hermit-routines run <ids>          [internal] ROUTINE_DUE handler — invoked by the monitor's notification
/hermitd:hermit-routines list               list configured routines from config.json
/hermitd:hermit-routines status              show monitor/anchor state (or CronCreate registrations in fallback mode)
/hermitd:hermit-routines stop [id]           stop the monitor (or a specific fallback-mode CronCreate)
/hermitd: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 `hermitd-start.ts` on always-on launches. Can also be called manually to apply config changes mid-session.

1. Use the harness-substituted `${CLAUDE_PLUGIN_ROOT}` paths below. Copy absolute commands into any CronCreate-delivered prompt at registration; the plugin root is NOT a Bash env var at runtime.

**Validate the plugin scripts before proceeding.** Run `test -f "${CLAUDE_PLUGIN_ROOT}/scripts/routines.ts"` (the `arm`/`precheck`/`finish` verbs all live in it) and `test -f "${CLAUDE_PLUGIN_ROOT}/scripts/routine-monitor.sh"`. If either fails, abort `load` immediately (do not register/delete anything) and log one line: `Routine load aborted: plugin scripts not found at "${CLAUDE_PLUGIN_ROOT}". No routines registered or reset.` 2. **Ask what needs arming:**

   bun ${CLAUDE_PLUGIN_ROOT}/scripts/routines.ts arm begin .hermit ${CLAUDE_PLUGIN_ROOT} --session-id "${CLAUDE_SESSION_ID}"

It reads config, the runtime mirror and both liveness files, and prints the whole plan as one JSON object. Append ` --reset` for `load --reset` (below). Branch on `status`:

• **`healthy`**: 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`**: log the line and stop.
• **`restart_required`**: report that the resident must be restarted to pick up the new plugin path. Stop without arming anything.
• **`arm`**: execute the plan in step 3. Optional keys appear only when they apply.
• An **`error`** (`check_error:<reason>`, exit 1) means the verb could not read `config.json` or the mirror, so it planned nothing. Abort `load`: register or delete nothing, and log `Routine load aborted: arm check failed: <reason>. No routines registered.`

3. **Execute the `arm` plan.** Fetch `select:CronCreate,CronList,CronDelete` in one `ToolSearch`. Then:

• `heartbeat` (`interval`, `first_start`): the heartbeat leg needs registration; pass `--heartbeat native` at commit. Without it the leg is current or disabled; pass `--heartbeat none`.
• `first_transition`: `CronList`, then delete every non-anchor `[hermit-routine:*]` entry before replacing them with the native poller.
• `monitor_skip`: no routine registration is needed; pass `none` as its commit argument.
• `activate`: invoke that 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` through the **CronCreate flow** below.

4. **Commit:**

   bun ${CLAUDE_PLUGIN_ROOT}/scripts/routines.ts arm commit .hermit ${CLAUDE_PLUGIN_ROOT} <native|none> --created "<succeeded-csv>" --heartbeat <native|none>

Use `native` for the routine leg unless `monitor_skip` was set. 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.

• `armed` (`scheduled`, `anchor`): log it.
• `fallback` (`liveness_absent`): go to Step 3-F. This also covers hosts that skip native monitors because the Monitor tool is unavailable.
• `heartbeat`: the independent heartbeat result. Log `registered`; for `dead`, report that the heartbeat will not run this session.

5. **Step 3-F, fallback** (only after `fallback`): run

   bun ${CLAUDE_PLUGIN_ROOT}/scripts/routines.ts arm begin .hermit ${CLAUDE_PLUGIN_ROOT} --fallback --session-id "${CLAUDE_SESSION_ID}"

This re-plans over the full enabled set without activation or a heartbeat leg. Execute its `delete`/`create` through the **CronCreate flow** below, then commit with `arm commit .hermit ${CLAUDE_PLUGIN_ROOT} fallback --created "<succeeded-csv>" --heartbeat none`.

**CronCreate flow** (executes the `delete`/`create` lists from any `arm begin` plan: monitor-mode anchor, fallback, or `--reset`). Report each `warnings` entry's `message` as a scheduler warning, including when all registrations are kept.