clearotron 0.2.0 → 0.2.2

package/driver/systemd/prelim-driver.service

@@ -1,86 +0,0 @@
-# GENERIC UNIT — safe to sync verbatim on deploy: no deployment-specific values live here; hostnames,
-# credentials and paths all come from EnvironmentFile=%h/.env. (Contrast the TEMPLATE units — profile/
-# recipe/portal-service, remote/client-mcp — whose live copies hold real CF Access values and must be
-# diffed, never overwritten. Both kinds are inventoried in docs/architecture/05-config-governance.md.)
-[Unit]
-Description=Prelim-search deterministic driver — drain the job queue
-Documentation=https://github.com/CordilleraSarl/Clearotron/blob/main/driver/README.md
-# No gateway dependency: compute runs on the standalone engine and delivery defaults to handoff
-# (outbox packets) — see docs/DELIVERY.md. Nothing here needs OpenClaw.
-# Type=oneshot fired by prelim-driver.path: if the runner fails its preflight on every retrigger
-# (exit 3 — no longer reachable since tracker issue 1014 deleted the gateway preflight; kept because the
-# start-limit interaction below is a property of Type=oneshot, not of that preflight), the default
-# start-limit (5 failures in 10s) locks the service out and can drive the .path unit's TriggerLimit
-# (200/2s) into a permanently failed state. Never rate-limit starts (Type=oneshot, no Restart= —
-# nothing here can loop unbounded); the runner also sleeps before its preflight-fail exit so the
-# retrigger cadence stays slow.
-StartLimitIntervalSec=0
-
-[Service]
-# oneshot: systemd guarantees a single instance, so two queue events can't start two concurrent drains.
-Type=oneshot
-EnvironmentFile=%h/.env
-# BOTH ROUTES THE DOCUMENTS PERMIT. INSTALL.md §1 requires "a coding CLI on your PATH, signed in" and
-# deliberately names no install route, so the reader picks one. The npm-global layout was the only one
-# on this line; claude.ai/install.sh -- the route a reader most often takes -- lands the binary in
-# ~/.local/bin, which was not here. The engine then failed `spawn claude ENOENT` and every stage burned
-# its full retry ladder for zero tokens, a failure that reads as a model problem and is not one.
-# CLEAROTRON_CLAUDE_PATH in the EnvironmentFile above is the exact answer for any other location; this
-# line is what makes the two documented layouts work without one.
-Environment=PATH=%h/.local/bin:%h/.npm-global/bin:/usr/local/bin:/usr/bin:/bin
-Environment=OPENCLAW_HOME=%h
-# THIS deployment's configuration is the EnvironmentFile above and nothing else. runner.mjs is one of
-# the CLI entries that reads <repo>/.env for a laptop first run (shared/env-local.mjs); a checkout has
-# no .env today, so this changes nothing — which is the point. It makes "no .env in the checkout" a
-# guarantee instead of a coincidence, so a stray file left by a debugging session cannot quietly
-# reconfigure the queue drain. Same line on trademark-artifacts-http.service, the other unit that
-# starts a wired entry.
-Environment=CLEAROTRON_NO_ENV_FILE=1
-# Deployment hostnames (CLEAROTRON_REPORTS_URL, CLEAROTRON_MCP_URL, CLEAROTRON_CLIENT_MCP_URL, CLEAROTRON_ACCESS_DOMAIN,
-# CLEAROTRON_STAFF_POOL_ROOT) live in the EnvironmentFile above, NOT here — this unit is git-tracked and generic, so a
-# hostname baked in becomes every deployment's hostname. They are non-secret; .env is simply the one place
-# this deployment's config already lives (docs/architecture/04-configuration-reference.md).
-#
-# Do NOT reintroduce a placeholder value for any of them. CLEAROTRON_CLIENT_MCP_URL was pinned here to a
-# example.com host, which is WORSE than leaving it unset: render.mjs's spec 61 §E fail-closed branch omits
-# the client connector when the var is EMPTY, so a placeholder defeated the guard and shipped a dead
-# tokenised link in the client export (2026-07-19). Unset ⇒ omitted; wrong ⇒ delivered.
-# NO WorkingDirectory=, DELIBERATELY, and this is the line not to re-add defensively.
-#
-# systemd does not expand environment variables in WorkingDirectory= -- it takes a path and specifiers
-# only -- so a config-derived checkout cannot go there. It does expand ${VAR} in ExecStart= ARGUMENTS,
-# which is where the path below sits.
-#
-# Dropping it is safe because nothing here reads the working directory: runner.mjs never calls
-# process.cwd(), and driver/driver.config.mjs:24 resolves REPO_ROOT as dirname(DRIVER_DIR) from
-# import.meta.url. The code finds itself from where its file is, not from where it was started.
-#
-# THE HARDCODED NAME THIS REPLACES could not work after a documented install. INSTALL.md §2 says
-# `git clone <this-repo> && cd <repo>`, which produces a directory named after the repository -- and
-# the name in this unit was the repository this one was cut FROM. WorkingDirectory then failed and the
-# unit never started, on a host nobody is watching.
-# runner.mjs claims each queued job atomically, runs the pipeline, marks .done/.failed.
-ExecStart=/usr/bin/node ${CLEAROTRON_CHECKOUT_DIR}/driver/runner.mjs
-# Refresh the portal's flag snapshot after every drain, from THIS unit because it has the engine
-# EnvironmentFile. The clause that used to sit here — "the portal deliberately has none (AUD-shadowing
-# rule)" — is out of date: the owner's 2026-08-26 "one configuration per server box" ruling gave every
-# unit the same `EnvironmentFile=%h/.env` and removed the second source of truth the AUD protection
-# defended against. The portal and worker units now refresh it at start too (tracker issue 170); a drain
-# is still worth refreshing after, because a run is when the engine's own posture is most recently proven.
-# A snapshot that only refreshes when somebody remembers eventually describes a configuration nobody
-# is running (flag-snapshot.mjs header). `-` prefix: a snapshot failure must never fail the drain.
-ExecStartPost=-/usr/bin/node ${CLEAROTRON_CHECKOUT_DIR}/driver/flag-snapshot.mjs
-# Ceiling for a WEDGED runner ONLY — never a deadline for honest work. oneshot means the WHOLE drain
-# runs inside "activating", and a multi-job backlog (runs ~1.5h+ each; one observed gather member alone
-# ~2h26m) makes honest activations unbounded. The runner bounds its own wall time instead: past its
-# admission budget (runner.mjs CLEAROTRON_ADMISSION_BUDGET_MS, default 2h) it claims no NEW jobs, finishes
-# what's in flight and exits 0 — leftover queue *.json re-match the .path glob, which retriggers a fresh
-# activation with a fresh clock. So a legit activation is bounded by budget (2h) + one run's wall
-# (worst observed component ~2h30m), and this ceiling MUST stay above that sum (see
-# driver/test/runner.admission-budget.test.mjs) so it only ever fires on a wedged runner (one
-# SIGTERM-immune engine child). Was 0 (infinite), which let that wedge hold the unit "activating"
-# forever with no backstop.
-TimeoutStartSec=6h
-Nice=5
-
-# NOTE: not [Install]ed — it is activated by prelim-driver.path, not enabled standalone.

package/driver/systemd/prelim-driver.timer

@@ -1,14 +0,0 @@
-[Unit]
-Description=Prelim-driver queue-drain fallback — re-scan every agent queue on a fixed cadence
-Documentation=https://github.com/CordilleraSarl/Clearotron/blob/main/driver/README.md
-
-[Timer]
-# Safety net behind the event-driven prelim-driver.path. runner.mjs claims jobs atomically, so a periodic
-# re-drain is cheap and can NEVER double-run a job the .path already picked up. It guarantees any queue the .path doesn't explicitly watch (e.g. a brand-new agent workspace) still
-# drains within ~90s — the self-healing backstop whose absence let a Alex-forwarded job silently never-run.
-OnBootSec=2min
-OnUnitActiveSec=90s
-Unit=prelim-driver.service
-
-[Install]
-WantedBy=timers.target

package/driver/systemd/prelim-outbox.path

@@ -1,27 +0,0 @@
-[Unit]
-Description=Watch the prelim delivery outbox for finished-run markers
-Documentation=https://github.com/CordilleraSarl/Clearotron/blob/main/driver/README.md
-
-[Path]
-# Workstream B — instant delivery. When a handoff-mode run finishes, the driver drops <runId>.pending here
-# (the marker's first line names the forwarder agent). inotify-backed, sub-second: a marker fires
-# prelim-outbox.service, which wakes that agent to run the prelim-deliver skill NOW instead of waiting up to
-# 55m for the HEARTBEAT completion-watch (which stays enabled as the backstop). Event-driven; nothing of
-# ours runs except while a delivery is being dispatched.
-# ── tracker issue 774 — THIS GLOB IS THIS DEPLOYMENT'S OUTBOX, NOT THE CODE DEFAULT ───────────────────────────────
-#
-# Same hazard as prelim-driver.path, and read that unit's note for the full version. A .path unit cannot
-# read an environment variable, so this literal and the driver's `config.outboxDir`
-# (CLEAROTRON_OUTBOX_DIR, else <CLEAROTRON_WORK_DIR>/prelim-outbox) are two spellings of one fact with
-# nothing checking them against each other. Disagree, and finished runs drop their `.pending` markers
-# where this watcher is not looking: no delivery wake, no failure, no log — the 55m completion-watch
-# backstop quietly becomes the delivery path.
-#
-# tracker issue 774 moved the CODE default for the workspace root; this glob did not move, because the deployment
-# pins `CLEAROTRON_WORK_DIR` and `CLEAROTRON_OUTBOX_DIR` explicitly (the production env example). Change this line
-# only together with those variables, on the same box, in the same change.
-PathExistsGlob=%h/.openclaw/prelim-outbox/*.pending
-Unit=prelim-outbox.service
-
-[Install]
-WantedBy=default.target

package/driver/systemd/prelim-outbox.service

@@ -1,37 +0,0 @@
-[Unit]
-Description=Prelim delivery — wake the forwarder agent to send finished runs (prelim-deliver)
-Documentation=https://github.com/CordilleraSarl/Clearotron/blob/main/driver/README.md
-# This unit is the OPENCLAW-ADJACENT reference integration (deliver-trigger.sh wakes an OpenClaw
-# agent to send). A headless integrator replaces this pair with their own outbox watcher — the
-# contract is docs/DELIVERY.md, not this unit.
-After=openclaw-gateway.service
-Wants=openclaw-gateway.service
-
-[Service]
-# oneshot: systemd serializes, so two outbox events can't start two concurrent wakes.
-Type=oneshot
-EnvironmentFile=%h/.env
-Environment=PATH=%h/.npm-global/bin:/usr/local/bin:/usr/bin:/bin
-Environment=OPENCLAW_HOME=%h
-# NO WorkingDirectory=, deliberately -- see prelim-driver.service for the full reasoning. systemd does
-# not expand variables in WorkingDirectory=, it does expand ${VAR} in ExecStart= arguments, and nothing
-# here reads the working directory: this entry point resolves what it needs from its OWN file location.
-# Reads each *.pending marker, wakes the named agent ONCE to run the prelim-deliver skill (which sends every
-# sendPending run VERBATIM + marks .sent, idempotent), then clears the markers. The marker is only an
-# edge-trigger; status.sendPending + the .sent guard are the source of truth and the 55m HEARTBEAT watch is
-# the backstop, so a cleared/lost marker never loses a delivery and never double-sends.
-ExecStart=/bin/bash ${CLEAROTRON_CHECKOUT_DIR}/driver/deliver-trigger.sh
-# 2026-07-04 incident: TimeoutStartSec=0 (no ceiling) let ONE hung wake wedge the whole lane for 19h —
-# 1500 covers the v2+C5 trigger worst case: wake wall 870s + drain-wait 180s + backoff pacing sleep ≤300s.
-# the openclaw CLI completed its agent turn (stopReason=stop) but never exited (event loop parked in
-# ep_poll; its own --timeout did not enforce process exit), so the oneshot sat "activating" forever and
-# every later .pending marker was silently swallowed (marble-spire's delivery + VENZY's failure notice).
-# A real ceiling makes the unit SELF-HEALING: on timeout systemd kills the cgroup and fails the unit;
-# PathExistsGlob re-fires while markers remain, and the sendPending/.sent guards keep re-wakes idempotent.
-# 900s comfortably covers the slowest observed legitimate wake (copper-spire: ~13 min agent turn) — sends
-# that complete are never cut mid-flight because the ceiling exceeds the turn wall.
-TimeoutStartSec=1500
-TimeoutStopSec=30
-Nice=5
-
-# NOTE: not [Install]ed — it is activated by prelim-outbox.path, not enabled standalone.

package/driver/systemd/prelim-outbox.timer

@@ -1,21 +0,0 @@
-[Unit]
-Description=Prelim delivery rescan — fixed-cadence backstop behind the outbox watcher
-Documentation=https://github.com/CordilleraSarl/Clearotron/blob/main/driver/README.md
-
-[Timer]
-# C5 — deterministic delivery backstop. The instant lane (prelim-outbox.path) is edge-triggered off
-# *.pending markers, and its former backstop — the 55m HEARTBEAT completion-watch — does not run
-# 22:00–05:00 (activeHours), so a wake that FAILED (turn error, CLI hang, gateway-restart collision)
-# could leave a finished run undelivered all night. This timer fires the SAME prelim-outbox.service:
-# deliver-trigger.sh's rescan step re-drops a <runId>.pending marker for every run still
-# sendPending==true with no .sent, then processes them. Idempotent and paced: sendPending/.sent (and
-# the per-channel send receipts) are the source of truth, and the backoff sidecars in
-# prelim-outbox/backoff/ keep a persistently failing wake from hot-retrying.
-# OnUnitActiveSec is measured from prelim-outbox.service's LAST activation (the .path triggers the same
-# unit), so the rescan self-defers while the instant lane is busy — "hourly-ish", never stacked.
-OnBootSec=10min
-OnUnitActiveSec=50min
-Unit=prelim-outbox.service
-
-[Install]
-WantedBy=timers.target