Road to 1.0: Release Candidate Readiness

[AndrewMcLachlan]

Goal

Define the minimum hardening and release work required before CodeHerd can make a credible 1.0 stability promise.

CodeHerd is functionally close to 1.0. This issue is about release confidence rather than adding more product features.

Constraints

• Paid Windows/macOS code-signing and notarisation are not currently affordable and are not a 1.0 blocker.
• Unsigned builds must be clearly identified and accompanied by safe, platform-specific installation guidance.
• A built-in auto-updater is not required; the existing update notification and GitHub Releases can remain the update path.

Build and quality gates

• Add an npm run typecheck script using tsc --noEmit.
• Fix the current type-check failure around optional app.dock access.
• Make type-checking a required CI step.
• Add focused automated tests for the highest-risk behaviour:
  • state persistence, migration, and restoration
  • Claude and Codex session discovery/parsing
  • status, title, rename, and colour tracking
  • shell and agent detection/argument construction
  • graceful tab and application shutdown
• Run those tests as a required CI step.

State durability

• Preserve a last-known-good backup of state.json.
• Recover cleanly from corrupt or interrupted writes rather than silently resetting everything.
• Test state schema defaults and migrations from older releases.
• Confirm upgrades preserve tabs, recently closed sessions, preferences, colours, and the active tab.

CLI compatibility and diagnostics

• Document the supported Claude Code and Codex CLI versions or compatibility policy.
• Keep fixture-based tests for the CLI/session formats CodeHerd parses.
• Show useful errors when an agent is missing, outdated, or returns an unexpected session format.
• Provide a simple way to locate or export diagnostic logs, with secrets and prompt content excluded where practical.

Platform confidence

• Define the supported Windows, macOS, and Linux versions and architectures.
• Add a repeatable release smoke-test checklist covering:
  • agent detection
  • new and resumed sessions
  • application restart and tab restoration
  • copy, paste, and multi-line paste
  • rename and colour behaviour
  • attention/working indicators and status metadata
  • graceful shutdown
• Run the checklist on every supported platform, with each available agent.
• Either verify a platform for 1.0 or clearly mark it experimental.

Better deployment without paid signing

• Use stable, versioned artifact names containing platform and architecture.
• Publish a SHA256SUMS file with every GitHub Release.
• Investigate publishing GitHub build-provenance attestations alongside release artifacts.
• Windows:
  • provide a conventional installer as well as the portable ZIP
  • document the unsigned-app/SmartScreen experience and upgrade/uninstall steps
• macOS:
  • continue providing a DMG or ZIP
  • document the expected Gatekeeper experience for an unsigned build and the supported installation path
• Linux:
  • continue providing the Debian package
  • consider a portable archive or AppImage if it materially improves coverage
• Add installation, upgrade, downgrade, and uninstall instructions to the README or release documentation.
• Verify the release workflow produces all expected artifacts before publishing the release.
• Confirm installing a new version over an old one preserves user state.

Release-candidate exit criteria

• Freeze the 1.0 scope; non-critical enhancements move to 1.x.
• Publish at least one v1.0.0-rc.N release.
• Complete a defined dogfooding/soak period without known data-loss, restoration, startup, or shutdown defects.
• Complete the platform smoke-test checklist against the final candidate.
• Ensure release notes clearly describe supported agents, platforms, installation caveats, and known limitations.
• Ship 1.0 only when CI, deployment artifacts, state recovery, and the release checklist are all green.

Explicitly not required for 1.0

• Paid code-signing certificates or Apple notarisation
• A built-in auto-updater
• Find in Session or other general feature enhancements
• Eliminating every unsigned-app warning that is controlled by the operating system

[AndrewMcLachlan]

Checked off everything completed by the merged PRs #95–#104:

• Quality gates: typecheck + vitest scripts and required CI steps (Fix tsc error: app.dock is possibly undefined #95, Add typecheck and test quality gates to CI #96); test suites for state persistence (State durability: backup, corruption recovery, and tests #97), session discovery/parsing (Session discovery/parsing tests for Claude and Codex #98), status/title/rename/colour (Add typecheck and test quality gates to CI #96, Session discovery/parsing tests for Claude and Codex #98), shell/agent detection & args (Shell/agent detection and argument construction tests #99), graceful shutdown (Graceful shutdown tests for PtyManager #101) — 149 tests total
• State durability: state.json.bak backup, corruption recovery with .corrupt preservation, migration tests (State durability: backup, corruption recovery, and tests #97)
• Diagnostics: opt-in PTY logging (CODEHERD_PTY_DEBUG), stale-log cleanup, Help → Open Diagnostics Folder (Opt-in PTY debug logging, stale log cleanup, diagnostics menu item #102)
• Deployment: versioned DMG name, pre-publish artifact verification, SHA256SUMS, build-provenance attestations (Release hardening: artifact verification, SHA256SUMS, provenance attestations #100); Windows Squirrel installer with Start-Menu-only shortcuts (Windows installer (Squirrel) with Start-Menu-only shortcuts #104)
• Docs: platform matrix, CLI compatibility policy, INSTALL.md (SmartScreen/Gatekeeper, upgrade/downgrade/uninstall), RELEASE_CHECKLIST.md (Docs: platform support, CLI compatibility policy, install guide, release checklist #103)

Left unchecked, deliberately:

• Items that are verified at RC time (upgrade-preserves-state ×2, running the checklist per platform, verify-or-mark-experimental) — the mechanisms exist, the executions haven't happened
• "Useful errors when an agent is missing/outdated" — the missing-agent banner exists; outdated-CLI detection doesn't yet
• AppImage — the portable Linux zip already ships; open question whether AppImage adds coverage
• All release-candidate exit criteria (process, not code)

Note: the release job's verify/checksum/attest path is untested against a real tag — the first v* (or v*-rc) tag exercises it end-to-end.

🤖 Generated with Claude Code