CodeStory v0.17.7

CodeStory keeps source reads tied to the indexed bytes, waits for refreshes across sessions, and makes indexing failures easier to diagnose and recover from.

Read from a coherent index

• Snippets and source-backed context, search and packet results verify source against the indexed content hash. Changed or missing files receive a typed refusal instead of returning unrelated current text.
• During a refresh, source-backed reads wait for a fresh complete index within the call deadline. Graph navigation may use the retained publication, with its freshness labelled historical in the response. Waiting across preparation stages shares one deadline.
• A second session waits for a project already being refreshed and adopts the completed publication. Cancelling the waiting call leaves the writer running.
• Call-path verification reports when its search budget is exhausted, so an incomplete investigation cannot look complete.

Index and recover with clearer diagnostics

• Incremental deletion uses indexed proof-fact lookups, avoiding stalls caused by scanning the surviving graph.
• Files with trailing whitespace in their extensions no longer abort indexing.
• Obsolete index images are reclaimed after publication finishes, including work deferred while another session was publishing. Cleanup preserves foreign entries and verifies the retired directory's identity before removing it.
• A write-lock timeout identifies the holding process and provides guidance to wait for or stop it. A failed freshness probe names the failed stage instead of reporting a misleading zero file count.
• Markdown errors include their cause chain and recovery commands. doctor --support-bundle <file> writes a local redacted diagnostic bundle, and doctor lists other cached projects with incompatible schemas and their recovery commands.
• Indexing warns when a repository exceeds the 25,000-file freshness-scan bound; doctor reports the same limitation as a warning.

Windows and MCP hosts

• Linked Git worktrees open with the repository identity shared by their sibling worktrees.
• Search-index repair and republishing can replace read-only components, including files shared with earlier generations. Failed publication restores their immutable permissions.
• Rewritten or replaced search-index files are revalidated even when their size and timestamps match the previous file.
• Plugin setup briefly retries a managed CLI folder publication blocked by another program.
• The user guide covers other MCP hosts, the CODESTORY_CLI override and recovery from a managed-CLI containment failure.

Upgrading

The core cache moves to schema 36. Existing 0.17.6 indexes are rebuilt into a new generation on the next product call, with a one-time indexing cost; status and diagnostic reads remain observational. An older cache supplies the explicit recovery command codestory-cli index --project <root> --refresh full. A cache written by a newer binary is refused with guidance to reset derived state and rebuild.

Publication stamps move to schema 4 to add freshness metadata and remain compatible with schema 3 clients. Install matching CLI and plugin versions and restart the MCP host.

Platform support

• macOS 15+ on Apple Silicon: supported with Metal
• Windows x64: supported with Vulkan
• Linux x64: supported with Vulkan
• CPU-only Windows and Linux: unsupported
• Intel Mac: unsupported
• Windows ARM: unsupported