@jx-grxf/patchpilot 0.4.0 → 1.2.0

package/dist/tui/runStatus.js

@@ -0,0 +1,164 @@
+/**
+ * Run-status verbs. The spinner glyph animates fast; the verb stays stable and
+ * only rotates on a slow cadence, and it advances in a pseudo-random order so
+ * it never feels like a fixed list cycling.
+ */
+export const runStatusVerbs = [
+    "Accomplishing",
+    "Actioning",
+    "Architecting",
+    "Baking",
+    "Bootstrapping",
+    "Brewing",
+    "Calculating",
+    "Cascading",
+    "Channeling",
+    "Composing",
+    "Computing",
+    "Concocting",
+    "Considering",
+    "Contemplating",
+    "Cooking",
+    "Crafting",
+    "Creating",
+    "Crunching",
+    "Crystallizing",
+    "Deciphering",
+    "Deliberating",
+    "Determining",
+    "Distilling",
+    "Elucidating",
+    "Envisioning",
+    "Forging",
+    "Generating",
+    "Hatching",
+    "Ideating",
+    "Imagining",
+    "Improvising",
+    "Incubating",
+    "Inferring",
+    "Inspecting",
+    "Manifesting",
+    "Mulling",
+    "Musing",
+    "Orchestrating",
+    "Percolating",
+    "Pondering",
+    "Processing",
+    "Puzzling",
+    "Reasoning",
+    "Reticulating",
+    "Reviewing",
+    "Ruminating",
+    "Sketching",
+    "Spelunking",
+    "Synthesizing",
+    "Tinkering",
+    "Transmuting",
+    "Unravelling",
+    "Wrangling",
+];
+/** Past-tense verbs for the run-completion summary ("Crunched for 17m 58s"). */
+export const completionVerbs = [
+    "Crunched",
+    "Cooked",
+    "Brewed",
+    "Forged",
+    "Hammered",
+    "Conjured",
+    "Distilled",
+    "Wrangled",
+    "Orchestrated",
+    "Synthesized",
+    "Composed",
+    "Architected",
+    "Tinkered",
+    "Pondered",
+    "Crafted",
+    "Spelunked",
+];
+/** Braille spinner glyphs — the classic fast loading animation. */
+export const spinnerGlyphs = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+/** Pulsing accent glyphs used for completion / decorative markers. */
+export const pulseGlyphs = ["✻", "✺", "✷", "✶", "✦", "✶", "✷", "✺"];
+/** Fast spinner glyph cadence in ms. */
+export const spinnerFrameMs = 90;
+/** Wave / highlight animation cadence in ms. */
+export const waveFrameMs = 110;
+/** The verb only changes once every this many ms. */
+export const verbCycleMs = 10_000;
+export function randomRunStatusSeed(random = Math.random) {
+    return Math.floor(Math.max(0, Math.min(0.999999999, random())) * 0x7fffffff);
+}
+/** Small deterministic hash so verb order is pseudo-random, not sequential. */
+function hashTick(tick, seed) {
+    let value = (Math.trunc(tick) * 2654435761 + Math.trunc(seed) * 40503 + 0x9e3779b9) >>> 0;
+    value ^= value >>> 15;
+    value = (value * 0x85ebca6b) >>> 0;
+    value ^= value >>> 13;
+    return value >>> 0;
+}
+/** Pick the fast-animating braille glyph for the given frame counter. */
+export function spinnerGlyph(frame) {
+    const safe = Number.isFinite(frame) ? Math.abs(Math.trunc(frame)) : 0;
+    return spinnerGlyphs[safe % spinnerGlyphs.length] ?? spinnerGlyphs[0];
+}
+/** Pick a pulsing accent glyph for the given frame counter. */
+export function pulseGlyph(frame) {
+    const safe = Number.isFinite(frame) ? Math.abs(Math.trunc(frame)) : 0;
+    return pulseGlyphs[safe % pulseGlyphs.length] ?? pulseGlyphs[0];
+}
+/**
+ * Pick the run-status verb for the given elapsed time. The verb is stable for
+ * `verbCycleMs`, then jumps to a pseudo-random next verb (never a fixed cycle).
+ */
+export function runStatusVerb(elapsedMs, seed = 0) {
+    const safeElapsed = Number.isFinite(elapsedMs) && elapsedMs > 0 ? elapsedMs : 0;
+    const tick = Math.floor(safeElapsed / verbCycleMs);
+    let index = hashTick(tick, seed) % runStatusVerbs.length;
+    if (tick > 0) {
+        const previousIndex = hashTick(tick - 1, seed) % runStatusVerbs.length;
+        if (index === previousIndex) {
+            index = (index + 1 + (hashTick(tick + 1, seed) % (runStatusVerbs.length - 1))) % runStatusVerbs.length;
+        }
+    }
+    return runStatusVerbs[index] ?? runStatusVerbs[0];
+}
+/**
+ * Split the run status into its parts so the UI can animate the verb on its
+ * own and render the (stable) state/detail separately with clear spacing.
+ */
+export function runStatusParts(options) {
+    const verb = runStatusVerb(options.elapsedMs, options.seed);
+    const state = options.workState.replace(/_/g, " ");
+    const trimmedStatus = options.status?.trim() ?? "";
+    const detail = trimmedStatus && trimmedStatus !== state ? trimmedStatus : "";
+    return { verb, state, detail };
+}
+/** Format elapsed milliseconds as a compact human duration for the status line. */
+export function formatElapsed(elapsedMs) {
+    if (!Number.isFinite(elapsedMs) || elapsedMs <= 0) {
+        return "starting";
+    }
+    return formatRunDuration(elapsedMs);
+}
+/** Format a run duration like "4s" or "17m 58s". */
+export function formatRunDuration(elapsedMs) {
+    const totalSeconds = Math.max(0, Math.floor((Number.isFinite(elapsedMs) ? elapsedMs : 0) / 1000));
+    if (totalSeconds < 60) {
+        return `${totalSeconds}s`;
+    }
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    if (minutes < 60) {
+        return `${minutes}m ${String(seconds).padStart(2, "0")}s`;
+    }
+    const hours = Math.floor(minutes / 60);
+    return `${hours}h ${String(minutes % 60).padStart(2, "0")}m`;
+}
+/** Build a run-completion summary like "Crunched for 17m 58s". */
+export function formatCompletionSummary(elapsedMs, seed = 0) {
+    const verb = completionVerbs[hashTick(0, seed + 7) % completionVerbs.length] ?? completionVerbs[0];
+    return `${verb} for ${formatRunDuration(elapsedMs)}`;
+}
+//# sourceMappingURL=runStatus.js.map

package/dist/tui/runStatus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runStatus.js","sourceRoot":"","sources":["../../src/tui/runStatus.ts"],"names":[],"mappings":"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"}

package/dist/tui/types.d.ts

@@ -23,4 +23,12 @@ export type AdvisorNote = {
     role: SubagentRole;
     message: string;
 };
+export type ToolTelemetry = {
+    total: number;
+    succeeded: number;
+    failed: number;
+    approvals: number;
+    denied: number;
+    byTool: Partial<Record<AgentToolName | "subagent", number>>;
+};
 export declare const maxTranscriptLines = 300;

package/dist/tui/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tui/types.ts"],"names":[],"mappings":"AAiCA,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tui/types.ts"],"names":[],"mappings":"AA0CA,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAC"}

package/docs/architecture.md

@@ -0,0 +1,115 @@
+# Architecture
+
+PatchPilot is split into a small agent core and an Ink terminal interface.
+
+## Components
+
+| Component | Responsibility |
+|---|---|
+| `OllamaClient` | Sends chat requests to the selected Ollama HTTP API and reads host model state |
+| `compute` | Classifies the selected Ollama endpoint as local or remote compute |
+| `subagents` | Runs small planner/reviewer advisor calls before the primary agent loop |
+| `AgentRunner` | Maintains the model loop, work-state transitions, session events, and typed tool calls |
+| `WorkspaceTools` | Provides bounded file, search, patch, Git, test, and shell actions |
+| `SessionStore` | Persists append-only JSONL session events and updates the global session index |
+| `App` | Renders the TUI transcript, approval prompts, status, and prompt input |
+| `systemStats` | Samples CPU and memory usage for the live header telemetry |
+
+## Compute Model
+
+PatchPilot separates the client machine from the compute machine:
+
+- The client machine runs the TUI, reads and writes workspace files, runs Git, and executes tests.
+- The compute machine runs Ollama inference.
+- `/connect` changes only the Ollama compute endpoint. It does not move workspace tools to the remote host.
+- Host discovery checks both the local LAN and reachable Tailscale peers, then verifies each candidate against Ollama's `GET /api/version`.
+- A localhost endpoint is classified as local compute. A LAN endpoint such as `http://192.168.1.50:11434` is classified as remote compute.
+
+This keeps the Windows-desktop-GPU plus MacBook-editing workflow simple: expose Ollama on the Windows machine, connect from the Mac, and keep all file operations local to the Mac workspace.
+
+## Subagents
+
+The first subagent layer is advisory and intentionally small:
+
+| Subagent | Purpose | Tool Access |
+|---|---|---|
+| Planner | Suggests likely files, order of work, and verification steps | None |
+| Reviewer | Calls out risk, missing tests, and platform concerns | None |
+
+Both subagents run as separate model calls before the primary agent starts. Their output is injected as advisory context only; the primary agent must still verify with workspace tools before changing code. This follows the useful part of the opencode `primary` vs `subagent` model without granting background agents write or shell permissions.
+
+## Native App Direction
+
+The target native structure is:
+
+| Layer | Direction |
+|---|---|
+| Core CLI | Keep the TypeScript/Node agent as the sidecar because it already owns tools, Ollama, and safety boundaries |
+| Desktop shell | Use Tauri for macOS and Windows instead of maintaining both Electron and Tauri |
+| Connect | Reuse the same Ollama compute endpoint model in CLI and desktop |
+| Security | Bind any local control server to loopback only and keep remote model traffic explicit |
+
+## Agent Protocol
+
+The first version uses a JSON command envelope instead of provider-specific tool calling. That keeps behavior portable across local models, including models that do not reliably emit native tool calls.
+
+Tool request:
+
+```json
+{
+  "action": "tools",
+  "message": "I need to inspect the project files.",
+  "tool_calls": [
+    {
+      "name": "list_files",
+      "arguments": {
+        "path": "."
+      }
+    }
+  ]
+}
+```
+
+PatchPilot exposes a `ToolSpec` registry for each tool. Specs describe risk, side effects, permission class, and transcript category. Tool calls execute sequentially so approval-gated reads, writes, and shell actions cannot overwrite each other's pending approval state.
+
+Longer runs can also call `update_todo` with a compact task snapshot. The runner stores that state separately from the transcript and the TUI renders it in the lower transcript area, with `in_progress` items animated and `completed` items checked.
+
+Final answer:
+
+```json
+{
+  "action": "final",
+  "message": "The repository is a TypeScript TUI agent..."
+}
+```
+
+## Sessions
+
+Each TUI launch creates a session id. Events are appended to `.patchpilot/sessions/<session-id>.jsonl` in the workspace:
+
+- `session.created`
+- `run.started`
+- `model.request`
+- `tool.requested`
+- `approval.requested`
+- `tool.completed`
+- `run.completed`
+- `run.failed`
+
+The workspace `.patchpilot/` folder is ignored by Git. A global index at `~/.patchpilot/session-index.json` keeps recent sessions discoverable for `patchpilot sessions`, `patchpilot resume`, `/sessions`, and `/resume`.
+
+## Release Publishing
+
+Tagged releases use `.github/workflows/release.yml`. The workflow verifies that `package.json` matches the tag, installs with `npm ci`, runs tests, builds, packs the CLI, publishes `@jx-grxf/patchpilot` to npm, and then creates or updates the GitHub Release with the `.tgz` artifact. Publishing uses the `NPM_TOKEN` repository secret when present and can fall back to npm trusted publishing if the package is configured for GitHub Actions OIDC on npm.
+
+## Safety
+
+The workspace root is resolved once at startup. Every file path is resolved against that root and rejected if it escapes the workspace. Writes and shell commands are blocked by default. In the TUI, risky tools request approval with allow-once, allow-session, or deny decisions. `--apply` and `--allow-shell` remain explicit compatibility switches for users who want global write or shell permission.
+
+## Telemetry
+
+PatchPilot reads Ollama's non-streaming chat metadata for prompt tokens, response tokens, total duration, and generation speed. Gemini reads API `usageMetadata`. Codex OAuth runs `codex exec --json` and parses the `turn.completed.usage` event, including `cached_input_tokens`, so the TUI can show real Codex CLI usage instead of only character-based estimates.
+
+Model discovery is cached in the current TUI session. Prompt execution reuses the known model list when the selected model is already present, avoiding repeated Gemini model-list calls and keeping Codex/Ollama discovery off the hot path.
+
+The TUI also keeps session-level accounting: request count, prompt tokens, cached prompt tokens, output tokens, total tokens, and estimated cost where public API token pricing is known. Local Ollama cost is reported as zero; Codex OAuth cost is shown as an API-price estimate because actual ChatGPT-plan quota handling is external to PatchPilot.

package/docs/gemini-wrapper.md

@@ -0,0 +1,110 @@
+# Gemini-Wrapper Setup
+
+PatchPilot can use `gemini_webapi` through the `gemini-wrapper` provider. This is an advanced, unofficial Gemini Web bridge. PatchPilot creates a managed Python venv only when you explicitly run `/doctor fix` or `patchpilot doctor --fix`, installs the pinned wrapper there, and starts the bridge command itself. It does not scan browser profiles or read cookies automatically.
+
+## 1. Let PatchPilot install the wrapper
+
+Do not run `python3 -m pip install -U gemini_webapi` against Homebrew Python. Homebrew blocks that with PEP 668.
+
+PatchPilot uses this managed venv instead:
+
+```sh
+~/.patchpilot/gemini-wrapper-venv
+```
+
+It creates the venv and installs the pinned `gemini_webapi` version when you explicitly approve `patchpilot doctor --fix` or `/doctor fix`. Normal chat startup does not install Python packages.
+
+## 2. Get the cookie values manually
+
+1. Open `https://gemini.google.com`.
+2. Open DevTools.
+3. Go to Application or Storage.
+4. Open Cookies for `https://gemini.google.com`.
+5. Copy `__Secure-1PSID`.
+6. Copy `__Secure-1PSIDTS` if it exists.
+
+Do not paste these values into issues, logs, chats, or commits. `__Secure-1PSID` acts like a Google session token.
+
+## 3. Run PatchPilot onboarding
+
+```sh
+patchpilot --provider gemini-wrapper
+patchpilot --provider gemini-wrapper --model flash
+patchpilot --provider gemini-wrapper --model flash-lite
+patchpilot --provider gemini-wrapper --model pro
+```
+
+Choose `Gemini-Wrapper` in setup. PatchPilot asks for:
+
+```text
+psid > ********
+ts   > ********
+```
+
+`psid` is required. `ts` is optional; press Enter to skip it.
+
+PatchPilot writes:
+
+```text
+~/.patchpilot/gemini-cookies.json
+```
+
+with owner-only file permissions (`0600`) and stores this config:
+
+```sh
+PATCHPILOT_PROVIDER=gemini-wrapper
+PATCHPILOT_MODEL=auto
+PATCHPILOT_GEMINI_WRAPPER_MODE=python
+PATCHPILOT_GEMINI_WRAPPER_COOKIES_JSON=/Users/you/.patchpilot/gemini-cookies.json
+PATCHPILOT_GEMINI_WRAPPER_MIN_INTERVAL_MS=1500
+PATCHPILOT_GEMINI_WRAPPER_TIMEOUT_MS=180000
+```
+
+If a pasted `__Secure-1PSIDTS` expires, PatchPilot retries the bridge request once without that optional timestamp. Transient WebAPI network timeouts are retried inside the bridge. Bridge calls are also serialized with a small default delay so advisor or agent requests do not hit the wrapper at the same instant. Set `PATCHPILOT_GEMINI_WRAPPER_MIN_INTERVAL_MS=0` only for debugging.
+
+The default bridge timeout is 180 seconds. `gemini-3-pro` can take longer through the unofficial WebAPI bridge, so PatchPilot gives Pro models at least 240 seconds. For fast local test loops, use `auto`; PatchPilot omits the model parameter and lets Gemini Web pick its current default.
+
+PatchPilot exposes current Gemini Web shortcuts through live bridge discovery:
+
+| PatchPilot model | Bridge behavior |
+| --- | --- |
+| `auto` | omit model and let Gemini Web choose |
+| `flash-lite` | resolve the live Flash-Lite model from `client.list_models()` and pass its `model_id` |
+| `flash` | prefer a live 3.5 Flash descriptor when the bridge exposes it; otherwise fall back to the current Flash descriptor or `gemini-3-flash` |
+| `pro` | resolve the live Pro descriptor when available; otherwise fall back to `gemini-3-pro` |
+| `thinking` | legacy compatibility alias for `gemini-3-flash-thinking` when available |
+
+Gemini Web now presents Denkaufwand/Thinking-Level controls rather than a recommended standalone `thinking` model. The unofficial `gemini_webapi` bridge does not expose that control as a stable PatchPilot option yet, so `/reasoning` reports the limitation instead of pretending to change Web Denkaufwand.
+
+## File Analysis
+
+Gemini-Wrapper file analysis uses the same `gemini_webapi` file pipeline documented by the upstream project: PatchPilot passes the approved file path as `files=[...]` to `GeminiClient.generate_content`. This is used by `inspect_document` for screenshots and images when the managed Python bridge is active, and as a fallback for PDFs/DOCX files when local text extraction cannot produce useful text.
+
+Supported direct file inputs include PNG, JPEG, WebP, GIF, HEIC/HEIF, PDF, and DOCX. PatchPilot still applies its own safety checks first: external absolute paths require file-analysis approval, sensitive paths are blocked, and browser cookie stores are never auto-scanned.
+
+By default, Gemini-Wrapper is tried first for images. PDFs use `pdftotext` first and DOCX is parsed from `word/document.xml` first; provider file analysis is used only when local document extraction fails or returns no useful text. Text/code files are read directly. Images can use local `tesseract` OCR when the user asks for `mode:"local"`/`mode:"ocr"`.
+
+The Python wrapper stores refreshed Google cookies in a PatchPilot-owned cache:
+
+```text
+~/.patchpilot/gemini-webapi-cache
+```
+
+PatchPilot creates that directory with owner-only permissions (`0700`) and passes it to `gemini_webapi` as `GEMINI_COOKIE_PATH`.
+
+## 4. Verify
+
+```sh
+patchpilot doctor --provider gemini-wrapper --check-model auto
+```
+
+Expected checks:
+
+- Node and Git are available.
+- `gemini_webapi` imports through `~/.patchpilot/gemini-wrapper-venv/bin/python`.
+- explicit cookie auth is configured.
+- the bridge lists Gemini models.
+
+## Security Boundary
+
+PatchPilot never scans Chrome, Safari, Firefox, Arc, Edge, Brave, Keychain, or browser cookie stores. The only supported auth sources are the masked paste onboarding flow, an explicit cookie JSON path, or explicit `GEMINI_SECURE_1PSID` environment variables.

package/docs/product-context.md

@@ -0,0 +1,43 @@
+# PatchPilot Product Context
+
+PatchPilot is a local-first, permissioned terminal coding agent. It is designed for repository work where the user wants every risky operation to be visible, reviewable, and easy to approve or deny.
+
+## Core Workflow
+
+1. Inspect the workspace with read-only tools.
+2. Keep a visible todo list for multi-step work.
+3. Propose or apply focused edits in build mode.
+4. Request scoped approvals for writes, package scripts, tests, and shell commands.
+5. Show Git diff, run checks, and leave commits or pull requests under the user's control.
+
+## Safety Model
+
+- `plan` mode is read-only.
+- `build` mode can request approvals for writes and shell actions.
+- `bypass` mode removes per-tool approval prompts only after an explicit trusted-workspace confirmation.
+- Session approvals are scoped to a concrete target such as a path, script body, patch hash, or normalized shell command.
+- Secrets, browser profiles, cookies, and credential files are denied by default.
+
+## TUI Surface
+
+- Header: current provider, model, route, mode, and high-level run state.
+- Sidebar: workspace, permissions, machine stats, session telemetry, and advisors.
+- Transcript: compact run log, tool results, todos, and live status.
+- Composer: bounded multiline prompt editor with visible newest input.
+- Command palette: `/models`, `/sessions`, `/connect`, `/doctor`, `/experimental`, and related commands.
+
+## Provider Matrix
+
+- Ollama: local or remote LAN/Tailscale inference.
+- Gemini: official Google Gemini API key.
+- Gemini-Wrapper: opt-in Gemini Web bridge through pinned `gemini_webapi`; Python bridge supports file analysis, HTTP wrapper mode does not.
+- OpenRouter: broad cloud model routing, including free variants.
+- NVIDIA: OpenAI-compatible NVIDIA NIM endpoints.
+- Codex: ChatGPT login through Codex CLI.
+
+## Useful First Questions
+
+- "What can PatchPilot do in this repo?"
+- "Summarize this project and list the safest next fixes."
+- "Find the test commands and explain the release process."
+- "Review the current diff for risky changes."

package/docs/releases/v0.1.1-beta.md

@@ -0,0 +1,18 @@
+# PatchPilot v0.1.1-beta
+
+## Highlights
+
+- Beta packaging pass for the early PatchPilot CLI.
+- Kept the project positioned as an experimental local-first coding-agent TUI.
+
+## Fixed
+
+- Tightened the first public install surface after the initial v0.1.0 release.
+
+## Improved
+
+- Clarified the beta release path before the later v0.2 and v0.3 hardening work.
+
+## Pull Requests
+
+- Early beta release maintenance.

package/docs/releases/v0.2.1.md

@@ -23,4 +23,4 @@
 
 ## Pull Requests
 
-- Pending PR from `feat/deep-dive-fixes`.
+- #7 Fix provider loops, onboarding safety, and public docs.

package/docs/releases/v0.3.1-beta.md

@@ -17,3 +17,7 @@
 - Header and sidebar now show `off`, `approval`, or `on` permissions based on the active mode instead of mixing mode and permission state.
 - Slash commands document `/mode bypass` and `/bypass` as explicit advanced controls.
 - Website-facing install flow can point users to the npm package instead of only GitHub assets.
+
+## Pull Requests
+
+- #17 Prepare v0.3.1 beta mode safety.

package/docs/releases/v0.4.0.md

@@ -24,4 +24,4 @@
 
 ## Pull Requests
 
-- v0.4 hardening branch: TUI approvals, provider capability filtering, script approval safety, and preview-positioned release docs.
+- #18 Prepare PatchPilot v0.4.0 hardening.

package/docs/releases/v1.0.0.md

@@ -0,0 +1,28 @@
+# PatchPilot v1.0.0
+
+## Highlights
+
+- Promotes PatchPilot to the first stable CLI release for visible, permissioned coding-agent runs across local, remote, and cloud model routes.
+- Finishes the Gemini-Wrapper provider path with explicit cookie onboarding, manual/auto model modes, pinned managed bridge installation, and clearer failure messages.
+- Adds real session resume context injection, model-driven `/init`, `/cleanup`, `/doctor fix`, and opt-in `/experimental` controls for subagents, file analysis, and memory.
+- Improves the TUI with readable transcript text, scrollable command and session panes, bottom-aligned transcript rendering, approval key isolation, and clearer token/cost/cache labels.
+
+## Fixed
+
+- Fixed a permission escalation bug where `--apply`, `/write on`, or `/shell on` could collapse into full build+bypass mode. Partial permissions now stay partial; bypass only applies to explicitly enabled permission groups.
+- Fixed shell confinement by blocking absolute shell path arguments outside the workspace and by detecting dangerous `git`/`npm` subcommands even after global options such as `git -C .` or `npm --prefix .`.
+- Fixed stale `/experimental` toggles by making agent runs observe the latest file-analysis and memory settings.
+- Fixed Gemini-Wrapper bridge timeout conversion so Python receives the configured seconds budget instead of a shortened fraction.
+- Fixed Gemini-Wrapper startup so normal chat runs no longer install unpinned Python packages at runtime.
+
+## Improved
+
+- External file analysis now requires per-path approval and still rejects sensitive paths after resolution.
+- `memory_remember` is treated as a durable write and requires write approval before persisting notes in SQLite.
+- `/init` now asks the selected model to inspect the repository and write project-specific `PATCHPILOT.md` guidance instead of emitting generic boilerplate.
+- Gemini-Wrapper documentation and README copy now label the route as advanced, unofficial, and explicit about session-cookie risk.
+- npm metadata now points to the public PatchPilot project page.
+
+## Pull Requests
+
+- #20 Harden Gemini-Wrapper, TUI sessions, experimental tools, and v1 release posture.

package/docs/releases/v1.0.1.md

@@ -0,0 +1,25 @@
+# PatchPilot v1.0.1
+
+## Highlights
+
+- Adds real Gemini-Wrapper file analysis for screenshots, images, PDFs, and DOCX files through the managed `gemini_webapi` Python bridge.
+- Adds `create_pdf` and `create_docx` tools so PatchPilot can generate simple text documents from agent output.
+- Adds a live provider-neutral todo panel in the TUI so longer agent runs show pending, active, and completed work.
+
+## Fixed
+
+- Fixed image inspection only returning metadata. With Gemini-Wrapper enabled, `inspect_document` now sends approved image files to Gemini Web as file inputs and returns visual analysis plus extracted visible text.
+- Fixed escaped multiline file writes. `write_file` and line-range `edit_file` now normalize likely double-escaped code/HTML payloads before writing, preventing `\n` and `\"` from landing as literal one-line source.
+- Fixed scanned/image-based PDF handling by falling back to Gemini-Wrapper file analysis when local `pdftotext` cannot extract text.
+- Fixed false-positive image inspection results. If provider analysis fails and no OCR mode was requested, PatchPilot now reports metadata-only analysis as degraded instead of claiming the image was understood.
+- Fixed approval-gated tools appearing stuck after approval by updating the visible run state immediately and executing tool calls sequentially.
+
+## Improved
+
+- Local document analysis is faster by default: PDFs use `pdftotext` and DOCX files are parsed directly before PatchPilot spends provider time. Images still use provider vision in `auto`, while `mode:"ocr"` keeps local OCR explicit.
+- Gemini-Wrapper docs now explain the upstream `files=[...]` pipeline and the supported file formats.
+- Providers can update visible run tasks through `update_todo`, with the active item animated in the transcript panel.
+
+## Pull Requests
+
+- #21 Improve file-edit reliability and Gemini-Wrapper document analysis.

package/docs/releases/v1.1.0.md

@@ -0,0 +1,30 @@
+# PatchPilot v1.1.0
+
+## Highlights
+
+- Adds Gemini-Wrapper document analysis for screenshots, images, PDFs, and DOCX files through the managed `gemini_webapi` bridge.
+- Adds approval-aware file generation tools for simple PDF and DOCX output.
+- Adds visible provider-neutral run todos so longer agent tasks expose pending, active, and completed work in the TUI.
+- Imports Gemini browser-cookie onboarding and model discovery improvements into the stable CLI line.
+
+## Fixed
+
+- Fixed escaped multiline file writes by normalizing likely double-escaped payloads before writing or line-range editing files.
+- Fixed image inspection that only returned metadata by routing approved image inputs through Gemini-Wrapper file analysis when available.
+- Fixed scanned PDF analysis by falling back to provider file analysis when local `pdftotext` cannot extract text.
+- Fixed approval-gated tools appearing stuck after approval by updating visible run state immediately and executing tool calls sequentially.
+- Fixed Gemini-Wrapper transport resets by retrying recoverable network failures.
+- Fixed local agent artifacts and game experiments leaking toward GitHub by ignoring them and removing generated `PATCHPILOT.md` from the tracked tree.
+
+## Improved
+
+- Updated runtime and development dependencies, including Ink, Zod, React, tsx, Vitest, Node types, and TypeScript 6.
+- Updated GitHub Actions to `actions/setup-node@v6` and `actions/github-script@v9`.
+- Added release workflow automation that triggers the website refresh after a GitHub release completes.
+- Kept generated local notes and browser-game experiments local-only via `.gitignore`.
+
+## Pull Requests
+
+- #21 Improve file-edit reliability and Gemini-Wrapper document analysis.
+- #19 Trigger website rebuild after releases.
+- #10, #11, #12, #13, #14, #15, #16 Dependency and workflow updates.

package/docs/releases/v1.2.0.md

@@ -0,0 +1,28 @@
+# PatchPilot v1.2.0
+
+## Highlights
+
+- Makes the fullscreen shell the stable default, with a compact header, command palette, animated run status, artifacts bar, saved-cost counter, cursor-aware composer, and a `/theme` switch back to the legacy layout.
+- Adds context storage and compaction primitives plus `/context` and `/compact` commands so long sessions can preserve useful workspace state without replaying noisy transcripts.
+- Adds composable ultra modes: `ultramaxx`, `ultrafast`, `ultracheap`, `ultrafocus:<path>`, and `ultraloop`, with conflict checks and visible keyword styling.
+- Adds first-run preferences for default mode, reasoning, thinking budget, and subagents, plus a use-at-your-own-risk acceptance step before onboarding continues.
+- Adds Windows hardening for clipboard image paste, path/attachment parsing, Codex CLI launcher resolution, and Gemini-Wrapper bootstrap commands.
+
+## Fixed
+
+- Hardened shell approvals so pipes remain supported, `&&` and `;` are available only through `/experimental shell-metacharacters`, and redirects, expansion, background jobs, OR chains, multiline commands, and glob expansion require explicit approval even in build+bypass.
+- Fixed `/write on` and `/shell on` so they no longer bypass the trusted-workspace confirmation panel.
+- Fixed fake success for unknown `/experimental` flags by validating supported flags before persisting settings.
+- Fixed external-file approval bypass behavior, shell path guards, attachment context handling, and secret/path checks around workspace tools.
+- Fixed Gemini-Wrapper re-auth flows so expired cookies can trigger an approval-style refresh panel and failed prompts can retry after refresh.
+- Fixed provider retry behavior, todo-only/fake final handling, TUI prompt handling, composer cursor behavior, run-status randomization, and overlay layout clipping.
+
+## Improved
+
+- Refreshes README guidance for the default shell, ultra modes, context commands, shell-metacharacter controls, onboarding disclaimer, remote host setup, and the current safety model.
+- Refreshes the npm lockfile with `npm update` and keeps the package verification surface aligned with the current dependency graph.
+- Adds broader Vitest coverage for context storage, compaction, shell guards, command help, layout math, clipboard, attachments, provider retry helpers, ultra modes, and Windows-oriented path behavior.
+
+## Pull Requests
+
+- #23 PatchPilot deep-dive hardening and context system.