cinna-cli 0.1.1__tar.gz → 0.1.3__tar.gz

{cinna_cli-0.1.1 → cinna_cli-0.1.3}/.github/workflows/publish.yml

@@ -11,10 +11,10 @@ jobs:
     name: Build distribution
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v5
+        uses: astral-sh/setup-uv@v8.1.0
         with:
           python-version: "3.11"
 
@@ -25,7 +25,7 @@ jobs:
         run: uv tool run --from twine twine check dist/*
 
       - name: Upload dist
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: dist
           path: dist/
@@ -41,7 +41,7 @@ jobs:
       id-token: write
     steps:
       - name: Download dist
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/

{cinna_cli-0.1.1 → cinna_cli-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cinna-cli
-Version: 0.1.1
+Version: 0.1.3
 Summary: Local development CLI for Cinna Core agents
 Project-URL: Homepage, https://github.com/opencinna/cinna-cli
 Project-URL: Repository, https://github.com/opencinna/cinna-cli

{cinna_cli-0.1.1 → cinna_cli-0.1.3}/docs/README.md

@@ -195,6 +195,7 @@ main.py  (CLI commands — Click)
   ├── client.py          — PlatformClient: HTTP + SSE stream_exec
   ├── mutagen_runtime.py — detect/install Mutagen; gate on version match
   ├── sync_session.py    — wrap the `mutagen` CLI (start/stop/status/conflicts)
+  ├── sync_tui.py        — live Textual TUI shown by `cinna dev` (Sync/Details/Conflicts tabs)
   ├── sync_ssh_shim.py   — `cinna-sync-ssh` entry point (WebSocket transport)
   ├── sync.py            — tarball/zip extraction helpers (initial clone only)
   ├── context.py         — CLAUDE.md, BUILDING_AGENT.md, .mcp.json, opencode.json
@@ -304,7 +305,12 @@ Opening the sync WebSocket keeps the remote env warm. The platform heartbeats `l
 
 ### Conflicts
 
-Mutagen's `two-way-safe` mode writes `<name>.conflict.<side>.<timestamp>` when it can't auto-merge. `cinna sync conflicts` walks the workspace and surfaces them. Users resolve by opening in their editor, picking a winner, and deleting the conflict copy. There is deliberately no magic UI — editors already have good 3-way merge tooling.
+Mutagen 0.18.1 in `two-way-safe` records conflicts in its session state (the `conflicts[]` array of `mutagen sync list --template '{{json .}}'`) but, contrary to older mutagen behavior, does **not** write `<name>.conflict.<side>.<timestamp>` files to disk — both sides simply retain their divergent content. See [`mutagen_capabilities.md` §7](./mutagen_capabilities.md#7--two-way-safe-does-not-write-conflictsidets-files) for the empirical proof and re-verification steps.
+
+Two surfaces expose conflicts:
+
+- **`cinna sync conflicts`** — a read-only Click subcommand that walks the workspace for any `*.conflict.*` files mutagen *does* end up writing (other sync modes, or future mutagen versions, may still produce them). Implementation lives in `sync_session.list_conflicts`.
+- **The Conflicts tab in `cinna dev`** — sourced from mutagen's JSON `conflicts[]`, always populated when a conflict exists. The user navigates the list with `↑`/`↓` and resolves with `1` (take REMOTE) or `5` (take LOCAL). Resolution mechanism: delete the file on the losing side (locally with `unlink()`, remotely via `cinna exec rm`) then `mutagen sync reset <session>`; mutagen sees one side empty, no common ancestor, and propagates the survivor. Verified against 0.18.1; see [`interface.md`](./interface.md) for the full element-to-mutagen-capability mapping.
 
 ---
 
@@ -428,6 +434,7 @@ uv run ruff format --check src/
 | WebSocket client | websockets | Minimal dep for the sync shim |
 | Sync engine | Mutagen | Battle-tested bidirectional sync; OSS; cross-platform |
 | Terminal | Rich | Spinners, panels, tables |
+| Live TUI | Textual | Three-tab interactive view (`cinna dev`); built on Rich |
 | MCP | mcp SDK | Official protocol SDK |
 | Tests | pytest + respx | Standard; respx is purpose-built for httpx |
 | Build | Hatchling | Minimal, standards-compliant |
@@ -440,7 +447,7 @@ uv run ruff format --check src/
 - **Interactive stdin for `cinna exec`** — REPLs, debuggers.
 - **Port forwarding** — `cinna forward local:remote` (Mutagen supports it).
 - **Post-sync hooks** — e.g. `uv sync` on `pyproject.toml` change.
-- **Web UI conflict resolution** — TUI and editor-based only for now.
+- **Web UI conflict resolution** — the in-TUI Conflicts tab covers the common case; editor-based 3-way merge stays the fallback for ones the TUI can't handle (e.g. asymmetric directory/file conflicts).
 - **Multi-device presence UI**.
 - **Bundled Mutagen daemon** — stay with a user-installed daemon.
 - **Telemetry pipe** to the backend.

cinna_cli-0.1.3/docs/interface.md

@@ -0,0 +1,160 @@
+# cinna sync TUI — Interface Reference
+
+> Maps every visible element of the live sync TUI (the screen shown by `cinna dev`) to the underlying Mutagen capability it depends on. Use this together with [`mutagen_capabilities.md`](./mutagen_capabilities.md) when bumping Mutagen versions: each feature here points to the section that proves the capability still works.
+
+The TUI is implemented in `src/cinna/sync_tui.py` and rendered by [Textual](https://textual.textualize.io/). It opens when the user runs `cinna dev` and closes on `q` / Ctrl-C; closing the TUI terminates the Mutagen sync session.
+
+---
+
+## Layout
+
+Three tabs, switched with `←` / `→`:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ cinna sync — <agent name>                              <clock>  │
+├─────────────────────────────────────────────────────────────────┤
+│ [ Sync ]  [ Details ]  [ Conflicts ]                            │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│   <tab content>                                                 │
+│                                                                 │
+├─────────────────────────────────────────────────────────────────┤
+│ q Quit  ◀ Tab  Tab ▶  1 take REMOTE  5 take LOCAL               │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Sync tab (default)
+
+The status-and-activity view. Layout:
+
+```
+┌─ Status pill, agent identity, endpoints ────────────────────────┐
+│ ⬤  Watching for changes                                         │
+│ Agent:    my-agent @ https://platform.example.com               │
+│ Local:    /Users/me/work/my-agent/workspace                     │
+│ Remote:   cinna@cinna-agent-<uuid>:/app/workspace               │
+└─────────────────────────────────────────────────────────────────┘
+  127 files · 14 dirs · 3.4 MB   Successful cycles: 12
+  · receiving 17/60 (53.4 MB so far, current file 3.0 MB)
+┌─ Activity log (scrolling) ──────────────────────────────────────┐
+│ 19:21:08  sync attached — both endpoints connected              │
+│ 19:21:09  status: watching → staging-beta [local→remote]        │
+│ 19:21:09    → remote [1/12] scripts/main.py (4.2 KB)            │
+│ 19:21:09    → remote [2/12] docs/notes.md (1.1 KB)              │
+│ 19:21:10  cycle #3 complete — synced 12 files (12.4 KB)         │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Elements and their Mutagen dependencies
+
+| Element                               | Source                                                            | Mutagen feature                                                                  |
+|---------------------------------------|-------------------------------------------------------------------|----------------------------------------------------------------------------------|
+| Status pill (`⬤  <text>`)             | `_state_pill` reading `status` + `alpha.connected`, `beta.connected` | [`mutagen_capabilities.md` §1, §3](./mutagen_capabilities.md#3-side-suffixed-status-values) |
+| Direction tag (`local→remote`)        | `_side_label` parsing the `-alpha` / `-beta` suffix of `status`   | [§3 side-suffixed status](./mutagen_capabilities.md#3-side-suffixed-status-values) |
+| Local / Remote URL lines              | `alpha.path`, `beta.{user,host,path}` from session JSON           | [§1 JSON shape](./mutagen_capabilities.md#1-mutagen-sync-list--template-json--output-shape) |
+| Stats line (files / dirs / total size)| `alpha.{files,directories,totalFileSize}`, `successfulCycles`     | [§1 JSON shape](./mutagen_capabilities.md#1-mutagen-sync-list--template-json--output-shape) |
+| Live progress (`receiving N/M …`)     | `(alpha|beta).stagingProgress.{receivedFiles,expectedFiles,totalReceivedSize,expectedSize}` | [§4 per-side stagingProgress](./mutagen_capabilities.md#4-per-side-stagingprogress) |
+| Per-file activity lines               | `_emit_staging_events` diffing `stagingProgress.path` between consecutive state records | [§4 stagingProgress.path](./mutagen_capabilities.md#4-per-side-stagingprogress) **and** [§2 monitor streams every change](./mutagen_capabilities.md#2-mutagen-sync-monitor-streams-state-on-every-change) — polling alone misses paths |
+| Status-transition lines               | `_emit_events` diffing `status` between consecutive records       | [§3 status](./mutagen_capabilities.md#3-side-suffixed-status-values)              |
+| Endpoint connect/disconnect lines     | `_emit_events` diffing `alpha.connected` / `beta.connected`       | [§1 JSON shape](./mutagen_capabilities.md#1-mutagen-sync-list--template-json--output-shape) |
+| Cycle-complete line with byte delta   | `_emit_cycle_complete` diffing `(alpha|beta).{files,totalFileSize}` against a pre-cycle snapshot | [§1 JSON shape](./mutagen_capabilities.md#1-mutagen-sync-list--template-json--output-shape); `successfulCycles` as edge trigger |
+| Scan / transition problem lines       | `_emit_problem_events` reading `(alpha|beta)(Scan|Transition)Problems[]` | [§1 JSON shape](./mutagen_capabilities.md#1-mutagen-sync-list--template-json--output-shape) |
+| Conflict log lines (`conflict: …`)    | `_emit_conflict_events` reading `conflicts[]`                     | [§6 conflict JSON shape](./mutagen_capabilities.md#6-conflict-json-shape)        |
+| `error: …` line                       | `lastError` field                                                  | [§1 JSON shape](./mutagen_capabilities.md#1-mutagen-sync-list--template-json--output-shape) |
+| Activity log file (`cinna.log`)       | Every TUI line is also routed to the `cinna.sync_tui` logger      | Independent of Mutagen — survives TUI close                                       |
+
+### How updates are delivered
+
+A single subprocess streams JSON state into the TUI: `mutagen sync monitor --template '{{json .}}{{"\n"}}' <session>`. The TUI reads `proc.stdout` line by line in `_monitor_loop`. Each parsed record is fed to `_render_sync_tab`, which renders the static pieces and then calls `_emit_events` — the per-file / per-cycle event emitter. Depends on [§2 monitor streaming](./mutagen_capabilities.md#2-mutagen-sync-monitor-streams-state-on-every-change).
+
+---
+
+## Details tab
+
+Verbatim output of `mutagen sync list --long <session>`, refreshed every 2 seconds (`DETAILS_INTERVAL`). This is what a power user would see if they ran the command themselves — full session metadata, scan results, raw conflict listings. Pure mutagen feature, no cinna interpretation.
+
+| Element     | Source                          | Mutagen feature                       |
+|-------------|----------------------------------|----------------------------------------|
+| Rendered text | `mutagen sync list --long`     | Native human-readable output — stable contract across 0.18.x |
+
+---
+
+## Conflicts tab
+
+```
+┌─ Conflicts (2) ──────────────────────────────────────────────────┐
+│ ▶ app-data/storage/workflow.db    (local+remote modified)        │
+│   docs/WORKFLOW_PROMPT.md          (local+remote modified)       │
+│                                                                  │
+│ ↑/↓ navigate  ·  1 take REMOTE (server)  ·  5 take LOCAL (yours) │
+│ Resolution deletes the losing side's file and resets mutagen     │
+│ history so the survivor propagates.                              │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+### Elements
+
+| Element                        | Source                                                     | Mutagen feature                                                          |
+|--------------------------------|-------------------------------------------------------------|---------------------------------------------------------------------------|
+| Conflicts list (one row / path)| `_extract_conflicts(session)` flattening `conflicts[].alphaChanges[].path` and `betaChanges[].path` | [§6 conflict JSON shape](./mutagen_capabilities.md#6-conflict-json-shape) |
+| Per-side modification tag      | Presence of paths in `alphaChanges` vs `betaChanges`        | [§6](./mutagen_capabilities.md#6-conflict-json-shape)                     |
+| `1 take REMOTE` action         | `_resolve_selected("beta")`: `rm <local file>` then `mutagen sync reset <session>` | [§8 per-file delete + reset](./mutagen_capabilities.md#8-per-file-conflict-resolution-via-delete--mutagen-sync-reset) |
+| `5 take LOCAL` action          | `_resolve_selected("alpha")`: `cinna exec rm <remote file>` then `mutagen sync reset <session>` | [§8](./mutagen_capabilities.md#8-per-file-conflict-resolution-via-delete--mutagen-sync-reset); requires cinna's own remote-exec channel |
+| Auto-refresh                   | `_maybe_refresh_conflicts` is called on every monitor record; re-renders the tab only when the set actually changes | [§2 monitor](./mutagen_capabilities.md#2-mutagen-sync-monitor-streams-state-on-every-change), [§6 conflicts](./mutagen_capabilities.md#6-conflict-json-shape) |
+
+### Why not source from disk?
+
+Because Mutagen 0.18.1 in `two-way-safe` does **not** write `.conflict.<side>.<ts>` files — both sides keep their own version and only the JSON state records the divergence. See [§7](./mutagen_capabilities.md#7--two-way-safe-does-not-write-conflictsidets-files). If a future mutagen version starts writing these copies again, `src/cinna/sync_session.py:list_conflicts` and `group_conflicts` are still in place and can be wired back in as a secondary data source.
+
+---
+
+## Keybindings
+
+| Key       | Action            | Where it lives                                                       |
+|-----------|-------------------|-----------------------------------------------------------------------|
+| `q`       | Quit              | App-level `action_quit`; on exit, the caller (`run_foreground`) calls `stop(config)` to terminate the Mutagen session. |
+| `Ctrl-C`  | Quit              | Same as `q`.                                                          |
+| `←` / `→` | Cycle tabs        | `action_cycle_tab(±1)`; wraps at ends.                               |
+| `1`       | Take REMOTE       | No-op outside the Conflicts tab. See [§8](./mutagen_capabilities.md#8-per-file-conflict-resolution-via-delete--mutagen-sync-reset). |
+| `5`       | Take LOCAL        | No-op outside the Conflicts tab. `1` and `5` are placed far apart on the keyboard to make a misfire unlikely. |
+| `↑` / `↓` | Navigate Conflicts list | Native to Textual's `OptionList`; only the Conflicts tab's list is focusable, so these keys do nothing on Sync / Details. |
+
+The `←` / `→` / `1` / `5` bindings are declared with `priority=True` so they fire even when the Conflicts `OptionList` has focus.
+
+---
+
+## Lifecycle
+
+```
+cinna dev
+    └─ sync_session.start(config, workspace_root)   # create / refresh Mutagen session
+    └─ run_foreground(config, workspace_root)
+          └─ run_tui(config, session_name, env, workspace_root)
+                └─ SyncApp.run()
+                       on_mount:
+                         · spawn _monitor_loop  (mutagen sync monitor --template …)
+                         · spawn _details_loop  (mutagen sync list --long, every 2 s)
+                       user presses q / Ctrl-C
+                       on_unmount:
+                         · cancel both loops
+                         · terminate the monitor subprocess
+          └─ stop(config)   # mutagen sync terminate <session-name>
+```
+
+The TUI does not outlive its terminal. Once the user quits, sync stops. To observe an existing sync session from another terminal without affecting it, the user runs `cinna sync status` (a read-only Click subcommand defined in `main.py`, not part of the TUI).
+
+---
+
+## Adding a new TUI element
+
+Procedure when you want to expose a new piece of Mutagen state:
+
+1. Look at the raw JSON: `mutagen sync list --template '{{json .}}' <session>` while the relevant state is active. Note the exact JSON key and where it lives (top-level, under `alpha`/`beta`, etc.).
+2. Add a row to [`mutagen_capabilities.md`](./mutagen_capabilities.md) if the field isn't already documented there. Include a reproduction command — future you, on the next mutagen bump, needs to verify it didn't move.
+3. Wire the read into `_render_sync_tab` (for static display) or `_emit_events` (for diff-driven log lines). Use `_safe_int` from `sync_session.py` for numeric fields to keep the defensive-accessor pattern consistent.
+4. Add a row to the appropriate table in this document linking the new element back to the capabilities reference.
+
+If a feature would need a Mutagen capability that doesn't yet exist in our pinned version, document the gap in [`mutagen_capabilities.md`](./mutagen_capabilities.md) and link to it from here so we know what to look for on the next bump.

cinna_cli-0.1.3/docs/mutagen_capabilities.md

@@ -0,0 +1,248 @@
+# Mutagen Capabilities — Verified Findings
+
+> A reference of every Mutagen behavior cinna-cli currently depends on, with the exact commands to re-verify each one. The goal: when we bump Mutagen, run through this doc top to bottom and confirm nothing regressed.
+
+**Currently pinned version:** Mutagen `0.18.1` (verified May 2026 against `mutagen version` on macOS arm64).
+
+All claims below were reproduced locally against that version. The reproduction commands assume the `mutagen` daemon is running (`mutagen daemon start`). They use temp dirs `/tmp/c-a` and `/tmp/c-b` as alpha/beta — clean them up between tests.
+
+---
+
+## 1. `mutagen sync list --template '{{json .}}'` output shape
+
+**What we rely on:** the JSON state is a top-level **array of session objects** (even when listing a single session by name). Each object flattens both the session config (alpha, beta endpoints, ignore rules) and the runtime state (status, conflicts, stagingProgress) at the top level — `state` is **not** a nested object.
+
+**Reproduce:**
+```bash
+mkdir -p /tmp/c-a /tmp/c-b && echo hi > /tmp/c-a/x.txt
+mutagen sync create --name=cap-test /tmp/c-a /tmp/c-b
+sleep 2
+mutagen sync list --template '{{json .}}' cap-test
+mutagen sync terminate cap-test
+```
+
+**Expected top-level keys (per session):**
+- `identifier`, `version`, `creationTime`, `creatingVersion`, `name`
+- `alpha`, `beta` — each contains `protocol`, `path`, `connected`, `scanned`, `directories`, `files`, `totalFileSize`, and during a transfer `stagingProgress`
+- `status` — string, see §3
+- `successfulCycles` — int counter (only emitted after first non-zero cycle)
+- `paused` — bool
+- `conflicts` — array, see §6
+- `lastError` — string (optional)
+
+**Where we read it:** `src/cinna/sync_session.py:_list_sessions`, `_to_status`; `src/cinna/sync_tui.py:_parse_monitor_payload`.
+
+---
+
+## 2. `mutagen sync monitor` streams state on every change
+
+**What we rely on:** `mutagen sync monitor --template '{{json .}}{{"\n"}}' <session>` is a long-running subprocess that writes one JSON-array record to stdout every time the daemon's session state changes — including progress ticks while a transfer is in flight. This is what lets the Sync tab show per-file paths in real time; polling at any practical interval misses fast files.
+
+**Reproduce:**
+```bash
+mkdir -p /tmp/c-a /tmp/c-b
+for i in $(seq 1 60); do dd if=/dev/urandom of=/tmp/c-a/file$i.bin bs=1M count=8 2>/dev/null; done
+mutagen sync create --name=cap-monitor /tmp/c-a /tmp/c-b
+( mutagen sync monitor --template '{{json .}}{{"\n"}}' cap-monitor & MPID=$!
+  sleep 12; kill $MPID 2>/dev/null
+) | head -20
+mutagen sync terminate cap-monitor
+rm -rf /tmp/c-a /tmp/c-b
+```
+
+**Expected:** multiple `[{...}]\n\n` payloads. During staging, you'll see `stagingProgress.path` change between records.
+
+**Where we read it:** `src/cinna/sync_tui.py:_monitor_loop`.
+
+**Known limit:** during very fast local-to-local syncs (60 files transferring in ~1 second on an SSD) the daemon coalesces updates and we observed roughly 1 distinct path emitted per 5–10 files. For cinna's actual use case (remote sync over network) each file takes long enough that monitor emits multiple progress records per file and we catch them all.
+
+---
+
+## 3. Side-suffixed `status` values
+
+**What we rely on:** `status` can take side-suffixed values `staging-alpha`, `staging-beta`, `transitioning-alpha`, `transitioning-beta`. These mean "currently writing to that side" — alpha = local, beta = remote. The base prefix (`staging`/`transitioning`/`scanning`/`watching`/`reconciling`/`saving`) is the phase.
+
+**Reproduce:** see §2 — during the transfer, watch the `status` field flip between `scanning` → `staging-beta` → `scanning` → `watching`.
+
+**Why we normalize:** `_to_status` and `_state_pill` both call `base_status(raw)` (in `sync_session.py`) which strips the `-<side>` suffix before matching against the set of healthy states. The side suffix drives the "local→remote" / "remote→local" direction label shown in the Sync tab.
+
+---
+
+## 4. Per-side `stagingProgress`
+
+**What we rely on:** when a side is staging, that side's object carries a `stagingProgress` block with these fields:
+```json
+{
+  "path": "file36.bin",
+  "receivedSize": 1638400,
+  "expectedSize": 3145728,
+  "receivedFiles": 17,
+  "expectedFiles": 60,
+  "totalReceivedSize": 53477376
+}
+```
+
+`path` is the file currently being received on that side. `expectedSize` is the *current file's* total, not the session's. `totalReceivedSize` is the cumulative bytes since staging started.
+
+**Reproduce:** §2 — watch any single record where `status` is `staging-beta`. `stagingProgress` will appear under `beta`.
+
+**Where we use it:** `src/cinna/sync_tui.py:_emit_staging_events` (logs each new `path` once, deduped against the previous record); `_render_sync_tab` appends the live progress hint to the stats line.
+
+---
+
+## 5. `mutagen.yml` and ignore semantics
+
+**What we rely on:** the per-workspace `mutagen.yml` written by `cinna sync` configures sync mode, scan mode, and ignore patterns. Mutagen reads it from the workspace root at session creation.
+
+**Currently written** (`src/cinna/sync_session.py:MUTAGEN_YML_TEMPLATE`):
+```yaml
+sync:
+  defaults:
+    mode: two-way-safe
+    permissions:
+      mode: portable
+    ignore:
+      vcs: true
+      paths:
+        - __pycache__/
+        - node_modules/
+        - .venv/
+        - .cinna/
+        - .mypy_cache/
+        - .pytest_cache/
+        - .DS_Store
+    scan:
+      mode: full
+```
+
+**Available sync modes** (`mutagen sync create --help`):
+- `two-way-safe` (cinna default) — both sides authoritative, conflicts halt
+- `two-way-resolved` — alpha wins on conflict (no manual intervention)
+- `one-way-safe` — alpha authoritative, beta cannot diverge
+- `one-way-replica` — alpha mirrored to beta exactly, beta overwritten
+
+**Available scan modes**: `full` (cinna default) and `accelerated`. `accelerated` uses filesystem watches and short-circuits unchanged directories; `full` is slower but more accurate for cases where watches misbehave (network filesystems, container bind mounts).
+
+---
+
+## 6. Conflict JSON shape
+
+**What we rely on:** when both sides modify the same file under `two-way-safe`, mutagen records a conflict in the session's `conflicts[]` array.
+
+**Shape:**
+```json
+{
+  "root": "shared.txt",
+  "alphaChanges": [
+    {"path": "shared.txt",
+     "old": {"kind": "file", "digest": "c9e870..."},
+     "new": {"kind": "file", "digest": "534ec1..."}}
+  ],
+  "betaChanges": [
+    {"path": "shared.txt",
+     "old": {"kind": "file", "digest": "c9e870..."},
+     "new": {"kind": "file", "digest": "e52d59..."}}
+  ]
+}
+```
+
+Some conflict kinds (directory/file disagreement, asymmetric delete) only populate `root`; the per-side change arrays may be empty.
+
+**Reproduce:**
+```bash
+mkdir -p /tmp/c-a /tmp/c-b && echo "orig" > /tmp/c-a/shared.txt
+mutagen sync create --name=cap-conflict --sync-mode=two-way-safe /tmp/c-a /tmp/c-b
+sleep 2
+mutagen sync pause cap-conflict
+echo "LOCAL"  > /tmp/c-a/shared.txt
+echo "REMOTE" > /tmp/c-b/shared.txt
+mutagen sync resume cap-conflict
+sleep 2
+mutagen sync list --template '{{json .}}' cap-conflict
+mutagen sync terminate cap-conflict
+rm -rf /tmp/c-a /tmp/c-b
+```
+
+**Where we read it:** `src/cinna/sync_tui.py:_extract_conflicts`.
+
+---
+
+## 7. ⚠ `two-way-safe` does NOT write `.conflict.<side>.<ts>` files
+
+**What we rely on:** in mutagen 0.18.1's `two-way-safe` mode, when a conflict occurs, mutagen records it in `conflicts[]` JSON but **leaves both sides' canonical files untouched**. No `.conflict.alpha.<ts>` or `.conflict.beta.<ts>` files are written.
+
+This contradicts older docs / forum posts about mutagen that describe conflict-marker files. We verified empirically that it does not happen in 0.18.1 two-way-safe.
+
+**Implication:** populating the Conflicts tab from a disk walk (`*.conflict.*`) returns an empty list even when conflicts exist. The tab must source from JSON, not the filesystem.
+
+**Reproduce:** §6, then check `ls -la /tmp/c-a /tmp/c-b` after the conflict appears — only `shared.txt` is present on each side.
+
+**If a future mutagen starts writing those files again:** `src/cinna/sync_session.py:list_conflicts` already walks for `*.conflict.<side>.<ts>` and is the path to surface them. The `cinna sync conflicts` CLI subcommand still uses it. The TUI currently does not — it sources conflicts from JSON via `_extract_conflicts`.
+
+---
+
+## 8. Per-file conflict resolution via delete + `mutagen sync reset`
+
+**What we rely on:** `mutagen sync reset <session>` clears the session's sync history (the common-ancestor record) without recreating the session. On the next scan, mutagen has no notion of what changed since when.
+
+By itself this does nothing useful for conflicts — both sides still have divergent content, so mutagen re-detects the conflict. But combined with deleting the *losing* side's file first, it forces propagation:
+
+| User picks | Action                                              | Effect                                                                                  |
+|------------|-----------------------------------------------------|------------------------------------------------------------------------------------------|
+| REMOTE     | `rm <alpha file>` then `mutagen sync reset <s>`     | Alpha empty, beta has content, no ancestor → mutagen propagates beta → alpha.            |
+| LOCAL      | `rm <beta file>` then `mutagen sync reset <s>`      | Beta empty, alpha has content, no ancestor → mutagen propagates alpha → beta.            |
+
+**Reproduce — Take REMOTE:**
+```bash
+# Set up conflict as in §6, then:
+rm /tmp/c-a/shared.txt
+mutagen sync reset cap-conflict
+sleep 3
+cat /tmp/c-a/shared.txt /tmp/c-b/shared.txt   # both = REMOTE
+mutagen sync list --template '{{json .}}' cap-conflict | python3 -c 'import json,sys; print(len(json.load(sys.stdin)[0].get("conflicts",[])))'
+# → 0
+```
+
+**Reproduce — Take LOCAL:** symmetric — `rm /tmp/c-b/shared.txt` instead.
+
+**Multi-conflict safety**: deleting one conflict file + reset only converges that one path. Other conflicts in the same session remain because both their sides still hold content. Verified by setting up two conflicts (`x.txt` and `y.txt`), resolving one with delete+reset, and observing the other untouched in the post-reset JSON.
+
+**Why we don't switch sync mode:** `two-way-resolved` would auto-resolve in alpha's favor, but its effect is session-wide — every conflict would resolve the same way. There's no per-file mode flag. The delete + reset approach is per-file.
+
+**Where we use it:** `src/cinna/sync_tui.py:_resolve_selected`. For the beta-side delete cinna shells out to `cinna exec rm -f -- <path>` since beta lives on the remote agent.
+
+---
+
+## 9. The SSH-shim contract
+
+**What we rely on:** mutagen invokes its SSH transport via the binary named `ssh` found in `$MUTAGEN_SSH_PATH`. `MUTAGEN_SSH_PATH` is a **directory** (not a binary path); mutagen searches it for an executable literally named `ssh`. The daemon captures its environment at startup, so any change to `MUTAGEN_SSH_PATH` requires restarting `mutagen daemon`.
+
+The remote URL must use OpenSSH-style `user@host:/path`, not `ssh://`. Mutagen's URL parser distinguishes the two and treats `ssh://` as a different transport.
+
+**Where we use it:** `src/cinna/sync_session.py:_ensure_ssh_shim_dir`, `_mutagen_env`, `_restart_daemon`, and the failure marker constants `_STALE_DAEMON_MARKERS` that trigger an automatic daemon restart on `sync create`.
+
+---
+
+## 10. `mutagen daemon` is shared across sessions
+
+**What we rely on:** a single `mutagen daemon` instance manages all sessions on the host, regardless of which user / project created them. `mutagen daemon stop` terminates ALL sessions across all projects; they auto-resume on the next `mutagen sync list` (or any subcommand that talks to the daemon).
+
+**Implication:** when cinna restarts the daemon to refresh stale env (`_restart_daemon`), other consumers of mutagen on the same machine experience a brief pause in their syncs. The pause is silent — they don't get a notification.
+
+**Reproduce:**
+```bash
+mutagen sync list           # note any non-cinna sessions
+mutagen daemon stop
+mutagen daemon start
+mutagen sync list           # same sessions reappear, all paused for a moment
+```
+
+---
+
+## When to revisit this doc
+
+- Bumping `mutagen` past `0.18.1` (any minor or major version).
+- Adding a UI feature that needs a Mutagen behavior we haven't documented.
+- After any user-reported sync bug that turns out to be a Mutagen-version-specific behavior change.
+
+Walking through §1–§8 with the reproduction commands takes ~5 minutes and catches the breaking changes that have historically bit us.

{cinna_cli-0.1.1 → cinna_cli-0.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cinna-cli"
-version = "0.1.1"
+version = "0.1.3"
 description = "Local development CLI for Cinna Core agents"
 readme = "README.md"
 requires-python = ">=3.10"

{cinna_cli-0.1.1 → cinna_cli-0.1.3}/src/cinna/main.py

@@ -408,7 +408,7 @@ def dev():
 
     st = sync_session.start(config, root)
     console.status(f"Sync session created ({st.state}) — attaching live view. Press Ctrl-C to stop.")
-    sync_session.run_foreground(config)
+    sync_session.run_foreground(config, root)
     console.status("Sync session terminated.")
 
 

{cinna_cli-0.1.1 → cinna_cli-0.1.3}/src/cinna/sync_session.py

@@ -46,7 +46,7 @@ sync:
         - .pytest_cache/
         - .DS_Store
     scan:
-      mode: accelerated
+      mode: full
 """
 
 
@@ -297,12 +297,12 @@ def stop(config: CinnaConfig) -> None:
     _run_mutagen(["sync", "terminate", session_name(config.agent_id)], config)
 
 
-def run_foreground(config: CinnaConfig) -> int:
-    """Attach the terminal to the Mutagen sync session via a two-tab TUI.
+def run_foreground(config: CinnaConfig, workspace_root: Path) -> int:
+    """Attach the terminal to the Mutagen sync session via a live TUI.
 
-    The TUI polls ``mutagen sync list`` once per second. Tab 1 renders a
-    friendly status block and a derived activity log; Tab 2 shows the raw
-    ``mutagen sync list --long`` output for power users.
+    Three tabs: Sync (status + per-file activity log), Details (raw
+    ``mutagen sync list --long``), and Conflicts (interactive resolution
+    for files Mutagen couldn't auto-merge).
 
     Blocks until the user presses ``q`` / Ctrl-C. On return the Mutagen
     session is terminated so sync does not outlive the TUI.
@@ -315,7 +315,7 @@ def run_foreground(config: CinnaConfig) -> int:
     env = _mutagen_env(config)
     rc = 0
     try:
-        rc = run_tui(config, session, env)
+        rc = run_tui(config, session, env, workspace_root)
     except KeyboardInterrupt:
         rc = 0
     finally:
@@ -343,9 +343,10 @@ def _to_status(config: CinnaConfig, session: dict) -> SyncStatus:
     """
     raw_state = (session.get("status") or session.get("state") or "").lower()
     paused = bool(session.get("paused"))
+    base = base_status(raw_state)
     if paused:
         state = "paused"
-    elif raw_state in {"watching", "scanning", "staging", "transitioning", "saving", "reconciling", "connected", "watching-changes"}:
+    elif base in {"watching", "scanning", "staging", "transitioning", "saving", "reconciling", "connected"}:
         state = "connected"
     elif raw_state in {"disconnected", "connecting"}:
         state = "disconnected"
@@ -380,6 +381,16 @@ def _safe_int(v) -> int:
         return 0
 
 
+def base_status(raw: str) -> str:
+    """Strip Mutagen's side suffix (e.g. ``staging-beta`` → ``staging``).
+
+    Mutagen distinguishes the receiving side in its status string while a
+    transfer is in flight, but most consumers care about the phase, not the
+    direction.
+    """
+    return raw.split("-", 1)[0] if "-" in raw else raw
+
+
 @dataclass
 class Conflict:
     path: Path
@@ -413,6 +424,64 @@ def list_conflicts(config: CinnaConfig, workspace_root: Path) -> list[Conflict]:
     return results
 
 
+@dataclass
+class ConflictGroup:
+    """Two-sided view of one conflicted path.
+
+    Mutagen may write one or both ``.conflict.<side>.<ts>`` copies depending
+    on which side it considered the winner. ``canonical`` is the real
+    workspace path the two copies are versions of.
+    """
+    canonical: Path
+    alpha_copy: Path | None = None
+    beta_copy: Path | None = None
+
+
+def _canonical_from_conflict(p: Path) -> Path:
+    """``foo/bar.txt.conflict.alpha.20260101`` → ``foo/bar.txt``."""
+    name = p.name
+    idx = name.find(".conflict.")
+    if idx <= 0:
+        return p
+    return p.parent / name[:idx]
+
+
+def group_conflicts(conflicts: list[Conflict]) -> list[ConflictGroup]:
+    """Bucket flat conflict-copy paths by their canonical workspace path."""
+    groups: dict[Path, ConflictGroup] = {}
+    for c in conflicts:
+        canonical = _canonical_from_conflict(c.path)
+        g = groups.setdefault(canonical, ConflictGroup(canonical=canonical))
+        if c.kind == "alpha":
+            g.alpha_copy = c.path
+        elif c.kind == "beta":
+            g.beta_copy = c.path
+    return sorted(groups.values(), key=lambda g: str(g.canonical))
+
+
+def resolve_conflict(group: ConflictGroup, side: str) -> None:
+    """Apply the user's choice: keep ``side``'s version at ``canonical``.
+
+    side: ``"alpha"`` (local) or ``"beta"`` (remote).
+
+    When the named side's conflict copy exists, it replaces the canonical
+    file. When it doesn't, the canonical file is already that side's content,
+    so we only delete the loser's copy. Mutagen picks up the change on its
+    next scan and propagates the resolution to the other endpoint.
+    """
+    if side not in ("alpha", "beta"):
+        raise ValueError(f"side must be 'alpha' or 'beta', got {side!r}")
+    target = group.alpha_copy if side == "alpha" else group.beta_copy
+    other = group.beta_copy if side == "alpha" else group.alpha_copy
+
+    if target is not None and target.exists():
+        if group.canonical.exists() and group.canonical.is_file():
+            group.canonical.unlink()
+        target.rename(group.canonical)
+    if other is not None and other.exists():
+        other.unlink()
+
+
 def session_log_dir(workspace_root: Path) -> Path:
     """Where we cache per-session breadcrumbs (exec history, etc.)."""
     return config_dir(workspace_root) / "sync"