Signals reference

The harn signals command, its hook adapter, the inbox file, and its configuration. For the design, see Ambient signals. For setup, see Deliver signals to Claude Code and Codex.

Commands#

Every command accepts --dir <DIR> to use an inbox other than the default. Commands that print data accept --json and emit the standard JSON envelope with schemaVersion: 1.

Firing#

fire and resolve print the transition: fired (generation N) for a state change, or unchanged when the signal was already in that state. A change owes one reminder; an unchanged result owes none.

Hook adapter#

harn signals hook --format claude-code|codex --event EVENT [--role ROLE] [--rewake] [--max-wait DURATION]

The hook reads the harness's JSON payload on stdin and uses its session_id, cwd, and, from Claude Code, session_title. The repository is the origin remote of the Git repository containing cwd. The role comes from --role, else HARN_EXT_SIGNALS_ROLE.

Every invocation except SessionEnd and Stop --rewake leases at most three reminders, prints them, and after flushing its output acks exactly those leases by token. A hook killed before that leaves its leases to lapse and be leased again; a hook running beside it never acks them.

When more reminders are routed to the session than one hook leases, the output ends with how many follow. With nothing to deliver, the hook prints nothing (Codex Stop: {}) and exits 0. A hook that fails prints harn signals hook: <reason> on stderr and exits 1, which both harnesses treat as a non-blocking hook error. It never exits 2 on failure.

Files#

The inbox directory is $HARN_EXT_SIGNALS_DIR when set, else ~/.harn/signals. It is created with mode 0700, and its files with 0600.

inbox.json#

{
  "schema": "harn.signals.inbox.v1",
  "signals": {
    "<key>": {
      "key": "<key>",
      "state": "fired | resolved | expired",
      "generation": 1,
      "severity": "info | warning | urgent",
      "event": {"schema": "harn.triage_event.v1", "...": "..."},
      "routing": {"repo": "owner/name", "cwd": "/path", "topic": "..."},
      "provenance": {"producer": "std/signals.monitor_github_ci", "signature": "verified | unverified | local"},
      "fired_at": "RFC 3339",
      "changed_at": "RFC 3339",
      "expires_at": "RFC 3339 or null",
      "delivery": {
        "generation": 1,
        "session_id": "...",
        "assigned_at": "RFC 3339",
        "lease": {"token": "...", "leased_at": "RFC 3339", "expires_at": "RFC 3339"},
        "acked_at": "RFC 3339 or null"
      },
      "attempts": 1,
      "fired_recipient": "session id leased the latest fired generation"
    }
  },
  "sessions": {
    "<id>": {
      "id": "<id>",
      "harness": "claude-code | codex | <other>",
      "cwd": "/path",
      "repo": "owner/name",
      "title": "...",
      "role": "control",
      "activity": "busy | idle",
      "registered_at": "RFC 3339",
      "last_seen": "RFC 3339"
    }
  }
}

The inbox stores the event's normalized fields only. It replaces raw_payload with {} and sets privacy.raw_payload_retained to false.

A document with any other schema is refused rather than migrated.

config.toml#

The inbox is the only owner of this policy. A held signal stays in the inbox unrouted and routes once the policy allows it. Unknown keys are refused.

Environment#

Rust API#

Hosts embed the inbox in-process through the harn-signals crate: Inbox::open, Inbox::register_session, Inbox::check_in, Inbox::ack_leases, Inbox::ack, Inbox::end_session, Inbox::fire, Inbox::resolve, Inbox::poll_idle, Inbox::claim_watcher, and Inbox::snapshot. A consumer acks each leased reminder with Inbox::ack_leases and its lease_token once the reminder reached the model. harn_signals::display_safe is the character filter for showing signal text anywhere. Replace the routing rules with Inbox::with_router and any Router implementation; the policy in config.toml applies before the router runs. harn_vm::stdlib::signals::render_reminders renders reminders into the text the hook adapter prints. Deliver it as a system reminder, never as a user message.

Harn API#

std/signals is the producer surface for Harn scripts and trigger handlers.

GitHub monitor options:

monitor_github_runners lists the organization runner group in pool.group when set, or else the repository's or organization's runners, reading every page. A listing stops at total_count, or at a short page when the response has none. A page without the runners field, a listing that ends short of its total_count, or one past 5,000 runners is unmeasured rather than counted short.

monitor_github_ci lists the repository's active workflows and reads each one's 20 most recent completed push runs on the branch, one request per workflow, so a busy workflow cannot push another's runs out of a shared page. The newest decisive run of each workflow is its reading. A branch where no workflow has a decisive recent run, or a response without workflow_runs, is unmeasured rather than recovered. monitor_github_open_prs is unmeasured when the search reports incomplete_results.

The runtime builtins are the session lifecycle and the producer calls underneath signal_apply:

request takes event (a normalized harn.triage_event.v1), key, severity, routing, provenance ({producer, signature}, default a local script), expires_in_seconds, and dir; unknown fields are refused. Timestamps come from the VM clock, so a mocked clock moves signal lifecycles too.

examples/triggers/ambient-signals wires the monitors to a five-minute cron trigger and the alert normalizers to webhook triggers.