# Scheduling and diagnostics tools

## `scheduling` tool group

Scheduled prompts fan a message body out to one or more agent inboxes
at a future time, optionally recurring. All scheduling ops go through
the operator approval queue (even self-targeted schedules — use
`remind` for unapproved self-wake). Authorization for read/cancel/edit
ops: you can act on schedules you own or any owned by a sub-agent in
your topology subtree.

### `request_schedule_prompt(targets, body, first_fire_at_unix, interval_seconds?, description?)`

Queue an operator-approval for a scheduled prompt. On approve,
`body` is fanned out to each agent in `targets` at
`first_fire_at_unix` (Unix timestamp). Recurring when `interval_seconds`
is set, one-shot otherwise.

Catch-up clamp: if hive-c0re is down across multiple intervals, only
ONE delayed fire happens on resume (per recurring schedule). The
skipped-cycle count surfaces in the per-target `last_result` for
audit.

### `edit_schedule(id, body?, description?, interval_seconds?, next_fire_at_unix?, targets_add?, targets_remove?)`

Partial-update a schedule. Pass only the fields to change; absent
fields are left alone. `targets_add` / `targets_remove` mutate the
recipient list in the same transaction — re-adding a previously
cancelled target drops its tombstone and starts fresh. Clearing
`interval_seconds` to null flips recurring → one-shot. Refuses
cancelled rows (terminal state).

### `cancel_schedule(id, targets?)`

Cancel a schedule. Omit `targets` / pass empty to cancel the whole
schedule; pass a list to cancel just those recipients (the schedule
auto-cancels when every target is removed).

### `fire_schedule_now(id)`

Fire a scheduled prompt out of band immediately. Recurring schedules
keep their cadence — the manual fire is additive. One-shot schedules
are consumed by the manual fire and cancelled afterwards.

### `list_schedules()`

Snapshot every schedule (active + cancelled-but-not-reaped): id,
owner, body, per-target `last_fired_at` + `last_result`,
`next_fire_at_unix`, `interval_seconds`. Use to look up an id before
cancelling, or to audit upcoming wake-ups across the swarm.

## `diagnostics` tool group

### `get_logs(agent, lines?)`

Fetch recent journal lines for a sub-agent container. Useful for
diagnosing MCP-registration failures, startup crashes, plugin install
errors, or any harness issue you can't see from inside the container.

Pass the plain logical agent name (e.g. `"gui"`) — hive-c0re resolves
the machine name (`h-<name>`). `lines` defaults to 50, host-capped at 500.

## `read_host_journal` capability

Capability-gated (not a tool group) — the operator enables it in the
P3RM1SS10NS C4P4B1L1T13S section. Unlike tool groups this is not
configurable from `agent.nix`.

### `get_host_journal(unit?, container?, lines?, priority?, grep?, since?, until?)`

Fetch recent lines from the **host** journal (requires
`read_host_journal` capability). Useful when you need visibility
outside your own container — infrastructure services, hive-c0re
lifecycle events, or another container's boot log.

- `unit` — filter to a systemd unit (e.g. `hive-c0re.service`).
- `container` — nspawn machine name verbatim. Agent containers use
  the `h-<name>` prefix (e.g. `h-iris`); infrastructure containers
  use their full name (e.g. `hive-ci`, `hive-forge`, `hive-matrix`,
  `hive-gateway`). Omit for the host journal.
- `lines` — how many lines to return (default 30, max 100).
- `priority` — minimum syslog level (`emerg` … `debug`).
- `grep` — regex matched against log message fields (`journalctl --grep`).
- `since` / `until` — time bounds (e.g. `-1h`, `2024-01-01 12:00:00`).

## See also

- `remind` (no-approval self-wake path) — documented in
  [`docs/turn-loop.md`](../turn-loop.md).
- [`docs/approvals.md`](../approvals.md) — approval flow for
  `request_schedule_prompt`.