Skip to content

sessionFlow v1.3.0

Latest
Latest

Choose a tag to compare

View all tags
@HarryHeYu HarryHeYu released this 20 Oct 14:52
· 5 commits to main since this release
v1.3.0
b38f0b2

sessionFlow v1.3.0 — Release Notes

Released 2026-10-20. Install:

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

Verify with voyager --version — it must print 1.3.0.

Voyager is not on PyPI. The voyager name there belongs to an unrelated
nearest-neighbour search library; a bare pip install voyager installs the wrong
project. Always use the @ git+… form.

The headline

A continuation reference you can actually check.

Until now a bundle told you which session a claim came from, and stopped there.
Re-checking it meant opening the transcript and squinting. v1.3.0 names the event,
and answers the question programmatically:

$ voyager evidence verify codex:01ab… 3 c71c180a
MATCH  the event at seq 3 is the one the reference named
  session : codex:01ab…
  found   : seq 3  #c71c180a
  cited   : seq 3  #c71c180a
  file    : same size and mtime as when it was indexed (not proof of identical
            bytes; see `voyager evidence` limits in docs)

  MATCH means the indexed event is the one the reference was made from.
  It does not mean the claim it carries is true.

Five outcomes, one per exit code, so a shell or CI can branch on them:

Status Exit Meaning
MATCH 0 the event at that position is the one the reference cited
MISMATCH 1 the position holds different content — the transcript was rewritten under the reference
NOT_FOUND 2 the session or that event no longer exists
UNVERIFIABLE 3 the reference names no digest, so only the position was checked — and a position is exactly what a mid-transcript edit renumbers
INVALID_REFERENCE 4 the reference is malformed

--json emits a stable object with the same fields plus source_available, so a
consumer can require both a content match and a live source.

voyager show now prints #seq/digest on every event line, so a reference cited
by a bundle resolves through the CLI without comparing two windows by eye.

What MATCH does not mean

MATCH says the indexed event is the one the reference was recorded from. It
does not say:

  • that the claim is true — no mechanism here decides that;
  • that the transcript was not tampered with — the fingerprint is 8 hex characters
    of SHA-256 over the event's identifying fields, compared pairwise. It detects
    accidental drift, and anyone who rewrites a transcript can recompute it;
  • that the original file is byte-identical — mtime/size are compared, and a
    touch shows as changed while an edit that preserves the size shows as
    unchanged.

v1.3.0 core improvements

  • Verifiable Evidence References — · seq N · #digest on every tool
    observation and every assistant claim in a bundle, plus voyager evidence verify to check one.
  • Claim-level event attribution — a claim names the message that made it, and
    the contradicting tool result keeps its own reference, so the two can be read
    against each other instead of being merged by recency.
  • Fingerprint-based consistency checks — a canonical JSON fingerprint
    (sha256-8hex-json-v1) over kind, content, command, tool_output,
    tool_call_id and exit_code. An exit code that flips 1 → 0 with the
    output text unchanged is caught; before this release it was not part of the
    fingerprint at all.
  • Source metadata status — the scanner has recorded mtime and size per
    source since forever and nothing read them back. They are now compared and
    reported, with their limits stated on every path.
  • Handoff evidence preservation — the context package written by
    voyager continue --out carries the reference on the claim it hands over. It
    was being dropped at the last step, which would have made the whole chain
    decorative on the path users actually take.
  • Test isolation hardening — the suite now refuses to run when discovery
    would reach real agent data, instead of relying on every test remembering to
    redirect. Import-time path capture is proven safe by a subprocess test that
    controls import order.

Everything else since v1.2.0

  • Reading a missing index no longer fabricates an empty database and answers
    "0 results" — which read as "you have no data" when the truth was "there is
    no index here"    . A typo'd --db now fails honestly.
  • voyager_continue gained thread_id, so a caller told "pick one" can actually
    pick one; and with no WorkThread at all it now agrees with the CLI instead of
    answering "nothing to continue" where the CLI compiled a bundle.
  • The dashboard shows a continuation preview per WorkThread, the sessions with
    their tool calls and exit codes, and the exact voyager continue --thread <id>
    to run — all read-only, with the ambiguity named rather than resolved.
  • voyager_switch no longer says "no active WorkThread" for a repo that has two.

Compatibility
Bridge schema 1, unchanged
Plugin v1.1.0 compatible as-is — 54 tests pass, and the plugin does not parse bundle text
v1.2.0 index opens with no migration; reads change no row and no schema object
v1.2.0 bundles readable. They carry no fingerprint, so evidence verify answers UNVERIFIABLE and offers the digest to adopt rather than inventing one
Downgrade safe for this release: v1.2.0 ignores the one index v1.3.0 adds

Breaking changes: none. All additions are additive — a new subcommand, new
optional JSON fields, and extra tokens appended inside existing bundle lines.
No schema change, no table added, no second event store.

Known limitations

  1. No automatic fact-checking. Nothing decides whether a historical claim is
    correct. The bundle hedges ("read as what it said rather than as verified
    fact") and every verify path states MATCH is not truth.
  2. The fingerprint is not a signature — see above.
  3. No source content hashing. mtime/size only.
  4. (session, seq) survives a re-scan and an append, not an edit in the middle
    of a transcript.     The fingerprint is what catches the latter, by reporting
    MISMATCH rather than silently re-pointing.
  5. Provenance is event-level, not claim-level. A reference says which
    message     said it; it does not extract the proposition and cite it separately.
  6. Unicode is not normalised in the fingerprint, so NFC and NFD spellings of
    the same text hash differently. A false MISMATCH is the safe direction.
  7. evidence verify is CLI-only. The JSON output is the intended machine
    surface; no API/MCP wrapper was added because nothing consumes it yet.
  8. The dashboard filter is snapshot-scoped by design; whole-index search is
    voyager search.
  9. Native resume and model-driven tool selection are not verified end to end.
    Both need paid providers.
  10. The SQLite concurrent-index flake remains unproven — not reproduced in
    bounded re-runs, and deliberately not papered over with sleeps or retries.

Upgrading

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

No migration runs. Your index is read as-is: no rows change, and the only
difference is one index the new version adds for its own speed. Rolling back is
safe because nothing was migrated.

Backup before upgrading (good practice, not required):

python -c "import sqlite3; \
  s=sqlite3.connect('$HOME/.voyager/index.db'); \
  d=sqlite3.connect('index-backup.db'); \
  s.backup(d); d.close(); s.close()"

Community

Listed in
awesome-dsh-plugin
(PR #7226, merged 2026-10-18).
That is a third-party directory listing — not a DeepSeek endorsement,
certification or partnership.

A note on the install command in this tag

The README.md inside this tag still shows @v1.2.0 in its install
commands. That is not a different release: the pin was repointed to @v1.3.0
in a follow-up commit on main (57aebef), after this tag was cut — the
release had to exist before the docs could point at it. The tag is immutable, so
the correction lives on main rather than inside it.

Use the current instructions:

pipx install "voyager[all] @ git+https://github.com/HarryHeYu/sessionFlow.git@v1.3.0"
voyager --version     # must print 1.3.0

Nothing about the code changed between the tag and main; only documentation.

Assets 4
Loading