fix(agents): recover post-update integration state

[ScriptedAlchemy]

Summary

This is the rollout follow-up to #441. The Hermes/TraceDecay architecture in #441 is intact: Hermes sessions resolve memory and LCM storage from the session workspace, project-backed sessions remain project-sharded, untethered sessions use profile-level user memory/session stores, autonomous post-turn review applies validated mutations, and TraceDecay-managed skills are exposed through Hermes's native plugin discovery and progressive tool discovery.

The v0.0.54 rollout exposed two pre-existing-state problems that could not be reproduced from a clean install:

1. Several generated prompt files had an intact TraceDecay-owned preamble and END marker but a missing START marker. Reinstall treated these files as unbalanced forever, so post-update integration refresh retried on every command.
2. A preserved historical Hermes-local sessions.db contained sessions whose original project path no longer exists. Explicit Hermes migration correctly refused to guess, but the same unresolved source also gated automatic post-update reinstall forever.

This PR makes those states recoverable without claiming user-authored text, guessing project identity, copying unscoped memory into user memory, or hiding real database failures.

Generated prompt block recovery

Managed-skill indexes and memory-digest blocks now recognize a narrowly defined orphaned generated block:

• the START marker is absent;
• exactly one matching END marker remains;
• the exact TraceDecay-generated heading and target-specific preamble remain;
• the preamble occurs exactly once before the END marker;
• no duplicate or competing marker block exists.

When all of those ownership signals are present, reinstall replaces or removes only the generated range beginning at the exact preamble. Text before and after that range is preserved. This repairs the real rollout state while avoiding a broad heading-based deletion heuristic.

Ambiguous states remain fail-closed:

• START without END;
• END without the exact generated preamble;
• duplicate START or END markers;
• repeated generated preambles;
• multiple candidate legacy target preambles.

Shared prompt files receive a two-pass uninstall: all target-slugged blocks are removed first, then the one legacy unslugged block is evaluated. This removes ordering dependence when an orphaned legacy block and a newer target-slugged block coexist.

The memory digest uses the same ownership and ambiguity rules. The generated heading/body preamble is now a single constant shared by rendering and recovery, preventing recovery logic from drifting from emitted content.

Hermes legacy session migration

The legacy migrator now has two explicit destination layouts:

• project scope: the registered project's existing profile-sharded sessions.db and tracedecay.db;
• user scope: profile-level user-sessions.db, with no project memory target.

Only sessions with provably neutral scope may enter user-sessions.db. Neutral evidence is limited to an empty selector, the explicit user selector, the exact user home, or the exact Hermes home. An arbitrary existing directory is not considered projectless. A vanished directory is not considered projectless. A Hermes plugin subdirectory is not considered projectless.

Project evidence is correlated per source session before the source store is assigned a destination. This prevents unrelated parallel or historical sessions from being flattened into one inferred project. Migration refuses:

• one session mapping to multiple projects;
• one source containing both project and projectless sessions;
• resolved project evidence mixed with unresolved evidence;
• multiple registered identities;
• registered identity collisions;
• vanished or unregistered project paths;
• malformed JSON metadata;
• syntactically valid but structurally invalid metadata;
• recognized project-attribution metadata keys with non-string values.

Deleted symlink metadata is now preserved when the removed alias can no longer be proven. A remaining registered path is not enough to silently assume that an unresolvable sibling field was merely an alias; privacy and project isolation take priority over opportunistic migration.

For genuinely projectless legacy sessions, copied session rows are normalized to project key/path user and written idempotently to user-sessions.db. The source is opened read-only and retained. Re-running migration recognizes the same logical source fingerprint and does not duplicate rows.

Legacy memory is deliberately stricter than session history. If a projectless legacy source also has a memory database, those facts are not copied to profile user memory because there is no durable proof that they are user-global. The session migration may complete, but the report now explicitly records the memory database as preserved/unresolved. Automatic reinstall prints that warning; explicit Hermes install remains strict. This prevents a successful-session message from silently implying that unscoped memory was migrated.

Automatic reinstall versus explicit migration

Automatic post-update reinstall now distinguishes migration outcomes:

• migrated/already migrated: continue;
• unresolved project evidence or intentionally preserved unscoped memory: warn, preserve the source, and continue integration reinstall;
• source open failure, integrity failure, copy failure, identity conflict, or partial migration failure: fail and keep the version marker pending.

This prevents an unresolved historical source from wedging every future TraceDecay command while retaining the important retry behavior for actual corruption or incomplete copying. Explicit tracedecay install --agent hermes remains strict and reports unresolved sources as an error so an operator cannot mistake preservation for completed cutover.

Autonomous curation boundary

This follow-up does not introduce a scheduler dry-run mode. Autonomous memory curation remains a two-phase validated mutation: proposed operations are evaluated read-only, accepted operations are then applied, and rejected operations remain audited. The read-only phase is validation, not the terminal behavior of an autonomous run.

An explicit operator preview remains useful and read-only. Destructive offline database repair, migration, garbage collection, and source-tree edits also retain their existing safety confirmations. That distinction lets TraceDecay self-improve and update/delete stale memories autonomously while preserving an audit boundary for operator-invoked destructive maintenance.

Concurrency and isolation

No process-global "active project" is introduced. Hermes runtime routing remains session-specific, so parallel Hermes sessions may use separate projects or separate worktrees without overwriting one another's routing context. Sessions in the same project intentionally converge on the same project shard, where database transactions and idempotent receipts provide coordination. Generated prompt updates remain ownership-scoped and ambiguity-safe.

Tests

Local verification on the final diff:

• Hermes migration module: 26/26 passed.
• Automatic reinstall outcome tests: 2/2 passed.
• Memory digest tests: 15/15 passed.
• Managed-skill target tests: 23/23 passed.
• Generated Hermes plugin checks: 38/38 passed.
• Stock Hermes integration: 24/24 passed against upstream 9dd9ef0ec99a87f078f7272b4323df5440b4b3f9.
• Workspace structured diagnostics: 0 errors, 0 warnings.
• cargo clippy --all-targets -- -D warnings: passed.
• cargo fmt --all -- --check: passed.
• git diff --check: passed.
• Conventional commit validation: passed.

The Hermes harness verifies plugin loading, memory provider discovery, context-engine activation, project isolation, untethered user scope, exact-session LCM ingestion, structured tool correlation, managed-skill discovery, progressive tool discovery, graph dispatch, and clean Hermes doctor output.

Rollout

After merge, release-plz should publish the follow-up release. The released artifact must then be installed, integrations reinstalled noninteractively, and both TraceDecay and Hermes restarted. Live verification should confirm that the preserved ambiguous legacy source produces a warning without a reinstall loop, project sessions remain in their project shards, untethered sessions use profile user scope, and the generated prompt markers remain balanced and idempotent.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 2da33b4

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR