Skip to content

Docs: deploy procedure and kept tooling disagree at cutover; remaining gaps after #77 #78

Closed

Description

@anuzzolilli-oss

(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

  1. 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) and fold-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.ps1 and Rollback-MasterDeploy.ps1 are not attached to any step.
  2. 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's masterBackupRoot; it holds a byte-identical copy of the tooling and that deployment's own Rollback-MasterDeploy.ps1. The rollback script in -191918 belongs to the earlier cutover.
  3. 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.ts and build.mjs read as repository paths; neither is in the repository. build.mjs expects the wrapper at src/live-entry.ts of the source tree it is run in and takes the source SHA as its argument; the deploy script expects a candidate folder holding dist\index.mjs, dist\build-info.json, package.json and LICENSE. None of that is stated.
  4. 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 needs ExpectedVersion changed separately.
  5. 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.ps1 is 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.
  6. Rollback-TunedLiveProxy.ps1 is misdescribed. The page says it "rolls that launcher back". It restores the config and the launcher from the receipt's backupRoot, which is the 2026-11-07 pre-tuning backup: a return to the original startup, not to the previous release.
  7. en/zh drift in step 9. English: "the expected version and commit". Chinese: "预期版本号与运行 commit" (running commit), plus an extra "(候选版本或已恢复的旧版本)" in the first sentence.
  8. Snapshot history skips a build. docs/cindy-project.md records d4aad618-live and lists 51a1cdbf-live as superseded. The receipt's previous build is 4b6687bc-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

  1. anuzzolilli-oss commented on Nov 16, 2026

    @anuzzolilli-oss
    OwnerAuthor

    (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.

  2. anuzzolilli-oss commented on Nov 17, 2026

    @anuzzolilli-oss
    OwnerAuthor

    (ai: anthropic/claude-fable-5-2)

    Owner decisions on section A, given in chat on 2026-11-16 and recorded here:

    1. Cutover order: the order the kept Deploy-Master.ps1 implements is the sanctioned one (the supervisor starts the new release; health is checked with supervision running).
    2. Failed rollback: stay inhibited and escalate to the owner. Written on the page as: if the restored release also fails its checks, put the hold back (inhibit set, task disabled, supervisor stopped), attempt nothing further and report with the evidence. The kept scripts re-enable supervision regardless; the page says so and they were not edited.
    3. Release identity: step 5 points at the candidate and the receipts instead of repeating the current values.

    The third open bullet in section A (adoption of a hand-started proxy) no longer applies under this order.

    Implemented in commit 22d4580ab on PR #79, which now closes this issue.

  3. added 2 commits that reference this issue on Nov 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions