Repository navigation
Description
(ai: anthropic/claude-fable-5-2)
Follow-up to #74 / #77. A review of the merged deploy procedure in reference/cindy-project.md (and reference/cindy-project.zh-CN.md), checked against the kept deployment tooling on the machine on 2026-11-16, found the gaps below. Docs only. Nothing was run against the live proxy; every file was only read.
A. Open decision for the owner: the steps and the kept script disagree at cutover
Steps 6–9 on master describe this order: supervision stays stopped and inhibited, the new proxy is started and checked, a failed canary is rolled back while still inhibited, and only then is maintenance.inhibit removed and the supervisor restarted (step 9).
The kept Deploy-Master.ps1 does it differently. Its section "4. cut over" stops the old proxy, then removes maintenance.inhibit, enables and starts the scheduled task, and waits up to 90 s for the supervisor to bring the new release up healthy. No proxy is started by hand, and supervision is running during the health check. Its failure branch re-creates the inhibit, disables the task, stops the supervisor and the new proxy, restores the saved launcher, removes the inhibit and starts the task again, then reports whether the old release came back healthy and rethrows either way.
supervision-receipt.json records the 2026-11-14 21:42 deployment of d4aad618-live as "ProxyPath and ExpectedCommit defaults only", which matches that script's two-line launcher edit.
So the page currently documents a manual-start, canary-under-inhibit model, while the tooling it points at implements a supervisor-start model. Both were reviewed: the steps on #77, the script by being the thing that ran. Which one is the sanctioned procedure is not something to guess. Until it is decided, these items stay open:
- Step 6 says state "is rechecked every
PollSeconds" and "Restart only that proxy". Under the step model the supervisor is stopped at that point, so nothing is rechecking, and the restart would have to be a manual start that the step does not describe. Under the script model the supervisor does the start. - Failed rollback has no defined end. Step 9 leaves maintenance only once the release that stays live has passed its checks. If the restored release also fails, the steps say nothing and the inhibit stays. The script's answer is different again: it re-enables supervision whether or not the old release is healthy.
- Whether the launcher header's adoption rule (a healthy single listener with the expected command line, version, commit and PID is adopted rather than rivalled) is the intended way a manually started proxy comes under supervision in step 9.
B. Gaps that do not depend on that decision
- Tooling is not tied to the steps. Docs: live-proxy deployment snapshot and procedure are out of date after the 2026-11-14 master deployment #74 asked for the steps to point at the kept tooling. Only step 3 names a tool.
iso-test.mjs(isolated boot/forwarding check) andfold-test.mjs(isolated fold/retrieval check) run a candidate bundle on their own port with a loopback upstream, so they belong to step 1;Deploy-Master.ps1andRollback-MasterDeploy.ps1are not attached to any step. - Tooling path and label. The page gives
backups\before-master-20261114-191918\tooling\and calls it tooling "from the initial repair". The deployment the snapshot records has its own backup,before-master-20261114-214204, named by the receipt'smasterBackupRoot; it holds a byte-identical copy of the tooling and that deployment's ownRollback-MasterDeploy.ps1. The rollback script in-191918belongs to the earlier cutover. - Build ordering and file locations. Step 1 says to build and test the candidate, but the recipe is in step 3, after step 2 prepares the release directory.
src/live-entry.tsandbuild.mjsread as repository paths; neither is in the repository.build.mjsexpects the wrapper atsrc/live-entry.tsof the source tree it is run in and takes the source SHA as its argument; the deploy script expects a candidate folder holdingdist\index.mjs,dist\build-info.json,package.jsonandLICENSE. None of that is stated. - Step 5 contradicts itself. "Change only the existing proxy's release path" is followed by three defaults that "must be changed". The kept script edits exactly two lines (
ProxyPath,ExpectedCommit) and stops if the edit would touch more, so a release with a new version needsExpectedVersionchanged separately. - Two different rollbacks are described as one, and step 10 is undefined after a rollback. Step 8 says "restore the saved launcher and receipt". During a failed cutover the receipts have not been rewritten yet, so only the launcher needs restoring.
Rollback-MasterDeploy.ps1is the after-the-fact rollback of a completed deployment and restores the launcher and both receipts. Step 10 then says "Finalize the deployment receipt and report the deployed SHA" without saying what that means when nothing was deployed. Rollback-TunedLiveProxy.ps1is misdescribed. The page says it "rolls that launcher back". It restores the config and the launcher from the receipt'sbackupRoot, which is the 2026-11-07 pre-tuning backup: a return to the original startup, not to the previous release.- en/zh drift in step 9. English: "the expected version and commit". Chinese: "预期版本号与运行 commit" (running commit), plus an extra "(候选版本或已恢复的旧版本)" in the first sentence.
- Snapshot history skips a build.
docs/cindy-project.mdrecordsd4aad618-liveand lists51a1cdbf-liveas superseded. The receipt's previous build is4b6687bc-live(the build Docs: live-proxy deployment snapshot and procedure are out of date after the 2026-11-14 master deployment #74 named), which appears nowhere on the page.
Suggested change
Fix section B in both languages now. For section A, state on the page what the kept script does and where it differs from the steps, and rewrite steps 6–9 only once the owner has chosen the model.
Not in scope: the items the review listed as additions beyond #74 (the SHA-pinning precondition, the supervisor internals in steps 4 and 6). They are not gaps. The release identity 0.1.213 / d4aad618-live is repeated in several places across both pages; pointing step 5 at the receipt would cut the edits needed at the next deployment, optional.
Activity
anuzzolilli-oss commentedon Nov 16, 2026
(ai: anthropic/claude-fable-5-2)
Draft PR for section B: #79. It also states on the page what the kept script does at cutover, without rewriting steps 6–9. It stays a draft until the section A decision is made.
docs: deploy steps follow the supervisor-start cutover order (#78)
anuzzolilli-oss commentedon Nov 17, 2026
(ai: anthropic/claude-fable-5-2)
Owner decisions on section A, given in chat on 2026-11-16 and recorded here:
Deploy-Master.ps1implements is the sanctioned one (the supervisor starts the new release; health is checked with supervision running).The third open bullet in section A (adoption of a hand-started proxy) no longer applies under this order.
Implemented in commit
22d4580abon PR #79, which now closes this issue.docs: correct four deploy-step statements against the scripts (#78)
Merge pull request #79 from anuzzolilli-oss/2026-11-16_deploy-procedu…