The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
Verify harness updates end to end and enforce complete updater coverage
Dee49cff387d828
diff --git a/.gitignore b/.gitignoreindex f6feeca39..b5c50db82 100644--- a/.gitignore+++ b/.gitignore@@ -2,6 +2,7 @@ node_modules/.vite/dist/.tsbuildinfo+cli/coverage/.DS_Store# IDE state. workspace.xml records local paths, run configs and sometimes datasource# credentials — none of it belongs in a public repo.diff --git a/cli/package.json b/cli/package.jsonindex 254a08be5..6acd338e7 100644--- a/cli/package.json+++ b/cli/package.json@@ -12,6 +12,7 @@"typecheck": "tsc --noEmit","start": "node dist/cli.js","test": "vitest run",+ "test:dsh-updates": "vitest run --config vitest.dsh-updates.config.ts","test:cursor-e2e": "RUN_CURSOR_E2E=1 vitest run src/engines/cursor/localE2e.spec.ts","test:tmux-real": "RUN_REAL_TMUX_DISCOVERY=1 vitest run src/lib/tmuxAgentDiscovery.real.spec.ts --reporter=verbose","test:herdr-real": "RUN_REAL_HERDR=1 vitest run src/lib/herdrBackend.real.spec.ts --reporter=verbose",diff --git a/cli/scripts/smoke-dsh-updates.ts b/cli/scripts/smoke-dsh-updates.tsindex b993b47a3..65eb77145 100644--- a/cli/scripts/smoke-dsh-updates.ts+++ b/cli/scripts/smoke-dsh-updates.ts@@ -71,7 +71,7 @@ if (!installed.ok) throw new Error(installed.detail)mkdirSync(workspace)await materializeWorkspace(installedDsh(id)!, workspace)writeFileSync(join(workspace, 'project.txt'), 'my finished project')-writeFileSync(join(workspace, 'AGENTS.md'), 'my custom instructions')+writeFileSync(join(workspace, 'AGENTS.md'), readFileSync(join(workspace, 'AGENTS.md'), 'utf8') + '\nmy custom instructions\n')writeFileSync(join(workspace, '.harness', 'verdict.json'), '{"ready":true,"summary":"finished"}')publish(true)let viewerUrl: string | null = nulldiff --git a/cli/src/cli.ts b/cli/src/cli.tsindex af196cdc9..2a627cba9 100644--- a/cli/src/cli.ts+++ b/cli/src/cli.ts@@ -81,7 +81,7 @@ import { prepareCodexResume } from './engines/codex/portableHistory.js'import { buildHarnessSessionLabel } from './lib/harnessSessionLabel.js'import { installedDsh } from './dsh/installed.js'import { dshVerdictPath, dshViewerName } from './dsh/manifest.js'-import { catalogEntry, refreshDshRegistry } from './dsh/catalog.js'+import { catalogEntry } from './dsh/catalog.js'import { removeDsh } from './dsh/install.js'import { preTrustClaudeProject, preTrustCodexProject } from './lib/claudeTrust.js'import { materializeWorkspace } from './dsh/materialize.js'diff --git a/cli/src/dsh/install.ts b/cli/src/dsh/install.tsindex 11de62af9..7f58e4408 100644--- a/cli/src/dsh/install.ts+++ b/cli/src/dsh/install.ts@@ -306,7 +306,7 @@ export async function installDsh(opts: DshInstallOptions): Promise<DshInstallResconst record: InstalledDshRecord = {id: manifest.id,dir,- source: opts.link ? resolve(opts.source) : opts.source,+ source: opts.link || existsSync(opts.source) ? resolve(opts.source) : opts.source,ref: opts.ref ?? null,...(opts.link || !opts.path ? {} : { path: opts.path }),commit,@@ -376,6 +376,12 @@ export async function finishInstall(resolved: InstalledDsh, opts: DshInstallOpti}}+ if (!recordDoctorFailure && uses && installedDsh(uses)?.manifest.kind !== 'viewer') {+ const detail = `viewer ${uses} is not available; the previous package will be kept`+ progress({ id: manifest.id, phase: 'failed', detail })+ return { ok: false, error: 'VIEWER_UNAVAILABLE', detail }+ }+progress({ id: manifest.id, phase: 'doctor' })const doctor = await runDshDoctor(resolved, opts.onLine)// Recorded even when the doctor complains: the user can fix the machine and run the doctor againdiff --git a/cli/src/dsh/service.spec.ts b/cli/src/dsh/service.spec.tsnew file mode 100644index 000000000..7195e24a8--- /dev/null+++ b/cli/src/dsh/service.spec.ts@@ -0,0 +1,100 @@+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'+import { installDsh, type DshInstallOptions, type DshInstallResult } from './install.js'+import { updateDsh } from './update.js'+import { mutateDsh } from './service.js'+import { refreshDshRegistry } from './catalog.js'+import type { DshRegistryEntry } from './registry.js'++const catalog = vi.hoisted(() => ({ entries: [] as DshRegistryEntry[] }))+vi.mock('./catalog.js', () => ({+ refreshDshRegistry: vi.fn(async () => catalog.entries),+ catalogEntry: (id: string) => catalog.entries.find(entry => entry.id === id),+}))+vi.mock('./install.js', async original => ({ ...await original<typeof import('./install.js')>(), installDsh: vi.fn() }))+vi.mock('./update.js', () => ({ updateDsh: vi.fn() }))++const success: DshInstallResult = { ok: true, installed: {+ id: 'acme/thing', dir: '/fixture', realDir: '/fixture', source: 'https://example.com/thing',+ ref: null, commit: null, linked: false, installedAt: 0,+ manifest: { spec: 1, id: 'acme/thing', name: 'Thing', engine: 'claude' },+}, doctor: { ok: true, lines: [] }, setupLines: [] }++describe('daemon package mutations', () => {+ beforeEach(() => {+ catalog.entries = [{ id: 'acme/thing', name: 'Thing', engine: 'claude', repo: 'https://example.com/thing', ref: 'a'.repeat(40), path: 'packages/thing' }]+ vi.mocked(installDsh).mockReset().mockResolvedValue(success)+ vi.mocked(updateDsh).mockReset().mockResolvedValue(success)+ vi.spyOn(console, 'log').mockImplementation(() => {})+ vi.spyOn(console, 'warn').mockImplementation(() => {})+ })+ afterEach(() => { vi.restoreAllMocks(); vi.useRealTimers() })++ it('pins catalog installs, allows a URL install, and updates an unlisted installed source', async () => {+ expect(await mutateDsh({ id: 'acme/thing' }, () => {})).toEqual({ ok: true, id: 'acme/thing' })+ const options = vi.mocked(installDsh).mock.calls[0]![0]+ expect(options).toMatchObject({ source: catalog.entries[0]!.repo, ref: 'a'.repeat(40), path: 'packages/thing', expectedId: 'acme/thing' })+ expect(options.registry!('acme/thing')).toEqual(catalog.entries[0])+ expect(await mutateDsh({ url: 'https://example.com/private', ref: 'v2' }, () => {})).toMatchObject({ ok: true })+ expect(vi.mocked(installDsh).mock.calls.at(-1)![0]).toMatchObject({ source: 'https://example.com/private', ref: 'v2', path: undefined })+ vi.mocked(updateDsh).mockImplementation(async options => {+ options.onProgress!({ id: 'acme/unlisted', phase: 'doctor' })+ options.onLine!('ok updated')+ return success+ })+ expect(await mutateDsh({ id: 'acme/unlisted', update: true }, () => {})).toMatchObject({ ok: true })+ expect(updateDsh).toHaveBeenCalledWith(expect.objectContaining({ id: 'acme/unlisted' }))+ expect(refreshDshRegistry).toHaveBeenLastCalledWith(true)+ })++ it('rejects an unknown catalog id and an empty request before running code', async () => {+ expect(await mutateDsh({ id: 'acme/missing' }, () => {})).toMatchObject({ ok: false, error: 'INVALID_DSH' })+ expect(await mutateDsh({}, () => {})).toMatchObject({ ok: false, error: 'INVALID_DSH' })+ expect(installDsh).not.toHaveBeenCalled()+ })++ it('throttles output, immediately sends doctor lines, and discards lines after terminal phases', async () => {+ vi.useFakeTimers()+ const progress = vi.fn()+ vi.mocked(installDsh).mockImplementation(async (options: DshInstallOptions) => {+ const line = options.onLine!+ const phase = options.onProgress!+ line('before phase'); vi.advanceTimersByTime(300)+ phase({ id: null, phase: 'clone' })+ line(' \r')+ line('Receiving 10%\rReceiving 20%')+ vi.advanceTimersByTime(300)+ line('queued output')+ line('newer queued output')+ phase({ id: 'acme/thing', phase: 'doctor' })+ line('checking')+ line('ok ready')+ line('miss fonts')+ phase({ id: 'acme/thing', phase: 'done' })+ line('late output'); vi.advanceTimersByTime(300)+ phase({ id: 'acme/thing', phase: 'failed' })+ line('late failure output'); vi.advanceTimersByTime(300)+ line('pending at return')+ return success+ })+ await mutateDsh({ id: 'acme/thing' }, progress)+ expect(progress.mock.calls.flat().filter(p => p.line).map(p => p.line)).toEqual(['Receiving 20%', 'ok ready', 'miss fonts'])+ expect(vi.getTimerCount()).toBe(0)+ })++ it('returns errors and clears pending narration when an operation throws', async () => {+ const failure = { ok: false, error: 'DOCTOR_FAILED', detail: 'miss runtime' } as const+ vi.mocked(installDsh).mockResolvedValue(failure)+ vi.mocked(updateDsh).mockResolvedValue(failure)+ for (const input of [{ url: 'https://example.com/package' }, { id: 'acme/thing' }, { id: 'acme/thing', update: true }]) {+ expect(await mutateDsh(input, () => {})).toEqual(failure)+ }+ vi.useFakeTimers()+ vi.mocked(installDsh).mockImplementation(async options => {+ options.onProgress!({ id: null, phase: 'clone' })+ options.onLine!('working')+ throw new Error('connection lost')+ })+ await expect(mutateDsh({ id: 'acme/thing' }, () => {})).rejects.toThrow('connection lost')+ expect(vi.getTimerCount()).toBe(0)+ })+})diff --git a/cli/src/dsh/service.ts b/cli/src/dsh/service.tsindex 6111a8296..d6b581cc4 100644--- a/cli/src/dsh/service.ts+++ b/cli/src/dsh/service.ts@@ -44,12 +44,15 @@ export const mutateDsh = async ({ id, url, ref, update }: { id?: string; url?: sif (!timer) timer = setTimeout(flushLine, 300)},}- const result = update ? await updateDsh({ ...options, id: id! }) : await installDsh(options)- if (timer) { clearTimeout(timer); timer = null }- if (!result.ok) {- console.warn(`[dsh] ${update ? 'update' : 'install'} of ${id ?? url} failed · ${result.error} · ${result.detail}`)- return { ok: false, error: result.error, detail: result.detail }+ try {+ const result = update ? await updateDsh({ ...options, id: id! }) : await installDsh(options)+ if (!result.ok) {+ console.warn(`[dsh] ${update ? 'update' : 'install'} of ${id ?? url} failed · ${result.error} · ${result.detail}`)+ return { ok: false, error: result.error, detail: result.detail }+ }+ console.log(`[dsh] ${update ? 'updated' : 'installed'} ${result.installed.id} at ${result.installed.dir}`)+ return { ok: true, id: result.installed.id }+ } finally {+ if (timer) clearTimeout(timer)}- console.log(`[dsh] installed ${result.installed.id} at ${result.installed.dir}`)- return { ok: true, id: result.installed.id }}diff --git a/cli/src/dsh/update.spec.ts b/cli/src/dsh/update.spec.tsindex ef2760f7e..8aec0d959 100644--- a/cli/src/dsh/update.spec.ts+++ b/cli/src/dsh/update.spec.ts@@ -3,7 +3,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'import { execFileSync } from 'node:child_process'import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync, writeFileSync } from 'node:fs'import { tmpdir } from 'node:os'-import { join } from 'node:path'+import { join, relative } from 'node:path'import { env } from '../config/env.js'import { dshInstallDir, installedDsh, invalidateInstalledDsh, readInstalledIndex, upsertInstalledRecord } from './installed.js'import { installDsh, removeDsh, type DshInstallProgress } from './install.js'@@ -213,6 +213,26 @@ describe('package updates', () => {expect(installedDsh(id)?.commit).toBe(ref)})+ it('records local clone sources absolutely so updates do not depend on the original working directory', async () => {+ const repo = create()+ await installDsh({ source: relative(process.cwd(), repo) })+ expect(readInstalledIndex()[0]!.source).toBe(repo)+ write(repo, { 'AGENTS.md': '# Latest' })+ const ref = commit(repo)+ expect((await update()).ok).toBe(true)+ expect(installedDsh(id)?.commit).toBe(ref)+ })++ it('restores the harness if its update introduces a viewer that cannot be installed', async () => {+ const repo = create()+ await installDsh({ source: repo })+ const before = readInstalledIndex()+ write(repo, { 'harness.json': JSON.stringify({ ...manifest, viewer: { use: 'acme/unpublished' } }) })+ expect(await update(catalog(repo, commit(repo)))).toMatchObject({ ok: false, error: 'VIEWER_UNAVAILABLE' })+ expect(readInstalledIndex()).toEqual(before)+ expect(installedDsh(id)?.manifest.viewer).toBeUndefined()+ })+it('skips unchanged package content even when another folder changed in the monorepo', async () => {const path = 'store/agents/thing'const repo = create(path)diff --git a/cli/vitest.dsh-updates.config.ts b/cli/vitest.dsh-updates.config.tsnew file mode 100644index 000000000..a6204d0d3--- /dev/null+++ b/cli/vitest.dsh-updates.config.ts@@ -0,0 +1,19 @@+import { defineConfig } from 'vitest/config'+import base from './vitest.config.js'++export default defineConfig({+ ...base,+ test: {+ ...base.test,+ include: ['src/dsh/**/*.spec.ts', 'src/backendSocket.dsh.spec.ts'],+ testTimeout: 30_000,+ coverage: {+ provider: 'v8',+ enabled: true,+ include: ['src/dsh/update.ts', 'src/dsh/updates.ts', 'src/dsh/lock.ts', 'src/dsh/service.ts'],+ thresholds: { statements: 100, branches: 100, functions: 100, lines: 100, perFile: true },+ reporter: ['text', 'json-summary'],+ reportsDirectory: 'coverage/dsh-updates',+ },+ },+})diff --git a/desktop/lib/store/store_screen.dart b/desktop/lib/store/store_screen.dartindex 4e1d43357..d19d941bf 100644--- a/desktop/lib/store/store_screen.dart+++ b/desktop/lib/store/store_screen.dart@@ -1258,9 +1258,7 @@ class _InstallLine extends StatelessWidget {} else if (run != null && run.failed) {status =run.log.where((line) => line.startsWith('miss')).lastOrNull ??- (installed- ? 'Update failed · previous version kept'- : 'Install failed');+ (installed ? 'Update failed' : 'Install failed');} else if (installed) {status = row?.linked == true? 'Installed · linked to a checkout'diff --git a/desktop/test/store_update_e2e_test.dart b/desktop/test/store_update_e2e_test.dartindex cfcf68225..533c6f3bf 100644--- a/desktop/test/store_update_e2e_test.dart+++ b/desktop/test/store_update_e2e_test.dart@@ -132,14 +132,16 @@ void main() {}Future<void> waitUntil(bool Function() done) async {- await tester.runAsync(() async {- final deadline = DateTime.now().add(const Duration(seconds: 30));- while (!done()) {- if (DateTime.now().isAfter(deadline))- fail('Update did not finish: $diagnostics');- await Future<void>.delayed(const Duration(milliseconds: 50));+ final deadline = DateTime.now().add(const Duration(seconds: 30));+ while (!done()) {+ if (DateTime.now().isAfter(deadline)) {+ fail('Update did not finish: $diagnostics');}- });+ await tester.runAsync(+ () => Future<void>.delayed(const Duration(milliseconds: 50)),+ );+ await tester.pump();+ }await tester.pumpAndSettle();}@@ -179,7 +181,7 @@ void main() {() => connection.request('smoke_reopen'),);expect(reopened!['preview'], 'my finished project');- expect(reopened['instructions'], 'my custom instructions');+ expect(reopened['instructions'], '<!-- harness:dsh acme/thing -->\noriginal instructions\n\nmy custom instructions\n');expect(reopened['skill'], 'skill version 3');expect(reopened['verdict'], {'ready': true, 'summary': 'finished'});diff --git a/desktop/test/store_viewers_test.dart b/desktop/test/store_viewers_test.dartindex 34abf69ae..0a4732ad6 100644--- a/desktop/test/store_viewers_test.dart+++ b/desktop/test/store_viewers_test.dart@@ -108,7 +108,12 @@ void main() {).map((button) => (button.child! as Text).data).toList();- expect(users, ['text-to-cad', 'Zeta arm']);+ expect(users, ['View', 'text-to-cad', 'Zeta arm']);+ await tester.tap(+ find.byKey(const ValueKey('store-viewer-action:autonomous/cad-viewer')),+ );+ expect(opened, ['autonomous/cad-viewer']);+ opened.clear();await tester.tap(find.byKey(const ValueKey(diff --git a/docs/cli.md b/docs/cli.mdindex 38f837775..9201dbe94 100644--- a/docs/cli.md+++ b/docs/cli.md@@ -16,6 +16,7 @@ works the same on a headless Linux server; the app is not required on a machine,| `harness start [-f] [--repair]` | Start the daemon from the saved session. `-f` runs in the foreground for a supervisor. `--repair` re-verifies the managed Node runtime. || `harness stop` · `harness logout` · `harness reset` | Stop the daemon · stop and clear the SSO session · stop and clear all local state. || `harness status` · `harness version` · `harness update [--force]` | Running, pid, machine id, session count · version · update now. |+| `harness dsh list` · `harness dsh update <owner/name>` | Installed harness package versions and available updates · update one package while preserving its workspaces. || `harness machines [list] [--json]` · `harness machines delete <id>` | This account's machines · remove another machine (never this one). || `harness pair <code>` · `harness pairings` · `harness unpair <#\|fp\|--all>` | Pair a browser with the code the web client shows; list; unpair. || `harness browser-link` | Print a reusable seven-day setup link for browsers. |diff --git a/docs/development.md b/docs/development.mdindex 637e991dd..b6d6a3d37 100644--- a/docs/development.md+++ b/docs/development.md@@ -58,6 +58,21 @@ cd provider/e2e && npm install && npm testmake device-test```+Harness package updates have a dedicated coverage gate and a desktop-to-daemon integration test:++```bash+cd cli && npm run test:dsh-updates+cd ../desktop+DSH_UPDATE_CLI_ROOT="$PWD/../cli" flutter test test/store_update_e2e_test.dart+```++The coverage gate requires 100% statements, branches, functions and lines in the updater, version+comparison, package locks and daemon mutation handler. The integration test uses temporary local Git+packages and a real WebSocket connection: click Update, reject a broken release, retry successfully,+update a shared viewer, then reopen the preserved workspace and fetch its rendered preview. It needs+Node and the CLI dependencies, with no account or model calls. Its fixture is+`cli/scripts/smoke-dsh-updates.ts`; `DSH_UPDATE_CLI_ROOT` makes this integration run explicit.+Each product releases on its own tag and the suffix routes the workflow: `vX.Y.Z_cli` bundles andpublishes the daemon (running daemons pick it up within a minute), `vX.Y.Z_backend` builds the image,`vX.Y.Z_desktop` builds, signs and publishes both macOS bundles and both Linux architectures.diff --git a/docs/plans/2026-09-17-002-harness-updates.md b/docs/plans/2026-09-17-002-harness-updates.mdindex 3f0fbff08..4a93e85c7 100644--- a/docs/plans/2026-09-17-002-harness-updates.md+++ b/docs/plans/2026-09-17-002-harness-updates.md@@ -1,5 +1,7 @@# Harness package updates+Status: implemented; final regression checks in progress.+Add explicit updates through `harness dsh update <id>` and the desktop Store. The daemon reports theinstalled and available commits; catalog entries may also carry a package tree revision so publishingan unrelated monorepo change does not offer every package an update.@@ -18,3 +20,8 @@ Verification: real local git repositories for whole-repo and subfolder updates,rollback, linked installs, source identity, concurrent mutations and workspace preservation; wire andCLI tests; desktop parsing and Store interaction tests; CLI typecheck/full suite and Flutter analysisand relevant widget tests. Setup scripts' external side effects cannot be rolled back.++Verified so far: 388 package/socket tests pass with 100% statements, branches, functions and lines+across `update.ts`, `updates.ts`, `lock.ts` and `service.ts`. The real Store → daemon → Git → setup →+doctor integration passes rollback, retry, independent viewer updates and reopening an unchanged+workspace with a working viewer. Store regression tests pass. See `docs/development.md` for commands.diff --git a/store/README.md b/store/README.mdindex 0887fcb19..926b2ffca 100644--- a/store/README.md+++ b/store/README.md@@ -247,6 +247,7 @@ the one folder, and runs its setup. From a terminal:```shharness dsh install autonomous/typst # from the shelf+harness dsh update autonomous/typst # update the package; keep projectsharness dsh install "$PWD/store/agents/typst" --link # this working tree, for developmentHARNESS_STORE_REF=my-branch harness start # the shelf from a pushed branch```@@ -260,20 +261,37 @@ The app's start page has a door to the store: every harness as a card, and a pagmark, who made it (`author`), its category and description, where it lives (`repo` and `path`,`homepage`, `upstream`), what it is licensed under (`license`), prompts beside what they made(`examples`), pictures (`screenshots`), ratings and-reviews, and a row per machine with Get, Open or Remove. Installing is still what it always was — a+reviews, and installation actions for this computer: Get, Update, Open and Remove. Installing is still what it always was — aclone (for a built-in package, of its one folder) under `~/.harness/dsh` on one machine, its toolchainset up beside it — so the page is honest about that: a harness is on a machine, not on an account.Ratings and reviews are the signed-in person's, one per package, kept in the control plane, never inthis repository.The sidebar starts with Search, followed by Discover and six broad sections: Design, Engineering,-Media, Science, Games and Code. Cards show Get or Open for each harness; its page manages installation-per machine. Package manifests keep their precise domain labels, grouped only for browsing.+Media, Science, Games and Code. Cards show Get, Update or Open for each harness; its page manages installation+on this computer. Package manifests keep their precise domain labels, grouped only for browsing.++Updates are explicit. The Store shows **Update** when a matching catalog source publishes a different+commit with changed package content. Built-in catalog entries carry their package folder's Git tree+revision, so a change elsewhere in the monorepo does not flag every installed harness. Hover over the+short installed version on a package page to see the installed and available commits.++`harness dsh update <id>` follows the matching catalog's published ref, or the recorded source/ref+for an unlisted package or private fork. A community catalog needs a full commit SHA in `ref` to+advertise updates; moving branches can still be updated from the CLI. Linked checkouts are updated+directly by their owner.++The updater fetches and validates a replacement, retains the previous package, and runs setup and+doctor at the permanent installation path. A failed check restores the old files and installed+record. Workspaces, copied instructions, output files and session identities are preserved; existing+skill links resolve to the updated package. Running sessions are not restarted. Setup scripts may+change external tools, and those external side effects cannot be rolled back. Shared viewer updates+are independent: open their page from **Viewers**, then choose **Update**.Viewer packages are shared dependencies, not Store listings. Installing a harness installs its vieweron that machine when needed; another harness using the same viewer reuses the installed copy. Viewersstay out of Discover, search and categories. Authors can still inspect and manage them with-`harness dsh list`, `doctor` and `remove`. A small **Viewers** icon at the bottom of the Store+`harness dsh list`, `update`, `doctor` and `remove`. A small **Viewers** icon at the bottom of the Storesidebar opens the viewer inventory, where each viewer shows its installed machines and the agentsthat depend on it. Dependency names come from the machines' catalogs, including community packages;an older daemon may not report that information yet.diff --git a/store/spec/CHANGES.md b/store/spec/CHANGES.mdindex 1cd513c53..e6c66ecfe 100644--- a/store/spec/CHANGES.md+++ b/store/spec/CHANGES.md@@ -154,3 +154,22 @@ Initial contract. Lifted from the `.board.json` (Circuit) and `.episode.json` (T- **Mechanism:** `StoreExampleSchema` in `cli/src/dsh/registry.ts`, `cli/scripts/lib/dshRegistry.mjs`,`cli/src/dsh/wire.ts`, the publisher's checks in `store/tools/catalog.mjs`, and the desktop`StoreExample` / `StoreShowcase`.++## 2026-09-17 — explicit package updates++- **Change:** installed records add optional `revision` (the package Git tree) and `updatedAt`.+ Catalog entries add optional `revision`; `ref` remains the source commit or ref to fetch.+ Installed `dsh_list` rows add `installedCommit`, `availableCommit` (nullable source SHAs) and+ `updateAvailable`. A changed tree avoids false updates from unrelated monorepo commits; older+ records fall back to comparing source commits. Linked installs and different sources are excluded.+- **Wire:** `dsh_update { id }` replies `{ ok: true, id }` or `{ error, detail }`, reusing+ `dsh_install_status` for clone/setup/doctor/done/failed progress. The daemon validates the id and+ follows the stored source; request URL/ref overrides are not accepted. Concurrent package mutations+ return `DSH_BUSY`. Unsupported daemons retain their normal unsupported-request response.+- **Behavior:** `harness dsh update <id>` and the Store's Update action replace the package only after+ fetching and identity checks. Setup and doctor run at its permanent path, with the previous copy+ retained until success. On failure it is restored; workspaces are never rematerialized by an update.+ Setup scripts' changes outside the package cannot be reverted by the host.+- **Backward compatible:** all version fields are optional additions. Older records remain readable;+ older desktop clients ignore new fields, and newer clients show their existing actions for daemons+ without update metadata. Shared viewers update independently.