How the Session Resync Process Handles Orphaned Sessions in agentsview

When agentsview performs a full resync, it preserves orphaned sessions—archived chats whose source JSONL files have been deleted—by copying them from the old database into the newly rebuilt temporary database before swapping, ensuring no historical data is lost.

The open-source agentsview project maintains a SQLite-backed index of AI agent sessions stored as JSONL files. When a full resync rebuilds this index from scratch, the system must handle orphaned sessions—historical records whose source files no longer exist on disk—without losing their searchable archive data.

The Three-Phase Orphan Preservation Workflow

The resync engine in internal/sync/engine.go implements a defensive workflow to ensure orphaned sessions survive the database rebuild.

Phase 1: Detecting and Copying Orphaned Data

After the temporary database is populated with fresh file data, the engine queries the existing database for sessions missing from disk. It calls CopyOrphanedDataFromExcluding to migrate these rows while respecting any deliberately excluded IDs:

orphaned, err := newDB.CopyOrphanedDataFromExcluding(origPath, stats.parserExcludedIDs)

This logic appears in lines 1703–1708 of the engine. The method returns the count of sessions successfully preserved and transfers them into the new database structure.

Phase 2: Recording Preservation Statistics

Once the copy succeeds, the engine records the number of rescued sessions in the sync statistics:

stats.OrphanedCopied = orphaned

This assignment occurs at lines 1727–1729. This metric propagates to the UI and API, giving users visibility into how many archived sessions were retained despite missing source files.

Phase 3: Re-linking Sub-Agent References

Orphaned sessions often contain references to sub-agent results generated during tool calls. The engine repairs these relationships only when orphans were copied:

if orphaned > 0 {
    if err := newDB.LinkSubagentSessions(); err != nil {
        log.Printf("resync: relink subagent sessions: %v", err)
    }
}

This sub-agent relinking logic is implemented at lines 1729–1735. It ensures that imported orphan rows remain fully functional with their hierarchical session graphs intact.

Error Handling and Atomicity Guarantees

If the orphan copy operation fails, the entire resync aborts to prevent data loss. The error handling at lines 1710–1716 ensures the temporary database is discarded and the original remains active. This atomic approach guarantees that users never lose their archived session history due to a partial or failed resync operation.

Triggering and Monitoring Session Resyncs

You can trigger the resync process and monitor orphan preservation through multiple interfaces.

Command Line Interface

Run a full resync from the terminal to rebuild the index and preserve orphans:

agentsview sync --full

This command invokes engine.SyncAll(), which eventually reaches the orphan-copy logic described above.

Programmatic Integration

Call the resync engine directly from Go code to handle orphaned sessions programmatically:

ctx := context.Background()
eng := sync.NewEngine(cfg)
stats, err := eng.Resync(ctx, nil)
if err != nil {
    log.Fatalf("resync failed: %v", err)
}
fmt.Printf("Orphaned sessions copied: %d\n", stats.OrphanedCopied)

HTTP API Monitoring

Query the sync status endpoint to verify how many orphaned sessions were preserved:

curl http://localhost:8080/api/v1/sync/status

The response includes the preservation count:

{
  "files_ok": 42,
  "files_failed": 0,
  "orphaned_copied": 3,
  "warnings": []
}

The orphaned_copied field corresponds to the stats.OrphanedCopied value set during the resync.

Summary

• Detection: The CopyOrphanedDataFromExcluding method in internal/sync/engine.go identifies sessions present in the old database but missing from disk.
• Preservation: Orphaned sessions are copied into the temporary database before the atomic swap, with counts stored in stats.OrphanedCopied.
• Relationship Repair: The LinkSubagentSessions method restores sub-agent references for all copied orphans.
• Safety: Error handling at lines 1710–1716 ensures failed orphan copies abort the resync without corrupting the active database.
• Visibility: Preservation statistics are exposed via CLI output, programmatic APIs, and the HTTP status endpoint.

Frequently Asked Questions

What triggers the session resync process in agentsview?

The resync process runs automatically on application startup, via the agentsview sync --full CLI command, or programmatically through the engine.Resync() method in internal/sync/engine.go. Each execution rebuilds the SQLite index from JSONL source files while preserving orphaned sessions.

How does agentsview define an orphaned session?

An orphaned session is a database record whose corresponding JSONL source file has been deleted from the monitored file system. Despite the missing source, the session data remains valuable as archived chat history, which the resync process intentionally preserves in the SQLite store.

Will orphaned sessions lose their sub-agent relationships after a resync?

No. The engine explicitly calls LinkSubagentSessions() at lines 1729–1735 whenever orphaned sessions are copied. This method repairs pointers between parent sessions and their generated sub-agent results, maintaining the complete conversation hierarchy.

What happens if the orphan copy process fails during resync?

The entire resync operation aborts immediately. The error handling logic at lines 1710–1716 discards the temporary database and retains the original, ensuring that no session data—orphaned or otherwise—is lost due to partial writes or corruption during the copy operation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}