shockwave / tests

# CLAUDE.md — tests

Node's built-in `node:test` runner. No install needed.

- `npm test` — runs every `tests/**/*.test.js`.
- `node --test tests/<file>.test.js` — run one file (useful when iterating).

## Imports here name `.ts` — this is load-bearing

The suite runs **straight off the source**, no build step. That's what makes it installable-free and quick, and it costs one rule: **Node resolves an import specifier literally.** It has no `extensionAlias`, so `'../src/renderer/linkIndex.js'` does not find `linkIndex.ts` the way Vite and esbuild do. Node strips types natively (22.18+), so the extension is the only thing in the way.

So every import in this directory names the real file — `from '../src/renderer/linkIndex.ts'` — and a module under test that imports **another** module under test names it `.ts` as well (`renameOps.ts`, `metadataCache.ts`, `settingsDiff.ts`, `api/src/keys.ts`). App-side imports elsewhere keep the `.js` spelling; both bundlers rewrite it.

This constraint is why the parser, the rename logic and the credential declaration were plain `.js` — and therefore unchecked by `tsc` — for as long as they were. It read as an unfinished migration and wasn't: being under test is what pinned them. **Adding a test for a module means changing that module's own imports to `.ts` in the same commit.**

## Coverage

| File | Coverage |
|---|---|
| `correlator.unit.test.js` | 13 pure-logic tests for the rename correlator: inode matching, hash fallback, grace timer, batch unlinks/adds, double-rename A→B→C, hash-collision determinism. |
| `correlator.integration.test.js` | 10 tests against real `@parcel/watcher` + the shared `watcherDispatch` + real `fs.rename`. Single renames, batch of 10, identical-content files, rename + simultaneous delete, atomic saves not classified as renames, folder rename emitting per-file renames inside. |
| `linkIndex.test.js` | 15 tests on `createLinkIndex` invariants: `updateFile`/`removeFile`/`renameFile`/`rebuild`, mtime preservation across rename, case-insensitive backlink keys, heading/alias stripping, `getEntriesGroupedBySource` sort/group semantics, `prettyName`. |
| `parserParity.test.js` | Runs both parsers (`src/renderer/linkIndex.ts` and `src/main/linkParser.ts`) against the same fixtures and asserts byte-identical output (incl. `targetParsed`). Add a fixture here when introducing new link syntax. |
| `linkResolver.test.js` | 10 unit tests for the pure resolver (`src/renderer/linkResolver.ts`): bare-unique, bare-ambiguous (same-folder + shortest tiebreakers), path-qualified exact/suffix match, stale-path→basename fallback, and `shortestUniqueLinkFor` (bare when unique, shortest disambiguating prefix, case preserved). |
| `renameOps.test.js` | 8 tests on `renameWithReferences` and `rewriteReferences` with an in-memory `fs` stub: rewrite-in-other-files, heading/alias preservation, case-insensitive match, self-reference rewriting, no-op when there are no backlinks, resolution-filtered rewrite (only the link resolving to the renamed file is rewritten), move re-qualifying path-links when a duplicate moves, and move of a unique basename as a no-op. |
| `loadDecision.test.js` | 11 tests on the one rule that decides whether the editor reads the active file from disk (`src/renderer/loadDecision.ts`). Pure, because the two ways it was got wrong both ended with a buffer on screen that did not belong to the file the tab pointed at — and the tab still saves to that file, so the next keystroke wrote the wrong content over it. Pins both: a draft tab gaining a path is **not** proof its draft was saved (clicking a file in the tree reuses the active tab, and React 18 batches the save and the navigation into one render, so they are indistinguishable from outside — an untouched new file followed by a click showed the empty buffer as that file), and "already loaded" must be confirmed by the editor rather than by our note about it (the view is rebuilt on a theme change and destroyed when graph view unmounts it, neither of which changes the active file, so the note outlived the buffer and leaving graph view left an empty editor over a real file). Also covers a promotion belonging to a different tab, a promotion into a rebuilt view, and that the draft's undo history follows the file it became even when a different file is then loaded. Both bugs were reproduced in the running app before the fix and re-checked after; what is *not* covered here is the effect wiring itself (`onViewCreated` → `editorEpoch`), which needs a DOM. |
| `linkingSystem.e2e.test.js` | 12 end-to-end tests with a real tmp workspace + `@parcel/watcher` + `watcherDispatch` + correlator + the renderer-side index. Exercises every external-actor scenario: rename rewrites refs, rename rewrites self-refs, folder rename re-keys nested files, deletes, adds, in-place edits, 10 simultaneous renames, atomic save not classified as rename. |
| `workspaceWatcher.test.js` | 2 tests against a real git repo + real `git merge` (what GitHub sync runs) with main's `@parcel/watcher` config for `.shockwave/`. Asserts the recursive dir watch (filtered to `workspace.json`) notifies on a merge that updates `workspace.json`, and never for sibling-only changes (`bookmarks.json`, `skills/`). |
| `workspaceFolder.test.js` | 17 tests for the add-workspace folder decision (`src/main/workspaceFolder.ts`), against REAL git repos in tmp dirs — the thing under test is what git reports, so stubbing git would test the stub. Covers all three states: `empty` (including the dotfile/`.DS_Store`-only case, which must NOT read as occupied), `clone` (https + ssh origins, and the branch coming from what's CHECKED OUT rather than an assumed default — the row stores it and the engine pushes to it), and `occupied` (files with no `.git`, a repo with no origin, a non-GitHub origin, a missing folder, an empty path). Plus `repoMismatch` — the guard `ensureCheckout` uses to stop a workspace attaching to a folder holding a different repo — and `parseGithubUrl` across every form git stores — including a repo name containing dots (`kontentengine.io`), where only a trailing `.git` may be stripped. |
| `workspaceRow.test.js` | 6 tests for `projectWorkspaceRow` (`src/main/workspaceRow.ts`) — and they now cover the LIVE path. This used to test a function nothing imported: `settingsStore.overlayLocal` built the renderer's shape inline, so the tested projection was fiction and the real one had no coverage, which is how `voiceReply` reached the settings page as undefined. Folding the two together also caught the reason the dead copy was dangerous: it still negated a `sync_disabled` column that **no longer exists** (the toggle is machine-local now and already positive), so adopting it as-written would have made every workspace read as syncing — the exact silent inversion the file was written to prevent. Pins the polarity both ways and absent-means-syncing, that `voiceReply` survives and that junk in it reads as `text` (plain text on the companion, two writers), and the `path: null` ("exists, not checked out on this machine") passthrough. |
| `versionCompare.test.js` | 11 tests over the two halves of the stale-companion kill switch. **The classification** (`src/main/versionCompare.ts`): parse of plain/`v`-prefixed `x.y.z` (and rejection of everything else, incl. injection strings), the three orderings (`match`/`companion-older`/`companion-newer`), numeric-not-lexicographic compare (`1.0.9` < `1.0.10`), and `dev` on either side staying silent. **The predicate that arms it** (`isCompanionStale`, `src/shared/constants.ts`) — one declaration read by main (which refuses every non-GET to the companion while it's true) and by four places in the renderer, so it is pinned where they can't each drift. Wrong in either direction is silent: too narrow and writes go through against a server that can't store them correctly, too wide and the app saves nothing while showing no reason. Covers both real mismatches being stale, **`dev` never being stale** (a local companion reports `APP_VERSION='dev'`, so the wide version would block every write in every development session), `match`/null/undefined reading as fine — not knowing is not a reason to refuse, and an unreachable server already fails at the transport — and an unrecognized status failing open, since these arrive over IPC from a build that may be older than this one. |
| `settingsDiff.test.js` | 17 tests for the pure settings patch-diffing (`src/renderer/settingsDiff.ts`): `buildPatch`/`changedLeaves` emit only leaf keys that actually changed — so a per-field setter can't republish a sibling credential it read from the cache — plus maps that travel whole (`codingAgent.providerKeys`, so a deleted key is visible to the store), collections passed through undiffed, and main-owned keys (`windowBounds`, `cron`) dropped. The last three pin the **rename marker**, deliberately sitting beside the strip that made the bug possible: renaming an agent secret with the token box left blank used to destroy the key, because the value is filed under the secret's NAME and this window holds no copy to resend — so `previousName` travelling intact is the only thing that turns a rename into a re-file. Drop it and the failure looks exactly like the original bug. |
| `settingsModel.test.js` | 11 tests on the renderer's ONE settings object (`src/renderer/settingsModel.ts`). The property is that `normalizeSettings` is **total and pure**: it assigns every key of `Settings` (the return type makes a miss a compile error) from its argument alone, so nothing can survive a payload that doesn't mention it. That is the whole fix for settings surviving a companion switch — the companion answers `GET /settings` from the rows it HAS, so a setting nobody set on that server is *absent*, and the twenty-one-assignment hydrate this replaced guarded seven of them on the key being present, i.e. read "no row here" as "keep the last server's value". The first three tests are that scenario end to end, including the one case that was not merely cosmetic: `codingAgent` fell back through `?? settingsRef.current`, landing a stale slice in the diff base and the merge source, so the OLD server's provider could be written INTO the new one on the next edit. The rest pin what must NOT be invented for a DB-backed value (a `DEFAULT_SETTINGS` merge once showed `anthropic` while the server-side agent threw "provider not configured"), that machine-local keys DO keep defaults, that `micProvider` and `telegramReply` survive a hydrate, both retired `treePanel` shapes still migrating forward, and junk payloads producing a usable shape rather than a crash. |
| `secretDeletes.test.js` | 4 tests on **where a stored credential may be destroyed** (`api/src/store.ts`). A source scan, for the same reasons as `rendererSettingsDoor.test.js`: the property is about which code path is allowed to do a thing, the queries need a live Postgres, and the failure mode is silence — a credential deleted for the wrong reason throws nothing, logs nothing at the call site, and is unrecoverable, the ciphertext being gone rather than orphaned. The rule is **destruction is a request, never an inference**, and every one of the four ways keys were lost came from inferring it: a rename (the name IS the owner, so a new name read as a new entity and the old one was deleted for being absent), a value that wouldn't decrypt (`unseal` returns `''`, and empty used to mean delete — so "I can't read this" became "delete it" on the next launch that wrote the list back), the desktop's own writes (which never had the renderer's drop-empties guard), and a stale list from a second machine or a dropped live feed. Pins that only `dropSecret`/`deleteAgentSecret`/`clearTelegramAccount` delete at all, that `writeAgentSecrets` deletes nothing, that `putSecret` refuses an empty value explicitly rather than treating it as a delete, and that a rename moves the `secret_value` rows. Verified by reintroducing the delete and watching two of the four fail. |
| `setupStatus.test.js` | 9 tests for the "needs setup" rule (`src/renderer/setupStatus.ts`) — the one definition read by the gear badge, the settings nav badges and the pages. Covers the three required items (companion URL **and** key, GitHub token **and** git, agent provider + model + a key), the per-provider key lookup (a key stored for a different provider is not a key for this one), `openai-compatible` correctly needing none, and the two defaults that decide whether a badge is a signal or noise: **git unknown reads as installed** (it's answered by a process spawn, so a badge for the first 200ms of every launch would fire on every clean install), and a wholly missing input reading as unconfigured rather than throwing. |
| `certPolicy.test.js` | 16 tests for the companion certificate decision (`src/main/api/certPolicy.ts`). This is what stands between a hostile network and every credential the user owns — a companion request carries the bearer key, and `GET /settings` returns the decrypted secret store — and it shipped once as "if the certificate is invalid, trust it anyway". Covers: a publicly-trusted chain deferring to Chromium (so a Let's Encrypt renewal never prompts), accept ONLY on an exact fingerprint match, a different fingerprint asking, **nothing-approved-yet asking** (the pinned regression: a 30s window used to adopt an unknown fingerprint automatically, deciding first approval without ever showing the user a value), empty fingerprints never comparing equal into an accept, `toDisplayFingerprint` rendering in openssl's notation so the app's value can be compared against `shockwave-fingerprint` on the server, and `pendingApplies` host/TTL filtering — one slot written by any request, so without the host filter a URL change could offer the previous server's certificate for approval. |
| `companionUrl.test.js` | 11 tests on what a companion URL may be (`src/main/api/urlPolicy.ts`) — the sibling of `certPolicy.test.js`, covering the case that policy can't reach. Over `https` the certificate decision says who we're talking to; over plain `http` there is no certificate at all, so the bearer key and the whole decrypted secret store `GET /settings` returns with it cross the wire readable, and no fingerprint approved afterwards undoes it. `https` anywhere, `http` to **loopback** — the web platform's own set (W3C secure-contexts), so the exemption is a definition rather than a guess about what looks local. Pins every spelling a person actually types (`localhost` and `api.localhost`, a trailing-dot FQDN, all of `127.0.0.0/8`, `[::1]` and its uncompressed form, `0.0.0.0`) and, separately, that `0x7f000001` / `2130706433` / `127.1` are exempt **because the URL parser normalizes them to `127.0.0.1`** — worth pinning because the instinct on seeing those in a test is to add a rule blocking them, which would block a legitimate loopback URL. The refusals are the other half: a private range or an mDNS `.local` name is a network (a LAN is exactly where someone else is listening, and it doesn't need the exemption — a self-signed cert the app pins is a working https deployment), a routable IPv6 address is not `[::1]`, and `localhost.evil.com` / `mylocalhost` / `127.0.0.1.evil.com` get nothing, since the `.localhost` rule is a suffix over a reserved tree and everything else is exact — never a substring test. Also pins the two questions answering differently on empty input — clearing the URL box is not a problem to report, but the transport still refuses to send to it — and that the refusal message names the fix, since it is shown to the user verbatim. |
| `gitRemote.test.js` | 5 tests for the companion's remote URL (`api/src/gitRemote.ts`). The PAT used to be embedded in it, and both `git clone` and `git remote set-url` persist the URL into `<dir>/.git/config` — which is the coding agent's own working directory, so `git remote -v` handed the agent a token with write access to every repo it covered. Asserts the URL carries no credentials and has no credential parameter at all, plus `hasEmbeddedCredentials` catching the shape that shipped and not false-positiving on an `@` outside the authority. |
| `gitGuards.test.js` | 8 tests on the guards that let a PAT-carrying git call run inside a working copy the coding agent controls (`guards()` in `api/src/git.ts`, `guardArgs()` in `src/main/sync.ts`). **Tested against REAL git, not by asserting on argv** — the claim is not "we pass these flags" but "git does not execute the agent's code while holding the token", and only git can settle that; a flag a git version ignores is worthless. Each test plants the attack and runs an actual push against a local bare repo. Covers: the unguarded `pre-push` hook stealing the token (the bug, pinned so the guards can be shown to fix something real), the same hook blocked by `core.hooksPath` + `--no-verify`, a `credential.helper` planted in `.git/config` never running, nothing being placeable where `core.hooksPath` points (`/dev/null` is not a directory — the empty-directory version was only empty until the agent filled it), the helper still answering for github.com (so a scoping typo fails here instead of breaking sync silently), the helper staying **silent for every other host** (`url.<base>.insteadOf` can redirect the push and no `-c` can clear it, so host-scoping is what keeps the token home), a hook surviving `reset --hard` + `clean -fd` (why the guard, not cleanup, is the fix), and a normal push still working. The mirrored `guards()` helper is deliberately one copy so drift fails a test rather than quietly stopping coverage. |
| `credentials.test.js` | 14 tests on the credential boundary (`agent-core/credentials.ts`) — the ONE declaration of which settings fields are credentials, and the path helpers its consumers share. It used to be written out three times (the companion deciding what to encrypt, main deciding what to strip, the renderer deciding what not to send back) and a mismatch is not cosmetic: miss a field in the strip and it leaks to the screen, miss it in the send guard and editing a sync interval wipes your GitHub token. Pins the list **by name** (so removing one is a deliberate act with a failing test), flag uniqueness, the OAuth-owned pair, that the companion's patterns match real keys and nothing else, and the helpers — `getPath`/`deletePath`/`setPathCopy` not mutating their input, `isSet` treating `''` as unset, and `isDeletableCredential` refusing non-credentials, junk paths, and the wildcard map itself (only its leaves). |
| `dailyNote.test.js` | 17 tests on daily-note naming (`agent-core/dailyNote.ts`) — the rules the app's calendar button and the agent's `daily_note` tool both resolve through. Worth pinning because the failure is silent: naming that drifts between the two doesn't throw, it quietly creates a second note beside the user's real one. Covers every shipped preset formatting and round-tripping back through the strict parse, slashes in the format becoming subfolders (and the `''`/`'/'` folder meaning the workspace root), and the two rules that exist because they were got wrong: **`formatDailyNote` takes a calendar date and so has no timezone to get wrong** (asserted by formatting the same date under UTC+14 and UTC−11), and **`basenameIdentifiesDate`** gating the workspace-wide lookup, since a `YYYY/MM/DD` format leaves the basename a bare day number and searching for `01` answers August 1st with July's note. Plus `todayISO` answering in the zone it's given and surviving an unset or invalid one — it's an optional setting, and a bad string in it must not brick the calendar button. |
| `spokenText.test.js` | 22 tests on the read-aloud rules (`agent-core/spokenText.ts`) — the pass that turns a reply into a script a speech engine can say. The whole reason it is find-and-replace rather than a model is the promise that it cannot drop a fact, and a promise like that is worth exactly as much as the test pinning it, so the facts-survive cases are the point of the file and the prettiness cases are the supporting cast: every number survives, a bare URL keeps every identifying character (we drop only the scheme, where hermes deletes the URL outright), link text is kept, inline code keeps its text. Also pins the divergences that came out of real breakage — a dot before a lowercase letter is left alone (hermes' rule turns `renameOps.ts` into "renameOps. ts" and `example.com/a?c=1` into "example. com/a? c=1"), and a table divider row leaves no dashes behind. The one deliberate removal is a fenced code block, and that is pinned too, so re-adding it would be a deliberate act. |
| `voiceReply.test.js` | 6 tests on the reply mode (`agent-core/voiceReply.ts`) — pure policy, no disk, since the value lives on the companion as one settings row. The three modes are NOT a scale, and every delivery path asks the same two questions of them: does this send the words, does this speak. `sendsText`/`speaks` are the one place that mapping lives and getting either backwards is silent — a voice note with no text, or text with no voice, and nothing errors. Also pins that an unrecognized value reads as the default (plain text row, two writers) while an unrecognized *argument* is REJECTED, so `/voice bogus` says so rather than looking like it worked and quietly turning speaking off. The sixth pins the storage path **by name** (`speech.telegramReply`) and that it is not a credential — six places have to agree on that string with none able to see the others, and a mode filed as a credential would be stripped before the renderer and reach the settings page as undefined forever. |
| `voiceProviders.test.js` | 12 tests on the speech-vendor table (`agent-core/voiceProviders.ts`). The matrix is **not square** — AssemblyAI transcribes and cannot synthesize — so "the voice provider" is not one choice, and a single dropdown driving both directions would either hide a vendor already in use or quietly speak against an account that doesn't exist. Pins the two lists being different, the vendors by name, and the one microphone fact that breaks quietly: **only ElevenLabs mints a single-use token**, where the other two are reusable for 60s, so a constant cache window fails the SECOND click. Also pins that one key per vendor serves both directions, that an empty key reads as no key, and that speaking needs a vendor AND a key AND a vendor that can speak. |
| `speak.test.js` | 9 tests on text to speech (`agent-core/speak.ts`) — the parts checkable without a vendor. The container sniffer exists because vendors ignore the format you ask for, and its failure is invisible: you get a `.ogg` file Telegram refuses as a voice message with an error naming neither the format nor the file (hermes hit exactly that and added the same check). Pins Ogg, the containers a vendor might send instead, and that MP3 and ADTS AAC — which share a sync word — are still told apart. The other half is the promise that **speaking never costs the user their reply**: every path that can fail before the request returns `null` rather than throwing, and those paths are enumerated here. |
| `transcriptFormat.test.js` | 8 tests on transcript formatting (`agent-core/transcriptFormat.ts`). The format IS the deliverable: a subtitle file with the wrong timestamp shape is silently rejected by every player that opens it, and the two formats differ by one character — SRT separates the fraction with a comma, WebVTT with a dot. Pins both shapes, that hours are carried (a cue reading `00:01:05` for the sixty-fifth minute is silently wrong, and a long recording is exactly when a transcript is worth having), that prose mode joins a speaker's run into a paragraph rather than leaving subtitle-length fragments, and that empty input yields an empty file rather than a malformed one. This is also the half of transcription with no network in it — which is the point of the seam, since swapping the speech engine cannot change any of it. |
| `mediaTags.test.js` | 18 tests on the file-delivery parser (`agent-core/mediaTags.ts`) — what decides that a path the agent typed becomes a file in the user's Telegram. Every rule exists because getting it wrong sends the wrong file or one nobody asked for: a path inside a code fence is being SHOWN, so matching it answers "how do I link an image?" by mailing the user that image; a path inside a JSON string value is stored tool output holding an earlier reply, so matching it re-sends the same file every turn after. Pins that the two passes are **chained** (a tagged path is cut from the text before the bare-path scan runs — that chaining IS the dedup), that a bare path is delivered only when the file really exists, that unknown extensions are left in the text rather than swallowed, and the containment rule: only files inside an allowed folder, with **symlinks resolved first**, since the agent can write a link inside a folder it is allowed to use. |
| `messageImages.test.js` | 8 tests on `agent-core/messageImages.ts` — the filter that carries a user's images from pi's message into the stored row. It is the whole reason chat images render, and its failure mode is **silence**: `message.content` is text-only by design (base64 in the column that feeds the search tsvector would bury every real match), so if this returns nothing, no attachment row is written, no request fails, and nothing logs — pictures simply stop appearing. That is the exact bug the attachment pipeline was built to fix, and it went unnoticed for as long as it did precisely because nothing complained. Pins that images survive alongside text, that an album keeps every image in order rather than collapsing to one, that a plain-text message yields `undefined` rather than an empty array on every row of every turn, that a zero-length part is dropped (it would render as a permanently broken image) while a missing mime type falls back instead of losing the picture, and that junk in the content array can't throw. |
| `speechChunks.test.js` | 12 tests on splitting a script into the pieces it is spoken in (`agent-core/speechChunks.ts`). Two promises that pull against each other, which is the whole reason it is a separate pure module: **nothing is lost** — every character comes back in order, and the vendor's input limit is respected as a hard cap rather than by cutting, which is how the tail of a long answer used to be silently never spoken — and **pieces are whole**, so a break lands on a sentence end even when that means overshooting the budget, because a clip that stops mid-word is worse than one that runs long. Also pins the shape that makes it worth doing (the first piece is the short one and they grow), the two runt guards that stop it producing silly bubbles (a short opening sentence isn't its own voice note; a two-second tail is folded into the piece before), and that text with no punctuation at all still survives whole. Lengths are never asserted exactly — how long a piece takes to say isn't knowable until it is made, so this works in estimates by design. |
| `waitingBubble.test.js` | 8 tests on the "..." bubble (`api/src/telegram/waitingBubble.ts`) — the message posted before a turn has anything to show, and the one a 🤬 reaction posts while the audio is being made. The property under test is **exclusive ownership**, which is the entire reason this is a separate piece: the bubble animates its message until somebody takes it, and must never write again afterwards. Its failure mode is a dot landing on top of the first words of a reply — visible, intermittent, and not reproducible on demand, which is exactly the kind of thing a test has to hold rather than a reader. Pins that a claim hands over the id and silences the animation, that a second claim gets nothing, that the dots actually grow, that `remove` deletes and then refuses to hand anything over, that it goes up as a plain message and never a reply (it stands in for an answer that hasn't arrived — pointing at something is the answer's job), and that a bubble which failed to post is simply absent (no slot, and nothing to delete) rather than an error the caller has to handle. The client is injected, so nothing here touches the network. |
| `telegramEntities.test.js` | 15 tests on `api/src/telegram/markdownEntities.ts` — the agent's markdown turned into Telegram's `entities` (plain text + offset/length spans). Tested because the alternative routes fail LOUDLY in the wrong direction: `parse_mode` encodes formatting into the string, so one unescaped `.` is a 400 and the message is never delivered. Entities can only be wrong by bolding the wrong characters — silent, and a test is the only thing that catches it. Pins that markers leave the text and the span covers the right words, that nesting emits two spans rather than flattening, that a fenced block keeps its contents verbatim, and the three properties that are the reason for the design: prose full of MarkdownV2 specials (`$5.00 (approx.) — item #3 [note] =`) passes through byte-for-byte, a half-typed `**bo` renders as itself instead of throwing (this is what the streaming path sends every ~1.3s, and what hermes cannot format at all), and **an astral emoji counts as 2** — Telegram measures UTF-16 code units and so does a JS string index, so "iterate code points instead" looks like a correctness fix and is the one change that would silently break every offset after an emoji. Chunking gets its own set: a span straddling a cut becomes one span per chunk, spans outside a window are dropped rather than zero-lengthed (Telegram rejects those), and after a real split every one of 40 bold words still covers exactly the word it started as — an off-by-one in the rebase shows up there as `mark1` reading `*mark1`. |
| `attachmentPolicy.test.js` | 21 tests on inbound attachments (`agent-core/attachmentPolicy.ts`) — covering **both hosts**, since the companion (Telegram) and the desktop (chat composer) run the one module. A Telegram photo arrives with no filename and no mime type, so the type comes from the magic bytes — and that is not cosmetic: providers reject a declared media type that doesn't match the actual bytes, so one wrong guess turns "look at this photo" into a failed turn. That bug was in this code (every native photo went out as `application/octet-stream`) and this file is why it isn't now. Also pins that a declared type is overruled by the bytes, that an HTML error page named `.jpg` is refused rather than sent to a vision model, that a filename can't climb out of the staging dir, that inlining is gated on the **extension** not on whether the bytes decode (PDFs start with decodable ASCII), and the notes — act-don't-ask for documents, and saying plainly when the model can't see an image.. The last seven cover `writeAttachment`, the write both hosts share, against real temp directories: a **tarball is saved and pointed at rather than refused** (the desktop answered that one "unsupported format" while its own system prompt promised the agent that files arrive in its scratch pad), a text file is BOTH saved and inlined, one over the inline cap degrades to a pointer instead of becoming the prompt, an image gets a path as well as its pixels, two files of the same name don't overwrite each other, a crafted filename can't escape the directory, and the ONE refusal is bytes claiming to be an image and clearly not. |
| `chatNotice.test.js` | 7 tests on `agent-core/chatNotice.ts` — how stale the chat you're returning to has to be before Telegram lists what moved while you were away, and how many it lists. Tested because **two builds resolve it**: the companion decides whether to send the notice, the desktop's Telegram page renders the numbers in effect, and a disagreement between them shows 24 hours on screen while the bot waits 48 — with nothing anywhere to report it. Pins the defaults by value, that each field falls back independently (settings rows are written one leaf at a time, so a partial object is the normal case), that `enabled: false` is off while `afterHours: 0` is every-resumed-chat, that out-of-range numbers clamp rather than disable the feature, and that a *string* `'24'` falls back instead of coercing — that one would not throw, it would silently never fire. |
| `settingsStrip.test.js` | 5 tests on the main→renderer credential strip (`src/main/settingsStrip.ts`). The pair to `rendererSettingsDoor.test.js`: that one pins *which function* an IPC handler may call, this one pins *what that function produces*. It is a separate pure module precisely so it can be tested — `settingsStore.ts` imports electron, so `node --test` cannot load it. Pins that a stored token comes back as a presence flag and never as a value, and that fixed-path settings credentials get their flag beside where the value was. The other three are all one rule, the one that was got wrong: **a flag never conjures the object that would have held it.** `setPathCopy` builds missing parents, so writing `oauth.hasClientSecret` gave every static-token agent secret an empty `oauth: {}` — and the renderer classifies by `!!s.oauth`, so every pasted token rendered as an OAuth connection, with a Reconnect button that could only fail and no way to reach the dialog that would let you paste the key. Nested flags now apply only when their container already exists; root-level ones (`token` → `hasToken`) always do, there being nothing to invent. |
| `rendererSettingsDoor.test.js` | 4 tests enforcing the one rule that keeps credentials off the screen: **an IPC handler may only return the stripped settings read.** `readSettings`/`readSettingsSafe` carry live credentials for main's own use (running the agent, pushing to git, minting the voice token); `readSettingsForRenderer` is the one that strips. Nothing in the language stops a future handler returning the wrong one, and the leak would be silent — the app would work perfectly while handing over every key. A source scan of `main.ts` (coarse by design: can't be fooled by a refactor, needs no Electron) checks that the scan still finds handlers at all, that `settings:read` returns the stripped read, that no handler returns a settings object still carrying credentials, and that the `settings:changed` push strips too. Verified by introducing the leak deliberately and watching it fail. |
| `hostArtifacts.test.js` | 7 tests on the host artifacts — everything the companion puts on the server *outside* its containers: the runtime files in the install dir, the one command on PATH, and the symlink pointing at it. **This file is also a worked example of pinning the wrong copy of something.** It used to check that `install.sh`'s fetch list and `apply.sh`'s `FILES` agreed, and they always did — while the copy that actually decides an upgrade is neither of them. It is the list inside whatever `apply.sh` a given *server* is holding, frozen at the release that box last installed. So deleting `api/traefik/gen-router.sh` in v1.0.85 removed it from both lists here, kept the suite green, and jammed every box still on v1.0.84 permanently: their `apply.sh` still named it, the fetch 404'd, and the fetch is upstream of the step that would have replaced `apply.sh`. The list is gone now — the host files ship in the image (`/host-files`) and both paths `docker cp` them out — so what is pinned is that property: the image delivers every file the host needs, neither script carries a runtime-file list or fetches one over the network, `apply.sh` **moves** files into place rather than copying over them (it is replacing itself while the shell reads it) with its staging dir inside `$COMPANION_DIR` so the `mv` is a rename and not a cross-device copy, `install.sh` creates exactly ONE symlink and it points at the dispatcher, `apply.sh` creates none (it cannot — `watch.sh` mounts only the install dir into the helper, which is what makes the single stable symlink target load-bearing), and the dispatcher ships executable in the repo, which is now what carries its mode through `COPY` → `docker cp` to the host. |
| `checkoutPool.test.js` | 6 tests on the warm-checkout queue's claim (`api/src/checkoutPool.ts`). The queue has no state field — a folder's **location** is its state (`pool/setup` unfinished, `pool/ready` usable, `work/<chatId>` claimed) and every move is a rename — so nothing here is enforced by a type and all of it has to be checked. Runs the REAL function, esbuild-bundled the way the server bundles it, not a mirror. Pins that a matching folder is claimed and leaves `ready/`, that an empty queue returns false rather than a broken directory (the caller's fallback is a normal clone, so false must mean exactly "nothing was waiting"), that repo AND branch are both part of a slot's identity, that a half-cloned folder in `setup/` is unreachable rather than merely undesirable, and the one that matters most: two chats claiming simultaneously get **different** folders — the rename being atomic is what replaces a lock, and if it ever fails two agents are sharing a checkout. |
| `checkoutReuse.test.js` | 8 tests on reusing a run's checkout (`prepareCheckout` in `api/src/git.ts`), against **real git** for the same reason `gitGuards.test.js` is — the claim is about what git does to a working tree, not about which argv we assemble. The bug pinned: reuse used to `reset --hard origin/<branch>` + `clean -fd` to guarantee a pristine start, which deleted work that hadn't reached GitHub yet. A turn's changes are only safe once pushed and the push happens *after* the agent replies, so a second Telegram message in that window started a run whose first act wiped the previous turn's work — silently, the checkout being the only copy. Covers the three things that must survive (uncommitted edits to a tracked file, untracked files the agent created, a commit never pushed), that a clean checkout still catches up so desktop pushes are picked up, and that unpushed work survives even when the remote also moved. **The fixture clones SHALLOW**, and that is the point: it used to clone full and fetch without `--depth`, while production cloned shallow and fetched *with* it — so these tests passed for the entire life of a bug where every reused checkout silently stopped catching up and every push after an outside change was rejected. Three tests pin it directly: that `--depth=1` on a fetch severs history at all (if that ever starts passing, git changed and `prepareCheckout` can be simplified), that a checkout damaged by the older release repairs itself via `--unshallow` and catches up, and that the repair doesn't cost an unpushed commit. The mirrored reuse sequence is one function so drift fails a test rather than quietly stopping coverage. |
| `fuzzyMatch.test.js` | 24 tests on the patch engine (`agent-core/fuzzyMatch.ts`), ported from hermes' `tools/fuzzy_match.py`. The chain is deliberately forgiving on the MATCH side, so every guard on the WRITE side is what stops that forgiveness corrupting the file — a strategy that matched loosely and then wrote `new_string` verbatim is worse than one that didn't match, because the patch silently succeeds and the damage surfaces later in a skill nobody re-reads. **Four tests are marked FIX and pinned by name**, because the obvious way to build this file is to copy knack's TypeScript port and that copy reintroduces every one: the exact-match cursor advancing by one char instead of the pattern length (overlapping spans corrupt the file under `replace_all`), no Unicode preservation on replacement (a replacement flattens the file's em-dashes and smart quotes), a UNICODE_MAP missing the minus sign and the Zs space family (typographic files fall through to the fuzziest strategy), and an ungated trailing-space expansion (a match ending on a word swallows the following space). Plus the three write-side guards and the did-you-mean gating. |
| `manageSkill.test.js` | 26 tests on writing skills (`agent-core/manageSkill.ts` + `skillValidate.ts`). Two of the rules protect the USER's files and both fail silently if they regress. Containment keeps writes inside the agent's own directory — break it and the agent edits skills the user uploaded. The create-collision check refuses a name held in ANY root, even one it can't write to: **pi keeps exactly one skill per name and the `.agents` copy WINS**, logging a collision diagnostic nothing surfaces, so without it the agent shadows a user's skill without touching the file. (Verified against pi directly before the test was written.) The third is read-before-write — an unattended agent must not rewrite content it only inferred from a transcript. Also covers the symlink escape, traversal paths, and that `delete` is not an action. |
| `skillTool.test.js` | 13 tests on the review run's tool set (`agent-core/defaults/tools.ts`) and the two tools it gets built (`agent-core/skillTool.ts`). The review list is EXPLICIT, not the catalog minus exclusions, and that direction is the safety property — a tool added next month must not arrive in the one run nobody watches, which `daily_note` proved while this was being designed. `write`/`edit`/`bash` being absent is what makes the guards real rather than decorative. The `read` override is the other half: pi has no skill-loading tool of ours to hang the read-before-write mark on (skills load with the plain `read` builtin), so the override IS the mechanism, and if it stops delegating or stops recording the gate silently passes nothing. Pins that a failed read records nothing (pi THROWS on a missing file rather than returning an error result) and that two runs don't share what each other read. |
| `reviewPrompt.test.js` | 14 tests on the review instruction (`agent-core/defaults/reviewPrompt.ts`). The prompt IS the feature — everything else only decides that a run happens and what it may touch; what it writes down is decided by this text, and it is hermes' text arrived at over a long tail of fixes. The failure guarded against is a **half-translation**: someone edits a line, or re-ports from a different source, and the result reads fine while having quietly lost the bias to action or one of the do-NOT-capture rules. So it asserts the load-bearing clauses verbatim (including the fifth do-NOT-capture bullet, "Unresolved failures", whose absence is the tell that someone re-ported from knack's older copy) AND that no hermes-only name survived — `skill_view`, `skills_list`, `curator`, `execute_code`. |
| `memoryStore.test.js` | 22 tests on the memory store (`agent-core/memoryStore.ts`). Everything about memory that can go quietly wrong lives there: the prompt and the trigger only decide that a write is attempted, this decides whether it is correct. Covers the `§` format (a `§` *inside* a line is content — only one alone on its own line separates), the budget counted on the serialized form so the number shown to the agent is the number enforced, creation on first write, the all-or-nothing batch, and substring matching including the ambiguous case. **Two of these exist because the naive version was measured failing**: concurrent adds lose an entry outright without the per-path lock (the desktop runs several chats against ONE workspace folder), and a file that exists but cannot be read must never be treated as empty — reading it as `[]` and saving would rewrite the whole file from a view that was not the real one. A directory where the file should be is the cheapest way to make a read genuinely fail. Also pins the symlink refusal, which matters because a background run holds no `write` and no `bash`, so a planted symlink is the one way such a run could write outside the workspace. |
| `memoryPrompt.test.js` | 11 tests on the memory instruction + the `memory` tool description, plus the tool layer between the store and pi (argument shapes that arrive from a model rather than from our own code: a **null `target`**, which strict providers send instead of omitting the field, and a `replace` with no `old_text`, which cannot be schema-required without a combinator some providers reject — both must return something the model can act on rather than a dead end). Same reasoning as `reviewPrompt.test.js` — the text IS the feature. The instruction is asserted in FULL rather than by distinctive clause, because unlike the skill prompt it took **zero substitutions**, so there is no adaptation for a verbatim copy to fight with; if hermes changes it, this fails and the new text gets read before it is taken. It also pins the **asymmetry between the two processes**: the skill prompt says "Be ACTIVE", the memory prompt deliberately does not, and that is the reason they are not one pass — pointing the skills wording at a chat that only talked is how a skill about nothing gets written. |
| `helperPrompt.test.js` | 13 tests on the helper prompt (`agent-core/defaults/helper.ts`), pinning one rule: **naming a tool the run does not have is worse than saying nothing.** The file already applied that to `send_message`, but two places named tools unconditionally — the tool section closed with "Reach for `bash` …" and the guidelines opened with a rule about `get_agent_secret` — and both appeared in a review run that had neither, immediately after the line "This is the complete set — there are no others." Anyone reading that prompt concludes the run has bash; so did a reviewer of the feature. Also pins the inverse, that the bash-vs-search advice survives everywhere bash exists, since removing it globally would be the opposite mistake. The **memory run** made the rule sharper still — it holds exactly one tool, so it is the narrowest run in the app, and it exposed two more sections that named tools unconditionally: `LINK_GRAPH` (it hands over a `grep` pattern to run) and `SKILLS` (authoring guidance for a run that cannot author). Both are gated now, and the generalisation is pinned: a section that teaches a tool is gone wherever that tool is. |
| `chatSources.test.js` | 2 tests that the chat-history source filter knows every kind of chat that exists. Written as a **rule, not a list** — it scans `api/src` for the `source: '<x>'` literals the run entry points actually write and checks each has an entry in `CHAT_SOURCES` and a label. A missing source is not a missing checkbox: those chats stay visible while the filter is `null` (the default, meaning all), so nothing looks wrong, and the moment the user narrows it once they become invisible with no control to turn them back on — while `allSelected` computes true over the known list, so the menu says everything is shown. That is a bug you find by losing history. `memory` was added with the memory pass and this is what would have caught forgetting it. The scan is deliberately bounded to `api/src`: every source but `desktop` is written on the companion (it is what runs a chat no person started), `desktop` is never a literal at all (`agent-core` stores `source ?? 'desktop'`), and widening to `agent-core` picks up `source: 'builtin'` from the skill scanner, which is a different kind of source entirely. |
| `backgroundSources.test.js` | 5 tests that **a background run can never examine another background run**. The failure it guards is self-sustaining rather than one-off: a review run makes tool calls and holds a conversation like any chat, so left eligible it crosses its own threshold, reviews itself, and the review of *that* reviews itself — an unattended model run every tick, each landing a commit, and nothing says so. Read as **source**, because `api/src/store.ts` pulls in drizzle + pg and this suite runs with no install; what is asserted is the rule, never the SQL text, so a rewritten query still passes as long as it keeps the guard. Four claims: every `source:` literal in `backgroundRun.ts` appears in `BACKGROUND_SOURCES` (a new background kind is covered the day it's added), each of those is a real `CHAT_SOURCES` value (a typo'd literal excludes nothing and looks identical to a working guard), **both** sweep queries filter on the shared `notBackgroundChat` fragment and that fragment derives from the list, and `cloneChatForBackground` still refuses a background source — the choke point every run passes through however it was picked. The two due-queries are deliberate near-copies of each other, which is exactly how a line survives in one and is lost from the other. |
| `scratchSweep.test.js` | 8 tests on the TTL sweep (`agent-core/scratchSweep.ts`) — the one piece of the app whose whole job is deleting the user's files, run unattended in two processes (desktop boot, companion hourly) off one setting. Real directories with mtimes backdated via `fs.utimes`, because the claim is about what the filesystem reports. Pins the feature — **a pinned chat is never swept, whatever its age** — and its inverse, that unpinning releases the dir on the next sweep, since otherwise pinning would be a one-way door and disk would only ever grow. Plus per-base counts in the order given (the companion passes three bases and logs them separately), a base that doesn't exist yet (a fresh install sweeps before the agent has ever run, and throwing there takes out the boot path), an entry vanishing between readdir and stat (a chat delete removes its dir directly, so that race is normal), and the TTL fallback: unset arrives as `undefined` from a companion that stores no defaults, and `0`/junk must land on `DEFAULT_SCRATCH_TTL_DAYS` rather than on "delete everything now". |
| `sharedDeps.test.js` | 3 tests pinning that the two `package.json` files agree. `agent-core/` is ONE source tree compiled into TWO artifacts — the Electron bundle and the companion's Docker image — and each build resolves dependencies from its own manifest, so the same source can end up running against two different copies of a library with nothing visible at build time. Written as a **rule, not a list** (any package named in both files must carry the same version), so the next shared dependency is covered the day it's added rather than needing an assertion nobody remembers to write. Plus: the two pi packages must be pinned **exactly**, since a caret defeats the first check entirely — both files can say `^0.80.5`, match, and still install different versions on different days. The third test guards the guard: it asserts the shared set is non-empty, because a refactor that moved everything out of one manifest would otherwise leave the loop iterating over nothing and reporting green. Verified by injecting a skew and an un-pin and watching both fail. |

## What's NOT covered by automated tests

The Electron UI itself. Tabs, drag-and-drop in the file tree, title-input commit, right-click menus, editor decorations, the chat sidebar (skills, secrets, attachments, voice), image paste/drop, quick search, bookmarks, daily notes, voice transcription, theme switching — these need manual verification with `npm run dev`.

Most of the **companion server** (`api/**` — Express + Postgres, the server-side agent for Telegram + cron, and all settings/secrets/chats storage). `api/` has no test files and no `test` script of its own; it's exercised by running it (Docker) against the desktop. It does now have **`npm run typecheck`** (`api/tsconfig.json`, covering `api/src/**` + `agent-core`), which is not test coverage but is the difference between a wrong annotation shipping and not: esbuild bundles that tree without checking it, so before that config existed nothing had ever type-checked the companion at all. Turning it on immediately found `webhook.ts` handing the raw `pg.Pool` type to functions that take the drizzle instance — it worked only because the annotation was wrong, which is why `db.ts` now exports `PgPool` and `Db` instead of `DB` and `Db`. The exceptions are the pieces that hold a credential, which are covered from here: `gitRemote.test.js` (the remote URL carries none), `gitGuards.test.js` (git won't execute the agent's code while holding the PAT — covers `api/src/git.ts`'s `guards()` and `src/main/sync.ts`'s `guardArgs()` together, since they're the same policy twice), and `credentials.test.js` (the declaration `api/src/keys.ts` derives from) — plus `attachmentPolicy.test.js`, which decides what a file the user sent IS, and `telegramEntities.test.js`, which decides what the agent's reply LOOKS like (pure, so it tests from here; the send that carries the result does not). Routes, storage, encryption, the scheduler, and the Telegram handlers have no automated coverage. **Chat attachments are covered at their one piece of logic and nowhere else**: `messageImages.test.js` pins what survives pi's message, but the insert (`store.appendMessages`), the read (`getMessages`), `GET /attachment/:id`, and the desktop's `app://attachment/` proxy all need a live Postgres and a running companion, so they're exercised by using the app. **The attachment pipeline is covered either side of its I/O but not through it**: `attachmentPolicy.test.js` decides the file's type, note and write (that last one against real directories, so it covers the desktop's `stashChatFile` and the companion's `cacheAttachment` at once) and `mediaTags.test.js` decides what gets sent back, but nothing exercises `webhook.ts`'s download-and-compose or `stream.ts`'s deliver-after-reply — those need a Telegram bot and a running companion. On the desktop side the same gap is `agent:stashFiles` and the composer's ingest: reading a `File`, choosing bytes-vs-path, and the send that composes them need a window, so they're verified by using the app.