kylon-cli 0.7.5-next.1059 → 0.7.5-next.1070

package/README.md

@@ -427,17 +427,16 @@ currently published target plus a 0-100% stable per-computer rollout for
 automatic updates. A missing, disabled, mismatched, or 0% policy sends no
 automatic request; manual upgrades still resolve the dist-tag normally.
 
-Every merge to `develop` publishes a prerelease to the `next` tag
-(`.github/workflows/cli-publish.yml`). A production deployment dispatched from
-`main` automatically invokes the same workflow in stable mode and publishes the
-exact `packages/cli/package.json` version to `latest`; it is idempotent when that
-version already exists. A CLI change intended for production must therefore bump
-the package version before the production deploy, or the stable publish will
-correctly no-op and `latest` will remain on the existing build.
-
-A matching `kylon-cli-vX.Y.Z` tag is an alternative supported stable-release
-trigger, not a required extra step after a production deploy. Do not run
-`npm publish` ad hoc: both paths use the CI workflow and its OIDC publisher.
+Qualifying merges to `develop` publish prereleases to `next`
+(`.github/workflows/cli-publish.yml`). Stable publication is optional: request
+`publish_cli=true` on a production Deploy from `main`, or label its merged main
+PR `release:cli`. After the Deploy finishes successfully, a separate workflow
+runs fresh full CLI qualification and publishes the exact package version to
+`latest`. A standalone stable dispatch runs from current `main` and requires
+already-deployed services. Bump the package version before a stable release.
+
+Stable tags are release records, not publication triggers. Do not run
+`npm publish` ad hoc: both stable entry points use CI and its OIDC publisher.
 Development installs `@next` and production installs `@latest`, so each
 environment tracks its own release train.
 
@@ -774,6 +773,31 @@ instead of waiting out inactivity timeouts and heartbeat intervals.
   without the advertisement fails over-budget assignments with a named error
   instead of receiving flags it would misparse.
 
+## macOS startup logs and external config volumes
+
+The macOS service writes startup stdout and stderr to
+`~/Library/Logs/KylonGateway/launchd.stdout.log` and `launchd.stderr.log`.
+These paths are independent of `~/.kylon` and `XDG_CONFIG_HOME`: launchd must
+open its output files before Node can request access to a removable volume.
+Install, upgrade, repair, and desktop first-time service creation use the same
+paths and prepare the log directory with mode `0700` and files with `0600`.
+Oversized startup files rotate at service installation/repair (10 MiB, three
+files per stream). Existing daemon logs are retained at `<configDir>/gateway.log`.
+Node and provider tools may still need macOS permission to access external data.
+
+`kylon gateway status` shows both locations, including when the daemon could
+not start. Its JSON keeps `daemon.log_path` for compatibility and adds
+`daemon.startup_log_paths` on macOS. Upgrade failure guidance reads recent
+errors from both daemon and startup stderr logs.
+
+`kylon diagnose` and its upload collect both kinds of logs. The same collector
+serves server-requested error diagnostics; self-diagnosis also sees the current
+startup tails. Raw startup output is redacted at collection time, leaf symlinks
+are not followed, and startup tails are capped at 1 MiB per file (256 KiB for a
+scoped error bundle). Missing logs do not prevent collecting other evidence.
+Full bundles keep three startup files per stream; scoped bundles keep two.
+Linux and Windows retain their existing log paths.
+
 ## Remote diagnostics
 
 The CLI reports to the server through one channel (`src/lib/telemetry.ts`):
@@ -1094,9 +1118,9 @@ API server is the security boundary.
 The CLI ships via **npm dist-tags** — there is no server-side version policy.
 `cli-verify.yml` validates on PRs and pushes; `cli-publish.yml` publishes via
 OIDC (no token): a prerelease to the `next` tag on every qualifying merge to
-`develop`, and the package version to `latest` when the production deploy runs
-from `main`. A matching `kylon-cli-vX.Y.Z` tag can also publish that stable
-version. Development installs `@next`; production installs `@latest`.
+`develop`, and an optionally requested stable release from current `main` to
+`latest`, after the web/server deploy and fresh complete CLI qualification.
+Development installs `@next`; production installs `@latest`.
 
 ### Versioning
 
@@ -1111,30 +1135,26 @@ Use explicit semver in `packages/cli/package.json`:
 Prerelease builds are versioned `<package-version>-next.<run>` automatically by
 `cli-publish.yml`. Stable mode publishes the exact package version and skips
 idempotently if npm already has it. Bump `packages/cli/package.json` whenever a
-new production CLI build must be published; otherwise the production deploy
-will intentionally leave `latest` unchanged.
+new production CLI build must be published. Service deployment alone leaves
+`latest` unchanged.
 
 ### Publishing
 
 - **Prerelease (automatic):** every merge to `develop` touching the CLI publishes
   `<package-version>-next.<run>` to the `next` tag via `cli-publish.yml` (OIDC, no
   `NPM_TOKEN`). dev tracks this tag, so dev always dogfoods the newest build.
-- **Stable (automatic with a production deploy):** a production deployment
-  dispatched from `main` calls `cli-publish.yml` in stable mode. It publishes
-  the package version only when that exact version is absent from npm. CLI
-  changes therefore need a package-version bump before the production deploy.
-- **Stable tag (alternative):** after bumping the package version, a matching
-  tag on `main` invokes the same stable workflow directly:
-
-  ```bash
-  git pull
-  git tag kylon-cli-v0.1.1
-  git push origin kylon-cli-v0.1.1   # cli-publish.yml publishes it to `latest`
-  npm view kylon-cli dist-tags        # verify
-  ```
-
-Do not `npm publish` ad hoc: production deploys and release tags both go through
-the workflow so the OIDC provenance path is exercised end to end.
+- **Stable after services (optional):** set `publish_cli=true` on a production
+  `deploy.yml` dispatch from `main`, or add `release:cli` to the merged main PR.
+  `cli-post-deploy.yml` waits for that Deploy's successful completion and starts
+  the independent test/verify/publish task. Default service deploys skip it.
+- **Stable standalone:** dispatch `cli-publish.yml` from `main` with
+  `release_channel=stable`. It verifies the current main commit came through a merged main
+  PR and that its service changes have deployed. CLI-only changes can follow
+  the already-deployed ancestor. Both stable paths run full provider E2E and
+  platform verification; prior PR CI evidence does not replace fresh proof.
+
+Do not `npm publish` ad hoc: use the stable workflow and its OIDC provenance.
+Pushing a version tag alone does not publish.
 
 ### Rollback
 
@@ -1153,6 +1173,47 @@ direction guard keeps a newer installed bundle over an older invoked copy, and
 `kylon upgrade` reports such a host as already current — so the way back for
 those hosts is publishing a fixed, higher version. Do not `npm unpublish`.
 
+### Server compatibility without a CLI release
+
+Service-only releases do not run the complete provider E2E matrix. They keep
+two cheaper checks in CI:
+
+- `cli-service-compat-contract.test.ts` sends independently versioned 0.7.4
+  request templates through the candidate API's real computer-key auth,
+  connection fence, task leases and reply persistence. The templates in
+  `scripts/ci/contracts/kylon-0.7.4.json` intentionally omit newer optional
+  capability fields. Keep this compatibility floor fixed; a new required field
+  must remain compatible with it rather than updating both sides of the test.
+- For backend, shared, CLI, root build or unclassified changes, the reusable
+  `CLI service compatibility` workflow downloads the current production stable
+  CLI, checks both public installer versions against npm `latest`, freezes its
+  exact version/integrity, and runs its foreground daemon against this commit's
+  local API with isolated PostgreSQL/Redis. A deterministic Claude process
+  supplies tool/text/result events without model calls or provider credentials.
+  The workflow verifies completed task/message persistence and uploads the
+  candidate SHA, package digest and executed-test report. Missing or skipped
+  cases fail the existing required `Tests` context. Display-only web/admin,
+  desktop/mobile, documentation and Grafana configuration changes skip this
+  extra smoke; unknown paths and missing diff history run it conservatively.
+
+The contract test also participates in normal affected-code Vitest selection.
+The smoke is excluded from that suite to avoid downloading/running a second
+client for every unrelated test run. Run both locally, **sequentially** (database
+preparation rebuilds the worktree's isolated schema):
+
+```sh
+node scripts/ci/prepare-cli-service-compat.mjs /tmp/cli-compat-stable
+CLI_COMPAT_PACKAGE_DIR=/tmp/cli-compat-stable bash scripts/test-local.sh --full -- --config scripts/ci/vitest-cli-service-compat.config.ts
+```
+
+This is a pre-merge protocol gate, not production/browser login evidence or
+real-provider E2E. Direct hotfix/patch deployment outside the normal PR gate
+must run `cli-service-compat.yml` manually on the target ref and check its SHA;
+the workflow neither publishes nor deploys. Major protocol changes can still
+request `external-agent:full`. Stable CLI publication always runs fresh full
+provider/platform qualification after the service deployment, independently
+of these cheap checks.
+
 ### Gemini CLI
 
 Install stable Gemini CLI 0.58.0 or newer with

package/dist/kylon-bundle.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.7.5-next.1059",
-  "fingerprint": "68952b8b82bc6d300aec1f9287cf1cd02f315e085c1aba83a434ec54f22ed1c9",
-  "source_commit": "437de562152fea4edfac4b68c9be73cc10d19aab"
+  "version": "0.7.5-next.1070",
+  "fingerprint": "1668173106e535e96464f7848fcb01598db7b56e181bcb2ef4b7172e95c1fbfe",
+  "source_commit": "426e8cfe32c12574e2e083adf5118b4066dbc125"
 }