v0.9.3

> **Codewhale** is the public product from Shannon Labs. The `codewhale`
> command, npm package, and release-asset names remain lowercase technical
> identifiers. The legacy npm package `deepseek-tui` is deprecated and
> receives no further releases. Users coming from v0.8.x legacy `deepseek` /
> `deepseek-tui` names should migrate with `docs/REBRAND.md`.

## Install

### Recommended — npm (one command, all three entrypoints)

```bash
npm install -g codewhale
```

The wrapper downloads the matched `codewhale`, `codew`, and `codewhale-tui`
binaries from this Release and places them in the same directory.

### Docker / GHCR

```bash
docker run --rm -it \
  -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \
  -v codewhale-home:/home/codewhale/.codewhale \
  ghcr.io/hmbown/codewhale:v0.9.3
```

The image ships the `codewhale` dispatcher, `codew` shim, and `codewhale-tui` runtime. The `latest` tag is also updated on release.

### Cargo (Linux / macOS)

```bash
cargo install codewhale-cli codewhale-tui --locked
```

Both crates are required — `codewhale-cli` produces the `codewhale` dispatcher and `codew` shim, while `codewhale-tui` produces the interactive runtime that the dispatcher delegates to. Installing only one crate will fail at runtime with a `MISSING_COMPANION_BINARY` error.

### Manual download — platform archives (recommended)

Each archive below contains the `codewhale` dispatcher, `codew` shim, and `codewhale-tui` runtime, plus an install script:

| Platform | Archive | Install script |
|---|---|---|
| Linux x64 | `codewhale-linux-x64.tar.gz` | `install.sh` |
| Linux ARM64 | `codewhale-linux-arm64.tar.gz` | `install.sh` |
| Android ARM64 (Termux) | `codewhale-android-arm64.tar.gz` | `install.sh` |
| macOS x64 | `codewhale-macos-x64.tar.gz` | `install.sh` |
| macOS ARM | `codewhale-macos-arm64.tar.gz` | `install.sh` |
| Windows x64 (installer) | `CodeWhaleSetup.exe` | NSIS setup |
| Windows x64 | `codewhale-windows-x64.zip` | `install.bat` |
| Windows x64 (portable) | `codewhale-windows-x64-portable.zip` | — |
| Windows ARM64 | `codewhale-windows-arm64.zip` | `install.bat` |
| Windows ARM64 (portable) | `codewhale-windows-arm64-portable.zip` | — |

**Unix (Linux / macOS):**
```bash
tar xzf codewhale-<platform>.tar.gz
cd codewhale-<platform>
./install.sh
```

**Windows:**
- For the installer path, run `CodeWhaleSetup.exe`; it installs `codewhale.exe`, `codew.exe`, and `codewhale-tui.exe` under `%LOCALAPPDATA%\Programs\CodeWhale\bin` and adds that directory to the current-user PATH.
- Extract the archive for your machine: `codewhale-windows-x64.zip` or
  `codewhale-windows-arm64.zip`
- Run `install.bat` (copies to `%USERPROFILE%\bin`)
- Add `%USERPROFILE%\bin` to your PATH

The **portable** Windows archive skips the install script — extract and run from any directory. The NSIS installer is currently unsigned and may trigger Windows SmartScreen until a signing certificate is wired into the release pipeline.

Each platform also has **bare, unarchived** binaries attached below (`codewhale-<platform>`, `codew-<platform>`, and `codewhale-tui-<platform>`) — the npm wrapper and the in-app `codewhale update` download the matched runtime binaries, whereas the `.tar.gz` / `.zip` archives above are the recommended manual download and additionally bundle an install script. The legacy npm package `deepseek-tui` is deprecated and is not republished. For migration from v0.8.x legacy binary names, see `docs/REBRAND.md`.

### Verify (recommended)

Download the checksum manifests from this Release and verify:

```bash
# Linux — archive bundles
sha256sum -c codewhale-bundles-sha256.txt --ignore-missing

# Linux — individual binaries
sha256sum -c codewhale-artifacts-sha256.txt --ignore-missing

# macOS
shasum -a 256 -c codewhale-bundles-sha256.txt --ignore-missing
shasum -a 256 -c codewhale-artifacts-sha256.txt --ignore-missing
```

## What's in v0.9.3

This is the Codewhale v0.9.3 source candidate. It is not a published release
until the matching tag, packages, checksums, and release assets exist.

DeepSeek V4 Flash is now a first-class Codewhale route, and the agent-facing
tool surface has been reduced to the canonical action tools that current
models actually need. This release also hardens credential, authorization,
durability, compaction, and macOS File Provider boundaries while deleting
stale runtime and dependency surface.

### Added

- Native `deepseek-v4-flash` support over DeepSeek's Responses API, including
  stateless reasoning-item replay, semantic SSE terminal events, structured
  function calls and outputs, `apply_patch`, and model-aware wire-format
  selection. Exact current Flash IDs use Responses; future direct
  `deepseek-vN-*` model IDs inherit that route conservatively, while custom
  DeepSeek-compatible endpoints retain Chat Completions unless configured
  otherwise.
- A pipe-only `codewhale auth print-api-key` handoff for explicitly selected
  providers. It shares Codewhale's home-scoped credential authority, refuses
  terminal output, and prevents sentinel placeholders from becoming live
  credentials.
- Per-turn `max_tool_calls` enforcement at the engine admission gate, plus a
  named-file write scope with a separate read seam. The runtime now rejects
  over-budget calls before execution and keeps the operator's write boundary
  explicit (#4415).
- Runtime-contract, source-structure, and persistence-backlog ratchets that
  name drift instead of allowing large ownership surfaces to grow silently
  (#3921, #4785).

### Changed

- Model-visible built-ins now use the canonical `Bash`, `File`, and `Run`
  action schemas. `apply_patch` remains available as the one direct custom
  edit tool supported by DeepSeek Responses. The bundled stop-ship workflow,
  Fleet fixtures, shell shortcut, and engine tests use the same canonical
  vocabulary.
- Canonical `File { action: "write" }` requests now pass through the same
  semantic repo-law checks as the former write path. Approval, Full Access,
  and workflow execution cannot bypass the repository safety floor by choosing
  the canonical schema.
- Codewhale home resolution is shared across the CLI, TUI, state, and secret
  stores. `doctor` is offline by default, distinguishes credential source from
  availability, and reports one consistent path snapshot.
- Durable runtime event writes are serialized across simultaneous processes,
  blocking history waits move off async workers, and provider quota exhaustion
  remains typed and retryable through compaction (#4522).
- Skill discovery caches the merged catalog behind watched-mtime validation;
  large skill, engine, subagent, UI, and ambient-ocean test blocks now live in
  owned test seams.
- Reasoning summaries stay in the user's language, complete jellyfish
  silhouettes relocate around transcript text, and cached ocean frames include
  their palette identity (#4807).
- The authorization-order contract now documents and tests how modes, hooks,
  permission rules, safety floors, repo law, approvals, and sandboxing compose
  (PR #4980).

### Fixed

- macOS sandbox extensions cover CloudStorage/File Provider workspaces without
  broadening unrelated paths; thanks @Watcher24 for the #4085 report and
  reproduction.
- Foreground shell state detaches before steering, so an interrupted command
  cannot keep owning the composer (PR #4979).
- MCP application-level failures and malformed error envelopes fail closed
  instead of looking like successful tool output.
- Optional PDF failures are truthful and PDF classification no longer misses
  supported inputs.
- Bracketed-paste contents are redacted from traces, and credential diagnostics
  never treat placeholder sentinels as usable keys.

### Removed

- The legacy callable aliases `exec_shell`, `run_shell_command`, `read_file`,
  `write_file`, `list_dir`, `grep_files`, `file_search`, and the duplicate
  Work/RLM registrations. Historical transcript and policy semantics remain
  readable, but new model turns receive only the canonical action surface.
- The bundled PDF parser dependency chain, replacing it with the smaller
  optional extraction boundary tracked by #4382.

## Contributors

- [Turisla](https://github.com/greyfreedom) (`@greyfreedom`) documented and
  locked the authorization-order contract in PR #4980.
- [Nightt](https://github.com/nightt5879) (`@nightt5879`) fixed foreground
  shell detachment before steering in PR #4979.
- [Watcher24](https://github.com/Watcher24) (`@Watcher24`) provided the macOS
  File Provider report and reproduction for #4085.
- [Fred Leitz](https://github.com/fleitz) (`@fleitz`) retains required
  source-candidate credit for the canonical `Bash` workspace fix from PR #4673
  and issue #4674.

See [CHANGELOG.md](https://github.com/Hmbown/CodeWhale/blob/main/CHANGELOG.md) for full notes and [docs/CHANGELOG_ARCHIVE.md](https://github.com/Hmbown/CodeWhale/blob/main/docs/CHANGELOG_ARCHIVE.md) for older releases.