Skip to content

Sync clarion-setup: defensive service-registration verification#87

Merged
jingerzz merged 1 commit into
zocomputer:mainfrom
jingerzz:sync-clarion-setup-defensive-service-verification
May 19, 2026
Merged

Sync clarion-setup: defensive service-registration verification#87
jingerzz merged 1 commit into
zocomputer:mainfrom
jingerzz:sync-clarion-setup-defensive-service-verification

Conversation

@jingerzz
Copy link
Copy Markdown
Collaborator

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:

  • had a trailing XML-tag artifact appended to its entrypoint (`sec-indexer</`)
  • had `CLARION_DATA_ROOT` inlined into the entrypoint shell-string instead of staying as a separate env var

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:

  • The platform's escape-handling is correct; auto-correcting malformed model input would be wrong
  • Validating shell-command syntax in the platform isn't appropriate ("there's not one syntax that's really valid we ought to parse")
  • The agent should check service startup

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.

…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.
@jingerzz jingerzz merged commit 3aeeec1 into zocomputer:main May 19, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant