From 4f94dad272d6bba8a3fd4abf61bbabec8b9a3d93 Mon Sep 17 00:00:00 2001 From: anuzzolilli-oss Date: Mon, 16 Nov 2026 13:32:02 -0500 Subject: [PATCH 1/3] docs: tie deploy tooling to steps and state where the kept script differs (#78) Follow-up to #74/#77. Fixes the parts of the deploy procedure that do not depend on the open cutover-order decision recorded in #78: - name the kept iso-test/fold-test checks in step 1 and point it at the build recipe in step 3 - say where live-entry.ts and build.mjs live and how the build is run - resolve step 5's contradiction about which launcher defaults change - separate the in-cutover rollback from Rollback-MasterDeploy.ps1 and define step 10 on the rollback path - cite the receipt's masterBackupRoot for the tooling, and describe Rollback-TunedLiveProxy.ps1 as the deeper pre-tuning rollback - record 4b6687bc-live in the superseded history - remove the step 9 en/zh drift Steps 6-9 are not rewritten. The page now states what Deploy-Master.ps1 does at cutover and that it differs from those steps. Assisted-by: Cindy (https://cindy.app) --- docs/cindy-project.md | 2 +- docs/cindy-project.zh-CN.md | 2 +- reference/cindy-project.md | 14 ++++++++------ reference/cindy-project.zh-CN.md | 16 +++++++++------- 4 files changed, 19 insertions(+), 15 deletions(-) diff --git a/docs/cindy-project.md b/docs/cindy-project.md index 60485b77f0..357b1c192f 100644 --- a/docs/cindy-project.md +++ b/docs/cindy-project.md @@ -25,7 +25,7 @@ The live proxy runs from a separate release directory under `%APPDATA%\CindyGlob As verified on 2026-11-16 from the deployment receipt `%APPDATA%\CindyGlobal\billion-context-proxy\tuned-deployment.json`, the live build is `d4aad618-live`, version `0.1.213`, built from source SHA `d4aad6189a7456059b12c7333662f499c633ca0c` — the merge commit of PR [#73](https://github.com/anuzzolilli-oss/billion-context/pull/73) on `master`. It was deployed on 2026-11-14, and the rollback backup for that cutover is `%APPDATA%\CindyGlobal\billion-context-proxy\backups\before-master-20261114-214204`. Treat these as a dated deployment snapshot: re-check the live manifest and this receipt before any future operation. -Superseded history, kept only as evidence: the 2026-11-08 snapshot recorded live build `51a1cdbf-live` from reviewed source `51a1cdbf4e732bfe9cedae73aec8aee53ec20599`, whose Git tree matched merged PR [#1](https://github.com/anuzzolilli-oss/billion-context/pull/1), merge commit `d6573a0881feb6102a3353e50060d07bf26099d9`. That state no longer describes the live service. +Superseded history, kept only as evidence: the 2026-11-08 snapshot recorded live build `51a1cdbf-live` from reviewed source `51a1cdbf4e732bfe9cedae73aec8aee53ec20599`, whose Git tree matched merged PR [#1](https://github.com/anuzzolilli-oss/billion-context/pull/1), merge commit `d6573a0881feb6102a3353e50060d07bf26099d9`. That state no longer describes the live service. Between the two, `4b6687bc-live` (source `4b6687bc81400026cf6e32c07357e0a02b736791`) was live briefly on 2026-11-14: the receipt records it as the previous build, and the backup for its cutover is `%APPDATA%\CindyGlobal\billion-context-proxy\backups\before-master-20261114-191918`. ### Live OmniRoute routing — verified 2026-11-15 diff --git a/docs/cindy-project.zh-CN.md b/docs/cindy-project.zh-CN.md index 0fcffc4a69..fc07a9b24d 100644 --- a/docs/cindy-project.zh-CN.md +++ b/docs/cindy-project.zh-CN.md @@ -25,7 +25,7 @@ 2026-11-16 依据部署回执 `%APPDATA%\CindyGlobal\billion-context-proxy\tuned-deployment.json` 验证:运行版本为 `d4aad618-live`,版本号 `0.1.213`,构建自源码 SHA `d4aad6189a7456059b12c7333662f499c633ca0c`——即 `master` 上 PR [#73](https://github.com/anuzzolilli-oss/billion-context/pull/73) 的合并提交。部署时间为 2026-11-14,该次切换的回滚备份位于 `%APPDATA%\CindyGlobal\billion-context-proxy\backups\before-master-20261114-214204`。这仍是带日期的部署快照:后续任何操作前须重新核对运行 manifest 与该回执。 -仅作证据保留的已被取代的历史:2026-11-08 快照记录的运行版本为 `51a1cdbf-live`,对应已评审源码 `51a1cdbf4e732bfe9cedae73aec8aee53ec20599`,其 Git tree 与已合并的 PR [#1](https://github.com/anuzzolilli-oss/billion-context/pull/1) 相同,合并提交为 `d6573a0881feb6102a3353e50060d07bf26099d9`。该状态已不再描述运行中的服务。 +仅作证据保留的已被取代的历史:2026-11-08 快照记录的运行版本为 `51a1cdbf-live`,对应已评审源码 `51a1cdbf4e732bfe9cedae73aec8aee53ec20599`,其 Git tree 与已合并的 PR [#1](https://github.com/anuzzolilli-oss/billion-context/pull/1) 相同,合并提交为 `d6573a0881feb6102a3353e50060d07bf26099d9`。该状态已不再描述运行中的服务。两者之间,`4b6687bc-live`(源码 `4b6687bc81400026cf6e32c07357e0a02b736791`)曾在 2026-11-14 短暂运行:回执将其记录为上一版本,该次切换的备份位于 `%APPDATA%\CindyGlobal\billion-context-proxy\backups\before-master-20261114-191918`。 ### 运行中的 OmniRoute 路由——2026-11-15 已验证 diff --git a/reference/cindy-project.md b/reference/cindy-project.md index 6e924bc219..7260b9d44e 100644 --- a/reference/cindy-project.md +++ b/reference/cindy-project.md @@ -84,15 +84,17 @@ The receipt identifies the active release, prior release, bundle hash and backup ## Deploy only with an explicit request -1. Pin the human-merged, reviewed source SHA and check the exact-head CI/review results. Build a separate candidate artifact and record its hash and any local runtime wrapper. Test that exact artifact in an isolated process using generated data and a loopback upstream. +1. Pin the human-merged, reviewed source SHA and check the exact-head CI/review results. Build a separate candidate artifact with the recipe in step 3 and record its hash and any local runtime wrapper. Test that exact artifact in an isolated process using generated data and a loopback upstream: the kept `iso-test.mjs` checks boot, identity and forwarding, and the kept `fold-test.mjs` checks folding and retrieval. Both start the bundle on their own port with a copy of the live config and never use the live port. 2. Verify the existing supervisor, configuration hash, listener PID/process identity and idle state. Prepare a new release directory and back up the supervisor and deployment receipt. Preserve authentication, settings, originals and the scheduled task's sign-in/recovery ownership. -3. Build the live bundle from the small local start-up wrapper `src/live-entry.ts` with the kept esbuild script `build.mjs`, not from the standard CLI entry; building the standard CLI alone does not capture this deployment's runtime policy. The wrapper requires an explicit `--port` (it rejects a non-integer value and ports below 1024 or above 65535), then calls `startServer({ ...loadOptions(), host: "127.0.0.1", port, passthrough: false, autoUpdate: false, autoRestartOnUpdate: false }, { boundedMaintenance: { timeoutMs: 15000, maxTokens: 1024 } })` and logs the enabled bounded maintenance. `build.mjs` bundles `src/live-entry.ts` → `out/dist/index.mjs` (bundle/esm/node20, alias `@earendil-works/pi-coding-agent` → `src/agent/pi-host-stub.ts`, external `jimp, mysql2, mysql2/promise, bufferutil, utf-8-validate`, createRequire banner) and writes `out/dist/build-info.json` with `sourceCommit`, `bundleSha256`, `commit` (the first 8 chars plus `-live`) and `localPatchSha256`; record those hashes in the receipt. +3. Build the live bundle from the small local start-up wrapper `live-entry.ts` with the kept esbuild script `build.mjs`, not from the standard CLI entry; building the standard CLI alone does not capture this deployment's runtime policy. Neither file is in the repository: both are in the kept tooling directory named below. Copy the wrapper to `src/live-entry.ts` in a checkout of the pinned source SHA and run `build.mjs` from that checkout's root with the full source SHA as its argument; do not commit the copied files. The wrapper requires an explicit `--port` (it rejects a non-integer value and ports below 1024 or above 65535), then calls `startServer({ ...loadOptions(), host: "127.0.0.1", port, passthrough: false, autoUpdate: false, autoRestartOnUpdate: false }, { boundedMaintenance: { timeoutMs: 15000, maxTokens: 1024 } })` and logs the enabled bounded maintenance. `build.mjs` bundles `src/live-entry.ts` → `out/dist/index.mjs` (bundle/esm/node20, alias `@earendil-works/pi-coding-agent` → `src/agent/pi-host-stub.ts`, external `jimp, mysql2, mysql2/promise, bufferutil, utf-8-validate`, createRequire banner) and writes `out/dist/build-info.json` with `sourceCommit`, `bundleSha256`, `commit` (the first 8 chars plus `-live`) and `localPatchSha256`; record those hashes in the receipt. The candidate folder handed to the cutover holds `dist\index.mjs`, `dist\build-info.json`, `package.json` and `LICENSE`. 4. Stop the supervisor before editing the launcher, and create `maintenance.inhibit` in the runtime root, which suppresses supervisor adoption, start and restart; a monitored child is left running while inhibited. Editing launcher defaults under a live supervisor is unsafe: adoption is by PID plus process creation time, rechecked after a handle is held, and one supervisor per installation is held by an OS-exclusive lock on `supervisor.lock`, so a second launch exits 0 immediately. The inhibit is temporary: step 9 removes it. -5. Change only the existing proxy's release path. The launcher's `ProxyPath`, `ExpectedVersion` and `ExpectedCommit` defaults must be changed to match the new release, otherwise the supervisor fails closed. Verified defaults for the current release are `ProxyPath` = `...\releases\master-d4aad618\dist\index.mjs`, `ExpectedVersion` = `0.1.213`, `ExpectedCommit` = `d4aad618-live`, alongside `Port` = `8787`, `NodePath` = `C:\Program Files\nodejs\node.exe`, `RestartDelaySeconds` 5, `PollSeconds` 5, `HeartbeatSeconds` 15 and a `-ReportOnly` switch. +5. Change only the launcher defaults that identify the release, and nothing else in the launcher: `ProxyPath` and `ExpectedCommit`, plus `ExpectedVersion` when the version changes. They must match the new release, otherwise the supervisor fails closed. The kept `Deploy-Master.ps1` rewrites exactly the `ProxyPath` and `ExpectedCommit` lines and stops if its edit would touch any other line, so it does not cover a version change. Verified defaults for the current release are `ProxyPath` = `...\releases\master-d4aad618\dist\index.mjs`, `ExpectedVersion` = `0.1.213`, `ExpectedCommit` = `d4aad618-live`, alongside `Port` = `8787`, `NodePath` = `C:\Program Files\nodejs\node.exe`, `RestartDelaySeconds` 5, `PollSeconds` 5, `HeartbeatSeconds` 15 and a `-ReportOnly` switch. 6. Expect the supervisor to fail closed on a foreign or unverified listener, unreadable/booting/mismatched health, a matching process that is not listening, missing executables, and inspection errors or timeouts: nothing is killed and nothing is started, and state is rechecked every `PollSeconds` and logged only when it changes. Restart only that proxy after active requests drain. On startup failure, take the rollback branch in step 8 rather than restarting supervision. 7. Check the manifest's source identity, single-listener ownership and unchanged configuration hash. Exercise request forwarding, actual folding, exact original text/image retrieval and session-scoped checker logs. Use one small authenticated provider request when authorized. -8. If the canary fails, roll back while supervision is still stopped and inhibited: restore the saved launcher and receipt, restore the previous release, restart that release and repeat the step 7 checks against it, then report the failure. Editing launcher defaults for the rollback under a live supervisor is unsafe for the same reason as in step 4, and the launcher still carries the candidate's release defaults, so the supervisor can fail closed on the restored listener for the reasons in steps 5 and 6. Complete this branch before leaving maintenance. +8. If the canary fails, roll back while supervision is still stopped and inhibited: restore the saved launcher, restore the receipts if they were already rewritten, restore the previous release, restart that release and repeat the step 7 checks against it, then report the failure. Editing launcher defaults for the rollback under a live supervisor is unsafe for the same reason as in step 4, and the launcher still carries the candidate's release defaults, so the supervisor can fail closed on the restored listener for the reasons in steps 5 and 6. Complete this branch before leaving maintenance. 9. Leave maintenance once the release that is to stay live has passed its checks, on the success path and the rollback path alike: remove `maintenance.inhibit` and restart the supervisor through its scheduled task. While that file exists the supervisor refuses adoption, start and restart, so a deployment that stops at the canary leaves the proxy running unsupervised — a manually started proxy can pass every check and still have no automatic adoption or restart. Verify the supervisor then reports the release now live, candidate or restored: its `supervisor-status.json` state, the expected version and commit, and the listener PID it adopted. -10. Finalize the deployment receipt and report the deployed SHA, results and rollback location. A local proxy deployment does not publish npm packages or update the hosting Cindy application. +10. On the success path, finalize the deployment receipt and report the deployed SHA, results and rollback location. On the rollback path nothing was deployed: confirm the receipts describe the restored release, and report the failure, the release left live and the backup location. A local proxy deployment does not publish npm packages or update the hosting Cindy application. -Deployment tooling from the initial repair is kept under `%APPDATA%\CindyGlobal\billion-context-proxy\backups\before-master-20261114-191918\tooling\`, containing exactly `Deploy-Master.ps1`, `build.mjs`, `fold-test.mjs`, `iso-test.mjs` and `live-entry.ts`, with the rollback script `Rollback-MasterDeploy.ps1` beside them; that backup root also holds `Start-BillionContextProxy.ps1`, `proxy.identity.json`, `supervision-receipt.json`, `supervisor-status.json` and `tuned-deployment.json`. The live launcher is `Start-BillionContextProxy.ps1` in the runtime root, and `Rollback-TunedLiveProxy.ps1` in the same root rolls that launcher back. Inspect the kept tooling before reuse: it contains pinned build hashes and previous-build assumptions. Do not execute an old installer against a different current release without rebuilding its identity and rollback checks. +Each master cutover keeps its tooling in its own backup: the `tooling\` directory under the backup root that the deployment receipt `tuned-deployment.json` names in `masterBackupRoot`, currently `%APPDATA%\CindyGlobal\billion-context-proxy\backups\before-master-20261114-214204`. It contains exactly `Deploy-Master.ps1`, `build.mjs`, `fold-test.mjs`, `iso-test.mjs` and `live-entry.ts`; the earlier `before-master-20261114-191918` backup holds a byte-identical copy. By step: `iso-test.mjs` and `fold-test.mjs` serve step 1, `live-entry.ts` and `build.mjs` step 3, and `Deploy-Master.ps1` automates the preflight, release directory, backup and cutover of steps 2 and 4–6. Beside `tooling\`, the backup root holds the pre-cutover `Start-BillionContextProxy.ps1`, `proxy.identity.json`, `supervision-receipt.json`, `supervisor-status.json` and `tuned-deployment.json`, and `Rollback-MasterDeploy.ps1`, which undoes that one completed cutover: it restores the launcher and both receipts from that backup and restarts the previous release through the scheduled task. Each backup's rollback script targets its own cutover, so use the one in the backup the receipt names. The live launcher is `Start-BillionContextProxy.ps1` in the runtime root. `Rollback-TunedLiveProxy.ps1` in the same root is a different, deeper rollback: it restores the configuration and the launcher from the receipt's `backupRoot`, the backup taken before the first tuned deployment on 2026-11-07, not the previous release. + +The kept `Deploy-Master.ps1` does not follow steps 6–9 as written. At cutover it stops the old proxy, removes `maintenance.inhibit` and starts the scheduled task, so the supervisor starts the new release and is already running during the health check; no proxy is started by hand. If that fails, it stops the supervisor and the new proxy, restores the saved launcher and starts the scheduled task again whether or not the previous release then reports healthy. It rewrites the receipts and writes `Rollback-MasterDeploy.ps1` only after a successful cutover. Which order is the sanctioned one is an open owner decision, tracked in [#78](https://github.com/anuzzolilli-oss/billion-context/issues/78); until it is settled, do not assume the script and the steps are interchangeable. Inspect the kept tooling before reuse: it contains pinned build hashes and previous-build assumptions. Do not execute an old installer against a different current release without rebuilding its identity and rollback checks. diff --git a/reference/cindy-project.zh-CN.md b/reference/cindy-project.zh-CN.md index c6ac4712b4..c49631a913 100644 --- a/reference/cindy-project.zh-CN.md +++ b/reference/cindy-project.zh-CN.md @@ -84,15 +84,17 @@ Get-Content (Join-Path $proxyRoot 'tuned-deployment.json') ## 仅在明确请求时部署 -1. 固定人工合并后已评审的源码 SHA,并检查该准确 SHA 的 CI 与评审结果。构建独立候选产物,记录其哈希及任何本地运行 wrapper;使用生成数据和回环模拟上游,在隔离进程中测试该同一产物。 +1. 固定人工合并后已评审的源码 SHA,并检查该准确 SHA 的 CI 与评审结果。按步骤 3 的方法构建独立候选产物,记录其哈希及任何本地运行 wrapper;使用生成数据和回环模拟上游,在隔离进程中测试该同一产物:保留的 `iso-test.mjs` 检查启动、身份与转发,保留的 `fold-test.mjs` 检查折叠与检索。两者都以运行配置的副本在各自的端口上启动 bundle,从不使用运行端口。 2. 验证现有 supervisor、配置哈希、监听 PID/进程身份及空闲状态。准备新的 release 目录,备份 supervisor 和部署回执;保留认证、设置、原文及计划任务的登录启动/恢复职责。 -3. 运行版本的 bundle 由小型本地启动 wrapper `src/live-entry.ts` 配合保留的 esbuild 脚本 `build.mjs` 构建,而非标准 CLI 入口;只构建标准 CLI 无法体现该部署的运行时策略。该 wrapper 要求显式 `--port`(拒绝非整数以及小于 1024 或大于 65535 的端口),随后调用 `startServer({ ...loadOptions(), host: "127.0.0.1", port, passthrough: false, autoUpdate: false, autoRestartOnUpdate: false }, { boundedMaintenance: { timeoutMs: 15000, maxTokens: 1024 } })`,并记录已启用的 bounded maintenance。`build.mjs` 打包 `src/live-entry.ts` → `out/dist/index.mjs`(bundle/esm/node20,别名 `@earendil-works/pi-coding-agent` → `src/agent/pi-host-stub.ts`,external 为 `jimp, mysql2, mysql2/promise, bufferutil, utf-8-validate`,带 createRequire banner),并写出 `out/dist/build-info.json`,内含 `sourceCommit`、`bundleSha256`、`commit`(前 8 位加 `-live`)与 `localPatchSha256`;把这些哈希记入回执。 +3. 运行版本的 bundle 由小型本地启动 wrapper `live-entry.ts` 配合保留的 esbuild 脚本 `build.mjs` 构建,而非标准 CLI 入口;只构建标准 CLI 无法体现该部署的运行时策略。这两个文件都不在仓库中:它们位于下文所述的保留工具目录。把 wrapper 复制到已固定源码 SHA 的检出目录中的 `src/live-entry.ts`,在该检出目录的根目录运行 `build.mjs`,并以完整源码 SHA 作为参数;不得提交复制进来的文件。该 wrapper 要求显式 `--port`(拒绝非整数以及小于 1024 或大于 65535 的端口),随后调用 `startServer({ ...loadOptions(), host: "127.0.0.1", port, passthrough: false, autoUpdate: false, autoRestartOnUpdate: false }, { boundedMaintenance: { timeoutMs: 15000, maxTokens: 1024 } })`,并记录已启用的 bounded maintenance。`build.mjs` 打包 `src/live-entry.ts` → `out/dist/index.mjs`(bundle/esm/node20,别名 `@earendil-works/pi-coding-agent` → `src/agent/pi-host-stub.ts`,external 为 `jimp, mysql2, mysql2/promise, bufferutil, utf-8-validate`,带 createRequire banner),并写出 `out/dist/build-info.json`,内含 `sourceCommit`、`bundleSha256`、`commit`(前 8 位加 `-live`)与 `localPatchSha256`;把这些哈希记入回执。交给切换步骤的候选目录包含 `dist\index.mjs`、`dist\build-info.json`、`package.json` 和 `LICENSE`。 4. 编辑 launcher 前必须先停止 supervisor,并在运行根目录创建 `maintenance.inhibit`;该文件会抑制 supervisor 的接管、启动与重启,被抑制期间已监控的子进程继续运行。在 supervisor 存活时修改 launcher 默认值不安全:接管按 PID 加进程创建时间进行,并在持有句柄后复核;每个安装只允许一个 supervisor,由 `supervisor.lock` 上的操作系统排他锁保持,因此第二次启动会立即以 0 退出。inhibit 是临时的:由步骤 9 删除。 -5. 仅更改现有代理的 release 路径。launcher 的 `ProxyPath`、`ExpectedVersion` 和 `ExpectedCommit` 默认值必须改为与新 release 一致,否则 supervisor 会失败关闭(fail closed)。当前 release 的已验证默认值为 `ProxyPath` = `...\releases\master-d4aad618\dist\index.mjs`、`ExpectedVersion` = `0.1.213`、`ExpectedCommit` = `d4aad618-live`,另有 `Port` = `8787`、`NodePath` = `C:\Program Files\nodejs\node.exe`、`RestartDelaySeconds` 5、`PollSeconds` 5、`HeartbeatSeconds` 15 及 `-ReportOnly` 开关。 +5. 仅更改 launcher 中标识 release 的默认值,launcher 的其他内容一律不动:`ProxyPath` 和 `ExpectedCommit`,版本号变化时再加上 `ExpectedVersion`。它们必须与新 release 一致,否则 supervisor 会失败关闭(fail closed)。保留的 `Deploy-Master.ps1` 只改写 `ProxyPath` 与 `ExpectedCommit` 两行,若改动会触及其他行则停止,因此不覆盖版本号变化的情况。当前 release 的已验证默认值为 `ProxyPath` = `...\releases\master-d4aad618\dist\index.mjs`、`ExpectedVersion` = `0.1.213`、`ExpectedCommit` = `d4aad618-live`,另有 `Port` = `8787`、`NodePath` = `C:\Program Files\nodejs\node.exe`、`RestartDelaySeconds` 5、`PollSeconds` 5、`HeartbeatSeconds` 15 及 `-ReportOnly` 开关。 6. 遇到外来或未经验证的监听者、不可读/正在启动/不匹配的健康结果、匹配但未监听的进程、缺失的可执行文件,以及检查错误或超时,supervisor 会失败关闭:既不终止也不启动任何进程,状态每 `PollSeconds` 复核一次,且仅在变化时记录日志。等待活跃请求结束后只重启该代理。启动失败时走步骤 8 的回滚分支,而不是重启监管。 7. 检查 manifest 源码身份、唯一监听者及配置哈希不变。验证转发、实际折叠、原文/图片精确检索及该测试 session 的检查日志。获授权后可发送一个小型认证提供商请求。 -8. Canary 失败时,在监管仍处于停止且已抑制的状态下完成回滚:恢复保存的 launcher 与回执、恢复旧 release、重启该旧版本并对它重做步骤 7 的检查,然后报告失败。为回滚而修改 launcher 默认值时若 supervisor 存活,与步骤 4 同理并不安全;且 launcher 仍携带候选版本的 release 默认值,因此 supervisor 可能因步骤 5 与 6 所述原因对已恢复的监听者 fail closed。必须先完成该分支,再退出维护状态。 -9. 当将要保持运行的 release(候选版本或已恢复的旧版本)通过其检查后退出维护状态,成功路径与回滚路径同样适用:删除 `maintenance.inhibit` 并通过计划任务重启 supervisor。该文件存在期间 supervisor 拒绝接管、启动与重启,因此停在 canary 的部署会让代理在无人监管下运行——手动启动的代理可能通过全部检查,却仍没有自动接管与重启。随后确认 supervisor 报告的是当前运行的 release(候选版本或已恢复版本):其 `supervisor-status.json` 状态、预期版本号与运行 commit,以及它接管的监听 PID。 -10. 完成部署回执,报告源码 SHA、结果及回滚位置。本地代理部署不包含 npm 发包或更新承载任务的 Cindy 应用。 +8. Canary 失败时,在监管仍处于停止且已抑制的状态下完成回滚:恢复保存的 launcher、若回执已被改写则一并恢复、恢复旧 release、重启该旧版本并对它重做步骤 7 的检查,然后报告失败。为回滚而修改 launcher 默认值时若 supervisor 存活,与步骤 4 同理并不安全;且 launcher 仍携带候选版本的 release 默认值,因此 supervisor 可能因步骤 5 与 6 所述原因对已恢复的监听者 fail closed。必须先完成该分支,再退出维护状态。 +9. 当将要保持运行的 release 通过其检查后退出维护状态,成功路径与回滚路径同样适用:删除 `maintenance.inhibit` 并通过计划任务重启 supervisor。该文件存在期间 supervisor 拒绝接管、启动与重启,因此停在 canary 的部署会让代理在无人监管下运行——手动启动的代理可能通过全部检查,却仍没有自动接管与重启。随后确认 supervisor 报告的是当前运行的 release(候选版本或已恢复版本):其 `supervisor-status.json` 状态、预期版本号与 commit,以及它接管的监听 PID。 +10. 成功路径:完成部署回执,报告已部署的 SHA、结果及回滚位置。回滚路径:没有完成任何部署,确认回执描述的是已恢复的 release,并报告失败、保持运行的 release 及备份位置。本地代理部署不包含 npm 发包或更新承载任务的 Cindy 应用。 -初次修复的部署工具保留在 `%APPDATA%\CindyGlobal\billion-context-proxy\backups\before-master-20261114-191918\tooling\`,其中恰好包含 `Deploy-Master.ps1`、`build.mjs`、`fold-test.mjs`、`iso-test.mjs` 和 `live-entry.ts`,回滚脚本 `Rollback-MasterDeploy.ps1` 就在同一位置旁边;该备份根目录同时保存 `Start-BillionContextProxy.ps1`、`proxy.identity.json`、`supervision-receipt.json`、`supervisor-status.json` 和 `tuned-deployment.json`。运行中的 launcher 是运行根目录中的 `Start-BillionContextProxy.ps1`,同一根目录下的 `Rollback-TunedLiveProxy.ps1` 用于回滚该 launcher。复用前检查这些保留的工具:它们含固定的构建哈希与旧版本假设。不得在当前版本已变化时直接执行旧安装脚本,应重新建立身份及回滚检查。 +每次 master 切换都把工具保留在各自的备份中:即部署回执 `tuned-deployment.json` 的 `masterBackupRoot` 所指备份根目录下的 `tooling\` 目录,当前为 `%APPDATA%\CindyGlobal\billion-context-proxy\backups\before-master-20261114-214204`。其中恰好包含 `Deploy-Master.ps1`、`build.mjs`、`fold-test.mjs`、`iso-test.mjs` 和 `live-entry.ts`;更早的 `before-master-20261114-191918` 备份中有一份逐字节相同的副本。按步骤对应:`iso-test.mjs` 与 `fold-test.mjs` 用于步骤 1,`live-entry.ts` 与 `build.mjs` 用于步骤 3,`Deploy-Master.ps1` 自动完成步骤 2 及步骤 4–6 中的预检、release 目录、备份与切换。在 `tooling\` 旁边,该备份根目录保存切换前的 `Start-BillionContextProxy.ps1`、`proxy.identity.json`、`supervision-receipt.json`、`supervisor-status.json` 和 `tuned-deployment.json`,以及 `Rollback-MasterDeploy.ps1`;后者撤销这一次已完成的切换:从该备份恢复 launcher 与两份回执,并通过计划任务重启旧 release。每个备份中的回滚脚本只针对它自己的那次切换,因此应使用回执所指备份中的那一个。运行中的 launcher 是运行根目录中的 `Start-BillionContextProxy.ps1`。同一根目录下的 `Rollback-TunedLiveProxy.ps1` 是另一种更深的回滚:它从回执的 `backupRoot`(2026-11-07 首次 tuned 部署之前的备份)恢复配置与 launcher,而不是回到上一个 release。 + +保留的 `Deploy-Master.ps1` 并不按步骤 6–9 的写法执行。切换时它停止旧代理、删除 `maintenance.inhibit` 并启动计划任务,因此由 supervisor 启动新 release,健康检查期间 supervisor 已在运行;没有手动启动任何代理。若失败,它停止 supervisor 与新代理、恢复保存的 launcher 并再次启动计划任务,无论旧 release 随后是否报告健康。只有切换成功后它才改写回执并写出 `Rollback-MasterDeploy.ps1`。哪一种顺序才是认可的流程,尚待所有者决定,见 [#78](https://github.com/anuzzolilli-oss/billion-context/issues/78);在此之前,不要假定脚本与上述步骤可以互换。复用前检查这些保留的工具:它们含固定的构建哈希与旧版本假设。不得在当前版本已变化时直接执行旧安装脚本,应重新建立身份及回滚检查。 From 22d4580abecf435990e5f526142b884a995cbdb3 Mon Sep 17 00:00:00 2001 From: anuzzolilli-oss Date: Mon, 16 Nov 2026 21:50:54 -0500 Subject: [PATCH 2/3] docs: deploy steps follow the supervisor-start cutover order (#78) Owner decision of 2026-11-16 on issue #78 section A: - The sanctioned cutover order is the one the kept Deploy-Master.ps1 implements: hold supervision, edit the launcher, stop the old proxy when idle, lift the hold and let the supervisor start the new release, check with supervision running. Steps 4 and 6-10 are rewritten to that order in English and Chinese. - A failed rollback ends with the hold back in place and a report to the owner. The page says the kept scripts re-enable supervision regardless, so the hold has to be applied by hand after them. - Step 5 no longer repeats the current release identity; it names the candidate and receipt fields that carry it. Docs only. Nothing was run against the live proxy. Assisted-by: Cindy (https://cindy.app) --- reference/cindy-project.md | 18 +++++++++--------- reference/cindy-project.zh-CN.md | 18 +++++++++--------- 2 files changed, 18 insertions(+), 18 deletions(-) diff --git a/reference/cindy-project.md b/reference/cindy-project.md index 7260b9d44e..4a1f8dbacb 100644 --- a/reference/cindy-project.md +++ b/reference/cindy-project.md @@ -87,14 +87,14 @@ The receipt identifies the active release, prior release, bundle hash and backup 1. Pin the human-merged, reviewed source SHA and check the exact-head CI/review results. Build a separate candidate artifact with the recipe in step 3 and record its hash and any local runtime wrapper. Test that exact artifact in an isolated process using generated data and a loopback upstream: the kept `iso-test.mjs` checks boot, identity and forwarding, and the kept `fold-test.mjs` checks folding and retrieval. Both start the bundle on their own port with a copy of the live config and never use the live port. 2. Verify the existing supervisor, configuration hash, listener PID/process identity and idle state. Prepare a new release directory and back up the supervisor and deployment receipt. Preserve authentication, settings, originals and the scheduled task's sign-in/recovery ownership. 3. Build the live bundle from the small local start-up wrapper `live-entry.ts` with the kept esbuild script `build.mjs`, not from the standard CLI entry; building the standard CLI alone does not capture this deployment's runtime policy. Neither file is in the repository: both are in the kept tooling directory named below. Copy the wrapper to `src/live-entry.ts` in a checkout of the pinned source SHA and run `build.mjs` from that checkout's root with the full source SHA as its argument; do not commit the copied files. The wrapper requires an explicit `--port` (it rejects a non-integer value and ports below 1024 or above 65535), then calls `startServer({ ...loadOptions(), host: "127.0.0.1", port, passthrough: false, autoUpdate: false, autoRestartOnUpdate: false }, { boundedMaintenance: { timeoutMs: 15000, maxTokens: 1024 } })` and logs the enabled bounded maintenance. `build.mjs` bundles `src/live-entry.ts` → `out/dist/index.mjs` (bundle/esm/node20, alias `@earendil-works/pi-coding-agent` → `src/agent/pi-host-stub.ts`, external `jimp, mysql2, mysql2/promise, bufferutil, utf-8-validate`, createRequire banner) and writes `out/dist/build-info.json` with `sourceCommit`, `bundleSha256`, `commit` (the first 8 chars plus `-live`) and `localPatchSha256`; record those hashes in the receipt. The candidate folder handed to the cutover holds `dist\index.mjs`, `dist\build-info.json`, `package.json` and `LICENSE`. -4. Stop the supervisor before editing the launcher, and create `maintenance.inhibit` in the runtime root, which suppresses supervisor adoption, start and restart; a monitored child is left running while inhibited. Editing launcher defaults under a live supervisor is unsafe: adoption is by PID plus process creation time, rechecked after a handle is held, and one supervisor per installation is held by an OS-exclusive lock on `supervisor.lock`, so a second launch exits 0 immediately. The inhibit is temporary: step 9 removes it. -5. Change only the launcher defaults that identify the release, and nothing else in the launcher: `ProxyPath` and `ExpectedCommit`, plus `ExpectedVersion` when the version changes. They must match the new release, otherwise the supervisor fails closed. The kept `Deploy-Master.ps1` rewrites exactly the `ProxyPath` and `ExpectedCommit` lines and stops if its edit would touch any other line, so it does not cover a version change. Verified defaults for the current release are `ProxyPath` = `...\releases\master-d4aad618\dist\index.mjs`, `ExpectedVersion` = `0.1.213`, `ExpectedCommit` = `d4aad618-live`, alongside `Port` = `8787`, `NodePath` = `C:\Program Files\nodejs\node.exe`, `RestartDelaySeconds` 5, `PollSeconds` 5, `HeartbeatSeconds` 15 and a `-ReportOnly` switch. -6. Expect the supervisor to fail closed on a foreign or unverified listener, unreadable/booting/mismatched health, a matching process that is not listening, missing executables, and inspection errors or timeouts: nothing is killed and nothing is started, and state is rechecked every `PollSeconds` and logged only when it changes. Restart only that proxy after active requests drain. On startup failure, take the rollback branch in step 8 rather than restarting supervision. -7. Check the manifest's source identity, single-listener ownership and unchanged configuration hash. Exercise request forwarding, actual folding, exact original text/image retrieval and session-scoped checker logs. Use one small authenticated provider request when authorized. -8. If the canary fails, roll back while supervision is still stopped and inhibited: restore the saved launcher, restore the receipts if they were already rewritten, restore the previous release, restart that release and repeat the step 7 checks against it, then report the failure. Editing launcher defaults for the rollback under a live supervisor is unsafe for the same reason as in step 4, and the launcher still carries the candidate's release defaults, so the supervisor can fail closed on the restored listener for the reasons in steps 5 and 6. Complete this branch before leaving maintenance. -9. Leave maintenance once the release that is to stay live has passed its checks, on the success path and the rollback path alike: remove `maintenance.inhibit` and restart the supervisor through its scheduled task. While that file exists the supervisor refuses adoption, start and restart, so a deployment that stops at the canary leaves the proxy running unsupervised — a manually started proxy can pass every check and still have no automatic adoption or restart. Verify the supervisor then reports the release now live, candidate or restored: its `supervisor-status.json` state, the expected version and commit, and the listener PID it adopted. -10. On the success path, finalize the deployment receipt and report the deployed SHA, results and rollback location. On the rollback path nothing was deployed: confirm the receipts describe the restored release, and report the failure, the release left live and the backup location. A local proxy deployment does not publish npm packages or update the hosting Cindy application. +4. Hold supervision before editing the launcher, in this order: create `maintenance.inhibit` in the runtime root, which suppresses supervisor adoption, start and restart; disable the scheduled task, whose repeating trigger would otherwise relaunch the supervisor; then stop the supervisor. A monitored child is left running while inhibited, so the old proxy keeps serving: confirm it is still healthy. Editing launcher defaults under a live supervisor is unsafe: adoption is by PID plus process creation time, rechecked after a handle is held, and one supervisor per installation is held by an OS-exclusive lock on `supervisor.lock`, so a second launch exits 0 immediately. The hold is temporary: step 6 lifts it at cutover, and step 8 lifts it again after a rollback. +5. Change only the launcher defaults that identify the release, and nothing else in the launcher: `ProxyPath` and `ExpectedCommit`, plus `ExpectedVersion` when the version changes. They must match the new release, otherwise the supervisor fails closed. Take the new values from the candidate, not from this page: `ProxyPath` is `dist\index.mjs` in the new release directory, `ExpectedCommit` is `commit` in the candidate's `dist\build-info.json`, and `ExpectedVersion` is the version its health endpoint reported in the step 1 isolated test. The values of the release being replaced are the launcher's current defaults; the receipts record the same release in `releaseRoot` and `build` of `tuned-deployment.json` and in `masterDeploy.proxyRelease` of `supervision-receipt.json`, which also carries the version. The kept `Deploy-Master.ps1` rewrites exactly the `ProxyPath` and `ExpectedCommit` lines and stops if its edit would touch any other line, and its health check has one fixed version written into it, so it does not cover a version change. The other defaults stay as they are: `Port` = `8787`, `NodePath` = `C:\Program Files\nodejs\node.exe`, `RestartDelaySeconds` 5, `PollSeconds` 5, `HeartbeatSeconds` 15 and a `-ReportOnly` switch. +6. Cut over only when idle: if any client connection to the live port is open, stand down instead of waiting for requests to drain. Stop only the old proxy, wait for the port to be released, then remove `maintenance.inhibit`, enable the scheduled task and start it. The supervisor then starts the new release itself, because no matching proxy exists and nothing listens on the port; do not start a proxy by hand. With supervision running, expect the supervisor to fail closed on a foreign or unverified listener, unreadable/booting/mismatched health, a matching process that is not listening, missing executables, and inspection errors or timeouts: nothing is killed and nothing is started, and state is rechecked every `PollSeconds` and logged only when it changes. The cutover has succeeded only when health reports the expected version and commit from the single listener's PID, with exactly one proxy process of the new release and exactly one supervisor; the kept script waits up to 90 seconds for that. Otherwise take the rollback branch in step 8. +7. With supervision running, check the manifest's source identity, single-listener ownership and unchanged configuration hash. Exercise request forwarding, actual folding, exact original text/image retrieval and session-scoped checker logs. Use one small authenticated provider request when authorized. The kept script checks only the health identity and process counts of step 6, then rewrites the receipts and writes `Rollback-MasterDeploy.ps1`, so these checks run after it has finished, and a failure here is rolled back with the receipts already rewritten. +8. If the cutover or these checks fail, roll back under a new hold: create `maintenance.inhibit`, disable the scheduled task, stop the supervisor and then the candidate proxy. Restore the saved launcher, and restore both receipts if they were already rewritten: a failure inside the cutover leaves the receipts untouched, a failure in step 7 after the kept script has finished does not, and `Rollback-MasterDeploy.ps1` in that cutover's backup restores all three files. Editing or restoring the launcher under a live supervisor is unsafe for the same reason as in step 4. Then lift the hold as in step 6, so that the supervisor starts the previous release, and repeat the step 6 success test and the step 7 checks against it. If the restored release fails them too, the rollback has failed: put the hold back (inhibit set, task disabled, supervisor stopped), make no further start, restore or edit attempt, and report to the owner with the evidence: the failed checks, `supervisor.log`, `bili.log` and what, if anything, holds the port. The live proxy then stays unsupervised or down until the owner decides; that is the intended end state, so that nothing restarts a failing proxy in a loop. +9. Confirm that maintenance has ended, on the success path and the rollback path alike: `maintenance.inhibit` is absent, the scheduled task is enabled and exactly one supervisor is running. While that file exists the supervisor refuses adoption, start and restart, so a deployment that leaves it behind has no automatic adoption or restart even when every check passed. Verify the supervisor reports the release now live, candidate or restored: its `supervisor-status.json` state, the expected version and commit, and the PID of the proxy it started. The only exception is the failed rollback in step 8, which deliberately ends with the hold in place. +10. On the success path, finalize the deployment receipt and report the deployed SHA, results and rollback location. On the rollback path nothing was deployed: confirm the receipts describe the restored release, and report the failure, the release left live and the backup location. After a failed rollback, report that no release is confirmed live and that the hold is in place. A local proxy deployment does not publish npm packages or update the hosting Cindy application. -Each master cutover keeps its tooling in its own backup: the `tooling\` directory under the backup root that the deployment receipt `tuned-deployment.json` names in `masterBackupRoot`, currently `%APPDATA%\CindyGlobal\billion-context-proxy\backups\before-master-20261114-214204`. It contains exactly `Deploy-Master.ps1`, `build.mjs`, `fold-test.mjs`, `iso-test.mjs` and `live-entry.ts`; the earlier `before-master-20261114-191918` backup holds a byte-identical copy. By step: `iso-test.mjs` and `fold-test.mjs` serve step 1, `live-entry.ts` and `build.mjs` step 3, and `Deploy-Master.ps1` automates the preflight, release directory, backup and cutover of steps 2 and 4–6. Beside `tooling\`, the backup root holds the pre-cutover `Start-BillionContextProxy.ps1`, `proxy.identity.json`, `supervision-receipt.json`, `supervisor-status.json` and `tuned-deployment.json`, and `Rollback-MasterDeploy.ps1`, which undoes that one completed cutover: it restores the launcher and both receipts from that backup and restarts the previous release through the scheduled task. Each backup's rollback script targets its own cutover, so use the one in the backup the receipt names. The live launcher is `Start-BillionContextProxy.ps1` in the runtime root. `Rollback-TunedLiveProxy.ps1` in the same root is a different, deeper rollback: it restores the configuration and the launcher from the receipt's `backupRoot`, the backup taken before the first tuned deployment on 2026-11-07, not the previous release. +Each master cutover keeps its tooling in its own backup: the `tooling\` directory under the backup root that the deployment receipt `tuned-deployment.json` names in `masterBackupRoot`, currently `%APPDATA%\CindyGlobal\billion-context-proxy\backups\before-master-20261114-214204`. It contains exactly `Deploy-Master.ps1`, `build.mjs`, `fold-test.mjs`, `iso-test.mjs` and `live-entry.ts`; the earlier `before-master-20261114-191918` backup holds a byte-identical copy. By step: `iso-test.mjs` and `fold-test.mjs` serve step 1, `live-entry.ts` and `build.mjs` step 3, and `Deploy-Master.ps1` automates the preflight, release directory and backup of step 2, the hold and launcher edit of steps 4–5, the cutover of step 6, the launcher-only rollback of step 8 when the cutover fails, and the receipt rewrite of step 10. Beside `tooling\`, the backup root holds the pre-cutover `Start-BillionContextProxy.ps1`, `proxy.identity.json`, `supervision-receipt.json`, `supervisor-status.json` and `tuned-deployment.json`, and `Rollback-MasterDeploy.ps1`, which undoes that one completed cutover: it restores the launcher and both receipts from that backup and restarts the previous release through the scheduled task. Each backup's rollback script targets its own cutover, so use the one in the backup the receipt names. The live launcher is `Start-BillionContextProxy.ps1` in the runtime root. `Rollback-TunedLiveProxy.ps1` in the same root is a different, deeper rollback: it restores the configuration and the launcher from the receipt's `backupRoot`, the backup taken before the first tuned deployment on 2026-11-07, not the previous release. -The kept `Deploy-Master.ps1` does not follow steps 6–9 as written. At cutover it stops the old proxy, removes `maintenance.inhibit` and starts the scheduled task, so the supervisor starts the new release and is already running during the health check; no proxy is started by hand. If that fails, it stops the supervisor and the new proxy, restores the saved launcher and starts the scheduled task again whether or not the previous release then reports healthy. It rewrites the receipts and writes `Rollback-MasterDeploy.ps1` only after a successful cutover. Which order is the sanctioned one is an open owner decision, tracked in [#78](https://github.com/anuzzolilli-oss/billion-context/issues/78); until it is settled, do not assume the script and the steps are interchangeable. Inspect the kept tooling before reuse: it contains pinned build hashes and previous-build assumptions. Do not execute an old installer against a different current release without rebuilding its identity and rollback checks. +Steps 4–9 follow the order the kept `Deploy-Master.ps1` implements: the supervisor, not the operator, starts the new release, and health is checked with supervision running. That order is the sanctioned one by owner decision of 2026-11-16 ([#78](https://github.com/anuzzolilli-oss/billion-context/issues/78)); the earlier wording, which started and checked the new proxy by hand under the inhibit, is superseded, and with it the question of how a hand-started proxy comes under supervision. The kept scripts still depart from the steps when a rollback fails. The failure branch of `Deploy-Master.ps1` and `Rollback-MasterDeploy.ps1` both remove the inhibit and start the scheduled task without requiring the previous release to be healthy (the first only reports the result, the second does not check), so after either one, do the step 8 checks yourself and put the hold back by hand if they fail. The script rewrites the receipts and writes `Rollback-MasterDeploy.ps1` only after a successful cutover. Inspect the kept tooling before reuse: it contains pinned build hashes and previous-build assumptions. Do not execute an old installer against a different current release without rebuilding its identity and rollback checks. diff --git a/reference/cindy-project.zh-CN.md b/reference/cindy-project.zh-CN.md index c49631a913..0629d0a959 100644 --- a/reference/cindy-project.zh-CN.md +++ b/reference/cindy-project.zh-CN.md @@ -87,14 +87,14 @@ Get-Content (Join-Path $proxyRoot 'tuned-deployment.json') 1. 固定人工合并后已评审的源码 SHA,并检查该准确 SHA 的 CI 与评审结果。按步骤 3 的方法构建独立候选产物,记录其哈希及任何本地运行 wrapper;使用生成数据和回环模拟上游,在隔离进程中测试该同一产物:保留的 `iso-test.mjs` 检查启动、身份与转发,保留的 `fold-test.mjs` 检查折叠与检索。两者都以运行配置的副本在各自的端口上启动 bundle,从不使用运行端口。 2. 验证现有 supervisor、配置哈希、监听 PID/进程身份及空闲状态。准备新的 release 目录,备份 supervisor 和部署回执;保留认证、设置、原文及计划任务的登录启动/恢复职责。 3. 运行版本的 bundle 由小型本地启动 wrapper `live-entry.ts` 配合保留的 esbuild 脚本 `build.mjs` 构建,而非标准 CLI 入口;只构建标准 CLI 无法体现该部署的运行时策略。这两个文件都不在仓库中:它们位于下文所述的保留工具目录。把 wrapper 复制到已固定源码 SHA 的检出目录中的 `src/live-entry.ts`,在该检出目录的根目录运行 `build.mjs`,并以完整源码 SHA 作为参数;不得提交复制进来的文件。该 wrapper 要求显式 `--port`(拒绝非整数以及小于 1024 或大于 65535 的端口),随后调用 `startServer({ ...loadOptions(), host: "127.0.0.1", port, passthrough: false, autoUpdate: false, autoRestartOnUpdate: false }, { boundedMaintenance: { timeoutMs: 15000, maxTokens: 1024 } })`,并记录已启用的 bounded maintenance。`build.mjs` 打包 `src/live-entry.ts` → `out/dist/index.mjs`(bundle/esm/node20,别名 `@earendil-works/pi-coding-agent` → `src/agent/pi-host-stub.ts`,external 为 `jimp, mysql2, mysql2/promise, bufferutil, utf-8-validate`,带 createRequire banner),并写出 `out/dist/build-info.json`,内含 `sourceCommit`、`bundleSha256`、`commit`(前 8 位加 `-live`)与 `localPatchSha256`;把这些哈希记入回执。交给切换步骤的候选目录包含 `dist\index.mjs`、`dist\build-info.json`、`package.json` 和 `LICENSE`。 -4. 编辑 launcher 前必须先停止 supervisor,并在运行根目录创建 `maintenance.inhibit`;该文件会抑制 supervisor 的接管、启动与重启,被抑制期间已监控的子进程继续运行。在 supervisor 存活时修改 launcher 默认值不安全:接管按 PID 加进程创建时间进行,并在持有句柄后复核;每个安装只允许一个 supervisor,由 `supervisor.lock` 上的操作系统排他锁保持,因此第二次启动会立即以 0 退出。inhibit 是临时的:由步骤 9 删除。 -5. 仅更改 launcher 中标识 release 的默认值,launcher 的其他内容一律不动:`ProxyPath` 和 `ExpectedCommit`,版本号变化时再加上 `ExpectedVersion`。它们必须与新 release 一致,否则 supervisor 会失败关闭(fail closed)。保留的 `Deploy-Master.ps1` 只改写 `ProxyPath` 与 `ExpectedCommit` 两行,若改动会触及其他行则停止,因此不覆盖版本号变化的情况。当前 release 的已验证默认值为 `ProxyPath` = `...\releases\master-d4aad618\dist\index.mjs`、`ExpectedVersion` = `0.1.213`、`ExpectedCommit` = `d4aad618-live`,另有 `Port` = `8787`、`NodePath` = `C:\Program Files\nodejs\node.exe`、`RestartDelaySeconds` 5、`PollSeconds` 5、`HeartbeatSeconds` 15 及 `-ReportOnly` 开关。 -6. 遇到外来或未经验证的监听者、不可读/正在启动/不匹配的健康结果、匹配但未监听的进程、缺失的可执行文件,以及检查错误或超时,supervisor 会失败关闭:既不终止也不启动任何进程,状态每 `PollSeconds` 复核一次,且仅在变化时记录日志。等待活跃请求结束后只重启该代理。启动失败时走步骤 8 的回滚分支,而不是重启监管。 -7. 检查 manifest 源码身份、唯一监听者及配置哈希不变。验证转发、实际折叠、原文/图片精确检索及该测试 session 的检查日志。获授权后可发送一个小型认证提供商请求。 -8. Canary 失败时,在监管仍处于停止且已抑制的状态下完成回滚:恢复保存的 launcher、若回执已被改写则一并恢复、恢复旧 release、重启该旧版本并对它重做步骤 7 的检查,然后报告失败。为回滚而修改 launcher 默认值时若 supervisor 存活,与步骤 4 同理并不安全;且 launcher 仍携带候选版本的 release 默认值,因此 supervisor 可能因步骤 5 与 6 所述原因对已恢复的监听者 fail closed。必须先完成该分支,再退出维护状态。 -9. 当将要保持运行的 release 通过其检查后退出维护状态,成功路径与回滚路径同样适用:删除 `maintenance.inhibit` 并通过计划任务重启 supervisor。该文件存在期间 supervisor 拒绝接管、启动与重启,因此停在 canary 的部署会让代理在无人监管下运行——手动启动的代理可能通过全部检查,却仍没有自动接管与重启。随后确认 supervisor 报告的是当前运行的 release(候选版本或已恢复版本):其 `supervisor-status.json` 状态、预期版本号与 commit,以及它接管的监听 PID。 -10. 成功路径:完成部署回执,报告已部署的 SHA、结果及回滚位置。回滚路径:没有完成任何部署,确认回执描述的是已恢复的 release,并报告失败、保持运行的 release 及备份位置。本地代理部署不包含 npm 发包或更新承载任务的 Cindy 应用。 +4. 编辑 launcher 前必须先暂停监管,顺序如下:在运行根目录创建 `maintenance.inhibit`,该文件会抑制 supervisor 的接管、启动与重启;禁用计划任务,否则其重复触发器会重新拉起 supervisor;然后停止 supervisor。被抑制期间已监控的子进程继续运行,因此旧代理仍在服务:确认它仍然健康。在 supervisor 存活时修改 launcher 默认值不安全:接管按 PID 加进程创建时间进行,并在持有句柄后复核;每个安装只允许一个 supervisor,由 `supervisor.lock` 上的操作系统排他锁保持,因此第二次启动会立即以 0 退出。这一暂停是临时的:步骤 6 在切换时解除,回滚后由步骤 8 再次解除。 +5. 仅更改 launcher 中标识 release 的默认值,launcher 的其他内容一律不动:`ProxyPath` 和 `ExpectedCommit`,版本号变化时再加上 `ExpectedVersion`。它们必须与新 release 一致,否则 supervisor 会失败关闭(fail closed)。新值取自候选产物,而非本页:`ProxyPath` 是新 release 目录中的 `dist\index.mjs`,`ExpectedCommit` 是候选产物 `dist\build-info.json` 中的 `commit`,`ExpectedVersion` 是步骤 1 隔离测试中其健康端点报告的版本号。被替换 release 的值即 launcher 当前的默认值;回执也记录同一 release:`tuned-deployment.json` 的 `releaseRoot` 与 `build`,以及 `supervision-receipt.json` 的 `masterDeploy.proxyRelease`(其中还含版本号)。保留的 `Deploy-Master.ps1` 只改写 `ProxyPath` 与 `ExpectedCommit` 两行,若改动会触及其他行则停止,且其健康检查中写死了一个固定版本号,因此不覆盖版本号变化的情况。其余默认值保持不变:`Port` = `8787`、`NodePath` = `C:\Program Files\nodejs\node.exe`、`RestartDelaySeconds` 5、`PollSeconds` 5、`HeartbeatSeconds` 15 及 `-ReportOnly` 开关。 +6. 仅在空闲时切换:只要运行端口上还有客户端连接,就中止,而不是等待请求结束。只停止旧代理,等待端口释放,然后删除 `maintenance.inhibit`、启用计划任务并启动它。此时没有匹配的代理且端口无人监听,因此由 supervisor 自行启动新 release;不得手动启动代理。监管运行期间,遇到外来或未经验证的监听者、不可读/正在启动/不匹配的健康结果、匹配但未监听的进程、缺失的可执行文件,以及检查错误或超时,supervisor 会失败关闭:既不终止也不启动任何进程,状态每 `PollSeconds` 复核一次,且仅在变化时记录日志。只有当健康结果由唯一监听者的 PID 报告预期版本号与 commit,且新 release 的代理进程恰好一个、supervisor 恰好一个时,切换才算成功;保留的脚本为此最多等待 90 秒。否则走步骤 8 的回滚分支。 +7. 在监管运行的状态下,检查 manifest 源码身份、唯一监听者及配置哈希不变。验证转发、实际折叠、原文/图片精确检索及该测试 session 的检查日志。获授权后可发送一个小型认证提供商请求。保留的脚本只检查步骤 6 的健康身份与进程数量,随后即改写回执并写出 `Rollback-MasterDeploy.ps1`,因此这些检查在脚本结束后进行,此处失败时须在回执已被改写的情况下回滚。 +8. 切换或上述检查失败时,在重新暂停监管后回滚:创建 `maintenance.inhibit`、禁用计划任务、停止 supervisor,再停止候选代理。恢复保存的 launcher,若回执已被改写则一并恢复两份回执:切换过程中失败时回执尚未改动,保留的脚本结束后在步骤 7 失败时则已改写,该次切换备份中的 `Rollback-MasterDeploy.ps1` 会恢复这三个文件。在 supervisor 存活时修改或恢复 launcher,与步骤 4 同理并不安全。随后按步骤 6 的方式解除暂停,由 supervisor 启动旧 release,并对它重做步骤 6 的成功判定与步骤 7 的检查。若恢复后的 release 同样未通过,即回滚失败:重新暂停监管(inhibit 已设、计划任务已禁用、supervisor 已停止),不再尝试任何启动、恢复或编辑,并携带证据向所有者报告:未通过的检查、`supervisor.log`、`bili.log`,以及端口当前由谁占用(如有)。此后运行中的代理处于无人监管或停止状态,直至所有者决定;这是有意设定的终态,以免失败的代理被反复重启。 +9. 确认维护状态已结束,成功路径与回滚路径同样适用:`maintenance.inhibit` 不存在、计划任务已启用,且恰好有一个 supervisor 在运行。该文件存在期间 supervisor 拒绝接管、启动与重启,因此遗留该文件的部署即使通过全部检查,也没有自动接管与重启。确认 supervisor 报告的是当前运行的 release(候选版本或已恢复版本):其 `supervisor-status.json` 状态、预期版本号与 commit,以及它所启动代理的 PID。唯一的例外是步骤 8 的回滚失败,它有意以暂停监管的状态结束。 +10. 成功路径:完成部署回执,报告已部署的 SHA、结果及回滚位置。回滚路径:没有完成任何部署,确认回执描述的是已恢复的 release,并报告失败、保持运行的 release 及备份位置。回滚失败时:报告没有任何 release 被确认在运行,且监管处于暂停状态。本地代理部署不包含 npm 发包或更新承载任务的 Cindy 应用。 -每次 master 切换都把工具保留在各自的备份中:即部署回执 `tuned-deployment.json` 的 `masterBackupRoot` 所指备份根目录下的 `tooling\` 目录,当前为 `%APPDATA%\CindyGlobal\billion-context-proxy\backups\before-master-20261114-214204`。其中恰好包含 `Deploy-Master.ps1`、`build.mjs`、`fold-test.mjs`、`iso-test.mjs` 和 `live-entry.ts`;更早的 `before-master-20261114-191918` 备份中有一份逐字节相同的副本。按步骤对应:`iso-test.mjs` 与 `fold-test.mjs` 用于步骤 1,`live-entry.ts` 与 `build.mjs` 用于步骤 3,`Deploy-Master.ps1` 自动完成步骤 2 及步骤 4–6 中的预检、release 目录、备份与切换。在 `tooling\` 旁边,该备份根目录保存切换前的 `Start-BillionContextProxy.ps1`、`proxy.identity.json`、`supervision-receipt.json`、`supervisor-status.json` 和 `tuned-deployment.json`,以及 `Rollback-MasterDeploy.ps1`;后者撤销这一次已完成的切换:从该备份恢复 launcher 与两份回执,并通过计划任务重启旧 release。每个备份中的回滚脚本只针对它自己的那次切换,因此应使用回执所指备份中的那一个。运行中的 launcher 是运行根目录中的 `Start-BillionContextProxy.ps1`。同一根目录下的 `Rollback-TunedLiveProxy.ps1` 是另一种更深的回滚:它从回执的 `backupRoot`(2026-11-07 首次 tuned 部署之前的备份)恢复配置与 launcher,而不是回到上一个 release。 +每次 master 切换都把工具保留在各自的备份中:即部署回执 `tuned-deployment.json` 的 `masterBackupRoot` 所指备份根目录下的 `tooling\` 目录,当前为 `%APPDATA%\CindyGlobal\billion-context-proxy\backups\before-master-20261114-214204`。其中恰好包含 `Deploy-Master.ps1`、`build.mjs`、`fold-test.mjs`、`iso-test.mjs` 和 `live-entry.ts`;更早的 `before-master-20261114-191918` 备份中有一份逐字节相同的副本。按步骤对应:`iso-test.mjs` 与 `fold-test.mjs` 用于步骤 1,`live-entry.ts` 与 `build.mjs` 用于步骤 3,`Deploy-Master.ps1` 自动完成步骤 2 的预检、release 目录与备份,步骤 4–5 的暂停监管与 launcher 编辑,步骤 6 的切换,切换失败时步骤 8 中仅恢复 launcher 的回滚,以及步骤 10 的回执改写。在 `tooling\` 旁边,该备份根目录保存切换前的 `Start-BillionContextProxy.ps1`、`proxy.identity.json`、`supervision-receipt.json`、`supervisor-status.json` 和 `tuned-deployment.json`,以及 `Rollback-MasterDeploy.ps1`;后者撤销这一次已完成的切换:从该备份恢复 launcher 与两份回执,并通过计划任务重启旧 release。每个备份中的回滚脚本只针对它自己的那次切换,因此应使用回执所指备份中的那一个。运行中的 launcher 是运行根目录中的 `Start-BillionContextProxy.ps1`。同一根目录下的 `Rollback-TunedLiveProxy.ps1` 是另一种更深的回滚:它从回执的 `backupRoot`(2026-11-07 首次 tuned 部署之前的备份)恢复配置与 launcher,而不是回到上一个 release。 -保留的 `Deploy-Master.ps1` 并不按步骤 6–9 的写法执行。切换时它停止旧代理、删除 `maintenance.inhibit` 并启动计划任务,因此由 supervisor 启动新 release,健康检查期间 supervisor 已在运行;没有手动启动任何代理。若失败,它停止 supervisor 与新代理、恢复保存的 launcher 并再次启动计划任务,无论旧 release 随后是否报告健康。只有切换成功后它才改写回执并写出 `Rollback-MasterDeploy.ps1`。哪一种顺序才是认可的流程,尚待所有者决定,见 [#78](https://github.com/anuzzolilli-oss/billion-context/issues/78);在此之前,不要假定脚本与上述步骤可以互换。复用前检查这些保留的工具:它们含固定的构建哈希与旧版本假设。不得在当前版本已变化时直接执行旧安装脚本,应重新建立身份及回滚检查。 +步骤 4–9 采用保留的 `Deploy-Master.ps1` 所实现的顺序:由 supervisor 而非操作者启动新 release,健康检查在监管运行的状态下进行。依据所有者 2026-11-16 的决定([#78](https://github.com/anuzzolilli-oss/billion-context/issues/78)),这是认可的顺序;此前在 inhibit 下手动启动并检查新代理的写法已被取代,手动启动的代理如何纳入监管的问题也随之不复存在。回滚失败时,保留的脚本仍与上述步骤不同。`Deploy-Master.ps1` 的失败分支与 `Rollback-MasterDeploy.ps1` 都会删除 inhibit 并启动计划任务,而不要求旧 release 健康(前者只报告结果,后者不做检查),因此在其中任何一个运行之后,须自行完成步骤 8 的检查,未通过时手动重新暂停监管。只有切换成功后脚本才改写回执并写出 `Rollback-MasterDeploy.ps1`。复用前检查这些保留的工具:它们含固定的构建哈希与旧版本假设。不得在当前版本已变化时直接执行旧安装脚本,应重新建立身份及回滚检查。 From 46be1dfef62f649236090c21f35d08066fc00cb5 Mon Sep 17 00:00:00 2001 From: anuzzolilli-oss Date: Mon, 16 Nov 2026 21:53:07 -0500 Subject: [PATCH 3/3] docs: correct four deploy-step statements against the scripts (#78) - Step 9: supervisor-status.json has no version or commit field; verify the monitored child and healthMatch there and the version and commit from the health endpoint. The restored proxy may be adopted, not started. - Step 6: the kept script waits 90 s for health only, then checks the process counts once. - Step 8: a candidate proxy exists only if the cutover got that far. - Tooling paragraph: the script's receipt rewrite is the one step 7 describes, not step 10's finalization. Assisted-by: Cindy (https://cindy.app) --- reference/cindy-project.md | 8 ++++---- reference/cindy-project.zh-CN.md | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/reference/cindy-project.md b/reference/cindy-project.md index 4a1f8dbacb..5cb9c7c8a8 100644 --- a/reference/cindy-project.md +++ b/reference/cindy-project.md @@ -89,12 +89,12 @@ The receipt identifies the active release, prior release, bundle hash and backup 3. Build the live bundle from the small local start-up wrapper `live-entry.ts` with the kept esbuild script `build.mjs`, not from the standard CLI entry; building the standard CLI alone does not capture this deployment's runtime policy. Neither file is in the repository: both are in the kept tooling directory named below. Copy the wrapper to `src/live-entry.ts` in a checkout of the pinned source SHA and run `build.mjs` from that checkout's root with the full source SHA as its argument; do not commit the copied files. The wrapper requires an explicit `--port` (it rejects a non-integer value and ports below 1024 or above 65535), then calls `startServer({ ...loadOptions(), host: "127.0.0.1", port, passthrough: false, autoUpdate: false, autoRestartOnUpdate: false }, { boundedMaintenance: { timeoutMs: 15000, maxTokens: 1024 } })` and logs the enabled bounded maintenance. `build.mjs` bundles `src/live-entry.ts` → `out/dist/index.mjs` (bundle/esm/node20, alias `@earendil-works/pi-coding-agent` → `src/agent/pi-host-stub.ts`, external `jimp, mysql2, mysql2/promise, bufferutil, utf-8-validate`, createRequire banner) and writes `out/dist/build-info.json` with `sourceCommit`, `bundleSha256`, `commit` (the first 8 chars plus `-live`) and `localPatchSha256`; record those hashes in the receipt. The candidate folder handed to the cutover holds `dist\index.mjs`, `dist\build-info.json`, `package.json` and `LICENSE`. 4. Hold supervision before editing the launcher, in this order: create `maintenance.inhibit` in the runtime root, which suppresses supervisor adoption, start and restart; disable the scheduled task, whose repeating trigger would otherwise relaunch the supervisor; then stop the supervisor. A monitored child is left running while inhibited, so the old proxy keeps serving: confirm it is still healthy. Editing launcher defaults under a live supervisor is unsafe: adoption is by PID plus process creation time, rechecked after a handle is held, and one supervisor per installation is held by an OS-exclusive lock on `supervisor.lock`, so a second launch exits 0 immediately. The hold is temporary: step 6 lifts it at cutover, and step 8 lifts it again after a rollback. 5. Change only the launcher defaults that identify the release, and nothing else in the launcher: `ProxyPath` and `ExpectedCommit`, plus `ExpectedVersion` when the version changes. They must match the new release, otherwise the supervisor fails closed. Take the new values from the candidate, not from this page: `ProxyPath` is `dist\index.mjs` in the new release directory, `ExpectedCommit` is `commit` in the candidate's `dist\build-info.json`, and `ExpectedVersion` is the version its health endpoint reported in the step 1 isolated test. The values of the release being replaced are the launcher's current defaults; the receipts record the same release in `releaseRoot` and `build` of `tuned-deployment.json` and in `masterDeploy.proxyRelease` of `supervision-receipt.json`, which also carries the version. The kept `Deploy-Master.ps1` rewrites exactly the `ProxyPath` and `ExpectedCommit` lines and stops if its edit would touch any other line, and its health check has one fixed version written into it, so it does not cover a version change. The other defaults stay as they are: `Port` = `8787`, `NodePath` = `C:\Program Files\nodejs\node.exe`, `RestartDelaySeconds` 5, `PollSeconds` 5, `HeartbeatSeconds` 15 and a `-ReportOnly` switch. -6. Cut over only when idle: if any client connection to the live port is open, stand down instead of waiting for requests to drain. Stop only the old proxy, wait for the port to be released, then remove `maintenance.inhibit`, enable the scheduled task and start it. The supervisor then starts the new release itself, because no matching proxy exists and nothing listens on the port; do not start a proxy by hand. With supervision running, expect the supervisor to fail closed on a foreign or unverified listener, unreadable/booting/mismatched health, a matching process that is not listening, missing executables, and inspection errors or timeouts: nothing is killed and nothing is started, and state is rechecked every `PollSeconds` and logged only when it changes. The cutover has succeeded only when health reports the expected version and commit from the single listener's PID, with exactly one proxy process of the new release and exactly one supervisor; the kept script waits up to 90 seconds for that. Otherwise take the rollback branch in step 8. +6. Cut over only when idle: if any client connection to the live port is open, stand down instead of waiting for requests to drain. Stop only the old proxy, wait for the port to be released, then remove `maintenance.inhibit`, enable the scheduled task and start it. The supervisor then starts the new release itself, because no matching proxy exists and nothing listens on the port; do not start a proxy by hand. With supervision running, expect the supervisor to fail closed on a foreign or unverified listener, unreadable/booting/mismatched health, a matching process that is not listening, missing executables, and inspection errors or timeouts: nothing is killed and nothing is started, and state is rechecked every `PollSeconds` and logged only when it changes. The cutover has succeeded only when health reports the expected version and commit from the single listener's PID, with exactly one proxy process of the new release and exactly one supervisor; the kept script waits up to 90 seconds for the health result and then checks the process counts once. Otherwise take the rollback branch in step 8. 7. With supervision running, check the manifest's source identity, single-listener ownership and unchanged configuration hash. Exercise request forwarding, actual folding, exact original text/image retrieval and session-scoped checker logs. Use one small authenticated provider request when authorized. The kept script checks only the health identity and process counts of step 6, then rewrites the receipts and writes `Rollback-MasterDeploy.ps1`, so these checks run after it has finished, and a failure here is rolled back with the receipts already rewritten. -8. If the cutover or these checks fail, roll back under a new hold: create `maintenance.inhibit`, disable the scheduled task, stop the supervisor and then the candidate proxy. Restore the saved launcher, and restore both receipts if they were already rewritten: a failure inside the cutover leaves the receipts untouched, a failure in step 7 after the kept script has finished does not, and `Rollback-MasterDeploy.ps1` in that cutover's backup restores all three files. Editing or restoring the launcher under a live supervisor is unsafe for the same reason as in step 4. Then lift the hold as in step 6, so that the supervisor starts the previous release, and repeat the step 6 success test and the step 7 checks against it. If the restored release fails them too, the rollback has failed: put the hold back (inhibit set, task disabled, supervisor stopped), make no further start, restore or edit attempt, and report to the owner with the evidence: the failed checks, `supervisor.log`, `bili.log` and what, if anything, holds the port. The live proxy then stays unsupervised or down until the owner decides; that is the intended end state, so that nothing restarts a failing proxy in a loop. -9. Confirm that maintenance has ended, on the success path and the rollback path alike: `maintenance.inhibit` is absent, the scheduled task is enabled and exactly one supervisor is running. While that file exists the supervisor refuses adoption, start and restart, so a deployment that leaves it behind has no automatic adoption or restart even when every check passed. Verify the supervisor reports the release now live, candidate or restored: its `supervisor-status.json` state, the expected version and commit, and the PID of the proxy it started. The only exception is the failed rollback in step 8, which deliberately ends with the hold in place. +8. If the cutover or these checks fail, roll back under a new hold: create `maintenance.inhibit`, disable the scheduled task, stop the supervisor and then the candidate proxy if one was started. Restore the saved launcher, and restore both receipts if they were already rewritten: a failure inside the cutover leaves the receipts untouched, a failure in step 7 after the kept script has finished does not, and `Rollback-MasterDeploy.ps1` in that cutover's backup restores all three files. Editing or restoring the launcher under a live supervisor is unsafe for the same reason as in step 4. Then lift the hold as in step 6, so that the supervisor starts the previous release, and repeat the step 6 success test and the step 7 checks against it. If the restored release fails them too, the rollback has failed: put the hold back (inhibit set, task disabled, supervisor stopped), make no further start, restore or edit attempt, and report to the owner with the evidence: the failed checks, `supervisor.log`, `bili.log` and what, if anything, holds the port. The live proxy then stays unsupervised or down until the owner decides; that is the intended end state, so that nothing restarts a failing proxy in a loop. +9. Confirm that maintenance has ended, on the success path and the rollback path alike: `maintenance.inhibit` is absent, the scheduled task is enabled and exactly one supervisor is running. While that file exists the supervisor refuses adoption, start and restart, so a deployment that leaves it behind has no automatic adoption or restart even when every check passed. Verify the supervisor is monitoring the release now live, candidate or restored: `supervisor-status.json` shows a monitored child with `healthMatch` true and no inhibit, its `childPid` is the single listener's PID, and the health endpoint reports the expected version and commit from that PID. The only exception is the failed rollback in step 8, which deliberately ends with the hold in place. 10. On the success path, finalize the deployment receipt and report the deployed SHA, results and rollback location. On the rollback path nothing was deployed: confirm the receipts describe the restored release, and report the failure, the release left live and the backup location. After a failed rollback, report that no release is confirmed live and that the hold is in place. A local proxy deployment does not publish npm packages or update the hosting Cindy application. -Each master cutover keeps its tooling in its own backup: the `tooling\` directory under the backup root that the deployment receipt `tuned-deployment.json` names in `masterBackupRoot`, currently `%APPDATA%\CindyGlobal\billion-context-proxy\backups\before-master-20261114-214204`. It contains exactly `Deploy-Master.ps1`, `build.mjs`, `fold-test.mjs`, `iso-test.mjs` and `live-entry.ts`; the earlier `before-master-20261114-191918` backup holds a byte-identical copy. By step: `iso-test.mjs` and `fold-test.mjs` serve step 1, `live-entry.ts` and `build.mjs` step 3, and `Deploy-Master.ps1` automates the preflight, release directory and backup of step 2, the hold and launcher edit of steps 4–5, the cutover of step 6, the launcher-only rollback of step 8 when the cutover fails, and the receipt rewrite of step 10. Beside `tooling\`, the backup root holds the pre-cutover `Start-BillionContextProxy.ps1`, `proxy.identity.json`, `supervision-receipt.json`, `supervisor-status.json` and `tuned-deployment.json`, and `Rollback-MasterDeploy.ps1`, which undoes that one completed cutover: it restores the launcher and both receipts from that backup and restarts the previous release through the scheduled task. Each backup's rollback script targets its own cutover, so use the one in the backup the receipt names. The live launcher is `Start-BillionContextProxy.ps1` in the runtime root. `Rollback-TunedLiveProxy.ps1` in the same root is a different, deeper rollback: it restores the configuration and the launcher from the receipt's `backupRoot`, the backup taken before the first tuned deployment on 2026-11-07, not the previous release. +Each master cutover keeps its tooling in its own backup: the `tooling\` directory under the backup root that the deployment receipt `tuned-deployment.json` names in `masterBackupRoot`, currently `%APPDATA%\CindyGlobal\billion-context-proxy\backups\before-master-20261114-214204`. It contains exactly `Deploy-Master.ps1`, `build.mjs`, `fold-test.mjs`, `iso-test.mjs` and `live-entry.ts`; the earlier `before-master-20261114-191918` backup holds a byte-identical copy. By step: `iso-test.mjs` and `fold-test.mjs` serve step 1, `live-entry.ts` and `build.mjs` step 3, and `Deploy-Master.ps1` automates the preflight, release directory and backup of step 2, the hold and launcher edit of steps 4–5, the cutover of step 6, the launcher-only rollback of step 8 when the cutover fails, and, straight after the cutover, the receipt rewrite that step 7 describes. Beside `tooling\`, the backup root holds the pre-cutover `Start-BillionContextProxy.ps1`, `proxy.identity.json`, `supervision-receipt.json`, `supervisor-status.json` and `tuned-deployment.json`, and `Rollback-MasterDeploy.ps1`, which undoes that one completed cutover: it restores the launcher and both receipts from that backup and restarts the previous release through the scheduled task. Each backup's rollback script targets its own cutover, so use the one in the backup the receipt names. The live launcher is `Start-BillionContextProxy.ps1` in the runtime root. `Rollback-TunedLiveProxy.ps1` in the same root is a different, deeper rollback: it restores the configuration and the launcher from the receipt's `backupRoot`, the backup taken before the first tuned deployment on 2026-11-07, not the previous release. Steps 4–9 follow the order the kept `Deploy-Master.ps1` implements: the supervisor, not the operator, starts the new release, and health is checked with supervision running. That order is the sanctioned one by owner decision of 2026-11-16 ([#78](https://github.com/anuzzolilli-oss/billion-context/issues/78)); the earlier wording, which started and checked the new proxy by hand under the inhibit, is superseded, and with it the question of how a hand-started proxy comes under supervision. The kept scripts still depart from the steps when a rollback fails. The failure branch of `Deploy-Master.ps1` and `Rollback-MasterDeploy.ps1` both remove the inhibit and start the scheduled task without requiring the previous release to be healthy (the first only reports the result, the second does not check), so after either one, do the step 8 checks yourself and put the hold back by hand if they fail. The script rewrites the receipts and writes `Rollback-MasterDeploy.ps1` only after a successful cutover. Inspect the kept tooling before reuse: it contains pinned build hashes and previous-build assumptions. Do not execute an old installer against a different current release without rebuilding its identity and rollback checks. diff --git a/reference/cindy-project.zh-CN.md b/reference/cindy-project.zh-CN.md index 0629d0a959..8191093bf4 100644 --- a/reference/cindy-project.zh-CN.md +++ b/reference/cindy-project.zh-CN.md @@ -89,12 +89,12 @@ Get-Content (Join-Path $proxyRoot 'tuned-deployment.json') 3. 运行版本的 bundle 由小型本地启动 wrapper `live-entry.ts` 配合保留的 esbuild 脚本 `build.mjs` 构建,而非标准 CLI 入口;只构建标准 CLI 无法体现该部署的运行时策略。这两个文件都不在仓库中:它们位于下文所述的保留工具目录。把 wrapper 复制到已固定源码 SHA 的检出目录中的 `src/live-entry.ts`,在该检出目录的根目录运行 `build.mjs`,并以完整源码 SHA 作为参数;不得提交复制进来的文件。该 wrapper 要求显式 `--port`(拒绝非整数以及小于 1024 或大于 65535 的端口),随后调用 `startServer({ ...loadOptions(), host: "127.0.0.1", port, passthrough: false, autoUpdate: false, autoRestartOnUpdate: false }, { boundedMaintenance: { timeoutMs: 15000, maxTokens: 1024 } })`,并记录已启用的 bounded maintenance。`build.mjs` 打包 `src/live-entry.ts` → `out/dist/index.mjs`(bundle/esm/node20,别名 `@earendil-works/pi-coding-agent` → `src/agent/pi-host-stub.ts`,external 为 `jimp, mysql2, mysql2/promise, bufferutil, utf-8-validate`,带 createRequire banner),并写出 `out/dist/build-info.json`,内含 `sourceCommit`、`bundleSha256`、`commit`(前 8 位加 `-live`)与 `localPatchSha256`;把这些哈希记入回执。交给切换步骤的候选目录包含 `dist\index.mjs`、`dist\build-info.json`、`package.json` 和 `LICENSE`。 4. 编辑 launcher 前必须先暂停监管,顺序如下:在运行根目录创建 `maintenance.inhibit`,该文件会抑制 supervisor 的接管、启动与重启;禁用计划任务,否则其重复触发器会重新拉起 supervisor;然后停止 supervisor。被抑制期间已监控的子进程继续运行,因此旧代理仍在服务:确认它仍然健康。在 supervisor 存活时修改 launcher 默认值不安全:接管按 PID 加进程创建时间进行,并在持有句柄后复核;每个安装只允许一个 supervisor,由 `supervisor.lock` 上的操作系统排他锁保持,因此第二次启动会立即以 0 退出。这一暂停是临时的:步骤 6 在切换时解除,回滚后由步骤 8 再次解除。 5. 仅更改 launcher 中标识 release 的默认值,launcher 的其他内容一律不动:`ProxyPath` 和 `ExpectedCommit`,版本号变化时再加上 `ExpectedVersion`。它们必须与新 release 一致,否则 supervisor 会失败关闭(fail closed)。新值取自候选产物,而非本页:`ProxyPath` 是新 release 目录中的 `dist\index.mjs`,`ExpectedCommit` 是候选产物 `dist\build-info.json` 中的 `commit`,`ExpectedVersion` 是步骤 1 隔离测试中其健康端点报告的版本号。被替换 release 的值即 launcher 当前的默认值;回执也记录同一 release:`tuned-deployment.json` 的 `releaseRoot` 与 `build`,以及 `supervision-receipt.json` 的 `masterDeploy.proxyRelease`(其中还含版本号)。保留的 `Deploy-Master.ps1` 只改写 `ProxyPath` 与 `ExpectedCommit` 两行,若改动会触及其他行则停止,且其健康检查中写死了一个固定版本号,因此不覆盖版本号变化的情况。其余默认值保持不变:`Port` = `8787`、`NodePath` = `C:\Program Files\nodejs\node.exe`、`RestartDelaySeconds` 5、`PollSeconds` 5、`HeartbeatSeconds` 15 及 `-ReportOnly` 开关。 -6. 仅在空闲时切换:只要运行端口上还有客户端连接,就中止,而不是等待请求结束。只停止旧代理,等待端口释放,然后删除 `maintenance.inhibit`、启用计划任务并启动它。此时没有匹配的代理且端口无人监听,因此由 supervisor 自行启动新 release;不得手动启动代理。监管运行期间,遇到外来或未经验证的监听者、不可读/正在启动/不匹配的健康结果、匹配但未监听的进程、缺失的可执行文件,以及检查错误或超时,supervisor 会失败关闭:既不终止也不启动任何进程,状态每 `PollSeconds` 复核一次,且仅在变化时记录日志。只有当健康结果由唯一监听者的 PID 报告预期版本号与 commit,且新 release 的代理进程恰好一个、supervisor 恰好一个时,切换才算成功;保留的脚本为此最多等待 90 秒。否则走步骤 8 的回滚分支。 +6. 仅在空闲时切换:只要运行端口上还有客户端连接,就中止,而不是等待请求结束。只停止旧代理,等待端口释放,然后删除 `maintenance.inhibit`、启用计划任务并启动它。此时没有匹配的代理且端口无人监听,因此由 supervisor 自行启动新 release;不得手动启动代理。监管运行期间,遇到外来或未经验证的监听者、不可读/正在启动/不匹配的健康结果、匹配但未监听的进程、缺失的可执行文件,以及检查错误或超时,supervisor 会失败关闭:既不终止也不启动任何进程,状态每 `PollSeconds` 复核一次,且仅在变化时记录日志。只有当健康结果由唯一监听者的 PID 报告预期版本号与 commit,且新 release 的代理进程恰好一个、supervisor 恰好一个时,切换才算成功;保留的脚本最多等待 90 秒取得该健康结果,随后检查一次进程数量。否则走步骤 8 的回滚分支。 7. 在监管运行的状态下,检查 manifest 源码身份、唯一监听者及配置哈希不变。验证转发、实际折叠、原文/图片精确检索及该测试 session 的检查日志。获授权后可发送一个小型认证提供商请求。保留的脚本只检查步骤 6 的健康身份与进程数量,随后即改写回执并写出 `Rollback-MasterDeploy.ps1`,因此这些检查在脚本结束后进行,此处失败时须在回执已被改写的情况下回滚。 -8. 切换或上述检查失败时,在重新暂停监管后回滚:创建 `maintenance.inhibit`、禁用计划任务、停止 supervisor,再停止候选代理。恢复保存的 launcher,若回执已被改写则一并恢复两份回执:切换过程中失败时回执尚未改动,保留的脚本结束后在步骤 7 失败时则已改写,该次切换备份中的 `Rollback-MasterDeploy.ps1` 会恢复这三个文件。在 supervisor 存活时修改或恢复 launcher,与步骤 4 同理并不安全。随后按步骤 6 的方式解除暂停,由 supervisor 启动旧 release,并对它重做步骤 6 的成功判定与步骤 7 的检查。若恢复后的 release 同样未通过,即回滚失败:重新暂停监管(inhibit 已设、计划任务已禁用、supervisor 已停止),不再尝试任何启动、恢复或编辑,并携带证据向所有者报告:未通过的检查、`supervisor.log`、`bili.log`,以及端口当前由谁占用(如有)。此后运行中的代理处于无人监管或停止状态,直至所有者决定;这是有意设定的终态,以免失败的代理被反复重启。 -9. 确认维护状态已结束,成功路径与回滚路径同样适用:`maintenance.inhibit` 不存在、计划任务已启用,且恰好有一个 supervisor 在运行。该文件存在期间 supervisor 拒绝接管、启动与重启,因此遗留该文件的部署即使通过全部检查,也没有自动接管与重启。确认 supervisor 报告的是当前运行的 release(候选版本或已恢复版本):其 `supervisor-status.json` 状态、预期版本号与 commit,以及它所启动代理的 PID。唯一的例外是步骤 8 的回滚失败,它有意以暂停监管的状态结束。 +8. 切换或上述检查失败时,在重新暂停监管后回滚:创建 `maintenance.inhibit`、禁用计划任务、停止 supervisor,再停止已启动的候选代理(如有)。恢复保存的 launcher,若回执已被改写则一并恢复两份回执:切换过程中失败时回执尚未改动,保留的脚本结束后在步骤 7 失败时则已改写,该次切换备份中的 `Rollback-MasterDeploy.ps1` 会恢复这三个文件。在 supervisor 存活时修改或恢复 launcher,与步骤 4 同理并不安全。随后按步骤 6 的方式解除暂停,由 supervisor 启动旧 release,并对它重做步骤 6 的成功判定与步骤 7 的检查。若恢复后的 release 同样未通过,即回滚失败:重新暂停监管(inhibit 已设、计划任务已禁用、supervisor 已停止),不再尝试任何启动、恢复或编辑,并携带证据向所有者报告:未通过的检查、`supervisor.log`、`bili.log`,以及端口当前由谁占用(如有)。此后运行中的代理处于无人监管或停止状态,直至所有者决定;这是有意设定的终态,以免失败的代理被反复重启。 +9. 确认维护状态已结束,成功路径与回滚路径同样适用:`maintenance.inhibit` 不存在、计划任务已启用,且恰好有一个 supervisor 在运行。该文件存在期间 supervisor 拒绝接管、启动与重启,因此遗留该文件的部署即使通过全部检查,也没有自动接管与重启。确认 supervisor 正在监控当前运行的 release(候选版本或已恢复版本):`supervisor-status.json` 显示一个受监控的子进程,`healthMatch` 为 true 且无 inhibit,其 `childPid` 即唯一监听者的 PID,且健康端点由该 PID 报告预期版本号与 commit。唯一的例外是步骤 8 的回滚失败,它有意以暂停监管的状态结束。 10. 成功路径:完成部署回执,报告已部署的 SHA、结果及回滚位置。回滚路径:没有完成任何部署,确认回执描述的是已恢复的 release,并报告失败、保持运行的 release 及备份位置。回滚失败时:报告没有任何 release 被确认在运行,且监管处于暂停状态。本地代理部署不包含 npm 发包或更新承载任务的 Cindy 应用。 -每次 master 切换都把工具保留在各自的备份中:即部署回执 `tuned-deployment.json` 的 `masterBackupRoot` 所指备份根目录下的 `tooling\` 目录,当前为 `%APPDATA%\CindyGlobal\billion-context-proxy\backups\before-master-20261114-214204`。其中恰好包含 `Deploy-Master.ps1`、`build.mjs`、`fold-test.mjs`、`iso-test.mjs` 和 `live-entry.ts`;更早的 `before-master-20261114-191918` 备份中有一份逐字节相同的副本。按步骤对应:`iso-test.mjs` 与 `fold-test.mjs` 用于步骤 1,`live-entry.ts` 与 `build.mjs` 用于步骤 3,`Deploy-Master.ps1` 自动完成步骤 2 的预检、release 目录与备份,步骤 4–5 的暂停监管与 launcher 编辑,步骤 6 的切换,切换失败时步骤 8 中仅恢复 launcher 的回滚,以及步骤 10 的回执改写。在 `tooling\` 旁边,该备份根目录保存切换前的 `Start-BillionContextProxy.ps1`、`proxy.identity.json`、`supervision-receipt.json`、`supervisor-status.json` 和 `tuned-deployment.json`,以及 `Rollback-MasterDeploy.ps1`;后者撤销这一次已完成的切换:从该备份恢复 launcher 与两份回执,并通过计划任务重启旧 release。每个备份中的回滚脚本只针对它自己的那次切换,因此应使用回执所指备份中的那一个。运行中的 launcher 是运行根目录中的 `Start-BillionContextProxy.ps1`。同一根目录下的 `Rollback-TunedLiveProxy.ps1` 是另一种更深的回滚:它从回执的 `backupRoot`(2026-11-07 首次 tuned 部署之前的备份)恢复配置与 launcher,而不是回到上一个 release。 +每次 master 切换都把工具保留在各自的备份中:即部署回执 `tuned-deployment.json` 的 `masterBackupRoot` 所指备份根目录下的 `tooling\` 目录,当前为 `%APPDATA%\CindyGlobal\billion-context-proxy\backups\before-master-20261114-214204`。其中恰好包含 `Deploy-Master.ps1`、`build.mjs`、`fold-test.mjs`、`iso-test.mjs` 和 `live-entry.ts`;更早的 `before-master-20261114-191918` 备份中有一份逐字节相同的副本。按步骤对应:`iso-test.mjs` 与 `fold-test.mjs` 用于步骤 1,`live-entry.ts` 与 `build.mjs` 用于步骤 3,`Deploy-Master.ps1` 自动完成步骤 2 的预检、release 目录与备份,步骤 4–5 的暂停监管与 launcher 编辑,步骤 6 的切换,切换失败时步骤 8 中仅恢复 launcher 的回滚,以及切换后随即进行的、步骤 7 所述的回执改写。在 `tooling\` 旁边,该备份根目录保存切换前的 `Start-BillionContextProxy.ps1`、`proxy.identity.json`、`supervision-receipt.json`、`supervisor-status.json` 和 `tuned-deployment.json`,以及 `Rollback-MasterDeploy.ps1`;后者撤销这一次已完成的切换:从该备份恢复 launcher 与两份回执,并通过计划任务重启旧 release。每个备份中的回滚脚本只针对它自己的那次切换,因此应使用回执所指备份中的那一个。运行中的 launcher 是运行根目录中的 `Start-BillionContextProxy.ps1`。同一根目录下的 `Rollback-TunedLiveProxy.ps1` 是另一种更深的回滚:它从回执的 `backupRoot`(2026-11-07 首次 tuned 部署之前的备份)恢复配置与 launcher,而不是回到上一个 release。 步骤 4–9 采用保留的 `Deploy-Master.ps1` 所实现的顺序:由 supervisor 而非操作者启动新 release,健康检查在监管运行的状态下进行。依据所有者 2026-11-16 的决定([#78](https://github.com/anuzzolilli-oss/billion-context/issues/78)),这是认可的顺序;此前在 inhibit 下手动启动并检查新代理的写法已被取代,手动启动的代理如何纳入监管的问题也随之不复存在。回滚失败时,保留的脚本仍与上述步骤不同。`Deploy-Master.ps1` 的失败分支与 `Rollback-MasterDeploy.ps1` 都会删除 inhibit 并启动计划任务,而不要求旧 release 健康(前者只报告结果,后者不做检查),因此在其中任何一个运行之后,须自行完成步骤 8 的检查,未通过时手动重新暂停监管。只有切换成功后脚本才改写回执并写出 `Rollback-MasterDeploy.ps1`。复用前检查这些保留的工具:它们含固定的构建哈希与旧版本假设。不得在当前版本已变化时直接执行旧安装脚本,应重新建立身份及回滚检查。