The sorrel CLI

The core loop

$ sorrel init                      # .sorrel/: object store + manifest + HEAD
$ echo "hello" > a.txt
$ sorrel status                    # dirty: added a.txt (real diff vs HEAD)
$ sorrel change create -m "add a"  # snapshot, diff, Change object, advance HEAD
$ echo "world" >> a.txt
$ sorrel diff                      # line-level unified hunks vs HEAD
$ sorrel change create -m "edit a"
$ sorrel log                       # snapshot DAG walk with change ids,
                                   # authors, and messages

status and change create use the engine's stat cache, so unchanged files are never re-hashed. log resolves each snapshot to the Change that produced it through a small index in .sorrel/changes.index.

Lanes: parallel work without branch noise

$ sorrel lane create --name agent/feature
$ sorrel lane list                 # every lane, its head, the active one marked
$ sorrel lane switch <lane-id>     # restores that lane's tree (refuses if dirty)
$ sorrel lane submit               # create a Hub proposal for the active lane
$ sorrel stack create --name series <change-id>
$ sorrel stack show <stack-id>

Each lane has its own head under .sorrel/heads/. Two lanes advance independently — exactly what parallel agents need to work without stepping on each other.

Merge: fast-forward or real three-way

$ sorrel merge <lane-id>
# fast-forward when the active lane has not diverged
# otherwise: engine three-way merge (merge base + line merge)

# on conflicts:
#   - conflicted files get <<<<<<< ours / ======= / >>>>>>> theirs markers
#   - .sorrel/MERGE_STATE records the stored MergeResult object
#   - HEAD does not move
$ sorrel merge --continue          # after resolving markers, complete the merge
# or:
$ sorrel merge --abort             # restore the pre-merge tree

Clean merges write a merged snapshot with both parents and record a merge Change. Conflicted merges leave inspectable state: marker-annotated files in the tree and first-class Conflict objects in the store.

Git bridge: import, export, and colocated sync

$ sorrel git import                 # Git commits → Sorrel snapshots
$ sorrel git export ./mirror.git   # Sorrel snapshots → Git commits
$ sorrel git sync                  # align colocated .git/ and .sorrel/

Import and export are incremental and record SHA-to-snapshot mappings in .sorrel/git-map.json. Colocated sync fast-forwards the side that has not moved; true divergence is imported onto a normal git/<branch> lane for the usual Sorrel merge flow.

Hub sync: push and pull

$ sorrel remote add origin http://127.0.0.1:3000
$ sorrel push origin               # negotiate missing objects, upload, advance ref
$ sorrel pull origin               # fetch refs, download closure, verify ids

Push seeds the local snapshot closure, asks the Hub which objects are missing, uploads only those, and advances the remote ref with fast-forward and closure checks. Pull verifies every downloaded object's content id before trusting it.

Workflows, policy, slices

$ sorrel workflow validate         # parse + check sorrel.workflow.yml
$ sorrel workflow run <job>        # execute locally, gated by Core policy
$ sorrel policy evaluate ...       # Core policy decision for an action
$ sorrel grant create ...          # record a real Core grant decision
$ sorrel slice create ...          # slice manifest for a subproject

Secrets, environments, and run logs

$ sorrel secret list                # handles only
$ sorrel secret sync                # refresh secretspec.toml
$ sorrel secret check --provider dotenv:.env
$ sorrel env info                   # devenv or local-fallback
$ sorrel workflow run test
$ sorrel run list
$ sorrel run show <run-id>
$ sorrel run logs <run-id>

Secret resolution and injection use upstream SecretSpec only after Core grant checks. Values are injected into the child process, never Sorrel objects, and persisted output under .sorrel/runs/ is redacted. Full devenv task mapping, Hub log streaming, and a hosted secret backend remain future work.