diff --git a/docs/cindy-project.md b/docs/cindy-project.md index fe22e9f047..60485b77f0 100644 --- a/docs/cindy-project.md +++ b/docs/cindy-project.md @@ -23,7 +23,9 @@ The development checkout holds source, local dependencies and test/build outputs The live proxy runs from a separate release directory under `%APPDATA%\CindyGlobal\billion-context-proxy`, managed by the existing scheduled task **Cindy - billion-context proxy**. It listens on `127.0.0.1:8787`. Building or testing the checkout does not deploy a release. -As verified on 2026-11-08, live build `51a1cdbf-live` uses reviewed source `51a1cdbf4e732bfe9cedae73aec8aee53ec20599`. Its Git tree matches merged PR [#1](https://github.com/anuzzolilli-oss/billion-context/pull/1), merge commit `d6573a0881feb6102a3353e50060d07bf26099d9`. Treat these as a dated deployment snapshot; check the live manifest and deployment receipt before future operations. +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. ### Live OmniRoute routing — verified 2026-11-15 diff --git a/docs/cindy-project.zh-CN.md b/docs/cindy-project.zh-CN.md index 09f5e6a41a..0fcffc4a69 100644 --- a/docs/cindy-project.zh-CN.md +++ b/docs/cindy-project.zh-CN.md @@ -23,7 +23,9 @@ 运行中的代理使用 `%APPDATA%\CindyGlobal\billion-context-proxy` 下独立的 release 目录,由现有计划任务 **Cindy - billion-context proxy** 管理,监听 `127.0.0.1:8787`。在开发目录构建或测试不会部署版本。 -2026-11-08 验证的运行版本是 `51a1cdbf-live`,对应已评审源码 `51a1cdbf4e732bfe9cedae73aec8aee53ec20599`。其 Git tree 与已合并的 PR [#1](https://github.com/anuzzolilli-oss/billion-context/pull/1) 相同,合并提交为 `d6573a0881feb6102a3353e50060d07bf26099d9`。这是带日期的部署快照;后续操作前重新检查运行 manifest 与部署回执。 +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`。该状态已不再描述运行中的服务。 ### 运行中的 OmniRoute 路由——2026-11-15 已验证 diff --git a/reference/cindy-project.md b/reference/cindy-project.md index ec6cbdd98a..6e924bc219 100644 --- a/reference/cindy-project.md +++ b/reference/cindy-project.md @@ -84,10 +84,15 @@ The receipt identifies the active release, prior release, bundle hash and backup ## Deploy only with an explicit request -1. Pin the 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 and record its hash and any local runtime wrapper. Test that exact artifact in an isolated process using generated data and a loopback upstream. 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. Change only the existing proxy's release path. Restart only that proxy after active requests drain. On startup failure, restore the saved launcher/receipt and restart the previous release. -4. 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. -5. Finalize the deployment receipt and report the deployed SHA, results and rollback location. If the canary fails, restore the previous release and report the failure. A local proxy deployment does not publish npm packages or update the hosting Cindy application. - -Deployment tooling and detailed historical logs from the initial repair remain in the original task's `inspection-evidence` directory. Inspect them before reuse: they contain 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. +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. +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. +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. +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. + +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. diff --git a/reference/cindy-project.zh-CN.md b/reference/cindy-project.zh-CN.md index db2c9331d8..c6ac4712b4 100644 --- a/reference/cindy-project.zh-CN.md +++ b/reference/cindy-project.zh-CN.md @@ -84,10 +84,15 @@ Get-Content (Join-Path $proxyRoot 'tuned-deployment.json') ## 仅在明确请求时部署 -1. 固定已评审源码 SHA,并检查该 SHA 的 CI 与评审。构建独立候选产物,记录哈希及本地运行 wrapper;使用生成数据和回环模拟上游,在隔离进程中测试同一产物。 +1. 固定人工合并后已评审的源码 SHA,并检查该准确 SHA 的 CI 与评审结果。构建独立候选产物,记录其哈希及任何本地运行 wrapper;使用生成数据和回环模拟上游,在隔离进程中测试该同一产物。 2. 验证现有 supervisor、配置哈希、监听 PID/进程身份及空闲状态。准备新的 release 目录,备份 supervisor 和部署回执;保留认证、设置、原文及计划任务的登录启动/恢复职责。 -3. 仅更改现有代理的 release 路径。等待活跃请求结束后只重启该代理。启动失败时恢复保存的 launcher/回执,并重启旧版本。 -4. 检查 manifest 源码身份、唯一监听者及配置哈希不变。验证转发、实际折叠、原文/图片精确检索及该测试 session 的检查日志。获授权后可发送一个小型认证提供商请求。 -5. 完成部署回执,报告源码 SHA、结果及回滚位置。Canary 失败则恢复旧版本并报告。本地代理部署不包含 npm 发包或更新承载任务的 Cindy 应用。 - -初次修复的部署工具和详细历史日志保留在原任务的 `inspection-evidence` 目录。复用前检查其固定哈希和旧版本假设;不得在当前版本已变化时直接执行旧安装脚本,应重新建立身份及回滚检查。 +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`;把这些哈希记入回执。 +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` 开关。 +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 应用。 + +初次修复的部署工具保留在 `%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。复用前检查这些保留的工具:它们含固定的构建哈希与旧版本假设。不得在当前版本已变化时直接执行旧安装脚本,应重新建立身份及回滚检查。