@hasna/recordings 0.2.13 → 0.3.1

package/Dockerfile.package

@@ -1,15 +1,14 @@
 # syntax=docker/dockerfile:1
 # Image built from the published @hasna/recordings npm tarball by the ECR image
-# builder (CodeBuild, ARM64). Runs recordings-serve (PURE REMOTE, Amendment A1):
-# the serve process reads/writes the shared cloud Postgres directly with
-# @hasna/contracts API-key auth. No local sqlite/sync in the service.
+# builder (CodeBuild, ARM64). Runs recordings-serve with the `postgresql` data
+# backend: the serve process reads/writes the shared Postgres directly, selected
+# by the presence of HASNA_RECORDINGS_DATABASE_URL. No on-box sqlite/sync in the
+# service.
 
 FROM oven/bun:1.3.13-alpine AS runtime
 
 ENV NODE_ENV=production \
     HASNA_APP_NAME=recordings \
-    HASNA_APP_MODE=self_hosted \
-    HASNA_RECORDINGS_STORAGE_MODE=remote \
     HOST=0.0.0.0 \
     PORT=8874 \
     NODE_EXTRA_CA_CERTS=/etc/ssl/certs/rds-global-bundle.pem \

package/README.md

@@ -26,7 +26,7 @@ provides recording controls and access to the main window while it is in the bac
   the CLI and MCP write), searchable and filterable by project, mode, and machine, with a
   detail pane (copy, paste-into-front-app, audio playback, metadata).
 - **Projects** — app projects are registered through the same canonical Store before a
-  recording can reference them, preserving referential integrity in local and remote modes.
+  recording can reference them, preserving referential integrity on either store.
 - **Settings** (⌘,) — OpenAI key, language, recording shortcut, permissions, projects,
   and voice shortcuts.
 
@@ -59,6 +59,9 @@ recordings app install \
 
 recordings app open           # launch it
 recordings app status         # show install state
+recordings app snapshot       # write ./desktop-snapshot.png for local UI debugging
+# From this repository, optionally choosing another output path:
+bun run desktop:snapshot -- /tmp/recordings-desktop.png
 /Applications/Recordings.app/Contents/Helpers/recordings-update-client status
 
 # Release builds run only as the isolated _recordingsbuild account. Provision these first:
@@ -115,7 +118,10 @@ RECORDINGS_RELEASE_COMPATIBLE_COHORT_MANIFEST="/Library/Application Support/Hasn
   ./build.sh release app-update
 
 # Explicit local-only alternative when Developer ID credentials are unavailable.
-# Build on a Mac other than the approved target; this does not replace a release:
+# Build on a Mac other than the approved target; this does not replace a release.
+# The approved targets are declared once in
+# scripts/policy/local-only-approved-targets.txt, which the builder, the installer,
+# and the artifact tool all read; add a Mac there rather than in any guard:
 RECORDINGS_LOCAL_APPROVED_TARGET="station06" \
 RECORDINGS_LOCAL_APPROVED_TARGET_IDENTITY_KIND="tailscale_node_id_sha256" \
 RECORDINGS_LOCAL_APPROVED_TARGET_IDENTITY_SHA256="AUTHENTICATED_TAILSCALE_NODE_ID_SHA256" \
@@ -135,6 +141,27 @@ recordings app install \
   --approved-target-identity-sha256 AUTHENTICATED_TAILSCALE_NODE_ID_SHA256 \
   --acknowledge-local-signing-and-permissions \
   --launch
+
+# Reinstalling or repairing an already-installed local-only app additionally needs
+# --allow-adhoc-identity-migration. Local-only builds are ad-hoc signed, so every rebuild
+# produces a new CDHash; replacing the installed app is therefore a real identity migration
+# and the installer refuses it with exit 1 until you approve it once, explicitly. Approving
+# it voids the Microphone and Accessibility grants held by the replaced app -- macOS keys
+# those to code identity and the installer cannot restore them -- so expect to grant both
+# again afterwards. Run `scripts/install_macos_app.sh --help` for the full argument list.
+recordings app install \
+  --artifact /path/to/Recordings-0.2.13-macos-station06-local-only.zip \
+  --manifest /path/to/Recordings-0.2.13-macos-station06-local-only.manifest.json \
+  --manifest-sha256 AUTHENTICATED_MANIFEST_SHA256 \
+  --expected-source-sha APPROVED_40_CHARACTER_COMMIT_SHA \
+  --expected-version 0.2.13 \
+  --artifact-policy local-only \
+  --approved-target station06 \
+  --approved-target-identity-kind tailscale_node_id_sha256 \
+  --approved-target-identity-sha256 AUTHENTICATED_TAILSCALE_NODE_ID_SHA256 \
+  --acknowledge-local-signing-and-permissions \
+  --allow-adhoc-identity-migration \
+  --launch
 swift test                    # run the native test suite
 ```
 
@@ -236,7 +263,9 @@ signature check. The mutable `/Applications` path is never executed, caller stat
 not inherited, and all snapshot paths are removed by normal installer cleanup. The builder applies
 the same checks in its private build directory and removes the snapshot with the rest of the build
 workspace. The status parser then
-requires online `Self` with hostname `station06`,
+requires online `Self` whose hostname equals the caller's `--expected-hostname` — the
+approved target when the installer verifies the target, and the builder's own host when
+the builder verifies itself, which `build.sh` requires to differ from the target —
 requires the single nonempty `Self.ID` to contain no whitespace or NUL, hashes its exact decoded
 bytes without a newline, and compares the digest. Neither raw node ID is written to the manifest,
 build log, or installer log. Older schema-v3 artifacts without an
@@ -264,6 +293,31 @@ The native app uses OpenAI realtime transcription for the stop-and-paste path: s
 unsettled, or cannot be saved. Raw and processed transcript fields are still stored
 separately, so cleanup instructions never replace the verbatim transcript.
 
+### What the app reads to confirm a paste
+
+Posting a Cmd-V keystroke returns no delivery receipt — `CGEvent.post` returns `Void` — so
+the only way to know whether a transcript actually landed is to look. Around each paste the
+app therefore **reads the text value of whatever field is focused in the target app**, via
+Accessibility, once before the keystroke and once after, and compares them.
+
+State this plainly because it is a real change in what a dictation app can see:
+
+- The read covers the focused field's full value and its current selection, not only the
+  pasted fragment, so text you did not dictate is inside the app's process during the
+  comparison.
+- It is **never logged and never persisted.** The comparison happens in memory and only its
+  verdict (`pasted` / `not observed` / `unverified` plus a reason) reaches the log.
+- Fields longer than 20,000 characters are reported unverifiable rather than copied and
+  scanned.
+- A field that publishes no Accessibility value — terminals, canvas editors, some Electron
+  apps — is reported as unverified, never as a success.
+- Reading requires the Accessibility permission the app already needs to post the keystroke.
+  No additional permission is requested, which is exactly why this is worth writing down.
+
+One known limit, in the safe direction: pasting text identical to the selection it replaces
+leaves the field's value and the occurrence count unchanged, so a genuinely successful paste
+is reported as **not observed**. The app under-claims rather than over-claims.
+
 ## CLI Usage
 
 ```bash
@@ -378,9 +432,23 @@ Endpoints: `GET /health` → `{"status":"ok","name":"recordings"}`, MCP at `/mcp
 
 ## HTTP API (`recordings-serve`)
 
-`recordings-serve` is the self-hosted HTTP API. In cloud mode it is PURE REMOTE
-(Amendment A1): the process reads/writes the shared cloud Postgres directly with
-API-key auth via [`@hasna/contracts`](https://www.npmjs.com/package/@hasna/contracts).
+`recordings-serve` is the HTTP API. Its data backend is a single two-value
+switch, `HASNA_RECORDINGS_STORAGE_MODE=sqlite | postgresql` (a
+`HASNA_RECORDINGS_DATABASE_URL` on its own implies `postgresql`). On
+`postgresql` the process reads/writes that database directly with API-key auth
+via [`@hasna/contracts`](https://www.npmjs.com/package/@hasna/contracts).
+
+There are no deployment modes. `local`, `self-hosted`, `cloud`, `remote` and
+`hybrid` no longer select anything, and passing one is an error that names the
+variable and value to use instead. Where the server runs, and who operates it,
+never changed how it stored data.
+
+The CLI and MCP client are a separate, two-value switch:
+`HASNA_RECORDINGS_CLIENT_STORE=sqlite | http`. Setting
+`HASNA_RECORDINGS_API_URL` + `HASNA_RECORDINGS_API_KEY` selects `http` on its
+own; `HASNA_RECORDINGS_CLIENT_STORE=sqlite` forces the on-box file even when
+both are set. The client never opens Postgres — it reaches the shared dataset
+only through this API.
 
 ```bash
 recordings-serve --port 8874          # start the API
@@ -401,8 +469,9 @@ Versioned API (`/v1/*`, API-key auth via `x-api-key` or `Authorization: Bearer`)
 | GET/POST | `/v1/agents` · GET `/v1/agents/:id` | `recordings:read` / `recordings:write` |
 | GET/POST | `/v1/projects` · GET `/v1/projects/:id` | `recordings:read` / `recordings:write` |
 
-Env: `HASNA_RECORDINGS_DATABASE_URL` (remote Postgres DSN — enables cloud `/v1`)
-and `HASNA_RECORDINGS_API_SIGNING_KEY` (HMAC signing secret for API-key auth).
+Env: `HASNA_RECORDINGS_STORAGE_MODE` (`sqlite` | `postgresql`),
+`HASNA_RECORDINGS_DATABASE_URL` (PostgreSQL DSN — implies `postgresql`) and
+`HASNA_RECORDINGS_API_SIGNING_KEY` (HMAC signing secret for API-key auth).
 
 ## SDK
 
@@ -433,6 +502,42 @@ context, `transcriber_prompt` for cleanup instructions, and `post_processing_mod
 `off`, `auto`, or `always`. Tool results preserve `raw_text` and return `processed_text`
 only when post-processing actually produced enhanced output.
 
+## Releasing
+
+The release version is hand-maintained in four places: `package.json`, `src/version.ts`, and both
+`CFBundleShortVersionString` and `CFBundleVersion` in
+`src/native/Recordings/RecordingsLib/Info.plist`. Bump them together, never by hand:
+
+```bash
+bun run version:set 0.3.0   # rewrites every hand-maintained site
+bun run generate:sdk        # restamps the generated SDK's header
+bun run version:check       # exits 1 if any site disagrees with package.json
+```
+
+A fifth copy is **generated**, not written: `src/server/openapi.ts` stamps `VERSION` into the
+OpenAPI document and `bun run generate:sdk` bakes it into the `// Source: …` header of
+`src/sdk/v1.generated.ts`. `version:set` leaves that file alone — the generator owns it, and
+patching the stamp by hand would hide real regeneration drift — so regenerate after every bump.
+`src/__tests__/version-site-guard.test.ts` fails when the committed header disagrees with
+`package.json`.
+
+`package.json` is the authority because `scripts/build_companion_cli.sh` compares the
+compiled CLI's `--version` against it and exits 1 on a mismatch. That abort propagates
+through `src/native/Recordings/build.sh` (`set -euo pipefail`), so a partial bump does
+not just fail an assertion -- the native app cannot be built at all, and the whole
+`native-app-companion-contract` suite aborts on its first test.
+
+Three things enforce it. `.github/workflows/ci.yml` runs the whole TypeScript suite on
+every push, which is what makes the two guards below actually block a branch rather than
+wait for someone to run them locally. `prepack` runs `build:native-fs-guard` first (the
+fail-closed macOS gate), then `version:check`, so a partial bump stops before the build
+rather than deep inside it. And `prepublishOnly` runs `bun test`, which covers the sites
+through `src/__tests__/native-bundle-version.test.ts` and
+`src/__tests__/version-site-guard.test.ts`.
+
+The Swift side is not covered: no reachable machine currently runs the Swift suite, so a
+version claim about the app bundle is only as verified as the last macOS build.
+
 ## Data Directory
 
 Data is stored in `~/.hasna/recordings/`.

package/bun.lock

@@ -5,7 +5,7 @@
     "": {
       "name": "@hasna/recordings",
       "dependencies": {
-        "@hasna/contracts": "^0.4.2",
+        "@hasna/contracts": "^0.8.4",
         "@hasna/events": "^0.1.11",
         "@modelcontextprotocol/sdk": "^1.12.1",
         "chalk": "^5.4.1",
@@ -23,7 +23,7 @@
     },
   },
   "packages": {
-    "@hasna/contracts": ["@hasna/contracts@0.4.2", "", { "dependencies": { "commander": "^13.1.0", "zod": "^3.25.76" }, "bin": { "contracts": "dist/cli/index.js", "contracts-cli": "dist/cli/index.js" } }, "sha512-xD7ZWQXR+AjYAJVpaMsQ+8V0SABiJSKVeI0B1WbPByYeGz6daDtgyZ6c3q0c2S6uzIEtUxlGHPundr675636ew=="],
+    "@hasna/contracts": ["@hasna/contracts@0.8.4", "", { "dependencies": { "commander": "^13.1.0", "zod": "^3.25.76" }, "bin": { "contracts": "dist/cli/index.js", "contracts-cli": "dist/cli/contracts-cli.js" } }, "sha512-a/flLzdu8cbCUrScNQT3VBMl2HgwbjUYWrmwQ45x19X6F8FPiOf2gbb43MT0vlKTLUPEonh5jSoEPdjp44nAGw=="],
 
     "@hasna/events": ["@hasna/events@0.1.11", "", { "dependencies": { "commander": "^13.1.0" }, "bin": { "events": "dist/cli/index.js", "hasna-events": "dist/cli/index.js" } }, "sha512-X36W9TB8mKxtS5UeW1n2IlvW6nPUcoYCQWNMMV+/JM4YNzlnnk1FRm8Aay02tt1LjQOGICCHF3hz/l//EHEe+Q=="],
 

package/dist/__tests__/helpers/installer-guard-execution.d.ts

@@ -0,0 +1,22 @@
+export declare const EXISTING_IDENTITY_SHA256: string;
+export declare const CANDIDATE_IDENTITY_SHA256: string;
+export declare const MANIFEST_SHA256: string;
+export type ArtifactPolicy = "local-only" | "release";
+export type IncompatibleDirection = "installed-requirement-vs-candidate" | "candidate-requirement-vs-installed" | "both";
+export type GuardExecutionOptions = {
+    identityMigration: boolean;
+    incompatibleDirection?: IncompatibleDirection;
+    artifactPolicy?: ArtifactPolicy;
+    extraArguments?: string[];
+};
+export type GuardExecutionResult = {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    reachedTransaction: boolean;
+    codesignInvocations: string[];
+    bunInvocations: string[];
+    unstubbedInvocations: string[];
+};
+export declare function runInstallerToIdentityGuard(options: GuardExecutionOptions): GuardExecutionResult;
+//# sourceMappingURL=installer-guard-execution.d.ts.map

package/dist/__tests__/helpers/installer-guard-execution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"installer-guard-execution.d.ts","sourceRoot":"","sources":["../../../src/__tests__/helpers/installer-guard-execution.ts"],"names":[],"mappings":"AA+DA,eAAO,MAAM,wBAAwB,QAAiB,CAAC;AACvD,eAAO,MAAM,yBAAyB,QAAiB,CAAC;AACxD,eAAO,MAAM,eAAe,QAAiB,CAAC;AAsB9C,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,SAAS,CAAC;AAuFtD,MAAM,MAAM,qBAAqB,GAE7B,oCAAoC,GAGpC,oCAAoC,GAEpC,MAAM,CAAC;AAEX,MAAM,MAAM,qBAAqB,GAAG;IAKlC,iBAAiB,EAAE,OAAO,CAAC;IAG3B,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;IAK9C,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IAKf,kBAAkB,EAAE,OAAO,CAAC;IAG5B,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAG9B,cAAc,EAAE,MAAM,EAAE,CAAC;IAMzB,oBAAoB,EAAE,MAAM,EAAE,CAAC;CAChC,CAAC;AAEF,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,qBAAqB,GAC7B,oBAAoB,CAwStB"}

package/dist/__tests__/helpers/installer-preflight.d.ts

@@ -0,0 +1,22 @@
+export declare const POLICY_RELATIVE_PATH = "scripts/policy/local-only-approved-targets.txt";
+export declare const READER_RELATIVE_PATH = "scripts/read_local_only_targets.sh";
+export declare const IDENTITY_GUARD_RELATIVE_PATH = "scripts/enforce_identity_migration.sh";
+export declare const readRepositoryFile: (relativePath: string) => string;
+export type InstallerPreflightOptions = {
+    artifactPolicy?: "release" | "local-only";
+    approvedTarget?: string;
+    hostname?: string;
+    extraArguments?: string[];
+    policyContents?: string | null;
+    removeReader?: boolean;
+    removeIdentityGuard?: boolean;
+    identityGuardContents?: string;
+    symlinkIdentityGuard?: boolean;
+    environment?: Record<string, string>;
+};
+export declare function runInstallerPreflight(options?: InstallerPreflightOptions): {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+};
+//# sourceMappingURL=installer-preflight.d.ts.map

package/dist/__tests__/helpers/installer-preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"installer-preflight.d.ts","sourceRoot":"","sources":["../../../src/__tests__/helpers/installer-preflight.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,oBAAoB,mDAAmD,CAAC;AACrF,eAAO,MAAM,oBAAoB,uCAAuC,CAAC;AACzE,eAAO,MAAM,4BAA4B,0CAA0C,CAAC;AAEpF,eAAO,MAAM,kBAAkB,GAAI,cAAc,MAAM,KAAG,MACA,CAAC;AAc3D,MAAM,MAAM,yBAAyB,GAAG;IACtC,cAAc,CAAC,EAAE,SAAS,GAAG,YAAY,CAAC;IAC1C,cAAc,CAAC,EAAE,MAAM,CAAC;IAGxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAG9B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAG/B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAG/B,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC,CAAC;AAEF,wBAAgB,qBAAqB,CACnC,OAAO,GAAE,yBAA8B,GACtC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CA8GtD"}

package/dist/__tests__/helpers/native-fs-guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"native-fs-guard.d.ts","sourceRoot":"","sources":["../../../src/__tests__/helpers/native-fs-guard.ts"],"names":[],"mappings":"AAKA,wBAAgB,wBAAwB,CAAC,cAAc,SAAuC,GAAG,MAAM,CAsCtG"}
+{"version":3,"file":"native-fs-guard.d.ts","sourceRoot":"","sources":["../../../src/__tests__/helpers/native-fs-guard.ts"],"names":[],"mappings":"AA2CA,wBAAgB,wBAAwB,CAAC,cAAc,SAAuC,GAAG,MAAM,CActG"}

package/dist/__tests__/helpers/source-assertions.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Shared assertions for contract tests that read source text.
+ *
+ * These live here rather than inside one suite because the defect they exist to prevent is
+ * repo-wide: a sweep of every `*.test.ts` found 40 ordering assertions written as
+ * `indexOf(a) < indexOf(b)`, across 11 files. `indexOf` answers -1 when the needle is absent and
+ * `-1 < anything` is true, so such an assertion PASSES when the thing being ordered is DELETED.
+ * The same hole exists in `.slice(indexOf(...), indexOf(...))` region bounds, where a -1 silently
+ * slices from the end of the file or to its start — a region assertion over the wrong text, or over
+ * none of it, reads exactly like a satisfied one.
+ *
+ * ---------------------------------------------------------------------------------------------
+ * BEFORE YOU BUILD A MUTATION BATTERY: three suites are RED ON A CONTENDED STATION, not on Linux.
+ *
+ * A mutation battery is evidence only when its clean control is GREEN. Include a suite that was
+ * already failing and the run was non-zero before you changed anything, so every mutation "looks
+ * caught" and every verdict is manufactured. That already produced one wrong all-clear here.
+ *
+ * These are the three suites it happens to. NO PASS/FAIL SPLIT IS RECORDED FOR THEM ON PURPOSE —
+ * see below. `macos-app-lifecycle.test.ts` has 140 tests, `native-app-companion-contract.test.ts`
+ * has 14, `config.test.ts` has 44, and how many of those fail is a property of the MACHINE:
+ *
+ *   src/__tests__/macos-app-lifecycle.test.ts
+ *   src/__tests__/native-app-companion-contract.test.ts
+ *   src/__tests__/config.test.ts
+ *
+ * CORRECTED 2026-07-27, and the correction is the useful part. This block used to call them
+ * "PERMANENTLY RED on Linux" and attribute fixed environmental causes — BSD `stat -f`, a fixture
+ * port reading `NaN`, a `getDataDir` HOME-ancestor assumption. The first CI run this repository
+ * ever had (run 30302342895, ubuntu-24.04) re-ran all three on a clean single-tenant runner and
+ * every one of them PASSED:
+ *
+ *   macos-app-lifecycle            140 pass / 0 fail   (358.85s)
+ *   native-app-companion-contract   14 pass / 0 fail   (  4.50s)
+ *   config                          44 pass / 0 fail   (  0.10s)
+ *
+ * So the cause is not the platform. Measure on a quiet machine, or in CI, before recording a suite
+ * as red. There were TWO independent station-local causes, and every earlier version of this comment
+ * named only one of them. In a 92-fail run of `macos-app-lifecycle.test.ts` on this station the
+ * failure messages broke down as 38 × `Home ancestor has an unexpected owner.`, 22 × FIFO
+ * synchronisation timeout, 24 × ENOENT on a fixture marker. The first cause is now fixed in the
+ * fixture and only the second remains; do not collapse them into one, because a quiet machine with
+ * `FORCE_COLOR` set still showed all 38 aborts, so "measure on a quiet machine" was necessary and
+ * not sufficient:
+ *
+ *   1. `FORCE_COLOR` — **FIXED IN THE FIXTURE, no longer a live cause.** The `stat` stub answered
+ *      `%u` by shelling out to `bun -e '… console.log(statSync(…).uid)'`
+ *      (`macos-app-lifecycle.test.ts:217`) and spread `...Bun.env` into the installer, so with
+ *      `FORCE_COLOR` set Bun COLOURED the number: the installer compared `\e[0m\e[33m1000\e[0m`
+ *      against `id -u`'s `1000` at `install_macos_app.sh:143` and aborted before reaching any gate.
+ *      `NO_COLOR=1` did NOT help — FORCE_COLOR wins in Bun. The stub now writes bare integers with
+ *      `process.stdout.write` and `unset FORCE_COLOR`s its own children, which takes that message
+ *      from 38 to 0 in place, positive-controlled (the same grep still finds 38 in the pre-fix log).
+ *      Nothing about ancestor MODE was ever involved: `verify_secure_parent` and
+ *      `verify_safe_home_ancestor` each `stat` only the one path handed to them, the sole call is
+ *      `verify_safe_home_ancestor "$HOME"`, and the stub hardcodes every `%Lp` answer anyway.
+ *      Kept here rather than deleted because it is the reason this file's split moved, and because
+ *      the same trap recurs in any stub that parses `console.log` of a NUMBER: only strings are
+ *      left uncoloured.
+ *   2. CONTENTION. The station routinely runs several full recordings suites at once out of
+ *      different worktrees, and this suite scans a shared /tmp — the hazard this very comment warns
+ *      about below. Those were FIFO timeouts at an internal 5000ms budget; the FIFO helper now uses
+ *      the suite's configured timeout too, so a raised test budget can distinguish load sensitivity
+ *      from a regression. With `FORCE_COLOR` unset the residual failures scaled with load: 132 pass /
+ *      8 fail at load ~20, 114 pass / 26 fail at load 44-60 on the same commit, which is why no split
+ *      belongs here either. GitHub Actions sets neither `FORCE_COLOR` nor a competing suite, which
+ *      is why both causes were absent from the only clean measurement.
+ *
+ * WHY NO SPLIT IS RECORDED. Every split ever written here has gone stale, including two written as
+ * corrections. On one unchanged tree, three consecutive runs measured 48/92, 48/92, 49/91; the
+ * single test that flips is `runtime smoke timeout does not wait forever on a live open process`
+ * (`macos-app-lifecycle.test.ts:3594`), which races a hardcoded internal `Bun.sleep(2_000)` that no
+ * `--timeout` flag reaches either. So a count comparison across two trees shows a phantom delta
+ * from this file alone — which is the concrete reason for the rule below: compare failing test
+ * NAMES, never counts. Two trees whose failing NAME SETS are identical are identical regardless of
+ * what the totals say.
+ *
+ * `@hasna/events` MUST resolve 0.1.11, as `bun.lock` pins it. A plain `bun install` pulls 0.1.14,
+ * which dropped a shipped CLI command inside the patch range and fails `cli.test.ts` — and it can
+ * drift back mid-session, so re-check it before quoting any cross-tree comparison.
+ *
+ * Corollary, also corrected: this repo NOW HAS CI. `.github/workflows/ci.yml` gates the whole
+ * suite with no exemptions on every pull request, so these suites are no longer gated only by
+ * somebody remembering to run them. What CI does NOT cover is the Swift/C half, which does not
+ * currently compile; see `.github/native-known-errors.txt`.
+ * Compare failing test NAMES, never counts — the suite is nondeterministic at the margin.
+ * ---------------------------------------------------------------------------------------------
+ */
+/**
+ * Assert `first` appears before `second`, requiring BOTH to exist.
+ *
+ * Use this instead of comparing two `indexOf` results directly. `firstMatch: "last"` selects
+ * `lastIndexOf` for the first operand, which has the identical -1 hole.
+ */
+export declare function expectOrder(haystack: string, first: string, second: string, options?: {
+    firstMatch?: "first" | "last";
+}): void;
+/**
+ * Slice between two markers, requiring both to exist and the region to be non-trivial.
+ *
+ * The length floor matters as much as the -1 checks: `slice(-1)` yields a ONE-CHARACTER string, not
+ * an empty one, so a `expect(region.length).toBeGreaterThan(0)` control passes on a region that
+ * contains nothing worth asserting about. Any `not.toContain` over such a region is vacuous.
+ */
+export declare function sliceBetween(source: string, open: string, close: string, options?: {
+    minimumLength?: number;
+}): string;
+/**
+ * Assert a marker occurs exactly once before slicing on it.
+ *
+ * A duplicated end marker silently extends a region: `let myPID = ProcessInfo…` occurs twice in
+ * `RecordingEngine.swift`, so a region bounded by it could stretch ~127 KB and be satisfied by
+ * copies of the needle from an unrelated function.
+ */
+export declare function sliceBetweenUnique(source: string, open: string, close: string): string;
+/** Strip Swift line comments so an assertion about code is not defeated by prose. */
+export declare function withoutComments(source: string): string;
+/**
+ * Index just past the `close` matching the `open` at `openIndex`, skipping comments and literals.
+ *
+ * Needed because `lastIndexOf("}")` is not brace matching, and the difference is a live defect: an
+ * early exit written between a decision and its use —
+ *
+ *     }                                        // the decision table closes here
+ *     guard stillOwnsChangeCount else { return }
+ *     if shouldRestore { … }
+ *
+ * — puts a NEARER `}` (the `else` block's) between the two, so a "nothing between them" check
+ * measured from the last brace saw only whitespace and passed. Counting braces naively fails the
+ * other way: one `}` inside a string literal, such as `log("settlement }")`, cancels a real opener.
+ * Both were measured surviving at EXIT=0.
+ */
+export declare function matchingDelimiterIndex(source: string, openIndex: number, open: string, close: string): number;
+export declare function withoutAnyComments(source: string): string;
+/**
+ * The arms of a Swift `switch` body, as a mapping from each matched case to its expression.
+ *
+ * Order- and grouping-independent, which matters because pinning an arm by its exact TEXT gets both
+ * directions wrong. It false-positives on a pure reorder — `.deliveredUnverified, .deliveryNotObserved`
+ * is the same table and failed — and it misses a real defect: splitting one outcome out of a group
+ * into its own arm with a different expression leaves the pinned needle intact, so
+ * `.targetUnavailable` could be given `false` while the six-outcome needle still matched.
+ *
+ * `body` is the text between the switch's braces, comments already stripped by the caller.
+ */
+export declare function switchArmsByOutcome(body: string): Map<string, string>;
+/**
+ * Evaluate a Swift boolean condition for a given binding of its identifiers.
+ *
+ * Folded in from PR #43, which pinned the clipboard-restore guard by evaluating it for BOTH values
+ * of the decision rather than comparing its text. That is the half worth keeping: an exact
+ * `toBe("shouldRestore")` on a captured condition kills the inversion, but it also fails on
+ * `(shouldRestore)` and on a trailing comment — reporting refactors as defects while proving
+ * nothing about behaviour.
+ *
+ * Deliberately narrow and fail-CLOSED: `true`, `false`, `!x`, whole-expression parentheses, and
+ * identifiers present in `env`. Anything else throws. An added disjunct
+ * (`shouldRestore || stillOwnsChangeCount`) is an unevaluatable expression, not a passing one —
+ * which is the behaviour that matters, because that disjunct is exactly how the
+ * transcript-destroying defect gets reintroduced. Extend the evaluator when a new shape is
+ * legitimate; do not loosen the assertion.
+ */
+export declare function evaluateSwiftCondition(condition: string, env: Record<string, boolean>): boolean;
+/**
+ * Every Swift source under a root, so an absence claim can be made about the app rather than about
+ * whichever files were on the reviewer's mind.
+ */
+export declare function swiftSourcesUnder(root: string): Array<[path: string, source: string]>;
+//# sourceMappingURL=source-assertions.d.ts.map

package/dist/__tests__/helpers/source-assertions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-assertions.d.ts","sourceRoot":"","sources":["../../../src/__tests__/helpers/source-assertions.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuFG;AAEH;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;CAAO,GAC9C,IAAI,CAON;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAO,GACvC,MAAM,CAWR;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAMtF;AAED,qFAAqF;AACrF,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKtD;AAuED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,MAAM,CA0BR;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAoEzD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAyBrE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAiC/F;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAIrF"}

package/dist/__tests__/preload.d.ts

@@ -1,5 +1,2 @@
-/**
- * Test preload — currently a no-op since we use bun:sqlite natively.
- * Kept for future test setup needs.
- */
+export {};
 //# sourceMappingURL=preload.d.ts.map

package/dist/__tests__/preload.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"preload.d.ts","sourceRoot":"","sources":["../../src/__tests__/preload.ts"],"names":[],"mappings":"AAAA;;;GAGG"}
+{"version":3,"file":"preload.d.ts","sourceRoot":"","sources":["../../src/__tests__/preload.ts"],"names":[],"mappings":""}

package/dist/cli/desktop-snapshot.d.ts

@@ -0,0 +1,20 @@
+export declare const DEFAULT_DESKTOP_SNAPSHOT = "desktop-snapshot.png";
+type CaptureResult = {
+    error?: Error;
+    status: number | null;
+    stderr?: string;
+};
+type DesktopSnapshotDependencies = {
+    platform?: NodeJS.Platform;
+    cwd?: string;
+    capture?: (executable: string, arguments_: string[]) => CaptureResult;
+};
+/**
+ * Write a main-display snapshot to a stable caller-visible path.
+ *
+ * `screencapture` writes into a private sibling directory first so a denied Screen Recording
+ * grant or an interrupted capture cannot truncate a useful snapshot from the previous run.
+ */
+export declare function exportDesktopSnapshot(output?: string, dependencies?: DesktopSnapshotDependencies): string;
+export {};
+//# sourceMappingURL=desktop-snapshot.d.ts.map

package/dist/cli/desktop-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"desktop-snapshot.d.ts","sourceRoot":"","sources":["../../src/cli/desktop-snapshot.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,wBAAwB,yBAAyB,CAAC;AAE/D,KAAK,aAAa,GAAG;IACnB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,KAAK,2BAA2B,GAAG;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,aAAa,CAAC;CACvE,CAAC;AAcF;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,SAA2B,EACjC,YAAY,GAAE,2BAAgC,GAC7C,MAAM,CAuDR"}