Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 15 additions & 8 deletions .claude/skills/sc-cli-reference/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -159,19 +159,26 @@ cargo run --bin sc -- work --agents 3 [--name <base>] -- <cmd> # fork agent wo
# (--with-secrets --identity <key> injects
# decrypted secrets into each agent env)
bash demo/run_work_demo.sh # parallel-agents round-trip proof
cargo run --bin sc -- ws fork --agents N [--identity <key>] # durable multi-invocation
cargo run --bin sc -- ws fork --agents N [--name <n>] [--identity <key>] # durable multi-invocation
# session: materializes N checkouts under
# .sc/ws/<i>/ and persists a manifest (P20)
cargo run --bin sc -- ws list # open session's workspaces, changed/unchanged
cargo run --bin sc -- ws run <i> [--with-secrets --identity <key>] -- <cmd> # run <cmd> in
# .sc/ws/<i>/ and persists a manifest (P20).
# --name opens a further named session in
# .sc/ws-<n>/ beside the unnamed one (ADR-0056);
# a name already open is refused
cargo run --bin sc -- ws list [--session <n>] # every open session's workspaces, changed/unchanged
# (or just session <n>'s)
cargo run --bin sc -- ws run [--session <n>] <i> [--with-secrets --identity <key>] -- <cmd> # run <cmd> in
# workspace i (SC_WORKSPACE/SC_WORKSPACE_DIR set)
cargo run --bin sc -- ws harvest [--into <branch>] [--identity <key>] # probe + auto-merge
cargo run --bin sc -- ws harvest [--session <n>] [--into <branch>] [--identity <key>] # probe + auto-merge
# every live workspace onto the landing branch
# (default the session's base branch, which must
# be checked out); clean lands cumulatively,
# conflicts fall back to work-<i> (always `work`;
# `--name` is `sc work` only)
cargo run --bin sc -- ws abandon [<i>] # drop one workspace or the whole session
# conflicts fall back to work-<i> (<n>-<i> for a
# named session); with several sessions the first
# harvest wins, a later conflicting one falls back.
# Omitting --session means the unnamed session,
# never a guessed named one
cargo run --bin sc -- ws abandon [--session <n>] [<i>] # drop one workspace or the whole session
bash demo/run_ws_demo.sh # multi-invocation session + auto-merge proof (P20)
cargo run --bin sc -- cherry-pick <ref> [--identity <key>] # replay one commit onto the
# current branch (--identity as above)
Expand Down
17 changes: 15 additions & 2 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -346,11 +346,11 @@ phases but the shape is stable:
- `promisor-lazy` — empty marker: this partial clone may fill gaps by object id
(P37a); `sparse-prev` — the previous sparse spec while a `sparse set` is in
flight (P37b).
- `local-key`, `protected-cache` (and `ws/cache-<i>`) — the P33 keyed stat cache
- `local-key`, `protected-cache` (and `ws/cache-<i>`, `ws-<name>/cache-<i>`) — the P33 keyed stat cache
for protected paths; never committed, never transferred.
- `tmp/` — guard-cleaned scratch for streaming pack transfer (P25).
- `ws/` — durable agent-session workspaces: `session.toml` manifest + per-agent
checkouts (P20). `git-remotes/<name>/` — the `git_oid ↔ sc_id` marks map and a
checkouts (P20); `ws-<name>/` — the same for a named session (ADR-0056). `git-remotes/<name>/` — the `git_oid ↔ sc_id` marks map and a
lazily-built bare `mirror.git` for network Git (P10/P18).
- Transient in-progress state (removed on completion/abort): `MERGE_HEAD`,
`PICK_HEAD`, `REBASE_STATE`, and their `*_DECIDED_ROOT` records, plus
Expand Down Expand Up @@ -781,6 +781,19 @@ guard family as a ref-mover.
directory, so a crash between the two never strands a `live = true` entry
pointing at a directory that no longer exists. See ADR-0030.

Named sessions (ADR-0056). `sc ws fork --name <n>` opens a further session in a
sibling root, `.sc/ws-<n>/` (manifest, `<i>/` checkouts and `cache-<i>` inside),
so the unnamed session's layout is untouched and tearing one session down never
touches another. `list`/`run`/`harvest`/`abandon` take `--session <n>`; without
it they mean the unnamed session and never guess a named one. Fallback branches
and `SC_WORKSPACE` are `<n>-<i>` (`work-<i>` unnamed). The repo lock serializes
every `sc` command, so harvests of different sessions run one at a time in
invocation order: the first lands, a later one merges over it or falls back.
`sc ws run` resolves its workspace and secret environment under the lock, then
releases it before spawning the command (`WsRunPlan`), so other sessions stay
usable while an agent runs. gc roots every open session's base snapshot.
Workspace refresh is designed in the ADR and not built.

## Phase 21 — hardening & consolidation sweep (built)

No new capability axis — a sweep closing the P16–P20 review tail. Every
Expand Down
14 changes: 10 additions & 4 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,7 @@ the code, those win.
| P17 | `sc rewrap`: one-commit bulk cutover of secrets + protected wrap lists to current recipients/escrow; escrow is a managed list; `--rotate` also re-seals every protected blob under a fresh key | [0027](docs/adr/0027-bulk-rewrap-and-multi-escrow.md), [0051](docs/adr/0051-rotate-protected-paths.md) |
| P18 | Hosted Git (GitHub https/ssh) via system-git mirror bridge (`SC_GIT` overrides); auth delegated to git | [0028](docs/adr/0028-network-git-remotes.md) |
| P19 | Resumable rebase (stop → resolve → `--continue`; one oplog record total), `cherry-pick --abort`/`--mainline <N>`, `sc amend` | [0029](docs/adr/0029-history-editing-polish.md) |
| P20 | Durable multi-invocation agent sessions: `sc ws fork/list/run/harvest/abandon` under `.sc/ws/`; harvest auto-merges, conflicts fall back to `work-<i>` | [0030](docs/adr/0030-agent-sessions-and-automerge.md) |
| P20 | Durable multi-invocation agent sessions: `sc ws fork/list/run/harvest/abandon` under `.sc/ws/`; harvest auto-merges, conflicts fall back to `work-<i>`. `fork --name <n>` opens a further named session in `.sc/ws-<n>/` (`--session <n>` on the other verbs; fallback branches and `SC_WORKSPACE` are `<n>-<i>`); sessions are harvested independently, first harvest wins; `ws run` releases the repo lock while the command runs; refresh is designed, not built (#215) | [0030](docs/adr/0030-agent-sessions-and-automerge.md), [0056](docs/adr/0056-named-concurrent-ws-sessions.md) |
| P21 | Hardening sweep: in-progress guards on all policy ops, git-marks self-heal, abort protected-skip parity, ws `"landed"` status | [0031](docs/adr/0031-hardening-consolidation.md) |
| P22 | Signed commits: v2 identities (one seed → X25519 + Ed25519), signatures as CAS objects, `sc sign`/`sc verify [--require]` | [0032](docs/adr/0032-signed-commits-provenance.md) |
| P23 | `sc conflicts`/`sc resolve --ours\|--theirs`: whole-file conflict resolution without hand-edited markers | [0033](docs/adr/0033-merge-ergonomics.md) |
Expand Down Expand Up @@ -211,7 +211,7 @@ transport-adjacent. The rest, imperatively:
to randomized, or with `--rotate`; only a plain rewrap over an all-randomized
tip is policy-only.
- **`.sc/local-key` and the per-checkout protected caches
(`.sc/protected-cache`, `.sc/ws/cache-<i>`) are never committed and never
(`.sc/protected-cache`, `<ws session root>/cache-<i>`) are never committed and never
transferred.** Cache saves are best-effort and ordered after ref moves; a
cache failure may cause a spurious re-seal but never incorrectness. The key
is owner-only on unix only; non-unix keeps default permissions and warns once
Expand Down Expand Up @@ -277,7 +277,13 @@ transport-adjacent. The rest, imperatively:
safe (reconstructed on next use). Stale marks self-heal on push/export.
- **`sc ws harvest` lands on the currently-checked-out branch** (default the
session's base; `--into` must also be checked out) — it refuses with a
`sc switch` hint otherwise.
`sc switch` hint otherwise. Several `sc ws` sessions may be open (the unnamed
one in `.sc/ws/`, named ones in `.sc/ws-<name>/`); `list`/`run`/`harvest`/
`abandon` take `--session <name>` and never guess a named session when none
is given. Harvests of different sessions run one at a time (repo lock), in
invocation order: the first lands, a later conflicting one falls back to
`<name>-<i>`. Do not run a pre-ADR-0056 `sc` against a repo with named
sessions open (its gc would not root their bases).
- **A stopped merge/pick/rebase lists the paths it wrote as plaintext in
`.sc/CONFLICT_PLAINTEXT`.** Protected conflict text never enters the CAS, so no
tree records it; completion treats a listed path absent from disk as deleted,
Expand Down Expand Up @@ -306,7 +312,7 @@ transport-adjacent. The rest, imperatively:

Deferred work is tracked in **`ROADMAP.md` → Deferred** (single source of
truth — do not re-list items here); entries that name an issue mirror the open
GitHub issues. Standing entries: named/concurrent `sc ws` sessions (#215),
GitHub issues. Standing entries: `sc ws` workspace refresh (#215),
blob-size clone filters (#217), bucket compaction and gc (#216), the non-unix
`.sc/local-key` ACL (#214), and the open
sparse, private-branch and abort edge cases (#241, #246, #247, #248).
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -170,7 +170,7 @@ and Git (including hosted GitHub) network transports, plus private branches
sealed to a recipient set until publish and a read-only Tauri desktop
browser. All 36 phases and P37a-37d are implemented and tested; `demo/` holds
27 independent end-to-end proofs, one per major capability. Remaining
follow-ons (transcript drop delivery gaps, bucket compaction and gc, named
concurrent `sc ws` sessions, size/count clone filters, and similar hardening
follow-ons (transcript drop delivery gaps, bucket compaction and gc, `sc ws`
workspace refresh, size/count clone filters, and similar hardening
items) are tracked in [ROADMAP.md](ROADMAP.md)'s Deferred section and as open
GitHub issues rather than being open MVP scope.
19 changes: 15 additions & 4 deletions ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -190,7 +190,15 @@ across every phase.
the session's base snapshot gated on manifest presence. Proven by
`demo/run_ws_demo.sh` (fork/edit/harvest across separate invocations:
two cumulative clean auto-merges, one conflict fallback, an `sc undo`
of a landing, zero residue at session end). (ADR-0030.)
of a landing, zero residue at session end). (ADR-0030.) Follow-on (#215,
ADR-0056): `sc ws fork --name <n>` opens further named sessions beside the
unnamed one, each in `.sc/ws-<n>/` with its own manifest and caches
(`--session <n>` on `list`/`run`/`harvest`/`abandon`; fallback branches and
`SC_WORKSPACE` are `<n>-<i>`); the unnamed layout is unchanged, no migration.
Harvests of different sessions are serialized by the repo lock and land in
invocation order (first wins, a later conflict falls back); `sc ws run`
releases the repo lock while its command runs, so other sessions stay usable.
Workspace refresh is designed in ADR-0056 and still deferred.
- **Phase 21 — Hardening & consolidation.** Closes the P16–P20 review
tail with no new capability axis. Every commit-creating policy op
(`protect`/`grant`/`revoke`/`secret add`/`secret rotate`/`secret
Expand Down Expand Up @@ -755,9 +763,12 @@ P28 review follow-ons, the port de-flake, the clippy allow-list) are recorded in
- **Remaining history-editing depth:** operation objects in the CAS
(Jujutsu-deep upgrade to the file oplog), oplog entries for
remote-tracking refs.
- **Named/multiple concurrent ws sessions (#215, P20).** P20 ships one unnamed
session per repo; named or concurrent sessions and workspace re-fork/refresh
from a newer tip need a design decision first.
- **`sc ws` workspace refresh (#215, P20).** Named and concurrent sessions
shipped (ADR-0056). Moving a live workspace onto a newer tip is designed there
(replay the workspace's commit with the ADR-0049 engine, refuse on any
conflict, re-materialize under the recorded view) but not built: it needs a
headless merge-into-tree entry point and a re-materialize that keeps files an
agent may have open. Abandon and re-fork covers it meanwhile.
- **Sparse untracked-file guard edge cases.** #241: on a case-insensitive
filesystem the untracked-file guard can alias an old-view path with a newly
in-view one. #248: an untracked file at an out-of-view path that the other side adds wins
Expand Down
Loading
Loading