clearotron 0.2.1 → 0.2.3

package/skills/clearotron-account/SKILL.md

@@ -165,21 +165,50 @@ question to the issuing firm rather than reconstructing an answer.
 
 ## Asking what-if
 
-A what-if re-runs **one step** of a finished search under a changed assumption, in a sandbox. It is the
-right tool when the user asks *what if this were different* — and the wrong one when they want a fresh
-answer about a different mark, which is a new search.
-
-- **Plan, read the honesty note aloud, then commit.** `what_if_plan` says in plain words how complete
-  the answer will be. Re-running an early step does **not** re-run the risk read or the report on top of
-  it, and a user who is not told that will read a partial output as a new verdict. Say it before you
-  spend, not after.
-- **It costs money and it is not instant.** The experiment queues on the server and runs there. Tell the
-  user it is running and collect it with `what_if_result` rather than promising an immediate answer.
+A what-if answers *what if this were different* about a search that has already run. There are two, and
+the search's own state decides which one you can have:
+
+- a **step re-run**, while the search is still live — one step runs again under a changed assumption, in
+  a sandbox;
+- a **memo**, once the search is delivered or archived — the evidence already gathered is read again
+  under the assumption, and a short document comes back naming the report it belongs to.
+
+Either is the wrong tool when the user wants a fresh answer about a different mark. That is a new search.
+
+**On a delivered report, offer the memo.** A step re-run is refused there, and that refusal is the one
+that used to end the conversation with *commission a fresh search*. It should not. A user holding a
+report who asks *what if the Korean application were abandoned* is asking the most ordinary question
+there is, and the memo is the answer to it — so check the search's state before you tell anyone the
+question cannot be answered.
+
+- **Name the step when you ask for a re-run; do not when you ask for a memo.** `what_if_plan` has to be
+  told which step, and asking without one is an error rather than a refusal you can relay. A memo re-runs
+  no step: pass the user's assumption as `instructions` and nothing else.
+- **Plan, read the honesty note aloud, then commit.** `what_if_plan` says in plain words how complete the
+  answer will be. Re-running an early step does **not** re-run the risk read or the report on top of it,
+  and a user who is not told that will read a partial output as a new verdict. Say it before you spend,
+  not after.
+- **It is not instant.** Both kinds queue on the server and run there. Tell the user it is running and
+  collect it with `what_if_result` rather than promising an immediate answer.
 - **You do not choose how it runs.** There is no model or tier for you to pick, and asking for one is
   refused. Express the change in `instructions`, in the user's own terms.
-- **The original is untouched, and say so.** A what-if never edits the delivered search or its report.
-  Present the result as *what this step would have said under that assumption*, never as a correction to
-  the report the user already holds.
+- **The original is untouched, and say so.** Neither kind edits the delivered search or its report.
+  Present the result as *what this would have said under that assumption*, never as a correction to the
+  report the user already holds.
+
+### What a memo is, and what it is not
+
+Say all three when you offer one, not when you deliver it. A user who learns the bounds afterwards has
+already read it as something it is not.
+
+- **It searches nothing.** No register is queried and no new evidence is gathered. It reasons over what
+  the search already found, and costs nothing beyond model time.
+- **It cannot confirm the assumption.** It says what would follow *if* the assumption held, and states
+  what the smallest piece of work would be that could settle whether it does. It is not a finding that
+  the Korean application was abandoned; it is what that would mean if it were.
+- **A stopped search takes neither kind.** A search its owner cancelled has evidence that was never
+  finished, and reasoning over a half-gathered record is how a memo comes to say more than the search
+  ever knew.
 
 ## Before you start a search
 

package/skills/clearotron-ops/SKILL.md

@@ -41,7 +41,7 @@ Extract from the request, faithfully (verbatim beats paraphrase):
 - **`forwarder`** (+ `forwarderEmail`) — the requester/reply route. REQUIRED, no default: this is
   where the report goes; a wrong route misdelivers a confidential document.
 - **`profileKey`** — call **`list_profiles`** and resolve by JUDGMENT: an explicit name, a
-  misspelling ("Zefyr" → zephyr), or an implicit reference ("our functional-beverage client") all
+  misspelling (a name typed as it sounds), or an implicit reference ("our functional-beverage client") all
   map to a key. OMIT it for a new/unknown customer (the neutral generic profile applies — this is
   non-blocking by design). Ask the requester only when you genuinely cannot tell. **Never pick a
   profile from the sender's email domain.**

package/driver/recipes/README.md

@@ -1,49 +0,0 @@
-# Saved searches ("recipes")
-
-One subdirectory per customer — `aurora/` and `zephyr/` — each holding one JSON file per saved search at
-`<customer>/<slug>.json`; the loader walks directories only, so nothing else here is a store. A recipe is a
-small named bundle: a base product, optional component toggles, an optional `scope` block (where the
-machinery points: `jurisdictions`, `platforms`, `classes`), and instruction-shaped `extras`.
-The display field is `label`, deliberately not `name` — `name` is a profile key, and the two key sets are
-disjoint by design, so a saved search can never carry rating config.
-
-## What reads it
-
-`loadRecipes()` in `../search-policy.mjs` walks `<dir>/<customer>/<slug>.json` into a
-`Map("customer/slug" → recipe)`, validating each file with `validateRecipe` — the same validator the write
-door uses, so the UI cannot persist a recipe the driver would later reject. `resolveSearchPolicy` then
-turns a job's `recipeKey` into the product, components, extras and scope the run uses; a recipe only runs
-for its own customer, and an `archived` one refuses with a clarify.
-
-The write side is `../recipe-service.mjs` (loopback, CF Access JWT, git auto-commit as the verified
-identity). The portal mounts those routes through `../portal-upstream.mjs`, which rebuilds the customer
-path segment from the resolved account; `../dev-portal.mjs` proxies `/recipes/*` for dev.
-
-**The store is named, never guessed.** `CLEAROTRON_RECIPES_DIR` unset means the deployment has no saved
-searches — not that it falls back to this directory. That fallback existed and was removed: production is
-exactly where the variable is unset, so it would have surfaced invented customers inside the product.
-
-## These are synthetic demos
-
-`aurora` and `zephyr` are fictional customers (`../profiles/aurora.json`, `../profiles/zephyr.json`) that
-exist so the dev cockpit and the test suite have something to render. A real deployment's recipes live
-outside the repo, in the customer-config store beside the profiles — no client data in git.
-
-| File | Base product, and any extras it carries |
-|---|---|
-| `aurora/quarterly-screen.json` | `knockout-search`, `extras.emailTable` |
-| `aurora/screen-with-register-counts.json` | `knockout-search` |
-| `zephyr/standard-clearance.json` | `multi-country-focus-search`, `extras.standingInstructions` + `extras.defaultDeadlineDays` |
-
-Two of them carry settings the product no longer offers, which is not an oversight: `emailTable` is inert
-but still validated so recipes written while it worked keep loading, and `defaultDeadlineDays` is a retired
-extra that `loadRecipes` drops on read and `validateRecipe` refuses on save. A stored recipe must not brick
-on a change it never asked for.
-
-## Where to start
-
-`zephyr/standard-clearance.json` — twelve lines, and the one whose `extras` show both what an
-instruction-shaped setting looks like (`standingInstructions`) and what a retired one looks like still
-sitting in a stored file. Then the recipe block in `../search-policy.mjs` (`RECIPE_KEYS`,
-`RECIPE_SCOPE_KEYS`, `RECIPE_EXTRA_KEYS`, `validateRecipe`), which is where every rule above is enforced
-and commented.

package/driver/skills/prelim-search/risk-framework-aurora.manifest.json

@@ -1,19 +0,0 @@
-{
-  "schema_version": 1,
-  "framework_key": "aurora",
-  "title": "Aurora Interactive risk framework (synthetic demo)",
-  "source_deck": "Synthetic demo transposition of a customer risk deck (structure faithful, content invented), doc 50 shape",
-  "entity_label": "Aurora Interactive",
-  "bands": [
-    { "label": "Very High", "tone": "severe" },
-    { "label": "High", "tone": "high" },
-    { "label": "Medium", "tone": "medium" },
-    { "label": "Manageable", "tone": "low" },
-    { "label": "Low", "tone": "minimal" }
-  ],
-  "structure": {
-    "kind": "matrix",
-    "axes": ["Legal Risk Level (A–E)", "Dispute Type"],
-    "display_note": "The band is read off this framework's Level × Dispute Type matrix; the matrix ceilings are stated in the deck and honoured as written."
-  }
-}

package/driver/skills/prelim-search/risk-framework-aurora.md

@@ -1,77 +0,0 @@
-# Risk framework — Aurora Interactive (SYNTHETIC demo customer)
-
-- **Applies to:** Aurora Interactive matters (`profileKey: aurora`).
-- **Source:** house-authored demonstration framework. Matrix-shaped, to exercise the two-input path.
-- **Bands, highest to lowest:** Very High · High · **Medium** · Manageable · **Low** (this framework, unlike the house default, has a Low band — its Level A output).
-- **Entity in prose:** **Aurora Interactive** (name the company; acquired studios are self-exclusions, not the entity).
-- **Customer emphasis:** defensibility-first and conservative — lead with a clear go / no-go and the practical "would they actually enforce" read; surface an alternative-name track early on a headline conflict.
-
-*A rubric to be reasoned with — not paraphrased away and not reduced to a lookup.* This framework RATES Aurora Interactive matters (doc 50). It is **matrix-shaped**: reason the two inputs below in order — the Legal Risk Level, then the Dispute Type — and read the band off the matrix. **State the rating as the band word** (Very High / High / Medium / Manageable / Low); the numerals beside the bands are internal indices, never the output. The engine applies this framework on an advisory basis; the senior lawyer makes the final determination. The firm-wide reasoning discipline — the consumer-confusion gate, the dominant-element rule, crowded-field handling, G&S discipline — lives in [`synthesis-rules.md`](synthesis-rules.md) and applies under every framework; Aurora calibration examples live in [`worked-examples-aurora.md`](worked-examples-aurora.md).
-
-## Legal Risk Levels (probability adverse party prevails)
-
-| Level | Probability | Description |
-|-------|------------|-------------|
-| **A** | 0–24% | Weak claim, negligible risk, strong defences available |
-| **B** | 25–49% | Some credible claims but more likely to prevail; manageable |
-| **C** | 51–60% | Better than even chance of adverse outcome; material risk, may need settlement |
-| **D** | 61–74% | Likely adverse outcome; some credible defences but unsuccessful result expected |
-| **E** | 75%+ | Strong claim / slam dunk against us; no or only weak defences |
-
-> **The letter follows the words (consistency rule — apply to every rated finding).** State the likelihood of confusion in plain words *first* — "more likely than not they'd win", "better-than-even is not reached", "confusion is unlikely", "distinguishable as wholes" — **then pick the letter those words require**: better-than-even reached → **C–E**; not reached → **A or B** (B = 25–49%, "credible claim but we have the better of it"). The prose read and the A–E letter are **one judgment and may not disagree.**
-
-## Dispute Types
-
-| Type | Characteristics |
-|------|----------------|
-| **Classic** | Actual confusion anticipated, well-known/famous mark, aggressive brand owner, direct industry competitor |
-| **Horse Trade** | Market overlap, settlement likely with payment or use restrictions |
-| **Paper Conflict** | Material register risk but no obvious market overlap in practice |
-| **Descriptive Terms** | Descriptiveness defence available, or extensive unregistered use weakens distinctiveness |
-| **Nuisance Claim** | Weak claim but party may still complain (trolls, squatters, speculative filings) |
-
-## The band matrix — reason the two inputs, then read the band off the matrix
-
-The band is **derived from two reasoned inputs, in this order — it is not chosen freely, and no practical /
-optics factor moves the band directly:**
-
-1. **Legal Risk Level (A–E) — first.** Answers one question: *"if this third party sued Aurora Interactive,
-   would they win?"* Set it from the likelihood-of-confusion comparison (marks-as-wholes × goods/services; see
-   `synthesis-rules.md` → *The consumer confusion test*), net of merits defences. (50% is not allowed — take a
-   view.) Applies to registered AND common-law rights.
-2. **Dispute Type — second.** Classic / Horse Trade / Paper Conflict / Descriptive (or extensive-use) / Nuisance.
-
-Then read the **band off the matrix** — this is the *output*; you do not adjust it afterwards:
-
-| Band | Requires |
-|---|---|
-| **Very High** *(5)* | Level **D or E** AND **Classic** |
-| **High** *(4)* | Level **D or E** AND (**Horse Trade** or **Nuisance**) |
-| **Medium** *(3)* | Level **C / D / E** AND (**Paper** or **Descriptive**) — OR — Level **C** AND (**Horse Trade** / **Classic** / **Nuisance**) |
-| **Manageable** *(2)* | Level **B** (routinely accepted; still alert on a troll/squatter, a known competitor / major brand owner, or heavy clean-up cost) |
-| **Low** *(1)* | Level **A** |
-
-**The ceilings are hard — and they ARE this framework's anti-escalation mechanism:**
-- **High and Very High REQUIRE Legal Level D or E.** A **Level-C finding tops out at Medium**, whatever the
-  dispute type or the practical factors. **Level A → Low and Level B → Manageable are fixed.**
-- **Elevate / mitigate considerations move the INPUTS — the Legal Level or the Dispute Type — never the output
-  band** (the factor lists live in `synthesis-rules.md`). A "confirmed aggressive enforcer", owner size, PR
-  sensitivity, or an Aurora Interactive partnership cannot lift a finding past its level's ceiling: they only
-  change *whether they'd win* (the Level) or the *character* of the dispute (the Type), and the matrix then
-  produces the band. This is exactly the optics-escalation error the ceilings prevent — a Level-C read does NOT
-  become High because the owner enforces aggressively; a house-mark-distinguished Level-B mark does NOT become
-  Very High because the owner is large or a partner.
-
-**Calibration anchors (structure-faithful; the mark names are invented, the anchor companies are real and named only as public examples of scale):** VELARIS / POLARIS-class famous-mark conflicts = Level
-**E** + **Classic** = **Very High**; TerraForge / TerraFlex = Level **E** + **Horse Trade** = **High**;
-Northgate / NorthData = Level **D** + **Horse Trade** = **High**.
-
-## Band meanings
-
-| Band | Meaning | Typical Response |
-|-------|---------|-----------------|
-| **Very High** | Generally not accepted | Run alternative name in parallel |
-| **High** | May accept with strong mitigation | Requires active risk management plan |
-| **Medium** | May accept with settlement/clean-up plan | Proceed with awareness and contingency |
-| **Manageable** | Routinely accepted | Note and monitor |
-| **Low** | Target outcome | Proceed with confidence |

package/driver/skills/prelim-search/risk-framework-zephyr.manifest.json

@@ -1,14 +0,0 @@
-{
-  "schema_version": 1,
-  "framework_key": "zephyr",
-  "title": "Zephyr Beverages risk framework (synthetic demo)",
-  "source_deck": "Synthetic demo transposition of a customer risk deck (structure faithful, content invented), doc 50 shape",
-  "entity_label": "Zephyr/Volt/Kaskade",
-  "bands": [
-    { "label": "Very High", "tone": "severe" },
-    { "label": "High", "tone": "high" },
-    { "label": "Medium", "tone": "medium" },
-    { "label": "Manageable", "tone": "low" }
-  ],
-  "structure": { "kind": "bands" }
-}

package/driver/skills/prelim-search/risk-framework-zephyr.md

@@ -1,33 +0,0 @@
-# Risk framework — Zephyr Beverages (SYNTHETIC demo customer)
-
-- **Applies to:** Zephyr matters (`profileKey: zephyr`).
-- **Source:** house-authored demonstration framework. The house default with a different entity family and one band relabelled.
-- **Bands, highest to lowest:** Very High · High · **Medium** · Manageable. There is no "Low"; Manageable is the lowest band.
-- **Entity in prose:** **Zephyr/Volt/Kaskade** — name the brand family, not "the company".
-- **Customer emphasis:** pragmatic and launch-oriented — a clear go / no-go and the facts that condition each real blocker, rather than exhaustive caveats. (Express this emphasis in the product voice: facts that condition, never a recommended "path" — retired voice, 2026-07-28.)
-
-*This is the house default with exactly two differences: the entity family, and band 3 is labelled **Medium** (not "Moderate"). A rubric to be reasoned with, not paraphrased.* This framework RATES the matter (doc 50): reason each conflict through the band definitions below — Legal position first, then Practical position, then Potential outcomes — and the band follows the words. A conflict Zephyr/Volt/Kaskade clearly wins with no material risk is **not a rated conflict** (there is no "Low" band; see `synthesis-rules.md`). The engine applies this framework on an advisory basis; the senior lawyer makes the final determination. The firm-wide reasoning discipline lives in [`synthesis-rules.md`](synthesis-rules.md) and applies under every framework; Zephyr calibration examples live in [`worked-examples-zephyr.md`](worked-examples-zephyr.md).
-
-## VERY HIGH RISK
-
-- **Legal position.** Prior rights owner is **very likely to win** and there are **no** credible defences or risk-mitigation strategies available to **Zephyr/Volt/Kaskade**.
-- **Practical position (one or more).** There is an obvious market overlap or risk of actual confusion — coexistence does not appear possible, even with payment of money, use restrictions or other exchange; **or** the prior mark is famous, owned by a known aggressor, or an industry competitor.
-- **Potential outcomes.** Name change likely required, possibly on an urgent basis · monetary exposure **more than $10 million** · severe PR consequences · highly unlikely to mitigate risk irrespective of time and money.
-
-## HIGH RISK
-
-- **Legal position.** Prior rights owner is **likely to win**, although some credible defences are available to **Zephyr/Volt/Kaskade**.
-- **Practical position.** There is possible market overlap, but co-existence appears possible with settlement involving payment of money, use restrictions, and/or other exchange.
-- **Potential outcomes.** Name change may be required, possibly on an urgent basis · high business disruption possible · monetary exposure **up to $10 million** · PR consequences · cleanup or mitigation may be possible depending on time and budget.
-
-## MEDIUM RISK
-
-- **Legal position.** Prior rights owner is **more likely than not to win**, although reasonable defences or risk-mitigation steps are available to **Zephyr/Volt/Kaskade**.
-- **Practical position (one or more).** There is no obvious market overlap; **or** risk-mitigation strategies are available to Zephyr/Volt/Kaskade (e.g. the prior mark is arguably weak or vulnerable to attack); **or** there are practical factors which suggest the prior rights owner may not object (e.g. settlement discussions are underway).
-- **Potential outcomes.** Name change may be required, possibly on an urgent basis · business disruption possible · monetary exposure **$5 to 7 figures** · PR consequences possible · cleanup or mitigation may be possible depending on time and budget.
-
-## MANAGEABLE RISK *(lowest band)*
-
-- **Legal position.** **Zephyr/Volt/Kaskade** is **more likely than not to win**, although there is still material risk and uncertainty.
-- **Practical position.** This level of risk includes nuisance claims, strategic (but weak) complaints by a competitor, and registration obstacles.
-- **Potential outcomes.** Budget potentially required for prosecution hurdles and nuisance claims.

package/driver/skills/prelim-search/worked-examples-aurora.md

@@ -1,10 +0,0 @@
-# Example per-customer worked examples — aurora (synthetic)
-
-Synthetic placeholder demonstrating a profile's `workedExamplesPath` hook. Real per-customer worked
-examples are a customer-config-store artifact, not repo code.
-
-**Convention (P6):** a per-customer file ADDS CALIBRATION and never replaces the voice. The before/after
-voice pairs live in [`worked-examples.md`](worked-examples.md) → *Voice — worked before / after pairs*, and
-a customer artifact that omits them leaves this customer's runs without the examples the house voice is
-learned from. The house prose contract itself is carried unconditionally by the stage message, so the RULES
-reach every run regardless of profile — it is the worked pairs that a replacement file can silently drop.

package/driver/skills/prelim-search/worked-examples-zephyr.md

@@ -1,10 +0,0 @@
-# Example per-customer worked examples — zephyr (synthetic)
-
-Synthetic placeholder demonstrating a profile's `workedExamplesPath` hook. Real per-customer worked
-examples are a customer-config-store artifact, not repo code.
-
-**Convention (P6):** a per-customer file ADDS CALIBRATION and never replaces the voice. The before/after
-voice pairs live in [`worked-examples.md`](worked-examples.md) → *Voice — worked before / after pairs*, and
-a customer artifact that omits them leaves this customer's runs without the examples the house voice is
-learned from. The house prose contract itself is carried unconditionally by the stage message, so the RULES
-reach every run regardless of profile — it is the worked pairs that a replacement file can silently drop.

package/driver/systemd/prelim-driver.path

@@ -1,69 +0,0 @@
-[Unit]
-Description=Watch the prelim-search driver queue for new job files
-Documentation=https://github.com/CordilleraSarl/Clearotron/blob/main/driver/README.md
-
-[Path]
-# Watch EVERY prelim-capable agent's queue (inotify-backed). When a *.json job lands in any of them, start
-# the drain service — which runs the job as the agent whose workspace it sits in. One PathExistsGlob per
-# watched queue ("Multiple directives may be combined … to watch multiple paths" — systemd.path(5)).
-# Event-driven, sub-second; nothing of ours runs except while a job is being processed. The
-# prelim-driver.timer fallback re-drains every ~90s so a queue NOT listed here (e.g. a brand-new agent, or
-# a mid-path glob systemd fails to arm) still gets picked up — the watcher is an optimisation over the timer,
-# never the sole drain path.
-#
-# These lines MUST mirror config.queueDirs (driver.config.mjs) — the runner drains those regardless, so any
-# queue the runner scans but the watcher misses only pays the ≤90s timer latency (the pre-fix bug: this unit
-# watched only the headless dir below, which does not exist in an agent-workspace deployment, so event-driven
-# pickup was dead and the queue drained on the timer alone — and wedged entirely whenever the timer was down).
-#
-# ── tracker issue 774 — THESE GLOBS ARE THIS DEPLOYMENT'S WORKSPACE ROOT, NOT THE CODE DEFAULT ────────────────────
-#
-# A .path unit CANNOT read an environment variable. There is no `%E`, no EnvironmentFile, no expansion:
-# the prefix below is a literal, and it is the one thing in the queue lane that CLEAROTRON_WORK_DIR
-# cannot reach. So this file and `CLEAROTRON_WORK_DIR` in %h/.env are two spellings of one fact, and
-# nothing at runtime notices when they stop agreeing.
-#
-# WHAT DISAGREEMENT LOOKS LIKE: the runner drains $CLEAROTRON_WORK_DIR; this watcher arms an inotify on
-# a path nothing writes to. Jobs land, the watcher never fires, no unit fails, no log line appears, and
-# the only thing still draining is the 90s prelim-driver.timer — so the lane looks alive and every job is
-# late. If the timer is also down, the queue simply stops.
-#
-# tracker issue 774 moved the CODE default for CLEAROTRON_WORK_DIR from `$HOME/.openclaw` to
-# `$HOME/trademark/workspace`. These globs did NOT move with it, and that is correct: they must track the
-# deployment, and the deployment pins `CLEAROTRON_WORK_DIR=<home>/.openclaw` in its EnvironmentFile
-# (the production env example) precisely so its run directories do not move under a live queue. Change one of
-# these three lines only together with that variable, on the same box, in the same change.
-# driver/test/data-plane-defaults.test.mjs asserts this file and the production env example still agree.
-#
-# AGENT-WORKSPACE deployment (this VM): one line per prelim-capable agent. We watch each CONCRETE queue dir
-# (only the final *.json is a wildcard) so systemd arms an inotify watch directly on the queue directory —
-# a mid-path `workspace-*` glob is not reliably armed. Add a line when a new prelim agent is onboarded; until
-# then the 90s timer + dynamic config.queueDirs still pick its jobs up.
-# ── RESOLVED AT INSTALL (tracker issue 1876 option B) ────────────────────────────────────────
-# `@CLEAROTRON_WORK_DIR@` is substituted by render-units.mjs when it writes the resolved copy into
-# ~/.config/systemd/user/. That closes the half of the disagreement above that VARIES BY MACHINE: the
-# workspace root is now taken from the same value the runner drains, so the two spellings cannot drift
-# apart on an install.
-#
-# THE AGENT SEGMENT IS NOT SUBSTITUTED, AND THAT IS A LIMIT WORTH STATING RATHER THAN HIDING.
-# `driver.config.mjs` builds the queue as join(workspaceRoot, workspaceDirName(agent), "studio",
-# "prelim-search", "queue") — so the root is configuration and `workspace-clawdi` is a per-deployment
-# choice, already documented by the commented alternative below. Substituting it would need a variable
-# nothing sets today, and inventing one to make this line look fully resolved would be the more
-# dangerous kind of fix: it would read as configured while resolving to whatever the default happened
-# to be. One real value substituted beats two that look substituted.
-PathExistsGlob=@CLEAROTRON_WORK_DIR@/workspace-clawdi/studio/prelim-search/queue/*.json
-# One line per ADDITIONAL prelim-capable agent this deployment onboards, e.g.
-#PathExistsGlob=%h/.openclaw/workspace-<agent>/studio/prelim-search/queue/*.json
-# Two lines here named individual people at this firm and shipped their identities to every clone
-# (tracker issue 1014). They are a deployment's own roster, not the product's. Omitting a line costs LATENCY and
-# not correctness: as the note above says, the 90s timer and the dynamic config.queueDirs still
-# collect that agent's jobs — the watch only makes them immediate.
-# HEADLESS deployment (docs/INTAKE.md): a standalone product with no agent workspaces instead watches the one
-# explicit queue named by CLEAROTRON_QUEUE_DIR (default ~/prelim-queue). Uncomment for that mode; harmless to
-# leave active in a mixed deployment (never matches when the dir is absent), mirroring the additive queueDirs.
-#PathExistsGlob=%h/prelim-queue/*.json
-Unit=prelim-driver.service
-
-[Install]
-WantedBy=default.target

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