Repository navigation
Releases and Workflows
-
Log Scrape: Scrape build output from bun runner (matching
exit 1conditions). - Error Isolation: Target the root failure point (e.g., missing package imports, type mismatch, or invalid asset clipping).
-
Patch Generation: Formulate a runnable bun terminal command (e.g.,
bun add @superdesign/svg-geometry@latest && bun run build). - Execution in Kabmo: The user or agent triggers execution directly in the right sidebar panel.
- Use the CSS variable system defined in
src/client/tailwind.css(var(--theme-ink),var(--theme-paper), etc.) and standard Tailwind classes mapped to them (bg-paper,text-ink,border-ink/20). - The application supports multiple themes (e.g., E-Ink Paper Monochrome, One Dark Pro Soft). DO NOT hardcode raw hex colors like
#141310or#faf8f3in component files. - Semantic states are expressed purely through these theme variables.
- Every theme write goes through
applyDocumentTheme(src/client/hooks/ui/theme.ts): it sets<html data-theme>and dispatchesomp:theme-changed. Writingdocument.documentElement.dataset.themedirectly leaves runtime consumers that cannot see CSS (the mermaid hydrator repaints diagrams per theme) on the previous palette. - The only allowable chroma (outside of dark theme) is the signal red variable
var(--theme-error)(text-error,bg-error) reserved for failures and error messages. Syntax highlighting is an explicit, user-approved exception: it is provided by Shiki with the dual-theme pairone-light(light themes) +one-dark-pro(dark themes). Token colors arrive as--shiki-light/--shiki-darkCSS variables on.shikispans — consume them insrc/client/tailwind.cssunder[data-theme], never hardcode token hex, and never reintroduce--syntax-*variables or.token.*classes.
-
NEVER edit
CHANGELOG.mdduring normal work — not for a feature, a fix, a refactor, a typo, or a version-less "unreleased" note. A task ends at code plus the gates in rule 8; the changelog is not part of it. -
CHANGELOG.mdis written only when cutting a release, and releases are cut by.github/workflows/release.ymlon every push tomain— so since0.6.0the file is written by the pipeline, never by hand:release.config.mjsderives each## [x.y.z] — YYYY-MM-DDsection from the Conventional Commits since the last tag, above the previous release (newest first), carrying the[Keep a Changelog](https://keepachangelog.com/en/1.1.0/)categories that apply (### Added,### Changed,### Fixed,### Removed). The section order, the header and the leading### BREAKING CHANGESgroup are that config'scommitTypesandwriterOpts; a new category means editing both. - New sections link their compare range inline (
## [0.6.0](…/compare/v0.5.0...v0.6.0) — …) and their bullets are commit subjects, not the hand-written prose the sections before0.6.0use, so the[x.y.z]:reference block at the file's tail stops at the last hand-written release. Never add to, reword or reformat a section that already shipped — it describes what shipped, not what a later change adjusted. - Write entries as released behavior: a bullet is the commit subject, so the subject carries the changelog — name the behavior that changed, never a restatement of the diff. A type marked
hiddeninrelease.config.mjs(chore,style,test,build,ci) appears nowhere, and a type carryingrelease: falseinrelease/release-rules.jscannot cut a version on its own — not even with a!on it, because the rules there shadow the analyzer's own{ breaking: true }fallback for every type this repository uses. - A bullet credits its author —
… ([c148bc5](…)) (thanks [@octocat](https://github.com/octocat))— unless that author is the repository owner, whose own commits carry the bulk of every release.release/contributors.jsresolves the handle offline from GitHub privacy addresses (NNN+login@users.noreply.github.com) and asks the API about every other author, which is why the release job'sGITHUB_TOKENis what credits a contributor who commits with a real mailbox; bots ([bot]logins,type: 'Bot') and unverified addresses get nothing, and a failed lookup never fails the release.
Every commit uses Conventional Commits — pick the type from what the diff actually does to observable behavior, not from how big it is:
-
feat— new user-visible behavior: a feature, endpoint, setting option, or capability that did not exist before. A change that only reorganizes internals while the UI/API output stays identical is NOT a feat. -
fix— corrects existing behavior that was wrong: a bug, regression, wrong result, crash, or broken edge case. There must be a demonstrable "before was wrong" state; a behavior change that is merely a decision is not a fix. -
refactor— restructures code with zero external behavior change: renames, file moves/extractions, deduplication, type tightening, performance work with no visible effect. -
perf— the primary intent is a measurable performance improvement, with behavior unchanged. -
style— formatting/whitespace/import order only; no logic change. (hiddeninrelease.config.mjs.) -
test— adds or repairs tests only; no production code change. (hidden.) -
build— toolchain, dependencies, build scripts (package.json,bunfig.toml,scripts/build-client.ts,bun.lock). (hidden.) -
ci— pipeline config only (.github/workflows/,release.config.mjs). (hidden.) -
chore— maintenance that fits none of the above (ignore files, secondary scripts). (hidden.) -
docs— documentation only (README, AGENTS.md, comments). -
BREAKING CHANGE— append!and a footer when a change requires callers/users to act: removed/renamed API, route, setting, or a changed contract. The changelog's### BREAKING CHANGESgroup comes from this footer. Two limits are enforced byrelease/release-rules.js, not by convention:!releases a major version only onfeat,feature,fix,perfandrefactor— onchore,docs,ciand the rest it releases nothing at all, so a breaking change to the build or the pipeline belongs in the type that carries it — and the footer is read case-sensitively, so it is writtenBREAKING CHANGE: …(orBREAKING-CHANGE:) at the start of a line. A lowercasebreaking-changemention in prose is not a footer; before the pattern was pinned, one such line in adocsbody cut a major release by itself. | Mixed change in one commit: split into separate commits when the files are separable; if not, use the dominant type and note the rest in the body. The subject names the behavior that changed (it becomes a changelog bullet verbatim), the body explains the why/how — never restate the diff.release/bump.test.jsasserts the whole table, and.github/workflows/ci.ymlruns it (with the other three gates) on every pull request — andrelease.ymlruns the same reusable workflow on every push tomain.
-
The npm names carry the
kabmo-prefix because the org does. The scope is@kabmo-labsand every package in it is a Kabmo package, so@kabmo-labs/kabmo-sdk/@kabmo-labs/kabmo-uistate which product they belong to instead of leaving a bareplugin-sdk/uito be read as the org's generic library. The directories follow the names (packages/kabmo-sdk,packages/kabmo-ui), and so do the release tag prefixes (kabmo-sdk/v1.2.3) — a tag is the package's identity in the workflow, and a tag that disagrees with the manifest name publishes a version under a name nobody wrote down. -
Every manifest starts at
0.0.1, and a seed tag is what keeps the line there. The app, both packages and all three bundled plugins declare0.0.1. semantic-release has no option for a first version:get-next-version.jsreturns the hardcodedFIRST_RELEASE(1.0.0) whenever the branch has no tag matchingtagFormat. Verified against a throwaway repository: no tag →1.0.0; av0.0.1tag present → the nextfeatcuts0.1.0and stays on the 0.x line. So the 0.0.1 lineage begins with av0.0.1tag (andkabmo-sdk/v0.0.1,kabmo-ui/v0.0.1for the packages) on the release commit; without it the first pipeline run publishes1.0.0whilepackage.jsonsays0.0.1, andpublish.ymlrefuses that mismatch. The retired local tagsv1.0.0/plugin-sdk/v1.0.0/ui/v1.0.0point at a commit that is not an ancestor ofHEADand were never pushed — they match notagFormatin use, so they neither seed nor block anything. -
The pre-rename specifiers still resolve, and they must.
@kabmo-labs/plugin-sdkand@kabmo-labs/uiare already baked into every plugin bundle on disk, soRUNTIME_SLOT_BY_SPECIFIER(panels/shim.ts),kabmoPackageDirs(panels/link.server.ts) andrunningVersions(panels/compat.server.ts) all name them beside the new ones. Removing them would fail an installed plugin at load withCannot load … must be loaded by Kabmo, which is a rename breaking the thing the rename was for. -
The published packages are versioned from commits too — never bump them by hand. They are released by the SAME workflow as the app,
.github/workflows/release.yml, whosepackagesjob runsnode release/release-packages.mjs. The version rules, the changelog shape and the contributor credit are the app's, reused rather than restated:release/packages.mjsreadscommitTypes,parserOptsandreleaseRulesout ofrelease.config.mjs. -
Every package that releases in one run shares ONE commit, one atomic push and one tag each. semantic-release still decides —
analyzeCommits(path-scoped) andgenerateNotes, run withdryRun: true, which in semantic-release 25 runsverifyConditions/analyzeCommits/verifyRelease/generateNotesand SKIPSprepare/publish— but its git side effects are gone:@semantic-release/gitcommitted AND pushed each package on its own, core tagged that commit, and@semantic-release/githubcreated a page for it, so one decision to release both packages left two commits and two pushes.release/packages-commit.jsnow stages both manifests, both changelogs and the sharedbun.lock, commits ONCE (chore(release): kabmo-sdk/v0.1.1, kabmo-ui/v0.2.1 [skip ci]), creates both lightweight tags at that commit, and pushes the branch with its tags--atomic;createGithubReleasesthen makes one release page per tag from the notes semantic-release generated (a422 already_existsis success, so a re-run can finish the job). Two facts are load-bearing and each was measured:packageReleaseConfigmust passplugins: []EXPLICITLY — semantic-release merges the repository'srelease.config.mjsunder the options and then falls back to its DEFAULT list (npm+github) for a nil key, so omitting it ran the APP's release plugins for a package and its first dry run refused on@semantic-release/github'sverifyConditions; and the writes are explicit (writePackageRelease: the local version plugin, which also refreshesbun.lockand verifies the record, then@semantic-release/changelog's ownprepare), becausepreparedoes not run in a dry run and calling the changelog plugin is what keeps the file byte-identical.commitReleaseand the release-page call are pinned byrelease/packages.test.js(onegit add, onegit commit, both tags atHEAD, one atomic push,422tolerated, a real scratch workspace for the write), and the whole path was rehearsed end to end in a clone: both packages moving to 1.1.0 produced exactly one commit carrying both manifests, both changelogs and the lock, with both tags on it and both pushed. -
The app releases AFTER the packages, in one chained run, and the order is load-bearing. The app does not ship
packages/(see itsfileslist) — at runtime it resolves@kabmo-labs/*from its ownnode_modules, which is the versionbun.lockrecords for those workspace packages, and aworkspace:spec is substituted from the LOCK rather than the manifest. Releasing the app first therefore publishes stale pins: measured,kabmo@4.1.1on npm declares both packages at1.0.0while they are at2.0.0(and@kabmo-labs/kabmo-ui@2.0.0declared the SDK at1.0.0while the SDK was2.0.0). Thepackagesjob commits the refreshedbun.lock, and theappjobneeds: packagesand fast-forwards to that commit before it installs and releases. The workflow is four jobs:packages→packages-publish, andpackages→app→app-publish; a failed package release stops the app's, because the pin state would be unknown. -
One workflow means one concurrency group, and that is the point. A concurrency group is not a lock: it is a queue that DROPS pending members as it grows. An earlier revision split the releases across two workflows and shared one group between them so they could not race on their release commits; measured, two pushes in quick succession put four runs in the one group and GitHub cancelled the app's runs to keep the queue bounded, so the app stopped releasing entirely. With both releases in one workflow there is no second group to collide with, and each job's
git fetch origin main && git merge --ff-only FETCH_HEADcovers the intra-run ordering. -
Both release jobs fast-forward their checkout before installing, and that is not optional. semantic-release refuses to release when the local branch is behind the remote — "The local branch main is behind the remote one, therefore a new version won't be published." — and it exits 0, so the run reports success while releasing nothing. Measured on this pipeline's first real run: the app's release had landed first and the packages run silently cut no release.
-
A release cuts the tag and the GitHub Release; the publish is dispatched. The release commits are pushed with
GITHUB_TOKEN, which raises no workflow run (onlyworkflow_dispatch/repository_dispatchare exempt), so thepackages-publishjob callsgh workflow run publish-plugins.yml -f packages=…for exactly the packages that released, andapp-publishcallsgh workflow run publish.yml -f tag=…. Both publish workflows stay separate and keep thenpmenvironment's approval gate, the gates and the tarball check. -
The two release jobs repeat their setup steps rather than sharing them through YAML anchors. GitHub does support anchors, but an alias carrying an entire step into a DIFFERENT job is not a shape the documented examples cover, and a parser that rejects it means no release at all, silently, on the push that needed one. Six short steps duplicated is the cheaper failure mode.
-
A rehearsal still writes to PRODUCTION unless it is
--dry-run. The runner commits and then pushes toorigin— a real branch move and real tags — and creates the GitHub release pages;assertReleaseEnvironmentinrelease/packages.jsrefuses to run outside CI unlessKABMO_RELEASE_ALLOW_NON_CI=1. (The per-package runs this replaced were worse:@semantic-release/gitpushed torepositoryUrl, read frompackage.json'srepositoryfield rather than the clone'sorigin, so a "scratch" run pushed togithub.com/kabmo-labs/kabmoand had to be reverted by hand.) Rehearse with--dry-run: it writes nothing at all — no version, no changelog, no lockfile — becausewritePackageReleaseis not called and semantic-release'sprepareis skipped in a dry run. -
@semantic-release/npmcannot write the version here, and that was found by rehearsing. It shells out tonpm version, and npm does not support theworkspace:protocol this workspace declares its SDK dependency with: the run dies withEUNSUPPORTEDPROTOCOL Unsupported URL Type "workspace:"on a sibling package's manifest, after npm reifies the tree (it removednode_modulesoutright in the first attempt).release/version-package.mjsis a local plugin that writes the one field instead, with no package manager in the loop — which is safe precisely because this pipeline does not publish.bun publishinpublish-plugins.ymlis what packs the protocol correctly (verified: the published 1.0.0 tarball carries the exact SDK version). -
Three mechanisms narrow one repository's history to one package, and all three are needed. (1) A per-package
tagFormat(kabmo-sdk/v${version}) makes the range start at that package's own last tag. (2) A path filter in front of the analyzer and the notes generator keeps only commits that touched the package directory — a tag range still contains every app commit made in between, and afeat(panels)there would bump the package's minor version while its own code did not change (measured on this repo: 12 commits inkabmo-sdk/v1.0.0..HEAD, 2 of them touching the SDK). (3) The local version plugin writes the new version into the package's ownpackage.json, and itsverifyConditionsrefuses aprivatepackage rather than cutting a release with nothing to publish. -
The filter is applied by WRAPPING the two plugins, not by a shareable config.
context.commitsis what both read and semantic-release hands the same context to every plugin in a step, so the only place a subset can be introduced is inside the plugin call. The wrappers are step keys (analyzeCommits/generateNotes), never entries inplugins:validatePluginrequires apluginsarray's first element to be a string or plain object, whilevalidateStepaccepts a function — a function inpluginsfails withEPLUGINSCONF, and the step keys are also the only place a function can carry options. -
release/commits.jsis the path lookup, because nothing upstream has it. semantic-release's own collector (git-log-parser) reads a fixed field set — hash, author, committer, subject, body — and no paths. Two whole-range calls:git logonce for messages and identities, andgit diff-tree --stdin --name-only -r --rootonce for every hash (one process, and measured identical paths togit log --name-only).--rootis what makes the repository's first commit list its paths at all. The scratch-repo test inrelease/packages.test.jsis what pins it. -
scopeCommitstakes the repository as an argument (context.cwd), not a path derived from the module. They are the same in the pipeline, but a caller whose commits came from elsewhere would otherwise have its hashes looked up in the wrong tree, where every commit reads as path-less — and a path-less commit is deliberately kept (a merge or an empty commit carries no change of its own, and dropping it would drop arevertgit recorded that way). That "keep everything" failure is silent; the test caught it. -
Catalog order is load-bearing and a failure STOPS the run.
@kabmo-labs/kabmo-uideclares"@kabmo-labs/kabmo-sdk": "workspace:*", andrelease/packages.jsis the one place a package's directory, tag prefix and manifest name are stated (release/packages.test.jsasserts them against the tree)..github/scripts/publish-plugin-packages.shexits on the first failure rather than publishing akabmo-uiafter a failed SDK release. -
A
workspace:spec is substituted frombun.lock, NOT from the manifest — so bumping a version without refreshing the lock publishes a stale dependency.bun.lockrecords a version for every workspace package, andbun publishreads that record. Measured in production: the version plugin bumpedpackages/kabmo-sdkto 2.0.0 and committed it, but the lock still said 1.0.0, so the next release published@kabmo-labs/kabmo-ui@2.0.0declaring"@kabmo-labs/kabmo-sdk": "1.0.0"while the SDK was 2.0.0 on the registry — an install resolving the old SDK, which is exactly the incompatibility the 2.0.0 release existed to announce. Reproduced in isolation: bumppackages/a/package.jsonwithoutbun installandbun pm packin a dependentpackages/bstill writes the old version.release/version-package.mjstherefore runsbun install --lockfile-onlyafter each version write (--lockfile-onlybecause the job has already installed and only the lock's record needs to change), and@semantic-release/gitcommitsbun.lockbeside the manifest — without the commit the refresh would be discarded and the next release would re-publish the stale pin.release/packages.test.jsbuilds a two-package fixture and asserts the dependent package packs the NEW version. -
A manual release still works and is still the escape hatch: bump the version in the package's
package.json, pushkabmo-sdk/vX.Y.Z(orkabmo-ui/vX.Y.Z), andpublish-plugins.ymlpublishes it. That workflow also takespackages(what the release workflow dispatches),tag(re-run one release whose publish failed, without re-creating it) andpackage(a hand-run fallback) — resolved in that order, and the tag/version match is checked for thetaginput as well as for a tag push. -
The bundled marketplace plugins are released by a version BUMP, not a publish — and the
marketplacejob inrelease.ymldoes it. The job is namedmarketplacerather thanpluginson purpose:publish-plugins.ymlalready means the npm packages@kabmo-labs/kabmo-sdkand@kabmo-labs/kabmo-ui, and a job calledpluginsbeside a workflow called "Publish Plugin Packages" reads as the same thing. Nothing here is published. All three (marketplace/plugins/{command-runner,session-info,stats}) areprivate: trueand reach a user inside the app's own tarball (getBundledMarketplaceDir()is<package>/marketplace;bun pm packcarriesmarketplace/plugins/*). There is no registry for them, so the version their manifest declares is the entire delivery mechanism:syncBundledPluginscompares the installed manifest's version against the store's and applies the new copy only when the store's is strictly NEWER (isNewer). A fix whose version did not move is therefore skipped by every existing install, forever — measured in this repository before the job existed: thestatssticky-header fix (09e097f) and thesession-infoicon fix (283802b) both shipped with their versions untouched, andgit log -Lshows their watermarks still at the original 1.0.0. -
The job sits BETWEEN
packagesand the shell bumps, and that position is the design. The chain ispackages → marketplace → shells → {apk-build, ipa-build, win-build, macos-build, linux-build} → shell-commit → app; the app job fast-forwards to the commits these jobs make (Sync to the current remote) and only then runsbun pm pack, so the bumped manifest is inside the tarball a user installs. A bump landing after the app packed would reach existing installs one release late.tests/ci-gates.test.tspins every hop, because the transitive gate check cannot see ordering. -
The Android shell is released the same way, and for the same reason —
release/android.js+ the sharedrelease/release-shells.mjs, run by theshellsjob (ONE commit for all five shells).packages/android/version.propertiesis the ONE place the shell'sversionNameis declared: the build reads it at configuration time, the shell appends it to its WebView User-Agent asKabmoAndroid/<versionName>, andpublish-android.ymlnames the assetKabmo-<versionName>-android.apkfrom it — so the version the console compares (versionFromAssetNameagainstshellVersion) is the same number by construction. It used to be the app's release TAG, which tied two independent cadences together: a shell-only fix could not reach an installed app unless the server also cut a version, and a server release shipped an APK whose version said nothing about whether the shell had changed. The bump level comes from the same analyzer, the write is surgical on the oneversionName=line, and achore/docs/test-only change asks for none.version.propertiesrather thanbuild.gradle.ktsis deliberate: the watermark isgit log -Lon the version LINE, and the Gradle file is rewritten for reasons that release nothing, so the range would start at the wrong commit.0.3.0is not arbitrary — the last shipped APK (kabmo-android-v0.2.0.apk, whoseversionNamewas the app tag) makes every installed shell reportKabmoAndroid/0.2.0, so starting below it would makeisNeweranswer false for the first independent release and no installed app would ever be offered it.versionCodeis still the workflow run number (-PkabmoVersionCode), because it is a monotonic counter rather than a version.release/android.test.jsasserts the file, the build's use of it, the asset naming, the read/rewrite, and the watermark and range against a throwaway repository. -
The bump must be COMMITTED by this job, not left for the app's release commit. semantic-release's
@semantic-release/gitcarries only its ownassets(CHANGELOG.md,package.json,bun.lock), so a plugin bump left uncommitted is discarded when that job resets to its checkout — and the tarball would pack the OLD version. The commit is achore(whichrelease/release-rules.jsgivesrelease: false, so it cannot cut a version by itself) and carries[skip ci]. -
release/marketplace.jsholds the catalog;release/watermark.jsholds the watermark itself (shared with the Android shell);release/release-marketplace.mjsis the runner. The watermark isgit log -Lon the version LINE, and a tag cannot serve. These plugins are released by the APP's release, so a bump rides inside achore(release): vX.Y.Zcommit and there is no per-plugin tag to range from.versionWatermark(dir, cwd)asks git which commit last changed"version"in the manifest, andcommitsSinceWatermarkranges from it — everything a plugin's history has to offer is either before the version it currently declares (already out) or after it (not yet).-Lis what makes it correct: agit log -p | grepwould report every commit that rewrote the file. An unresolvable watermark (shallow clone, no version line) reports every commit the caller collected rather than none, because "cannot tell" must never read as "nothing to do". -
The bump LEVEL comes from the same rules as everything else.
release/release-marketplace.mjsruns the real@semantic-release/commit-analyzerwith the config looked up by name fromrelease.config.mjs, so afixis a patch, afeata minor and aBREAKING CHANGE:footer a major — verified on this tree:session-infocomputed 2.0.0 (its range contains5018640, whose body carries a real breaking footer) andstats1.1.0. A range ofchore/docs/testcommits asks for nothing and the version is left alone, so a plugin whose only change was a test file does not ship a no-op update to every user. -
Only the bump is derived — no changelog, no tag, no GitHub release. None of those reach an installed plugin, and
@semantic-release/changelogwould commit a file per plugin that nothing reads. -
The write is surgical: two version LINES, never a
JSON.stringifyround-trip.replaceVersionLinesrewrites"version"(2-space indent) andkabmo.version(4-space) by anchoring on their indentation and the previous value, and throws unless it rewrote exactly two. AJSON.stringify(manifest, null, 2)round-trip is whatrelease/version-package.mjsdoes for the packages and is wrong here: these manifests are hand-formatted, and re-serializing expanded every inline object — measured, a two-line bump came out as a 16-line diff rewritingpeerDependenciesMeta. -
Both version spellings must agree, and the gate says so.
package.jsoncarriesversionandkabmo.version; the registry reads the SECOND (toManifestreadspkg.kabmo) and the sync compares it, so bumping only the first is a no-op that looks like a release.release/marketplace.test.jsasserts they match in every manifest, that every directory undermarketplace/plugins/has aBUNDLED_PLUGINSrow (a plugin no row names is never bumped), that each row'sidis the manifest's own id, and that every plugin staysprivate— plus the watermark and range against a throwaway repository, since a watermark is a fact about history and a test reading this repo's would break the moment a commit landed. -
The gates and the browser specs are a REQUIREMENT of every release, and that is why they live in reusable workflows.
.github/workflows/gates.yml(the four gates,bun test, the generated settings schema) and.github/workflows/e2e-specs.yml(the Playwright suite) areworkflow_callfiles;ci.ymlande2e.ymlare PULL REQUEST triggers that call them, andrelease.yml,publish.ymlandpublish-plugins.ymleach have two jobs that call them andneeds:them. A release job is therefore unreachable until both have passed. Re-running the commands insiderelease.ymlwould be a second copy that drifts from what a pull request runs, and reading another run's conclusion over the API races the run it is waiting for — a release run would have to tell "no run found yet" apart from "no run exists", and a redmainread as a missing run is precisely the failure this shape prevents../.github/workflows/<file>.ymlis the reference form (same commit as the caller);$/…says the same thing but is newer, andactionlintrejects it — a parser that refuses the spelling fails the whole workflow, which on a release pipeline means no release at all, silently. -
Each releasing workflow gates the commit it actually acts on, and the three are not the same commit.
release.ymlgates the pushed commit (emptyref:input = the caller'sgithub.sha);publish-plugins.ymlgatesgithub.shatoo, but for a different reason — a tag push is a baregit pushof a ref nobody gated, and these tags are pushed byrelease.ymlonto the release commit, which is a LATER commit than the onerelease.ymlitself gated;publish.ymlpassesref:= the tag, because arelease: publishedrun is not a push tomain(noe2e.ymlrun exists for that event to wait on at all) and a dispatch re-run must verify the published bytes rather thanmain's tip.release.ymldeliberately runs its gate jobs BEFORE each release job'sSync to the current remote: the sync can only fast-forward onto a release commit this same workflow produced, and that commit's own run gated its own starting point, so nothing ungated reaches a tag through it. -
A reusable workflow RENAMES the checks a commit receives, and nothing can prevent it. A called workflow's checks are namespaced by the CALLER's job name, so
<caller job> / <callee job>is what reports: measured on this repository, the single jobGatesinci.ymlnow reportsGates / ChecksandGates / Settings schema, where it used to reportGatesandSettings schema. That is inert HERE only becausemain's ruleset requires no status checks (verified: its rules aredeletionandnon_fast_forward). A repository whose branch protection DID require those names would need the ruleset updated in the same change, or every pull request would wait forever on a check that no longer reports — and the callee's job name is not configurable from the caller, so there is no spelling that avoids it. -
A rejected push of the release's NOTES ref strands the release AFTER the tag is pushed, and re-running the job repairs nothing.
Release the appruns semantic-release, whose order is commit → tag →git push --tags→git push refs/notes/semantic-release-<tag>→publish. On the release run of 2026-11-11 (43120058573) the fourth step was rejected —! [remote rejected] refs/notes/semantic-release-v0.28.0 … (failed)— with no rule behind it (the repository's only ruleset targets branches withdeletion/non_fast_forward, and the identical push from a developer machine succeeded minutes later), so it was a server-side rejection that has not recurred in 37 earlier releases. The first three steps had landed:maincarriedchore(release): v0.28.0and the tag existed, while npm still served 0.27.0 and NO GitHub release existed. A re-run of that job is not the repair, and it is not harmless either. The job re-executes on the run's original sha, but its ownSync to the current remotestep fast-forwards tomain's tip first, so what semantic-release analyzes is whatevermainis NOW: with no commits after the tag it logs "There are no relevant changes" and exits 0 without publishing, and with commits after it, it cuts a NEW release from a commit this run never gated. Measured on 2026-11-12: re-running43120058573to clear its red status cutv0.29.0from62e7ca21— 22 commits later, whose own gates were red — and published a GitHub release for it.publish.ymlcannot fire for the stranded tag either, because its trigger isrelease: publishedand there is no release to publish. Re-run that job only whengit log <tag>..origin/mainis empty. The repair is three moves: (1) push the notes ref by hand (git notes --ref semantic-release-<tag> add -f -m '{"channels":[null]}' <tag>, the exact contentaddNotewrites, then push that ref); (2) create the release on the tag with the CHANGELOG section as its body, which is what firespublish.yml— gates and browser specs against the tag, thenbun publish; (3) dispatch each shell body (publish-android/-ios/-macos/-windows/-linux.yml) withtag:, because their attach phase downloads an artifact uploaded by an earlier call in the SAME run and an attach-only dispatch has nothing to download — so every dispatch BUILDS from the tag.Release the app'sreleased=falsekeeps its own attach jobs skipped on any re-run, which is why (3) is the owning path. Android's dispatch also requiresversion-code: pass the run number of the stranded release, the value its skippedapk-buildwould have used. -
A push to
mainraises exactly ONE workflow, andtests/ci-gates.test.tsasserts it. GitHub starts one run per workflow FILE whoseon.pushmatches, and the files do not know about each other:ci.ymlande2e.ymlused to carrypush: branches: [main]besiderelease.yml, so every merge ran the gates and the browser matrix twice on the same commit. Measured on 26333b1: CI 6m33s and E2E 25m17s beside the identicalGates / …andE2E specs / …jobs inside the Release run, and the duplicate pair had already DISAGREED — that CI run'sGates / Checks (Windows)went red on anEBUSYtemp-directory rmdir inapplyStashwhile the Release leg of the same job passed, which is a redmainwith no code change behind it. Those triggers are gone: the gates are a job ofrelease.yml(which is whatneeds:makes binding anyway),ci.yml/e2e.ymlkeep only their pull-request triggers, andlabel-merge-conflict.ymlsweeps every four hours instead of on the push that caused the conflict — a 26s label mirror is not worth a second run per merge. The test walks every workflow file and fails if any other file'son.pushcovers every push tomain(apaths:-filtered push, likepr-intake.ymlre-validating its own scripts, is not every push). -
A gate job never carries an
if:. A gate with a condition is one that can be skipped, which is not a gate — thee2elabel condition therefore stays one2e.yml's own caller job (the one context where a label exists) and a release always runs the browser layer. That matters becausee2e.ymlskips the browser suite on a pull request without the label, so the merge that produced a release commit may never have run one. -
The iOS shell is the same product on the other mobile platform, and it shares the console's contract rather than restating it.
packages/iosis a SwiftPM package (Swift 6 + UIKit + WebKit, no SwiftUI, no third-party deps, no.xcodeproj) with the same two-target splitpackages/macosuses:KabmoShellholds every rule that can be tested without a screen (URLNormalizer,ShellSettingsincl. the zoom mapping,LoadingState,HealthProbe,ShellUpdate,ShellUserAgent,SVGPath/Wordmark/WordmarkRenderer) andkabmo-shellis the UIKit app. The app target is guarded by#if canImport(UIKit)soswift buildstays meaningful on a Mac with only the Command Line Tools — the logic suite (swift run kabmo-shell-tests, a plain executable because XCTest ships with Xcode) runs there and in CI, and the application only compiles against the iOS SDK. Where the platform genuinely differs, the shell says so instead of imitating Android: an IPA cannot be installed by an app (noPackageInstallerequivalent, no sideload-by-URL), soShellUpdate.actionrecognises an IPA download and opens the release page with a reason instead of writing a file nothing can use; andWKWebView.pageZoomis already page-relative, soShellSettings.pageZoomis a plain ratio — the Android twin's density multiply would render a 100% setting at 2.6× on a 3× phone, whichShellSettingsTestspins. The launch overlay's rules are the Android ones, including the two that fail silently: a progress frame afterdone/failedis ignored, anddidFinishnever clears a failure (a failed load still finishes on WebKit's error page). Progress arrives by KVO onestimatedProgress—WKNavigationDelegatereports started/finished/failed and nothing in between, so a delegate-only shell draws a bar that jumps from indeterminate to gone. The app is namedKabmo, and the name is ENFORCED because nothing fails when it drifts.CFBundleDisplayNameandCFBundleNameare bothKabmo(the Home Screen, the app switcher and Settings read the first), the bundle isKabmo.app, andCFBundleExecutableisKabmo— the FILE inside the bundle, whichscripts/build-ipa.shcopies the SwiftPM product to, because the product stayskabmo-shell(SwiftPM derives it from the target, and a lower-case binary name is the platform's convention). Three files state it and each can be changed alone, so all three are checked: the build script refuses a bundle whose display name is notKabmoand refuses an executable the bundle does not carry,publish-ios.ymlre-checks both on the ARTIFACT (a stale checkout, or a later step rewriting the plist, passes the script's check and fails here), andrelease/ios-name.test.jspins the plist, the script, the workflow and the console's own… for iOSlabel. The quick action's title is deliberately NOT the app name: it readsServer settings, because a shortcut titledKabmowould be the icon's label twice. The Android shell'sapp_name, the macOS/Linux/Windows shells'Kabmowindow and executable names, and the PWA manifest'sname/short_nameare the same word — one product, one name. A download keeps the session cookie, which is why it is aWKDownloadand not a URL handed to Safari (ShellDownloads.swift): the editor's file lives on the console's own origin and is authenticated by anHttpOnlycookie, so handing the URL to the system browser fetches the LOGIN PAGE — a corrupt-looking file rather than an authorization failure, the exact bugKabmoDownloadsprevents on Android.WKDownloadtransfers with the web view's own cookie store and the finished file goes to the system share sheet;ShellUpdate.safeFileNamemakes a server-supplied name one path segment (aContent-Dispositionwith../../etc/passwdwould otherwise resolve outside the download directory). An IPA is refused here too, by the sameShellUpdatedecision. The wordmark ispublic/kabmo-wordmark.svgas path data (Wordmark.swift, generated, never hand-edited) andWordmarkTestsre-derives every number from the SVG plus rasterizes it to assert ink where the artwork has ink — the same guardpackages/android'sWordmarkDrawableTestapplies to its VectorDrawable. The server chip is the same control the Android shell draws, one row down from the drawer's title bar:ShellServerHostanswersservers_state/servers_add/servers_remove/servers_activateoverwindow.webkit.messageHandlers.kabmo, and the page adapts it into__kabmoCall— the same four commands, the samestartable: false(no child process on a phone), and the same drawer placement, because the chat header has no room at 390px.ServerListlives in the LOGIC target with the wire and the migration from the old singleserver_url, soswift run kabmo-shell-testspins the rules without a simulator. The switch itself never touchesWKWebsiteDataStore:ShellServerHosthops to the main actor beforeonActivate, soswitchServerneeds no second dispatch, and the cookie delete the first version performed is gone for the same reason as Android's — it signed the user out of BOTH servers.onSavedno longer clearsloadedURLeither, so reopening Settings on an unchanged address (the zoom slider lives there) stops throwing away the live document, tab state and composer draft; a real address change is still caught byviewDidAppear. -
One console contract for both shells, and the prefix is the only per-shell fact.
src/shared/lib/updates/shell-ua.tsparsesKabmoAndroid/andKabmoIOS/through ONE grammar (shellVersion(ua, kind),SHELL_UA_PREFIXES),src/server/lib/updates/shell-release.tsresolves either artifact from the same release LIST (fetchShellRelease(kind), per-shell cache onglobalThis,resetShellReleaseCache), andsrc/client/hooks/ui/updates/shell-download.tsholds the one offer table both sidebars call (useShellOffer). The routes stay separate (/api/updates/android,/api/updates/ios) because one endpoint answering "the newest shell" would need a query parameter whose absence silently means Android. There is no iOS INSTALL offer: iOS has no sideload-by-URL path, soshouldOfferShellDownload('ios', null, …)returns null even on an iPhone — only an installed iOS shell is ever offered an update, and the Android browser offer is unchanged. The bootstrap carries two fields (shellVersion,iosShellVersion) rather than one "shell version", because the two artifacts are on separate release tracks and folding them would compare one shell's version against the other's published asset. -
The Windows shell is released the same way, and for the same reason —
release/windows.js+ the sharedrelease/release-shells.mjs, run by theshellsjob.packages/windows/version.propertiesis the ONE place itsversionNameis declared:KabmoDesktop.App.csprojreads it at build time through theReadShellVersiontarget (into the assembly'sVersion, which is what the shell reports to the page asshellVersion), andpublish-windows.ymlnames the asset from it. The version is never written in the.csproj— a literal there is a second source that drifts the first time either is bumped, and the failure is silent (the app reports a version the pipeline never published);release/windows.test.jsfails on it. The target reads the file throughRegexrather thanReadLinesFromFile+ aStartsWithfilter, because the item-metadata form evaluates to the LITERAL text@(_VersionLine)when the item is empty and the SDK rejects that withNETSDK1018(measured). The artifact is an INSTALLER —Kabmo-<v>-win-<arch>-setup.exe, compiled frompackages/windows/installer/kabmo.issby Inno Setup 6, which is preinstalled onwindows-latestAND onwindows-11-arm(verified against actions/runner-images: 6.7.1 on Windows 2022, 2025 and Windows 11 Arm64), so the build needs no third-party action and no download at run time. A ZIP would leave no Add/remove-programs entry, no Start-menu entry and no uninstaller, so "which version is this" and "how do I remove it" would both have no answer — the same reasonpackages/macosships a.appandpackages/linuxa.tar.gz(each platform's own convention). Four properties are load-bearing andrelease/windows.test.jsasserts each: a STABLEAppId(a generated one installs a second copy beside the first, with two Start-menu entries and two uninstallers),PrivilegesRequired=lowest(the app writes only to%APPDATA%\Kabmoand%LOCALAPPDATA%\Kabmo\webview, so the ordinary install shows no UAC prompt;/ALLUSERSoverrides), a WebView2 check in[Code]before anything is copied (a missing runtime is why the window paints nothing, and saying so up front beats a blank window), andMinVersion=10.0.17763(the Evergreen Runtime's floor). The version arrives as/DAppVersion=<v>and the workflow re-reads it off the built file's ownProductVersionbefore uploading. It is NOT an MSIX: MSIX requires a certificate bound to a publisher identity and refuses to install without one, so the installer is unsigned and SmartScreen warns until it has reputation. There is no User-Agent token, but the console DOES offer this app an update — over the bridge, the same contract macOS uses (__kabmoDesktop.shellVersion, read from the assembly's ownVersion). Unlike the two mobile shells, nothing is downloaded FROM the console: those two are, so the server parses their published version on every request, while a desktop app is installed by hand and only needs to be TOLD it is behind. -
The Linux shell is the fourth port of the same shell, and its two real differences from macOS are forced by the platform, not chosen.
packages/linuxis a Rust crate (gtk0.18 +webkit2gtk2.0 with thev2_22feature floor, so Ubuntu 22.04 and Debian 12 are supported) split the way the Swift package is:src/store.rsholds the rules (server list, ownership by recorded pid,normalise_urlrefusing a base path),src/system.rsthe side effects (probe, per-port record discovery, aprocess_group(0)spawn killed withkill(-pgid)),src/main.rsthe window's app and wiring, withsrc/chrome.rsholding the window's own behaviour (shortcut table,window.txt, the webview's data directories, the page's drag/double-click/contextmenu intents) andsrc/commands.rsthe commands the page may issue. The rules suite is a plain executable split by domain underrules/(cargo run --bin kabmo-desktop-tests, 78 checks, no display), because a rule that can only be checked by opening a window is a rule that is not checked. The binary is namedKabmo, not the crate's name — GTK derives the process name,WM_CLASSand the taskbar label from the executable's file name, sokabmo-desktopput that string in the window list while the window's own title said Kabmo (the same driftpackages/macosfixed by naming its SwiftPM productKabmo);mainsetsprgname/application_namefrom oneAPP_NAMEconstant before GTK starts, andrelease/linux.test.jsasserts the title, the About panel, the launcher template'sName=/StartupWMClassand the binary's own file name together. The installer is a real script, not a heredoc insidebuild-app.sh, and the.desktopis a TEMPLATE it fills in (scripts/install.sh+scripts/kabmo.desktop.in):Exectakes an absolute path while a tarball unpacks anywhere, and the shipped-ready entry this replaced usedExec=sh -c '…' sh %k, whichdesktop-file-validaterejects outright (the spec has no single quotes, and$must be escaped inside a quoted argument) — an invalid entry fails SILENTLY, with the menu listing an app that does nothing when clicked. TheExecvalue is always QUOTED because a space is a reserved character there and the validator does NOT catch an unquoted one (measured:Exec=/tmp/my prefix/bin/Kabmovalidates, and a launcher then splits it into two arguments), whileTryExecstays a bare path for the inverse reason. The installer refuses to write an entry with an unresolved@TOKEN@, validates what it wrote, and has--uninstall;publish-linux.ymlRUNS it into a throwaway prefix on every release and checks what it placed, so a token the script stopped filling in fails the build rather than the user's menu. Verified end to end: the workflow's own verify step run verbatim, a tarball unpacked into a random directory and installed from there, andgtk-launch kabmostarting the app from the generated entry. The release wiring is the other three shells' —release/linux.js+ the sharedrelease/release-shells.mjs, run by theshellsjob ofrelease.yml,publish-linux.ymlbuilds before the tag (appneeds: linux-build) and only attaches after it (linux-app), andpackages/linux/version.propertiesis the ONE placeversionNameis declared (build.rsbakes it in asKABMO_SHELL_VERSION; neverCARGO_PKG_VERSION, because the crate is never published). -
The three DESKTOP shells ship two architectures each, built NATIVELY, and every artifact is checked against its own header.
macos→arm64(macos-15) +x64(macos-15-intel);windows→x64(windows-latest) +arm64(windows-11-arm);linux→x86_64(ubuntu-latest) +arm64(ubuntu-24.04-arm) — every label verified in the GitHub-hosted runner reference, and each row compiles, runs its rules suite and verifies on the machine it targets. A cross-build is not an option: all three link native libraries (AppKit/WebKit, WPF/WebView2, GTK/WebKitGTK), so it would need a sysroot and would ship a binary nothing in the job ever executed. The asset name carries the architecture, in one scheme for all three —<App>-<version>-<platform>-<arch>:Kabmo-<v>-mac-<arch>.zip+.dmg,Kabmo-<v>-win-<arch>-setup.exe, and on LinuxKabmo-<v>-linux-<arch>.tar.gz/.deb/.rpm/.AppImage(+.zsync).Kabmois capitalised because it is the product's NAME (the word the window title, the installer and the.desktopentry carry), not a package slug; the two MOBILE shells keepkabmo-android-v<v>.apk/kabmo-ios-v<v>.ipabecauseversionFromAssetNamePARSES those to answer "is a newer shell published", and renaming one would silently stop offering updates. Nothing parses a desktop name, which is why those three were free to change. Each build asserts the architecture of the file it produced, from the file's own header —lipo -archs(Mach-O), the PEmachinefield (0x8664x64 /0xAA64Arm64), the ELFe_machinefield (62 x86-64 / 183 AArch64) — because a runtime pack or SDK that silently resolved to the host architecture would publish anarm64-named file carrying an x64 binary, which fails on the user's machine and nowhere in the pipeline. The macOS matrix carries a separatemachofield (x86_64) becauselipoprints a different spelling from the asset label (x64). The Windows installer'sArchitecturesAllowedcomes from the same/DAppArchvalue that names the file —x64osfor x64,arm64for Arm64 — so the Arm64 installer refuses an x64 machine and the x64 one refuses Arm64;x64compatiblewould have matched both via emulation, which is now the wrong file for an Arm machine to pick. Each build phase uploads one artifact PER architecture and the attach phase downloads them withpattern:+merge-multiple: true, then refuses to upload unless exactly two files arrived — a shared artifact name would let the second row overwrite the first, and a one-architecture release installs on one machine family and not the other. Each desktop shell ships every package format its platform actually uses, and the Linux three are built by scripts besidebuild-app.sh. macOS ships a.zip(what a script or updater consumes —ditto, so the signature and extended attributes survive) AND a.dmg(hdiutil createwith the bundle beside anApplicationsalias, which is what a person expects to drag);hdiutilwarns that it is deprecated in favour ofdiskutil image create from, and that alternative is unusable here because it takes no-fs— a folder source becomes an APFS volume, while HFS+ is what every macOS from 10.x up mounts. Linux ships.tar.gz(no root,install.sh→~/.local),.deb(dpkg-deb),.rpm(rpmbuild) and.AppImage(appimagetool, pinned, run withAPPIMAGE_EXTRACT_AND_RUN=1because a container has no/dev/fuse) — four answers to "how do I install this", none of which replaces another. Two rules fail only on the user's machine and are therefore stated in the scripts: the.debdepends onlibgtk-3-0t64, notlibgtk-3-0(Ubuntu 24.04 renamed GTK 3's runtime package in the 64-bittime_ttransition, and the old name makes the package UNINSTALLABLE — apt answers "no installation candidate"), and the.rpmrequiresgtk3/webkit2gtk4.1, the Fedora-family names, because the build host is Ubuntu and its own names resolve nowhere.appimagetoolwrites its.zsyncinto the CURRENT DIRECTORY, so the script runs it from inside the output directory — an absolute destination put the AppImage in the output dir and the delta metadata in the caller's cwd (measured). The.debnames its architectureamd64/arm64while RPM and AppImage sayx86_64/aarch64, which is why the Linux matrix carriesdebandhostbeside the asset labelarch; the attach phase then requires TWO of EVERY format (shopt -s nullglob, because an unmatched pattern stays literal and would count 1) and treats the.zsyncas optional. Release artifacts go toartifacts/— neverdist/(the client bundle's own output, which a later build can delete) and neverrelease/(tracked source: the bump scripts and their tests). ALL FIVE shells now share one naming scheme —<App>-<version>-<platform>[-<arch>].<ext>:Kabmo-<v>-android.apk,Kabmo-<v>-ios.ipa,Kabmo-<v>-mac-<arch>.zip/.dmg,Kabmo-<v>-win-<arch>-setup.exe,Kabmo-<v>-linux-<arch>.tar.gz/.deb/.rpm/.AppImage. The mobile pair has NO architecture segment because neither artifact is per-arch: the APK is one universal build (the shell is pure Kotlin, no native libraries — verified: no.so, nojniLibs, noabiFilters) and the IPA contains only the device slice (arm64-apple-ios). The mobile rename needs a compatibility path and the desktop one does not, because the console PARSES those two names to answer "is a newer shell published":SHELL_ASSETScarrieslegacyPrefix/legacyExtension(kabmo-android-v,kabmo-ios-v) andversionFromAssetNametries the current scheme first, then the legacy one. Without it an installed shell would read as "no update" from the moment this shipped — silently, since a name that does not match is indistinguishable from a release carrying no artifact. The two mobile prefixes are now bothKabmo-, so the EXTENSION is what keeps a desktop asset from being read as a mobile one;shell-release.test.tspins every desktop filename asnullfor both kinds. -
The IPA is released the same way the APK is —
release/ios.js+ the sharedrelease/release-shells.mjs, run by theshellsjob — andpublish-ios.ymlbuilds it on macOS.packages/ios/version.propertiesis the ONE place the shell'sversionNameis declared:scripts/build-ipa.shfillsCFBundleShortVersionStringfrom it throughrelease/ios-version.mjs, the shell appendsKabmoIOS/<versionName>to its WebView User-Agent throughapplicationNameForUserAgent(set on the CONFIGURATION — a value assigned to a live web view is ignored with no error, so the token would be missing from the very request that renders the shell), and the asset is namedKabmo-<versionName>-ios.ipafrom the same file. The two-phase shape is the APK's:ipa-buildruns BEFORE the tag andappneeds: ipa-build, so a Swift error or an unavailable macOS runner stops the release before anything is tagged;ipaonly attaches the run artifact. The bundle is assembled by hand (scripts/build-ipa.sh: noxcodebuild, icon rendered from geometry byscripts/make-icon.swift, icons verified against the plist's own list) and is unsigned — signing needs an Apple-issued certificate bound to a team and a device set, so the artifact is for a developer who re-signs it, for Xcode/TestFlight, and for CI verification.release/ios.test.jsasserts the file, the build's use of it, the asset naming, the read/rewrite, the watermark and range against a throwaway repository, AND that the Swift prefix, the TypeScript prefix and the asset naming agree — three files stating two strings, where a change to one alone makes the console read the shell as a browser. -
A shell version bump reaches
mainonly AFTER every shell build passed, and the staging branch is what makes both possible. The order is bump → build → COMMIT → tag → attach.shellswrites the fiveversion.properties, commits them as ONEchoreand publishes that commit onrelease/shell-bump; the five builds compile that sha;shell-commitfast-forwardsmainonto it once all five are green;appthen tags frommainand the attach jobs upload the artifacts. Committing first was the bug: a build that failed (a Kotlin compiler that moved, a missing keystore, a Rust crate that stopped building) leftmaindeclaring a shell version no artifact exists for, so the next release bumped again and the version file became a record of attempts rather than of builds — the failure this order removes, not just a reordering.ref:cannot bemainany more (it would compile the PRE-bump tree and every artifact would declare the previous version, an update no installed app is offered), and it is a COMMIT rather than the branch name so a later run cannot move the tree under a 30-minute build.shell-commitcarries no job-levelif:— a skipped job skips every dependent, andappmust still run to report that a chore-only push has nothing to release — and it refuses to push unless the staged commit is a descendant ofmain's tip, becausemainmoving during the build window invalidates the artifacts rather than being something a merge could paper over. The staging ref is deleted only after the commit landed: while a run is stopped at a build it is the only ref holding the tree those artifacts were built from, which is what makes re-running the failed build job possible.tests/ci-gates.test.tspins all of it (noHEAD:maininshells, oneneeds:edge per build onshell-commit, and the same stagedref:in all five builds). -
The Android APK is a RELEASE artifact, not an npm package — and BUILDING it is a GATE on the app release.
packages/androidis a private Kotlin application, so there is no registry for it:.github/workflows/publish-android.ymlis a reusable body (the same shape aspublish-app.yml) whose only output is the.apkattached to the GitHub release. It runs in two phases, and the split is the point.buildcompiles, verifies and uploads the APK as a run artifact;release.yml'sapk-buildjob calls it withmode: build,ref: ${{ needs.shells.outputs.ref }}(the staged bump commit) andversion-code: ${{ github.run_number }}, andappneeds: apk-build— so a toolchain that moved, a missing keystore, a Kotlin error or a signature mismatch stops the release BEFORE a tag exists.attachdownloads that artifact and uploads it to the releaseappcreated;release.yml'sapkjob calls it withmode: attach,needs: [app, apk-build]and the sameif: needs.app.outputs.released == 'true'asapp-publish. Artifacts are scoped to the workflow RUN, so the two calls are one pipeline: the attach uploads the exact bytes the checks passed and cannot rebuild them. The old shape built the APK after the tag, so a failure there left a release already tagged and published with no shell attached — measured: the SDK'stoolspackage was removed and the job died in setup, so the console kept offering the previous APK and the only repair was a hand-run dispatch. Building before the tag inverts that.ref: mainrather than the trigger commit is load-bearing: theandroidbump job just pushed the shell version, and building the starting commit would declare the PREVIOUS one — an update no installed app is ever offered. A manualworkflow_dispatchbuilds the TAG it names (so a repair matches the release it repairs) and attaches when given one; there is nomodeinput on that path, because a dispatch has no earlier call in its own run to have uploaded an artifact. It does NOT call the gate workflows: it is reachable only fromrelease.yml, whoseappjob already depends transitively on both, and re-running the browser matrix for a packaging step adds minutes without coverage. That is whytests/ci-gates.test.tstreats it as a body that is NOT a gate provider and asserts theneeds:chain instead.permissions: contents: writemust be on the CALLER of the attach — a reusable workflow can only downgrade what it inherits, soreadinrelease.ymlturns the body'swriteinto read and the upload fails with 403 after a full build; the build call needs onlycontents: read.version-codeis${{ github.run_number }}, typedstring, stated at BUILD time and nowhere else: Android refuses an install whoseversionCodedoes not increase, so a fixed value makes every release after the first uninstallable over the previous one — andgithub.run_numberis a STRING context value, so anumberinput rejects it (actionlint: "string value cannot be assigned"). TheversionNamecomes frompackages/android/version.properties— the shell's OWN version, bumped by the sharedrelease/release-shells.mjsin theshellsjob ofrelease.yml— and onlyversionCodereaches Gradle as a property (-PkabmoVersionCode), because it is a monotonic counter rather than a version. The built APK is verified withaapt2 dump badgingagainst both, and the asset is namedkabmo-android-v<versionName>.apkfrom the same file, becauseversionFromAssetNamereads the published version out of the asset NAME. Signing material is REQUIRED: withoutANDROID_KEYSTORE_BASE64the build step FAILS the job rather than falling back to a debug key (a different key on every runner, so no APK it produced could install over the previous one), and the built certificate is checked against the keystore's own fingerprint; the emptiness check lives in the SHELL because thesecretscontext is not available in a stepif:. The keystore andkeystore.propertiesare removed in analways()step. -
The shell button is TWO offers from TWO facts, and conflating them hides one of them. It sits in the sidebar footer directly after About (both layouts).
update: the page is running inside the APK and a newer one is published.install: the page is an Android BROWSER (Chrome, Brave, Firefox) and an APK is published — the reader may not know the native shell exists, which is the whole point of the offer, and there is no installed version to compare against so it names the newest published one. A desktop browser and an iPad get neither: an APK cannot be installed there, and the app's own update badge already covers the server.ShellDownload.kindcarries which one it is, andshellDownloadLabelis the single place the wording lives (Install …vsUpdate …) because both footers draw the control — the phone's visible word isGet APK/Update APKrather than the oldAPK, which named the file type instead of the action. Both facts travel on the User-Agent, and they are different questions:KabmoWebView.configureappendsKabmoAndroid/<versionName>andandroidShellVersionparses it into the bootstrap'sshellVersion(the app), whileisAndroidDevicematches the platform token intoisAndroid(the device). The UA is the only channel that crosses the very request which renders the shell, so the page is served already knowing and no bridge or extra round trip is needed.isAndroidDevicematchesAndroid, neverMobile: an Android tablet sendsAndroidwithoutMobileand is a device the APK installs on, while an iPad sendsMobileand has no APK at all — aMobiletest would drop the first and admit the second. Measured in the browser across six user agents: Chrome-Android and Brave-Android →Install Kabmo 0.3.5 for Android(Get APK), shell0.3.0against a published0.3.5→Update Kabmo 0.3.5 for Android(Update APK), shell0.3.5→ nothing, desktop Chrome → nothing, iPad → nothing. The second comes fromGET /api/updates/android→fetchAndroidRelease(src/server/lib/updates/android-release.ts), one unauthenticated GitHub read of the release LIST — not/releases/latest, which answers the newest release of ANY kind and this repository publishes THREE artifacts from one push. The packages are released FIRST (packages → marketplace → android → apk-build → app), and@semantic-release/githubruns in both pipelines, so akabmo-sdk/v*release is newer than the app release that carries the APK; measured against a stub answering exactly that shape,/releases/latestproduced{url: null, latest: null}and the button vanished while the APK sat one entry below. The probe therefore scans the list (20 entries, drafts and prereleases skipped) and takes the first one whose ASSET LIST names an APK, cached 5 minutes onglobalThis(thebun --hotrule) withresetShellReleaseCache()as the test seam. The version is read from the asset NAME, never the release tag — the APK rides on the app's release, whose tag names the SERVER version, so a tag comparison would compare an APK against a server. An up-to-date app shows nothing, and so does one AHEAD of the published asset (a sideloaded newer build): theupdatebranch requiresisNewer(latest, shellVersion), while theinstallbranch needs no comparison at all because nothing is installed. The shell token alone is enough for the update offer even whenisAndroidis absent — both come from the same UA, so a bootstrap served by an older build must not silently drop the update. A failed probe answers{url: null, latest: null}and never a 500, because a button the console cannot back with a link must not appear. Measured end to end in the real APK against a stub:shellVersion: 0.1.0+ release9.9.9→ button after About with the right href; release0.1.0→ no button, footer reads Settings · About · Desktop; a plain browser → no button at all. -
The DESKTOP trio installs its own update too, and the whole path exists because the shell now reports its ARCHITECTURE. Every desktop artifact is per-architecture (
Kabmo-0.2.0-mac-arm64.zip,Kabmo-0.2.0-win-x64-setup.exe,Kabmo-0.2.0-linux-x86_64.AppImage), so the console used to answer a desktop probe with the RELEASE PAGE — correct for a link, useless for a self-update, because naming one arch's file hands half the readers a build that will not launch. The shell injectsarchbesideshellVersionin__kabmoDesktop(a COMPILE-TIME fact in all three:#if arch(arm64),RuntimeInformation.ProcessArchitecture,cfg!(target_arch), which is also the right answer for a Rosetta/emulated launch),useShellDownloadsends it as?arch=to/api/updates/desktop?kind=…, andfetchShellRelease(kind, fetch, arch)resolves that ONE file.directis a FIELD on the release payload, not something the client infers: it is true for the mobile pair (one file for every device) and for a desktop shell that named its arch, and false for a desktop probe without one — which is exactly the link-versus-button decision.SHELL_ASSETS[kind].selfUpdateis the one table stating WHICH file a shell can install by itself: the.zipfor macOS (ditto -x -kextracts it with its signature; a.dmgcannot be extracted without mounting), the Inno-setup.exefor Windows (a stableAppIdis what makes an install an UPGRADE), the.AppImagefor Linux (the only one of its four formats a shell can replace —.deb/.rpmneed root). An arch the release does not publish keeps the PAGE rather than falling back to the sibling build, and the arch is part of the CACHE KEY (shell-cache.ts,kind:arch), because one console is routinely shared by machines that differ only by architecture.ShellUpdateButton(common/shell-update-button/) is one control on both layouts, and the footer carries NO status text — every word a run has to say is a dialog.canSelfUpdateis the one predicate: a FILE, in a DESKTOP shell, inside the shell — Android installs throughPackageInstaller(its own path, untouched) and iOS cannot install at all, so neither belongs here, and a shell that cannot install it draws a LINK to the release page instead. The LINK draws the glyph too, in both variants — that branch is the mobile pair's ONLY branch.canSelfUpdaterefuses Android and iOS (each installs through its own path, or cannot install at all), so every APK/IPA offer is a link, and the link used to rendervariant === 'label'as the word alone: the phone's footer showedGet APKwith no mark beside it while Settings, About and Desktop all had one. Thelabelvariant's glyph is 14px and its class isLABEL_CLASS— the footer's own bare row, nop-1and no hover plate — because the desktop's 16px padded glyph plate reads as a different kind of control in a row of bare glyph-and-word entries; the icon-only variant keepsICON_CLASSat 16.index.test.tsxpins the link case (an<svg>inside the<a>, the word beside it, nop-1) andmobile.e2e.tsmeasures the rendered box against the About glyph's own width, because a DOM query would pass on an<svg>with no box. The button opensModal.tsxin acreatePortaltodocument.body, and the portal is load-bearing twice: the footer is a 24px flex row of glyphs, so a dialog nested in it put its whole sentence into the ROW's own text content (measured in the browser — the row read as the dialog body), and anyoverflow/transformlater added to that row would clip afixedoverlay. Four phases live in the dialog and nowhere else —confirm(what the platform will do: macOS replaces the bundle, Windows runs the installer silently, Linux swaps the AppImage and says a.deb/.rpminstall cannot; plus what is NOT lost, since only this window restarts),working, and the shell's own sentence fordone/errorwith aTry againthat re-runs the same offer. A run is never started by the footer control — the confirmation is what asks the shell, which is why a 24px glyph cannot replace the app on a single press with no words.reset()runs when the dialog OPENS, so a dismissed failure does not greet the next press with its old refusal;resetrefuses while a run is in flight, because the shell is already replacing itself and reportingidlewould re-arm a control whose second press starts a second installer. Closing mid-run hides the dialog without cancelling anything — the shell has already begun, and a Cancel that could not stop it would be a button that lies — so the control stays disabled until the run answers. The shell does the work, and the reply is sent BEFORE it quits — a page whose shell vanished mid-request would keep a spinner over an update that worked: macOS downloads,ditto-extracts, checkscodesign --verify --deep --strictplus the bundle's identifier and a STRICTLY higher version, renames the old bundle aside (undoing it on failure so the user is never left with no app) and restarts via a detached waiter that waits for its own pid; Windows downloads, checksMZ, runs the installer/SILENT /SUPPRESSMSGBOXES /NORESTART /CLOSEAPPLICATIONS /SP-and closes 600 ms later so the reply lands; Linux requires$APPIMAGE(a.deb/.rpminstall says so and offers the page), checks the ELFe_machine, stages BESIDE the image so therenamestays on one filesystem, and schedules the relaunch one second later. What none of them can promise, and each module says so: authenticity. The macOS build is signed AD-HOC and the Windows/Linux artifacts are unsigned, so these checks catch a truncated download, an HTML error page saved as a binary and the other architecture's build — they do NOT prove provenance. HTTPS from an allowlisted GitHub host is what bounds the damage meanwhile; Developer ID + notarisation and Authenticode are the pipeline changes that would make it a real check. Rules live in testable modules (packages/macos/Sources/KabmoDesktop/ShellUpdate.swift,packages/windows/src/KabmoDesktop/ShellUpdate.cs,packages/linux/src/update.rs) and are pinned byswift run kabmo-desktop-tests(157 checks),dotnet run --project packages/windows/tests(124) and the Linux rules suite — all three suites assert the same host allowlist, the same version comparison and the same refusal sentences, so the four implementations cannot drift about whether an update exists. -
Tapping that button inside the APK finishes the install itself — one system dialog, no file manager — and the keystore is what makes it possible at all.
ApkInstallerdownloads the APK into the app's cache, verifies it (getPackageArchiveInfo: the package must bedev.kabmo.shelland itsversionCodemust be strictly HIGHER than the installed one, because Android refuses an equal code withINSTALL_FAILED_VERSION_DOWNGRADE), then commits onePackageInstallersession;InstallResultReceiverlaunches the system's own "Do you want to update this app?" fromSTATUS_PENDING_USER_ACTIONand reports every terminal status back through the same vocabulary. Silent install is impossible for a sideloaded app — only a device-owner or Play-managed one replaces itself without consent — so the confirmation stays, andREQUEST_INSTALL_PACKAGESplus the per-app "Allow from this source" toggle is what removes the four-step Downloads dance. The rules that fail silently live inApkUpdateand are JVM-tested: what counts as an APK (URL path, MIME, or aContent-Dispositionthat NAMES a file — never the fallback name, or every download would match), which installer status is which failure, and that a download name is sanitized to one path segment.MainActivity.onDestroyreleases the flow's static dialog and the installer callback, or an install that outlives the Activity crashes a successful update withBadTokenException. -
The update path only works because every release is signed by the SAME keystore, and CI now refuses to ship one that is not.
v0.2.0,v0.3.0andv0.4.0each carried a different certificate —apksigner verify --print-certson the published assets shows three distinct SHA-256 digests — becauseANDROID_KEYSTORE_BASE64was unset andbuild.gradle.ktsfalls back to~/.android/debug.keystore, which a runner regenerates per job. Measured on an emulator with the real assets:adb install kabmo-android-v0.4.0.apkover 0.3.0 answersINSTALL_FAILED_UPDATE_INCOMPATIBLE: Existing package dev.kabmo.shell signatures do not match newer version, and the same pair built with one keystore installs cleanly (versionCode17 → 18,Success), while a downgrade is refused (INSTALL_FAILED_VERSION_DOWNGRADE).publish-android.ymltherefore FAILS when the secret is absent (the fallback remains for a contributor's local build, never for a release) and verifies the built APK's certificate against the keystore's own fingerprint —keytoolprints it uppercase andapksignerlowercase, so both are folded before comparing.version.propertiescarries0.5.0for the migration: one uninstall is still needed to get onto a device holding an older build, and every release after that updates in place. -
The WebView's pinch zoom and the Settings → Page zoom slider are DIFFERENT zooms, and the first build had pinch switched off.
setSupportZoom(true)+builtInZoomControls(true)+displayZoomControls(false)is the browser-shaped combination: the gesture works, no +/- buttons appear. The shell shipped with the first twofalse, so a two-finger spread did nothing while Chrome zoomed — the reported "kenapa gak ngezoom kayak Chrome". The slider (setInitialScale, re-applied on everyonResume) is the page's STARTING scale and does NOT block a pinch: measured on Android 15 with a real two-finger gesture (asendeventsequence on/dev/input/event1, sinceadb inputcannot do multitouch), the viewport went 1 → 2.883 withsetInitialScale(100)in force, and a cold start returned it to 1. Two traps cost the most time here and both are about the test, not the code: the emulator still zoomed withsetSupportZoom(false)compiled in (verified withdexdump), so the setting is not the only path into the gesture there and an A/B on it proves nothing; and every early "pinch does nothing" measurement was taken against a page that had not loaded (the server was down, so the WebView showedchrome-error://), where no gesture zooms. Reproduce against a loaded page before concluding anything. -
The shell draws a launch overlay from the tap until the console paints, and it is a SIBLING of the WebView — never a view inside the page. The page cannot report its own readiness (its bundle is what renders the app), and a page-drawn overlay would vanish exactly when the page fails to load.
LoadingOverlay(platform views, like the settings screen) is added to aFrameLayoutabove the WebView;LoadingStateholds the rules and is JVM-tested, because every one of them is an ordering the platform actually produces and each fails as a stuck or missing overlay rather than as an exception. The bar is indeterminate until real progress arrives: a determinate bar at 0 is indistinguishable from a stuck one, and the first seconds of a cold start are when the user decides whether the app is broken — so Chromium's 0% tick is ignored. 100% is not a finish (onPageFinishedis, and the shell is still fetching the bundle at 100%), and progress never moves backwards within a load (a redirect reports 100 then 10, which made the bar snap back and read as a stall). A failed main-frame load keeps the overlay up with a reason and Retry / Server settings — host, connect, timeout, SSL, catch-all — andonReceivedErroris gated onrequest.isForMainFrame, because a page that loads but cannot reach one of its assets reports an error too and treating that as a failed page would cover a working console.onPageFinishednever clears a failure: a failed load still finishes on the error page Chromium renders, and hiding the overlay there is exactly the blank paper screen with no explanation the overlay exists to remove; Retry reloads the saved address because that error page is not a document the console can recover from.startLoad(cold start, saved-URL change, Retry) and a RELOAD re-open the overlay — a plain in-app navigation does not, or the login submit would flash it like a reload. The page's own Reload control is a different thing and was the bug:location.reload()fetches the SAME address again, which from the shell's side is a cold start in miniature (the console is replaced by a blank document while the bundle is re-fetched), and the overlay stayed hidden so the header's button looked like it did nothing. The only signal a reload gives is that the url is the one already on screen — measured on Android 15:onPageStartedreports no reload flag,doUpdateVisitedHistorysaysisReload=false, and alocation.href = '/other'navigation reports a different url, whilelocation.reload()andlocation.replace(location.href)both report the same one.LoadingState.isDocumentReload(startedUrl, shownUrl, phase)is that test, and it requires phaseDONEbecausestartLoadarms the overlay itself beforeloadUrl, so the firstonPageStartedof a cold start would otherwise restart its own arm; the shown url is LATCHED inonPageFinished, never read fromview.url, which already points at the incoming document by the time the next load starts. Verified end to end against a real console behind a 20s-delayed bundle: clicking the header's Reload put the wordmark andLoading the console… 51%on screen, and the same click without the delay completed too fast to see. Verified on a real emulator against a 4s-stalling stub and a dead port: the wordmark +Loading the console… 10%mid-load, no progress node once painted, andCould not connect…+ Retry over the dead port with a tap recovering to the live page. The wordmark is the ARTWORK README.md embeds, not the app's name in aTextView:res/drawable/kabmo_wordmark.xmlis a port ofpublic/kabmo-wordmark.svg(same plate, same three K strokes, same outlined word, same colours) because the overlay is platform views and has no SVG renderer, and the three differences are forced by the format — every y shifted+128.12(the SVG is authored around a baseline at 0 and a viewport cannot start below the origin), the plate a path rather than a<rect>, and the gradient inline in viewport space. A copy of one drawing is exactly what drifts silently (the overlay still renders, just not the mark), soWordmarkDrawableTestre-derives the drawable from the SVG — every path with only y shifted, the plate against the rect, the gradient span and both stops, the stroke weight and per-stroke colours — and fails on a nudged hex.app_namestays as theImageView'scontentDescription. -
ALL FIVE shells draw one launch overlay, and the wordmark in it is GENERATED from the README artwork. Android and iOS had it from the start (a sibling of the web view, four phases, a wordmark, a bar, Retry, a failure that
didFinishcannot clear); the three desktop shells each drew aKabmoTEXT FIELD and a spinner instead, which is a different product for the same few seconds. They now share the contract:SplashState(packages/macos/Sources/KabmoDesktop/SplashState.swift,packages/windows/src/KabmoDesktop/SplashState.cs),LoadingState(Android, iOS) andProgress(packages/linux/src/splash.rs, drawn bysplash_view.rs) are the same four phases (connecting/loading/done/failed), the same three progress rules (a frame after the end is ignored, progress never moves backwards, a zero frame stays indeterminate), the same five failure reasons with one sentence each, and the same reload test. The artwork is the reason this is one bullet rather than five:public/kabmo-wordmark.svgis the ONE copy,scripts/shell-wordmark.mjsGENERATESWordmark.swift,Wordmark.csandwordmark_data.rsfrom it, and each shell's rules suite re-derives every number from that same file (the iOSWordmarkTests,packages/macos/Tests/SplashTests.swift,packages/windows/tests/Program.cs,packages/linux/rules/wordmark.rs) — a hand-typed copy is the shape that drifts silently, because the splash still renders, just not the mark.bun run scripts/shell-wordmark.mjs --checkis a CI gate ingates.yml. A platform that cannot do what the others do says so rather than imitating it: WebView2 exposes NO progress estimate (NavigationStarting/ContentLoading/DOMContentLoaded/NavigationCompletedand nothing between), so the Windows bar sweeps for the whole load instead of inventing a percentage, while WebKit and WebKitGTK give one through KVO/estimated-load-progress;UIProgressViewhas no indeterminate state, so iOS slides aSweepBarsegment along the same 180pt track (two bars sharing onebarRow, or the hidden one collapses and the sentence jumps every phase change); and the reload signal differs per platform — WebView2 reportsCoreWebView2NavigationKind.Reloadexplicitly, whileWKNavigationDelegateand WebKitGTK'sload_changedhave no flag at all, so macOS, iOS and Linux compare the started URL against the one LATCHED when a document finished (isDocumentReload, and only fromdone, or a cold start would restart its own arm). The macOS splash was in the app target and could not be tested, which is how it shipped as a text field:SplashViewmoved intoKabmoDesktopsoTestsWindowrenders it in a real window and asserts the assembled view — the mark present and in the artwork's aspect, the bar determinate only once a real percentage arrives, the sentence the state's, Retry only on a failure — because a splash that drew the wrong phase passed every state-machine case. -
The Android shell has TWO ways to change servers: the console's own chip, and the launcher shortcut. Long-press the Kabmo icon → Server settings still edits the ACTIVE address, and it is still the only entry point that works when that address no longer answers — a console that cannot load renders no drawer to switch from. The chip lives in the DRAWER's title bar rather than the chat header, measured: at 390px with a password set the chat header leaves the session title 89px and a 32px chip costs 40 of them, while the drawer row has ~158px spare. It is a chip, not a labelled button, for the same reason. Still no edge tab and no floating button: the WebView fills the display and every edge belongs to Kabmo's own chrome. What makes the chip exist at all is
window.kabmoHost(ServerHost.kt), adapted by the page into the same__kabmoCallthe desktop trio installs (src/client/lib/shell/transport.ts) — and the split betweenhasShellBridge()andisDesktopShell()is load-bearing, becausetitlebarInsetLeftreads "a shell with no identity" as a macOS window and would reserve 5rem for traffic lights a phone does not have. Commands:servers_state,servers_add,servers_remove,servers_activate; noservers_start/servers_stop, because a phone has no child process to own, and the state saysstartable: falseso the panel never draws one. Params cross FORM-ENCODED and the state comes back as JSON TEXT (ServerWire) becauseorg.jsonis a stub in the JVM unit suite — the same reasonShellPaletteuses a line wire. The shortcut intent targetsMainActivity, neverSettingsActivity: a shortcut is launched with the LAUNCHER's identity, so a non-exported target is refused withPermission Denial: … not exported from uid(measured on a real APK — the shortcut silently did nothing).SettingsActivitytherefore stays unexported andMainActivityopens it, handling the action in BOTHonCreateandonNewIntentbecausesingleTaskdelivers a re-launch to the running instance. That is also whywindow.KabmoNativeand itsDeviceSettingscategory were removed rather than left as a second door: a control that opens a screen the shell already owns is a second thing to keep in sync, and the shell-side entry is the only one that survives a saved address that no longer answers. Two faults in that bridge were shipped in the first version and both are measured. (1)ServerHostanswers every command onserverWork, soonActivatearrived on a pool thread andswitchServercalledLoadingOverlay.render/WebView.loadUrlinline —ViewRootImpl$CalledFromWrongThreadExceptionon the tap, process dead (adb logcat:FATAL EXCEPTION: pool-3-thread-1 … at MainActivity.startLoad, reproducible on an Android 35 emulator against two real password-protected servers). ArunOnUiThreadhop is the fix, and the latch moved intostartLoadso an address recorded but never loaded cannot makeonResumeskip the retry (that was the reported "it does not restart the page and stays on the old server"). (2) Both phones called the cookie wipe on a switch, which is what lost the session: cookies are keyed by host and the session cookie is NAMED per port (omp_session_<port>insrc/server/lib/auth/token.ts), so a different origin can neither receive nor collide with the previous one's cookie — the wipe only signed the user out of every server in the list. Verified on the emulator: signing into both 4400 and 4500, then switching 4400 → 4500 → 4400 → 4500, reopens each console with no login screen and no crash. The desktop trio never cleared the jar onservers_activate; a cookie a server no longer accepts is a302 /loginfrom the auth gate, not a 401 loop. -
A shell's launch overlay paints the CONSOLE's palette, which it can only learn from the page it is covering. Every overlay shipped a literal
#FAF8F3/#141310— the default LIGHT palette's paper and ink — so a dark install opened on a paper-white rectangle and jumped to a near-black console, and the macOS splash drewNSColor.windowBackgroundColor, which follows the OS appearance rather than the theme at all. The shell cannot read CSS (it draws before the page exists, which is the point), and it must not grow a second copy of a 45-palette catalog, so the palette crosses as VALUES:shellPaletteFor(src/shared/lib/theme/shell-palette.ts) projects one palette onto six literal-hex slots —canvas(the page's own ground, NOTpaper:bodypaints canvas, so paper is a step lighter at the exact seam),paper,ink,mutedandhairline(the document's own--ink-secondary/--ink-hairlinemixes, composited over canvas),error— and normalizes every value to six-digit hex because the ported palettes are not uniform (jetbrains-lightcarries#FFF) and four parsers reading a shorthand is four places to get it wrong. The page publishes it aswindow.__kabmoPalette()(src/client/lib/native/palette.ts, installed before the first render, read at CALL time so a theme picked in Settings reaches the next launch with no reload), and each shell stores the answer for the NEXT cold start — the one launch where nothing is running to ask — then applies it to the live overlay too, because a theme changed in Settings is exactly the case where the stored palette is stale and the overlay it describes is still on screen. The wire is a pipe-separated line, not JSON:variant|canvas|paper|ink|muted|hairline|error, because Android'sorg.jsonis a stub in a JVM unit test (Method ... not mocked), so a JSON wire would leave the parser that most needs pinning as the only one that cannot have a test. Each shell parses it with a rule that REFUSES rather than half-fills (ShellPalette.parsein Kotlin/Swift/C#/Rust) — a field that could not be read would paint#000000where the console paints paper, and keeping the previous palette is the only answer that cannot be wrong. Every shell's suite pins its default against the shared string (shellPaletteWire(shellPalette(null))), so a change on one side has to be made on both:ShellPaletteTest.kt(6),ShellPaletteTests.swifton iOS and macOS,ShellPalette.csin the Windows runner,packages/linux/rules/palette.rs, plusshell-palette.test.tsandpalette.test.tsfor the projection and the publisher. The three native surfaces each needed their own "apply again" entry point, because aCALayer/UIButton.Configuration/ProgressBarcopies the colour at assignment and nothing follows the palette on its own:LoadingOverlay.applyPalette(Android, iOS),SplashView.applyPalette(macOS),SplashView.ApplyPalette(Windows) andSplash::apply_palette(Linux, one reloadedCssProvider— and the stylesheet becamepalette::splash_css(&palette), since the constant it replaced hardcoded the light theme). The web surfaces that paint before the bundle are the same fix:firstFrameStyleinlineshtml,body{background-color:<canvas>}into the shell (unlayered, so it cannot lose to the bundle it stands in for — measured a white flash on a dark install for the length of the CSS request), and the PWA manifest'sbackground_colorshipped the brand tile's GREEN (#0B5D3B), so the manifest is now served from/manifest.webmanifestwith the request's palette baked in (themedManifest,no-store) and the shell's link is rewritten to it — a hashed bundled copy's body cannot be varied by any route. Verified in a real browser against a live server: withone-dark-pro-softstored, the served HTML carried<style>html,body{background-color:#21252b;},meta theme-color #282c34andmanifest background_color #21252b, and__kabmoPalette()answereddark|#21252b|#282c34|#abb2bf|#777c87|#343940|#e06c75— moving tolight|#f4f1ea|…on a live theme flip with no reload. -
The WINDOWS shell cannot resize at all, and
WindowChromeis why the code looks like it can.WindowChrome { CaptionHeight = 0, ResizeBorderThickness = 6 }answersWM_NCHITTESTfor the PARENT window, but the WebView2 is a child HWND covering the whole client area, so the mouse never reaches the parent's hit test and the page gets themousedowninstead. Every edge and corner is therefore un-resizable and the 6px band is a reservation nothing can grab — the same shapeMicrosoftEdge/WebView2Feedback#4538reports (a full-window WebView2 underWindowChromecannot be resized; aMarginaround the control is the only thing that makes the border live again), closed as a tracked feature request and folded into#2243, which asks forapp-regionto grow a resize meaning and is still open.#2243also confirmsapp-region: dragis the ONLY non-client behaviour WebView2 exposes, which is why the drag works here and the resize does not. The fix is Gantry'sResizeFrame: the PAGE renders eight thin edge/corner strips with the right cursors and calls a bridge command, and the shell postsWM_NCLBUTTONDOWNwith the matchingHT*code afterReleaseCaptureso Windows runs its own interactive resize. NOT done — it is a shared-client change (a strip per edge on every layout) and this shell cannot be RUN on a macOS host, only compiled.packages/windows/README.mdstates the defect rather than claiming the border works; do not restore that claim without the strips. -
The macOS shell is a native Swift package, and its window chrome is the one part a webview host cannot inherit.
packages/macos(Swift 6 + AppKit + WKWebView, no Xcode project, no third-party deps) is split the waypackages/iosis:Sources/KabmoDesktopholds every rule that can be tested without a screen (Persisted,Store,System,ShellWindow's puredraggedOrigin), andSources/kabmo-desktopis the AppKit app. The SwiftPM product is namedKabmo, notkabmo-desktop, because a process with no bundle reports its executable's file name —swift run kabmo-desktopputkabmo-desktopin the menu bar (measured withNSRunningApplication), andscripts/build-app.shcopies the product toContents/MacOS/Kabmoso the plist, the binary and the menu bar agree. The data directory is~/Library/Application Support/Kabmo, withmigrateLegacyStateDir()movingkabmo-desktop's state on the first launch after the rename (only when the new directory is absent). The drag hook lives insendEvent, notmouseDown— measured: a press inside aWKWebViewnever reachesNSWindow.mouseDown, so amouseDownoverride is dead code that looks correct.sendEventasks the page whether the press landed on[data-drag-region]throughdragRegionSelector, and the follow is manual arithmetic (beginDrag→draggedOrigin(windowOrigin:startMouse:pointer:), a pure function) rather thanperformWindowDragWithEvent:: the native loop reads the physical pointer through an event tap and cannot be driven or tested (AXIsProcessTrusted: falseon a normal machine — measured before, during and after, all identical), while the manual form is asserted byTestsWindowagainst a realShellWindow. Double-click obeysAppleActionOnDoubleClick(DoubleClickAction.current()), the bar carries the system's own right-click menu (barMenu()), andvalidateUserInterfaceItemclaims only close/minimise/zoom/full-screen so an unrelated action cannot be swallowed. The frame's RESIZE BAND is claimed before the page too, and that is why diagonal resizing did nothing.fullSizeContentViewputs the page under the bar, so the page marks its whole top 40px[data-drag-region]— including the 3px strip along the top edge and the band around both top corners thatNSThemeFramereserves for dragging the window's SIZE. Measured through the realShellWindow: a press at(1, H-1),(6, H-6),(W-1, H-1)and(W/2, H-1)all answered "the page says drag handle" and started a window MOVE, so every diagonal resize (both top corners, and the top edge itself) moved the window instead of resizing it. The bottom, left and right edges kept working because the page marks nothing there — which is exactly the reported shape, "diagonal resize does nothing" while the plain edges are fine.frameOwnsPress(at:)is the predicate:contentView.superview.hitTestat the press point, and the answer is the FRAME's when the hit is neither the content view nor inside it. It is deliberately not a hard-coded band thickness — measured on macOS 27 the band is 3px along the top edge, 4px along the bottom and the sides, and 8px into the top-left corner because the close button's own margin is reserved there, so a fixed probe point passes on one macOS and lands in the page on the next.sendEventbreaks out of the claim for a frame press (sosuper.sendEventstarts AppKit's own resize loop), the right-click menu refuses the band the same way, andclaimsBarPresscarries both so the window suite asserts the decision rather than restating its inputs.runResizeBandCasesmeasures where the band ENDS and asserts the header is a drag handle again past it, in both directions — a fix that simply refused every press in the top strip would pass a one-sided case. Pinned byTestsWindowagainst a realShellWindow; the fix was A/B'd, with the three "not claimed as a window drag" cases failing whenframeOwnsPresswas removed. The traffic lights are claimed by the SYSTEM before the page is asked, and that ordering was the bug that made close / minimise / zoom dead. The page marks its whole header[data-drag-region]and reserves its leftmost 76px for the buttons (trafficLightInset), soelementFromPointat a traffic light answers "a drag handle" — the window claimed the press,super.sendEventnever ran, and the button never saw the click, while the same strip still moved the window.sendEventnow testshitsStandardButton(at:)FIRST and breaks out of the claim (so the press passes through to the button). That predicate isstandardWindowButton(_:)for.closeButton/.miniaturizeButton/.zoomButton, converted to window coordinates — the only way to reach them, since they live in the private titlebar container and not incontentView, and their frames are AppKit's to decide. A hidden button is skipped so a window without.closablereserves no dead strip.TestsWindowpins both directions: a press inside each button's own frame is not a drag and reaches the button, and the gap just pasttrafficLightInsetis still a drag (the fix must not turn the reserved strip into dead window). Its own harness had to move: the "blank header" case pressed at x=60, which is INSIDE the close button's frame, so it was asserting the bug as correct behaviour — the page-owned point istrafficLightInset + 24. The Edit menu is what gives the page its clipboard chords, and without it the composer ignores ⌘V. AWKWebViewreceives NO ⌘C/⌘V/⌘X/⌘Z/⌘A unless the app's menu bar declares those key equivalents — the web view is the first responder and does see thekeydown(a page readsmetaKeyandkey === 'v'), but the edit COMMANDS travel through the menu system, so with no item claiming the chord AppKit never asks the responder chain,paste:never runs and the page's ownpasteevent never fires either. The shell built App, File, View and Window and nothing else, which is why the macOS app's composer silently ignored the keyboard's clipboard chords. Measured A/B on a bareWKWebViewagainst the same window with the menu: ⌘V left the field unchanged with nopasteevent versuspaste-proof; ⌘A left the selection4-4versus0-11; ⌘C left the pasteboardnilversus the selected text; ⌘X leftalphain the field versus an emptied field with the text on the pasteboard; ⌘Z/⌘⇧Z did nothing versushi→ empty →hi.EditMenu.swiftholds the row table (editMenuItems) and the gate (editMenuHandles), and four details are load-bearing because each fails silently:undo:/redo:have no AppKit-declared selector (they areNSResponder's informal protocol, absent from every public header) so they are spelled as strings whileNSText'scut:/copy:/paste:/delete:/selectAll:are used as selectors so a typo is a compile error rather than a dead row;Redocarries⌘⇧ZEXPLICITLY, because a menu item's default mask is.commandandkeyEquivalent: "z"alone collides with Undo and makes the row unreachable;ShellWindow.validateUserInterfaceItemmust allow the rows — it answeredfalsefor every action it did not name itself, andundo:/redo:resolve against the WINDOW (measured:NSApp.target(forAction:)answersNSWindowfor those two andWKWebViewfor the other five) whose own default answer isfalse, so the menu was built, the chords were declared, and ⌘Z still did nothing; and the chords need a KEY window, so a suite driving them mustNSApp.activatefirst or the key-equivalent pass never runs.TestsWindow/main.swiftdrives all of it into a realWKWebView, and its undo case runs FIRST because WebKit keeps ONE undo stack per document — run after the cut case, ⌘Z undid the cut and the field came back ascut-me(measured), which reads as "undo is broken" when the ordering was what was wrong. With the menu removed, 8 of those checks fail. Quit was slow for three independent reasons, and each was measured rather than guessed. (1)applicationWillTerminateran aTaskand thenDispatchSemaphore.waited on the MAIN thread — andNSApplicationDelegatemethods are@MainActor, so the task that would signal needed the very actor blocked in the wait: the app beachballed for the full 6 s timeout on EVERY quit. It is nowapplicationShouldTerminate+.terminateLater, AppKit's own deferral, with the work detached andreply(toApplicationShouldTerminate:)ending the quit. (2) The spawned child inherited a BLOCKED SIGTERM:posix_spawncopies the caller's signal MASK, andPOSIX_SPAWN_SETSIGDEFresets only the DISPOSITION — the app blocks SIGTERM, sokill(-group, SIGTERM)left it pending, the child never died, andkillGroupalways ran its full 40 × 50 ms budget. Verified A/B: with onlySETSIGDEFthe child "died from SIGTERM? false"; addingPOSIX_SPAWN_SETSIGMASKwith an empty set, "true". 2.27 s → 0.058 s per server. (3) A zombie answered "alive":isAlivepolledkill(pid, 0), which still answers 0 for an exited-but-unreaped child, so the grace loop never saw it go. It now useswaitpid(WNOHANG)(which also reaps) and falls back to the signal probe onECHILDfor an adopted pid. The escalation is also COLLECTED now, not just sent — returning straight afterSIGKILLleft the child a zombie for the next caller.Tests/main.swiftmeasures all three (an exited child is not alive; a well-behaved child is released in under 0.5 s; a SIGTERM-ignoring child is still killed) and each case fails with its fix reverted. Linux had the same two shutdown faults, and one more.is_alivepolledkill(pid, 0)(same zombie bug, same fix —waitpid(WNOHANG)); andstop_all()ran on the GTK main loop, freezing the window for the whole grace budget, so it now runs on its own thread withMainContext::invokeposting the quit back (theSupervisormoved fromRctoArcfor that). It does NOT have the mask bug: Rust'sCommandresets the signal mask for the child itself. Windows was already correct on both counts — itsClosedhandler is on the UI thread but every await in the library isConfigureAwait(false), so the continuation cannot queue behind the wait. A bridge command runs ON the GTK loop, so anything that blocks there freezes the window — and a frozen loop cannot rundelete_event, which reads as "the app will not quit".connect_script_message_receivedis delivered on the main thread, andupdate_applyused to do aureqdownload (its own read timeout is 120 s) plus the ELF check and therenameinline: the shell was unresponsive for the whole download and uncloseable while it ran, the same end state macOS reached for a different reason. It is now answered bystart_update(main.rs): everything cheap — the AppImage check, the one-job guard, every refusal — is decided in the same tick so the page is never left waiting on a job that never started, only the blocking half goes to a thread, and the answer returns throughtimeout_add_localbecause the reply script and the window are GTK objects (reply_nowis the one place that evaluates one). A worker that dies without answering still answers the page, and the restart is scheduled from the loop, and ONLY on success:update::planrefuses a build that is not an AppImage before anything is downloaded, andupdate::outcomecarries the reply and the relaunch decision together, because a refused install that restarted would come back as the image this process already runs while the page reports the failure — both pure and pinned inrules/update.rs. The__relaunchmarker and its strip in the bridge reply are gone with the old path.servers_startand the start half ofservers_activatecarry the same budget and are deferred the same way:Deps::startnow SPAWNS (Supervisor::spawn) and the wait issystem::wait_until_ready— address and pid only, which is what makes it safe on a worker thread.ServerStore::starttherefore answers theStartResult(id, address, pid) instead of a(id, url)pair, andactivateanswers(url, Option<pid>): a server that already answered has nothing to wait for, while one this call spawned must be waited for before the window moves. The__awaitmarker carries the worker's inputs (address, pid, port for the log line, and the record to stop), the reply is held until it lands, and a server that never answered is STOPPED before the page is told — it is still a child of this process, and leaving it would make the next Start answer "already starting on that port".rules/store.rspins that a switch needing no start hands back no pid. The reply has to reach AppKit through the main RUN LOOP, not the main actor — and that is why 0.4.2 could not be quit at all.applicationShouldTerminatereturning.terminateLaterputs-[NSApplication _shouldTerminate]into a nested event loop that servicesCFRunLoopPerformBlockbut not the main dispatch queue, which is where Swift's main-actor executor lives: the deferred reply (await MainActor.run { sender.reply(…) }) therefore never ran, the app kept a window it would not close, and every later Quit was answeredcancelagainst a latch that could never be cleared — the reported "after updating the macOS DMG the app does not quit, it has to be killed from Activity Monitor". Measured on the installed 0.4.2: a Quit request was accepted, the process stayed idle, andsampleshowed the main thread parked in_shouldTerminate → nextEventMatchingMask → mach_msgwith no concurrency thread holding a Kabmo frame.TerminateCoordinator(Sources/KabmoDesktop/Terminate.swift) now delivers the answer throughCFRunLoopPerformBlock(CFRunLoopGetMain(), .commonModes)— which that nested loop DOES service — and sendsreplyToApplicationShouldTerminate:through the ObjC runtime, becauseNSApplicationmarks it@MainActorwhile a run-loop block is not andperform(_:with:)cannot carry aBOOL(it passes an object pointer whose low byte read asfalse; measured, and it canceled the quit it was meant to complete). The rebuilt bundle quits in 20–40 ms, three runs. Two further traps are stated in that file because each one silently re-breaks it: the shutdown work must be an actor method, never an injected@escaping () async -> Void(a closure created in the@MainActordelegate is main-actor-isolated, so awaiting it from the detached task hops back to the starved main thread — measured in the window suite: the child task entered, the empty closure never returned, and the task group waited out its whole ceiling), and a second Quit must answer.terminateNowrather than.terminateCancel, becausecancelaborts the pending reply and leaves the latch set for the life of the process.runQuitCasesin the window suite drives the real path —NSApp.terminatewith the coordinator answering, an 8 s watchdog as the assertion, andreply: falseso the suite itself survives. Both test suites are plain executables that exit non-zero, becauseXCTestships with Xcode and this package builds with the Command Line Tools alone:swift run kabmo-desktop-tests(204 checks, no window) andswift run kabmo-desktop-window-tests(a real window and webview). The window suite loads its page ONCE, at top level, and every case drives that document. A load started from insiderunCasesnever finishes on the x64 release runner: measured on run #128, the navigation case'sloadHTMLString(_:baseURL:)sat atestimatedProgress = 0.1withisLoading = truefor its whole 30 s budget while the identical load at top level commits in 0.3 s, so five checks failed on a working web view (the arm64 leg passed with the same code). The same measurement is whyDroppedPathsWindowTestsdrives the page already on screen instead of a secondWKWebView. The suite page therefore carries the navigation case's own elements (#panel,#blank) and is loaded withloadSimulatedRequestathttp://console.test/— a real http origin, because the rule under test compares origins and anabout:blankpage would answer.insidefor a cross-origin subframe even with the delegate that ignorestargetFrame.proveClickCloses()runs LAST for the same reason: it closes the window, and a web view whose window is closed is one WebKit may suspend. Settings › asks the PAGE for its modal, and a reload is not that. Every settings screen is a client-rendered modal, so the shell has nothing native to show — the row's job is to dispatch the one event both layouts already listen for,omp:open-settings(PageEvents.swift,openSettings(in:)). What it used to do was append?settings=1andloadthe URL again, and nothing on the client reads that parameter: the modal never opened while the live document was thrown away — a running turn, the composer draft and the timeline's scroll position with it. The Linux shell had already sent the event, so the contract was known and this shell simply was not using it. The case in the window suite dispatches the SHIPPED script into a real page and asserts the listener fired once, the detail is empty, and the document SURVIVED (documentElement.dataset.probekept), which is the half that fails if the row ever reloads again — verified by restoring the reload, which fails 4 cases including the later typing ones because the page was replaced.release/macos.test.jspins the two silent halves: the row goes through the helper rather than a query parameter, and the name the Swift constant declares is the namesettings/Modal.tsxlistens for (a typo either side is a dispatch into the void). -
The macOS shell is released by a version BUMP, not a publish — and
packages/macos/version.propertiesis the ONE place its version is declared.release/macos.jsholds the table (MACOS_SHELL),readVersionName,replaceVersionLineand the watermark; the sharedrelease/release-shells.mjsbumps it (with the other four shells, in one commit) from the same Conventional Commits rules the app uses;release/macos-version.mjsprints it forscripts/build-app.sh, which fillsCFBundleShortVersionStringandCFBundleVersion..github/workflows/publish-macos.ymlis a two-phase reusable body:buildcompiles the package on BOTH architectures (arm64onmacos-15,x64onmacos-15-intel), runs both Swift suites, verifies the version the plist declares, the ad-hoc signature and the binary's ownlipo -archsslice, and uploads oneKabmo-<version>-mac-<arch>.zipper row — andrelease.ymlcalls it asmacos-buildBEFOREapptags, so a Swift error or a plist that disagrees with the properties file stops the release instead of shipping a tag whose release carries no app.macos-appattaches that artifact after the release exists and builds nothing.appneeds: macos-build, so the build is a gate rather than a consequence. The archive is made withditto, neverzip.zip -rstrips the bundle's extended attributes and code signature, and macOS then refuses to launch the extracted app ("damaged") with nothing in the archive to say why; verified by extracting the published shape and re-runningcodesign --verify --deep --strict. There is deliberately no User-Agent token, unlike the Android and iOS shells — but the console DOES offer this app an update. The version comes over the BRIDGE instead: the shell injects__kabmoDesktopbefore the page's first script, anddesktopShellFromIdentityreadsshellVersionfrom it, so the sidebar's offer is decided on the first paint. A UA token would mean every asset request carried a string the bridge already supplies. The reported version must come from the BUNDLE (ShellVersion.current()→CFBundleShortVersionString, whichscripts/build-app.shfills fromversion.properties):App.swiftused to declareshellVersion: "0.1.0"as a literal, so the pipeline bumped the properties file to0.2.0while the running app went on telling the console0.1.0— a comparison against a version that did not exist.release/macos.test.jsasserts both halves (noKabmoMacOStoken, and no literal version inApp.swift). -
tests/ci-gates.test.tsis the contract, asserted on the YAML graph rather than on file text. Every job in a releasing workflow must reach both gate jobs TRANSITIVELY (so a publish job added withoutneedsfails the test rather than shipping), every localuses:must resolve to a file that declaresworkflow_call, everywith:key must be declared by the callee, no gate job may carry anif:, the chainpackages → marketplace → shellsmust hold and every shell build mustneeds: shells(the lockfile and bump ordering, which the transitive check cannot see; the five per-shell bump jobs must be gone and the one commit must stage all five version files), the shell bumps must run and commit BEFOREapk-buildcompiles and BEFOREapptags, the APK must be built before the tag and only attached after it, andpublish.yml's gate jobs must pin therefthey check. Two traps are pinned by its own implementation:needsis a STRING for one dependency and an array for several (spreading the string yields its characters), and the array must be COPIED beforestack.pop()— handing out the parsed array drains the job's ownneedsas the walk consumes it, so the second job through the closure reports a gate it does reach as missing (measured).
@kabmo-labs-bot is a GitHub App plus the workflows in .github/workflows/; it triages every new issue and reviews every pull request. CONTRIBUTING.md is the contributor-facing half of this contract — read it before changing any of these files, because the two must tell the same story.
-
Writes go through the App, never
GITHUB_TOKEN. Every bot job mints an installation token fromBOT_APP_ID+BOT_APP_PRIVATE_KEY(actions/create-github-app-token), so comments and labels come from@kabmo-labs-botand cannot re-trigger a workflow that matches bot comments. Jobs are skipped outsidekabmo-labs/kabmo: a fork run has no App secret. -
Command surface, first line of a comment, exact match:
@<BOT_MENTION> help|review|summarize|triage|reproduce [focus](plus the/oc-reviewalias).helpis answered without a model — it is a fixed string. The mention comes from the repository variableBOT_MENTION(defaultkabmo-bot) rather than a literal, so an App whose slug differs still triggers:bot-config-check.ymlis the one place that reads the App's real slug from its own installation token and reports the value to set. -
The agent is the pinned
ompCLI, run headless..github/scripts/install-omp.showns the version pin (OMP_VERSION);.github/scripts/run-omp-bot.shrunsomp -pwith a persona file, a policy overlay, and the prompt on stdin. The runner needsoven-sh/setup-bun;ompis a Bun program. -
Two provider modes, picked by whether
BOT_API_BASEURLis set. Unset:BOT_MODELis a provider omp already knows andBOT_API_KEYis exported as the env var that provider reads (BOT_API_KEY_ENV, e.g.DEEPSEEK_API_KEY). Set: the model lives behind an OpenAI-compatible gateway, so the script declares a provider for the run from.github/bot/provider-models.ymland passes the key with--api-key. The second mode exists because omp ships no provider for an arbitrary base URL, and because--api-keyoverrides the file's value while amodels.ymlapiKeycannot reference an environment variable ($VARand${VAR}are both literally true strings — verified against a local OpenAI-compatible stub) — so the template carries a placeholder and the real secret never touches the runner's disk. A thinking level (BOT_THINKING) only reaches the provider when the model entry declaresreasoning: true— verified against the stub: without that line--thinkingis accepted and silently dropped, with it a--thinking highrun arrives asreasoning_effort: "high". The template carries the line; a model's declaredeffortsmay never includeoff(the schema rejects it, and omp clampsoffup to the lowest listed effort). Repository settings: secretBOT_API_KEY; variablesBOT_MODEL,BOT_API_BASEURL(optional),BOT_API_KEY_ENV(required only whenBOT_API_BASEURLis unset),BOT_THINKING(optional, defaulthigh),BOT_MENTION(optional, defaultkabmo-bot). The three provider settings are read from either store (vars.X || secrets.X), so a value placed in Secrets still works.BOT_MENTIONmust be a variable: every command trigger is a job condition, and a job condition may readgithub,needs,varsandinputs— neversecrets— so a secret of that name is silently ignored and the default is used instead (bot-config-check.ymlreports exactly that). -
Policy is data, in the
.github/bot/*.ymlpolicy overlays.tools.approval.<tool>: denyplus abash.patternsallowlist ending in- match: "*"/denygives a deny-by-default session; the reviewer cannot edit a file or run anything butgh,git,rg,ls,cat. Never writeapproval: prompt: there is no UI on a runner, so a prompt is a rejected call that reads to the model as a broken tool. -
Procedure is versioned with the repository, in
.omp/skills/{pr-review,issue-intake}/SKILL.md, read by the agent throughskill://. The persona files (.github/bot/*.persona.md) hold identity, guardrails and the exact output contract; the skills hold the steps. A 25 KB prompt never lives in a workflow. -
Nothing downstream trusts the model.
verify-review-verdict.shre-reads the posted comment from the API, requires the final line to be the marker<!-- omc-review-meta {"head":"…","verdict":"…"} -->, checks that the marker's HEAD equals the requested HEAD and is still the current one, that the human-readable verdict and reviewed-HEAD lines agree, and only then writes onereview:*label. A mismatch fails the job and marksreview:automation-failed; the verdict itself never fails a check. The human-readable checks read values, not decoration (backticks, bold, whitespace): a live run posted a correct review with every backtick stripped on the way to the API, and a gate stricter than the generator turns a finished review into a wasted run — the HEAD must still be named as a complete token, so tolerance applies to formatting and never to content. -
Readiness is a label, not a comment:
review:pending|ready|needs-evidence|blocked|human-required|automation-failed. Exactly one at a time —set-review-status.shis the only writer. Drafts carry none. -
Trust boundary:
pull_request_targetruns with secrets, so the base is what is checked out and the head is fetched as passive git data — never installed, built, or executed. A diff touchingAGENTS.md,CONTRIBUTING.md,.github/{workflows,scripts,bot,ISSUE_TEMPLATE}/**,.github/PULL_REQUEST_TEMPLATE.mdor.omp/skills/**is refused (review:human-required): automation must not clear a change to its own policy. -
Logic lives in
.github/scripts/*.sh, not in YAML. Each script takes arguments and reads its state throughgh, so it can be exercised locally against a stubbedgh; the workflow steps stay thin glue. When adding a gate, add it as a script. -
Never put user content into a
run:block through${{ }}— title, body, comment text and focus go throughenv:and are read as shell variables.run-omp-bot.shpipes the assembled prompt toompon stdin for the same reason: no interpolation into shell text, no argument-quoting hazard. - Editing any of these files is a
ci-type change; the review-policy paths above mean the pull request that changes them will be markedreview:human-requiredand must be read by a human.
Using Kabmo
How it is built
- Architecture
- Runtime and toolchain
- App shell and layout
- Chat stream and tools
- omp engine and settings
- Plugins, skills and automation
- Desktop integration
- Workspace panels
- Providers
- Harnesses
- Tool panels
Shipping it
History