Repository navigation
docs: record the current live-proxy snapshot and the supervised deploy procedure (#74) - #77
Conversation
…y procedure (#74) docs/cindy-project.md still named the 2026-11-08 build `51a1cdbf-live` as the live service, directly contradicting the `0.1.213` / `d4aad618-live` section added below it by #76. The dated snapshot now states the current verified state read from the deployment receipt: build `d4aad618-live`, version `0.1.213`, source `d4aad6189a7456059b12c7333662f499c633ca0c` (merge commit of #73), deployed 2026-11-14, rollback backup `backups\before-master-20261114-214204`. The earlier build is kept as explicitly superseded history rather than deleted. reference/cindy-project.md's "Deploy only with an explicit request" predated the adopting supervisor installed 2026-11-10 and is rewritten to the procedure actually used, adding what it omitted: - the live bundle is built from the local start-up wrapper `src/live-entry.ts` via the kept esbuild `build.mjs`, not the standard CLI entry; - the supervisor must be stopped and `maintenance.inhibit` created before the launcher is edited, since one supervisor per install holds an exclusive lock on `supervisor.lock` and adopts by PID plus process creation time; - the launcher's `ProxyPath`, `ExpectedVersion` and `ExpectedCommit` defaults must move with the release, otherwise the supervisor fails closed; - the fail-closed conditions, so a mismatch is not retried into a start; - the real tooling location. The pointer to an `inspection-evidence` directory named a path that does not exist; it now points at `backups\before-master-20261114-191918\tooling\` with the rollback script beside it. No safety gate is weakened and no config or env surface changes: this documents existing behaviour. en/zh parity applied to both pages. Docs only; no source or test changes. Verified: node tools/check-architecture-docs.mjs, npm run typecheck, git diff --check. Every concrete value was read from the live machine (tuned-deployment.json, Start-BillionContextProxy.ps1 and the kept tooling) on 2026-11-16, not carried over from the issue text, which names the superseded `4b6687bc-live`. Assisted-by: Cindy (https://cindy.app)
📦 Built Package ArtifactBranch: Download artifact
tar xzf billion-context-pr77.tgz
npm install -g packageInstall instructions are refreshed on each push. |
|
|
||
| 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. |
There was a problem hiding this comment.
(ai: openai/gpt-6-astra)
WARNING: Restore supervision after leaving maintenance
Step 4 stops the supervisor and creates maintenance.inhibit, but steps 5-8 never remove that file or restart the supervisor, including on rollback. Following the documented sequence therefore leaves supervisor-driven starts blocked by the stated inhibit behavior; even a manually restarted proxy that passes the canary remains without automatic adoption/restart. Add an explicit maintenance-exit step on both success and rollback: remove the inhibit at the appropriate cutover point, restart the existing supervisor/task, and verify that it supervises the expected release before finalizing the receipt.
Code Review Summary(ai: openai/gpt-6-astra) Status: No Issues Found | Recommendation: Merge Light incremental review of the maintenance-exit procedure at Files Reviewed (1 file)
Static documentation review only; no code or deployment commands were executed. Live-machine tooling and behavior were not independently verified. Previous Review Summaries (2 snapshots, latest commit 389715a)Current summary above is authoritative. Previous snapshots are kept for context only. Previous review (commit 389715a)(ai: openai/gpt-6-astra) Status: 1 Issue Found | Recommendation: Address before merge OverviewLight incremental pass over the maintenance-exit procedure at
Issue Details (click to expand)WARNING
Files Reviewed (1 file)
Static documentation review only; no code or deployment commands were executed. Live-machine tooling and behavior were not independently verified. Previous review (commit 2fa861d)(ai: openai/gpt-6-astra) Status: 1 Issue Found | Recommendation: Address before merge OverviewLight pass over the live-service snapshot and deployment procedure at
Issue Details (click to expand)WARNING
Files Reviewed (2 files)
Static review only; no code or deployment commands were executed. Live-machine receipts and scripts were unavailable, so deployment-state claims were not independently verified. Reviewed by gpt-6-astra · Input: 33 · Output: 3K · Cached: 378.9K Review guidance: REVIEW.md from base branch |
…74) Review finding on #77: step 4 creates `maintenance.inhibit` but no later step removed it. The documented sequence therefore ended with supervisor-driven adoption, start and restart still suppressed, leaving a proxy that passed the canary but ran unsupervised. Add step 8, which removes the inhibit and restarts the supervisor through its scheduled task on both the success path and rollback, then verifies the supervisor reports the expected release: `supervisor-status.json` state, expected version and commit, and the adopted listener PID. Step 4 now names the inhibit as temporary and points at the step that clears it. Verified against the launcher's own inhibit handling in `Start-BillionContextProxy.ps1` (adoption refused, start skipped, monitored child left running with no restart after exit while the file exists) and against the live runtime root, which currently holds no `maintenance.inhibit`. en/zh parity kept: 9 steps in both files, same structure. Docs only. Verified: node tools/check-architecture-docs.mjs, git diff --check. Assisted-by: Cindy (https://cindy.app)
| 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, restore the saved launcher/receipt and restart the previous release. | ||
| 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. Leave maintenance before finalizing, on the success path and on rollback 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 expected release: its `supervisor-status.json` state, the expected version and commit, and the listener PID it adopted. |
There was a problem hiding this comment.
(ai: openai/gpt-6-astra)
WARNING: Complete canary-failure rollback before restarting supervision
If the candidate starts but fails the checks in step 7, the numbered sequence now removes maintenance.inhibit and restarts the supervisor in step 8, before step 9 restores the previous release. That puts the rollback's launcher changes under a live supervisor, contrary to step 4's explicit safety requirement; the supervisor still has the candidate's release defaults and can fail closed on the restored listener as described in steps 5-6. Move the canary-failure branch before this shared maintenance-exit step: restore the saved launcher/receipt and previous release while supervision remains stopped and inhibited, then restart the supervisor and verify the restored release before finalizing.
…74) Second review finding on #77: the previous commit put the maintenance-exit step before the rollback, so on a canary failure the sequence removed `maintenance.inhibit` and restarted the supervisor first, then restored the previous release. That put the rollback's launcher edits under a live supervisor, contrary to step 4's own safety requirement, and the launcher still carried the candidate's release defaults, so the supervisor could fail closed on the restored listener for the reasons steps 5 and 6 describe. Reorder so the rollback branch completes while supervision is still stopped and inhibited: - step 8 is now the canary-failure branch: restore the saved launcher and receipt, restore the previous release, restart it, repeat the step 7 checks against it, then report the failure; - step 9 leaves maintenance once whichever release is to stay live — candidate or restored — has passed its checks, and verifies the supervisor reports that release; - step 10 finalizes the receipt. Step 6 also carried the pre-existing "on startup failure, restore the saved launcher/receipt and restart the previous release" clause, which duplicated and under-specified the new step 8; it now points at that branch instead. Step 4's cross-reference follows the renumbering. Docs only. en/zh parity kept: 10 steps in both files, same order and the same cross-references. Verified: node tools/check-architecture-docs.mjs, git diff --check. Assisted-by: Cindy (https://cindy.app)
Scope
Closes #74. Docs only: four files, no source or test changes, no config/env surface change, no safety gate weakened.
docs/cindy-project.md+docs/cindy-project.zh-CN.mdreference/cindy-project.md+reference/cindy-project.zh-CN.mdWhat was wrong
A live contradiction on the docs page.
docs/cindy-project.mdstill named the 2026-11-08 build51a1cdbf-liveas the live service, while the section directly below it — added by #76 — says live is0.1.213/d4aad618-live. Two adjacent paragraphs disagreed about what is running.A deploy procedure that predates the supervisor.
reference/cindy-project.md's "Deploy only with an explicit request" was written before the adopting supervisor installed 2026-11-10. It omittedmaintenance.inhibit, the launcher defaults that must move with the release, the requirement to stop the supervisor before editing the launcher, and the fact that the live bundle is built from a local start-up wrapper rather than the standard CLI entry.A pointer to a directory that does not exist. The procedure told the reader to inspect the original task's
inspection-evidencedirectory before reusing the tooling. That path could not be found, so the instruction was unactionable.What changed
The dated snapshot now states the current verified state, and the earlier build is kept as explicitly superseded history rather than deleted, so the page no longer contradicts itself.
The deploy procedure is rewritten to eight steps matching what was actually done on 2026-11-14, adding:
src/live-entry.tsvia the kept esbuildbuild.mjs, not the standard CLI entry — building the standard CLI alone does not capture this deployment's runtime policy;maintenance.inhibitcreated before the launcher is edited, since one supervisor per install holds an exclusive lock onsupervisor.lockand adopts by PID plus process creation time;ProxyPath,ExpectedVersionandExpectedCommitdefaults must move with the release, otherwise the supervisor fails closed;backups\before-master-20261114-191918\tooling\, with the rollback script beside it.en/zh parity applied to both pages: same facts, same step count (8/8), same heading structure.
Evidence basis — read from the machine, not from the issue
The issue body is itself out of date. #74 names
4b6687bc-liveas the live build, but live moved again tomaster-d4aad618on 2026-11-14 21:42 EST, and the upstream config changed on 2026-11-15. Every concrete value in this PR was read from the live machine on 2026-11-16 rather than carried over from the issue text:d4aad618-live, version0.1.213tuned-deployment.json, launcherExpectedVersion/ExpectedCommitd4aad6189a7456059b12c7333662f499c633ca0ctuned-deployment.jsonsourceCommitbefore-master-20261114-214204tuned-deployment.jsonmasterBackupRoot; directory existsRollback-MasterDeploy.ps1ProxyPath,Port,NodePath, poll/heartbeat defaultsStart-BillionContextProxy.ps1param block, quoted exactlymaintenance.inhibit,supervisor.lock, fail-closed conditionsstartServeroptions,boundedMaintenancetooling\live-entry.tsbuild-info.jsonfieldstooling\build.mjsConfig SHA-256 hashes are recorded; no credentials, keys or DPAPI-protected config contents appear.
Out of scope and untouched: the
inspection-evidencereferences inreference/eph02-evaluation.mdandreference/maintenance-safety-evaluation.md, which are different tasks' evidence. Also untouched: the "### Live OmniRoute routing — verified 2026-11-15" section from #76, and the existing "Inspect the live proxy" command block.Verification
node tools/check-architecture-docs.mjs— all green (308 src files covered, no ghosts; ledger 8/8 active)npm run typecheck— clean (confirms no accidental source change)git diff --check— cleandocs/index*.mdneeds no edit; both pages were already indexedNothing was executed against the live proxy and port 8787 was not touched. No deployment claim is made here: this documents state, it does not change it.
Not addressed by this PR
#61 and #55 were left as evidence-watch, per their current owner-deferred states — #61's runner-side stall watch already landed in #72 and the remaining scope waits on a future stall producing a process list; #55 is narrowed but unestablished, with the suggested next step being a machine-side
LocalDumpscapture rather than a repo change.One latent item surfaced while reading #55 and deliberately not folded in here, to keep one issue = one scope: a
0xC0000005native crash currently classifies as the retryableswallowedshape inscripts/ci-failure-shapes.mjs, so it can pass green after a retry. That is a CI-classifier question with its own owner gate, not a docs change.