# Changelog and migration

> Version history, breaking changes, and upgrade steps between versions.

- Repository: egoist/lorca
- GitHub: https://github.com/egoist/lorca
- Human docs: https://grok-wiki.com/public/docs/egoist-lorca-2cf67495e5e6
- Complete Markdown: https://grok-wiki.com/public/docs/egoist-lorca-2cf67495e5e6/llms-full.txt

## Source Files

- `CHANGELOG.md`

---

---
title: "Changelog and migration"
description: "Version history, breaking changes, and upgrade steps between versions."
---

Lorca ships **three independent version lines**: Mac app (`package.json` → Sparkle), standalone CLI (`Cargo.toml` `[workspace.package]` → GitHub `cli-vX.Y.Z`), and mobile (`mobile/app.config.ts` → TestFlight / store builds). `CHANGELOG.md` feeds **Mac Sparkle release notes only**.

| Surface | Source of truth | Current tree | How users get updates |
| --- | --- | --- | --- |
| Mac app | root `package.json` `"version"` | `1.0.7` | Sparkle feed `https://mac-releases.lorca.app/appcast.xml` |
| CLI | `Cargo.toml` `[workspace.package].version` | `0.1.7` | Re-run install script, or pin `LORCA_VERSION` |
| Mobile | `mobile/app.config.ts` `version` | `1.0.0` | iOS: `bun run release-ios` → TestFlight |

<Warning>
`CHANGELOG.md` currently has `## [Unreleased]` and `## [0.1.0]` only. The Mac tree is at `1.0.7` with **no matching changelog section**, so `bun run release-mac` would ship that version without Sparkle notes until you add `## [1.0.7]`.
</Warning>

## Version map

```text
package.json "version"  ──► Info.plist CFBundle*  ──► Sparkle compares / updates
Cargo.toml version      ──► lorca --version       ──► GitHub release cli-vX.Y.Z
mobile/app.config.ts    ──► CFBundleShortVersion  ──► TestFlight (build number separate)
```

- Mac release replaces the **whole** `.app`, including the CLI under `Contents/Resources/bin`.
- Standalone CLI installs under `~/.local/bin` by default; a Mac-app update does **not** refresh that copy.
- CLI and Mac versions are **not** required to match.

## Changelog format (Mac)

`CHANGELOG.md` is Keep-a-Changelog-style. `scripts/changelog.ts` `extractReleaseNotes` reads a level-2 heading whose first token is the version (`## [1.0.7]`, `## 1.0.7`, `## v1.0.7`).

On release, `bun run release-mac` writes `Lorca-<version>.md` beside the Sparkle zip when a section exists; otherwise it logs a warning and continues.

### Add notes for the next Mac cut (~2 minutes)

<Steps>
  <Step title="Add the section">
    Put `## [X.Y.Z]` at the **top** of `CHANGELOG.md` (above older sections). Move finished bullets out of `## [Unreleased]`.
  </Step>
  <Step title="Release">
    Run `bun run release-mac X.Y.Z`. That bumps `package.json`, builds/signs/notarizes, regenerates `appcast.xml`, and uploads to R2.
  </Step>
  <Step title="Commit">
    Commit `package.json` and `CHANGELOG.md` so the tree matches what shipped.
  </Step>
</Steps>

After this, Sparkle’s update window shows that section’s body.

## Release notes

:::updates
@update Unreleased - Mac notes queued for the next Sparkle cut

- Command cards appear only while input or a long-running command needs you (Allow once / Always allow / Deny, or live output).
- Running-tasks toolbar control lists in-flight bot commands with Stop per command.
- Interactive commands (`sudo`, `ssh`, `[Y/n]`) no longer hang the turn; answers are never stored in chat. Quiet commands wait after 20s silence; sessions end after 30 minutes without output, when Lorca quits, or when the chat is deleted.
- Terminal color codes are stripped before the bot sees output (full file keeps them).
- ChatGPT, Grok, and OpenCode GPT/Grok chats stick to the prompt-cache server; Spent no longer double-counts cached input on those providers; Claude cache reuse improved across groups and heavy tool turns; one chat speaking no longer breaks another chat’s cache.

@update 0.1.0 - First Mac release

- Initial public Mac app release (`## [0.1.0]` in `CHANGELOG.md`).

@update CLI 0.1.7 - Latest tagged standalone CLI

- Workspace crate version `0.1.7`; GitHub tag `cli-v0.1.7`. Confirm with `lorca --version` → `lorca 0.1.7`.
:::

## Upgrade: Mac app (~1 minute)

Automatic checks are on (`SUEnableAutomaticChecks`). Sparkle verifies EdDSA signatures with `SUPublicEDKey` from Info.plist before install.

<Steps>
  <Step title="Check">
    Open Lorca → **Check for Updates…**, or Settings ▸ General ▸ Updates.
  </Step>
  <Step title="Install">
    Accept the update. Sparkle swaps the bundle (app + bundled CLI). Lorca stops the old CLI on quit and starts the new one on relaunch.
  </Step>
  <Step title="Verify">
    Confirm the version in Settings / About matches the feed (`Updater.currentVersion` reads `CFBundleShortVersionString`).
  </Step>
</Steps>

<Note>
Debug / `Lorca Dev` builds disable Sparkle (`Updater.isEnabled` is false under `DEBUG`). Old R2 archives stay published so far-behind installs can still full-download.
</Note>

## Upgrade: standalone CLI (~1 minute)

Re-run the installer. It downloads from `releases/latest` (or `LORCA_VERSION`), checks `.sha256`, and replaces the binary via rename so a running `lorca serve` keeps its open file.

<Tabs>
  <Tab title="macOS / Linux">
```sh
curl -fsSL https://lorca.app/install-cli.sh | sh
lorca --version
```
  </Tab>
  <Tab title="Windows (PowerShell)">
```powershell
irm https://lorca.app/install-cli.ps1 | iex
lorca --version
```
  </Tab>
  <Tab title="Pin a version">
```sh
LORCA_VERSION=0.1.7 curl -fsSL https://lorca.app/install-cli.sh | sh
```
  </Tab>
</Tabs>

| Variable | Default | Effect |
| --- | --- | --- |
| `LORCA_VERSION` | latest | Install that crate version (no `v` / `cli-v` prefix) |
| `LORCA_INSTALL_DIR` | `~/.local/bin` | Install location |
| `LORCA_NO_MODIFY_PATH` | unset | Skip PATH profile edits |
| `LORCA_DOWNLOAD_URL` | GitHub releases URL | Override download base |

<Check>
Success: installer prints `Installed lorca <version> at …/lorca`, and `lorca --version` matches.
</Check>

## Upgrade: iOS (~30 minutes after upload)

Marketing version is `version` in `mobile/app.config.ts` (`1.0.0`). Each upload needs a higher build number (`BUILD_NUMBER` or timestamp via `bun run release-ios`). Users get builds through TestFlight after App Store Connect processing.

## Storage and schema migration

### Device home (`~/.lorca` or `LORCA_HOME`)

`App::load` states the local storage layout has **no migration path**. On every launch it deletes superseded files if present:

- `state.json`
- `transcript.sqlite3` (+ `-wal` / `-shm`)

Current state lives in `lorca.sqlite3` (`PRAGMA user_version = 1`). Identity, credentials, chats, and plugins stay under the home directory across Mac/CLI binary upgrades.

### Hard wipe (destructive, ~1 minute)

```sh
bun run reset          # prompts; deletes ~/.lorca (or ~/.lorca-dev with --dev)
bun run reset -y       # skip confirm
bun run reset --relay  # also wipe local relay DB under temp/
```

Without the backup phrase, a reset identity is unrecoverable.

### Relay databases

SQLite and Postgres backends keep a `schema_version` table and an append-only `MIGRATIONS` list. Both lists are **empty** in the current tree (baseline schema only). Policy: steps only **add** tables, nullable columns, or indexes; never edit a shipped step. Postgres applies steps once (with deadlock retry) so old and new processes can run side by side during deploy.

## Cutting a release (maintainers)

### Mac app

1. Add `## [X.Y.Z]` to `CHANGELOG.md`.
2. `bun run release-mac X.Y.Z` (or `bun run release-mac --local` to notarize without upload).
3. Commit `package.json` + `CHANGELOG.md`.

Env knobs: `FORCE=1` replace published zip; `NO_HISTORY=1` skip delta archives; `R2_BUCKET` / `DOWNLOAD_URL_PREFIX` for the feed host.

### CLI

1. Set `[workspace.package].version` in `Cargo.toml`, run `cargo check -p lorca`, commit with `Cargo.lock`.
2. `gh workflow run release-cli.yml` or `git tag cli-vX.Y.Z && git push origin cli-vX.Y.Z`.
3. Publish the draft with **Set as the latest release** checked (`install-cli` uses `releases/latest`).

Tag must match crate version; a mismatched or already-published tag fails the workflow.

## Agent API: coming from pi

Porting TypeScript `pi-agent-core` code uses the name map in `docs/agent/coming-from-pi.md` (`Agent::new`, `prompt` / `continue_run`, `QueueMode`, `ToolExecutionMode`, channel events). Persistence and branching stay host-owned; Lorca does not ship pi’s session tree.

## Related pages

<CardGroup>
  <Card title="Installation" href="/installation">
    First install for Mac, CLI, and mobile, plus recovery notes.
  </Card>
  <Card title="Deployment and operations" href="/deployment">
    Release pipelines, R2/Sparkle, CLI workflow, and relay ops.
  </Card>
  <Card title="CLI reference" href="/cli-reference">
    Commands, flags, `lorca --version`, and serve defaults.
  </Card>
  <Card title="Data model reference" href="/data-model-reference">
    Local SQLite and relay `schema_version` shapes.
  </Card>
</CardGroup>

Next: open `CHANGELOG.md` and confirm whether your Mac version needs a new `## [X.Y.Z]` section before the next `bun run release-mac`.