Skip to main content

Secure launcher integration

Use when integrating secure high-level process launchers. Use this workflow when a controller or coordinator needs a high-level launcher/admission interface on top of an existing process transport, agent CLI, systemd wrapper, or other execution substrate.

Standing rules​

  • Treat the integration layer as a new security-sensitive candidate even when the low-level transport is already reviewed and installed. Transport acceptance does not prove caller-interface compatibility.
  • Name roles in source and policy; resolve provider/model/reasoning/profile through versioned configuration. Record the actual route in receipts after execution, never as hardcoded active policy.
  • Separate source approval, installation/readback, no-provider canary, provider-backed execution, and review verdict. Process success is never approval.
  • Keep accepted transport bytes immutable unless a fresh transport review explicitly accepts new hashes.
  • After more than two failed resolution attempts on the same unresolved item, stop the normal patch loop. Dispatch a fresh read-only Escalation Reviewer with the full cumulative lineage and require one complete failure/race-matrix remediation plan before another implementation attempt.

Procedure​

1. Reconcile the two contracts before writing code​

Read the caller-facing interface and the installed transport together. Compare:

  • exact CLI and flag placement;
  • request schema and scalar types;
  • role/route/fallback semantics;
  • plan, brief, candidate, and workspace authority;
  • reservation and replay identity;
  • receipt lifecycle and terminal-state meaning;
  • approval semantics;
  • runtime executable, environment, cgroup, and filesystem constraints.

Do not satisfy a filename check by copying, renaming, hard-linking, or symlinking a different interface. If translation is required, implement a façade with its own candidate manifest, tests, independent review, install receipt, and rollback.

2. Packetize before dispatching a confined Implementer​

Copy every authoritative external input the worker must read into a packet-local read-only reference/ directory and hash-check each copy. Make the brief point to local paths. An attached brief does not grant access to absolute paths named inside it; denied discovery can consume a whole run without producing code.

Require an early mutation checkpoint: tests first, observed RED, then the smallest production slice. If a pass exits after discovery with no artifact, preserve the session, supply the complete local packet, and resume only with a literal file/test postcondition.

3. Snapshot authority once, before reservations​

Stable-read plan and brief through retained descriptors. Before any durable reservation:

  1. validate canonical path, regular type, owner, mode, size, encoding, and path representation;
  2. compare the declared plan digest to the retained bytes;
  3. calculate the brief digest;
  4. enforce a documented aggregate prompt-size limit;
  5. construct an unambiguous length-delimited or equivalent byte-safe prompt format;
  6. complete all other deterministic checks.

After reservations, build the frozen prompt only from retained bytes. Never reopen authority paths. Test replacement between preflight and publication, embedded framing tokens, missing trailing newline, invalid UTF-8, aggregate boundaries, and exact round-trip digest extraction.

4. Keep configured runtime authority authoritative​

Bind canonical regular interpreter and launcher-entry paths plus expected hashes in configuration. Validate them before reservations and immediately before submission. Put the configured expected digest into generated intent; a later read may confirm it but must never replace it with a newly observed digest.

For virtual environments, test the actual packaging/install algorithm—not a friendlier fixture:

  • resolve a symlinked launcher to a verified regular base interpreter;
  • use a no-clobber regular copy or a hardlink only when inode/mode semantics are acceptable;
  • handle cross-filesystem fallback through an exclusively created temporary file, descriptor-based copy, mode/hash verification, fsync, and atomic no-replace publication;
  • verify final lstat identity, owner, exact mode/hash, sys.prefix, package import origin, and installed parser behavior;
  • ensure config application is unavailable until every runtime gate passes.

Never chmod a hardlink when that would mutate the source inode.

5. Generate and test the entire command​

Assert full argv equality against the installed parser, including:

  • global profile and telemetry options in their real positions;
  • chat/subcommand selection;
  • one-shot and query-file delivery;
  • rules/customization policy;
  • exact tool surface;
  • provider/model/reasoning from role config;
  • fallback/delegation prohibition;
  • source tag and current run-budget flag.

A route-only low-level validator can admit a command that never delivers the assignment. Run a harmless installed-parser/import probe with no provider/network activity in addition to synthetic parser tests.

6. Reserve and publish with a complete state matrix​

Model candidate, prefix, and assignment reservations separately. Cover omitted-prefix derivation and explicit-prefix publication. For each create-once artifact, inject failures/races around:

  • exclusive temporary creation;
  • short/interrupted write;
  • chmod/fsync;
  • temporary inode replacement or foreign links;
  • no-replace final publication;
  • final inode and expected link-count checks;
  • directory fsync;
  • readback;
  • temporary-name removal;
  • post-publication alias/replacement.

A failed public launch publication must never dispatch, overwrite foreign data, permit retry, or imply approval. Clean up only installer-owned artifacts.

7. Validate transport evidence semantically​

Read claim and terminal artifacts once with stable descriptor checks; retain raw bytes and parse those bytes with duplicate-key rejection. Hash the retained bytes. Require exact accepted schemas and types, then bind:

  • intent digest;
  • source inventory;
  • exact command;
  • claim digest;
  • attempted flag;
  • terminal state;
  • adapter/process return code;
  • optional failure field for ambiguity.

Reconcile success, failed submission, and ambiguous exception separately. Every malformed or mismatched case must produce durable non-approval, retry_allowed=false, and a nonzero launcher status.

8. Verify independently before every state transition​

Do not trust worker summaries or exit zero. Independently:

  1. inspect changed-file scope and manifests;
  2. verify every manifest size/mode/hash programmatically;
  3. run focused and full isolated suites after the latest edit;
  4. AST/compile-check without bytecode residue;
  5. rehash accepted transport bytes;
  6. run the no-provider parser/import gate;
  7. create an immutable read-only review packet;
  8. launch a fresh Reviewer and rehash subjects after exit.

A Reviewer approval permits only the explicitly named next gate. Installation must capture preimages, exact runtime/config bytes, rollback, and post-install readback. Run a no-provider canary before any provider-backed assignment.

Review-loop convergence​

Count substantive REQUEST_CHANGES rounds cumulatively. After the third failed candidate, do not send another narrow correction brief. Give the Escalation Reviewer:

  • every prior report and disposition;
  • exact current candidate and manifest;
  • fresh parent gate evidence;
  • caller and transport contracts;
  • the complete input, installation, reservation, publication, evidence, terminal-state, rollback, and cleanup matrix.

The Escalation Reviewer returns one actionable ordered plan with exact files, RED tests, acceptance gates, and re-review criteria. The Coordinator executes it; a fresh Reviewer checks the exact successor.

Status reporting​

Report concise milestones:

  • running: real Implementer/Reviewer child alive and its current phase;
  • written: concrete files changed, not merely analysis;
  • verified: exact commands and counts independently observed;
  • reviewed: immutable candidate and verdict;
  • installed: exact bytes/config/rollback read back;
  • blocked: one precise owner/action, not repeated unchanged status.

Never call staged, fail-closed, or test-green source “deployed.”

Source: jknash/hermes-shared-skills · branch hermes-jkdev001 @ 1d0d545c3970 · skills/engineering/secure-launcher-integration/ · view source · Imported 2026-10-04. Supporting files (references, scripts) remain in the source repository.

version 1.0.0 · author Hermes Curator · license MIT.

Published by Muse · 2026-10-04.