State and Files¶

Omni stores tools, dotfiles, and host settings. Agent desired and runtime state belongs to APM.

Agent state¶

APM owns the global manifest, lockfile, package cache, marketplace metadata, and deployed agent files:

~/.apm/apm.yml — desired package/runtime declarations.
~/.apm/apm.lock.yaml — resolved dependency state.
~/.apm/marketplaces.json — marketplace registry/cache.
APM target directories and agent configuration files under $HOME.

Omni does not maintain a parallel deployed skill/plugin store. Its optional host template is omni/apm.yml under the OS user config directory (~/.config/omni/apm.yml on Linux). omni agents sync copies that template over ~/.apm/apm.yml before invoking APM install. A template generated by omni agents migrate --write begins with # omni:agents-migration:v1; migrate refuses to replace an existing template whose first non-empty line is not that exact marker.

Installed package manifests are ownership evidence for bundled MCP/LSP children. A package declaration is authoritative over an identical top-level child; a different definition or multiple package owners is a blocking conflict. If a package has not been installed and its manifest is unavailable, sync permits a package-only first install but blocks a template that also declares standalone MCP/LSP services rather than guessing ownership.

Manifestless skill packages use strict, fail-closed evidence from the APM lock and installed module; Omni creates no replacement state file or synthesized package metadata. See Package-owned MCP and LSP for the supported boundary and Doctor behavior.

Omni state¶

Omni configuration remains in settings.json and optional settings.d/*.json fragments. SQLite state lives under the normal Omni data directory. Dotfiles remain owned by Omni and tools remain owned by their configured providers.

agents-template-state in the state directory ($OMNI_STATE_DIR, or $XDG_STATE_HOME/omni by default) holds the hash of the live APM manifest as of the last sync that applied the host template. Sync compares it against ~/.apm/apm.yml to detect edits made outside Omni and refuses to overwrite them without --force-template.

Every selected legacy owner is snapshotted into a verified normalized wrapper under:

<Omni state>/agents-migration/bundles/<sha256>/
  apm.yml
  runtime/...
  skills/...
  hooks/...
  agents/...
  commands/...

They are content-addressed local APM package inputs, not deployed client state or a second ownership database. The hash covers the normalized manifest and each copied file's destination, content, and executable mode. Source apm.yml metadata and supported dependency semantics are preserved while bundle-relative paths are rebased into the wrapper. Unsupported native extensions or dependency forms block migration.

Migrate publishes wrappers atomically before updating the marked template and never deletes stale wrapper hashes. The live manifest may still reference an older hash until sync applies the new template. Rerun migrate after the copied source snapshot changes to publish a refreshed wrapper; sync validates the referenced hash before APM runs.

Pre-APM hosts keep their old declarations in a .omni-apm-migration-backup-* snapshot directory committed in the dotfiles repo, next to the real settings.json. It is read-only input for omni agents migrate. paths.json maps original owner roots to copied snapshot paths; a copied marketplaces.json may supply marketplace/catalog evidence. Migration uses only this snapshot evidence. It does not read the live APM cache, apm.lock.yaml, the network, or APM source.

Migrate and sync acquire the same write lock for the canonical template. Sync then acquires the global APM workspace lock and holds both while it classifies package-owned children, rechecks template/module identities, materializes the exact candidate bytes that passed preflight, and invokes APM. A changed canonical template is rejected rather than reread after validation. No ownership failure writes ~/.apm/apm.yml, updates agents-template-state, registers a marketplace, or runs APM. Direct external apm processes do not honor Omni's workspace lock and are unsupported while sync runs.

omni doctor --fix may remove an exact standalone MCP/LSP duplicate from the canonical template only. It preserves supported template symlinks and edits the resolved regular target atomically without re-encoding the YAML. Dry-run writes nothing. The fixer holds the template lock before the APM workspace lock and rechecks the template, live manifest, lockfile, module-manifest hashes, symlink chain, and target identity before replacement. Conflicts, multiple owners, unsupported source layouts, changed inputs, and unsafe symlink layouts leave the whole repair unchanged. Doctor never repairs the live manifest, lockfile, installed module manifests, package cache, or harness configuration.

Environment variables¶

HOME, XDG_DATA_HOME, XDG_STATE_HOME, OMNI_STATE_DIR, and provider-specific environment variables control Omni paths and provider behavior. APM resolves its own runtime environment.

Cache contents¶

Omni caches discovery and provider metadata, and the last answer apm outdated gave, so the Agents view can show known updates before a fresh check finishes. APM owns package and marketplace cache contents under ~/.apm/.