The working-tree overlay

cix's canonical index is built from committed, pushed git state. Your uncommitted work is not in it. The overlay is the layer that closes that gap: the client uploads dirty files server-side, keyed to who you are, which repository and branch you are on, and the exact commit (head_sha) your working tree sits on.

What the overlay gives you

Reads merge overlay bytes over canonical bytes, so a file you just edited is served as you see it, not as it was last pushed. Symbol lookups can find names in uploaded files. Writes verify against overlay state so two writers cannot silently clobber each other.

Anchoring

Every overlay row is pinned to a branch and a head commit. This is why a detached HEAD or an unresolvable branch refuses writes (STALE_OVERLAY_REQUIRED): without the pin, the server cannot say which committed state your edits are relative to, and serving or editing against a guess is exactly the failure cix exists to prevent. It is also why switching branches can momentarily surface stale-state errors — the overlay for the new branch has not been uploaded yet. A single refresh_index on the affected file heals this.

What is excluded

Secret-shaped files, binaries and deleted files are never uploaded. Read responses that report overlay coverage count these separately as "excluded by design" — an excluded file is not silently served from an older copy.

The practical rules

• Responses that mention refresh_stale() are telling you some dirty files are not yet uploaded; calling it makes subsequent reads current.
• Overlay state is per-branch. After a branch switch, expect one refresh.
• If writers fail while readers work in the same session, the session's cached git state is stale — reconnect the MCP session rather than retrying.