profile-isolated-agent-runtimes

Profile-Isolated Agent Runtimes

Overview

Use this class-level skill when one tenant or product instance contains multiple persistent Hermes-like operators and correctness depends on every chat turn, background job, secret, and mutation reaching the exact owning profile.

The central rule is:

Business/domain records retain their canonical ownership model; profiles identify isolated operators, immutable authority, runtime routing, and provenance.

This skill covers the full chain from durable profile identity through runtime resolution, private filesystem materialization, profile-bound capabilities, chat/job dispatch, lifecycle supervision, and disposable canary proof.

When to Use

• Adding business/portfolio profiles to a tenant application.
• Replacing a shared/global agent transport with profile-prefixed routing.
• Building one private multiplexer with isolated profile homes.
• Binding API credentials and domain authority to profiles.
• Making scheduled reasoning jobs profile-owned.
• Reviewing fallback, cross-profile access, secret leakage, startup, backup, or rollback behavior.
• Salvaging timed-out delegated implementation of security-sensitive runtime work.

Required Topology Decision

Choose and document the product topology before coding:

• Single-business tier: one persistent business profile.
• Portfolio tier: one portfolio profile plus one isolated business profile per business.
• Canonical records remain project/business-owned.
• Portfolio reads require explicit field grants; portfolio mutations are delegated to the owning business profile.

Do not equate profile identity with data ownership, and do not let caller/model fields create authority.

Canonical Runtime Chain

thread/job
  → hermes_profile_id
  → authoritative active profile reload
  → exact stored opaque runtime_ref
  → trusted runtime resolution
  → /p/<profile-slug>/...
  → isolated home/session/secrets
  → profile-bound capability
  → canonical domain command
  → profile-attributed audit/job/review/UI state

Hard requirements:

1. runtime_ref is opaque and server-owned, never a caller URL/path/port.
2. Use one canonical versioned runtime contract across router, manager, materializer, supervisor, appliance, and tests.
3. Reject missing, inactive, unhealthy, stale, malformed, or contradictory bindings.
4. Enforced routing never falls back to global Hermes or an unprefixed/legacy transport.
5. A supplied project/business ID is a consistency assertion only.
6. Provenance uses the real profile foreign key, never a free-form binding string.

Multiplexer and Private Homes

Prefer one private API-only multiplexer per tenant with profile-prefixed routes. Materialize one private home per profile beneath the multiplexer root and isolate:

• sessions and transcript state;
• memory and knowledge;
• cron/job state;
• workspace and temporary files;
• plugin configuration;
• provider and domain credentials.

Use canonical/relative path containment checks and reject traversal, absolute escapes, unsafe slugs, and sibling-prefix tricks.

Raw capabilities and provider keys belong only in private profile secret files. Config/manifests may contain provider/model names and trusted non-secret bindings, never raw credentials or model-selectable authority. Profile-local connector configuration must defeat hostile ambient values.

Profile-Bound Authorization

Issue one reusable active capability identity per profile:

• store only capability hashes;
• persist the actual profile foreign key;
• derive business scope from the authenticated active profile;
• reload profile authority per request;
• revoke stale identities before rotation;
• write plaintext capability only into the owning profile's private secret file;
• deny portfolio business mutations and require explicit field-level grants for portfolio business reads.

Persistent business profiles should not receive ambient host, Docker, SSH, plugin administration, source/database access, or self-modification authority. Use temporary bounded workers for elevation.

Profile-Owned Scheduled Reasoning

Keep deterministic domain-only jobs on the non-agent path. Reasoning jobs must persist project_id plus hermes_profile_id, validate ownership before handler effects, deduplicate within a profile, claim atomically, use expiring leases, reclaim stale leases, and preserve failure evidence across recurring reschedules.

Dispatch a claimed job only through the active profile's current stored runtime binding. Force profile routing even if ambient routing defaults to legacy or shadow. Give every recurring reasoning handler an explicit failure-reschedule policy.

Lifecycle and Readiness

Prevent startup deadlocks:

1. The domain server plans profiles and materializes multiplexer/profile files.
2. Its health gate reports materialization readiness.
3. The agent sidecar starts and reads the generated private root.
4. The supervisor probes exact profile-prefixed routes.
5. Only exact healthy bindings become active.
6. Later failures become profile-attributed failed state and are retried safely.

Initial config/materialization errors fail startup closed. Public health must not expose raw credentials or internal error detail.

If scheduled work is a product feature, enable the scheduler by default and provide an explicit maintenance/external-worker disable switch.

Verification Discipline

Use strict RED-GREEN-REFACTOR for authority, routing, and lifecycle boundaries. Minimum tests:

• runtime-ref/slug/path attacks;
• profile-prefix retention for session, chat/run, events, history, interrupt, and jobs;
• no global fallback;
• cross-business denial before network/domain effects;
• portfolio grant and delegation boundaries;
• pause/revoke/tamper behavior;
• same-kind jobs across profiles and one-execution claims;
• expired lease recovery and recurring failure evidence;
• model/secret rotation without leakage;
• backup/restore of nested profile state with secrets excluded.

Then run disposable real-runtime canaries for one-business and portfolio-plus-two-business topologies. A schema assertion, Compose parse, or mocked probe is not a runtime canary. Report environmental blockers honestly rather than synthesizing success.

Delegated Work Rule

Timeout and completion messages are not evidence. Inspect the worker transcript, actual worktree, untracked files, diff, commits, and tests. Repair and commit a coherent slice yourself or reject it; cherry-pick only after independent verification. A timed-out branch may be useful, but it is never automatically complete.

Supporting Reference

See references/runtime-dispatch-supervision-checklist.md for detailed filesystem, capability, job, startup, backup, adversarial, and canary checklists derived from a complete multi-profile implementation.

Common Pitfalls

1. Resolving a profile correctly, then discarding its runtime before transport.
2. Exporting project authority through model-visible environment variables.
3. Sharing all role keys in one readable .env.
4. Treating a persona name or free-form binding as authorization.
5. Allowing portfolio mutation because portfolio can read summaries.
6. Globally deduplicating same-kind jobs across business profiles.
7. Rescheduling a failed recurring job while erasing attempts/error evidence.
8. Disabling schedulers in the appliance while claiming scheduled dispatch works.
9. Maintaining obsolete profile/workspace backup roots after consolidating under one multiplexer home.
10. Calling mocked tests or Compose validation an end-to-end isolation canary.