dsh-github-copilot 0.4.0-alpha.18 → 0.4.0-alpha.20

package/docs/npm-distribution.md

@@ -25,27 +25,24 @@ through the normal reviewed PR path. Version changes include package.json,
 deployment-baseline.json and both README URLs; `publishConfig.tag` must agree
 with the channel. Do not silently rename a taken package.
 
-## First package bootstrap is a maintainer operation
-
-The normal main pipeline publishes the GitHub Release first, then requires npm
-publication. Until bootstrap/trusted publishing is configured, the npm step
-fails explicitly and the workflow is **not fully delivered**. This is intentional,
-not a successful skipped step. The already published GitHub archive is retained.
-
-1. From the verified immutable Release, obtain its original versioned tarball
-   and `SHA256SUMS`. Verify the annotated tag/commit, Release state, asset digest,
-   archive contents and SHA-256. Do not repack or edit this archive.
-2. In an approved environment, the authorized maintainer verifies `npm whoami`
-   is the intended account (`cloga`) and performs the first ordinary
-   `npm publish <original-release.tgz> --access public --tag alpha --ignore-scripts --registry=https://registry.npmjs.org/`
-   with interactive 2FA or explicitly authorized legitimate publishing
-   credentials. `<original-release.tgz>` is the exact downloaded real artifact,
-   not a directory or placeholder. Do not print, copy or commit credentials, or
-   weaken 2FA to make this succeed.
-3. Read back the exact npm version and compare `dist.integrity` with the
-   archive's SHA-512 SRI. Configure trusted publishing, then rerun the failed
-   CI release job on its original revision. It recovers the same bytes and
-   verifies the existing npm version without another publish.
+## Initial package publication is complete
+
+The initial `dsh-github-copilot@0.4.0-alpha.18` package was published from the
+immutable `v0.4.0-alpha.18` GitHub Release archive. The public registry version,
+SHA-512 SRI, `alpha` tag, tarball size and SHA-256 were independently verified
+against those original Release bytes. The one-time workflow, token-authenticated
+bootstrap script and their focused tests have therefore been removed. No normal
+release workflow references `NPM_TOKEN`; removing any now-unused repository
+secret remains a separate explicit maintainer operation.
+
+The successful publish was not immediately visible to a read performed about
+four seconds later, so that workflow run ended as a failure even though the
+package and tag subsequently converged. Treat this as an uncertain write, not
+permission to publish again. npm registry package metadata and dist-tags are
+eventually consistent: after any successful or uncertain publish command, wait
+for the exact version to become observable, verify `dist.integrity` and the
+non-decreasing channel tag, then rerun the normal pipeline to reconcile
+read-only. Never retry a publish merely because immediate readback is stale.
 
 **`npm stage publish` cannot bootstrap a nonexistent package.** The
 [official npm stage prerequisites](https://docs.npmjs.com/cli/v11/commands/npm-stage/)
@@ -104,7 +101,8 @@ The npm step reads package/version state before writing. Only E404 means
 absence; auth, TLS, timeout, malformed metadata and registry failures stop
 delivery. An existing exact version is accepted only with matching SHA-512 SRI
 and a channel tag at that version or a newer one. Conflicting bytes fail closed.
-An uncertain write is not retried in-process; rerun the workflow to reconcile.
+An uncertain write is not retried in-process. Allow registry visibility to
+converge, then rerun the workflow to reconcile the exact existing version.
 A matching version with an older/missing tag requires maintainer review; the
 workflow does not silently repair it with separate dist-tag writes.
 
@@ -120,15 +118,71 @@ There is no historical bulk backfill and no silent npm opt-out.
 
 ## Installation preflight still applies
 
-After both channels are verified, official Desktop accepts the exact
-`dsh-github-copilot@<version>` npm spec in its package manager. It does not accept
-the Release URL or local tarball in that UI. Follow the existing README
-`scripts/check-search-composition.mjs` preflight before changing configuration;
-the script remains in the package. A successful package lookup or install does
-not prove runtime activation or a successful Copilot request.
-
-For separately managed CLI profiles only, retain the required `--profile` on
-`dsh plugin` commands. Never use the CLI to write a reserved Desktop-managed
-profile, copy into node_modules, patch Core or restart active Sessions without
-their separate approvals. Installed-on-disk and loaded-runtime evidence remain
-distinct.
+The native Desktop package manager remains the preferred interactive entry
+point when its registry access is permitted and available. After npm publication
+is verified, it accepts the exact `dsh-github-copilot@<version>` npm spec, not a
+Release URL or local tarball in that UI. This UI input restriction is not a
+blanket prohibition on maintaining the same profile through the supported CLI.
+Controlled CLI maintenance is also supported for Desktop-managed profiles under
+the checklist below. Neither entry point replaces the package's required
+`scripts/check-search-composition.mjs` preflight. A package lookup, preflight or
+successful installation is not proof of runtime activation or a model call.
+
+## Controlled offline CLI maintenance
+
+This path installs this package's prebuilt, verified Release without requiring
+access to a blocked npm registry. It is not permission to bypass organizational registry restrictions:
+use only artifacts obtained through organizationally approved sources and
+already available dependency caches. A registry ban remains in force; offline
+installation does not repair TLS or prove that npm publication is healthy. The
+dual-channel **publication** policy above is unchanged.
+
+1. Obtain explicit installation approval for the exact version and profile.
+   Resolve the actual DSH CLI, install anchor, `DSH_HOME` and profile directory;
+   do not assume a shell shim points to the Desktop's current installation.
+2. Verify the original Release tarball with an independently trusted SHA-256,
+   its package name/version and safe archive layout. Do not substitute a local
+   build or repack an existing immutable Release. Extract only the verified
+   artifact before executing its packaged preflight.
+3. Run `scripts/check-search-composition.mjs` against that exact profile, home
+   and install anchor, including any extra startup patches. Require
+   `supported: true`; unknown, conflicting or unsupported composition is a stop,
+   not permission to remove guards or rewrite the profile.
+4. Keep one writer: do not run Desktop package updates and CLI installation
+   concurrently. Take a private backup of installation metadata (package.json,
+   lockfile, bundle/patch configuration and relevant package-manager settings),
+   record the current version, and retain a verified rollback artifact.
+   Do not copy credential stores, `.env` files or browser storage. If ensuring
+   exclusive maintenance requires stopping the Host, obtain separate approval.
+5. Invoke the supported DSH CLI with an absolute path to the verified archive:
+
+   ```sh
+   dsh plugin --profile web add /absolute/path/to/verified-release.tgz --offline --ignore-scripts
+   ```
+
+   Replace `web` and the archive path with the approved targets. `--offline`
+   requires the existing cache; `--ignore-scripts` prevents package lifecycle
+   scripts from creating a second, uncontrolled installation/network path. If
+   the cache is incomplete or a dependency requires a new build, stop and report
+   the missing requirement. Do not silently remove these flags, change registry,
+   add a VPN/proxy/mirror, or fetch blocked dependencies through another channel.
+   Keep TLS verification enabled. Actual platform permission/approval refusals
+   remain authoritative; this procedure does not override them.
+6. Check the exit result and read back the installed version, lock entry and
+   package files against the verified archive. Re-run the composition preflight
+   and an appropriate import-only smoke check without activating the plugin.
+   Inspect all metadata differences: the CLI reconciles `dsh.profile.bundles`
+   and may add unrelated installed bundles. Preserve unrelated settings; stop
+   for review on unexpected changes and revert only changes proven to belong
+   to this operation, never overwrite later user edits with a whole backup.
+   Use the package manager, not manual copying into node_modules or Core patches.
+7. Report the installed version, checksum, backup and evidence limits. Obtain
+   separate restart approval before interrupting the Host or active Sessions.
+   Installed-on-disk and loaded-runtime are separate states: after an approved
+   restart, verify the loaded build and the intended behavior independently.
+
+If installation fails, inspect the actual installed state before retrying or
+rolling back; a failed command is not proof that nothing changed. A rollback
+also needs reviewed, narrowly scoped metadata/dependency restoration. This
+documentation change does not rewrite installed or published historical docs,
+change machine-wide registry policy, or grant blanket approval for future updates.

package/docs/session-search-routing.md

@@ -48,6 +48,6 @@ The added regressions cover silent expiry/replacement, native final assertions,
 
 1. Complete the full verification gate and update deployment/agent evidence inventories, public export smoke and both READMEs.
 2. Add end-to-end coverage of the main router's managed metadata, fallback credentials/options, cancellations during discovery/fallback, mixed multi-query provenance, and complete unload/reload behavior.
-3. Run retained exact Core-baseline fixtures, not only the development artifact. Do not infer seven-pin runtime compatibility from type checks.
+3. Run retained exact Core-baseline fixtures, not only the development artifact. Do not infer eight-pin runtime compatibility from type checks.
 4. Align the new package version, release metadata and package/archive tests.
 5. Run bounded live Copilot hosted-search and permitted-fallback acceptance separately. A successful chat request does not prove hosted search. No live profile installation, global search selection change or restart has occurred for this work.