Sync clarion-setup: defensive service-registration verification#87
Merged
jingerzz merged 1 commit intoMay 19, 2026
Conversation
…ion) Upstream PR jingerzz/clarion-intelligence-system#20: hardens clarion-setup's SKILL.md against silent service-registration corruption documented in gist f074a7555097546b5f582bdf07234a4f (a new Zo user ended with a registered sec-indexer service whose entrypoint had a trailing XML-tag artifact and whose CLARION_DATA_ROOT got inlined into the entrypoint string instead of staying in env_vars). Two changes: 1. Step 4 — explicit env_vars formatting guidance. The parameter is a JSON object, not a stringified JSON. Correct vs wrong examples inline so models that try to escape it back out know to re-form the call. 2. Step 5 — replace the weak `sec-indexer --help` check (proves binary on PATH, says nothing about service state) with real service-startup verification via `service_doctor sec-indexer`. Names the two known failure modes (trailing entrypoint chars, missing/inlined env_vars), provides log-inspection paths, and adds an explicit "do not report setup complete until RUNNING with non-zero uptime" rule. Zo engineering response (paraphrased) confirmed the SKILL.md is the right layer for both fixes — escape-handling in the platform is correct as-is; entrypoint validation isn't a platform concern (heuristic); the agent should check service startup. Docs-only; no Zo platform changes required.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Syncs `External/clarion-setup/SKILL.md` to upstream `jingerzz/clarion-intelligence-system@4236cdd` (PR #20).
What this addresses
A new Zo user's Clarion install (documented in gist `f074a7555097546b5f582bdf07234a4f`) ended with a "successfully registered" `sec-indexer` service that:
The agent reported "setup complete" because `register_user_service` returned success and `sec-indexer --help` worked. Neither proves the service actually runs. The supervisor cannot execute `sec-indexer</`.
Root cause and where the fix lives
The model on that Zo serialized `env_vars` as a stringified JSON instead of a JSON object, causing escape-handling complexity and multiple `runner stopped` failures. The eventual workaround inlined env vars into the entrypoint shell-string — fragile, and the entrypoint also bled an XML stop-token artifact.
Zo engineering confirmed (paraphrased) that:
Translation: prevention and verification belong in the bootstrap's SKILL.md. This sync brings that fix into the registry.
Changes (docs-only, +36/-4 lines)
Step 4 — sharpen env_vars guidance. New env_vars formatting (critical — common failure mode) callout with correct-vs-wrong examples:
```json
// correct
{"ZO_API_KEY": "$ZO_API_KEY", "CLARION_DATA_ROOT": "/home/workspace/clarion"}
// WRONG (stringified, requires escapes)
"{\"ZO_API_KEY\": \"$ZO_API_KEY\", ...}"
```
Tells the agent that escape-sequences-required means re-form the call.
Step 5 — replace weak `--help` check with real service-status verification. Previous Step 5 just ran `sec-indexer --help` and called the install done. New Step 5 runs `service_doctor sec-indexer`, requires `RUNNING` with non-zero uptime, names the two known failure modes (trailing entrypoint chars; missing/inlined env_vars), provides log paths, and adds an explicit "do not report setup complete until status is RUNNING" rule. The `--help` check is preserved at the bottom as a labeled secondary sanity check.
Validation
`bun validate` — clean on `clarion-setup` (the 15 pre-existing warnings on other skills are untouched).
Footprint
Single file: `External/clarion-setup/SKILL.md`. No code, no schema, no other skills affected.
After merge, the SKILL.md change is what the registry serves to new users running install the clarion-setup skill. Frontmatter is unchanged, so no manifest regen is needed.