fulcra-agent-automation

Fulcra Agent Automation

BUS V3 (2026-07-27, operator-ordered): the listener half of this skill is RETIRED. Agents read their event queue on every wake — one bounded get-records query (docs/coord/BUS-V3.md) — and run no resident listener. Do not install new listeners (§2) or listener-tick automation; hosts still running one should stand it down. The heartbeat (§1: scheduled reconcile + projection + digest) and the wake-on-schedule adapters (§3, repurposed to trigger a queue-reading wake rather than a listen tick) remain current. The listen verb itself was REMOVED from the engine on 2026-08-03 (PR #523); invoking it is now an argparse error.

Ties the coord skills together for unattended operation. fulcra-agent-reconcile heals a team's index/views, but someone has to run it; this skill schedules it, and makes wake-ups (cron/heartbeat) resume structured continuity first. Scheduling is a single, platform-specific action (not a fold), so this skill is prose + one bundled install script — no engine logic.

Require consent: always ask the user before creating any scheduled job or background automation.

Where to start — the re-entrancy probes

Before installing anything, probe what this host already runs. Enter at the first probe that fails (per the repo's skill-quality pattern, docs/skill-quality-pattern.md):

All probes pass → nothing to install; re-running any installer is safe anyway (reinstall replaces the job, never duplicates — CI-tested for the heartbeat's launchd and cron paths; the listener installer and its test suite were removed with the retired stack). Re-running after this upgrade also MIGRATES any coord2-era artifacts (old fulcra-coord2-hooks/ dir, coord2-watch-<agent> automation, coord2 watch hooks marker, fulcra-coord2:begin fence) to the new names in place — old artifacts removed, zero orphans (host-simulation-tested in packages/coord-engine/tests/test_adapter_installers.py).

1. Heartbeat — keep the views healed

Schedule coord-engine reconcile <team> on a timer so the index/aggregate never drift, even when no agent is actively working.

Bundled installer (macOS launchd / Linux cron):

# every 20 minutes (default); creates a LaunchAgent on macOS or a crontab line on Linux
./scripts/install-heartbeat.sh <team> [interval-minutes]
./scripts/install-heartbeat.sh --uninstall <team>

It runs coord-engine reconcile <team>; needs coord-engine + an authenticated fulcra-api on PATH.

OpenClaw / other runtimes: add a line to your HEARTBEAT.md (or a native cron job, per fulcra-agent-teams' automation section) that runs coord-engine reconcile <team> on your chosen cadence. Prefer a longer interval or an external loop over waking the model every tick.

Projection — task transitions onto your Fulcra timeline (model-free)

The heartbeat can project each task transition (create / pickup / update / complete) onto your Fulcra timeline as an Agent-Tasks annotation, mechanically, spending no model tokens — and it annotates transitions made by any agent or harness, not just this host. Reconcile already computes the transitions; projection folds them onto the timeline right after.

Opt in per team (default is off):

coord-engine annotate resolution <team> transitions   # turn projection on for this team
coord-engine annotate resolution <team> off           # turn it back off
coord-engine annotate status <team>                    # resolution level + cursor position

The level is stored on the bus, so every host's heartbeat reads the same setting. With projection on, install-heartbeat.sh runs coord-engine annotate project <team> immediately after each reconcile — it consumes the structured pending.json transitions reconcile just wrote (the log.md bullets can't feed the fold — they carry no task_id/kind/ts), emits one annotation per new transition (deterministic id + cursor, so a re-run or mid-run crash never double-writes), and advances the cursor. Off or absent ⇒ the step no-ops. The heartbeat chain then finishes with coord-engine digest <team> --store --emit-timeline, which keeps the operator's twice-daily digest alive on both surfaces (bus copy + the 'Agent Tasks — Digest' timeline track) — see the health skill for its semantics.

Multi-host is safe: the typed ingest endpoint upserts on an explicit record id (live-verified 2026-07-14 — a same-id re-POST returns 201 and the record count stays 1), and every projected annotation carries a deterministic id, so two hosts racing reconcile && annotate project in the same window converge on the same records instead of duplicating them. The cursor still matters — it is what keeps quiet ticks cheap (no re-POSTs) — but it is an efficiency guard, not the only thing between you and duplicates. Run projection from every heartbeat host.

resolution is a level axis, not a boolean: {off, transitions} are live today; finer levels (tool calls, I/O, …) are additive later without a config-shape change. Any other value is rejected.

Projection is the successor to the in-process fulcra-coord annotations writer. Both emit Agent-Tasks moments for the same transition to a no-dedup endpoint, so running both double-writes the timeline. Enabling projection therefore requires the legacy annotations writer stay off — which the standing rule (AGENTS.md → Fulcra platform surface) already mandates on every host. Projection is the sanctioned replacement; do not switch the legacy writer back on to get timeline annotations — turn projection on instead.

2. Awaiting replies — the reply leg is the queue read (listener REMOVED)

There is no listener. Replies to an ask (tell/broadcast/remind/review request) arrive as bus v3 events; you await them by reading your event queue on your next scheduled wake:

coord-engine queue <team> --agent <you>

The send verbs print exactly that as their breadcrumb — tell/broadcast echo replies: coord-engine queue <team> --agent <you> and review request echoes await verdicts: coord-engine queue <team> --agent <me>.

The coord-engine listen verb — the resident diff/notify watcher this section used to document (inbox/response/verdict id-diffing, LISTEN DEGRADED streaks, the head/tail budgets) — was retired as the wake surface on 2026-07-27 and removed from the engine entirely on 2026-08-03 (PR #523): running it is an argparse usage error, its env knobs (COORD_LISTEN_*, COORD_LISTENER_STATE) are gone, and its durable listen-state.json shards are historical residue (see the takeover note in GET-ON-THE-BUS §5). The mechanics live in git history, not here.

A scheduled wake must never die on degradation (the doctrine outlives the watcher): a degraded queue read or fold backs off and re-fires on the next tick; only affirmative delivery ends the wait. Degradation is never interpreted as a clean queue, and never as permission to stop waking.

The load-bearing wake read is the bus v3 queue read (coord-engine queue <team> --agent <you>), with briefing as the durable-state fold you run after it. When a scheduled tick's queue/briefing/inbox degrades, quiet is NOT clear — apply the raw-bus fallback in §3 (Degraded briefing → fail-closed raw-bus fallback): raw-list + direct-read the unacked directives before reporting, never conclude "no work" off a degraded read.

Per-platform — pick the leg that matches how the agent runs

• launchd / cron (unattended host): REMOVED with the retired stack (cleanup slice 1, 2026-07-28) — do not install; stand down any survivor per the probe table. The bundled installer's scheduled tick, notification/consent-gated wake chain, adaptive due-time gate, and COORD_LISTENER_* advisory env fields all went with it (git history has the details). What replaces it on an unattended host is a plain scheduled wake (launchd/cron) running the queue read — see docs/coord/GET-ON-THE-BUS.md §6 for the crontab recipe, and keep the heartbeat (§1) for reconcile.
• Every platform (Claude Code live, Codex, headless): the queue read. These platforms once ran resident listen variants; the verb no longer exists. The pickup on every platform is the bus v3 queue delivery (coord-engine queue <team> --agent <agent>) on the wake the platform already has (automation tick, scheduled job, session start). Under cursor v2, the harness must leave the token uncommitted while the agent works and run queue commit only after every event in the staged batch has a durable terminal classification, supplied as one --result <record-id>=<outcome> per event. A harness consuming queue --json parses the single stdout object and switches on type: queue-result (state DATA|CLEAR) is the whole success surface, and every nonzero exit yields one queue-error that must be reported with its state and error_code verbatim — the states are not interchangeable: INVALID (*-invalid, event-id-missing) is corrupt human-fixable data that no retry will clear (surface it to the operator; never delete or recreate the named file to "unstick" the read); UNKNOWN (*-read-failed, window-unknown, consume-audit-failed, stage-race-unverified) is a transport doubt that backoff-and-retry handles; INCOMPATIBLE (engine-incompatible, cas-unsupported, authority-not-v2) means upgrade or reconfigure, not retry; ABSENT (config-absent) means the bus is not set up; REFUSED (usage, results-incomplete, stale-token) means the invocation itself was wrong.

For push-capable harnesses and the fleet security contract, see docs/coord/EVENT-DRIVEN-WAKE.md. The bundled wake/openclaw.sh and wake/codex.sh adapters were removed with the listener stack (cleanup slice 1). Directed wakes via the optional wake router are shipped but unproven in deployment (the reference deployment was evaluated and retired, 2026-08 — see BUS-V3.md "Latency, and the router"); scheduled wakes + queue reads are the standing pattern. Where a router IS deployed, its adapters are host-local ($COORD_WAKE_ADAPTER_DIR/<adapter>.sh, registered per agent in _coord/router/config.json), and wake/macos-notify.sh remains in-repo as an adapter example.

Single-flight remains an efficiency rule, not a correctness assumption. The listener-era cursor could lose work when two same-agent wakes overlapped. Cursor v2 CAS-stages one pending batch: a losing wake reloads and replays the winner, stale commit tokens cannot advance coverage, and successful commit retries are idempotent. Still keep one scheduled wake per agent identity and coalesce overlaps—the second wake adds cost and may duplicate processing even though it cannot corrupt coverage.

3. Harness adapters — lifecycle wiring

Bus v3 queue reads (on each wake) deliver events, but the lifecycle contract — resume-on-wake, snapshot-on-change, park-before-context-loss — is owned by a per-harness adapter that hooks the platform's own session events. The contract itself (rules 1–4) lives in fulcra-agent-continuity §The lifecycle contract; the adapters below automate it. Each keys everything on a distinct coord marker. Retired first-generation entries are left inert unless an installer's documented migration path explicitly recognizes them. All installers are idempotent (reinstall replaces, never duplicates) and ship an --uninstall inverse.

Tick doctrine (shared by every adapter). Every adapter keys off the same canonical, queue-led tick — though claude-code's hook renders only the first steps (continuity resume + briefing) as session context, leaving the queue read and the verdict-before-ack duty steps to the waking agent: continuity resume → queue (READ your events, process them, and — under cursor v2 — queue commit the staged token only after every event has a durable terminal classification; this is the wake surface, not briefing) → briefing (the durable-state fold — identity, role inboxes, needs-me incl. pending reviews; it is what the events do NOT cover, never a substitute for the queue read) → for each review request, slug-exact verdict-before-ack (write the verdict file, verify review status clears you from pending_required, only then ack — never ack bare or against a different slug) → handle other work → continuity snapshot → usage log (ATC, when accounts are declared) → continuity park before session end → report last: the human-visible summary is the tick's final output, composed after every command above. Text followed by more tool activity may never render — "sent" is not "delivered" — so anything that MUST reach a recipient (human or agent) goes on the bus as a durable artifact (ask, review doc, snapshot), never only in session text. PR/forge feedback arrives via briefing (forge mirror sweeps all three GitHub surfaces) — never hand-roll gh polls in a watch prompt. These hooks/prompts/blocks are rendered artifacts, not live references: after upgrading fulcra-tools, RE-RUN YOUR ADAPTER INSTALLER to regenerate them — an un-regenerated hook keeps emitting the doctrine it was rendered under.

Degraded briefing → fail-closed raw-bus fallback (doctrine, not optional). A wake read that degrades is absence of a complete answer, never proof of "all clear" — and the fallback covers every degraded section, not just reviews. A watcher that acts only on what a clean-looking fold returned can silently drop a live unacked directive.

• Directives / inbox — the general case. Every aggregate-backed read (briefing, inbox, needs-me, status, board, search) folds the summaries index through the public-read failure contract (AGENTS.md → The public-read failure contract): when the index/listing is UNKNOWN it emits the shared read-degraded marker (or inbox's named inbox-degraded type) — carried in the --json result and as a stderr notice — instead of a clean-empty. On ANY such marker (or a briefing that reports a failed resume / stalled section), the watcher MUST NOT conclude "no work": it raw-lists and direct-reads the unacked directives — enumerate team/<team>/task/ (fulcra-api file list), read each intent:/assignee-shaped doc naming this agent or a role it holds, and act on anything open-and-unacked. Only report a genuinely clear inbox when a non-degraded read returns empty; a degraded read is reported degraded, never "no directives."
• Reviews — the specific case. The briefing/needs-me pending-review fold is projection-first: it serves the reconcile-built reviews section of _coord/summaries.json when that section is fresh, and discloses which source it used in a trailing review-source row — review fold: projection (as of T) or review fold: raw scan — <reason> (stale / incomplete / malformed / unrecognized). A raw-scan row is a loud fallback, never a silent one; read it as "a reconcile is behind", not as an error in your own obligations. The caller's OWN head slugs are raw-tallied on every call either way. The raw scan is wall-clock bounded (COORD_REVIEW_FOLD_BUDGET, default 45s): on a slow transport it stops early and emits a review-fold-degraded row ({scanned, total}, plus skipped when a slug's doc or verdict read failed) rather than a clean-looking partial. On that row, fall back to a per-slug review status sweep over the review/ listing for the unscanned and skipped remainder, and clear those verdicts before acking. Full contract: docs/coord/BUS-V3.md → "Where a fold's answer came from".

Codex's repaired watch prompt already does the review sweep; the directive raw-bus fallback is the same discipline for the inbox side — the installer-generated watcher (§2) and every adapter tick (below) run the composite engine path (briefing first) and honor both markers before reporting.

Claude Code / Cowork — settings.json hooks.

./scripts/claude-code/install-claude-code.sh <team> <agent>
./scripts/claude-code/install-claude-code.sh --uninstall <team> <agent>

Writes three scripts to ~/.claude/fulcra-agent-hooks/ and merges their command paths into ~/.claude/settings.json: SessionStart → bounded continuity resume + inbox brief injected as context; PreCompact and SessionEnd → backgrounded continuity park. It touches only its own command paths; a coord2-era fulcra-coord2-hooks install is migrated to the new dir in place. Pre-coord first-generation hooks are not managed by this installer and should be removed separately. Cowork uses the same core and the same settings.json, so the same installer covers it.

The SessionStart hook also consumes exact-identity queued wake nudges from ${COORD_WAKE_DIR:-${XDG_STATE_HOME:-~/.local/state}/coord-engine/wakes} before the briefing. These files are written atomically and keyed by the router idempotency key; duplicate delivery self-overwrites, consumption happens once, and no event body or encoded command enters model context. Malformed files remain in place and surface a degraded marker instead of being silently discarded.

Codex — hooks.json merge + app-thread automation.

python3 scripts/codex/install_codex_watch.py <team> <agent> [--codex-dir DIR] [--thread-id ID] [--interval-minutes N] [--uninstall] [--dry-run]

Merges SessionStart (matcher startup|resume|clear|compact) + PreCompact entries into ~/.codex/hooks.json — same entry shape as Claude Code — and seeds a coord-first app-thread automation under ~/.codex/automations/coord-watch-<agent>/ whose prompt embeds contract rules 1–3 and ticks the inbox. The default safety-net cadence is 30 minutes (override with --interval-minutes), replacing the old 5-minute model-backed poll. For event-driven wake, register its exact thread id with the wake router (host-local codex-exec-resume adapter in _coord/router/config.json). The adapter uses the stable codex exec resume <SESSION_ID> interface, never passes --dangerously-bypass-approvals-and-sandbox, and never places raw bus event text in the prompt; the resumed agent fetches authoritative briefing state. Deployment precondition: on the first real host, verify the SessionStart hook actually fires before relying on hook-based automation seeding — pass --thread-id for the deterministic path if you already know the watch thread.

Codex SessionStart consumes the same queued-wake directory and exact-identity format as Claude Code. The host executor invokes coord-engine wake queue-file <team> --agent <id> --key <idempotency-key>; the hook invokes coord-engine wake consume <team> --agent <id>. Both commands are model-free.

OpenClaw — managed prose block.

python3 scripts/openclaw/install_openclaw.py <team> <agent> [--workspace DIR] [--uninstall] [--dry-run]

Merges a fulcra-agent-fenced block (<!-- fulcra-agent:begin … --> / <!-- fulcra-agent:end -->) into the workspace's HEARTBEAT.md and BOOT.md, embedding contract rules 1–2 for OpenClaw to read at boot and on each heartbeat tick. The managed blocks are intentionally compact because OpenClaw reads them repeatedly; detailed doctrine stays in this skill. Rule 3 (park on shutdown) is not automated — the prose-block layer has no shutdown hook to fire it, so it must be followed as prose. This is the prose-block layer only — no hooks-dir machinery. It validates marker balance before any write and refuses (exit 1) on unbalanced or crossed markers rather than risk destroying user content between an orphan marker and an appended one.

Hermes (Daytona sandbox) — provisioned out of band: the fhd provisioner that installs the Claude Code adapter inside the sandbox lives in the standalone hermes-daytona repo (extracted from this monorepo) and is tracked there, not here.

Claude web / Cowork-cloud tier (best-effort): cloud sessions have no persistent filesystem or scheduler on your machine. Follow the lifecycle contract as prose (fulcra-agent-continuity §contract), and use the platform's scheduled routines to open a periodic duty-cycle session that runs steps 1–2 of the contract. There is no durable background pickup on this tier; anything that must not wait for a routine belongs with an agent on a host tier.

The router's routine-align adapter does not wake or create a cloud session. It writes one idempotency-keyed standard delivery record under team/<team>/_coord/router/delivered/, extended with mode: self-armed-routine, eligible_at, and no_session_created: true. For this lane, “delivered” means alignment-recorded: queued work has been aligned to the agent's already-existing Routine, and the Routine's normal SessionStart/briefing reads the authoritative bus. Treating this marker as an exact-session wake is a contract violation.

4. Resume on wake — structured, not a prose re-read

When a cron/heartbeat wakes an agent to do team work, the wake payload should resume continuity first (this is the structured version of fulcra-agent-teams' "read progress.md before acting" rule):

coord-engine continuity resume <team> <agent>
coord-engine queue <team> --agent <agent>      # the wake surface: read + process + commit

Then process the team inbox and, before concluding, snapshot again (coord-engine continuity snapshot …) and let the next reconcile heal the views.

5. Recommended loop for a team

1. Heartbeat: install-heartbeat.sh <team> — reconcile every ~20m (consent first).
2. On wake: continuity resume → queue (read/process/commit) → do work (task …, inbox) → continuity snapshot → reconcile.
3. Gate merges with fulcra-agent-review (review status), and keep roles fresh with fulcra-agent-roles (roles status), escalating vacancies.

That's the full coord stack running unattended on top of a fulcra-agent-teams space.

See the bundled scripts/install-heartbeat.sh.