Collaborate Commands (work in progress)

[owenmccadden]

Updated Semantics

• Pull: resume your own session
  • Works on: sessions you own only.
  • Push: upserts to the original session.
  • Others’ sessions: “Session not found” (by design).
• Branch: copy your own session
  • Works on: sessions you own only.
  • Push: always creates a new session (independent branch).
  • Default target: current tracked session if no ID provided.
• Fork: copy someone else’s session
  • Works on: public sessions you don’t own (and optionally your own with a suggestion to use branch).
  • Push: always creates a new session (independent fork).

Decision Rules

• If you own it:
  • sb pull → resume original (append).
  • sb branch → new child owned by you (new session).
  • sb fork → disallow with a helpful hint: “Use sb branch” (optional --force to override).
• If you don’t own it:
  • sb pull → “Session not found”.
  • sb branch → error with hint to use sb fork.
  • sb fork → allowed for public sessions; creates a new session owned by you.

CLI Shapes

• sb pull <sessionId|url> [options]
  • --into : target project (default CWD).
  • --platform <claude|gemini|qchat|file>, --resume: materialize to provider and make continue-able.
  • --alias , --no-track: control local tracking.
• sb branch [<sessionId|url>] [options]
  • If omitted, branches current tracked session.
  • --at <n|head>: branch at message index (default head).
  • --title, --tags, --summary, --private.
  • --alias , --local (pending-branch until first push), --no-pull, --platform, --resume.
• sb fork <sessionId|url> [options]
  • Same options as branch.
  • Enforced on non-owned sessions; your own sessions suggest sb branch instead.

Lineage and Tracking

• Lineage fields for every session: rootId, parentId, baseCount, baseDigest.
• Tracking file per project: .sessionbase/tracking.json
  • current:
  • aliases[alias]: {
    sessionId?, parentId, rootId, baseCount, baseDigest,
    platform, files, lastPulledAt
    }
• Pull sets sessionId to the original; branch/fork set parentId and record baseCount/baseDigest at branch point; sessionId is assigned immediately (remote branch/fork) or on
  first push (local pending).

Push Behavior

• Pull flow: append delta since baseCount to tracked sessionId; CAS-validate baseDigest.
• Branch/fork flow: append to the new sessionId (or create-on-push if pending).
• On CAS mismatch (remote advanced): return 409; suggest sb pull to refresh base or sb branch/fork to diverge.

Helpful UX Guards

• sb fork on own session → “You own this session. Use sb branch to create a copy.” (offer --force).
• sb branch on others’ session → “You don’t own this session. Use sb fork.”
• sb pull on others’ session → “Session not found.”

Provider Materialization

• If --resume:
  • Claude: write jsonl under ~/.claude/projects//sb-.jsonl.
  • Gemini: create ~/.gemini/tmp//checkpoint-sb-.json (fresh).
  • Q Chat: no DB import; rely on canonical file + tracking.

Examples

• Continue your session:
  • sb pull session-123 --platform claude --resume --alias main
  • edit; sessionbase push → appends to session-123.
• Branch your own:
  • sb branch session-123 --at 42 --alias exp-a --title "RAG variant A"
  • edit; sessionbase push → creates new session and appends there.
• Fork someone else’s:
  • sb fork alice-999 --alias trial --private
  • edit; sessionbase push → creates your new session and appends there.

Edge Cases

• Privacy: fork disallowed on private sessions you don’t own; clear error.
• Multiple branches: aliases isolate baseCount/baseDigest; independent pushes.
• Gemini staleness: pulled checkpoints are fresh; still support --force for older user-created checkpoints.