Skip to content

Commit 8ddb046

Browse files
committed
docs(devlog): wp10 follow-up designs + campaign phase records
- 090 (windows program): transactional update with rollback — stage-to-side, verification manifest, swap protocol, failure-mode table, boot probe (#1942/#1849 remaining half, diff-level). - 051 (campaign): thought-signature credential scope (keyFor v4 + preferred discriminator) and the six-site emit-after-commit barrier design (#1926 remaining half, diff-level). - 010-050: campaign phase records (WP-V audit, wp6 redesigns, wp7 dispositions, wp9 sweep + docs drift, wp10 plan), all audit-reviewed.
1 parent 0da9e20 commit 8ddb046

6 files changed

Lines changed: 458 additions & 0 deletions

File tree

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# 090 — Transactional update with rollback (#1942 / #1849 remaining half)
2+
3+
Follow-up on the landed foundation: 010 argv fix, 020 wrapper killer, 030/031
4+
atomic replace + retry counters, d09c75299 missing-install wrapper guard.
5+
This doc is the diff-level design for the half that is NOT built: stage-to-side
6+
install, post-install verification, and rollback. No code in this doc's cycle;
7+
it is consumed by a later implementation work-phase (one PABCD cycle).
8+
9+
## Problem restatement
10+
11+
update/job.ts today: pre-flight registry integrity probe (job.ts:1783-1801) →
12+
npm install into the LIVE prefix → done. Failure after the old tree is removed
13+
leaves a file-less skeleton (#1849) with no recovery; nothing verifies the new
14+
tree before it becomes live (#1942). d09c75299 only stops the wrapper restart
15+
storm after the damage.
16+
17+
## Design: stage → verify → swap → rollback window
18+
19+
### D1. Stage-to-side layout
20+
21+
- New module: src/update/transactional-install.ts (est. ~250 lines).
22+
- Stage root: <prefix>/.ocx-staging/<version>/ — same volume as the live
23+
install so the swap is renameAtomicFile-eligible (030 foundation; cross-volume
24+
rename falls back to copy+fsync+rename per windows-atomic-replace.ts).
25+
- npm install --prefix <stage> ${PKG}@<version> runs against the stage, never
26+
the live tree. Live tree untouched until verification passes.
27+
- Disk-space pre-check: refuse staging below 2x package size.
28+
29+
### D2. Post-install verification manifest
30+
31+
- New file: src/update/install-manifest.ts. Verification rows:
32+
| artifact | check |
33+
| package.json | exists, parses, .version === target |
34+
| bin/ocx.mjs (+ platform launchers) | exists, non-empty, first line shebang/marker |
35+
| bundled Bun binary | exists, size > 10MB, spawn "--version" exit 0 |
36+
| node_modules sentinel deps | package.json of each direct dep exists |
37+
- Verification runs INSIDE the stage before any swap. Failure = delete stage,
38+
report, live tree never touched. This alone closes the #1849 empty-install
39+
class.
40+
41+
### D3. Swap protocol (the transactional core)
42+
43+
1. Move live tree → <prefix>/.ocx-backup/<oldversion>/ (same-volume rename;
44+
wrapper killer from 020 stops running wrappers first, guard from d09c75299
45+
keeps restarts from racing the window).
46+
2. Move stage → live (renameAtomicFile directory-level; on Windows retry class
47+
EBUSY/EPERM/EACCES via 031 counters, publisher id "update:swap").
48+
3. Re-run the D2 manifest against the LIVE path (paranoia re-verify).
49+
4. On success: delete backup after a grace period (next successful boot), not
50+
immediately — the running service that spawned the update may still hold
51+
the old cwd.
52+
5. On failure at any step: rollback = reverse rename backup → live; if that
53+
also fails (double fault), leave backup in place and write a recovery
54+
marker file the wrapper guard (service.ts:1549) can print, so the user has
55+
a one-line restore instruction instead of a dead install.
56+
57+
### D4. Failure-mode table
58+
59+
| fault | state | recovery |
60+
| stage install fails | live intact | delete stage, report |
61+
| verify fails | live intact | delete stage, report |
62+
| power loss during step 1 | live moved or partial | boot probe finds backup + no live → restore backup |
63+
| power loss during step 2 | backup intact, live missing | same boot probe path |
64+
| locked file during swap | retry class, bounded | 031 counters; exhaust → rollback |
65+
| double fault | backup present, live broken | recovery marker + manual one-liner |
66+
67+
- Boot probe: new startup check in src/service.ts (est. +30 lines) — if
68+
.ocx-backup exists and live manifest fails, auto-restore before serving.
69+
70+
### D5. Wiring
71+
72+
- src/update/job.ts: replace the direct npm-install block with
73+
transactionalInstall() (est. -40/+60 lines); keep the pre-flight probe.
74+
- CLI ocx update: same entry, shared module.
75+
- Config: no new options (transactional is the only mode).
76+
77+
## Accept criteria / test plan
78+
79+
- tests/update-transactional.test.ts: fixture prefix trees; fault injection
80+
per D4 row (mock renameAtomicFile failures, kill mid-swap via step hooks);
81+
assert live-tree invariant (live is always either old-complete or
82+
new-complete, never partial) across every injected fault.
83+
- tests/update-manifest.test.ts: each manifest row red/green.
84+
- Windows CI leg (060 gate) must run both suites; the platform-windows
85+
dispatch flake documented in the campaign (Log Guard suites) is unrelated
86+
but must be green-or-baselined before trusting the leg.
87+
- Issues #1942 and #1849 close only when the boot probe + swap land.
88+
Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# 020 — WP6: REDESIGN-SMALL #1748 (fake-IP outbound) + #1920 (Computer Use tool-result normalization)
2+
3+
Prior cycle's disposition (000 matrix): both REDESIGN-SMALL — fresh scoped branches,
4+
close originals with credit, close linked issues.
5+
6+
## Part 1 — #1748 outbound-only Clash fake-IP routing (branch codex/redesign-1748-fakeip)
7+
8+
Already-implemented WIP delta (carried over the WP-V stash, rebased onto 69650fac4):
9+
10+
- src/lib/destination-policy.ts: `resolvePublicAddresses` gains explicit
11+
`allowBenchmarkAddresses` opt-in. A HOSTNAME answer in 198.18.0.0/15 (IANA
12+
benchmark = Clash/Surge/Mihomo fake-IP DNS) is accepted without marking the
13+
destination private. Literal 198.18.x URLs still reject; mixed answers with
14+
RFC1918 still reject; image/Lab fetch (no opt-in) keeps rejecting — this is
15+
what avoids the SSRF widening the original PR had.
16+
- src/lib/provider-outbound.ts: passes `allowBenchmarkAddresses: proxyConfigured`
17+
— the opt-in arms ONLY when an outbound HTTP(S) proxy is configured, so the
18+
hostname rides the proxy CONNECT instead of pin-connecting to the fake IP.
19+
- tests: 5 new cases in tests/destination-policy-resolved.test.ts (opt-in accept,
20+
no-opt-in reject, mixed reject, literal reject, image-fetch reject) + proxy
21+
integration cases in tests/provider-outbound.test.ts.
22+
23+
Verify: bun test ./tests/destination-policy-resolved.test.ts ./tests/provider-outbound.test.ts
24+
+ tsc. PR to dev, close #1748 with credit.
25+
26+
## Part 2 — #1920 Computer Use / node_repl tool-result normalization (branch codex/redesign-1920-toolresult)
27+
28+
Original PR: 867 lines, 5 files, broad compaction layer applied only on the
29+
EXTERNAL replay text path. Disposition directive: "apply formatted.text at
30+
native toolResultPart + decode test" — the empty/error normalization must reach
31+
the NATIVE protobuf path (toolResultContentItems), which the original never
32+
touched, and the proof is a ConversationStep decode test.
33+
34+
Scoped design (new file src/adapters/cursor/tool-result-normalize.ts, ~60 lines):
35+
36+
- `normalizeCursorToolResultText(text, {toolName, toolNamespace, isError})`
37+
→ `{ text, isError }`:
38+
- blank/whitespace or "<empty>"-only exec wrapper output on node_repl /
39+
computer-use tools → actionable "[empty output: …verify application state
40+
with get_app_state]" + isError=true.
41+
- known unrecoverable runtime strings (SkyComputerUseError, "sky is not
42+
defined", "Identifier … has already been declared", "unsupported import in
43+
exec") → isError=true, append one-line recovery guidance.
44+
- all other text: unchanged (no screenshot stripping, no AXTree compaction —
45+
the native path already bounds images by real serialized size at
46+
toolCallStep, so the original's byte-budget machinery is unnecessary here).
47+
- Wire-in at protobuf-request.ts:
48+
- toolResultContentItems(): when parts is undefined (plain text result), run
49+
the normalizer before creating McpTextContent; when parts exist, normalize
50+
the JOINED text-only case (pure-text results) — image-bearing results pass
51+
through untouched.
52+
- toolResultToText() (external replay text path): reuse the same normalizer so
53+
both wire shapes agree.
54+
- isError propagation: toolResultPart() McpSuccess.isError picks up the
55+
normalized isError.
56+
- external replay sites that BYPASS toolResultToText (r2 audit): the
57+
externalModel branch of conversationTurns (~:645-650) builds
58+
"prefix + contentToText(message.content)" directly and takes its
59+
"[Tool Error]" prefix from raw message.isError; the root-prompt path (~:243)
60+
also prefixes from raw isError. Both must consume the normalizer's
61+
{ text, isError } — this is the exact cursor/grok-4.6 repro path of #1866.
62+
- Decode test (tests/cursor-toolresult-normalize.test.ts): build a
63+
ConversationStep via the real builder with an empty node_repl result,
64+
fromBinary-decode it, assert the McpToolResult content text carries the
65+
normalization marker and isError=true; plus unit rows for each failure state
66+
and a non-computer-use tool that stays byte-identical.
67+
68+
IN: the two branches above. OUT: screenshot stripping, AXTree compaction,
69+
request-builder budget markers (original PR scope — deferred with the close).
70+
71+
r2 audit notes folded in:
72+
- #1748 LOW: the benchmark opt-in arms on global proxyConfigured; if NO_PROXY
73+
excludes the provider host, Bun bypasses the proxy and direct-connects to the
74+
fake IP (non-routable benchmark space — not an SSRF widening, but the "rides
75+
the proxy" claim has this corner). Record as a code comment on the opt-in.
76+
- #1866 close comment MUST explicitly state the deferred half: oversized
77+
AX-tree/screenshot text summarization (compaction) is NOT included; only
78+
empty/error-state normalization ships. The native path bounds images (not
79+
text) by serialized size.
80+
81+
Close #1920 with credit + directive note; close #1866 when merged.
82+
83+
## Verifiers
84+
85+
- bun test ./tests/destination-policy-resolved.test.ts ./tests/provider-outbound.test.ts (part 1; reads both change targets)
86+
- bun test ./tests/cursor-toolresult-normalize.test.ts + bun test tests/cursor-*.test.ts glob (part 2)
87+
- bun run typecheck per branch; PR CI; lidge suite before merge.
Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# 030 — WP7: landed-redesign closeout + #1876 / #1842 disposition
2+
3+
## Part A — already-landed redesigns (bookkeeping only)
4+
5+
- #1932 (WHAM 401) → landed via #2021 (f2b507f83), original CLOSED already. No linked issue.
6+
- #1896 (functions-namespace) → landed via #2020 (5f2b93979), original CLOSED. Linked #1844 is a PR (merged), not an issue.
7+
- #1889 (x-goog-api-client) → landed via #2018 (ea16f8613), original CLOSED. Linked #1836 is a PR (closed), not an issue.
8+
- r4 audit confirmed: no OPEN issue references 1932/1896/1889 or the landing PRs.
9+
- Nothing to do beyond verification (done above via gh states).
10+
11+
## Part B — #1876 (async Windows snapshot collector, linked #1852 OPEN)
12+
13+
Matrix: REDESIGN-SMALL "rebase onto fail-closed snapshot API; keep async collector, 250ms TTL".
14+
Head 125156c3e is only 7 commits behind dev and scratch-merges CLEAN. Wibias
15+
CHANGES_REQUESTED exists — check whether it postdates the head.
16+
Decision rule (in order):
17+
1. Audit the head against the directive: does it build on the CURRENT fail-closed
18+
snapshot API (post-#1946/#1947 state), is the TTL guidance honored (matrix says
19+
250ms; PR body says 5s — resolve which is right against structure/03 and the
20+
review thread), is the CHANGES_REQUESTED stale?
21+
r4 resolution: BOTH TTLs are correct by design — 250ms is the unknown-state
22+
negative cache (CATALOG_STATE_UNKNOWN_TTL_MS, #1947 policy), 5s the positive
23+
advisory cache (CATALOG_STATE_TTL_MS); head 125156c3e adopts dev's machinery
24+
and all four fail-closed commits are its ancestors.
25+
2. HARD GATES before any #1876 merge (r4 HIGH): (a) the Wibias CHANGES_REQUESTED
26+
explicitly demands the full Windows suite on the resulting EXACT head —
27+
dispatch the platform-windows workflow (workflow_dispatch, full SHA) on the
28+
landed candidate and require green; (b) reviewDecision must clear via Wibias
29+
re-review or explicit dismissal with reason. Blocker-1 staleness alone does
30+
NOT clear the review. Only then: validate named suites + tsc and MERGE with
31+
credit; close #1852.
32+
3. If gaps are small → merge-with-fixup commits on a codex/land-1876 branch (same
33+
pattern as the land-* train), close original + #1852.
34+
4. If gaps are structural → close with a redesign directive comment (do NOT merge).
35+
36+
## Part C — #1842 (OAuth redaction, no linked issue)
37+
38+
Matrix: REDESIGN-SMALL "OAuth redaction; preserve typed identity errors".
39+
Head e298b2d80 is 308 commits behind but scratch-merges CLEAN (security-sensitive
40+
surfaces: auth-api, oauth, sidecars — MAINTAINERS security review applies).
41+
Decision rule: same ladder as Part B, with two extra gates:
42+
- the redaction must NOT swallow the typed identity errors that #1932's transient
43+
gate and the account-pool health machinery rely on (invalid_refresh_token,
44+
invalid_workspace_selected classification paths in auth-api.ts) — that is the
45+
exact "preserve typed identity errors" directive;
46+
r4 verification: gate PASSES on the scratch-merged tree — #1842's hunks
47+
(auth-api login-flow ~1791-2045, core.ts 2169/3809) have zero overlap with
48+
f2b507f83's classification hunks (@566-601, @723), and redaction rewrites
49+
outbound messages only, never body-code classification.
50+
- privacy:scan and the oauth/auth test suites must pass on the merged tree.
51+
- r4 MEDIUM: dev core.ts drifted 29 hunks since the merge-base; raw err.message
52+
still escapes at post-merge-base sites (core.ts ~1101/1104/1107, ~2131) the PR
53+
never saw. The fixup commit must either extend coverage to those sites or
54+
scope the landing-commit claim explicitly. r4 LOW: squash the no-op
55+
oauth-account-routes /api/oauth/status remnant in the fixup.
56+
57+
## Verifiers
58+
59+
- Per-PR scratch worktree on lidge or local: bun test <named suites> + tsc.
60+
- #1876 additionally requires the platform-windows workflow_dispatch run green on
61+
the exact landed SHA (lidge is not a Windows leg and does not discharge it).
62+
- gh pr checks after any push; lidge full suite before wp11 closeout (not per-merge).
63+
64+
IN: dispositions for 1876/1842 + issue closes. OUT: new feature work beyond fixups.
65+
66+
## Outcome (wp7 close)
67+
68+
- Part A: verified terminal (1932/1896/1889 CLOSED, landings on dev, no open issues).
69+
- Part C #1842: 7-commit redesign rebased to codex/land-1842-v2, independent
70+
security review SECURITY: APPROVE, PR #2043 ALL GREEN, merged e446607c8;
71+
original #1842 closed with credit. Canonical dev push CI green on e446607c8
72+
(run 32147799485).
73+
- Part B #1876: NEEDS_HUMAN — candidate validated (rebased, fail-closed
74+
ancestors, TTLs honored) and windows dispatch run 32145700019 failed ONLY in
75+
suites that fail identically on dev's own control dispatch 32147924436
76+
(Log Guard / CodeRabbit-protection / WS-relay families; pre-existing dev
77+
Windows-leg redness, zero app-server-process failures). Merge held for the
78+
standing Wibias CHANGES_REQUESTED re-review/dismissal; evidence posted on the
79+
PR. #1852 stays open until #1876 lands.
80+
- Pre-existing (out of campaign scope, recorded): the platform-windows
81+
workflow_dispatch leg is red on dev itself (Log Guard suites) since at least
82+
366a56324 (8/16). Deserves its own unit.
Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# 040 — WP9: resolved-issue sweep + structure/04 drift disposition
2+
3+
## Part 1 — structure/04 drift line
4+
5+
Recorded finding (devlog/_fin/260818_release_readiness_2260/010:50): "structure/04
6+
claims chat passthrough emits service_tier by default — docs drift, needs a line fix."
7+
8+
Current-state verdict (CORRECTED per r6 audit): no historical revision of
9+
structure/04 ever said "emits by default" verbatim, and B1 did NOT fix the
10+
drift — B1 INTRODUCED it. The release-readiness auditor recorded the finding
11+
against the post-B1 doc; the finding IS the B1-added clause at structure/04:663
12+
("canonical Fast follows the resolved Fast policy and does not require
13+
chatServiceTier"), which sits in the NATIVE chat passthrough paragraph.
14+
Code: buildOpenAIChatPassthroughRequest (openai-chat.ts:121) forwards
15+
service_tier only when provider.chatServiceTier is set.
16+
17+
r6 verified verdict (F2, HIGH): structure/04:663 is FALSE for the native path.
18+
A classified Fast-capable route CAN reach the native passthrough
19+
(isNativeChatRouteEligible excludes only combo/policy/auth/store/hosted-tools,
20+
chat-native.ts:54-72), and on that path NO canonical Fast injection happens:
21+
no decideTier/tierDecision/canonicalToWire/fastMode wiring exists in
22+
chat-native.ts — tier resolution lives only in the Responses pipeline
23+
(core.ts:1206) feeding adapter buildRequest (openai-chat.ts:1304-1313), which
24+
the passthrough bypasses. Caller canonical "fast"/"priority" is DROPPED without
25+
chatServiceTier:true and forwarded RAW (never wire-mapped) with it; fastMode
26+
injects nothing. The sentence is true only for the bridged
27+
Chat->Responses->Chat path. B fix: rewrite the :663 clause to scope canonical
28+
Fast policy to the bridged path and state the native passthrough's actual
29+
contract (chatServiceTier-gated raw forwarding, no injection). Docs-only
30+
commit to dev.
31+
32+
## Part 2 — resolved-issue sweep
33+
34+
Sweep the ~50 open issues for ones already resolved by merges on dev
35+
(campaign rule: PRs target dev, no auto-close). Method: 2 parallel read-only
36+
subagent lanes over the open-issue list, each issue judged against origin/dev
37+
code with commit evidence; close only issues whose fix is verifiably on dev
38+
(cite SHA + file:line), comment-with-evidence per close. Known candidates from
39+
the campaign: #1938-class already handled; check #1939 (ownership sync error),
40+
#1924 (OpenCode Go quota gate), #1927 (MiMo vision bypass), #1866 (closed in
41+
wp6), #1852 (stays open pending #1876), plus anything the lanes find.
42+
Judgment rule: ambiguous = leave open with a status comment only if evidence is
43+
strong; never close on inference.
44+
45+
## Verifiers
46+
47+
- Docs commit: docs-only diff (git show --stat), pushed to dev directly
48+
(docs-only, campaign pre-approval) or via PR if any src/ file is touched.
49+
- Issue closes: gh issue view state transitions with evidence comments.
50+
- bun run typecheck only if any src change (not expected).
51+
52+
IN: doc line fix + evidence-based issue closes. OUT: any code behavior change.

0 commit comments

Comments
 (0)