sessionFlow v1.1.0

sessionFlow v1.1.0

The continuation bundle no longer lets a clock decide what the work was.

v1.1.0 is a correctness release. It has no new commands and no new providers.
What it changes is what the product says — about which session a piece of work
stopped in, which WorkThread a repository's work belongs to, and what a provider
can actually do. Several of those statements were wrong before this release, and
two of them were wrong in a way that would have made an agent act on the wrong
history.

Nothing is uploaded anywhere; all indexing, searching and context restoration
happens locally.

---

Highlights

• One canonical session order. The handoff order, the most recent activity
  and the goal-conditioned conclusion are now three separate things, and only
  the handoff order decides what the bundle leads with. A session that was merely
  re-scanned can no longer take the headline from the session the work was handed
  to, and when the clock and the handoff order disagree the bundle says so.
• Ambiguity is reported, not resolved. A repository with more than one active
  WorkThread no longer gets one picked for it. Every surface returns the
  candidates; the commands that act refuse and tell you how to choose.
• A capability matrix that matches the adapters. voyager verify --matrix
  previously reported ZCode as supporting native resume while the adapter set
  can_resume = False.
• A corrupt or locked ZCode database is no longer a deleted one. Unreadable
  is not absent: history is retained, and the reason is reported.
• The bundle prefers evidence to assertion. Under budget pressure it used to
  keep an assistant's self-report and drop the repository snapshot.

---

Continuity correctness

Three concepts, kept apart (D20, #15)

Two compilation paths used to disagree about a WorkThread's sessions — one
ordered them by updated_at, the other by thread_sessions.ord — and both chose
the "latest" session by timestamp. The result: a session whose provider file was
re-scanned could take the headline away from the session the work had actually
been handed to, and the two formats could tell different stories about the same
data.

concept	source	role
thread order	thread_sessions.ord	the one session order; the persisted handoff sequence
latest activity	updated_at	reported as provenance, never used to select
relevant conclusion	goal + evidence	its own mechanism, unchanged

canonical_session_order() is now the single source of the order, shared by both
renderers, the handoff engine, the launcher and the bridge. The headline is the
last row in that order — the end of the handoff chain — and the bundle names the
rule that chose it. Where the clock and the handoff order disagree, the bundle
states the disagreement rather than silently picking one.

A session's earlier work survives (#14)

The bundle used to keep only each session's last assistant message, so a
session whose final turn was a progress note lost the proposals, constraints and
open items it had raised earlier. Selection now keeps several per session, labels
them ([proposal], [open]) and never presents them as verified fact.

A conclusion is not verified state

The section titled "Current verified state" held the newest session's last
assistant message. It is now "Latest assistant conclusion", read as what was
said rather than as what is true, and the older-session section no longer marks
anything "superseded" — a newer session is not automatically more correct.

---

Multi-WorkThread ambiguity safety (#17)

A repository can carry several active WorkThreads at once. The core was already
of two minds about this: the session-start hook and the MCP surface refused to
choose, while current_work, continue_context, voyager continue and
voyager switch all quietly took the newest. voyager thread reopen had even
been printing "automatic continuation will now report AMBIGUOUS and refuse to
choose" — the CLI contradicted its own warning.

auto.resolve_work_thread() is now the single resolver behind all of them.
Recency may suggest a default; it never establishes intent.

situation	behaviour
more than one active thread	thread_ambiguous: true, every candidate listed (id, title, updated_at, goal), newest first; the returned one is labelled a default
exactly one / none	unchanged, nothing added
explicit thread_id	honoured, including one from another repo (thread_out_of_scope)
thread_id that does not exist	thread_not_found, and no fallback to another thread
voyager continue / voyager switch	exit 2, print every candidate and --thread

Additive only: bridge schema stays v1.

---

Provider data reliability

• Unreadable is not absent. A ZCode database that is corrupt, locked or
  permission-denied used to be dropped by discovery, which made the scan conclude
  that every one of that provider's sources had vanished and mark all its
  sessions SOURCE_MISSING. Sources are now classified as absent / readable /
  unreadable / not-a-ZCode-database; "present but unusable" keeps the sessions
  live and the reason is reported. When the database becomes readable again, the
  next scan re-indexes normally.
• The Codex SessionStart relay hardcoded C:\Python314\python.exe and passed
  its payload through the console code page. On any other machine the hook
  produced empty output, and a non-ASCII repository path was mangled. The
  interpreter is resolved at run time and the payload is forwarded as bytes.
• Signal-word matching no longer confuses optional with option or
  have nothing with have not, without breaking CJK text adjacent to a
  keyword.

---

Capability reporting

voyager verify --matrix declared ZCode's native_resume as SUPPORTED while
zcode.py sets can_resume = False, so the matrix advertised a resume path that
could not be built. The adapter is now the authority for that dimension, and
voyager doctor explains every dimension from the same resolver the matrix
reads — so the two cannot drift apart again.

The README's platform table now says explicitly that its Resume column names
the command Voyager will run, not a verified outcome.

---

Context budget and provenance

• Budget packing kept a section's priority and its render order as one thing, so
  trimming a bundle also reordered it. They are separate now: priority decides
  what survives, the compiler decides where it appears.
• The keep-order put an assistant's self-report above the repository snapshot,
  files, commands and errors. Evidence now outranks assertion.
• _priority_of matched by prefix, so ## Goal captured
  ## Goal-ranked evidence and gave the evidence section the goal's priority.
• When a tight budget drops a conflicting proposal, the drop is reported rather
  than leaving a silently single-sided summary.

---

Verification status

Kept apart on purpose — nothing below is promoted.

what	level	evidence
Core suite	PASS	1072 passed, 20 skipped, 1092 collected; CI 10/10 on Ubuntu and Windows, Python 3.10–3.13
Continuation ordering, ambiguity, budget, capability truth	UNIT + INTEGRATION VERIFIED	the suites named in CHANGELOG.md
Cross-agent continuation through DSH	LIVE VERIFIED (synthetic index)	six real DSH turns, real model, real core — dsh-sessionflow/docs/p8-live-verification.md
Continuation from real provider session files	LIVE VERIFIED (real files, fixture scenario)	3 real Codex rollouts + 3 real Claude Code sessions copied into an isolated HOME and parsed by the real adapters, then continued by a real agent — dsh-sessionflow/docs/p9-live-verification.md
Hook firing (Claude / Grok / Codex)	ZERO_TOUCH_LIVE_VERIFIED	see the verification table in README.md
Native resume	NOT VERIFIED	no resume has been exercised end to end on any provider. The commands exist and are wired up; that is not the same thing

---

Compatibility and upgrade notes

• No breaking changes. Bridge schema_version stays 1; the six DSH tool
  contracts are unchanged; no CLI command was removed or renamed.
• Every new field is additive. A client that ignores unknown keys needs no
  change.
• voyager continue and voyager switch now exit non-zero when a repository has
  more than one active WorkThread and no --thread was given. Scripts that
  relied on the newest thread being chosen should pass --thread explicitly.
• The bundle's section headings changed (## Latest assistant conclusion,
  ## Other sessions' conclusions). Anything matching the old strings — a
  parser, a saved prompt, a test — needs updating.
• The index is not migrated destructively; the schema change is additive.

---

Known limitations

• Native resume is not verified. codex, claude, dsh and grok declare
  a resume path and the adapter builds the command; none has been observed
  resuming a session end to end. zcode, cursor, kiro and antigravity
  report no resume path at all, and the matrix now says so.
• Provider capability variance is unchanged from v1.0.0: agents expose
  different levels of persistence detail, and file-edit tracking is stronger on
  some than others.
• The live verification used synthetic and real-format fixtures, not a real
  project of yours. What that proves is the pipeline; it does not claim anything
  about your specific session files.
• Distribution is still GitHub source install. PyPI and npm publication remain
  deferred: the voyager name on PyPI belongs to an unrelated library, so
  pip install voyager installs the wrong project.

---

Changelog: CHANGELOG.md.
Decisions: docs/DECISIONS.md — D20 covers the ordering rule.
Plugin: [dsh-sessionflow](https://...

sessionFlow v1.0.0

sessionFlow v1.0.0

Search. Understand. Continue. Switch agents without losing context.

SessionFlow v1.0.0 is a production-ready cross-agent continuity layer. It unifies session history from multiple AI coding agents into a single searchable index, restores context mid-task, and hands off work between agents without losing reasoning or progress.

Nothing is uploaded anywhere — all indexing, searching, and context restoration happens locally on your machine.

---

Highlights

• Unified agent timeline: Merge sessions from 8+ agent platforms (Codex, Claude Code, ZCode, DSH, Cursor, Kiro, Grok, Antigravity) into one queryable index.
• Full-text search: Find commands, code changes, or reasoning across all agent history — CJK substring search supported.
• Context restoration: Resume any session from where you left off with voyager continue <thread> or restore via MCP/DSH tools.
• Cross-agent handoff: Seamlessly transition work between different agents using voyager switch and voyager handoff.
• Local-first privacy: No cloud upload required; all data stays on your machine.
• DSH plugin available: Six standardized tools for agent-side query access (see DSH Integration).

---

Supported Agents and Workflows

First-class support (native adapters)

• Codex: Rollout JSONL format with thread correlation.
• Claude Code: Project JSONL with file-version chain tracking.
• ZCode: SQLite-based session storage.
• DSH: Compressed JSONL sessions via zstd transport.

Good-faith support (best-effort adapters)

• Cursor: JSON project files.
• Kiro: Event-based session logs.
• Grok: Agent conversation records.
• Antigravity: Custom runtime sessions.

Note: Provider capabilities differ in their native persistence models. sessionFlow normalizes these differences while preserving provenance. Where an agent's native interface supports it, resume commands are executed automatically; otherwise, users receive actionable hints about how to manually restore context.

---

Search, Timeline, and Continuity

Full-text search

Search across all normalized events:

voyager search "sqlite migration"

Supports:

• CJK substrings (中文搜索)
• File path matching
• Command history lookup
• Context snippet extraction

Timeline per repository

See what happened to your project over time:

voyager list --repo my-project

Shows:

• Session ID, provider, timestamp
• Message/tool counts
• Titles extracted from session metadata

Context restoration

Resume any session directly:

voyager continue <thread-id>

Or restore context inline:

voyager show <thread-id> --json | ...

Cross-agent handoff

Move work between agents:

voyager handoff claude --from codex

Uses lease-based concurrency control to prevent conflicting writes when multiple agents access the same workspace thread.

---

Reliability and Safety

Read-only by default

All core queries (search, recent, session, current_work) are read-only. The only write operation (merge) persists explicit user actions like creating or updating WorkThreads.

Transactional repairs

The voyager doctor --fix command runs a read-only diagnostic first, then applies only whitelisted repairs (SAFE_FIXERS). Repairs are:

• Transactional: All-or-nothing per repair batch
• Idempotent: Safe to re-run after failures
• Dry-run enabled: Test before applying changes

Empty-state UX

When no agent sessions are detected, sessionFlow shows clear error messages with:

• Helpful hints about supported providers
• Commands to run synthetic demo data (voyager demo)
• Links to documentation for extending support to new agents

No tracebacks, no confusing stack traces — just actionable guidance.

---

DSH Integration

The DSH plugin (dsh-sessionflow) exposes six standardized tools to any DSH-connected agent:

1. sessionflow_search: Full-text search across all sessions
2. sessionflow_recent: Get most recent sessions from last N hours/days
3. sessionflow_session: Retrieve full details of a specific session/thread
4. sessionflow_current_work: Identify active/in-progress threads
5. sessionflow_continue_context: Restore context from a prior session
6. sessionflow_merge: Merge work across multiple session sources

Usage

Install the plugin once:

dsh plugin --profile <profile> install HarryHeYu/dsh-sessionflow

Agents can then use natural language to discover and continue past work:

"我之前这个项目做到哪了？" → sessionflow_current_work
"继续这个会话" → sessionflow_continue_context <id>
"帮我合并 codex 和 claude 的上下文" → sessionflow_merge

Bridge Schema v1: Versioned contract between core and plugin. Additive-only changes preserve compatibility; schema never breaks consumer implementations.

---

Installation

Pipx (recommended)

Isolated CLI installation without virtualenv management:

pipx install "voyager[all] @ git+https://github.com/HarryHeYu/sessionFlow.git"

Components:

• Core: pipx install "voyager @ git+https://github.com/HarryHeYu/sessionFlow.git"
• DSH support: pipx install "voyager[dsh] @ git+https://github.com/HarryHeYu/sessionFlow.git"
• MCP server: pipx install "voyager[mcp] @ git+https://github.com/HarryHeYu/sessionFlow.git"

Direct pip

User-level installation:

pip install "voyager[all] @ git+https://github.com/HarryHeYu/sessionFlow.git"

From source

For development or custom builds:

git clone https://github.com/HarryHeYu/sessionFlow
cd sessionFlow
pip install -e ".[all]"

Verify installation

voyager --help
voyager demo           # Synthetic tour, no agents needed
voyager list           # Discover existing sessions

---

Known Limitations

Provider capability variance

Different agents expose different levels of persistence detail:

• Native session IDs may not map perfectly across providers
• Some agents track file edits better than others
• Resume command support depends on provider capabilities and observed evidence

Zero-touch continuity

Automatic context recovery works best when:

• The agent natively supports session restoration commands
• Sufficient evidence exists in the session logs to identify correct state
• Provider-specific constraints are documented in adapter implementations

Where zero-touch isn't available, sessionFlow provides clear manual restoration hints.

Platform-specific behavior

Some features behave differently across operating systems:

• Windows uses PowerShell for certain Codex operations
• File path normalization differs between Unix and Windows
• Unicode handling is tested on all platforms but may require environment configuration in rare cases

Distribution strategy

sessionFlow v1.0.0 is distributed primarily through GitHub source installation. Package manager publishing is intentionally deferred:

• PyPI: Name undecided (existing voyager package taken); target future release
• npm (dsh-sessionflow): Publication deferred by design; current distribution via GitHub plugin installation

This allows the team to validate the stable API surface before committing to package manager ecosystems.

Data retention

sessionFlow preserves historical sessions even when their source provider becomes unavailable (marked as SOURCE_MISSING). This prevents accidental data loss during provider migrations or tool replacements. However, deleted session files from local agent directories will be reflected in future scans unless explicitly archived.

---

Changelog: See CHANGELOG.md for full release history including RC1 and RC2 improvements.

Architecture: Learn more about the bridge protocol and adapter architecture in docs/architecture.md.

Post-1.0 plans: Roadmap and upcoming improvements tracked in docs/POST-1.0.md.

sessionFlow v1.0.0-rc2

sessionFlow v1.0.0-rc2

Unified AI Coding Agent Session Management

Release candidate. Tag: v1.0.0-rc2.

This RC is about first-time-user experience and open-source plumbing —
no core-semantics changes: the bridge stays at schema v1, and the
verification, timeline and doctor models are untouched.

Highlights

• voyager demo — explore sessionFlow with zero agents installed: a
  synthetic 4-agent / 1-WorkThread index (implement → review → debug →
  harden, one "authentication flow" working day) at ~/.voyager/demo.db,
  separate from your real index. Every follow-up command the verb prints
  is regression-tested.
• README with a real demo — dual-path Quick Start (Fast Demo / Real
  Usage), product screenshots and a typed-terminal demo GIF, all
  generated from the synthetic index; a use-cases page (lost context /
  agent switching / engineering memory).
• Release automation — pushing a v* tag now runs the test suite on
  the tag tree and opens the GitHub Release (notes from
  docs/releases/<tag>.md, rc tags marked pre-release). The Windows CI
  matrix covers Python 3.10–3.13.
• Contributor plumbing — issue templates, PR template, a contributing
  guide documenting the O1–O6 architecture rules (single source of truth,
  evidence honesty, the safe-repair allowlist, versioned bridge), a
  security policy and a code of conduct.

Verification

Automated compatibility:

• 974 tests passing (full gate)
• bridge contract verified against the pinned core
• release workflow itself validated by this tag's run

Live verification:

• unchanged from rc1 and still machine-local: only providers with
  persisted evidence in this machine's verification_events table are
  reported LIVE/zero-touch; no unsupported live claims

Pure local: no accounts, no cloud, no telemetry.

Install

git clone https://github.com/HarryHeYu/sessionFlow
cd sessionFlow
pip install -e ".[all]"
voyager demo            # 2-minute synthetic tour, no agents needed
voyager scan            # then index YOUR agents

PyPI packaging is prepared but not yet published.

sessionFlow v1.0.0-rc1 — Unified AI Coding Agent Session Management

sessionFlow v1.0.0-rc1

Unified AI Coding Agent Session Management

Release candidate. Tag: v1.0.0-rc1.

Features

• Unified indexing across AI coding agents — Codex, Claude Code, DSH
  (DeepSeek Harness), ZCode, Grok, Cursor, Kiro and Antigravity, normalized
  into one local SQLite index. Read-only against provider files.
• Cross-agent full text search — FTS5 (trigram) over every indexed
  session, with structured filters (provider, repo, time).
• Timeline and provenance tracking — one canonical WorkThread timeline:
  derived facts (attachments, handoffs, checkpoints, pending resolution)
  and persisted transitions (source missing/returned/archived, thread
  status), each event with provenance and deterministic ordering.
• Session continuation and handoff — continue / switch / handoff
  / merge compile a tiered context (authoritative L0 thread state +
  bounded L1 window + retrieval hint) for the next agent, with cross-agent
  lease coordination.
• Retention and historical lifecycle management — a vanished provider
  source retains the normalized history (searchable, exported, on the
  timeline) instead of deleting it; explicit archiving marks
  ARCHIVED_CANONICAL.
• Doctor diagnostics and safe repair — read-only diagnosis with an
  audited repair boundary: only derived-state repairs (FTS rebuild, stale
  cache) run under --fix, each transactional, idempotent, with a dry-run
  plan.
• DSH bridge integration — versioned JSON bridge (schema_version 1)
  consumed by the dsh-sessionflow
  plugin (six tools), plus an MCP server.

Architecture

AI Agents
(Codex / Claude / DSH / ZCode / Grok ...)
        |
        v
sessionFlow Core
        |
        +-- Index
        +-- Timeline
        +-- Continuity
        +-- Verification
        +-- Doctor
        |
        v
Bridge API
        |
        v
dsh-sessionflow plugin

See docs/architecture.md for the full map.

Verification

Automated compatibility:

• 970+ tests passing (full gate)
• bridge contract verified against the pinned core (O6.5 consumer gate)
• plugin compatibility verified (npm test / npm run build green)

Live verification:

• only providers with persisted evidence in this machine's
  verification_events table are reported LIVE/zero-touch; the doctor, the
  verify CLI and this README all cap claims at declared capability until
  evidence exists
• no unsupported live claims: providers without a startup surface (e.g.
  DSH) are reported NOT_FOUND for startup verification regardless of other
  capabilities

Pure local: no accounts, no cloud, no telemetry.

Install

pip install voyager          # once the PyPI release is published
voyager scan && voyager doctor

See the README for the
full quickstart and docs/demos for real command transcripts.