@rewind-ai/cli 0.6.2

package/docs/MCP.md

@@ -0,0 +1,107 @@
+# REWIND MCP (V2 tools → V5 engine)
+
+## Architecture
+
+```
+Cursor Agent
+    │  MCP tools/call
+    ▼
+REWIND MCP server (stdio, local)
+    │  identify actor (MCP client)
+    │  Transaction Engine (V5)
+    │    → permission → FilesystemAdapter
+    │    → BEFORE → mutate → AFTER
+    │  append action ledger (+ v5 overlay)
+    ▼
+sandbox-test-project/  (or sandbox-enforced-project)
+```
+
+Provenance comes from **mediation**, not from watching the OS.
+MCP is a mediation route, not REWIND itself.
+
+## Tools
+
+| Tool | Mutating | Notes |
+|------|----------|-------|
+| `rewind_read_file` | no | Audit only |
+| `rewind_list_directory` | no | Audit only |
+| `rewind_write_file` | yes | Create or overwrite |
+| `rewind_create_file` | yes | Fails if exists |
+| `rewind_delete_file` | yes | Stores blob before delete |
+| `rewind_move_file` | yes | Fails if destination exists |
+| `rewind_create_directory` | yes | |
+| `rewind_delete_directory` | yes | Captures full subtree |
+| `rewind_get_status` | no | |
+| `rewind_action_history` | no | |
+| `rewind_undo_action` | undo | Conflict-aware |
+
+No shell/exec tools.
+
+## Configuration (Cursor)
+
+Project file: `.cursor/mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "rewind": {
+      "command": "npx",
+      "args": ["tsx", "${workspaceFolder}/src/cli.ts", "mcp"],
+      "env": {
+        "REWIND_PROJECT_ROOT": "${workspaceFolder}"
+      }
+    }
+  }
+}
+```
+
+Also works via **Cursor Settings → Tools & MCP → Add new MCP server** (stdio).
+
+Restart Cursor or toggle the server after changing config. Check **Output → MCP Logs** if tools do not appear.
+
+Manual start for debugging:
+
+```bash
+cd /Users/jack/Desktop/REWIND
+npm run mcp
+```
+
+(stdio — normally Cursor launches this.)
+
+## Provenance guarantees
+
+**What we claim**
+
+- An MCP client requested tool `T` with args `…`
+- REWIND itself performed the filesystem mutation
+- `source = MCP` on the ledger entry
+- Client `name`/`version` recorded when MCP initialize provides them; otherwise `UNKNOWN_MCP_CLIENT`
+
+**What we do not claim**
+
+- “Cursor process PID authored these bytes”
+- “All Cursor activity is mediated”
+- That native Cursor edits are impossible while MCP is connected
+
+## Bypass limitation (critical)
+
+Cursor retains native filesystem tools. An agent can edit `sandbox-test-project` **without** calling REWIND MCP.
+
+| Path | Provenance |
+|------|------------|
+| `rewind_write_file` | MCP / HIGH mediation certainty |
+| Native Cursor edit | UNKNOWN (V1 watcher may observe WHAT only) |
+
+REWIND never claims it controls all Cursor activity merely because MCP is connected.
+
+Closing the bypass eventually requires vendor tool policies, sandboxing, or agent integration — out of scope for V2.
+
+## V3 note
+
+Mutating tools accept `sandbox: "test" | "enforced"` (default `test`).
+Use `sandbox=enforced` against `sandbox-enforced-project/` under V3 fs-readonly + hooks + optional seatbelt.
+See docs/ENFORCEMENT.md — enforcement is **scoped**, not universal.
+
+## Safety
+
+All tools use V0/V1 path validation. Escapes (`../`, absolute outsides, `.rewind`, symlink escapes) fail closed.

package/docs/PACKAGING.md

@@ -0,0 +1,77 @@
+# Packaging & updates
+
+## Current distribution (V6.2)
+
+| Channel | Status |
+|---------|--------|
+| `npm pack` + global install from tarball | Proven locally |
+| npm registry `@rewind-ai/cli` | Ready to publish (not published yet) |
+| Homebrew | Not created |
+| Signed macOS app | Not created |
+
+### User install (after publish)
+
+```bash
+npm install -g @rewind-ai/cli
+cd /path/to/your/project
+rewind setup
+rewind doctor
+rewind open
+```
+
+Package name: **`@rewind-ai/cli`**. Binary command: **`rewind`**.
+
+### Local pack proof (before publish)
+
+```bash
+npm run build
+npm pack                    # creates rewind-ai-cli-0.6.2.tgz
+npm install -g ./rewind-ai-cli-0.6.2.tgz
+rewind version
+cd /tmp/some-project && rewind setup
+```
+
+Do not claim the package is on npm until it is published.
+
+## Runtime paths
+
+| Kind | Location |
+|------|----------|
+| Package (read-only) | npm global prefix / node_modules/@rewind-ai/cli |
+| Project state | `<project>/.rewind/` |
+| User state | `~/.rewind/` (credentials, commercial, keys, optional `.env`) |
+
+Never write runtime state into `dist/` or the package install directory.
+
+## Env / Stripe TEST config (installed users)
+
+Prefer **user-level** env — not a `.env` inside the npm package:
+
+```bash
+mkdir -p ~/.rewind
+# Create ~/.rewind/.env with sk_test_… / price_… / whsec_…
+```
+
+Also accepted: project-cwd `.env` (gitignored). See [HUMAN-SETUP.md](./HUMAN-SETUP.md).
+
+## Updates
+
+`rewind update` prints channel instructions.  
+Updates **must not** delete `.rewind/` history, CAS, or policies.
+
+## Uninstall
+
+```bash
+rewind uninstall                 # removes MCP config; keeps recovery data
+rewind uninstall --delete-recovery-data --yes
+npm uninstall -g @rewind-ai/cli
+```
+
+## Publish (manual — do not run until ready)
+
+```bash
+npm login
+npm publish --access public
+```
+
+`package.json` includes `"publishConfig": { "access": "public" }` for the scoped package.

package/docs/PERMISSIONS.md

@@ -0,0 +1,53 @@
+# Permissions (V5)
+
+## EXISTS
+
+Local policy file: `.rewind/policy/permissions.json`
+
+```json
+{
+  "version": 1,
+  "defaultEffect": "ALLOW",
+  "rules": [
+    {
+      "id": "ask-delete",
+      "priority": 10,
+      "effect": "ASK",
+      "adapter": "filesystem",
+      "operation": "delete",
+      "resourcePattern": "**",
+      "enabled": true,
+      "reason": "Deletes require approval"
+    }
+  ]
+}
+```
+
+### Decisions (before mutation)
+
+| Decision | Behaviour |
+|----------|-----------|
+| ALLOW | Continue mediated execute |
+| ASK | No mutation; transaction → AWAITING_APPROVAL + pending approval record |
+| DENY | No mutation; transaction → DENIED |
+
+### Match dimensions (generic)
+
+actor client · adapter · operation · resource glob · reversibility · risk
+
+Default document uses `defaultEffect: ALLOW` so existing FS tests remain usable.
+
+CLI:
+
+```bash
+rewind policy
+rewind policy init
+rewind policy set ask-delete ASK --op delete --enable
+```
+
+## PLANNED
+
+- Risk scoring
+- Per-actor quotas
+- UI policy editor
+- Outside-project DENY that is not already covered by path safety

package/docs/PRODUCT-V5.md

@@ -0,0 +1,63 @@
+# REWIND V5 — Product Core
+
+## Status
+
+**EXISTS (shipped in this tree):** general transaction model, adapter interface, FilesystemAdapter wrapping V2 mediation, permission engine (ALLOW/ASK/DENY), approval backend + CLI, actor/authority foundation, ledger query layer, V5 CLI surface, MCP routed through V5 engine, loopback local API + minimal control UI, development entitlement provider, threat model docs.
+
+**PLANNED (not shipped):** shell/DB/HTTP/browser adapters, real compensation strategies, delegated human authority, Stripe/billing, polished desktop app, universal enforcement of native Cursor writes.
+
+## Product truth
+
+REWIND is undo for AI agents — a local **control and transaction layer**:
+
+CONTROL → RECORD → REVERSE → PROVE
+
+Mediated path: `AGENT → REWIND → TARGET`
+
+Filesystem is the first production adapter, not the definition of REWIND.
+
+## Non-negotiable lessons preserved
+
+1. Observation ≠ attribution  
+2. Native/bypassed writes are never authoritative mediated actions  
+3. Mediation provides trustworthy provenance  
+4. Reversible actions need before/after state  
+5. Undo is conflict-aware  
+6. If current ≠ expected after → refuse undo  
+7. Human/newer work wins  
+8. Enforcement ≠ mediation  
+9. MCP is a mediation route, not REWIND itself  
+10. Filesystem is the first adapter  
+
+## Commands
+
+```bash
+npm run rewind -- status
+npm run rewind -- transactions
+npm run rewind -- transaction <act_…>
+npm run rewind -- undo <act_…>
+npm run rewind -- approvals
+npm run rewind -- approve <appr_…>
+npm run rewind -- deny <appr_…>
+npm run rewind -- policy
+npm run rewind -- policy init
+npm run rewind -- policy set ask-delete ASK --op delete --enable
+npm run rewind -- api          # loopback 127.0.0.1:7429 + token
+npm run mcp
+```
+
+## What V5 proves
+
+- Core no longer assumes every transaction is a filesystem op (adapter boundary exists).
+- One mediated execution path for FS MCP tools (via transaction engine).
+- Permissions can DENY/ASK before mutation; DENY leaves target unchanged.
+- Approvals revalidate state (TOCTOU refusal).
+- Conflict-aware undo still protects newer work.
+- Local API is loopback + token, not a public service.
+
+## What V5 does not prove
+
+- Agents cannot bypass REWIND (same-UID / native tools still can).
+- Non-filesystem adapters work.
+- Commercial licensing / entitlement enforcement.
+- A production desktop product UX.

package/docs/PRODUCT-V6.md

@@ -0,0 +1,69 @@
+# REWIND V6 — First sellable product
+
+## EXISTS
+
+Installable product surface for **REWIND Personal** (£2.99/month list):
+
+| Area | Status |
+|------|--------|
+| `rewind setup` / `doctor` / `open` / `uninstall` / `version` / `update` | Shipped |
+| Cursor MCP client integration | Shipped (only tested client) |
+| Control app (Activity/Approvals/Agents/Policy/Settings) | Shipped via local API |
+| Browser login (`rewind login`) local-dev + OIDC-ready | Shipped (local-dev works without IdP) |
+| Commercial file store (users/installs/subs) | Shipped (not Postgres) |
+| Stripe TEST Checkout Session + signed webhook → Personal | Shipped (V6.1) |
+| Installable npm package (`npm pack` / global tarball) | Shipped (V6.2) |
+| Simulated subscribe without Stripe keys | Kept for offline/dev |
+| Ed25519 signed entitlements + cache/grace | Shipped |
+| **Undo never paywalled** | Invariant + tested |
+
+## Product boundary
+
+- **CORE** — transaction engine, adapters, undo, CAS, permissions (no billing)
+- **SERVICE** — local API, MCP, project setup
+- **CLIENT** — control UI
+- **COMMERCIAL** — auth, Stripe, signed entitlement (separate from Core)
+
+## Honest language
+
+**REWIND CONNECTED** — mediated actions will be recorded.  
+Native Cursor writes outside MCP are **not** authoritative transactions.
+
+## User journey (test mode)
+
+```bash
+npm install && npm run build
+npm pack && npm install -g ./rewind-ai-cli-*.tgz
+rewind setup
+rewind login --email you@example.com
+rewind subscribe          # SIMULATED without keys; STRIPE TEST MODE with sk_test_ + price_
+rewind open               # control UI on 127.0.0.1
+# Ask Cursor to create a file via REWIND MCP
+rewind transactions
+rewind undo <id>
+```
+
+## REAL STRIPE SANDBOX PROOF
+
+```bash
+# .env (gitignored) with sk_test_…, price_…, whsec_… from stripe listen
+rewind api
+stripe listen --forward-to http://127.0.0.1:7429/v1/commercial/stripe/webhook
+rewind login --email you@example.com
+rewind subscribe          # opens real Checkout — does NOT activate locally
+# Complete TEST payment → signed webhook → Personal entitlement
+rewind status             # Entitlement: REWIND Personal
+```
+
+Webhook path: `POST /v1/commercial/stripe/webhook` on the local loopback API (default port **7429**).
+
+## PLANNED / NOT DONE
+
+- Published npm package / Homebrew tap / notarised macOS app
+- Production Auth0/Clerk OIDC credentials
+- Production entitlement signing service (private key offline)
+- Customer Portal wiring
+- Website checkout wiring
+- Hosted commercial HTTP (non-loopback)
+
+See [HUMAN-SETUP.md](./HUMAN-SETUP.md) and [PACKAGING.md](./PACKAGING.md).

package/docs/PROTECTED-SESSIONS.md

@@ -0,0 +1,155 @@
+# REWIND V4 — Protected Cursor Sessions
+
+## Verdict
+
+**Model A (intercept + transactionalise) is proven** for supported Cursor Agent tool paths in a project configured with REWIND hooks.
+
+Workflow:
+
+```bash
+npm run rewind -- protect ./sandbox-v4-project
+# open sandbox-v4-project in Cursor — use the agent normally
+npm run rewind -- status
+npm run rewind -- undo-session rw_…
+```
+
+The user does **not** need to say “use rewind_write_file.”
+
+---
+
+## Architecture (Model A)
+
+```
+Cursor Agent Write / StrReplace / Delete
+        │
+        ▼
+  preToolUse (failClosed)
+        │  capture BEFORE → CAS
+        │  create PREPARED/EXECUTING action
+        │  permission: allow
+        ▼
+  Cursor performs native mutation
+        │
+        ▼
+  postToolUse / afterFileEdit
+        │  capture AFTER → CAS
+        │  mark COMPLETED
+        ▼
+  .rewind/actions + audit ledger
+
+Shell (beforeShellExecution, failClosed)
+  read-only allowlist → allow
+  mutation / opaque interpreters → deny
+```
+
+**Provenance claim (precise):**
+
+> Cursor Agent requested this tool operation during protected session X.
+
+**Not claimed:** OS-level authorship (PID wrote these bytes).
+
+---
+
+## Lifecycle
+
+1. `protect <path>` — validate root, init `.rewind`, baseline fingerprint, create `ProtectedSession`, merge hooks/MCP, self-test, print summary.
+2. Developer opens the project in Cursor and works normally.
+3. Hooks ledger native mutations; shell policy blocks dangerous commands.
+4. `status` / `sessions` / `actions` — inspect.
+5. `undo-session <id>` — reverse COMPLETED actions newest→oldest with conflict protection.
+6. `unprotect` — remove only REWIND-managed hook/MCP entries; keep history.
+
+---
+
+## Trust model
+
+| State | Meaning |
+|-------|---------|
+| AUTHORITATIVE | Session mutations explained by COMPLETED CURSOR_HOOK actions (or clean baseline) |
+| UNTRUSTED | Unexplained mutation / incomplete actions / drift — **not** attributed to Cursor without hook evidence |
+
+Human keyboard edits are **not** claimed as Cursor actions. If drift detection sees them → `UNKNOWN_MUTATION` / UNTRUSTED.
+
+---
+
+## Cursor hooks installed
+
+| Event | failClosed | Role |
+|-------|------------|------|
+| `sessionStart` | false | Crash recovery + context note |
+| `sessionEnd` | false | Bind cursor session ids |
+| `preToolUse` (Write\|Delete\|StrReplace\|EditNotebook\|Shell) | **true** | BEFORE capture / shell redirect to beforeShell path |
+| `postToolUse` | false | AFTER capture |
+| `postToolUseFailure` | false | Mark FAILED |
+| `afterFileEdit` | false | Secondary AFTER capture |
+| `beforeShellExecution` | **true** | Conservative shell policy |
+| `beforeMCPExecution` | false | Allow (MCP optional for Model A) |
+
+Security-critical gates use `failClosed: true`: hook crash, timeout, or invalid JSON **blocks** the action (Cursor behaviour).
+
+---
+
+## Shell policy
+
+Prefer false-positive blocks over silent mutation.
+
+- **Allow:** `pwd`, `ls`, `cat`, `grep`/`rg`, `find` (no `-delete`/`-exec`), `git status|diff|log|…`, `echo`/`printf` without redirects.
+- **Deny:** redirects (`>`, `>>`), `rm`/`mv`/`cp`/`mkdir`/`touch`/`sed -i`, **and** opaque interpreters (`node`, `python`, `bash`, `npm`, …) even without obvious redirects.
+
+Indirect writes via `node -e '…writeFile…'` are **blocked**.
+
+---
+
+## Session undo
+
+1. Load COMPLETED actions for session.
+2. Sort newest → oldest.
+3. For each: if current == recorded AFTER → restore BEFORE; else CONFLICT (preserve bytes) and continue.
+4. Status: `UNDONE` | `PARTIALLY_UNDONE` | `CONFLICTED`.
+
+---
+
+## Crash recovery
+
+Incomplete `PREPARED`/`EXECUTING` actions (pre fired, post missing) are marked `FAILED` on next `protect` / `sessionStart` recovery. No fabricated AFTER state.
+
+---
+
+## Human vs agent
+
+Hooks bound the **Cursor agent tool loop only**. The human can edit in the editor freely. This is not OS filesystem lockdown (see V3).
+
+---
+
+## Limitations
+
+- Only projects with REWIND hooks loaded (open the protected folder as the workspace).
+- Tab / non-agent edit paths may not hit the same hooks.
+- Opaque shell is denied rather than checkpointed.
+- Observation is of Cursor’s declared tool use — not kernel provenance.
+- MCP is optional for Model A; ledgering is hook-based.
+
+---
+
+## Manual testing
+
+See the final V4 report in-chat, or:
+
+```bash
+npm run rewind -- protect ./sandbox-v4-project
+# Open sandbox-v4-project in Cursor; refactor auth without mentioning REWIND
+npm run rewind -- status
+npm run rewind -- undo-session <id>
+```
+
+Fail-closed demo helpers (tests / harness):
+
+- `breakProtectHook(projectRoot)` / `restoreProtectHook(projectRoot)`
+
+---
+
+## Allowed security claim
+
+> REWIND can protect filesystem changes made through supported Cursor Agent tool paths in a project configured with REWIND hooks.
+
+Not allowed: “prevents all AI writes”, “OS-level protection”, “every Cursor filesystem change is guaranteed mediated.”

package/docs/THREAT-MODEL.md

@@ -0,0 +1,84 @@
+# Threat Model (V5) — brutally accurate
+
+## Trust boundaries
+
+| Zone | Trust |
+|------|--------|
+| Mediated path (MCP/CLI/API → engine → adapter) | **Authoritative provenance** for what REWIND executed |
+| Native Cursor edits / shell / other processes | **Untrusted observation only** — not mediated actions |
+| `.rewind/` ledger + CAS | Local integrity assumed; not cryptographically sealed against the same user |
+
+## Mediated vs bypassed
+
+- **Mediated:** action entered via REWIND tools/engine → before/after recorded → undo may be safe.
+- **Bypassed:** same-UID write outside REWIND → may appear in watchers → **must never** be labelled authoritative mediated provenance.
+
+Observation is not attribution. V1 proved this; V5 does not reverse that finding.
+
+## MCP is not universal enforcement
+
+MCP is a **mediation route**. Agents (and Cursor native tools) can still mutate the filesystem without calling REWIND. Enforcement (V3 hooks/seatbelt/fs-readonly) is a separate, partial experiment on `sandbox-enforced-project`.
+
+## Same-UID problems
+
+REWIND runs as the user. Anything the user can write, another process under the same UID can write — including:
+
+- Cursor built-in apply/write tools
+- Shell `>` / `tee` / editors
+- Malicious or confused agents skipping MCP
+
+Mandatory mediation is **not** achieved for the general Cursor workspace.
+
+## Hooks limitations
+
+Cursor hooks can deny some tool calls when the hook runner works. Fail-closed hooks that **crash** (e.g. runner init failure) can brick the agent or, if failClosed is disabled, fail open. Hooks are not a kernel boundary.
+
+## Sandbox limitations
+
+Approved sandboxes (`sandbox-test-project`, `sandbox-enforced-project`) constrain MCP path safety. They do not stop native edits to those trees unless additional enforcement is enabled — and even then, same-UID bypasses remain.
+
+## Local API attack surface
+
+- Binds **127.0.0.1 only** (not `0.0.0.0`).
+- Bearer token written to `.rewind/api-token` (mode 0600) and required for mutating routes.
+- Any local process that can read the token can approve/undo. Treat workstation compromise as full compromise.
+- No TLS; loopback only.
+
+## Approval TOCTOU
+
+Mitigated for **target state fingerprint** change between ASK and APPROVE. Remaining risks:
+
+- Intent fields are not re-hashed beyond adapter revalidation
+- Approver confusion / social engineering
+- Clock / ordering races across multiple pending approvals on related paths
+
+## Ledger & CAS tampering
+
+A local attacker (or the agent itself) can edit `.rewind/actions`, `.rewind/transactions`, or `.rewind/objects`. V5 does **not** provide tamper-evident sealing or remote attestation. Provenance is trustworthy only relative to an untampered local REWIND home.
+
+Malicious agents may attempt to alter `.rewind` to fake undo safety. Path safety blocks MCP from targeting `.rewind/**`, but shell/native writes can still reach it.
+
+## Process crash
+
+Incomplete `PREPARED` / `EXECUTING` / `UNDOING` → marked `FAILED` on recovery.  
+`AWAITING_APPROVAL` is preserved (not treated as crash debris).  
+Partial mutations mid-execute can leave filesystem dirty with FAILED ledger entries — operator must inspect.
+
+## Entitlement
+
+Development provider always allows mediation. A future paid provider can deny mediation, but cannot stop bypass writes.
+
+## Authentication & commercial (V6)
+
+- Browser login preferred; LocalDevAuth for test; OIDC when configured
+- Credentials in `~/.rewind/credentials.json` (0600); optional macOS Keychain mirror
+- Signed entitlements (ed25519); private key never in the distributed app
+- Stripe webhooks must be signature-verified; idempotent event ids
+- Licence theft: cached entitlement is bound to installation id in claims (soft); full device attestation is PLANNED
+- Entitlement replay/tamper: signature verification required; tampered payloads fall back to free mediation — **undo still works**
+- Local API remains loopback + bearer token
+- Uninstall never deletes recovery data unless `--delete-recovery-data --yes`
+- Update channel must not wipe `.rewind/`
+
+Until then: **REWIND proves control for actions that choose to go through it**, not total containment of all agent I/O.
+

package/docs/TRANSACTIONS.md

@@ -0,0 +1,57 @@
+# Transactions (V5)
+
+## EXISTS
+
+### Model
+
+`Transaction` (version 5) is the in-memory / overlay / query model:
+
+- identity: `id`, `sequence`, `sessionId`, `createdAt`
+- `actor` / `authority` / `source`
+- `adapter` + `operation` + `target`
+- `before` / `after` (adapter-typed payloads)
+- `reversibility`, `permission`, `status`, `undo`
+- filesystem keeps `legacyTool` for MCP/CLI compatibility
+
+On disk for filesystem actions:
+
+1. **v2 ActionRecord** — `.rewind/actions/act_….json` (backwards compatible)
+2. **v5 overlay** — `.rewind/transactions/act_….json` (full Transaction)
+
+Existing V2/V3 action files remain readable via compatibility mapping.
+
+### Status lifecycle
+
+```
+PREPARED → AWAITING_APPROVAL → DENIED
+         → EXECUTING → COMPLETED → UNDOING → UNDONE
+                     → FAILED
+         → DENIED
+COMPLETED → CONFLICTED   (undo refused)
+```
+
+Invalid transitions throw `InvalidTransitionError`.
+
+### Reversibility classes
+
+| Class | Meaning in V5 |
+|-------|----------------|
+| REVERSIBLE | Exact restore when current == after (FS ops) |
+| COMPENSATABLE | Domain concept only — **no compensation implemented** |
+| APPROVAL_REQUIRED | Policy/intent classification; not auto-executed |
+| IRREVERSIBLE | No safe inverse |
+
+### Undo
+
+1. Load transaction  
+2. Adapter `compareExpectedCurrent`  
+3. If mismatch → CONFLICTED, refuse  
+4. Else adapter `reverse` + verify  
+
+Human/newer work wins.
+
+## PLANNED
+
+- Event-sourced append-only status log (today: overlay + action file updates for status fields)
+- Cross-adapter dependency graphs
+- Compensating transactions for non-FS adapters