Context sync — Agent Surface

Not for shared projects. Location sync shares a local .context/ store through a Git repository, a bucket or a folder. A team that works in a Test Manager project uses a shared project instead (shared-projects.md). A folder linked to one refuses kane-cli context sync, kane-cli context push and kane-cli context clone (REMOTE_UNSUPPORTED), and a location pull (a location name, --rebase, --yes or --answer: PULL_LOCATION_LINKED); a plain kane-cli context pull --mode agent there brings the project's tests, when kane-cli context pull --help lists --project (shared-projects.md §7). Never use both in one folder.

The assurance store (.context/, references/assurance.md §8) is one person's. Context sync shares it with a team through a location: a GitHub repository, an S3-compatible bucket, or a folder. Each person keeps their own store and publishes to the location; nothing on a location is ever overwritten or deleted. Reach for this reference when the user wants to share their context store, join a teammate's, get two stores level, or resolve a sync conflict. Sync never calls the KaneAI service — no credits, no model.

Version gate. kane-cli context sync, kane-cli context push, kane-cli context pull and kane-cli context clone exist on kane-cli 0.8.14 and later. On an older CLI they fail as an unknown command (exit 2, a "did you mean" line) — the CLI is too old, not a typo. Confirm with kane-cli --version, have the user update, stop.

1. Vocabulary — use these words

2. Commands

Every command takes --mode agent (NDJSON, stderr byte-empty, done last). [name] defaults to the only location; with several, to the one called origin; otherwise the command refuses and asks for a name.

Location forms: https://github.com/<owner>/<repo>.git or git@github.com:<owner>/<repo>.git (optional ?prefix=<path>#<branch>); s3://<bucket>/<prefix>?endpoint=<https://host:port>&region=<region> (endpoint only for a non-AWS service); a folder path.

3. The stream — the minimum an agent parses

Envelope {"type":…,"v":1,"verb":"sync",…}; a write verb refused by the fence stamps its own name ("verb":"name"). The vocabulary is open — tolerate unknown event types and fields, never fail on them. Events not listed (sync_locations, sync_removed, sync_rebase_item, gitignore_updated, …) are informational — summarize or ignore. Two are not: a warning{message} (a .gitignore that could not be written, a lifecycle note) is relayed to the user, and sync_doctor after kane-cli context sync doctor --abort carries aborted and a detail that names the next step (§4).

Captured shapes (real runs):

{"type":"sync_error","v":1,"verb":"sync","code":"SYNC_DIVERGED","detail":"you and origin both added work after position 2; nothing was pushed","remedy":"run kane-cli context pull origin --rebase to save your local work, take the team version from origin, and then reapply yours"}
{"type":"sync_rebase_decision","v":1,"verb":"sync","rebase_id":"2026-09-14T10-47-54-074Z-reset","decision_id":"h3","kind":"slug","intent":"names","seq":3,"label":"names spec","location":"origin","mine":"named prd \"spec\" at 2026-09-14T10:47:50.866Z","theirs":"\"spec\" names brief on origin (by bob at 2026-09-14T10:47:47.857Z)","answers":[{"answer":"keep-theirs","consequence":"the local change stays in the backup"},{"answer":"apply-mine","consequence":"the name moves to the local node; the node that holds it on origin is reached by its id again"}]}
{"type":"done","v":1,"verb":"sync","status":"paused","exit_code":3}

4. Exit codes (these verbs only)

A nonzero exit says what stopped, not that nothing happened: kane-cli context sync finishes its pull before its push can be refused, and a push can land before its confirmation is lost. The events before the sync_error say what completed; its detail says what did not.

5. Decisions — how to answer

A rebase starts only with kane-cli context pull <name> --rebase --yes --mode agent, and only on the user's explicit instruction (without a terminal --yes is required — otherwise SYNC_DIVERGED with that exact line as the remedy). The walk reapplies what it can, emits one sync_rebase_decision per real disagreement, then sync_rebase_done{paused} + done{paused}, exit 3. The rebase stays open until every decision is answered or it is aborted.

• One decision at a time, never guess. Present each card in plain words: what local did (mine), what <name> holds (theirs), the offered answers with their consequence. If the user's instruction clearly settles it, answer; otherwise ask. Never pass an answer the card did not offer.
• Answer by id, only with an answer from that card's answers[]: kane-cli context sync <name> --answer h3=keep-theirs --mode agent (repeatable; also on kane-cli context pull). keep-theirs writes nothing — the local change stays in the backup, and a later saved record built on it is looked at again; apply-mine lands the local version on top of the location's; apply-mine-as-new (offered only for newly created items) adds the local content as a new item.
• Some cards offer only keep-theirs: a record this build cannot read or replay, one that refers to an item the location no longer has, or one the store's own checks refuse. Tell the user that piece of work stays in the backup and has to be done again after the rebase.
• After an answer the stream re-emits the decisions still open and done{paused} again. When the last one lands, on kane-cli context sync: sync_rebase_done{complete} → sync_pull_done → sync_push_done → done{complete}; on kane-cli context pull: sync_rebase_done{complete} → sync_pull_done → done{complete} — pull never pushes, so publish afterwards with kane-cli context push or kane-cli context sync.
• Decide later = do not answer; the rebase stays open. kane-cli context sync status <name> --mode agent lists the open decisions whenever the location can be reached (when it cannot, the command refuses and lists nothing); kane-cli context sync status --show <n> --mode agent prints one saved record in full and needs no location.
• An unknown id, an answer the card does not offer, or --answer with no open rebase → error{USAGE} naming the fix; an answer checked against decisions that have since moved → SYNC_REBASE_PENDING — read kane-cli context sync status again.

6. Refusal codes — map to plain words, remedy verbatim

7. The fence

While a rebase is open, the store takes writes from the walk only. Every other write verb — kane-cli context name, kane-cli context retire, kane-cli context revert, kane-cli context ingest, kane-cli context extract, kane-cli design tests, kane-cli maintain reconcile, kane-cli context review — refuses SYNC_REBASE_PENDING (exit 2; a sync_error under --mode agent, stamped with that verb's name); kane-cli context push emits sync_rebase_open then the same refusal; a test run does not refuse — its results wait to the side and land on the first run after the rebase is finished. Reads (kane-cli context sync status, kane-cli context sync doctor, kane-cli context sync list, kane-cli context explain, kane-cli context fsck, kane-cli context view) never block. Two ways out, both the user's call and never taken on the agent's own initiative: finish it (kane-cli context sync <name>, answering decisions per §5) or close it (kane-cli context sync doctor --abort — reapplied items stay, unresolved local changes stay in the backup, sync_rebase_done{aborted} when a readable rebase is closed, otherwise sync_doctor.detail says what was set aside; exit 3 when decisions were left). Never delete a lock, a backup or anything under .context/sync/, and never delete files under .context/ to lift the fence — the backup and the rebase record are the way back.

8. Never

• Never edit, copy around, or hand-repair anything under .context/; never git add/git merge .context/ — keep it gitignored. Sharing happens through a location, even when the location is a Git repository.
• Never put a secret in a location address or on the command line: S3 keys go through --credential-env/--credential-file (or KANE_SYNC_S3_ACCESS_KEY_ID + KANE_SYNC_S3_SECRET_ACCESS_KEY at use time), a GitHub token through KANE_SYNC_GIT_TOKEN. An address is safe to paste; it grants nothing by itself.

9. Narration

• Translate codes; never show event or field names, ids, hashes or raw NDJSON. Name the location by its name: "origin has 3 records you have not pulled", "published 2 records to team".
• One line per decision, from label + mine + theirs + the offered answers; one line per answer landed ("kept origin's version for the name spec"). The id stays in the command (--answer h3=…), out of the narration.
• On exit 3 say what is waiting (a pull, or N decisions) and the exact next command; it is not a failure. On exit 2 relay remedy verbatim (or message when there is none), and say what did complete before it.
• sync_behind on an assurance stream is one advisory line ("origin has moved past this machine — pull when convenient"); the run continues.