Skip to content

docs: record the current live-proxy snapshot and the supervised deploy procedure (#74) - #77

Merged
anuzzolilli-oss merged 3 commits into
masterfrom
2026-11-16_cindy-project-docs-live-snapshot
Nov 16, 2026
Merged

anuzzolilli-oss merged 3 commits into
masterfrom
2026-11-16_cindy-project-docs-live-snapshot

Conversation

@anuzzolilli-oss

Copy link
Copy Markdown
Owner

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.md
  • reference/cindy-project.md + reference/cindy-project.zh-CN.md

What was wrong

A live contradiction on the docs page. docs/cindy-project.md still named the 2026-11-08 build 51a1cdbf-live as the live service, while the section directly below it — added by #76 — says live is 0.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 omitted maintenance.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-evidence directory 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:

  • 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 — building the standard CLI alone does not capture this deployment's runtime policy;
  • 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 an operator reading a mismatch does not retry their way into a start;
  • the real tooling location, 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-live as the live build, but live moved again to master-d4aad618 on 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:

Claim Source
build d4aad618-live, version 0.1.213 tuned-deployment.json, launcher ExpectedVersion/ExpectedCommit
source d4aad6189a7456059b12c7333662f499c633ca0c tuned-deployment.json sourceCommit
rollback backup before-master-20261114-214204 tuned-deployment.json masterBackupRoot; directory exists
tooling dir + its 5 files, Rollback-MasterDeploy.ps1 directory listing
ProxyPath, Port, NodePath, poll/heartbeat defaults Start-BillionContextProxy.ps1 param block, quoted exactly
maintenance.inhibit, supervisor.lock, fail-closed conditions launcher header comments
wrapper port validation, startServer options, boundedMaintenance tooling\live-entry.ts
esbuild flags, alias, externals, build-info.json fields tooling\build.mjs

Config SHA-256 hashes are recorded; no credentials, keys or DPAPI-protected config contents appear.

Out of scope and untouched: the inspection-evidence references in reference/eph02-evaluation.md and reference/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 — clean
  • en/zh parity audited per fact: occurrence counts symmetric across both language pairs
  • No new or moved docs, so docs/index*.md needs no edit; both pages were already indexed

Nothing 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 LocalDumps capture 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 0xC0000005 native crash currently classifies as the retryable swallowed shape in scripts/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.

…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)
@anuzzolilli-oss
anuzzolilli-oss marked this pull request as ready for review November 16, 2026 07:49
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

📦 Built Package Artifact

Branch: 2026-11-16_cindy-project-docs-live-snapshot (577047f)

Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr77.tgz
npm install -g package

Install instructions are refreshed on each push.

Comment thread reference/cindy-project.md Outdated

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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@kilo-code-bot

kilo-code-bot Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Code Review Summary

(ai: openai/gpt-6-astra)

Status: No Issues Found | Recommendation: Merge

Light incremental review of the maintenance-exit procedure at 577047fbb5ada73739d8499664a0c8739f2d8759. The translated counterpart is present; its contents were skipped per REVIEW.md.

Files Reviewed (1 file)
  • reference/cindy-project.md

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

Overview

Light incremental pass over the maintenance-exit procedure at 389715a7f17dcb7ca87dc52010acbd75ab0ecf2b. The translated counterpart is present; its contents were skipped per REVIEW.md.

Severity Count
CRITICAL 0
WARNING 1
SUGGESTION 0
Issue Details (click to expand)

WARNING

File Line Issue
reference/cindy-project.md 94 Step 8 restarts supervision before step 9 performs canary-failure rollback, putting launcher restoration under a live supervisor with the candidate's defaults. Restore the previous release while stopped/inhibited, then restart and verify supervision.
Files Reviewed (1 file)
  • reference/cindy-project.md - 1 issue

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

Overview

Light pass over the live-service snapshot and deployment procedure at 2fa861d6d051be4a57b254a907eae45fd877339b. Both translated counterparts are present; their contents were skipped per REVIEW.md.

Severity Count
CRITICAL 0
WARNING 1
SUGGESTION 0
Issue Details (click to expand)

WARNING

File Line Issue
reference/cindy-project.md 90 The procedure creates maintenance.inhibit and stops the supervisor but never restores supervision on success or rollback, leaving supervised starts/recovery disabled. Document removal of the inhibit and restart/verification of the supervisor.
Files Reviewed (2 files)
  • docs/cindy-project.md - 0 issues
  • reference/cindy-project.md - 1 issue

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.

Fix these issues in Kilo Cloud


Reviewed by gpt-6-astra · Input: 33 · Output: 3K · Cached: 378.9K

Review guidance: REVIEW.md from base branch master

…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)
Comment thread reference/cindy-project.md Outdated
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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(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)
@anuzzolilli-oss
anuzzolilli-oss merged commit 3b62dd6 into master Nov 16, 2026
42 checks passed
@anuzzolilli-oss
anuzzolilli-oss deleted the 2026-11-16_cindy-project-docs-live-snapshot branch November 16, 2026 18:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Docs: live-proxy deployment snapshot and procedure are out of date after the 2026-11-14 master deployment

1 participant