Maintenance & Recovery

omegon-maintain is the release-coupled recovery companion. It remains independently runnable when the normal TUI, agent loop, provider setup, project configuration, plugins, extensions, MCP, mutable packs, memory, lifecycle, or orchestration state is broken.

It is a bounded data-inspection and recovery tool, not a second agent harness, generic repair shell, package manager, or mode of omegon.

Start With Read-Only Evidence

omegon-maintain --json identity
omegon-maintain --json doctor
omegon-maintain --json composition inspect
omegon-maintain --json release inspect

identity reports the artifact, protocol, limits, target, and compiled exclusions without loading normal runtime roots.
composition inspect reports the compiled maintenance profile, not a live contribution graph.
doctor runs bounded structural checks; unavailable evidence can produce a degraded result.
release inspect inspects adjacent package metadata only. Use offline verification for signed release evidence.
release verify reports the verified Sigstore workflow identity and validates package plus resident locks before optional inventory.

Stable Automation Contract

With --json, normal termination writes exactly one JSON object to stdout; logs and progress go to stderr. Status is success, failure, ordegraded.

Exit	Meaning
`0`	All requested work settled successfully.
`1`	Definite failure, refusal, invalid input, unsupported operation, or timeout before dispatch.
`2`	Degraded or partial evidence, possible-dispatch timeout, unknown settlement, or audit/output settlement failure.

Do not treat exit 2 as success or blindly retry a mutation. Reconciliation may reuse the same request UUID only for the exact same command fingerprint.

Roots, Deadlines, and Dry Runs

--workspace, --home, and --config-home require existing absolute directories.
Project contribution, selected-session, and resource operations require an explicit --workspace.
User contribution listing uses --scope user without --workspace.
Every mutation and mutation dry run requires --deadline. Durations use an unsigned integer plus ms, s, or m, with a ten-minute maximum.
Final root symlinks, aliased roots, and group/other-writable mutation roots are rejected.

--dry-run does not dispatch the requested mutation, but it may bootstrap maintenance-owned state, create or acquire lock files, and append a dry-run audit record.

Contributions

omegon-maintain --json \
  --workspace /absolute/path/to/project \
  contribution list --scope project

omegon-maintain --json \
  --workspace /absolute/path/to/project \
  contribution inspect plugin:formatter --scope project

omegon-maintain --json --dry-run --deadline 30s \
  --workspace /absolute/path/to/project \
  contribution disable plugin:formatter --scope project

omegon-maintain --json --deadline 30s \
  --workspace /absolute/path/to/project \
  contribution disable plugin:formatter --scope project

Selectors use <kind>:<id>, where kind isextension, plugin, skill, prompt,catalog, or workflow. Listing gives invalid filesystem names an opaque entry:sha256:<hex> selector instead of interpreting them. IDs match[A-Za-z0-9][A-Za-z0-9._-]127.

Disable affects future activation; it does not stop a running process. Quarantine first settles the deny, then atomically moves a real entry on the same filesystem or unlinks a contribution symlink without opening or modifying its target:

omegon-maintain --json --deadline 30s \
  --workspace /absolute/path/to/project \
  contribution quarantine plugin:formatter --scope project

Restore, enable, purge, recursive deletion, and copy-delete fallback are not available.

Sessions

omegon-maintain --json \
  --workspace /absolute/path/to/project \
  session list

omegon-maintain --json \
  --workspace /absolute/path/to/project \
  session inspect <session-id>

omegon-maintain --json --dry-run --deadline 30s \
  --workspace /absolute/path/to/project \
  session quarantine <session-id>

omegon-maintain --json --deadline 30s \
  --workspace /absolute/path/to/project \
  session quarantine <session-id>

Selection requires one exact session and workspace identity. Maintenance prefers semantic catalog framing and falls back to a legacy pair only when no catalog exists. Quarantine identity-pins the selected framing, installs resume-deny authority, and preserves all session bytes. It does not rewrite stores, synthesize events, change completion state, or semantically repair a conversation.

Semantic Store Recovery

Authority events and referenced content blobs are durable truth. Corrupt, unsupported, missing, or identity-mismatched required data fails closed.
A catalog is required when authority exists. Missing or stale catalog identity is fatal rather than a reason to load compatibility JSON.
Host-state checkpoints and observation ledgers retain their own authority. Malformed or torn required records fail closed.
Projector-owned transcript, provider-history, frontend, and compaction outputs are derived. A proven corrupt chunk may be quarantined and rebuilt from validated authority under the projector lock.
Audit, journal, telemetry, UI state, and presentation exports may report degradation but never repair or replace semantic authority.
Legacy pairs are one-way import sources. Once a mixed base is materialized, stale or missing pair bytes cannot affect semantic resume.

A semantic save that succeeded before a still-required legacy-pair publication failed is reported as partial_publication; semantic durability is not rolled back. There is no maintenance or runtime rollback selector that makes a compatibility file authoritative.

Invocation Mutation Fences

If a mutating invocation may have reached its owner but acknowledgement or settlement cannot be made durable, Omegon records independent emergency fence evidence and denies later mutations with the same declared domain and key. This is an unknown-settlement safety condition, not an ordinary tool failure. Do not delete or edit fence files and do not blindly retry the mutation.

Omegon also rejects reuse of a stable call ID when its original mutating invocation remains unknown and did not persist idempotency or exact owner-enforced deduplication. This check spans prior turns and cannot be overridden by newer contribution metadata. A safe-retry scheduler is not currently exposed; verify owner state or use an audited reconciliation path instead.

Provider retry is a different mechanism: it repeats an inference request before a completed tool call is dispatched. Provider backoff never authorizes resending a mutation whose owner completion is unknown.

The current omegon-maintain release does not inspect, reconcile, or clear runtime invocation fences. Clearing requires deterministic owner reconciliation or a future explicit, audited operator recovery action; session quarantine does not clear these records.

Native /status reports current composition and lifecycle diagnostics, not a ledger of historical unknown invocations or mutation fences. No supported runtime or maintenance command currently lists, reconciles, or clears those records.

Runtime Ownership Records

omegon-maintain --json \
  --workspace /absolute/path/to/project \
  resource list

omegon-maintain --json --dry-run --deadline 30s \
  --workspace /absolute/path/to/project \
  resource prune-stale

omegon-maintain --json --deadline 30s \
  --workspace /absolute/path/to/project \
  resource prune-stale

Pruning removes only records proven stale by heartbeat, boot, PID, and process-start evidence. It never kills a process. Legacy, malformed, clock-skewed, or incomplete records remain inspect-only or unverifiable.

Audit Evidence

omegon-maintain --json audit inspect
omegon-maintain --json audit verify

Audit verification checks structural hash-chain continuity. It is not authenticity proof against an attacker who can rewrite all user-owned maintenance state.

Offline Release Verification

omegon-maintain --json release verify \
  --archive /absolute/path/omegon-<version>-<target>.tar.gz \
  --manifest /absolute/path/omegon-<version>-<target>.tar.gz.manifest.json \
  --bundle /absolute/path/omegon-<version>-<target>.tar.gz.manifest.sigstore.json

All operands must be absolute regular files. Verification performs no discovery or download, and streams the archive without extracting or executing it. Compiled policy checks repository, workflow, issuer, and tag identity while the signed manifest binds the archive digest, provenance, target, version, commit, and both executable identities.

Not Implemented

There are no fix, repair, clean, update, orrollback aliases. Maintenance does not edit project source/configuration, run hooks or probes, kill processes, repair conversation semantics, or discover, download, install, activate, switch, or roll back releases.