@patze/code-cli 0.10.2

package/docs/patze-cli-architecture.md

@@ -0,0 +1,137 @@
+# Patze CLI architecture
+
+Status: **Phase 4E — Session apply history & drift recovery UX** (2026-05-27)  
+Package: `@patze/code-cli` · binary: `patze`
+
+Quality benchmark for permission selector layout: external [OpenAI Codex CLI](https://github.com/openai/codex) permission menu (reference only).
+
+## Agent loop (trust chain)
+
+```
+prompt → inspect → plan → diff → permissions → approve → apply → verify
+  ✅       ✅       ✅      ✅        ✅          ✅       ✅       ✅
+```
+
+| Stage | Status | Notes |
+|-------|--------|-------|
+| prompt | ✅ | Free text or `/goal` |
+| inspect | ✅ | Local read-only summary |
+| plan | ✅ | Server preview when auth ready |
+| diff | ✅ | Read-only patch proposal |
+| permissions | ✅ | Codex-like selector; `edit-with-approval` enables apply |
+| approve | ✅ | Gate object; requires `/diff` + suggest/edit-with-approval |
+| apply | ✅ | Interactive only; typed `APPLY <digest>` confirmation |
+| verify | ✅ | Local read-only check of last apply; repeatable |
+
+## Gated apply (Phase 4C)
+
+### Preconditions (fail-closed)
+
+1. Permission mode = `edit-with-approval`
+2. Active `ApprovalGate` matching latest `DiffReviewState`
+3. Session preview still carries same `artifact_digest` / `preview_digest` + patch body
+4. Exact confirmation phrase: `APPLY ${maskDigest(artifact_digest)}`
+5. No active verify drift recovery block (Phase 4E)
+
+### Patch application
+
+- Module: `runtime/patch-apply.ts` + `runtime/unified-diff.ts`
+- Applies unified diff from approved server preview only
+- Validates workspace root, deny rules, relative paths
+- Rejects: absolute paths, `..` traversal, binary diffs, shell-style diff commands
+- **Never** invokes shell
+
+### Session updates after apply
+
+- `lastApplyResult` records files written, per-file `beforeHash` / `afterHash`, `appliedAt`, `gateConsumed`
+- `applyHistory[]` append (max 20, process-local only)
+- `consumedGateKeys` prevents repeated `/apply` from the same gate
+- Approval gate and pending review cleared
+- `patze code apply` remains disabled (no `--yes`)
+
+## Safe verify (Phase 4D)
+
+### Scope
+
+- Interactive `/verify` only; **repeatable** (re-check drift anytime)
+- Verifies **last apply result in session** — not historical runs
+- Read-only filesystem checks + content hash comparison
+- **Never** runs shell, npm test, or network calls
+
+### Checks (fail-closed)
+
+1. `lastApplyResult` exists
+2. Approval gate inactive; no pending `approved_apply_patch`
+3. Gate key marked consumed in session
+4. Each applied file: workspace boundary, existence, `afterHash` match
+
+### Status
+
+| Status | Meaning |
+|--------|---------|
+| `passed` | All checks OK — clears drift recovery block |
+| `failed` | Drift or session inconsistency — activates drift recovery |
+| `unavailable` | No prior apply in session |
+
+### Non-interactive
+
+- `patze code verify` → help-only / local-safe summary
+- Command-based project test/lint verify → **future gated capability**
+
+## Drift recovery (Phase 4E)
+
+Module: `cli/commands/trust-loop-snapshot.ts`, `cli/commands/verify-drift-guard.ts`
+
+### On verify failure
+
+1. Store `lastVerifyResult` with `issues[]`
+2. Set `verifyDriftBlocked = true`
+3. Clear approval gate, diff review, pending actions (no file writes)
+4. Block `/approve` and `/apply` until recovery
+
+### Recovery paths
+
+| Action | Effect |
+|--------|--------|
+| Fix files + `/verify` (pass) | Clears drift block |
+| `/reject` | Clears pending gate + drift block; no file writes |
+| `/diff` | Allowed (read-only review) while blocked |
+
+### Trust-loop snapshot (`/status`, `/context`)
+
+Redacted view of permission, goal, pending state, apply history, last apply/verify summaries.
+
+**Limitation:** apply history is in-memory for the current process only — no persistence, no runs sync.
+
+## Permission modes
+
+| Mode | Phase | Writes |
+|------|-------|--------|
+| `read-only` | active | none |
+| `suggest` | active | none; approval gate only |
+| `edit-with-approval` | active | gated `/apply` only |
+| `full-auto` | forbidden | never |
+
+## Safety model
+
+1. No auto-apply in any mode.
+2. No SSE, execute, or runs sync.
+3. No backend contract changes for apply/verify.
+4. Interactive confirmation is mandatory for apply.
+5. Verify and `/reject` recovery never modify files.
+
+## Dev instructions
+
+```bash
+cd packages/patze-code-cli
+npm run verify
+```
+
+## Non-goals (Phase 4E)
+
+- `--yes` non-interactive apply
+- `patze code apply` mutation path
+- Shell-based verify (npm test, lint, typecheck)
+- Persistent apply history across process restarts
+- execute / runs sync
+- full-auto permission

package/docs/patze-cli-codex-reference-study.md

@@ -0,0 +1,43 @@
+# Patze CLI — Codex reference study
+
+Status: **Phase 0** reference notes (2026-05-28)  
+Benchmark: [openai/codex](https://github.com/openai/codex) public repo and docs — **quality bar only**, not a product copy.
+
+## What Codex optimizes for
+
+| Area | Codex pattern | Patze adoption |
+|------|---------------|----------------|
+| Install | curl/npm/Homebrew; single binary name | `@patze/code-cli` npm first; binary `patze`; Homebrew later |
+| Entry | `codex` opens TUI; `codex "prompt"` one-shot | Phase 1b TUI; Phase 1 one-shot via `patze goal --dry-run` |
+| Help | Short top-level help; deeper docs linked | `patze --help` + package docs |
+| Workspace | Local cwd; Rust core owns sandbox | `runtime/workspace.ts`; server owns execute policy |
+| Approval | Explicit trust/sandbox posture | `runtime/approvals.ts`; default preview-first |
+| Patches | Inline diff presentation in TUI | `cli/ui/diff-view.ts`; server artifact truth later |
+| Progress | Streaming phases + tool trace | Phase 4 SSE client against PatzeAgents |
+| Packaging | Multi-platform binaries + npm | Node 20 ESM now; optional native lane later |
+| Docs | install.md, contributing, auth guides | README + architecture + rollout notes |
+
+## Command UX patterns worth copying (behavior, not names)
+
+1. **Deterministic subcommands** — stable verbs (`status`, `login`, `goal`, `code`, `runs`).
+2. **Safe defaults** — dry-run / preview before apply.
+3. **Structured status** — one screen answers “am I configured?” and “can I reach backend?”
+4. **Progress semantics** — queued → running → completed/failed; never infer success from stream close alone.
+5. **Patch review** — human-readable diff before write; apply is a separate explicit action.
+
+## Patze deliberate differences
+
+- Auth via **Patze internal API key + user UUID**, not ChatGPT OAuth.
+- Execute/verify authority stays on **FastAPI PatzeAgents** (`/internal/patze-code/*`).
+- No OpenAI/Codex branding in user-facing strings.
+- No `--dangerously-skip-permissions` equivalent.
+
+## Non-goals (this study)
+
+- Copying Codex Rust crate layout verbatim into Patze.
+- Shipping Cursor SDK or `CURSOR_API_KEY` flows to end users.
+- Rebuilding OpenAI cloud auth in the CLI.
+
+## Rollout note
+
+When adding server-backed commands, gate behind explicit flags and keep Phase 0 dry-run paths working without network.

package/docs/release-checklist.md

@@ -0,0 +1,83 @@
+# Release checklist — @patze/code-cli internal beta
+
+Use before tagging `0.10.x` for team rollout. **Not** npm `latest` / 1.0 gate.
+
+## Version bump
+
+- [ ] `VERSION` matches `package.json` version
+- [ ] `CHANGELOG.md` entry for this version
+- [ ] README version pins and command tables updated
+- [ ] `scripts/verify-version.mjs` passes
+
+## Build and verify
+
+```bash
+cd packages/patze-code-cli
+npm run verify
+```
+
+Includes:
+
+- [ ] `verify-version.mjs`
+- [ ] `tsc` build
+- [ ] `verify-pack.mjs` (tarball audit)
+- [ ] `typecheck`
+- [ ] unit tests (`node --test tests/*.test.mjs`)
+- [ ] `smoke-beta.mjs` (temp workspace + local pack install)
+
+Individual commands:
+
+```bash
+npm run verify:pack -- --verbose
+npm run smoke
+npm pack --dry-run
+```
+
+## Package contents
+
+- [ ] `files` in `package.json`: `bin`, `dist`, `docs`, `README`, `CHANGELOG`, `NOTICE`, `VERSION`
+- [ ] No `src/`, `tests/`, `.cookbook-vendor`, `.env` in pack output
+- [ ] Required docs present (see `verify-pack.mjs` `REQUIRED_PATHS`)
+
+## Safety / capability truthfulness
+
+- [ ] README **implemented vs planned** table accurate
+- [ ] `patze code apply` still disabled
+- [ ] No `--yes`, no auto-apply, no full-auto
+- [ ] Verify remains local read-only (no shell)
+- [ ] No new backend contract changes in this slice
+- [ ] No telemetry upload added
+
+## Secrets hygiene
+
+- [ ] `verify-pack` secret scan clean on publish tree
+- [ ] Rollout docs/scripts use placeholders (`<token>`, `api.example.com`)
+- [ ] No real home paths or tokens in committed docs
+- [ ] `patze doctor` / `patze status` mask tokens in output
+
+## Rollout assets (0.10.2+)
+
+- [ ] `docs/install-beta.md` + `scripts/install-beta.sh`
+- [ ] `docs/beta-tester-checklist.md`
+- [ ] `docs/beta-feedback-template.md`
+- [ ] `docs/known-limitations.md`
+- [ ] `docs/smoke-command-guide.md`
+- [ ] `docs/uninstall-reset.md`
+
+## Publish (when ready)
+
+```bash
+npm publish --tag beta
+# or team tarball handoff:
+npm pack
+```
+
+## Post-publish smoke (testers)
+
+Hand testers [`install-beta.md`](install-beta.md) and confirm:
+
+```bash
+patze --version
+patze doctor
+patze status
+```

package/docs/safety-model.md

@@ -0,0 +1,69 @@
+# Safety model
+
+`@patze/code-cli` is a **local terminal client**. PatzeAgents server remains authoritative for auth, entitlements, artifacts, and policy. The CLI defaults **fail-closed**.
+
+## Non-negotiables
+
+| Rule | Enforcement |
+|------|-------------|
+| No auto-apply | Writes only via gated interactive `/apply` |
+| No `--yes` | Apply requires typed `APPLY <masked-artifact-digest>` |
+| No shell execution | Verify is read-only filesystem + hash checks only |
+| No `full-auto` | Permission mode is forbidden permanently |
+| No SSE / runs sync | No background run streaming or remote run mutation |
+| No backend contract changes from CLI | Client adapts to existing PatzeAgents APIs |
+
+## Permission modes
+
+| Mode | Reads | Approval gate | File writes |
+|------|-------|---------------|-------------|
+| `read-only` | ✅ | ❌ | ❌ |
+| `suggest` | ✅ | ✅ | ❌ |
+| `edit-with-approval` | ✅ | ✅ | ✅ gated `/apply` only |
+| `full-auto` | — | — | **forbidden** |
+
+## Gated apply preconditions
+
+All must pass before any file write:
+
+1. Permission = `edit-with-approval`
+2. Active approval gate matching latest `/diff` review
+3. Session preview digests + patch body still match gate
+4. Exact confirmation phrase
+5. No active verify drift recovery block
+
+## Verify scope
+
+- Checks **last apply in current session only**
+- Local read-only: workspace boundary, file existence, content hash vs apply snapshot
+- Repeatable (`/verify` may be run multiple times)
+- Does **not** run npm test, lint, typecheck, or arbitrary shell commands
+
+## Drift recovery
+
+When `/verify` fails:
+
+- `/approve` and `/apply` are blocked
+- `/reject` clears pending gate + drift state — **never modifies files**
+- Fix files manually + `/verify` pass, or `/reject` and restart trust loop
+
+## Redaction
+
+Session output masks:
+
+- Artifact and preview digests (`artifa…90ab` style)
+- API tokens (`configured` / masked, never full value in `/status`)
+
+Never log or print raw bearer tokens in normal operator flows.
+
+## Workspace boundaries
+
+Default deny patterns include `.env`, `node_modules`, `.git`. Patches reject absolute paths, `..` traversal, binary diffs, and shell-style diff commands.
+
+## Internal beta limits
+
+- Apply history is **in-memory for current process** — not persisted across restarts
+- No remote run sync or server-side apply receipt (future read-only slice)
+- Shell-based project verification remains a **future gated capability**
+
+See also: [`trust-loop.md`](trust-loop.md), [`internal-beta.md`](internal-beta.md).

package/docs/smoke-command-guide.md

@@ -0,0 +1,61 @@
+# Smoke command guide — maintainers
+
+Quick reference for release verification. Beta testers can use the lighter checklist in [`beta-tester-checklist.md`](beta-tester-checklist.md).
+
+## Full verify (recommended before tag)
+
+```bash
+cd packages/patze-code-cli
+npm run verify
+```
+
+Runs: version check → build → pack audit → typecheck → unit tests → smoke.
+
+## Individual commands
+
+| Command | Purpose |
+|---------|---------|
+| `npm run build` | Compile TypeScript to `dist/` |
+| `npm run typecheck` | `tsc --noEmit` |
+| `npm test` | Unit tests (requires build) |
+| `npm run verify:pack` | Audit `npm pack` output |
+| `npm run verify:pack -- --verbose` | JSON summary of pack manifest |
+| `npm run smoke` | Temp workspace CLI smoke + local install |
+| `npm run smoke -- --skip-install` | Skip tarball install step |
+
+## What smoke covers
+
+- `patze --version`
+- `patze --help`
+- `patze status` (auth/cwd lines)
+- `patze code inspect`
+- `patze goal … --dry-run`
+- `patze code verify` (help/safety text)
+- `patze code apply` (disabled message)
+- Optional: `npm pack` → global install → `patze --version`
+
+Smoke does **not** exercise interactive `/apply` (requires stdin). Use manual trust-loop checklist for that.
+
+## Pack audit (`verify-pack`)
+
+Fails closed on:
+
+- Blocked paths: `.cookbook-vendor`, `src/`, `tests/`, etc.
+- Missing required publish files
+- Secret-like patterns in text files (keys, bearer tokens, home paths)
+
+## Install script smoke
+
+```bash
+./scripts/install-beta.sh local
+patze doctor
+```
+
+## Troubleshooting
+
+| Symptom | Check |
+|---------|-------|
+| `dist_main: missing` in doctor | Run `npm run build` |
+| verify-pack home-path hit | Remove real `/home/...` from docs |
+| smoke install fail | Node 20+, npm global prefix writable |
+| status exit 1 | Expected without auth — not a smoke failure |

package/docs/trust-loop.md

@@ -0,0 +1,90 @@
+# Trust loop
+
+The Patze Code CLI interactive trust loop is the operator path from intent to verified local apply.
+
+```
+prompt → inspect → plan → diff → permissions → approve → apply → verify
+```
+
+## Stages
+
+| Stage | Command | Mutates files? |
+|-------|---------|----------------|
+| prompt | free text or `/goal` | No |
+| inspect | `/inspect` or `patze code inspect` | No |
+| plan | `/plan` or `patze code plan --preview` | No |
+| diff | `/diff` | No (read-only patch view) |
+| permissions | `/permissions` | No |
+| approve | `/approve` | No (gate only) |
+| apply | `/apply` + confirmation | **Yes** (gated) |
+| verify | `/verify` | No (read-only check) |
+
+## Example session
+
+```text
+patze
+/goal Improve README quickstart
+/plan
+/diff
+/permissions suggest
+/approve
+/permissions edit-with-approval
+/apply
+APPLY artifa…90ab
+/verify
+/status
+```
+
+## Permission flow
+
+1. **`suggest`** — review and approve patches; no writes
+2. **`edit-with-approval`** — enables `/apply` after approval gate is set
+
+Direct set: `/permissions read-only|suggest|edit-with-approval`
+
+## After apply
+
+```
+Next
+  /verify — check applied files
+  /status
+  /exit
+```
+
+## Session visibility
+
+`/status` and `/context` show a redacted trust-loop snapshot:
+
+- permission mode, goal, pending diff/approval
+- apply history (this process only)
+- last apply and last verify summaries (masked digests)
+
+## Drift recovery
+
+If `/verify` reports `status: failed`:
+
+```
+Recommended next steps
+  /diff — review latest proposed patch
+  /reject — clear pending gate and drift recovery
+  manual review — file changed after apply
+```
+
+## Non-interactive commands
+
+| Command | Status |
+|---------|--------|
+| `patze code inspect` | ✅ read-only |
+| `patze code plan --preview` | ✅ server preview when auth configured |
+| `patze code diff` | ✅ read-only |
+| `patze code apply` | ❌ disabled — use interactive `/apply` |
+| `patze code verify` | ℹ️ help-only summary |
+
+## Planned (not in 0.10.x beta)
+
+- Shell-based verify (npm test / lint / typecheck)
+- `patze runs` sync
+- Non-interactive apply (`--yes`)
+- Server-side apply receipt (read-only)
+
+See [`safety-model.md`](safety-model.md) for boundaries.

package/docs/uninstall-reset.md

@@ -0,0 +1,44 @@
+# Uninstall and reset — internal beta
+
+## Uninstall global CLI
+
+```bash
+npm uninstall -g @patze/code-cli
+which patze   # should print nothing
+```
+
+If you installed from a local tarball, the same command applies (`npm uninstall -g @patze/code-cli`).
+
+## Reset local credentials (optional)
+
+Patze Code stores config under your user config directory and optional project `.patze/` files.
+
+1. Remove or edit global config (path shown by `patze doctor` under **config** — values redacted).
+2. Remove project override if present: `.patze/config.json` in your workspace.
+3. Unset env vars:
+
+```bash
+unset PATZE_CODE_API PATZE_CODE_TOKEN PATZE_CODE_USER_ID
+```
+
+## Reset interactive session only
+
+Inside `patze` shell:
+
+```text
+/reset    # clears agent session state (in-memory)
+/clear    # clears transcript
+/exit
+```
+
+Session apply history is **process-local** — restarting `patze` clears it.
+
+## Clean beta fixture workspace
+
+```bash
+rm -rf /tmp/patze-beta   # or your chosen test directory
+```
+
+## Reinstall fresh
+
+See [`install-beta.md`](install-beta.md).

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@patze/code-cli",
+  "version": "0.10.2",
+  "description": "Patze Code — local terminal coding agent client for PatzeAgents",
+  "license": "UNLICENSED",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "patze": "bin/patze.mjs"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "docs",
+    "CHANGELOG.md",
+    "NOTICE.md",
+    "README.md",
+    "VERSION"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "verify:pack": "npm run build && node scripts/verify-pack.mjs --verbose",
+    "smoke": "node scripts/smoke-beta.mjs",
+    "verify": "node scripts/verify-version.mjs && npm run build && node scripts/verify-pack.mjs && npm run typecheck && npm test && node scripts/smoke-beta.mjs"
+  },
+  "keywords": [
+    "patze",
+    "patze-code",
+    "coding-agent",
+    "cli"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}