pi-kage 0.3.2 → 0.3.3

package/README.md

@@ -31,13 +31,9 @@ instead of shipping.
 ## The idea
 
 A shadow clone is a **full, independent copy** of the repo — like a second engineer on a second
-machine. Each parallel session gets its own working tree, its own branch, its own commits and PR.
-Code merges the normal way: on GitHub. No local collisions, ever.
-
-And like a real Naruto shadow clone, it **carries your memory out** (the origin's 5 most recent pi
-sessions are copied into the clone, so you can `resume` them there) and **returns it on dispel** (the
-clone's *new* sessions are merged back into the original when you `finish`). The clone always opens a
-**fresh** session — kage never replays your old turns or fakes a "resumed" conversation.
+machine. Each parallel session gets its own working tree, branch, commits, and PR. Code merges the
+normal way: on GitHub. No local collisions, ever. And like a real Naruto shadow clone, it carries
+your memory out and returns it on dispel (see [How it works](#how-it-works)).
 
 Why a full folder copy instead of `git worktree`? A worktree shares one `.git`, which means you
 can't check out the same branch twice, you share stash/refs, and you get a *fresh* checkout with no
@@ -136,38 +132,31 @@ for subcommands and clone names.
 
 Four invariants keep parallel work safe and lossless:
 
-1. **Isolation** — a clone is a full independent copy with its own `.git`.
+1. **Isolation** — a clone is a full independent copy with its own `.git`. kage **doesn't create a
+   branch**: the clone stays on the origin's current branch and kage stays out of git flow entirely,
+   so you decide your own branching/PR workflow inside the clone (instruct the agent via your
+   `AGENTS.md`).
 2. **Code flows back via git, never the working tree.** With a remote you push the branch and merge a
-   PR; with **no remote**, `finish` fetches the clone's branch into the origin's git as a local
-   `kage/<name>-<sha>` branch (the origin's working tree is left untouched — merge it when you like). Either
-   way kage never copies the clone's working tree onto the origin, which would re-create the collisions
-   it avoids. `finish` still refuses to delete **uncommitted** work (it can't be preserved by a fetch).
-3. **Memory flows through `~/.pi`.** On create, the origin's session `.jsonl` files are copied into the
-   clone (the 5 most recent, by mtime) — so `pi`'s resume picker inside the clone surfaces them if you
-   want it, but the clone itself opens a **fresh** session (kage never replays turns or fakes a resumed
-   conversation). On `finish`, sessions the clone created are copied back whole; an unchanged copied-in
-   session adds nothing; and a copied-in session you *resumed and added to* comes back as a **new,
-   self-contained session** — so the origin's original session (and the leaf pi would resume) is never
-   mutated, and your added turns aren't lost.
+   PR. With **no remote**, `finish` fetches the clone's branch into the origin's git as a local
+   `kage/<name>-<sha>` branch (origin's working tree untouched — `git merge` it when you like; the short
+   sha keeps the ref unique so reusing a name never collides). kage never copies the clone's working
+   tree onto the origin — that would re-create the collisions it avoids — so `finish` refuses to delete
+   **uncommitted** work, which a fetch can't preserve.
+3. **Memory flows through `~/.pi`, never replayed.** On create, the origin's 5 most recent session
+   `.jsonl` files are copied into the clone — `pi`'s resume picker surfaces them, but the clone opens a
+   **fresh** session (kage never replays turns or fakes a resumed conversation). On `finish`, sessions
+   the clone created are copied back whole; an unchanged copied-in session adds nothing; and a
+   copied-in session you *resumed and added to* comes back as a **new, self-contained** session — so
+   the origin's original session (the leaf pi would resume) is never mutated and your turns aren't lost.
 4. **The origin is read-only to kage** — it only copies out and writes session memory; it never
    touches the origin's working tree, even while another session is live there.
 
+With a remote configured, `finish` nudges you to push first (so PR-flow mistakes surface) unless you
+pass `--push` / `--pr` / `--force`.
+
 ## Notes & caveats
 
 - The copy is a snapshot of the origin's **current** state, **including uncommitted changes**.
-- kage **doesn't create a branch** — the clone stays on the origin's current branch, and kage stays out
-  of git flow entirely. Decide your own branching/PR workflow inside the clone (instruct the agent via
-  your `AGENTS.md` / project conventions).
-- The clone opens a **fresh** pi session. The origin's 5 most recent sessions are copied in and are
-  **resumable** via pi's resume picker. Real work belongs in the clone's own fresh session, but if you do
-  resume a copied origin session and add turns, on `finish` that continuation is written back as a
-  **separate** session (the origin's original session is left untouched), so nothing is lost and no
-  active conversation is hijacked.
-- **No remote?** `finish` still works losslessly: committed work that isn't on a remote is fetched into
-  the origin as a local `kage/<name>-<sha>` branch (the exact name is printed; `git merge` it to
-  integrate). The short sha keeps the ref unique, so reusing a clone name never collides. With a remote
-  configured, `finish` keeps nudging you to push first (so PR-flow mistakes surface) unless you
-  `--push`/`--pr` or `--force`.
 - **Submodules**: a submodule's `.git` pointer is an absolute path and breaks on copy — run
   `git submodule update --init` in the clone.
 - Non-APFS / non-reflink filesystems fall back to a full (heavier) copy.

package/bin/kage.mjs

@@ -30,7 +30,7 @@ import { homedir } from "node:os";
 import { basename, dirname, join, resolve, sep } from "node:path";
 import readline from "node:readline";
 
-const VERSION = "0.3.2"; // keep in sync with package.json (enforced by test)
+const VERSION = "0.3.3"; // keep in sync with package.json (enforced by test)
 const MARKER = ".kage.json";
 const SESSIONS = process.env.KAGE_SESSIONS_DIR || join(homedir(), ".pi", "agent", "sessions");
 const RECENT_SESSIONS = 5; // how many of the origin's most-recent sessions to copy into a clone

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-kage",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "🥷 Shadow Clone Jutsu for your git repo: copy it into an isolated folder, work in parallel with pi, then merge the session memory back",
   "keywords": [
     "pi",