Versioning & History

Every artifact in CRHQ is automatically versioned. Each time the content changes — whether the agent updates it, you save an edit in the panel, or anything in between — a new immutable version is recorded. Older versions are never overwritten.

How versioning works

When an artifact is created, it's v1. Every subsequent change adds a new version row:

• An agent updates the artifact via the API → version bumps
• You edit the markdown / file content in the panel and hit Save → version bumps
• The agent renames the artifact (changes title, language, or file path) → version bumps even if the content didn't move much

Detection uses a composite hash of title + language + filePath + content. So renames count, not just content changes.

The current version number appears as a small v<n> badge in the artifact header (only shown when versionNum > 1 — fresh artifacts don't carry the noise).

Opening the History modal

Once an artifact has been edited at least once, the History button (clock-rewind icon) appears in the artifact toolbar. Tap it to open the Version History modal.

The modal has two zones:

• Top — version list (scrollable, max ~38% on mobile) — Newest version first. Each row shows version number, relative time, who made the change (agent / system / your email), and any change summary. Restored versions show an italic Restored from v<n> label.
• Bottom — preview pane (fixed, with internal scroll) — Shows the selected version's title, metadata, and content. For HTML and markdown versions there's a Preview / Code toggle so you can see either the rendered output or the raw source.

Tap any row to preview that version. The currently-active version has a small current pill on the right.

Restoring a version

In the preview pane, tap Restore as new version. A confirm sheet slides up with the reassurance text:

Tap Yes, restore as new version and:

• A new version row is added to the top of the list (e.g. v5 if you restored v2 over v4)
• The new version is marked Restored from v<n> so the lineage is visible
• The artifact's content swaps to that version
• The History modal closes
• A toast at the top of the artifact panel confirms Restored from v2 (now v5)

Restore is always non-destructive. v2 still exists in the list. v4 still exists in the list. Restoring v2 creates v5.

Mobile view of the History modal

On mobile (≤600px) the modal becomes fullscreen with the same 2-zone layout. Tap targets are 44px minimum. The slide-up confirm sheet is anchored to the bottom of the preview pane (max 75% height) so the reassurance text and CTAs are always visible.

What happens to file-content artifacts on restore

For artifacts backed by a file on disk (file_content type), restore updates the artifact snapshot only — the file on disk is not touched. The next manual file Refresh may overwrite the restored content with what's currently on disk. The History modal shows an inline tip when the selected artifact is file_content so you're not surprised.

What happens when versions are bumped over WebSocket

When the agent updates an artifact:

• A version.create event is logged on the server
• A WebSocket artifact:update broadcast goes out with the new versionNum
• Your panel updates the version badge live, and the History button appears immediately if it wasn't visible before (no page refresh needed)
• Any open Version History modal invalidates its cache so the next open shows the new row

Versions vs the panel close button

Closing the artifact panel tab (the × on the tab) does not affect versions — the artifact and all its history stay in the database. To permanently delete an artifact and all its versions (and revoke any active share), use Session Details → Artifacts tab → ⋯ → Remove forever, with confirm.

Caps and limits

• No cap on the number of versions per artifact in v1 — every change is recorded
• The version cache TTL is 30s per artifact in the client (refetched on next History modal open)
• Backfill: artifacts that existed before versioning was rolled out got an initial v1 row with the change summary Initial version